@orion-agents/orion-code 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -22,12 +22,25 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.9] — CANDIDATE
+## [0.3.10] — CANDIDATE
+
+> **Status: candidate.** Not merged, tagged or published to npm.
+
+### Added
+
+- The local Web host defaults to port **4242** (M42, the Orion Nebula) instead of
+  the generic 3080; `DEFAULT_WEB_PORT` is the single source shared by
+  cli-options, launch and server.
+- `orion web start [--port N]`: idempotent background-host start (prints the URL
+  when already running); start/restart/`--background` share one arg builder.
+- README documents the background-host lifecycle (`start|status|stop|restart`,
+  pidfile/log locations) and the launchd foreground-supervision recipe.
 
 ## [0.3.9] — CANDIDATE
 
-> **Status: candidate.** Deterministic-bug-fix release + background host lifecycle
-> (issue #247 S1/S2). Not merged, tagged or published to npm.
+> **Status: npm-published.** `@orion-agents/orion-code@0.3.9` is available through the npm
+> registry (latest tag); deterministic-bug-fix release + background host lifecycle
+> (issue #247 S1/S2). Published 2026-09-04; git tag/release may lag.
 
 ### Added
 

package/README.md

@@ -2,10 +2,10 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.9 candidate — deterministic-bug sweep over the open issue set plus a native
-> background-host lifecycle: `orion web --background` with pidfile/log management
-> (`orion web status|stop|restart`). Candidate source is not an npm publication,
-> Git tag, or merge-ready release.
+> v0.3.10 candidate — the local Web host now defaults to port 4242 (M42, the
+> Orion Nebula) with a first-class lifecycle: `orion web start|status|stop|restart`
+> manage a detached host (pidfile + logs), and `--background` stays supported.
+> Candidate source is not an npm publication, Git tag, or merge-ready release.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.7 plan](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -170,7 +170,7 @@ current development environments. Node 20 is upstream EOL and is no longer a v0.
 After the immutable `0.3.5` npm receipt exists:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.9
+npm install -g @orion-agents/orion-code@0.3.10
 orion --version
 orion doctor
 ```
@@ -258,6 +258,30 @@ atomic, revision-guarded Context transition. The left dock is 240–480px or a 4
 Narrow layouts use drawers without overwriting desktop widths. Files, Git and Review are read-only;
 terminal creation requires an explicit gesture and its ticket/output never enter Workbench SSE.
 
+#### Background host & lifecycle (v0.3.10)
+
+The Web Workbench binds **127.0.0.1 only**; the default port is **4242** (M42, the
+Orion Nebula) so it never collides with common dev-tool ports.
+
+```bash
+orion web                          # foreground; open http://127.0.0.1:4242
+orion web --background             # detached host (pidfile + logs, survives terminal exit)
+orion web start [--port N]         # idempotent background start
+orion web status  [--port N]       # running pid/URL/workspace or stale report
+orion web restart [--port N]       # stop + start
+orion web stop    [--port N]       # graceful SIGTERM stop
+```
+
+The pidfile lives at `~/.orion-code/web-host.<port>.pid` and logs append to
+`~/.orion-code/logs/web-<port>.log`. Backgrounding is a process-lifecycle feature
+only: approval, context-revision and sandbox rules stay fail-closed, and the host
+never binds beyond loopback.
+
+For crash-restart and login autostart on macOS, register the **foreground** command
+(`orion web --no-open --port 4242 --cwd <dir>`) in a launchd LaunchAgent
+(`RunAtLoad` + `KeepAlive`) — do not combine it with `--background`, because
+launchd must supervise the host process itself.
+
 #### Host-managed Settings
 
 The Settings dialog reads from the active Host rather than treating browser storage as a second

package/README.zh-CN.md

@@ -2,9 +2,10 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.9 候选版本：对 OPEN issue 集的确定性 bug 清扫 + 原生后台 host 生命周期 ——
-> `orion web --background`（pidfile/日志）与 `orion web status|stop|restart` 管理。
-> Candidate 源码不代表已创建 npm 发布、Git tag 或达到可合并状态。
+> v0.3.10 候选版本：本地 Web host 默认端口改为 **4242**（M42，猎户座大星云），
+> 并新增一等生命周期管理：`orion web start|status|stop|restart` 管理脱离终端的
+> 后台 host（pidfile + 日志），`--background` 仍可用。Candidate 源码不代表已创建
+> npm 发布、Git tag 或达到可合并状态。
 
 [English](README.md) ·
 [v0.3.7 方案](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -101,7 +102,7 @@ Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 当 npm 已存在不可变的 `0.3.4` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.9
+npm install -g @orion-agents/orion-code@0.3.10
 orion --version
 orion doctor
 ```
@@ -185,6 +186,23 @@ Host 时会 abort 并 fail-closed。
 键盘精细调宽。窄屏自动使用 drawer，且不覆盖桌面宽度偏好。文件、Git 和审阅保持只读；创建终端需要
 显式 user gesture，短期 ticket 与输出均不进入 Workbench SSE。
 
+#### 后台运行与管理（v0.3.10）
+
+Web Workbench 只绑定 **127.0.0.1**；默认端口为 **4242**（M42，猎户座大星云），避免与常用开发端口冲突。
+
+```bash
+orion web                          # 前台启动；打开 http://127.0.0.1:4242
+orion web --background             # 脱离终端的后台 host（pidfile + 日志）
+orion web start [--port N]         # 幂等后台启动
+orion web status  [--port N]       # 查看运行 pid/URL/workspace
+orion web restart [--port N]       # 重启
+orion web stop    [--port N]       # 优雅停止
+```
+
+pidfile 位于 `~/.orion-code/web-host.<port>.pid`，日志追加到 `~/.orion-code/logs/web-<port>.log`。后台化只涉及进程生命周期：审批/上下文版本/沙箱规则保持 fail-closed，host 绝不绑定局域网。
+
+macOS 需要崩溃自动重启与开机自启时，用 launchd LaunchAgent 托管**前台**命令（`orion web --no-open --port 4242 --cwd <dir>`，`RunAtLoad`+`KeepAlive`）——不要与 `--background` 混用，launchd 必须直接监管 host 进程。
+
 #### Host 管理的 Settings
 
 Settings dialog 从当前 Host 读取设置，不把浏览器存储当成第二配置真源。主题和减少动效会跨刷新、端口

package/dist/cli.js

@@ -58,10 +58,20 @@ function showWebHelp() {
     console.log('Usage: orion web [--port <number>] [--no-open] [--cwd <directory>] [--background]');
     console.log('Starts the local-only Web Workbench on 127.0.0.1.');
     console.log('  --background      run detached in the background (pidfile + logs under ~/.orion-code)');
+    console.log('orion web start [--port <number>] [--cwd <directory>] [--no-open]');
     console.log('orion web status [--port <number>]');
     console.log('orion web stop [--port <number>]');
     console.log('orion web restart [--port <number>]');
-    console.log('  Manage a background host started with --background.');
+    console.log('  Manage a background host started with --background (start starts one).');
+}
+function webBackgroundArgs(options) {
+    return [
+        ...(options.open ? [] : ['--no-open']),
+        '--port',
+        String(options.port),
+        '--cwd',
+        options.cwd,
+    ];
 }
 async function manageBackgroundHost(command, args) {
     const options = (0, cli_options_1.parseWebCliOptions)(args);
@@ -157,6 +167,20 @@ async function main() {
             return;
         }
         const rest = args.slice(1);
+        if (rest[0] === 'start') {
+            const startOptions = (0, cli_options_1.parseWebCliOptions)(rest.slice(1));
+            const current = (0, host_daemon_1.hostDaemonStatus)(startOptions.port);
+            if (current.state === 'running') {
+                console.log(`orion web is already running: ${current.pidfile.url} (pid ${current.pidfile.pid})`);
+                return;
+            }
+            await (0, web_1.runOrionWeb)({
+                ...startOptions,
+                background: true,
+                backgroundArgs: webBackgroundArgs(startOptions),
+            });
+            return;
+        }
         if (rest[0] === 'status' || rest[0] === 'stop') {
             await manageBackgroundHost(rest[0], rest.slice(1));
             return;
@@ -167,25 +191,12 @@ async function main() {
             await (0, web_1.runOrionWeb)({
                 ...restartOptions,
                 background: true,
-                backgroundArgs: [
-                    ...(restartOptions.open ? [] : ['--no-open']),
-                    '--port',
-                    String(restartOptions.port),
-                    '--cwd',
-                    restartOptions.cwd,
-                ],
+                backgroundArgs: webBackgroundArgs(restartOptions),
             });
             return;
         }
         const options = (0, cli_options_1.parseWebCliOptions)(rest);
-        const backgroundArgs = [
-            ...(options.open ? [] : ['--no-open']),
-            '--port',
-            String(options.port),
-            '--cwd',
-            options.cwd,
-        ];
-        await (0, web_1.runOrionWeb)({ ...options, backgroundArgs });
+        await (0, web_1.runOrionWeb)({ ...options, backgroundArgs: webBackgroundArgs(options) });
         return;
     }
     if (args[0] === 'migrate') {

package/dist/web/cli-options.d.ts

@@ -2,7 +2,11 @@
  * CLI option parsing for `orion web` (extracted from the CLI entry so the
  * grammar has a unit-testable surface — issue #218 regression coverage).
  */
-export declare const DEFAULT_WEB_PORT = 3080;
+/**
+ * M42 (Orion Nebula) — the local Web Workbench host binds this by default so
+ * `orion web` never collides with common dev-tool ports.
+ */
+export declare const DEFAULT_WEB_PORT = 4242;
 export interface WebCliOptions {
     readonly port: number;
     readonly open: boolean;

package/dist/web/cli-options.js

@@ -6,7 +6,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_WEB_PORT = void 0;
 exports.parseWebCliOptions = parseWebCliOptions;
-exports.DEFAULT_WEB_PORT = 3080;
+/**
+ * M42 (Orion Nebula) — the local Web Workbench host binds this by default so
+ * `orion web` never collides with common dev-tool ports.
+ */
+exports.DEFAULT_WEB_PORT = 4242;
 function parseWebCliOptions(args) {
     let port = exports.DEFAULT_WEB_PORT;
     let open = true;

package/dist/web/host-daemon.d.ts

@@ -9,7 +9,7 @@
  *
  * The pidfile shape is intentionally tiny and human-readable:
  *
- *   { "pid": 12345, "port": 3080, "url": "http://127.0.0.1:3080",
+ *   { "pid": 12345, "port": 4242, "url": "http://127.0.0.1:4242",
  *     "startedAt": 1725000000000, "workspace": "/abs/path" }
  */
 import { type ChildProcess } from 'child_process';

package/dist/web/host-daemon.js

@@ -22,7 +22,7 @@ exports.stopBackgroundHost = stopBackgroundHost;
  *
  * The pidfile shape is intentionally tiny and human-readable:
  *
- *   { "pid": 12345, "port": 3080, "url": "http://127.0.0.1:3080",
+ *   { "pid": 12345, "port": 4242, "url": "http://127.0.0.1:4242",
  *     "startedAt": 1725000000000, "workspace": "/abs/path" }
  */
 const child_process_1 = require("child_process");

package/dist/web/launch.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runOrionWeb = runOrionWeb;
+const cli_options_1 = require("./cli-options");
 const child_process_1 = require("child_process");
 const server_1 = require("./server");
 const host_daemon_1 = require("./host-daemon");
@@ -8,7 +9,7 @@ async function runOrionWeb(options) {
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
     const isDaemonChild = process.env[host_daemon_1.HOST_DAEMON_CHILD_ENV] === '1';
-    const port = options.port ?? 3080;
+    const port = options.port ?? cli_options_1.DEFAULT_WEB_PORT;
     if (options.background && !isDaemonChild) {
         // Parent side: launch detached and wait for its pidfile, then print the URL.
         const { pidfile } = await (0, host_daemon_1.spawnBackgroundHost)({

package/dist/web/server.js

@@ -9,12 +9,13 @@ const version_1 = require("../product/version");
 const redaction_1 = require("../services/redaction");
 const protocol_1 = require("./protocol");
 const errors_1 = require("./errors");
+const cli_options_1 = require("./cli-options");
 const terminal_server_1 = require("./terminal-server");
 const workbench_controller_1 = require("./workbench-controller");
 const HOST = '127.0.0.1';
 const API_PREFIX = '/api/v1';
 async function startOrionWebServer(options) {
-    const requestedPort = options.port ?? 3080;
+    const requestedPort = options.port ?? cli_options_1.DEFAULT_WEB_PORT;
     if (!Number.isSafeInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
         throw new Error('Web port must be an integer from 0 through 65535.');
     }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@orion-agents/orion-code",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@orion-agents/orion-code",
-      "version": "0.3.9",
+      "version": "0.3.10",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-agents/orion-code",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Orion Code - local-first goal-driven coding agent for terminal and Web.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",