@a5c-ai/agent-runtime 5.0.1-staging.016f0b0e8119

package/dist/observability/health.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Run Health Model (GAP-STATE-008).
+ *
+ * Computes a point-in-time health snapshot from journal events.
+ * Pure function — no file I/O, takes events as input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRunHealthFromEvents = computeRunHealthFromEvents;
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    stuckThresholdMs: 300_000, // 5 minutes
+    degradedErrorRate: 0.3,
+    failedErrorRate: 0.7,
+    maxPendingAge: 600_000, // 10 minutes
+};
+/**
+ * Compute a health snapshot from an array of journal events.
+ */
+function computeRunHealthFromEvents(events, options) {
+    const config = { ...DEFAULT_CONFIG, ...options?.config };
+    const now = options?.now ?? Date.now();
+    // Track effects
+    const requestedAt = new Map(); // effectId → timestamp ms
+    const resolvedEffects = new Set();
+    let failedEffects = 0;
+    let totalLatency = 0;
+    let latencyCount = 0;
+    let lastActivityAt = null;
+    let hasRunFailed = false;
+    const iterations = new Set();
+    for (const event of events) {
+        lastActivityAt = event.recordedAt;
+        const ts = new Date(event.recordedAt).getTime();
+        if (event.type === "RUN_FAILED") {
+            hasRunFailed = true;
+        }
+        if (event.type === "EFFECT_REQUESTED") {
+            const effectId = typeof event.data.effectId === "string" ? event.data.effectId : undefined;
+            if (effectId) {
+                requestedAt.set(effectId, ts);
+            }
+            const iteration = typeof event.data.iteration === "number" ? event.data.iteration : undefined;
+            if (iteration != null) {
+                iterations.add(iteration);
+            }
+        }
+        if (event.type === "EFFECT_RESOLVED") {
+            const effectId = typeof event.data.effectId === "string" ? event.data.effectId : undefined;
+            if (effectId) {
+                resolvedEffects.add(effectId);
+                const reqTs = requestedAt.get(effectId);
+                if (reqTs != null) {
+                    totalLatency += ts - reqTs;
+                    latencyCount++;
+                }
+                const status = typeof event.data.status === "string" ? event.data.status : undefined;
+                if (status === "error") {
+                    failedEffects++;
+                }
+            }
+        }
+    }
+    // Compute metrics
+    const totalEffects = requestedAt.size;
+    const resolvedCount = resolvedEffects.size;
+    const pendingCount = totalEffects - resolvedCount;
+    const errorRate = resolvedCount > 0 ? failedEffects / resolvedCount : 0;
+    const avgEffectLatencyMs = latencyCount > 0 ? Math.round(totalLatency / latencyCount) : 0;
+    // Oldest pending effect age
+    let oldestPendingAgeMs = 0;
+    for (const [effectId, reqTs] of requestedAt) {
+        if (!resolvedEffects.has(effectId)) {
+            const age = now - reqTs;
+            if (age > oldestPendingAgeMs) {
+                oldestPendingAgeMs = age;
+            }
+        }
+    }
+    const metrics = {
+        errorRate,
+        avgEffectLatencyMs,
+        pendingCount,
+        oldestPendingAgeMs,
+        iterationCount: iterations.size,
+        lastActivityAt,
+        totalEffects,
+        resolvedEffects: resolvedCount,
+        failedEffects,
+    };
+    // Determine status and issues
+    const issues = [];
+    let status = "healthy";
+    if (hasRunFailed) {
+        status = "failed";
+        issues.push("Run failed: RUN_FAILED event detected");
+    }
+    else if (errorRate >= config.failedErrorRate && resolvedCount > 0) {
+        status = "failed";
+        issues.push(`High error rate: ${(errorRate * 100).toFixed(1)}% exceeds failed threshold (${(config.failedErrorRate * 100).toFixed(1)}%)`);
+    }
+    else if (lastActivityAt != null &&
+        now - new Date(lastActivityAt).getTime() > config.stuckThresholdMs &&
+        pendingCount > 0) {
+        status = "stuck";
+        const idleMs = now - new Date(lastActivityAt).getTime();
+        issues.push(`Run stuck: no activity for ${Math.round(idleMs / 1000)}s (threshold: ${Math.round(config.stuckThresholdMs / 1000)}s)`);
+    }
+    else if (errorRate >= config.degradedErrorRate && resolvedCount > 0) {
+        status = "degraded";
+        issues.push(`Elevated error rate: ${(errorRate * 100).toFixed(1)}% exceeds degraded threshold (${(config.degradedErrorRate * 100).toFixed(1)}%)`);
+    }
+    // Additional issues (additive, don't change status)
+    if (oldestPendingAgeMs > config.maxPendingAge &&
+        status !== "failed") {
+        issues.push(`Oldest pending effect age: ${Math.round(oldestPendingAgeMs / 1000)}s exceeds max pending age (${Math.round(config.maxPendingAge / 1000)}s)`);
+        if (status === "healthy") {
+            status = "degraded";
+        }
+    }
+    return {
+        status,
+        metrics,
+        issues,
+        computedAt: new Date(now).toISOString(),
+    };
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,6 @@
+export { buildPhaseTimeline, buildPhaseTimelineFromEvents } from "./timeline";
+export { computeRunHealthFromEvents } from "./health";
+export { getRunHealthSnapshot, getOrchestrationStatus, getPendingWorkItems, type OrchestrationStatus, type OrchestrationPhase, type PendingWorkItem, } from "./runStatus";
+export type { PhaseTimeline, PhaseEntry, PhaseName, Milestone, IterationTimeline, RunHealthSnapshot, RunHealthStatus, RunHealthMetrics, HealthConfig, } from "./types";
+export { registerWebhook, unregisterWebhook, listWebhooks, buildWebhookEvent, evaluateAlertLevel, filterRegistrations, type AlertLevel, type WebhookEventType, type WebhookRegistration, type WebhookEvent, type WebhookDeliveryResult, type WebhookRegistry, type WebhookRegistrationInput, WEBHOOK_SCHEMA_VERSION, } from "./webhooks";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SCHEMA_VERSION = exports.filterRegistrations = exports.evaluateAlertLevel = exports.buildWebhookEvent = exports.listWebhooks = exports.unregisterWebhook = exports.registerWebhook = exports.getPendingWorkItems = exports.getOrchestrationStatus = exports.getRunHealthSnapshot = exports.computeRunHealthFromEvents = exports.buildPhaseTimelineFromEvents = exports.buildPhaseTimeline = void 0;
+var timeline_1 = require("./timeline");
+Object.defineProperty(exports, "buildPhaseTimeline", { enumerable: true, get: function () { return timeline_1.buildPhaseTimeline; } });
+Object.defineProperty(exports, "buildPhaseTimelineFromEvents", { enumerable: true, get: function () { return timeline_1.buildPhaseTimelineFromEvents; } });
+var health_1 = require("./health");
+Object.defineProperty(exports, "computeRunHealthFromEvents", { enumerable: true, get: function () { return health_1.computeRunHealthFromEvents; } });
+var runStatus_1 = require("./runStatus");
+Object.defineProperty(exports, "getRunHealthSnapshot", { enumerable: true, get: function () { return runStatus_1.getRunHealthSnapshot; } });
+Object.defineProperty(exports, "getOrchestrationStatus", { enumerable: true, get: function () { return runStatus_1.getOrchestrationStatus; } });
+Object.defineProperty(exports, "getPendingWorkItems", { enumerable: true, get: function () { return runStatus_1.getPendingWorkItems; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "registerWebhook", { enumerable: true, get: function () { return webhooks_1.registerWebhook; } });
+Object.defineProperty(exports, "unregisterWebhook", { enumerable: true, get: function () { return webhooks_1.unregisterWebhook; } });
+Object.defineProperty(exports, "listWebhooks", { enumerable: true, get: function () { return webhooks_1.listWebhooks; } });
+Object.defineProperty(exports, "buildWebhookEvent", { enumerable: true, get: function () { return webhooks_1.buildWebhookEvent; } });
+Object.defineProperty(exports, "evaluateAlertLevel", { enumerable: true, get: function () { return webhooks_1.evaluateAlertLevel; } });
+Object.defineProperty(exports, "filterRegistrations", { enumerable: true, get: function () { return webhooks_1.filterRegistrations; } });
+Object.defineProperty(exports, "WEBHOOK_SCHEMA_VERSION", { enumerable: true, get: function () { return webhooks_1.WEBHOOK_SCHEMA_VERSION; } });

package/dist/observability/runStatus.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Run status and inspection APIs (GAP-OBS-001, GAP-UX-005, GAP-UX-006).
+ *
+ * - getRunHealthSnapshot: wraps computeRunHealthFromEvents with journal loading
+ * - getOrchestrationStatus: structured status view combining metadata, health, effects
+ * - getPendingWorkItems: detailed inspection of pending effects
+ */
+import type { RunHealthSnapshot } from "./types";
+/**
+ * Compute a health snapshot for a run by loading its journal.
+ */
+export declare function getRunHealthSnapshot(runDir: string): Promise<RunHealthSnapshot>;
+export type OrchestrationPhase = "created" | "running" | "waiting" | "completed" | "failed";
+export interface OrchestrationStatus {
+    runId: string;
+    processId: string;
+    phase: OrchestrationPhase;
+    iterationCount: number;
+    totalEffects: number;
+    pendingEffects: number;
+    resolvedEffects: number;
+    failedEffects: number;
+    health: RunHealthSnapshot;
+    createdAt: string;
+    lastActivityAt: string | null;
+}
+/**
+ * Get structured orchestration status for a run.
+ */
+export declare function getOrchestrationStatus(runDir: string): Promise<OrchestrationStatus>;
+export interface PendingWorkItem {
+    effectId: string;
+    taskId?: string;
+    kind?: string;
+    title?: string;
+    requestedAt: string;
+    ageMs: number;
+    labels?: string[];
+}
+/**
+ * List pending (unresolved) effects with rich detail.
+ */
+export declare function getPendingWorkItems(runDir: string): Promise<PendingWorkItem[]>;
+//# sourceMappingURL=runStatus.d.ts.map

package/dist/observability/runStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runStatus.d.ts","sourceRoot":"","sources":["../../src/observability/runStatus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAMjD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAMD,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,CAAC;AAEb,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC,CAqC9B;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC,CA4E5B"}

package/dist/observability/runStatus.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Run status and inspection APIs (GAP-OBS-001, GAP-UX-005, GAP-UX-006).
+ *
+ * - getRunHealthSnapshot: wraps computeRunHealthFromEvents with journal loading
+ * - getOrchestrationStatus: structured status view combining metadata, health, effects
+ * - getPendingWorkItems: detailed inspection of pending effects
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunHealthSnapshot = getRunHealthSnapshot;
+exports.getOrchestrationStatus = getOrchestrationStatus;
+exports.getPendingWorkItems = getPendingWorkItems;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const health_1 = require("./health");
+// ---------------------------------------------------------------------------
+// GAP-OBS-001: Run Health Snapshot
+// ---------------------------------------------------------------------------
+/**
+ * Compute a health snapshot for a run by loading its journal.
+ */
+async function getRunHealthSnapshot(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    return (0, health_1.computeRunHealthFromEvents)(events);
+}
+/**
+ * Get structured orchestration status for a run.
+ */
+async function getOrchestrationStatus(runDir) {
+    const [metadata, events] = await Promise.all([
+        (0, babysitter_sdk_1.readRunMetadata)(runDir),
+        (0, babysitter_sdk_1.loadJournal)(runDir),
+    ]);
+    const health = (0, health_1.computeRunHealthFromEvents)(events);
+    // Determine phase from events
+    let phase = "created";
+    const hasCompleted = events.some((e) => e.type === "RUN_COMPLETED");
+    const hasFailed = events.some((e) => e.type === "RUN_FAILED");
+    const hasPending = health.metrics.pendingCount > 0;
+    if (hasFailed) {
+        phase = "failed";
+    }
+    else if (hasCompleted) {
+        phase = "completed";
+    }
+    else if (hasPending) {
+        phase = "waiting";
+    }
+    else if (events.length > 1) {
+        phase = "running";
+    }
+    return {
+        runId: metadata.runId,
+        processId: metadata.processId,
+        phase,
+        iterationCount: health.metrics.iterationCount,
+        totalEffects: health.metrics.totalEffects,
+        pendingEffects: health.metrics.pendingCount,
+        resolvedEffects: health.metrics.resolvedEffects,
+        failedEffects: health.metrics.failedEffects,
+        health,
+        createdAt: metadata.createdAt,
+        lastActivityAt: health.metrics.lastActivityAt,
+    };
+}
+/**
+ * List pending (unresolved) effects with rich detail.
+ */
+async function getPendingWorkItems(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    const now = Date.now();
+    // Track requested and resolved effect IDs
+    const requested = new Map();
+    const resolved = new Set();
+    for (const event of events) {
+        if (event.type === "EFFECT_REQUESTED") {
+            const effectId = typeof event.data.effectId === "string"
+                ? event.data.effectId
+                : undefined;
+            if (effectId) {
+                requested.set(effectId, {
+                    effectId,
+                    requestedAt: event.recordedAt,
+                    data: event.data,
+                });
+            }
+        }
+        if (event.type === "EFFECT_RESOLVED") {
+            const effectId = typeof event.data.effectId === "string"
+                ? event.data.effectId
+                : undefined;
+            if (effectId) {
+                resolved.add(effectId);
+            }
+        }
+    }
+    // Build pending items
+    const items = [];
+    for (const [effectId, req] of requested) {
+        if (resolved.has(effectId))
+            continue;
+        const reqTs = new Date(req.requestedAt).getTime();
+        // Try to read task definition for richer details
+        let title;
+        let kind;
+        let taskId;
+        let labels;
+        try {
+            const taskPath = path.join(runDir, "tasks", effectId, "task.json");
+            const raw = await node_fs_1.promises.readFile(taskPath, "utf-8");
+            const taskDef = JSON.parse(raw);
+            title = typeof taskDef.title === "string" ? taskDef.title : undefined;
+            kind = typeof taskDef.kind === "string" ? taskDef.kind : undefined;
+            taskId = typeof taskDef.taskId === "string" ? taskDef.taskId : undefined;
+            labels = Array.isArray(taskDef.labels) ? taskDef.labels : undefined;
+        }
+        catch {
+            // Task def may not exist for all effect types
+            kind = typeof req.data.kind === "string" ? req.data.kind : undefined;
+            taskId = typeof req.data.taskId === "string" ? req.data.taskId : undefined;
+        }
+        items.push({
+            effectId,
+            taskId,
+            kind,
+            title,
+            requestedAt: req.requestedAt,
+            ageMs: now - reqTs,
+            labels,
+        });
+    }
+    // Sort by age descending (oldest first)
+    items.sort((a, b) => b.ageMs - a.ageMs);
+    return items;
+}

package/dist/observability/timeline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GAP-OBS-NEW-002: Phase Timeline Visualization.
+ *
+ * Synthesizes phase timeline data from journal events. Identifies planning,
+ * execution, verification, and completion phases with duration metrics.
+ */
+import { type JournalEvent } from "@a5c-ai/babysitter-sdk";
+import type { PhaseTimeline } from "./types";
+export declare function buildPhaseTimelineFromEvents(events: JournalEvent[]): PhaseTimeline;
+export declare function buildPhaseTimeline(runDir: string): Promise<PhaseTimeline>;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/observability/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/observability/timeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,SAAS,CAAC;AA2BjB,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,CA6HlF;AAoCD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAG/E"}

package/dist/observability/timeline.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * GAP-OBS-NEW-002: Phase Timeline Visualization.
+ *
+ * Synthesizes phase timeline data from journal events. Identifies planning,
+ * execution, verification, and completion phases with duration metrics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPhaseTimelineFromEvents = buildPhaseTimelineFromEvents;
+exports.buildPhaseTimeline = buildPhaseTimeline;
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const VERIFICATION_TASK_IDS = new Set([
+    "typecheck",
+    "lint",
+    "run-tests",
+    "adversarial-review",
+]);
+function ms(a, b) {
+    return new Date(b).getTime() - new Date(a).getTime();
+}
+function makePhase(name, startedAt, endedAt) {
+    return {
+        name,
+        startedAt,
+        endedAt,
+        durationMs: endedAt ? ms(startedAt, endedAt) : null,
+    };
+}
+function isVerificationEvent(event) {
+    const taskId = event.data.taskId;
+    return taskId != null && VERIFICATION_TASK_IDS.has(taskId);
+}
+function buildPhaseTimelineFromEvents(events) {
+    if (events.length === 0) {
+        return {
+            phases: [],
+            milestones: [],
+            iterations: [],
+            currentPhase: "planning",
+            totalDurationMs: null,
+        };
+    }
+    const phases = [];
+    const milestones = [];
+    let currentPhase = "planning";
+    const firstEvent = events[0];
+    const lastEvent = events[events.length - 1];
+    // Find key transition points
+    const firstEffectReq = events.find((e) => e.type === "EFFECT_REQUESTED");
+    const runCompleted = events.find((e) => e.type === "RUN_COMPLETED");
+    const runFailed = events.find((e) => e.type === "RUN_FAILED");
+    // Find first verification event (typecheck/lint/test/review)
+    const firstVerificationReq = events.find((e) => e.type === "EFFECT_REQUESTED" && isVerificationEvent(e));
+    const lastVerificationResolved = [...events]
+        .reverse()
+        .find((e) => e.type === "EFFECT_RESOLVED" && isVerificationEvent(e));
+    // Phase 1: Planning — from RUN_CREATED to first EFFECT_REQUESTED
+    if (firstEvent.type === "RUN_CREATED") {
+        const planEnd = firstEffectReq?.recordedAt ?? null;
+        phases.push(makePhase("planning", firstEvent.recordedAt, planEnd));
+        if (planEnd) {
+            currentPhase = "execution";
+        }
+    }
+    // Phase 2: Execution — from first EFFECT_REQUESTED to verification start (or last resolved)
+    if (firstEffectReq) {
+        // Find the last non-verification EFFECT_RESOLVED as fallback execution end
+        const lastNonVerifResolved = [...events]
+            .reverse()
+            .find((e) => e.type === "EFFECT_RESOLVED" && !isVerificationEvent(e));
+        const execEnd = firstVerificationReq?.recordedAt
+            ?? runCompleted?.recordedAt
+            ?? runFailed?.recordedAt
+            ?? lastNonVerifResolved?.recordedAt
+            ?? null;
+        phases.push(makePhase("execution", firstEffectReq.recordedAt, execEnd));
+        currentPhase = execEnd ? (firstVerificationReq ? "verification" : "execution") : "execution";
+    }
+    // Phase 3: Verification — quality gates
+    if (firstVerificationReq) {
+        const verEnd = lastVerificationResolved?.recordedAt
+            ?? runCompleted?.recordedAt
+            ?? runFailed?.recordedAt
+            ?? null;
+        phases.push(makePhase("verification", firstVerificationReq.recordedAt, verEnd));
+        currentPhase = verEnd ? "completion" : "verification";
+    }
+    // Phase 4: Completion
+    if (runCompleted) {
+        phases.push(makePhase("completion", runCompleted.recordedAt, runCompleted.recordedAt));
+        currentPhase = "completed";
+    }
+    else if (runFailed) {
+        phases.push(makePhase("completion", runFailed.recordedAt, runFailed.recordedAt));
+        currentPhase = "failed";
+    }
+    // Extract milestones
+    for (const event of events) {
+        if (event.type === "EFFECT_RESOLVED" && event.data.kind === "breakpoint") {
+            milestones.push({
+                type: "breakpoint",
+                label: event.data.title ?? `Breakpoint ${event.data.effectId}`,
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+        if (event.type === "EFFECT_RESOLVED" &&
+            (event.data.taskId === "adversarial-review")) {
+            milestones.push({
+                type: "quality-gate",
+                label: `Quality review: ${event.data.taskId}`,
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+        if (event.type === "RUN_COMPLETED") {
+            milestones.push({
+                type: "run-completed",
+                label: "Run completed",
+                occurredAt: event.recordedAt,
+            });
+        }
+        if (event.type === "RUN_FAILED") {
+            milestones.push({
+                type: "run-failed",
+                label: "Run failed",
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+    }
+    // Build iteration breakdowns
+    const iterations = buildIterations(events);
+    const totalDurationMs = events.length >= 2 ? ms(firstEvent.recordedAt, lastEvent.recordedAt) : null;
+    return {
+        phases,
+        milestones,
+        iterations,
+        currentPhase,
+        totalDurationMs,
+    };
+}
+function buildIterations(events) {
+    const iterationMap = new Map();
+    for (const event of events) {
+        const iter = event.data.iteration;
+        if (iter != null) {
+            let group = iterationMap.get(iter);
+            if (!group) {
+                group = [];
+                iterationMap.set(iter, group);
+            }
+            group.push(event);
+        }
+    }
+    const iterations = [];
+    for (const [iteration, iterEvents] of iterationMap) {
+        if (iterEvents.length === 0)
+            continue;
+        const first = iterEvents[0];
+        const last = iterEvents[iterEvents.length - 1];
+        const endedAt = last.type === "EFFECT_RESOLVED" ? last.recordedAt : null;
+        iterations.push({
+            iteration,
+            phases: [], // Per-iteration phase breakdown could be added later
+            startedAt: first.recordedAt,
+            endedAt,
+            durationMs: endedAt ? ms(first.recordedAt, endedAt) : null,
+        });
+    }
+    return iterations.sort((a, b) => a.iteration - b.iteration);
+}
+async function buildPhaseTimeline(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    return buildPhaseTimelineFromEvents(events);
+}

package/dist/observability/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Observability types.
+ *
+ * GAP-OBS-NEW-002: Phase Timeline types.
+ * GAP-STATE-008: Run Health Model types.
+ */
+export type RunHealthStatus = "healthy" | "degraded" | "stuck" | "failed";
+export interface RunHealthMetrics {
+    errorRate: number;
+    avgEffectLatencyMs: number;
+    pendingCount: number;
+    oldestPendingAgeMs: number;
+    iterationCount: number;
+    lastActivityAt: string | null;
+    totalEffects: number;
+    resolvedEffects: number;
+    failedEffects: number;
+}
+export interface RunHealthSnapshot {
+    status: RunHealthStatus;
+    metrics: RunHealthMetrics;
+    issues: string[];
+    computedAt: string;
+}
+export interface HealthConfig {
+    /** Threshold for detecting stuck runs (default: 300000ms = 5min). */
+    stuckThresholdMs: number;
+    /** Error rate above which run is 'degraded' (default: 0.3). */
+    degradedErrorRate: number;
+    /** Error rate above which run is 'failed' (default: 0.7). */
+    failedErrorRate: number;
+    /** Max age for pending effects before generating issue (default: 600000ms = 10min). */
+    maxPendingAge: number;
+}
+export type PhaseName = "planning" | "execution" | "verification" | "completion";
+export interface PhaseEntry {
+    name: PhaseName;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+}
+export interface Milestone {
+    type: "breakpoint" | "quality-gate" | "run-completed" | "run-failed";
+    label: string;
+    occurredAt: string;
+    data?: Record<string, unknown>;
+}
+export interface IterationTimeline {
+    iteration: number;
+    phases: PhaseEntry[];
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+}
+export interface PhaseTimeline {
+    phases: PhaseEntry[];
+    milestones: Milestone[];
+    iterations: IterationTimeline[];
+    currentPhase: PhaseName | "completed" | "failed";
+    totalDurationMs: number | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC"}

package/dist/observability/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Observability types.
+ *
+ * GAP-OBS-NEW-002: Phase Timeline types.
+ * GAP-STATE-008: Run Health Model types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });