Boost Pipeline Laravel Package

Technical Evaluation

Architecture fit

• boost-pipeline is a Laravel package (service provider + pipeline:history artisan command + a web page) that orchestrates shell steps for an agent-driven workflow. It fits teams already on Laravel who want step execution, run state, and history without standing up a separate orchestrator.
• v0.22.0 pushes it from "step runner" toward "small scheduler": Shell::exclusive('name', $capacity) adds machine-wide concurrency caps, and Shell::onAbort('<cmd>') adds compensating cleanup. That is the right direction for long-running, multi-step agent work, but it means the package now owns resource contention semantics we previously owned ourselves.
• Observability improved materially: duration_ms and slot_wait_ms on step results, plus waiting_for_slot in next_step, give us the raw data for queue-latency and capacity reporting.

Integration feasibility

• Low-friction install: composer package, auto-discovery, one command to inspect history. No infrastructure dependency is introduced by this release beyond whatever backs exclusive() (see key questions — this is the single largest unknown).
• All new surface (onAbort, exclusive) is opt-in; teams that only consume next_step and step results can adopt v0.22.0 without touching their configs.

Technical risk

• Breaking behaviour (high): "A timeout or a stopped run now ends every process the step started, not only its shell." Any pipeline that intentionally leaves a background process alive across steps (dev server, queue worker, browser/session daemon, watcher) will silently lose it at the first timeout. This is the item most likely to cause an incident-shaped regression on upgrade.
• Contract change (medium): next_step can now return waiting_for_slot. Consumers with a closed enum, strict validation, or match on status will throw or stall. Wall-clock timeout expectations also shift, because slot wait no longer counts toward the timeout — a step can queue longer than the timeout value suggests.
• New hard config constraint (medium): exclusive() requires withResponseWindow() and a config without one is refused at load. Failure is loud and early (good), but it couples two features and blocks adoption of slots in non-interactive pipelines.
• New refusal path (medium): open_run now refuses once vendor/composer/installed.php changes, asking for a reconnect. Correct safety posture (dependency drift invalidates an in-flight run), but it adds a failure mode the calling agent must detect and handle rather than treat as generic error.
• Additive, low risk: duration_ms / slot_wait_ms fields, abandoned status in pipeline:history and the page.

Key questions

• What backs machine-wide exclusivity — filesystem lock or cache lock? If filesystem, the cap is per host and our multi-runner/CI topology silently multiplies it. If cache, which drivers are supported and what happens on Redis/DB outage?
• Is a slot released if the process is SIGKILLed, or only on graceful abort/onAbort? What is the recovery behaviour for an orphaned slot?
• What is the exact exit code / error shape for the open_run "reconnect required" refusal, so the agent harness can distinguish it from a crash?
• Does the process-group kill cover detached/setsid children and grandchildren, and is there an opt-out for deliberately daemonized processes?
• Minimum PHP/Laravel versions, and does next_step's status set have a documented, versioned contract?

Integration Approach

Stack fit

• Natural fit for an existing Laravel service already hosting the agent tooling; the artisan command and web page give operators a zero-build dashboard.
• Confirm the runtime hosts match where the package assumes steps execute (same machine, same user, writable lock path, available proc/signal capabilities).

Migration path

• Pin exact versions, not ranges: this is a 0.x package, and v0.22.0 itself shows minor bumps can carry breaking behaviour changes. Upgrade v0.21.0 → v0.22.0 deliberately per environment.
• Pre-upgrade audit in three passes: (1) grep pipelines for steps that leave background processes running and expect them to survive; (2) grep the agent/client code for hard-coded step status values; (3) grep configs for exclusive + missing withResponseWindow (only relevant if slots are already modelled).
• No data migration implied; abandoned is a derived display/state value, but verify it does not rewrite persisted run rows in a way our reporting queries assume.

Compatibility

• New result fields are additive — downstream consumers tolerate them unless they do strict schema equality or golden-file diffs on step results.
• Status enumeration is now wider (waiting_for_slot, plus abandoned in history). Treat the status set as a versioned enum in our own code before adopting.
• The composer-drift refusal is a behavioural contract with the agent harness; version the harness and the package together.

Sequencing

1. Read the changelog and confirm the exclusivity backing store and kill semantics with the maintainer.
2. Land the harness changes first: unknown-status tolerance, waiting_for_slot handling, and explicit reconnect handling on open_run refusal.
3. Upgrade in dev/CI with a canary pipeline that exercises timeouts and background processes.
4. Adopt onAbort cleanup hooks before adopting exclusive() — cleanup is the prerequisite for safe contention.
5. Pilot exclusive() on a single non-critical named resource at capacity 1, measure slot_wait_ms, then widen.
6. Roll to the operator-facing pipeline:history page last.

Operational Impact

Maintenance

• Pre-1.0 churn is the cost of adoption: budget a review of every 0.x minor, not just majors. The verified-sha marker in release notes is a useful supply-chain signal — keep it in the upgrade checklist.
• Two config surfaces now need drift review: response-window settings and exclusivity capacities. Add both to the config-as-code review.

Support

• New operator questions will cluster on three things: "why is my step waiting", "why did my background server die", and "why does it want me to reconnect". Each needs a runbook entry and a log line that names the cause.
• Expose slot_wait_ms and duration_ms in whatever dashboard the team already watches; without it, contention complaints are unanswerable.

Scaling

• Machine-scoped capacity is a per-host limit. If we scale out runners, effective global concurrency is capacity × hosts — either accept that or pick a shared lock backend. Decide this before the first horizontal scale-out, not after.
• Because slot wait is excluded from the timeout, a saturated resource produces unbounded queue latency rather than a timeout error. Set an alert on slot_wait_ms p95, not just on failures.

Failure modes

• Silent loss of a daemonized process after a timeout — most likely regression; mitigate with onAbort and an explicit post-timeout assertion in the pipeline.
• Orphaned slot if a runner dies hard, blocking a resource until manual intervention — verify release-on-crash behaviour.
• Reconnect loop if composer install runs frequently in the same workspace, e.g. mid-run dependency refresh by another agent.
• Abandoned run accumulation — harmless for correctness, but it will inflate the history page and any run-count reporting.
• Cleanup-command failure: onAbort running a command that itself fails or hangs needs a bounded timeout of its own, or abort handling becomes a second failure.

Ramp-up

• Low for existing users: nothing is mandatory in v0.22.0 except awareness of the process-kill change and the new status value.
• Medium for slot adoption: two coupled concepts (exclusive slots + response windows) must be understood together, and capacity sizing requires a baseline of slot_wait_ms that we do not yet have. Plan one iteration of measurement before setting capacities.