iteration-cli 0.8.0 → 0.9.0

package/README.md

@@ -11,6 +11,8 @@ The collectors run on macOS or Linux with Node.js 22 or later. Cursor's local Ag
 
 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.
 
+The collector replaces detected secrets with `[REDACTED]` before writing trace events to the upload outbox. It also redacts pending events left by an older collector before uploading them. This applies to Codex, Claude Code, and Cursor, including Cursor subagent transcript bytes stored as base64. Detection is best effort; original local agent files and previously uploaded traces are unchanged.
+
 Claude Code sessions are read from `~/.claude/projects`, including session subagents. If Claude uses `CLAUDE_CONFIG_DIR`, the collector follows that setting during connection; `iteration connect claude --claude-home DIR` selects another directory explicitly. The collector reads only saved local JSONL records. Claude Code may remove old transcripts under its own retention settings, so connect before local history is removed. The records can contain prompts, reasoning, tool input and output, and context snapshots; workspace members can read what uploads. Unknown record shapes are reported as capture gaps in the collector log. Remote Claude sessions are outside this local collector.
 
 Connecting Codex or Claude Code also adds a Stop hook to the coding agent. After an agent turn in a git repository where you had friction episodes this week, it shows one line such as `◆ Iteration · 3 friction episodes in this repo this week · 1 new since yesterday`. The hook reads local files only and adds a few milliseconds to a turn. Codex asks you to approve it once with `/hooks`. `iteration disconnect` removes it.

package/dist/claude-transcript.js

@@ -14,6 +14,7 @@ const CONTEXT_RECORD_TYPES = new Set([
     "file-history-delta",
     "cost-state",
     "queue-operation",
+    "pr-link",
 ]);
 function object(value) {
     const parsed = z.record(z.string(), z.json()).safeParse(value);

package/dist/collector.js

@@ -5,8 +5,9 @@ import { collectorFetch } from "./collector-fetch.js";
 import { parseClaudeLine } from "./claude-transcript.js";
 import { cursorHookFiles } from "./cursor-hooks.js";
 import { parseCursorHookLine, parseCursorTranscriptLine, } from "./cursor-transcript.js";
+import { redactTraceEvent } from "./redact-trace.js";
 import { parseRolloutLine } from "./rollout.js";
-import { acknowledgeEvents, appendEvents, collectorSource, collectorSourceDirectory, loadState, nextBatch, outboxSize, pendingEventIds, sourceFiles, saveState, } from "./storage.js";
+import { acknowledgeEvents, appendEvents, collectorSource, collectorSourceDirectory, loadState, nextBatch, outboxSize, pendingEventIds, redactPendingOutbox, sourceFiles, saveState, } from "./storage.js";
 const MAX_SCAN_BYTES_PER_FILE = 16 * 1024 * 1024;
 const MAX_SCAN_BYTES_PER_TICK = 16 * 1024 * 1024;
 const MAX_RECORD_BYTES = 3 * 1024 * 1024;
@@ -152,13 +153,14 @@ export async function scanSourceOnce(config, paths, signal) {
             for (const parsedEvent of parsed.events) {
                 if (queuedIds.has(parsedEvent.eventId))
                     continue;
-                const eventBytes = Buffer.byteLength(JSON.stringify(parsedEvent), "utf8");
+                const event = await redactTraceEvent(parsedEvent);
+                const eventBytes = Buffer.byteLength(JSON.stringify(event), "utf8");
                 if (eventBytes > MAX_EVENT_BYTES) {
                     logGap(filename, byteOffset, "normalized_event_exceeds_upload_limit");
                 }
                 else {
-                    events.push(parsedEvent);
-                    queuedIds.add(parsedEvent.eventId);
+                    events.push(event);
+                    queuedIds.add(event.eventId);
                 }
             }
             lineStart = index + 1;
@@ -239,6 +241,7 @@ async function uploadPendingOnce(config, paths, fetcher = collectorFetch, signal
     return uploaded;
 }
 export async function collectorTick(config, paths, fetcher = collectorFetch, signal, onAcknowledged) {
+    await redactPendingOutbox(paths);
     let uploaded = await uploadPendingOnce(config, paths, fetcher, signal, onAcknowledged);
     const scan = (await outboxSize(paths)) >= SCAN_PAUSE_OUTBOX_BYTES
         ? { discovered: 0, caughtUp: false }

package/dist/redact-trace.d.ts

@@ -0,0 +1,2 @@
+import type { TraceEvent } from "iteration-trace-contracts";
+export declare function redactTraceEvent(event: TraceEvent): Promise<TraceEvent>;

package/dist/redact-trace.js

@@ -0,0 +1,182 @@
+import { lintSource } from "@secretlint/core";
+import { rules as recommendedRules } from "@secretlint/secretlint-rule-preset-recommend";
+import * as z from "zod";
+const REDACTED = "[REDACTED]";
+const secretlintConfig = {
+    rules: recommendedRules
+        .filter((rule) => rule.meta.id !== "@secretlint/secretlint-rule-filter-comments")
+        .map((rule) => ({ id: rule.meta.id, rule })),
+};
+const assignment = /\b([A-Za-z][A-Za-z0-9_-]{0,79})["']?\s*[:=]\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s"'`,;}&]+))/g;
+const authorization = /\b(?:authorization|proxy-authorization)["']?\s*:\s*["']?(?:Bearer|Basic)\s+([A-Za-z0-9._~+/-]+={0,2})/gi;
+const privateKey = /-----BEGIN ((?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY)-----[\s\S]*?-----END \1-----/g;
+function normalizedKey(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .toLowerCase();
+}
+function sensitiveKey(key) {
+    const normalized = normalizedKey(key);
+    if (/^(?:next_public|public|vite|react_app)_/.test(normalized))
+        return false;
+    return (/(?:^|_)(?:secret|password|passwd|credential)(?:_|$)/.test(normalized) ||
+        /(?:^|_)(?:api_key|private_key|database_url|db_url|dsn|connection_string|authorization|proxy_authorization|auth_header|cookie|set_cookie|token)$/.test(normalized));
+}
+function placeholder(value) {
+    const trimmed = value.trim();
+    return (trimmed === REDACTED ||
+        /^(?:<[^>]+>|\$\{[^}]+\}|\*+|redacted|placeholder|example|changeme|undefined|null)$/i.test(trimmed) ||
+        /^(?:process\.env|env)\.[A-Za-z0-9_]+$/.test(trimmed));
+}
+function addRange(ranges, start, end, length) {
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        start < 0 ||
+        end > length ||
+        start >= end) {
+        throw new Error("Local trace secret scanner returned an invalid location.");
+    }
+    ranges.push({ start, end });
+}
+function textRanges(value) {
+    const ranges = [];
+    for (const match of value.matchAll(assignment)) {
+        const key = match[1];
+        const candidate = match[2] ?? match[3] ?? match[4];
+        if (key === undefined ||
+            candidate === undefined ||
+            candidate.length === 0 ||
+            !sensitiveKey(key) ||
+            placeholder(candidate) ||
+            ((normalizedKey(key) === "authorization" ||
+                normalizedKey(key) === "proxy_authorization") &&
+                /^(?:Bearer|Basic)$/i.test(candidate)))
+            continue;
+        const start = match.index + match[0].lastIndexOf(candidate);
+        addRange(ranges, start, start + candidate.length, value.length);
+    }
+    for (const match of value.matchAll(authorization)) {
+        const candidate = match[1];
+        if (candidate === undefined || placeholder(candidate))
+            continue;
+        const start = match.index + match[0].lastIndexOf(candidate);
+        addRange(ranges, start, start + candidate.length, value.length);
+    }
+    for (const match of value.matchAll(privateKey)) {
+        addRange(ranges, match.index, match.index + match[0].length, value.length);
+    }
+    return ranges;
+}
+function replaceRanges(value, ranges) {
+    if (ranges.length === 0)
+        return value;
+    ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [];
+    for (const range of ranges) {
+        const previous = merged.at(-1);
+        if (previous !== undefined && range.start <= previous.end) {
+            merged[merged.length - 1] = {
+                start: previous.start,
+                end: Math.max(previous.end, range.end),
+            };
+        }
+        else
+            merged.push(range);
+    }
+    let result = value;
+    for (let index = merged.length - 1; index >= 0; index -= 1) {
+        const range = merged[index];
+        if (range === undefined)
+            continue;
+        result = `${result.slice(0, range.start)}${REDACTED}${result.slice(range.end)}`;
+    }
+    return result;
+}
+async function redactText(value) {
+    if (value.length === 0 || value === REDACTED)
+        return value;
+    const ranges = textRanges(value);
+    let result;
+    try {
+        result = await lintSource({
+            source: {
+                contentType: "text",
+                content: value,
+                filePath: "trace.txt",
+                ext: "txt",
+            },
+            options: {
+                maskSecrets: true,
+                noPhysicFilePath: true,
+                config: secretlintConfig,
+            },
+        });
+    }
+    catch {
+        throw new Error("Local trace secret scanning failed; the event was not queued.");
+    }
+    for (const message of result.messages) {
+        addRange(ranges, message.range[0], message.range[1], value.length);
+    }
+    return replaceRanges(value, ranges);
+}
+async function redactValue(value, cache, force) {
+    const parsedText = z.string().safeParse(value);
+    if (parsedText.success) {
+        const text = parsedText.data;
+        if (force)
+            return placeholder(text) ? text : REDACTED;
+        let result = cache.get(text);
+        if (result === undefined) {
+            result = redactText(text);
+            cache.set(text, result);
+        }
+        return result;
+    }
+    if (value === null || value === true || value === false)
+        return value;
+    const parsedNumber = z.number().safeParse(value);
+    if (parsedNumber.success)
+        return force ? REDACTED : parsedNumber.data;
+    if (Array.isArray(value)) {
+        const items = await Promise.all(value.map((item) => redactValue(item, cache, force)));
+        return items.every((item, index) => item === value[index]) ? value : items;
+    }
+    const record = value;
+    const entries = await Promise.all(Object.entries(record).map(async ([key, item]) => [
+        key,
+        await redactValue(item, cache, force || sensitiveKey(key)),
+    ]));
+    return entries.every(([key, item]) => item === record[key])
+        ? value
+        : Object.fromEntries(entries);
+}
+export async function redactTraceEvent(event) {
+    const cache = new Map();
+    if (event.payload.sourceType === "cursor_subagent_transcript") {
+        const parsed = z.string().safeParse(event.payload.base64);
+        if (!parsed.success)
+            throw new Error("Cursor transcript has invalid encoded content.");
+        const bytes = Buffer.from(parsed.data, "base64");
+        if (bytes.toString("base64") !== parsed.data)
+            throw new Error("Cursor transcript has invalid encoded content.");
+        const raw = bytes.toString("latin1");
+        const redacted = await redactText(raw);
+        const { base64: _encoded, ...remaining } = event.payload;
+        const payload = await redactValue(remaining, cache, false);
+        return {
+            ...event,
+            payload: {
+                ...payload,
+                base64: redacted === raw
+                    ? parsed.data
+                    : Buffer.from(redacted, "latin1").toString("base64"),
+            },
+        };
+    }
+    const payload = await redactValue(event.payload, cache, false);
+    return payload === event.payload
+        ? event
+        : { ...event, payload: payload };
+}

package/dist/storage.d.ts

@@ -44,6 +44,7 @@ export type CollectorPaths = Readonly<{
     config: string;
     state: string;
     outbox: string;
+    redactionMarker: string;
     lock: string;
     historyBackfill: string;
     health: string;
@@ -63,6 +64,7 @@ export declare function saveState(state: CollectorState, paths: CollectorPaths):
 export declare function outboxSize(paths: CollectorPaths): Promise<number>;
 export declare function pendingEventIds(paths: CollectorPaths): Promise<Set<string>>;
 export declare function appendEvents(events: readonly TraceEvent[], paths: CollectorPaths): Promise<void>;
+export declare function redactPendingOutbox(paths: CollectorPaths): Promise<void>;
 export declare function nextBatch(paths: CollectorPaths, maxBytes: number): Promise<readonly TraceEvent[]>;
 export declare function acknowledgeEvents(acknowledgedIds: ReadonlySet<string>, paths: CollectorPaths): Promise<void>;
 export declare function initializeState(source: CollectorSource, home: string, paths: CollectorPaths, includeHistory: boolean): Promise<void>;

package/dist/storage.js

@@ -1,10 +1,11 @@
 import { once } from "node:events";
-import { createWriteStream, promises as fs } from "node:fs";
+import { createReadStream, createWriteStream, promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
 import { MAX_TRACE_EVENTS_PER_BATCH, parseTraceEventBatch, } from "iteration-trace-contracts";
 import * as z from "zod";
+import { redactTraceEvent } from "./redact-trace.js";
 const MAX_OUTBOX_BYTES = 64 * 1024 * 1024;
 export function collectorSource(config) {
     return "cursorHome" in config
@@ -66,6 +67,7 @@ const healthSchema = z
         .nullable(),
 })
     .strict();
+const redactionMarkerSchema = z.object({ version: z.literal(1) }).strict();
 function parseOutboxEvent(line) {
     let decoded;
     try {
@@ -116,6 +118,7 @@ export function collectorPaths(directory = defaultCollectorDirectory("codex")) {
         config: path.join(directory, "config.json"),
         state: path.join(directory, "state.json"),
         outbox: path.join(directory, "outbox.jsonl"),
+        redactionMarker: path.join(directory, "redaction.json"),
         lock: path.join(directory, "collector.lock"),
         historyBackfill: path.join(directory, "history-backfill.json"),
         health: path.join(directory, "health.json"),
@@ -330,6 +333,72 @@ export async function appendEvents(events, paths) {
         await handle.close();
     }
 }
+export async function redactPendingOutbox(paths) {
+    let marker;
+    try {
+        marker = await fs.readFile(paths.redactionMarker, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            marker = null;
+        else
+            throw error;
+    }
+    if (marker !== null) {
+        let decoded;
+        try {
+            decoded = JSON.parse(marker);
+        }
+        catch {
+            throw new Error("Collector redaction marker is not valid JSON.");
+        }
+        if (!redactionMarkerSchema.safeParse(decoded).success)
+            throw new Error("Collector redaction marker has an invalid shape.");
+        return;
+    }
+    const size = await outboxSize(paths);
+    if (size > MAX_OUTBOX_BYTES)
+        throw new Error("Trace outbox exceeds its configured capacity.");
+    if (size > 0) {
+        const temporary = `${paths.outbox}.${process.pid}.redacting`;
+        const output = await fs.open(temporary, "w", 0o600);
+        try {
+            const lines = createInterface({
+                input: createReadStream(paths.outbox, { encoding: "utf8" }),
+                crlfDelay: Infinity,
+            });
+            for await (const line of lines) {
+                const event = await redactTraceEvent(parseOutboxEvent(line));
+                await output.writeFile(`${JSON.stringify(event)}\n`, "utf8");
+            }
+            await output.sync();
+        }
+        catch (error) {
+            await output.close();
+            await fs.rm(temporary, { force: true });
+            throw error;
+        }
+        await output.close();
+        try {
+            if ((await fs.stat(temporary)).size > MAX_OUTBOX_BYTES)
+                throw new Error("Redacted trace outbox exceeds its configured capacity.");
+            await fs.rename(temporary, paths.outbox);
+            const directory = await fs.open(path.dirname(paths.outbox), "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true });
+            throw error;
+        }
+    }
+    await ensurePrivateDirectory(path.dirname(paths.redactionMarker));
+    await writeJsonAtomic(paths.redactionMarker, { version: 1 });
+}
 export async function nextBatch(paths, maxBytes) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
         throw new Error("Maximum upload batch size must be a positive integer.");
@@ -493,9 +562,12 @@ export async function ensureHistoryBackfill(codexHome, paths) {
     });
     return true;
 }
+// Version 2 re-reads Claude history so stored sessions gain each response's
+// final usage report and the PR links Claude records.
+const CLAUDE_HISTORY_BACKFILL_VERSION = 2;
 export async function ensureClaudeHistoryBackfill(claudeHome, paths) {
     const version = await readHistoryBackfillVersion(paths);
-    if (version !== null && version >= 1)
+    if (version !== null && version >= CLAUDE_HISTORY_BACKFILL_VERSION)
         return false;
     const state = await loadState(paths);
     if (!state.initialized ||
@@ -504,7 +576,9 @@ export async function ensureClaudeHistoryBackfill(claudeHome, paths) {
     }
     await claudeFiles(path.join(claudeHome, "projects"));
     await saveState({ ...state, cursors: {}, skipping: [] }, paths);
-    await writeJsonAtomic(paths.historyBackfill, { version: 1 });
+    await writeJsonAtomic(paths.historyBackfill, {
+        version: CLAUDE_HISTORY_BACKFILL_VERSION,
+    });
     return true;
 }
 export async function ensureCursorHistoryBackfill(cursorHome, paths) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,6 +17,8 @@
     "iteration": "./dist/cli.js"
   },
   "dependencies": {
+    "@secretlint/core": "13.0.6",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
     "zod": "4.6.4",
     "iteration-trace-contracts": "0.7.0"
   },