@orion-agents/orion-code 0.3.7 → 0.3.10

package/CHANGELOG.md

@@ -22,6 +22,54 @@ which is **not** a pass.
 
 ## [Unreleased]
 
+## [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: 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
+
+- `orion web --background`: starts the Web Workbench host detached from the
+  terminal, writes a pidfile (`~/.orion-code/web-host.<port>.pid`), redirects
+  logs to `~/.orion-code/logs/web-<port>.log` and prints URL/pid.
+- `orion web status|stop|restart [--port <number>]`: pidfile-based host
+  management without third-party supervisors. Still binds 127.0.0.1 and keeps
+  the fail-closed approval/context/sandbox semantics unchanged (issue #247).
+
+### Fixed
+
+- Issue-sweep triage: #222 (blank session rename), #223 (failed create leaves a
+  persisted active session), #234 (URL userinfo password starting with `token:`),
+  #238 (busy state-write clearing processing), #242 (stale Settings save into the
+  newly active workspace) were all already resolved on `main` — closed with
+  source evidence.
+- Web redaction now covers uppercase X-prefixed environment assignments
+  (`X_CLIENT_SECRET=…`, `CLIENT_SECRET=…`, `AUTH_TOKEN=…`) whose secret suffix
+  hides behind underscore word characters (issue #241).
+- Cmd/Ctrl+B can again open the Project Navigator at 761–799px: expanding the
+  navigation preference now resolves to a drawer and opens it explicitly instead
+  of leaving an invisible drawer (issue #226).
+
+### Tests
+
+- `redaction-xprefixed-env` suite: X-prefixed env values, bare uppercase
+  assignments, #234 userinfo regression, #241 JSON keys.
+
 ## [0.3.7] — CANDIDATE
 
 > **Status: candidate.** This work is isolated on the codex/v0.3.7 worktree (left project
@@ -73,7 +121,6 @@ which is **not** a pass.
   112 cases green. E2E: `web-v037-session-lifecycle.spec.ts` (archive/restore, delete-confirm,
   tags round-trip) runs in CI.
 
-
 ## [0.3.6] — CANDIDATE
 
 > **Status: candidate.** This work is isolated on the codex/v0.3.6 worktree (pure web
@@ -111,7 +158,6 @@ which is **not** a pass.
 - Markdown heading off-by-one: `##` renders as `<h2>` (was `<h3>`), a lone `#` no longer
   collapses to `<h6>`; >6 hashes stay a plain paragraph per GFM.
 
-
 ## [0.3.5] — CANDIDATE
 
 > **Status: candidate.** This work is isolated on the codex/v0.3.5 worktree. It is not

package/README.md

@@ -2,12 +2,10 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.7 candidate — a left project-rail interaction release on top of the v0.3.6 work:
-> shortened connection copy, a keyboard-reachable per-Session overflow menu
-> (rename / tags / archive / delete with confirmation), persisted Session tags with
-> rail badges, an archived-Session section with restore, and a friendlier
-> "打开或新增项目" workspace dialog. 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) ·
@@ -172,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.7
+npm install -g @orion-agents/orion-code@0.3.10
 orion --version
 orion doctor
 ```
@@ -260,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,10 +2,10 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.7 候选版本：左侧项目栏交互发布（基于 v0.3.6 之上）—— 状态文案精简、会话行键盘可达
-> 操作菜单（重命名 / 标签 / 归档 / 删除含确认）、可持久化会话标签与行内徽章、已归档会话区一键还原、
-> 以及更友好的「打开或新增项目」工作区对话框。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) ·
@@ -102,7 +102,7 @@ Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 当 npm 已存在不可变的 `0.3.4` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.7
+npm install -g @orion-agents/orion-code@0.3.10
 orion --version
 orion doctor
 ```
@@ -186,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

@@ -18,6 +18,8 @@ const product_bootstrap_1 = require("./runtime/product-bootstrap");
 const command_1 = require("./migration/command");
 const version_1 = require("./product/version");
 const web_1 = require("./web");
+const host_daemon_1 = require("./web/host-daemon");
+const cli_options_1 = require("./web/cli-options");
 const BRAND = chalk_1.default.hex('#FF6B35');
 const ACCENT = chalk_1.default.hex('#00D4AA');
 const DIM = chalk_1.default.dim;
@@ -52,41 +54,46 @@ function showCliHelp() {
     console.log(DIM('tui is the default product UI. terminal is the technical fallback; print is experimental.'));
     console.log();
 }
-function parseWebCliOptions(args) {
-    let port = 3080;
-    let open = true;
-    let cwd = process.cwd();
-    for (let index = 0; index < args.length; index++) {
-        const argument = args[index];
-        if (argument === '--no-open') {
-            open = false;
-            continue;
+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 (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);
+    const status = (0, host_daemon_1.hostDaemonStatus)(options.port);
+    if (command === 'status') {
+        if (status.state === 'running') {
+            console.log(`orion web is running: ${status.pidfile.url} (pid ${status.pidfile.pid})`);
+            console.log(`workspace ${status.pidfile.workspace} · started ${new Date(status.pidfile.startedAt).toISOString()}`);
         }
-        if (argument === '--port' || argument.startsWith('--port=')) {
-            const portValue = argument === '--port' ? args[++index] : argument.slice('--port='.length);
-            if (!portValue || !/^\d+$/u.test(portValue)) {
-                throw new Error('--port must be an integer from 0 through 65535.');
-            }
-            port = Number(portValue);
-            if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
-                throw new Error('--port must be an integer from 0 through 65535.');
-            }
-            continue;
+        else if (status.state === 'stale') {
+            console.log(`orion web is not running (stale pidfile for pid ${status.pid} on port ${status.port}).`);
         }
-        if (argument === '--cwd' || argument.startsWith('--cwd=')) {
-            const cwdValue = argument === '--cwd' ? args[++index] : argument.slice('--cwd='.length);
-            if (!cwdValue?.trim())
-                throw new Error('--cwd requires a directory path.');
-            cwd = cwdValue;
-            continue;
+        else {
+            console.log(`orion web is not running on port ${options.port}.`);
         }
-        throw new Error(`Unknown orion web option: ${argument}`);
+        return;
     }
-    return { port, open, cwd };
-}
-function showWebHelp() {
-    console.log('Usage: orion web [--port <number>] [--no-open] [--cwd <directory>]');
-    console.log('Starts the local-only Web Workbench on 127.0.0.1.');
+    const result = await (0, host_daemon_1.stopBackgroundHost)(options.port);
+    if (result === 'stopped')
+        console.log(`orion web on port ${options.port} stopped.`);
+    else
+        console.log(`orion web was not running on port ${options.port}.`);
 }
 function parseCliOptions(args) {
     let uiRenderer = config_1.DEFAULT_UI_RENDERER;
@@ -159,7 +166,37 @@ async function main() {
             showWebHelp();
             return;
         }
-        await (0, web_1.runOrionWeb)(parseWebCliOptions(args.slice(1)));
+        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;
+        }
+        if (rest[0] === 'restart') {
+            await manageBackgroundHost('stop', rest.slice(1));
+            const restartOptions = (0, cli_options_1.parseWebCliOptions)(rest.slice(1));
+            await (0, web_1.runOrionWeb)({
+                ...restartOptions,
+                background: true,
+                backgroundArgs: webBackgroundArgs(restartOptions),
+            });
+            return;
+        }
+        const options = (0, cli_options_1.parseWebCliOptions)(rest);
+        await (0, web_1.runOrionWeb)({ ...options, backgroundArgs: webBackgroundArgs(options) });
         return;
     }
     if (args[0] === 'migrate') {

package/dist/services/redaction.js

@@ -69,6 +69,14 @@ const SECRET_PATTERNS = [
     // Anthropic / OpenAI-style long-lived keys that do not start with `sk-`.
     [/\bxai-[A-Za-z0-9]{16,}\b/g, '[REDACTED_SECRET]'],
     [/\bgsk_[A-Za-z0-9]{16,}\b/g, '[REDACTED_SECRET]'],
+    [
+        // Uppercase environment assignments with a secret-shaped suffix, e.g.
+        // `export X_CLIENT_SECRET=…` / `CLIENT_SECRET=…`. The generic lower-case
+        // field rules cannot match these because the underscore is a word
+        // character, so no boundary exists right before `client_secret` (issue #241).
+        /\b((?:[A-Z][A-Z0-9_]*_)?(?:CLIENT_SECRET|ACCESS_TOKEN|AUTH_TOKEN|SECRET_KEY|PRIVATE_KEY|SESSION_KEY|ENCRYPTION_KEY|DB_PASSWORD|API_KEY|API_TOKEN|CREDENTIALS?|SECRETS?)\s*=\s*)(["']?)[^\s"',;]+/gi,
+        '$1$2[REDACTED_SECRET]',
+    ],
     [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [REDACTED_SECRET]'],
 ];
 /** Field-name guard shared by browser/event and approval snapshot projections. */

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

@@ -0,0 +1,17 @@
+/**
+ * CLI option parsing for `orion web` (extracted from the CLI entry so the
+ * grammar has a unit-testable surface — issue #218 regression coverage).
+ */
+/**
+ * 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;
+    readonly cwd: string;
+    readonly background: boolean;
+}
+export declare function parseWebCliOptions(args: readonly string[]): WebCliOptions;
+//# sourceMappingURL=cli-options.d.ts.map

package/dist/web/cli-options.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * CLI option parsing for `orion web` (extracted from the CLI entry so the
+ * grammar has a unit-testable surface — issue #218 regression coverage).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WEB_PORT = void 0;
+exports.parseWebCliOptions = parseWebCliOptions;
+/**
+ * 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;
+    let cwd = process.cwd();
+    let background = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--background' || argument === '--daemon') {
+            background = true;
+            continue;
+        }
+        if (argument === '--no-open') {
+            open = false;
+            continue;
+        }
+        if (argument === '--port' || argument.startsWith('--port=')) {
+            const portValue = argument === '--port' ? args[++index] : argument.slice('--port='.length);
+            if (!portValue || !/^\d+$/u.test(portValue)) {
+                throw new Error('--port must be an integer from 0 through 65535.');
+            }
+            port = Number(portValue);
+            if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
+                throw new Error('--port must be an integer from 0 through 65535.');
+            }
+            continue;
+        }
+        if (argument === '--cwd' || argument.startsWith('--cwd=')) {
+            const cwdValue = argument === '--cwd' ? args[++index] : argument.slice('--cwd='.length);
+            if (!cwdValue?.trim())
+                throw new Error('--cwd requires a directory path.');
+            cwd = cwdValue;
+            continue;
+        }
+        throw new Error(`Unknown orion web option: ${argument}`);
+    }
+    return { port, open, cwd, background };
+}
+//# sourceMappingURL=cli-options.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Native background/daemon lifecycle for `orion web` (issue #247, S1+S2).
+ *
+ * A foreground `orion web --background` parent spawns the real host detached,
+ * waits for it to publish a pidfile under the config home, then returns. The
+ * detached child redirects its stdio to per-host log files and keeps the
+ * fail-closed approval / context / sandbox semantics untouched — this is a
+ * process-lifecycle concern only, still bound to 127.0.0.1.
+ *
+ * The pidfile shape is intentionally tiny and human-readable:
+ *
+ *   { "pid": 12345, "port": 4242, "url": "http://127.0.0.1:4242",
+ *     "startedAt": 1725000000000, "workspace": "/abs/path" }
+ */
+import { type ChildProcess } from 'child_process';
+export declare const HOST_PIDFILE_BASE = "web-host";
+export declare const HOST_DAEMON_CHILD_ENV = "ORION_WEB_DAEMON_CHILD";
+export declare const DAEMON_READY_TIMEOUT_MS = 8000;
+export declare const DAEMON_POLL_MS = 120;
+export interface HostPidfile {
+    readonly pid: number;
+    readonly port: number;
+    readonly url: string;
+    readonly workspace: string;
+    readonly startedAt: number;
+}
+export type HostDaemonStatus = {
+    readonly state: 'running';
+    readonly pidfile: HostPidfile;
+} | {
+    readonly state: 'stopped';
+} | {
+    readonly state: 'stale';
+    readonly pid: number;
+    readonly port: number;
+};
+export declare function hostLogsDirectory(): string;
+export declare function hostPidfilePath(port: number): string;
+export declare function parseHostPidfile(raw: string): HostPidfile | null;
+export declare function readHostPidfile(port: number): HostPidfile | null;
+export declare function writeHostPidfile(pidfile: HostPidfile): void;
+export declare function clearHostPidfile(port: number): void;
+/** Cross-platform process-liveness probe used by `status`. */
+export declare function isProcessAlive(pid: number): boolean;
+export declare function hostDaemonStatus(port: number): HostDaemonStatus;
+/**
+ * Parent-side entry for `--background`: spawn the host detached, redirect its
+ * stdio to `~/.orion-code/logs/web-<port>.log`, and wait for the pidfile so the
+ * foreground command can print the URL and exit cleanly.
+ */
+export declare function spawnBackgroundHost(options: {
+    readonly cwd: string;
+    readonly port: number;
+    readonly webArgs: readonly string[];
+}): Promise<{
+    readonly child: ChildProcess;
+    readonly pidfile: HostPidfile;
+}>;
+/** Terminate a background host by pidfile (SIGTERM, then escalate to SIGKILL). */
+export declare function stopBackgroundHost(port: number): Promise<'stopped' | 'not_running'>;
+//# sourceMappingURL=host-daemon.d.ts.map

package/dist/web/host-daemon.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAEMON_POLL_MS = exports.DAEMON_READY_TIMEOUT_MS = exports.HOST_DAEMON_CHILD_ENV = exports.HOST_PIDFILE_BASE = void 0;
+exports.hostLogsDirectory = hostLogsDirectory;
+exports.hostPidfilePath = hostPidfilePath;
+exports.parseHostPidfile = parseHostPidfile;
+exports.readHostPidfile = readHostPidfile;
+exports.writeHostPidfile = writeHostPidfile;
+exports.clearHostPidfile = clearHostPidfile;
+exports.isProcessAlive = isProcessAlive;
+exports.hostDaemonStatus = hostDaemonStatus;
+exports.spawnBackgroundHost = spawnBackgroundHost;
+exports.stopBackgroundHost = stopBackgroundHost;
+/**
+ * Native background/daemon lifecycle for `orion web` (issue #247, S1+S2).
+ *
+ * A foreground `orion web --background` parent spawns the real host detached,
+ * waits for it to publish a pidfile under the config home, then returns. The
+ * detached child redirects its stdio to per-host log files and keeps the
+ * fail-closed approval / context / sandbox semantics untouched — this is a
+ * process-lifecycle concern only, still bound to 127.0.0.1.
+ *
+ * The pidfile shape is intentionally tiny and human-readable:
+ *
+ *   { "pid": 12345, "port": 4242, "url": "http://127.0.0.1:4242",
+ *     "startedAt": 1725000000000, "workspace": "/abs/path" }
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const paths_1 = require("../product/paths");
+exports.HOST_PIDFILE_BASE = 'web-host';
+exports.HOST_DAEMON_CHILD_ENV = 'ORION_WEB_DAEMON_CHILD';
+exports.DAEMON_READY_TIMEOUT_MS = 8000;
+exports.DAEMON_POLL_MS = 120;
+function hostLogsDirectory() {
+    return (0, path_1.join)((0, paths_1.getConfigHome)(), 'logs');
+}
+function hostPidfilePath(port) {
+    return (0, path_1.join)((0, paths_1.getConfigHome)(), `${exports.HOST_PIDFILE_BASE}.${port}.pid`);
+}
+function parseHostPidfile(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== 'object')
+            return null;
+        const record = value;
+        if (typeof record.pid !== 'number' ||
+            typeof record.port !== 'number' ||
+            typeof record.url !== 'string' ||
+            typeof record.workspace !== 'string' ||
+            typeof record.startedAt !== 'number') {
+            return null;
+        }
+        return Object.freeze({
+            pid: record.pid,
+            port: record.port,
+            url: record.url,
+            workspace: record.workspace,
+            startedAt: record.startedAt,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function readHostPidfile(port) {
+    const path = hostPidfilePath(port);
+    if (!(0, fs_1.existsSync)(path))
+        return null;
+    try {
+        return parseHostPidfile((0, fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeHostPidfile(pidfile) {
+    (0, fs_1.mkdirSync)((0, paths_1.getConfigHome)(), { recursive: true });
+    (0, fs_1.writeFileSync)(hostPidfilePath(pidfile.port), JSON.stringify(pidfile, null, 2), 'utf8');
+}
+function clearHostPidfile(port) {
+    try {
+        (0, fs_1.rmSync)(hostPidfilePath(port), { force: true });
+    }
+    catch {
+        // Pidfile removal is best-effort: a locked/restricted filesystem must not
+        // turn `orion web stop` into a failure after the process is already gone.
+    }
+}
+/** Cross-platform process-liveness probe used by `status`. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function hostDaemonStatus(port) {
+    const pidfile = readHostPidfile(port);
+    if (!pidfile)
+        return { state: 'stopped' };
+    if (isProcessAlive(pidfile.pid)) {
+        return { state: 'running', pidfile };
+    }
+    return { state: 'stale', pid: pidfile.pid, port };
+}
+/** Build the argument vector used to re-launch the current CLI detached. */
+function childArgs(webArgs) {
+    const entry = process.argv[1];
+    if (!entry)
+        throw new Error('Unable to determine the CLI entry to relaunch.');
+    return [entry, 'web', ...webArgs];
+}
+/**
+ * Parent-side entry for `--background`: spawn the host detached, redirect its
+ * stdio to `~/.orion-code/logs/web-<port>.log`, and wait for the pidfile so the
+ * foreground command can print the URL and exit cleanly.
+ */
+function spawnBackgroundHost(options) {
+    const logsDirectory = hostLogsDirectory();
+    (0, fs_1.mkdirSync)(logsDirectory, { recursive: true });
+    const logPath = (0, path_1.join)(logsDirectory, `web-${options.port}.log`);
+    const output = (0, fs_1.openSync)(logPath, 'a');
+    const child = (0, child_process_1.spawn)(process.execPath, childArgs(options.webArgs), {
+        cwd: options.cwd,
+        detached: true,
+        stdio: ['ignore', output, output],
+        env: { ...process.env, [exports.HOST_DAEMON_CHILD_ENV]: '1' },
+    });
+    child.unref();
+    return new Promise((resolve, reject) => {
+        const deadline = Date.now() + exports.DAEMON_READY_TIMEOUT_MS;
+        const poll = () => {
+            const pidfile = readHostPidfile(options.port);
+            if (pidfile && pidfile.pid === child.pid) {
+                resolve({ child, pidfile });
+                return;
+            }
+            if (child.exitCode !== null || child.signalCode !== null) {
+                reject(new Error(`Background host exited before readiness (code ${child.exitCode ?? 'signal'}); see ${logPath}`));
+                return;
+            }
+            if (Date.now() > deadline) {
+                reject(new Error(`Background host did not become ready within ${exports.DAEMON_READY_TIMEOUT_MS}ms; see ${logPath}`));
+                return;
+            }
+            setTimeout(poll, exports.DAEMON_POLL_MS);
+        };
+        poll();
+    });
+}
+/** Terminate a background host by pidfile (SIGTERM, then escalate to SIGKILL). */
+function stopBackgroundHost(port) {
+    const status = hostDaemonStatus(port);
+    if (status.state !== 'running')
+        return Promise.resolve('not_running');
+    const { pidfile } = status;
+    return new Promise(resolve => {
+        try {
+            process.kill(pidfile.pid, 'SIGTERM');
+        }
+        catch {
+            clearHostPidfile(port);
+            resolve('stopped');
+            return;
+        }
+        const deadline = Date.now() + 4000;
+        const poll = () => {
+            if (!isProcessAlive(pidfile.pid)) {
+                clearHostPidfile(port);
+                resolve('stopped');
+                return;
+            }
+            if (Date.now() > deadline) {
+                try {
+                    process.kill(pidfile.pid, 'SIGKILL');
+                }
+                catch {
+                    // Already gone.
+                }
+                clearHostPidfile(port);
+                resolve('stopped');
+                return;
+            }
+            setTimeout(poll, 100);
+        };
+        poll();
+    });
+}
+//# sourceMappingURL=host-daemon.js.map

package/dist/web/launch.d.ts

@@ -2,6 +2,9 @@ export interface RunOrionWebOptions {
     readonly cwd: string;
     readonly port?: number;
     readonly open?: boolean;
+    readonly background?: boolean;
+    /** Full `orion web` arguments of the relaunched child (excludes --background). */
+    readonly backgroundArgs?: readonly string[];
     readonly stdout?: Pick<NodeJS.WriteStream, 'write'>;
     readonly stderr?: Pick<NodeJS.WriteStream, 'write'>;
 }