Merge pull request #91 from freshtechbro/codex/package-postinstall-autostart

feat: reconcile autostart during package postinstall

Author: freshtechbro

README.md

@@ -115,11 +115,13 @@ npx --no-install opendevbrowser help
 
 Published npm consumer proof is tracked separately in [docs/RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) through `scripts/registry-consumer-smoke.mjs`.
 
-Set `OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1` before `npm install` only if you need a packaging smoke test that avoids the install-time managed-skill refresh entirely.
+Set `OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1` before `npm install` only if you need a packaging smoke test that exits the legacy package lifecycle shim before built postinstall code imports. Set `OPDEVBROWSER_SKIP_INSTALL_AUTOSTART_RECONCILIATION=1` when you only want to skip install-time daemon auto-start reconciliation.
 
 See [docs/FIRST_RUN_ONBOARDING.md](docs/FIRST_RUN_ONBOARDING.md) for the full onboarding checklist, [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) for runtime inventory, and [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the live CLI and tool surface.
 
-Successful installs reconcile daemon auto-start on supported platforms so the relay is available on login. macOS LaunchAgents persist a stable `WorkingDirectory` under `~/.cache/opendevbrowser` so launchd does not start the daemon from `/`. If the current CLI entrypoint lives under a transient temp-root path such as a first-run `/tmp` or `/private/tmp` workspace, OpenDevBrowser refuses to persist that path as auto-start. Rerun `opendevbrowser daemon install`, or `npx --no-install opendevbrowser daemon install` from a persistent local package install, from a stable install location if you want login auto-start; remove it later with `opendevbrowser daemon uninstall`.
+CLI/plugin installs still reconcile daemon auto-start on supported platforms after successful install so the relay is available on login. Raw npm global package postinstall also best-effort reconciles auto-start when npm lifecycle context clearly indicates a global install. Local, ambiguous, conflicting, or non-npm package-manager contexts skip package postinstall auto-start without failing package installation.
+
+Package postinstall auto-start targets the packaged CLI entrypoint `dist/cli/index.js`, not the lifecycle shim at `scripts/postinstall-sync-skills.mjs`. `src/cli/daemon-autostart.ts` owns platform safety and refuses to persist `_npx`, `/tmp`, `/private/tmp`, or onboarding workspace paths before writing LaunchAgent or Task Scheduler state. Package postinstall warnings are non-fatal; repair with `opendevbrowser daemon install`, inspect with `opendevbrowser daemon status`, or remove with `opendevbrowser daemon uninstall`.
 
 Bundled skills sync to **OpenCode, Codex, ClaudeCode, and AmpCLI** targets during install. `npx opendevbrowser` manages global or project-local targets according to the selected skills mode, and package installation (`npm install -g`, local tarball install, or equivalent) best-effort syncs the canonical bundled packs into the managed global targets during package `postinstall`. See [docs/CLI.md](docs/CLI.md) for exact target paths.
 
@@ -751,7 +753,7 @@ See [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the source-accura
 | `npx opendevbrowser --local` | Install to project config |
 | `npx opendevbrowser --with-config` | Also create opendevbrowser.jsonc |
 | `npx opendevbrowser --full` | Full install (config + extension assets) |
-| `npm install -g opendevbrowser` | Install persistent global CLI |
+| `npm install -g opendevbrowser` | Install persistent global CLI; npm global postinstall best-effort reconciles daemon auto-start |
 | `npx opendevbrowser --update` | Repair OpenCode package caches and plugin pins |
 | `npx opendevbrowser --uninstall` | Remove from config |
 | `npx opendevbrowser --version` | Show version |

docs/AGENTS.md

@@ -32,6 +32,15 @@ When command/tool/channel surface changes:
 - `README.md`
 - relevant `AGENTS.md` files
 
+When install, package postinstall, or daemon auto-start behavior changes:
+- `README.md`
+- `docs/CLI.md`
+- `docs/FIRST_RUN_ONBOARDING.md`
+- `docs/ARCHITECTURE.md`
+- `src/cli/AGENTS.md`
+- `scripts/AGENTS.md`
+- `tests/AGENTS.md`
+
 When canvas session/code-sync/projection behavior changes:
 - `docs/CLI.md`
 - `docs/SURFACE_REFERENCE.md`
@@ -85,6 +94,7 @@ When mirrored website inputs change (`docs/`, `skills/`, `assets/`, `CHANGELOG.m
 
 - Do not keep stale numeric claims when source has changed.
 - Do not document unsupported flags/commands.
+- Do not conflate CLI/plugin install auto-start reconciliation with raw package postinstall. Package postinstall is best effort, uses `dist/cli/index.js`, and skips local, ambiguous, conflicting, or non-npm package-manager contexts without failing installation.
 - Do not describe `canvas.starter.list` or `canvas.starter.apply` as unshipped once `PUBLIC_CANVAS_COMMANDS` includes them.
 - Do not describe `tsx-react-v1` as the shipped adapter lane; current docs must describe it as a legacy binding that migrates to `builtin:react-tsx-v2`.
 - Do not imply public-repo ownership of `frontend/`; website source is private.

docs/ARCHITECTURE.md

@@ -42,12 +42,9 @@ Daemon-backed `canvas` CLI requests inject the caller worktree as `repoRoot`; `C
 Canonical inventory and channel contracts: `docs/SURFACE_REFERENCE.md`.
 Frontend architecture and generation flow are documented in `docs/FRONTEND.md`.
 
-The CLI installer reconciles daemon auto-start after every successful install
-(macOS LaunchAgent, Windows Task Scheduler). Existing per-user entries are rechecked and repaired when they are missing or stale on
-supported platforms, and when the macOS LaunchAgent is malformed or lacks the stable `~/.cache/opendevbrowser` working directory; unsupported platforms are skipped and continue without auto-start. If the current CLI entrypoint is running from a
-transient temp-root path, install-time reconciliation refuses to persist it and surfaces guidance to rerun `daemon install` from a
-stable install location. `getAutostartStatus()` remains the canonical source of auto-start truth for both install reconciliation
-and `daemon status`, and a stable persisted auto-start entry remains authoritative even when the current invocation is transient.
+Install-time daemon auto-start reconciliation has two entrypoints. CLI/plugin install still reconciles after every successful install. Raw npm global package postinstall runs `src/cli/installers/package-postinstall.ts` best effort, re-exported through `src/cli/installers/postinstall-skill-sync.ts` to keep the shipped built import path stable, and only attempts auto-start when npm lifecycle context clearly indicates a global install. Local, ambiguous, conflicting, or non-npm package-manager contexts skip package postinstall auto-start without failing package installation.
+
+Both entrypoints reuse the same reconciliation and platform safety owner in `src/cli/daemon-autostart.ts` (macOS LaunchAgent, Windows Task Scheduler). Existing per-user entries are rechecked and repaired when they are missing or stale on supported platforms, and when the macOS LaunchAgent is malformed or lacks the stable `~/.cache/opendevbrowser` working directory; unsupported platforms are skipped and continue without auto-start. Package postinstall injects the packaged CLI entrypoint `dist/cli/index.js`, not the lifecycle shim at `scripts/postinstall-sync-skills.mjs`. If the current CLI entrypoint is running from a transient `_npx`, `/tmp`, `/private/tmp`, or onboarding workspace path, install-time reconciliation refuses to persist it and surfaces guidance to rerun `daemon install` from a stable install location. `getAutostartStatus()` remains the canonical source of auto-start truth for both install reconciliation and `daemon status`, and a stable persisted auto-start entry remains authoritative even when the current invocation is transient.
 
 ## Challenge orchestration ownership
 
@@ -565,7 +562,7 @@ Validation script:
 - `src/devtools/`: console/network/exception trackers and debug bundle channels.
 - `src/tools/`: tool definitions and response shaping.
 - `src/relay/`: relay server and protocol types.
-- `src/cli/`: CLI commands, daemon/autostart, `DaemonClient`, `RemoteManager`, `RemoteCanvasManager`, relay status cache, and installers.
+- `src/cli/`: CLI commands, daemon/autostart, `DaemonClient`, `RemoteManager`, `RemoteCanvasManager`, relay status cache, and installers, including package postinstall orchestration.
 - `src/cli/commands/artifacts.ts`: artifact lifecycle cleanup (`artifacts cleanup --expired-only`).
 - `extension/`: Chrome extension UI and background logic.
 - `opendevbrowser-website-deploy/frontend/`: private website app and generated content pipeline.

docs/CLI.md

@@ -70,9 +70,9 @@ npx --no-install opendevbrowser help
 Load extension unpacked from:
 - `$WORKDIR/node_modules/opendevbrowser/extension`
 
-Set `OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1` before `npm install` only if you need a packaging smoke test that avoids the install-time managed-skill refresh entirely.
+Set `OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1` before `npm install` only if you need a packaging smoke test that exits the legacy package lifecycle shim before built postinstall code imports. Set `OPDEVBROWSER_SKIP_INSTALL_AUTOSTART_RECONCILIATION=1` when you only want to skip install-time daemon auto-start reconciliation.
 
-By default (`--skills-global`), the CLI installs bundled skills to global OpenCode/Codex/ClaudeCode/AmpCLI locations. Use `--skills-local` for project-local locations or `--no-skills` to skip CLI-managed skill installation. Package installation (`npm install -g`, local tarball install, or equivalent) also best-effort syncs the canonical bundled packs into the managed global skill targets during package `postinstall`. Use `--full` to always create `opendevbrowser.jsonc` and pre-extract extension assets.
+By default (`--skills-global`), the CLI installs bundled skills to global OpenCode/Codex/ClaudeCode/AmpCLI locations. Use `--skills-local` for project-local locations or `--no-skills` to skip CLI-managed skill installation. Package installation (`npm install -g`, local tarball install, or equivalent) also best-effort syncs the canonical bundled packs into the managed global skill targets during package `postinstall`. Raw npm global package postinstall best-effort reconciles daemon auto-start only when npm lifecycle context clearly indicates a global install; local, ambiguous, conflicting, or non-npm package-manager contexts skip auto-start without failing package installation. Use `--full` to always create `opendevbrowser.jsonc` and pre-extract extension assets.
 
 Installer inventory:
 - `--skills-global` and `--skills-local` sync the 10 canonical `opendevbrowser-*` packs under `skills/` into managed global or project-local agent directories.
@@ -220,13 +220,11 @@ npx opendevbrowser --skills-local
 npx opendevbrowser --no-skills
 ```
 
-On successful installs, the CLI reconciles daemon auto-start on supported platforms (macOS/Windows) so the relay is available on
+On successful installs, the CLI/plugin installer reconciles daemon auto-start on supported platforms (macOS/Windows) so the relay is available on
 login. Existing installs are rechecked and repaired when the per-user auto-start entry is missing or stale on macOS and Windows,
-and when the macOS LaunchAgent is malformed or missing its stable non-root working directory. If the current CLI entrypoint lives under a transient temp-root path (for example a
-first-run `/tmp` or `/private/tmp` `npx` workspace), OpenDevBrowser refuses to persist that path as auto-start. Plugin install
-still succeeds, but auto-start repair warns and you must rerun `opendevbrowser daemon install` from a stable install location, or
-`npx --no-install opendevbrowser daemon install` from a persistent local package install. You can remove auto-start later with
-`opendevbrowser daemon uninstall`.
+and when the macOS LaunchAgent is malformed or missing its stable non-root working directory. Raw npm global package postinstall also runs the same reconciliation best effort when npm lifecycle context clearly indicates a global install. Package postinstall targets `dist/cli/index.js`, not `scripts/postinstall-sync-skills.mjs`, and all package warnings are non-fatal.
+
+If the current CLI entrypoint lives under a transient temp-root path (for example a first-run `/tmp` or `/private/tmp` `npx` workspace), OpenDevBrowser refuses to persist that path as auto-start. Plugin install still succeeds, and package install still exits successfully, but auto-start repair warns or skips. Rerun `opendevbrowser daemon install` from a stable install location, or `npx --no-install opendevbrowser daemon install` from a persistent local package install. You can inspect with `opendevbrowser daemon status` and remove auto-start later with `opendevbrowser daemon uninstall`.
 
 ### Update
 
@@ -382,7 +380,10 @@ Behavior:
 - when the current invocation is transient, a stable persisted auto-start entry can still report `health="healthy"`; `expectedCommand` is omitted instead of advertising the transient current path as the repair target.
 - `daemon status` returns exit code `0` when the daemon is reachable even if auto-start is missing, stale, or malformed, and `10` when the daemon is not running.
 - Successful plugin installs surface auto-start reconciliation through `autostartAction`; `autostartError` is included only when repair fails.
-- If install-time reconciliation is running from a transient temp-root CLI path, it refuses to write auto-start and reports `autostartAction="repair_failed"` with guidance to rerun `opendevbrowser daemon install` from a stable install location.
+- Raw npm global package postinstall best-effort reconciles auto-start only when npm lifecycle context clearly indicates a global install. Local, ambiguous, conflicting, or non-npm package-manager contexts skip auto-start without failing package installation.
+- Package postinstall auto-start uses `dist/cli/index.js` as the packaged CLI entrypoint and never persists `scripts/postinstall-sync-skills.mjs`.
+- `OPDEVBROWSER_SKIP_INSTALL_AUTOSTART_RECONCILIATION=1` skips install-time auto-start reconciliation only. `OPDEVBROWSER_SKIP_POSTINSTALL_SKILL_SYNC=1` remains the legacy full package lifecycle shim skip because the shim exits before importing built code.
+- If install-time reconciliation is running from a transient temp-root CLI path, it refuses to write auto-start and reports `autostartAction="repair_failed"` for plugin installs or a non-fatal package postinstall warning, with guidance to rerun `opendevbrowser daemon install` from a stable install location.
 
 Exit codes align with the CLI:
 - `0`: success

docs/FIRST_RUN_ONBOARDING.md

@@ -56,6 +56,7 @@ Expected:
   - `$CODEX_HOME/skills`
   - `$CLAUDECODE_HOME/skills`
   - `$AMP_CLI_HOME/skills`
+- local tarball package postinstall skips daemon auto-start because the npm lifecycle context is local, not a clear global install
 - each populated global skill directory contains `.opendevbrowser-managed-skills.json` plus one `.opendevbrowser-managed-skill.json` sentinel per bundled canonical pack
 
 ## 2b) Validate the help-led quick-start path
@@ -147,15 +148,16 @@ Expected:
 - extension assets are extracted to `~/.config/opencode/opendevbrowser/extension`
 - extracted assets now include `manifest.json`, `popup.html`, `canvas.html`, `dist/`, and `icons/`
 - `OPENCODE_CONFIG_DIR` isolates config lookup only; it does not relocate the extracted extension asset directory
-- because this guide uses a temp `WORKDIR`, install-time daemon auto-start reconciliation may warn instead of persisting a background entry
+- because this guide uses a temp `WORKDIR`, CLI/plugin install-time daemon auto-start reconciliation may warn instead of persisting a background entry
+- raw package postinstall auto-start is best effort and skips local, ambiguous, conflicting, or non-npm package-manager contexts without failing package installation
 - if persistent login auto-start is desired after onboarding, rerun `opendevbrowser daemon install` from a stable install location outside the temp workspace; macOS should persist `WorkingDirectory=~/.cache/opendevbrowser`
 
 ## 3c) Stable auto-start follow-up
 
 The onboarding workspace proves first-run package behavior, not long-lived daemon auto-start. Do **not** treat `$WORKDIR` as the
 final login-start location.
 
-When you want to validate daemon auto-start, rerun from the intended persistent install location:
+When you want to validate daemon auto-start, rerun from the intended persistent install location. A raw `npm install -g opendevbrowser` may already reconcile auto-start during package postinstall when npm lifecycle context clearly indicates a global install, but the explicit daemon commands remain the repair and verification surface:
 
 ```bash
 # Global install