Epic: NetScript Process Manager — bare-metal supervisor + admin console (pup/pm2 done right)

[rickylabs]

Epic — NetScript Process Manager

Part of #327 (Deployment epic, bare-metal lane). No closing keyword — this umbrella closes by hand when its children land.

The bare-metal deployment target of #327: how NetScript apps are run, supervised, and administered on bare metal. The concept of pup + pm2, rebuilt for 2026 as a first-party NetScript plugin (@netscript/plugin-process-manager(-core), CLI group netscript pm) at the quality bar of workers/auth.

1. Problem statement

Today --no-aspire bare-metal supervision is zero automation beyond deno task --cwd <m> dev run by hand in N terminals. Production restart/liveness is 100% delegated to systemd/Servy with no NetScript-owned aggregate status/logs, no runtime-mutable process list, no admin console. This epic fills that gap without re-importing pm2's god-daemon failure class.

2. Prior art (verdicts)

• pup (MIT, dormant ~19.5mo): excellent concept — declarative pup.json, 3 start policies, one REST control plane consumed by CLI/plugins/UI alike. Aged code: dax-sh over Deno.Command, deprecated @std/io readLines, god-object Pup class, bespoke polling-IPC telemetry, unfixed descendant-kill bug. We keep the concept, not the code.
• pm2 (v7, Node/Bun): rich restart strategies worth matching; its always-on god-daemon caused repeated unbounded-RSS (150GB+) and daemon-duplication incidents — a structural warning, not a model.
• Servy / systemd: NetScript already ships production Servy + systemd adapters behind OsServicePort; extend (WatchdogSec/Type=notify/hardening/cgroups), don't replace.
• process-compose / s6-rc / Quadlet: the generator-to-native-supervisor precedent and the dependency-ordered graph model we converge on.

3. Architecture (one paragraph)

Supervision engine as a library: dev mode runs it foreground-attached (netscript pm dev, no daemon); production compiles the declarative process graph into OS-native units (systemd/Servy via the existing renderers + OsServicePort, extracted to @netscript/deploy-core at PM-20), and the pm's resident piece is a control-plane service — itself one more OS-supervised unit hosting the typed oRPC control plane, never a parent of the workload. If it dies, the workload keeps running and the OS restarts the control plane. This structurally eliminates the god-daemon failure mode.

4. Scope / non-scope (binding)

In: typed dependency-ordered process-graph contract; dev foreground engine; compile-to-OS-units; resident control-plane oRPC service; netscript pm CLI (pup parity floor); OTEL netscript.process domain; --no-aspire resolvers; browser-served admin console (desktop packaging deferred, PM-32); OsServicePort renderer extensions; packages/deploy-core extraction.
Out: re-implementing restart/liveness in production (OS owns it); a deployment/rollout system (#327 owns it); a monitoring product (OTEL export only); a production load balancer; milestone-1 N-instance clustering (OF-5 → Backlog, PM-35); macOS/launchd (OF-6). No god-daemon, no SaaS monitoring, no git+SSH deploy inside the pm, no untyped config, no fake cluster mode.

5. Surfaces

• A) Admin console — one Fresh app, three modes (OF-2): browser-served by the control-plane service ships first (PM-29); Deno-Desktop packaging second (PM-32, soft dep feat(deploy): single-artifact packaging + release server + snapshot updater (substrate) #456/feat(sdk): in-process link-mode adapter for single-process service mounting #451); embedded DashboardPanelContribution panel third (PM-33, gated on CR-DDX-HOSTAGNOSTIC to epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6) #400).
• B) Pure CLI (netscript pm <verb>) — pup/pm2 parity floor, leveraging the OTEL/oRPC/deploy seams NetScript ships for free (OF-1, OF-7).

6. Owner forks — RATIFIED 2026-07-06

All nine forks ratified by the owner (in-session, Stage H): OF-1..OF-8 = recommendation (a); OF-5 clustering explicitly re-homed to Backlog / Triage (PM-35); OF-9 hard fork resolved: milestone 1 = 0.0.1-beta.8 (beta.7 already carries 28 open issues). PM-0 rides beta.6 as an independent fix-forward precursor.

7. Cross-epic dependency edges

• epic: NetScript enterprise deployment framework (cloud-agnostic + bare-metal, CLI + Aspire) #327 — parent (bare-metal lane placement).
• epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6) #400 dev-dashboard — CommandInvokePort first-definer (dashboard-defines-first, recorded bidirectional fallback); CR-DDX-HOSTAGNOSTIC change request (gates PM-33 only); Aspire command kind consumed, never extended.
• feat(sdk): in-process link-mode adapter for single-process service mounting #451 / feat(deploy): single-artifact packaging + release server + snapshot updater (substrate) #456 (desktop Tier-4) — soft deps for PM-32 only.
• [Deploy-S9] Bare-metal enterprise hardening (stable): cross-host HA + external secret store + signing #345 — re-scoped to cross-host HA/secrets/signing; per-host multi-instance moved here (PM-35).
• fresh-ui L3 blocks/ promotion — shared dep for PM-29 (can ship on L2 + local composition if promotion lags).

8. Milestone train (post-ratification)

• 0.0.1-beta.6: PM-0 (hard placement — independent fix-forward).
• 0.0.1-beta.8 (M1, per OF-9): PM-1..PM-31 (v1-min cuttable floor = 21 slices) + PM-32/PM-33 (M2, soft-dep feat(deploy): single-artifact packaging + release server + snapshot updater (substrate) #456/feat(sdk): in-process link-mode adapter for single-process service mounting #451; PM-33 slips if the epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6) #400 CR is unresolved).
• 0.0.1-stable: PM-34 + re-scoped [Deploy-S9] Bare-metal enterprise hardening (stable): cross-host HA + external secret store + signing #345 convergence.
• Backlog / Triage: PM-35 (per-host multi-instance / clustering, per owner OF-5 pick).

9. Sub-issues

• PM-0 [process-manager PM-0] Wire linux-service/windows-service deploy targets + fix resolveTargetConfig key mismatch + de-gate flat verbs #511
• PM-1 [process-manager PM-1] Process-graph contract v1 (ProcessGraphShape/ProcessSpecShape + state vocabulary + restart policies) #512
• PM-2 [process-manager PM-2] Telemetry: netscript.process domain + ProcessInstrumentationLike facade #513
• PM-3 [process-manager PM-3] Core package scaffold: ports + KV registry adapter #514
• PM-4 [process-manager PM-4] Restart controller: pure nextDelay(state, policy, clock) #515
• PM-5 [process-manager PM-5] Process runner: Deno.Command-native spawn + descendant-tree kill #516
• PM-6 [process-manager PM-6] Supervisor loop + composable start policies (autostart/cron/watch) #517
• PM-7 [process-manager PM-7] Log multiplexer + persistent sink (rotation) #518
• PM-8 [process-manager PM-8] Dev loop + ShutdownManager integration (engine side of pm dev) #519
• PM-9 [process-manager PM-9] ProcessManagerContract v1: the 18-route table #520
• PM-10 [process-manager PM-10] Control-plane oRPC service (PluginServiceContribution) #521
• PM-11 [process-manager PM-11] Loopback transport + address-descriptor discovery + CLI degraded mode #522
• PM-12 [process-manager PM-12] Token auth: opaque bearer + 0o600 secrets + deny-remote default #523
• PM-13 [process-manager PM-13] Event stream + follow-logs (eventIterator, live-only v1) #524
• PM-14 [process-manager PM-14] Telemetry wiring: span/metric catalog + 14-point checklist #525
• PM-15 [process-manager PM-15] systemd renderer knobs: Type=notify, WatchdogSec, hardening, cgroups v2 #526
• PM-16 [process-manager PM-16] Pure-Deno sd_notify helper (+ abstract-namespace spike) #527
• PM-17 [process-manager PM-17] OsServicePort capability descriptor + warn-and-omit #528
• PM-18 [process-manager PM-18] Conventions wiring: ServiceDeployTargetPorts → wired 8-op adapters #529
• PM-19 [process-manager PM-19] Compile adapters: ProcessSpec → systemd/Servy unit configs #530
• PM-20 [process-manager PM-20] Extract packages/deploy-core (@netscript/deploy-core) + promote F-DEPLOY gates #531
• PM-21 [process-manager PM-21] Deploy-facing schema: process-graph knobs on deploy.targets.linux/.windows #532
• PM-22 [process-manager PM-22] --no-aspire resolvers + pm explain provenance #533
• PM-23 [process-manager PM-23] AspireResource[] resolver (manifest-wins precedence) #534
• PM-24 [process-manager PM-24] pm scaffold.plugin.json + plugin add typed glue (pm.config.ts) #535
• PM-25 [process-manager PM-25] netscript pm CLI router + read verbs (+ degraded-local reads) #536
• PM-26 [process-manager PM-26] Lifecycle verbs via the shared CommandInvokePort shape #537
• PM-27 [process-manager PM-27] pm dev: foreground multiplexer over the engine dev loop #538
• PM-28 [process-manager PM-28] pm monitor: live status + follow stream (no TUI lib) #539
• PM-29 [process-manager PM-29] Admin console: Fresh app, browser-served by the control plane #540
• PM-30 [process-manager PM-30] Docs wave: 7 pages + cli-reference staleness fix #541
• PM-31 [process-manager PM-31] Merge-readiness e2e: scaffold suites + JSR-scoped publish dry-run #542
• PM-32 [process-manager PM-32] Desktop packaging of the console (deno desktop, 5-target cross-compile) #543
• PM-33 [process-manager PM-33] DashboardPanelContribution "Process Control" panel #544
• PM-34 [process-manager PM-34] systemd --user + linger non-root install mode #545
• PM-35 [process-manager PM-35] Per-host multi-instance / clustering (template units + reusePort) #546

10. Open questions (carried from plan §9)

1. Telemetry T2 owner sign-off on E15 (mint only netscript.process; no netscript.service.instance).
2. epic: NetScript Dev Dashboard — the Aspire/Scalar satellite that drives the framework (ships as a plugin, beta.6) #400's answer to CR-DDX-HOSTAGNOSTIC — gates PM-33's milestone only.
3. followLogs rate-cap numbers (bounded policy required by PM-13 acceptance; exact figures at implementation).
4. fresh-ui L3-blocks sequencing for PM-29.

11. Design source

.llm/runs/plan-process-manager--seed/ on PR #504: plan.md (Stage E, amended at Stage F, PLAN-EVAL PASS) + research/design/d1..d5-*.md + research.md §C1–C7.

RFC #820 additions (owner-ratified 2026-07-17 — PR #822)

• PM-A feat(pm): graph adoption & reconcile contract [PM-A] #827 — graph adoption & reconcile contract
• PM-B feat(pm): supervised-child runtime helper — pipe-EOF liveness + descendant cleanup [PM-B] #828 — supervised-child runtime helper (pipe-EOF liveness + descendant cleanup)

Acceptance amendments applied on PM-1 #512, PM-5 #516, PM-15 #526 (see each issue's RFC section). Sequencing: PM is the first shipping wave (beta.12) — desktop singleton-graph (#830, beta.14) consumes this epic's engine.

PM-C addition (owner-directed 2026-07-17)

• PM-C feat(pm): Windows Task Scheduler adapter — cron-policy processes compile to Scheduled Tasks [PM-C] #844 — Windows Task Scheduler adapter (cron-policy → Scheduled Tasks; wraps schtasks, adopts Deno.cron.persistent feat(ext/cron): scaffold Deno.cron.persistent API (no backends yet) denoland/deno#33965 when its backends land) — beta.13