diff --git a/.ai/prompts/code-review-deep-1.md b/.ai/prompts/code-review-deep-1.md
deleted file mode 100644
index c15a499b6..000000000
--- a/.ai/prompts/code-review-deep-1.md
+++ /dev/null
@@ -1,35 +0,0 @@
-Provide a code review for this branch relative to the base branch for bugs and defects.
-
-To do this, follow these steps precisely:
-
-1. Use Git to retrieve a list of modified files in this branch.
-2. Use a Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files the pull request modified
-3. Use a Haiku agent to view the branch's diff, and ask the agent to return a summary of the change
-4. Then, launch 5 parallel Opus agents to independently code review the change for production bugs and vulnerabilities.
- a. Agent #1: Read the git blame and history of the code modified, to identify any bugs in light of that historical context
- b. Agent #2: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
- c. Agent #3-5: Read the file changes in this branch, then do a scan for potential bugs. Focus on bugs with production / end-user impact, and avoid small issues and nitpicks.
-
-Output a report with all the bugs using this format:
-
-
-
- title of bug
- brief description of bug
-
- lib/apps/fabro-cli/src/commands/resume.rs
- 115
- 115
-
- critical/high/medium/low
-
- ...
-
-
-Write the report to: `.ai/tmp/candidate_bugs.xml`
-
-Notes:
-
-- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
-- Include all potential bugs of all severity (critical/high/medium/low) that have production / end-user impact. (We will analyze them separately later.)
-- Make a todo list first
\ No newline at end of file
diff --git a/.ai/prompts/code-review-deep-2.md b/.ai/prompts/code-review-deep-2.md
deleted file mode 100644
index aa7000436..000000000
--- a/.ai/prompts/code-review-deep-2.md
+++ /dev/null
@@ -1,110 +0,0 @@
-Provide a code review for this branch relative to the base branch for bugs and defects.
-
-We have a report of candidate bugs which you need to analyze.
-
-To do this, follow these steps precisely:
-
-1. Use Git to retrieve a list of modified files in this branch.
-2. View the branch's diff and understand the changes
-3. Then, launch 5 parallel Opus agents to independently assess the candidate bugs. For each bug, investigate it thoroughly in order to produce the report in the format below. If the candidate bug is not valid, then discard it.
-
-Input: Read from `.ai/tmp/candidate_bugs.xml`
-
-Output a report with all the bugs using this format:
-
-```xml
-
-
- up to 3 sentences
- important OR nit
- yes OR no
-
- lib/apps/fabro-cli/src/commands/resume.rs
- 115
- 115
-
-
- ...
- ...
- ...
- ...
- ...
-
- first step
- second step
- ...
- bug
-
-
-
- ...
-
-```
-
-Here is a real-world example:
-
-```xml
-
-
- `prepare_from_checkpoint` unconditionally creates a `LocalSandbox` via `local_sandbox_with_callback`, completely ignoring the `--sandbox` flag and TOML config. A user running `fabro resume --checkpoint logs/checkpoint.json --workflow w.fabro --sandbox docker` will silently get a local sandbox instead of Docker; to fix this, call `resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)` just as `prepare_from_branch` does.
-
- important
- no
-
- lib/apps/fabro-cli/src/commands/resume.rs
- 208
- 208
-
-
-
- `prepare_from_checkpoint` (resume.rs, around line 196) always wires up a `LocalSandbox` regardless of what sandbox the caller requested:
-
- ```rust
- let sandbox: Arc = local_sandbox_with_callback(original_cwd, Arc::clone(&emitter));
- let sandbox: Arc = Arc::new(fabro_agent::ReadBeforeWriteSandbox::new(sandbox));
- ```
-
- The `args.sandbox` field (a `Option`) is populated by clap but never read inside this function. No error is raised and no warning is printed.
-
-
- When a user invokes `fabro resume --checkpoint path/to/checkpoint.json --workflow w.fabro --sandbox docker`, `resume_command` sees `args.checkpoint.is_some()` and dispatches to `prepare_from_checkpoint`. That function builds the `ResumeContext` with a `LocalSandbox` and returns. The `--sandbox docker` value stored in `args.sandbox` is forwarded to `run_resumed` but by then the sandbox is already constructed and the field is never consulted.
-
-
- `prepare_from_branch` — the sibling function for the run-ID path — correctly calls `resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)` and dispatches through a `match sandbox_provider { ... }` that handles `Local`, `Docker`, `Ssh`, `Exe`, and `Daytona`. The checkpoint-file path was clearly authored separately and the sandbox resolution step was simply omitted. Additionally, the old `fabro run --resume checkpoint.json --sandbox docker` path ran through `run_command`, which performed sandbox resolution before the checkpoint branch — so this is a genuine regression of a previously-working feature.
-
-
- Any user relying on `--sandbox docker` (for reproducibility, filesystem isolation, or container-specific tooling), `--sandbox ssh` (remote host execution), or `--sandbox exe` when resuming from a checkpoint file will silently run against the local filesystem instead. There is no error, no warning, and the job may produce different results or corrupt local state. The flag is prominently documented in both `docs/reference/cli.mdx` and the `--help` output, so users have every reason to expect it to work.
-
-
- Replace the hardcoded `local_sandbox_with_callback` call in `prepare_from_checkpoint` with the same sandbox-resolution logic used by `prepare_from_branch`:
-
- ```rust
- let sandbox_provider = if args.dry_run {
- SandboxProvider::Local
- } else {
- resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)?
- };
- // then match sandbox_provider { ... } as prepare_from_branch does
- ```
-
- Note that `run_defaults` must also be threaded into `prepare_from_checkpoint` (currently it is not passed to this function), matching the signature of `prepare_from_branch`.
-
-
- User runs: `fabro resume --checkpoint ~/.fabro/runs/20260321-01ABC.../checkpoint.json --workflow deploy.fabro --sandbox docker`
- `resume_command` evaluates `args.checkpoint.is_some()` → `true` → calls `prepare_from_checkpoint(&args, ...)`.
- Inside `prepare_from_checkpoint`, `args.sandbox` holds `Some(CliSandboxProvider::Docker)` but is never read.
- Line ~196: `let sandbox = local_sandbox_with_callback(original_cwd, Arc::clone(&emitter));` — a `LocalSandbox` is constructed unconditionally.
- `ResumeContext { sandbox, ... }` is returned with the local sandbox.
- `run_resumed` receives this context and runs the entire workflow inside the local sandbox.
- Docker is never launched; no diagnostic message is emitted.
-
-
-
-```
-
-Write the output to `.ai/tmp/analyzed_bugs.xml`
-
-Notes:
-
-- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
-- Make a todo list first
\ No newline at end of file
diff --git a/.ai/prompts/code-review-deep-3.md b/.ai/prompts/code-review-deep-3.md
deleted file mode 100644
index b0b4a272b..000000000
--- a/.ai/prompts/code-review-deep-3.md
+++ /dev/null
@@ -1,33 +0,0 @@
-Filter the bugs identified by code review to the bugs worth fixing.
-
-We have a report of analyzed bugs which you need to filter.
-
-To do this, follow these steps precisely:
-
-1. Use Git to retrieve a list of modified files in this branch.
-2. Use a Haiku agent to view the branch's diff, and ask the agent to return a summary of the change
-3. For each bug assess if it is a false positive based on the criteria below.
-
-Input: Read from `.ai/tmp/analyzed_bugs.xml`
-
-Filter out the false positives. Examples of false positives:
-
-- Nits
-- Something that looks like a bug but is not actually a bug
-- Pedantic issues that a senior engineer wouldn't call out
-- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
-- General code quality issues (eg. lack of test coverage, general security issues, poor documentation)
-- Maintainability, code smells, etc.
-- Changes in functionality that are likely intentional or are directly related to the broader change
-- Real issues, but are not related to the changes in the branch
-
-Ouput:
-
-1. Write to `.ai/tmp/valid_bugs.xml` in the same XML format with the false positives filtered out.
-2. Write to `.ai/tmp/false_positives.md` a summary of the false positives you filtered out and why.
-
-Notes:
-
-- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
-- Make a todo list first
-- It is OK to keep bugs which are pre-existing, if and only if they are both A) important and B) relevant to the changes being made.
diff --git a/.ai/prompts/code-review-fast.md b/.ai/prompts/code-review-fast.md
deleted file mode 100644
index b26ba8b64..000000000
--- a/.ai/prompts/code-review-fast.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*)
-description: Code review a pull request
-disable-model-invocation: false
----
-
-Provide a code review for the given pull request.
-
-To do this, follow these steps precisely:
-
-1. Use a Haiku agent to check if the pull request (a) is closed, (b) is a draft, (c) does not need a code review (eg. because it is an automated pull request, or is very simple and obviously ok), or (d) already has a code review from you from earlier. If so, do not proceed.
-2. Use another Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files the pull request modified
-3. Use a Haiku agent to view the pull request, and ask the agent to return a summary of the change
-4. Then, launch 5 parallel Sonnet agents to independently code review the change. The agents should do the following, then return a list of issues and the reason each issue was flagged (eg. CLAUDE.md adherence, bug, historical git context, etc.):
- a. Agent #1: Audit the changes to make sure they compily with the CLAUDE.md. Note that CLAUDE.md is guidance for Claude as it writes code, so not all instructions will be applicable during code review.
- b. Agent #2: Read the file changes in the pull request, then do a shallow scan for obvious bugs. Avoid reading extra context beyond the changes, focusing just on the changes themselves. Focus on large bugs, and avoid small issues and nitpicks. Ignore likely false positives.
- c. Agent #3: Read the git blame and history of the code modified, to identify any bugs in light of that historical context
- d. Agent #4: Read previous pull requests that touched these files, and check for any comments on those pull requests that may also apply to the current pull request.
- e. Agent #5: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
-5. For each issue found in #4, launch a parallel Haiku agent that takes the PR, issue description, and list of CLAUDE.md files (from step 2), and returns a score to indicate the agent's level of confidence for whether the issue is real or false positive. To do that, the agent should score each issue on a scale from 0-100, indicating its level of confidence. For issues that were flagged due to CLAUDE.md instructions, the agent should double check that the CLAUDE.md actually calls out that issue specifically. The scale is (give this rubric to the agent verbatim):
- a. 0: Not confident at all. This is a false positive that doesn't stand up to light scrutiny, or is a pre-existing issue.
- b. 25: Somewhat confident. This might be a real issue, but may also be a false positive. The agent wasn't able to verify that it's a real issue. If the issue is stylistic, it is one that was not explicitly called out in the relevant CLAUDE.md.
- c. 50: Moderately confident. The agent was able to verify this is a real issue, but it might be a nitpick or not happen very often in practice. Relative to the rest of the PR, it's not very important.
- d. 75: Highly confident. The agent double checked the issue, and verified that it is very likely it is a real issue that will be hit in practice. The existing approach in the PR is insufficient. The issue is very important and will directly impact the code's functionality, or it is an issue that is directly mentioned in the relevant CLAUDE.md.
- e. 100: Absolutely certain. The agent double checked the issue, and confirmed that it is definitely a real issue, that will happen frequently in practice. The evidence directly confirms this.
-6. Filter out any issues with a score less than 80. If there are no issues that meet this criteria, do not proceed.
-7. Use a Haiku agent to repeat the eligibility check from #1, to make sure that the pull request is still eligible for code review.
-8. Finally, use the gh bash command to comment back on the pull request with the result. When writing your comment, keep in mind to:
- a. Keep your output brief
- b. Avoid emojis
- c. Link and cite relevant code, files, and URLs
-
-Examples of false positives, for steps 4 and 5:
-
-- Pre-existing issues
-- Something that looks like a bug but is not actually a bug
-- Pedantic nitpicks that a senior engineer wouldn't call out
-- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
-- General code quality issues (eg. lack of test coverage, general security issues, poor documentation), unless explicitly required in CLAUDE.md
-- Issues that are called out in CLAUDE.md, but explicitly silenced in the code (eg. due to a lint ignore comment)
-- Changes in functionality that are likely intentional or are directly related to the broader change
-- Real issues, but on lines that the user did not modify in their pull request
-
-Notes:
-
-- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
-- Use `gh` to interact with Github (eg. to fetch a pull request, or to create inline comments), rather than web fetch
-- Make a todo list first
-- You must cite and link each bug (eg. if referring to a CLAUDE.md, you must link it)
-- For your final comment, follow the following format precisely (assuming for this example that you found 3 issues):
-
----
-
-### Code review
-
-Found 3 issues:
-
-1. (CLAUDE.md says "<...>")
-
-
-
-2. (some/other/CLAUDE.md says "<...>")
-
-
-
-3. (bug due to )
-
-
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
-- If this code review was useful, please react with 👍. Otherwise, react with 👎.
-
----
-
-- Or, if you found no issues:
-
----
-
-### Code review
-
-No issues found. Checked for bugs and CLAUDE.md compliance.
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-
-- When linking to code, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/claude-cli-internal/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15
- - Requires full git sha
- - You must provide the full sha. Commands like `https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar` will not work, since your comment will be directly rendered in Markdown.
- - Repo name must match the repo you're code reviewing
- - # sign after the file name
- - Line range format is L[start]-L[end]
- - Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to `L4-7`)
\ No newline at end of file
diff --git a/.chisel/calibration/work/adjudication.md b/.chisel/calibration/work/adjudication.md
deleted file mode 100644
index 8f3f7bb28..000000000
--- a/.chisel/calibration/work/adjudication.md
+++ /dev/null
@@ -1,249 +0,0 @@
-# Calibration Adjudication
-
-Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-Cartography: v1 at `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`.
-The only later commit adds cartography artifacts, so the mapped code paths are
-unchanged at the assessed revision.
-
-Sample: `fabro-workflow`, `fabro-http`, `fabro-web-app`, `repository-ci`.
-Control: `fabro-checkpoint`.
-
-## Independent Score Matrix
-
-Cells list reviewer 1 / reviewer 2 / reviewer 3.
-
-| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
-|---|---:|---:|---:|---:|
-| `fabro-workflow` | 2 / 3 / 4 | 2 / 2 / 2 | 2 / 3 / 2 | 2 / 2 / 2 |
-| `fabro-http` | 4 / 4 / 4 | 4 / 4 / 4 | 4 / 3 / 4 | 3 / 4 / 4 |
-| `fabro-web-app` | 4 / 4 / 3 | 2 / 2 / 2 | 2 / 2 / 2 | 2 / 2 / 2 |
-| `repository-ci` | 4 / 4 / 3 | 3 / 3 / 3 | 2 / 3 / 2 | 2 / 2 / 2 |
-
-Unanimous pairs establish that central machinery may still have a stable path:
-`fabro-workflow` is 2 for simplicity and duplication; `fabro-web-app` is 2 for
-simplicity, domain model, and duplication; and `repository-ci` is 3 for
-simplicity and 2 for duplication. `fabro-http` is unanimously 4 for ownership
-and simplicity.
-
-## Material Disagreements
-
-### `fabro-workflow` × ownership and boundaries — 2 / 3 / 4
-
-- **Evidence:** `pipeline/mod.rs` and `pipeline/types.rs` give the normal run
- explicit phase owners; `lifecycle/mod.rs:WorkflowLifecycle` owns callback
- ordering through focused delegates.
-- **Counterevidence:** terminal completion and failure are also constructed in
- `pipeline/finalize.rs:build_terminal_event`,
- `operations/start.rs:emit_workflow_run_failed`,
- `operations/start.rs:persist_terminal_engine_failure`, completion/drop
- guards, retry, and archive operations.
-- **Ambiguous rule:** two reviewers judged the clear normal path; one judged
- whether the same lifecycle has one home across normal and exceptional paths.
-- **Discriminator:** inspect every recurring terminal path. A routine
- terminal-contract change crossing several operation owners is score-2
- ownership pressure even when the success path is well partitioned.
-- **Draft adjudication:** 2.
-
-### `fabro-workflow` × domain model — 2 / 3 / 2
-
-- **Evidence:** `pipeline/types.rs` encodes phase states and canonical product
- records are reused.
-- **Counterevidence:** `event/events.rs:Event::StageCompleted` carries a string
- status; `lifecycle/event.rs:EventLifecycle::after_node` serializes a typed
- outcome and `event/convert.rs:stage_status_from_string` reparses it with an
- unknown-value fallback.
-- **Ambiguous rule:** whether a typed durable event isolates an invalid
- intermediate representation on the common producer path.
-- **Discriminator:** common-path invalid intermediate states are central even
- when the durable result is typed.
-- **Draft adjudication:** 2.
-
-### `fabro-http` × domain model — 4 / 3 / 4
-
-- **Evidence:** `ProxyPolicy`, `resolve_with_env_value`, and
- `HttpClientBuildError` form a closed policy with explicit precedence and
- rejection.
-- **Counterevidence:** public builders expose both
- `proxy_policy(ProxyPolicy::Disabled)` and lower-level `no_proxy()`.
-- **Ambiguous rule:** whether a lower-level transport control creates a second
- meaning for the repository policy.
-- **Discriminator:** an escape hatch does not split the canonical concept when
- the typed policy remains closed and its precedence is enforced.
-- **Draft adjudication:** 4.
-
-### `fabro-http` × duplication of knowledge — 3 / 4 / 4
-
-- **Evidence:** `define_builder!` is the shared async/blocking authority and
- `ProxyPolicy::resolve` owns precedence.
-- **Counterevidence:** adding a policy variant synchronizes the enum, parser,
- expected-value error text, behavior match, and tests.
-- **Ambiguous rule:** whether co-location and exhaustive matching make all
- policy vocabulary authoritative.
-- **Discriminator:** hypothetical variants do not establish routine
- recurrence; exhaustive compiler-checked behavior remains one authority
- unless direct evidence shows recurring manual synchronization.
-- **Draft adjudication:** 4.
-
-### `fabro-web-app` × ownership and boundaries — 4 / 4 / 3
-
-- **Evidence:** `entry.tsx`, route graphs, `lib/api-client.ts`, queries,
- mutations, effect hooks, and the build script give shared responsibilities
- visible homes.
-- **Counterevidence:** `install-app.tsx` and `routes/run-stages.tsx` contain
- several central transformations and presentation concerns.
-- **Ambiguous rule:** whether a busy but clearly identified route owner is
- boundary pressure or simplicity pressure.
-- **Discriminator:** do not lower ownership for internal complexity unless
- routine changes cross another owner or reverse the mapped dependency
- direction.
-- **Draft adjudication:** 4.
-
-### `repository-ci` × ownership and boundaries — 4 / 4 / 3
-
-- **Evidence:** Rust and TypeScript workflows have distinct validation jobs,
- narrow permissions, and delegate build procedures to repository commands.
-- **Counterevidence:** the Rust clippy job embeds the repository's legacy-auth
- vocabulary check.
-- **Ambiguous rule:** whether enforcement of a product migration invariant is
- misplaced when CI owns validation but not the underlying vocabulary.
-- **Discriminator:** a named invariant check may live in CI, but its product
- vocabulary must remain authoritative elsewhere; this isolated boundary
- friction fits 3.
-- **Draft adjudication:** 3.
-
-### `repository-ci` × domain model — 2 / 3 / 2
-
-- **Evidence:** job, runner, permission, and test-mode vocabulary is otherwise
- coherent.
-- **Counterevidence:** `rust.yml:on.*.paths` names nonexistent `openapi/**`
- rather than `docs/public/api-reference/fabro-api.yaml`, and
- `zizmor.yml:rules.stale-action-refs.ignore` identifies exceptions by stale
- line positions.
-- **Ambiguous rule:** whether configuration references are domain vocabulary
- or only duplicated operational data.
-- **Discriminator:** identifiers that control central behavior are domain
- vocabulary; missing or stale referents create score-2 pressure.
-- **Draft adjudication:** 2.
-
-## Draft Anchor Decisions
-
-- Anchor score 4 on a positive enforcing mechanism, never absence of a defect.
-- Separate owner clarity from the amount of machinery inside that owner.
-- Treat invalid common-path intermediate states as domain-model pressure.
-- Treat repeated semantic decisions as duplication only when routine changes
- require manual synchronization.
-- Treat mapped configuration identifiers as domain vocabulary.
-- Reserve N/E for a lens without direct evidence; no sampled pair required it.
-
-## Consistency Review
-
-The fresh reviewer applied only the written draft to `fabro-checkpoint` and
-reported:
-
-| Lens | Score | Evidence confidence |
-|---|---:|---|
-| Ownership and boundaries | 2 | Medium |
-| Simplicity | 3 | High |
-| Domain model | 2 | High |
-| Duplication of knowledge | 2 | High |
-
-The control exposed four material wording problems:
-
-1. The draft did not say how a component-level score combines several
- responsibilities, or whether positive mechanisms and friction can coexist
- at score 4.
-2. Necessary layered delegation could satisfy the original ownership and
- simplicity score-2 wording.
-3. The domain rules did not say when a public low-level API is an escape hatch
- or what score a common invalid intermediate implies.
-4. Decision rule 5 contradicted the duplication anchor by assigning routine
- string synchronization to score 3.
-
-The revision now says that a central concern caps rather than averages, score 4
-requires a positive production mechanism without material friction, public
-surface alone does not establish routine work, and missing paths are not
-negative without mapped-purpose evidence. The anchors now distinguish competing
-owners from necessary delegation and maintainer navigation from runtime
-layering. Decision rules 2–6 resolve scoped lifecycle handoff, necessary
-delegation, common-path invalid states, direct evidence of recurring
-synchronization, and configuration identifiers. Tests corroborate production
-authorities but are not second authorities merely because they restate a
-contract.
-
-All 16 wording observations in `consistency-review.md` are covered by those
-changes or by the existing primary-lens and confidence sections. No consistency
-objection remains open before validation.
-
-## Validation
-
-### Round 1
-
-| Assignment | Validator 1 | Validator 2 | Validator 3 | Result |
-|---|---:|---:|---:|---|
-| `fabro-workflow` × ownership | 2 | 2 | 2 | Resolved |
-| `fabro-workflow` × domain | 2 | 2 | 2 | Resolved |
-| `fabro-http` × domain | 4 | 4 | 4 | Resolved |
-| `fabro-http` × duplication | 4 | 4 | 3 | Repeated adjacent split |
-| `fabro-web-app` × ownership | 4 | 4 | 4 | Resolved |
-| `repository-ci` × ownership | 4 | 2 | 4 | Non-adjacent split |
-| `repository-ci` × domain | 2 | 2 | 2 | Resolved |
-| Control × ownership | 2 | 4 | 2 | Non-adjacent split |
-| Control × simplicity | 4 | 4 | 3 | Adjacent split |
-| Control × domain | 2 | 3 | 2 | Adjacent split |
-| Control × duplication | 3 | 2 | 3 | Adjacent split |
-
-The sample's workflow lifecycle, event status, HTTP policy model, web
-composition, and CI identifier anchors now converge. Six assignments require
-the permitted final simplification:
-
-- HTTP diagnostic allowed-value text is a concrete second semantic
- representation, even though the macro is the behavioral authority.
-- A CI check owns trigger coverage for every path its embedded policy scans;
- this is distinct from the domain meaning of a nonexistent selector.
-- Control ownership is judged against the mapped metadata-branch purpose, not
- against narrower names on `Store` and `BranchStore`.
-- The control's unused dependency and unused parallel entry layer are isolated
- simplicity friction rather than evidence-free public breadth.
-- Validation in an external caller does not make an invalid-capable mapped
- entry type enforce its own legal shape.
-- Repeated fixed Git protocol syntax is a concrete second representation, but
- multiple current call sites alone do not make changing that protocol an
- ordinary mapped change.
-
-Decision rules 2–6 now state those discriminators directly. Round 2 will
-re-score only the six unresolved assignments.
-
-### Round 2
-
-| Assignment | Validator 1 | Validator 2 | Validator 3 | Result |
-|---|---:|---:|---:|---|
-| `fabro-http` × duplication | 3 | 3 | 3 | Resolved |
-| `repository-ci` × ownership | 2 | 2 | 2 | Resolved |
-| Control × ownership | 2 | 2 | 2 | Resolved |
-| Control × simplicity | 3 | 3 | 3 | Resolved |
-| Control × domain | 2 | 2 | 2 | Resolved |
-| Control × duplication | 3 | 3 | 3 | Resolved |
-
-All round-2 scores converge. The final control baseline is ownership 2
-(High), simplicity 3 (High), domain model 2 (Medium), and duplication of
-knowledge 3 (Medium). Domain confidence remains Medium because one validator
-found a material ambiguity over whether low-level Git path validation belongs
-inside the component. Duplication confidence remains Medium because stable
-protocol syntax is concrete repetition but has limited demonstrated change
-burden.
-
-Across both validation rounds, the final disputed sample scores are:
-
-| Component | Ownership and boundaries | Domain model | Duplication of knowledge |
-|---|---:|---:|---:|
-| `fabro-workflow` | 2 | 2 | — |
-| `fabro-http` | — | 4 | 3 |
-| `fabro-web-app` | 4 | — | — |
-| `repository-ci` | 2 | 2 | — |
-
-No non-adjacent or repeated adjacent split remains.
-
-## Open Questions
-
-None.
diff --git a/.chisel/calibration/work/consistency-review.md b/.chisel/calibration/work/consistency-review.md
deleted file mode 100644
index e41ff2c26..000000000
--- a/.chisel/calibration/work/consistency-review.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Chisel Consistency Review: `fabro-checkpoint`
-
-Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-Scope: `lib/components/fabro-checkpoint/**` only. The scored evidence is the manifest, production source, and unit tests at the pinned revision. I did not inspect callers, sample reviews, adjudication, or any other file under `.chisel/calibration/work/`.
-
-## Scores
-
-| Lens | Score | Confidence |
-|---|---:|---|
-| `ownership-boundaries` | 2 | Medium |
-| `simplicity` | 3 | High |
-| `domain-model` | 2 | High |
-| `duplication-knowledge` | 2 | High |
-
-Confidence here describes this reading's evidence quality. The rubric's additional requirement that a final High confidence needs independent convergence can only be decided during adjudication.
-
-## `ownership-boundaries`: 2
-
-The central branch lifecycle crosses two public owners. `BranchStore` stores the branch name and owns bootstrap plus normal branch reads and writes (`branch.rs:20-209`), but branch cleanup is exposed only as `Store::delete_ref(branch)` (`git.rs:215-226`). `BranchStore` keeps both its `Store` reference and branch name private and has no cleanup/archive operation. A caller therefore has to retain the same raw branch identity and leave the branch-scoped interface for cleanup. Bootstrap sequencing is also caller-owned: `BranchStore::new` does not establish the branch, writes fail when it is absent, and every writable test explicitly calls `ensure_branch` first (`branch.rs:26-81, 282-343`). This is recurring lifecycle work rather than an isolated edge, especially under decision rule 1. Primary tags: `lifecycle`, `ownership`.
-
-Strongest counterevidence: once initialized, `BranchStore::write_with` keeps the read-modify-write sequence together and delegates only Git object/ref primitives to `Store` (`branch.rs:56-82`). The dependency direction is stable: branch storage depends on the lower-level Git store, not vice versa.
-
-Why adjacent scores do not fit:
-
-- **1 does not fit:** `BranchStore` is a stable, identifiable owner for the common branch-scoped read/write responsibility, and `Store` is a coherent lower-level Git owner.
-- **3 does not fit:** the split includes explicit bootstrap and cleanup paths. Decision rule 1 says recurring terminal ownership cannot be treated as isolated merely because the success path is clear.
-
-Confidence is Medium because the split is direct, but the scoped evidence cannot show whether archive, retry, and cleanup are deliberately owned by a higher-level caller.
-
-## `simplicity`: 3
-
-The common write path is directly traceable: `write_entry`/`write_entries` prepare blobs, `write_with` reads the tip tree, applies one mutation, writes one commit, and advances one ref (`branch.rs:56-109`). `Store::read_tree` and `Store::write_tree` use a single flat `TreeEntries` representation with private recursive helpers (`git.rs:39-99, 141-159, 229-310`). These are positive reinforcing mechanisms, not just an absence of complexity.
-
-The remaining simplicity pressure is isolated configuration burden. The manifest declares `fabro-store`, `serde`, and the dev dependency `chrono` (`Cargo.toml:16-28`), but none is referenced anywhere in the component source or tests at this revision. The public `Store::repo` escape hatch (`git.rs:112-114`) and the lower-level object API also add surface area, but normal branch writes do not have to choose among competing implementations. Primary tag: `configuration-sprawl`.
-
-Strongest counterevidence to lowering the score: the component has one linear common mutation path, and its indirection corresponds directly to Git's blob/tree/commit/ref structure.
-
-Why adjacent scores do not fit:
-
-- **2 does not fit:** ordinary reads and writes do not repeatedly traverse competing orchestration paths or configuration machinery; the `BranchStore` to `Store` layering is stable and direct.
-- **4 does not fit:** the centralized mutation path is a qualifying positive mechanism, but the unused manifest dependencies are concrete unnecessary configuration rather than necessary machinery.
-
-Confidence is High because all component files are in scope, so the dependency non-use and the full common write path are directly observable.
-
-## `domain-model`: 2
-
-The common tree-entry producer accepts invalid intermediate path states. `TreeEntries` hides its map, but its public `set` accepts any `Into` without validating a relative Git path (`git.rs:46-61`). Both `BranchStore::write_entry` and `write_entries` feed caller-provided `&str` paths directly into it (`branch.rs:84-109`), and `build_dir_node` later assigns meaning by splitting the strings on `/` (`git.rs:270-294`). Empty components, leading/trailing separators, and file/directory prefix collisions are therefore representable in the canonical intermediate type and reach late Git-tree construction rather than being rejected at the common boundary. Branch identity is likewise an arbitrary `String` until `git2` receives the synthesized ref name (`branch.rs:20-38`, `git.rs:182-197`). This is central invalid-state pressure under decision rule 3, not an isolated low-level escape hatch. Primary tag: `invalid-states`.
-
-The small helper `sharded_path` is corroborating boundary evidence: its contract says the input is a hex ID, but its public signature accepts any `&str` and slices at a caller-provided byte offset (`branch.rs:211-220`), so a non-ASCII input can panic rather than be rejected as invalid input.
-
-Strongest counterevidence: `FileMode` is a closed enum and `TreeEntries` keeps ordering and representation private (`git.rs:13-99`). `Error` also distinguishes a missing branch from generic Git failures (`error.rs:5-18`). The component therefore has stable concepts even though common constructors do not preserve all their invariants.
-
-Why adjacent scores do not fit:
-
-- **1 does not fit:** branch storage, tree entries, file modes, authors, and trailers all have recognizable, stable meanings.
-- **3 does not fit:** raw paths and branch names enter the common public read/write boundary, so validation friction is not isolated outside routine use.
-
-Confidence is High because the accepting producers and their downstream interpretation are both visible within the scoped common path.
-
-## `duplication-knowledge`: 2
-
-The transformation “find a path in a commit tree, treat only `NotFound` as absence, load the entry as a blob, and copy its bytes” is independently implemented by `BranchStore::read_entry`, `BranchStore::read_entries`, and `Store::read_blob_at` (`branch.rs:119-158`, `git.rs:200-213`). An ordinary maintenance change to missing-entry or entry-kind behavior must synchronize all three common read locations. Ref qualification is also repeated in `update_ref`, `resolve_ref`, and `delete_ref` (`git.rs:182-226`).
-
-Trailer grammar supplies independent corroboration at the commit-message edge: `": "` formatting/detection is separately encoded by `append`, `parse`, `format_message`, and `has_trailing_trailer_block` (`trailer.rs:9-25, 28-42, 45-65, 68-87`). Primary tags: `repeated-transformation`, `repeated-policy`.
-
-Strongest counterevidence: important write knowledge is authoritative. `BranchStore::write_with` centralizes tip loading, parent linkage, commit creation, and ref advancement, while `GitAuthor::default` centralizes the fallback identity (`branch.rs:56-82`, `author.rs:13-35`).
-
-Why adjacent scores do not fit:
-
-- **1 does not fit:** the repeated implementations currently agree, and stable authorities exist for branch mutation, author defaults, and file-mode conversion.
-- **3 does not fit:** the repeated blob-read transformation appears on the public latest-entry and multi-entry common paths, so a routine storage-policy change encounters it centrally rather than only at an edge.
-
-Confidence is High because the repeated transformations and the mechanisms that are already centralized can both be enumerated completely inside the scoped component.
-
-## Rubric wording audit
-
-The following rules or anchors were ambiguous or non-discriminating in this application. I resolved each explicitly rather than silently choosing an interpretation.
-
-1. **One component score across several responsibilities.** The instruction says to judge “each mapped component,” while the anchors use singular phrases such as “a mapped responsibility” and “a core concept.” It does not say whether to average sub-responsibilities, take the worst concern, or weight by centrality. I scored the mapped checkpoint-storage responsibility and let a directly evidenced central concern cap the lens; isolated author/trailer helpers could affect a score only at 3 versus 4.
-
-2. **How to establish “routine” and “central” with component-only evidence.** A public method may be a mapped entry point without being frequent, and scoped evidence cannot establish caller frequency. I treated bootstrap, latest reads/writes, and cleanup as routine because they are ordinary lifecycle operations implied by branch storage. I did not infer frequency for unrelated external call sites.
-
-3. **N/E threshold versus an absent lifecycle path.** “Use N/E when evidence is insufficient” does not say whether a missing archive/retry API is negative evidence, out of scope, or grounds for N/E. I scored paths that are directly present (bootstrap, normal operation, cleanup), did not penalize an unobserved archive/retry design, and lowered ownership confidence for the coverage gap.
-
-4. **Score 3 and score 4 overlap in every lens.** A positive reinforcing mechanism can coexist with isolated friction, so the score-4 requirement and score-3 anchor can both be true. I treated any evidenced unnecessary/frictional mechanism as a cap at 3; score 4 requires both a positive mechanism and no material friction in the mapped responsibility. This is why the unused manifest dependencies keep simplicity at 3 despite `write_with`.
-
-5. **What qualifies as a “positive reinforcing mechanism.”** The rubric does not say whether tests, encapsulation alone, or a production authority qualifies. I required an operative production mechanism that funnels behavior or rejects invalid construction. Tests alone did not qualify.
-
-6. **Ownership score 2 versus ordinary delegation.** “Cross recurring owners or dependency boundaries” could penalize every layered implementation. Decision rule 2 partly resolves this, but “same responsibility” remains subjective. I treated `BranchStore` calling `Store` during a write as ordinary delegation; I counted cleanup only because the caller must leave the branch-scoped owner and supply its identity again.
-
-7. **Decision rule 1 when terminal operations live at a lower abstraction.** The rule says not to isolate recurring terminal owners but does not define whether a lower-level deletion primitive is a second owner or a delegate. Because `BranchStore` offers no cleanup interface and keeps the needed state private, I treated `Store::delete_ref` as a lifecycle-owner crossing, not merely internal machinery.
-
-8. **Simplicity score 2’s “repeatedly traverse.”** It is unclear whether this means runtime calls passing through multiple necessary layers, or maintainers choosing among competing paths repeatedly. I used the latter interpretation, consistent with the lens question and decision rule 2; necessary Git layers did not lower the score.
-
-9. **Decision rule 2’s “simplicity pressure.”** The rule labels machinery inside an owner as pressure even though the lens expressly permits necessary complexity and gives no score consequence for “pressure.” I treated machinery as evidence to test for necessity, not as an automatic deduction.
-
-10. **Domain score 4 versus decision rule 4’s escape hatch.** “Every common boundary” is not defined, and a public low-level API can be called common or an escape hatch depending on external usage. I treated `TreeEntries::set` as common because `BranchStore::write_with`, `write_entry`, and `write_entries` use it directly; `Store::repo` was treated as an escape hatch.
-
-11. **Decision rule 3 does not identify a score boundary.** It says a typed durable value does not “repair domain pressure,” but does not say whether a common invalid intermediate means 2 or merely prevents 4. I mapped common-path invalid intermediates to the score-2 anchor (“routine changes reconcile ... invalid intermediate states”); isolated invalid intermediates would map to 3.
-
-12. **Duplication score 2 versus decision rule 5.** Rule 5 says to score 3 when a routine vocabulary change requires synchronization, while the score-2 anchor says routine synchronization of the same policy/invariant/transformation is score 2. Those statements conflict unless “vocabulary” is an unstated special case. I treated rule 5 narrowly as an exception for localized, string-only vocabulary at an edge. The score-2 finding here rests instead on repeated behavioral blob-read transformations on common paths.
-
-13. **What test repetition counts as knowledge duplication.** The `repeated-test-knowledge` tag suggests tests can count, but the anchors do not distinguish duplicated policy from assertions that intentionally restate expected behavior. I did not count an assertion of a production contract as a second authority. Repeated test fixture setup was only isolated counterevidence and did not drive a numeric score.
-
-14. **Decision rule 6 lacks a lens and defines neither “current referent” nor “line selector.”** Its opening phrase points toward `domain-model`, while duplicated CI selectors could point toward `duplication-knowledge`; its mandatory score 2 also bypasses centrality analysis. It had no referent in this component, so I did not apply it. If applicable, I would classify a single invalid identifier under domain model and synchronized copies under duplication.
-
-15. **The “primary lens only” rule does not explain multi-causal facts.** Raw strings can simultaneously expose invalid states, repeat vocabulary, and force lifecycle handoffs. I assigned each negative fact once by its primary question: lifecycle handoff to ownership, unused dependencies to simplicity, raw path legality to domain, and repeated lookup/ref/trailer behavior to duplication.
-
-16. **Confidence High cannot be finalized by one reviewer.** “Final High also requires independent readings to converge” is not decidable during an independent review. I reported evidence-quality confidence now and left final convergence to adjudication.
-
-All other score-1 versus score-2 distinctions were discriminating here: the component consistently has identifiable owners, paths, concepts, and intended policies, so none of the “no stable ... can be identified” anchors fit.
diff --git a/.chisel/calibration/work/reviewer-1.md b/.chisel/calibration/work/reviewer-1.md
deleted file mode 100644
index d6c0140da..000000000
--- a/.chisel/calibration/work/reviewer-1.md
+++ /dev/null
@@ -1,182 +0,0 @@
-# Calibration review — reviewer 1
-
-Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-Scope: `fabro-workflow`, `fabro-http`, `fabro-web-app`, and `repository-ci` as routed by `.chisel/cartography/codebase-map.md`. I excluded `apps/fabro-web/app/components/playground/**` from `fabro-web-app`, and limited `repository-ci` to `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`. The routed paths have no changes between the map revision and the reviewed revision.
-
-## Provisional ratings
-
-| Component | Ownership boundaries | Simplicity | Domain model | Duplication of knowledge |
-| --- | --- | --- | --- | --- |
-| `fabro-workflow` | **2 — High** | **2 — High** | **2 — High** | **2 — High** |
-| `fabro-http` | **4 — High** | **4 — High** | **4 — High** | **3 — High** |
-| `fabro-web-app` | **4 — High** | **2 — High** | **2 — High** | **2 — High** |
-| `repository-ci` | **4 — High** | **3 — High** | **2 — High** | **2 — High** |
-
-## `fabro-workflow`
-
-### Ownership boundaries — 2, High confidence
-
-The component has a clear top-level phase boundary: `pipeline/mod.rs` orders parse, transform, validate, initialize, execute, finalize, and pull-request processing; `pipeline/types.rs` gives those phases distinct result types. `pipeline/execute.rs:execute`, `graph.rs:WorkflowGraph`, and `node_handler.rs:WorkflowNodeHandler` also make the boundary with the generic `fabro-core` executor explicit. `lifecycle/mod.rs:WorkflowLifecycle` composes named lifecycle owners instead of placing every callback in the executor.
-
-The pressure appears in terminal-run ownership. The normal path is owned by `pipeline/finalize.rs:finalize` and `pipeline/finalize.rs:build_terminal_event`, while engine/bootstrap failures are handled by `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, and the completion/drop guards in `operations/start.rs`. Retry and archive operations also synthesize terminal events in `operations/retry.rs` and `operations/archive.rs`. These paths are understandable individually, but terminal state, persistence, and event emission do not have one stable lifecycle home.
-
-A representative routine change is adding terminal metadata that must be present for every failed or concluded run. It would require checking or changing `pipeline/finalize.rs:build_terminal_event`, `pipeline/finalize.rs:finalize`, `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, the start-operation guards, and the corresponding terminal paths in `operations/retry.rs` and `operations/archive.rs`.
-
-Strongest counterevidence: the main successful-run path is explicit and strongly partitioned, and `WorkflowLifecycle` plus `RunServices` give many responsibilities named owners.
-
-Why adjacent scores do not fit: 3 understates the issue because terminal completion is a central lifecycle concern, not an edge-only exception; an ordinary terminal-contract change must inspect several authorities. 1 does not fit because the normal path and the exceptional paths are still traceable and deliberately named.
-
-### Simplicity — 2, High confidence
-
-The top-level flow is readable, but routine run startup crosses a large amount of central wiring. `operations/start.rs:start` enters `execute_persisted_run`, constructs `RunSession`, and then `RunSession::run` coordinates logging, SHA listeners, initialization, cleanup/drain guards, execution, finalization, and pull-request handling. `pipeline/types.rs:InitOptions` carries a large set of run inputs, and `operations/start.rs:RunSession::run` assembles them before handing control to `pipeline/initialize.rs`. The resulting services are then repartitioned through `services.rs:RunServices`, `services.rs:EngineServices`, and `pipeline/execute.rs:execute`.
-
-A representative routine change is adding a run-scoped service needed by node handlers. It would pass through `operations/start.rs:StartServices` or `RunSession`, `pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, `pipeline/types.rs:Initialized`, `services.rs:RunServices`, `services.rs:EngineServices`, and the destructuring/building in `pipeline/execute.rs:execute`.
-
-Strongest counterevidence: the phase result types in `pipeline/types.rs` and the extracted executor/lifecycle adapters make the long path navigable; the complexity is structured rather than accidental.
-
-Why adjacent scores do not fit: 3 does not fit because the pressure is on the common startup and execution path, and a small run-scoped dependency change propagates through several central handoff types. 1 does not fit because the ordered pipeline and named handoffs still provide a stable path through the component.
-
-### Domain model — 2, High confidence
-
-The strongest positive mechanism is the phase model in `pipeline/types.rs`: `Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` constrain which data exists at each stage. Canonical run records are reused from `fabro-types`, and `services.rs:RunServices` documents cancellation ownership.
-
-However, the core event path weakens those guarantees. `event/events.rs:Event::StageCompleted` carries `status: String`; lifecycle code such as `lifecycle/event.rs` converts `StageOutcome` to a string, and `event/convert.rs:stage_status_from_string` parses it back when creating the durable event. An unknown value is not rejected: it is warned about and converted to `StageOutcome::Failed`. The durable model in `fabro-types` is typed, but the internal central event model permits invalid status values and gives them a lossy fallback meaning. `WorkflowRunCompleted` similarly carries a string status internally.
-
-Strongest counterevidence: the durable event body and most run/pipeline records use named enums and phase-specific types, so this is not a component with generally unmodeled state.
-
-Why adjacent scores do not fit: 3 does not fit because stage and run outcomes are central workflow vocabulary used on every execution, and the internal-to-durable boundary permits and silently reinterprets invalid values. 1 does not fit because canonical typed outcomes exist and dominate downstream storage; the break is concentrated at the internal event boundary.
-
-### Duplication of knowledge — 2, High confidence
-
-Adding an event requires coordinated knowledge in several central authorities. The internal variant lives in `event/events.rs:Event`; its wire name is separately selected by `event/names.rs:event_name`; durable fields are declared in `fabro-types::EventBody`; conversion is implemented in `event/convert.rs:event_body_from_event`; stored-field behavior is selected in `event/stored_fields.rs:stored_event_fields_for_variant`; and tracing behavior is implemented on `Event`. `docs/internal/events-strategy.md` documents this multi-site procedure, confirming that this is the expected recurring event-evolution path rather than a one-off remnant.
-
-A representative routine change is adding a persisted workflow event. It touches `event/events.rs:Event`, `event/names.rs:event_name`, the `Event` tracing method, `fabro_types::EventBody`, `event/convert.rs:event_body_from_event`, `event/stored_fields.rs:stored_event_fields_for_variant`, emitters, and any event consumers.
-
-Strongest counterevidence: `event/emitter.rs:Emitter::emit_with_scope` constructs the canonical run event once before dispatch, exhaustive matches make omissions visible to the compiler, and the strategy document gives maintainers one checklist.
-
-Why adjacent scores do not fit: 3 does not fit because event evolution is frequent, central workflow work and requires synchronized changes across representations and crates. 1 does not fit because each representation has a stated role and there is a single canonicalization point before dispatch.
-
-Lens-boundary note: the internal `Event`/durable `EventBody` split could be described as a domain-model issue or duplication. I treated the repeated declarations and conversion sites as duplication of knowledge; the separate `String`-to-`StageOutcome` loss of meaning is the domain-model issue. Likewise, repeated terminal constructors are secondary duplication, but I classified the primary problem as ownership because the key question is which operation owns terminal lifecycle completion.
-
-## `fabro-http`
-
-### Ownership boundaries — 4, High confidence
-
-`lib/foundation/fabro-http/src/lib.rs` is a small, focused owner for HTTP client construction and proxy policy. Callers get approved async or blocking builders and convenience clients from this crate. Repository lint policy in `clippy.toml` disallows direct `reqwest` constructors and points callers to `fabro-http`, so the boundary is reinforced rather than merely conventional. `ProxyPolicy::resolve` also owns the environment-variable authority through `fabro_static::EnvVars::FABRO_HTTP_PROXY_POLICY`.
-
-Strongest counterevidence: the crate deliberately re-exports several `reqwest` types and carries lint exceptions for those facade exports, so callers are not isolated from every transport detail.
-
-Why adjacent scores do not fit: 3 does not fit because construction policy, environment precedence, test defaults, and transport facade all have one enforced home with no observed competing builder authority.
-
-### Simplicity — 4, High confidence
-
-The common path is short: choose `HttpClientBuilder` or `BlockingHttpClientBuilder`, optionally configure it, resolve `ProxyPolicy`, and build the underlying client. `define_builder!` generates the shared async/blocking surface once, while the async-only `read_timeout` extension remains plainly visible next to the macro invocation. Convenience functions such as `http_client`, `blocking_http_client`, `test_http_client`, and `blocking_test_http_client` expose the common cases directly.
-
-Strongest counterevidence: macro generation means the two concrete builder implementations are not visible as ordinary source, and async-only options must be added outside the shared definition.
-
-Why adjacent scores do not fit: 3 does not fit because the macro removes rather than creates routine common-option work: a shared builder option is added in one readable location, while the generated types remain thin wrappers.
-
-### Domain model — 4, High confidence
-
-`ProxyPolicy` names the only supported policies, `ProxyPolicy::parse` rejects unknown values, and `ProxyPolicy::resolve_with_env_value` makes precedence explicit: a caller override wins, then the environment value, then the system default. Test helpers force `Disabled`, making local test semantics deliberate. `HttpClientBuildError` distinguishes policy configuration failure from transport construction failure.
-
-Strongest counterevidence: callers can express no-proxy behavior through both `proxy_policy(ProxyPolicy::Disabled)` and the lower-level `no_proxy()` builder method, and the facade re-exports lower-level proxy types.
-
-Why adjacent scores do not fit: 3 does not fit because the overlapping entry points do not introduce an ambiguous stored state or silent fallback: the policy values and their precedence are explicit, and invalid environment vocabulary fails closed.
-
-### Duplication of knowledge — 3, High confidence
-
-The builder macro is a strong anti-duplication mechanism for async and blocking clients. The remaining policy vocabulary is manually repeated: `ProxyPolicy` variants, `ProxyPolicy::parse`, the expected-value text in `HttpClientBuildError::InvalidProxyPolicy`, and the policy match in the generated `build` method must agree.
-
-A representative routine change is adding another supported proxy policy. It would touch `ProxyPolicy`, `ProxyPolicy::parse`, the expected-value message on `HttpClientBuildError::InvalidProxyPolicy`, the `define_builder!` build-time match, and policy tests in the same source file.
-
-Strongest counterevidence: every repeated policy decision is co-located in one small file, and the exhaustive build match makes a missing behavioral branch a compile error.
-
-Why adjacent scores do not fit: 4 does not fit because the accepted vocabulary and error vocabulary are independently maintained strings. 2 does not fit because the synchronization is confined to one authority and does not force routine callers or neighboring components to change.
-
-Lens-boundary note: macro use could be counted as simplicity indirection, but its primary effect here is eliminating async/blocking duplication. The generated control flow is small enough that I did not lower simplicity for it.
-
-## `fabro-web-app`
-
-### Ownership boundaries — 4, High confidence
-
-The app has explicit composition points. `app/entry.tsx` selects normal or install mode and installs shared providers; `app/router.tsx` and `app/install-router.tsx` own the two route trees. `app/lib/api-client.ts` owns generated-client construction and uniform API errors, `app/lib/query-keys.ts` owns cache keys, and `app/lib/queries.ts` owns shared reads. The React effects policy is embodied by approved wrappers in `app/hooks/effects.ts`; direct effect usage is concentrated in hooks and live-event libraries rather than route/component bodies. `scripts/build.ts` separately owns deterministic asset building and atomic publication.
-
-Strongest counterevidence: some cache mutation and API-write coordination remains in route handlers, particularly in the large run and installation screens, so not every server interaction passes through a single application-service layer.
-
-Why adjacent scores do not fit: 3 does not fit because routing, reads, client configuration, effects, and build publication each have a visible and consistently used owner; route-local writes are appropriate UI orchestration rather than a competing global authority.
-
-### Simplicity — 2, High confidence
-
-The normal routing shell is simple, but two central screens concentrate substantial policy and presentation. `app/routes/run-stages.tsx` combines event-to-turn reduction, event filtering, grouping, stage/activity interpretation, row and panel rendering, stage renderer selection, and the route page. `app/install-app.tsx` similarly combines installation state transitions, controller behavior, forms, and view composition. Cross-tab stream coordination in `app/lib/cross-tab-sse.ts` is another large central mechanism.
-
-A representative routine change is showing a new kind of stage activity in the run timeline. It requires following `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES`, `app/routes/run-stages.tsx:STAGE_ACTIVITY_EVENT_SET`, `app/routes/run-stages.tsx:buildStageActivity`, the route's turn/activity types, and the corresponding render helpers in the same large route module.
-
-Strongest counterevidence: shared event lists, query keys, generated API types, and route helpers provide landmarks, and the activity reducer is deterministic rather than dispersed among many components.
-
-Why adjacent scores do not fit: 3 does not fit because run-stage interpretation is a common product path and small presentation changes require navigating large modules that mix reduction and rendering concerns. 1 does not fit because the route and install flows remain typed, testable, and traceable from explicit entry points.
-
-### Domain model — 2, High confidence
-
-Generated API types provide a strong canonical model for ordinary request/response queries, and several local models use discriminated unions. The live-event boundary is weaker. `app/lib/sse.ts:EventPayload` permits an optional event name plus arbitrary fields. `app/lib/run-events.ts:RunEventPayload` and `app/lib/live-events.ts:LiveEventPayload` repeat mostly optional envelope fields with `properties: unknown`. `app/lib/sse.ts:subscribeToSharedEventSource` parses JSON and casts it to the requested payload type without runtime validation. Common live UI behavior therefore accepts payloads that lack the fields implied by their event names.
-
-There is additional vocabulary translation in `app/data/runs.ts:RunStatus`, which locally reproduces API run-state kinds and adds presentation state, and compatibility shape probing in `app/lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance`.
-
-Strongest counterevidence: generated types remain the authority for normal API calls, `session-stream.ts` and query paths use generated event-envelope types where possible, and the local run status adds a genuine presentation concept rather than merely renaming every API state.
-
-Why adjacent scores do not fit: 3 does not fit because SSE drives common live run behavior and its central payload model makes invalid event/field combinations representable and unchecked. 1 does not fit because static generated models are sound and the weak representation is concentrated at live and compatibility boundaries.
-
-### Duplication of knowledge — 2, High confidence
-
-Live refresh policy is repeated in separate manually curated authorities. `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` lists events that invalidate run summaries, while `app/lib/board-events.ts:BOARD_STATUS_EVENTS` independently lists many of the same run, interview, and pull-request lifecycle events for board refresh. The duplicated payload interfaces in `run-events.ts` and `live-events.ts` add another synchronization surface.
-
-A representative routine change is adding a lifecycle event that changes both a run summary and its board status. It requires updating `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` and `app/lib/board-events.ts:BOARD_STATUS_EVENTS`, then checking phase derivation in `app/lib/run-phases.ts:deriveRunPhases` and live consumers if the event also changes the visible run phase.
-
-Strongest counterevidence: stage activity vocabulary is centralized in `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` and imported by the run-stages route; query keys and server contract types are also centralized or generated.
-
-Why adjacent scores do not fit: 3 does not fit because the repeated invalidation lists govern common live behavior, and a missing update produces stale UI rather than a compile-time failure. 1 does not fit because each list has a clear local purpose and several other high-change vocabularies already have a single authority.
-
-Lens-boundary note: the repeated loose live-event interfaces are both duplicate declarations and a weak model. I treated representable invalid payloads and unchecked casts as the domain-model finding; I used independently maintained event-invalidation sets as the primary duplication finding. The size of `run-stages.tsx` is primarily simplicity pressure, not evidence that its route ownership is unclear.
-
-## `repository-ci`
-
-### Ownership boundaries — 4, High confidence
-
-`.github/workflows/rust.yml` and `.github/workflows/typescript.yml` have an explicit language split and named jobs for formatting, linting, generated documentation, tests, type checking, and builds. Each workflow sets narrow permissions, concurrency behavior is visible, and toolchain/action versions are pinned. The TypeScript build job's Rust build step has a clear purpose: verify the embedded production SPA through the repository's actual build command.
-
-Strongest counterevidence: the Rust clippy job contains a repository-specific legacy-auth `git grep` policy check, rather than delegating that policy to a named script or dedicated job.
-
-Why adjacent scores do not fit: 3 does not fit because the special check is still plainly owned by repository validation, while language-level checks, permissions, and production build validation have unambiguous homes and no competing workflow was observed.
-
-### Simplicity — 3, High confidence
-
-The workflows are short and linear, with direct commands corresponding to local development commands. Friction is isolated: setup steps are repeated across jobs, the clippy job embeds a multi-pattern shell assertion for legacy auth identity removal, and the ignored twin E2E selection is encoded directly in a long `nextest` expression. These cost attention but do not obscure the overall validation flow.
-
-A representative routine change is adding a new TypeScript validation job. It would repeat the checkout, Bun setup, and dependency-install sequence already present in `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and `jobs.build`, then add the new command.
-
-Strongest counterevidence: each job can be understood independently, commands are explicit, and there is no multi-layer reusable-workflow indirection.
-
-Why adjacent scores do not fit: 4 does not fit because repeated setup and inline special policies add avoidable local friction. 2 does not fit because ordinary check changes still have a direct path through one small workflow and do not cross a complex control structure.
-
-### Domain model — 2, High confidence
-
-Some configuration identifiers no longer denote repository reality. Both push and pull-request triggers in `.github/workflows/rust.yml` refer to `openapi/**`, but that path does not exist; the actual API contract is `docs/public/api-reference/fabro-api.yaml`, which the same workflow's legacy-auth check names directly. `.github/workflows/typescript.yml` also omits that contract path even though the TypeScript API client is generated from it. A contract-only change can therefore fall outside the configured validation vocabulary.
-
-`.github/zizmor.yml:rules.stale-action-refs.ignore` identifies three exceptions by `rust.yml` source line. History shows those locations originally denoted Rust toolchain actions, while the current line numbers point elsewhere after workflow edits. The exception's identity is coupled to incidental layout rather than the action it is meant to describe.
-
-Strongest counterevidence: jobs, test modes, toolchain versions, permissions, and build profiles are otherwise named explicitly and line up with repository commands.
-
-Why adjacent scores do not fit: 3 does not fit because the stale/nonexistent identifiers affect whether central source-of-truth changes are validated and whether static-validation exceptions retain their intended meaning. 1 does not fit because most CI vocabulary remains stable and the affected values can be corrected from clear repository authorities.
-
-### Duplication of knowledge — 2, High confidence
-
-Trigger-path knowledge is repeated in every workflow and twice within each workflow: `.github/workflows/rust.yml:on.push.paths` duplicates `on.pull_request.paths`, and `.github/workflows/typescript.yml` does the same. Cross-language contract inputs then require synchronized edits in both files. The stale `openapi/**` entry and omission of `docs/public/api-reference/fabro-api.yaml` are direct evidence that this repeated knowledge has drifted.
-
-A representative routine change is moving or adding a source-of-truth file that must trigger all relevant CI. It requires updating `rust.yml:on.push.paths`, `rust.yml:on.pull_request.paths`, `typescript.yml:on.push.paths`, and `typescript.yml:on.pull_request.paths`; there is no shared authority that makes one update cover the four consumers.
-
-Strongest counterevidence: commands and action versions are local to their jobs, so much of the visible repetition is deliberate job isolation, and each language workflow is small.
-
-Why adjacent scores do not fit: 3 does not fit because trigger selection is central to CI's purpose, the synchronization crosses both event sections and language workflows, and actual drift is present. 1 does not fit because the duplicated lists are easy to locate and most entries still agree.
-
-Lens-boundary note: the stale OpenAPI trigger could be scored only as duplicate path knowledge. I used the repeated four-list maintenance burden for duplication, while treating the fact that `openapi/**` currently has no referent—and that line-based Zizmor identities no longer name the intended actions—as domain vocabulary drift.
diff --git a/.chisel/calibration/work/reviewer-2.md b/.chisel/calibration/work/reviewer-2.md
deleted file mode 100644
index a9082f5c0..000000000
--- a/.chisel/calibration/work/reviewer-2.md
+++ /dev/null
@@ -1,176 +0,0 @@
-# Calibration Sample Review — Reviewer 2
-
-Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-This review uses the component boundaries in `.chisel/cartography/codebase-map.md`. In particular, `fabro-web-app` excludes `apps/fabro-web/app/components/playground/**`, and `repository-ci` contains only `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`.
-
-## Score summary
-
-| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
-|---|---:|---:|---:|---:|
-| `fabro-workflow` | 3 (Medium) | 2 (High) | 3 (Medium) | 2 (High) |
-| `fabro-http` | 4 (High) | 4 (High) | 3 (High) | 4 (High) |
-| `fabro-web-app` | 4 (Medium) | 2 (Medium) | 2 (Medium) | 2 (Medium) |
-| `repository-ci` | 4 (High) | 3 (High) | 3 (High) | 2 (High) |
-
-## `fabro-workflow`
-
-### `ownership-boundaries` — 3, Medium confidence
-
-The component has a recognizable high-level owner and intended dependency direction. `lib/components/fabro-workflow/src/operations/mod.rs` owns run-level operations, while `lib/components/fabro-workflow/src/pipeline/mod.rs` owns the ordered phase API. `lib/components/fabro-workflow/src/pipeline/types.rs:Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` make phase ownership explicit. `lib/components/fabro-workflow/src/services.rs:RunServices` and `EngineServices` distinguish run-lifetime services from node-execution services, and `lib/components/fabro-workflow/src/node_handler.rs:WorkflowNodeHandler` is a visible adapter to `fabro-core`.
-
-The friction is at the public edge: `lib/components/fabro-workflow/src/lib.rs` exposes operations, pipeline phases, handlers, records, services, runtime storage, and several `#[doc(hidden)]` modules. Callers can therefore enter below the complete lifecycle as well as through `lib/components/fabro-workflow/src/operations/start.rs:start`. This weakens containment, but it does not create a competing production owner.
-
-**Strongest counterevidence:** The typed phase outputs and the `RunServices`/`EngineServices` split strongly reinforce one workflow lifecycle.
-
-**Why adjacent scores do not fit:** A 4 does not fit because the broad facade exposes enough lifecycle internals to make the boundary porous. A 2 does not fit because the normal `start` path and each phase owner remain identifiable and dependencies are delegated to dedicated crates.
-
-### `simplicity` — 2, High confidence
-
-The stable common path is traceable, but routine work crosses substantial central machinery: `lib/components/fabro-workflow/src/operations/start.rs:start` → `execute_persisted_run` → `RunSession::new` → `RunSession::run` → `pipeline::initialize` → `pipeline::execute` → `pipeline::finalize` → `pipeline::pull_request`. Along that path, `StartServices`, `RunSession`, and `lib/components/fabro-workflow/src/pipeline/types.rs:InitOptions` each carry many run concerns, while bootstrap, completion, cleanup, steering-drain, sandbox, and event-flush guards add multiple exit paths. `lib/components/fabro-workflow/src/pipeline/initialize.rs:initialize` also coordinates sandbox creation/reconnection, hooks, credentials, Git setup, handler construction, and resume state.
-
-**Representative routine change:** Adding one run-scoped execution service would normally thread through `operations/start.rs:StartServices`, `RunSession`, and `RunSession::new`; `pipeline/types.rs:InitOptions`; `pipeline/initialize.rs:initialize`; and `services.rs:RunServices` or `EngineServices`.
-
-**Strongest counterevidence:** `operations/start.rs:RunSession::run` presents the main phases in a linear order, and the phase-specific types preserve that order despite the setup machinery.
-
-**Why adjacent scores do not fit:** A 3 does not fit because the pressure is on the main run path rather than at an edge. A 1 does not fit because there is a stable phase sequence and named service bundles to follow.
-
-### `domain-model` — 3, Medium confidence
-
-The strongest mechanism is the phase-state model in `lib/components/fabro-workflow/src/pipeline/types.rs`; private fields on `Validated` and `Persisted` and opaque `ResumeState` prevent several invalid transitions. `lib/components/fabro-workflow/src/pipeline/finalize.rs:classify_engine_result` is also a clear authority for translating an engine result into `StageOutcome`, failure detail, and `RunStatus`.
-
-The main friction is the extensible, string-valued handler vocabulary on the common graph path. `lib/components/fabro-workflow/src/handler/mod.rs:HandlerRegistry::resolve` works with type strings and falls back to the default handler, while `default_registry` registers the built-in strings. Validation in `fabro-validate` protects normal runs, but execution itself does not carry a closed built-in handler type.
-
-**Strongest counterevidence:** `pipeline/types.rs:ResumeState::from_projection`, the phase output types, and `pipeline/finalize.rs:classify_engine_result` give important workflow concepts one enforced shape.
-
-**Why adjacent scores do not fit:** A 4 does not fit because handler identity remains string-valued and default-resolved through a central execution boundary. A 2 does not fit because validation and typed phase states canonicalize the normal run before execution.
-
-### `duplication-knowledge` — 2, High confidence
-
-Event knowledge is repeated across central authorities. `lib/components/fabro-workflow/src/event/events.rs:Event` defines the emitter-facing shape, `lib/components/fabro-workflow/src/event/convert.rs:event_body_from_event` translates it to the stored `fabro_types::EventBody`, `lib/components/fabro-workflow/src/event/names.rs:event_name` separately assigns wire names, and `lib/components/fabro-workflow/src/event/stored_fields.rs:stored_event_fields_for_variant` separately assigns envelope metadata. These exhaustive matches help detect omissions, but every ordinary event extension still requires synchronized semantic decisions.
-
-**Representative routine change:** Adding a stored workflow event can touch `event/events.rs:Event`, `event/convert.rs:event_body_from_event`, `event/names.rs:event_name`, `event/stored_fields.rs:stored_event_fields_for_variant`, and the canonical `lib/foundation/fabro-types/src/run_event/mod.rs:EventBody` authority.
-
-**Strongest counterevidence:** `event/convert.rs:to_run_event_at` is the single assembly point, and Rust's exhaustive matches turn many missed updates into compile failures.
-
-**Why adjacent scores do not fit:** A 3 does not fit because event emission and persistence are central, recurring behavior. A 1 does not fit because the authorities are explicit and compiler-checked rather than unidentifiable.
-
-## `fabro-http`
-
-### `ownership-boundaries` — 4, High confidence
-
-`lib/foundation/fabro-http/src/lib.rs` has one focused transport-construction boundary. `HttpClientBuilder`, `BlockingHttpClientBuilder`, `ProxyPolicy`, the client aliases, and the production/test constructors all live there; the crate depends only on `fabro-static`, `reqwest`, and `thiserror`. Repository policy reinforces the boundary through `clippy.toml:disallowed-methods`, which directs raw reqwest construction to this facade.
-
-**Strongest counterevidence:** The public reqwest aliases and re-exports make the abstraction intentionally permeable, so it does not own higher-level request behavior.
-
-**Why the adjacent score does not fit:** A 3 does not fit because exposing reqwest types is part of the mapped purpose, while construction policy and proxy resolution still have one clear owner.
-
-### `simplicity` — 4, High confidence
-
-`lib/foundation/fabro-http/src/lib.rs:define_builder` expresses shared async/blocking forwarding once. Both builders end at the same short `ProxyPolicy::resolve` and `build` path, and `http_client`, `test_http_client`, `blocking_http_client`, and `blocking_test_http_client` are thin named entry points. A shared reqwest builder option is normally added once to the macro.
-
-**Strongest counterevidence:** The macro hides generated methods, and async-only `HttpClientBuilder::read_timeout` must sit outside it.
-
-**Why the adjacent score does not fit:** A 3 does not fit because this indirection directly removes twin implementations and leaves callers with a single conventional builder path.
-
-### `domain-model` — 3, High confidence
-
-`lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` gives the repository policy two named states, `ProxyPolicy::resolve_with_env_value` defines explicit-over-environment precedence, and `HttpClientBuildError::InvalidProxyPolicy` rejects unknown values. The tests cover default, environment, invalid, and explicit-override cases.
-
-The isolated ambiguity is that `HttpClientBuilder::no_proxy` and `HttpClientBuilder::proxy_policy(ProxyPolicy::Disabled)` both publicly express disabled proxy behavior, but `no_proxy` mutates the inner builder without updating the policy field. Their relationship is not represented or documented in the type.
-
-**Strongest counterevidence:** The closed enum, typed error, and resolver tests make the environment-facing policy meaning unusually explicit.
-
-**Why adjacent scores do not fit:** A 4 does not fit because two public controls overlap without an encoded relationship. A 2 does not fit because the overlap is local and every normal constructor still passes through one two-state resolver.
-
-### `duplication-knowledge` — 4, High confidence
-
-The builder macro is the authority for behavior shared by synchronous and asynchronous clients, and every constructor delegates to those builders. The production/test and async/blocking helper names repeat syntax, not policy: test behavior is expressed once as `ProxyPolicy::Disabled`.
-
-**Strongest counterevidence:** Four constructor helpers and the separate async-only impl are superficially repetitive.
-
-**Why the adjacent score does not fit:** A 3 does not fit because changing proxy precedence or disabled behavior has one authority; the remaining repetition does not require synchronized policy decisions.
-
-## `fabro-web-app`
-
-### `ownership-boundaries` — 4, Medium confidence
-
-The main browser lifecycle has clear homes. `apps/fabro-web/app/entry.tsx` selects install or normal routing and owns root providers; `app/router.tsx:routes` owns the product route graph; `app/install-router.tsx:installRoutes` owns first-run routing; `app/lib/api-client.ts` owns HTTP normalization; `app/lib/queries.ts` and `app/lib/mutations.ts` own shared server access; and `app/hooks/effects.ts` contains reusable browser-effect lifecycles. Route modules own page-specific composition. The separately mapped playground enters through `app/router.tsx` without its excluded implementation being absorbed into this assessment.
-
-**Strongest counterevidence:** `app/routes/run-stages.tsx` and `app/install-app.tsx` each combine page state, domain projection, and rendering in one route-owned file.
-
-**Why the adjacent score does not fit:** A 3 does not fit because those combinations create local complexity, but no competing owner or reversed dependency was identified; shared cross-route responsibilities still have clear modules.
-
-### `simplicity` — 2, Medium confidence
-
-Two common product paths carry central transformation machinery. `apps/fabro-web/app/routes/run-stages.tsx` turns event envelopes into `TurnType` values in `buildStageActivity`, then separately groups, filters, timelines, labels, summarizes, and renders them through `buildChatItems`, `groupConsecutiveTools`, `filterDisplayItems`, `buildThreadDnaItems`, and the route's view components. `apps/fabro-web/app/install-app.tsx` similarly contains the install reducer, session hydration, controller, step forms, review, finishing, payload construction, and supporting controls in one flow.
-
-**Representative routine change:** Changing how a tool event appears on the stage page requires tracing `run-stages.tsx:buildStageActivity`, `buildChatItems`/`groupConsecutiveTools`, `buildThreadDnaItems`, `turnLabel`, `turnSummary`, `EventDetails`, and `StageChatView`.
-
-**Strongest counterevidence:** The stage path uses discriminated unions and mostly pure exported transformations with focused tests, so each individual step can be reasoned about.
-
-**Why adjacent scores do not fit:** A 3 does not fit because the long transformation chains are central to major routes. A 1 does not fit because the named pure functions provide a stable trace through both flows.
-
-### `domain-model` — 2, Medium confidence
-
-Generated API types provide a useful boundary, but the central event path accepts several simultaneous shapes. `apps/fabro-web/app/lib/run-events.ts:RunEventPayload` makes event identity and metadata optional and `stageIdFromPayload` falls back from `stage_id` to `node_id` to `properties.node_id`. `app/routes/run-stages.tsx:activityEventStageId` repeats that shape tolerance for stored `EventEnvelope`s, while `buildStageActivity` reads tool, text, argument, and output values from both `properties` and legacy top-level fields via `app/lib/unknown.ts`.
-
-**Representative routine change:** Moving one stage-event field to its canonical envelope location can require coordinated interpretation changes in `lib/run-events.ts:RunEventPayload` and `stageIdFromPayload`, plus `routes/run-stages.tsx:activityEventStageId` and `buildStageActivity`.
-
-**Strongest counterevidence:** Once parsed, `run-stages.tsx:TurnType`, `StageRenderer`, and generated `StageHandler`/`StageState` types give the UI clear closed shapes.
-
-**Why adjacent scores do not fit:** A 3 does not fit because the multi-shape event interpretation is on live invalidation and the main stage view, not an edge. A 1 does not fit because generated types and discriminated UI projections establish a stable canonical shape after parsing.
-
-### `duplication-knowledge` — 2, Medium confidence
-
-Stage-state presentation policy is authoritative in several common views. `apps/fabro-web/app/lib/stage-sidebar.ts:ACTIVE_STAGE_STATES`, `IN_FLIGHT_STAGE_STATES`, `SUCCEEDED_STAGE_STATES`, `STAGE_STATUS_TONE`, and `STAGE_STATUS_LABEL` define classifications and visuals, while `app/components/stage-sidebar.tsx:statusConfig`, `app/components/run-waterfall.tsx:stageBarClass` and `isStageInFlight`, and `app/components/stage-popover.tsx:StatusPill` make parallel state decisions.
-
-**Representative routine change:** Adding a generated `StageState` requires reviewing or changing all of those authorities so the sidebar, waterfall, and popover agree on activity, success, label, and tone.
-
-**Strongest counterevidence:** Generated `StageState` plus exhaustive `Record` mappings catch many omissions, and `lib/stage-sidebar.ts` already centralizes several shared classifications.
-
-**Why adjacent scores do not fit:** A 3 does not fit because stage status is central to multiple routine run views and synchronization is recurring. A 1 does not fit because the generated enum is a clear semantic authority and TypeScript catches many missing cases.
-
-## `repository-ci`
-
-### `ownership-boundaries` — 4, High confidence
-
-The two workflows divide validation by ecosystem: `.github/workflows/rust.yml:jobs` owns Rust format, lint, generated-doc, workspace test, twin-mode ignored tests, and manual macOS validation; `.github/workflows/typescript.yml:jobs` owns web/client typecheck, web tests, and the embedded-SPA production build. Both use top-level empty permissions and job-local read permission. The cross-language Cargo build in the TypeScript build job validates the mapped embedded-SPA integration rather than creating a second build owner.
-
-**Strongest counterevidence:** The Rust clippy job contains a repository-wide legacy-auth guard that also scans TypeScript and API paths.
-
-**Why the adjacent score does not fit:** A 3 does not fit because that cross-language invariant remains an explicitly named CI check, while job and workflow lifecycle ownership stays clear.
-
-### `simplicity` — 3, High confidence
-
-The main flow is explicit: named jobs perform checkout, tool setup, and one or two direct repository commands. The isolated friction is `.github/workflows/rust.yml:jobs.clippy.steps.Verify legacy auth identity removal`, where a long regular expression and shell exit-status protocol are embedded in a lint job. The twin-mode test semantics also need a substantial comment and package expression in `jobs.test`.
-
-**Strongest counterevidence:** Separate jobs, direct commands, pinned tools, and no reusable-workflow indirection make routine CI behavior easy to locate.
-
-**Why adjacent scores do not fit:** A 4 does not fit because the legacy guard and twin-mode selection require non-obvious local interpretation. A 2 does not fit because that machinery is isolated and ordinary check changes still follow a direct job structure.
-
-### `domain-model` — 3, High confidence
-
-Job names, triggers, permissions, platforms, and commands have consistent meanings in the GitHub Actions structure. Exact action SHAs and named modes such as `--profile ci` reduce ambiguity. The main gap is that `.github/workflows/rust.yml:jobs.test` relies on the external default meaning of `FABRO_TEST_MODE` for its twin run rather than setting the mode in the workflow; the comment is the only local declaration of that state.
-
-**Strongest counterevidence:** The command, package selector, and explanation tightly describe the intended twin-only behavior, and every job has an explicit runner and permission set.
-
-**Why adjacent scores do not fit:** A 4 does not fit because a central test mode is implicit in an external default. A 2 does not fit because the rest of the workflow vocabulary is coherent and the implicit state is limited to one documented test step.
-
-### `duplication-knowledge` — 2, High confidence
-
-Trigger policy is repeated verbatim between `on.push.paths` and `on.pull_request.paths` in both workflow files. Action versions and bootstrap steps are also copied across every job. `.github/zizmor.yml:rules.stale-action-refs.ignore` adds line-number references to `rust.yml`, creating another manually synchronized representation; at this revision its listed lines 37, 49, and 62 are respectively a blank line, the `fmt` job key, and a Cargo command rather than action references.
-
-**Representative routine change:** Adding a new Rust-owned source area requires matching edits to `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths`; upgrading checkout requires synchronized edits in `jobs.fmt`, `clippy`, `generated-docs`, `test`, and `test-macos`, followed by review of `.github/zizmor.yml:rules.stale-action-refs.ignore`.
-
-**Strongest counterevidence:** The duplication is explicit and small enough to inspect, and each actual validation command appears once in its intended job.
-
-**Why adjacent scores do not fit:** A 3 does not fit because triggers and action versions are central, recurring maintenance knowledge and the stale line selectors demonstrate drift. A 1 does not fit because the canonical workflows and intended checks remain identifiable.
-
-## Lens-boundary confusion
-
-- The `fabro-workflow` `Event`/`EventBody` split could be described as two domain shapes. I assigned its score effect to `duplication-knowledge` because the discriminating problem is the synchronized event name, conversion, and envelope-field decisions, not an inability to identify either type's meaning.
-- The size and mixed contents of `fabro-web-app` route files could look like misplaced responsibility. I assigned the main effect to `simplicity` because the route remains the clear owner; the problem is tracing the amount of local machinery.
-- Repeated `StageState` maps could be treated as domain drift. I assigned them to `duplication-knowledge` because the generated enum preserves meaning and the observed burden is repeating presentation/classification policy across views.
-- The `.github/zizmor.yml` line selectors could be treated as invalid configuration meaning. I assigned their main effect to `duplication-knowledge` because the failure mechanism is manual synchronization with line positions; `repository-ci` domain scoring instead uses the implicit twin-mode default.
-- `fabro-http`'s macro could be treated as simplicity indirection, while its two proxy-disable controls could be treated as duplicate policy. I treated the macro as a positive simplicity/duplication mechanism and the overlapping controls as `domain-model` friction because the unresolved question is what each public control means.
diff --git a/.chisel/calibration/work/reviewer-3.md b/.chisel/calibration/work/reviewer-3.md
deleted file mode 100644
index 98558bff4..000000000
--- a/.chisel/calibration/work/reviewer-3.md
+++ /dev/null
@@ -1,490 +0,0 @@
-# Calibration Sample Review — Reviewer 3
-
-Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-Scope follows `.chisel/cartography/codebase-map.md`: `fabro-workflow`,
-`fabro-http`, `fabro-web-app`, and `repository-ci`. The `fabro-web-app`
-reading excludes `apps/fabro-web/app/components/playground/**`;
-`repository-ci` includes only `.github/workflows/rust.yml`,
-`.github/workflows/typescript.yml`, and `.github/zizmor.yml`.
-
-## Provisional Matrix
-
-| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
-|---|---:|---:|---:|---:|
-| `fabro-workflow` | 4 / High | 2 / High | 2 / High | 2 / High |
-| `fabro-http` | 4 / High | 4 / High | 4 / High | 4 / High |
-| `fabro-web-app` | 3 / High | 2 / High | 2 / High | 2 / High |
-| `repository-ci` | 3 / High | 3 / High | 2 / High | 2 / High |
-
-## `fabro-workflow`
-
-### `ownership-boundaries` — 4, High confidence
-
-Evidence:
-
-- `lib/components/fabro-workflow/src/pipeline/mod.rs` exposes an ordered phase
- facade, while `pipeline/types.rs:Parsed`, `Transformed`, `Validated`,
- `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` give each
- phase an explicit handoff.
-- `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and
- `HandlerRegistry` own workflow-specific dispatch;
- `src/node_handler.rs:WorkflowNodeHandler` is the narrow adapter to
- `fabro_core::handler::NodeHandler`.
-- `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` states
- that it owns callback ordering and delegates event, hook, fidelity,
- auto-status, circuit-breaker, Git, and artifact work to focused lifecycle
- objects.
-- `lib/components/fabro-workflow/Cargo.toml:[dependencies]` points from the
- orchestrator to parsing, validation, sandbox, persistence, model, and generic
- execution crates; generic traversal remains in `fabro-core`.
-
-Strongest counterevidence: startup state is carried through
-`operations/start.rs:StartServices`, `RunSession`,
-`pipeline/types.rs:InitOptions`, and `services.rs:RunServices` /
-`EngineServices`, so the lifecycle boundary has substantial wiring.
-
-Why adjacent scores do not fit: 3 would treat that wiring as unclear ownership,
-but the common path consistently identifies phase, handler, lifecycle, and
-generic-executor owners. The counterevidence is primarily machinery inside the
-intended orchestration owner, not a competing dependency direction or lifecycle
-home.
-
-### `simplicity` — 2, High confidence
-
-Evidence:
-
-- The normal start path crosses
- `operations/start.rs:start` → `execute_persisted_run` →
- `RunSession::new` → `RunSession::run` →
- `pipeline::initialize` → `pipeline::execute` →
- `pipeline::finalize` → `pipeline::pull_request`.
-- The same run-scoped collaborators are reshaped across
- `operations/start.rs:StartServices`, `RunSession`,
- `pipeline/types.rs:InitOptions`, `services.rs:RunServices`, and
- `EngineServices`.
-- `lifecycle/mod.rs:WorkflowLifecycle::new` takes the full set of lifecycle
- collaborators and has an explicit `too_many_arguments` exception before
- constructing seven sub-lifecycles with shared coordination state.
-
-Strongest counterevidence: the phase-state types in
-`pipeline/types.rs` and the focused handler/lifecycle modules make this
-machinery traceable; the common path is not hidden.
-
-Why adjacent scores do not fit: 3 does not fit because every ordinary run
-traverses the service reshaping and multi-stage cleanup/finalization path; this
-is central rather than edge friction. 1 does not fit because the named phase
-sequence and handoff types provide a stable path through the machinery.
-
-Representative routine change: adding a run-scoped execution-audit sink for
-handlers would require threading it through
-`operations/start.rs:StartServices`, `RunSession`,
-`RunSession::new`, `RunSession::run`,
-`pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, and
-`services.rs:RunServices` or `EngineServices`.
-
-### `domain-model` — 2, High confidence
-
-Evidence:
-
-- Positive mechanisms are substantial:
- `pipeline/types.rs:Validated` hides its graph and exposes validation
- operations, `ResumeState::from_projection` creates opaque resume state, and
- `run_status.rs` plus `outcome.rs` reuse canonical types from `fabro-types` and
- `fabro-core`.
-- A central exception remains:
- `event/events.rs:Event::StageCompleted` represents `status` as `String`, while
- execution uses typed `outcome.rs:StageOutcome`.
- `event/convert.rs:stage_status_from_string` reparses the string and maps every
- unknown value to a failed outcome.
-- The common producer
- `lifecycle/event.rs:EventLifecycle::after_node` converts the typed outcome to
- a string before the canonical event conversion converts it back.
-
-Strongest counterevidence: the pipeline phase types, `RunStatus`,
-`StageOutcome`, `StageId`, and the durable `fabro_types::EventBody` otherwise
-give the main workflow concepts canonical typed shapes.
-
-Why adjacent scores do not fit: 3 does not fit because stage completion is on
-the execution hot path and accepts states the canonical outcome enum rejects.
-1 does not fit because the canonical types and phase states still give the
-workflow a coherent vocabulary overall.
-
-Representative routine change: adding or changing a stage outcome would touch
-the canonical `lib/foundation/fabro-core/src/outcome.rs:StageOutcome`, string
-construction in `lifecycle/event.rs:EventLifecycle::after_node`,
-`event/events.rs:Event::StageCompleted`,
-`event/convert.rs:stage_status_from_string`, and terminal interpretation in
-`pipeline/finalize.rs:classify_engine_result`.
-
-### `duplication-knowledge` — 2, High confidence
-
-Evidence:
-
-- `event/events.rs:Event` defines the internal event shape,
- `event/names.rs:event_name` independently maps every variant to its external
- name, `event/stored_fields.rs:stored_event_fields` independently selects
- envelope fields, and `event/convert.rs:event_body_from_event` constructs the
- canonical `fabro_types::EventBody`.
-- `docs/internal/events-strategy.md:Adding A New Event` explicitly requires
- synchronized edits to the internal event, tracing, external name,
- `EventBody`, stored fields, conversion, and consumers.
-- Exhaustive matches make omissions visible, but they do not make one of those
- mappings authoritative for the others.
-
-Strongest counterevidence: `event/emitter.rs:Emitter` canonicalizes each emitted
-event once, all listeners receive the same `RunEvent`, and exhaustive matching
-plus conversion tests detect much of the synchronization drift.
-
-Why adjacent scores do not fit: 3 does not fit because adding an event is a
-routine extension to this component and centrally requires several independent
-authorities. 1 does not fit because the events strategy clearly identifies all
-authorities and the compiler/test suite gives a stable update path.
-
-Representative routine change: adding `run.suspended` would touch
-`event/events.rs:Event`, `events.rs:Event::trace`,
-`event/names.rs:event_name`,
-`lib/foundation/fabro-types/src/run_event/mod.rs:EventBody`,
-`event/stored_fields.rs:stored_event_fields`,
-`event/convert.rs:event_body_from_event`, and relevant store/UI consumers.
-
-## `fabro-http`
-
-### `ownership-boundaries` — 4, High confidence
-
-Evidence:
-
-- The component is one focused source module:
- `lib/foundation/fabro-http/src/lib.rs` owns the reqwest facade,
- `ProxyPolicy`, client builders, build errors, and deterministic test clients.
-- `src/lib.rs:HttpClientBuilder::build` and
- `BlockingHttpClientBuilder::build` are the construction boundary where the
- process proxy policy is applied.
-- `clippy.toml:disallowed-methods` denies direct reqwest client constructors and
- points callers to this component; `fabro_static::EnvVars` supplies the one
- environment-variable name without introducing higher-level configuration.
-
-Strongest counterevidence: the facade deliberately re-exports many reqwest
-types, and exceptional consumers still carry direct reqwest dependencies for
-generated clients or incompatible dependency versions.
-
-Why adjacent scores do not fit: 3 does not fit because the normal async,
-blocking, production, and test construction paths all converge on the same
-owned policy, with a repository lint reinforcing that boundary.
-
-### `simplicity` — 4, High confidence
-
-Evidence:
-
-- `src/lib.rs:define_builder!` expresses the common async/blocking builder once;
- the four convenience constructors are thin calls to the same builders.
-- The common flow is direct:
- `HttpClientBuilder::new` → optional reqwest options →
- `HttpClientBuilder::build` → `ProxyPolicy::resolve` → reqwest build.
-- The only async-only option is visibly isolated in
- `HttpClientBuilder::read_timeout`.
-
-Strongest counterevidence: the macro hides the two generated impls and every
-new exposed reqwest option requires another forwarding method.
-
-Why adjacent scores do not fit: 3 does not fit because the macro removes a real
-parallel API synchronization burden while leaving the common client-building
-path locally readable; its indirection is not encountered beyond this file.
-
-### `domain-model` — 4, High confidence
-
-Evidence:
-
-- `src/lib.rs:ProxyPolicy` has exactly the two supported states,
- `ProxyPolicy::resolve_with_env_value` makes explicit configuration override
- environment fallback, and invalid/non-Unicode values become
- `HttpClientBuildError`.
-- `src/lib.rs:HttpClientBuildError` distinguishes invalid policy from underlying
- reqwest construction failure.
-- `test_http_client` and `blocking_test_http_client` select the typed
- `ProxyPolicy::Disabled` rather than relying on ambient test environment state.
-
-Strongest counterevidence: the environment boundary is necessarily stringly,
-and `ProxyPolicy::parse` accepts case variants before producing the enum.
-
-Why adjacent scores do not fit: 3 does not fit because invalid strings are
-rejected at the boundary, precedence is explicit, and all downstream paths use
-the closed enum.
-
-### `duplication-knowledge` — 4, High confidence
-
-Evidence:
-
-- `src/lib.rs:define_builder!` is the single authority for shared async and
- blocking options and policy application.
-- `ProxyPolicy::resolve` is the single production authority for explicit/env/
- default precedence.
-- `clippy.toml:disallowed-methods` prevents ordinary callers from silently
- recreating client-construction policy outside the component.
-
-Strongest counterevidence: async and blocking convenience constructors remain
-as four syntactically similar functions, and `read_timeout` cannot live in the
-shared macro surface.
-
-Why adjacent scores do not fit: 3 does not fit because the remaining repetition
-does not duplicate a policy or require independent decisions; it exposes
-parallel entry points backed by the same authority.
-
-## `fabro-web-app`
-
-### `ownership-boundaries` — 3, High confidence
-
-Evidence:
-
-- `apps/fabro-web/app/entry.tsx:AppRuntime` owns browser bootstrap and global
- runtime providers; `router.tsx:routes` and
- `install-router.tsx:installRoutes` own the two route graphs.
-- `app/lib/queries.ts` and `app/lib/mutations.ts` own server reads and writes;
- `app/lib/api-client.ts` owns transport/error normalization.
-- `app/hooks/effects.ts` and purpose-named hooks such as
- `useRunEvents` and `useInstallRestartHealthPolling` contain browser resource
- lifecycles rather than leaving them in route rendering.
-- `routes/run-detail.tsx:RunDetail` delegates its header, actions, model,
- lifecycle-toast, tab-shell, and docked-control responsibilities to the
- `routes/run-detail/**` modules.
-
-Strongest counterevidence: two mapped common paths still concentrate several
-responsibilities:
-`install-app.tsx:InstallApp` / `useInstallController` contains state,
-hydration, submission, step routing, payload construction, and rendering, while
-`routes/run-stages.tsx:RunStages` / `buildStageActivity` contains event
-interpretation and a large part of stage presentation.
-
-Why adjacent scores do not fit: 4 does not fit because those central route
-modules are not merely edge exceptions. 2 does not fit because routes, API
-access, queries, mutations, browser effects, and build lifecycle still have
-stable homes and dependencies generally point through those homes.
-
-### `simplicity` — 2, High confidence
-
-Evidence:
-
-- The first-run common path is concentrated in
- `install-app.tsx:installReducer`, `useInstallController`, `InstallApp`,
- `LlmStep`, `ObjectStoreStep`, `SandboxStep`, `GithubStep`,
- `buildObjectStorePayload`, and `buildSandboxPayload`.
-- The run-stage common path combines
- `routes/run-stages.tsx:selectStageRenderer`,
- `buildStageActivity`, filtering, debug views, waterfall construction, and
- `RunStages`.
-- Cross-tab event sharing introduces a second substantial state machine at
- `app/lib/cross-tab-sse.ts:CrossTabSseCoordinator`, beneath the already
- separate shared-event-source logic in `app/lib/sse.ts:subscribeToSharedEventSource`.
-
-Strongest counterevidence: reducers, discriminated unions, shared query hooks,
-purpose-named integration hooks, and extracted run-detail modules make many
-individual flows explicit and testable.
-
-Why adjacent scores do not fit: 3 does not fit because installation, run-stage
-inspection, and live refresh are mapped common paths, not optional edge
-machinery. 1 does not fit because each path still has identifiable entry
-points, state machines, and tests.
-
-Representative routine change: adding an installation step for telemetry would
-touch `install-app.tsx:INSTALL_STEPS`, `InstallState`, `InstallAction`,
-`installReducer`, `useInstallController`, `InstallApp`, a new step component,
-review-summary helpers, `install-api.ts`, and the generated install API
-authority in `docs/public/api-reference/fabro-api.yaml`.
-
-### `domain-model` — 2, High confidence
-
-Evidence:
-
-- Positive mechanisms include generated API types throughout the query and
- route layers, `mode.ts:FabroMode`, and exhaustive display maps such as
- `lib/sandbox-state.ts:SANDBOX_STATE_DISPLAY`.
-- The central SSE boundary instead uses
- `lib/sse.ts:EventPayload`, where `event` is optional and all other fields are
- unknown, then extends it as
- `lib/run-events.ts:RunEventPayload` with optional string identifiers and
- another untyped `properties` map.
-- `lib/run-events.ts:stageIdFromPayload` accepts `stage_id`, `node_id`, or
- `properties.node_id` as the stage identity.
-- `lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance`
- cast generated values into compatibility shapes and infer lifecycle from
- either `kind`, `instance`, or legacy `runtime` / `provider` fields.
-
-Strongest counterevidence: normal HTTP reads and writes use
-`@qltysh/fabro-api-client` types, and `Record` display maps
-make many API vocabulary changes compile-visible.
-
-Why adjacent scores do not fit: 3 does not fit because SSE drives normal run
-refresh and stage views while permitting absent event and identity fields with
-multiple meanings. 1 does not fit because generated HTTP types and local
-discriminated unions still provide a coherent model for most operations.
-
-Representative routine change: making stage identity canonical across live
-events would touch the wire authority
-`docs/public/api-reference/fabro-api.yaml`,
-`lib/sse.ts:EventPayload`, `lib/run-events.ts:RunEventPayload`,
-`stageIdFromPayload`, and consumers such as
-`routes/run-stages.tsx:buildStageActivity`.
-
-### `duplication-knowledge` — 2, High confidence
-
-Evidence:
-
-- `lib/board-events.ts:BOARD_STATUS_EVENTS` independently decides which run
- events refresh lists, while `lib/run-events.ts:RUN_SUMMARY_EVENTS`,
- `TERMINAL_EVENTS`, and other sets decide detail invalidations.
-- `lib/run-phases.ts:deriveRunPhases` independently matches the same lifecycle
- event vocabulary to build the pre-stage timeline.
-- `lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` is a positive local authority
- shared with `routes/run-stages.tsx:buildStageActivity`, but it covers only one
- slice of the broader manual event policy.
-
-Strongest counterevidence: list and detail invalidation are genuinely different
-consumer decisions, `query-keys.ts:queryKeys` centralizes cache identities, and
-the stage-activity list is deliberately shared with its reducer.
-
-Why adjacent scores do not fit: 3 does not fit because a normal lifecycle-event
-extension that affects board and run detail requires synchronized policy edits
-in separate common subscriptions. 1 does not fit because each consumer's
-authority is named, localized, and covered by focused tests.
-
-Representative routine change: adding a `run.suspended` transition that should
-refresh both list and detail views would touch
-`board-events.ts:BOARD_STATUS_EVENTS`,
-`run-events.ts:RUN_SUMMARY_EVENTS` (and possibly `TERMINAL_EVENTS` if its
-semantics require it), `board-events.test.tsx`, `run-events.test.tsx`, and the
-upstream event/OpenAPI authorities.
-
-## `repository-ci`
-
-### `ownership-boundaries` — 3, High confidence
-
-Evidence:
-
-- `.github/workflows/rust.yml:jobs` owns Rust formatting, lint, generated-doc,
- Linux test, twin-E2E, and manual macOS validation.
-- `.github/workflows/typescript.yml:jobs` owns browser/client typecheck, web
- tests, and the embedded-SPA release build.
-- Both workflows set top-level empty permissions and grant only
- `contents: read` per job; all third-party actions are commit-pinned.
-- Generated-document and embedded-SPA behavior is delegated to
- `cargo dev docs check` and `cargo dev build`, leaving those build procedures
- in `fabro-build-tooling`.
-
-Strongest counterevidence:
-`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]`
-contains an authentication-migration vocabulary grep inside the general CI
-workflow, so an auth-domain transition also has a policy home here.
-
-Why adjacent scores do not fit: 4 does not fit because that product-domain
-policy crosses into the CI owner and the trigger boundary has drift discussed
-under domain model. 2 does not fit because the normal validation jobs and their
-delegated build/test authorities remain clearly owned and directional.
-
-Representative routine change: renaming or restoring an authentication identity
-would require changing the product types and also the legacy-name authority in
-`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]`.
-
-### `simplicity` — 3, High confidence
-
-Evidence:
-
-- Each job is a short checkout/setup/command sequence, and the two workflows
- split by the repository's Rust and Bun validation surfaces.
-- `.github/workflows/rust.yml:jobs.test` explains the non-obvious twin-mode
- expression and why it must not use the strict E2E profile.
-- `.github/workflows/typescript.yml:jobs.build` delegates the mixed Rust/SPA
- build to one repository command rather than reproducing its internals.
-
-Strongest counterevidence: checkout, tool setup, install, permissions, runner,
-and cache declarations are repeated across every job; the inline legacy-auth
-shell condition is more elaborate than the surrounding declarative checks.
-
-Why adjacent scores do not fit: 4 does not fit because routine maintenance must
-scan repeated job scaffolding and one bespoke shell policy. 2 does not fit
-because a contributor can still trace each common validation path directly
-from one named job to one repository command.
-
-### `domain-model` — 2, High confidence
-
-Evidence:
-
-- `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths` contain
- `openapi/**`, but that directory does not exist at the assessed revision.
-- The actual contract authority is
- `docs/public/api-reference/fabro-api.yaml`, as named by
- `AGENTS.md:API workflow`,
- `lib/foundation/fabro-api/build.rs:main`, and
- `lib/packages/fabro-api-client/package.json:scripts.generate`.
-- Neither `.github/workflows/rust.yml:on.*.paths` nor
- `.github/workflows/typescript.yml:on.*.paths` names that actual contract
- path, even though both generated clients depend on it.
-
-Strongest counterevidence: job names, Rust versus TypeScript scope, twin versus
-live test meaning, and toolchain versions are otherwise explicit; the commands
-the jobs run correspond to checked-in project commands.
-
-Why adjacent scores do not fit: 3 does not fit because an ordinary edit to the
-HTTP source of truth falls outside both central validation trigger models. 1
-does not fit because the workflows still have a stable and mostly accurate
-vocabulary for jobs, branches, tools, and commands.
-
-Representative routine change: editing only
-`docs/public/api-reference/fabro-api.yaml` should exercise Rust generation and
-TypeScript typecheck/build, but its meaning would have to be repaired in
-`.github/workflows/rust.yml:on.push.paths`,
-`.github/workflows/rust.yml:on.pull_request.paths`,
-`.github/workflows/typescript.yml:on.push.paths`, and
-`.github/workflows/typescript.yml:on.pull_request.paths`.
-
-### `duplication-knowledge` — 2, High confidence
-
-Evidence:
-
-- Each workflow repeats its path set under both `on.push.paths` and
- `on.pull_request.paths`; a new CI-relevant repository path has two authorities
- per language.
-- `.github/workflows/rust.yml:jobs.fmt`, `jobs.clippy`,
- `jobs.generated-docs`, `jobs.test`, and `jobs.test-macos` independently repeat
- checkout pins, credential policy, runner/toolchain setup, and often cache
- setup.
-- `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and
- `jobs.build` independently repeat checkout, Bun setup, and frozen install.
-
-Strongest counterevidence: independent jobs preserve failure isolation and
-least-privilege permissions, while the substantive docs/build procedures are
-delegated to repository commands rather than copied into YAML.
-
-Why adjacent scores do not fit: 3 does not fit because path and tool-bootstrap
-knowledge is repeated on every routine trigger or tool-version update. 1 does
-not fit because all copies remain confined to two small workflow files and the
-substantive check authorities are still identifiable.
-
-Representative routine change: adding a new Rust-relevant `tools/**` tree would
-require synchronized edits to
-`.github/workflows/rust.yml:on.push.paths` and
-`on.pull_request.paths`; updating the Rust checkout/toolchain baseline requires
-reviewing the pins in every `rust.yml:jobs.*.steps` copy.
-
-## Lens-Boundary Notes
-
-- The repeated startup carriers in `fabro-workflow` could be labeled ownership
- or simplicity. I counted their unclear amount of machinery under simplicity;
- ownership was judged from whether each phase, resource lifecycle, and
- dependency direction has a named home.
-- The workflow's internal `Event` and durable `EventBody` have documented
- distinct meanings. I therefore counted the many synchronized mappings under
- duplication, not domain model. The separate `StageCompleted.status: String`
- finding drives the domain-model score because it admits invalid states.
-- Large web route files are not ownership findings merely because they are
- large. They lower simplicity where common behavior is difficult to trace; the
- ownership score moves only where several responsibilities remain concentrated
- despite otherwise clear route/data/effect homes.
-- In the web event layer, optional/untyped payload shape is a domain-model
- finding. Repeating lifecycle-event policy across list, detail, and phase
- consumers is a duplication finding.
-- In CI, the stale `openapi/**` referent is a domain-model finding because the
- path no longer means the API authority it purports to cover. Repeating trigger
- and setup lists is separately a duplication finding.
-- The `fabro-http` builder macro adds local indirection, but its primary effect
- is to make shared async/blocking policy authoritative. I treated it as a
- positive duplication mechanism rather than simplicity friction.
diff --git a/.chisel/calibration/work/validation-1.md b/.chisel/calibration/work/validation-1.md
deleted file mode 100644
index 6954086ae..000000000
--- a/.chisel/calibration/work/validation-1.md
+++ /dev/null
@@ -1,424 +0,0 @@
-# Chisel calibration validation 1
-
-Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-This is an independent reading of only the requested assignments. Scores use the
-mapped purposes and the final calibration rubric. Boundary evidence is included
-where it establishes whether a scoped mechanism is on a production common path.
-
-## Summary
-
-| Component | Lens | Score | Evidence confidence |
-|---|---|---:|---|
-| `fabro-workflow` | `ownership-boundaries` | 2 | High |
-| `fabro-workflow` | `domain-model` | 2 | High |
-| `fabro-http` | `domain-model` | 4 | High |
-| `fabro-http` | `duplication-knowledge` | 4 | High |
-| `fabro-web-app` | `ownership-boundaries` | 4 | Medium |
-| `repository-ci` | `ownership-boundaries` | 4 | Medium |
-| `repository-ci` | `domain-model` | 2 | High |
-| `fabro-checkpoint` | `ownership-boundaries` | 2 | High |
-| `fabro-checkpoint` | `simplicity` | 4 | Medium |
-| `fabro-checkpoint` | `domain-model` | 2 | High |
-| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium |
-
-## `fabro-workflow`
-
-### `ownership-boundaries`: 2
-
-- **Evidence:** `lifecycle/mod.rs:53-80` presents `WorkflowLifecycle` as the
- callback owner, and `lifecycle/git.rs:77-93, 397-401` gives `GitLifecycle`
- its own `last_git_sha` state. The normal `RunSession::run` path nevertheless
- creates a second `last_git_sha`, reconstructs it by listening to emitted
- checkpoint, terminal, and Git events, then passes it back into finalization
- (`operations/start.rs:821-856, 914-923`). Terminal responsibility is split
- again: engine outcomes become terminal events in
- `pipeline/finalize.rs:524-596`, while bootstrap, initialization, and
- finalization errors become `run.failed` through the outer operation in
- `operations/start.rs:176-285, 288-346`. These crossings occur on the normal
- run and error paths, not at an optional edge.
-- **Strongest counterevidence:** `operations/start.rs:796-953` is a recognizable
- top-level owner for the initialize → execute → finalize → pull-request
- sequence, and `WorkflowLifecycle` explicitly orders focused delegates for
- each executor callback (`lifecycle/mod.rs:221-469`).
-- **Why adjacent scores do not fit:** 3 does not fit because the caller always
- mirrors and resupplies Git identity on the common run path, and terminal
- failure handling routinely selects between two owners. 1 does not fit because
- both the executor callback owner and the outer run-session owner are stable
- and traceable; the problem is their competition, not the absence of owners.
-- **Rule discrimination:** Decision rule 2 is decisive for the mirrored
- `last_git_sha`. The phrase “complete lifecycle” is otherwise ambiguous about
- whether an executor lifecycle may end before durability finalization; the
- explicit state round-trip makes the result 2 without relying on that
- ambiguity.
-
-### `domain-model`: 2
-
-- **Evidence:** The internal durable event shape stores
- `Event::StageCompleted.status` as `String`
- (`event/events.rs:264-272`). Both synthetic terminal-stage completion and
- ordinary successful stage completion stringify the canonical
- `StageOutcome` (`lifecycle/event.rs:215-240, 355-366`), after which the
- mandatory event conversion reparses it and converts an unknown value to
- `Failed` (`event/convert.rs:14-24, 309-333`). This typed → string → typed path
- is part of every successful stage-completion event.
-- **Strongest counterevidence:** `fabro_types::StageOutcome` is a stable
- canonical type, most event fields are typed, and the fallback prevents an
- unrecognized string from escaping into the stored projection.
-- **Why adjacent scores do not fit:** 3 does not fit because common production
- completion events depend on the invalid intermediate rather than using it as
- a compatibility edge. 1 does not fit because the canonical status meaning is
- clear and the conversion point is explicit.
-- **Rule discrimination:** Decision rule 4 and the rubric's repository example
- make this assignment unambiguous.
-
-## `fabro-http`
-
-### `domain-model`: 4
-
-- **Evidence:** `ProxyPolicy` is a closed `System | Disabled` vocabulary;
- parsing rejects every other boundary value
- (`src/lib.rs:23-35`). Resolution gives explicit configuration precedence over
- the environment, defaults absence to `System`, and rejects non-Unicode input
- (`src/lib.rs:38-60`). Every async and blocking builder reaches that resolver
- before construction (`src/lib.rs:160-166, 172-193`), while the deterministic
- test helpers select the typed `Disabled` value
- (`src/lib.rs:195-213`).
-- **Strongest counterevidence:** The builder also exposes raw `no_proxy()` and
- `proxy()` operations (`src/lib.rs:96-106`), so callers can combine an
- underlying reqwest choice with `ProxyPolicy`; Unix-socket production callers
- do use `no_proxy()` (`lib/foundation/fabro-client/src/client.rs:2123-2134`).
-- **Why adjacent scores do not fit:** 3 does not fit because the common
- policy-controlled constructors never interpret an invalid policy: they
- return `HttpClientBuildError`. The raw builder operations represent valid
- per-client transport configuration, not a second string vocabulary. 2 and 1
- do not fit because no common-path conversion or unstable meaning is present.
-- **Rule discrimination:** Decision rule 4 is potentially non-discriminating
- if every forwarded low-level builder method is called an “escape hatch.”
- Here `no_proxy()` carries no invalid intermediate and does not weaken
- `ProxyPolicy::resolve`, so treating it as ordinary typed builder
- configuration preserves the rule's distinction.
-
-### `duplication-knowledge`: 4
-
-- **Evidence:** `define_builder!` holds the complete shared async/blocking
- builder policy once, including proxy resolution and construction
- (`src/lib.rs:72-170`), and is instantiated for the two reqwest client kinds
- (`src/lib.rs:172-193`). The four convenience constructors delegate to those
- builders rather than reproducing policy (`src/lib.rs:195-213`).
-- **Strongest counterevidence:** The generated facade necessarily lists each
- forwarded reqwest method, and the test and non-test convenience constructors
- have similar bodies.
-- **Why adjacent scores do not fit:** 3 does not fit because the similar
- forwarding and wrappers are syntax over one policy authority, not separately
- maintained transport knowledge. 2 does not fit because a proxy-policy change
- is made once in the macro/resolver, not synchronized across async and
- blocking implementations. 1 does not fit because the authority is explicit.
-- **Rule discrimination:** The rubric's `define_builder!` example directly
- distinguishes shared macro expansion from semantic duplication; no material
- ambiguity remains.
-
-## `fabro-web-app`
-
-### `ownership-boundaries`: 4
-
-- **Evidence:** `entry.tsx:17-49` owns browser startup, chooses the normal or
- installation route graph once, and installs shared SWR runtime policy.
- `router.tsx:97-184` owns normal route composition. Shared transport and error
- handling live in `lib/api-client.ts:64-160, 213-310`; shared reads such as
- `useRun` and `useRunState` live in `lib/queries.ts:182-193`; run mutations and
- their cache lifecycle live in `lib/mutations.ts:65-132`; and run-scoped SSE
- subscription, invalidation, resync, and cleanup live in
- `lib/run-events.ts:129-309`. The representative busy route composes those
- owners rather than reimplementing them
- (`routes/run-detail.tsx:79-145, 313-379`).
-- **Strongest counterevidence:** Some route-local CRUD actions call the shared
- API facade directly, and `run-detail.tsx:193-205` coordinates delete state,
- cache invalidation, toast, and navigation in the route.
-- **Why adjacent scores do not fit:** 3 does not fit because the counterevidence
- is local page UX ownership; it does not split a shared transport, read,
- mutation, or subscription lifecycle. 2 does not fit because routine run-page
- changes use the established owners rather than coordinating competing ones.
- 1 does not fit because startup, routing, transport, caching, and streaming
- each have readily identifiable homes.
-- **Rule discrimination:** “One owner” is mildly non-discriminating for a large
- browser application unless responsibility is evaluated at lifecycle
- granularity. Using the rubric's `apiData`/`useRun` example, route composition
- is not itself a second owner. Confidence is Medium because this is the
- largest sampled scope.
-
-## `repository-ci`
-
-### `ownership-boundaries`: 4
-
-- **Evidence:** `rust.yml:3-40` owns Rust branch/PR/manual triggers and
- concurrency, while its jobs contain format, lint, generated-doc, Linux test,
- twin E2E, and manual macOS lifecycles (`rust.yml:48-147`).
- `typescript.yml:3-34` owns the corresponding TypeScript triggers and
- concurrency, and its jobs contain typecheck, test, and integrated SPA/Rust
- build lifecycles (`typescript.yml:36-77`). Delegation to `cargo dev` is the
- mapped dependency on build tooling, not reverse ownership.
-- **Strongest counterevidence:** The TypeScript build invokes a Rust build
- (`typescript.yml:75-77`), and invalid path selectors mean some intended
- changes do not start the declared workflows.
-- **Why adjacent scores do not fit:** 3 does not fit because the cross-language
- build is the intentional embedded-SPA integration boundary, not friction, and
- selector validity is classified under domain model by decision rule 6. 2
- does not fit because no routine job requires coordination between competing
- CI owners. 1 does not fit because the two language validation homes and their
- dependency direction are explicit.
-- **Rule discrimination:** The score-4 phrase “complete lifecycle” is
- non-discriminating for hosted CI if it is read to require repository
- ownership of GitHub's runner lifecycle. This score treats the checked-in
- trigger/job lifecycle as the mapped responsibility and the platform as an
- intended boundary.
-
-### `domain-model`: 2
-
-- **Evidence:** Both Rust trigger selectors name `openapi/**`
- (`rust.yml:18,34`), but that revision has no tracked target there; the actual
- API contract is `docs/public/api-reference/fabro-api.yaml`, which the
- TypeScript client generation command consumes
- (`lib/packages/fabro-api-client/package.json:7`). The real contract path is
- absent from both workflow path filters. In addition, all three zizmor
- `stale-action-refs` identifiers target `rust.yml:37`, `:49`, and `:62`
- (`zizmor.yml:1-6`), which are respectively the end of trigger setup, the
- `fmt` job key, and a `run` command—not action references at this revision.
- These invalid identifiers sit directly in trigger and static-validation
- configuration.
-- **Strongest counterevidence:** The workflow/job vocabulary itself is stable,
- all jobs and action pins have clear meanings, and changes under the large
- valid Rust and TypeScript source selectors do trigger their expected suites.
-- **Why adjacent scores do not fit:** 3 does not fit because the dead OpenAPI
- selector is present in both routine branch and PR paths, while every scoped
- zizmor exception lacks a current target. 1 does not fit because the overall
- workflow and job model remains stable; the defect is a recurring set of
- invalid identifiers.
-- **Rule discrimination:** Decision rule 6 is decisive that these are domain
- pressure rather than ownership or duplication. It does not state when one or
- more dead selectors move from 3 to 2; centrality in both trigger modes and
- total staleness of the scoped zizmor selectors supply that discrimination
- here.
-
-## Control: `fabro-checkpoint`
-
-### `ownership-boundaries`: 2
-
-- **Evidence:** The mapped component claims metadata branches, but its
- production boundary consumer owns the metadata writer's branch, parent OID,
- discovery, remote, and push lifecycle
- (`fabro-workflow/src/run_metadata.rs:272-282, 313-439`). On every snapshot,
- that caller validates entries, individually drives `Store` through blobs,
- tree, commit, and ref update, and retains the parent identity for the next
- write (`run_metadata.rs:313-350`). `BranchStore` provides a contained
- read-modify-write owner (`branch.rs:17-24, 42-81`) but has no production
- caller at this revision.
-- **Strongest counterevidence:** The dependency direction is intended
- (`fabro-workflow` depends on `fabro-checkpoint`), and the low-level `Store`
- consistently owns Git object/ref operations (`git.rs:101-227`).
-- **Why adjacent scores do not fit:** 3 does not fit because the lifecycle
- crossing occurs on every metadata snapshot, not in an isolated adapter. 1
- does not fit because low-level Git ownership and the caller's higher-level
- writer ownership are both stable; the problem is the split between them.
-- **Rule discrimination:** Decision rule 2 applies because the caller retains
- and resupplies branch/parent identity to complete successive writes. The
- rubric does not say whether a deliberately low-level `Store` narrows the
- mapped ownership claim; the explicit mapped claim to metadata branches makes
- this crossing discriminating.
-
-### `simplicity`: 4
-
-- **Evidence:** The production `Store` has direct blob, tree, commit, and ref
- operations (`git.rs:123-226`). Tree conversion is a single read recursion and
- a single bottom-up write path (`git.rs:229-310`). At the higher level,
- `BranchStore::write_with` is a linear resolve → read → mutate → write → commit
- → update sequence (`branch.rs:56-81`), and entry operations are small
- delegates (`branch.rs:84-117`). Necessary Git layering is visible rather than
- hidden behind competing configuration machinery.
-- **Strongest counterevidence:** There are two entry levels, and the production
- metadata writer uses the lower-level `Store` instead of `BranchStore`.
-- **Why adjacent scores do not fit:** 3 does not fit because choosing the
- low-level entry is required for replace-whole-tree and remote-parent behavior,
- not unnecessary indirection. 2 does not fit because the scoped common
- operations do not navigate competing implementations or configuration. 1
- does not fit because both paths are directly traceable.
-- **Rule discrimination:** Ownership rule 2 could otherwise cause the
- out-of-scope metadata writer's machinery to be counted again as simplicity
- friction. The lens exclusions make that non-discriminating evidence here;
- within the scoped implementation, the production primitives are direct.
-
-### `domain-model`: 2
-
-- **Evidence:** `TreeEntries::set` accepts any `String` path without validation
- (`git.rs:46-60`), and `write_tree` later interprets it by splitting on `/`
- (`git.rs:149-153, 270-293`). The common metadata caller must therefore define
- and apply `validate_metadata_path` outside this component before every
- `TreeEntries` construction
- (`fabro-workflow/src/run_metadata.rs:313-332, 471-480`). The component also
- maps every unrecognized Git file mode to `Blob`
- (`git.rs:21-35, 229-250`) rather than rejecting an unsupported state.
-- **Strongest counterevidence:** `FileMode` is otherwise a closed enum, Git
- object IDs use `git2::Oid`, and the current production metadata caller does
- reject empty, absolute, dot-segment, and empty-segment paths before writing.
-- **Why adjacent scores do not fit:** 3 does not fit because external path
- validation is mandatory on every common metadata snapshot and the canonical
- `TreeEntries` shape can always hold an invalid path. 1 does not fit because
- the intended path and mode meanings remain clear and production does have a
- validation step.
-- **Rule discrimination:** Decision rule 4 clearly places the caller-validated
- `TreeEntries` intermediate at 2. Whether unknown Git modes are a compatibility
- escape hatch is ambiguous by itself, but it is not needed to choose the
- score.
-
-### `duplication-knowledge`: 3
-
-- **Evidence:** Branch-to-full-ref formatting is repeated in `Store::update_ref`,
- `resolve_ref`, and `delete_ref` (`git.rs:182-225`), and the boundary metadata
- writer has another `full_ref` transformation
- (`fabro-workflow/src/run_metadata.rs:364-439`). `BranchStore::read_entry`,
- `read_entries`, `list_entries`, and `tip_tree` also repeat parts of branch-tip
- resolution (`branch.rs:119-184`). These repetitions are local and stable, but
- there is no single helper enforcing them.
-- **Strongest counterevidence:** Mutation sequencing is authoritative in
- `BranchStore::write_with` (`branch.rs:56-81`), metadata branch naming has one
- `META_BRANCH_PREFIX` constant (`lib.rs:7`), Git-author defaults have one
- `Default` implementation (`author.rs:13-20`), and the repeated ref syntax is a
- fixed Git protocol form rather than frequently changing Fabro policy.
-- **Why adjacent scores do not fit:** 4 does not fit because ref normalization
- and branch-tip traversal are still represented in several places. 2 does not
- fit because there is no direct evidence that a routine checkpoint change
- must alter those stable protocol transformations in sync; the repetitions are
- isolated implementation knowledge. 1 does not fit because each policy has an
- identifiable local authority even where a helper is absent.
-- **Rule discrimination:** Decision rule 5 leaves a real 3-versus-4 ambiguity:
- repeated `refs/heads/` can be classified as harmless protocol syntax. I score
- 3 because the same branch-to-ref transformation crosses the component
- boundary, but do not score 2 without evidence of routine synchronization.
-
-## Overall rubric observations
-
-- Decision rule 2 successfully distinguishes focused delegates from a lifecycle
- that sends identity back through an event/caller round trip.
-- Decision rule 6 prevents dead CI selectors from being double-counted as
- ownership defects, but needs centrality/recurrence evidence to distinguish 2
- from 3.
-- “One owner” and “complete lifecycle” need responsibility-sized interpretation
- for route trees and hosted CI; otherwise healthy composition cannot reach 4.
-- Decision rule 5 correctly keeps stable protocol repetition from automatically
- becoming score 2, but the line between harmless syntax and a repeated
- transformation remains the least discriminating part of this sample.
-
-## Round 2 revalidation
-
-| Component | Lens | Score | Confidence |
-|---|---|---:|---|
-| `fabro-http` | `duplication-knowledge` | 3 | Medium |
-| `repository-ci` | `ownership-boundaries` | 2 | High |
-| `fabro-checkpoint` | `ownership-boundaries` | 2 | High |
-| `fabro-checkpoint` | `simplicity` | 3 | High |
-| `fabro-checkpoint` | `domain-model` | 2 | High |
-| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium |
-
-### `fabro-http` × `duplication-knowledge`: 3
-
-- **Decisive evidence:** Proxy disabling has two concrete semantic
- representations in the mapped entry layer: callers may set
- `ProxyPolicy::Disabled` (`src/lib.rs:23-27, 90-94`), or call the separately
- exposed `no_proxy()` builder operation (`src/lib.rs:96-100`). The former is
- interpreted by calling the same underlying `inner.no_proxy()` transformation
- during `build` (`src/lib.rs:160-165`). Both forms are used on direct boundary
- paths: test constructors select the enum (`src/lib.rs:199-213`), while the
- Unix-socket transport selects `no_proxy()`
- (`lib/foundation/fabro-client/src/client.rs:2123-2134`).
-- **Adjacent scores:** 4 does not fit revised rule 6 because there is a concrete
- second representation of the same no-proxy decision. 2 does not fit because
- an ordinary proxy-policy extension does not require manually synchronizing
- those call sites; async and blocking policy construction still share the one
- `define_builder!` mechanism (`src/lib.rs:72-193`). 1 does not fit because the
- resolver remains a stable authority.
-- **Remaining ambiguity:** `no_proxy()` can reasonably be viewed as a lower-level
- reqwest operation rather than a second Fabro policy. Revised rule 6 makes 3
- the conservative result because `ProxyPolicy::Disabled` is implemented by
- that exact operation, but this classification keeps confidence at Medium.
-
-### `repository-ci` × `ownership-boundaries`: 2
-
-- **Decisive evidence:** The Rust check explicitly scans
- `docs/public/api-reference/fabro-api.yaml` in its legacy-identity guard
- (`rust.yml:80-92`), but neither push nor pull-request triggers include that
- real path (`rust.yml:3-35`); they include the nonexistent `openapi/**`
- selector instead (`rust.yml:18,34`). A routine API-contract change can
- therefore change a scanned target without starting its owning check.
-- **Adjacent scores:** 3 does not fit because the non-triggering target is on a
- routine branch/PR check path, not an isolated manual edge. 1 does not fit
- because the workflow, jobs, and intended trigger owner remain identifiable.
- 4 is directly excluded by revised rule 3's trigger-coverage requirement.
-- **Remaining ambiguity:** `typescript.yml:76` also invokes a Rust build from a
- narrower trigger set, but that broader interpretation is unnecessary; the
- explicitly scanned, non-triggering API contract is sufficient for 2.
-
-### `fabro-checkpoint` × `ownership-boundaries`: 2
-
-- **Decisive evidence:** The mapped owner exposes low-level `Store` primitives,
- while the routine metadata caller reconstructs the mapped branch lifecycle:
- `RunMetadataWriter` owns branch, parent, and discovery state
- (`fabro-workflow/src/run_metadata.rs:272-282`), then validates entries and
- sequences blob, tree, commit, ref update, and retained parent state on every
- snapshot (`run_metadata.rs:313-350`). No production boundary uses the
- component's higher-level `BranchStore`.
-- **Adjacent scores:** 3 does not fit because every metadata snapshot traverses
- the split. 1 does not fit because the low-level Git owner and caller-side
- lifecycle are both stable. 4 is directly excluded by revised rule 2: the
- routine caller reconstructs a lifecycle the map assigns to this component.
-- **Remaining ambiguity:** A narrower map that assigned only Git object
- primitives to `fabro-checkpoint` could make this healthy delegation, but the
- actual map explicitly assigns metadata branches and checkpoint commits.
-
-### `fabro-checkpoint` × `simplicity`: 3
-
-- **Decisive evidence:** `Cargo.toml:16-24` carries `fabro-store` as a production
- dependency, but scoped production code does not use it. The component also
- exposes `BranchStore` as a parallel entry layer (`branch.rs:17-24`) that has
- no production caller at this revision; the common metadata path uses `Store`
- directly. The active `Store` path itself remains linear and direct
- (`git.rs:123-226`).
-- **Adjacent scores:** 4 is explicitly capped at 3 by revised rule 4 for the
- unused production dependency and parallel unused entry layer. 2 does not fit
- because routine production work does not repeatedly navigate those unused
- elements; its `Store` path is direct. 1 does not fit because a stable common
- path is easy to trace.
-- **Remaining ambiguity:** Either isolated fact independently supplies the
- revised rule's cap, so there is no material score ambiguity.
-
-### `fabro-checkpoint` × `domain-model`: 2
-
-- **Decisive evidence:** `TreeEntries::set` accepts arbitrary string paths
- (`git.rs:46-60`) before `write_tree` interprets them structurally
- (`git.rs:149-153, 270-293`). Every common metadata snapshot must validate
- those paths outside the mapped entry before constructing `TreeEntries`
- (`fabro-workflow/src/run_metadata.rs:313-332, 471-480`).
-- **Adjacent scores:** 3 does not fit revised rule 5 because caller validation
- does not isolate an invalid-capable mapped entry used on every snapshot. 1
- does not fit because path meaning is stable and the caller does enforce it.
- 4 is excluded because the canonical entry type itself admits invalid states.
-- **Remaining ambiguity:** Unknown Git modes also collapse to `Blob`
- (`git.rs:21-35`), but that compatibility question is not needed for the
- score; the routine path shape is decisive.
-
-### `fabro-checkpoint` × `duplication-knowledge`: 3
-
-- **Decisive evidence:** The short branch name is converted to
- `refs/heads/{branch}` independently in `Store::update_ref`, `resolve_ref`, and
- `delete_ref` (`git.rs:182-225`), while the routine boundary writer carries a
- second `full_ref` conversion
- (`fabro-workflow/src/run_metadata.rs:364-439`). These are concrete repeated
- representations, but of stable Git protocol knowledge.
-- **Adjacent scores:** 4 does not fit revised rule 6 because the
- branch-to-full-ref transformation has a concrete second representation. 2
- does not fit because no ordinary mapped change is shown to require
- synchronizing the stable Git namespace transformations; repeated call sites
- alone are insufficient. 1 does not fit because the transformation and its
- local authorities are clear.
-- **Remaining ambiguity:** The literal can also be classified as harmless Git
- syntax, which the lens excludes. Its repetition across the mapped boundary
- supports 3, but the harmless-syntax distinction keeps confidence at Medium.
diff --git a/.chisel/calibration/work/validation-2.md b/.chisel/calibration/work/validation-2.md
deleted file mode 100644
index b33efa10f..000000000
--- a/.chisel/calibration/work/validation-2.md
+++ /dev/null
@@ -1,450 +0,0 @@
-# Chisel calibration validation 2
-
-Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
-
-This is an independent reading of the final rubric. I did not seek or infer
-earlier scores.
-
-## Scores
-
-| Component | Lens | Score | Evidence confidence |
-|---|---|---:|---|
-| `fabro-workflow` | `ownership-boundaries` | 2 | High |
-| `fabro-workflow` | `domain-model` | 2 | High |
-| `fabro-http` | `domain-model` | 4 | High |
-| `fabro-http` | `duplication-knowledge` | 4 | Medium |
-| `fabro-web-app` | `ownership-boundaries` | 4 | Medium |
-| `repository-ci` | `ownership-boundaries` | 2 | High |
-| `repository-ci` | `domain-model` | 2 | High |
-| `fabro-checkpoint` | `ownership-boundaries` | 4 | Medium |
-| `fabro-checkpoint` | `simplicity` | 4 | Medium |
-| `fabro-checkpoint` | `domain-model` | 3 | Medium |
-| `fabro-checkpoint` | `duplication-knowledge` | 2 | Medium |
-
-## Disputed assignments
-
-### `fabro-workflow` × `ownership-boundaries` — 2
-
-**Direct evidence.** `WorkflowLifecycle` is a real central owner for engine
-callback ordering: it contains the event, hook, fidelity, status, circuit
-breaker, git, and artifact delegates and orders them in every callback
-(`src/lifecycle/mod.rs:53-80`, `223-470`). The full run lifecycle nevertheless
-crosses that owner on normal paths. `WorkflowLifecycle::on_run_end` only runs
-the hook (`src/lifecycle/mod.rs:467-469`); `pipeline::finalize` separately builds
-and emits the terminal event and stops the sandbox
-(`src/pipeline/finalize.rs:524-635`); `RunSession::run` separately owns
-initialize/execute/finalize, progress flushing, steering drain, and a second
-sandbox cleanup guard (`src/operations/start.rs:796-953`); detached bootstrap
-and completion guards own additional terminal-failure paths
-(`src/operations/start.rs:956-1139`). A routine change to terminal ordering or
-cleanup must account for these owners.
-
-**Strongest counterevidence.** The split is deliberate. In particular,
-`finalize` documents why the terminal event must follow metadata flushing, and
-the scope guards cover panic/interruption paths that an async lifecycle callback
-cannot reliably cover.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because the split is on
-every ordinary terminal path, not an isolated compatibility path. Score 1 does
-not fit because the owners and dependency direction are identifiable:
-`RunSession` is the outer orchestrator and `WorkflowLifecycle` consistently owns
-engine callbacks.
-
-**Rule discrimination.** Decision rule 2 is useful here, but “complete routine
-lifecycle operations” must include terminal emission and resource cleanup, not
-only engine callbacks. Without that reading, the positive orchestrator example
-could make 3 and 2 hard to distinguish.
-
-### `fabro-workflow` × `domain-model` — 2
-
-**Direct evidence.** The canonical execution result is the typed
-`StageOutcome`, re-exported in `src/outcome.rs:1-12`. The common stage-completion
-event instead stores `status: String` (`src/event/events.rs:264-293`).
-`EventLifecycle::after_node` converts the typed value to a string for every
-successful completion (`src/lifecycle/event.rs:319-378`), and
-`event_body_from_event` reparses it into `StageOutcome`
-(`src/event/convert.rs:309-348`). Unknown strings are silently reinterpreted as
-a non-retryable failure (`src/event/convert.rs:14-24`). The same string
-intermediate is used for synthetic terminal stages
-(`src/lifecycle/event.rs:183-242`).
-
-**Strongest counterevidence.** Durable `fabro_types::StageCompletedProps` is
-typed, and ordinary producers derive the string from a typed value rather than
-accepting arbitrary user text.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because the conversion
-and invalid intermediate occur on the common event path for every completed
-stage. Score 1 does not fit because `StageOutcome` supplies a stable canonical
-meaning and most execution code uses it directly.
-
-**Rule discrimination.** Decision rule 4 and the repository example are
-decisive. The rule would be non-discriminating if “compatibility escape hatch”
-were allowed to describe the central `Event` type merely because the durable
-type is healthier.
-
-### `fabro-http` × `domain-model` — 4
-
-**Direct evidence.** `ProxyPolicy` is a closed two-variant vocabulary
-(`src/lib.rs:23-27`). The environment boundary parses case-insensitively and
-rejects every other value with a typed `HttpClientBuildError`
-(`src/lib.rs:29-70`). Explicit policy has a documented precedence in
-`resolve_with_env_value`, and both async and blocking builders resolve the
-policy immediately before applying it (`src/lib.rs:38-59`, `160-166`,
-`172-193`). The common production and test constructors all pass through those
-builders (`src/lib.rs:195-213`).
-
-**Strongest counterevidence.** The builders also expose the lower-level
-`no_proxy()` and `proxy()` methods (`src/lib.rs:96-106`), so callers can express
-transport configuration outside the high-level enum.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because the lower-level
-methods are intentional reqwest-facade escape hatches; the common constructors
-and environment boundary do not rely on an invalid or ambiguous policy value.
-There is positive production enforcement rather than a test-only contract.
-
-**Rule discrimination.** Decision rule 4 discriminates well if “low-level
-escape hatch” is read literally. If any alternate builder method were treated
-as a second domain meaning, scores 3 and 4 would become difficult to distinguish
-for facades.
-
-### `fabro-http` × `duplication-knowledge` — 4
-
-**Direct evidence.** `define_builder!` is one production mechanism for all
-shared async/blocking builder methods and for applying proxy policy
-(`src/lib.rs:72-170`); the two concrete builders are declarations of that
-mechanism (`src/lib.rs:172-193`). `ProxyPolicy::resolve` is the single authority
-for explicit-versus-environment precedence (`src/lib.rs:38-59`), and the four
-convenience constructors delegate to the builders (`src/lib.rs:195-213`).
-Workspace boundary evidence reinforces this authority: `clippy.toml` disallows
-raw reqwest client constructors in favor of these functions/builders.
-
-**Strongest counterevidence.** The tokens `system` and `disabled` also appear in
-the human-readable error text, and the async/blocking test constructors repeat
-the choice of `ProxyPolicy::Disabled`.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because the repeated
-tokens and two one-line convenience constructors do not form independent
-authorities for a recurring transformation. The macro and resolver are what
-enforce behavior.
-
-**Rule discrimination.** Decision rule 5 is useful but leaves a small judgment
-gap around repeated diagnostic vocabulary. Here that repetition is
-non-discriminating: adding a variant would make the exhaustive application
-match fail to compile, while one diagnostic sentence is not a second policy
-engine. This is why confidence is Medium rather than High.
-
-### `fabro-web-app` × `ownership-boundaries` — 4
-
-**Direct evidence.** Shared HTTP configuration, authentication redirect, and
-error normalization live in `app/lib/api-client.ts:64-160,213-309`. Read state
-and cache keys live in `app/lib/queries.ts` and
-`app/lib/query-keys.ts`; for example, `useRun` owns the run-detail fetch/cache
-lifecycle (`queries.ts:182-187`). Shared run mutations and their cache updates
-live in `app/lib/mutations.ts:42-208`. Run SSE connection sharing, cleanup, and
-cache invalidation live in `app/lib/sse.ts:42-189` and
-`app/lib/run-events.ts:129-308`. Browser resources with more specialized
-lifecycles are likewise contained: terminal WebSocket/xterm/listener cleanup is
-in `app/hooks/use-terminal-session.ts:62-229`, and install polling owns its
-timer, interval, and abort controller in
-`app/hooks/use-install-effects.ts:72-127`.
-
-`RunDetail` composes these owners and retains view-local state and interaction
-ordering (`app/routes/run-detail.tsx:79-145,148-379`). Its size does not make it
-the owner of transport or resource cleanup.
-
-**Strongest counterevidence.** Several feature routes perform feature-local
-create/edit/delete calls and SWR invalidation directly, and `RunDetail` owns the
-delete dialog, pending state, toast, list invalidation, and navigation
-(`run-detail.tsx:193-205`) rather than using a single mutation hook for that
-entire interaction.
-
-**Why adjacent scores do not fit.** Score 3 does not fit without a concrete
-isolated lifecycle that has competing owners. The direct route mutations keep
-their feature interaction lifecycle local and still use the shared transport;
-they are not evidence that ordinary reads, SSE, or browser resources leak into
-route composition.
-
-**Rule discrimination.** The final repository example is discriminating:
-“busy route” must not itself count as boundary leakage. Confidence remains
-Medium because the application scope is broad, although the representative
-read, mutation, live-update, terminal, install, and route boundaries converge.
-
-### `repository-ci` × `ownership-boundaries` — 2
-
-**Direct evidence.** The Rust workflow’s Clippy job owns a repository-wide
-“legacy auth identity removal” guard that scans `lib/apps`, `lib/components`,
-`lib/foundation`, `apps`, `lib/packages`, and the OpenAPI document
-(`.github/workflows/rust.yml:80-91`). The workflow’s path filters do not include
-`apps/**`, `lib/packages/**`, or
-`docs/public/api-reference/fabro-api.yaml`
-(`rust.yml:3-35`). A routine change in a scanned TypeScript/package/API path can
-therefore introduce a forbidden identity without starting the job that owns the
-guard. The policy lifecycle is placed under a narrower Rust trigger than the
-responsibility it claims.
-
-**Strongest counterevidence.** The primary Rust and TypeScript build/test
-responsibilities otherwise have clear workflow homes, read-only permissions,
-and stable concurrency ownership (`rust.yml:38-147`;
-`typescript.yml:30-77`). The TypeScript production build’s Rust step is a
-legitimate composition point because it builds the Rust binary with the
-embedded SPA.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because the trigger
-mismatch affects ordinary changes in multiple scanned source areas, not an
-isolated maintenance path. Score 1 does not fit because the two main language
-workflows and their jobs still have stable owners and dependency direction.
-
-**Rule discrimination.** No final rule explicitly says how to classify a check
-whose declared scan scope exceeds its trigger scope. The ownership lens’s
-“complete lifecycle” language is sufficient, but an explicit trigger/target
-coverage rule would make 2 versus 3 less ambiguous.
-
-### `repository-ci` × `domain-model` — 2
-
-**Direct evidence.** Every value in `.github/zizmor.yml` is a line-addressed
-identifier: `rust.yml:37`, `rust.yml:49`, and `rust.yml:62`
-(`.github/zizmor.yml:1-6`). At this revision those lines are respectively a
-blank separator, the `fmt` job key, and a `run:` step—not action references.
-Thus none is a current target for the configured `stale-action-refs` ignores.
-Routine edits to `rust.yml` can change the accidental referents again without
-changing the selectors.
-
-**Strongest counterevidence.** The syntax still communicates an intended
-workflow-and-line selector, and the main workflow job/status vocabulary is
-otherwise stable.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because all three
-values in the entire scoped zizmor configuration lack their intended current
-referent; this is not one isolated compatibility value. Score 1 does not fit
-because the selector format and intended concept remain identifiable even
-though the instances are stale.
-
-**Rule discrimination.** Decision rule 6 is decisive and correctly keeps this
-under domain model rather than ownership. It would not by itself distinguish 2
-from 3; the fact that every configured identifier is stale and line edits make
-the condition recur supplies that distinction.
-
-## Control: `fabro-checkpoint`
-
-### `fabro-checkpoint` × `ownership-boundaries` — 4
-
-**Direct evidence.** `git::Store` owns the `git2::Repository` and the low-level
-blob/tree/commit/ref operations (`src/git.rs:101-227`).
-`branch::BranchStore` owns branch identity, author identity, and the complete
-local read-modify-write lifecycle, including parent resolution, tree read,
-commit, and ref update (`src/branch.rs:17-82`). Author and trailer concerns are
-focused modules rather than state hidden in callers (`src/author.rs`;
-`src/trailer.rs`). Boundary evidence points in the intended direction:
-`fabro-workflow` depends on these primitives, while its
-`RunMetadataWriter` owns the additional temp repository, remote discovery,
-credentials, push, and degradation lifecycle. That is a higher-level owner
-using a lower-level delegate, not a reverse dependency.
-
-**Strongest counterevidence.** The production metadata writer uses `Store`
-directly and manually sequences blob, tree, commit, and ref operations
-(`fabro-workflow/src/run_metadata.rs:313-361`) instead of using `BranchStore`.
-The crate name/description can make that look like the mapped checkpoint
-lifecycle has escaped the component.
-
-**Why adjacent scores do not fit.** Score 3 does not fit if responsibilities are
-classified by their actual state: `Store` owns local Git mechanics,
-`BranchStore` owns local branch writes, and `RunMetadataWriter` owns remote run
-metadata. No concrete resource is acquired by one of those owners and released
-by another.
-
-**Rule discrimination.** Decision rule 2 is ambiguous for intentionally
-low-level facades. Passing a branch to `Store::update_ref` should not alone mean
-“resupplying identity” when the caller owns the higher-level remote branch
-lifecycle and `Store` never claimed it. If the mapped purpose is instead read
-as all run-checkpoint lifecycle, this assignment could become 2; that purpose
-boundary should be fixed before using the control for strict agreement.
-
-### `fabro-checkpoint` × `simplicity` — 4
-
-**Direct evidence.** The local branch write path is linear in
-`BranchStore::write_with`: resolve parent, read tree, apply one caller mutation,
-write tree, commit, update ref (`src/branch.rs:56-81`). Single-file,
-multi-file, and delete operations are thin delegates to that path
-(`src/branch.rs:84-117`). The lower-level tree conversion is one direct
-flat-to-nested algorithm (`src/git.rs:229-309`), and trailer formatting/parsing
-uses straightforward local control flow (`src/trailer.rs:9-87`).
-
-**Strongest counterevidence.** `BranchStore` has no external production caller
-at this revision; the actual metadata path uses the lower-level `Store` API.
-There is also some unused-looking surface such as `MetadataError` and generic
-branch read/list/log helpers.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because no direct
-production evidence shows routine changes navigating the unused surface or
-competing implementations. The production `Store` call sequence is itself
-linear. The rubric explicitly says a public method alone does not establish
-frequency, so unused API breadth cannot by itself create common-path
-indirection.
-
-**Rule discrimination.** The score-4 requirement for a “production mechanism”
-is mildly ambiguous when the clearest high-level mechanism has no production
-caller but its lower-level mechanism does. Treating compiled non-test code as
-sufficient would make the rule non-discriminating; this score instead relies on
-the directly used `Store` path also being traceable.
-
-### `fabro-checkpoint` × `domain-model` — 3
-
-**Direct evidence.** The common metadata boundary validates every path before
-putting it into `TreeEntries`
-(`fabro-workflow/src/run_metadata.rs:319-336,471-481`), explicitly selects
-`FileMode::Blob`, and converts author strings with the fallible
-`git2::Signature::now` before committing (`run_metadata.rs:337-345`). Within the
-control, `FileMode` and `TreeEntries` give Git tree entries a stable meaning
-(`src/git.rs:13-99`), and Git failures stay typed (`src/error.rs:3-32`).
-
-There is nevertheless isolated model friction. `TreeEntries::set` accepts any
-string path with no invariant-bearing path type (`src/git.rs:59-61`);
-`FileMode::from_i32` maps every unrecognized Git mode to `Blob`
-(`src/git.rs:30-35`); `GitAuthor` has public raw string fields
-(`src/author.rs:6-11`); and `BranchStore` says trees grow monotonically while
-also exposing `delete_entry` (`src/branch.rs:17-19,111-117`).
-
-**Strongest counterevidence.** These are not merely hypothetical invalid
-shapes: low-level public callers can bypass the production metadata-path
-validation, and Git supports meaningful modes omitted by `FileMode`.
-
-**Why adjacent scores do not fit.** Score 4 does not fit because the low-level
-types themselves do not reject invalid paths/authors or preserve every Git
-mode. Score 2 does not fit because the directly traced production metadata path
-validates before interpretation and does not depend on the fallback
-`from_i32`; the friction is in lower-level escape paths and the currently
-unused `BranchStore`, not every common snapshot.
-
-**Rule discrimination.** Decision rule 4 is useful but ambiguous about whether
-a common caller validating raw values before a low-level API counts as a
-“common-path invalid intermediate.” The rule should distinguish an actually
-reparsed/ambiguous value from a raw value that has already passed one boundary
-check but lacks an invariant-bearing Rust type.
-
-### `fabro-checkpoint` × `duplication-knowledge` — 2
-
-**Direct evidence.** The branch-name-to-full-ref transformation
-`refs/heads/{branch}` is repeated independently in `Store::update_ref`,
-`Store::resolve_ref`, and `Store::delete_ref`
-(`src/git.rs:182-225`). The direct production boundary repeats it again in
-`RunMetadataWriter::full_ref`
-(`fabro-workflow/src/run_metadata.rs:425-439`). A routine addition or change to
-branch ref handling must preserve the same transformation in each location.
-The trailer grammar has a second, smaller recurrence: `": "` is independently
-formatted, parsed, and detected in `append`, `parse`, `format_message`, and
-`has_trailing_trailer_block` (`src/trailer.rs:11-12,28-40,45-59,68-86`).
-
-**Strongest counterevidence.** Both grammars are tiny and stable, tests cover
-the trailer forms, and the three Store methods currently agree. A helper could
-look like cosmetic deduplication rather than a material abstraction.
-
-**Why adjacent scores do not fit.** Score 3 does not fit because branch
-resolution/update/deletion are ordinary Store operations and direct boundary
-code already supplies a fourth recurrence; this is not only a hypothetical
-future variant. Score 1 does not fit because the repeated transformations are
-stable and readily identifiable even though they lack a single authority.
-
-**Rule discrimination.** Decision rule 5 is decisive only if “direct evidence
-of routine recurrence” includes several current operations applying the same
-transformation. If it instead requires historical change evidence, the final
-rule would be non-discriminating for a revision-only review and this assignment
-would move toward 3.
-
-## Round 2 revalidation
-
-These scores supersede the corresponding Round 1 scores.
-
-### `fabro-http` × `duplication-knowledge` — 3 (Medium)
-
-**Decisive evidence.** `ProxyPolicy::parse` is the behavioral authority for the
-external `system`/`disabled` vocabulary, while
-`HttpClientBuildError::InvalidProxyPolicy` separately enumerates those values
-in its diagnostic (`src/lib.rs:29-35,63-66`). The builder macro remains one
-authority for applying the policy to both client kinds (`src/lib.rs:72-193`).
-
-**Adjacent scores and ambiguity.** Score 4 does not fit because the diagnostic
-is a concrete second representation that can drift. Score 2 does not fit
-because proxy behavior is not independently reimplemented: the shared
-resolver and macro enforce it, and the two no-proxy convenience constructors
-are call sites rather than separate authorities (`src/lib.rs:195-213`). The
-remaining ambiguity is whether changing the closed proxy vocabulary is routine
-enough to make the diagnostic synchronization central; I treat it as isolated.
-
-### `repository-ci` × `ownership-boundaries` — 2 (High)
-
-**Decisive evidence.** The Rust workflow's legacy-auth check scans `apps`,
-`lib/packages`, and `docs/public/api-reference/fabro-api.yaml`
-(`rust.yml:80-91`), but its push and pull-request path filters omit all three
-(`rust.yml:3-35`). Under decision rule 3, that check owns trigger coverage for
-every path it scans, so routine changes in those targets bypass its lifecycle.
-
-**Adjacent scores and ambiguity.** Score 3 does not fit because the missing
-triggers affect several routine source and contract paths, not an isolated
-edge. Score 1 does not fit because the Rust and TypeScript workflow owners and
-dependency direction remain stable. No material ambiguity remains under the
-new trigger-coverage rule.
-
-### `fabro-checkpoint` × `ownership-boundaries` — 2 (High)
-
-**Decisive evidence.** The map assigns checkpoint commits, trees, metadata
-branches, authorship, and trailers to this component. The routine
-`RunMetadataWriter` caller reconstructs that mapped lifecycle from `Store`
-primitives: it writes blobs and a tree, creates the commit and author/message,
-updates the ref, and pushes
-(`fabro-workflow/src/run_metadata.rs:313-361`). Decision rule 2 therefore
-places ownership at 2 even though the crate dependency points toward
-`fabro-checkpoint`.
-
-**Adjacent scores and ambiguity.** Score 3 does not fit because this is the
-common metadata snapshot path, not an edge case. Score 1 does not fit because
-the dependency direction and the low-level `Store` role are stable, and
-`BranchStore::write_with` demonstrates a coherent lifecycle owner inside the
-crate (`src/branch.rs:56-81`). The only remaining ambiguity is how specialized
-the metadata commit is, but the map explicitly includes metadata branches.
-
-### `fabro-checkpoint` × `simplicity` — 3 (High)
-
-**Decisive evidence.** `fabro-store` and `serde` are production dependencies
-with no source use (`Cargo.toml:16-24`), and `BranchStore` is a parallel
-high-level entry layer with no production caller outside this crate. Decision
-rule 4 makes those isolated simplicity frictions and caps 4 at 3.
-
-**Adjacent scores and ambiguity.** Score 4 does not fit because the unused
-production edges and parallel layer are concrete. Score 2 does not fit because
-the production `Store` path remains direct; normal callers do not navigate the
-unused dependencies or `BranchStore`. Whether `BranchStore` is retained for a
-future caller is ambiguous, but the unused dependencies alone sustain 3.
-
-### `fabro-checkpoint` × `domain-model` — 2 (Medium)
-
-**Decisive evidence.** The mapped Git-tree entry accepts any `String` path
-through `TreeEntries::set` (`src/git.rs:44-61`), while the routine metadata
-writer must validate paths before constructing those entries
-(`fabro-workflow/src/run_metadata.rs:319-336,471-481`). Decision rule 5 says
-caller validation does not isolate an invalid-capable mapped entry.
-`FileMode::from_i32` also collapses every unrecognized mode to `Blob`
-(`src/git.rs:29-35`).
-
-**Adjacent scores and ambiguity.** Score 3 does not fit because raw paths cross
-the common write boundary. Score 1 does not fit because tree entries, modes,
-and authors retain stable meanings and the caller does validate its input.
-Confidence is Medium because a deliberately low-level Git store can reasonably
-leave some path constraints to higher-level schemas, although the revised rule
-weighs against that interpretation.
-
-### `fabro-checkpoint` × `duplication-knowledge` — 3 (Medium)
-
-**Decisive evidence.** The `refs/heads/{branch}` transformation is repeated in
-three `Store` operations and once at the workflow boundary
-(`src/git.rs:182-225`; `fabro-workflow/src/run_metadata.rs:425-439`).
-Trailer formatting, parsing, and block detection also encode the `": "`
-convention separately (`src/trailer.rs:11-12,28-40,45-59,68-86`). These are
-concrete second representations, so decision rule 6 caps 4 at 3.
-
-**Adjacent scores and ambiguity.** Score 2 does not fit on the current evidence:
-adding a Store operation or trailer key may repeat a call-site convention, but
-does not require an ordinary mapped change to modify all existing locations.
-Score 4 does not fit because the representations are nevertheless concrete and
-can drift. The remaining ambiguity is whether broader trailer-syntax support
-would be routine maintenance; if so, its formatter/parser/detector
-synchronization would support 2.
diff --git a/.chisel/calibration/work/validation-3.md b/.chisel/calibration/work/validation-3.md
deleted file mode 100644
index 3969b0b13..000000000
--- a/.chisel/calibration/work/validation-3.md
+++ /dev/null
@@ -1,447 +0,0 @@
-# Chisel calibration validation 3
-
-Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`.
-
-This is an independent reading of the final rubric and the assigned component
-scopes. I traced representative production entry points and direct boundary
-callers. I did not inspect prior calibration scores or any other file in
-`.chisel/calibration/work/`.
-
-## Score summary
-
-| Component | Lens | Score | Evidence confidence |
-| --- | --- | ---: | --- |
-| `fabro-workflow` | ownership-boundaries | 2 | High |
-| `fabro-workflow` | domain-model | 2 | High |
-| `fabro-http` | domain-model | 4 | High |
-| `fabro-http` | duplication-knowledge | 3 | Medium |
-| `fabro-web-app` | ownership-boundaries | 4 | Medium |
-| `repository-ci` | ownership-boundaries | 4 | Medium |
-| `repository-ci` | domain-model | 2 | High |
-| `fabro-checkpoint` | ownership-boundaries | 2 | High |
-| `fabro-checkpoint` | simplicity | 3 | Medium |
-| `fabro-checkpoint` | domain-model | 2 | High |
-| `fabro-checkpoint` | duplication-knowledge | 3 | Medium |
-
-## `fabro-workflow`
-
-### `ownership-boundaries`: 2 (High)
-
-- **Evidence:** `src/lifecycle/mod.rs:53-80,221-469` provides a real central
- `WorkflowLifecycle` and explicitly orders focused event, hook, fidelity, Git,
- artifact, status, and circuit-breaker delegates. Its terminal callback,
- however, only forwards `on_run_end` to the hook. Normal terminal persistence,
- metadata completion, terminal event emission, and sandbox stopping instead
- live in `src/pipeline/finalize.rs:524-635`. Bootstrap and execution failures
- take another terminal path in `src/operations/start.rs:176-345`, while
- `RunSession::run` also installs cleanup and drain guards at
- `src/operations/start.rs:889-947`. A routine terminal-lifecycle change must
- therefore coordinate the lifecycle orchestrator, finalizer, and detached
- failure/guard paths.
-- **Strongest counterevidence:** The normal phase sequence is plainly owned by
- `RunSession::run` (`initialize -> execute -> finalize -> pull_request`), and
- callback ordering inside graph execution has one obvious owner,
- `WorkflowLifecycle`.
-- **Why 3 does not fit:** Terminal completion, failure, persistence, and cleanup
- are common paths, not isolated edge compatibility. The split therefore
- remains central even though each individual phase is understandable.
-- **Why 1 does not fit:** Stable phase owners and a stable dependency direction
- are readily identifiable; the problem is coordination among them, not the
- absence of ownership.
-- **Rule discrimination:** The repository example correctly requires terminal
- inspection and rule 1 makes the common terminal split score-capping. Decision
- rule 2 is less literal here because no single identity is resupplied across
- every split, but the score does not depend on that rule.
-
-### `domain-model`: 2 (High)
-
-- **Evidence:** `src/lifecycle/event.rs:319-390` starts with the typed
- `StageOutcome` on an `Outcome`, serializes it with
- `outcome.status.to_string()`, and stores the result in the
- `Event::StageCompleted.status: String` field declared at
- `src/event/events.rs:264-293`. Every successful stage then passes through
- `src/event/convert.rs:14-24,309-348`, which reparses the string and silently
- converts an unknown value into a non-retryable failure. This is the ordinary
- durable-event path, not an import-only compatibility path.
-- **Strongest counterevidence:** The destination event model already has the
- canonical `fabro_types::StageOutcome`, parallel-branch completion carries it
- directly, and other core run concepts use typed IDs, reasons, timings, and an
- opaque `ResumeState` (`src/pipeline/types.rs:252-285`).
-- **Why 3 does not fit:** The invalid intermediate occurs for each ordinary
- successful stage before durable interpretation, so it is central rather than
- an isolated escape hatch.
-- **Why 1 does not fit:** `StageOutcome` itself has a stable, typed meaning; the
- defect is the recurring string round trip between two typed points.
-- **Rule discrimination:** Decision rule 4 is directly discriminating here:
- this is exactly a common-path invalid intermediate.
-
-## `fabro-http`
-
-### `domain-model`: 4 (High)
-
-- **Evidence:** `src/lib.rs:23-61` gives proxy behavior a closed
- `ProxyPolicy::{System, Disabled}` vocabulary. The environment boundary
- accepts case-insensitive valid names, rejects every other value with a typed
- `HttpClientBuildError`, handles non-Unicode values explicitly, gives explicit
- policy precedence over the environment, and resolves absence to `System`.
- Both generated builders invoke this resolver before constructing a client
- (`src/lib.rs:72-193`), and the test-client entry points select
- `ProxyPolicy::Disabled` rather than passing an unchecked string
- (`src/lib.rs:195-213`).
-- **Strongest counterevidence:** The facade deliberately exposes reqwest's
- lower-level `Proxy` and `.no_proxy()` operations, so callers can compose
- transport details outside the two-value environment policy.
-- **Why 3 does not fit:** Those operations are typed builder choices, not
- unvalidated representations of the `FABRO_HTTP_PROXY_POLICY` value. Every
- common construction path still validates that boundary before use; I found no
- material meaning or validation friction.
-- **Why 1-2 do not fit:** There is one stable meaning, one resolver, and no
- recurring conversion through an invalid intermediate.
-- **Rule discrimination:** Decision rule 4 could be read ambiguously if every
- low-level builder method is called a policy escape hatch. The rubric's own
- `ProxyPolicy` example resolves that ambiguity in favor of the closed,
- validated environment-policy model.
-
-### `duplication-knowledge`: 3 (Medium)
-
-- **Evidence:** `define_builder!` at `src/lib.rs:72-193` is one authoritative
- production mechanism for the shared async/blocking builder surface and for
- applying the resolved proxy policy. The four convenience constructors route
- through those builders. The remaining repeated knowledge is narrow:
- `"system"` and `"disabled"` appear both in the parser and in the manually
- maintained `InvalidProxyPolicy` expectation text
- (`src/lib.rs:29-35,63-69`).
-- **Strongest counterevidence:** The macro removes the materially risky
- async/blocking synchronization, and the compiler forces the policy-application
- match to cover every enum variant. The two test helpers' use of
- `ProxyPolicy::Disabled` is ordinary reuse, not a second policy authority.
-- **Why 4 does not fit:** The user-facing valid-value list is a small second
- representation that can drift from the parser, so there is some isolated
- repeated domain knowledge.
-- **Why 2 does not fit:** There is no direct evidence that routine changes
- repeatedly synchronize separate async/blocking implementations. A future
- enum variant is hypothetical, and rule 5 specifically says exhaustive
- compiler-checked branches and hypothetical variants do not establish
- competing authorities.
-- **Rule discrimination:** Rule 5 cleanly rules out 2 but is non-discriminating
- between 3 and 4 for a duplicated allowed-value error message. I treat that
- message as real but isolated maintenance friction, hence 3.
-
-## `fabro-web-app`
-
-### `ownership-boundaries`: 4 (Medium)
-
-- **Evidence:** `app/entry.tsx:17-48` owns root creation, global SWR policy,
- build-version guarding, toast mounting, and the single normal/install router
- choice. `app/router.tsx:97-184` owns normal route composition, while
- `app/install-router.tsx:6-22` owns the install graph. Shared HTTP translation
- and unauthorized handling live in `app/lib/api-client.ts:213-309`; shared
- reads such as `useRun` live in `app/lib/queries.ts:182-187`; recurring run
- mutations and cache follow-up live in
- `app/lib/mutations.ts:65-149`. Route components compose these owners.
- Separately, `scripts/build.ts:183-249,289-368` contains the complete
- app-local build, atomic publication, and old-build pruning lifecycle and
- publishes only `apps/fabro-web/dist`; boundary tooling mirrors that output
- into the Rust SPA rather than the web build writing across the boundary.
-- **Strongest counterevidence:** Some route-specific CRUD mutations import
- `apiData` and generated API objects directly, and the install feature spans
- `install-app.tsx`, `install-api.ts`, `install-query.ts`, and effect hooks.
- `run-detail.tsx` is also a busy composition point.
-- **Why 3 does not fit:** The direct calls remain at the route-specific UX
- owner and still use the shared transport/error boundary; shared read and
- recurring run-lifecycle responsibilities are not reimplemented there.
- Install state, transport, query, and browser effects have distinct homes.
- I found no isolated lifecycle that must leave its owner and resupply identity.
-- **Why 1-2 do not fit:** Runtime, routing, transport, queries, route UX, and
- build publication all have stable owners with dependencies pointing from
- composition toward shared services.
-- **Rule discrimination:** The final repository example is useful and
- discriminating: a large route is not by itself boundary leakage. The score
- would change if direct routes reimplemented shared transport or cache
- lifecycles, but representative boundary checks did not show that.
-
-## `repository-ci`
-
-### `ownership-boundaries`: 4 (Medium)
-
-- **Evidence:** `.github/workflows/rust.yml:48-147` owns Rust formatting,
- lint/architecture checks, generated docs, Linux tests, twin E2E selection,
- and manual macOS tests. `.github/workflows/typescript.yml:36-77` owns web and
- generated-client typechecks, web tests, and the production embedded-SPA
- integration build. Each workflow owns its concurrency and least-privilege job
- permissions. The TypeScript workflow's `cargo dev build` is the intentional
- integration boundary that consumes the web bundle; it does not create a
- competing implementation of the web build.
-- **Strongest counterevidence:** The TypeScript build job invokes Rust build
- tooling, path scopes overlap around `lib/apps/fabro-spa/**`, and
- `.github/zizmor.yml` is configuration whose consumer is not shown in these
- files.
-- **Why 3 does not fit:** Cross-language integration is part of the mapped CI
- purpose and has one concrete home. The stale configuration values discussed
- below are domain-model findings, while duplicated push/pull selectors are
- duplication findings; counting either again as ownership friction would
- violate the rubric's primary-lens rule.
-- **Why 1-2 do not fit:** The Rust and TypeScript responsibilities and their
- dependency direction are stable. Routine validation changes have an obvious
- workflow owner rather than requiring competing lifecycle owners.
-- **Rule discrimination:** The instruction not to penalize an unevidenced
- missing lifecycle matters for the unseen zizmor consumer. The rubric is
- otherwise discriminating once repeated selector policy is kept out of the
- ownership lens.
-
-### `domain-model`: 2 (High)
-
-- **Evidence:** Both Rust trigger selectors name `openapi/**`
- (`.github/workflows/rust.yml:6-19,22-35`), but that revision has no tracked
- `openapi/` target. The actual Rust generator and TypeScript generator consume
- `docs/public/api-reference/fabro-api.yaml`
- (`lib/foundation/fabro-api/build.rs:159` and
- `lib/packages/fabro-api-client/package.json:7`), a path omitted from both
- workflow trigger models. This makes a core API-spec change invisible to the
- intended CI trigger. In addition, all three
- `.github/zizmor.yml:4-6` line selectors target
- `.github/workflows/rust.yml` lines 37, 49, and 62, which are respectively
- `workflow_dispatch`, the `fmt` job key, and a shell `run`, not action
- references for `stale-action-refs`.
-- **Strongest counterevidence:** Most configured branches, paths, action SHAs,
- runner labels, job names, and commands have clear current targets, and both
- workflow documents have a stable overall schema.
-- **Why 3 does not fit:** The dead OpenAPI selector sits in both central Rust
- push and pull-request triggers and omits the actual source of truth. It is not
- merely an isolated stale lint suppression.
-- **Why 1 does not fit:** The CI configuration language and almost all values
- remain interpretable; the problem is recurring invalid/no-target identifiers,
- not the absence of a stable configuration model.
-- **Rule discrimination:** Decision rule 6 correctly classifies the no-target
- identifiers as domain pressure, but it does not itself distinguish 2 from 3.
- The centrality of the API source-of-truth trigger is what selects 2.
-
-## Control: `fabro-checkpoint`
-
-### `ownership-boundaries`: 2 (High)
-
-- **Evidence:** Inside the component, `BranchStore` owns a branch string and
- author and delegates Git objects to `Store`
- (`src/branch.rs:17-82`), which is a sensible direction. At the production
- boundary, however, no production caller constructs `BranchStore`.
- `fabro-workflow/src/run_metadata.rs:272-451` instead keeps `Store`, branch,
- author, `parent_oid`, and discovery state as separate fields, manually writes
- blobs and trees, supplies parents to `Store::write_commit`, resupplies the
- branch to `Store::update_ref`, and owns fetch/push discovery. Other checkpoint
- commit and trailer lifecycle work also remains in `fabro-workflow`. Thus the
- mapped checkpoint/metadata-branch lifecycle crosses the scoped owner on the
- normal production path.
-- **Strongest counterevidence:** `Store` is itself a mapped public entry point,
- the dependency direction remains `fabro-workflow -> fabro-checkpoint`, and
- remote authentication/push orchestration reasonably belongs near a workflow
- run rather than in a low-level Git object store.
-- **Why 3 does not fit:** The caller-held branch and parent identity are used on
- every metadata snapshot, not only in an isolated migration or uncommon
- fallback.
-- **Why 1 does not fit:** Low-level Git ownership and the higher workflow
- orchestration are both stable and understandable; they simply split one
- routine persistence lifecycle.
-- **Rule discrimination:** Decision rule 2 is directly discriminating:
- `RunMetadataWriter` retains and repeatedly resupplies the identity needed to
- complete operations on `Store`. The mapped breadth of “metadata branches”
- makes this more than ordinary parameter passing.
-
-### `simplicity`: 3 (Medium)
-
-- **Evidence:** The production low-level path is traceable:
- `Store::write_blob -> TreeEntries::set -> Store::write_tree ->
- Store::write_commit -> Store::update_ref`
- (`src/git.rs:123-188`). `BranchStore::write_with` also gives branch-oriented
- writes one linear read/modify/write implementation
- (`src/branch.rs:56-117`). The recursive flat-tree conversion is justified by
- Git's nested tree representation. The friction is isolated: `BranchStore` is
- a sizeable second entry layer with tests but no production caller at this
- revision, and `Cargo.toml:18` declares `fabro-store` although scoped
- production code does not reference it.
-- **Strongest counterevidence:** The two entry points represent legitimate
- abstraction levels, and the mapped cartography names both. None of the normal
- `Store` operations requires navigating configuration machinery or dynamic
- dispatch.
-- **Why 4 does not fit:** The unused higher layer/dependency is concrete,
- avoidable surface and configuration burden, even though it is off the current
- production common path.
-- **Why 2 does not fit:** Routine production writes do not repeatedly choose
- between `Store` and `BranchStore`; the observed caller consistently uses
- `Store`, and that path is direct.
-- **Rule discrimination:** The “public method alone does not establish
- frequency” rule prevents treating `BranchStore` as a competing common path.
- It is less discriminating between 3 and 4; the concrete unused dependency and
- unused entry layer are why I select 3.
-
-### `domain-model`: 2 (High)
-
-- **Evidence:** `GitAuthor::from_options` accepts arbitrary name/email strings
- (`src/author.rs:22-30`), while `BranchStore::new` only interprets them by
- calling `Signature::now(...).expect(...)`
- (`src/branch.rs:26-39`). `TreeEntries` stores paths as unrestricted `String`
- and `BranchStore::write_entry/write_entries` put caller strings into it
- without validation (`src/git.rs:46-90`,
- `src/branch.rs:84-109`); interpretation and possible rejection occur later
- while rebuilding Git trees. `FileMode::from_i32` also maps every unknown Git
- mode to `Blob` (`src/git.rs:21-36`) rather than preserving or rejecting an
- unknown shape. These invalid-capable intermediates sit on the mapped storage
- entry paths.
-- **Strongest counterevidence:** `FileMode` is closed for values the component
- writes, normal metadata callers validate paths before constructing
- `TreeEntries`, Git itself rejects malformed signatures/trees, and object IDs
- use git2's typed `Oid`.
-- **Why 3 does not fit:** Raw author and path values are carried by the ordinary
- entry-point types and interpreted later; they are not confined to a separate
- compatibility importer.
-- **Why 1 does not fit:** Authors, tree entries, modes, branches, and commits all
- have stable intended meanings. The issue is delayed validation and lossy
- fallback, not an unidentifiable core concept.
-- **Rule discrimination:** Decision rule 4 is discriminating here: these are
- common-path invalid-capable intermediate shapes rather than a low-level
- escape hatch unused by the entry path.
-
-### `duplication-knowledge`: 3 (Medium)
-
-- **Evidence:** Important transformations are mostly authoritative:
- `FileMode::{as_i32,from_i32}` contains the mode mapping,
- `BranchStore::write_with` contains branch read/modify/write, and
- `GitAuthor::default` contains the default identity. The narrow repeated
- knowledge is the bare-branch to full-ref transformation
- `format!("refs/heads/{branch}")` in each of
- `Store::{update_ref,resolve_ref,delete_ref}`
- (`src/git.rs:182-225`), with another full-ref rendering at the direct
- workflow metadata boundary. Trailer rendering also spells
- `"{}: {}"` in both `append` and `format_message`
- (`src/trailer.rs:9-65`).
-- **Strongest counterevidence:** The repeated ref syntax is stable low-level Git
- syntax, the three ref methods implement different operations, and the
- apparent duplication in single-entry/multi-entry or tip/commit reads has
- intentionally different result shapes. Unifying those operations would risk
- a parameterized mega-helper.
-- **Why 4 does not fit:** Full-ref and trailer-line rendering have small but real
- second representations rather than one helper/type enforcing each
- transformation.
-- **Why 2 does not fit:** There is no direct evidence of routine changes
- repeatedly synchronizing those stable renderings, and hypothetical future ref
- methods do not satisfy decision rule 5. The repeated knowledge is isolated
- from ordinary checkpoint-format extension.
-- **Rule discrimination:** Rule 5 usefully rules out 2 but is
- non-discriminating between 3 and 4 for repeated, stable protocol syntax. I
- score 3 because the repetitions are concrete, while keeping confidence
- Medium because their maintenance materiality is limited.
-
-## Round 2 revalidation
-
-I independently reapplied the simplified decision rules to only the requested
-assignments. Scores below supersede the corresponding Round 1 judgments for
-this revalidation.
-
-| Component | Lens | Round 2 score | Confidence |
-| --- | --- | ---: | --- |
-| `fabro-http` | duplication-knowledge | 3 | High |
-| `repository-ci` | ownership-boundaries | 2 | High |
-| `fabro-checkpoint` | ownership-boundaries | 2 | High |
-| `fabro-checkpoint` | simplicity | 3 | High |
-| `fabro-checkpoint` | domain-model | 2 | High |
-| `fabro-checkpoint` | duplication-knowledge | 3 | Medium |
-
-### `fabro-http` × `duplication-knowledge`: 3 (High)
-
-- **Decisive evidence:** `define_builder!` remains the one mechanism for the
- materially recurring async/blocking builder policy
- (`src/lib.rs:72-193`). The parser and `InvalidProxyPolicy` message still hold
- a concrete second representation of the allowed `"system"`/`"disabled"`
- vocabulary (`src/lib.rs:29-35,63-69`).
-- **Adjacent scores:** 4 does not fit because revised rule 6 explicitly caps a
- concrete second semantic representation at 3. Score 2 does not fit because an
- ordinary mapped change does not currently synchronize separate async and
- blocking implementations; adding a future policy variant is not direct
- recurrence evidence.
-- **Remaining ambiguity:** None material. Revised rule 6 now resolves the prior
- 3-versus-4 uncertainty.
-
-### `repository-ci` × `ownership-boundaries`: 2 (High)
-
-- **Decisive evidence:** The Rust workflow's architecture check scans
- `apps`, `lib/packages`, and
- `docs/public/api-reference/fabro-api.yaml`
- (`.github/workflows/rust.yml:80-91`), but its push and pull-request triggers
- omit all three routine target paths (`rust.yml:6-19,22-35`). Its Cargo jobs
- also consume the real API specification through
- `lib/foundation/fabro-api/build.rs`, yet that specification does not trigger
- the workflow. The TypeScript workflow likewise consumes the generated API
- client and performs the embedded integration build without making the source
- specification a trigger. Under revised rule 3, each check owns this coverage;
- the omitted routine targets are therefore central ownership pressure.
-- **Adjacent scores:** 3 does not fit because API, app, and package changes are
- routine targets of checks the workflow actually runs, not isolated edge
- inputs. Score 1 does not fit because Rust and TypeScript job ownership and
- dependency direction otherwise remain stable.
-- **Remaining ambiguity:** None material. The nonexistent `openapi/**` value is
- still a separate domain-model finding; the ownership finding rests on the
- real scanned/consumed paths that fail to trigger.
-
-### `fabro-checkpoint` × `ownership-boundaries`: 2 (High)
-
-- **Decisive evidence:** The mapped higher owner is `BranchStore`, but the
- routine production metadata caller instead retains `Store`, branch, author,
- parent, and discovery state and reconstructs blob/tree/commit/ref lifecycle
- from `Store` primitives in
- `fabro-workflow/src/run_metadata.rs:272-451`. Revised rule 2 names this shape
- directly.
-- **Adjacent scores:** 3 does not fit because reconstruction occurs on every
- metadata snapshot, not at an isolated edge. Score 1 does not fit because the
- low-level `Store` and workflow-level caller are stable, identifiable owners;
- the concern is the lifecycle split between them.
-- **Remaining ambiguity:** The workflow reasonably owns remote authentication,
- but that does not remove its reconstruction of the mapped checkpoint and
- metadata-branch persistence lifecycle.
-
-### `fabro-checkpoint` × `simplicity`: 3 (High)
-
-- **Decisive evidence:** The current production `Store` write sequence is
- linear and direct (`src/git.rs:123-188`). `BranchStore` is a parallel mapped
- entry layer with no production caller at this revision, and `Cargo.toml:18`
- declares the unused production dependency `fabro-store`. Revised rule 4
- classifies exactly this as isolated simplicity friction that caps 4 at 3.
-- **Adjacent scores:** 4 does not fit because the parallel unused layer and
- dependency are concrete. Score 2 does not fit because routine callers do not
- navigate competing paths or machinery; they consistently follow the direct
- `Store` path.
-- **Remaining ambiguity:** None material after rule 4. `BranchStore` being a
- mapped entry does not make it frequent when the boundary search finds no
- production caller.
-
-### `fabro-checkpoint` × `domain-model`: 2 (High)
-
-- **Decisive evidence:** Mapped entry shapes accept unrestricted author and path
- strings: `GitAuthor::from_options` stores raw values before
- `BranchStore::new` interprets them with `Signature::now(...).expect(...)`
- (`src/author.rs:22-30`, `src/branch.rs:26-39`), and
- `TreeEntries`/`write_entry` carry unchecked string paths until Git-tree
- construction (`src/git.rs:46-90`, `src/branch.rs:84-109`). Revised rule 5
- says caller validation and a typed destination do not isolate this
- invalid-capable mapped entry.
-- **Adjacent scores:** 3 does not fit because the invalid-capable shapes are on
- mapped entry paths, not a compatibility-only edge. Score 1 does not fit
- because the intended meanings of authors, paths, modes, and commits remain
- stable.
-- **Remaining ambiguity:** None material. Normal callers supplying valid values
- does not make the entry type canonical by construction.
-
-### `fabro-checkpoint` × `duplication-knowledge`: 3 (Medium)
-
-- **Decisive evidence:** Bare branch names are independently rendered as
- `refs/heads/{branch}` in `Store::update_ref`, `resolve_ref`, and `delete_ref`
- (`src/git.rs:182-225`), and trailer lines are independently rendered in
- `trailer::append` and `format_message` (`src/trailer.rs:9-65`). These are
- concrete second semantic representations, so revised rule 6 excludes 4.
-- **Adjacent scores:** 4 does not fit because the second renderings are real.
- Score 2 does not fit because no evidenced ordinary mapped change must
- synchronize the stable Git ref or trailer syntax across those locations;
- future ref operations are hypothetical, while the existing operations have
- distinct behavior.
-- **Remaining ambiguity:** Limited ambiguity remains over whether stable
- protocol syntax is material enough to count as semantic repetition at all.
- Rule 6 does not define that threshold, so confidence remains Medium; if it
- counts, 3 is the rule-directed score.
diff --git a/.chisel/cartography/work/docs.md b/.chisel/cartography/work/docs.md
deleted file mode 100644
index 482b37bea..000000000
--- a/.chisel/cartography/work/docs.md
+++ /dev/null
@@ -1,238 +0,0 @@
-# Documentation cartography scout
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
-
-Instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and the Chisel cartography prompt. Scope is every tracked file under `docs/**`, plus `README.md` and `install.md`.
-
-## Inventory
-
-There are **488** scoped tracked files:
-
-| Area | Files |
-| --- | ---: |
-| `docs/public/**` | 253 |
-| `docs/internal/**` | 82 |
-| `docs/plans/**` | 88 |
-| `docs/brainstorms/**` | 11 |
-| `docs/ideation/**` | 3 |
-| `docs/superpowers/**` | 49 |
-| `README.md`, `install.md` | 2 |
-
-## Proposed components
-
-### `public-documentation` — Public documentation
-
-- **Purpose:** Own the authored Fabro user documentation, Mintlify presentation/configuration, repository landing page, and the maintenance procedure for published web screenshots.
-- **Globs:**
- - `README.md`
- - `docs/public/**`
- - `docs/internal/updating-web-screenshots.md`
-- **Exclude globs:**
- - `docs/public/api-reference/fabro-api.yaml` — separate source contract
- - `docs/public/changelog/**` — separate published release-history component
- - all 22 generated public Graphviz SVG globs listed under exclusions below
-- **Entry points:**
- - `README.md`
- - `docs/public/docs.json`
- - `docs/public/getting-started/introduction.mdx`
- - `docs/public/getting-started/quick-start.mdx`
- - `docs/internal/updating-web-screenshots.md`
-- **Owns:**
- - Mintlify theme, navigation, tabs, and page ordering
- - public concepts, guides, tutorials, administration material, and reference prose
- - public documentation images, manually maintained SVG illustrations, logos, syntax definitions, and curated web screenshots
- - repository-facing overview and documentation links
- - web-screenshot capture and verification workflow
-- **Depends on candidates:** `fabro-http-api-contract`, `documentation-demo-workflows`, the CLI/config components that refresh fenced reference regions.
-- **Evidence:**
- - `AGENTS.md:46-51` mounts `docs/public` as the Mintlify document root.
- - `docs/public/docs.json` declares the Mintlify schema, theme, navigation, OpenAPI tab, and changelog tab.
- - `README.md` links to `docs.fabro.sh` and embeds assets from `docs/public/images` and `docs/public/logo`.
- - `docs/internal/updating-web-screenshots.md` names `docs/public/images/web/` as the screenshot destination, maps files to UI routes and doc consumers, and defines the refresh/verification workflow.
- - `lib/foundation/fabro-dev/src/commands/docs.rs` exposes `cargo dev docs refresh/check`; `docs_cli_reference.rs` and `docs_options_reference.rs` update only fenced regions of `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx`. The two whole files remain assigned here because substantial prose outside those fences is authored.
- - `test/docs/extract_dots.py` extracts workflow examples from the public docs for validation.
-- **Assigned count:** **112**: 110 public-site files after the API contract, changelog, and 22 generated SVGs are removed, plus `README.md` and the screenshot-maintenance guide.
-
-### `public-release-history` — Published changelog
-
-- **Purpose:** Preserve and publish dated user-facing release/change records independently of current reference documentation.
-- **Globs:** `docs/public/changelog/**`
-- **Entry points:** `docs/public/docs.json` changelog navigation; newest page at the assessed revision is `docs/public/changelog/2026-07-25.mdx`.
-- **Owns:** dated titles, migration warnings, feature summaries, and historical behavior notes.
-- **Depends on candidates:** `public-documentation` for Mintlify navigation/presentation.
-- **Evidence:**
- - `docs/public/docs.json` gives changelog its own top-level tab and lists every dated page.
- - The 120 `docs.json` changelog page entries exactly match the 120 tracked MDX files.
- - Each page has date/title frontmatter and describes changes for that date.
- - `lib/apps/fabro-server/tests/it/api/docs.rs:45-50` deliberately reads a changelog page as historical documentation.
-- **Assigned count:** **120**.
-
-### `fabro-http-api-contract` — Fabro HTTP API contract
-
-- **Purpose:** Define the OpenAPI-first wire contract used by the server, generated clients/types, conformance tests, and published API reference.
-- **Globs:** `docs/public/api-reference/fabro-api.yaml`
-- **Entry points:** `docs/public/api-reference/fabro-api.yaml`
-- **Owns:** HTTP routes, request/response schemas, authentication declarations, and API-facing wire documentation.
-- **Depends on candidates:** none at the documentation layer; parent reconciliation should make its consumers depend on this component.
-- **Consumers / evidence:**
- - `AGENTS.md:55-61` explicitly calls this file the source of truth and documents the Rust and TypeScript regeneration workflow.
- - `lib/foundation/fabro-api/build.rs:159` consumes it for Rust generation.
- - `lib/packages/fabro-api-client/package.json:7` consumes it for TypeScript Axios generation.
- - `lib/apps/fabro-server/src/server/handler/system.rs:694` embeds it in the server.
- - `lib/apps/fabro-server/tests/it/openapi_conformance.rs:21` reads it for route/spec conformance.
- - `docs/public/docs.json` points Mintlify's API tab at it.
-- **Assigned count:** **1**.
-
-### `documentation-demo-workflows` — Executable documentation demos
-
-- **Purpose:** Provide runnable workflow definitions and supporting configuration/prompts used by public tutorials and demonstrations.
-- **Globs:**
- - `docs/internal/demo/*.fabro`
- - `docs/internal/demo/*.toml`
- - `docs/internal/demo/prompts/**`
-- **Exclude globs:**
- - `docs/internal/demo/*.svg`
- - `docs/internal/demo/*.png`
-- **Entry points:**
- - `docs/internal/demo/01-hello.fabro`
- - `docs/internal/demo/14-search-imagegen.toml`
- - tutorial commands of the form `fabro run docs/internal/demo/.fabro`
-- **Owns:** small executable example graphs, the image-generation demo run config, and shared demo prompt text.
-- **Depends on candidates:** CLI runner, workflow engine/validator, agent tools, and configured sandbox/model providers.
-- **Evidence:**
- - Public tutorials such as `docs/public/tutorials/hello-world.mdx`, `parallel-review.mdx`, `multi-model.mdx`, `plan-implement.mdx`, and `ensemble.mdx` invoke these paths directly.
- - `docs/public/core-concepts/models.mdx:250-251` also uses these graphs as runnable model examples.
- - `docs/internal/demo/14-search-imagegen.toml` selects its graph, Daytona environment, snapshot, and output assets.
- - `.fabro` files are complete Graphviz workflow entry documents with `goal`, start, and exit nodes.
-- **Assigned count:** **16** (14 `.fabro`, one `.toml`, one prompt).
-
-### `internal-engineering-guidance` — Active engineering policies and architecture references
-
-- **Purpose:** Record active repository-wide engineering policies and maintained architectural/runtime contracts that guide implementation changes.
-- **Globs:**
- - `docs/internal/*-strategy.md`
- - `docs/internal/*-policy.md`
- - `docs/internal/events.md`
- - `docs/internal/fabro-event-schema-v2-concrete-shape.md`
- - `docs/internal/llm-client-resolution.md`
- - `docs/internal/run-directory-keys.md`
-- **Entry points:**
- - `AGENTS.md:136-146`
- - `docs/internal/events-strategy.md`
- - `docs/internal/testing-strategy.md`
- - `docs/internal/error-handling-strategy.md`
-- **Owns:**
- - logging, events, testing, migrations, secret handling, error handling, React-effect, and panic policies
- - the maintained event catalog and implemented V2 event design explanation
- - LLM client-resolution rules, parallel-execution semantics, and run scratch-file reference
-- **Depends on candidates:** the runtime, server, CLI, web, configuration/auth, and workflow components whose contracts it describes. These are documentation dependencies rather than build edges.
-- **Evidence:**
- - `AGENTS.md:136-146` makes seven strategy/policy documents mandatory reading before related changes.
- - `docs/internal/events-strategy.md` distinguishes durable product events from tracing and identifies their consumers.
- - `docs/internal/events.md` is the maintained serialized event catalog and was updated near the assessed revision.
- - `docs/internal/fabro-event-schema-v2-concrete-shape.md:5` says `Status: implemented`; it also says the hand-written Rust types, not this document, are the actual contract source of truth.
- - `docs/internal/parallel-strategy.md:3` says `Status: implemented` and was updated with the shared-checkout behavior at the assessed revision.
- - `lib/foundation/fabro-vault/src/store.rs:359` links implementation documentation back to `docs/internal/migrations-strategy.md`.
-- **Assigned count:** **13**.
-
-### `product-context` — Internal product framing
-
-- **Purpose:** Maintain concise product intent, audience, current shape, success signals, and stable technical/product constraints.
-- **Globs:** `docs/internal/product/**`
-- **Entry points:**
- - `docs/internal/product/product-description.md`
- - `docs/internal/product/current-state.md`
-- **Owns:** business problem, personas, product description, current-state snapshot, success metrics, and product-level technical requirements.
-- **Depends on candidates:** none as a build edge; it informs product and documentation work across the repository.
-- **Evidence:**
- - The six documents have complementary named roles rather than dated implementation tasks.
- - `docs/internal/product/current-state.md` explicitly describes a deliberately brief current product snapshot.
- - `docs/internal/product/technical-requirements.md` explicitly calls its contents stable constraints product changes should respect.
-- **Assigned count:** **6**.
-
-## Cross-scope assignment
-
-### `install.md` -> marketing-site component
-
-- **Count:** **1**.
-- `install.md` is a tracked mode-`120000` symlink to `apps/marketing/public/install.md`.
-- Commit `0cc02c294dac23e3ace7646528431e758e37eea1` states that Vercel deploys the marketing subtree, so the real file lives there and the repository-root path is a symlink.
-- `apps/marketing/src/pages/index.astro` advertises `https://fabro.sh/install.md`.
-- The root alias should therefore be claimed by the component that owns `apps/marketing/public/install.md`, rather than by `public-documentation`.
-
-## Evidence-backed exclusions
-
-### Historical brainstorm, plan, audit, and design records — 159 files
-
-These are point-in-time requirements, ideation, implementation plans, handoffs, one-time QA instructions, measurements, audits, or superseded proposals. They remain useful history but are not active source contracts or maintained policy components.
-
-| Glob/path | Count | Evidence |
-| --- | ---: | --- |
-| `docs/brainstorms/**` | 11 | Dated `*-requirements.md` brainstorm artifacts. |
-| `docs/ideation/**` | 3 | Dated ideation records. |
-| `docs/plans/**` | 88 | Dated implementation plans and handoffs. |
-| `docs/superpowers/plans/**` | 45 | Dated execution plans. |
-| `docs/superpowers/specs/**` | 4 | Dated feature/design specs. |
-| `docs/internal/cargo-target-apfs-churn-plan.md` | 1 | Checkbox execution plan with an unfilled results section. |
-| `docs/internal/cli-workflow-coupling-audit.md` | 1 | Snapshot audit organized around completed and remaining couplings. |
-| `docs/internal/event-schema-competitive-analysis.md` | 1 | Dated comparative research report. |
-| `docs/internal/fabro-event-schema-v2-proposal.md` | 1 | Explicit `Status: proposal`; the implemented concrete-shape document supersedes its framing. |
-| `docs/internal/mcp-server-qa-test-plan.md` | 1 | Explicitly says it is a one-time manual QA pass, not a reusable testing template. |
-| `docs/internal/plan-events-as-source-of-truth-follow-ups.md` | 1 | Prerequisite implementation plan. |
-| `docs/internal/plan-events-as-source-of-truth.md` | 1 | Implementation plan/summary rather than current contract reference. |
-| `docs/internal/slow-test-opportunities-2026-04-07.md` | 1 | Dated measurement dataset and implementation-status record. |
-
-This exclusion does **not** include `docs/public/changelog/**`: the changelog is a live, complete Mintlify publication surface and is mapped as its own component.
-
-### Generated Graphviz renderings — 44 files
-
-| Glob/path | Unique count | Evidence |
-| --- | ---: | --- |
-| `docs/internal/demo/*.svg` | 11 | Every file contains `Generated by graphviz`; each has a same-stem `.fabro` source. |
-| `docs/internal/demo/*.png` | 11 | Same-stem raster renderings were introduced alongside the `.fabro` and generated SVG files; their pixel dimensions match the SVG point dimensions at Graphviz's 96-DPI raster scale. |
-| `docs/public/images/*-workflow.svg` | 9 | Every matching tracked file contains `Generated by graphviz`. |
-| `docs/public/images/tutorial-*.svg` | 10 | Every matching tracked file contains `Generated by graphviz`; one file overlaps the previous glob. |
-| `docs/public/images/brave-search-research.svg` | 1 | Contains `Generated by graphviz`. |
-| `docs/public/images/how-fabro-works.svg` | 1 | Contains `Generated by graphviz`. |
-| `docs/public/images/nlspec-conformance.svg` | 1 | Contains `Generated by graphviz`. |
-| `docs/public/images/plan-implement-readme.svg` | 1 | Contains `Generated by graphviz`. |
-
-The public SVG rows resolve to **22 unique files** because `tutorial-sub-workflow.svg` matches both broad globs. Curated UI screenshots and hand-authored SVG illustrations remain assigned to `public-documentation`; `docs/internal/updating-web-screenshots.md` establishes their manual capture and verification workflow.
-
-The fenced regions in `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx` are generated, but the files are mixed authored/generated documents. Cartography operates at file granularity, so both whole files stay assigned to `public-documentation`.
-
-### Vendored third-party legal text — 1 file
-
-- **Glob:** `docs/internal/licenses/graphviz-14.1.5-LICENSE`
-- **Count:** **1**.
-- **Evidence:** the filename pins Graphviz 14.1.5, the contents are the verbatim Eclipse Public License 2.0 plus secondary-license text, and the introducing commit is `chore: add vendored Graphviz license to docs-internal/licenses`.
-
-## Unmapped files
-
-- **Glob:** `docs/internal/assets/**`
-- **Count:** **15**.
-- These form a coherent collection of logos, palette mockups, headers, and HTML/PNG social-card pairs, but no tracked file consumes these exact paths at the assessed revision.
-- `docs/internal/updating-web-screenshots.md` identifies `docs/public/logo/dark.svg` and `docs/public/logo/light.svg`, not the internal assets, as the source-of-truth logos.
-- The collection has no manifest, status marker, or documented update workflow establishing whether it is maintained brand source, derived output, or historical design collateral. It should remain unmapped until that ownership is confirmed.
-
-## Coverage
-
-| Disposition | Count |
-| --- | ---: |
-| Assigned to proposed documentation components | 268 |
-| Cross-scope assignment (`install.md` to marketing site) | 1 |
-| **Assigned total** | **269** |
-| Excluded historical records | 159 |
-| Excluded generated renderings | 44 |
-| Excluded vendored license | 1 |
-| **Excluded total** | **204** |
-| Unmapped internal brand collateral | 15 |
-| **Scoped relevant total** | **488** |
-
-`269 + 204 + 15 = 488`; every scoped tracked file is assigned, excluded, or explicitly unmapped.
-
-## Open questions
-
-1. Are the 15 files under `docs/internal/assets/**` maintained brand sources, or intentionally retained historical collateral? A component should be added only if an owner/update workflow confirms the former.
-2. Should the parent map keep `docs/internal/fabro-event-schema-v2-concrete-shape.md` in active engineering guidance, as proposed here based on `Status: implemented` and recent updates, or treat it as an implemented design record now that Rust event types and `events.md` carry the live contract?
-3. Confirm the final marketing component ID that will claim the `install.md` symlink together with `apps/marketing/public/install.md`.
diff --git a/.chisel/cartography/work/ops.md b/.chisel/cartography/work/ops.md
deleted file mode 100644
index ef4b6c16a..000000000
--- a/.chisel/cartography/work/ops.md
+++ /dev/null
@@ -1,461 +0,0 @@
-# Repository operations cartography scout
-
-Assessed revision:
-`2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`).
-
-Owned scope: root-level tracked files plus tracked files under `.ai/**`,
-`.cargo/**`, `.claude/**`, `.config/**`, `.fabro/**`, `.github/**`,
-`bin/**`, `docker/**`, and `installer/**`. Files under `lib/**`, `apps/**`,
-`docs/**`, `test/**`, and `evals/**` were not counted. The
-`lib/foundation/fabro-dev/**` and `lib/foundation/build-support/**` trees were
-consulted only as boundary and dependency evidence because the foundation
-scout owns them.
-
-Applicable instructions read: `AGENTS.md`, its `CLAUDE.md` symlink, and
-`CONTRIBUTING.md`.
-
-## Inventory and boundary approach
-
-- `git ls-tree -r --name-only` at the assessed revision yields exactly 143
- tracked files in this scope: 24 root files, four under `.ai/`, one under
- `.cargo/`, eight under `.claude/`, one under `.config/`, 87 under `.fabro/`,
- seven under `.github/`, one under `bin/`, eight under `docker/`, and two
- under `installer/`.
-- Repository-wide manifests, tool configuration, and contributor rules are
- grouped as one development-policy component. They form the shared contract
- used by Cargo, Bun, nextest, rustfmt, Clippy, contributors, coding agents,
- and CI; splitting every configuration file would create small boundaries
- without independent entry points.
-- Pull-request CI and release automation are separate. The former validates
- changes on branch events, while the latter owns version tags and publication
- of binary, container, GitHub Release, and Homebrew artifacts.
-- Product container packaging and operator Compose deployment are grouped
- because the image layout, entrypoint, runtime environment, proxy files, and
- Compose stacks share one deployable artifact contract. The explicit
- split-web proof-of-concept is retained in this proposed component, with the
- question noted below.
-- `.fabro/project.toml`, its development image, and the named workflow catalog
- are grouped as the repository's Fabro-native automation surface. They share
- the `fabro run ` consumer, project defaults, clone-based execution
- environment, and repository-maintenance lifecycle.
-- The smaller `.ai`, `.claude`, and `bin/agent` families are grouped as coding
- agent automation. Their clients differ, but all supply repository-local
- prompts, skills, hooks, or helper commands to agents working on this
- repository.
-- Machine-produced state, a backup, vendored policy text, non-runtime review
- assets, legal/overview metadata, and canonical-file symlink aliases are
- excluded with exact counts below.
-
-## Proposed components
-
-### `repository-development-policy` — Repository development policy
-
-- **Assigned file count:** 11
-- **Purpose:** Defines the repository-wide Rust and JavaScript workspace,
- dependency, formatting, lint, test, version-control, contributor, and coding
- agent development contract.
-- **Globs:**
- - `.cargo/**`
- - `.config/**`
- - `.gitattributes`
- - `.gitignore`
- - `AGENTS.md`
- - `CONTRIBUTING.md`
- - `Cargo.toml`
- - `package.json`
- - `bunfig.toml`
- - `clippy.toml`
- - `rustfmt.toml`
-- **Exclude globs:** none
-- **Entry points:**
- - `Cargo.toml:[workspace]`
- - `Cargo.toml:[workspace.dependencies]`
- - `Cargo.toml:[workspace.lints]`
- - `package.json:workspaces`
- - `.cargo/config.toml:[alias]`
- - `.config/nextest.toml`
- - `AGENTS.md`
- - `CONTRIBUTING.md`
-- **Owns:** Rust and Bun workspace membership; shared Rust dependency and
- version policy; workspace lint and compilation profiles; Bun linker
- selection; Cargo developer aliases and test proxy policy; nextest timeout
- profiles; rustfmt and Clippy policy; tracked/generated path treatment; and
- repository-wide contributor and agent instructions.
-- **Depends-on candidates:** `fabro-build-tooling` (the `cargo dev` alias
- dispatches to its feature-gated binary).
-- **Evidence:**
- - `Cargo.toml` — declares all Rust workspace members, default members,
- workspace package metadata, shared dependencies, lint policy, and build
- profiles.
- - `package.json` and `bunfig.toml` — declare the JavaScript workspace and
- deterministic Bun workspace linker contract.
- - `.cargo/config.toml` — exposes `cargo dev` as the CLI entry to
- `fabro-dev`, defines the test alias, and supplies the repository test
- proxy-policy environment.
- - `.config/nextest.toml`, `clippy.toml`, and `rustfmt.toml` — are direct
- configuration inputs to the repository's test, lint, and formatting
- commands.
- - `AGENTS.md` and `CONTRIBUTING.md` — define the repository-wide build/test
- commands, architectural policies, and contribution workflow.
- - `.gitattributes` and `.gitignore` — actively define generated-file
- classification and the source/output boundary used by developers and CI.
- - `lib/foundation/fabro-dev/Cargo.toml` and
- `lib/foundation/fabro-dev/src/lib.rs:Command` — out-of-scope evidence that
- the Cargo alias targets a distinct internal development CLI.
-
-### `repository-ci` — Pull-request and branch continuous integration
-
-- **Assigned file count:** 3
-- **Purpose:** Runs branch and pull-request validation for the Rust and
- TypeScript workspaces and configures static validation of GitHub Actions
- workflows.
-- **Globs:**
- - `.github/workflows/rust.yml`
- - `.github/workflows/typescript.yml`
- - `.github/zizmor.yml`
-- **Exclude globs:** none
-- **Entry points:**
- - `.github/workflows/rust.yml`
- - `.github/workflows/typescript.yml`
- - `.github/zizmor.yml`
-- **Owns:** branch/path trigger policy; Rust format, lint, generated-doc, test,
- and twin-E2E jobs; TypeScript typecheck, test, and production-build jobs;
- concurrency cancellation; CI test profile selection; and repository-local
- workflow-linter exceptions.
-- **Depends-on candidates:** `repository-development-policy`,
- `fabro-build-tooling`, `fabro-web-app`,
- `fabro-api-client-generation`, and `twin-openai`. The workflows are also
- integration consumers of the full Rust workspace rather than a production
- runtime dependency of each Rust component.
-- **Evidence:**
- - `.github/workflows/rust.yml` — path-gates Rust-relevant changes and runs
- the pinned formatter, Clippy, generated-document check, workspace nextest
- suite, and selected twin-mode E2E packages.
- - `.github/workflows/typescript.yml` — installs the frozen Bun workspace,
- typechecks the web app and generated-client package, runs web tests, and
- invokes `cargo dev build` for the release-style embedded-SPA build.
- - `.github/zizmor.yml` — is consumed alongside those workflows and names
- workflow-specific action-reference exceptions.
- - `lib/foundation/fabro-dev/src/commands/build.rs` — out-of-scope evidence
- that `cargo dev build` refreshes the SPA and then forwards to Cargo build.
-
-### `release-distribution-automation` — Release and package publication
-
-- **Assigned file count:** 4
-- **Purpose:** Cuts nightly releases and publishes versioned CLI archives,
- GitHub Releases, multi-architecture container images, attestations, and
- stable/nightly Homebrew formulas.
-- **Globs:**
- - `.github/workflows/nightly.yml`
- - `.github/workflows/release.yml`
- - `installer/**`
-- **Exclude globs:** none
-- **Entry points:**
- - `.github/workflows/nightly.yml`
- - `.github/workflows/release.yml`
- - `installer/fabro.rb.template`
- - `installer/fabro-nightly.rb.template`
-- **Owns:** scheduled nightly tag creation; cross-platform release target
- matrix; CLI archive/checksum generation; provenance attestations; GitHub
- Release creation; release container publication; stable and nightly release
- channel selection; and Homebrew formula template substitution/publication.
-- **Depends-on candidates:** `repository-development-policy`,
- `fabro-build-tooling`, `container-packaging-and-deployment`, `fabro-cli`,
- and `fabro-spa`.
-- **Evidence:**
- - `.github/workflows/nightly.yml` — mints the release-app token and invokes
- `cargo --locked dev release --nightly` after ensuring the current commit
- does not already have a nightly tag.
- - `.github/workflows/release.yml` — is triggered by version tags, compiles
- and packages five targets, attests archives and container images, creates
- the GitHub Release, publishes the multi-architecture image, and updates
- stable or nightly Homebrew formulas.
- - `installer/fabro.rb.template` and
- `installer/fabro-nightly.rb.template` — define the platform archive URLs,
- checksum placeholders, installed binary, and Homebrew smoke test consumed
- by the release workflow.
- - `lib/foundation/fabro-dev/src/commands/release.rs` — out-of-scope evidence
- that the developer CLI owns release version computation, test smoke,
- `Cargo.toml`/`Cargo.lock` update, commit, tag, and push before the tag
- workflow publishes artifacts.
- - `lib/foundation/fabro-dev/src/commands/docker_build.rs` — out-of-scope
- evidence that local image construction intentionally shares the release
- pipeline's `tmp/docker-context//fabro` layout.
-
-### `container-packaging-and-deployment` — Container packaging and deployment
-
-- **Assigned file count:** 16
-- **Purpose:** Packages the Fabro CLI/server as a runtime container and
- defines supported local, production, Tailscale, and split-web Compose
- deployments around that image.
-- **Globs:**
- - `.dockerignore`
- - `.env.example`
- - `Dockerfile`
- - `docker-compose*.yaml`
- - `docker/**`
-- **Exclude globs:** none
-- **Entry points:**
- - `Dockerfile`
- - `docker/entrypoint.sh`
- - `docker/preflight.sh`
- - `docker-compose.yaml`
- - `docker-compose.prod.yaml`
- - `docker-compose.tailscale.yaml`
- - `docker-compose.split-web.yaml`
-- **Owns:** staged multi-architecture binary image layout; runtime package and
- unprivileged-user setup; storage-home and Docker-socket group handoff;
- deployment environment contract; preflight resource/daemon/network checks;
- Caddy proxy/TLS behavior; Compose services, volumes, ports, and health
- checks; and the split static-web/API deployment configuration.
-- **Depends-on candidates:** `fabro-cli`, `fabro-server`, `fabro-web-app`, and
- `fabro-build-tooling`.
-- **Evidence:**
- - `Dockerfile` — consumes the architecture-specific binary staged under
- `tmp/docker-context`, installs runtime dependencies, and installs the
- shared entrypoint.
- - `docker/entrypoint.sh` — owns storage permissions, Docker socket group
- mapping, and privilege drop before launching Fabro.
- - `docker/preflight.sh` — is a standalone deployment readiness entry point
- for Docker version/daemon, Compose, CPU, memory, disk, port, and registry
- reachability.
- - `docker-compose.yaml`, `docker-compose.local.yaml`,
- `docker-compose.prod.yaml`, and `docker-compose.tailscale.yaml` — define
- distinct operator compositions around the same Fabro image and runtime
- state.
- - `docker-compose.split-web.yaml` and `docker/split-web/**` — jointly own the
- alternate edge/API/static-web composition; the local README documents its
- request ownership and validation commands.
- - `.github/workflows/release.yml` and
- `lib/foundation/fabro-dev/src/commands/docker_build.rs` — release and local
- developer consumers both stage the same per-architecture context consumed
- by the root Dockerfile.
-
-### `fabro-repository-automation` — Fabro-native repository automation
-
-- **Assigned file count:** 41
-- **Purpose:** Configures Fabro's own development environment and supplies the
- named workflow graphs, prompts, permissions, and project defaults used for
- repository maintenance, integration demonstrations, and workflow examples.
-- **Globs:**
- - `.fabro/Dockerfile`
- - `.fabro/project.toml`
- - `.fabro/workflows/**`
-- **Exclude globs:**
- - `.fabro/workflows/goal/workflow.svg`
-- **Entry points:**
- - `.fabro/project.toml`
- - `.fabro/workflows/*/workflow.toml`
- - `.fabro/workflows/*/workflow.fabro`
- - `.fabro/workflows/implement-plan/workflow.fabro`
- - `.fabro/workflows/patch-cves/workflow.fabro`
- - `.fabro/workflows/pr-simplify/workflow.fabro`
- - `.fabro/workflows/smoke/workflow.fabro`
-- **Owns:** repository-level pull-request defaults; the `fabro-dev` Daytona
- environment and resource/lifecycle labels; its browser-capable Rust/Bun
- development image; named workflow graph catalog; workflow-local prompts;
- GitHub integration permissions; and repository verification/maintenance
- command sequences.
-- **Depends-on candidates:** `fabro-cli`, `fabro-config`, `fabro-workflow`,
- `fabro-graphviz`, `fabro-sandbox`, `fabro-github`,
- `fabro-build-tooling`, and `repository-development-policy`.
-- **Evidence:**
- - `.fabro/project.toml` — is the project-level Fabro configuration entry,
- selecting the Daytona environment, `.fabro/Dockerfile`, resource limits,
- lifecycle, labels, and pull-request defaults.
- - `.fabro/Dockerfile` — supplies the clone-based workflow environment with
- Git, ripgrep, browser/desktop support, GitHub CLI, pinned Rust tooling,
- nextest, and Bun.
- - `.fabro/workflows/*/workflow.toml` — provides per-workflow graph selection,
- environment overrides, pull-request behavior, and GitHub token
- permissions.
- - `.fabro/workflows/*/workflow.fabro` — provides independently runnable
- Graphviz workflow entries for demos, human interaction, GitHub
- operations, implementation, verification, maintenance, and smoke tests.
- - `.fabro/workflows/implement-plan/workflow.fabro` — invokes the
- repository's Cargo/Bun verification contract and `cargo dev` generated-doc
- and SPA lifecycle, tying maintenance workflows to the same developer
- tooling as CI.
- - `.fabro/workflows/patch-cves/**` and
- `.fabro/workflows/pr-simplify/**` — pair bundled prompts with the explicit
- GitHub permissions and pull-request behavior needed by repository
- maintenance runs.
- - `AGENTS.md` — documents `fabro run ` as resolving
- `.fabro/workflows//workflow.toml`, establishing the catalog's common
- consumer.
-
-### `coding-agent-automation` — Repository coding-agent automation
-
-- **Assigned file count:** 11
-- **Purpose:** Supplies repository-local code-review prompts, documentation
- and changelog skills, edit hooks, and an image-generation helper to external
- coding-agent clients.
-- **Globs:**
- - `.ai/prompts/**`
- - `.claude/settings.json`
- - `.claude/skills/**`
- - `bin/agent/**`
-- **Exclude globs:**
- - `.claude/skills/*/watermark`
-- **Entry points:**
- - `.ai/prompts/code-review-fast.md`
- - `.ai/prompts/code-review-deep-1.md`
- - `.claude/skills/changelog/SKILL.md`
- - `.claude/skills/docs/SKILL.md`
- - `.claude/settings.json`
- - `bin/agent/imagegen`
-- **Owns:** fast and multi-stage deep code-review orchestration prompts;
- changelog selection and MDX formatting procedure; code-to-documentation
- mapping and update procedure; post-edit Rust formatting hook; and the
- command-line Gemini image request/output flow.
-- **Depends-on candidates:** `public-documentation` and
- `public-release-history` are data/format consumers of the two skills; the
- remaining prompts and helper use external agent, GitHub CLI, Git, and Gemini
- interfaces rather than product runtime components.
-- **Evidence:**
- - `.ai/prompts/code-review-deep-{1,2,3}.md` — define a three-artifact review
- pipeline from candidate discovery through analysis and false-positive
- filtering.
- - `.ai/prompts/code-review-fast.md` — defines pull-request eligibility,
- parallel review/confidence filtering, and the GitHub comment output
- contract.
- - `.claude/skills/changelog/SKILL.md` and its references — define the
- Git-history-to-Mintlify changelog workflow and output format.
- - `.claude/skills/docs/SKILL.md` and its mapping reference — define the
- Git-history-to-public-doc update workflow and map implementation paths to
- published documentation pages.
- - `.claude/settings.json` — registers the repository-local post-edit Rust
- formatting hook.
- - `bin/agent/imagegen` — is an executable helper that loads repository
- environment credentials, calls the Gemini image endpoint, and writes the
- decoded image.
-
-## Evidence-backed exclusions
-
-### Vendored Rust style-guide skill
-
-- **Glob:** `.fabro/skills/rust-style-guide/**`
-- **Count:** 44 tracked files.
-- **Reason/evidence:** Commit `9af0296469b902c9780a983dee5bee07b0abbcdf`
- explicitly records all 44 files as vendored from
- `brynary/rust-style-guide` commit `8fd2a4f`, trimmed to the runtime skill
- payload. The files are copied policy/procedure content rather than authored
- implementation owned by this repository. The skill entry point also routes
- readers across the copied `guidelines/**` and `workflows/**` payload.
-
-### Dependency resolution outputs
-
-- **Paths:** `Cargo.lock`, `bun.lock`
-- **Count:** two tracked files.
-- **Reason/evidence:** These are machine-maintained dependency resolution
- snapshots. `lib/foundation/fabro-dev/src/commands/release.rs` explicitly
- runs `cargo update --workspace` and stages `Cargo.lock`, while all CI/release
- consumers use Cargo `--locked` or Bun `--frozen-lockfile`; the manifests and
- policies that generate and consume them remain assigned.
-
-### Skill watermarks
-
-- **Glob:** `.claude/skills/*/watermark`
-- **Count:** two tracked files.
-- **Reason/evidence:** Each file is a commit SHA used as generated progress
- state. `.claude/skills/changelog/SKILL.md` and
- `.claude/skills/docs/SKILL.md` each explicitly instruct their workflow to
- overwrite its watermark with `git rev-parse HEAD`.
-
-### Project configuration backup
-
-- **Path:** `.fabro/project.toml.bak`
-- **Count:** one tracked file.
-- **Reason/evidence:** The `.bak` file preserves the previous inline
- `[run.sandbox.daytona]`/snapshot configuration, while
- `.fabro/project.toml` is the canonical current project configuration and
- points to the separate `.fabro/Dockerfile`.
-
-### Non-runtime workflow and review assets
-
-- **Paths:** `.fabro/workflows/goal/workflow.svg`, `.github/assets/**`
-- **Count:** three tracked files: one SVG workflow illustration and two PNG
- screenshots.
-- **Reason/evidence:** The goal workflow's runtime TOML points to
- `workflow.fabro`, not the SVG, and the SVG has no tracked runtime consumer.
- Commit `ac32963538f4441d40a47fcfcd868ca290d2b899` identifies the two PNGs as
- live screenshots captured for a web-feature pull request and says they are
- safe to remove from that change; no tracked source references them at the
- assessed revision.
-
-### Canonical-file symlink aliases
-
-- **Paths:** `CLAUDE.md`, `install.sh`, `install.md`
-- **Count:** three tracked symlinks.
-- **Reason/evidence:** Git records each with mode `120000`. Their targets are
- `AGENTS.md`, `apps/marketing/public/install.sh`, and
- `apps/marketing/public/install.md`, respectively. The canonical instruction
- file is assigned above, while the canonical install resources are owned by
- the web scout's `fabro-marketing-site`; excluding aliases prevents the same
- content from being assessed twice.
-
-### Root overview and legal metadata
-
-- **Paths:** `README.md`, `LICENSE.md`
-- **Count:** two tracked files.
-- **Reason/evidence:** `README.md` is the repository/product landing document
- and routes readers to the public installation and documentation surfaces;
- it does not define an independently executable or state-owning boundary.
- `LICENSE.md` is the repository's MIT legal text. Neither should form a
- quality-scored implementation component on its own.
-
-## Coverage ledger
-
-| Classification | Files |
-| --- | ---: |
-| `repository-development-policy` | 11 |
-| `repository-ci` | 3 |
-| `release-distribution-automation` | 4 |
-| `container-packaging-and-deployment` | 16 |
-| `fabro-repository-automation` | 41 |
-| `coding-agent-automation` | 11 |
-| Vendored Rust style-guide skill | 44 |
-| Dependency resolution outputs | 2 |
-| Skill watermarks | 2 |
-| Project configuration backup | 1 |
-| Non-runtime workflow and review assets | 3 |
-| Canonical-file symlink aliases | 3 |
-| Root overview and legal metadata | 2 |
-| **Total** | **143** |
-
-Computed scope coverage:
-
-- **Relevant tracked files:** 143
-- **Assigned to proposed components:** 86
-- **Excluded with evidence:** 57
-- **Unmapped:** 0
-
-The component and exclusion patterns above were resolved against the assessed
-revision's `git ls-tree` inventory. They are disjoint, and
-`86 + 57 + 0 = 143`.
-
-## Open boundary questions
-
-1. Should `repository-development-policy` remain one repository-wide
- developer contract, or should the final map separate executable
- workspace/tool configuration from the contributor/agent governance in
- `AGENTS.md` and `CONTRIBUTING.md`?
-2. Should `container-packaging-and-deployment` split into an image-packaging
- component and an operator Compose-deployment component? The root
- `Dockerfile` has a release/local-build lifecycle, while the Compose/Caddy
- files own runtime topology, but both share the image and entrypoint
- contract.
-3. Should the explicitly named split-web proof-of-concept remain inside the
- container deployment component, become a separate experimental deployment
- component, or be excluded as non-production material?
-4. Should `.fabro/project.toml` and `.fabro/Dockerfile` remain with the named
- workflow catalog? They share the Fabro project/run consumer today, but the
- environment image and project defaults could change independently from
- individual graphs.
-5. Should the small `.ai`, `.claude`, and `bin/agent` families remain grouped
- as `coding-agent-automation`, or does the final map need separate
- review-automation and documentation-maintenance boundaries despite their
- small file counts?
-6. Should root `README.md` remain excluded as repository overview metadata,
- or should it be folded into the docs scout's `public-documentation`
- component even though it sits outside `docs/**`?
diff --git a/.chisel/cartography/work/review.md b/.chisel/cartography/work/review.md
deleted file mode 100644
index e71fa8395..000000000
--- a/.chisel/cartography/work/review.md
+++ /dev/null
@@ -1,198 +0,0 @@
-# Independent cartography review
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
-
-Reviewed artifact:
-`.chisel/cartography/work/candidate-codebase-map.json`.
-
-This review is limited to component boundaries, dependencies, evidence, and
-file disposition. It does not assess implementation quality.
-
-## Independent inventory check
-
-I resolved the fixed tree with `git ls-tree -r --name-only` and matched every
-component glob, component exclusion, global exclusion, and declared unmapped
-path independently of the candidate's renderer.
-
-- Tracked files: **3,104**
-- Candidate claims: **2,256**
-- Candidate global exclusions: **848**
-- Candidate unmapped files: **0**
-- Files without a disposition: **0**
-- Files claimed by multiple components, or both claimed and globally excluded:
- **0**
-- Overlap between separate global-exclusion entries: **0**
-
-The candidate's mechanical accounting is therefore correct as written.
-Component IDs are unique, all named dependencies resolve, all globs resolve,
-and every evidence/entry-point path exists in the fixed tree. A symbol-text
-check also found no missing Rust/TypeScript symbols among the qualified
-references; the one non-symbol qualifier is the valid JSON property reference
-`package.json:scripts.generate`.
-
-Mechanical coverage does not settle whether each disposition or boundary is
-architecturally correct. The supported corrections below change the
-classification of 15 files but leave the total inventory unchanged.
-
-## Supported corrections
-
-### 1. Move `docs/internal/assets/**` from global exclusion to `unmapped_files`
-
-All 15 files under `docs/internal/assets/**` are currently excluded because
-they have no tracked consumer or documented update workflow. That establishes
-that ownership is unresolved; it does not establish that the SVG, HTML, and
-raster files are generated, vendored, build output, or historical records.
-The candidate's own open question likewise asks whether they are maintained
-brand sources.
-
-Until that question is answered, exclusion asserts more than the evidence
-supports. Preserve the open question and list the 15 exact tracked paths as
-unmapped. This changes coverage to **2,256 assigned, 833 excluded, 15
-unmapped**.
-
-### 2. Restore `fabro-spa` as a separate component
-
-`lib/apps/fabro-spa/Cargo.toml` declares an independent Rust package with the
-specific responsibility “Embedded production SPA assets for Fabro.”
-`lib/apps/fabro-spa/src/lib.rs` exposes the server-facing `get` and
-`AssetBytes` interface, owns compile-time embedding and hashes, and is consumed
-directly by `lib/apps/fabro-server/src/static_files.rs` and
-`lib/apps/fabro-server/src/csp.rs`.
-
-Folding those two assigned files into `fabro-web-app` combines a browser
-application with a Rust server adapter that has a different entry point,
-consumer, toolchain, and reason to change. It also turns the precise dependency
-`fabro-server -> fabro-spa` into the over-broad
-`fabro-server -> fabro-web-app`.
-
-Add a `fabro-spa` component for `lib/apps/fabro-spa/Cargo.toml` and
-`lib/apps/fabro-spa/src/**`; retain `lib/apps/fabro-spa/assets/**` as the
-evidence-backed generated-output exclusion. Remove those assigned paths from
-`fabro-web-app`, replace the server's web-app edge with
-`fabro-server -> fabro-spa`, and let the SPA refresh tooling express the
-build-time connection to the browser app.
-
-The two-file size is not by itself a reason to hide this package: it has a
-manifest, public interface, owned compile-time lifecycle, and independent
-consumer boundary, the same kind of evidence used to retain other small Rust
-components in the candidate.
-
-### 3. Separate `fabro-build-support` from `fabro-build-tooling`
-
-`lib/foundation/build-support/Cargo.toml` is an independent package whose only
-responsibility is build-script Git/profile metadata.
-`lib/foundation/build-support/git_metadata.rs` exposes that public API, and
-the direct consumers are `lib/apps/fabro-cli/build.rs` and
-`lib/apps/fabro-server/build.rs`.
-
-The remaining `fabro-dev` package is an executable repository-development CLI
-with SPA, documentation, release, benchmark, and container command
-lifecycles. Combining these packages hides shared compile-time infrastructure
-inside an unrelated command application; the candidate purpose has to join
-“runs repository ... automation” with “supplies compile-time Git metadata” to
-cover both.
-
-Add a `fabro-build-support` component for
-`lib/foundation/build-support/**`. Keep `lib/foundation/fabro-dev/**`,
-`test/bin/release_test.sh`, and `test/analysis/bench-tests-diff.sql` in the
-existing development-tooling component. Add
-`fabro-cli -> fabro-build-support` and
-`fabro-server -> fabro-build-support`, which are explicit Cargo build
-dependencies.
-
-### 4. Correct the shared fixture dependency direction
-
-`workflow-test-corpus` is inert input data. The candidate evidence identifies
-the readers:
-
-- `fabro-test` resolves files beneath `../../../test/`;
-- `fabro-cli` source/tests install the root and template fixtures;
-- `fabro-graphviz` and `fabro-validate` enumerate
- `test/dot-compatibility`;
-- `fabro-workflow` enumerates `test/attractor`.
-
-Those consumers depend on the corpus, just as the generated API clients depend
-on their source contract. The candidate currently records the reverse and
-also names `fabro-template`, for which there is no direct corpus read.
-
-Make `workflow-test-corpus.depends_on` empty, add
-`workflow-test-corpus` to the five direct consumer components above, and omit
-the unsupported `fabro-template` edge. This correction does not require
-redistributing the shared files.
-
-### 5. Add direct operational dependencies omitted from
-`fabro-build-tooling`
-
-The candidate's purpose and evidence include operations whose source contains
-explicit repository-component dependencies, but its dependency list contains
-only Cargo library dependencies:
-
-- `docs_cli_reference.rs` invokes `fabro-cli` and writes
- `docs/public/reference/cli.mdx`;
-- `docs_options_reference.rs` writes the same public-documentation surface;
-- `spa_refresh.rs` invokes the build in `apps/fabro-web` and mirrors its output
- into `lib/apps/fabro-spa/assets`;
-- `docker_build.rs` runs the root container build;
-- `release.rs` reads and updates the root Cargo workspace contract.
-
-Add dependencies from `fabro-build-tooling` to `fabro-cli`,
-`public-documentation`, `fabro-web-app`, the restored `fabro-spa`,
-`container-packaging-and-deployment`, and
-`repository-development-policy`. These are the same operational dependency
-kind already used for CI, release, repository-workflow, and documentation
-components; omitting them only for the development CLI makes the graph
-inconsistent.
-
-### 6. Add `public-documentation -> public-release-history`
-
-`docs/public/docs.json`, owned by `public-documentation`, enumerates every
-changelog page and gives the collection its top-level publication surface.
-The existing `public-release-history -> public-documentation` edge captures
-the changelog's dependence on Mintlify presentation, but it omits the direct
-navigation/configuration dependency in the other direction. Retain the
-existing edge and add the reciprocal edge.
-
-## Optional boundary questions
-
-These are plausible alternatives, but the fixed revision does not require
-them as corrections:
-
-1. **First-run web installer.** The 14 install/mode files have a distinct
- router, reducer, API facade, storage token, and lifecycle, so a
- `fabro-web-install` component is supportable now; it does not need a
- separate binary entry point to qualify. On the other hand, it is selected
- by the shared browser entry and imports the app's common UI/runtime. For the
- recommended map, keep it in `fabro-web-app` and preserve this as an open
- boundary question. Splitting it would raise the component count by one.
-2. **Shared workflow corpus ownership.** Its cross-crate consumers justify the
- shared corpus component. Distributing the root/template, Attractor, and DOT
- compatibility subcorpora to their consumers is also possible, but would
- make the DOT corpus arbitrarily owned by one of two readers. Retain the
- shared component unless later assessment proves its combined boundary
- noisy.
-3. **Workflow, LLM, store, and server subcomponents.** The candidate's broad
- components have recognizable internal areas, but their crate facades,
- shared state, and integration lifecycles currently support the retained
- crate/service boundaries. No additional split is required at this
- revision.
-
-No candidate component is supported for removal or merger. In particular, the
-single-file OpenAPI contract and the small MCP, evaluation, CI, and release
-components have independent source-of-truth, protocol, executable, or
-publication lifecycles that justify their granularity.
-
-## Recommended disposition
-
-Apply the two supported package splits and retain the optional boundaries as
-questions:
-
-- **Recommended component count:** **70** (candidate 68, plus
- `fabro-spa` and `fabro-build-support`)
-- **Relevant tracked files:** **3,104**
-- **Assigned:** **2,256**
-- **Excluded:** **833**
-- **Unmapped:** **15** (`docs/internal/assets/**`, listed as exact paths)
-- **Overlap or uncovered files:** **0**
-
-The counts satisfy `2,256 + 833 + 15 = 3,104`. The optional installer split
-would produce 71 components without changing coverage.
diff --git a/.chisel/cartography/work/rust-apps.md b/.chisel/cartography/work/rust-apps.md
deleted file mode 100644
index 473455896..000000000
--- a/.chisel/cartography/work/rust-apps.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# Rust Applications Cartography Scout
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
-
-Scope: tracked files under `lib/apps/**`. Root `Cargo.toml`, `.gitignore`,
-`AGENTS.md`, and `CONTRIBUTING.md` were read only as workspace, exclusion, and
-repository-instruction evidence; they are not included in the scope counts.
-`CLAUDE.md` resolves to the same repository guidance as `AGENTS.md`.
-
-The primary proposal is one component per Cargo application package. These
-boundaries are established by independent package manifests, binary or library
-entry points, public interfaces, package-owned lifecycle/state, package test
-suites, and explicit Cargo dependency edges. The CLI and server have broad
-module trees, but their entry points and tests converge on one executable or
-one shared server state/router respectively.
-
-## Inventory and coverage
-
-The inventory was computed with:
-
-```text
-git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/apps
-```
-
-| Scope | Tracked | Assigned | Excluded | Unmapped |
-| --- | ---: | ---: | ---: | ---: |
-| `lib/apps/fabro-cli/**` | 241 | 241 | 0 | 0 |
-| `lib/apps/fabro-mcp-server/**` | 5 | 5 | 0 | 0 |
-| `lib/apps/fabro-server/**` | 112 | 112 | 0 | 0 |
-| `lib/apps/fabro-spa/**` | 3 | 2 | 1 | 0 |
-| **Total** | **361** | **360** | **1** | **0** |
-
-The one excluded tracked file is
-`lib/apps/fabro-spa/assets/.gitkeep`. `AGENTS.md` states that embedded SPA
-assets are refreshed build output and are gitignored except for `.gitkeep`;
-`.gitignore` corroborates this with `lib/apps/fabro-spa/assets/*` and the
-explicit `.gitkeep` exception. The placeholder is therefore excluded as
-evidence of a generated build-output directory. No generated code, vendored
-code, dependency trees, or other build output is tracked elsewhere in this
-scope.
-
-## Proposed components
-
-### `fabro-cli` — Fabro CLI Application
-
-- **Purpose:** Provides the `fabro` command-line application, including command parsing and dispatch, terminal presentation, server/client bootstrap, and the hidden local run-worker process entry.
-- **Assigned file count:** 241
-- **Globs:**
- - `lib/apps/fabro-cli/Cargo.toml`
- - `lib/apps/fabro-cli/build.rs`
- - `lib/apps/fabro-cli/src/**`
- - `lib/apps/fabro-cli/tests/**`
-- **Exclude globs:** none
-- **Entry points:**
- - `lib/apps/fabro-cli/src/main.rs:main`
- - `lib/apps/fabro-cli/src/main.rs:main_inner`
- - `lib/apps/fabro-cli/src/args.rs:Cli`
- - `lib/apps/fabro-cli/src/args.rs:Commands`
- - `lib/apps/fabro-cli/src/commands/run/mod.rs:dispatch`
-- **Owns:**
- - The `fabro` process lifecycle, exit classification, telemetry bootstrap, and logging bootstrap.
- - CLI argument and subcommand contracts plus human-readable and JSON output behavior.
- - Per-command resolved settings, lazy API client/credential/catalog state in `CommandContext`.
- - Local server discovery/startup and authenticated server connections.
- - The hidden `__run-worker` subprocess entry and its terminal run-progress presentation.
-- **Candidate `depends_on` IDs within this scout:** `fabro-mcp-server`, `fabro-server`.
-- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-checkpoint`, `fabro-client`, `fabro-config`, `fabro-dump`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp`, `fabro-model`, `fabro-oauth`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-static`, `fabro-store`, `fabro-telemetry`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge.
-- **Evidence:**
- - `lib/apps/fabro-cli/Cargo.toml:[[bin]]` — declares package `fabro-cli` as the `fabro` binary with `src/main.rs` as its entry point and lists direct workspace dependencies, including `fabro-mcp-server` and `fabro-server`.
- - `Cargo.toml:[workspace]` — includes `lib/apps/*` as members and selects `lib/apps/fabro-cli` as the default workspace member.
- - `lib/apps/fabro-cli/src/main.rs:main_inner` — creates the shared command context and dispatches every `Commands` variant, including the server and run-worker paths.
- - `lib/apps/fabro-cli/src/args.rs:Commands` — defines the complete top-level CLI command surface; `RunCommands` includes the hidden `__run-worker` entry.
- - `lib/apps/fabro-cli/src/command_context.rs:CommandContext` — owns the per-invocation settings, output mode, storage path, lazy server client, credential source, and model catalog shared by commands.
- - `lib/apps/fabro-cli/src/server_client.rs:connect_server_with_settings` — resolves local or remote targets and constructs the authenticated control-plane client used by command implementations.
- - `lib/apps/fabro-cli/tests/it/main.rs` — assembles command, scenario, support, and end-to-end workflow tests around the same binary application boundary.
-
-### `fabro-mcp-server` — Fabro MCP Stdio Server
-
-- **Purpose:** Exposes Fabro run operations as an MCP stdio tool server and supplies MCP-client configuration generation and installation helpers used by the CLI.
-- **Assigned file count:** 5
-- **Globs:**
- - `lib/apps/fabro-mcp-server/Cargo.toml`
- - `lib/apps/fabro-mcp-server/src/**`
-- **Exclude globs:** none
-- **Entry points:**
- - `lib/apps/fabro-mcp-server/src/lib.rs:start`
- - `lib/apps/fabro-mcp-server/src/server.rs:start`
- - `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings`
- - `lib/apps/fabro-mcp-server/src/config.rs:config_json`
- - `lib/apps/fabro-mcp-server/src/config.rs:init_agent`
-- **Owns:**
- - The MCP stdio service lifecycle and registered Fabro tool router.
- - Lazy construction of the Fabro client-backed tool backend.
- - Translation from MCP run-create inputs to Fabro API run manifests.
- - MCP client configuration rendering and updates to supported agent config files.
-- **Candidate `depends_on` IDs within this scout:** `fabro-server`.
-- **Manifest-backed cross-scope dependency candidates:** `fabro-api`, `fabro-client`, `fabro-config`, `fabro-manifest`, `fabro-model`, `fabro-tool`, `fabro-types`, `fabro-util`.
-- **Evidence:**
- - `lib/apps/fabro-mcp-server/Cargo.toml:[package]` — declares a distinct library package described as the Fabro MCP stdio server and lists a direct `fabro-server` dependency.
- - `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings` — defines the public construction boundary, client factory, config path, and working directory used to start the service.
- - `lib/apps/fabro-mcp-server/src/server.rs:start` — owns the `rmcp` stdio service lifecycle; `FabroMcpServer` owns the tool router and lazy backend.
- - `lib/apps/fabro-mcp-server/src/manifest_builder.rs:McpRunManifestBuilder` — adapts MCP tool creation requests through `fabro_server::run_tool_manifest`.
- - `lib/apps/fabro-cli/src/commands/mcp/mod.rs:dispatch` — the separate CLI package consumes this library solely through its public start/config/init interfaces.
-
-### `fabro-server` — Fabro HTTP Server
-
-- **Purpose:** Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, schedulers, worker processes, sessions, authentication, integrations, and startup/shutdown.
-- **Assigned file count:** 112
-- **Globs:**
- - `lib/apps/fabro-server/Cargo.toml`
- - `lib/apps/fabro-server/build.rs`
- - `lib/apps/fabro-server/migrations/**`
- - `lib/apps/fabro-server/src/**`
- - `lib/apps/fabro-server/tests/**`
-- **Exclude globs:** none
-- **Entry points:**
- - `lib/apps/fabro-server/src/serve.rs:serve_command`
- - `lib/apps/fabro-server/src/server.rs:AppState`
- - `lib/apps/fabro-server/src/server.rs:build_router`
- - `lib/apps/fabro-server/src/server.rs:build_router_with_options`
- - `lib/apps/fabro-server/src/server.rs:spawn_scheduler`
- - `lib/apps/fabro-server/src/lib.rs`
-- **Owns:**
- - Listener binding, resolved startup configuration, migrations, web enablement, and graceful shutdown.
- - Shared `AppState`: managed runs, persistent stores, session runtimes, artifact storage, resource sampling, settings/catalog state, and integration services.
- - API and web routing, authentication/principal middleware, static-file delivery, security headers, and OpenAPI conformance at the router boundary.
- - Run and automation scheduling, worker launch/control/token state, cancellation escalation, and global event broadcast.
- - Server-side install, diagnostics, GitHub webhook, Slack, environment, secret, variable, MCP-server, and sandbox coordination exposed through HTTP handlers.
-- **Candidate `depends_on` IDs within this scout:** `fabro-spa`.
-- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-automation`, `fabro-client`, `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp-store`, `fabro-model`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-slack`, `fabro-static`, `fabro-store`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-variable`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge.
-- **Evidence:**
- - `lib/apps/fabro-server/Cargo.toml:[package]` — declares a distinct HTTP-server library package, an integration-test target gated by `test-support`, and a direct `fabro-spa` dependency.
- - `lib/apps/fabro-server/src/lib.rs` — exposes the server's supported module/API surface and gates `test_support` behind tests or the explicit feature.
- - `lib/apps/fabro-server/src/serve.rs:serve_command` — resolves settings and secrets, runs database and compatibility migrations, builds stores/state/router, binds listeners, starts background services, and coordinates shutdown.
- - `lib/apps/fabro-server/src/server.rs:AppState` — centralizes the service's run registry, stores, session and worker runtime state, schedulers, event channel, settings, credentials, integrations, and shutdown token.
- - `lib/apps/fabro-server/src/server.rs:build_router_with_options` — composes real/demo APIs, auth/web routes, middleware, static assets, and the health surface around the shared state.
- - `lib/apps/fabro-server/src/server/handler/mod.rs:real_routes` — registers the HTTP resource handlers that consume `AppState`.
- - `lib/apps/fabro-server/tests/it/main.rs` — assembles API, conformance, pagination, and lifecycle scenario tests around the same library/router boundary.
-
-### `fabro-spa` — Embedded SPA Assets
-
-- **Purpose:** Provides the compile-time embedded production SPA asset lookup API and precomputed content hashes consumed by the HTTP server.
-- **Assigned file count:** 2
-- **Globs:**
- - `lib/apps/fabro-spa/Cargo.toml`
- - `lib/apps/fabro-spa/src/**`
- - `lib/apps/fabro-spa/assets/**`
-- **Exclude globs:**
- - `lib/apps/fabro-spa/assets/**`
-- **Entry points:**
- - `lib/apps/fabro-spa/src/lib.rs:get`
- - `lib/apps/fabro-spa/src/lib.rs:AssetBytes`
-- **Owns:**
- - Compile-time embedding of production SPA files from `assets/`.
- - Asset byte ownership and the SHA-256 metadata returned to server static-file handling.
- - The invariant that source maps are not embedded.
-- **Candidate `depends_on` IDs within this scout:** none
-- **Manifest-backed cross-scope dependency candidates:** none
-- **Evidence:**
- - `lib/apps/fabro-spa/Cargo.toml:[package]` — declares a distinct library package for embedded production SPA assets and depends only on `rust-embed`.
- - `lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets` — defines the compile-time asset folder and source-map exclusions.
- - `lib/apps/fabro-spa/src/lib.rs:get` — is the package's public asset lookup interface and returns bytes with their precomputed SHA-256 value.
- - `lib/apps/fabro-server/src/static_files.rs` — consumes `fabro_spa::get` and `fabro_spa::AssetBytes`, establishing the direction `fabro-server` → `fabro-spa`.
- - `AGENTS.md` and `.gitignore` — identify `assets/` contents as refreshed, ignored build output while preserving only `.gitkeep`.
-
-## Dependency reconciliation notes
-
-The in-scope application dependency edges are exact production Cargo edges:
-
-```text
-fabro-cli ───────────────→ fabro-server ───────────────→ fabro-spa
- └──→ fabro-mcp-server ───→ fabro-server
-```
-
-The cross-scope dependency labels above use Cargo package names as provisional
-component IDs. If another scout groups multiple packages into one component,
-the parent map should translate those package edges to the reconciled
-component ID. Build-time and dev-only edges should be handled consistently
-across the final map; the primary candidate lists above include production
-and build-time edges but do not add dev-only test-support dependencies.
-
-Dev-only workspace edges that may matter during reconciliation are:
-
-- `fabro-cli` tests additionally use `fabro-acp`, `fabro-macros`,
- `fabro-server` with `test-support`, `fabro-types` with `test-support`, and
- `fabro-workflow` with `test-support`.
-- `fabro-server` tests additionally use `fabro-macros`, `fabro-sandbox` with
- `test-support`, and `fabro-types` with `test-support`.
-
-## Exclusions and unmapped files
-
-- **Excluded:** `lib/apps/fabro-spa/assets/.gitkeep` — placeholder retained in
- an otherwise ignored generated-asset directory.
-- **Unmapped:** none.
-
-## Open boundary questions
-
-1. Should `fabro-server` remain one service component, as proposed, or should
- the final repository map expose separate server transport/auth and
- run/worker-coordination components? `serve_command`, `AppState`, and the
- integration suite currently join those lifecycles, while the public auth
- modules, handler tree, and worker-control modules offer possible
- sub-boundaries.
-2. Should the hidden `fabro __run-worker` path remain part of `fabro-cli`, as
- proposed, or be represented as a run-worker component? It has a distinct
- process lifecycle and is launched by `fabro-server`, but it shares the CLI
- binary, manifest, dispatch, command context, and integration-test suite.
-3. Should MCP client configuration/init behavior and the MCP stdio tool
- service remain one `fabro-mcp-server` component, as proposed? They are
- separate public operations but share one five-file package and one CLI
- namespace.
-4. Should `fabro-spa` remain a separate component, as proposed, or be folded
- into `fabro-server` because all generated payloads are excluded and the
- remaining package has two assigned files? Its separate Cargo package and
- public asset/hash interface establish a dependency boundary, while its only
- production consumer in this scope is the server.
diff --git a/.chisel/cartography/work/rust-components.md b/.chisel/cartography/work/rust-components.md
deleted file mode 100644
index 64f672a17..000000000
--- a/.chisel/cartography/work/rust-components.md
+++ /dev/null
@@ -1,391 +0,0 @@
-# Cartography scout report: Rust components
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
-
-Scope: tracked files under `lib/components/**`, with workspace manifests and public consumers consulted only as boundary evidence.
-
-## Boundary synthesis
-
-The scope contains 23 non-published, shared in-repository Rust library crates. The primary proposal keeps one component per crate: every crate has its own manifest and crate root, exposes a distinct public vocabulary or execution facade, and owns a separate domain state, external protocol, or runtime lifecycle. This also keeps the regular Cargo dependency edges directional and makes every glob non-overlapping.
-
-The four SQLite-backed resource crates (`fabro-automation`, `fabro-environment`, `fabro-mcp-store`, and `fabro-variable`) use a similar storage pattern, but their identifiers, validation, import formats, tables, and public consumers differ; they are therefore proposed as separate components. The two-file crates (`fabro-dump`, `fabro-install`, and `fabro-manifest`) are also kept separate because each contains a substantial public operation and has a distinct dependency/consumer boundary rather than being a collection of incidental helpers.
-
-Checked-in snapshots, prompt templates, grammars, migrations, and test fixture keys are assigned to the component whose behavior they exercise. No tracked file in this scope has evidence of being vendored or build output, and no checked-in generated source is excluded.
-
-## Proposed components
-
-### `fabro-acp` — Agent Client Protocol runtime
-
-- Purpose: Launch and control Agent Client Protocol processes through Fabro sandboxes and translate their sessions into Fabro run results.
-- Globs: `lib/components/fabro-acp/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-acp/src/lib.rs`, `lib/components/fabro-acp/src/command.rs:AcpProcessSpec`, `lib/components/fabro-acp/src/session.rs:run_acp_turn`
-- Owns: ACP process specifications; ACP transport/session lifetime; live steering and cancellation handles; ACP process exit/error translation.
-- Depends on candidates: `fabro-sandbox`
-- Evidence:
- - `lib/components/fabro-acp/Cargo.toml` — declares an ACP backend crate with a default `runtime` feature and an optional runtime dependency on `fabro-sandbox`.
- - `lib/components/fabro-acp/src/lib.rs` — exposes the process specification and runtime session/control API while keeping transport internal.
- - `lib/components/fabro-acp/tests/session.rs` — exercises the session boundary as an integration test.
-- Scoped tracked files: 8
-
-### `fabro-agent` — Coding agent runtime
-
-- Purpose: Run programmable coding-agent sessions, including model profiles, context management, native tools, permissions, MCP tools, and subagents.
-- Globs: `lib/components/fabro-agent/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-agent/src/lib.rs`, `lib/components/fabro-agent/src/session.rs:Session`, `lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry`, `lib/components/fabro-agent/src/cli.rs:run_with_args`
-- Owns: agent session state and history; agent/model profiles and prompt templates; tool registry and execution lifecycle; context compaction; todo/question/subagent runtimes; agent-emitted events.
-- Depends on candidates: `fabro-llm`, `fabro-mcp`, `fabro-sandbox`
-- Evidence:
- - `lib/components/fabro-agent/Cargo.toml` — describes a programmable agentic loop and declares direct dependencies on the LLM, MCP, and sandbox crates.
- - `lib/components/fabro-agent/src/lib.rs` — presents one crate-level facade spanning sessions, profiles, tools, permissions, history, and subagent supervision.
- - `lib/components/fabro-agent/tests/it/main.rs` — anchors the crate's integration-test suite; profile prompt snapshots and `.j2` templates are behavioral assets of the same runtime.
-- Scoped tracked files: 66
-
-### `fabro-automation` — Automation definitions and storage
-
-- Purpose: Validate, version, import, and durably store scheduled, API-triggered, and manual Fabro automation definitions.
-- Globs: `lib/components/fabro-automation/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-automation/src/lib.rs`, `lib/components/fabro-automation/src/store.rs:AutomationStore`, `lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once`
-- Owns: automation IDs and revisions; automation targets and triggers; canonical revision calculation; automation SQLite records; legacy file-definition import.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-automation/Cargo.toml` — declares “Automation domain and durable storage for Fabro” and uses the shared database foundation.
- - `lib/components/fabro-automation/src/lib.rs` — re-exports the automation domain, validation errors, revisions, store, and one-time importer as one API.
- - `lib/components/fabro-automation/tests/store.rs` and `lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs` — cover and evolve the owned automation persistence format.
-- Scoped tracked files: 9
-
-### `fabro-checkpoint` — Git checkpoint storage
-
-- Purpose: Store workflow checkpoints and metadata in Git commits and dedicated metadata branches.
-- Globs: `lib/components/fabro-checkpoint/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-checkpoint/src/lib.rs`, `lib/components/fabro-checkpoint/src/branch.rs:BranchStore`, `lib/components/fabro-checkpoint/src/git.rs:Store`
-- Owns: Git tree entries and checkpoint commits; metadata-branch naming and access; checkpoint commit authorship and trailers; checkpoint-specific error types.
-- Depends on candidates: `fabro-store`
-- Evidence:
- - `lib/components/fabro-checkpoint/Cargo.toml` — identifies Git-backed workflow checkpoint storage and directly depends on `fabro-store`.
- - `lib/components/fabro-checkpoint/src/lib.rs` — exposes branch, Git, author, trailer, and checkpoint error modules behind one crate facade.
- - `lib/components/fabro-checkpoint/src/branch.rs:BranchStore` and `lib/components/fabro-checkpoint/src/git.rs:Store` — provide the two persistence entry points over the same Git repository state.
-- Scoped tracked files: 7
-
-### `fabro-dump` — Run dump materialization
-
-- Purpose: Materialize a stored run projection, event history, checkpoints, artifacts, and referenced blobs into a portable directory tree.
-- Globs: `lib/components/fabro-dump/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-dump/src/lib.rs:RunDump`, `lib/components/fabro-dump/src/lib.rs:RunDump::from_store_state_and_events`, `lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir`
-- Owns: dump entry layout and filenames; stage ranking within dumps; blob hydration; dump serialization and directory writing.
-- Depends on candidates: `fabro-store`
-- Evidence:
- - `lib/components/fabro-dump/Cargo.toml` — gives the crate a direct dependency on `fabro-store`, which supplies projections and event envelopes.
- - `lib/components/fabro-dump/src/lib.rs:RunDump` — contains the public dump-building and writing lifecycle, with inline tests for its output contract.
- - Workspace consumers `fabro-cli` and `fabro-workflow` both depend directly on `fabro-dump`, rather than accessing its behavior through `fabro-store`.
-- Scoped tracked files: 2
-
-### `fabro-environment` — Environment definitions and storage
-
-- Purpose: Validate, seed, version, import, and durably store server-owned execution environment definitions.
-- Globs: `lib/components/fabro-environment/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-environment/src/lib.rs`, `lib/components/fabro-environment/src/store.rs:EnvironmentStore`, `lib/components/fabro-environment/src/store.rs:seed_default_environment`
-- Owns: environment IDs and revisions; environment drafts and canonical revisions; environment SQLite records; built-in environment seeding; legacy directory import.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-environment/Cargo.toml` — declares the server-owned environment domain and durable storage.
- - `lib/components/fabro-environment/src/lib.rs` — exports a specific environment domain/store API, including seeding and import operations.
- - `lib/components/fabro-environment/tests/store.rs` — exercises the environment persistence boundary independently of the other resource stores.
-- Scoped tracked files: 7
-
-### `fabro-github` — GitHub authentication and API
-
-- Purpose: Resolve GitHub credentials and perform authenticated GitHub App, repository, branch, and pull-request API operations.
-- Globs: `lib/components/fabro-github/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-github/src/lib.rs:GitHubCredentials`, `lib/components/fabro-github/src/lib.rs:GitHubContext`, `lib/components/fabro-github/src/lib.rs:create_pull_request`, `lib/components/fabro-github/src/lib.rs:resolve_authenticated_url`
-- Owns: GitHub credential forms and token minting; GitHub API request/response translation; repository URL normalization and authenticated clone URLs; pull-request lifecycle calls.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-github/Cargo.toml` — describes GitHub App authentication and API helpers and declares the JWT/HTTP dependencies used at this boundary.
- - `lib/components/fabro-github/src/lib.rs` — defines the credential context, testable HTTP abstraction, App token flow, and repository/PR operations in one public surface.
- - `lib/components/fabro-github/tests/integration.rs` and `lib/components/fabro-github/src/testdata/rsa_private.pem` — exercise the external authentication/API boundary using a dedicated test key fixture.
-- Scoped tracked files: 4
-
-### `fabro-graphviz` — Workflow graph language
-
-- Purpose: Parse Graphviz DOT into Fabro's typed graph model and parse conditions/stylesheets or render graphs for presentation.
-- Globs: `lib/components/fabro-graphviz/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-graphviz/src/lib.rs`, `lib/components/fabro-graphviz/src/parser/mod.rs:parse`, `lib/components/fabro-graphviz/src/condition.rs:parse_condition_expr`, `lib/components/fabro-graphviz/src/render.rs:render_dot`
-- Owns: DOT lexer/parser/semantic conversion; graph parsing errors; condition and stylesheet syntax; Graphviz rendering normalization.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-graphviz/Cargo.toml` — names the crate as the DOT parser and typed graph data model.
- - `lib/components/fabro-graphviz/src/parser/mod.rs:parse` — is the source-to-typed-graph entry point backed by separate lexer, grammar, AST, and semantic modules.
- - `lib/components/fabro-graphviz/src/lib.rs` — exposes parsing-adjacent condition, fidelity, rendering, and stylesheet interfaces as the graph-language boundary.
-- Scoped tracked files: 14
-
-### `fabro-hooks` — Workflow lifecycle hooks
-
-- Purpose: Configure and execute user-defined workflow lifecycle hooks and bridge tool hooks into the agent runtime.
-- Globs: `lib/components/fabro-hooks/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-hooks/src/lib.rs`, `lib/components/fabro-hooks/src/runner.rs:HookRunner`, `lib/components/fabro-hooks/src/executor.rs:HookExecutor`, `lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback`
-- Owns: hook configuration and event selection; hook execution context; hook result/decision merging; HTTP/command hook dispatch; agent tool-hook bridging.
-- Depends on candidates: `fabro-agent`, `fabro-llm`
-- Evidence:
- - `lib/components/fabro-hooks/Cargo.toml` — identifies workflow lifecycle hooks and directly depends on the agent and LLM components used by hook execution.
- - `lib/components/fabro-hooks/src/lib.rs` — exposes hook definitions, decisions, runner, execution context, and the agent bridge.
- - `lib/components/fabro-hooks/tests/host_command_hooks.rs` — tests host-command hooks through the public lifecycle boundary.
-- Scoped tracked files: 8
-
-### `fabro-install` — Installation persistence
-
-- Purpose: Prepare, persist, and roll back shared CLI/server installation settings, credentials, development tokens, and default environments.
-- Globs: `lib/components/fabro-install/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan`, `lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct`, `lib/components/fabro-install/src/lib.rs:merge_server_settings`
-- Owns: install persistence plans; settings and server-env mutations; vault writes/removals; development-token creation and rollback; default environment seeding during install.
-- Depends on candidates: `fabro-environment`
-- Evidence:
- - `lib/components/fabro-install/Cargo.toml` — describes shared install primitives for CLI and server flows and directly depends on the environment store.
- - `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan` — groups the files, env entries, token, and vault state committed by one install operation.
- - Workspace consumers `fabro-cli` and `fabro-server` depend directly on this crate, making it a shared install boundary rather than CLI-local code.
-- Scoped tracked files: 2
-
-### `fabro-interview` — Human interaction runtime
-
-- Purpose: Represent workflow questions and answers and provide console, callback, queue, control, recording, replay, and automatic interviewer implementations.
-- Globs: `lib/components/fabro-interview/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-interview/src/lib.rs:Interviewer`, `lib/components/fabro-interview/src/lib.rs:ask_with_timeout`, `lib/components/fabro-interview/src/control.rs:ControlInterviewer`
-- Owns: question/answer protocol; interviewer request lifetime and timeout behavior; queued and controlled answer delivery; interview recording and replay.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-interview/Cargo.toml` — defines human-in-the-loop interviewer traits and implementations as the crate purpose.
- - `lib/components/fabro-interview/src/lib.rs:Interviewer` — is the shared async interaction interface and re-exports all implementation strategies.
- - `lib/components/fabro-interview/src/control_protocol.rs` and `lib/components/fabro-interview/src/control.rs` — own the worker-control delivery protocol and pending interaction state.
-- Scoped tracked files: 10
-
-### `fabro-llm` — Unified LLM client
-
-- Purpose: Provide a provider-neutral generation API with model routing, middleware, retries, token/cost accounting, provider adapters, and wire codecs.
-- Globs: `lib/components/fabro-llm/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-llm/src/lib.rs`, `lib/components/fabro-llm/src/client.rs:Client`, `lib/components/fabro-llm/src/provider.rs:ProviderAdapter`, `lib/components/fabro-llm/src/generate.rs:generate`, `lib/components/fabro-llm/src/generate.rs:stream`
-- Owns: normalized LLM request/response/stream types; provider adapter registry; provider-specific authentication and transport; request/response/stream wire translation; retry/middleware/generation orchestration; token and cost calculations.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-llm/Cargo.toml` — describes a unified multi-provider client and does not depend on another component crate.
- - `lib/components/fabro-llm/src/provider.rs:ProviderAdapter` and `lib/components/fabro-llm/src/client.rs:Client` — define the adapter contract and client registry through which the provider modules are consumed.
- - `lib/components/fabro-llm/tests/it/wire/mod.rs` and its provider-specific snapshot trees — verify that the codecs and adapters implement the same normalized client boundary.
-- Scoped tracked files: 188
-
-### `fabro-manifest` — Run manifest construction
-
-- Purpose: Resolve workflow/configuration inputs, collect static dependencies, and construct a self-contained run manifest with Git provenance.
-- Globs: `lib/components/fabro-manifest/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-manifest/src/lib.rs:build_run_manifest`, `lib/components/fabro-manifest/src/lib.rs:build_run_overrides`, `lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput`
-- Owns: manifest build input/output; configuration-layer resolution for manifest creation; workflow/file dependency collection; Git context and pre-run push preparation.
-- Depends on candidates: `fabro-github`, `fabro-graphviz`, `fabro-workflow`
-- Evidence:
- - `lib/components/fabro-manifest/Cargo.toml` — declares run manifest construction and direct dependencies on graph parsing, GitHub support, and selected workflow utilities.
- - `lib/components/fabro-manifest/src/lib.rs:build_run_manifest` — is a single public assembly operation that produces the API `RunManifest`.
- - Workspace consumers `fabro-cli`, `fabro-server`, and `fabro-mcp-server` depend directly on the crate to share identical manifest construction.
-- Scoped tracked files: 2
-
-### `fabro-mcp` — MCP client runtime
-
-- Purpose: Connect to configured Model Context Protocol servers, manage their connection lifetimes, discover tools, and dispatch qualified tool calls.
-- Globs: `lib/components/fabro-mcp/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-mcp/src/lib.rs`, `lib/components/fabro-mcp/src/client.rs:McpClient`, `lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager`
-- Owns: MCP client connections; stdio and streaming HTTP transport selection; server connection manager state; tool discovery, qualified names, and call-result conversion.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-mcp/Cargo.toml` — describes the MCP client role and enables the rmcp client/transport features required by it.
- - `lib/components/fabro-mcp/src/lib.rs` — exposes client, config, connection manager, and HTTP transport modules while keeping protocol handlers internal.
- - `lib/components/fabro-mcp/tests/stdio_integration.rs` — verifies the external MCP process boundary over stdio.
-- Scoped tracked files: 10
-
-### `fabro-mcp-store` — MCP server catalog storage
-
-- Purpose: Durably store, revision, cache, and import server-managed MCP server definitions.
-- Globs: `lib/components/fabro-mcp-store/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-mcp-store/src/lib.rs`, `lib/components/fabro-mcp-store/src/store.rs:McpServerStore`, `lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once`
-- Owns: MCP server definition SQLite records; definition revisions and optimistic concurrency; synchronous catalog cache; legacy directory import.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-mcp-store/Cargo.toml` — declares server-managed MCP catalog durable storage.
- - `lib/components/fabro-mcp-store/src/lib.rs` — explicitly states that the domain model is shared but this crate owns persistence, and exports only the store/error/import API.
- - `lib/components/fabro-mcp-store/tests/store.rs` — exercises that persistence boundary independently from live MCP connections.
-- Scoped tracked files: 6
-
-### `fabro-sandbox` — Execution sandbox abstraction
-
-- Purpose: Define the execution sandbox and provider contracts and implement local, Docker, and Daytona sandbox lifecycles.
-- Globs: `lib/components/fabro-sandbox/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-sandbox/src/lib.rs`, `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry`
-- Owns: sandbox filesystem/process/terminal interface; provider creation, lookup, and removal lifecycle; local/Docker/Daytona implementations; clone-source setup and reconnect behavior; sandbox errors and redaction.
-- Depends on candidates: `fabro-github`
-- Evidence:
- - `lib/components/fabro-sandbox/Cargo.toml` — defines provider features (`local`, `docker`, `daytona`) around the common sandbox crate and makes GitHub support optional for clone-based providers.
- - `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox` and `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider` — separate per-sandbox operations from provider lifecycle management within one public boundary.
- - `lib/components/fabro-sandbox/tests/docker_streaming.rs` and `lib/components/fabro-sandbox/tests/daytona_streaming_live.rs` — exercise provider implementations against the shared contract.
-- Scoped tracked files: 23
-
-### `fabro-slack` — Slack interaction integration
-
-- Purpose: Connect to Slack Socket Mode and translate workflow questions, answers, run lifecycle events, and thread replies between Slack and Fabro.
-- Globs: `lib/components/fabro-slack/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-slack/src/connection.rs:run`, `lib/components/fabro-slack/src/client.rs:SlackClient`, `lib/components/fabro-slack/src/blocks.rs:question_to_blocks`
-- Owns: Slack credential resolution; Socket Mode connection/event loop; Slack API client; block rendering; interaction payload parsing; run-to-thread registry and dispatch.
-- Depends on candidates: `fabro-interview`, `fabro-workflow`
-- Evidence:
- - `lib/components/fabro-slack/Cargo.toml` — declares the Slack interviewer integration and directly depends on the interview and workflow components.
- - `lib/components/fabro-slack/src/connection.rs:run` — owns the Socket Mode connection lifetime and dispatch loop.
- - `lib/components/fabro-slack/src/interaction.rs` and `lib/components/fabro-slack/src/threads.rs` — translate external payloads into interview submissions and associate Slack threads with run state.
-- Scoped tracked files: 11
-
-### `fabro-store` — Run and authentication persistence
-
-- Purpose: Persist run event streams, projections, blobs, artifacts, summaries, catalog indexes, and server authentication grants over SlateDB, object storage, and SQLite.
-- Globs: `lib/components/fabro-store/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-store/src/lib.rs`, `lib/components/fabro-store/src/slate/mod.rs:Database`, `lib/components/fabro-store/src/slate/run_store.rs:RunDatabase`, `lib/components/fabro-store/src/run_state.rs:RunProjectionReducer`
-- Owns: run event append/read lifecycle; run projection reduction and caching; run/blob/artifact key layout; run catalog and summary indexes; authorization-code and refresh-token records; storage-specific errors and locking.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-store/src/lib.rs` — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth records.
- - `lib/components/fabro-store/src/slate/mod.rs:Database` — is the shared storage root from which run, blob, catalog, auth-code, and refresh-token stores are obtained.
- - `lib/components/fabro-store/tests/serializable_projection.rs` — tests the durable projection representation at the crate boundary.
-- Scoped tracked files: 25
-
-### `fabro-tool` — Run-control tools
-
-- Purpose: Define and execute the shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend.
-- Globs: `lib/components/fabro-tool/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-tool/src/lib.rs`, `lib/components/fabro-tool/src/common.rs:FabroToolBackend`, `lib/components/fabro-tool/src/common.rs:tool_definitions`, `lib/components/fabro-tool/src/create.rs:create_runs`
-- Owns: tool names, JSON schemas, and parameter validation; backend-neutral run-control operations; result DTOs and text rendering; API-client backend adapter.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-tool/Cargo.toml` — identifies shared run-control tool behavior and depends on foundation API/client contracts rather than the server or workflow implementation.
- - `lib/components/fabro-tool/src/common.rs:FabroToolBackend` — is the abstraction shared by CLI, server, workflow, and MCP-server consumers.
- - `lib/components/fabro-tool/src/lib.rs` — exports a matched set of validated operation/result/text interfaces for all supported tools.
-- Scoped tracked files: 12
-
-### `fabro-tracker` — Issue tracker adapters
-
-- Purpose: Provide a common issue-tracker interface with GitHub Projects and Linear implementations.
-- Globs: `lib/components/fabro-tracker/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-tracker/src/lib.rs:Tracker`, `lib/components/fabro-tracker/src/github.rs:GitHubTracker`, `lib/components/fabro-tracker/src/linear.rs:LinearTracker`
-- Owns: normalized issue and blocker records; candidate-issue query and state-transition contract; GitHub Projects GraphQL adapter; Linear GraphQL adapter.
-- Depends on candidates: `fabro-github`
-- Evidence:
- - `lib/components/fabro-tracker/Cargo.toml` — declares the tracker trait/types boundary and directly depends on GitHub support for one adapter.
- - `lib/components/fabro-tracker/src/lib.rs:Tracker` — defines a provider-neutral async issue workflow implemented by both provider modules.
- - `lib/components/fabro-tracker/src/fixtures/github-app-test-key.pem` — is a test fixture owned by the GitHub tracker adapter, not a runtime credential or vendored file.
-- Scoped tracked files: 5
-
-### `fabro-validate` — Workflow graph validation
-
-- Purpose: Run built-in and catalog-aware lint rules over typed Fabro workflow graphs and return structured diagnostics.
-- Globs: `lib/components/fabro-validate/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-validate/src/lib.rs:validate`, `lib/components/fabro-validate/src/lib.rs:validate_with_catalog`, `lib/components/fabro-validate/src/lib.rs:LintRule`, `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules`
-- Owns: validation severity and diagnostic structure; lint-rule interface and built-in rule registry; graph/catalog validation traversal; validation error escalation.
-- Depends on candidates: `fabro-acp`, `fabro-graphviz`
-- Evidence:
- - `lib/components/fabro-validate/Cargo.toml` — declares graph validation/linting and directly depends on graph parsing plus ACP backend validation.
- - `lib/components/fabro-validate/src/lib.rs:LintRule` — provides the extension interface and public diagnostic API.
- - `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules` and the 31 rule source files — form an explicit registry of independently tested rules under one validation lifecycle.
-- Scoped tracked files: 36
-
-### `fabro-variable` — Workflow variable storage
-
-- Purpose: Validate, durably store, snapshot, and import workflow-visible non-sensitive variables.
-- Globs: `lib/components/fabro-variable/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-variable/src/lib.rs:VariableStore`, `lib/components/fabro-variable/src/lib.rs:VariableStore::value_map`, `lib/components/fabro-variable/src/lib.rs:import_legacy_json_once`
-- Owns: variable name validation; variable SQLite records and timestamps; name-to-value snapshots for template contexts; legacy JSON import and backup.
-- Depends on candidates: `[]`
-- Evidence:
- - `lib/components/fabro-variable/Cargo.toml` — defines workflow-visible, non-sensitive variables as a separate storage concern.
- - `lib/components/fabro-variable/src/lib.rs:VariableStore` — exposes CRUD and render-context snapshot operations over that single domain.
- - `lib/components/fabro-variable/tests/store.rs` — verifies its persistence/import contract independently from environments, automations, and MCP definitions.
-- Scoped tracked files: 3
-
-### `fabro-workflow` — Workflow orchestration engine
-
-- Purpose: Transform, validate, initialize, execute, persist, resume, and finalize graph-defined Fabro runs across handlers, lifecycle hooks, sandboxes, checkpoints, events, and human controls.
-- Globs: `lib/components/fabro-workflow/**`
-- Exclude globs: `[]`
-- Entry points: `lib/components/fabro-workflow/src/operations/mod.rs`, `lib/components/fabro-workflow/src/operations/start.rs:start`, `lib/components/fabro-workflow/src/pipeline/mod.rs`, `lib/components/fabro-workflow/src/pipeline/execute.rs:execute`, `lib/components/fabro-workflow/src/handler/mod.rs:Handler`
-- Owns: run operation lifecycle (create/start/resume/retry/rewind/fork/archive); workflow transform/validate/initialize/execute/finalize phases; node handler registry and built-in handlers; run-scoped services and cancellation; workflow event conversion/emission; checkpoint, Git, artifact, hook, and status lifecycles; steering and run control.
-- Depends on candidates: `fabro-acp`, `fabro-agent`, `fabro-checkpoint`, `fabro-dump`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-interview`, `fabro-llm`, `fabro-mcp`, `fabro-sandbox`, `fabro-store`, `fabro-tool`, `fabro-validate`
-- Evidence:
- - `lib/components/fabro-workflow/Cargo.toml` — defines the DOT-based workflow runner and declares the component dependencies used to assemble the engine.
- - `lib/components/fabro-workflow/src/pipeline/mod.rs` — exposes the ordered parse/transform/validate/initialize/execute/finalize phase boundary and its typed phase states.
- - `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` — connect node execution to the run-scoped lifecycle under the same engine.
- - `lib/components/fabro-workflow/tests/it/main.rs` and `lib/components/fabro-workflow/tests/materialize_run.rs` — exercise end-to-end orchestration and run materialization.
-- Scoped tracked files: 122
-
-## Coverage
-
-The fixed-revision inventory was computed with:
-
-```text
-git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/components
-```
-
-| Component glob | Assigned tracked files |
-| --- | ---: |
-| `lib/components/fabro-acp/**` | 8 |
-| `lib/components/fabro-agent/**` | 66 |
-| `lib/components/fabro-automation/**` | 9 |
-| `lib/components/fabro-checkpoint/**` | 7 |
-| `lib/components/fabro-dump/**` | 2 |
-| `lib/components/fabro-environment/**` | 7 |
-| `lib/components/fabro-github/**` | 4 |
-| `lib/components/fabro-graphviz/**` | 14 |
-| `lib/components/fabro-hooks/**` | 8 |
-| `lib/components/fabro-install/**` | 2 |
-| `lib/components/fabro-interview/**` | 10 |
-| `lib/components/fabro-llm/**` | 188 |
-| `lib/components/fabro-manifest/**` | 2 |
-| `lib/components/fabro-mcp/**` | 10 |
-| `lib/components/fabro-mcp-store/**` | 6 |
-| `lib/components/fabro-sandbox/**` | 23 |
-| `lib/components/fabro-slack/**` | 11 |
-| `lib/components/fabro-store/**` | 25 |
-| `lib/components/fabro-tool/**` | 12 |
-| `lib/components/fabro-tracker/**` | 5 |
-| `lib/components/fabro-validate/**` | 36 |
-| `lib/components/fabro-variable/**` | 3 |
-| `lib/components/fabro-workflow/**` | 122 |
-| **Total** | **580** |
-
-- Relevant tracked files: 580
-- Assigned files: 580
-- Excluded files: 0
-- Unmapped files: 0
-- Duplicate claims: 0 (the proposed crate-directory globs are disjoint)
-
-## Exclusions and unmapped files
-
-- Evidence-backed exclusions: none.
-- Unmapped files: none.
-- Checked-in `.snap`, `.j2`, `.lark`, migration, README, and test-key files remain assigned because they specify or exercise component behavior.
-
-## Boundary questions for reconciliation
-
-1. Should `fabro-workflow` remain one engine component, as proposed, or be split into a public run-operations/materialization component and an execution component? `src/operations/**` and `src/pipeline/**` expose recognizable facades, but `services.rs`, `event.rs`, `runtime_store.rs`, the root modules, and lifecycle/handler code tie both facades to the same run-scoped state and make a non-overlapping ownership split less clear.
-2. Should `fabro-llm` remain one unified client component, as proposed, or should `src/providers/**`, `src/codec/**`, and `tests/it/wire/**` form a provider-protocol-adapters component? The adapter trait and wire-focused tests support that sub-boundary, while `adapter_registry.rs`, shared normalized types, transport helpers, and direct module references keep it inside one crate-level client lifecycle.
-3. Should `fabro-store` remain one persistence component, as proposed, or should its authorization-code/refresh-token stores be separated from run/event/blob persistence? `slate::Database` exposes them from one storage root, but their record lifecycles are consumed by server authentication rather than workflow execution.
diff --git a/.chisel/cartography/work/rust-foundation.md b/.chisel/cartography/work/rust-foundation.md
deleted file mode 100644
index 088542416..000000000
--- a/.chisel/cartography/work/rust-foundation.md
+++ /dev/null
@@ -1,389 +0,0 @@
-# Rust foundation cartography scout
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
-
-Scope: all 365 tracked files under `lib/foundation/**`. Root and consumer manifests, the OpenAPI specification, and public consumer entry points were consulted only as boundary evidence and are not part of this scope's coverage counts.
-
-Applicable instructions read: `AGENTS.md` and `CONTRIBUTING.md` (`CLAUDE.md` is a symlink to `AGENTS.md`).
-
-## Boundary approach
-
-- Most foundation crates are proposed as components in their own right because their manifests, crate-root facades, public state or lifecycle, focused tests, and reverse dependency edges describe a distinct responsibility.
-- `build-support` and `fabro-dev` are grouped as `fabro-build-tooling`: the two-file build-support crate would otherwise be too narrow for a stable assessment, and both crates serve repository build/development lifecycle rather than product runtime.
-- `fabro-macros` and `fabro-options-metadata` are grouped as `fabro-macros-metadata`: the proc-macro crate cannot expose runtime metadata itself, and the `OptionsMetadata` derive and runtime visitor model form one compiler/runtime contract. The proc-macro crate's `Combine` and `e2e_test` entry points remain part of that compiler-support component.
-- The small `fabro-http`, `fabro-proc`, and `fabro-static` crates remain separate. Each is a dependency hub with a distinct public policy boundary (HTTP construction/proxy policy, OS process primitives, and shared string registries respectively), so grouping them would mix independent reasons to change.
-- `fabro-types` and `fabro-util` remain crate-level components. Their crate-root facades and cross-module use are the stable public boundaries available at this revision; a finer file-family split would not have an independent manifest or facade and would create overlapping conceptual ownership.
-- Production and normal compile-time internal dependencies are listed below. Dev-only edges to `fabro-test` are omitted except for the test-support component itself.
-
-## Proposed components
-
-### `fabro-build-tooling` — Fabro build and developer tooling
-
-- **File count:** 23
-- **Purpose:** Runs repository development, build, documentation, SPA, container, benchmark, and release automation and supplies compile-time Git metadata to product build scripts.
-- **Globs:** `lib/foundation/build-support/**`, `lib/foundation/fabro-dev/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-dev/src/main.rs:main`, `lib/foundation/fabro-dev/src/lib.rs:run`, `lib/foundation/build-support/git_metadata.rs:collect_from`, `lib/foundation/build-support/git_metadata.rs:cargo_profile`
-- **Owns:** developer CLI command dispatch; subprocess plans for build/docs/SPA/Docker/release/test benchmarking; reference generation checks; compile-time Git SHA, rerun paths, and Cargo profile discovery.
-- **Depends on candidates:** `fabro-config`, `fabro-macros-metadata`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-dev/Cargo.toml` — declares an internal `fabro-dev` binary/library and integration-test target behind the `dev` feature.
- - `lib/foundation/fabro-dev/src/lib.rs:Command` — dispatches the build, Docker, docs, release, SPA, and benchmark command families.
- - `lib/foundation/fabro-dev/src/commands/mod.rs:PlannedCommand` — centralizes the subprocess lifecycle shared by those commands.
- - `lib/foundation/fabro-dev/tests/it/main.rs` — provides the integration-test composition root for the developer CLI.
- - `lib/foundation/build-support/Cargo.toml` and `lib/foundation/build-support/git_metadata.rs:BuildGitMetadata` — define a build-script-only support crate whose public result is embedded Git/build metadata; `lib/apps/fabro-cli/Cargo.toml` and `lib/apps/fabro-server/Cargo.toml` consume it as a build dependency.
-
-### `fabro-api` — Generated API contract and Rust client
-
-- **File count:** 60
-- **Purpose:** Generates the low-level Rust HTTP client and API type surface from the OpenAPI contract while reusing canonical Fabro domain types and verifying wire/type parity.
-- **Globs:** `lib/foundation/fabro-api/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-api/build.rs:main`, `lib/foundation/fabro-api/src/lib.rs:ApiClient`, `lib/foundation/fabro-api/src/lib.rs:types`
-- **Owns:** OpenAPI-to-Progenitor compatibility transformations; generated-client configuration; canonical type replacement map; low-level generated client facade; API/domain type identity and JSON round-trip tests.
-- **Depends on candidates:** `fabro-config`, `fabro-model`, `fabro-types`
-- **External dependency edges:** API types are also replaced with types from the `fabro-automation` and `fabro-environment` components.
-- **Evidence:**
- - `lib/foundation/fabro-api/Cargo.toml` — describes generated Rust types and HTTP client and declares `build.rs` generation dependencies.
- - `lib/foundation/fabro-api/build.rs:main` — reads `docs/public/api-reference/fabro-api.yaml`, patches the generator view, registers canonical type replacements, and writes `OUT_DIR/codegen.rs`.
- - `lib/foundation/fabro-api/src/lib.rs:generated` — includes the generated file behind a private module and exposes `ApiClient` plus a type facade.
- - `lib/foundation/fabro-api/tests/run_event_round_trip.rs:run_event_reuses_canonical_type` and the other `tests/*_round_trip.rs` files — verify type identity and OpenAPI JSON shape across the exported contract.
- - `docs/public/api-reference/fabro-api.yaml` — repository instructions identify this out-of-scope file as the HTTP contract source of truth.
-
-### `fabro-auth` — Provider credential resolution
-
-- **File count:** 16
-- **Purpose:** Resolves provider credentials and interpolated headers from environment or vault sources, refreshes OAuth credentials, and drives interactive authentication strategies.
-- **Globs:** `lib/foundation/fabro-auth/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver`, `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource`, `lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy`, `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource`
-- **Owns:** provider credential-source precedence; API authorization/header material; configured-provider discovery; OAuth refresh and vault write-back; API-key and Codex-device login strategy state.
-- **Depends on candidates:** `fabro-http`, `fabro-model`, `fabro-oauth`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-vault`
-- **Evidence:**
- - `lib/foundation/fabro-auth/Cargo.toml` — describes typed provider credential storage/resolution and declares the model, OAuth, redaction, vault, HTTP, and type dependencies.
- - `lib/foundation/fabro-auth/src/lib.rs` — exposes sources, resolver, strategies, refresh, and vault adapters as the crate facade.
- - `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve` — composes catalog policy, vault/environment lookup, header interpolation, and OAuth refresh into the provider-facing credential.
- - `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource` — provides the source abstraction used by environment, in-memory vault, and SQLite-backed vault implementations.
- - `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource::persist_oauth_refreshes` — owns revision-aware persistence of refreshed OAuth state.
-
-### `fabro-client` — High-level Fabro service client
-
-- **File count:** 9
-- **Purpose:** Provides the high-level authenticated Fabro service client over HTTP or Unix sockets, including endpoint operations, SSE streams, token refresh, target normalization, and local CLI auth storage.
-- **Globs:** `lib/foundation/fabro-client/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-client/src/client.rs:Client::builder`, `lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect`, `lib/foundation/fabro-client/src/target.rs:ServerTarget`, `lib/foundation/fabro-client/src/auth_store.rs:AuthStore`, `lib/foundation/fabro-client/src/client.rs:RunEventStream`
-- **Owns:** connected client transport state; API operation wrappers and error classification; OAuth refresh coordination; HTTP/Unix target canonicalization; SSE buffering; per-server CLI authentication file and locking lifecycle.
-- **Depends on candidates:** `fabro-api`, `fabro-http`, `fabro-model`, `fabro-static`, `fabro-types`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-client/Cargo.toml` — distinguishes the typed high-level client from the generated `fabro-api` dependency.
- - `lib/foundation/fabro-client/src/client.rs:ClientState` and `Client` — own the generated client, raw HTTP client, bearer token, base URL, refresh lock, and optional transport reconnection.
- - `lib/foundation/fabro-client/src/target.rs:ServerTarget::build_public_http_client` — defines the HTTP-versus-Unix-socket transport boundary.
- - `lib/foundation/fabro-client/src/auth_store.rs:AuthStore` — owns the locked local authentication file lifecycle.
- - `lib/foundation/fabro-client/src/lib.rs` — exposes the client, streams, credential, error, session, store, and target facade consumed by CLI/server/tool applications.
-
-### `fabro-config` — Layered configuration and runtime paths
-
-- **File count:** 52
-- **Purpose:** Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical storage/runtime paths.
-- **Globs:** `lib/foundation/fabro-config/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:RunSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:load_server_runtime_settings`, `lib/foundation/fabro-config/src/lib.rs:load_config_file`, `lib/foundation/fabro-config/src/resolve/mod.rs`
-- **Owns:** source-layer structs and merge semantics; built-in defaults; settings parsing/validation/resolution; configuration compatibility migrations; home, storage, runtime-directory, and run-scratch path conventions; daemon/envfile/log-filter configuration helpers.
-- **Depends on candidates:** `fabro-macros-metadata`, `fabro-model`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-config/Cargo.toml` — declares the centralized configuration crate and its optional `clap` integration.
- - `lib/foundation/fabro-config/src/lib.rs` — exposes layer types, builders, resolvers, parsing, storage, and runtime path facade.
- - `lib/foundation/fabro-config/src/builders.rs` — composes defaults and source layers into dense user, server, run, workflow, and model-catalog settings.
- - `lib/foundation/fabro-config/src/layers/combine.rs` and `lib/foundation/fabro-config/src/layers/*.rs` — define the layer merge contract and source-specific shapes.
- - `lib/foundation/fabro-config/src/migrations.rs` plus `lib/foundation/fabro-config/migrations/*.rs` — register and implement the settings-file migration lifecycle.
- - `lib/foundation/fabro-config/src/tests/*.rs` — exercise resolution independently for root, CLI, project, run, server, and workflow sources.
-
-### `fabro-core` — Generic graph execution kernel
-
-- **File count:** 13
-- **Purpose:** Executes generic directed workflow graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts.
-- **Globs:** `lib/foundation/fabro-core/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-core/src/executor.rs:ExecutorBuilder`, `lib/foundation/fabro-core/src/executor.rs:Executor::run`, `lib/foundation/fabro-core/src/graph.rs:Graph`, `lib/foundation/fabro-core/src/handler.rs:NodeHandler`, `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle`
-- **Owns:** in-memory execution state; node/edge traversal loop; handler and lifecycle extension contracts; retry/visit/cancellation decisions; stall-watchdog task lifecycle.
-- **Depends on candidates:** `fabro-types`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-core/Cargo.toml` — identifies the crate as the generic workflow execution engine without depending on the higher-level workflow component.
- - `lib/foundation/fabro-core/src/graph.rs` — defines generic graph, node, and edge contracts.
- - `lib/foundation/fabro-core/src/executor.rs:Executor::run` — owns the traversal and execution lifecycle.
- - `lib/foundation/fabro-core/src/state.rs:ExecutionState` — owns current node, outcomes, retries, visits, completed nodes, and context.
- - `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle` and `lib/foundation/fabro-core/src/stall.rs:StallWatchdog` — expose the lifecycle hooks and owned background timeout task.
- - `lib/components/fabro-workflow/Cargo.toml` — out-of-scope consumer evidence that the product workflow component adapts this lower-level kernel.
-
-### `fabro-db` — Shared SQLite database foundation
-
-- **File count:** 9
-- **Purpose:** Opens and migrates the shared SQLite database, manages migration rollback snapshots and private file permissions, and defines the bundled schema migration set.
-- **Globs:** `lib/foundation/fabro-db/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-db/src/lib.rs:Database::connect`, `lib/foundation/fabro-db/src/lib.rs:Database::migrate`, `lib/foundation/fabro-db/src/lib.rs:Database::health_check`, `lib/foundation/fabro-db/src/lib.rs:DbPool`
-- **Owns:** SQLite pool setup; WAL/synchronous/busy-timeout policy; schema migration registry; pre-migration snapshot and legacy-backup paths; database file permissions; shared tables and indexes declared in `migrations/*.sql`.
-- **Depends on candidates:** `[]`
-- **Evidence:**
- - `lib/foundation/fabro-db/Cargo.toml` — declares a SQLite storage foundation with SQLx migration support.
- - `lib/foundation/fabro-db/src/lib.rs:Database` — owns database connection, migration, snapshot, health-check, and pool access lifecycle.
- - `lib/foundation/fabro-db/migrations/*.sql` — define the variables, environments, secrets, MCP servers, automations, and run-projection schema compiled into this crate's migrator.
- - `lib/foundation/fabro-db/tests/sqlite.rs` — exercises migration, snapshot, permissions, and database behavior at the crate boundary.
- - `lib/components/fabro-variable/Cargo.toml`, `lib/components/fabro-environment/Cargo.toml`, `lib/components/fabro-mcp-store/Cargo.toml`, `lib/components/fabro-automation/Cargo.toml`, and `lib/components/fabro-store/Cargo.toml` — out-of-scope manifests show multiple persistence components sharing this foundation.
-
-### `fabro-http` — Shared HTTP transport construction
-
-- **File count:** 2
-- **Purpose:** Centralizes reqwest type exposure and synchronous/asynchronous HTTP client construction with Fabro's proxy and test no-proxy policy.
-- **Globs:** `lib/foundation/fabro-http/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder`, `lib/foundation/fabro-http/src/lib.rs:http_client`, `lib/foundation/fabro-http/src/lib.rs:test_http_client`, `lib/foundation/fabro-http/src/lib.rs:BlockingHttpClientBuilder`
-- **Owns:** approved reqwest facade; proxy-policy resolution from `FABRO_HTTP_PROXY_POLICY`; async/blocking client builders; deterministic no-proxy test clients.
-- **Depends on candidates:** `fabro-static`
-- **Evidence:**
- - `lib/foundation/fabro-http/Cargo.toml` — declares a shared reqwest-wrapper crate.
- - `lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` and `HttpClientBuilder` — implement the shared transport-construction policy rather than domain HTTP behavior.
- - The root `Cargo.toml` exposes `fabro-http` as a workspace dependency, and app/component manifests consume it directly, establishing it as a cross-cutting transport boundary.
-
-### `fabro-macros-metadata` — Compile-time macros and option metadata
-
-- **File count:** 6
-- **Purpose:** Supplies Fabro's derive/attribute macros and the runtime option-metadata model used by generated configuration and documentation tooling.
-- **Globs:** `lib/foundation/fabro-macros/**`, `lib/foundation/fabro-options-metadata/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-macros/src/lib.rs:e2e_test`, `lib/foundation/fabro-macros/src/lib.rs:derive_combine`, `lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionSet`
-- **Owns:** macro input parsing and expansion for E2E mode gates, configuration-layer combination, and option metadata; option visitor/tree representation; flattened lookup/display/serialization of option metadata.
-- **Depends on candidates:** `[]`
-- **Evidence:**
- - `lib/foundation/fabro-macros/Cargo.toml` — declares the proc-macro crate and a dev dependency on the runtime metadata crate.
- - `lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl` — generates implementations against `fabro_options_metadata::OptionsMetadata`.
- - `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata` and `OptionSet` — provide the runtime half of that generated contract.
- - `lib/foundation/fabro-macros/tests/options_metadata.rs` — tests the proc-macro/runtime pair together.
- - `lib/foundation/fabro-config/Cargo.toml` and `lib/foundation/fabro-dev/Cargo.toml` — out-of-scope consumer evidence for configuration derives and generated option documentation.
-
-### `fabro-model` — LLM model and provider catalog
-
-- **File count:** 28
-- **Purpose:** Defines provider/model identity, capabilities, billing metadata, embedded catalog data, override merging, and model selection.
-- **Globs:** `lib/foundation/fabro-model/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::from_builtin_with_overrides`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::select`, `lib/foundation/fabro-model/src/bootstrap_catalog.rs:catalog`, `lib/foundation/fabro-model/src/lib.rs`
-- **Owns:** canonical provider/model IDs; embedded provider TOML catalog; catalog indexes and selection state; provider auth declarations; model capabilities, controls, codecs/adapters, reasoning levels, pricing, and billing calculations.
-- **Depends on candidates:** `fabro-static`
-- **Evidence:**
- - `lib/foundation/fabro-model/Cargo.toml` — names provider identity, model metadata, and resolution as the crate responsibility and embeds catalog resources.
- - `lib/foundation/fabro-model/src/catalog.rs:BuiltinCatalogToml` and `Catalog` — load embedded provider files into indexed selection state.
- - `lib/foundation/fabro-model/src/catalog/providers/*.toml` — are the tracked built-in provider/model catalog sources.
- - `lib/foundation/fabro-model/src/ids.rs` — defines open-ended provider and model identity shared by auth, config, API, and LLM consumers.
- - `lib/foundation/fabro-model/src/billing.rs` and `src/types.rs` — define the catalog's billing and public model metadata surfaces.
-
-### `fabro-oauth` — OAuth PKCE and loopback callback flow
-
-- **File count:** 3
-- **Purpose:** Implements generic OAuth 2.0 PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh.
-- **Globs:** `lib/foundation/fabro-oauth/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow`, `lib/foundation/fabro-oauth/src/lib.rs:start_callback_server_with_errors`, `lib/foundation/fabro-oauth/src/lib.rs:exchange_code`, `lib/foundation/fabro-oauth/src/lib.rs:refresh_token`, `lib/foundation/fabro-oauth/examples/login.rs:main`
-- **Owns:** PKCE verifier/challenge and state generation; authorization URL encoding; ephemeral callback listener/task and shutdown handle; callback validation/result delivery; token response decoding and refresh requests.
-- **Depends on candidates:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-oauth/Cargo.toml` — declares a generic OAuth 2.0 PKCE token-acquisition crate.
- - `lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle` — owns the ephemeral callback server port and shutdown channel.
- - `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow` — composes PKCE, callback server, browser, and token exchange into the top-level flow.
- - `lib/foundation/fabro-oauth/examples/login.rs` — demonstrates the crate as a standalone protocol flow.
- - `lib/foundation/fabro-auth/Cargo.toml` and `lib/apps/fabro-cli/Cargo.toml` — out-of-scope manifests establish both auth-library and direct CLI consumers.
-
-### `fabro-proc` — OS process primitives
-
-- **File count:** 8
-- **Purpose:** Wraps platform process primitives for signals, process groups, advisory file locking, pre-exec hooks, process liveness, and process-title rewriting.
-- **Globs:** `lib/foundation/fabro-proc/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-proc/src/lib.rs`, `lib/foundation/fabro-proc/src/signal.rs:process_running`, `lib/foundation/fabro-proc/src/signal.rs:sigterm_process_group`, `lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid`, `lib/foundation/fabro-proc/src/title.rs:init`
-- **Owns:** Unix signal/process-group calls; cross-platform liveness semantics; advisory locks; child pre-exec configuration; captured argv memory and process title state.
-- **Depends on candidates:** `[]`
-- **Evidence:**
- - `lib/foundation/fabro-proc/Cargo.toml` — describes safe wrappers for process-management primitives and compiles the C argv capture helper.
- - `lib/foundation/fabro-proc/src/lib.rs` — is a platform-gated facade over flock, pre-exec, signal, and title modules.
- - `lib/foundation/fabro-proc/c/capture_argv.c` and `lib/foundation/fabro-proc/build.rs` — establish the FFI/build boundary for title rewriting.
- - `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-cli/Cargo.toml`, and `lib/components/fabro-sandbox/Cargo.toml` — out-of-scope manifests show independent process-lifecycle consumers.
-
-### `fabro-redact` — Secret and credential redaction
-
-- **File count:** 8
-- **Purpose:** Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded Gitleaks rules and entropy scanning.
-- **Globs:** `lib/foundation/fabro-redact/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-redact/src/lib.rs:redact_string`, `lib/foundation/fabro-redact/src/lib.rs:redacted_url_for_log`, `lib/foundation/fabro-redact/src/jsonl.rs:redact_jsonl_line`, `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl`
-- **Owns:** Gitleaks rule source and generated rule table; lazy rule engine; entropy thresholds; overlap merging and redaction marker; JSON field/object skip policy; safe URL display semantics.
-- **Depends on candidates:** `[]`
-- **Evidence:**
- - `lib/foundation/fabro-redact/Cargo.toml` — declares the secret/credential redaction boundary.
- - `lib/foundation/fabro-redact/build.rs:main` and `lib/foundation/fabro-redact/data/gitleaks.toml` — compile the tracked rule source into an untracked `OUT_DIR` table.
- - `lib/foundation/fabro-redact/src/lib.rs:redact_string` — composes entropy and Gitleaks detection into one public redaction surface.
- - `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` — owns the raw-versus-display URL credential boundary.
- - `lib/foundation/fabro-redact/src/jsonl.rs` — applies the scanner to structured event/log content.
-
-### `fabro-static` — Shared static conventions
-
-- **File count:** 4
-- **Purpose:** Defines dependency-light canonical environment-variable names and the registry that classifies bootstrap and optional-vault secrets.
-- **Globs:** `lib/foundation/fabro-static/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-static/src/env_vars.rs:EnvVars`, `lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret`, `lib/foundation/fabro-static/src/secret_registry.rs:optional_vault_secrets`
-- **Owns:** canonical process environment string constants; bootstrap-secret set; optional vault-secret set and classification.
-- **Depends on candidates:** `[]`
-- **Evidence:**
- - `lib/foundation/fabro-static/Cargo.toml` — declares a no-dependency static string registry.
- - `lib/foundation/fabro-static/src/env_vars.rs:EnvVars` — centralizes environment names consumed across applications, components, and foundation crates.
- - `lib/foundation/fabro-static/src/secret_registry.rs` — defines secret scope independently of vault/auth implementations.
- - The root `Cargo.toml` exposes the crate as a workspace dependency, and `fabro-http`, `fabro-model`, `fabro-util`, auth, telemetry, server, CLI, sandbox, Slack, and GitHub manifests consume it.
-
-### `fabro-telemetry` — Analytics and crash telemetry
-
-- **File count:** 11
-- **Purpose:** Initializes analytics/crash reporting, builds anonymous telemetry context, buffers events, and hands delivery to blocking or detached senders across CLI and server lifecycles.
-- **Globs:** `lib/foundation/fabro-telemetry/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-telemetry/src/lib.rs:init_cli`, `lib/foundation/fabro-telemetry/src/lib.rs:init_server`, `lib/foundation/fabro-telemetry/src/lib.rs:track`, `lib/foundation/fabro-telemetry/src/lib.rs:shutdown`, `lib/foundation/fabro-telemetry/src/panic.rs:install_panic_hook`
-- **Owns:** process-global telemetry state; anonymous CLI/server identifiers; background buffer thread and shutdown join; analytics event shape/context; command sanitization; Segment delivery and detached subprocess handoff; Sentry panic capture.
-- **Depends on candidates:** `fabro-http`, `fabro-static`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-telemetry/Cargo.toml` — declares analytics and crash reporting with HTTP, Sentry, Git, and process-spawn dependencies.
- - `lib/foundation/fabro-telemetry/src/lib.rs:Global` — owns the process-global sender, identity, context, level, and background thread.
- - `lib/foundation/fabro-telemetry/src/buffer.rs` and `src/sender.rs` — define buffered delivery and upload boundaries.
- - `lib/foundation/fabro-telemetry/src/spawn.rs` — owns the detached subprocess handoff used at process exit.
- - `lib/foundation/fabro-telemetry/src/panic.rs` — owns panic-hook event construction and capture.
-
-### `fabro-template` — Template rendering and dependency discovery
-
-- **File count:** 4
-- **Purpose:** Renders MiniJinja templates with Fabro context, source-aware diagnostics, rooted include stores, caching/recording wrappers, and static dependency discovery.
-- **Globs:** `lib/foundation/fabro-template/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-template/src/lib.rs:render_source`, `lib/foundation/fabro-template/src/lib.rs:render_named`, `lib/foundation/fabro-template/src/lib.rs:TemplateContext`, `lib/foundation/fabro-template/src/store.rs:TemplateStore`, `lib/foundation/fabro-template/src/dependency.rs:discover_static_dependency_closure`
-- **Owns:** template context/value exposure; strict and lenient render modes; source-location error diagnostics; include/import path safety and rooted resolution; filesystem/bundle/cache/recording stores; static dependency closure.
-- **Depends on candidates:** `fabro-types`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-template/Cargo.toml` — declares the shared MiniJinja rendering boundary.
- - `lib/foundation/fabro-template/src/lib.rs:TemplateContext` and `TemplateError` — define the public render input and source-aware failure surface.
- - `lib/foundation/fabro-template/src/store.rs:TemplateStore` and `TemplateIncludeResolver` — define source loading and root containment.
- - `lib/foundation/fabro-template/src/dependency.rs` — owns include/import extraction and dependency-closure discovery.
- - `lib/components/fabro-agent/Cargo.toml`, `lib/components/fabro-workflow/Cargo.toml`, and `lib/components/fabro-manifest/Cargo.toml` — out-of-scope manifests show agent, workflow, and manifest consumers.
-
-### `fabro-test` — Shared integration-test infrastructure
-
-- **File count:** 3
-- **Purpose:** Provides isolated Fabro CLI/server integration-test contexts, twin/live mode control, process and environment harnessing, snapshot normalization, and HTTP assertion helpers.
-- **Globs:** `lib/foundation/fabro-test/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-test/src/lib.rs:TestContext`, `lib/foundation/fabro-test/src/lib.rs:TestMode`, `lib/foundation/fabro-test/src/lib.rs:apply_test_isolation`, `lib/foundation/fabro-test/src/lib.rs:test_http_client`, `lib/foundation/fabro-test/src/http_assert.rs:expect_reqwest_status`
-- **Owns:** per-test temporary home/storage/session/server lifecycle; E2E mode and live-secret gating; subprocess environment isolation; test daemon coordination; snapshot filters; twin service setup; Axum/reqwest response assertion diagnostics.
-- **Depends on candidates:** `fabro-config`, `fabro-http`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`
-- **External dependency edges:** depends on the `fabro-install`, `twin-openai`, and `twin-github` test components.
-- **Evidence:**
- - `lib/foundation/fabro-test/Cargo.toml` — identifies the crate as integration-test utilities and declares test-only component/twin dependencies.
- - `lib/foundation/fabro-test/src/lib.rs:TestContext` — owns isolated test paths, session state, Fabro binary invocation, filters, and managed server/storage state.
- - `lib/foundation/fabro-test/src/lib.rs:TestMode` and `apply_test_isolation` — define the twin/live/strict and environment-isolation contracts used by the `e2e_test` macro.
- - `lib/foundation/fabro-test/src/http_assert.rs` — centralizes response consumption and diagnostic assertion behavior for both server and network tests.
- - Workspace app/component manifests list `fabro-test` only in dev-dependency/test contexts.
-
-### `fabro-types` — Shared product contracts and state records
-
-- **File count:** 78
-- **Purpose:** Defines the serializable identifiers, settings records, run/session/event/state projections, and other shared product vocabulary exchanged across Fabro crates and API boundaries.
-- **Globs:** `lib/foundation/fabro-types/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-types/src/lib.rs`, `lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent`, `lib/foundation/fabro-types/src/run.rs:RunSpec`, `lib/foundation/fabro-types/src/settings/mod.rs`, `lib/foundation/fabro-types/src/outcome.rs:Outcome`, `lib/foundation/fabro-types/src/status.rs:RunStatus`
-- **Owns:** canonical serde shapes and IDs for runs, stages, sessions, events, transcripts, outcomes, status, projections, sandboxes, MCP servers, variables, secrets, integrations, billing, repositories, pull requests, and dense/resolved settings; feature-gated shared test fixtures.
-- **Depends on candidates:** `fabro-model`, `fabro-util`
-- **Evidence:**
- - `lib/foundation/fabro-types/Cargo.toml` — describes shared record structs/enums and exposes only `clap` and `test-support` feature boundaries.
- - `lib/foundation/fabro-types/src/lib.rs` — is a single crate facade that re-exports the canonical shared product vocabulary across its module families.
- - `lib/foundation/fabro-types/src/run_event/mod.rs` and `src/run_event/*.rs` — define the event contract consumed by workflow, storage, server, client, and API code.
- - `lib/foundation/fabro-types/src/settings/mod.rs` and `src/settings/*.rs` — define the resolved settings contract consumed by `fabro-config` and runtime components.
- - `lib/foundation/fabro-types/tests/*.rs` — verify serde and method contracts for run specs, events, failures, sandbox models, inventory, and stage handlers.
- - `lib/foundation/fabro-api/build.rs` and its round-trip tests — boundary evidence that API generation intentionally reuses these types rather than generating parallel DTOs.
-
-### `fabro-util` — Cross-cutting runtime and CLI utilities
-
-- **File count:** 24
-- **Purpose:** Provides shared environment, filesystem, shell, terminal, logging, token, error-rendering, time, backoff, warning, and workspace-glob primitives used across Fabro crates.
-- **Globs:** `lib/foundation/fabro-util/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-util/src/lib.rs`, `lib/foundation/fabro-util/src/shell.rs:shell_quote`, `lib/foundation/fabro-util/src/printer.rs:Printer`, `lib/foundation/fabro-util/src/home.rs:Home`, `lib/foundation/fabro-util/src/run_log.rs:BufferedFileAppender`, `lib/foundation/fabro-util/src/workspace_glob.rs:WorkspaceGlobSet`
-- **Owns:** low-level helper contracts and any helper-owned state, including the global warning set, buffered run-log guard, environment abstraction, home directory, dev/session token formats, terminal styles/printers, backoff policy, error-chain rendering, and workspace glob compilation.
-- **Depends on candidates:** `fabro-static`
-- **Evidence:**
- - `lib/foundation/fabro-util/Cargo.toml` — identifies shared terminal/path/environment/runtime helpers and has no product-component dependencies.
- - `lib/foundation/fabro-util/src/lib.rs` — exposes the helper modules directly as the public crate facade.
- - `lib/foundation/fabro-util/src/shell.rs` — owns shell quoting/joining used by workflow and developer tooling.
- - `lib/foundation/fabro-util/src/run_log.rs` and `src/warnings.rs` — contain the component's stateful log-guard and warning-registry lifecycles.
- - `lib/foundation/fabro-util/tests/dev_token.rs` and `tests/error_chain.rs` — test stable token-file and error-rendering contracts.
-
-### `fabro-vault` — Secret vault and SQLite secret store
-
-- **File count:** 4
-- **Purpose:** Validates and stores workflow-visible secrets in file/in-memory vaults or the shared SQLite database, including revision-aware updates and one-time legacy import.
-- **Globs:** `lib/foundation/fabro-vault/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `lib/foundation/fabro-vault/src/lib.rs:Vault::load`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::open`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::apply`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::snapshot`, `lib/foundation/fabro-vault/src/store.rs:import_legacy_json_once`
-- **Owns:** secret-name/type validation; redacted secret entry representation; atomic JSON vault persistence; SQL secret CRUD; secret revisions and compare-and-swap refresh updates; snapshots; legacy JSON import and backup lifecycle.
-- **Depends on candidates:** `fabro-db`, `fabro-static`, `fabro-types`
-- **Evidence:**
- - `lib/foundation/fabro-vault/Cargo.toml` — declares the workflow-visible secret vault and its database/type dependencies.
- - `lib/foundation/fabro-vault/src/lib.rs:Vault` — owns file-backed or detached in-memory entries and atomic write behavior.
- - `lib/foundation/fabro-vault/src/store.rs:SecretStore` — owns the SQLite-backed secret operations and snapshots.
- - `lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision` — exposes the revision boundary used for concurrent OAuth refresh write-back.
- - `lib/foundation/fabro-vault/tests/store.rs` — exercises store CRUD, validation, snapshots, and legacy import at the public boundary.
-
-## Coverage
-
-| Proposed component | Tracked files |
-| --- | ---: |
-| `fabro-build-tooling` | 23 |
-| `fabro-api` | 60 |
-| `fabro-auth` | 16 |
-| `fabro-client` | 9 |
-| `fabro-config` | 52 |
-| `fabro-core` | 13 |
-| `fabro-db` | 9 |
-| `fabro-http` | 2 |
-| `fabro-macros-metadata` | 6 |
-| `fabro-model` | 28 |
-| `fabro-oauth` | 3 |
-| `fabro-proc` | 8 |
-| `fabro-redact` | 8 |
-| `fabro-static` | 4 |
-| `fabro-telemetry` | 11 |
-| `fabro-template` | 4 |
-| `fabro-test` | 3 |
-| `fabro-types` | 78 |
-| `fabro-util` | 24 |
-| `fabro-vault` | 4 |
-| **Total assigned** | **365** |
-
-- **Relevant tracked files:** 365
-- **Assigned:** 365
-- **Excluded:** 0
-- **Unmapped:** 0
-- **Overlap:** 0; every proposed glob is a whole crate directory, and the two grouped components use disjoint crate directories.
-- **Tracked exclusions:** none. Build outputs such as `OUT_DIR/codegen.rs` and `OUT_DIR/rules_generated.rs` are generated but are not tracked and therefore are not part of the 365-file inventory. No vendored or generated tracked source was found in scope.
-- **Unmapped files:** `[]`
-
-## External boundary evidence consulted
-
-These files are outside the scoped inventory and are neither assigned nor counted as unmapped:
-
-- `Cargo.toml` — workspace membership, workspace dependencies, and lint policy.
-- `docs/public/api-reference/fabro-api.yaml` — source contract read by `fabro-api/build.rs`.
-- `lib/apps/fabro-cli/Cargo.toml`, `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-mcp-server/Cargo.toml` — application-level reverse dependency evidence.
-- Relevant `lib/components/*/Cargo.toml` manifests — reverse dependency evidence for execution, storage, schema, types, templates, auth, HTTP, process, test, and API foundations.
-
-## Genuine boundary questions
-
-1. Should `build-support` remain grouped with `fabro-dev` in the final map, or should its compile-time consumer boundary make it a separate two-file component despite the resulting assessment granularity?
-2. Should `fabro-macros` and `fabro-options-metadata` remain one component? Their `OptionsMetadata` compiler/runtime contract supports grouping, while `Combine` and `e2e_test` also connect the proc-macro crate to configuration and test infrastructure.
-3. Should the SQL migration files under `fabro-db/migrations/**` remain with the shared database foundation, or should reconciliation assign table-specific migrations to the variable, environment, MCP-store, automation, and run-store components that own the corresponding query behavior? The current proposal follows compile-time ownership by `fabro-db`.
-4. Is `fabro-types` an acceptable single assessment component, or does the final map need stable subcomponents for settings, run/event/projection, and other contract families? This revision exposes one manifest and one broad crate facade, so this scout found no non-overlapping public boundary for such a split.
diff --git a/.chisel/cartography/work/tests-evals.md b/.chisel/cartography/work/tests-evals.md
deleted file mode 100644
index 7b66d5825..000000000
--- a/.chisel/cartography/work/tests-evals.md
+++ /dev/null
@@ -1,332 +0,0 @@
-# Cartography scout report: tests and evaluations
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
-
-Scope: all 180 tracked files under `test/**` and `evals/**`. Cargo workspace
-manifests, test consumers, repository documentation sources, and implementation
-entry points were consulted only as boundary evidence and are not included in
-this scope's counts.
-
-Applicable instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and
-`docs/internal/testing-strategy.md` (`CLAUDE.md` is a symlink to `AGENTS.md`).
-
-## Boundary decisions
-
-- `twin-openai` and `twin-github` are separate components. Each is a distinct
- Cargo workspace member with its own protocol surface, router, state model,
- lifecycle, fixtures, and consumers. Their common use as local fake services
- is not enough to combine OpenAI scenario/stream behavior with GitHub
- repository/authentication behavior.
-- The checked-in workflow fixtures outside `test/docs/**` are proposed as a
- shared `workflow-test-corpus` component. They are all user-facing workflow,
- configuration, prompt, and template inputs, and they are intentionally
- consumed across CLI, workflow, graph-language, rendering, and validation
- tests. Keeping them together avoids assigning shared compatibility data to
- one arbitrary production consumer.
-- `test/docs/**` is proposed as a separate
- `documentation-workflow-tests` component. It has its own extraction and
- multi-phase runner entry points and owns a documentation-derived but curated
- executable corpus. The tracked fixtures are test source: the checklist
- records extracted, assembled, and adapted cases, and `run_tests.sh` executes
- them directly. They are therefore assigned rather than excluded as generated
- output.
-- The SWE-bench tooling is a distinct evaluation component. It owns a
- generation, grading, monitoring, environment-generation, and result-recording
- workflow that is independent of the normal Cargo test lifecycle.
-- `evals/swe-bench/scoreboard/**` is not executable evaluation source. The
- evaluation README calls it a Git-tracked permanent record, and
- `record_results.py` writes every tracked file shape beneath it. Those 16
- recorded outputs are proposed as a global exclusion.
-- The two distribution shell tests and the benchmark-analysis SQL do not form a
- coherent component together. They are recommended additions to existing
- components, described after the component proposals.
-
-## Proposed components
-
-### `twin-openai` — OpenAI protocol twin
-
-- **File count:** 35 (28 Rust, 5 Markdown, 1 Cargo manifest, 1 `.gitignore`)
-- **Purpose:** Provides a deterministic OpenAI-compatible HTTP service for
- black-box and protocol-contract tests, including scripted successes,
- failures, streaming, request inspection, and live shape comparison.
-- **Globs:** `test/twin/openai/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `test/twin/openai/src/main.rs:main`,
- `test/twin/openai/src/lib.rs:build_app`,
- `test/twin/openai/src/lib.rs:build_app_with_config`,
- `test/twin/openai/src/app.rs:router`
-- **Owns:** server bind/configuration lifecycle; `/v1/responses` and
- `/v1/chat/completions` request/response contracts; bearer-token namespaces;
- FIFO scenario queues; deterministic response IDs; normalized request logs;
- SSE construction and transport-failure behavior; admin reset/scenario APIs;
- debug UI and snapshots; local and opt-in live contract suites.
-- **Depends on candidates:** `fabro-http`, `fabro-static`
-- **Evidence:**
- - `Cargo.toml` — lists `test/twin/openai` as a workspace member and exposes
- `twin-openai` as a workspace dependency.
- - `test/twin/openai/Cargo.toml` — declares a non-published library/binary
- package described as a fake OpenAI-compatible server.
- - `test/twin/openai/src/app.rs:router` and
- `test/twin/openai/src/openai/mod.rs:router` — compose the health, OpenAI,
- admin, and debug HTTP surfaces.
- - `test/twin/openai/src/state.rs:AppState` — owns namespaced response
- counters, scenario queues, and request logs.
- - `test/twin/openai/src/engine/scenario.rs:ScenarioScript` — defines scripted
- success, application-error, delay, partial/malformed stream, and hang
- behavior.
- - `test/twin/openai/tests/common/mod.rs:spawn_server` and the eight sibling
- contract suites — exercise the service as a protocol boundary; the ignored
- `live_openai_contract.rs` compares supported protocol shapes with the live
- API.
- - `lib/foundation/fabro-test/Cargo.toml` and
- `lib/foundation/fabro-test/src/lib.rs:twin_openai` — show the shared
- integration-test harness consuming this package as an in-process service.
-
-### `twin-github` — GitHub protocol twin
-
-- **File count:** 20 (17 Rust, 2 PEM fixtures, 1 Cargo manifest)
-- **Purpose:** Provides an in-process fake GitHub service with seeded mutable
- state and temporary Git repositories for black-box GitHub App, OAuth, API,
- GraphQL, and smart-HTTP tests.
-- **Globs:** `test/twin/github/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `test/twin/github/src/server.rs:TestServer::start`,
- `test/twin/github/src/server.rs:build_router`,
- `test/twin/github/src/state.rs:AppState`,
- `test/twin/github/src/fixtures.rs:FixtureState::into_app_state`
-- **Owns:** ephemeral listener and shutdown lifecycle; temporary bare Git
- repositories; fake apps, installations, repositories, branches, pull
- requests, releases, projects, comments, webhook configuration, manifest
- conversions, access tokens, OAuth codes/tokens/users; GitHub authentication
- checks; bundled test RSA key pair.
-- **Depends on candidates:** `fabro-http`
-- **Evidence:**
- - `Cargo.toml` — lists `test/twin/github` independently as a workspace member
- and workspace dependency.
- - `test/twin/github/Cargo.toml` — declares a non-published library package
- described as a fake GitHub API server.
- - `test/twin/github/src/handlers/mod.rs:build_router` — registers the GitHub
- App, installation, branch, pull-request, manifest, OAuth, user, release,
- GraphQL, and Git smart-HTTP routes.
- - `test/twin/github/src/state.rs:AppState` — owns the central seeded and
- mutable GitHub-domain state.
- - `test/twin/github/src/server.rs:TestServer::start` — initializes temporary
- Git repositories, binds an ephemeral listener, and controls graceful
- shutdown.
- - `test/twin/github/src/fixtures.rs:FixtureState` and
- `test/twin/github/src/testdata/*.pem` — define reusable seeded service data
- and the owned authentication fixtures.
- - `lib/foundation/fabro-test/src/lib.rs:TwinGitHub` and
- `lib/apps/fabro-cli/tests/it/support/auth_harness.rs` — show this twin
- serving the CLI/server authentication integration boundary.
-
-### `workflow-test-corpus` — Shared workflow compatibility fixtures
-
-- **File count:** 42
- - 8 root `test/*.fabro` workflows
- - 14 `test/attractor/*.dot` compatibility graphs
- - 3 `test/dot-compatibility/*.fabro` graphs
- - 17 templating/configuration files under the four templated fixture trees
-- **Purpose:** Supplies reusable user-facing workflow, compatibility,
- configuration, prompt, partial, and template inputs to cross-crate parser,
- validator, renderer, workflow, and CLI tests.
-- **Globs:** `test/*.fabro`, `test/attractor/**`,
- `test/dot-compatibility/**`, `test/templated_inputs/**`,
- `test/templated_unbound_imported/**`,
- `test/templated_unbound_partial/**`, `test/templates/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `test/simple.fabro`,
- `test/attractor/simple_example.dot`,
- `test/dot-compatibility/acp-agent-chain.fabro`,
- `test/templates/static_dependencies/workflow.fabro`,
- `test/templates/sibling_partial/workflow.fabro`
-- **Owns:** representative valid and invalid workflow shapes; branching,
- conditions, parallelism, styles, and legacy syntax cases; Attractor DOT
- compatibility graphs; shared DOT parse/render/validation cases; template
- input, import, include, sibling-partial, static-dependency, and
- missing-dependency fixture trees.
-- **Depends on candidates:** `fabro-cli`, `fabro-graphviz`, `fabro-template`,
- `fabro-test`, `fabro-validate`, `fabro-workflow`
-- **Evidence:**
- - `docs/internal/testing-strategy.md` — explicitly recognizes checked-in
- user-facing workflows, configs, prompts, and repository contents as shared
- fixtures.
- - `lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture` —
- resolves named inputs from the repository `test/` directory for isolated
- CLI tests.
- - `lib/apps/fabro-cli/tests/it/cmd/validate.rs` and
- `lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs` — consume the
- root workflows and all templating fixture trees as black-box CLI inputs.
- - `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — enumerates
- and parses every graph in `test/attractor/**`.
- - `lib/components/fabro-graphviz/src/render.rs:dot_compatibility_fixtures`
- and
- `lib/components/fabro-validate/src/lib.rs:dot_compatibility_fixtures` —
- independently enumerate the same three `test/dot-compatibility/**` inputs,
- establishing that corpus as shared rather than crate-local.
-
-### `documentation-workflow-tests` — Documentation workflow conformance
-
-- **File count:** 55 (40 Fabro workflows, 7 shell files, 5 Markdown files, 2
- run TOML files, 1 Python extractor)
-- **Purpose:** Extracts, curates, validates, preflights, and executes workflow
- examples and companion files derived from Fabro documentation.
-- **Globs:** `test/docs/**`
-- **Exclude globs:** `[]`
-- **Entry points:** `test/docs/run_tests.sh`,
- `test/docs/extract_dots.py:main`, `test/docs/CHECKLIST.md`
-- **Owns:** documentation-example corpus layout; prompt and script stubs;
- variable-bearing run configurations; extraction naming and stub generation;
- validate/preflight/dry-run/live phase selection; parallel execution and
- temporary result/run directories; the documented corpus checklist.
-- **Depends on candidates:** `fabro-cli`, `fabro-workflow`, the final
- documentation-site component
-- **Evidence:**
- - `test/docs/run_tests.sh:run_one` — discovers all 40 tracked `*.fabro`
- examples and invokes the built `fabro` binary in validate, preflight,
- dry-run, model-specific, or full execution modes.
- - `test/docs/extract_dots.py:main` — reads documentation Markdown, extracts
- complete DOT graphs, and creates companion prompt stubs and run
- configurations under `test/docs`.
- - `test/docs/CHECKLIST.md` — documents the 40-example corpus, distinguishes
- extracted and assembled cases, records companion-file needs, and provides
- the runner commands.
- - `.claude/skills/docs/SKILL.md` — instructs documentation changes containing
- full DOT graphs to run `./test/docs/run_tests.sh validate`, tying this
- harness to the documentation change lifecycle.
-
-### `swe-bench-evaluation` — SWE-bench evaluation workflow
-
-- **File count:** 9 (6 Python scripts, 1 Fabro workflow, 1 requirements file, 1
- README)
-- **Purpose:** Generates Fabro patches for SWE-bench Lite instances, grades
- them through Daytona or the official harness, monitors runs, and records
- normalized result summaries.
-- **Globs:** `evals/swe-bench/*.py`, `evals/swe-bench/*.fabro`,
- `evals/swe-bench/*.txt`, `evals/swe-bench/README.md`
-- **Exclude globs:** `[]` (the sibling scoreboard is a global exclusion)
-- **Entry points:** `evals/swe-bench/run_eval.py:main`,
- `evals/swe-bench/evaluate_daytona.py:main`,
- `evals/swe-bench/evaluate.py:main`,
- `evals/swe-bench/record_results.py:main`,
- `evals/swe-bench/status.py:main`,
- `evals/swe-bench/gen_dockerfile.py:main`
-- **Owns:** SWE-bench Lite dataset selection; per-instance goal/workflow/TOML
- generation; Daytona snapshot and sandbox specifications; Fabro subprocess
- orchestration and timeout cleanup; patch extraction; official and
- Daytona-based grading; progress summaries; scoreboard record schema and
- leaderboard regeneration.
-- **Depends on candidates:** `fabro-cli`, `fabro-sandbox`,
- `fabro-workflow`
-- **External dependencies:** Hugging Face `datasets`, the `swebench` harness,
- Daytona, and optionally Docker through the official harness.
-- **Evidence:**
- - `evals/swe-bench/README.md` — defines the three-stage generate, evaluate,
- and record lifecycle, the two grading backends, and raw-versus-recorded
- result locations.
- - `evals/swe-bench/run_eval.py:run_instance` — creates per-instance Fabro
- workflows/configs, invokes `fabro run`, and extracts produced patches.
- - `evals/swe-bench/evaluate_daytona.py` — creates grading workflows and
- executes held-out tests in Daytona snapshots.
- - `evals/swe-bench/evaluate.py:main` — exposes the alternative official
- Docker-backed `swebench.harness.run_evaluation` path.
- - `evals/swe-bench/gen_dockerfile.py:generate_dockerfile` — translates
- SWE-bench repository/version specs into reusable sandbox images.
- - `evals/swe-bench/record_results.py:main` and
- `regenerate_leaderboard` — define and write the tracked scoreboard record
- formats.
-
-## Recommended additions to existing components
-
-These files are assigned in the coverage accounting but do not justify new
-components:
-
-| File | Recommended component | Reason |
-| --- | --- | --- |
-| `test/bin/install_test.sh` | documentation/web scout's marketing-site component | It is a black-box shell contract test whose sole product target is `apps/marketing/public/install.sh`; it owns a fake `gh` executable and temporary install home only for that test. |
-| `test/bin/release_test.sh` | `fabro-build-tooling` | It is an executable release-mode shell contract and changes with the repository release-automation lifecycle. |
-| `test/analysis/bench-tests-diff.sql` | `fabro-build-tooling` | Its documented inputs are the two CSVs produced by `cargo dev bench-tests`, whose implementation is `lib/foundation/fabro-dev/src/commands/bench_tests.rs`. |
-
-## Global exclusion
-
-### Recorded SWE-bench scoreboards
-
-- **Globs:** `evals/swe-bench/scoreboard/**`
-- **Tracked files:** 16 (1 leaderboard JSON plus 5 run directories containing
- one `README.md`, one `meta.json`, and one `instances.jsonl` each)
-- **Reason:** committed evaluation records generated by
- `evals/swe-bench/record_results.py`, not executable evaluation source.
-- **Evidence:** `evals/swe-bench/README.md` calls the directory a Git-tracked
- permanent record; `record_results.py` writes `instances.jsonl`, `meta.json`,
- each run `README.md`, and regenerates `leaderboard.json`.
-
-Raw `evals/swe-bench/results/**` data is also described as generated output,
-but it is not tracked at the assessed revision and therefore is not part of
-the 180-file inventory.
-
-No `test/docs/**` files are excluded. Although the extractor derives some
-files from documentation, the tracked corpus includes assembled/adapted
-executable fixtures and companion stubs/configuration, and the runner consumes
-those files as test inputs.
-
-## Coverage
-
-| Assignment | Tracked files |
-| --- | ---: |
-| `twin-openai` | 35 |
-| `twin-github` | 20 |
-| `workflow-test-corpus` | 42 |
-| `documentation-workflow-tests` | 55 |
-| `swe-bench-evaluation` | 9 |
-| Recommended addition to marketing-site component | 1 |
-| Recommended additions to `fabro-build-tooling` | 2 |
-| Global exclusion: SWE-bench scoreboards | 16 |
-| **Scoped inventory** | **180** |
-
-- **Assigned:** 164 (161 in proposed test/evaluation components and 3 additions
- to existing components)
-- **Excluded:** 16
-- **Unmapped:** 0
-- **Overlap:** 0
-- **Accounting check:** `164 + 16 + 0 = 180`
-- **Unmapped files:** `[]`
-
-## External boundary evidence consulted
-
-These files are outside the scoped inventory and are neither assigned nor
-counted as unmapped:
-
-- `Cargo.toml` — workspace membership and workspace dependency declarations for
- both twin services.
-- `lib/foundation/fabro-test/Cargo.toml` and
- `lib/foundation/fabro-test/src/lib.rs` — shared fixture installation and twin
- service consumption.
-- `lib/apps/fabro-cli/tests/it/**` — black-box workflow fixture and twin-GitHub
- consumers.
-- `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — Attractor
- corpus consumer.
-- `lib/components/fabro-graphviz/src/render.rs` and
- `lib/components/fabro-validate/src/lib.rs` — shared DOT compatibility corpus
- consumers.
-- `docs/internal/testing-strategy.md` — repository test-layer and fixture
- ownership policy.
-- `.claude/skills/docs/SKILL.md` — documentation test-runner invocation policy.
-- `apps/marketing/public/install.sh` — install shell-test target.
-- `lib/foundation/fabro-dev/src/commands/bench_tests.rs` — benchmark CSV
- producer consumed by the analysis SQL.
-
-## Genuine boundary questions
-
-1. Should `workflow-test-corpus` remain a distinct 42-file shared data
- component, as proposed, or should reconciliation distribute its three
- subcorpora to `fabro-cli` (25 general/template fixtures),
- `fabro-workflow` (14 Attractor fixtures), and `fabro-graphviz` (3 shared DOT
- compatibility fixtures)? The cross-crate consumers support a shared
- boundary, while the production behaviors they exercise support attachment.
-2. Should `documentation-workflow-tests` remain a separate executable harness,
- or should its 55 files be included in the documentation-site component?
- Its runner and phase lifecycle support separation; its source derivation and
- documentation-change trigger support inclusion with documentation.
-3. Should `test/bin/release_test.sh` be assigned to `fabro-build-tooling` as a
- release-lifecycle contract, or remain separately unmapped until the final
- map determines which current release entry point owns that shell contract?
diff --git a/.chisel/cartography/work/validate-render.mjs b/.chisel/cartography/work/validate-render.mjs
deleted file mode 100644
index 33f1e4174..000000000
--- a/.chisel/cartography/work/validate-render.mjs
+++ /dev/null
@@ -1,271 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
-
-function fail(message) {
- throw new Error(message);
-}
-
-function globRegex(glob) {
- let source = "^";
- for (let index = 0; index < glob.length; index += 1) {
- const character = glob[index];
- if (character === "*") {
- if (glob[index + 1] === "*") {
- source += ".*";
- index += 1;
- } else {
- source += "[^/]*";
- }
- } else if (character === "?") {
- source += "[^/]";
- } else {
- source += character.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
- }
- }
- return new RegExp(`${source}$`);
-}
-
-function matchesAny(path, globs) {
- return globs.some((glob) => globRegex(glob).test(path));
-}
-
-function requireKeys(value, expected, label) {
- const actual = Object.keys(value).sort();
- const wanted = [...expected].sort();
- if (JSON.stringify(actual) !== JSON.stringify(wanted)) {
- fail(
- `${label} keys differ\nexpected ${JSON.stringify(wanted)}\nfound ${JSON.stringify(actual)}`,
- );
- }
-}
-
-function referencedPath(reference) {
- return reference.split(" — ", 1)[0].split(":", 1)[0];
-}
-
-function validate(map) {
- requireKeys(
- map,
- [
- "schema_version",
- "cartography_version",
- "created_at",
- "repository",
- "instructions",
- "overview",
- "global_exclusions",
- "components",
- "unmapped_files",
- "coverage",
- "open_questions",
- ],
- "map",
- );
- requireKeys(
- map.repository,
- ["name", "root", "revision", "short_revision"],
- "repository",
- );
- requireKeys(
- map.coverage,
- [
- "relevant_file_count",
- "assigned_file_count",
- "excluded_file_count",
- "unmapped_file_count",
- ],
- "coverage",
- );
- if (map.schema_version !== 1) fail("schema_version must be 1");
- if (map.cartography_version !== 1) fail("cartography_version must be 1");
-
- const files = execFileSync(
- "git",
- ["ls-tree", "-r", "--name-only", map.repository.revision],
- { encoding: "utf8" },
- )
- .trim()
- .split("\n")
- .filter(Boolean);
- const fileSet = new Set(files);
- const ids = map.components.map(({ id }) => id);
- if (new Set(ids).size !== ids.length) fail("component IDs are not unique");
- for (const id of ids) {
- if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) {
- fail(`invalid component ID: ${id}`);
- }
- }
-
- const allGlobs = [];
- for (const exclusion of map.global_exclusions) {
- requireKeys(exclusion, ["globs", "reason"], "global exclusion");
- allGlobs.push(...exclusion.globs);
- }
- for (const component of map.components) {
- requireKeys(
- component,
- [
- "id",
- "name",
- "purpose",
- "globs",
- "exclude_globs",
- "entry_points",
- "owns",
- "depends_on",
- "evidence",
- ],
- `component ${component.id}`,
- );
- allGlobs.push(...component.globs, ...component.exclude_globs);
- for (const dependency of component.depends_on) {
- if (!ids.includes(dependency)) {
- fail(`${component.id} depends on missing component ${dependency}`);
- }
- if (dependency === component.id) {
- fail(`${component.id} depends on itself`);
- }
- }
- for (const reference of [...component.entry_points, ...component.evidence]) {
- const path = referencedPath(reference);
- if (!fileSet.has(path)) {
- fail(`${component.id} references missing path ${path}`);
- }
- }
- }
- for (const instruction of map.instructions) {
- if (!fileSet.has(instruction)) fail(`missing instruction ${instruction}`);
- }
- for (const glob of allGlobs) {
- if (!files.some((path) => globRegex(glob).test(path))) {
- fail(`glob resolves to no tracked files: ${glob}`);
- }
- }
-
- const excluded = new Set(
- files.filter((path) =>
- map.global_exclusions.some(({ globs }) => matchesAny(path, globs)),
- ),
- );
- const claims = new Map();
- for (const component of map.components) {
- for (const path of files) {
- if (
- matchesAny(path, component.globs) &&
- !matchesAny(path, component.exclude_globs)
- ) {
- if (excluded.has(path)) {
- fail(`${path} is both globally excluded and claimed by ${component.id}`);
- }
- const previous = claims.get(path);
- if (previous) {
- fail(`${path} is claimed by both ${previous} and ${component.id}`);
- }
- claims.set(path, component.id);
- }
- }
- }
-
- for (const path of map.unmapped_files) {
- if (!fileSet.has(path)) fail(`unmapped file does not exist: ${path}`);
- if (excluded.has(path) || claims.has(path)) {
- fail(`unmapped file also has another disposition: ${path}`);
- }
- }
- const unmapped = new Set(map.unmapped_files);
- const missing = files.filter(
- (path) => !claims.has(path) && !excluded.has(path) && !unmapped.has(path),
- );
- if (missing.length > 0) {
- fail(`files lack a disposition:\n${missing.join("\n")}`);
- }
-
- const computed = {
- relevant_file_count: files.length,
- assigned_file_count: claims.size,
- excluded_file_count: excluded.size,
- unmapped_file_count: unmapped.size,
- };
- if (JSON.stringify(computed) !== JSON.stringify(map.coverage)) {
- fail(
- `coverage mismatch\nexpected ${JSON.stringify(computed)}\nfound ${JSON.stringify(map.coverage)}`,
- );
- }
- if (
- computed.assigned_file_count +
- computed.excluded_file_count +
- computed.unmapped_file_count !==
- computed.relevant_file_count
- ) {
- fail("coverage counts do not add up");
- }
- return computed;
-}
-
-function inline(values) {
- return values.map((value) => `\`${value}\``).join(", ");
-}
-
-function render(map) {
- const lines = [
- "# Chisel Codebase Map",
- "",
- `Cartography v${map.cartography_version} · revision \`${map.repository.revision}\` · ${map.created_at}`,
- `Assigned ${map.coverage.assigned_file_count} files · excluded ${map.coverage.excluded_file_count} · unmapped ${map.coverage.unmapped_file_count} · instructions: ${map.instructions.join(", ")}`,
- "",
- map.overview,
- "",
- "## Components",
- ];
-
- for (const component of map.components) {
- lines.push(
- "",
- `### \`${component.id}\` — ${component.name}`,
- "",
- `- **Purpose:** ${component.purpose}`,
- `- **Paths:** ${inline(component.globs)}`,
- );
- if (component.exclude_globs.length > 0) {
- lines.push(`- **Excludes:** ${inline(component.exclude_globs)}`);
- }
- if (component.entry_points.length > 0) {
- lines.push(`- **Entry points:** ${inline(component.entry_points)}`);
- }
- if (component.owns.length > 0) {
- lines.push(`- **Owns:** ${component.owns.join("; ")}`);
- }
- if (component.depends_on.length > 0) {
- lines.push(`- **Depends on:** ${inline(component.depends_on)}`);
- }
- if (component.evidence.length > 0) {
- lines.push(`- **Evidence:** ${component.evidence.join("; ")}`);
- }
- }
-
- if (map.global_exclusions.length > 0 || map.unmapped_files.length > 0) {
- lines.push("", "## Exclusions and Unmapped Code", "");
- for (const exclusion of map.global_exclusions) {
- lines.push(`- ${inline(exclusion.globs)} — ${exclusion.reason}`);
- }
- for (const path of map.unmapped_files) {
- lines.push(`- \`${path}\` — unmapped`);
- }
- }
-
- if (map.open_questions.length > 0) {
- lines.push("", "## Open Questions", "");
- for (const question of map.open_questions) {
- lines.push(`- ${question}`);
- }
- }
- lines.push("");
- return lines.join("\n");
-}
-
-const [inputPath, outputPath] = process.argv.slice(2);
-if (!inputPath) fail("usage: validate-render.mjs [map.md]");
-const map = JSON.parse(readFileSync(inputPath, "utf8"));
-const coverage = validate(map);
-if (outputPath) writeFileSync(outputPath, render(map));
-process.stdout.write(`${JSON.stringify(coverage)}\n`);
diff --git a/.chisel/cartography/work/web.md b/.chisel/cartography/work/web.md
deleted file mode 100644
index 0441611e4..000000000
--- a/.chisel/cartography/work/web.md
+++ /dev/null
@@ -1,305 +0,0 @@
-# JavaScript/TypeScript cartography proposal
-
-Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
-
-Owned scout scope: every tracked file under `apps/**` and
-`lib/packages/**` at the assessed revision. `package.json`, `bun.lock`, and
-`docs/public/api-reference/fabro-api.yaml` were consulted only as dependency
-evidence and are not included in the scope counts. Applicable repository
-instructions are `AGENTS.md` (the `CLAUDE.md` project instructions) and
-`CONTRIBUTING.md`.
-
-## Boundary decisions
-
-- `apps/fabro-web` contains three coherent assessable responsibilities, not
- just one directory-shaped component:
- - the normal-mode React application, shared browser runtime, and bundle
- production;
- - the alternate first-run installation mode, with its own route graph,
- reducer/form lifecycle, session token, API facade, and focused tests;
- - the workflow playground subtree, which explicitly defines a standalone
- prop boundary and owns a browser-persisted workflow draft, graph
- simulation, chat adapter, and generated project files.
-- The marketing site and Remotion project are separate applications. Each has
- its own package manifest, framework entry point, build command, assets, and
- output/deployment lifecycle.
-- The hand-written Fabro API client generation package is an assessable
- component, but its checked-in `src/**` tree is generator output and should
- be excluded from assessment. The distinction and counts are documented
- below.
-
-## Proposed components
-
-### `fabro-web-app` — Fabro browser application
-
-- **Purpose:** Build and run the normal-mode React SPA for run operations,
- chats, automations, insights, settings, profiles, and their shared browser
- infrastructure.
-- **Tracked files:** 309.
-- **Globs:** `apps/fabro-web/**`
-- **Exclude globs (assigned to sibling components):**
- `apps/fabro-web/app/components/playground/**`,
- `apps/fabro-web/app/install-*`,
- `apps/fabro-web/app/mode.ts`,
- `apps/fabro-web/app/mode.test.ts`,
- `apps/fabro-web/app/hooks/use-install-effects.ts`
-- **Entry points:** `apps/fabro-web/scripts/build.ts:main`,
- `apps/fabro-web/app/entry.tsx`,
- `apps/fabro-web/app/router.tsx:routes`,
- `apps/fabro-web/index.template.html`
-- **Owns:** Browser bundle assembly and content-hashed publication under
- `dist/`; the normal-mode route graph; run, chat, automation, insight,
- settings, and profile UX; shared API/query/mutation/event-stream adapters;
- app-wide layouts, components, hooks, browser view preferences, and public
- UI assets.
-- **Depends-on candidates:** `fabro-web-install` (alternate route graph
- composed by the browser entry), `fabro-workflow-playground` (route-level
- feature composition), `fabro-api-client-generation` (through its generated
- package output), and the parent map's server HTTP/API-contract component
- (likely `fabro-server` and/or `fabro-api`).
-- **Evidence:**
- - `apps/fabro-web/package.json` — declares a private React application,
- custom build/dev commands, browser dependencies, tests, and a workspace
- dependency on `@qltysh/fabro-api-client`.
- - `apps/fabro-web/scripts/build.ts:main` — bundles
- `app/entry.tsx`, compiles Tailwind CSS, copies public/worker assets, writes
- the HTML shell, publishes a content-addressed build, and provides the
- watch lifecycle.
- - `apps/fabro-web/app/entry.tsx` — creates the React root, browser router,
- SWR runtime, build-version guard, and toaster, then selects the normal or
- install route graph.
- - `apps/fabro-web/app/router.tsx:routes` — explicitly composes the
- normal-mode route tree for chats, playground, automations, runs, insights,
- settings, and profile pages beneath the app shell.
- - `apps/fabro-web/app/lib/api-client.ts` and
- `apps/fabro-web/app/lib/queries.ts` — form the browser-side API and query
- integration boundary used across normal-mode routes.
-
-### `fabro-web-install` — First-run browser installer
-
-- **Purpose:** Drive the browser-only first-run installation workflow that
- configures server URL, object storage, sandbox, LLM providers, and GitHub
- before finishing installation.
-- **Tracked files:** 14.
-- **Globs:** `apps/fabro-web/app/install-*`,
- `apps/fabro-web/app/mode.ts`,
- `apps/fabro-web/app/mode.test.ts`,
- `apps/fabro-web/app/hooks/use-install-effects.ts`
-- **Exclude globs:** none.
-- **Entry points:** `apps/fabro-web/app/install-router.tsx:installRoutes`,
- `apps/fabro-web/app/install-app.tsx:InstallApp`,
- `apps/fabro-web/app/mode.ts:resolveFabroMode`
-- **Owns:** The `install` browser mode; installation step navigation and form
- reducer state; install-session query lifecycle; the
- `fabro-install-token` session-storage value; URL token/GitHub callback
- consumption; install-specific validation, persistence, finish, and restart
- health-poll behavior.
-- **Depends-on candidates:** `fabro-web-app` for the shared root, common UI,
- hooks, and browser API transport; `fabro-api-client-generation` through
- generated Install DTOs/API methods; and the parent map's server
- installation/API-contract component.
-- **Evidence:**
- - `apps/fabro-web/app/entry.tsx` — selects `installRoutes` instead of the
- normal `routes` when `window.__FABRO_MODE__` resolves to `install`.
- - `apps/fabro-web/app/install-router.tsx:installRoutes` — defines a separate
- catch-all route graph centered on `InstallApp`.
- - `apps/fabro-web/app/install-app.tsx` — owns the seven-step install flow
- and its installation-specific reducer/form state.
- - `apps/fabro-web/app/install-api.ts` — wraps generated Install API methods
- and owns the session-storage token contract.
- - `docs/public/api-reference/fabro-api.yaml` — dependency evidence outside
- owned scope: declares the `Install` tag as the first-run browser install
- workflow.
-
-### `fabro-workflow-playground` — Browser workflow playground
-
-- **Purpose:** Provide a self-contained workflow drafting, simulation, chat,
- visualization, file-generation, download, and run-launch surface.
-- **Tracked files:** 44.
-- **Globs:** `apps/fabro-web/app/components/playground/**`
-- **Exclude globs:** none.
-- **Entry points:**
- `apps/fabro-web/app/components/playground/playground.tsx:Playground`
-- **Owns:** The `WorkflowDraft` graph schema and reducer; the versioned
- `fabro:playground:draft:v1` local-storage document; draft validation and
- animation; workflow simulation state; canvas rendering; playground chat/SSE
- adaptation; `workflow.fabro`, TOML, and README rendering; download and
- real-run launch controls.
-- **Depends-on candidates:** `fabro-web-app` for a small set of shared chat,
- graph-theme, dynamic-import, event-hook, and test utilities; and the parent
- map's server component for `/api/v1/playground/chat` and `/api/v1/runs`.
-- **Evidence:**
- - `apps/fabro-web/app/components/playground/playground.tsx:Playground` —
- exposes `chatEndpoint`, `authMode`, and optional redirect props and states
- that the subtree is framed for re-embedding without the app shell or
- app-wide stores.
- - `apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft` —
- defines the complete workflow document and describes it as a
- self-contained, re-embeddable island.
- - `apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft`
- — owns reducer-driven browser persistence and the versioned storage key.
- - `apps/fabro-web/app/components/playground/chat/runtime.ts:createPlaygroundAdapter`
- — adapts chat turns and streamed tool calls into draft changes.
- - `apps/fabro-web/app/routes/playground.tsx:PlaygroundRoute` — integration
- evidence in the sibling app component: mounts the feature at
- `/playground` and supplies its endpoint/auth contract.
-
-### `fabro-marketing-site` — Fabro marketing site
-
-- **Purpose:** Build and deploy the public Fabro site, including product
- landing content, blog, roadmap, showcase, install resources, and social
- metadata/assets.
-- **Tracked files:** 51 assigned; two generated Vercel link files excluded
- below.
-- **Globs:** `apps/marketing/**`
-- **Exclude globs:** `apps/marketing/.vercel/**`
-- **Entry points:** `apps/marketing/astro.config.mjs`,
- `apps/marketing/src/pages/index.astro`,
- `apps/marketing/src/content.config.ts`
-- **Owns:** Astro page routing and layout; global marketing presentation;
- blog, roadmap, and showcase content collections; workflow showcase
- rendering; public install script/instructions and brand/social assets;
- public redirects and Vercel deployment configuration.
-- **Depends-on candidates:** none within this scout's assessable components.
- It has framework dependencies and renders workflow graphs via Viz.js but
- does not import another repository workspace.
-- **Evidence:**
- - `apps/marketing/package.json` — declares an independent private Astro
- application with dev/build/preview lifecycle.
- - `apps/marketing/astro.config.mjs` — integrates React/Tailwind and defines
- public redirects.
- - `apps/marketing/src/content.config.ts` — defines separately typed roadmap,
- blog, and showcase content collections whose source documents are owned
- under `src/content/**`.
- - `apps/marketing/src/pages/**` — Astro's file-based entries own the landing,
- roadmap, blog, and showcase URL surfaces.
- - `apps/marketing/vercel.json` — owns production redirect behavior for the
- deployed site.
-
-### `fabro-remotion-video` — Fabro Remotion composition
-
-- **Purpose:** Render the branded `FabroIntro` motion-graphics video.
-- **Tracked files:** 9.
-- **Globs:** `apps/remotion/**`
-- **Exclude globs:** none.
-- **Entry points:** `apps/remotion/src/index.ts`,
- `apps/remotion/src/Root.tsx:RemotionRoot`,
- `apps/remotion/src/FabroIntro.tsx:FabroIntro`
-- **Owns:** The `FabroIntro` composition registration, 1920x1080/30fps/150
- frame timeline, image-format configuration, logo animation, brand assets,
- and `out/intro.mp4` render lifecycle.
-- **Depends-on candidates:** none within this scout's assessable components.
-- **Evidence:**
- - `apps/remotion/package.json` — declares an independent Remotion project
- whose studio and render/build scripts target composition `FabroIntro`.
- - `apps/remotion/src/index.ts` — registers the Remotion root.
- - `apps/remotion/src/Root.tsx:RemotionRoot` — declares the composition ID,
- component, dimensions, frame rate, and duration.
- - `apps/remotion/src/FabroIntro.tsx:FabroIntro` — owns the composition's
- animation timeline and use of the two local public assets.
-
-### `fabro-api-client-generation` — TypeScript API client generation contract
-
-- **Purpose:** Configure, normalize, and type-check the generated
- TypeScript/Axios client for the Fabro OpenAPI contract.
-- **Tracked files:** 6 assigned; 554 generated/output files excluded below.
-- **Globs:** `lib/packages/fabro-api-client/package.json`,
- `lib/packages/fabro-api-client/openapitools.json`,
- `lib/packages/fabro-api-client/scripts/**`,
- `lib/packages/fabro-api-client/tests/**`,
- `lib/packages/fabro-api-client/tsconfig.json`
-- **Exclude globs:** `lib/packages/fabro-api-client/src/**`
-- **Entry points:**
- `lib/packages/fabro-api-client/package.json:scripts.generate`,
- `lib/packages/fabro-api-client/scripts/normalize-generated.ts`
-- **Owns:** OpenAPI Generator CLI/template options and version selection;
- output location; deterministic whitespace normalization; strict TypeScript
- compilation of output; hand-written exhaustiveness/invariant checks for
- generated discriminated unions and API shapes.
-- **Depends-on candidates:** the parent map's `fabro-api`/OpenAPI-contract
- component, whose source is
- `docs/public/api-reference/fabro-api.yaml`.
-- **Evidence:**
- - `lib/packages/fabro-api-client/package.json` — `generate` invokes pinned
- OpenAPI Generator CLI `2.20.2`, reads the repository OpenAPI YAML, selects
- `typescript-axios` with separate model/API packages and tag-based APIs,
- writes to `src`, then runs the normalizer.
- - `lib/packages/fabro-api-client/openapitools.json` — selects generator
- version `7.20.0`.
- - `lib/packages/fabro-api-client/scripts/normalize-generated.ts` — is
- explicitly hand-written normalization logic and scans exactly
- `src/**/*.ts`.
- - `lib/packages/fabro-api-client/tests/principal-exhaustive.ts` and
- `tests/reasoning-output-invariant.ts` — hand-written compile-time
- assertions over generated types.
- - `lib/packages/fabro-api-client/tsconfig.json` — type-checks both
- `src/**/*` and `tests/**/*`.
-
-## Evidence-backed exclusions
-
-### Generated TypeScript/Axios client output
-
-- **Glob:** `lib/packages/fabro-api-client/src/**`
-- **Count:** 554 tracked files: 551 TypeScript files and three generator
- bookkeeping/ignore files
- (`.openapi-generator/FILES`, `.openapi-generator/VERSION`, and
- `.openapi-generator-ignore`).
-- **Reason/evidence:**
- - The hand-written package script directs OpenAPI Generator to `-o src`.
- - 550 of the 551 TypeScript files carry the literal header
- `NOTE: This class is auto generated by OpenAPI Generator` and
- `Do not edit the class manually`.
- - The only TypeScript file without that header is
- `src/models/index.ts`; it is explicitly named in
- `src/.openapi-generator/FILES`.
- - `src/.openapi-generator/FILES` contains 545 generated path entries and
- `src/.openapi-generator/VERSION` records `7.20.0`.
- - Six additional TypeScript files are not in that `FILES` snapshot, but
- each has the same auto-generation marker:
- `models/daytona-network-layer-one-of-allow-list.ts`,
- `models/daytona-network-layer-one-of.ts`,
- `models/daytona-network-layer.ts`, `models/docker-settings.ts`,
- `models/run-projection-checkpoints-inner-inner.ts`, and
- `models/sandbox-provider.ts`.
- - Therefore the stable exclusion is the output-root glob `src/**`, not only
- the metadata's current list or only marker-bearing files.
-
-### Vercel CLI link metadata
-
-- **Glob:** `apps/marketing/.vercel/**`
-- **Count:** 2 tracked files.
-- **Reason/evidence:** `apps/marketing/.vercel/README.txt` states that the
- folder is automatically created when linking a directory to a Vercel
- project, describes `project.json` as the linked project/team IDs, and says
- the directory should not be committed/shared. These are generated local
- deployment-link records rather than marketing-site source.
-
-## Computed coverage
-
-| Category | Count |
-| --- | ---: |
-| Tracked files in owned scope | 989 |
-| Assigned to proposed components | 433 |
-| Evidence-backed excluded | 556 |
-| Unmapped | 0 |
-
-Assigned counts are `309 + 14 + 44 + 51 + 9 + 6 = 433`. Excluded counts are
-`554 + 2 = 556`. The total is `433 + 556 + 0 = 989`. No file is claimed by
-two proposed components.
-
-## Open questions
-
-1. Should the 14-file first-run installer remain a separate component in the
- final map? Its alternate route graph, lifecycle, state, and API boundary
- support the split, but it imports shared web UI/runtime code while the
- shared browser entry imports its route graph, so source dependencies are
- reciprocal at composition time.
-2. Should `apps/fabro-web/app/routes/playground.tsx` remain assigned to
- `fabro-web-app` as the app-level integration adapter (the proposal here),
- or move into `fabro-workflow-playground`? Keeping the 44-file subtree as
- the playground boundary matches its own standalone/re-embedding contract.
-3. Which final Rust component ID owns
- `docs/public/api-reference/fabro-api.yaml` and the server endpoints:
- `fabro-api`, `fabro-server`, or a separately reconciled API-contract
- component? The JavaScript dependencies above should be renamed to that
- final ID.
diff --git a/.gitignore b/.gitignore
index c348f3710..75d0db485 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,9 +11,6 @@ evals/swe-bench/repos/
evals/swe-bench/results/
evals/swe-bench/dockerfiles/
__pycache__
-.ai/plans
-.ai/comments
-.ai/tmp
.worktrees/
**/*.pending-snap
.worktrees
@@ -21,3 +18,6 @@ __pycache__
.mcp.json
docs/internal/agent
.amp/portals/*
+
+# AI-generated artifacts stay local.
+/.ai/
diff --git a/docs/brainstorms/2026-04-08-eliminate-scratch-artifact-cache-requirements.md b/docs/brainstorms/2026-04-08-eliminate-scratch-artifact-cache-requirements.md
deleted file mode 100644
index 6e9aea286..000000000
--- a/docs/brainstorms/2026-04-08-eliminate-scratch-artifact-cache-requirements.md
+++ /dev/null
@@ -1,69 +0,0 @@
----
-date: 2026-04-08
-topic: eliminate-scratch-artifact-cache
----
-
-# Eliminate Scratch Artifact Cache
-
-## Problem Frame
-
-The artifact collection pipeline uses `scratch/cache/artifacts/files/` as a staging area for CLI uploads: files are downloaded from the sandbox to local disk, hashed, then uploaded to the server's `ArtifactStore`. Now that `ArtifactStore` (backed by object store) is the durable source of truth, this persistent local cache is unnecessary overhead. It adds disk usage and complicates the scratch directory contract. It also obscures a separate bug: server-managed runs currently start `ArtifactLifecycle` with no artifact sink configured, so collected artifacts are discarded. Eliminating the cache alone does not fix that bug; server-managed runs also need a direct `ArtifactStore` write path.
-
-## Requirements
-
-**Pipeline: Replace persistent cache with transient local staging**
-
-- R1. `collect_artifacts` must download each file from the sandbox into a transient per-attempt local directory tree that preserves each artifact's relative path, compute MD5/SHA256 from those transient local files, and keep that transient tree available until the configured artifact sink has finished consuming it, including upload retries. Delete the transient tree immediately after direct store writes or HTTP uploads finish. No persistent `cache/artifacts/` directory.
-- R2. `CapturedArtifactInfo` (path, mime, hashes, bytes) must still be produced for each collected file and emitted via `ArtifactCaptured` events.
-
-**Store: Write artifacts directly to ArtifactStore**
-
-- R3. When running server-side, `ArtifactLifecycle` writes collected artifacts directly to the server's `ArtifactStore`, fixing the current gap where server-managed runs configure no artifact sink and silently discard artifacts.
-- R4. When running via CLI, the existing HTTP upload path (`HttpArtifactUploader`) continues to work. Internal uploader abstractions may change as needed, but the CLI must continue uploading artifacts to the server rather than writing directly to `ArtifactStore`.
-- R5. `ArtifactLifecycle` must be configured with exactly one artifact sink for artifact-enabled runs: either a direct `ArtifactStore`-backed sink for server-managed runs or an HTTP uploader-backed sink for CLI runs. It must also hold a `RunId` for direct `ArtifactStore::put` calls. The internal representation of that sink (enum, unified trait, or refined existing trait) is deferred to planning.
-
-**Scratch cleanup**
-
-- R6. Remove `artifact_cache_dir()`, `artifact_files_dir()`, and `artifact_stage_dir()` from `RunScratch` in `fabro-config/src/storage.rs`.
-- R7. Remove the `create_dir_all(self.artifact_files_dir())` from `RunScratch::create()`.
-- R8. Update `docs/reference/run-directory.mdx` and `docs-internal/run-directory-keys.md` to remove all `cache/artifacts/` entries (including `cache/artifacts/files/`).
-- R10. Update integration tests in `fabro-workflow/tests/it/integration.rs` and `daytona_integration.rs` that assert on `artifact_stage_dir` paths to verify artifacts via `ArtifactStore` or uploader behavior instead of local filesystem paths.
-
-**CLI output**
-
-- R9. The post-run "=== Artifacts ===" output must stop printing local scratch paths. It should list durable artifact identifiers derived from stored metadata, at minimum `node_slug`, `retry`, and `relative_path`, and reference `fabro artifact cp` for retrieval.
-- R11. Removing `artifact_stage_dir()` must not change durable per-stage/per-attempt grouping. Artifacts must still be addressable by `StageId`, and CLI/server artifact surfaces must continue exposing `node_slug`, `retry`, and `relative_path` from store-backed metadata rather than reconstructing local scratch paths.
-
-## Success Criteria
-
-- Server-managed workflow runs produce artifacts in `ArtifactStore` (previously they did not).
-- No `cache/artifacts/` directory is created or written to during any workflow run.
-- `fabro artifact list` and `fabro artifact cp` continue to work unchanged.
-- The post-run artifact summary prints logical artifact identifiers (`node_slug`, `retry`, `relative_path`) instead of local scratch paths.
-- `ArtifactCaptured` events still contain correct hashes and byte counts.
-
-## Scope Boundaries
-
-- No changes to `fabro artifact list` or `fabro artifact cp` commands.
-- No changes to the `Sandbox` trait (no streaming download API).
-- No changes to the HTTP artifact upload protocol between CLI and server.
-- `runtime/blobs/` (context value materialization) is a separate concern, unchanged.
-
-## Key Decisions
-
-- **Transient local staging, not persistent scratch cache**: The `Sandbox` trait only has `download_file_to_local`. Rather than adding a streaming API to all sandbox impls, use transient local files outside `RunScratch`, but keep them alive until the configured sink has finished consuming them.
-- **Server writes to ArtifactStore directly**: The server already owns the `ArtifactStore` instance. Server-managed runs should use that directly instead of relying on an uploader being present.
-- **CLI keeps HTTP upload path**: The CLI continues uploading artifacts to the server over HTTP. The internal uploader interface may change, but the wire protocol stays the same. Smaller blast radius than giving the CLI its own local `ArtifactStore`.
-
-## Outstanding Questions
-
-### Deferred to Planning
-
-- [Affects R5][Technical] What internal representation should `ArtifactLifecycle` use for the exactly-one artifact sink? Options: an enum with server/CLI variants, a new unified trait, or a refactor of the existing uploader trait.
-- [Affects R1][Technical] Should `collect_artifacts` return transient local handles/paths alongside `CapturedArtifactInfo`, or should store/upload happen inside the collection step while the transient files are definitely still present?
-- [Affects R1][Technical] Should transient staging use `tempfile::TempDir` (auto-cleanup on drop) or manual `std::fs::remove_dir_all`? The former is more robust against panics.
-- [Affects R9][Needs research] What does the current CLI output look like for artifacts, and what is the best replacement format? Check `lib/crates/fabro-cli/src/commands/run/output.rs`.
-
-## Next Steps
-
--> `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md b/docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md
deleted file mode 100644
index c34cb4ad0..000000000
--- a/docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md
+++ /dev/null
@@ -1,541 +0,0 @@
----
-date: 2026-04-08
-topic: settings-toml-redesign
----
-
-# Settings TOML Redesign
-
-## Problem Frame
-
-Fabro has three layered TOML config files:
-
-- `~/.fabro/settings.toml` for machine defaults
-- `fabro.toml` for project defaults
-- `workflow.toml` for workflow-local defaults
-
-All three layer into one unified settings object. In same-host setups, the CLI and server may both read `~/.fabro/settings.toml`. In split-host setups, the CLI host and server host each read their own local `settings.toml` and consume only the sections relevant to that process.
-
-The current config shape grew organically. It now has naming drift, mixed ownership boundaries, uneven merge semantics, and several top-level sections that no longer reflect a clean mental model. Fabro is still greenfield with no deployed compatibility burden, so this is the right time to make a hard cut and establish a coherent, future-proof config language.
-
-The new design must optimize for:
-
-- a small, elegant top-level structure
-- coherent ownership boundaries between run, CLI, server, project, and workflow concerns
-- paste-anywhere ergonomics across the three config files
-- explicit and predictable layering semantics
-- future provider growth without provider-specific sprawl in the core model
-
-## Requirements
-
-**Config language and layering**
-
-- R1. `settings.toml`, `fabro.toml`, and `workflow.toml` must share the same schema. Files differ by precedence only, not by allowed sections.
-- R2. Any config section may appear in any Fabro TOML file. Consumers must ignore sections they do not use.
-- R3. The top-level schema must be strictly namespaced. The only top-level config domains are `[project]`, `[workflow]`, `[run]`, `[cli]`, `[server]`, and `[features]`, plus reserved underscore-prefixed meta keys.
-- R4. The schema version key must be `_version`, not `version`.
-- R5. Underscore-prefixed keys are reserved only at the top level for config-language metadata. Nested underscore keys are not part of the language.
-- R6. The config language must not add a general unset mechanism in this pass.
-- R7. Unknown config keys against the full union schema must be hard errors. This is schema validation, not consumer-specific validation.
-- R8. Duplicate keys and duplicate hook `id` values within the same file must be hard errors.
-
-**Object model and namespace boundaries**
-
-- R9. `[workflow]` and `[run]` must be sibling top-level sections. Do not nest `[workflow.run]`.
-- R10. `[workflow]` is descriptive for now. It must support first-class fields such as `name`, `description`, optional `graph`, and `metadata`. Structured workflow inputs are deferred.
-- R11. `workflow.toml` remains the canonical workflow config filename. The default graph file remains `workflow.fabro`, with optional `[workflow].graph` override.
-- R12. `[project]` must be a first-class project object with fields such as `name`, `description`, `directory`, and `metadata`.
-- R13. `project.directory` replaces the old Fabro project root concept and means the Fabro-managed project directory inside the repo, defaulting to `fabro/`.
-- R14. Workflow discovery remains conventional: `/workflows//workflow.toml`. Do not add a separate configurable workflows directory.
-- R15. `[run]` is the shared execution domain. It may appear in all three files and layer normally.
-- R16. `[cli]` and `[server]` are owner-first process domains. Settings belong to the process that reads them, not to whether the host is “local” or “remote.” For trust-boundary reasons, CLI and server processes consume their owner-specific sections only from the local `~/.fabro/settings.toml` plus explicit process-local overrides. Same-shaped `cli.*` and `server.*` stanzas in `fabro.toml` and `workflow.toml` remain schema-valid but inert for those processes.
-- R17. `[features]` is a reserved cross-cutting namespace for Fabro capability flags only. It must have a high admission bar and must not become a junk drawer.
-- R18. Logging is process-owned. Use `[cli.logging]` and `[server.logging]`; do not keep a shared logging section.
-
-**Run model**
-
-- R19. `[run]` must keep a small direct manifest surface for cross-cutting run fields such as `goal` and `working_dir`.
-- R20. `working_dir` replaces `work_dir`.
-- R21. `metadata` replaces Fabro-owned `labels` and exists on `project`, `workflow`, and `run` as flat string-to-string maps.
-- R22. `run.inputs` replaces `vars`. `run.inputs` must accept TOML scalar values. `metadata` remains string-to-string. `run.inputs` intentionally replaces the full inherited map rather than merging by key.
-- R23. `[run.model]` is the default model selection surface for LLM-backed workflow stages. `[run.agent]` is only for agent-specific settings.
-- R24. `[run.agent]` owns agent-only knobs such as `fabro_tools` and `mcps`. `[run.sandbox]` owns the sandbox selection and execution-environment surface, including `provider`, shared sandbox knobs, `env`, and provider-specific nested tables.
-- R25. Workspace tool permissions belong to `[cli.exec.agent]`.
-- R26. `[run.git]` and `[run.scm]` must remain separate concepts. `git` is local Git behavior such as commit author; `scm` is remote host/provider behavior.
-- R27. `[run.pull_request]` remains the provider-neutral run surface for PR behavior.
-- R28. `[run.prepare]` is the run preparation surface and replaces the old `setup` naming.
-- R29. `run.prepare` must be an ordered list of steps at `[[run.prepare.steps]]`.
-- R30. `run.prepare.steps` replaces as a whole ordered list across layers.
-- R31. `[run.execution]` groups run-conduct knobs such as `mode`, `approval`, and `retros`. In the first pass, `mode` is `normal | dry_run`, `approval` is `prompt | auto`, and `retros` is a positive-form boolean. Do not keep negated or ambiguous booleans like `no_retro`.
-- R32. `[run.checkpoint]` remains its own run domain. `[[run.hooks]]` is the ordered run-hook surface for run lifecycle automation.
-- R33. `[run.artifacts]` defines what run artifacts are collected. Server-side artifact storage is separate.
-- R34. `[run.notifications.]` is a keyed set of named notification routes. Notification routes merge by field across layers and support `enabled = false`.
-- R35. `[run.interviews]` is a single optional external/default interview delivery surface. HTTP/API answering is always available and is not modeled as an interview provider.
-- R36. Notification and interview event selection must use raw Fabro event names, not a second notification-specific vocabulary.
-
-**CLI model**
-
-- R37. CLI target resolution lives under `[cli.target]`, not `[server]` or `[cli.remote]`.
-- R38. CLI target transport must be explicit with `type = "http" | "unix"` and transport-specific fields, not overloaded scheme strings.
-- R39. CLI transport TLS lives under `[cli.target.tls]`.
-- R40. CLI auth is a separate domain at `[cli.auth]`, with explicit `strategy` selection. `strategy = "none"` explicitly disables inherited auth.
-- R41. `fabro exec` defaults live under `[cli.exec]`, with `[cli.exec.model]` and `[cli.exec.agent]` split cleanly.
-- R42. Generic CLI output defaults live under `[cli.output]`, not under `exec`.
-- R43. Upgrade checks live under `[cli.updates]`.
-- R44. Idle sleep prevention lives under `[cli.exec]`.
-
-**Server model**
-
-- R45. `[server]` is a namespace container. Actual settings live in named subdomains.
-- R46. The server binds the API and web surfaces on one shared listener. Bind transport must live under `[server.listen]`, not separately under `[server.api]` and `[server.web]`.
-- R47. `[server.listen]` must use explicit transport types such as `tcp` and `unix`.
-- R48. Shared listener TLS must live under `[server.listen.tls]`.
-- R49. `[server.api]` holds only API-surface settings such as public URL, not bind/auth/TLS settings.
-- R50. `[server.web]` holds only web-surface settings such as `enabled` and public URL, not auth settings.
-- R51. Server auth is a cohesive domain at `[server.auth]`.
-- R52. `[server.auth.api]` must support multiple strategies concurrently.
-- R53. `[server.auth.web]` must support multiple providers concurrently via `[server.auth.web.providers.]`.
-- R54. Web-auth access rules remain provider-neutral on `[server.auth.web]`; provider-specific config lives under each provider subtable.
-- R55. Web-auth providers must support `enabled = true|false` to disable inherited provider config cleanly.
-- R56. Inbound provider webhooks belong under provider integrations such as `[server.integrations.github.webhooks]`, not under generic server auth or web sections.
-- R57. `[server.storage]` refers only to a managed local disk root on the host. It must expose a single managed `root`.
-- R58. `[server.artifacts]` is separate from `[server.storage]` and is backed by an object store provider.
-- R59. `[server.slatedb]` is separate from both `[server.storage]` and `[server.artifacts]`. It is backed by its own object store provider and may include database-specific tunables such as `flush_interval`.
-- R60. `[server.scheduler]` owns server-managed execution policy such as concurrency limits. It must not compete with `[run]`.
-
-**Provider and future-proofing rules**
-
-- R61. Core Fabro concepts should be provider-neutral. Provider-specific details should live in provider-specific nested tables where the domain genuinely requires them.
-- R62. Sandbox config must remain provider-specific because provider differences are too large to hide behind one flat abstraction.
-- R63. Model config must remain intentionally provider-neutral. It should not grow provider-specific subtables. `run.model.fallbacks` is a single ordered array of model references. Each entry may be a bare provider token such as `openai`, a bare model alias or model id such as `gpt-5.4`, or a qualified reference such as `gemini/gemini-flash`. Bare references are allowed only when unambiguous. Ambiguous bare references must hard-error and require qualification. A bare provider token means “choose the best matching model from that provider.”
-- R64. SCM config must be provider-neutral at the core (`[run.scm]`) with room for provider-specific nested tables such as `[run.scm.github]` only where necessary.
-- R65. Slack is the chat integration. Its server-owned setup lives under `[server.integrations.slack]`; run behavior lives under `[run.notifications.*]` and `[run.interviews]`.
-- R66. Object-store-backed domains must use a shared pattern: a small provider-neutral envelope plus provider-specific nested tables.
-- R67. For local object-store providers, default to `server.storage.root`, but allow explicit local override roots when needed.
-
-**Merge, validation, and runtime semantics**
-
-- R68. Scalars replace.
-- R69. Structured tables merge by field.
-- R70. Freeform maps replace by default.
-- R71. A small, explicit set of maps may merge by key where additive inheritance is the least surprising behavior, including `run.sandbox.env` and provider-native maps such as `run.sandbox.daytona.labels`. These maps are intentionally sticky in v1: higher-precedence layers may overwrite keys but cannot remove inherited keys.
-- R72. Arrays replace by default.
-- R73. Arrays must support splice semantics via `...` in declared splice-capable string arrays, for example `["...", "c"]` for append and `["a", "..."]` for prepend. At most one exact `"..."` marker may appear per array. In the base layer with no inherited parent, the splice marker resolves to an empty inherited segment. In splice-capable arrays, the literal string value `"..."` is reserved and may not be used as data.
-- R74. Security and policy lists must replace by default and only inherit via explicit `...`.
-- R75. Keyed named objects such as notifications, MCPs, and web-auth providers must merge by field across layers. User-defined keyed object names in namespaces that also host provider-specific subtables must not equal built-in provider identifiers, to avoid ambiguous shapes such as `[run.notifications.slack.slack]`.
-- R76. Named keyed objects that may need to be disabled must support `enabled = false`.
-- R77. `[[run.hooks]]` remains an ordered list. Hooks may define an optional `id`; `name` remains human-facing only. Hooks without `id` append. Hooks with the same `id` replace whole entries in place. Hooks without `id` from a higher-precedence layer append after the fully merged inherited hook list, preserving per-file declaration order. Hook ordering remains significant.
-- R78. Provider-specific required fields should only be validated when that provider/section is actually consumed.
-- R79. Unresolved `${env.NAME}` references should only error when the field is actually consumed.
-- R80. The config language must not require separate validation modes for CLI, server, and run config in this pass. Runtime consumption drives context-specific validation.
-
-**String interpolation and value formats**
-
-- R81. Any string field may use `${env.NAME}` interpolation, either as the whole value or as a substring inside a larger string. Multiple `${env.NAME}` tokens may appear in the same string.
-- R82. Do not support config-to-config references such as `${run.inputs.foo}` in this pass.
-- R83. All time-like values should use human-readable durations such as `"30s"`, `"1m"`, or `"1h"`, not `_ms` or `_secs` fields.
-- R84. Memory and disk settings should accept generous human-readable size syntax. Bare values such as `8`, plus `8G`, `8GB`, and `8GiB`, should all parse successfully.
-- R85. Docs and examples should use `GB` as the canonical style. Parsing should remain generous.
-- R86. CPU remains an integer core count.
-
-**Command execution shape**
-
-- R87. Shell-evaluated actions use `script = "..."`.
-- R88. Direct process launches use `command = ["..."]`.
-- R89. `script` and `command` are mutually exclusive.
-- R90. The `script` xor `command` rule must apply consistently across prepare steps, hooks, and MCP transports that launch a local process. Non-launching MCP transports such as plain HTTP do not use either field.
-
-## Precedence and Override Order
-
-The config language has one schema but two consumption models.
-
-Shared layered domains such as `[project]`, `[workflow]`, `[run]`, and `[features]` use this override order:
-
-1. Explicit process-local command args or flags
-2. Explicit process-local environment override channels, where Fabro defines them
-3. `workflow.toml`
-4. `fabro.toml`
-5. `~/.fabro/settings.toml`
-6. Built-in defaults
-
-Owner-specific process domains use a narrower trust boundary:
-
-1. Explicit process-local command args or flags
-2. Explicit process-local environment override channels, where Fabro defines them
-3. `~/.fabro/settings.toml`
-4. Built-in defaults
-
-Additional rules:
-
-- String interpolation via `${env.NAME}` is not a separate precedence layer. It is value resolution inside the winning layered config value.
-- Server start flags override only the server-consumed settings for that process invocation. They do not change persisted TOML values.
-- CLI flags override only the CLI-consumed settings for that process invocation.
-- `cli.*` and `server.*` stanzas in `fabro.toml` and `workflow.toml` remain parseable but are not part of runtime precedence for those processes.
-- If a future env override channel exists for a setting, it must sit between explicit args/flags and layered TOML.
-
-## Validation Boundary
-
-Schema validation and runtime validation are separate concerns:
-
-- All config files validate against the full union schema before consumer-specific filtering.
-- Unknown-key validation and duplicate-key validation run at schema-validation time, not at consumer-specific runtime.
-- Lazy validation applies only to provider-specific required fields, selected strategies/providers, and `${env.NAME}` resolution for fields that a consumer actually uses.
-- Unused but schema-valid `cli.*` and `server.*` stanzas in lower-trust files remain inert rather than invalid.
-
-## Disable Semantics
-
-The config language must use one explicit rule for inherited config suppression:
-
-- Absence means inherit or express no opinion.
-- `enabled = false` disables inherited keyed named objects such as notification routes, MCP entries, and web-auth providers.
-- `provider = "none"` or `strategy = "none"` disables inherited singleton selectable sections such as interviews or auth.
-- Disabled sections suppress provider-specific required-field validation for their disabled subtree.
-
-## Public URL Semantics
-
-`server.listen` is only the bind transport. It must not be treated as a public URL source.
-
-- `server.api.url` and `server.web.url` are optional public URLs.
-- They are not derived from `server.listen`.
-- They are not derived from each other.
-- If omitted, Fabro must treat the corresponding public URL as unspecified rather than synthesizing one implicitly.
-
-## Normative Merge Matrix
-
-This redesign should specify exact merge behavior for the first-pass config surface rather than relying only on structural categories.
-
-| Path | Merge behavior |
-|---|---|
-| `project` direct scalar fields such as `name`, `description`, and `directory` | replace by field |
-| `project.metadata` | replace |
-| `workflow` direct scalar fields such as `name`, `description`, and `graph` | replace by field |
-| `workflow.metadata` | replace |
-| `run` direct scalar fields such as `goal` and `working_dir` | replace by field |
-| `run.metadata` | replace |
-| `run.inputs` | replace |
-| `run.model` direct scalar fields such as `provider` and `name` | replace by field |
-| `run.model.fallbacks` | replace, with `...` splice support |
-| `run.git.author` | merge by field |
-| `run.execution` | merge by field |
-| `run.checkpoint` | merge by field |
-| `run.sandbox` direct scalar fields such as `provider` and `preserve` | merge by field |
-| `run.sandbox.` | merge by field |
-| `run.sandbox.env` | merge by key |
-| provider-native maps such as `run.sandbox.daytona.labels` | merge by key |
-| notification route `events` arrays | replace, with `...` splice support |
-| `run.pull_request` | merge by field |
-| `run.interviews` | merge by field |
-| `run.interviews.` | merge by field |
-| `run.prepare.steps` | replace whole ordered list |
-| `run.notifications.` | merge by field |
-| `run.notifications..` | merge by field |
-| `run.agent.mcps.` | merge by field |
-| `cli.target` | merge by field |
-| `cli.auth` | merge by field |
-| `cli.exec` | merge by field |
-| `cli.exec.model` | merge by field |
-| `cli.exec.agent` | merge by field |
-| `cli.output` | merge by field |
-| `cli.updates` | merge by field |
-| `server.listen` | merge by field |
-| `server.api` | merge by field |
-| `server.web` | merge by field |
-| `server.auth.api` | merge by field |
-| `server.auth.api.` | merge by field |
-| `server.auth.web.providers.` | merge by field |
-| `server.storage` | merge by field |
-| `server.artifacts` | merge by field |
-| `server.artifacts.` | merge by field |
-| `server.slatedb` | merge by field |
-| `server.slatedb.` | merge by field |
-| `server.scheduler` | merge by field |
-| `[[run.hooks]]` | ordered list with special optional-`id` replacement rule |
-
-New config paths added later should declare one of these behaviors explicitly in docs and implementation. Do not let merge behavior be accidental from Rust type shape alone.
-
-## Canonical Rendering
-
-Fabro should parse generously but render consistently in docs and config-inspection output.
-
-- Durations should render in human-readable form such as `30s`, `1m`, or `1h`.
-- Memory and disk should render using `GB` in user-facing examples and normalized output.
-- `fabro settings` or equivalent config-inspection output should emit canonicalized values rather than the user's original alternate spelling when values have been normalized internally.
-- `fabro settings` or equivalent config-inspection output must redact values that were sourced from `${env.NAME}` by default, rather than printing the resolved secret-bearing value verbatim.
-
-## Object Store Credential Semantics
-
-First-pass object store configuration must work without a Fabro-specific secret reference language.
-
-- Object store providers may rely on provider-native ambient auth such as IAM roles, workload identity, local credential files, or equivalent external mechanisms.
-- Provider-specific object-store config fields may also take ordinary string values populated via `${env.NAME}`.
-- This redesign does not add `${secret.NAME}` or a separate secret-backend reference syntax.
-
-## Executable Config Trust Boundary
-
-Config-executed actions are part of Fabro's trusted configuration model, not the agent permission model.
-
-- `script` and `command` in prepare steps, hooks, and launching MCP transports are executable configuration, not passive metadata.
-- These actions execute under the trust boundary of the consuming process.
-- They are not mediated by `cli.exec.agent.permissions`.
-- Users should treat `fabro.toml` and `workflow.toml` as executable project configuration, not as untrusted data blobs.
-
-## Migration and Failure Behavior
-
-This is a hard-cut redesign, but migration still needs explicit failure semantics.
-
-- Missing `_version` defaults to `1` in the first pass.
-- `_version` values higher than the parser supports must hard-fail with an upgrade hint before deeper validation continues.
-- The legacy top-level `version` key must hard-fail with a targeted rename hint to `_version`.
-- Historical keys and obsolete top-level shapes should hard-fail rather than silently aliasing forward.
-- Error messages should point to the new replacement path whenever the replacement is known.
-- Historical file names that are no longer read should fail or warn deterministically with a rename hint.
-- There should be no silent compatibility layer that keeps old and new shapes both alive indefinitely.
-- Migration guidance must explicitly call out that the new default `project.directory = "fabro/"` changes workflow discovery relative to the old implicit project-root behavior.
-- Historical string command forms such as `command = "cargo fmt"` must migrate to either `script = "cargo fmt"` or `command = ["cargo", "fmt"]`.
-- Historical hook `name` remains display-only in the new language. Cross-layer hook replacement uses the optional `id` field, so users must add `id` explicitly where merge identity is intended.
-
-Known first-pass migration mappings:
-
-| Old shape | New shape |
-|---|---|
-| `version = 1` | `_version = 1` |
-| top-level `goal` | `[run].goal` |
-| top-level `work_dir` or `directory` | `[run].working_dir` |
-| top-level `labels` | `[run.metadata]` |
-| `[vars]` | `[run.inputs]` |
-| `[llm]` | `[run.model]` |
-| `[setup]` | `[run.prepare]` |
-| `[sandbox]` | `[run.sandbox]` |
-| `[checkpoint]` | `[run.checkpoint]` |
-| `[pull_request]` | `[run.pull_request]` |
-| `[artifacts]` | `[run.artifacts]` |
-| `[exec]` | `[cli.exec]` |
-| `[mcp_servers]` | `[run.agent.mcps]` or `[cli.exec.agent.mcps]`, depending on the consumer |
-| `[api]` | `[server.api]` |
-| `[web]` | `[server.web]` |
-| `[artifact_storage]` | `[server.artifacts]` |
-| Git commit author settings | `[run.git.author]` |
-| GitHub App and webhook settings | `[server.integrations.github]` |
-
-## Success Criteria
-
-- The new config language has a small, defensible top-level schema with clear object ownership boundaries.
-- Users can paste a stanza between `settings.toml`, `fabro.toml`, and `workflow.toml` and still parse successfully.
-- Same-host and split-host deployments both fit the model without separate schema branches.
-- Merge behavior is predictable enough that users can explain it from the docs without reading implementation code.
-- Provider growth in SCM, chat integrations, and object stores does not force repeated top-level redesigns.
-- Users can disable inherited singleton and keyed-object behavior without a general unset language.
-- Users can predict flag/env/TOML precedence without reading implementation code.
-- When users supply old config keys, Fabro fails with targeted upgrade guidance rather than silently ignoring or partially accepting them.
-
-## Scope Boundaries
-
-- No backwards-compatibility requirements. This is a hard-cut redesign.
-- No secret-reference syntax such as `${secret.NAME}` in this pass.
-- No secret backend configuration in this pass.
-- No structured workflow input schema in this pass.
-- No prompt-specific run config section in this pass.
-- No separate validation modes such as “validate as server config” in this pass.
-- No automatic migration tool in this pass.
-
-## Key Decisions
-
-- **Strict top-level namespaces**: Keep the root schema extremely small and reserve underscore-prefixed top-level keys for config-language metadata.
-- **Same schema everywhere**: File type controls precedence, not which sections are legal.
-- **Owner-first process config**: CLI and server settings belong to the process that reads them, even in same-host setups.
-- **Provider-neutral core with provider-specific leaves**: Use this for SCM, notifications, interviews, sandboxes, and object stores where it improves long-term coherence.
-- **No general unset**: Prefer explicit disable mechanisms such as `enabled = false` and `"none"` selectors.
-- **Lazy validation for unused stanzas**: This preserves the “paste any stanza anywhere” rule without weakening strict unknown-key validation.
-- **Shared server listener**: Bind transport and transport TLS are shared at `[server.listen]`; API and web remain separate surfaces above that.
-- **Separate storage, artifacts, and SlateDB**: These are materially different server concerns and should not be collapsed into one storage section.
-- **Ordered lists are rare**: Keep them where order is semantically important, especially hooks and prepare steps. Prefer keyed named objects elsewhere.
-- **Hard-fail migration**: The system should aggressively reject obsolete keys and point users at replacements instead of carrying a compatibility burden into the new language.
-
-## Canonical Shape
-
-```toml
-_version = 1
-
-[project]
-[workflow]
-[run]
-[cli]
-[server]
-[features]
-```
-
-Representative subtree:
-
-```toml
-_version = 1
-
-[project]
-name = "Fabro"
-description = "AI workflow orchestration"
-directory = "fabro/"
-
-[workflow]
-name = "Implement Feature"
-description = "Turns a request into a code change"
-
-[run]
-goal = "Implement OAuth refresh tokens"
-working_dir = "/workspace"
-
-[run.model]
-provider = "anthropic"
-name = "sonnet"
-fallbacks = ["openai", "gpt-5.4", "gemini/gemini-flash"]
-
-[run.notifications.ops]
-enabled = true
-provider = "slack"
-events = ["run.failed"]
-
-[run.notifications.ops.slack]
-channel = "#ops"
-
-[run.interviews]
-provider = "slack"
-
-[run.interviews.slack]
-channel = "#approvals"
-
-[cli.target]
-type = "http"
-url = "https://fabro.example.com/api/v1"
-
-[cli.auth]
-strategy = "mtls"
-
-[cli.exec.model]
-provider = "anthropic"
-name = "claude-opus"
-
-[cli.exec.agent]
-permissions = "read-write"
-
-[server.listen]
-type = "tcp"
-address = "127.0.0.1:32276"
-
-[server.api]
-url = "https://fabro.example.com/api/v1"
-
-[server.web]
-enabled = true
-url = "https://fabro.example.com"
-
-[server.storage]
-root = "/var/lib/fabro"
-
-[server.artifacts]
-provider = "s3"
-prefix = "artifacts"
-
-[server.slatedb]
-provider = "s3"
-prefix = "runs"
-flush_interval = "1s"
-```
-
-## Canonical File Examples
-
-Minimal `~/.fabro/settings.toml`:
-
-```toml
-_version = 1
-
-[cli.target]
-type = "unix"
-path = "~/.fabro/fabro.sock"
-
-[cli.exec]
-prevent_idle_sleep = true
-
-[cli.exec.model]
-provider = "anthropic"
-name = "claude-opus"
-
-[cli.exec.agent]
-permissions = "read-write"
-
-[cli.output]
-format = "text"
-verbosity = "normal"
-
-[cli.updates]
-check = true
-
-[server.listen]
-type = "unix"
-path = "~/.fabro/fabro.sock"
-
-[server.storage]
-root = "~/.fabro/storage"
-
-[run.interviews]
-provider = "slack"
-
-[run.interviews.slack]
-channel = "#approvals"
-```
-
-Minimal `fabro.toml`:
-
-```toml
-_version = 1
-
-[project]
-name = "Fabro"
-description = "AI workflow orchestration"
-directory = "fabro/"
-
-[run.model]
-provider = "anthropic"
-name = "sonnet"
-
-[run.sandbox]
-provider = "daytona"
-
-[[run.prepare.steps]]
-script = "bun install"
-```
-
-Minimal `workflow.toml`:
-
-```toml
-_version = 1
-
-[workflow]
-name = "Implement Feature"
-description = "Turns a request into a code change"
-
-[run]
-goal = "Implement OAuth refresh tokens"
-
-[run.inputs]
-repo = "fabro"
-
-[run.notifications.ops]
-enabled = true
-provider = "slack"
-events = ["run.failed", "run.completed"]
-
-[run.notifications.ops.slack]
-channel = "#ops"
-```
-
-## Outstanding Questions
-
-### Deferred to Planning
-
-- [Affects R64][Technical] What exact run-side SCM targeting fields should live under `[run.scm]` in the first pass: repo slug, owner/repo split, base branch defaults, or additional checkout/ref context?
-- [Affects R66][Technical] What exact shared field set should the object-store envelope expose before provider-specific subtables begin?
-- [Affects R90][Technical] What exact field set should the MCP launcher schema expose in addition to `script` xor `command`, `type`, and timeouts?
-- [Affects R34][Technical] What minimal first-pass notification route surface is required beyond `enabled`, `provider`, and `events`?
-- [Affects R83][Technical] What duration parser will Fabro standardize on, and what canonical normalization should be shown in error messages and generated examples?
-
-## Next Steps
-
-- Update the user-facing config docs to match this new object model.
-- `/ce:plan` for a migration and implementation plan covering parser changes, merge semantics, docs, and test updates.
diff --git a/docs/brainstorms/2026-04-15-ip-whitelist-requirements.md b/docs/brainstorms/2026-04-15-ip-whitelist-requirements.md
deleted file mode 100644
index 4bae1704c..000000000
--- a/docs/brainstorms/2026-04-15-ip-whitelist-requirements.md
+++ /dev/null
@@ -1,75 +0,0 @@
----
-date: 2026-04-15
-topic: ip-whitelist
----
-
-# IP Address Whitelisting
-
-## Problem Frame
-
-Some fabro users deploy without network-level controls (VPN, firewall). These users need fabro itself to restrict access by client IP address so that only trusted networks can reach the web UI and API.
-
-## Requirements
-
-**Access Control**
-- R1. When an IP whitelist is configured, requests from non-whitelisted IPs receive 403 Forbidden before authentication is evaluated. This applies to all requests: API, web UI, and static assets
-- R2. When no IP whitelist is configured, all IPs are allowed (current behavior, no breaking change)
-- R3. Health check endpoints (e.g., `/health`) are exempt from IP filtering so load balancers and monitoring continue to work
-- R10. Log rejected requests (client IP, request path, timestamp) at warn level for security auditing and debugging
-
-**IP Matching**
-- R4. Support individual IPv4 and IPv6 addresses (e.g., `1.2.3.4`, `::1`)
-- R5. Support CIDR notation for ranges (e.g., `10.0.0.0/8`, `fd00::/8`)
-
-**Reverse Proxy Support**
-- R6. When deployed behind a reverse proxy, detect client IP from `X-Forwarded-For` or `X-Real-IP` headers
-- R7. Proxy header trust must be explicitly configured (trusted proxy count or trusted proxy list) to prevent spoofing; without configuration, use the TCP remote address
-- R11. When the server listens on a Unix socket and an IP whitelist is configured, proxy header trust must also be configured or the server refuses to start
-
-**Configuration**
-- R8. IP whitelist is configured via server settings (settings.toml / environment variables), not via the web UI
-- R9. Changes require a server restart (IP whitelist does not participate in the existing settings hot-reload cycle)
-- R12. Server must refuse to start if the IP whitelist contains invalid entries (malformed CIDR, unparseable addresses). Fail-closed prevents a false sense of security
-
-## Success Criteria
-
-- A fabro instance with an IP whitelist configured rejects requests from non-whitelisted IPs with 403
-- Health checks remain accessible from any IP
-- The feature has zero impact when unconfigured (default: allow all)
-- IP detection works correctly behind common reverse proxies (nginx, AWS ALB) when trust is configured
-- Invalid whitelist configuration prevents server startup with a clear error message
-- Rejected requests appear in server logs with enough detail to diagnose misconfiguration
-
-## Scope Boundaries
-
-- No web UI for managing the whitelist
-- No per-user or per-role IP rules
-- No rate limiting (separate concern)
-- No IP blocklist (deny-list) -- only allowlist
-- No hot-reload of IP rules without restart
-- No geo-IP or DNS-based filtering
-- No implicit localhost/loopback exemption -- admins must explicitly whitelist 127.0.0.1/::1 if needed
-- GitHub webhook listener (separate TcpListener) is out of scope -- it uses HMAC signature verification for its own access control
-
-## Key Decisions
-
-- **Config-only, no UI management**: Keeps the attack surface small -- an attacker who bypasses IP filtering can't weaken it through the UI
-- **Block before auth**: Reduces exposure -- non-whitelisted IPs can't even probe auth endpoints
-- **Health check exemption**: Practical necessity for load-balanced deployments
-- **Explicit proxy trust**: Prevents IP spoofing via forged headers in direct-connection deployments
-- **Fail-closed on invalid config**: Server refuses to start rather than silently degrading to allow-all
-- **No implicit loopback exemption**: Keeps behavior strict and predictable; admin error is recoverable via config file edit
-- **Unix socket requires proxy trust**: Since Unix sockets have no TCP remote address, proxy headers are the only way to determine client IP
-
-## Outstanding Questions
-
-### Deferred to Planning
-- [Affects R6, R7][Needs research] What reverse proxy IP detection does Axum's ecosystem already provide (e.g., `axum-client-ip`, `ConnectInfo`) and what needs custom implementation? Note: the server currently does not use `into_make_service_with_connect_info`, and the TLS path does not propagate `remote_addr`
-- [Affects R8][Technical] What is the best configuration shape in settings.toml? Note: `ServerLayer` uses `#[serde(deny_unknown_fields)]`, which constrains field additions
-- [Affects R3][Technical] Which health check endpoints should be exempted? Currently `/health` and `/health/diagnostics` exist; the latter probes server internals and may not be safe to exempt
-- [Affects R4, R5][Technical] How should IPv4-mapped IPv6 addresses (e.g., `::ffff:10.0.0.1`) be handled -- should they match plain IPv4 whitelist entries?
-- [Affects R6][Technical] For X-Forwarded-For with multiple IPs, which position in the chain should be treated as the client IP? (rightmost-minus-N is the secure approach)
-
-## Next Steps
-
--> `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-16-fabro-upgrade-prerelease-requirements.md b/docs/brainstorms/2026-04-16-fabro-upgrade-prerelease-requirements.md
deleted file mode 100644
index 46267be6d..000000000
--- a/docs/brainstorms/2026-04-16-fabro-upgrade-prerelease-requirements.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# `fabro upgrade --prerelease` — requirements
-
-## Problem
-
-`fabro upgrade` hits GitHub's `/releases/latest`, which excludes prereleases. Users on a prerelease (e.g. `0.204.0-beta.0`) or wanting to opt into betas must supply an exact `--version v0.X.Y-alpha.N`. There is no channel opt-in.
-
-## Goal
-
-Add `--prerelease` to `fabro upgrade` so a single invocation picks the highest semver across stable **and** prereleases.
-
-## Behavior
-
-- New bool flag `--prerelease` on `fabro upgrade`. Conflicts with `--version` (explicit version already selects any tag).
-- Scope: only the explicit `fabro upgrade` command. Background auto-check (`spawn_upgrade_check` / `check_and_print_notice`) stays stable-only.
-- Selection when `--prerelease` is set:
- 1. Fetch `GET /repos/fabro-sh/fabro/releases` (first page, 30 items — `gh` and HTTP backends).
- 2. Drop entries with `draft: true` or an unparseable `tag_name`.
- 3. Pick the max by semver over the remaining set (stable + prereleases together). This means a newer stable beats an older beta; `--prerelease` *widens* the candidate set, it does not prefer prereleases.
- 4. If the filtered set is empty, fall back to the existing stable-latest path (`/releases/latest`).
-- Downgrade protection unchanged:
- - Target < current, no explicit version → bail ("latest release … is older than installed version …, skipping").
- - Target == current, no `--force` → "Already on version …".
-- `--dry-run`, `--force`, JSON output, SHA256 verify, atomic swap — all unchanged.
-
-## Code touchpoints
-
-- `lib/crates/fabro-cli/src/args.rs` — add `prerelease: bool` with `#[arg(long, conflicts_with = "version")]`.
-- `lib/crates/fabro-cli/src/commands/upgrade.rs`:
- - New local `ReleaseSummary { tag_name: String, draft: bool, prerelease: bool }` (serde).
- - New `Backend::fetch_releases(&self) -> Result>` that hits `/releases` via HTTP or `gh api repos/{repo}/releases`.
- - New pure `fn pick_latest_tag(releases: &[ReleaseSummary]) -> Option` — filters drafts + unparseable tags, returns max-semver `tag_name`.
- - `run_upgrade`: when `args.prerelease`, call `fetch_releases` → `pick_latest_tag`; on `None`, fall back to `fetch_latest_release_tag`.
- - `spawn_upgrade_check` / `check_and_print_notice` untouched.
-
-## Tests (unit, no network)
-
-- `pick_latest_tag`:
- - mixed stable + prerelease, newest is prerelease → picks prerelease.
- - mixed stable + prerelease, newest is stable → picks stable.
- - all drafts → `None` (triggers fallback).
- - malformed tag (`"weekly-build-3"`) alongside valid tags → skipped, valid winner returned.
- - empty input → `None`.
-- Clap: `fabro upgrade --prerelease --version 0.1.0` exits with `conflicts_with` error. (Existing `UpgradeArgs` tests style.)
-
-## Out of scope
-
-- Persistent channel config, env var (`FABRO_UPGRADE_CHANNEL`), `--stable` opt-out.
-- Changing background upgrade notice to include prereleases.
-- Docs/changelog updates beyond the `--help` string (can follow in the same PR as trivial diffs).
-
-## Open questions
-
-None.
diff --git a/docs/brainstorms/2026-04-19-run-archived-status-requirements.md b/docs/brainstorms/2026-04-19-run-archived-status-requirements.md
deleted file mode 100644
index ee0d393db..000000000
--- a/docs/brainstorms/2026-04-19-run-archived-status-requirements.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-date: 2026-04-19
-topic: run-archived-status
----
-
-# Add a Terminal `archived` Status to Workflow Runs
-
-## Problem Frame
-
-Workflow runs accumulate over time. Today the three terminal statuses (`succeeded`, `failed`, `dead`) all share the same shelf: they stay visible in `fabro ps`/`fabro runs list` with `-a`, clutter API listings, and carry no signal about whether the user has actually finished with the run. Users want a way to mark a run "I've reviewed this, no further action needed" that (a) captures that intent explicitly, (b) drops the run out of default listings, and (c) leaves all data readable for reference. The mark is also the natural signal an eventual retention/delete policy would key off, though deletion itself is out of scope here.
-
-## Behavior by Status
-
-| Operation | Active (submitted/starting/running/paused) | Terminal (succeeded/failed/dead) | Archived |
-|---|---|---|---|
-| Read detail, logs, artifacts, attach-replay | ✓ | ✓ | ✓ |
-| Resume / rewind / retro re-run | ✓ where valid | ✓ where valid | ✗ (unarchive first) |
-| Archive | ✗ (finish first) | ✓ | — |
-| Unarchive | — | — | ✓ (restores prior terminal status) |
-| Shown in default `fabro ps` / `runs list` | ✓ | ✗ | ✗ (hidden; opt-in flag) |
-
-## Requirements
-
-**Status model**
-- R1. Add `archived` as a new terminal variant of `RunStatus`, surfaced as the run's `status` field in CLI, API, and UI consumers.
-- R2. Archiving is permitted only from existing terminal statuses: `succeeded`, `failed`, `dead`. Archiving an active run is rejected.
-- R3. Archiving is reversible. `unarchive` restores the exact terminal status the run held immediately before it was archived.
-- R4. The prior terminal status must be retained durably — either captured in the unarchive event payload or persisted on the run record — so unarchive is deterministic across restarts, reloads, and event replay.
-- R5. All three source terminal statuses archive identically — no per-source gating, reasons, or side effects differ between `succeeded`/`failed`/`dead`.
-
-**Operations**
-- R6. `fabro archive [...]` archives one or more runs in a single invocation. Per-id failures are surfaced individually; the batch does not abort on the first error.
-- R7. `fabro unarchive [...]` reverses the archive for one or more runs in a single invocation, with the same per-id failure semantics as R6.
-- R8. HTTP API exposes archive and unarchive operations and supports the same multi-id bulk behavior the CLI uses.
-- R9. Archive and unarchive appear on the run-timeline event stream with the actor that performed the action, so the transition is captured for audit alongside existing status events. Whether this is implemented as new `RunArchived`/`RunUnarchived` event variants or by extending the existing status-transition event family is deferred to planning.
-
-**Visibility**
-- R10. `fabro ps` and `fabro runs list` hide archived runs by default. An explicit flag opts them in; the exact flag shape (extend `-a/--all` vs. add `--archived`) is a planning decision.
-- R11. The JSON listing API exposes an equivalent archived-visibility control so API consumers opt in to archived runs explicitly and don't get surprised by a new default set.
-- R12. In v1, direct run-detail reads by run ID continue to succeed regardless of archived state — archive is a listing-filter concern, not an access-control one. Future retention/deletion layers may reintroduce access-control semantics on top of archive; v1 does not foreclose that.
-
-**Safety of archived runs**
-- R13. Archived runs are read-only (see R14 for the mutation-rejection contract). Read surfaces — viewing detail, logs, artifacts, attach-replay, checkpoint inspection — all continue to work as they did in the prior terminal status.
-- R14. Any operation that would mutate a run — lifecycle (resume, rewind, retro re-run, run-control actions, further status transitions) *and* metadata (label edits, tag changes, any future annotation/comment surface) — must reject with a clear error that tells the user to `fabro unarchive` first. Archived is a fully frozen state from a user perspective; R13's "read-only" is defined by this rejection list. The one preserved escape hatch is the system's existing "always-allow `Dead`" path in `can_transition_to` — supervisor/orphan handling may still mark an archived run `Dead` (with the archive then effectively discarded). The exhaustive endpoint-level audit is a planning task (see Deferred Questions).
-- R15. Archiving does not change storage, retention, or cleanup behavior. Checkpoints, artifacts, logs, and blob references remain as they were in the prior terminal status.
-- R16. When a consumer explicitly asks for archived runs — either by the archived-visibility opt-in flag, or (if/when a status filter is introduced) by `status=archived` — the explicit ask is sufficient; consumers should not need to *also* set a second gate. Note: today neither the CLI (`RunsListArgs`) nor the `listRuns` API exposes a generic `status=` filter; introducing one is not a v1 requirement, but if it arrives later it should interact with the archived opt-in per this rule.
-
-## Success Criteria
-
-- A user runs `fabro archive `. Listings that would previously surface the run's terminal status (e.g. `fabro ps -a`, `fabro runs list -a`, or the JSON list API) no longer include it. A listing with the archived-opt-in flag surfaces it with `status = archived`.
-- `fabro unarchive ` returns the run to its original terminal status; listings and behavior match the pre-archive state exactly.
-- Attempting any mutating operation on an archived run produces an actionable error referencing `unarchive`.
-- Archive/unarchive actions appear in the run's event timeline with actor information.
-- Bulk form (`fabro archive A B C`) archives each independently and surfaces per-run success/failure without aborting the whole batch.
-
-## Scope Boundaries
-
-- Web UI archive/unarchive controls — deferred; CLI + API only in v1. The web UI is itself an API consumer, so it will pick up the new default-hide listing behavior passively; no UI code change is required in v1 to keep that surface consistent.
-- Automatic archive policies (age, count, per-workflow retention) — deferred.
-- Storage reduction tied to archive (checkpoint pruning, log compaction, artifact eviction) — explicitly out of scope.
-- Deletion of archived runs — out of scope; archived is a signal that deletion *could* later key off, not a step toward it in this feature. Making archived runs efficiently queryable as a set (needed for a future retention job) is not a v1 requirement beyond what R16 already provides.
-- Permission/authorization model for who can archive whose runs — assumed to match existing mutation authorization; no new authz surface introduced here. Planning should confirm this during the mutation-endpoint audit (see Deferred Questions).
-- Archiving active (non-terminal) runs — not supported; users cancel/complete first.
-- Forward-compat of stored `prior_status` values across a future `RunStatus` enum evolution — out of scope; if the enum later changes shape, archived runs persisted at that time will be handled by whatever migration that change introduces.
-- Idempotency of repeated archive/unarchive invocations — planning decision (no-op vs. error). This *is* user-visible via the bulk per-id result shape in R6/R7, so planning must pick a concrete behavior before shipping; the decision is only deferred in the sense that brainstorm didn't choose between no-op and error.
-
-## Alternatives Considered
-
-- **Auto-hide terminal runs by default (no archive action)** — rejected. The whole premise is to *capture user intent*. Auto-hiding silently removes runs the user has not acknowledged, producing a false "it's handled" signal and leaving users guessing which of a large terminal set they've actually reviewed. The explicit-action model trades a small amount of ceremony for a clear, user-driven triage state. It is also compatible with a future auto-archive policy layered on top (out of scope for v1), so nothing is lost.
-- **Boolean `archived` flag orthogonal to status** — rejected for v1. Keeps status semantics stable and avoids the prior-status-restoration problem entirely, but forces every consumer (CLI, API, UI, reports) to learn a second axis. The single-status-axis model is simpler at the point of use given the v1 shape; see Key Decisions for the accepted tradeoff.
-- **Predicate-based bulk archive (`--status succeeded --older-than 14d`)** — deferred. Would make mass-triage frictionless for users with many accumulated runs, but ID-based bulk (R6) is enough to validate the core premise in v1 and avoids defining a query language up front. Can be added once adoption is observed.
-
-## Key Decisions
-
-- **New first-class terminal enum value, not a boolean flag** — shown as the surface status in `ps`, API, and UI. Keeping status as the single axis avoids teaching every consumer about a parallel `archived` dimension. Accepted tradeoff: a future orthogonal lifecycle axis (e.g. `superseded`, soft-delete) would need its own modeling rather than composing with `archived`. For the stated v1 shape (reversible user-intent triage on a reached-terminal run), the single-axis model is simpler at the point of use even though it costs more if lifecycle gains a second axis later. This choice is also load-bearing and expensive to reverse: once `Archived` is serialized into the event log, checkpoint metadata, the OpenAPI spec, and the TypeScript client, converting to an orthogonal boolean later would require a data migration across every one of those surfaces.
-- **Reversible via unarchive, restoring prior terminal status** — archival is triage intent, not a destructive operation. Accidental archives must be trivially undoable without data loss.
-- **Read-only while archived; mutation requires explicit unarchive** — prevents the "I said I was done with this" run from silently mutating. Forces a conscious lift.
-- **Hidden from default listings with opt-in flag** — the whole point of the feature is reducing noise in default views. Direct-by-ID access stays unrestricted.
-- **No storage impact** — keeps blast radius small. Storage/retention is a separate future feature.
-- **All three source terminal statuses archive identically** — simplest state machine; avoids carving out `dead` or `failed` as "un-archivable."
-
-## Dependencies / Assumptions
-
-- `RunStatus` and its transition guard in `lib/crates/fabro-types/src/status.rs` will be extended with `Archived`, and with transitions from each of `Succeeded`/`Failed`/`Dead` into `Archived` and back. *Verified against current code.* Note: `can_transition_to` today uses `is_terminal()` to hard-block any exit from a terminal state (except to `Dead`). Introducing archived therefore requires either narrowing `is_terminal()` into two concepts — "reached a terminal outcome" vs. "immutable / not transitionable" — or special-casing archive/unarchive transitions in the guard. Which direction to take is a planning decision; whichever is chosen, planning must audit every existing caller of `is_terminal()` (UI state, completion detection, billing roll-ups, reporting) and decide per caller whether `Archived` should be treated as "reached terminal" or "immutable / not transitionable."
-- `RunStatusRecord` carries a single status + optional reason + `updated_at`. `RunProjection` in `lib/crates/fabro-store/src/run_state.rs` holds only the most recent `RunStatusRecord` — each status-change event overwrites `self.status` and there is no queryable status-history projection. *Verified against current code.* The event log itself retains the full sequence of status-change events via a per-run monotonic `event_seq` (`AtomicU32` in `lib/crates/fabro-store/src/slate/run_store.rs`), so events for a given run are replayed in append order; prior terminal status is therefore recoverable via replay. Given the existing projection shape, the cleanest pattern for R4 is to carry the restored status on the unarchive event payload itself so replay reconstructs state without scanning backward. Final mechanism choice is still a planning decision.
-- The OpenAPI spec `docs/api-reference/fabro-api.yaml` is the source of truth for the HTTP interface; archive/unarchive endpoints and the new status value are added there first, and both the Rust progenitor client and the TS Axios client regenerate per the existing workflow. The existing `listRuns` operation must also gain a query parameter (e.g. `include_archived`) — today it only accepts pagination params — so API consumers have an explicit way to opt in; this is an edit to an existing endpoint, not purely additive.
-- Run events are extensible; existing variants like `RunRemoving` in `lib/crates/fabro-workflow/src/event.rs` serve as shape precedents for `RunArchived`/`RunUnarchived`.
-- Run IDs are assumed to be globally unique and resolvable without additional workspace/project scoping. R6/R7's bare-positional-ID CLI shape depends on this. If namespacing is later introduced, scoping will need to be added to the archive CLI as a compat-aware change.
-- Existing mutation operations in `lib/crates/fabro-workflow/src/operations/` are the set that must be taught to reject when the run is archived.
-
-## Outstanding Questions
-
-### Resolve Before Planning
-
-- (none)
-
-### Deferred to Planning
-
-- [Affects R4][Technical] Record prior terminal status on the unarchive event payload (preferred pattern given the existing projection shape — see Dependencies), vs. add a `prior_status` field to the run record, vs. walk the event log on unarchive. Pick the mechanism and update the projection accordingly.
-- [Affects R10][User decision] Extend `-a/--all` to also include archived, vs. add a separate `--archived` flag (and whether `-a --archived` composes). This also drives the 'No running processes found' hint text. Compat note: today `-a` means "show all runs including terminal"; extending it silently narrows that meaning, while a separate `--archived` flag preserves it.
-- [Affects R8][Technical] API shape — dedicated endpoints (`POST /runs/{id}/archive`, `POST /runs/{id}/unarchive`, plus a bulk form) vs. extending the existing `RunControlAction` enum with `Archive`/`Unarchive`.
-- [Affects R9][Technical] Exact event variant names and payload shape (`RunArchived { actor }`, `RunUnarchived { actor, restored_status }`?), including whether they piggyback on the existing status-transition event family.
-- [Affects R14][Technical] The full list of endpoints and operations that must reject on archived runs; planning should audit `operations/*.rs` and the server's mutation routes, including label/tag write paths and any event-producing endpoint that bypasses `can_transition_to`.
-- [Affects R11][Technical] Whether other internal list surfaces (dashboards, summaries, PR cross-references, usage roll-ups) need the same default-hide treatment, or whether they're acceptable as-is.
-
-## Next Steps
-
-→ `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md b/docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md
deleted file mode 100644
index 66b4a9e39..000000000
--- a/docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-date: 2026-04-19
-topic: run-files-changed-tab
----
-
-# Run "Files Changed" Tab — Make It Real
-
-## Problem Frame
-
-Every workflow run modifies files in a sandboxed worktree. Today the run detail UI has a **Files** tab skeleton that imports `@pierre/diffs` and renders hardcoded `fallbackFiles` when the loader's response is empty — which is always the case in a non-demo server, because the endpoint `GET /runs/{id}/files` the tab calls does not exist. The OpenAPI spec even defines `PaginatedRunFileList` and `FileDiff`, but no operation references them.
-
-Users cannot see what a run actually changed without leaving the product. The goal of this brainstorm is to replace the demo/fallback content with a real, per-run diff rendered by `@pierre/diffs`, with sensible behavior across the run lifecycle (running → succeeded/partial → failed → sandbox destroyed).
-
-Persistence reality today (verified in code):
-- `RunProjection.final_patch: Option` is captured on `RunCompleted` via the lifecycle git hook (`lib/crates/fabro-workflow/src/lifecycle/git.rs`) and stored in SlateDB (`lib/crates/fabro-store/src/run_state.rs`).
-- It is a **unified-patch string** (output of `git diff HEAD`), not structured per-file `{old_file, new_file}` contents.
-- It is set only for `Success` / `PartialSuccess` — `RunFailed` does not populate it.
-- Successful checkpoint commits are pushed to `origin` (E2E: `daytona_integration.rs:1541`), so the branch + SHAs are typically reachable from origin after the sandbox is gone — though **branch retention is not a guarantee** (auto-delete on merge, admin cleanup, force-push, repo archival can prune refs). We treat origin as a best-effort source, not an authority.
-
-### Failure modes this plan must avoid
-- **Partial-coverage trust erosion.** The tab silently shows content in some states and nothing in others. Users form the impression "works sometimes."
-- **Stale-but-plausible content.** The UI shows a diff that's minutes old with no indication of freshness; users act on it as current.
-- **Secret exfiltration.** A working-tree file contains a token/credential and the tab happily displays it to anyone with run access.
-- **Server DoS.** An authenticated caller hits the endpoint in a loop against a massive run and pegs the box.
-
-Each requirement below names the failure mode it addresses.
-
-## Requirements
-
-**Presentation (Files tab UI)**
-- R1. The Files tab renders a real `FileDiff[]` via `@pierre/diffs`' `MultiFileDiff` for the current run.
-- R2. Keep the existing split/unified and disable-background toggles. Persist the split/unified choice in browser localStorage (scope is per-browser, not per-account; note: shared-machine users inherit the last setting). If an md-breakpoint collapse fires (R8), it overrides the rendered view without overwriting the stored preference.
-- R3. Remove (or hide behind a feature flag) the inline "Steer" comment affordance — out of scope here; it will be brainstormed separately when the backend `/runs/{id}/steer` is designed.
-- R4. **Empty-state taxonomy** (expected: no diff exists): distinct messaging for (a) the run has not produced a `base_sha` yet (Submitted/Starting), (b) the run produced a `base_sha` but touched no files, (c) the run completed but has no recoverable diff (Failed with no checkpoint, or Succeeded-but-`final_patch`-absent + origin unreachable). The toolbar stays usable in all three.
-- R5. **Error-state taxonomy** (diff should exist but we could not retrieve it): distinct UI treatment for (a) transient / retriable (network, timeout, reconnect failure) with a Retry affordance, (b) permanent / data-loss — typically caught by R4(c) instead, (c) auth/config (e.g. origin credentials invalid) with a contact-admin affordance, (d) unknown 5xx with a request ID for support. When `final_patch` is available and origin is unreachable, the response flows into R12's degraded view, not R5.
-- R6. **Loading and refresh**: initial fetch shows a diff-area skeleton (toolbar still visible). The tab exposes an explicit **Refresh** button in the toolbar. For **Running** runs the freshness indicator reads "Checkpoint Xm ago" sourced from the `to_sha` commit time (not the HTTP response time) so users can distinguish "tab fetched seconds ago" from "nothing has changed on the agent side in minutes". For completed runs it reads "Fetched Xs ago" sourced from HTTP response time. Prior content remains visible during re-fetch; a failed refresh leaves the last good data on screen with an inline error banner. The Refresh button is disabled when the last response's `to_sha` equals the currently-displayed `to_sha`. No auto-refresh in v1.
-- R7. **Deep linking**: the URL supports a per-file anchor (`#file=`) that scrolls to that file and expands it on load.
-- R8. **Accessibility and responsive**: below Tailwind `md` the split view auto-collapses to unified; `j`/`k` keys move between files; `change_kind` indicators carry accessible names; toolbar controls meet WCAG touch-target size; focus returns to the refresh button after refresh.
-
-**Diff semantics**
-- R9. Show the **net diff between the run's `base_sha` and its current head commit** (equivalent to `git diff HEAD`). Committed changes only; uncommitted working-tree state is **not** surfaced in v1.
-- R10. **Live (Running)** reads the sandbox's HEAD via the sandbox's git (effectively "diff as of the most recent checkpoint"). **Semantics** match `sandbox_git::git_diff` (`git diff HEAD`), but that helper is `pub(crate)`, has a 30 s timeout that conflicts with R32, and returns a single unbounded string — it cannot satisfy R24/R25/R27/R28. A new sibling helper is required: enumerates via `git diff --raw -z --find-renames=50% ..HEAD` with an early-stop at the 200-file cap, then per-file materializes via `git cat-file --batch` (size-gated) and `git show :` for non-binary entries. Committed-HEAD reads are safe to interleave with in-progress agent work (no index/working-tree mutation).
-- R11. **Post-sandbox** reconstructs the diff from the origin-side checkpoint branch using the run's recorded `base_sha` and head SHA.
-- R12. **Fallback when origin cannot be read** (branch pruned, fetch failure, repo archived) and `final_patch` is available (Success / PartialSuccess only per Persistence reality): parse the stored `final_patch` string into a degraded `FileDiff[]` — each entry has the file name, `change_kind`, and hunks, but **no full old/new contents**. The UI renders a "patch-only view" indicator so users know contents are not available. `@pierre/diffs` consumes this via empty `contents` plus a visible banner on each affected file (exact UI treatment is a planning concern; behavior is specified here). Note: the current `DiffFile` schema has only `{name, contents}`; R12 requires either (a) a new optional `hunks` field on `FileDiff`, or (b) dropping R12 in favor of R4's empty-state path — see Outstanding Questions. The degraded view must re-apply R24/R25/R26/R31 caps + denylist during parsing; filters apply to the response, not the source. If `final_patch` is `None` on a completed run, treat as R4(c) (no recoverable diff).
-- R13. **Coverage by run state**: `Running` / `Succeeded` / `PartialSuccess` always produce a diff. `Failed` produces a diff **if** the run checkpointed at least once before failing: use `RunFailed.git_commit_sha` (already carried on the event) as the head SHA and reconstruct from origin via R11, or from the sandbox if reachable via R10. Failed runs with no successful checkpoint fall through to R4(c). No changes to the run lifecycle or the `RunFailed` event are required.
-
-**Backend / API contract**
-- R14. Add `GET /api/v1/runs/{id}/files` with `operationId: listRunFiles`, returning the existing `PaginatedRunFileList` schema. The name is retained (additive change); v1 repurposes the existing `meta` object with top-level `truncated: bool` + `total_changed: int` per R27 rather than populating cursor fields. A rename can happen in a later additive version.
-- R15. The endpoint accepts optional `from_sha` and `to_sha` query parameters. Defaults: `from_sha = base_sha`, `to_sha = current HEAD`. Clients omit both in v1 and the server **rejects non-default values with 400** in v1 (prevents arbitrary-ref reads outside the run's branch; re-enable once an ancestry check against the run's branch head is in place). A future version can enable non-default values without a schema break. Rationale: keep the forward-compat slot without opening a read-ref surface before it's validated.
-- R16. Materialize the `FileDiff[]` **on demand** at request time. No new run-time persistence of per-file contents.
-- R17. Do not remove or change SlateDB's existing `final_patch` string projection. Other paths depend on it (PR body generation). The new endpoint is additive.
-- R18. No changes to the run lifecycle (no new events, no push-on-failure, no new event props). The tab works with existing persisted state.
-
-**Schema changes to `FileDiff`** (`docs/api-reference/fabro-api.yaml`)
-- R19. Add `change_kind: added | modified | deleted | renamed` to `FileDiff` as an **optional** field (the server always populates it on new responses; absence is tolerated for schema back-compat with pre-existing clients). Clients should consume `change_kind` when present and fall back to inferring from `old_file`/`new_file` content presence per R20.
-- R20. For added files: `old_file.contents = ""` and `old_file.name = new_file.name`. For deleted files: `new_file.contents = ""` and `new_file.name = old_file.name`. For renames: both `old_file.name` and `new_file.name` populated with distinct values; contents populated.
-- R21. Add **independent** booleans `truncated: bool` and `binary: bool` (both default `false`). `truncated` means size/line caps were hit (R24) or response-level budget was exhausted (R25). `binary` means content is not textual (R26). The two can coexist on a single entry.
-- R22. Add `sensitive: bool` (default `false`) to mark entries skipped by the denylist (R29). Contents empty, but the name/change_kind surface so reviewers know a change happened.
-- R23. Schema additions are additive: `old_file`/`new_file` stay `required` on `FileDiff` (empty-string contents represent added/deleted sides). New fields are optional for client back-compat; existing consumers that ignore them still render correctly.
-
-**Practical limits**
-- R24. Per-file cap (**Provisional, pending cap calibration below**): **256 KB** and **20,000 lines**. Over-cap entries return `truncated: true` with empty `contents`.
-- R25. Aggregate response cap (**Provisional**): **5 MB** of total `contents` bytes. Once the running byte budget is exceeded, subsequent entries are returned with `name` + `change_kind` only (empty contents, `truncated: true`). The response `meta.truncated` flag also flips to `true` so the UI can show an aggregate banner.
-- R26. Skip binary files: return `{name, change_kind, binary: true, contents: ""}`. Do **not** set `truncated` on the binary entry itself unless it also exceeds the per-file size cap; binary files that exhaust the aggregate budget do not retroactively change; they affect only the cap for subsequent entries.
-- R27. File-count cap (**Provisional**): **200 files**. Overflow surfaces as `meta.truncated: true` + `meta.total_changed` with a persistent banner on the tab. v1 repurposes the existing `meta` object rather than implementing cursor pagination; a real cursor is deferred until a consumer needs it.
-- R28. Rename detection uses `git diff --find-renames=50%`. Below threshold, changes are emitted as add + delete (no `renamed` entry). This is a git invocation contract, not a hand-rolled heuristic.
-
-**Security & observability**
-- R29. The endpoint enforces **`AuthenticatedService` authentication** (the same extractor used by other `/runs/{id}/*` endpoints). Run-ownership / workspace authorization is **not** currently enforced on sibling endpoints; adding it is a cross-cutting concern tracked separately. Unauthorized callers receive 404 (not 403) to avoid run-ID enumeration. If a workspace-membership layer is introduced later, this endpoint inherits it automatically via the shared extractor.
-- R30. **Committed-only scope is the primary secret-exposure control.** Because R9 restricts the diff to committed content, `.gitignore` is not itself a mitigation (git already respects it) — the real control is the denylist (R31) plus the caller's pre-existing run-access authorization. This requirement exists to make the threat model explicit: the tab shows what a user with the same repo access would see via `git diff` locally, no more and no less.
-- R31. **Sensitive-path denylist** (defense-in-depth, not a complete control): skip entries whose repo-relative paths match a built-in denylist (`.env`, `.env.*`, `*.pem`, `id_rsa*`, `.aws/credentials`, `.git/config`, `*.p12`, `*.keystore`, `*.key`). Return a placeholder entry with `sensitive: true` (R22). The denylist is owned by `fabro-server` and can be extended via config in a follow-up. Content-based secret detection is **out of scope**: a committed secret in a non-matching path is visible to anyone with run access, same as it would be via `git show` against the origin repo. The denylist narrows the accidental-exposure surface on common filenames; it is not a guarantee.
-- R32. **Request budget**: hard timeout on the git subprocess (10 s in sandbox, 20 s on host), per-caller rate limit on `/runs/{id}/files` (shared with sibling run endpoints), and **request coalescing per run**: concurrent callers for the same run share a single in-flight materialization — the second caller does not kick off its own git work nor receive a 429. Stop enumeration early once the 200-file cap is hit; do not enumerate-then-truncate.
-- R33. **Server-side git hardening**: the `git` process (on host for the origin path) runs with `core.hooksPath=/dev/null`, `protocol.ext.allow=never`, smudge/clean filters disabled, and no `GIT_CONFIG_*` leakage. All interpolated inputs (SHAs, paths, refs) go through `shell_quote()` per project rules. Content comes from `git show :` (blob addressing), never from filesystem reads. Committed symlinks are surfaced as a file whose `contents` is the literal link-target string; they are never dereferenced. **Applicability** depends on the post-sandbox read mechanism choice (see Outstanding Questions): under a GitHub REST read path, the subprocess flags are moot and blob addressing is via the REST API.
-- R34. `X-Fabro-Demo: 1` short-circuits to fixture output and must never trigger a real run lookup or sandbox/origin access. A real run ID without the header always goes through the normal auth + materialization path; the two modes cannot cross-contaminate.
-- R35. Diff contents, full changed-file paths, and raw git stderr must **not** appear in `tracing` logs, Sentry breadcrumbs, or Segment events. Log only counts, sizes, durations, and run IDs. See `docs-internal/logging-strategy.md`.
-
-**Demo mode**
-- R36. Demo mode returns a static `FileDiff[]` fixture so homepage/marketing demos work. The fixture currently hardcoded in `apps/fabro-web/app/routes/run-files.tsx` (`fallbackFiles`) moves to the server's demo handler alongside the other `/runs/{id}/*` demo stubs; the frontend no longer ships a fallback.
-
-## Success Criteria
-
-- A typical successful run's Files tab shows the same content as `git diff HEAD` run against the sandbox — not `fallbackFiles`.
-- A currently-running run's Files tab shows the diff as of its most recent checkpoint; a **Refresh** click re-queries the sandbox and updates within the p95 budget.
-- A `Failed` run whose sandbox is still reachable shows the diff through its last checkpoint. A `Failed` run whose sandbox is gone shows the distinct empty-state message from R4, not a blank fallback.
-- A completed run whose sandbox has been destroyed still shows its diff when the origin branch is present; if origin cannot be read, the UI renders the `final_patch`-derived degraded view with a visible banner.
-- Pathological runs (many files, huge files, binary files) complete within **p95 < 3 s** for runs up to 200 files and 5 MB aggregate content on a warm host-side cache. First contentful paint within 500 ms of data arrival. Binary, truncated, and sensitive entries render with clear markers.
-- Demo mode (`X-Fabro-Demo: 1`) still shows a recognizable fixture without touching any real run / sandbox / origin.
-
-## Scope Boundaries
-
-- "Steer" inline commenting is **not** in scope.
-- **Uncommitted working-tree state is not surfaced in v1** — live runs show the diff as of the last checkpoint only. Revisit once @pierre/diffs and caching behavior are proven on committed state.
-- No per-stage / per-checkpoint UI view; only the aggregate `base → current`. The optional `from_sha`/`to_sha` query params in R15 exist purely as forward compatibility.
-- No search, filtering, grouping, or collapse UX beyond what `@pierre/diffs` provides out of the box.
-- No diff download / export / copy-as-patch.
-- No changes to the run lifecycle, `RunFailed` event, or the existing `final_patch` persistence.
-- No live streaming updates — refresh is user-initiated via R6's Refresh control.
-
-## Key Decisions
-
-- **Committed-HEAD-only in v1.** Removes working-tree concurrency with the agent, removes the gitignore/secret-exfil risk unique to uncommitted content, and makes live and post-sandbox views semantically identical. Uncommitted-tree view is a deliberate v2 candidate, not a cut corner.
-- **Materialize on demand + `final_patch` fallback, no new run-time persistence.** Primary path reads git (sandbox or origin). When origin cannot be read, fall back to parsing the existing `final_patch` into a degraded hunks-only view. This keeps the architecture read-heavy without duplicating content, and explicitly does not depend on origin retention as an authority.
-- **Don't touch the run lifecycle.** An earlier draft proposed a push-on-failure lifecycle change; that approach is dropped. It introduced side-effect surface (ref pollution, CI triggers, crash-time credentials) that outweighed the benefit; the Failed-post-sandbox empty state is an acceptable v1 UX.
-- **Extend `FileDiff` schema additively.** `change_kind`, `truncated`, `binary`, and `sensitive` are independent fields so each can be reasoned about on its own; `old_file`/`new_file` stay required for back-compat.
-- **Security at the edge, not in clients.** Server-side enforces authz (R29), `.gitignore` (R30), sensitive-path denylist (R31), request budget (R32), and git-process hardening (R33). The UI assumes it receives safe data.
-- **Drop `PaginationMeta` cursoring.** A single `meta.truncated: bool` + `total_changed: int` matches what v1 actually needs; a real cursor is deferred until there is a consumer.
-
-## Dependencies / Assumptions
-
-- `base_sha` is reliably recorded on `StartRecord` for runs that pass `RunStarted`. Runs in `Submitted`/`Starting` have no `base_sha` yet — covered by R4(a).
-- The `fabro-server` process can read from origin using the same GitHub credentials resolver as `git_push_host`. The exact read mechanism (REST blob/tree API vs. a server-side bare clone vs. a shared mirror) is explicitly flagged below as Resolve-Before-Planning.
-- `@pierre/diffs` accepts the existing `{old_file, new_file}` contents shape and treats the added fields (`change_kind`, `truncated`, `binary`, `sensitive`) as inert metadata the callsite can read. A quick spike confirms this before the OpenAPI change is locked.
-- `reconnect_run_sandbox` in `fabro-server` dispatches to `fabro_sandbox::reconnect::reconnect`, which already supports Local, Docker, and Daytona providers (verified in `lib/crates/fabro-sandbox/src/reconnect.rs`). Live-state diff therefore works for all three. When reconnect fails at runtime for any provider, the endpoint returns R5(a) (transient, retriable) — failure is a runtime condition, not a provider-support gap.
-
-## Outstanding Questions
-
-### Resolve Before Planning
-- [Affects R11][Needs research] **Post-sandbox read mechanism**: GitHub REST `git/trees` + `git/blobs` vs. server-side bare clone (with cache) vs. a shared mirror. Each has different latency, rate-limit, and privacy profile. Pick one before planning because it shapes the handler, caching, and failure modes. Current leaning: GitHub REST with a per-installation token scoped to the run's repo, because it avoids server-side disk state; validate with a quick LOE estimate for a bare-clone alternative.
-- [Affects R24, R25, R27][Needs research] **Cap calibration**: sample P50/P95 `final_patch` sizes and file counts across recent runs before locking numeric caps. The 200 / 256 KB / 20 k / 5 MB targets are placeholders; confirm (or revise) against real data. Target: keep the truncation rate on common workflows under **5%**. Until calibrated, treat the Success Criteria p95 as conditional on whatever caps survive.
-- [Affects R12][Decision] **Keep R12 (degraded patch-only view) or drop it in favor of R4(c) empty state?** R12 requires either (a) a new optional `hunks` field on `FileDiff`, or (b) a non-standard rendering in `@pierre/diffs` that may not be supported, plus a server-side patch parser. A scope-guardian review argues the empty state is sufficient; an adversarial review flags that the fallback is load-bearing only when origin retention fails (unknown frequency). Resolve before planning: run a two-day spike on (a) parse feasibility + @pierre/diffs input shape, and (b) telemetry on branch retention in the target repos. Then keep or drop R12 with evidence.
-
-### Deferred to Planning
-- [Affects R9, R10][Technical] Should the sandbox-side `git` invocation be reused via `sandbox_git::git_diff`, or does the `--find-renames` + `-z` + raw machine-readable listing suggest a sibling helper? Either is fine; pick the smaller diff.
-- [Affects R12][Technical] The `final_patch`-derived degraded view needs a patch parser on the server. Is there an existing Rust patch parser we prefer (`gix-diff`, `unidiff`, hand-rolled)? Decide based on workspace dependency policy.
-- [Affects R22, R31][Technical] Denylist lives in `fabro-server` initially; revisit whether it should be config-driven in a follow-up.
-- [Affects R32][Technical] Concurrency cap of 1 per run: is this coarse-grained lock sufficient, or do we need request coalescing so concurrent viewers share one materialization?
-- [Affects R6][Technical] "Last updated Xs ago" freshness indicator — is the timestamp the HTTP response time, or the `to_sha` commit time? Probably the former; confirm with a UX spike.
-- [Affects R31][Technical] Which specific redaction-related primitives from `fabro-util` should we reuse? (Log scrubbing redaction is different from content redaction; content-redaction is explicitly **out of scope** per Key Decisions — skipping is simpler than masking.)
-
-## Next Steps
-
-→ `/ce:plan` for structured implementation planning.
diff --git a/docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md b/docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md
deleted file mode 100644
index 4d7c43639..000000000
--- a/docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md
+++ /dev/null
@@ -1,126 +0,0 @@
----
-date: 2026-04-19
-topic: web-ui-lifecycle-actions
----
-
-# Expose CLI Lifecycle Actions in the Web UI
-
-## Problem Frame
-
-The Fabro web UI today is essentially read-only for run management. The only mutating action exposed is **Preview** (opens a sandbox port URL). Every other run lifecycle action — cancelling a stuck run, cleaning up the board, revisiting archived runs — requires dropping to the CLI.
-
-Two concrete user problems drive this work:
-
-1. **Daily friction for CLI users.** People live in the board view and detail pages but have to context-switch to a terminal to manage state.
-2. **Excludes non-CLI teammates.** PMs, reviewers, and stakeholders can watch runs but cannot participate in managing them, cutting the UI off as a collaboration surface.
-
-The web UI should own the **everyday lifecycle operations** these users hit. Rarer or more dangerous CLI verbs (force-delete of active runs, checkpoint ops, etc.) can remain CLI-only by design; the goal is user value per surface, not parity for parity's sake.
-
-Most server infrastructure already exists — `POST /runs/{id}/{cancel,archive,unarchive}` are live, wired to the workflow engine's operations, and emit SSE events. The remaining work is UI surface + a handful of concrete SSE reconciliation gaps (see Dependencies).
-
-## Requirements
-
-**Action set**
-- R1. Expose three lifecycle actions on the run detail page (`/runs/{id}`): **cancel**, **archive**, **unarchive**.
-- R2. Do not expose `pause`, `unpause`, or `delete` in this first pass. Pause/unpause has no evidenced daily-user need; delete's tab-close-mid-undo failure mode is unacceptable for a non-CLI teammate because observability is destroyed (there's no run to revisit to self-verify).
-- R3. Do not expose checkpoint operations (resume, rewind, fork) or HITL question answering in this first pass.
-- R4. Do not expose these actions on the board kanban cards or as bulk selection in this first pass.
-
-**State-aware visibility**
-- R5. Only show an action when the run's current status makes it valid:
- - **cancel (primary)**: visible as a primary affordance when status is `submitted`, `runnable`, `starting`, `running`, or `paused`. Not shown as primary when `blocked` — see R6. The server also accepts cancel on `blocked` runs; that path is only reachable via the secondary surface from R6.
- - **archive**: visible only when status is terminal (`succeeded`, `failed`, `dead`) AND not already archived.
- - **unarchive**: visible only when `archived`.
-- R6. When a run is `blocked` (waiting on an HITL question), do not show cancel as a primary action. Instead, show an inline notice with the pending question text (from `GET /api/v1/runs/{id}/questions`, whose `ApiQuestion.text` field is already human-readable) and the instruction: "Answer this question via `fabro` CLI to continue." Cancel remains reachable via an overflow/secondary affordance (e.g., a "…" menu) for users who truly want to abandon the run. This protects the common case (non-CLI teammate accidentally cancelling work that was waiting for them) without fully hiding the escape hatch.
-- R7. Visibility updates live when the run status changes. The detail page must subscribe to the run's SSE event stream (`GET /runs/{id}/attach`) so action affordances appear/disappear without a manual refresh.
-
-**Interaction & feedback**
-
-Two toast patterns, matched to the reversibility of each action:
-
-- R8. **Cancel uses a client-side deferred toast with a fixed 5-second countdown.** Cancel has partially-irreversible side effects (the agent stops mid-stage) so the undo window guards against misclicks.
- - Clicking cancel shows a toast with the action description, a 5-second countdown, and an **Undo** button. The cancel affordance enters a disabled/pending state during the window (not hidden — hiding mid-window misrepresents actual run state).
- - If the user clicks **Undo** before the countdown expires, the pending client-side timer is cancelled and no API call is made.
- - If the countdown expires, the client fires the API call. **Before firing**, the UI performs a `GET /api/v1/runs/{id}` refetch: if the run's status is no longer one where cancel is valid (e.g., the run completed or was cancelled elsewhere), the pending action is aborted and a brief "Run transitioned — cancel aborted" notice is shown instead. This covers the SSE-channel-unreachable case where R9's event-driven abort cannot fire.
- - If the tab is closed or navigated away (including SPA navigation to another route) mid-window, the pending action is silently cancelled. Accepted tradeoff of the client-only approach.
-
-- R9. **Archive and unarchive fire immediately with an inverse-action toast.** Both are fully reversible by the opposite API call, so the 5-second countdown is overhead with no safety benefit. Gmail-archive shape:
- - Clicking archive fires `POST /runs/{id}/archive` immediately (optimistic UI: the run disappears from terminal views / moves to archived views right away).
- - On success, show a toast: "Run archived. **Unarchive**" with a visible action button. The toast remains dismissable for ~8 seconds.
- - Clicking **Unarchive** in the toast fires `POST /runs/{id}/unarchive`. The toast updates to "Run restored" briefly, then dismisses.
- - Unarchive-triggered-from-the-primary-affordance works identically, with the inverse verb.
-
-- R10. **Undo-window collisions (cancel only).** While the cancel timer is pending for a run, other primary affordances for that run are disabled (not hidden). If an SSE event arrives for that run that would change its status (another tab, a CLI user, the run finishing naturally), the pending client-side timer is cancelled, the toast is dismissed with a brief notice ("Run transitioned — action cancelled"), and the UI reconciles to the new status. If a newly-valid action (e.g., archive becomes valid because the run just completed) results from the transition, its affordance lights up immediately rather than waiting for the toast to fully dismiss.
-
-- R11. On a successful async cancel (status unchanged in the response body), the UI relies on SSE for the final status flip. No additional success toast beyond the deferred-toast already shown.
-
-- R12. On API failure (including 409 precondition failures — e.g., the run transitioned out of a valid state between toast-expiry and API call), show an error toast that includes the server's error message, and refetch the run so the UI reconciles to actual state. For the archive/unarchive fire-immediately path, additionally roll back the optimistic UI change on failure.
-
-- R13. **Multi-tab behavior (single-client rules apply per tab).** R8/R10 are scoped per-client: each tab runs its own timer. An SSE-delivered status transition in tab B (caused by tab A firing cancel) will cancel tab B's own pending timer for the same run per R10 and surface the transition notice. Cross-tab action coordination beyond what SSE already provides is not a requirement for this pass.
-
-**Accessibility**
-- R14. Both toast patterns (deferred cancel toast; immediate archive/unarchive toast) must meet baseline a11y expectations:
- - Toast container uses `role="status"` with `aria-live="polite"` (assertive interrupts screen-reader output and is wrong here). Announcement names the action, e.g., "Cancel run requested, undoing in 5 seconds" or "Run archived. Press Unarchive to undo."
- - Toast does **not** steal focus, but is reachable via keyboard (tab order places the action button — Undo or Unarchive — immediately after the triggering affordance).
- - For the cancel deferred toast, while keyboard focus is on the **Undo** button, the 5-second countdown **pauses** and resumes counting down from the paused value when focus leaves. Focus leaving the Undo button after the countdown would have expired does not auto-fire the action — the user must still explicitly close the toast or navigate away for the countdown to resume its final tick.
- - Archive/unarchive toasts do not count down (they fire on click); they remain dismissable and focusable for ~8 seconds.
- - Touch targets (Undo / Unarchive buttons) meet 44×44 CSS px minimum. The detail page is expected to work on tablet and larger; phone-size support is not a requirement for this pass.
- - The action cluster is keyboard-operable end to end (no mouse-only affordances). Keyboard shortcuts for individual actions are out of scope for this pass.
-
-## Success Criteria
-
-- A user managing runs day-to-day can complete a full session (cancelling a stuck run, archiving finished ones, revisiting an archived one) without touching the CLI.
-- A non-CLI teammate can cancel or archive a run in the web UI without onboarding documentation beyond "click the button."
-- A non-CLI teammate who lands on a `blocked` run understands the run is waiting on a human answer, sees the question text, and does not accidentally cancel work in progress. **Note:** unblocking the teammate so they can actually *answer* the question requires HITL-answering in the web UI, which is deferred — this first pass prevents destruction, not participation. If blocked-teammate-can't-proceed proves to be a real painful pattern in usage, HITL answering should be the next scope to pick up.
-- When a run transitions state while the detail page is open (e.g., finishes, gets archived from the CLI, gets cancelled by someone else), the available actions update live without a page refresh.
-- The cancel deferred-toast component (toast container + Undo + pause-on-focus countdown + polite aria-live) is shaped so it can host future destructive actions (delete if we solve the observability problem; force-cancel if ever added) without redesign. The archive/unarchive immediate-inverse toast is a simpler shape that other reversible fire-and-forget actions can reuse.
-
-## Scope Boundaries
-
-**Out of scope for this first pass:**
-- `pause` and `unpause` (no evidenced daily-user pain for the target personas; revisit if a real workflow surfaces).
-- `delete` (tab-close-silently-cancels destroys observability — there's no run to revisit to self-verify — which is unacceptable for the non-CLI teammate persona; revisit with server-side soft-delete or a different UX).
-- Force-delete of active runs (`rm --force`).
-- Checkpoint operations: `resume`, `rewind`, `fork`. These need parameter input (which checkpoint? which branch?) that doesn't fit the uniform button+toast pattern.
-- Answering HITL questions from the web UI. R6 surfaces the question read-only and points to the CLI.
-- Board-card actions and bulk multi-select on the board.
-- Dense table/list view of runs.
-- Server-side deferred/pending states.
-- Keyboard shortcuts for individual actions.
-- Role-based authorization (assumed unchanged from today; all authenticated users can take all actions).
-- Phone-size responsive layout.
-
-## Key Decisions
-
-- **Cancel + archive + unarchive only.** Cancel addresses the clearest daily pain (stuck runs). Archive/unarchive addresses board clutter and is fully reversible by the opposite action — lowest-risk place to validate the interaction pattern. Pause/unpause are deferred for lack of evidenced need; delete is deferred because its client-side-undo failure mode destroys observability for the non-CLI teammate persona.
-- **Run detail page only, not the board.** Keep the first pass tight.
-- **Two toast patterns matched to reversibility, not one uniform pattern.** Cancel is partially irreversible → deferred-toast with a bound 5-second countdown. Archive/unarchive are fully reversible via the opposite API call → fire-immediately with an inverse-action toast (Gmail-archive shape). This is more spec than "one pattern for everything" but maps to a real property of the actions and eliminates a pointless friction tax on the reversible ones. The shared toast infrastructure (container, action-button slot, aria-live, keyboard reachability) is reused across both; only the cancel path carries the countdown + focus-pause machinery.
-- **Pre-fire status recheck on the deferred cancel path.** At countdown expiry, the client refetches `GET /runs/{id}` before firing the cancel API call. This covers the SSE-unreachable failure mode where R10's event-driven abort cannot fire: without the recheck, a dead SSE channel would silently degrade to "timer fires, 409 error, user sees error toast for a race they didn't create." One extra GET per cancel is a cheap premium for reliable UX.
-- **Blocked runs suppress cancel as a primary affordance and show the pending question.** Protects non-CLI teammates from the worst failure mode (cancelling work that was waiting for them). Cancel remains reachable via a secondary/overflow affordance for users who genuinely want to abandon. This solves the destruction problem but leaves the participation problem for HITL-in-the-web to solve later.
-- **Client-side deferral, not server-side.** Chosen on shipping speed; does not add new lifecycle states. Accepted tradeoff: the "undo" promise is soft — tab close or SPA nav silently cancels. This is tolerable precisely because the action with the worst silent-cancellation consequence (delete) was scoped out.
-- **Accessibility is in the requirements, not deferred to implementation.** ARIA semantics, keyboard reachability, focus-pauses-countdown, touch-target sizing, and aria-live politeness are specified rather than left as "standard best practices."
-- **Pattern reuse is claimed only within this action family.** We do not claim "adding resume/rewind/fork/HITL later is same shape, new button." Those need parameter input (checkpoint choice, answer text) that the button+toast pattern doesn't host. That's fine — these patterns are for fire-and-forget lifecycle mutations, and the rest of the verbs will need their own UX.
-
-## Dependencies / Assumptions
-
-- The existing API endpoints (`POST /runs/{id}/{cancel,archive,unarchive}`) are stable and will not require spec changes. Verified against `docs/api-reference/fabro-api.yaml`.
-- The generated TypeScript client in `lib/packages/fabro-api-client` exposes (or will trivially expose after regeneration) methods for these endpoints.
-- **SSE coverage is not uniform.** The server emits `run.*` events for status transitions including `run.archived` / `run.unarchived` (`fabro-workflow/src/event.rs`, `fabro-server/src/server.rs`). Known gaps the plan must address:
- - The board's event allowlist (`apps/fabro-web/app/routes/runs.tsx` `BOARD_STATUS_EVENTS`) does not currently include `run.archived` / `run.unarchived`. Adding them is in scope.
- - The per-run `/attach` SSE stream terminates on `RunCompleted` / `RunFailed`. Archive/unarchive events fire on already-terminal runs, so the detail page must either reconnect to a non-terminating channel, refetch on the successful archive/unarchive response, or listen at a layer above `/attach`. Planning should pick an approach.
-- **Run detail page is not yet SSE-subscribed.** `apps/fabro-web/app/routes/run-detail.tsx` currently fetches the run once via the React Router loader and does not subscribe to `/api/v1/runs/{id}/attach`. Wiring this subscription at the detail-page level (the owner of `run.status` that drives R5 visibility) is net-new work for R7. Individual tab components (stage-sidebar, run-files) already have per-run SSE subscriptions that can be used as a pattern.
-- **No undo-capable toast system exists yet.** The only Toast in `apps/fabro-web` is a read-only live-region banner (`apps/fabro-web/app/routes/run-files/states.tsx`) with local `useState`/`setTimeout`. R8 + R9 + R12 together require a shared toast component with: a countdown, action-button slot, programmatic dismiss, multi-toast coexistence, polite aria-live, and focus-pauses-countdown behavior. This is net-new UI infrastructure.
-- **Cancel semantics.** For `submitted` and `runnable` runs, cancel synchronously flips lifecycle `status` to `failed` with `status_reason: cancelled` and returns that on the response. For `starting`/`running`/`blocked`/`paused` runs, cancel returns 200 with unchanged status and the transition lands asynchronously via the workflow engine. The UI should treat cancel as "request accepted" and rely on SSE for the final status flip — R10 covers this implicitly, but the plan should make the optimistic-UI behavior explicit (e.g., the cancel affordance stays in its disabled/pending state until either the response body carries the synchronous `failed`/`cancelled` result or the SSE-driven reconciliation arrives).
-- **Per-run `/attach` stream has silent termination paths beyond the terminal-event case.** `attach_event_is_terminal` only matches `RunCompleted | RunFailed`, but the task that drives the stream can also exit without a terminal marker if the store read errors, if the run projection becomes non-active mid-replay, or if cancel lands on a runnable run that never transitioned to running (covered by the `cancel_before_run_transitions_to_running_returns_empty_attach_stream` test in `fabro-server/src/server.rs`). R7 and R10 must therefore not assume a terminal event will always land: the plan needs a fallback refetch path for "SSE stream ended without a terminal marker" and for "SSE channel unreachable during an undo window."
-- Authorization is a non-issue today (single-user / trusted deployment assumption). If multi-tenant auth lands, the action affordances will need to respect it, but that's a separate workstream.
-
-## Outstanding Questions
-
-### Deferred to Planning
-- [Affects R8][Design] Exact visual placement of the action cluster in the detail page header: single "Actions" dropdown vs. inline buttons vs. split primary+overflow. Behavior is specified here; visual placement resolves in design/implementation. Consider how cancel-on-blocked lives in the overflow while the primary slot is occupied by the R6 inline notice.
-- [Affects R11][Technical] Confirm the 409 error-body shape from the server so error-toast copy can use the server-provided message verbatim.
-- [Affects R7, R10][Technical] Decide the post-terminal reconciliation mechanism for archive/unarchive: reconnect SSE after terminal close, refetch on 2xx archive/unarchive response, or subscribe on a non-terminating channel. Either the per-run `/attach` contract extends or the UI uses response-driven reconciliation.
-
-## Next Steps
-
-→ `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md b/docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md
deleted file mode 100644
index 90848007f..000000000
--- a/docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md
+++ /dev/null
@@ -1,146 +0,0 @@
----
-date: 2026-04-20
-topic: fabro-store-record-abstractions
----
-
-# Fabro-store Record Abstractions
-
-## Problem Frame
-
-Adding a new persisted record type to `fabro-store` today means writing ~200–400 LOC of repetitive plumbing in a new `Slate*Store`: key construction, JSON serialization, `get`/`put`/`delete`/`scan_prefix` wrappers, optional per-key consume mutex, optional GC-by-prefix-scan, optional secondary index. The existing four record families — `RefreshToken`, `AuthCode`, `Blob`, and the Run catalog index — share most of that plumbing mechanically, but each duplicates it inside `lib/crates/fabro-store/src/slate/`. As more record types land (new auth flows, sessions, vault entries, agent state), the duplication compounds and each copy is one more place where serialization, locking, or key encoding can drift.
-
-Greenfield, no production deployments — backwards compat can be broken freely.
-
-## Architecture
-
-```
-lib/crates/fabro-store/
- Database
- .refresh_tokens() -> Arc
- .auth_codes() -> Arc
- .blobs() -> Arc
- .catalog_index() -> Arc
- .runs() -> Runs (unchanged)
-
- *Store wrappers (one per Record)
- own: Repository + domain helpers (KeyedMutex, ReplayCache, …)
- expose: domain-named methods (consume_and_rotate, delete_chain, …)
-
- Repository ← reusable typed K/V layer
- get / put / delete / scan_stream / scan_prefix_stream / gc
- serializes via R::Codec
- keys built from R::PREFIX + R::Id::key_segments
- pub(crate) — wrapper Stores own it; never exposed on Database
-
- trait Record / trait RecordId / trait Codec
- Record::PREFIX (const)
- Record::Codec (associated type; each impl writes `type Codec = JsonCodec;`)
- Record::id(&self) (-> Self::Id)
- RecordId::key_segments(&self) -> Vec (Repository assembles SlateKey)
-
- transaction(&db, |tx| { tx.put(&r1)?; tx.put(&r2)?; })
- ← cross-record atomic batch
-```
-
-Run's event log, projection cache, broadcast channel, and per-run mutex stay in `RunDatabase` and are deliberately out of scope. The Run catalog *index* (today's `slate/catalog.rs`) is in scope and becomes `RunCatalogIndex` on top of `Repository`.
-
-## Records in Scope
-
-| Record | PREFIX | Id type | Codec | Special semantics |
-|------------------|-------------------------|---------------------|-----------|---------------------------------------------------------|
-| RefreshToken | `auth/refresh` | `[u8; 32]` (hex) | JsonCodec | KeyedMutex consume lock, in-memory replay revocation |
-| AuthCode | `auth/code` | `String` (opaque) | JsonCodec | KeyedMutex consume lock, single-use |
-| Blob | `blobs/sha256` | `RunBlobId` | RawBytesCodec | Immutable, content-addressed, never deleted |
-| RunCatalogEntry | `runs/_index/by-start` | `RunId` | EmptyCodec | Empty value; date segment derived from `RunId.created_at()` |
-
-## Requirements
-
-**Core abstraction**
-- R1. Define `trait Record: Sized + Send + Sync + 'static` with associated `type Id: RecordId`, `type Codec: Codec`, `const PREFIX: &'static str`, and `fn id(&self) -> Self::Id`. Each `impl Record` writes `type Codec = JsonCodec;` (or its override) explicitly — no associated-type default, since `associated_type_defaults` is unstable on stable Rust as of 2026. One extra line per impl is the lowest-magic alternative; the workspace doesn't have a proc-macro sub-crate today and adding one is more weight than the savings justifies. `PREFIX` is a `/`-separated path of segments (e.g. `"auth/refresh"`, `"runs/_index/by-start"`) that `Repository` splits before assembling the `\0`-separated `SlateKey`; `/` is therefore reserved inside any single segment.
-- R2. Define `trait RecordId { fn key_segments(&self) -> Vec; }`. Implementations return segment data; `Repository` assembles the SlateKey internally so `SlateKey` (and its `\0`-segment-boundary invariant) stay `pub(crate)`. Built-in impls: `[u8; 32]` writes one hex segment; `String` writes itself; `RunBlobId` writes its sha256 hex segment; `RunId` writes two segments — `` derived from `RunId.created_at()` followed by the RunId string. (`RunId`-as-Record-Id is used only by `RunCatalogEntry` today; if a future record needs a single-segment RunId encoding it uses a newtype wrapper.)
-- R3. Define `trait Codec { fn encode(r: &R) -> Result>; fn decode(bytes: &[u8]) -> Result; }` with built-in implementations: `JsonCodec` (used by most records), `RawBytesCodec` (for `Blob`), `EmptyCodec` (for index entries with no value). `JsonCodec::encode` is implemented as a one-line literal forwarding to `serde_json::to_vec(&value)` (and `decode` to `serde_json::from_slice`); the implementation IS the proof of byte-identity. A snapshot test on a representative `RefreshToken` and `AuthCode` is kept as a regression net so any accidental change to the forwarding impl (e.g. someone adds an envelope) fails CI loudly. The snapshot files commit the on-disk wire format to the repo and are reviewed as wire-format changes when they change.
-- R4. Provide `Repository` exposing the typed K/V primitives: `get(&R::Id)`, `put(&R)`, `delete(&R::Id)`, `scan_stream() -> impl Stream>` (full prefix), `scan_prefix_stream(extra_segments)`, and `gc(predicate: impl Fn(&R) -> bool) -> Result` (scans, filters, deletes — replaces the three hand-rolled GC-by-prefix-scan loops in today's stores). `Repository` is `pub(crate)`. The `gc` predicate is sync `Fn` (so it cannot mutate caller state across the scan), MUST NOT perform I/O or block (it runs once per scanned record), and MUST be free of side effects (gc may be called more than once on the same record set during retries or future caller logic). `gc` issues all deletes in a single `slatedb::WriteBatch` — atomic vs today's per-key delete loop, deliberate behaviour change. No capability traits, no marker subtraits — domain logic lives in the wrapper Store.
-
-**Wrapper stores**
-- R5. Each record family has a named domain `*Store` type that owns a `Repository` and any domain-specific helpers (per-key mutex, in-memory caches, replay revocation set). Trivial stores (`BlobStore`, `RunCatalogIndex`) are still concrete named types even when they are thin pass-throughs. **Security boundary**: `Repository` is `pub(crate)`; construction is gated to the wrapper Store and to test fixtures. The `Repository` field on each wrapper Store is private (`pub(super)` at most); wrapper Stores never expose `.scan_stream()` / `.gc()` / `.repository()` accessors. `Database` exposes only the wrapper Stores, never `Repository` directly. Domain methods that need a scan (e.g. `gc_expired`, `delete_chain`) perform it internally and return aggregate results, never raw records. The boundary is enforced for crate-external callers by the `pub(crate)` visibility; for crate-internal contributors it is convention + code review (a future fabro-store author who constructs `Repository` directly is bypassing the design and the PR review should catch it).
-- R6. `RefreshTokenStore` keeps its existing API (`insert_refresh_token`, `find_refresh_token`, `consume_and_rotate`, `delete_chain`, `gc_expired`, `mark_refresh_token_replay`, `was_recently_replay_revoked`). `consume_and_rotate` uses the new `transaction` helper while still holding its `KeyedMutex` guard around the call. The replay revocation set (`mark_refresh_token_replay` / `was_recently_replay_revoked`) is in-memory only with a 60s TTL — it MUST NOT be moved into `Repository` or otherwise persisted. Rationale: it's a transient signal so the current process can recognize replays within the rotation window; persisting attacker-supplied token hashes adds disk I/O and a new GC surface with no security benefit and an unbounded-growth risk under token-stuffing attack.
-- R7. `AuthCodeStore` keeps its existing API (`insert`, `consume`, `gc_expired`). The `AuthCode` struct gains a `code: String` first field carrying its own key (today's struct receives the code as a separate parameter to `insert`); this lets `Record::id(&self)` return the key from the value, which `Repository::scan_stream` requires. The on-disk JSON shape gains one field — acceptable under greenfield.
-- R8. `BlobStore` exposes `read(&RunBlobId)`, `write(bytes) -> RunBlobId`, `exists(&RunBlobId)`. `delete` is intentionally not exposed — current behaviour is that blobs survive run deletion (enforced by `delete_run_keeps_global_cas_blobs` test). `RunDatabase::write_blob` / `read_blob` / `list_blobs` keep their signatures and delegate to `BlobStore` internally so existing callers (and tests) require no changes.
-- R9. `RunCatalogIndex` exposes `add(&RunId)`, `remove(&RunId)`, `list(query: &ListRunsQuery) -> Vec`, replacing the free functions in `lib/crates/fabro-store/src/slate/catalog.rs`. `list` scans the prefix, applies `query.start`/`query.end` filtering against `run_id.created_at()`, and sorts by the same key as today's `catalog.rs:39-49` — `(year, month, day, hour, minute, run_id)` ascending — derived inside `RunCatalogIndex::list` from each `RunId`'s embedded ULID timestamp. The post-list summary-building loop in `Database::list_runs` (`slate/mod.rs:170-183`) is **not** absorbed into `RunCatalogIndex`; only the catalog scan + filter + sort move.
-
-**Cross-record atomic writes**
-- R10. Provide a `transaction(&db, |tx| { … })` helper producing a single `slatedb::WriteBatch`. `Tx` exposes `put(&R)` and `delete(&R::Id)` for any `R: Record`, so a single transaction can span record types. Replaces the hand-built `slatedb::WriteBatch` in `RefreshTokenStore::consume_and_rotate`. **Atomicity invariants** (security-critical for token rotation): the closure is `FnOnce(&mut Tx) -> Result` (synchronous); on closure `Err`, no slatedb write occurs (codec errors short-circuit via `?`); on closure `Ok`, exactly one `slatedb::WriteBatch::write` commit is issued; no retry, no partial flush, no commit-on-drop. A fault-injection test asserts that an encode failure on the Nth `put` leaves the database unchanged. To restrict the cross-type capability to authorized callers, `transaction` is `pub(crate)` — wrapper Stores expose domain-named atomic methods (e.g. `RefreshTokenStore::consume_and_rotate`) that compose `transaction` internally.
-
-**Database surface**
-- R11. `Database` exposes `refresh_tokens()`, `auth_codes()`, `blobs()`, `catalog_index()`, and `runs()`. Each lazily initializes its store via `OnceCell` and returns `Arc<*Store>` (mirrors today's pattern in `lib/crates/fabro-store/src/slate/mod.rs:208-228`).
-- R12. `RunDatabase`'s event-sourcing machinery (event log, projection cache, broadcast channel, atomic seq counter, per-run state mutex) and public method signatures are unchanged. Two internal touch-points exist: (a) the catalog call sites all live in `Database` itself — `Database::create_run` (`slate/mod.rs:119,127`), `Database::list_runs` (`slate/mod.rs:169`), and `Database::delete_run` (`slate/mod.rs:204`) — and migrate from `catalog::write_index` / `catalog::delete_index` / `catalog::list_run_ids` to the new `RunCatalogIndex` (lazily initialized on `Database` via `OnceCell`, like the other stores); (b) `RunDatabase::write_blob` / `read_blob` / `list_blobs` (`run_store.rs:283-302`) keep their public signatures and behaviour but delegate internally to `BlobStore` per R8. No callers change.
-
-**Reusable helpers**
-- R13. Extract `KeyedMutex` (per-key async mutex on top of `DashMap>>` with auto-cleanup when strong count drops to 2) as a shared helper inside `fabro-store`, used by `RefreshTokenStore` and `AuthCodeStore`. **Security purpose**: `KeyedMutex` serializes concurrent `consume` operations on the same key. Required by single-use semantics for `AuthCode` and replay detection for `RefreshToken` — without it, a TOCTOU race between the find/get and the delete/mark-used write permits double-consumption. Auto-cleanup at `strong_count == 2` bounds the map size so a high volume of distinct codes/hashes cannot grow it without limit. The cleanup check and the entry insertion happen under the same `DashMap` shard lock so a concurrent `lock(&key)` cannot observe a soon-to-be-dropped Arc and acquire a different `Mutex` instance for the same key. `KeyedMutex` exposes only `lock(&self, key: K) -> Guard<'_>` — never returns or clones the inner `Arc`; `Guard` holds the Arc internally so the strong-count==2 check happens after `Guard` drops. The lock MUST NOT be made optional, replaced with a TTL/janitor, or relocated to a separate process without explicit security review.
-
-## Success Criteria
-
-- Adding a 5th simple K/V record type requires writing only: a struct + `impl Record` + an `impl RecordId` (if its ID type isn't already covered) + a thin `*Store` wrapper. No new key-construction code, no `serde_json::to_vec`/`from_slice` per store, no copy of get/put/delete/scan plumbing.
-- All existing public store APIs (`RefreshTokenStore::consume_and_rotate`, `AuthCodeStore::consume`, etc.) keep their signatures and observable behaviour. Existing unit and integration tests pass without modification.
-- `lib/crates/fabro-store/src/slate/auth_tokens.rs` and `auth_codes.rs` shrink to roughly their domain logic (consume lock, GC traversal, replay cache) — kv plumbing moves into `Repository`.
-- `lib/crates/fabro-store/src/slate/catalog.rs` is deleted; `RunCatalogIndex` exposes the same operations through `Repository`.
-- A single `transaction(…)` call replaces the hand-built `slatedb::WriteBatch` in `RefreshTokenStore::consume_and_rotate`.
-
-## Scope Boundaries
-
-- Run aggregate's event-sourcing machinery (`RunDatabase` event log, projection cache, broadcast channel, `recover_next_seq`, `EventProjectionCache`, atomic seq counter) is not refactored. `RunDatabase`'s blob methods are touched only to delegate to `BlobStore` per R8 — no signature or behaviour change.
-- No marker capability traits (`ExpiringRecord`, `ConsumableRecord`, `IndexedRecord`, `ContentAddressed`). Capabilities are hand-written per `*Store`.
-- No record schema versioning or migration framework. Greenfield, can break compat.
-- No swap-out of the storage backend (still SlateDB on `Arc`). Repository is parameterized by `R`, not by storage.
-- No changes to `ArtifactStore` or other non-SlateDB storage.
-- No changes to the public `Database::create_run` / `open_run` / `delete_run` / `list_runs` API signatures or observable behaviour. Internal implementations of `create_run`, `list_runs`, and `delete_run` consume the new `RunCatalogIndex` per R12.
-
-## Key Decisions
-
-- **Two worlds** (Run separate from simple K/V records): unifying an event-sourced aggregate (atomic seq counter, projection cache, live broadcast, per-run state mutex) with single-key records would either flatten to a lowest-common-denominator API or force Run's complexity onto records that don't need it.
-- **Hand-written `*Store` wrappers on a thin `Repository`** (not marker capability traits): chose lowest magic. Capability variations are small in number, infrequently added, and easy to read inline. A reader of `RefreshTokenStore` should see exactly what `consume_and_rotate` does without crossing trait-bound boundaries.
-- **Multi-segment IDs via data-only `key_segments() -> Vec`**: `SlateKey` stays `pub(crate)`. `Repository` assembles the key internally — `RecordId` impls cannot violate the `\0`-segment-boundary invariant by accident. Small allocation per key derivation is acceptable for the encapsulation gain.
-- **Codec specified explicitly per impl** (no associated-type default): `associated_type_defaults` is unstable on stable Rust as of 2026. Rather than wait, pull in a derive-macro sub-crate, or split into sub-traits, every `impl Record` writes `type Codec = JsonCodec;` (or its override). One extra line per impl, no nightly, no proc-macro infra.
-- **`transaction(...)` as a single-batch atomic primitive, `pub(crate)`**: `consume_and_rotate` already needs an atomic two-key write; one helper covers it and any future cross-record flows. Closure is `FnOnce`, all-or-nothing, no commit-on-drop. Crate-private visibility prevents callers from bypassing per-store invariants — wrapper Stores expose domain-named atomic methods that compose `transaction` internally.
-- **Repository for security-sensitive records is store-private**: `Database` exposes only wrapper Stores. `RefreshTokenStore` and `AuthCodeStore` never hand out a `Repository` accessor or generic `scan`. Prevents a new caller in `fabro-server` (or anywhere else) from walking the entire token table.
-- **Named `*Store` for every record**: discoverability matters more than line count. `db.blobs()` and `db.catalog_index()` read more clearly than `db.repository::()`. The trivial wrappers (`BlobStore`, `RunCatalogIndex`) are accepted overhead — see Alternatives Considered for the leaner shape we rejected.
-
-## Alternatives Considered
-
-Three lighter shapes were considered. The full scaffold (R1–R13) was chosen anyway. Comparison:
-
-| Option | New types | Approx. scaffold | Per-record cost (5th) | Trade |
-|---|---|---|---|---|
-| (1) Copy-paste-and-rename | 0 | 0 LOC | ~200 LOC duplicated | Zero abstraction tax now; drift risk grows linearly. |
-| (2) `JsonStore` helper only | 1 (~30 LOC) | ~30 LOC | ~80 LOC | Removes JSON serde duplication only. No typed key, no codec abstraction, no transaction helper, no security boundary. Each store keeps bespoke key construction and consume locks. |
-| (3) Minimum-viable subset (R1+R2+R3 JsonCodec only+R4+R6+R7+R13) | ~5 traits + Repository + KeyedMutex | ~120 LOC | ~30 LOC | Touches only `auth_tokens.rs` and `auth_codes.rs`. Drops `BlobStore`, `RunCatalogIndex`, cross-record `transaction`, `RawBytesCodec`, `EmptyCodec`. Loses the boundary requirement (no Blob/catalog pass-through to demonstrate the pattern). |
-| **(chosen) Full scaffold (R1–R13)** | ~6 traits + Repository + Tx + 4 wrapper stores + KeyedMutex | ~250 LOC | ~30 LOC | All of (3) plus Blob CAS and catalog refactor onto the same shape. R8 (`BlobStore` as a public Database surface) and R9 (catalog migration) are forward-looking in their *value* — they don't have a new today-consumer beyond what already works through `RunDatabase::write_blob` and `catalog::*` — but they are concrete refactors of existing code, not speculative new code. R10's cross-type Tx is similarly forward-looking. |
-
-**Why (chosen) over (3)**: standardizes the shape across every K/V record the crate has, so new entrants (sessions, vault, agent state) hit one well-understood pattern instead of choosing between "use `Repository`" and "use the older bespoke style." Designs the security boundary (R5) once for the whole crate so a future security-sensitive record inherits the discipline by default rather than reinventing it. (Note: only `RefreshToken` and `AuthCode` actually need the boundary today; for `Blob` and `RunCatalogEntry` the boundary is "free" — there's nothing sensitive to protect — so the security argument is forward-leaning, not load-bearing right now.)
-
-**Why not (2) `JsonStore`**: removes the JSON duplication but nothing else. Each store still hand-writes its own key construction (so the scan/key-parsing invariants stay scattered), its own consume mutex (so KeyedMutex can't naturally land), and its own atomic-write batch (so the security invariants in R10 stay implicit). Reduction in scaffolding is real, reduction in surface-to-think-about is much smaller than it looks.
-
-**Why not (1) copy-paste**: works fine until two records drift. The first such drift (e.g., one store fixes a key-encoding bug another doesn't) is a class of bug the abstraction prevents structurally.
-
-**Acknowledged speculative scope**: R8 (`BlobStore` public surface), R9 (catalog sweep), and R10's cross-type Tx are all forward-looking. The bet is that paying the setup cost once now is cheaper than retrofitting later. If that bet is wrong, the cost is the LOC delta between (3) and (chosen) plus the ongoing readability cost: a new contributor must learn `Record`/`RecordId`/`Codec`/`Repository`/`Tx`/`KeyedMutex` to add a record, vs. learning one `JsonStore` API; trait-resolution makes "where is this key constructed?" harder to grep; generic error messages reference `::Codec` instead of `JsonCodec`. The per-record LOC numbers in the table above are rough estimates — the actual delta between (2)/(3) and (chosen) for a 5th record is small (single-digit LOC). The primary argument for (chosen) over (3) is consistency-across-records and one-time security-boundary design, not per-record LOC.
-
-## Dependencies / Assumptions
-
-- SlateDB's `WriteBatch` is suitable as the underlying primitive for the `transaction` helper. Already used by `RefreshTokenStore::consume_and_rotate`.
-- The current public consumers of `Database::auth_codes()` / `auth_tokens()` are limited to `fabro-server` and crate-internal tests. The `Slate*Store` type names are referenced in `fabro-server` (`serve.rs:799-829` types `Arc` etc.); renaming to `*Store` is a mechanical import update on the order of one PR for `fabro-server`, not a deep API change.
-
-## Outstanding Questions
-
-### Resolve Before Planning
-
-(none)
-
-### Deferred to Planning
-
-- [Affects R13] [Technical] Whether `KeyedMutex` lives at `lib/crates/fabro-store/src/keyed_mutex.rs` or in a small shared util module. Either is fine.
-- [Affects R5–R9] [Technical] Migration order — which store moves to `Repository` first and in what PR sequence. Suggested order: R13 (`KeyedMutex` extraction, can land first as a precursor PR) → `BlobStore` (greenfield, simplest) → `RunCatalogIndex` (replaces `catalog.rs`) → `AuthCodeStore` → `RefreshTokenStore` (most complex due to consume-and-rotate + replay cache). Planning concern.
-- [Affects R10] [Technical] Whether to add a separate `per_repository_batch` helper for the common single-type case so callers don't pay the cross-record machinery cost when they don't need it. Performance/ergonomics tweak, not a correctness question.
-
-## Next Steps
-
-→ `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md b/docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md
deleted file mode 100644
index 8fba87662..000000000
--- a/docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md
+++ /dev/null
@@ -1,95 +0,0 @@
----
-date: 2026-04-22
-topic: web-install-object-store-choice
----
-
-# Web Install Object Store Choice
-
-## Problem Frame
-
-The browser install wizard currently configures server URL, LLM credentials, and GitHub integration, but it does not let the operator choose where Fabro's object-store-backed data lives. Fabro already supports a local object store and AWS S3 in server configuration, and the runtime model keeps a separate local storage root for host-local state. The missing product behavior is a guided first-run choice for the shared object store used by both SlateDB and artifacts.
-
-Without this step, operators who want S3-backed storage must finish install and then hand-edit server configuration and startup secrets. That creates avoidable setup drift between "works locally" and "production-like" deployments, especially for remote-first installs where the web wizard is supposed to be the primary setup path.
-
-```mermaid
-flowchart TB
- A[Welcome]
- B[Server]
- C[Object store]
- D[LLM]
- E[GitHub]
- F[Review]
- G[Finish]
-
- A --> B --> C --> D --> E --> F --> G
-```
-
-## Requirements
-
-**Wizard flow**
-- R1. The web install wizard must add a new `Object store` step after `Server` and before `LLM`, making the operator-visible order `Welcome → Server → Object store → LLM → GitHub → Review`.
-- R2. The sidebar/progress UI, route flow, back/next behavior, and review screen must treat `Object store` as a first-class step, with refresh/re-entry behavior matching the existing install steps.
-- R3. The wizard must explain that Fabro always keeps a local storage directory on the host and that this step chooses only the shared object store for object-store-backed server data.
-
-**Storage modes**
-- R4. The `Object store` step must offer exactly two wizard-managed modes: `Local disk` and `AWS S3`.
-- R5. Choosing `Local disk` must configure both `server.slatedb` and `server.artifacts` to use the local object store provider.
-- R6. Choosing `Local disk` must not prompt for S3-only fields such as bucket, region, or AWS credentials.
-- R7. Choosing `AWS S3` must configure both `server.slatedb` and `server.artifacts` to use AWS S3, with one shared bucket and separate fixed prefixes so SlateDB data lives under `slatedb/` and artifact data lives under `artifacts/`.
-- R8. The wizard must not expose separate object-store choices for SlateDB and artifacts. Operators who need split backends or more advanced layouts must configure them manually after install.
-- R9. The wizard must not expose S3-compatible endpoint or path-style options in v1. The step must clearly note that non-AWS S3-compatible backends are out of scope for the wizard and require manual configuration.
-
-**S3 fields and credentials**
-- R10. When `AWS S3` is selected, the wizard must collect `bucket` and `region`.
-- R11. The `AWS S3` path must offer exactly two credential modes: `Use AWS runtime credentials` and `Enter AWS access key credentials`.
-- R12. `Use AWS runtime credentials` must be described as the path for deployments where AWS credentials come from the runtime environment or attached role, and it must not prompt for AWS secret material.
-- R13. `Enter AWS access key credentials` must prompt only for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
-- R14. Manual AWS access-key credentials are server-only startup secrets. They must be persisted as server startup env secrets, not as workflow-visible vault secrets.
-- R15. The wizard must not support session-token or STS inputs in v1. Operators who need temporary-session credential flows must configure object-store access manually outside the wizard.
-
-**Validation and review**
-- R16. The `AWS S3` path must perform live validation before the operator can continue past the `Object store` step.
-- R17. Live validation must confirm that the configured bucket, region, chosen credential mode, and fixed `slatedb/` / `artifacts/` prefixes permit Fabro to reach the target S3 bucket with the intended object-store setup.
-- R18. Validation errors must render inline on the `Object store` step and make it clear whether the failure is due to bucket/region mismatch, missing runtime credentials, or invalid manually-entered credentials when that distinction is available.
-- R19. The review step must summarize the chosen object-store mode. For S3, it must show the bucket, region, credential mode, and that Fabro will use the fixed `slatedb/` and `artifacts/` prefixes in the shared bucket without revealing secret values.
-
-## Success Criteria
-- Operators can complete first-run setup for either local object storage or AWS S3 without editing `settings.toml` by hand.
-- An install completed with `Local disk` produces the expected local-provider config for both SlateDB and artifacts.
-- An install completed with `AWS S3` produces the expected shared-bucket S3 config for both SlateDB and artifacts, with `slatedb/` and `artifacts/` prefixes.
-- Manual AWS credentials, when provided, are stored only as server startup secrets and are not exposed in workflow-visible secret surfaces.
-- Misconfigured S3 details are caught during the install wizard instead of surfacing only after install completes and the server restarts.
-
-## Scope Boundaries
-- The local host storage root remains separate and is not replaced by S3.
-- The wizard does not support separate object-store backends for SlateDB and artifacts.
-- The wizard does not support non-AWS S3-compatible backends.
-- The wizard does not support session-token or STS credential inputs.
-- Advanced object-store layouts, custom prefixes beyond the fixed `slatedb/` and `artifacts/`, and other specialized storage topologies remain manual-configuration workflows.
-
-## Key Decisions
-- One shared object-store choice for both SlateDB and artifacts: keeps the wizard simple and avoids first-run misconfiguration.
-- AWS S3 only in the wizard: reduces surface area and avoids exposing endpoint/path-style details meant for manual advanced setups.
-- Two S3 auth paths: ambient runtime credentials for AWS-native deployments, or manually-entered access keys for non-AWS deployments that still target S3.
-- Live validation on the wizard step: catches storage errors before the install succeeds and the server exits.
-- `Object store` comes before provider/integration setup: keeps server-level infrastructure decisions together near the server URL step.
-
-## Dependencies / Assumptions
-- The existing server config model continues to treat `server.storage.root` as host-local storage and `server.slatedb` / `server.artifacts` as separate object-store-backed domains.
-- The runtime continues to initialize S3 access from startup environment credentials or the ambient AWS credential chain.
-- Using one shared S3 bucket with distinct `slatedb/` and `artifacts/` prefixes is sufficient for the wizard-managed path.
-
-## Outstanding Questions
-
-### Resolve Before Planning
-
-(none)
-
-### Deferred to Planning
-- [Affects R16-R18] [Technical] Define the exact validation probe shape for local vs S3 so the install flow checks the real runtime path without creating misleading side effects in the bucket.
-- [Affects R14] [Technical] Confirm the exact persistence path and lifecycle for manual AWS credentials in `server.env`, including whether existing install rollback behavior is sufficient for newly-added AWS env keys.
-- [Affects R19] [Technical] Decide how the review screen and session payload represent the credential mode without leaking secret values and while preserving edit/re-entry behavior.
-
-## Next Steps
-
-→ `/prompts:ce-plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-04-25-cargo-dev-ux-cleanup-requirements.md b/docs/brainstorms/2026-04-25-cargo-dev-ux-cleanup-requirements.md
deleted file mode 100644
index 7871db69d..000000000
--- a/docs/brainstorms/2026-04-25-cargo-dev-ux-cleanup-requirements.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-date: 2026-04-25
-topic: cargo-dev-ux-cleanup
----
-
-# `cargo dev` UX Cleanup
-
-## Problem Frame
-
-`cargo dev` was created in April 2026 to consolidate five shell scripts into one Rust binary, modeled after `uv`'s ergonomics. Six commands shipped:
-
-`docker-build`, `refresh-spa`, `check-spa-budgets`, `generate-cli-reference`, `generate-options-reference`, `release`.
-
-A few rough edges have surfaced now that the surface is in regular use by humans, agents, and CI:
-
-- `refresh-spa` is mandatory before any TypeScript commit, but CI enforces it via a separate `git diff --exit-code` step rather than a first-class check mode. The dirty-check lives in CI YAML, not in the dev tool.
-- `check-spa-budgets` is a sibling command instead of part of the same SPA verification pass, so contributors need to remember two commands to "verify the SPA is shippable."
-- Word order is mixed — `docker-build` is noun-verb, `refresh-spa` and `check-spa-budgets` are verb-noun, the two `generate-*-reference` commands are verb-noun-noun. There is no rule a contributor can apply to guess a command name.
-- `release [nightly]` uses a positional with a single accepted value (`nightly`), reading awkwardly compared with `--nightly`.
-
-This brainstorm captures the rename + consolidation pass to fix word order, fold SPA verification into one command, and switch the release prerelease to a flag.
-
-## Surface Comparison
-
-| Today | After |
-|---|---|
-| `cargo dev docker-build` | `cargo dev docker-build` (unchanged) |
-| `cargo dev refresh-spa` | `cargo dev spa refresh` |
-| `cargo dev check-spa-budgets` + CI `git diff --exit-code` | `cargo dev spa check` (folds both) |
-| `cargo dev generate-cli-reference` | `cargo dev docs refresh` (regenerates both artifacts) |
-| `cargo dev generate-cli-reference --check` | `cargo dev docs check` (verifies both artifacts) |
-| `cargo dev generate-options-reference` | `cargo dev docs refresh` |
-| `cargo dev generate-options-reference --check` | `cargo dev docs check` |
-| `cargo dev release` | `cargo dev release` (unchanged) |
-| `cargo dev release nightly` | `cargo dev release --nightly` |
-| — | `cargo dev spa` prints SPA command help |
-| — | `cargo dev docs` prints docs command help |
-
-## Requirements
-
-### Naming convention
-
-- R1. Adopt noun-verb word order (uv style): the group/subject comes first, the action second. `docker-build` is grandfathered as a single hyphenated noun-verb name because it has no siblings; `release` stays as a single verb because it has no group.
-- R2. Group-only invocation is non-mutating help: `cargo dev spa` prints the SPA subcommand help and exits successfully; `cargo dev docs` prints the docs subcommand help and exits successfully. Mutating commands always require an explicit verb (`refresh`).
-
-### SPA group
-
-- R3. `cargo dev spa refresh` rebuilds the SPA via `bun run build`, verifies the built `dist/` output against the asset budget gate, and only then replaces `lib/crates/fabro-spa/assets/`. On budget violation, it exits non-zero and leaves the committed asset directory untouched. This extends today's `refresh-spa` behavior with the budget gate so contributors can't ship an oversized bundle by accident without creating a dirty tracked tree on failed refresh.
-- R4. `cargo dev spa check` is non-mutating with respect to tracked files: it must not rewrite `lib/crates/fabro-spa/assets/`, and it must leave the tracked working tree unchanged whether it passes or fails. It may use ignored temporary output, but it must clean up any temporary directory it creates. It must fail (non-zero exit) when **either** (a) the SPA bundle in `lib/crates/fabro-spa/assets/` does not match what `bun run build` would produce now (given the current `bun.lock` and source tree), **or** (b) the bundle exceeds asset budgets. This subsumes both today's `check-spa-budgets` and the CI `git diff --exit-code -- lib/crates/fabro-spa/assets` step. The bit-exact comparison relies on `bun run build` being reproducible from a frozen lockfile; CI is the authoritative environment because `bun install --frozen-lockfile` runs there. If a contributor sees a `spa check` failure locally that they can't explain, the resolution is to run `cargo dev spa refresh` and commit the result — CI's `spa check` then arbitrates.
-- R5. Both `.github/workflows/typescript.yml` (Build job) and `.github/workflows/release.yml` (`verify-spa` job, lines 29–31) call `cargo dev spa check` instead of `cargo dev refresh-spa` + `git diff --exit-code -- lib/crates/fabro-spa/assets`. The dirty-check no longer lives in workflow YAML. Both CI workflows must run `bun install --frozen-lockfile` before `cargo dev spa check`; this preserves the TypeScript workflow's existing setup and tightens the release workflow, which currently uses plain `bun install`.
-
-### Docs group
-
-- R6. `cargo dev docs refresh` regenerates both `docs/reference/cli.mdx` and `docs/reference/user-configuration.mdx` in one pass. Replaces the two `generate-*-reference` commands' default mode.
-- R7. `cargo dev docs check` verifies both MDX artifacts are up to date without rewriting them. Replaces the two commands' `--check` mode. Non-zero exit on drift in either file.
-
-### Release
-
-- R8. `cargo dev release` cuts a stable release; `cargo dev release --nightly` cuts a nightly prerelease. The `[nightly]` positional is removed. Other release-mode flags (`--dry-run`, `--skip-tests`, `--release-date`) are unchanged.
-
-### Migration
-
-- R9. Hard cut: the old names (`refresh-spa`, `check-spa-budgets`, `generate-cli-reference`, `generate-options-reference`, `release nightly` positional) are removed in the same PR. No deprecated aliases.
-- R10. All in-repo callers update in the same PR. Scope explicitly includes:
- - CI workflows under `.github/workflows/` (including `nightly.yml`'s `cargo dev release nightly` invocation and `release.yml`'s `verify-spa` job).
- - `AGENTS.md` (including its release-mode usage line that shows `[nightly]`) and `CLAUDE.md`.
- - Any live `docs/` references that show the user-facing command (historical artifacts under `docs/plans/` and `docs/brainstorms/` are left alone).
- - The `lib/crates/fabro-dev/` source crate itself: the subprocess invocation in `src/commands/release.rs` (currently `cargo dev refresh-spa`), `bail!` and help strings inside `src/commands/*.rs` that name the old commands, and integration tests under `tests/it/` that invoke subcommands by name. These must rename in lockstep with the clap subcommand declarations or `cargo nextest run -p fabro-dev` will fail.
-
-## Success Criteria
-
-- `cargo dev --help` lists `docker-build`, `spa`, `docs`, `release` (four entries) with consistent noun-verb naming.
-- A contributor can answer "how do I verify the SPA before pushing?" with one command (`cargo dev spa check`) instead of two plus a `git diff`.
-- CI's TypeScript Build job, the release pipeline's `verify-spa` job, and the docs-reference checks each call exactly one `cargo dev check` command; the workflow YAML no longer contains a `git diff --exit-code` line for SPA assets, and both SPA-checking workflows use `bun install --frozen-lockfile`.
-- `rg "refresh-spa|check-spa-budgets|generate-cli-reference|generate-options-reference|release nightly|release \\[nightly\\]" .github CLAUDE.md AGENTS.md docs/ lib/crates/fabro-dev/ -g '!docs/plans/**' -g '!docs/brainstorms/**'` returns no live references after the PR merges. Historical matches inside `docs/plans/` and `docs/brainstorms/` are acceptable.
-- `cargo nextest run -p fabro-dev` passes after the rename, and no `bail!` or help text inside `lib/crates/fabro-dev/src/` references the removed command names.
-
-## Scope Boundaries
-
-- Out of scope: `cargo dev verify` aggregate command, `cargo dev doctor` environment check, `--json` output for agents, `--watch` mode for `spa refresh`, pre-commit hook installation. These were considered and deferred — worth a separate brainstorm if footgun-reduction proves still painful after this cleanup.
-- Out of scope: any change to what `docker-build` does or its flag surface.
-- Out of scope: extending the release prerelease vocabulary beyond `nightly` (`--prerelease ` style). The single `--nightly` flag is enough for the current need; switch to `--prerelease` if/when a second prerelease kind is introduced.
-
-## Key Decisions
-
-- **Noun-verb word order** (uv style) wins over verb-noun (cargo style). Rationale: `cargo dev` was already modeled after `uv` per docs/plans/2026-04-24-001-refactor-adopt-uv-patterns-plan.md, and the user picked `spa refresh` directly.
-- **One docs command pair, not per-artifact.** `docs refresh` regenerates both MDX files; `docs check` verifies both. Rationale: both regenerations are fast and idempotent, granular targeting has no real use case, and the simpler pair mirrors `spa refresh` / `spa check`.
-- **`spa check` owns both the diff and the budget gate.** Rationale: contributors think of "is the SPA ready to ship?" as one question; splitting it across two commands and a CI YAML step is what produced today's friction.
-- **Group-only commands are help-only.** Rationale: `cargo dev spa` and `cargo dev docs` are easy commands for humans and agents to discover; making them mutate the working tree by default is too easy to trigger accidentally. Explicit verbs keep the command surface predictable.
-- **`spa refresh` also enforces the budget gate before replacing committed assets.** Rationale: a successful refresh that quietly produces an over-budget bundle is a footgun, but a failed refresh should not leave tracked assets dirty. Validate the built output first, then mirror it into `lib/crates/fabro-spa/assets/` only on success.
-- **`spa check`'s bit-exact comparison relies on `bun install --frozen-lockfile`.** Rationale: CI is the authoritative environment because both SPA-checking workflows run `bun install --frozen-lockfile` before `spa check`; locally, contributors run `spa refresh` to make their working tree match what their bun produces, then trust CI's `spa check` to arbitrate cross-machine drift.
-- **Hard cut, no deprecated aliases.** Rationale: the tool is internal-only with all callers in this repo; the user's standing preference is "simplest change, don't care about migration."
-
-## Outstanding Questions
-
-### Resolve Before Planning
-
-(none)
-
-### Deferred to Planning
-
-- [Affects R4][Technical] Implementation strategy for `spa check`'s diff: build into a temporary output directory and compare it against `lib/crates/fabro-spa/assets/`, or rebuild `apps/fabro-web/dist/` and clean it up after comparison. Whichever path is chosen must leave tracked files untouched and must not require a clean working tree outside `lib/crates/fabro-spa/assets/`.
-- [Affects R10][Needs research] Confirm the explicit caller list is exhaustive via `rg "refresh-spa|check-spa-budgets|generate-cli-reference|generate-options-reference|release nightly|release \\[nightly\\]" . -g '!target/**' -g '!docs/plans/**' -g '!docs/brainstorms/**'` immediately before merging.
-
-## Next Steps
-
-→ `/ce:plan` for structured implementation planning
diff --git a/docs/brainstorms/2026-07-21-graph-zoom-lr-increase-requirements.md b/docs/brainstorms/2026-07-21-graph-zoom-lr-increase-requirements.md
deleted file mode 100644
index ba0443d89..000000000
--- a/docs/brainstorms/2026-07-21-graph-zoom-lr-increase-requirements.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# Specification: Increase Maximum Zoom for Left-to-Right Graph View
-
-## Intent Description
-
-Users working with workflow graphs in the left-to-right (LR) orientation currently experience a maximum zoom limit of 200%, which is insufficient for detailed inspection of complex graphs. The top-down (TB) orientation uses the same 200% limit, but the different aspect ratio and layout of TB graphs makes this limit feel more generous in practice. LR graphs, being horizontally oriented, often require higher magnification to read node labels and inspect edges comfortably.
-
-This change increases the maximum zoom ceiling for the LR graph direction to provide parity in perceived usability between the two orientations. The goal is to allow users to zoom in further when viewing LR graphs while maintaining the existing zoom behavior for TB graphs. Additionally, to improve the user experience when switching between orientations, zoom levels are now persisted separately for each direction — when you switch from TB to LR and back, your previous zoom level for each mode is restored.
-
-## Architecture Specification
-
-### Affected Components
-
-**`apps/fabro-web/app/lib/graph-viewport.ts`**
-- Replace the single `GRAPH_MAX_ZOOM` constant (currently 200) with direction-aware zoom limits
-- Export two constants: `GRAPH_MAX_ZOOM_TB = 200` and `GRAPH_MAX_ZOOM_LR = 400` (2x increase from 200%)
-- Update `clampZoom()` to accept an optional direction parameter and apply the appropriate max limit
-- Maintain backward compatibility: when direction is not specified, use the TB limit as the default
-
-**`apps/fabro-web/app/routes/run-overview.tsx`**
-- Thread the active direction (`activeDirection: "LR" | "TB"`) to `clampZoom()` calls
-- Relevant call sites: `fitToWindow()` callback and zoom interactions via `zoomAtPoint()`
-- Pass direction to `zoomAtPoint()` so it can forward it to `clampZoom()`
-- Hold a separate remembered view per direction via `useRememberedGraphView`, keyed `-TB` and `-LR`
-- Restore the appropriate zoom level when switching between TB and LR orientations
-
-**`apps/fabro-web/app/components/graph-toolbar.tsx`**
-- Update zoom button disabled state to use direction-aware max zoom
-- Import both `GRAPH_MAX_ZOOM_TB` and `GRAPH_MAX_ZOOM_LR`
-- Receive `direction` prop and check against the appropriate constant
-
-**`apps/fabro-web/app/lib/graph-viewport.test.ts`**
-- Update test assertions that reference `GRAPH_MAX_ZOOM` to test both TB and LR limits
-- Add test coverage for direction-aware clamping behavior
-
-### Type Signature Changes
-
-```typescript
-// Before
-export const clampZoom = (zoom: number): number
-
-// After
-export const clampZoom = (zoom: number, direction?: "LR" | "TB"): number
-```
-
-```typescript
-// Before
-export function zoomAtPoint(
- view: GraphView,
- factor: number,
- cursor?: { x: number; y: number },
-): GraphView
-
-// After
-export function zoomAtPoint(
- view: GraphView,
- factor: number,
- cursor?: { x: number; y: number },
- direction?: "LR" | "TB",
-): GraphView
-```
-
-### Constraints
-
-- **Backward compatibility**: `clampZoom()` and `zoomAtPoint()` must remain callable without the direction parameter for existing call sites outside the run overview route
-- **Single source of truth**: Zoom limits must be defined as exported constants in `graph-viewport.ts`, not duplicated in component files
-- **No change to TB behavior**: The TB max zoom remains 200%
-- **Minimum zoom unchanged**: `GRAPH_MIN_ZOOM` remains 25% for both directions
-
-## Acceptance Criteria
-
-1. **LR zoom ceiling increased**: When viewing a workflow graph in LR orientation, the user can zoom in to 400% (up from 200%) using toolbar buttons, scroll wheel, or trackpad pinch gestures
-2. **TB zoom ceiling unchanged**: When viewing a workflow graph in TB orientation, the maximum zoom remains 200%
-3. **Toolbar button state**: The zoom-in button is disabled when at the direction-specific maximum (LR or TB), and the zoom-out button is disabled at 25% for both directions
-4. **Fit-to-window respects limits**: The "Fit to window" button clamps the computed zoom to the direction-specific maximum when appropriate
-5. **Zoom persistence per direction**: When switching from TB to LR (or vice versa), the zoom level you previously used for that direction is restored — each direction remembers its own zoom level independently
-6. **Tests pass**: All existing `graph-viewport.test.ts` tests pass, and new tests verify direction-aware clamping behavior
-
-## Ambiguity Log
-
-| Decision | Classification | Resolved By | Rationale / Answer |
-|----------|----------------|-------------|-------------------|
-| What should the new LR maximum zoom be? | requires-stakeholder-input | human | Initially set to 300% (1.5x), but feedback requested increasing it to 400% (2x) for better usability with complex LR graphs. Updated to 400% based on user testing. |
-| Should the zoom limit change be retroactive to existing remembered zoom states? | inferable | Spec author | When a user switches from TB to LR, their remembered zoom state for that run is already stored. Each direction now maintains its own zoom level in a ref, so switching between TB and LR preserves the zoom you used for each mode. The `clampZoom` behavior ensures each direction's zoom stays within its max limit. |
-| Should the minimum zoom (25%) also be direction-aware? | inferable | Spec author | The user request specifically mentions "higher zoom in the overview graph in the left-to-right version" and compares max zoom between orientations. The minimum zoom was not mentioned as a problem. Changing the minimum would be scope creep. Keep `GRAPH_MIN_ZOOM` uniform at 25%. |
-| Should the constants be named `GRAPH_MAX_ZOOM_TB` / `GRAPH_MAX_ZOOM_LR` or use a different naming convention? | inferable | Spec author | The existing constant is `GRAPH_MAX_ZOOM`. The direction-aware version should maintain lexical proximity and clarity. Suffix-based naming (`_TB`, `_LR`) follows the existing `Direction` type values and makes import/usage clear in components. Alternative approaches (e.g., a `MAX_ZOOM_BY_DIRECTION` map) add indirection without benefit. |
-| Should `zoomAtPoint()` accept direction as a parameter or should callers pre-clamp? | inferable | Spec author | `zoomAtPoint()` internally calls `clampZoom()` at line 45. If direction-aware clamping is needed, threading direction through `zoomAtPoint()` avoids forcing every caller to manually clamp before calling. This centralizes the clamping logic and matches the existing function's responsibility. Pre-clamping at call sites would scatter the logic and risk inconsistency. |
-| What happens to the playground canvas zoom (mentioned in graph-viewport.ts comments)? | inferable | Spec author | The comment at line 5-7 of `graph-viewport.ts` notes the playground canvas has its own pan/zoom with discrete steps and could import this module for cursor-anchored zoom. The playground is not mentioned in the user request. The change should not affect the playground unless it explicitly imports and uses the new direction-aware `clampZoom()`. Since it currently uses discrete steps (not the percentage-based system), it remains unaffected. |
-
----
-
-## Cross-Artifact Consistency Gate
-
-- [ ] Intent is unambiguous — two developers would interpret it the same way.
-- [ ] Every behavior/goal in the intent maps to at least one acceptance criterion.
-- [ ] Architecture constrains implementation without over-engineering.
-- [ ] Same concepts named consistently across all three artifacts.
-- [ ] No artifact contradicts another.
-- [ ] Every gap/ambiguity finding is logged — inferable with rationale, or resolved by the human.
diff --git a/docs/ideation/2026-04-02-slatedb-consolidation-ideation.md b/docs/ideation/2026-04-02-slatedb-consolidation-ideation.md
deleted file mode 100644
index 59d683202..000000000
--- a/docs/ideation/2026-04-02-slatedb-consolidation-ideation.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-date: 2026-04-02
-topic: slatedb-consolidation
-focus: Consolidate SlateDB from one-per-run to single instance owned by fabro server, all access via HTTP/Unix socket
----
-
-# Ideation: SlateDB Consolidation Behind Server
-
-## Codebase Context
-
-**Project shape:** Rust workspace (30 crates) + React 19 frontend. AI-powered workflow orchestration platform.
-
-**Current storage architecture:**
-- `fabro-store` crate defines `Store` and `RunStore` async traits with `SlateStore` and `InMemoryStore` impls
-- Each workflow run gets its own SlateDB database (unique `db_prefix` per run)
-- `SlateRunDb` enum distinguishes Writer (`slatedb::Db`) and Reader (`DbReader`)
-- CLI opens SlateDB directly via `build_store()` (~25 call sites)
-- Server also opens SlateDB directly
-- Unix socket binding and server daemon management already implemented
-
-**Key constraints:**
-- SlateDB chosen for "bottomless" S3 storage path — not replaceable with SQLite
-- Greenfield app, not yet deployed — no migration concerns
-- Events-as-source-of-truth migration actively in progress
-- Moving away from SQLite dependency, not toward it
-
-## Ranked Ideas
-
-### 1. Events-First Server Architecture
-**Description:** Make events the sole write path. CLI POSTs events to the server, server materializes all state (run record, node outcomes, checkpoints, etc.) from events via projection. SSE pushes events to subscribers instantly. The Writer/Reader distinction is eliminated. The API is coarser-grained REST shaped by domain needs (POST /runs/{id}/events, GET /runs/{id}/state, GET /runs/{id}/events?stream SSE) — not a 1:1 mirror of the 40-method RunStore trait.
-**Rationale:** Collapses 40 put methods to a single append endpoint. Converges with the events-as-source-of-truth work already in progress. Makes SSE push, Writer/Reader elimination, trait flattening, and in-memory projection all fall out as natural consequences. Both critics called this "the plan."
-**Downsides:** Requires events-as-source-of-truth to be complete enough that all RunStore state is derivable from events. The follow-ups doc lists gaps.
-**Confidence:** 90%
-**Complexity:** High
-**Status:** In Progress
-
-### 2. Auto-Start Server Daemon
-**Description:** When a CLI command needs store access and `fabro.sock` is missing (or unreachable), automatically run `fabro server start` before proceeding. Uses existing daemon management and readiness probe.
-**Rationale:** Without this, every CLI command fails unless the user manually starts the server first. The daemon infrastructure already exists (start.rs has try_connect readiness probe, daemon spawning, flock locking). Auto-start is the difference between smooth DX and broken DX.
-**Downsides:** First command in a session pays ~1-2s startup cost. Edge cases around stale sockets and failed starts.
-**Confidence:** 95%
-**Complexity:** Low
-**Status:** Unexplored
-
-### 3. Thin HTTP Client for CLI
-**Description:** An HTTP-backed `Store`/`RunStore` implementation that connects to the server over Unix socket. With events-first (#1), this is thin — mostly `POST /events`, SSE subscription, and a handful of read endpoints. Replaces the ~25 `build_store()` call sites.
-**Rationale:** The mechanical bridge between CLI and server. The trait boundary is the right seam. `InMemoryStore` tests are completely unaffected.
-**Downsides:** Error handling for server-down scenarios (mitigated by auto-start #2).
-**Confidence:** 95%
-**Complexity:** Medium
-**Status:** Unexplored
-
-## Rejection Summary
-
-| # | Idea | Reason Rejected |
-|---|------|-----------------|
-| 1 | Batch write API | Premature optimization — measure Unix socket latency first |
-| 2 | Run-prefixed key namespace | Implementation detail, falls out of engine design |
-| 3 | Streaming binary assets | YAGNI — no evidence of multi-MB blob problems |
-| 4 | Graceful fallback / offline mode | Fights the architecture — auto-start is the answer |
-| 5 | Connection pooling | Default HTTP client behavior, not a decision |
-| 6 | In-memory projection cache | Redundant with events-first — materialization IS the cache |
-| 7 | Eliminate SlateDB (BTreeMap + WAL) | Building a database; SlateDB provides S3 path |
-| 8 | Auto-generate HTTP client from trait | Contradicts coarser-grained API design |
-| 9 | Lazy-load sequence counters | Micro-optimization; events-first removes the problem |
-| 10 | Kill HTTP; shared SlateDB as IPC | Contradicts architecture; couples to storage internals |
-| 11 | Flip dependency (server in CLI) | Architecturally backwards from stated direction |
-| 12 | Event log as IPC (no HTTP) | Shared file append is fragile; HTTP serializes for free |
-| 13 | Consolidate catalog only | Half-measure creating a third topology |
-| 14 | CLI event-streaming client | Subsumed by events-first |
-| 15 | Time-travel / run replay | Not a consolidation decision; events-first makes it free later |
-| 16 | Multi-workspace fan-in | Feature creep; no current demand |
-| 17 | Reactive web UI via events | Orthogonal frontend concern |
-| 18 | Persistent run queue | Orthogonal scheduler feature |
-| 19 | MCP host for external agents | Orthogonal; fabro-mcp exists |
-| 20 | Tombstone soft delete | Implementation detail of engine |
-| 21 | Intent log for crash recovery | Redundant — event log IS the intent log |
-| 22 | Column families | SlateDB doesn't support them; premature |
-| 23 | Optimistic concurrency control | Single server owns writes — no concurrent writer problem |
-| 24 | Backpressure / write batching | Premature; no write pressure evidence |
-| 25 | SQLite catalog + cross-run queries | Moving away from SQLite dependency; use SlateDB-based index |
-| 26 | Migration command | Greenfield app, not yet deployed |
-| 27 | Consolidate to SQLite | SlateDB provides bottomless S3 storage |
-
-## Session Log
-- 2026-04-02: Initial ideation — 35 candidates generated (6 agents), 6 survived critique, 3 accepted by user (rejected: SQLite catalog, migration command, SQLite as engine)
diff --git a/docs/ideation/2026-04-08-fabro-event-schema-ideation.md b/docs/ideation/2026-04-08-fabro-event-schema-ideation.md
deleted file mode 100644
index d3cb82638..000000000
--- a/docs/ideation/2026-04-08-fabro-event-schema-ideation.md
+++ /dev/null
@@ -1,134 +0,0 @@
----
-date: 2026-04-08
-topic: fabro-event-schema
-focus: greenfield redesign of Fabro's event schemas and streaming contract
----
-
-# Ideation: Fabro Event Schema Redesign
-
-Assumption: greenfield reset. No production deployments, no backward-compatibility constraints, optimize for the best long-term event model rather than incremental migration cost.
-
-These are not ten unrelated features. They are the ten strongest changes to make as one coherent event-platform redesign.
-
-## Codebase Context
-
-- Fabro already has the strongest core envelope in the comparison set: `id`, `ts`, `run_id`, `event`, optional `session_id`, `parent_session_id`, `node_id`, `node_label`, plus `properties`
-- `docs-internal/events-strategy.md` already treats events as the durable audit trail that powers storage, SSE, CLI progress, retro analysis, and JSONL sinks
-- `RunEvent` and `EventBody` already give Fabro a typed internal model, but the public contract is still more convention-driven than schema-first
-- Recent internal plans already push Fabro toward events as source of truth, checkpoint derivation, and simplified `RunEvent`, so the repo is directionally aligned with a stronger event platform
-- The biggest remaining gaps are cross-cutting ones: replay, correlation depth, public schema generation, live-stream semantics, and structured status/error/approval states
-
-## Ranked Ideas
-
-### 1. Split Fabro into two event products: a durable event log and a live UI stream
-**Description:** Define two first-class streams instead of one overloaded one. The durable log contains immutable domain facts suitable for audit, replay, storage, and projections. The live stream contains UI-oriented deltas, snapshots, keep-alives, and fast-changing progress. They share IDs and correlation fields, but they are different contracts.
-**Rationale:** This is the highest-leverage fix. Most competitors get into trouble by mixing audit events, high-frequency streaming deltas, control frames, and reconnect machinery into one schema. Fabro should not. Durable events should be boring and trustworthy. Live events should be optimized for interactivity.
-**Downsides:** Two contracts are more work than one. Emitters must decide whether an event is durable, live-only, or both.
-**Confidence:** 98%
-**Complexity:** High
-**Status:** Recommended
-
-### 2. Add a formal replay and resume contract with ordered cursors and snapshot handshakes
-**Description:** Every run and session stream gets a monotonic `seq` plus a documented resume protocol: subscribe from cursor, receive the latest snapshot if needed, then apply deltas after `seq > cursor`. Define SSE `id` semantics, dedupe rules, replay buffer guarantees, and failure behavior when a client falls too far behind.
-**Rationale:** Goose is the clearest proof that reconnect semantics need to be part of the design, not a side effect. Greenfield Fabro should make "reattach to a long-running workflow" a first-class use case.
-**Downsides:** The server needs replay buffers or snapshot storage, and clients need to implement cursor logic correctly.
-**Confidence:** 96%
-**Complexity:** High
-**Status:** Recommended
-
-### 3. Expand the envelope into a real correlation graph
-**Description:** Keep the existing strong envelope and add the IDs Fabro will actually want long term: `workflow_id`, `branch_id`, `checkpoint_id`, `turn_id`, `message_id`, `tool_call_id`, `request_id`, `causation_id`, and `correlation_id`. Not every event sets every field, but the contract makes those slots explicit.
-**Rationale:** Current Fabro is strong at run/session/node identity, but still thin below that. The next generation of debugging, UI, projection, and analytics work will want to join events by turn, message, tool call, branch, checkpoint, and request without reconstructing those edges from payloads.
-**Downsides:** Emitters and handlers must be stricter about ID ownership and propagation.
-**Confidence:** 95%
-**Complexity:** Medium
-**Status:** Recommended
-
-### 4. Make the public event contract schema-first and generated from one registry
-**Description:** Keep Fabro's `event` + event-specific payload shape, but stop treating the public wire contract as implicit. Generate JSON Schema, TypeScript types, Rust validators, docs, and streaming examples from one source of truth. Every public event family gets an explicit schema version from day one.
-**Rationale:** This is the cleanest fix for drift. Claude Sessions benefits from having a clear public union. OpenCode shows how useful generated event types are. Fabro should combine both while preserving its stronger envelope.
-**Downsides:** Codegen and schema governance add process overhead. Some engineers will fight the discipline.
-**Confidence:** 94%
-**Complexity:** High
-**Status:** Recommended
-
-### 5. Normalize lifecycle grammar across all streamable entities
-**Description:** Standardize event families around a small lifecycle vocabulary: `.started`, `.delta`, `.snapshot`, `.completed`, `.failed`, `.cancelled`, `.interrupted`. Apply it consistently to runs, stages, sessions, turns, messages, tool calls, commands, checkpoints, parallel branches, and retro work where relevant.
-**Rationale:** pi-mono is strongest here. Clients get dramatically simpler when every streamable thing follows the same lifecycle rules instead of bespoke one-off semantics.
-**Downsides:** Some event families will feel slightly unnatural if forced into the same lifecycle vocabulary. Discipline matters.
-**Confidence:** 93%
-**Complexity:** Medium
-**Status:** Recommended
-
-### 6. Replace stringly status and failure fields with explicit tagged unions
-**Description:** Stop representing terminal and waiting states as loosely-typed strings where possible. Add typed unions for `stop_reason`, `retry_status`, `approval_status`, `wait_reason`, `error_kind`, `failure_class`, and `interrupt_reason`. Preserve display strings separately when useful.
-**Rationale:** Claude Sessions gets this exactly right. This is a major quality jump for policy engines, UIs, analytics, and test fixtures. It also reduces accidental schema drift where one code path emits `"timed_out"` and another emits `"timeout"`.
-**Downsides:** More up-front schema design. Adding new states later requires more care.
-**Confidence:** 96%
-**Complexity:** Medium
-**Status:** Recommended
-
-### 7. Introduce typed content blocks and block-level deltas for agent output
-**Description:** Model agent-facing content as typed blocks instead of mostly strings: `text`, `reasoning`, `tool_call`, `tool_result`, `patch`, `file_ref`, `artifact_ref`, `plan`, `todo`, `command_output`, and `summary`. Live deltas target block IDs rather than appending ambiguous raw text.
-**Rationale:** This is the difference between a transcript that only humans can read and one that both humans and tools can reason over. It unlocks richer UIs, selective re-rendering, better retro analysis, and much cleaner summarization and compaction.
-**Downsides:** The model is more complex than "event name plus string payload." Poorly chosen block boundaries can make clients awkward.
-**Confidence:** 92%
-**Complexity:** High
-**Status:** Recommended
-
-### 8. Make human-in-the-loop and control-plane semantics first-class events
-**Description:** Promote approvals, questions, interrupts, resumes, compactions, and operator interventions into explicit event families: `approval.requested`, `approval.responded`, `question.asked`, `question.answered`, `interrupt.requested`, `interrupt.applied`, `resume.required`, `compaction.started`, `compaction.completed`, `compaction.failed`.
-**Rationale:** This is one of the clearest wins from Claude Sessions and OpenCode. Human-in-loop behavior is not edge-case control traffic. It is core workflow state and deserves durable, typed representation.
-**Downsides:** It increases surface area. Some flows that are currently implicit must become explicit state machines.
-**Confidence:** 94%
-**Complexity:** Medium
-**Status:** Recommended
-
-### 9. Add first-class snapshot events for fast attach and projection repair
-**Description:** Introduce self-contained snapshot events such as `run.snapshot`, `session.snapshot`, and `checkpoint.saved` that intentionally duplicate enough state to let clients and projectors reattach without replaying the full history. Treat these as part of the contract, not ad hoc recovery hacks.
-**Rationale:** This complements replay. Durable facts remain append-only, but long-running workflows need efficient recovery points. Greenfield Fabro can design snapshots deliberately instead of letting checkpoint semantics and UI recovery drift apart.
-**Downsides:** Snapshot compaction and retention rules must be explicit or the event system becomes harder to reason about.
-**Confidence:** 90%
-**Complexity:** High
-**Status:** Recommended
-
-### 10. Promote model, tool, and command work into first-class span-style event families
-**Description:** Treat model requests, tool execution, MCP calls, shell commands, and patch application as first-class event families with started/completed/error plus usage, latency, retries, provider, model, routing, approval outcome, and output references. Do not hide these behind generic stage completion summaries.
-**Rationale:** Fabro is an AI workflow product. The event model should expose the actual unit economics and failure surfaces of AI work. This gives better debugging, cost analysis, policy enforcement, and product telemetry than aggregating everything back into stage summaries.
-**Downsides:** More event volume. Care is needed to keep live deltas separate from durable summaries.
-**Confidence:** 93%
-**Complexity:** Medium
-**Status:** Recommended
-
-## What This Adds Up To
-
-If Fabro adopted all ten, the resulting idealized model would look like this:
-
-- one durable event log for facts
-- one live stream for interactive state
-- one shared envelope with strong correlation IDs
-- one generated public schema registry
-- one consistent lifecycle grammar
-- one explicit replay/snapshot story
-- typed blocks and typed states instead of strings and ad hoc payloads
-
-That is materially better than any single comparator repo.
-
-## Rejection Summary
-
-| # | Idea | Reason Rejected |
-|---|------|-----------------|
-| 1 | Keep one stream and just document it better | Not enough — durable and live concerns have different optimization goals |
-| 2 | Flatten all event-specific fields into the top level | Root churn would make the schema worse, not better |
-| 3 | Switch to JSON-RPC-style `method`/`params` notifications | Too transport-shaped for Fabro's broader event-log use case |
-| 4 | Use timestamps alone for replay ordering | Weak contract; reconnect needs explicit sequence semantics |
-| 5 | Eventize binary artifacts and all large blobs directly | Expensive and noisy; use refs/metadata instead |
-| 6 | Keep string errors but standardize message text | Still not machine-readable enough |
-| 7 | Make snapshots the only source of truth | Loses auditability and event-sourced advantages |
-| 8 | Encode every UI concern in the durable log | Durable logs should stay trustworthy and projection-friendly |
-| 9 | Preserve current schema and only add more event names | Misses the deeper contract problems |
-| 10 | Treat approvals and questions as transport-level control traffic | These are product-level workflow semantics and belong in the event model |
-
-## Session Log
-
-- 2026-04-08: Grounded ideation from current Fabro event docs and code, plus comparison against Claude Sessions, Claude Code, Goose, OpenAI Codex, OpenCode, and pi-mono. Survivors intentionally optimized for greenfield quality rather than migration ease.
diff --git a/docs/ideation/2026-04-08-fabro-uninstall-ideation.md b/docs/ideation/2026-04-08-fabro-uninstall-ideation.md
deleted file mode 100644
index 117eed371..000000000
--- a/docs/ideation/2026-04-08-fabro-uninstall-ideation.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-date: 2026-04-08
-topic: fabro-uninstall
-focus: add `fabro uninstall` command — the opposite of install
----
-
-# Ideation: `fabro uninstall` Command
-
-## Codebase Context
-
-- `fabro install` creates `~/.fabro/` with settings.toml, certs/, storage/ (secrets, server state, logs, scratch, store, artifacts), skills/, workflows/, logs/, tmp/
-- `install.sh` modifies shell configs (.zshrc/.bashrc/.config/fish) adding PATH entries with `# fabro` sentinel comment
-- `Home` (fabro-util) and `Storage` (fabro-config) structs are canonical path registries
-- `system prune` provides the established dry-run/--yes/size-reporting UX pattern
-- `server stop` handles graceful SIGTERM→SIGKILL with socket cleanup
-- Binary installed to `~/.fabro/bin/fabro` by install.sh; brew/cargo installs go elsewhere
-
-## Ranked Ideas
-
-### 1. Core Mirror Uninstall
-**Description:** `fabro uninstall` removes `~/.fabro/` entirely, using `Home` and `Storage` structs as the canonical path registry. Compose existing deletion logic rather than writing new teardown code.
-**Rationale:** Home/Storage structs enumerate every path, so future paths added to install automatically appear in uninstall — zero maintenance drift.
-**Downsides:** None significant — table stakes.
-**Confidence:** 95%
-**Complexity:** Low
-**Status:** Unexplored
-
-### 2. Server Shutdown First
-**Description:** Before removing any files, detect a running server and gracefully stop it, reusing `server stop` logic (SIGTERM→SIGKILL). Only then proceed with file deletion.
-**Rationale:** Deleting files under a running server creates orphaned processes, dangling sockets, and corrupt state.
-**Downsides:** None — correctness requirement.
-**Confidence:** 95%
-**Complexity:** Low
-**Status:** Unexplored
-
-### 3. Shell Config Cleanup
-**Description:** Remove PATH lines from `.zshrc`/`.bashrc`/`.config/fish` that `install.sh` added, using the `# fabro` sentinel comment as grep target.
-**Rationale:** Stale PATH entries are the #1 complaint after CLI uninstalls. Sentinel comment makes surgical removal safe.
-**Downsides:** Shell config surgery requires careful testing across shells.
-**Confidence:** 85%
-**Complexity:** Medium
-**Status:** Unexplored
-
-### 4. Dry-Run by Default
-**Description:** Follow `system prune` pattern: list everything that would be removed with sizes, require `--yes` to confirm. Support `--json`.
-**Rationale:** Already proven UX in the codebase. Prevents "oops" moments.
-**Downsides:** None.
-**Confidence:** 95%
-**Complexity:** Low
-**Status:** Unexplored
-
-### 5. Binary Self-Removal
-**Description:** If binary lives inside `~/.fabro/bin/` (install.sh path), delete it as final step. For brew/cargo, print a hint instead.
-**Rationale:** Users expect "uninstall" to mean "gone." Simple conditional based on `current_exe()` path.
-**Downsides:** Self-deleting binary must be last step. Detection heuristic could be wrong if user moved the binary.
-**Confidence:** 75%
-**Complexity:** Low
-**Status:** Unexplored
-
-## Rejection Summary
-
-| # | Idea | Reason Rejected |
-|---|------|-----------------|
-| 1 | Selective component uninstall | YAGNI — users can back up manually |
-| 2 | GitHub App deregistration | Scope creep — remote API during teardown is fragile |
-| 3 | Export before destroy | Gold-plating — `cp -r ~/.fabro` suffices |
-| 4 | Telemetry farewell event | Marginal value, unwelcome phoning home |
-| 5 | Install manifest | Over-engineering for small deterministic footprint |
-| 6 | Per-repo cascade cleanup | Filesystem scanning is slow and presumptuous |
-| 7 | Secure secrets shredding | Security theater on modern SSDs |
-| 8 | Reframe as `system reset` | Poor discoverability |
-| 9 | Doctor extension | Mixing diagnostic and destructive ops |
-| 10 | Install --undo flag | Terrible discoverability |
-| 11 | Teardown facet trait | Premature abstraction for ~5 steps |
-| 12 | Event-sourced uninstall | Requires rewriting install first |
-| 13 | Restoration script | Worse version of export (already cut) |
-| 14 | Server-mediated uninstall | Circular dependency |
-| 15 | Manifest + Selective | Both halves cut |
-| 16 | Doctor-informed uninstall | Coupling for no benefit |
-
-## Session Log
-- 2026-04-08: Initial ideation — ~40 generated across 5 agents, deduped to 22, 5 survived. All 5 accepted as facets of one command. Proceeding to plan.
diff --git a/docs/internal/cargo-target-apfs-churn-plan.md b/docs/internal/cargo-target-apfs-churn-plan.md
deleted file mode 100644
index d72adf33e..000000000
--- a/docs/internal/cargo-target-apfs-churn-plan.md
+++ /dev/null
@@ -1,280 +0,0 @@
-# Reduce Cargo Target APFS Churn Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make day-to-day Cargo builds and cleanup less painful on macOS/APFS by reducing the number and size of debug artifacts written under `target/`.
-
-**Architecture:** Keep the change local to Cargo profile configuration first, because the observed slow path was filesystem metadata deletion in `target/debug/deps`, not Rust compilation logic. Prefer reversible profile tuning over moving build output or disabling incremental compilation until measurements prove those stronger options are needed.
-
-**Tech Stack:** Rust Cargo profiles, macOS/APFS, `cargo clean`, `cargo nextest`, pinned nightly formatting/lint commands.
-
----
-
-## Background
-
-On 2026-04-28, `cargo clean` in this repo spent several minutes deleting `target/debug/deps`. A process sample showed the active work was mostly `unlink(2)`, with smaller time in `lstat` and directory traversal. Activity Monitor reported very low write throughput because this workload is metadata-bound: many small file deletions and APFS journal updates, not large sequential writes.
-
-The repo already has:
-
-```toml
-[profile.dev.package."*"]
-debug = false # Disable debug info for all dependencies
-opt-level = 1 # Shrinks monomorphized generics, reducing test binary size
-```
-
-That reduces dependency debug info, but workspace crates can still emit full debug info. The sampled clippy command included `-C debuginfo=2 -C split-debuginfo=unpacked` for a Fabro crate, which can create more debug artifacts and cleanup work on macOS.
-
-## Proposed First Change
-
-Add lower-debug Cargo profile settings for local dev and tests:
-
-```toml
-[profile.dev]
-debug = "line-tables-only"
-split-debuginfo = "off"
-
-[profile.test]
-debug = "line-tables-only"
-split-debuginfo = "off"
-```
-
-Expected impact:
-
-- Keeps source file and line information for backtraces.
-- Usually keeps breakpoints and source stepping usable.
-- Reduces or removes rich local-variable inspection in `lldb` and IDE debuggers.
-- Reduces debug metadata and split-debug filesystem artifacts.
-- Does not change debug assertions, overflow checks, runtime behavior, or optimization level.
-- Causes one rebuild after the profile settings change.
-
-## Task 1: Baseline Current Target Cost
-
-**Files:**
-- Read: `Cargo.toml`
-- No code changes
-
-- [ ] **Step 1: Confirm no `cargo clean` is running**
-
-Run:
-
-```bash
-ps -axo pid,ppid,stat,etime,pcpu,command | rg -i 'cargo clean' || true
-```
-
-Expected: no active `cargo clean` process, or wait for the existing cleanup to finish.
-
-- [ ] **Step 2: Build the workspace using current settings**
-
-Run:
-
-```bash
-cargo build --workspace
-```
-
-Expected: build succeeds.
-
-- [ ] **Step 3: Record current target size**
-
-Run:
-
-```bash
-du -sh target target/debug target/debug/deps 2>/dev/null
-```
-
-Expected: record the three size values in this file under "Results".
-
-- [ ] **Step 4: Record current entry pressure**
-
-Run:
-
-```bash
-find target/debug/deps -maxdepth 1 -mindepth 1 | wc -l
-```
-
-Expected: record the entry count in this file under "Results".
-
-## Task 2: Apply Lower-Debug Profile Settings
-
-**Files:**
-- Modify: `Cargo.toml`
-
-- [ ] **Step 1: Add profile settings**
-
-Edit `Cargo.toml` so the release profile section is followed by:
-
-```toml
-[profile.dev]
-debug = "line-tables-only"
-split-debuginfo = "off"
-
-[profile.test]
-debug = "line-tables-only"
-split-debuginfo = "off"
-```
-
-Keep the existing dependency-specific dev profile below it:
-
-```toml
-[profile.dev.package."*"]
-debug = false # Disable debug info for all dependencies
-opt-level = 1 # Shrinks monomorphized generics, reducing test binary size
-```
-
-- [ ] **Step 2: Format if Cargo.toml style changes**
-
-No formatter is required for this simple TOML change. Keep comments and spacing consistent with the surrounding file.
-
-## Task 3: Verify Builds and Tests Still Work
-
-**Files:**
-- Read: `Cargo.toml`
-- No additional code changes
-
-- [ ] **Step 1: Build the workspace**
-
-Run:
-
-```bash
-cargo build --workspace
-```
-
-Expected: build succeeds. The first build after changing profile settings may rebuild many crates.
-
-- [ ] **Step 2: Run the core test suite**
-
-Run:
-
-```bash
-cargo nextest run --workspace
-```
-
-Expected: tests pass. If macOS reports `Too many open files (os error 24)`, rerun with:
-
-```bash
-ulimit -n 4096 && cargo nextest run --workspace
-```
-
-- [ ] **Step 3: Run clippy with the pinned nightly toolchain**
-
-Run:
-
-```bash
-cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings
-```
-
-Expected: clippy passes.
-
-## Task 4: Measure Impact
-
-**Files:**
-- Read: `Cargo.toml`
-- Update: this plan's "Results" section
-
-- [ ] **Step 1: Record new target size**
-
-Run:
-
-```bash
-du -sh target target/debug target/debug/deps 2>/dev/null
-```
-
-Expected: compare against Task 1.
-
-- [ ] **Step 2: Record new entry pressure**
-
-Run:
-
-```bash
-find target/debug/deps -maxdepth 1 -mindepth 1 | wc -l
-```
-
-Expected: compare against Task 1. The size reduction may be more meaningful than entry-count reduction, depending on how much split debug info was previously generated.
-
-- [ ] **Step 3: Time a clean operation when convenient**
-
-Run only when a full cleanup is acceptable:
-
-```bash
-time cargo clean
-```
-
-Expected: compare wall-clock time against the prior observed multi-minute cleanup. Activity Monitor may still show low MB/s because deletion remains metadata-bound.
-
-## Task 5: Decide Whether to Stop or Tune Further
-
-**Files:**
-- Modify only if needed: `Cargo.toml`
-- Optional local-only config: `.cargo/config.toml`
-
-- [ ] **Step 1: Stop if the result is acceptable**
-
-If `target/` size and cleanup time are acceptable, keep the lower-debug profile settings and do not add more tuning.
-
-- [ ] **Step 2: Consider disabling incremental only if cleanup is still too costly**
-
-Use this stronger setting only if the cleanup pain still outweighs slower edit-compile cycles:
-
-```toml
-[profile.dev]
-debug = "line-tables-only"
-split-debuginfo = "off"
-incremental = false
-
-[profile.test]
-debug = "line-tables-only"
-split-debuginfo = "off"
-incremental = false
-```
-
-Expected tradeoff: fewer incremental artifacts, but slower repeated local builds.
-
-- [ ] **Step 3: Consider a local target directory only if repo-local `target/` remains disruptive**
-
-For a personal-only setup, use `.cargo/config.toml` if it is intentionally untracked, or a global Cargo config outside the repo:
-
-```toml
-[build]
-target-dir = "/Users/bhelmkamp/.cache/cargo-targets/fabro"
-```
-
-Expected tradeoff: build output is isolated from the repo and easier to exclude from Spotlight/backups, but all developers do not automatically share the same behavior unless the config is committed.
-
-## Rollback
-
-To restore full debug info for normal dev/test builds, remove these settings:
-
-```toml
-[profile.dev]
-debug = "line-tables-only"
-split-debuginfo = "off"
-
-[profile.test]
-debug = "line-tables-only"
-split-debuginfo = "off"
-```
-
-For a one-off debugger session without changing `Cargo.toml`, run:
-
-```bash
-CARGO_PROFILE_DEV_DEBUG=2 CARGO_PROFILE_DEV_SPLIT_DEBUGINFO=unpacked cargo build
-```
-
-## Results
-
-Fill this in when the plan is executed:
-
-```text
-Before:
-- target size:
-- target/debug size:
-- target/debug/deps size:
-- target/debug/deps entries:
-- cargo clean wall-clock time:
-
-After:
-- target size:
-- target/debug size:
-- target/debug/deps size:
-- target/debug/deps entries:
-- cargo clean wall-clock time:
-```
diff --git a/docs/internal/cli-workflow-coupling-audit.md b/docs/internal/cli-workflow-coupling-audit.md
deleted file mode 100644
index 198e658f3..000000000
--- a/docs/internal/cli-workflow-coupling-audit.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# CLI Workflow Coupling Audit
-
-## Scope
-
-- Production imports under `lib/apps/fabro-cli/src/**` that still reference `fabro_workflow::*` after the server-owned selector/export refactor.
-- Test-only imports are listed separately so the remaining architectural debt is explicit.
-
-## Completed In This Change
-
-- Removed the production CLI dependency on `fabro_workflow::run_lookup`.
-- Removed the production CLI dependency on `fabro_workflow::run_dump`.
-- Added server-owned selector resolution via `GET /api/v1/runs/resolve` and migrated single-run selector flows to it.
-- Migrated user-facing fork/rewind timeline inspection and execution to server APIs.
-
-## Remaining Production Couplings
-
-| Path | Direct dependency | Why it still exists | Required remediation track |
-| --- | --- | --- | --- |
-| `lib/apps/fabro-cli/src/commands/pr/create.rs` | `StageOutcome`, `pull_request::maybe_open_pull_request` | CLI still reconstructs store state and runs PR creation logic from the workflow pipeline directly. | Replace with a server API, or extract PR orchestration into a non-engine shared service crate plus API. |
-| `lib/apps/fabro-cli/src/commands/run/runner.rs` | `artifact_snapshot::CapturedArtifactInfo`, `artifact_upload::{ArtifactSink, StageArtifactUploader}`, `event::{Emitter, RunEventSink}`, `operations::{self, StartServices}`, `run_control::RunControlState`, `runtime_store::{RunStoreBackend, RunStoreHandle}` | Hidden worker subprocess path still lives inside the CLI crate and embeds the workflow engine directly. | Re-home worker/runtime code outside the user CLI surface, ideally into a dedicated worker crate or binary. |
-| `lib/apps/fabro-cli/src/manifest_builder.rs` | `git::{GitSyncStatus, head_sha, sync_status}` | Manifest submission still relies on git helper logic that happens to live in `fabro_workflow`. | Extract git-sync inspection helpers into a non-workflow shared crate/module. |
-| `lib/apps/fabro-cli/src/server_client.rs` | `artifact_snapshot::CapturedArtifactInfo` | The upload client reuses a workflow-owned artifact snapshot DTO. | Extract shared artifact snapshot DTOs into `fabro-store`, `fabro-types`, or a dedicated shared crate. |
-| `lib/apps/fabro-cli/src/commands/runs/inspect.rs` | `run_status::RunStatus` | CLI output types still depend on engine-owned run status enums. | Extract shared status types into `fabro-types` or switch to API-generated/public store types. |
-| `lib/apps/fabro-cli/src/commands/runs/list.rs` | `run_status::RunStatus` | List rendering still depends on engine-owned run status enums. | Extract shared status types into `fabro-types` or switch to API-generated/public store types. |
-| `lib/apps/fabro-cli/src/commands/run/attach.rs` | `StageOutcome`, `run_status::RunStatus` | Attach/replay logic still formats engine-owned terminal status types directly. | Extract shared run/conclusion status types into `fabro-types`. |
-| `lib/apps/fabro-cli/src/commands/run/output.rs` | `StageOutcome`, `records::Conclusion` | Human-readable completion output still consumes workflow-owned conclusion/status records. | Extract shared conclusion/status DTOs into `fabro-types` or `fabro-store`. |
-| `lib/apps/fabro-cli/src/commands/run/wait.rs` | `records::Conclusion`, `run_status::RunStatus` | Wait output still depends on workflow-owned status/conclusion records. | Extract shared conclusion/status DTOs into `fabro-types` or `fabro-store`. |
-| `lib/apps/fabro-cli/src/commands/run/run_progress/stage_display.rs` | `StageOutcome`, `format_cost` | Progress UI still depends on shared stage outcome and workflow-owned cost-formatting helper code. | Move formatting helpers into `fabro-util`. |
-| `lib/apps/fabro-cli/src/commands/run/run_progress/info_display.rs` | `event::RunNoticeLevel` | Progress UI still formats workflow-owned notice levels directly. | Extract shared notice/event enums into `fabro-types`. |
-| `lib/apps/fabro-cli/src/commands/run/run_progress/event.rs` | `event::RunNoticeLevel` | Progress event translation still depends on workflow-owned notice levels. | Extract shared notice/event enums into `fabro-types`. |
-
-## Test-Only Couplings
-
-| Path | Direct dependency | Why it still exists | Suggested handling |
-| --- | --- | --- | --- |
-| `lib/apps/fabro-cli/src/commands/dump.rs` test module | `event::{Event, append_event}` | Unit tests synthesize workflow events directly. | Low priority; keep until a lighter-weight event fixture helper exists. |
-| `lib/apps/fabro-cli/src/commands/run/wait.rs` test module | `StageOutcome`, `records::Conclusion`, `run_status::RunStatusRecord` | Output tests construct workflow-owned records directly. | Replace with shared fixture builders once conclusion DTOs move out. |
-| `lib/apps/fabro-cli/src/commands/run/run_progress/mod.rs` test module | `event::{Event, RunNoticeLevel, to_run_event, to_run_event_at}`, `outcome::billed_model_usage_from_llm` | Progress tests build engine events directly. | Replace with shared event fixture helpers after event DTO extraction. |
-| `lib/apps/fabro-cli/src/commands/run/run_progress/event.rs` test module | `event::{Event, to_run_event}` | Event rendering tests depend on engine event constructors. | Replace with shared event fixture helpers after event DTO extraction. |
-| `lib/apps/fabro-cli/src/commands/run/runner.rs` test module | `artifact_upload::StageArtifactUploader` | Worker tests still reach into workflow upload internals. | Keep with worker re-home work; not worth separating first. |
-| `lib/apps/fabro-cli/tests/it/workflow/real_cli.rs` | `context::Context`, `event::Emitter`, `handler::agent::{CodergenBackend, CodergenResult}`, `handler::llm::cli::AgentCliBackend` | Integration test exercises the real workflow engine directly through CLI harnesses. | Accept as engine integration coverage or move under workflow-owned test support later. |
-| `lib/apps/fabro-cli/tests/it/scenario/recovery.rs` | `operations::{RunTimeline, build_timeline}` | Scenario test inspects rewind timeline internals directly. | Replace after server-owned rewind/timeline APIs exist. |
-
-## Follow-Up Order
-
-1. Design a server API for PR creation so user-facing CLI commands stop importing workflow PR operations directly.
-2. Decide whether the hidden worker path should move to a dedicated worker crate/binary or remain a CLI-internal implementation detail with a stricter boundary.
-3. Extract shared status, conclusion, notice, and artifact snapshot types/helpers out of `fabro_workflow`.
-4. Extract git sync helpers from `fabro_workflow` so manifest building no longer depends on engine code.
diff --git a/docs/internal/event-schema-competitive-analysis.md b/docs/internal/event-schema-competitive-analysis.md
deleted file mode 100644
index f142e4183..000000000
--- a/docs/internal/event-schema-competitive-analysis.md
+++ /dev/null
@@ -1,376 +0,0 @@
-# Event Schema Competitive Analysis
-
-Date: 2026-04-08
-
-This report compares the event schemas used by:
-
-- Claude Sessions API
-- Claude Code
-- Goose
-- OpenAI Codex
-- OpenCode
-- pi-mono
-
-Goal: identify patterns Fabro should copy, avoid, or formalize more clearly.
-
-## Executive Summary
-
-Fabro's current event model is already ahead of most of the field on one important point: it has a canonical envelope with stable metadata (`id`, `ts`, `run_id`, `event`, optional `session_id`, `parent_session_id`, `node_id`, `node_label`) and a typed internal-to-external mapping.
-
-The biggest improvement opportunities are not "more events." They are:
-
-1. Keep transport concerns separate from domain events, but document them as part of the contract.
-2. Make every streamed event part of one explicit public schema. Avoid opaque blobs and server-injected fields that the schema does not admit.
-3. Add more first-class correlation fields where the UI or downstream systems need them, especially `turn_id`, `message_id`, `tool_call_id`, `request_id`, and retry/attempt IDs.
-4. Make retry, stop, idle, and requires-action states machine-readable unions instead of loose strings.
-5. Be explicit about delta vs snapshot semantics and replay behavior.
-
-## Fabro Baseline
-
-Fabro's current strategy is documented in `docs-internal/events-strategy.md`. The canonical external shape is:
-
-```json
-{
- "id": "uuidv7",
- "ts": "2026-03-30T12:00:01.000Z",
- "run_id": "01JQ...",
- "event": "agent.tool.started",
- "session_id": "ses_child",
- "parent_session_id": "ses_parent",
- "node_id": "code",
- "node_label": "Code",
- "properties": { "...": "..." }
-}
-```
-
-That envelope is stronger than most comparator systems. It gives Fabro stable top-level metadata, keeps event-specific data inside `properties`, and avoids flattening arbitrary fields into the root.
-
-Relevant current Fabro sources:
-
-- `docs-internal/events-strategy.md`
-- `lib/components/fabro-workflow/src/event.rs`
-- `lib/foundation/fabro-types/src/run_event/mod.rs`
-- pebble's `CodingEvent` (`pebble-coding-agent`, re-exported from `fabro_types`)
-
-## Comparison Matrix
-
-| System | Public event surface | Discriminator | Universal envelope fields on every event | Replay / ordering story | Main strength | Main weakness |
-| --- | --- | --- | --- | --- | --- | --- |
-| Claude Sessions | 20-event public union | `type` | `id`, `processed_at` | Event IDs exist; replay semantics are not part of the event payload | Very explicit, stable union with typed nested states | Less transport detail and fewer workflow-specific events |
-| Claude Code | 24 core SDK messages, 31 stdout/control variants | `type`, often `subtype` | Usually `uuid`, `session_id`; no universal timestamp | Streaming is batched/coalesced; control and domain share the same channel | Rich task, hook, status, and tool progress | Nested stream payload is opaque at runtime; control and data are mixed |
-| Goose | 7 `MessageEvent` variants | `type` | None in JSON payload; SSE `id` is outside payload | Strong SSE replay via monotonic seq + `Last-Event-ID` + replay buffer | Reattach/replay semantics are clear | Transport fields are injected outside schema; payload typing is shallow |
-| Codex SDK | 8 thread events | `type` | No universal ID/timestamp | Ordered stream, no replay contract in payload | Very simple client model | Too minimal for rich UIs and analytics |
-| Codex app-server | 49 notification methods | `method` + `params` | No universal ID/timestamp in params | Ordered notifications, no seq/replay field | Richest low-level protocol in the set | Fragmented event story; transport shape leaks into the schema |
-| OpenCode | 45 generated event variants | `type` + `properties` | No universal ID/timestamp | Plain SSE; client supports SSE IDs but server does not emit them | Broadest app/runtime event coverage | Wire/schema drift and no universal envelope |
-| pi-mono | 12 assistant stream events, 10 agent events, 14 session events | `type` | Session header only; not per event | JSONL stream, no replay contract | Excellent streaming lifecycle grammar | No durable universal envelope for downstream consumers |
-
-## System Notes
-
-### Claude Sessions
-
-What it does well:
-
-- One explicit public union.
-- Every event has `id`, `type`, and `processed_at`.
-- Tool confirmation, custom tool results, MCP tool use, session errors, session status, and model-span events are all first-class.
-- Terminal and waiting states are structured. `session.status_idle.stop_reason` is not a loose string; it is a small union.
-- Error reporting is structured. `session.error.error` is a tagged union, not just a message.
-
-Why it matters for Fabro:
-
-- This is the cleanest example of a public agent-session event API that is still small enough to understand.
-- The main idea to copy is not the exact event list. It is the discipline: explicit tagged unions for stop reasons, errors, and status transitions.
-
-Sources:
-
-- `https://platform.claude.com/docs/en/api/beta/sessions/events/stream`
-- `https://platform.claude.com/docs/specs/merged.53db30dfcc06f431.json.gz`
-
-### Claude Code
-
-Schema shape:
-
-- `SDKMessageSchema` contains 24 core message variants.
-- `StdoutMessageSchema` expands the stdout protocol to 31 variants once control messages and keep-alives are included.
-- Many events use `type: "system"` plus a `subtype`, for example `init`, `status`, `api_retry`, `hook_started`, `task_progress`, and `session_state_changed`.
-- Streaming assistant output is wrapped as `type: "stream_event"`.
-
-What it does well:
-
-- It covers more than just model output: task lifecycle, hook lifecycle, compaction boundaries, retries, authentication state, file persistence, tool progress, prompt suggestions.
-- It carries `uuid` and `session_id` widely, which is useful for correlation.
-- It includes explicit session-state transitions (`idle`, `running`, `requires_action`).
-
-What is weak:
-
-- The nested streaming payload is not explicitly validated at runtime. `RawMessageStreamEventPlaceholder` is `z.unknown()`.
-- Control protocol messages live in the same stream as domain messages.
-- `type: "system"` plus `subtype` is workable, but less ergonomic than a flatter public union.
-- There is no universal top-level timestamp on every event.
-
-Why it matters for Fabro:
-
-- Copy the breadth, not the shape.
-- Avoid opaque inner payloads in public schemas.
-- Avoid mixing keep-alive/control/config traffic into the same schema that product consumers use for analytics and UI rendering.
-
-Sources:
-
-- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/entrypoints/sdk/coreSchemas.ts`
-- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/entrypoints/sdk/controlSchemas.ts`
-- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/remote/sdkMessageAdapter.ts`
-- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/cli/transports/ccrClient.ts`
-- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/utils/sdkEventQueue.ts`
-
-### Goose
-
-Schema shape:
-
-- One small SSE payload union: `Message`, `Error`, `Finish`, `Notification`, `UpdateConversation`, `ActiveRequests`, `Ping`.
-- SSE `id:` carries a monotonic sequence number.
-- Session replay uses `Last-Event-ID` plus a replay buffer.
-- `request_id` and `chat_request_id` are injected at the SSE framing layer, not modeled in the payload type.
-
-What it does well:
-
-- Clear reattach story.
-- Monotonic sequence numbers are transport-level, not payload-level.
-- `ActiveRequests` lets the client discover in-flight work when reconnecting.
-
-What is weak:
-
-- The public event payload omits fields the client actually consumes.
-- `Notification.message` is effectively an untyped object.
-- The session stream also emits comment heartbeats outside the schema, and there is a separate `Ping` payload variant in the shared enum. That split is easy to drift.
-
-Why it matters for Fabro:
-
-- Goose is the best example here for replay and reconnect semantics.
-- The lesson is not "put sequence numbers in the payload." The lesson is "formalize replay outside the payload, and do not rely on undocumented injected fields."
-
-Sources:
-
-- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/routes/reply.rs`
-- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/routes/session_events.rs`
-- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/session_event_bus.rs`
-- `/Users/bhelmkamp/p/block/goose/ui/desktop/openapi.json`
-- `/Users/bhelmkamp/p/block/goose/ui/desktop/src/hooks/useSessionEvents.ts`
-
-### OpenAI Codex
-
-There are really two event systems:
-
-1. The TypeScript SDK `ThreadEvent` surface.
-2. The app-server `ServerNotification` protocol.
-
-SDK shape:
-
-- 8 high-level events: thread started, turn started/completed/failed, item started/updated/completed, fatal stream error.
-- Rich detail is pushed down into `ThreadItem`, which includes `agent_message`, `reasoning`, `command_execution`, `file_change`, `mcp_tool_call`, `web_search`, `todo_list`, and `error`.
-
-App-server shape:
-
-- 49 server notification methods.
-- Notifications are discriminated by `method`, with a typed `params` object.
-- Coverage includes thread lifecycle, turn lifecycle, item lifecycle, deltas, token usage, command output, MCP progress, model reroutes, config warnings, and experimental realtime notifications.
-
-What it does well:
-
-- Good separation of a simple developer-facing SDK from a richer system protocol.
-- The low-level protocol is broad and explicit.
-- Experimental notifications are clearly labeled as experimental.
-
-What is weak:
-
-- The event story is fragmented. "Which schema should I build against?" depends on which integration layer you pick.
-- There is no universal timestamp or universal event ID in the event bodies.
-- `method` + `params` is transport-shaped. It works well for JSON-RPC, but it is not as clean as a transport-agnostic event envelope.
-
-Why it matters for Fabro:
-
-- If Fabro needs both a high-level SDK and a low-level protocol, document the layering explicitly.
-- If Fabro only needs one event stream, a single canonical envelope is simpler than method-shaped notifications.
-
-Sources:
-
-- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/events.ts`
-- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/items.ts`
-- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/thread.ts`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/ServerNotification.ts`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/src/protocol/common.rs`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartedNotification.ts`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnCompletedNotification.ts`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/AgentMessageDeltaNotification.ts`
-- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/CommandExecOutputDeltaNotification.ts`
-
-### OpenCode
-
-Schema shape:
-
-- One generated `Event` union with 45 variants.
-- `GlobalEvent` adds `directory` plus `payload: Event`.
-- Events use `type` plus a `properties` object.
-- Coverage includes questions, permissions, messages, message parts, session status/idle/compacted/error/diff, workspace readiness, PTYs, worktrees, VCS, file edits, MCP, TUI commands, and more.
-
-What it does well:
-
-- Broad coverage.
-- Generated API types from the server surface.
-- Clear split between session-scoped events and global events.
-- Status is partly structured. `SessionStatus` is a union of `idle`, `retry`, and `busy`.
-
-What is weak:
-
-- No universal event ID.
-- No universal timestamp.
-- No replay cursor or sequence field.
-- The wire stream emits `server.heartbeat`, but the generated `Event` union does not include it.
-- The global event schema says `directory` is present, but the initial global `server.connected` and heartbeat frames omit it.
-
-Why it matters for Fabro:
-
-- OpenCode shows how far a generated event surface can go.
-- It also shows the cost of not having a canonical envelope: clients must reconstruct correlation from nested `sessionID`, `messageID`, `partID`, and route-specific wrappers.
-
-Sources:
-
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/sdk/js/src/v2/gen/types.gen.ts`
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/sdk/js/src/v2/gen/core/serverSentEvents.gen.ts`
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/server.ts`
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/routes/global.ts`
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/event.ts`
-- `/Users/bhelmkamp/p/anomalyco/opencode/packages/web/src/content/docs/server.mdx`
-
-### pi-mono
-
-Schema shape:
-
-- `AssistantMessageEvent` has 12 streaming variants: `start`, block start/delta/end for text, thinking, and tool calls, then `done` or `error`.
-- `AgentEvent` has 10 lifecycle variants across agent, turn, message, and tool execution.
-- `AgentSessionEvent` extends `AgentEvent` with 4 session-only retry/compaction events.
-- JSON mode starts with a session header, then emits JSONL events.
-
-What it does well:
-
-- Excellent streaming lifecycle grammar.
-- Strong layering:
- - low-level assistant stream events
- - mid-level agent lifecycle events
- - high-level session events
-- The proxy mode has a bandwidth-optimized streaming shape that intentionally strips partial message snapshots and reconstructs them client-side.
-
-What is weak:
-
-- There is no universal per-event envelope.
-- There are no event IDs or replay semantics.
-- Timestamping is inconsistent. The session header has a timestamp, and some embedded message objects have timestamps, but not every event line does.
-
-Why it matters for Fabro:
-
-- pi-mono is the best example here for event layering and start/delta/end/done grammar.
-- Fabro should borrow that lifecycle discipline if it expands live agent streaming, but keep Fabro's stronger envelope.
-
-Sources:
-
-- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/ai/src/types.ts`
-- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/agent/src/types.ts`
-- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/agent/src/proxy.ts`
-- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/coding-agent/src/core/agent-session.ts`
-- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/coding-agent/docs/json.md`
-
-## Cross-System Patterns
-
-### Patterns worth copying
-
-- One obvious discriminator per public event.
-- Explicit unions for error state, stop reason, retry state, and requires-action state.
-- Stable correlation IDs for session/thread/turn/message/tool levels.
-- A documented replay story for long-running streams.
-- Generated public schemas from one source of truth.
-- A clear distinction between snapshot events and delta events.
-
-### Patterns worth avoiding
-
-- Opaque `unknown` payloads inside otherwise typed events.
-- Server-injected fields that the public schema does not model.
-- Mixing keep-alives, control RPCs, and domain events in one event contract.
-- Event systems that only make sense in the context of one transport, for example JSON-RPC `method`/`params`, when the real need is a transport-agnostic event log.
-- No universal ID or timestamp on durable events.
-
-## Recommendations For Fabro
-
-### 1. Keep the canonical envelope
-
-Fabro should keep `id`, `ts`, `run_id`, `event`, `session_id`, `parent_session_id`, `node_id`, and `node_label` exactly as the backbone of the public schema. That is already better than every comparator except Claude Sessions on consistency.
-
-### 2. Do not let transport metadata leak informally
-
-If Fabro supports SSE replay or live reattach, define transport rules explicitly:
-
-- SSE `id`
-- replay cursor semantics
-- comment heartbeat vs payload heartbeat
-- reconnect guarantees
-
-Do not make clients depend on extra fields injected by one server path that are absent from the formal schema.
-
-### 3. Add deeper correlation IDs where the product needs them
-
-Fabro already has run/session/node metadata. The next likely additions are:
-
-- `turn_id`
-- `message_id`
-- `tool_call_id`
-- `request_id`
-- `attempt`
-
-Those should be explicit schema fields, not encoded into ad hoc strings.
-
-### 4. Prefer unions over stringly terminal state
-
-If Fabro expands live session or agent events, model terminal and waiting states like Claude Sessions does:
-
-- `stop_reason`
-- `retry_status`
-- `requires_action`
-- `error_kind`
-
-Avoid free-form strings when a small tagged union will do.
-
-### 5. Standardize lifecycle families
-
-If Fabro emits live agent output, choose one lifecycle grammar and document it:
-
-- `.started`
-- `.delta`
-- `.completed`
-- `.failed`
-
-If snapshot replacement events also exist, mark them clearly and document when clients should treat them as authoritative replacement vs append-only updates.
-
-### 6. Keep domain events separate from control and keep-alive traffic
-
-Claude Code shows the downside of multiplexing control requests, control responses, keep-alives, and domain messages in one stream contract. Fabro's durable run events should stay product-facing and analyzable.
-
-### 7. Add schema-drift tests for streamed events
-
-OpenCode and Goose both show how easy it is for the wire stream to diverge from the published schema. Fabro should keep tests that validate:
-
-- every emitted streamed payload is representable by the public schema
-- no consumer-visible fields are injected outside the schema
-- replay/heartbeat frames are documented and tested separately
-
-## Bottom Line
-
-Fabro does not need to copy any one competitor's schema wholesale.
-
-The best composite design is:
-
-- Claude Sessions' explicit unions for status and errors
-- Goose's replay semantics
-- Codex's separation between a simple high-level client view and a richer low-level view, if Fabro ever needs both
-- OpenCode's breadth of runtime events
-- pi-mono's streaming lifecycle grammar
-- Fabro's existing canonical envelope as the foundation
-
-That combination would produce an event model that is both durable and ergonomic: good for live UI streaming, replay, analytics, tests, and long-term compatibility.
diff --git a/docs/internal/fabro-event-schema-v2-proposal.md b/docs/internal/fabro-event-schema-v2-proposal.md
deleted file mode 100644
index 0ce5f9bd1..000000000
--- a/docs/internal/fabro-event-schema-v2-proposal.md
+++ /dev/null
@@ -1,632 +0,0 @@
-# Fabro Event Schema V2 Proposal
-
-Date: 2026-04-08
-
-Status: proposal
-
-Assumptions:
-
-- greenfield redesign
-- no production deployments
-- no backward-compatibility constraints
-- optimize for the best long-term public event contract
-
-This proposal turns the earlier ideation into concrete schema changes.
-
-## Design Goal
-
-Fabro should expose:
-
-1. a durable, append-only event log for audit, storage, replay, and projections
-2. a separate live stream for UI-oriented snapshots, deltas, and fast progress
-
-They should share IDs and correlation fields, but they should not be the same contract.
-
-## Top 10 Concrete Improvements
-
-### 1. Split the single event story into two concrete public APIs
-
-#### Proposal
-
-Introduce two top-level event contracts:
-
-- `DurableEvent`
-- `LiveEvent`
-
-Endpoints:
-
-- `GET /runs/:run_id/events`
- - append-only durable events
- - replayable
- - no keep-alive payload events
-- `GET /runs/:run_id/live`
- - live UI stream
- - snapshots + deltas + keep-alives
- - resumable with cursor
-
-#### Durable event shape
-
-```json
-{
- "kind": "durable",
- "id": "evt_01960d0c...",
- "seq": 182,
- "ts": "2026-04-08T15:01:02.123Z",
- "run_id": "run_01JQ...",
- "event": "agent.tool.started",
- "session_id": "ses_123",
- "node_id": "code",
- "properties": {
- "tool_call_id": "tool_abc",
- "tool_name": "read_file",
- "arguments": { "path": "src/main.rs" }
- }
-}
-```
-
-#### Live event shape
-
-```json
-{
- "kind": "live",
- "id": "levt_01960d0d...",
- "seq": 991,
- "ts": "2026-04-08T15:01:03.000Z",
- "run_id": "run_01JQ...",
- "event": "message.delta",
- "session_id": "ses_123",
- "message_id": "msg_456",
- "part_id": "part_1",
- "properties": {
- "block_type": "text",
- "delta": "Let me check that file..."
- }
-}
-```
-
-#### Why this is better
-
-- Durable events stay stable and analyzable.
-- Live events can be noisy and UI-oriented without polluting projections.
-- Keeps Fabro from repeating the Claude Code / OpenCode problem of mixing control, transport, and product semantics.
-
-### 2. Add explicit stream ordering, replay, and recovery semantics
-
-#### Proposal
-
-Every durable and live stream event gets:
-
-- `seq: u64`
-- SSE `id:` = `seq`
-- replay semantics based on `Last-Event-ID`
-
-Server rules:
-
-- if `Last-Event-ID` is present and still buffered, replay `seq > cursor`
-- if cursor is too old, return a structured reset event in live streams and `409 replay_reset_required` in durable streams
-- durable streams never emit synthetic snapshots
-- live streams may start with a `*.snapshot` event after reconnect
-
-#### New live-only events
-
-- `stream.heartbeat`
-- `run.snapshot`
-- `session.snapshot`
-- `node.snapshot`
-- `stream.reset_required`
-
-#### Example `stream.reset_required`
-
-```json
-{
- "kind": "live",
- "id": "levt_01960d0e...",
- "seq": 1200,
- "ts": "2026-04-08T15:02:00.000Z",
- "run_id": "run_01JQ...",
- "event": "stream.reset_required",
- "properties": {
- "reason": "cursor_too_old",
- "expected_from_seq": 1170
- }
-}
-```
-
-#### Why this is better
-
-- Reattach behavior becomes deterministic.
-- Clients no longer guess whether they missed data.
-- Replay is part of the contract, not an implementation detail.
-
-### 3. Expand the envelope into a first-class correlation model
-
-#### Proposal
-
-Extend the shared envelope with these optional fields:
-
-- `workflow_id`
-- `stage_id`
-- `branch_id`
-- `checkpoint_id`
-- `session_id`
-- `parent_session_id`
-- `turn_id`
-- `message_id`
-- `part_id`
-- `tool_call_id`
-- `request_id`
-- `causation_id`
-- `correlation_id`
-
-Rules:
-
-- `id` is the event's own identity
-- `causation_id` points to the immediate triggering event, if any
-- `correlation_id` groups a whole logical operation, for example one user request or one retry attempt tree
-- `request_id` is transport/API request scoped, not workflow scoped
-
-#### Concrete change
-
-Move these IDs out of ad hoc `properties` payloads when they are structural identifiers.
-
-Good:
-
-```json
-{
- "event": "agent.tool.completed",
- "tool_call_id": "tool_abc",
- "message_id": "msg_456",
- "properties": {
- "tool_name": "read_file",
- "is_error": false
- }
-}
-```
-
-Bad:
-
-```json
-{
- "event": "agent.tool.completed",
- "properties": {
- "tool_call_id": "tool_abc",
- "message_id": "msg_456",
- "tool_name": "read_file"
- }
-}
-```
-
-#### Why this is better
-
-- Correlation becomes universal instead of event-family-specific.
-- UI and analytics consumers can join without parsing `properties`.
-- Parent/child agent and retry trees become much easier to reason about.
-
-### 4. Replace stringly state with concrete tagged unions
-
-#### Proposal
-
-Define explicit union types for stateful fields.
-
-Examples:
-
-```ts
-type StopReason =
- | { type: "completed" }
- | { type: "requires_input"; request_id: string }
- | { type: "interrupted"; interrupt_reason: InterruptReason }
- | { type: "failed"; error_kind: ErrorKind }
- | { type: "retries_exhausted"; attempts: number };
-
-type RetryStatus =
- | { type: "not_retrying" }
- | { type: "retry_scheduled"; attempt: number; next_retry_at: string }
- | { type: "retrying"; attempt: number }
- | { type: "retries_exhausted"; attempts: number };
-
-type ApprovalStatus =
- | { type: "not_required" }
- | { type: "requested"; approval_id: string }
- | { type: "approved"; approval_id: string; actor: string }
- | { type: "denied"; approval_id: string; actor: string; reason?: string };
-```
-
-#### Concrete fields to replace
-
-- `status`
-- `reason`
-- `failure_class`
-- `interrupt_reason`
-- `stop_reason`
-- `approval_status`
-
-#### Why this is better
-
-- Eliminates string drift.
-- Makes reducers and policy engines much safer.
-- Makes test fixtures much more stable.
-
-### 5. Standardize event family grammar across the entire product
-
-#### Proposal
-
-Use one lifecycle vocabulary:
-
-- `.created`
-- `.started`
-- `.snapshot`
-- `.delta`
-- `.updated`
-- `.completed`
-- `.failed`
-- `.cancelled`
-- `.interrupted`
-- `.deleted`
-
-Apply it consistently to the same kinds of things:
-
-- `run.*`
-- `stage.*`
-- `session.*`
-- `turn.*`
-- `message.*`
-- `message.part.*`
-- `tool.*`
-- `command.*`
-- `checkpoint.*`
-- `parallel.branch.*`
-- `retro.*`
-
-#### Concrete renames
-
-Current style is already decent, but V2 should be stricter.
-
-Examples:
-
-- `agent.text.delta` -> `message.part.delta`
-- `agent.tool.output.delta` -> `tool.output.delta`
-- `agent.processing.end` -> `turn.completed` or `session.idle`, depending on actual semantics
-
-#### Why this is better
-
-- Consumers can infer behavior from naming alone.
-- Reduces one-off event families that encode bespoke lifecycle semantics.
-
-### 6. Introduce typed content blocks and block-level deltas
-
-#### Proposal
-
-Represent streamable content as typed message parts.
-
-Base union:
-
-```ts
-type MessagePart =
- | { type: "text"; part_id: string; text: string }
- | { type: "reasoning"; part_id: string; text: string }
- | { type: "tool_call"; part_id: string; tool_call_id: string; tool_name: string; input: unknown }
- | { type: "tool_result"; part_id: string; tool_call_id: string; output: unknown; is_error: boolean }
- | { type: "patch"; part_id: string; patch_ref: string }
- | { type: "file_ref"; part_id: string; file_id: string; path: string }
- | { type: "artifact_ref"; part_id: string; artifact_id: string; label: string }
- | { type: "plan"; part_id: string; items: PlanItem[] }
- | { type: "todo"; part_id: string; items: TodoItem[] }
- | { type: "command_output"; part_id: string; command_id: string; stream: "stdout" | "stderr"; text: string };
-```
-
-Live delta event:
-
-```json
-{
- "event": "message.part.delta",
- "message_id": "msg_456",
- "part_id": "part_1",
- "properties": {
- "part_type": "text",
- "delta": "checking src/main.rs"
- }
-}
-```
-
-Durable completion event:
-
-```json
-{
- "event": "message.completed",
- "message_id": "msg_456",
- "properties": {
- "parts": [
- { "type": "text", "part_id": "part_1", "text": "checking src/main.rs" }
- ]
- }
-}
-```
-
-#### Why this is better
-
-- Supports rich UI without reparsing free-form text.
-- Supports structured summarization, compaction, and retro generation.
-- Aligns Fabro with the best parts of Claude Sessions and pi-mono.
-
-### 7. Make approvals, questions, and operator interventions first-class durable events
-
-#### Proposal
-
-Add explicit event families:
-
-- `approval.requested`
-- `approval.responded`
-- `question.asked`
-- `question.answered`
-- `interrupt.requested`
-- `interrupt.applied`
-- `resume.required`
-- `resume.applied`
-
-#### Example `approval.requested`
-
-```json
-{
- "kind": "durable",
- "id": "evt_01960d0f...",
- "seq": 201,
- "ts": "2026-04-08T15:03:00.000Z",
- "run_id": "run_01JQ...",
- "session_id": "ses_123",
- "tool_call_id": "tool_abc",
- "event": "approval.requested",
- "properties": {
- "approval_id": "apr_1",
- "scope": "tool_call",
- "tool_name": "exec_command",
- "request": {
- "cmd": "git push origin branch"
- }
- }
-}
-```
-
-#### Example `approval.responded`
-
-```json
-{
- "kind": "durable",
- "id": "evt_01960d10...",
- "seq": 202,
- "ts": "2026-04-08T15:03:10.000Z",
- "run_id": "run_01JQ...",
- "event": "approval.responded",
- "properties": {
- "approval_id": "apr_1",
- "result": {
- "type": "approved",
- "actor": "user"
- }
- }
-}
-```
-
-#### Why this is better
-
-- Human-in-loop behavior becomes queryable and replayable.
-- Workflow interruption is no longer hidden in transport or UI state.
-
-### 8. Add real snapshot events instead of relying on ad hoc reconstruction
-
-#### Proposal
-
-Define explicit snapshot events for live attach and projection recovery:
-
-- `run.snapshot`
-- `session.snapshot`
-- `node.snapshot`
-- `checkpoint.saved`
-
-#### Example `session.snapshot`
-
-```json
-{
- "kind": "live",
- "id": "levt_01960d11...",
- "seq": 1500,
- "ts": "2026-04-08T15:04:00.000Z",
- "run_id": "run_01JQ...",
- "session_id": "ses_123",
- "event": "session.snapshot",
- "properties": {
- "state": { "type": "running" },
- "turn_id": "turn_9",
- "messages": [
- {
- "message_id": "msg_456",
- "role": "assistant",
- "parts": [
- { "type": "text", "part_id": "part_1", "text": "checking src/main.rs" }
- ]
- }
- ],
- "active_tool_calls": [
- {
- "tool_call_id": "tool_abc",
- "tool_name": "read_file",
- "status": "running"
- }
- ]
- }
-}
-```
-
-#### Concrete rule
-
-- snapshots are authoritative replacement state for live consumers
-- snapshots are optional in durable streams
-- checkpoints are durable domain snapshots, not just UI snapshots
-
-#### Why this is better
-
-- Fast attach becomes trivial.
-- Projections can self-heal from snapshots.
-- Checkpoint semantics become explicit rather than emergent.
-
-### 9. Make model, tool, command, and MCP work first-class span families
-
-#### Proposal
-
-Create event families with shared semantics:
-
-- `model.request.started`
-- `model.request.completed`
-- `model.request.failed`
-- `tool.started`
-- `tool.output.delta`
-- `tool.completed`
-- `tool.failed`
-- `command.started`
-- `command.output.delta`
-- `command.completed`
-- `command.failed`
-- `mcp.call.started`
-- `mcp.call.progress`
-- `mcp.call.completed`
-- `mcp.call.failed`
-
-#### Example `model.request.completed`
-
-```json
-{
- "kind": "durable",
- "id": "evt_01960d12...",
- "seq": 220,
- "ts": "2026-04-08T15:05:00.000Z",
- "run_id": "run_01JQ...",
- "session_id": "ses_123",
- "turn_id": "turn_9",
- "request_id": "req_llm_1",
- "event": "model.request.completed",
- "properties": {
- "provider": "anthropic",
- "model": "claude-sonnet-4",
- "latency_ms": 1834,
- "usage": {
- "input_tokens": 1400,
- "output_tokens": 380,
- "reasoning_tokens": 120,
- "cache_read_tokens": 900,
- "cache_write_tokens": 0
- },
- "retry_status": { "type": "not_retrying" }
- }
-}
-```
-
-#### Why this is better
-
-- Cost and latency analysis become first-class.
-- Policy engines can reason about real operations, not just stage summaries.
-- Cross-provider comparison gets much easier.
-
-### 10. Generate and enforce the public schema, docs, and examples from one registry
-
-#### Proposal
-
-Build a single `event_schema_registry` source that defines:
-
-- envelope fields
-- event families
-- payload types
-- union types
-- versioning
-- example payloads
-
-Artifacts generated from it:
-
-- Rust types
-- TypeScript types
-- JSON Schema
-- OpenAPI / SSE docs
-- sample event fixtures
-- validation tests
-
-#### Concrete rules
-
-- every public event must have:
- - one schema definition
- - one example payload
- - one validation test
-- no endpoint may inject extra consumer-visible fields outside the schema
-- keep-alive frames are documented separately from payload events
-
-#### Why this is better
-
-- Prevents the OpenCode and Goose class of drift.
-- Makes Fabro's event API publishable and stable from day one.
-
-## Recommended V2 Event Families
-
-If Fabro were starting from scratch, I would structure the public families like this:
-
-- `run.*`
-- `stage.*`
-- `checkpoint.*`
-- `parallel.branch.*`
-- `session.*`
-- `turn.*`
-- `message.*`
-- `message.part.*`
-- `model.request.*`
-- `tool.*`
-- `command.*`
-- `mcp.call.*`
-- `approval.*`
-- `question.*`
-- `interrupt.*`
-- `resume.*`
-- `compaction.*`
-- `retro.*`
-- `artifact.*`
-- `stream.*` (live only)
-
-## Recommended Field Placement Rules
-
-Top-level envelope:
-
-- identity and correlation
-- ordering
-- timestamps
-- scope
-
-`properties`:
-
-- event-family-specific payload
-- business data
-- structured state payloads
-
-Never in `properties` if they are structural:
-
-- `run_id`
-- `seq`
-- `event`
-- `session_id`
-- `message_id`
-- `tool_call_id`
-- `request_id`
-- `causation_id`
-- `correlation_id`
-
-## Bottom Line
-
-The best greenfield version of Fabro is not "the current schema plus more events."
-
-It is:
-
-- separate durable and live contracts
-- replayable ordered streams
-- a richer envelope
-- typed state unions
-- typed content blocks
-- explicit snapshots
-- first-class HITL events
-- first-class span families
-- generated schema/docs/tests from one registry
-
-That would give Fabro a better event platform than any of the compared systems.
diff --git a/docs/internal/mcp-server-qa-test-plan.md b/docs/internal/mcp-server-qa-test-plan.md
deleted file mode 100644
index 920ff0754..000000000
--- a/docs/internal/mcp-server-qa-test-plan.md
+++ /dev/null
@@ -1,254 +0,0 @@
-# Fabro MCP Server — QA Test Plan
-
-> Historical manual QA results. The run-create source selectors and flat settings
-> below predate the registered-version contract. Current calls register file contents
-> with `fabro_workflow_version_create`, then pass `workflow_version_id`, an explicit
-> standalone `target`, and nested `args` to `fabro_run_create`. See
-> [the current MCP guide](../public/agents/mcp.mdx) for the supported contract.
-
-One-time manual QA pass for the 5 tools exposed by `fabro-mcp-server`. Source of truth: `lib/apps/fabro-mcp-server/src/run_tools/`.
-
-This plan is **not** a template for adding automated test coverage — it exists to drive a single hands-on sweep against a real running server. Tick boxes as scenarios pass; add notes inline for failures or surprising behavior. Open bugs/PRs for issues found; do not port these scenarios into the Rust test suite.
-
-## Findings rollup
-
-Live list of bugs and notable observations surfaced during the sweep. Each entry links back to the scenario where it was found.
-
-### Bugs / mismatches
-None currently open.
-
-### Rechecked / no longer open
-- **C18 — `fabro_run_create` shorthand schema/runtime mismatch**: fixed on 2026-05-22. `runs: ["sleeper"]` is now accepted as workflow-selector shorthand, object-form specs remain supported for create options, and `tools/list` advertises both item shapes. Covered by `fabro_run_create_tool_advertises_string_and_object_run_specs`, `stdio_server_initializes_and_lists_run_tools`, and `mcp_create_string_shorthand_deserializes_before_auth`.
-- **C4 — `inputs` schema/runtime mismatch**: fixed by narrowing MCP input values to scalar JSON (`string`, `boolean`, `integer`, `number`) and rejecting arrays/objects locally with scalar-only errors. Re-tested on 2026-05-11 against `127.0.0.1:32276`; `tools/list` now advertises scalar-only `inputs.additionalProperties`.
-- **C5 — Misleading null-input error message**: fixed. Re-tested on 2026-05-11; null now returns ``input `maybe` cannot be null; use a string, boolean, or number``.
-- **I7 / I9 — Misleading "Run not found." on terminal runs**: fixed on 2026-05-11 in the server API layer. `message`/steer against a durable terminal run that no longer has a live managed engine now returns `409` with `run_not_steerable`; `cancel` returns `409` with `Run is already terminal and cannot be cancelled.` True missing runs still return `404`.
-- **I10 — Archived runs not filtered from default search**: fixed on 2026-05-11 by aligning MCP search with the HTTP API. `fabro_run_search` now hides archived runs when `archived` is omitted, while `archived=true` still searches archived runs explicitly.
-- **I15 / I16 — yes/no answer flow**: re-tested on 2026-05-11 against `fabro server` `0.230.0-nightly.0` at `127.0.0.1:32276`. `answer=true` and `answer=false` both submit successfully for the bundled `interview` workflow's first `yes_no` question. `true` advanced the run to the next `confirmation` question.
-- **I22 — numeric answer local validation**: re-tested on 2026-05-11 against the same server. `answer=42` now returns `unsupported answer value: 42; expected boolean, string, or object` from the MCP layer before reaching the API.
-- **Section 2 side observation — Search payloads include full `goal` text**: fixed on 2026-05-11. `fabro_run_search` now returns bounded `goal_preview` plus `goal_truncated` instead of the full `goal`, keeping list responses compact while preserving full summaries on other run interactions.
-- **X6 — Cursor/filter ordering**: simplified on 2026-05-11 by applying search filters before sorting and applying the `after` cursor. This prevents unrelated runs outside the filtered result set from trimming the page. Pagination is explicitly not snapshot-isolated; a new matching run inserted before the cursor during traversal appears when the client starts a new search.
-
-### UX / polish
-- **C12 — `cwd` errors don't distinguish "directory missing" from "workflow not in directory"**: both return `workflow not found: `.
-- **S9 (bonus) — Undocumented date format**: error message reveals `YYYY-MM-DD` is accepted alongside RFC3339, but the schema only says RFC3339.
-- **S17 — `run_ids` accepts more than IDs**: error message reveals it also matches ID prefixes and workflow names. Either rename the field or document.
-- **E4 — Events `search` is whole-envelope substring match**: search includes embedded payloads (workflow definitions, settings, sandbox dockerfile, etc.), so a search like `query="list_prs"` legitimately matches the `run.created` event because that event embeds the workflow JSON. Easy to misinterpret. Consider documenting or scoping search to event body only.
-
-### Nice-to-haves
-- **C16 — Helpful error**: unknown workflow lists available workflows. Keep.
-
-## Pre-flight (all tools)
-
-- [ ] **P1** Server unreachable — stop `fabro server`, call any tool, expect a clear connection-error message (not a panic, not a hang).
-- [ ] **P2** Schema discovery — list tools through an MCP client; verify each tool has a complete JSON schema and the documented `anyOf` for `AnswerValue`.
-
----
-
-## 1. `fabro_run_create`
-
-Source: `run_tools/create.rs:124`
-
-### Happy path
-- [x] **C1** Create one run from an existing workflow (e.g. `gh-list`); default `start=true` → expect `start_requested=true`, `status` in `{runnable, starting, running}`. — **PASS**. `status=runnable`.
-- [x] **C2** Create with `start=false` → expect `started=false`, `status=submitted`. — **PASS**. Run `01KRC4MP2NEQS9GJDE9FJ0EECH` kept as fixture for I3.
-- [x] **C3** Batch create 5 runs in one call → all return; result preserves array order. — **PASS**. ULIDs monotonically increasing.
-
-### Inputs / manifest
-- [x] **C4** Pass `inputs` with string / number / boolean / nested object / array → **PASS** after 2026-05-11 recheck. Scalar values are accepted. Arrays and objects are rejected locally with scalar-only errors, and the MCP schema now advertises scalar-only `inputs` values.
-- [x] **C5** `inputs` containing `null` → **PASS** after 2026-05-11 recheck. Returns ``input `maybe` cannot be null; use a string, boolean, or number``.
-- [x] **C6** `labels={"team": "qa"}` round-trip via search. — **PASS**. All 5 C3 runs returned with labels intact.
-- [x] **C7** Optional flags: `goal`, `model+provider`, `sandbox`, `preserve_sandbox+auto_approve+dry_run`. — **PASS** all accepted; `goal` override round-tripped via search.
-- [x] **C8** Custom `run_id`: valid ULID accepted (`01KRC500000000C8TEST00000A`); wrong length → `invalid length`; invalid Crockford char (e.g. `U`) → `invalid character`. — **PASS**.
-
-### `cwd`
-- [x] **C9** Omit `cwd` → uses base CWD. — **PASS** (covered by every prior scenario).
-- [x] **C10** `cwd` to repo root resolves workflow. — **PASS**.
-- [x] **C11** `cwd=/tmp` (no `.fabro/workflows`) → `workflow not found: gh-list`. — **PASS**.
-- [x] **C12** `cwd=/this/path/does/not/exist/xyz123` → same generic `workflow not found: gh-list`. — **PASS but note**: error doesn't distinguish "directory missing" from "workflow not in directory". Minor UX gap.
-
-### Validation
-- [x] **C13** Empty `runs: []` → `runs must contain at least 1 item(s)`. — **PASS**.
-- [x] **C14** 51 entries → `runs must contain no more than 50 item(s)`. — **PASS**.
-- [x] **C15** Missing required `workflow` → MCP layer `-32602: missing field 'workflow'`. — **PASS**.
-- [x] **C16** Unknown workflow slug → `Unknown workflow 'X'\n\nAvailable workflows: ...`. — **PASS** (very helpful — lists available workflows).
-- [x] **C18** String shorthand `runs: ["gh-list"]` → accepted as the workflow selector. `tools/list` should show `runs.items.anyOf` with both a string branch and an object branch requiring `workflow`. — **COVERED by automated regression tests added 2026-05-22**.
-
-### Failure semantics
-- [x] **C17** Invalid sandbox name → `failed to resolve manifest settings: run.sandbox.provider: invalid value - unknown sandbox provider: this-sandbox-does-not-exist`. — **PASS**. Error raised at manifest-resolve time before any run record is created (no orphaned submitted run).
-
----
-
-## 2. `fabro_run_search`
-
-Source: `run_tools/search.rs:75`
-
-### Happy path
-- [x] **S1** No params → returns up to 20 runs, sorted by `started_at OR created_at` desc. — **PASS**. Mixed-timestamp ordering correct (succeeded run at pos 8 sorts by its `started_at` between two `created_at`-only runs).
-- [x] **S2** `first=5` → exactly 5; `next_cursor` is the last run's ID. — **PASS**.
-- [x] **S3** `first=100` → all 17 runs, `next_cursor=null`. — **PASS**.
-- [x] **S4** Cursor follow-through: page 1 IDs `[A, B]`, page 2 with `after=B` returns `[C, D]`. No overlap. — **PASS**. Note: cursors are run IDs, not opaque tokens.
-
-### Filters
-- [x] **S5** `workflow="smoke"` (slug) and `workflow="Smoke"` (name) both match same run. — **PASS**.
-- [x] **S6** `status=["succeeded"]` → 4; `["failed","dead"]` → 1; `["submitted"]` → 5. — **PASS**.
-- [x] **S7** Labels round-trip. — **PASS** (verified via C6).
-- [x] **S8** `archived=false` → all unarchived runs; `archived=true` → `[]` (no archived runs yet). Re-verify after I10. — **PARTIAL** (no archived fixtures yet).
-- [x] **S9** `created_after`/`created_before` (RFC3339) bound results correctly; tight window `17:00–18:00` returns only old runs. — **PASS**. **Bonus**: error message reveals `YYYY-MM-DD` is also accepted — undocumented in the schema.
-- [x] **S10** `run_ids=[A,B,A]` → 2 deduped runs. — **PASS**.
-- [x] **S11** Combined `workflow + status + labels + archived` → returns exactly the 5 batch=c3 runs. — **PASS**.
-
-### Validation
-- [x] **S12** `first=101` → `first must be <= 100`. — **PASS**.
-- [x] **S13** `run_ids=[]` → `run_ids must contain at least 1 item(s)`. — **PASS**.
-- [x] **S14** `run_ids` length 101 → `run_ids must contain no more than 100 item(s)`. — **PASS**.
-- [x] **S15** `status=["bogus"]` → `unknown run status 'bogus'`. — **PASS**.
-- [x] **S16** `created_after="not-a-date"` → `created_after must be RFC3339 or YYYY-MM-DD: input contains invalid characters`. — **PASS**.
-
-### Edge cases
-- [x] **S17** Non-existent ID in `run_ids` → `No run found matching '' (tried run ID prefix and workflow name)`. — **PASS** + **finding**: `run_ids` also accepts ID prefixes and workflow names, which is broader than the field name suggests.
-- [x] **S18** No matches → `{"runs": [], "next_cursor": null}`. — **PASS**.
-- [x] **S19** Bogus `after=` → returns full first page (skip never applies). — **PASS** as documented.
-
-### Side observation
-Search responses include the full `goal` text per run; a single `ImplementPlan` run can add ~30 KB to every search payload. Consider truncating `goal` (or excluding it from list responses) the way events have `max_content_length`. **Logged in Findings.**
-
----
-
-## 3. `fabro_run_gather`
-
-Source: `run_tools/gather.rs:56`
-
-### Happy path
-- [x] **G1** Gather 1 already-terminal run → instant return, `timed_out=false`, `elapsed_seconds=0`. — **PASS**.
-- [x] **G2** In-flight `gh-list` with `timeout=60, poll=5` → reaches `succeeded`, `timed_out=false`, `elapsed=30`. — **PASS**.
-- [x] **G3** In-flight `gh-list` with `timeout=5, poll=5` → `timed_out=true`, `elapsed=5`, run still `starting`. — **PASS**.
-- [x] **G4** Mix of 2 terminal + 1 in-flight, `timeout=90, poll=5` → all 3 succeeded, `timed_out=false`, `elapsed=40`. — **PASS**.
-
-### Validation
-- [x] **G5** `run_ids=[]` → `run_ids must contain at least 1 item(s)`. — **PASS**.
-- [x] **G6** 51 IDs → `run_ids must contain no more than 50 item(s)`. — **PASS**.
-- [x] **G7** `timeout_seconds=601` → `timeout_seconds must be <= 600`. — **PASS**.
-- [x] **G8** `poll_interval_seconds=4` → `poll_interval_seconds must be >= 5`. — **PASS**.
-- [x] **G9** Omit both → call accepted; terminal run still returns instantly. Default values per source: `timeout=300, poll=15`. — **PASS**.
-
-### Edge cases
-- [x] **G10** Non-existent run ID → `No run found matching '' (tried run ID prefix and workflow name)`. — **PASS** (same fuzzy match as search).
-- [x] **G11** Poll cadence: G3 confirms last sleep clamps to deadline (`elapsed=5` exactly with `timeout=5, poll=5`). — **PASS** (inferred from G2/G3 timing).
-- [ ] **G12** Run cancelled mid-gather → terminal `failed(status_reason=cancelled)` quickly. — **DEFERRED** to after I8 (cancel).
-- [ ] **G13** Run becomes `blocked` — verify gather still waits. — **DEFERRED** to after Section 5 (interview workflow).
-
----
-
-## 4. `fabro_run_events`
-
-Source: `run_tools/events.rs:115`
-
-### Actions
-- [x] **E1** `list` no filters → 45 events (`gh-list` has full lifecycle: run.*, sandbox.*, git.*, stage.*, etc.), `next_cursor=46`. — **PASS**.
-- [x] **E2** `details` with 2 event_ids → returns exactly those 2 envelopes. — **PASS**.
-- [x] **E3** `details` with no `event_ids` → `event_ids is required for details action`. — **PASS**.
-- [x] **E4** `search query="list_prs"` → 14 events. Includes `run.created` because it embeds the full workflow definition (which contains the `list_prs` node ID). — **PASS** + **observation**: search ranges over the entire serialized envelope, so big embedded payloads (workflow defs, settings) can produce non-obvious hits.
-- [x] **E5** `search` with missing `query` → `query is required for search action`. — **PASS**.
-
-### Filters
-- [x] **E6** `event_types=["stage.started"]` → exactly 4 events (start, list_prs, list_issues, exit). — **PASS**.
-- [x] **E7** `categories=["git","sandbox"]` → 12 events all with prefix `git.*` or `sandbox.*`. — **PASS**.
-- [x] **E8** `created_after=17:03:10Z` + `created_before=17:03:13Z` → 5 events all timestamped 17:03:12.89x. — **PASS**.
-- [x] **E9** Combined `event_types + offset + first` covered by E14.
-
-### Pagination & direction
-- [x] **E10** Page 1 `first=10` → seqs 1–10, `next_cursor=11`. Page 2 `after=11, first=5` → seqs 11–15, `next_cursor=16`. No duplicates; contiguous. — **PASS**.
-- [x] **E11** `direction=desc, first=5` → seqs 45, 44, 43, 42, 41; `next_cursor=41` (last seq, no +1 — per the desc branch). — **PASS**.
-- [x] **E12** Default direction = asc (E10 confirms). — **PASS**.
-- [x] **E13** `direction="weird"` → `direction must be 'asc' or 'desc'`. — **PASS**.
-- [x] **E14** `event_types=["stage.started"], offset=2, first=5` → returned 2 events (seqs 29, 39) — correctly skipped the first 2 (15, 19) of the 4 matching. — **PASS**.
-- [x] **E15** `limit=3` → 3 events. — **PASS** (alias works).
-
-### Truncation
-- [x] **E16** `stage.completed, first=1, max_content_length=200` → 1 event, `truncated=true`, `event` is a JSON string. — **PASS**.
-- [x] **E17** UTF-8 boundary — **VERIFIED via existing unit test** at `events.rs:269-312`. Can't easily reproduce through MCP surface (no multibyte event content in default fixtures).
-- [x] **E18** Default `max_content_length=20000` → all 5 events `truncated=false` (including the ~5 KB `run.created`). — **PASS**.
-
-### Validation
-- [x] **E19** `run_id=" "` (whitespace) → `run_id is required`. — **PASS**.
-- [x] **E20** `first=201` → `first must be <= 200`. — **PASS**.
-- [x] **E21** Non-existent run ID → fuzzy-match error (same as search/gather). — **PASS**.
-
----
-
-## 5. `fabro_run_interact`
-
-Source: `run_tools/interact.rs:201`
-
-### Actions
-
-#### `get`
-- [x] **I1** Returns `{summary, projection}`; projection includes `spec`, `graph`, `status`, `checkpoints`, `pending_interviews`, `stages`, `sandbox`, `conclusion`, etc. — **PASS**.
-- [x] **I2** Non-existent run → fuzzy match error. — **PASS**.
-
-#### `start`
-- [x] **I3** Non-started run (from C2) → `start` transitions to `runnable`. Second `start` → `start has already been requested for this run`. — **PASS**.
-
-#### `message` (steer)
-- [ ] **I4** Steer a running LLM agent — **DEFERRED** (requires an active LLM agent stage; would burn LLM tokens; can be exercised manually once the answer bug below is resolved).
-- [ ] **I5** `interrupt=true` — **DEFERRED** along with I4.
-- [x] **I6** Missing `message` → `message is required for action message`. — **PASS**.
-- [x] **I7** Message a terminal run → initially returned `Run not found.`. — **FIXED**: durable terminal runs without a live managed engine now return `409 run_not_steerable`; true missing runs remain `404`.
-
-#### `cancel`
-- [x] **I8** Cancel a `gh-list` run during `starting`. Returns summary at request time (status=`starting`). Subsequent `gather` returned terminal `failed` within 5s; `get` projection shows `status: {kind: "failed", reason: "cancelled"}` and `conclusion.failure_reason: "Pipeline cancelled"`. — **PASS** + **observation**: `cancel`'s returned summary is a snapshot at request time, not the eventual terminal status.
-- [x] **I9** Cancel an already-terminal run → initially returned `Run not found.`. — **FIXED**: durable terminal runs without a live managed engine now return `409` with `Run is already terminal and cannot be cancelled.`; true missing runs remain `404`.
-
-#### `archive` / `unarchive`
-- [x] **I10** Archive terminal run → `archived=true` in summary; visible via `search archived=true`. — **FIXED**: default search now hides archived runs to match `/api/v1/runs`; `archived=true` still surfaces archived runs explicitly.
-- [x] **I11** Unarchive → reverses (`archived=false`). — **PASS**.
-- [x] **I12** Archive an active run → `run must be terminal (succeeded, failed, or dead) to archive; current status is starting`. — **PASS** (excellent error).
-
-#### `get_questions`
-- [x] **I13** Terminal run → `questions: []`. — **PASS**.
-- [x] **I14** Blocked interview run → returns full question record (id, text, options, question_type, stage, allow_freeform). — **PASS**.
-
-#### `answer` — `AnswerValue` shapes
-
-Re-check note: the earlier `yes_no` answer failure did not reproduce against `fabro server` `0.230.0-nightly.0` on `127.0.0.1:32276` (2026-05-11). Boolean answers are accepted for `yes_no` questions, and invalid question/type combinations are rejected by the API as expected.
-
-- [x] **I15** `answer=true` on the first `yes_no` question → submitted successfully (`submitted=true`) and advanced to the `confirmation` question. — **PASS**. Run `01KRCAQ9AS14KFCW4CXBZQ0CW9`.
-- [x] **I16** `answer=false` on a fresh `yes_no` question → submitted successfully (`submitted=true`). — **PASS**. Run `01KRCATZ031CAPEPVB4CNFEE33`.
-- [ ] **I17** `answer="some text"` — **NOT RE-TESTED**. Should be tested against a `freeform` question or a question with `allow_freeform=true`; text is not valid for the bundled `yes_no` question.
-- [ ] **I18** `answer={"text":"hi"}` — **NOT RE-TESTED**. Same scope as I17.
-- [x] **I19** `answer={"option":"Y"}` against the first `yes_no` question → `Answer does not match question type.` — **PASS / expectation corrected**. The MCP layer maps this shape to `selected`, but `server.rs:2670-2710` only accepts `yes`/`no` for `yes_no` and `confirmation`; `selected` belongs to `multiple_choice`.
-- [ ] **I20** `answer={"options":[...]}` — **NOT RE-TESTED**. Should be tested against a `multi_select` question; `multi_selected` is not valid for `yes_no`.
-- [x] **I21** `answer={"value":"yes"}` → `answer object must contain one of: option, options, text` (local validation). — **PASS**.
-- [x] **I22** `answer=42` (number) → `unsupported answer value: 42; expected boolean, string, or object`. — **PASS** (local validation).
-- [x] **I23** `answer={"option": 5}` → `answer option must be a string: invalid type: integer '5', expected a string`. — **PASS**.
-- [x] **I24** `answer={"options": ["a", 2]}` → `answer options must be strings: invalid type: integer '2', expected a string`. — **PASS**.
-- [x] **I25** `action=answer` without `question_id` → `question_id is required for action answer`. — **PASS**.
-- [x] **I26** `action=answer` without `answer` → `answer is required for action answer`. — **PASS**.
-- [x] **I27** Already-answered question — observed indirectly: the same question_id returned `Question no longer exists or was already answered.` on retry. — **PASS**.
-
-### Cross-cutting
-- [x] **I28** `run_id=" "` → `run_id is required`. — **PASS**.
-- [x] **I29** Action enum: `Get` and `get-questions` both rejected with `unknown variant 'X', expected one of: get, start, message, cancel, archive, unarchive, get_questions, answer`. — **PASS**.
-
----
-
-## 6. End-to-end scenarios (multi-tool)
-
-- [x] **X1 — Happy lifecycle** `gh-list` create → 35s gather → events filtered to `stage.started/completed` → 8 events for 4 stages (start, list_prs, list_issues, exit). Sequence matches workflow graph. — **PASS**.
-- [x] **X2 — Cancel mid-run** Covered by I8: `gh-list` cancel during `starting` → gather returned terminal `failed` in 5s; projection shows `status_reason=cancelled`. — **PASS**.
-- [ ] **X3 — Human-in-the-loop** — **PARTIAL**. The earlier yes/no answer blocker is no longer reproduced (I15/I16 now pass), and `gather` returning `timed_out=true` on a `blocked` run **was** verified (G13). Full interview completion remains unverified in this sweep.
-- [ ] **X4 — Steering** — **DEFERRED** (requires active LLM agent).
-- [x] **X5 — Archive flow** Covered by I10/I11: archive → search with `archived=true` returns it (also returned by default search — see I10 finding). Unarchive reverses. — **PASS** with caveat.
-- [x] **X6 — Search/cursor under churn** Page 1 `first=3` → cursor saved. Created new run `01KRC625KG…` mid-flow. Page 2 with original cursor returned 3 older runs; a fresh page 1 placed the new run at position 1. — **ACCEPTED / SIMPLIFIED**. Pagination is not snapshot-isolated; clients that need newly inserted earlier results should restart the search. Code now applies filters before sorting/cursoring so unrelated runs outside the filtered result set do not trim filtered pages.
-- [x] **X7 — Events while running** Started `gh-list` run, listed events `desc` immediately (max seq=8), gathered to completion, re-listed (max seq=46). Seq numbers grew monotonically; no early events lost. — **PASS**.
-- [x] **X8 — Truncated event recovery** Fetched the `ImplementPlan` `run.created` event (embeds ~30 KB goal) at default `max_content_length=20000` → `truncated:true`, payload returned as a JSON string. — **PASS**.
-- [ ] **X9 — Stranger inputs** — Skipped per scope decision. Trivially safe since inputs go through TOML conversion to be stored as values; the MCP layer never opens paths.
-
----
-
-## 7. Mechanics for the manual sweep
-
-- **Driver** — run these scenarios through an MCP client (e.g. Claude Code with the `fabro` MCP server configured) against a locally running `fabro server`.
-- **Reusable run IDs** — keep a handful of already-terminal runs around (e.g. one `gh-list` succeeded, one failed `implement-plan`) as fixtures for `events`, `gather` (instant-return), `interact.get`, and `archive` scenarios.
-- **Server unreachable cases** — stop the API server with the MCP client still connected to exercise error propagation paths.
-- **Issue tracking** — file a GitHub issue per defect; link the scenario ID (e.g. `C13`) so this plan and the bugs cross-reference.
diff --git a/docs/internal/plan-events-as-source-of-truth-follow-ups.md b/docs/internal/plan-events-as-source-of-truth-follow-ups.md
deleted file mode 100644
index 1ca2b9fc2..000000000
--- a/docs/internal/plan-events-as-source-of-truth-follow-ups.md
+++ /dev/null
@@ -1,457 +0,0 @@
-# Plan: Events as Source of Truth Follow-Ups
-
-Close the remaining event-contract gaps required before we can execute `~/.claude/plans/memoized-pondering-knuth.md` and make projected `RunState` the primary read model.
-
-## Context
-
-`docs-internal/plan-events-as-source-of-truth.md` has mostly landed. The event stream is materially stronger now, but it still does not cover every field that `memoized-pondering-knuth.md` wants to derive from events.
-
-The next step is not a broad store refactor. It is a narrow follow-up pass that:
-
-- finishes the missing event coverage
-- makes the remaining source-of-truth boundaries explicit
-- leaves `memoized-pondering-knuth.md` with no hidden event-contract assumptions
-
-This plan is a prerequisite plan, not the full event-sourced store migration.
-
-## Simplification Rules
-
-These rules govern every follow-up event change in this document:
-
-- enrich an existing semantic event before inventing a new one
-- keep run-level summary data on run-level events
-- keep handler-specific metadata on handler-specific events
-- avoid storage-shaped event names like `*.recorded`, `*.persisted`, or `*.written`
-- explicitly retain non-event concerns instead of half-eventizing them
-
-If a proposed event change violates one of those rules, prefer a simpler shape.
-
-## Goal
-
-After this plan lands, the later `memoized-pondering-knuth.md` work should be able to:
-
-- build a projected `RunState` without inventing missing data
-- replace direct read-side APIs with projection helpers
-- remove duplicated write-side persistence for all event-backed fields
-
-without first having to stop and redesign the event model again.
-
-## Relationship To The Existing Plans
-
-### What `plan-events-as-source-of-truth.md` already solved
-
-- `run.created`
-- `stage.completed.response`
-- `sandbox.initialized` sandbox metadata
-- `checkpoint.completed.diff`
-- `command.started` / `command.completed`
-- `retro.started.prompt/provider/model`
-- `retro.completed.response/retro`
-
-### What is still missing for `memoized-pondering-knuth.md`
-
-- semantic run status events
-- checkpoint events that can reconstruct full checkpoint snapshots and history
-- full pull request record coverage
-- final patch coverage
-- provider-used coverage
-- parallel-results coverage
-- an explicit decision for fields that should remain non-event for now
-
-## Decisions
-
-### 1. Use semantic run lifecycle events, not a generic `run.status_changed`
-
-Status should be reconstructed from explicit run lifecycle events rather than a generic “status changed” envelope.
-
-Add event coverage for:
-
-- `run.submitted`
-- `run.starting`
-- `run.running`
-- `run.paused`
-- `run.removing`
-- `run.completed`
-- `run.failed`
-- `run.dead`
-
-Projection rule:
-
-- the latest status-bearing run event defines `RunStatusRecord.status`
-- event-specific fields define `RunStatusRecord.reason`
-- envelope `ts` defines `RunStatusRecord.updated_at`
-
-`run.started` remains the start-record / execution-metadata event, not the canonical status event.
-
-This separation is intentional:
-
-- `run.started` answers "when and how did execution begin?"
-- `run.running` answers "what is the run's status?"
-
-Status mapping table:
-
-| Event | Projected `RunStatus` | `StatusReason` rule |
-|---|---|---|
-| `run.submitted` | `Submitted` | `None` |
-| `run.starting` | `Starting` | optional if the emitter has a concrete reason, otherwise `None` |
-| `run.running` | `Running` | `None` |
-| `run.paused` | `Paused` | preserve emitted reason if present |
-| `run.removing` | `Removing` | `None` |
-| `run.completed` | `Succeeded` | preserve emitted reason if present; default should remain `Completed` or `PartialSuccess` based on terminal outcome |
-| `run.failed` | `Failed` | preserve emitted reason if present; expected common reasons include workflow/bootstrap/sandbox failures |
-| `run.dead` | `Dead` | preserve emitted reason if present; otherwise `None` |
-
-If any current status mutation cannot be represented cleanly by this table, fix the event model in this follow-up plan rather than pushing ambiguity into the later projector.
-
-### 2. Keep the boundary tight: not every stored value must become an event in this pass
-
-This follow-up plan should only eventize the fields that block the later projected-state cutover.
-
-Retain as non-event concerns for now:
-
-- binary assets
-- artifact value blobs / offloaded context artifacts
-
-This means `memoized-pondering-knuth.md` should be updated afterwards so `artifact_values` is no longer listed as a required event-backed row for the first cut.
-
-### 3. Prefer complete event payloads over event joins that require hidden store lookups
-
-If a projected record needs fields that do not already exist in another authoritative event, add them directly to the relevant event.
-
-Do not rely on:
-
-- sidecar JSON files
-- legacy store records
-- “the caller can join this with some other direct read”
-
-Prefer one self-contained semantic event over reconstructing a record from several unrelated low-level events when that reconstruction adds complexity for little value.
-
-## Follow-Up Coverage Matrix
-
-This matrix is the contract for this plan. Each row must be green before `memoized-pondering-knuth.md` starts removing read/write APIs.
-
-| Field / record needed later | Current direct source | Current event state | Follow-up required |
-|---|---|---|---|
-| `RunStatusRecord` | `put_status` in create/start/resume/finalize/disk paths | Incomplete; no semantic status event family | Add semantic run lifecycle events and a status mapping table |
-| `StartRecord` | `put_start` | Mostly covered by `run.started` | Verify `run.started` fully covers `run_branch`, `base_sha`, `start_time`; no shape change if already true |
-| latest `Checkpoint` | `put_checkpoint` | Incomplete; `checkpoint.completed` only carries `node_id`, `status`, `git_commit_sha`, `diff` | Enrich `checkpoint.completed` to carry a full checkpoint snapshot payload |
-| checkpoint history | `append_checkpoint` / `list_checkpoints` | Incomplete; history cannot be rebuilt from current event payload | Use fully-populated `checkpoint.completed` as append-only checkpoint history |
-| `Conclusion` | `put_conclusion` | Partially covered by terminal events plus stage aggregation | Verify the projector can derive full `Conclusion`, including retries/tokens/stage summaries, from existing events; if projection stays awkward, enrich terminal run events instead of adding new conclusion-only events |
-| `PullRequestRecord` | `put_pull_request` | Incomplete; `pull_request.created` only carries URL/number/draft | Enrich `pull_request.created` to carry full `PullRequestRecord` fields |
-| final patch | `put_final_patch` | Incomplete; terminal run event carries final SHA but not patch text | Enrich `run.completed` with `final_patch` |
-| node provider metadata | `put_node_provider_used` | Incomplete; prompt/CLI events carry provider/model, but agent-mode still relies on sidecar sync | Project from existing handler-specific events and enrich forwarded agent session events if needed |
-| node parallel results | `put_node_parallel_results` | Incomplete; `parallel.branch.completed.head_sha` is not enough | Enrich `parallel.completed` to carry the final results payload |
-| node diff | `put_node_diff` | Partially covered by `checkpoint.completed.diff` | Decide and document whether node diff is sourced from the latest checkpoint event for that node or a dedicated node diff event; keep one canonical rule |
-| retro prompt/response/retro payload | `put_retro_prompt`, `put_retro_response`, `put_retro` | Covered | No new event work; just parity-test it |
-| sandbox record | `put_sandbox` | Covered | No new event work; just parity-test it |
-
-## Required Event Changes
-
-### 1. Add semantic run lifecycle events
-
-Add new `Event` variants for:
-
-- `RunSubmitted`
-- `RunStarting`
-- `RunRunning`
-- `RunPaused`
-- `RunRemoving`
-- `RunDead`
-
-Existing terminal events remain:
-
-- `run.completed`
-- `run.failed`
-
-Required payload fields:
-
-- `reason: Option` where applicable
-- any extra fields already emitted on terminal events should stay there
-
-Emit from the same places that currently call `put_status`:
-
-- `lib/components/fabro-workflow/src/operations/create.rs`
-- `lib/components/fabro-workflow/src/operations/start.rs`
-- `lib/components/fabro-workflow/src/operations/resume.rs`
-- `lib/components/fabro-workflow/src/pipeline/finalize.rs`
-- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
-- CLI administrative flows that directly mutate status:
- - `lib/apps/fabro-cli/src/commands/runs/rm.rs`
- - `lib/apps/fabro-cli/src/commands/run/rewind.rs`
-
-### 2. Enrich `checkpoint.completed` to carry a full checkpoint snapshot
-
-Current `checkpoint.completed` is not enough to rebuild `Checkpoint`.
-
-Add fields covering:
-
-- `timestamp` is still the envelope `ts`
-- `current_node`
-- `completed_nodes`
-- `node_retries`
-- `context_values`
-- `node_outcomes`
-- `next_node_id`
-- `git_commit_sha`
-- `loop_failure_signatures`
-- `restart_failure_signatures`
-- `node_visits`
-- `diff`
-
-Emitter seam:
-
-- `lib/components/fabro-workflow/src/lifecycle/event.rs`
-
-Producer seam for the source checkpoint object:
-
-- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
-
-Design rule:
-
-- one `checkpoint.completed` event must be sufficient to reconstruct one historical checkpoint record without replaying prior stage events
-
-That keeps checkpoint history export and `rebuild_meta` simple.
-
-Do not split checkpoint reconstruction back across `stage.completed` and other incidental events unless there is a strong size or performance reason. A saved checkpoint is a first-class domain event and should be self-contained.
-
-### 3. Enrich `pull_request.created` to carry the full record
-
-Current event payload is too small for `PullRequestRecord`.
-
-Add:
-
-- `html_url`
-- `number`
-- `owner`
-- `repo`
-- `base_branch`
-- `head_branch`
-- `title`
-- `draft`
-
-Producer seam:
-
-- `lib/components/fabro-workflow/src/pipeline/pull_request.rs`
-
-After this lands, `put_pull_request` should become removable during the later memoized-state cutover.
-
-Do not add a second storage-oriented PR event. The semantic event is already "pull request created"; it just needs the full payload.
-
-### 4. Enrich `run.completed` with the final patch
-
-Current final patch only exists via direct store writes.
-
-Do not add a separate storage-shaped event. The final patch is run-level terminal metadata, so it belongs on the terminal success event.
-
-Enrich `run.completed`, using the patch already computed from:
-
-- `lib/components/fabro-workflow/src/lifecycle/git.rs`
-
-Required payload:
-
-- `final_patch: Option`
-
-Projection rule:
-
-- `RunState.final_patch` projects from `run.completed.properties.final_patch`
-
-This keeps final run summary data in one place alongside:
-
-- `status`
-- `duration_ms`
-- `artifact_count`
-- `final_git_commit_sha`
-
-If failed runs later need final patch coverage too, extend the terminal failure event deliberately. Do not introduce a separate patch-persistence event unless terminal events prove insufficient.
-
-### 5. Finish provider-used coverage using existing handler-specific events
-
-The current system still reads `provider_used.json` from disk and syncs it into the store. That is not event-sourced.
-
-Replace that with one explicit projection rule based on existing handler-specific events.
-
-Use:
-
-- `stage.prompt` for prompt-mode stages
-- forwarded `agent.session.started` for agent-mode stages
-- `agent.cli.started` for CLI-backed agent stages
-
-If agent-mode forwarded session events still do not carry enough metadata, enrich `AgentEvent::SessionStarted` rather than adding a new stage-wide event.
-
-Required projected output:
-
-- `mode`
-- `provider`
-- `model`
-- any existing raw provider-used JSON fields that are still needed by consumers
-
-Likely seams:
-
-- `lib/components/fabro-workflow/src/handler/agent.rs`
-- `lib/components/fabro-workflow/src/handler/llm/api.rs`
-- `lib/components/fabro-workflow/src/pipeline/retro.rs` if retro uses the same forwarded agent session path
-- any CLI-backed LLM path if it still produces `provider_used.json`
-
-Do not keep the current “read JSON sidecar, then `put_node_provider_used`” pattern once this event exists.
-
-Do not add a stage-generic provider-used event. Provider metadata is transport-specific and should stay attached to the prompt/agent/CLI events that actually know it.
-
-### 6. Enrich `parallel.completed` with the final results payload
-
-`parallel.branch.completed.head_sha` is useful but not enough to replace `put_node_parallel_results`.
-
-Use the existing terminal parallel event rather than adding a storage-shaped event name.
-
-Add to `parallel.completed`, emitted from:
-
-- `lib/components/fabro-workflow/src/handler/parallel.rs`
-
-Required new payload:
-
-- `results` as the same JSON array currently persisted to `parallel_results.json`
-
-Projection rule:
-
-- `StageProjection.parallel_results` projects from `parallel.completed.properties.results`
-
-Why this is the right event:
-
-- it is emitted after all branch executions have joined
-- the final result set has already been assembled
-- it represents completion of the parallel node’s branch-collection phase
-
-The workflow-level outcome of the node still comes from `stage.completed`; `parallel.completed` just becomes the canonical source for the branch result set.
-
-Do not add `parallel.results_recorded` or similar. The semantic event already exists.
-
-### 7. Lock down the node diff rule
-
-We already added `checkpoint.completed.diff`, but the memoized plan should not proceed until there is one explicit derivation rule for node diff.
-
-Decision required:
-
-- either `StageProjection.diff` is “latest checkpoint diff for that node visit”
-- or add a dedicated `node.diff_generated` event
-
-This follow-up plan should pick one and update docs/tests accordingly.
-
-Given the current code, using `checkpoint.completed.diff` is the simpler option unless multiple diffs per node visit need to be preserved.
-
-Prefer `checkpoint.completed.diff` unless a concrete consumer proves that diff generation and checkpoint persistence are semantically different moments.
-
-## File Map
-
-Likely files to touch:
-
-- `docs-internal/events.md`
-- `docs-internal/run-directory-keys.md`
-- `docs-internal/events-strategy.md`
-- `lib/components/fabro-workflow/src/event.rs`
-- `lib/components/fabro-workflow/src/lifecycle/event.rs`
-- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
-- `lib/components/fabro-workflow/src/lifecycle/git.rs`
-- `lib/components/fabro-workflow/src/operations/create.rs`
-- `lib/components/fabro-workflow/src/operations/start.rs`
-- `lib/components/fabro-workflow/src/operations/resume.rs`
-- `lib/components/fabro-workflow/src/pipeline/finalize.rs`
-- `lib/components/fabro-workflow/src/pipeline/pull_request.rs`
-- `lib/components/fabro-workflow/src/handler/agent.rs`
-- `lib/components/fabro-workflow/src/handler/parallel.rs`
-- `lib/apps/fabro-cli/src/commands/runs/rm.rs`
-- `lib/apps/fabro-cli/src/commands/run/rewind.rs`
-- tests in `fabro-workflow`, `fabro-cli`, and `fabro-store`
-
-## Phases
-
-### Phase 1: Define the missing event contract
-
-- add semantic run lifecycle events
-- enrich `checkpoint.completed`
-- enrich `pull_request.created`
-- enrich `run.completed` with `final_patch`
-- add provider-used event coverage
-- add parallel-results event coverage
-- document the node diff derivation rule
-
-This phase is complete when every row in the follow-up coverage matrix is backed by an explicit event contract.
-
-Priority during this phase:
-
-- first enrich existing semantic events
-- only add a truly new event when no existing semantic event owns the data
-
-### Phase 2: Emit the new events everywhere status/data currently writes directly
-
-Replace silent state mutation with canonical event emission first.
-
-Important rule:
-
-- do not remove direct store writes yet
-- dual-write is acceptable in this phase
-- the purpose is to prove event completeness before the memoized-state migration begins
-
-### Phase 3: Add parity tests against current stored records
-
-Add tests that build real event sequences and verify the future projector contract is now possible for:
-
-- status reconstruction
-- start record reconstruction
-- checkpoint reconstruction
-- checkpoint history reconstruction
-- pull request reconstruction
-- final patch reconstruction
-- provider-used reconstruction
-- parallel-results reconstruction
-
-Where a direct legacy store record still exists, compare the event-derived value against the legacy persisted value.
-
-Keep the tests shaped around semantic events, not internal store APIs. The point is to prove the event contract is sufficient.
-
-Minimum parity scenarios:
-
-- create-only run before execution starts
-- normal started/running run
-- resumed run
-- rewound run
-- successful git-backed run with final patch
-- PR-producing run
-- parallel run with branch results
-- retro-enabled run
-- failed run that exits through terminal/drop-guard paths
-
-### Phase 4: Update the downstream migration plan
-
-Once this follow-up plan lands:
-
-- update `~/.claude/plans/memoized-pondering-knuth.md`
-- remove any rows that were intentionally retained as non-event concerns
-- mark the newly-completed event-backed rows as ready
-- delete stale “likely needs to be added” wording that is no longer true
-
-This keeps the later store-migration plan honest and implementation-ready.
-
-## Verification
-
-1. `cargo build --workspace`
-2. `cargo clippy --workspace -- -D warnings`
-3. `cargo nextest run -p fabro-workflow`
-4. `cargo nextest run -p fabro-cli`
-5. `cargo nextest run -p fabro-store`
-6. `cargo nextest run --workspace`
-7. Manual:
- - create a run and inspect `progress.jsonl`
- - verify semantic run lifecycle events appear in the expected order
- - verify a run with git changes emits `run.completed.properties.final_patch`
- - verify a PR-producing run emits full PR metadata in `pull_request.created`
- - verify a parallel run emits canonical final results on `parallel.completed` without reading `parallel_results.json`
-
-## Exit Criteria
-
-This follow-up plan is complete when:
-
-- every row in the follow-up coverage matrix is either event-backed or explicitly retained as non-event
-- direct store writes are no longer the only source for status, checkpoint history, pull request record, final patch, provider-used, or parallel results
-- projector parity tests prove the later `RunState` refactor has the event data it needs
-- `memoized-pondering-knuth.md` can be updated to proceed without hidden event-contract gaps
-
-At that point, the later migration work should mostly be mechanical projection and API cleanup, not more event-model design.
diff --git a/docs/internal/plan-events-as-source-of-truth.md b/docs/internal/plan-events-as-source-of-truth.md
deleted file mode 100644
index 3c2319930..000000000
--- a/docs/internal/plan-events-as-source-of-truth.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# Plan: Events as Source of Truth
-
-Make all run directory key data derivable from events in `progress.jsonl`.
-
-## Summary of changes
-
-### Clarified derivation rules
-
-- Envelope fields count as event sources. Any file field may be sourced from event envelope metadata (`run_id`, `ts`, `node_id`, `node_label`) as well as `properties`.
-- When a file is reconstructed from multiple events, the derivation should be documented explicitly in `events.md` and `run-directory-keys.md`; consumers should not need to infer cross-event joins.
-- `retro.json` is reconstructed from multiple events: `run.started` provides `workflow_name` and `goal`, `retro.completed` provides the parsed `retro` payload, and the retro event envelope provides the completion timestamp.
-- `conclusion.json.final_git_commit_sha` is normalized from the terminal run event: `run.completed.properties.final_git_commit_sha` on success/partial success, `run.failed.properties.git_commit_sha` on failure.
-
-### New events
-
-| Event | Purpose |
-|-------|---------|
-| `run.created` | Full run definition (settings, graph, workflow source/config, labels, paths). Emitted at end of CREATE operation, before START. |
-| `command.started` | Command node invocation: script, language, timeout_ms |
-| `command.completed` | Command node result: stdout, stderr, exit_code, duration_ms, timed_out |
-| `agent.cli.started` | CLI-backend LLM invocation: mode, provider, model, command |
-| `agent.cli.completed` | CLI-backend LLM result: stdout, stderr |
-
-### Enriched events
-
-| Event | New fields |
-|-------|------------|
-| `stage.started` | Remove `script` (moved to `command.started`), make `handler_type` non-optional |
-| `stage.completed` | `context_updates`, `jump_to_node`, `context_values`, `node_visits`, `loop_failure_signatures`, `restart_failure_signatures`, `response` |
-| `sandbox.initialized` | `provider`, `identifier`, `working_directory`, `repo_cloned`, `clone_origin_url`, `clone_branch` |
-| `checkpoint.completed` | `diff` |
-| `parallel.branch.completed` | `head_sha` |
-| `agent.session.started` | `mode`, `provider`, `model` |
-| `stage.prompt` | `mode`, `provider`, `model` |
-| `retro.started` | `prompt`, `provider`, `model` |
-| `retro.completed` | `response`, `retro` (full Retro struct) |
-
-### Already covered (no changes needed)
-
-| Key | Event source |
-|-----|--------------|
-| `start.json` | `run.started` |
-| `nodes/{node_id}/prompt.md` | `stage.prompt` |
-| `nodes/{node_id}/status.json` | `stage.completed` |
-| `retro/status.json` | `retro.completed` / `retro.failed` |
-| `conclusion.json` | `run.completed` / `run.failed` + aggregation from `stage.completed` |
-| `checkpoints/*.json` | Same as `checkpoint.json` — derived from `stage.completed` replay |
-
----
-
-## Detailed decisions
-
-### 1–2. `_init.json` + `run.json` — new `run.created` event
-
-**Decision:** Emit a `run.created` event at the end of the CREATE operation (before START). Carries everything needed to persist the run:
-
-- From `_init.json`: `created_at`, `db_prefix`, `run_dir`
-- From `run.json`: `settings`, `graph`, `workflow_slug`, `source_directory`, `base_branch`, `labels`
-- From `workflow.fabro`/`workflow.toml`: `workflow_source` (raw dot text), `workflow_config` (raw TOML text)
-
-The existing `run.started` stays lightweight — it signals execution has begun. The CREATE→START boundary is: `run.created` persists the run definition, `run.started` marks execution start.
-
-Derivation details:
-- `_init.json.run_id` and `run.json.run_id` come from `run.created` envelope `run_id`
-- `_init.json.created_at` and `run.json.created_at` come from `run.created` envelope `ts`
-
-### 3. `checkpoint.json` — internal engine state
-
-**Decision:** Add `context_updates`, `jump_to_node`, `context_values`, `node_visits`, `loop_failure_signatures`, and `restart_failure_signatures` to the `stage.completed` event properties. All checkpoint fields become derivable from replaying stage events.
-
-New fields on `stage.completed`:
-- `context_updates` — map of context key → JSON value set by this stage
-- `jump_to_node` — non-edge jump target (optional)
-- `context_values` — full accumulated context map after this stage
-- `node_visits` — map of node id → visit count after this stage
-- `loop_failure_signatures` — failure signature → count after this stage
-- `restart_failure_signatures` — failure signature → count after this stage
-
-Derivation details:
-- `checkpoint.json.timestamp` comes from the corresponding `checkpoint.completed` envelope `ts`
-- `checkpoints/{seq:04}-{epoch_ms}.json` uses the same derivation as `checkpoint.json`, with snapshot timestamp taken from each `checkpoint.completed` envelope `ts`
-
-### 4. `retro.json` — LLM-generated retro content
-
-**Decision:** Embed the full `Retro` struct as a `retro` property on the `retro.completed` event.
-
-Derivation details:
-- `retro.json.run_id` comes from the `retro.completed` envelope `run_id`
-- `retro.json.workflow_name` comes from `run.started.properties.name`
-- `retro.json.goal` comes from `run.started.properties.goal`
-- `retro.json.timestamp` comes from the `retro.completed` envelope `ts`
-- The remaining retro content comes from `retro.completed.properties.retro`
-
-### 5. `sandbox.json` — missing fields
-
-**Decision:** Add sandbox-native identity and clone metadata to `sandbox.initialized` so it alone is sufficient to reconstruct `sandbox.json`. Host paths and container mount points are not part of the durable event model; clone-based providers report their sandbox working directory plus repository clone state instead.
-
-### 6. `workflow.fabro` + `workflow.toml` — raw source files
-
-**Decision:** Add `workflow_source` (raw dot text) and `workflow_config` (raw TOML text) as string fields on `run.created`. Covered by gap 1–2.
-
-### 7. `nodes/{node_id}/response.md` — LLM response text
-
-**Decision:** Add a `response` string field to `stage.completed` for LLM stages.
-
-### 8. `nodes/{node_id}/prompt.md` — already covered
-
-No change needed. `stage.prompt` is emitted per handler invocation (including retries) with the full rendered prompt text.
-
-### 9–10. `stdout.log`, `stderr.log`, `script_timing.json` — new `command.completed` event
-
-**Decision:** Emit a `command.completed` event after a command node finishes. Fields:
-- `stdout`, `stderr`, `exit_code`, `duration_ms`, `timed_out`
-
-The `node_id` is in the envelope.
-
-### 11. `nodes/{node_id}/script_invocation.json` — new `command.started` event
-
-**Decision:** Emit a `command.started` event with `script`, `language`, `timeout_ms`. Pairs with `command.completed`. Remove `script` from `stage.started` — it's handler-specific data that belongs on the handler-specific event (same pattern as `agent.session.started` and `stage.prompt`).
-
-### 12. `cli_stdout.log`, `cli_stderr.log`, `provider_used.json` (CLI) — new `agent.cli.started` / `agent.cli.completed` events
-
-**Decision:** Emit an `agent.cli.started` event before the CLI subprocess starts, with `mode` ("cli"), `provider`, `model`, `command`. Emit `agent.cli.completed` after it finishes, with `stdout`, `stderr`. The `node_id` is in the envelope.
-
-### 13. `nodes/{node_id}/diff.patch` — git diff
-
-**Decision:** Add a `diff` string field to `checkpoint.completed`.
-
-### 14. `nodes/{node_id}/provider_used.json` — provider metadata
-
-**Decision:** Add provider metadata to handler-specific events:
-- `agent.session.started` gets `mode` ("agent"), `provider`, `model`
-- `agent.cli.started` gets `mode` ("cli"), `provider`, `model`, `command`
-- `stage.prompt` gets `mode` ("prompt"), `provider`, `model`
-
-### 15. `parallel_results.json` — `head_sha`
-
-**Decision:** Add an optional `head_sha` field to `parallel.branch.completed`.
-
-### 16. `retro/prompt.md` + `retro/response.md`
-
-**Decision:** Add `prompt` to `retro.started`. Add `response` to `retro.completed` (alongside the parsed retro struct).
-
-### 17. `retro/provider_used.json`
-
-**Decision:** Add `provider` and `model` to `retro.started` alongside the prompt.
-
-### Conclusion timestamps and final SHA normalization
-
-**Decision:** Treat terminal run events as the authoritative source for `conclusion.json`.
-
-Derivation details:
-- `conclusion.json.timestamp` comes from the terminal event envelope `ts` (`run.completed` or `run.failed`)
-- `conclusion.json.final_git_commit_sha` comes from `run.completed.properties.final_git_commit_sha` on success/partial success
-- On failure, `conclusion.json.final_git_commit_sha` is reconstructed from `run.failed.properties.git_commit_sha`
-
----
-
-## Follow-up improvements
-
-- `node_visits`, `loop_failure_signatures`, `restart_failure_signatures` on `stage.completed` are snapshots of accumulated state. In the future, these could be derived from event replay instead of being carried on each event — removing them would reduce event size but require replay logic in every consumer.
-- `context_values` is the full accumulated context map. If context maps grow large, a future optimization could emit only `context_updates` (the delta) and require consumers to accumulate. For now, shipping the full snapshot is simpler.
-- `stdout`/`stderr` on `command.completed` could be large. If this becomes a problem, consider a size threshold with truncation or a separate blob store with a reference in the event.
diff --git a/docs/internal/slow-test-opportunities-2026-04-07.md b/docs/internal/slow-test-opportunities-2026-04-07.md
deleted file mode 100644
index 790a80c20..000000000
--- a/docs/internal/slow-test-opportunities-2026-04-07.md
+++ /dev/null
@@ -1,410 +0,0 @@
-# Slow Test Improvement Opportunities
-
-Date: 2026-04-07
-
-All measurements in this note were taken with `ulimit -n 4096` in the test subshell.
-
-Primary timing dataset:
-- `/tmp/fabro-slow-tests-ulimit.7FJkSO/slow_tests_passing.csv`
-- `/tmp/fabro-slow-tests-ulimit.7FJkSO/report_passing.txt`
-
-Passing suite baseline:
-- `cargo nextest run --workspace --no-fail-fast --status-level fail --final-status-level fail --show-progress none`
-- Result: `3631 passed, 182 skipped`
-
-Method:
-- Ranking is based on the 5-pass passing dataset above.
-- Impact estimates are aggregate median test-time reductions, not additive suite wall-clock reductions.
-- Where a number is inferred rather than directly measured, that is called out explicitly.
-
-## Top 10
-
-### [x] 1. Change two slow `exec` mock responses from retriable `500` to non-retriable `400`
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/exec.rs`
-
-Measured evidence:
-- `fabro-cli::it::cmd::exec::exec_cli_server_target_overrides_configured_server_target`: `6.858s` median
-- `fabro-cli::it::cmd::exec::exec_server_target_uses_remote_transport_instead_of_local_api_key_resolution`: `6.787s` median
-- Direct microbenchmark of the same CLI path:
- - mocked `500`: `7.49s` median
- - mocked `400`: `0.053s` median
-
-Implementation status:
-- Implemented in `lib/apps/fabro-cli/tests/it/cmd/exec.rs`
-- Verified with `ulimit -n 4096` via 5 targeted nextest runs per test
-- Post-change nextest exec-time medians:
- - `exec_server_target_uses_remote_transport_instead_of_local_api_key_resolution`: `1.580s`
- - `exec_cli_server_target_overrides_configured_server_target`: `1.563s`
-
-Estimated impact:
-- About `13.54s` aggregate median test time
-
-Complexity:
-- Low
-
-Pros:
-- Pure test change
-- Strongest measured single win
-- Keeps the same assertion shape if the response body marker is preserved
-
-Cons:
-- If retry-on-5xx coverage matters, keep one dedicated retry-focused test elsewhere
-
----
-
-### 2. Short-circuit delete-path worker grace for already-terminal runs
-
-Files:
-- `lib/apps/fabro-server/src/server.rs`
-
-Measured evidence:
-- `fabro-cli::it::cmd::system_prune::system_prune_yes_deletes_matching_runs`: `10.477s`
-- `fabro-cli::it::cmd::rm::rm_deletes_completed_run`: `5.359s`
-- `fabro-cli::it::cmd::rm::rm_partial_failure_reports_which_identifiers_failed`: `5.293s`
-- `fabro-cli::it::cmd::rm::rm_partial_failure_json_includes_removed_and_errors`: `5.257s`
-- `fabro-cli::it::cmd::rm::rm_force_deletes_run_without_sandbox_json_when_store_has_sandbox`: `5.275s`
-- Server code uses `WORKER_CANCEL_GRACE = 5s` in `terminate_worker_for_deletion()`
-
-Estimated impact:
-- Roughly `20-25s` aggregate across the measured completed-run delete tests
-- This is an inference from the timing cluster plus the `5s` grace, not a standalone delta benchmark
-
-Complexity:
-- Medium
-
-Pros:
-- Helps real behavior, not just tests
-- Likely addresses the single slowest test too
-
-Cons:
-- Needs careful correctness review around active worker shutdown semantics
-- Higher overlap with several delete-related tests
-
----
-
-### [x] 3. Collapse the five abnormally slow `help` integration tests into one smoke test or a lighter harness
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/artifact.rs`
-- `lib/apps/fabro-cli/tests/it/cmd/artifact_list.rs`
-- `lib/apps/fabro-cli/tests/it/cmd/artifact_cp.rs`
-- `lib/apps/fabro-cli/tests/it/cmd/config.rs`
-- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-
-Measured evidence:
-- Slow `help` tests:
- - `artifact_list::help`: `1.659s`
- - `artifact_cp::help`: `1.656s`
- - `artifact::help`: `1.640s`
- - `config::help`: `1.592s`
- - `attach::help`: `1.559s`
-- Aggregate median across those 5 tests: `8.106s`
-- Direct command timings:
- - `artifact list --help`: about `10ms`
- - `attach --help`: about `9ms`
- - `settings --help`: about `10ms`
-
-Estimated impact:
-- Conservative recoverable time: about `6.45s`
-
-Implementation status:
-- Implemented by removing the 5 command-owned help tests and replacing them with `scenario::smoke::help_smoke_covers_high_cost_commands`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli help_smoke_covers_high_cost_commands completion_smoke_covers_help_and_generation --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `2 passed`
-- Post-change timing over 5 targeted runs:
- - `fabro-cli::it::scenario::smoke::help_smoke_covers_high_cost_commands`: `2.164s` median
-
-Complexity:
-- Low
-
-Pros:
-- Pure harness cleanup
-- Clearly process/setup dominated rather than command-work dominated
-
-Cons:
-- Less granular failure reporting
-
----
-
-### [x] 4. Replace `doctor_no_color_when_no_color_set` with a render-path assertion
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/doctor.rs`
-- `lib/foundation/fabro-util/src/check_report.rs`
-
-Measured evidence:
-- `fabro-cli::it::cmd::doctor::doctor_no_color_when_no_color_set`: `5.131s`
-- Direct timing of `fabro doctor` under minimal test-like env: `5.115s`
-- Existing unit coverage already exercises no-color report rendering
-
-Estimated impact:
-- About `5.13s`
-
-Implementation status:
-- Implemented by deleting `fabro-cli::it::cmd::doctor::doctor_no_color_when_no_color_set`
-- Added a unit-level render assertion in `lib/apps/fabro-cli/src/commands/doctor.rs`:
- - `render_report_text_without_color_has_no_ansi`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli render_report_text_without_color_has_no_ansi --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `1 passed`
-- Removed median cost from the suite: `5.131s`
-
-Complexity:
-- Low to medium
-
-Pros:
-- Same intent can likely be covered without a full diagnostics run
-- Very high return for a single test
-
-Cons:
-- Slightly less end-to-end than the current test
-- Requires choosing the right lower-level render assertion
-
----
-
-### [x] 5. Fix local Unix-socket autostart so it doesn't burn the full 5s readiness wait
-
-Files:
-- `lib/apps/fabro-cli/src/server_client.rs`
-- `lib/apps/fabro-cli/tests/it/cmd/server_start.rs`
-
-Measured evidence:
-- Pre-fix 5-run timing for `fabro-cli::it::cmd::server_start::concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up`:
- - runs: `6.786998459`, `6.833243958`, `6.832145834`, `6.851452709`, `6.768980709`
- - median: `6.832s`
- - stdev: `0.035s`
-- Direct measurement showed the real bottleneck was not the test's polling loops:
- - two concurrent fresh `fabro --json settings` calls each took about `5.1s`
- - `fabro server stop --timeout 0` only took about `0.12s`
-- Root cause: the Unix-socket client was doing a full `wait_for_server_ready()` loop before attempting local autostart when no daemon was running
-
-Estimated impact:
-- Measured win on the original `server_start` test: about `5.02s`
-- This also speeds up other fresh local Unix-socket autostart paths that hit the same client logic
-
-Complexity:
-- Medium
-
-Pros:
-- Fixes a real product-path inefficiency instead of just shaving test harness overhead
-- Large win on the original slow test
-
-Cons:
-- Touched shared local-server connection logic, so verification needs to cover the autostart path itself
-
-Implementation status:
-- Implemented by splitting the Unix-socket connection path into:
- - a single immediate health probe before autostart
- - the existing retrying readiness wait after autostart
-- Kept the original integration test coverage in `lib/apps/fabro-cli/tests/it/cmd/server_start.rs`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `1 passed`
-- Post-change 5-run timing for `fabro-cli::it::cmd::server_start::concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up`:
- - runs: `1.801041000`, `1.812114833`, `1.760408750`, `1.817953958`, `1.958977916`
- - median: `1.812s`
- - stdev: `0.075s`
-- Aggregate measured change for the original test:
- - before: `6.832s`
- - after: `1.812s`
- - saved: `5.020s`
-- Direct post-change autostart probe across 3 fresh concurrent runs:
- - median process runtime: `0.092s`
- - stdev: `0.028s`
-
----
-
-### [x] 6. Collapse three lightweight `attach` smoke tests into one scenario-style test
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-
-Measured evidence:
-- `attach_requires_run_arg`: `1.595s`
-- `attach_uses_configured_server_target_without_server_flag`: `1.555s`
-- `attach_errors_when_live_stream_ends_before_terminal_event`: `1.629s`
-- Aggregate median: `4.779s`
-- Direct `fabro attach` parse-error path is about `12ms`
-
-Estimated impact:
-- Conservative recoverable time: about `3.15s`
-
-Implementation status:
-- Implemented by removing the 3 command-owned smoke tests from `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-- Added `fabro-cli::it::scenario::smoke::attach_smoke_covers_arg_validation_and_remote_server_behaviors`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_smoke_covers_arg_validation_and_remote_server_behaviors --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `1 passed`
-- Post-change timing over 5 targeted runs:
- - `fabro-cli::it::scenario::smoke::attach_smoke_covers_arg_validation_and_remote_server_behaviors`: `1.584s` median
-- Aggregate measured change for the full 3-test batch:
- - before: `4.779s` median test-time sum
- - after: `1.584s` median test-time sum
- - saved: `3.195s`
-
-Complexity:
-- Low to medium
-
-Pros:
-- Fits the user's preference for merging complex cmd coverage into more natural scenarios
-- Mostly harness/process cost
-
-Cons:
-- Bundles distinct failure modes together
-
----
-
-### [x] 7. Collapse the three `completion` tests
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/completion.rs`
-
-Measured evidence:
-- `completion::generates_zsh_completions`: `1.567s`
-- `completion::generates_fish_completions`: `1.566s`
-- `completion::help`: `1.564s`
-- Aggregate median: `4.697s`
-- Direct command timings:
- - `completion zsh`: about `13ms`
- - `completion fish`: about `13ms`
- - `completion --help`: about `10ms`
-
-Estimated impact:
-- Conservative recoverable time: about `3.13s`
-
-Implementation status:
-- Implemented by removing the 3 command-owned completion smoke tests and replacing them with `scenario::smoke::completion_smoke_covers_help_and_generation`
-- Post-change timing over 5 targeted runs:
- - `fabro-cli::it::scenario::smoke::completion_smoke_covers_help_and_generation`: `2.147s` median
-- Aggregate measured change for the full 8-test batch:
- - before: `12.803s` median test-time sum
- - after: `4.310s` median test-time sum
- - saved: `8.492s`
-
-Complexity:
-- Low
-
-Pros:
-- Very safe refactor
-- Strong evidence that cost is test harness overhead
-
-Cons:
-- Less granular failures if combined too aggressively
-
----
-
-### [x] 8. Remove or merge the duplicate attach replay test
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-
-Measured evidence:
-- `attach_replays_completed_detached_run`: `2.696s`
-- `attach_replays_from_store_without_run_json_or_progress_jsonl`: `2.675s`
-- The two tests are currently identical in code and assertions
-
-Implementation status:
-- Implemented by removing the duplicate test from `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_replays_completed_detached_run --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `1 passed`
-
-Estimated impact:
-- Immediate `2.675s` if the duplicate is removed
-
-Complexity:
-- Low
-
-Pros:
-- Full savings on one test
-- Strongest low-risk cleanup in `attach.rs`
-
-Cons:
-- If the intended missing-file case matters, the merged test should actually delete `run.json` / `progress.jsonl`
-
----
-
-### [x] 9. Make `attach_before_completion_streams_to_finished_state` event-driven instead of sleep-driven
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-
-Measured evidence:
-- `attach_before_completion_streams_to_finished_state`: `3.043s`
-- The test includes `sleep(Duration::from_secs(1))`
-- `write_gated_workflow()` adds another fixed `sleep 0.2`
-
-Implementation status:
-- Implemented by replacing the fixed 1-second gate-release sleep with a real attach-output signal in `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
-- The test now spawns `fabro attach`, waits for replayed stderr output (`✓ start`), then releases the workflow gate
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_before_completion_streams_to_finished_state --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `1 passed`
-- Isolated A/B benchmark over 5 targeted nextest runs with `ulimit -n 4096`, comparing the current workspace to a detached `HEAD` worktree using the same `CARGO_TARGET_DIR`:
- - before (`HEAD` sleep-driven test): `8.013s` median, `0.227s` stdev
- - after (current event-driven test): `6.933s` median, `0.016s` stdev
- - saved: `1.079s`
-
-Estimated impact:
-- Measured isolated saving: `1.079s`
-- Full-suite saving should be at least about `1.0s`
-
-Complexity:
-- Low
-
-Pros:
-- Removes an explicit fixed delay
-- Makes the test more deterministic
-
-Cons:
-- Overlaps with the broader gated-workflow helper improvement below
-
----
-
-### [x] 10. Remove or parameterize the fixed `sleep 0.2` in `write_gated_workflow()`
-
-Files:
-- `lib/apps/fabro-cli/tests/it/cmd/support.rs`
-
-Measured evidence:
-- `write_gated_workflow()` hardcodes `sleep 0.2`
-- The helper is used in 6 cmd tests
-
-Implementation status:
-- Implemented by deleting the fixed `sleep 0.2` from `write_gated_workflow()` in `lib/apps/fabro-cli/tests/it/cmd/support.rs`
-- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli -E 'test(attach_before_completion_streams_to_finished_state) | test(ctrl_c_cancels_active_run_via_server) | test(rm_force_terminates_active_run_worker) | test(start_rejects_already_active_or_completed_run) | test(start_runs_under_server_ownership_without_launcher_record)' --status-level fail --final-status-level fail --show-progress none`
-- Verification result: `5 passed`
-- Targeted 5-pass benchmark with `ulimit -n 4096` over the 5 tests that currently use the helper:
- - before: `24.783s` aggregate median test-time sum
- - after: `23.558s` aggregate median test-time sum
- - saved: `1.225s`
-- Per-test median deltas:
- - `attach_before_completion_streams_to_finished_state`: `1.977s -> 1.635s`
- - `ctrl_c_cancels_active_run_via_server`: `6.781s -> 6.681s`
- - `rm_force_terminates_active_run_worker`: `11.984s -> 11.876s`
- - `start_rejects_already_active_or_completed_run`: `2.041s -> 1.684s`
- - `start_runs_under_server_ownership_without_launcher_record`: `2.000s -> 1.682s`
-
-Estimated impact:
-- Measured aggregate saving across current helper users: `1.225s`
-
-Complexity:
-- Low
-
-Pros:
-- Small suite-wide gain
-- Straightforward helper cleanup
-
-Cons:
-- Overlaps slightly with item 9
-
-## Notes On Excluded Ideas
-
-- I did not rank broad `rm` test consolidation highly on its own because the dominant cost appears to be the delete path itself, not just fixture setup.
-- I did not rank `system_prune_dry_run_lists_matching_runs_without_deleting` because it is already fast at `0.183s`; the expensive case is specifically `--yes`.
-- I did not rank `attach_json_errors_without_prompting_for_human_input` higher than item 8 because it is clearly slow (`6.882s`) but I did not finish a direct before/after measurement for replacing its `logs --json` polling loop with direct event-store polling.
-
-## Suggested First Pass
-
-If optimizing for highest impact with lowest complexity:
-
-1. Change the two slow `exec` tests to use non-retriable mock statuses
-2. Remove or fix the duplicate attach replay test
-3. Collapse the slow `help` / `completion` smoke tests into lighter coverage
diff --git a/docs/plans/2026-04-02-001-feat-server-daemon-management-plan.md b/docs/plans/2026-04-02-001-feat-server-daemon-management-plan.md
deleted file mode 100644
index d336646f3..000000000
--- a/docs/plans/2026-04-02-001-feat-server-daemon-management-plan.md
+++ /dev/null
@@ -1,446 +0,0 @@
----
-title: "feat: Add server daemon management with Unix socket support"
-type: feat
-status: completed
-date: 2026-04-02
-deepened: 2026-04-02
----
-
-# feat: Add server daemon management with Unix socket support
-
-## Overview
-
-Transform `fabro server` from a foreground-only TCP server into a proper daemon with background/foreground modes, stop/status lifecycle commands, Unix socket binding, and flock-based locking to prevent thundering herd when multiple CLI invocations auto-start the server.
-
-## Problem Frame
-
-The fabro server currently runs only in the foreground on a TCP port. Users must manually manage the process lifecycle. There is no way to check if a server is running, stop it gracefully, or prevent duplicate instances. When the CLI eventually auto-starts the server on demand, concurrent CLI invocations could race to start multiple servers simultaneously.
-
-## Requirements Trace
-
-- R1. `fabro server start` launches as a background daemon by default
-- R2. `fabro server start --foreground` retains current blocking behavior
-- R3. `fabro server stop` sends SIGTERM, waits, escalates to SIGKILL
-- R4. `fabro server status` reports running/stopped with PID, bind address, uptime
-- R5. A JSON server record tracks PID and metadata; stale records are auto-cleaned
-- R6. `--bind` replaces `--host`/`--port`, supporting both Unix sockets and TCP addresses
-- R7. Default bind is `{storage_dir}/fabro.sock` (Unix socket)
-- R8. flock-based locking prevents concurrent start attempts (thundering herd)
-- R9. Only one server instance can run at a time per storage directory
-- R10. TLS is not supported on Unix sockets (only on TCP)
-
-## Scope Boundaries
-
-- No systemd/launchd integration (out of scope)
-- No log rotation or `server logs` subcommand beyond basic prev-file rotation (future work)
-- Breaking change: `--host` and `--port` are removed, replaced by `--bind`
-- Client-side Unix socket connectivity (TypeScript Axios client, CLI-to-server calls) is tracked as a follow-up concern -- this plan covers the server side only
-
-## Context & Research
-
-### Relevant Code and Patterns
-
-- `lib/crates/fabro-cli/src/commands/run/launcher.rs` -- JSON-based launcher records with PID tracking, stale detection via `process_alive()` + `ps` command-line matching, lazy cleanup on read
-- `lib/crates/fabro-cli/src/commands/run/start.rs` -- Self-re-exec pattern: spawns `fabro __detached` with `pre_exec_setsid`, stdout/stderr to log file, writes record after spawn, checks `try_wait()` for immediate failure, forwards `--storage-dir` to child
-- `lib/crates/fabro-cli/src/commands/run/detached.rs` -- `scopeguard::guard(launcher_path, remove_launcher_record)` for guaranteed cleanup on exit; `title_init()`/`title_set()` for proctitle; receives record path via `--launcher-path` arg
-- `lib/crates/fabro-proc/src/` -- `process_alive`, `sigterm`, `sigkill`, `pre_exec_setsid`, `title_init`/`title_set`. All functions are thin libc wrappers -- no retry loops or higher-level logic
-- `lib/crates/fabro-server/src/serve.rs` -- Current `serve_command()` with `ServeArgs`, config polling, webhook manager lifecycle. No graceful shutdown wired. TLS path uses manual `loop { listener.accept() }` via `hyper_util`, not `axum::serve`
-- `lib/crates/fabro-cli/src/args.rs:650` -- `#[command(name = "__detached", hide = true)]` hidden subcommand pattern with its own args struct
-- `lib/crates/fabro-cli/src/args.rs:972-984` -- `ServerNamespace`/`ServerCommand` enum
-- `lib/crates/fabro-cli/src/main.rs:108-195` -- Config log level extraction and command dispatch for server
-
-### Institutional Learnings
-
-No `docs/solutions/` directory exists. Patterns are embedded in the launcher record system.
-
-## Key Technical Decisions
-
-- **Hidden subcommand for daemon child, not a flag**: The daemon spawns `fabro server __serve --record-path --bind ...` as a detached child. `__serve` is a hidden `ServerCommand` variant with its own args struct, matching the `__detached` pattern in `RunCommands`. This keeps `ServeArgs` focused on server runtime concerns and process lifecycle in `fabro-cli`.
-
-- **Process lifecycle stays in fabro-cli**: `fabro-server` has no dependency on `fabro-proc` and should not gain one. A `foreground.rs` in `fabro-cli/src/commands/server/` wraps `serve_command()` with record writes, scopeguard cleanup, and proctitle management -- same boundary as `detached.rs` wrapping workflow operations.
-
-- **Record ownership: parent writes, child cleans up**: In daemon mode, the parent writes `server.json` after spawn (and cleans up on failure). The child receives the record path via `--record-path` and sets up a `scopeguard` to remove it on exit. This matches the launcher record ownership model exactly.
-
-- **Server record, not bare PID file**: A JSON `ServerRecord` (pid, bind: Bind, log_path, started_at) stored at `{storage_dir}/server.json`, following the `LauncherRecord` pattern. The `bind` field uses the `Bind` enum (not a raw string) so consumers get type-safe access without re-parsing. Enables `status` to report rich info and supports PID-command-line validation against PID reuse.
-
-- **flock on a separate lock file**: `{storage_dir}/server.lock` is acquired with `LOCK_EX | LOCK_NB` before any start attempt. Losers of the race block on the lock (with timeout), then discover the server already running. The lock file is separate from `server.json` so the record can be atomically rewritten without interfering with the lock. `flock()` auto-releases on process crash.
-
-- **Keep fabro-proc thin**: Only `try_flock_exclusive(file) -> io::Result` goes in `fabro-proc` (thin libc wrapper). The timeout/retry loop lives in the caller (`server/start.rs`), consistent with every other function in `fabro-proc` being a single-syscall wrapper.
-
-- **`Bind` enum defined in fabro-server**: A `Bind` enum (`Bind::Unix(PathBuf) | Bind::Tcp(SocketAddr)`) lives in `fabro-server` since it's a server concern ("what am I binding to?"). Used in both `ServeArgs` resolution and `ServerRecord`. Serializes cleanly via serde tagged enum: `{"unix": "/path"}` or `{"tcp": "127.0.0.1:3000"}`. Consumers (stop, status) can match on the variant directly instead of re-parsing a string -- e.g., `stop` knows to clean up the socket file when `bind` is `Bind::Unix`.
-
-- **Bind address parsing**: `parse_bind(s: &str) -> Result` in `fabro-server`. If the value contains `/`, it's a Unix socket path. Otherwise it's `host:port` TCP. Default: `{storage_dir}/fabro.sock`. Unix socket paths are validated against the 104-byte limit on macOS (108 on Linux).
-
-- **Graceful shutdown via SIGTERM handler**: Wire `tokio::signal::unix::signal(SignalKind::terminate())` into `axum::serve().with_graceful_shutdown()`. The foreground mode also handles SIGINT (ctrl-c). **Known limitation:** The TLS codepath uses a manual `loop { listener.accept() }` via `hyper_util` and cannot use `with_graceful_shutdown`. Under TLS, `server stop` will rely on SIGTERM causing process exit (default behavior) but may need SIGKILL escalation. This is acceptable for now.
-
-- **Process title includes bind address**: `fabro: server {bind}` to support PID-command-line validation and disambiguate if the single-instance invariant ever relaxes.
-
-- **No TLS on Unix sockets**: When bind is a Unix socket, skip the TLS codepath entirely. TLS only applies to TCP binds.
-
-- **Log rotation on start**: Rename existing `server.log` to `server.log.prev` before starting, so crash diagnostics from the previous run are preserved.
-
-## Open Questions
-
-### Resolved During Planning
-
-- **Where does flock live?** Only `try_flock_exclusive` in `fabro-proc` (thin wrapper). Timeout loop in caller.
-- **Default bind address?** `{storage_dir}/fabro.sock` (Unix socket). Resolved storage dir is used so it respects `--storage-dir` and config overrides.
-- **How does the parent know the daemon is ready?** Poll-connect to the socket/port with a short timeout (up to 5s). Same approach as pg_ctl.
-- **What happens to TLS + Unix socket?** Not supported. If `--bind` is a socket path and TLS is configured, emit a warning and skip TLS.
-- **Hidden flag or hidden subcommand?** Hidden subcommand (`__serve`), matching the `__detached` pattern. Not a flag on `ServeArgs`.
-- **Where does process lifecycle code live?** In `fabro-cli/src/commands/server/`, not in `fabro-server`. Same boundary as `detached.rs`.
-- **Client connectivity with Unix socket default?** Tracked as follow-up -- this plan covers server-side only. The `server.json` record stores the bind address so clients can discover it.
-
-### Deferred to Implementation
-
-- Exact readiness polling interval and timeout values (start with 50ms interval, 5s timeout)
-- Whether `server stop` should print tail of server.log on timeout before SIGKILL
-- Exact chmod permissions on the Unix socket file (start with default, tighten if needed)
-
-## High-Level Technical Design
-
-> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
-
-```
- fabro server start
- |
- acquire flock(server.lock)
- / \
- (got lock) (blocked)
- | |
- read server.json wait for lock (retry loop in start.rs)
- / \ |
- (live pid) (none/stale) (got lock)
- | | |
- "already rotate server.log -> server.log.prev
- running" spawn: fabro server __serve --record-path ... --bind ...
- exit 1 pre_exec_setsid, stdout/stderr -> server.log
- |
- parent: write server.json with child PID
- parent: poll-connect to bind address
- / \
- (connected) (timeout)
- | |
- exit 0 print error + log tail
- clean up server.json
- exit 1
-
- fabro server __serve --record-path --bind ...
- |
- title_init() + title_set("fabro: server ")
- scopeguard(record_path, remove_server_record)
- register SIGTERM/SIGINT shutdown
- |
- bind listener (Unix or TCP)
- axum::serve(...).with_graceful_shutdown(...)
- |
- (on shutdown signal)
- scopeguard fires: remove server.json
- remove socket file (if Unix)
-```
-
-```mermaid
-graph TB
- U1[Unit 1: flock in fabro-proc]
- U2[Unit 2: ServerRecord]
- U3[Unit 3: Bind enum + --bind + Unix socket]
- U4[Unit 4: daemon spawn + __serve]
- U5[Unit 5: server stop]
- U6[Unit 6: server status]
- U7[Unit 7: main.rs dispatch]
-
- U1 --> U4
- U3 --> U2
- U2 --> U4
- U2 --> U5
- U2 --> U6
- U3 --> U4
- U4 --> U7
- U5 --> U7
- U6 --> U7
-```
-
-Units 1 and 3 can run in parallel. Unit 2 depends on Unit 3 (for the `Bind` enum type). Units 5 and 6 can run in parallel after Unit 2. Unit 7 ties everything together.
-
-## Implementation Units
-
-- [x] **Unit 1: Add flock wrapper to fabro-proc**
-
- **Goal:** Provide `try_flock_exclusive` in `fabro-proc` as a thin libc wrapper for advisory file locking.
-
- **Requirements:** R8
-
- **Dependencies:** None
-
- **Files:**
- - Create: `lib/crates/fabro-proc/src/flock.rs`
- - Modify: `lib/crates/fabro-proc/src/lib.rs`
- - Test: `lib/crates/fabro-proc/src/flock.rs` (inline tests)
-
- **Approach:**
- - `try_flock_exclusive(file: &File) -> io::Result` -- `libc::flock(fd, LOCK_EX | LOCK_NB)`, returns `Ok(false)` on `EWOULDBLOCK`
- - `flock_unlock(file: &File) -> io::Result<()>` -- `libc::flock(fd, LOCK_UN)` for explicit unlock
- - Unix-only (`#[cfg(unix)]`), consistent with existing `fabro-proc` gating
- - No retry loops or timeout logic -- keep this crate at the syscall-wrapper level
-
- **Patterns to follow:**
- - `lib/crates/fabro-proc/src/signal.rs` -- same style: thin wrapper over libc, `#[cfg(unix)]` gating, pub functions re-exported from `lib.rs`
- - `lib/crates/fabro-proc/src/pre_exec.rs` -- unsafe block style and safety comments
-
- **Test scenarios:**
- - Happy path: acquire lock on a temp file, confirm returns true
- - Happy path: release lock (drop file), re-acquire succeeds
- - Edge case: try_flock_exclusive on already-locked file (held by another fd) returns Ok(false)
-
- **Verification:**
- - `cargo nextest run -p fabro-proc` passes
- - `cargo clippy -p fabro-proc -- -D warnings` clean
-
-- [x] **Unit 2: Add ServerRecord and lifecycle helpers**
-
- **Goal:** Create a `ServerRecord` struct with read/write/remove/is_running helpers, mirroring `LauncherRecord`.
-
- **Requirements:** R5, R9
-
- **Dependencies:** Unit 3 (for `Bind` enum type)
-
- **Files:**
- - Create: `lib/crates/fabro-cli/src/commands/server/record.rs`
- - Create: `lib/crates/fabro-cli/src/commands/server/mod.rs`
- - Modify: `lib/crates/fabro-cli/src/commands/mod.rs` (add `pub(crate) mod server;` gated with `#[cfg(feature = "server")]`)
-
- **Approach:**
- - `ServerRecord { pid: u32, bind: Bind, log_path: PathBuf, started_at: DateTime }` where `Bind` is the enum from `fabro-server` (Unit 3). The `bind` field serializes as a tagged enum (`{"unix": "/path"}` or `{"tcp": "127.0.0.1:3000"}`), giving consumers type-safe access -- e.g., `stop` matches on `Bind::Unix` to know it should remove the socket file
- - Paths: `server_record_path(storage_dir) -> {storage_dir}/server.json`, `server_lock_path(storage_dir) -> {storage_dir}/server.lock`, `server_log_path(storage_dir) -> {storage_dir}/server.log`
- - `server_record_is_running(record) -> bool` -- `process_alive(pid)` + `ps` command-line match for "fabro" and "server"
- - `active_server_record(storage_dir) -> Option` -- read, check liveness, lazy-clean stale
- - Path helpers only -- lock acquisition logic lives in Unit 4
-
- **Patterns to follow:**
- - `lib/crates/fabro-cli/src/commands/run/launcher.rs` -- identical record lifecycle pattern: `write_*`, `read_*`, `remove_*`, `*_is_running`, `active_*`
-
- **Test scenarios:**
- - Happy path: write record, read it back, fields match
- - Happy path: active_server_record returns None when no record file exists
- - Edge case: active_server_record returns None and removes file when PID is dead (use pid u32::MAX)
- - Edge case: active_server_record returns None and removes file when process doesn't match command-line check
-
- **Verification:**
- - `cargo nextest run -p fabro-cli` for the new module's tests pass
-
-- [x] **Unit 3: Add Bind enum, replace --host/--port with --bind, add Unix socket listener**
-
- **Goal:** Define the `Bind` enum as the shared type for bind addresses. Change `ServeArgs` to use `--bind` instead of `--host`/`--port`. Support both Unix socket and TCP binding in `serve_command`. Wire graceful shutdown.
-
- **Requirements:** R6, R7, R10
-
- **Dependencies:** None (parallel with Unit 1)
-
- **Files:**
- - Create: `lib/crates/fabro-server/src/bind.rs` (Bind enum + parse_bind + Display impl)
- - Modify: `lib/crates/fabro-server/src/lib.rs` (pub mod bind)
- - Modify: `lib/crates/fabro-server/src/serve.rs`
- - Modify: `lib/crates/fabro-server/Cargo.toml` (ensure tokio `net` feature includes unix support)
- - Modify: `lib/crates/fabro-cli/src/main.rs` (update dispatch if ServeArgs shape changes)
- - Test: `lib/crates/fabro-server/tests/it/api.rs` (update any tests using --host/--port)
- - Test: `lib/crates/fabro-server/src/bind.rs` (inline tests for parse_bind)
-
- **Approach:**
- - Define `Bind` enum in `bind.rs`: `Bind::Unix(PathBuf) | Bind::Tcp(SocketAddr)` with `Serialize`/`Deserialize` (serde tagged enum), `Display`, `Clone`, `Debug`, `PartialEq`. This type is used by both `serve_command` and `ServerRecord` (Unit 2)
- - `parse_bind(bind: &str) -> Result`. Contains `/` -> Unix socket; otherwise `host:port` parsed as `SocketAddr`. Validate Unix socket path length (104 bytes on macOS, 108 on Linux)
- - `Bind::display()` shows the address for human-readable output (used in proctitle, status, logs)
- - Replace `--host` and `--port` on `ServeArgs` with `--bind` (`Option`, no default in clap -- default computed at runtime from resolved storage dir using the socket path)
- - In `serve_command`, branch on `Bind` variant: `UnixListener::bind` vs `TcpListener::bind`
- - For Unix sockets: remove stale socket file before bind, skip TLS codepath (log warning if TLS configured)
- - Wire `axum::serve(listener, router).with_graceful_shutdown(shutdown_signal())` for the non-TLS path, where `shutdown_signal` awaits SIGTERM or SIGINT. **Note:** The TLS path (`serve_tls`) uses a manual accept loop and cannot use `with_graceful_shutdown` -- document as known limitation, SIGTERM will still cause process exit
- - Derive `Clone` on `ServeArgs` to simplify the config polling task (currently manually clones each field)
-
- **Patterns to follow:**
- - Current `serve.rs` listener binding and axum::serve pattern
- - Axum 0.8 supports `UnixListener` directly via `axum::serve`
-
- **Test scenarios:**
- - Happy path: parse_bind with "127.0.0.1:3000" returns Tcp variant
- - Happy path: parse_bind with "/tmp/fabro.sock" returns Unix variant
- - Edge case: parse_bind with invalid address returns error
- - Edge case: parse_bind with path exceeding 104 bytes returns error on macOS
- - Happy path: server binds to Unix socket and accepts HTTP requests over it
- - Happy path: server binds to TCP address (existing behavior preserved)
- - Edge case: stale socket file is removed before binding
- - Integration: graceful shutdown on SIGTERM -- server stops accepting connections and exits cleanly
-
- **Verification:**
- - `cargo nextest run -p fabro-server` passes
- - Existing server tests still pass (adapted for --bind)
-
-- [x] **Unit 4: Add daemon spawn, __serve hidden subcommand, and foreground wrapper**
-
- **Goal:** Make `server start` launch a background daemon by default. `--foreground` retains current behavior. Both modes write/clean server records. Daemon mode uses flock to prevent thundering herd. `__serve` is the hidden subcommand the daemon child runs.
-
- **Requirements:** R1, R2, R8, R9
-
- **Dependencies:** Units 1, 2, 3
-
- **Files:**
- - Create: `lib/crates/fabro-cli/src/commands/server/start.rs` (daemon spawn logic + flock retry loop)
- - Create: `lib/crates/fabro-cli/src/commands/server/foreground.rs` (wraps `serve_command` with record lifecycle, scopeguard, proctitle)
- - Modify: `lib/crates/fabro-cli/src/args.rs` (add `__Serve` hidden variant to `ServerCommand` with its own args struct; add `--foreground` flag to `Start` variant args)
- - Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs` (dispatch)
-
- **Approach:**
- - **`ServerCommand::__Serve(ServeChildArgs)`**: Hidden subcommand with `--record-path`, `--bind`, plus forwarded args (`--model`, `--provider`, `--dry-run`, `--sandbox`, `--max-concurrent-runs`, `--config`, `--storage-dir`). Dispatches to `foreground.rs`.
- - **`foreground.rs`**: `title_init()` + `title_set("fabro: server {bind}")`, `scopeguard::guard(record_path, remove_server_record)`, then calls `serve_command()`. Mirrors `detached.rs` wrapping workflow operations.
- - **`start.rs` daemon path**: Open `server.lock`, retry `try_flock_exclusive` in a loop (50ms intervals, 5s timeout); check `active_server_record`; if running, print "already running" and exit 1; rotate `server.log` to `server.log.prev`; spawn self with `fabro server __serve --record-path --bind ...` using `pre_exec_setsid`, stdout/stderr to `server.log`, stdin null, `env_remove("FABRO_JSON")`; write `server.json` with child PID; check `try_wait()` for immediate failure; poll-connect to bind address (50ms intervals, 5s timeout); on success print `"server started (pid N) on "`, exit 0; on failure print error + tail of log, clean up, exit 1
- - **`start.rs` foreground path** (`--foreground`): Write `server.json`, register scopeguard for cleanup, then call `serve_command()` directly (no re-exec)
- - **Forward all relevant args to child**: `--storage-dir`, `--config`, `--model`, `--provider`, `--dry-run`, `--sandbox`, `--max-concurrent-runs`
-
- **Patterns to follow:**
- - `lib/crates/fabro-cli/src/commands/run/start.rs` -- self-re-exec with `pre_exec_setsid`, log redirect, record write, `try_wait` check, `--storage-dir` forwarding, `env_remove("FABRO_JSON")`
- - `lib/crates/fabro-cli/src/commands/run/detached.rs` -- `scopeguard` cleanup, `title_init`/`title_set`, receives record path via arg
- - `lib/crates/fabro-cli/src/args.rs:650` -- `#[command(name = "__detached", hide = true)]` pattern
-
- **Test scenarios:**
- - Happy path: `server start` spawns daemon, writes server.json, exits 0
- - Happy path: `server start --foreground` runs in foreground, writes server.json, cleans up on exit
- - Edge case: `server start` when already running prints "already running" and exits 1
- - Edge case: `server start` with stale server.json (dead PID) cleans up and starts fresh
- - Happy path: flock prevents concurrent start -- second caller waits and finds server running
- - Edge case: daemon fails to start (bad bind address) -- parent reports error, cleans up record
- - Edge case: daemon child exits immediately -- parent detects via try_wait, reports error
- - Integration: after daemon start, server.json contains correct PID and bind address
- - Integration: server.log.prev contains previous log content after restart
-
- **Verification:**
- - `cargo nextest run -p fabro-cli` passes
- - Manual: `fabro server start` starts daemon, `fabro server start` again says "already running"
-
-- [x] **Unit 5: Add server stop subcommand**
-
- **Goal:** `fabro server stop` sends SIGTERM, waits for graceful exit, escalates to SIGKILL, cleans up.
-
- **Requirements:** R3
-
- **Dependencies:** Unit 2
-
- **Files:**
- - Create: `lib/crates/fabro-cli/src/commands/server/stop.rs`
- - Modify: `lib/crates/fabro-cli/src/args.rs` (add `Stop` variant to `ServerCommand` with `StopArgs { timeout }`)
- - Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs`
-
- **Approach:**
- - Read `active_server_record` -- if None, print "not running", exit 1
- - `fabro_proc::sigterm(pid)`
- - Poll `process_alive(pid)` at 100ms intervals up to `--timeout` (default 10s)
- - If still alive after timeout, `fabro_proc::sigkill(pid)`
- - Remove `server.json` and socket file (match on `record.bind` -- if `Bind::Unix(path)`, remove the socket file)
- - Print "server stopped"
-
- **Patterns to follow:**
- - `fabro_proc::sigterm`/`sigkill`/`process_alive` for signal management
- - `launcher.rs::remove_launcher_record` for cleanup
-
- **Test scenarios:**
- - Happy path: stop a running server -- sends SIGTERM, process exits, record cleaned up
- - Edge case: stop when not running -- prints "not running", exits 1
- - Edge case: stop with stale record (dead PID) -- cleans up record, prints "not running", exits 1
- - Edge case: process doesn't exit within timeout -- escalates to SIGKILL
- - Happy path: Unix socket file is removed after stop
-
- **Verification:**
- - `cargo nextest run -p fabro-cli` passes
- - Manual: `fabro server start && fabro server stop` completes cleanly
-
-- [x] **Unit 6: Add server status subcommand**
-
- **Goal:** `fabro server status` reports running/stopped state with metadata. Supports `--json`.
-
- **Requirements:** R4
-
- **Dependencies:** Unit 2
-
- **Files:**
- - Create: `lib/crates/fabro-cli/src/commands/server/status.rs`
- - Modify: `lib/crates/fabro-cli/src/args.rs` (add `Status` variant to `ServerCommand` with `StatusArgs { json }`)
- - Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs`
-
- **Approach:**
- - Read `active_server_record` -- if None, print "not running", exit 1
- - Compute uptime from `started_at`
- - Human output: `"running (pid N) on , started X ago"`
- - `--json`: `{ "status": "running", "pid": N, "bind": "...", "started_at": "...", "uptime_seconds": N }`
- - Exit code: 0 = running, 1 = not running (same as `pg_ctl status`)
-
- **Patterns to follow:**
- - Other CLI commands that support `--json` output (check `globals.json` usage pattern)
-
- **Test scenarios:**
- - Happy path: status when running -- prints info, exits 0
- - Happy path: status --json when running -- outputs valid JSON with expected fields
- - Edge case: status when not running -- prints "not running", exits 1
- - Edge case: status with stale record -- cleans up, prints "not running", exits 1
-
- **Verification:**
- - `cargo nextest run -p fabro-cli` passes
-
-- [x] **Unit 7: Update main.rs dispatch and config loading for new server subcommands**
-
- **Goal:** Wire all server subcommands (start, stop, status, __serve) into CLI dispatch. Fix config log level extraction to handle new ServerCommand variants.
-
- **Requirements:** R1, R2, R3, R4
-
- **Dependencies:** Units 4, 5, 6
-
- **Files:**
- - Modify: `lib/crates/fabro-cli/src/main.rs`
- - Modify: `lib/crates/fabro-cli/src/args.rs` (update `Commands::name()` match arm for all new variants)
-
- **Approach:**
- - Change `let ServerCommand::Start(args) = ns.command;` to `match ns.command { Start(..) => ..., Stop(..) => ..., Status(..) => ..., __Serve(..) => ... }` in both the config log level block and the dispatch block
- - `__Serve` and `Start` (when in foreground/daemon mode) load server settings for log level; `Stop` and `Status` load user settings
- - Update `Commands::name()` to return `"server start"`, `"server stop"`, `"server status"`, `"server __serve"` for telemetry
- - Log prefix: `"server"` for `Start`/`__Serve`, `"cli"` for `Stop`/`Status`
- - `#[cfg(feature = "server")]` gating on all new paths
-
- **Patterns to follow:**
- - Existing dispatch pattern in `main.rs` for other namespace commands (e.g., `Commands::RunCmd`)
- - Feature gating on all server references
-
- **Test scenarios:**
- - Happy path: `fabro server stop --help` prints help text
- - Happy path: `fabro server status --help` prints help text
- - Happy path: `fabro server start --help` still works with new --bind flag and --foreground flag
- - Happy path: telemetry name returns correct values for each subcommand
-
- **Verification:**
- - `cargo nextest run -p fabro-cli` passes (including existing server tests)
- - `cargo clippy --workspace -- -D warnings` clean
-
-## System-Wide Impact
-
-- **Interaction graph:** `serve_command()` gains a graceful shutdown signal handler. A new `foreground.rs` wrapper in `fabro-cli` manages server record lifecycle around `serve_command()`. Config polling task and webhook manager lifecycle preserved unchanged. Webhook manager shutdown (line 274-277 of `serve.rs`) becomes reachable for the first time via graceful shutdown -- the existing code is correct but the implementing agent should not add a scopeguard that drops the tokio runtime before async shutdown runs.
-- **Error propagation:** Daemon start failures surface to the parent via poll-connect timeout + log tail. Stop failures surface via exit code.
-- **State lifecycle risks:** Stale `server.json` after crash -- mitigated by PID liveness + command-line check on every read, with lazy cleanup (same proven pattern as launcher records). Stale socket file -- removed before bind attempt.
-- **API surface parity:** The `--bind` change is breaking for anyone using `--host`/`--port`. No API endpoint changes. Client-side connectivity to Unix sockets (TypeScript Axios client, CLI HTTP calls) is not addressed in this plan and needs follow-up.
-- **Integration coverage:** Unit tests can verify record lifecycle and parse_bind. Integration tests should cover the full start/status/stop cycle with a real server process.
-- **Unchanged invariants:** All HTTP routes, auth, config reloading, webhook manager, and SSE streaming behavior are unchanged. The server's runtime behavior is identical once it's listening.
-
-## Risks & Dependencies
-
-| Risk | Mitigation |
-|------|------------|
-| PID reuse after crash leads to signaling wrong process | Two-phase check: `process_alive` + `ps` command-line matching for "fabro" and "server" with bind address in proctitle, same proven pattern as launcher records |
-| flock not supported on all filesystems (e.g., NFS) | Storage dir is local by convention (~/.fabro). Document that network filesystems are unsupported for storage |
-| Unix socket path exceeds 104-byte limit on macOS | `parse_bind` validates path length at parse time with a clear error message |
-| Axum 0.8 UnixListener support | Axum 0.8 is already the workspace version; `serve()` accepts `UnixListener` natively |
-| Breaking --host/--port removal | Acceptable per scope decision. Users see a clear clap error pointing to --bind |
-| Race between parent writing server.json and child exiting | Check `try_wait()` immediately after spawn (same pattern as `start.rs`); if child already exited, clean up and report error |
-| TLS path lacks graceful shutdown | Documented as known limitation. SIGTERM still causes process exit; stop command escalates to SIGKILL after timeout. TLS + daemon is an uncommon combination |
-| Client-side code assumes TCP | Tracked as follow-up. Server record stores bind address for client discovery |
-
-## Sources & References
-
-- Related code: `lib/crates/fabro-cli/src/commands/run/launcher.rs`, `lib/crates/fabro-cli/src/commands/run/start.rs`, `lib/crates/fabro-cli/src/commands/run/detached.rs`
-- Related code: `lib/crates/fabro-proc/src/signal.rs`, `lib/crates/fabro-proc/src/pre_exec.rs`
-- Related code: `lib/crates/fabro-server/src/serve.rs`
-- Related code: `lib/crates/fabro-cli/src/args.rs:650` (`__detached` hidden subcommand pattern), `lib/crates/fabro-cli/src/args.rs:972-984` (`ServerCommand`)
-- Related code: `lib/crates/fabro-cli/src/main.rs:108-195`
diff --git a/docs/plans/2026-04-02-002-feat-http-store-client-auto-start-plan.md b/docs/plans/2026-04-02-002-feat-http-store-client-auto-start-plan.md
deleted file mode 100644
index c63ad7c81..000000000
--- a/docs/plans/2026-04-02-002-feat-http-store-client-auto-start-plan.md
+++ /dev/null
@@ -1,566 +0,0 @@
----
-title: "feat: auto-start server and route CLI store access over HTTP"
-type: feat
-status: active
-date: 2026-04-02
-origin: docs/ideation/2026-04-02-slatedb-consolidation-ideation.md
-deepened: 2026-04-04
----
-
-# feat: auto-start server and route CLI store access over HTTP
-
-## Overview
-
-Phase 1 replaces direct CLI access to SlateDB with a Unix-socket HTTP client that talks to `fabro server`, and auto-starts that daemon whenever CLI store access is needed. Use the generated `fabro-api` Rust client as the transport surface where the existing API already matches the needed operations.
-
-Phase 2 is an explicit follow-on decision: if we require strict single-owner semantics for all workflow execution writes, detached/start/resume execution must also move under server ownership rather than remaining in CLI-spawned engine processes.
-
-## Problem Frame
-
-The old plan assumed most of the HTTP surface and daemon infrastructure still needed to be built. That is no longer true.
-
-Current state in the repo:
-
-- Server daemon management is already implemented in `fabro-cli`:
- - `lib/crates/fabro-cli/src/commands/server/start.rs`
- - `lib/crates/fabro-cli/src/commands/server/record.rs`
-- Unix socket bind support is already implemented in `fabro-server`:
- - `lib/crates/fabro-server/src/serve.rs`
- - `lib/crates/fabro-server/src/bind.rs`
-- The server already owns a single `SlateStore` instance and already exposes store-backed endpoints for:
- - run state
- - events
- - live event attach over SSE
- - blobs
- - checkpoint
- - retro
- - stage artifacts
-- The generated `fabro-api` client is reqwest-based and can be constructed with a custom `reqwest::Client`.
-- Reqwest 0.13 in this repo supports Unix sockets via `ClientBuilder::unix_socket(...)`.
-
-The real remaining work is narrower:
-
-1. CLI store access still opens `SlateStore` directly from local disk.
-2. CLI does not auto-start the server when store access is needed.
-3. Some API gaps remain, especially durable run listing and durable run deletion.
-4. Several CLI command paths still assume local engine processes own workflow execution and store writes.
-
-## Requirements Trace
-
-- R1. CLI commands that need store access auto-start `fabro server` when no active daemon is available.
-- R2. CLI store reads and writes stop opening SlateDB directly and instead use the server over HTTP via Unix socket.
-- R3. `fabro server` becomes the only process that opens SlateDB for migrated CLI store-access flows in phase 1, with full execution-path consolidation tracked separately in Unit 6 if strict single-owner semantics remain required.
-- R4. The generated `fabro-api` Rust client is used for server communication where its current API surface applies.
-- R5. Existing `InMemoryStore`-based tests and server-internal `SlateStore` usage remain unaffected.
-- R6. Event streaming remains live and efficient for attach/log-follow workflows.
-- R7. Binary transfer for blobs and artifacts remains raw bytes over HTTP.
-- R8. Error messages for server startup and server-unreachable cases are explicit and actionable.
-- R9. The plan must reflect the current repo state rather than the assumptions in the original 2026-04-02 draft.
-
-## Scope Boundaries
-
-In scope:
-
-- CLI auto-start of the local server daemon
-- HTTP-backed client access for CLI store consumers
-- Server API additions needed for store parity
-- Migration of CLI run discovery, logs/attach, blob/artifact access, and delete flows to server-backed access
-
-Out of scope for the first pass:
-
-- TypeScript/web client changes
-- Replacing server-internal `SlateStore`
-- Removing local run directories or runtime files
-- Re-architecting workflow execution to be fully server-owned in the same change set
-- Full trait refactors across `fabro-workflow` unless they are required to unblock the CLI migration
-
-Follow-on scope, likely separate plan or addressed by Unit 6's decision fork:
-
-- Consolidating detached/resume/start execution so workflow engine writes are also server-owned end-to-end
-
-## Current-State Audit
-
-### Already Implemented
-
-- Daemon lifecycle:
- - `lib/crates/fabro-cli/src/commands/server/start.rs`
- - `lib/crates/fabro-cli/src/commands/server/status.rs`
- - `lib/crates/fabro-cli/src/commands/server/stop.rs`
- - `lib/crates/fabro-cli/src/commands/server/record.rs`
-- Unix socket server binding:
- - `lib/crates/fabro-server/src/serve.rs`
- - `lib/crates/fabro-server/src/bind.rs`
-- Existing server routes relevant to store access:
- - `GET /api/v1/runs/{id}/state`
- - `GET /api/v1/runs/{id}/events`
- - `GET /api/v1/runs/{id}/attach`
- - `POST /api/v1/runs/{id}/events`
- - `POST /api/v1/runs/{id}/blobs`
- - `GET /api/v1/runs/{id}/blobs/{blobId}`
- - `GET|POST /api/v1/runs/{id}/stages/{stageId}/artifacts`
- - `GET /api/v1/runs/{id}/stages/{stageId}/artifacts/download`
- - `GET /api/v1/runs/{id}/checkpoint`
- - `GET /api/v1/runs/{id}/retro`
-- `RunProjection` already contains much more than the old plan assumed:
- - checkpoint and checkpoint history
- - retro and retro prompt/response
- - sandbox
- - final patch
- - pull request
-
-### Still Missing or Mismatched
-
-- `lib/crates/fabro-cli/src/store.rs` still builds a local `SlateStore`
-- CLI commands are typed against concrete `SlateStore` / `SlateRunStore`
-- Server `GET /api/v1/runs` is not durable store-backed; it serves in-memory managed runs only
-- No durable delete endpoint exists for runs
-- Artifact listing CLI still reads local artifact directories directly rather than using the server
-- Detached CLI execution still opens the store directly and runs workflow engine code locally
-
-## Key Technical Decisions
-
-- **Use `fabro-api::Client` over Unix socket, not a custom hyper-only client.**
- - The previous plan's "reqwest cannot do Unix sockets" assumption is stale.
- - The generated client already covers `state`, `events`, `attach`, `blobs`, and artifact endpoints.
- - Build a thin `fabro-cli` client wrapper around:
- - `fabro_api::Client`
- - `reqwest::ClientBuilder::unix_socket(socket_path)`
- - For any operation not yet present in the OpenAPI spec, add the endpoint to the spec and regenerate `fabro-api`.
-
-- **Do not introduce a new transport crate until there is a clear reuse case.**
- - The immediate consumers are in `fabro-cli`.
- - A small `fabro-cli::server_client` module is enough for the first migration.
- - If a second Rust crate later needs the same client, extract then.
-
-- **Auto-start belongs in CLI store/bootstrap code, not in the generated client.**
- - The generated client should stay transport-only.
- - Server lifecycle discovery/start remains in `fabro-cli`.
-
-- **Treat `RunProjection` as the primary read snapshot.**
- - The existing `/runs/{id}/state` endpoint already returns the coarse-grained shape most CLI reads need.
- - This should replace many fine-grained local store reads without widening the API.
-
-- **Split the migration into two layers.**
- - Layer 1: CLI read/write operations that are naturally expressible against the current server API
- - Layer 2: execution-path consolidation for detached/resume/start flows if we want the server, not CLI subprocesses, to be the sole write owner
-
-- **Preserve local run-directory access where it is orthogonal to SlateDB.**
- - Run discovery still needs local run-dir paths for UI output and fallback/orphan detection.
- - Runtime interview files and launcher metadata remain file-based unless separately redesigned.
-
-## Open Questions
-
-### Resolved for This Plan
-
-- **Should we use the generated `fabro-api` client?**
- - Yes. It matches the repo direction and now works with Unix socket transport via reqwest.
-
-- **Do we need a brand-new HTTP store crate first?**
- - No. Start with a thin CLI-side server client and only extract if a second consumer appears.
-
-- **Does the server already expose enough snapshot data?**
- - Mostly yes. `RunProjection` already covers much more than the earlier plan assumed.
-
-### Deferred to Implementation
-
-- Whether to model the new CLI-side access layer as:
- - a direct "server client" API, or
- - a local wrapper that mimics `SlateStore` / `SlateRunStore`
-- Whether artifact-list CLI should remain filesystem-based for local-only debugging or migrate fully to server-backed listing in phase 1
-- Whether detached engine execution should be migrated in the same branch or explicitly deferred behind a feature boundary
-
-## Relevant Code and Patterns
-
-### Daemon and Unix Socket Patterns
-
-- `lib/crates/fabro-cli/src/commands/server/start.rs`
-- `lib/crates/fabro-cli/src/commands/server/record.rs`
-- `lib/crates/fabro-server/src/serve.rs`
-- `lib/crates/fabro-server/src/bind.rs`
-
-### Existing Generated Client
-
-- `lib/crates/fabro-api/src/lib.rs`
-- `lib/crates/fabro-api/build.rs`
-- `docs/api-reference/fabro-api.yaml`
-
-### Store-Backed Server Routes
-
-- `lib/crates/fabro-server/src/server.rs`
-
-### CLI Entry Points That Must Migrate
-
-- `lib/crates/fabro-cli/src/store.rs`
-- `lib/crates/fabro-cli/src/commands/runs/list.rs`
-- `lib/crates/fabro-cli/src/commands/run/logs.rs`
-- `lib/crates/fabro-cli/src/commands/run/attach.rs`
-- `lib/crates/fabro-cli/src/commands/run/diff.rs`
-- `lib/crates/fabro-cli/src/commands/run/ssh.rs`
-- `lib/crates/fabro-cli/src/commands/run/output.rs`
-- `lib/crates/fabro-cli/src/commands/store/dump.rs`
-- `lib/crates/fabro-cli/src/commands/pr/create.rs`
-- `lib/crates/fabro-cli/src/commands/pr/list.rs`
-- `lib/crates/fabro-cli/src/commands/pr/view.rs`
-- `lib/crates/fabro-cli/src/commands/runs/rm.rs`
-- `lib/crates/fabro-cli/src/commands/system/df.rs`
-- `lib/crates/fabro-cli/src/commands/artifact/list.rs`
-- `lib/crates/fabro-cli/src/commands/artifact/cp.rs`
-- `lib/crates/fabro-cli/src/commands/run/wait.rs`
-- `lib/crates/fabro-cli/src/commands/run/preview.rs`
-- `lib/crates/fabro-cli/src/commands/run/rewind.rs`
-
-### Run Discovery Coupling
-
-- `lib/crates/fabro-workflow/src/run_lookup.rs`
-
-### Execution-Path Coupling
-
-- `lib/crates/fabro-cli/src/commands/run/create.rs`
-- `lib/crates/fabro-cli/src/commands/run/start.rs`
-- `lib/crates/fabro-cli/src/commands/run/detached.rs`
-- `lib/crates/fabro-cli/src/commands/run/resume.rs`
-
-## High-Level Design
-
-### Layer 1: CLI server-backed store access
-
-`fabro-cli` gains a small client/bootstrap layer:
-
-1. Resolve active server from `server.json`
-2. If absent or stale, auto-start daemon using existing lock/spawn/readiness logic
-3. Construct `reqwest::Client` bound to the Unix socket
-4. Construct `fabro_api::Client` with base URL like `http://fabro`
-5. Expose helper methods for:
- - run state
- - run events list
- - run events attach SSE stream
- - blob read/write
- - stage artifact list/read/write
- - durable run list
- - durable run delete
-
-CLI command handlers stop calling `build_store()` and instead call a new helper such as:
-
-`store::connect_server(storage_dir) -> Result`
-
-### Layer 2: API parity for run discovery and deletion
-
-The server adds durable endpoints for:
-
-- listing runs from the store catalog rather than only in-memory managed runs
-- deleting run store state
-
-The CLI keeps local run-dir fallback/orphan detection logic from `run_lookup.rs`, but its durable run summary source becomes the server.
-
-### Layer 3: Optional execution consolidation
-
-If we want strict compliance with "server is the only process accessing SlateDB", then detached/resume/start flows must stop opening run stores locally. That likely means:
-
-- CLI creates/starts runs by calling server APIs
-- server-owned scheduler/executor performs writes
-- attach/logs become purely server-backed observers
-
-This is separable from the read-path migration and should be treated as a deliberate second stage.
-
-### Artifact handling boundary in phase 1
-
-Artifact metadata and binary reads can move to server-backed endpoints in phase 1, but local run-directory artifact scanning may remain temporarily filesystem-based where commands are acting as local debugging tools rather than store clients. Implementation should make that boundary explicit rather than leaving a silent mixed-mode design.
-
-## Implementation Units
-
-- [ ] **Unit 1: Add CLI server bootstrap and generated-client construction**
-
-**Goal:** Replace raw local `SlateStore` bootstrap in `fabro-cli` with "find or start server, then connect over Unix socket".
-
-**Requirements:** R1, R2, R4, R5, R8
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/store.rs`
-- Create: `lib/crates/fabro-cli/src/server_client.rs`
-- Modify: `lib/crates/fabro-cli/src/main.rs`
-- Modify: `lib/crates/fabro-cli/Cargo.toml`
-
-**Approach:**
-- Add `ensure_server_running(storage_dir: &Path) -> Result` in `server/start.rs` or a sibling helper module.
-- Reuse:
- - `acquire_lock`
- - `active_server_record`
- - daemon spawn path
- - readiness polling
-- Fast path: if `active_server_record()` exists, return its bind.
-- If no record exists, start the daemon on the default Unix socket path and wait for readiness.
-- In a new `server_client.rs`, build:
- - `reqwest::ClientBuilder::new().unix_socket(socket_path)`
- - `fabro_api::Client::new_with_client("http://fabro", reqwest_client)`
-
-**Patterns to follow:**
-- `lib/crates/fabro-cli/src/commands/server/start.rs`
-- `lib/crates/fabro-cli/src/commands/server/record.rs`
-- `lib/crates/fabro-api/src/lib.rs`
-
-**Test scenarios:**
-- Existing active server record returns immediately without spawning
-- Missing server record triggers daemon start and waits for readiness
-- Stale server record is ignored and replaced by a working daemon
-- Unix socket connection errors produce a clear CLI-facing error
-
-**Verification:**
-- `cargo build -p fabro-cli`
-- targeted tests for server start/status helpers in `fabro-cli`
-
-- [ ] **Unit 2: Add durable server endpoints needed for CLI parity**
-
-**Goal:** Close the durable API gaps that block CLI migration.
-
-**Requirements:** R2, R3, R4, R5
-
-**Files:**
-- Modify: `docs/api-reference/fabro-api.yaml`
-- Modify: `lib/crates/fabro-server/src/server.rs`
-- Modify: `lib/crates/fabro-api/build.rs` only if codegen constraints require it
-- Regenerate: `lib/crates/fabro-api` via normal build
-
-**Required endpoints:**
-- `GET /api/v1/store/runs`
- - durable run summaries from `state.store.list_runs(...)`
-- `DELETE /api/v1/store/runs/{id}`
- - durable store deletion for a run
-
-**Contract guardrail:**
-- Do not change existing `GET /api/v1/runs` response semantics in this unit.
-- The existing `/runs` route remains the board-oriented runtime view backed by `state.runs`.
-- Durable catalog access belongs on the distinct `/api/v1/store/runs` surface unless a separate reviewed plan intentionally merges the concepts.
-
-**Optional endpoint for phase-1 cleanup if needed:**
-- `GET /api/v1/runs/{id}/artifacts`
- - if we decide to stop using local artifact directory scanning for listing/copy
-
-**Patterns to follow:**
-- Existing store-backed handlers in `lib/crates/fabro-server/src/server.rs`
-
-**Test scenarios:**
-- Durable run list returns runs persisted before current server boot
-- Durable run delete removes store state for existing run
-- Deleting missing run is idempotent or returns a clearly documented 404 behavior
-- New endpoints are represented in `fabro-api` codegen output
-
-**Verification:**
-- `cargo build -p fabro-api`
-- `cargo nextest run -p fabro-server`
-
-- [ ] **Unit 3: Migrate run discovery to server-backed durable summaries**
-
-**Goal:** Stop CLI run discovery from reading store summaries via direct `SlateStore`.
-
-**Requirements:** R2, R3, R4
-
-**Files:**
-- Modify: `lib/crates/fabro-workflow/src/run_lookup.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/runs/list.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/system/df.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/pr/list.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/mod.rs`
-- Add tests in:
- - `lib/crates/fabro-cli/tests/it/cmd/`
- - `lib/crates/fabro-workflow` tests if `run_lookup` signatures change
-
-**Approach:**
-- Decouple `run_lookup` from concrete `SlateStore` inputs.
-- Introduce a smaller input shape for durable summaries, likely:
- - a plain `Vec`, or
- - a small trait implemented by both local tests and the new CLI client wrapper
-- Preserve local run-dir fallback/orphan detection from filesystem scanning.
-- Use server-provided durable summaries as the authoritative store source.
-
-**Patterns to follow:**
-- `lib/crates/fabro-workflow/src/run_lookup.rs`
-
-**Test scenarios:**
-- Persisted run appears in list even after server restart
-- Local orphan run still appears when store summary is absent
-- Prefix resolution still works against durable summaries plus local paths
-- `runs list` behavior remains unchanged for filters and JSON output
-
-**Verification:**
-- `cargo nextest run -p fabro-cli runs_list`
-- targeted `run_lookup` tests
-
-- [ ] **Unit 4: Migrate read-heavy CLI commands to server-backed state/events/blob/artifact access**
-
-**Goal:** Move the majority of CLI read flows off direct SlateDB access.
-
-**Requirements:** R2, R3, R4, R6, R7, R8
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/run/logs.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/attach.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/diff.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/ssh.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/output.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/store/dump.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/pr/create.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/pr/view.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/wait.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/preview.rs`
-
-**Approach:**
-- Replace direct `open_run_reader()` usage with calls to:
- - `get_run_state`
- - `list_run_events`
- - `attach_run_events`
- - `read_run_blob`
- - `list_stage_artifacts`
- - artifact download endpoint
-- Build one SSE parsing helper in CLI for `attach_run_events()` byte streams.
-- Continue using `RunProjection` as the coarse-grained read model.
-
-**Patterns to follow:**
-- `lib/crates/fabro-server/src/server.rs` attach SSE response shape
-- Existing CLI attach/log rendering logic
-
-**Test scenarios:**
-- `logs --follow` continues to stream events to completion
-- `attach` replays existing events then follows live events
-- state-driven commands still read final patch, PR data, sandbox, checkpoint, and retro from `RunProjection`
-- blob and artifact download remain raw bytes
-
-**Verification:**
-- targeted `fabro-cli` command tests:
- - logs
- - attach
- - diff
- - pr view/create
- - store dump
-
-- [ ] **Unit 5: Migrate write/delete CLI operations that should hit the server**
-
-**Goal:** Stop CLI deletion and similar store mutations from touching SlateDB directly.
-
-**Requirements:** R2, R3, R4, R8
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/runs/rm.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/run/start.rs` if status validation moves to server reads only
-- Modify: `lib/crates/fabro-cli/src/commands/run/rewind.rs` only if it currently depends on direct store writes in the targeted path
-
-**Approach:**
-- Replace direct `store.delete_run()` calls with server API delete.
-- Replace direct event append for `RunRemoving` with `POST /runs/{id}/events`.
-- Keep local run-dir deletion and sandbox cleanup local unless a server-owned deletion flow is explicitly introduced.
-
-**Test scenarios:**
-- removing a completed run deletes local run dir and durable store state
-- removing a run with missing store state still behaves predictably
-- server-unreachable deletion path returns actionable error text
-
-**Verification:**
-- `cargo nextest run -p fabro-cli runs_rm`
-
-- [ ] **Unit 6: Decide and document the execution-ownership boundary**
-
-**Goal:** Explicitly close the gap between "CLI reads via server" and "server is the only process accessing SlateDB".
-
-**Requirements:** R3, R9
-
-**Files:**
-- Modify: this plan document after implementation decision, or create follow-on plan
-- Review:
- - `lib/crates/fabro-cli/src/commands/run/create.rs`
- - `lib/crates/fabro-cli/src/commands/run/start.rs`
- - `lib/crates/fabro-cli/src/commands/run/detached.rs`
- - `lib/crates/fabro-cli/src/commands/run/resume.rs`
-
-**Decision fork:**
-
-Option A: **Phase-1 complete means CLI read/write store access is server-backed, but local engine subprocesses remain**
-- Faster
-- Leaves a strict reading of R3 partially unmet
-
-Option B: **Phase-2 also migrates execution ownership to the server**
-- CLI create/start/resume become HTTP calls
-- Detached local engine path is retired or reduced to server-only launch
-- Strictly satisfies "server is the only process accessing SlateDB"
-
-**Recommendation:**
-- Treat Option A as the first implementation milestone
-- Open a follow-on plan immediately for Option B if the requirement remains strict
-
-**Implementation note (2026-04-04):**
-- This branch follows Option A.
-- CLI durable run discovery, wait/logs/diff/preview/PR listing, and run deletion are moving behind the server-backed store client.
-- Detached/create/start/resume execution ownership remains local for now and still needs a follow-on server-owned execution plan if strict single-owner SlateDB semantics remain required.
-
-**Test scenarios:**
-- explicit documentation of whichever boundary we choose
-- no silent mixing of local-store and server-store code paths remains after the chosen milestone
-
-## Sequencing
-
-1. Unit 1 first: auto-start and client bootstrap
-2. Unit 2 second: add missing durable API surface
-3. Unit 3 third: migrate run discovery and durable summary reads
-4. Unit 4 fourth: migrate read-heavy commands
-5. Unit 5 fifth: migrate store mutations that still happen in CLI
-6. Unit 6 last: finalize the execution-ownership boundary and either defer or continue
-
-## Risks and Mitigations
-
-- **Risk: `/api/v1/runs` semantics are runtime-board state, not durable store state**
- - Mitigation: add distinct `/api/v1/store/runs` routes rather than silently repurposing `/runs`
-
-- **Risk: `run_lookup` is coupled to concrete `SlateStore`**
- - Mitigation: extract a smaller durable-summary input shape before touching multiple commands
-
-- **Risk: SSE parsing via generated client is lower-level than current in-process stream usage**
- - Mitigation: centralize byte-stream-to-event parsing in one helper and cover it with focused tests
-
-- **Risk: some CLI commands still depend on local runtime files rather than store data**
- - Mitigation: migrate only true store access in this plan; do not conflate run-dir filesystem concerns with SlateDB consolidation
-
-- **Risk: execution paths still open the store directly after read-path migration**
- - Mitigation: explicitly treat execution consolidation as a tracked decision point, not an accidental omission
-
-## Verification Strategy
-
-Per-unit targeted verification:
-
-- `cargo build -p fabro-api`
-- `cargo nextest run -p fabro-server`
-- `cargo nextest run -p fabro-cli`
-
-Focused command coverage should include:
-
-- server start/status/stop
-- runs list
-- logs
-- attach
-- diff
-- pr view/create/list
-- runs rm
-- store dump
-
-Manual smoke flow after Units 1-5:
-
-1. stop any running server
-2. run a CLI command that needs store access
-3. verify server auto-starts
-4. verify the command succeeds through the Unix socket path
-5. verify no CLI path in the tested flow opens local SlateDB directly
-
-Durability smoke flow:
-
-1. create or identify a persisted run
-2. stop the server
-3. start the server again
-4. verify durable run listing still finds the run through the HTTP path
-5. verify run state for that run is still readable through the HTTP path
-
-## Change Summary
-
-The old plan is no longer the right implementation guide. The repo already has daemon management, Unix socket support, store-backed server endpoints, and a generated Rust client that can be used over UDS. The remaining plan is to:
-
-- auto-start the server from CLI store bootstrap
-- use `fabro-api::Client` over Unix socket
-- add the missing durable run-list/delete endpoints
-- migrate CLI store consumers off direct `SlateStore`
-- then explicitly decide whether execution ownership also moves fully into the server
diff --git a/docs/plans/2026-04-04-run-event-simplification-plan.md b/docs/plans/2026-04-04-run-event-simplification-plan.md
deleted file mode 100644
index 0f7777a9c..000000000
--- a/docs/plans/2026-04-04-run-event-simplification-plan.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Simplify `RunEvent` While Keeping Wire JSON Stable
-
-## Summary
-- Refactor the event model so `RunEvent` stores only envelope metadata plus a typed `EventBody`; the JSON wire format stays `{ ..., "event": "...", "properties": { ... } }`.
-- Treat this as an internal Rust API break now: remove public `RunEvent.event` and `RunEvent.properties`, update repo call sites in one pass, and align the code with `docs-internal/events-strategy.md`'s "canonical envelope built once" rule.
-- Preserve forward-compatibility for unknown stored events explicitly instead of relying on duplicate cached fields.
-- Phase the refactor into three commits so the direct `Event -> RunEvent` mapping can land and be verified before the cached-field removal.
-
-## Implementation Changes
-- Sequencing
- - Commit 1: add `EventBody::event_name() -> &str`, remove `event_name_from_body()` and `properties_from_body()`, and replace both with explicit implementations that keep cached fields working through commits 1 and 2.
- - Commit 2: rework `fabro-workflow` to construct `RunEvent` directly from `Event`; this is the main structural refactor and the primary regression risk.
- - Commit 3: remove cached `RunEvent.event` / `RunEvent.properties`, update callers and tests, and replace `EventBody::Unknown` with a raw-preserving variant.
-- `lib/crates/fabro-types/src/run_event/mod.rs`
- - Redefine `RunEvent` to contain `id`, `ts`, `run_id`, optional envelope metadata, and `body: EventBody` only.
- - Keep `RunEvent::from_value`, `from_json_str`, and `to_value`, but make them thin wire-boundary helpers around a private raw wire struct for `{ event, properties }`.
- - Replace `EventBody::Unknown` with a raw-preserving variant such as `Unknown { name: String, properties: Value }`.
- - Add `EventBody::event_name() -> &str` implemented as an exhaustive `match` returning the serde rename string for each known variant and `name.as_str()` for `Unknown`.
- - In commit 1, replace `properties_from_body()` with an explicit property-serialization helper that derives the inner properties payload without the current serialize-and-pluck helper pattern; it may still serialize as an interim step, but it should exist only to support cached fields and wire serialization during the transition.
- - Keep JSON property extraction as a serialization helper, not a hot-path public API. Use it only in `RunEvent::to_value` / `Serialize` and in wire-shape tests that need JSON-level assertions.
- - Remove `refresh_cache`, `event_name_from_body`, and `properties_from_body`.
- - Call out unknown-event fallback explicitly: `Unknown { name, properties }` cannot rely on `#[serde(other)]`, so `RunEvent::from_value` must use a custom fallback path that preserves raw `event` and `properties` when typed `EventBody` deserialization fails.
-- `lib/crates/fabro-workflow/src/event.rs`
- - Split the current conversion into two explicit pieces: envelope metadata extraction and `Event -> EventBody` construction.
- - Rework `to_run_event_at()` to build `RunEvent` directly, not via `json!` plus `RunEvent::from_value`.
- - Keep all existing canonicalization rules, but express them as Rust matches: `run_id` stripping, node/session extraction, node-label defaults, failure/error normalization, and agent/sandbox nested event flattening.
- - Treat `Event::Agent` and `Event::Sandbox` as the bulk of the work:
- - `Event::Agent` must expand each `AgentEvent` sub-variant into the corresponding `EventBody` variant while also lifting `stage -> node_id`, preserving `session_id` / `parent_session_id` in the envelope, and merging `visit` into the inner props where required.
- - `Event::Sandbox` must unwrap each `SandboxEvent` sub-variant into the corresponding `EventBody` variant while preserving the current flattened wire shape.
- - `Event::WorkflowRunFailed` must continue converting `FabroError` into the stored string form used by `RunFailedProps`.
- - stage/parallel/prompt/watchdog variants must continue moving `node_id`/`stage`/`branch`/`node` into the envelope with the same current `node_label` defaults.
- - Make the lossy cross-crate conversions explicit in the implementation and guard them with wire-shape characterization tests:
- - `fabro_agent::AgentError -> String`
- - `fabro_llm::error::SdkError -> string fields in retry props`
- - `fabro_llm` usage types -> `fabro_types` usage structs
- - `fabro_workflow::error::FabroError -> String`
- - Delete `tagged_variant_fields*` once all variant mapping is direct and covered by tests.
- - Keep redaction/persistence logic driven by serialized `RunEvent` wire value; no wire-shape change and no redaction contract change.
- - Explicitly keep the `build_redacted_event_payload` pipeline out of scope for this pass: no changes to `to_value() -> normalize -> to_string -> redact -> from_str`.
-- `lib/crates/fabro-store/src/types.rs`, `lib/crates/fabro-store/src/run_state.rs`, and repo consumers
- - Update call sites to stop reading `RunEvent.event` and `RunEvent.properties` directly.
- - Default rule: production consumers match on `body`; only serialization/wire tests should rely on JSON property extraction.
- - Route store decoding through one helper path (`TryFrom<&EventPayload>` or `RunEvent::from_value`) and keep clone-based payload parsing for now; zero-copy parsing is out of scope for this pass.
- - Update strategy/docs terminology only, not code naming: leave `RunEvent` as the code type in this pass and align `docs-internal/events-strategy.md` if needed.
-
-## Test Plan
-- `lib/crates/fabro-types/src/run_event/mod.rs`
- - known event round-trip preserves the wire JSON shape
- - unknown event round-trip preserves raw `event` and `properties`
- - known event name with invalid properties still fails deserialization
- - absent optional envelope fields serialize as omitted fields, not `null`
-- `lib/crates/fabro-workflow/src/event.rs`
- - characterization tests for representative variants: stage event, agent event, sandbox event, and run failure
- - assert direct construction produces the same wire JSON and envelope fields as today
- - assert `build_redacted_event_payload` still returns a valid `EventPayload`
- - add focused coverage for agent flattening and sandbox flattening, since those wrappers are the highest-risk conversion paths
-- `lib/crates/fabro-store/src/run_state.rs` or adjacent store tests
- - replay persisted payloads into `RunProjection` still reconstructs run, status, checkpoint, retro, and pull-request state correctly
-- Test migration rules
- - behavior tests should prefer matching on typed `body` instead of reintroducing JSON-shaped assertions
- - wire-contract tests should assert on `to_value()` / serialized JSON when the exact `properties` shape matters
- - do not replace all former `stored.properties["foo"]` assertions with a general-purpose allocating helper in production code
- - `fabro-cli/src/commands/run/run_progress/event.rs::from_run_event()` is already aligned with the target design because it matches on `EventBody`; only any remaining CLI tests asserting through `stored.properties` need migration in commit 3
-- Verification
- - run `cargo nextest run -p fabro-types`
- - run `cargo nextest run -p fabro-workflow`
- - run `cargo nextest run -p fabro-store`
- - run `cargo fmt --check --all` and `cargo clippy --workspace -- -D warnings`
-
-## Assumptions
-- The JSON wire protocol stays compatible; only the internal Rust representation and helper APIs change.
-- Internal Rust API break is acceptable now; tests and internal consumers will be updated in the same pass.
-- Unknown stored events are a supported forward-compatibility case and must survive parse/serialize unchanged.
-- This pass optimizes for simplicity and maintainability first; deeper read-side performance work such as borrowed parsing, eliminating `Value` clones in projection, or optimizing the redaction pipeline can follow separately.
diff --git a/docs/plans/2026-04-04-shared-nextest-test-daemon-plan.md b/docs/plans/2026-04-04-shared-nextest-test-daemon-plan.md
deleted file mode 100644
index 1db01f396..000000000
--- a/docs/plans/2026-04-04-shared-nextest-test-daemon-plan.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Shared Test Storage + Production Auto-Start for CLI Tests
-
-## Summary
-Use one shared test `storage_dir` per test session and rely on the existing production auto-start behavior to converge on a single shared daemon for that storage root.
-
-Session identity rules:
-- when `NEXTEST_RUN_ID` is present, use one shared storage dir for the full `cargo nextest run`
-- when `NEXTEST_RUN_ID` is absent, use one shared storage dir per test process
-
-The test harness will not implement its own daemon bootstrap protocol. Instead:
-- every test process points `FABRO_STORAGE_DIR` at the same test-run storage root
-- the first CLI command that needs the daemon triggers normal production auto-start
-- existing `server.lock`, `server.json`, and `fabro.sock` behavior prevents duplicate servers for that shared storage dir
-- the test harness is responsible only for:
- - selecting the shared test storage root
- - making test assertions/helpers safe under shared storage
- - cleaning up the shared daemon and temp root at the end of the test run
-
-This keeps test behavior aligned with production daemon identity semantics.
-
-## Implementation Changes
-### 1. Shared `storage_dir` in `fabro-test`
-In `lib/crates/fabro-test/src/lib.rs`:
-- Change `TestContext::new` to detect `NEXTEST_RUN_ID`.
-- Derive a shared test root under temp:
- - if `NEXTEST_RUN_ID` is present: `$TMPDIR/fabro-nextest//`
- - otherwise: `$TMPDIR/fabro-test-process//`
- - shared storage dir: `/storage`
-- Keep `temp_dir` and `home_dir` per context; only `storage_dir` becomes shared for the session.
-- Do not explicitly start the daemon from the harness.
-- Keep using the normal CLI command path so the first server-backed command triggers production auto-start against the shared storage dir.
-- Add concrete session cleanup coordination using marker files:
- - under the session root, create `clients/` marker files
- - protect create/remove/scan operations with a session lock file
- - on `TestContext` init:
- - acquire lock
- - create or refresh this process marker
- - remove stale markers for dead PIDs
- - release lock
- - on process teardown:
- - acquire lock
- - remove this process marker
- - remove any other stale dead markers
- - if no markers remain, call `fabro server stop --storage-dir ` and remove the shared temp root
- - release lock
-- Crash behavior:
- - crashed processes may leave stale markers behind
- - future init/teardown paths reap dead markers under the same lock
- - teardown cleanup is best-effort; if `fabro server stop` or root removal fails, later harness initialization remains responsible for authoritative stale-session reaping
-- Add stale-run cleanup on harness initialization:
- - scan old `fabro-nextest/*` roots
- - if all tracked PIDs for a root are dead, stop any server tied to that root and remove it
- - likewise scan old `fabro-test-process/*` roots and reap dead process-owned sessions
-
-The harness should only coordinate test-run ownership and cleanup, not daemon startup.
-
-### 2. Per-test labeling for shared-state safety
-Add a per-`TestContext` test case ULID and expose:
-- `fabro_test_run=`
-- `fabro_test_case=`
-
-Update run-creation helpers to append these labels to created runs:
-- `run`
-- `create`
-- detached/create-start helpers
-- any workflow fixture helpers that create runs internally
-
-Use existing production `--label KEY=VALUE` support; do not invent a new namespacing mechanism.
-
-### 3. Replace isolated-storage helper assumptions
-Update helpers in:
-- `lib/crates/fabro-cli/tests/it/cmd/support.rs`
-- `lib/crates/fabro-cli/tests/it/workflow/mod.rs`
-
-Specifically:
-- remove helpers that assume there is exactly one run in `storage_dir/runs`
-- replace `only_run(context)`-style logic with:
- - exact run-id lookup when the helper already has the run id, or
- - test-case-label-based lookup when the helper needs to discover “the run created by this test”
-- keep direct store inspection helpers, but always resolve a concrete run first
-
-### 4. Make shared-daemon tests robust
-Update tests to match the shared-daemon model:
-- exact-run tests remain strict and use ULIDs directly
-- global/listing tests (`ps`, `runs list`, `system df`, workflow-slug/recency lookup) should assert the presence/properties of the current test’s run(s), not exact global emptiness/counts unless explicitly scoped
-- when a command offers structured output, prefer parsing that output and filtering to the current test’s run(s) over broad transcript snapshots or loose substring matching
-- destructive tests must always be scoped:
- - exact run IDs when possible
- - otherwise use existing `--label` filters
-- broad destructive operations like “delete everything” are not allowed in shared-daemon tests
-
-Rewrite current tests that depend on ambient exclusivity, especially:
-- helpers asserting a single run in storage
-- `ps` tests expecting global count equality
-- `system prune` tests filtering only by common workflow names like `Simple`
-
-## Important Interface / Behavior Changes
-- `fabro-test::TestContext` uses a shared `storage_dir` per nextest run when `NEXTEST_RUN_ID` is set.
-- Test-created runs gain deterministic labels:
- - `fabro_test_run`
- - `fabro_test_case`
-- Test code must treat shared storage as normal under nextest and avoid assumptions based on storage exclusivity.
-
-## Test Plan
-- `fabro-test` coverage:
- - multiple contexts in one nextest run resolve to the same shared storage dir
- - multiple contexts without `NEXTEST_RUN_ID` but in the same process resolve to the same shared storage dir
- - contexts still get distinct `temp_dir` and `home_dir`
- - marker-file cleanup removes stale prior session roots
- - last-process cleanup stops the daemon and removes the shared root
-- CLI integration updates:
- - helper coverage for resolving runs by exact ULID or test-case label
- - `ps`, `runs list`, and `system prune` tests updated to shared-storage-safe assertions
- - destructive tests verified to target only test-owned runs
-- End-to-end acceptance:
- - a full `cargo nextest run -p fabro-cli` should converge on one daemon per `NEXTEST_RUN_ID` storage root
- - a `cargo test --workspace` invocation should converge on one daemon per test process, not per `TestContext`
- - after the run, no test-owned `fabro.sock` daemon remains for that root
- - add an early validation test or harness check that concurrent auto-start against the same shared `storage_dir` converges on one daemon under parallel load
-
-## Assumptions and Defaults
-- Production auto-start semantics for a single `storage_dir` are the source of truth and already provide duplicate-server protection via the existing lock/record path.
-- `NEXTEST_RUN_ID` is used when available to derive the shared nextest-run root; otherwise the current process PID is used to derive a shared per-process root.
-- The shared test storage root is fully separate from production storage in both modes.
-- No separate harness-managed daemon bootstrap protocol is added.
-- No changes to production daemon lifetime semantics are part of this plan.
diff --git a/docs/plans/2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md b/docs/plans/2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md
deleted file mode 100644
index 020fff85c..000000000
--- a/docs/plans/2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md
+++ /dev/null
@@ -1,419 +0,0 @@
-# CLI De-globalize Server URL And Storage Dir
-
-## Summary
-Make `--storage-dir` and `--server-url` command-scoped instead of global so the CLI surface matches the architecture we now have.
-
-This pass should:
-
-- keep only truly global flags in `GlobalArgs`
-- move local-storage selection onto the commands that actually use local storage
-- move remote-server selection onto the commands that actually support remote targeting
-- remove false affordances from help output, docs, and env-var wiring
-
-This plan is the direct follow-on to [2026-04-05-next-steps-after-cli-mode-removal.md](../ideation/2026-04-05-next-steps-after-cli-mode-removal.md).
-
-## Scope Boundaries
-In scope:
-- de-globalize `--storage-dir` / `FABRO_STORAGE_DIR`
-- de-globalize `--server-url` / `FABRO_SERVER_URL`
-- update clap types, parser tests, dispatch signatures, and command help
-- keep `model` and `exec` behavior consistent with the recent cleanup, but expressed through command-local args
-- update docs/examples that still show top-level target flags
-
-Out of scope:
-- changing server/runtime behavior for `run`, `model`, or `exec`
-- adding new remote-capable commands
-- making `exec` server-owned
-- changing `[server].base_url` semantics again
-- broad config/schema changes outside the CLI arg surface
-
-## Problem Frame
-The code no longer has a meaningful whole-program “mode”, but the CLI still advertises target-selection flags as if every command can choose between local storage and a remote server.
-
-That is now misleading in several different ways:
-
-- many commands still show `--server-url` even though they never use it
-- many commands still show `--storage-dir` even though they do not read local runtime state
-- docs still describe these flags as global CLI surface area
-- help snapshot churn is broader than the real behavior surface because the flags leak into unrelated commands
-
-The goal is not to invent new behavior. The goal is to make the CLI honest about which commands actually support which target-selection controls.
-
-## Key Decisions
-- `GlobalArgs` remains, but only for true global flags:
- - `--json`
- - `--debug`
- - `--no-upgrade-check`
- - `--quiet`
- - `--verbose`
-- `--storage-dir` and `--server-url` stop being top-level/global clap args entirely.
-- target-selection args belong to leaf commands, not parent namespaces.
- - Rationale: keep natural syntax such as:
- - `fabro run foo.fabro --storage-dir /tmp/fabro`
- - `fabro model list --server-url https://fabro.example.com/api/v1`
- - `fabro server start --storage-dir /tmp/fabro`
- - Avoid awkward parent-namespace syntax like `fabro model --server-url ... list`.
-- `FABRO_STORAGE_DIR` and `FABRO_SERVER_URL` remain supported, but only for commands that define the corresponding arg.
-- command-local target syntax becomes the supported surface.
- - Old forms like `fabro --server-url ... model list` and `fabro --storage-dir ... run ...` are intentionally removed in this pass.
-- during implementation, temporary duplication between global target args and the new leaf-command args is acceptable.
- - Rationale: this refactor touches many commands, so the migration should stay compile-safe until the old global fields are fully unused and can be removed in one cleanup step.
-- `settings` keeps `--storage-dir`, because it changes the resolved local settings output.
-- `settings` does not keep `--server-url`.
- - Rationale: command-local remote target overrides should not masquerade as merged durable config.
-- `preflight` keeps `--storage-dir`, because it resolves a local run-oriented settings stack and should continue to allow explicit local storage selection.
-- `exec` keeps only `--server-url`.
- - `exec` does not need `--storage-dir`.
-- `model list` and `model test` keep both:
- - `--server-url` for explicit remote server targeting
- - `--storage-dir` for explicit local auto-start/storage selection
-- the existing `model` config/defaulting contract stays intact:
- - explicit `--server-url` wins
- - explicit `--storage-dir` suppresses configured `[server].base_url`
- - otherwise `model` may default to configured `[server].base_url`
-- the existing `exec` contract stays intact:
- - server routing only happens when the command-local `server_url` value is set, whether by CLI flag or `FABRO_SERVER_URL`
- - configured `[server].base_url` alone still does not reroute `exec`
-- `fabro model` with no subcommand remains the convenience alias for default listing behavior.
- - target overrides are not a compatibility goal for the bare alias in this pass; users should use `fabro model list ...` when specifying target args explicitly.
-
-## Command Matrix
-### `--server-url` only
-- `fabro exec`
-
-### `--storage-dir` and `--server-url`
-- `fabro model list`
-- `fabro model test`
-
-### `--storage-dir` only
-- `fabro run`
-- `fabro create`
-- `fabro start`
-- `fabro attach`
-- `fabro logs`
-- `fabro resume`
-- `fabro rewind`
-- `fabro fork`
-- `fabro wait`
-- `fabro diff`
-- hidden `fabro __runner`
-- `fabro ps`
-- `fabro rm`
-- `fabro inspect`
-- `fabro artifact list`
-- `fabro artifact cp`
-- `fabro sandbox cp`
-- `fabro sandbox preview`
-- `fabro sandbox ssh`
-- `fabro store dump`
-- `fabro pr create`
-- `fabro pr list`
-- `fabro pr view`
-- `fabro pr merge`
-- `fabro pr close`
-- `fabro system prune`
-- `fabro system df`
-- `fabro server start`
-- `fabro server stop`
-- `fabro server status`
-- hidden `fabro server __serve`
-- `fabro settings`
-- `fabro preflight`
-
-### Neither target arg
-- `fabro validate`
-- `fabro graph`
-- `fabro parse`
-- `fabro doctor`
-- `fabro install`
-- `fabro repo init`
-- `fabro repo deinit`
-- `fabro workflow list`
-- `fabro workflow create`
-- `fabro provider login`
-- hidden `fabro skill install`
-- `fabro secret get`
-- `fabro secret list`
-- `fabro secret set`
-- `fabro secret rm`
-- `fabro docs`
-- `fabro discord`
-- `fabro completion`
-- `fabro upgrade`
-- internal analytics/panic commands
-
-## Implementation Changes
-### 1. Narrow `GlobalArgs` and add command-scoped target arg structs
-In `lib/crates/fabro-cli/src/args.rs`:
-- add the new command-scoped target arg structs first, while temporarily leaving `storage_dir` and `server_url` on `GlobalArgs`
-- keep `GlobalArgs` as the long-term home only for the true-global output/logging/upgrade-check surface
-- add small reusable arg structs:
- - `StorageDirArgs { storage_dir: Option }`
- - `ServerUrlArgs { server_url: Option }`
- - `ModelTargetArgs { storage_dir: Option, server_url: Option }`
-- keep the `storage_dir` / `server_url` conflict on `ModelTargetArgs`
-- keep the existing env bindings:
- - `FABRO_STORAGE_DIR`
- - `FABRO_SERVER_URL`
-
-This temporary duplication is intentional. The crate should continue to compile while commands migrate off `GlobalArgs`.
-
-Because the target args will now live on leaf commands, convert inline/anonymous clap variants into explicit args structs where needed. The important conversions are:
-- `Exec(AgentArgs)` -> `Exec(ExecArgs)` where `ExecArgs` flattens:
- - `ServerUrlArgs`
- - `fabro_agent::cli::AgentArgs`
-- `ModelsCommand::List { ... }` -> `ModelsCommand::List(ModelListArgs)`
-- `ModelsCommand::Test { ... }` -> `ModelsCommand::Test(ModelTestArgs)`
-- `RunCommands::Start { run: String }` -> `RunCommands::Start(StartArgs)` where `StartArgs` flattens `StorageDirArgs`
-- `RunCommands::Attach { run: String }` -> `RunCommands::Attach(AttachArgs)` where `AttachArgs` flattens `StorageDirArgs`
-- `RunCommands::Runner { ... }` -> `RunCommands::Runner(RunnerArgs)` where `RunnerArgs` flattens `StorageDirArgs`
-- `ServerCommand::Start { ... }` -> `ServerCommand::Start(ServerStartArgs)` where `ServerStartArgs` flattens:
- - `StorageDirArgs`
- - the existing `foreground` flag
- - `ServeArgs`
-- `ServerCommand::Stop { ... }` -> `ServerCommand::Stop(ServerStopArgs)` where `ServerStopArgs` flattens `StorageDirArgs`
-- `ServerCommand::Status { ... }` -> `ServerCommand::Status(ServerStatusArgs)` where `ServerStatusArgs` flattens `StorageDirArgs`
-- `ServerCommand::Serve { ... }` -> `ServerCommand::Serve(ServerServeArgs)` where `ServerServeArgs` flattens:
- - `StorageDirArgs`
- - the existing `record_path` field
- - `ServeArgs`
-
-Also flatten `StorageDirArgs` into the leaf arg types that currently rely on global storage selection, including:
-- `RunArgs`
-- `LogsArgs`
-- `DiffArgs`
-- `ResumeArgs`
-- `RewindArgs`
-- `ForkArgs`
-- `WaitArgs`
-- `RunsListArgs`
-- `RunsRemoveArgs`
-- `InspectArgs`
-- `ArtifactListArgs`
-- `ArtifactCpArgs`
-- `CpArgs`
-- `PreviewArgs`
-- `SshArgs`
-- `StoreDumpArgs`
-- `PrCreateArgs`
-- `PrListArgs`
-- `PrViewArgs`
-- `PrMergeArgs`
-- `PrCloseArgs`
-- `RunsPruneArgs`
-- `DfArgs`
-- `SettingsArgs`
-- `PreflightArgs`
-
-### 2. Rework parser and dispatch wiring around leaf-command target args
-In `lib/crates/fabro-cli/src/main.rs`:
-- keep `Cli { globals, command }`, but with the narrower `GlobalArgs`
-- update dispatch pattern matches to use the new wrapper arg structs:
- - `ExecArgs`
- - `ModelListArgs`
- - `ModelTestArgs`
- - `StartArgs`
- - `AttachArgs`
- - `RunnerArgs`
-- replace parser tests that assume global target flags with command-local parser tests
-
-Parser behavior to lock down:
-- `fabro run test/simple.fabro --storage-dir /tmp/fabro` parses
-- `fabro model list --server-url http://localhost:3000/api/v1` parses
-- `fabro exec --server-url http://localhost:3000/api/v1 "prompt"` parses
-- `fabro model list --storage-dir /tmp/fabro --server-url http://localhost:3000/api/v1` fails with the command-local conflict
-- `fabro --server-url http://localhost:3000/api/v1 model list` no longer parses
-- `fabro --storage-dir /tmp/fabro run test/simple.fabro` no longer parses
-
-These parser assertions belong at the end of the migration, after `storage_dir` and `server_url` have actually been removed from `GlobalArgs`. Before that cleanup step, the old top-level forms will still parse and should not be treated as failures yet.
-
-### 3. Replace “with globals” settings helpers with explicit local/remote override helpers
-The current helper layer in `lib/crates/fabro-cli/src/user_config.rs` is still shaped around global target args. That should be simplified to explicit command-local override helpers.
-
-In `lib/crates/fabro-cli/src/user_config.rs`:
-- remove or rename the generic helpers that imply target args are global:
- - `user_layer_with_globals(...)`
- - `load_user_settings_with_globals(...)`
- - `apply_global_overrides(...)`
-- replace them with explicit helpers such as:
- - `user_layer_with_storage_dir(storage_dir: Option<&Path>) -> anyhow::Result`
- - `load_user_settings_with_storage_dir(storage_dir: Option<&Path>) -> anyhow::Result`
- - `exec_server_target(args: &ServerUrlArgs, settings: &Settings) -> Option`
- - `model_server_target(args: &ModelTargetArgs, settings: &Settings) -> Option`
-- keep `build_server_client(...)`
-
-Behavior to preserve:
-- local-storage commands can still resolve settings with an explicit storage-dir override
-- `model` keeps its existing defaulting behavior
-- `exec` only resolves a remote target when its command-local `server_url` value is set
-- TLS continues to come from `[server].tls` when a remote target is selected
-
-### 4. Repoint command implementations to explicit target args
-Update the commands that currently read target selection through `GlobalArgs`.
-
-In `lib/crates/fabro-cli/src/commands/model.rs`:
-- switch from `GlobalArgs`-based target lookup to `ModelTargetArgs`
-- keep the recent server-canonical behavior unchanged
-
-In `lib/crates/fabro-cli/src/commands/exec.rs`:
-- switch from `GlobalArgs`-based target lookup to `ServerUrlArgs`
-- remove any remaining dependence on `storage_dir`
-- load settings with plain `load_user_settings()`, not a storage-dir-aware helper
- - `exec` does not need local storage override semantics anymore
- - it should then pass `&ServerUrlArgs` to `exec_server_target(...)`
-
-In the local-storage command modules:
-- replace `load_user_settings_with_globals(globals)` with the explicit storage-dir helper
-- read `storage_dir` from the command’s own args struct, not from `globals`
-
-Key files here include:
-- `lib/crates/fabro-cli/src/commands/run/mod.rs`
-- `lib/crates/fabro-cli/src/commands/run/command.rs`
-- `lib/crates/fabro-cli/src/commands/run/logs.rs`
-- `lib/crates/fabro-cli/src/commands/run/resume.rs`
-- `lib/crates/fabro-cli/src/commands/run/rewind.rs`
-- `lib/crates/fabro-cli/src/commands/run/fork.rs`
-- `lib/crates/fabro-cli/src/commands/run/wait.rs`
-- `lib/crates/fabro-cli/src/commands/run/diff.rs`
-- `lib/crates/fabro-cli/src/commands/run/cp.rs`
-- `lib/crates/fabro-cli/src/commands/run/preview.rs`
-- `lib/crates/fabro-cli/src/commands/run/ssh.rs`
-- `lib/crates/fabro-cli/src/commands/runs/list.rs`
-- `lib/crates/fabro-cli/src/commands/runs/rm.rs`
-- `lib/crates/fabro-cli/src/commands/runs/inspect.rs`
-- `lib/crates/fabro-cli/src/commands/artifact/list.rs`
-- `lib/crates/fabro-cli/src/commands/artifact/cp.rs`
-- `lib/crates/fabro-cli/src/commands/store/dump.rs`
-- `lib/crates/fabro-cli/src/commands/pr/*.rs`
-- `lib/crates/fabro-cli/src/commands/system/*.rs`
-- `lib/crates/fabro-cli/src/commands/server/mod.rs`
-- `lib/crates/fabro-cli/src/commands/preflight.rs`
-- `lib/crates/fabro-cli/src/commands/config/mod.rs`
-
-Important internal-path detail:
-- hidden commands still need explicit local storage wiring
-- `fabro server __serve` must keep receiving `--storage-dir` from `lib/crates/fabro-cli/src/commands/server/start.rs`
-- hidden `fabro __runner` should continue to accept explicit storage-dir selection through its own args struct rather than through `GlobalArgs`
-
-### 5. Make help output and docs reflect the new command contract
-In `docs/reference/cli.mdx`:
-- remove `--storage-dir` and `--server-url` from the “Global options” table
-- add a short “Command-scoped target selection” section or matrix
-- update examples to use command-local placement:
- - `fabro model list --server-url ...`
- - `fabro server start --storage-dir ...`
-
-In `docs/reference/user-configuration.mdx`:
-- keep `[server].base_url` documentation
-- clarify that it is a default only for commands that support remote server targets
-- keep the `model` / `exec` asymmetry explicit
-- update examples away from top-level `fabro --server-url ...`
-
-In `docs/administration/deploy-server.mdx`:
-- update “point the CLI at a server” examples to command-local syntax
-- clarify that `model` can use configured `[server].base_url`, while `exec` still needs explicit `--server-url`
-
-In `docs/reference/run-directory.mdx`:
-- change “global `--storage-dir` flag” wording to command-local run-family wording
-
-Also scan for stale examples in nearby docs and changelog/admin references and update only the ones that would now be actively misleading.
-
-### 6. Update unit tests, parser tests, and help snapshots
-#### Unit and parser coverage
-In `lib/crates/fabro-cli/src/main.rs` tests:
-- replace the old global target-flag parse tests with command-local parse tests
-- add the explicit “old global placement no longer parses” cases
-
-In `lib/crates/fabro-cli/src/user_config.rs` tests:
-- update helper tests to use the new arg structs
-- preserve coverage for:
- - `exec` CLI/env `server_url` routing
- - `exec` ignoring configured `[server].base_url`
- - `model` configured `[server].base_url` defaulting
- - `model` `storage_dir` suppressing configured remote target
- - TLS inheritance
-
-#### Integration coverage
-Update behavior/help coverage in:
-- `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/model.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/model_test.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/config.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/run.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/create.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/attach.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/logs.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/resume.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/rewind.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/wait.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/diff.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/runner.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/inspect.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/store.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/store_dump.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/artifact_list.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/artifact_cp.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/sandbox_cp.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/pr.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/pr_list.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/pr_view.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/pr_merge.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/pr_close.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/system.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/system_df.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/system_prune.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/server_start.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/server_stop.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/server_status.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/preflight.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
-
-Behavior scenarios to add or preserve:
-- `exec` still routes through the server only when its command-local `server_url` is set
-- `model` still honors configured `[server].base_url` when no explicit `storage_dir` is set
-- `model` command-local `server_url` still overrides configured base URL
-- `model` command-local `storage_dir` still forces local behavior
-- old top-level target-flag placement fails at parse time
-
-For snapshot churn:
-- use the repo workflow from `CLAUDE.md`
- - `cargo insta pending-snapshots`
- - verify the expected help/output changes
- - `cargo insta accept`
-
-## Dependencies And Sequencing
-Apply the change in this order:
-
-1. add the new command-scoped target arg structs in `args.rs`, but keep `storage_dir` and `server_url` on `GlobalArgs` temporarily so the crate still compiles during migration
-2. add the new explicit helpers in `user_config.rs` alongside the old global-based helpers
-3. repoint `exec` and `model` to the new target arg structs and helpers
-4. repoint the local-storage and server command modules, plus test harness/env wiring, off `GlobalArgs`
-5. remove `storage_dir` and `server_url` from `GlobalArgs`, then delete the old global-based helper path once it is unused
-6. update parser tests for the final clap shape, then update docs and help snapshots
-
-This ordering keeps the refactor compile-safe: helper and command migration happen before the old global fields are removed, and parser assertions about the old top-level syntax move to the final cleanup step where they become true.
-
-## Test Plan
-- targeted parser/unit tests:
- - `cargo test -p fabro-cli --lib main::tests -- --nocapture`
- - `cargo test -p fabro-cli --lib user_config::tests -- --nocapture`
-- targeted CLI integration tests:
- - `cargo nextest run -p fabro-cli cmd::exec:: --no-fail-fast`
- - `cargo nextest run -p fabro-cli cmd::model:: cmd::model_list:: cmd::model_test:: cmd::config:: --no-fail-fast`
- - `cargo nextest run -p fabro-cli cmd::run:: cmd::create:: cmd::attach:: cmd::logs:: cmd::resume:: cmd::rewind:: cmd::wait:: cmd::diff:: cmd::runner:: --no-fail-fast`
- - `cargo nextest run -p fabro-cli cmd::server_start:: cmd::server_stop:: cmd::server_status:: --no-fail-fast`
-- broader CLI sweep after targeted coverage is green:
- - `cargo nextest run -p fabro-cli --no-fail-fast`
-- final verification:
- - `cargo fmt --check --all`
- - `cargo clippy --workspace --all-targets -- -D warnings`
-
-## Assumptions And Defaults
-- Pre-production status means removing the old global target-flag placement is acceptable; no compatibility shim is required.
-- `FABRO_STORAGE_DIR` and `FABRO_SERVER_URL` remain useful and should stay, but only where the corresponding command actually supports the underlying behavior.
-- The recent `model` and `exec` behavioral contracts are already correct; this pass is about CLI honesty and arg ownership, not product redefinition.
-- If we later want a broader “remote-capable command matrix” abstraction, it should be built on top of these command-local args rather than by reintroducing misleading global target flags.
diff --git a/docs/plans/2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md b/docs/plans/2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md
deleted file mode 100644
index 4b3f0c56e..000000000
--- a/docs/plans/2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md
+++ /dev/null
@@ -1,242 +0,0 @@
-# CLI Exec Explicit Local Sessions And Mode Removal
-
-## Summary
-Simplify the last misleading CLI mode seam by:
-
-- making `fabro exec` explicitly CLI-owned/local
-- removing the global `ExecutionMode` / `resolve_mode` abstraction entirely
-- deleting `mode` from user config and resolved `Settings`
-- treating Fabro server usage as a command-specific connection choice instead of a whole-program execution mode
-
-This pass does **not** move the agent loop into the server. `fabro exec` remains a local agent session. The only server-backed `exec` behavior in scope is optional model transport through `FabroServerAdapter` and the existing `/completions` endpoint.
-
-## Scope Boundaries
-In scope:
-- `fabro exec`
-- removal of `ExecutionMode`, `ResolvedMode`, and `resolve_mode`
-- removal of `mode` from `user.toml` / `Settings`
-- command-scoped server-target resolution for `exec`
-- small adjacent `model` cleanup needed so `[server]` remains meaningful after `mode` is removed
-- docs/help/config/test cleanup for the new contract
-
-Out of scope:
-- server-owned interactive agent sessions
-- new `/exec`, `/sessions`, or worker-RPC server APIs
-- moving tool execution, MCP, permissions, or output rendering into the server
-- changing the run lifecycle commands
-- changing the `/completions` API contract
-- adding a new persistent `exec` config field for default server routing
-
-## Key Decisions
-- `fabro exec` always owns the agent session locally:
- - prompt loop
- - tool execution
- - permission prompts
- - MCP connections
- - event/output rendering
-- when `fabro exec` uses a Fabro server, only the LLM transport changes:
- - requests go through `fabro_llm::providers::FabroServerAdapter`
- - the adapter continues to call the existing `/completions` endpoint
-- remove `mode` entirely instead of narrowing it.
- - Once `exec` stops using it, there is no legitimate runtime consumer left.
-- `fabro exec` remote routing stays an explicit per-invocation choice in this pass:
- - `--server-url` enables server-routed model transport
- - configured `[server].base_url` alone does **not** reroute `exec`
- - Rationale: this keeps `exec` honest as a local command and avoids inventing a new “force direct” override surface immediately.
-- `[server]` remains a real config surface after `mode` removal, but its meaning changes:
- - it stores connection information for commands that support a remote Fabro server target
- - it is not a whole-program execution mode switch
-- `fabro model` should honor configured `[server].base_url` as its default remote target once `mode` is gone.
- - `--server-url` still overrides config
- - explicit `--storage-dir` still forces local auto-start for `model`
- - this is a small collateral cleanup to keep the config contract coherent
-- keep the global `--server-url` / `--storage-dir` clap conflict unchanged in this pass.
- - Rationale: reducing the misleading mode abstraction does not require broad CLI flag-surface churn, and `exec` does not need both simultaneously.
-- global help/docs must stop claiming:
- - `--storage-dir` implies standalone mode
- - `--server-url` implies server mode
-- no backward-compatibility shim is required for `mode` in `user.toml`, `fabro settings`, or docs.
-- `mode = "server"` / `mode = "standalone"` should disappear completely from the supported config surface:
- - remove it from docs, examples, tests, and resolved settings output
- - existing user config files that still contain it are out of contract after this pass
- - if deserialization happens to ignore the stale key, that is incidental behavior, not preserved product surface
-
-## Implementation Changes
-### 1. Remove global mode from shared config and settings types
-Delete the dead mode concept from the shared config graph.
-
-In `lib/crates/fabro-types/src/settings/user.rs`:
-- delete `ExecutionMode`
-
-In `lib/crates/fabro-types/src/settings/mod.rs`:
-- remove the `ExecutionMode` re-export
-- remove `Settings.mode`
-
-In `lib/crates/fabro-config/src/user.rs`:
-- stop re-exporting `ExecutionMode`
-
-In `lib/crates/fabro-config/src/config.rs`:
-- remove `ConfigLayer.mode`
-- remove `mode` combine logic
-
-In `lib/crates/fabro-config/src/settings.rs`:
-- stop mapping `value.mode` into `Settings`
-
-Behavior:
-- `fabro settings` no longer emits a `mode` field
-- `user.toml` no longer documents or accepts `mode` as a meaningful setting in this pass
-
-### 2. Replace `resolve_mode` with command-scoped server-target helpers
-Stop encoding command behavior as a fake global mode decision.
-
-In `lib/crates/fabro-cli/src/user_config.rs`:
-- delete:
- - `ResolvedMode`
- - `resolve_mode(...)`
-- keep `build_server_client(...)`
-- add one small shared remote-target type, for example:
- - `ServerTarget { base_url: String, tls: Option }`
-- update `apply_global_overrides(...)` so it only applies:
- - `storage_dir`
- - `server.base_url`
- - and does **not** synthesize any `mode`
-- if `apply_global_overrides(...)` becomes a trivial two-field merge helper after `mode` removal, inline it at the call sites instead of preserving it mechanically
-- add concrete helpers that reflect the real command boundaries:
- - `exec_server_target(globals: &GlobalArgs, settings: &Settings) -> Option`
- - `model_server_target(globals: &GlobalArgs, settings: &Settings) -> Option`
-
-Expected helper semantics:
-- `exec` helper:
- - returns a remote server target only when `--server-url` is present
- - uses configured `[server].tls` if available
- - ignores configured `[server].base_url` when no CLI flag is present
-- `model` helper:
- - returns `--server-url` when present
- - otherwise returns configured `[server].base_url` when present and no explicit `--storage-dir` was provided
- - otherwise returns no remote target so the command falls back to local server auto-start
-
-This helper split is intentional. `exec` and `model` are both server-aware, but they do not have the same defaulting rules.
-
-### 3. Make `fabro exec` explicitly local with optional server-routed model transport
-Remove the last server-vs-standalone branching from the command implementation.
-
-In `lib/crates/fabro-cli/src/commands/exec.rs`:
-- remove the `resolve_mode(...)` call
-- remove the `match resolved.mode { ... }` branch
-- always build the session as a local CLI-owned agent session
-- when the `exec` server-target helper returns `Some(target)`:
- - build the HTTP client with `build_server_client(...)`
- - create a `FabroServerAdapter`
- - register it on a `fabro_llm::Client`
- - call `run_with_args_and_client(...)`
-- when the helper returns `None`:
- - keep the direct provider path via `run_with_args(...)`
-- replace logging from `mode = "server"/"standalone"` to something transport-shaped such as:
- - `transport = "server"`
- - `transport = "direct"`
-
-Keep unchanged:
-- permission behavior
-- MCP server wiring
-- output format behavior
-- sub-agent behavior
-- sandbox/tool execution ownership
-
-### 4. Keep `[server]` meaningful after removing `mode`
-Make the shared server config still useful without preserving the abstract mode layer.
-
-In `lib/crates/fabro-cli/src/commands/model.rs`:
-- stop hand-rolling the `globals.server_url` match
-- use the new model-target helper from `user_config.rs`
-- preserve current user-visible `model` behavior apart from the new config defaulting:
- - remote target when `--server-url` is passed
- - remote target when `[server].base_url` is configured and no explicit `--storage-dir` is passed
- - local auto-start otherwise
-
-This is the only planned collateral behavior change outside `exec`, and it exists to keep `[server]` coherent after `mode` removal.
-
-### 5. Remove stale docs and help text
-Rewrite the user-facing contract around explicit server targets instead of execution modes.
-
-In `lib/crates/fabro-cli/src/args.rs`:
-- no `--mode` flag exists today, so there is no parser flag removal in this file
-- update the global flag docstrings:
- - `--storage-dir` should describe local data/storage selection only
- - `--server-url` should describe targeting a Fabro API server for commands that support it
-- remove any wording that says either flag “implies” a mode
-
-In docs:
-- `docs/reference/user-configuration.mdx`
- - remove the `mode` section
- - rewrite `[server]` as connection info for remote-target-capable commands
- - clarify the `exec` vs `model` behavior split explicitly
-- `docs/reference/cli.mdx`
- - update the global option descriptions for `--storage-dir` and `--server-url`
-- `docs/administration/deploy-server.mdx`
- - remove guidance telling users to set `mode = "server"` in `user.toml`
- - rewrite the “Pointing the CLI at a server” section around:
- - `--server-url`
- - configured `[server].base_url`
- - command-specific behavior
-- update any nearby docs that still describe “whole CLI server mode” rather than explicit server-target selection
-
-### 6. Remove or rewrite stale tests
-Delete tests that only exist to preserve `mode` semantics, and add coverage for the real command boundaries.
-
-In `lib/crates/fabro-cli/src/user_config.rs` tests:
-- replace `resolve_mode_*` tests with helper-focused tests covering:
- - `exec` has no server target by default
- - `exec` uses CLI `--server-url`
- - `exec` ignores configured `[server].base_url` without CLI `--server-url`
- - `model` uses configured `[server].base_url`
- - `model` CLI `--server-url` overrides configured base URL
- - `model` explicit `--storage-dir` suppresses configured remote targeting
- - TLS is still taken from `[server].tls` when a remote target is selected
-
-In `lib/crates/fabro-cli/tests/it/cmd/exec.rs`:
-- update help snapshots for the new global flag wording
-- add one behavior test proving `--server-url` changes the failure mode away from local missing-provider-key validation
- - for example: with no local provider key configured and an unreachable `--server-url`, the command should fail on remote connection rather than `API key not set for provider ...`
-- add one regression test proving configured `[server].base_url` alone does not reroute `exec`
- - expected outcome: with no local provider key, `exec` still fails on the local missing-key path
-- add one explicit override test proving CLI `--server-url` wins over configured `[server].base_url` for `exec`
- - expected outcome: with both present, the command targets the CLI URL and the failure shape reflects that URL/path rather than the configured one
-
-In `lib/crates/fabro-cli/tests/it/cmd/model.rs` and/or `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`:
-- add coverage showing configured `[server].base_url` is honored without passing `--server-url`
-
-In `lib/crates/fabro-cli/tests/it/cmd/config.rs`:
-- remove `ExecutionMode` imports and expectations
-- update `fabro settings` assertions so `mode` is no longer expected in resolved output
-- keep coverage that `--server-url` still overrides configured `[server].base_url`
-
-In help snapshots:
-- update any snapshots whose global options block still mentions implied server/standalone mode
- - especially:
- - `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/model.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/config.rs`
-- use the repo snapshot workflow from `CLAUDE.md`:
- - run `cargo insta pending-snapshots`
- - verify the expected help/output changes
- - then run `cargo insta accept`
-
-## Test Plan
-- Targeted unit tests:
- - `cargo test -p fabro-cli user_config::tests -- --nocapture`
-- Targeted CLI integration tests:
- - `cargo nextest run -p fabro-cli cmd::exec:: cmd::model:: cmd::model_list:: cmd::config:: --no-fail-fast`
-- Broader regression sweep after the targeted tests are green:
- - `cargo nextest run -p fabro-cli --no-fail-fast`
-- Final verification:
- - `cargo fmt --check --all`
- - `cargo clippy --workspace --all-targets -- -D warnings`
-
-## Assumptions And Defaults
-- `fabro exec` remains a local agent session in this pass. If we later want server-owned interactive sessions, that should be a separate product/architecture plan.
-- The existing `/completions` endpoint and `FabroServerAdapter` are sufficient for optional server-routed `exec` model traffic.
-- Pre-production status means removing `mode` outright is acceptable; no shim or migration warning is required.
-- `[server].base_url` remains valuable as a remote target config surface for commands like `model`, even after `mode` is removed.
-- `exec` staying CLI-flag-only for server routing is intentional in this pass. If users later need a default server-routed `exec`, that should be introduced as an explicit `exec`-scoped config surface rather than reintroducing a fake whole-program mode.
diff --git a/docs/plans/2026-04-05-cli-model-server-canonical-and-llm-removal-plan.md b/docs/plans/2026-04-05-cli-model-server-canonical-and-llm-removal-plan.md
deleted file mode 100644
index 11630b591..000000000
--- a/docs/plans/2026-04-05-cli-model-server-canonical-and-llm-removal-plan.md
+++ /dev/null
@@ -1,364 +0,0 @@
-# CLI Model Server Canonicalization And LLM Namespace Removal
-
-## Summary
-Take the next low-risk simplification step after the run lifecycle cleanup by:
-
-- removing the entire unused `fabro llm` CLI namespace
-- making the `fabro model` family fully server-canonical
-- leaving `fabro exec` unchanged for now
-
-This pass is intentionally asymmetric:
-- `fabro llm` is removed from the CLI surface entirely
-- `fabro model` remains, but becomes a server-backed command family instead of a mixed standalone/server command
-- `fabro model test` keeps its current bulk/fan-out role in the CLI, but the server endpoint remains single-model only with an explicit test mode
-
-Because backward compatibility is not required yet, this pass should prefer simplification over shims. `model test --deep` stays, but it becomes an explicit server capability via `mode=basic|deep` on the single-model test endpoint instead of relying on the old mixed local/server split.
-
-## Scope Boundaries
-In scope:
-- remove `fabro llm`
-- add `provider` and `query` filters to `GET /api/v1/models`
-- keep `POST /api/v1/models/{id}/test` as a single-model health/test endpoint
-- add optional `mode=basic|deep` to `POST /api/v1/models/{id}/test`
-- make `fabro model list` and `fabro model test` always use the server
-
-Out of scope:
-- `fabro exec`
-- broader removal of `ExecutionMode` / `resolve_mode` outside the `model` command family
-- changing `POST /models/{id}/test` into a bulk endpoint
-- changing model storage/catalog ownership away from the server’s built-in catalog
-- deleting lower-level `fabro_llm::cli` prompt/chat helpers unless they become dead and trivially removable during the refactor
-
-## Key Decisions
-- `GET /api/v1/models` gets flat query params, not a generic filter object:
- - `provider=`
- - `query=`
-- `query` matches `id`, `display_name`, and `aliases`, case-insensitively.
-- Pagination applies after filtering.
-- filtered `/api/v1/models` results preserve the built-in catalog order.
-- invalid `provider` filter values are rejected with `400`, not treated as “no filter” or “no matches”.
-- "invalid" means the query value fails to parse as a known `fabro_model::Provider` enum variant.
-- a parsed `provider` value that happens to match zero catalog entries still returns `200` with an empty page.
-- `POST /api/v1/models/{id}/test` continues to test exactly one model per request and gains one optional query param:
- - `mode=basic|deep`
- - default: `basic`
-- CLI fan-out stays in `fabro model test`, not in the HTTP API.
-- `model test --deep` is preserved and maps to `mode=deep` on repeated single-model server calls.
-- `fabro model` should use the generated `fabro_api::Client` for model HTTP calls, not ad hoc raw `reqwest` + URL assembly.
-- `fabro model` gets a command-specific server-target helper rather than reusing global `ExecutionMode` branching.
- - if `--server-url` is present, use remote HTTP(S) with configured TLS
- - otherwise use local server auto-start + Unix socket for the selected storage dir
- - this does not change `resolve_mode` behavior for other commands
-- `basic` is the explicit name for the current simple health check mode.
- - Rationale: an enum-shaped mode is clearer than `deep=true` and leaves room for future test kinds without changing the endpoint shape.
-- `POST /api/v1/models/{id}/test` accepts either a canonical model ID or an alias.
- - The server resolves aliases using the built-in catalog.
- - The response should always return the canonical `model_id`, not the alias string from the path.
-- `model test --model ` should POST the provided value directly to `/api/v1/models/{id-or-alias}/test`.
- - the CLI does not pre-resolve aliases via `GET /models`
-- CLI `model list --json` preserves its current output contract as a plain array of model objects.
- - The server remains paginated internally, but the CLI should flatten that to preserve the existing CLI JSON surface.
-- Deep-mode API results remain binary at the schema level:
- - success cases return `status: ok`
- - any deep validation failure returns `status: error`
- - the failure details go in `error_message`
- - no new warning/partial result state is introduced in this pass
- - models without required tool support still return HTTP `200` with `status: error`
- - absence of reasoning traces alone does not fail deep mode in this pass
-
-## Implementation Changes
-### 1. Remove the `fabro llm` CLI namespace
-Update the CLI surface so `fabro llm` no longer exists.
-
-In `lib/crates/fabro-cli/src/args.rs`:
-- remove the `Commands::Llm` variant
-- remove `LlmNamespace` and `LlmCommand`
-- remove `ChatArgs` / `PromptArgs` imports from `fabro_llm::cli`
-- remove command-name mapping for `llm prompt` and `llm chat`
-
-In `lib/crates/fabro-cli/src/main.rs`:
-- remove the `Commands::Llm(...)` dispatch arm
-
-In `lib/crates/fabro-cli/src/commands/mod.rs`:
-- remove `pub(crate) mod llm;`
-
-Delete:
-- `lib/crates/fabro-cli/src/commands/llm/mod.rs`
-- `lib/crates/fabro-cli/src/commands/llm/chat.rs`
-- `lib/crates/fabro-cli/src/commands/llm/prompt.rs`
-
-Test/support cleanup:
-- remove `mod llm;` and `mod llm_prompt;` from `lib/crates/fabro-cli/tests/it/cmd/mod.rs`
-- delete:
- - `lib/crates/fabro-cli/tests/it/cmd/llm.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/llm_prompt.rs`
-- remove the now-unused `TestContext::llm()` helper from `lib/crates/fabro-test/src/lib.rs`
-- update top-level help snapshots in `lib/crates/fabro-cli/tests/it/cmd/fabro.rs` and any parser/help coverage that still mentions `llm`
-
-This pass should only remove the CLI namespace. Do not widen the blast radius by opportunistically deleting unrelated lower-level LLM helpers unless the compiler proves they are now dead and the deletion is mechanical.
-
-Because `fabro llm` is the only CLI surface for these paths today, expect some prompt/chat internals to become dead as a direct consequence of this removal. If the compiler confirms there are no remaining callers, delete the dead items in this pass rather than preserving unreachable code:
-- `PromptArgs`
-- `ChatArgs`
-- `run_prompt`
-- `run_chat`
-- `run_prompt_via_server`
-- `run_chat_via_server`
-
-### 2. Make `/api/v1/models` a real server-owned list endpoint
-Treat `/api/v1/models` as a canonical non-demo API surface.
-
-In `docs/api-reference/fabro-api.yaml`:
-- add optional query parameters to `GET /api/v1/models`:
- - `provider`
- - `query`
-- document `query` matching semantics explicitly:
- - substring match
- - case-insensitive
- - fields: `id`, `display_name`, `aliases`
-- add optional query parameter to `POST /api/v1/models/{id}/test`:
- - `mode=basic|deep`
- - default behavior when omitted: `basic`
- - document `basic` as the current simple prompt/availability check
- - document `deep` as the multi-turn tool-use / reasoning round-trip check
-
-In `lib/crates/fabro-server/src/server.rs`:
-- keep `/models/{id}/test` wired to the real server handler
-- stop treating `/models` as demo semantics only
-- replace the `demo::list_models` route usage with a non-demo handler
-- implement a small query extractor for model filters and pagination in the real server path
-- implement a small query extractor for model test mode in the `test_model` handler
-- fix the `test_model` response to use `info.id` (the canonical model ID from the catalog lookup) instead of the raw `id` path parameter in all response branches, so alias lookups return the canonical ID
-
-In `lib/crates/fabro-server/src/demo/mod.rs`:
-- `demo::list_models` is currently wired in both `demo_routes()` and `real_routes()`; replace both usages with the new non-demo handler
-- remove the now-unused `list_models` helper from the demo module
-
-Behavior:
-- server builds the list from `fabro_model::Catalog::builtin()`
-- applies `provider` filter if present
-- applies `query` filter if present
-- paginates the filtered list
-- returns the same `PaginatedModelList` schema shape as today
-- preserves built-in catalog order after filtering
-- rejects unknown `provider` values with `400`
- - this means parse failure against `fabro_model::Provider`
- - a valid parsed provider with zero matching models still returns `200` and an empty page
-- `POST /models/{id}/test`:
- - defaults to `basic`
- - accepts either a canonical model ID or an alias
- - runs the current simple one-prompt check in `basic` mode
- - runs the deeper multi-turn tool-use / reasoning check in `deep` mode
- - still returns one result object for one model
-
-### 3. Make `fabro model` server-canonical
-Remove standalone/server branching from the CLI `model` command family.
-
-In `lib/crates/fabro-cli/src/commands/model.rs`:
-- stop using `resolve_mode`
-- stop passing `Option` into `run_models(...)`
-- construct a typed `fabro_api::Client` up front and pass it through unconditionally
-
-In `lib/crates/fabro-cli/src/server_client.rs`:
-- keep the existing local auto-start + Unix-socket path for storage-backed connections
-- add one small model-command helper that returns a typed `fabro_api::Client` from either:
- - explicit remote base URL + configured TLS (`--server-url`), or
- - local auto-start + Unix socket for the selected storage dir
-- if needed, split the current Unix-only local connect helper into:
- - a local auto-start helper, and
- - a thin typed-client constructor for remote HTTP(S) base URLs
-- do not route `model` through `ServerStoreClient`; `model` should use the generated API client directly
-
-This change is intentionally command-specific:
-- `--server-url` keeps working for remote server usage
-- `--storage-dir` or default local storage uses local server auto-start
-- `model` no longer branches on `ExecutionMode`
-- global `resolve_mode` behavior for other commands stays unchanged in this pass
-
-### 4. Simplify model selection and test orchestration
-Keep the CLI in charge of bulk orchestration, but move catalog authority to the server.
-
-In `lib/crates/fabro-llm/src/cli.rs`:
-- replace the raw `reqwest` + `base_url` model HTTP helpers with generated `fabro_api::Client` calls
-- update `fetch_models_from_server(...)` to forward `provider` and `query` to the server instead of filtering locally after the response
-- update the fetch helper to follow pagination until `meta.has_more` is false instead of assuming one page is enough
-- remove local provider filtering from the fetch helper
-- remove the local query filtering in `run_models(...)` (the `if let Some(q) = &query { ... models.retain(...) }` block), since the server now handles query filtering
-- simplify `run_models(...)` so it no longer accepts an optional server connection; `model` should always call the server-backed path
-- keep `model test` fan-out behavior in the CLI:
- - `model test --model ` calls `POST /models/{id-or-alias}/test` once
- - `model test --provider ` first resolves the filtered list via `GET /models?provider=...`, then POSTs `/test` once per returned model
- - bare `model test` first resolves the full list via `GET /models`, then POSTs `/test` once per model
- - `model test --deep` maps each request to `POST /models/{id}/test?mode=deep`
- - default `model test` behavior maps each request to `basic` mode
- - any shared fetch helper used from test fan-out paths passes `query=None`, because query filtering remains list-only in this pass
-
-Preserve current broad behavior where reasonable:
-- `--model` remains the direct single-model selector and should pass the user-supplied ID or alias through unchanged
-- unknown model inputs should continue to surface an “unknown model” style error when the server returns 404
-- CLI fan-out result formatting and failure aggregation should remain substantially the same
-- `model list --json` should continue to print a plain JSON array, not the server’s paginated envelope
-- CLI output order should preserve the server/catalog order
-- CLI selection behavior remains:
- - `--model` takes precedence over `--provider`
- - query filtering applies only to `list`, not `test`, unless explicitly added later
-
-### 5. Preserve `model test --deep` via server-owned test modes
-`--deep` remains useful, but it should stop depending on the old local test execution branch. The server should own both single-model test modes, and the CLI should only orchestrate fan-out.
-
-Server-side implementation:
-- extract the single-model test logic out of CLI-only code and into a reusable non-CLI helper in `fabro-llm` so the server can execute:
- - `basic` mode
- - `deep` mode
-- keep that logic in `fabro-llm`, not inline in the axum handler; this is LLM-domain behavior, not route-local glue
-- shape the extracted helper around an internal outcome type that already matches the binary API contract:
- - success => `status: ok`
- - failure => `status: error` plus message detail
-- preserve the current timeout budgets:
- - `basic` uses the current short timeout budget (`30s`)
- - `deep` uses the current long timeout budget (`90s`)
-- keep deep mode's current in-process tool-closure pattern from `build_deep_test_params`; this pass does not add RPC or external tool-runner infrastructure
-- `mode=deep` for a model without tool support returns HTTP `200` with `status: error` and a clear `error_message`
-- if a reasoning-capable model completes deep mode without reasoning traces, do not fail for that fact alone in this pass
-- the initial source material is the existing logic in `lib/crates/fabro-llm/src/cli.rs`:
- - `build_deep_test_params`
- - `validate_deep_result`
- - current one-model test logic
-- the end state should be:
- - server calls a reusable `fabro-llm` helper for one-model test execution
- - CLI no longer owns authoritative one-model test behavior
-- do not leave deep behavior only in the CLI-local path once `model` becomes server-canonical
-
-CLI-side implementation:
-- keep `deep` on `ModelsCommand::Test`
-- update the server-call helper(s) to pass `mode=deep` when requested
-- remove only the dead local standalone branches once the server owns both modes
-- remove the `"Warning: --deep is not supported in server mode"` diagnostic from `test_models_via_server`, since deep mode is now a server-owned capability
-- remove the `deep_unsupported` field from `ModelTestOutput` JSON serialization, since deep mode is now fully supported via the server
-
-In CLI help/snapshots:
-- keep `--deep` on `model test --help`
-- update wording if needed so it reflects a server-backed deep test rather than a local-only path
-
-### 6. Dependencies And Sequencing
-Apply this in order so the refactor has stable interfaces to land on:
-
-- land the OpenAPI changes for `/models` filters and `/models/{id}/test?mode=basic|deep` first
-- update the server list/test handlers, including provider parsing, alias handling, and canonical response IDs
-- extract the reusable single-model `basic` / `deep` test helper in `fabro-llm`
-- regenerate the Rust typed API client via `cargo build -p fabro-api`
-- repoint `fabro model` and its fetch/test helpers to the generated `fabro_api::Client`
-- remove the `fabro llm` CLI namespace and any compiler-confirmed dead prompt/chat code
-- regenerate the TypeScript client once the server contract is settled
-
-Section 2's endpoint and mode changes must land before replacing the deep-mode server flow described in Section 5.
-
-### 7. Regenerate typed API clients through the normal workflow
-Because `/api/v1/models` changes, follow the repo’s API workflow instead of hand-editing generated clients.
-
-Source of truth:
-- `docs/api-reference/fabro-api.yaml`
-
-Generated/regenerated artifacts:
-- Rust API client/types via `cargo build -p fabro-api`
-- TypeScript client via `cd lib/packages/fabro-api-client && bun run generate`
-
-Expected generated updates include:
-- `lib/packages/fabro-api-client/src/api/models-api.ts`
-- related generated model/type files under `lib/packages/fabro-api-client/src/models/`
-
-## Important Interface / Behavior Changes
-- `fabro llm` is removed from the CLI surface completely.
-- `fabro model` always talks to the server.
-- `GET /api/v1/models` accepts:
- - `provider`
- - `query`
-- invalid `provider` values return `400`
-- invalid `provider` means the value does not parse as a known `fabro_model::Provider`
-- valid provider filters that simply match zero models still return `200` with an empty page
-- filtered results preserve built-in catalog order
-- `POST /api/v1/models/{id}/test` accepts:
- - optional `mode=basic|deep`
- - default mode `basic`
-- `/models/{id}/test` accepts aliases but returns the canonical `model_id`
-- `model test --model ` posts that alias directly and relies on server-side alias resolution
-- `model test --deep` remains supported and maps to `mode=deep`.
-- `model list --json` continues to output a plain JSON array.
-
-## Test Plan
-CLI command surface:
-- `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
- - top-level help no longer lists `llm`
-- `lib/crates/fabro-cli/tests/it/cmd/model.rs`
- - bare `model` and `model list` still work
- - provider/query list behavior still matches expected snapshots
- - JSON output still parses as a plain array
- - `model list` still works with an auto-started local server and with `--server-url`
-- `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
- - help text still matches the new server-backed behavior
-- `lib/crates/fabro-cli/tests/it/cmd/model_test.rs`
- - help text still mentions `--deep`
- - unknown model still errors cleanly
- - `--model ` calls the single-model test endpoint directly and succeeds via server-side alias resolution
- - deep mode still routes through the server-backed model test flow
- - JSON output no longer includes `deep_unsupported`
-- delete now-obsolete `llm` CLI tests:
- - `lib/crates/fabro-cli/tests/it/cmd/llm.rs`
- - `lib/crates/fabro-cli/tests/it/cmd/llm_prompt.rs`
-
-Server/API behavior:
-- `lib/crates/fabro-server/src/server.rs`
- - add tests for `GET /api/v1/models` with:
- - no filters
- - `provider`
- - `query`
- - combined `provider + query`
- - case-insensitive query matching
- - pagination applied after filtering
- - invalid provider returns `400`
- - valid parsed provider + no matching query returns `200` with an empty page
- - filtered results preserve catalog order
- - extend `POST /api/v1/models/{id}/test` coverage for:
- - omitted mode defaults to `basic`
- - explicit `mode=basic`
- - explicit `mode=deep`
- - invalid mode rejected cleanly
- - alias path values resolve successfully and return the canonical `model_id`
- - unknown model still returns 404
- - `mode=deep` on a model without tool support returns `200` with `status: error`
-
-LLM CLI internals:
-- `lib/crates/fabro-llm/src/cli.rs`
- - update `fetch_models_from_server` unit tests to assert outgoing `provider` / `query` params
- - add coverage that multi-page server responses are fully traversed
- - update/remove tests that assumed client-side provider filtering
- - add coverage that test fan-out paths call the shared fetch helper with `query=None`
- - add or update server-call tests so deep mode is forwarded as `mode=deep`
- - add helper-level coverage for the binary deep-mode contract:
- - tool-less models return `error`
- - missing reasoning traces alone do not fail
- - remove only the dead standalone-only test coverage after server ownership is in place
-
-Full verification:
-- `cargo build -p fabro-api`
-- `cargo nextest run -p fabro-cli --no-fail-fast`
-- `cargo nextest run -p fabro-server`
-- `cargo fmt --check --all`
-- `cargo clippy --workspace -- -D warnings`
-- `cd lib/packages/fabro-api-client && bun run generate`
-
-## Assumptions And Defaults
-- `fabro llm` is dead product surface and should be removed cleanly, not hidden.
-- `exec` remains a separate product surface and is intentionally untouched in this pass.
-- `GET /api/v1/models` remains a built-in catalog view; this pass does not introduce live provider discovery.
-- CLI model fetches must traverse paginated `/models` responses until exhaustion.
-- `model test` remains a CLI orchestrator over repeated single-model HTTP calls.
-- local-storage-backed `fabro model` may auto-start the local server on first use.
-- for local auto-started servers, model testing assumes the daemon inherits the CLI environment, including provider credentials.
-- for explicit remote `--server-url` usage, provider credential availability is the remote server operator's responsibility.
-- `POST /api/v1/models/{id}/test` uses a single optional query param for mode selection:
- - `basic`
- - `deep`
-- Deep-mode validation failures are represented as `status: error` plus `error_message`, not a new intermediate status.
-- If both `--model` and `--provider` are supplied to `model test`, keep the current effective behavior of prioritizing the explicit model selection rather than inventing a new validation rule in this pass.
-- No backward-compatibility shims are needed for removed CLI commands or flags.
diff --git a/docs/plans/2026-04-05-cli-run-lifecycle-cleanup-compaction-plan.md b/docs/plans/2026-04-05-cli-run-lifecycle-cleanup-compaction-plan.md
deleted file mode 100644
index db4176f59..000000000
--- a/docs/plans/2026-04-05-cli-run-lifecycle-cleanup-compaction-plan.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# CLI Run Lifecycle Cleanup Compaction
-
-## Summary
-Simplify the proven server-backed CLI run lifecycle without changing execution topology in this pass.
-
-This pass keeps `/api/v1/runs/*` as the canonical run API, ignores `/boards/runs`, and treats the current server-owned in-process execution model as the stable behavior for now. The goal is to remove obsolete local-launcher compatibility, collapse duplicated server-backed lookup code, and leave the CLI in a cleaner client-to-server shape. The hidden internal command is renamed from `__detached` to `__runner` now so the code reflects its future role, but this pass does not yet make the server spawn it.
-
-## Key Changes
-### 1. Lock the cleanup boundary
-- Treat the run lifecycle surface as server-backed and cleanup-eligible:
- - `run`, `create`, `start`, `resume`, `attach`, `wait`, `logs`, `diff`, `preview`, `ssh`, `runs/*`, `pr/*`, `artifact/*`, `system df/prune`, `store dump`
-- Leave these out of scope for this pass:
- - global `ExecutionMode` / `resolve_mode`
- - `model`, `exec`, `llm chat`, `llm prompt`
- - `/boards/runs`
- - changing `POST /runs/{id}/start` to spawn a worker
- - introducing worker-RPC execution
-
-### 2. Rename and shrink the hidden worker entrypoint
-- Rename the hidden internal subcommand from `__detached` to `__runner`.
-- Rename the enum variant, parser tests, help snapshots, and the command module/test names so internal terminology matches the future worker model.
-- Narrow the hidden command contract to the minimum needed for its current thin behavior:
- - keep `run_id`
- - keep `resume`
- - keep storage selection via globals/settings
- - remove `run_dir`
- - remove `launcher_path`
-- Keep its implementation simple for now:
- - connect to the server
- - call `POST /runs/{id}/start`
- - poll terminal status
-- Do not keep `__detached` as an alias. This pass is the rename.
-
-### 3. Remove launcher-era compatibility
-- Delete the launcher-record subsystem in `commands/run/launcher.rs`:
- - record file creation/removal
- - stale PID cleanup
- - process-command matching
- - run-id fallback via launcher metadata
-- Simplify `attach` to a server-only model when no explicit child handle is supplied:
- - infer run ID from the explicit argument or `run_dir/id.txt`
- - infer storage dir from the `runs/` path shape only
- - cancel via `POST /runs/{id}/cancel`
- - remove launcher-PID probing, launcher-based kill logic, and “server-owned vs launcher-owned” branching
-- Remove the now-dead `engine_child` compatibility path from `attach` if it is no longer used by production callers.
-- Update `run`, `resume`, and related comments/tests so they describe server-owned execution accurately instead of launcher/detach-era behavior.
-
-### 4. Collapse duplicated server-backed run resolution
-- Add one small internal helper layer for server-backed run lookup and state access.
-- Move the repeated pattern out of individual commands:
- - connect to server for storage dir
- - list durable run summaries
- - resolve a user-supplied run selector against `runs_base(...)`
- - optionally fetch current state/events
-- Repoint already-server-backed commands to this helper so they stop hand-rolling the same summary lookup logic.
-- Keep behavior unchanged; this is compaction, not a semantic migration.
-
-### 5. Preserve the single-store ownership invariant explicitly
-- Do not add any direct SlateDB access to `__runner`.
-- Treat the server as the only SlateDB reader/writer.
-- Keep the future `__runner` model aligned with server-owned storage:
- - the worker process may execute workflow logic
- - all durable run mutation must still go through server HTTP endpoints over the Unix socket
-- In this cleanup pass, reflect that invariant in naming, comments, and any internal helper boundaries so later worker-RPC work does not have to undo new local-store assumptions.
-
-### 6. Remove stale transitional tests and comments
-- Rewrite or delete tests that only exist to preserve launcher-record or `__detached` behavior.
-- Keep tests that prove the intended architecture:
- - server-backed detached run creation/start/attach
- - no launcher record is created in normal run/start/resume flow
- - hidden `__runner` still parses and works with its reduced contract
-- Update misleading comments and docstrings that still describe local detached engine ownership.
-
-## Test Plan
-- Targeted CLI tests:
- - `cmd::start::*`
- - `cmd::attach::*`
- - `cmd::detached::*` renamed to `cmd::runner::*`
- - `cmd::resume::*`
- - `cmd::logs::*`
- - `cmd::wait::*`
-- Add or update focused tests for:
- - attach infers run ID from `id.txt` without launcher metadata
- - ctrl-c / detach uses server cancel for active runs
- - `__runner` help/parser no longer mentions launcher-era flags
- - no launcher files are created anywhere in the normal run/start/resume flow
-- Run full verification:
- - `cargo nextest run -p fabro-cli --no-fail-fast`
- - `cargo nextest run -p fabro-server`
- - `cargo fmt --check --all`
- - `cargo clippy --workspace -- -D warnings`
-
-## Assumptions And Defaults
-- `/boards/runs` is demo-only and ignored in this pass.
-- `POST /runs/{id}/start` continues to queue and execute runs inside the server process for now.
-- The future worker model is ordinary server-owned child processes, not detached launcher-managed processes.
-- The server remains the single SlateDB reader/writer; future `__runner` processes must use server HTTP endpoints over the Unix socket for durable mutation.
-- `__runner` is retained now because a later plan will make it the server-launched per-run worker, but that worker flip is explicitly not part of this cleanup pass.
-- The local run directory still exists and remains a valid source for `id.txt` and runtime/artifact paths where the current code already depends on it.
-- Broader standalone-to-server cleanup outside the proven run lifecycle area is deferred to a later plan.
diff --git a/docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md b/docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md
deleted file mode 100644
index e5667dbe5..000000000
--- a/docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md
+++ /dev/null
@@ -1,570 +0,0 @@
-# Run-Adjacent Server-Only Cleanup
-
-## Summary
-
-Make the remaining user-facing run-adjacent commands server-only:
-
-- `fabro resume`
-- `fabro diff`
-- `fabro fork`
-- `fabro rewind`
-- `fabro artifact list`
-- `fabro artifact cp`
-- `fabro pr create|list|view|merge|close`
-- `fabro sandbox preview`
-- `fabro sandbox ssh`
-- `fabro sandbox cp`
-
-After this pass, those commands should no longer resolve runs through local `runs/` directories or flatten `--storage-dir`. They should all target a server the same way the core lifecycle commands already do:
-
-1. explicit `--server` / `FABRO_SERVER`
-2. configured `[server].target`
-3. default local server instance, auto-started via the default local storage dir
-
-There is intentionally no separate “force local” override for these commands in this pass. If `[server].target` is configured, that target wins unless the user passes an explicit `--server` value pointing at a local Unix socket. This is a simplicity tradeoff, not an accidental regression.
-
-This is cleanup/compaction, not a new subsystem. The goal is to finish the architectural move already made for `run`, `create`, `start`, `attach`, `logs`, `wait`, `ps`, `inspect`, and `rm`.
-
-## Scope Boundaries
-
-In scope:
-- the commands listed above
-- shared run-resolution helpers in `fabro-cli`
-- missing thin server APIs needed to make sandbox-oriented commands truly server-only
-- CLI help/docs/snapshots for the new contract
-
-Out of scope:
-- `fabro store dump`
-- `fabro system df`
-- `fabro system prune`
-- hidden/internal commands like `__runner`
-- changing run execution topology
-- changing checkpoint format or git metadata format
-- changing GitHub auth/secrets flows
-
-## Problem Frame
-
-The run lifecycle is only partially simplified today.
-
-Core lifecycle commands are already server-only, but the rest of the run-adjacent surface still falls back to local path-based lookup through `ServerRunLookup` in [server_runs.rs](lib/crates/fabro-cli/src/server_runs.rs). That creates three kinds of drift:
-
-- some commands still expose `--storage-dir` even though the real abstraction is now a server target
-- some commands read local run files even when equivalent data already exists in server state/store
-- some commands still reconnect directly from the CLI to sandboxes, which breaks the “server-owned runs” abstraction for remote targets
-
-That is unnecessary complexity in a greenfield app with no production compatibility constraints.
-
-## Key Decisions
-
-- All in-scope commands become server-only.
- - They flatten `ServerTargetArgs`, not `StorageDirArgs`.
- - `--storage-dir` is removed from their public CLI surface.
- - `FABRO_STORAGE_DIR` is not part of the public contract for these commands.
- - If `[server].target` is configured, these commands use it unless an explicit `--server` is passed.
- - There is no separate “force local default instance” flag.
-
-- `ServerRunLookup` becomes local/admin-only.
- - Keep it only for genuinely local maintenance commands like `store dump`, `system df`, and `system prune`.
- - User-facing run commands should resolve selectors through `ServerSummaryLookup` plus server state/events.
-
-- `fabro diff` is simplified to stored server-backed output only.
- - Drop the live sandbox reconnect fallback.
- - Drop `--stat` and `--shortstat`.
- - Output comes only from stored diff data already present in run state (`final_patch` and per-node `diff`).
- - If no stored diff exists, return a clear error.
-
-- `fabro fork` and `fabro rewind` remain local git operations, but not local run-store operations.
- - Run selection and run event/state loading come from the target server.
- - Repo mutation still happens against the caller’s local checkout, which is the correct boundary.
- - Before mutating the repo, the CLI should compare the current checkout against a durable stored repo identity and fail fast on obvious mismatch.
-
-- `fabro pr *` stays CLI-owned for GitHub network calls, but server-owned for run lookup and pull-request record loading.
- - This keeps the current GitHub App model intact while removing local run-dir dependence.
- - `pr create` should use the same repo-mismatch guard as `fork` and `rewind` before operating on the caller’s checkout.
-
-- `fabro artifact *` should reuse the existing stage artifact API instead of walking local `artifacts/` directories.
- - The CLI can derive relevant stage IDs from `RunProjection.nodes` and call the existing stage artifact list/download endpoints.
-
-- `fabro sandbox preview`, `fabro sandbox ssh`, and `fabro sandbox cp` should stop reconnecting to sandboxes directly from the CLI.
- - The server owns the sandbox record and should own the reconnect.
- - The CLI becomes a thin consumer of server responses.
-
-- The server API should stay thin and capability-shaped.
- - Reuse existing APIs where they already exist.
- - Add only the missing endpoints required for truly server-only sandbox operations.
-
-- Backward compatibility is not a goal.
- - Remove obsolete flags and behavior instead of shimming them.
- - Prefer deleting speculative unused surface over preserving it.
-
-## Sequencing
-
-This plan should land in two phases.
-
-Phase 1: pure CLI/server-state cleanup using APIs that already exist
-
-- `resume`
-- `fork`
-- `rewind`
-- `pr *`
-- `artifact list`
-- `artifact cp` (the stage artifact list/download routes already exist and are implemented)
-- `diff`
-- Phase 1 OpenAPI cleanup for `diff`:
- - delete `/api/v1/runs/{id}/files`
-- shared `ServerSummaryLookup` / `ServerRunLookup` narrowing
-- help/docs/snapshot churn for those commands
-
-Phase 2: thin server API completion for sandbox-owned commands
-
-- `sandbox preview`
-- `sandbox ssh`
-- `sandbox cp`
-
-This keeps the simpler repoints from being blocked on the few missing server capability routes.
-
-The final `ServerRunLookup` narrowing should happen only after the last in-scope command that still imports it has been migrated. Do not try to enforce an admin-only boundary halfway through the sequence while migrated and unmigrated command families still coexist.
-
-## Implementation Changes
-
-### 0. Add a durable repo identity field for local-repo operations
-
-The current `RunRecord.host_repo_path` is a filesystem path, not a durable cross-machine identity. It should not be used for a server-targeted repo-mismatch guard.
-
-Add a new persisted field to `RunRecord`, for example:
-
-- `repo_origin_url: Option`
-
-Recommended semantics:
-
-- source it from `RunManifest.git.origin_url`, which is already sanitized before it reaches the server
-- persist it in the run record when a manifest-sourced run is created
-- treat it as the canonical repo-identity signal for CLI commands that mutate or inspect the caller’s local checkout on behalf of a server-selected run
-
-Normalization rules should be explicit and shared:
-
-- strip embedded credentials
-- normalize GitHub-style SSH URLs to HTTPS form
-- trim a trailing `.git`
-- trim trailing `/`
-
-Guard behavior:
-
-- `fork`, `rewind`, and `pr create` detect the current checkout’s origin URL locally
-- normalize it with the same helper used for the stored field
-- if both sides are present and clearly differ, fail with a targeted repo-mismatch error
-- if the stored field is absent, skip the guard rather than inventing a heuristic fallback
-
-Files expected to change:
-
-- [run.rs](lib/crates/fabro-types/src/run.rs)
-- the manifest-backed run creation path that already receives `manifest.git.origin_url`
-- any serialization/projection paths that persist and reload `RunRecord`
-
-### 1. Convert remaining run-adjacent args to `ServerTargetArgs`
-
-In [args.rs](lib/crates/fabro-cli/src/args.rs):
-
-- replace `StorageDirArgs` with `ServerTargetArgs` for:
- - `ArtifactListArgs`
- - `ArtifactCpArgs`
- - `CpArgs`
- - `PreviewArgs`
- - `SshArgs`
- - `DiffArgs`
- - `ResumeArgs`
- - `RewindArgs`
- - `ForkArgs`
- - `PrCreateArgs`
- - `PrListArgs`
- - `PrViewArgs`
- - `PrMergeArgs`
- - `PrCloseArgs`
-
-Also simplify `DiffArgs`:
-
-- remove `stat`
-- remove `shortstat`
-- update help text to describe stored diff output only
-
-Resulting CLI contract:
-
-- `fabro diff --server http://127.0.0.1:3000/api/v1`
-- `fabro artifact list --server /var/run/fabro.sock`
-- `fabro sandbox ssh --server https://fabro.example.com/api/v1`
-- no `--storage-dir` on these commands
-- no public `FABRO_STORAGE_DIR` support on these commands
-
-### 2. Narrow shared lookup helpers
-
-In [server_runs.rs](lib/crates/fabro-cli/src/server_runs.rs):
-
-- keep `ServerSummaryLookup` as the default user-facing selector path
-- add any missing helper methods needed for:
- - selector resolution
- - filtered summary listing
- - summary-to-state/event follow-up work
-- keep `ServerRunLookup` only for commands that remain explicitly local/admin-only
-
-Do not try to finish that narrowing until the last in-scope migrated command is off `ServerRunLookup`.
-
-In [server_client.rs](lib/crates/fabro-cli/src/server_client.rs):
-
-- add thin wrappers for the server APIs the CLI now needs, split by phase:
- - Phase 1:
- - list stage artifacts
- - download stage artifact
- - Phase 2:
- - generate preview URL
- - create SSH access
- - sandbox file listing/download/upload
-
-Do not introduce a parallel target-resolution stack. Reuse:
-
-- `connect_server_only(...)`
-- `server_only_command_connection(...)`
-
-If tests still need `FABRO_STORAGE_DIR` internally to steer the default local server instance, treat that as harness-only plumbing rather than user-facing behavior.
-
-### 3. Repoint `resume` to the server-only lifecycle helpers
-
-In [resume.rs](lib/crates/fabro-cli/src/commands/run/resume.rs):
-
-- stop using `ServerRunLookup`
-- resolve the run via `ServerSummaryLookup`
-- call the existing direct-client start helper
-- for foreground resume:
- - attach through the existing direct-client attach helper
- - print the existing server-backed summary output with no local `run_dir`
-
-This is intentionally a small mechanical repoint. It should make `resume` match the already-simplified `start`/`attach` contract without introducing new behavior.
-
-### 4. Repoint `fork` and `rewind` to server-backed run state
-
-In [fork.rs](lib/crates/fabro-cli/src/commands/run/fork.rs) and [rewind.rs](lib/crates/fabro-cli/src/commands/run/rewind.rs):
-
-- stop using `ServerRunLookup`
-- resolve the run via `ServerSummaryLookup`
-- fetch events/state via the resolved `ServerStoreClient`
-- keep the local git/checkpoint mutation logic unchanged
-- before mutating the local repo, validate obvious identity against stored run metadata:
- - compare the current checkout’s detected repo identity against `RunRecord.repo_origin_url` when present
- - if they clearly do not match, fail with a targeted error instead of mutating the wrong checkout
-
-In [rewind.rs](lib/crates/fabro-cli/src/commands/run/rewind.rs):
-
-- remove dependence on `run.path` for rewound-state cleanup
-- if a small local run-dir cleanup is still required, compute it server-side or remove it
-- keep durable run-state restoration (`run.rewound`, restored checkpoint, `run.submitted`) server-backed
-
-The point is to make rewind/fork depend on the local repo, not on local run-store layout.
-
-### 5. Repoint `pr *` to server-backed run selection and record loading
-
-In [pr/mod.rs](lib/crates/fabro-cli/src/commands/pr/mod.rs) and subcommands:
-
-- remove `runs_base(...)` / `ServerRunLookup::connect_from_runs_base(...)`
-- resolve runs through `ServerSummaryLookup`
-- load pull-request state from `get_run_state(...)`
-
-Specific changes:
-
-- [pr/list.rs](lib/crates/fabro-cli/src/commands/pr/list.rs)
- - replace `scan_runs_with_summaries(...)` with summary iteration from `ServerSummaryLookup`
- - keep current GitHub detail-fetch fanout in the CLI
-
-- [pr/create.rs](lib/crates/fabro-cli/src/commands/pr/create.rs)
- - rebuild run state from server events instead of local path lookup
- - keep local repo detection via `detect_repo_info(...)`
- - apply the same repo-mismatch guard used by `fork` / `rewind` before proceeding
-
-- [pr/view.rs](lib/crates/fabro-cli/src/commands/pr/view.rs)
-- [pr/close.rs](lib/crates/fabro-cli/src/commands/pr/close.rs)
-- [pr/merge.rs](lib/crates/fabro-cli/src/commands/pr/merge.rs)
- - load the stored PR record from the target server only
-
-### 6. Make `diff` fully server-backed and simpler
-
-In [diff.rs](lib/crates/fabro-cli/src/commands/run/diff.rs):
-
-- stop using `ServerRunLookup`
-- resolve via `ServerSummaryLookup`
-- load `RunProjection` from the target server
-- keep only two sources of diff output:
- - per-node `diff`
- - run-level `final_patch`
-- remove sandbox reconnect and live diff generation entirely
-
-Behavior:
-
-- `fabro diff ` prints `final_patch`
-- `fabro diff --node ` prints the stored node diff
-- if no stored diff exists, error with a clear message
-
-Because this pass intentionally simplifies the product surface:
-
-- remove `--stat`
-- remove `--shortstat`
-- update docs/tests accordingly
-
-Also remove dead speculative server API surface tied to the old diff shape:
-
-- delete `/api/v1/runs/{id}/files` from [fabro-api.yaml](docs/api-reference/fabro-api.yaml)
-- remove the corresponding `not_implemented` route from [server.rs](lib/crates/fabro-server/src/server.rs)
-
-This is a Phase 1 OpenAPI/spec change and should be treated as part of that phase explicitly.
-
-That API is currently unimplemented and unused by the CLI. Keeping it around only adds drift.
-
-### 7. Repoint `artifact list` and `artifact cp` to the existing server artifact API
-
-In [artifact/list.rs](lib/crates/fabro-cli/src/commands/artifact/list.rs) and [artifact/cp.rs](lib/crates/fabro-cli/src/commands/artifact/cp.rs):
-
-- stop using `ServerRunLookup` and `RuntimeState`
-- resolve the run via `ServerSummaryLookup`
-- fetch `RunProjection`
-- enumerate stage IDs from `RunProjection.nodes`
-- use the existing stage artifact routes for each relevant stage:
- - list artifact filenames
- - download artifact bytes
-
-Keep filtering behavior in the CLI:
-
-- `--node`
-- `--retry`
-- tree/no-tree output layout
-- filename collision handling
-
-This preserves the current artifact UX while removing local artifact-dir reads.
-
-### 8. Finish preview/SSH/file-transfer as real server-owned sandbox operations
-
-This is the only part of the plan that needs new or completed server APIs.
-
-#### 8a. Preview
-
-The route already exists in [fabro-api.yaml](docs/api-reference/fabro-api.yaml) and [server.rs](lib/crates/fabro-server/src/server.rs), but the real handler is still `not_implemented`.
-
-Implement it in [server.rs](lib/crates/fabro-server/src/server.rs):
-
-- load the run’s sandbox record from store/state
-- reconnect server-side
-- for Daytona:
- - generate signed or unsigned preview URL as requested
-- return `409` if:
- - no active sandbox
- - sandbox provider does not support preview
-
-Then repoint [preview.rs](lib/crates/fabro-cli/src/commands/run/preview.rs) to the server API instead of direct Daytona reconnect.
-
-#### 8b. SSH
-
-Add a new route to [fabro-api.yaml](docs/api-reference/fabro-api.yaml):
-
-- `POST /api/v1/runs/{id}/ssh`
-
-Recommended request/response shape:
-
-- request:
- - `ttl_minutes`
-- response:
- - `command`
-
-Implement the handler in [server.rs](lib/crates/fabro-server/src/server.rs):
-
-- load sandbox record
-- reconnect server-side
-- generate SSH access for supported providers
-- return `409` when unsupported or unavailable
-
-Then repoint [ssh.rs](lib/crates/fabro-cli/src/commands/run/ssh.rs):
-
-- `--print` prints the returned command
-- non-`--print` locally `exec`s the returned command
-
-That preserves current UX while removing direct CLI sandbox reconnect.
-
-#### 8c. Sandbox file transfer (`fabro sandbox cp`)
-
-Add a small server-owned file-transfer surface for sandboxes.
-
-Recommended routes:
-
-- `GET /api/v1/runs/{id}/sandbox/files`
- - query:
- - `path`
- - optional `depth`
- - returns directory entries
-
-- `GET /api/v1/runs/{id}/sandbox/file`
- - query:
- - `path`
- - returns raw file bytes
-
-- `PUT /api/v1/runs/{id}/sandbox/file`
- - query:
- - `path`
- - request body:
- - raw file bytes
-
-Implementation in [server.rs](lib/crates/fabro-server/src/server.rs):
-
-- load sandbox record
-- reconnect server-side
-- delegate to the existing `Sandbox` trait:
- - `list_directory`
- - `download_file_to_local` equivalent via temp file or direct read/write helper
- - `upload_file_from_local` equivalent via temp file or direct write helper
-
-CLI changes in [cp.rs](lib/crates/fabro-cli/src/commands/run/cp.rs):
-
-- stop reconnecting to sandboxes directly
-- resolve runs via `ServerSummaryLookup`
-- for recursive download:
- - list directory via server
- - download files one by one via server
-- for upload:
- - recursively walk local input
- - upload files one by one via server
-
-This keeps the current UX and avoids inventing a tar/archive protocol.
-
-### 9. Update docs/help text to match the new surface
-
-Update:
-
-- [docs/reference/cli.mdx](docs/reference/cli.mdx)
-- [docs/reference/user-configuration.mdx](docs/reference/user-configuration.mdx)
-- [docs/core-concepts/how-fabro-works.mdx](docs/core-concepts/how-fabro-works.mdx)
-
-The docs should explicitly reflect:
-
-- in-scope run-adjacent commands now use `--server`, not `--storage-dir`
-- `diff` is stored-output only
-- sandbox preview/SSH/file transfer are server-mediated
-- local storage-dir maintenance commands still exist, but they are not the normal user-facing run lifecycle
-
-## Test Plan
-
-### Help/parser coverage
-
-Update snapshots in:
-
-- [artifact_list.rs](lib/crates/fabro-cli/tests/it/cmd/artifact_list.rs)
-- [artifact_cp.rs](lib/crates/fabro-cli/tests/it/cmd/artifact_cp.rs)
-- [diff.rs](lib/crates/fabro-cli/tests/it/cmd/diff.rs)
-- [fork.rs](lib/crates/fabro-cli/tests/it/cmd/fork.rs)
-- [resume.rs](lib/crates/fabro-cli/tests/it/cmd/resume.rs)
-- [rewind.rs](lib/crates/fabro-cli/tests/it/cmd/rewind.rs)
-- [pr_create.rs](lib/crates/fabro-cli/tests/it/cmd/pr_create.rs)
-- [pr_list.rs](lib/crates/fabro-cli/tests/it/cmd/pr_list.rs)
-- [pr_view.rs](lib/crates/fabro-cli/tests/it/cmd/pr_view.rs)
-- [pr_close.rs](lib/crates/fabro-cli/tests/it/cmd/pr_close.rs)
-- [pr_merge.rs](lib/crates/fabro-cli/tests/it/cmd/pr_merge.rs)
-- [sandbox_cp.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_cp.rs)
-- [sandbox_preview.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs)
-- [sandbox_ssh.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs)
-
-Scenarios:
-
-- help shows `--server`
-- help no longer shows `--storage-dir`
-- `diff --help` no longer shows `--stat` or `--shortstat`
-- no docs/help text implies these commands honor `FABRO_STORAGE_DIR`
-
-Use the normal snapshot workflow:
-
-1. `cargo insta pending-snapshots`
-2. inspect changes
-3. `cargo insta accept`
-
-### CLI targeting behavior
-
-Add or update CLI tests for each in-scope command family:
-
-- explicit `--server` wins
-- configured `[server].target` is used when no flag is passed
-- no explicit target uses the default local server instance
-
-Concrete tests:
-
-- `resume` uses configured server target without local run-dir lookup
-- `artifact list` uses configured server target without local artifact-dir lookup
-- `artifact cp` uses configured server target and downloads through the server
-- `pr list` uses configured server target without scanning local runs/
-- `pr view`/`pr merge`/`pr close` resolve records from the server target
-- `sandbox preview` uses the server endpoint instead of direct Daytona reconnect
-- `sandbox ssh --print` uses the server endpoint and prints the returned command
-- `sandbox cp` upload/download works against a target server without CLI-side sandbox reconnect
-- when `[server].target` is configured, these commands use it by default
-- there is no separate local override path besides passing an explicit local `--server`
-
-### Diff behavior coverage
-
-In [diff.rs](lib/crates/fabro-cli/tests/it/cmd/diff.rs):
-
-- completed run with stored final patch still prints patch
-- missing stored final patch errors cleanly
-- stored node diff still works
-- remove tests that depend on live diff fallback semantics
-
-### Fork/rewind/resume behavior coverage
-
-In:
-
-- [fork.rs](lib/crates/fabro-cli/tests/it/cmd/fork.rs)
-- [rewind.rs](lib/crates/fabro-cli/tests/it/cmd/rewind.rs)
-- [resume.rs](lib/crates/fabro-cli/tests/it/cmd/resume.rs)
-
-Add server-target coverage:
-
-- configured `[server].target` works without local run-store lookup
-- explicit `--server` overrides configured target
-- rewind/fork/resume continue to mutate only the local repo, not local run-store metadata files
-- rewind/fork/pr-create fail fast when the selected run’s stored `repo_origin_url` clearly does not match the current checkout
-- rewind/fork/pr-create skip the guard cleanly when older runs do not have a stored durable repo identity yet
-
-### Server API coverage
-
-Add server tests in [server.rs](lib/crates/fabro-server/src/server.rs) or the server integration suite for:
-
-- preview URL generation for a supported sandbox
-- preview rejects missing/unsupported sandboxes with `409`
-- SSH command generation for a supported sandbox
-- SSH rejects missing/unsupported sandboxes with `409`
-- sandbox file list/download/upload round-trip
-- stage artifact list/download continues to work for the CLI use case
-
-### Full verification
-
-- `cargo fmt --check --all`
-- `cargo clippy --workspace --all-targets -- -D warnings`
-- `cargo nextest run --workspace`
-
-## Risks
-
-- The biggest risk is accidentally preserving local run-path assumptions under a server-only CLI surface.
- - Mitigation: delete `--storage-dir` from in-scope commands and remove local lookup usage outright instead of trying to support both models.
-
-- `fork`, `rewind`, and `pr create` still depend on the caller’s local repo matching the selected run closely enough.
- - Mitigation: keep that boundary, but add an explicit repo-mismatch guard using stored run metadata so obvious mistakes fail fast.
-
-- `sandbox cp` is the largest unit because it needs a new server-owned file transfer surface.
- - Mitigation: keep the API thin and capability-shaped; do not design a generic virtual filesystem protocol.
-
-- Preview/SSH capability is provider-specific.
- - Mitigation: standardize on `409` for unsupported or unavailable sandbox capability.
-
-## Follow-on
-
-After this lands, the remaining local/admin seam should be small and explicit:
-
-- `store dump`
-- `system df`
-- `system prune`
-- any hidden/internal commands that truly operate on local storage
-
-At that point, `ServerRunLookup` should either:
-
-- be deleted entirely if those commands are also repointed later, or
-- be clearly renamed/documented as a local maintenance helper rather than a normal user-facing run abstraction
diff --git a/docs/plans/2026-04-05-run-create-server-target-plan.md b/docs/plans/2026-04-05-run-create-server-target-plan.md
deleted file mode 100644
index 6665ce289..000000000
--- a/docs/plans/2026-04-05-run-create-server-target-plan.md
+++ /dev/null
@@ -1,243 +0,0 @@
-# Run/Create Server Target Support
-
-## Summary
-Make `fabro run` and `fabro create` targetable via `--server` / `[server].target` now that run submission is manifest-based and server-owned.
-
-This pass should:
-
-- add `--server` support to `fabro run` and `fabro create`
-- align their target-resolution semantics with `preflight`, `validate`, and `graph`
-- remove the last local-storage-only assumptions from the run submission path
-- keep local run behavior unchanged when a local server is selected
-
-This is primarily cleanup/compaction, not a new subsystem. The manifest refactor already made remote submission possible; the CLI surface just has not caught up yet.
-
-## Scope Boundaries
-In scope:
-- `fabro run`
-- `fabro create`
-- the internal start/attach/summary helpers required for `fabro run` to work against an explicit server target
-- docs/help/tests for the new targeting contract
-
-Out of scope:
-- adding `--server` to top-level `fabro start`, `fabro attach`, `fabro wait`, `fabro logs`, `fabro inspect`, `fabro diff`, `fabro resume`, or `fabro rewind`
-- changing the HTTP API
-- changing manifest structure or workflow bundle persistence
-- changing server-side run ownership or execution topology
-
-Accepted temporary asymmetry:
-- `fabro create --server ...` will be supported in this pass even though the standalone follow-up lifecycle commands remain local-only.
-- That is acceptable because `create` already prints only a run ID and is useful for automation. A later pass can broaden remote targeting across the rest of the run lifecycle surface.
-
-## Problem Frame
-The CLI/server boundary is now inconsistent:
-
-- `preflight`, `validate`, and `graph` already build manifests and target either a local auto-started server or an explicit remote `--server`
-- `run` and `create` already build manifests, but they still only flatten `--storage-dir` and then hard-wire submission to `connect_server(settings.storage_dir())`
-- `run` still assumes every submitted run has a meaningful local run directory for attach and final summary output
-
-That is architectural drift. The system is already manifest-first and server-canonical. `run` and `create` are the remaining commands that still behave as if run submission is inherently local.
-
-## Key Decisions
-- `RunArgs` should flatten `ServerConnectionArgs`, not `StorageDirArgs`.
- - `fabro create` inherits the same args because it already reuses `RunArgs`.
-- `run` and `create` should use the same connection contract as other server-backed commands:
- - explicit `--server` wins
- - explicit `--storage-dir` selects a local server and suppresses configured `[server].target`
- - otherwise configured `[server].target` may be used
- - otherwise the command defaults to the local server for the resolved storage dir
-- `fabro run` should use one resolved server connection end-to-end for:
- - manifest submission
- - `POST /runs/{id}/start`
- - live attach / polling
-- `fabro create` should remain run-ID-only output.
- - It should not pretend there is always a local `run_dir`.
-- foreground `fabro run` against a remote/configured server should attach successfully.
- - This requires decoupling attach from local run-dir inference.
-- remote foreground `run` should print a server-backed final summary that omits local-only fields.
- - Keep: run ID, status, duration, cost/tokens, failure reason, PR URL, final output
- - Omit: local run directory path and local artifact listing when there is no local run dir
-- local `run` behavior should remain unchanged.
- - If the resolved connection is local, keep the existing local run-dir summary and asset listing behavior.
-- No OpenAPI change is required.
- - This is CLI cleanup on top of the existing manifest-backed `POST /runs`.
-
-## Implementation Changes
-
-### 1. Add target args to `run` / `create`
-In `lib/crates/fabro-cli/src/args.rs`:
-- change `RunArgs` to flatten `ServerConnectionArgs`
-- remove the dedicated `StorageDirArgs` field from `RunArgs`
-- keep all existing workflow/run override flags unchanged
-
-This updates both:
-- `fabro run`
-- `fabro create`
-
-Help/CLI contract to lock down:
-- `fabro run foo.fabro --server http://127.0.0.1:3000/api/v1`
-- `fabro create foo.fabro --server /var/run/fabro.sock`
-- `fabro run foo.fabro --storage-dir /tmp/fabro`
-- `fabro create foo.fabro` still defaults to local storage unless `[server].target` is configured
-
-### 2. Resolve run/create connections the same way as other server-backed commands
-In `lib/crates/fabro-cli/src/commands/run/command.rs` and `lib/crates/fabro-cli/src/commands/run/create.rs`:
-- keep using local user-config resolution for manifest defaults
- - load settings with storage-dir override only, using the command-local `storage_dir` value if present
-- stop deriving the submission client from `settings.storage_dir()`
-- instead resolve the server connection with the existing server-backed connection logic in `lib/crates/fabro-cli/src/user_config.rs`
-- connect using the resolved connection, not a hard-coded local store path
-
-Recommended shape:
-- let `create_run(...)` return a richer value than `(RunId, PathBuf)`, for example:
- - `CreatedRun { run_id, local_run_dir: Option, connection: ServerConnection }`
-
-Rationale:
-- `command::execute()` needs more than a run ID now
-- remote runs have no trustworthy local run dir
-- passing the resolved connection forward keeps the rest of the flow honest
-
-In `lib/crates/fabro-cli/src/server_client.rs`:
-- add a small helper that returns a `ServerStoreClient` from a resolved `ServerConnection`
-- reuse the existing resolved API-client path rather than introducing parallel target parsing
-
-### 3. Refactor `run` to start and attach through the resolved server connection
-In `lib/crates/fabro-cli/src/commands/run/start.rs`:
-- keep the current public/local helper for top-level `fabro start`
-- add a connection-agnostic helper that can start a run from an already-connected `ServerStoreClient`
-
-In `lib/crates/fabro-cli/src/commands/run/attach.rs`:
-- preserve the existing top-level `attach_run(...)` entrypoint for local-storage workflows
-- extract the existing server-backed attach logic into a helper that accepts:
- - `&ServerStoreClient`
- - `&RunId`
- - `Option<&Path>` for a local run dir
- - existing `kill_on_detach`, `styles`, and `json_output` flags
-- make the current top-level local path delegate to that extracted helper after doing its storage-dir/run-id inference
-
-In `lib/crates/fabro-cli/src/commands/run/command.rs`:
-- for `fabro run`, use the resolved connection returned by `create_run(...)`
-- if `--detach` is set:
- - print the run ID and exit exactly as today
-- otherwise:
- - start via the resolved server client
- - attach via the extracted direct-client attach helper
- - print the final run summary using the same resolved connection
-
-This keeps `fabro run` coherent for both:
-- local auto-started server flows
-- explicit/configured remote server flows
-
-### 4. Decouple final summary rendering from local run-dir assumptions
-In `lib/crates/fabro-cli/src/commands/run/output.rs`:
-- split summary fetching from summary rendering
-- make the renderer accept:
- - server-backed run state / conclusion / checkpoint
- - `Option<&Path>` for a local run dir
-
-Concrete behavior:
-- when `local_run_dir` is present:
- - keep printing the local run path
- - keep printing local artifact listings
-- when `local_run_dir` is absent:
- - do not print a local run path line
- - do not attempt local artifact discovery
- - still print the rest of the run conclusion and final output
-
-This is the smallest cleanup that makes remote foreground `run` feel intentional without broadening the whole remote lifecycle command surface.
-
-### 5. Keep standalone follow-up lifecycle commands local for now
-Do **not** add `--server` to these commands in this pass:
-- `fabro start`
-- `fabro attach`
-- `fabro wait`
-- `fabro logs`
-- `fabro inspect`
-- `fabro diff`
-- `fabro resume`
-- `fabro rewind`
-
-Rationale:
-- they form a larger remote lifecycle surface with selector semantics, replay UX, and local-path assumptions of their own
-- broadening them now would turn a cleanup pass into a larger capability expansion
-
-But the plan should call the temporary boundary out explicitly in docs/help text where useful:
-- `fabro create --server ...` is valid, but follow-up manipulation of that run outside `fabro run` remains a later pass
-
-### 6. Update docs and help text
-Update the user-facing references that describe server targeting:
-- `docs/reference/cli.mdx`
-- `docs/reference/user-configuration.mdx`
-- `docs/administration/deploy-server.mdx`
-
-The docs should explicitly say:
-- `fabro run` and `fabro create` now honor `--server` / `[server].target`
-- `fabro exec` still requires explicit `--server`
-- top-level run lifecycle follow-up commands are still local-storage commands in this pass
-
-## Test Plan
-
-### CLI help / parser surface
-Update snapshots in:
-- `lib/crates/fabro-cli/tests/it/cmd/run.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/create.rs`
-
-Scenarios:
-- `run --help` shows both `--storage-dir` and `--server`
-- `create --help` shows both `--storage-dir` and `--server`
-
-### `create` targeting behavior
-In `lib/crates/fabro-cli/tests/it/cmd/create.rs`:
-- `create --server ` submits to the explicit server and prints the created run ID
-- configured `[server].target` reroutes `create` when no explicit target args are passed
-- explicit `--storage-dir` suppresses configured `[server].target`
-- explicit `--server` overrides configured `[server].target`
-- remote-targeted `create` does not require local run-dir inspection to succeed
-
-### `run` targeting behavior
-In `lib/crates/fabro-cli/tests/it/cmd/run.rs`:
-- `run --server --detach ...` submits and prints a run ID without relying on a local run dir
-- foreground `run --server ...` creates, starts, attaches, and exits successfully
-- configured `[server].target` reroutes `run` when no explicit target args are passed
-- explicit `--storage-dir` suppresses configured `[server].target`
-- explicit `--server` overrides configured `[server].target`
-- remote foreground `run` prints a final summary without a local run-directory line
-- local `run --storage-dir ...` still prints the local run-directory line and local artifact section exactly as today
-
-### Test infrastructure
-Prefer a real TCP-bound fabro test server over `httpmock` for `run`.
-
-Reason:
-- `run` needs multiple real endpoints (`POST /runs`, `POST /runs/{id}/start`, event replay, run-state polling, question polling)
-- mocking all of that would verify request wiring but not the actual remote run lifecycle
-
-If the current CLI integration helpers do not already provide this, add a small reusable helper in:
-- `lib/crates/fabro-cli/tests/it/support.rs`
-or
-- `lib/crates/fabro-test/src/lib.rs`
-
-That helper should:
-- launch a real fabro server bound to loopback TCP
-- return a usable `http://127.0.0.1:PORT/api/v1` target string
-- keep fixture storage isolated from the invoking CLI’s local storage dir
-
-## Risks
-- The biggest risk is hidden local-run-dir assumptions in attach/summary code.
- - Mitigation: refactor those surfaces explicitly rather than trying to fake a local path for remote runs.
-- Config-target defaulting could surprise users if docs are not updated.
- - Mitigation: update CLI docs and help snapshots in the same pass.
-- Supporting `create --server` before the broader remote lifecycle commands is intentionally asymmetric.
- - Mitigation: call it out in the plan/docs instead of pretending the whole run lifecycle is remote-ready.
-
-## Follow-on
-After this lands, the next logical cleanup is a dedicated remote run-lifecycle plan for:
-- `start`
-- `attach`
-- `wait`
-- `logs`
-- `inspect`
-- `diff`
-- `resume`
-- `rewind`
-
-That should be a separate pass, not folded into this one.
diff --git a/docs/plans/2026-04-05-run-manifest-and-preflight-plan.md b/docs/plans/2026-04-05-run-manifest-and-preflight-plan.md
deleted file mode 100644
index 08ee2be92..000000000
--- a/docs/plans/2026-04-05-run-manifest-and-preflight-plan.md
+++ /dev/null
@@ -1,842 +0,0 @@
-# Run Manifest and Preflight
-
-## Summary
-
-Replace the current `POST /runs` request — which sends a filesystem path and relies on the server reading workflow definition files from disk — with a self-contained **run manifest**. The CLI gathers all workflow-definition inputs (DOT source, TOML configs, referenced prompt files, imported graphs, child workflows) into a single JSON payload. The server owns all interpretation: config merging, variable expansion, transforms, validation.
-
-This also introduces `POST /api/v1/preflight`, which accepts the same manifest and returns a structured health report without creating a run.
-
-After this change, the server no longer reads workflow/config/prompt/import files from the CLI's filesystem. It still uses the manifest `cwd` / resolved working directory for execution context (for example local sandbox and repo-aware behavior). The path-based `workflow_path` submission mode is removed.
-
-## Scope Boundaries
-
-In scope:
-- define the `RunManifest` schema in the OpenAPI spec
-- CLI-side manifest builder that walks the workflow tree and bundles all referenced files
-- file resolver abstraction for transforms (bundle-backed instead of disk-backed)
-- refactor `FileInliningTransform` and `ImportTransform` to use file resolver
-- server-side config resolution from manifest layers (args, workflow TOML, project TOML, user TOML)
-- child workflow resolution from the manifest's workflow map
-- replace `POST /api/v1/runs` request body with the manifest
-- new `POST /api/v1/preflight` endpoint using the same manifest
-- update `fabro run`, `fabro create`, `fabro preflight` to build and send manifests
-- demo mode for preflight and updated run creation
-
-Out of scope:
-- changes to run execution, checkpointing, or resume
-- changes to sandbox creation or the execution engine
-- changes to `fabro exec`
-- encrypted or compressed manifests
-- manifest size limits or streaming upload
-
-## Manifest Shape
-
-```json
-{
- "version": 1,
- "run_id": "01HV6D7S5YF4Z4B2M7K4N0Q6T9",
- "cwd": "/Users/user/p/my-project",
- "git": {
- "origin_url": "https://github.com/acme/my-app.git",
- "branch": "feature/foo",
- "sha": "abc123",
- "clean": true
- },
- "goal": {
- "type": "file",
- "path": "goal.md",
- "text": "Build and test the app..."
- },
- "args": {
- "model": "claude-opus-4-6",
- "sandbox": "local"
- },
- "target": {
- "identifier": "smoke",
- "path": "fabro/workflows/smoke/workflow.fabro"
- },
- "configs": [
- { "type": "project", "path": "fabro.toml", "source": "[fabro]\nroot = \"fabro/\"\n..." },
- { "type": "user", "path": "/Users/user/.fabro/user.toml", "source": "..." }
- ],
- "workflows": {
- "fabro/workflows/smoke/workflow.fabro": {
- "source": "digraph { ... }",
- "config": {
- "path": "fabro/workflows/smoke/workflow.toml",
- "source": "version = 1\n[vars]\nlanguage = \"rust\""
- },
- "files": {
- "prompts/review.md": {
- "content": "You are a code reviewer...",
- "ref": { "type": "file_inline", "original": "@prompts/review.md", "from": "workflow.fabro" }
- },
- "validate.fabro": {
- "content": "digraph { ... }",
- "ref": { "type": "import", "original": "./validate.fabro", "from": "workflow.fabro" }
- }
- }
- },
- "fabro/workflows/implement-plan/workflow.fabro": {
- "source": "digraph { ... }",
- "files": {
- "prompts/simplify.md": {
- "content": "...",
- "ref": { "type": "file_inline", "original": "@prompts/simplify.md", "from": "workflow.fabro" }
- }
- }
- }
- }
-}
-```
-
-Field semantics:
-- `version` — manifest schema version, currently `1`
-- `run_id` — optional pre-generated run ID. Used by detached/local create flows that allocate the run ID in the CLI before submission
-- `cwd` — the CLI's working directory at invocation time
-- `git` — optional, observable git state from the CLI's working directory. Omitted if not in a git repo
- - `origin_url` — remote origin URL, **sanitized** (credentials stripped from HTTPS URLs to prevent token leakage)
- - `branch` — current branch name
- - `sha` — current commit SHA
- - `clean` — whether the working tree has uncommitted changes
-- `goal` — resolved goal with provenance, always includes `text` (the content) and `type` (`"value"` for literal string, `"file"` for file-sourced, `"graph"` for graph-attribute-sourced). When `type` is `"file"`, includes `path` (original file path from TOML or CLI `--goal-file`). The server uses `text` directly and clears any merged `goal_file` path
-- `args` — command-local run/preflight args that affect run settings. Sparse: omitted flags are absent. This is not a generic env layer or a dump of global CLI flags
-- `target.identifier` — what the user typed (slug like `"smoke"` or path like `"./custom.fabro"`)
-- `target.path` — resolved path, keys into the `workflows` map
-- `configs` — non-workflow config sources, each with `type` (`"project"` or `"user"`), `path`, and raw TOML `source`
-- `workflows` — flat map of all workflows (root + children), keyed by resolved path
- - `source` — raw DOT source (unexpanded, pre-transform)
- - `config` — optional, the workflow's TOML config with `path` and `source`
- - `files` — map of normalized logical path (relative to that workflow's root directory) to file entry, each with `content` (file content) and `ref` (discovery metadata: `type`, `original` reference string, and optional `from` logical path for nested imports). Types: `file_inline` (`@file`), `import`, `dockerfile`. Note: `goal_file` no longer appears here — goals are in the top-level `goal` object
-
-## Key Decisions
-
-- **CLI gathers, server transforms.** The CLI's only job is reading files from disk and bundling them. All interpretation — TOML parsing, config merging, variable expansion, graph transforms, validation — happens server-side.
-- **Detached/create flows keep CLI-allocated run IDs.** The manifest carries an optional `run_id`, preserving the current `run -d` / `create` behavior where the CLI can pre-generate the run ID before submission.
-- **Flat workflow map.** All workflows (root and children, at any nesting depth) are in a single flat `workflows` map. Relationships are implicit via `stack.child_workflow` attributes in the DOT source. This avoids deep nesting and naturally deduplicates shared children.
-- **Inline child workflows stay inline.** `stack.child_dot_source` continues to work exactly as it does today and does not need manifest bundling. Manifest child-workflow support is specifically for `stack.child_workflow` / `stack.child_dotfile`.
-- **Child workflows don't have their own settings.** Today `parse_child_graph()` passes `Settings::default()` to children and never loads their TOML. The manifest preserves this — child workflow entries carry their DOT source and files but no separate config layers. If a child has a `workflow.toml`, it can optionally be included in `config` for future use, but the server does not merge it today.
-- **Config resolution moves to the server.** The CLI currently merges `cli_args.combine(workflow_config).combine(project_config).combine(user_config).resolve()`. The manifest ships the raw layers and the server performs the merge. Merge precedence is determined by the server based on config `type`, not by array order.
-- **Server merge precedence:** `args` > workflow `config` > `project` config > `user` config > server defaults. There is no separate manifest `env` layer. Server-owned operational settings such as `storage_dir`, `[server]`, `api`, `web`, `features`, `log`, and `exec` are ignored from manifest configs; the active server instance owns those.
-- **File resolution must stay contextual.** Transforms currently resolve relative paths based on the current graph/file location. The manifest refactor cannot collapse that to `resolve("foo.md") -> content`; the resolver must accept the current logical directory so nested imports like `subflow/imported.fabro -> @prompts/foo.md` still resolve correctly.
-- **Goal is resolved by the CLI and travels as a top-level object.** The CLI resolves the final goal using the current precedence rules (`--goal` / `--goal-file` over merged config `goal` / `goal_file`, otherwise graph-level `goal`) and sends it as `manifest.goal`. The server applies `manifest.goal.text` after config merge and clears `goal_file`, so goal handling never requires filesystem reads server-side.
-- **Git state travels in the manifest.** The CLI captures origin URL (sanitized — credentials stripped from HTTPS URLs), current branch, commit SHA, and clean/dirty status. This replaces the server's need to run git commands or access the repo filesystem. Credential sanitization is mandatory to prevent token leakage in HTTPS URLs with embedded PATs or installation tokens.
-- **`workflow_path` mode is removed.** After migration, the server only accepts manifests. The `dot_source` / `workflow_path` fields in `CreateRunRequest` are replaced by the manifest.
-- **Preflight uses the same manifest.** `POST /api/v1/preflight` accepts a `RunManifest` and returns a `PreflightResponse` with workflow diagnostics plus the rendered checks payload. No validated manifest round-trip.
-- **Manifest discovery walks the DOT AST.** The CLI must parse the DOT source enough to find `@file` references (in `prompt` and `goal` attributes), `import` attributes, and `stack.child_workflow` / `stack.child_dotfile` attributes. It does NOT run the full transform pipeline — just scans for file references.
-
-## Implementation Changes
-
-### 1. File resolver abstraction
-
-Create `lib/crates/fabro-workflow/src/file_resolver.rs`.
-
-```rust
-pub trait FileResolver: Send + Sync {
- /// Resolve a logical reference string relative to the current logical directory.
- /// Returns the normalized logical path plus file content.
- fn resolve(&self, current_dir: &Path, reference: &str) -> Option;
-}
-
-pub struct ResolvedFile {
- pub logical_path: PathBuf,
- pub content: String,
-}
-```
-
-One implementation:
-
-**`BundleFileResolver`** — reads from a manifest's files map:
-```rust
-pub struct BundleFileResolver {
- files: HashMap,
-}
-```
-The resolver normalizes `current_dir.join(reference)` into a workflow-relative logical path (strip leading `./`, collapse `.` / `..`) and looks up that normalized key. This preserves the current import/file-inlining semantics without any filesystem access. The `files` map is built from the manifest's `ManifestFileEntry` objects (extracting `content` by normalized logical path key).
-
-No `DiskFileResolver` is needed — this is a hard cutover. The existing filesystem-based resolution logic in the transforms is replaced entirely.
-
-Add `pub mod file_resolver;` to `lib/crates/fabro-workflow/src/lib.rs`.
-
-Tests:
-- `BundleFileResolver` with test data, verify exact key lookup works
-- Verify `None` for missing files
-- Verify path normalization handles `./` prefix stripping and nested `..`
-- Verify nested import scoping resolves relative to the imported file's logical directory
-
-### 2. Refactor FileInliningTransform
-
-In `lib/crates/fabro-workflow/src/transforms/file_inlining.rs`:
-
-Change the struct to hold a resolver instead of paths:
-```rust
-pub struct FileInliningTransform {
- resolver: Arc,
-}
-
-impl FileInliningTransform {
- pub fn new(resolver: Arc) -> Self {
- Self { resolver }
- }
-}
-```
-
-Update `resolve_file_ref` to use the resolver:
-- strip the `@` prefix to get the relative path
-- call `self.resolver.resolve(current_dir, path_str)` instead of `std::fs::read_to_string`
-- thread the current logical directory through the transform so imported files can inline their own relative references correctly
-- remove tilde expansion and `canonicalize` logic (the CLI resolved all paths during bundling)
-
-The `apply()` method stays structurally the same — it iterates node prompts and graph goal, calling the updated resolution logic.
-
-### 3. Refactor ImportTransform
-
-In `lib/crates/fabro-workflow/src/transforms/import.rs`:
-
-Same pattern — hold a resolver:
-```rust
-pub struct ImportTransform {
- resolver: Arc,
-}
-```
-
-Update `resolve_import_path` and `prepare_import`:
-- `resolve_import_path` uses `self.resolver.resolve(current_dir, path_str)` instead of filesystem canonicalize
-- `prepare_import` gets the file content from the resolver instead of `std::fs::read_to_string`
-- when applying `FileInliningTransform` to imported content, pass the same resolver plus the imported file's logical parent directory
-
-The recursive import expansion and circular import detection stay the same.
-
-### 4. Update transform pipeline
-
-In `lib/crates/fabro-workflow/src/pipeline/transform.rs`:
-
-Change `TransformOptions` to carry a resolver:
-```rust
-pub struct TransformOptions {
- pub file_resolver: Option>,
- pub custom_transforms: Vec>,
-}
-```
-
-Update the `transform` function:
-- where it currently checks `options.base_dir.is_some()` to gate `ImportTransform` and `FileInliningTransform`, check `options.file_resolver.is_some()` instead
-- construct the transforms with the resolver
-
-### 5. Manifest schema in OpenAPI
-
-In `docs/api-reference/fabro-api.yaml`, add schemas:
-
-```yaml
-RunManifest:
- description: Self-contained workflow run manifest.
- type: object
- required:
- - version
- - cwd
- - target
- - workflows
- properties:
- version:
- type: integer
- description: Manifest schema version.
- example: 1
- run_id:
- type: string
- nullable: true
- description: Optional pre-generated run ID to use instead of allocating a new ULID.
- example: "01HV6D7S5YF4Z4B2M7K4N0Q6T9"
- cwd:
- type: string
- description: CLI working directory at invocation time.
- git:
- $ref: "#/components/schemas/ManifestGit"
- goal:
- $ref: "#/components/schemas/ManifestGoal"
- args:
- $ref: "#/components/schemas/ManifestArgs"
- target:
- $ref: "#/components/schemas/ManifestTarget"
- configs:
- type: array
- items:
- $ref: "#/components/schemas/ManifestConfig"
- workflows:
- type: object
- additionalProperties:
- $ref: "#/components/schemas/ManifestWorkflow"
-
-ManifestGit:
- description: Observable git state from the CLI working directory.
- type: object
- required:
- - origin_url
- - branch
- - sha
- - clean
- properties:
- origin_url:
- type: string
- description: >
- Remote origin URL, sanitized (credentials stripped from HTTPS URLs).
- e.g. https://user:token@github.com/acme/app.git becomes https://github.com/acme/app.git
- example: "https://github.com/acme/my-app.git"
- branch:
- type: string
- description: Current branch name.
- example: feature/foo
- sha:
- type: string
- description: Current commit SHA.
- example: abc123def
- clean:
- type: boolean
- description: Whether the working tree has uncommitted changes.
-
-ManifestGoal:
- description: Resolved goal with provenance.
- type: object
- required:
- - type
- - text
- properties:
- type:
- type: string
- enum:
- - value
- - file
- - graph
- description: >
- How the goal was sourced: "value" (literal from TOML goal field or --goal flag),
- "file" (resolved from goal_file), "graph" (from graph-level goal attribute in DOT).
- text:
- type: string
- description: The resolved goal content. Server uses this directly.
- path:
- type: string
- description: Original file path (only present when type is "file").
-
-ManifestTarget:
- type: object
- required:
- - identifier
- - path
- properties:
- identifier:
- type: string
- description: What the user typed (slug or path).
- example: smoke
- path:
- type: string
- description: Resolved path, keys into the workflows map.
- example: fabro/workflows/smoke/workflow.fabro
-
-ManifestConfig:
- type: object
- required:
- - type
- properties:
- type:
- type: string
- enum:
- - project
- - user
- path:
- type: string
- description: Filesystem path to the config file.
- source:
- type: string
- description: Raw TOML source of the config file.
-
-ManifestWorkflowConfig:
- type: object
- required:
- - path
- - source
- properties:
- path:
- type: string
- description: Path to the workflow TOML file.
- source:
- type: string
- description: Raw TOML source.
-
-ManifestArgs:
- description: Command-local run/preflight flags that affect run settings. All fields optional (sparse).
- type: object
- properties:
- model:
- type: string
- provider:
- type: string
- sandbox:
- type: string
- verbose:
- type: boolean
- dry_run:
- type: boolean
- auto_approve:
- type: boolean
- no_retro:
- type: boolean
- preserve_sandbox:
- type: boolean
- label:
- type: array
- items:
- type: string
-
-ManifestFileEntry:
- description: A bundled file with discovery metadata.
- type: object
- required:
- - content
- - ref
- properties:
- content:
- type: string
- description: File content.
- ref:
- $ref: "#/components/schemas/ManifestFileRef"
-
-ManifestFileRef:
- description: How this file was discovered.
- type: object
- required:
- - type
- - original
- properties:
- type:
- type: string
- enum:
- - file_inline
- - import
- - dockerfile
- description: Discovery type.
- original:
- type: string
- description: The reference string as it appeared in the DOT/TOML.
- example: "@prompts/review.md"
- from:
- type: string
- description: Optional logical path of the file/graph that referenced this entry.
-
-ManifestWorkflow:
- type: object
- required:
- - source
- properties:
- source:
- type: string
- description: Raw DOT source (unexpanded, pre-transform).
- config:
- $ref: "#/components/schemas/ManifestWorkflowConfig"
- files:
- type: object
- additionalProperties:
- $ref: "#/components/schemas/ManifestFileEntry"
- description: >
- Map of normalized logical path to file entry with content and discovery metadata.
-```
-
-Replace the `CreateRunRequest` schema with `RunManifest` on `POST /api/v1/runs`.
-
-Add `POST /api/v1/preflight`:
-```yaml
-/api/v1/preflight:
- post:
- operationId: runPreflight
- tags: [Runs]
- summary: Validate a workflow manifest without creating a run.
- description: >
- Accepts the same manifest as POST /runs. Validates the workflow,
- checks sandbox availability, LLM provider access, and GitHub token
- minting. Returns a structured pass/fail report.
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/RunManifest"
- responses:
- "200":
- description: Preflight report.
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/PreflightResponse"
-```
-
-The preflight response should preserve the current CLI JSON contract:
-- `workflow` summary/diagnostics from validation
-- `checks` as the rendered report payload
-
-So add:
-```yaml
-PreflightResponse:
- type: object
- required:
- - workflow
- - checks
- properties:
- workflow:
- $ref: "#/components/schemas/PreflightWorkflowSummary"
- checks:
- $ref: "#/components/schemas/DiagnosticsReport"
-```
-
-Rebuild `fabro-api`:
-```
-cargo build -p fabro-api
-```
-
-### 6. Server-side config resolution from manifest
-
-Create `lib/crates/fabro-server/src/manifest.rs`.
-
-This module:
-
-1. **Parses run-relevant config layers from the manifest:**
- - `args` → converted to a `ConfigLayer` (map CLI arg names to `ConfigLayer` fields, similar to `TryFrom<&RunArgs>` in `overrides.rs`)
- - workflow `config.source` → parsed as TOML via `fabro_config` and converted to `ConfigLayer`
- - each `configs[]` entry → parsed as TOML and converted to `ConfigLayer`
- - strip or ignore non-run fields from uploaded configs (`storage_dir`, `[server]`, `api`, `web`, `features`, `log`, `exec`, `max_concurrent_runs`)
-
-2. **Merges in server-determined precedence:**
- ```rust
- pub fn resolve_settings(manifest: &RunManifest, server_defaults: &Settings) -> Result {
- let args_layer = parse_args_layer(&manifest.args)?;
- let workflow_layer = parse_workflow_config(manifest)?;
- let project_layer = find_config_layer(manifest, "project")?;
- let user_layer = find_config_layer(manifest, "user")?;
-
- args_layer
- .combine(workflow_layer)
- .combine(project_layer)
- .combine(user_layer)
- .resolve()
- }
- ```
-
-3. **Applies the top-level goal after merge.**
- - if `manifest.goal` is present, set `settings.goal = Some(manifest.goal.text.clone())`
- - clear `settings.goal_file` so server-side goal handling never tries to read the filesystem
-
-4. **Builds a `BundleFileResolver`** from the target workflow's `files` map.
-
-5. **Constructs a `CreateRunInput`** with:
- - `WorkflowInput::DotSource { source, base_dir: None }` — using the raw DOT from the manifest
- - resolved `Settings`
- - `cwd` from the manifest
- - a `file_resolver` for the transform pipeline
-
-The `parse_args_layer` function maps manifest `args` keys to `ConfigLayer` fields. The mapping mirrors the current `TryFrom<&RunArgs>` / `TryFrom<&PreflightArgs>` logic in `overrides.rs`, but without `goal` / `goal_file` because those are represented by the top-level `goal` object. The keys are the same field names: `model`, `provider`, `sandbox`, `verbose`, `dry_run`, `auto_approve`, `no_retro`, `preserve_sandbox`, `label`.
-
-### 7. Update POST /runs handler
-
-In `lib/crates/fabro-server/src/server.rs`:
-
-Replace the current `create_run` handler. The new handler:
-
-1. Deserializes the request body as `RunManifest`.
-2. Validates manifest version is supported.
-3. Calls `manifest::resolve_settings(&manifest, &state.settings)` to merge configs.
-4. Looks up the root workflow in `manifest.workflows` using `manifest.target.path`.
-5. Builds a `BundleFileResolver` from the root workflow's `files` map.
-6. Parses `manifest.run_id` when present, preserving the current detached/local create behavior.
-7. Constructs `CreateRunInput`:
- ```rust
- CreateRunInput {
- workflow: WorkflowInput::DotSource {
- source: root_workflow.source.clone(),
- base_dir: None,
- },
- settings,
- cwd: PathBuf::from(&manifest.cwd),
- workflow_slug: Some(manifest.target.identifier.clone()),
- run_id: Some(run_id),
- host_repo_path: None,
- base_branch: None,
- }
- ```
-8. Passes the manifest's workflow map to `operations::create()` so child workflows can be resolved later.
-
-The `operations::create()` and `validate()` paths in `fabro-workflow` need to accept the file resolver (via `TransformOptions`) and the workflow map (for child resolution). This requires updating `CreateRunInput`, `ValidateInput`, or shared workflow-resolution state:
-
-```rust
-pub struct CreateRunInput {
- pub workflow: WorkflowInput,
- pub settings: Settings,
- pub cwd: PathBuf,
- pub workflow_slug: Option,
- pub run_id: Option,
- pub host_repo_path: Option,
- pub base_branch: Option,
- pub file_resolver: Option>,
- pub workflow_bundle: Option>,
-}
-```
-
-In `operations::create()` (`create.rs`) and `validate()` (`validate.rs`), when `file_resolver` is `Some`, use it in `TransformOptions` instead of relying on `base_dir`.
-
-### 8. Child workflow resolution from manifest
-
-In `lib/crates/fabro-workflow/src/handler/manager_loop.rs`:
-
-`parse_child_graph()` currently resolves `stack.child_workflow` as `WorkflowInput::Path` and reads from disk. Update it to check for a workflow bundle first:
-
-```rust
-fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<...> {
- // ... existing stack.child_dot_source handling ...
-
- if let Some(path) = node.attr("stack.child_workflow").or(node.attr("stack.child_dotfile")) {
- let bundle = services.workflow_bundle.as_ref()
- .ok_or_else(|| anyhow!("no workflow bundle available"))?;
- let child = bundle.get(path)
- .ok_or_else(|| anyhow!("child workflow not found in manifest: {path}"))?;
- let resolver = BundleFileResolver::new(child.files.clone());
- // Pass resolver plus the child's logical root to validate()
- Ok(WorkflowInput::DotSource {
- source: child.source.clone(),
- base_dir: None,
- })
- }
-}
-```
-
-Add `workflow_bundle: Option>>` to `EngineServices` so it is accessible during execution.
-
-When the child workflow is resolved from the bundle, its own `files` map provides a scoped `BundleFileResolver` for that child's transforms (`@file` refs, imports within the child).
-
-### 9. CLI manifest builder
-
-Create `lib/crates/fabro-cli/src/manifest_builder.rs`.
-
-This module builds a `RunManifest` from CLI inputs:
-
-```rust
-pub struct ManifestBuilder;
-
-impl ManifestBuilder {
- pub fn build_for_run(cwd: PathBuf, args: &RunArgs) -> Result { ... }
- pub fn build_for_preflight(cwd: PathBuf, args: &PreflightArgs) -> Result { ... }
-}
-```
-
-The build process:
-
-1. **Resolve workflow path**: call `project_config::resolve_workflow_path(&args.workflow, &cwd)` to get the `.fabro` file path and optional `.toml` config path.
-
-2. **Read the root workflow**:
- - read the `.fabro` file: `std::fs::read_to_string(&dot_path)`
- - if a `.toml` exists, read it: `std::fs::read_to_string(&toml_path)`
-
-3. **Discover file references in the DOT source**:
- - parse the DOT source with `parser::parse(&source)`
- - scan all nodes for `prompt` attributes starting with `@` → collect file paths
- - scan graph-level `goal` attribute for `@` prefix → collect file path
- - scan all nodes for `import` attributes → collect file paths
- - scan all nodes for `stack.child_workflow` / `stack.child_dotfile` attributes → collect child workflow paths
-
-4. **Resolve the final goal**:
- - compute the final goal using the current precedence rules (`--goal` / `--goal-file` over merged config `goal` / `goal_file`, otherwise graph-level `goal`)
- - store it in top-level `manifest.goal`
- - do **not** add `goal_file` to the workflow `files` map
-
-5. **Resolve file references from the TOML config**:
- - if the TOML has `sandbox.daytona.snapshot.dockerfile.path`, read the Dockerfile and add to `files`
-
-6. **Read all discovered files** into the `files` map, keyed by normalized logical path relative to the workflow root. Resolve relative to the `.fabro` file's parent directory, with `~/.fabro` as fallback (matching current `resolve_file_ref` logic).
-
-7. **Recursively process child workflows** (step 3-6 for each child). Children go into the flat `workflows` map. Detect circular references via a visited set.
-
-8. **Process imported `.fabro` files**: imports also go into the workflow's `files` map (they are read and their content is stored under workflow-relative logical paths). Imported files may themselves contain `@file` refs and nested imports — the builder must recursively discover these too.
-
-9. **Gather configs**:
- - read `fabro.toml` via `project_config::discover_project_config()`
- - read `~/.fabro/user.toml` via the user config path
- - for each, record `type`, `path`, and raw `source`
-
-10. **Gather args**: serialize the command-local args that affect run settings. Use the same field names as `ConfigLayer` (`model`, `provider`, `sandbox`, etc.) but exclude `goal` / `goal_file` because those are represented by top-level `manifest.goal`. Only include fields that the user actually set (sparse).
-
-11. **Carry the optional run ID** from `RunArgs.run_id` when present.
-
-12. **Assemble and return** the `RunManifest`.
-
-The DOT parser is already available in `fabro-workflow`. The CLI already depends on `fabro-workflow` (it calls `validate()`). The manifest builder reuses the parser for discovery but does NOT run transforms.
-
-### 10. Update CLI commands
-
-In `lib/crates/fabro-cli/src/commands/run/create.rs`:
-
-Replace the current flow:
-```rust
-// Before (sends path + pre-resolved settings):
-let settings = cli_args_config.combine(workflow_config).combine(cli_defaults).resolve()?;
-client.create_run_from_workflow_path(workflow_path, &cwd, &settings, run_id)
-
-// After (sends manifest):
-let manifest = ManifestBuilder::build_for_run(cwd, &args)?;
-client.create_run_from_manifest(&manifest)
-```
-
-Remove `create_run_from_workflow_path` from `server_client.rs`. Add `create_run_from_manifest` that POSTs the manifest JSON.
-
-The optional local validation step (lines 39-51) can be removed — the server validates as part of run creation. Or it can stay as a fast-fail with a note that it won't catch everything the server checks.
-
-In `lib/crates/fabro-cli/src/commands/run/overrides.rs`:
-
-The `TryFrom<&RunArgs> for ConfigLayer` conversion is no longer needed for the settings merge (the server does it). But the args serialization for the manifest's `args` field needs similar logic. Consider:
-- keeping the conversion as a helper for building the manifest's `args` object
-- or writing a new `RunArgs::to_manifest_args()` method that produces a JSON map
-
-In `lib/crates/fabro-cli/src/commands/preflight.rs`:
-
-Replace the current flow:
-```rust
-// Before (runs all checks CLI-side):
-let settings = cli_args_config.combine(workflow_config).combine(cli_defaults).resolve()?;
-validate(ValidateInput { ... })?;
-run_preflight(&settings, ...)?;
-
-// After (sends manifest to server):
-let manifest = ManifestBuilder::build_for_preflight(cwd, &args)?;
-let cli_settings = load_user_settings_with_storage_dir(args.storage_dir.as_deref())?;
-let client = server_client::connect_server(&cli_settings.storage_dir()).await?;
-let response = client.run_preflight().body(manifest).send().await?;
-render_report(&response.checks);
-```
-
-Remove all local preflight check functions. The CLI becomes a thin client that builds the manifest, sends it, and renders the response.
-
-### 11. Preflight handler on server
-
-In `lib/crates/fabro-server/src/server.rs`:
-
-```rust
-async fn run_preflight(
- _auth: AuthenticatedService,
- State(state): State>,
- Json(manifest): Json,
-) -> Response {
- let report = preflight::run_preflight(&state, &manifest).await;
- (StatusCode::OK, Json(report)).into_response()
-}
-```
-
-Create `lib/crates/fabro-server/src/preflight.rs`.
-
-This module adapts the checks from the current CLI-side `preflight.rs`:
-
-1. **Resolve settings** from manifest via `manifest::resolve_settings()`.
-2. **Validate the workflow** — parse, transform (using `BundleFileResolver`), validate.
-3. **Check sandbox** — resolve sandbox provider from settings, attempt to create/initialize a test sandbox.
-4. **Check LLM providers** — for each model used by the graph, verify the provider is configured (secret exists in secret store) and reachable.
-5. **Check GitHub token** — if the workflow has `github.permissions`, attempt to mint a test installation access token.
-
-Each check produces a `CheckResult`. The function returns a `PreflightResponse` with:
-- `workflow` summary (`name`, node/edge counts, goal, diagnostics)
-- `checks` as the `DiagnosticsReport` payload
-
-Add route in `real_routes()`:
-```rust
-.route("/preflight", post(run_preflight))
-```
-
-### 12. Demo mode
-
-In `lib/crates/fabro-server/src/demo/mod.rs`:
-
-**Run creation demo**: The demo handler already exists for `POST /runs`. Update it to accept the manifest schema. The demo can ignore the manifest contents and return a canned run response as it does today.
-
-**Preflight demo**: Return an all-passing preflight report:
-```rust
-pub(crate) async fn run_preflight(
- _auth: AuthenticatedService,
- State(_state): State>,
- Json(_manifest): Json,
-) -> Response {
- (StatusCode::OK, Json(serde_json::json!({
- "workflow": {
- "name": "demo",
- "nodes": 3,
- "edges": 2,
- "goal": "Demo",
- "diagnostics": []
- },
- "checks": {
- "version": fabro_util::version::FABRO_VERSION,
- "sections": [
- {
- "title": "Workflow",
- "checks": [
- { "name": "Parse & Validate", "status": "pass", "summary": "3 nodes, 2 edges, goal set", "details": [] },
- ]
- },
- {
- "title": "Sandbox",
- "checks": [
- { "name": "Provider", "status": "pass", "summary": "local sandbox available", "details": [] },
- ]
- },
- {
- "title": "LLM",
- "checks": [
- { "name": "Providers", "status": "pass", "summary": "Anthropic, OpenAI reachable", "details": [] },
- ]
- },
- ]
- }
- }))).into_response()
-}
-```
-
-Wire in `demo_routes()`:
-```rust
-.route("/preflight", post(demo::run_preflight))
-```
-
-### 13. Cleanup
-
-After the manifest is working:
-
-- **Remove `workflow_path` mode** from the `POST /runs` handler. Remove the `workflow_path`, `cwd`, `settings_json` fields from the request schema. Remove `CreateRunRequest` from the OpenAPI spec and replace with `RunManifest`.
-- **Keep `WorkflowInput::Path` for local-only CLI commands.** Do not remove it from `source.rs`; commands like `validate` and `graph` still use local path resolution. The cleanup is server-specific: remove the server's path-based submission path, not the workflow crate's local path input abstraction.
-- **No `DiskFileResolver` to remove** — it was never created (hard cutover).
-- **Remove `create_run_from_workflow_path`** from `server_client.rs`.
-- **Remove `ConfigLayer::for_workflow()`** usage from CLI run/preflight commands (the server does config resolution now). The function itself may still be useful for other CLI code paths.
-- **Remove CLI-side preflight check functions** from `preflight.rs`.
-- **Remove `TryFrom<&RunArgs> for ConfigLayer`** if replaced by manifest args serialization.
-
-## Implementation Order
-
-```
- 1 File resolver trait + BundleFileResolver (no deps)
- 2 Refactor FileInliningTransform to use resolver (depends on 1)
- 3 Refactor ImportTransform to use resolver (depends on 1)
- 4 Update transform pipeline (TransformOptions) (depends on 2, 3)
- 5 Manifest schema in OpenAPI + rebuild fabro-api (no deps, parallel with 1-4)
- 6 Server-side config resolution (manifest.rs) (depends on 5)
- 7 CLI manifest builder (depends on 5)
- 8 Update POST /runs handler to accept manifest (depends on 4, 6)
- 9 Child workflow resolution from manifest (depends on 8)
-10 Update CLI run/create to send manifest (depends on 7, 8)
-11 Preflight server handler (depends on 4, 6)
-12 Update CLI preflight to send manifest (depends on 7, 11)
-13 Demo mode (depends on 5)
-14 Cleanup: remove workflow_path mode + dead code (depends on 10, 12)
-```
-
-Steps 1-4 (resolver refactor) and 5 (schema) can proceed in parallel. Step 7 (CLI builder) and 6 (server config) can proceed in parallel once the schema exists.
-
-## Resolved Questions
-
-1. **`args` field schema**: **Typed and limited to run settings.** The OpenAPI schema defines explicit fields matching the command-local run/preflight overrides (model, provider, sandbox, verbose, dry_run, auto_approve, no_retro, preserve_sandbox, label). `goal` / `goal_file` are excluded because the final goal is represented by top-level `manifest.goal`. All fields are optional (sparse — only set fields are present).
-
-2. **Import path scoping**: **Workflow-relative logical paths plus contextual resolution.** All file paths in a workflow's `files` map are normalized logical paths relative to that workflow's root directory. Each file entry carries `ref` metadata with `type`, `original`, and optional `from`. The server resolves nested imports and `@file` references by passing the current logical directory into the resolver; it does not use metadata fields for lookup.
-
-3. **Backward compatibility**: **Hard cutover.** The old `CreateRunRequest` (workflow_path/dot_source) is removed when the manifest lands. CLI and local server are the same binary, so they upgrade together. Remote servers need coordinated upgrade.
-
-4. **DOT parser for discovery**: **Full parse.** The CLI uses the existing `fabro-workflow` parser (already a dependency). It's fast, handles all edge cases (quoted strings, comments, escapes), and is more reliable than regex scanning.
-
-5. **No manifest `env` layer**: the current CLI does not have a separate run-settings env layer like `FABRO_MODEL` or `FABRO_PROVIDER`. Manifest config precedence is `args` > workflow config > project config > user config > server defaults, with server-owned operational settings stripped from uploaded configs.
diff --git a/docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md b/docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md
deleted file mode 100644
index c68f072bd..000000000
--- a/docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md
+++ /dev/null
@@ -1,984 +0,0 @@
-# Server-Canonical Secrets, Doctor, and Repo Init
-
-## Summary
-
-Migrate five CLI command families from local-only to server-canonical:
-
-- **secrets** — move from `~/.fabro/.env` to server-owned JSON store with write-only API
-- **provider login** — keep validation in CLI, save credentials via server API
-- **repo init** — call server to verify repo access after scaffolding
-- **doctor** — replace local probing with a single server diagnostics endpoint
-- **health** — add server version to `GET /health` for CLI/server parity checks
-
-After this pass, the CLI has no direct file I/O for secrets and no direct probing of external services for health checks. The server is the single owner of credentials and the single source of diagnostic truth.
-
-This plan deliberately excludes the run manifest (server-canonical `POST /runs` body). That is a separate, larger effort.
-
-## Scope Boundaries
-
-In scope:
-- add `version` to `GET /health`
-- server-side secret store (JSON file, in-memory cache, store-backed secret accessors)
-- `PUT /api/v1/secrets/{name}`, `DELETE /api/v1/secrets/{name}`, `GET /api/v1/secrets`
-- rewrite `fabro secret set`, `fabro secret list`, `fabro secret rm` as API clients
-- remove `fabro secret get` (secrets are write-only)
-- rewrite `fabro provider login` to save credentials via the server
-- update `fabro install` to save GitHub App secrets via the local server and print restart guidance when needed
-- `GET /api/v1/repos/github/{owner}/{name}` for repo access checks
-- update `fabro repo init` to call repo endpoint
-- `POST /api/v1/health/diagnostics` with server-side health probing
-- rewrite `fabro doctor` as API client + version parity check + retained local config warning
-- demo mode handlers for all new endpoints
-- add shared `--server ` support for these server-canonical CLI commands, where `` is either an HTTP(S) base URL or an absolute Unix socket path
-
-Out of scope:
-- run manifest / workflow packaging
-- changes to `fabro exec` credential handling (`OPENAI_API_KEY=secret fabro exec ...` is the intended path)
-- remote server auth (mTLS, JWT) — endpoints follow existing auth patterns
-- encrypted-at-rest secret storage — JSON file with filesystem permissions is sufficient for now
-- openssl system dependency check (being removed soon)
-- broader CLI target cleanup outside the command families touched by this plan
-
-## Key Decisions
-
-- Secrets are **write-only**. No endpoint exposes secret values after they are stored. `GET /api/v1/secrets` returns names and timestamps only. `fabro secret get` is removed.
-- Secret storage is a JSON file at `/secrets.json` under the active server data dir.
-- The server does **not** mutate process env vars on secret writes. Server-side secret consumers read through a shared store-backed adapter so updated secrets take effect immediately for request-time flows.
-- Startup-time components that only initialize once at server boot are allowed to require restart after credential changes. `fabro install` should print that restart requirement when it detects the server was already running.
-- `GET /health` gains a `version` field. The CLI checks version parity before rendering diagnostics.
-- `POST /api/v1/health/diagnostics` (not GET) because it triggers expensive external probes (LLM providers, GitHub, sandbox). The response reuses the shape of the existing `CheckReport` struct.
-- `GET /api/v1/repos/github/{owner}/{name}` is intentionally GitHub-specific in the URL. Another segment can be added for other providers later.
-- `provider login` keeps its interactive prompting and OAuth flow on the CLI side. After obtaining credentials, it saves them via `PUT /api/v1/secrets/{name}`.
-- `doctor` keeps one local CLI check for user config files and legacy `.env` warning, then requires a connected server for everything else. There is no fast/offline mode.
-- `dot` system dependency check moves server-side. `openssl` check is dropped. `node` check is dropped (build-time dependency only).
-- The `--show-values` flag on `fabro secret list` is removed as a consequence of the write-only secret model.
-- `PUT /api/v1/secrets/{name}` accepts any env-var-like key name and rejects invalid names with `400`.
-- These server-canonical CLI commands use one explicit override flag, `--server `, where `` is either an HTTP(S) URL or an absolute Unix socket path. When omitted, they connect to the local server for the active storage dir, starting it if necessary.
-- `[server].base_url` is replaced by `[server].target`, using the same string syntax as `--server`.
-- `fabro install` is local-only. It never targets a remote server.
-- All new endpoints have demo mode handlers.
-
-## Implementation Changes
-
-### 1. Add version to `GET /health`
-
-In `docs/api-reference/fabro-api.yaml`:
-- add `version` field to `HealthResponse` schema:
- ```yaml
- HealthResponse:
- description: Service health check response.
- type: object
- required:
- - status
- - version
- properties:
- status:
- type: string
- description: Health status indicator.
- example: ok
- version:
- type: string
- description: Server version string.
- example: "0.176.2"
- ```
-
-In `lib/crates/fabro-server/src/server.rs`:
-- update the `health` handler to include the version:
- ```rust
- async fn health() -> Response {
- Json(serde_json::json!({
- "status": "ok",
- "version": fabro_util::version::FABRO_VERSION,
- }))
- .into_response()
- }
- ```
-
-Rebuild `fabro-api` to pick up the schema change:
-```
-cargo build -p fabro-api
-```
-
-Add a test in `server.rs` inline tests:
-- send `GET /health`, assert status 200, assert `version` field is a non-empty string, assert `status` is `"ok"`.
-
-### 2. Server-side secret store
-
-Create `lib/crates/fabro-server/src/secret_store.rs`.
-
-This module owns a JSON file and an in-memory cache:
-
-```rust
-pub struct SecretEntry {
- pub value: String,
- pub created_at: String, // ISO 8601
- pub updated_at: String, // ISO 8601
-}
-
-pub struct SecretMetadata {
- pub name: String,
- pub created_at: String,
- pub updated_at: String,
-}
-
-pub struct SecretStore {
- path: PathBuf,
- entries: HashMap,
-}
-```
-
-Public API:
-- `SecretStore::load(path: PathBuf) -> Result` — reads JSON file (or creates empty if missing), parses into `entries`.
-- `store.set(name: &str, value: &str) -> Result` — validates the key name, upserts entry with current timestamp, writes atomically (write to temp file, rename to `secrets.json`), returns metadata.
-- `store.remove(name: &str) -> Result<()>` — validates the key name, removes entry (error if not found), writes atomically (write to temp file, rename).
-- `store.list() -> Vec` — returns names + timestamps, sorted by name. No values.
-- `store.get(name: &str) -> Option<&str>` — reads a single secret value for server-side consumers.
-- `store.snapshot() -> HashMap` — clones the current key/value map for request-time consumers that need a full view.
-- `SecretStore::validate_name(name: &str) -> Result<()>` — accept only env-var-like keys (`[A-Za-z_][A-Za-z0-9_]*`).
-
-The JSON file format:
-```json
-{
- "ANTHROPIC_API_KEY": {
- "value": "sk-ant-...",
- "created_at": "2026-04-05T10:30:00Z",
- "updated_at": "2026-04-05T10:30:00Z"
- }
-}
-```
-
-File permissions: `0o600` on Unix (same as current `.env`).
-
-Inline tests in `secret_store.rs`:
-- `load` from empty/missing file returns empty store
-- `set` creates entry, verify file written
-- `set` existing key updates `updated_at`, preserves `created_at`
-- `remove` deletes entry, verify file written
-- `remove` missing key returns error
-- `list` returns sorted metadata without values
-- invalid names are rejected
-- use `tempdir` for file paths in tests
-
-In `lib/crates/fabro-server/src/server.rs`:
-- add `pub secret_store: tokio::sync::RwLock` to `AppState`
-- update `build_app_state` to derive `secrets.json` from the active server data dir and call `SecretStore::load(path)?`
-- update `create_app_state` (test helper) to use a temp path
-
-In `lib/crates/fabro-server/src/lib.rs`:
-- add `pub mod secret_store;`
-
-Also in the server layer:
-- add small store-backed adapters for the server-side secret consumers touched by this plan instead of continuing to call `std::env::var(...)` / `from_env()`
-- the adapters only need to cover the flows touched by this plan:
- - LLM client construction for diagnostics/model probing
- - GitHub App credentials for repo checks
- - GitHub client secret and session secret reads in web auth
- - diagnostics secret presence/probe checks
-- request-time server flows should read from the current `SecretStore` snapshot so new credentials take effect immediately
-- startup-time flows may continue to require restart if they only read credentials during boot
-
-### 3. Secret CRUD API endpoints
-
-In `docs/api-reference/fabro-api.yaml`:
-- add schemas:
- ```yaml
- SetSecretRequest:
- description: Request to store a secret value.
- type: object
- required:
- - value
- properties:
- value:
- type: string
- description: The secret value to store.
-
- SecretMetadata:
- description: Metadata for a stored secret (value is never exposed).
- type: object
- required:
- - name
- - created_at
- - updated_at
- properties:
- name:
- type: string
- description: Secret key name.
- example: ANTHROPIC_API_KEY
- created_at:
- type: string
- format: date-time
- description: When the secret was first stored.
- updated_at:
- type: string
- format: date-time
- description: When the secret was last updated.
-
- SecretListResponse:
- description: List of stored secret metadata.
- type: object
- required:
- - data
- properties:
- data:
- type: array
- items:
- $ref: "#/components/schemas/SecretMetadata"
- ```
-
-- add paths:
- ```yaml
- /api/v1/secrets:
- get:
- operationId: listSecrets
- tags: [Secrets]
- summary: List stored secrets (names and timestamps only).
- responses:
- "200":
- description: Secret metadata list.
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/SecretListResponse"
-
- /api/v1/secrets/{name}:
- put:
- operationId: setSecret
- tags: [Secrets]
- summary: Store or update a secret.
- parameters:
- - name: name
- in: path
- required: true
- schema:
- type: string
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/SetSecretRequest"
- responses:
- "200":
- description: Secret stored.
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/SecretMetadata"
- "400":
- description: Invalid secret name or request body.
- delete:
- operationId: deleteSecret
- tags: [Secrets]
- summary: Delete a stored secret.
- parameters:
- - name: name
- in: path
- required: true
- schema:
- type: string
- responses:
- "204":
- description: Secret deleted.
- "400":
- description: Invalid secret name.
- "404":
- description: Secret not found.
- "500":
- description: Secret store write failed.
- ```
-
-Rebuild `fabro-api`:
-```
-cargo build -p fabro-api
-```
-
-In `lib/crates/fabro-server/src/server.rs`:
-- add handlers:
-
- ```rust
- async fn list_secrets(
- _auth: AuthenticatedService,
- State(state): State>,
- ) -> Response {
- let store = state.secret_store.read().await;
- let data = store.list();
- (StatusCode::OK, Json(serde_json::json!({ "data": data }))).into_response()
- }
-
- async fn set_secret(
- _auth: AuthenticatedService,
- State(state): State>,
- Path(name): Path,
- Json(body): Json,
- ) -> Response {
- let mut store = state.secret_store.write().await;
- match store.set(&name, &body.value) {
- Ok(meta) => (StatusCode::OK, Json(meta)).into_response(),
- Err(SecretStoreError::InvalidName(_)) => {
- ApiError::new(StatusCode::BAD_REQUEST, "invalid secret name").into_response()
- }
- Err(e) => ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, e).into_response(),
- }
- }
-
- async fn delete_secret(
- _auth: AuthenticatedService,
- State(state): State>,
- Path(name): Path,
- ) -> Response {
- let mut store = state.secret_store.write().await;
- match store.remove(&name) {
- Ok(()) => StatusCode::NO_CONTENT.into_response(),
- Err(SecretStoreError::InvalidName(_)) => StatusCode::BAD_REQUEST.into_response(),
- Err(SecretStoreError::NotFound(_)) => StatusCode::NOT_FOUND.into_response(),
- Err(_) => StatusCode::INTERNAL_SERVER_ERROR.into_response(),
- }
- }
- ```
-
-- update the `axum::routing` import to include `put` and `delete`
-- ensure request-body logging/redaction treats `PUT /secrets/{name}` values as sensitive and never logs the raw secret
-- add routes in `real_routes()`:
- ```rust
- .route("/secrets", get(list_secrets))
- .route("/secrets/{name}", put(set_secret).delete(delete_secret))
- ```
-
-- add routes in `demo_routes()` pointing to demo handlers (see §10).
-
-Tests in `server.rs` inline tests:
-- `PUT /secrets/TEST_KEY` with `{"value": "test-val"}` → 200, response has `name`, `created_at`, `updated_at`
-- `GET /secrets` → 200, `data` array contains the key just set, no `value` field present
-- `PUT` same key again → 200, `updated_at` changes
-- `PUT /secrets/NOT-VALID` → 400
-- `DELETE /secrets/TEST_KEY` → 204
-- `DELETE /secrets/NONEXISTENT` → 404
-- `GET /secrets` after delete → empty `data`
-
-### 4. Rewrite `fabro secret` CLI commands as API clients
-
-In `lib/crates/fabro-cli/src/commands/secret/mod.rs`:
-- remove `SecretCommand::Get` variant
-- make `execute` async (it currently dispatches to sync functions)
-- each subcommand uses the shared explicit server-target helper, then the generated `fabro_api::Client`
-
-In `lib/crates/fabro-cli/src/args.rs`:
-- add `ServerTargetArgs`:
- ```rust
- #[derive(Args, Debug, Clone, Default)]
- pub(crate) struct ServerTargetArgs {
- /// Fabro server target: http(s) URL or absolute Unix socket path
- #[arg(long = "server", env = "FABRO_SERVER")]
- pub(crate) target: Option,
- }
- ```
-- flatten `ServerTargetArgs` into:
- - `SecretNamespace`
- - `ProviderLoginArgs`
- - `DoctorArgs` (convert the inline `Doctor { ... }` variant to a named args struct)
- - `RepoInitArgs` (convert the inline `RepoCommand::Init { ... }` variant to a named args struct)
-- do **not** add `ServerTargetArgs` to `InstallArgs`; `install` stays local-only
-
-In `lib/crates/fabro-cli/src/user_config.rs`:
-- replace `[server].base_url` support with `[server].target`
-- add a shared parser/resolver for explicit server targets used by these command families:
- - `http://...` or `https://...` => remote HTTP target
- - absolute path => Unix socket target
- - anything else => clear parse error
-- when `ServerTargetArgs` is absent, fall back to the local storage-dir/default-storage-dir server and auto-start it if necessary
-- use this helper from `secret`, `provider login`, `repo init`, and `doctor`
-
-In `lib/crates/fabro-cli/src/commands/secret/set.rs`:
-- replace the body with:
- ```rust
- pub(super) async fn set_command(
- args: &SecretSetArgs,
- server: &ServerTargetArgs,
- globals: &GlobalArgs,
- ) -> Result<()> {
- let client = secret_client(server).await?;
- let meta = client.set_secret()
- .name(&args.key)
- .body(types::SetSecretRequest { value: args.value.clone() })
- .send()
- .await?;
- if globals.json {
- print_json_pretty(&meta)?;
- } else {
- eprintln!("Set {}", args.key);
- }
- Ok(())
- }
- ```
-
-In `lib/crates/fabro-cli/src/commands/secret/list.rs`:
-- remove `--show-values` flag from `SecretListArgs`
-- replace the body with:
- ```rust
- pub(super) async fn list_command(
- args: &SecretListArgs,
- server: &ServerTargetArgs,
- globals: &GlobalArgs,
- ) -> Result<()> {
- let client = secret_client(server).await?;
- let resp = client.list_secrets().send().await?;
- if globals.json {
- print_json_pretty(&resp.data)?;
- } else {
- for secret in &resp.data {
- println!("{}\t{}", secret.name, secret.updated_at);
- }
- }
- Ok(())
- }
- ```
-
-In `lib/crates/fabro-cli/src/commands/secret/rm.rs`:
-- replace the body with:
- ```rust
- pub(super) async fn rm_command(
- args: &SecretRmArgs,
- server: &ServerTargetArgs,
- globals: &GlobalArgs,
- ) -> Result<()> {
- let client = secret_client(server).await?;
- client.delete_secret().name(&args.key).send().await?;
- if globals.json {
- print_json_pretty(&serde_json::json!({ "key": args.key }))?;
- } else {
- eprintln!("Removed {}", args.key);
- }
- Ok(())
- }
- ```
-
-Delete `lib/crates/fabro-cli/src/commands/secret/get.rs`.
-
-In `lib/crates/fabro-cli/src/args.rs`:
-- remove `SecretCommand::Get` and `SecretGetArgs`
-
-Update any integration tests that test `fabro secret get` — remove them.
-
-### 5. Rewrite `fabro provider login` to save via server
-
-In `lib/crates/fabro-cli/src/commands/provider/login.rs`:
-- after obtaining validated `env_pairs` (the `Vec<(String, String)>` of env var name → key value), replace the `provider_auth::write_env_file(...)` call with API calls:
- ```rust
- let client = provider_secret_client(&args.server).await?;
- for (env_var, key) in &env_pairs {
- client.set_secret()
- .name(env_var)
- .body(types::SetSecretRequest { value: key.clone() })
- .send()
- .await
- .with_context(|| format!("failed to save {env_var} to server"))?;
- }
- ```
-- remove the `provider_auth::write_env_file` call
-- add a temporary warning if a legacy `.env` file exists under the active local storage dir:
- ```
- Warning: ~/.fabro/.env is no longer read by fabro server. Re-enter credentials with `fabro provider login` or `fabro secret set`.
- ```
-
-In `lib/crates/fabro-cli/src/shared/provider_auth.rs`:
-- `write_env_file` may become dead code after this change. If no other callers exist, delete it.
-- `validate_api_key` currently calls `std::env::set_var` temporarily to validate. This still works because validation happens before saving. However, consider whether the validation should instead construct the LLM client explicitly with the key rather than mutating process env. This is a follow-up concern — for now the existing validation approach is fine since the CLI process is single-threaded for this flow.
-
-### 5a. Update `fabro install` to save GitHub App secrets via the local server
-
-In `lib/crates/fabro-cli/src/commands/install.rs`:
-- keep `install` local-only. It should always operate on the local server for the active storage dir and never accept `--server`
-- after writing `server.toml` / `user.toml` and producing GitHub App secret env pairs, persist those secret values via the local server's `PUT /secrets/{name}` API instead of writing `.env`
-- detect whether the local server was already running before `install`
-- if the server was not running, letting the local client auto-start it is fine
-- if the server was already running, print a clear restart warning after saving secrets:
- ```
- Fabro server was already running. Restart it to pick up startup-time credential changes (for example webhook listener configuration).
- ```
-- remove the `.env` reload
-- update the final doctor invocation to the new signature / args shape
-
-This is intentionally a hard break from `.env`, but `install` should print a temporary migration warning if it sees a legacy `.env` file in the local storage dir.
-
-### 6. `GET /api/v1/repos/github/{owner}/{name}` endpoint
-
-In `docs/api-reference/fabro-api.yaml`:
-- add schema:
- ```yaml
- RepoCheckResponse:
- description: Repository access check result.
- type: object
- required:
- - owner
- - name
- - accessible
- properties:
- owner:
- type: string
- description: GitHub repository owner.
- example: acme-corp
- name:
- type: string
- description: GitHub repository name.
- example: my-app
- accessible:
- type: boolean
- description: Whether the server has read-write access to this repository.
- default_branch:
- type: string
- nullable: true
- description: Default branch name, if accessible.
- example: main
- private:
- type: boolean
- nullable: true
- description: Whether the repository is private, if accessible.
- permissions:
- type: object
- nullable: true
- description: Detected permission levels.
- properties:
- pull:
- type: boolean
- push:
- type: boolean
- admin:
- type: boolean
- install_url:
- type: string
- nullable: true
- description: GitHub App installation URL when the repo is not yet accessible.
- ```
-
-- add path:
- ```yaml
- /api/v1/repos/github/{owner}/{name}:
- get:
- operationId: getGithubRepo
- tags: [Repos]
- summary: Check server access to a GitHub repository.
- parameters:
- - name: owner
- in: path
- required: true
- schema:
- type: string
- - name: name
- in: path
- required: true
- schema:
- type: string
- responses:
- "200":
- description: Repository access details.
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/RepoCheckResponse"
- ```
-
-Rebuild `fabro-api`:
-```
-cargo build -p fabro-api
-```
-
-In `lib/crates/fabro-server/Cargo.toml`:
-- add `fabro-github` as a dependency if not already present
-
-In `lib/crates/fabro-server/src/server.rs`:
-- add handler:
- ```rust
- async fn get_github_repo(
- _auth: AuthenticatedService,
- State(state): State>,
- Path((owner, name)): Path<(String, String)>,
- ) -> Response
- ```
- The handler:
- 1. Reads non-secret GitHub App config (`app_id`, `slug`) from `Settings`. Reads `GITHUB_APP_PRIVATE_KEY` from `SecretStore`.
- 2. Signs a JWT via `fabro_github::sign_app_jwt`.
- 3. Calls `GET /repos/{owner}/{name}/installation` to check if the App is installed.
- 4. If installed, mints an installation token and calls `GET /repos/{owner}/{name}` to get repo details (default branch, private flag, permissions).
- 5. If not installed, returns `accessible: false` with null optional fields and, when possible, an `install_url`.
- 6. Returns `RepoCheckResponse`.
-
- If GitHub App credentials are not configured (missing from settings or secret store), return `accessible: false` with a descriptive error or a 503.
-
-- add route in `real_routes()`:
- ```rust
- .route("/repos/github/{owner}/{name}", get(get_github_repo))
- ```
-- add route in `demo_routes()` pointing to demo handler (see §10).
-
-Tests:
-- Testing the real handler requires mocking the GitHub API or the `HttpClient` trait. Use a unit test that exercises the response shape with a mock `AppState` that has a test GitHub client, or test at the integration level with the demo handler.
-- At minimum, test the demo handler returns 200 with the expected shape.
-
-### 7. Update `fabro repo init` to call repo endpoint
-
-In `lib/crates/fabro-cli/src/commands/repo/init.rs`:
-- replace `check_github_app_installation()` with a server call:
- ```rust
- async fn check_repo_access(owner: &str, name: &str, args: &RepoInitArgs) -> Result<()> {
- let client = repo_client(&args.server).await?;
- let resp = client.get_github_repo()
- .owner(owner)
- .name(name)
- .send()
- .await?;
- if resp.accessible {
- println!(" {} GitHub repo {}/{} is accessible", green_check, owner, name);
- if let Some(branch) = &resp.default_branch {
- println!(" Default branch: {branch}");
- }
- } else {
- println!(" {} GitHub repo {}/{} is not accessible", yellow_warn, owner, name);
- println!(" Install the GitHub App to enable PR creation and webhook triggers.");
- if let Some(url) = &resp.install_url {
- println!(" Install at: {url}");
- }
- }
- Ok(())
- }
- ```
-- The function still parses the git remote to extract `owner`/`name` — that stays CLI-side since it reads the local git config.
-- Remove the direct `fabro_github::sign_app_jwt`, `fabro_github::check_app_installed`, `build_github_app_credentials` calls.
-- Keep the `fabro-github` dependency in `fabro-cli/Cargo.toml` — it has many other callers (pr/*, preflight.rs, shared/github.rs).
-- preserve the current interactive UX:
- - when the repo is not yet accessible and stdin is a terminal, print the install URL, wait for Enter, then call the repo endpoint again
- - print the second check result after the re-check
-
-### 8. `POST /api/v1/health/diagnostics` endpoint
-
-In `docs/api-reference/fabro-api.yaml`:
-- add schemas:
- ```yaml
- DiagnosticsReport:
- description: Server health diagnostics report.
- type: object
- required:
- - version
- - sections
- properties:
- version:
- type: string
- description: Server version.
- sections:
- type: array
- items:
- $ref: "#/components/schemas/DiagnosticsSection"
-
- DiagnosticsSection:
- type: object
- required:
- - title
- - checks
- properties:
- title:
- type: string
- checks:
- type: array
- items:
- $ref: "#/components/schemas/DiagnosticsCheck"
-
- DiagnosticsCheck:
- type: object
- required:
- - name
- - status
- - summary
- properties:
- name:
- type: string
- status:
- type: string
- enum:
- - pass
- - warning
- - error
- summary:
- type: string
- details:
- type: array
- items:
- $ref: "#/components/schemas/DiagnosticsDetail"
- remediation:
- type: string
- nullable: true
-
- DiagnosticsDetail:
- type: object
- required:
- - text
- - warn
- properties:
- text:
- type: string
- warn:
- type: boolean
- ```
-
-- add path:
- ```yaml
- /api/v1/health/diagnostics:
- post:
- operationId: runDiagnostics
- tags: [Discovery]
- summary: Run server health diagnostics.
- description: Probes external services (LLM providers, GitHub, sandbox) and checks server configuration. May be slow.
- responses:
- "200":
- description: Diagnostics report.
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/DiagnosticsReport"
- ```
-
-Rebuild `fabro-api`:
-```
-cargo build -p fabro-api
-```
-
-Create `lib/crates/fabro-server/src/diagnostics.rs`.
-
-This module contains the server-side check functions. Many can be adapted from the existing `doctor.rs` in `fabro-cli`. The key checks, grouped into sections:
-
-**Section "Credentials":**
-- `check_llm_providers` — for each provider in `Provider::ALL`, check if a secret exists in the store and probe connectivity by sending a test message.
-- `check_github_app` — check that `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, etc. exist in settings/store, validate JWT signing, and probe `GET /app` on GitHub API.
-- `check_sandbox` — check `DAYTONA_API_KEY` exists. Probe Daytona API.
-- `check_brave_search` — check `BRAVE_SEARCH_API_KEY` exists. Probe Brave API.
-
-**Section "System":**
-- `check_system_dep_dot` — check `dot` is in PATH and version ≥ 2.0.0.
-
-**Section "Configuration":**
-- `check_crypto` — validate mTLS certs/keys, JWT keys, session secret (same checks as current doctor).
-
-Dropped from diagnostics (compared to current doctor):
-- `check_api` / `check_web` — the CLI's ability to call the diagnostics endpoint is itself the connectivity check. No circular self-check.
-- `check_system_dep_node` — node is a build-time dependency only, not needed at server runtime.
-- `check_system_dep_openssl` — being removed soon.
-
-The handler:
-
-```rust
-async fn run_diagnostics(
- _auth: AuthenticatedService,
- State(state): State>,
-) -> Response {
- let report = diagnostics::run_all(&state).await;
- (StatusCode::OK, Json(report)).into_response()
-}
-```
-
-`diagnostics::run_all` runs all checks concurrently (where possible) and returns a `DiagnosticsReport`. The probes (LLM, GitHub, Daytona, Brave) should be run concurrently via `tokio::join!` or `futures::join!`.
-- apply explicit timeouts to the live probes so `doctor` cannot hang indefinitely
-- keep concurrency bounded to this fixed set of checks; do not allow unbounded fan-out
-
-Each check function returns a `DiagnosticsCheck` struct that maps 1:1 to the API schema. The existing `CheckResult` from `fabro_util::check_report` is very close — consider either:
-- reusing `CheckResult` directly and serializing it (it already has `Serialize`)
-- or mapping to the generated `fabro_api` types
-
-For the wire contract, prefer an explicit conversion step rather than assuming `CheckResult` serialization is automatically stable enough for the API surface.
-
-Add route in `real_routes()`:
-```rust
-.route("/health/diagnostics", post(run_diagnostics))
-```
-
-Add route in `demo_routes()` pointing to demo handler (see §10).
-
-Tests:
-- test that `POST /health/diagnostics` returns 200 with a `version` field and a non-empty `sections` array
-- test that each section has a `title` and `checks` array
-- test the demo handler returns the same shape
-
-### 9. Rewrite `fabro doctor` as API client
-
-In `lib/crates/fabro-cli/src/commands/doctor.rs`:
-- replace `run_doctor` with a thin client:
- ```rust
- pub async fn run_doctor(args: &DoctorArgs, globals: &GlobalArgs) -> Result<()> {
- let client = doctor_client(&args.server).await?;
-
- // Local config warning block
- let local_checks = render_local_config_checks()?;
-
- // Version parity check
- let health = client.get_health().send().await?;
- let server_version = &health.version;
- let cli_version = fabro_util::version::FABRO_VERSION;
-
- // Run diagnostics
- let report = client.run_diagnostics().send().await?;
-
- if globals.json {
- print_json_pretty(&report)?;
- return Ok(());
- }
-
- // Version parity
- if server_version != cli_version {
- eprintln!(
- "⚠ Version mismatch: CLI={cli_version} Server={server_version}"
- );
- }
-
- // Render the retained local config warnings first, then the server diagnostics report.
- render_local_checks(&local_checks);
- render_diagnostics(&report);
-
- Ok(())
- }
- ```
-- the rendering logic from `CheckReport::render()` can be reused. Either:
- - convert the API response into a `CheckReport` and call `render()`
- - or extract the rendering logic into a function that takes the diagnostics fields directly
-- remove the local dry-run / offline mode flag
-- keep the local user-config and legacy `.env` checks
-- remove the other local check functions (`check_llm_providers`, `check_github_app`, `check_sandbox`, `check_brave_search`, `check_system_deps`, `check_api`, `check_web`, `check_crypto`)
-- remove the corresponding test functions if they only tested the removed local checks
-- keep the `CheckReport`/`CheckResult` rendering code in `fabro_util::check_report` — it is still useful for rendering the server's response
-
-If the server client connection fails (server unreachable), the error message should be clear:
-```
-Error: could not connect to fabro server. Run `fabro server start` or check `fabro server status`.
-```
-
-Also:
-- if a legacy local `.env` file exists, print a temporary warning that the server no longer reads it
-- `doctor` should still succeed in rendering that local warning even when the diagnostics call later fails
-
-### 10. Demo mode handlers
-
-In `lib/crates/fabro-server/src/demo/mod.rs`:
-
-**Secrets demo:**
-- maintain a static in-memory `HashMap` with pre-populated fake secrets:
- ```rust
- pub(crate) async fn list_secrets(...) -> Response {
- let data = vec![
- serde_json::json!({
- "name": "ANTHROPIC_API_KEY",
- "created_at": "2026-01-15T09:00:00Z",
- "updated_at": "2026-03-20T14:30:00Z",
- }),
- serde_json::json!({
- "name": "OPENAI_API_KEY",
- "created_at": "2026-01-15T09:05:00Z",
- "updated_at": "2026-02-10T11:00:00Z",
- }),
- serde_json::json!({
- "name": "GITHUB_APP_PRIVATE_KEY",
- "created_at": "2026-01-15T09:10:00Z",
- "updated_at": "2026-01-15T09:10:00Z",
- }),
- ];
- (StatusCode::OK, Json(serde_json::json!({ "data": data }))).into_response()
- }
-
- pub(crate) async fn set_secret(...) -> Response {
- // return fake metadata with current timestamps
- }
-
- pub(crate) async fn delete_secret(...) -> Response {
- StatusCode::NO_CONTENT.into_response()
- }
- ```
-
-**Repo demo:**
-- return a fake accessible repo:
- ```rust
- pub(crate) async fn get_github_repo(
- ...,
- Path((owner, name)): Path<(String, String)>,
- ) -> Response {
- (StatusCode::OK, Json(serde_json::json!({
- "owner": owner,
- "name": name,
- "accessible": true,
- "default_branch": "main",
- "private": false,
- "permissions": { "pull": true, "push": true, "admin": false },
- }))).into_response()
- }
- ```
-
-**Diagnostics demo:**
-- return an all-passing report:
- ```rust
- pub(crate) async fn run_diagnostics(...) -> Response {
- (StatusCode::OK, Json(serde_json::json!({
- "version": fabro_util::version::FABRO_VERSION,
- "sections": [
- {
- "title": "Credentials",
- "checks": [
- { "name": "LLM Providers", "status": "pass", "summary": "Anthropic, OpenAI configured", "details": [], "remediation": null },
- { "name": "GitHub App", "status": "pass", "summary": "JWT signing OK", "details": [], "remediation": null },
- { "name": "Sandbox", "status": "pass", "summary": "Daytona reachable", "details": [], "remediation": null },
- { "name": "Brave Search", "status": "pass", "summary": "API key configured", "details": [], "remediation": null },
- ]
- },
- {
- "title": "System",
- "checks": [
- { "name": "dot", "status": "pass", "summary": "dot 12.1.2", "details": [], "remediation": null },
- ]
- },
- {
- "title": "Configuration",
- "checks": [
- { "name": "Crypto", "status": "pass", "summary": "All keys valid", "details": [], "remediation": null },
- ]
- },
- ]
- }))).into_response()
- }
- ```
-
-Wire all demo handlers in `demo_routes()`:
-```rust
-.route("/secrets", get(demo::list_secrets))
-.route("/secrets/{name}", put(demo::set_secret).delete(demo::delete_secret))
-.route("/repos/github/{owner}/{name}", get(demo::get_github_repo))
-.route("/health/diagnostics", post(demo::run_diagnostics))
-```
-
-## Implementation Order
-
-```
-1 Health version (no deps, small)
-2 Secret store + adapters (no deps)
-3 Secret CRUD API (depends on 2)
-4 Shared server target plumbing (parallel with 2-3)
-5 Secret CLI migration (depends on 3, 4)
-6 Provider login migration (depends on 3, 4)
-7 Install migration (depends on 3)
-8 Repo check API (depends on 2)
-9 Repo init migration (depends on 4, 8)
-10 Diagnostics API (depends on 2)
-11 Doctor CLI migration (depends on 1, 4, 10)
-```
-
-Steps 1, 2, and 4 can start in parallel. Steps 5 and 6 can run in parallel once 3 and 4 are done.
-
-## Resolved Questions
-
-1. **Secret store path**: `/secrets.json` under the active server data dir. Credentials are owned by the server instance, not by a global shared file.
-
-2. **Migration from existing `.env`**: no auto-import. Hard break. Users must re-enter credentials via `fabro provider login` or `fabro secret set`, and the CLI/server should emit a temporary warning when they detect a legacy `.env`.
-
-3. **GitHub App credentials for repo check**: non-secret config (`app_id`, `slug`) goes in server settings (not mixed with secrets). Secret values (`GITHUB_APP_PRIVATE_KEY`) go in the secret store. The repo check handler reads `app_id`/`slug` from `Settings` and `GITHUB_APP_PRIVATE_KEY` from `SecretStore`.
-
-4. **Diagnostics: `check_api` and `check_web`**: dropped. The CLI's ability to call the diagnostics endpoint *is* the API connectivity check — if the server is unreachable, the CLI gets a connection error before any diagnostics run. No circular self-check needed. The one retained local CLI check is user config / legacy `.env`.
-
-5. **`node` dependency**: dropped from diagnostics. The web app is an SPA served by the Rust server; `node` is a build-time dependency only, not needed at server runtime.
-
-6. **`dot` dependency**: moves server-side. `openssl` dependency: dropped (being removed soon).
-
-7. **Server targeting**: server-canonical admin commands use `--server ` and `[server].target`, where `` is either an HTTP(S) base URL or an absolute Unix socket path.
-
-8. **`fabro install` targeting**: `install` is local-only and writes config plus secrets for the local server host. If the server was already running, `install` prints that a restart is required for startup-time features to pick up new secrets.
diff --git a/docs/plans/2026-04-06-cli-config-socket-storage-separation-plan.md b/docs/plans/2026-04-06-cli-config-socket-storage-separation-plan.md
deleted file mode 100644
index 5e24ba8e2..000000000
--- a/docs/plans/2026-04-06-cli-config-socket-storage-separation-plan.md
+++ /dev/null
@@ -1,231 +0,0 @@
-# CLI Config, Socket, And Storage Separation
-
-## Summary
-Separate machine config, server target, and server storage so the CLI no longer conflates:
-
-- config path: `~/.fabro/settings.toml`
-- default socket target: `~/.fabro/fabro.sock`
-- default storage dir: `~/.fabro/storage`
-
-Normal user-facing commands should always talk to a server target. A Unix socket target may auto-start the daemon. An HTTP target may not. Serverless/direct-storage command behavior should be removed from normal commands in this pass.
-
-## Scope Boundaries
-In scope:
-- add `FABRO_CONFIG` support for machine settings loading
-- default the server target to `~/.fabro/fabro.sock`
-- default server storage to `~/.fabro/storage`
-- decouple socket-path resolution from storage-dir resolution
-- keep daemon auto-start only for Unix socket targets
-- remove normal-command fallback to direct storage-based targeting
-- keep `fabro server *`, hidden `fabro __runner`, and `fabro install` as storage-owning commands
-- keep user-facing `--server` on server-targeted commands
-- remove user-facing `--storage-dir` from server-targeted commands
-
-Out of scope:
-- `fabro exec`
-- `fabro system df`
-- `fabro system prune`
-- `fabro store dump`
-- new remote maintenance endpoints for deferred commands
-
-## Problem Frame
-The current CLI still mixes together two different ideas:
-
-- a local daemon reached over a Unix socket
-- serverless behavior where the CLI uses `storage_dir` as the command target
-
-That has produced the wrong defaults and the wrong abstractions:
-
-- the socket path is currently derived from `storage_dir`
-- many commands still model targeting as "server or storage dir"
-- normal commands can still fall back to a storage-driven local connection shape
-- autostart is keyed off the local/storage connection path instead of the actual server target type
-
-The intended model is simpler:
-
-- normal commands always resolve a server target
-- the default server target is a Unix socket in `~/.fabro`
-- Unix socket targets may auto-start a daemon
-- HTTP targets may not auto-start a daemon
-- storage is server-owned runtime state, not the primary targeting mechanism for normal commands
-
-## Key Decisions
-- `FABRO_CONFIG` selects the active machine settings file.
- - For server lifecycle commands and daemon auto-start, precedence is: explicit `--config` where supported, then `FABRO_CONFIG`, then `~/.fabro/settings.toml`.
- - Normal user-facing commands do not gain a new `--config` flag in this pass; they resolve settings from `FABRO_CONFIG` or the default path.
-- `FABRO_SERVER` selects the effective server target for normal commands.
- - It accepts either an absolute Unix socket path or an `http(s)` URL.
- - If unset, use `settings.server.target`.
- - If that is unset, default to `~/.fabro/fabro.sock`.
-- Server-targeted commands keep `--server` as the standard one-off override.
- - `FABRO_SERVER` remains the env-var equivalent.
-- `FABRO_STORAGE_DIR` is no longer a normal command-targeting mechanism.
- - It remains an override for storage-owning commands only.
- - Precedence for storage-owning commands: explicit `--storage-dir` where still supported, then `FABRO_STORAGE_DIR`, then `settings.storage_dir`, then `~/.fabro/storage`.
-- `settings.server.target` remains the durable place to configure the machine's server target.
-- `settings.storage_dir` remains the durable place to configure where the local server stores data.
-- `fabro server start` keeps `--config` and `--bind`.
- - Its default bind is `~/.fabro/fabro.sock`, not `/fabro.sock`.
-- `fabro server stop` and `fabro server status` remain storage-owning commands and continue to resolve the local server instance from storage-owned records.
-- `fabro settings` is a local config-inspection command, not a server-targeted command.
- - It keeps its current local settings-resolution behavior in this pass.
-- `fabro exec` is unchanged in this pass.
-
-## Command Classification
-### Storage-owning commands
-These commands continue to resolve and use local storage directly:
-
-- `fabro server start`
-- `fabro server stop`
-- `fabro server status`
-- hidden `fabro server __serve`
-- hidden `fabro run __runner`
-- `fabro install`
-
-### Local config-inspection commands
-These commands stay outside the server-targeting cleanup in this pass:
-
-- `fabro settings`
-
-### Server-targeted commands
-These commands should resolve a `ServerTarget` only and should not use storage-dir fallback semantics:
-
-- `fabro run`
-- `fabro create`
-- `fabro preflight`
-- `fabro validate`
-- `fabro graph`
-- `fabro model list`
-- `fabro model test`
-- `fabro doctor`
-- `fabro repo init`
-- `fabro provider login`
-- `fabro secret list`
-- `fabro secret rm`
-- `fabro secret set`
-- `fabro ps`
-- `fabro rm`
-- `fabro inspect`
-- `fabro run start`
-- `fabro run attach`
-- `fabro run logs`
-- `fabro run resume`
-- `fabro run rewind`
-- `fabro run fork`
-- `fabro run wait`
-- hidden `fabro run diff`
-- `fabro artifact list`
-- `fabro artifact cp`
-- `fabro sandbox cp`
-- `fabro sandbox preview`
-- `fabro sandbox ssh`
-- `fabro pr create`
-- `fabro pr list`
-- `fabro pr view`
-- `fabro pr merge`
-- `fabro pr close`
-
-### Deferred local-maintenance commands
-These remain unchanged in this pass:
-
-- `fabro system df`
-- `fabro system prune`
-- `fabro store dump`
-
-These deferred commands continue to use `StorageDirArgs` and the existing hybrid `ServerRunLookup::connect(storage_dir)` path in this pass, and should keep working against the new default storage dir without being reclassified as server-targeted commands yet.
-
-## Implementation Changes
-### 1. Shared settings and path resolution
-- Add a shared helper for the active settings path used by CLI and server code.
- - This helper must honor `FABRO_CONFIG`.
-- Add a shared helper for the default socket path: `~/.fabro/fabro.sock`.
-- Change the default storage dir helper to return `~/.fabro/storage`.
-- Stop deriving the socket path from `storage_dir`.
-
-### 2. Target resolution model
-- Refactor CLI target resolution so normal commands resolve a `ServerTarget`, not a "local vs target" union.
-- Remove `ServerConnection::Local` as a normal command-routing concept.
-- Split helpers into two categories:
- - server-target resolution for normal commands
- - storage-dir resolution for storage-owning commands
-- Keep TLS handling attached to `HttpUrl` targets exactly as today.
-
-### 3. Connection and auto-start behavior
-- Update the server client helpers so they accept or derive a `ServerTarget`.
-- If the resolved target is `UnixSocket(path)`:
- - attempt to connect to that socket
- - if unavailable, auto-start the daemon
- - auto-start the daemon bound to that exact socket path
-- If the resolved target is `HttpUrl(url)`:
- - attempt to connect once
- - if unavailable, fail with a clean reachability error
- - do not auto-start anything
-- Auto-start must pass the active config path through to the spawned server with `--config`.
-- The auto-start helper should take the resolved active config path, resolved Unix socket path, and resolved local storage dir as explicit inputs.
- - It should not rediscover config via environment variables or reload settings internally during daemon launch.
-- Auto-start may also pass the resolved storage dir for the local server process, but only as runtime/server lifecycle plumbing, not as the command target abstraction.
-- Any active-server record lookup used by `server stop`, `server status`, `install`, or daemon auto-start should temporarily fall back to the legacy implicit storage root `~/.fabro` when no explicit storage location is provided and no record exists under the new default `~/.fabro/storage`.
- - This is only to find already-running daemons started before the default-storage change.
-
-### 4. CLI arg surface cleanup
-- Keep user-facing `--server` on all server-targeted commands listed above.
-- Remove user-facing `--storage-dir` from all server-targeted commands listed above.
-- Remove the `storage_dir_explicit` conflict plumbing for those commands.
-- Remove the custom `--server` / `--storage-dir` conflict detection in `main.rs` once no supported command still accepts both flags together.
-- Keep `--storage-dir` only on storage-owning commands in this pass.
-- Keep `--config` only where already appropriate for server lifecycle.
-- Update help text and parser tests so normal commands still advertise `--server` but no longer imply that storage-dir is a general targeting control.
-
-### 5. Run/create local run-dir handling
-- `run` / `create` currently thread a synthesized local run dir through the result object to print asset paths after completion.
-- Preserve that behavior only when the effective target is the machine's local Unix socket and the effective local storage dir is known.
-- For HTTP targets, do not synthesize a local run dir.
-- This should be derived from "effective target is local socket" plus resolved storage dir, not from a `ServerConnection::Local` enum variant.
-
-### 6. Docs and user-visible messaging
-- Rewrite docs and examples so:
- - normal commands use config-driven target resolution by default
- - temporary overrides use `FABRO_SERVER=... fabro ...`
- - config-file overrides use `FABRO_CONFIG=... fabro ...`
-- Update language to avoid "local mode" as a user-facing concept.
- - Use "Unix socket target" or "HTTP target".
- - Use "serverless" only for the behavior being removed.
-- Make `doctor` and `settings` print:
- - active config path
- - effective server target
- - effective storage dir
- - any active env-var overrides
-
-## Test Plan
-- Unit tests for path and precedence helpers:
- - active config path honors `FABRO_CONFIG`
- - default socket path is `~/.fabro/fabro.sock`
- - default storage dir is `~/.fabro/storage`
- - `FABRO_SERVER` overrides `settings.server.target`
- - `FABRO_STORAGE_DIR` overrides `settings.storage_dir` for storage-owning commands only
- - `FABRO_CONFIG=/custom/path/settings.toml` loads that file's contents and the resolved `server.target` / `storage_dir` from that file actually take effect
-- Unit tests for target resolution:
- - normal commands default to a Unix socket target when nothing is configured
- - normal commands no longer resolve a storage-dir fallback connection
- - HTTP targets never route into autostart code
-- Integration tests for daemon behavior:
- - `fabro server start` defaults to binding `~/.fabro/fabro.sock`
- - auto-start for socket-targeted commands binds the requested socket, not `/fabro.sock`
- - auto-start passes the active config path through to the daemon
- - HTTP-targeted commands fail cleanly when unreachable
- - `server stop` / `server status` still find an already-running daemon whose record lives under the legacy implicit storage root
-- Parser/help tests:
- - server-targeted commands still accept `--server`
- - server-targeted commands no longer accept `--storage-dir`
- - storage-owning commands still accept `--storage-dir` where intended
- - `fabro settings` keeps its existing local settings override surface in this pass
-- Workflow behavior tests:
- - `run`, `create`, `model`, `doctor`, `ps`, and `secret` work via the default socket target
- - local Unix socket runs still print local asset/run-dir info when appropriate
- - HTTP-targeted runs do not print synthesized local run-dir paths
-
-## Assumptions
-- This is a hard cut for CLI targeting semantics. No deprecation period for removed normal-command flags.
-- `FABRO_SERVER` is the single override for user-facing command targeting; no separate `FABRO_SOCKET` env var is added.
-- `server.target` remains the canonical durable target field in `settings.toml`.
-- Deferred commands will be handled in a later pass rather than forced into this refactor.
diff --git a/docs/plans/2026-04-06-object-backed-artifact-uploads.md b/docs/plans/2026-04-06-object-backed-artifact-uploads.md
deleted file mode 100644
index f11a7e503..000000000
--- a/docs/plans/2026-04-06-object-backed-artifact-uploads.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Object-Backed Artifact Uploads
-
-## Summary
-- Make `ArtifactStore` the durable source of truth for all stage artifacts, backed by a configurable object store that can be local filesystem or S3.
-- Keep the server as the only durable artifact writer. Worker subprocesses upload artifacts to the server over the existing stage-artifacts POST route; they do not write `ArtifactStore` directly and do not use the run scratch directory as IPC.
-- Ship both upload modes on `POST /api/v1/runs/{id}/stages/{stageId}/artifacts`:
- - `application/octet-stream` for single-file upload
- - `multipart/form-data` for batch upload on the same path
-- Default artifact-upload failure policy is non-fatal: after bounded retries, the worker emits a warning notice and the run continues.
-- Multipart uploads are a strict wire format: the `manifest` part must arrive first so the server can validate the batch before accepting file bytes.
-
-## Key Changes
-- Add artifact storage configuration separate from the main run-store path:
- - default backend: local object store rooted under the existing storage directory
- - optional backend: S3 with bucket, region, prefix, optional endpoint override, and path-style toggle
-- Refactor server startup so `ArtifactStore` is constructed from artifact-storage config instead of being hardwired to `LocalFileSystem` in `serve.rs`.
-- Extend `ArtifactStore` with streaming writes:
- - add `put_stream(...)` that writes directly to the configured object store using `object_store::buffered::BufWriter`
- - use the same deterministic object key layout as today so retries are idempotent
-- Replace the buffered server artifact upload handler with a streaming implementation:
- - `application/octet-stream`: requires `filename` query param, streams request body into `ArtifactStore`
- - `multipart/form-data`: requires a JSON `manifest` part first, followed by file parts; the manifest is the canonical source of artifact paths and optional checksums/content types
-- Add multipart request types to the OpenAPI spec:
- - `ArtifactBatchUploadManifest`
- - `ArtifactBatchUploadEntry`
- - one entry per file part, keyed by part name and relative artifact path
-- Validate both octet-stream `filename` query params and multipart manifest paths with the existing relative-path rules; reject traversal, empty segments, duplicate manifest paths, duplicate part names, missing parts, and unexpected parts.
-- Compute and verify `sha256` during upload when provided by the client. If omitted, accept the upload without checksum enforcement. Native backend checksum features such as S3-specific checksum headers are optional optimizations, not part of the v1 contract.
-- Enforce explicit server-side limits:
- - maximum single artifact size
- - maximum artifacts per multipart request
- - maximum total multipart request bytes
- - reject uploads that exceed these limits before durable commit when possible, and abort active multipart writes when the limit is crossed mid-stream
-- For multipart requests, return non-2xx on the first failed file and leave already-written objects in place. Retries are safe because object keys are deterministic; v1 does not attempt cross-object rollback.
-- Treat concurrent uploads to the same `{run_id, stage_id, path}` as idempotent-safe retries. Deterministic object keys mean duplicate concurrent uploads may race, but the final durable object must be equivalent regardless of which writer wins.
-- Update worker subprocess behavior:
- - after a stage captures artifacts locally, the worker uploads them to the server over the internal artifact route
- - single-file uploads may use raw octet-stream; batch upload should use multipart when multiple artifacts exist for the stage
- - the worker emits `artifact.captured` only after the server confirms durable upload
- - on repeated upload failure, the worker emits a warning-style run notice and continues
-- Update read paths so `ArtifactStore` is the only source for list/download; no run-scratch fallback is required.
-- Extend the worker spawn contract so the server provides:
- - internal server address or Unix-socket target
- - a short-lived bearer token scoped to artifact upload routes for that run
-- Accept that interrupted multipart uploads may leave orphaned objects in v1. Record this as operational debt and add a later cleanup pass or age-based GC policy for abandoned artifact objects.
-
-## Public Interfaces
-- `POST /api/v1/runs/{id}/stages/{stageId}/artifacts` accepts both `application/octet-stream` and `multipart/form-data`.
-- Multipart wire format:
- - one `manifest` JSON part first
- - one file part per manifest entry
- - manifest fields: `part`, `path`, optional `sha256`, optional `expected_bytes`, optional `content_type`
-- Settings gain artifact object-store configuration, with local as the default and S3 as an explicit opt-in backend.
-
-## Test Plan
-- Server integration: single-file octet-stream upload stores objects in local object store and returns `204`.
-- Server integration: multipart batch upload with manifest stores every artifact under the expected object keys and returns `204`.
-- Validation: invalid artifact path, invalid octet-stream `filename`, duplicate path, duplicate part name, missing file part, unexpected file part, malformed manifest, and manifest-not-first all return `400`.
-- Integrity: checksum mismatch returns error and does not mark the artifact as captured.
-- Limits: oversized single artifact, oversized batch byte total, and too many multipart entries all fail with the configured limit response and abort the active upload.
-- Retry behavior: partial multipart failure can be retried safely and produces the correct final artifact set.
-- Concurrency: concurrent uploads to the same run/stage/path converge safely to one correct durable object.
-- Read path: list/download returns artifacts only from `ArtifactStore`.
-- Worker integration: worker uploads captured artifacts through the server route and emits `artifact.captured` only after success.
-- Failure behavior: repeated upload failure emits a warning notice and the run completes without failing.
-- Backend coverage: large artifact upload works against an S3-compatible backend such as MinIO and uses streaming/multipart object-store writes without buffering the full file in memory.
-
-## Assumptions
-- Scope is limited to `ArtifactStore` stage artifacts. Large run blobs written by `RunDatabase::write_blob()` are unchanged.
-- Runs are expected to have durable artifacts in object storage; scratch copies are only local cache/state.
-- The server remains the sole durable artifact writer and owns all artifact object-store credentials.
-- Non-fatal artifact-upload failure is the chosen default for v1; if strict durability becomes required later, it can be added as a separate policy change.
-- The artifact object key remains scoped by run id, stage id, and relative artifact path, so same-key retries are naturally idempotent.
diff --git a/docs/plans/2026-04-06-settings-command-server-local-merge-plan.md b/docs/plans/2026-04-06-settings-command-server-local-merge-plan.md
deleted file mode 100644
index 7ce0c2c89..000000000
--- a/docs/plans/2026-04-06-settings-command-server-local-merge-plan.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Settings Command Server/Local Merge Plan
-
-## Summary
-Refactor `fabro settings` so it answers “what settings will actually be used?” instead of only dumping locally merged config.
-
-The command contract becomes:
-
-- `fabro settings`
- - show the effective merged settings for the selected server target plus local config
-- `fabro settings --local`
- - show only locally resolved settings, with no server call
-- `fabro settings WORKFLOW`
- - show the effective merged settings for that workflow after server defaults are applied
-- `fabro settings --local WORKFLOW`
- - show the local-only merged settings for that workflow, with no server call
-
-This plan is intentionally separate from the broader config/socket/storage cleanup. It can land independently as long as the command reuses the current shared target-resolution behavior that exists at implementation time.
-
-## Problem Frame
-The current `fabro settings` command is purely local. It resolves project/workflow config plus local machine settings and prints the result in YAML or JSON.
-
-That is no longer the most useful answer for users, because workflows run on a server and the final settings are not purely local. The server already applies its own defaults and runtime adjustments during manifest preparation, so the current output is only a partial picture.
-
-The goal of this pass is to make `fabro settings` answer two distinct questions clearly:
-
-- what would the CLI resolve locally without talking to a server?
-- what settings will actually be used when this workflow runs on the selected server?
-
-## Key Decisions
-- `fabro settings` becomes server-targeted by default.
- - It should fetch server settings and merge them with local config using the same merge logic the server uses for real runs.
-- `fabro settings --local` skips the server entirely and preserves the current local inspection behavior.
-- `fabro settings` keeps the optional positional `WORKFLOW`.
- - With no workflow argument, it shows the effective baseline settings for the current repo/config context.
- - With a workflow argument, it shows the effective run settings for that workflow.
-- `fabro settings` should support `--server` as the normal one-off server-target override.
-- `fabro settings --local` conflicts with `--server`.
-- `fabro settings` should no longer take `--storage-dir`.
- - Storage targeting is not the purpose of this command.
-- Output format stays the same:
- - default: YAML `Settings`
- - `--json`: JSON `Settings`
-- The command should return only the resolved `Settings` object, not extra metadata fields.
- - Effective target/config-path diagnostics belong in `doctor` or other output, not in the `settings` payload itself.
-- Bare `fabro settings` should use the same server-target resolution behavior as other server-targeted commands at the time this plan lands.
- - If the resolved target is a Unix socket, it may use the normal socket/autostart path.
- - If the resolved target is an HTTP target and the server is unreachable, the command should fail clearly.
- - It should not silently fall back to `--local`.
-- The `/api/v1/settings` endpoint should return the full effective runtime `Settings` object from the server.
- - The shared merge helper remains responsible for precedence and for preserving the existing distinction between full server defaults and local-daemon-only overrides.
-
-## Implementation Changes
-### 1. CLI surface
-- Change `SettingsArgs` in [`lib/crates/fabro-cli/src/args.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/args.rs) to:
- - add `ServerTargetArgs`
- - add `--local`
- - keep optional `WORKFLOW`
- - remove `StorageDirArgs`
-- Update help text and parser tests in [`lib/crates/fabro-cli/tests/it/cmd/config.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/tests/it/cmd/config.rs) accordingly.
-
-### 2. Shared merge logic
-- Extract the server/default merge logic currently embedded in [`lib/crates/fabro-server/src/run_manifest.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/run_manifest.rs) into a shared helper in `fabro-config` that both the server and CLI can call.
-- The helper should live in `fabro-config` because both `fabro-cli` and `fabro-server` already depend on it, while `fabro-cli` should not depend on `fabro-server` merge internals.
-- The shared helper should accept:
- - the local config layers already resolved by the CLI side
- - server settings fetched from the target server
- - a mode flag matching current manifest preparation semantics
-- The helper must preserve the current distinction between:
- - normal remote/server merge behavior
- - local-daemon merge behavior
-- The helper must make the precedence explicit:
- - `fabro settings`: `project + user + server_defaults`
- - `fabro settings WORKFLOW`: `workflow + project + user + server_defaults`
- - `fabro settings --local`: `project + user`
- - `fabro settings --local WORKFLOW`: `workflow + project + user`
-- In server-targeted mode, the helper must apply `strip_server_owned_fields` to local layers (workflow, project, user) before combining with server defaults, matching `prepare_manifest_with_mode` semantics. Without this, fields like `exec` or `server` set in a local workflow config would override the server's values, which doesn't match actual run behavior.
-- The helper should continue to apply the same server-side rules that exist today:
- - normal mode uses the full `server_defaults_layer()`
- - local-daemon mode uses `local_daemon_server_overrides_layer()`
- - any required post-resolution overrides, such as forcing `storage_dir` from the active server settings, remain in the shared helper rather than being reimplemented by the CLI
-- The CLI determines the mode from the resolved `ServerTarget` type: `ServerTarget::UnixSocket` → local-daemon mode, `ServerTarget::HttpUrl` → remote mode.
-- The shared helper's scope is layer combination + resolution + post-resolution overrides. `prepare_manifest_with_mode` continues to handle manifest-specific work (parsing workflow bundles, building `args_layer` from `ManifestArgs`, applying `manifest.goal`) and delegates to the shared helper for the combine/resolve step.
-- The server should be switched to use the shared helper so `fabro settings` cannot drift from actual run semantics.
-
-### 3. Server settings source
-- Implement the real `/api/v1/settings` route in [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/server.rs), matching the existing OpenAPI contract in [`docs/api-reference/fabro-api.yaml`](/Users/bhelmkamp/p/fabro-sh/fabro/docs/api-reference/fabro-api.yaml).
-- The route should return the server’s current effective runtime settings from `AppState`, not just a raw disk parse.
-- The route should return the full runtime `Settings` object, not a reduced server-owned subset.
-- The CLI settings command should call this route when `--local` is not set.
-
-### 4. Command behavior
-- In [`lib/crates/fabro-cli/src/commands/config/mod.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/commands/config/mod.rs):
- - preserve the existing local merge path for `--local`
- - add a server-targeted path for the default behavior
-- Local-only resolution should keep the current semantics:
- - no workflow: project config from cwd + local settings
- - workflow: workflow config + project config + local settings
-- Server-targeted resolution should:
- - resolve the server target using the normal shared target-resolution helpers
- - fetch server settings from `/api/v1/settings`
- - build the same local layers the command already knows how to build
- - combine them with fetched server settings using the shared merge helper
-- If the server is unreachable:
- - Unix socket targets should follow the same socket/autostart behavior normal server-targeted commands use at the time this plan lands
- - HTTP targets should fail clearly
- - the command should not fall back to local-only mode unless the user explicitly asked for `--local`
-- For `WORKFLOW`, the command should not call `preflight` or create a run.
- - It should compute and print the resolved settings only.
-
-### 5. Separation from broader targeting cleanup
-- This plan should not block on the larger config/socket/storage refactor.
-- If the broader refactor lands first, `fabro settings` should reuse the new target-resolution helpers.
-- If it lands first, `fabro settings` should reuse the current `--server` / configured server-target behavior and keep its implementation scoped to this command.
-- This plan does not change `exec`, `system df`, `system prune`, or `store dump`.
-
-## Test Plan
-- CLI parser/help coverage in [`lib/crates/fabro-cli/tests/it/cmd/config.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/tests/it/cmd/config.rs):
- - `fabro settings --help` shows `--local` and `--server`
- - `fabro settings --local --server ...` is rejected
- - `--storage-dir` is no longer accepted
-- Local behavior tests:
- - `fabro settings --local` preserves current merged local output
- - `fabro settings --local WORKFLOW` resolves workflow + project + local settings only
-- Server-targeted behavior tests:
- - `fabro settings` fetches server settings and merges them with local config
- - `fabro settings WORKFLOW` merges workflow + project + local + server settings
- - `fabro settings --server http://...` uses the explicit target
- - socket-targeted settings resolution behaves the same way normal commands do at the time this plan lands
- - unreachable HTTP targets fail clearly and do not fall back to local-only output
-- Shared merge helper tests:
- - `prepare_manifest_with_mode()` delegates to the shared helper for the merge/defaults path
- - helper tests directly cover the layer precedence for:
- - `project + user`
- - `workflow + project + user`
- - `project + user + server_defaults`
- - `workflow + project + user + server_defaults`
- - local-daemon merge semantics remain distinct from remote-server merge semantics where that distinction already exists
- - server-owned fields in local layers (workflow, project, user) are stripped before merging in server-targeted mode, matching `prepare_manifest_with_mode` behavior
-- Server route tests:
- - real `/api/v1/settings` returns the structured settings shape from the OpenAPI contract
- - route reflects effective runtime settings, including active storage-dir/runtime overrides
-
-## Assumptions
-- Returning the raw `Settings` payload is sufficient; no new wrapper response is needed for the CLI command.
-- Reusing the existing `/api/v1/settings` contract is preferable to adding a second settings-resolution endpoint in this pass.
-- `fabro settings WORKFLOW` may perform local workflow/project discovery exactly as the command does today; the only new remote input is the selected server’s settings.
-- This pass is command-focused and does not attempt to solve all settings introspection use cases elsewhere in the API.
diff --git a/docs/plans/2026-04-06-subprocess-run-workers-signal-control-plan.md b/docs/plans/2026-04-06-subprocess-run-workers-signal-control-plan.md
deleted file mode 100644
index 8c7c00460..000000000
--- a/docs/plans/2026-04-06-subprocess-run-workers-signal-control-plan.md
+++ /dev/null
@@ -1,237 +0,0 @@
-# Subprocess Run Workers And Signal Control
-
-## Summary
-- Move workflow execution out of `fabro server` into one hidden worker subprocess per run.
-- Use Unix signals for lifecycle control, but keep the server as the sole durable writer for run events, projections, and summaries.
-- Stream canonical worker events back to the server over the worker stdout pipe so the event log, SSE, and API status stay coherent without multi-process append races.
-
-## Scope Boundaries
-In scope:
-- replace in-process run execution with supervised worker subprocesses
-- repurpose hidden `fabro __runner` into hidden `fabro __run-worker`
-- use signals for `cancel`, `pause`, and `unpause`
-- make the server the only writer to a run's durable event stream
-- define a worker spawn contract, stdout/stderr contract, and control priority rules
-- add request and effect events for run control
-- phase delivery so subprocess cancel lands before pause and procline polish
-
-Out of scope:
-- non-Unix parity for worker supervision
-- crash-time worker reattachment in the first delivery
-- changing the current public control routes away from `/runs/{id}/cancel`, `/pause`, and `/unpause`
-- changing terminal cancellation away from durable `status=failed` with `status_reason=cancelled`
-
-## Problem Frame
-The intended architecture is server-supervised subprocess workers, not server-local async tasks. The current plan also assumed both server and worker could append to the same run event stream, but the current `RunDatabase` writer is process-local: sequence allocation, event cache, and watch fanout are held in per-process memory. That makes multi-process writes and cross-process `watch_events_from()` unsafe as a foundation for this refactor.
-
-The revised plan therefore needs to solve four things explicitly:
-
-- control delivery without shared in-process primitives
-- durable event ordering without multi-process writers
-- server observation of worker state transitions
-- clear priority and override rules when multiple control requests arrive
-
-## Key Decisions
-- Hidden worker command
- - Rename hidden `fabro __runner` to hidden `fabro __run-worker`.
- - `__run-worker` executes a single run locally and does not call back into the server API.
-- Single-writer rule
- - The server is the only process that appends durable run events, updates run projections, and drives SSE.
- - The worker must not open a write-capable `RunDatabase`.
- - The worker may open the run store read-only for manifest and checkpoint reads only.
-- Worker-to-server event path
- - Worker stdout is reserved for newline-delimited canonical `RunEvent` JSON objects.
- - The worker builds canonical events once, using the existing event model, and writes them to stdout.
- - The server reads stdout, validates each event, appends it to the run store, and fans it out to SSE and any in-process listeners.
- - This replaces the current assumption that the worker writes directly to the run store.
-- Worker stderr and logs
- - Worker stderr is not part of the event stream.
- - The server captures worker stderr, writes it to a per-run log file under the run scratch directory, and mirrors lines into server tracing with the run id attached.
-- Worker spawn contract
- - The server spawns `fabro __run-worker --run-id --mode --storage-dir `.
- - If the active config path is required to reproduce local runtime behavior, pass `--config ` as well.
- - The worker does not need a server address because it does not talk HTTP to the server.
-- Control delivery
- - `cancel` sends `SIGTERM` to the worker process.
- - After the grace timeout, the server sends `SIGKILL` to the worker process group.
- - `pause` sends `SIGUSR1`.
- - `unpause` sends `SIGUSR2`.
- - Do not use `SIGSTOP` / `SIGCONT` for API pause and unpause.
-- Control priority and conflict rules
- - Priority is `cancel > pause > unpause`.
- - `pending_control` remains a single value and later accepted requests overwrite lower-priority pending requests.
- - `cancel` is accepted from `submitted`, `runnable`, `starting`, `running`, or `paused`.
- - A `cancel` request overwrites a pending `pause` or `unpause`.
- - `pause` is accepted only when observed status is `running` and `pending_control` is `null`.
- - `unpause` is accepted only when observed status is `paused` and `pending_control` is `null`.
- - A lower-priority request while a higher-priority request is pending returns `409`.
- - If `pause` is pending and `cancel` arrives before the worker reaches a safe point, the worker must skip `run.paused` and terminate through the normal cancel path.
- - If the run is already paused and `cancel` arrives, the worker must exit the pause wait and cancel immediately.
-- Signal handling in the worker
- - `SIGTERM` requests cooperative cancellation.
- - `SIGUSR1` requests cooperative pause.
- - `SIGUSR2` requests cooperative unpause.
- - Pause takes effect only at safe points such as between stages, before retry sleeps, before entering or resuming human waits, and at existing cancellation checkpoints.
-- Event naming
- - Use `run.cancel.requested`, `run.pause.requested`, and `run.unpause.requested` for accepted control requests.
- - Use `run.paused` and `run.unpaused` for observed worker transitions.
- - Keep terminal cancellation on `run.failed` with `reason=cancelled`.
- - Avoid `run.resumed` because `resume` already means resume-from-checkpoint elsewhere in the system.
-- Restart behavior in the first delivery
- - Do not attempt PID-based worker reattachment in the first delivery.
- - On graceful server shutdown, terminate active workers before exit.
- - On server startup, any non-terminal run with stale worker metadata from a prior server process is marked interrupted or terminated and its worker metadata is cleared.
- - Robust crash-time reattachment is deferred to a later phase and must include process identity verification before any signal delivery.
-- API shape
- - Keep the current control routes and verbs.
- - Extend `RunStatusResponse` with `status_reason` and `pending_control`.
- - Extend durable `StoreRunSummary` with `pending_control`.
- - Control endpoints return the current observed status plus `pending_control`; they do not report the requested action as completed until the worker emits the corresponding effect event.
-- Process titles
- - Server titles:
- - `fabro server boot`
- - `fabro server unix:/path/to/socket`
- - `fabro server tcp:127.0.0.1:3000`
- - `fabro server stopping`
- - Worker titles use the existing 12-character short run-id convention:
- - `fabro start`
- - `fabro resume`
- - `fabro init`
- - `fabro running`
- - `fabro waiting`
- - `fabro paused`
- - `fabro cancelling`
- - `fabro succeeded`
- - `fabro failed`
- - `fabro cancelled`
-
-## Delivery Plan
-### Phase 1: Subprocess execution and signal cancel
-- Spawn one worker subprocess per started run.
-- Make the server the sole event-store writer.
-- Stream canonical worker events over stdout into the server.
-- Route worker stderr into per-run log files and server tracing.
-- Implement signal-based `cancel` only.
-- Do not support crash-time worker reattachment in this phase.
-
-### Phase 2: Control request events and API status enrichment
-- Add `run.cancel.requested` and `pending_control`.
-- Extend `RunStatusResponse` and `StoreRunSummary` with `status_reason` and `pending_control`.
-- Update status projections so accepted cancel requests surface immediately without pretending the run has already terminated.
-
-### Phase 3: Pause and unpause
-- Add `SIGUSR1` and `SIGUSR2` handling.
-- Add `run.pause.requested`, `run.unpause.requested`, `run.paused`, and `run.unpaused`.
-- Implement the priority and overwrite rules defined above.
-
-### Phase 4: Procline polish and optional crash-time recovery
-- Add title helpers and short-id process titles.
-- If crash-time worker recovery is still wanted, design it as a separate pass with explicit worker identity verification before any PID-based signaling.
-
-## Implementation Changes
-### 1. Server supervision and worker pipes
-- Replace the current `tokio::spawn(execute_run(...))` path in `lib/crates/fabro-server/src/server.rs` with worker subprocess spawning.
-- Introduce a server-side supervisor record for live runs that stores:
- - observed status
- - created time
- - local error text
- - worker PID
- - worker PGID
- - worker mode (`start` or `resume`)
- - current `pending_control`
- - handles for worker stdout and stderr tasks
-- On worker spawn:
- - set process-group isolation
- - capture stdout and stderr
- - start one task that parses stdout into canonical `RunEvent`s and appends them to the run store
- - start one task that drains stderr into a per-run log file and tracing
- - set observed status to `starting`
-- On worker exit:
- - if the worker already produced a terminal run event, clear live worker metadata only
- - if no terminal run event was appended, append a terminal failure with `reason=terminated`
-
-### 2. Workflow engine event sink refactor
-- Refactor run execution so the worker path no longer depends on direct run-store writes from inside `fabro-workflow`.
-- Introduce a run-event sink abstraction used by workflow execution, retro, pull-request creation, and any remaining bypass paths that currently append directly to the run store.
-- For worker execution, the sink serializes canonical `RunEvent` JSON lines to stdout.
-- Preserve the current event-strategy rule that the canonical `RunEvent` is built exactly once and reused for all downstream sinks.
-
-### 3. Worker execution and safe-point control
-- Rewrite `lib/crates/fabro-cli/src/commands/run/runner.rs` into the `__run-worker` entrypoint that:
- - loads the run manifest and checkpoint state read-only from storage
- - executes `operations::start` or `operations::resume`
- - owns the workflow `Emitter`
- - translates OS signals into local cooperative control flags
-- At safe points:
- - if cancel is requested, terminate through the existing cancellation path
- - if pause is requested and cancel is not pending, emit `run.paused`, block until unpause or cancel, then emit `run.unpaused` when execution continues
-- Make cancel override a paused state immediately.
-
-### 4. Event model and projection updates
-- Extend `fabro-workflow` event types and `fabro-types` `EventBody` with:
- - `run.cancel.requested`
- - `run.pause.requested`
- - `run.unpause.requested`
- - `run.paused`
- - `run.unpaused`
-- Keep request events server-originated and effect events worker-originated.
-- Update `lib/crates/fabro-store/src/run_state.rs` so projections:
- - track `pending_control`
- - do not let request events overwrite observed status
- - apply `run.paused` and `run.unpaused` to observed status
- - continue projecting terminal cancellation as `status=failed` and `status_reason=cancelled`
-- Extend durable `RunSummary` with `pending_control`.
-
-### 5. API and client updates
-- Update `docs/api-reference/fabro-api.yaml` with:
- - a new `RunControlAction` schema using `cancel`, `pause`, and `unpause`
- - `pending_control` on `RunStatusResponse`
- - `status_reason` on `RunStatusResponse`
- - `pending_control` on `StoreRunSummary`
-- Define control endpoint behavior as:
- - validate whether the action is currently allowed
- - apply the priority and overwrite rules above
- - append the corresponding request event
- - update `pending_control`
- - send the signal if a live worker exists
- - return the current observed status response
-- Regenerate both generated API clients after the OpenAPI change.
-
-### 6. Process title cleanup
-- Keep using `fabro_proc::title_init()` and `fabro_proc::title_set()`.
-- Add helpers for server title updates by bind and lifecycle phase, and worker title updates by short run id and worker phase.
-- Keep procline verification lightweight; do not build brittle exact-string end-to-end assertions around process titles.
-
-## Test Plan
-- Single-writer and event-path tests
- - worker execution path opens the run store read-only only
- - worker stdout emits valid newline-delimited canonical `RunEvent` payloads
- - server appends worker-streamed events in order and SSE reflects the appended stream
- - worker stderr is captured into the per-run log file
-- Cancel tests
- - starting a runnable run spawns a worker subprocess and records PID and PGID
- - `POST /runs/{id}/cancel` appends `run.cancel.requested`, sets `pending_control=cancel`, sends `SIGTERM`, and later converges to durable `failed` with `status_reason=cancelled`
- - cancelling a submitted or runnable run reaches durable `failed/cancelled` without spawning a worker
- - an unresponsive worker is escalated from worker `SIGTERM` to process-group `SIGKILL`
-- Pause and unpause tests
- - `POST /runs/{id}/pause` on a running worker appends `run.pause.requested`, sets `pending_control=pause`, and later projects `paused`
- - `POST /runs/{id}/unpause` on a paused worker appends `run.unpause.requested`, sets `pending_control=unpause`, and later projects `running`
- - pause followed by cancel before a safe point never produces `run.paused`
- - cancel while paused exits the pause wait and converges to durable `failed/cancelled`
- - lower-priority actions while a higher-priority action is pending return `409` and append no request event
-- Startup behavior tests
- - graceful server shutdown terminates active workers
- - startup clears stale worker metadata and marks prior non-terminal runs interrupted or terminated
-- Verification commands
- - `cargo nextest run -p fabro-server`
- - `cargo nextest run -p fabro-workflow`
- - `cargo nextest run -p fabro-store`
- - `cargo nextest run -p fabro-cli`
- - `cargo fmt --check --all`
- - `cargo clippy --workspace -- -D warnings`
-
-## Assumptions
-- This refactor is Unix-first and may explicitly reject or defer non-Unix worker supervision behavior.
-- The first delivery optimizes for correct subprocess supervision and durable event ordering, not crash-time worker survival across server restarts.
-- `pause` and `unpause` are cooperative safe-point transitions, not immediate OS-level stop and continue.
-- The short run id remains the first 12 characters of the ULID, matching current CLI presentation.
diff --git a/docs/plans/2026-04-07-fix-attach-terminal-authoritative-stream-plan.md b/docs/plans/2026-04-07-fix-attach-terminal-authoritative-stream-plan.md
deleted file mode 100644
index a319307c8..000000000
--- a/docs/plans/2026-04-07-fix-attach-terminal-authoritative-stream-plan.md
+++ /dev/null
@@ -1,204 +0,0 @@
----
-title: "fix: make attach streams terminal-authoritative"
-type: fix
-status: active
-date: 2026-04-07
----
-
-# fix: make attach streams terminal-authoritative
-
-## Overview
-
-Remove `ATTACH_FINAL_STATUS_GRACE` by making `GET /api/v1/runs/{id}/attach` the authoritative source of terminal completion for `fabro attach`.
-
-After this change:
-
-- the server streams ordered events starting at `since_seq`
-- if a terminal event is reached, the server emits it and closes the stream immediately
-- the CLI exits as soon as it sees `run.completed` or `run.failed`
-- the CLI no longer waits for quiet time or polls run state after attach completes
-
-## Problem Frame
-
-Current behavior is split across the server and CLI in a way that creates a completion race:
-
-- the server treats `/attach` as a live-only event tail and returns `410 Gone` when the run is no longer live
-- the CLI lists historical events first, then opens `/attach?since_seq=next_seq`
-- if the run finishes between those two steps, the CLI can miss the terminal event and has to rely on `ATTACH_FINAL_STATUS_GRACE`
-- even when the CLI does receive a terminal event, the server-side live stream does not close on that event, so the CLI waits for a grace period before deciding the stream is done
-
-The desired contract is simpler: `attach` should trust the stream. If the stream ends before a terminal event, that is an error, not a case for client-side repair logic.
-
-## Requirements Trace
-
-- R1. `GET /api/v1/runs/{id}/attach` must serve ordered events beginning at `since_seq`, whether the run is still live or already terminal.
-- R2. If the stream reaches `run.completed` or `run.failed`, the server must emit that event and close the stream immediately.
-- R3. `fabro attach` must derive completion and exit status from streamed events, not from grace periods or follow-up state polling.
-- R4. `GET /api/v1/runs/{id}/attach` must stop returning `410 Gone` for completed runs.
-- R5. The existing bare-attach API behavior when `since_seq` is omitted remains unchanged: the endpoint starts at the current tail, so attaching after a completed run with no unread events may produce an empty stream that closes immediately.
-- R6. The CLI must not interpret R5 as a protocol success path. `fabro attach` still short-circuits terminal runs via its initial state-and-history replay, so its premature-EOF error handling applies only to the live-stream path entered after the initial terminal check.
-- R7. The run-specific SSE attach stream must send keepalives during idle periods so long-running quiet stages do not surface as transport EOFs.
-- R8. Interview handling and Ctrl-C detach behavior remain unchanged.
-
-## Key Technical Decisions
-
-- The server owns the completion contract.
- The CLI stays simple and exits immediately on terminal events.
-
-- Premature EOF is a protocol error.
- If the live attach stream ends before a terminal event is observed, `fabro attach` exits non-zero with a clear error instead of performing a repair lookup. This does not conflict with R5 because the CLI does not enter the live-stream path for already-terminal runs.
-
-- `/attach` becomes replay-capable for completed runs.
- The endpoint no longer uses “run is live” as a gate for whether unread events can be served.
-
-- No new durable storage primitive is required, but the live-watch helper must be hardened.
- `open_run_reader()` already returns the shared active `RunDatabase` for live runs, but the current `watch_events_from()` handoff is not strong enough for this contract because it snapshots recent events before subscribing. The implementation must make the replay-to-watch transition seq-complete.
-
-- Keepalive is in scope for run-specific attach.
- The new fail-fast EOF contract is only acceptable if the run-specific SSE stream gets the same idle keepalive treatment as the existing global attach endpoint.
-
-## Public API / Interface Changes
-
-- Update `docs/api-reference/fabro-api.yaml` for `GET /api/v1/runs/{id}/attach`:
- - change the description from “live run” SSE to “ordered event stream starting at `since_seq`, replaying persisted events and continuing with live updates while the run remains active”
- - remove the `410 Run is not live on this server` response
-
-- Regenerate generated clients after the spec update:
- - `cargo build -p fabro-api`
- - `cd lib/packages/fabro-api-client && bun run generate`
-
-- Remove the CLI’s `RunAttachStreamError::Gone` branch from the Rust server client.
-
-## Implementation Units
-
-### [ ] Unit 1: Make server attach replay terminal-safe
-
-**Goal**
-
-Change the server attach endpoint so it can always deliver unread terminal events and self-close on terminal completion.
-
-**Files**
-
-- `lib/crates/fabro-server/src/server.rs`
-- `lib/crates/fabro-store/src/slate/run_store.rs`
-- `docs/api-reference/fabro-api.yaml`
-
-**Approach**
-
-- Replace the current “live run only” guard in `attach_run_events()`.
-- Open the run reader first and return `404` only when the run truly does not exist.
-- Compute `start_seq` exactly as today.
-- Replay persisted events from `start_seq` using `list_events_from_with_limit` in bounded batches, converting them through the existing `sse_event_from_store()` helper.
-- Detect terminal events during replay. If replay emits `run.completed` or `run.failed`, close the SSE stream immediately after that event.
-- Before using live watch for attach, harden `watch_events_from()` so it is seq-complete for handoff:
- - subscribe to `event_tx` before snapshotting `recent_events`
- - snapshot and emit cached events at or after the requested seq
- - then drain broadcast events, discarding any seq lower than the next expected seq
- This closes the snapshot-to-subscribe gap that exists in the current helper.
-- If replay reaches the current tail without hitting a terminal event and the run is still active, switch to the hardened `watch_events_from(next_seq)` on the shared `RunDatabase`.
-- In the live phase, stream events until the first terminal event, then close immediately.
-- Add `.keep_alive(KeepAlive::default())` to the run-specific SSE response so idle stages do not turn into transport EOFs.
-
-**Patterns to follow**
-
-- Existing event serialization helpers in `lib/crates/fabro-server/src/server.rs`
-- Existing event listing behavior in `list_run_events()`
-- Global attach keepalive behavior in `lib/crates/fabro-server/src/server.rs`
-- Updated `watch_events_from()` semantics in `lib/crates/fabro-store/src/slate/run_store.rs`
-
-**Test scenarios**
-
-- Attach to a live run and confirm the stream includes stage events, then a terminal event, then EOF.
-- Attach after the run has already completed with `since_seq` before the terminal event and confirm replay includes the terminal event, then EOF.
-- Attach after completion with `since_seq` after the last event and confirm the stream returns `200` and closes cleanly with no events.
-- Attach during the race where the run completes after the client reads history but before it opens `/attach`, and confirm the terminal event is still delivered.
- Use a barrier or oneshot to hold terminal completion until after the history read returns and release it before the `/attach` request starts, so the race is deterministic rather than sleep-based.
-- Attach to a nonexistent run and confirm `404` remains unchanged.
-- Attach to a run with a deliberately quiet stage and confirm the SSE response stays open via keepalive until later events arrive.
-
-**Verification**
-
-- Server tests prove `200` is returned for completed runs with unread events.
-- Server tests prove the stream terminates immediately after a terminal event.
-
-### [ ] Unit 2: Simplify CLI attach around terminal events
-
-**Goal**
-
-Remove timer-based completion handling from `fabro attach` and make the command trust streamed terminal events.
-
-**Files**
-
-- `lib/crates/fabro-cli/src/commands/run/attach.rs`
-- `lib/crates/fabro-cli/src/server_client.rs`
-
-**Approach**
-
-- Delete `ATTACH_FINAL_STATUS_GRACE`.
-- Delete `determine_exit_code_with_server()`.
-- Remove `RunAttachStreamError::Gone` and its special handling.
-- Keep the initial replay path: if the initial event list or run state already shows the run is terminal, replay and exit as today.
-- In the live attach path, emit events and return immediately when `event_exit_code()` sees `run.completed` or `run.failed`.
-- If the live attach stream ends before a terminal event is observed, return a non-zero protocol error instead of polling server state.
-- Document in code that this EOF rule applies only after the command has already ruled out the R5 completed-run replay case via the initial terminal check.
-- Leave interview prompting and Ctrl-C behavior unchanged.
-
-**Patterns to follow**
-
-- Existing `event_exit_code()` extraction in `lib/crates/fabro-cli/src/commands/run/attach.rs`
-- Existing replay behavior in `replay_run_with_client()`
-
-**Test scenarios**
-
-- Successful attach on a live run exits `0` immediately after `run.completed`.
-- Failed attach on a live run exits `1` immediately after `run.failed`.
-- Completed run replay still exits with the correct code without opening a live stream.
-- Premature EOF before any terminal event produces a non-zero exit and clear error text.
-
-**Verification**
-
-- CLI tests no longer depend on grace-period timing.
-- No attach code path polls run state after a live stream finishes.
-
-### [ ] Unit 3: Align tests, demo behavior, and generated API artifacts
-
-**Goal**
-
-Update repo expectations so they match the new terminal-authoritative attach contract.
-
-**Files**
-
-- `lib/crates/fabro-server/tests/it/scenario/run_completion.rs`
-- `lib/crates/fabro-server/tests/it/scenario/sse.rs`
-- `lib/crates/fabro-cli/tests/it/cmd/attach.rs`
-- `lib/crates/fabro-server/src/demo/mod.rs`
-- generated Rust and TypeScript API artifacts
-
-**Approach**
-
-- Replace current `200 or 410` attach assertions with `200`-only expectations where applicable.
-- Update the server unit/integration test near the current `StatusCode::GONE` assertion to verify replay-and-close semantics instead.
-- Update the demo attach stub to return a short SSE response that ends cleanly, rather than `410`.
-- Regenerate Rust and TypeScript clients after the OpenAPI change.
-
-**Test scenarios**
-
-- Server scenario tests verify completed-run attach no longer returns `410`.
-- CLI mock-server attach tests verify the command exits from streamed terminal events rather than fallback logic.
-- Demo-mode attach still behaves coherently for callers expecting an attach response.
-
-**Verification**
-
-- Spec, generated clients, and tests all describe the same `attach` contract.
-
-## Test Plan
-
-- `cargo nextest run -p fabro-server`
-- `cargo nextest run -p fabro-cli`
-- Target the attach-specific server and CLI tests first while iterating, then run the crate suites before landing.
-
-## Assumptions
-
-- `fabro logs` and `FOLLOW_TERMINAL_GRACE` are out of scope for this change.
-- Every valid terminal run should emit a persisted terminal event (`run.completed` or `run.failed`); any gap found during implementation should be treated as a server bug to fix, not a reason to reintroduce client grace timing.
-- The user preference for attach simplicity is authoritative: premature EOF is an error, not a repairable condition.
diff --git a/docs/plans/2026-04-07-global-cas-blob-refs-plan.md b/docs/plans/2026-04-07-global-cas-blob-refs-plan.md
deleted file mode 100644
index 417a0f2e8..000000000
--- a/docs/plans/2026-04-07-global-cas-blob-refs-plan.md
+++ /dev/null
@@ -1,209 +0,0 @@
-# Global CAS Blob Refs Plan
-
-## Summary
-
-Replace durable offload pointers with global content-addressed blob refs and keep file paths as an execution-only concern.
-
-- Automatic large-value offload should persist `blob://sha256/` refs instead of `file://...` paths.
-- Blob bytes should be stored in a global CAS namespace rather than under per-run keys.
-- Handlers and preamble generation should continue to see file references, but those files should be materialized only in the execution-local environment.
-- Host scratch blob cache files should stop being part of the durable contract.
-- Garbage collection is explicitly deferred in this pass.
-
-## Problem Frame
-
-Large context values are currently offloaded by writing the serialized JSON bytes to the run store, materializing a host-side cache file, and replacing the original value with a `file://` pointer to that file.
-
-That shape creates the wrong durable boundary:
-
-- persisted checkpoints and checkpoint-completed events contain host- or sandbox-specific file paths instead of stable storage references
-- resume seeds those path strings back into runtime state verbatim
-- remote sandbox sync rewrites durable context into sandbox-local `file://` paths
-- fork semantics are awkward because the same logical content becomes tied to a specific run and a specific materialized file path
-
-The durable source of truth should be the blob bytes addressed by content hash. File paths should only exist as a temporary execution detail for agents and command handlers.
-
-## Key Decisions
-
-- Use `blob://sha256/` as the only new durable blob reference format.
- - `RunBlobId` remains the existing SHA-256 hex content hash type in this pass.
- - Durable run state, checkpoints, and checkpoint-completed event payloads should persist only plain JSON values and `blob://` refs.
-
-- Make blob storage global CAS instead of run-scoped.
- - Internally, blob bytes move from per-run keys to global keys such as `blobs#sha256#`.
- - Existing run-scoped server endpoints can remain as the API surface for now, but they should read and write the global CAS store under the hood.
-
-- Keep blob handling invisible to the model.
- - The model should continue to receive file references in prompts and preambles.
- - `blob://` is a backend durability protocol, not a model-facing protocol.
-
-- Materialize blobs only in execution-local views.
- - Before handler execution and before preamble construction, resolve `blob://` refs into local files for the active sandbox.
- - For remote sandboxes, materialize under `{working_directory}/.fabro/blobs/.json`.
- - For local execution, materialize under a run-local ephemeral runtime directory such as `runtime/blobs/.json`.
-
-- Do not persist execution-local `file://` refs back into durable state.
- - Managed materialized blob file refs must be normalized back to `blob://sha256/` before context snapshots are emitted or checkpointed.
-
-- Preserve compatibility with older runs.
- - Read paths should continue to recognize legacy blob-backed `file://.../.json` values.
- - New writes should use only the `blob://` form.
-
-- Leave stage artifacts unchanged.
- - This change applies only to offloaded run blobs.
- - `ArtifactStore` remains the durable system for captured stage artifacts.
-
-- Defer GC.
- - New blob writes are append-only in this pass.
- - No mark-and-sweep, refcounting, or retention enforcement is included here.
-
-## Implementation Changes
-
-### 1. Blob Storage And Blob Ref Helpers
-
-- Keep `RunBlobId` unchanged in `lib/crates/fabro-types/src/run_blob_id.rs`.
-- Add a shared blob-ref helper module in `fabro-workflow` or `fabro-types` that:
- - formats `blob://sha256/`
- - parses `blob://sha256/`
- - recognizes legacy blob-backed `file://.../.json`
- - extracts blob ids from managed materialized blob file paths
-- Change `fabro-store` blob key construction from `blobs#{run_id}#{blob_id}` to a global key layout such as `blobs#sha256#`.
-- Update `RunDatabase::write_blob` and `RunDatabase::read_blob` to operate on the global CAS namespace.
-- Remove blob enumeration from the main architecture path. `list_blobs` should not be part of new feature work; if retained temporarily, it should be treated as legacy/debug-only.
-
-### 2. Automatic Offload
-
-- In `lib/crates/fabro-workflow/src/artifact.rs`, change `offload_large_values` so that it:
- - serializes the JSON value
- - writes the bytes to CAS through the existing run-store handle
- - replaces the value with `blob://sha256/`
- - does not write a host-side cache file
-- Remove the current assumption that `cache/artifacts/values/{blob_id}.json` is part of the durable contract.
-- Keep the offload threshold unchanged at 100KB in this pass.
-
-### 3. Execution-Time Materialization
-
-- Replace `sync_artifacts_to_env` with an execution-time blob materialization flow that handles both:
- - new `blob://` refs
- - existing explicit or legacy `file://` refs
-- Split this into two responsibilities:
- - blob resolution and materialization for managed blob refs
- - existing file-copy behavior for explicit `file://` refs that are not blob-backed
-- Materialization behavior:
- - read the blob bytes from CAS
- - write the JSON bytes into a sandbox-usable file path
- - return a rewritten execution-local value using `file://`
-- Managed materialized paths should use a deterministic layout based on blob id so repeated refs dedupe naturally within an execution.
-
-### 4. Context And Durable Snapshot Boundaries
-
-- Introduce a clear split between:
- - durable context values
- - execution-local resolved context values
-- Before handler execution, create a resolved execution view where `blob://` refs are rewritten to materialized `file://` refs.
-- After handler execution, normalize any managed materialized blob file refs in handler-produced context changes back to `blob://sha256/`.
-- Compatibility reads should normalize legacy blob-backed `file://.../.json` values to `blob://sha256/` in memory before they enter new durable snapshots.
-- Update checkpoint creation and checkpoint-completed event emission so they snapshot only durable values, never execution-local materialized paths.
-- Treat `current.preamble` as runtime-only derived state and exclude it from persisted context snapshots. This prevents preamble strings containing execution-local file paths from leaking into checkpoints or event payloads.
-
-### 5. Preamble And Handler Execution
-
-- Keep blobs invisible to the model.
-- Before fidelity builds `current.preamble`, resolve completed-stage outcome values and current context into an execution-local view that contains file refs, not blob refs.
-- `build_preamble` should continue to work with file references and should not mention `blob://` or “blobs” in user/model-facing output.
-- Prompt and agent handlers should continue to consume `context.preamble()` and file references exactly as they do now.
-- The only new behavior for handlers should be that the file refs they receive come from execution-time materialization rather than from durable checkpoint state.
-
-### 6. Resume And Fork Behavior
-
-- Resume should seed durable `blob://` values from checkpoint state and let the next execution hop materialize them as needed.
-- Legacy checkpoints containing blob-backed `file://.../.json` values should be normalized on read so resumed runs persist the new `blob://` form on the next checkpoint.
-- Fork should copy checkpoint and run state without copying blob payloads.
-- Child runs should retain the same `blob://sha256/` refs as the source run.
-
-### 7. CLI And Export Behavior
-
-- Update CLI final-output rendering so when `response.*` is a blob ref it resolves the blob through the run-store read path before printing markdown.
-- Keep explicit non-blob file refs as plain file references in CLI output.
-- Refactor `store dump` to become reference-driven for blobs:
- - scan exported JSON structures for blob refs
- - fetch only referenced blobs
- - hydrate them inline in exported JSON
- - stop emitting a top-level `blobs/` directory
-- Preserve the current export layout for run metadata, nodes, retro output, checkpoints, events, and stage artifacts.
-
-### 8. Server And API Surface
-
-- Keep the existing run-scoped blob routes:
- - `POST /api/v1/runs/{id}/blobs`
- - `GET /api/v1/runs/{id}/blobs/{blobId}`
-- Change their implementation to use global CAS storage internally.
-- Do not add public blob enumeration or global blob-fetch routes in this pass.
-- Do not add GC or blob-membership verification to the API contract in this pass.
-
-## Test Plan
-
-### Blob Ref Helpers
-
-- parse and format `blob://sha256/`
-- recognize legacy blob-backed `file://.../.json`
-- reject ordinary non-blob `file://` refs
-- normalize managed materialized blob file refs back to blob refs
-
-### Offload And Persistence
-
-- large values are replaced with `blob://sha256/`
-- offload writes the blob bytes to CAS
-- offload no longer creates a host scratch cache file
-- small values remain inline
-- checkpoint and checkpoint-completed payloads persist `blob://` refs, not `file://`
-- `current.preamble` is excluded from persisted context snapshots
-
-### Execution Materialization
-
-- local execution materializes `blob://` refs to local runtime files
-- remote execution materializes `blob://` refs to sandbox files under `.fabro/blobs/`
-- preamble generation receives file refs and does not expose `blob://`
-- handlers receive file refs and can read them normally
-- explicit non-blob `file://` refs keep their existing remote-copy behavior
-
-### Normalization And Compatibility
-
-- handler-produced managed materialized blob file refs are normalized back to `blob://` before checkpointing
-- legacy blob-backed `file://.../.json` values are normalized to `blob://` on resume
-- ordinary explicit `file://` refs are preserved as file refs
-- resumed runs re-checkpoint using only the new `blob://` form
-
-### Fork, CLI, And Export
-
-- forked runs reuse the same `blob://sha256/` refs with no blob copy
-- CLI final-output rendering resolves blob-backed final responses
-- `store dump` hydrates referenced blobs inline
-- `store dump` emits no top-level `blobs/` directory
-
-## Important Files
-
-- `lib/crates/fabro-workflow/src/artifact.rs`
-- `lib/crates/fabro-workflow/src/lifecycle/artifact.rs`
-- `lib/crates/fabro-workflow/src/lifecycle/fidelity.rs`
-- `lib/crates/fabro-workflow/src/node_handler.rs`
-- `lib/crates/fabro-workflow/src/handler/llm/preamble.rs`
-- `lib/crates/fabro-workflow/src/pipeline/execute.rs`
-- `lib/crates/fabro-workflow/src/records/checkpoint.rs`
-- `lib/crates/fabro-workflow/src/lifecycle/event.rs`
-- `lib/crates/fabro-store/src/keys.rs`
-- `lib/crates/fabro-store/src/slate/run_store.rs`
-- `lib/crates/fabro-server/src/server.rs`
-- `lib/crates/fabro-cli/src/server_client.rs`
-- `lib/crates/fabro-cli/src/commands/run/output.rs`
-- `lib/crates/fabro-workflow/src/run_dump.rs`
-- `docs/execution/context.mdx`
-- `docs/agents/outputs.mdx`
-
-## Assumptions And Defaults
-
-- The durable blob ref format for this pass is `blob://sha256/`.
-- `RunBlobId` remains the current type name even though blobs are no longer run-scoped.
-- Global CAS uses the existing durable key-value store rather than introducing a new blob backend.
-- Existing run-scoped blob HTTP routes remain the only supported transport surface in this pass.
-- Blob lifecycle management and GC are explicitly deferred.
diff --git a/docs/plans/2026-04-07-interview-control-channel-and-server-slack-plan.md b/docs/plans/2026-04-07-interview-control-channel-and-server-slack-plan.md
deleted file mode 100644
index b83494c22..000000000
--- a/docs/plans/2026-04-07-interview-control-channel-and-server-slack-plan.md
+++ /dev/null
@@ -1,390 +0,0 @@
----
-title: "feat: unify interview handling around projected questions, worker stdin, and server-owned Slack"
-type: feat
-status: active
-date: 2026-04-07
----
-
-# feat: unify interview handling around projected questions, worker stdin, and server-owned Slack
-
-## Overview
-
-Replace the current split interview architecture with one canonical model:
-
-- pending interviews live in the durable run projection
-- answers enter through the server
-- active runs receive accepted answers through a live control sink
-- Slack becomes a server-owned delivery surface, not a special in-memory interviewer path
-
-This refactor removes `FileInterviewer` and `WebInterviewer`, keeps the existing HTTP question and answer routes as the canonical external contract, and uses worker `stdin` JSONL for server-to-worker answer delivery.
-
-## Problem Frame
-
-Interview handling is currently split across two transport-specific implementations:
-
-- subprocess runs use `FileInterviewer`, with `interview_request.json` and `interview_response.json` scratch files
-- the in-process server override path uses `WebInterviewer`, with pending questions and answer waiters held only in memory
-
-That split leaks into the server:
-
-- `GET /runs/{id}/questions` branches between `WebInterviewer.pending_questions()` and the request scratch file
-- `POST /runs/{id}/questions/{qid}/answer` branches between `WebInterviewer.submit_answer()` and the response scratch file
-- Slack is built on the same special `WebInterviewer` path instead of the canonical server question API
-
-The result is one feature implemented twice, with two incompatible sources of truth for pending questions and two different answer delivery mechanisms.
-
-The desired architecture is simpler:
-
-- the durable run event stream and run projection are authoritative for pending interviews
-- the server owns answer validation and first-answer-wins behavior
-- subprocess workers receive accepted answers over `stdin`, which also establishes the future control plane for steering
-- Slack is just another server-owned client of the canonical answer path
-
-## Scope Boundaries
-
-In scope:
-
-- add stable question ids and persist pending interviews in the run projection
-- replace scratch-file answer transport with worker `stdin` JSONL
-- replace `WebInterviewer` with the same brokered answer model used by subprocess runs
-- move Slack onto a single global Socket Mode listener inside `fabro-server`
-- keep the existing HTTP question and answer routes as the canonical external API
-- expand the question API payload to expose the information needed by CLI and Slack
-
-Out of scope:
-
-- worker-side steering behavior beyond reserving the `stdin` protocol shape for it
-- server restart rehydration of Slack delivery state
-- a separate Slack bridge process
-- signed Slack tokens or tamper-evident action payloads
-- any new public answer route or worker-side HTTP contract
-
-## Requirements Trace
-
-- R1. Pending interview state must be derived from durable run events and exposed from the run projection, not from scratch files or live interviewer objects.
-- R2. Every interview question must have a stable `question_id` that survives through events, HTTP APIs, Slack payloads, and worker answer delivery.
-- R3. `GET /runs/{id}/questions` must read only from canonical projected pending interview state.
-- R4. `POST /runs/{id}/questions/{qid}/answer` must remain the canonical answer ingress for web, CLI, and Slack.
-- R5. For subprocess runs, the server must deliver accepted answers to the worker over `stdin` as versioned JSONL.
-- R6. For the in-process `registry_factory_override` path, the server must still support interview-driven tests without `WebInterviewer`.
-- R7. `FileInterviewer` and `WebInterviewer` must be removed from production use and then deleted.
-- R8. Slack must be owned by `fabro-server` as a single global Socket Mode listener, not by per-run workers and not by a separate bridge process.
-- R9. Slack delivery state may be memory-only. After server restart, stale Slack prompts may be ignored and resumed runs may post fresh prompts under the new server config.
-- R10. Slack payloads must carry `run_id` and `qid`, and Slack answers must route through the same canonical server answer handler as HTTP.
-- R11. Multiple-choice and multi-select answers must remain structured end-to-end and must not be flattened to text in the Slack path.
-- R12. Accepted answers must use first-answer-wins semantics across concurrent HTTP and Slack submissions.
-
-## Key Decisions
-
-- `Question` gains a first-class `id: String`.
- - Generate it in the human handler as a ULID string.
- - Do not hide it in `metadata`.
- - Do not add a new `QuestionId` wrapper type in this pass.
-
-- `interview.started` becomes the authoritative pending-question event.
- - Keep `question` as the human-readable text field.
- - Add `question_id`, `stage`, `question_type`, `options`, `allow_freeform`, `timeout_seconds`, and `context_display`.
-
-- `interview.completed` and `interview.timeout` gain `question_id`.
-
-- Add `interview.interrupted`.
- - Carry `question_id`, `question`, `stage`, `reason`, and `duration_ms`.
- - Use it when the interviewer returns `Interrupted`, while `Skipped` flows through `interview.completed`, so pending interview cleanup stays event-driven.
-
-- `RunProjection` becomes the only source of truth for pending interviews.
- - Add `pending_interviews: BTreeMap`.
- - Insert on `interview.started`.
- - Remove on `interview.completed`, `interview.timeout`, `interview.interrupted`, `run.rewound`, and terminal run events.
-
-- Keep the existing answer route contract.
- - `GET /runs/{id}/questions` and `POST /runs/{id}/questions/{qid}/answer` remain the public surface.
- - `SubmitAnswerRequest` already supports freeform, single-select, and multi-select and does not need to change.
- - Expand `ApiQuestion` with `stage`, `timeout_seconds`, and `context_display`.
-
-- Server-to-worker answer delivery uses `stdin` JSONL, versioned from day one.
- - Use one JSON object per line.
- - Implement only `interview.answer` in this pass.
- - Reserve the envelope for future steering, but do not implement steering behavior yet.
-
-- Use a broker-backed interviewer abstraction for both runtime paths.
- - Replace `FileInterviewer` and `WebInterviewer` with an internal `InterviewBroker` plus `ControlInterviewer`.
- - For subprocess runs, the broker is fed by parsed `stdin` control messages.
- - For the in-process override path, the broker is fed directly by the server’s canonical answer submission service.
-
-- Slack is a server-owned delivery surface, not a worker concern.
- - Start one Socket Mode listener inside `fabro-server` when both Slack tokens and `slack.default_channel` are configured.
- - Have that service consume the server's existing global run-event broadcast, the same fanout fed by `forward_run_events_to_global(...)` for both subprocess and in-process runs.
- - Do not read from SSE endpoints or introduce a second event source.
- - Keep Slack message metadata and thread routing in server memory only.
- - Do not replay or restore Slack posts after restart.
-
-- Slack action payloads use plain JSON in `value`.
- - Carry at least `run_id`, `qid`, and answer metadata.
- - Keep `action_id` structural rather than encoding identifiers into it.
- - Validate all incoming Slack answers against the current projected pending interview before accepting them.
-
-- `ControlInterviewer` is the runtime `Interviewer` implementation.
- - `inform()` remains a no-op.
- - `ask_multiple()` continues to use the trait default, so multiple concurrent `ask()` calls must work correctly when keyed by `qid`.
-
-- `InterviewBroker` owns only live waiter state.
- - It does not own canonical pending-question state; `RunProjection.pending_interviews` does.
- - Its server/transport injection surface is `submit(qid, answer) -> Result<(), SubmitError>`.
- - Unknown, already-resolved, or duplicate `qid`s are rejected by the broker.
-
-- Event replay must stay backward compatible.
- - New interview event fields must deserialize with defaults so old `progress.jsonl` entries still replay.
- - Historical `interview.started` events that lack `question_id` must not populate `pending_interviews`.
- - Historical runs continue to replay normally, but projection-backed pending interview reconstruction is only guaranteed for runs created after this change.
-
-- The old file-claim reattach window is intentionally removed.
- - Client detach and reattach no longer matter because the pending question is durable in the projection and can be fetched again later.
- - Only loss of the live server-worker control channel is treated as fatal for the waiting interview.
-
-- First-answer-wins is enforced in memory before transport delivery.
- - Projection lookup proves the question is still pending.
- - A per-run acceptance guard must then claim `qid` exactly once before any answer is sent to the worker.
- - If transport delivery fails, that claim is released so a later submission can retry.
- - If transport delivery succeeds, the claim stays until the interview lifecycle event clears the pending question.
-
-## Recommended Delivery Order
-
-Recommended sequencing:
-
-- Phase A: steps 1 and 2 together
- - lock the question id, event shape, replay compatibility, projection model, and API question shape first
-
-- Phase B: steps 3, 4, and 5 together
- - implement `InterviewBroker`, `ControlInterviewer`, canonical answer submission, subprocess `stdin` transport, in-process override migration, and CLI attach adjustments in one pass
- - steps 3 and 4 should land together because they both restructure the live answer transport in `server.rs`
-
-- Phase C: step 6
- - migrate Slack after the canonical pending-question model and answer submission path are stable
-
-- Phase D: step 7
- - remove dead implementations, examples, and outdated docs only after the new path is covered by tests
-
-Parallelizable work after Phase A is in place:
-
-- worker-side `ControlInterviewer` and JSONL parsing
-- CLI `ApiQuestion` conversion updates
-- Slack payload and parsing refactor
-
-## Implementation Changes
-
-### 1. Canonical question ids and interview events
-
-Update the workflow and event model so the pending interview can be reconstructed without a live transport object.
-
-- Modify `lib/crates/fabro-interview/src/lib.rs`:
- - add `Question.id`
- - keep `metadata` and `default` as internal-only fields
- - export the new broker-backed interviewer implementation
-
-- Modify `lib/crates/fabro-workflow/src/handler/human.rs`:
- - generate `question.id`
- - emit the richer `interview.started`
- - emit `interview.interrupted` for `Interrupted`
- - emit `interview.completed` for `Skipped`
- - emit `question_id` on `interview.completed` and `interview.timeout`
-
-- Modify `lib/crates/fabro-workflow/src/event.rs` and `lib/crates/fabro-types/src/run_event/misc.rs`:
- - extend the interview event variants and payload props to carry the full pending-question surface
- - keep event names stable except for adding `interview.interrupted`
-
-### 2. Run projection and API question surface
-
-Update the store projection and public question API to surface the canonical pending interview state.
-
-- Modify `lib/crates/fabro-store/src/run_state.rs`:
- - add `pending_interviews`
- - add `PendingInterviewRecord`
- - apply insert and cleanup rules for all interview lifecycle events
-
-- Modify `docs/api-reference/fabro-api.yaml`:
- - expand `ApiQuestion` with `stage`, `timeout_seconds`, and `context_display`
- - leave `SubmitAnswerRequest` unchanged
-
-- Regenerate generated API clients:
- - Rust via `cargo build -p fabro-api`
- - TypeScript via `cd lib/packages/fabro-api-client && bun run generate`
-
-### 3. Replace file transport with worker `stdin` JSONL
-
-Replace scratch-file answer delivery with a live control channel into the worker.
-
-- Add `InterviewBroker` and `ControlInterviewer` in `lib/crates/fabro-interview/src/lib.rs` and supporting modules:
- - `ControlInterviewer` implements `Interviewer`
- - `ControlInterviewer::ask(question)` registers a oneshot waiter under `question.id` and awaits broker delivery
- - `InterviewBroker` owns only live waiter state, such as `HashMap>`
- - `InterviewBroker::submit(qid, answer)` resolves a waiter exactly once and returns a typed error for unknown or already-resolved questions
- - `inform()` remains a no-op
- - `ask_multiple()` continues to use the trait default and is supported by allowing concurrent per-`qid` waiters
-
-- Modify `lib/crates/fabro-server/src/server.rs`:
- - spawn workers with `stdin(Stdio::piped())`
- - store a per-run live answer transport instead of a `WebInterviewer`
- - use a bounded per-run `mpsc::Sender` feeding a dedicated JSONL pump into worker stdin
- - enqueue control messages with a short timeout; if enqueue times out or the channel is closed, clear any acceptance claim and return a transient server error rather than hanging the request
- - run a JSONL pump that writes accepted answers into the worker stdin pipe
- - replace the current `get_questions` and `submit_answer` branches with one projection-backed question query plus one internal answer-submission service
- - implement canonical answer submission in this order:
- - load the pending question from the projection
- - validate and build the `Answer`
- - acquire the per-run acceptance guard and claim `qid` exactly once
- - submit the answer to the live transport
- - release the claim on transport failure
- - keep the claim until interview completion, timeout, or abort clears the pending question
- - reject a second concurrent submission with `409` once the acceptance guard says the question was already claimed
-
-- Modify `lib/crates/fabro-cli/src/commands/run/runner.rs`:
- - replace `FileInterviewer` with `ControlInterviewer`
- - start a `stdin` reader task that parses versioned JSONL `WorkerControl` messages
- - resolve broker waiters by `qid`
- - treat unexpected control-channel closure as interviewer abort/failure rather than hanging forever
- - keep a dedicated stdin reader task running for the life of the worker so answer messages do not block behind unrelated stage execution
-
-- Define a wire-specific answer payload.
- - Do not serialize internal `Answer` directly on the wire.
- - Use an explicit `kind` shape such as `yes`, `no`, `text`, `selected`, and `multi_selected`.
-
-- Remove scratch-file interview transport.
- - delete the request and response file helpers from the server
- - stop creating or reading `interview_request.json` and `interview_response.json` for server-managed runs
- - intentionally remove the old claim-file reattach window because pending questions are now projection-backed and re-fetchable after client reconnect
-
-### 4. Replace `WebInterviewer` in the in-process override path
-
-Keep the test override path, but move it onto the same architecture as subprocess runs.
-
-- Modify `lib/crates/fabro-server/src/server.rs`:
- - replace `ManagedRun.interviewer` with a live answer transport enum such as:
- - subprocess `stdin` control sender
- - in-process broker handle
- - keep `create_app_state_with_registry_factory(...)` and `execute_run_in_process(...)`
- - pass a broker-backed `Arc` into the override registry instead of `WebInterviewer`
-
-- Keep the external behavior unchanged for tests.
- - `GET /runs/{id}/questions` still lists pending questions
- - `POST /runs/{id}/questions/{qid}/answer` still satisfies waiting in-process interview gates
- - the difference is that both now go through the projection and canonical submission service
-
-### 5. Keep CLI attach on the canonical server question path
-
-Do not make attach parse the event payload into the prompt directly in this pass.
-
-- Keep `lib/crates/fabro-cli/src/commands/run/attach.rs` event-driven behavior:
- - `interview.started` remains the trigger
- - attach fetches pending questions from the server
- - attach prompts locally with `ConsoleInterviewer`
- - attach submits answers through the existing server client
-
-- Update CLI question conversion for any new `ApiQuestion` fields that should be shown, especially `context_display`.
-
-### 6. Move Slack onto server-owned canonical answer handling
-
-Replace the current `WebInterviewer`-centric Slack path with a server-owned integration.
-
-- Add server-side Slack wiring in `lib/crates/fabro-server/src/server.rs`:
- - create a single Slack service on startup when both tokens and `slack.default_channel` are configured
- - subscribe it to the existing `state.global_event_tx` broadcast and filter `interview.started`, `interview.completed`, `interview.timeout`, and `interview.interrupted`
- - post a Slack message for each fresh pending interview
- - use completion, timeout, and abort events for best-effort Slack message updates while the in-memory message metadata still exists
-
-- Refactor `lib/crates/fabro-slack`:
- - remove `WebInterviewer` dependencies from the Socket Mode connection path
- - change parsed interactions to carry `run_id` and `qid`
- - use structural `action_id` values and JSON `value` payloads
- - preserve structured multiple-choice and multi-select answers
- - change freeform thread routing from `thread_ts -> question_id` to `thread_ts -> (run_id, qid)`
-
-- Keep Slack delivery state memory-only inside the server.
- - store `(run_id, qid) -> posted message metadata`
- - store `thread_ts -> (run_id, qid)`
- - after restart, do not rehydrate these maps
- - reject or ignore stale Slack interactions that no longer match a live pending interview
-
-- Route Slack answers through the canonical internal answer-submission service.
- - Slack must not call interviewer objects directly
- - if the answer is accepted, update the original Slack message when metadata is still present
-
-### 7. Remove obsolete interview implementations and docs
-
-After replacement coverage is in place:
-
-- delete `lib/crates/fabro-interview/src/file.rs`
-- delete `lib/crates/fabro-interview/src/web.rs`
-- remove their re-exports from `lib/crates/fabro-interview/src/lib.rs`
-- delete or rewrite `lib/crates/fabro-slack/examples/slack_e2e.rs`
-- update `docs/integrations/slack.mdx` so it describes the new server-owned projected-question architecture instead of the old web interviewer model
-
-## Public Interface Changes
-
-- `ApiQuestion` adds:
- - `stage`
- - `timeout_seconds`
- - `context_display`
-
-- `SubmitAnswerRequest` does not change.
-
-- Run events change as follows:
- - `interview.started` carries the full pending-question payload
- - `interview.completed` gains `question_id`
- - `interview.timeout` gains `question_id`
- - `interview.interrupted` is new
-
-- Slack interactive payloads change from `question_id`-only routing to explicit `run_id + qid` routing in the action value payload.
-
-## Test Plan
-
-- `fabro-store`
- - add projection tests for pending interview insert and cleanup
- - cover `completed`, `timeout`, `interrupted`, rewind, and terminal run cleanup
-
-- `fabro-workflow`
- - add handler tests that verify:
- - generated `question.id`
- - richer `interview.started`
- - `interview.interrupted` on `Interrupted`
- - `interview.completed` on `Skipped`
- - correlated `question_id` on completion and timeout
- - old interview events without the new fields still deserialize and replay safely
-
-- `fabro-interview`
- - add broker tests for:
- - waiter registration by `qid`
- - answer delivery
- - unknown `qid`
- - duplicate answer handling
- - control-channel closure behavior
-
-- `fabro-server`
- - add tests that verify:
- - `GET /runs/{id}/questions` is projection-backed only
- - `POST /runs/{id}/questions/{qid}/answer` works for both subprocess and in-process runs
- - first-answer-wins returns success once and `409` thereafter
- - no interview scratch files are created for server-managed runs
- - `registry_factory_override` still supports interview-driven tests without `WebInterviewer`
- - a full-loop integration test covers:
- - server starts a run with a human gate
- - worker emits `interview.started`
- - pending question appears in `GET /runs/{id}/questions`
- - `POST /runs/{id}/questions/{qid}/answer` succeeds
- - the server delivers the answer over worker `stdin`
- - the workflow continues to terminal completion
-
-- `fabro-slack`
- - add tests that verify:
- - button payloads carry `run_id` and `qid`
- - freeform thread routing uses `(run_id, qid)`
- - multi-select remains structured
- - stale interactions are rejected after the pending interview is gone
- - Slack answers use the same canonical answer-submission service as HTTP
-
-## Assumptions
-
-- `Question.metadata` and `Question.default` remain internal runtime fields and are not exposed in `ApiQuestion`.
-- `context_display` is the only contextual prompt payload exposed externally in this pass.
-- Slack posts only when both Slack tokens and `slack.default_channel` are configured.
-- Slack delivery metadata is intentionally ephemeral and may be lost on server restart.
-- `stdin` JSONL is the long-term worker control plane; this pass only implements interview answers, not steering behavior.
diff --git a/docs/plans/2026-04-07-run-manifest-blobs-and-bundle-removal-plan.md b/docs/plans/2026-04-07-run-manifest-blobs-and-bundle-removal-plan.md
deleted file mode 100644
index b9ea84eef..000000000
--- a/docs/plans/2026-04-07-run-manifest-blobs-and-bundle-removal-plan.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Run Manifest Blobs And Bundle Removal Plan
-
-## Summary
-Persist run-definition inputs in CAS-backed blob storage and stop treating scratch as a durable source of workflow definition state.
-
-This pass stores two durable blob-backed payloads for `/runs` creates:
-
-- the raw submitted `RunManifest` on `run.created`
-- the smaller accepted internal run definition on `run.submitted`
-
-It removes `workflow_bundle.json` from scratch and updates start/resume to load the accepted definition from the run store instead.
-
-## Key Decisions
-- Keep the current event sequence.
- - Do not add a separate `run.accepted` event.
- - `run.created` carries the raw submitted-manifest blob ref.
- - `run.submitted` carries the accepted-definition blob ref.
-- Store the submitted manifest as the exact request-body bytes.
- - Motivation: preserve the exact wire submission for audit/debugging, not just the parsed semantic content.
- - Consequence: semantically equivalent JSON bodies with different whitespace or field ordering will produce different blob IDs.
-- Treat this as greenfield work.
- - Do not add compatibility fallbacks for older event shapes, older runs, or older scratch layouts.
- - Do not preserve `workflow_bundle.json` reads or writes behind a migration shim.
-- Keep `workflow_source` inline on `run.created`.
- - Cheap projection reads and existing graph-source consumers should continue to work without hydrating a blob.
-- Rename `StoredWorkflowBundle` to `AcceptedRunDefinition` and make it the durable accepted-definition payload.
- - Keep the existing data shape (`workflow_path`, `workflows`) and add a `version` field.
- - Delete the file I/O helpers instead of introducing a second identical type with conversion boilerplate.
-- Treat the accepted-definition pointer as part of run status state.
- - Because `run.submitted` is reused by rewind, every `run.submitted` emission must carry the accepted-definition blob ref from run state.
-
-## Implementation Changes
-### 1. Event and projection types
-- Update [`lib/crates/fabro-types/src/run_event/run.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run_event/run.rs):
- - add `submitted_manifest_blob: Option` to `RunCreatedProps`
- - replace `RunSubmitted(RunStatusTransitionProps)` with `RunSubmitted(RunSubmittedProps)`
- - define `RunSubmittedProps { reason: Option, accepted_definition_blob: Option }`
-- Update [`lib/crates/fabro-types/src/run_event/mod.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run_event/mod.rs) and event-name plumbing to use the new `RunSubmittedProps`.
-- Update [`lib/crates/fabro-types/src/run.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run.rs) `RunRecord` with:
- - `submitted_manifest_blob: Option`
- - `accepted_definition_blob: Option`
-- Update [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs):
- - `run.created` seeds `submitted_manifest_blob`
- - `run.submitted` updates run status and overwrites `accepted_definition_blob`
- - `graph_source` continues to come from inline `workflow_source`
-
-### 2. Durable run-definition blob payloads
-- Update [`lib/crates/fabro-workflow/src/workflow_bundle.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/workflow_bundle.rs):
- - rename `StoredWorkflowBundle` to `AcceptedRunDefinition`
- - add a `version` field
- - remove `load_from_run_dir()` and any `workflow_bundle.json` file I/O helpers
-- Keep `BundledWorkflow` and `WorkflowBundle` as runtime types used by execution and child-workflow resolution.
-- Keep the current constructor/runtime helper surface where useful, but do not add a parallel accepted-definition type or a redundant conversion layer.
-
-### 3. Server create path and blob persistence
-- Update [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-server/src/server.rs) `POST /runs`:
- - read the raw request body bytes
- - deserialize `RunManifest` from those bytes
- - pass both the typed manifest and the original bytes into workflow creation because this pass intentionally stores the exact submitted JSON bytes
-- Update [`lib/crates/fabro-workflow/src/operations/create.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/create.rs):
- - extend `CreateRunInput` with optional raw submitted-manifest bytes
- - after opening the run store, write the raw manifest bytes to CAS when present
- - derive the accepted definition from `workflow_path` + `workflow_bundle` and write it to CAS
- - remove the `persist_workflow_bundle()` call and delete the helper
- - append `run.created` with `submitted_manifest_blob`
- - append `run.submitted` with `accepted_definition_blob`
-- All normal `/runs` creates, including CLI `fabro run` through the server route, should write both blobs.
-- Direct low-level `CreateRunInput` callers that bypass manifests may omit `submitted_manifest_blob`.
- - If they still provide `workflow_path` + `workflow_bundle`, they should still get an `accepted_definition_blob`.
- - Only callers that provide neither manifest bytes nor a bundled workflow definition may leave both refs `None`.
-
-### 4. Start, resume, and rewind
-- Update [`lib/crates/fabro-workflow/src/operations/start.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/start.rs):
- - stop reading `workflow_bundle.json` from `persisted.run_dir()`
- - load `state.run.accepted_definition_blob`
- - fetch the accepted-definition bytes through `RunStoreHandle`
- - deserialize the accepted definition and reconstruct `workflow_path` / `workflow_bundle`
-- Leave `WorkflowInput::Path` behavior unchanged for truly non-bundled runs that never had an accepted-definition blob.
-- Update [`lib/crates/fabro-cli/src/commands/run/rewind.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/rewind.rs) so the re-emitted `run.submitted` event includes the current `accepted_definition_blob` from run state.
-- Keep manager-loop and parallel child-workflow execution unchanged once `EngineServices.workflow_bundle` is hydrated from the accepted-definition blob.
-
-### 5. Output and documentation cleanup
-- Update CLI JSON/event rendering paths that special-case empty `run.submitted` properties so they tolerate structured `RunSubmittedProps`:
- - [`lib/crates/fabro-cli/src/commands/run/logs.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/logs.rs)
- - [`lib/crates/fabro-cli/src/commands/run/attach.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/attach.rs)
-- Remove `workflow_bundle.json` from [`docs/reference/run-directory.mdx`](/Users/bhelmkamp/p/fabro-sh/fabro-2/docs/reference/run-directory.mdx).
-- Update any tests or docs that mention `StoredWorkflowBundle` or scratch-based workflow bundle persistence.
-
-## Public Interface Changes
-- Internal event payload shape changes:
- - `run.created` gains `submitted_manifest_blob`
- - `run.submitted` now emits structured properties with `reason` and `accepted_definition_blob`
-- Internal run-state shape changes:
- - `RunProjection.run` gains `submitted_manifest_blob` and `accepted_definition_blob`
-- No public `/runs` request-shape change is intended.
-- No new HTTP routes are required; existing run-scoped blob read/write APIs remain the storage surface.
-
-## Test Plan
-- Add create-path coverage in [`lib/crates/fabro-workflow/src/operations/create.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/create.rs):
- - manifest-backed create writes both blobs
- - raw submitted-manifest bytes round-trip exactly through CAS
- - first event is `run.created` with `submitted_manifest_blob`
- - second event is `run.submitted` with `accepted_definition_blob`
- - no `workflow_bundle.json` file is written
-- Add start/resume coverage in [`lib/crates/fabro-workflow/src/operations/start.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/start.rs):
- - accepted-definition blob hydrates `workflow_bundle`
- - bundled imports/prompts/child workflows still resolve after original source files are removed
-- Add projection/event coverage in [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs) and event serde tests:
- - `run.created` stores `submitted_manifest_blob`
- - `run.submitted` updates `accepted_definition_blob`
- - serialized/deserialized `RunSubmittedProps` round-trips cleanly
-- Add rewind coverage in [`lib/crates/fabro-cli/src/commands/run/rewind.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/rewind.rs):
- - rewind re-emits `run.submitted` with the current accepted-definition blob
-- Update CLI attach/log integration tests so `run.submitted` JSON includes structured properties and still renders correctly.
-
-## Assumptions
-- Greenfield strictness is preferred over compatibility padding.
-- Orphaned manifest/definition blobs are acceptable in this pass; no blob GC work is included.
- - CAS deduplication limits duplicate growth because identical payloads share blob storage.
-- The raw submitted-manifest blob is stored exactly as received over HTTP, not by reserializing a typed struct.
-- The accepted definition is the only durable source used to reconstruct bundled workflow execution state after creation.
diff --git a/docs/plans/2026-04-07-run-state-projection-consolidation-plan.md b/docs/plans/2026-04-07-run-state-projection-consolidation-plan.md
deleted file mode 100644
index 1d2303670..000000000
--- a/docs/plans/2026-04-07-run-state-projection-consolidation-plan.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Run State Projection Consolidation Plan
-
-## Summary
-Consolidate the duplicated CLI and CLI-test run-state projection structs into the canonical read-model types owned by `fabro-store`.
-
-This pass keeps `RunProjection` and `NodeState` in `fabro-store`, does not move them into `fabro-types`, and does not touch workflow events. The goal is to make the store projection the single source of truth for the `/api/v1/runs/{id}/state` response and for CLI-side consumption of that response.
-
-## Key Decisions
-- `fabro_store::RunProjection` and `fabro_store::NodeState` become the only production definitions.
-- The server response shape remains strict.
- - Do not add backward-compat aliases, migration shims, or permissive serde fallbacks.
- - If the server and CLI drift, the build or tests should fail.
-- `RunProjection` remains a store-owned read model in this pass.
- - Do not move it into `fabro-types`.
-- The existing store projection helper surface is the shared API:
- - `node()`
- - `iter_nodes()`
- - `is_empty()`
- - `list_node_visits()`
-
-## Implementation Changes
-### 1. Make the store projection reusable as the client model
-- Update [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs) so `RunProjection` and `NodeState` derive `serde::Deserialize` in addition to their current derives.
-- Keep the field layout unchanged unless deserialization requires a minimal adjustment for the existing JSON shape.
-- Keep the current helper methods on `RunProjection` as the public access surface for downstream crates.
-
-### 2. Remove the duplicated CLI runtime projection
-- Delete the local `RunProjection` and `NodeState` definitions from [`lib/crates/fabro-cli/src/server_client.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/server_client.rs).
-- Import `fabro_store::RunProjection` instead.
-- Keep `get_run_state()` structurally simple:
- - fetch `/api/v1/runs/{id}/state`
- - deserialize the response into the shared store projection type
-- Do not recreate projection helper methods in the CLI.
-
-### 3. Remove the duplicated CLI test projection
-- Delete the mirrored `RunProjection` and `NodeState` definitions from [`lib/crates/fabro-cli/tests/it/cmd/support.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/tests/it/cmd/support.rs).
-- Reuse `fabro_store::RunProjection` in test helpers that fetch `/api/v1/runs/{id}/state`.
-- Rewrite any test call sites that depend on direct `nodes` map access to use the shared projection API instead:
- - `iter_nodes()`
- - `node()`
- - `list_node_visits()`
-
-### 4. Keep the server boundary unchanged
-- Leave [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-server/src/server.rs) behavior unchanged for `GET /api/v1/runs/{id}/state`.
-- The endpoint already returns the store projection directly; this pass only removes downstream duplication.
-
-## Public Interface Changes
-- No HTTP API shape change is intended.
-- No `fabro-types` change is intended.
-- The effective shared contract becomes explicit:
- - `/api/v1/runs/{id}/state` is represented by `fabro_store::RunProjection`
- - the CLI no longer maintains a private mirror type for that payload
-
-## Test Plan
-- Add a `fabro-store` serde test that deserializes a representative run-state JSON payload into `RunProjection`, including stage-id string keys such as `build@2`.
-- Add a `fabro-store` round-trip test that serializes and deserializes `RunProjection` and verifies:
- - `node()` returns the expected node state
- - `list_node_visits()` returns the expected visit list
-- Run `cargo nextest run -p fabro-store`.
-- Run `cargo nextest run -p fabro-cli`.
-- Confirm existing CLI integration coverage that hits `/api/v1/runs/{id}/state` still passes with the shared projection type.
-
-## Assumptions
-- This plan covers only the projection-consolidation pass we discussed, not event cleanup or broader run-state refactors.
-- Greenfield strictness is preferred over compatibility padding.
-- `fabro-store` is the correct ownership boundary for this read model in the current architecture.
diff --git a/docs/plans/2026-04-07-store-dump-server-owned-export-plan.md b/docs/plans/2026-04-07-store-dump-server-owned-export-plan.md
deleted file mode 100644
index bf6664111..000000000
--- a/docs/plans/2026-04-07-store-dump-server-owned-export-plan.md
+++ /dev/null
@@ -1,235 +0,0 @@
-# Store Dump Server-Owned Export Plan
-
-## Summary
-
-Align `fabro store dump` with the intended architecture by making it a pure server-backed export command.
-
-- The CLI should resolve runs from server summaries only.
-- It should fetch hydrated run state, hydrated event history, and artifacts over HTTP.
-- It should stop creating a temporary `Database`.
-- It should stop reading local scratch directories or local storage/object-store paths.
-- It can keep the current export-style output layout on disk, except blob storage should stay transparent:
- - top-level metadata files
- - `nodes/**`
- - `retro/**`
- - `events.jsonl`
- - `checkpoints/**`
- - `artifacts/**`
-
-This is a debugging export, not a strict snapshot mechanism. Best-effort consistency is acceptable.
-
-## Problem Frame
-
-`fabro store dump` is still implemented as a local store reconstruction flow:
-
-- it resolves the run through local-storage-aware helpers
-- it fetches events over HTTP but replays them into an in-memory `fabro_store::Database`
-- it reads artifacts from local storage directly
-- it assumes the CLI can see the same storage and scratch directories as the server
-
-That is now the wrong boundary. The server should own store access; the CLI should only export server-provided run data to disk.
-
-## Key Decisions
-
-- `store dump` becomes server-only.
- - Use `ServerTargetArgs`, not `StorageDirArgs`.
- - Resolve selectors through `ServerSummaryLookup`, not `ServerRunLookup`.
- - Do not scan local scratch directories or orphan runs.
-
-- Keep the current export layout.
- - It is fine that the command still writes `events.jsonl`, `checkpoints/`, and `artifacts/`.
- - It should not write a `blobs/` directory.
- - Blob storage is an internal offload mechanism, not part of the user-facing export model.
-
-- Do not add blob enumeration.
- - Blob-backed values should be hydrated server-side before the CLI receives run state or events.
- - The CLI should not need to understand blob pointer conventions.
- - The exported files should look as if offloading had never happened.
-
-- Best-effort race handling is acceptable.
- - If a blob or artifact is listed/referenced but disappears before download, skip it and continue.
- - Fail on transport or server errors other than `404`.
-
-- Event pagination should use the server's `meta.has_more` contract.
- - Do not stop paging based on "returned fewer than page size".
- - The client should retain and use pagination metadata from the API response.
-
-- Artifact downloads should be concurrent with a fixed upper bound.
- - Use a bounded concurrency strategy such as `JoinSet` or `FuturesUnordered` with a small limit.
- - Recommended default: `8` concurrent artifact downloads.
-
-## Implementation Changes
-
-### 1. Convert `store dump` to standard server targeting
-
-In `fabro-cli`:
-
-- change `StoreDumpArgs` to flatten `ServerTargetArgs`
-- remove `StorageDirArgs` from this command
-- update help text, docs, and snapshots to show `--server` / `FABRO_SERVER`
-
-Run resolution should follow the same contract as other server-backed inspection commands:
-
-1. explicit `--server`
-2. configured `[server].target`
-3. default local server instance if no server target is configured
-
-The command should no longer derive behavior from a local storage dir.
-
-### 2. Resolve the run from server summaries only
-
-- replace `ServerRunLookup` usage with `ServerSummaryLookup`
-- resolve `` from server-provided summaries only
-- remove any dependence on local scratch-path scanning during selector resolution
-
-This ensures `store dump` works even when the server runs on a different host.
-
-### 3. Add server/API support for paginated hydrated reads
-
-The CLI path depends on the server returning enough information to page correctly and to keep blob handling transparent.
-
-Add or update the server/API contract for:
-
-- `GET /runs/{id}/state?hydrate_blobs=true`
-- `GET /runs/{id}/events?...&hydrate_blobs=true`
-
-Follow the existing OpenAPI-first workflow for these API changes:
-
-- update `docs/api-reference/fabro-api.yaml`
-- rebuild Rust API types/client via `cargo build -p fabro-api`
-- regenerate the TypeScript client in `lib/packages/fabro-api-client`
-
-Also update the CLI client shape for event listing so pagination metadata is preserved instead of discarded:
-
-- add a new paginated event-list helper for `store dump` that returns both `data` and `meta.has_more`
-- keep the existing `list_run_events(...) -> Vec` convenience method in place for current callers unless there is a strong reason to migrate them in the same change
-- `store dump` must consume the metadata-bearing form
-
-The existing artifact APIs are already sufficient for this plan:
-
-- `list_run_artifacts(run_id)`
-- `download_stage_artifact(run_id, stage_id, filename)`
-
-No new artifact endpoint work is required here.
-
-### 4. Add server-side blob hydration for state and events
-
-Blob storage is intended to be transparent. `store dump` should not detect, enumerate, or hydrate blob pointers in the CLI.
-
-Recommended API shape:
-
-- add `hydrate_blobs=true` as an optional query parameter on both endpoints
-- when omitted or `false`, preserve current behavior
-- when `true`, the server resolves blob-backed references before serializing the response
-- reflect those query parameters in the OpenAPI schema and generated clients
-
-Hydration scope:
-
-- all blob-backed values inside `RunProjection`
-- all blob-backed values inside returned event payloads
-- this includes values that ultimately flow into exported checkpoint JSON because checkpoints come from `RunProjection.checkpoints`
-
-Hydration mechanism:
-
-- implement a shared server-side JSON hydrator that walks `serde_json::Value`, detects blob-backed pointer values, reads the referenced blobs from the run store, and replaces the pointer string with the parsed JSON payload
-- reuse the same helper for both state and event responses so blob resolution rules stay identical
-- keep the helper server-owned rather than attaching it only to `RunProjection`, because event payloads need the same treatment
-
-If a referenced blob cannot be resolved during hydrated fetch:
-
-- treat `404` as a race-tolerant miss
-- preserve the original pointer value in the hydrated response
-- fail on non-`404` server/store errors
-
-This keeps blob knowledge server-owned, which matches the architecture this plan is trying to enforce.
-
-### 5. Refactor `RunDump` to accept fetched export data instead of store handles
-
-`RunDump::store_export` currently assumes:
-
-- a `RunDatabase`
-- an `ArtifactStore`
-- store enumeration for blobs and artifacts
-
-Refactor this into a store-agnostic export builder with a concrete constructor:
-
-```rust
-RunDump::from_export(
- state: &RunProjection,
- events: &[EventEnvelope],
- artifacts: &HashMap<(StageId, String), Bytes>,
-) -> Result
-```
-
-Notes:
-
-- `state` is already hydrated
-- `events` are already hydrated
-- blobs are not a separate constructor parameter
-- `artifacts` are the only binary payloads the CLI still fetches explicitly
-
-The new builder should preserve the current file layout and validation rules:
-
-- top-level metadata files from `RunProjection`
-- node files under `nodes//visit-/`
-- `retro/prompt.md` and `retro/response.md`
-- `events.jsonl`
-- `checkpoints/.json` sourced directly from `RunProjection.checkpoints`
-- `artifacts/nodes//visit-/`
-
-Keep the existing staged-directory write behavior:
-
-- reject non-empty output dirs
-- write into a temp dir under the output parent
-- rename into place when complete
-
-### 6. Replace local store reconstruction with HTTP-backed export collection
-
-In `dump_command`, fetch the export inputs directly from the server:
-
-- hydrated current run state via `get_run_state(run_id, hydrate_blobs = true)`
-- full hydrated event history via paginated `list_run_events(run_id, since_seq, limit, hydrate_blobs = true)`
- - use an explicit page size of `1000`
- - continue paging based on `meta.has_more`
-- run artifacts via `list_run_artifacts(run_id)`
-- artifact contents via `download_stage_artifact(run_id, stage_id, filename)` using bounded concurrency
-
-Do not:
-
-- create a `Database`
-- call `rebuild_run_store`
-- open a local `ArtifactStore`
-- read anything under local `storage/` or scratch paths
-
-### 7. Leave shared event-rebuild helpers for other commands
-
-`rebuild_run_store` is still used by other commands such as `fork`, `rewind`, and `pr create`.
-
-- remove it from `store dump`
-- do not delete it in this change unless those other commands are migrated too
-
-This plan is specific to aligning `store dump` with server-owned export.
-
-## Test Plan
-
-- update the `store dump --help` snapshot for the CLI arg change from `--storage-dir` to `--server`
-- re-enable the disabled `store dump` integration coverage and make it exercise the server-backed path only
-- add a regression test for a run with more than 100 events to prove pagination exports the full `events.jsonl`
-- add a regression test for a run with exactly `1000` events to prove the client performs the additional page fetch and stops on `has_more = false`, not on page-size heuristics
-- add server/API coverage for hydrated fetches:
- - hydrated `get_run_state(..., hydrate_blobs = true)` replaces blob-backed pointers with original JSON values
- - hydrated `list_run_events(..., hydrate_blobs = true)` replaces blob-backed pointers in event payloads
- - blob `404` during hydration preserves the original pointer value
-- add coverage that no `blobs/` directory is emitted
-- add `RunDump` coverage for the new store-agnostic constructor to verify the exported file layout remains unchanged for representative state/events/blobs/artifacts
-- keep or restore the non-empty output-dir rejection test
-- add a race-tolerance test where a referenced artifact returns `404` and the export completes without that artifact file
-- add coverage that artifact downloads run through the bounded-concurrency path without changing output order or file paths
-
-## Assumptions and Defaults
-
-- `store dump` should use the standard server-target contract, not `--storage-dir`
-- the current export file layout is intentionally preserved
-- blob handling is transparent and server-owned; there is no `blobs/` export directory and no need for a blob-list API
-- best-effort consistency is sufficient because this command exists for debugging and inspection
-- the server remains the only component allowed to access the underlying run store in this architecture
diff --git a/docs/plans/2026-04-07-worker-http-only-run-store-migration-plan.md b/docs/plans/2026-04-07-worker-http-only-run-store-migration-plan.md
deleted file mode 100644
index ac884a717..000000000
--- a/docs/plans/2026-04-07-worker-http-only-run-store-migration-plan.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# Complete Worker HTTP-Only Run Store Migration
-
-## Summary
-- Finish the architecture change by removing all `RunDatabase` / SlateDB usage from the detached `fabro __run-worker` path.
-- Keep the server as the only SlateDB owner and single writer.
-- Do this with one run-scoped internal runtime abstraction used by workflow execution, plus two implementations:
- - local adapter for server-side execution and tests
- - HTTP-backed adapter for detached workers
-- Let the HTTP-backed worker maintain a write-through in-memory mirror of acknowledged events and projection state so repeated worker-side reads do not turn into unnecessary HTTP round-trips.
-- Reuse existing server endpoints; no OpenAPI or route changes are required for this migration.
-
-## Internal Interface Changes
-- Introduce a small run-scoped async runtime-facing store interface in `fabro-workflow` for the operations the executor actually needs:
- - `load_state() -> RunProjection`
- - `list_events() -> Vec`
- - `append_run_event(&RunEvent) -> ()`
- - `write_blob(&[u8]) -> RunBlobId`
- - `read_blob(&RunBlobId) -> Option`
-- Change workflow execution plumbing to depend on that interface instead of `RunDatabase`:
- - `StartServices`
- - `EngineServices`
- - the pipeline structs and options that currently carry `RunDatabase`
- - helpers that currently hard-code persisted-load, retro, and finalize store reads
-- Replace the `RunEventSink::store(RunDatabase)` special case with a backend-based writer so event emission no longer assumes a local SlateDB handle.
-- Keep the interface scoped to a single run so methods do not need a `RunId` parameter.
-
-## Implementation Changes
-### 1. Runtime backend abstraction
-- Add a runtime store backend trait in `fabro-workflow` and migrate the worker-facing execution path to depend on it instead of `RunDatabase`.
-- Keep the interface narrow and asynchronous, covering only the worker-side behaviors that still depend on store access:
- - load run projection / run record / graph source
- - list events
- - append run events
- - write blobs
- - read blobs
-- Allow the HTTP-backed implementation to keep a write-through in-memory mirror of run state and events, but only update that mirror after the server has acknowledged the write. The server remains canonical; the worker cache is a derived mirror for read efficiency only.
-- Define failure policy up front:
- - apply bounded retries to transient HTTP failures
- - if retries exhaust on a required read or write, fail the worker run with a clear fatal error
- - do not continue executing after the worker loses the ability to read or write canonical run state
-
-### 2. Local adapter for server execution
-- Add a local adapter in `fabro-workflow` that wraps `RunDatabase`.
-- Keep server-side execution behavior unchanged:
- - the server still opens the durable `RunDatabase`
- - the server passes the local adapter into workflow execution
- - the server remains the only SlateDB owner and single writer in production execution
-- Keep existing unit and integration tests that rely on in-process `RunDatabase` semantics working through this adapter.
-
-### 3. HTTP-backed adapter for detached workers
-- Add an HTTP-backed adapter in `fabro-cli` on top of `ServerStoreClient`.
-- Extend `ServerStoreClient` with the missing worker-side helpers already supported by the server API:
- - write run blob
- - read run blob
- - get checkpoint only if a migrated path needs a direct checkpoint call rather than `load_state()`
-- The detached worker should use this adapter for all run-state reads and event/blob writes.
-- Seed the adapter from the server once at worker startup, then keep its in-memory mirror in sync from acknowledged appends and explicit refetches when needed.
-
-### 4. Migrate confirmed worker-path reads off `RunDatabase`
-- Move the confirmed detached-worker call sites to the new backend before deleting any local store construction:
- - startup validation and persisted-run loading
- - resume checkpoint loading
- - retro state and event reads
- - finalize conclusion building and metadata-finalize reads
- - artifact blob offload and any worker-path blob reads
- - git metadata checkpoint and finalize reads that currently load state from the local store
-- Treat this as a worker-path refactor, not a whole-repo purge of `RunDatabase`.
-- Explicitly out of scope for this migration:
- - server supervisor code
- - server routes and server-local run execution
- - `store dump` and other separate server-funneling work
-
-### 5. Remove local worker store usage
-- After the worker-path reads above are migrated, delete the local seeded in-memory store path from `lib/crates/fabro-cli/src/commands/run/runner.rs`:
- - remove local `Database::new(InMemory, ..., flush_interval)` construction
- - remove seeding via `list_run_events()` into a local `RunDatabase`
- - remove the worker-side `RunEventSink::fanout([store, callback])`
-- After this change, detached workers send events directly to the server over HTTP and never construct or open any `fabro_store::Database`.
-
-## Test Plan
-- Add unit coverage for the new local adapter covering:
- - state loading
- - event append
- - blob write behavior
- - blob read behavior
-- Add focused unit coverage for the HTTP-backed adapter covering:
- - write-through projection and event cache updates after acknowledged appends
- - bounded retry behavior
- - fatal failure when required HTTP reads or writes keep failing
-- Add focused CLI and worker tests proving detached execution still works for:
- - start
- - resume
- - cancel / ctrl-c
- - human gate handling
- - large context value blob offload
-- Add a regression test that would have failed under the old design:
- - detached worker event delivery is no longer paced by a local worker-side store append
- - `dry_run_simple` no longer shows the `~100ms` per-event cadence caused by the worker’s local store path
-- Add a regression test that the detached worker path no longer constructs a local `fabro_store::Database`.
-- Keep existing server execution tests green to prove the local adapter preserved current semantics.
-
-## Assumptions and Defaults
-- No public HTTP API changes are needed for this migration; existing run state, event, checkpoint, blob, and artifact routes are sufficient.
-- The runtime backend is scoped to a single run, matching detached-worker execution semantics.
-- The HTTP-backed worker cache is a derived mirror updated only after successful server acknowledgements; it does not make the worker a second source of truth.
-- While a detached worker is executing, it is assumed to be the sole emitter of run events for that run; if server-originated events are later added to the live run stream, the cache model will need an explicit invalidation or subscription mechanism.
-- The detached worker must have zero direct SlateDB access after this change.
-- The server remains the only component allowed to own a `RunDatabase` in production execution.
-- This should land as one coherent migration, not as a partial compatibility phase, because the current mixed model is both architecturally wrong and performance-visible.
diff --git a/docs/plans/2026-04-08-001-feat-fabro-uninstall-command-plan.md b/docs/plans/2026-04-08-001-feat-fabro-uninstall-command-plan.md
deleted file mode 100644
index 0262a8f1c..000000000
--- a/docs/plans/2026-04-08-001-feat-fabro-uninstall-command-plan.md
+++ /dev/null
@@ -1,339 +0,0 @@
----
-title: "feat: Add `fabro uninstall` command"
-type: feat
-status: completed
-date: 2026-04-08
-origin: docs/ideation/2026-04-08-fabro-uninstall-ideation.md
-deepened: 2026-04-08
----
-
-# feat: Add `fabro uninstall` command
-
-## Overview
-
-Add a `fabro uninstall` top-level CLI command that reverses the effects of `fabro install` and `install.sh`. The command stops a running server, removes the `~/.fabro/` directory tree, cleans shell config PATH entries, and handles binary self-removal. Defaults to dry-run (preview) mode, requiring `--yes` to execute.
-
-## Problem Frame
-
-There is no supported way to uninstall Fabro. Users must manually `rm -rf ~/.fabro`, hunt for stale PATH entries in their shell configs, and figure out how to stop the server. This creates friction, erodes trust, and leaves detritus after uninstall.
-
-## Requirements Trace
-
-- R1. Remove the `~/.fabro/` directory and all contents
-- R2. Stop a running server before removing files
-- R3. Remove `# fabro` PATH lines from shell configs (.zshrc, .bashrc, .bash_profile, .config/fish/config.fish)
-- R4. Default to dry-run with size reporting; require `--yes` to execute
-- R5. Delete the binary when installed via `install.sh` to `~/.fabro/bin/`; print a hint otherwise
-- R6. Support `--json` output for scriptability
-
-## Scope Boundaries
-
-- No selective/component uninstall (users can back up manually)
-- No GitHub App deregistration via API
-- No export/backup archive feature
-- No telemetry farewell event
-- No per-repo cascade cleanup (repos can be cleaned individually via `fabro repo deinit`)
-
-## Context & Research
-
-### Relevant Code and Patterns
-
-- `lib/crates/fabro-cli/src/commands/install.rs` — what `fabro install` creates (settings.toml, certs/, secrets.json)
-- `apps/marketing/public/install.sh` — what the shell installer creates (binary at `~/.fabro/bin/fabro`, PATH lines with `# fabro` sentinel)
-- `lib/crates/fabro-cli/src/commands/server/stop.rs` — `execute(storage_dir, timeout)`: SIGTERM, poll, SIGKILL, record+socket cleanup
-- `lib/crates/fabro-cli/src/commands/server/record.rs` — `active_server_record_details()` for detecting running server
-- `lib/crates/fabro-cli/src/commands/system/prune.rs` — dry-run-by-default pattern with `--yes`, size reporting via `format_size()`
-- `lib/crates/fabro-cli/src/commands/repo/deinit.rs` — cleanup command pattern: green checkmarks, NotFound tolerance, `Vec` return, `--json` support
-- `lib/crates/fabro-util/src/home.rs` — `Home` struct with all path accessors (`root()`, `certs_dir()`, `storage_dir()`, etc.)
-- `lib/crates/fabro-config/src/storage.rs` — `Storage` struct with storage path accessors
-- `lib/crates/fabro-cli/src/args.rs` — `Commands` enum for command registration, `Commands::name()` for telemetry
-- `lib/crates/fabro-cli/src/commands/upgrade.rs` — `std::env::current_exe()?.canonicalize()?` for binary path detection
-- `lib/crates/fabro-config/src/user_config.rs` — `load_settings()` for resolving effective configuration including non-default `storage_dir`
-
-### Institutional Learnings
-
-No `docs/solutions/` directory exists. No prior learnings on install/uninstall patterns.
-
-## Key Technical Decisions
-
-- **Top-level command, not subcommand of `system`**: Matches `install`/`upgrade` placement. Users will search for `fabro uninstall` — discoverability matters. (see origin: docs/ideation/2026-04-08-fabro-uninstall-ideation.md)
-- **`--yes` confirmation model (not `--dry-run`)**: Matches `system prune` pattern — destructive operations default to preview. The flag name `--yes` is already established in the codebase.
-- **Use `Home::from_env()` as the canonical root**: Respects `$FABRO_HOME` for non-default installations. Never hardcode `~/.fabro/`.
-- **Shell config cleanup uses exact `# fabro` sentinel match**: The `install.sh` script writes `# fabro` as a marker comment before the PATH export. Match with `line.trim() == "# fabro"` (exact match, not substring) to avoid deleting unrelated lines like `# fabro workflow helper`. After matching the sentinel, validate that the following line matches an expected PATH pattern (`export PATH=` or `fish_add_path`) before removing it — this prevents accidentally deleting an innocent line if the file was manually edited.
-- **Binary path resolved during inventory, not after deletion**: `std::env::current_exe()?.canonicalize()?` must be called during the inventory phase (Unit 2) and stored. On macOS, `canonicalize()` fails with `NotFound` after the file is deleted by `remove_dir_all`. The stored path is used later by Unit 5.
-- **Binary self-deletion is the final step**: On Unix, unlinking a running binary works (the inode stays alive until the process exits). Must be absolutely last since nothing can run after the binary is gone.
-- **Do not call `stop::execute()` without a guard**: `server::stop::execute()` calls `std::process::exit(1)` when no server is running. The uninstall command must check `record::active_server_record_details()` first and only call `stop::execute()` when a server is confirmed running.
-- **Resolve `storage_dir` through settings, not just `Home`**: If `settings.toml` configures a non-default `storage_dir`, the server record lives at that custom path. Load effective settings via `user_config::load_settings()` during inventory to resolve the actual `storage_dir`.
-- **Compute-once inventory**: The inventory is built once (Unit 2) and consumed by all subsequent units. No step should re-detect artifacts during execution — the directory may already be partially deleted.
-- **Exit code policy**: Exit 0 only if all critical steps (server stop, directory removal) succeeded. Exit 1 if any critical step failed. Shell config cleanup and binary handling failures warn but do not affect the exit code.
-- **Synchronous implementation**: Server stop logic (`stop::execute`) is synchronous. The uninstall function itself should be async (matching the dispatch pattern in main.rs) but can call sync helpers.
-
-## Open Questions
-
-### Resolved During Planning
-
-- **Should uninstall clean up shell configs that `fabro install` (Rust) didn't create?** Yes — `install.sh` creates them, and the user experience of "uninstall" should reverse the full installation, not just the Rust command's portion.
-- **What if the server won't stop?** Follow the existing SIGTERM→SIGKILL pattern from `server/stop.rs`. If SIGKILL fails (shouldn't happen on Unix), warn and continue with removal.
-
-- **Should the dry-run preview show active workflow run count?** Yes — if the server is running with in-flight workflows, stopping it will terminate them. The preview should report the count so users can make an informed decision. The run count can be obtained from the server API if available, or noted as "server running (active runs unknown)" if the API is unreachable.
-- **What about `$ZDOTDIR` mismatch between install and uninstall time?** If the user's `$ZDOTDIR` was set differently at install time versus uninstall time, the uninstall will look in the wrong file. This is an inherent limitation — document it but do not try to solve it.
-
-### Deferred to Implementation
-
-- **Fish shell syntax differences**: `fish_add_path` vs `export PATH=` — the removal logic needs shell-specific handling. Determine exact patterns during implementation.
-
-## Implementation Units
-
-- [x] **Unit 1: Command registration and skeleton**
-
-**Goal:** Register `fabro uninstall` as a top-level CLI command with args parsing.
-
-**Requirements:** R4, R6
-
-**Dependencies:** None
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/args.rs`
-- Modify: `lib/crates/fabro-cli/src/commands/mod.rs`
-- Modify: `lib/crates/fabro-cli/src/main.rs`
-- Create: `lib/crates/fabro-cli/src/commands/uninstall.rs`
-
-**Approach:**
-- Add `UninstallArgs` struct with `--yes` bool field (clap attribute: `#[arg(long)]`)
-- Add `Uninstall(UninstallArgs)` variant to `Commands` enum with doc comment `/// Uninstall Fabro from this machine`
-- Add `Self::Uninstall(_) => "uninstall"` to `Commands::name()`
-- Add `pub(crate) mod uninstall;` to `commands/mod.rs`
-- Add dispatch arm in main.rs calling `commands::uninstall::run_uninstall(&args, &globals).await?`
-- Skeleton `run_uninstall` that prints "not yet implemented" and returns Ok
-
-**Patterns to follow:**
-- `InstallArgs` struct and `Commands::Install` variant in `args.rs`
-- Dispatch pattern in `main.rs` (line ~176)
-- Module declaration pattern in `commands/mod.rs`
-
-**Test scenarios:**
-- Happy path: `fabro uninstall --help` outputs usage text including `--yes` flag description
-- Happy path: `fabro uninstall` (no args) parses successfully and runs the skeleton
-
-**Verification:**
-- `cargo build -p fabro-cli` succeeds
-- `fabro uninstall --help` shows the expected usage
-
----
-
-- [x] **Unit 2: Inventory and dry-run preview**
-
-**Goal:** Discover all Fabro artifacts on the system, compute sizes, and display a preview manifest. When `--yes` is not passed, this is the complete behavior.
-
-**Requirements:** R1, R2, R3, R4, R5, R6
-
-**Dependencies:** Unit 1
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
-
-**Approach:**
-- Use `Home::from_env()` to resolve the root directory
-- Check if `Home::root()` exists; if not, print "Fabro is not installed" and exit 0 (skip settings loading entirely)
-- If home exists, attempt to load effective settings via `user_config::load_settings()` to resolve actual `storage_dir`. If settings loading fails (e.g., settings.toml missing or corrupt), fall back to `Home::from_env().storage_dir()` — this handles partial installs and repeated uninstall attempts
-- Build an inventory struct containing all information needed by subsequent units:
- - `home_root`: resolved Home root path
- - `storage_dir`: resolved storage directory path
- - `home_exists`: whether the home directory exists
- - `home_size`: total size of home directory (recursive walk)
- - `server_running`: whether a server is detected via `record::active_server_record_details(&storage_dir)`
- - `shell_configs`: list of shell config file paths that contain the `# fabro` sentinel (exact match: `line.trim() == "# fabro"`)
- - `binary_path`: resolved path from `std::env::current_exe()?.canonicalize()?` (must be resolved NOW, before any deletion)
- - `binary_is_managed`: whether `binary_path` starts with `home_root`
-- Shell config files to scan: `$ZDOTDIR/.zshrc` or `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.config/fish/config.fish`
-- In dry-run mode (no `--yes`): print each item that would be removed with its size, including active run warning if server is running, then print `"Pass --yes to confirm."` summary
-- Support `--json` output: serialize inventory as JSON to stdout
-- Follow the `system prune` output style for human-readable format
-
-**Patterns to follow:**
-- `system prune` dry-run output format ("would delete: ...", "N item(s) would be deleted (X freed)")
-- `format_size()` for human-readable byte formatting
-- `console::Style` / `Styles::detect_stderr()` for colored output
-- `GlobalArgs.json` check for JSON vs human output
-
-**Test scenarios:**
-- Happy path: preview with populated `~/.fabro/` lists all directories and files with sizes
-- Happy path: preview with `--json` outputs structured JSON to stdout
-- Edge case: `~/.fabro/` does not exist — prints "Fabro is not installed" and exits cleanly
-- Edge case: shell config files exist but contain no fabro lines — omitted from preview
-- Edge case: binary is not in `~/.fabro/bin/` — preview notes it must be removed manually
-- Happy path: running server detected — preview notes it will be stopped and warns about active runs
-- Edge case: `current_exe()` or `canonicalize()` fails — inventory stores `None` for binary path, warns in preview
-
-**Verification:**
-- `fabro uninstall` (no `--yes`) prints a complete manifest and does NOT delete anything
-- `fabro uninstall --json` outputs valid JSON with inventory details
-- Preview accurately reflects what exists on disk
-
----
-
-- [x] **Unit 3: Server shutdown and directory removal**
-
-**Goal:** When `--yes` is passed, stop a running server and remove `~/.fabro/` and all contents.
-
-**Requirements:** R1, R2
-
-**Dependencies:** Unit 2
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
-- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
-
-**Approach:**
-- Use the inventory's `server_running` and `storage_dir` fields (computed in Unit 2)
-- **Critical**: Only call `server::stop::execute()` when `inventory.server_running` is true. `stop::execute()` calls `std::process::exit(1)` when no server is found — calling it unconditionally would terminate the process before any cleanup happens.
-- If running, call `server::stop::execute(&inventory.storage_dir, Duration::from_secs(5))`
-- If not running, skip with no error
-- **Safety guardrail before deletion**: Validate `inventory.home_root` is reasonable before calling `remove_dir_all`. Refuse to proceed if the resolved path is a filesystem root (`/`), the user's home directory (`$HOME`), or does not contain an expected marker file (e.g., `settings.toml` or `certs/`). This prevents catastrophic data loss from a misconfigured `$FABRO_HOME`.
-- After validation, remove `inventory.home_root` with `std::fs::remove_dir_all`
-- If `storage_dir` differs from the default and is outside `home_root`, validate it contains Fabro artifacts (e.g., `secrets.json` or `store/`) before removing
-- Handle `ErrorKind::NotFound` gracefully (already uninstalled)
-- Report each step with green checkmark output following `deinit.rs` pattern
-- The `fabro.sock` socket file is inside `~/.fabro/` so it's removed as part of the directory deletion
-
-**Patterns to follow:**
-- `server::stop::execute()` for server shutdown (call ONLY when server is confirmed running)
-- `record::active_server_record_details()` for server detection (already done in inventory)
-- `deinit.rs` checkmark output pattern
-- `RunScratch::remove()` for NotFound tolerance
-
-**Test scenarios:**
-- Happy path: with `--yes` and no running server, `~/.fabro/` is removed successfully
-- Happy path: with `--yes` and running server, server is stopped before removal
-- Edge case: `~/.fabro/` does not exist — reports "nothing to remove" without error
-- Error path: server stop fails (SIGKILL also fails) — warns and continues with removal
-- Error path: `$FABRO_HOME` set to `/` — refuses to delete, prints error
-- Error path: `$FABRO_HOME` set to `$HOME` — refuses to delete, prints error
-- Error path: `$FABRO_HOME` points to a directory without Fabro marker files — refuses to delete
-- Integration: after removal, `~/.fabro/` directory does not exist on disk
-
-**Verification:**
-- `fabro uninstall --yes` removes `~/.fabro/` completely
-- A running server is stopped before file removal
-- No orphaned processes remain after uninstall
-
----
-
-- [x] **Unit 4: Shell config cleanup**
-
-**Goal:** Remove PATH lines that `install.sh` added to shell configuration files, using the `# fabro` sentinel comment.
-
-**Requirements:** R3
-
-**Dependencies:** Unit 2 (uses shell config detection from inventory)
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
-- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
-
-**Approach:**
-- Use the inventory's `shell_configs` list (detected in Unit 2)
-- For each shell config file in the list:
- - Read the file contents
- - Find lines where `line.trim() == "# fabro"` (exact match, not substring — avoids matching `# fabro workflow helper`)
- - Validate that the following line matches an expected PATH pattern before removing it:
- - zsh/bash: following line starts with `export PATH=`
- - fish: following line starts with `fish_add_path`
- - If the following line does NOT match, remove only the sentinel line (defensive — the file was manually edited)
- - Remove the sentinel line AND the validated following line
- - Write the modified contents back
- - Handle edge cases: sentinel at end of file, multiple sentinels, sentinel with no following line
-- Report each modified file with the deinit checkmark pattern
-- If a shell config file is not found or has no fabro lines, skip silently
-
-**Patterns to follow:**
-- `deinit.rs` reporting pattern (green checkmarks per item)
-- **Atomic write pattern**: Write modified content to a temporary file in the same directory, then `std::fs::rename()` over the original (atomic on POSIX). This prevents a truncated/corrupt dotfile if the process crashes mid-write. Check `std::fs::symlink_metadata()` before modifying — if the file is a symlink, follow it (matching `std::fs::read_to_string` behavior) but note this in output so users with dotfile managers are aware.
-
-**Test scenarios:**
-- Happy path: `.zshrc` with `# fabro` + PATH line — both lines removed, rest of file intact
-- Happy path: `.bashrc` with `# fabro` + PATH line — both lines removed
-- Happy path: `.bash_profile` with `# fabro` + PATH line — both lines removed
-- Happy path: `config.fish` with `# fabro` + `fish_add_path` — both lines removed
-- Edge case: shell config exists but has no `# fabro` line — file is not modified
-- Edge case: shell config file does not exist — no error
-- Edge case: `# fabro` is the last line in the file (no following PATH line) — only sentinel line removed
-- Edge case: multiple `# fabro` blocks in the same file — all are removed
-- Edge case: `# fabro` followed by an unrelated line (not PATH export) — only sentinel removed, following line preserved
-- Edge case: line contains `# fabro` as substring (`# fabro-related`) — not matched, file unchanged
-- Integration: after cleanup, opening a new shell does not add fabro to PATH
-
-**Verification:**
-- Shell config files have fabro lines removed without corrupting other content
-- Files without fabro lines are not modified (mtime unchanged)
-
----
-
-- [x] **Unit 5: Binary status reporting and final output**
-
-**Goal:** Report whether the binary was already removed (managed install) or print a removal hint (external install). Print final summary.
-
-**Requirements:** R5
-
-**Dependencies:** Unit 3 (must run after directory removal)
-
-**Files:**
-- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
-- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
-
-**Approach:**
-- Use the inventory's pre-resolved `binary_path` and `binary_is_managed` fields (resolved in Unit 2 before any deletion — `canonicalize()` fails on macOS after the file is deleted)
-- If `binary_is_managed` is true: the binary was inside `~/.fabro/bin/` and was already removed by Unit 3's `remove_dir_all` — report as removed
-- If `binary_is_managed` is false: print a tailored hint
- - Check if path contains `/Cellar/` (Homebrew): "run `brew uninstall fabro`"
- - Check if path contains `.cargo/bin/` (cargo): "run `cargo uninstall fabro`"
- - Otherwise: "The fabro binary at {path} must be removed manually."
-- If `binary_path` is `None` (resolution failed in Unit 2): warn and skip
-- Print final summary: "Fabro has been uninstalled." (bold, to stderr)
-- For `--json` output: include `binary_removed` and `binary_hint` fields
-
-**Patterns to follow:**
-- `deinit.rs` final summary line pattern (bold text)
-- Package manager path detection is heuristic — keep it simple
-
-**Test scenarios:**
-- Happy path: binary was in `~/.fabro/bin/` and was already removed by directory deletion — reports binary removed
-- Happy path: binary is in `/opt/homebrew/Cellar/` — prints "run `brew uninstall fabro`" hint
-- Happy path: binary is in `~/.cargo/bin/` — prints "run `cargo uninstall fabro`" hint
-- Edge case: binary path detection fails (`current_exe()` error) — warns but does not fail the overall uninstall
-- Happy path: final summary message is printed after all steps complete
-
-**Verification:**
-- When binary was installed via `install.sh`, it is deleted or confirmed deleted
-- When binary was installed via other means, a clear removal instruction is printed
-- `fabro uninstall --yes --json` outputs valid JSON including inventory, execution results, and binary status
-- The command exits successfully after all steps
-
-## System-Wide Impact
-
-- **Interaction graph:** The uninstall command interacts with: `server::stop` (server lifecycle), `Home`/`Storage` (path resolution), shell config files (external to fabro), and the running binary itself. No callbacks, middleware, or observers are affected.
-- **Error propagation:** Each step warns on failure but continues. Critical steps (server stop, directory removal) affect the exit code (exit 1 on failure). Non-critical steps (shell config, binary) warn only. A partial uninstall is better than aborting on the first error.
-- **State lifecycle risks:** Stopping the server terminates in-flight workflow runs — the dry-run preview warns about this. Mitigated by mandatory server stop as the first step (prevents filesystem corruption) and by defaulting to dry-run (gives user a chance to see the warning before committing).
-- **API surface parity:** No API endpoint equivalent needed — uninstall is a local-only operation.
-- **Unchanged invariants:** `fabro install`, `fabro server`, `fabro repo deinit`, and `system prune` are not modified by this plan. The uninstall command reuses their code but does not change their behavior.
-
-## Risks & Dependencies
-
-| Risk | Mitigation |
-|------|------------|
-| Shell config surgery corrupts user's dotfiles | Use sentinel-based detection (not regex on PATH content). Only remove exact `# fabro` + next line. Write tests with realistic file content. |
-| Binary self-deletion race condition | Delete binary as the absolute last step. On Unix, unlink of a running binary is safe (inode persists until process exits). |
-| `$FABRO_HOME` set to dangerous path (`/`, `$HOME`) | Safety guardrail: validate resolved path is not a root or home dir, and contains expected marker files, before `remove_dir_all`. |
-| Server stop timeout blocks uninstall | Use a short timeout (5s). SIGKILL as fallback. Continue with removal even if stop fails. |
-| `stop::execute()` exits process when no server found | Guard with `active_server_record_details()` check; never call `stop::execute()` unconditionally. |
-| `canonicalize()` fails after file deletion on macOS | Resolve binary path during inventory phase (Unit 2), before any deletion occurs. |
-| Non-default `storage_dir` in settings.toml | Load settings during inventory to resolve actual storage_dir; don't assume it's inside `~/.fabro/`. |
-| `$ZDOTDIR` differs between install and uninstall time | Known limitation — document it. Uninstall uses current `$ZDOTDIR`. |
-| Partial `remove_dir_all` failure (locked files on macOS) | Warn and report which files remain. Exit 1. User can retry or manually remove. |
-
-## Sources & References
-
-- **Origin document:** [docs/ideation/2026-04-08-fabro-uninstall-ideation.md](docs/ideation/2026-04-08-fabro-uninstall-ideation.md)
-- Related code: `lib/crates/fabro-cli/src/commands/install.rs`, `lib/crates/fabro-cli/src/commands/server/stop.rs`, `lib/crates/fabro-cli/src/commands/system/prune.rs`, `lib/crates/fabro-cli/src/commands/repo/deinit.rs`
-- Related code: `lib/crates/fabro-util/src/home.rs`, `lib/crates/fabro-config/src/storage.rs`
-- Related code: `apps/marketing/public/install.sh`
diff --git a/docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md b/docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md
deleted file mode 100644
index 02c988dfb..000000000
--- a/docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# CLI CommandContext And Server Access Refactor Plan
-
-## Summary
-Refactor `fabro-cli` around an invocation-scoped `CommandContext` that centralizes local settings loading and server connection setup for user-facing server-backed commands. This is a greenfield codebase with no backward-compatibility constraints, so the refactor should be done in one full pass for the in-scope command surface rather than preserving a long-lived mixed model. Keep config-layer composition command-local where commands genuinely need it, keep the generated `fabro_api::Client` as the main HTTP interface, and reuse the existing `ServerStoreClient` type instead of layering a second handwritten endpoint facade on top of it.
-
-## Public Types And Interfaces
-- Add eager, invocation-scoped `CommandContext`:
- - Holds `cwd`, `base_config_path`, `machine_settings`, `server_mode`, and a cached server client cell.
- - `cwd` is the invocation working directory and replaces repeated inline `std::env::current_dir()` lookups in migrated commands such as `preflight`, `validate`, `graph`, `fabro settings`, and workflow-oriented run creation paths.
- - `base_config_path` is the local settings file path chosen by `--config`, `FABRO_CONFIG`, or the default path.
- - `machine_settings` is the result of the existing local settings loaders for the command:
- - base settings for commands using `load_settings()`
- - base settings plus storage-dir override for commands using `load_settings_with_storage_dir(...)`
- - `machine_settings` does not include workflow or project config layers.
- - Do not store `ConfigLayer` on `CommandContext`.
-- Keep config-layer composition command-local:
- - `fabro settings` continues to build `EffectiveSettingsLayers` with its existing helpers.
- - workflow and manifest code continues to use `ConfigLayer::for_workflow(...)`, `discover_project_config(...)`, and existing workflow resolution structs where individual layers matter.
- - `CommandContext` should not attempt to reconstruct or cache workflow/project config layers.
-- Use two explicit server access modes that match the real connection paths in the codebase:
- - `ServerMode::None`
- - `ServerMode::ByTarget { target_override: Option