|
| 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