Skip to content

docs: clarify start runs an independent process, add optional service…#11

Merged
gavin09527 merged 5 commits into
mainfrom
docs/persistent-service-note
Jul 20, 2026
Merged

docs: clarify start runs an independent process, add optional service…#11
gavin09527 merged 5 commits into
mainfrom
docs/persistent-service-note

Conversation

@Noah-Bytes

Copy link
Copy Markdown
Collaborator

… setup

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.

What

Why

Test plan

  • npm test passes locally
  • npm run build passes locally

Checklist

  • No secrets / credentials committed
  • Semgrep / Gitleaks findings addressed, or a // nosemgrep: <rule-id> suppression is justified inline and approved by the project lead

Noah-Bytes added 3 commits July 20, 2026 23:37
… setup

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.
Doc-only release: ships the updated README (persistent-service /
start-independent-process notes). No source changes since alpha.2.
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.

@gavin09527 gavin09527 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — docs-only + alpha.3 bump, approving.

The 'start is an independent process / survives closing the session' note is the right thing to document (matches Noah's observation) and correctly tells you how to stop it (Ctrl+C / kill PID). The optional systemd/pm2 section is appropriately gated — 'ask the user before setting it up; don't do it silently' aligns with treating a boot-persistent service as an explicit, state-changing action; the unit/pm2 commands are sound and the 'run init once beforehand' note is correct. No secrets, no code changes.

One minor non-blocking doc-accuracy nuance: elsewhere the docs describe start as running 'in the foreground until SIGINT/SIGTERM', which is in slight tension with 'keeps running after you close the terminal'. A plain interactive foreground process usually gets SIGHUP'd and dies when its terminal closes; the survive-the-session behavior is specific to agent/CLI harnesses that launch it in a way that doesn't propagate SIGHUP (or detach it). Might be worth a half-sentence clarifying it's launch-context-dependent, so a user who ran it in a bare terminal and saw it stop on close isn't confused. Not blocking.

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.

@gavin09527 gavin09527 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM ✅ 文案与我先前的建议一致(start 取决于启动方式;补充可选的 service 说明)。已正式 approve。

…lity)

- WorkingDirectory now uses a concrete path (%h/.codex-openmax)
  instead of a <path/to/config-dir> 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.

@gavin09527 gavin09527 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

重新审过 10104d1(address zylos0t P3s)——WorkingDirectory=%h/.codex-openmax、enable-linger 标注为系统级变更需先征得用户同意、可读性调整都到位 ✅。此次为最新一次 push(Noah-Bytes 16:08)后的批准,满足 require_last_push_approval。

@gavin09527
gavin09527 merged commit bb87df0 into main Jul 20, 2026
3 checks passed
@gavin09527
gavin09527 deleted the docs/persistent-service-note branch July 20, 2026 16:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants