Files

Fusion 034528cee4 feat(FN-4222): add experiment-finalize CLI command and API route

Implements the `experiment-finalize` CLI command (FN-4222) and its companion dashboard API route, wiring the feature through the pi extension as a new callable tool. Includes the command implementation, extension tooling, API integration, and corresponding test coverage.

Fusion-Task-Id: FN-4222

2026-05-14 04:25:06 -07:00

1.8 KiB

Raw Blame History

Experiment Session Finalize Workflow

Motivation

FN-4136 identified a gap versus upstream autoresearch-finalize: Fusion had no workflow to split kept experiment commits into reviewable branches from a shared merge-base.

Plan model

Finalize builds groups of kept run records, each with ordered commits and a suggested branch name. Branch names default to:

experiment/<session-id>/<slug>-<index>

Override schema:

{
  "groups": [
    {
      "id": "segment:1",
      "title": "Latency fixes",
      "suggestedBranchName": "experiment/exp-1/latency-fixes-1",
      "runRecordIds": ["RUN-2", "RUN-5"]
    }
  ]
}

Algorithm

Resolve merge-base from session baseline ref and integration branch.
Build default plan from kept runs.
Apply optional override and validate run IDs / branch uniqueness.
For each group: create branch at merge-base, checkout, cherry-pick commits in order.
Restore original ref.
Append finalize session record and move session to finalized.
On failure, rollback created branches and restore original ref; session remains finalizing.

Error taxonomy

Error code	CLI exit	HTTP status
`state_error`	2	409
`no_kept_runs`	3	409
`plan_error`	4	400
`merge_base_error`	5	422
`cherry_pick_conflict`	6	422
`branch_exists`	7	409
unknown/untyped	1	500

Recovery

If finalize fails after session status moves to finalizing:

Inspect and delete leftover branches (git branch -D <name>).
Restore session status manually via store update to active.
Re-run finalize (optionally with a plan override).

Follow-ups

FN-4221: dashboard finalize UI wiring.
FN-4223: naming clarifications around research/experiment command surfaces.
Upstream reference: autoresearch-finalize branch-split semantics.

1.8 KiB Raw Blame History