Refresh agent-compose examples and real-daemon coverage

examples/agent-compose/README.md

@@ -11,18 +11,30 @@ simplest to most complete.
 | [docker-scheduler-cron](docker-scheduler-cron/) | Managed cron scheduler control plane. | No, for `config`/`up`/`ps`/`down` |
 | [docker-scheduler-script-url](docker-scheduler-script-url/) | A scheduler script loaded from a relative file URL source. | No, for `config`/`up`/`ps`/`down` |
 | [docker-scheduler-timeout](docker-scheduler-timeout/) | End-to-end scheduled run that fires, executes the agent, and persists logs. | Yes, for the scheduled run |
+| [docker-workspace-lifecycle](docker-workspace-lifecycle/) | Local workspace copy plus sandbox stop, resume, exec, and removal. | No |
+| [docker-multi-agent](docker-multi-agent/) | Two independent agents using the same workspace source. | No for command runs; yes for prompts |
+| [docker-env-secrets](docker-env-secrets/) | Dotenv, project/agent variables, and secret redaction. | No |
+| [docker-volume-persistence](docker-volume-persistence/) | Managed volumes and read-only bind mounts. | No |
+| [docker-build](docker-build/) | Build and run a guest-derived Docker image. | No |
+| [docker-scheduler-script-runtime](docker-scheduler-script-runtime/) | Inline QJS, persisted scheduler state, and shell callbacks. | No |
+| [boxlite-minimal](boxlite-minimal/) | Minimal BoxLite configuration template. | Only for prompt runs |
+| [microsandbox-minimal](microsandbox-minimal/) | Minimal Microsandbox configuration template. | Only for prompt runs |
 
 ## Common prerequisites
 
 - Docker daemon is running.
 - The `agent-compose` daemon is already running.
-- The `agent-compose-guest:latest` image exists locally.
+- Docker can access `ghcr.io/chaitin/agent-compose-guest:latest`.
 
-From the repository root, build the guest image if needed:
+Pull the image used by the examples if needed:
 
 ```bash
-task image:agent-compose-guest
+docker pull ghcr.io/chaitin/agent-compose-guest:latest
 ```
 
 Each example has its own `README.md` with the exact commands and expected
 output.
+
+Running the BoxLite and Microsandbox examples additionally requires Linux, KVM
+access, their runtime artifacts, and a binary that includes the selected
+compiled driver.

examples/agent-compose/README.zh-CN.md

@@ -10,17 +10,28 @@
 | [docker-scheduler-cron](docker-scheduler-cron/) | managed cron scheduler 的控制面流程。 | `config`/`up`/`ps`/`down` 不需要 |
 | [docker-scheduler-script-url](docker-scheduler-script-url/) | 从相对文件 URL 来源加载 scheduler 脚本。 | `config`/`up`/`ps`/`down` 不需要 |
 | [docker-scheduler-timeout](docker-scheduler-timeout/) | 端到端的定时运行：触发、执行 agent 并持久化日志。 | 定时运行需要 |
+| [docker-workspace-lifecycle](docker-workspace-lifecycle/) | 本地 workspace 副本及 sandbox stop、resume、exec、rm。 | 不需要 |
+| [docker-multi-agent](docker-multi-agent/) | 两个独立 agent 使用同一 workspace source。 | command 不需要；prompt 需要 |
+| [docker-env-secrets](docker-env-secrets/) | Dotenv、project/agent variables 和 secret 隐藏。 | 不需要 |
+| [docker-volume-persistence](docker-volume-persistence/) | 托管 volume 和只读 bind mount。 | 不需要 |
+| [docker-build](docker-build/) | 构建并运行基于 guest 的 Docker 镜像。 | 不需要 |
+| [docker-scheduler-script-runtime](docker-scheduler-script-runtime/) | Inline QJS、持久 scheduler state 和 shell callback。 | 不需要 |
+| [boxlite-minimal](boxlite-minimal/) | 最小 BoxLite 配置模板。 | prompt run 需要 |
+| [microsandbox-minimal](microsandbox-minimal/) | 最小 Microsandbox 配置模板。 | prompt run 需要 |
 
 ## 通用前置条件
 
 - Docker daemon 正在运行。
 - `agent-compose` daemon 已经启动。
-- 本地存在 `agent-compose-guest:latest` 镜像。
+- Docker 能访问 `ghcr.io/chaitin/agent-compose-guest:latest`。
 
-如需构建 guest 镜像，在仓库根目录执行：
+如需获取示例使用的镜像，执行：
 
 ```bash
-task image:agent-compose-guest
+docker pull ghcr.io/chaitin/agent-compose-guest:latest
 ```
 
 每个示例都有自己的 `README.md`，包含完整命令和预期输出。
+
+运行 BoxLite 和 Microsandbox 示例还要求 Linux、KVM 权限、对应 runtime
+artifacts，以及包含所选 compiled driver 的二进制。

examples/agent-compose/boxlite-minimal/README.md

@@ -0,0 +1,59 @@
+# Minimal BoxLite project
+
+Languages: English | [中文](README.zh-CN.md)
+
+This example defines a single Codex agent backed by the BoxLite driver.
+
+## Requirements
+
+Runtime use requires Linux, KVM access, BoxLite artifacts, and a binary whose
+`compiled_drivers` contains `boxlite`. Check the binary before applying:
+
+```bash
+agent-compose --json version
+test -r /dev/kvm && test -w /dev/kvm
+```
+
+## Inspect the configuration
+
+```bash
+agent-compose config
+```
+
+The normalized output should contain `driver.name: boxlite`.
+
+## Run on a BoxLite host
+
+After the requirements above are satisfied:
+
+```bash
+agent-compose up
+agent-compose run reviewer --command "uname -a"
+agent-compose ps --all
+agent-compose down
+```
+
+`run` should return `status: succeeded`, a non-empty sandbox ID, and the guest
+kernel information. If the binary does not include BoxLite, the command reports
+the driver as unsupported. Missing KVM access or runtime artifacts cause
+BoxLite initialization to fail.
+
+## Normalized config output
+
+`agent-compose config` produces:
+
+```yaml
+name: boxlite-minimal
+agents:
+    - name: reviewer
+      provider: codex
+      image: ghcr.io/chaitin/agent-compose-guest:latest
+      driver:
+        name: boxlite
+        boxlite: {}
+network:
+    mode: default
+```
+
+This output confirms that the project selects BoxLite. Runtime output depends
+on the BoxLite artifacts and KVM environment on the host.

examples/agent-compose/boxlite-minimal/README.zh-CN.md

@@ -0,0 +1,58 @@
+# 最小 BoxLite project
+
+语言：[English](README.md) | 中文
+
+本示例定义一个使用 BoxLite driver 的 Codex agent。
+
+## 环境要求
+
+实际运行要求 Linux、KVM 权限、BoxLite artifacts，以及 `compiled_drivers` 包含
+`boxlite` 的二进制。应用前检查：
+
+```bash
+agent-compose --json version
+test -r /dev/kvm && test -w /dev/kvm
+```
+
+## 查看配置
+
+```bash
+agent-compose config
+```
+
+归一化输出应包含 `driver.name: boxlite`。
+
+## 在 BoxLite host 上运行
+
+满足上述环境要求后执行：
+
+```bash
+agent-compose up
+agent-compose run reviewer --command "uname -a"
+agent-compose ps --all
+agent-compose down
+```
+
+`run` 应返回 `status: succeeded`、非空 sandbox ID 和 guest kernel 信息。如果二进制
+未包含 BoxLite，命令会报告 driver 不受支持；缺少 KVM 权限或 runtime artifacts
+会导致 BoxLite 初始化失败。
+
+## Config 归一化输出
+
+`agent-compose config` 输出如下：
+
+```yaml
+name: boxlite-minimal
+agents:
+    - name: reviewer
+      provider: codex
+      image: ghcr.io/chaitin/agent-compose-guest:latest
+      driver:
+        name: boxlite
+        boxlite: {}
+network:
+    mode: default
+```
+
+该输出表明 project 已选择 BoxLite；runtime 输出取决于 host 上的 BoxLite artifacts
+和 KVM 环境。

examples/agent-compose/boxlite-minimal/agent-compose.yml

@@ -0,0 +1,8 @@
+name: boxlite-minimal
+
+agents:
+  reviewer:
+    provider: codex
+    image: ghcr.io/chaitin/agent-compose-guest:latest
+    driver:
+      boxlite: {}

examples/agent-compose/docker-build/Dockerfile

@@ -0,0 +1,4 @@
+ARG BASE_IMAGE=ghcr.io/chaitin/agent-compose-guest:latest
+FROM ${BASE_IMAGE}
+ARG EXAMPLE_MARKER=built-by-agent-compose
+RUN printf '%s\n' "${EXAMPLE_MARKER}" > /opt/agent-compose-example.txt

examples/agent-compose/docker-build/README.md

@@ -0,0 +1,49 @@
+# Build a Docker guest image
+
+Languages: English | [中文](README.zh-CN.md)
+
+This example builds a guest-derived image and verifies a build argument marker.
+
+## Prerequisites and configuration
+
+Docker and the daemon must be running, and Docker must be able to obtain the
+published guest base image. `build.context` is this directory, `dockerfile`
+selects `Dockerfile`, `args` supplies the marker, and `tags` adds a second local
+tag to the primary `image` reference.
+
+## Run the example
+From this example directory:
+
+```bash
+agent-compose build
+agent-compose up
+agent-compose run worker --command "cat /opt/agent-compose-example.txt"
+agent-compose down
+agent-compose rmi agent-compose-example-build:latest --force
+agent-compose rmi agent-compose-example-build:local --force
+```
+
+The expected marker is `built-by-agent-compose`. The build requires Docker and
+access to the published guest base image. The example uses fixed local tags for
+clarity; automation should copy the example and substitute unique tags.
+
+## Expected result
+
+`build` must complete and create both local tags. The worker command reads the
+file written during the image build and must print `built-by-agent-compose`.
+After `down`, both `rmi` commands remove the tutorial images. Avoid these fixed
+tags in concurrent automation; use a unique tag for each build.
+
+## Example output
+
+A successful image build and guest run produces output like:
+
+```console
+status=succeeded
+run=a023773553771e0be8d51fb1a983c37e66c2712697b37e9119be7ba4ccc04ef8
+sandbox=78459590803602e1945bdac9e3c74a1d9a656c29f57b6169bab757d1779b1d7e
+built-by-agent-compose
+```
+
+Generated run and sandbox IDs differ. Concurrent automation should substitute
+a unique image tag.

examples/agent-compose/docker-build/README.zh-CN.md

@@ -0,0 +1,45 @@
+# 构建 Docker guest image
+
+语言：[English](README.md) | 中文
+
+该示例构建一个基于 guest image 的本地镜像，并验证 build argument marker。
+
+## 前置条件与配置
+
+Docker 和 daemon 必须已启动，Docker 还需能获得发布版 guest 基础镜像。
+`build.context` 指向本目录，`dockerfile` 选择 Dockerfile，`args` 提供 marker，
+`tags` 为主 `image` 引用增加第二个本地 tag。
+
+## 运行示例
+在示例目录中执行：
+
+```bash
+agent-compose build
+agent-compose up
+agent-compose run worker --command "cat /opt/agent-compose-example.txt"
+agent-compose down
+agent-compose rmi agent-compose-example-build:latest --force
+agent-compose rmi agent-compose-example-build:local --force
+```
+
+预期 marker 为 `built-by-agent-compose`。构建需要 Docker 能访问发布版 guest base
+image。示例使用固定 tag 以便阅读；自动化测试应复制示例并替换成唯一 tag。
+
+## 预期结果
+
+`build` 必须完成并创建两个本地 tag。worker 命令读取镜像构建阶段写入的文件，输出
+必须为 `built-by-agent-compose`。`down` 后两个 `rmi` 命令删除教程镜像。并发自动化
+不要复用这些固定 tag；每次 build 应使用唯一 tag。
+
+## 输出示例
+
+镜像构建和 guest run 成功后，输出示例如下：
+
+```console
+status=succeeded
+run=a023773553771e0be8d51fb1a983c37e66c2712697b37e9119be7ba4ccc04ef8
+sandbox=78459590803602e1945bdac9e3c74a1d9a656c29f57b6169bab757d1779b1d7e
+built-by-agent-compose
+```
+
+动态 run 和 sandbox ID 会不同；并发自动化应替换为唯一 image tag。

examples/agent-compose/docker-build/agent-compose.yml

@@ -0,0 +1,15 @@
+name: docker-build
+
+agents:
+  worker:
+    provider: codex
+    image: agent-compose-example-build:local
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        EXAMPLE_MARKER: built-by-agent-compose
+      tags:
+        - agent-compose-example-build:latest
+    driver:
+      docker: {}

examples/agent-compose/docker-env-secrets/README.md

@@ -0,0 +1,53 @@
+# Project environment and secrets
+
+Languages: English | [中文](README.zh-CN.md)
+
+This example uses an explicit dotenv file, project variables, agent-specific
+environment, and secret metadata. The committed value is intentionally fake.
+
+## Prerequisites and configuration
+
+Docker and the daemon must be running. `env_file: example.env` supplies
+`EXAMPLE_SECRET`; project `variables` apply to every agent, while `agents.*.env`
+is agent-scoped. `secret: true` marks values for redaction in rendered config.
+
+## Run the example
+From this example directory:
+
+```bash
+agent-compose config
+agent-compose up
+agent-compose run inspector --command '
+  test "$PROJECT_VALUE" = project-level &&
+  test "$AGENT_VALUE" = agent-level &&
+  test "$PROJECT_SECRET" = safe-example-secret &&
+  test "$AGENT_SECRET" = safe-example-secret &&
+  echo "environment ok"
+'
+agent-compose down
+```
+
+`config` redacts values marked `secret: true`. Project variables are supplied to
+runs, while agent env is scoped to that agent. Process environment values passed
+to the CLI take precedence over `example.env`.
+
+## Expected result
+
+Before `up`, confirm `agent-compose config` contains `********` and never prints
+`safe-example-secret`. The command run must print `environment ok`, proving the
+real guest received both scopes. The value is a non-sensitive fixture; do not
+commit production secrets or use this pattern as a secret manager.
+
+## Example output
+
+A successful environment check produces output like:
+
+```console
+status=succeeded
+run=f1d22000463b950c2251f72c77477d42fbe9a39b2663bbce39b0b20c04be05e8
+sandbox=9fffd2978773c87708dc46facb8bf5ba8b1edf275382afb56380b0294a497939
+environment ok
+```
+
+Rendered config must contain `********` and must not contain the fixture
+secret. Generated IDs will differ.