FE-1089: Reconcile executor with alpha branch by kostandinang · Pull Request #274 · hashintel/brunch

kostandinang · 2026-06-30T23:20:25Z

FE-1089: Reconcile executor with alpha branch

Reconciles the legacy orchestration path onto alpha's executor architecture as bounded Pi tools. This PR is the scaffold layer: it proves the selected-spec graph can be projected into execution inputs, materialized into artifacts, advanced through a run lifecycle, and prepared for promotion without reviving a separate orchestrator role.

The important boundary is what it deliberately does not do: it does not run agents or tests, mutate graph truth, or touch git. Those irreversible or environment-dependent effects move behind injected ports in follow-up frontiers: FE-1109 sandbox -> FE-1111 agent runner -> FE-1112 promotion.

Transition

Separate orchestrator role -> live executor tool surface. The executor remains the foreground CODE path; this PR adds tools to it instead of creating another agent mode.
One-off planning output -> ExecutionSpecSnapshot plus durable outline/draft artifacts. The graph-to-execution seam is now explicit and testable.
Broad runner actions -> one explicit side effect per executor tool. Each step reports exactly what it writes under .brunch, keeping the trust boundary reviewable.
Simulated result files -> injected execution ports in follow-up branches. This PR keeps scaffold behavior honest and leaves real worktree, agent, verification, and promotion effects to later slices.

Changed

src/executor/ owns the pure product contracts: projection, plan shaping, run lifecycle state, Petri export, and promotion-prep data.
src/.pi/extensions/agent-runtime/execute-*/ registers thin Pi adapters that validate params, call executor core, and surface side effects.
src/agents/runtime/executor/ admits these execute tools into the live executor allowlist and prompt surface.
memory/SPEC.md / memory/PLAN.md record the D99-L split into scaffold, sandbox, agent runner, and promotion.

Follow-ups

FE-1109 adds real git worktrees and real test execution behind injected ports.
FE-1111 adds the sealed CODE worker that produces real diffs inside the sandbox.
FE-1112 adds promotion from verified run artifacts.

Verification

npm run verify passes: 163 test files, 1102 tests, 0 errors, 3 pre-existing lint warnings.

cursor · 2026-06-30T23:20:32Z

PR Summary

Medium Risk
Large new execute surface and filesystem side-effect contracts under .brunch, but real agent/git/graph effects remain gated off in CODE mode; main risk is mis-documented or prematurely activated writer/lifecycle tools.

Overview
FE-1089 moves legacy cook orchestration onto alpha as native CODE-mode execute_* Pi tools over a new src/executor/ product core, instead of reviving a separate orchestrator or shelling out to the old CLI.

The core adds ExecutionSpecSnapshot v1 and projectExecuteGraph so the selected-spec graph projects into snapshot, plan check, outline, draft, and old-cook preview shapes, plus bounded helpers that advance descriptive run metadata and artifacts only under .brunch/execution-reports and .brunch/cook (plan files, run.json, worktree population, report logs, slice request/result ingestion, Petri export, promotion-prep JSON). Each step reports explicit sideEffects; there is no real agent/test execution, graph mutation, or host git work.

Tool gating: the shell registers the full execute tool set, but execute mode only activates read-only footholds (execute_status, execute_snapshot, execute_plan_check, execute_plan_outline, execute_plan_draft, execute_plan_preview) via the executor allowlist; artifact and lifecycle tools stay registered and test-covered but inactive until a later real-execution boundary. execute_status and updated executor prompt text document active vs inactive tools.

Canon/process: memory/PLAN.md promotes orchestrator-alpha-cutover and retires orchestrator-tool-port as a separate active frontier; memory/SPEC.md adds D101-L and I56-L. memory/REFACTOR.md sketches a follow-up dedup of cook run-metadata I/O in orchestration code (out of scope for discriminated CookRunMetadata).

Tests expand registry, runtime policy, TUI registration, and executor unit coverage for projections, bounded paths, and lifecycle transitions.

^{Reviewed by Cursor Bugbot for commit 8166015. Bugbot is set up for automated code reviews on this repo. Configure here.}

kostandinang · 2026-07-01T02:34:05Z

Addressed the Bugbot review findings:

plan_only runs now advance past the source-copy step so report init and slices can continue (they used to stall).
execute_slice_start now accepts a completed run and picks the next unfinished slice, so multi-slice plans can run to the end.
execute_status now lists execute_test_result among the ported tools.
runId is validated before it is used to build file paths, so a value like ../escape can no longer read or write outside .brunch/cook/runs/.

Each fix has test coverage. npm run verify is green.

The FE-1089 handoff described the descriptive scaffold as still in progress; it is now superseded (PRs #274/#275/#276 open, executor arc underway). Handoff files are volatile transfer state, so retire it.

kostandinang · 2026-07-01T07:37:12Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Aligns src/orchestration with the TOPOLOGY.md convention used by every other src/** subtree (AGENTS.md topology-files rule). Updates the two canonical-doc references (memory/SPEC.md D99-L materialized-state list and memory/PLAN.md cook frontier traceability lines). No code change. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

The identical readRunMetadata(path) helper (try/JSON.parse/catch) was privately copy-pasted into 13 cook-*.ts lifecycle files. Move it to cook-run.ts as the exported readCookRunMetadata, alongside the run-dir and metadata-path helpers it already owns, and import it everywhere. Drop the now-unused readFile imports. Behavior identical; existing cook tests cover every caller. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Every cook transition tool hand-wrote the same run.json write followed by a { kind: 'write_file', path: metadataPath, ifExists: 'overwrite' } side-effect literal. Add persistCookRunMetadata to cook-run.ts, which writes the metadata and returns that canonical side-effect record, and adopt it across the 13 transition tools. Tools keep their own status guard, result shape, and any artifact write; only the metadata write + side-effect encoding is centralized. Drop now-unused writeFile imports. Behavior identical; existing cook tests cover every caller. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

The subtree owns the execute-mode projection seam and cook lifecycle contracts; 'executor' names that role in the codebase's own vocabulary (execute_* tools, executor prompt/runtime) and matches the single-word src/** house style. Directory rename only: cook-* filenames are unchanged. Updates the 23 Pi extension import paths, both TOPOLOGY.md files, and the src/executor path pointers in memory/SPEC.md and memory/PLAN.md. No behavior change. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Renames the 17 src/executor/cook-*.ts files (+ their tests) to drop the legacy cook- prefix (cook-run.ts -> run.ts, etc.), now that the subtree itself is named executor. Updates internal imports, the 23 Pi extension import paths, and the filename references in both TOPOLOGY.md files plus memory/SPEC.md and memory/PLAN.md. Left intentionally unchanged (separate surfaces): the Cook* exported symbols, the execute_cook_* Pi tool names and execute-cook-* extension dirs, the .brunch/cook/ runtime artifact paths, the cook-sandbox/ cook-agent-runner/cook-land frontier names, and the stashed src/app/cook-*.ts port work. No behavior change. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Renames the 17 execute-cook-* Pi extension dirs to execute-*, and the matching tool identifiers (execute_cook_* -> execute_*) and constants (BRUNCH_EXECUTE_COOK_*_TOOL -> BRUNCH_EXECUTE_*_TOOL) in session/schema/tool-names.ts, execute-status pendingTools, the extension registry, active-tools allowlist, executor.md prompt, .pi/settings.json, and the SPEC/PLAN references. No two tool names collide after the drop. Runtime .brunch/cook/ artifact paths, the Cook* exported symbols, and the cook-sandbox/cook-agent-runner/cook-land frontier names are unchanged. No behavior change. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Removes the legacy Cook/cook token from ~130 identifiers across the executor module and its Pi adapters: types (CookRunMetadata -> RunMetadata, CookPlanPreview -> PlanPreview, ExecuteCookRunCreateParams -> ExecuteRunCreateParams, ...), functions (createCookRun -> createRun, readCookRunMetadata -> readRunMetadata, copyCookHostSource -> copyHostSource, ...), and tool-param prose ('Cook run id' -> 'Run id'). The two dir-path helpers that would collapse to the ubiquitous local var names are given a Path suffix instead (cookRunDir -> runDirPath, cookWorktreeDir -> worktreeDirPath), matching sibling runMetadataPath / planFilePath / reportsPath. .brunch/cook/ runtime paths and the stashed CookExecutionPorts seam are unchanged. No behavior change. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Renames the orchestrator-cutover arc frontiers in memory/PLAN.md and memory/SPEC.md: cook-sandbox -> executor-sandbox, cook-agent-runner -> executor-agent-runner, cook-land -> executor-land, and the superseded cook-real-execution -> executor-real-execution. The cook-execution-ports seam name, CookExecutionPorts type, src/app/cook-*.ts port impls, and .brunch/cook/ paths are left for the stashed cook-sandbox work. Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Address Cursor Bugbot review findings on the fs-only cook lifecycle: - plan_only runs now advance to source_copied instead of stalling at source_policy_selected, so report init and slices can proceed. - execute_slice_start accepts slice_completed and picks the next incomplete slice, so multi-slice plans can walk the full chain. - execute_status lists execute_test_result among ported tools. - runId is validated before building filesystem paths, rejecting values like ../escape that would leave .brunch/cook/runs/.

The FE-1089 handoff described the descriptive scaffold as still in progress; it is now superseded (PRs #274/#275/#276 open, executor arc underway). Handoff files are volatile transfer state, so retire it.

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e7fee47. Configure here.}

Co-authored-by: Cursor <cursoragent@cursor.com>

lunelson

This sets up the executor tool surface cleanly around explicit run artifacts and side effects.

One thing I’d like to keep visible: active-tools.ts, pi-extensions.ts, and the executor prompt admit the full execute lifecycle in one scaffold step, while the later stack entries are still making individual steps real. That seems fine if the surface remains gated until the stack lands together; I would not want these tools reachable independently while some of the side-effecting steps are still placeholders.

kostandinang · 2026-07-01T15:21:57Z

This sets up the executor tool surface cleanly around explicit run artifacts and side effects.

One thing I’d like to keep visible: active-tools.ts, pi-extensions.ts, and the executor prompt admit the full execute lifecycle in one scaffold step, while the later stack entries are still making individual steps real. That seems fine if the surface remains gated until the stack lands together; I would not want these tools reachable independently while some of the side-effecting steps are still placeholders.

Addressed this: the descriptive lifecycle scaffold remains registered/testable, but CODE-mode active tools now expose only the read-only execute footholds. execute_status and the executor prompt now call out that artifact/lifecycle tools are inactive until the real-execution stack lands.

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread src/executor/report.ts

Comment thread src/executor/slice-start.ts Outdated

Comment thread src/.pi/extensions/agent-runtime/execute-status/index.ts

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread src/executor/run.ts Outdated

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/slice-start.ts Outdated

kostandinang mentioned this pull request Jul 1, 2026

FE-1109: Reconcile executor sandbox worktrees and test runner ports #275

Open

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/run.ts

Comment thread src/executor/worktree.ts

Comment thread src/.pi/settings.json

Comment thread src/executor/run-complete.ts

kostandinang self-assigned this Jul 1, 2026

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/slice-start.ts Outdated

Comment thread src/executor/slice-execute.ts Outdated

kostandinang requested a review from lunelson July 1, 2026 07:36

This was referenced Jul 1, 2026

re-sync and add notes about server refactor #277

Draft

FE-1111: Reconcile executor agent runner #278

Open

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/test-result.ts

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/run-complete.ts

kostandinang changed the title ~~FE-1089: Reconcile orchestrator with alpha branch~~ FE-1089: Reconcile executor with alpha branch Jul 1, 2026

kostandinang mentioned this pull request Jul 1, 2026

FE-1112: Reconcile run-local executor promotion #279

Open

kostandinang added 12 commits July 1, 2026 14:22

Add execute status foothold tool

2cbd06a

Add execution spec snapshot projection

47afa52

Add execute snapshot projection tool

c77515b

Update execute status ported tools

4c7050e

Sync orchestrator alpha cutover plan

21cc3f5

Add execute plan check tool

966fa69

Add execute plan outline tool

da0c758

Add execute plan outline artifact tool

829cb5a

Include criteria in execute plan outline

b82ee0c

Add executable plan draft tool

4df6234

Sync executable plan draft progress

2aa0122

Add executable plan draft artifact tool

65d1ef6

kostandinang and others added 23 commits July 1, 2026 14:32

Add execute cook slice request

9e99ad4

Add execute cook agent result ingestion

cfdae99

Add execute cook test result ingestion

2a03edf

Add execute cook slice completion

e043d63

Add execute cook run completion

4f87d50

Add execute cook Petri export

7eba412

Add execute cook promotion prepare

54c0c8f

Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

Reorder FE-1089: defer host land to cook-real-execution

5823fb5

Amp-Thread-ID: https://ampcode.com/threads/T-019f1a7b-422b-74bd-a47d-df4ac4ad810d Co-authored-by: Amp <amp@ampcode.com>

FE-1089: Remove stale handoff delivery notes

cf37aba

The FE-1089 handoff described the descriptive scaffold as still in progress; it is now superseded (PRs #274/#275/#276 open, executor arc underway). Handoff files are volatile transfer state, so retire it.

FE-1089: Make run completion idempotent

1a2d9b1

Co-authored-by: Cursor <cursoragent@cursor.com>

FE-1089: Bound slice advancement and output paths

3d42e72

Co-authored-by: Cursor <cursoragent@cursor.com>

FE-1089: Guard test result slice paths

88667e4

Co-authored-by: Cursor <cursoragent@cursor.com>

FE-1089: Reject empty run completion

bd7af0c

Co-authored-by: Cursor <cursoragent@cursor.com>

Resolve FE-1089 merge docs after rebase

e7fee47

Co-authored-by: Cursor <cursoragent@cursor.com>

kostandinang force-pushed the ka/fe-1089-orchestrator-alpha-cutover branch from 0e53a63 to e7fee47 Compare July 1, 2026 12:36

cursor Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread src/executor/launch.ts

FE-1089: Bound launch plan paths

16b1dbe

Co-authored-by: Cursor <cursoragent@cursor.com>

lunelson approved these changes Jul 1, 2026

View reviewed changes

FE-1089: Gate descriptive executor tools

8166015

kostandinang mentioned this pull request Jul 1, 2026

FE-1118: Reconcile host executor promotion #282

Open

Uh oh!

Conversation

kostandinang commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!