@yycholla/pi-dynamic-workflows 3.3.0

package/dist/effort-command.js

@@ -0,0 +1,68 @@
+/**
+ * Standing `/effort` opt-in (pi's answer to CC's ultracode): a session toggle that
+ * auto-arms a workflow for substantive interactive messages, with effort-tier
+ * guidance nudging fan-out breadth and the hard caps (tokenBudget / maxAgents) the
+ * model should set on the workflow tool call.
+ *
+ * Honest scope: the runtime cannot enforce "reviewer N / loop K" — those live in
+ * the script the model writes — so the tiers are guidance plus the model setting
+ * the real hard caps (tokenBudget/maxAgents are genuine runtime ceilings). The
+ * pre-flight ceiling-confirm dialog (roadmap P1-5 #4) is a downscope point: an
+ * `input` hook transforms synchronously and can't await a confirm, so it is left
+ * to a follow-up; `/effort` is explicit opt-in, which is the safety valve.
+ */
+export function createEffortState() {
+    return { level: "off" };
+}
+const HIGH_DIRECTIVE = "Effort: HIGH. Be thorough — use a few parallel reviewers/perspectives and an adversarial verify pass (see verify()/judgePanel()); set a moderate tokenBudget and maxAgents on the workflow tool call.";
+const ULTRA_DIRECTIVE = "Effort: ULTRA. Be exhaustive — fan out widely (more reviewers/judges, deeper loopUntilDry rounds, a completenessCheck at the end), and prefer the big tier for synthesis. This can spend a lot of tokens quickly, so set explicit caps you're comfortable paying for (a generous but bounded tokenBudget and a high maxAgents) on the workflow tool call rather than leaving them unbounded.";
+/** The extra directive appended to the forced-workflow prompt for an effort level. */
+export function effortDirective(level) {
+    if (level === "high")
+        return HIGH_DIRECTIVE;
+    if (level === "ultra")
+        return ULTRA_DIRECTIVE;
+    return undefined;
+}
+/**
+ * Whether a message should auto-arm under effort mode: a real interactive request,
+ * not a terse acknowledgement or a slash command. (hasTrigger handles the explicit
+ * "workflow(s)" keyword separately.)
+ */
+export function isSubstantive(text) {
+    const t = text.trim();
+    return t.length >= 16 && !t.startsWith("/");
+}
+export function registerEffortCommand(pi, state) {
+    pi.registerCommand("effort", {
+        description: "Standing workflow effort: off | high | ultra — auto-arms a workflow for substantive messages",
+        async handler(args, _ctx) {
+            const arg = args.trim().toLowerCase();
+            const say = (content) => pi.sendMessage({ customType: "effort", content, display: true });
+            if (arg === "off" || arg === "high" || arg === "ultra") {
+                state.level = arg;
+                await say(arg === "off"
+                    ? "Effort off — messages are no longer auto-armed as workflows."
+                    : `Effort ${arg} — substantive messages now auto-arm a workflow (${arg === "ultra" ? "exhaustive" : "thorough"} fan-out). Use /effort off to stop.`);
+                return;
+            }
+            await say(`Effort is currently "${state.level}". Usage: /effort off | high | ultra`);
+        },
+    });
+    // `/ultracode` — the headline name for the maximal-effort mode (Pi's ultracode):
+    // `/ultracode` turns it on, `/ultracode off` turns it off. Alias for /effort ultra.
+    pi.registerCommand("ultracode", {
+        description: "Ultracode: standing maximal-effort mode (this session only, never persisted) — auto-arms an exhaustive workflow for substantive messages. /ultracode off to stop.",
+        async handler(args, _ctx) {
+            const arg = args.trim().toLowerCase();
+            const say = (content) => pi.sendMessage({ customType: "effort", content, display: true });
+            if (arg === "off") {
+                state.level = "off";
+                await say("Ultracode off — messages are no longer auto-armed as workflows.");
+                return;
+            }
+            state.level = "ultra";
+            await say("Ultracode ON — substantive messages now auto-arm an exhaustive workflow (wide fan-out, big-tier synthesis). Use /ultracode off to stop.");
+        },
+    });
+}

package/dist/enums.d.ts

@@ -0,0 +1,69 @@
+/** Classifies a workflow capability by its runtime and documentation role. */
+export declare enum CapabilityClassification {
+    RUNTIME_GLOBAL = "runtime-global",
+    WORKFLOW_TOOL_INPUT = "workflow-tool-input",
+    SCRIPT_CONTRACT = "script-contract",
+    COMPATIBILITY_BEHAVIOR = "compatibility-behavior",
+    INTERNAL_SUBSTRATE = "internal-substrate",
+    DYNAMIC_REFERENCE = "dynamic-reference"
+}
+/** Declares whether workflow authors should use a capability. */
+export declare enum CapabilitySupport {
+    SUPPORTED = "supported",
+    COMPATIBILITY = "compatibility",
+    INTERNAL = "internal"
+}
+/** Identifies the model-visible surface responsible for discovery. */
+export declare enum DiscoveryPlacement {
+    COMPACT_GUIDANCE = "compact-guidance",
+    WORKFLOW_AUTHORING_SKILL = "workflow-authoring-skill",
+    NONE = "none"
+}
+/** Names the subsystem that owns a capability's behavior. */
+export declare enum CapabilityOrigin {
+    PROJECT = "project",
+    TOOL_ADAPTER = "tool-adapter",
+    VM_REALM = "vm-realm",
+    LIVE_CONFIGURATION = "live-configuration"
+}
+/** Severity carried by capability-alignment diagnostics. */
+export declare enum DiagnosticSeverity {
+    ERROR = "error",
+    WARNING = "warning",
+    INFORMATION = "information"
+}
+/** Optional model-comprehension scenario groups. */
+export declare enum ComprehensionSuite {
+    QUICK = "quick",
+    FULL = "full",
+    COVERAGE = "coverage"
+}
+/** Authoring operation exercised by a comprehension scenario. */
+export declare enum ComprehensionTaskKind {
+    WRITE = "write",
+    EDIT = "edit",
+    REVIEW = "review",
+    DEBUG = "debug"
+}
+/** Whether authoring guidance may be optimized against behavioral evidence or must remain frozen. */
+export declare enum WorkflowAuthoringProtection {
+    BEHAVIORALLY_COVERED = "behaviorally-covered",
+    GUIDANCE_FROZEN = "guidance-frozen"
+}
+/** Machine-readable release-gate failure and warning domains. */
+export declare enum WorkflowReleaseDiagnosticCode {
+    INCOMPATIBLE_VERSION = "INCOMPATIBLE_VERSION",
+    MISSING_BEHAVIOR_EVIDENCE = "MISSING_BEHAVIOR_EVIDENCE",
+    UNRESOLVED_BEHAVIOR_EVIDENCE = "UNRESOLVED_BEHAVIOR_EVIDENCE",
+    BROKEN_CONTRACT_REFERENCE = "BROKEN_CONTRACT_REFERENCE",
+    MISSING_PACKAGE_RESOURCE = "MISSING_PACKAGE_RESOURCE",
+    BROKEN_PACKAGE_LINK = "BROKEN_PACKAGE_LINK",
+    STALE_GENERATED_SURFACE = "STALE_GENERATED_SURFACE",
+    TOOL_INPUT_MISMATCH = "TOOL_INPUT_MISMATCH",
+    RUNTIME_CONSTRAINT_DISAGREEMENT = "RUNTIME_CONSTRAINT_DISAGREEMENT",
+    NON_CONTRACTUAL_PROSE_DRIFT = "NON_CONTRACTUAL_PROSE_DRIFT",
+    MISSING_AUTHORING_COVERAGE = "MISSING_AUTHORING_COVERAGE",
+    UNPROTECTED_AUTHORING_GUIDANCE = "UNPROTECTED_AUTHORING_GUIDANCE",
+    PROTECTED_GUIDANCE_DRIFT = "PROTECTED_GUIDANCE_DRIFT",
+    UNKNOWN_COMPREHENSION_SCENARIO = "UNKNOWN_COMPREHENSION_SCENARIO"
+}

package/dist/enums.js

@@ -0,0 +1,78 @@
+/** Classifies a workflow capability by its runtime and documentation role. */
+export var CapabilityClassification;
+(function (CapabilityClassification) {
+    CapabilityClassification["RUNTIME_GLOBAL"] = "runtime-global";
+    CapabilityClassification["WORKFLOW_TOOL_INPUT"] = "workflow-tool-input";
+    CapabilityClassification["SCRIPT_CONTRACT"] = "script-contract";
+    CapabilityClassification["COMPATIBILITY_BEHAVIOR"] = "compatibility-behavior";
+    CapabilityClassification["INTERNAL_SUBSTRATE"] = "internal-substrate";
+    CapabilityClassification["DYNAMIC_REFERENCE"] = "dynamic-reference";
+})(CapabilityClassification || (CapabilityClassification = {}));
+/** Declares whether workflow authors should use a capability. */
+export var CapabilitySupport;
+(function (CapabilitySupport) {
+    CapabilitySupport["SUPPORTED"] = "supported";
+    CapabilitySupport["COMPATIBILITY"] = "compatibility";
+    CapabilitySupport["INTERNAL"] = "internal";
+})(CapabilitySupport || (CapabilitySupport = {}));
+/** Identifies the model-visible surface responsible for discovery. */
+export var DiscoveryPlacement;
+(function (DiscoveryPlacement) {
+    DiscoveryPlacement["COMPACT_GUIDANCE"] = "compact-guidance";
+    DiscoveryPlacement["WORKFLOW_AUTHORING_SKILL"] = "workflow-authoring-skill";
+    DiscoveryPlacement["NONE"] = "none";
+})(DiscoveryPlacement || (DiscoveryPlacement = {}));
+/** Names the subsystem that owns a capability's behavior. */
+export var CapabilityOrigin;
+(function (CapabilityOrigin) {
+    CapabilityOrigin["PROJECT"] = "project";
+    CapabilityOrigin["TOOL_ADAPTER"] = "tool-adapter";
+    CapabilityOrigin["VM_REALM"] = "vm-realm";
+    CapabilityOrigin["LIVE_CONFIGURATION"] = "live-configuration";
+})(CapabilityOrigin || (CapabilityOrigin = {}));
+/** Severity carried by capability-alignment diagnostics. */
+export var DiagnosticSeverity;
+(function (DiagnosticSeverity) {
+    DiagnosticSeverity["ERROR"] = "error";
+    DiagnosticSeverity["WARNING"] = "warning";
+    DiagnosticSeverity["INFORMATION"] = "information";
+})(DiagnosticSeverity || (DiagnosticSeverity = {}));
+/** Optional model-comprehension scenario groups. */
+export var ComprehensionSuite;
+(function (ComprehensionSuite) {
+    ComprehensionSuite["QUICK"] = "quick";
+    ComprehensionSuite["FULL"] = "full";
+    ComprehensionSuite["COVERAGE"] = "coverage";
+})(ComprehensionSuite || (ComprehensionSuite = {}));
+/** Authoring operation exercised by a comprehension scenario. */
+export var ComprehensionTaskKind;
+(function (ComprehensionTaskKind) {
+    ComprehensionTaskKind["WRITE"] = "write";
+    ComprehensionTaskKind["EDIT"] = "edit";
+    ComprehensionTaskKind["REVIEW"] = "review";
+    ComprehensionTaskKind["DEBUG"] = "debug";
+})(ComprehensionTaskKind || (ComprehensionTaskKind = {}));
+/** Whether authoring guidance may be optimized against behavioral evidence or must remain frozen. */
+export var WorkflowAuthoringProtection;
+(function (WorkflowAuthoringProtection) {
+    WorkflowAuthoringProtection["BEHAVIORALLY_COVERED"] = "behaviorally-covered";
+    WorkflowAuthoringProtection["GUIDANCE_FROZEN"] = "guidance-frozen";
+})(WorkflowAuthoringProtection || (WorkflowAuthoringProtection = {}));
+/** Machine-readable release-gate failure and warning domains. */
+export var WorkflowReleaseDiagnosticCode;
+(function (WorkflowReleaseDiagnosticCode) {
+    WorkflowReleaseDiagnosticCode["INCOMPATIBLE_VERSION"] = "INCOMPATIBLE_VERSION";
+    WorkflowReleaseDiagnosticCode["MISSING_BEHAVIOR_EVIDENCE"] = "MISSING_BEHAVIOR_EVIDENCE";
+    WorkflowReleaseDiagnosticCode["UNRESOLVED_BEHAVIOR_EVIDENCE"] = "UNRESOLVED_BEHAVIOR_EVIDENCE";
+    WorkflowReleaseDiagnosticCode["BROKEN_CONTRACT_REFERENCE"] = "BROKEN_CONTRACT_REFERENCE";
+    WorkflowReleaseDiagnosticCode["MISSING_PACKAGE_RESOURCE"] = "MISSING_PACKAGE_RESOURCE";
+    WorkflowReleaseDiagnosticCode["BROKEN_PACKAGE_LINK"] = "BROKEN_PACKAGE_LINK";
+    WorkflowReleaseDiagnosticCode["STALE_GENERATED_SURFACE"] = "STALE_GENERATED_SURFACE";
+    WorkflowReleaseDiagnosticCode["TOOL_INPUT_MISMATCH"] = "TOOL_INPUT_MISMATCH";
+    WorkflowReleaseDiagnosticCode["RUNTIME_CONSTRAINT_DISAGREEMENT"] = "RUNTIME_CONSTRAINT_DISAGREEMENT";
+    WorkflowReleaseDiagnosticCode["NON_CONTRACTUAL_PROSE_DRIFT"] = "NON_CONTRACTUAL_PROSE_DRIFT";
+    WorkflowReleaseDiagnosticCode["MISSING_AUTHORING_COVERAGE"] = "MISSING_AUTHORING_COVERAGE";
+    WorkflowReleaseDiagnosticCode["UNPROTECTED_AUTHORING_GUIDANCE"] = "UNPROTECTED_AUTHORING_GUIDANCE";
+    WorkflowReleaseDiagnosticCode["PROTECTED_GUIDANCE_DRIFT"] = "PROTECTED_GUIDANCE_DRIFT";
+    WorkflowReleaseDiagnosticCode["UNKNOWN_COMPREHENSION_SCENARIO"] = "UNKNOWN_COMPREHENSION_SCENARIO";
+})(WorkflowReleaseDiagnosticCode || (WorkflowReleaseDiagnosticCode = {}));

package/dist/errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Workflow-specific error types.
+ */
+/** Dependency-neutral diagnostic payload retained by capability contract failures. */
+export interface CapabilityErrorDiagnostic {
+    code: string;
+    severity: "error" | "warning" | "information";
+    subject: string;
+    message: string;
+}
+/** Dependency-neutral skill-loading payload retained by generation failures. */
+export interface ModelGenerationSkillLoadingEvidence {
+    discovered: boolean;
+    loaded: boolean;
+    toolCalls: Array<{
+        tool: string;
+        path?: string;
+    }>;
+}
+/** Dependency-neutral provider-usage payload retained by generation failures. */
+export interface ModelGenerationTokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    cost: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** Stable runtime and persistence failure codes exposed to callers and UI surfaces. */
+export declare enum WorkflowErrorCode {
+    /** Agent exceeded timeout. */
+    AGENT_TIMEOUT = "AGENT_TIMEOUT",
+    /** Workflow was aborted by user. */
+    WORKFLOW_ABORTED = "WORKFLOW_ABORTED",
+    /** Agent limit exceeded. */
+    AGENT_LIMIT_EXCEEDED = "AGENT_LIMIT_EXCEEDED",
+    /** Token budget exhausted. */
+    TOKEN_BUDGET_EXHAUSTED = "TOKEN_BUDGET_EXHAUSTED",
+    /**
+     * The provider's subscription/usage/quota/rate limit was hit. Distinct from the
+     * user's self-imposed TOKEN_BUDGET_EXHAUSTED: a provider limit refills on its own,
+     * so the run is checkpointed (paused) and replayed by resume() rather than failed.
+     */
+    PROVIDER_USAGE_LIMIT = "PROVIDER_USAGE_LIMIT",
+    /** Script validation failed. */
+    SCRIPT_VALIDATION_ERROR = "SCRIPT_VALIDATION_ERROR",
+    /** A schema agent never produced valid structured_output (after repair + extraction). */
+    SCHEMA_NONCOMPLIANCE = "SCHEMA_NONCOMPLIANCE",
+    /** A non-schema agent completed without any assistant text output. */
+    AGENT_EMPTY_OUTPUT = "AGENT_EMPTY_OUTPUT",
+    /** Agent execution failed. */
+    AGENT_EXECUTION_ERROR = "AGENT_EXECUTION_ERROR",
+    /** Run state persistence failed. */
+    PERSISTENCE_ERROR = "PERSISTENCE_ERROR",
+    /** Unknown error. */
+    UNKNOWN = "UNKNOWN"
+}
+/** Classified workflow failure with recoverability and optional agent/provider context. */
+export declare class WorkflowError extends Error {
+    readonly code: WorkflowErrorCode;
+    readonly recoverable: boolean;
+    readonly agentLabel?: string;
+    readonly details?: unknown;
+    /** For PROVIDER_USAGE_LIMIT: the provider's human reset hint, e.g. "Resets in ~3h" (verbatim). */
+    readonly resetHint?: string;
+    constructor(message: string, code: WorkflowErrorCode, options?: {
+        recoverable?: boolean;
+        agentLabel?: string;
+        details?: unknown;
+        resetHint?: string;
+    });
+}
+/** Contract failure that retains every definition or assembly diagnostic. */
+export declare class WorkflowCapabilityContractError extends Error {
+    readonly diagnostics: readonly CapabilityErrorDiagnostic[];
+    constructor(message: string, diagnostics: readonly CapabilityErrorDiagnostic[]);
+}
+/** Generation failure that retains loading and token evidence for diagnosis. */
+export declare class ModelGenerationError extends Error {
+    readonly skillLoadingEvidence: ModelGenerationSkillLoadingEvidence;
+    readonly tokenUsage: ModelGenerationTokenUsage;
+    constructor(message: string, skillLoadingEvidence: ModelGenerationSkillLoadingEvidence, tokenUsage: ModelGenerationTokenUsage);
+}
+/** Narrow an unknown failure to WorkflowError. */
+export declare function isWorkflowError(error: unknown): error is WorkflowError;
+/** Report whether an unknown failure is a provider usage-limit checkpoint condition. */
+export declare function isProviderUsageLimit(error: unknown): error is WorkflowError;
+/**
+ * Detect a provider subscription/usage/quota/rate-limit exhaustion from free-form
+ * error text, and extract the provider's human reset hint when present.
+ *
+ * The pi SDK does NOT throw these — it records them as an assistant message with
+ * stopReason "error" and an errorMessage like "Codex usage limit reached (plus
+ * plan). Resets in ~3h.". Callers reading message metadata MUST gate on
+ * stopReason === "error" before trusting this, so a task whose own output merely
+ * mentions "rate limit" is never misclassified. Patterns mirror the SDK's own
+ * non-retryable-limit table. Deliberately excludes transient overloaded/5xx
+ * errors, which stay recoverable and keep retrying.
+ */
+export declare function classifyProviderLimit(text: string | undefined): {
+    matched: boolean;
+    resetHint?: string;
+};
+/** Recognize abort-like Error messages without assuming a provider-specific class. */
+export declare function isAbortError(error: unknown): boolean;
+/** Recognize timeout-like errors by name or message. */
+export declare function isTimeoutError(error: unknown): boolean;
+/**
+ * Wrap an unknown error into a WorkflowError with appropriate classification.
+ */
+export declare function wrapError(error: unknown, context?: {
+    agentLabel?: string;
+}): WorkflowError;

package/dist/errors.js

@@ -0,0 +1,140 @@
+/**
+ * Workflow-specific error types.
+ */
+/** Stable runtime and persistence failure codes exposed to callers and UI surfaces. */
+export var WorkflowErrorCode;
+(function (WorkflowErrorCode) {
+    /** Agent exceeded timeout. */
+    WorkflowErrorCode["AGENT_TIMEOUT"] = "AGENT_TIMEOUT";
+    /** Workflow was aborted by user. */
+    WorkflowErrorCode["WORKFLOW_ABORTED"] = "WORKFLOW_ABORTED";
+    /** Agent limit exceeded. */
+    WorkflowErrorCode["AGENT_LIMIT_EXCEEDED"] = "AGENT_LIMIT_EXCEEDED";
+    /** Token budget exhausted. */
+    WorkflowErrorCode["TOKEN_BUDGET_EXHAUSTED"] = "TOKEN_BUDGET_EXHAUSTED";
+    /**
+     * The provider's subscription/usage/quota/rate limit was hit. Distinct from the
+     * user's self-imposed TOKEN_BUDGET_EXHAUSTED: a provider limit refills on its own,
+     * so the run is checkpointed (paused) and replayed by resume() rather than failed.
+     */
+    WorkflowErrorCode["PROVIDER_USAGE_LIMIT"] = "PROVIDER_USAGE_LIMIT";
+    /** Script validation failed. */
+    WorkflowErrorCode["SCRIPT_VALIDATION_ERROR"] = "SCRIPT_VALIDATION_ERROR";
+    /** A schema agent never produced valid structured_output (after repair + extraction). */
+    WorkflowErrorCode["SCHEMA_NONCOMPLIANCE"] = "SCHEMA_NONCOMPLIANCE";
+    /** A non-schema agent completed without any assistant text output. */
+    WorkflowErrorCode["AGENT_EMPTY_OUTPUT"] = "AGENT_EMPTY_OUTPUT";
+    /** Agent execution failed. */
+    WorkflowErrorCode["AGENT_EXECUTION_ERROR"] = "AGENT_EXECUTION_ERROR";
+    /** Run state persistence failed. */
+    WorkflowErrorCode["PERSISTENCE_ERROR"] = "PERSISTENCE_ERROR";
+    /** Unknown error. */
+    WorkflowErrorCode["UNKNOWN"] = "UNKNOWN";
+})(WorkflowErrorCode || (WorkflowErrorCode = {}));
+/** Classified workflow failure with recoverability and optional agent/provider context. */
+export class WorkflowError extends Error {
+    code;
+    recoverable;
+    agentLabel;
+    details;
+    /** For PROVIDER_USAGE_LIMIT: the provider's human reset hint, e.g. "Resets in ~3h" (verbatim). */
+    resetHint;
+    constructor(message, code, options = {}) {
+        super(message);
+        this.name = "WorkflowError";
+        this.code = code;
+        this.recoverable = options.recoverable ?? false;
+        this.agentLabel = options.agentLabel;
+        this.details = options.details;
+        this.resetHint = options.resetHint;
+    }
+}
+/** Contract failure that retains every definition or assembly diagnostic. */
+export class WorkflowCapabilityContractError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.name = "WorkflowCapabilityContractError";
+        this.diagnostics = diagnostics;
+    }
+}
+/** Generation failure that retains loading and token evidence for diagnosis. */
+export class ModelGenerationError extends Error {
+    skillLoadingEvidence;
+    tokenUsage;
+    constructor(message, skillLoadingEvidence, tokenUsage) {
+        super(message);
+        this.name = "ModelGenerationError";
+        this.skillLoadingEvidence = skillLoadingEvidence;
+        this.tokenUsage = tokenUsage;
+    }
+}
+/** Narrow an unknown failure to WorkflowError. */
+export function isWorkflowError(error) {
+    return error instanceof WorkflowError;
+}
+/** Report whether an unknown failure is a provider usage-limit checkpoint condition. */
+export function isProviderUsageLimit(error) {
+    return isWorkflowError(error) && error.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT;
+}
+/**
+ * Detect a provider subscription/usage/quota/rate-limit exhaustion from free-form
+ * error text, and extract the provider's human reset hint when present.
+ *
+ * The pi SDK does NOT throw these — it records them as an assistant message with
+ * stopReason "error" and an errorMessage like "Codex usage limit reached (plus
+ * plan). Resets in ~3h.". Callers reading message metadata MUST gate on
+ * stopReason === "error" before trusting this, so a task whose own output merely
+ * mentions "rate limit" is never misclassified. Patterns mirror the SDK's own
+ * non-retryable-limit table. Deliberately excludes transient overloaded/5xx
+ * errors, which stay recoverable and keep retrying.
+ */
+export function classifyProviderLimit(text) {
+    if (!text)
+        return { matched: false };
+    const matched = /usage limit|limit reached|insufficient[_\s]?quota|quota exceeded|exceeded your current quota|out of budget|available balance|\bquota\b|rate.?limit|too many requests|\b429\b|GoUsageLimitError|FreeUsageLimitError|\bbilling\b/i.test(text);
+    if (!matched)
+        return { matched: false };
+    const reset = text.match(/resets?\s+(?:in|at)\s+[^.\n]+/i);
+    return { matched: true, resetHint: reset?.[0]?.trim() };
+}
+/** Recognize abort-like Error messages without assuming a provider-specific class. */
+export function isAbortError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /\babort(?:ed)?\b/i.test(error.message);
+}
+/** Recognize timeout-like errors by name or message. */
+export function isTimeoutError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /\btimeout\b/i.test(error.message) || error.name === "TimeoutError";
+}
+/**
+ * Wrap an unknown error into a WorkflowError with appropriate classification.
+ */
+export function wrapError(error, context) {
+    if (isWorkflowError(error))
+        return error;
+    if (isAbortError(error)) {
+        return new WorkflowError(error instanceof Error ? error.message : "Workflow was aborted", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true });
+    }
+    if (isTimeoutError(error)) {
+        return new WorkflowError(error instanceof Error ? error.message : "Agent timed out", WorkflowErrorCode.AGENT_TIMEOUT, { recoverable: true, agentLabel: context?.agentLabel });
+    }
+    // Defense-in-depth: today the SDK buries provider usage/quota limits in an
+    // assistant message (detected in agent.ts), but a future SDK might throw them.
+    // Classify a thrown limit here too — recoverable:false so the run checkpoints
+    // (paused) instead of being retried into the same wall or silently nulled.
+    if (error instanceof Error) {
+        const limit = classifyProviderLimit(error.message);
+        if (limit.matched) {
+            return new WorkflowError(error.message, WorkflowErrorCode.PROVIDER_USAGE_LIMIT, {
+                recoverable: false,
+                agentLabel: context?.agentLabel,
+                resetHint: limit.resetHint,
+            });
+        }
+    }
+    return new WorkflowError(error instanceof Error ? error.message : String(error), WorkflowErrorCode.AGENT_EXECUTION_ERROR, { recoverable: true, agentLabel: context?.agentLabel, details: error });
+}

package/dist/extension-reload.d.ts

@@ -0,0 +1,37 @@
+import type { EffortState } from "./effort-command.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+/**
+ * Live extension state that Pi may hand from one extension generation to the
+ * next during `/reload`. This deliberately stays process-local: run snapshots
+ * and journals already provide the durable cold-start path, while the live
+ * manager is what owns in-flight promises, abort controllers, and event streams.
+ */
+export declare const WORKFLOW_EXTENSION_VERSION: string;
+export interface WorkflowReloadRuntime {
+    cwd: string;
+    /** Package version that created this manager. Only an exact match is retained. */
+    extensionVersion: string;
+    manager: WorkflowManager;
+    effort: EffortState;
+}
+export interface WorkflowRuntimeClaim {
+    compatible?: WorkflowReloadRuntime;
+    versionMismatch?: WorkflowReloadRuntime;
+}
+/** Stage a live runtime immediately before Pi tears down the old extension runner. */
+export declare function handoffWorkflowRuntime(runtime: WorkflowReloadRuntime): void;
+/** Claim a staged runtime from the extension generation that `/reload` just stopped. */
+export declare function takeWorkflowRuntime(cwd: string): WorkflowReloadRuntime | undefined;
+/**
+ * Claim a staged runtime and compare its package version with this extension
+ * generation. Any package update falls back to a fresh manager; only reloads
+ * within the exact same installed version retain live workflow state.
+ */
+export declare function claimWorkflowRuntime(cwd: string): WorkflowRuntimeClaim;
+/**
+ * Move live runs from a replaced extension version onto the existing journal
+ * recovery path before the fresh manager is constructed.
+ */
+export declare function pauseVersionMismatchWorkflowRuntime(runtime: WorkflowReloadRuntime): number;
+/** Test/cleanup helper; identity guard avoids deleting a newer handoff. */
+export declare function discardWorkflowRuntime(cwd: string, runtime?: WorkflowReloadRuntime): void;

package/dist/extension-reload.js

@@ -0,0 +1,78 @@
+import packageJson from "../package.json" with { type: "json" };
+/**
+ * Live extension state that Pi may hand from one extension generation to the
+ * next during `/reload`. This deliberately stays process-local: run snapshots
+ * and journals already provide the durable cold-start path, while the live
+ * manager is what owns in-flight promises, abort controllers, and event streams.
+ */
+export const WORKFLOW_EXTENSION_VERSION = packageJson.version;
+const RELOAD_HANDOFF_KEY = Symbol.for("@quintinshaw/pi-dynamic-workflows:reload-handoffs");
+const RELOAD_HANDOFF_TTL_MS = 30_000;
+function handoffs() {
+    const root = globalThis;
+    const existing = root[RELOAD_HANDOFF_KEY];
+    if (existing)
+        return existing;
+    const created = new Map();
+    root[RELOAD_HANDOFF_KEY] = created;
+    return created;
+}
+/** Stage a live runtime immediately before Pi tears down the old extension runner. */
+export function handoffWorkflowRuntime(runtime) {
+    const store = handoffs();
+    const previous = store.get(runtime.cwd);
+    if (previous)
+        clearTimeout(previous.timer);
+    const entry = {};
+    entry.runtime = runtime;
+    entry.timer = setTimeout(() => {
+        if (store.get(runtime.cwd) === entry)
+            store.delete(runtime.cwd);
+    }, RELOAD_HANDOFF_TTL_MS);
+    entry.timer.unref?.();
+    store.set(runtime.cwd, entry);
+}
+/** Claim a staged runtime from the extension generation that `/reload` just stopped. */
+export function takeWorkflowRuntime(cwd) {
+    const store = handoffs();
+    const entry = store.get(cwd);
+    if (!entry)
+        return undefined;
+    clearTimeout(entry.timer);
+    store.delete(cwd);
+    return entry.runtime;
+}
+/**
+ * Claim a staged runtime and compare its package version with this extension
+ * generation. Any package update falls back to a fresh manager; only reloads
+ * within the exact same installed version retain live workflow state.
+ */
+export function claimWorkflowRuntime(cwd) {
+    const runtime = takeWorkflowRuntime(cwd);
+    if (!runtime)
+        return {};
+    return runtime.extensionVersion === WORKFLOW_EXTENSION_VERSION
+        ? { compatible: runtime }
+        : { versionMismatch: runtime };
+}
+/**
+ * Move live runs from a replaced extension version onto the existing journal
+ * recovery path before the fresh manager is constructed.
+ */
+export function pauseVersionMismatchWorkflowRuntime(runtime) {
+    let paused = 0;
+    for (const run of runtime.manager.listRuns()) {
+        if (run.status === "running" && runtime.manager.pause(run.runId))
+            paused++;
+    }
+    return paused;
+}
+/** Test/cleanup helper; identity guard avoids deleting a newer handoff. */
+export function discardWorkflowRuntime(cwd, runtime) {
+    const store = handoffs();
+    const entry = store.get(cwd);
+    if (!entry || (runtime && entry.runtime !== runtime))
+        return;
+    clearTimeout(entry.timer);
+    store.delete(cwd);
+}

package/dist/fs-persistence.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared filesystem primitives for JSON-backed persistence.
+ *
+ * Both run-persistence.ts (workflow runs) and workflow-saved.ts (saved
+ * workflow commands) persist plain-JSON records to per-record files under a
+ * project/user directory, and both need the same three guarantees:
+ *
+ *  1. Atomic writes with a recovery backup — a crash mid-write must never
+ *     corrupt the live file, and a later-discovered-truncated primary must
+ *     still be recoverable from the last good write.
+ *  2. Corrupt-file recovery on read — a truncated/corrupt primary falls back
+ *     to its `.bak` sidecar instead of losing the record.
+ *  3. A missing or unreadable directory degrades to "no files" rather than
+ *     throwing — a listing must never crash because one storage location is
+ *     temporarily inaccessible (not yet created, deleted mid-race, EACCES).
+ *
+ * This module is the single implementation of all three; run-persistence.ts
+ * and workflow-saved.ts both call into it rather than maintaining parallel
+ * copies.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+/** Filesystem operations used by JSON persistence. Exposed for testing. */
+export type PersistenceFsLayer = {
+    existsSync: typeof existsSync;
+    mkdirSync: typeof mkdirSync;
+    readdirSync: typeof readdirSync;
+    readFileSync: typeof readFileSync;
+    renameSync: typeof renameSync;
+    statSync: typeof statSync;
+    unlinkSync: typeof unlinkSync;
+    writeFileSync: typeof writeFileSync;
+};
+/** The real node:fs implementations. */
+export declare function defaultPersistenceFs(): PersistenceFsLayer;
+/** Merge a partial test override on top of the real node:fs implementations. */
+export declare function resolvePersistenceFs(overrides?: Partial<PersistenceFsLayer>): PersistenceFsLayer;
+/** Ensure `dir` exists (recursive mkdir), idempotent. */
+export declare function ensureDir(fs: PersistenceFsLayer, dir: string): void;
+/**
+ * Atomically write JSON to `path`: tmp-write + rename (atomic on the same
+ * filesystem, so a crash mid-write can't corrupt the live file), then
+ * best-effort refresh a `.bak` sidecar from the just-written good state —
+ * the recovery fallback readJsonWithBackupRecovery() uses if the primary is
+ * later found truncated (e.g. a rename that itself got interrupted by a
+ * power loss on a filesystem/OS combination where rename isn't fully atomic).
+ */
+export declare function writeJsonAtomicWithBackup(fs: PersistenceFsLayer, path: string, data: unknown): void;
+/**
+ * Read JSON from `path`, falling back to `path.bak` if the primary is
+ * missing or fails to parse. Returns null if neither candidate parses.
+ */
+export declare function readJsonWithBackupRecovery<T>(fs: PersistenceFsLayer, path: string): T | null;
+/**
+ * List `.json` record files in `dir`. A missing directory (never created
+ * yet) or an unreadable one (deleted between the existsSync check and
+ * readdirSync, permission-denied, etc.) both degrade to an empty list
+ * rather than throwing — callers (run listings, saved-workflow listings)
+ * must never crash a navigator/listing because one storage location is
+ * temporarily inaccessible.
+ */
+export declare function listJsonFilesSafe(fs: PersistenceFsLayer, dir: string): string[];
+/** Best-effort unlink; ignores missing-file/permission errors, reports whether it deleted anything. */
+export declare function unlinkIfExistsSafe(fs: PersistenceFsLayer, path: string): boolean;