pi-pstack-native 0.0.0-stage → 1.0.0

package/src/models/router.ts

@@ -0,0 +1,171 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadModels } from "../runtime/config.ts";
+import type { ThinkingLevelName } from "../runtime/types.ts";
+
+export type ResolvedModel = {
+  requestedSelector: string;
+  selector: string;
+  model: ExtensionContext["model"];
+  thinkingLevel: ExtensionContext["thinkingLevel"] | ThinkingLevelName | undefined;
+  notes: string[];
+};
+
+function parseSelector(selector: string): { provider: string; id: string } | undefined {
+  const slash = selector.indexOf("/");
+  if (slash <= 0 || slash === selector.length - 1) return undefined;
+  return { provider: selector.slice(0, slash), id: selector.slice(slash + 1) };
+}
+
+export function supportsThinking(model: ExtensionContext["model"], level: ThinkingLevelName): boolean {
+  if (!model) return false;
+  if (level === "off") return true;
+  const candidate = model as unknown as { reasoning?: boolean; thinkingLevelMap?: Record<string, string | null | undefined> };
+  if (!candidate.reasoning) return false;
+  const mapped = candidate.thinkingLevelMap?.[level];
+  if (mapped === null) return false;
+  if ((level === "xhigh" || level === "max") && mapped === undefined) return false;
+  return true;
+}
+
+const EFFORTS: ThinkingLevelName[] = ['max', 'xhigh', 'high', 'medium', 'low', 'minimal'];
+export function lowerSupportedThinking(model: ExtensionContext['model'], level: ThinkingLevelName): ThinkingLevelName | undefined {
+  const index = EFFORTS.indexOf(level);
+  return index < 0 ? undefined : EFFORTS.slice(index + 1).find(candidate => supportsThinking(model, candidate));
+}
+
+/** Identify only recognizable model families; provider names alone do not establish family. */
+export function modelFamily(selector: string): string | undefined {
+  const id = parseSelector(selector)?.id.toLowerCase() ?? '';
+  for (const [family, pattern] of [
+    ['claude', /(?:^|[\/_-])claude(?:[\d_-]|$)/],
+    ['grok', /(?:^|[\/_-])(?:grok|composer)(?:[\d_.-]|$)/],
+    ['gpt', /(?:^|[\/_-])gpt(?:[\d_.-]|$)/],
+    ['gemini', /(?:^|[\/_-])gemini(?:[\d_.-]|$)/],
+    ['deepseek', /(?:^|[\/_-])deepseek(?:[\d_.-]|$)/],
+    ['qwen', /(?:^|[\/_-])qwen(?:[\d_.-]|$)/],
+    ['llama', /(?:^|[\/_-])llama(?:[\d_.-]|$)/],
+    ['mistral', /(?:^|[\/_-])mistral(?:[\d_.-]|$)/],
+  ] as const) if (pattern.test(id)) return family;
+  return undefined;
+}
+
+function sameFamilyFallback(ctx: ExtensionContext, selector: string): string | undefined {
+  const wanted = parseSelector(selector), family = modelFamily(selector);
+  if (!wanted || !family) return undefined;
+  const score = (candidate: string) => {
+    const parsed = parseSelector(candidate)!;
+    const a = wanted.id.toLowerCase(), b = parsed.id.toLowerCase();
+    let prefix = 0; while (prefix < Math.min(a.length, b.length) && a[prefix] === b[prefix]) prefix++;
+    return (parsed.provider === wanted.provider ? 10_000 : 0) + prefix;
+  };
+  return availableModelSelectors(ctx).filter(candidate => candidate !== selector && parseSelector(candidate)?.provider === wanted.provider && modelFamily(candidate) === family)
+    .sort((a, b) => score(b) - score(a) || a.localeCompare(b))[0];
+}
+
+/** Prefer a known family different from the parent; never infer a family from provider names. */
+export function selectJudgeFromPool(ctx: ExtensionContext, pool: string[]): { model?: string; notes: string[] } {
+  const notes: string[] = [];
+  const choices: string[] = [];
+  const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+  const parentFamily = parent ? modelFamily(parent) : undefined;
+  const eligible = (candidate: string) => parentFamily ? Boolean(modelFamily(candidate) && modelFamily(candidate) !== parentFamily) : candidate !== parent;
+  const resolve = (selector: string) => {
+    if (selector === 'inherit-parent' || selector === 'auto') return;
+    try {
+      const resolved = resolveRoleModel(ctx, 'judge', selector);
+      if (!resolved.model) throw new Error(`Parent model unavailable for ${selector}`);
+      notes.push(...resolved.notes);
+      choices.push(`${resolved.model.provider}/${resolved.model.id}`);
+    } catch (error) { notes.push(`Judge pool entry ${selector} unavailable: ${error instanceof Error ? error.message : String(error)}`); }
+  };
+  for (const selector of pool) resolve(selector);
+  if (!choices.some(eligible) && typeof ctx.modelRegistry.getAvailable === 'function') {
+    for (const selector of availableModelSelectors(ctx)) if (!pool.includes(selector)) resolve(selector);
+  }
+  const selected = choices.find(eligible);
+  if (!parentFamily) notes.push('The parent model family is unknown; judge family independence cannot be established.');
+  if (!selected) notes.push('No eligible cross-judge is available; the coordinator must compare and select the base.');
+  return { model: selected, notes };
+}
+
+export function resolveModelSelector(ctx: ExtensionContext, role: string, selector: string): ExtensionContext["model"] {
+  let model: ExtensionContext["model"];
+  if (selector === "inherit-parent" || selector === "auto") model = ctx.model;
+  else {
+    const parsed = parseSelector(selector);
+    if (!parsed) throw new Error(`Invalid model selector for ${role}: ${selector}. Use provider/model, inherit-parent, or auto.`);
+    model = ctx.modelRegistry.find(parsed.provider, parsed.id);
+    if (!model) throw new Error(`Model for ${role} is not available in this Pi session: ${selector}`);
+  }
+
+  return model;
+}
+
+export function resolveRoleModel(ctx: ExtensionContext, role: string, explicit?: string, taskThinking?: ThinkingLevelName): ResolvedModel {
+  const config = loadModels();
+  const requested = explicit?.trim() || config.roles[role] || "inherit-parent";
+  let selector = requested;
+  const notes: string[] = [];
+  const parsed = parseSelector(requested);
+  if (config.fallbackPolicy === 'same-family' && parsed && !ctx.modelRegistry.find(parsed.provider, parsed.id)) {
+    const fallback = sameFamilyFallback(ctx, requested);
+    if (fallback) { selector = fallback; notes.push(`Model ${requested} is unavailable; using same-family ${fallback}.`); }
+  }
+  const model = resolveModelSelector(ctx, role, selector);
+  const configuredThinking = taskThinking ?? config.thinkingLevel;
+  let thinkingLevel = configuredThinking === "inherit-parent" ? ctx.thinkingLevel : configuredThinking;
+  // Explicit pstack reasoning choices fail closed. `inherit-parent` intentionally delegates
+  // compatibility/clamping to Pi's native AgentSession, just as the parent session does.
+  if (configuredThinking !== "inherit-parent" && thinkingLevel && model && !supportsThinking(model, thinkingLevel as ThinkingLevelName)) {
+    const lower = config.fallbackPolicy === 'same-family' ? lowerSupportedThinking(model, thinkingLevel as ThinkingLevelName) : undefined;
+    if (!lower) throw new Error(`Configured pstack child reasoning level ${thinkingLevel} is not supported by ${model.provider}/${model.id}. Run /setup-pstack and choose another level or inherit-parent.`);
+    notes.push(`Reasoning level ${thinkingLevel} is unavailable on ${model.provider}/${model.id}; using ${lower}.`);
+    thinkingLevel = lower;
+  }
+  return { requestedSelector: requested, selector, model, thinkingLevel, notes };
+}
+
+export function availableModelSelectors(ctx: ExtensionContext): string[] {
+  const source = ctx.scopedModels.length ? ctx.scopedModels.map((x) => x.model) : ctx.modelRegistry.getAvailable();
+  return [...new Set<string>(source.map((m: {provider:string; id:string}) => `${m.provider}/${m.id}`))].sort();
+}
+
+/** Suggest only models visible to this Pi session. Repeated seats are explicitly reported. */
+export function suggestedPanels(ctx: ExtensionContext): Record<string, string[]> {
+  const available = availableModelSelectors(ctx);
+  const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+  const first = parent && available.includes(parent) ? parent : available[0] ?? 'inherit-parent';
+  const family = modelFamily(first);
+  const second = available.find(item => item !== first && family && modelFamily(item) && modelFamily(item) !== family)
+    ?? available.find(item => item !== first) ?? first;
+  const runners = [first, second];
+  // A judge pool is ordered by preference, not a copy of the entire registry.
+  // Keep it bounded even when the user has hundreds of available models.
+  const judges = available.length ? [...new Set(runners)] : ['inherit-parent'];
+  return { arena: [...runners], architect: [...runners], interrogate: [...runners], 'arena-judges': [...judges] };
+}
+
+/** Drop unavailable configured seats, then retain the upstream minimum using a real survivor or parent. */
+export function resolvePanelSeats(ctx: ExtensionContext, selectors: string[], minimum: number, notes: string[]): string[] {
+  const models = selectors.flatMap(selector => {
+    try {
+      const resolved = resolveRoleModel(ctx, 'panel', selector);
+      notes.push(...resolved.notes);
+      if (!resolved.model) throw new Error(`PARENT_MODEL_UNAVAILABLE: ${selector}`);
+      return [`${resolved.model.provider}/${resolved.model.id}`];
+    } catch (error) {
+      notes.push(`Panel seat ${selector} was dropped: ${error instanceof Error ? error.message : String(error)}`);
+      return [];
+    }
+  });
+  if (!models.length && ctx.model) {
+    const parent = resolveRoleModel(ctx, 'panel', 'inherit-parent');
+    if (parent.model) {
+      models.push(`${parent.model.provider}/${parent.model.id}`);
+      notes.push(`No configured panel seats resolved; using parent model ${models[0]}.`);
+    }
+  }
+  if (!models.length) throw new Error('NO_AVAILABLE_PANEL_MODELS');
+  while (models.length < minimum) { models.push(models[0]!); notes.push('Repeated the remaining model to replace a dropped seat; model diversity is not established.'); }
+  return models;
+}

package/src/program/coordinator.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { WorkflowRunSpec } from '../runtime/types.ts';
+import type { WorkflowEngine } from '../workflow/engine.ts';
+import { protocol, transact, uid, hash } from '../runtime/protocol.ts';
+import { buildDispatch, commitDispatch, materializeDispatch, requireDispatch } from './dispatch.ts';
+export interface Unit {key:string;spec:WorkflowRunSpec;workflowId?:string;ordersRevision?:number;ordersAcknowledgement?:{revision:number;actor:string;reason:string;at:string};state:'pending'|'running'|'needs-verify'|'blocked'|'failed'|'ready-to-integrate'|'reconciled';ledgerRefs:string[]}
+export interface OrdersDrift {key:string;dispatchedRevision:number|null;currentRevision:number;message:string}
+export interface Program {id:string;owner:string;revision:number;state:'pilot'|'scaling'|'paused'|'blocked'|'completed';maxConcurrency:number;units:Unit[];inbox:{id:string;key:string;state:Unit['state'];processed:boolean}[];orders?:{revision:number;instructions:string[];digest:string};blockedReason?:{code:'ORDERS_STALE';units:{key:string;dispatchedRevision:number|null}[];currentRevision:number;message:string};completionPredicate:'all-units-verified';createdAt:string}
+export function ordersDrift(program:Program,unit:Unit):OrdersDrift|undefined {
+  if(!program.orders || !unit.workflowId)return undefined;
+  if(unit.ordersRevision===program.orders.revision || unit.ordersAcknowledgement?.revision===program.orders.revision)return undefined;
+  const dispatchedRevision=unit.ordersRevision ?? null;
+  return {key:unit.key,dispatchedRevision,currentRevision:program.orders.revision,message:`STALE_ORDERS: unit ${unit.key} was dispatched under orders revision ${dispatchedRevision ?? 'none'}, current revision ${program.orders.revision}`};
+}
+export class ProgramCoordinator {
+  private workflows: WorkflowEngine;
+  constructor(workflows:WorkflowEngine) { this.workflows=workflows; }
+  create(owner:string, specs:{key:string;spec:WorkflowRunSpec}[],maxConcurrency=4):Program {
+    if(!specs.length || new Set(specs.map(s=>s.key)).size!==specs.length)throw new Error('INVALID_UNITS');
+    if(specs.some(s=>s.spec.nodes.some(n=>!n.brief || n.brief.contractLevel!=='strict')))throw new Error('PROGRAM_REQUIRES_STRICT_BRIEFS');
+    const p:Program={id:uid('program'),owner,revision:0,state:'pilot',maxConcurrency:Math.max(1,Math.min(16,maxConcurrency)),units:specs.map(s=>({...s,state:'pending',ledgerRefs:[]})),inbox:[],completionPredicate:'all-units-verified',createdAt:new Date().toISOString()};
+    return transact('program-created',p.id,owner,s=>{s.programs[p.id]=p;return p;});
+  }
+  get(id:string,owner:string):Program {const p=protocol().programs[id] as Program;if(!p || p.owner!==owner)throw new Error('PROGRAM_NOT_FOUND');return p;}
+  private drift(program:Program):OrdersDrift[] {return program.units.flatMap(unit=>{const found=ordersDrift(program,unit);return found?[found]:[];});}
+  private assertOrdersDigest(program:Program):void {if(program.orders && program.orders.digest!==hash(program.orders.instructions))throw new Error('ORDERS_INTEGRITY_MISMATCH: stored standing orders do not match their digest');}
+  private blockOrders(id:string,owner:string,drift:OrdersDrift[]):Program {
+    return transact('program-orders-stale',id,owner,s=>{const p=s.programs[id] as Program;p.state='blocked';p.blockedReason={code:'ORDERS_STALE',units:drift.map(d=>({key:d.key,dispatchedRevision:d.dispatchedRevision})),currentRevision:drift[0].currentRevision,message:drift.map(d=>d.message).join('; ')};p.revision++;return p;});
+  }
+  async run(id:string,ctx:ExtensionContext):Promise<Program> {
+    const owner=ctx.sessionManager.getSessionId();const p=this.get(id,owner);
+    if(p.state==='paused' || p.state==='completed')return p;
+    this.assertOrdersDigest(p);
+    const stale=this.drift(p);
+    if(stale.length)return this.blockOrders(id,owner,stale);
+    const runUnit=async(key:string)=>{
+      let unit=this.get(id,owner).units.find(u=>u.key===key)!;
+      if(!unit.workflowId) {
+        const currentProgram=this.get(id,owner);const orders=currentProgram.orders;
+        this.assertOrdersDigest(currentProgram);
+        const workflow=this.workflows.build({...unit.spec,nodes:unit.spec.nodes.map(n=>({...n,brief:n.brief && orders?{...n.brief,id:`${n.brief.id}.${currentProgram.id}.${unit.key}`,revision:1,standingOrders:orders.instructions}:n.brief})),parentSessionId:owner,contractLevel:'strict'});
+        const dispatch=buildDispatch({programId:id,unitKey:key,owner,workflow,ordersRevision:orders?.revision});
+        transact('unit-dispatched',id,owner,s=>{
+          const u=s.programs[id].units.find((x:Unit)=>x.key===key);
+          if(u.workflowId && u.workflowId!==dispatch.workflowId)throw new Error('UNIT_ALREADY_DISPATCHED');
+          u.workflowId=dispatch.workflowId;u.state='running';if(orders)u.ordersRevision=orders.revision;
+          commitDispatch(s,dispatch);
+          return {key,workflowId:dispatch.workflowId,dispatchId:dispatch.id};
+        });
+        unit=this.get(id,owner).units.find(u=>u.key===key)!;
+      }
+      materializeDispatch(requireDispatch(unit.workflowId!), (record)=>this.workflows.materialize(record));
+      const wf=await this.workflows.run(unit.workflowId!,ctx);
+      transact('unit-completion',id,owner,s=>{
+        const program=s.programs[id] as Program;const u=program.units.find(x=>x.key===key)!;
+        u.ledgerRefs=Object.values(wf.calls).flatMap(c=>c.verification?.ledgerId ?? []);
+        u.state=wf.state==='failed' || wf.state==='cancelled'?'failed':this.workflows.acceptedWorkflow(wf)?'ready-to-integrate':'blocked';
+        program.inbox.push({id:uid('inbox'),key,state:u.state,processed:false});program.revision++;
+        return {key,state:u.state};
+      });
+    };
+    if(p.state==='pilot') {
+      await runUnit(p.units[0].key);
+      const pilot=this.get(id,owner).units[0];
+      transact('pilot-settled',id,owner,s=>{s.programs[id].state=pilot.state==='ready-to-integrate'?'scaling':'blocked';return {state:s.programs[id].state};});
+      const stalled=this.drift(this.get(id,owner));
+      if(stalled.length)return this.blockOrders(id,owner,stalled);
+      if(pilot.state!=='ready-to-integrate')return this.get(id,owner);
+    }
+    const active=new Map<string,Promise<void>>();
+    while(true) {
+      const current=this.get(id,owner);if(current.state==='paused'){await Promise.all(active.values());return this.get(id,owner);}
+      const drift=this.drift(current);
+      if(drift.length){await Promise.all(active.values());return this.blockOrders(id,owner,drift);}
+      for(const unit of current.units) {
+        if(active.size>=current.maxConcurrency)break;
+        if(!['pending','running','blocked'].includes(unit.state) || active.has(unit.key))continue;
+        const promise=runUnit(unit.key).finally(()=>active.delete(unit.key));active.set(unit.key,promise);
+      }
+      if(!active.size)break;
+      await Promise.race(active.values());
+      if(this.get(id,owner).units.some(u=>u.state==='blocked' || u.state==='failed')) {await Promise.all(active.values());break;}
+    }
+    const late=this.drift(this.get(id,owner));
+    return late.length?this.blockOrders(id,owner,late):this.drain(id,owner);
+  }
+  drain(id:string,owner:string):Program {
+    this.get(id,owner);
+    return transact('inbox-drained',id,owner,s=>{const p=s.programs[id] as Program;for(const e of p.inbox){if(e.processed)continue;e.processed=true;const u=p.units.find(u=>u.key===e.key)!;if(u.state==='ready-to-integrate')u.state='reconciled';}p.revision++;return p;});
+  }
+  close(id:string,owner:string):Program {
+    const p=this.get(id,owner);
+    const failures=p.units.filter(u=>{const wf=u.workflowId?this.workflows.get(u.workflowId):undefined;return u.state!=='reconciled' || !wf || !this.workflows.acceptedWorkflow(wf);});
+    if(failures.length)throw new Error(`PROGRAM_CLOSE_BLOCKED: ${failures.map(u=>u.key).join(',')}`);
+    return transact('program-closed',id,owner,s=>{s.programs[id].state='completed';return s.programs[id];});
+  }
+  updateOrders(id:string,owner:string,instructions:string[],reason:string):Program {
+    this.get(id,owner);if(!reason.trim() || !instructions.length || instructions.some(x=>typeof x!=='string'))throw new Error('INVALID_STANDING_ORDERS');
+    return transact('program-orders-revised',id,owner,s=>{const p=s.programs[id] as Program;p.orders={revision:(p.orders?.revision ?? 0)+1,instructions,digest:hash(instructions)};p.revision++;return { ...p, reason };});
+  }
+  acknowledgeOrders(id:string,owner:string,key:string,revision:number,reason:string):Program {
+    const p=this.get(id,owner);
+    if(!reason.trim())throw new Error('INVALID_STANDING_ORDERS_ACKNOWLEDGEMENT');
+    this.assertOrdersDigest(p);
+    if(!p.orders)throw new Error('NO_STANDING_ORDERS');
+    if(p.orders.revision!==revision)throw new Error(`ORDERS_REVISION_MISMATCH: acknowledgement names revision ${revision}, current revision ${p.orders.revision}`);
+    const unit=p.units.find(u=>u.key===key);if(!unit)throw new Error('UNKNOWN_UNIT');
+    if(!unit.workflowId)throw new Error('UNIT_NOT_DISPATCHED');
+    return transact('unit-orders-acknowledged',id,owner,s=>{
+      const current=s.programs[id] as Program;
+      if(current.orders?.revision!==revision)throw new Error(`ORDERS_REVISION_MISMATCH: acknowledgement names revision ${revision}, current revision ${current.orders?.revision ?? 'none'}`);
+      this.assertOrdersDigest(current);
+      current.units.find(u=>u.key===key)!.ordersAcknowledgement={revision,actor:owner,reason,at:new Date().toISOString()};current.revision++;return current;
+    });
+  }
+  resume(id:string,owner:string):Program & {staleUnits:OrdersDrift[]} {
+    const p=this.get(id,owner);if(!['paused','blocked'].includes(p.state))throw new Error('PROGRAM_NOT_RESUMABLE');
+    const resumed=transact('program-resumed',id,owner,s=>{const p=s.programs[id] as Program;p.state=['ready-to-integrate','reconciled'].includes(p.units[0].state)?'scaling':'pilot';return p;});
+    return { ...resumed, staleUnits: this.drift(resumed) };
+  }
+  pause(id:string,owner:string):Program {this.get(id,owner);return transact('program-paused',id,owner,s=>{s.programs[id].state='paused';return s.programs[id];});}
+}

package/src/program/dispatch.ts

@@ -0,0 +1,83 @@
+import { hash, protocol, transact } from '../runtime/protocol.ts';
+import { workflowPath } from '../runtime/home.ts';
+import { readJson } from '../runtime/store.ts';
+import type { DispatchRecord, WorkflowRecord } from '../runtime/types.ts';
+
+type DispatchStore = { dispatches: Record<string, DispatchRecord> };
+
+export function briefDigest(workflow: WorkflowRecord): string {
+  return hash(Object.keys(workflow.calls).sort().map((key) => [key, workflow.calls[key]!.brief ? hash(workflow.calls[key]!.brief) : null]));
+}
+
+export function dispatchKey(programId: string, unitKey: string): string {
+  return `dsp_${hash({ programId, unitKey }).slice(0, 24)}`;
+}
+
+export function buildDispatch(input: { programId: string; unitKey: string; owner: string; workflow: WorkflowRecord; ordersRevision?: number }): DispatchRecord {
+  return {
+    id: dispatchKey(input.programId, input.unitKey),
+    owner: input.owner,
+    programId: input.programId,
+    unitKey: input.unitKey,
+    workflowId: input.workflow.id,
+    briefDigest: briefDigest(input.workflow),
+    ...(input.ordersRevision === undefined ? {} : { ordersRevision: input.ordersRevision }),
+    state: 'committed',
+    workflow: input.workflow,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function sameIntent(a: DispatchRecord, b: DispatchRecord): boolean {
+  return a.programId === b.programId && a.unitKey === b.unitKey && a.owner === b.owner && a.workflowId === b.workflowId &&
+    a.briefDigest === b.briefDigest && a.ordersRevision === b.ordersRevision && hash(a.workflow) === hash(b.workflow);
+}
+
+export function commitDispatch(store: DispatchStore, dispatch: DispatchRecord): DispatchRecord {
+  const existing = store.dispatches[dispatch.id];
+  if (!existing) {
+    store.dispatches[dispatch.id] = dispatch;
+    return dispatch;
+  }
+  if (!sameIntent(existing, dispatch)) throw new Error(`DISPATCH_CONFLICT: ${dispatch.id} was already committed with a different description`);
+  return existing;
+}
+
+export function findDispatch(workflowId: string): DispatchRecord | undefined {
+  return Object.values(protocol().dispatches).find((dispatch) => dispatch.workflowId === workflowId);
+}
+
+export function requireDispatch(workflowId: string): DispatchRecord {
+  const dispatch = findDispatch(workflowId);
+  if (!dispatch) throw new Error(`ORPHAN_WORKFLOW: ${workflowId} has no committed dispatch record`);
+  return dispatch;
+}
+
+/** Committed intent is the truth. The workflow file is rebuilt from it, never edited into agreement. */
+export function materializeDispatch(dispatch: DispatchRecord, write: (record: WorkflowRecord) => void): DispatchRecord {
+  const existing = readJson<WorkflowRecord | undefined>(workflowPath(dispatch.workflowId), undefined);
+  if (!existing) write(dispatch.workflow);
+  else if (hash(existing) !== hash(dispatch.workflow)) throw new Error(`DISPATCH_MATERIALIZE_CONFLICT: ${dispatch.workflowId} on disk differs from the committed dispatch`);
+  if (dispatch.state === 'materialized') return dispatch;
+  return transact('dispatch-materialized', dispatch.id, dispatch.owner, (state) => {
+    const current = state.dispatches[dispatch.id];
+    if (!current || current.state === 'materialized') return current ?? dispatch;
+    current.state = 'materialized';
+    current.materializedAt = new Date().toISOString();
+    return current;
+  });
+}
+
+export function dispatchVeto(workflowId: string, file: WorkflowRecord | undefined): string | undefined {
+  const state = protocol();
+  const units = (Object.values(state.programs) as { id: string; owner: string; units?: { key: string; workflowId?: string }[] }[])
+    .flatMap((program) => (program.units ?? []).map((unit) => ({ program, unit })));
+  const references = units.find(({ unit }) => unit.workflowId === workflowId);
+  const dispatch = Object.values(state.dispatches).find((candidate) => candidate.workflowId === workflowId);
+  if (!references && !dispatch) return undefined;
+  if (!references || !dispatch) return 'ORPHAN_WORKFLOW';
+  if (dispatch.programId !== references.program.id || dispatch.unitKey !== references.unit.key) return 'DISPATCH_MISMATCH';
+  if (!file) return 'DISPATCH_NOT_MATERIALIZED';
+  if (briefDigest(file) !== dispatch.briefDigest) return 'DISPATCH_DRIFT';
+  return undefined;
+}

package/src/runner/cli.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { auditWorktree } from '../worktree/manager.ts';
+import { prepareStack, openStack } from '../delivery/stack.ts';
+import { preparePR, openPreparedPR } from '../delivery/prepare.ts';
+// Node >=22.19 executes the shipped TypeScript sources natively.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { runService } from './service.ts';
+import { migrate } from '../runtime/migrate.ts';
+import { protocol, hash, transact } from '../runtime/protocol.ts';
+import { fingerprint } from '../artifacts/fingerprint.ts';
+import { authorizeMerge, ship, refresh } from '../delivery/frontier.ts';
+import { GitHubCLI } from '../delivery/provider.ts';
+const [action,...args]=process.argv.slice(2);
+try {
+  if(action==='migrate')console.log(JSON.stringify(migrate(!args.includes('--apply')),null,2));
+  else if(action==='run') {
+    if(!args[0])throw new Error('run requires runner configuration JSON');
+    const controller=new AbortController();process.on('SIGTERM',()=>controller.abort());process.on('SIGINT',()=>controller.abort());
+    await runService(args[0],args.includes('--once'),controller.signal);
+  } else if(action==='approve-gate') {
+    const [cwd,briefPath,gateId]=args;const brief=JSON.parse(readFileSync(briefPath,'utf8'));const gate=brief.verification.find(g=>g.id===gateId);
+    if(gate?.kind!=='human-approval' || !args.includes('--approve'))throw new Error('Requires human-approval gate and explicit --approve');
+    const fp=fingerprint(cwd,args.includes('--committed')?'committed':'working');
+    transact('human-gate-approved',gateId,'human-cli',s=>{s.approvals[hash({fingerprint:fp,gate:hash(gate)})]={actor:'human-cli',at:new Date().toISOString(),briefId:brief.id};return {gateId};});
+    console.log('Human approval recorded for this exact fingerprint.');
+  } else if(action==='worktree-audit') {
+    const info=JSON.parse(readFileSync(args[0],'utf8'));console.log(JSON.stringify(await auditWorktree(info,args[1] ?? info.baseRef),null,2));
+  } else if(action==='stack-plan') {
+    const input=JSON.parse(readFileSync(args[0],'utf8'));const plan=await prepareStack(input,new GitHubCLI());
+    if(args[1])writeFileSync(args[1],JSON.stringify(plan,null,2)+'\n',{mode:0o600});
+    console.log(JSON.stringify(plan,null,2));
+  } else if(action==='stack-open') {
+    const plan=JSON.parse(readFileSync(args[0],'utf8'));console.log(JSON.stringify(await openStack(plan,new GitHubCLI(),args.includes('--approve')),null,2));
+  } else if(action==='ship') {
+    const spec=JSON.parse(readFileSync(args[0],'utf8'));const provider=new GitHubCLI();
+    if(!args.includes('--approve'))console.log(JSON.stringify(await ship(spec,provider),null,2));
+    else {
+      const n=Number(args[args.indexOf('--pr')+1]);const f=await refresh(spec,provider);const token=authorizeMerge(f,n,'human-cli');
+      console.log(JSON.stringify(await ship(spec,provider,{token,dryRun:false}),null,2));
+    }
+  } else if(action==='open-pr') {
+    const [cwd,ledgerId,detailsPath]=args;const details=JSON.parse(readFileSync(detailsPath,'utf8'));
+    const plan=preparePR(cwd,ledgerId,details);console.log(JSON.stringify(await openPreparedPR(cwd,plan,new GitHubCLI(),args.includes('--approve')),null,2));
+  } else if(action==='export') {writeFileSync(args[0],JSON.stringify(protocol(),null,2));console.log('Audit exported.');}
+  else throw new Error('Usage: pstack-runner run CONFIG [--once] | migrate [--apply] | approve-gate CWD BRIEF GATE --approve [--committed] | worktree-audit INFO [BASE] | stack-plan INPUT [OUTPUT] | stack-open PLAN [--approve] | ship STACK [--approve --pr NUMBER] | export FILE');
+} catch(error) {console.error(String(error));process.exitCode=1;}

package/src/runner/lease.ts

@@ -0,0 +1,17 @@
+import { protocol, transact } from '../runtime/protocol.ts';
+export interface Lease {subject:string;owner:string;token:number;expiresAt:number}
+export function claimLease(subject:string,owner:string,ttlMs=30000):Lease {
+  return transact('lease-claimed',subject,owner,s=>{
+    const prior=s.leases[subject] as Lease|undefined;
+    if(prior && prior.expiresAt>Date.now() && prior.owner!==owner)throw new Error('LEASE_BUSY');
+    const lease={subject,owner,token:(prior?.token ?? 0)+1,expiresAt:Date.now()+ttlMs};s.leases[subject]=lease;return lease;
+  });
+}
+export function renewLease(lease:Lease,ttlMs=30000):Lease {
+  return transact('lease-renewed',lease.subject,lease.owner,s=>{
+    const prior=s.leases[lease.subject];if(!prior || prior.owner!==lease.owner || prior.token!==lease.token || prior.expiresAt<=Date.now())throw new Error('LEASE_LOST');
+    prior.expiresAt=Date.now()+ttlMs;return prior;
+  });
+}
+export function assertLease(lease:Lease):void {const current=protocol().leases[lease.subject];if(!current || current.owner!==lease.owner || current.token!==lease.token || current.expiresAt<=Date.now())throw new Error('LEASE_LOST');}
+export function releaseLease(lease:Lease):void {transact('lease-released',lease.subject,lease.owner,s=>{const current=s.leases[lease.subject];if(current?.token===lease.token && current.owner===lease.owner)current.expiresAt=0;return {token:lease.token};});}

package/src/runner/service.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { AgentHost } from '../agent/host.ts';
+import { WorkflowEngine } from '../workflow/engine.ts';
+import { protocol, uid, transact } from '../runtime/protocol.ts';
+import { claimLease, renewLease, releaseLease, assertLease } from './lease.ts';
+export interface RunnerConfig {agentDir:string;model:string;workflowIds:string[];pollMs?:number}
+export async function runnerOnce(config:RunnerConfig):Promise<unknown[]> {
+  if(!isAbsolute(config.agentDir) || !config.model?.includes('/') || !Array.isArray(config.workflowIds))throw new Error('RUNNER_REQUIRES_EXPLICIT_AGENT_DIR_MODEL_WORKFLOWS');
+  const { ModelRuntime, ModelRegistry }=await import('@earendil-works/pi-coding-agent');
+  const runtime=await ModelRuntime.create({authPath:join(config.agentDir,'auth.json'),modelsPath:join(config.agentDir,'models.json'),allowModelNetwork:false});
+  const slash=config.model.indexOf('/');const provider=config.model.slice(0,slash);const model=runtime.getModel(provider,config.model.slice(slash+1));
+  if(!model || !runtime.hasConfiguredAuth(provider)) {
+    transact('runner-blocked','runner','standalone',()=>({reason:'AUTHENTICATION_UNAVAILABLE',workflowIds:config.workflowIds}));
+    return [{status:'blocked',reason:'AUTHENTICATION_UNAVAILABLE'}];
+  }
+  const host=new AgentHost({agentDir:config.agentDir,modelRuntime:runtime});const engine=new WorkflowEngine(host);const output:unknown[]=[];
+  for(const id of config.workflowIds) {
+    const wf=engine.get(id);if(!wf || ['completed','failed','cancelled','paused'].includes(wf.state))continue;
+    const owner=uid('runner');const lease=claimLease(id,owner);let lost=false;
+    const timer=setInterval(()=>{try {renewLease(lease);}catch{lost=true;void engine.pause(id);for(const a of host.list().filter(a=>a.workflowId===id && a.state==='running'))void host.stop(a.id);}},5000);
+    try {
+      assertLease(lease);
+      const ctx={cwd:wf.parentCwd,model,thinkingLevel:'medium',scopedModels:[],modelRegistry:new ModelRegistry(runtime),sessionManager:{getSessionId:()=>wf.parentSessionId ?? `runner-${id}`,getSessionFile:()=>undefined}} as any;
+      output.push(await engine.run(id,ctx));assertLease(lease);if(lost)throw new Error('LEASE_LOST');
+    } finally {clearInterval(timer);releaseLease(lease);}
+  }
+  return output;
+}
+export async function runService(configPath:string,once=false,signal?:AbortSignal):Promise<void> {
+  const config=JSON.parse(readFileSync(configPath,'utf8')) as RunnerConfig;
+  do {
+    try {await runnerOnce(config);}catch(error){transact('runner-error','runner','standalone',()=>({reason:String(error)}));}
+    if(once || signal?.aborted)return;
+    await new Promise<void>(resolve=>{const done=()=>{clearTimeout(timer);signal?.removeEventListener('abort',done);resolve();};const timer=setTimeout(done,Math.max(1000,Math.min(config.pollMs ?? 5000,30000)));signal?.addEventListener('abort',done,{once:true});});
+  }while(!signal?.aborted);
+}

package/src/runtime/checkout.ts

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** Canonicalize aliases (symlinks, subdirectories) to their individual checkout, not the shared Git common dir. */
+export function checkoutIdentity(cwd: string): string {
+  const canonical = realpathSync(resolve(cwd));
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: canonical, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return realpathSync(root);
+  } catch { return canonical; }
+}
+
+export function writerLockKey(cwd: string): string {
+  return createHash("sha256").update(checkoutIdentity(cwd)).digest("hex").slice(0, 20);
+}

package/src/runtime/config.ts

@@ -0,0 +1,49 @@
+import { configPath, modelConfigPath } from "./home.ts";
+import { readJson, writeJsonAtomic } from "./store.ts";
+import type { ModelConfig, RuntimeConfig } from "./types.ts";
+
+export const DEFAULT_CONFIG: RuntimeConfig = {
+  version: 1,
+  skillsEnabled: true,
+  defaultConcurrency: 4,
+  loopMissedPolicy: "run-once",
+};
+
+export const DEFAULT_MODELS: ModelConfig = {
+  version: 1,
+  thinkingLevel: "inherit-parent",
+  fallbackPolicy: "same-family",
+  roles: {
+    worker: "inherit-parent",
+    reviewer: "inherit-parent",
+    scout: "inherit-parent",
+    architect: "inherit-parent",
+    verifier: "inherit-parent",
+    synthesizer: "inherit-parent",
+    integrator: "inherit-parent",
+    "poteto-agent": "inherit-parent",
+    "comment-sicko": "inherit-parent",
+  },
+};
+
+export function loadConfig(): RuntimeConfig {
+  const raw = readJson<Partial<RuntimeConfig>>(configPath(), DEFAULT_CONFIG);
+  return {
+    ...DEFAULT_CONFIG,
+    ...raw,
+    version: 1,
+    defaultConcurrency: Math.max(1, Math.min(16, Number(raw.defaultConcurrency) || DEFAULT_CONFIG.defaultConcurrency)),
+  };
+}
+export function saveConfig(config: RuntimeConfig): void { writeJsonAtomic(configPath(), config); }
+export function loadModels(): ModelConfig {
+  const raw = readJson<Partial<ModelConfig>>(modelConfigPath(), DEFAULT_MODELS);
+  const level = raw.thinkingLevel === undefined ? DEFAULT_MODELS.thinkingLevel : raw.thinkingLevel;
+  if (typeof level !== "string" || !["inherit-parent", "off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(level)) {
+    throw new Error(`Invalid thinkingLevel in ${modelConfigPath()}; edit it to inherit-parent, off, minimal, low, medium, high, xhigh, or max.`);
+  }
+  const fallbackPolicy = raw.fallbackPolicy ?? "disabled";
+  if (fallbackPolicy !== "disabled" && fallbackPolicy !== "same-family") throw new Error(`Invalid fallbackPolicy in ${modelConfigPath()}; use disabled or same-family.`);
+  return { panels: raw.panels, workflows: raw.workflows, version: 1, roles: { ...DEFAULT_MODELS.roles, ...(raw.roles ?? {}) }, thinkingLevel: level as ModelConfig["thinkingLevel"], fallbackPolicy };
+}
+export function saveModels(config: ModelConfig): void { writeJsonAtomic(modelConfigPath(), config); }

package/src/runtime/errors.ts

@@ -0,0 +1,12 @@
+import type { DurableError } from "./types.ts";
+
+export function durableError(code: string, error: unknown, retryable = false): DurableError {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    code,
+    message,
+    retryable,
+    ...(error instanceof Error && error.cause ? { cause: String(error.cause) } : {}),
+    occurredAt: new Date().toISOString(),
+  };
+}

package/src/runtime/home.ts

@@ -0,0 +1,17 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function pstackHome(): string {
+  return process.env.PSTACK_NATIVE_HOME || join(homedir(), ".pi", "agent", "pstack-native");
+}
+
+export const homePath = (...parts: string[]): string => join(pstackHome(), ...parts);
+export const workflowPath = (id: string): string => homePath("workflows", `${id}.json`);
+export const agentPath = (id: string): string => homePath("agents", `${id}.json`);
+export const journalPath = (id: string): string => homePath("journals", `${id}.jsonl`);
+export const lockPath = (name: string): string => homePath("locks", `${name}.lock`);
+export const worktreeRoot = (): string => homePath("worktrees");
+export const childSessionRoot = (): string => homePath("sessions");
+export const configPath = (): string => homePath("config.json");
+export const modelConfigPath = (): string => homePath("models.json");
+export const loopsPath = (): string => homePath("loops", "loops.json");