Improve Runtime Console navigation and coding guidance

.github/workflows/ci.yml

@@ -597,7 +597,7 @@ jobs:
         shell: pwsh
         run: |
           $ErrorActionPreference = "Stop"
-          $stage = Join-Path $env:GITHUB_WORKSPACE "target\desktop-ci-bundle"
+          $stage = Join-Path $env:RUNNER_TEMP "webcodex-desktop-ci-bundle"
           & .\scripts\prepare_desktop_bundle.ps1 `
             -BinDir "target\dogfood" `
             -Version "${{ steps.runtime.outputs.version }}" `

.github/workflows/release-build.yml

@@ -658,7 +658,7 @@ jobs:
         run: |
           $ErrorActionPreference = "Stop"
           $binDir = Join-Path "target" (Join-Path $env:RUST_TARGET "release")
-          $stage = Join-Path $env:GITHUB_WORKSPACE "target\desktop-release-bundle"
+          $stage = Join-Path $env:RUNNER_TEMP "webcodex-desktop-release-bundle"
           & .\scripts\prepare_desktop_bundle.ps1 `
             -BinDir $binDir `
             -Version $env:VERSION `

README.md

@@ -31,7 +31,7 @@ npx --yes @yyjeqhc/webcodex share
 - **Use the real toolchain** — run commands, tests, formatters, compilers, and project-specific tooling on the machine that owns the repository.
 - **Work with Git** — inspect status and diffs while keeping repository operations visible and reviewable.
 - **Handle long-running work** — keep jobs observable instead of requiring one model turn to stay open indefinitely.
-- **Support human review** — use the Runtime Console and task workflow to guide, cancel, accept, or reject work where those actions are available.
+- **Support human review** — use the [Runtime Console](docs/runtime-console.md) and task workflow to guide, cancel, accept, or reject work where those actions are available.
 
 ## Why WebCodex?
 

apps/desktop/src-tauri/src/process/tests/macos.rs

@@ -1,8 +1,9 @@
 use crate::activity::ActivityLog;
 use crate::process::{ProcessKind, ProcessSupervisor};
 use std::path::{Path, PathBuf};
+use std::process::Command;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
-use tokio::process::{Child, Command};
+use tokio::process::{Child, Command as TokioCommand};
 
 const TEST_TIMEOUT: Duration = Duration::from_secs(5);
 const POLL_INTERVAL: Duration = Duration::from_millis(20);
@@ -76,7 +77,7 @@ async fn desktop_owned_group_kills_descendant_without_touching_unrelated_process
         .arg("webcodex-owned-tree")
         .arg(&marker);
 
-    let mut control = Command::new("/bin/sleep")
+    let mut control = TokioCommand::new("/bin/sleep")
         .arg("60")
         .spawn()
         .expect("spawn unrelated control process");

apps/desktop/src-tauri/src/webcodex/cli.rs

@@ -1119,19 +1119,15 @@ mod tests {
                 .unwrap_or_default()
                 .as_nanos()
         ));
-        let script = concat!(
-            "$child = Start-Process powershell.exe ",
-            "-ArgumentList '-NoProfile','-NonInteractive','-Command','Start-Sleep -Seconds 30' ",
-            "-PassThru; ",
-            "Set-Content -Path $args[0] -Value \"$PID $($child.Id)\" -NoNewline; ",
-            "Start-Sleep -Seconds 30"
+        let escaped_marker = marker.to_string_lossy().replace('\'', "''");
+        let script = format!(
+            "$child = Start-Process powershell.exe -ArgumentList '-NoProfile','-NonInteractive','-Command','Start-Sleep -Seconds 30' -PassThru; Set-Content -LiteralPath '{escaped_marker}' -Value \"$PID $($child.Id)\" -NoNewline; Start-Sleep -Seconds 30"
         );
         let args = vec![
             "-NoProfile".to_string(),
             "-NonInteractive".to_string(),
             "-Command".to_string(),
-            script.to_string(),
-            marker.to_string_lossy().to_string(),
+            script,
         ];
         let payload = vec![b'x'; CLI_INPUT_BYTES];
         let started = Instant::now();
@@ -1143,25 +1139,25 @@ mod tests {
                 Some(&payload),
                 false,
                 &cancellation,
-                Duration::from_secs(5),
+                Duration::from_secs(8),
             )
             .await
         });
-        let marker_deadline = Instant::now() + Duration::from_secs(4);
+        let marker_deadline = Instant::now() + Duration::from_secs(6);
         while !marker.is_file() {
             assert!(
                 Instant::now() < marker_deadline,
                 "blocked-stdin fixture must publish owned pids before timeout"
             );
             tokio::time::sleep(Duration::from_millis(20)).await;
         }
-        let error = tokio::time::timeout(Duration::from_secs(5), command)
+        let error = tokio::time::timeout(Duration::from_secs(12), command)
             .await
             .expect("blocked-stdin command must finish within its bounded cleanup")
             .expect("blocked-stdin fixture task")
             .unwrap_err();
         assert_eq!(error.code, "webcodex_command_timeout");
-        assert!(started.elapsed() < Duration::from_secs(9));
+        assert!(started.elapsed() < Duration::from_secs(12));
         let pids = std::fs::read_to_string(&marker)
             .expect("fixture must publish owned pids")
             .split_whitespace()

crates/webcodex-core/src/runtime_contract.rs

@@ -48,7 +48,7 @@ pub const RECOVERY_TOOL_VALUES: [&str; 7] = [
 ];
 
 pub const BUILTIN_CODING_WORKFLOW_CONTRACT: &str = "webcodex.coding_workflow";
-pub const BUILTIN_CODING_WORKFLOW_VERSION: u64 = 6;
+pub const BUILTIN_CODING_WORKFLOW_VERSION: u64 = 7;
 pub const BUILTIN_CODING_WORKFLOW_MAX_GUIDANCE_ITEMS: usize = 8;
 
 /// Validate a Runner project path without applying host-local filesystem semantics.

crates/webcodex-tool-contracts/src/registry/output_schemas/coding_tasks.rs

@@ -402,12 +402,19 @@ fn startup_workspace_schema() -> Value {
 fn startup_workflow_schema() -> Value {
     json!({
         "type": "object",
-        "description": "WebCodex-owned model guidance for named coding/review pass roles. Separate from project instructions and Session authority.",
+        "description": "WebCodex-owned workflow defaults and optional named coding/review roles. Separate from project instructions and Session authority.",
         "properties": {
             "contract": {"type": "string", "const": BUILTIN_CODING_WORKFLOW_CONTRACT},
             "version": {"type": "integer", "const": BUILTIN_CODING_WORKFLOW_VERSION},
             "authority": {"type": "string", "const": "model_guidance_only"},
             "role_selection": {"type": "string", "maxLength": 240},
+            "guidance": {
+                "type": "array",
+                "description": "Default behavior for every coding/review task, including tasks without a named role. Guidance never grants authority.",
+                "minItems": 1,
+                "maxItems": BUILTIN_CODING_WORKFLOW_MAX_GUIDANCE_ITEMS,
+                "items": {"type": "string", "maxLength": 320}
+            },
             "model_protocol": {
                 "type": "object",
                 "description": "Shared model-invocation guidance. It is not Session state, authority, or execution policy.",
@@ -443,7 +450,7 @@ fn startup_workflow_schema() -> Value {
                 "additionalProperties": false
             }
         },
-        "required": ["contract", "version", "authority", "role_selection", "model_protocol", "roles"],
+        "required": ["contract", "version", "authority", "role_selection", "guidance", "model_protocol", "roles"],
         "additionalProperties": false
     })
 }

crates/webcodex-tool-contracts/src/test_support.rs

@@ -108,6 +108,11 @@ fn validate_schema_instance_at(instance: &Value, schema: &Value, path: &str) ->
         }
     }
     if let Some(array) = instance.as_array() {
+        if let Some(min_items) = schema.get("minItems").and_then(Value::as_u64) {
+            if array.len() < min_items as usize {
+                return Err(format!("{path}: below minItems"));
+            }
+        }
         if let Some(max_items) = schema.get("maxItems").and_then(Value::as_u64) {
             if array.len() > max_items as usize {
                 return Err(format!("{path}: maxItems exceeded"));

docs/CODING_WORKFLOW.md

@@ -25,7 +25,14 @@ Use `work_on_project` for both a new coding task and an explicit continuation. W
 
 For ordinary use you do not need to reason about WebCodex's internal continuity or audit fields. Those are implementation/maintainer contracts.
 
-Behavioral roles are expressed in the task instruction, not through a separate authority mechanism. For example:
+The built-in workflow includes default guidance for every task, even when no
+role is named: inspect the target and applicable rules, preserve existing work,
+complete authorized implementation, validate proportionally, observe existing
+Jobs instead of duplicating effects, and report evidence honestly. Use only
+tools and protocol fields supported by the current exposed schemas.
+
+Behavioral roles add emphasis to those defaults. They are expressed in the task
+instruction, not through a separate authority mechanism. For example:
 
 ```text
 Use the implementation_owner guidance. Implement <task>, run focused validation,
@@ -36,15 +43,26 @@ For an independent review:
 
 ```text
 Use the independent_review guidance. Review <change or commit> independently,
-correct only concrete findings, and run focused regression validation.
+report concrete findings with file/line evidence and impact, and do not edit.
 ```
 
-Role guidance changes model behavior only. Authentication, project authority, tool policy, and safety checks remain authoritative.
+To request corrections as well, explicitly add “fix concrete findings and run
+focused regression validation.” Naming a review role alone does not authorize edits.
+
+Guidance is delivered in tool results; it is not the client's system prompt and
+does not grant execution authority. Host instructions, the user's task,
+applicable project rules, authentication, and runtime safety policy still apply.
+Delivery is not proof that a model read, retained, or followed the guidance.
+Keep guidance enabled unless the current model context already retains it.
 
 ## Inspect before editing
 
 Prefer structured project search/read tools over shell commands when they express the task. Read only the files and ranges needed to understand the change, and preserve unrelated work already present in the workspace.
 
+The bootstrap reads a fixed set of instruction entry points; it does not scan
+every subdirectory for rules. Before changing a path, inspect applicable nested
+instructions and recover any relevant missing or truncated rule content.
+
 For branch/PR review, start with the bounded review/change-summary tools exposed by the current Server, then narrow to targeted reads or diff hunks when needed.
 
 ## Editing
@@ -81,6 +99,20 @@ Multi-window coordination is an advanced maintainer workflow, not part of the or
 
 The exact concurrency, retry, provenance, and cross-Session authorization rules are documented in [Manual Multi-Window Collaboration](agent/manual-window-collaboration.md). Their protocol fields are intentionally omitted here.
 
+## Assessing effectiveness
+
+Runtime tests check that guidance is delivered consistently, remains bounded,
+matches its schema, and never becomes authority. The scripted
+`scripts/eval_coding_loop.sh` checks tool-loop mechanics; it does not run a model
+or measure instruction following.
+
+To measure behavioral benefit, compare the same model, tools, settings, and task
+fixtures with and without guidance over repeated runs. Include a small fix, a
+review-only task, existing unrelated changes, nested instructions, and an
+uncertain long-running effect. Compare correctness and scope preservation first,
+then unnecessary clarification, duplicate execution, validation quality, tool
+calls, and token cost. Do not infer a success-rate improvement from schema tests.
+
 ## Internal protocol details
 
 When developing WebCodex itself, use the maintainer contracts rather than expanding this user guide:

docs/CODING_WORKFLOW.zh-CN.md

@@ -25,7 +25,9 @@ work_on_project
 
 普通使用不需要理解 WebCodex 内部的 continuity/audit field；这些属于 implementation/maintainer contract。
 
-Behavioral role 写在 task instruction 里即可，例如实现任务：
+内置工作流为所有任务提供默认 guidance，不要求先指定角色：核对目标和适用规则、保留已有工作、完成已授权的实现、按改动范围验证、观察已有 Job 而不重复执行，以及如实报告证据。只使用当前暴露的 schema 支持的工具与协议字段。
+
+Behavioral role 在默认原则上增加侧重点，写在 task instruction 里即可，例如实现任务：
 
 ```text
 使用 implementation_owner guidance。实现 <任务>，运行聚焦 validation，
@@ -36,15 +38,19 @@ Behavioral role 写在 task instruction 里即可，例如实现任务：
 
 ```text
 使用 independent_review guidance。独立评审 <改动或 commit>，
-只修复具体问题，并运行聚焦 regression validation。
+报告有文件/行号证据和影响说明的具体发现，不修改文件。
 ```
 
-Role guidance 只改变模型行为，不改变 authentication、project authority、tool policy 或 hard safety。
+如果也希望修复，明确补充“修复具体发现，并运行聚焦回归验证”。单独指定评审角色不代表授权修改。
+
+Guidance 通过工具结果交给客户端，不是客户端的 system prompt，也不会授予执行权限。Host 指令、用户任务、适用项目规则、认证和运行时安全策略仍然有效。返回 guidance 不等于模型已经读取、记住或遵守；只有当前模型上下文仍保留内容时才应关闭其返回。
 
 ## 编辑前先检查
 
 能够表达任务时，优先使用 structured project search/read，而不是 shell。只读取理解当前改动所需的文件和范围，并保留 workspace 中已经存在的无关工作。
 
+Bootstrap 只读取固定的几个指令入口，不会扫描所有子目录规则。修改某个路径前，需要检查适用的子目录指令，并补读相关缺失或被截断的规则内容。
+
 做 branch/PR review 时，先使用当前 Server 提供的有界 review/change-summary 工具，再按需要缩小到具体文件或 diff hunks。
 
 ## 编辑
@@ -81,6 +87,12 @@ Guard failure 是 **zero-write conflict**，不是削弱 guard 的理由。重
 
 精确的 concurrency、retry、provenance 与 cross-Session authorization 规则见 [Manual Multi-Window Collaboration](agent/manual-window-collaboration.md)。对应 protocol field 有意不放在普通工作流里。
 
+## 如何判断是否有效
+
+运行时测试可以证明 guidance 的返回一致、有界、符合 schema，且不会变成执行权限。`scripts/eval_coding_loop.sh` 检查的是脚本化工具循环，没有运行模型，不能衡量模型是否遵守提示词。
+
+要衡量行为收益，应固定模型、工具、参数与任务样本，对比有无 guidance 的多次运行。样本至少包括小型修复、只读评审、已有无关改动、子目录规则，以及结果不确定的长时间操作。先比较正确性与任务范围保持，再比较不必要的询问、重复执行、验证质量、工具调用和 token 成本。不能从 schema 测试通过推断模型成功率提升。
+
 ## 内部协议细节
 
 开发 WebCodex 本身时，直接阅读 maintainer contract，而不是继续扩充这份普通用户指南：

docs/agent/openapi-guidelines.md

@@ -1,9 +1,8 @@
 # OpenAPI / GPT Action Guidelines
 
 Product and integration detail for GPT Actions and OpenAPI exposure.
-**Hard invariants agents must obey are in [`AGENTS.md`](../../AGENTS.md)**
-(architecture section). This document holds the longer product rules so
-`AGENTS.md` stays an execution contract.
+Repository-wide rules are in [`AGENTS.md`](../../AGENTS.md). This document
+owns the API-specific invariants and product guidance linked from that guide.
 
 Related: [`GPT_ACTIONS.md`](../GPT_ACTIONS.md), [`MCP.md`](../MCP.md).
 

docs/agent/session-model.md

@@ -562,10 +562,6 @@ For deliberate coordinator/worker delegation across separate windows, keep the
 Sessions independent and use the existing handoff plus message-board primitives;
 see [Manual Multi-Window Collaboration](manual-window-collaboration.md).
 
-### Invariants (must)
-
-These are also summarized in `AGENTS.md` §7, **Sessions**:
-
 ---
 
 ## 2. Action Audit Session

docs/runtime-console.md

@@ -0,0 +1,24 @@
+# Runtime Console navigation
+
+Open `/runtime` and connect with an existing runtime credential.
+
+- **Projects & Sessions** is the collaboration workspace. Select a Project and
+  Workflow Session in the sidebar. Recent Sessions starts expanded and can be
+  collapsed when more room is needed.
+- **Context** opens the selected Session's context. **Overview** shows work,
+  attention, validation, and model-reported progress directly. **Activity** shows
+  retained events and the existing follow-latest control. **Details** shows
+  identity, lifecycle, mode, timestamps, and workspace information.
+- **Runtime & Agents** provides three separate destinations: **Overview**,
+  **Runner fleet**, and **Durable Agents**. Selecting a destination shows its
+  full content and updates the navigation highlight. Switching destinations
+  keeps existing forms mounted so unsent input is retained.
+
+The context panel still adapts between a docked rail, popover, and mobile sheet.
+Closing it leaves a labeled Context entry in the header. Context navigation uses
+ordinary keyboard-focusable buttons, with the current choice announced as pressed.
+Mobile operation navigation closes after selection and focuses the destination.
+
+These are presentation changes. Workflow Session and durable Agent identities,
+credential scopes, refresh behavior, and mutation handling keep their existing
+contracts. Model-reported progress remains informational.