FE-877: brownfield promotion — commit the cook result onto cook/<runId> via git plumbing

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019ecb9a-9a08-733b-833d-76885fc8243a

Author: kostandinang

memory/PLAN.md

@@ -59,7 +59,7 @@ The May 2026 intent-spec, multi-chat, changeset-ledger, prompt/context, and agen
 4. `dogfood-spike` (ln-spike) — **(done — 2026-06-16)** ran a real brownfield cook (hand-authored 2-slice plan: feature + wiring, `node:http` app) against a throwaway git repo. **Verdict:** chain works end-to-end (CoW worktree, clean-tree gate, per-slice→`__epic__` merge composed the wiring, TDD red/green, working branch untouched); the agent wired the feature reachable and **self-authored a genuine boot-and-probe** integration test (imports the real entry, `listen(0)`, `http.get('/health')`, asserts not-404). Orphan did **not** reproduce — but reachability was **agent-discretion, not enforced** → confirms the *value* of `integration-oracle`/`app-runtime-probe` (independent, unshortcuttable reachability). Two refinements surfaced: the probe should own the boot mechanism (the agent had to invent a `.js→.ts` resolve hook), and dep-install was unexercised (zero-dep app). Bonus: the `Cannot find module` TDD red was handled as a test-red (not infra) — validates FE-872 slice 1 live.
 5. `app-runtime-probe` — **(slices 1–2 landed — FE-875, `runProbe` + `buildProbeSpec`)** build + boot + exercise the host app; the concrete reachability mechanism `integration-oracle` depends on (without it, "reachable" collapses back to "a test that imports the module"). Slice 1: boot + HTTP probe + reachable/not-reachable/infra classification + teardown. Slice 2: harness-owned `ProbeSpec` resolution — `buildProbeSpec(ProbeTarget)` allocates a free ephemeral port and assembles ready/feature URLs from boot-argv + *paths*, so a hardcoded port can't collide under parallel cook (the boot test's hand-rolled port dance is now the production primitive it dogfoods). Stays off the dispatch seam: argv + paths are inputs cook-time grounding will supply; the harness owns only the port pick + URL/env assembly (loopback-only; best-effort ephemeral port with an acknowledged TOCTOU window, no retry framework). Every probe HTTP call (readiness poll + feature request) carries a per-call `AbortSignal.timeout` so a server that accepts a connection but never responds can't hang the probe (and the cook) past the deadline; timeouts are overridable for tests. Remaining: mode-awareness, integration-oracle gating (where the `ProbeTarget` argv/paths come from = `integration-oracle` #6).
 6. `integration-oracle` — **(Half A + Half B seam landed — FE-876)** oracle asserts product reachability via `app-runtime-probe`. Half A (off-seam): `Epic.probe?: ProbeTarget` folds a `runProbe` result into the `verify-epic` verdict — after slices merge into `__epic__/<epicId>/`, the epic is `done` only when tests pass **and** the feature is reachable; `not-reachable` is the FE-800 orphan, `infra` is a harness fault. Probe gated behind tests passing (never boot a known-broken build); absent → unchanged unit verdict; reachability rides the existing `report.passed` routing. Half B seam: host-blind `Epic.reachability?: ReachabilityIntent` (architect-emittable, D160-K) + an injectable `ProbeGrounder` (`createPiActions({ groundProbe })`) that cook-time-resolves intent → concrete `ProbeTarget` by reading the worktree; `verify-epic` resolves via `probe ?? ground(reachability)`, a grounder that throws is an `infra` fault (visible, not a silent pass), intent without a grounder is an inert no-op. **Remaining (dispatch seam, lands atomically with the pi-harness contract):** the production `ProbeGrounder` (an `execute`-mode agent that reads the worktree) + architect emission of `reachability` intent — deferred together so intent is enforced the moment it's emitted (avoids perturbing the 3 reference fixtures). Runs in the FE-738 semantic lane. Promotes FE-800's integration-blind follow-on to a frontier. *(grounder impl depends on `agent-extension-host`)*
-7. `brownfield-promotion` — commit/merge the cook result into the user's checkout; extends FE-827's greenfield promotion to brownfield.
+7. `brownfield-promotion` — **(landed — FE-877, `promoteBrownfieldRun`)** commit a completed brownfield cook result onto the repo's own `cook/<runId>` branch as one reviewable commit; extends FE-827's greenfield promotion to brownfield and closes the cook-codebase-mode follow-on (the result no longer sits uncommitted in the worktree). Git plumbing only (`commit-tree` + CAS `update-ref`, parent = the existing `cook/<runId>` base, throwaway index + external work-tree), so the user's active branch, working tree, and index are never touched; gitignored deps don't land. Reuses `promotionSourceDir` to compose the tree across slice layouts. Auto-runs on a completed brownfield cook (no `--out` needed); merging into the working branch stays the **user's** call. Unblocks FE-872's brownfield dep-delta capture.
 8. `brunch-ship` — one-shot `brunch serve <specId>` wrapper (prep → recipe → cook → taste → plate), no manual steps. Arc 1 capstone.
 
 **Runtime umbrella + semantic substrate:**

src/orchestrator/src/cook-cli.ts

@@ -13,7 +13,7 @@ import { createPetrinautStreamServer, type PetrinautStreamServer } from './petri
 import { createPiActions } from './pi-actions.js';
 import { loadPlan } from './plan-loader.js';
 import { resolveToolchain } from './project-profile.js';
-import { promoteGreenfieldRun } from './promote-run.js';
+import { promoteBrownfieldRun, promoteGreenfieldRun } from './promote-run.js';
 import { parseSpecId, resolveLatestSpecPlanPath, specPlanPath, specsRootDir } from './spec-plan-paths.js';
 import { ToolchainTestRunner } from './test-runner.js';
 import type { Plan, PlanMode } from './types.js';
@@ -530,13 +530,49 @@ export async function runCook(opts: CookOptions): Promise<void> {
     console.error(`  ${result.reports.length} events → ${reportsPath}`);
     console.error('');
 
-    // Promotion-back is opt-in via --out and greenfield-only; a run that did
-    // not complete promotes nothing (the artifact stays inspectable).
-    if (opts.outDir) {
-      if (sandbox.kind === 'codebase') {
-        console.error(`  !  --out promotion is greenfield-only; brownfield output stays at ${sandboxDir}`);
+    // Brownfield promotion is automatic (the result already lives on the repo's
+    // own `cook/<runId>` branch); greenfield promotion is opt-in via --out. A run
+    // that did not complete promotes nothing — the artifact stays inspectable.
+    if (sandbox.kind === 'codebase') {
+      if (opts.outDir) {
+        console.error(`  !  --out is ignored for brownfield; the result lands on cook/${runId} in the repo`);
         console.error('');
-      } else if (!ok) {
+      }
+      if (!ok) {
+        console.error(`  !  run did not complete — nothing promoted. Artifact: ${sandboxDir}`);
+        console.error('');
+      } else {
+        try {
+          const source = promotionSourceDir({
+            sliceLayout,
+            sandboxDir,
+            runDir,
+            plan,
+            completedSliceIds: result.slices.filter((s) => s.status === 'completed').map((s) => s.sliceId),
+          });
+          for (const c of source.conflicts) {
+            console.error(
+              `  !  merge conflict on ${c.path} (slices ${c.slices.join(', ')}; kept ${c.winner})`,
+            );
+          }
+          const promoted = promoteBrownfieldRun({
+            sourceDir: sandbox.sourceDir,
+            sourceTreeDir: source.dir,
+            runId,
+          });
+          console.error(
+            `  ✓  promoted → ${promoted.branch} @ ${promoted.commit.slice(0, 8)}  (merge it into your branch when ready)`,
+          );
+          console.error('');
+        } catch (err) {
+          console.error(`  ✗  promotion failed: ${err instanceof Error ? err.message : String(err)}`);
+          console.error('');
+          recordCookExitStatus(false);
+          return;
+        }
+      }
+    } else if (opts.outDir) {
+      if (!ok) {
         console.error(`  !  run did not complete — nothing promoted. Artifact: ${sandboxDir}`);
         console.error('');
       } else {

src/orchestrator/src/promote-run.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { promoteGreenfieldRun } from './promote-run.js';
+import { promoteBrownfieldRun, promoteGreenfieldRun } from './promote-run.js';
 
 const dirs: string[] = [];
 const GIT_TEST_TIMEOUT_MS = 20_000;
@@ -205,3 +205,153 @@ describe('promoteGreenfieldRun', () => {
     GIT_TEST_TIMEOUT_MS,
   );
 });
+
+describe('promoteBrownfieldRun', () => {
+  const id = ['-c', 'user.name=t', '-c', 'user.email=t@e'];
+
+  // A user repo on `main` with a base commit, plus a cook/<runId> branch at the
+  // same base (as `git worktree add -b cook/<runId> … HEAD` would create).
+  function userRepo(): { dir: string; baseHead: string } {
+    const dir = mkdtempSync(join(tmpdir(), 'cook-userrepo-'));
+    dirs.push(dir);
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+    writeFileSync(join(dir, 'app.ts'), 'export const v = 1;\n');
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n');
+    execFileSync('git', ['add', '.'], { cwd: dir });
+    execFileSync('git', [...id, 'commit', '-q', '-m', 'base'], { cwd: dir });
+    execFileSync('git', ['branch', 'cook/r1'], { cwd: dir });
+    const baseHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim();
+    return { dir, baseHead };
+  }
+
+  // The composed cook result: a full tree (base + the cook delta).
+  function composedTree(): string {
+    const d = mkdtempSync(join(tmpdir(), 'cook-composed-'));
+    dirs.push(d);
+    writeFileSync(join(d, 'app.ts'), 'export const v = 2;\n'); // modified
+    writeFileSync(join(d, 'feature.ts'), 'export const f = true;\n'); // added
+    writeFileSync(join(d, '.gitignore'), 'node_modules/\n');
+    mkdirSync(join(d, 'node_modules'));
+    writeFileSync(join(d, 'node_modules', 'dep.js'), 'junk\n'); // gitignored — must not land
+    return d;
+  }
+
+  it(
+    'commits the composed tree onto cook/<runId>, leaving the active branch and working tree untouched',
+    () => {
+      const { dir, baseHead } = userRepo();
+      const tree = composedTree();
+      const branchesBefore = execFileSync('git', ['branch', '--list'], { cwd: dir, encoding: 'utf8' });
+
+      const result = promoteBrownfieldRun({ sourceDir: dir, sourceTreeDir: tree, runId: 'r1' });
+
+      // cook/r1 advanced by one commit on top of the base.
+      expect(result.branch).toBe('cook/r1');
+      expect(result.commit).not.toBe(baseHead);
+      const parent = execFileSync('git', ['rev-parse', 'cook/r1^'], { cwd: dir, encoding: 'utf8' }).trim();
+      expect(parent).toBe(baseHead);
+
+      // The commit's tree carries the delta — and not the gitignored deps.
+      const files = execFileSync('git', ['ls-tree', '-r', '--name-only', 'cook/r1'], {
+        cwd: dir,
+        encoding: 'utf8',
+      });
+      expect(files).toContain('feature.ts');
+      expect(files).toContain('app.ts');
+      expect(files).not.toContain('node_modules');
+      const appAtCook = execFileSync('git', ['show', 'cook/r1:app.ts'], { cwd: dir, encoding: 'utf8' });
+      expect(appAtCook).toContain('v = 2');
+
+      // The user's active branch (main), HEAD, working tree, and index are untouched.
+      expect(execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim()).toBe(
+        baseHead,
+      );
+      expect(
+        execFileSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim(),
+      ).toBe('main');
+      expect(readFileSync(join(dir, 'app.ts'), 'utf8')).toContain('v = 1');
+      expect(existsSync(join(dir, 'feature.ts'))).toBe(false);
+      expect(execFileSync('git', ['status', '--porcelain'], { cwd: dir, encoding: 'utf8' })).toBe('');
+      // Only cook/r1 moved — no stray branches.
+      expect(execFileSync('git', ['branch', '--list'], { cwd: dir, encoding: 'utf8' })).toBe(branchesBefore);
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
+  it('throws when the cook/<runId> branch is absent (must be created by the worktree)', () => {
+    const { dir } = userRepo();
+    const tree = composedTree();
+    expect(() => promoteBrownfieldRun({ sourceDir: dir, sourceTreeDir: tree, runId: 'missing' })).toThrow(
+      /cook\/missing/,
+    );
+  });
+
+  it(
+    'works in the real linked-worktree topology — the live sandbox worktree is left to be discarded, the main checkout untouched',
+    () => {
+      // Mirror production: cook/r1 exists *because* a linked worktree checked it out.
+      const dir = mkdtempSync(join(tmpdir(), 'cook-userrepo-'));
+      dirs.push(dir);
+      execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+      writeFileSync(join(dir, 'app.ts'), 'export const v = 1;\n');
+      writeFileSync(join(dir, '.gitignore'), 'node_modules/\n');
+      execFileSync('git', ['add', '.'], { cwd: dir });
+      execFileSync('git', [...id, 'commit', '-q', '-m', 'base'], { cwd: dir });
+      const wt = join(dir, 'wt');
+      execFileSync('git', ['worktree', 'add', '-q', '-b', 'cook/r1', wt, 'HEAD'], { cwd: dir });
+      const baseHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim();
+
+      const result = promoteBrownfieldRun({ sourceDir: dir, sourceTreeDir: composedTree(), runId: 'r1' });
+
+      // Only cook/r1 moved (one commit on the base).
+      expect(execFileSync('git', ['rev-parse', 'cook/r1^'], { cwd: dir, encoding: 'utf8' }).trim()).toBe(
+        baseHead,
+      );
+      expect(execFileSync('git', ['show', 'cook/r1:app.ts'], { cwd: dir, encoding: 'utf8' })).toContain(
+        'v = 2',
+      );
+      // The main checkout is wholly untouched.
+      expect(execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim()).toBe(
+        baseHead,
+      );
+      expect(
+        execFileSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim(),
+      ).toBe('main');
+      expect(readFileSync(join(dir, 'app.ts'), 'utf8')).toContain('v = 1');
+      // tracked files untouched (the linked `wt/` dir is an expected untracked entry).
+      expect(
+        execFileSync('git', ['status', '--porcelain', '--untracked-files=no'], {
+          cwd: dir,
+          encoding: 'utf8',
+        }),
+      ).toBe('');
+      expect(result.commit).not.toBe(baseHead);
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
+  it('stages tracked deletions — a file removed in the composed tree is removed in the cook commit', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'cook-userrepo-'));
+    dirs.push(dir);
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+    writeFileSync(join(dir, 'keep.ts'), 'keep\n');
+    writeFileSync(join(dir, 'old.ts'), 'remove me\n');
+    execFileSync('git', ['add', '.'], { cwd: dir });
+    execFileSync('git', [...id, 'commit', '-q', '-m', 'base'], { cwd: dir });
+    execFileSync('git', ['branch', 'cook/r1'], { cwd: dir });
+
+    // Composed tree drops old.ts.
+    const tree = mkdtempSync(join(tmpdir(), 'cook-composed-'));
+    dirs.push(tree);
+    writeFileSync(join(tree, 'keep.ts'), 'keep\n');
+
+    promoteBrownfieldRun({ sourceDir: dir, sourceTreeDir: tree, runId: 'r1' });
+
+    const files = execFileSync('git', ['ls-tree', '-r', '--name-only', 'cook/r1'], {
+      cwd: dir,
+      encoding: 'utf8',
+    });
+    expect(files).toContain('keep.ts');
+    expect(files).not.toContain('old.ts');
+  });
+});

src/orchestrator/src/promote-run.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync } from 'node:fs';
-import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 
 export type PromoteResult = { target: string; branch: string; commit: string };
 
@@ -11,8 +12,16 @@ export type PromoteOptions = {
   force: boolean;
 };
 
-function git(args: string[], cwd: string): string {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+export type BrownfieldPromoteOptions = {
+  /** The user's repo root the brownfield cook ran against (a worktree of it). */
+  sourceDir: string;
+  /** The composed final tree to land (from `promotionSourceDir`). */
+  sourceTreeDir: string;
+  runId: string;
+};
+
+function git(args: string[], cwd: string, env?: NodeJS.ProcessEnv): string {
+  return execFileSync('git', args, { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
 // Deterministic committer so promotion never depends on (or mutates) global git config.
@@ -110,3 +119,65 @@ export function promoteGreenfieldRun(opts: PromoteOptions): PromoteResult {
   const commit = git(['rev-parse', 'HEAD'], target);
   return { target, branch, commit };
 }
+
+/**
+ * Land a completed *brownfield* run's composed tree onto the `cook/<runId>`
+ * branch of the user's repo as one reviewable commit — the brownfield analogue
+ * of `promoteGreenfieldRun`. The brownfield sandbox was created with
+ * `git worktree add -b cook/<runId> … HEAD`, so the branch already exists at the
+ * base the run started from; this commits the result on top of it via plumbing
+ * (`commit-tree` + compare-and-swap `update-ref`) using a throwaway index and an
+ * external work-tree, so the user's real working tree, index, and active branch
+ * are never touched. Merging `cook/<runId>` into the working branch stays the
+ * user's call — promotion never freelances into it.
+ */
+export function promoteBrownfieldRun(opts: BrownfieldPromoteOptions): PromoteResult {
+  const sourceDir = resolve(opts.sourceDir);
+  const sourceTreeDir = resolve(opts.sourceTreeDir);
+  const branch = `cook/${opts.runId}`;
+  const ref = `refs/heads/${branch}`;
+
+  // The branch must already exist (the sandbox branched it from HEAD); its tip is
+  // the parent we commit on top of and the CAS expected-value for update-ref.
+  let parent: string;
+  try {
+    parent = git(['rev-parse', '--verify', ref], sourceDir);
+  } catch {
+    throw new Error(
+      `Brownfield promotion expects an existing ${branch} branch in ${sourceDir} (created by the cook worktree).`,
+    );
+  }
+
+  // Absolute git dir so a throwaway index + external work-tree can target the
+  // user's object store without depending on cwd.
+  const gitDir = resolve(sourceDir, git(['rev-parse', '--git-dir'], sourceDir));
+  const tmp = mkdtempSync(join(tmpdir(), 'brunch-promote-'));
+  const env: NodeJS.ProcessEnv = { ...process.env, GIT_INDEX_FILE: join(tmp, 'index') };
+  const plumb = ['--git-dir', gitDir, '--work-tree', sourceTreeDir];
+  try {
+    // Seed the index from the base, then stage the composed tree as the delta —
+    // adds, modifications, and deletions, all relative to the base commit.
+    git([...plumb, 'read-tree', parent], sourceDir, env);
+    git([...plumb, 'add', '-A'], sourceDir, env);
+    const tree = git(['--git-dir', gitDir, 'write-tree'], sourceDir, env);
+    const commit = git(
+      [
+        ...COMMIT_IDENTITY,
+        '--git-dir',
+        gitDir,
+        'commit-tree',
+        tree,
+        '-p',
+        parent,
+        '-m',
+        `cook: ${opts.runId}`,
+      ],
+      sourceDir,
+      env,
+    );
+    git(['--git-dir', gitDir, 'update-ref', ref, commit, parent], sourceDir, env);
+    return { target: sourceDir, branch, commit };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}