pi-pstack-native 0.0.0-stage → 1.0.0

package/test/delivery-stack.test.ts

@@ -0,0 +1,106 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtempSync,mkdirSync,writeFileSync,rmSync,readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {git,fingerprint} from '../src/artifacts/fingerprint.ts';
+import {verify} from '../src/verification/runner.ts';
+import {prepareStack,openStack} from '../src/delivery/stack.ts';
+import {collectReviewThreads} from '../src/delivery/review-threads.ts';
+import {refresh,eligibility,watchFrontier} from '../src/delivery/frontier.ts';
+import type {Frontier} from '../src/delivery/frontier.ts';
+import {protocol} from '../src/runtime/protocol.ts';
+import type {PullRequest} from '../src/delivery/provider.ts';
+
+test('linear PR stack has per-parent verification, dry-run, head-bound opening, idempotent retry and stale-plan rejection',async()=>{
+ const dir=mkdtempSync(join(process.cwd(),'.stack-test-')),previous=process.env.PSTACK_NATIVE_HOME;process.env.PSTACK_NATIVE_HOME=join(dir,'state');
+ try{
+  const {root,refs,prs,opens,provider,lanes}=await stackFixture(dir);
+  const plan=await prepareStack({repo:'test/stack',rootBase:'main',owner:'operator',lanes},provider);
+  assert.deepEqual(plan.entries.map(e=>e.base),['main','feature/lane1']);assert.ok(plan.entries.every(e=>/^[a-f0-9]{40}$/.test(e.patchId)));
+  await openStack(plan,provider);assert.equal(opens.length,0);
+  await openStack(plan,provider,true);assert.deepEqual(opens.map(p=>[p.base,p.head]),[['main','feature/lane1'],['feature/lane1','feature/lane2']]);assert.ok(opens.every(p=>p.body.includes('## Verification') && p.body.includes('Patch ID')));
+  await openStack(plan,provider,true);assert.equal(opens.length,2);
+  prs.get(2)!.baseRef='main';await assert.rejects(openStack(plan,provider,true),/EXISTING_PR_MISMATCH/);prs.get(2)!.baseRef='feature/lane1';
+  const spec={id:'stack-fixture',repo:'test/stack',repoId:fingerprint(root).repoId,numbers:[1,2],owner:'operator',rootBase:'main'};
+  const f=await refresh(spec,provider as any);assert.equal(watchFrontier(f).state,'reviewable');assert.deepEqual(eligibility(f)[1].blockers,['LOWER_UNMERGED']);
+  prs.get(2)!.baseRef='main';await assert.rejects(refresh(spec,provider as any),/TOPOLOGY/);prs.get(2)!.baseRef='feature/lane1';
+  prs.get(1)!.state='MERGED';const advanced=await refresh(spec,provider as any);assert.ok(eligibility(advanced)[1].blockers.includes('FRONTIER_BASE_NOT_TRUNK'));assert.equal(watchFrontier(advanced,{number:1,headSha:prs.get(1)!.headSha,digest:f.digest}).state,'advance');prs.get(1)!.state='OPEN';
+  prs.get(1)!.reviewThreads!.unresolved=1;assert.ok(eligibility(await refresh(spec,provider as any))[0].blockers.includes('UNRESOLVED_REVIEW_THREADS'));
+  prs.get(1)!.reviewThreads=undefined;assert.ok(eligibility(await refresh(spec,provider as any))[0].blockers.includes('REVIEW_THREADS_NOT_CHECKED'));
+  refs.set('main','f'.repeat(40));await assert.rejects(openStack(plan,provider,true));assert.equal(opens.length,2);
+ }finally{if(previous===undefined)delete process.env.PSTACK_NATIVE_HOME;else process.env.PSTACK_NATIVE_HOME=previous;rmSync(dir,{recursive:true,force:true});}
+});
+const page=(nodes:any[],next:string|null)=>({data:{repository:{pullRequest:{reviewThreads:{nodes,pageInfo:{hasNextPage:next!==null,endCursor:next}}}}}});
+const thread=(id:string,resolved:boolean)=>({id,isResolved:resolved,comments:{nodes:[{author:{login:'bugbot[bot]'},createdAt:'2026-10-14T00:00:00Z'}]}});
+test('review threads beyond page one block; cursor loops, incomplete pages and API errors fail closed',async()=>{
+ const calls:(string|null)[]=[];const summary=await collectReviewThreads(async cursor=>{calls.push(cursor);return cursor===null?page(Array.from({length:100},(_,i)=>thread(String(i),true)),'next'):page([thread('late',false)],null);});
+ assert.equal(summary.total,101);assert.equal(summary.unresolved,1);assert.equal(summary.bugbotUnresolved,1);assert.deepEqual(calls,[null,'next']);
+ await assert.rejects(collectReviewThreads(async()=>page([], 'repeat')),/CURSOR_REPEATED/);
+ await assert.rejects(collectReviewThreads(async()=>({data:{repository:{pullRequest:{reviewThreads:{nodes:[],pageInfo:{hasNextPage:true,endCursor:null}}}}}})),/CURSOR/);
+ await assert.rejects(collectReviewThreads(async()=>({errors:[{message:'rate limited'}]})),/UNAVAILABLE/);
+});
+test('actual GitHub adapter paginates reviews and rejects a moved PR during its read',async()=>{
+ const {GitHubCLI}=await import('../src/delivery/provider.ts');let pages=0,reads=0,moved=false;
+ const execute=(args:string[])=>{
+  if(args[0]==='pr' && args[1]==='view') {reads++;return JSON.stringify({number:1,headRefOid:moved && reads%2===0?'c'.repeat(40):'b'.repeat(40),baseRefOid:'a'.repeat(40),headRefName:'feature/a',baseRefName:'main',state:'OPEN',isDraft:false,mergeable:'MERGEABLE',mergeStateStatus:'CLEAN',reviewDecision:'APPROVED',statusCheckRollup:[{conclusion:'SUCCESS'}]});}
+  assert.equal(args[0],'api');assert.equal(args[1],'graphql');pages++;return JSON.stringify(args.includes('after=next')?page([thread('late',false)],null):page([thread('early',true)],'next'));
+ };
+ const provider=new GitHubCLI(execute),pr=await provider.read('test/stack',1);assert.equal(pages,2);assert.equal(pr.reviewThreads?.unresolved,1);assert.equal(pr.headRef,'feature/a');
+ moved=true;await assert.rejects(provider.read('test/stack',1),/PR_CHANGED_DURING_READ/);
+});
+/** Local fixture: one worktree and one accepted ledger per lane, and a PR store that stands in for GitHub. */
+async function stackFixture(dir:string,count=2,createdHead?:(head:string)=>string) {
+ const root=join(dir,'root');mkdirSync(root);git(root,['init','-q','-b','main']);git(root,['config','user.name','Test']);git(root,['config','user.email','test@example.invalid']);git(root,['remote','add','origin','https://github.com/test/stack.git']);writeFileSync(join(root,'base'),'base');git(root,['add','.']);git(root,['commit','-qm','base']);
+ const refs=new Map([['main',git(root,['rev-parse','HEAD'])]]),prs=new Map<number,PullRequest>(),opens:{base:string;head:string;body:string}[]=[];
+ const provider={async branchHead(_repo:string,head:string){return refs.get(head)!;},async find(_repo:string,head:string){return [...prs.values()].find(p=>p.headRef===head)?.number ?? null;},async read(_repo:string,n:number){return structuredClone(prs.get(n)!);},async open(repo:string,base:string,head:string,_title:string,bodyFile:string){const number=prs.size+1;opens.push({base,head,body:readFileSync(bodyFile,'utf8')});prs.set(number,{repo,number,headRef:head,baseRef:base,baseSha:refs.get(base)!,headSha:createdHead?createdHead(head):refs.get(head)!,state:'OPEN',draft:false,mergeState:'CLEAN',mergeable:'MERGEABLE',ci:'passed',review:'approved',reviewThreads:{status:'checked',unresolved:0,bugbotUnresolved:0,total:0}});return `https://github.com/test/stack/pull/${number}`;}};
+ const lanes:import("../src/delivery/stack.ts").StackLane[]=[];let parent=refs.get('main')!;
+ for(let i=1;i<=count;i++) {
+  const cwd=join(dir,`lane${i}`),head=`feature/lane${i}`;git(root,['worktree','add','-qb',head,cwd,parent]);writeFileSync(join(cwd,`unit${i}`),'ready');git(cwd,['add','.']);git(cwd,['commit','-qm',`unit${i}`]);const fp=fingerprint(cwd,'committed');refs.set(head,fp.commitSha);
+  const cmd=[process.execPath,'-e',`process.exit(require('node:fs').readFileSync('unit${i}','utf8')==='ready'?0:1)`];
+  const b:any={id:`lane${i}`,revision:1,contractLevel:'strict',goal:'unit',scope:{include:['**'],exclude:[],repoId:fp.repoId},contextRefs:[],acceptance:[{id:'done',description:'ready',required:true,gateIds:['surface']}],verification:[{id:'surface',kind:'command',command:cmd,sideEffect:'none',category:'behavior'}],timeboxSeconds:30,forbidden:['remote-write'],standingOrders:[],reportFormat:'task-report-v1'};
+  const report:any={status:'completed',artifactRefs:[],base:parent,head:fp.commitSha,commandsRun:[],evidenceRefs:[],deviations:[],unresolved:[],nextActions:[]};
+  const ledger=await verify(cwd,b,{pr:{repoId:fp.repoId,number:i,headSha:fp.commitSha,baseSha:parent},report,policy:{commands:[cmd]}});assert.equal(ledger.contractAccepted,true);
+  lanes.push({key:`unit${i}`,cwd,head,ledgerId:ledger.id,title:`Unit ${i}`});parent=fp.commitSha;
+ }
+ return {root,refs,prs,opens,provider,lanes};
+}
+const cleanLane=(over:Partial<PullRequest>={}):PullRequest=>({repo:'test/stack',number:1,headRef:'feature/a',baseRef:'main',headSha:'a'.repeat(40),baseSha:'b'.repeat(40),state:'OPEN',draft:false,mergeState:'CLEAN',mergeable:'MERGEABLE',ci:'passed',review:'approved',reviewThreads:{status:'checked',unresolved:0,bugbotUnresolved:0,total:0},...over});
+const oneLaneFrontier=(pr:PullRequest):Frontier=>({id:'probe-eligibility',repoId:'probe',repo:'test/stack',numbers:[pr.number],owner:'operator',rootBase:'main',generation:1,digest:'probe',checkedAt:'',prs:[pr]});
+function stateHome(t:any){const dir=mkdtempSync(join(process.cwd(),'.stack-state-')),previous=process.env.PSTACK_NATIVE_HOME;process.env.PSTACK_NATIVE_HOME=join(dir,'state');t.after(()=>{if(previous===undefined)delete process.env.PSTACK_NATIVE_HOME;else process.env.PSTACK_NATIVE_HOME=previous;rmSync(dir,{recursive:true,force:true});});}
+
+test('draft and merge state must be explicit and clean before a PR is eligible',(t)=>{
+ stateHome(t);
+ const blockers=(over:Partial<PullRequest>)=>eligibility(oneLaneFrontier(cleanLane(over)))[0].blockers.filter(b=>b!=='CURRENT_VERIFICATION_REQUIRED');
+ assert.deepEqual(blockers({}),[]);
+ assert.deepEqual(blockers({draft:true}),['PR_DRAFT']);
+ assert.deepEqual(blockers({draft:undefined as any}),['PR_DRAFT']);
+ assert.deepEqual(blockers({mergeState:'DIRTY'}),['MERGE_STATE_DIRTY']);
+ assert.deepEqual(blockers({mergeState:'BEHIND'}),['MERGE_STATE_BEHIND']);
+ assert.deepEqual(blockers({mergeState:undefined as any}),['MERGE_STATE_MISSING']);
+ assert.deepEqual(blockers({mergeState:'SOMETHING_NEW'}),['MERGE_STATE_SOMETHING_NEW']);
+ assert.deepEqual(blockers({mergeable:undefined as any}),['STATE_UNCERTAIN']);
+});
+
+test('the first frontier requires an operator rootBase instead of adopting a PR base',async(t)=>{
+ stateHome(t);
+ const provider={async read(){return structuredClone(cleanLane({baseRef:'feature/retargeted'}));}};
+ const spec={id:'probe-root',repoId:'probe',repo:'test/stack',numbers:[1],owner:'operator'};
+ await assert.rejects(refresh(spec,provider as any),/STACK_ROOT_BASE_REQUIRED/);
+ const f=await refresh({...spec,rootBase:'main'},provider as any);
+ assert.equal(f.rootBase,'main');
+ assert.ok(eligibility(f)[0].blockers.includes('FRONTIER_BASE_NOT_TRUNK'));
+ assert.equal((await refresh(spec,provider as any)).rootBase,'main');
+ await assert.rejects(refresh({...spec,rootBase:'release'},provider as any),/STACK_ROOT_BASE_CHANGED/);
+});
+
+test('a branch that moves during PR creation revokes that lane and stops opening later lanes',async()=>{
+ const dir=mkdtempSync(join(process.cwd(),'.stack-move-')),previous=process.env.PSTACK_NATIVE_HOME;process.env.PSTACK_NATIVE_HOME=join(dir,'state');
+ try{
+  const {opens,provider,lanes}=await stackFixture(dir,2,()=>'9'.repeat(40));
+  const plan=await prepareStack({repo:'test/stack',rootBase:'main',owner:'operator',lanes},provider);
+  await assert.rejects(openStack(plan,provider,true),/STACK_CREATED_PR_MISMATCH/);
+  assert.equal(opens.length,1);
+  assert.equal(protocol().invalidations[lanes[0]!.ledgerId]!.reason,'PR_CREATED_FROM_UNVERIFIED_REFS');
+  assert.equal(protocol().invalidations[lanes[1]!.ledgerId],undefined);
+ }finally{if(previous===undefined)delete process.env.PSTACK_NATIVE_HOME;else process.env.PSTACK_NATIVE_HOME=previous;rmSync(dir,{recursive:true,force:true});}
+});

package/test/dispatch.test.ts

@@ -0,0 +1,171 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { capture, fingerprint, git, ownerOf } from "../src/artifacts/fingerprint.ts";
+import { WorkflowEngine } from "../src/workflow/engine.ts";
+import { ProgramCoordinator } from "../src/program/coordinator.ts";
+import { briefDigest, buildDispatch, commitDispatch, dispatchVeto } from "../src/program/dispatch.ts";
+import { workflowPath } from "../src/runtime/home.ts";
+import { protocol, transact } from "../src/runtime/protocol.ts";
+import { listJson, readJson, writeJsonAtomic } from "../src/runtime/store.ts";
+import type { WorkflowRecord } from "../src/runtime/types.ts";
+import type { TaskBrief } from "../src/contracts/types.ts";
+
+function fixture() {
+  const root = mkdtempSync(join(process.cwd(), ".test-dispatch-"));
+  const repo = join(root, "repo");
+  mkdirSync(repo);
+  process.env.PSTACK_NATIVE_HOME = join(root, "state");
+  git(repo, ["init", "-q"]);
+  git(repo, ["config", "user.name", "Test"]);
+  git(repo, ["config", "user.email", "test@example.invalid"]);
+  writeFileSync(join(repo, "source.txt"), "baseline");
+  git(repo, ["add", "."]);
+  git(repo, ["commit", "-qm", "baseline"]);
+  return { root, repo, cleanup() { rmSync(root, { recursive: true, force: true }); delete process.env.PSTACK_NATIVE_HOME; } };
+}
+
+function brief(repo: string, id: string): TaskBrief {
+  return {
+    id, revision: 1, contractLevel: "strict", goal: "Check source",
+    scope: { repoId: fingerprint(repo).repoId, include: ["**"], exclude: [] },
+    contextRefs: [], acceptance: [{ id: "ac", description: "source valid", required: true, gateIds: ["file"] }],
+    verification: [{ id: "file", kind: "file", path: "source.txt", pattern: "baseline", category: "typecheck" }],
+    forbidden: [], standingOrders: [], reportFormat: "task-report-v1", timeboxSeconds: 30,
+  };
+}
+
+function report(fp: { commitSha: string }) {
+  return { status: "completed" as const, base: fp.commitSha, head: fp.commitSha, artifactRefs: [], commandsRun: [], evidenceRefs: [], deviations: [], unresolved: [], nextActions: [] };
+}
+
+function harness(repo: string) {
+  const agents = new Map<string, any>();
+  const state = { runs: 0 };
+  const host: any = {
+    get: (id: string) => agents.get(id),
+    async run(spec: any) {
+      state.runs += 1;
+      const fp = capture(spec.cwd, spec.id, [], "working", { kind: "baseline", owner: ownerOf(spec.brief, { workflowId: spec.workflowId, callKey: spec.callKey }) }).fingerprint;
+      const agent = { ...spec, state: "completed", cwd: spec.cwd, baseline: fp, report: report(fp), result: "checked" };
+      agents.set(agent.id, agent);
+      return agent;
+    },
+    async recover(agent: any) { return agent; },
+    async stop(id: string) { return { ...agents.get(id), state: "cancelled" }; },
+  };
+  const engine = new WorkflowEngine(host);
+  const coordinator = new ProgramCoordinator(engine);
+  const ctx: any = { cwd: repo, sessionManager: { getSessionId: () => "session" } };
+  const workflows = () => listJson<WorkflowRecord>(dirname(workflowPath("x")));
+  return { engine, coordinator, ctx, runs: () => state.runs, workflows };
+}
+
+function program(coordinator: ProgramCoordinator, repo: string) {
+  return coordinator.create("session", [{ key: "unit", spec: { cwd: repo, nodes: [{ key: "read", profile: "scout", task: "inspect", brief: brief(repo, "unit") }] } }]);
+}
+
+test("a crash between the dispatch commit and the workflow file rebuilds it from the record", async (t) => {
+  const f = fixture();
+  try {
+    const h = harness(f.repo);
+    const p = program(h.coordinator, f.repo);
+    const materialize = h.engine.materialize.bind(h.engine);
+    let crash = true;
+    t.mock.method(h.engine, "materialize", (record: WorkflowRecord) => {
+      if (crash) { crash = false; throw new Error("injected crash before the workflow file"); }
+      return materialize(record);
+    });
+    await assert.rejects(() => h.coordinator.run(p.id, h.ctx), /injected crash/);
+    const committed = h.coordinator.get(p.id, "session").units[0]!;
+    assert.ok(committed.workflowId, "the unit link commits with the dispatch record");
+    assert.equal(existsSync(workflowPath(committed.workflowId!)), false, "no workflow file exists yet");
+    assert.equal(h.runs(), 0, "no child starts before the file is rebuilt");
+    const dispatches = Object.values(protocol().dispatches);
+    assert.equal(dispatches.length, 1);
+    assert.equal(dispatches[0]!.state, "committed");
+
+    await h.coordinator.run(p.id, h.ctx);
+    assert.equal(h.runs(), 1);
+    assert.equal(h.workflows().length, 1);
+    assert.equal(h.workflows()[0]!.id, committed.workflowId);
+    assert.equal(Object.values(protocol().dispatches).length, 1, "recovery reuses the committed dispatch");
+    assert.equal(Object.values(protocol().dispatches)[0]!.state, "materialized");
+  } finally { t.mock.restoreAll(); f.cleanup(); }
+});
+
+test("duplicate recovery never creates a second dispatch or workflow file", async (t) => {
+  const f = fixture();
+  try {
+    const h = harness(f.repo);
+    const p = program(h.coordinator, f.repo);
+    const materialize = h.engine.materialize.bind(h.engine);
+    let crash = true;
+    t.mock.method(h.engine, "materialize", (record: WorkflowRecord) => {
+      if (crash) { crash = false; throw new Error("injected crash"); }
+      return materialize(record);
+    });
+    await assert.rejects(() => h.coordinator.run(p.id, h.ctx), /injected crash/);
+    await h.coordinator.run(p.id, h.ctx);
+    await h.coordinator.run(p.id, h.ctx);
+    assert.equal(h.runs(), 1);
+    assert.equal(h.workflows().length, 1);
+    assert.equal(Object.values(protocol().dispatches).length, 1);
+    assert.deepEqual(Object.values(protocol().dispatches).map((d) => d.workflowId), [h.workflows()[0]!.id]);
+  } finally { t.mock.restoreAll(); f.cleanup(); }
+});
+
+test("a program unit that points at an unregistered workflow file is refused", async () => {
+  const f = fixture();
+  try {
+    const h = harness(f.repo);
+    const p = program(h.coordinator, f.repo);
+    const orphan = h.engine.create({ cwd: f.repo, nodes: [{ key: "read", profile: "scout", task: "inspect", brief: brief(f.repo, "orphan") }] });
+    transact("test-orphan-link", p.id, "test", (s) => {
+      const unit = s.programs[p.id].units[0];
+      unit.workflowId = orphan.id;
+      unit.state = "running";
+      return null;
+    });
+    await assert.rejects(() => h.coordinator.run(p.id, h.ctx), /ORPHAN_WORKFLOW/);
+    assert.equal(h.runs(), 0);
+    assert.equal(h.workflows().length, 1, "the refused unit creates no second workflow");
+    assert.equal(Object.keys(protocol().dispatches).length, 0);
+  } finally { f.cleanup(); }
+});
+
+test("a workflow file rewritten after the commit is reported as drift", async () => {
+  const f = fixture();
+  try {
+    const h = harness(f.repo);
+    const p = program(h.coordinator, f.repo);
+    await h.coordinator.run(p.id, h.ctx);
+    const id = h.coordinator.get(p.id, "session").units[0]!.workflowId!;
+    const dispatch = Object.values(protocol().dispatches)[0]!;
+    assert.equal(dispatch.workflowId, id);
+    assert.equal(dispatch.briefDigest, briefDigest(h.workflows()[0]!));
+    const file = readJson<WorkflowRecord>(workflowPath(id), undefined as any);
+    file.calls.read!.brief!.standingOrders = ["rewritten outside the transaction"];
+    file.updatedAt = new Date().toISOString();
+    writeJsonAtomic(workflowPath(id), file);
+    assert.equal(dispatchVeto(id, readJson<WorkflowRecord>(workflowPath(id), undefined as any)), "DISPATCH_DRIFT");
+  } finally { f.cleanup(); }
+});
+
+test("the dispatch record carries the orders revision and one stable identity", async () => {
+  const f = fixture();
+  try {
+    const h = harness(f.repo);
+    const p = program(h.coordinator, f.repo);
+    h.coordinator.updateOrders(p.id, "session", ["rule"], "operator update");
+    await h.coordinator.run(p.id, h.ctx);
+    const dispatch = Object.values(protocol().dispatches)[0]!;
+    assert.equal(dispatch.ordersRevision, 1);
+    assert.equal(dispatch.programId, p.id);
+    assert.equal(dispatch.unitKey, "unit");
+    const rebuilt = buildDispatch({ programId: p.id, unitKey: "unit", owner: "session", workflow: dispatch.workflow, ordersRevision: 1 });
+    assert.equal(rebuilt.id, dispatch.id, "the dispatch identity is deterministic per program unit");
+    assert.equal(commitDispatch(protocol(), rebuilt).id, dispatch.id);
+  } finally { f.cleanup(); }
+});

package/test/e2e/fixture-child.mjs

@@ -0,0 +1,33 @@
+const [mode, ...rest] = process.argv.slice(2);
+
+if (mode === "ship") {
+  const [port, checkout, home, repoId, repo, number, token, crash] = rest;
+  process.env.PSTACK_NATIVE_HOME = home;
+  const { ship } = await import("../../src/delivery/frontier.ts");
+  const { githubClient } = await import("./harness.ts");
+  const spec = { id: `e2e-ship-${number}`, repoId, repo, numbers: [Number(number)], owner: "e2e-operator" };
+  try {
+    const result = await ship(spec, githubClient(Number(port), crash, repo), { token, dryRun: false });
+    process.stdout.write(`SHIPPED ${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stdout.write(`SHIP-FAILED ${error.message}\n`);
+    process.exitCode = 1;
+  }
+} else if (mode === "workflow") {
+  const [port, home, agentDir, checkout, sessionDir] = rest;
+  process.env.PSTACK_NATIVE_HOME = home;
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  const { AgentHost } = await import("../../src/agent/host.ts");
+  const { WorkflowEngine } = await import("../../src/workflow/engine.ts");
+  const { openParentContext, strictWorkflowSpec, SIGKILL_SESSION_ID } = await import("./parent-context.ts");
+  const parent = await openParentContext({ agentDir, cwd: checkout, sessionDir, modelPort: Number(port), sessionId: SIGKILL_SESSION_ID });
+  const engine = new WorkflowEngine(new AgentHost());
+  const record = engine.create(strictWorkflowSpec(checkout, parent.ctx.sessionManager.getSessionId()));
+  process.stdout.write(`WORKFLOW ${record.id}\n`);
+  const finished = await engine.run(record.id, parent.ctx);
+  process.stdout.write(`COMPLETED ${finished.state}\n`);
+  parent.dispose();
+} else {
+  process.stderr.write(`unknown fixture child mode: ${mode}\n`);
+  process.exit(2);
+}

package/test/e2e/harness.ts

@@ -0,0 +1,282 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { createServer, request, type Server } from "node:http";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const OFFLINE = "[offline]";
+export const FAKE_PROVIDER = "[fake-provider]";
+export const LIVE = "[live]";
+export const MODEL = "loopback-model";
+
+export function listen(server: Server): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolvePort((server.address() as { port: number }).port); });
+  });
+}
+
+export function closeServer(server: Server): Promise<void> {
+  server.closeAllConnections();
+  return new Promise((resolveClose) => server.close(() => resolveClose()));
+}
+
+export function post(port: number, path: string, body: unknown): Promise<{ status: number; json: any }> {
+  return new Promise((resolvePost, reject) => {
+    const payload = JSON.stringify(body ?? {});
+    const req = request({ host: "127.0.0.1", port, path, method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) } }, (res) => {
+      let text = "";
+      res.on("data", (chunk) => { text += chunk; });
+      res.on("end", () => {
+        try { resolvePost({ status: res.statusCode ?? 0, json: text ? JSON.parse(text) : {} }); }
+        catch { reject(new Error(`Non-JSON response from ${path}: ${text.slice(0, 200)}`)); }
+      });
+    });
+    req.on("error", reject);
+    req.end(payload);
+  });
+}
+
+export function readBody(source: NodeJS.ReadableStream): Promise<string> {
+  return new Promise((resolveBody, reject) => {
+    let text = "";
+    source.on("data", (chunk) => { text += chunk; });
+    source.on("end", () => resolveBody(text));
+    source.on("error", reject);
+  });
+}
+
+export function git(cwd: string, args: string[]): string {
+  return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }).trim();
+}
+
+export function initFixtureRepo(dir: string, remote: string, files: Record<string, string> = { "base.txt": "base\n" }): string {
+  mkdirSync(dir, { recursive: true });
+  execFileSync("git", ["init", "-q", "-b", "main", dir]);
+  git(dir, ["config", "user.email", "e2e@example.invalid"]);
+  git(dir, ["config", "user.name", "e2e fixture"]);
+  git(dir, ["config", "commit.gpgsign", "false"]);
+  git(dir, ["config", "core.hooksPath", join(dir, ".git", "hooks-disabled")]);
+  for (const [path, content] of Object.entries(files)) writeFileSync(join(dir, path), content);
+  git(dir, ["add", "-A"]);
+  git(dir, ["commit", "-qm", "fixture"]);
+  git(dir, ["remote", "add", "origin", remote]);
+  return git(dir, ["rev-parse", "HEAD"]);
+}
+
+export function writeModelConfig(agentDir: string, port: number, modelIds: string[] = [MODEL]): void {
+  mkdirSync(agentDir, { recursive: true });
+  writeFileSync(join(agentDir, "models.json"), JSON.stringify({
+    providers: {
+      loopback: {
+        baseUrl: `http://127.0.0.1:${port}/v1`,
+        api: "openai-completions",
+        apiKey: "loopback-token-not-a-secret",
+        models: modelIds.map(id => ({ id, name: id, reasoning: false, contextWindow: 16_384, maxTokens: 1_024, input: ["text"] })),
+      },
+    },
+  }));
+}
+
+export function writeVerificationPolicy(home: string, commands: string[][]): void {
+  mkdirSync(home, { recursive: true });
+  writeFileSync(join(home, "verification-policy.json"), JSON.stringify({ commands }));
+}
+
+export interface ModelStep { tool?: { name: string; args: unknown }; text?: string; hold?: boolean }
+export interface ModelCall { node: string; step: number; model: string; tools: string[]; messages: any[] }
+export interface ModelServer { port: number; calls: ModelCall[]; close(): Promise<void> }
+
+function messageText(message: any): string {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((part) => typeof part?.text === "string" ? part.text : "").join("");
+  return "";
+}
+
+export function taskMarker(text: string): string {
+  return text.match(/TASK:([a-z0-9-]+)/i)?.[1] ?? "unknown";
+}
+
+export function toolResultText(messages: any[]): string {
+  return messages.filter((message) => message?.role === "tool").map(messageText).join("\n");
+}
+
+export async function startModelServer(script: (call: ModelCall) => ModelStep): Promise<ModelServer> {
+  const calls: ModelCall[] = [];
+  const server = createServer(async (req, res) => {
+    const body = JSON.parse(await readBody(req));
+    const messages = Array.isArray(body.messages) ? body.messages : [];
+    const userMessages = messages.filter((message) => message.role === "user");
+    const node = taskMarker(userMessages.length ? messageText(userMessages.at(-1)) : "");
+    const step = messages.filter((message) => message.role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.length).length;
+    const call: ModelCall = { node, step, model: body.model, tools: (body.tools ?? []).map((tool: any) => tool.function?.name), messages };
+    calls.push(call);
+    const next = script(call);
+    if (next.hold) return;
+    const chunk = (delta: unknown, finish: string | null = null) => ({ id: "chatcmpl-e2e", object: "chat.completion.chunk", created: 1, model: body.model, choices: [{ index: 0, delta, finish_reason: finish }] });
+    res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+    if (next.tool) {
+      const args = JSON.stringify(next.tool.args ?? {});
+      res.write(`data: ${JSON.stringify(chunk({ role: "assistant", content: "" }))}\n\n`);
+      res.write(`data: ${JSON.stringify(chunk({ tool_calls: [{ index: 0, id: `call_${node}_${step}`, type: "function", function: { name: next.tool.name, arguments: args } }] }))}\n\n`);
+      res.end(`data: ${JSON.stringify(chunk({}, "tool_calls"))}\n\ndata: [DONE]\n\n`);
+      return;
+    }
+    const text = next.text ?? "";
+    res.write(`data: ${JSON.stringify(chunk({ role: "assistant", content: "" }))}\n\n`);
+    if (text) res.write(`data: ${JSON.stringify(chunk({ content: text }))}\n\n`);
+    res.end(`data: ${JSON.stringify(chunk({}, "stop"))}\n\ndata: [DONE]\n\n`);
+  });
+  const port = await listen(server);
+  return { port, calls, close: () => closeServer(server) };
+}
+
+export interface GitHubView {
+  reviewThreads?: {status:"checked";total:number;unresolved:number;bugbotUnresolved:number};
+  number: number; headSha: string; baseSha: string; baseRef: string; state: "OPEN" | "MERGED" | "CLOSED"; draft: boolean; mergeState: string;
+  mergeable: "MERGEABLE" | "CONFLICTING" | "UNKNOWN"; ci: "passed" | "failed" | "pending" | "unknown";
+  review: "approved" | "changes-requested" | "pending";
+}
+
+export interface GitHubCall { op: "read" | "merge" | "branch" | "open"; detail: string }
+
+export interface GitHubServer {
+  port: number; views: Map<number, GitHubView>; branches: Map<string, string>; calls: GitHubCall[];
+  close(): Promise<void>;
+}
+
+export async function startGitHubServer(checks: "passed" | "failed" | "pending" | "unknown", review: GitHubView["review"]): Promise<GitHubServer> {
+  const views = new Map<number, GitHubView>();
+  const branches = new Map<string, string>();
+  const calls: GitHubCall[] = [];
+  const server = createServer(async (req, res) => {
+    const body = req.method === "POST" ? JSON.parse(await readBody(req) || "{}") : {};
+    const reply = (status: number, value: unknown) => { res.writeHead(status, { "content-type": "application/json" }); res.end(JSON.stringify(value)); };
+    const path = req.url ?? "";
+    if (path === "/read") {
+      calls.push({ op: "read", detail: String(body.number) });
+      const view = views.get(Number(body.number));
+      return view ? reply(200, {...view,reviewThreads:view.reviewThreads ?? {status:"checked",total:0,unresolved:0,bugbotUnresolved:0}}) : reply(404, { error: "unknown pull request" });
+    }
+    if (path === "/merge") {
+      const view = views.get(Number(body.number));
+      if (!view) { calls.push({ op: "merge", detail: "missing" }); return reply(404, { error: "unknown pull request" }); }
+      if (view.headSha !== body.headSha) { calls.push({ op: "merge", detail: "head-moved" }); return reply(409, { error: "HEAD_MOVED" }); }
+      calls.push({ op: "merge", detail: `${view.number}@${view.headSha.slice(0, 7)}` });
+      view.state = "MERGED";
+      return reply(200, view);
+    }
+    if (path === "/branch") {
+      calls.push({ op: "branch", detail: String(body.branch) });
+      const sha = branches.get(String(body.branch));
+      return sha ? reply(200, { sha }) : reply(404, { error: "unknown branch" });
+    }
+    if (path === "/open") {
+      const head = branches.get(String(body.head));
+      const base = branches.get(String(body.base));
+      if (!head || !base) { calls.push({ op: "open", detail: "unknown-ref" }); return reply(422, { error: "unknown ref" }); }
+      const number = views.size + 1;
+      views.set(number, { number, headSha: head, baseSha: base, baseRef: String(body.base), state: "OPEN", draft: false, mergeState: "CLEAN", mergeable: "MERGEABLE", ci: checks, review });
+      calls.push({ op: "open", detail: `${number} ${body.base}<-${body.head}` });
+      return reply(201, { number, url: `https://github.com/loopback-owner/lemn-disposable/pull/${number}` });
+    }
+    return reply(404, { error: "unsupported route" });
+  });
+  const port = await listen(server);
+  const github: GitHubServer = {
+    port, views, branches, calls,
+    close: () => closeServer(server),
+  };
+  return github;
+}
+
+export interface MergeCrash { mode: "normal" | "crash-before" | "crash-after" }
+
+export function githubClient(port: number, crash: MergeCrash["mode"] = "normal", repo = "loopback-owner/lemn-disposable") {
+  const view = (value: any): GitHubView => ({ number: value.number, headSha: value.headSha, baseSha: value.baseSha, baseRef: value.baseRef, state: value.state, draft: value.draft, mergeState: value.mergeState, mergeable: value.mergeable, ci: value.ci, review: value.review, reviewThreads:value.reviewThreads });
+  return {
+    async read(target: string, number: number) {
+      const { status, json } = await post(port, "/read", { repo: target, number });
+      if (status !== 200) throw new Error(`read ${number} failed: ${status}`);
+      return { ...view(json), repo: target };
+    },
+    async merge(pr: any) {
+      if (crash === "crash-before") process.kill(process.pid, "SIGKILL");
+      const { status, json } = await post(port, "/merge", { number: pr.number, headSha: pr.headSha });
+      if (crash === "crash-after") process.kill(process.pid, "SIGKILL");
+      if (status !== 200) throw new Error(json.error ?? `merge failed: ${status}`);
+    },
+    async branchHead(target: string, branch: string) {
+      const { status, json } = await post(port, "/branch", { repo: target, branch });
+      if (status !== 200) throw new Error(`branchHead ${branch} failed: ${status}`);
+      if (json.sha) return String(json.sha);
+      throw new Error("REMOTE_BRANCH_UNCERTAIN");
+    },
+    async open(target: string, base: string, head: string, title: string, bodyFile: string) {
+      const { status, json } = await post(port, "/open", { repo: target, base, head, title, bodyFile });
+      if (status !== 201) throw new Error(json.error ?? `open failed: ${status}`);
+      return `https://github.com/${repo}/pull/${json.number}`;
+    },
+  };
+}
+
+export function reportText(base: string, head: string, commandsRun: string[][] = []): string {
+  return `\`\`\`json\n${JSON.stringify({ status: "completed", artifactRefs: [], base, head, commandsRun, evidenceRefs: [], deviations: [], unresolved: [], nextActions: [] })}\n\`\`\``;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+export async function waitFor(predicate: () => boolean, label: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${label}`);
+    await sleep(20);
+  }
+}
+
+export interface ChildHandle {
+  child: ChildProcess;
+  stdout: string[];
+  stderr: string[];
+  exit: Promise<{ code: number | null; signal: string | null }>;
+  waitForLine(prefix: string, timeoutMs?: number): Promise<string>;
+}
+
+export function cleanEnv(extra: Record<string, string | undefined> = {}): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env, ...extra };
+  delete env.NODE_TEST_CONTEXT;
+  delete env.NODE_TEST_WORKER_ID;
+  return env;
+}
+
+export function spawnChild(script: string, args: string[], env: Record<string, string | undefined>): ChildHandle {
+  const child = spawn(process.execPath, ["--experimental-strip-types", script, ...args], { cwd: process.cwd(), env: cleanEnv(env), stdio: ["ignore", "pipe", "pipe"] });
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  child.stdout!.setEncoding("utf8");
+  child.stderr!.setEncoding("utf8");
+  child.stdout!.on("data", (chunk: string) => { stdout.push(...chunk.split("\n").filter(Boolean)); });
+  child.stderr!.on("data", (chunk: string) => { stderr.push(...chunk.split("\n").filter(Boolean)); });
+  const exit = new Promise<{ code: number | null; signal: string | null }>((resolveExit) => {
+    child.on("exit", (code, signal) => resolveExit({ code, signal }));
+  });
+  const waitForLine = async (prefix: string, timeoutMs = 60_000): Promise<string> => {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const line = stdout.find((entry) => entry.startsWith(prefix));
+      if (line) return line;
+      if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${prefix}. stdout=${stdout.join(" | ")} stderr=${stderr.join(" | ")}`);
+      await sleep(25);
+    }
+  };
+  return { child, stdout, stderr, exit, waitForLine };
+}
+
+export function redactCaptured(text: string): string {
+  return text
+    .replace(/(gh[pousr]_[A-Za-z0-9]{8,}|github_pat_[A-Za-z0-9_]{8,}|sk-[A-Za-z0-9-]{8,})/g, "[REDACTED]")
+    .replace(/https?:\/\/[^/@\s]+@/g, "https://[REDACTED]@")
+    .replace(/((?:api[_-]?key|token|password|secret)\s*[:=]\s*)[^\s,"'}]+/gi, "$1[REDACTED]");
+}