iteration-cli 0.4.3 → 0.5.0

package/dist/launch-agent.d.ts

@@ -1,12 +1,13 @@
+import type { CollectorSource } from "iteration-trace-contracts";
 export type LaunchAgentRestart = {
     isLoaded(timeoutMs: number): Promise<boolean>;
     bootstrap(timeoutMs: number): Promise<void>;
     wait(delayMs: number): Promise<void>;
     now(): number;
 };
-export declare function launchAgentPlist(cliPath?: string, nodePath?: string, logDirectory?: string, dataDirectory?: string): string;
+export declare function launchAgentPlist(cliPath?: string, nodePath?: string, logDirectory?: string, dataDirectory?: string, source?: CollectorSource): string;
 export declare function bootstrapAfterBootout(wasLoaded: boolean, control: LaunchAgentRestart): Promise<void>;
-export declare function installLaunchAgent(dataDirectory?: string): Promise<string>;
-export declare function uninstallLaunchAgent(): Promise<void>;
-export declare function launchAgentStatus(): Promise<boolean>;
+export declare function installLaunchAgent(dataDirectory?: string, source?: CollectorSource): Promise<string>;
+export declare function uninstallLaunchAgent(source?: CollectorSource): Promise<void>;
+export declare function launchAgentStatus(source?: CollectorSource): Promise<boolean>;
 export declare function launchAgentRunning(output: string): boolean;

package/dist/launch-agent.js

@@ -6,7 +6,9 @@ import path from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 const execFile = promisify(execFileCallback);
-const LABEL = "com.iteration.codex-collector";
+function label(source) {
+    return `com.iteration.${source}-collector`;
+}
 const LAUNCHCTL_TIMEOUT_MS = 5_000;
 const RESTART_TIMEOUT_MS = 10_000;
 const RESTART_POLL_MS = 200;
@@ -18,14 +20,15 @@ function xml(value) {
         .replaceAll('"', """)
         .replaceAll("'", "'");
 }
-function plistPath(homeDirectory = os.homedir()) {
-    return path.join(homeDirectory, "Library", "LaunchAgents", `${LABEL}.plist`);
+function plistPath(source, homeDirectory = os.homedir()) {
+    return path.join(homeDirectory, "Library", "LaunchAgents", `${label(source)}.plist`);
 }
-export function launchAgentPlist(cliPath = fileURLToPath(new URL("./cli.js", import.meta.url)), nodePath = process.execPath, logDirectory = path.join(os.homedir(), "Library", "Logs"), dataDirectory = path.join(os.homedir(), ".config", "iteration", "codex-collector")) {
+export function launchAgentPlist(cliPath = fileURLToPath(new URL("./cli.js", import.meta.url)), nodePath = process.execPath, logDirectory = path.join(os.homedir(), "Library", "Logs"), dataDirectory = path.join(os.homedir(), ".config", "iteration", "codex-collector"), source = "codex") {
     const argumentsList = [
         nodePath,
         cliPath,
         "run",
+        source,
         "--data-directory",
         dataDirectory,
     ];
@@ -36,13 +39,13 @@ export function launchAgentPlist(cliPath = fileURLToPath(new URL("./cli.js", imp
         '<?xml version="1.0" encoding="UTF-8"?>',
         '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
         '<plist version="1.0"><dict>',
-        `<key>Label</key><string>${LABEL}</string>`,
+        `<key>Label</key><string>${label(source)}</string>`,
         `<key>ProgramArguments</key><array>${argumentsXml}</array>`,
         "<key>RunAtLoad</key><true/>",
         "<key>KeepAlive</key><true/>",
         "<key>ThrottleInterval</key><integer>10</integer>",
-        `<key>StandardOutPath</key><string>${xml(path.join(logDirectory, "iteration-codex-collector.log"))}</string>`,
-        `<key>StandardErrorPath</key><string>${xml(path.join(logDirectory, "iteration-codex-collector.error.log"))}</string>`,
+        `<key>StandardOutPath</key><string>${xml(path.join(logDirectory, `iteration-${source}-collector.log`))}</string>`,
+        `<key>StandardErrorPath</key><string>${xml(path.join(logDirectory, `iteration-${source}-collector.error.log`))}</string>`,
         "</dict></plist>",
     ].join("");
 }
@@ -61,9 +64,9 @@ function serviceMissing(error) {
     return (String(details.code) === "113" ||
         details.stderr?.includes("Could not find service") === true);
 }
-async function serviceLoaded(target, timeoutMs = LAUNCHCTL_TIMEOUT_MS) {
+async function serviceLoaded(target, source, timeoutMs = LAUNCHCTL_TIMEOUT_MS) {
     try {
-        await execFile("launchctl", ["print", `${target}/${LABEL}`], {
+        await execFile("launchctl", ["print", `${target}/${label(source)}`], {
             timeout: timeoutMs,
         });
         return true;
@@ -74,10 +77,10 @@ async function serviceLoaded(target, timeoutMs = LAUNCHCTL_TIMEOUT_MS) {
         throw error;
     }
 }
-async function bootoutIfLoaded(target) {
-    if (!(await serviceLoaded(target)))
+async function bootoutIfLoaded(target, source) {
+    if (!(await serviceLoaded(target, source)))
         return false;
-    await execFile("launchctl", ["bootout", `${target}/${LABEL}`], {
+    await execFile("launchctl", ["bootout", `${target}/${label(source)}`], {
         timeout: LAUNCHCTL_TIMEOUT_MS,
     });
     return true;
@@ -124,21 +127,21 @@ export async function bootstrapAfterBootout(wasLoaded, control) {
         }
     }
 }
-export async function installLaunchAgent(dataDirectory) {
+export async function installLaunchAgent(dataDirectory, source = "codex") {
     if (process.platform !== "darwin") {
         throw new Error("Automatic startup is currently supported on macOS only.");
     }
-    const file = plistPath();
+    const file = plistPath(source);
     const launchAgents = path.dirname(file);
     const logs = path.join(os.homedir(), "Library", "Logs");
     await fs.mkdir(launchAgents, { recursive: true, mode: 0o755 });
     await fs.mkdir(logs, { recursive: true, mode: 0o755 });
     await fs.writeFile(file, launchAgentPlist(undefined, undefined, undefined, dataDirectory ??
-        path.join(os.homedir(), ".config", "iteration", "codex-collector")), { encoding: "utf8", mode: 0o644 });
+        path.join(os.homedir(), ".config", "iteration", `${source}-collector`), source), { encoding: "utf8", mode: 0o644 });
     const target = launchctlTarget();
-    const wasLoaded = await bootoutIfLoaded(target);
+    const wasLoaded = await bootoutIfLoaded(target, source);
     await bootstrapAfterBootout(wasLoaded, {
-        isLoaded: (timeoutMs) => serviceLoaded(target, timeoutMs),
+        isLoaded: (timeoutMs) => serviceLoaded(target, source, timeoutMs),
         bootstrap: async (timeoutMs) => {
             await execFile("launchctl", ["bootstrap", target, file], {
                 timeout: timeoutMs,
@@ -147,26 +150,26 @@ export async function installLaunchAgent(dataDirectory) {
         wait: sleep,
         now: Date.now,
     });
-    await execFile("launchctl", ["kickstart", "-p", `${target}/${LABEL}`], {
+    await execFile("launchctl", ["kickstart", "-p", `${target}/${label(source)}`], {
         timeout: LAUNCHCTL_TIMEOUT_MS,
     });
     return file;
 }
-export async function uninstallLaunchAgent() {
+export async function uninstallLaunchAgent(source = "codex") {
     if (process.platform !== "darwin") {
         throw new Error("Automatic startup is currently supported on macOS only.");
     }
-    const file = plistPath();
-    await bootoutIfLoaded(launchctlTarget());
+    const file = plistPath(source);
+    await bootoutIfLoaded(launchctlTarget(), source);
     await fs.rm(file, { force: true });
 }
-export async function launchAgentStatus() {
+export async function launchAgentStatus(source = "codex") {
     if (process.platform !== "darwin")
         return false;
     try {
         const { stdout } = await execFile("launchctl", [
             "print",
-            `${launchctlTarget()}/${LABEL}`,
+            `${launchctlTarget()}/${label(source)}`,
         ]);
         return launchAgentRunning(stdout);
     }

package/dist/rollout.js

@@ -3,6 +3,40 @@ import path from "node:path";
 import { parseTracePayload, } from "iteration-trace-contracts";
 import * as z from "zod";
 const recordSchema = z.record(z.string(), z.unknown());
+const CONTEXT_RECORDS = [
+    "session_meta",
+    "turn_context",
+    "compacted",
+    "token_usage_record",
+    "world_state",
+    "retained_context",
+    "security_risk_score",
+];
+const RESPONSE_CONTEXT_TYPES = [
+    "reasoning",
+    "todo_list",
+    "compaction",
+    "context_compaction",
+    "configuration_update",
+    "additional_tools",
+];
+const EVENT_CONTEXT_TYPES = [
+    "task_complete",
+    "task_started",
+    "turn_complete",
+    "token_count",
+    "thread_goal_updated",
+    "thread_rolled_back",
+    "turn_aborted",
+    "thread_settings_applied",
+    "agent_reasoning",
+    "agent_reasoning_raw_content",
+];
+const COMPLETED_CONTEXT_TYPES = [
+    "reasoning",
+    "todo_list",
+];
+const IGNORED_EVENT_MESSAGES = ["turn_started"];
 function parseJsonRecord(value) {
     const parsed = recordSchema.safeParse(value);
     return parsed.success ? parsed.data : null;
@@ -11,6 +45,18 @@ function parseJsonString(value) {
     const parsed = z.string().safeParse(value);
     return parsed.success ? parsed.data : null;
 }
+function oneOf(value, allowed) {
+    return value !== null && allowed.includes(value);
+}
+const sourceOrdinalSchema = z
+    .number()
+    .int()
+    .min(0)
+    .max(Number.MAX_SAFE_INTEGER);
+function sourceOrdinal(value) {
+    const parsed = sourceOrdinalSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
 function sessionFromPath(filename) {
     const basename = path.basename(filename, ".jsonl");
     return basename.startsWith("rollout-")
@@ -33,6 +79,32 @@ function safePayload(value) {
         return null;
     }
 }
+function eventTimestamp(record) {
+    const timestamp = parseJsonString(record.timestamp);
+    return timestamp !== null && !Number.isNaN(Date.parse(timestamp))
+        ? timestamp
+        : null;
+}
+function capturedEvent(record, filename, byteOffset, eventType, payload, callId, run) {
+    const eventPayload = safePayload(payload);
+    if (eventPayload === null)
+        return { kind: "gap", reason: `invalid_${eventType}_payload` };
+    const sessionId = sessionFromPath(filename);
+    return {
+        kind: "event",
+        event: {
+            eventId: sha256(`${sessionId}:${byteOffset}`),
+            sessionId,
+            sequence: byteOffset,
+            callId,
+            projectId: null,
+            occurredAt: eventTimestamp(record),
+            eventType,
+            payload: eventPayload,
+            ...(run === undefined ? {} : { run }),
+        },
+    };
+}
 function mapResponseItem(payload) {
     const type = parseJsonString(payload.type);
     if (type === "message") {
@@ -46,9 +118,10 @@ function mapResponseItem(payload) {
     if (type === "agent_message") {
         return { eventType: "assistant_message", callId: null };
     }
-    if (["reasoning", "todo_list"].includes(type ?? ""))
-        return null;
-    if ([
+    if (oneOf(type, RESPONSE_CONTEXT_TYPES)) {
+        return { eventType: type, callId: null };
+    }
+    if (oneOf(type, [
         "function_call",
         "custom_tool_call",
         "mcp_tool_call",
@@ -56,42 +129,39 @@ function mapResponseItem(payload) {
         "tool_search_call",
         "image_generation_call",
         "local_shell_call",
-    ].includes(type ?? "")) {
+    ])) {
         return { eventType: "tool_call", callId: callIdFrom(payload) };
     }
-    if ([
+    if (oneOf(type, [
         "function_call_output",
         "custom_tool_call_output",
         "mcp_tool_call_output",
         "web_search_output",
         "tool_search_output",
-    ].includes(type ?? "")) {
+    ])) {
         return { eventType: "tool_result", callId: callIdFrom(payload) };
     }
     return null;
 }
 function mapCompletedItem(item) {
     const type = parseJsonString(item.type);
-    if ([
+    if (oneOf(type, [
         "command_execution",
         "mcp_tool_call",
         "collab_tool_call",
         "web_search",
         "file_change",
-    ].includes(type ?? "")) {
+    ])) {
         return { eventType: "tool_result", callId: callIdFrom(item) };
     }
     if (type === "agent_message") {
         return { eventType: "assistant_message", callId: null };
     }
+    if (oneOf(type, COMPLETED_CONTEXT_TYPES)) {
+        return { eventType: type, callId: null };
+    }
     return null;
 }
-function eventTimestamp(record) {
-    const timestamp = parseJsonString(record.timestamp);
-    return timestamp !== null && !Number.isNaN(Date.parse(timestamp))
-        ? timestamp
-        : null;
-}
 export function parseRolloutLine(line, filename, byteOffset) {
     let decoded;
     try {
@@ -105,131 +175,66 @@ export function parseRolloutLine(line, filename, byteOffset) {
         return { kind: "gap", reason: "record_is_not_an_object" };
     const recordType = parseJsonString(record.type);
     const payload = parseJsonRecord(record.payload);
-    if ([
-        "session_meta",
-        "turn_context",
-        "compacted",
-        "token_usage_record",
-        "world_state",
-        "retained_context",
-        "security_risk_score",
-    ].includes(recordType ?? "")) {
-        return { kind: "ignored" };
+    if (oneOf(recordType, CONTEXT_RECORDS)) {
+        if (payload === null)
+            return { kind: "gap", reason: `${recordType}_without_payload` };
+        let run;
+        if (recordType === "session_meta" &&
+            parseJsonString(payload.id) === sessionFromPath(filename).slice(-36)) {
+            const source = parseJsonRecord(payload.source);
+            const subagent = source === null ? null : parseJsonRecord(source.subagent);
+            const spawn = subagent === null ? null : parseJsonRecord(subagent.thread_spawn);
+            const parentId = parseJsonString(payload.parent_thread_id) ??
+                (spawn === null ? null : parseJsonString(spawn.parent_thread_id));
+            const startOrdinal = sourceOrdinal(payload.subagent_history_start_ordinal);
+            run = {
+                kind: "identity",
+                id: sessionFromPath(filename).slice(-36),
+                parentId,
+                ownStart: parentId === null,
+                startOrdinal,
+            };
+        }
+        return capturedEvent(record, filename, byteOffset, recordType, payload, null, run);
     }
     if (recordType === "response_item" && payload !== null) {
         const mapped = mapResponseItem(payload);
         if (mapped === null) {
             const payloadType = parseJsonString(payload.type) ?? "unknown";
-            if ([
-                "reasoning",
-                "compaction",
-                "context_compaction",
-                "configuration_update",
-                "additional_tools",
-            ].includes(payloadType)) {
-                return { kind: "ignored" };
-            }
             return {
                 kind: "gap",
                 reason: `unsupported_response_item:${payloadType}`,
             };
         }
-        const eventPayload = safePayload(payload);
-        if (eventPayload === null)
-            return { kind: "gap", reason: "invalid_response_item_payload" };
-        const sessionId = sessionFromPath(filename);
-        return {
-            kind: "event",
-            event: {
-                eventId: sha256(`${sessionId}:${byteOffset}`),
-                sessionId,
-                sequence: byteOffset,
-                callId: mapped.callId,
-                projectId: null,
-                occurredAt: eventTimestamp(record),
-                eventType: mapped.eventType,
-                payload: eventPayload,
-            },
-        };
+        return capturedEvent(record, filename, byteOffset, mapped.eventType, payload, mapped.callId);
     }
     if (recordType === "event_msg" && payload !== null) {
         const messageType = parseJsonString(payload.type);
         if (messageType === "user_message") {
-            const eventPayload = safePayload(payload);
-            if (eventPayload === null)
-                return { kind: "gap", reason: "invalid_user_message_payload" };
-            const sessionId = sessionFromPath(filename);
-            return {
-                kind: "event",
-                event: {
-                    eventId: sha256(`${sessionId}:${byteOffset}`),
-                    sessionId,
-                    sequence: byteOffset,
-                    callId: null,
-                    projectId: null,
-                    occurredAt: eventTimestamp(record),
-                    eventType: "user_message",
-                    payload: eventPayload,
-                },
-            };
+            return capturedEvent(record, filename, byteOffset, "user_message", payload, null);
         }
         if (messageType === "agent_message") {
-            const eventPayload = safePayload(payload);
-            if (eventPayload === null)
-                return { kind: "gap", reason: "invalid_agent_message_payload" };
-            const sessionId = sessionFromPath(filename);
-            return {
-                kind: "event",
-                event: {
-                    eventId: sha256(`${sessionId}:${byteOffset}`),
-                    sessionId,
-                    sequence: byteOffset,
-                    callId: null,
-                    projectId: null,
-                    occurredAt: eventTimestamp(record),
-                    eventType: "assistant_message",
-                    payload: eventPayload,
-                },
-            };
+            return capturedEvent(record, filename, byteOffset, "assistant_message", payload, null);
         }
-        if ([
+        if (oneOf(messageType, [
             "mcp_tool_call_end",
             "web_search_end",
             "image_generation_end",
             "patch_apply_end",
-        ].includes(messageType ?? "")) {
-            const eventPayload = safePayload(payload);
-            if (eventPayload === null)
-                return { kind: "gap", reason: "invalid_tool_result_payload" };
-            const sessionId = sessionFromPath(filename);
-            return {
-                kind: "event",
-                event: {
-                    eventId: sha256(`${sessionId}:${byteOffset}`),
-                    sessionId,
-                    sequence: byteOffset,
-                    callId: callIdFrom(payload),
-                    projectId: null,
-                    occurredAt: eventTimestamp(record),
-                    eventType: "tool_result",
-                    payload: eventPayload,
-                },
-            };
+        ])) {
+            return capturedEvent(record, filename, byteOffset, "tool_result", payload, callIdFrom(payload));
         }
-        if ([
-            "task_started",
-            "turn_started",
-            "task_complete",
-            "turn_complete",
-            "token_count",
-            "thread_goal_updated",
-            "thread_rolled_back",
-            "turn_aborted",
-            "thread_settings_applied",
-            "agent_reasoning",
-            "agent_reasoning_raw_content",
-        ].includes(messageType ?? "")) {
+        if (oneOf(messageType, IGNORED_EVENT_MESSAGES))
             return { kind: "ignored" };
+        if (oneOf(messageType, EVENT_CONTEXT_TYPES)) {
+            const ordinal = sourceOrdinal(record.ordinal);
+            const run = messageType === "thread_settings_applied" &&
+                parseJsonString(payload.thread_id) ===
+                    sessionFromPath(filename).slice(-36) &&
+                ordinal !== null
+                ? { kind: "start", sourceOrdinal: ordinal }
+                : undefined;
+            return capturedEvent(record, filename, byteOffset, messageType, payload, null, run);
         }
         if (messageType !== "item_completed") {
             return {
@@ -243,27 +248,9 @@ export function parseRolloutLine(line, filename, byteOffset) {
         const mapped = mapCompletedItem(item);
         if (mapped === null) {
             const itemType = parseJsonString(item.type) ?? "unknown";
-            if (["reasoning", "todo_list"].includes(itemType))
-                return { kind: "ignored" };
             return { kind: "gap", reason: `unsupported_completed_item:${itemType}` };
         }
-        const eventPayload = safePayload(item);
-        if (eventPayload === null)
-            return { kind: "gap", reason: "invalid_completed_item_payload" };
-        const sessionId = sessionFromPath(filename);
-        return {
-            kind: "event",
-            event: {
-                eventId: sha256(`${sessionId}:${byteOffset}`),
-                sessionId,
-                sequence: byteOffset,
-                callId: mapped.callId,
-                projectId: null,
-                occurredAt: eventTimestamp(record),
-                eventType: mapped.eventType,
-                payload: eventPayload,
-            },
-        };
+        return capturedEvent(record, filename, byteOffset, mapped.eventType, item, mapped.callId);
     }
     return {
         kind: "gap",

package/dist/service.d.ts

@@ -1,4 +1,5 @@
+import type { CollectorSource } from "iteration-trace-contracts";
 import { type CollectorPaths } from "./storage.js";
 export declare function acquireCollectorLock(paths: CollectorPaths): Promise<() => Promise<void>>;
 export declare function waitForCollectorLock(paths: CollectorPaths): Promise<() => Promise<void>>;
-export declare function runCollector(directory?: string): Promise<void>;
+export declare function runCollector(directory?: string, expectedSource?: CollectorSource): Promise<void>;

package/dist/service.js

@@ -1,8 +1,8 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { collectorTick } from "./collector.js";
-import { collectorPaths, ensureHistoryBackfill, ensurePrivateDirectory, loadConfig, } from "./storage.js";
+import { collectorTick, TraceUploadError } from "./collector.js";
+import { collectorSource, collectorPaths, ensureClaudeHistoryBackfill, ensureHistoryBackfill, ensurePrivateDirectory, healthSnapshot, loadConfig, saveHealth, } from "./storage.js";
 function errorCode(error) {
     if (error instanceof Error && "code" in error)
         return String(error.code);
@@ -10,6 +10,25 @@ function errorCode(error) {
 }
 class CollectorLockBusyError extends Error {
 }
+function collectorFailure(error) {
+    return {
+        atMs: Date.now(),
+        kind: error instanceof TraceUploadError ? error.kind : "collector",
+        status: error instanceof TraceUploadError ? error.status : null,
+    };
+}
+async function persistHealth(health, paths) {
+    try {
+        await saveHealth(health, paths);
+    }
+    catch {
+        console.error(JSON.stringify({
+            level: "warning",
+            operation: "save_collector_health",
+            message: "Local collector status could not be saved; collection continues.",
+        }));
+    }
+}
 export async function acquireCollectorLock(paths) {
     await ensurePrivateDirectory(path.dirname(paths.lock));
     for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -38,7 +57,7 @@ export async function acquireCollectorLock(paths) {
             }
             try {
                 process.kill(lockPid, 0);
-                throw new CollectorLockBusyError("Codex collector is already running.");
+                throw new CollectorLockBusyError("Collector is already running.");
             }
             catch (processError) {
                 if (errorCode(processError) !== "ESRCH")
@@ -47,7 +66,7 @@ export async function acquireCollectorLock(paths) {
             }
         }
     }
-    throw new Error("Could not obtain the Codex collector lock.");
+    throw new Error("Could not obtain the collector lock.");
 }
 export async function waitForCollectorLock(paths) {
     for (let attempt = 0; attempt < 81; attempt += 1) {
@@ -65,7 +84,7 @@ export async function waitForCollectorLock(paths) {
     }
     throw new Error("Could not obtain the collector lock.");
 }
-export async function runCollector(directory) {
+export async function runCollector(directory, expectedSource) {
     const paths = collectorPaths(directory);
     const releaseLock = await acquireCollectorLock(paths);
     const controller = new AbortController();
@@ -75,13 +94,44 @@ export async function runCollector(directory) {
     let retryDelayMs = 5000;
     try {
         const config = await loadConfig(paths);
-        await ensureHistoryBackfill(config.codexHome, paths);
+        const source = collectorSource(config);
+        if (expectedSource !== undefined && expectedSource !== source) {
+            throw new Error(`Collector directory belongs to ${source}, not ${expectedSource}.`);
+        }
+        const loadedHealth = await healthSnapshot(paths);
+        let health = loadedHealth.health;
+        if (loadedHealth.kind === "unavailable") {
+            console.error(JSON.stringify({
+                level: "warning",
+                operation: "load_collector_health",
+                message: "Local collector status could not be read; collection continues.",
+            }));
+        }
+        if ("claudeHome" in config)
+            await ensureClaudeHistoryBackfill(config.claudeHome, paths);
+        else
+            await ensureHistoryBackfill(config.codexHome, paths);
         while (!controller.signal.aborted) {
+            let acknowledgedAtMs = null;
             try {
-                const result = await collectorTick(config, paths, fetch, controller.signal);
+                const result = await collectorTick(config, paths, fetch, controller.signal, () => {
+                    acknowledgedAtMs = Date.now();
+                });
+                if (acknowledgedAtMs !== null ||
+                    health.lastFailure !== null ||
+                    (result.historyCaughtUp && health.historyCaughtUpAtMs === null)) {
+                    health = {
+                        lastUploadAtMs: acknowledgedAtMs ?? health.lastUploadAtMs,
+                        historyCaughtUpAtMs: health.historyCaughtUpAtMs ??
+                            (result.historyCaughtUp ? Date.now() : null),
+                        lastFailure: null,
+                    };
+                    await persistHealth(health, paths);
+                }
                 if (result.discovered > 0 || result.uploaded > 0) {
                     console.info(JSON.stringify({
                         level: "info",
+                        source,
                         discovered: result.discovered,
                         uploaded: result.uploaded,
                         outboxBytes: result.outboxBytes,
@@ -92,14 +142,21 @@ export async function runCollector(directory) {
             catch (error) {
                 if (controller.signal.aborted)
                     break;
+                health = {
+                    lastUploadAtMs: acknowledgedAtMs ?? health.lastUploadAtMs,
+                    historyCaughtUpAtMs: health.historyCaughtUpAtMs,
+                    lastFailure: collectorFailure(error),
+                };
                 console.error(JSON.stringify({
                     level: "error",
+                    source,
                     operation: "collector_tick",
                     errorName: error instanceof Error ? error.name : "UnknownError",
                     message: error instanceof Error
                         ? error.message
                         : "Unknown collector failure.",
                 }));
+                await persistHealth(health, paths);
                 retryDelayMs = Math.min(retryDelayMs * 2, 60_000);
             }
             try {

package/dist/status-view.d.ts

@@ -0,0 +1,30 @@
+import { type CollectorSource } from "iteration-trace-contracts";
+import type { CollectorHealth } from "./storage.js";
+type ScanProgress = Readonly<{
+    kind: "waiting";
+} | {
+    kind: "scanning";
+    scannedBytes: number;
+    totalBytes: number;
+}>;
+export type CliStatus = Readonly<{
+    kind: "not_connected";
+}> | Readonly<{
+    kind: "needs_repair";
+    pendingBytes: number;
+    configPath: string;
+}> | Readonly<{
+    kind: "connected";
+    workspaceName: string | null;
+    running: boolean;
+    scan: ScanProgress;
+    pendingEvents: number;
+    pendingBytes: number;
+    health: CollectorHealth;
+    healthAvailable: boolean;
+    tracesUrl: string;
+    logPath: string;
+}>;
+export declare function renderHome(status: CliStatus, nowMs?: number, source?: CollectorSource): string;
+export declare function renderDetailedStatus(status: CliStatus, nowMs?: number, source?: CollectorSource): string;
+export {};