Accretion
Observable, deterministic orchestration for local AI coding agents
Accretion supervises Codex, Claude Code, and opencode through one provider-neutral control
plane, with deterministic planning, bounded verifier-gated feedback loops,
isolated workspaces, and a durable normalized execution trace.
Author: resume.draveniq.dev ·
Documentation · Frontend guide ·
Developer guide · Showcase ·
Research results · Project status ·
v0.4 release notes
[!IMPORTANT]
The v0.4.0 release makes node configuration routing evidence-aware: every
AGENT, TOOL and VERIFIER node is routed over the 6-tuple (runtime, model,
tools, skills, verifier, environment) by a receipt-first deterministic router,
learned from verified experience through an offline ranker, a project adapter
and a shadow stage evaluated by branched live rollouts, explored only by a
guarded bandit under six circuit breakers and a cost ledger, and promoted
through an append-only activation ledger behind a calibrated safe-improvement
gate. The Experiment Studio shows each decision; the research instrument runs
a pre-registered, locked benchmark. Every v0.4 feature is off by default
(ACCRETION_ENABLE_NODE_ROUTING). The release notes
and release audit record the gate evidence and
the disclosed limitations; every acceptance criterion is claimed
(in scope: 167 proven: 159 unmet MUST: 0), and axe-core reports zero
violations across all eighteen routes.
The preceding v0.2.0 release added opt-in P5 validated dynamic workflows, P6
bounded candidate search and P7 verified-experience replay; its
frozen baseline and
audit remain the immutable record, as does the
v0.1.0 static control.
The inherited v0.1 foundation includes P0 runtime feasibility, P1
deterministic planning, P2 verifier-gated feedback loops, P3 static graph
execution, and the P4 governed harness/operator release gate. Its five validated
templates can execute:
direct-v1, feedback-loop-v1, fixed-graph-v1 (with human approval gates),
hybrid-rd-v1, and the bounded safe-unknown-v1 fallback.
Start here
Accretion is for developers and operators who want to run local AI coding agents
without making a provider session the authority for permissions, acceptance, or
recovery. The repository contains the FastAPI control plane, React operator UI,
PostgreSQL schema, runtime adapters, deterministic verifiers, frozen research
fixtures, examples, and operational documentation in one workspace.
This is a local orchestration and research system, not an unrestricted deployment
agent. It deliberately fails closed when evidence, authority, budgets, or recovery
state are uncertain.
Why Accretion
AI coding runtimes expose different protocols, session models, event formats,
and failure behavior. Accretion puts a durable control plane around them so an
operator can answer five questions before and during every run:
- What will execute? Typed task contracts produce an inspectable profile and
a versioned strategy decision.
- Why was it selected? Every score, unknown feature, matched rule, alternative,
and override is visible and persisted.
- Where can it make changes? Each mutable run receives an isolated disposable
Git worktree with explicit capability constraints.
- What actually happened? Provider activity becomes a normalized,
append-only event stream that survives UI reconnects and backend restarts.
- Did the result really pass? Independent deterministic verifiers inspect an
immutable candidate snapshot; provider-reported completion is never acceptance.
Capabilities
| Area | Included today |
|---|
| Runtime control | Structured Codex App Server, Claude Code, and opencode server adapters, plus a deterministic fake runtime |
| Task planning | Versioned prompt/context contracts, deterministic profiling, static strategy selection, and explicit unknown handling |
| Feedback execution | Bounded multi-turn loops, structured repair directives, one reusable provider session, and durable pause/resume/cancel controls |
| Independent acceptance | Output-contract, Git-diff, trajectory-policy, and bounded command verifiers with fail-closed policy evaluation |
| Safety | Hard wall-time, turn, tool-call, and iteration ceilings; high-risk approval gates; audited overrides; and side-effect idempotency |
| Isolation | One Git worktree lease per mutable run with captured diff artifacts |
| Recovery | Atomic iteration commits, optimistic revisions, session continuation, and restart reconciliation without replaying committed work |
| Observability | Durable PostgreSQL state, immutable verifier evidence, monotonic normalized events, resumable SSE, runtime health, and usage pressure |
| Operator frontend | Seventeen implemented routes for dashboard, task/planning, live graph and controls, runtime monitor, history/audit, approvals, capability registries, ACR-ARCH, P5–P7 research, and the v0.3 administration pages (Plugins, Connections, MCP Servers, Capability Inspector, Identity) |
| Governed capabilities | Immutable capability/skill/plugin/policy registries, task-scoped MCP exposure, approval-bound idempotent side effects, and executor-boundary credential injection |
| Architecture benchmark | Frozen 30-task ACR-ARCH corpus, 68 balanced replay scenarios, raw dimensions, utility/regret, filterable operator UI, and opt-in live provider calibration |
| Dynamic workflow research | Frozen 12-task P5 static-versus-dynamic suite with cohort uplift, architecture regret, structural variation, invalid-proposal fallback, and a release-gate UI |
| Candidate search | Opt-in P6 best-of-N, hypothesis, cross-provider, and generator-reviewer execution with shared budgets, isolated trajectories, independent ranking, and crash-safe promotion |
| Verified experience | Opt-in P7 immutable terminal evidence, repository-scoped deterministic retrieval, compatibility and transfer-risk scoring, explicit negative knowledge, fresh-control trajectory replay, repeated revalidation, and a frozen transfer benchmark |
Frontend status
Yes—the frontend is implemented for the P0–P7 scope plus the v0.3 M6
administration pages and the v0.4 router administration page, eighteen routes
in all.
It is not a mock dashboard: it calls the generated API contract, starts from
authoritative snapshots, follows active runs through resumable server-sent
events, and exposes the decision and verifier evidence needed to explain a run.
| Frontend gate | Current evidence |
|---|
| User-facing scope | Dashboard, New Task/Planning, Live Run, Runtimes, History, Approvals, Capabilities, ACR-ARCH, P5 Dynamic, P6 Search, P7 Experience, and the v0.3 administration pages (Plugins, Connections, MCP Servers, Capability Inspector, Identity) |
| API safety | Generated OpenAPI TypeScript schema; backend remains the authority for policy and transitions |
| Live behavior | Snapshot-first state, monotonic SSE, reconnect and sequence-gap recovery |
| Verification | The component test suite, ESLint, TypeScript, OpenAPI idempotence, and production build all pass; axe-core 4.13.0 reports zero violations across all eighteen routes (the v0.2 exception in issue #52 was discharged in v0.3.0) — see browser and accessibility evidence |
See the operator frontend guide for every route, the
operator journey, data flow, P5–P7 coverage, source map, and frontend commands.
Architecture
P2 feedback-loop lifecycle
The executable P2 path is intentionally small and inspectable: one provider
session produces a candidate, independent verifiers inspect an immutable
snapshot, and only policy-approved evidence can finish the run. A failed
candidate returns structured findings to the same session; budget exhaustion or
uncertainty escalates to the operator.
The profiler reads typed task metadata and deterministic repository evidence. It
does not parse objective keywords or invoke an LLM. The selector persists one
of the following static decisions:
| Mode | Template | Current behavior |
|---|
DIRECT | direct-v1 | Executes one provider call, then applies the configured acceptance policy |
LOOP | feedback-loop-v1 | Executes bounded observe/verify/repair iterations in one provider session |
GRAPH | fixed-graph-v1 | Executes a checkpointed static graph with plan and outcome approval gates |
HYBRID | hybrid-rd-v1 | Executes the macro research graph with bounded local experiment/develop loops |
| Safe fallback | safe-unknown-v1 | Runs one bounded loop, verifies, and performs at most one replan before escalating |
How a feedback loop succeeds
- The runtime produces a candidate in the run's disposable worktree.
- Accretion captures an immutable observation and invokes the policy's independent
verifiers.
PASS completes the run; FAIL becomes a structured repair directive for the
next iteration.INCONCLUSIVE, exhausted budgets, repeated failure, or no progress fail closed
to explicit escalation. Cancellation and restart reconciliation close the
current attempt without losing committed iteration history.
Worker text such as “done” or “tests pass” is never sufficient evidence. Every
loop remains bounded by persisted wall-time, turn, tool-call, and iteration
ceilings.
Developer showcase
Run a bounded, read-only task through the real HTTP API and deterministic fake
runtime without consuming a signed-in provider session:
uv run python examples/showcase.py --repository "$PWD"
The showcase walkthrough explains the resulting planning,
runtime, verification, graph, trace, and audit records.
Project status
| Milestone | Status | Scope |
|---|
| P0 — Runtime feasibility | Complete | Runtime adapters, isolation, normalized events, health, recovery, and idempotency |
| P1 — Deterministic planning | Complete | Prompt/context contracts, profiling, selection, persistence, API, and New Task UI |
| P2 — Feedback loops | Complete | Bounded repeat execution, independent verification, recovery, controls, and loop visualization |
| P3 — Static graphs | Complete | Template registry, GRAPH/HYBRID engines, approval gates, checkpoints, replay, and graph visualization |
| P4 — Harness and release gate | Complete | Governed capabilities/MCP, credential boundary, side-effect evidence, complete operator surfaces, resumable SSE, and ACR-ARCH |
| P5 — Dynamic workflows | Released (opt-in) | Typed proposals, deterministic graph validation, static fallback, immutable revisions, safe replan, and operator inspection |
| P6 — Bounded candidate search | Released (opt-in) | Evidence-based routing, isolated branches, shared budgets, fail-closed ranking, promotion recovery, operator lineage, and frozen N=1/2/4 replay research |
| P7 — Verified experience | Released (opt-in) | Explicit materialization/selection, exact deterministic retrieval, invalidation, negative guidance, isolated fresh-control replay, operator provenance, and frozen negative-transfer research |
The v0.3 integration platform, delivered as nine milestones:
| Milestone | Status | Scope |
|---|
| M0 — Connection-aware capabilities | Released | Connector, connection and binding contracts with a capability resolver; every v0.1/v0.2 capability resolves unchanged |
| M1 — Identity and SSO | Released | Principals keyed by issuer and subject, workspaces and memberships, OIDC Authorization Code + PKCE, session middleware with a LOCAL_PRINCIPAL default |
| M2 — Token broker | Released | Encrypted secret store, single-use OAuth transactions, broker-backed capability invocation, and the GitHub connector lifecycle |
| M3 — Remote MCP | Released | Authenticated MCP SDK v2 discovery and invocation, durable discovery snapshots, server lifecycle/audit records, health and circuit breaker |
| M4 — Plugin manager | Released | Version registry, workspace-scoped installations, manifest trust and dependency resolution, resolver gate |
| M5 — Research intelligence | Released | MCP-backed research capabilities, evidence normalization, connector-attributed sources with trust the connector cannot assert for itself |
| M6 — Operator administration | Released | Plugins, Connections, MCP Servers, Capability Inspector and Identity pages, plus run-detail provenance inspectors |
| M7 — Enterprise-managed authorization | Released (off by default) | Optional EMA in which a centrally issued token still passes through capability policy, connection isolation and the audit trail unchanged |
| M8 — Release hardening | Released | Executable SDD §24.8 release gate, every acceptance criterion claimed (unmet MUST: 0), CI gating the full harness, and zero axe violations across all seventeen routes |
Research result summary
The consolidated experiments and results guide
explains the frozen design, primary result, classification, negative/null cases,
fixture provenance, and reproduction path for ACR-ARCH and P5–P7. It also keeps
signed-in provider calibration and release engineering results visibly separate
from deterministic research claims.
P6 completion summary
P6 was delivered as three independently reviewed slices into develop:
| Slice | Merged evidence | Result |
|---|
| Contracts and persistence | PR #37 | Versioned search plans, runtime decisions, candidate trajectories/scores, promotion records, feature gates, PostgreSQL migration 0008, and API contracts |
| Executor and recovery | PR #38 | Best-of-N, hypothesis, cross-provider, and generator-reviewer execution; isolated worktrees; shared budgets; independent selection; cancellation; and crash reconciliation |
| Operator and research surfaces | PR #39 | Search planning and lineage UI, provider/model/version and spend evidence, frozen 12-task N=1/2/4 benchmark, runbook, showcase, acceptance report, and accessible diagrams |
All nine P6 acceptance criteria (V02-P6-001 through V02-P6-009) are mapped
to automated evidence in the P6 acceptance report.
The final P6 gate recorded 200 passing PostgreSQL-backed backend tests with three
opt-in live-provider tests skipped, 19 passing UI tests, a successful production
build, and a complete PostgreSQL upgrade/downgrade/upgrade cycle. P6 remains off
by default. REPLAY_BRANCH continues to fail closed unless the independent P7
deployment/project gates are enabled and the operator has frozen compatible
matches into task context.
P7 completion summary
P7 adds explicit procedural reuse without automatic learning or authority
expansion. Its immutable experience contracts and pgvector persistence landed in
PR #41; deterministic retrieval,
compatibility, invalidation, selection, and ContextBundle v2 landed in
PR #42; and replay execution,
operator explainability, and the frozen transfer gate landed in
PR #43. Replay execution keeps a
fresh control, creates a new isolated worktree/session per positive seed, uses
negative experience only as avoidance guidance, and revalidates before launch,
selection, promotion, and recovery.
All eight P7 criteria (V02-P7-001 through V02-P7-008) are mapped in the
P7 acceptance report. The frozen P7 gate contains
20 tasks, 50 sources, and 80 traces; it records 95% stale rejection (corpus-declared;
the criterion itself is proven against the live assessor, see ADR3-M8-005), 3.33%
negative transfer, +0.0705 replay quality, 20% fewer replay tool calls, and no
false-accept or success-rate regression. These are fixture results, not live
provider claims.
See the v0.1 system design and the
multi-release SDD index for the full
architecture and acceptance criteria. The latest
v0.1 release audit records the clean-checkout GO
decision. The frozen v0.1 baseline identifies the exact
release and experimental control; the v0.1.0 release notes
describe its shipped scope, compatibility, and reproducibility hashes.
The v0.2 release added the opt-in P5 dynamic-workflow, P6 bounded-search, and P7
verified-experience slices. Start with the P5 dynamic benchmark, P7 runbook,
developer showcase, acceptance report,
and delivery plan. The frozen v0.2 baseline
records the exact release identifiers and evidence fingerprints. The
v0.2 release audit records the release authorization
and browser exception; the
v0.2 SDD remains the normative contract.
The v0.3.0 release added the integration platform: connections and
bindings, identity and SSO, the token broker, remote MCP, plugins, research
capabilities, operator administration, optional enterprise-managed
authorization, and the release hardening that made the gate executable. Start
with the release notes and
release audit; the
acceptance baseline gives the
per-criterion status, the
release-hardening runbook records the
M8 decisions and how to reproduce the gate, and
browser and accessibility evidence
records the axe-core results. The
v0.3 SDD remains the normative contract for that
surface.
The current v0.4.0 release makes node configuration routing evidence-aware:
the receipt-first deterministic router, the experience and feedback pipeline,
the offline ranker and candidate gate, cold start and the project adapter,
shadow evaluation by branched live rollouts, the guarded bandit, the activation
ledger and the promotion gate, the Experiment Studio, and a pre-registered,
locked router benchmark. Start with the
release notes and
release audit; the
acceptance baseline gives the
per-criterion status, the frozen v0.4 baseline
the release identifiers, and the
research results the locked benchmark's
numbers with their pre-registration.
The v0.4 SDD is the normative contract for
this release.
Quick start
Prerequisites
- Python 3.12+
uv- Node.js 22+ and npm
- Git
- Docker with Compose
- Optional: supported, signed-in Codex, Claude Code, and opencode CLIs for live providers
The validated live-provider range is carried unchanged from v0.2: Codex CLI
>=0.148,<0.149, Claude Code >=2.1.231,<2.2, and opencode >=1.18,<1.19. The
v0.3.0 evidence was recorded against Codex CLI 0.148.0 and Claude Code
2.1.252 — see
live-acceptance-2026-09-01.md.
v0.4.0 recorded no new live-provider run: its routing, learning and benchmark
evidence is replay-only on the FAKE runtime, and the three manual criteria are
still carried by the v0.3.0 record until it expires on 2027-02-28.
Choose and clone a version
For the current immutable release:
git clone --branch v0.4.0 https://github.com/santapong/Accretion.git
cd Accretion
For the immutable v0.1 static control, use --branch v0.1.0. For ongoing
development:
git clone --branch develop https://github.com/santapong/Accretion.git
cd Accretion
Then install and migrate:
cp .env.example .env
uv sync --all-groups
npm ci
docker compose up -d postgres
uv run alembic upgrade head
Start the control plane
Run the API and UI in separate terminals:
make api
make ui
Open http://localhost:5173. The API is available at
http://localhost:8000, with interactive documentation at
http://localhost:8000/docs.
Live providers are disabled by default. Enable them only after confirming the
local CLIs are installed and signed in:
ACCRETION_ENABLE_LIVE_PROVIDERS=true
Accretion checks CLI authentication status but never reads or copies raw
provider credentials.
For deterministic acceptance, declare concrete repository-relative output paths
when creating a task. If required evidence or a configured verifier is unavailable,
Accretion returns INCONCLUSIVE and escalates instead of accepting the run.
Configuration
All settings use the ACCRETION_ prefix and can be placed in .env.
| Variable | Default | Purpose |
|---|
ACCRETION_DATABASE_URL | Local PostgreSQL | Authoritative state and event store |
ACCRETION_DATA_DIR | .accretion | Worktrees and captured artifacts |
ACCRETION_ENABLE_LIVE_PROVIDERS | false | Allows Codex, Claude, and opencode executions |
ACCRETION_ENABLE_DYNAMIC_WORKFLOWS | false | Enables P5 proposal and graph-revision services globally |
ACCRETION_ENABLE_CANDIDATE_SEARCH | false | Enables P6 search globally; project opt-in is still required |
ACCRETION_ENABLE_EXPERIENCE_RETRIEVAL | false | Enables P7 materialization, retrieval, selection, and replay integration globally |
ACCRETION_GLOBAL_MAX_RUNS | 4 | Global concurrency ceiling |
ACCRETION_PROVIDER_MAX_RUNS | 2 | Per-provider concurrency ceiling |
ACCRETION_PROJECT_MAX_RUNS | 2 | Per-project concurrency ceiling |
ACCRETION_OPERATOR_IDENTITY | local-operator | Identity recorded in override audits |
See .env.example for the complete local configuration.
Verification
Run the standard backend and frontend checks:
make check
make test
npm run build
npm run api:generate
PostgreSQL integration tests use ACCRETION_TEST_POSTGRES_URL. Signed-in live
provider tests are deliberately opt-in:
ACCRETION_LIVE_PROVIDERS=1 ACCRETION_CLAUDE_LIVE_MODEL=sonnet \
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 \
uv run --no-sync pytest -p pytest_asyncio.plugin -m live
ACCRETION_LIVE_PROVIDERS=1 ACCRETION_CLAUDE_LIVE_MODEL=sonnet \
uv run --no-sync python scripts/run_acr_arch_live_sample.py
The validated CLI range and recorded acceptance evidence are documented in the
P0 runtime runbook and the
P2 loops and verifiers runbook.
Repository guide
apps/ui/ React operator interface
src/accretion/api/ FastAPI routes and schemas
src/accretion/runtimes/ Codex, Claude, opencode, and fake runtime adapters
src/accretion/persistence Durable state, planning history, and side effects
src/accretion/planning.py Deterministic profiler and selector policy
src/accretion/looping.py Loop policy, budgets, and terminal outcomes
src/accretion/projections.py Read-only execution graph projections
src/accretion/governance.py Capability policy, credentials, and governed executor
src/accretion/benchmark.py Frozen ACR-ARCH replay and architecture metrics
src/accretion/search_benchmark.py Frozen P6 quality-vs-compute replay metrics
src/accretion/experience_benchmark.py Frozen P7 transfer-safety replay metrics
src/accretion/orchestration/ P5 workflow and P6 candidate-search authority
src/accretion/experience/ P7 materialization, embedding, compatibility, and retrieval
src/accretion/verifiers/ Deterministic verifier implementations and registry
migrations/ Alembic schema history
tests/ Unit, API, PostgreSQL, and live acceptance tests
examples/ Safe public-API demonstrations using the fake runtime
docs/ Documentation hub and grouped visual assets
docs/guides/ Newcomer, developer, frontend, and showcase guides
docs/runbooks/ P0–P7 operation and recovery procedures
docs/research/ Experiment design, frozen results, and decisions
docs/releases/ Versioned plans, audits, notes, and baselines
docs/governance/ Repository and documentation process
docs/sdd/ Versioned normative system design specifications
Contributing and security
Development uses short-lived branches and pull requests into protected
develop; stable releases are promoted to main. Before contributing, read
CONTRIBUTING.md and the
branch policy.
Please report security concerns through the process in
SECURITY.md, not through a public issue.
License
Accretion is available under the MIT License.
