Supervision Laravel Package

Technical Evaluation

Architecture fit — plausible but unproven; scope is narrower than the name suggests. description.md discloses more than the package name does: a supervision layer for long-running PHP processes, with configurable health checks, automatic restarts, failure handling, a Laravel service provider, framework-agnostic usage, and hooks for custom monitoring logic. That is a meaningful, bounded capability — process/worker babysitting — not a general APM or observability platform. A TPM's first job is to place it correctly in the stack: this is a liveness and restart layer for daemons and queue workers, adjacent to Supervisor/systemd and Laravel Horizon's process management, not a replacement for Pulse, Telescope, or Sentry. The "framework-agnostic PHP usage" claim matters architecturally: it implies the Laravel integration is a thin wrapper over a core runtime, which is generally the more portable and more testable shape, but also means restart semantics may depend on how the host process was launched.

Integration feasibility — mechanically easy, evidentially blocked. Composer-installable, vendor-namespaced, Laravel service provider and config: the integration surface is conventional and low-effort. The blocker is not integration, it is evidence. Zero stars, zero dependents, zero score, and no visible release history mean there is no third-party production usage to borrow confidence from. If this package supervises other processes, the failure mode is worse than a normal dependency: a fault in the supervisor can leave workers dead while the app believes it is healthy, or worse, can trigger restart loops that amplify an incident. That raises the bar for source review above what a typical utility package requires.

Technical risk — concentrated in ownership, process semantics, and blast radius.

• Ownership risk: no visible maintainer history, no tagged releases, no CI signal. Assume single-maintainer, bus factor of one.
• Process-semantics risk: restart policies, backoff, grace periods, and signal handling are easy to get subtly wrong. A supervisor that restarts too aggressively can cause a thundering herd against a recovering database; one that backs off too gently leaves queues stalled.
• Privilege risk: supervision tooling often needs to signal, fork, or exec other processes. Confirm what it requires from the runtime user and whether it assumes pcntl/posix (absent or restricted on many containerised and Windows-adjacent environments).
• Data-path risk: determine whether health state is in-memory, in cache/Redis, in a log, or shipped to an external endpoint. Any outbound telemetry or phone-home must be disclosed and disabled by default.
• Duplication risk: if Supervisor/systemd, Horizon, or the platform's orchestrator (Kubernetes liveness probes, ECS health checks) already handle restarts, this package is competing with the most battle-tested layer in the stack.

Key questions to answer from source or from the maintainer:

1. What exactly does it supervise — queue workers, custom daemons, scheduler, HTTP health endpoints — and what triggers a restart?
2. Does it replace Supervisor/systemd, or sit alongside them? Who owns the process tree?
3. What are the PHP floor and Laravel version constraints, and are they enforced in CI?
4. Is there a tagged release, changelog, and stated backward-compatibility policy? Is there a LICENSE file, and does it permit forking and private distribution?
5. Where does health state live, and is any network egress performed or required?
6. What is the failure mode when the supervisor itself crashes — who supervises the supervisor?
7. What overhead does it add to worker startup and per-cycle checks?
8. Does it conflict with Horizon's worker management (two supervisors fighting over the same pool is a known self-inflicted outage pattern)?

Integration Approach

Stack fit — conditionally viable, only as a replacement for something, never as an addition. Laravel estates typically already run Supervisor or systemd for daemons, Horizon for queues, and Pulse/Sentry for visibility. The TPM question is not "does it install?" but "what do we remove if we adopt it?" If the answer is "nothing," the package is a second restart mechanism layered on the first, which is a reliability regression dressed as a reliability improvement. Fit is strongest in small, single-node deployments without an orchestrator — where Supervisor configs are hand-maintained and drift is a real cost. Fit is weakest in Kubernetes or ECS environments, where the platform already owns process liveness and an in-container supervisor is redundant.

Migration path — greenfield trial with a designed exit. There is nothing to migrate from; do not decommission existing process management during evaluation. Run in parallel on one non-critical worker group, with the existing Supervisor config left intact but disabled where it would contend for the same processes. Define the exit before starting: the integration must sit behind an internal interface (a ProcessSupervisor contract or equivalent) so the package is a binding swap, not a code change. Config and health-check definitions should be captured in the repo, not in the package's published defaults, so switching tools is a rewrite of one adapter.

Compatibility — pin and constrain. Install into a disposable app pinned to the exact PHP minor and Laravel major of the target service. Capture composer why and the resolved graph before and after to detect transitive pins that would block a future Laravel upgrade — a supervision utility must never become the reason the estate cannot move framework versions. Verify pcntl/posix availability in the actual runtime image, not on the developer laptop. Confirm behaviour under the container's PID 1 semantics: a supervisor not running as PID 1 receives no SIGTERM propagation, which is a classic container shutdown bug.

Sequencing — five gates, each with a named owner:

1. Source and supply-chain review — license, dependency depth, egress behaviour, process signals. Security sign-off is a gate, not a formality.
2. Sandbox install — package boots, publishes config, supervises one trivial daemon in a disposable environment.
3. Parallel canary — one internal, non-revenue worker group, fixed window (two to four weeks), existing supervisor disabled only for that group.
4. Measured comparison — restart latency, missed-cycle detection, false-positive restarts, worker restart storms, overhead per worker start.
5. Decision gate — adopt-and-fork, watch, or close. Broad rollout is discussed only after this gate, and only if step 4 produced numbers.

Operational Impact

Maintenance — the dominant lifecycle cost and the decisive factor. Zero dependents and no visible release cadence mean the adopting team becomes the de facto maintainer. Supervision code sits on the boundary between application and host, which is exactly the boundary that changes when base images, PHP versions, or orchestration platforms move. Budget explicitly for: forking into a private registry, pinning to a commit hash, and funding a small recurring allowance for security patches and Laravel-upgrade compatibility. If the team will not fund that line item, the package should not be adopted however well the canary behaves — the cost simply moves to an unplanned outage later.

Support — effectively self-support with an on-call penalty. No issue backlog to mine for known failure modes, no Stack Overflow footprint, no community to consult. When a worker pool stalls at 03:00, the responder will be reading unfamiliar source, not documentation. Any adoption must carry a runbook written during the trial: how restarts are triggered, how to disable the supervisor safely, where health state is visible, and what the expected log signature of a restart loop looks like. That runbook is a deliverable of the evaluation, not a follow-up.

Scaling — unmeasured, and measurement is a prerequisite. Supervision is cheap when idle and expensive in the wrong moments: at high concurrency, during a dependency outage, or when many workers restart simultaneously. The canary must capture restart-count distribution over time (a flat line of restarts is suspicious; a sawtooth is a restart loop), behaviour when the backing store or monitored dependency is unavailable, and whether health state accumulates unbounded in long-lived processes. Critically, test the "dependency down" case: if the supervisor restarts workers faster than the dependency can recover, it converts a degradation into a full outage.

Failure modes to design against:

• Supervisor of the supervisor gap — the supervising process dies and nothing reports it; the monitoring layer needs its own heartbeat check.
• Restart storm / thundering herd against a recovering database or queue backend.
• Double-supervision conflict with Horizon or an existing Supervisor config fighting over the same worker pool.
• Silent worker death where the app appears healthy but the queue is not draining — the exact condition this package claims to detect, so it must be tested deliberately by killing workers.
• Signal handling in containers — SIGTERM not propagated, causing hard kills and lost jobs on deploys.
• Framework lock from dependency pins blocking a Laravel major upgrade across the estate.
• Supply-chain compromise — an unmaintained package with install scripts running in production images.
• Duplicate operational cost if existing process management is not retired after adoption.

Ramp-up — low technical effort, non-trivial organisational effort. Installation and config are a day's work for a mid-level engineer; the API surface is small and conventional. The friction is elsewhere: no documentation to read, so knowledge is reverse-engineered from source and then lost when the integrator moves on. Plan for two named engineers (not one) to hold context, a written runbook as the acceptance criterion for the canary, and a handover review with the on-call rotation before any production exposure beyond the internal service.

Recommendation to the steering group: classify as watch, do not adopt at current evidence. Approve a time-boxed evaluation of roughly three to five engineering days only if a named owner can state the operational gap this closes that Supervisor/systemd, Horizon, or the platform orchestrator does not already close — and can name the metric (restart-to-recovery time, missed-cycle detection rate, supervisor config drift incidents) on which it must beat the incumbent. Absent that, close it out and redirect the effort to hardening existing process supervision.