@agwab/pi-workflow 0.3.0 → 0.4.0

package/dist/workflow-metrics.js

@@ -0,0 +1,272 @@
+export const WORKFLOW_METRICS_SCHEMA_VERSION = 1;
+export const WORKFLOW_METRICS_PRICING_MODEL_VERSION = "provider-reported-v1";
+const USAGE_METRIC_KEYS = [
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "cachedInputTokens",
+    "cacheCreationInputTokens",
+    "cacheReadInputTokens",
+    "reasoningTokens",
+    "costUsd",
+];
+const TIMING_METRIC_KEYS = [
+    "launchWaitMs",
+    "launchDurationMs",
+    "executionMs",
+    "totalMs",
+    "launchSlotReleaseDelayMs",
+];
+function hasOwnValue(record, key) {
+    return Object.hasOwn(record, key);
+}
+function metricValue(record, key) {
+    if (!record || !hasOwnValue(record, key))
+        return null;
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function metricString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function sumMetricValues(values) {
+    if (values.length === 0)
+        return { value: null, incomplete: true };
+    let total = 0;
+    for (const value of values) {
+        if (value === null)
+            return { value: null, incomplete: true };
+        total += value;
+    }
+    return { value: total, incomplete: false };
+}
+function usageAttempts(task) {
+    return task.usage?.aggregate?.attempts ?? task.usage?.attempts?.length ?? 0;
+}
+function timingAttempts(task) {
+    return task.timing?.aggregate?.attempts ?? task.timing?.attempts?.length ?? 0;
+}
+function taskUsageMetrics(task) {
+    const usage = task.usage;
+    const source = usage?.aggregate ?? usage;
+    const unavailable = usage === undefined ||
+        usage.attempts?.some((attempt) => attempt.unavailable) === true;
+    const metrics = Object.fromEntries(USAGE_METRIC_KEYS.map((key) => [key, metricValue(source, key)]));
+    const incomplete = unavailable ||
+        usage?.incomplete === true ||
+        usage?.aggregate?.incomplete === true ||
+        USAGE_METRIC_KEYS.some((key) => metrics[key] === null);
+    return {
+        inputTokens: metrics.inputTokens,
+        outputTokens: metrics.outputTokens,
+        totalTokens: metrics.totalTokens,
+        cachedInputTokens: metrics.cachedInputTokens,
+        cacheCreationInputTokens: metrics.cacheCreationInputTokens,
+        cacheReadInputTokens: metrics.cacheReadInputTokens,
+        reasoningTokens: metrics.reasoningTokens,
+        costUsd: metrics.costUsd,
+        attempts: usageAttempts(task),
+        unavailable,
+        incomplete,
+        unavailableTaskIds: unavailable ? [task.taskId] : [],
+        incompleteTaskIds: incomplete ? [task.taskId] : [],
+    };
+}
+function taskLaunchTimingMetrics(task) {
+    const timing = task.timing;
+    const aggregateSource = timing?.aggregate ?? timing;
+    const unavailable = timing === undefined;
+    const metrics = Object.fromEntries(TIMING_METRIC_KEYS.map((key) => [
+        key,
+        metricValue(key === "launchSlotReleaseDelayMs" ? timing : aggregateSource, key),
+    ]));
+    const incomplete = unavailable ||
+        timing?.aggregate?.incomplete === true ||
+        TIMING_METRIC_KEYS.some((key) => metrics[key] === null);
+    return {
+        launchWaitMs: metrics.launchWaitMs,
+        launchDurationMs: metrics.launchDurationMs,
+        executionMs: metrics.executionMs,
+        totalMs: metrics.totalMs,
+        launchSlotReleaseDelayMs: metrics.launchSlotReleaseDelayMs,
+        attempts: timingAttempts(task),
+        unavailable,
+        incomplete,
+        unavailableTaskIds: unavailable ? [task.taskId] : [],
+        incompleteTaskIds: incomplete ? [task.taskId] : [],
+    };
+}
+function sumResumeRetryAttempts(task, key) {
+    return (task.resumeEvents ?? []).reduce((total, event) => {
+        const attempts = event[key];
+        return typeof attempts === "number" && Number.isFinite(attempts)
+            ? total + attempts
+            : total;
+    }, 0);
+}
+function taskRetryMetrics(task) {
+    const launchRetries = (task.launchRetry?.attempts ?? 0) +
+        sumResumeRetryAttempts(task, "launchRetryAttempts");
+    const outputRetries = (task.outputRetry?.attempts ?? 0) +
+        sumResumeRetryAttempts(task, "outputRetryAttempts");
+    const resumeEvents = task.resumeEvents?.length ?? 0;
+    const totalRetryEvents = launchRetries + outputRetries + resumeEvents;
+    return {
+        launchRetries,
+        outputRetries,
+        resumeEvents,
+        totalRetryEvents,
+        tasksWithRetries: totalRetryEvents > 0 ? 1 : 0,
+    };
+}
+function emptyStatusCounts() {
+    return {
+        pending: 0,
+        running: 0,
+        blocked: 0,
+        completed: 0,
+        failed: 0,
+        skipped: 0,
+        interrupted: 0,
+        total: 0,
+    };
+}
+function rollupUsage(tasks) {
+    const rollup = Object.fromEntries(USAGE_METRIC_KEYS.map((key) => [
+        key,
+        sumMetricValues(tasks.map((task) => task.usage[key])),
+    ]));
+    const unavailableTaskIds = tasks.flatMap((task) => task.usage.unavailableTaskIds);
+    const incompleteTaskIds = tasks.flatMap((task) => task.usage.incompleteTaskIds);
+    return {
+        inputTokens: rollup.inputTokens.value,
+        outputTokens: rollup.outputTokens.value,
+        totalTokens: rollup.totalTokens.value,
+        cachedInputTokens: rollup.cachedInputTokens.value,
+        cacheCreationInputTokens: rollup.cacheCreationInputTokens.value,
+        cacheReadInputTokens: rollup.cacheReadInputTokens.value,
+        reasoningTokens: rollup.reasoningTokens.value,
+        costUsd: rollup.costUsd.value,
+        attempts: tasks.reduce((total, task) => total + task.usage.attempts, 0),
+        unavailable: unavailableTaskIds.length > 0,
+        incomplete: incompleteTaskIds.length > 0 ||
+            USAGE_METRIC_KEYS.some((key) => rollup[key].incomplete),
+        unavailableTaskIds,
+        incompleteTaskIds,
+    };
+}
+function rollupLaunchTiming(tasks) {
+    const rollup = Object.fromEntries(TIMING_METRIC_KEYS.map((key) => [
+        key,
+        sumMetricValues(tasks.map((task) => task.launchTiming[key])),
+    ]));
+    const unavailableTaskIds = tasks.flatMap((task) => task.launchTiming.unavailableTaskIds);
+    const incompleteTaskIds = tasks.flatMap((task) => task.launchTiming.incompleteTaskIds);
+    return {
+        launchWaitMs: rollup.launchWaitMs.value,
+        launchDurationMs: rollup.launchDurationMs.value,
+        executionMs: rollup.executionMs.value,
+        totalMs: rollup.totalMs.value,
+        launchSlotReleaseDelayMs: rollup.launchSlotReleaseDelayMs.value,
+        attempts: tasks.reduce((total, task) => total + task.launchTiming.attempts, 0),
+        unavailable: unavailableTaskIds.length > 0,
+        incomplete: incompleteTaskIds.length > 0 ||
+            TIMING_METRIC_KEYS.some((key) => rollup[key].incomplete),
+        unavailableTaskIds,
+        incompleteTaskIds,
+    };
+}
+function rollupRetries(tasks) {
+    const launchRetries = tasks.reduce((total, task) => total + task.retries.launchRetries, 0);
+    const outputRetries = tasks.reduce((total, task) => total + task.retries.outputRetries, 0);
+    const resumeEvents = tasks.reduce((total, task) => total + task.retries.resumeEvents, 0);
+    return {
+        launchRetries,
+        outputRetries,
+        resumeEvents,
+        totalRetryEvents: launchRetries + outputRetries + resumeEvents,
+        tasksWithRetries: tasks.reduce((total, task) => total + task.retries.tasksWithRetries, 0),
+    };
+}
+function statusCounts(tasks) {
+    const counts = emptyStatusCounts();
+    for (const task of tasks) {
+        counts[task.status] += 1;
+        counts.total += 1;
+    }
+    return counts;
+}
+function rollupTasks(tasks) {
+    return {
+        taskCount: tasks.length,
+        statusCounts: statusCounts(tasks),
+        usage: rollupUsage(tasks),
+        launchTiming: rollupLaunchTiming(tasks),
+        retries: rollupRetries(tasks),
+    };
+}
+function stageMetrics(tasks) {
+    const stageIds = [];
+    for (const task of tasks) {
+        if (!stageIds.includes(task.stageId))
+            stageIds.push(task.stageId);
+    }
+    return stageIds.map((stageId) => ({
+        stageId,
+        ...rollupTasks(tasks.filter((task) => task.stageId === stageId)),
+    }));
+}
+function taskMetrics(task) {
+    return {
+        taskId: task.taskId,
+        specId: task.specId,
+        displayName: task.displayName,
+        agent: task.agent,
+        status: task.status,
+        statusDetail: task.statusDetail,
+        stageId: task.stageId ?? null,
+        kind: task.kind ?? null,
+        provider: metricString(task.usage?.provider),
+        model: metricString(task.usage?.model ?? task.runtime.model),
+        thinking: metricString(task.usage?.thinking ?? task.runtime.thinking),
+        usage: taskUsageMetrics(task),
+        launchTiming: taskLaunchTimingMetrics(task),
+        retries: taskRetryMetrics(task),
+    };
+}
+/**
+ * Build a deterministic, JSON-serializable metrics export from a persisted
+ * workflow run record. The helper is intentionally pure: it reads only the
+ * supplied record, performs no pricing inference, and does not mutate the run.
+ */
+export function buildWorkflowRunMetrics(run) {
+    const byTask = run.tasks.map((task) => taskMetrics(task));
+    const totals = rollupTasks(byTask);
+    return {
+        schemaVersion: WORKFLOW_METRICS_SCHEMA_VERSION,
+        pricingModelVersion: WORKFLOW_METRICS_PRICING_MODEL_VERSION,
+        pricingSource: "provider-reported",
+        costsAreProviderReported: true,
+        run: {
+            runId: run.runId,
+            ...(run.name === undefined ? {} : { name: run.name }),
+            type: run.type,
+            status: run.status,
+            createdAt: run.createdAt,
+            updatedAt: run.updatedAt,
+        },
+        totals,
+        byStage: stageMetrics(byTask),
+        byTask,
+        metadata: {
+            usageUnavailableTaskIds: [...totals.usage.unavailableTaskIds],
+            usageIncompleteTaskIds: [...totals.usage.incompleteTaskIds],
+            launchTimingUnavailableTaskIds: [
+                ...totals.launchTiming.unavailableTaskIds,
+            ],
+            launchTimingIncompleteTaskIds: [...totals.launchTiming.incompleteTaskIds],
+            incomplete: totals.usage.incomplete || totals.launchTiming.incomplete,
+            unavailable: totals.usage.unavailable || totals.launchTiming.unavailable,
+        },
+    };
+}

package/dist/workflow-output-artifacts.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { validateStructuredContract, } from "./workflow-artifacts.js";
+import { stripWorkflowPartialOutputSections } from "./workflow-partial-output.js";
 import { validateJsonSchema, } from "./json-schema.js";
 export const VNEXT_OUTPUT_PROTOCOL = "workflow-output-sections-v1";
 export const VNEXT_TASK_RESULT_SCHEMA = "workflow-task-result-v1";
@@ -17,16 +18,17 @@ const DEFAULT_MAX_DIGEST_CHARS = 1000;
 const DEFAULT_REFS_URL_VALIDATION_TIMEOUT_MS = 8_000;
 const DEFAULT_REFS_URL_VALIDATION_MAX_URLS = 25;
 export function parseWorkflowOutput(raw, options = {}) {
+    const protocolRaw = stripWorkflowPartialOutputSections(raw);
     const issues = [];
     const requirements = sectionRequirements(options);
-    const sections = collectSections(raw, requirements);
-    validateSectionLayout(raw, sections, issues, requirements);
+    const sections = collectSections(protocolRaw, requirements);
+    validateSectionLayout(protocolRaw, sections, issues, requirements);
     const control = parseControlSection(sectionText(sections, SECTION_CONTROL), issues, options);
     const analysis = parseAnalysisSection(sectionText(sections, SECTION_ANALYSIS), issues, requirements);
     const refs = parseRefsSection(sectionText(sections, SECTION_REFS), issues, requirements);
     validateControlContract(control, issues, options.controlContract);
     validateControlJsonSchema(control, issues, options.controlJsonSchema);
-    return buildParsedOutput(raw, issues, { control, analysis, refs }, requirements);
+    return buildParsedOutput(protocolRaw, issues, { control, analysis, refs }, requirements);
 }
 export function parseWorkflowOutputForBundle(raw, options = {}) {
     const parsed = parseWorkflowOutput(raw, options);

package/dist/workflow-partial-output.d.ts

@@ -0,0 +1,45 @@
+export declare const WORKFLOW_PARTIAL_OUTPUT_PROTOCOL: "workflow-partial-output-v1";
+export declare const WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA: "workflow-partial-output-ledger-v1";
+export declare const WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE = "partial-control.json";
+export type WorkflowPartialOutputIssueCode = "invalid_json" | "invalid_type" | "invalid_schema" | "invalid_path" | "disallowed_path" | "missing_items" | "missing_item_id" | "duplicate_item_id";
+export interface WorkflowPartialOutputIssue {
+    code: WorkflowPartialOutputIssueCode;
+    message: string;
+    sectionIndex?: number;
+    path?: string;
+    itemId?: string;
+}
+export interface WorkflowPartialOutputItem {
+    path: string;
+    itemId: string;
+    itemHash: string;
+    item: unknown;
+    ordinal: number;
+    sectionIndex: number;
+    sectionItemIndex: number;
+    itemRef: string;
+}
+export interface WorkflowPartialOutputLedger {
+    schema: typeof WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA;
+    protocol: typeof WORKFLOW_PARTIAL_OUTPUT_PROTOCOL;
+    items: WorkflowPartialOutputItem[];
+    issues: WorkflowPartialOutputIssue[];
+}
+export interface ParseWorkflowPartialOutputOptions {
+    allowedPaths?: readonly string[];
+}
+export declare function partialOutputLedgerPath(taskDir: string): string;
+export declare function readWorkflowPartialOutputLedger(taskDir: string): Promise<WorkflowPartialOutputLedger | undefined>;
+export declare function writeWorkflowPartialOutputLedger(options: {
+    taskDir: string;
+    rawOutput: string;
+    allowedPaths?: readonly string[];
+}): Promise<WorkflowPartialOutputLedger>;
+export declare function writeWorkflowPartialOutputLedgerFromFile(options: {
+    taskDir: string;
+    outputFile: string;
+    allowedPaths?: readonly string[];
+}): Promise<WorkflowPartialOutputLedger | undefined>;
+export declare function stripWorkflowPartialOutputSections(raw: string): string;
+export declare function parseWorkflowPartialOutput(raw: string, options?: ParseWorkflowPartialOutputOptions): WorkflowPartialOutputLedger;
+export declare function hasFatalPartialOutputIssue(ledger: Pick<WorkflowPartialOutputLedger, "issues"> | undefined): WorkflowPartialOutputIssue | undefined;

package/dist/workflow-partial-output.js

@@ -0,0 +1,205 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashDynamicRequest } from "./dynamic-events.js";
+import { readJson, writeJsonAtomic } from "./store.js";
+export const WORKFLOW_PARTIAL_OUTPUT_PROTOCOL = "workflow-partial-output-v1";
+export const WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA = "workflow-partial-output-ledger-v1";
+export const WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE = "partial-control.json";
+const PARTIAL_CONTROL_OPEN = "partial-control";
+export function partialOutputLedgerPath(taskDir) {
+    return join(taskDir, WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE);
+}
+export async function readWorkflowPartialOutputLedger(taskDir) {
+    return await readJson(partialOutputLedgerPath(taskDir));
+}
+export async function writeWorkflowPartialOutputLedger(options) {
+    const ledger = parseWorkflowPartialOutput(options.rawOutput, {
+        allowedPaths: options.allowedPaths,
+    });
+    await writeJsonAtomic(partialOutputLedgerPath(options.taskDir), ledger);
+    return ledger;
+}
+export async function writeWorkflowPartialOutputLedgerFromFile(options) {
+    const rawOutput = await readFile(options.outputFile, "utf8").catch(() => undefined);
+    if (rawOutput === undefined)
+        return undefined;
+    return await writeWorkflowPartialOutputLedger({
+        taskDir: options.taskDir,
+        rawOutput,
+        allowedPaths: options.allowedPaths,
+    });
+}
+export function stripWorkflowPartialOutputSections(raw) {
+    if (!raw.includes(PARTIAL_CONTROL_OPEN))
+        return raw;
+    return raw.replace(partialControlSectionRegExp(), "");
+}
+export function parseWorkflowPartialOutput(raw, options = {}) {
+    const allowedPaths = options.allowedPaths
+        ? new Set(options.allowedPaths)
+        : undefined;
+    const items = [];
+    const issues = [];
+    const byPathAndId = new Map();
+    for (const section of collectPartialControlSections(raw)) {
+        const parsed = parsePartialSectionJson(section, issues);
+        if (!parsed)
+            continue;
+        const path = parsePartialSectionPath(parsed, section, allowedPaths, issues);
+        if (!path)
+            continue;
+        const rawItems = parsePartialSectionItems(parsed, section, path, issues);
+        if (!rawItems)
+            continue;
+        for (const [sectionItemIndex, item] of rawItems.entries()) {
+            const itemId = stablePartialItemId(item);
+            if (!itemId) {
+                issues.push({
+                    code: "missing_item_id",
+                    sectionIndex: section.index,
+                    path,
+                    message: "partial output items must be objects with a stable non-empty string id",
+                });
+                continue;
+            }
+            const itemHash = hashDynamicRequest(item);
+            const key = `${path}\0${itemId}`;
+            const existing = byPathAndId.get(key);
+            if (existing) {
+                if (existing.itemHash !== itemHash) {
+                    issues.push({
+                        code: "duplicate_item_id",
+                        sectionIndex: section.index,
+                        path,
+                        itemId,
+                        message: `partial output item ${itemId} at ${path} changed after it was published`,
+                    });
+                }
+                continue;
+            }
+            const ordinal = items.length;
+            const partialItem = {
+                path,
+                itemId,
+                itemHash,
+                item,
+                ordinal,
+                sectionIndex: section.index,
+                sectionItemIndex,
+                itemRef: `${WORKFLOW_PARTIAL_OUTPUT_LEDGER_FILE}#/items/${ordinal}`,
+            };
+            items.push(partialItem);
+            byPathAndId.set(key, partialItem);
+        }
+    }
+    return {
+        schema: WORKFLOW_PARTIAL_OUTPUT_LEDGER_SCHEMA,
+        protocol: WORKFLOW_PARTIAL_OUTPUT_PROTOCOL,
+        items,
+        issues,
+    };
+}
+export function hasFatalPartialOutputIssue(ledger) {
+    return ledger?.issues.find((issue) => issue.code === "duplicate_item_id");
+}
+function collectPartialControlSections(raw) {
+    if (!raw.includes(PARTIAL_CONTROL_OPEN))
+        return [];
+    const matches = [];
+    const re = partialControlSectionRegExp();
+    let match;
+    while ((match = re.exec(raw)) !== null) {
+        matches.push({
+            content: match[1] ?? "",
+            start: match.index,
+            end: re.lastIndex,
+            index: matches.length,
+        });
+    }
+    return matches;
+}
+function partialControlSectionRegExp() {
+    return /[ \t]*<partial-control\s*>([\s\S]*?)<\/partial-control>[ \t]*(?:\r?\n)?/gi;
+}
+function parsePartialSectionJson(section, issues) {
+    let parsed;
+    try {
+        parsed = JSON.parse(section.content.trim());
+    }
+    catch (error) {
+        issues.push({
+            code: "invalid_json",
+            sectionIndex: section.index,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    if (!isRecord(parsed)) {
+        issues.push({
+            code: "invalid_type",
+            sectionIndex: section.index,
+            message: "partial-control section must contain a JSON object",
+        });
+        return undefined;
+    }
+    if (parsed.schema !== WORKFLOW_PARTIAL_OUTPUT_PROTOCOL) {
+        issues.push({
+            code: "invalid_schema",
+            sectionIndex: section.index,
+            message: `partial-control schema must be ${WORKFLOW_PARTIAL_OUTPUT_PROTOCOL}`,
+        });
+        return undefined;
+    }
+    return parsed;
+}
+function parsePartialSectionPath(section, match, allowedPaths, issues) {
+    const path = section.path;
+    if (typeof path !== "string" || !path.startsWith("$.")) {
+        issues.push({
+            code: "invalid_path",
+            sectionIndex: match.index,
+            message: "partial-control path must be a control JSONPath starting with $.",
+        });
+        return undefined;
+    }
+    if (allowedPaths && !allowedPaths.has(path)) {
+        issues.push({
+            code: "disallowed_path",
+            sectionIndex: match.index,
+            path,
+            message: `partial-control path ${path} is not declared for this stage`,
+        });
+        return undefined;
+    }
+    return path;
+}
+function parsePartialSectionItems(section, match, path, issues) {
+    const items = section.items;
+    if (!Array.isArray(items)) {
+        issues.push({
+            code: "missing_items",
+            sectionIndex: match.index,
+            path,
+            message: "partial-control items must be an array",
+        });
+        return undefined;
+    }
+    return items;
+}
+function stablePartialItemId(item) {
+    if (!isRecord(item) || typeof item.id !== "string")
+        return undefined;
+    const sanitized = sanitizePartialItemId(item.id);
+    return sanitized || undefined;
+}
+function sanitizePartialItemId(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/workflow-progress-health.js

@@ -12,9 +12,6 @@ const STUCK_BY_DURATION = {
 };
 export function diagnoseWorkflowRunHealth(run, options = {}) {
     const nowMs = options.nowMs ?? Date.now();
-    const runningTask = currentRunningTask(run.tasks ?? []);
-    if (runningTask)
-        return diagnoseWorkflowTaskHealth(runningTask, run, { nowMs });
     const problem = (run.tasks ?? []).find((task) => isProblemStatus(task.status));
     if (problem)
         return problemRunHealth(problem, nowMs);
@@ -22,6 +19,9 @@ export function diagnoseWorkflowRunHealth(run, options = {}) {
         return problemWorkflowHealth(run.status);
     if (run.status === "completed")
         return completedWorkflowHealth();
+    const runningTask = currentRunningTask(run.tasks ?? []);
+    if (runningTask)
+        return diagnoseWorkflowTaskHealth(runningTask, run, { nowMs });
     return waitingWorkflowHealth(run, nowMs);
 }
 export function diagnoseWorkflowTaskHealth(task, run, options = {}) {
@@ -41,10 +41,6 @@ export function classifyWorkflowTaskDuration(task) {
         .filter(Boolean)
         .join(" ")
         .toLowerCase();
-    if (/\b(render|helper|support|schema|partition|gate)\b/.test(text))
-        return "short";
-    if (/\b(research|audit|synthesis|review|verify|verifier|normalize|plan|impact|spec)\b/.test(text))
-        return "long";
     const maxRuntimeMs = task.runtime?.maxRuntimeMs;
     if (maxRuntimeMs !== undefined && Number.isFinite(maxRuntimeMs)) {
         if (maxRuntimeMs <= 5 * 60_000)
@@ -52,6 +48,12 @@ export function classifyWorkflowTaskDuration(task) {
         if (maxRuntimeMs >= 60 * 60_000)
             return "long";
     }
+    if (task.kind === "support")
+        return "short";
+    if (/\b(research|audit|synthesi[sz]e?r?|review(?:er|ers|ing|s)?|verif(?:y|ier|iers|ication)|normaliz(?:e|er|ing|ation)?|plan(?:ning)?|impact|spec)\b/.test(text))
+        return "long";
+    if (/\b(render|helper|support|schema|partition|gate)\b/.test(text))
+        return "short";
     return "medium";
 }
 function currentRunningTask(tasks) {
@@ -93,6 +95,33 @@ function problemRunHealth(task, nowMs) {
 }
 function waitingWorkflowHealth(run, nowMs) {
     const hasPending = run.taskSummary.pending > 0;
+    const lastActivityAgeMs = ageMs(run.updatedAt, nowMs);
+    if (hasPending && lastActivityAgeMs !== undefined) {
+        if (lastActivityAgeMs >= STUCK_BY_DURATION.medium) {
+            return {
+                state: "likely-stuck",
+                label: "scheduler stuck",
+                summary: "pending tasks have not scheduled",
+                tone: "error",
+                suggestion: "resume",
+                reason: "no task is running and run activity is stale",
+                lastActivityAt: run.updatedAt,
+                lastActivityAgeMs,
+            };
+        }
+        if (lastActivityAgeMs >= STALL_BY_DURATION.medium) {
+            return {
+                state: "stalled",
+                label: "scheduler quiet",
+                summary: "pending tasks are waiting without recent activity",
+                tone: "warning",
+                suggestion: "inspect",
+                reason: "no task is running and run activity is stale",
+                lastActivityAt: run.updatedAt,
+                lastActivityAgeMs,
+            };
+        }
+    }
     return {
         state: hasPending ? "pending" : "active",
         label: hasPending ? "pending" : "active",
@@ -105,7 +134,7 @@ function waitingWorkflowHealth(run, nowMs) {
             ? "no task is currently running"
             : "workflow is still in progress",
         lastActivityAt: run.updatedAt,
-        lastActivityAgeMs: ageMs(run.updatedAt, nowMs),
+        lastActivityAgeMs,
     };
 }
 function runningTaskHealth(context) {
@@ -189,8 +218,11 @@ function runningContext(task, run, nowMs) {
     const durationClass = classifyWorkflowTaskDuration(task);
     const startedAtMs = parseTime(task.startedAt);
     const heartbeatAt = parseHeartbeatAt(task.lastMessage);
+    const heartbeatAgeMs = ageMs(heartbeatAt, nowMs);
     const activityAt = latestIso([heartbeatAt, run?.updatedAt, task.startedAt]);
     const lastActivityAgeMs = ageMs(activityAt, nowMs);
+    const hasFreshHeartbeat = heartbeatAgeMs !== undefined &&
+        heartbeatAgeMs <= STALL_BY_DURATION[durationClass];
     return {
         task,
         nowMs,
@@ -199,8 +231,8 @@ function runningContext(task, run, nowMs) {
         activityAt,
         lastActivityAgeMs,
         heartbeatAt,
-        heartbeatAgeMs: ageMs(heartbeatAt, nowMs),
-        hasBackendSignal: Boolean(task.backendHandle || task.pid || heartbeatAt),
+        heartbeatAgeMs,
+        hasBackendSignal: Boolean(task.pid || hasFreshHeartbeat),
         staleMs: lastActivityAgeMs ?? Number.POSITIVE_INFINITY,
     };
 }