CLI Kernel Steward Subsystem and Runway Guide
1. Overview and Operational Philosophy
The zqk kernel steward subsystem acts as the autonomous maintenance heartbeat and runway monitoring watchdog for the ZQK Knowledge Kernel. It guarantees two essential invariants:
- Deterministic Resource and Storage Hygiene: Continually reaps stale lock files, flushes orphaned temporary files, and performs write-ahead log (WAL) compaction. This prevents multi-agent concurrency leaks and unbounded storage growth across long-running autonomous execution sessions.
- Roadmap Runway Depletion Sensing: Measures the volume of shovel-ready Priority Plans and Backlog Items currently in the execution pipeline. When shovel-ready runway drops below target safety buffers (e.g. fewer than 2 shovel-ready plans), the steward generates deterministic ambient signals (
SIG-RUNWAY-REPLENISHMENT) that inform autonomous Technical Program Management (TPM) agents to replenish the queue before worker swarms face starvation.
flowchart TD
subgraph Steward Loop ["Kernel Steward Loop (zqk kernel steward daemon / sweep)"]
direction TB
Boot["Steward Invocation"] --> Hygiene["Resource Hygiene Check"]
Hygiene --> Reaping["Reap Stale Locks & Temp Files"]
Reaping --> WAL["Compact WAL"]
WAL --> Runway["Evaluate Roadmap Runway"]
Runway --> CheckBuffer{"Runway Buffer < Target?"}
CheckBuffer -- "Yes (Starvation Risk)" --> Sig["Generate Ambient Replenishment Signals"]
CheckBuffer -- "No" --> Record["Record Sweep Telemetry"]
Sig --> Record
end
2. Command Architecture and Taxonomy
The steward CLI surface is nested cleanly under zqk kernel steward:
| Command | Usage | Description |
|---|---|---|
zqk kernel steward sweep |
One-shot execution | Runs an immediate single pass of storage hygiene, reaps stale locks/temps, compacts the WAL, evaluates runway, and outputs a formatted SweepResult. |
zqk kernel steward daemon |
Long-running daemon | Runs in the background (or foreground with --interval) continuously executing periodic hygiene and runway monitoring cycles at configured intervals (default: 30s). Protected by singleton PID locks. |
Command Flags
--interval <seconds>(daemon only): Polling interval in seconds (default: 30). Non-positive or omitted values fall back safely to 30 seconds.- Standard Global Flags:
--format (json|yaml|table)and--context (ai-agent|human|debug).
3. Storage and Process Hygiene
The steward coordinates with the underlying pkg/resourcehygiene and pkg/storage components to ensure spotless state across execution:
- Stale Lock Reaping: Discovers and unlinks abandoned
.lockfiles older thanresourcehygiene.DefaultLockStaleAge(e.g..cas_sweep.lock,session.lock). - Orphaned Temp File Cleanup: Identifies durable and transient
.tmpfiles in.zqk/cache/or.zqk/tmp/older than 30 minutes and purges them. - WAL Compaction: Invokes
storage.CompactWAL(projectRoot)to checkpoint append-only write-ahead logs into durable CAS storage while verifying zero transaction loss. - Test Isolation Discipline: In test environments, tests executing
steward sweeporsteward daemonMUST register teardown viastorage.RunProjectTestTeardown(storage.TempProjectTeardown(testRoot, nil))to ensure open SQLite and WAL descriptors are flushed before temporary directory removal.
4. Runway Monitoring and Starvation Risk Signals
The steward interfaces with pkg/kernel/steward/monitor.go to compute runway metrics:
- Shovel-Ready Criteria: A Priority Plan is considered shovel-ready when:
1. Its lifecycle status is either
plannedoractive. 2. It has one or more linked Backlog Items (backlog_item_refs). - Target Buffer: The default safety buffer is
MinimumShovelReadyRunway = 2. - Ambient Signals: If the shovel-ready buffer falls below target, the steward emits a high-priority ambient signal:
yaml signalid: SIG-RUNWAY-1792076808375819000 priority: P4-RUNWAY-REPLENISHMENT message: Roadmap runway lead (0 plans) is below target buffer (2). Autonomous steward replenishing queue. timestamp: 2026-10-15T08:06:48.375821-07:00Autonomous agents consumingzqk workflow whats-nextinspect this signal to proactively groom the next batch of priority plans without human intervention.
5. Verification and Done-Gates
Verification for the kernel steward subsystem is tracked under TST-001 and satisfies the Three-Fold Proof:
- Static Floor Invariant (
CRIT-001): Statement test coverage incmd/zqk/kernelmaintains \(\ge 90.0\%\) with no unhandled branch paths. - Operational Dynamic Proof (
CRIT-001):TestStewardDaemon_TickerIterationandTestKernelStewardSweepExecutionexecute cleanly in isolated temp roots and verify sweep telemetry collection. - Negative Boundary & Hygiene Proof (
CRIT-001): Negative flag values (--interval -10), missing interval flag fallback, and singleton daemon duplicate prevention execute deterministically without panics or leaks.