mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
5fc9157017
## Summary Removes Fabro's automatic retro generation stage so workflow runs go directly from execution to finalization and optional PR creation. This drops the retro-specific crate, events, projection fields, config/API knobs, and user-facing docs in favor of the existing durable run observability surfaces. ## What Changed - Deleted the `fabro-retro` crate and the workflow `retro` pipeline phase, with finalization now consuming `Executed` state directly. - Removed retro configuration and API surface area, including `--no-retro`, `[run.execution].retros`, manifest `no_retro`, `features.retros`, and run projection `retro*` fields. - Retired typed `retro.*` events while keeping historical event logs readable by deserializing retired retro event names as `Unknown`. - Stopped appending retro sections to generated PR bodies and updated docs, marketing copy, screenshots, and navigation to point users toward observability/event-stream inspection. ## Testing Not run during PR creation; this branch already contained the implementation commit. --- [](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with GPT-5 (unknown context, reasoning unspecified) via [Codex](https://openai.com/codex)
84 lines
3.9 KiB
Text
84 lines
3.9 KiB
Text
---
|
|
title: "Run Directory"
|
|
description: "Structure of Fabro's per-run directory"
|
|
---
|
|
|
|
<Warning>
|
|
The run directory structure and file formats described here are internal implementation details and subject to change without notice. Do not build tooling that relies on them. The authoritative source of run state is the event-sourced run store; the scratch directory is now mostly local runtime state and caches.
|
|
</Warning>
|
|
|
|
Each `fabro run` invocation creates a timestamped directory under `~/.fabro/storage/scratch/`:
|
|
|
|
```
|
|
~/.fabro/storage/scratch/20260307-01JQXYZ123ABC456DEF789/
|
|
```
|
|
|
|
The naming format is `YYYYMMDD-{run_id}`, where `run_id` is the ULID assigned to the run. You can override the base storage directory with the global `--storage-dir` flag (the scratch directory will be `<storage-dir>/scratch/`).
|
|
|
|
## Root-level files
|
|
|
|
| File | Format | When written | Description |
|
|
|---|---|---|---|
|
|
| `workflow_bundle.json` | JSON | Run create | Bundled workflow input used to restart the run without re-reading the original workflow files. Includes the root workflow path plus bundled child workflow sources and inline files. |
|
|
| `run.pid` | Text | Legacy only | Legacy process ID file from older runs. Current detached launches use launcher records instead, and current attach/resume no longer read `run.pid`. |
|
|
|
|
## Local-only directories
|
|
|
|
These paths are local runtime state and caches, not the canonical run state.
|
|
|
|
- **`worktree/`** — When running in worktree mode, Fabro creates a Git worktree here as the working directory for agents and commands.
|
|
- **`runtime/`** — Local runtime files. Today this includes `runtime/server.log` for the raw per-run worker tracing log and materialized blob payloads under `runtime/blobs/`.
|
|
- **`nodes/{manager_node}_{visit}/child/`** — Nested scratch directories for manager-loop child workflows.
|
|
|
|
Large durable values, event streams, checkpoints, diffs, and conclusions are no longer projected into live scratch by default. Use `fabro events`, `fabro inspect`, the API, or `fabro dump` for those surfaces. Use `fabro logs` for the raw per-run worker tracing log when it is available.
|
|
|
|
## Reconstructed and export-only layouts
|
|
|
|
Metadata branch snapshots and `fabro dump` exports now use the same core layout:
|
|
|
|
- `run.json` for the current projection snapshot, including the current checkpoint
|
|
- `graph.fabro` for workflow source
|
|
- `stages/{rank:03}-{node_id}@{visit}/...` for execution-order-prefixed per-stage prompt, response, status, diff, and command output files
|
|
|
|
`fabro dump` adds export-only history surfaces on top of that shared layout:
|
|
|
|
- `events.jsonl` for the durable event stream
|
|
- `checkpoints/*.json` for checkpoint history snapshots
|
|
- `artifacts/{node_id}@{visit}/...` for exported artifact payloads
|
|
|
|
## Browsing runs
|
|
|
|
Use `fabro ps` to scan the scratch directory and display a table of all runs with their status, workflow name, and timestamps. Pass `--json` for machine-readable output.
|
|
|
|
```bash
|
|
fabro ps
|
|
fabro ps --json
|
|
fabro ps --filter workflow=my-workflow
|
|
```
|
|
|
|
## Full directory tree
|
|
|
|
```
|
|
~/.fabro/storage/scratch/
|
|
├── 20260307-01JQXYZ123ABC456DEF789/ # One directory per run
|
|
│ ├── workflow_bundle.json
|
|
│ ├── run.pid # Legacy only; older runs may contain this
|
|
│ ├── runtime/
|
|
│ │ └── blobs/
|
|
│ │ └── 01JT5Y3KJ0N5S9E1Y7YFBR2G4D.json
|
|
│ ├── cache/
|
|
│ │ └── artifacts/
|
|
│ │ └── files/
|
|
│ │ └── test/
|
|
│ │ └── retry_1/
|
|
│ │ ├── test-results/
|
|
│ │ │ └── screenshot.png
|
|
│ ├── nodes/
|
|
│ │ └── manager/
|
|
│ │ └── child/
|
|
│ │ ├── workflow_bundle.json
|
|
│ │ ├── runtime/
|
|
│ │ ├── cache/
|
|
│ │ └── worktree/
|
|
│ └── worktree/ # Git worktree (git checkpoint mode)
|
|
```
|