@wichayutdew/pi-workflows 0.1.1

package/dist/index.js

@@ -0,0 +1,4576 @@
+// src/harness.ts
+import { randomBytes, randomUUID } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { readFile as readFile2, rm } from "node:fs/promises";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/commands.ts
+function splitFirst(value) {
+  const trimmed = value.trim();
+  const separator = trimmed.search(/\s/);
+  if (separator === -1)
+    return [trimmed, ""];
+  return [trimmed.slice(0, separator), trimmed.slice(separator).trim()];
+}
+function registerHarnessCommands(pi, controller) {
+  pi.registerCommand("workflow-list", {
+    description: "List loaded declarative workflows",
+    handler: async (_args, ctx) => controller.list(ctx)
+  });
+  pi.registerCommand("workflow-start", {
+    description: "Start a workflow: /workflow-start <id> [input]",
+    getArgumentCompletions: (prefix) => {
+      const items = controller.workflowIds().filter((id) => id.startsWith(prefix)).map((id) => ({ value: id, label: id }));
+      return items.length > 0 ? items : null;
+    },
+    handler: async (args, ctx) => {
+      const [workflowId, input] = splitFirst(args);
+      if (!workflowId) {
+        ctx.ui.notify("Usage: /workflow-start <id> [input]", "warning");
+        return;
+      }
+      await controller.start(workflowId, input, ctx);
+    }
+  });
+  pi.registerCommand("workflow-pause", {
+    description: "Pause the active workflow without losing its checkpoint",
+    handler: async (reason, ctx) => controller.pause(reason.trim(), ctx)
+  });
+  pi.registerCommand("workflow-resume", {
+    description: "Reload configuration and resume the paused workflow",
+    handler: async (_args, ctx) => controller.resume(ctx)
+  });
+  pi.registerCommand("workflow-abort", {
+    description: "Abort the active workflow",
+    handler: async (reason, ctx) => controller.abort(reason.trim(), ctx)
+  });
+  pi.registerCommand("workflow-reload", {
+    description: "Reload workflow files while no workflow is running",
+    handler: async (_args, ctx) => controller.reload(ctx)
+  });
+  pi.registerCommand("workflow-status", {
+    description: "Open the active workflow status board",
+    handler: async (_args, ctx) => controller.status(ctx)
+  });
+}
+
+// src/config/load.ts
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parseDocument } from "yaml";
+
+// src/digest.ts
+import { createHash } from "node:crypto";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)]));
+  }
+  return value;
+}
+function digest(value) {
+  return createHash("sha256").update(JSON.stringify(canonicalize(value))).digest("hex");
+}
+
+// src/config/ceiling.ts
+function selectorAllowed(requested, ceiling) {
+  const separator = requested.indexOf("/");
+  if (separator === -1)
+    return ceiling.includes(requested);
+  const server = requested.slice(0, separator);
+  return ceiling.includes(server) || ceiling.includes(requested);
+}
+function ruleKey(rule) {
+  return JSON.stringify([rule.executable, rule.argsPrefix]);
+}
+function bashWithinCeiling(requested, ceiling) {
+  if (ceiling.mode === "unrestricted")
+    return true;
+  if (requested.mode === "deny")
+    return true;
+  if (ceiling.mode === "deny")
+    return false;
+  if (ceiling.mode === "read-only")
+    return requested.mode === "read-only";
+  if (requested.mode !== "allow-list")
+    return false;
+  const allowedRules = new Set(ceiling.allow.map(ruleKey));
+  const allowedSources = new Set(ceiling.approvedSources ?? []);
+  return requested.allow.every((rule) => allowedRules.has(ruleKey(rule))) && (requested.approvedSources ?? []).every((source) => allowedSources.has(source));
+}
+function checkWorkflowAgainstCeiling(workflow, ceiling) {
+  const errors = [];
+  for (const [stepId, step] of Object.entries(workflow.steps)) {
+    const path = `workflow.steps.${stepId}.permissions`;
+    const subagentPath = `workflow.steps.${stepId}.subagent`;
+    for (const tool of step.permissions.tools) {
+      if (!ceiling.tools.includes(tool)) {
+        errors.push(`${path}.tools: "${tool}" exceeds the user permission ceiling`);
+      }
+    }
+    for (const selector of step.permissions.mcp) {
+      if (!selectorAllowed(selector, ceiling.mcp)) {
+        errors.push(`${path}.mcp: "${selector}" exceeds the user permission ceiling`);
+      }
+    }
+    for (const extension of step.permissions.extensions) {
+      if (!ceiling.extensions.includes(extension)) {
+        errors.push(`${path}.extensions: "${extension}" exceeds the user permission ceiling`);
+      }
+    }
+    for (const skill of step.permissions.skills) {
+      if (!ceiling.skills.includes(skill)) {
+        errors.push(`${path}.skills: "${skill}" exceeds the user permission ceiling`);
+      }
+    }
+    if (!bashWithinCeiling(step.permissions.bash, ceiling.bash)) {
+      errors.push(`${path}.bash: exceeds the user permission ceiling`);
+    }
+    if (!step.subagent)
+      continue;
+    if (!ceiling.subagent) {
+      errors.push(`${subagentPath}: subagent execution exceeds the user permission ceiling`);
+      continue;
+    }
+    if (!ceiling.subagent.agents.includes(step.subagent.agent)) {
+      errors.push(`${subagentPath}.agent: "${step.subagent.agent}" exceeds the user permission ceiling`);
+    }
+    if (!ceiling.subagent.contexts.includes(step.subagent.context)) {
+      errors.push(`${subagentPath}.context: "${step.subagent.context}" exceeds the user permission ceiling`);
+    }
+    if (step.subagent.model && !ceiling.subagent.models.includes(step.subagent.model)) {
+      errors.push(`${subagentPath}.model: "${step.subagent.model}" exceeds the user permission ceiling`);
+    }
+    if (step.subagent.timeoutMs > ceiling.subagent.maxTimeoutMs) {
+      errors.push(`${subagentPath}.timeoutMs: exceeds the user permission ceiling`);
+    }
+    if (step.subagent.artifacts && !ceiling.subagent.artifacts) {
+      errors.push(`${subagentPath}.artifacts: exceeds the user permission ceiling`);
+    }
+    if (!step.subagent.turnBudget) {
+      errors.push(`${subagentPath}.turnBudget: required for a project workflow`);
+    } else {
+      if (step.subagent.turnBudget.maxTurns > ceiling.subagent.maxTurns) {
+        errors.push(`${subagentPath}.turnBudget.maxTurns: exceeds the user permission ceiling`);
+      }
+      if ((step.subagent.turnBudget.graceTurns ?? 0) > ceiling.subagent.maxGraceTurns) {
+        errors.push(`${subagentPath}.turnBudget.graceTurns: exceeds the user permission ceiling`);
+      }
+    }
+    if (!step.subagent.toolBudget) {
+      errors.push(`${subagentPath}.toolBudget: required for a project workflow`);
+    } else {
+      if (step.subagent.toolBudget.hard > ceiling.subagent.maxToolCalls) {
+        errors.push(`${subagentPath}.toolBudget.hard: exceeds the user permission ceiling`);
+      }
+      if (step.subagent.toolBudget.block !== "*") {
+        errors.push(`${subagentPath}.toolBudget.block: must be "*" for a project workflow`);
+      }
+    }
+  }
+  return errors;
+}
+
+// src/config/types.ts
+var WORKFLOW_SCHEMA_VERSION = 1;
+var SUBAGENT_RUNTIME_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+var EMPTY_PERMISSIONS = {
+  tools: [],
+  mcp: [],
+  extensions: [],
+  skills: [],
+  bash: { mode: "deny", allow: [] }
+};
+var DEFAULT_STEP_SUBAGENT = {
+  agent: "pi-workflows.step",
+  context: "fresh",
+  timeoutMs: 900000,
+  artifacts: false
+};
+var DEFAULT_SETTINGS = {
+  version: WORKFLOW_SCHEMA_VERSION,
+  allowProjectWorkflows: false
+};
+
+// src/command-names.ts
+var HARNESS_COMMAND_NAMES = [
+  "workflow-abort",
+  "workflow-list",
+  "workflow-pause",
+  "workflow-reload",
+  "workflow-resume",
+  "workflow-start",
+  "workflow-status"
+];
+var PI_BUILTIN_COMMAND_NAMES = [
+  "arminsayshi",
+  "changelog",
+  "clone",
+  "compact",
+  "copy",
+  "debug",
+  "dementedelves",
+  "export",
+  "fork",
+  "hotkeys",
+  "import",
+  "login",
+  "logout",
+  "model",
+  "name",
+  "new",
+  "quit",
+  "reload",
+  "resume",
+  "scoped-models",
+  "session",
+  "settings",
+  "share",
+  "tree",
+  "trust"
+];
+var RESERVED_COMMAND_NAMES = new Set([
+  ...HARNESS_COMMAND_NAMES,
+  ...PI_BUILTIN_COMMAND_NAMES
+]);
+
+// src/config/validate.ts
+var IDENTIFIER_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+var OUTCOME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+var TOOL_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+var RESOURCE_SELECTOR_PATTERN = /^[A-Za-z0-9_@./:+-]+$/;
+var MCP_SELECTOR_PATTERN = /^[A-Za-z0-9_.:-]+(?:\/[A-Za-z0-9_.:-]+)?$/;
+var EXECUTABLE_PATTERN = /^[A-Za-z0-9_./+-]+$/;
+var BASH_APPROVAL_SOURCE_PATTERN = /^(verification-worker|verification-reviewer|remote-actions)$/;
+var PROMPT_VARIABLES = new Set([
+  "workflow.input",
+  "workflow.id",
+  "run.id",
+  "step.id",
+  "step.title",
+  "last.summary",
+  "gate.feedback"
+]);
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, path, errors) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key)) {
+      errors.push(`${path}: unknown property "${key}"`);
+    }
+  }
+}
+function readString(value, path, errors, options = {}) {
+  if (typeof value !== "string") {
+    errors.push(`${path}: expected a string`);
+    return;
+  }
+  const result = value.trim();
+  if ((options.nonEmpty ?? true) && !result) {
+    errors.push(`${path}: must not be empty`);
+    return;
+  }
+  if (options.pattern && !options.pattern.test(result)) {
+    errors.push(`${path}: invalid value "${result}"`);
+    return;
+  }
+  return result;
+}
+function readInteger(value, fallback, path, errors, limits) {
+  if (value === undefined)
+    return fallback;
+  if (!Number.isInteger(value) || value < limits.min || value > limits.max) {
+    errors.push(`${path}: expected an integer from ${limits.min} to ${limits.max}`);
+    return fallback;
+  }
+  return value;
+}
+function readBoolean(value, fallback, path, errors) {
+  if (value === undefined)
+    return fallback;
+  if (typeof value !== "boolean") {
+    errors.push(`${path}: expected a boolean`);
+    return fallback;
+  }
+  return value;
+}
+function readStringList(value, path, errors, pattern) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: expected an array of strings`);
+    return [];
+  }
+  const result = [];
+  const seen = new Set;
+  value.forEach((item, index) => {
+    const parsed = readString(item, `${path}[${index}]`, errors, { pattern });
+    if (!parsed)
+      return;
+    if (seen.has(parsed)) {
+      errors.push(`${path}[${index}]: duplicate value "${parsed}"`);
+      return;
+    }
+    seen.add(parsed);
+    result.push(parsed);
+  });
+  return result;
+}
+function parseBashRule(value, path, errors) {
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return [];
+  }
+  rejectUnknownKeys(value, ["executable", "argsPrefix", "argsPrefixes"], path, errors);
+  const executable = readString(value.executable, `${path}.executable`, errors, {
+    pattern: EXECUTABLE_PATTERN
+  });
+  if (value.argsPrefix !== undefined && value.argsPrefixes !== undefined) {
+    errors.push(`${path}: argsPrefix and argsPrefixes are mutually exclusive`);
+  }
+  if (value.argsPrefixes !== undefined) {
+    if (!Array.isArray(value.argsPrefixes)) {
+      errors.push(`${path}.argsPrefixes: expected an array of argument arrays`);
+      return [];
+    }
+    if (value.argsPrefixes.length === 0) {
+      errors.push(`${path}.argsPrefixes: at least one prefix is required`);
+    }
+    const prefixes = [];
+    const seen = new Set;
+    value.argsPrefixes.forEach((candidate, index) => {
+      const prefixPath = `${path}.argsPrefixes[${index}]`;
+      const prefix = readStringList(candidate, prefixPath, errors, /^[^\s]+$/);
+      if (Array.isArray(candidate) && candidate.length === 0) {
+        errors.push(`${prefixPath}: at least one argument is required`);
+        return;
+      }
+      if (prefix.length === 0)
+        return;
+      const key = JSON.stringify(prefix);
+      if (seen.has(key)) {
+        errors.push(`${prefixPath}: duplicate argument prefix`);
+        return;
+      }
+      seen.add(key);
+      prefixes.push(prefix);
+    });
+    return executable ? prefixes.map((argsPrefix2) => ({ executable, argsPrefix: argsPrefix2 })) : [];
+  }
+  const argsPrefix = readStringList(value.argsPrefix, `${path}.argsPrefix`, errors, /^[^\s]+$/);
+  return executable ? [{ executable, argsPrefix }] : [];
+}
+function parseBashPermission(value, path, errors) {
+  if (value === undefined) {
+    return { ...EMPTY_PERMISSIONS.bash, allow: [] };
+  }
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return { ...EMPTY_PERMISSIONS.bash, allow: [] };
+  }
+  rejectUnknownKeys(value, ["mode", "allow", "approvedSources"], path, errors);
+  const mode = readString(value.mode, `${path}.mode`, errors);
+  const validMode = mode === "deny" || mode === "read-only" || mode === "allow-list" || mode === "unrestricted";
+  if (!validMode) {
+    errors.push(`${path}.mode: expected deny, read-only, allow-list, or unrestricted`);
+  }
+  const allow = [];
+  if (value.allow !== undefined) {
+    if (!Array.isArray(value.allow)) {
+      errors.push(`${path}.allow: expected an array`);
+    } else {
+      value.allow.forEach((rule, index) => {
+        allow.push(...parseBashRule(rule, `${path}.allow[${index}]`, errors));
+      });
+    }
+  }
+  const approvedSources = (value.approvedSources === undefined ? [] : readStringList(value.approvedSources, `${path}.approvedSources`, errors, BASH_APPROVAL_SOURCE_PATTERN)).filter((source) => {
+    const valid = source === "verification-worker" || source === "verification-reviewer" || source === "remote-actions";
+    if (!valid) {
+      errors.push(`${path}.approvedSources: expected verification-worker, verification-reviewer, or remote-actions`);
+    }
+    return valid;
+  });
+  const normalizedMode = validMode ? mode : "deny";
+  if (normalizedMode !== "allow-list" && allow.length > 0) {
+    errors.push(`${path}.allow: only valid when mode is "allow-list"`);
+  }
+  if (normalizedMode === "allow-list" && allow.length === 0) {
+    if (approvedSources.length === 0) {
+      errors.push(`${path}: allow-list mode requires an allow rule or an approved command source`);
+    }
+  }
+  if (normalizedMode !== "allow-list" && approvedSources.length > 0) {
+    errors.push(`${path}.approvedSources: only valid when mode is "allow-list"`);
+  }
+  return {
+    mode: normalizedMode,
+    allow,
+    ...approvedSources.length > 0 ? { approvedSources } : {}
+  };
+}
+function parsePermissions(value, path, errors) {
+  if (value === undefined) {
+    return {
+      tools: [],
+      mcp: [],
+      extensions: [],
+      skills: [],
+      bash: { mode: "deny", allow: [] }
+    };
+  }
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return {
+      tools: [],
+      mcp: [],
+      extensions: [],
+      skills: [],
+      bash: { mode: "deny", allow: [] }
+    };
+  }
+  rejectUnknownKeys(value, ["tools", "mcp", "extensions", "skills", "bash"], path, errors);
+  const permissions = {
+    tools: readStringList(value.tools, `${path}.tools`, errors, TOOL_PATTERN),
+    mcp: readStringList(value.mcp, `${path}.mcp`, errors, MCP_SELECTOR_PATTERN),
+    extensions: readStringList(value.extensions, `${path}.extensions`, errors, RESOURCE_SELECTOR_PATTERN),
+    skills: readStringList(value.skills, `${path}.skills`, errors, RESOURCE_SELECTOR_PATTERN),
+    bash: parseBashPermission(value.bash, `${path}.bash`, errors)
+  };
+  if (permissions.bash.mode !== "deny" && !permissions.tools.includes("bash")) {
+    errors.push(`${path}.tools: must include "bash" when Bash is enabled`);
+  }
+  return permissions;
+}
+function parseRequirements(value, permissions, path, errors) {
+  if (value === undefined) {
+    return {
+      tools: [],
+      extensions: [],
+      skills: []
+    };
+  }
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return {
+      tools: [],
+      extensions: [],
+      skills: []
+    };
+  }
+  rejectUnknownKeys(value, ["tools", "extensions", "skills"], path, errors);
+  const requirements = {
+    tools: readStringList(value.tools, `${path}.tools`, errors, TOOL_PATTERN),
+    extensions: readStringList(value.extensions, `${path}.extensions`, errors, RESOURCE_SELECTOR_PATTERN),
+    skills: readStringList(value.skills, `${path}.skills`, errors, RESOURCE_SELECTOR_PATTERN)
+  };
+  for (const tool of requirements.tools) {
+    if (!permissions.tools.includes(tool) && !(tool === "mcp" && permissions.mcp.length > 0)) {
+      errors.push(`${path}.tools: required tool "${tool}" is not allowed by this step`);
+    }
+  }
+  for (const extension of requirements.extensions) {
+    if (!permissions.extensions.includes(extension)) {
+      errors.push(`${path}.extensions: required extension "${extension}" is not allowed by this step`);
+    }
+  }
+  for (const skill of requirements.skills) {
+    if (!permissions.skills.includes(skill)) {
+      errors.push(`${path}.skills: required skill "${skill}" is not allowed by this step`);
+    }
+  }
+  return requirements;
+}
+function parseSubagentTurnBudget(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, ["maxTurns", "graceTurns"], path, errors);
+  const maxTurns = readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
+    min: 1,
+    max: 1000
+  });
+  const graceTurns = value.graceTurns === undefined ? undefined : readInteger(value.graceTurns, 0, `${path}.graceTurns`, errors, {
+    min: 0,
+    max: 100
+  });
+  if (maxTurns === 0)
+    return;
+  return {
+    maxTurns,
+    ...graceTurns !== undefined ? { graceTurns } : {}
+  };
+}
+function parseSubagentToolBudget(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, ["soft", "hard", "block"], path, errors);
+  const hard = readInteger(value.hard, 0, `${path}.hard`, errors, {
+    min: 1,
+    max: 1e5
+  });
+  const soft = value.soft === undefined ? undefined : readInteger(value.soft, 0, `${path}.soft`, errors, {
+    min: 1,
+    max: 1e5
+  });
+  let block;
+  if (value.block === "*") {
+    block = "*";
+  } else if (value.block !== undefined) {
+    block = readStringList(value.block, `${path}.block`, errors, TOOL_PATTERN);
+    if (block.length === 0) {
+      errors.push(`${path}.block: expected "*" or at least one tool name`);
+    }
+  }
+  if (soft !== undefined && hard > 0 && soft > hard) {
+    errors.push(`${path}.soft: must not exceed hard`);
+  }
+  if (hard === 0)
+    return;
+  return {
+    hard,
+    ...soft !== undefined ? { soft } : {},
+    ...block !== undefined ? { block } : {}
+  };
+}
+function parseStepSubagent(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (typeof value === "string") {
+    const agent2 = readString(value, path, errors, {
+      pattern: SUBAGENT_RUNTIME_NAME_PATTERN
+    }) ?? DEFAULT_STEP_SUBAGENT.agent;
+    return { ...DEFAULT_STEP_SUBAGENT, agent: agent2 };
+  }
+  if (!isObject(value)) {
+    errors.push(`${path}: expected a workflow subagent name or object`);
+    return;
+  }
+  rejectUnknownKeys(value, [
+    "agent",
+    "context",
+    "model",
+    "timeoutMs",
+    "turnBudget",
+    "toolBudget",
+    "artifacts"
+  ], path, errors);
+  const agent = value.agent === undefined ? DEFAULT_STEP_SUBAGENT.agent : readString(value.agent, `${path}.agent`, errors, {
+    pattern: SUBAGENT_RUNTIME_NAME_PATTERN
+  }) ?? DEFAULT_STEP_SUBAGENT.agent;
+  const contextValue = value.context === undefined ? DEFAULT_STEP_SUBAGENT.context : readString(value.context, `${path}.context`, errors);
+  const context = contextValue === "fork" || contextValue === "fresh" ? contextValue : DEFAULT_STEP_SUBAGENT.context;
+  if (contextValue !== "fork" && contextValue !== "fresh") {
+    errors.push(`${path}.context: expected fresh or fork`);
+  }
+  const model = value.model === undefined ? undefined : readString(value.model, `${path}.model`, errors, {
+    pattern: RESOURCE_SELECTOR_PATTERN
+  });
+  const timeoutMs = readInteger(value.timeoutMs, DEFAULT_STEP_SUBAGENT.timeoutMs, `${path}.timeoutMs`, errors, { min: 1000, max: 86400000 });
+  const turnBudget = parseSubagentTurnBudget(value.turnBudget, `${path}.turnBudget`, errors);
+  const toolBudget = parseSubagentToolBudget(value.toolBudget, `${path}.toolBudget`, errors);
+  const artifacts = readBoolean(value.artifacts, DEFAULT_STEP_SUBAGENT.artifacts, `${path}.artifacts`, errors);
+  return {
+    agent,
+    context,
+    ...model ? { model } : {},
+    timeoutMs,
+    ...turnBudget ? { turnBudget } : {},
+    ...toolBudget ? { toolBudget } : {},
+    artifacts
+  };
+}
+function parsePrompt(value, path, errors) {
+  if (typeof value === "string") {
+    const inline = readString(value, path, errors);
+    return inline ? { inline } : undefined;
+  }
+  if (!isObject(value)) {
+    errors.push(`${path}: expected a string or an object`);
+    return;
+  }
+  rejectUnknownKeys(value, ["file"], path, errors);
+  const file = readString(value.file, `${path}.file`, errors);
+  if (!file)
+    return;
+  if (file.startsWith("/") || file.includes("\x00")) {
+    errors.push(`${path}.file: expected a safe relative path`);
+    return;
+  }
+  return { file };
+}
+function parseTransitions(value, path, errors) {
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return {};
+  }
+  const transitions = {};
+  for (const [outcome, targetValue] of Object.entries(value)) {
+    if (!OUTCOME_PATTERN.test(outcome)) {
+      errors.push(`${path}: invalid outcome "${outcome}"`);
+      continue;
+    }
+    const target = readString(targetValue, `${path}.${outcome}`, errors);
+    if (target)
+      transitions[outcome] = target;
+  }
+  if (Object.keys(transitions).length === 0) {
+    errors.push(`${path}: at least one transition is required`);
+  }
+  return transitions;
+}
+function parseGate(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, [
+    "provider",
+    "submitOutcome",
+    "approvedOutcome",
+    "rejectedOutcome",
+    "timeoutMs"
+  ], path, errors);
+  const providerValue = value.provider === undefined ? "prompt" : readString(value.provider, `${path}.provider`, errors);
+  const provider = providerValue === "prompt" || providerValue === "plannotator" ? providerValue : undefined;
+  if (!provider) {
+    errors.push(`${path}.provider: expected prompt or plannotator`);
+  }
+  const submitOutcome = readString(value.submitOutcome, `${path}.submitOutcome`, errors, {
+    pattern: OUTCOME_PATTERN
+  });
+  const approvedOutcome = readString(value.approvedOutcome, `${path}.approvedOutcome`, errors, {
+    pattern: OUTCOME_PATTERN
+  });
+  const rejectedOutcome = readString(value.rejectedOutcome, `${path}.rejectedOutcome`, errors, {
+    pattern: OUTCOME_PATTERN
+  });
+  if (provider === "prompt" && value.timeoutMs !== undefined) {
+    errors.push(`${path}.timeoutMs: only valid with provider "plannotator"`);
+  }
+  if (!submitOutcome || !approvedOutcome || !rejectedOutcome || !provider) {
+    return;
+  }
+  if (approvedOutcome === rejectedOutcome) {
+    errors.push(`${path}: approvedOutcome and rejectedOutcome must differ`);
+  }
+  if (provider === "prompt") {
+    return {
+      provider,
+      submitOutcome,
+      approvedOutcome,
+      rejectedOutcome
+    };
+  }
+  return {
+    provider,
+    submitOutcome,
+    approvedOutcome,
+    rejectedOutcome,
+    timeoutMs: readInteger(value.timeoutMs, 5000, `${path}.timeoutMs`, errors, {
+      min: 1000,
+      max: 30000
+    })
+  };
+}
+function parseStep(value, stepId, path, errors) {
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, [
+    "title",
+    "prompt",
+    "subagent",
+    "permissions",
+    "requires",
+    "transitions",
+    "gate"
+  ], path, errors);
+  const title = value.title === undefined ? stepId : readString(value.title, `${path}.title`, errors);
+  const prompt = parsePrompt(value.prompt, `${path}.prompt`, errors);
+  const subagent = parseStepSubagent(value.subagent, `${path}.subagent`, errors);
+  const permissions = parsePermissions(value.permissions, `${path}.permissions`, errors);
+  const requires = parseRequirements(value.requires, permissions, `${path}.requires`, errors);
+  const transitions = parseTransitions(value.transitions, `${path}.transitions`, errors);
+  const gate = parseGate(value.gate, `${path}.gate`, errors);
+  if (gate) {
+    if (!Object.hasOwn(transitions, gate.approvedOutcome)) {
+      errors.push(`${path}.transitions: missing gate outcome "${gate.approvedOutcome}"`);
+    }
+    if (!Object.hasOwn(transitions, gate.rejectedOutcome)) {
+      errors.push(`${path}.transitions: missing gate outcome "${gate.rejectedOutcome}"`);
+    }
+    if (Object.hasOwn(transitions, gate.submitOutcome)) {
+      errors.push(`${path}.transitions: submitOutcome is handled by the gate and must not be a transition`);
+    }
+  }
+  if (!title || !prompt)
+    return;
+  return {
+    title,
+    prompt,
+    ...subagent ? { subagent } : {},
+    permissions,
+    requires,
+    transitions,
+    ...gate ? { gate } : {}
+  };
+}
+function validatePromptText(text, path) {
+  const errors = [];
+  for (const match of text.matchAll(/\{\{([^{}]+)\}\}/g)) {
+    const variable = match[1]?.trim() ?? "";
+    if (!PROMPT_VARIABLES.has(variable)) {
+      errors.push(`${path}: unknown prompt variable "{{${variable}}}"`);
+    }
+  }
+  return errors;
+}
+function validateWorkflow(value) {
+  const errors = [];
+  if (!isObject(value)) {
+    return { errors: ["workflow: expected an object"] };
+  }
+  rejectUnknownKeys(value, [
+    "$schema",
+    "version",
+    "id",
+    "command",
+    "description",
+    "start",
+    "maxStepVisits",
+    "summaryMaxChars",
+    "steps"
+  ], "workflow", errors);
+  if (value.$schema !== undefined && typeof value.$schema !== "string") {
+    errors.push("workflow.$schema: expected a string");
+  }
+  if (value.version !== WORKFLOW_SCHEMA_VERSION) {
+    errors.push(`workflow.version: expected ${WORKFLOW_SCHEMA_VERSION}`);
+  }
+  const id = readString(value.id, "workflow.id", errors, {
+    pattern: IDENTIFIER_PATTERN
+  });
+  const command = readString(value.command, "workflow.command", errors, {
+    pattern: IDENTIFIER_PATTERN
+  });
+  const description = readString(value.description, "workflow.description", errors);
+  const start = readString(value.start, "workflow.start", errors, {
+    pattern: IDENTIFIER_PATTERN
+  });
+  const maxStepVisits = readInteger(value.maxStepVisits, 5, "workflow.maxStepVisits", errors, {
+    min: 1,
+    max: 100
+  });
+  const summaryMaxChars = readInteger(value.summaryMaxChars, 4000, "workflow.summaryMaxChars", errors, { min: 100, max: 50000 });
+  if (command && RESERVED_COMMAND_NAMES.has(command)) {
+    errors.push(`workflow.command: "${command}" is reserved by Pi or the harness`);
+  }
+  const steps = {};
+  if (!isObject(value.steps)) {
+    errors.push("workflow.steps: expected an object");
+  } else {
+    for (const [stepId, stepValue] of Object.entries(value.steps)) {
+      if (!IDENTIFIER_PATTERN.test(stepId)) {
+        errors.push(`workflow.steps: invalid step id "${stepId}"`);
+        continue;
+      }
+      const step = parseStep(stepValue, stepId, `workflow.steps.${stepId}`, errors);
+      if (step)
+        steps[stepId] = step;
+    }
+  }
+  if (Object.keys(steps).length === 0) {
+    errors.push("workflow.steps: at least one step is required");
+  }
+  if (start && !Object.hasOwn(steps, start)) {
+    errors.push(`workflow.start: unknown step "${start}"`);
+  }
+  for (const [stepId, step] of Object.entries(steps)) {
+    for (const [outcome, target] of Object.entries(step.transitions)) {
+      if (target !== "$done" && target !== "$pause" && !Object.hasOwn(steps, target)) {
+        errors.push(`workflow.steps.${stepId}.transitions.${outcome}: unknown target "${target}"`);
+      }
+    }
+  }
+  if (errors.length > 0 || !id || !command || !description || !start) {
+    return { errors };
+  }
+  return {
+    value: {
+      version: WORKFLOW_SCHEMA_VERSION,
+      id,
+      command,
+      description,
+      start,
+      maxStepVisits,
+      summaryMaxChars,
+      steps
+    },
+    errors
+  };
+}
+function parsePermissionCeiling(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, ["tools", "mcp", "extensions", "skills", "bash", "subagent"], path, errors);
+  const permissions = parsePermissions({
+    ...value.tools !== undefined ? { tools: value.tools } : {},
+    ...value.mcp !== undefined ? { mcp: value.mcp } : {},
+    ...value.extensions !== undefined ? { extensions: value.extensions } : {},
+    ...value.skills !== undefined ? { skills: value.skills } : {},
+    ...value.bash !== undefined ? { bash: value.bash } : {}
+  }, path, errors);
+  const subagent = value.subagent === undefined ? undefined : parseSubagentPermissionCeiling(value.subagent, `${path}.subagent`, errors);
+  return {
+    ...permissions,
+    ...subagent ? { subagent } : {}
+  };
+}
+function parseSubagentPermissionCeiling(value, path, errors) {
+  if (!isObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  rejectUnknownKeys(value, [
+    "agents",
+    "contexts",
+    "models",
+    "maxTimeoutMs",
+    "maxTurns",
+    "maxGraceTurns",
+    "maxToolCalls",
+    "artifacts"
+  ], path, errors);
+  const agents = readStringList(value.agents, `${path}.agents`, errors, SUBAGENT_RUNTIME_NAME_PATTERN);
+  const contexts = readStringList(value.contexts, `${path}.contexts`, errors, /^(?:fresh|fork)$/);
+  const models = readStringList(value.models, `${path}.models`, errors, RESOURCE_SELECTOR_PATTERN);
+  if (agents.length === 0) {
+    errors.push(`${path}.agents: at least one subagent is required`);
+  }
+  if (contexts.length === 0) {
+    errors.push(`${path}.contexts: at least one context mode is required`);
+  }
+  for (const field of [
+    "maxTimeoutMs",
+    "maxTurns",
+    "maxGraceTurns",
+    "maxToolCalls",
+    "artifacts"
+  ]) {
+    if (value[field] === undefined) {
+      errors.push(`${path}.${field}: required`);
+    }
+  }
+  const maxTimeoutMs = readInteger(value.maxTimeoutMs, 0, `${path}.maxTimeoutMs`, errors, { min: 1000, max: 86400000 });
+  const maxTurns = readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
+    min: 1,
+    max: 1000
+  });
+  const maxGraceTurns = readInteger(value.maxGraceTurns, 0, `${path}.maxGraceTurns`, errors, { min: 0, max: 100 });
+  const maxToolCalls = readInteger(value.maxToolCalls, 0, `${path}.maxToolCalls`, errors, { min: 1, max: 1e5 });
+  const artifacts = readBoolean(value.artifacts, false, `${path}.artifacts`, errors);
+  return {
+    agents,
+    contexts,
+    models,
+    maxTimeoutMs,
+    maxTurns,
+    maxGraceTurns,
+    maxToolCalls,
+    artifacts
+  };
+}
+function validateSettings(value) {
+  const errors = [];
+  if (!isObject(value)) {
+    return { errors: ["settings: expected an object"] };
+  }
+  rejectUnknownKeys(value, ["$schema", "version", "allowProjectWorkflows", "permissionCeiling"], "settings", errors);
+  if (value.$schema !== undefined && typeof value.$schema !== "string") {
+    errors.push("settings.$schema: expected a string");
+  }
+  if (value.version !== WORKFLOW_SCHEMA_VERSION) {
+    errors.push(`settings.version: expected ${WORKFLOW_SCHEMA_VERSION}`);
+  }
+  let allowProjectWorkflows = false;
+  if (typeof value.allowProjectWorkflows === "boolean") {
+    allowProjectWorkflows = value.allowProjectWorkflows;
+  } else if (value.allowProjectWorkflows !== undefined) {
+    errors.push("settings.allowProjectWorkflows: expected a boolean");
+  }
+  const permissionCeiling = parsePermissionCeiling(value.permissionCeiling, "settings.permissionCeiling", errors);
+  if (allowProjectWorkflows && !permissionCeiling) {
+    errors.push("settings.permissionCeiling: required when project workflows are enabled");
+  }
+  if (errors.length > 0)
+    return { errors };
+  return {
+    value: {
+      ...DEFAULT_SETTINGS,
+      allowProjectWorkflows,
+      ...permissionCeiling ? { permissionCeiling } : {}
+    },
+    errors
+  };
+}
+
+// src/config/load.ts
+function diagnostic(path, message, level = "error") {
+  return { path, message, level };
+}
+async function readYaml(path, kind) {
+  const text = await readFile(path, "utf8");
+  const document = parseDocument(text, {
+    customTags: [],
+    merge: false,
+    prettyErrors: true,
+    resolveKnownTags: false,
+    schema: "core",
+    strict: true,
+    stringKeys: true,
+    uniqueKeys: true,
+    version: "1.2"
+  });
+  const issues = [...document.errors, ...document.warnings];
+  if (issues.length > 0) {
+    throw new Error(issues.map((issue) => issue.message).join(`
+`));
+  }
+  if (document.directives.yaml.explicit && document.directives.yaml.version !== "1.2") {
+    throw new Error(`${kind} YAML must use version 1.2`);
+  }
+  return document.toJS({ maxAliasCount: 100 });
+}
+function isInside(root, candidate) {
+  const pathFromRoot = relative(root, candidate);
+  return pathFromRoot === "" || pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot);
+}
+async function loadPrompt(sourcePath, definition, stepId) {
+  const prompt = definition.steps[stepId]?.prompt;
+  if (!prompt)
+    throw new Error(`unknown step "${stepId}"`);
+  if ("inline" in prompt)
+    return prompt.inline;
+  const sourceDirectory = await realpath(dirname(sourcePath));
+  const requestedPath = resolve(sourceDirectory, prompt.file);
+  if (!isInside(sourceDirectory, requestedPath)) {
+    throw new Error(`prompt file escapes workflow directory: ${prompt.file}`);
+  }
+  const actualPath = await realpath(requestedPath);
+  if (!isInside(sourceDirectory, actualPath)) {
+    throw new Error(`prompt file symlink escapes workflow directory: ${prompt.file}`);
+  }
+  return readFile(actualPath, "utf8");
+}
+async function loadWorkflowFile(sourcePath, sourceKind) {
+  const raw = await readYaml(sourcePath, "workflow");
+  const validation = validateWorkflow(raw);
+  if (!validation.value) {
+    throw new Error(validation.errors.join(`
+`));
+  }
+  const definition = validation.value;
+  const prompts = {};
+  for (const stepId of Object.keys(definition.steps)) {
+    const text = await loadPrompt(sourcePath, definition, stepId);
+    const promptErrors = validatePromptText(text, `workflow.steps.${stepId}.prompt`);
+    if (promptErrors.length > 0) {
+      throw new Error(promptErrors.join(`
+`));
+    }
+    prompts[stepId] = text;
+  }
+  const stepDigests = Object.fromEntries(Object.entries(definition.steps).map(([stepId, step]) => [
+    stepId,
+    digest({ step, prompt: prompts[stepId] })
+  ]));
+  return {
+    definition,
+    prompts,
+    digest: digest({ definition, prompts }),
+    stepDigests,
+    sourcePath,
+    sourceKind
+  };
+}
+async function loadWorkflowDirectory(directory, sourceKind) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT")
+      return { workflows: [], diagnostics: [] };
+    return {
+      workflows: [],
+      diagnostics: [
+        diagnostic(directory, `cannot read workflow directory: ${String(error)}`)
+      ]
+    };
+  }
+  const workflows = [];
+  const diagnostics = [];
+  const files = entries.filter((entry) => entry.isFile() && /\.workflow\.ya?ml$/i.test(entry.name)).map((entry) => join(directory, entry.name)).sort();
+  for (const path of files) {
+    try {
+      workflows.push(await loadWorkflowFile(path, sourceKind));
+    } catch (error) {
+      diagnostics.push(diagnostic(path, error instanceof Error ? error.message : String(error)));
+    }
+  }
+  return { workflows, diagnostics };
+}
+async function loadSettings(userDirectory) {
+  const path = join(userDirectory, "settings.yaml");
+  try {
+    const validation = validateSettings(await readYaml(path, "settings"));
+    if (!validation.value) {
+      return {
+        settings: DEFAULT_SETTINGS,
+        diagnostics: validation.errors.map((message) => diagnostic(path, message))
+      };
+    }
+    return { settings: validation.value, diagnostics: [] };
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT")
+      return { settings: DEFAULT_SETTINGS, diagnostics: [] };
+    return {
+      settings: DEFAULT_SETTINGS,
+      diagnostics: [
+        diagnostic(path, `cannot read settings: ${error instanceof Error ? error.message : String(error)}`)
+      ]
+    };
+  }
+}
+function addWorkflow(catalog, commands, workflow, diagnostics) {
+  const id = workflow.definition.id;
+  const command = workflow.definition.command;
+  const existing = catalog.get(id);
+  if (existing) {
+    diagnostics.push(diagnostic(workflow.sourcePath, `workflow id "${id}" already belongs to ${existing.sourcePath}; overrides are not allowed`));
+    return;
+  }
+  const existingCommand = commands.get(command);
+  if (existingCommand) {
+    diagnostics.push(diagnostic(workflow.sourcePath, `command "/${command}" already belongs to workflow "${existingCommand}"`));
+    return;
+  }
+  catalog.set(id, workflow);
+  commands.set(command, id);
+}
+function defaultUserWorkflowDirectory() {
+  const explicit = process.env.PI_WORKFLOWS_DIR?.trim();
+  if (explicit)
+    return resolve(explicit);
+  const agentDirectory = process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent");
+  return join(agentDirectory, "workflows");
+}
+async function loadCatalog(options) {
+  const userDirectory = resolve(options.userDirectory ?? defaultUserWorkflowDirectory());
+  const diagnostics = [];
+  const settingsResult = await loadSettings(userDirectory);
+  diagnostics.push(...settingsResult.diagnostics);
+  const catalog = new Map;
+  const commands = new Map;
+  const userResult = await loadWorkflowDirectory(userDirectory, "user");
+  diagnostics.push(...userResult.diagnostics);
+  for (const workflow of userResult.workflows) {
+    addWorkflow(catalog, commands, workflow, diagnostics);
+  }
+  const projectDirectory = join(resolve(options.cwd), ".pi", "workflows");
+  if (settingsResult.settings.allowProjectWorkflows) {
+    if (!options.projectTrusted) {
+      diagnostics.push(diagnostic(projectDirectory, "project workflows were skipped because the project is not trusted", "warning"));
+    } else if (!settingsResult.settings.permissionCeiling) {
+      diagnostics.push(diagnostic(projectDirectory, "project workflows were skipped because no user permission ceiling is configured"));
+    } else {
+      const projectResult = await loadWorkflowDirectory(projectDirectory, "project");
+      diagnostics.push(...projectResult.diagnostics);
+      for (const workflow of projectResult.workflows) {
+        const ceilingErrors = checkWorkflowAgainstCeiling(workflow.definition, settingsResult.settings.permissionCeiling);
+        if (ceilingErrors.length > 0) {
+          diagnostics.push(...ceilingErrors.map((message) => diagnostic(workflow.sourcePath, message)));
+          continue;
+        }
+        addWorkflow(catalog, commands, workflow, diagnostics);
+      }
+    }
+  }
+  return {
+    workflows: catalog,
+    settings: settingsResult.settings,
+    diagnostics,
+    userDirectory,
+    ...settingsResult.settings.allowProjectWorkflows ? { projectDirectory } : {}
+  };
+}
+
+// src/config/command-conflicts.ts
+function isSuffixedInvocation(name, command) {
+  if (!name.startsWith(`${command}:`))
+    return false;
+  return /^\d+$/.test(name.slice(command.length + 1));
+}
+function hasRuntimeCommandConflict(command, availableCommands, ownedAliases) {
+  if (availableCommands.some((candidate) => isSuffixedInvocation(candidate.name, command))) {
+    return true;
+  }
+  return !ownedAliases.has(command) && availableCommands.some((candidate) => candidate.name === command);
+}
+
+// src/engine/transitions.ts
+function currentStep(workflow, run) {
+  return workflow.definition.steps[run.currentStepId];
+}
+function withUpdate(run, changes, now) {
+  return { ...run, ...changes, updatedAt: now };
+}
+function allowedOutcomes(workflow, run) {
+  const step = currentStep(workflow, run);
+  if (!step)
+    return [];
+  const gateResolutionOutcomes = step.gate ? new Set([step.gate.approvedOutcome, step.gate.rejectedOutcome]) : undefined;
+  return [
+    ...Object.keys(step.transitions).filter((outcome) => !gateResolutionOutcomes?.has(outcome)),
+    ...step.gate ? [step.gate.submitOutcome] : []
+  ];
+}
+function pauseRun(run, reason, now) {
+  if (run.status !== "running" && run.status !== "awaiting-gate") {
+    return withUpdate(run, { pauseReason: reason || run.pauseReason }, now);
+  }
+  return withUpdate(run, {
+    status: "paused",
+    pausedFrom: run.status,
+    pauseReason: reason || `Paused during step "${run.currentStepId}"`
+  }, now);
+}
+function resumeRun(run, now) {
+  if (run.status !== "paused")
+    return run;
+  return withUpdate(run, {
+    status: run.pausedFrom ?? (run.pendingGate ? "awaiting-gate" : "running"),
+    pauseReason: undefined,
+    pausedFrom: undefined
+  }, now);
+}
+function abortRun(run, reason, now) {
+  return withUpdate(run, {
+    status: "aborted",
+    pauseReason: reason || "Aborted by user",
+    pausedFrom: undefined,
+    pendingGate: undefined
+  }, now);
+}
+function advanceRun(workflow, run, outcome, summary, now) {
+  if (run.status !== "running") {
+    throw new Error(`workflow is ${run.status}; only a running workflow can advance`);
+  }
+  const step = currentStep(workflow, run);
+  if (!step)
+    throw new Error(`current step "${run.currentStepId}" no longer exists`);
+  if (step.gate?.submitOutcome === outcome) {
+    throw new Error(`outcome "${outcome}" must be submitted through the configured gate`);
+  }
+  const target = step.transitions[outcome];
+  if (!target) {
+    throw new Error(`outcome "${outcome}" is not valid for step "${run.currentStepId}"`);
+  }
+  if (target === "$pause") {
+    return withUpdate(run, {
+      status: "paused",
+      pausedFrom: "running",
+      pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
+      lastSummary: summary
+    }, now);
+  }
+  const completed = {
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    outcome,
+    summary,
+    completedAt: now
+  };
+  if (target === "$done") {
+    return withUpdate(run, {
+      status: "completed",
+      history: [...run.history, completed],
+      stepHandoff: summary,
+      lastSummary: summary,
+      gateFeedback: "",
+      pausedFrom: undefined,
+      pendingGate: undefined
+    }, now);
+  }
+  const nextStep = workflow.definition.steps[target];
+  if (!nextStep)
+    throw new Error(`transition target "${target}" does not exist`);
+  const nextVisitCount = (run.visits[target] ?? 0) + 1;
+  const visits = { ...run.visits, [target]: nextVisitCount };
+  const overVisitLimit = nextVisitCount > workflow.definition.maxStepVisits;
+  return withUpdate(run, {
+    status: overVisitLimit ? "paused" : "running",
+    currentStepId: target,
+    currentStepDigest: workflow.stepDigests[target] ?? "",
+    visits,
+    history: [...run.history, completed],
+    stepHandoff: summary,
+    lastSummary: summary,
+    gateFeedback: "",
+    ...overVisitLimit ? {
+      pausedFrom: "running",
+      pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`
+    } : { pausedFrom: undefined, pauseReason: undefined }
+  }, now);
+}
+function beginGate(workflow, run, outcome, artifact, requestId, now) {
+  if (run.status !== "running") {
+    throw new Error(`workflow is ${run.status}; gate submission requires a running workflow`);
+  }
+  const step = currentStep(workflow, run);
+  if (!step?.gate)
+    throw new Error(`step "${run.currentStepId}" has no gate`);
+  if (outcome !== step.gate.submitOutcome) {
+    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
+  }
+  if (!artifact.trim())
+    throw new Error("gate submission requires a non-empty artifact");
+  if (!requestId)
+    throw new Error("gate submission requires a request id");
+  return withUpdate(run, {
+    status: "awaiting-gate",
+    pendingGate: {
+      provider: step.gate.provider,
+      requestId,
+      stepId: run.currentStepId,
+      artifact,
+      submittedOutcome: outcome,
+      requestedAt: now
+    }
+  }, now);
+}
+function attachGateReviewId(run, reviewId, now) {
+  if (!run.pendingGate)
+    throw new Error("workflow has no pending gate");
+  if (run.pendingGate.provider !== "plannotator") {
+    throw new Error("only a Plannotator gate can have a review id");
+  }
+  return withUpdate(run, { pendingGate: { ...run.pendingGate, reviewId } }, now);
+}
+function failGate(run, reason, now) {
+  if (!run.pendingGate)
+    return run;
+  return withUpdate(run, {
+    status: "running",
+    pendingGate: undefined,
+    gateFeedback: reason
+  }, now);
+}
+function storeGateResolution(run, resolution, now) {
+  if (!run.pendingGate)
+    return run;
+  return withUpdate(run, { pendingGate: { ...run.pendingGate, resolution } }, now);
+}
+function resolveGate(workflow, run, resolution, now) {
+  const pending = run.pendingGate;
+  if (!pending)
+    throw new Error("workflow has no pending gate");
+  const step = workflow.definition.steps[pending.stepId];
+  if (!step?.gate)
+    throw new Error(`gated step "${pending.stepId}" no longer exists`);
+  if (run.currentStepId !== pending.stepId) {
+    throw new Error("gate result does not match the current step");
+  }
+  const outcome = resolution.approved ? step.gate.approvedOutcome : step.gate.rejectedOutcome;
+  const summary = resolution.approved ? pending.artifact : resolution.feedback ? `Gate ${resolution.approved ? "approved" : "rejected"}: ${resolution.feedback}` : `Gate ${resolution.approved ? "approved" : "rejected"}`;
+  const runnable = withUpdate(run, {
+    status: "running",
+    pendingGate: undefined,
+    ...resolution.approved ? { reviewedArtifact: pending.artifact } : {},
+    pausedFrom: undefined,
+    pauseReason: undefined,
+    gateFeedback: resolution.feedback
+  }, now);
+  const advanced = advanceRun(workflow, runnable, outcome, summary, now);
+  return {
+    ...advanced,
+    gateFeedback: resolution.feedback
+  };
+}
+function rebuildVisits(history, currentStepId) {
+  const visits = {};
+  for (const entry of history) {
+    visits[entry.stepId] = (visits[entry.stepId] ?? 0) + 1;
+  }
+  visits[currentStepId] = (visits[currentStepId] ?? 0) + 1;
+  return visits;
+}
+function retainedReviewedArtifact(workflow, run, history) {
+  const reviewedArtifact = run.reviewedArtifact ?? "";
+  if (!reviewedArtifact)
+    return "";
+  const sourceRetained = history.some((entry) => {
+    const gate = workflow.definition.steps[entry.stepId]?.gate;
+    return gate !== undefined && entry.outcome === gate.approvedOutcome && entry.summary === reviewedArtifact;
+  });
+  return sourceRetained ? reviewedArtifact : "";
+}
+function reconcileRun(run, workflow, now) {
+  if (run.workflowId !== workflow.definition.id) {
+    return {
+      changed: false,
+      error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
+  if (!workflow.definition.steps[run.currentStepId]) {
+    return {
+      changed: true,
+      error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`
+    };
+  }
+  const changedHistoryIndex = run.history.findIndex((entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest);
+  if (changedHistoryIndex >= 0) {
+    const changedEntry = run.history[changedHistoryIndex];
+    if (!changedEntry || !workflow.definition.steps[changedEntry.stepId]) {
+      return {
+        changed: true,
+        error: "a completed step was removed; abort or restore the configuration"
+      };
+    }
+    const retainedHistory = run.history.slice(0, changedHistoryIndex);
+    const restartedStep = changedEntry.stepId;
+    const stepHandoff = retainedHistory.at(-1)?.summary ?? "";
+    const reviewedArtifact = retainedReviewedArtifact(workflow, run, retainedHistory);
+    return {
+      changed: true,
+      restartedStep,
+      run: withUpdate(run, {
+        workflowDigest: workflow.digest,
+        status: "paused",
+        currentStepId: restartedStep,
+        currentStepDigest: workflow.stepDigests[restartedStep] ?? "",
+        history: retainedHistory,
+        visits: rebuildVisits(retainedHistory, restartedStep),
+        reviewedArtifact,
+        stepHandoff,
+        lastSummary: stepHandoff,
+        pendingGate: undefined,
+        pausedFrom: "running",
+        pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
+        gateFeedback: ""
+      }, now)
+    };
+  }
+  const currentDigest = workflow.stepDigests[run.currentStepId] ?? "";
+  const currentChanged = currentDigest !== run.currentStepDigest;
+  return {
+    changed: true,
+    ...currentChanged ? { restartedStep: run.currentStepId } : {},
+    run: withUpdate(run, {
+      workflowDigest: workflow.digest,
+      currentStepDigest: currentDigest,
+      ...currentChanged ? {
+        status: "paused",
+        pendingGate: undefined,
+        pausedFrom: "running",
+        pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
+        gateFeedback: ""
+      } : {}
+    }, now)
+  };
+}
+
+// src/engine/state.ts
+var RUN_STATE_VERSION = 1;
+function createRun(workflow, input, baselineTools, runId, now) {
+  const start = workflow.definition.start;
+  return {
+    stateVersion: RUN_STATE_VERSION,
+    runId,
+    workflowId: workflow.definition.id,
+    workflowDigest: workflow.digest,
+    input,
+    status: "running",
+    currentStepId: start,
+    currentStepDigest: workflow.stepDigests[start] ?? "",
+    baselineTools: [...new Set(baselineTools)],
+    visits: { [start]: 1 },
+    history: [],
+    startedAt: now,
+    updatedAt: now,
+    reviewedArtifact: "",
+    stepHandoff: "",
+    lastSummary: "",
+    gateFeedback: ""
+  };
+}
+function isWorkflowRun(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const run = value;
+  const historyIsValid = Array.isArray(run.history) && run.history.every((entry) => entry !== null && typeof entry === "object" && typeof entry.stepId === "string" && typeof entry.stepDigest === "string" && typeof entry.outcome === "string" && typeof entry.summary === "string" && typeof entry.completedAt === "number");
+  const visitsAreValid = run.visits !== null && typeof run.visits === "object" && !Array.isArray(run.visits) && Object.values(run.visits).every((count) => Number.isInteger(count) && count >= 0);
+  const gateIsValid = run.pendingGate === undefined || run.pendingGate !== null && typeof run.pendingGate === "object" && (run.pendingGate.provider === "prompt" || run.pendingGate.provider === "plannotator") && typeof run.pendingGate.requestId === "string" && run.pendingGate.requestId.length > 0 && typeof run.pendingGate.stepId === "string" && typeof run.pendingGate.artifact === "string" && (run.pendingGate.summary === undefined || typeof run.pendingGate.summary === "string") && typeof run.pendingGate.submittedOutcome === "string" && typeof run.pendingGate.requestedAt === "number" && (run.pendingGate.reviewId === undefined || typeof run.pendingGate.reviewId === "string") && (run.pendingGate.resolution === undefined || run.pendingGate.resolution !== null && typeof run.pendingGate.resolution === "object" && typeof run.pendingGate.resolution.approved === "boolean" && typeof run.pendingGate.resolution.feedback === "string" && typeof run.pendingGate.resolution.resolvedAt === "number");
+  const optionalsAreValid = (run.reviewedArtifact === undefined || typeof run.reviewedArtifact === "string") && (run.stepHandoff === undefined || typeof run.stepHandoff === "string") && (run.pauseReason === undefined || typeof run.pauseReason === "string") && (run.pausedFrom === undefined || run.pausedFrom === "running" || run.pausedFrom === "awaiting-gate");
+  const statusIsValid = run.status === "running" || run.status === "paused" || run.status === "awaiting-gate" || run.status === "completed" || run.status === "aborted";
+  const pauseStateIsValid = run.status === "paused" ? run.pausedFrom === "running" || run.pausedFrom === "awaiting-gate" : run.pausedFrom === undefined;
+  const gateStateIsValid = !gateIsValid ? false : run.pendingGate === undefined ? run.status !== "awaiting-gate" && run.pausedFrom !== "awaiting-gate" : run.pendingGate.stepId === run.currentStepId && (run.status === "awaiting-gate" || run.status === "paused" && run.pausedFrom === "awaiting-gate");
+  return run.stateVersion === RUN_STATE_VERSION && typeof run.runId === "string" && typeof run.workflowId === "string" && typeof run.workflowDigest === "string" && typeof run.input === "string" && typeof run.currentStepId === "string" && typeof run.currentStepDigest === "string" && Array.isArray(run.baselineTools) && run.baselineTools.every((tool) => typeof tool === "string") && historyIsValid && visitsAreValid && gateIsValid && optionalsAreValid && statusIsValid && pauseStateIsValid && gateStateIsValid && typeof run.startedAt === "number" && typeof run.updatedAt === "number" && typeof run.lastSummary === "string" && typeof run.gateFeedback === "string";
+}
+
+// src/engine/checkpoint.ts
+function readLatestCheckpoint(entries, customType) {
+  for (let index = entries.length - 1;index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== "custom" || entry.customType !== customType)
+      continue;
+    return isWorkflowRun(entry.data) ? { status: "valid", run: structuredClone(entry.data) } : { status: "invalid" };
+  }
+  return { status: "none" };
+}
+
+// src/engine/resume.ts
+function captureResumeCheckpoint(run, sessionEpoch) {
+  return {
+    sessionEpoch,
+    runId: run.runId,
+    workflowId: run.workflowId,
+    currentStepId: run.currentStepId,
+    ...run.pendingGate?.reviewId ? { reviewId: run.pendingGate.reviewId } : {}
+  };
+}
+function matchesResumeCheckpoint(run, sessionEpoch, checkpoint) {
+  return sessionEpoch === checkpoint.sessionEpoch && run?.status === "paused" && run.runId === checkpoint.runId && run.workflowId === checkpoint.workflowId && run.currentStepId === checkpoint.currentStepId && run.pendingGate?.reviewId === checkpoint.reviewId;
+}
+
+// src/integrations/plannotator.ts
+var PLANNOTATOR_REQUEST_CHANNEL = "plannotator:request";
+var PLANNOTATOR_RESULT_CHANNEL = "plannotator:review-result";
+function errorText(value, fallback) {
+  return typeof value.error === "string" && value.error.trim() ? value.error : fallback;
+}
+function normalizeStartResponse(value) {
+  if (value === null || typeof value !== "object") {
+    return {
+      status: "error",
+      error: "Plannotator returned an invalid response"
+    };
+  }
+  const response = value;
+  if (response.status === "unavailable") {
+    return {
+      status: "unavailable",
+      error: errorText(response, "Plannotator is unavailable")
+    };
+  }
+  if (response.status === "error") {
+    return {
+      status: "error",
+      error: errorText(response, "Plannotator failed")
+    };
+  }
+  const result = response.result !== null && typeof response.result === "object" ? response.result : undefined;
+  if (response.status === "handled" && result?.status === "pending" && typeof result.reviewId === "string") {
+    return {
+      status: "handled",
+      result: { status: "pending", reviewId: result.reviewId }
+    };
+  }
+  return {
+    status: "error",
+    error: "Plannotator returned an invalid start result"
+  };
+}
+function normalizeStatusResponse(value, requestedReviewId) {
+  if (value === null || typeof value !== "object") {
+    return {
+      status: "error",
+      error: "Plannotator returned an invalid response"
+    };
+  }
+  const response = value;
+  if (response.status === "unavailable") {
+    return {
+      status: "unavailable",
+      error: errorText(response, "Plannotator is unavailable")
+    };
+  }
+  if (response.status === "error") {
+    return {
+      status: "error",
+      error: errorText(response, "Plannotator failed")
+    };
+  }
+  const result = response.result !== null && typeof response.result === "object" ? response.result : undefined;
+  if (response.status !== "handled" || !result) {
+    return {
+      status: "error",
+      error: "Plannotator returned an invalid status result"
+    };
+  }
+  if (result.status === "pending" || result.status === "missing") {
+    return { status: "handled", result: { status: result.status } };
+  }
+  if (result.status === "completed" && typeof result.reviewId === "string" && typeof result.approved === "boolean") {
+    if (result.reviewId !== requestedReviewId) {
+      return {
+        status: "error",
+        error: "Plannotator returned a result for a different review"
+      };
+    }
+    return {
+      status: "handled",
+      result: {
+        status: "completed",
+        reviewId: result.reviewId,
+        approved: result.approved,
+        feedback: typeof result.feedback === "string" ? result.feedback : ""
+      }
+    };
+  }
+  return {
+    status: "error",
+    error: "Plannotator returned an invalid status result"
+  };
+}
+function parsePlannotatorResult(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const result = value;
+  if (typeof result.reviewId !== "string" || typeof result.approved !== "boolean") {
+    return;
+  }
+  return {
+    reviewId: result.reviewId,
+    approved: result.approved,
+    feedback: typeof result.feedback === "string" ? result.feedback : ""
+  };
+}
+function requestPlannotatorReview(events, requestId, content, origin, timeoutMs) {
+  return new Promise((resolve2) => {
+    let settled = false;
+    const finish = (response) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2(normalizeStartResponse(response));
+    };
+    const timer = setTimeout(() => finish({
+      status: "unavailable",
+      error: `Plannotator did not respond within ${timeoutMs}ms`
+    }), timeoutMs);
+    timer.unref?.();
+    events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
+      requestId,
+      action: "plan-review",
+      payload: {
+        planContent: content,
+        origin
+      },
+      respond: finish
+    });
+  });
+}
+function requestPlannotatorReviewStatus(events, requestId, reviewId, timeoutMs) {
+  return new Promise((resolve2) => {
+    let settled = false;
+    const finish = (response) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2(normalizeStatusResponse(response, reviewId));
+    };
+    const timer = setTimeout(() => finish({
+      status: "unavailable",
+      error: `Plannotator did not respond within ${timeoutMs}ms`
+    }), timeoutMs);
+    timer.unref?.();
+    events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
+      requestId,
+      action: "review-status",
+      payload: { reviewId },
+      respond: finish
+    });
+  });
+}
+
+// src/integrations/prompt-gate.ts
+var APPROVE = "Approve";
+var REQUEST_CHANGES = "Request changes";
+var PAUSE = "Pause workflow";
+async function requestPromptGateReview(ui, title, artifact, signal) {
+  const choice = await ui.select(`${title}
+
+${artifact}`, [APPROVE, REQUEST_CHANGES, PAUSE], ...signal ? [{ signal }] : []);
+  if (choice === APPROVE) {
+    return { status: "resolved", approved: true, feedback: "" };
+  }
+  if (choice !== REQUEST_CHANGES) {
+    return { status: "dismissed" };
+  }
+  while (true) {
+    const feedback = await ui.input("Workflow review feedback", "Describe the required changes", ...signal ? [{ signal }] : []);
+    if (feedback === undefined) {
+      return { status: "dismissed" };
+    }
+    if (feedback.trim()) {
+      return {
+        status: "resolved",
+        approved: false,
+        feedback: feedback.trim()
+      };
+    }
+    ui.notify("Feedback cannot be empty", "warning");
+  }
+}
+
+// src/integrations/subagents/protocol.ts
+import { tmpdir } from "node:os";
+import { basename, dirname as dirname2, relative as relative2, resolve as resolve2 } from "node:path";
+
+// src/runtime/step-result.ts
+function isObject2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseWorkflowStepResult(value, policy) {
+  if (!isObject2(value))
+    throw new Error("workflow step result must be an object");
+  const allowedKeys = new Set([
+    "version",
+    "policyDigest",
+    "outcome",
+    "summary",
+    "artifact"
+  ]);
+  const unknownKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unknownKey) {
+    throw new Error(`workflow step result has unknown property "${unknownKey}"`);
+  }
+  if (value.version !== 1)
+    throw new Error("unsupported workflow step result version");
+  if (value.policyDigest !== policy.policyDigest) {
+    throw new Error("workflow step result does not match the active policy");
+  }
+  if (typeof value.outcome !== "string" || !policy.outcomes.includes(value.outcome)) {
+    throw new Error(`workflow step returned invalid outcome "${String(value.outcome)}"`);
+  }
+  if (typeof value.summary !== "string") {
+    throw new Error("workflow step summary must be a string");
+  }
+  const summary = value.summary.trim();
+  if (!summary) {
+    throw new Error("workflow step summary must not be empty");
+  }
+  if (summary.length > policy.summaryMaxChars) {
+    throw new Error(`workflow step summary exceeds ${policy.summaryMaxChars} characters`);
+  }
+  if (value.artifact !== undefined && typeof value.artifact !== "string") {
+    throw new Error("workflow step artifact must be a string");
+  }
+  const artifact = typeof value.artifact === "string" ? value.artifact : undefined;
+  if (artifact !== undefined && artifact.length > 200000) {
+    throw new Error("workflow step artifact exceeds 200000 characters");
+  }
+  if (value.outcome === policy.gateSubmitOutcome && (!artifact || !artifact.trim())) {
+    throw new Error("workflow gate outcome requires a non-empty artifact");
+  }
+  return {
+    version: 1,
+    policyDigest: policy.policyDigest,
+    outcome: value.outcome,
+    summary,
+    ...artifact !== undefined ? { artifact } : {}
+  };
+}
+
+// src/integrations/subagents/protocol.ts
+var SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1;
+var SUBAGENT_DELEGATION_REQUEST_EVENT = "prompt-template:subagent:request";
+var SUBAGENT_DELEGATION_STARTED_EVENT = "prompt-template:subagent:started";
+var SUBAGENT_DELEGATION_UPDATE_EVENT = "prompt-template:subagent:update";
+var SUBAGENT_DELEGATION_RESPONSE_EVENT = "prompt-template:subagent:response";
+var SUBAGENT_DELEGATION_CANCEL_EVENT = "prompt-template:subagent:cancel";
+var CHILD_POLICY_OPEN = "<pi-workflows-policy-v1>";
+var CHILD_POLICY_CLOSE = "</pi-workflows-policy-v1>";
+var FORK_TASK_BOUNDARY = `
+
+Task:
+`;
+var POLICY_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+var CAPABILITY_TOKEN_PATTERN = /^[a-f0-9]{64}$/;
+var RESULT_FILE_NAME = "result.json";
+var CAPABILITY_FILE_NAME = "capability";
+var RESULT_DIRECTORY_PREFIX = "pi-workflows-step-";
+function isObject3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isStepPermissions(value) {
+  if (!isObject3(value) || !isObject3(value.bash))
+    return false;
+  const bash = value.bash;
+  const modeIsValid = bash.mode === "deny" || bash.mode === "read-only" || bash.mode === "allow-list" || bash.mode === "unrestricted";
+  const rulesAreValid = Array.isArray(bash.allow) && bash.allow.every((rule) => isObject3(rule) && typeof rule.executable === "string" && isStringArray(rule.argsPrefix));
+  const approvedSourcesAreValid = bash.approvedSources === undefined || isStringArray(bash.approvedSources) && new Set(bash.approvedSources).size === bash.approvedSources.length && bash.approvedSources.every((source) => source === "verification-worker" || source === "verification-reviewer" || source === "remote-actions");
+  const approvalShapeIsValid = bash.mode === "allow-list" ? bash.allow.length > 0 || Array.isArray(bash.approvedSources) && bash.approvedSources.length > 0 : bash.approvedSources === undefined;
+  return isStringArray(value.tools) && isStringArray(value.mcp) && isStringArray(value.extensions) && isStringArray(value.skills) && modeIsValid && rulesAreValid && approvedSourcesAreValid && approvalShapeIsValid;
+}
+function isSafeStepFilePath(path, expectedName) {
+  const base = resolve2(tmpdir());
+  const candidate = resolve2(path);
+  const fromBase = relative2(base, candidate);
+  return fromBase !== "" && !fromBase.startsWith("..") && !fromBase.includes("\x00") && basename(candidate) === expectedName && basename(dirname2(candidate)).startsWith(RESULT_DIRECTORY_PREFIX);
+}
+function isSafeStepResultPath(path) {
+  return isSafeStepFilePath(path, RESULT_FILE_NAME);
+}
+function isSafeStepCapabilityPath(path) {
+  return isSafeStepFilePath(path, CAPABILITY_FILE_NAME);
+}
+function isSubagentRuntimeName(name) {
+  return Boolean(name && SUBAGENT_RUNTIME_NAME_PATTERN.test(name));
+}
+function parseChildPolicy(value) {
+  if (!isObject3(value))
+    throw new Error("child policy must be an object");
+  const allowedKeys = new Set([
+    "version",
+    "requestId",
+    "agent",
+    "workflowId",
+    "runId",
+    "stepId",
+    "stepTitle",
+    "policyDigest",
+    "capabilityPath",
+    "capabilityToken",
+    "resultPath",
+    "permissions",
+    "approvedBashCommands",
+    "outcomes",
+    "summaryMaxChars",
+    "gateSubmitOutcome"
+  ]);
+  const unknownKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unknownKey) {
+    throw new Error(`child policy has unknown property "${unknownKey}"`);
+  }
+  const stringFields = [
+    "requestId",
+    "agent",
+    "workflowId",
+    "runId",
+    "stepId",
+    "stepTitle",
+    "policyDigest",
+    "capabilityPath",
+    "capabilityToken",
+    "resultPath"
+  ];
+  for (const field of stringFields) {
+    if (typeof value[field] !== "string" || !value[field]) {
+      throw new Error(`child policy ${field} must be a non-empty string`);
+    }
+  }
+  if (value.version !== 1)
+    throw new Error("unsupported child policy version");
+  if (!POLICY_DIGEST_PATTERN.test(value.policyDigest)) {
+    throw new Error("child policy digest is invalid");
+  }
+  if (!isSubagentRuntimeName(value.agent)) {
+    throw new Error("child policy agent is not a valid subagent runtime name");
+  }
+  if (!CAPABILITY_TOKEN_PATTERN.test(value.capabilityToken)) {
+    throw new Error("child policy capability token is invalid");
+  }
+  if (!isSafeStepCapabilityPath(value.capabilityPath)) {
+    throw new Error("child policy capability path is outside its temporary directory");
+  }
+  if (!isSafeStepResultPath(value.resultPath)) {
+    throw new Error("child policy result path is outside its temporary directory");
+  }
+  if (dirname2(resolve2(value.capabilityPath)) !== dirname2(resolve2(value.resultPath))) {
+    throw new Error("child policy files must share one temporary directory");
+  }
+  if (!isStepPermissions(value.permissions)) {
+    throw new Error("child policy permissions are invalid");
+  }
+  if (value.approvedBashCommands !== undefined && (!isStringArray(value.approvedBashCommands) || new Set(value.approvedBashCommands).size !== value.approvedBashCommands.length)) {
+    throw new Error("child policy approved Bash commands are invalid");
+  }
+  if (!isStringArray(value.outcomes) || value.outcomes.length === 0 || new Set(value.outcomes).size !== value.outcomes.length) {
+    throw new Error("child policy outcomes are invalid");
+  }
+  if (!Number.isInteger(value.summaryMaxChars) || value.summaryMaxChars < 100 || value.summaryMaxChars > 50000) {
+    throw new Error("child policy summaryMaxChars is invalid");
+  }
+  if (value.gateSubmitOutcome !== undefined && (typeof value.gateSubmitOutcome !== "string" || !value.outcomes.includes(value.gateSubmitOutcome))) {
+    throw new Error("child policy gate outcome is invalid");
+  }
+  return value;
+}
+function encodeChildPolicy(policy) {
+  const encoded = Buffer.from(JSON.stringify(policy), "utf8").toString("base64url");
+  return `${CHILD_POLICY_OPEN}${encoded}${CHILD_POLICY_CLOSE}`;
+}
+function extractChildPolicy(text) {
+  let start = 0;
+  if (!text.startsWith(CHILD_POLICY_OPEN)) {
+    const forkStart = text.indexOf(`${FORK_TASK_BOUNDARY}${CHILD_POLICY_OPEN}`);
+    if (forkStart === -1)
+      return;
+    start = forkStart + FORK_TASK_BOUNDARY.length;
+  }
+  const payloadStart = start + CHILD_POLICY_OPEN.length;
+  const end = text.indexOf(CHILD_POLICY_CLOSE, payloadStart);
+  if (end === -1 || text.indexOf(CHILD_POLICY_OPEN, payloadStart) !== -1) {
+    throw new Error("delegated task contains an invalid child policy envelope");
+  }
+  const encoded = text.slice(payloadStart, end);
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    throw new Error("delegated task child policy cannot be decoded");
+  }
+  const task = `${text.slice(0, start)}${text.slice(end + CHILD_POLICY_CLOSE.length)}`.trim();
+  if (!task)
+    throw new Error("delegated task is empty after policy extraction");
+  return { policy: parseChildPolicy(decoded), task };
+}
+function parseDelegatedStepResult(value, policy) {
+  try {
+    return parseWorkflowStepResult(value, policy);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(message.replaceAll("workflow step", "delegated step"), {
+      cause: error
+    });
+  }
+}
+
+// src/integrations/subagents/client.ts
+var DELEGATION_STATUSES = new Set([
+  "completed",
+  "failed",
+  "timed_out",
+  "cancelled",
+  "interrupted",
+  "turn_budget_exhausted",
+  "tool_budget_exhausted",
+  "acceptance_failed",
+  "invalid_request",
+  "unavailable_context"
+]);
+function requestIdOf(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const requestId = value.requestId;
+  return typeof requestId === "string" ? requestId : undefined;
+}
+function parseResponse(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const response = value;
+  if (response.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION || typeof response.requestId !== "string" || typeof response.status !== "string" || !DELEGATION_STATUSES.has(response.status)) {
+    return;
+  }
+  return response;
+}
+function parseUpdate(value) {
+  if (value === null || typeof value !== "object")
+    return;
+  const update = value;
+  if (update.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION || typeof update.requestId !== "string") {
+    return;
+  }
+  return update;
+}
+
+class SubagentDelegationClient {
+  events;
+  active;
+  constructor(events) {
+    this.events = events;
+  }
+  get activeRequestId() {
+    return this.active?.requestId;
+  }
+  delegate(request, options = {}) {
+    if (this.active) {
+      return Promise.reject(new Error(`subagent request "${this.active.requestId}" is still active`));
+    }
+    if (options.signal?.aborted) {
+      return Promise.reject(new Error("subagent delegation was cancelled"));
+    }
+    let start = () => {
+      return;
+    };
+    let requestCancellation = () => {
+      return;
+    };
+    let resolveTerminal = () => {
+      return;
+    };
+    const terminal = new Promise((resolve3) => {
+      resolveTerminal = resolve3;
+    });
+    const delegation = new Promise((resolve3, reject) => {
+      let settled = false;
+      let cancellationRequested = false;
+      const subscriptions = [];
+      const startTimeoutMs = options.startTimeoutMs ?? 3000;
+      const overallTimeoutMs = (request.timeoutMs ?? 900000) + 5000;
+      const subscribe = (event, handler) => {
+        const unsubscribe = this.events.on(event, handler);
+        if (typeof unsubscribe === "function")
+          subscriptions.push(unsubscribe);
+      };
+      const stopLocalWatchers = () => {
+        clearTimeout(startTimer);
+        clearTimeout(overallTimer);
+        options.signal?.removeEventListener("abort", abort);
+      };
+      const cleanup = () => {
+        stopLocalWatchers();
+        for (const unsubscribe of subscriptions)
+          unsubscribe();
+        if (this.active?.requestId === request.requestId)
+          this.active = undefined;
+      };
+      const finish = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        cleanup();
+        if ("response" in result)
+          resolve3(result.response);
+        else
+          reject(result.error);
+      };
+      const emitCancel = () => {
+        if (cancellationRequested || settled)
+          return;
+        cancellationRequested = true;
+        this.events.emit(SUBAGENT_DELEGATION_CANCEL_EVENT, {
+          version: SUBAGENT_DELEGATION_PROTOCOL_VERSION,
+          requestId: request.requestId
+        });
+      };
+      const failAndCancel = (reason) => {
+        if (settled)
+          return;
+        emitCancel();
+        if (settled)
+          return;
+        settled = true;
+        stopLocalWatchers();
+        reject(new Error(reason));
+      };
+      const abort = () => {
+        failAndCancel("subagent delegation was cancelled");
+      };
+      requestCancellation = emitCancel;
+      subscribe(SUBAGENT_DELEGATION_STARTED_EVENT, (data) => {
+        if (requestIdOf(data) !== request.requestId)
+          return;
+        clearTimeout(startTimer);
+      });
+      subscribe(SUBAGENT_DELEGATION_UPDATE_EVENT, (data) => {
+        const update = parseUpdate(data);
+        if (!update || update.requestId !== request.requestId)
+          return;
+        options.onUpdate?.(update);
+      });
+      subscribe(SUBAGENT_DELEGATION_RESPONSE_EVENT, (data) => {
+        const response = parseResponse(data);
+        if (!response || response.requestId !== request.requestId)
+          return;
+        resolveTerminal();
+        if (settled) {
+          cleanup();
+          options.onLateTerminal?.(response);
+          return;
+        }
+        finish({ response });
+      });
+      const startTimer = setTimeout(() => {
+        failAndCancel("pi-subagents did not accept the delegation request; verify it is installed and loaded");
+      }, startTimeoutMs);
+      const overallTimer = setTimeout(() => {
+        failAndCancel("pi-subagents did not settle the delegation request before its deadline");
+      }, overallTimeoutMs);
+      startTimer.unref?.();
+      overallTimer.unref?.();
+      options.signal?.addEventListener("abort", abort, { once: true });
+      start = () => this.events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
+    });
+    this.active = {
+      requestId: request.requestId,
+      requestCancellation,
+      terminal
+    };
+    start();
+    return delegation;
+  }
+  async cancelActiveAndWait(waitMs = 5000) {
+    const active = this.active;
+    if (!active)
+      return true;
+    active.requestCancellation();
+    return new Promise((resolve3) => {
+      let finished = false;
+      const finish = (confirmed) => {
+        if (finished)
+          return;
+        finished = true;
+        clearTimeout(timer);
+        resolve3(confirmed);
+      };
+      const timer = setTimeout(() => finish(false), waitMs);
+      active.terminal.then(() => finish(true));
+    });
+  }
+}
+
+// src/preflight.ts
+function sourceMatches(resource, selector) {
+  const source = `${resource.sourceInfo?.source ?? ""}
+${resource.sourceInfo?.path ?? ""}`;
+  return source.toLowerCase().includes(selector.toLowerCase());
+}
+function preflightStep(step, inventory) {
+  const errors = [];
+  const toolNames = new Set(inventory.tools.map((tool) => tool.name));
+  const subagentTool = inventory.tools.find((tool) => tool.name === "subagent" && sourceMatches(tool, "pi-subagents"));
+  if (step.subagent && !subagentTool) {
+    errors.push('pi-subagents is required, but its "subagent" tool is not installed or detectable');
+  }
+  for (const tool of step.requires.tools) {
+    if (!toolNames.has(tool)) {
+      errors.push(`required tool "${tool}" is not installed`);
+    }
+  }
+  if (step.permissions.mcp.length > 0 && !toolNames.has("mcp")) {
+    errors.push('MCP selectors are configured, but the "mcp" proxy tool is not installed');
+  }
+  const extensionResources = [...inventory.tools, ...inventory.commands];
+  if (step.gate?.provider === "plannotator" && !step.requires.extensions.includes("plannotator") && !extensionResources.some((resource) => sourceMatches(resource, "plannotator"))) {
+    errors.push("Plannotator is required by this gate, but its extension is not installed or detectable");
+  }
+  for (const extension of step.requires.extensions) {
+    if (!extensionResources.some((resource) => sourceMatches(resource, extension))) {
+      errors.push(`required extension "${extension}" is not detectable`);
+    }
+  }
+  for (const skill of step.requires.skills) {
+    if (!inventory.skills.has(skill)) {
+      errors.push(`required skill "${skill}" is not loaded`);
+    }
+  }
+  return errors;
+}
+
+// src/prompt.ts
+function formatList(values) {
+  return values.length > 0 ? values.join(", ") : "(none)";
+}
+function currentStepHandoff(run) {
+  const incoming = run.stepHandoff ?? "";
+  if (!incoming || incoming === run.lastSummary)
+    return run.lastSummary;
+  if (!run.lastSummary)
+    return incoming;
+  return [
+    "Incoming approved or previous-step handoff:",
+    incoming,
+    "",
+    "Latest paused attempt:",
+    run.lastSummary
+  ].join(`
+`);
+}
+function renderTemplate(template, values) {
+  return template.replace(/\{\{([^{}]+)\}\}/g, (_match, rawName) => {
+    const name = rawName.trim();
+    return values[name] ?? "";
+  });
+}
+function templateValues(workflow, run, step) {
+  return {
+    "workflow.input": run.input,
+    "workflow.id": workflow.definition.id,
+    "run.id": run.runId,
+    "step.id": run.currentStepId,
+    "step.title": step.title,
+    "last.summary": currentStepHandoff(run),
+    "gate.feedback": run.gateFeedback
+  };
+}
+function buildStepTask(workflow, run, execution, policyEnvelope) {
+  const step = workflow.definition.steps[run.currentStepId];
+  if (!step)
+    throw new Error(`unknown workflow step "${run.currentStepId}"`);
+  const prompt = renderTemplate(workflow.prompts[run.currentStepId] ?? "", templateValues(workflow, run, step));
+  const outcomes = allowedOutcomes(workflow, run);
+  const allowedOutcomeSet = new Set(outcomes);
+  const transitionLines = Object.entries(step.transitions).filter(([outcome]) => allowedOutcomeSet.has(outcome)).map(([outcome, target]) => `- ${outcome}: ${target}`).join(`
+`);
+  const gateLine = step.gate ? `- ${step.gate.submitOutcome}: submit the artifact to ${step.gate.provider}; include the full artifact argument` : "";
+  const delegated = execution === "delegated";
+  return [
+    ...policyEnvelope ? [policyEnvelope, ""] : [],
+    `# ${delegated ? "Delegated" : "Main-agent"} declarative workflow step`,
+    "",
+    `Workflow: ${workflow.definition.id}`,
+    `Run: ${run.runId}`,
+    `Step: ${run.currentStepId} (${step.title})`,
+    "",
+    "## Step instructions",
+    "",
+    prompt,
+    "",
+    `## Enforced ${delegated ? "child" : "step"} resources`,
+    "",
+    `Pi tools: ${formatList(step.permissions.tools)}`,
+    `MCP selectors: ${formatList(step.permissions.mcp)}`,
+    `Extension selectors: ${formatList(step.permissions.extensions)}`,
+    `Skills: ${formatList(step.permissions.skills)}`,
+    `Bash policy: ${step.permissions.bash.mode}`,
+    "",
+    `Use only the listed skills for this step. Tool calls are enforced ${delegated ? "inside this child process" : "by the workflow harness"}.`,
+    "",
+    "## Completion contract",
+    "",
+    `Call \`workflow_complete_step\` exactly once, after all work for this ${delegated ? "delegated" : "main-agent"} step is complete.`,
+    `Valid outcomes: ${outcomes.join(", ")}`,
+    transitionLines,
+    gateLine,
+    "",
+    "Put a concise handoff in `summary`. Do not call the completion tool alongside other tool calls. If the workflow definition or environment is wrong, use an outcome that transitions to `$pause`."
+  ].join(`
+`);
+}
+function buildDelegatedStepTask(workflow, run, policyEnvelope) {
+  return buildStepTask(workflow, run, "delegated", policyEnvelope);
+}
+function buildMainStepTask(workflow, run) {
+  return buildStepTask(workflow, run, "main");
+}
+function buildMainWorkflowNotice(workflow, run) {
+  const step = workflow.definition.steps[run.currentStepId];
+  if (!step)
+    throw new Error(`unknown workflow step "${run.currentStepId}"`);
+  if (!step.subagent) {
+    return [
+      "# Active main-agent workflow",
+      "",
+      `Workflow "${workflow.definition.id}" is running step "${run.currentStepId}" (${step.title}) in this session.`,
+      "Perform only the active workflow step with its allowed resources.",
+      "Call `workflow_complete_step` exactly once when finished.",
+      "Use `/workflow-pause` to halt and repair the workflow before resuming."
+    ].join(`
+`);
+  }
+  return [
+    "# Active subagent workflow",
+    "",
+    `Workflow "${workflow.definition.id}" is running step "${run.currentStepId}" (${step.title}) in a separate pi-subagents child process.`,
+    "Do not perform the workflow step in this main session.",
+    "Use `/workflow-status` to inspect it or `/workflow-pause` to cancel the child and repair the workflow before resuming."
+  ].join(`
+`);
+}
+
+// src/policy/approved-commands.ts
+import { basename as basename3 } from "node:path";
+
+// src/policy/bash.ts
+import { basename as basename2 } from "node:path";
+var UNQUOTED_SHELL_META = new Set([
+  ";",
+  "&",
+  "|",
+  "<",
+  ">",
+  `
+`,
+  "\r",
+  "`",
+  "$",
+  "(",
+  ")",
+  "{",
+  "}",
+  "#",
+  "\x00"
+]);
+var PATHNAME_EXPANSION = new Set(["*", "?", "[", "]", "~"]);
+var WRAPPER_COMMANDS = new Set([
+  "bash",
+  "builtin",
+  "command",
+  "env",
+  "exec",
+  "fish",
+  "sh",
+  "time",
+  "xargs",
+  "zsh"
+]);
+var READ_ONLY_EXECUTABLES = new Set([
+  "grep",
+  "head",
+  "ls",
+  "pwd",
+  "rg",
+  "stat",
+  "tail",
+  "wc"
+]);
+var READ_ONLY_GIT_SUBCOMMANDS = new Set([
+  "diff",
+  "grep",
+  "log",
+  "ls-files",
+  "rev-parse",
+  "show",
+  "status"
+]);
+var DANGEROUS_GIT_OPTIONS = [
+  "--config-env",
+  "--exec",
+  "--ext-diff",
+  "--open-files-in-pager",
+  "--output",
+  "--textconv"
+];
+var DANGEROUS_GIT_SHORT_OPTIONS = [
+  { subcommand: "grep", option: "-O" }
+];
+var HOSTED_API_MUTATION_OPTIONS = [
+  "--field",
+  "--form",
+  "--input",
+  "--method",
+  "--raw-field",
+  "-F",
+  "-X",
+  "-f"
+];
+function reject(reason) {
+  return { allowed: false, reason };
+}
+function tokenizeRestrictedCommand(command) {
+  if (!command.trim())
+    return { error: "empty Bash command" };
+  const tokens = [];
+  let token = "";
+  let quote;
+  let escaping = false;
+  let tokenStarted = false;
+  for (const character of command) {
+    if (quote === "'") {
+      if (character === `
+` || character === "\r" || character === "\x00") {
+        return { error: "multiline and null characters are not allowed" };
+      }
+      if (character === "'") {
+        quote = undefined;
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (quote === '"') {
+      if (character === `
+` || character === "\r" || character === "\x00") {
+        return { error: "multiline and null characters are not allowed" };
+      }
+      if (character === '"') {
+        quote = undefined;
+      } else if (character === "$" || character === "`" || character === "\\") {
+        return {
+          error: "substitutions and escapes are not allowed inside double quotes"
+        };
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (escaping) {
+      if (character === `
+` || character === "\r" || character === "\x00") {
+        return { error: "multiline and null characters are not allowed" };
+      }
+      token += character;
+      escaping = false;
+      tokenStarted = true;
+      continue;
+    }
+    if (character === "\\") {
+      escaping = true;
+      tokenStarted = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) {
+        quote = undefined;
+      } else {
+        token += character;
+      }
+      tokenStarted = true;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      tokenStarted = true;
+      continue;
+    }
+    if (UNQUOTED_SHELL_META.has(character)) {
+      return {
+        error: "shell operators, substitutions, expansions, and comments are not allowed"
+      };
+    }
+    if (PATHNAME_EXPANSION.has(character)) {
+      return {
+        error: "unquoted pathname and tilde expansion are not allowed"
+      };
+    }
+    if (/\s/.test(character)) {
+      if (tokenStarted) {
+        tokens.push(token);
+        token = "";
+        tokenStarted = false;
+      }
+      continue;
+    }
+    token += character;
+    tokenStarted = true;
+  }
+  if (escaping)
+    return { error: "trailing Bash escape is not allowed" };
+  if (quote)
+    return { error: "unterminated Bash quote" };
+  if (tokenStarted)
+    tokens.push(token);
+  if (tokens.length === 0)
+    return { error: "empty Bash command" };
+  return { tokens };
+}
+function parseRestrictedGitCommand(tokens) {
+  let index = 1;
+  while (index < tokens.length) {
+    const token = tokens[index];
+    if (token === "-C") {
+      if (!tokens[index + 1])
+        return;
+      index += 2;
+      continue;
+    }
+    if (token === "--no-pager") {
+      index += 1;
+      continue;
+    }
+    if (!token || token.startsWith("-"))
+      return;
+    return { subcommand: token, subcommandIndex: index };
+  }
+  return;
+}
+function matchesRule(tokens, rule) {
+  if (tokens[0] !== rule.executable)
+    return false;
+  return rule.argsPrefix.every((expected, index) => tokens[index + 1] === expected);
+}
+function hasOption(tokens, option) {
+  return tokens.some((token) => token === option || token.startsWith(`${option}=`));
+}
+function authorizeReadOnly(tokens) {
+  const executable = tokens[0] ?? "";
+  if (READ_ONLY_EXECUTABLES.has(executable)) {
+    if (executable === "rg" && (hasOption(tokens, "--pre") || hasOption(tokens, "--pre-glob"))) {
+      return reject("rg preprocessors are not allowed in read-only mode");
+    }
+    return { allowed: true, tokens: [...tokens] };
+  }
+  if (executable !== "git") {
+    return reject(`"${executable}" is not in the read-only Bash preset`);
+  }
+  const gitCommand = parseRestrictedGitCommand(tokens);
+  if (!gitCommand || !READ_ONLY_GIT_SUBCOMMANDS.has(gitCommand.subcommand)) {
+    return reject(`git subcommand "${gitCommand?.subcommand ?? ""}" is not read-only`);
+  }
+  const dangerousOption = DANGEROUS_GIT_OPTIONS.find((option) => hasOption(tokens, option));
+  if (dangerousOption) {
+    return reject(`git option "${dangerousOption}" is not allowed in read-only mode`);
+  }
+  const dangerousShortOption = DANGEROUS_GIT_SHORT_OPTIONS.find(({ subcommand: matchedSubcommand, option }) => gitCommand.subcommand === matchedSubcommand && tokens.slice(gitCommand.subcommandIndex + 1).some((token) => token === option || token.startsWith(option)));
+  if (dangerousShortOption) {
+    return reject(`git option "${dangerousShortOption.option}" is not allowed in read-only mode`);
+  }
+  return { allowed: true, tokens: [...tokens] };
+}
+function usesReadOnlyPreset(tokens) {
+  const executable = tokens[0] ?? "";
+  return READ_ONLY_EXECUTABLES.has(executable) || executable === "git" && READ_ONLY_GIT_SUBCOMMANDS.has(parseRestrictedGitCommand(tokens)?.subcommand ?? "");
+}
+function authorizeHostedApiRead(tokens) {
+  const executable = basename2(tokens[0] ?? "");
+  if (executable !== "gh" && executable !== "glab" || tokens[1] !== "api") {
+    return { allowed: true, tokens: [...tokens] };
+  }
+  const mutationOption = HOSTED_API_MUTATION_OPTIONS.find((option) => tokens.slice(2).some((token) => token === option || token.startsWith(`${option}=`) || option.length === 2 && token.startsWith(option)));
+  if (mutationOption) {
+    return reject(`${executable} api option "${mutationOption}" is not allowed by a static read-only rule`);
+  }
+  return { allowed: true, tokens: [...tokens] };
+}
+function authorizeBash(command, permission, approvedCommands = []) {
+  if ((permission.approvedSources?.length ?? 0) > 0 && approvedCommands.includes(command)) {
+    return { allowed: true };
+  }
+  if (permission.mode === "unrestricted") {
+    return { allowed: true };
+  }
+  if (permission.mode === "deny") {
+    return reject("Bash is disabled for this workflow step");
+  }
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens)
+    return reject(parsed.error ?? "invalid Bash command");
+  const executable = parsed.tokens[0] ?? "";
+  if (WRAPPER_COMMANDS.has(basename2(executable))) {
+    return reject(`shell wrapper "${executable}" is not allowed in restricted mode`);
+  }
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(executable)) {
+    return reject("environment assignments are not allowed in restricted mode");
+  }
+  if (permission.mode === "read-only") {
+    return authorizeReadOnly(parsed.tokens);
+  }
+  const rule = permission.allow.find((candidate) => matchesRule(parsed.tokens ?? [], candidate));
+  if (!rule) {
+    return reject(`command does not match this step's Bash allow-list`);
+  }
+  if (usesReadOnlyPreset(parsed.tokens)) {
+    return authorizeReadOnly(parsed.tokens);
+  }
+  return authorizeHostedApiRead(parsed.tokens);
+}
+
+// src/policy/approved-commands.ts
+var SHELL_WRAPPERS = new Set([
+  "bash",
+  "env",
+  "exec",
+  "fish",
+  "sh",
+  "xargs",
+  "zsh"
+]);
+var REMOTE_EXECUTABLES = new Set(["curl", "scp", "ssh", "rsync", "wget"]);
+var FORBIDDEN_LONG_PUSH_OPTIONS = [
+  "--force",
+  "--force-if-includes",
+  "--force-with-lease",
+  "--all",
+  "--delete",
+  "--mirror",
+  "--prune",
+  "--tags"
+];
+var PUBLISH_EXECUTABLES = new Set(["bun", "cargo", "npm", "pnpm", "yarn"]);
+var LOCAL_VERIFICATION_GIT_SUBCOMMANDS = new Set([
+  "add",
+  "branch",
+  "commit",
+  "diff",
+  "grep",
+  "log",
+  "ls-files",
+  "rev-parse",
+  "show",
+  "status",
+  "worktree"
+]);
+function hasDestructivePushShortOption(token) {
+  return token.startsWith("-") && !token.startsWith("--") && (token.slice(1).includes("f") || token.slice(1).includes("d"));
+}
+function hasForbiddenLongPushOption(token) {
+  if (!token.startsWith("--") || token === "--")
+    return false;
+  const optionName = token.split("=", 1)[0] ?? token;
+  return FORBIDDEN_LONG_PUSH_OPTIONS.some((option) => option.startsWith(optionName));
+}
+function hasEmptyPushRefspecSide(token) {
+  const separator = token.indexOf(":");
+  return separator >= 0 && (separator === 0 || separator === token.length - 1);
+}
+function isObject4(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseJsonDocuments(text) {
+  const documents = [];
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      documents.push(JSON.parse(trimmed));
+    } catch {}
+  }
+  const fences = /```(?:json)?[ \t]*\r?\n([\s\S]*?)```/gi;
+  for (const match of text.matchAll(fences)) {
+    const candidate = match[1]?.trim();
+    if (!candidate)
+      continue;
+    try {
+      documents.push(JSON.parse(candidate));
+    } catch {}
+  }
+  return documents;
+}
+function verificationCommands(value, role) {
+  if (!isObject4(value) || !Array.isArray(value.repositories))
+    return [];
+  const commands = [];
+  for (const repository of value.repositories) {
+    if (!isObject4(repository) || !Array.isArray(repository[role]))
+      continue;
+    for (const check of repository[role]) {
+      if (isObject4(check) && typeof check.command === "string") {
+        commands.push(check.command);
+      }
+    }
+  }
+  return commands;
+}
+function remoteActionCommands(value) {
+  if (!isObject4(value) || !Array.isArray(value.actions))
+    return [];
+  const commands = [];
+  for (const action of value.actions) {
+    if (isObject4(action) && action.toolName === "bash" && isObject4(action.input) && typeof action.input.command === "string") {
+      commands.push(action.input.command);
+    }
+  }
+  return commands;
+}
+function containsPublishOperation(tokens) {
+  return tokens.slice(1).some((token) => token.length >= 3 && "publish".startsWith(token));
+}
+function safeVerificationCommand(command) {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens)
+    return false;
+  const executable = basename3(parsed.tokens[0] ?? "");
+  if (SHELL_WRAPPERS.has(executable) || REMOTE_EXECUTABLES.has(executable)) {
+    return false;
+  }
+  const subcommand = executable === "git" ? parseRestrictedGitCommand(parsed.tokens)?.subcommand : parsed.tokens[1];
+  if (executable === "git" && (!subcommand || !LOCAL_VERIFICATION_GIT_SUBCOMMANDS.has(subcommand))) {
+    return false;
+  }
+  if (executable === "gh" || executable === "glab")
+    return false;
+  if (PUBLISH_EXECUTABLES.has(executable) && containsPublishOperation(parsed.tokens)) {
+    return false;
+  }
+  if (executable === "docker" && parsed.tokens.slice(1).includes("push")) {
+    return false;
+  }
+  return true;
+}
+function safeRemoteActionCommand(command) {
+  const parsed = tokenizeRestrictedCommand(command);
+  if (!parsed.tokens)
+    return false;
+  const executable = parsed.tokens[0];
+  const subcommand = executable === "git" ? parseRestrictedGitCommand(parsed.tokens)?.subcommand : parsed.tokens[1];
+  if (executable === "gh" || executable === "glab") {
+    if (subcommand !== "api")
+      return false;
+    return !parsed.tokens.slice(2).some((token, index, apiTokens) => {
+      const upper = token.toUpperCase();
+      return upper === "--METHOD=DELETE" || upper === "-XDELETE" || (upper === "--METHOD" || upper === "-X") && apiTokens[index + 1]?.toUpperCase() === "DELETE";
+    });
+  }
+  if (executable !== "git" || subcommand !== "push")
+    return false;
+  return !parsed.tokens.slice(1).some((token) => hasForbiddenLongPushOption(token) || token.startsWith("+") || hasEmptyPushRefspecSide(token) || hasDestructivePushShortOption(token));
+}
+function extractApprovedBashCommands(artifact, sources) {
+  if (!artifact.trim() || sources.length === 0)
+    return [];
+  const commands = [];
+  for (const document of parseJsonDocuments(artifact)) {
+    for (const source of sources) {
+      if (source === "verification-worker") {
+        commands.push(...verificationCommands(document, "worker").filter(safeVerificationCommand));
+      } else if (source === "verification-reviewer") {
+        commands.push(...verificationCommands(document, "reviewer").filter(safeVerificationCommand));
+      } else {
+        commands.push(...remoteActionCommands(document).filter(safeRemoteActionCommand));
+      }
+    }
+  }
+  return [...new Set(commands)];
+}
+
+// src/policy/completion-batch.ts
+function toolCalls(message) {
+  if (message === null || typeof message !== "object")
+    return [];
+  const candidate = message;
+  if (candidate.role !== "assistant" || !Array.isArray(candidate.content))
+    return [];
+  return candidate.content.filter((item) => item !== null && typeof item === "object" && item.type === "toolCall" && typeof item.id === "string" && typeof item.name === "string");
+}
+function invalidCompletionCallIds(message, completionTool) {
+  const calls = toolCalls(message);
+  if (calls.length === 1 && calls[0]?.name === completionTool)
+    return new Set;
+  return new Set(calls.filter((call) => call.name === completionTool).map((call) => call.id));
+}
+
+// src/policy/immutable-input.ts
+function freezeToolInput(input) {
+  const seen = new WeakSet;
+  const freeze = (value) => {
+    if (value === null || typeof value !== "object" || seen.has(value))
+      return;
+    seen.add(value);
+    for (const child of Object.values(value))
+      freeze(child);
+    Object.freeze(value);
+  };
+  freeze(input);
+  return input;
+}
+
+// src/policy/tools.ts
+function reject2(reason) {
+  return { allowed: false, reason };
+}
+function sourceText(tool) {
+  return `${tool.sourceInfo?.source ?? ""}
+${tool.sourceInfo?.path ?? ""}`.toLowerCase();
+}
+function isMcpAdapterTool(tool) {
+  return sourceText(tool).includes("pi-mcp-adapter");
+}
+function matchesExtensionSelector(tool, selector) {
+  const source = tool.sourceInfo?.source;
+  if (source === "builtin" || source === "sdk")
+    return false;
+  return sourceText(tool).includes(selector.toLowerCase());
+}
+function resolveActiveTools(inventory, step, completionToolName) {
+  const exact = new Set(step.permissions.tools);
+  const selected = inventory.filter((tool) => tool.name === completionToolName || exact.has(tool.name) || tool.name === "mcp" && step.permissions.mcp.length > 0 || !isMcpAdapterTool(tool) && step.permissions.extensions.some((selector) => matchesExtensionSelector(tool, selector))).map((tool) => tool.name);
+  return [...new Set(selected)];
+}
+function selectorAllows(selectors, server, tool) {
+  return selectors.some((selector) => {
+    const separator = selector.indexOf("/");
+    if (separator === -1)
+      return selector === server;
+    return selector.slice(0, separator) === server && selector.slice(separator + 1) === tool;
+  });
+}
+function authorizeMcpProxy(input, selectors) {
+  if (selectors.length === 0) {
+    return reject2("MCP access is disabled for this workflow step");
+  }
+  const unsupportedModes = [
+    "action",
+    "connect",
+    "describe",
+    "search",
+    "regex",
+    "includeSchemas"
+  ].filter((field) => input[field] !== undefined);
+  if (unsupportedModes.length > 0) {
+    return reject2(`MCP proxy mode "${unsupportedModes[0]}" is disabled; use an explicit server and tool`);
+  }
+  if (typeof input.server !== "string" || !input.server.trim()) {
+    return reject2("MCP proxy calls must name an explicit server");
+  }
+  if (typeof input.tool !== "string" || !input.tool.trim()) {
+    return reject2("MCP proxy calls must name an explicit tool");
+  }
+  const server = input.server.trim();
+  const tool = input.tool.trim();
+  if (!selectorAllows(selectors, server, tool)) {
+    return reject2(`MCP tool "${server}/${tool}" is not allowed for this workflow step`);
+  }
+  return { allowed: true };
+}
+function authorizeToolCall(toolName, input, step, inventory, approvedBashCommands = []) {
+  const tool = inventory.find((candidate) => candidate.name === toolName);
+  const allowedByName = step.permissions.tools.includes(toolName);
+  const allowedByExtension = tool !== undefined && !isMcpAdapterTool(tool) && step.permissions.extensions.some((selector) => matchesExtensionSelector(tool, selector));
+  if (toolName === "mcp") {
+    return authorizeMcpProxy(input, step.permissions.mcp);
+  }
+  if (!allowedByName && !allowedByExtension) {
+    return reject2(`tool "${toolName}" is not allowed for this workflow step`);
+  }
+  if (toolName === "bash") {
+    const command = input.command;
+    if (typeof command !== "string")
+      return reject2("Bash call is missing command text");
+    const result = authorizeBash(command, step.permissions.bash, approvedBashCommands);
+    return result.allowed ? { allowed: true } : reject2(result.reason ?? "Bash command is not allowed");
+  }
+  return { allowed: true };
+}
+
+// src/runtime/completion-tool.ts
+import { Type } from "typebox";
+var WORKFLOW_COMPLETION_TOOL = "workflow_complete_step";
+var WORKFLOW_COMPLETION_PARAMETERS = Type.Object({
+  outcome: Type.String({
+    description: "One exact outcome allowed by the active workflow step"
+  }),
+  summary: Type.String({
+    description: "Concise checkpoint and handoff for the next workflow step",
+    maxLength: 50000
+  }),
+  artifact: Type.Optional(Type.String({
+    description: "Full artifact required when submitting to a review gate",
+    maxLength: 200000
+  }))
+}, { additionalProperties: false });
+
+// src/runtime/main-step-runtime.ts
+class MainStepRuntime {
+  pi;
+  active;
+  pendingResult;
+  invalidCompletionCalls = new Set;
+  suspended = false;
+  constructor(pi) {
+    this.pi = pi;
+    this.registerLifecycle();
+    this.registerPolicy();
+    this.registerCompletionTool();
+  }
+  get activeStepId() {
+    return this.active?.stepId;
+  }
+  activate(execution) {
+    if (this.active) {
+      throw new Error(`main workflow step "${this.active.stepId}" is still active`);
+    }
+    this.suspended = false;
+    this.active = execution;
+    this.pendingResult = undefined;
+    this.invalidCompletionCalls.clear();
+    this.pi.setActiveTools(resolveActiveTools(this.pi.getAllTools(), execution.step, WORKFLOW_COMPLETION_TOOL));
+  }
+  deactivate() {
+    const wasActive = this.active !== undefined;
+    this.active = undefined;
+    this.pendingResult = undefined;
+    this.invalidCompletionCalls.clear();
+    return wasActive;
+  }
+  suspend() {
+    const wasActive = this.deactivate();
+    if (wasActive) {
+      this.suspended = true;
+      this.pi.setActiveTools([]);
+    }
+    return wasActive;
+  }
+  release() {
+    this.suspended = false;
+  }
+  registerLifecycle() {
+    const reset = () => {
+      this.suspended = false;
+      this.deactivate();
+      this.pi.setActiveTools(this.pi.getActiveTools().filter((tool) => tool !== WORKFLOW_COMPLETION_TOOL));
+    };
+    this.pi.on("session_start", reset);
+    this.pi.on("session_tree", reset);
+    this.pi.on("session_shutdown", () => {
+      this.suspended = false;
+      this.deactivate();
+    });
+    this.pi.on("agent_settled", (_event, context) => {
+      const active = this.active;
+      if (!active)
+        return;
+      const result = this.pendingResult;
+      this.active = undefined;
+      this.pendingResult = undefined;
+      this.invalidCompletionCalls.clear();
+      return active.onSettled(result, context);
+    });
+  }
+  registerPolicy() {
+    this.pi.on("turn_start", () => {
+      this.invalidCompletionCalls.clear();
+    });
+    this.pi.on("message_end", (event) => {
+      if (!this.active)
+        return;
+      const invalid = invalidCompletionCallIds(event.message, WORKFLOW_COMPLETION_TOOL);
+      if (invalid.size > 0 || event.message.role === "assistant") {
+        this.invalidCompletionCalls = invalid;
+      }
+    });
+    this.pi.on("tool_call", (event) => {
+      if (this.suspended) {
+        return {
+          block: true,
+          reason: "Main-agent workflow step is suspended"
+        };
+      }
+      if (!this.active) {
+        if (event.toolName === WORKFLOW_COMPLETION_TOOL) {
+          return {
+            block: true,
+            reason: "No main-agent workflow step is active"
+          };
+        }
+        return;
+      }
+      if (this.invalidCompletionCalls.has(event.toolCallId)) {
+        return {
+          block: true,
+          reason: `${WORKFLOW_COMPLETION_TOOL} must be the only tool call in its message`
+        };
+      }
+      if (event.toolName === WORKFLOW_COMPLETION_TOOL) {
+        freezeToolInput(event.input);
+        return;
+      }
+      const authorization = authorizeToolCall(event.toolName, event.input, this.active.step, this.pi.getAllTools(), this.active.approvedBashCommands);
+      if (!authorization.allowed) {
+        return {
+          block: true,
+          reason: authorization.reason ?? "Tool blocked by main workflow policy"
+        };
+      }
+      freezeToolInput(event.input);
+    });
+  }
+  registerCompletionTool() {
+    this.pi.registerTool({
+      name: WORKFLOW_COMPLETION_TOOL,
+      label: "Complete Workflow Step",
+      description: "Return one validated result from an active workflow step",
+      promptSnippet: "Complete the active workflow step",
+      promptGuidelines: [
+        "Call workflow_complete_step alone after all active workflow-step work is complete."
+      ],
+      parameters: WORKFLOW_COMPLETION_PARAMETERS,
+      executionMode: "sequential",
+      execute: async (_toolCallId, params) => {
+        if (!this.active) {
+          throw new Error("No main-agent workflow step is active");
+        }
+        if (this.pendingResult) {
+          throw new Error("Main-agent workflow step already produced a result");
+        }
+        const result = parseWorkflowStepResult({
+          version: 1,
+          policyDigest: this.active.policyDigest,
+          outcome: params.outcome,
+          summary: params.summary,
+          ...params.artifact !== undefined ? { artifact: params.artifact } : {}
+        }, this.active);
+        this.pendingResult = result;
+        this.pi.setActiveTools([]);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Captured workflow step outcome "${result.outcome}".`
+            }
+          ],
+          details: {
+            workflowId: this.active.workflowId,
+            runId: this.active.runId,
+            stepId: this.active.stepId,
+            outcome: result.outcome
+          },
+          terminate: true
+        };
+      }
+    });
+  }
+}
+
+// src/runtime/serial-task-queue.ts
+class SerialTaskQueue {
+  tail = Promise.resolve();
+  run(task) {
+    const result = this.tail.then(task, task);
+    this.tail = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  }
+}
+
+// src/workflow-list.ts
+function escapeMarkdownTableCell(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll("|", "\\|").replace(/\r\n|\r|\n/g, " ");
+}
+function formatWorkflowList(workflows) {
+  return [
+    "| Workflow | Command | Description |",
+    "| --- | --- | --- |",
+    ...workflows.map((workflow) => `| \`${workflow.id}\` | \`/${workflow.command}\` | ${escapeMarkdownTableCell(workflow.description)} |`)
+  ].join(`
+`);
+}
+
+// src/workflow-status.ts
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi
+} from "@earendil-works/pi-tui";
+var REFRESH_INTERVAL_MS = 1000;
+var WIDE_LAYOUT_MIN_COLUMNS = 92;
+var MAX_PATH_ROWS = 16;
+function formatWorkflowStatusText(snapshot) {
+  const { run } = snapshot;
+  const lines = [
+    `Workflow: ${run.workflowId}`,
+    `Run: ${run.runId}`,
+    `Status: ${run.status}`,
+    `Step: ${run.currentStepId}`,
+    `Completed steps: ${run.history.length}`
+  ];
+  if (run.pendingGate?.reviewId) {
+    lines.push(`Review: ${run.pendingGate.reviewId}`);
+  }
+  if (snapshot.execution?.kind === "subagent") {
+    lines.push(`Subagent: ${snapshot.execution.agent} (${snapshot.execution.requestId})`, `Progress: ${snapshot.execution.progress}`);
+  } else if (snapshot.execution?.kind === "main") {
+    lines.push("Execution: main agent");
+  }
+  if (run.pauseReason)
+    lines.push(`Reason: ${run.pauseReason}`);
+  return lines.join(`
+`);
+}
+async function showWorkflowStatus(ctx, getSnapshot) {
+  await ctx.ui.custom((tui, theme, _keybindings, done) => {
+    const view = new WorkflowStatusView(getSnapshot, tui, theme, done);
+    view.start();
+    return view;
+  });
+}
+
+class WorkflowStatusView {
+  getSnapshot;
+  tui;
+  theme;
+  done;
+  timer;
+  closed = false;
+  constructor(getSnapshot, tui, theme, done) {
+    this.getSnapshot = getSnapshot;
+    this.tui = tui;
+    this.theme = theme;
+    this.done = done;
+  }
+  start() {
+    this.timer = setInterval(() => this.tui.requestRender(), REFRESH_INTERVAL_MS);
+    this.timer.unref?.();
+  }
+  dispose() {
+    if (this.timer)
+      clearInterval(this.timer);
+    this.timer = undefined;
+  }
+  invalidate() {}
+  handleInput(data) {
+    if (data === "q" || data === "Q" || matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || matchesKey(data, "ctrl+d")) {
+      this.close();
+    }
+  }
+  render(width) {
+    const viewportWidth = Math.max(1, Math.floor(width || 1));
+    const snapshot = this.getSnapshot();
+    if (viewportWidth < 12) {
+      const label = snapshot ? `${statusGlyph(this.theme, snapshot.run.status)} ${snapshot.run.workflowId} ${statusLabel(snapshot.run.status)}` : "No workflow";
+      return [truncateToWidth(label, viewportWidth, "…", true)];
+    }
+    const contentWidth = viewportWidth - 2;
+    const lines = snapshot ? renderBoard(this.theme, snapshot, contentWidth) : renderEmptyBoard(this.theme, contentWidth);
+    return lines.map((line) => padAnsi(truncateToWidth(line, contentWidth, "…"), viewportWidth));
+  }
+  close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.dispose();
+    this.done();
+    this.tui.requestRender(true);
+  }
+}
+function renderBoard(theme, snapshot, width) {
+  const header = boxed(theme, "✦ Workflow Status", width, renderHeaderLines(theme, snapshot, width - 4), "borderAccent");
+  let body;
+  if (width >= WIDE_LAYOUT_MIN_COLUMNS) {
+    const gap = 2;
+    const summaryWidth = Math.min(42, Math.max(36, Math.floor(width * 0.36)));
+    const pathWidth = width - summaryWidth - gap;
+    const summary = boxed(theme, "Run Summary", summaryWidth, renderSummaryLines(theme, snapshot, summaryWidth - 4));
+    const path = boxed(theme, "Execution Path", pathWidth, renderPathLines(theme, snapshot, pathWidth - 4), "borderAccent");
+    body = joinPanels(summary, summaryWidth, path, pathWidth, gap);
+  } else {
+    body = [
+      ...boxed(theme, "Run Summary", width, renderSummaryLines(theme, snapshot, width - 4)),
+      "",
+      ...boxed(theme, "Execution Path", width, renderPathLines(theme, snapshot, width - 4), "borderAccent")
+    ];
+  }
+  return [
+    ...header,
+    "",
+    ...body,
+    "",
+    theme.fg("dim", "q / Esc close · live refresh")
+  ];
+}
+function renderEmptyBoard(theme, width) {
+  return [
+    ...boxed(theme, "✦ Workflow Status", width, [theme.fg("muted", "No workflow checkpoint in this session")], "borderAccent"),
+    "",
+    theme.fg("dim", "q / Esc close")
+  ];
+}
+function renderHeaderLines(theme, snapshot, width) {
+  const { run } = snapshot;
+  const workflowName = inline(run.workflowId);
+  const status = statusBadge(theme, run.status);
+  const completed = theme.fg("success", `${run.history.length} completed attempt${run.history.length === 1 ? "" : "s"}`);
+  const firstLine = [
+    statusGlyph(theme, run.status),
+    theme.bold(workflowName),
+    status,
+    theme.fg("muted", "·"),
+    completed
+  ].join(" ");
+  const currentTitle = stepTitle(snapshot.workflow, run.currentStepId);
+  const visit = Math.max(1, run.visits[run.currentStepId] ?? 1);
+  const elapsed = formatElapsed(elapsedMs(snapshot));
+  const secondLine = [
+    theme.fg("muted", "step"),
+    theme.fg("text", formatStepName(currentTitle, run.currentStepId)),
+    theme.fg("muted", `· visit ${visit} · elapsed ${elapsed}`)
+  ].join(" ");
+  return [
+    truncateToWidth(firstLine, width),
+    truncateToWidth(secondLine, width)
+  ];
+}
+function renderSummaryLines(theme, snapshot, width) {
+  const { run, workflow } = snapshot;
+  const lines = [
+    ...keyValueLines(theme, "workflow", run.workflowId, width),
+    ...keyValueLines(theme, "run", run.runId, width),
+    ...keyValueLines(theme, "status", statusLabel(run.status), width, statusColor(run.status)),
+    ...keyValueLines(theme, "current", formatStepName(stepTitle(workflow, run.currentStepId), run.currentStepId), width),
+    ...keyValueLines(theme, "visit", String(Math.max(1, run.visits[run.currentStepId] ?? 1)), width),
+    ...keyValueLines(theme, "started", formatTimestamp(run.startedAt), width),
+    ...keyValueLines(theme, "updated", `${formatTimestamp(run.updatedAt)} · ${formatElapsed(elapsedMs(snapshot))}`, width)
+  ];
+  const execution = formatExecution(snapshot.execution);
+  if (execution) {
+    lines.push(...keyValueLines(theme, "execution", execution, width, "accent"));
+  }
+  if (run.pendingGate) {
+    const review = run.pendingGate.reviewId ? `${run.pendingGate.provider} · ${run.pendingGate.reviewId}` : `${run.pendingGate.provider} · opening`;
+    lines.push(...keyValueLines(theme, "review", review, width, "warning"));
+  }
+  if (!workflow) {
+    lines.push(...keyValueLines(theme, "config", "workflow definition is not loaded", width, "warning"));
+  } else if (workflow.digest !== run.workflowDigest) {
+    lines.push(...keyValueLines(theme, "config", "definition changed since this checkpoint", width, "warning"));
+  }
+  if (run.pauseReason) {
+    lines.push(...keyValueLines(theme, "reason", run.pauseReason, width, run.status === "aborted" ? "error" : "warning"));
+  }
+  return lines;
+}
+function renderPathLines(theme, snapshot, width) {
+  const entries = buildPathEntries(snapshot);
+  if (entries.length === 0) {
+    return [theme.fg("muted", "No step attempts recorded")];
+  }
+  const hidden = Math.max(0, entries.length - MAX_PATH_ROWS);
+  const visible = entries.slice(hidden);
+  const lines = hidden > 0 ? [
+    theme.fg("dim", `… ${hidden} earlier attempt${hidden === 1 ? "" : "s"}`)
+  ] : [];
+  for (const entry of visible) {
+    const visit = entry.visit > 1 ? theme.fg("dim", ` · visit ${entry.visit}`) : "";
+    const left = `${statusGlyph(theme, entry.status)} ${theme.fg(entry.current ? "text" : "muted", entry.title)}${visit}`;
+    const right = entry.outcome ? `${statusLabel(entry.status)} · ${inline(entry.outcome)}` : statusLabel(entry.status);
+    const row = joinColumns(left, theme.fg(statusColor(entry.status), right), width, Math.max(12, Math.floor(width * 0.58)));
+    lines.push(entry.current ? theme.bg("selectedBg", padAnsi(row, width)) : truncateToWidth(row, width));
+  }
+  return lines;
+}
+function buildPathEntries(snapshot) {
+  const { run, workflow } = snapshot;
+  const visits = new Map;
+  const entries = run.history.map((entry) => {
+    const visit = (visits.get(entry.stepId) ?? 0) + 1;
+    visits.set(entry.stepId, visit);
+    return historyPathEntry(workflow, entry, visit);
+  });
+  if (run.status !== "completed") {
+    entries.push({
+      stepId: run.currentStepId,
+      title: stepTitle(workflow, run.currentStepId),
+      status: run.status,
+      visit: Math.max(visits.get(run.currentStepId) ?? 0, run.visits[run.currentStepId] ?? 1),
+      current: true
+    });
+  } else if (entries.length === 0 || entries.at(-1)?.stepId !== run.currentStepId) {
+    entries.push({
+      stepId: run.currentStepId,
+      title: stepTitle(workflow, run.currentStepId),
+      status: "completed",
+      visit: Math.max(1, run.visits[run.currentStepId] ?? 1),
+      current: true
+    });
+  }
+  return entries;
+}
+function historyPathEntry(workflow, entry, visit) {
+  return {
+    stepId: entry.stepId,
+    title: stepTitle(workflow, entry.stepId),
+    status: "completed",
+    visit,
+    outcome: entry.outcome,
+    current: false
+  };
+}
+function keyValueLines(theme, label, rawValue, width, valueColor = "text") {
+  const safeWidth = Math.max(1, width);
+  const labelWidth = Math.min(10, Math.max(7, label.length + 1));
+  const valueWidth = Math.max(1, safeWidth - labelWidth);
+  const value = theme.fg(valueColor, inline(rawValue));
+  const wrapped = wrapTextWithAnsi(value, valueWidth);
+  const prefix = theme.fg("muted", label.padEnd(labelWidth));
+  return (wrapped.length > 0 ? wrapped : [""]).map((line, index) => index === 0 ? `${prefix}${line}` : `${" ".repeat(labelWidth)}${line}`);
+}
+function boxed(theme, title, width, content, color = "borderMuted") {
+  const safeWidth = Math.max(8, Math.floor(width));
+  const bodyWidth = Math.max(1, safeWidth - 4);
+  const topLabel = `╭─ ${title} `;
+  const top = `${topLabel}${"─".repeat(Math.max(0, safeWidth - visibleWidth(topLabel) - 1))}╮`;
+  const bottom = `╰${"─".repeat(Math.max(0, safeWidth - 2))}╯`;
+  const body = content.length > 0 ? content : [""];
+  return [
+    theme.fg(color, top),
+    ...body.map((line) => `${theme.fg(color, "│")} ${padAnsi(truncateToWidth(line, bodyWidth), bodyWidth)} ${theme.fg(color, "│")}`),
+    theme.fg(color, bottom)
+  ];
+}
+function joinPanels(left, leftWidth, right, rightWidth, gap) {
+  const height = Math.max(left.length, right.length);
+  return Array.from({ length: height }, (_, index) => {
+    const leftLine = padAnsi(left[index] ?? "", leftWidth);
+    const rightLine = padAnsi(right[index] ?? "", rightWidth);
+    return `${leftLine}${" ".repeat(gap)}${rightLine}`;
+  });
+}
+function joinColumns(left, right, width, leftWidth) {
+  const safeLeftWidth = Math.max(1, Math.min(leftWidth, width - 2));
+  const rightWidth = Math.max(1, width - safeLeftWidth - 1);
+  return `${padAnsi(truncateToWidth(left, safeLeftWidth), safeLeftWidth)} ${truncateToWidth(right, rightWidth)}`;
+}
+function padAnsi(value, width) {
+  const visible = visibleWidth(value);
+  if (visible >= width)
+    return value;
+  return `${value}${" ".repeat(width - visible)}`;
+}
+function statusGlyph(theme, status) {
+  if (status === "completed")
+    return theme.fg("success", "✓");
+  if (status === "running")
+    return theme.fg("accent", "↻");
+  if (status === "paused" || status === "awaiting-gate") {
+    return theme.fg("warning", "◆");
+  }
+  if (status === "aborted")
+    return theme.fg("error", "✕");
+  return theme.fg("dim", "•");
+}
+function statusColor(status) {
+  if (status === "completed")
+    return "success";
+  if (status === "running")
+    return "accent";
+  if (status === "paused" || status === "awaiting-gate")
+    return "warning";
+  if (status === "aborted")
+    return "error";
+  return "dim";
+}
+function statusLabel(status) {
+  return status === "awaiting-gate" ? "AWAITING REVIEW" : status.toUpperCase().replaceAll("-", " ");
+}
+function statusBadge(theme, status) {
+  return theme.fg(statusColor(status), theme.bold(`[${statusLabel(status)}]`));
+}
+function stepTitle(workflow, stepId) {
+  return inline(workflow?.definition.steps[stepId]?.title ?? stepId);
+}
+function formatStepName(title, stepId) {
+  const safeStepId = inline(stepId);
+  return title === safeStepId ? title : `${title} (${safeStepId})`;
+}
+function formatExecution(execution) {
+  if (!execution)
+    return;
+  if (execution.kind === "main")
+    return "main agent";
+  return `${execution.agent} · ${execution.progress} · ${execution.requestId}`;
+}
+function inline(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function elapsedMs(snapshot) {
+  const { run } = snapshot;
+  const end = run.status === "running" || run.status === "awaiting-gate" ? snapshot.now : run.updatedAt;
+  return Math.max(0, end - run.startedAt);
+}
+function formatElapsed(milliseconds) {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1000));
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor(totalSeconds % 86400 / 3600);
+  const minutes = Math.floor(totalSeconds % 3600 / 60);
+  const seconds = totalSeconds % 60;
+  if (days > 0)
+    return `${days}d ${hours}h`;
+  if (hours > 0)
+    return `${hours}h ${minutes}m`;
+  if (minutes > 0)
+    return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+function formatTimestamp(milliseconds) {
+  const value = new Date(milliseconds);
+  if (!Number.isFinite(value.getTime()))
+    return "unknown";
+  const year = value.getFullYear();
+  const month = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  const hours = String(value.getHours()).padStart(2, "0");
+  const minutes = String(value.getMinutes()).padStart(2, "0");
+  const seconds = String(value.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+// src/harness.ts
+var STATE_ENTRY_TYPE = "pi-workflows-state-v1";
+var STATUS_KEY = "pi-workflows";
+function emptyCatalog() {
+  return {
+    workflows: new Map,
+    settings: DEFAULT_SETTINGS,
+    diagnostics: [],
+    userDirectory: ""
+  };
+}
+function formatDiagnostics(catalog) {
+  const shown = catalog.diagnostics.slice(0, 3).map((item) => `${item.path}: ${item.message}`);
+  const remaining = catalog.diagnostics.length - shown.length;
+  return [
+    ...shown,
+    ...remaining > 0 ? [`${remaining} more diagnostic(s)`] : []
+  ].join(`
+`);
+}
+
+class WorkflowHarness {
+  pi;
+  subagents;
+  mainSteps;
+  catalog = emptyCatalog();
+  run;
+  latestContext;
+  availableSkills = new Set;
+  sessionActive = false;
+  sessionEpoch = 0;
+  activeDelegation;
+  activePromptReview;
+  registeredWorkflowCommands = new Set;
+  catalogLoadSequence = 0;
+  mutationQueue = new SerialTaskQueue;
+  constructor(pi) {
+    this.pi = pi;
+    this.subagents = new SubagentDelegationClient(pi.events);
+    this.mainSteps = new MainStepRuntime(pi);
+    registerHarnessCommands(pi, this);
+    this.registerLifecycle();
+    this.registerPolicy();
+    this.registerPlannotatorResults();
+  }
+  workflowIds() {
+    return [...this.catalog.workflows.keys()].sort();
+  }
+  async list(ctx) {
+    const workflows = [...this.catalog.workflows.values()].sort((left, right) => left.definition.id.localeCompare(right.definition.id));
+    if (workflows.length === 0) {
+      ctx.ui.notify(`No workflows loaded from ${this.catalog.userDirectory}`, this.catalog.diagnostics.length > 0 ? "warning" : "info");
+      return;
+    }
+    this.pi.sendMessage({
+      customType: "workflow-list",
+      content: formatWorkflowList(workflows.map((workflow) => workflow.definition)),
+      display: true
+    });
+  }
+  start(workflowId, input, ctx) {
+    return this.enqueueMutation(ctx, (sessionEpoch) => this.startNow(workflowId, input, ctx, sessionEpoch));
+  }
+  async startNow(workflowId, input, ctx, sessionEpoch) {
+    if (this.activeDelegation) {
+      ctx.ui.notify(`Cannot start a workflow while subagent "${this.activeDelegation.agent}" is still cancelling`, "warning");
+      return;
+    }
+    if (this.run && this.run.status !== "completed" && this.run.status !== "aborted") {
+      ctx.ui.notify(`Workflow "${this.run.workflowId}" is ${this.run.status}; resume or abort it first`, "warning");
+      return;
+    }
+    if (!ctx.isIdle()) {
+      ctx.abort();
+      await ctx.waitForIdle();
+    }
+    if (!this.sessionActive || this.sessionEpoch !== sessionEpoch) {
+      ctx.ui.notify("Workflow start was superseded by a session change", "warning");
+      return;
+    }
+    this.captureSkills(ctx.getSystemPromptOptions().skills);
+    if (!await this.reloadCatalog(ctx, false)) {
+      ctx.ui.notify("Workflow start was superseded by a newer configuration load", "warning");
+      return;
+    }
+    if (!this.sessionActive || this.sessionEpoch !== sessionEpoch) {
+      ctx.ui.notify("Workflow start was superseded by a session change", "warning");
+      return;
+    }
+    const workflow = this.catalog.workflows.get(workflowId);
+    if (!workflow) {
+      ctx.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
+      return;
+    }
+    const preflightErrors = this.preflight(workflow, workflow.definition.start);
+    if (preflightErrors.length > 0) {
+      ctx.ui.notify(`Cannot start workflow:
+${preflightErrors.join(`
+`)}`, "error");
+      return;
+    }
+    const baselineTools = this.pi.getActiveTools();
+    this.run = createRun(workflow, input.trim(), baselineTools, randomUUID(), Date.now());
+    this.persist();
+    this.isolateMainSessionTools();
+    this.updateStatus();
+    this.launchCurrentStep(workflow);
+  }
+  pause(reason, ctx) {
+    return this.enqueueMutation(ctx, () => this.pauseNow(reason, ctx));
+  }
+  async pauseNow(reason, ctx) {
+    if (!this.run || this.run.status === "completed" || this.run.status === "aborted") {
+      ctx.ui.notify("No active workflow to pause", "warning");
+      return;
+    }
+    if (this.run.status === "paused") {
+      ctx.ui.notify(`Workflow is already paused${this.run.pauseReason ? `: ${this.run.pauseReason}` : ""}`, "info");
+      return;
+    }
+    this.cancelPromptReview();
+    const mainSuspended = this.mainSteps.suspend();
+    const cancellationConfirmed = await this.cancelActiveDelegation("Workflow paused by user");
+    if (!ctx.isIdle()) {
+      ctx.abort();
+      if (mainSuspended)
+        await ctx.waitForIdle();
+    }
+    this.run = pauseRun(this.run, reason, Date.now());
+    this.persist();
+    if (cancellationConfirmed) {
+      this.restoreBaselineTools();
+    } else {
+      this.isolateMainSessionTools();
+    }
+    this.updateStatus();
+    ctx.ui.notify(cancellationConfirmed ? `Paused "${this.run.workflowId}" at step "${this.run.currentStepId}". Fix the issue, then run /workflow-resume.` : `Pause recorded at "${this.run.currentStepId}", but child cancellation is not confirmed. Main tools remain isolated until it exits.`, cancellationConfirmed ? "info" : "warning");
+  }
+  resume(ctx) {
+    return this.enqueueMutation(ctx, () => this.resumeNow(ctx));
+  }
+  async resumeNow(ctx) {
+    if (!this.run || this.run.status !== "paused") {
+      ctx.ui.notify("No paused workflow to resume", "warning");
+      return;
+    }
+    if (this.activeDelegation) {
+      ctx.ui.notify(`Cannot resume while subagent "${this.activeDelegation.agent}" is still cancelling`, "warning");
+      return;
+    }
+    const checkpoint = captureResumeCheckpoint(this.run, this.sessionEpoch);
+    if (!ctx.isIdle()) {
+      ctx.abort();
+      await ctx.waitForIdle();
+    }
+    if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+      ctx.ui.notify("Resume was superseded by another workflow or session change", "warning");
+      return;
+    }
+    this.captureSkills(ctx.getSystemPromptOptions().skills);
+    await this.reloadCatalog(ctx, false);
+    if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+      ctx.ui.notify("Resume was superseded by another workflow or session change", "warning");
+      return;
+    }
+    let workflow = this.catalog.workflows.get(this.run.workflowId);
+    if (!workflow) {
+      ctx.ui.notify(`Workflow "${this.run.workflowId}" is no longer loaded; restore it or abort`, "error");
+      return;
+    }
+    const reconciled = reconcileRun(this.run, workflow, Date.now());
+    if (!reconciled.run) {
+      ctx.ui.notify(reconciled.error ?? "Cannot reconcile workflow configuration", "error");
+      return;
+    }
+    let resumed = reconciled.run;
+    if (resumed.pendingGate?.provider === "plannotator" && !resumed.pendingGate.reviewId) {
+      resumed = failGate(resumed, "Gate submission was interrupted before a review id was recorded; submit it again", Date.now());
+    }
+    if (resumed.pendingGate?.provider === "plannotator" && resumed.pendingGate.reviewId && !resumed.pendingGate.resolution) {
+      const requestedReviewId = resumed.pendingGate.reviewId;
+      const gateStep = workflow.definition.steps[resumed.pendingGate.stepId];
+      const statusResponse = await requestPlannotatorReviewStatus(this.pi.events, `${resumed.runId}:review-status:${randomUUID()}`, requestedReviewId, gateStep?.gate?.provider === "plannotator" ? gateStep.gate.timeoutMs : 5000);
+      if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+        ctx.ui.notify("Resume was superseded by another workflow or session change", "warning");
+        return;
+      }
+      workflow = this.catalog.workflows.get(this.run.workflowId);
+      if (!workflow) {
+        ctx.ui.notify(`Workflow "${this.run.workflowId}" is no longer loaded; restore it or abort`, "error");
+        return;
+      }
+      const latest = reconcileRun(this.run, workflow, Date.now());
+      if (!latest.run) {
+        ctx.ui.notify(latest.error ?? "Cannot reconcile workflow configuration", "error");
+        return;
+      }
+      resumed = latest.run;
+      if (!resumed.pendingGate?.resolution && resumed.pendingGate?.reviewId === requestedReviewId && statusResponse.status !== "handled") {
+        ctx.ui.notify(statusResponse.error ?? "Cannot query the pending Plannotator review", "error");
+        return;
+      }
+      if (!resumed.pendingGate?.resolution && resumed.pendingGate?.reviewId === requestedReviewId && statusResponse.status === "handled" && statusResponse.result.status === "completed") {
+        resumed = storeGateResolution(resumed, {
+          approved: statusResponse.result.approved,
+          feedback: statusResponse.result.feedback,
+          resolvedAt: Date.now()
+        }, Date.now());
+      } else if (!resumed.pendingGate?.resolution && resumed.pendingGate?.reviewId === requestedReviewId && statusResponse.status === "handled" && statusResponse.result.status === "missing") {
+        resumed = failGate(resumed, "Plannotator no longer has the pending review; submit it again", Date.now());
+      }
+    }
+    const storedResolution = resumed.pendingGate?.resolution;
+    if (storedResolution) {
+      try {
+        resumed = resolveGate(workflow, resumed, storedResolution, Date.now());
+      } catch (error) {
+        ctx.ui.notify(`Cannot apply stored gate result: ${error instanceof Error ? error.message : String(error)}`, "error");
+        return;
+      }
+    } else {
+      resumed = resumeRun(resumed, Date.now());
+    }
+    this.run = resumed;
+    if (this.run.status === "awaiting-gate") {
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+      if (this.run.pendingGate?.provider === "prompt") {
+        this.launchPromptReview(workflow, this.run, ctx);
+        ctx.ui.notify("Workflow resumed with built-in review open", "info");
+        return;
+      }
+      ctx.ui.notify(`Workflow resumed and is waiting for review ${this.run.pendingGate?.reviewId ?? ""}`.trim(), "info");
+      return;
+    }
+    if (this.run.status !== "running") {
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+      ctx.ui.notify(`Workflow is now ${this.run.status}`, "info");
+      return;
+    }
+    const preflightErrors = this.preflight(workflow, this.run.currentStepId);
+    if (preflightErrors.length > 0) {
+      this.run = pauseRun(this.run, `Step preflight failed: ${preflightErrors.join("; ")}`, Date.now());
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+      ctx.ui.notify(`Cannot resume workflow:
+${preflightErrors.join(`
+`)}`, "error");
+      return;
+    }
+    this.persist();
+    this.isolateMainSessionTools();
+    this.updateStatus();
+    this.launchCurrentStep(workflow);
+  }
+  abort(reason, ctx) {
+    return this.enqueueMutation(ctx, () => this.abortNow(reason, ctx));
+  }
+  async abortNow(reason, ctx) {
+    if (!this.run || this.run.status === "completed" || this.run.status === "aborted") {
+      ctx.ui.notify("No active workflow to abort", "warning");
+      return;
+    }
+    this.cancelPromptReview();
+    const mainSuspended = this.mainSteps.suspend();
+    const cancellationConfirmed = await this.cancelActiveDelegation("Workflow aborted by user");
+    if (!ctx.isIdle()) {
+      ctx.abort();
+      if (mainSuspended)
+        await ctx.waitForIdle();
+    }
+    this.run = abortRun(this.run, reason, Date.now());
+    this.persist();
+    if (cancellationConfirmed) {
+      this.restoreBaselineTools();
+    } else {
+      this.isolateMainSessionTools();
+    }
+    this.updateStatus();
+    ctx.ui.notify(cancellationConfirmed ? `Aborted workflow "${this.run.workflowId}"` : `Workflow "${this.run.workflowId}" is aborted, but its child has not confirmed cancellation; main tools remain isolated`, cancellationConfirmed ? "info" : "warning");
+  }
+  reload(ctx) {
+    return this.enqueueMutation(ctx, () => this.reloadNow(ctx));
+  }
+  async reloadNow(ctx) {
+    if (this.run && (this.run.status === "running" || this.run.status === "awaiting-gate")) {
+      ctx.ui.notify("Pause the workflow before reloading its configuration", "warning");
+      return;
+    }
+    this.captureSkills(ctx.getSystemPromptOptions().skills);
+    await this.reloadCatalog(ctx, true);
+  }
+  async status(ctx) {
+    const snapshot = this.workflowStatusSnapshot();
+    if (!snapshot) {
+      ctx.ui.notify("No workflow checkpoint in this session", "info");
+      return;
+    }
+    if (ctx.hasUI && ctx.mode === "tui") {
+      await showWorkflowStatus(ctx, () => this.workflowStatusSnapshot());
+      return;
+    }
+    ctx.ui.notify(formatWorkflowStatusText(snapshot), "info");
+  }
+  workflowStatusSnapshot() {
+    if (!this.run)
+      return;
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    let execution;
+    if (this.activeDelegation) {
+      execution = {
+        kind: "subagent",
+        agent: this.activeDelegation.agent,
+        requestId: this.activeDelegation.requestId,
+        progress: this.activeDelegation.progress ?? "starting"
+      };
+    } else if (this.mainSteps.activeStepId) {
+      execution = { kind: "main" };
+    }
+    return {
+      run: this.run,
+      now: Date.now(),
+      ...workflow ? { workflow } : {},
+      ...execution ? { execution } : {}
+    };
+  }
+  registerLifecycle() {
+    this.pi.on("session_start", async (_event, ctx) => {
+      this.sessionEpoch += 1;
+      this.sessionActive = false;
+      this.cancelPromptReview();
+      this.mainSteps.deactivate();
+      await this.cancelActiveDelegation("Pi session changed");
+      if (this.run)
+        this.restoreBaselineTools();
+      this.run = undefined;
+      this.latestContext = ctx;
+      if (!await this.reloadCatalog(ctx, false))
+        return;
+      this.restoreFromSession(ctx);
+      this.sessionActive = true;
+    });
+    this.pi.on("session_tree", async (_event, ctx) => {
+      this.sessionEpoch += 1;
+      this.sessionActive = false;
+      this.cancelPromptReview();
+      this.mainSteps.deactivate();
+      await this.cancelActiveDelegation("Pi session tree changed");
+      this.latestContext = ctx;
+      if (!await this.reloadCatalog(ctx, false))
+        return;
+      this.restoreFromSession(ctx);
+      this.sessionActive = true;
+    });
+    this.pi.on("session_shutdown", async () => {
+      this.sessionEpoch += 1;
+      this.sessionActive = false;
+      this.cancelPromptReview();
+      this.mainSteps.deactivate();
+      await this.cancelActiveDelegation("Pi session shut down");
+      if (this.run)
+        this.restoreBaselineTools();
+      this.run = undefined;
+      this.latestContext = undefined;
+    });
+  }
+  registerPolicy() {
+    this.pi.on("before_agent_start", (event, ctx) => {
+      this.latestContext = ctx;
+      this.captureSkills(event.systemPromptOptions.skills);
+      if (!this.run || this.run.status !== "running")
+        return;
+      const workflow = this.catalog.workflows.get(this.run.workflowId);
+      if (!workflow) {
+        this.run = pauseRun(this.run, "Workflow configuration disappeared; reload or restore it", Date.now());
+        this.persist();
+        this.restoreBaselineTools();
+        this.updateStatus();
+        return;
+      }
+      return {
+        systemPrompt: `${event.systemPrompt}
+
+${buildMainWorkflowNotice(workflow, this.run)}`
+      };
+    });
+  }
+  launchCurrentStep(workflow) {
+    const run = this.run;
+    if (!run || run.status !== "running" || this.activeDelegation || this.mainSteps.activeStepId) {
+      return;
+    }
+    const step = workflow.definition.steps[run.currentStepId];
+    if (!step) {
+      this.pauseForExecutionFailure("Workflow", `Step "${run.currentStepId}" is missing from the workflow`);
+      return;
+    }
+    const subagent = step.subagent;
+    if (!subagent) {
+      this.launchMainStep(workflow, run, step);
+      return;
+    }
+    const requestId = `${run.runId}:${run.currentStepId}:${randomUUID()}`;
+    const resultDirectory = mkdtempSync(join2(tmpdir2(), "pi-workflows-step-"));
+    const capabilityPath = join2(resultDirectory, "capability");
+    const capabilityToken = randomBytes(32).toString("hex");
+    const resultPath = join2(resultDirectory, "result.json");
+    writeFileSync(capabilityPath, capabilityToken, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    const approvedBashCommands = extractApprovedBashCommands(run.reviewedArtifact ?? "", step.permissions.bash.approvedSources ?? []);
+    const policyDigest = digest({
+      version: 1,
+      requestId,
+      agent: subagent.agent,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepDigest: run.currentStepDigest,
+      capabilityPath,
+      resultPath,
+      approvedBashCommands
+    });
+    const policy = {
+      version: 1,
+      requestId,
+      agent: subagent.agent,
+      workflowId: workflow.definition.id,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepTitle: step.title,
+      policyDigest,
+      capabilityPath,
+      capabilityToken,
+      resultPath,
+      permissions: structuredClone(step.permissions),
+      ...approvedBashCommands.length > 0 ? { approvedBashCommands } : {},
+      outcomes: allowedOutcomes(workflow, run),
+      summaryMaxChars: workflow.definition.summaryMaxChars,
+      ...step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}
+    };
+    const active = {
+      requestId,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepDigest: run.currentStepDigest,
+      sessionEpoch: this.sessionEpoch,
+      resultDirectory,
+      policy,
+      agent: subagent.agent
+    };
+    const request = {
+      version: 1,
+      requestId,
+      agent: subagent.agent,
+      task: buildDelegatedStepTask(workflow, run, encodeChildPolicy(policy)),
+      context: subagent.context,
+      cwd: this.latestContext?.cwd ?? process.cwd(),
+      timeoutMs: subagent.timeoutMs,
+      skill: step.permissions.skills.length > 0 ? [...step.permissions.skills] : false,
+      acceptance: {
+        level: "none",
+        reason: "Pi Workflows owns correlated step completion and human-review gates"
+      },
+      artifacts: subagent.artifacts,
+      ...subagent.model ? { model: subagent.model } : {},
+      ...subagent.turnBudget ? { turnBudget: structuredClone(subagent.turnBudget) } : {},
+      ...subagent.toolBudget ? { toolBudget: structuredClone(subagent.toolBudget) } : {}
+    };
+    this.activeDelegation = active;
+    this.updateStatus();
+    this.latestContext?.ui.notify(`Delegated "${run.currentStepId}" to subagent "${subagent.agent}"`, "info");
+    this.subagents.delegate(request, {
+      onUpdate: (update) => this.handleDelegationUpdate(active, update),
+      onLateTerminal: (response) => this.queueDelegationResponse(active, response)
+    }).then((response) => this.queueDelegationResponse(active, response), (error) => this.queueDelegationFailure(active, error instanceof Error ? error.message : String(error)));
+  }
+  launchMainStep(workflow, run, step) {
+    const approvedBashCommands = extractApprovedBashCommands(run.reviewedArtifact ?? "", step.permissions.bash.approvedSources ?? []);
+    const identity = {
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepDigest: run.currentStepDigest,
+      sessionEpoch: this.sessionEpoch
+    };
+    const policyDigest = digest({
+      version: 1,
+      execution: "main",
+      workflowId: workflow.definition.id,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepDigest: run.currentStepDigest,
+      permissions: step.permissions,
+      approvedBashCommands,
+      nonce: randomUUID()
+    });
+    const execution = {
+      workflowId: workflow.definition.id,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepDigest: run.currentStepDigest,
+      policyDigest,
+      step: structuredClone(step),
+      approvedBashCommands,
+      outcomes: allowedOutcomes(workflow, run),
+      summaryMaxChars: workflow.definition.summaryMaxChars,
+      ...step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {},
+      onSettled: (result, context) => this.queueMainStepResult(identity, result, context)
+    };
+    try {
+      this.mainSteps.activate(execution);
+      this.updateStatus();
+      this.latestContext?.ui.notify(`Started "${run.currentStepId}" in the main agent`, "info");
+      this.pi.sendUserMessage(buildMainStepTask(workflow, run), {
+        deliverAs: "followUp"
+      });
+    } catch (error) {
+      this.mainSteps.deactivate();
+      this.pauseForExecutionFailure("Main-agent step", error instanceof Error ? error.message : String(error));
+    }
+  }
+  queueMainStepResult(identity, result, context) {
+    return this.mutationQueue.run(() => this.finishMainStep(identity, result, context)).catch((error) => {
+      this.pauseForExecutionFailure("Main-agent step", error instanceof Error ? error.message : String(error));
+    });
+  }
+  async finishMainStep(identity, result, context) {
+    this.latestContext = context;
+    if (!this.sessionActive || this.sessionEpoch !== identity.sessionEpoch || !this.run || this.run.status !== "running" || this.run.runId !== identity.runId || this.run.currentStepId !== identity.stepId || this.run.currentStepDigest !== identity.stepDigest) {
+      return;
+    }
+    if (!result) {
+      throw new Error("agent settled without calling workflow_complete_step exactly once");
+    }
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    const step = workflow?.definition.steps[this.run.currentStepId];
+    if (!workflow || !step) {
+      throw new Error("Active workflow configuration is unavailable");
+    }
+    if (step.gate?.submitOutcome === result.outcome) {
+      await this.submitGate(workflow, this.run, result.outcome, result.artifact ?? "");
+      return;
+    }
+    this.run = advanceRun(workflow, this.run, result.outcome, result.summary, Date.now());
+    this.settleAfterTransition(workflow);
+  }
+  handleDelegationUpdate(active, update) {
+    if (this.activeDelegation !== active)
+      return;
+    const progress = [
+      update.currentTool ? `tool ${update.currentTool}` : undefined,
+      update.toolCount !== undefined ? `${update.toolCount} calls` : undefined,
+      update.tokens !== undefined ? `${update.tokens} tokens` : undefined
+    ].filter((part) => part !== undefined);
+    active.progress = progress.join(", ") || "running";
+    this.updateStatus();
+  }
+  queueDelegationResponse(active, response) {
+    this.mutationQueue.run(() => this.finishDelegation(active, response)).catch((error) => {
+      this.pauseForDelegationFailure(error instanceof Error ? error.message : String(error));
+    });
+  }
+  queueDelegationFailure(active, reason) {
+    this.mutationQueue.run(async () => {
+      if (this.activeDelegation !== active) {
+        await this.cleanupDelegation(active);
+        return;
+      }
+      if (this.subagents.activeRequestId === active.requestId) {
+        this.retainUnconfirmedDelegation(active, reason);
+        return;
+      }
+      this.activeDelegation = undefined;
+      await this.cleanupDelegation(active);
+      this.pauseForDelegationFailure(reason);
+    }).catch((error) => {
+      this.pauseForDelegationFailure(error instanceof Error ? error.message : String(error));
+    });
+  }
+  async finishDelegation(active, response) {
+    if (this.activeDelegation !== active) {
+      await this.cleanupDelegation(active);
+      return;
+    }
+    this.activeDelegation = undefined;
+    try {
+      if (!this.sessionActive || this.sessionEpoch !== active.sessionEpoch || !this.run || this.run.status !== "running" || this.run.runId !== active.runId || this.run.currentStepId !== active.stepId || this.run.currentStepDigest !== active.stepDigest) {
+        return;
+      }
+      if (response.status !== "completed") {
+        throw new Error(`Subagent "${active.agent}" ${response.status.replaceAll("_", " ")}${response.error ? `: ${response.error}` : ""}`);
+      }
+      const workflow = this.catalog.workflows.get(this.run.workflowId);
+      const step = workflow?.definition.steps[this.run.currentStepId];
+      if (!workflow || !step) {
+        throw new Error("Active workflow configuration is unavailable");
+      }
+      const requiredSkillWarning = step.requires.skills.length > 0 ? response.warnings?.find((warning) => /skill/i.test(warning)) : undefined;
+      if (requiredSkillWarning) {
+        throw new Error(`Subagent skill preflight failed: ${requiredSkillWarning}`);
+      }
+      const rawResult = JSON.parse(await readFile2(active.policy.resultPath, "utf8"));
+      const result = parseDelegatedStepResult(rawResult, active.policy);
+      if (step.gate?.submitOutcome === result.outcome) {
+        await this.submitGate(workflow, this.run, result.outcome, result.artifact ?? "");
+        return;
+      }
+      this.run = advanceRun(workflow, this.run, result.outcome, result.summary, Date.now());
+      this.settleAfterTransition(workflow);
+    } catch (error) {
+      this.pauseForDelegationFailure(error instanceof Error ? error.message : String(error));
+    } finally {
+      await this.cleanupDelegation(active);
+      if (active.cancelling)
+        this.releaseMainAfterCancellation(active);
+    }
+  }
+  async cancelActiveDelegation(reason) {
+    const active = this.activeDelegation;
+    if (!active)
+      return true;
+    active.cancelling = true;
+    active.progress = "cancelling";
+    this.updateStatus();
+    if (this.subagents.activeRequestId !== active.requestId) {
+      active.progress = "cancellation unconfirmed";
+      this.updateStatus();
+      this.latestContext?.ui.notify(`${reason}; the delegation channel already closed without a terminal response`, "warning");
+      return false;
+    }
+    const confirmed = await this.subagents.cancelActiveAndWait();
+    if (confirmed && this.activeDelegation === active) {
+      this.activeDelegation = undefined;
+      await this.cleanupDelegation(active);
+    } else if (!confirmed) {
+      this.latestContext?.ui.notify(`${reason}; waiting for subagent "${active.agent}" to confirm termination`, "warning");
+    }
+    return confirmed;
+  }
+  async cleanupDelegation(active) {
+    await rm(active.resultDirectory, { recursive: true, force: true });
+  }
+  pauseForDelegationFailure(reason) {
+    this.pauseForExecutionFailure("Subagent step", reason);
+  }
+  pauseForExecutionFailure(label, reason) {
+    if (!this.run || this.run.status !== "running")
+      return;
+    this.mainSteps.deactivate();
+    this.run = pauseRun(this.run, `${label} failed: ${reason}`, Date.now());
+    this.persist();
+    if (this.activeDelegation) {
+      this.isolateMainSessionTools();
+    } else {
+      this.restoreBaselineTools();
+    }
+    this.updateStatus();
+    this.latestContext?.ui.notify(`Workflow paused at "${this.run.currentStepId}": ${reason}`, "error");
+  }
+  retainUnconfirmedDelegation(active, reason) {
+    active.cancelling = true;
+    active.progress = "cancellation unconfirmed";
+    if (this.run?.status === "running") {
+      this.run = pauseRun(this.run, `Subagent step failed: ${reason}`, Date.now());
+      this.persist();
+    }
+    this.isolateMainSessionTools();
+    this.updateStatus();
+    this.latestContext?.ui.notify(`Workflow paused, but subagent "${active.agent}" has not confirmed termination. Main tools and resume remain blocked; restart Pi if no terminal response arrives.`, "error");
+  }
+  releaseMainAfterCancellation(active) {
+    if (this.activeDelegation === active)
+      this.activeDelegation = undefined;
+    if (!this.activeDelegation && this.run && this.run.status !== "running" && this.run.status !== "awaiting-gate") {
+      this.restoreBaselineTools();
+      this.updateStatus();
+      this.latestContext?.ui.notify(`Subagent "${active.agent}" has terminated; main tools are restored`, "info");
+    }
+  }
+  async submitGate(workflow, originalRun, outcome, artifact) {
+    const requestSessionEpoch = this.sessionEpoch;
+    const requestId = `${originalRun.runId}:${originalRun.currentStepId}:${randomUUID()}`;
+    const step = workflow.definition.steps[originalRun.currentStepId];
+    if (!step?.gate)
+      throw new Error("Current step has no gate");
+    this.run = beginGate(workflow, originalRun, outcome, artifact, requestId, Date.now());
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    if (step.gate.provider === "prompt") {
+      this.launchPromptReview(workflow, this.run, this.latestContext);
+      return;
+    }
+    const response = await requestPlannotatorReview(this.pi.events, requestId, artifact, `pi-workflows:${workflow.definition.id}:${originalRun.currentStepId}`, step.gate.timeoutMs);
+    if (!this.sessionActive || this.sessionEpoch !== requestSessionEpoch || !this.run || this.run.runId !== originalRun.runId || this.run.currentStepId !== originalRun.currentStepId || this.run.pendingGate?.requestId !== requestId || this.run.pendingGate.reviewId !== undefined) {
+      throw new Error("Gate request was superseded by a workflow state change");
+    }
+    if (this.run.status !== "awaiting-gate" && !(this.run.status === "paused" && this.run.pendingGate)) {
+      throw new Error("Gate request was superseded by a workflow state change");
+    }
+    if (response.status !== "handled") {
+      const reason = response.error ?? "Plannotator is unavailable";
+      const gateFailed = failGate(this.run, reason, Date.now());
+      this.run = this.run.status === "paused" ? pauseRun(gateFailed, reason, Date.now()) : gateFailed;
+      this.persist();
+      if (this.run.status === "running") {
+        this.isolateMainSessionTools();
+      } else {
+        this.restoreBaselineTools();
+      }
+      this.updateStatus();
+      throw new Error(reason);
+    }
+    this.run = attachGateReviewId(this.run, response.result.reviewId, Date.now());
+    this.persist();
+    this.updateStatus();
+    this.latestContext?.ui.notify(`Submitted "${originalRun.currentStepId}" for Plannotator review ${response.result.reviewId}`, "info");
+  }
+  launchPromptReview(workflow, run, context) {
+    const pendingGate = run.pendingGate;
+    if (!pendingGate || pendingGate.provider !== "prompt")
+      return;
+    if (!context?.hasUI) {
+      this.pausePromptGate(pendingGate.requestId, "Built-in review requires Pi TUI or RPC mode; resume there to continue");
+      return;
+    }
+    if (this.activePromptReview?.requestId === pendingGate.requestId)
+      return;
+    this.cancelPromptReview();
+    const active = {
+      requestId: pendingGate.requestId,
+      runId: run.runId,
+      stepId: pendingGate.stepId,
+      sessionEpoch: this.sessionEpoch,
+      abortController: new AbortController
+    };
+    this.activePromptReview = active;
+    requestPromptGateReview(context.ui, `Review ${workflow.definition.id}:${pendingGate.stepId}`, pendingGate.artifact, active.abortController.signal).then((result) => this.queuePromptReviewResult(active, result), (error) => this.queuePromptReviewFailure(active, error instanceof Error ? error.message : String(error)));
+  }
+  queuePromptReviewResult(active, result) {
+    this.mutationQueue.run(() => this.finishPromptReview(active, result)).catch((error) => {
+      this.latestContext?.ui.notify(`Cannot apply built-in review: ${error instanceof Error ? error.message : String(error)}`, "error");
+    });
+  }
+  queuePromptReviewFailure(active, reason) {
+    this.mutationQueue.run(async () => {
+      if (this.activePromptReview !== active)
+        return;
+      this.activePromptReview = undefined;
+      this.pausePromptGate(active.requestId, `Built-in review failed: ${reason}`);
+    }).catch((error) => {
+      this.latestContext?.ui.notify(`Cannot pause failed built-in review: ${error instanceof Error ? error.message : String(error)}`, "error");
+    });
+  }
+  async finishPromptReview(active, result) {
+    if (this.activePromptReview !== active)
+      return;
+    this.activePromptReview = undefined;
+    if (!this.sessionActive || this.sessionEpoch !== active.sessionEpoch || !this.run || this.run.runId !== active.runId || this.run.currentStepId !== active.stepId || this.run.pendingGate?.provider !== "prompt" || this.run.pendingGate.requestId !== active.requestId) {
+      return;
+    }
+    if (result.status === "dismissed") {
+      this.pausePromptGate(active.requestId, "Built-in review was dismissed; resume to reopen it");
+      return;
+    }
+    const resolution = {
+      approved: result.approved,
+      feedback: result.feedback,
+      resolvedAt: Date.now()
+    };
+    if (this.run.status === "paused") {
+      this.run = storeGateResolution(this.run, resolution, Date.now());
+      this.persist();
+      this.latestContext?.ui.notify("Built-in review finished while paused. Run /workflow-resume to apply it.", "info");
+      return;
+    }
+    if (this.run.status !== "awaiting-gate")
+      return;
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    if (!workflow) {
+      this.pausePromptGate(active.requestId, "Built-in review finished, but workflow configuration is unavailable");
+      return;
+    }
+    try {
+      this.run = resolveGate(workflow, this.run, resolution, Date.now());
+      this.settleAfterTransition(workflow);
+    } catch (error) {
+      this.pausePromptGate(active.requestId, `Cannot apply built-in review: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  pausePromptGate(requestId, reason) {
+    if (!this.run || this.run.pendingGate?.provider !== "prompt" || this.run.pendingGate.requestId !== requestId) {
+      return;
+    }
+    if (this.run.status === "awaiting-gate") {
+      this.run = pauseRun(this.run, reason, Date.now());
+    }
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    this.latestContext?.ui.notify(`Workflow paused at "${this.run.currentStepId}": ${reason}`, "warning");
+  }
+  cancelPromptReview() {
+    const active = this.activePromptReview;
+    if (!active)
+      return;
+    this.activePromptReview = undefined;
+    active.abortController.abort();
+  }
+  registerPlannotatorResults() {
+    this.pi.events.on(PLANNOTATOR_RESULT_CHANNEL, (data) => {
+      this.mutationQueue.run(() => this.handlePlannotatorResult(data)).catch((error) => {
+        this.latestContext?.ui.notify(`Cannot apply Plannotator result: ${error instanceof Error ? error.message : String(error)}`, "error");
+      });
+    });
+  }
+  async handlePlannotatorResult(data) {
+    if (!this.sessionActive || this.run?.pendingGate?.provider !== "plannotator" || !this.run.pendingGate.reviewId) {
+      return;
+    }
+    const result = parsePlannotatorResult(data);
+    if (!result || result.reviewId !== this.run.pendingGate.reviewId)
+      return;
+    const resolution = {
+      approved: result.approved,
+      feedback: result.feedback,
+      resolvedAt: Date.now()
+    };
+    if (this.run.status === "paused") {
+      this.run = storeGateResolution(this.run, resolution, Date.now());
+      this.persist();
+      this.latestContext?.ui.notify(`Review ${result.reviewId} finished while paused. Run /workflow-resume to apply it.`, "info");
+      return;
+    }
+    if (this.run.status !== "awaiting-gate")
+      return;
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    if (!workflow) {
+      this.run = pauseRun(this.run, "Gate result arrived, but workflow configuration is unavailable", Date.now());
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+      return;
+    }
+    try {
+      this.run = resolveGate(workflow, this.run, resolution, Date.now());
+      this.settleAfterTransition(workflow);
+    } catch (error) {
+      this.run = pauseRun(this.run, `Cannot apply gate result: ${error instanceof Error ? error.message : String(error)}`, Date.now());
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+    }
+  }
+  settleAfterTransition(workflow) {
+    if (!this.run)
+      return;
+    if (this.run.status === "running") {
+      const preflightErrors = this.preflight(workflow, this.run.currentStepId);
+      if (preflightErrors.length > 0) {
+        this.run = pauseRun(this.run, `Step preflight failed: ${preflightErrors.join("; ")}`, Date.now());
+      }
+    }
+    this.persist();
+    if (this.run.status !== "running") {
+      this.restoreBaselineTools();
+      this.updateStatus();
+      if (this.run.status === "completed") {
+        this.latestContext?.ui.notify(`Workflow "${this.run.workflowId}" completed`, "info");
+      } else if (this.run.status === "paused") {
+        this.latestContext?.ui.notify(`Workflow paused: ${this.run.pauseReason ?? "manual action required"}`, "warning");
+      }
+      return;
+    }
+    this.isolateMainSessionTools();
+    this.updateStatus();
+    this.launchCurrentStep(workflow);
+  }
+  preflight(workflow, stepId) {
+    const step = workflow.definition.steps[stepId];
+    if (!step)
+      return [`step "${stepId}" does not exist`];
+    return preflightStep(step, {
+      tools: this.pi.getAllTools(),
+      commands: this.pi.getCommands(),
+      skills: this.availableSkills
+    });
+  }
+  isolateMainSessionTools() {
+    this.pi.setActiveTools([]);
+  }
+  restoreBaselineTools() {
+    this.mainSteps.release();
+    if (this.run) {
+      this.pi.setActiveTools(this.run.baselineTools);
+      return;
+    }
+    this.pi.setActiveTools(this.pi.getActiveTools());
+  }
+  captureSkills(skills) {
+    if (!skills)
+      return;
+    this.availableSkills = new Set(skills.map((skill) => skill.name));
+  }
+  enqueueMutation(ctx, operation) {
+    if (!this.sessionActive) {
+      ctx.ui.notify("The Pi session is still initializing", "warning");
+      return Promise.resolve();
+    }
+    const sessionEpoch = this.sessionEpoch;
+    return this.mutationQueue.run(async () => {
+      if (!this.sessionActive || this.sessionEpoch !== sessionEpoch) {
+        ctx.ui.notify("Workflow command was superseded by a session change", "warning");
+        return;
+      }
+      await operation(sessionEpoch);
+    });
+  }
+  persist() {
+    if (this.run) {
+      this.pi.appendEntry(STATE_ENTRY_TYPE, structuredClone(this.run));
+    }
+  }
+  restoreFromSession(ctx) {
+    this.latestContext = ctx;
+    const previousBaseline = this.run?.baselineTools;
+    const entries = ctx.sessionManager.getBranch();
+    const checkpoint = readLatestCheckpoint(entries, STATE_ENTRY_TYPE);
+    this.run = checkpoint.status === "valid" ? checkpoint.run : undefined;
+    if (checkpoint.status === "invalid") {
+      ctx.ui.notify("The newest workflow checkpoint is invalid or from an unsupported version; recovery stopped", "error");
+    }
+    if (this.run && (this.run.status === "running" || this.run.status === "awaiting-gate")) {
+      this.run = pauseRun(this.run, "Session was restored; inspect the checkpoint before resuming", Date.now());
+      this.persist();
+    }
+    if (!this.run && previousBaseline) {
+      this.pi.setActiveTools(previousBaseline);
+    } else {
+      this.restoreBaselineTools();
+    }
+    if (this.activeDelegation)
+      this.isolateMainSessionTools();
+    this.updateStatus();
+  }
+  async reloadCatalog(ctx, announce) {
+    const loadSequence = ++this.catalogLoadSequence;
+    const sessionEpoch = this.sessionEpoch;
+    const catalog = await loadCatalog({
+      cwd: ctx.cwd,
+      projectTrusted: ctx.isProjectTrusted()
+    });
+    if (loadSequence !== this.catalogLoadSequence || sessionEpoch !== this.sessionEpoch) {
+      return false;
+    }
+    this.latestContext = ctx;
+    const availableCommands = this.pi.getCommands();
+    for (const [workflowId, workflow] of catalog.workflows) {
+      const command = workflow.definition.command;
+      if (hasRuntimeCommandConflict(command, availableCommands, this.registeredWorkflowCommands)) {
+        catalog.workflows.delete(workflowId);
+        catalog.diagnostics.push({
+          level: "error",
+          path: workflow.sourcePath,
+          message: `command "/${command}" conflicts with another loaded Pi resource`
+        });
+      }
+    }
+    this.catalog = catalog;
+    for (const workflow of catalog.workflows.values()) {
+      this.pi.registerCommand(workflow.definition.command, {
+        description: workflow.definition.description,
+        handler: async (args, commandContext) => this.start(workflow.definition.id, args, commandContext)
+      });
+      this.registeredWorkflowCommands.add(workflow.definition.command);
+    }
+    if (announce) {
+      const diagnosticText = formatDiagnostics(this.catalog);
+      ctx.ui.notify(diagnosticText ? `Loaded ${this.catalog.workflows.size} workflow(s)
+${diagnosticText}` : `Loaded ${this.catalog.workflows.size} workflow(s)`, diagnosticText ? "warning" : "info");
+    } else if (this.catalog.diagnostics.some((item) => item.level === "error")) {
+      ctx.ui.notify(`Workflow configuration errors:
+${formatDiagnostics(this.catalog)}`, "warning");
+    }
+    return true;
+  }
+  updateStatus() {
+    if (!this.latestContext)
+      return;
+    if (!this.run) {
+      this.latestContext.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+    const delegation = this.activeDelegation ? `; ${this.activeDelegation.agent}: ${this.activeDelegation.progress ?? "starting"}` : this.mainSteps.activeStepId ? "; main agent: running" : "";
+    this.latestContext.ui.setStatus(STATUS_KEY, `${this.run.workflowId}: ${this.run.currentStepId} (${this.run.status}${delegation})`);
+  }
+}
+
+// src/integrations/subagents/child-runtime.ts
+import { randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+var CHILD_COMPLETION_TOOL = WORKFLOW_COMPLETION_TOOL;
+function policyStep(policy) {
+  return {
+    title: policy.stepTitle,
+    prompt: { inline: "Delegated workflow step" },
+    subagent: {
+      agent: policy.agent,
+      context: "fresh",
+      timeoutMs: 900000,
+      artifacts: false
+    },
+    permissions: policy.permissions,
+    requires: { tools: [], extensions: [], skills: [] },
+    transitions: {}
+  };
+}
+function childSystemPrompt(policy) {
+  return [
+    "# Pi Workflows delegated step",
+    "",
+    `Workflow: ${policy.workflowId}`,
+    `Run: ${policy.runId}`,
+    `Step: ${policy.stepId} (${policy.stepTitle})`,
+    "",
+    "The parent workflow harness owns orchestration and state transitions.",
+    "Perform only this delegated step. Its child-side tool policy is enforced.",
+    "When finished, call `workflow_complete_step` exactly once and as the only tool call in that message.",
+    `Valid outcomes: ${policy.outcomes.join(", ")}`,
+    `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...policy.gateSubmitOutcome ? [
+      `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`
+    ] : [],
+    "If the workflow definition or environment is wrong, choose an outcome that transitions to $pause."
+  ].join(`
+`);
+}
+function writeResult(policy, result) {
+  if (existsSync(policy.resultPath)) {
+    throw new Error("Delegated workflow step already produced a result");
+  }
+  const temporaryPath = `${policy.resultPath}.${randomUUID2()}.tmp`;
+  try {
+    writeFileSync2(temporaryPath, JSON.stringify(result), {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    renameSync(temporaryPath, policy.resultPath);
+  } catch (error) {
+    try {
+      unlinkSync(temporaryPath);
+    } catch {}
+    throw error;
+  }
+}
+function verifyCapability(policy, childAgent) {
+  if (!isSubagentRuntimeName(childAgent) || childAgent !== policy.agent) {
+    throw new Error("child agent does not match the delegated workflow policy");
+  }
+  let actual;
+  try {
+    actual = Buffer.from(readFileSync(policy.capabilityPath, "utf8"), "utf8");
+  } catch {
+    throw new Error("delegated workflow capability is missing");
+  }
+  const expected = Buffer.from(policy.capabilityToken, "utf8");
+  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+    throw new Error("delegated workflow capability is invalid");
+  }
+  unlinkSync(policy.capabilityPath);
+}
+function registerSubagentChildRuntime(pi, options = {}) {
+  let activePolicy;
+  let policyError;
+  let invalidCompletionCalls = new Set;
+  let effectiveTools = new Set;
+  let completionRegistered = false;
+  const childAgent = options.childAgent ?? process.env.PI_SUBAGENT_CHILD_AGENT?.trim();
+  const registerCompletionTool = () => {
+    if (completionRegistered)
+      return;
+    completionRegistered = true;
+    pi.registerTool({
+      name: CHILD_COMPLETION_TOOL,
+      label: "Complete Delegated Workflow Step",
+      description: "Return one validated result from a pi-workflows delegated child step",
+      promptSnippet: "Complete the delegated workflow step",
+      promptGuidelines: [
+        "Call workflow_complete_step alone after all delegated work is complete."
+      ],
+      parameters: WORKFLOW_COMPLETION_PARAMETERS,
+      executionMode: "sequential",
+      execute: async (_toolCallId, params) => {
+        if (!activePolicy) {
+          throw new Error("No delegated workflow policy is active");
+        }
+        if (policyError)
+          throw new Error(policyError);
+        const result = parseDelegatedStepResult({
+          version: 1,
+          policyDigest: activePolicy.policyDigest,
+          outcome: params.outcome,
+          summary: params.summary,
+          ...params.artifact !== undefined ? { artifact: params.artifact } : {}
+        }, activePolicy);
+        writeResult(activePolicy, result);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Captured workflow step outcome "${result.outcome}".`
+            }
+          ],
+          details: {
+            workflowId: activePolicy.workflowId,
+            runId: activePolicy.runId,
+            stepId: activePolicy.stepId,
+            outcome: result.outcome
+          },
+          terminate: true
+        };
+      }
+    });
+  };
+  pi.on("input", (event) => {
+    let extracted;
+    try {
+      extracted = extractChildPolicy(event.text);
+    } catch (error) {
+      policyError = error instanceof Error ? error.message : String(error);
+      pi.setActiveTools([]);
+      return {
+        action: "transform",
+        text: `Delegated workflow policy is invalid: ${policyError}`,
+        ...event.images ? { images: event.images } : {}
+      };
+    }
+    if (!extracted)
+      return;
+    if (activePolicy) {
+      policyError = "child received more than one workflow policy";
+      pi.setActiveTools([]);
+      return {
+        action: "transform",
+        text: `Delegated workflow policy is invalid: ${policyError}`,
+        ...event.images ? { images: event.images } : {}
+      };
+    }
+    try {
+      verifyCapability(extracted.policy, childAgent);
+      const profileTools = new Set(pi.getActiveTools());
+      activePolicy = extracted.policy;
+      policyError = undefined;
+      registerCompletionTool();
+      effectiveTools = new Set(resolveActiveTools(pi.getAllTools(), policyStep(activePolicy), CHILD_COMPLETION_TOOL).filter((toolName) => toolName === CHILD_COMPLETION_TOOL || profileTools.has(toolName)));
+    } catch (error) {
+      policyError = error instanceof Error ? error.message : String(error);
+      effectiveTools.clear();
+      pi.setActiveTools([]);
+      return {
+        action: "transform",
+        text: `Delegated workflow policy is invalid: ${policyError}`,
+        ...event.images ? { images: event.images } : {}
+      };
+    }
+    pi.setActiveTools([...effectiveTools]);
+    return {
+      action: "transform",
+      text: extracted.task,
+      ...event.images ? { images: event.images } : {}
+    };
+  });
+  pi.on("before_agent_start", (event) => {
+    if (!activePolicy) {
+      if (policyError)
+        pi.setActiveTools([]);
+      return;
+    }
+    return {
+      systemPrompt: `${event.systemPrompt}
+
+${childSystemPrompt(activePolicy)}`
+    };
+  });
+  pi.on("turn_start", () => {
+    invalidCompletionCalls.clear();
+  });
+  pi.on("message_end", (event) => {
+    if (!activePolicy)
+      return;
+    const invalid = invalidCompletionCallIds(event.message, CHILD_COMPLETION_TOOL);
+    if (invalid.size > 0 || event.message.role === "assistant") {
+      invalidCompletionCalls = invalid;
+    }
+  });
+  pi.on("tool_call", (event) => {
+    if (!activePolicy) {
+      if (!policyError)
+        return;
+      return {
+        block: true,
+        reason: policyError
+      };
+    }
+    if (invalidCompletionCalls.has(event.toolCallId)) {
+      return {
+        block: true,
+        reason: `${CHILD_COMPLETION_TOOL} must be the only tool call in its message`
+      };
+    }
+    if (event.toolName === CHILD_COMPLETION_TOOL) {
+      if (policyError) {
+        return {
+          block: true,
+          reason: policyError
+        };
+      }
+      freezeToolInput(event.input);
+      return;
+    }
+    if (!effectiveTools.has(event.toolName)) {
+      return {
+        block: true,
+        reason: `tool "${event.toolName}" is not enabled by subagent "${childAgent ?? "unknown"}"`
+      };
+    }
+    const authorization = authorizeToolCall(event.toolName, event.input, policyStep(activePolicy), pi.getAllTools(), activePolicy.approvedBashCommands ?? []);
+    if (!authorization.allowed) {
+      return {
+        block: true,
+        reason: authorization.reason ?? "Tool blocked by workflow child policy"
+      };
+    }
+    freezeToolInput(event.input);
+  });
+}
+
+// src/index.ts
+function piWorkflowsExtension(pi) {
+  if (process.env.PI_SUBAGENT_CHILD === "1") {
+    const childAgent = process.env.PI_SUBAGENT_CHILD_AGENT?.trim();
+    if (isSubagentRuntimeName(childAgent)) {
+      registerSubagentChildRuntime(pi, { childAgent });
+    }
+    return;
+  }
+  new WorkflowHarness(pi);
+}
+export {
+  piWorkflowsExtension as default
+};