iteration-cli 0.12.0 → 0.13.0

package/README.md

@@ -1,13 +1,19 @@
 # Iteration CLI
 
-Install one CLI for Iteration's supported coding-agent sources:
+Connect a computer with the command shown on your Iteration workspace's overview:
+
+```sh
+npx iteration-cli connect --workspace <workspace ID>
+```
+
+`--workspace` connects to that workspace without a prompt. The collectors keep running from their own copy of the CLI, so the command does not need a global install. To keep the `iteration` command for status and later changes, install it globally:
 
 ```sh
 npm install --global iteration-cli
 iteration connect
 ```
 
-The collectors run on macOS or Linux with Node.js 22 or later. Cursor's local Agents window collector is tested on macOS. Linux needs systemd. The CLI automatically enables background collection after logout and installs a user service that starts at boot and restarts on failure. If server policy does not let the user enable this, an administrator must allow background services for the account. The setting applies to the whole Linux account and remains enabled after `iteration disconnect`; the CLI does not turn off other user services. `iteration connect` finds supported agents with local session directories, asks once before uploading their saved sessions and future activity, and connects them to one workspace. A connected collector checks for newly detected supported agents and connects them under that approval. Each source has its own background process, local checkpoint, and upload queue. Run `iteration` to see connected sources, `iteration status cursor` for Cursor details, and `iteration help` for other commands. Source-specific connect commands remain available for advanced setups.
+The collectors run on macOS or Linux with Node.js 22 or later. Cursor's local Agents window collector is tested on macOS. Linux needs systemd. The CLI automatically enables background collection after logout and installs a user service that starts at boot and restarts on failure. If server policy does not let the user enable this, an administrator must allow background services for the account. The setting applies to the whole Linux account and remains enabled after `iteration disconnect`; the CLI does not turn off other user services. `iteration connect` finds supported agents with local session directories, shows how many saved sessions each one has, asks once before uploading them and future activity, and connects them to one workspace. Saved sessions import newest first, and each collector reports its import progress to Iteration until it completes. A connected collector checks for newly detected supported agents and connects them under that approval. Each source has its own background process, local checkpoint, and upload queue. Run `iteration` to see connected sources, `iteration status cursor` for Cursor details, and `iteration help` for other commands. Source-specific connect commands remain available for advanced setups.
 
 Cursor's **This Mac** Agents sessions are read from `~/.cursor/projects/*/agent-transcripts/<conversation>/<conversation>.jsonl`. Connecting Cursor also installs user-level hooks in `~/.cursor/hooks.json` automatically. They capture tool output, thought blocks, model and usage fields, subagent transcripts, and other lifecycle records that the main transcript omits; the collector queues those records locally before upload. Existing hooks are preserved, and `iteration disconnect cursor` removes only Iteration's entries. No Cursor approval or settings step is needed. A custom Cursor directory can be selected with `iteration connect cursor --cursor-home DIR`. Local history predating connection has transcript messages and tool calls, but tool results that Cursor never wrote to its transcript cannot be recovered. Cloud Agents are outside this local collector.
 

package/dist/cli.js

@@ -7633,6 +7633,12 @@ var acknowledgementSchema = object({
 }).strict();
 var episodeCountSchema = number2().int().min(0).max(Number.MAX_SAFE_INTEGER);
 var collectorFrictionSummarySchema = object({ weekEpisodes: episodeCountSchema, dayEpisodes: episodeCountSchema }).strict().refine((summary) => summary.dayEpisodes <= summary.weekEpisodes, "The last day cannot have more friction episodes than the last week.");
+var sessionCountSchema = number2().int().min(0).max(1e6);
+var collectorHistoryProgressSchema = object({
+  sessions: sessionCountSchema,
+  readSessions: sessionCountSchema,
+  complete: boolean2()
+}).strict().refine((progress) => progress.readSessions <= progress.sessions, "Read sessions cannot exceed listed sessions.").refine((progress) => !progress.complete || progress.readSessions === progress.sessions, "A complete import has read every listed session.");
 var collectorEnrollmentRequestSchema = object({
   deviceName: string2().trim().min(1).max(160),
   organizationId: string2().regex(UUID_PATTERN).optional(),
@@ -7933,7 +7939,7 @@ async function clerkDeviceSignIn(configuration) {
   );
   const verificationUrl = challenge.verification_uri_complete ?? challenge.verification_uri;
   process.stdout.write(
-    "Sign in to Iteration to authorize this collector.\nCode: " + challenge.user_code + "\nLink: " + verificationUrl + "\n"
+    "Sign in to Iteration in your browser and confirm this code.\nCode: " + challenge.user_code + "\nLink: " + verificationUrl + "\n"
   );
   await openBrowser(verificationUrl);
   return pollForAccessToken(
@@ -7981,7 +7987,7 @@ async function chooseOrganization(organizations, hasMore) {
     );
   }
   if (process.stdin.isTTY !== true) {
-    throw new Error("Run iteration interactively or pass --organization-id.");
+    throw new Error("Run iteration interactively or pass --workspace.");
   }
   const prompt = createInterface({
     input: process.stdin,
@@ -15081,6 +15087,38 @@ async function claudeFiles(root) {
   }
   return files.sort();
 }
+function isSessionFile(filename) {
+  return !filename.includes(`${path8.sep}subagents${path8.sep}`);
+}
+async function countSavedSessions(source, home) {
+  return (await sourceFiles(source, home)).filter(isSessionFile).length;
+}
+async function sourceFilesNewestFirst(source, home) {
+  const files = await sourceFiles(source, home);
+  const listed = [];
+  for (let start2 = 0; start2 < files.length; start2 += 64) {
+    const batch = files.slice(start2, start2 + 64);
+    const stats = await Promise.all(batch.map((filename) => fs8.stat(filename)));
+    for (const [index, stat] of stats.entries()) {
+      const filename = batch[index];
+      if (filename === void 0) continue;
+      listed.push({
+        filename,
+        size: stat.size,
+        modifiedMs: stat.mtimeMs,
+        session: isSessionFile(filename)
+      });
+    }
+  }
+  listed.sort(
+    (left, right) => right.modifiedMs - left.modifiedMs || left.filename.localeCompare(right.filename)
+  );
+  return listed.map(({ filename, size, session }) => ({
+    filename,
+    size,
+    session
+  }));
+}
 function sourceFiles(source, home) {
   const directory = path8.resolve(home);
   if (source === "codex") return rolloutFiles(path8.join(directory, "sessions"));
@@ -17021,9 +17059,13 @@ async function scanSourceOnce(config2, paths, signal) {
   }
   const cursors = { ...state.cursors };
   const skipping = new Set(state.skipping);
+  const sessionFiles = await sourceFilesNewestFirst(source, sourceDirectory);
+  const listedSizes = new Map(
+    sessionFiles.map((file) => [file.filename, file.size])
+  );
   const files = [
     ...source === "claude" ? await claudeGitHookFiles(config2.dataDirectory) : [],
-    ...await sourceFiles(source, sourceDirectory),
+    ...sessionFiles.map((file) => file.filename),
     ...source === "cursor" ? await cursorHookFiles(config2.dataDirectory) : []
   ];
   const completedHooks = [];
@@ -17039,15 +17081,15 @@ async function scanSourceOnce(config2, paths, signal) {
       caughtUp = false;
       break;
     }
-    const stats = await fs13.stat(filename);
+    const size = listedSizes.get(filename) ?? (await fs13.stat(filename)).size;
     let offset = cursors[filename] ?? 0;
-    if (offset > stats.size) {
+    if (offset > size) {
       logGap(filename, offset, "rollout_file_shrank_resetting_cursor");
       offset = 0;
       skipping.delete(filename);
     }
     const bytesToRead = Math.min(
-      stats.size - offset,
+      size - offset,
       MAX_SCAN_BYTES_PER_FILE,
       remainingBudget
     );
@@ -17067,7 +17109,7 @@ async function scanSourceOnce(config2, paths, signal) {
     } finally {
       await handle.close();
     }
-    if (readEnd < stats.size) caughtUp = false;
+    if (readEnd < size) caughtUp = false;
     if (skipping.has(filename)) {
       const newline = buffer.indexOf(10);
       if (newline < 0) {
@@ -17130,7 +17172,7 @@ async function scanSourceOnce(config2, paths, signal) {
       lineStart = buffer.length;
     }
     cursors[filename] = offset + lineStart;
-    if ((source === "cursor" && filename.includes(`${path16.sep}cursor-hooks${path16.sep}`) || source === "claude" && filename.includes(`${path16.sep}git-queue${path16.sep}`)) && cursors[filename] === stats.size)
+    if ((source === "cursor" && filename.includes(`${path16.sep}cursor-hooks${path16.sep}`) || source === "claude" && filename.includes(`${path16.sep}git-queue${path16.sep}`)) && cursors[filename] === size)
       completedHooks.push(filename);
   }
   await appendEvents(events, paths);
@@ -17147,7 +17189,17 @@ async function scanSourceOnce(config2, paths, signal) {
     },
     paths
   );
-  return { discovered: events.length, caughtUp };
+  const sessions = sessionFiles.filter((file) => file.session);
+  return {
+    discovered: events.length,
+    caughtUp,
+    history: {
+      sessions: sessions.length,
+      readSessions: sessions.filter(
+        (file) => (cursors[file.filename] ?? 0) >= file.size
+      ).length
+    }
+  };
 }
 async function uploadPendingOnce(config2, paths, fetcher = collectorFetch, signal, onAcknowledged) {
   let uploaded = 0;
@@ -17217,7 +17269,7 @@ async function collectorTick(config2, paths, fetcher = collectorFetch, signal, o
     signal,
     onAcknowledged
   );
-  const scan = await outboxSize(paths) >= SCAN_PAUSE_OUTBOX_BYTES ? { discovered: 0, caughtUp: false } : await scanSourceOnce(config2, paths, signal);
+  const scan = await outboxSize(paths) >= SCAN_PAUSE_OUTBOX_BYTES ? { discovered: 0, caughtUp: false, history: null } : await scanSourceOnce(config2, paths, signal);
   uploaded += await uploadPendingOnce(
     config2,
     paths,
@@ -17229,10 +17281,66 @@ async function collectorTick(config2, paths, fetcher = collectorFetch, signal, o
     discovered: scan.discovered,
     uploaded,
     outboxBytes: await outboxSize(paths),
-    historyCaughtUp: scan.caughtUp
+    historyCaughtUp: scan.caughtUp,
+    history: scan.history
   };
 }
 
+// src/history-progress.ts
+var REQUEST_TIMEOUT_MS3 = 15e3;
+var REPORT_INTERVAL_MS = 1e4;
+var HistoryProgressError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "HistoryProgressError";
+  }
+};
+function unchanged(left, right) {
+  return right !== null && left.sessions === right.sessions && left.readSessions === right.readSessions && left.complete === right.complete;
+}
+var HistoryProgressReporter = class {
+  #sent = null;
+  #sentAtMs = Number.NEGATIVE_INFINITY;
+  #completed = false;
+  async report(config2, progress, fetcher, signal, nowMs) {
+    if (this.#completed || unchanged(progress, this.#sent)) return;
+    if (!progress.complete && nowMs - this.#sentAtMs < REPORT_INTERVAL_MS)
+      return;
+    let response;
+    try {
+      response = await fetcher(
+        new URL("/api/traces/collector-progress", config2.endpoint),
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${config2.token}`,
+            "content-type": "application/json"
+          },
+          body: JSON.stringify(progress),
+          signal: AbortSignal.any([
+            signal,
+            AbortSignal.timeout(REQUEST_TIMEOUT_MS3)
+          ])
+        }
+      );
+    } catch (error2) {
+      if (signal.aborted) throw error2;
+      throw new HistoryProgressError(
+        "History progress could not reach Iteration.",
+        { cause: error2 }
+      );
+    }
+    if (response.status !== 204) {
+      throw new HistoryProgressError(
+        `History progress failed with HTTP ${response.status}.`
+      );
+    }
+    this.#sent = progress;
+    this.#sentAtMs = nowMs;
+    this.#completed = progress.complete;
+  }
+};
+
 // src/cursor-billing.ts
 import { createHash as createHash7 } from "node:crypto";
 import { promises as fs14 } from "node:fs";
@@ -18172,6 +18280,7 @@ async function runCollector(directory, expectedSource) {
     const summariesRefreshedAt = /* @__PURE__ */ new Map();
     let lastAutoCheckAt = 0;
     let lastBillingSyncAt = 0;
+    const historyProgress = new HistoryProgressReporter();
     const runtimeVersion = process.env.ITERATION_RUNTIME_VERSION;
     let lastRuntimeCheckAt = 0;
     let trialSettled = runtimeVersion === void 0;
@@ -18234,6 +18343,7 @@ async function runCollector(directory, expectedSource) {
       }
       let acknowledgedAtMs = null;
       let billingReady = false;
+      let history = null;
       try {
         const result = await collectorTick(
           config2,
@@ -18245,6 +18355,12 @@ async function runCollector(directory, expectedSource) {
           }
         );
         billingReady = result.historyCaughtUp && result.outboxBytes === 0;
+        if (result.history !== null) {
+          history = {
+            ...result.history,
+            complete: billingReady && result.history.readSessions === result.history.sessions
+          };
+        }
         if (acknowledgedAtMs !== null || health.lastFailure !== null || result.historyCaughtUp && health.historyCaughtUpAtMs === null) {
           health = {
             lastUploadAtMs: acknowledgedAtMs ?? health.lastUploadAtMs,
@@ -18297,6 +18413,30 @@ async function runCollector(directory, expectedSource) {
         await persistHealth(health, paths);
         retryDelayMs = Math.min(retryDelayMs * 2, 6e4);
       }
+      if (history !== null) {
+        try {
+          await historyProgress.report(
+            config2,
+            history,
+            collectorFetch,
+            controller.signal,
+            Date.now()
+          );
+        } catch (error2) {
+          if (controller.signal.aborted) break;
+          console.error(
+            JSON.stringify({
+              level: "warning",
+              at: (/* @__PURE__ */ new Date()).toISOString(),
+              source,
+              operation: "report_history_progress",
+              errorName: error2 instanceof Error ? error2.name : "UnknownError",
+              causes: errorCauses(error2),
+              message: error2 instanceof Error ? error2.message : "Unknown history progress failure."
+            })
+          );
+        }
+      }
       try {
         if (source !== "cursor")
           await refreshTurnSummaries(
@@ -18753,7 +18893,7 @@ function argumentsForCli() {
       help: { type: "boolean" },
       endpoint: { type: "string" },
       "device-name": { type: "string" },
-      "organization-id": { type: "string" },
+      workspace: { type: "string" },
       "codex-home": { type: "string" },
       "claude-home": { type: "string" },
       "cursor-home": { type: "string" },
@@ -18797,7 +18937,7 @@ function usage(command) {
         "",
         "Options for advanced setups:",
         "  --device-name NAME      Name this computer in Iteration",
-        "  --organization-id UUID  Select a workspace without a prompt",
+        "  --workspace ID          Connect to this workspace without a prompt",
         "  --codex-home DIR        Use a different Codex data directory",
         "  --claude-home DIR       Use a different Claude data directory",
         "  --cursor-home DIR       Use a different Cursor data directory",
@@ -18902,7 +19042,7 @@ async function initialize(source, values) {
   const endpoint = optionalString(values, "endpoint") ?? DEFAULT_INGEST_ENDPOINT;
   const endpointUrl = validateCollectorEndpoint(endpoint);
   const deviceName = optionalString(values, "device-name") ?? os8.hostname();
-  const organizationId = optionalString(values, "organization-id");
+  const organizationId = optionalString(values, "workspace");
   const directory = dataDirectory(source, values);
   const paths = collectorPaths(directory);
   const selectedHome = path21.resolve(
@@ -18949,13 +19089,15 @@ async function initialize(source, values) {
   }
   const notice = await turnSummaryNotice(config2);
   process.stdout.write(
-    `${collectorSourceLabel(source)} is connected to ${enrollment.organizationName}. Existing sessions are importing and new activity is collected automatically. Run iteration to check progress.${notice}
+    `${collectorSourceLabel(source)} is connected to ${enrollment.organizationName}. Existing sessions are importing, newest first, and new activity is collected automatically. Iteration shows the import as it runs.${notice}
 `
   );
   return config2;
 }
 async function approveAllSources(sources, workspaceName, yes) {
-  const names = sources.map(collectorSourceLabel).join(" and ");
+  const names = sources.map(
+    ({ source, sessions }) => `${collectorSourceLabel(source)} (${sessions.toLocaleString("en-US")} saved ${sessions === 1 ? "session" : "sessions"})`
+  ).join(" and ");
   const safeName = safeWorkspaceName(workspaceName);
   process.stdout.write(
     `Detected ${names || "no saved agent sessions"} on this computer.
@@ -19032,14 +19174,19 @@ async function connectAll(values) {
       );
     }
   }
-  const requestedOrganizationId = optionalString(values, "organization-id");
+  const requestedOrganizationId = optionalString(values, "workspace");
   if (requestedOrganizationId && existingScopes[0] && requestedOrganizationId !== existingScopes[0].scope.organizationId) {
     throw new Error("The existing collector belongs to a different workspace.");
   }
   const previousConsent = await loadMachineConsent();
   if (previousConsent === null || anchorExisting === null || previousConsent.endpoint !== endpoint || previousConsent.anchorSource !== anchorSource || previousConsent.anchorDataDirectory !== anchorExisting.dataDirectory || previousConsent.organizationId !== existingScopes[0]?.scope.organizationId || previousConsent.sourceHomes.codex !== sourceHomes.codex || previousConsent.sourceHomes.claude !== sourceHomes.claude || previousConsent.sourceHomes.cursor !== sourceHomes.cursor) {
     await approveAllSources(
-      detected,
+      await Promise.all(
+        detected.map(async (source) => ({
+          source,
+          sessions: await countSavedSessions(source, sourceHomes[source])
+        }))
+      ),
       existingScopes[0]?.scope.organizationName ?? null,
       values.yes === true
     );

package/dist/cursor-hook-entry.js

@@ -7435,6 +7435,12 @@ var acknowledgementSchema = object({
 }).strict();
 var episodeCountSchema = number2().int().min(0).max(Number.MAX_SAFE_INTEGER);
 var collectorFrictionSummarySchema = object({ weekEpisodes: episodeCountSchema, dayEpisodes: episodeCountSchema }).strict().refine((summary) => summary.dayEpisodes <= summary.weekEpisodes, "The last day cannot have more friction episodes than the last week.");
+var sessionCountSchema = number2().int().min(0).max(1e6);
+var collectorHistoryProgressSchema = object({
+  sessions: sessionCountSchema,
+  readSessions: sessionCountSchema,
+  complete: boolean2()
+}).strict().refine((progress) => progress.readSessions <= progress.sessions, "Read sessions cannot exceed listed sessions.").refine((progress) => !progress.complete || progress.readSessions === progress.sessions, "A complete import has read every listed session.");
 var collectorEnrollmentRequestSchema = object({
   deviceName: string2().trim().min(1).max(160),
   organizationId: string2().regex(UUID_PATTERN).optional(),

package/dist/launcher.js

@@ -6511,6 +6511,12 @@ var acknowledgementSchema = object({
 }).strict();
 var episodeCountSchema = number2().int().min(0).max(Number.MAX_SAFE_INTEGER);
 var collectorFrictionSummarySchema = object({ weekEpisodes: episodeCountSchema, dayEpisodes: episodeCountSchema }).strict().refine((summary) => summary.dayEpisodes <= summary.weekEpisodes, "The last day cannot have more friction episodes than the last week.");
+var sessionCountSchema = number2().int().min(0).max(1e6);
+var collectorHistoryProgressSchema = object({
+  sessions: sessionCountSchema,
+  readSessions: sessionCountSchema,
+  complete: boolean2()
+}).strict().refine((progress) => progress.readSessions <= progress.sessions, "Read sessions cannot exceed listed sessions.").refine((progress) => !progress.complete || progress.readSessions === progress.sessions, "A complete import has read every listed session.");
 var collectorEnrollmentRequestSchema = object({
   deviceName: string2().trim().min(1).max(160),
   organizationId: string2().regex(UUID_PATTERN).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
     "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
     "esbuild": "0.28.2",
     "zod": "4.6.4",
-    "iteration-trace-contracts": "0.9.0"
+    "iteration-trace-contracts": "0.10.0"
   },
   "scripts": {
     "build": "pnpm --filter iteration-trace-contracts build && tsc -p tsconfig.json --noEmit && node build.mjs"