docs: record verified Python 0.4.0a1 publication

.agents/README.md

@@ -1,8 +1,12 @@
 # `.agents/` — engineering record of the python-sdk repository
 
+## Published specification 5 alpha — 2026-10-25
+
+Client/server **0.4.0a1** are public. [Release verification](evidence/verify/2026-10-25-python-040a1-public-release.md) records immutable tag identity, required CI, four public artifact hashes matched to the preserved candidate, and fresh exact-version installation. The [public catalog integration](evidence/verify/2026-10-25-python-public-catalog-base.md) verifies the released SDK against the live specification 5 base manifest. This host release does not update existing sandbox images or imply whole-catalog production certification.
+
 ## Specification 5 migration — 2026-10-25
 
-The [unified startup proposal](notes/proposed/architecture/2026-10-25-unified-template-launch.md)
+The [implemented unified startup design](notes/implemented/architecture/2026-10-25-unified-template-launch.md)
 removes workflow selection and preserves all template services. The
 [contract foundation](evidence/verify/2026-10-25-unified-template-contract.md) records
 local shared-vector checks only. [Runtime checkpoint](evidence/verify/2026-10-25-unified-template-runtime.md) records

.agents/evidence/verify/2026-10-25-python-040a1-public-release.md

@@ -0,0 +1,78 @@
+# Verification: public Python 0.4.0a1 pair
+
+- Date: 2026-10-25
+- Implementation: https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/108
+- Source and immutable tag: `11e7e93486f852edd1fe23366c52936058d9d446`, `v0.4.0a1`.
+- Result: PASS — both alpha distributions are public and independently installed.
+
+## Publication gates
+
+The final PR head `97888a7a8008053ecef2eb252324a0e8fa165dd6` passed all 11 checks.
+The PR was merged with that expected head, and the actual merge SHA was confirmed.
+[Main CI](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40179926574)
+passed all 10 jobs before the new matching tag and
+[GitHub prerelease](https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a1)
+were created. Neither an existing tag nor a public version was replaced.
+
+[Publication run 40180399513](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40180399513)
+passed on its first attempt: complete tag CI, paired build, artifact checks and
+preservation, existing-public-file preflight, server upload, client upload, public
+file verification and fresh installation. No upload or readback failure occurred
+in this publication run. The configured repository credential remained in Actions;
+its value was not copied into the workspace or written to evidence.
+
+## Independent public readback
+
+Both exact-version PyPI JSON responses contained one wheel and one sdist. Each was
+downloaded independently, hashed, and compared against both the public SHA-256 and
+the exact `python-release-candidate` artifact preserved by the successful workflow.
+All four comparisons passed:
+
+| Public file | SHA-256 |
+| --- | --- |
+| `agent_sandbox_server-0.4.0a1-py3-none-any.whl` | `475422904a2f8f11a883ceefc02e5acd2bbfbe9c83ee2b9e7d0d04fec4982473` |
+| `agent_sandbox_server-0.4.0a1.tar.gz` | `2ad964bf12c28ee60f2fab46f7ae73c2d582d2b2b5978f51767ed6a3d4d3b461` |
+| `agent_sandbox_client-0.4.0a1-py3-none-any.whl` | `1db89a5ba669bb52d51844a07cc2180e13df790b215833f2db758114fb9a8eb2` |
+| `agent_sandbox_client-0.4.0a1.tar.gz` | `335c10dcddb759c2f9e54294daabf0944171b39a28c1d12ae9dc0e6444533b71` |
+
+To reproduce: fetch `https://pypi.org/pypi/<distribution>/0.4.0a1/json` for
+`agent-sandbox-server` and `agent-sandbox-client`; download each `urls` entry; compare
+`hashlib.sha256(content).hexdigest()` with `digests.sha256`. Download the preserved
+candidate from the linked publication run and compare the same filenames and hashes.
+
+## Fresh public installation
+
+From outside the source checkout, create a new virtual environment and run:
+
+```sh
+python -m pip install --no-cache-dir --index-url https://pypi.org/simple 'agent-sandbox-client==0.4.0a1'
+python -m pip check
+python -c "from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))"
+python -c 'from agent_sandbox.api import launch_template, TemplateSession, TemplateLaunchError; from agent_sandbox.server import start'
+```
+
+The independent check used Python 3.13.13. Installation and `pip check` exited 0;
+both installed versions were 0.4.0a1, the client automatically required the exact
+matching server, and module loading came from the new environment's `site-packages`.
+The new template API and existing standard sync/async/Provider creation exports
+imported successfully. The installed `launch_template` signature has no
+`workflow_id`, and its packaged validator accepted a specification 5 native `base`
+manifest. These are installed-distribution checks, not a new cloud acceptance claim.
+
+## Scope and retained limitations
+
+The previously recorded five real unified-template startup cases, original full
+CLI pass, additional unexplained CLI failure, and focused successful file check
+remain separate in the [runtime diagnostic evidence](2026-10-25-unified-template-cli-diagnostic.md).
+https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109 remains open; this
+release does not invent a cause or erase the failure. Local environment-intercepted
+test failures also remain recorded in earlier evidence.
+
+The release is alpha. It does not certify all providers, every template operation,
+or production readiness. Installing this host package does not update runtime
+packages inside existing images. The public catalog/CLI cutover is coordinated in
+their owner repositories; no catalog-dependent cloud experiment was run during
+this documentation follow-up.
+
+Documentation-only verification: repository health 106 passes / 1 warning / 0
+failures, hygiene and whitespace checks passed. Historical evidence was preserved.

.agents/evidence/verify/2026-10-25-python-public-catalog-base.md

@@ -0,0 +1,92 @@
+# Verification: released SDK and public catalog base manifest
+
+- Date: 2026-10-25
+- Result: PASS — one owned sandbox, expected output, independently confirmed absence.
+- SDK: public PyPI client/server 0.4.0a1, freshly installed outside the source checkout.
+- Catalog: <https://registry.agent-sandbox.cn/catalog.json>, schema 3.
+- TTL requested: 300 seconds.
+
+## Input and boundary
+
+The catalog response identified templates `45eb6c4`, CLI `408e618`, Python SDK
+`11e7e93`, providers `48f0910`, Node SDK `f473f7d` and Registry `7986493`. Its fetched
+bytes had SHA-256 `ffd21eb7058f35137fed1125dae4268a360e5d2ebc427fa78c2021baa9c297ac`.
+The base entry's published manifest digest was
+`sha256:8fcb10e223a4e592d3f4fa44069dcc966eeb91799cd768ce106470368f7acdd9`.
+
+The test selected the public catalog's `base` entry for `alicloud-express` and passed
+its complete `manifest` mapping unchanged to `launch_template`. That manifest declares
+specification 5, `template_id: base` and an empty `provides` map. No local substitute,
+source checkout, manifest override or catalog cache was used.
+
+An earlier local invocation of `launch_template('base', ...)` returned
+`FileNotFoundError` for `base` before creating any resource. This was an incorrect
+test assumption: Python's documented string input is a local YAML path; bare-name
+catalog resolution belongs to the CLI. The corrected experiment explicitly resolves
+the public catalog manifest before calling Python. This observation is retained as
+an input-contract boundary, not classified as a product defect or a successful cloud test.
+No new registry resolver or patch release was introduced.
+
+## Result
+
+Elapsed times below start immediately before launch, after fetching the catalog:
+
+| Operation | Elapsed | Result |
+| --- | --- | --- |
+| `launch_template(manifest, provider='alicloud-express', timeout=300)` | 1.070 s | PASS; zero declared application services, as specified by base. |
+| `session.sandbox.commands.run('printf 42', timeout=30)` | 1.463 s | PASS; exit 0, stdout exactly `42`. |
+| `session.close()` in `finally` | 1.647 s | PASS. |
+| Independent `ProviderSandbox.get_info_by_id` | 1.984 s | PASS; `SandboxNotFoundError` confirms owned resource absent. |
+
+The complete scenario took 2.049 seconds. The run journal ended with
+`cleanup-intent`, `deleted`, `cleanup-complete`. Only one sandbox was created;
+no full CLI acceptance suite or template matrix was rerun. No interpreter API,
+application health/discovery or arbitrary service behavior is claimed by this
+base shell-operation check.
+
+## Reproduce
+
+Use the exact public installation from the
+[release record](2026-10-25-python-040a1-public-release.md) and configure the Express
+account through `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`.
+Then run outside the source checkout:
+
+```python
+import asyncio
+import json
+import urllib.request
+
+from agent_sandbox import ProviderSandbox
+from agent_sandbox.api import launch_template
+from agent_sandbox.models.errors import SandboxNotFoundError
+
+with urllib.request.urlopen("https://registry.agent-sandbox.cn/catalog.json") as response:
+    catalog = json.load(response)
+assert catalog["schema"] == 3
+entry = next(row for row in catalog["templates"]
+             if row["name"] == "base" and row.get("native_provider") == "alicloud-express")
+manifest = entry["manifest"]
+assert manifest["spec_version"] == 5
+
+async def main():
+    session = await launch_template(manifest, provider="alicloud-express", timeout=300)
+    sandbox_id = session.sandbox.id
+    try:
+        result = await session.sandbox.commands.run("printf 42", timeout=30)
+        assert result.exit_code == 0 and result.stdout == "42"
+    finally:
+        await session.close()
+        try:
+            await ProviderSandbox.get_info_by_id(sandbox_id, provider="alicloud-express")
+        except SandboxNotFoundError:
+            pass
+        else:
+            raise AssertionError("Owned sandbox still exists")
+
+asyncio.run(main())
+```
+
+The public catalog can advance; record its revision metadata and response digest
+when reproducing. The earlier CLI diagnostic limitation remains independently
+tracked in https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109. This
+narrow success does not erase that historical result.

.agents/notes/proposed/architecture/2026-10-25-unified-template-launch.md → .agents/notes/implemented/architecture/2026-10-25-unified-template-launch.md

@@ -1,6 +1,6 @@
 # Decision: Launch a complete template without workflow selection
 
-Status: proposed
+Status: implemented
 
 ## Problem
 
@@ -18,7 +18,9 @@ remain immutable historical inputs and do not certify specification 5 launches.
 
 `launch_template(manifest, provider=..., reference=...)` starts a previously prepared
 reference, checks SandboxServer protocol v2 services and returns all declared endpoints. Python does
-not acquire source building. The static planner returns `supported`, required/missing
+not acquire source building or bare-name catalog resolution: the input is a manifest
+mapping or local YAML path. Catalog callers resolve a manifest before launching it.
+The static planner returns `supported`, required/missing
 operations, all services and an optional unsupported-combination reason.
 
 ## Alternatives considered
@@ -40,6 +42,11 @@ and real provider startup/cleanup. Five new startup scenarios passed; all 11 che
 for implementation head `66c86f2` passed. The separate CLI acceptance rerun has an
 unconfirmed file-transfer failure tracked in
 https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/109.
+The final PR, merged main and release-tag CI passed; client/server 0.4.0a1 were
+published and independently installed. The public v3 catalog base manifest passed
+launch, exec and independently confirmed cleanup through that installed release.
+See [publication](../../../evidence/verify/2026-10-25-python-040a1-public-release.md)
+and [public catalog integration](../../../evidence/verify/2026-10-25-python-public-catalog-base.md).
 
 ## Acceptance criteria
 

CHANGELOG.md

@@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [0.4.0a1] - 2026-10-25
 
-Candidate: not yet published.
+Published alpha pair: [v0.4.0a1](https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a1). Both distributions use the same version; see [publication verification](.agents/evidence/verify/2026-10-25-python-040a1-public-release.md).
 
 ### Changed