docs: consolidate runtime candidate code and revised OpenSpec

Combine candidate code at 6c590c3 with the revised OpenSpec documents from 36fa750 on fix/runtime-integration-hardening.

Preserve the candidate src tree and build/CI configuration. Update AGENTS.md and review.md to record the combined delivery, current version-branch snapshots and verification boundaries.

Local structural checks: 14 documents, 6 capability specs, 28 requirements, 60 scenarios and 43 unchecked implementation tasks. Original document tree verified against GitHub; updated document tree matches the prepared content.

No product-code changes, task completion claims, feature-branch updates or releases. OpenSpec CLI validation and local Java/OpenCode tests were not run; CI must be checked against this new commit.

Author: loong10k

openspec/AGENTS.md

@@ -0,0 +1,20 @@
+# OpenSpec 工作约定
+
+本仓库采用 `spec-driven`：proposal → specs → design → tasks → review → implementation → verification → archive。
+OpenSpec 的工件依赖判断只证明文件是否齐备，不代表用户批准；本项目另外使用 change 中的 `review.md` 记录批准状态。
+
+## 执行门禁
+
+1. 读取 `config.yaml`、目标 change 全部工件和相关主规范；没有主规范时不得凭空使用 MODIFIED。
+2. 将可观察契约写入 `specs/<capability>/spec.md`，技术选择写入 design，任务和验证写入 tasks。
+3. 在项目目录执行 `openspec validate <change-id> --strict`，保存工具版本、命令、退出码与完整输出；失败或未执行都不是通过。
+4. 用户明确批准书面范围与计划后才能进入实现。此前只允许只读调查和文档修改。
+5. 已有提前实现的代码保留在原分支，逐条映射规范、补失败用例并复验；不能通过倒填勾选框追认完成。
+6. 三条兼容线分别记录提交和测试证据。只允许 Java/Jackson/构建适配差异，不允许悄悄删功能。
+7. 所有实现与验证门禁满足后，再同步主规范并归档。不得将提案直接复制成“已经实现”的主规范。
+
+## 本轮状态
+
+当前 change：`harden-opencode-runtime-integration`。
+按用户“提交代码文档，推送 github”的交付要求，修订后的 OpenSpec 文档与已有候选代码汇总到 `fix/runtime-integration-hardening`。纯文档分支保留原评审快照；不强推、不回滚、不合并到 main 或三条 feature 分支。交付汇总不代表规范审批、实现完成或三分支验收通过。
+正式 CLI 校验或运行测试受环境限制时，准确记录 `NOT_RUN` 和原因，保留未勾选任务。

openspec/changes/harden-opencode-runtime-integration/design.md

@@ -0,0 +1,52 @@
+# 源码基线、出处与修订说明
+
+核对日期：2026-09-20。以下是本次读取时的快照，分支后续可能移动。
+
+## 仓库锚点
+
+仓库：https://github.com/easy-4-java/opencode-java-sdk
+
+| 分支 | 固定提交 | 本轮用途 |
+|---|---|---|
+| feature/1.0.x | 05702c10fc2533c9dfb4f58be2b97f1247a4c9b3 | 兼容契约参照；JDK 基线冲突未解决 |
+| feature/2.0.x | 13f68b1b506dfb0aa274d388f7f5a028d340b67b | Java 17/Jackson 2 兼容线参照 |
+| feature/3.0.x | 99974efc311ba8c0aabad8c9471ed803d155e534 | 本次纯文档分支基线 |
+| fix/runtime-integration-hardening | 6c590c3a9af2a595d729cb6e50b1fd6d3458459e | 已有草稿与提前实现的来源，不纳入本次代码变更 |
+
+比较最后两项：实现分支领先 34 个提交，净变更 29 个文件，其中 OpenSpec 文档 11 个、主代码 11 个、测试 7 个。这是文件/提交差异统计，不是已完成能力或测试通过数量。
+原始源码树：b778e00248132beda29e73138df454204b5e6209。
+原草稿 openspec 树：cd382f6f06f399e03a5b191a2f3f28913a68e774。
+
+## 已有实现的核验范围
+
+主代码：OpenCodeCliConfig、OpenCodeChatClient、OpenCodeSseClient、OpenCodeConfig、OpenCodeServerConfig、SseSubscription、OpenCodeCliExecutionContext、OpenCodeCliExecutor、OpenCodeCliResult、OpenCodeCliStreamHandle、OpenCodeRunOptions。
+测试：OpenCodeChatClientStreamingContractTest、OpenCodeSseReadinessContractTest、OpenCodeConfigContractTest、OpenCodeCliExecutorRuntimeContractTest、OpenCodeCliStreamingContractTest、OpenCodeCliTest、OpenCodeRunOptionsContractTest。
+这些文件只证明改动存在。本轮没有运行它们，也没有把它们带入文档分支。
+
+## 原草稿问题及本稿处理
+
+1. 只有 changes，没有对应主 specs；cli-contract、chat-streaming、configuration-model 却使用 MODIFIED。本稿保留同一个 change id，六项首次纳管契约统一声明 New/ADDED。
+2. contract-verification 的跨分支 Requirement 没有 Scenario。本稿为每条 Requirement 补齐可观察 WHEN/THEN 场景。
+3. config.yaml 原有 project/conventions 自定义键不能代替官方文档约定的 context/rules 注入。本稿改用 schema/context/rules；不声称已运行官方验证证明旧 YAML 被拒绝。
+4. 原任务缺少明确书面批准门禁，部分项没有自己的验证方法。本稿加入 review.md、逐项需求编号和验收证据，所有任务保持未勾选。
+5. 原稿部分决策仍是二选一。本稿明确首版 managed 要求固定端口、share 迁移规则、默认资源策略；这些设计仍待用户批准。
+
+## 外部参考
+
+- 用户参考 CLI：https://open-code.ai/en/docs/cli
+- 用户参考 Web：https://open-code.ai/en/docs/web
+- 上游 CLI：https://opencode.ai/docs/cli/
+- 上游 Web：https://opencode.ai/docs/web/
+- 目标版本 run 解析器：https://github.com/anomalyco/opencode/blob/v1.17.18/packages/opencode/src/cli/cmd/run.ts
+- 目标版本事件类型：https://github.com/anomalyco/opencode/blob/v1.17.18/packages/sdk/js/src/v2/gen/types.gen.ts
+- OpenSpec 工作流 schema：https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml
+- OpenSpec 配置说明：https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md
+- OpenSpec 规范约定：https://github.com/Fission-AI/OpenSpec/blob/main/openspec/specs/openspec-conventions/spec.md
+
+网页与 main 文档会变化；实施时记录读取版本和二进制摘要。当前 v1.17.18 是候选固定契约基线，不是已运行认证结果。
+
+## 证据边界
+
+已做：GitHub 分支/树/文件/差异读取；形成纯文档评审稿。
+未做：本机 CodeGraph、Java 构建、真实 OpenCode、OpenSpec 官方 CLI 严格校验、漏洞/泄漏动态验证。
+环境探测：node/npm/git 可用，openspec 未安装；npm registry DNS 解析失败。不得用自写检查替代官方校验或行为测试。

openspec/changes/harden-opencode-runtime-integration/evidence.md

@@ -1,43 +1,50 @@
-## Why
+# OpenCode 运行时集成加固提案
 
-The SDK already exposes broad OpenCode HTTP, SSE and CLI coverage, but several integration contracts are incomplete or inconsistent with OpenCode v1.17.18. The most important gaps are no longer missing command wrappers: they are incorrect CLI option modeling, fragile streaming semantics, lack of bounded and isolated CLI execution, and treating long-running Web/Serve/ACP processes as ordinary blocking commands.
+## Why
 
-This change hardens the SDK so Java applications can embed OpenCode reliably rather than only invoke it as a thin command wrapper.
+已有 SDK 命令入口较多，但原始基线存在参数契约、流式事件处理、子进程管理和配置往返的缺口。此次先将这些行为写成可评审、可测试的 OpenSpec，再决定实现，避免以“已有方法或提交”替代完成证明。
 
 ## What Changes
 
-- Correct the `opencode run --share` model from a string-valued option to a boolean switch.
-- Add typed support for currently unmodeled documented execution flags needed by programmatic integrations, including `run --auto` and `run --interactive`.
-- Make CLI execution honor `maxConcurrentExecutions`.
-- Add per-execution environment overrides and explicit environment inheritance semantics.
-- Add bounded stdout/stderr capture so an untrusted or long-running child process cannot grow memory without limit.
-- Preserve captured stdout/stderr and distinguish timeout, cancellation, spawn failure, and non-zero exit outcomes.
-- Add a streaming CLI execution API that delivers stdout/stderr incrementally before process exit.
-- Add a managed long-running process abstraction for `serve`, `web`, and ACP launch use cases with start, readiness, stop, exit, and log-tail semantics.
-- Correct HTTP/SSE chat streaming to consume canonical delta events without appending full part snapshots as text deltas.
-- Add SSE readiness and failure propagation so a prompt is not submitted until the event stream is connected and transport failure completes the chat stream exceptionally.
-- Keep “unsubscribe from events” separate from “abort server-side session execution”; abort remains explicit.
-- Add a typed `server` configuration model and real unknown-field preservation for OpenCode configuration round-trips.
-- Add real OpenCode contract tests in addition to existing `echo`-based argument-construction tests.
-- Apply behavioral changes first to `feature/3.0.x`, then port equivalent behavior to `feature/2.0.x` and `feature/1.0.x` while preserving each line's Java/Jackson compatibility.
+- 精确建模 CLI 参数：布尔 `--share`、显式启用的 `--auto`、交互参数和版本受控的网络/全局选项；保留 raw argv。
+- 补有界输出、并发准入、每次调用独立环境、退出分类、取消与实时 CLI 输出。
+- 为 Web/Serve 建立启动、就绪、退出和关闭契约，分离启动超时与进程存活时间。
+- 为 ACP 提供双向 stdio 启动边界，不声称已经实现完整 ACP Java 协议客户端。
+- 修正 SSE 文本增量/快照、连接就绪、终态错误、取消、会话关联与资源释放。
+- 补 server 配置及未知 JSON 字段保留，同时保留通用配置提交入口。
+- 建立固定版本的上游契约、真实子进程及三兼容分支验证。
+- **BREAKING（行为纠错）**：旧 `share(String)` 只兼容 null/true/false；其他值明确拒绝，不再把任意字符串当作分享范围。新接口使用 boolean。
+- 有界缓冲和明确错误分类可能改变旧调用者观察到的截断、空白及失败结果，必须提供迁移说明，不删除原有方法签名。
 
 ## Capabilities
 
 ### New Capabilities
 
-- `cli-runtime`: bounded, cancellable, concurrent, environment-isolated CLI process execution with streaming and managed-process modes.
-- `server-lifecycle`: managed lifecycle for long-running OpenCode `serve` / `web` / ACP launcher processes.
-- `contract-verification`: version-pinned OpenCode CLI and SSE contract tests beyond command-string construction.
+此处 New 表示首次进入 OpenSpec 主规范体系，不代表对应业务以前完全不存在。读取的草稿只有 change，没有 `openspec/specs` 主规范，因此六份 delta 都用 ADDED，不伪造 MODIFIED 基线。
+
+- `cli-contract`：类型化参数、原始参数、危险开关与终端模式边界。
+- `cli-runtime`：并发、输出界限、调用环境、流式执行与错误分类。
+- `server-lifecycle`：Web/Serve 管理、认证、资源所有权及 ACP 启动边界。
+- `chat-streaming`：SSE 就绪、事件归约、失败、取消与同会话隔离。
+- `configuration-model`：强类型 server、未知字段和 PATCH 边界。
+- `contract-verification`：证据、评审门禁、固定上游版本及三线兼容验证。
 
 ### Modified Capabilities
 
-- `cli-contract`: typed OpenCode CLI flags MUST match upstream option arity and semantics.
-- `chat-streaming`: SSE chat streaming MUST use canonical delta events, wait for subscription readiness, and propagate transport failures.
-- `configuration-model`: OpenCode configuration MUST model server settings and preserve unknown fields across read/modify/write operations.
+无。后续已有主规范且需求改变时，才使用 MODIFIED 并完整保留既有场景。
+
+## Scope and Non-Goals
+
+本提案覆盖上面六个能力。完整 ACP 协议客户端、内嵌 PTY/终端尺寸控制、Web UI 重做、跨主机服务注册、多租户安全平台、无服务端支持的 SSE 精确一次重放均不在本次范围；这些内容需要独立 proposal。
 
 ## Impact
 
-- Public API: `OpenCodeRunOptions.share(String)` is an incorrect API and requires a compatibility migration to `share(boolean)`. The string overload may be temporarily deprecated if source compatibility is required.
-- Runtime behavior: CLI commands become concurrency-controlled and output-bounded; long-running commands gain a separate lifecycle API instead of relying on the ordinary synchronous timeout path.
-- Tests: contract tests require a pinned OpenCode test binary or explicitly enabled integration-test profile.
-- Branching: implementation starts on the Java 21 / Jackson 3 line, then is backported with compatibility-specific code for the older branches.
+源码锚点：`feature/1.0.x@05702c10fc2533c9dfb4f58be2b97f1247a4c9b3`、`feature/2.0.x@13f68b1b506dfb0aa274d388f7f5a028d340b67b`、`feature/3.0.x@99974efc311ba8c0aabad8c9471ed803d155e534`。
+本轮纯文档分支基于第三个提交；从已有实现分支复用草稿，但不带入其代码提交。
+建议以 OpenCode `v1.17.18` 为契约目标；真实二进制、摘要和测试证据尚未记录，不声称通过兼容验证。
+1.0.x 的 JDK 基线冲突是该分支实现与发布的阻塞条件，不能擅自用提高版本号代替解决。
+
+## Approval Status
+
+DRAFT / NOT_APPROVED。现有实现仅为待核验候选，不作为规范已经满足的证据。
+本轮只交付规范和计划；下一次实施前完成 `review.md` 门禁。事实及出处见 `evidence.md`，技术方案见 `design.md`。

openspec/changes/harden-opencode-runtime-integration/proposal.md

@@ -0,0 +1,53 @@
+# 评审门禁与交付状态
+
+## 当前状态
+
+- 工件：书面评审稿；没有新增规范批准记录。
+- 人工批准：NOT_APPROVED。提交推送授权不等于对每条行为规范和实现结果的验收。
+- 实现：PAUSED；已有代码为候选，本次不新增或重写业务源码及测试。
+- 交付目标：将既有候选代码与修订后的 OpenSpec 文档汇总到 `fix/runtime-integration-hardening`。
+- OpenSpec 官方 CLI 严格校验：NOT_RUN。当前容器没有 openspec 命令，registry.npmjs.org DNS 解析未成功，未执行官方 CLI 校验。
+- Java/Maven/OpenCode 本地运行测试：NOT_RUN。本次仅同步文档，未运行候选源码的构建或测试。
+- 三分支同步/兼容通过：NOT_DONE；本次不更新三条 feature 分支。
+- 主规范同步、归档、合并到版本分支及发布：NOT_DONE。
+
+文档结构检查、Git 内容哈希一致性检查、CI 状态查询分别记录；它们不能相互替代，也不能代替人工批准。
+
+## 汇总来源与不变范围
+
+- 候选代码来源：`fix/runtime-integration-hardening@6c590c3a9af2a595d729cb6e50b1fd6d3458459e`。
+- 规范来源：`docs/opencode-runtime-integration-spec@36fa7504a07fcd9dca2da7c490bcb0d696211c77`。
+- 原始规范子树：`50b7eeb08425f2d4c00e0fdde4057267e0624e8e`。
+- 汇总时仅更新 OpenSpec 文档及本轮状态说明；源码和测试子树保持 `7e81c66d96cbdfa7d53a5e7d80f7295caad049bf`，构建与 CI 配置不变。
+- 规范任务保持未勾选；已有候选代码必须逐条关联需求、补失败用例并复验，不能追认完成。
+- 纯文档分支保留原始评审快照，不删除、不移动；候选分支通过新增提交向前推进，不 reset、不强推。
+
+## 本次操作开始时的版本分支快照
+
+以下是读取远端所得快照，不是本次提交产物；后续操作应重新 fetch，不能用旧副本覆盖新的审计修复。
+
+| 分支 | 读取时提交 |
+|---|---|
+| feature/1.0.x | cf53e19bee92981d216c2a7a800a9113ab7e6870 |
+| feature/2.0.x | e85f2caf040358dfe43cf6a09fa054a059a34b92 |
+| feature/3.0.x | 2e22856e47219444de5bf7ff66a09841c8c40ea0 |
+
+这些分支已有相对于最初分析基线的新提交。真正实施和回移时需重新比较各分支差异；不能将当前候选分支视作已包含这些提交。
+
+## 验证命令与证据规则
+
+在项目目录中安装可用的 OpenSpec CLI 后执行，并记录工具版本、命令、退出码和完整输出：
+
+```sh
+openspec --version
+openspec validate harden-opencode-runtime-integration --strict
+openspec status --change harden-opencode-runtime-integration --json
+```
+
+严格校验预期退出码为 0；status 仅显示工件依赖情况，不是批准证明。Java/Maven 和真实 OpenCode 测试需分别记录实际命令、运行环境、通过/失败/跳过数与报告路径。
+
+现有 CI 工作流的 push / pull_request 过滤目标为 feature/3.0.x，另声明 workflow_dispatch。仅推送候选分支不能假定自动触发 CI；应按最终提交 SHA 查询运行记录。历史提交 CI 成功不能记作本次新提交 CI 成功；无记录应记为 NOT_TRIGGERED，排队或执行中也不能记作通过。
+
+## 后续实现门禁
+
+批准人、时间、文档提交 SHA、范围与保留项必须真实记录。继续实现前读取完整 proposal、design、tasks、specs 和当前分支代码；按需求补失败测试，再执行实现及三分支验证。文档归档和发布仍受这些门禁约束。