@orion-agents/orion-code 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -22,6 +22,88 @@ which is **not** a pass.
 
 ## [Unreleased]
 
+## [0.3.1] — CANDIDATE
+
+> **Status: candidate.** This branch carries the v0.3 Web quality and long-session recovery fixes.
+> It is not a Git tag, GitHub Release or npm publication until those receipts exist.
+
+### Added
+
+- Add a registered multi-project navigator with lazy inactive-project Session pages and one atomic,
+  revision-guarded active Workspace/Session transition.
+- Add a professional right work dock for Agent, Review, Terminal, Files and Git, with an IDE-style
+  mouse-resized 320–720px desktop panel and responsive drawers that preserve desktop width.
+- Add bounded, revisioned read models for workspace-contained files, Git status/log/diff and review
+  metadata, plus an explicit real-PTY terminal with short-lived WebSocket attach tickets.
+- Add the v0.3.1 OpenAPI, migration guide and exact-artifact WEB31-P0-01..12 qualification contract.
+
+### Changed
+
+- Extend full browser qualification to 34 scenarios and the Node 22.12/24/26 critical matrix to 24
+  scenarios, all bound to one source-clean tgz, installed-target identity and real Chrome runner.
+- Raise the packed-package ceiling from 2.00 to 2.25 MiB for the bundled xterm client while keeping
+  the 10 MiB unpacked and 1,500-entry limits unchanged.
+- Keep terminal output off the Workbench SSE and durable Session history; Host restart reports the
+  terminal as lost instead of fabricating recovery.
+
+### Fixed
+
+- Keep the conversation composer in a bounded bottom dock while transcript history and pending
+  approval or follow-up content scroll independently.
+- Bind Web commands and recovery snapshots to the active Session, make replay reset a terminal
+  barrier, and preserve Session-scoped drafts across navigation.
+- Serve large tool output only from a browser-safe derivative so arbitrary byte offsets cannot
+  bypass redaction.
+- Persist verified Thread heads and immutable transcript pages, use revision-bound collection
+  cursors, and load additional browser history explicitly instead of draining every page at boot.
+
+### Security
+
+- Require UUID idempotency keys and current Workspace/Context guards for v0.3.1 resource operations;
+  stale guards return `context_revision_conflict` with zero side effects.
+- Bind every WEB31 screenshot and high-risk structured fact into the Web E2E receipt, including
+  context targeting, PTY orphan count, SSE/WS isolation, axe and secret gates.
+
+## [0.3.0] — CANDIDATE
+
+> **Status: candidate.** This source version is not a Git tag, GitHub Release or npm publication
+> until those external receipts are created and read back separately.
+
+### Added
+
+- Add `orion web`, a loopback-only React workbench for workspace/session navigation, streaming
+  conversation and tools, follow-up/interrupt, approvals, Goal/Plan, model/effort settings,
+  Skills/MCP metadata, large-output inspection and diagnostics.
+- Add a versioned same-origin Web API with bounded cursor pagination, process-lifetime idempotency
+  keys, settings compare-and-swap, session recovery snapshots and a replayable SSE event stream.
+- Add a Host-owned Settings subsystem with strict typed reads, keyed exact-byte revisions,
+  raw-preserving atomic batch updates, lock-inside CAS, external-edit convergence, last-good
+  recovery and browser conflict handling.
+- Add the source-audited v0.3.0 product plan, OpenAPI contract and v0.2.2 migration/rollback guide.
+
+### Changed
+
+- Set the release-qualification contract to maintained Node 22.12+, 24 and 26; publication now
+  requires exact-tarball native SQLite, CLI, TUI, Web and fail-closed evidence on every line.
+- Extract the CLI composition into one shared product bootstrap so Web, TUI, terminal and print
+  retain the same AgentRuntimeController, OrionSessionRunner, OrionRuntime and durable stores.
+- Resolve new root/child runtimes from the selected model profile and support exact
+  BUILD/PLAN/AUTO selection at the next logical-request boundary.
+- Align durable approval scopes with the product permission store as `once`, `project`, `global`.
+- Route Web, TUI and slash-command changes for default model, project/global effort and tool
+  confirmation through one Settings coordinator; keep the current-session model distinct from the
+  default for newly created sessions.
+
+### Security
+
+- Bind Web only to `127.0.0.1`; require exact Origin, per-process nonce and JSON for mutations; cap
+  bodies and pages; reject Host/path-boundary violations; and send restrictive browser headers.
+- Keep pending approvals runtime-owned across browser disconnects, redact browser-safe projections,
+  expose no provider credentials, and disconnect slow SSE clients so they recover by cursor rather
+  than growing an unbounded response buffer.
+- Expose credential readiness only, keep the configuration-file action pathless, preserve invalid
+  external bytes, and require Runtime-idle mutation for settings that alter execution policy.
+
 ## [0.2.2] — 2026-08-27
 
 > **Status: published.** The `v0.2.2` tag and npm `latest` package identify this release tree.

package/README.md

@@ -1,13 +1,46 @@
 # Orion Code
 
-Goal-driven coding agent for the terminal.
-
-> v0.2.2 — resilient Thread session recovery, provider-safe interrupted tool
-> history, and width-stable Goal usage visibility on the v0.2 Harness.
-
-[中文说明](README.zh-CN.md) · [Architecture plan](docs/plan/v0.2.0-dsh-harness-redesign-plan.md) ·
-[Migration guide](docs/migration/v0.1.9-to-v0.2.0.md) ·
-[Release checklist](docs/plan/v0.2.0-release-checklist.md)
+Local-first, goal-driven coding agent for the terminal and browser.
+
+> v0.3.1 candidate — one Orion runtime with a local Web Workbench, replayable browser state and
+> the existing TUI/terminal surfaces. Candidate source is not an npm publication or Git tag.
+
+[中文说明](README.zh-CN.md) ·
+[v0.3.1 professional shell plan](docs/plan/v0.3.1-web-workbench-professional-shell-plan.md) ·
+[v0.3.1 Web API](docs/architecture/v0.3.1-web-api.yaml) ·
+[v0.3.1 E2E plan](docs/test/v0.3.1-web-workbench-e2e-plan.md) ·
+[v0.3.1 migration](docs/migration/v0.3.0-to-v0.3.1.md) ·
+[v0.3.0 Web plan](docs/plan/v0.3.0-web-workbench-plan.md) ·
+[Settings plan](docs/plan/v0.3.0-settings-integration-plan.md) ·
+[Node compatibility](docs/plan/v0.3.0-node-runtime-compatibility-plan.md) ·
+[Web API](docs/architecture/v0.3.0-web-api.yaml) ·
+[Migration guide](docs/migration/v0.2.2-to-v0.3.0.md) ·
+[Settings migration](docs/migration/v0.2.2-to-v0.3.0-settings.md) ·
+[real-state gallery](docs/assets/screenshots/v0.3.0-web/README.md)
+
+## What v0.3.1 includes
+
+- **One runtime, two interactive surfaces.** `orion web` uses the same product bootstrap,
+  AgentRuntimeController, Session/Thread stores, ToolGateway, approvals, Goals, Plans, Skills and
+  MCP boundaries as the terminal product; the browser does not run a second agent loop.
+- **Recoverable Web workbench.** The React workbench includes workspace/session navigation,
+  transcript and tool activity, BUILD/PLAN/AUTO, follow-ups, interrupt, approvals, Goal/Plan,
+  model/effort settings, Skills/MCP and diagnostics. Snapshots plus cursor replay repair refreshes
+  and SSE reconnects.
+- **Professional project shell.** The left navigator shows registered projects with lazy Session
+  pages while the center remains the only Agent conversation. A resizable right dock provides
+  Agent, Review, Terminal, Files and Git surfaces; files/Git/review are bounded read models and the
+  terminal is an explicit, ephemeral real PTY isolated from Session history and SSE.
+- **Local security boundary.** The host binds only `127.0.0.1`; writes require an exact Origin,
+  process nonce, JSON body and idempotency key. Responses use a restrictive CSP, browser payloads
+  are redacted, and large tool results are byte-paged instead of placed on the event stream.
+- **Host-owned Settings.** Appearance, the default model, workspace effort and the global tool
+  confirmation policy use one strict, revisioned `orion.json` coordinator. Atomic batches, file-lock
+  CAS, external-edit invalidation, last-good recovery and explicit source/scope/apply metadata keep
+  the browser, slash commands, TUI and Runtime on the same persisted truth.
+- **Deliberate DSH adaptation.** The design was source-audited against a fixed DeepSeek Harness
+  revision. DSH's browser uses POST plus two downlink WebSockets; Orion intentionally uses JSON
+  HTTP plus one replayable SSE downlink while retaining Orion's Model/Skills/MCP boundaries.
 
 ## What changed in v0.2.0
 
@@ -44,12 +77,13 @@ user extension boundaries.
 
 ## Install
 
-Node.js 20, 22, and 24 are supported.
+Node.js 22.12+, 24, and 26 are supported. Use Node 24 LTS for production or Node 26 Current for
+current development environments. Node 20 is upstream EOL and is no longer a v0.3 runtime.
 
-Install the published `0.2.2` release:
+After the immutable `0.3.1` npm receipt exists:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.2.2
+npm install -g @orion-agents/orion-code@0.3.1
 orion --version
 orion doctor
 ```
@@ -106,6 +140,9 @@ Run `orion doctor` after configuration. Diagnostics never need to print the secr
 ```bash
 orion                         # default product TUI
 orion --ui terminal           # technical terminal fallback
+orion web                     # local Web Workbench; opens a browser
+orion web --no-open --port 0  # choose an ephemeral loopback port
+orion web --cwd /path/to/repo # start against another existing workspace
 orion -p "explain this repo"  # experimental non-interactive mode
 orion -p --output-format json "run the focused tests"
 orion diff
@@ -115,6 +152,41 @@ orion commit
 Experimental non-interactive print mode is available through `orion -p`; keep it out of
 interactive workflows that require confirmations or live steering.
 
+### Local Web Workbench
+
+`orion web` serves the packaged client and `/api/v1/*` from one loopback origin. It does not expose
+a LAN bind. Configure provider credentials with the normal Orion config/environment flow, then use
+the browser to select a workspace and session, run or steer work, answer approvals, and inspect
+runtime state. Closing or refreshing a tab leaves pending approvals owned by the runtime; stopping
+the host aborts them fail-closed.
+
+The browser exposes Plan receipts exactly as committed (`body`, `returnMode`, `digest`). It does not
+insert an extra review gate: after PLAN commits, the existing runtime restores BUILD/AUTO and starts
+implementation in a separate logical turn.
+
+The project navigator does not create multiple runtimes. Cross-project Session selection is one
+atomic, revision-guarded Context transition. The right dock is 320–720px on desktop and is adjusted
+with an IDE-style mouse drag; there is no keyboard fine-resize control. Narrow layouts use drawers
+without overwriting the saved desktop width. Files, Git and Review are read-only; terminal creation
+requires an explicit gesture and its short-lived ticket and output never enter the Workbench SSE.
+
+#### Host-managed Settings
+
+The Settings dialog reads from the active Host rather than treating browser storage as a second
+configuration source. Theme and reduced-motion preferences persist across refreshes, ports and Host
+restarts. The default model applies to newly created sessions; changing the current session remains
+an explicit `/model` or session-control action. Effort is the active workspace's project default,
+with a session override taking precedence. Tool confirmation is global, may be changed only while
+the Runtime is idle and applies at the next logical request; `allow` never bypasses hard policy,
+sandbox or workspace containment.
+
+Every save is one atomic compare-and-swap batch. A concurrent tab or external `orion.json` edit is
+shown as a conflict without discarding the draft. Invalid external JSON preserves the last-good
+Runtime configuration and is never overwritten by the Web UI. Provider credentials remain outside
+the Web API: Settings exposes readiness only and its local configuration action accepts no path.
+See the [Settings migration guide](docs/migration/v0.2.2-to-v0.3.0-settings.md) for precedence,
+legacy appearance import and rollback details.
+
 ### BUILD, PLAN, AUTO
 
 Press `Shift+Tab` to cycle `BUILD → PLAN → AUTO`. The status bar and input border show the current
@@ -190,12 +262,15 @@ npm run bench:harness:baseline
 npm run bench:harness
 npm run bench:harness:compare -- <baseline.json> <candidate.json>
 npm run prepublishOnly
+npm run test:web-e2e -- --grep @settings
 ```
 
 Release qualification additionally builds one exact tarball and installs that unchanged hash on
-Node 20/22/24 for package identity, native SQLite, TUI, terminal, print, Goal, subagent, Skill, MCP,
-Compact, and resume journeys. See the
-[`v0.2.0 release checklist`](docs/plan/v0.2.0-release-checklist.md).
+Node 22/24/26 for package identity, native SQLite, TUI, terminal, print, Web, Goal, subagent, Skill,
+MCP, Compact, and resume journeys. WEB31-P0-01..12 additionally qualify the multi-project shell,
+read-only engineering panels, real PTY and responsive/accessibility contract. See the
+[`v0.3.1 Web Workbench plan`](docs/plan/v0.3.1-web-workbench-professional-shell-plan.md) and
+[`v0.3.1 E2E qualification plan`](docs/test/v0.3.1-web-workbench-e2e-plan.md).
 
 ## Security
 

package/README.zh-CN.md

@@ -1,13 +1,42 @@
 # Orion Code
 
-面向终端的目标驱动 Coding Agent。
-
-> v0.2.2：让 Thread 会话恢复具备单会话故障隔离，安全恢复中断的工具历史，并确保窄终端
-> 始终可见 Goal 已用 token。
-
-[English](README.md) · [架构主计划](docs/plan/v0.2.0-dsh-harness-redesign-plan.md) ·
-[迁移指南](docs/migration/v0.1.9-to-v0.2.0.md) ·
-[准出清单](docs/plan/v0.2.0-release-checklist.md)
+面向终端与浏览器、本地优先的目标驱动 Coding Agent。
+
+> v0.3.1 候选版本：一套 Orion Runtime，同时提供本地 Web Workbench 与既有 TUI/terminal。
+> Candidate 源码不代表已经创建 npm 发布或 Git tag。
+
+[English](README.md) ·
+[v0.3.1 专业工作台方案](docs/plan/v0.3.1-web-workbench-professional-shell-plan.md) ·
+[v0.3.1 Web API](docs/architecture/v0.3.1-web-api.yaml) ·
+[v0.3.1 E2E 方案](docs/test/v0.3.1-web-workbench-e2e-plan.md) ·
+[v0.3.1 迁移](docs/migration/v0.3.0-to-v0.3.1.md) ·
+[v0.3.0 Web 方案](docs/plan/v0.3.0-web-workbench-plan.md) ·
+[Settings 方案](docs/plan/v0.3.0-settings-integration-plan.md) ·
+[Node 兼容方案](docs/plan/v0.3.0-node-runtime-compatibility-plan.md) ·
+[Web API](docs/architecture/v0.3.0-web-api.yaml) ·
+[迁移指南](docs/migration/v0.2.2-to-v0.3.0.md) ·
+[Settings 迁移](docs/migration/v0.2.2-to-v0.3.0-settings.md) ·
+[真实状态图册](docs/assets/screenshots/v0.3.0-web/README.md)
+
+## v0.3.1 包含什么
+
+- **一个 Runtime、两个交互界面。** `orion web` 与终端产品共用 product bootstrap、
+  AgentRuntimeController、Session/Thread、ToolGateway、审批、Goal、Plan、Skills 和 MCP；浏览器不另起
+  一套 agent loop。
+- **可恢复的 Web 工作台。** React 界面覆盖工作区/会话、对话与工具活动、BUILD/PLAN/AUTO、follow-up、
+  interrupt、审批、Goal/Plan、模型/effort、Skills/MCP 和诊断。快照与 cursor replay 负责刷新和 SSE
+  重连恢复。
+- **专业项目工作台。** 左侧展示已注册项目并懒加载 Session，中间仍是唯一 Agent 会话。右侧可变宽面板
+  提供 Agent、审阅、终端、文件和 Git；文件/Git/审阅是有界只读投影，终端是显式启动、与 Session
+  history 和 SSE 隔离的临时真实 PTY。
+- **本地安全边界。** Host 只绑定 `127.0.0.1`；写请求必须携带精确 Origin、进程 nonce、JSON body 和
+  幂等键。响应设置严格 CSP，浏览器 payload 经过脱敏，大型工具结果按字节分页读取。
+- **Host 管理的 Settings。** 外观、默认模型、工作区 Effort 与全局工具确认策略统一进入严格、带
+  revision 的 `orion.json` Coordinator。原子批量保存、文件锁内 CAS、外部编辑 invalidation、
+  last-good 恢复与明确的来源/作用域/生效时机，让浏览器、slash 命令、TUI 与 Runtime 使用同一持久真相。
+- **有边界地参考 DSH。** 方案基于固定 DeepSeek Harness revision 做了源码审计。DSH Web 实际使用
+  POST 加两条下行 WebSocket；Orion 有意选择 JSON HTTP 加一条可 replay 的 SSE，同时保留 Orion 的
+  Model/Skills/MCP 边界。
 
 ## v0.2.0 带来了什么
 
@@ -39,12 +68,13 @@ MCP 仍是用户可见的扩展边界。
 
 ## 安装
 
-支持 Node.js 20、22、24。
+支持 Node.js 22.12+、24 和 26。生产环境建议使用 Node 24 LTS，当前开发环境也支持 Node 26
+Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 
-安装已发布的 `0.2.2` 版本：
+当 npm 已存在不可变的 `0.3.1` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.2.2
+npm install -g @orion-agents/orion-code@0.3.1
 orion --version
 orion doctor
 ```
@@ -101,6 +131,9 @@ Orion 读取 `~/.orion-code/orion.json`。可从
 ```bash
 orion                         # 默认产品 TUI
 orion --ui terminal           # 技术诊断 terminal fallback
+orion web                     # 启动本地 Web Workbench 并打开浏览器
+orion web --no-open --port 0  # 使用操作系统分配的 loopback 端口
+orion web --cwd /path/to/repo # 指定另一个已存在工作区
 orion -p "解释这个仓库"       # 实验性的非交互模式
 orion -p --output-format json "运行 focused tests"
 orion diff
@@ -109,6 +142,33 @@ orion commit
 
 `orion -p` 是早期实验性的非交互入口；需要确认弹层或实时 steering 的任务应使用 TUI。
 
+### 本地 Web Workbench
+
+`orion web` 在同一个 loopback origin 提供打包后的客户端与 `/api/v1/*`，v0.3.1 不提供 LAN bind。
+Provider 凭据仍通过 Orion 配置/环境变量管理；浏览器负责选择工作区和会话、执行或 steer 任务、回答
+审批并查看运行态。关闭或刷新 tab 不会替用户批准/拒绝，pending approval 仍由 Runtime 持有；停止
+Host 时会 abort 并 fail-closed。
+
+浏览器只展示已提交 Plan receipt 的 `body`、`returnMode`、`digest`，不会额外插入 review gate。
+PLAN 提交后仍由既有 Runtime 恢复 BUILD/AUTO，并在新的 logical turn 中启动实现。
+
+多项目导航不会创建多个 Runtime；跨项目 Session 选择是一次带 revision guard 的原子 Context 切换。
+桌面右栏可用 IDE 式鼠标拖动在 320–720px 间调整，不提供键盘精细调宽；窄屏自动使用 drawer，且不覆盖
+桌面宽度偏好。文件、Git 和审阅保持只读；创建终端需要显式 user gesture，短期 ticket 与输出均不进入
+Workbench SSE。
+
+#### Host 管理的 Settings
+
+Settings dialog 从当前 Host 读取设置，不把浏览器存储当成第二配置真源。主题和减少动效会跨刷新、端口
+和 Host 重启保留；默认模型只影响新建 Session，当前 Session 仍通过 `/model` 或会话控制显式切换；
+Effort 是当前 workspace 的 project default，Session override 优先；工具确认是全局策略，只能在 Runtime
+idle 时保存，并从下一个 logical request 生效。`allow` 不会绕过 hard policy、sandbox 或工作区边界。
+
+每次保存都是一次原子 CAS batch。并发标签页或外部 `orion.json` 编辑会显示冲突但保留草稿；非法 JSON
+只会让页面进入 invalid 状态，Runtime 继续使用 last-good，Web 绝不覆盖坏文件。Provider 凭据不会进入
+Web API，页面只显示 readiness，打开本地配置文件的动作也不接受 path。优先级、旧 appearance 一次迁移
+和回滚方法见 [Settings 迁移说明](docs/migration/v0.2.2-to-v0.3.0-settings.md)。
+
 ### BUILD、PLAN、AUTO
 
 按 `Shift+Tab` 循环 `BUILD → PLAN → AUTO`。状态栏和输入框边框会显示当前模式。Mode 决定工作流，
@@ -179,11 +239,14 @@ npm run bench:harness:baseline
 npm run bench:harness
 npm run bench:harness:compare -- <baseline.json> <candidate.json>
 npm run prepublishOnly
+npm run test:web-e2e -- --grep @settings
 ```
 
-正式准出还会只构建一次 exact tarball，并在 Node 20/22/24 安装同一个 hash，验证 package identity、
-native SQLite、TUI、terminal、print、Goal、subagent、Skill、MCP、Compact 与 resume。详见
-[`v0.2.0 准出清单`](docs/plan/v0.2.0-release-checklist.md)。
+正式准出还会只构建一次 exact tarball，并在 Node 22/24/26 安装同一个 hash，验证 package identity、
+native SQLite、TUI、terminal、print、Web、Goal、subagent、Skill、MCP、Compact 与 resume；
+WEB31-P0-01..12 还会验证多项目工作台、只读工程面板、真实 PTY、响应式与无障碍合同。详见
+[`v0.3.1 Web Workbench 方案`](docs/plan/v0.3.1-web-workbench-professional-shell-plan.md)与
+[`v0.3.1 E2E 资格计划`](docs/test/v0.3.1-web-workbench-e2e-plan.md)。
 
 ## 安全
 

package/bin/orion

@@ -4,6 +4,16 @@ const path = require('path');
 const os = require('os');
 const fs = require('fs');
 
+const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+const supportedNodeRuntime =
+  (nodeMajor === 22 && nodeMinor >= 12) || nodeMajor === 24 || nodeMajor === 26;
+if (!supportedNodeRuntime) {
+  console.error(
+    `Orion Code requires Node.js 22.12+, 24, or 26; current runtime is ${process.versions.node}.`
+  );
+  process.exit(1);
+}
+
 // ============================================================================
 // Multi-path .env loading
 //
@@ -22,22 +32,23 @@ function loadEnvFile(filePath) {
 }
 
 const envFilesLoaded = [];
+const loadConfiguredEnvFiles = process.env.ORION_CODE_DISABLE_ENV_FILES !== '1';
 
 // 1. Global config: ~/.orion-code.env
 const globalEnv = path.join(os.homedir(), '.orion-code.env');
-if (loadEnvFile(globalEnv)) {
+if (loadConfiguredEnvFiles && loadEnvFile(globalEnv)) {
   envFilesLoaded.push(globalEnv);
 }
 
 // 2. Current working directory: ./.env
 const localEnv = path.join(process.cwd(), '.env');
-if (loadEnvFile(localEnv)) {
+if (loadConfiguredEnvFiles && loadEnvFile(localEnv)) {
   envFilesLoaded.push(localEnv);
 }
 
 // 3. Package directory (development fallback)
 const packageEnv = path.join(__dirname, '..', '.env');
-if (loadEnvFile(packageEnv)) {
+if (loadConfiguredEnvFiles && loadEnvFile(packageEnv)) {
   envFilesLoaded.push(packageEnv);
 }
 
@@ -53,4 +64,4 @@ if (fs.existsSync(distCli)) {
 } else {
   require('ts-node').register({ transpileOnly: true });
   require(srcCli);
-}
+}