feat(install): defer app detection to first run; keep postinstall thin - #538

Summary

Makes install lazy — audit roadmap §4.5.4 (docs/audits/AUDIT_2026-06-10.md, PR #522): the heavy app-bind/launcher detection moves out of postinstall into a once-only, never-throws first-run hook in the CLI, and postinstall becomes a thin CI-aware notice. This removes a whole class of install-time fragility (spawning the router, rewriting config.toml, scanning LOCALAPPDATA//Applications during npm install).

Before / after

First-run hook design

• Marker ~/.codex/multi-auth/first-run-setup.json: claimed with exclusive wx create (cross-process at-most-once), finalized via the repo's temp+rename atomic pattern inside withFileOperationRetry (Windows-safe).
• Never blocks or fails a command: every step resolves to completed/skipped/failed statuses; even marker-claim failure resolves; belt-and-braces .catch at the call site. Debug-only logging, no tokens/emails.
• All existing gates preserved: CI wins over opt-ins; CODEX_MULTI_AUTH_APP_BIND / _APP_BIND_INSTALL / _APP_LAUNCHER_INSTALL / _RUNTIME_ROTATION_PROXY honored; bind still requires a detected or already-bound desktop app. The install-context check became "module path contains node_modules", keeping dev checkouts and tests side-effect-free.

Tests + docs

• test/first-run.test.ts (new, 15 tests): gates, once-only + marker contents, second-run skip, concurrency at-most-once, step-failure-doesn't-fail, CI skip, dev-checkout skip, CLI wiring.
• Postinstall tests rewritten to the thin contract (silent in CI/non-TTY, notice-only on TTY, throwing sink still exits 0, no-detection source invariants).
• README/CONFIG_FIELDS/uninstall help/preuninstall comments updated to say the bind/launcher work happens on first CLI run.

Validation

• npm run typecheck + typecheck:scripts; eslint --max-warnings=0
• documentation (25), codex-manager-cli (201), first-run (15), uninstall/preuninstall suites pass; the 2 remaining install-codex-auth failures are environment-only — independently re-verified byte-identical on clean origin/main
• Manual rehearsal: CI=1 postinstall silent exit 0; TTY notice-only; dist-module first run completed→already-done; failure injection resolves without throwing; real-defaults run produced correct marker JSON

Risk / Rollback

Behavioral change to install flow (deliberate, per the audit): consumers get the bind/launcher setup on first codex-multi-auth invocation instead of during npm install. Revert the single commit to restore eager postinstall.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

moves desktop-app detection, Codex app bind, and launcher routing out of npm postinstall into a once-only first-run hook (lib/runtime/first-run.ts) called before CLI dispatch; postinstall becomes a thin, always-exit-0 TTY notice with no dist imports or filesystem mutations.

• lib/runtime/first-run.ts claims a per-user marker (~/.codex/multi-auth/first-run-setup.json) with an exclusive writeFileSync(flag:"wx") for cross-process at-most-once semantics, then finalizes it atomically via withFileOperationRetry+rename; every step is best-effort and failure only debug-logs sanitized messages.
• isInstalledPackageContext approximates the old isGlobalNpmInstall gate at CLI runtime using module path heuristics: requires a node_modules segment, excludes _npx cache runs, and excludes paths whose relative(cwd, modulePath) resolves without a .. prefix; there is an edge-case false-negative for pnpm/yarn global installs when cwd is an ancestor of the global node_modules location (e.g., running from ~/).
• test suite covers gates, once-only semantics, concurrency, step-failure resilience, CI/dev-checkout skips, loadLauncherInstall fallback/failure modes, and CLI wiring; uses removeWithRetry per test/AGENTS.md; missing a coverage case for the "partial marker" state (claim written, process killed before finalize).

Confidence Score: 5/5

safe to merge; the change is a deliberate behavioral shift from eager postinstall to lazy first-run, and every failure path resolves gracefully without blocking any CLI command

the core once-only guarantee is backed by OS-level exclusive file creation (wx flag) and the atomic temp+rename finalize; the belt-and-braces .catch at the call site means no first-run failure can ever surface to the user; the postinstall simplification removes an entire class of install-time fragility

lib/runtime/first-run.ts — the isInstalledPackageContext CWD-relative heuristic has a false-negative for pnpm/yarn global installs when the user's working directory is an ancestor of the global node_modules path

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant CLI as runCodexMultiAuthCli
    participant FRS as ensureFirstRunSetup
    participant FS as Filesystem
    participant Bind as defaultBindCodexApp
    participant Launch as defaultInstallLauncher

    CLI->>FRS: "await ensureFirstRunSetup({ notify }).catch(()=>undefined)"
    FRS->>FRS: isCiEnvironment(env)?
    alt CI / ignored-scripts
        FRS-->>CLI: "{ran:false, reason:"ci"}"
    else not installed package context
        FRS->>FRS: isInstalledPackageContext()
        FRS-->>CLI: "{ran:false, reason:"not-installed"}"
    else marker already exists
        FRS->>FS: existsSync(markerPath)
        FS-->>FRS: true
        FRS-->>CLI: "{ran:false, reason:"already-done"}"
    else first run
        FRS->>FS: "writeFileSync(markerPath, claim, {flag:"wx"})"
        Note over FS: exclusive create — at most one winner cross-process
        FRS->>Bind: bindCodexApp()
        Bind-->>FRS: "completed" | "skipped" | throws→"failed"
        FRS->>Launch: installLauncher()
        Launch-->>FRS: "completed" | "skipped" | throws→"failed"
        FRS->>FS: atomicWriteMarker (temp+rename via withFileOperationRetry)
        FRS-->>CLI: "{ran:true, appBind, launcher}"
    end
    CLI->>CLI: continue normal dispatch

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
lib/runtime/first-run.ts:229-233
**`isInstalledPackageContext` false-negative for pnpm/yarn global installs when cwd is a home-directory ancestor**

`relative(cwd, modulePath)` returns a path without a leading `..` whenever `cwd` is an ancestor of `modulePath`. pnpm's default global store on Linux is `~/.local/share/pnpm/global/node_modules/…`, so any user who runs `codex-multi-auth` from `~/` (or any ancestor of that path) will get `relative("~", "~/.local/…") = ".local/…"` — no leading `..`, not absolute — and the function returns `false`, silently skipping first-run setup with reason `"not-installed"`. the marker is never written, so every subsequent invocation from that cwd retries and skips again indefinitely. the same scenario applies to any configured npm prefix under the home dir (e.g., `~/.npm-global/lib/node_modules/…`). the workaround is to run from a project subdirectory, but the user has no indication anything is wrong.

### Issue 2 of 2
test/first-run.test.ts:1217-1235
**missing vitest coverage for partial/incomplete marker (claim written, process dies before finalize)**

the second-run skip test exercises a marker produced by a successful finalize. there is no test that pre-creates a marker containing only `{ version, startedAt }` (i.e., the claim was written but finalization never ran because the process was killed mid-setup) and then asserts that `ensureFirstRunSetup` returns `{ ran: false, reason: "already-done" }`. the design intention is that the claim itself is the idempotency gate, but that's an untested invariant: a test that writes the partial marker directly and calls `ensureFirstRunSetup` would pin this deliberately and guard against any future accidental "re-run on incomplete marker" logic.

_{Reviews (3): Last reviewed commit: "docs(upgrade): note the first-run setup ..." | Re-trigger Greptile}