Epic: Self-configuring Agent OS — measured install-time config + drift healing (config-lifecycle)

Problem Scope

The Agent OS heals its data (ADR-0027), heals its processes (ADR-0026), and tunes its serving sweet-spot (#14418) — but its own configuration is a hand-managed static artifact with no lifecycle owner: hand-run init scripts, hand-merged operator overlays, hand-tuned cadences. Nothing monitors the config plane, nothing reconciles it, nothing records why a value is what it is.

Empirical anchors (the chronic-drift corpus, all WITH docs/scripts shipped): session 567e4f07 (2026-05-10) self-repaired a local config.mjs + template ancestor-path bug · a Codex-side session hit the manual initServerConfigs denial wall (2026-07-02) · the author's own overlay silently lacked newer template leaves until a runtime TypeError forced a hand-merge (2026-07-02). Root cause: config-as-static-artifact — mechanically, the snapshot-not-inheritance seam (config.mjs copies the template instead of inheriting from it).

The business stake is Ring-2 adoption: time-to-first-persistence (TTFP) is the sellable number for Agent-OS-on-your-codebase; today it is expert-setup-shaped.

Why an Epic: the outcome spans a Decision Record, an acceptance harness, install-time and drift-heal capabilities, and a metrics plane — coordinated changes across ai/ config substrate, install pipeline, and docs that no single PR can deliver.

Intended Solution (the graduated shape)

Measurement-first E → A+C on the existing homeostatic/MAPE-K pattern, over the ADR-0019 reactive-Provider knowledge plane (written INTO, never around):

• Measurement floor first (Option E): a timed fresh-install acceptance harness produces the manual baseline before any machinery claims adoption wins — TTFP, time-to-first-PR (the #14230 fork→PR ≤ 30 min outcome contract), config-touch-count. The harness IS the falsifyingQuery implementation for every adoption claim (per the #14430 discipline), and the measurement substrate comes up FIRST during install so fresh installs are never invisible.
• Install-time detect-and-propose (A): a one-shot probe emits deploymentClass as its first fact, scopes the configurable surface, and proposes a complete template-derived overlay delta; the human confirms once. Probe scope: propose-and-confirm leaves + auto-envelope initial values + schema-declared delegation sentinels only.
• Drift-heal-by-proposal (C): the overlay stops being a snapshot — the template exports an extendable base and the operator overlay becomes the singleton subclass carrying delta-only data (inheritance-by-construction kills the additive-drift class at the root; grounded buildable at source: src/state/Provider.mjs:98-114 deep merge, ai/ConfigProvider.mjs:90-109 hierarchical thin-child composition). Version-stamp + preflight-diff canaries cover the residual overridden-leaf conflict class. Drift detection fires at local-dev preflight, never CI-only (false-green closure).
• Runtime self-tuning (B) is explicitly deferred — laddered behind measurable auto-tier leaves, the controller-arbitration coordinator contract (three controllers over one knowledge plane never run blind — the #13873 boundary), and its structural bounds: session-scoped override layers or next-boot deltas only.
• The blast-tier taxonomy travels WITH the leaves: T0 detect-only / T1 auto-within-envelope / T2 propose-and-confirm / T3 human-only, × a deploymentClass shift rule (tenant/cloud: every T1→T2; propose-only on guest substrate at every tier), carried as a declaration slot with a fail-closed T3 default, lint-checkable.

Hard scope boundaries carried from graduation (per-sub ACs live in the subs): ADR-0019 SSOT — no hidden defaults, no pass-along config objects, no non-entrypoint AiConfig imports · config-world only, never ADR-0027 data mutation · B4 inviolate: no runtime mutation of the shared config singleton, ever · no self-licensing enables — dedicated enables are human-only unless a schema-declared delegation sentinel exists, and numeric ranges may not smuggle disable semantics into auto-tier (declared envelopes exclude disable regions; boundary-crossing = tier escalation) · every self-set value carries {why, when, source, evidence} provenance as ADR-0019-native leaf metadata · #14426-class integrity canary for any new node/record class.

Source & Graduation Record

Graduated from Discussion #14456 (2026-07-04): §5.2 Step-Back delivered by the non-author family + §6.2 family-keyed quorum met.

Signal Ledger (carried per §6.6)

Unresolved Dissent: none. Unresolved Liveness: Ada/Vega were Opus-benched during divergence; Gemini operator-benched — re-poll obligations attach to future material edits, not to this graduation event.

Out of Scope

• The runtime tuner (B) until its ladder gates are met — deferred by design, not forgotten.
• ADR-0027 data-world healing (sibling immune-system plane).
• Business-surface rendering beyond emitting METRIC nodes (the #14442 business engine owns dashboards/rendering).
• A "better init wizard only" path (Option D) — subsumed as A's confirmation UI.

Avoided Traps (divergence preserved from the source Discussion)

• Static-tooling-only (D): all three lived drift instances happened WITH scripts and docs shipped — discipline demonstrably did not hold.
• One-shot A without C: improves day-0, rots day-30 — install-time config claims authority it stops earning (A's own falsifier).
• B-first: most config is not outcome-measurable (auth modes, paths, identities), and a second controller without the coordinator contract recreates the #13873 arbitration problem structurally.
• Enable-smuggling via numeric ranges: four live template leaves embed ≤0 disables semantics inside tunable ranges — an AIMD tuner walking a watchdog cadence across that boundary self-disables the immune system without touching an enable flag.
• CI-only drift detection / board-column substrate: the stale-overlay class bites at local dev; durable facts live in graph/issue substrate.

Related

Discussion #14456 (source) · #13873 → #14418 + ADR-0026 (homeostatic pattern + carry-forward ACs) · ADR-0019 (the config knowledge plane — read-gate before any code here, per §critical_gates rule 10) · ADR-0025/0027 (MAPE siblings) · #14430/#14442 (provenance discipline + METRIC home) · #14230 (outcome contract) · #14404/ingestTenant.mjs (onboarding path) · learn/agentos/AiConfigModel.md.

Lane note: Lane 5 of the post-v13.1 goal-scoping map (Discussion #14561). Steward: the author, until a lane owner self-selects.

Structure-map gate: N/A recorded — placement claims are source-anchored via the graduation Step-Back's V-B-A (file:line cites above); no new directory placement occurs at epic-filing time (each leaf runs structural-pre-flight when authored).