The repository contains the executable, file-backed implementation shipped in
the published v0.3.0 installation control-plane release. The protocol and reference
CLI version are both 0.3.0; release gates are closed while runtime and
production claims remain evidence-scoped.
The implementation is deliberately inspectable: the control
root contains canonical JSON projections and append-only JSONL ledgers that can
be replayed after a process restart.
bin/valp install init --workspace /path/to/workspace
bin/valp leader candidates --workspace /path/to/workspace
bin/valp leader select <observed-principal-id> --workspace /path/to/workspace
bin/valp leader start --workspace /path/to/workspace
bin/valp leader open --workspace /path/to/another/caller
bin/valp leader show --workspace /path/to/workspace
bin/valp status --workspace /path/to/workspace
The first two commands never select a Leader. leader select records explicit
user intent but leaves active_leader unset and epoch 0 fenced to bootstrap.
leader start creates a fresh installation-owned runtime attachment from the
selected passport’s adapter and launch argv, verifies the exact attachment and
health, then activates epoch 1. It does not adopt the current CLI, a focused
pane, or a user-opened session. Once active, leader start is idempotent with
leader open: it focuses the current attachment from any caller workspace and
reprovisions it only when the old attachment is gone. The Leader authority is
the installation and selected principal, not the pane or window. The control
root defaults to <workspace>/.valp when present, otherwise an initialized
$VALP_CONTROL_ROOT or ~/.valp root is reused; pass --root for an explicit
installation.
Use leader restart for an explicitly fenced fresh attachment of the same
principal and leader rotate <observed-principal-id> for a different
principal. Every Agent later created or assigned
by that Leader is a task/project-owned Worker, including the same Agent product.
If provisioning or binding validation fails after a start, restart, or rotation
is prepared, the core writes leader_session_start_failed, moves the
installation to blocked, and leaves the active epoch unchanged. A failed
receipt does not contain a fabricated binding digest or runtime session id.
One blocked first start can be recovered only with an exact session id and explicit approval:
bin/valp leader recover-start --workspace /path/to/workspace \
--session <exact-runtime-session-id> --approve
The command is legal only at epoch 0 when no Leader binding exists and the
unchanged selection, passport, blocking event, and latest failed start
receipt all match epoch 1 and generation 1. The reference HERDR adapter
addresses only the named session and uses bounded read-only identity, workspace,
process, argv, non-focus, cwd, and health checks. It does not create, move,
focus, close, or replace runtime state. Success preserves the failed receipt
and records its digest plus the recovery-approval event in the active binding
and normal provisioned/activated receipts.
The implementation writes installation metadata, protocol manifest, state, exact Leader session binding and immutable binding history, Leader session receipts, capability observations and registry, message/event/failure ledgers, evidence/claim/review ledgers, and migration receipts. State-changing commands use expected-revision compare-and-swap, leader-epoch fencing, idempotency keys, append-only event digests, and a cross-process control lock. A replay or projection digest mismatch fails closed as a registry consistency error.
Task projections are stored below tasks/<task-id>/task-state.json. The legal
task reducer prevents runtime completed from jumping directly to done; the
Done transition requires receipts, expected evidence, verification, review,
approval, final synthesis, and audit gates to be explicitly true.
Observations are intentionally layered. A provider declaration does not become local presence, live callability, or task verification automatically.
bin/valp capabilities reconcile \
--workspace /path/to/workspace \
--observations examples/v0.3-installation/observations.json
bin/valp hello --workspace /path/to/workspace --nonce YWJjMTIz
bin/valp plugin validate path/to/plugin/manifest.json
bin/valp protocol migrate --workspace /path/to/workspace --to 0.3.0 --dry-run
bin/valp protocol migrate --workspace /path/to/workspace \
--plan /path/to/approved-plan.json --apply --approve
bin/valp state replay --root ~/.valp --check
bin/valp conformance --profile core-writer
bin/valp adapter process run TASK-001 --workspace /path/to/workspace \
--command "python worker.py" --approve
Migration without --apply, or with explicit --dry-run, creates a plan with
no activation. Applying the control-root plan or an exact --plan <file>
requires --apply --approve. A 0.3.0-draft installation upgrade inventories and
checkpoints the complete control root under migration-snapshots/, excluding
only lock and migration-journal outputs. It keeps the active Leader identity and
epoch, updates the active read/write protocol to 0.3.0, and leaves terminal
draft Tasks as immutable legacy-read-only history. New writes to those Tasks are
rejected until a separately specified Task projection migration exists. The
plan binds state and registry revisions, Leader epoch, affected Tasks/plugins,
rollback strategy, and validation cases. Exact interrupted checkpoints may be
resumed; conflicting targets fail closed. A legacy 0.2.0 workspace import
preserves its original bytes under legacy/. Both paths recheck source digests
and record a migration receipt. Plugins cannot write authoritative VALP ledgers
directly.
Control transitions use an atomic ledger replacement and a digest-bound transition journal. A retry completes the same message, event, state, and installation update after an interrupted commit instead of treating a partial message append as success.
The 0.3.0 core does not make HERDR mandatory. The local-process adapter is a
real non-HERDR worker adapter for the declared host/profile, but it is not an
AI provider or hosted agent service. Runtime adapters still own session
control, provider calls, liveness, and output collection. Release status does
not claim every independently operated agent, hosted Full Mode path, platform,
or production deployment has been proven.