From 306a2e3ecd98738d086c6b543adb53e39a42f627 Mon Sep 17 00:00:00 2001 From: Noah-Bytes Date: Mon, 20 Jul 2026 23:37:46 +0800 Subject: [PATCH 1/5] docs: clarify start runs an independent process, add optional service setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Noah reported that closing the CLI/agent session that launched `codex-openmax start` doesn't stop the adapter — the docs never explained that `start` is its own process, not a child tied to the invoking session's lifetime. Adds: an explicit note on that behavior + how to stop it, and an optional "running as a persistent service" section (systemd user service / pm2) for anyone who wants it to survive a reboot. Marked optional and requiring the user's explicit go-ahead first — it changes system state (a boot-persistent service), unlike the default init/start flow. --- README.md | 44 +++++++++++++++++++++++++++++++++++++++ docs/onboarding-design.md | 3 ++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f8099a..3c6cd0f 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,50 @@ connects the SDK bridge, and serves the adapter until `SIGINT`/`SIGTERM`. Requir binary on `PATH`. Full field contract + security notes: [`docs/onboarding-design.md`](docs/onboarding-design.md). +**`start` is an independent process, not tied to your current shell session.** It keeps +running after you close the terminal, CLI, or agent session you launched it from — closing +that session does not stop the adapter. To stop it, `Ctrl+C` the process (or `kill` its PID) +in the terminal it's actually running in. + +### Running as a persistent service (optional) + +If you want `codex-openmax` to survive a reboot or keep running unattended, run `start` under +a process manager instead of a bare foreground shell. **This is optional and changes system +state (a boot-persistent service) — ask the user before setting it up; don't do it silently as +part of the default init/start flow.** + +systemd (user service, survives reboot with `loginctl enable-linger`): + +```bash +mkdir -p ~/.config/systemd/user +cat > ~/.config/systemd/user/codex-openmax.service <<'UNIT' +[Unit] +Description=codex-openmax adapter + +[Service] +WorkingDirectory=%h/path/to/your/config-dir +ExecStart=codex-openmax start +Restart=on-failure + +[Install] +WantedBy=default.target +UNIT +systemctl --user daemon-reload +systemctl --user enable --now codex-openmax +loginctl enable-linger "$USER" # keep the user service running across reboots/logout +``` + +pm2: + +```bash +pm2 start codex-openmax --name codex-openmax -- start +pm2 save +pm2 startup # prints the command to enable pm2 itself on boot +``` + +Either way, run `codex-openmax init` once beforehand so `config.json` already exists in the +working directory the service starts from. + ## Layout ``` diff --git a/docs/onboarding-design.md b/docs/onboarding-design.md index fa93a0e..fef5257 100644 --- a/docs/onboarding-design.md +++ b/docs/onboarding-design.md @@ -99,7 +99,8 @@ Steps — self-register shape (invitation_id + invitation_token, no pre-provisio ## Non-goals (this PR) - No platform-side rendering (that's the workspace flow, tracked with luna/gavin). -- No daemonization/pm2 packaging (`start` runs foreground; supervisor integration later). +- No daemonization/pm2 packaging (`start` runs foreground; supervisor integration later — README + documents an optional systemd/pm2 setup as a workaround in the meantime). - No ws/daemon transport (P2 item ② — codex 0.144.5's `app-server --listen ws://`). ## Distribution (added after owner review, 2026-07-20) From 2e076788ad78f86e98769f868d358b9dd63d7280 Mon Sep 17 00:00:00 2001 From: Noah-Bytes Date: Mon, 20 Jul 2026 23:45:45 +0800 Subject: [PATCH 2/5] chore: bump version to 0.1.0-alpha.3 Doc-only release: ships the updated README (persistent-service / start-independent-process notes). No source changes since alpha.2. --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 51910fe..69b9507 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@openmaxai/codex-openmax", - "version": "0.1.0-alpha.2", + "version": "0.1.0-alpha.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@openmaxai/codex-openmax", - "version": "0.1.0-alpha.2", + "version": "0.1.0-alpha.3", "dependencies": { "@openmaxai/openmax-agent-sdk": "^1.0.1" }, diff --git a/package.json b/package.json index c97c52e..6ef53e5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@openmaxai/codex-openmax", - "version": "0.1.0-alpha.2", + "version": "0.1.0-alpha.3", "private": false, "description": "Codex CLI ⇆ OpenMax/CWS channel adapter (Category B): Layer 1 shared SDK bridge + Layer 2 runtime adapter.", "repository": { From cb48514c70456cac565537774a85889eb154265c Mon Sep 17 00:00:00 2001 From: Noah-Bytes Date: Mon, 20 Jul 2026 23:46:38 +0800 Subject: [PATCH 3/5] docs: stop hardcoding a specific npm version in README prose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Status section named a specific published version (0.1.0-alpha.0) that drifted stale after every release since — the npm badge above it already shows the live version. Reworded to reference the badge instead of a version string that needs updating on every bump. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3c6cd0f..798059b 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,11 @@ channel) to the OpenMax / CWS platform. ## Status -**Alpha — published.** `@openmaxai/codex-openmax@0.1.0-alpha.0` is on npm. P1 MVP (the +**Alpha — published** on npm (see the badge above for the current version). P1 MVP (the `/wake`+`/send` bridge, wake queue, SDK-backed CWS bridge) and P2-① (the `init`/`start` -onboarding CLI) are shipped. Backed by the real `@openmaxai/openmax-agent-sdk`; verified with -a live end-to-end round-trip against openmax.com. +onboarding CLI, incl. self-register) are shipped. Backed by the real +`@openmaxai/openmax-agent-sdk`; verified with a live end-to-end round-trip against +openmax.com. ## What it is From ebf842915f0daa61003bb62aa3c1c6bde003e830 Mon Sep 17 00:00:00 2001 From: Noah-Bytes Date: Mon, 20 Jul 2026 23:55:47 +0800 Subject: [PATCH 4/5] docs: clarify start's session-survival depends on launch method MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit zylos0t review (PR#11) flagged a real tension: the doc said start keeps running after closing the launching session, but also runs "foreground until SIGINT/SIGTERM" — a plain interactive foreground process normally gets SIGHUP (and exits) when its controlling terminal closes. Only a detached/backgrounded launch (no controlling tty, e.g. an onboarding agent spawning it for you) survives session close. Notes both cases so someone running it in a bare terminal isn't confused when it stops. --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 798059b..3ac39e1 100644 --- a/README.md +++ b/README.md @@ -80,10 +80,12 @@ connects the SDK bridge, and serves the adapter until `SIGINT`/`SIGTERM`. Requir binary on `PATH`. Full field contract + security notes: [`docs/onboarding-design.md`](docs/onboarding-design.md). -**`start` is an independent process, not tied to your current shell session.** It keeps -running after you close the terminal, CLI, or agent session you launched it from — closing -that session does not stop the adapter. To stop it, `Ctrl+C` the process (or `kill` its PID) -in the terminal it's actually running in. +**Whether closing your session stops `start` depends on how it was launched.** Run directly in +a bare interactive terminal, closing that terminal sends `SIGHUP` and it exits like any other +foreground process. Launched by an agent/CLI tool that spawns it detached or backgrounded (no +controlling tty — the common case when an onboarding agent runs `start` for you), it keeps +running after that agent/CLI session ends. Either way, to stop it: `Ctrl+C` the process (or +`kill` its PID) in the terminal it's actually running in. ### Running as a persistent service (optional) From 10104d149f73a5527e72a23903c8fc4be0211774 Mon Sep 17 00:00:00 2001 From: Noah-Bytes Date: Tue, 21 Jul 2026 00:08:38 +0800 Subject: [PATCH 5/5] docs: address zylos0t P3s on PR#11 (WorkingDirectory, linger, readability) - WorkingDirectory now uses a concrete path (%h/.codex-openmax) instead of a placeholder to find/replace. - loginctl enable-linger split out of the copy-paste systemd block into its own step with an explicit note that it's a system-level change beyond the service itself. - SIGHUP/session-survival paragraph split into two bullets for scannability. None of these are behavior changes; doc-only, no P1/P2 review findings. --- README.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3ac39e1..a798cc3 100644 --- a/README.md +++ b/README.md @@ -80,12 +80,16 @@ connects the SDK bridge, and serves the adapter until `SIGINT`/`SIGTERM`. Requir binary on `PATH`. Full field contract + security notes: [`docs/onboarding-design.md`](docs/onboarding-design.md). -**Whether closing your session stops `start` depends on how it was launched.** Run directly in -a bare interactive terminal, closing that terminal sends `SIGHUP` and it exits like any other -foreground process. Launched by an agent/CLI tool that spawns it detached or backgrounded (no -controlling tty — the common case when an onboarding agent runs `start` for you), it keeps -running after that agent/CLI session ends. Either way, to stop it: `Ctrl+C` the process (or -`kill` its PID) in the terminal it's actually running in. +**Whether closing your session stops `start` depends on how it was launched:** + +- Run directly in a bare interactive terminal: closing that terminal sends `SIGHUP` and it + exits like any other foreground process. +- Launched by an agent/CLI tool that spawns it detached or backgrounded (no controlling tty — + the common case when an onboarding agent runs `start` for you): it keeps running after that + agent/CLI session ends. + +Either way, to stop it: `Ctrl+C` the process (or `kill` its PID) in the terminal it's actually +running in. ### Running as a persistent service (optional) @@ -94,16 +98,16 @@ a process manager instead of a bare foreground shell. **This is optional and cha state (a boot-persistent service) — ask the user before setting it up; don't do it silently as part of the default init/start flow.** -systemd (user service, survives reboot with `loginctl enable-linger`): +systemd (user service): ```bash -mkdir -p ~/.config/systemd/user +mkdir -p ~/.config/systemd/user ~/.codex-openmax cat > ~/.config/systemd/user/codex-openmax.service <<'UNIT' [Unit] Description=codex-openmax adapter [Service] -WorkingDirectory=%h/path/to/your/config-dir +WorkingDirectory=%h/.codex-openmax ExecStart=codex-openmax start Restart=on-failure @@ -112,7 +116,14 @@ WantedBy=default.target UNIT systemctl --user daemon-reload systemctl --user enable --now codex-openmax -loginctl enable-linger "$USER" # keep the user service running across reboots/logout +``` + +To survive reboot/logout (not just this login session), a user service also needs linger +enabled — this is a system-level change (affects this Linux user account beyond the service +itself), so confirm with the user before running it: + +```bash +loginctl enable-linger "$USER" ``` pm2: