Skip to content

feat: show Codex sessions across Gateway and paired nodes#102586

Merged
steipete-oai merged 3 commits into
mainfrom
codex/codex-session-fleet
Jul 9, 2026
Merged

feat: show Codex sessions across Gateway and paired nodes#102586
steipete-oai merged 3 commits into
mainfrom
codex/codex-session-fleet

Conversation

@steipete-oai

@steipete-oai steipete-oai commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Closes #102503

What Problem This Solves

Codex sessions are local to the computer running Codex. Operators using a Gateway, a development box, and a paired Mac currently have to inspect every host separately and cannot see those sessions in one OpenClaw view.

Why This Change Was Made

This extends the opt-in codex-supervisor plugin with a metadata-only catalog backed by the current Codex App Server thread/list contract. Each participating node owns local consent and local App Server access; the Gateway owns authorization, aggregation, CLI output, and the Control UI. Both the TypeScript node host and native macOS node implement the same versioned, read-only command.

Thread content, transcript previews, mutations, Codex home paths, raw remote errors, and direct network exposure of App Server remain outside this surface. Enabling the plugin separately on the Gateway and participating nodes is required.

User Impact

Operators can run openclaw codex sessions or open the Codex Sessions plugin page to browse active or archived Codex sessions across the Gateway and connected nodes, search titles, refresh individual hosts, and paginate per host. A failing or disconnected host is isolated instead of preventing sessions from other hosts from loading.

Evidence

  • Codex supervisor focused suite: 60 tests passed across four files.
  • Control UI focused suite: 17 tests passed across three files.
  • Browser E2E: one federated catalog scenario passed, including partial host failure and pagination.
  • Native macOS node: 48 focused Swift tests passed, including a response frame larger than 64 KiB while App Server remained open.
  • Full Linux build passed on AWS Crabbox (run_df5871d84de7).
  • Changed-surface gate passed on AWS Crabbox (run_ccbdcf84d3d9).
  • Final-head Control UI i18n generation/check and git diff --check passed.
  • Final-head Codex supervisor suite: 60/60 tests passed after removing the type-only dependency delta.
  • Final-head native catalog suite: 9/9 tests passed; the touched Swift file passes SwiftFormat and SwiftLint.
  • Final-head Control UI i18n tooling: 7/7 tests passed with zero English fallbacks across all 20 locales; locale-specific translation passes and an independent wording/placeholder audit completed.
  • Fresh autoreview found no accepted/actionable findings; security diff scan found no findings.
  • Synthetic screenshots were inspected locally; they contain fabricated hosts, paths, and session identifiers.

The implementation and PR text are AI-assisted. A sanitized agent transcript was intentionally omitted at the operator's request.

@steipete-oai
steipete-oai requested a review from a team as a code owner July 9, 2026 09:00
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation app: macos App: macos app: web-ui App: web-ui plugin: file-transfer extensions: codex-supervisor Extension: codex-supervisor labels Jul 9, 2026
@github-actions github-actions Bot added the dependencies-changed PR changes dependency-related files label Jul 9, 2026
@openclaw-barnacle openclaw-barnacle Bot added size: XL maintainer Maintainer-authored PR labels Jul 9, 2026
@github-actions

github-actions Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dependency graph guard cleared

This PR no longer has blocked dependency graph changes. A future dependency graph change requires a fresh /allow-dependencies-change comment after the guard blocks that new head SHA.

  • Current SHA: 97bac0162c4de11219bfcf68911539e86d6a23af

@github-actions github-actions Bot removed the dependencies-changed PR changes dependency-related files label Jul 9, 2026
@clawsweeper

clawsweeper Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed July 9, 2026, 6:22 AM ET / 10:22 UTC.

Summary
The PR adds a codex-supervisor federated Codex session catalog across Gateway endpoints, paired node commands, native macOS nodes, CLI output, Control UI, docs, tests, and generated UI i18n.

Reproducibility: yes. by source inspection for the review finding: a title match beyond the first unsearched thread/list page is not returned until the operator manually advances cursors; no live run was performed in this read-only review.

Review metrics: 3 noteworthy metrics.

  • Patch size: 93 files, +8017/-125. The PR spans plugin runtime, native macOS, Control UI, docs, tests, and generated i18n, so review needs cross-surface parity rather than diff-only checks.
  • Config/default surface: 1 enabled-default field added, 1 startup activation changed. The plugin remains disabled by default, but explicitly enabled installs now activate on startup, which affects operator upgrade expectations.
  • Node command surface: 1 new node command, 1 default invoke policy. The catalog adds a paired-node command and default platform policy, so approval and metadata exposure matter before merge.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/nodes/index.md, persistent cache schema: ui/src/i18n/.i18n/ar.tm.jsonl, persistent cache schema: ui/src/i18n/.i18n/de.tm.jsonl, persistent cache schema: ui/src/i18n/.i18n/es.tm.jsonl, persistent cache schema: ui/src/i18n/.i18n/fa.tm.jsonl, persistent cache schema: ui/src/i18n/.i18n/fr.tm.jsonl, and 14 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🌊 off-meta tidepool
Patch quality: 🦪 silver shellfish
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Fix title search paging in both TypeScript and native macOS paths.
  • Resolve the conflicting branch or replace the uneditable source branch.
  • [P2] Record maintainer approval for the Codex metadata boundary before merge.

Risk before merge

  • [P1] The PR currently cannot merge cleanly because GitHub reports CONFLICTING/DIRTY and maintainerCanModify=false.
  • [P1] The new catalog intentionally exposes Codex session names, cwd, host identity, source, model provider, and Git branch across paired-node boundaries, so operator authorization and node consent need explicit maintainer security sign-off.
  • [P1] Enabling the catalog changes plugin startup behavior for an explicitly enabled plugin and adds a node command that may require operator reapproval on existing paired nodes.

Maintainer options:

  1. Repair search and settle boundary review (recommended)
    Fix the TypeScript and macOS title-search paging behavior, then have the owner confirm the node metadata boundary before merge.
  2. Accept page-local search deliberately
    Maintainers can keep the current paging behavior only if the UI and CLI clearly present search as page-local continuation.
  3. Pause until branch is mergeable
    Because the branch is conflicting and uneditable by maintainers, pause or replace it if the source branch cannot be updated quickly.

Next step before merge

  • [P1] Protected maintainer-labeled feature work, an uneditable conflicting branch, and search/security contract choices require human review before any repair or merge path.

Maintainer decision needed

  • Question: Should Codex catalog title search scan unsearched App Server pages itself, call upstream thread/list.searchTerm despite preview-match leakage, or remain page-local with explicit UI wording?
  • Rationale: Upstream Codex search can match transcript-derived previews, while OpenClaw's advertised catalog wants title-only search across paired-node metadata; automation should not choose the privacy/performance contract by itself.
  • Likely owner: steipete — steipete owns the linked maintainer product request and has the strongest recent history on codex-supervisor and plugin UI surfaces.
  • Options:
    • Bounded title-only scan (recommended): Have OpenClaw page through metadata-only thread/list results until it fills the requested title-match page or hits a maintainer-approved scan cap, and keep TypeScript and macOS semantics identical.
    • Use upstream App Server search: Pass searchTerm through to Codex and accept that result existence can be influenced by transcript-derived previews.
    • Keep page-local search: Preserve the current behavior but change CLI/UI copy and docs so operators know each Load more click continues the search instead of completing it.

Security
Needs attention: The diff adds a deliberate cross-node Codex metadata channel, so the implementation needs maintainer security sign-off even though no supply-chain issue was found.

Review findings

  • [P2] Scan enough pages for title search — extensions/codex-supervisor/src/supervisor.ts:336-358
  • [P2] Keep native node search parity — apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalog.swift:295-300
Review details

Best possible solution:

Keep the plugin-owned metadata-only design, but fix title search semantics consistently in TypeScript and native macOS, resolve the merge conflict, and get maintainer security/product approval before merge.

Do we have a high-confidence way to reproduce the issue?

Yes by source inspection for the review finding: a title match beyond the first unsearched thread/list page is not returned until the operator manually advances cursors; no live run was performed in this read-only review.

Is this the best way to solve the issue?

Partly: the plugin-owned metadata-only boundary is the right layer, but first-page-only local filtering is not the best search implementation unless maintainers explicitly accept page-local search semantics.

Full review comments:

  • [P2] Scan enough pages for title search — extensions/codex-supervisor/src/supervisor.ts:336-358
    This still asks Codex for one unsearched thread/list page and only then filters session.name, so a real title match on a later App Server page is hidden behind an empty or incomplete search result. Because upstream searchTerm also matches previews, the safer fix is a bounded title-only pagination loop, but returning only the first unsearched page does not satisfy the advertised title search.
    Confidence: 0.87
  • [P2] Keep native node search parity — apps/macos/Sources/OpenClaw/NodeMode/MacNodeCodexThreadCatalog.swift:295-300
    The native macOS node repeats the same one-page behavior by intentionally omitting search from the App Server request and filtering names only after a single page is decoded. If the TypeScript node/Gateway path gets a bounded title-only scan, Mac-hosted sessions will still be missed unless this path uses the same paging contract.
    Confidence: 0.84

Overall correctness: patch is incorrect
Overall confidence: 0.84

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 6ad8a77b512f.

Label changes

Label changes:

  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
  • add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The PR is maintainer-labeled, so the external-contributor proof gate is not applied; the body lists focused suites, E2E, Crabbox run IDs, and synthetic screenshot inspection.

Label justifications:

  • P2: This is a medium-impact operator workflow feature with limited blast radius, not an emergency or active production regression.
  • merge-risk: 🚨 compatibility: The PR changes plugin activation metadata and adds a node command surface that existing paired-node operators may need to reapprove or understand during upgrade.
  • merge-risk: 🚨 security-boundary: The catalog moves Codex session metadata from local nodes to the Gateway/UI and must preserve the intended authorization and redaction boundary.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🌊 off-meta tidepool and patch quality is 🦪 silver shellfish.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The PR is maintainer-labeled, so the external-contributor proof gate is not applied; the body lists focused suites, E2E, Crabbox run IDs, and synthetic screenshot inspection.
Evidence reviewed

Security concerns:

  • [medium] Federated Codex metadata boundary — extensions/codex-supervisor/src/session-catalog.ts:614
    The new Gateway method and node command expose session names, cwd, host identity, source, model provider, and Git branch from paired nodes; merge should confirm that operator.write scope, node pairing approval, plugin opt-in, and transcript exclusion are the intended boundary.
    Confidence: 0.86

Acceptance criteria:

  • [P1] Add a regression where a non-matching first App Server page is followed by a matching titled session on a later page for the TypeScript catalog path.
  • [P1] Add the same title-search paging regression for the native macOS node catalog path.
  • [P1] Rerun the focused codex-supervisor, Control UI, and native macOS catalog suites after the branch conflict is resolved.

What I checked:

Likely related people:

  • steipete: Recent main history shows steipete introduced and maintained codex-supervisor session listing and plugin UI surfaces, and the linked issue is a maintainer-labeled product request by steipete. (role: feature sponsor and recent area contributor; confidence: high; commits: 9dd3bce549b4, 69c3b56bdecb, c730d8f1f1bb; files: extensions/codex-supervisor/src/supervisor.ts, ui/src/pages/plugin/plugin-page.ts, docs/plugins/reference/codex-supervisor.md)
  • mbelinky: GitHub history attributes the paired-node Codex CLI session listing feature to mbelinky's prior merged work, which is the closest existing user path this PR extends. (role: introduced adjacent behavior; confidence: medium; commits: a5c1956ca17a; files: extensions/codex/src/node-cli-sessions.ts, extensions/codex/src/command-handlers.ts)
  • RomneyDa: Recent history on extensions/codex-supervisor/src/supervisor.ts includes record-guard refactoring that touches the same supervisor normalization style. (role: recent adjacent refactor contributor; confidence: medium; commits: de34dfdbe8c4; files: extensions/codex-supervisor/src/supervisor.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (1 earlier review cycle)
  • reviewed 2026-07-09T09:29:39.590Z sha 1025327 :: needs real behavior proof before merge. :: [P1] Use App Server title search before paging | [P1] Pass searchTerm through from the macOS node

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. labels Jul 9, 2026
@steipete-oai
steipete-oai force-pushed the codex/codex-session-fleet branch from 1025327 to 2ab3d35 Compare July 9, 2026 09:34
@clawsweeper clawsweeper Bot removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 9, 2026
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jul 9, 2026
@steipete-oai
steipete-oai force-pushed the codex/codex-session-fleet branch from 0863c58 to 97bac01 Compare July 9, 2026 10:28
@steipete-oai

steipete-oai commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Land-ready verification for 97bac0162c4de11219bfcf68911539e86d6a23af:

  • OpenClaw OPENCLAW_TESTBOX=1 scripts/pr prepare-run 102586: passed (hosted_exact_or_recent_rebase).
  • Exact-head GitHub CI run 29011704992: all scheduled jobs passed, including build-artifacts, macos-swift, dependency/lint/type/docs/security gates, and the broad Node shards.
  • Codex supervisor focused suite: 61/61 passed across four files.
  • Control UI focused suite: 17/17 passed; browser E2E: 1/1 passed.
  • Control UI i18n tooling: 7/7 passed with zero English fallbacks across all 20 locales; locale-specific translation passes and an independent wording/placeholder audit completed.
  • Native catalog: 9/9 final-head tests passed; 48/48 broader focused native tests passed before the formatting-only follow-up. The touched Swift file passes SwiftFormat and SwiftLint.
  • Full Linux build passed (run_df5871d84de7); earlier changed-surface proof passed (run_ccbdcf84d3d9).
  • Fresh post-translation autoreview: no accepted/actionable findings. Security diff scan: no findings.

Known proof gap: synthetic Control UI screenshots were inspected locally but could not be attached because the configured Crabbox coordinator has no artifact backend. No live/private session screenshot was uploaded. Live Gateway + native Mac + CLI node verification will run against landed artifacts immediately after merge.

@steipete-oai
steipete-oai merged commit 5154fe0 into main Jul 9, 2026
98 checks passed
@steipete-oai
steipete-oai deleted the codex/codex-session-fleet branch July 9, 2026 10:42
@steipete-oai

steipete-oai commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Merged via squash.

@github-actions github-actions Bot mentioned this pull request Jul 9, 2026
Open
@steipete-oai steipete-oai mentioned this pull request Jul 9, 2026
Merged
@obviyus obviyus mentioned this pull request Jul 9, 2026
Merged
This was referenced Jul 10, 2026
Closed
Merged
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 10, 2026
@steipete-oai @steipete
feat: show Codex sessions across Gateway and paired nodes (openclaw#1…
cbeac32 
…02586)

* feat(codex): add federated session catalog

* fix(codex): align session catalog checks

* fix(ui): translate Codex session catalog

---------

Co-authored-by: Peter Steinberger <[email protected]>
This was referenced Jul 11, 2026
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

app: macos App: macos app: web-ui App: web-ui docs Improvements or additions to documentation extensions: codex-supervisor Extension: codex-supervisor maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. plugin: file-transfer rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: XL status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Feature]: View Codex sessions across Gateway and paired nodes

2 participants

@steipete-oai @steipete