pi-pstack-native 0.0.0-stage → 1.0.0

package/src/tools/protocol.ts

@@ -0,0 +1,53 @@
+import { assertGitHubRepository } from "../delivery/git.ts";
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { WorkflowEngine } from '../workflow/engine.ts';
+import { assertSessionOwner } from '../runtime/ownership.ts';
+import { object, string, enums, array, number } from './schema.ts';
+import { verify } from '../verification/runner.ts';
+import { fingerprint } from '../artifacts/fingerprint.ts';
+import { ownerOf } from '../artifacts/fingerprint.ts';
+import { protocol, hash } from '../runtime/protocol.ts';
+import { contextSnapshot } from '../context/snapshot.ts';
+import { GitHubCLI } from '../delivery/provider.ts';
+import { refresh, eligibility, watchFrontier } from '../delivery/frontier.ts';
+import { ProgramCoordinator } from '../program/coordinator.ts';
+const reply=(value:unknown)=>({content:[{type:'text' as const,text:JSON.stringify(value,null,2)}],details:value});
+export function registerProtocolTools(pi:ExtensionAPI,engine:WorkflowEngine):void {
+  const owned=(id:string,ctx:any)=>{const w=engine.get(id);assertSessionOwner(w,ctx.sessionManager.getSessionId());return w!;};
+  pi.registerTool({name:'pstack_verify',label:'Pstack Verification',description:'Inspect current repository fingerprint or run the persisted deterministic gates for a workflow call. Command permissions come from operator verification-policy.json, never from agent text.',parameters:object({action:enums(['fingerprint','run','run-pr','ledger','contract','revise']),id:string(),key:string(),brief:{type:'object',additionalProperties:true},reason:string(),repo:string(),number:number()},['action']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    if(p.action==='fingerprint')return reply(fingerprint(ctx.cwd));
+    const w=owned(p.id,ctx);const c=w.calls[p.key];if(!c)throw new Error('Unknown call');
+    if(p.action==='contract')return reply(c.brief ?? {contractLevel:'legacy',verification:'unknown'});
+    if(p.action==='revise')return reply(engine.reviseBrief(w.id,c.key,p.brief,'coordinator',p.reason));
+    if(p.action==='ledger') {const l=c.verification?.ledgerId?protocol().ledgers[c.verification.ledgerId]:undefined;return reply({ledger:l ?? null,current:engine.accepted(c),verification:c.verification ?? 'unknown'});}
+    if(!c.brief || c.state!=='completed' || !c.cwd)throw new Error('Completed call with brief and artifact cwd required');
+    const agent=c.agentId ? (await import('../runtime/store.ts')).readJson<any>((await import('../runtime/home.ts')).agentPath(c.agentId),undefined):undefined;
+    if(!agent)throw new Error('Agent artifact record missing');
+    if(p.action==='run-pr') {
+      assertGitHubRepository(c.cwd,p.repo);
+      const actual=await new GitHubCLI().read(p.repo,p.number);const current=fingerprint(c.cwd,'committed');
+      if(actual.headSha!==current.commitSha || actual.state!=='OPEN')throw new Error('PR_HEAD_MISMATCH');
+      return reply(await verify(c.cwd,c.brief,{before:agent.baseline,owner:ownerOf(c.brief,{workflowId:w.id,callKey:c.key}),report:agent.report,pr:{repoId:current.repoId,number:p.number,headSha:actual.headSha},signal:_signal}));
+    }
+    await engine.verifyCall(w.id,c.key,agent);return reply(engine.get(w.id)?.calls[c.key]);
+  }} as any);
+  pi.registerTool({name:'pstack_delivery',label:'Pstack Delivery Plan',description:'Read live GitHub PR stack state and return deterministic shipping blockers. The operator must name the trusted rootBase; it is never taken from the PRs under review. This tool never merges; authorized merge is a human CLI operation.',parameters:object({id:string(),repo:string(),numbers:array(number()),rootBase:string(),requireReview:{type:'boolean'},requireBehavior:{type:'boolean'}},['id','repo','numbers','rootBase']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    assertGitHubRepository(ctx.cwd,p.repo);
+    const f=await refresh({...p,repoId:fingerprint(ctx.cwd).repoId,owner:ctx.sessionManager.getSessionId()},new GitHubCLI());return reply({frontier:f,decisions:eligibility(f),watch:watchFrontier(f),dryRun:true});
+  }} as any);
+  pi.registerTool({name:'pstack_context',label:'Pstack Context Snapshot',description:'Rebuild authoritative handoff and current evidence status from durable records.',parameters:object({}),async execute(_id,_p,_signal,_update,ctx){return reply(contextSnapshot(engine,ctx.sessionManager.getSessionId()));}} as any);
+  const coordinator=new ProgramCoordinator(engine);
+  pi.registerTool({name:'pstack_program',label:'Pstack Program',description:'Create, run, drain, pause and close strict unit programs with a pilot and rolling concurrency. Close checks every unit and its current evidence.',parameters:object({action:enums(['create','run','status','drain','pause','resume','orders','close']),id:string(),units:array({type:'object',additionalProperties:true}),maxConcurrency:number(),standingOrders:array(string()),reason:string()},['action']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    const owner=ctx.sessionManager.getSessionId();
+    if(p.action==='create')return reply(coordinator.create(owner,(p.units ?? []).map((u:any)=>({...u,spec:{...u.spec,cwd:ctx.cwd,parentSessionId:owner}})),p.maxConcurrency));
+    if(p.action==='run')return reply(await coordinator.run(p.id,ctx));
+    if(p.action==='status')return reply(coordinator.get(p.id,owner));
+    if(p.action==='resume'){coordinator.resume(p.id,owner);return reply(await coordinator.run(p.id,ctx));}
+    if(p.action==='orders')return reply(coordinator.updateOrders(p.id,owner,p.standingOrders,p.reason));
+    if(p.action==='drain')return reply(coordinator.drain(p.id,owner));
+    if(p.action==='pause')return reply(coordinator.pause(p.id,owner));
+    return reply(coordinator.close(p.id,owner));
+  }} as any);
+  for(const [name,action] of [['pstack-contract','contract'],['pstack-ledger','ledger']] as const)pi.registerCommand(name,{description:`Show ${action} for WORKFLOW KEY`,handler:async(args,ctx)=>{const [id,key]=args.trim().split(/\s+/);const w=owned(id,ctx);const c=w.calls[key];if(!c)throw new Error('Unknown call');ctx.ui.notify(JSON.stringify(action==='contract'?c.brief:{...c.verification,current:engine.accepted(c)},null,2),'info');}});
+  pi.registerCommand('pstack-handoff',{description:'Reconstruct durable context index',handler:async(_args,ctx)=>{ctx.ui.notify(JSON.stringify(contextSnapshot(engine,ctx.sessionManager.getSessionId()),null,2),'info');}});
+}

package/src/tools/schema.ts

@@ -0,0 +1,9 @@
+// Pi accepts ordinary JSON Schema objects in addition to TypeBox-tagged schemas.
+// Keeping schemas here avoids a runtime dependency on typebox.
+export type JsonSchema = Record<string, unknown>;
+export const string = (description?: string, extra: Record<string, unknown> = {}): JsonSchema => ({ type: "string", ...(description ? { description } : {}), ...extra });
+export const boolean = (description?: string): JsonSchema => ({ type: "boolean", ...(description ? { description } : {}) });
+export const number = (description?: string, extra: Record<string, unknown> = {}): JsonSchema => ({ type: "number", ...(description ? { description } : {}), ...extra });
+export const array = (items: JsonSchema, description?: string): JsonSchema => ({ type: "array", items, ...(description ? { description } : {}) });
+export const object = (properties: Record<string, JsonSchema>, required: string[] = [], extra: Record<string, unknown> = {}): JsonSchema => ({ type: "object", properties, required, additionalProperties: false, ...extra });
+export const enums = (values: string[], description?: string): JsonSchema => ({ type: "string", enum: values, ...(description ? { description } : {}) });

package/src/tools/workflow.ts

@@ -0,0 +1,103 @@
+import { upstreamVersion } from "../runtime/upstream.ts";
+import { buildTemplate } from "../templates/build.ts";
+import { validateBrief } from "../contracts/brief.ts";
+import { validateGraph, dependencyEdges } from "../workflow/graph.ts";
+import { planArtifacts } from "../workflow/artifacts.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowEngine } from "../workflow/engine.ts";
+import { chainNodes } from "../workflow/graph.ts";
+import { loadModels } from "../runtime/config.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+import { array, enums, number, object, string } from "./schema.ts";
+
+const NODE = object({
+  evidencePackets: {type:"array",items:{type:"object",additionalProperties:true}},
+  brief: { type: "object", additionalProperties: true },
+  thinkingLevel: enums(["off","minimal","low","medium","high","xhigh","max"]),
+  budget: {type:"object",additionalProperties:true},
+  key: string("Unique call key."),
+  profile: string("Agent profile. Defaults to worker."),
+  task: string("Task for this node."),
+  dependsOn: array(string(), "Keys that must complete first."),
+  model: string("Optional model selector."),
+  modelRole: string("Optional named model role within the playbook."),
+  isolation: enums(["shared", "readonly", "worktree"]),
+}, ["key", "task"]);
+const PARAMETERS = object({
+  action: enums(["plan", "run", "start", "status", "list", "pause", "resume", "cancel", "retry"], "Operation."),
+  template: {type:"object",additionalProperties:true},
+  contractLevel: enums(["minimal","strict"]),
+  budget: {type:"object",additionalProperties:true},
+  dryRun: {type:"boolean"},
+  id: string("Workflow id."),
+  key: string("Call key for retry."),
+  name: string("Human-readable workflow name."),
+  playbook: string("Optional task or playbook name for configured role-model overrides, such as feature or bug-fix."),
+  skill: string("Optional originating pstack skill."),
+  mode: enums(["graph", "parallel", "chain", "swarm", "arena", "architect", "interrogate", "orchestrate", "review"], "Workflow mode."),
+  nodes: array(NODE, "Workflow nodes."),
+  maxConcurrency: number("Shared concurrency limit.", { minimum: 1, maximum: 16 }),
+}) as any;
+
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value }; }
+function normalizedNodes(mode: string | undefined, nodes: any[]): any[] {
+  if (mode === "chain") return chainNodes(nodes.map(({ dependsOn: _d, ...node }) => node));
+  if (mode === "parallel") return nodes.map((node) => ({ ...node, dependsOn: [] }));
+  return nodes;
+}
+
+export function registerWorkflowTool(pi: ExtensionAPI, workflows: WorkflowEngine): void {
+  pi.registerTool({
+    name: "pstack_workflow",
+    label: "Pstack Workflow",
+    description: "Run durable Pi-native dependency graphs. Pass playbook and optional node modelRole for task-specific routing. Arena, architect and interrogate load configured or suggested panels. With no eligible cross-judge, arena/architect return candidates for the coordinator to compare, integrate and verify. Interrogate uses isolated adversaries and separate repro sessions; inspect actual evidence. Swarm races support first-pass and rank-all selection. Each template needs a strict brief; arena/architect also need a rubric. Plan first to inspect models, nodes and fallback notes.",
+    promptSnippet: "Run durable pstack multi-agent workflows",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      const owned = (id: string) => { const record = workflows.get(id); assertSessionOwner(record, sessionId); return record!; };
+      switch (params.action) {
+        case "plan":
+        case "run":
+        case "start": {
+          let plan: ReturnType<typeof buildTemplate> | undefined;
+          if (params.template) {
+            plan=buildTemplate(params.template,ctx);params.nodes=plan.nodes;
+            params.mode=params.template.kind.startsWith("autopilot")?"graph":params.template.kind === "interrogate"?"review":params.template.kind === "architect"?"arena":params.template.kind;
+            params.budget=params.budget ?? plan.budget;
+          }
+          else if (["arena","architect","interrogate","swarm","review"].includes(params.mode)) throw new Error("SPECIALIZED_MODE_REQUIRES_TEMPLATE");
+          if (!Array.isArray(params.nodes) || !params.nodes.length) throw new Error(`${params.action} requires nodes`);
+          const overrides = loadModels().workflows?.[params.playbook ?? params.mode ?? "graph"];
+          const nodes=normalizedNodes(params.mode,params.nodes).map(node => ({ ...node, model: node.model ?? (node.modelRole ? overrides?.[node.modelRole] : undefined) ?? overrides?.[node.profile ?? "worker"] }));
+          validateGraph(nodes);planArtifacts(nodes);
+          for(const n of nodes) {if(params.contractLevel==="strict" && !n.brief)throw new Error("BRIEF_INCOMPLETE");if(n.brief)validateBrief(n.brief);}
+          if(params.action==="plan" || params.dryRun) return reply({nodes,edges:dependencyEdges(nodes),plan,budget:params.budget ?? null,dryRun:true});
+          const record = workflows.create({
+            name: params.name,
+            deliveryContract: plan?.deliveryContract,
+            completionPolicy: plan?.completionPolicy,
+            modelNotes: plan?.notes,
+            type: params.mode || "graph",
+            playbook: params.playbook,
+            skill: params.skill,
+            nodes, contractLevel: params.contractLevel, budget:params.budget,
+            maxConcurrency: params.maxConcurrency,
+            parentSessionId: ctx.sessionManager.getSessionId(),
+            cwd: ctx.cwd,
+            pstackVersion: upstreamVersion(),
+          });
+          return reply(params.action === "run" ? await workflows.run(record.id, ctx) : workflows.start(record.id, ctx));
+        }
+        case "status": { if (!params.id) throw new Error("status requires id"); const w=owned(params.id);return reply({...w,currentAcceptance:Object.fromEntries(Object.values(w.calls).map((c:any)=>[c.key,c.brief?workflows.accepted(c):"unknown"]))}); }
+        case "list": return reply(workflows.list(ctx.sessionManager.getSessionId()));
+        case "pause": { if (!params.id) throw new Error("pause requires id"); owned(params.id); return reply(workflows.pause(params.id)); }
+        case "resume": { if (!params.id) throw new Error("resume requires id"); owned(params.id); return reply(workflows.resume(params.id, ctx)); }
+        case "cancel": { if (!params.id) throw new Error("cancel requires id"); owned(params.id); return reply(await workflows.cancel(params.id)); }
+        case "retry": { if (!params.id || !params.key) throw new Error("retry requires id and key"); owned(params.id); const next = workflows.retry(params.id, params.key); workflows.start(params.id, ctx); return reply(next); }
+        default: throw new Error(`Unsupported action: ${params.action}`);
+      }
+    },
+  } as any);
+}

package/src/tools/worktrees.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentHost } from "../agent/host.ts";
+import { enums, object, string } from "./schema.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+
+const PARAMETERS = object({
+  action: enums(["list", "cleanup"], "Operation."),
+  id: string("Agent id that owns the worktree."),
+}, ["action"]) as any;
+
+function reply(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value };
+}
+
+export function registerWorktreeTool(pi: ExtensionAPI, agents: AgentHost): void {
+  pi.registerTool({
+    name: "pstack_worktrees",
+    label: "Pstack Worktrees",
+    description: "List runtime-owned Git worktrees or safely clean one by agent id. Cleanup refuses dirty worktrees.",
+    promptSnippet: "Inspect or clean pstack-owned worktrees",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      if (params.action === "list") {
+        return reply(agents.list().filter((a) => a.worktree && a.parentSessionId === sessionId).map((a) => ({
+          agentId: a.id, workflowId: a.workflowId, callKey: a.callKey, state: a.state,
+          path: a.worktree, branch: a.branch, repoRoot: a.worktreeRepoRoot, baseRef: a.worktreeBaseRef,
+        })));
+      }
+      if (params.action === "cleanup") {
+        if (!params.id) throw new Error("cleanup requires id");
+        assertSessionOwner(agents.get(params.id), sessionId);
+        return reply(await agents.cleanupWorktree(params.id));
+      }
+      throw new Error(`Unsupported action: ${params.action}`);
+    },
+  } as any);
+}

package/src/verification/process.mjs

@@ -0,0 +1,9 @@
+// A small supervisor keeps command lifetime tied to the runner's pipe and timeout.
+import { spawn } from 'node:child_process';
+const [timeoutText, executable, ...args]=process.argv.slice(2);
+const child=spawn(executable,args,{shell:false,stdio:['ignore','inherit','inherit'],env:process.env});
+const terminate=()=>{try{if(process.platform!=='win32')process.kill(-process.pid,'SIGKILL');else child.kill('SIGKILL');}catch{};process.exit(124);};
+const timer=setTimeout(terminate,Number(timeoutText));
+process.stdin.resume();process.stdin.on('end',terminate);
+child.on('error',error=>{clearTimeout(timer);process.stderr.write(error.message);process.exit(127);});
+child.on('exit',(code,signal)=>{clearTimeout(timer);process.exit(code ?? (signal?125:0));});

package/src/verification/runner.ts

@@ -0,0 +1,148 @@
+import { fileURLToPath } from "node:url";
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { homePath, lockPath } from '../runtime/home.ts';
+import { FileLock } from '../runtime/lock.ts';
+import { hash, uid, transact, protocol } from '../runtime/protocol.ts';
+import { redactSecrets, redactLogTail } from '../runtime/redact.ts';
+import { fingerprint, capture, ownerOf, resolveBaseline, sameFingerprint, git } from '../artifacts/fingerprint.ts';
+import { changedPaths, matchPath, scopeViolations, validateBrief, reportSatisfies, hasBlockingReportNotes } from '../contracts/brief.ts';
+import type { GateSpec, GateStatus, TaskBrief, Evidence, Ledger, Fingerprint, TaskReport, BaselineOwner } from '../contracts/types.ts';
+export interface RunnerPolicy { commands: string[][]; environment?: Record<string,string>; allowLocal?: boolean; allowRemote?: boolean; maxOutputBytes?: number; maxTimeoutSeconds?: number }
+export function loadRunnerPolicy(): RunnerPolicy {
+  try { return JSON.parse(readFileSync(homePath('verification-policy.json'),'utf8')); }
+  catch { return {commands:[]}; }
+}
+function filePath(cwd: string, path: string): string {
+  const base = realpathSync(cwd); const candidate = realpathSync(resolve(base,path)); const rel = relative(base,candidate);
+  if (isAbsolute(path) || isAbsolute(rel) || rel==='..' || rel.startsWith('../')) throw new Error('Gate path escapes artifact');
+  return candidate;
+}
+async function command(cwd: string, gate: GateSpec, policy: RunnerPolicy, signal?: AbortSignal): Promise<{status: GateStatus; exitCode?:number|null; log:string; reason?:string}> {
+  if (!gate.command?.length || !policy.commands?.some(c=>JSON.stringify(c)===JSON.stringify(gate.command))) return {status:'blocked',log:'',reason:'COMMAND_NOT_ALLOWED'};
+  if (!['none','local','remote'].includes(gate.sideEffect ?? '') || gate.sideEffect==='local' && !policy.allowLocal || gate.sideEffect==='remote' && !policy.allowRemote) return {status:'blocked',log:'',reason:'SIDE_EFFECT_NOT_AUTHORIZED'};
+  if (signal?.aborted) return {status:'blocked',log:'',reason:'CANCELLED'};
+  return new Promise(resolveResult=>{
+    const duration=Math.max(1,Math.min(gate.timeoutSeconds ?? 120,policy.maxTimeoutSeconds ?? 300))*1000;
+    const child = spawn(process.execPath,[fileURLToPath(new URL('./process.mjs',import.meta.url)),String(duration),...gate.command!], {cwd, shell:false, detached:process.platform!=='win32', env:{PATH:process.env.PATH ?? '', ...policy.environment}});
+    let raw=''; let reason: string|undefined;
+    const cap = Math.max(1024, Math.min(policy.maxOutputBytes ?? 65536, 4*1024*1024));
+    const collect = (b: Buffer) => { raw=(raw+b.toString('utf8')).slice(-(cap+8192)); };
+    child.stdout?.on('data',collect); child.stderr?.on('data',collect);
+    const kill = (why: string) => { reason=why; try { if (process.platform!=='win32' && child.pid) process.kill(-child.pid,'SIGKILL'); else child.kill('SIGKILL'); } catch {} };
+    const timer = setTimeout(()=>kill('TIMEOUT'), duration);
+    const abort = ()=>kill('CANCELLED'); signal?.addEventListener('abort',abort,{once:true});
+    const cleanup = ()=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);};
+    child.on('error',error=>{cleanup(); resolveResult({status:'blocked',reason:'ENVIRONMENT_UNAVAILABLE',log:redactSecrets(error.message)});});
+    child.on('close',code=>{cleanup();resolveResult({status:reason || code===124 || code===125 || code===127 ? 'blocked' : code===0 ? 'passed' : 'failed', exitCode:code,reason,log:redactLogTail(raw,cap)});});
+  });
+}
+export function parseTestReport(text: string, format: 'junit'|'tap'): boolean {
+  if (format==='tap') {
+    const plan = text.match(/^1\.\.(\d+)\s*$/m); const tests = text.match(/^(?:not )?ok\s+\d+.*$/gm) ?? [];
+    return Boolean(plan && Number(plan[1])>0 && tests.length===Number(plan[1]) && !/^not ok\b/m.test(text) && !/Bail out!/i.test(text) && !tests.some(t=>/#\s*(SKIP|TODO)/i.test(t)));
+  }
+  if (/<!DOCTYPE|<!ENTITY/i.test(text)) throw new Error('Unsafe XML');
+  const suites = [...text.matchAll(/<testsuite\b([^>]*)>/g)];
+  if (!suites.length || !/<\/testsuite>/.test(text) || /<(failure|error|skipped)\b/.test(text)) return false;
+  return suites.every(([,attrs])=>{
+    const n=(key:string)=>{const m=attrs.match(new RegExp(`\\b${key}=["'](\\d+)["']`));return m?Number(m[1]):undefined;};
+    return (n('tests') ?? 0)>0 && n('failures')===0 && n('errors')===0 && (n('skipped') ?? 0)===0;
+  });
+}
+export function ledgerCurrent(entry: Ledger, current: Fingerprint): boolean {
+  const state=protocol();
+  return entry.status==='passed' && (!entry.pr || Boolean(entry.diffBase && (!entry.pr.baseSha || entry.diffBase.commitSha===entry.pr.baseSha))) && !state.invalidations[entry.id] && sameFingerprint(entry.fingerprint,current) && entry.evidenceRefs.length>0 && entry.evidenceRefs.every(id=>{
+    const e=state.evidence[id]; if (!e || e.status!=='passed') return false;
+    try { return hash(readFileSync(e.logPath,'utf8'))===e.checksum; } catch {return false;}
+  });
+}
+export function invalidate(cwd: string, reason: string): string[] {
+  const current=fingerprint(cwd);
+  return transact('ledger-invalidation',current.repoId,'runtime',s=>{
+    const ids=Object.values(s.ledgers).filter(e=>e.fingerprint.repoId===current.repoId && !sameFingerprint(e.fingerprint,current) && !s.invalidations[e.id]).map(e=>e.id);
+    for(const id of ids)s.invalidations[id]={at:new Date().toISOString(),reason}; return ids;
+  });
+}
+export async function verify(cwd: string, brief: TaskBrief, options: {policy?:RunnerPolicy; actor?:string; before?:Fingerprint; owner?:BaselineOwner; parents?:string[]; pr?:Ledger['pr']; signal?:AbortSignal; report?:TaskReport} = {}): Promise<Ledger> {
+  const actor=options.actor ?? 'verification-runner';
+  try {validateBrief(brief);} catch(error) {transact('verification-rejected',brief?.id ?? 'unknown',actor,()=>({reason:String(error)}));throw error;}
+  const policy=options.policy ?? loadRunnerPolicy();
+  const lock=new FileLock(lockPath(`verify-${hash(realpathSync(cwd))}`));
+  const deadline=Date.now()+5000;
+  while(!lock.acquire()) {
+    if(Date.now()>=deadline || options.signal?.aborted)throw new Error('VERIFICATION_BUSY_OR_CANCELLED');
+    await new Promise(resolve=>setTimeout(resolve,25));
+  }
+  try {
+    const resolution=options.before ? resolveBaseline(options.before, options.owner ?? ownerOf(brief)) : undefined;
+    const baseline=resolution?.kind==='ok' ? resolution.fingerprint : undefined;
+    const artifact=capture(cwd,undefined,options.parents ?? [],options.pr?'committed':'working',{kind:'verification',baseline});
+    if(brief.scope.repoId!==artifact.fingerprint.repoId)throw new Error('REPOSITORY_MISMATCH');
+    if(options.pr && (options.pr.repoId!==artifact.fingerprint.repoId || options.pr.headSha!==artifact.fingerprint.commitSha))throw new Error('PR_HEAD_MISMATCH');
+    let paths:string[]=[];let diffBase:Ledger['diffBase'];let baselineError:string|undefined;
+    try {
+      if(options.pr?.baseSha) {
+        const base=options.pr.baseSha;
+        if(!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(base) || git(cwd,['rev-parse','--verify',`${base}^{commit}`])!==base)throw new Error('INVALID_DIFF_BASE');
+        git(cwd,['merge-base','--is-ancestor',base,artifact.fingerprint.commitSha]);
+        paths=git(cwd,['diff','--no-renames','--name-only','-z',base,artifact.fingerprint.commitSha]).split('\0').filter(Boolean);
+        diffBase={kind:'pr',commitSha:base,refreshed:false};
+      } else if(options.before) {
+        const before=baseline;
+        if(!before)throw new Error(resolution?.kind==='unowned' ? 'BASELINE_NOT_OWNED' : 'DIFF_BASE_UNPROVEN');
+        if(before.repoId!==artifact.fingerprint.repoId || before.policyVersion!==1 || !['working','committed'].includes(before.kind) || !before.files || typeof before.files!=='object' || Array.isArray(before.files) || !Object.values(before.files).every(value=>typeof value==='string') || before.workspaceDigest!==hash({files:before.files,indexTree:before.indexTree}) || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(before.commitSha) || git(cwd,['rev-parse','--verify',`${before.commitSha}^{commit}`])!==before.commitSha)throw new Error('INVALID_DIFF_BASE');
+        if(options.pr) {
+          if(before.dirty!==false || before.treeSha!==before.indexTree || git(cwd,['rev-parse',`${before.commitSha}^{tree}`])!==before.treeSha)throw new Error('INVALID_DIFF_BASE');
+          git(cwd,['merge-base','--is-ancestor',before.commitSha,artifact.fingerprint.commitSha]);
+          paths=git(cwd,['diff','--no-renames','--name-only','-z',before.commitSha,artifact.fingerprint.commitSha]).split('\0').filter(Boolean);
+        } else paths=changedPaths(before,artifact.fingerprint,cwd);
+        diffBase={kind:'fingerprint',commitSha:before.commitSha,fingerprintHash:hash(before),refreshed:false};
+      } else if(options.pr || brief.contractLevel==='strict')baselineError='DIFF_BASE_REQUIRED';
+      else paths=[...new Set([...git(cwd,['diff','--no-renames','--name-only','-z','HEAD']).split('\0'),...git(cwd,['diff','--cached','--no-renames','--name-only','-z','HEAD']).split('\0'),...git(cwd,['ls-files','--others','--exclude-standard','-z']).split('\0')].filter(Boolean))].sort();
+    } catch(error) {const message=error instanceof Error ? error.message : '';baselineError=message==='DIFF_BASE_UNPROVEN'?'DIFF_BASE_UNPROVEN':message==='BASELINE_NOT_OWNED'?'BASELINE_NOT_OWNED':'DIFF_BASE_UNAVAILABLE';}
+    const baseKey=(base:Ledger['diffBase'])=>base?hash({kind:base.kind,commitSha:base.commitSha,fingerprintHash:base.fingerprintHash}):undefined;
+    transact('verification-baseline',brief.id,actor,s=>{
+      const old=Object.values(s.ledgers).filter(e=>e.fingerprint.repoId===artifact.fingerprint.repoId && (options.pr?e.pr?.number===options.pr.number && e.pr.repoId===options.pr.repoId:e.gateDefinitionHash===hash(brief) && !e.pr));
+      if(diffBase)diffBase.refreshed=old.some(e=>baseKey(e.diffBase)!==baseKey(diffBase));
+      for(const e of old)if(e.fingerprint.commitSha!==artifact.fingerprint.commitSha || baseKey(e.diffBase)!==baseKey(diffBase))s.invalidations[e.id]={at:new Date().toISOString(),reason:'DIFF_BASE_OR_HEAD_CHANGED'};
+      return {diffBase,reason:baselineError};
+    });
+    const violations=scopeViolations(brief,paths);
+    const requiredIds = new Set((brief.acceptance ?? []).filter(ac=>ac.required).flatMap(ac=>ac.gateIds));
+    const results: Evidence[]=[]; const nonce=uid('exec');
+    for(const gate of brief.verification) {
+      const id=uid('ev'); const startedAt=new Date().toISOString();
+      const logPath=homePath('evidence',`${id}.log`);
+      let status:GateStatus='blocked'; let log=''; let reason:string|undefined; let exitCode:number|null|undefined;
+      transact('gate-started',id,actor,s=>{s.evidence[id]={id,gateId:gate.id,gateDefinitionHash:hash(gate),status:'running',cwd,startedAt,finishedAt:startedAt,artifactId:artifact.id,logPath,checksum:'',actor,environmentHash:hash({node:process.version,platform:process.platform,policy})};return {id};});
+      try {
+        if(baselineError)reason=baselineError;
+        else if(violations.length) {reason='SCOPE_VIOLATION';log=JSON.stringify(violations);}
+        else if(gate.coverage && paths.some(p=>!gate.coverage!.some(g=>matchPath(p,g))))reason='INSUFFICIENT_COVERAGE';
+        else if(gate.kind==='command' || gate.kind==='test-report' && gate.command) {
+          const r=await command(cwd,gate,policy,options.signal);status=r.status;log=r.log;reason=r.reason;exitCode=r.exitCode;
+          if(status==='passed' && gate.kind==='test-report')status=parseTestReport(readFileSync(filePath(cwd,gate.path!),'utf8'),gate.format!)?'passed':'failed';
+        } else if(gate.kind==='file') {log=readFileSync(filePath(cwd,gate.path!),'utf8');status=!gate.pattern || new RegExp(gate.pattern).test(log)?'passed':'failed';}
+        else if(gate.kind==='diff') {log=JSON.stringify(paths);status=paths.length<=(gate.maxFiles ?? Infinity)?'passed':'failed';}
+        else if(gate.kind==='test-report') {log=readFileSync(filePath(cwd,gate.path!),'utf8');status=parseTestReport(log,gate.format!)?'passed':'failed';}
+        else if(gate.kind==='human-approval') {const approval=protocol().approvals[hash({fingerprint:artifact.fingerprint,gate:hash(gate)})];status=approval?'passed':'blocked';reason=approval?undefined:'HUMAN_APPROVAL_REQUIRED';log=JSON.stringify(approval ?? {});}
+        else {reason='ADVISORY_ONLY';}
+      } catch(error) {status='blocked';reason='CHECK_UNAVAILABLE';log=String(error);}
+      log=redactLogTail(log,Math.min(policy.maxOutputBytes ?? 65536,4*1024*1024));mkdirSync(dirname(logPath),{recursive:true});writeFileSync(logPath,log,{mode:0o600});
+      const evidence:Evidence={id,gateId:gate.id,gateDefinitionHash:hash(gate),status,reason,command:gate.command,cwd,exitCode,startedAt,finishedAt:new Date().toISOString(),artifactId:artifact.id,logPath,checksum:hash(log),actor,environmentHash:hash({node:process.version,platform:process.platform,policy})};
+      results.push(evidence);transact('gate-settled',id,actor,s=>{s.evidence[id]=evidence;return {id,status,reason};});
+    }
+    const required=results.filter(e=>brief.verification.find(g=>g.id===e.gateId)?.required!==false || requiredIds.has(e.gateId));
+    let status:GateStatus = required.length===0 ? 'blocked' : required.some(e=>e.status==='failed')?'failed':required.some(e=>e.status!=='passed')?'blocked':'passed';
+    if(baselineError || violations.length)status='blocked';
+    try {if(!sameFingerprint(artifact.fingerprint,fingerprint(cwd,options.pr?'committed':'working')))status='stale';} catch {status='stale';}
+    const categories=brief.verification.filter(g=>(g.required!==false || requiredIds.has(g.id)) && ['command','test-report'].includes(g.kind)).map(g=>g.category);
+    const r=options.report;
+    const contractAccepted=!baselineError && (brief.contractLevel==='minimal' || Boolean(r && r.status==='completed' && reportSatisfies(brief,r) && r.head===artifact.fingerprint.commitSha && r.base===(diffBase?.commitSha ?? artifact.fingerprint.commitSha) && !hasBlockingReportNotes(r)));
+    const ledger:Ledger={contractAccepted,id:uid('ver'),artifactId:artifact.id,fingerprint:artifact.fingerprint,evidenceRefs:required.map(e=>e.id),gateIds:required.map(e=>e.gateId),gateDefinitionHash:hash(brief),status,verdict:status==='passed'?(categories.includes('behavior')?'unit-test-verified':'type-check-only'):status==='failed'?'verifier-failed':status==='blocked'?'verifier-blocked':'not-verified',verifiedAt:new Date().toISOString(),verifiedBy:actor,executionNonce:nonce,diffBase,pr:options.pr};
+    transact('verification-recorded',ledger.id,actor,s=>{s.ledgers[ledger.id]=ledger;return ledger;});return ledger;
+  } catch(error) {transact('verification-rejected',brief.id,actor,()=>({reason:String(error)}));throw error;}
+  finally {lock.release();}
+}

package/src/workflow/artifacts.ts

@@ -0,0 +1,97 @@
+import { getProfile } from "../agent/profiles.ts";
+import type { WorkflowNodeSpec } from "../runtime/types.ts";
+
+export const PARENT_ARTIFACT = "@parent";
+export type ArtifactPlan = {
+  origin: Map<string, Set<string>>;
+  /** Every writer lane must be isolated if any unrelated writer could run concurrently. */
+  isolated: Set<string>;
+  ancestors: Map<string, Set<string>>;
+};
+
+/** Analyze all upstream writes, including writes hidden behind read-only synthesizers. */
+export function planArtifacts(nodes: WorkflowNodeSpec[]): ArtifactPlan {
+  const byKey = new Map(nodes.map((node) => [node.key, node]));
+  const origin = new Map<string, Set<string>>();
+  const ancestors = new Map<string, Set<string>>();
+  const visiting = new Set<string>();
+  const visit = (key: string): void => {
+    if (origin.has(key)) return;
+    if (visiting.has(key)) throw new Error(`Workflow contains a dependency cycle at ${key}`);
+    visiting.add(key);
+    const node = byKey.get(key);
+    if (!node) throw new Error(`Unknown workflow node ${key}`);
+    const profile = getProfile(node.profile ?? "worker");
+    if (profile.writable && node.isolation === "readonly") {
+      throw new Error(`Writable call ${key} cannot use readonly isolation.`);
+    }
+    if (profile.name === "integrator" && node.isolation && node.isolation !== "shared") {
+      throw new Error(`Integrator ${key} must run in the target checkout with shared isolation.`);
+    }
+    const deps = node.dependsOn ?? [];
+    if (profile.name === 'repro-verifier' && (node.isolation !== 'shared' || deps.length !== 1 || byKey.get(deps[0]!)?.profile !== 'adversary')) throw new Error(`Repro verifier ${key} must continue exactly one adversary worktree.`);
+    const prior = new Set<string>();
+    const parents = new Set<string>();
+    for (const dep of deps) {
+      visit(dep);
+      for (const lane of origin.get(dep)!) prior.add(lane);
+      parents.add(dep);
+      for (const ancestor of ancestors.get(dep)!) parents.add(ancestor);
+    }
+    ancestors.set(key, parents);
+    if (profile.name === "integrator") {
+      // A successful integration deliberately collapses prior worktree artifacts into the parent.
+      origin.set(key, new Set([PARENT_ARTIFACT]));
+    } else if (profile.writable) {
+      if (prior.size > 1) {
+        throw new Error(`Writable call ${key} has multiple unmerged writable artifacts (${[...prior].join(", ")}). Use profile "integrator" for an explicit merge owner.`);
+      }
+      if (prior.size === 1 && !prior.has(PARENT_ARTIFACT)) {
+        if (node.isolation === "worktree") {
+          throw new Error(`Writable continuation ${key} cannot fork its existing artifact using worktree isolation; add an integrator or start an independent branch.`);
+        }
+        origin.set(key, prior);
+      } else {
+        origin.set(key, new Set([key]));
+      }
+    } else {
+      if (["reviewer", "verifier"].includes(profile.name) && prior.size > 1) {
+        throw new Error(`${profile.name} call ${key} sees multiple unmerged writable artifacts (${[...prior].join(", ")}). Add an integrator node first, then verify/review the integrated checkout.`);
+      }
+      if (profile.name === 'cross-judge' && (deps.length < 1 || prior.size !== deps.length || deps.some(dep => {
+        const candidate = byKey.get(dep)!;
+        return (candidate.profile ?? 'worker') !== 'worker' || candidate.isolation !== 'worktree' || (candidate.dependsOn?.length ?? 0) !== 0 || origin.get(dep)?.size !== 1;
+      }))) throw new Error(`Cross-judge ${key} requires distinct root worker worktrees as direct dependencies.`);
+      origin.set(key, prior);
+    }
+    visiting.delete(key);
+  };
+  for (const node of nodes) visit(node.key);
+
+  const isolated = new Set<string>();
+  const writers = nodes.filter((node) => getProfile(node.profile ?? "worker").writable);
+  for (let i = 0; i < writers.length; i++) {
+    for (let j = i + 1; j < writers.length; j++) {
+      const a = writers[i]!, b = writers[j]!;
+      if (ancestors.get(a.key)!.has(b.key) || ancestors.get(b.key)!.has(a.key)) continue;
+      const aLane = [...origin.get(a.key)!][0]!;
+      const bLane = [...origin.get(b.key)!][0]!;
+      // An incomparable fork on an existing lane cannot be executed safely on the same checkout.
+      if (aLane === bLane) {
+        throw new Error(`Concurrent writable calls ${a.key} and ${b.key} fork the same unmerged artifact. Serialize them or add an explicit integration boundary.`);
+      }
+      if (aLane !== PARENT_ARTIFACT) isolated.add(aLane);
+      if (bLane !== PARENT_ARTIFACT) isolated.add(bLane);
+    }
+  }
+  // Explicit isolation must not defeat the graph's required isolation.
+  for (const node of writers) {
+    const profile = getProfile(node.profile ?? "worker");
+    if (profile.name === "integrator") continue;
+    const lane = [...origin.get(node.key)!][0]!;
+    if (isolated.has(lane) && node.isolation === "shared" && profile.name !== 'repro-verifier') {
+      throw new Error(`Writable call ${node.key} requires a worktree: shared isolation would collide with an independent writer.`);
+    }
+  }
+  return { origin, isolated, ancestors };
+}