Vuoro: governed work without a cockpit-shaped monolith

Overview

sprintctl started with a mundane failure: humans and agents were editing the same Markdown sprint files, and agents kept pattern-matching against the wrong piece of prose. Better prompts reduced the frequency but did not change the failure mode. The durable fix was to move live sprint state into a schema and make a CLI the write authority.

kctl followed as the read-only knowledge path. It consumes sprint history, extracts durable and coordination candidates, and puts them through explicit review and publication. It does not silently turn every session note into canon, and it never writes work back into sprintctl.

Those two tools are still useful on their own. They are no longer the whole story. The same state-ownership rule has grown into Vuoro: each repository owns one operational domain, and agent-cockpit composes their read surfaces instead of becoming a new database with opinions about all of them.

The names carry separate meanings. Vuoro is the public ecosystem label. agentops remains the repository for shared contracts, cross-repository plans, and the UI. agent-cockpit remains that UI. The public rename avoids confusing the ecosystem with AgentOps.ai without churning implementation names.

Interactive system map

Explore the interactive Vuoro system map to follow the wider lifecycle across sprintctl, kctl, actionq, actionq-dispatch, auditctl, deployment, and agent-cockpit. It focuses on state ownership and the handoffs between tools rather than treating the cockpit as the system itself.

Architecture and communication paths

Three modes describe how a request travels, not three competing sources of truth. In local mode, an agent calls the owning CLI and keeps SQLite state, claim recovery material, Git worktrees, and filesystem effects on its machine. In remote mode, that same domain tool uses its shared PostgreSQL authority. In served mode, the transport-only Vuoro client talks to Vuoro service, which authenticates the caller, checks compatibility, and invokes a pinned adapter for the owning tool.

The modes compose. A served request can reach a remote authority while the worker that receives it still performs bounded Git and filesystem work locally. The cockpit reads projections and submits dispatch through the documented API; it does not gain a raw write path into the domain databases. None of these arrows promises a distributed transaction. Receipts, append-only events, idempotency, and explicit recovery carry work across the boundaries.

System shape

sprintctl owns sprints, work items, dependencies, events, claims, and handoffs. It runs against repo-local SQLite or a shared PostgreSQL backend, and a declared backend mismatch fails rather than quietly opening a different source of truth. Claim ID and token prove possession of an active claim; resume and handoff commands turn live state into deterministic context for a new operator or agent session. PostgreSQL now retains expired claim rows and exposes a lineage lease_epoch. The epoch is historical structure, not downstream fencing.

kctl reads sprintctl events and owns the extraction, review, publication, and rendering of knowledge artifacts. The relationship is deliberately one-way. Rendered Markdown remains useful for review and Git history, but it is a projection, not the live control plane.

The sibling tools fill different gaps:

• actionq owns PostgreSQL-backed action and session lifecycles with a strict queue contract and append-only events.
• actionq-dispatch owns the bounded one-action coordinator: worktrees, worker invocation, path ACLs, pre- and post-gates, and result recording through the owning CLIs.
• auditctl owns a repo-local audit index plus durable daily NDJSON artifacts that can be rebuilt and read independently.
• agentops owns reusable dispatch skills and schemas, cross-repository plans, and the agent-cockpit application. The cockpit reads sprint state, queue sessions, audit artifacts, and cost signals; its writes stay mediated by the owning domain contracts rather than direct database mutation.

The rule across the repositories is simple: state ownership decides repository ownership. It is also the main defense against building a cockpit-shaped monolith.

One work item, including failure

Here is the end-to-end property the system is designed to demonstrate:

1. An operator creates a work item through sprintctl. Sprintctl records the item and event history.
2. An agent starts a claim. Its claim ID and secret token—not the actor name, branch, or hostname—prove the current ownership incarnation.
3. Dispatch submits an action through actionq. Actionq-dispatch creates a bounded worktree, applies path and command policy, invokes one worker, and runs its gates.
4. If the worker fails or returns an invalid result, the result is recorded as failed or rejected. It is not published and does not close the work item.
5. The same owner can resume with its private recovery record. A new owner needs an explicit handoff or recovery that rotates proof, so stale proof cannot settle the item.
6. Once a valid result clears independent verification, the owning CLI records completion and releases the claim. Auditctl indexes portable evidence, and the cockpit projects the sprint, claim, dispatch, and audit outcome.

This is an acceptance walkthrough, not a claim that the six steps form one atomic transaction. The next proof is to automate it with injected failure, stale-proof rejection, recovery without duplicate settlement, and comparison of the audit and cockpit projections with the owning records.

Current state

The tools are public and used across active repositories. sprintctl supports both local and remote modes, recoverable claims, provenance links, and a single-command resume bundle. kctl has a functioning two-stream extraction and review pipeline. actionq supplies the queue and session read contracts, while actionq-dispatch supplies the one-shot coordinator and auditctl emits portable audit shards.

The agent-cockpit is live and can show repository and sprint state, claims, session and dispatch lifecycles, audit outcomes, and bounded cost or model headroom signals. Its dispatch surface forwards work through actionq. sprintctl state and workspace artifacts remain separate service contracts rather than tables the UI is free to rewrite.

The screenshot is the current sprint overview: backlog and active work on the left, claim-aware work detail in the middle, and dispatch activity in the operator surface. It is a composed view of owning systems rather than a new state authority.

This is a different system from the original pair of pipx-installed SQLite tools. Local-first operation is still the default for a small repository, but PostgreSQL and agent-cockpit now provide a shared view when work crosses hosts or needs an operator surface.

Open edges

The substrate has enough parts that it must continually justify them. A tool designed to remove coordination ambiguity can recreate it through version drift, overlapping commands, or unclear recovery rules between repositories. Interface contracts and end-to-end verification matter more now than another feature in any one CLI.

kctl and auditctl are also less exercised than sprintctl and agent-cockpit. Their clean ownership boundaries are promising, but durable extraction and recovery need more operational mileage before they should be treated as settled.

The agent-cockpit write surface should stay narrow. Dispatch and explicit sprint operations are useful; turning the UI into a privileged backdoor around claim, queue, or audit rules would recreate the original Markdown problem with better CSS.