# Veritas Kanban v6 Agent Runtime Control Plane

This document defines the supported v6.1.2 architecture for executable agent
harnesses and Buzz integration. It is the version-level composition of the
individual contract documents for
[ACP](ACP-PROVIDER-V1.md),
[harness conformance](HARNESS-CONFORMANCE-V1.md),
[filesystem sandbox backends](FILESYSTEM-SANDBOX-BACKENDS.md),
[tool control](TOOL-CONTROL-PLANE-V1.md), and
[runtime hooks](RUNTIME-HOOK-V1.md).

Documentation freshness: 2026-08-24 for Veritas Kanban 6.1.2.

## Authority Model

Veritas owns:

- task and attempt identity;
- worktree allocation and baseline;
- task envelope and launch manifest;
- sandbox, environment key names, budgets, tools, MCP, and credential
  references;
- run supervision, approvals, causal events, and terminal completion; and
- workflow, Squad Chat, roster/profile, telemetry, and audit state.

A provider owns only its documented transport, native session identifiers, and
raw execution behavior inside the compiled boundary. Buzz relay communication
owns signed delivery, not Veritas task or completion state.

## Adapter Boundaries

| Adapter                    | Harnesses                                                                 | Transport boundary                            | v6 behavior                                                                                                                       |
| -------------------------- | ------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `acp-stdio`                | Buzz Agent, Grok Build, GitHub Copilot CLI, configured generic ACP agents | JSON-RPC over bounded newline-delimited stdio | Exact initialize identity/capabilities, session lifecycle negotiation, causal updates, permission brokering, no-shell supervision |
| `codex-app-server`         | OpenAI Codex app-server 0.145.0                                           | Pinned JSON-RPC v2 stdio schemas              | Thread/turn lifecycle, streamed items, exact provider requests, remote control and unsandboxed shell method disabled              |
| `claude-code`              | Claude Code 2.1.218                                                       | Supervised bare-mode stream-json process      | System-owned arguments, static permissions, credential scrubbing, bounded JSONL, authoritative result required                    |
| `codex-cli`                | OpenAI Codex CLI                                                          | One-shot JSON process                         | Existing task transport plus v6 launch, tool, credential, event, supervisor, and completion contracts                             |
| `codex-sdk`                | `@openai/codex-sdk 0.144.3`                                               | In-process SDK stream                         | Existing SDK session transport plus the shared v6 contracts                                                                       |
| `hermes-cli`               | Hermes Agent v2026.7.7.2                                                  | One-shot process                              | No resume; unsupported conversation controls fail closed                                                                          |
| `openclaw`                 | OpenClaw v2026.6.11                                                       | Gateway `/tools/invoke`                       | Remote task session with explicit gateway policy and capability evidence                                                          |
| Buzz communication adapter | Buzz v0.4.24 relay/community                                              | Signed Nostr HTTP and WebSocket               | Channel mapping, replay, identity, definition import, and external workflow-trigger evidence only                                 |

Provider profiles select an adapter. No unknown executable, provider-less
record, or unsupported profile can route through an implicit fallback.

The server resolves these contracts through a provider adapter registry. The
registry owns the task-envelope renderer, runtime probe, event mapper, start
dispatch, and stop semantics for each exact executable provider. Attempt state
transitions remain centralized in the lifecycle coordinator, while terminal
completion and recovery consume the same persisted provider evidence.

## Run Lifecycle

```text
profile normalization
  -> provider runtime probe and support tier
  -> transactional worktree allocation
  -> immutable task envelope
  -> immutable launch manifest and credential plan
  -> supervised provider launch
  -> causal event journal
  -> exact-action approvals and mediated tools
  -> provider conversation lifecycle
  -> idempotent completion result
  -> terminal lease and worktree reconciliation
```

The probe and launch both bind provider version/build, profile configuration,
transport, capability digest, and probe revision. Drift detected between them
blocks before prompt execution.

`run-event/v1` is appended before legacy logs, traces, telemetry, and live
projection. Per-attempt cursors and deduplication support reconnect/replay.
`run-supervisor/v1` owns one active process group or remote handle and one
terminal transition. Restart recovery verifies PID/handle, worktree, task
envelope, launch manifest, and event cursor before reattaching or resuming.

`conversation-lifecycle/v1` exposes only operations supported by current
provider evidence. A generic process stdin write never stands in for a provider
follow-up protocol.

## MCP, Tools, Credentials, And Approvals

Tool-server discovery produces a version-bound inventory. A run catalog
compiles exact allow, deny, and approval decisions. Native provider injection
is allowed only when the provider transport can represent the complete policy
without exposing denied or approval-required tools.

Credential-bound tools use the system-owned `veritas-run` stdio MCP bridge.
The provider receives an opaque handle bound to the task, attempt, catalog,
launch manifest, allowed method, tool arguments digest, approval, operation,
TTL, and use count. A credential value resolves only inside the one-shot
downstream call and never enters native provider configuration or durable
evidence.

`run-approval/v1` binds a reviewer decision to the exact provider request and
action hash. Expired, stale, changed, cancelled, interrupted, duplicate, or
already-terminal requests deny safely. Mobile review is allowed only for
adapter-declared mobile-safe actions.

## Buzz Composition

Buzz has five intentionally separate seams:

1. Relay compatibility and reference-only identity configuration.
2. Signed Squad Chat root/reply delivery and replay.
3. Preview-first one-way persona/team definition import.
4. `buzz-agent` task execution through generic ACP and the `veritas-run`
   bridge.
5. Allowlisted root-message workflow triggers through the provider-neutral
   pre-external-trigger hook.

No seam creates a parallel task, workflow, credential, roster, chat, memory, or
completion authority. Relay failure cannot mark an agent run complete, and ACP
task execution cannot grant relay or community permissions.

## Certification And Runtime State

`harness-compatibility-matrix/v1` is the reviewed record for exact builds,
source caveats, fixtures, capabilities, invalidation, and limitations.
`harness-conformance-suite/v1` supplies seeded repeated deterministic
evaluations. The live support tier additionally consumes installation,
configuration, authentication posture, current runtime manifest, and platform.

Settings, API diagnostics, `vk doctor --json`, dispatch, and telemetry consume
the same record. Credential-gated live smoke supplements deterministic
evidence and never hides a failure.

## Security Boundaries

- Provider processes launch without a shell in the assigned worktree.
- User-controlled paths pass segment validation and base containment.
- Environment values are allowlisted and redacted before durable storage.
- Protocol records, stdout/stderr, queues, payloads, retries, timeouts, and
  artifacts are bounded.
- Required unsupported filesystem, network, environment, credential, MCP,
  tool, approval, lifecycle, and budget controls block before attempt mutation.
- Required network policy resolves and pins destinations, routes governed
  traffic through the run-scoped egress gateway, enforces protocol, host, port,
  HTTP method, and normalized path rules, and rejects direct or unverifiable
  bypass paths.
