Phase 1C: server distribution polish (CLI + install + supervision + upgrade)

[aterrylu]

Summary

Phase 1C of the desktop-app initiative. Polishes the autonomOS Server distribution into something shippable to external users: a public curl install.sh | bash install path, OS-native daemon supervision (launchd/systemd-user, no pm2), an atomic upgrade flow, and a hard-cutover migration for existing pm2 users.

Built end-to-end as 5 self-contained commits, each individually reviewable.

What ships

Subcommand	Behavior
autonomos start	Run server in foreground (default when no subcommand). Forwards --port / --embedded flags.
autonomos stop	Read PID file, SIGTERM, wait up to 10s, escalate to SIGKILL if needed.
autonomos status	Daemon state — version, pid, port, hostname, uptime, url.
autonomos install-service	Write launchd plist (mac) or systemd-user unit (linux). User-scope, no sudo.
autonomos uninstall-service	Stop daemon, remove service file.
autonomos upgrade	Fetch latest GitHub release, verify SHA256, atomic swap, restart daemon.
autonomos migrate-from-pm2	One-shot migration: stop pm2's autonomos + install OS-native supervisor.

install.sh at scripts/install.sh:

• Cross-platform Bash (darwin-arm64/x64 + linux-x64/arm64)
• Downloads from GitHub Releases
• Verifies SHA256 before extraction
• Installs to $HOME/.local by default (no sudo)
• Auto-detects pm2-managed autonomos and migrates before installing the new supervisor
• Auto-runs install-service post-install

HTTP API additions:

• GET /api/system/version — version + platform + arch
• POST /api/system/upgrade — server-side upgrade (callable from dashboard; UI button is a follow-up)

Release pipeline at .github/workflows/release.yml:

• Triggered by v* tags
• Matrix: macos-14 (arm64), macos-13 (x64), ubuntu-latest, ubuntu-24.04-arm
• Builds dashboard → embeds → bundles → tarballs each platform
• Publishes a GitHub Release with all tarballs + SHA256SUMS

Architecture changes

• New package: packages/cli/ — autonomos CLI, depends on @autonomos/server
• New module: packages/server/src/run.ts — exports runServer(argv); the CLI's start subcommand calls this directly (no subprocess hop). Old packages/server/src/index.ts becomes a thin entry that calls runServer for backward compat with Phase 1B's Electron-spawn contract.
• New module: packages/server/src/pid-file.ts — JSON PID file at $configDir/autonomos.pid. Written on listen, removed on shutdown. Skipped in embedded mode.
• New module: packages/server/src/version.ts — single source of truth for the running version.
• New module: packages/server/src/upgrade.ts — shared upgrade logic used by CLI + HTTP endpoint.
• packages/server/build/build-binary.ts — now bundles packages/cli/src/index.ts (the CLI is the top-level entry; it dispatches argv-only invocations to runServer for the Phase 1B contract). Also writes the bundle's own package.json for runtime version reading.

Backward compat for existing pm2 users

The migration is hard cutover, automatic on upgrade:

1. curl install.sh | bash detects pm2-managed autonomos
2. Auto-runs autonomos migrate-from-pm2:
   • pm2 stop autonomos
   • pm2 delete autonomos
   • pm2 save
   • install-service --force (writes plist/unit + activates)
3. Daemon now under OS-native supervision; existing pm2 setup is gone

install-service itself refuses to overwrite an active pm2 install unless --force is passed — prevents accidental port collisions.

Test plan

• Hermetic end-to-end (scripts/test-install.sh):
  • Build tarball + SHA256SUMS
  • install.sh with BUNDLE_URL=file:// + INSTALL_PREFIX=/tmp
  • Verify wrapper, --help, start, status, /api/host probe, stop
  • install-service --no-activate under test prefix → verify plist/unit written
  • uninstall-service → verify plist/unit removed
• CI matrix (.github/workflows/test-install.yml):
  • macos-14 (darwin-arm64) + ubuntu-latest (linux-x64)
  • Runs test-install.sh on PR
• tsc -b clean
• npx biome check packages/ clean (only pre-existing useTerminal.ts warnings unrelated to 1C)
• Manual verification on existing pm2 setup — Terry to run on his actual deployment before merging. The make prod/pm2 path is hard to fully exercise in CI.

What's NOT in this PR

• Dashboard Settings → About UI for the upgrade button. The /api/system/upgrade endpoint exists; UI integration is a small follow-up.
• Windows distribution (no Windows Service install yet; deferred per Phase 1C scope).

Commits (5)

1. feat(cli): commit 1/5 — packages/cli/ scaffold + start/stop/status
2. feat(cli): commit 2/5 — install-service + uninstall-service
3. feat: commit 3/5 — install.sh + GitHub Releases workflow
4. feat: commit 4/5 — autonomos upgrade + /api/system/* endpoints
5. feat: commit 5/5 — pm2 migration + hermetic test + CI matrix

Existing make dev/make prod/pm2 flows: untouched until a user explicitly runs autonomos upgrade or migrate-from-pm2.

🤖 Generated with Claude Code

[nox-0x]

Requesting changes — the release workflow as written will fail on the first v* tag push because bun build-binary.ts --tarball produces no tarballs (the script only honors TARBALL=1 env, per its own embedded warning comment), so the Upload tarball step will then 404. That breaks the entire distribution path this PR is built around.

Everything else looks solid: CLI subcommand layout is clean, PID file + status state machine is well thought out, the atomic-swap upgrade flow with .previous rollback is sensible, the pm2 migration cleanly hands off to install-service, and the hermetic test (scripts/test-install.sh) actually exercises a real install→start→status→stop→install-service→uninstall-service round-trip on both macOS and Linux.

Minor follow-ups (not blockers, easy to land later):

• scripts/test-install.sh lines 89–94 — the "Verifying /api/system/version" section never actually calls the endpoint. It parses the token preview from the server log and stops. Since one of Phase 1C's selling points is the new /api/system/* surface, exercising it in CI would be cheap (fetch via the auth-cookie endpoint or via Authorization header — token is in the log).
• packages/server/src/upgrade.ts performUpgrade — version comparison is equality-only (latestVersion === currentVersion). If the user is on a newer version than latest (manual install / dev build), autonomos upgrade will silently downgrade them. Pre-1.0 this is fine, but a < check would catch it cheaply later.
• packages/cli/package.json — "bin": { "autonomos": "./src/index.ts" } doesn't work via npm install (npm can't exec TS). Phase 1C ships via install.sh + bundle, so this isn't load-bearing today, but it's a footgun if someone tries npm i -g @autonomos/cli later.

Fix the release.yml tarball flag and this is good to ship.

[nox-0x]

Reviewed Phase 1C end-to-end. Confirming the existing unresolved thread on release.yml:48 is a real, still-present blocker — the workflow passes --tarball as argv, but build-binary.ts:51 only honors TARBALL=1 env var (scripts/test-install.sh:51 does it correctly). On a real v* tag push, no .tar.gz is produced and the Upload tarball step fails on a missing path, leaving the release empty and install.sh with nothing to fetch. The hermetic CI test does not exercise release.yml and so does not catch this.

One-line fix: run: TARBALL=1 bun packages/server/build/build-binary.ts (matching test-install.sh).

Otherwise the design is solid:

• runServer(argv) extraction + pid-file.ts JSON contract is clean; embedded mode correctly skips the PID file.
• Atomic upgrade flow (live → .previous, .new → live, .previous retained for manual rollback) is well-thought-out.
• install-service correctly refuses to overwrite a pm2 install without --force; migration path is auto-triggered from install.sh.
• detectProgramArgs() handles node-runtime layouts correctly, and the supervisor file's reference to $INSTALL_DIR/index.js continues to resolve after autonomos upgrade swaps the bundle.
• systemd ExecStart uses POSIX single-quote shell escaping for args; plist uses XML escaping. Good attention to detail.

Submitting as COMMENT rather than APPROVE specifically because the release-pipeline bug, if not caught before the first tag, will block the public install path that is the headline deliverable of this PR. Once that one-line fix lands the rest looks ready to merge.

[nox-0x]

Requesting changes — the prior critical thread on release.yml:48 (--tarball flag isn't read by build-binary.ts) is still unaddressed, so the first real v* tag push will fail at Upload tarball and the GitHub Release will have no artifacts for install.sh to fetch.

build-binary.ts:51 only consults process.env.TARBALL === "1", and the comment right above it explicitly warns "Bun's CLI eats unknown long-flags, so we use an env var instead." The hermetic test-install.sh:51 correctly uses TARBALL=1 bun …, but the release workflow still passes --tarball as argv. Since test-install.yml doesn't exercise release.yml, this only surfaces on the first tagged release.

Trivial fix — pick one:

• release.yml:48 → run: TARBALL=1 bun packages/server/build/build-binary.ts (matches the test script), or
• teach build-binary.ts to also accept process.argv.includes("--tarball").

Everything else looks good: PID-file + status/stop lifecycle is clean, atomic swap in upgrade.ts is well-structured (keeps .previous for manual rollback), pm2 migration preserves PORT, install-service refuses to overwrite an active pm2 install without --force, hermetic test exercises the end-to-end install flow. Ship it once release.yml is fixed.

[nox-0x]

Requesting changes — the release workflow as-currently-written won't produce tarballs, so the first v* tag push will publish a release with no install artifacts.

The existing unresolved critical thread on .github/workflows/release.yml:48 (from nox-0x) is still load-bearing: that step runs bun packages/server/build/build-binary.ts --tarball, but build-binary.ts:51 only consults process.env.TARBALL === "1". Bun's CLI eats unknown long flags before forwarding argv, so --tarball is silently dropped, no .tar.gz is produced, and the Upload tarball step fails on a missing file. The hermetic test correctly uses TARBALL=1 and so doesn't exercise this path — it's release-only and won't surface until tag time.

Fix is one line — either swap the workflow step to TARBALL=1 bun packages/server/build/build-binary.ts, or teach build-binary.ts to also accept --tarball via process.argv.includes. Resolve the existing thread once done.

Everything else looks solid:

• CLI dispatcher / start/stop/status lifecycle is clean, PID-file source-of-truth + isPidAlive fallback is the right pattern.
• install-service correctly refuses to overlay an active pm2 install absent --force, and migrate-from-pm2 preserves the pm2 PORT into the new supervisor.
• upgrade.ts SHA256-verifies before atomic swap and keeps a .previous directory for manual rollback — sensible.
• Hermetic test-install.sh exercises the full install → start → status → /api/host → stop → install-service → uninstall-service loop on the CI matrix, including a stub claude so the provider check doesn't kill the daemon.

No new critical findings beyond the pre-existing thread.

[nox-0x]

Requesting changes — the existing critical unresolved thread on .github/workflows/release.yml:48 is still valid after the four follow-up fixes, and it blocks the entire distribution path on the first real tag push.

release.yml step "Build bundle + tarball" runs bun packages/server/build/build-binary.ts --tarball, but build-binary.ts:51 only honors process.env.TARBALL === "1". The hermetic test (scripts/test-install.sh:51) and package.json's build:binary:all are written consistent with that (the latter uses --all, which the script does check via process.argv.includes("--all") at line 81 — so there's also an internal inconsistency: --all is read from argv but --tarball is intentionally not). On a v* tag push, the build step succeeds, no .tar.gz is produced, and the Upload tarball step fails with "no files found." No release artifacts → install.sh has nothing to fetch.

Fix is one-line — either:

• run: TARBALL=1 bun packages/server/build/build-binary.ts in release.yml, or
• add process.argv.includes("--tarball") to wantTarball in build-binary.ts.

Everything else in this PR looks solid:

• The pm2 migration path (detect → stop → delete → save --force → install-service with preserved PORT) is careful and the four fixup commits address the right edge cases (PATH-less pm2, empty-dump persistence, PORT preservation).
• PID-file flow, atomic upgrade swap (with .previous for manual rollback), and the launchd/systemd templates (XML-escaped and shell-quoted properly) all look correct.
• The hermetic test exercises start/stop/status/install-service/uninstall-service end-to-end, including a claude stub for CI environments without the real CLI.
• runServer's PID-file write is correctly skipped in embedded mode, with cleanup on SIGTERM/SIGINT.

The release-workflow bug is the only blocker. Happy to flip to approve once it's a one-line patch.

[aterrylu]

Addressed in commit 93f247e:

Critical (the unresolved blocker):

• .github/workflows/release.yml:48 — flipped to TARBALL=1 bun packages/server/build/build-binary.ts. You're right that --tarball was getting eaten by bun's CLI before reaching argv — the matching working pattern is in scripts/test-install.sh:51 which uses TARBALL=1, now mirrored in the workflow.

Non-blocker follow-ups (all three):

• scripts/test-install.sh — /api/system/version is now actually fetched and validated, with AUTONOMOS_TOKEN overridden to a per-run test value so the test stays hermetic from the host's ~/.autonomos/token.
• packages/server/src/upgrade.ts — replaced equality with a tiny compareSemver() helper. currentVersion >= latestVersion now returns up-to-date; downgrade-by-misclick is prevented.
• packages/cli/package.json — removed the bin field. Phase 1C ships via install.sh + bundle + node wrapper script; pointing bin at .ts would have silently failed under npm i -g. Left an inline _comment_no_bin so the next person doesn't re-add it without reading the trade-off.

Verification:

• ✓ Local hermetic test passes including the new /api/system/version assertion ({"version":"0.0.1","platform":"darwin","arch":"arm64"})
• ✓ tsc -b + biome both clean

Ready for re-review.

[nox-0x]

Approving — solid end-to-end shipping infrastructure with the prior critical (release.yml TARBALL env) cleanly addressed in 93f247e; no new blocking issues.

Reviewed the full diff:

• release.yml now uses TARBALL=1 matching test-install.sh. currentTarget() correctly maps each matrix runner to its tarball name, the upload paths line up, and SHA256SUMS is computed in the publish job.
• upgrade.ts download → SHA256 verify → atomic rename → keep .previous for rollback is correct. The compareSemver downgrade-guard is the right behavior (and the pre-release-stripping limitation is explicitly documented). Cached ESM modules survive the rename, so the post-swap shutdown path won't break from missing files.
• PID file lifecycle is clean: written on listen in standalone-only, removed on shutdown, defensive cleanup in stop. isPidAlive via kill(pid, 0) is the standard pattern.
• Service templates — plist XML-escaping + systemd shell-quoting both look correct. process.argv[0] resolves to absolute node path so the supervisor doesn't need PATH lookup for the entry. Auto-detected programArgs is overridable via --bin.
• pm2 migration — pm2 save --force is correctly used (the comment captures why --force is mandatory after delete). findPm2Binary walks the bun/volta/homebrew dirs that non-interactive curl | bash would otherwise miss. PORT is preserved through to install-service.
• Hermetic test — the v1.0 critique (parsing log output instead of fetching /api/system/version) is fixed; now actually does an authenticated GET with AUTONOMOS_TOKEN. Service-file written-then-removed assertion runs under --no-activate so it doesn't touch the user's real launchd/systemd.
• /api/system/upgrade is behind requireAuth. The 500ms setTimeout → process.exit(0) flush window is acknowledged in the comment.

Minor follow-up nits (NOT blockers — fine in a later PR):

• runOrThrow error message includes stderr but not stdout — if launchctl emits diagnostic to stdout we lose it. Cosmetic.
• During the brief post-rename window before the supervisor restarts, dashboard serveStatic requests will 404 because the captured dashboardDist path no longer resolves. Acceptable transient.
• release.yml isn't gated by test-install.yml passing — a malformed tag push could publish broken artifacts. The author manually verifies before tagging today; fine for the scale.

PR is mergeable. The "manual verification on existing pm2 setup" checkbox in the description is the right gate before pushing the install endpoint live, but doesn't block the merge itself.