pi-pstack-native 0.0.0-stage → 1.0.0

package/src/setup/command.ts

@@ -0,0 +1,331 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { availableModelSelectors, lowerSupportedThinking, supportsThinking, suggestedPanels } from "../models/router.ts";
+import { loadModels, saveModels } from "../runtime/config.ts";
+import { modelConfigPath } from "../runtime/home.ts";
+import type { ModelConfig } from "../runtime/types.ts";
+
+type Draft = ModelConfig & { panels: Record<string, string[]>; workflows: Record<string, Record<string, string>> };
+type Item<T> = { label: string; value: T };
+type Pick<T> = { kind: "choice"; value: T } | { kind: "back" } | { kind: "cancel" };
+type Row = { text: string; error?: string };
+
+const ROLE_DESCRIPTIONS: Record<string, string> = {
+  worker: "implementation", architect: "design and implementation", reviewer: "read-only review",
+  scout: "read-only exploration", verifier: "read-only verification", synthesizer: "reconcile results",
+  integrator: "combine work", "poteto-agent": "delegated Poteto task", "comment-sicko": "comment and workaround review",
+};
+const TASK_ROLES = [
+  { name: "feature", role: "worker", label: "feature", defaultRole: "worker" },
+  { name: "refactoring", role: "worker", label: "refactoring", defaultRole: "worker" },
+  { name: "bug-fix", role: "worker", label: "bug-fix", defaultRole: "worker" },
+  { name: "perf-issue", role: "worker", label: "performance issue", defaultRole: "worker" },
+  { name: "hillclimb", role: "worker", label: "hillclimb", defaultRole: "worker" },
+  { name: "how", role: "scout", label: "how explorer", defaultRole: "scout" },
+  { name: "how", role: "synthesizer", label: "how explainer", defaultRole: "synthesizer" },
+  { name: "why", role: "scout", label: "why investigators", defaultRole: "scout" },
+  { name: "why", role: "synthesizer", label: "why synthesizer", defaultRole: "synthesizer" },
+  { name: "swarm", role: "worker", label: "swarm workers", defaultRole: "worker" },
+  { name: "reflect", role: "tooling", label: "reflect tooling" },
+  { name: "reflect", role: "judgment", label: "reflect judgment" },
+  { name: "reflect", role: "divergent", label: "reflect divergent" },
+  { name: "reflect", role: "synthesizer", label: "reflect synthesizer" },
+] as const;
+type TaskRole = { name: string; role: string; label: string; defaultRole?: string };
+const PANEL_INFO: Record<string, { label: string; min: number }> = {
+  arena: { label: "arena runners", min: 2 },
+  "arena-judges": { label: "arena cross-judge pool", min: 1 },
+  architect: { label: "architect runners", min: 2 },
+  interrogate: { label: "interrogate reviewers", min: 1 },
+};
+const BUDGETS: Item<ModelConfig["thinkingLevel"]>[] = [
+  { value: "max", label: "unlimited — max reasoning" },
+  { value: "xhigh", label: "large — xhigh reasoning" },
+  { value: "high", label: "medium — high reasoning" },
+  { value: "medium", label: "small — medium reasoning" },
+  { value: "inherit-parent", label: "inherit-parent — use the parent session's reasoning level" },
+  { value: "off", label: "off — disable reasoning" },
+  { value: "minimal", label: "minimal — least reasoning effort" },
+  { value: "low", label: "low — lower reasoning effort" },
+];
+
+// Pi's standard selector renders every option, without scrolling. Page long lists
+// so they remain usable for users with a large model registry and in RPC mode.
+async function pick<T>(ctx: ExtensionContext, title: string, items: Item<T>[], backLabel: string): Promise<Pick<T>> {
+  const size = 5;
+  let page = 0;
+  for (;;) {
+    const pages = Math.max(1, Math.ceil(items.length / size));
+    const visible = items.slice(page * size, (page + 1) * size);
+    const options = visible.map(item => item.label);
+    if (page + 1 < pages) options.push("Next page →");
+    if (page > 0) options.push("← Previous page");
+    options.push(backLabel);
+    const selected = await ctx.ui.select(`${title}${pages > 1 ? ` (${page + 1}/${pages})` : ""}`, options);
+    if (selected === undefined) return { kind: "cancel" };
+    if (selected === "Next page →") { page++; continue; }
+    if (selected === "← Previous page") { page--; continue; }
+    if (selected === backLabel) return { kind: "back" };
+    const item = visible.find(candidate => candidate.label === selected);
+    if (item) return { kind: "choice", value: item.value };
+    ctx.ui.notify("Invalid selection; try again.", "error");
+  }
+}
+
+function snapshot(): string | undefined {
+  try { return readFileSync(modelConfigPath(), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// loadModels also serves legacy runtime callers. Validate the setup input here
+// before it can be rewritten, including malformed JSON and malformed maps.
+function parseExisting(raw: string | undefined): Record<string, unknown> {
+  if (raw === undefined) return {};
+  let value: unknown;
+  try { value = JSON.parse(raw); } catch { throw new Error(`Cannot read ${modelConfigPath()}: invalid JSON. Fix the file before running setup.`); }
+  const strings = (map: unknown) => isRecord(map) && Object.values(map).every(item => typeof item === "string" && item.trim());
+  if (!isRecord(value) || (value.version !== undefined && value.version !== 1)
+      || (value.roles !== undefined && !strings(value.roles))
+      || (value.workflows !== undefined && (!isRecord(value.workflows) || !Object.values(value.workflows).every(strings)))
+      || (value.panels !== undefined && (!isRecord(value.panels) || !Object.values(value.panels).every(
+        seats => Array.isArray(seats) && seats.every(item => typeof item === "string" && item.trim()),
+      )))) {
+    throw new Error(`Cannot safely edit ${modelConfigPath()}: invalid model configuration. Fix the file before running setup.`);
+  }
+  return value;
+}
+
+function taskRoles(config: Draft): TaskRole[] {
+  const result: TaskRole[] = TASK_ROLES.map(role => ({ ...role }));
+  for (const [name, roles] of Object.entries(config.workflows)) {
+    for (const role of Object.keys(roles)) {
+      if (!result.some(item => item.name === name && item.role === role)) result.push({ name, role, label: `${name} / ${role}` });
+    }
+  }
+  return result;
+}
+
+function roleKeys(config: Draft): string[] {
+  return [...new Set([...Object.keys(ROLE_DESCRIPTIONS), ...Object.keys(config.roles)])];
+}
+
+function panelKeys(config: Draft): string[] {
+  return [...new Set([...Object.keys(PANEL_INFO), ...Object.keys(config.panels)])];
+}
+
+function modelStatus(ctx: ExtensionContext, available: Set<string>, config: Draft, value: string): { note?: string; error?: string } {
+  const alias = value === "inherit-parent" || value === "auto";
+  if (!alias && !available.has(value)) return { error: "not available; choose a model" };
+  const slash = value.indexOf("/");
+  const model = alias ? ctx.model : slash > 0 ? ctx.modelRegistry.find(value.slice(0, slash), value.slice(slash + 1)) : undefined;
+  if (!model) return alias ? { note: "parent model not selected yet" } : { error: "not available; choose a model" };
+  const level = config.thinkingLevel;
+  if (level === "inherit-parent") return {};
+  if (!supportsThinking(model, level)) {
+    const lower = config.fallbackPolicy === "same-family" ? lowerSupportedThinking(model, level) : undefined;
+    return lower ? { note: `uses ${lower} reasoning (fallback)` } : { error: `does not support ${level} reasoning` };
+  }
+  const mapped = (model as unknown as { thinkingLevelMap?: Record<string, string | null> }).thinkingLevelMap?.[level];
+  return mapped && mapped !== level ? { note: `Pi maps ${level} to ${mapped}` } : {};
+}
+
+function describe(ctx: ExtensionContext, available: Set<string>, config: Draft, label: string, value: string): Row {
+  const status = modelStatus(ctx, available, config, value);
+  return { text: `${label}: ${value}${status.error ? ` [needs choice: ${status.error}]` : status.note ? ` [${status.note}]` : ""}`, error: status.error && `${label}: ${status.error}` };
+}
+
+function reviewRows(ctx: ExtensionContext, available: Set<string>, config: Draft): Row[] {
+  const rows: Row[] = [{ text: `Budget: ${config.thinkingLevel}; fallback: ${config.fallbackPolicy ?? "disabled"}` }];
+  for (const role of roleKeys(config)) rows.push(describe(ctx, available, config, `Role ${role}`, config.roles[role] ?? "inherit-parent"));
+  for (const task of taskRoles(config)) {
+    const value = config.workflows[task.name]?.[task.role];
+    if (value) rows.push(describe(ctx, available, config, task.label, value));
+    else rows.push({ text: `${task.label}: role default${task.defaultRole ? ` (${config.roles[task.defaultRole] ?? "inherit-parent"})` : " (dispatch profile)"}` });
+  }
+  for (const name of panelKeys(config)) {
+    const seats = config.panels[name] ?? [];
+    const info = PANEL_INFO[name] ?? { label: name, min: 1 };
+    if (seats.length < info.min || seats.length > 16) rows.push({ text: `${info.label}: ${seats.length} seats [needs ${info.min}–16]`, error: `${info.label} needs ${info.min}–16 seats` });
+    const actual = seats.map(value => value === "auto" || value === "inherit-parent" ? ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "parent" : value);
+    if (name !== "arena-judges" && new Set(actual).size < actual.length) rows.push({ text: `${info.label}: repeated model seats do not add model diversity` });
+    if (name === "arena-judges" && seats.some(value => value === "auto" || value === "inherit-parent")) rows.push({ text: "Judge pool: parent aliases do not judge" });
+    seats.forEach((value, index) => rows.push(describe(ctx, available, config, `${info.label} ${index + 1}`, value)));
+  }
+  return rows;
+}
+
+async function chooseBudget(ctx: ExtensionContext, current: ModelConfig["thinkingLevel"], fresh: boolean, initial = false): Promise<Pick<ModelConfig["thinkingLevel"]>> {
+  const ordered = [...BUDGETS].sort((a, b) => Number(b.value === current) - Number(a.value === current));
+  return pick(ctx, `Child reasoning budget (${fresh ? "large matches upstream defaults" : `current: ${current}`})`, ordered, initial ? "Cancel setup" : "Back to review");
+}
+
+async function chooseModel(ctx: ExtensionContext, available: string[], title: string, current?: string, roleDefault = false): Promise<Pick<string | undefined>> {
+  const items: Item<string | undefined>[] = [
+    { value: "inherit-parent", label: "inherit-parent — parent model" },
+    { value: "auto", label: "auto — parent model" },
+    ...available.map(value => ({ value, label: value })),
+  ];
+  if (roleDefault) items.unshift({ value: undefined, label: "Use role default" });
+  items.sort((a, b) => Number(b.value === current) - Number(a.value === current));
+  return pick(ctx, title, items, "Back");
+}
+
+async function editPanel(ctx: ExtensionContext, config: Draft, name: string, available: string[]): Promise<boolean> {
+  const info = PANEL_INFO[name] ?? { label: name, min: 1 };
+  const seats = [...(config.panels[name] ?? [])];
+  for (;;) {
+    const items: Item<string>[] = [
+      { value: "done", label: "Done editing panel" },
+      { value: "add", label: "Add a seat" },
+      ...seats.map((value, index) => ({ value: String(index), label: `Seat ${index + 1}: ${value}` })),
+    ];
+    const chosen = await pick(ctx, `${info.label} (${seats.length} seats; ${info.min}–16 allowed)`, items, "Back to review");
+    if (chosen.kind === "cancel") return false;
+    if (chosen.kind === "back") return true;
+    if (chosen.value === "done") { config.panels[name] = seats; return true; }
+    if (chosen.value === "add") {
+      if (seats.length >= 16) { ctx.ui.notify("A panel can have at most 16 seats.", "error"); continue; }
+      const model = await chooseModel(ctx, available, `Add seat to ${info.label}`);
+      if (model.kind === "cancel") return false;
+      if (model.kind === "choice" && model.value) seats.push(model.value);
+      continue;
+    }
+    const index = Number(chosen.value);
+    const action = await ctx.ui.select(`Seat ${index + 1}: ${seats[index]}`, ["Change model", "Remove seat", "Move up", "Move down", "Back to panel"]);
+    if (action === undefined) return false;
+    if (action === "Remove seat") seats.splice(index, 1);
+    else if (action === "Move up" && index > 0) [seats[index - 1], seats[index]] = [seats[index]!, seats[index - 1]!];
+    else if (action === "Move down" && index + 1 < seats.length) [seats[index], seats[index + 1]] = [seats[index + 1]!, seats[index]!];
+    else if (action === "Change model") {
+      const model = await chooseModel(ctx, available, `Model for ${info.label} seat ${index + 1}`, seats[index]);
+      if (model.kind === "cancel") return false;
+      if (model.kind === "choice" && model.value) seats[index] = model.value;
+    }
+  }
+}
+
+const VERIFICATION_FOLLOWUP = [
+  "Complete the optional verification part of /setup-pstack for the current project.",
+  "First inspect the project for a project-local verify-* skill or an existing harness that drives the real app (not merely unit tests).",
+  "If neither exists, offer once to create a project-local verification skill using /skill:create-verification-skill; ask and wait for the user's answer before creating anything.",
+  "Separately check for a project-local skill that runs a model checker, proof, or other formal verifier against the code. If none exists, offer once to create one using /skill:create-formal-verification-skill; ask and wait for the user's answer.",
+  "Do not count the bundled create-* instructions as existing project verification. Respect a no or cancellation, and do not claim a skill ran unless it was actually invoked. If a requested skill is unavailable, say so.",
+].join(" ");
+
+export async function runSetup(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI) { ctx.ui.notify("/setup-pstack requires an interactive UI.", "error"); return; }
+  let original: string | undefined, config: ModelConfig, raw: Record<string, unknown>;
+  try { original = snapshot(); raw = parseExisting(original); config = loadModels(); }
+  catch (error) { ctx.ui.notify(error instanceof Error ? error.message : String(error), "error"); return; }
+  let available = availableModelSelectors(ctx);
+  if (!available.length) ctx.ui.notify("No available Pi models detected. Parent aliases are still selectable; configure Pi models and rerun setup to choose explicit models.", "warning");
+  const next: Draft = {
+    ...raw, ...config, roles: { ...config.roles },
+    panels: Object.fromEntries(Object.entries(config.panels ?? {}).map(([name, seats]) => [name, [...seats]])),
+    workflows: Object.fromEntries(Object.entries(config.workflows ?? {}).map(([name, values]) => [name, { ...values }])),
+  };
+  for (const [name, seats] of Object.entries(suggestedPanels(ctx))) next.panels[name] ??= seats;
+  if (original === undefined && available.length) {
+    const code = available.find(model => /(?:grok|composer)/i.test(model)) ?? available[0]!;
+    const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
+    const judgment = available.find(model => /claude/i.test(model)) ?? (available.includes(parent) ? parent : available[0]!);
+    next.roles.worker = code;
+    for (const role of ["architect", "reviewer", "verifier", "synthesizer", "integrator", "poteto-agent", "comment-sicko"]) next.roles[role] = judgment;
+    next.roles.scout = code;
+    next.workflows.reflect = { tooling: code, judgment, divergent: judgment, synthesizer: judgment };
+  }
+  const first = await chooseBudget(ctx, original === undefined ? "xhigh" : next.thinkingLevel, original === undefined, true);
+  if (first.kind !== "choice") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+  next.thinkingLevel = first.value;
+  let page = 0;
+  for (;;) {
+    available = availableModelSelectors(ctx);
+    const rows = reviewRows(ctx, new Set(available), next);
+    const size = 4, pages = Math.max(1, Math.ceil(rows.length / size));
+    page = Math.min(page, pages - 1);
+    const invalid = rows.filter(row => row.error);
+    const title = `Review pstack settings (${page + 1}/${pages})${invalid.length ? ` — ${invalid.length} need attention` : ""}\n${rows.slice(page * size, (page + 1) * size).map(row => row.text).join("\n")}`;
+    const actions = ["Save settings", "Edit a role", "Edit a task model", "Edit a panel", "Change budget", "Change fallback"];
+    if (page + 1 < pages) actions.push("Next page →");
+    if (page > 0) actions.push("← Previous page");
+    const action = await ctx.ui.select(title, actions);
+    if (action === undefined) { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+    if (action === "Next page →") { page++; continue; }
+    if (action === "← Previous page") { page--; continue; }
+    if (action === "Change budget") {
+      const selected = await chooseBudget(ctx, next.thinkingLevel, false);
+      if (selected.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      if (selected.kind === "choice") next.thinkingLevel = selected.value;
+      continue;
+    }
+    if (action === "Change fallback") {
+      const policies: Item<NonNullable<ModelConfig["fallbackPolicy"]>>[] = [
+        { value: "disabled", label: "disabled — block unsupported reasoning" },
+        { value: "same-family", label: "same-family — allow reported lower reasoning and model fallback" },
+      ];
+      policies.sort((a, b) => Number(b.value === next.fallbackPolicy) - Number(a.value === next.fallbackPolicy));
+      const selected = await pick(ctx, "Model fallback policy", policies, "Back to review");
+      if (selected.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      if (selected.kind === "choice") next.fallbackPolicy = selected.value;
+      continue;
+    }
+    if (action === "Edit a role") {
+      const selected = await pick(ctx, "Choose role to edit", roleKeys(next).map(value => ({ value, label: `${value} — ${next.roles[value] ?? "inherit-parent"}` })), "Back to review");
+      if (selected.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      if (selected.kind === "choice") {
+        const model = await chooseModel(ctx, available, `Model for ${selected.value}`, next.roles[selected.value]);
+        if (model.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+        if (model.kind === "choice" && model.value) next.roles[selected.value] = model.value;
+      }
+      continue;
+    }
+    if (action === "Edit a task model") {
+      const selected = await pick(ctx, "Choose task model to edit", taskRoles(next).map(value => ({ value, label: `${value.label} — ${next.workflows[value.name]?.[value.role] ?? "role default"}` })), "Back to review");
+      if (selected.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      if (selected.kind === "choice") {
+        const task = selected.value;
+        const model = await chooseModel(ctx, available, `Model for ${task.label}`, next.workflows[task.name]?.[task.role], true);
+        if (model.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+        if (model.kind === "choice") {
+          const values = { ...next.workflows[task.name] };
+          if (model.value) values[task.role] = model.value; else delete values[task.role];
+          if (Object.keys(values).length) next.workflows[task.name] = values; else delete next.workflows[task.name];
+        }
+      }
+      continue;
+    }
+    if (action === "Edit a panel") {
+      const selected = await pick(ctx, "Choose panel to edit", panelKeys(next).map(value => ({ value, label: `${PANEL_INFO[value]?.label ?? value} — ${(next.panels[value] ?? []).length} seats` })), "Back to review");
+      if (selected.kind === "cancel") { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      if (selected.kind === "choice" && !await editPanel(ctx, next, selected.value, available)) { ctx.ui.notify("Setup cancelled; nothing was written.", "info"); return; }
+      continue;
+    }
+    if (action !== "Save settings") { ctx.ui.notify("Invalid selection; try again.", "error"); continue; }
+    // Registry/auth state may change while a dialog is open; recheck just before saving.
+    const finalRows = reviewRows(ctx, new Set(availableModelSelectors(ctx)), next);
+    const finalInvalid = finalRows.filter(row => row.error);
+    if (finalInvalid.length) {
+      page = Math.floor(finalRows.findIndex(row => row.error) / size);
+      ctx.ui.notify(`Cannot save yet: ${finalInvalid[0]!.error}. Edit the affected choice or change the budget.`, "error");
+      continue;
+    }
+    try {
+      if (snapshot() !== original) { ctx.ui.notify("models.json changed during setup; nothing was written. Rerun setup to review the current settings.", "error"); return; }
+      saveModels(next);
+    } catch (error) { ctx.ui.notify(`Could not save pstack settings: ${error instanceof Error ? error.message : String(error)}`, "error"); return; }
+    const duplicates = panelKeys(next).filter(name => name !== "arena-judges" && (() => {
+      const values = (next.panels[name] ?? []).map(value => value === "auto" || value === "inherit-parent" ? ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "parent" : value);
+      return new Set(values).size < values.length;
+    })());
+    ctx.ui.notify(`Saved pstack settings to ${modelConfigPath()}.${duplicates.length ? ` Repeated seats do not add model diversity: ${duplicates.join(", ")}.` : ""}${ctx.model ? " Checking optional project verification next." : " Select a parent model and use /skill:create-verification-skill or /skill:create-formal-verification-skill if needed."}`, "info");
+    if (ctx.model) pi.sendUserMessage(VERIFICATION_FOLLOWUP, ctx.isIdle() ? { expandPromptTemplates: true } : { expandPromptTemplates: true, deliverAs: "followUp" });
+    return;
+  }
+}

package/src/telemetry/metrics.ts

@@ -0,0 +1,11 @@
+import type { WorkflowRecord } from '../runtime/types.ts';
+export function metrics(workflows:WorkflowRecord[]) {
+  const calls=workflows.flatMap(w=>Object.values(w.calls));
+  const complete=calls.filter(c=>c.state==='completed');const verified=complete.filter(c=>c.verification?.status==='passed');
+  const known=calls.filter(c=>c.usage?.tokens!==null && c.usage?.tokens!==undefined);
+  const costs=calls.filter(c=>c.usage?.cost!==null && c.usage?.cost!==undefined);
+  return {attempts:calls.reduce((n,c)=>n+c.attempt,0),completed:complete.length,verifiedRecorded:verified.length,verificationRate:complete.length?verified.length/complete.length:null,
+    tokens:known.length===calls.length?known.reduce((n,c)=>n+c.usage!.tokens!,0):null,cost:costs.length===calls.length?costs.reduce((n,c)=>n+c.usage!.cost!,0):null,
+    blocked:calls.filter(c=>c.verification?.status==='blocked').length,staleRecorded:calls.filter(c=>c.verification?.status==='stale').length,elapsedMs:calls.reduce((n,c)=>n+(c.usage?.elapsedMs ?? 0),0),
+    interpretation:'Recorded gate results; use current artifact checks before delivery. Unknown usage is never counted as zero.'};
+}

package/src/templates/build.ts

@@ -0,0 +1,172 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { resolveRoleModel, resolvePanelSeats, selectJudgeFromPool, suggestedPanels, modelFamily } from '../models/router.ts';
+import { loadModels } from '../runtime/config.ts';
+import type { WorkflowNodeSpec } from '../runtime/types.ts';
+import type { TaskBrief, Budget } from '../contracts/types.ts';
+import { validateBrief } from '../contracts/brief.ts';
+import { validateGraph } from '../workflow/graph.ts';
+import { planArtifacts } from '../workflow/artifacts.ts';
+
+export interface TemplateSpec {
+  kind: 'arena' | 'architect' | 'interrogate' | 'swarm' | 'review' | 'autopilot-stack' | 'autopilot-full';
+  brief: TaskBrief;
+  models?: string[]; panel?: string; judgeModel?: string; rubric?: { criterion: string; weight: number }[];
+  candidateCount?: number; swarmMode?: 'race' | 'partition'; slices?: { key: string; task: string; brief: TaskBrief }[];
+  selectionPolicy?: 'best-of' | 'first-pass' | 'rank-all';
+  judgeMode?: 'cross' | 'per-candidate';
+  independencePolicy?: 'different-model' | 'different-family' | 'explicit-waiver' | 'independent-session';
+  modelFamilies?: Record<string, string>; budget?: Budget;
+}
+
+function panelModels(name: string, ctx?: ExtensionContext, notes: string[] = []): string[] {
+  const models = loadModels().panels?.[name];
+  if ((!Array.isArray(models) || !models.length) && ctx) {
+    const suggested = suggestedPanels(ctx)[name];
+    if (suggested) { notes.push(`Panel ${name} was not configured; using session-available suggested seats: ${suggested.join(', ')}.`); return suggested; }
+  }
+  if (!Array.isArray(models) || !models.length || models.length > 16 || models.some(m => typeof m !== 'string' || !m.trim())) {
+    throw new Error(`PANEL_NOT_CONFIGURED: ${name}. Run /setup-pstack and configure its model seats.`);
+  }
+  return models;
+}
+
+function canonicalModel(selector: string, ctx?: ExtensionContext, notes: string[] = []): string {
+  if (typeof selector !== 'string' || !selector.trim()) throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+  const value = selector.trim();
+  if (!ctx) {
+    if (!value.includes('/') && value !== 'auto' && value !== 'inherit-parent') throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+    return value;
+  }
+  const resolved = resolveRoleModel(ctx, 'panel', value);
+  const { model } = resolved;
+  notes.push(...resolved.notes);
+  if (!model) throw new Error(`PARENT_MODEL_UNAVAILABLE: ${value}`);
+  return `${model.provider}/${model.id}`;
+}
+
+/** Configured panels become explicit node models before a workflow is created. */
+export function buildTemplate(input: TemplateSpec, ctx?: ExtensionContext): {
+  nodes: WorkflowNodeSpec[]; estimatedAgents: number; budget: Budget | undefined;
+  notes: string[]; deliveryContract: 'local-dag' | 'candidate-only' | 'remote-stack-required'; completionPolicy?: 'first-pass';
+} {
+  validateBrief(input.brief);
+  if (input.selectionPolicy && (!['best-of', 'first-pass', 'rank-all'].includes(input.selectionPolicy) || input.kind !== 'swarm' || input.swarmMode !== 'race')) throw new Error('INVALID_SWARM_SELECTION_POLICY');
+  if (input.brief.contractLevel !== 'strict') throw new Error('TEMPLATE_REQUIRES_STRICT_BRIEF');
+  const defaultPanel = input.kind === 'arena' ? 'arena' : input.kind === 'architect' ? 'architect' :
+    input.kind === 'review' || input.kind === 'interrogate' ? 'interrogate' : undefined;
+  const panel = input.panel ?? (!input.models?.length ? defaultPanel : undefined);
+  const config = loadModels();
+  const notes = ['Strict deterministic gates run on each artifact. Fallbacks and failed panels are reported.',
+    'Model cost estimate is unknown until provider usage is available.'];
+  const selectors = panel ? panelModels(panel, ctx, notes) : input.models?.length ? input.models :
+    input.kind === 'swarm' ? [config.workflows?.swarm?.worker ?? config.roles.worker ?? 'inherit-parent'] : undefined;
+  if (!selectors?.length) throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+  const tolerantPanel = Boolean(ctx && ['arena', 'architect', 'interrogate', 'review'].includes(input.kind));
+  const minimum = selectors.length === 1 && ['interrogate', 'review'].includes(input.kind) ? 1 : 2;
+  const models = tolerantPanel ? resolvePanelSeats(ctx!, selectors, minimum, notes) : selectors.map(selector => canonicalModel(selector, ctx, notes));
+  let judgeModel = input.judgeModel ? canonicalModel(input.judgeModel, ctx, notes) : undefined;
+  let policy = input.independencePolicy ?? (['arena', 'architect'].includes(input.kind) ? 'independent-session' : undefined);
+  if (judgeModel && ctx && ['arena', 'architect'].includes(input.kind)) {
+    const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    if (parent && modelFamily(parent) && (!modelFamily(judgeModel) || modelFamily(parent) === modelFamily(judgeModel))) {
+      notes.push('The requested judge is not known to be from a different family than the parent and was skipped.'); judgeModel = undefined;
+    }
+  }
+  if (!judgeModel && (input.kind === 'arena' || input.kind === 'architect')) {
+    const pool = panelModels('arena-judges', ctx, notes);
+    if (ctx) {
+      const selection = selectJudgeFromPool(ctx, pool);
+      judgeModel = selection.model;
+      notes.push(...selection.notes);
+    } else judgeModel = canonicalModel(pool[0]!);
+    policy ??= 'independent-session';
+    if (judgeModel) notes.push('The configured judge is a separate session.');
+  }
+  if ((input.kind === 'review' || input.kind === 'interrogate') && new Set(models).size < 2) {
+    notes.push('The review panel has fewer than two distinct models; multiple sessions do not establish model diversity.');
+  } else if ((input.kind === 'review' || input.kind === 'interrogate') && new Set(models).size < models.length) {
+    notes.push('Some review seats resolve to the same model; those seats do not add model diversity.');
+  }
+  const node = (key: string, profile: string, task: string, dependsOn: string[] = [], model?: string, brief = input.brief): WorkflowNodeSpec =>
+    ({ key, profile, task, dependsOn, model, brief, isolation: profile === 'worker' || profile === 'adversary' ? 'worktree' : profile === 'integrator' || profile === 'repro-verifier' ? 'shared' : 'readonly' });
+  let nodes: WorkflowNodeSpec[];
+  let candidateOnly = false;
+  if (input.kind === 'interrogate') {
+    const adversaries = models.map((model, i) => node(`adversary-${i + 1}`, 'adversary',
+      'Break the stated change. Run a reproduction for every finding in this isolated copy of the target, including its uncommitted changes. Report the command, observed and expected outputs; do not fix the target.', [], model,
+      { ...input.brief, id: `${input.brief.id}.adversary-${i + 1}`, reportRequirements: { kind: 'repro-review' } }));
+    const verifiers = adversaries.map((a, i) => node(`repro-${i + 1}`, 'repro-verifier',
+      'Independently rerun each reported command in this adversary worktree. Check whether the reproduction changes the reviewed code and whether its output breaks the stated intent. Drop findings that do not reproduce. Report actual commands and output; do not apply fixes.', [a.key], models[(i + 1) % models.length],
+      { ...input.brief, id: `${input.brief.id}.repro-${i + 1}`, reportRequirements: { kind: 'repro-review' } }));
+    nodes = [...adversaries, ...verifiers, node('synthesize', 'synthesizer', 'Compare the independently rerun reports, merge duplicate root causes, and report findings and dropped findings. Do not apply any changes. The coordinator must inspect actual command evidence before calling findings verified.', verifiers.map(n => n.key), judgeModel, { ...input.brief, id: `${input.brief.id}.interrogate-synthesis`, reportRequirements: { kind: 'repro-review' } })];
+    notes.push('Adversaries and separate repro sessions use isolated worktrees. Reports are model statements; the coordinator must inspect command evidence before accepting a finding. No changes are integrated.');
+  } else if (input.kind === 'review') {
+    const reviewers = models.map((model, i) => node(`review-${i + 1}`, 'reviewer',
+      'Review the fixed artifact. Emit findings with evidence locations, severity, reproducible findings, and model identity; do not edit.', [], model,
+      { ...input.brief, id: `${input.brief.id}.review-${i + 1}`, reportRequirements: { kind: 'review' } }));
+    nodes = [...reviewers, node('synthesize', 'synthesizer', 'Deduplicate findings by evidence, preserve minority reproducible findings. Produce severity and unresolved list.', reviewers.map(n => n.key), judgeModel)];
+  } else if (input.kind === 'autopilot-stack' || input.kind === 'autopilot-full' || input.kind === 'swarm' && input.swarmMode === 'partition') {
+    if (!input.slices?.length) throw new Error('SLICES_REQUIRED');
+    const serial = input.kind === 'autopilot-stack';
+    const workers = input.slices.map((slice, i) => {
+      validateBrief(slice.brief);
+      const result = node(slice.key, 'worker', slice.task, serial && i ? [input.slices![i - 1]!.key] : [], models[i % models.length], slice.brief);
+      if (serial && i) result.isolation = 'shared';
+      return result;
+    });
+    nodes = [...workers, node('integrate', 'integrator', 'Integrate every completed slice. Report completed/total coverage and unresolved slices.', workers.map(w => w.key), models[0],
+      { ...input.brief, id: `${input.brief.id}.coverage`, reportRequirements: { kind: 'coverage', slices: workers.map(w => w.key) } }),
+      node('verify', 'verifier', 'Audit integrated artifact and deterministic evidence. Default delivery is dry-run.', ['integrate'], judgeModel)];
+  } else if (input.kind === 'swarm' && input.swarmMode === 'race' && input.selectionPolicy === 'first-pass') {
+    const count = input.candidateCount ?? Math.max(2, models.length);
+    if (!Number.isInteger(count) || count < 2 || count > 16) throw new Error('INDEPENDENT_CANDIDATES_REQUIRED');
+    nodes = Array.from({ length: count }, (_, i) => node(`candidate-${i + 1}`, 'worker', input.brief.goal, [], models[i % models.length], { ...input.brief, id: `${input.brief.id}.candidate-${i + 1}` }));
+    notes.push('First-pass race: the first independently accepted candidate wins; remaining sessions receive cancellation and must settle before completion. No candidate is integrated automatically.');
+  } else {
+    if (input.kind === 'swarm' && input.swarmMode !== 'race') throw new Error('SWARM_MODE_REQUIRED');
+    if (!input.rubric?.length || input.rubric.some(r => !r.criterion || !(r.weight > 0))) throw new Error('RUBRIC_REQUIRED');
+    const count = input.candidateCount ?? (input.kind === 'swarm' ? Math.max(2, models.length) : models.length);
+    if (!Number.isInteger(count) || count < 2 || count > 16) throw new Error('INDEPENDENT_CANDIDATES_REQUIRED');
+    if (!judgeModel && input.kind === 'swarm') throw new Error('INDEPENDENT_JUDGE_REQUIRED');
+    policy ??= 'different-model';
+    if (judgeModel && policy === 'different-model' && models.includes(judgeModel)) throw new Error('JUDGE_NOT_INDEPENDENT');
+    if (judgeModel && policy === 'different-family' && (!input.modelFamilies?.[judgeModel] || models.some(m => !input.modelFamilies?.[m] || input.modelFamilies[m] === input.modelFamilies[judgeModel!]))) throw new Error('MODEL_FAMILY_INDEPENDENCE_UNPROVEN');
+    const goal = input.kind === 'architect' ? `${input.brief.goal}\nProduce a structurally distinct architectural sketch with types, signatures and module boundaries. Use not-implemented bodies and pseudocode; do not implement the final behavior in this phase.` : input.brief.goal;
+    const candidates = Array.from({ length: count }, (_, i) => node(`candidate-${i + 1}`, 'worker', goal, [], models[i % models.length],
+      { ...input.brief, id: `${input.brief.id}.candidate-${i + 1}` }));
+    if (!judgeModel && input.kind !== 'swarm') {
+      nodes = candidates;
+      candidateOnly = true;
+      notes.push('Cross-judge skipped. The coordinator must inspect every candidate, select and integrate the base, and verify the result; this candidate-only plan does not complete the skill.');
+    } else if (input.kind !== 'swarm' && input.judgeMode !== 'per-candidate') {
+      const keys = candidates.map(c => c.key);
+      const judge = node('cross-judge', 'cross-judge', `Inspect every candidate using pstack_candidates. Compare each against the same rubric ${JSON.stringify(input.rubric)} using direct file evidence, select one base, and identify useful parts to integrate.`, keys, judgeModel,
+        { ...input.brief, id: `${input.brief.id}.cross-evaluation`, reportRequirements: { kind: 'cross-evaluation', candidates: keys, criteria: input.rubric.map(r => r.criterion) } });
+      const integrate = node('integrate', 'integrator', 'Read each candidate and independently compare it criterion by criterion. Compare that judgment with the cross-judge, select a base, graft useful parts deliberately, and record the selection, grafts, rejections and dropouts.', [...keys, judge.key], models[0]);
+      const implement = input.kind === 'architect' ? node('implement', 'worker', 'Implement the requested behavior against the selected architectural sketch. Surface deviations from the sketch and run the relevant checks.', ['integrate'], models[0], { ...input.brief, id: `${input.brief.id}.implementation` }) : undefined;
+      if (implement) implement.isolation = 'shared';
+      nodes = [...candidates, judge, integrate, ...(implement ? [implement] : []),
+        node('verify', 'verifier', 'Audit final combined artifact. Candidate passes cannot prove integrated code.', [implement?.key ?? 'integrate'], judgeModel)];
+      if (implement) notes.push('Ground the existing system with how/why before dispatch; the implementation phase follows the selected sketch.');
+      notes.push('One read-only cross-judge can inspect the verified candidate worktrees through confined tools.');
+    } else {
+      const judges = candidates.map(c => node(`judge-${c.key}`, 'reviewer', `Evaluate only this candidate using ${JSON.stringify(input.rubric)}. Emit criterion, score, evidence, weaknesses, selectedParts.`, [c.key], judgeModel,
+        { ...input.brief, id: `${input.brief.id}.${c.key}.evaluation`, reportRequirements: { kind: 'evaluation', criteria: input.rubric!.map(r => r.criterion) } }));
+      if (input.kind === 'swarm' && input.selectionPolicy === 'rank-all') {
+        nodes = [...candidates, ...judges, node('rank', 'synthesizer', 'Rank every candidate against the rubric and explain each rank. Do not integrate or change any candidate.', judges.map(n => n.key), judgeModel,
+          { ...input.brief, id: `${input.brief.id}.ranking`, reportRequirements: { kind: 'ranking', candidates: candidates.map(c => c.key) } })];
+        notes.push('Rank-all returns an ordered comparison without automatically integrating a winner.');
+      } else {
+        nodes = [...candidates, ...judges, node('select', 'synthesizer', 'Select evidence-backed candidate/parts and explain rubric scores.', judges.map(n => n.key), judgeModel,
+          { ...input.brief, id: `${input.brief.id}.selection`, reportRequirements: { kind: 'selection', candidates: candidates.map(c => c.key) } }),
+          node('integrate', 'integrator', 'Integrate only selected parts and rerun deterministic checks.', ['select'], models[0]),
+          node('verify', 'verifier', 'Audit final combined artifact. Candidate passes cannot prove integrated code.', ['integrate'], judgeModel)];
+        notes.push('This template uses per-candidate judge sessions.');
+      }
+    }
+  }
+  validateGraph(nodes);
+  planArtifacts(nodes);
+  if (input.kind === 'autopilot-stack') notes.push('This DAG prepares local work, not a delivered PR stack. Use pstack-runner stack-plan/stack-open with independently verified linear worktree branches.');
+  return { deliveryContract: candidateOnly ? 'candidate-only' : input.kind === 'autopilot-stack' ? 'remote-stack-required' : 'local-dag', ...(input.kind === 'swarm' && input.swarmMode === 'race' && input.selectionPolicy === 'first-pass' ? { completionPolicy: 'first-pass' as const } : {}), nodes, estimatedAgents: nodes.length, budget: input.budget, notes };
+}

package/src/tools/agents.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentHost } from "../agent/host.ts";
+import { getProfile } from "../agent/profiles.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+import { loadModels } from "../runtime/config.ts";
+import { array, enums, object, string } from "./schema.ts";
+
+const PARAMETERS = object({
+  action: enums(["run", "start", "status", "list", "send", "stop"], "Operation."),
+  evidencePackets: {type:"array",items:{type:"object",additionalProperties:true}},
+  brief: {type:"object",additionalProperties:true},
+  budget: {type:"object",additionalProperties:true},
+  thinkingLevel: enums(["off","minimal","low","medium","high","xhigh","max"]),
+  id: string("Agent id for status/send/stop."),
+  profile: string("Agent profile, e.g. worker, reviewer, verifier, architect."),
+  playbook: string("Optional task or playbook name for configured role-model overrides, e.g. feature or bug-fix."),
+  modelRole: string("Optional named model role within the playbook, e.g. reflect tooling or judgment."),
+  task: string("Assigned task for run/start; message for send when message is omitted."),
+  message: string("Message for send."),
+  model: string("Optional provider/model selector or inherit-parent."),
+  isolation: enums(["shared", "readonly", "worktree"], "Optional isolation override."),
+  cwd: string("Optional working directory. Defaults to current Pi cwd."),
+  ids: array(string(), "Reserved for future batch operations."),
+}) as any;
+
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }], details: value }; }
+
+export function registerAgentTool(pi: ExtensionAPI, agents: AgentHost): void {
+  pi.registerTool({
+    name: "pstack_agents",
+    label: "Pstack Agents",
+    description: "Run and control Pi-native child AgentSessions. Pass playbook and optional modelRole to apply task-specific model overrides configured by /setup-pstack; an explicit model takes precedence. Background writable starts default to a worktree. Prefer pstack_workflow for parallel writers, integration, and dependency graphs.",
+    promptSnippet: "Launch or inspect Pi-native pstack child agents",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      const owned = (id: string) => { const record = agents.get(id); assertSessionOwner(record, sessionId); return record!; };
+      switch (params.action) {
+        case "run": {
+          if (!params.profile || !params.task) throw new Error("run requires profile and task");
+          const routes = params.playbook ? loadModels().workflows?.[params.playbook] : undefined;
+          const model = params.model ?? (params.modelRole ? routes?.[params.modelRole] : undefined) ?? routes?.[params.profile];
+          return reply(await agents.run({ profile: params.profile, task: params.task, cwd: params.cwd || ctx.cwd, isolation: params.isolation, model, evidencePackets:params.evidencePackets,brief:params.brief,budget:params.budget,thinkingLevel:params.thinkingLevel }, ctx));
+        }
+        case "start": {
+          if (!params.profile || !params.task) throw new Error("start requires profile and task");
+          const profile = getProfile(params.profile);
+          const isolation = params.isolation ?? (profile.writable ? "worktree" : profile.defaultIsolation);
+          const routes = params.playbook ? loadModels().workflows?.[params.playbook] : undefined;
+          const model = params.model ?? (params.modelRole ? routes?.[params.modelRole] : undefined) ?? routes?.[params.profile];
+          return reply(agents.start({ profile: params.profile, task: params.task, cwd: params.cwd || ctx.cwd, isolation, model, evidencePackets:params.evidencePackets,brief:params.brief,budget:params.budget,thinkingLevel:params.thinkingLevel }, ctx));
+        }
+        case "status": { if (!params.id) throw new Error("status requires id"); return reply(owned(params.id)); }
+        case "list": return reply(agents.list().filter((a) => a.parentSessionId === sessionId));
+        case "send": { if (!params.id || !(params.message || params.task)) throw new Error("send requires id and message"); owned(params.id); await agents.send(params.id, params.message || params.task); return reply({ ok: true, id: params.id }); }
+        case "stop": { if (!params.id) throw new Error("stop requires id"); owned(params.id); return reply(await agents.stop(params.id)); }
+        default: throw new Error(`Unsupported action: ${params.action}`);
+      }
+    },
+  } as any);
+}

package/src/tools/graph.ts

@@ -0,0 +1,37 @@
+import { upstreamVersion } from "../runtime/upstream.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowEngine } from "../workflow/engine.ts";
+import { array, enums, number, object, string } from "./schema.ts";
+
+const NODE = object({ evidencePackets:{type:"array",items:{type:"object",additionalProperties:true}}, key: string(), profile: string(), task: string(), model: string(), isolation: enums(["shared","readonly","worktree"]) }, ["key","task"]);
+const EDGE = object({ from: string(), to: string() }, ["from","to"]);
+const PARAMETERS = object({
+  action: enums(["run","start"]), name: string(), nodes: array(NODE), edges: array(EDGE), maxConcurrency: number(undefined,{minimum:1,maximum:16}),
+}, ["action","nodes","edges"]) as any;
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value }; }
+
+export function registerGraphTool(pi: ExtensionAPI, workflows: WorkflowEngine): void {
+  pi.registerTool({
+    name: "pstack_graph",
+    label: "Pstack Graph",
+    description: "Low-level durable DAG runner. Edges are dependency arrows from prerequisite to dependent node.",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const deps = new Map<string,string[]>();
+      for (const node of params.nodes) deps.set(node.key, []);
+      for (const edge of params.edges) {
+        if (!deps.has(edge.to) || !deps.has(edge.from)) throw new Error(`Unknown edge ${edge.from} -> ${edge.to}`);
+        deps.get(edge.to)!.push(edge.from);
+      }
+      const record = workflows.create({
+        name: params.name,
+        type: "graph",
+        nodes: params.nodes.map((node: any) => ({ ...node, dependsOn: deps.get(node.key) })),
+        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));
+    },
+  } as any);
+}