@agwab/pi-workflow 0.2.0 → 0.2.1

package/dist/store.js

@@ -8,6 +8,9 @@ const TERMINAL_INDEX_LIMIT = 50;
 const LEASE_STALE_MS = 30_000;
 const INDEX_LOCK_WAIT_MS = 5_000;
 const INDEX_LOCK_RETRY_MS = 50;
+const DEFAULT_INDEX_UPDATE_DEBOUNCE_MS = 500;
+let indexUpdateDebounceMs = DEFAULT_INDEX_UPDATE_DEBOUNCE_MS;
+const pendingIndexUpdates = new Map();
 const runLeaseContext = new AsyncLocalStorage();
 const TASK_STATUSES = [
     "pending",
@@ -256,7 +259,46 @@ export async function writeRunRecord(cwd, run) {
     const derived = deriveRunStatus(run);
     Object.assign(run, derived);
     await writeJsonAtomic(workflowRunPath(cwd, run.runId), run);
-    await updateIndex(cwd).catch(() => undefined);
+    scheduleIndexUpdate(cwd, run.runId, {
+        immediate: isTerminalWorkflowStatus(run.status),
+    });
+}
+function indexUpdateKey(cwd, runId) {
+    return `${cwd}\0${runId}`;
+}
+function scheduleIndexUpdate(cwd, runId, options) {
+    const key = indexUpdateKey(cwd, runId);
+    const existing = pendingIndexUpdates.get(key);
+    if (existing) {
+        clearTimeout(existing.timer);
+        pendingIndexUpdates.delete(key);
+    }
+    const runUpdate = () => {
+        pendingIndexUpdates.delete(key);
+        void updateIndex(cwd, runId).catch(() => undefined);
+    };
+    if (options.immediate) {
+        runUpdate();
+        return;
+    }
+    // Pending debounced index writes are intentionally not flushed on process exit:
+    // the next explicit index rebuild/read path self-heals from run.json records.
+    const timer = setTimeout(runUpdate, indexUpdateDebounceMs);
+    timer.unref?.();
+    pendingIndexUpdates.set(key, { cwd, runId, timer });
+}
+export async function flushPendingIndexUpdatesForTests() {
+    const pending = [...pendingIndexUpdates.values()];
+    pendingIndexUpdates.clear();
+    for (const item of pending)
+        clearTimeout(item.timer);
+    await Promise.all(pending.map((item) => updateIndex(item.cwd, item.runId)));
+}
+export function setIndexUpdateDebounceMsForTests(value) {
+    indexUpdateDebounceMs =
+        value === undefined
+            ? DEFAULT_INDEX_UPDATE_DEBOUNCE_MS
+            : Math.max(0, Math.floor(value));
 }
 export async function writeCompiledRunArtifact(cwd, runId, compiled) {
     const runDir = workflowRunDir(cwd, runId);
@@ -830,48 +872,15 @@ function isRunRecordLike(value) {
         typeof task.status === "string" &&
         TASK_STATUSES.includes(task.status)));
 }
-export async function updateIndex(cwd) {
+export async function updateIndex(cwd, changedRunId) {
     const lockFile = join(workflowsRoot(cwd), "index.lock");
     const ownerId = `${process.pid}-${randomBytes(3).toString("hex")}`;
     await ensureDir(workflowsRoot(cwd));
     await acquireLockWithWait(lockFile, ownerId);
     try {
-        const runs = (await listRunRecords(cwd)).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
-        const active = runs.filter((run) => !isTerminalWorkflowStatus(run.status));
-        const terminal = runs
-            .filter((run) => isTerminalWorkflowStatus(run.status))
-            .slice(0, TERMINAL_INDEX_LIMIT);
-        const selected = [...active, ...terminal].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
-        const index = {
-            schemaVersion: 1,
-            updatedAt: nowIso(),
-            runs: selected.map((run) => ({
-                runId: run.runId,
-                name: run.name,
-                type: run.type,
-                artifactGraph: run.artifactGraph,
-                status: run.status,
-                taskSummary: run.taskSummary,
-                createdAt: run.createdAt,
-                updatedAt: run.updatedAt,
-                parentRunId: run.parentRunId,
-                rootRunId: run.rootRunId,
-                round: run.round,
-                fanout: run.fanout,
-                runJson: toProjectPath(cwd, workflowRunPath(cwd, run.runId)),
-                tasks: run.tasks.map((task) => ({
-                    taskId: task.taskId,
-                    displayName: task.displayName,
-                    agent: task.agent,
-                    kind: task.kind,
-                    stageId: task.stageId,
-                    backendHandle: task.backendHandle,
-                    status: task.status,
-                    statusDetail: task.statusDetail,
-                    lastMessage: task.lastMessage,
-                })),
-            })),
-        };
+        const index = changedRunId
+            ? await updateIndexIncremental(cwd, changedRunId)
+            : await rebuildIndex(cwd);
         await writeJsonAtomic(workflowIndexPath(cwd), index);
         return index;
     }
@@ -879,6 +888,93 @@ export async function updateIndex(cwd) {
         await releaseLock(lockFile, ownerId);
     }
 }
+async function updateIndexIncremental(cwd, changedRunId) {
+    const existing = await readIndexForIncremental(cwd);
+    if (!existing)
+        return rebuildIndex(cwd);
+    let changedRun;
+    try {
+        changedRun = await readRunRecord(cwd, changedRunId);
+    }
+    catch {
+        return rebuildIndex(cwd);
+    }
+    const changedEntry = buildIndexEntry(cwd, changedRun);
+    const entries = existing.runs
+        .filter((entry) => entry.runId !== changedRun.runId)
+        .concat(changedEntry);
+    return {
+        schemaVersion: 1,
+        updatedAt: nowIso(),
+        runs: selectIndexEntries(entries),
+    };
+}
+async function readIndexForIncremental(cwd) {
+    let index;
+    try {
+        index = await readIndex(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isIndexRecordLike(index))
+        return undefined;
+    return index;
+}
+async function rebuildIndex(cwd) {
+    const runs = await listRunRecords(cwd);
+    return {
+        schemaVersion: 1,
+        updatedAt: nowIso(),
+        runs: selectIndexEntries(runs.map((run) => buildIndexEntry(cwd, run))),
+    };
+}
+function selectIndexEntries(entries) {
+    const sorted = [...entries].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    const active = sorted.filter((entry) => !isTerminalWorkflowStatus(entry.status));
+    const terminal = sorted
+        .filter((entry) => isTerminalWorkflowStatus(entry.status))
+        .slice(0, TERMINAL_INDEX_LIMIT);
+    return [...active, ...terminal].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+function buildIndexEntry(cwd, run) {
+    return {
+        runId: run.runId,
+        name: run.name,
+        type: run.type,
+        artifactGraph: run.artifactGraph,
+        status: run.status,
+        taskSummary: run.taskSummary,
+        createdAt: run.createdAt,
+        updatedAt: run.updatedAt,
+        parentRunId: run.parentRunId,
+        rootRunId: run.rootRunId,
+        round: run.round,
+        fanout: run.fanout,
+        runJson: toProjectPath(cwd, workflowRunPath(cwd, run.runId)),
+        tasks: run.tasks.map((task) => ({
+            taskId: task.taskId,
+            displayName: task.displayName,
+            agent: task.agent,
+            kind: task.kind,
+            stageId: task.stageId,
+            backendHandle: task.backendHandle,
+            status: task.status,
+            statusDetail: task.statusDetail,
+            lastMessage: task.lastMessage,
+        })),
+    };
+}
+function isIndexRecordLike(value) {
+    return (value?.schemaVersion === 1 &&
+        Array.isArray(value.runs) &&
+        value.runs.every((entry) => entry &&
+            typeof entry === "object" &&
+            typeof entry.runId === "string" &&
+            typeof entry.updatedAt === "string" &&
+            typeof entry.status === "string" &&
+            Array.isArray(entry.tasks)));
+}
 export function deriveRunStatus(run) {
     const next = { ...run, tasks: run.tasks };
     next.taskSummary = summarizeTasks(next.tasks);

package/dist/subagent-backend.d.ts

@@ -1,6 +1,10 @@
 import type { CompiledTask, WorkflowRunRecord, WorkflowTaskRunRecord } from "./types.js";
 import type { BackendLaunchResult } from "./backend.js";
 export declare function setSubagentApiForTests(api: unknown | undefined): void;
+export declare function setSubagentLaunchControlsForTests(options?: {
+    releaseDelayMs?: number;
+    retryJitterMs?: number | (() => number);
+}): void;
 export declare function cleanupSubagentRun(_cwd: string, run: WorkflowRunRecord): Promise<void>;
 export declare function launchSubagentTask(cwd: string, run: WorkflowRunRecord, task: WorkflowTaskRunRecord, compiledTask: CompiledTask): Promise<BackendLaunchResult>;
 export declare function refreshRunFromSubagentArtifacts(cwd: string, run: WorkflowRunRecord): Promise<WorkflowRunRecord>;

package/dist/subagent-backend.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
 import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { availableParallelism } from "node:os";
 import { fileURLToPath } from "node:url";
 import { fromProjectPath, isTerminalTaskStatus, nowIso, toProjectPath, writeRunRecord, } from "./store.js";
 import { applyTaskResultArtifact, isTaskTimedOut, markTaskTimedOut, } from "./result.js";
@@ -15,6 +16,10 @@ const FETCH_CONTENT_CACHE_ENV = "PI_WORKFLOW_FETCH_CONTENT_CACHE";
 const LEGACY_FETCH_CACHE_ENV = "PI_WORKFLOW_FETCH_CACHE";
 const DEFAULT_TRANSIENT_MODEL_FAILURE_RETRIES = 5;
 const DEFAULT_ARTIFACT_OUTPUT_RETRIES = 2;
+const MAX_CONCURRENT_LAUNCHES_ENV = "PI_WORKFLOW_MAX_CONCURRENT_LAUNCHES";
+const DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS = 3_000;
+const MIN_TRANSIENT_RETRY_JITTER_MS = 1_000;
+const MAX_TRANSIENT_RETRY_JITTER_MS = 5_000;
 const MODULE_PATH = fileURLToPath(import.meta.url);
 const MODULE_DIR = dirname(MODULE_PATH);
 const BUNDLED_PI_WEB_ACCESS_EXTENSION = bundledNodeModulePath("pi-web-access", "index.ts");
@@ -47,6 +52,81 @@ async function loadSubagentApi() {
     cachedSubagentApi ??= import(subagentApiSpecifier).then((mod) => mod);
     return cachedSubagentApi;
 }
+let launchSlotReleaseDelayMs = DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS;
+let transientRetryJitterForTests;
+const launchWaitQueue = [];
+let activeLaunchSlots = 0;
+function resolveMaxConcurrentLaunches() {
+    const override = Number.parseInt(process.env[MAX_CONCURRENT_LAUNCHES_ENV] ?? "", 10);
+    if (Number.isFinite(override))
+        return Math.max(1, Math.floor(override));
+    return Math.max(2, Math.floor(availableParallelism() / 2));
+}
+function isLaunchGateSaturated() {
+    return activeLaunchSlots >= resolveMaxConcurrentLaunches();
+}
+async function acquireLaunchSlot() {
+    if (!isLaunchGateSaturated()) {
+        activeLaunchSlots += 1;
+        return releaseLaunchSlot;
+    }
+    await new Promise((resolveWait) => launchWaitQueue.push(resolveWait));
+    return releaseLaunchSlot;
+}
+function releaseLaunchSlot() {
+    const next = launchWaitQueue.shift();
+    if (next) {
+        // Transfer the occupied slot directly to the queued launcher.
+        next();
+        return;
+    }
+    activeLaunchSlots = Math.max(0, activeLaunchSlots - 1);
+}
+function releaseLaunchSlotAfterDelay(delayMs, release) {
+    if (delayMs <= 0) {
+        release();
+        return;
+    }
+    const timer = setTimeout(release, delayMs);
+    timer.unref?.();
+}
+async function runWithLaunchSlot(action) {
+    const release = await acquireLaunchSlot();
+    let holdAfterReturn = false;
+    try {
+        const result = await action();
+        holdAfterReturn = true;
+        return result;
+    }
+    finally {
+        releaseLaunchSlotAfterDelay(holdAfterReturn ? launchSlotReleaseDelayMs : 0, release);
+    }
+}
+function transientRetryJitterMs() {
+    if (transientRetryJitterForTests)
+        return transientRetryJitterForTests();
+    return (MIN_TRANSIENT_RETRY_JITTER_MS +
+        Math.floor(Math.random() *
+            (MAX_TRANSIENT_RETRY_JITTER_MS - MIN_TRANSIENT_RETRY_JITTER_MS + 1)));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function setSubagentLaunchControlsForTests(options) {
+    launchSlotReleaseDelayMs =
+        options?.releaseDelayMs === undefined
+            ? DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS
+            : Math.max(0, Math.floor(options.releaseDelayMs));
+    transientRetryJitterForTests =
+        options?.retryJitterMs === undefined
+            ? undefined
+            : typeof options.retryJitterMs === "function"
+                ? options.retryJitterMs
+                : () => Math.max(0, Math.floor(options.retryJitterMs));
+    activeLaunchSlots = 0;
+    while (launchWaitQueue.length > 0)
+        launchWaitQueue.shift()?.();
+}
 export async function cleanupSubagentRun(_cwd, run) {
     for (const task of run.tasks) {
         if (isTerminalTaskStatus(task.status))
@@ -77,6 +157,14 @@ export async function launchSubagentTask(cwd, run, task, compiledTask) {
             message: "fast:on is not supported for pi-workflow execution.",
         };
     }
+    if ((task.launchRetry?.attempts ?? 0) > 0) {
+        const jitterMs = transientRetryJitterMs();
+        task.statusDetail = "retry_model_failure";
+        task.lastMessage = `waiting ${jitterMs}ms before retrying transient-model launch`;
+        await writeRunRecord(cwd, run);
+        if (jitterMs > 0)
+            await sleep(jitterMs);
+    }
     const systemPromptFile = fromProjectPath(cwd, task.files.systemPrompt);
     const taskPromptFile = fromProjectPath(cwd, task.files.taskPrompt);
     const outputFile = fromProjectPath(cwd, task.files.output);
@@ -126,7 +214,11 @@ export async function launchSubagentTask(cwd, run, task, compiledTask) {
         subagentOptions.extensions = extensions;
         if (captureToolCallsEnabled())
             subagentOptions.captureToolCalls = true;
-        launched = await api.runSubagent(subagentOptions);
+        if (isLaunchGateSaturated()) {
+            task.lastMessage = `waiting for pi-subagent launch slot (${resolveMaxConcurrentLaunches()} max)`;
+            await writeRunRecord(cwd, run).catch(() => undefined);
+        }
+        launched = await runWithLaunchSlot(() => api.runSubagent(subagentOptions));
     }
     catch (error) {
         task.status = "pending";
@@ -259,8 +351,23 @@ async function materializeTerminalSubagentResult(cwd, run, task, snapshot) {
         : undefined;
     const toolCalls = await readToolCallsSummary(snapshot, subagentResult, artifactRoot);
     const outputText = await readFile(outputFile, "utf8").catch(() => "");
+    const stderrText = await readFile(stderrFile, "utf8").catch(() => "");
     const outputBytes = Buffer.byteLength(outputText, "utf8");
-    const statusInfo = workflowStatusFromSubagent(snapshot, subagentResult, outputBytes);
+    let statusInfo = workflowStatusFromSubagent(snapshot, subagentResult, outputBytes);
+    const deterministicBootFailure = classifyDeterministicBootFailure({
+        statusInfo,
+        stderrText,
+        outputBytes,
+        contextLengthExceeded: Boolean(subagentResult?.metadata?.contextLengthExceeded ??
+            snapshot.metadata?.contextLengthExceeded),
+    });
+    if (deterministicBootFailure) {
+        statusInfo = {
+            status: "failed",
+            failureKind: "deterministic_boot",
+            errorMessage: deterministicBootFailure,
+        };
+    }
     const completedAt = typeof subagentResult?.completedAt === "string"
         ? subagentResult.completedAt
         : (snapshot.completedAt ?? nowIso());
@@ -685,6 +792,23 @@ function failArtifactGraphTask(task, options) {
     task.lastMessage = options.message;
     return true;
 }
+function classifyDeterministicBootFailure(options) {
+    if (options.statusInfo.status !== "failed" ||
+        options.statusInfo.failureKind !== "model" ||
+        options.outputBytes !== 0 ||
+        options.contextLengthExceeded) {
+        return undefined;
+    }
+    const text = options.stderrText;
+    const deterministicPattern = /(Failed to load extension|Cannot find module|(?:failed to load|invalid|missing) (?:workflow )?config(?:uration)?|config(?:uration)? (?:error|failed|invalid))/i;
+    if (!deterministicPattern.test(text))
+        return undefined;
+    const excerpt = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => deterministicPattern.test(line)) ?? text.trim();
+    return `deterministic-boot failure: ${excerpt.slice(0, 500)}`;
+}
 function shouldRetryTransientModelFailure(statusInfo, workflowResult, outputBytes) {
     return (statusInfo.status === "failed" &&
         statusInfo.failureKind === "model" &&
@@ -714,14 +838,14 @@ function retryOrFailTransientSubagentFailure(task, options) {
     if (!exhausted) {
         task.status = "pending";
         task.statusDetail = "retry_model_failure";
-        task.lastMessage = `${options.message}; retrying transient model failure (${attempt}/${maxAttempts})`;
+        task.lastMessage = `${options.message}; retrying transient-model failure (${attempt}/${maxAttempts})`;
         return true;
     }
     task.status = "failed";
     task.statusDetail = task.launchRetry.reason ?? "model_exhausted";
     task.exitCode = 1;
     task.completedAt = nowIso();
-    task.lastMessage = `${options.message}; transient model failure retries exhausted (${maxAttempts})`;
+    task.lastMessage = `${options.message}; transient-model failure retries exhausted (${maxAttempts})`;
     return true;
 }
 function retryOrFailArtifactGraphTask(task, options) {

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowRuntimeThinkingResolution } from "./workflow-runtime.js";
+import type { WorkflowModelInfo, WorkflowRuntimeDefaults, WorkflowRuntimeThinkingResolution } from "./workflow-runtime.js";
 export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
 export declare const FAST_MODES: readonly ["inherit", "off"];
 export declare const APPROVAL_MODES: readonly ["non-interactive", "on-request"];
@@ -420,6 +420,8 @@ export interface CompiledDynamicWorkflowTask {
     helpers: Record<string, CompiledDynamicWorkflowHelper>;
     workflows: Record<string, CompiledDynamicNestedWorkflow>;
     decisionLoop?: CompiledDynamicDecisionLoop;
+    runtimeOverrides?: WorkflowRuntimeDefaults;
+    availableModels?: WorkflowModelInfo[];
 }
 export interface CompiledArtifactGraphTask {
     enabled: true;

package/dist/workflow-runtime.d.ts

@@ -35,6 +35,8 @@ export interface ResolveWorkflowRuntimeOptions {
     availableModels?: WorkflowModelInfo[];
     prompt?: WorkflowRuntimePrompt;
 }
+export type WorkflowRuntimeLayer = WorkflowRuntimeDefaults | undefined;
+export declare function selectWorkflowRuntime(...layers: WorkflowRuntimeLayer[]): WorkflowRuntimeResolutionInput;
 export declare function toWorkflowModelInfo(model: {
     provider: string;
     id: string;

package/dist/workflow-runtime.js

@@ -1,4 +1,34 @@
 import { THINKING_LEVELS } from "./types.js";
+export function selectWorkflowRuntime(...layers) {
+    const modelLayer = layers.find((layer) => modelOf(layer));
+    const model = modelOf(modelLayer);
+    let thinking;
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.thinking) {
+            thinking = layer.thinking;
+            break;
+        }
+        const layerModel = modelOf(layer);
+        const modelThinking = layerModel
+            ? splitKnownThinkingSuffix(layerModel).thinking
+            : undefined;
+        if (modelThinking) {
+            thinking = modelThinking;
+            break;
+        }
+    }
+    return {
+        ...(model ? { model } : {}),
+        ...(thinking ? { thinking } : {}),
+    };
+}
+function modelOf(layer) {
+    return typeof layer?.model === "string" && layer.model.trim()
+        ? layer.model.trim()
+        : undefined;
+}
 export function toWorkflowModelInfo(model) {
     return {
         provider: model.provider,

package/docs/usage.md

@@ -187,6 +187,17 @@ A run prints a `workflow_*` id. Use that id for follow-up commands:
 
 The runtime task is not optional. `/workflow run <workflow>` and `/workflow dynamic` without task text fail before launch.
 
+### Opt-in fast mode
+
+For lower-latency runs, pass `--thinking low` explicitly:
+
+```text
+/workflow run --thinking low deep-research "Research this repository and summarize the architecture tradeoffs."
+/workflow dynamic --thinking low "Research this repository and summarize the architecture tradeoffs."
+```
+
+This is an opt-in fast mode. Package defaults remain conservative until a separate holdout evaluation provides enough evidence to change them. Current evidence is limited but encouraging for explicit fast runs: the 2026-07-02 `deep-research` combined gate on P1/P2/P3-style prompts resolved non-support tasks to `low`, completed selected valid runs in about 15-17 minutes, passed the strict gate 9/9, and had zero source-ref join failures across those 9 runs. Treat this as a speed option, not proof that every workflow should default to `low`.
+
 ### Run-scoped web-source cache
 
 Prefer normalized workflow web tools in new workflows:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-workflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Workflow orchestration for Pi subagents.",
   "private": false,
   "type": "module",