qwen-code/packages/managed-agent-server/README.md

Qwen Managed Agent Server

The application lives in packages/managed-agent-server, alongside the Java SDK. It builds as one Maven reactor with thirteen production modules and a verification module. The executable remains one Spring Boot service. Install the Java SDK before building the reactor; see Runtime Broker internals.

Every configuration property, with its environment variable and default, is listed in the configuration reference. It is generated from this module's configuration metadata and the descriptions in configuration-descriptions.json; a new property needs a description there, and a settings class declared outside ManagedAgentProperties needs @NestedConfigurationProperty on its field, or the metadata leaves it out.

Standalone Spring Boot control plane for the Qwen Code Hosted Harness. It has no DataWorks dependency. The default loopback listen address keeps the header-asserted tenant model: a trusted upstream sends X-Qwen-Tenant-Id and the server uses that value on every database read and write. Leaving loopback requires authentication: set QWEN_MANAGED_AGENT_SERVER_ADDRESS and configure signed mode (QWEN_MANAGED_AGENT_AUTH_MODE=signed with QWEN_MANAGED_AGENT_AUTH_SIGNING_KEY) so the broker verifies each request's HMAC signature itself, or put an authenticated gateway in front. With the default auto mode a non-loopback address refuses to start. See "Broker authentication and writer credentials" below.

设计说明：English | 简体中文

Local embedded profile

The installed CLI starts local Managed mode with qwen serve --managed --open. It checks local Java 21, downloads a matching server JAR on first use, and reuses the verified versioned cache on subsequent starts. An explicitly preinstalled runtime can instead bundle Java 21 for offline use. It needs no MySQL, Docker, Maven or systemd. The ordinary server profile keeps its existing MySQL defaults. Design: English | 简体中文.

The central-release Maven profile attaches sources, Javadoc and GPG signatures for server publication, without attaching the auxiliary operator JARs. The executable server JAR uses the exec classifier. Ordinary builds keep the existing attachments and do not activate Central publishing. The protected Release Managed server runtime workflow sets the artifact version from an existing CLI release tag and publishes identical JAR bytes and checksums to GitHub Release assets and the official OSS mirror after full SDK/server verification. Distribution does not require Central credentials, GPG signing or a successful Central publication. Signed Maven publication remains an independent operation using the existing profile. The CLI's first-use download uses OSS/GitHub and requires no Maven installation. See the release procedure and its Chinese version.

The launcher selects the managed-local Spring profile and supplies an existing canonical, owner-only QWEN_MANAGED_AGENT_LOCAL_DATA_DIRECTORY. The directory and its private subdirectories must be owned by the current user with mode 0700; symlinks, noncanonical paths and data-directory paths containing ; are refused. The profile creates these directories:

Path	Persistent contents
database/managed.mv.db	Embedded H2 database with the canonical Managed schema
runtime/	Durable local Runtime worker state
workspaces/	Application-owned Workspace storage roots and their original identity markers
legacy/	Private fallback cwd for unbound Sessions

H2 uses MySQL compatibility mode, lowercase catalog metadata, DB_CLOSE_ON_EXIT=FALSE and WRITE_DELAY=0. Its embedded file lock and the launcher's data-directory lock admit one local control plane. The connection pool retains an idle connection to keep that file lock held. No H2 TCP server, AUTO_SERVER, or Web console is enabled. Database URL overrides are refused; the profile keeps the existing Flyway admission and structure validation and never repairs foreign, partial, history-only or unsupported catalogs.

The launcher supplies the existing Harness URL/token/digest, Session Store base URL and binding key, Broker token and credential encryption key, Node executable and worker entry. QWEN_MANAGED_AGENT_WORKSPACE_ID is the first 16 hexadecimal characters of the SHA-256 of the canonical legacy/ path; it identifies the fallback Runtime and Session Store, independently of the bound Workspace IDs created through the API. Public API requests use signed authentication; the front door retains the signing key and fixed tenant/actor identity. Java, Harness and Broker listeners must stay on loopback. Readiness is GET /actuator/health/readiness, which includes the database and Spring's readiness state. The public front door opens after readiness and the authenticated Harness capability probe succeed.

The profile enables verified, durable local-process workers, file tools and Shell with default approval mode. The launcher creates the first Workspace through the existing signed WebShell creation API using a persistent idempotency key. It creates a new application-owned Workspace; the shell's current Git checkout is not copied, symlinked or imported. The existing Workspace ownership and grant checks still apply. Tool publication remains disabled unless separately configured; ordinary persisted tool receipts do not require an object store.

Keep the database, Runtime state, Workspace roots, credentials and worker QWEN_HOME/file-history together across restarts. Credentials never rotate merely because the application restarts. The local profile defaults trusted whole-host reboot recovery to false; macOS supports same-boot worker adoption only. Linux operators may explicitly enable QWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERY under its existing trusted-host contract. Missing or conflicting physical identity markers remain closed to execution; startup does not re-register or repair them.

Maven modules and Java packages

Module	Responsibility	Internal dependencies
contracts	Service and repository interfaces, shared values, settings views and protocol rules	None
control-plane	Session, Workspace, catalog, lifecycle, Channel, automation and extension orchestration	contracts
runtime-broker	Runtime execution, routing, binding, leases, cancellation and recovery coordination	contracts
persistence	JDBC/memory repositories, schema and atomic database operations	contracts
runtime-http	Shared Runtime HTTP transport	contracts
runtime-host	Native identity, bounded host processes and private state files	contracts
runtime-local	Local process provider and factory	contracts, runtime-http, runtime-host
runtime-external	External scratch/workspace providers and factory	contracts, runtime-http
runtime-kubernetes	Kubernetes resident/CSI provider and maintenance capability	contracts, runtime-http
runtime-ssh	SSH provider, connection manager and factory	contracts, runtime-http, runtime-host
runtime-static	Pre-attested static Runtime provider and factory	contracts
adapters	Harness SDK, OSS, MQ, Git and filesystem operations	contracts, runtime-http, runtime-host
server	HTTP endpoints, Spring assembly, startup and maintenance entry points	Shared modules; optional runtime provider JARs
verification	Unit, integration, architecture and packaging tests; not published	All thirteen production modules

The parent coordinate is com.alibaba:qwen-managed-agent-parent. All modules share its version; the server keeps com.alibaba:qwen-managed-agent-server. Each production Java package belongs to one module. Orchestration and persistence collaborate through contracts; provider implementations share the narrow HTTP and host-I/O modules. The server compiles without any backend implementation classes. Backend modules do not depend on each other; routing stays in runtime-broker. SQL helpers sharing a connection remain in managedagent.persistence or runtimebroker.persistence. The Broker service lives in runtimebroker.service; physical clients and providers live in their owning adapter or provider modules. Maintenance applications retain their separate component scan.

Only server creates executable JARs. Its ordinary library JAR and the existing exec and maintenance classifiers are under server/target/. Dependencies are ordinary JARs nested under BOOT-INF/lib in executable artifacts. Install the reactor before using the server POM directly or embedding the library in another Maven project:

mvn -pl server -am -DskipTests install
mvn -f server/pom.xml spring-boot:run

Embedding imports ManagedAgentConfiguration; internal callbacks additionally import ManagedAgentInternalConfiguration. The standalone application also enables the public web configuration. Add the ordinary server artifact as the dependency; Maven resolves the shared modules transitively. All five backend providers are optional runtime dependencies: an embedding host must explicitly add its chosen com.alibaba:qwen-managed-agent-runtime-{local,ssh,kubernetes,external,static} coordinates at the same version. Maven still resolves all five when building the standalone server, but does not propagate them to library consumers. The verification module is never installed or deployed. The standalone application YAML is excluded from the ordinary library JAR.

Runtime factories are discovered through META-INF/services/com.alibaba.qwen.code.runtimebroker.spi.RuntimeProviderFactory. The default executable and operator artifacts include all five backend JARs. A library host can omit all backends when its Broker is disabled, or select a single provider. runtime-broker.provisioner supports local-process, ssh-process, kubernetes-workspace, external-scratch, external-workspace and static; existing built-in settings and persisted identities are unchanged. Only the selected factory validates its configuration and creates resources. Missing providers and duplicate kinds fail explicitly.

Backend selection for embedding is ordinary Maven dependency selection. For example, a host using Kubernetes adds qwen-managed-agent-server and qwen-managed-agent-runtime-kubernetes at the same version; no exclusions for Local, SSH, External or Static are needed. A host using Local+SSH adds both corresponding backend artifacts. Packaged availability and enabled configuration are separate: only the configured backend is initialized, with Local+SSH as the supported routing combination. The default standalone and operator artifacts continue to contain every backend. Selective standalone builds and archives are outside this change.

To add a compatible provider, compile its factory against qwen-managed-agent-contracts, implement RuntimeProviderFactory, register its fully qualified class name in that service file, and add the JAR to the host application's runtime classpath. Select its exact kind with qwen.managed-agent.runtime-broker.provisioner; bind additional string settings under qwen.managed-agent.runtime-broker.provider-options. For example, a provider that reads getProviderOptions().get("endpoint") can receive qwen.managed-agent.runtime-broker.provider-options.endpoint=https://provider.example. Factories must have inert constructors; validation is configuration-only, preflight may perform read-only diagnostics, and creation transfers the provider's close ownership to the Broker. A remote provider leaves usesLocalWorkspace() false. Plugins execute as trusted application code and must honor the existing identity, fencing and Runtime HTTP contracts. This supports classpath selection at startup; existing warmup behavior remains, with no live JAR reload or automatic download.

The provider boundaries and acceptance criteria are in the backend module design.

Server configuration accessors use Lombok through the server POM's annotation processor; enable annotation processing when compiling through an IDE. Keep accessors with normalization, copying or fallback logic explicit. Lombok is excluded from executable and maintenance JARs and is not a runtime dependency of embedding applications.

See the complete Maven boundary design: English | 简体中文.

Integration status

The Hosted path supports durable no-tool Sessions and private Workspace tool profiles. G0 adds opt-in public creation with an initial Workspace Turn (file tools, or mandatory-approval foreground Shell under the Shell opt-in) through the production Broker. This is not complete Workspace lifecycle, in-flight recovery or distributed provisioning support. See the G0 section below for its exact deployment and admission boundary, and the historical review corrections for the original split's merge gates; earlier preview timing and recovery results below do not establish completion of later slices.

API contract

contracts/src/main/resources/openapi/managed-agent-public-api.openapi.json is the single source for the public and WebShell routes. ManagedAgentApiContractTest compares the mapped routes, the ApiModels records and real responses with it; verification/src/test/resources/openapi/contract-known-gaps.txt lists the differences that a later slice still has to close; none remain after D4. The WebShell client types are generated from the same file by npm run generate:managed-agent-api in packages/web-shell. The test-tree SurfaceRegistry names every mounted route, internal ones included, with its admission rule class; SurfaceRegistryGateTest fails any mounted route the registry lacks, so a new public or WebShell route needs both a spec operation and a registry entry (actor-roles design, D5). Sessions created for the built-in qwen-code agent record the agent revision from QWEN_MANAGED_AGENT_REVISION (default 1); a Session pinned to a stored definition records the revision it resolved at admission. POST /v1/agents, GET /v1/agents/{id} and POST /v1/agents/{id} store tenant-scoped, immutable AgentDefinition revisions; a Session pinned to one executes that stored revision (see "Stored agent execution" below). Every response carries X-Request-Id, which error envelopes repeat as request_id and the logs print. Events keep the schema and projection versions they were accepted with. They keep their Item and Part identity too, except after Harness recovery retracts output: the retracted deltas lose their text and identity, later deltas may name other Parts, and a stream.reconciled event announces it. A client that sees one reloads the Items and resumes after their snapshot_through_sequence. A cursor below a Session's replay floor gets 409 cursor_expired from the JSON event query and one agent.session.resync_required frame from either stream whenever the cursor is below the durable floor. Rebuilding projections or pruning all retained events never resets that floor. Message queries page directly over ma_message; a scoped opaque cursor fixes the membership range and complete ordering position while message bodies and statuses remain live. Projection rebuild invalidates the cursor. The default transcript returns recent Items and the actual materialized coverage for SSE handoff, without reading the whole history or unmaterialized event tail. Export reads forward within its initial membership range and does not promise a fixed content version. Its retained snapshotThroughSequence field names that fixed range; transcript coverage names the current read watermark. A projection behind the replay floor or an initial export behind committed events returns retryable message_projection_pending. The historical reload_snapshot resync action now means reload the live message view. See the removal design (简体中文). GET /v1/agents/sessions/{id}/turns lists a Session's Turns newest first with an opaque cursor, and GET /v1/agents/sessions/{id}/turns/{turnId} reads one. Design: English | 简体中文; Session query: English | 简体中文; Event replay: English | 简体中文; Durable lifecycle: English | 简体中文; Turn queries: English | 简体中文; Actions (Hosted permission approvals): English | 简体中文; AgentDefinition revisions: English | 简体中文

On-demand tool details

Managed ReadFile and Shell cards read saved arguments, output and errors only when expanded, through /api/agent/web-shell/v1/tool-details/get, without a feature switch. Each request requires a trusted actor and current Session/Workspace read access, rechecked before returning. It does not require Artifact publication or download permissions and never executes a tool or starts a Harness.

Lifecycle events remain metadata-only. Existing retained private results can be read without backfilling public events. Allowlisted input is limited to 4 KiB; text is limited to 8 KiB and 200 lines, with truncation reported. Closed cards do not fetch details. Reads stay inside the saved Session/Workspace and have a bounded history budget. Saved version-1 Shell display records also supply structured execution details to the shared daemon card. Their text fields share a separate 8 KiB/200-line budget, and directory/output-file paths share an 8 KiB budget. Unsupported or malformed structures retain the legacy text fallback; private fields are excluded. See the complete design: English | 简体中文.

Tool publication storage

Tool publication depends on ToolPublicationObjectStore; Aliyun OSS is its default implementation. Publication remains disabled unless qwen.managed-agent.tool-publication.enabled=true. To use another backend, register one application @Bean returning ToolPublicationObjectStore from a configuration imported into the Spring server. The default OSS auto-configuration then backs off, and no OSS endpoint, region, bucket or credentials are needed. Common publication service URL, capacities and verification deadlines remain required. Without a custom store, existing OSS configuration and client lifecycle are unchanged.

Implement atomic create without overwrite, guarded reads, idempotent physical deletion and validateConfiguration() for private, durable, immutable storage. Throw ToolPublicationStorageException with ACCESS_DENIED for definite storage denial or FAILURE for other backend failures, preserving the original cause. Even with scheduled GC disabled, failed-publication cleanup requires deletion. Do not automatically replay completed writes or a returned stream. All server instances sharing a SQL catalog must use the same byte namespace: replacing the bean does not migrate retained objects or enable fallback to another backend.

The extension applies to the Spring server. Standalone WorkspaceRecoveryMain and WorkspaceCsiWorkerAckMain still construct their documented OSS/inline storage directly; custom-backend deployments must integrate the same backend into their maintenance tooling. No additional production backend is included. Design: English | 简体中文.

Managed tool results (O3)

O3 publishes durable Hosted foreground Shell outcomes to Items, events and Managed WebShell. Downloads read immutable stdout/stderr after the writer is sealed, without reviving a Harness. The API requires a trusted actor and a current Workspace read grant, checked at request admission and then once per read-revalidation-interval while a download is in flight; a tenant header alone cannot authorize it.

O3 requires O2 publication to be configured, including qwen.managed-agent.tool-publication.verification-bytes-per-second and qwen.managed-agent.tool-publication.max-verification-timeout. These required O2 verification settings are separate from the O3 content-read timeout, artifacts.read-timeout.

The O3 settings use the qwen.managed-agent.artifacts prefix; the configuration reference lists each with its default and limits.

A product can replace ManagedArtifactPolicy for narrower publication or actor rules. Published previews persist in shared events. Policy changes do not automatically reproject historical results; content requests use the current read policy at admission and once per revalidation window thereafter. Configure the policy before enabling projection.

qwen.managed-agent.events.read-grant-recheck-interval (default 5s) bounds how often a live event stream re-checks the Workspace read grant; PT0S restores the per-event check. Tool-publication authorization always uses the session journal head's validated activation columns. Missing or inconsistent head proofs refuse publication. Original reads are capped at 1 MiB per Range request; full downloads use bounded segment buffers and stream with backpressure. Deployments must retain O2 roots and validate real OSS and slow-reader limits before enabling this feature. O3 does not enable public Shell execution or garbage collection.

Design: English | 简体中文; revalidation window: English | 简体中文.

Asynchronous tool publication verification

Enable qwen.managed-agent.tool-publication.async-verification-enabled (default false) to use asynchronous admission. verification-concurrency defaults to 2 and controls the dedicated verifier pool, independently of retention and GC.

Clients that support asynchronous verification send X-Qwen-Tool-Publication-Async: 1 and poll the operation status after HTTP 202. Synchronous responses remain supported when asynchronous verification is disabled or the request does not opt in. A mode is saved when each operation is created, so retries do not change it. FAILED carries only a safe error: {status, code} and must be handled as a terminal error, outside network retry handling. The adapter keeps awaiting verified success before completing publish, seal, prefix, or finish.

For rollback, disable new async admission and leave the verifier and head authorization running until accepted work drains. Do not downgrade the server while pending async operations still need verification. Historical async success replay returns the prior receipt; actual reads and final integrity checks still validate current storage bytes.

Design and client migration contract: English | 简体中文.

Experimental reference distribution

The independent Hosted Java reference distribution packages the runnable server, operator-recovery entry point, embedded Broker component, a configuration template, systemd unit templates, a credential bootstrap, a phased upgrade command for the systemd layout, provenance manifest, checksums, and deployment/upgrade instructions. Pull requests and manual dry runs build and boot the same Linux archive; only a protected-main production dispatch publishes an immutable prerelease. See Managed Agent reference deployment and the distribution design. The bundled launcher also supports --check, a read-only preflight for configuration, the compatibility of a single configured Harness, ports, leftover Runtime workers and database grants; add --online while the server runs. When the database check succeeds, the output includes a capacity line with grouped counts from ma_runtime_binding, ma_runtime_session and ma_operation. These are durable logical records for capacity triage; they are not a count of physical worker processes or memory usage. The line explicitly reports physical processes and memory as unknown, and does not infer idle work or reclaim anything. If the database check fails, capacity remains skipped.

Prerequisites

• Java 21
• Maven 3.8.9+ (the SpotBugs gate's plugin declares that floor)
• MySQL 8

MySQL is the supported database family; full integration CI uses MySQL 8.4. MariaDB no longer has a CI lane or an ongoing compatibility guarantee. Existing dialect handling remains in place; this change does not reject MariaDB solely by product name or introduce a catalog migration.

MySQL and MariaDB require STRICT_TRANS_TABLES or STRICT_ALL_TABLES in each application connection's session sql_mode. Schema admission and validation reject non-strict connections before schema writes. The embedded default Managed pool adds STRICT_TRANS_TABLES when creating every physical connection, preserving the other session modes. A non-strict global default is accepted. Strict mode prevents ordinary writes to unsigned counters from silently clamping negative values to zero; IGNORE writes can downgrade these errors to warnings. Standalone, maintenance and custom DataSource callers must configure every application connection to retain strict mode throughout operation; a startup check does not police later administrative or connection-mode changes. The application does not change the server's global SQL mode. MariaDB CHECK enforcement still requires both global and session settings to be enabled.

Run the packaged CLI with qwen serve --profile hosted-harness as a separate process (the credentialed launch is spelled out in the Full WebShell dual-path development entry below). It supports durable no-tool Sessions and the opt-in Workspace file Turns described in the G0 section below.

Install the Java SDK before building this module:

mvn -f ../sdk-java/qwencode/pom.xml -DskipTests -Dgpg.skip=true install

Configure and start the server:

export SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/qwen_managed_agent'
export SPRING_DATASOURCE_USERNAME='qwen'
export SPRING_DATASOURCE_PASSWORD='replace-me'
export QWEN_MANAGED_AGENT_HARNESS_ENABLED='true'
export QWEN_MANAGED_AGENT_HARNESS_BASE_URL='http://127.0.0.1:4170'
export QWEN_MANAGED_AGENT_HARNESS_TOKEN='replace-me'
export QWEN_MANAGED_AGENT_CAPABILITY_DIGEST='sha256:replace-with-64-hex-characters'
export QWEN_MANAGED_AGENT_WORKSPACE_ID='local-dev-workspace'

mvn -pl server -am -DskipTests install
mvn -f server/pom.xml spring-boot:run

Instead of the token and digest, QWEN_MANAGED_AGENT_HARNESS_CREDENTIALS_FILE can name the Harness's own environment file. While the Harness is enabled, the server then reads QWEN_SERVER_TOKEN and QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST from it, and QWEN_MANAGED_RUNTIME_BROKER_TOKEN when the file sets it, into its configuration, never into its process environment. It refuses to start when a direct QWEN_MANAGED_AGENT_HARNESS_TOKEN or QWEN_MANAGED_AGENT_CAPABILITY_DIGEST is also set, or a direct QWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKEN beside a file Broker token. The file sets the Harness's QWEN_MANAGED_RUNTIME_BROKER_URL and QWEN_MANAGED_RUNTIME_BROKER_TOKEN together or neither; a file with only one of them, or with either one empty, refuses startup. Write each of these keys as KEY=value on one line, with no whitespace around the = and only letters, digits and ._:/+=- in the value (the Broker URL may also use [ and ] to bracket an IPv6 literal, as in http://[::1]:4182), and start comments with #. The server refuses, by file and line, any line it might read differently from systemd or a shell, such as a continuation, a carriage return from CRLF line endings, a ; comment, an unterminated quote or text after a closing quote.

Create a Session and read its events as in Run a first Session; the requests are the same against this development server. The Session examples below use the same default tenant.

The returned id is an RFC UUID and is the canonical identity used by the public API, Hosted Harness transcript, and Runtime Broker. The server does not maintain a separate public-to-Harness Session mapping.

Public Session lifecycle

Close, archive and delete are durable ma_operation execution units. Each answers 202 with a command operation that GET /v1/agents/sessions/{id}/operations/{operationId} reads back, also after a delete; the WebShell adapter offers the same routes. The public control plane owns lifecycle state and tenant/idempotency checks, while the Hosted Harness remains the private title authority and the Runtime Broker owns execution bindings.

Turn input and cancellation are recorded in the same table as submit_input and cancel operations. Each is saved with its command, the same route reads it back, and a retry under the key resolves to it. The Turn dispatcher stays their only deliverer, and the Turn decides their outcome. An input completes once a Harness admits its Turn. A cancel completes once its Turn is cancelled, and fails with turn_already_settled if the Turn ended another way. Neither blocks a lifecycle operation; an active Turn still does. Admission responses do not carry the operation id yet. See the Turn command operation design.

curl -sS -X PATCH \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID \
  -H 'Content-Type: application/json' \
  -H 'X-Qwen-Tenant-Id: default' \
  -H 'Idempotency-Key: rename-1' \
  -d '{"title":"investigate checkout failure"}'

curl -sS -X POST \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID/close \
  -H 'X-Qwen-Tenant-Id: default' \
  -H 'Idempotency-Key: close-1'

curl -sS \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID/operations/$OPERATION_ID \
  -H 'X-Qwen-Tenant-Id: default'

curl -sS -X POST \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID/archive \
  -H 'X-Qwen-Tenant-Id: default' \
  -H 'Idempotency-Key: archive-1'

curl -sS -X POST \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID/unarchive \
  -H 'X-Qwen-Tenant-Id: default' \
  -H 'Idempotency-Key: unarchive-1'

curl -sS -X DELETE \
  http://127.0.0.1:8080/v1/agents/sessions/$SESSION_ID \
  -H 'X-Qwen-Tenant-Id: default' \
  -H 'Idempotency-Key: delete-1'

Close and delete reject an active Turn and seal input as soon as they are admitted. A background worker then closes the Hosted Harness Session, waits until no Harness holds its journal writer under an unexpired lease (the holding Harness seals it when closing), drains the Runtime binding (fenced by the persisted Session status the Broker checks on the warm admission resolve for an unbound Session, so the fence survives restarts; an in-process flag is kept only for a Session row that has vanished) and completes the operation; a failed attempt is retried with the dispatch backoff until it succeeds, so a 202 never means that tools stopped (a Harness whose capability digest no longer matches retries the same way, logged with the permanent reason — nothing may complete honestly before an operator realigns the versions, because a confirmation requires the Harness's own acknowledgement). When the Hosted Harness restarts, a live control plane adopts the new process generation: the connector renegotiates once instead of failing every bound Session, pending Turns re-attach through the takeover load as their retries come due, and the Session's bound boot ID moves to the new generation without a Java restart. A Turn parked in a supported state continues on the replacement (G3 Step 3). In a Session without Hooks or MCP, an unfinished model round reissues its saved request and retracts the dead owner's published prefix, and a requested native-file approval keeps its Action and deadline; a committed terminal is projected once. Step 3 neither reissues a model round nor resumes an approval in a Session with Hooks or MCP, and no gate covers how such a parked Turn ends. A takeover load that can never continue (an in-flight Shell call, an unfinished prefix continuation, a saved request that is oversized or carries image payloads, or other evidence a replacement cannot drive) ends the Turn as managed_runtime_recovery_blocked with a typed reason instead of retrying forever. The Session row and its generation binding survive that decline, but the declined Turn's input stays unsettled in the journal, so the Session cannot admit a further Turn — close it and start a new Session. See "Hosted recovery scope" below for what the first release covers. A Harness whose journal writes stopped after a failed commit answers every close with 503 until it restarts. A delete of a closed or archived Session needs no Harness. Archive accepts only a closed Session and completes at once; unarchive restores it to closed. Rename waits for the Harness to durably commit session_metadata. When a rename failure is recorded, its PENDING command becomes FAILED while retaining its receipt and request digest. The same key retries the same content with the replay flag set; changed content or a different Session conflicts. A successful concurrent request can still complete the receipt, and a failing sibling cannot overwrite that completed outcome. It cannot complete a retired receipt once a later rename has completed either: that sibling answers 409 session_mutation_superseded and the newer public SQL title stays. The latest title attempt is now a durable delivery with a monotonically increasing per-Session revision. The Harness checks this revision inside its journal commit and uses a stable command identity per attempt, so a late older versioned write cannot undo a newer versioned title and a lost reply can be replayed without another write. A failed same-key request retried after a later rename receives a new revision and can still win. Pending same-key retries keep their original revision. A recovery worker redelivers the latest unfinished title and completes its public receipt; older completion attempts cannot affect the newer delivery. Both inline requests and recovery workers claim before sending; failure cleanup requires the current unexpired owner. Fresh disabled or unsupported Harness requests are refused before admission. Workspace migration also refuses unfinished title delivery even when the public command is FAILED. Close, archive, delete and cwd changes wait for this delivery to settle, including when its public command is FAILED, so sealing cannot strand a title already accepted by the Harness. A delivery whose submission went unanswered is the exception (D7-2): it parks recovery_blocked, is never sent again, and retires its public receipt, so it holds neither later titles nor the lifecycle; the operation reconciler completes it, and shows the title, once the Session journal holds its revision's commit, and fails it once a deleted Session's complete journal lacks it (design). The Harness must advertise title protocol version 1 before the SDK sends a versioned title. Plain private SDK title writes remain supported and preserve the watermark. See the concurrency design. If the command store is unavailable during cleanup, the original API failure is preserved and the same key can resume its receipt when storage returns. Only an in-flight lifecycle change blocks another one. A retry with the same key from the same actor returns the original operation once it has completed.

Harness attachment uses strict create/load semantics: create returns 409 for an existing private Session authority, while load returns 404 for a missing authority and never initializes one. The Java connector attempts strict create for a new binding and loads on conflict or uncertain creation outcome. A known existing binding only loads. The Java connector caches an attachment per (tenantId, sessionId), so one tenant's cached reference is never handed to another by the connector. The Harness itself keys its in-memory Session by sessionId alone and does not compare the presented tenant, Store endpoint or workspace on attach; the only attach-time identity fence is the Harness writer generation, so tenant isolation on attach is the caller's responsibility in this slice. A presented Harness writer generation is checked: an attach whose writerId is not this process's boot ID fails closed with 409 hosted_harness_generation_mismatch — the restart-generation failure described above. That managed_session_store_conflict fence is target design for the integration slice, not shipped behavior.

Delete writes a public tombstone: get and list stop returning the Session, while its operations stay readable. Completed deletion permanently marks an existing private journal DELETED, clears its writer and recovery references, and fences new writes and recovery. Close and archive keep output pinned. The deletion request records the tombstone; output collection stays disabled by default and requires the retention deployment gates. With both qwen.managed-agent.tool-publication.enabled and qwen.managed-agent.tool-publication.gc-enabled true, a typed SESSION_RESOURCE_GC operation in ma_operation releases retired journal, message, record, native journal snapshot and artifact owners and their ma_resource_ref references in bounded transactions after the deletion grace. Unreferenced PUBLISHED or REFERENCED immutable MYSQL_INLINE bodies in ma_resource are then byte-dropped, keeping their identities with state COLLECTED. Capture objects follow a separate CAPTURE_GC operation: it persists deletion intent before physical deletion and retains its claim generation and cursor until the outcome is settled. Live readers, recovery protection and unresolved object writes block collection. Session/head tombstones and event-stream tail and retention-floor counters remain. Unreferenced bodies of active Sessions remain retained until Session retirement, except released public message bodies that the reader-aware projection collector can reclaim. Reads of the retired Session stay fenced with tool_output_session_retired exactly as before; a workspace-recovery read that physically reaches a collected byte copy fails the named check resource_collected instead of the generic resource_layout_unsupported or resource_corrupt verdict a pre-V65 broker produces.

This revision starts with a new empty database. Existing development or application databases keep their historical data under the old binary; the new service refuses legacy catalogs before running its baseline. Session identities and public URLs remain stable within their own environment.

The public listener intentionally ignores end-user Authorization. The optional Runtime Broker listener still requires a separate machine bearer and must remain private.

Private Managed Session store

The shared fresh baseline creates the private Managed Session head, journal and resource tables. The internal routes under /internal/managed-session-store/v1/** provide database-time writer leases and generations, head compare-and-set, idempotent transaction receipts, exact JSONL transaction bytes, paged restore reads, atomic checkpoint-pointer advancement, and transactional resources up to 64 KiB. Callers must provide the trusted tenant header and a writer credential in X-Qwen-Managed-Writer-Token; only its SHA-256 is persisted. Without QWEN_MANAGED_AGENT_SESSION_STORE_BINDING_KEY the credential is a fresh Base64URL secret the caller mints (first writer wins); with a binding key it must be the broker-issued HMAC over the Session scope and self-minted secrets are rejected. Restore, transaction-page, and resource reads require the same current, unexpired writer secret.

Restore transaction pages are bounded to 8 MiB of unencoded record bytes even when the requested item limit is larger. Unknown head states, unsafe counters, or missing transaction revisions fail closed as storage corruption.

The routes follow qwen.managed-agent.harness.enabled by default, because the Hosted Harness requires them; QWEN_MANAGED_AGENT_SESSION_STORE_ENABLED overrides that default. Serve them only on a private service listener or trusted service network. The explicit settings are:

export QWEN_MANAGED_AGENT_SESSION_STORE_ENABLED='true'
export QWEN_MANAGED_AGENT_SESSION_STORE_BASE_URL='http://127.0.0.1:8080'
export QWEN_MANAGED_AGENT_SESSION_STORE_WRITER_LEASE_DURATION='60s'
export QWEN_MANAGED_AGENT_WORKSPACE_ID='workspace-demo'

QWEN_MANAGED_AGENT_SESSION_STORE_BASE_URL must be reachable from the Hosted Harness. When it is blank and the store listener — the internal listener when internal-server.port is set, otherwise the public one — binds a blank, 127.0.0.1, 0.0.0.0, :: or ::1 address on a fixed port, the server uses that listener's loopback http:// URL. A public listener that serves TLS through server.ssl, or any other listener, needs an explicit URL. When both the Harness and Store are enabled, Java includes a scoped Store descriptor in each new private Hosted Session request. The ordinary daemon rejects that descriptor, while the Hosted Harness uses the TypeScript HTTP adapter with the descriptor's broker-issued writer credential (or a self-generated secret when no binding key is configured). Workspace-bound Sessions use their persisted Workspace ID for the Store scope; unbound Sessions use QWEN_MANAGED_AGENT_WORKSPACE_ID. The public Session, private journal and Runtime binding retain one (tenantId, workspaceId, sessionId) identity. When the global store ID is blank, the store uses the Runtime Broker's ID: its configured ID, otherwise the hash a local-process or Kubernetes Broker derives from QWEN_MANAGED_AGENT_WORKSPACE_CWD, even while the Broker is disabled. If the Runtime Broker also has an explicit ID, startup rejects a mismatch. Keep an existing deployment's ID unchanged, since unbound Sessions resolve their store scope from it.

This activates the durable create and cold-load paths for newly created Hosted Sessions. The load path rebuilds the Harness state from the scoped Store and does not require a Pod-local transcript. The Store boundary has an independent-JVM crash/takeover proof against real MySQL. A deterministic multi-process check also kills the real Java and Hosted Harness owners, deletes their local homes, and proves that replacement owners complete a second Turn with the first Turn's restored context. A separate recovery slice supports one known pending tool execution: the replacement Harness starts or polls the original Broker identity, commits its settled receipt as results_ready, and Java replaces the Harness boot and public event epoch under the Turn dispatch lease, durably records the replacement attachment watermark before invoking checkpoint-bound continuation with the original public prompt identity, and advances the cursor after the response. Unit, contract, and H2 coordinator/store tests verify that this path does not resubmit the Prompt or replay the tool. Do not advertise general automatic cross-Pod recovery yet. The SQL scan below discovers eligible committed wake inputs after writer loss; multi-tool recovery, recovered cancellation, event/checkpoint reconstruction after a mid-continuation Harness crash, the full multi-process in-flight failure matrix, OSS-backed resources, and scheduler recovery are still pending. Resources larger than 64 KiB fail with managed_session_oss_disabled until the immutable OSS path is implemented. Production deployments must add mTLS or equivalent service authentication; the tenant and writer headers are scope and fencing inputs, not a substitute for transport identity. Responses under the private prefix use Cache-Control: no-store.

Web fetch in Workspace Sessions

The main Hosted files, shell, search and team lead profiles provide web_fetch with url, prompt and optional format (auto, markdown, html or text). The bound Runtime fetches public HTTPS content and returns normalized text and HTTP metadata to the conversation model. default and auto-edit require approval with the actual destination URL; yolo retains its approval bypass. Plan mode, snapshot read profiles and the dedicated CSI files profile do not admit this tool.

The Runtime worker must use Node.js; other JavaScript runtimes are refused because they may ignore the pinned connection dispatcher. Every request, retry and same-host redirect checks and pins public DNS addresses, verifies TLS and uses a dedicated connection agent. Private and metadata addresses, URL credentials, plain HTTP and binary downloads are refused. The request does not inherit the process-wide proxy dispatcher. Cross-host, scheme or port redirects are returned for a new call and approval. Text is bounded to 16 KiB after JSON encoding with a truncation notice; no download or overflow file is written on the worker host. The worker does not make a separate model call or retain a web cache.

Upgrade Runtime workers together with the Harness before relying on its web-fetch/1 capability. See the English design and Chinese design.

Wake recovery after Harness loss

With the Session Store enabled, an independent control-plane scan discovers committed Monitor/background Shell, channel, child-result, workflow, Automation and Session message inputs after their writer lease expires. It runs every two seconds on a dedicated scheduler, handles up to eight candidate Sessions per pass, and leaves a durable 30-second retry delay after a claim. EventTransport is optional; an acknowledged or already-claimed MQ wake cannot suppress this scan.

Only a matching committed turn.settled consumes an input. Recovery reattaches the Session and lets its existing wake pump run unattempted inputs or settle interrupted attempts honestly. It does not replay tool effects or turn unknown results into success. Old inputs retain this policy regardless of age. Closing, retired, private CSI and stopped or terminal child runs are excluded; Workspace grants and mount checks still apply. A failed recovery logs the tenant and Session and remains retryable without a permanent attempt limit. Backlog or unavailable execution/restore evidence can delay recovery beyond the lease and retry time.

The shared V1 baseline includes a revision-stamped wake hint and retry timestamp in the Session head. Unknown or stale hints rebuild from committed journal events; compacted heads are excluded without marking their inputs consumed, while missing or corrupt proof is refused. Each proof invocation reads at most 32 transactions and yields with its complete continuation for a later claim; partial proof never clears the hint or triggers a load. At most 128 exact-prefix continuations or positive memos are retained. Live partials keep their slots; new long proofs wait for completed or ineligible holders to free capacity. A new revision or process restart begins proof at zero with the durable hint intact. Use matching Server and Broker builds that understand the current V1 baseline. This scan is locally verified on macOS/MySQL 8.4. Linux/Windows, real MQ-on and deployed provider acceptance remain unverified; see also Hosted recovery scope. The English design and Chinese design describe the recovery boundary and acceptance criteria.

Managed automation (H6)

The control plane runs the H6 automation runtime for persistent definitions: a definition is created, revised, read and retired under the Workspace-bound Session its creator owns (/v1/agent-automations), a scanner derives each definition's due slots on this host's tz database, claims the definition under a lease with a fence, records every occurrence decision in its own ledger (V57) and fires a run as one idempotent Hosted Harness operation; a manual run is the same operation keyed by its Idempotency-Key. The Session journal's schedule and automation_run chains stay the authority; the ledger locates, leases and indexes. The per_run target and the delivery policy are refused until their slices land. Design: managed automation runtime.

The settings use the qwen.managed-agent.automation prefix; the configuration reference lists each with its default and limits.

Full WebShell dual-path development entry

The full WebShell can keep an ordinary Qwen daemon for its existing chat, workspace, settings, and terminal surfaces while routing only the Managed panel to this Spring service.

The one-shot launcher starts the ordinary daemon and the private Hosted Harness from TypeScript source, writes the Harness wiring (QWEN_MANAGED_AGENT_HARNESS_*, the rotating capability digest, and the HTTP Session Store that Hosted Sessions require) to a spring.env under the OS temp directory — kept outside the served workspace, mode-0600 on POSIX (on Windows NTFS ACLs scope the per-user temp directory instead, and a PowerShell spring.env.ps1 sibling is written next to it) — waits for /actuator/health on the Spring service (--skip-java-wait bypasses), then opens the WebShell with the Managed panel selected:

npm run dev:managed-agent
# In a second terminal, before the Java health wait expires (10 min).
# Once per clone, and re-run after pulling changes to the Java SDK:
mvn -f packages/sdk-java/qwencode/pom.xml -DskipTests -Dgpg.skip=true install
# One-time, on a fresh MySQL 8 (creates the database and user the URL names;
# the performance_schema SELECT covers Flyway's boot probe — without it the
# probe is denied (ERROR 1142) and startup stops at 'foreign_key_checks'):
mysql -u root -e "CREATE DATABASE qwen_managed_agent CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'qwen'@'localhost' IDENTIFIED BY 'replace-me'; CREATE USER 'qwen'@'127.0.0.1' IDENTIFIED BY 'replace-me'; GRANT ALL ON qwen_managed_agent.* TO 'qwen'@'localhost'; GRANT ALL ON qwen_managed_agent.* TO 'qwen'@'127.0.0.1'; GRANT SELECT ON performance_schema.user_variables_by_thread TO 'qwen'@'localhost'; GRANT SELECT ON performance_schema.user_variables_by_thread TO 'qwen'@'127.0.0.1';"
# (official MySQL images enable skip-name-resolve, so 'qwen'@'localhost' alone never
#  matches TCP clients; a containerized MySQL sees the gateway address — grant at
#  'qwen'@'%' or the container-visible host instead)
# Every run; the launcher prints this spring.env path at startup (on Windows,
# the printed path is the spring.env.ps1 sibling):
source <printed spring.env path>
export SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/qwen_managed_agent'
export SPRING_DATASOURCE_USERNAME='qwen'
export SPRING_DATASOURCE_PASSWORD='replace-me'
mvn -f packages/managed-agent-server/pom.xml -pl server -am -DskipTests install
mvn -f packages/managed-agent-server/server/pom.xml spring-boot:run

The daemon, Harness and Java URLs print at startup with the spring.env path, and the full Managed URL (which carries the daemon token) prints on an interactive terminal; ports auto-increment when busy. The launcher verifies only that something Spring-Boot-shaped answers /actuator/health — it cannot prove that Spring loaded this run's spring.env, so restart Spring whenever the launcher (and its rotating token and digest) restarts. If every Turn then fails with hosted_harness_rejected in the panel: a Harness 400 means the Session Store wiring in spring.env did not load (invalid_managed_session_store — an env file from an older run), while a Harness 401 means a launcher restarted without restarting Spring — re-source the new spring.env and restart Spring.

To wire the pieces by hand instead, keep the ordinary daemon on 4170 (the vite proxy's default) and start the private Hosted Harness on a distinct port. The profile refuses to start without credentials, so the launch reuses the same credential pair the Prerequisites section exports for Spring — CLI-side the token travels as QWEN_SERVER_TOKEN and the capability digest as QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST — plus --no-web, which the profile requires and no environment variable supplies:

QWEN_SERVER_TOKEN="$QWEN_MANAGED_AGENT_HARNESS_TOKEN" \
QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST="$QWEN_MANAGED_AGENT_CAPABILITY_DIGEST" \
qwen serve --profile hosted-harness --port 4171 --hostname 127.0.0.1 --no-web

— and Spring must point at it with the matching base URL. The Hosted Harness rejects every attach without a store descriptor; the HTTP Session Store follows the Harness, defaults to this server's loopback listener and is scoped by the workspace ID exported in Prerequisites, so only the Harness URL changes:

export QWEN_MANAGED_AGENT_HARNESS_BASE_URL='http://127.0.0.1:4171'

It is read once at JVM startup, so if mvn spring-boot:run is already up on the 4170 value exported in Prerequisites, restart it with the override in place.

The ordinary daemon treats --port as a request and moves to the next free port on a collision, and 4171 is exactly where a daemon displaced from 4170 lands. The Hosted Harness profile never moves: it fails to start when its port is taken, naming the port. Start the Harness first, or confirm the daemon's bound port in its startup line.

With both up, run from the repository root:

QWEN_DAEMON_URL=http://127.0.0.1:4170 \
QWEN_MANAGED_AGENT_JAVA_URL=http://127.0.0.1:8080 \
  npm run dev:managed-agent-web

Open http://127.0.0.1:5174/?managed=1&managedProvider=java&tenant=local-java-demo. The standard WebShell entry proxies its existing routes to the ordinary daemon and /api/agent/web-shell/v1/** to Spring. Use managedSession=<sessionId> to deep-link a Managed Session. If the ordinary daemon requires authentication, append its token as the usual #token=... fragment.

managedProvider=java and tenant are local-development conveniences and are honored only by the Vite development entry. Production hosts should construct createJavaManagedAgentProvider(...) themselves and pass it to WebShellWithProviders.managedAgentProvider; a trusted upstream must derive the tenant instead of trusting a browser query parameter. Products that do not have an ordinary daemon can continue to render the exported ManagedAgentWebShell directly. Neither browser mode receives the private Harness or Runtime Broker credentials.

Native macOS Workspace development

The Java Broker can run the existing local Node.js tool worker on macOS with verified Workspace registration and durable same-boot worker adoption. Set QWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERY=false; whole-host reboot recovery remains Linux-only. Keep durable local mode and verified Workspace recovery enabled. Use the local directory import below for automatic registration, or register storage offline using the maintenance command and configure the same mount in the Java service. A missing registration still refuses tool execution.

For the Vite entry, set VITE_MANAGED_AGENT_WORKSPACE_BINDING=true and VITE_MANAGED_AGENT_ACTOR_ID to your development actor. On the loopback Java service, set QWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADER=X-Qwen-Actor-Id; local directory import grants the importing actor automatically, while offline registration requires a separate Workspace grant. Configure VITE_MANAGED_AGENT_MODEL_PRESETS with published AgentDefinition IDs for new-task model choices; the server's model-catalog supplies model choices within bound Sessions. These settings supplement the Broker and Hosted Harness wiring below; enabling selectors alone does not enable tools.

macOS storage identity combines IOPlatformUUID with the original device, inode and nanosecond birth time from native stat, cross-checked against the JDK directory identity. Worker identity also checks kern.bootsessionuuid and the exact process start instant before re-attestation. Preserve the SQL database, private Runtime state directory and credential key across Broker restarts. macOS handles use explicit macos namespace labels; older Java readers refuse them. A different boot is refused even for operator stop attestation. Background Shell, Monitor, command Hooks and Linux CSI retain their existing platform restrictions. The published reference distribution's Linux qualification is unchanged.

Embedded Runtime Broker

Public foreground Shell admission

Stored AgentDefinition Sessions keep their compiled profile and approval mode; the Shell switch changes only the built-in agent's default profile selection. Every Shell Session still requires the switch and valid asking approval for fresh execution. Harness load copies retain the definition identity alongside suppressChildAgents.

QWEN_MANAGED_AGENT_WORKSPACE_SHELL_ENABLED=true selects the server-owned hosted-workspace-shell/1 profile for newly created built-in qwen-code Workspace Sessions on both public REST and WebShell, including empty creation. It defaults to false and requires Workspace files plus its deployment prerequisites. Set QWEN_MANAGED_AGENT_APPROVAL_MODE to default or auto-edit; Shell opt-in with yolo, an empty or unknown mode fails startup. Shell always asks permission. Existing Sessions keep their stored profile and approval mode.

Disabling only the Shell flag refuses fresh Turns on existing Shell Sessions with 409 workspace_unavailable; original idempotency keys, accepted approval responses, cancellation and settlement remain supported while Workspace files remain enabled and persisted approval remains default or auto-edit. Files-off or invalid approval can refuse attachment; neither case is bypassed by a capability. Files Sessions retain their existing behavior. Shell Session responses add foreground_shell (public) or foregroundShell (WebShell); false disables fresh sending. Files and unbound Sessions omit the field, with no schema default. workspaceTurns expresses creator/grant permission, not sufficient Shell Turn admission: fresh sending also requires foregroundShell=true. Controlled W2 cwd changes do not execute Shell and retain their own files, actor, path and context-revision admission; the Shell flag is not a general Session freeze.

Shell close and active delete use lifecycle v2 with reliable original-Worker stop support. Archive and unarchive require completed close proof; unarchive restores CLOSED. A live or cancelling foreground Turn and a pending approval return turn_active. Shell lifecycle is advertised by default; an explicit empty lifecycle profile list disables it. Existing G3 recovery refusals remain in force; no dispatched Shell is automatically replayed. Keep the opt-in off until the deployment passes #12904, #13010 and public FG6f physical failure gates. See the complete design.

Public child agents

QWEN_MANAGED_AGENT_WORKSPACE_CHILD_AGENTS_ENABLED defaults to true and enables public agent delegation for qualified new built-in qwen-code Workspace Sessions. Set it to false to disable new delegation. Admission requires public Shell, a durable LOCAL process Broker, Session isolation, and a Harness advertising public-child-agents/1, approval selection and Shell lifecycle v2. Other deployment profiles continue to start without public child admission. Existing Sessions remain opted out. SSH, resident/CSI, custom definitions, Team, Workflow, messaging, nesting and isolated child Workspaces are excluded from this first release.

Children share the parent's directory, definition and owner, start without its conversation, and keep the effective approval mode, actual model route and Skills captured at launch. Later parent policy changes apply only to new children. Default execution is background; explicit foreground waits retain the existing mount restrictions. Each root admits at most four active children and 64 launches over its lifetime.

The optional child_agents / WebShell childAgents capability identifies orchestration support. Turning the deployment switch off blocks new launches while admitted tasks can still recover, receive approvals, stop and deliver results. Query pending approvals with include_children=true or WebShell includeChildren: true; answer each Action on its actual owner Session. Aggregation grants no new response permission.

Stopping a parent Turn durably stops new launches and requests cancellation for active children from that prompt only. A stop request is distinct from physical termination. Late results remain available through the task's childSessionId transcript without automatically waking cancelled work. Public children reject independent new Turns and policy/model changes. See the bilingual design for recovery and rollout acceptance.

Initial Workspace Turn (G0)

QWEN_MANAGED_AGENT_WORKSPACE_FILES_ENABLED=true opts in to an initial Workspace Turn supplied with public Session creation: Read/Write/Edit under hosted-workspace-files/1, or file tools plus mandatory-approval foreground Shell under hosted-workspace-shell/1 when the Shell opt-in above is enabled. The WebShell creation adapter uses the same admission. This requires the Hosted Harness and HTTP Session Store, default or auto-edit approval for Shell (yolo is also valid for files), and a local-process, session-isolated Broker with configured runtime-broker.workspace-mounts. Registry entries must use managed-runtime-tools/1 and preapproved-workspace-tools/1, and their tenant/storage identity must have a deployment mount. Fresh LOCAL databases additionally require QWEN_MANAGED_AGENT_RUNTIME_VERIFIED_WORKSPACE_RECOVERY_ENABLED=true on Linux or macOS and a successful native storage registration before tool or child Git execution. Every logical alias maps to one physical owner; aliases of the same native mount share that owner while retaining independent logical admission fences. Registration preserves the first marker provenance, and an unmapped alias cannot acquire physical execution authority. The trusted ingress must provide an AuthenticatedTenantActor principal with read/create grants; a caller header alone does not authenticate an actor. For local runs and the packaged-stack E2E, which have no ingress, QWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADER names a request header whose value is then trusted as the actor for the request's tenant. It is disabled by default; never enable it where untrusted clients can reach the server.

Upload files into a Workspace

With Workspace file access enabled and compatible Server, CLI and WebShell artifacts, select a persisted LOCAL or SSH_LOCAL Workspace and choose Add file → Upload to workspace. Uploads accept binary and empty files up to 8 MiB each, use an existing destination directory, and reject occupied paths without overwriting them. The composer inserts a scoped path reference for tools to use; binary bytes are not converted into a small-text snapshot or message attachment. Old CLIs leave upload disabled. CSI, folder uploads and automatic directory creation are unsupported.

Uploads require an authenticated actor with OPERATOR or OWNER access and verified storage. An execution-storage member, including a retained MCP Runtime, keeps the Workspace busy. A durable physical-storage hold excludes new execution and retirement until the original upload has a definite result. If the response is uncertain, query the original upload ID; recovery does not replay the write on another Runtime. Cancelling the browser request does not delete a file already committed. See the English design and Chinese design for the protocol, recovery and acceptance boundaries.

Create empty Workspaces from WebShell

Set QWEN_MANAGED_AGENT_WORKSPACE_CREATION_ROOT to an existing canonical, server-owned directory to enable New workspace → Start from scratch in the Managed composer. The default is disabled. The root must be separate from static Workspace mounts, the default Workspace cwd, and private Runtime state. Enable Workspace files, the Session Store, the durable Session-isolated local-process Broker and verified local Workspace recovery first. Enabling this setting authorizes authenticated tenant actors to allocate independent empty roots and receive OWNER access; only enable it for tenants allowed to consume this host's storage.

POST /api/agent/web-shell/v1/workspaces/create accepts displayName (trimmed, 1–128 characters without controls) and idempotencyKey. It returns the regular Workspace summary without host paths. Creation freezes an actor-scoped WORKSPACE_CREATE receipt, derives a tenant-separated directory below the configured root, registers its native identity and marker, and atomically publishes the ACTIVE Workspace with its creator grant. The Workspace query advertises workspaceCreation when enabled. Existing static mount configuration continues to work.

An uncertain response must be retried with the same key and name. The page preserves that pending operation across refresh and selects the result without clearing the prompt or model. Completed replay never restores revoked access, recreates missing registry rows, or registers held storage again. Pending registration resumes in place after a process restart; failed attempts retain their owned directory for retry. There is no automatic storage deletion or arbitrary host-path import. Workspace persistence does not imply recovery of a resident Harness Session whose writer lease expired during control-plane downtime; that existing Session recovery boundary is separate from creating or reusing a Workspace. Keep the configured root and SQL database durable together. Schema V4 extends the receipt namespace after the published V3 Session-list migration while retaining all published migration resources and existing data.

Select an existing local project directory

For a trusted single-user deployment bound to loopback, enable QWEN_MANAGED_AGENT_LOCAL_DIRECTORY_IMPORT_ENABLED=true alongside Workspace files, durable local-process execution and verified recovery. Authenticate with signed requests or OPEN mode plus a trusted actor header. The single-user qwen serve --managed launcher enables this capability with signed authentication. Then Workspace → Choose existing directory browses this computer directly, without a pre-registered parent or grant. Import keeps the project in place, automatically registers its projects parent outside Git worktrees, grants the current actor OWNER access, and sets the project as the initial working directory. The parent shares file access and catalog-local leases across projects; this is not a filesystem sandbox or a global parent-directory claim. New imports use imported-<receipt key> storage IDs and private registration metadata below runtime-broker.state-directory/imported-projects/<storage ID>. Independent local catalogs may import the same project while leaving any global storage marker untouched. Whole-storage migration, physical recovery and exclusive file-history rewind are unavailable for these shared imports; own-process Runtime recovery remains available. Existing owned roots are reused while sessions run. Private Runtime state and creation roots must stay outside imported parents. Remote listeners cannot enable this local feature, including with the insecure bind override. Signed mode retains signature validation and does not accept a trusted actor header in its place. This capability is for a trusted single-user host deployment.

The actor-authenticated directory query accepts localPath (empty starts at the host home directory), and create accepts an absolute localPath with the name and idempotency key. These fields are exclusive with Workspace-relative source fields. localDirectoryImport advertises the capability independently; pending receipts pin native root identity and completed receipts resolve imported roots after restart or disabling further imports. Neither retry nor restart repairs a missing or mismatched registration metadata or restores revoked access. Legacy created- imports and application-owned roots keep their global marker contract; no existing receipt or marker is converted automatically. See the local import design.

For other deployments, the existing authorized-root flow remains available. With verified LOCAL storage enabled, New workspace → Choose existing directory browses the Linux or macOS execution host through Java. Select an ACTIVE ROOT Workspace you own, then choose an existing project beneath its authorized root. Administrators can register and grant a projects parent directory once; the root must remain outside all Git worktrees. The selected project stays in place and becomes the new Workspace's persistent default working directory. Other Workspaces on that storage retain the same shared file-access scope and physical-owner lease; selecting a subdirectory does not create filesystem isolation.

POST /api/agent/web-shell/v1/workspaces/directories/query accepts workspaceId and cwdRelative, rechecks OWNER access and native storage, and returns at most 100 real immediate child directories (scanning at most 1024 entries). Only this authorized route discloses its execution-host root path. The existing create route accepts sourceWorkspaceId and cwdRelative together to bind a new logical Workspace to the verified source storage, configuration, and policy. It does not create directories or re-register storage. The creation receipt pins source generation and directory; pending retries refuse source changes or revoked ownership. Completed replay checks the new Workspace's current access. WebShell summaries expose defaultCwdRelative and canSelectDirectory; missing values mean . and unsupported, respectively. The page advertises workspaceDirectorySelection separately from empty creation and preserves the selected directory across retries, refresh, and reselect. See the bilingual design.

QWEN_MANAGED_AGENT_APPROVAL_MODE defaults to yolo. In default and auto-edit, any caller with a read grant on the bound Workspace can list and inspect pending permission Actions through the public API or WebShell; answering one needs the Session's recorded owner or a caller holding OPERATOR or above, and that read grant as well. A Shell Session is the exception: only its recorded owner may answer, because that answer runs a command. Responses are durable, idempotent operations; their final result follows the committed Harness decision. QWEN_MANAGED_AGENT_APPROVAL_TIMEOUT defaults to 10m and accepts 1s to 24h. The initial approval mode is pinned at Session creation and must be confirmed by the Harness on creation and load. Built-in Workspace Sessions can select a different policy for later Turns while retaining the original definition.

Structured user questions

Root Sessions using hosted-workspace-files/1, /2, /3, or hosted-workspace-shell/1 expose ask_user_question, including public Plan mode. The tool asks one to four required questions, each offering two to four choices and a custom-text answer. Single-choice questions accept one option or custom text; multiple-choice questions also allow both together. The tool must be the only call in its batch. MCP/Hook Sessions, child Sessions, foreground-only workers and resident CSI profiles do not expose it.

The question appears as a pending Action with kind: question. WebShell keeps the answer draft visible until delivery is confirmed; refreshing retrieves the same pending Action. Public responses use kind: question, answers with question_id, optional option_ids and optional text, plus the Action's input_revision and policy_revision. WebShell uses their camelCase names. Use the returned question and option IDs, not their labels, and the existing Action response endpoints and idempotency key. Response authorization is the same as permission Actions, including the Shell owner restriction.

Questions always wait for a human answer, including Full Access and live approval-policy changes. The existing approval timeout, cancellation and expiry rules apply. Invalid or conflicting answers cannot replace the durable decision; an equivalent retry returns the original result. The original question and answer survive service/Harness restart and resume the same tool call. Answer text is limited to 8192 UTF-16 code units per question and the canonical answer array to 32 KiB; the complete tool input is limited to 16 KiB.

Deploy compatible Java server, Java SDK, Harness and WebShell artifacts together. Drain and fence older writers before reopening execution; older binaries cannot interpret the new question options/decisions and must not resume Sessions with pending questions. No database schema change is required. See the question design (简体中文) for the continuation contract and acceptance scope.

Approval policy selection

For new Workspace-bound WebShell Sessions, the shared composer queries POST /api/agent/web-shell/v1/session-options/query with agentId using the authenticated tenant actor. The response contains the effective approvalMode and availableApprovalModes; Workspace discovery advertises approvalModeSelection for this contract. Built-in Sessions allow default, auto-edit, and yolo (Full Access). Shell Full Access additionally requires the Harness feature approval-selection/1; without it Shell offers only default and auto-edit. The Shell deployment opt-in and its deployment default remain unchanged. Hosted execution does not support classifier auto or plan. An AgentDefinition exposes only its compiled policy, which a creation request cannot override.

The WebShell create request may include approvalMode only with a Workspace binding. Omission preserves the existing default and request digest; explicit selection is persisted in the Session and joins its idempotency digest. Retrying the same key reads the original pin even if deployment defaults, the AgentDefinition, or a later Session selection changed. Workspace-bound and definition-pinned Session summaries expose the current approvalMode, immutable initialApprovalMode, and approvalRevision. Legacy unbound built-in Sessions omit this metadata because their execution policy is supplied by the deployment. The public REST create contract is unchanged.

The only ordinary Shell profile is hosted-workspace-shell/1, including native glob alongside Read/Write/Edit, Shell and Monitor. The unshipped /2 Shell profile was removed; development Sessions using it must be recreated. See the consolidation design (简体中文).

Eligible Workspace Sessions can change their execution approval policy. With the Harness feature live-approval-selection/1, a selection affects subsequent permission checks in the current Turn, and ordinary pending tools are durably allowed when the selected mode permits them. Already dispatched tools and explicit Hook or Plan-exit approvals retain their existing decisions. Built-in qwen-code Sessions require the Harness feature approval-selection/1. Stored AgentDefinition Sessions using exactly hosted-workspace-files/1, hosted-workspace-files/3 or hosted-workspace-shell/1 additionally require agent-definition-approval-selection/1; both features must remain available for execution after any override, including a return to the initial mode. POST /api/agent/web-shell/v1/session-approval/query returns the current mode, revision, available modes, and support. POST /api/agent/web-shell/v1/session-approval/change accepts sessionId, approvalMode, expectedRevision, idempotencyKey, and requestId. Only the recorded Session owner with current Workspace OPERATOR or OWNER access may change it or replay a receipt. Without live support, the Session must be idle, with no pending approval or retained Runtime. Context/lifecycle and recovery barriers always apply; Plan changes remain idle-only. The options response advertises live behavior with liveSupported. Upgrade the control plane and Harness together in a maintenance window, fencing old Java writers before reopening execution; new Harness tool Turns refuse a missing live-policy endpoint. See the live approval design (简体中文). Identical retries return the original result without another revision; different content under the same key and stale revisions conflict. The definition pin and initial creation policy remain immutable; later user Turns freeze the selected mode and revision. Creation options still expose only the compiled initial policy. Files/2, MCP, read-only child, team-lead, CSI, unknown profiles, and unbound text Sessions do not gain policy selection; hosted-workspace-files/3 does. There is no public REST mutation endpoint. See the stored-definition approval design (简体中文).

The stored-definition extension needs no schema migration, but old Java readers and writers ignore custom overrides. For live approval, use the coordinated control-plane/Harness upgrade described above and stop or fence every old Java/Broker process sharing the catalog before permitting changes. After a custom override, rollback must use a compatible build or keep affected Sessions blocked while applying a forward fix. Do not mix old Java binaries, clear revisions, or rewrite definition/history to roll back. Custom initial-yolo definitions retain the existing ten-minute approval timeout fallback after an override; custom initial-default/auto-edit definitions retain their stored timeout.

Schema V6 preserves the original policy and adds a current override plus per-Turn approval snapshots. Turn admission and policy changes share the Session row lock. Immutable Turn snapshots preserve retry and recovery identity; live permission boundaries separately read the current durable Session selection. Revision zero and legacy Turns consistently omit the private approvalSelection field, preserving prompt retry identity across Harness capability upgrades; positive revisions always send the saved Turn snapshot. yolo skips ordinary file and Shell approvals, while explicit Hook ask/deny decisions retain their existing behavior. The configured approval timeout persists for new selectable Full Access Sessions and survives a later switch back to asking. Legacy Full Access definitions without a timeout keep the existing 10-minute fallback. WebShell retains an uncertain change with its original request and key across refresh, blocks send/model/cwd changes until receipt readback, and ignores older policy revisions. A Session with an override cannot execute through an older Harness. Follow the coordinated live rollout above; rollback binaries must understand the saved override and snapshots. See the approval selection design.

Workspace-bound WebShell Session summaries can include modelContext with the actual observed modelId, optional latest-request inputTokens and resolved contextWindowSize, and observedAt. The Hosted CLI records capacity beside successful provider usage; the Java Session Store projects only committed main-model attempts into one private latest-resource pointer. Lists read these observations in one batch without scanning journal history. Older or invalid usage advances the pointer but leaves missing values unknown; cumulative billing totals and inferred capacities never substitute for them. The shared usage popover does not offer manual compression. New tasks continue to select published AgentDefinition presets. This observation projection uses existing SQL tables and resource-reference cleanup without changing the recovery format.

To allow an existing Workspace Session to change its next Turn's model, publish an explicit qwen.managed-agent.model-catalog list of {modelId, label} entries in the server configuration. The default is empty. IDs must identify configured, cached-credential models in the Hosted CLI; this selection path supplies only an ID. The Harness must advertise model-selection/1. POST /api/agent/web-shell/v1/session-models/query returns the catalog and current selection; POST /api/agent/web-shell/v1/session-models/change takes sessionId, modelId, expectedRevision and idempotencyKey and synchronously returns the saved selection. The caller needs Workspace OPERATOR or OWNER and the Session must be idle, without pending approval, context/lifecycle work or recovery. Same-key retries return their original result before mutable catalog and role gates, provided the caller still has read access. They never reapply a change.

Creation can instead supply a complete connection in public model_config or WebShell modelConfig:

{
  "protocol": "openai",
  "model": "qwen3-coder-plus",
  "base_url": "https://models.example/v1",
  "api_key": "application-supplied-key",
  "generation_config": { "temperature": 0.7, "max_tokens": 4096 }
}

Configure qwen.managed-agent.model-config-base-urls as a YAML list containing the exact allowed base URLs; its empty default disables this path. The Session Store and session-model-config/1 Harness capability are required. The standard server also needs the Runtime Broker's SecretProtector and credential key ring. Protocols are openai, openai-responses, anthropic and gemini; accepted generation fields are temperature, top_p, top_k, max_tokens, presence_penalty, frequency_penalty and seed. The Anthropic adapter forwards only temperature, top_p, top_k and max_tokens; it ignores seed and both penalty fields. Other provider support varies, and providers may reject parameters they do not support. URL userinfo, query strings, fragments, OAuth and arbitrary headers are not supported. Credentials are literal values, without environment substitution.

The complete configuration is encrypted with tenant/Session binding and included in creation idempotency through its digest. It is immutable, inherited by child Sessions and restored after Harness reattachment. It overrides host model settings, including auxiliary and fallback choices, for this Session's execution. Do not combine it with modelId; host-catalog switching is disabled for these Sessions. Public responses and journal resources never include the credentials. Retain encryption keys while ma_session.model_config_key_id references them, including for closed Sessions. The unreleased V1 schema gains these columns; recreate development catalogs under the existing schema policy. No browser credential editor is included.

For multi-tenant deployments, a trusted application service or gateway must authenticate tenant/actor identity and retain the platform signing key. The endpoint allowlist is deployment-wide; tenant-specific model permissions, parameter limits, quotas and outbound network restrictions must be enforced by the caller or deployment. Each Session retains an immutable credential snapshot, so replacing a provider key requires a new Session. See the deployment boundary.

Idle Workspace Sessions support manual context compression when the Harness advertises context-compression/1. Send POST /v1/agents/sessions/{sessionId}/compress with Idempotency-Key and { "expected_compaction_revision": 0 }, using the Session's current compaction_revision; WebShell uses /api/agent/web-shell/v1/sessions/compress and camelCase fields. The public context_compression capability advertises deployment support; the WebShell contextCompression capability also reflects the current caller grant and execution facts. A Workspace OPERATOR or OWNER can admit the durable context_compression operation; the existing operation query returns pending, running, recovery_blocked, completed or failed, and a completed outcome is compressed or noop. Same-key retries resolve the original operation before mutable capability, revision and busy checks. Compression refuses active or queued Turns, approvals, unsettled Hooks and conflicting context work. It does not create a user Turn or change approval, Plan or Workspace context revisions. After compression, context usage stays unknown until the next main-model observation. Deploy matching Server/Broker, Harness and WebShell builds using the current V1 baseline; stop new compression admission and settle accepted operations before rollback. Existing retained journals establish their compaction revision on first read; if that evidence is unavailable, the capability is false and the revision is omitted.

Schema V5 adds the current selection to the Session and copies it into each newly admitted Turn. Retries and recovery send that Turn's fixed model, never a later Session choice. No explicit selection preserves the original AgentDefinition/deployment behavior. Selection does not change the AgentDefinition identity, instructions, tools or approval policy. Each newly committed selection clears the latest context observation, including A→B→A without a Turn, until a new successful model request supplies usage. modelSelection in the summary describes the next-Turn setting; modelContext describes an actual successful request. An unavailable selected model fails closed rather than falling back to the deployment model.

Submit agent_id: "qwen-code", the existing workspace selection and input through POST /v1/agents/sessions. The server persists hosted-workspace-shell/1 with the deployment default default/auto-edit policy when the Shell deployment opt-in is enabled, otherwise hosted-workspace-files/1 with the configured file approval mode. This also applies to empty bound creation. The Session Store uses the persisted Workspace ID; public callers cannot choose the profile. W1c offline migration remains files/1-only and refuses persisted Shell definitions with migration_profile_unsupported. Configure the Harness's deployment-owned --managed-runtime-broker-url and --managed-runtime-broker-token options, or the QWEN_MANAGED_RUNTIME_BROKER_URL and QWEN_MANAGED_RUNTIME_BROKER_TOKEN variables they fall back to, to reach this Broker. The variables keep the token off the command line, and qwen serve removes them from its environment once read, so no process the Harness starts inherits the token. When QWEN_MANAGED_AGENT_HARNESS_CREDENTIALS_FILE names that environment file and it sets the token, the control plane takes its Broker token from it and refuses a second, direct QWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKEN. A repeated creation key returns the original Session/Turn; changed input conflicts. Disabling the Workspace files opt-in refuses creation with input, including replays, while empty bound creation remains available. The Shell opt-in selects the persisted profile; it does not independently admit creation input. Upgrade the Harness before enabling the Shell flag: an older Harness ignores suppressChildAgents and would advertise the child agent tool. The directory mounted for a Workspace is trusted deployment data, not a filesystem sandbox.

Later Turns may be submitted by any caller holding OPERATOR on the bound Workspace under the same opt-in while the Session's creator-keyed execution facts hold (the Workspace registry still backs the binding and stays ACTIVE, and the actor recorded by the Workspace create command keeps OPERATOR or above; the WebShell adapter's per-caller workspaceTurns capability flag mirrors exactly that rule, though the public surface publishes no such flag). Shell Sessions also require the Shell opt-in and valid persisted approval for fresh sending. workspaceTurns does not certify Shell admission; Shell clients also require foregroundShell=true. Such a caller may cancel the Session's running Turns and rename the Session — a readable actor below OPERATOR gets 403 session_operation_forbidden, and an admitted OPERATOR blocked by the shape or fact gates gets 409 workspace_unavailable. Workspace close follows its separate close capability and lifecycle admission. Public Shell close and active delete use the existing lifecycle v2 path when the Runtime can reliably stop the original Worker. Shell lifecycle is advertised by default; explicitly setting QWEN_HOSTED_LIFECYCLE_V2_PROFILES replaces the list, and an empty value disables it. Archive and unarchive require completed close proof; unarchive restores CLOSED. Active or cancelling foreground Turns and pending approvals return turn_active: cancel the original Turn, wait for settlement, then close. Background Shell, Monitor and child Sessions use the existing resource drain and cascade. Uncertain execution, output or stop evidence remains blocked for recovery. Controlled cwd changes ship below (W2); broad Workspace capability advertisement remains gated. Qualified new public Shell Sessions expose agent under the public-child admission above; public Session messaging remains unavailable. Background Shell, Monitor and complete in-flight recovery remain separate slices. The existing EmbeddedRuntimeBroker is used through production configuration; no direct store admission or test Broker replacement is needed.

Design: English | 简体中文.

Broker authentication and writer credentials

QWEN_MANAGED_AGENT_AUTH_MODE selects how the public surface (/v1/agents/** — including the bare POST /v1/agents collection route — and the WebShell adapter) authenticates its caller: auto (the default) resolves to open when server.address is loopback and refuses to start otherwise, open keeps the header-asserted tenant and the optional trusted-actor stand-in for local runs, and signed requires every public request to carry X-Qwen-Actor-Id, X-Qwen-Signature-Timestamp (epoch seconds, within QWEN_MANAGED_AGENT_AUTH_ALLOWED_DRIFT, default 5m, minimum 1s) and X-Qwen-Signature: v1=<lowercase hex HMAC-SHA256> over the canonical string below, keyed by QWEN_MANAGED_AGENT_AUTH_SIGNING_KEY (at least 32 bytes):

"qwen-broker-auth-v1\n" + METHOD + "\n" + undecoded request path + "\n"
+ raw query string (empty when absent) + "\n" + tenant + "\n" + actor + "\n"
+ timestamp + "\n" + lowercase hex SHA-256 of the raw request body + "\n"
+ the Idempotency-Key header value (empty when absent)

A repeated Idempotency-Key header answers 400 invalid_request, and a body beyond QWEN_MANAGED_AGENT_AUTH_MAX_SIGNED_BODY_BYTES (default 10 MiB) answers 413 payload_too_large. Signed mode cannot be combined with QWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADER.

QWEN_MANAGED_AGENT_SESSION_STORE_BINDING_KEY switches writer tokens from self-minted to broker-provisioned: the writer credential becomes an HMAC over (tenantId, workspaceId, sessionId) that the Broker hands to the Harness in the attach payload, and the store rejects any other token, including during a free lease window. A configured key must be at least 32 bytes. A Broker that intentionally serves the store over plaintext HTTP inside a trusted network sets QWEN_MANAGED_AGENT_SESSION_STORE_ALLOW_INSECURE_HTTP=true, which the attach payload forwards to the Harness so its client accepts the URL. The internal surface (/internal/**) may move to its own listener via QWEN_MANAGED_AGENT_INTERNAL_SERVER_PORT and QWEN_MANAGED_AGENT_INTERNAL_SERVER_ADDRESS (default 127.0.0.1); either port then answers 404 for the other surface's routes. Leaving loopback — public or internal — requires signed mode or a configured binding key respectively, unless QWEN_MANAGED_AGENT_AUTH_ALLOW_INSECURE_BIND=true explicitly overrides the guard. Loopback is a trust boundary only as strong as the host: a shared host that runs untrusted workloads (including model-generated commands) should configure a binding key even on loopback.

Design: English | 简体中文.

Session working directory

Select the Workspace-relative working directory when creating the Session. Directory-change submission and the WebShell Change directory action have been retired. Previously admitted CWD_CHANGE operations still settle through their original coordinator and remain readable through operation queries; their records, fences and session.context.changed events are retained. Daemon/ACP relocation and tool-level directories are separate capabilities.

Design: English | 简体中文.

Broker deployment

The Broker starts before the first Hosted Harness connection, so the supported startup order is Spring/Broker first, Hosted Harness second, traffic last. The Harness SDK handshake is lazy and occurs on the first admitted Turn.

For the single-node local-process provisioner, also set:

export QWEN_MANAGED_AGENT_RUNTIME_BROKER_ENABLED='true'
# Omit when QWEN_MANAGED_AGENT_HARNESS_CREDENTIALS_FILE names a file that sets
# QWEN_MANAGED_RUNTIME_BROKER_TOKEN; setting both refuses startup.
export QWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKEN='replace-me'
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY_ID='local-dev-v1'
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY='replace-with-base64-encoded-32-byte-key'
export QWEN_MANAGED_AGENT_WORKSPACE_CWD='/absolute/authorized/workspace'
export QWEN_MANAGED_AGENT_RUNTIME_STATE_DIRECTORY='/absolute/private/state'
export QWEN_MANAGED_AGENT_NODE_EXECUTABLE='/absolute/path/to/node'
export QWEN_MANAGED_AGENT_RUNTIME_WORKER_ENTRY='/absolute/path/to/dist/cli.js'

For the external scratch provisioner, set these instead of the node executable, worker entry and state directory (the Broker token and credential key pair are still required). External scratch also requires an explicit Workspace ID: the worker-side cwd cannot be hashed on the Broker host, so no ID can be derived for this kind.

export QWEN_MANAGED_AGENT_RUNTIME_BROKER_ENABLED='true'
export QWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKEN="$QWEN_EXTERNAL_BROKER_TOKEN"
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY_ID='external-dev-v1'
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY="$QWEN_EXTERNAL_CREDENTIAL_KEY_BASE64"
export QWEN_MANAGED_AGENT_CAPABILITY_DIGEST="$QWEN_EXTERNAL_CAPABILITY_DIGEST"
export QWEN_MANAGED_AGENT_RUNTIME_PROVISIONER='external-scratch'
export QWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERY='false'
export QWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_URL='https://provider.example/'
export QWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_TOKEN="$QWEN_EXTERNAL_PROVIDER_TOKEN"
export QWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_PROVIDER_ID='external'
export QWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_REQUEST_TIMEOUT='30s'
export QWEN_MANAGED_AGENT_EXTERNAL_RUNTIME_STARTUP_TIMEOUT='2m'
export QWEN_MANAGED_AGENT_WORKSPACE_ID="$QWEN_EXTERNAL_WORKSPACE_ID"
export QWEN_MANAGED_AGENT_WORKSPACE_CWD='/workspace'

Keep Workspace files and Shell disabled. Fill the $QWEN_EXTERNAL_* variables with your own values from a secret store and pick a stable Workspace ID; they are placeholders for operator-supplied values, not usable defaults. Set the capability digest (sha256: plus 64 lowercase hexadecimal characters) even with Harness disabled; the embedded Broker requires it. The provider URL must be HTTP(S) without credentials, query or fragment, and the cwd is the worker-side path. The provider implements authenticated provision and observe routes and must persist its mapping from the Broker's logical handle to one immutable physical resource across restarts. There is no release route, so a closed Session's worker is not stopped and its provider TTL must be budgeted. This increment has no tool consumer yet: Session Turns warm the worker but the model receives no tools until the Workspace extension lands. See the Broker guide and the bilingual design.

Local-process workers run model-directed tools, so the Broker starts them without any environment variable whose name begins, in any letter case, with QWEN_MANAGED_AGENT_, QWEN_MANAGEDAGENT_, QWEN_MANAGED_RUNTIME_BROKER_, SPRING_ or OSS_. Every other variable of the server process still reaches the worker and its tools. Keep unrelated secrets out of the service environment. A worker that uses the artifact tool's oss publisher therefore needs its credentials under the ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET and ALIBABA_CLOUD_SECURITY_TOKEN names, which that publisher also accepts. Those names are not filtered: they reach every worker the Broker starts and every model-directed tool it runs. The Broker copies its environment into a worker once, at launch, and never refreshes it; a Broker restart does not refresh a durable worker that it adopts by pid. Give those names a long-lived RAM identity that can only write the artifact bucket and prefix, never the account key that the OSS_ filter withholds. A short-lived STS token needs a rotation path that re-execs the Broker before it expires, and even then an adopted durable worker keeps its launch-time credentials. One credential set serves every tenant and workspace on the host. This does not isolate files: a worker runs as the service account and can read whatever that account can.

After a credential-key rotation, keep each prior key in previous-credential-keys while any persisted row references it: Runtime bindings, complete Session model configurations and extension settings all retain key IDs. Use the retirement query in the runbook linked below to check all three scopes.

The brackets are not decoration: Spring's relaxed binder strips /, : and spaces from plain map keys, so an unbracketed ID binds as a key that matches no persisted row.

qwen:
  managed-agent:
    runtime-broker:
      credential-key-id: local-dev-v2
      credential-key: replace-with-base64-encoded-32-byte-v2-key
      previous-credential-keys:
        '[local-dev-v1]': replace-with-base64-encoded-32-byte-v1-key

New credentials use only the active key; reads select the active or previous key by the ID stored with the ciphertext, and an unavailable ID fails closed. The YAML-only ring, the retirement query, the operator-recovery ring and the single-key-pair CSI/migration entries are normative in Rotate the Runtime credential key, with the rationale in the rotation design.

Two optional settings change how the Broker listens and how long it waits for a dispatched v3 execution's result: runtime-broker.allow-non-loopback and runtime-broker.v3-result-window. Read their entries in the configuration reference before changing either.

Every qwen.managed-agent.* duration setting binds a suffix-less number as seconds except for runtime-broker.retention.max-age, which binds as days, and the millisecond-bound settings below. Millisecond-bound settings — auth.allowed-drift (so a stale 300000 keeps meaning five minutes instead of widening the signature-replay window to ~83 hours), the sub-second events.batch-interval and events.materialize-interval, runtime-broker.child-workspace-git-timeout, runtime-broker.retention.scan-delay, automation.scan-delay, automation.lease, automation.late-tolerance and automation.lookback — bind a suffix-less number as milliseconds. Always write the suffix (90s, 500ms). At startup the server reads each seconds-convention setting's written value and warns on a bare integer — the shape of a stale milliseconds-style override — naming what the number binds as now (seconds) and what it would have bound before (milliseconds); a suffixed value never warns. Cadences bound through @Scheduled placeholders — artifacts.projection-interval, channels.scan-delay, child-relay.scan-delay, child-workspace.scan-delay, dispatch.scan-delay, events.replay-floor-interval, message-relay.scan-delay, session-worktree.scan-delay and wake-recovery.scan-delay — also read a bare number as milliseconds, and the startup warning cannot see them, so always write the suffix there.

For the local-process and Kubernetes provisioners, when QWEN_MANAGED_AGENT_WORKSPACE_ID is omitted, the server derives the same 16-character SHA-256 workspace ID that Qwen Code uses from the canonical workspace path. An explicitly configured ID must match that value or startup fails before traffic is accepted. The derivation does not apply to external-scratch, which requires an explicit ID because its worker-side cwd cannot be hashed on the Broker host.

The Hosted file profile connects through the private Broker endpoint, which defaults to http://127.0.0.1:4182. When enabled, the embedded Broker always uses the Spring DataSource and Flyway-managed Runtime tables; it does not fall back to in-memory repositories. The active credential key and every configured previous key must decode to exactly 32 bytes and protect persisted Runtime seeds and static Runtime credentials with AES-256-GCM. New writes use only the active key; reads select the exact key ID stored with the ciphertext. By default, local worker ownership is durable: the Broker registers every launch and a restarted Broker adopts the same live worker. This requires Linux and fails startup elsewhere; on such hosts set QWEN_MANAGED_AGENT_RUNTIME_DURABLE_LOCAL_PROCESS=false together with QWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERY=false to keep worker ownership ephemeral (a restarted Broker then cannot adopt it). The state directory must be persistent local storage, owned by the Broker user with mode 0700, without symlinks, outside every configured Workspace root. The expected owner is resolved from the process UID, so a numeric UID without a passwd entry is fine. Workers and tools must be trusted; same-UID hostile tools and multi-host or remote storage are unsupported. Keep the host machine ID, SQL credential key, placement mapping, state directory and worker command stable across Broker restarts. Shutdown and late lease discard detach from registered workers instead of killing them. /etc/machine-id must be nonempty and stable, and Linux must expose the PID and time namespaces (/proc/self/ns/pid and /proc/self/ns/time; the latter requires Linux 5.6 or newer with CONFIG_TIME_NS). An empty or malformed identity fails startup the same way as an absent one, naming both opt-out switches. The service manager must let workers survive a Broker exit: systemd's default KillMode=control-group kills them, as does restarting a container whose main process is the Broker. Configure the service to leave child workers running (for example, systemd KillMode=process) and use an init that reaps orphaned processes. The Broker recognizes Z/X workers as exited even before they are reaped. Missing or damaged records and worker death do not authorize replacement; worker death does not prove escaped writers stopped. No host reboot reclamation is enabled by this option alone. Old v1 handles cannot be upgraded by guessing identity. This option does not retire idle workers or prune their registration and lock files. With session isolation, each Hosted Session can retain a separate idle worker across Broker restarts; budget process, memory and state-directory growth for it. Physical cleanup needs an evidence-preserving lifecycle; do not delete records to reclaim capacity. See the adoption design.

Trusted same-host Linux reboot recovery is also on by default. It requires durable local mode with the local-process provisioner, so a deployment that opts out of durable local workers or uses another provisioner must set QWEN_MANAGED_AGENT_RUNTIME_TRUSTED_LOCAL_REBOOT_RECOVERY=false. A changed kernel boot ID on the original machine can prove that original local writers stopped; worker-only death still cannot. The service scans eight saved bindings every five seconds, independently of current Session grants, and clears only the original SQL holder after all execution receipts become terminal. Recovery never starts a replacement worker or replays an unknown execution. A later authorized request may create a new generation. Keep the same Broker user, local disks, machine identity and SQL keys; remote writers, restored/cloned snapshots and external jobs that recreate writers are outside this contract. Where a matching boot identity cannot be trusted as stop evidence, set the option to false. The reboot recovery design distinguishes portable test evidence from the dedicated Linux reboot acceptance gate completed at W0e-3 head 8c2b626c. A systemd soft reboot is not stop proof because it does not change the kernel boot ID.

The Kubernetes adapter's real-cluster fault matrix remains a production gate. This standalone reference keeps the one configured directory for legacy unbound Sessions. Persisted bound Sessions use the private Workspace execution path below.

Managed Server and Runtime Broker share the single 38-table baseline in persistence/src/main/resources/db/managed-schema/V1__managed_schema.sql. Until the first formal Managed Agent release, schema changes update this V1 baseline in place. Do not add V2+ migrations or increment the database schema version before that release. Recreate development catalogs when the baseline changes; pre-release database upgrades are not maintained. The Server loads it through Flyway; Broker initialization reads the same resource. Both refuse a legacy, partial, foreign, or history-only catalog before schema writes. An already initialized complete baseline is structurally validated; a Broker-created baseline may be registered by Flyway only after that validation. Schema initialization does not repair or backfill old data.

Use a new MySQL 8.4/InnoDB database for the new environment. Quiesce old admissions and settle in-flight work before cutover; retain the old environment/database for historical reads. New Sessions belong to the new database, which must remain available if routing is rolled back. The retired SQL/Java migration chain and upgrade tests are archived outside the runtime classpath. The former separate Broker schema.sql has been removed.

Terminal Runtime record retention

Runtime JDBC retention is disabled by default. It removes old terminal executions, Sessions and bindings in bounded batches on a dedicated scheduler; it does not stop workers or delete Workspace files. Its settings use the qwen.managed-agent.runtime-broker.retention prefix; the configuration reference lists them with their environment variables, defaults and limits.

Recovery records, Workspace holders and CSI retirement keep their bindings. Child Session lineage also keeps a binding until its canonical parent child_run has a committed terminal projection; a missing projection remains protected. This lets cascade and relay repair a stopped child's original Runtime identity. Lineage and permanent relay classifications are never collected here. A :process execution also keeps its whole binding family while its owning Session has an unsettled background Shell child_run, including top-level Sessions and Workspace isolation. This preserves the process-status evidence used by Session-open never-started reconciliation until those Shell records settle; the association conservatively protects the whole owning Session. The lookup deduplicates owning Sessions by both raw value and binary identity before checking their records on the sweep connection. Publication and CSI ACK references keep the original execution and its parents, including already collected publications; unreferenced siblings may be removed. Nonterminal children, live operation/dispatch leases and managed bindings without stop evidence remain retained. Binding slots and generation counters, placement guards, harness drains and storage fences remain durable. Successful ticks log scanned, skipped and deleted counts and duration; failures retry on the next tick.

Enabling retention allows eligible, unreferenced historical records to be deleted once they age past max-age; it does not guarantee deletion by that age. Publication and CSI ACK references retain executions and their parent sessions and bindings regardless of age, including COLLECTED publications. After cleanup, existing missing-record responses apply. Callers must not reuse expired Runtime Session IDs or idempotency keys. Initialize a fresh database with the single canonical 38-table V1 baseline and keep cleanup disabled. Legacy catalogs are rejected; no in-place upgrade or old-data migration is provided. Verify repeated initialization preserves terminal receipts, retain the old environment for historical reads and settle its in-flight work before cutover. Shared publication, CSI operation/work and Session record variants are checked by their typed discriminators; their metadata and physical owner headers are not collected. Every publication writer must use the locking protocol, and retention stays disabled until the exact-identity Hosted cleanup release-proof contract in #13992 is delivered and verified. An owed cleanup descriptor can outlive its RELEASED binding; collection then makes the original release conflict and blocks the Hosted Session. This PR does not implement that release-proof contract. Disable retention before reverting to older writers; disabling prevents future cleanup but cannot restore deleted records. See the retention design.

Private Workspace tool execution (W0c-3)

The worker entry is the built CLI bundle; the server launches it with managed-runtime-worker. Configure canonical existing roots using Spring configuration (all Brokers sharing the database must use the same mappings):

qwen:
  managed-agent:
    runtime-broker:
      workspace-mounts:
        - tenant-id: tenant-a
          storage-id: storage-a
          root: /absolute/canonical/workspace-a

An empty mapping list rejects bound Session execution. This path requires local-process provisioning and session isolation. The Session must be created through W0b with a Registry configuration reference of managed-runtime-tools/1 and policy reference of preapproved-workspace-tools/1. The original creator must still have read and create grants. Other frozen configuration pairs are refused.

The private Broker can acquire, execute Read/Write/Edit/foreground Shell, and release these Sessions. One Runtime Session holds each tenant/storage pair until the original worker closes its execution gate. Lost or ambiguous responses retain the SQL holder; there is no timeout-based takeover. The provider and file tools do not confine access to the mount root: Read/Write/Edit and Shell can reach other paths allowed by the worker's host permissions. Foreground Shell may create detached descendants. Use this only with trusted local workloads. The W0e recovery above handles trusted host reboot; it does not provide physical isolation or recovery after worker-only death. Public bound Turn admission is limited to the initial Workspace Turn described in G0 above (file tools, or mandatory-approval foreground Shell under the Shell opt-in; the public-child admission above controls agent) and later Turns submitted by any caller holding OPERATOR on the Workspace under the same opt-in while the Session's creator-keyed execution facts hold (the WebShell adapter's per-caller workspaceTurns capability flag mirrors that same rule; the public surface publishes no such flag). Shell Sessions additionally require the Shell opt-in and valid persisted approval for fresh sending; workspaceTurns does not by itself admit a Shell Turn, which also requires foregroundShell=true. Such a caller may also cancel the Session's running Turns and rename the Session. Later Turns run under the creator's Workspace grants, so an actor without a read grant keeps the existing session_not_found invisibility, a readable actor below OPERATOR is refused session_operation_forbidden, and an admitted OPERATOR whose Session lost the creator-keyed facts meets the family's domain workspace_unavailable. Public Shell close and active delete require lifecycle v2 and reliable original-Worker stop support. The canonical Shell profile advertises v2 by default; explicit lifecycle environment values override that list. Public close follows its separate close capability and lifecycle admission. Archive, delete and unarchive follow their separate retention capabilities after reliable Workspace close; the Shell profile reaches public creation only through the deployment Shell opt-in described above; callers cannot select it. See the bilingual execution design for the exact boundary.

Hosted files/Shell file history additionally requires persistent worker backup storage. Configure an absolute QWEN_HOME in the Broker/worker environment and mount it as durable storage writable by the worker OS user. Backups are stored at $QWEN_HOME/file-history/<Harness Session ID>/; without the override they use the worker user's ~/.qwen/file-history/. Preserve this directory alongside the Workspace and SQL database. A Workspace mount alone does not preserve these backup bytes, and referenced backups must survive worker/container restarts. The stock image runs as UID 10001; derived images must provision appropriate write access for their worker user.

Roll out the Broker and worker bundle before the Hosted Harness. An older Broker rejects raw-history control, including the bind before a read-only tool turn. The Harness releases a definite rejected bind and ends the turn with an error; it does not run unbacked writes. Missing backups also refuse tool turns until the original backup data is restored. Unknown or partial effects still require operator recovery. See the bilingual file-history design for record capacity and rewind semantics.

Verified original-mount recovery (W1a)

The current fresh 38-table baseline requires this physical mount guard for LOCAL tool and child Git execution in a trusted, single-host OpenJDK 21 local-process deployment on Linux or macOS with a persistent, unambiguous root birth time. Enable QWEN_MANAGED_AGENT_RUNTIME_VERIFIED_WORKSPACE_RECOVERY_ENABLED=true and complete offline registration before admitting that work. Text-only Turns can run without registration; LOCAL tool acquisition fails with 409 workspace_unavailable when the physical mapping is absent. Taking the next tool Turn after a Broker restart also requires durable-local-process=true. macOS requires trusted-local-reboot-recovery=false and supports same-boot adoption only. Linux whole-host restart succeeds only while the registered physical identity still matches. The shared V1 baseline stores registration, independent mount_birth_time and mount fence in ma_storage and ma_storage_owner. An unregistered mount is never registered from the directory found at startup.

Marker v2 stores birth time as a canonical Instant string. Linux reads creation time, mtime, device and inode in one JDK unix attribute snapshot and rejects creation time at/before epoch or equal to mtime, which OpenJDK 21 may return when birth time is unsupported. A real Linux birth time equal to mtime is also conservatively refused; prepare the project layout or update the root's mtime offline before retrying. macOS reads native nanosecond birth time with stat and cross-checks its device/inode against the JDK canonical-directory snapshot, because JDK 21 truncates macOS birth time to seconds. A positive native macOS birth time is independent even when it equals mtime; fresh empty roots keep their original birth time. Mtime is not an identity field, and ordinary mtime changes do not invalidate an unchanged birth time. The marker contains an application-specific HMAC-SHA256 host ID with Qwen-Code/verified-workspace/v2 as input. Its key is the trimmed machine-id UTF-8 bytes on Linux or the original IOPlatformUUID UTF-8 bytes on macOS; neither raw identity is stored in the marker.

Keep the storage root outside every Git worktree, with Session cwd in a child project directory. .qwen-managed-storage.json is an administrator maintenance file: do not read/write it through model tools or subject it to Git cleanup/stash. Tools are not confined by this layout. Missing or conflicting markers close admission; completed registrations never automatically republish them, including on a same-UUID retry. Marker repair needs a separate design.

The first-release contract initializes fresh catalogs with one complete shared V1 baseline and marker v2. Server, Broker, Harness and WebShell must use matching builds. Earlier development catalogs and checkpoints are unsupported; keep any data that still needs historical access with its original deployment, and use a fresh database and state directory for this build. Do not bypass refusal with Flyway repair, outOfOrder or manual history edits. See the first-release contract (简体中文).

Stop all processes and external jobs that can write the storage, account for old Runtime holders and verify the original root before registration. Initialize the new database with the canonical V1 baseline, then run the private maintenance entry from this module on the same execution host. Give a stable canonical lowercase, hyphenated 36-character UUID to each operation and reuse it after a crash. Database credentials come from W1_JDBC_URL, W1_JDBC_USER and W1_JDBC_PASSWORD environment variables:

mvn -q -pl server -am -DskipTests -Dgpg.skip=true install
mvn -q -pl server exec:java \
  -Dexec.mainClass=com.alibaba.qwen.code.managedagent.maintenance.WorkspaceStorageRegistrationMain \
  -Dexec.args='register tenant-a storage-a /absolute/canonical/workspace-a <operation-uuid> --offline-confirmed'

In the reference distribution, run it as bin/qwen-managed-agent-admin storage-registration register tenant-a storage-a /absolute/canonical/workspace-a '<operation-uuid>' --offline-confirmed; bin/qwen-managed-agent-admin with no arguments lists every maintenance entry it wraps. The same entry is available from a shipped Spring Boot fat jar, without the source checkout or Maven:

java -cp /path/to/app.jar \
  -Dloader.main=com.alibaba.qwen.code.managedagent.maintenance.WorkspaceStorageRegistrationMain \
  org.springframework.boot.loader.launch.PropertiesLauncher \
  register tenant-a storage-a /absolute/canonical/workspace-a '<operation-uuid>' --offline-confirmed

inspect <tenant> <storage> <canonical-root> is read-only. The same entry also accepts fence or restore-original with a mount revision and the exact operation UUID; both require --offline-confirmed. A fence has no timeout and requires every holder field to be clear after exact-owner cleanup. Entering a new fence and restoring both require the intact registered root identity and marker. W1 cannot force-fence, re-register or repair a changed identity or missing marker; admission stays closed until the verified original mapping is re-presented, or a separately designed offline repair is performed. Stop new admissions, settle or cancel original executions, prove writers stopped, release holders and stop service/external writer processes before fencing. restore-original only reopens the still-verified original mapping after its holder is clear. Both commands accept retries with the same operation UUID; restoring increments the mount revision, so a delayed old fence cannot reopen maintenance. Completed registration and restore retries revalidate identity and marker; concurrent same-operation retries do not advance the revision twice. Inspect reports state, revision, active/completed operation, holder and independent identity/marker status, including while fenced. The flag records the operator's offline check; the program cannot stop arbitrary processes or external writers itself. Do not use it on a live shared storage.

After registration, enable QWEN_MANAGED_AGENT_RUNTIME_VERIFIED_WORKSPACE_RECOVERY_ENABLED=true on the whole new deployment before admission. On each new attachment, model submission, Runtime claim and execute, the server compares the configured canonical root against the SQL registration, Linux host/device/inode/birth-time identity and the root marker. A missing or conflicting marker, replacement root, missing saved cwd or fenced storage blocks new work; original execution status/cancel and authorized history remain on their saved identities. The marker is a continuity check, not a backup or protection against a malicious same-UID writer. See the W1 design. Hosted Workspace cold-load validation is always enabled, independently of the Java mount-guard option. Omitted tool profile and Shell captureBytes use the saved definition; supplied values must match exactly. Saved approval settings remain pinned. Integrity checks run before new model work or Broker prepare/execute and cover retained private resources plus complete remote Shell output, including pages, segments and empty-stream seals. Preserve O2 recovery of original results_ready, consumed-final and not_started receipts. An incomplete receipt may produce a blocked ACK or original-history repair before load is refused, so refusal does not promise zero journal writes or ACKs. Restore validation uses a fixed committed cut, and continuation still requires current writer ownership and authorization. Missing old resources or unsupported recovery domains block loading. Passive Harness loading does not implement unknown-execution cleanup; use original Broker execution identities. Rollback to old binaries requires entry points to remain stopped because those binaries ignore the fence columns. Public Workspace next-turn admission for any caller holding OPERATOR on the bound Workspace, while the Session's creator-keyed execution facts hold, under the G0 opt-in described above has landed; public Workspace resume still requires product-route integration, and this internal guard is not a public resume capability yet.

Build the container from the repository root:

docker build -f packages/managed-agent-server/Dockerfile .

The stock image contains the Java control plane only. Use the static Runtime provisioner, or provide a derived image/mount with Node.js and the Qwen worker artifacts, before enabling the local-process provisioner in a container.

The image keeps the application's 127.0.0.1 defaults, so a plain docker run -p 8080:8080 publishes nothing: -p DNATs to the container's bridge IP, and a loopback listener is unreachable through it. Publishing is an explicit opt-in, and the server refuses a non-loopback bind under the shipped auto auth mode, so the command must name an authentication posture — signed mode, as the introduction recommends (see "Broker authentication and writer credentials" above). The signing key and the datasource password are passed valueless so Docker forwards them from the shell environment — the = spelling would leave either secret in the command's argv for the container's whole lifetime. A valueless -e forwards the variable of the same name, so export QWEN_MANAGED_AGENT_AUTH_SIGNING_KEY and SPRING_DATASOURCE_PASSWORD before the run. The datasource must also be named: the Prerequisites' 127.0.0.1 default is the container itself from inside, so the image cannot boot against it:

docker run -p 8080:8080 \
  -e QWEN_MANAGED_AGENT_SERVER_ADDRESS=0.0.0.0 \
  -e QWEN_MANAGED_AGENT_AUTH_MODE=signed \
  -e QWEN_MANAGED_AGENT_AUTH_SIGNING_KEY \
  -e SPRING_DATASOURCE_URL='jdbc:mysql://<db-host>:3306/qwen_managed_agent' \
  -e SPRING_DATASOURCE_USERNAME='qwen' \
  -e SPRING_DATASOURCE_PASSWORD \
  <image>

or the deliberately unauthenticated -e QWEN_MANAGED_AGENT_AUTH_ALLOW_INSECURE_BIND=true override.

The qwen user the recipe names needs the grants from the Full WebShell entry's MySQL one-liner — including SELECT on performance_schema.user_variables_by_thread, granted at the container-visible host — or Flyway's boot probe is denied (ERROR 1142) and startup stops.

Publishing the API needs no Runtime Broker face: the broker ships disabled by default, and a non-loopback broker bind is a separate opt-in — the broker refuses one unless QWEN_MANAGED_AGENT_RUNTIME_BROKER_ALLOW_NON_LOOPBACK=true is also set (see Broker deployment above).

The opt-in makes the authentication consequence load-bearing. Under the shipped default — auto resolving to open — there is no HTTP authentication: tenancy is whatever X-Qwen-Tenant-Id says. Signed mode HMAC-authenticates every request's tenant and actor headers; the insecure-bind override publishes with request authentication off. Either way the tenant-scoped API is exposed to anything that can route to the listener. That exposure does not depend on publishing a port: on the default bridge network the API also answers on the container's own bridge address, so every process on the Docker host and every peer container on that bridge can reach it with no -p at all. Run a published deployment behind an ingress that authenticates the tenant before setting X-Qwen-Tenant-Id, map ports only inside your own network policy, and attach the container only to networks whose peers you trust.

Managed Session Store verification

Run Maven from the parent directory. Unit and H2 tests run in verification with the normal test phase; all original profile names and test families remain available from the parent reactor. Focused commands such as mvn -Dtest=ModuleArchitectureTest,ManagedAgentEmbeddingTest test build required production modules first. Test reports are under verification/target/{surefire-reports,failsafe-reports} and aggregate coverage under verification/target/site/jacoco-aggregate. Do not run the verification POM alone against stale installed same-version artifacts. mvn clean verify checks the compiled module boundaries, the existing test families and packaged server artifacts. The embedding-host fixture is under verification/src/test/embedding-host; after installing the production reactor, run its normal and embedded profiles to verify an independent host. mvn verify additionally runs the SpotBugs high-confidence gate (Maven 3.8.9+): a new warning fails the build, and a false positive goes into spotbugs-excludes.xml with a justification in the PR. To run the static gates without the test suite, use mvn verify -DskipTests — it also runs Checkstyle and the Spring Boot repackage, and the full suite includes environment-sensitive timing tests that can fail on a local machine, so CI is the arbiter; for SpotBugs alone, run mvn compile spotbugs:check. The optional real-MySQL profile also verifies schema upgrade, exact bytes, public Item projection, and the independent-JVM Managed Session Store crash/takeover path:

mvn -Pmysql-integration \
  -Dmysql.url='jdbc:mysql://127.0.0.1:3306/managed_agent_test' \
  -Dmysql.user=root \
  -Dmysql.password= \
  verify

Use a disposable database: the integration test creates and deletes fixture rows within the selected schema.

The hosted-harness-mysql profile additionally clears every ma_ base table before each top-level Hosted*IT class, while retaining the schema and Flyway history. Its JUnit extension is enabled only in that profile; one fork and disabled JUnit parallelism keep cleanup ahead of the next class's contexts. Use a database exclusively owned by this test invocation. Class teardown must still stop all contexts and child processes. State is preserved between methods, nested classes, and context restarts inside one class. See the isolation design (简体中文).

Managed extension packages

Complete package distribution and the seven-component Managed profile are opt-in. Set QWEN_MANAGED_AGENT_EXTENSION_PACKAGES_ENABLED=true, QWEN_MANAGED_AGENT_EXTENSION_ARTIFACT_DIRECTORY to a durable private directory, and QWEN_MANAGED_AGENT_EXTENSION_ALLOWED_ACTORS to the permitted operator actor keys. The configured Workspace OPERATOR grant is also required. See the configuration example for the separate Runtime execution profile: Linux LOCAL and SSH require delegated cgroup v2; native macOS requires the explicit developer-process-group mode. Existing Runtime bindings do not acquire the new execution contract automatically. Replicas must share the authoritative artifact directory. A Runtime cache is reconstructible and cannot replace that directory. Published versions and encrypted settings revisions are retained; this increment does not implement garbage collection.

In WebShell, select the Managed Workspace and Session, open Extensions, prepare an original Git/npm/directory/archive source for its target platform, then publish it. An update explicitly selects the catalog extension ID. Select package versions and an exact saved settings revision before applying to an idle Session. Saving settings creates a complete immutable revision; values never appear in read responses. Upgrading a package preserves its selected settings revision. An unfinished apply has separate Continue original operation and Restore previous version controls; unknown outcomes continue to block inference until the original owner reconciles.

Public clients use /v1/agents/workspaces/{workspaceId}/extensions for bounded binary publication and catalog queries and /v1/agents/sessions/{sessionId}/extensions for configuration queries and application. The OpenAPI contract documents the settings and operation subresources. The Java SDK exposes ManagedExtensionsClient; the TypeScript daemon SDK can prepare and stream an original package. Creation's optional extensionPins freezes the initial selection before the first model call. Omitting it retains the existing Session path.

Package assets use an explicit read-only extension source. Model tool schemas list the selected public pins; read_file and glob accept package-relative paths or extension://<extensionId>/<path>. Shell selects extension_context and receives QWEN_EXTENSION_ROOT, while its working directory remains the Session directory. Ordinary Workspace tools retain their existing containment rules. Executable preflight checks target interpreters and directly resolvable commands without running Hooks or connecting MCP; complex authored Shell expressions are checked when their approved invocation executes. Argument placeholders inside nested Shell substitution, backticks or heredocs are rejected explicitly.

See the linked English design and Chinese design. Local focused tests, macOS developer receipts and the existing Linux static-extension gate below establish different boundaries. Complete package Linux/SSH cleanup, fault injection and real-provider qualification remain separate acceptance gates.

Linux extension process acceptance

HostedExtensionsIT is collected by the existing hosted-harness-mysql profile. It uses the public AgentDefinition and Session APIs, real MySQL, the packaged Harness and durable native worker, a stdio MCP process, and command Hooks in a delegated cgroup v2 subtree. It verifies static Skill bytes, extension revision pinning across Harness replacement, Hook allow/deny, cancellation of a Hook and its descendant, safe continuation, and physical close. A separate MCP fault case writes and fsyncs an effect before disconnecting, then verifies that a replacement Harness refuses recovery without replaying the effect or reporting successful close.

After building the root packages and bundle and installing the current Java SDK, run this focused slice from packages/managed-agent-server on Linux with JDK 21, Node 22+, disposable MySQL 8.4, and Maven already inside the delegated cgroup ancestor:

QWEN_MANAGED_HOOK_CGROUP_ROOT=/sys/fs/cgroup/your-delegated-root \
  mvn -Phosted-harness-mysql -Dit.test=HostedExtensionsIT \
  -Dnode.executable=/absolute/path/to/node \
  -Dqwen.cli.entry="$PWD/../../dist/cli.js" \
  -Dmysql.url='jdbc:mysql://127.0.0.1:3306/managed_agent_test' \
  -Dmysql.user=root -Dmysql.password= verify

Missing Linux/MySQL/cgroup prerequisites are not acceptance. This selector verifies only the extension class; it does not establish that the complete Hosted profile passed. Evidence is saved before forced fixture teardown under verification/target/failsafe-reports/hosted-extension-evidence/ and is included in the existing CI report upload. The interrupted MCP case leaves its public Turn RUNNING with durable ma_turn.error_code = hosted_runtime_recovery_blocked and ordinary execution UNKNOWN, rejects new input and close with 409 turn_active, and does not replay the physical effect; successful cleanup is established by the separate healthy-close case. This gate uses a controlled loopback model and local stdio transport, so it does not establish upstream-model, remote transport, reboot, cross-machine, SSH MCP/Hook, or production acceptance. See the complete English design and Chinese design.

Real-model end-to-end check

The full-chain script starts Spring with its embedded Runtime Broker and runs both the Hosted Harness and the worker from the packaged dist/cli.js: the Harness as node dist/cli.js serve --profile hosted-harness, and each worker, launched by the Broker, as node dist/cli.js managed-runtime-worker. No separate worker bundle exists. The G0 integration test (HostedPublicWorkspaceIT) uses the same packaged dist/cli.js.

The real-model run below creates its Session through the public route as a Workspace-bound G0 Session, and proves the physical tool execution through the durable ma_tool_execution record (exactly one SETTLED row). Hosted tool intent and receipt events also expose tool names and lifecycle status through public item.tool_call.updated events without O2 publication. Raw arguments and output remain behind the existing publication policy. The Hosted model loop follows model.maxSessionTurns (default -1); it no longer imposes a separate 16-round limit. See the progress design. The run needs live model credentials, so no CI job executes it; it has been run locally as evidence (macOS, qwen3.8-max), and a green CI run therefore says nothing about this mode. The script also needs java, mysqld, mysql and mysqladmin on PATH; it starts its own temporary MySQL server and exits before starting anything else when a command or a required file is missing.

Build the required artifacts first, then run (the Maven steps need Maven 3.8.9+ — the SpotBugs gate rides the verify phase that install traverses):

npm run build && npm run bundle
mvn -f packages/sdk-java/qwencode/pom.xml -DskipTests -Dgpg.skip=true install
mvn -f packages/managed-agent-server/pom.xml clean package
npm run test:e2e:managed-agent-server -- --model moonshot/kimi-k3

For the deterministic durable-owner failover check, use the same built artifacts and run:

npm run test:e2e:managed-session-failover

This mode uses a local fake model, completes one Turn, kills the Spring and Hosted Harness process trees, deletes their old local homes, starts replacement owners against the same MySQL store, and verifies that the second Turn sees the first Turn's prompt and answer.

The in-flight and continuation variants run the same replacement-owner proof through a physical Workspace file tool execution. The runner configures the G0 public Workspace admission for every mode — it seeds the Workspace registry and access grant as deployment data, enables the G0 file admission, and uses QWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADER for its local actor — and the real-model check and both tool-driven variants create their Sessions through the public route as Workspace-bound Sessions, while --session-failover deliberately stays unbound to exercise the plain durable-owner takeover:

npm run test:e2e:managed-inflight-failover
npm run test:e2e:managed-continuation-failover

Both modes require Linux: the replacement owner retires the dead worker's Runtime binding through the durable local-Worker reclaim (#12380 W0e), which runs on Linux only. The runner enables durable-local-process for these modes and refuses other platforms with an explicit error; the Hosted failover E2E CI job runs both.

The in-flight mode holds the first Broker :start request after the Harness has durably committed its await_runtime checkpoint, kills the original Spring and Hosted Harness process trees, deletes their homes, and starts replacement owners. It requires the replacement Harness to use the original executionCallId, execute the physical tool exactly once, continue the original Prompt without replay, and commit one public terminal event. The continuation mode kills the Harness after the first published text chunk and requires one tool execution, one further continuation, only the replacement's answer in the public transcript, and one terminal event. Both modes run in the Hosted failover E2E CI job.

The G3 arms replace owners without an operator choosing the next one. With --harness-only, the Spring control plane stays alive and only the Hosted Harness is killed, so the live control plane must adopt the next Harness generation:

npm run test:e2e:managed-harness-restart-failover
npm run test:e2e:managed-harness-restart-inflight-failover
npm run test:e2e:managed-harness-restart-continuation-failover
npm run test:e2e:managed-harness-restart-model-round-failover

The model-round arm creates a Session with no Workspace, publishes a prefix from its first model round, and kills the Harness twice. Each replacement must reissue the same saved model request and retract the prefix before its own text appears. The arm then requires one terminal event, only the final answer in the public transcript, no tool execution, and a next Turn whose model history holds one copy of the prompt and answer and none of the prefixes.

The Step 3 packaged gates take over a parked native-file approval or model continuation through a Harness-only replacement. Each keeps the original identities (the Action for the approval gates, the Runtime binding and the prepared or settled execution), confirms the original Runtime cleanup, completes a next Turn, and closes the Session:

npm run test:e2e:managed-harness-restart-approval-allow
npm run test:e2e:managed-harness-restart-approval-deny
npm run test:e2e:managed-harness-restart-approval-cancel
npm run test:e2e:managed-harness-restart-approval-expiry
npm run test:e2e:managed-harness-restart-continuation-closeout

Five arms from #14481 step 2 layer one fault on the Allow path. The first crashes the replacement Harness as soon as the decision is durably recorded; the second holds the Runtime Broker's execution :start so the crash lands after the PREPARED row and before the physical dispatch; the third crashes after the approved result commits while the post-tool model round is held, so its reissue must reuse the saved request and retract the published prefix. All three leave the original Action, prepare key, digest and Runtime identity in place, start a third Harness generation, and require exactly one settled execution, one file effect and one terminal. The other two drop the control plane's reply after it committed; the retry under the same Idempotency-Key must land on the original record, so a lost decision produces one ACTION_RESPONSE operation and a lost Turn admission produces one Turn row:

npm run test:e2e:managed-harness-restart-approval-after-decision
npm run test:e2e:managed-harness-restart-approval-after-prepare
npm run test:e2e:managed-harness-restart-approval-after-result
npm run test:e2e:managed-harness-restart-approval-decision-reply-lost
npm run test:e2e:managed-harness-restart-approval-admission-reply-lost

Two more cover the next barriers of the same matrix. The terminal reply-loss arm commits turn.settled, loses its reply (and every bounded retry of it) until the crash, and restarts the Harness; the replacement projects the committed terminal, and no second store commit is required. The missing-terminal arm refuses the write itself, so the replacement must compensate the payable checkpoint exactly once. Both keep one original Action, one settled execution, one file effect, one terminal, the recovered model answer and the original cleanup:

npm run test:e2e:managed-harness-restart-approval-terminal-reply-lost
npm run test:e2e:managed-harness-restart-approval-terminal-write-failed

A refused cleanup release followed by another crash (C3) refuses the release until the Turn is terminal and its Harness is killed. The owed cleanup is then paid by the replacement through the control plane's debt retry, not by the Turn path: the arm requires the replacement's own release, one confirmed event and no remaining HOSTED_CLEANUP projection:

npm run test:e2e:managed-harness-restart-approval-cleanup-failed

The control plane retries that debt itself. A periodic scan reads the dedicated managed database (never an embedded host's business database), lists outstanding HOSTED_CLEANUP owners whose Session has no active Turn, resolves the owed Turn from the cleanup descriptor, and issues the same prompt-scoped cleanup-only load an operator recheck uses. The scan is keyset-paginated and wraps around, advancing past unreadable descriptors so a stuck prefix cannot starve later debts. Retries back off in memory from 10 seconds to 5 minutes; an attempt that loses the daemon or its reference drops the connector's cached attachment so the next one loads the replacement generation, while a named refusal of live work only backs off. A Session with live work, an unsupported profile or unreadable evidence keeps its debt and waits for the operator recheck route. See the cleanup debt design.

A lost takeover-load reply (A4's load half) drops the reply to the replacement's first drive load once, via a test-gated Harness hook (QWEN_E2E_DROP_LOAD_REPLY, never set in production). The control plane redrives the same load into the now-active driver; the arm asserts the reply was actually lost, then requires the original Turn to project exactly one terminal with the recovered answer — the redrive restates the active attachment instead of wedging the Turn:

npm run test:e2e:managed-harness-restart-approval-load-reply-lost

A crash between the main stream's durable Finished marker and the assistant commit (B3a) holds the replacement inside that window via a test-gated Harness hook (QWEN_E2E_CRASH_BEFORE_ASSISTANT_COMMIT, never set in production), set only on the generation that must crash. Once its post-tool round records Finished, the hook holds before the assistant commit and the runner kills it there; the next generation must reissue the saved request deep-equal and project one terminal with the recovered answer, rather than compensate an already-committed output:

npm run test:e2e:managed-harness-restart-approval-finished-before-commit

A crash in the mixed-sibling approval gap (A3's native half) approves a two-call batch one sibling at a time and holds the replacement on the first approval it asks after the earlier sibling is decided, via a test-gated Harness hook (QWEN_E2E_HOLD_PENDING_SIBLING_APPROVAL, never set in production) set only on the generation that must crash. The runner kills it there; the next generation must re-hang the original pending Action with its original deadline, require that sibling's own Allow rather than inherit the earlier one, leave the decided sibling un-re-asked, and settle both calls once each in their original order:

npm run test:e2e:managed-harness-restart-approval-sibling-approval

A crash after several earlier tool rounds (B3) runs a multi-round fixture with two earlier tools and holds the replacement while a later post-tool request is open (the hold is on the fake-model side, so no serve hook is needed). The runner kills it there; the next generation must resume the saved logical round and restore the turn cost snapshot and per-model token ledger rather than restart them, with each earlier execution occurring once and the later request reissued deep-equal. "Cost budget" here is the TurnBudget snapshot plus the token ledger, not a cumulative spend gate:

npm run test:e2e:managed-harness-restart-approval-after-earlier-tools

They write their evidence under .qwen/investigations/g3-step3-implementation/; G3_VERIFY_REPORT_DIR overrides the directory. The remaining rows stay focused or integration tested for now: the rewritten-input and Hook-no-rerun half of mixed calls (a commandStep follow-up, since a native continuation refuses Hook/MCP sessions), Hook/MCP/child uncertainty, the attempt and stream identities plus the live SSE view, and the mixed-version reader/bundle closure (#14481).

Two arms keep a former owner alive while its replacement finishes the Turn and then wake it with SIGCONT:

npm run test:e2e:managed-continuation-frozen-owner-failover
npm run test:e2e:managed-frozen-control-plane-failover

The first freezes the original Harness, so it covers the journal: the woken writer commits nothing. The second freezes the original Spring and Harness together during a no-tool model round. It starts a second Spring and Harness on the same MySQL, and the new Harness reissues the round to completion. After the wake, the MySQL general log must show the former Spring's claim UPDATEs carrying its stale owner id, and the former Harness must log the store's refusal of its stale writer grant. None of these attempts may change the Session binding, the Turn row, the public events or the journal, as far as the snapshot listed in D11 of the replaceable-Harness design can see. All of these arms are steps of the Hosted failover E2E CI job (hosted-failover-e2e), which runs daily or on demand. It builds the CLI and packages the server itself, so a failing test in the Hosted MySQL job does not skip the arms, and each arm runs even when an earlier one failed.

Hosted recovery scope

Ordinary LOCAL and SSH_LOCAL Managed Workspace Sessions may execute concurrently in the same directory, with one active Turn per Session. An UNKNOWN tool result on a READY binding retains its original Runtime Session and cannot be replayed, but does not exclude another ordinary Session. Existing LOST, DRAINING, OPERATOR_RECOVERY and attested RECOVERY_BLOCKED placement barriers remain in force. Physical registration, fencing, migration and maintenance still require every execution membership and unproven writer to drain. Shared files have no transactional isolation. Undo can run alongside other Sessions and uploads, subject to the existing file-level history checks. An active or unconfirmed undo blocks only its originating Runtime Session's execution, repeated undo and mount handback; neighboring Sessions can continue. Resident/private CSI and existing Agent/Workflow child-admission restrictions are unchanged. See the concurrency design (简体中文) and the updated rewind semantics (简体中文).

The baseline stores ordinary execution memberships per Runtime Session. Use matching Server/Broker builds with a fresh catalog. CSI reservation and physical-maintenance ownership retain their existing roles. Development catalogs using singleton holders require their original deployment to finish or recover and release those holders; they cannot be reused by this build.

The SQL wake scan has separate local macOS/MySQL 8.4 evidence; it does not yet have Linux/Windows, real-MQ or deployed provider acceptance. The scope below does not extend those claims.

The first Hosted release supports recovery for one Java control-plane instance on one trusted Linux host. That control plane replaces reachable Hosted Harness process generations one after another, and a Runtime Session stays exclusive to its Session. Recovery covers only the profiles and parked states that are explicitly supported and accepted on the released artifacts. The gates above accept the in-flight and continuation Runtime takeovers, the native-file approval waits and the first model round of a no-tool Session, all without Hooks or MCP. An in-flight Shell call and unknown external effects stay blocked rather than replayed, and Step 3 neither reissues a model round nor resumes an approval in a Session with Hooks or MCP. Journal writer fencing, durable engine ownership, capability and journal-contract checks and fail-closed recovery apply throughout. A refused recovery is never replayed through another Runtime or the Legacy engine.

The frozen control-plane arm shows that a woken former control plane's stale claim is refused and changes nothing, and a store test pins the bind guards that claim never reaches. Neither makes two live control planes a supported deployment. Routing between them is out of scope: a new Turn could be claimed by either one. Cross-host takeover, physical-ownership handoff between hosts, real providers and mixed-version clusters still need their own acceptance before they are supported.

The --big-output long-answer mode is also Workspace-bound:

npm run test:e2e:managed-big-output

It streams a long answer, verifies the complete public text and stored record, deletes the original Harness and Runtime homes, and checks the complete answer in a cold replacement's model context. A short answer remains inline. This mode executes no tools and has no Runtime binding to reclaim, so it keeps durable-local-process disabled and does not require Linux.

A zero-delay run checks the real-model path as shown above; a controlled cold-start delay additionally tests output before Runtime readiness:

npm run test:e2e:managed-agent-server -- \
  --model moonshot/kimi-k3 \
  --runtime-delay-ms 45000

That run additionally requires the first model event to precede Runtime readiness whenever the delay reaches the 15 seconds the acceptance criterion names. A deterministic controlled-model proof of the same ordering is tracked in #12941.

The real-model check extracts only the selected model provider, its referenced environment credential, the selected model, and the authentication policy from the supplied settings file into a private temporary Qwen home. It does not copy hooks, MCP servers, extensions, tools, permissions, or other provider credentials. The runner removes that file, the MySQL data directory, workspaces, and child processes on exit. Override the source with --settings /path/to/settings.json; credentials are never printed by the runner.

W1c offline Workspace migration

See the English design and Chinese design. Run only after every service is upgraded, admission/dispatch is disabled, accepted work is settled, Harness writers are stopped, and automatic restart is disabled. The source remains accessible on the same trusted Linux host. Export the original canonical absolute QWEN_HOME in the private maintenance and registration commands as well as the Broker/Harness environment, with no symlink components. fileHistoryRoot must equal the canonical $QWEN_HOME/file-history directory. Preserve that home and its independent history volume; do not move it with the Workspace.

The current baseline includes the Workspace migration schema. Earlier development catalogs require fresh disposable fixtures; do not edit Flyway history to reuse them.

The private artifact is qwen-managed-agent-server-0.1.0-alpha-workspace-migration.jar; the reference distribution runs the same entry as bin/qwen-managed-agent-admin workspace-migration. Set W1_JDBC_URL, W1_JDBC_USER, W1_JDBC_PASSWORD, W1_RUNTIME_CREDENTIAL_KEY_ID, and W1_RUNTIME_CREDENTIAL_KEY to the original deployment database and Broker credential key. The full request file contains version (the JSON integer 1), migrationOperationId, tenantId, storageId, fenceOperationId, captureOperationId, mountRevision, sourceRoot, targetRoot, bundleRoot, fileHistoryRoot, stateDirectory, nodeExecutable, and cliEntry. Fence admission is storage-scoped for bound Sessions; unbound legacy Sessions are outside that ownership. Metadata transactions share the tenant placement lock, so other storages of the same tenant may wait until those transactions finish; file scans and physical retirement hold no such lock. Paths must be canonical absolute deployment paths; roots and the durable Runtime state directory cannot overlap. IDs must be distinct UUIDs. Keep this exact request file for retries.

Before starting a new operation, the original Runtime state directory and retained history directory must exist at canonical paths, and the unchanged Linux identity reader must prove the history volume, including unambiguous birth time. Run maintenance as the original service user; the Runtime state directory must belong to that UID with exact POSIX 0700 permissions, checked by the same durable provider validator without creating or changing it. Failure returns migration_state_unavailable or migration_history_unverified before creating a migration row/fence or retiring placements. The target copy is still prepared after retirement. Run java -jar <migration.jar> retire <request.json> --offline-confirmed first. Then use the existing registration command to fence the original revision with the request's fence ID, and capture the W1b bundle with the request's capture ID. Prepare the target Workspace through the external offline copy procedure, preserving modes and the copied source marker. Run prepare and then promote with the same arguments. The first prepare and every new promote attempt verify sealed content, live source, target, retained history and original physical identities. Replaying prepare after PREPARED or any completed operation returns the saved receipt without rescanning; use promote for fresh transition verification. inspect <request.json> reads progress and the original receipt. abort <request.json> --offline-confirmed requires all placements retired and W1a still fenced; it does not restart anything or remove target artifacts. After abort or invalidation, prepare a fresh external target copy matching the new capture before starting a new operation; foreign marker or temporary files are rejected.

If the original history root has birth time equal to mtime, including when the first Session backup creates it, preflight conservatively returns migration_history_unverified. With all writers stopped, confirm the filesystem exposes a genuine persistent birth time, then update only the original history directory's mtime as the service user and retry retire with the same request:

touch -m -- "$QWEN_HOME/file-history"

Do not recreate or move the directory, change QWEN_HOME, or modify retained backups. Mtime is not an identity field; the root's device, inode and birth time must remain unchanged. A filesystem without a provable birth time remains unsupported after touch.

Promotion increments mount revision once. Successful prepare and promote commits clear the migration's previous error code. Update the deployment's Workspace root and restart Broker/Harness with the original QWEN_HOME before opening admission. An old deployment mapping fails closed. New file Turns and undo use fresh Runtime identities. Source rows, messages, journal, keys and backup names remain unchanged. Failure preserves the fence; missing stop proof, unsupported profiles or drift require diagnosis. Reverse migration is a new verified operation at a higher revision.

The target marker is the sole manifest exception and must match the copied source marker or the exact operation-pinned target marker. Do not hand-edit it. No online drain, directory copying, public migration route, Shell/MCP/Hook migration or source-lost recovery is provided. Uninitialized retained members without a verifiable frozen private definition are refused. Production Linux/MySQL acceptance evidence must be recorded separately from injected-identity tests.

Stored agent execution

Sessions pin a stored AgentDefinition revision and digest at admission. permission_policy and tools select the Session's immutable approval mode and hosted tool profile. model accepts {} or { "id": "configured-model" }; instructions accepts UTF-8 text up to 64 KiB. Static Skills and administrator-provisioned MCP/Hook pins are supported as described below. Environment templates and per-definition approval timeouts remain unsupported and are refused explicitly.

Set QWEN_MANAGED_AGENT_DEFINITION_MODELS to comma-separated IDs configured in the Harness's deployment modelProviders; it defaults to empty. Each ID must resolve to one configured provider route with deployment credentials. An absent or ambiguous route or unresolved credentials fails the Turn with model_unavailable before inference. Credentials never belong in definitions. Enable and configure the Managed Session Store for stored-definition execution; instructions are delivered as digest-addressed resource references and verified on load.

QWEN_MANAGED_AGENT_DEFINITION_TOOL_PROFILES defaults to hosted-workspace-files/1. Before opting into hosted-workspace-files/2, drain old workers and upgrade every provisioner according to #13166. Opting into hosted-workspace-files/3 needs the same drain and upgrade before its approval selection is enabled. Empty permission policies inherit the deployment approval mode (default yolo); use default for deployments that require approval.

skills accepts up to 16 static { "name": "review", "description": "Review changes", "body": "Read the diff and report concrete defects.", "base_directory": ".qwen/skills/review" } entries for a Workspace-bound tool profile. base_directory is optional and defaults to .; it is a canonical POSIX path relative to the Session's working directory, matching Runtime read_file and glob, never the Harness host. Absolute paths, traversal, empty or dot components, colons, backslashes and control characters are rejected. Names are unique and use letters, numbers, _, :, ., or - (at most 128 UTF-8 bytes); descriptions are nonblank and at most 4096 UTF-8 bytes, bodies are nonblank and at most 32768 bytes, directories are at most 4096 bytes, and the compact JSON catalog is at most 48 KiB. Invalid Unicode and extra Skill fields are rejected. Bodies grant no tool permissions and cannot register Hooks, override the model, or discover host-installed skills. The connector publishes the catalog as a digest-addressed managed-agent-skills resource; a replacement Harness validates and reads the original reference.

Public and WebShell Workspace Session creation also accept an optional skills array in the same static format. The Session catalog permits 256 entries, 512 KiB per body and 2 MiB compact JSON; AgentDefinition admission retains the smaller limits above. Both origins use the same managed-agent-skills resource kind, whose shared resource validators apply the 2-MiB bound; the smaller definition limits are enforced at admission. The array adds to the pinned AgentDefinition Skills (including for the built-in qwen-code agent); duplicate names or combined limits are rejected. The effective catalog is saved immutably with the creation receipt, and changing Skill content under the same idempotency key conflicts. Empty or omitted arrays preserve existing behavior. The WebShell uses the enabled Skills from its existing Skills management page; creation imports an immutable instruction snapshot from the explicitly selected trusted daemon Workspace. Upload and enable/disable remain on that page. Manual-only and user-hidden invocation flags are preserved; source asset directories, permission grants, model overrides and Hooks are not imported. This requires a durable Session Store and a Harness advertising session-skills/2; deploy compatible Java, SDK, Harness, and WebShell artifacts together. The existing Skills page owns discovery and installation; the Managed execution Runtime does not discover source directories implicitly.

mcp_servers accepts up to 16 unique { "server_id": "docs", "server_revision": 1, "definition_digest": "<64 lowercase hex characters>" } pins. Select an explicitly allowlisted hosted-workspace-mcp/1 or hosted-workspace-shell/1 tool profile in QWEN_MANAGED_AGENT_DEFINITION_TOOL_PROFILES. The legacy MCP profile requires pins and retains its no-Shell/no-backup contract. Ordinary shell/1 accepts optional pins and keeps Read/Write/Edit, foreground/background Shell, file backups and rewind on the same Session Runtime owner. Other profiles, foreground-only SSH and dedicated CSI resident Workspaces reject nonempty pins. Plan creation/change is explicitly unavailable for Agents with MCP pins; Session options do not advertise it. Static pins do not import daemon settings or enable configuration editing. The Runtime deployment owns the matching server manifest, endpoints, transport and credentials. hook_catalog similarly accepts { "catalog_id": "review", "catalog_revision": 1, "definition_digest": "<64 lowercase hex characters>" } for any Workspace-bound tool profile, selecting a Runtime-provisioned Hook catalog. Revisions are positive JavaScript-safe integers. Neither field accepts executable recipes or credentials. Create/update continues to store future configuration shapes without interpreting them; the limits and supported shapes above are enforced at Session admission. An old definition containing an unsupported shape remains rejected there.

Roll out the compatible Runtime manifest, Broker and Hosted Harness before admitting configured Sessions. The Harness must advertise workspace-shell-mcp/1 for ordinary Shell with MCP. Set QWEN_HOSTED_LIFECYCLE_V2_PROFILES to include hosted-workspace-shell/1 for that combination, or hosted-workspace-mcp/1 for the legacy profile, before public close/delete. Ordinary Shell with MCP requires the lifecycle v2 close path rather than direct Hosted DELETE. Preserve reliable Runtime stop support; configuration admission does not bypass these existing lifecycle gates. MCP/Hook load requests carry pins from the original admitted AgentDefinition revision, and Skills use the saved resource reference. Updating a definition affects new Sessions only. Unknown execution outcomes continue to require reconciliation of the original Runtime operation. Missing, corrupt or conflicting resources fail loading explicitly. Existing Sessions without extension fields keep their prior behavior for non-MCP profiles. The MCP profile requires nonempty server pins during create and attach/load validation. Older storage admission could retain an empty-pin MCP profile even though Hosted attachment already rejected it; audit stored definitions and Sessions before rollout rather than assuming none exist. Retain historical access separately and settle or close affected Sessions on the previous deployment before replacement. Publish a corrected definition revision for new Sessions; existing Session pins are not rewritten.

Session MCP management

Deploy matching Java, Java SDK, Broker, Runtime and WebShell artifacts. The Harness must advertise session-mcp-management/1, and QWEN_HOSTED_LIFECYCLE_V2_PROFILES must enable the Session's exact hosted-workspace-shell/1 or hosted-workspace-mcp/1 profile. The initial implementation uses ordinary local-process Workspace workers; foreground-only SSH, dedicated CSI resident profiles, read-only children and other tool profiles do not gain management. An ordinary Shell Session may add its first MCP server without being recreated.

Use the Session's Manage MCP entry or the MCP management page. Add or edit selects an exact server revision published in that tenant and Workspace's Runtime-private QWEN_MANAGED_MCP_CONFIG manifest. Remove, enable, disable, reload and restart apply to the current Session. The manifest remains deployment administration: this interface neither accepts arbitrary executable recipes nor imports daemon settings, credentials or OAuth state. Inventory exposes only the published identifier, revision, digest and transport. Keep historical manifest revisions available for existing Sessions.

Management reattaches only to a Session resident in the current Harness and never triggers cleanup, recovery or wake dispatch. After a Harness restart, continue or recover the Session through its normal execution flow first; management otherwise returns hosted_mcp_session_load_required. A new empty Session may initialize through management without sending a Turn. Command status never creates a Session, and uncertain creation never loads a cold journal implicitly. Cleanup-only recovery attachments also refuse management until a normal execution load upgrades them.

The original AgentDefinition and Skills stay pinned. Explicit management commands append independent Session MCP settings revisions; they do not change other Sessions or future defaults. Each snapshot retains at most 32 server identities including removed tombstones, with at most 16 enabled selections; the existing shared Runtime connection quota still applies. Removed and disabled selections survive Session reload. Direct detach remains governed by the existing lifecycle protocol. The Session retains its original owner and MCP history until ordered close, so Plan remains unavailable after MCP management even when every server is removed. File/Shell tools, approvals, backups and rewind retain their ordinary behavior. Restart drains the selected connection before reconnecting, without restarting a shared worker.

Public routes are GET /v1/agents/sessions/{sessionId}/mcp-management, POST /v1/agents/sessions/{sessionId}/mcp-management/commands with Idempotency-Key, and GET /v1/agents/sessions/{sessionId}/mcp-management/commands/{operationId}. WebShell has corresponding POST query, submit and operation-query routes under /api/agent/web-shell/v1/session-mcp/management/. Commands include action, serverId and expectedRevision; add/edit also include the exact selected server pin. Management requires Workspace execution permission and a public active Session. The settings commit rechecks idle/Plan/lifecycle admission atomically; a static settings revision or catalog is not proof of a healthy connection.

An unconfirmed operation keeps its original identity. Status queries are read-only; explicit retry first queries that original operation, then resumes the saved original command only while it remains unsettled. The UI can retain unconfirmed public command metadata across a tab reload when the provider has an explicit tenant-and-actor productScope; otherwise it retains it only in memory. Neither mode stores executable recipes or credentials. Unknown physical outcomes block replacement rather than replaying on another Runtime. See the complete English design and Chinese design for ownership, authorization and qualification boundaries.

Shell lifecycle handoff

Initial v2 close/delete admission preserves an already-live writer for one configured Session Store writer-lease duration, measured using database time. Ordinary renewal and writes remain fenced; idempotent replay, failed resubmission and claim retries never refresh the allowance. Effects still requires a valid lease. A delivery or child cascade beyond this finite handoff can still require recovery; expired writers are not revived. See the lifecycle design (简体中文).