feat: UNIX socket control plane for porter daemon

[dougEfresh]

Summary

Adds a REST API over a UNIX domain socket for runtime management of the porter daemon: scheduled task CRUD, daemon health, and worker pool observability.

API endpoints

GET  /api/health
GET  /api/scheduled-tasks
GET  /api/scheduled-tasks/:id
POST /api/scheduled-tasks
DELETE /api/scheduled-tasks/:id
POST /api/scheduled-tasks/:id/pause
POST /api/scheduled-tasks/:id/resume
POST /api/scheduled-tasks/:id/fire
GET  /api/scheduled-tasks/:id/runs
GET  /api/workers

CLI

porter task list|get|create|delete|pause|resume|fire|runs
porter status
porter help

Socket lifecycle

Systemd manages the socket directory via RuntimeDirectory=porter-%i. Each template
instance gets its own isolated directory:

porter@projects-me-pi-porter  →  /run/user/1000/porter-projects-me-pi-porter/porter.sock
porter-dev                    →  /run/user/1000/porter-dev/porter.sock

The daemon binds the socket directly with Bun.serve({ unix }).

Why not systemd socket activation?

Bun.serve({ fd }) was proposed in oven-sh/bun#2852
but the PR was closed without merging. Connections open successfully on the
passed fd but Bun never dispatches to the HTTP handler.

Design decisions

• No edit/update endpoint: delete + recreate for changes, no nextRun ambiguity
• Hooks stay strings: KISS, no arrays or env maps
• Session auto-create: POST creates session rows so FK constraints pass
• PORTER_SOCKET env var: set by the systemd service unit, consumed by both daemon and CLI
• Limit clamping: ?limit on runs endpoint capped at 500, rejects negatives

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dba3cefa-3f0d-41f4-8142-f7d13462c9e5

📥 Commits

Reviewing files that changed from the base of the PR and between c8ccdd1 and 0328552.

📒 Files selected for processing (16)

• docs/config.md
• docs/control-plane.md
• resources/systemd/porter-dev.service
• resources/systemd/porter-dev.socket
• resources/systemd/porter@.service
• resources/systemd/porter@.socket
• runtime/src/agent/pi-runner.ts
• runtime/src/agent/worker-pool.ts
• runtime/src/cli.ts
• runtime/src/control-server.ts
• runtime/src/daemon.ts
• runtime/src/db/scheduled-task-store.ts
• runtime/src/index.ts
• runtime/src/scheduler/index.ts
• runtime/src/scheduler/registry.ts
• runtime/src/scheduler/types.ts

---

📝 Walkthrough

Walkthrough

This PR introduces a control plane REST API for Porter's daemon, accessible over UNIX domain sockets. A new ControlServer class handles health checks, scheduled task CRUD and lifecycle operations (pause/resume/fire), task run history, and worker observability. The daemon now owns and manages this server instance alongside its scheduler. A new CLI module communicates with the daemon via HTTP-over-UNIX-socket fetch, supporting task management commands and daemon status checks. Systemd socket and service units manage socket creation, permissions, and cleanup across development and production deployments. Documentation covers API endpoints, CLI usage, and socket configuration.

✨ Finishing Touches

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch control-plane

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}