@rk0429/agentic-relay 21.0.0 → 21.1.2

package/dist/application/routine-status-query-service.js

@@ -1,6 +1,7 @@
 import { ValidationError } from "../core/errors.js";
 import { isProcessAlive } from "./housekeeping.js";
 import { RoutineName } from "../domain/routine-name.js";
+const STALE_HEARTBEAT_THRESHOLD_MS = 60_000;
 export class RoutineStatusQueryService {
     deps;
     checkProcessAlive;
@@ -10,17 +11,24 @@ export class RoutineStatusQueryService {
     }
     async list() {
         const merged = await this.buildMergedView();
-        return merged.map((entry) => ({
-            name: entry.name,
-            status: entry.status,
-            nextScheduledAt: entry.nextScheduledAt,
-            lastRun: entry.lastRun,
-        }));
+        return {
+            entries: merged.entries.map((entry) => ({
+                name: entry.name,
+                status: entry.status,
+                schedule: entry.schedule,
+                missedPolicy: entry.missedPolicy,
+                nextScheduledAt: entry.nextScheduledAt,
+                lastRun: entry.lastRun,
+                lastScheduledAt: entry.lastScheduledAt,
+                warnings: entry.warnings,
+            })),
+            invalid: merged.invalid,
+        };
     }
     async status(name, options = {}) {
         const routineName = name instanceof RoutineName ? name.value : name;
         const merged = await this.buildMergedView(options.limit ?? 10);
-        const entry = merged.find((candidate) => candidate.name === routineName);
+        const entry = merged.entries.find((candidate) => candidate.name === routineName);
         if (!entry) {
             throw new ValidationError(`Routine not found: ${routineName}`, {
                 recoveryHint: "Run a catalog rescan and confirm the routine name.",
@@ -30,52 +38,56 @@ export class RoutineStatusQueryService {
     }
     async buildMergedView(limit = 10) {
         const now = new Date();
-        let catalog = this.deps.catalogService.getCatalog();
-        if (catalog.size === 0) {
-            catalog = (await this.deps.catalogService.rescan()).catalog;
+        let snapshot = this.deps.catalogService.getSnapshot();
+        if (snapshot.catalog.size === 0 && snapshot.invalid.length === 0) {
+            snapshot = await this.deps.catalogService.rescan();
         }
         const [states, runtimes, logs] = await Promise.all([
             this.deps.stateRepo.list(),
             this.deps.runtimeRepo.list(),
             this.deps.store.listLogs(),
         ]);
+        const catalog = snapshot.catalog;
         const stateMap = new Map(states.map((entry) => [entry.name.value, entry]));
         const runtimeMap = new Map(runtimes.map((entry) => [entry.name, entry.projection]));
+        const warningsByName = buildWarningsByName(snapshot);
         const names = new Set([
             ...catalog.keys(),
             ...stateMap.keys(),
             ...runtimeMap.keys(),
         ]);
-        return [...names]
-            .sort((left, right) => left.localeCompare(right))
-            .map((name) => {
-            const catalogEntry = catalog.get(name);
-            const stateEntry = stateMap.get(name);
-            const runtime = runtimeMap.get(name);
-            const recentExecutions = filterRoutineLogs(logs, name).slice(0, limit);
-            const lastRun = stateEntry?.state.lastExecutedAt?.toISOString() ??
-                recentExecutions[0]?.timestamp ??
-                null;
-            const status = resolveStatus(runtime, stateEntry?.state.lastStatus, this.checkProcessAlive);
-            return {
-                name,
-                status,
-                nextScheduledAt: stateEntry?.state.nextScheduledAt?.toISOString() ??
-                    catalogEntry?.definition.trigger?.schedule.nextAfter(now)?.toISOString() ??
-                    null,
-                lastRun,
-                definition: catalogEntry
-                    ? {
-                        description: catalogEntry.definition.description,
-                        yamlPath: catalogEntry.yamlPath,
-                        scheduled: catalogEntry.definition.isScheduled(),
-                    }
-                    : undefined,
-                state: stateEntry?.state,
-                runtime,
-                recentExecutions,
-            };
-        });
+        return {
+            entries: [...names]
+                .sort((left, right) => left.localeCompare(right))
+                .map((name) => {
+                const catalogEntry = catalog.get(name);
+                const stateEntry = stateMap.get(name);
+                const runtime = runtimeMap.get(name);
+                const recentExecutions = filterRoutineLogs(logs, name).slice(0, limit);
+                const lastRun = stateEntry?.state.lastExecutedAt?.toISOString() ?? null;
+                const status = resolveStatus(runtime, stateEntry?.state.lastStatus, this.checkProcessAlive, now);
+                return {
+                    name,
+                    status,
+                    schedule: catalogEntry?.definition.trigger?.schedule.value ?? null,
+                    missedPolicy: catalogEntry?.definition.trigger?.missedPolicy ?? null,
+                    nextScheduledAt: stateEntry?.state.nextScheduledAt?.toISOString() ??
+                        catalogEntry?.definition.trigger?.schedule.nextAfter(now)?.toISOString() ??
+                        null,
+                    lastRun,
+                    lastScheduledAt: stateEntry?.state.lastScheduledAt?.toISOString() ?? null,
+                    warnings: warningsByName.get(name) ?? [],
+                    definition: buildDefinitionDto(catalogEntry),
+                    state: buildRoutineStateDto(stateEntry),
+                    runtime,
+                    recentExecutions,
+                };
+            }),
+            invalid: snapshot.invalid.map((issue) => ({
+                yamlPath: issue.yamlPath,
+                error: issue.error,
+            })),
+        };
     }
 }
 function filterRoutineLogs(logs, routineName) {
@@ -86,13 +98,73 @@ function filterRoutineLogs(logs, routineName) {
     })
         .sort((left, right) => right.timestamp.localeCompare(left.timestamp));
 }
-function resolveStatus(runtime, lastStatus, checkProcessAlive) {
+function resolveStatus(runtime, lastStatus, checkProcessAlive, now) {
     if (runtime) {
-        return checkProcessAlive(runtime.pid) ? "running" : "stale_runtime";
+        if (!checkProcessAlive(runtime.pid)) {
+            return "stale_runtime";
+        }
+        if (now.getTime() - new Date(runtime.lastHeartbeatAt).getTime() >
+            STALE_HEARTBEAT_THRESHOLD_MS) {
+            return "stale_runtime";
+        }
+        return "running";
     }
-    if (lastStatus === "completed" || lastStatus === "failed") {
+    if (lastStatus === "completed" || lastStatus === "failed" || lastStatus === "skipped") {
         return lastStatus;
     }
     return "idle";
 }
+function buildRoutineStateDto(stateEntry) {
+    if (!stateEntry) {
+        return undefined;
+    }
+    return {
+        routineName: stateEntry.name.value,
+        workflowPath: stateEntry.workflowPath,
+        lastExecutedAt: stateEntry.state.lastExecutedAt?.toISOString() ?? null,
+        lastScheduledAt: stateEntry.state.lastScheduledAt?.toISOString() ?? null,
+        lastStatus: stateEntry.state.lastStatus,
+        nextScheduledAt: stateEntry.state.nextScheduledAt?.toISOString() ?? null,
+    };
+}
+function buildDefinitionDto(catalogEntry) {
+    if (!catalogEntry) {
+        return null;
+    }
+    return {
+        description: catalogEntry.definition.description ?? null,
+        yamlPath: catalogEntry.yamlPath,
+        scheduled: catalogEntry.definition.isScheduled(),
+        schedule: catalogEntry.definition.trigger?.schedule.value ?? null,
+        missedPolicy: catalogEntry.definition.trigger?.missedPolicy ?? null,
+        catchUpLimit: catalogEntry.definition.trigger?.catchUpLimit.value ?? null,
+        stepSummary: catalogEntry.definition.workflow.steps.map((step) => `${step.id} (${resolveStepKind(step)})`),
+    };
+}
+function buildWarningsByName(snapshot) {
+    const warnings = new Map();
+    for (const issue of snapshot.invalid) {
+        if (issue.kind !== "duplicate_name" || !issue.routineName) {
+            continue;
+        }
+        const entry = warnings.get(issue.routineName) ?? [];
+        entry.push(formatDuplicateWarning(issue));
+        warnings.set(issue.routineName, entry);
+    }
+    return warnings;
+}
+function formatDuplicateWarning(issue) {
+    const ignored = issue.yamlPath;
+    const retained = issue.duplicateOf ?? "the earlier file";
+    return `Duplicate routine name detected. Ignoring ${ignored} because ${retained} is loaded first.`;
+}
+function resolveStepKind(step) {
+    if ("workflow" in step && step.workflow) {
+        return "workflow";
+    }
+    if ("command" in step && step.command) {
+        return "command";
+    }
+    return "prompt";
+}
 //# sourceMappingURL=routine-status-query-service.js.map

package/dist/application/routine-status-query-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"routine-status-query-service.js","sourceRoot":"","sources":["../../src/application/routine-status-query-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routine-status-query-service.js","sourceRoot":"","sources":["../../src/application/routine-status-query-service.ts"],"names":[],"mappings":"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"}

package/dist/bin/relay.d.ts

@@ -1,9 +1,9 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 import { type ForkOptions } from "node:child_process";
 import { CoreManagementService } from "../application/core-management-service.js";
 import { reconcileAbandonedRunningTaskSessions, runStartupHousekeeping } from "../application/housekeeping.js";
 import { RelayCliService } from "../application/relay-cli-service.js";
-import { RoutineDaemonService, type ProcessStatus } from "../application/routine-daemon-service.js";
+import { RoutineDaemonService, type ProcessStatus, type RoutineDigestEvent } from "../application/routine-daemon-service.js";
 import { RoutineRunService } from "../application/routine-run-service.js";
 import { RoutineStatusQueryService } from "../application/routine-status-query-service.js";
 import { TaskService } from "../application/task-service.js";
@@ -29,6 +29,7 @@ type RoutineCommand = Extract<RelayCliCommand, {
 }>;
 interface TextWriter {
     write(chunk: string): unknown;
+    isTTY?: boolean;
 }
 interface CoreCommandHandlerDependencies {
     service: Pick<CoreManagementService, "setup" | "update" | "remove">;
@@ -63,6 +64,7 @@ interface RoutineCommandHandlerDependencies {
     createRoutineDaemonService: (options: {
         configDir: string;
         allowCommandRun: boolean;
+        onRoutineEvent?: (event: RoutineDigestEvent) => void;
     }) => Promise<Pick<RoutineDaemonService, "start">>;
     createRoutineStatusQueryService: (options: {
         configDir: string;

package/dist/bin/relay.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 import { fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { access, readFile, realpath, rm } from "node:fs/promises";
@@ -136,7 +136,7 @@ async function main() {
         stateRepo: new RoutineStateRepository(store),
         eventLog: new RoutineEventLogSink(store),
     });
-    const createRoutineDaemonService = async ({ configDir, allowCommandRun }) => {
+    const createRoutineDaemonService = async ({ configDir, allowCommandRun, onRoutineEvent }) => {
         const catalogService = new RoutineCatalogService({
             configDir,
             workflowRepo,
@@ -163,6 +163,8 @@ async function main() {
             runService,
             stateRepo,
             leaseRepo,
+        }, {
+            onRoutineEvent,
         });
     };
     const createRoutineStatusQueryService = ({ configDir }) => new RoutineStatusQueryService({
@@ -334,11 +336,19 @@ export async function handleRoutineCommand(command, dependencies) {
     switch (command.kind) {
         case "routine-run": {
             const workflowPath = resolveRoutineWorkflowPath(command.workflowPath, command.configDir, dependencies.cwd);
+            const dryRunTime = new Date().toISOString();
+            const routineVars = command.dryRun
+                ? {
+                    ...(command.vars ?? {}),
+                    scheduled_time: dryRunTime,
+                    trigger_time: dryRunTime,
+                }
+                : (command.vars ?? {});
             await dependencies.runStartupHousekeeping(dependencies.store, {
                 protectedLoopStateFile: command.resumeStateFile,
             });
             await dependencies.reconcileAbandonedRunningTaskSessions(dependencies.store, dependencies.taskService);
-            const loadedRoutine = await dependencies.loadRoutine(workflowPath, dependencies.workflowRepo, command.vars ?? {});
+            const loadedRoutine = await dependencies.loadRoutine(workflowPath, dependencies.workflowRepo, routineVars);
             if (command.dryRun) {
                 dependencies.stdout.write(renderRoutineDryRun(loadedRoutine, workflowPath));
                 return 0;
@@ -425,6 +435,14 @@ export async function handleRoutineCommand(command, dependencies) {
             const service = await dependencies.createRoutineDaemonService({
                 configDir,
                 allowCommandRun: command.allowCommandRun ?? false,
+                onRoutineEvent: command.daemon
+                    ? undefined
+                    : (event) => {
+                        if (event.eventType === "routine_state_updated") {
+                            return;
+                        }
+                        dependencies.stdout.write(`${renderRoutineDigestLine(event, dependencies.stdout)}\n`);
+                    },
             });
             await service.start();
             return 0;
@@ -437,7 +455,7 @@ export async function handleRoutineCommand(command, dependencies) {
             const service = dependencies.createRoutineStatusQueryService({
                 configDir: resolveRoutineConfigDir(command.configDir, dependencies.store, dependencies.cwd),
             });
-            dependencies.stdout.write(renderRoutineList(await service.list()));
+            dependencies.stdout.write(renderRoutineList(await service.list(), command.format ?? "table"));
             return 0;
         }
         case "routine-status": {
@@ -445,7 +463,7 @@ export async function handleRoutineCommand(command, dependencies) {
                 configDir: resolveRoutineConfigDir(command.configDir, dependencies.store, dependencies.cwd),
             });
             if (!command.name) {
-                dependencies.stdout.write(renderRoutineList(await service.list()));
+                dependencies.stdout.write(renderRoutineList(await service.list(), "table"));
                 return 0;
             }
             dependencies.stdout.write(renderRoutineStatus(await service.status(command.name, { limit: command.limit })));
@@ -465,7 +483,7 @@ export function renderHelpText(topic, scriptName = path.basename(fileURLToPath(i
         `       ${scriptName} routine run <path> [--config <dir>] [--var key=value ...] [--dry-run] [--resume-state <file>] [--force-resume] [--allow-command-run]`,
         `       ${scriptName} routine start [--config <dir>] [--daemon] [--allow-command-run]`,
         `       ${scriptName} routine stop`,
-        `       ${scriptName} routine list [--config <dir>]`,
+        `       ${scriptName} routine list [--config <dir>] [--format <table|tsv|json>]`,
         `       ${scriptName} routine status [name] [--config <dir>] [--limit <n>]`,
         `       ${scriptName} core <setup|update|remove> [options]`,
         `       ${scriptName} setup-vscode [--target <code|code-insiders|cursor>] [--uninstall]`,
@@ -549,6 +567,7 @@ function renderRoutineSubcommandHelp(scriptName) {
         "",
         "Options:",
         "  --config <dir>        Override the routine config directory",
+        "  --format <fmt>        Output format for `routine list` (table, tsv, json)",
         "  --daemon              Start the daemon in the background",
         "  --allow-command-run   Allow trusted workflows that declare command.run",
         "  --resume-state <file> Resume a loop-capable routine from checkpoint state",
@@ -585,7 +604,7 @@ function enforceAllowCommandRun(workflowPath, capabilitySummary, allowCommandRun
     }
     const offendingPaths = capabilitySummary.commandRunWorkflowPaths.join(", ");
     throw new ValidationError(`Workflow "${path.resolve(workflowPath)}" requires --allow-command-run because it declares command.run in: ${offendingPaths}.`, {
-        recoveryHint: "Re-run with --allow-command-run only for trusted workflows.",
+        recoveryHint: "Re-run with --allow-command-run only for trusted workflows, e.g. `relay routine run workflow.yaml --allow-command-run`.",
     });
 }
 function isRoutineDaemonChild(env) {
@@ -794,8 +813,12 @@ function printLoopResult(result, writer = process.stderr) {
 function printRoutineRunResult(result, writer = process.stderr) {
     const lines = [
         `Routine ${result.status}.`,
-        `Scheduled time: ${result.scheduledTime}`,
-        ...(result.triggerTime ? [`Trigger time: ${result.triggerTime}`] : []),
+        ...(result.hasTrigger === false
+            ? [`Run time: ${result.scheduledTime}`]
+            : [
+                `Scheduled time: ${result.scheduledTime}`,
+                ...(result.triggerTime ? [`Trigger time: ${result.triggerTime}`] : []),
+            ]),
         ...(result.routineRunId ? [`Routine run id: ${result.routineRunId}`] : []),
         ...(result.workflowExecutionId
             ? [`Workflow execution id: ${result.workflowExecutionId}`]
@@ -821,21 +844,88 @@ function renderRoutineDryRun(loadedRoutine, workflowPath) {
     ];
     return `${lines.join("\n")}\n`;
 }
-function renderRoutineList(entries) {
+function renderRoutineList(result, format = "table") {
+    const { entries, invalid } = result;
+    if (format === "json") {
+        return `${JSON.stringify({ routines: entries, invalid }, null, 2)}\n`;
+    }
     if (entries.length === 0) {
-        return "No routines found.\n";
+        return invalid.length === 0
+            ? "No routines found.\n"
+            : `No routines found.\n\n${renderInvalidRoutineFiles(invalid)}\n`;
     }
-    const lines = entries.map((entry) => `${entry.name}\tstatus=${entry.status}\tnext=${formatOptionalTimestamp(entry.nextScheduledAt)}\tlast=${formatOptionalTimestamp(entry.lastRun)}`);
-    return `${lines.join("\n")}\n`;
+    if (format === "tsv") {
+        const lines = [
+            "NAME\tSCHEDULE\tMISSED\tLAST_RUN\tNEXT_RUN\tSTATUS",
+            ...entries.map((entry) => [
+                entry.name,
+                formatRoutineSchedule(entry.schedule),
+                formatRoutineMissedPolicy(entry.missedPolicy),
+                formatOptionalTimestamp(entry.lastRun),
+                formatOptionalTimestamp(entry.nextScheduledAt),
+                entry.status,
+            ].join("\t")),
+            ...invalid.map((entry) => `# Skipped: ${path.basename(entry.yamlPath)}: ${entry.error.replace(/\r?\n/g, " | ")}`),
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    const rows = entries.map((entry) => [
+        entry.name,
+        formatRoutineSchedule(entry.schedule),
+        formatRoutineMissedPolicy(entry.missedPolicy),
+        formatOptionalTimestamp(entry.lastRun),
+        formatOptionalTimestamp(entry.nextScheduledAt),
+        entry.status,
+    ]);
+    const headers = ["NAME", "SCHEDULE", "MISSED", "LAST RUN", "NEXT RUN", "STATUS"];
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column].length)));
+    const lines = [
+        headers.map((header, column) => header.padEnd(widths[column])).join("  "),
+        ...rows.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join("  ")),
+    ];
+    const sections = [`${lines.join("\n")}\n`];
+    const warnings = [...new Set(entries.flatMap((entry) => entry.warnings))];
+    if (warnings.length > 0) {
+        sections.push(`Warnings:\n${warnings.map((warning) => `  - ${warning}`).join("\n")}\n`);
+    }
+    if (invalid.length > 0) {
+        sections.push(`${renderInvalidRoutineFiles(invalid)}\n`);
+    }
+    return sections.join("\n");
+}
+function renderInvalidRoutineFiles(invalid) {
+    return [
+        `Skipped ${invalid.length} file(s):`,
+        ...invalid.map((entry) => `  - ${path.basename(entry.yamlPath)}: ${firstLine(entry.error)}`),
+    ].join("\n");
+}
+function firstLine(value) {
+    return value.split(/\r?\n/u, 1)[0] ?? "";
 }
 function renderRoutineStatus(entry) {
+    const definition = entry.definition;
+    const nextScheduledAt = entry.state?.nextScheduledAt
+        ? entry.state.nextScheduledAt
+        : entry.nextScheduledAt
+            ? `${entry.nextScheduledAt} (estimated)`
+            : "-";
     const lines = [
         `Name: ${entry.name}`,
         `Status: ${entry.status}`,
-        `Next scheduled: ${formatOptionalTimestamp(entry.nextScheduledAt)}`,
-        `Last run: ${formatOptionalTimestamp(entry.lastRun)}`,
-        ...(entry.definition?.description ? [`Description: ${entry.definition.description}`] : []),
-        ...(entry.definition?.yamlPath ? [`YAML: ${entry.definition.yamlPath}`] : []),
+        `Description: ${definition?.description ?? "-"}`,
+        `YAML: ${definition?.yamlPath ?? "-"}`,
+        `Schedule: ${definition?.schedule ?? "manual"}`,
+        `Missed policy: ${definition?.missedPolicy ?? "-"}`,
+        `Catch-up limit: ${definition?.catchUpLimit ?? "-"}`,
+        `Steps: ${definition?.stepSummary.length ? definition.stepSummary.join(", ") : "-"}`,
+        `Next scheduled: ${nextScheduledAt}`,
+        `Last executed: ${formatOptionalTimestamp(entry.lastRun)}`,
+        `Last scheduled: ${formatOptionalTimestamp(entry.lastScheduledAt)}`,
+        `Workflow path: ${entry.state?.workflowPath ?? "-"}`,
+        `Last status: ${entry.state?.lastStatus ?? "-"}`,
+        ...(entry.warnings.length > 0
+            ? ["Warnings:", ...entry.warnings.map((warning) => `  - ${warning}`)]
+            : []),
         ...(entry.runtime
             ? [
                 `Running pid: ${entry.runtime.pid}`,
@@ -845,7 +935,7 @@ function renderRoutineStatus(entry) {
         "",
         "Recent events:",
         ...(entry.recentExecutions.length > 0
-            ? entry.recentExecutions.map((event) => `  - ${event.timestamp} ${event.event_type}`)
+            ? entry.recentExecutions.map((event) => `  - ${renderRoutineEventSummary(event)}`)
             : ["  - none"]),
     ];
     return `${lines.join("\n")}\n`;
@@ -853,6 +943,66 @@ function renderRoutineStatus(entry) {
 function formatOptionalTimestamp(value) {
     return value ?? "-";
 }
+function formatRoutineSchedule(value) {
+    return value ?? "manual";
+}
+function formatRoutineMissedPolicy(value) {
+    return value ?? "-";
+}
+const DIGEST_EVENT_TYPE_WIDTH = 20;
+function renderRoutineDigestLine(event, writer = process.stdout) {
+    const timestamp = new Date().toISOString().slice(11, 19);
+    const eventType = colorizeDigestEventType(event.eventType.padEnd(DIGEST_EVENT_TYPE_WIDTH), event.eventType, writer);
+    return `[${timestamp}] ${eventType}  ${event.routineName}  ${formatRoutineDigestDetail(event)}`;
+}
+function colorizeDigestEventType(value, eventType, writer) {
+    if (!writer.isTTY) {
+        return value;
+    }
+    const color = eventType === "routine_triggered" || eventType === "routine_catch_up"
+        ? 36
+        : eventType === "routine_completed"
+            ? 32
+            : eventType === "routine_failed"
+                ? 31
+                : eventType === "routine_skipped"
+                    ? 33
+                    : null;
+    return color === null ? value : `\u001B[${color}m${value}\u001B[0m`;
+}
+function formatRoutineDigestDetail(event) {
+    if (typeof event.detail.message === "string") {
+        return event.detail.message;
+    }
+    if (typeof event.detail.reason === "string") {
+        return `reason=${event.detail.reason}`;
+    }
+    if (typeof event.detail.scheduledTime === "string") {
+        return `scheduled_time=${event.detail.scheduledTime}`;
+    }
+    if (typeof event.detail.durationMs === "number") {
+        return `duration=${formatDigestDuration(event.detail.durationMs)}`;
+    }
+    if (typeof event.detail.error === "string") {
+        return `error="${event.detail.error}"`;
+    }
+    return Object.entries(event.detail)
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(" ");
+}
+function formatDigestDuration(durationMs) {
+    if (durationMs % 1000 === 0) {
+        return `${durationMs / 1000}s`;
+    }
+    return `${(durationMs / 1000).toFixed(1)}s`;
+}
+function renderRoutineEventSummary(event) {
+    const detail = (event.details?.routine ?? {});
+    if (event.event_type === "routine_failed") {
+        return `${event.timestamp} ${event.event_type} error_code=${detail.error_code ?? "-"} error_message=${detail.error_message ?? "-"} workflow_execution_id=${detail.workflow_execution_id ?? "-"}`;
+    }
+    return `${event.timestamp} ${event.event_type}`;
+}
 function renderDryRun(workflow, workflowPath) {
     const lines = [];
     lines.push(`Workflow: ${workflow.name}`);
@@ -1034,6 +1184,9 @@ function handleFatalError(error) {
     const message = error instanceof Error ? error.message : "agentic-relay failed unexpectedly.";
     if (error instanceof ValidationError) {
         console.error(message);
+        if (error.recoveryHint) {
+            console.error(`Hint: ${error.recoveryHint}`);
+        }
         process.exitCode = 1;
         return;
     }