Skip to content

Commit bf57900

Browse files
authored
Merge #7011: recognize Desktop supervision on Windows and discover the Codex app CLI on macOS
fix(service,codex): recognize Desktop supervision on Windows and discover the Codex app CLI on macOS
2 parents b71d1e1 + d91ecf8 commit bf57900

31 files changed

Lines changed: 1447 additions & 49 deletions
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Lane L4 — platform issues #6853 and #6973 (2.84.0 release train)
2+
3+
Lane of the 2.84.0 release train. Coordinator thread `01a130be-2e10-7af0-adf9-efca9fe37e30` owns push, PRs and merges.
4+
Lane session `01a130c8-4644-7143-8264-ae552e1d1874`, worktree `/private/tmp/rt284-lanes/L4`,
5+
branch `codex/rt284-issues-platform` from `origin/dev` `3e58c2ce3ee5433901ed467fe87c32fb4b5c5e77`.
6+
7+
## Objective
8+
9+
Two commits, each with focused regression tests:
10+
11+
1. **#6853** — prove OpenCodex Desktop supervision on Windows so `ocx status`, `doctor`, `resolve`,
12+
`service install/repair/start/restart`, `stop` and `update` treat a Desktop-supervised runtime the way
13+
they already do on macOS and Linux. Design: [010](010_6853_windows_supervision.md).
14+
2. **#6973** — discover the Codex desktop app's bundled CLI on macOS as a lowest-precedence installed
15+
candidate that never silently takes over a persisted selection. Design: [020](020_6973_chatgpt_app_cli.md).
16+
17+
## Constraints
18+
19+
- `src/service/desktop-supervision.mjs` is imported by the Node >= 18 launcher (`bin/ocx.mjs:12`): no Bun or
20+
TypeScript imports, no FFI.
21+
- `scripts/test-layout/layout.json` is 1999 lines on dev and must stay under 2000: new entries append to an
22+
existing line. New test files are registered in `layout.json` `explicit` and
23+
`tests/fixtures/test-layout-expected.json`.
24+
- Tests run from the lane worktree with the global Bun 1.4.0 that dev pins (`package.json` `testRunnerBun`); the
25+
coordinator's 1.4.3 override applies only to the union with #6986.
26+
- No push, PR, merge, comment or release from this lane.
27+
28+
## Work-phase map
29+
30+
| Phase | Doc | Depends on | Output |
31+
|---|---|---|---|
32+
| wp0 | 000-020 | — | this roadmap; audited before implementation (executed inside the wp1 cycle) |
33+
| wp1 | 010 | — | commit `fix(service): prove OpenCodex Desktop supervision on Windows (#6853)` |
34+
| wp2 | 020 | — | commit `feat(codex): discover the Codex app's bundled CLI on macOS (#6973)` |
35+
| wp3 | 030 | wp1, wp2 | restack onto L3, commit `test(link): classify passive-read opens by write capability`, this devlog commit, Bun 1.4.3 union verification, exact-head review |
36+
37+
Final lane head on L3 `d9ce24cdec`: #6853 `52ca9103f7`, #6973 `ca946248f6`, watcher `91864ee9e7`, then this devlog commit.
38+
Reviews: #6853 PASS (pre-restack `fc9d078201`), #6973 PASS (pre-restack `88840876ad`), restacked head PASS (`9a5ca6a415`).
39+
40+
## Verification per phase
41+
42+
Focused tests named in each decade doc, then `bun run typecheck`, `tests/ci-workflows/file-size-ratchet.test.ts`,
43+
`tests/test-layout.test.ts`, `tests/test-layout-tooling.test.ts`, `bun run structure:check`,
44+
`bun run privacy:scan`. Real Windows/macOS-app qualification is out of reach locally; hosted Windows CI runs the
45+
injected-snapshot tests and live qualification stays a recorded residual.
46+
47+
48+
## Consultation record
49+
50+
- #6973: architect proposal and reflection by sol agent Huygens (`01a130ca-d372-7d52-9fae-7655f54bd445`, gpt-6.1-sol):
51+
proposal → 020; reflection ALIGNED with gaps, folded in 020 amendments.
52+
- #6853: plan written by main from source evidence (no separate architect proposal — recorded gap); bounded design check
53+
by the same architect returned MISALIGNED with three P1 and two P2 findings, dispositioned in 010 amendments
54+
(one P1 rejected for lane scope with a recorded residual).
55+
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# 010 — #6853 Windows Desktop supervision proof
2+
3+
## Problem
4+
5+
`inspectDesktopSupervision()` returns `{ kind: "unsupported" }` on win32
6+
(`src/service/desktop-supervision.mjs:75`), `desktopStartupOwnership()` excludes win32
7+
(`src/service/desktop-startup.ts:53`) and `diagnoseDesktopStartup()` dispatches only Linux or macOS
8+
(`src/service/desktop-startup.ts:267-268`). On Windows every consumer behaves as if no Desktop runs:
9+
status/doctor recommend `ocx service repair|restart`, `ocx service install` may clear managers, `ocx stop`
10+
omits the Desktop notice and `ocx update` gets no live veto.
11+
12+
## Proof standard (from the issue and its triage)
13+
14+
Desktop is proven only when all hold, twice, with identical snapshots:
15+
16+
1. `ocx.pid`, `runtime-port.json` and an optional `targetPid` agree (existing `capture()`).
17+
2. The runtime process exists; its parent PID is > 0 and names a live process.
18+
3. The parent image basename is `opencodex-desktop.exe` (case-insensitive).
19+
4. The runtime image equals `<dirname(parent image)>\ocx.exe` (case-insensitive, `path.win32` normalized).
20+
5. Parent and child share a session id.
21+
6. Parent creation time strictly precedes child creation time (PID-reuse guard).
22+
23+
Anything unreadable is `unknown` (`probe-failed` or a specific reason), never `desktop` and never `none`.
24+
A parent that is readable and is not Desktop is `none`.
25+
26+
## Acquisition (Node-safe)
27+
28+
One bounded call per snapshot: `powershell.exe -NoProfile -NoLogo -NonInteractive -Command <script>` with
29+
`timeout: 5000`, `windowsHide: true`, reading `Win32_Process` for the runtime PID and then its
30+
`ParentProcessId`, emitting compact JSON
31+
`{"child":{pid,parent,exe,session,created}|null,"parent":{...}|null}` where `created` is the UTC tick count as a
32+
string (exceeds 2^53). PowerShell is resolved as
33+
`<SystemRoot|windir, absolute, else C:\Windows>\System32\WindowsPowerShell\v1.0\powershell.exe`, mirroring
34+
`src/update/npm-invocation.mjs:99-101` (plain ESM cannot reach the FFI resolver in
35+
`src/lib/windows-elevation.ts`). The PID is a validated safe integer interpolated into a numeric filter only.
36+
37+
Seam: `deps.windowsProcesses(pid) => { child, parent }` for tests; default `windowsProcessPair(pid, run)`.
38+
39+
## Diff
40+
41+
### MODIFY `src/service/desktop-supervision.mjs`
42+
43+
- import `win32` from `node:path`.
44+
- NEW `windowsPowerShellPath(env)`, `windowsProcessPair(pid, execute, env)` (exported) that runs the script above
45+
through `execute` with the Windows timeout and parses/validates rows (`pid`, `parent` safe integers,
46+
`session` integer, `created` decimal string, `exe` string or null).
47+
- `inspectDesktopSupervision`: accept `win32`; `seen()` accepts `opencodex-desktop.exe` case-insensitively;
48+
`capture()` calls a NEW `windowsCapture(snapshot)` on win32 that applies checks 2-6 and returns the same
49+
`{ ...snapshot, kind }` / `{ error }` shape (`proxy-mismatch`, `session-mismatch`, `creation-order`).
50+
POSIX path unchanged. Result for desktop: `{ kind, runtimePid, supervisorPid, app, proxy }`.
51+
- `run()` gains `windowsHide: true` and an optional timeout argument.
52+
53+
### MODIFY `src/service/desktop-supervision.d.mts`
54+
55+
Add `WindowsProcessRow`, `WindowsProcessPair`, `windowsProcesses?` and `env?` deps, and export
56+
`windowsProcessPair`.
57+
58+
### MODIFY `src/service/desktop-startup.ts`
59+
60+
- `desktopStartupOwnership`: include `win32` (ownership-only, still no probes).
61+
- NEW `diagnoseWindowsDesktopStartup(deps)`:
62+
- owner `none` → `diagnoseSupervisedStartup(deps, revision, () => ({ loginEnabled: false }))` — the live
63+
supervisor is reported, Start at Login is not verified on Windows and is never credited.
64+
- owner desktop → read `%APPDATA%\com.opencodex.desktop\install-id` (Tauri `app_config_dir`,
65+
`desktop/src-tauri/tauri.conf.json:5`, `desktop/src-tauri/src/identity.rs:22-26`); mismatch → not running;
66+
otherwise `running` only if `inspectDesktopSupervision` proves Desktop and ownership is unchanged after the
67+
probe. `loginEnabled: false`.
68+
- other owners → `undefined`.
69+
- `diagnoseDesktopStartup`: dispatch `win32` to it.
70+
71+
`src/codex/autostart-health.ts:94` stays darwin/linux-only: Windows can report the supervisor and drop the
72+
`ocx service` advice (`autostart-health.ts:110,122-125,224`) but cannot read as protected until Windows Start at
73+
Login is verified. Recorded as residual.
74+
75+
### Consumers (no code change expected; covered by tests)
76+
77+
`desktop-command-guard.ts` (install/repair/start/restart refusal), `desktop-runtime-guidance.ts` (stop notice,
78+
duplicate start), `bin/ocx.mjs:339-340` and `src/update/index.ts:489,658` (update veto), `doctor.ts`,
79+
`hub-disable.ts`, `status.ts:317-334` local-supervision override.
80+
81+
## Tests
82+
83+
NEW `tests/service/service-desktop-supervision-windows.test.ts` (domain `service`; register in
84+
`layout.json` by appending to an existing `service` line and in `test-layout-expected.json`):
85+
86+
- proves Desktop for matching pid files, sibling `ocx.exe`, same session and older parent (case-insensitive paths)
87+
- a non-Desktop readable parent is positive `none`
88+
- runtime image outside the Desktop directory → `unknown/proxy-mismatch`, desktopSeen true
89+
- session mismatch, equal or newer parent creation → `unknown`
90+
- unreadable parent image, malformed JSON, thrown PowerShell → `unknown/probe-failed`, desktopSeen false
91+
- changed second snapshot → `unknown/snapshot-changed`
92+
- default reader builds the PowerShell argv under SystemRoot with a numeric filter and parses tick strings
93+
- `desktopServiceCommandRefusal("install")`, `desktopStopNotice`, latch, with win32 evidence
94+
- `diagnoseDesktopStartup` on win32: unowned supervisor → `supervisor` set, `loginEnabled:false`, health has no
95+
`ocx service` command; owned with matching install-id → `owned:true, running:true`; mismatched id → not running
96+
- `desktopStartupOwnership` on win32 → owned projection without probes
97+
98+
MODIFY `tests/service/service-desktop-startup.test.ts`: the "unsupported platforms never probe" case drops
99+
`win32` from its platform list (keeps `freebsd`).
100+
101+
102+
## Amendments after architect reflection (Huygens, MISALIGNED → folded)
103+
104+
| Finding | Disposition |
105+
|---|---|
106+
| P1 owned projection vs legacy status override (`src/cli/status.ts:326`, `tests/cli/cli-status-startup-health.test.ts:284`) | **Rejected for this lane, residual recorded.** The `owned === false` requirement is shared macOS/Linux policy pinned by a test; changing it is a cross-platform policy change. The gap is transitional: a runtime carrying this change reports Windows ownership through `desktopStartupOwnership`, so only an *older* Windows runtime with a durable Desktop claim keeps its live service advice. The owned Windows diagnostic mirrors macOS (no `supervisor` field). |
107+
| P1 both PID records required | **Accepted.** On win32, `desktop` requires `ocx.pid` and `runtime-port.json` both present, valid and equal (and equal to `targetPid` when given); either missing → `unknown/pid-record-missing`. Returned `child.pid` must equal the runtime PID and `parent.pid` must equal `child.parent`, else `probe-failed`. |
108+
| P1 partial observation loses the veto | **Accepted.** The reader calls `seen()` as soon as a parent `exe` string is present, before validating any other field, so a Desktop image with unreadable session/creation evidence yields `unknown` with `desktopSeen: true`. |
109+
| P2 startup seam | **Accepted.** `DesktopStartupDeps` gains `windowsProcesses` and `readWindowsInstallId`; they are forwarded to `inspectDesktopSupervision`; tests never read a real profile. |
110+
| P2 aggregate deadline | **Accepted.** Each `inspectDesktopSupervision` call on win32 gets a 6,000 ms budget shared by its two acquisitions (each `min(3000, remaining)`, at least 250 ms or the snapshot is `probe-failed`), so `diagnoseSupervisedStartup`'s two inspections stay under 12 s, inside the 15 s Windows probe budget (`src/codex/autostart-health.ts:14`). A test drives slow successful acquisitions with an injected clock. |
111+
| ticks compared numerically | **Accepted.** `BigInt` comparison of decimal tick strings. |
112+
| missing child/parent evidence | **Accepted.** On win32 a missing child row is `unknown/process-missing` and a missing parent row `unknown/parent-missing` (not POSIX `none`). A readable non-Desktop parent stays positive `none`. |
113+
| broader consumer tests | **Accepted.** Tests cover install/repair/start/restart refusal, duplicate-start guidance, stop notice, update veto through `resolveRuntimeOwnership`-style supervision input, and status selection for an older live verdict with an unowned supervisor. |
114+
| update claim correction | **Accepted.** Durable non-CLI ownership already vetoes update replacement (`src/update/runtime-ownership.mjs:70`); the gap is the *live supervision* veto. |
115+
| live Windows qualification | Outstanding; recorded as residual for the coordinator/issue. |
116+
117+
118+
## Amendments after independent audit round 1 (Arendt, FAIL → folded)
119+
120+
| Finding | Disposition |
121+
|---|---|
122+
| P1 legacy owned Windows status case | **Accepted (supersedes the earlier rejection).** Older Windows runtimes never reported a `desktop` diagnostic, so the owned case cannot have existed in a legacy live verdict before. The Windows owned diagnostic carries `supervisor: { supervisorPid, runtimePid, app }` when the live chain is proven (durable `owned: true` preserved). `selectStatusStartupHealth` (`src/cli/status.ts:326`) accepts `local.desktop.owned === true` **only when `local.platform === "win32"`**; the PID-pair binding, the missing-capability precondition and macOS/Linux policy are unchanged. Tests: win32 owned legacy override, win32 unowned legacy override, changed pair, inconclusive probe, modern live verdict authoritative, and the existing darwin/linux "owned" rejection still holds. |
123+
| P2 image paths must be fully qualified | **Accepted.** A row `exe` is evidence only if it matches `^[A-Za-z]:\\` after `/`→`\` (drive-absolute). UNC (`\\server`), device (`\\?\`, `\\.\`), drive-relative (`C:foo`), rooted (`\foo`), relative and empty paths are `unknown/image-unqualified` and never yield `desktop` or positive `none`. Fixtures cover each form. |
124+
| P2 partial-observation interface | **Accepted.** `windowsProcessPair(pid, execute, { onExecutable, timeoutMs, env })` calls `onExecutable(parent.exe)` for any string parent image **before** strict row validation; `inspectDesktopSupervision` passes `seen`. Injected `windowsProcesses(pid, { onExecutable, timeoutMs })` gets the same options. Tests feed malformed rows through the default reader with an injected `run` and assert `unknown` + `desktopSeen: true` plus a blocked latch. The per-acquisition timeout is `min(3000, remaining)` from the 6,000 ms inspection budget; the original 5,000 ms figure is withdrawn. |
125+
| P2 test runner pin | **Accepted.** The lane branch is based on dev, whose `package.json` `testRunnerBun` is 1.4.0; tests use the global `~/.bun/bin/bun` 1.4.0 (the coordinator's 1.4.3 override applies only to the union with #6986). Verification also runs `tests/service/service-desktop-startup.test.ts`, `service-desktop-startup-linux.test.ts`, `tests/cli/cli-status-startup-health.test.ts`, and a Node (`node -e`) import smoke of `src/service/desktop-supervision.mjs` exercising `windowsProcessPair` with an injected `run`. |
126+
| P2 docs sync | **Accepted.** Update `structure/desktop-shell.md` (§ runtime ownership, "Windows reports supervision as unsupported"), `structure/ops/service-and-sidecars.md:430`, `structure/runtime.md:546`, and `docs-site/src/content/docs/guides/desktop-app.md:101-143` plus its translated mirrors where they state the Windows limitation: Windows now proves live supervision; Windows Start at Login remains unverified, so Windows never reads as protected by Desktop. |
127+
128+
129+
## Amendment after audit round 2 (NEAR-PASS, P3 folded)
130+
131+
Update the comments that describe supervision as exclusively unowned: `src/service/desktop-startup.ts:17`
132+
(`supervisor` field) and `src/cli/status.ts:325` (selector) — live supervision stays independent of ownership; the
133+
owned override is Windows-only because older Windows runtimes never reported a Desktop diagnostic.
134+

0 commit comments

Comments
 (0)