buildwithyj/quota-cistern

Purpose and Executables

quota-cistern is a Rust workspace for unattended, budget-bounded coding-agent execution. It queues delegated tasks, runs them in isolated Git branches/worktrees, enforces time and agent-usage limits, and leaves results for human review. User entry points are the cistern CLI (crates/cistern/src/main.rs, crates/cistern/src/cli.rs) and the long-running local daemon cisternd (crates/cisternd/src/main.rs).

Client/Daemon Boundary

The CLI owns command parsing, output formatting, local configuration access, and daemon session interaction (crates/cistern/src/task.rs, crates/cistern/src/session.rs, crates/cistern/src/config.rs). It maps commands such as task registration, run, interruption, review, diff, and apply onto daemon-facing contracts. Shared request/value definitions live in crates/cistern-contract/src/lib.rs, with address and exchange/code protocol pieces in crates/cistern-contract/src/address.rs and crates/cistern-contract/src/exchange.rs.

Hexagonal Daemon Core

cisternd separates policy from operating-system and vendor details. Domain state models configuration, tasks, sessions, consumption, and supervision in crates/cisternd/src/core/domain/task.rs, crates/cisternd/src/core/domain/session.rs, and crates/cisternd/src/core/domain/supervision.rs. Inbound and outbound interfaces define the core’s callable use cases and required infrastructure capabilities under crates/cisternd/src/core/port/inbound/ and crates/cisternd/src/core/port/outbound/.

Execution and Budget Control

Execution orchestration is centered on crates/cisternd/src/core/service/execution.rs. A session receives a usage and time budget, starts eligible backlog tasks, observes actual per-task consumption, and admits further work only when remaining budget permits. Supervision tracks running work and termination reasons; interruption or exhausted budget stops active tasks while retaining their worktree/branch state. Backlog and configuration policies are separate services in crates/cisternd/src/core/service/backlog.rs and crates/cisternd/src/core/service/configuration.rs.

Adapters and Persistence/Process Effects

Inbound adapters expose backlog, configuration, and execution operations to the local client protocol (crates/cisternd/src/adapter/inbound/backlog.rs, crates/cisternd/src/adapter/inbound/execution.rs). Outbound adapters implement core ports against local machine resources: repository and worktree operations, session/backlog storage, clock/limits, and agent invocation (crates/cisternd/src/adapter/outbound/repository.rs, crates/cisternd/src/adapter/outbound/worktree.rs, crates/cisternd/src/adapter/outbound/agent.rs). This is the critical boundary that creates immutable per-task result branches and launches external agent processes.

Agent and Git Workflow

Version 0.1.0 targets the Claude vendor on one machine. The Claude adapter carries prompt/response and limit-related assets (crates/cisternd/src/adapter/outbound/claude.json, crates/cisternd/src/adapter/outbound/claude-goal.txt, crates/cisternd/src/adapter/outbound/claude-answer.json). Each assigned task gets a dedicated worktree and result branch; dependent tasks can use a predecessor branch as a base. Result branches are not subsequently modified, merged, or pushed by the system; apply/discard are review dispositions performed through the CLI.

Runtime Lifecycle

The daemon platform layer owns serving, signal handling, and background work coordination (crates/cisternd/src/platform/serve.rs, crates/cisternd/src/platform/signal.rs, crates/cisternd/src/platform/work.rs). The system is single-host and permits one active session at a time. Its material external dependencies are the local Git repository/worktree environment and the Claude agent runtime; no network service or web application is indicated.