feat(sdk): return authoritative turn settlement results

docs/architecture/agent-runtime-lifecycle-sequence.md

@@ -239,7 +239,8 @@
 
 5. **结算同步点（[runtime.rs:1038-1051](../../src/crates/execution/agent-runtime/src/runtime.rs#L1038-L1051)）**：
    `wait_for_turn_settlement()` 是阻塞调用，调用方用它等 turn 进入
-   `TurnOutcome::{Completed, Cancelled, Failed}`，之后才读 transcript / 算 usage。
+   `TurnOutcome::{Completed, Cancelled, Failed}`，并取得 Runtime 确认的终态、最终回答和结束原因；
+   transcript 与 usage 仍按需通过各自的只读接口获取。
 
 6. **post-call hooks（[post_call_hooks.rs:156-172](../../src/crates/execution/agent-runtime/src/post_call_hooks.rs#L156-L172)）**：
    仅在「成功工具调用后」（`SuccessfulToolPostCall`）触发，当前唯一具体钩子是

docs/architecture/agent-runtime-services-design.md

@@ -68,7 +68,7 @@ Agent Runtime API 的逻辑归属与物理部署分离：相同归属模块可
 私有 SDK Host 或目标机器 Runtime 中。任何 Rust 部署都只管理自己进程树内的服务与 Node/Bun Plugin Host；不能因为多个
 GUI/TUI/Remote Client 连接就复制 Runtime 状态模块，或按 Client/Workspace 创建 Plugin Host。
 
-Rust Runtime SDK 以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前接口版本为 v9 preview：
+Rust Runtime SDK 以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前接口版本为 v10 preview：
 小版本更新允许增加可选 builder hook、有默认实现的端口方法或注册表查询能力，但不得向外部可用
 Rust 结构体字面量（struct literal）构造的 DTO 直接增加字段，也不得改变既有端口语义、错误分类、session / turn 标识含义或
 默认 feature 依赖。任何需要调用方改写现有嵌入代码的变更，必须提升接口版本并提供兼容迁移路径。
@@ -98,6 +98,9 @@ v8 增加 `TurnTokenUsage` 聚合事实。对应 SDK Host protocol v5 支持本
 v9 删除从未接入真实执行路径的 Harness descriptor registry、builder 注入和查询接口。命名工作流由
 Product Assembly 选择并在 `agent-workflows` / 现有产品 owner 中执行，SDK 调用方无需安装或注入另一套工作流框架。
 
+v10 让 Turn settlement 返回 Runtime 确认的终态、最终回答和结束原因。现有 Rust embedder 需要接收
+`AgentTurnSettlementResult`；CLI 和 App Server adapter 可在不扩展各自 wire contract 的情况下丢弃返回值。
+
 只要外部调用方仍必须导入 `bitfun-core`、启用 `product-full`、持有具体服务管理器、读取产品命令
 注册表、理解 ACP/内部端口或依赖全局可变状态，公开 SDK 发布边界就不成立。公开 SDK 的完整
 术语、能力等价和版本要求以 [`agent-sdk-product-architecture.md`](agent-sdk-product-architecture.md) 为准。
@@ -441,7 +444,7 @@ impl AgentRuntime {
 该 Rust 接口是内部产品入口复用的当前形态，不是公开 Python/TypeScript SDK 的目标 API。它必须只接收
 已组装的类型化部件，不负责创建
 文件系统、终端、MCP、AI 客户端、Remote 提供方或产品命令。
-当前 v9 preview 接口以 message / attachment / metadata、默认标准执行目标和活动 Turn 文本 steer 作为最小输入形态；若把
+当前 v10 preview 接口以 message / attachment / metadata、默认标准执行目标和活动 Turn 文本 steer 作为最小输入形态；若把
 model-round cancellation token、结构化 AgentInput 或更复杂的事件游标纳入公开 SDK，
 必须分别评审 Rust Runtime SDK、SDK Host protocol 和公开 SDK API 的版本，并保留旧路径兼容。
 

src/apps/cli/src/agent/runtime_client.rs

@@ -1296,7 +1296,7 @@ impl CliAgentRuntimeClient {
         };
         match &self.backend {
             CliAgentRuntimeBackend::Embedded(runtime) => {
-                runtime.wait_for_turn_settlement(request).await
+                runtime.wait_for_turn_settlement(request).await.map(|_| ())
             }
             CliAgentRuntimeBackend::Shared(client) => {
                 let result = client
@@ -2762,10 +2762,10 @@ mod dual_backend_behavior_tests {
         AgentSessionWorkspaceRequest, AgentSubmissionPort, AgentSubmissionRequest,
         AgentSubmissionResult, AgentTurnCancellationPort, AgentTurnCancellationRequest,
         AgentTurnCancellationResult, AgentTurnSettlementPort, AgentTurnSettlementRequest,
-        AgenticEvent, DialogSubmitOutcome, PermissionReply, PermissionRequest,
-        PermissionRequestManager, PermissionRequestSource, PermissionRequestSourceKind, PortError,
-        PortErrorKind, PortResult, RuntimeError, SessionState, SessionTranscript,
-        SessionTranscriptReader, SessionTranscriptRequest,
+        AgentTurnSettlementResult, AgentTurnSettlementStatus, AgenticEvent, DialogSubmitOutcome,
+        PermissionReply, PermissionRequest, PermissionRequestManager, PermissionRequestSource,
+        PermissionRequestSourceKind, PortError, PortErrorKind, PortResult, RuntimeError,
+        SessionState, SessionTranscript, SessionTranscriptReader, SessionTranscriptRequest,
     };
     use bitfun_agent_runtime_ipc::{
         RuntimeInstanceIdentity, RuntimeIpcClient, RuntimeIpcClientError, RuntimeIpcErrorCode,
@@ -3101,7 +3101,7 @@ mod dual_backend_behavior_tests {
         async fn wait_for_turn_settlement(
             &self,
             request: AgentTurnSettlementRequest,
-        ) -> PortResult<()> {
+        ) -> PortResult<AgentTurnSettlementResult> {
             match self
                 .state
                 .settlement_outcomes
@@ -3111,7 +3111,11 @@ mod dual_backend_behavior_tests {
                 .cloned()
             {
                 Some(Some(error)) => Err(error),
-                _ => Ok(()),
+                _ => Ok(AgentTurnSettlementResult {
+                    status: AgentTurnSettlementStatus::Completed,
+                    final_response: Some("fixture result".to_string()),
+                    finish_reason: Some("stop".to_string()),
+                }),
             }
         }
     }

src/apps/cli/src/dispatch/worker.rs

@@ -400,7 +400,7 @@ async fn run_inner(store: &DispatchStore, job_id: &str) -> Result<()> {
         })
         .await;
     let (terminal_state, terminal_error) = match settlement {
-        Ok(()) => (terminal_state, terminal_error),
+        Ok(_) => (terminal_state, terminal_error),
         Err(error) => (
             DispatchJobState::Failed,
             Some(format!(

src/crates/assembly/core/src/agentic/coordination/background_outcomes.rs

@@ -704,6 +704,8 @@ mod tests {
                 "persisted child result".to_string(),
                 &[],
                 TurnStats::default(),
+                Some("complete".to_string()),
+                Some(true),
             )
             .await
             .expect("complete child turn");