Mesh Seat Worker & Supervisor Daemon (`pkg/seatworker`)

pkg/seatworker provides OS supervisor installation and lifecycle management for persistent autonomous agent worker processes (zqk agent seat-worker).

1. What is a Seat Worker?

A Seat Worker is a dedicated, headless autonomous process bound to a specific seated persona defined in .zqk/agent-runtime/peer_seats.json (or peer_seats.json).

While interactive agents operate within an IDE or single CLI session, a Seat Worker runs continuously in the background under the host OS supervisor:

macOS: launchd User Agent (~/Library/LaunchAgents/com.zqk.mesh.seat-worker.<seat>.plist)
Linux: systemd User Service (~/.config/systemd/user/com.zqk.mesh.seat-worker.<seat>.service)

The worker daemon periodically polls its seat's inbox (poll_seconds, default 30s), dequeues steers and task assignments (ATK-*), prepares kernel context, executes the cognitive reasoning and action loop, and returns status updates to the Knowledge Kernel.

2. When Should You Use Them?

Continuous 24/7 Autonomous Loops: When you want agents to autonomously make progress on backlog items, perform continuous verification, or monitor repository health without requiring an open IDE terminal.
Specialized Agent Swarms: When dedicating specific hardware or processes to specialized roles (e.g., dedicated TPM orchestrator, Code Craftsman, QA Verification, or Security Auditor).
Sovereign Mesh Compute Clusters: In multi-node federated mesh environments where remote machines advertise compute capacity and execute delegated workloads.

3. Installation & CLI Usage

Install seat worker daemons natively using the CLI:

# Install supervisor units for all agentapi/mcp seats in peer_seats.json
zqk agent install-seat-workers

# Install a specific seat worker with a 15-second polling interval
zqk agent install-seat-workers --seat craftsman --poll-seconds 15

# Enable autonomous execution of code/shell mutations
zqk agent install-seat-workers --seat craftsman --execute-non-comms

# Dry-run / test without registering with launchctl/systemctl
zqk agent install-seat-workers --write-only

To run a seat worker directly in the foreground for debugging:

zqk agent seat-worker --agent-id craftsman --persona-ref community-code-craftsman --poll-seconds 10

4. Architecture & Supervision Flow

  ┌─────────────────────────────────────────────────────────────┐
  │ Host Supervisor (launchd / systemd)                         │
  │ com.zqk.mesh.seat-worker.<seat_id>                          │
  └───────────────┬─────────────────────────────────────────────┘
                  │ Spawns & Keeps Alive
                  ▼
  ┌─────────────────────────────────────────────────────────────┐
  │ zqk agent seat-worker                                       │
  │   - Agent ID: <seat_id>                                     │
  │   - Persona:  <persona_ref>                                 │
  │   - Interval: <poll_seconds>                                │
  └───────┬───────────────────────────────▲─────────────────────┘
          │ Polls Inbox / Steer           │ Emits Status / ACKs
          ▼                               │
  ┌────────────────────────┐    ┌─────────┴─────────────┐
  │ Agent Feed (Inbox)     │    │ Knowledge Kernel      │
  │ .zqk/agent-runtime/    │    │ (Tasks, Criteria, CAS)│
  └────────────────────────┘    └───────────────────────┘

5. Limitations & Operational Considerations

Root Kernel Binding: Seat workers must be installed on the canonical project root containing the .zqk/ kernel directory. Installing on isolated git worktrees is explicitly rejected (cannot install seat workers on worktree root).
Execution Permissions (--execute-non-comms): - By default, seat workers only ingest correspondence and claim work. - When --execute-non-comms is enabled, the worker executes live bash commands, file modifications, and git operations. Ensure proper git credentials and branch protections are configured.
Cognitive Timeout & Retries: - loadAttempts (3 attempts): Caps retries per task to prevent infinite loops on failing tasks.
Log Inspection: Supervisor stdout and stderr streams are isolated per seat under: .zqk/logs/mesh/seat-worker-<seat_id>.stdout.log .zqk/logs/mesh/seat-worker-<seat_id>.stderr.log