Skip to content

fix(client): refuse a bare OCX_SERVICE=1 client runtime with the re-register advice - #8796

Merged
lidge-jun merged 1 commit into
devfrom
fix/8545-legacy-bare-flag-refusal
Nov 16, 2026
Merged

lidge-jun merged 1 commit into
devfrom
fix/8545-legacy-bare-flag-refusal

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

A Remote Link Child's client runtime can carry a bare OCX_SERVICE=1 and no other owner evidence. This happens for a service registered before 2.49, and for the detached proxy that ocx claude, ocx codex or ocx opencode starts. Nothing the runtime can read tells these apart. Before this PR, ocx restart refused only while some service looked viable; otherwise it spawned a detached replacement, which a legacy systemd unit or launchd job could still own and kill. ocx disconnect left the runtime serving with no explanation.

Owner decision (lidge-jun, 2026-11-16, #8545): do not accept parent-command-line evidence as ownership proof. Refuse a legacy bare-flag runtime with a message telling the user to re-register the service once, which writes the current ownership marker. Stop nothing on inference.

What changes:

  • classifyClientRestartSupervisor (src/client/runtime-restart.ts) returns a new verdict, legacy-flag, for a bare OCX_SERVICE=1. It does so whatever the service diagnostic says and whether or not the connection ended. The old legacyServiceViable input (isServiceViable) is gone, and the parent-command-line derivation is never consulted. restartRefusedByOwner includes legacy-flag, so the runtime answers 409 restart_supervised / legacy-flag and stops, replaces and recycles nothing.
  • The runtime record states restartOwner: "legacy-flag" (recordedRestartOwner). The record validator already accepts any string up to 64 characters, so older CLIs read it as an unhandled owner, which is their current behavior.
  • ocx restart reports: "Restart not performed; the running client runtime was kept and nothing was stopped." followed by LEGACY_FLAG_OWNER_ADVICE (src/cli/restart-failure.ts). The advice: if a background service runs it, re-register the service once with ocx service repair; if ocx claude, ocx codex or ocx opencode started it, run ocx stop and start it again.
  • ocx sync defers its restart with the same advice.
  • ocx disconnect sends no restart request for legacy-flag, prints the advice on stderr, and exits 0. The disconnect itself completed, so a Home's revoke still finishes. A Home-driven leave that runs ocx restart next gets the same refusal and advice.
  • After the re-registration, the runtime carries the managed marker, so restart, disconnect and sync use the service path that fix(link): Children owned by the desktop app or a service can leave and re-link from the Home #8529 added.

Scope: runtimes that carry a current marker (OCX_SERVICE_MANAGED, the Windows wrapper marker) or that run under the desktop app are unchanged. A runtime with no OCX_SERVICE at all is unchanged too. The start-time stay-out check in src/service/service-child-ownership.ts still reads the parent's command line, because it only refuses to serve and never stops anything. A companion proxy on a Child is now refused as well, because it is indistinguishable from a legacy service. Giving companions their own non-inheritable marker was deliberately left out (the removed attempt in #8529).

Docs: the English and Spanish CLI lifecycle reference and Remote Link guide are updated; the other locales of those pages do not describe the bare-flag case. The structure/remote-link.md and structure/runtime.md contracts are updated as well.

Closes #8545

Verification

  • Hosted CI with ci:full on e772b21: all 32 checks passed, including all five full Ubuntu test shards (test 1/5–test 5/5). That run includes tests/server/proxy-liveness-self-pid-record.test.ts, so the local timeouts in that file came from load on this host, not from this branch.
  • Tests were rewritten first to encode the owner decision, and failed before the change (Export named 'recordedRestartOwner' not found, LEGACY_FLAG_OWNER_ADVICE not found):
    • tests/clients/client-runtime-restart.test.ts: for a legacy service child and each of the three companion proxies, with every service diagnostic and the connection ended or not, the verdict is legacy-flag, the admission is supervised, and stop, spawn and recycle are never called. A markerless legacy Windows service whose parent command line names this install's wrapper is still legacy-flag, which is the "never infer from the parent command line" guard; that test covers restart, disconnect and sync.
    • tests/cli/disconnect-runtime.test.ts: legacy-flag records give exit 0, no restart request, and stderr that names the pid, "nothing was stopped" and ocx service repair, in text and --json modes and for disconnected, connected and invalid states.
    • tests/cli/link-apply-restart.test.ts: sync defers with the advice; the 409 legacy-flag parse, deferral and message are covered.
  • bun test tests/clients/client-runtime-restart.test.ts tests/cli/disconnect-runtime.test.ts tests/cli/link-apply-restart.test.ts tests/cli/cli-client-start-fence.test.ts: 133 pass, 0 fail.
  • The 46 test files that import the changed modules: 1331 pass, 3 skip, 3 fail. All 3 failures are timeouts in subprocess tests. ocx-launcher-desktop-handoff and stop-deferred-teardown passed on re-run. proxy-liveness-self-pid-record (two real ocx start spawn cases) failed on re-runs on this branch and passed once on the base commit. This host's load average reached 130 during these runs, and neither case reaches the client-runtime code, but I could not finish a clean A/B. This PR carries ci:full so hosted shards settle it.
  • bun test tests/ci-workflows/docs-spanish-localization.test.ts tests/ci-workflows/docs-link-targets.test.ts: 38 pass, 0 fail.
  • bun run typecheck: exit 0. bun run structure:check: passed. bun run privacy:scan: exit 0.
  • NOT RUN: bun run test:changed and full bun run test locally. The host was at critical load, and the launching thread asked for no heavy local commands. Hosted CI's test changed and the ci:full shards cover them.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (No credential or auth change. The change only refuses more and stops nothing.)

Summary by CodeRabbit

  • Behavior Changes

    • Runtimes identified only by OCX_SERVICE=1 are no longer stopped or restarted automatically. ocx restart refuses, and ocx sync defers the restart with guidance.
    • ocx disconnect leaves these runtimes running and completes successfully, with advice on how to restart them safely.
  • Documentation

    • Updated the Remote Link and lifecycle guides with recovery steps for background services and companion proxies, including instructions for older versions.

…egister advice

A client runtime whose only owner evidence is a bare OCX_SERVICE=1 (a
service registered before 2.49, or the proxy of ocx claude, ocx codex or
ocx opencode) cannot show who owns it. Before, ocx restart refused it only
while some service looked viable and otherwise spawned a detached
replacement, which a legacy manager could still own and kill.

Per the owner decision, such a runtime is now always refused as
legacy-flag: ocx restart answers 409 restart_supervised legacy-flag,
ocx sync defers, and ocx disconnect keeps it (exit 0, the disconnect
itself completed). Each prints the same advice: re-register the service
once with ocx service repair, which writes the current ownership
marker, or stop and restart a companion's proxy. Ownership is never
inferred from the service diagnostic or the parent's command line, and
nothing is stopped on inference. The runtime record states
restartOwner legacy-flag so disconnect can name the case.

Closes #8545
@lidge-jun lidge-jun added the ci:full Run the four full Ubuntu test shards on this pull request label Nov 16, 2026
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Client runtimes marked only with OCX_SERVICE=1 are now classified as legacy-flag. Restart and sync refuse or defer without stopping these runtimes. Disconnect leaves them running, exits successfully, and reports recovery advice.

Changes: Legacy-Flag Runtime Lifecycle

Layer / File(s) Summary
Classify and record runtime ownership
src/client/runtime-restart.ts, src/client/runtime.ts, src/config/process-state.ts, src/cli/claude.ts, tests/clients/client-runtime-restart.test.ts
Bare OCX_SERVICE=1 runtimes are classified as legacy-flag, regardless of service diagnostics or connection state. Runtime records use this classification when ownership cannot be proven. Tests cover refusal without stopping, replacement, or recycling.
Apply refusal and report lifecycle outcomes
src/cli/disconnect-runtime.ts, src/cli/link-apply-restart.ts, src/cli/restart-failure.ts, src/cli/system-restart-client.ts, tests/cli/*, structure/*, docs-site/src/content/docs/*
Restart reports the refusal and recovery advice. Sync defers the restart with that advice. Disconnect does not restart the runtime and exits with code 0. Tests and lifecycle documentation describe these outcomes and the documented recovery steps.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related PRs

  • lidge-jun/opencodex#8513: Adds Home-orchestrated restart of Child Codex through the client runtime restart endpoint whose refusal behavior changes here.
  • lidge-jun/opencodex#7484: Introduced the client restart path and supervisor classification updated by this change.
Merge Risk: Minimal · up to e772b

Client runtimes with only a bare OCX_SERVICE=1 flag are now refused on restart, deferred on sync, and kept on disconnect with re-registration advice. The behavior is intentional and consistent across the code, tests and docs. No merge-blocking risk was found.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Linked Issues check Inconclusive Issue #8545 is the only active direct target. Its core outcome is met in part. For a bare OCX_SERVICE=1 runtime, src/client/runtime-restart.ts now classifies the owner as legacy-flag, whatever the ser… Provide the exit code and output channel that the Child's legacy-flag sync deferral uses. Show that classifySyncResult in src/link/sync-fanout-classify.ts (or its caller) carries that advice to the Home, or add a test for that path. Confirm…
Passed Passed checks: 3 passed

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: a bare OCX_SERVICE=1 client runtime is now refused with the re-register advice. The raw summary and objectives confirm this is the primary behavior change (restart ref…
Out of Scope Changes check Passed Each changed area ties to the legacy-flag ownership decision in #8545. Changed areas are src/client/runtime-restart.ts (classifier and recordedRestartOwner), src/client/runtime.ts (record fallback), s…
Full details: Title check

Explanation

The title names the main change: a bare OCX_SERVICE=1 client runtime is now refused with the re-register advice. The raw summary and objectives confirm this is the primary behavior change (restart refused, sync deferred, disconnect exits 0 with advice). The title is specific and concise, and it uses the same identifiers as the changed code (legacy-flag classification, refusal path). It does not mention the docs or test updates, which is acceptable because it need not cover every detail.

Full details: Out of Scope Changes check

Explanation

Each changed area ties to the legacy-flag ownership decision in #8545. Changed areas are src/client/runtime-restart.ts (classifier and recordedRestartOwner), src/client/runtime.ts (record fallback), src/cli/restart-failure.ts (advice and supervisor type), src/cli/system-restart-client.ts (response validation), src/cli/disconnect-runtime.ts, src/cli/link-apply-restart.ts, src/cli/claude.ts (comment), src/config/process-state.ts (documentation), and the matching tests. Documentation changes cover the same behavior in English and Spanish reference and guide pages, structure/remote-link.md, and structure/runtime.md. The summary notes one extra structure/remote-link.md line about disconnect recovery of prepared receipts. That text describes existing documented behavior and is not a new behavior change. No unrelated change is shown.

Full details: Linked Issues check

Explanation

Issue #8545 is the only active direct target. Its core outcome is met in part. For a bare OCX_SERVICE=1 runtime, src/client/runtime-restart.ts now classifies the owner as legacy-flag, whatever the service diagnostic or connection state. restartRefusedByOwner includes legacy-flag, so restart stops, replaces, and recycles nothing. ocx restart refuses with 409 restart_supervised / legacy-flag. ocx disconnect sends no restart request, prints advice, and exits 0. ocx sync defers with the same advice. The runtime records restartOwner 'legacy-flag'. This keeps the runtime and states what remains, and it does not guess the owner. Tests in tests/clients/client-runtime-restart.test.ts, tests/cli/disconnect-runtime.test.ts, and tests/cli/link-apply-restart.test.ts cover these paths. Gaps remain. The issue lists five design items. Items 1 to 4 (positive ownership evidence, one-time upgraded-process handling, authenticated stop, connect fence) are explicitly not implemented. The PR states this, and it refuses instead of stopping, so the fence and authenticated stop are not exercised. Item 5 requires that the Child advice reach the Home through sync fan-out. src/link/sync-fanout-classify.ts is not in the changed set. classifySyncResult maps only known exit codes, and any unlisted code becomes child-sync-failed with no advice. The PR does not state the exit code of the legacy-flag sync deferral, so delivery of the advice to the Home cannot be established.

Resolution

Provide the exit code and output channel that the Child's legacy-flag sync deferral uses. Show that classifySyncResult in src/link/sync-fanout-classify.ts (or its caller) carries that advice to the Home, or add a test for that path. Confirm in the issue or PR that items 1 to 4 are deferred by owner decision, so the Home-side behavior is accepted as the final scope.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 595de1e and e772b21.

Files selected for processing: 17

  • docs-site/src/content/docs/es/guides/remote-link.md
  • docs-site/src/content/docs/es/reference/cli/lifecycle.md
  • docs-site/src/content/docs/guides/remote-link.md
  • docs-site/src/content/docs/reference/cli/lifecycle.md
  • src/cli/claude.ts
  • src/cli/disconnect-runtime.ts
  • src/cli/link-apply-restart.ts
  • src/cli/restart-failure.ts
  • src/cli/system-restart-client.ts
  • src/client/runtime-restart.ts
  • src/client/runtime.ts
  • src/config/process-state.ts
  • structure/remote-link.md
  • structure/runtime.md
  • tests/cli/disconnect-runtime.test.ts
  • tests/cli/link-apply-restart.test.ts
  • tests/clients/client-runtime-restart.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

@github-actions

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 16, 2026
@lidge-jun
lidge-jun marked this pull request as ready for review November 16, 2026 05:31
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 16, 2026 05:31
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T05:32:39.613539Z e772b21 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@lidge-jun

Copy link
Copy Markdown
Owner Author

Merge-manager review against the #8545 owner decision at e772b21: MERGE. A bare OCX_SERVICE=1 client runtime is refused (classifyClientRestartSupervisor → legacy-flag whatever the service diagnostic says; 409 restart_supervised/legacy-flag; ended-connection recycle unreachable), with LEGACY_FLAG_OWNER_ADVICE (ocx service repair, or ocx stop + restart for ocx claude/codex/opencode) printed by ocx restart, ocx sync and ocx disconnect. No stop, spawn or recycle on that verdict; refusals are side-effect free. Desktop, the managed marker, the Windows wrapper marker and the no-flag case keep their verdicts. Windows coverage uses an injected win32 parent and runs on every OS; Windows execution of ocx service repair on a real legacy registration comes from the lane=all after merge. No conflicts with the queue.

Follow-ups (not blocking; outside the client restart/disconnect path #8545 names): other bare-flag trusts in src/server/management/system-restart.ts (~221–225, 340, 479), src/server/index/package-tree-guard.ts (19, 31), src/client/stop-routing.ts (30) and src/client/runtime.ts recycleStandalone (~191, 233–236 — needs an owner call: exit vs spawn a replacement a legacy service may kill); the existing start-time stay-out check (src/service/service-child-ownership.ts ~90–116) still reads the parent command line (it only refuses to serve, stops nothing) — owner to confirm it stays; sync fan-out may drop a Child's stderr advice on exit 1 (src/link/sync-fanout-classify.ts); a listener test returning a real legacy-flag 409; "Disconnected, but…" wording on the legacy-flag disconnect message.

@lidge-jun

Copy link
Copy Markdown
Owner Author

Maintainer integration of #8796 at e772b21 (closes #8545), reviewed against the #8545 owner decision.

  • What it does: a client runtime that carries only the bare OCX_SERVICE=1 flag is now refused as legacy-flag, with advice to re-register the service once (ocx service repair, or ocx stop and then a restart for companion launches). Ownership is never inferred from the parent command line, and nothing is stopped on an inference: a refusal has no side effects, and properly registered runtimes keep their earlier verdicts.
  • Follow-ups, not in this PR's scope: other bare-flag trusts outside the client restart and disconnect path, such as system-restart.ts and runtime.ts recycleStandalone, and the start-time stay-out check that reads the parent command line but only refuses to serve.
  • CI on this exact head: all checks passed, including the five full Ubuntu shards (ci:full) and a successful enforce-target.
  • Merge check: a simulated merge onto current dev is clean, with no file over the size cap.
  • Windows: it touches service ownership on Windows, so the next batched lane=all on dev will include it.

@lidge-jun
lidge-jun merged commit ee56d83 into dev Nov 16, 2026
46 of 49 checks passed
@lidge-jun
lidge-jun deleted the fix/8545-legacy-bare-flag-refusal branch November 16, 2026 08:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working ci:full Run the four full Ubuntu test shards on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restart and disconnect for a client runtime whose owner cannot be proven (legacy bare-flag service children and companion proxies)

1 participant