# v0.6 Roadmap — Controlled Runtime Experiments

Status: **repository-level complete in `0.6.0`**.

v0.6 adds one finite, authority-gated waterfall profiling experiment while keeping Runtime Diagnostics and Runtime Verification read-only. It does not generalize the project into arbitrary Cordis/runtime mutation.

## Completion summary

- [x] Wave A — architecture and authority contract
- [x] Wave B — shared experiment contract
- [x] Wave C — lease coordinator core
- [x] Wave D — experiment trace association
- [x] Wave E — DSH Agent approval/tool adapter
- [x] Wave F — MCP auth/capability adapter
- [x] Wave G — unified service/control integration
- [x] Wave H — DSH/MCP/Human production adapters
- [x] Wave I — combined real DSH experiment proof
- [x] Wave J — repository closeout

## Implemented product boundary

Included:

- [x] one shared `WaterfallExperimentCoordinator` owns all instrumentation mutation;
- [x] Human vs Agent ownership semantics;
- [x] finite Agent leases with default 15 s and maximum 60 s TTL;
- [x] exact lease stop, stale-stop no-op, and timeout cleanup;
- [x] experiment-tagged waterfall traces and exact `experimentId` filtering;
- [x] read-only experiment status through diagnostics / Cordis Inspect / MCP;
- [x] dedicated DSH start/stop tools, with start requiring one-shot `ctx.approval`;
- [x] optional authenticated MCP experiment capability;
- [x] Human emergency stop and explicit Agent-owned Profiler UX;
- [x] combined keyless real DSH proof.

Deferred:

- automatic reload/orchestration;
- arbitrary event execution;
- generic listener/service/config mutation;
- persistent approvals;
- lease renewal;
- multiple simultaneous leases;
- remote MCP;
- payload capture;
- automatic root-cause `diagnose()`;
- non-waterfall instrumentation.

## Wave A — Architecture and authority contract ✓

Final decisions:

- [x] one coordinator is the only production mutation owner;
- [x] Human emergency stop may terminate an Agent lease;
- [x] Agent cannot steal Human ownership;
- [x] Agent leases are always finite;
- [x] DSH mutation uses dedicated tools rather than `CordisRuntime` Inspect;
- [x] DSH start requires one-shot approval, while exact stop does not require a second approval;
- [x] external MCP uses explicit operator capability + bearer authentication rather than fake DSH identity;
- [x] trace attribution uses `experimentId = leaseId`.

Architecture decision: [.agents/notes/implemented/architecture/2026-08-24-controlled-runtime-experiments.md](../.agents/notes/implemented/architecture/2026-08-24-controlled-runtime-experiments.md).

## Wave B — Shared experiment contract ✓

Delivered:

- [x] transport-neutral owner/status/lease/outcome types;
- [x] finite TTL input contract;
- [x] `dsh | mcp` Agent source vocabulary;
- [x] optional trace `experimentId`;
- [x] public exports and contract tests.

Landed through PR #53.

## Wave C — Lease coordinator core ✓

Delivered:

- [x] single-owner state machine;
- [x] Human acquire/release;
- [x] Agent start/exact stop;
- [x] finite expiry timer;
- [x] stale timeout/stop protection;
- [x] Human force-stop;
- [x] conflict/unsupported fail-closed handling;
- [x] disposal cleanup and deterministic tests.

Landed through PR #54.

## Wave D — Experiment trace association ✓

Delivered:

- [x] trace `experimentId` metadata;
- [x] current-lease tagging;
- [x] Human traces remain untagged;
- [x] exact `experimentId` query filtering;
- [x] bounded retention semantics preserved;
- [x] late settlement / late `next()` retains original association.

Landed through PR #55, with MCP schema parity completed in Wave I.

## Wave E — DSH Agent authority adapter ✓

Delivered:

- [x] `cordis_start_waterfall_experiment`;
- [x] `cordis_stop_waterfall_experiment`;
- [x] start asks through real `ctx.approval` before coordinator mutation;
- [x] only `allowed-once` proceeds;
- [x] missing/rejected/cancelled/unavailable outcomes fail closed;
- [x] stop is exact-lease cleanup without second approval;
- [x] `CordisRuntime` remains read-only.

Adapter landed through PR #56; live DSH registration landed through PR #59.

## Wave F — MCP auth/capability adapter ✓

Delivered:

- [x] optional bearer authentication;
- [x] non-empty token required for external experiment mutation;
- [x] original seven read-only MCP tools remain backward-compatible by default;
- [x] experiment mutation tools are omitted unless explicitly enabled;
- [x] experiment status/start/stop schema and delegation;
- [x] official MCP SDK auth/tool-list coverage;
- [x] endpoint remains `127.0.0.1` only.

Authority helper landed through PR #57; final live integration landed through clean rebuild PR #62.

## Wave G — Unified service/control integration ✓

Delivered:

- [x] `DevtoolsService` owns the coordinator;
- [x] Human browser enable/disable routes through coordinator ownership;
- [x] diagnostics expose read-only experiment status;
- [x] trace tagging reads coordinator lease context;
- [x] disposal delegates owner-safe cleanup;
- [x] exactly one production mutation path remains.

Landed through PR #58.

## Wave H — Production adapters and UI ✓

### H1 — DSH live tools

- [x] real ToolRuntime registration;
- [x] live coordinator delegation;
- [x] approval-gated finite start;
- [x] exact stop.

PR #59.

### H2 — MCP live experiments

- [x] live coordinator delegation;
- [x] plugin config validation;
- [x] authenticated official SDK Client start/status/stop;
- [x] default seven-tool compatibility preserved;
- [x] bad/missing token fails before mutation.

PR #62. The earlier sibling implementation was rebuilt from latest `main` after DSH/UI siblings landed rather than dropping either behavior during an entry-file conflict.

### H3 — Human ownership UX

- [x] ordinary Human profiling remains behavior-compatible when idle;
- [x] Agent source and expiry are visible;
- [x] Agent-owned state is not presented as a Human toggle session;
- [x] Human emergency stop terminates Agent ownership.

PR #61.

## Wave I — Combined real DSH experiment proof ✓

PR #63 added an independent controlled-experiment smoke while retaining the existing v0.5 Runtime Verification smoke.

The final real DSH proof uses no model/API credentials and exercises:

```text
real SessionStore live session + open turn
  ↓
real ToolRuntime + ApprovalService
  ├─ unavailable/rejected → no mutation
  └─ allowed-once → DSH Agent lease
                         ↓
                    real waterfall
                         ↓
                 tagged exact trace
                         ↓
              stale stop / exact stop

then

authenticated official MCP Client
  ↓
MCP Agent lease
  ↓
exact experimentId trace filter
  ↓
Human emergency stop / TTL cleanup

then

ordinary Human Profiler still works
```

Negative twins proven:

- [x] DSH approval rejected/unavailable → no mutation;
- [x] bad/missing MCP authentication → no authorized mutation;
- [x] stale lease stop → no mutation;
- [x] Human force-stop → Agent lease ends safely.

A first E2E attempt intentionally revealed that a session-shaped fake is not sufficient: real ToolRuntime rejects a caller whose session is not live in `SessionStore`. The final fixture therefore creates an authoritative live session and opens a real turn, preserving the genuine ToolRuntime/ApprovalService authority path.

## Wave J — Repository closeout ✓

Delivered in the final closeout PR:

- [x] architecture decision moved from proposed to implemented;
- [x] README documents ownership, DSH approval, MCP auth, lease workflow, and real proof;
- [x] product/roadmap/parallel docs describe actual implementation;
- [x] `package.json` repository version is `0.6.0`;
- [x] MCP protocol server reports `0.6.0`;
- [x] release-hardening policy/typecheck/tests/build/client-bundle/two-real-DSH-smoke gate required before merge.

No npm publish, Git tag, or GitHub Release is part of repository closeout.

## Completion definition

v0.6 is complete at repository level when this closeout PR is merged after full CI:

- one coordinator owns all waterfall instrumentation mutation;
- DSH start is one-shot approved and finite;
- external MCP mutation is explicitly capability-gated and authenticated;
- exact lease ownership protects stop/timeout races;
- Agent traces are attributable through `experimentId` while retention remains bounded;
- Human emergency control remains authoritative;
- real DSH E2E proves positive and fail-closed paths without model/API credentials;
- observer diagnostics, Runtime Verification, Human UI, and waterfall parity remain green.

Repository readiness remains separate from npm publication, tags, and GitHub Releases.