--- description: Guarded local SQLite diagnosis, retention preview, pruning, and compaction for Neo — plus the regenerable browser evidence and the rest of the framework's own disk footprint agents: [neo] task_types: [runtime-storage, local-maintenance, telemetry-retention, disk-footprint] triggers: [aios.sqlite large, runtime database size, remove old runtime data, prune, compact, screenshots taking space, visual-screenshots, walkthrough artifacts, disk full, free disk space, disco cheio, liberar espaço, backups taking space, storage:triage] --- # Neo Runtime Storage Load this module only for an explicit runtime-storage request. The database is local and disposable as a whole, but active coordination inside it is not disposable while work is in progress. ## Boundaries - Keep `.aioson/runtime/aios.sqlite` local and gitignored. Never propose versioning, uploading, or sharing it. - Never run direct SQL. Use only the maintenance CLI below. - Never delete durable project-memory files (`features`, `learnings`, `brains`, `rules`, `docs`, dossiers, or plans). - Never delete squad files under `output/`; old `content_items` rows with a registered `source_path` are only a rebuildable local index. - Pruning preserves active tasks/runs, paused executions inside the retention window, pending/running runner items, actionable Neural Chain work items, unresolved handoffs, artifacts, learnings, plans, and catalog/configuration rows. - Preserve legacy `content_items` rows without `source_path` until their database-only payload has been exported to files. - `--force` is forbidden unless the operator explicitly confirms that reported live runtime records are not running. ## Automatic lifecycle `feature:close` already maintains the database at every closure: it removes the closed feature's raw lane output, applies the retention windows and compacts when free pages are at least 8 MB and 25% of the file. Only work that moved in the last 120 minutes counts as live and holds compaction back; rows a dead session left `running` show as `stale` in `runtime:storage` and do not block it (`aioson agent:recover .` marks them abandoned). `aioson doctor .` reports `runtime:db_health`; `aioson doctor . --fix` runs the same prune-and-compact. A manual request is only needed between closures. ## Procedure 1. Diagnose read-only: `aioson runtime:storage . --json` 2. If cleanup is useful, preview exact policy targets without deleting: `aioson runtime:prune . --dry-run --older-than=30 --output-older-than=14 --json` 3. Show database size, dominant category, eligible direct rows, protected active counts, retention windows, and whether physical compaction is useful. 4. If the operator has not already explicitly requested execution, ask for confirmation once. A request such as "remove old runtime data now" is sufficient approval after the preview; a generic `@neo` activation is not. 5. Execute only the approved scope: - Cleanup: `aioson runtime:prune . --older-than=30 --output-older-than=14 --json` - Cleanup plus disk reclamation: add `--compact`. - Compaction without deletion: `aioson runtime:compact . --json`. 6. Report rows removed per table, bytes reclaimed, skipped compaction, and any integrity/locking error. ## Evidence artifacts on disk The visual and browser gates leave regenerable binaries beside their reports: runtime captures under `.aioson/context/features/{slug}/visual-screenshots/` (from `verify:artifact --kind=visual --screenshots`) and per-step snapshots under `.aioson/briefings/{slug}/browser/{script}/` or `.aioson/context/features/{slug}/browser/{script}/` (from `browser:run`). They are not the evidence — the JSON and Markdown reports next to them are — and every report carries the line that regenerates its folder. The producers replace what they wrote once a run has measured (a capture run narrowed by `--route` keeps its sibling captures), `feature:archive` drops the binaries when a feature closes, and `hygiene:scan` lists what is orphaned or heavy under `heavy_evidence_artifacts`. - Preview: `aioson evidence:prune . --dry-run` (add `--slug={slug}` for one owner). Orphans — files the latest report no longer references — are the default scope; `--all` removes every capture and snapshot, never a report. - Execute only on an explicit request, after showing the preview: `aioson evidence:prune .` or `aioson evidence:prune . --all`. - Never delete the reports (`visual-evidence.json`, `browser/{script}.json|.md`) or anything outside these folders. ## Disk footprint The rest of the framework's own disk footprint: the doc snapshots `agent:done` writes after @product, @sheldon and @planner (`~/.aioson/backups/{project}/`), the rollback folders `aioson update` leaves in `.aioson/backups/`, logs an agent or tool let grow inside `.aioson/`, and heavy paths the framework cannot regenerate (scratch under `.aioson/runtime/` or `.aioson/tmp/`, a backup the framework did not write, raw research output under `researchs/`). The producers keep the newest 10 snapshots and the newest 5 rollback folders on their own; `hygiene:scan` lists what is left under `disk_footprint`, and `doctor`/`update` warn when retention is past due. The recall index (`.aioson/runtime/context-search.sqlite`) is a cache each project rebuilds from its own Markdown and is deleted with the project; it is never a cleanup target. The machine-wide index every project shared before (`~/.aioson/search/`) is retired the first time a project opens its own. 1. Diagnose read-only: `aioson storage:triage . --json`. Add `--global` when the request is about the machine's disk: every project's snapshots, the old machine-wide recall index, and files someone left in `~/.aioson/search/`. 2. Present two groups: **Mechanical** (`decides: auto` — snapshots and rollback folders past retention, oversized logs trimmed to their head and tail, the old machine-wide recall index) and **Owner decisions** (`decides: owner` — each heavy path with its size and reason). 3. Preview: `aioson storage:triage . --apply --dry-run`, plus `--remove= --dry-run` for each path the owner names. 4. Ask once. A request such as "free disk space now" approves the mechanical group after the preview; an owner path goes only when the owner names it. 5. Execute only the approved scope: `aioson storage:triage . --apply`, then `aioson storage:triage . --remove=` with each path exactly as the report prints it. One path the report did not list refuses the whole call; nothing changes. 6. Report the bytes freed per item and every failure (a file another process holds open stays, and is named). - Never delete these files by hand, and never remove a path the report did not list. - The runtime database is never part of this procedure — it follows the Procedure above. - A heavy path the owner keeps on purpose goes into `.aioson/context/hygiene-retention.md` as `| | retained | | |`; hygiene stops listing it. Do not route to another agent merely to run these commands. After maintenance, return to Neo's normal read-only routing behavior.