iteration-cli 0.4.2 → 0.4.4

package/README.md

@@ -7,7 +7,7 @@ npm install --global iteration-cli
 iteration
 ```
 
-The Codex collector currently runs on macOS with Node.js 22 or later. Connecting imports existing local Codex sessions and collects new activity. Run `iteration status` to check uploads, or `iteration help` for other commands.
+The Codex collector currently runs on macOS with Node.js 22 or later. Connecting imports existing local Codex sessions and collects new activity. Run `iteration` to see whether collection and uploads are healthy, `iteration status` for details, or `iteration help` for other commands.
 
 If you previously installed the Codex-specific package, remove it with the package manager you used:
 

package/dist/cli.js

@@ -7,8 +7,9 @@ import * as z from "zod";
 import { authenticateAndEnrollCollector } from "./clerk-device-auth.js";
 import { importCodexHistory } from "./history-import.js";
 import { runCollector } from "./service.js";
+import { renderDetailedStatus, renderHome, } from "./status-view.js";
 import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
-import { assertFreshCollectorDirectory, collectorPaths, ensureStartableState, historyScanProgress, loadConfig, outboxSize, pendingEventIds, prepareInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
+import { assertFreshCollectorDirectory, collectorPaths, ensureStartableState, healthSnapshot, historyScanProgress, loadConfig, outboxSize, pendingEventIds, prepareInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
 const DEFAULT_INGEST_ENDPOINT = "https://useiteration.com/api/traces/ingest";
 function argumentsForCli() {
     const parsed = parseArgs({
@@ -66,34 +67,34 @@ function usage(command) {
         "Iteration CLI",
         "",
         "Get started:",
-        "  iteration                 Connect Codex, or show connection status",
+        "  iteration                 Connect Codex, or see its current activity",
         "",
         "Commands:",
         "  iteration connect codex   Connect Codex directly",
-        "  iteration status          Check uploads and connection",
+        "  iteration status          See scan, upload, and error details",
         "  iteration disconnect codex      Stop collecting",
         "",
         "Run iteration connect codex --help for advanced setup options.",
     ].join("\n") + "\n");
 }
-async function configured(paths) {
+async function fileExists(filename) {
     try {
-        await fs.access(paths.config);
+        await fs.access(filename);
         return true;
     }
     catch (error) {
         if (error instanceof Error && "code" in error && error.code === "ENOENT") {
             return false;
         }
-        throw new Error(`Could not inspect collector config at ${paths.config}.`, {
+        throw new Error(`Could not inspect collector file at ${filename}.`, {
             cause: error,
         });
     }
 }
 async function defaultCommand() {
-    const paths = collectorPaths(dataDirectory({}));
-    if (await configured(paths)) {
-        await status({});
+    const snapshot = await statusSnapshot({});
+    if (snapshot.kind !== "not_connected") {
+        process.stdout.write(`${renderHome(snapshot)}\n`);
         return;
     }
     if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
@@ -127,6 +128,7 @@ async function initialize(values) {
         token: enrollment.token,
         codexHome,
         dataDirectory: directory,
+        organizationName: enrollment.organizationName,
     };
     await saveConfig(config, paths);
     try {
@@ -141,7 +143,7 @@ async function initialize(values) {
     catch (error) {
         throw new Error("Collector access was approved, but background startup failed. Run iteration start codex to retry it.", { cause: error });
     }
-    process.stdout.write(`Codex connected to ${enrollment.organizationName}. Existing local sessions and new activity will upload in the background. Run iteration status to check uploads.\n`);
+    process.stdout.write(`Codex is connected to ${enrollment.organizationName}. Existing sessions are importing and new activity is collected automatically. Run iteration to check progress.\n`);
 }
 async function importHistory(values) {
     if (process.platform !== "darwin") {
@@ -168,33 +170,46 @@ async function start(values) {
     const config = await loadConfig(paths);
     const repairedState = await ensureStartableState(config, paths);
     await installLaunchAgent(directory);
-    process.stdout.write(`Collector started. Existing local sessions and new activity will upload in the background. Run iteration status to check uploads.${repairedState ? " Incomplete setup was repaired." : ""}\n`);
+    process.stdout.write(`Codex is collecting again. Run iteration to check progress.${repairedState ? " Incomplete setup was repaired." : ""}\n`);
 }
-async function status(values) {
+async function statusSnapshot(values) {
     const paths = collectorPaths(dataDirectory(values));
-    if (!(await configured(paths))) {
-        process.stdout.write("Installed: false\nRunning: false\nPending events: 0\n");
-        return;
+    if (!(await fileExists(paths.config))) {
+        const [stateExists, pendingBytes] = await Promise.all([
+            fileExists(paths.state),
+            outboxSize(paths),
+        ]);
+        if (stateExists || pendingBytes > 0) {
+            return { kind: "needs_repair", pendingBytes, configPath: paths.config };
+        }
+        return { kind: "not_connected" };
     }
     const config = await loadConfig(paths);
-    const running = await launchAgentStatus();
-    const [size, ids, scan] = await Promise.all([
+    const [running, size, ids, scan, localHealth] = await Promise.all([
+        launchAgentStatus(),
         outboxSize(paths),
         pendingEventIds(paths),
         historyScanProgress(config.codexHome, paths),
+        healthSnapshot(paths),
     ]);
-    const scanLabel = scan.kind === "waiting"
-        ? "Local history: waiting for collector start"
-        : scan.totalBytes === 0
-            ? "Local scan: no session data found"
-            : `Local scan: ${scan.scannedBytes} of ${scan.totalBytes} bytes processed`;
-    process.stdout.write([
-        "Installed: true",
-        `Running: ${running}`,
-        scanLabel,
-        `Pending events: ${ids.size}`,
-        `Pending bytes: ${size}`,
-    ].join("\n") + "\n");
+    const pendingEvents = size === 0 ? 0 : ids.size;
+    const pendingBytes = ids.size === 0 ? 0 : size;
+    return {
+        kind: "connected",
+        workspaceName: config.organizationName ?? null,
+        running,
+        scan,
+        pendingEvents,
+        pendingBytes,
+        health: localHealth.health,
+        healthAvailable: localHealth.kind === "available",
+        tracesUrl: new URL("/app/sessions", config.endpoint).toString(),
+        logPath: path.join(os.homedir(), "Library", "Logs", "iteration-codex-collector.error.log"),
+    };
+}
+async function status(values) {
+    const snapshot = await statusSnapshot(values);
+    process.stdout.write(`${renderDetailedStatus(snapshot)}\n`);
 }
 async function main() {
     const { command, source, values } = argumentsForCli();

package/dist/collector.d.ts

@@ -1,7 +1,16 @@
 import { type CollectorConfig, type CollectorPaths } from "./storage.js";
-export declare function scanRolloutsOnce(config: CollectorConfig, paths: CollectorPaths, signal?: AbortSignal): Promise<number>;
-export declare function collectorTick(config: CollectorConfig, paths: CollectorPaths, fetcher?: typeof fetch, signal?: AbortSignal): Promise<Readonly<{
+export declare class TraceUploadError extends Error {
+    readonly kind: "http" | "network" | "response";
+    readonly status: number | null;
+    constructor(kind: "http" | "network" | "response", status: number | null, message: string, options?: ErrorOptions);
+}
+export declare function scanRolloutsOnce(config: CollectorConfig, paths: CollectorPaths, signal?: AbortSignal): Promise<Readonly<{
+    discovered: number;
+    caughtUp: boolean;
+}>>;
+export declare function collectorTick(config: CollectorConfig, paths: CollectorPaths, fetcher?: typeof fetch, signal?: AbortSignal, onAcknowledged?: () => void): Promise<Readonly<{
     discovered: number;
     uploaded: number;
     outboxBytes: number;
+    historyCaughtUp: boolean;
 }>>;

package/dist/collector.js

@@ -11,6 +11,16 @@ const MAX_EVENT_BYTES = MAX_UPLOAD_BYTES - 1024;
 const MAX_UPLOADS_PER_TICK = 5;
 const MAX_REQUEST_BYTES = 4 * 1024 * 1024;
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+export class TraceUploadError extends Error {
+    kind;
+    status;
+    constructor(kind, status, message, options) {
+        super(message, options);
+        this.name = "TraceUploadError";
+        this.kind = kind;
+        this.status = status;
+    }
+}
 function logGap(filename, offset, reason) {
     console.error(JSON.stringify({
         level: "capture_gap",
@@ -32,10 +42,13 @@ export async function scanRolloutsOnce(config, paths, signal) {
     const queuedIds = await pendingEventIds(paths);
     const events = [];
     let remainingBudget = MAX_SCAN_BYTES_PER_TICK;
+    let caughtUp = true;
     for (const filename of files) {
         signal?.throwIfAborted();
-        if (remainingBudget === 0)
+        if (remainingBudget === 0) {
+            caughtUp = false;
             break;
+        }
         const stats = await fs.stat(filename);
         let offset = cursors[filename] ?? 0;
         if (offset > stats.size) {
@@ -50,15 +63,19 @@ export async function scanRolloutsOnce(config, paths, signal) {
         }
         const handle = await fs.open(filename, "r");
         let buffer;
+        let readEnd = offset;
         try {
             buffer = Buffer.alloc(bytesToRead);
             const result = await handle.read(buffer, 0, bytesToRead, offset);
             buffer = buffer.subarray(0, result.bytesRead);
+            readEnd = offset + result.bytesRead;
             remainingBudget -= result.bytesRead;
         }
         finally {
             await handle.close();
         }
+        if (readEnd < stats.size)
+            caughtUp = false;
         if (skipping.has(filename)) {
             const newline = buffer.indexOf(10);
             if (newline < 0) {
@@ -120,9 +137,9 @@ export async function scanRolloutsOnce(config, paths, signal) {
         sourceDirectory: state.sourceDirectory,
         initialized: true,
     }, paths);
-    return events.length;
+    return { discovered: events.length, caughtUp };
 }
-async function uploadPendingOnce(config, paths, fetcher = fetch, signal) {
+async function uploadPendingOnce(config, paths, fetcher = fetch, signal, onAcknowledged) {
     let uploaded = 0;
     for (let attempt = 0; attempt < MAX_UPLOADS_PER_TICK; attempt += 1) {
         signal?.throwIfAborted();
@@ -133,41 +150,54 @@ async function uploadPendingOnce(config, paths, fetcher = fetch, signal) {
         if (Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
             throw new Error("Queued trace batch exceeds the upload request limit.");
         }
-        const response = await fetcher(config.endpoint, {
-            method: "POST",
-            headers: {
-                authorization: `Bearer ${config.token}`,
-                "content-type": "application/json",
-            },
-            body,
-            signal: signal
-                ? AbortSignal.any([signal, AbortSignal.timeout(15_000)])
-                : AbortSignal.timeout(15_000),
-        });
+        let response;
+        try {
+            response = await fetcher(config.endpoint, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${config.token}`,
+                    "content-type": "application/json",
+                },
+                body,
+                signal: signal
+                    ? AbortSignal.any([signal, AbortSignal.timeout(15_000)])
+                    : AbortSignal.timeout(15_000),
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            throw new TraceUploadError("network", null, "Trace upload could not reach Iteration.", { cause: error });
+        }
         if (response.status !== 202) {
-            throw new Error(`Trace upload failed with HTTP ${response.status}.`);
+            throw new TraceUploadError("http", response.status, `Trace upload failed with HTTP ${response.status}.`);
         }
         let acknowledgement;
         try {
             acknowledgement = await response.json();
         }
         catch (error) {
-            throw new Error("Trace upload returned an unreadable acknowledgement.", {
-                cause: error,
-            });
+            throw new TraceUploadError("response", null, "Trace upload returned an unreadable acknowledgement.", { cause: error });
         }
         const expectedIds = batch.map((event) => event.eventId);
         const parsed = parseTraceEventAcknowledgement(acknowledgement, expectedIds);
-        if (!parsed.success)
-            throw new Error(parsed.error);
+        if (!parsed.success) {
+            throw new TraceUploadError("response", null, parsed.error);
+        }
         await acknowledgeEvents(new Set(parsed.value.acceptedEventIds), paths);
+        onAcknowledged?.();
         uploaded += batch.length;
     }
     return uploaded;
 }
-export async function collectorTick(config, paths, fetcher = fetch, signal) {
-    let uploaded = await uploadPendingOnce(config, paths, fetcher, signal);
-    const discovered = await scanRolloutsOnce(config, paths, signal);
-    uploaded += await uploadPendingOnce(config, paths, fetcher, signal);
-    return { discovered, uploaded, outboxBytes: await outboxSize(paths) };
+export async function collectorTick(config, paths, fetcher = fetch, signal, onAcknowledged) {
+    let uploaded = await uploadPendingOnce(config, paths, fetcher, signal, onAcknowledged);
+    const scan = await scanRolloutsOnce(config, paths, signal);
+    uploaded += await uploadPendingOnce(config, paths, fetcher, signal, onAcknowledged);
+    return {
+        discovered: scan.discovered,
+        uploaded,
+        outboxBytes: await outboxSize(paths),
+        historyCaughtUp: scan.caughtUp,
+    };
 }

package/dist/launch-agent.d.ts

@@ -1,4 +1,11 @@
+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 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>;

package/dist/launch-agent.js

@@ -3,9 +3,13 @@ import { execFile as execFileCallback } from "node:child_process";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 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";
+const LAUNCHCTL_TIMEOUT_MS = 5_000;
+const RESTART_TIMEOUT_MS = 10_000;
+const RESTART_POLL_MS = 200;
 function xml(value) {
     return value
         .replaceAll("&", "&")
@@ -52,18 +56,73 @@ function launchctlTarget() {
         throw new Error("Could not determine the current macOS user id.");
     return `gui/${userId}`;
 }
-async function bootoutIfLoaded(target) {
+function serviceMissing(error) {
+    const details = error;
+    return (String(details.code) === "113" ||
+        details.stderr?.includes("Could not find service") === true);
+}
+async function serviceLoaded(target, timeoutMs = LAUNCHCTL_TIMEOUT_MS) {
     try {
-        await execFile("launchctl", ["print", `${target}/${LABEL}`]);
+        await execFile("launchctl", ["print", `${target}/${LABEL}`], {
+            timeout: timeoutMs,
+        });
+        return true;
     }
     catch (error) {
-        const details = error;
-        if (String(details.code) === "113" ||
-            details.stderr?.includes("Could not find service"))
-            return;
+        if (serviceMissing(error))
+            return false;
         throw error;
     }
-    await execFile("launchctl", ["bootout", `${target}/${LABEL}`]);
+}
+async function bootoutIfLoaded(target) {
+    if (!(await serviceLoaded(target)))
+        return false;
+    await execFile("launchctl", ["bootout", `${target}/${LABEL}`], {
+        timeout: LAUNCHCTL_TIMEOUT_MS,
+    });
+    return true;
+}
+function transientBootstrapFailure(error) {
+    const details = error;
+    return (String(details.code) === "5" ||
+        /^Bootstrap failed:\s*5\b/m.test(details.stderr ?? ""));
+}
+function restartTimeoutError(lastBootstrapFailure) {
+    return new Error(lastBootstrapFailure === undefined
+        ? "The previous Codex collector did not stop within 10 seconds."
+        : "launchctl bootstrap still failed with error 5 after 10 seconds.", { cause: lastBootstrapFailure });
+}
+export async function bootstrapAfterBootout(wasLoaded, control) {
+    if (!wasLoaded) {
+        await control.bootstrap(LAUNCHCTL_TIMEOUT_MS);
+        return;
+    }
+    const deadline = control.now() + RESTART_TIMEOUT_MS;
+    let lastBootstrapFailure;
+    while (true) {
+        let remaining = deadline - control.now();
+        if (remaining <= 0) {
+            throw restartTimeoutError(lastBootstrapFailure);
+        }
+        if (!(await control.isLoaded(Math.min(remaining, LAUNCHCTL_TIMEOUT_MS)))) {
+            remaining = deadline - control.now();
+            if (remaining <= 0)
+                continue;
+            try {
+                await control.bootstrap(Math.min(remaining, LAUNCHCTL_TIMEOUT_MS));
+                return;
+            }
+            catch (error) {
+                if (!transientBootstrapFailure(error))
+                    throw error;
+                lastBootstrapFailure = error;
+            }
+        }
+        remaining = deadline - control.now();
+        if (remaining > 0) {
+            await control.wait(Math.min(remaining, RESTART_POLL_MS));
+        }
+    }
 }
 export async function installLaunchAgent(dataDirectory) {
     if (process.platform !== "darwin") {
@@ -77,9 +136,20 @@ export async function installLaunchAgent(dataDirectory) {
     await fs.writeFile(file, launchAgentPlist(undefined, undefined, undefined, dataDirectory ??
         path.join(os.homedir(), ".config", "iteration", "codex-collector")), { encoding: "utf8", mode: 0o644 });
     const target = launchctlTarget();
-    await bootoutIfLoaded(target);
-    await execFile("launchctl", ["bootstrap", target, file]);
-    await execFile("launchctl", ["kickstart", "-p", `${target}/${LABEL}`]);
+    const wasLoaded = await bootoutIfLoaded(target);
+    await bootstrapAfterBootout(wasLoaded, {
+        isLoaded: (timeoutMs) => serviceLoaded(target, timeoutMs),
+        bootstrap: async (timeoutMs) => {
+            await execFile("launchctl", ["bootstrap", target, file], {
+                timeout: timeoutMs,
+            });
+        },
+        wait: sleep,
+        now: Date.now,
+    });
+    await execFile("launchctl", ["kickstart", "-p", `${target}/${LABEL}`], {
+        timeout: LAUNCHCTL_TIMEOUT_MS,
+    });
     return file;
 }
 export async function uninstallLaunchAgent() {

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 { collectorPaths, 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) {
@@ -75,10 +94,33 @@ export async function runCollector(directory) {
     let retryDelayMs = 5000;
     try {
         const config = await loadConfig(paths);
+        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.",
+            }));
+        }
         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",
@@ -92,6 +134,11 @@ 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",
                     operation: "collector_tick",
@@ -100,6 +147,7 @@ export async function runCollector(directory) {
                         ? 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,29 @@
+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): string;
+export declare function renderDetailedStatus(status: CliStatus, nowMs?: number): string;
+export {};

package/dist/status-view.js

@@ -0,0 +1,239 @@
+function safeWorkspaceName(value) {
+    const cleaned = value
+        ?.split("")
+        .map((character) => {
+        const code = character.charCodeAt(0);
+        return code < 32 || (code >= 127 && code <= 159) ? " " : character;
+    })
+        .join("")
+        .replace(/\s+/g, " ")
+        .trim();
+    return cleaned === undefined || cleaned === "" ? null : cleaned;
+}
+function readableBytes(bytes) {
+    if (bytes < 1_000)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let amount = bytes;
+    let index = -1;
+    do {
+        amount /= 1_000;
+        index += 1;
+    } while (amount >= 1_000 && index < units.length - 1);
+    const precision = amount < 10 ? 1 : 0;
+    return `${amount.toFixed(precision).replace(/\.0$/, "")} ${units[index]}`;
+}
+function relativeTime(atMs, nowMs) {
+    const elapsedSeconds = Math.max(0, Math.floor((nowMs - atMs) / 1_000));
+    if (elapsedSeconds < 5)
+        return "just now";
+    if (elapsedSeconds < 60)
+        return `${elapsedSeconds} second${elapsedSeconds === 1 ? "" : "s"} ago`;
+    const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+    if (elapsedMinutes < 60)
+        return `${elapsedMinutes} minute${elapsedMinutes === 1 ? "" : "s"} ago`;
+    const elapsedHours = Math.floor(elapsedMinutes / 60);
+    if (elapsedHours < 24)
+        return `${elapsedHours} hour${elapsedHours === 1 ? "" : "s"} ago`;
+    const elapsedDays = Math.floor(elapsedHours / 24);
+    return `${elapsedDays} day${elapsedDays === 1 ? "" : "s"} ago`;
+}
+function pendingDescription(status) {
+    return `${status.pendingEvents} event${status.pendingEvents === 1 ? "" : "s"} (${readableBytes(status.pendingBytes)}) waiting on this Mac`;
+}
+function progressDescription(scan) {
+    if (scan.kind === "waiting")
+        return "Local history is preparing to scan.";
+    if (scan.totalBytes === 0)
+        return "No local Codex sessions found yet.";
+    if (scan.scannedBytes >= scan.totalBytes)
+        return `Local history scanned (${readableBytes(scan.totalBytes)}).`;
+    const remainingBytes = scan.totalBytes - scan.scannedBytes;
+    if (remainingBytes < 1_000_000)
+        return "Local scan is nearly caught up (less than 1 MB remains).";
+    const percentage = Math.min(99, Math.floor((scan.scannedBytes / scan.totalBytes) * 100));
+    return `About ${percentage}% of local history scanned (${readableBytes(scan.scannedBytes)} of ${readableBytes(scan.totalBytes)}).`;
+}
+function historyDescription(status) {
+    if (status.health.historyCaughtUpAtMs === null) {
+        return progressDescription(status.scan);
+    }
+    if (status.scan.kind === "waiting")
+        return "History is preparing to scan.";
+    const remainingBytes = status.scan.totalBytes - status.scan.scannedBytes;
+    if (remainingBytes <= 0)
+        return "History imported; local files are caught up.";
+    if (remainingBytes < 1_000_000)
+        return "History imported; scanning current activity.";
+    return `History imported; ${readableBytes(remainingBytes)} of new activity waiting to scan.`;
+}
+function failureDescription(status) {
+    const failure = status.health.lastFailure;
+    if (failure === null) {
+        throw new Error("A collector failure is required to describe it.");
+    }
+    if (failure.kind === "http") {
+        const code = failure.status === null ? "HTTP error" : `HTTP ${failure.status}`;
+        if (failure.status === 401 || failure.status === 403) {
+            return {
+                heading: "Codex upload access needs attention",
+                explanation: `Iteration denied this collector (${code}). Queued data stays on this Mac. Contact Iteration support to reconnect it safely.`,
+            };
+        }
+        if (failure.status !== null &&
+            failure.status < 500 &&
+            failure.status !== 429) {
+            return {
+                heading: "Codex uploads need attention",
+                explanation: `Iteration rejected an event batch (${code}). Check the collector log for details.`,
+            };
+        }
+        return {
+            heading: "Codex uploads are delayed",
+            explanation: `Iteration could not accept an upload (${code}). Retrying automatically.`,
+        };
+    }
+    if (failure.kind === "network") {
+        return {
+            heading: "Codex uploads are delayed",
+            explanation: "Could not reach Iteration. Retrying automatically.",
+        };
+    }
+    if (failure.kind === "response") {
+        return {
+            heading: "Codex uploads need attention",
+            explanation: "Iteration returned an unexpected upload response. Retrying automatically.",
+        };
+    }
+    return {
+        heading: "Codex collector needs attention",
+        explanation: "A local error interrupted collection. See iteration status codex for details.",
+    };
+}
+export function renderHome(status, nowMs = Date.now()) {
+    if (status.kind === "not_connected") {
+        return [
+            "Iteration",
+            "",
+            "Codex is not connected.",
+            "Run iteration connect codex to import your existing sessions.",
+        ].join("\n");
+    }
+    if (status.kind === "needs_repair") {
+        return [
+            "Iteration",
+            "",
+            "Codex connection needs repair",
+            "Local collector data exists, but its connection details are missing.",
+            status.pendingBytes > 0
+                ? `${readableBytes(status.pendingBytes)} of queued data remains on this Mac.`
+                : "Existing local progress remains on this Mac.",
+            "Run iteration status codex for recovery details.",
+        ].join("\n");
+    }
+    const workspaceName = safeWorkspaceName(status.workspaceName);
+    const lines = [
+        workspaceName === null ? "Iteration" : `Iteration · ${workspaceName}`,
+        "",
+    ];
+    if (!status.running) {
+        lines.push("Codex is stopped", "New sessions are not being collected.");
+        if (status.pendingEvents > 0)
+            lines.push(`${pendingDescription(status)}.`);
+        lines.push("Resume with iteration start codex.");
+    }
+    else if (!status.healthAvailable) {
+        lines.push("Codex is running; local status needs attention", "Upload history could not be read. Collection continues in the background.");
+        if (status.pendingEvents > 0)
+            lines.push(`${pendingDescription(status)}.`);
+        lines.push("Details: iteration status codex");
+    }
+    else if (status.health.lastFailure !== null) {
+        const failure = failureDescription(status);
+        lines.push(failure.heading, failure.explanation);
+        if (status.pendingEvents > 0)
+            lines.push(`${pendingDescription(status)}.`);
+        if (status.health.lastUploadAtMs !== null) {
+            lines.push(`Last successful upload ${relativeTime(status.health.lastUploadAtMs, nowMs)}.`);
+        }
+        lines.push("Details: iteration status codex");
+    }
+    else if (status.scan.kind === "waiting") {
+        lines.push("Codex is preparing your history", progressDescription(status.scan));
+    }
+    else if (status.scan.kind === "scanning" &&
+        status.scan.totalBytes > 0 &&
+        status.scan.scannedBytes < status.scan.totalBytes &&
+        status.health.historyCaughtUpAtMs === null) {
+        lines.push("Codex is importing existing sessions", historyDescription(status), "New activity is collected automatically.");
+    }
+    else if (status.scan.kind === "scanning" &&
+        status.scan.totalBytes - status.scan.scannedBytes >= 1_000_000) {
+        lines.push("Codex is catching up with new activity", historyDescription(status));
+        if (status.pendingEvents > 0)
+            lines.push(`${pendingDescription(status)}.`);
+    }
+    else if (status.pendingEvents > 0) {
+        lines.push("Codex is uploading captured sessions", `${pendingDescription(status)}.`);
+    }
+    else if (status.scan.totalBytes === 0) {
+        lines.push("Codex is connected", "Waiting for Codex sessions on this Mac.");
+    }
+    else if (status.scan.kind === "scanning" &&
+        status.scan.scannedBytes < status.scan.totalBytes) {
+        lines.push("Codex is collecting new activity", "Local history is imported; current activity is being scanned.");
+    }
+    else {
+        lines.push("Codex is collecting", "Local scan is caught up and no uploads are waiting.", "New activity is collected automatically.");
+    }
+    if (status.running &&
+        status.health.lastFailure === null &&
+        status.health.lastUploadAtMs !== null) {
+        lines.push(`Last successful upload ${relativeTime(status.health.lastUploadAtMs, nowMs)}.`);
+    }
+    lines.push("", `Explore traces  ${status.tracesUrl}`);
+    return lines.join("\n");
+}
+export function renderDetailedStatus(status, nowMs = Date.now()) {
+    if (status.kind === "not_connected") {
+        return "Codex is not connected. Run iteration connect codex to connect.";
+    }
+    if (status.kind === "needs_repair") {
+        return [
+            "Codex connection needs repair",
+            "Local collector data exists without its connection details.",
+            `Queued data: ${readableBytes(status.pendingBytes)}`,
+            `Restore the missing config from backup: ${status.configPath}`,
+            "If you do not have it, contact Iteration support before reconnecting; existing data has been kept.",
+        ].join("\n");
+    }
+    const workspaceName = safeWorkspaceName(status.workspaceName);
+    const lines = [
+        "Codex collector",
+        ...(workspaceName === null ? [] : [`Workspace: ${workspaceName}`]),
+        `Background process: ${status.running ? "Running" : "Stopped"}`,
+        `History: ${historyDescription(status).replace(/^History /, "")}`,
+        `Uploads: ${status.pendingEvents === 0 ? "None waiting" : pendingDescription(status)}`,
+    ];
+    if (!status.healthAvailable) {
+        lines.push("Local status: unavailable; check collector file permissions", `Collector log: ${status.logPath}`);
+    }
+    if (status.health.lastUploadAtMs !== null) {
+        lines.push(`Last successful upload: ${relativeTime(status.health.lastUploadAtMs, nowMs)}`);
+    }
+    if (status.health.lastFailure !== null) {
+        const failure = status.health.lastFailure;
+        const label = failure.kind === "http" && failure.status !== null
+            ? `HTTP ${failure.status}`
+            : failure.kind === "network"
+                ? "Network unavailable"
+                : failure.kind === "response"
+                    ? "Unexpected upload response"
+                    : "Local collector error";
+        lines.push(`Last issue: ${label} (${relativeTime(failure.atMs, nowMs)})`, `Collector log: ${status.logPath}`);
+    }
+    if (!status.running)
+        lines.push("Resume: iteration start codex");
+    lines.push(`Explore traces: ${status.tracesUrl}`);
+    return lines.join("\n");
+}

package/dist/storage.d.ts

@@ -4,6 +4,7 @@ export type CollectorConfig = Readonly<{
     token: string;
     codexHome: string;
     dataDirectory: string;
+    organizationName?: string;
 }>;
 export type CollectorState = Readonly<{
     cursors: Readonly<Record<string, number>>;
@@ -11,18 +12,39 @@ export type CollectorState = Readonly<{
     sourceDirectory: string | null;
     initialized: boolean;
 }>;
+export type CollectorFailure = Readonly<{
+    atMs: number;
+    kind: "http" | "network" | "response" | "collector";
+    status: number | null;
+}>;
+export type CollectorHealth = Readonly<{
+    lastUploadAtMs: number | null;
+    historyCaughtUpAtMs: number | null;
+    lastFailure: CollectorFailure | null;
+}>;
+export type HealthSnapshot = Readonly<{
+    kind: "available";
+    health: CollectorHealth;
+} | {
+    kind: "unavailable";
+    health: CollectorHealth;
+}>;
 export type CollectorPaths = Readonly<{
     config: string;
     state: string;
     outbox: string;
     lock: string;
     historyBackfill: string;
+    health: string;
 }>;
 export declare function validateCollectorEndpoint(endpoint: string): URL;
 export declare function collectorPaths(directory?: string): CollectorPaths;
 export declare function assertFreshCollectorDirectory(paths: CollectorPaths): Promise<void>;
 export declare function ensurePrivateDirectory(directory: string): Promise<void>;
 export declare function saveConfig(config: CollectorConfig, paths: CollectorPaths): Promise<void>;
+export declare function loadHealth(paths: CollectorPaths): Promise<CollectorHealth>;
+export declare function healthSnapshot(paths: CollectorPaths): Promise<HealthSnapshot>;
+export declare function saveHealth(health: CollectorHealth, paths: CollectorPaths): Promise<void>;
 export declare function loadConfig(paths: CollectorPaths): Promise<CollectorConfig>;
 export declare function loadState(paths: CollectorPaths): Promise<CollectorState>;
 export declare function saveState(state: CollectorState, paths: CollectorPaths): Promise<void>;

package/dist/storage.js

@@ -12,6 +12,7 @@ const configSchema = z
     token: z.string(),
     codexHome: z.string(),
     dataDirectory: z.string(),
+    organizationName: z.string().min(1).max(160).optional(),
 })
     .strict();
 const stateSchema = z
@@ -22,6 +23,20 @@ const stateSchema = z
     initialized: z.boolean(),
 })
     .strict();
+const healthSchema = z
+    .object({
+    lastUploadAtMs: z.number().int().min(0).nullable(),
+    historyCaughtUpAtMs: z.number().int().min(0).nullable(),
+    lastFailure: z
+        .object({
+        atMs: z.number().int().min(0),
+        kind: z.enum(["http", "network", "response", "collector"]),
+        status: z.number().int().min(100).max(599).nullable(),
+    })
+        .strict()
+        .nullable(),
+})
+    .strict();
 function parseOutboxEvent(line) {
     let decoded;
     try {
@@ -74,6 +89,7 @@ export function collectorPaths(directory = defaultDirectory()) {
         outbox: path.join(directory, "outbox.jsonl"),
         lock: path.join(directory, "collector.lock"),
         historyBackfill: path.join(directory, "history-backfill.json"),
+        health: path.join(directory, "health.json"),
     };
 }
 export async function assertFreshCollectorDirectory(paths) {
@@ -113,6 +129,57 @@ export async function saveConfig(config, paths) {
     await ensurePrivateDirectory(path.dirname(paths.config));
     await writeJsonAtomic(paths.config, config);
 }
+export async function loadHealth(paths) {
+    let contents;
+    try {
+        contents = await fs.readFile(paths.health, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return {
+                lastUploadAtMs: null,
+                historyCaughtUpAtMs: null,
+                lastFailure: null,
+            };
+        }
+        throw new Error(`Could not read collector health at ${paths.health}.`, {
+            cause: error,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error("Collector health is not valid JSON.", { cause: error });
+    }
+    const parsed = healthSchema.safeParse(decoded);
+    if (!parsed.success) {
+        throw new Error("Collector health has an invalid shape.", {
+            cause: parsed.error,
+        });
+    }
+    return parsed.data;
+}
+export async function healthSnapshot(paths) {
+    try {
+        return { kind: "available", health: await loadHealth(paths) };
+    }
+    catch {
+        return {
+            kind: "unavailable",
+            health: {
+                lastUploadAtMs: null,
+                historyCaughtUpAtMs: null,
+                lastFailure: null,
+            },
+        };
+    }
+}
+export async function saveHealth(health, paths) {
+    await ensurePrivateDirectory(path.dirname(paths.health));
+    await writeJsonAtomic(paths.health, health);
+}
 export async function loadConfig(paths) {
     let contents;
     try {
@@ -135,12 +202,12 @@ export async function loadConfig(paths) {
         throw new Error("Collector config has an invalid shape.", {
             cause: parsed.error,
         });
-    const { endpoint, token, codexHome, dataDirectory } = parsed.data;
+    const { endpoint, token, codexHome, dataDirectory, organizationName } = parsed.data;
     validateCollectorEndpoint(endpoint);
     if (token.length !== 43 || !/^[A-Za-z0-9_-]+$/.test(token)) {
         throw new Error("Collector token has an invalid format.");
     }
-    return { endpoint, token, codexHome, dataDirectory };
+    return { endpoint, token, codexHome, dataDirectory, organizationName };
 }
 export async function loadState(paths) {
     let contents;
@@ -437,6 +504,11 @@ export async function resetHistoryCursors(codexHome, paths) {
             throw new Error("Codex history size exceeds the supported limit.");
         }
     }
+    const localHealth = await healthSnapshot(paths);
+    if (localHealth.kind === "unavailable" ||
+        localHealth.health.historyCaughtUpAtMs !== null) {
+        await saveHealth({ ...localHealth.health, historyCaughtUpAtMs: null }, paths);
+    }
     await saveState({
         cursors,
         skipping: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "repository": {
     "type": "git",