---
digest: >
  v0.30.1 contains all user-scoped runtime state inside the resolved mirror
  home. Development and test environments no longer write databases to the
  homes root (~/.mirror-minds), unconfigured runs fail with an actionable
  one-line hint instead of silently creating root databases, extension
  dispatch resolves the same environment-aware database as the core, the Pi
  mirror-logger writes its log inside the mirror home, and runtime diagnose
  reports legacy root artifacts with a documented manual relocation route.
---

# v0.30.1 — Runtime State Home Containment

**Date:** 2026-07-12

## Highlights

- The runtime directory is the resolved mirror home for **every**
  `MEMORY_ENV`; the environment selects only the database name
  (`memory.db`, `memory_dev.db`, `memory_test.db`).
- Unconfigured resolution fails loudly: a one-line actionable hint
  (`Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER…`),
  exit code 2, no traceback, and no silent homes-root writes.
- Extension dispatch and the core share one `(mirror home, environment) →
  database` mapping (`db_path_for_home`), so a single session can no longer
  straddle two database files.
- The Pi mirror-logger writes to `<mirror home>/mirror-logger.log`; the
  homes root remains only as the bootstrap error channel when no mirror
  home is resolvable.
- `runtime diagnose` reports `legacy_root_runtime_state` findings for
  databases, logs, locks, and backups sitting directly in the homes root,
  with a manual relocation route documented in REFERENCE.

## Where We Started

A field investigation during a `mirror`-journey session found the homes root
(`~/.mirror-minds`) accumulating live runtime state alongside the per-user
mirror homes: an orphan production `memory.db` holding 190 conversations
bulk-imported in a 22-second burst with no resolvable mirror home, a live
root `memory_dev.db` carrying the framework repository's own development
sessions, the Pi `mirror-logger.log`, bootstrap locks, and a `backups/`
directory.

The root cause was pre-CV4 flat-layout semantics that survived inside
`config.py`: the mirror home was honored only in production, so development
and test environments — and any run with an unresolvable home — silently
targeted the homes root. The same split let extension state and session
registration land in two different databases, which had caused a
wrong-session export earlier the same day.

## What Changed

`config.py` now separates the two axes it had entangled. The runtime
directory always resolves to the mirror home; `MEMORY_ENV` picks only the
database name. Explicit `MEMORY_PROD_DIR`, `MEMORY_DIR`, and `DB_PATH`
overrides keep winning and are never second-guessed. When nothing is
configured, database-touching commands raise
`MirrorHomeNotConfiguredError` — surfaced by the CLI as a single actionable
line with exit code 2 — instead of materializing databases in the root.

Extension dispatch (`memory ext`) opens the database through the shared
`db_path_for_home` mapping. The Pi logger resolves its log destination with
the same precedence as data routing (`MEMORY_DIR` > resolved mirror home >
homes-root bootstrap fallback), reusing the resolution machinery introduced
in v0.29.3 rather than adding a third copy (TD-001 scope note recorded).
`runtime diagnose` gains detection for legacy root artifacts, and REFERENCE
documents the manual relocation route.

## Conscious Exclusions

- **No automatic migration.** Existing root databases are detected and
  reported, never moved or merged automatically — diverged histories require
  a human decision. An assisted relocation command is a candidate follow-up.
- **`EXPORT_DIR` homes-root fallback** is unchanged (no root artifact
  observed in the wild); recorded in the story's refactoring notes.
- **No automated tests for the Pi extension's TypeScript path resolution** —
  the Pi extension has no test harness; the behavior was validated manually.
  The duplicated resolution contract remains tracked as TD-001.

## Lessons

The leak survived because failure was silent: development and test writes
"worked", just in the wrong place, for months. The loud-failure rule would
have surfaced the orphan production database the day it was created.
Stabilization principles apply to configuration resolution, not only to
provider errors — silence, not the wrong path, was the root defect.

## Next Horizon

CV9.E2 continues with embedding resilience (S1) and external extension
runtime surface parity (S2); CV9.DS7 conversation metadata lifecycle still
has apply behavior open; Boundary Hardening (CV9.E1) remains ahead of the
full CV9 done condition.
