iteration-cli 0.5.0 → 0.6.0

package/README.md

@@ -4,14 +4,15 @@ Install one CLI for Iteration's supported coding-agent sources:
 
 ```sh
 npm install --global iteration-cli
-iteration connect codex
-iteration connect claude
+iteration connect
 ```
 
-The collectors currently run on macOS with Node.js 22 or later. Connect either source or both on the same Mac. Each source has its own background process, local checkpoint, and upload queue. Connecting imports existing local sessions and collects new activity. Run `iteration` to see connected sources, `iteration status codex` or `iteration status claude` for details, and `iteration help` for other commands.
+The collectors currently run on macOS with Node.js 22 or later. `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 codex` or `iteration status claude` for details, and `iteration help` for other commands. `iteration connect codex` and `iteration connect claude` remain available for advanced source-specific setups.
 
 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 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.
+
 To rescan older local sessions, preview with `iteration import-history claude`, then confirm with `iteration import-history claude --yes`. Use `iteration start claude` to restart collection and `iteration disconnect claude` to stop its background process without deleting local pending data.
 
 If you previously installed the Codex-specific package, remove it with the package manager you used:

package/dist/auto-connect.d.ts

@@ -0,0 +1,30 @@
+import { type CollectorSource } from "iteration-trace-contracts";
+import { type CollectorConfig, type CollectorState } from "./storage.js";
+export type MachineConsent = Readonly<{
+    version: 1;
+    endpoint: string;
+    organizationId: string;
+    anchorSource: CollectorSource;
+    anchorDataDirectory: string;
+    sourceHomes: Readonly<{
+        codex: string;
+        claude: string;
+    }>;
+}>;
+export declare function sourceHome(source: CollectorSource): string;
+export declare function detectedSources(sourceHomes: MachineConsent["sourceHomes"]): Promise<CollectorSource[]>;
+export declare function loadMachineConsent(): Promise<MachineConsent | null>;
+export declare function saveMachineConsent(consent: MachineConsent): Promise<void>;
+export type SourceEnrollment = Readonly<{
+    token: string;
+    organizationId: string;
+    organizationName: string;
+}>;
+export declare function readCollectorScope(anchor: CollectorConfig): Promise<Readonly<{
+    organizationId: string;
+    organizationName: string;
+}>>;
+export declare function expandSource(anchor: CollectorConfig, source: CollectorSource, organizationId: string | null, request?: typeof fetch): Promise<SourceEnrollment>;
+export declare function activateSource(source: CollectorSource, home: string, endpoint: string, enrollment: SourceEnrollment, state: CollectorState): Promise<CollectorConfig>;
+export declare function connectNewDetectedSources(anchor: CollectorConfig, consent: MachineConsent): Promise<CollectorSource[]>;
+export declare function connectedConfig(source: CollectorSource): Promise<CollectorConfig | null>;

package/dist/auto-connect.js

@@ -0,0 +1,220 @@
+import { promises as fs } from "node:fs";
+import { createHmac } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import * as z from "zod";
+import { COLLECTOR_SOURCES, parseCollectorEnrollmentResponse, } from "iteration-trace-contracts";
+import { installLaunchAgent } from "./launch-agent.js";
+import { installTurnSummary } from "./turn-summary.js";
+import { assertFreshCollectorDirectory, collectorPaths, defaultCollectorDirectory, ensurePrivateDirectory, loadConfig, prepareSourceInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
+const consentSchema = z
+    .object({
+    version: z.literal(1),
+    endpoint: z.url(),
+    organizationId: z.uuid(),
+    anchorSource: z.enum(COLLECTOR_SOURCES),
+    anchorDataDirectory: z.string(),
+    sourceHomes: z.object({ codex: z.string(), claude: z.string() }).strict(),
+})
+    .strict();
+function consentPath() {
+    return path.join(os.homedir(), ".config", "iteration", "auto-connect.json");
+}
+export function sourceHome(source) {
+    return path.resolve(source === "codex"
+        ? (process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex"))
+        : (process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude")));
+}
+export async function detectedSources(sourceHomes) {
+    const detected = [];
+    for (const source of COLLECTOR_SOURCES) {
+        const directory = path.join(sourceHomes[source], source === "codex" ? "sessions" : "projects");
+        let stats;
+        try {
+            stats = await fs.stat(directory);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                continue;
+            throw new Error(`Could not inspect ${source} sessions at ${directory}.`, {
+                cause: error,
+            });
+        }
+        if (!stats.isDirectory()) {
+            throw new Error(`${source} session path is not a directory: ${directory}.`);
+        }
+        detected.push(source);
+    }
+    return detected;
+}
+export async function loadMachineConsent() {
+    let text;
+    try {
+        text = await fs.readFile(consentPath(), "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw new Error("Could not read automatic source connection settings.", {
+            cause: error,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error("Automatic source connection settings are invalid.", {
+            cause: error,
+        });
+    }
+    const parsed = consentSchema.safeParse(decoded);
+    if (!parsed.success)
+        throw new Error("Automatic source connection settings are invalid.");
+    validateCollectorEndpoint(parsed.data.endpoint);
+    return parsed.data;
+}
+export async function saveMachineConsent(consent) {
+    const parsed = consentSchema.parse(consent);
+    validateCollectorEndpoint(parsed.endpoint);
+    const filename = consentPath();
+    await ensurePrivateDirectory(path.dirname(filename));
+    const temporary = `${filename}.${process.pid}.tmp`;
+    const handle = await fs.open(temporary, "w", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(parsed)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(temporary, filename);
+}
+export async function readCollectorScope(anchor) {
+    const endpoint = validateCollectorEndpoint(anchor.endpoint);
+    const response = await fetch(new URL("./collector-auth/expand", endpoint), {
+        headers: { Authorization: `Bearer ${anchor.token}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    const payload = await response.json();
+    if (!response.ok) {
+        const error = z.object({ error: z.string() }).safeParse(payload);
+        throw new Error(`Could not identify the collector workspace: ${error.success ? error.data.error : `HTTP ${response.status}`}`);
+    }
+    const parsed = z
+        .object({ organizationId: z.uuid(), organizationName: z.string().min(1) })
+        .strict()
+        .safeParse(payload);
+    if (!parsed.success)
+        throw new Error("Iteration returned an invalid collector workspace.");
+    return parsed.data;
+}
+export async function expandSource(anchor, source, organizationId, request = fetch) {
+    const endpoint = validateCollectorEndpoint(anchor.endpoint);
+    const token = createHmac("sha256", anchor.token)
+        .update(`iteration-source:${source}`, "utf8")
+        .digest("base64url");
+    const response = await request(new URL("./collector-auth/expand", endpoint), {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${anchor.token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            source,
+            token,
+            ...(organizationId === null ? {} : { organizationId }),
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const payload = await response.json();
+    if (!response.ok) {
+        const error = z.object({ error: z.string() }).safeParse(payload);
+        throw new Error(`Could not connect ${source}: ${error.success ? error.data.error : `HTTP ${response.status}`}`);
+    }
+    const parsed = parseCollectorEnrollmentResponse(payload);
+    if (!parsed.success || parsed.value.status !== "enrolled") {
+        throw new Error(`Iteration returned an invalid ${source} connection response.`);
+    }
+    if (organizationId !== null &&
+        parsed.value.organizationId !== organizationId) {
+        throw new Error(`Iteration connected ${source} to an unexpected workspace.`);
+    }
+    return parsed.value;
+}
+export async function activateSource(source, home, endpoint, enrollment, state) {
+    const directory = defaultCollectorDirectory(source);
+    const paths = collectorPaths(directory);
+    await assertFreshCollectorDirectory(paths, source);
+    const common = {
+        endpoint,
+        token: enrollment.token,
+        dataDirectory: directory,
+        organizationId: enrollment.organizationId,
+        organizationName: enrollment.organizationName,
+    };
+    const config = source === "codex"
+        ? { ...common, codexHome: home }
+        : { ...common, source: "claude", claudeHome: home };
+    await saveConfig(config, paths);
+    try {
+        await saveState(state, paths);
+        await installLaunchAgent(directory, source);
+    }
+    catch (error) {
+        throw new Error(`${source} was connected, but local startup failed. Run iteration start ${source} to repair it.`, { cause: error });
+    }
+    return config;
+}
+export async function connectNewDetectedSources(anchor, consent) {
+    if (anchor.dataDirectory !== consent.anchorDataDirectory ||
+        anchor.endpoint !== consent.endpoint) {
+        throw new Error("Automatic connection settings do not match the running collector.");
+    }
+    const detected = await detectedSources(consent.sourceHomes);
+    const connected = [];
+    for (const source of detected) {
+        if (source === consent.anchorSource)
+            continue;
+        const paths = collectorPaths(defaultCollectorDirectory(source));
+        try {
+            await fs.access(paths.config);
+            continue;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        await assertFreshCollectorDirectory(paths, source);
+        const state = await prepareSourceInitialState(source, consent.sourceHomes[source], true);
+        const enrollment = await expandSource(anchor, source, consent.organizationId);
+        const config = await activateSource(source, consent.sourceHomes[source], consent.endpoint, enrollment, state);
+        connected.push(source);
+        try {
+            await installTurnSummary(config);
+        }
+        catch (error) {
+            console.error(JSON.stringify({
+                level: "warning",
+                source,
+                operation: "install_turn_summary",
+                message: error instanceof Error
+                    ? error.message
+                    : "The turn summary could not be installed.",
+            }));
+        }
+    }
+    return connected;
+}
+export async function connectedConfig(source) {
+    const paths = collectorPaths(defaultCollectorDirectory(source));
+    try {
+        await fs.access(paths.config);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return loadConfig(paths);
+}

package/dist/clerk-device-auth.d.ts

@@ -2,5 +2,6 @@ import { type CollectorSource } from "iteration-trace-contracts";
 export declare function authenticateAndEnrollCollector(endpoint: URL, deviceNameValue: string, organizationId: string | null, source?: CollectorSource): Promise<Readonly<{
     token: string;
     deviceId: string;
+    organizationId: string;
     organizationName: string;
 }>>;

package/dist/clerk-device-auth.js

@@ -273,6 +273,7 @@ export async function authenticateAndEnrollCollector(endpoint, deviceNameValue,
     return {
         token: result.token,
         deviceId: result.deviceId,
+        organizationId: result.organizationId,
         organizationName: result.organizationName,
     };
 }

package/dist/cli.js

@@ -2,13 +2,16 @@
 import os from "node:os";
 import path from "node:path";
 import { promises as fs } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import * as z from "zod";
-import { collectorSourceLabel, } from "iteration-trace-contracts";
+import { COLLECTOR_SOURCES, collectorSourceLabel, } from "iteration-trace-contracts";
 import { authenticateAndEnrollCollector } from "./clerk-device-auth.js";
+import { activateSource, connectedConfig, detectedSources, expandSource, loadMachineConsent, readCollectorScope, saveMachineConsent, sourceHome, } from "./auto-connect.js";
 import { importSourceHistory } from "./history-import.js";
 import { runCollector } from "./service.js";
-import { renderDetailedStatus, renderHome, } from "./status-view.js";
+import { renderDetailedStatus, renderHome, safeWorkspaceName, } from "./status-view.js";
+import { installTurnSummary, turnSummaryApprovalHint, uninstallTurnSummary, } from "./turn-summary.js";
 import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
 import { assertFreshCollectorDirectory, collectorSource, collectorSourceDirectory, collectorPaths, defaultCollectorDirectory, ensureStartableState, healthSnapshot, historyScanProgress, loadConfig, outboxSize, pendingEventIds, prepareSourceInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
 const DEFAULT_INGEST_ENDPOINT = "https://useiteration.com/api/traces/ingest";
@@ -52,6 +55,7 @@ function usage(command) {
     if (command === "connect") {
         process.stdout.write([
             "Connect a coding agent to Iteration",
+            "  iteration connect         Connect all detected agents on this Mac",
             "  iteration connect codex",
             "  iteration connect claude",
             "",
@@ -62,7 +66,8 @@ function usage(command) {
             "  --organization-id UUID  Select a workspace without a prompt",
             "  --codex-home DIR        Use a different Codex data directory",
             "  --claude-home DIR       Use a different Claude data directory",
-            "  --data-directory DIR   Use a different Iteration state directory",
+            "  --yes                  Approve uploads without a terminal prompt",
+            "  --data-directory DIR   Use a different state directory with a source-specific command",
             "  --endpoint URL         Use a different Iteration server",
         ].join("\n") + "\n");
         return;
@@ -71,15 +76,15 @@ function usage(command) {
         "Iteration CLI",
         "",
         "Get started:",
-        "  iteration                 See connected sources or connect Codex",
+        "  iteration connect         Connect detected agents and import sessions",
         "",
         "Commands:",
-        "  iteration connect codex   Connect Codex directly",
-        "  iteration connect claude  Connect Claude Code directly",
+        "  iteration                 See connection status",
         "  iteration status          See scan, upload, and error details",
+        "  iteration connect codex|claude  Connect one source (advanced)",
         "  iteration disconnect codex|claude  Stop a source",
         "",
-        "Run iteration connect codex --help for advanced setup options.",
+        "Run iteration connect --help for advanced setup options.",
     ].join("\n") + "\n");
 }
 async function fileExists(filename) {
@@ -107,18 +112,35 @@ async function defaultCommand() {
     ].filter(({ snapshot }) => snapshot.kind !== "not_connected");
     if (connected.length > 0) {
         process.stdout.write(`${connected.map(({ source, snapshot }) => renderHome(snapshot, Date.now(), source)).join("\n\n")}\n`);
+        const discovered = await detectedSources({
+            codex: sourceHome("codex"),
+            claude: sourceHome("claude"),
+        });
+        const missing = discovered.filter((source) => (source === "codex" ? codex : claude).kind === "not_connected");
+        if (missing.length > 0) {
+            process.stdout.write(`\n${missing.map(collectorSourceLabel).join(" and ")} found on this Mac but not connected. Run iteration connect to include ${missing.length === 1 ? "it" : "them"}.\n`);
+        }
         return;
     }
     if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
-        process.stdout.write("Run iteration connect codex or iteration connect claude in a terminal.\n");
+        process.stdout.write("Run iteration connect in a terminal.\n");
         return;
     }
-    await initialize("codex", {});
+    await connectAll({});
 }
 function dataDirectory(source, values) {
     return path.resolve(optionalString(values, "data-directory") ??
         defaultCollectorDirectory(source));
 }
+async function turnSummaryNotice(config) {
+    try {
+        await installTurnSummary(config);
+        return ` A one-line friction summary now appears after agent turns in your repositories.${turnSummaryApprovalHint(config)}`;
+    }
+    catch (error) {
+        return ` The turn summary could not be installed: ${error instanceof Error ? error.message : "unknown error"} Run iteration start ${collectorSource(config)} to retry it.`;
+    }
+}
 async function initialize(source, values) {
     if (process.platform !== "darwin") {
         throw new Error("Automatic startup is currently supported on macOS only.");
@@ -143,6 +165,7 @@ async function initialize(source, values) {
         endpoint: endpointUrl.toString(),
         token: enrollment.token,
         dataDirectory: directory,
+        organizationId: enrollment.organizationId,
         organizationName: enrollment.organizationName,
     };
     const config = source === "codex"
@@ -161,7 +184,134 @@ async function initialize(source, values) {
     catch (error) {
         throw new Error(`Collector access was approved, but background startup failed. Run iteration start ${source} to retry it.`, { cause: error });
     }
-    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.\n`);
+    const notice = await turnSummaryNotice(config);
+    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}\n`);
+    return config;
+}
+async function approveAllSources(sources, workspaceName, yes) {
+    const names = sources.map(collectorSourceLabel).join(" and ");
+    const safeName = safeWorkspaceName(workspaceName);
+    process.stdout.write(`Detected ${names || "no saved agent sessions"} on this Mac.\n` +
+        `Connect supported agents${safeName ? ` to ${safeName}` : " to the workspace you select"}? Existing sessions and future activity, including prompts, code, and tool output, will be uploaded. Workspace members can read them. Newly detected supported agents will connect automatically.\n`);
+    if (yes)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Run iteration connect interactively or pass --yes to approve uploads.");
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await prompt.question("Connect agents? [y/N] "))
+            .trim()
+            .toLowerCase();
+        if (answer !== "y" && answer !== "yes")
+            throw new Error("No agents were connected.");
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function connectAll(values) {
+    if (process.platform !== "darwin") {
+        throw new Error("Automatic startup is currently supported on macOS only.");
+    }
+    if (values["data-directory"] !== undefined) {
+        throw new Error("--data-directory requires a source-specific connect command.");
+    }
+    const configs = await Promise.all(COLLECTOR_SOURCES.map(connectedConfig));
+    const sourceHomes = {
+        codex: path.resolve(optionalString(values, "codex-home") ??
+            (configs[0] && "codexHome" in configs[0]
+                ? configs[0].codexHome
+                : sourceHome("codex"))),
+        claude: path.resolve(optionalString(values, "claude-home") ??
+            (configs[1] && "claudeHome" in configs[1]
+                ? configs[1].claudeHome
+                : sourceHome("claude"))),
+    };
+    const detected = await detectedSources(sourceHomes);
+    const existing = COLLECTOR_SOURCES.flatMap((source, index) => configs[index] ? [{ source, config: configs[index] }] : []);
+    if (detected.length === 0 && existing.length === 0) {
+        process.stdout.write("No supported local coding agents found yet. Run iteration connect after using Codex or Claude Code on this Mac.\n");
+        return;
+    }
+    const anchorSource = existing[0]?.source ?? detected[0];
+    const anchorExisting = existing[0]?.config ?? null;
+    const endpoint = validateCollectorEndpoint(optionalString(values, "endpoint") ??
+        anchorExisting?.endpoint ??
+        DEFAULT_INGEST_ENDPOINT).toString();
+    const existingScopes = await Promise.all(existing.map(async (item) => ({
+        ...item,
+        scope: await readCollectorScope(item.config),
+    })));
+    for (const item of existingScopes) {
+        if (item.config.endpoint !== endpoint) {
+            throw new Error("Existing sources use different Iteration servers. Connect one source at a time.");
+        }
+        if (existingScopes[0]?.scope.organizationId !== item.scope.organizationId) {
+            throw new Error("Existing sources use different workspaces. Connect one source at a time.");
+        }
+    }
+    const requestedOrganizationId = optionalString(values, "organization-id");
+    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) {
+        await approveAllSources(detected, existingScopes[0]?.scope.organizationName ?? null, values.yes === true);
+    }
+    let anchor = anchorExisting ?? (await initialize(anchorSource, values));
+    let organizationId = requestedOrganizationId ??
+        existingScopes[0]?.scope.organizationId ??
+        anchor.organizationId ??
+        null;
+    for (const source of detected) {
+        if (source === anchorSource ||
+            configs[COLLECTOR_SOURCES.indexOf(source)] !== null)
+            continue;
+        const paths = collectorPaths(defaultCollectorDirectory(source));
+        await assertFreshCollectorDirectory(paths, source);
+        const state = await prepareSourceInitialState(source, sourceHomes[source], true);
+        const enrollment = await expandSource(anchor, source, organizationId);
+        const config = await activateSource(source, sourceHomes[source], endpoint, enrollment, state);
+        organizationId = enrollment.organizationId;
+        const notice = await turnSummaryNotice(config);
+        process.stdout.write(`${collectorSourceLabel(source)} is connected to ${enrollment.organizationName}.${notice}\n`);
+    }
+    if (organizationId === null) {
+        organizationId = (await readCollectorScope(anchor)).organizationId;
+    }
+    if (anchor.organizationId === undefined) {
+        anchor = { ...anchor, organizationId };
+        await saveConfig(anchor, collectorPaths(anchor.dataDirectory));
+    }
+    await saveMachineConsent({
+        version: 1,
+        endpoint,
+        organizationId,
+        anchorSource,
+        anchorDataDirectory: anchor.dataDirectory,
+        sourceHomes,
+    });
+    for (const item of existing) {
+        await ensureStartableState(item.config, collectorPaths(item.config.dataDirectory));
+        await installLaunchAgent(item.config.dataDirectory, item.source);
+        const notice = await turnSummaryNotice(item.config);
+        process.stdout.write(`${collectorSourceLabel(item.source)} is still connected.${notice}\n`);
+    }
+    process.stdout.write("Detected agents are connected. New supported agents on this Mac will connect automatically.\n");
 }
 async function importHistory(source, values) {
     if (process.platform !== "darwin") {
@@ -192,7 +342,8 @@ async function start(source, values) {
         throw new Error(`This collector directory belongs to ${collectorSource(config)}.`);
     const repairedState = await ensureStartableState(config, paths);
     await installLaunchAgent(directory, source);
-    process.stdout.write(`${collectorSourceLabel(source)} is collecting again. Run iteration to check progress.${repairedState ? " Incomplete setup was repaired." : ""}\n`);
+    const notice = await turnSummaryNotice(config);
+    process.stdout.write(`${collectorSourceLabel(source)} is collecting again. Run iteration to check progress.${repairedState ? " Incomplete setup was repaired." : ""}${notice}\n`);
 }
 async function statusSnapshot(source, values) {
     const paths = collectorPaths(dataDirectory(source, values));
@@ -253,7 +404,10 @@ async function main() {
         !(command === "connect" && selectedSource !== null)) {
         throw new Error("Existing sessions are included automatically. Run iteration to connect.");
     }
-    if (command === "" || (command === "connect" && source === undefined)) {
+    if (command === "connect" && source === undefined) {
+        return connectAll(values);
+    }
+    if (command === "") {
         if (Object.keys(values).length > 0) {
             throw new Error("Options require a source. Run iteration connect --help for details.");
         }
@@ -265,8 +419,10 @@ async function main() {
         if (selectedSource === "claude" && values["codex-home"] !== undefined)
             throw new Error("--codex-home requires the Codex source.");
     }
-    if (command === "connect" && selectedSource !== null)
-        return initialize(selectedSource, values);
+    if (command === "connect" && selectedSource !== null) {
+        await initialize(selectedSource, values);
+        return;
+    }
     if (command === "run") {
         if (source !== undefined && selectedSource === null)
             throw new Error("The run source must be codex or claude.");
@@ -284,6 +440,10 @@ async function main() {
         return start(selectedSource, values);
     if (command === "disconnect" && selectedSource !== null) {
         await uninstallLaunchAgent(selectedSource);
+        const paths = collectorPaths(dataDirectory(selectedSource, values));
+        if (await fileExists(paths.config)) {
+            await uninstallTurnSummary(await loadConfig(paths));
+        }
         process.stdout.write("Collector startup removed. Local pending data was retained.\n");
         return;
     }

package/dist/service.js

@@ -1,7 +1,9 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
+import { connectNewDetectedSources, loadMachineConsent, } from "./auto-connect.js";
 import { collectorTick, TraceUploadError } from "./collector.js";
+import { refreshTurnSummaries } from "./turn-summary.js";
 import { collectorSource, collectorPaths, ensureClaudeHistoryBackfill, ensureHistoryBackfill, ensurePrivateDirectory, healthSnapshot, loadConfig, saveHealth, } from "./storage.js";
 function errorCode(error) {
     if (error instanceof Error && "code" in error)
@@ -111,7 +113,34 @@ export async function runCollector(directory, expectedSource) {
             await ensureClaudeHistoryBackfill(config.claudeHome, paths);
         else
             await ensureHistoryBackfill(config.codexHome, paths);
+        const summariesRefreshedAt = new Map();
+        let lastAutoCheckAt = 0;
         while (!controller.signal.aborted) {
+            if (Date.now() - lastAutoCheckAt >= 60_000) {
+                lastAutoCheckAt = Date.now();
+                try {
+                    const consent = await loadMachineConsent();
+                    if (consent?.anchorSource === source) {
+                        const connected = await connectNewDetectedSources(config, consent);
+                        if (connected.length > 0) {
+                            console.info(JSON.stringify({
+                                level: "info",
+                                operation: "auto_connect_sources",
+                                connected,
+                            }));
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error(JSON.stringify({
+                        level: "error",
+                        operation: "auto_connect_sources",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Automatic source connection failed.",
+                    }));
+                }
+            }
             let acknowledgedAtMs = null;
             try {
                 const result = await collectorTick(config, paths, fetch, controller.signal, () => {
@@ -159,6 +188,22 @@ export async function runCollector(directory, expectedSource) {
                 await persistHealth(health, paths);
                 retryDelayMs = Math.min(retryDelayMs * 2, 60_000);
             }
+            try {
+                await refreshTurnSummaries(config, summariesRefreshedAt, Date.now(), fetch, controller.signal);
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    break;
+                console.error(JSON.stringify({
+                    level: "warning",
+                    source,
+                    operation: "refresh_turn_summaries",
+                    errorName: error instanceof Error ? error.name : "UnknownError",
+                    message: error instanceof Error
+                        ? error.message
+                        : "Unknown turn summary failure.",
+                }));
+            }
             try {
                 await delay(retryDelayMs, undefined, { signal: controller.signal });
             }

package/dist/status-view.d.ts

@@ -25,6 +25,7 @@ export type CliStatus = Readonly<{
     tracesUrl: string;
     logPath: string;
 }>;
+export declare function safeWorkspaceName(value: string | null): string | null;
 export declare function renderHome(status: CliStatus, nowMs?: number, source?: CollectorSource): string;
 export declare function renderDetailedStatus(status: CliStatus, nowMs?: number, source?: CollectorSource): string;
 export {};

package/dist/status-view.js

@@ -2,7 +2,7 @@ import { collectorSourceLabel, } from "iteration-trace-contracts";
 function sourceName(source) {
     return collectorSourceLabel(source);
 }
-function safeWorkspaceName(value) {
+export function safeWorkspaceName(value) {
     const cleaned = value
         ?.split("")
         .map((character) => {
@@ -122,7 +122,7 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
             "Iteration",
             "",
             `${name} is not connected.`,
-            `Run iteration connect ${source} to import your existing sessions.`,
+            "Run iteration connect to import your existing sessions.",
         ].join("\n");
     }
     if (status.kind === "needs_repair") {
@@ -203,7 +203,7 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
 export function renderDetailedStatus(status, nowMs = Date.now(), source = "codex") {
     const name = sourceName(source);
     if (status.kind === "not_connected") {
-        return `${name} is not connected. Run iteration connect ${source} to connect.`;
+        return `${name} is not connected. Run iteration connect to connect.`;
     }
     if (status.kind === "needs_repair") {
         return [

package/dist/storage.d.ts

@@ -3,6 +3,7 @@ type CollectorConnection = Readonly<{
     endpoint: string;
     token: string;
     dataDirectory: string;
+    organizationId?: string;
     organizationName?: string;
 }>;
 export type CollectorConfig = (CollectorConnection & Readonly<{

package/dist/storage.js

@@ -16,6 +16,7 @@ const connectionSchema = {
     endpoint: z.string(),
     token: z.string(),
     dataDirectory: z.string(),
+    organizationId: z.uuid().optional(),
     organizationName: z.string().min(1).max(160).optional(),
 };
 const configSchema = z.union([

package/dist/turn-summary.d.ts

@@ -0,0 +1,21 @@
+import { type CollectorFrictionSummary } from "iteration-trace-contracts";
+import { type CollectorConfig } from "./storage.js";
+export type TurnSummaryPaths = Readonly<{
+    directory: string;
+    script: string;
+    requests: string;
+    lines: string;
+    shown: string;
+}>;
+export declare function turnSummaryPaths(dataDirectory: string): TurnSummaryPaths;
+export declare function installTurnSummary(config: CollectorConfig): Promise<void>;
+export declare function uninstallTurnSummary(config: CollectorConfig): Promise<void>;
+export declare function turnSummaryMessage(summary: CollectorFrictionSummary): string | null;
+export declare class TurnSummaryRefreshError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function refreshTurnSummaries(config: CollectorConfig, refreshedAt: Map<string, Readonly<{
+    directory: string;
+    atMs: number;
+}>>, nowMs: number, fetcher?: typeof fetch, signal?: AbortSignal): Promise<number>;
+export declare function turnSummaryApprovalHint(config: CollectorConfig): string;

package/dist/turn-summary.js

@@ -0,0 +1,302 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { isLaunchDirectory, parseCollectorFrictionSummary, } from "iteration-trace-contracts";
+import * as z from "zod";
+import { collectorSource, ensurePrivateDirectory, } from "./storage.js";
+const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+const REQUEST_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+const MAX_REFRESHES_PER_PASS = 20;
+const REQUEST_TIMEOUT_MS = 10_000;
+const HOOK_TIMEOUT_SECONDS = 1;
+const REQUEST_KEY_PATTERN = /^\d{1,10}$/;
+export function turnSummaryPaths(dataDirectory) {
+    const directory = path.join(dataDirectory, "turn-summary");
+    return {
+        directory,
+        script: path.join(directory, "stop-hook.sh"),
+        requests: path.join(directory, "requests"),
+        lines: path.join(directory, "lines"),
+        shown: path.join(directory, "shown"),
+    };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+// The hook runs at the end of every agent turn, so it only reads files the
+// collector keeps current and never waits on the network. Every failure prints
+// the empty object both agents accept, so a broken summary never blocks a turn.
+function hookScript(paths) {
+    return `#!/bin/sh
+exec 2>/dev/null
+cat >/dev/null
+summary=${shellQuote(paths.directory)}
+quiet() { printf '{}\\n'; exit 0; }
+unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX
+cd "\${CLAUDE_PROJECT_DIR:-.}" || quiet
+directory=$(git rev-parse --show-toplevel) || quiet
+case $directory in /*) ;; *) quiet ;; esac
+set -- $(printf '%s' "$directory" | cksum)
+key=$1
+[ -n "$key" ] || quiet
+printf '%s\\n' "$directory" > "$summary/requests/$key"
+[ -f "$summary/lines/$key" ] || quiet
+{ IFS= read -r owner && IFS= read -r message; } < "$summary/lines/$key" || quiet
+[ "$owner" = "$directory" ] || quiet
+last=
+[ -f "$summary/shown/$key" ] && IFS= read -r last < "$summary/shown/$key"
+[ "$last" = "$message" ] && quiet
+printf '%s\\n' "$message" > "$summary/shown/$key" || quiet
+printf '%s\\n' "$message"
+`;
+}
+function hookCommand(paths) {
+    return `/bin/sh ${shellQuote(paths.script)}`;
+}
+function agentHookFile(config) {
+    return "claudeHome" in config
+        ? path.join(config.claudeHome, "settings.json")
+        : path.join(config.codexHome, "hooks.json");
+}
+const hookEntrySchema = z.object({ command: z.string().optional() }).loose();
+const hookGroupSchema = z
+    .object({ hooks: z.array(hookEntrySchema).optional() })
+    .loose();
+const hookFileSchema = z
+    .object({
+    hooks: z
+        .object({ Stop: z.array(hookGroupSchema).optional() })
+        .loose()
+        .optional(),
+})
+    .loose();
+async function readHookFile(filename) {
+    let contents;
+    let mode = 0o600;
+    try {
+        contents = await fs.readFile(filename, "utf8");
+        mode = (await fs.stat(filename)).mode & 0o777;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return { file: {}, mode };
+        }
+        throw new Error(`Could not read agent hooks at ${filename}.`, {
+            cause: error,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error(`Agent hooks at ${filename} are not valid JSON.`, {
+            cause: error,
+        });
+    }
+    const parsed = hookFileSchema.safeParse(decoded);
+    if (!parsed.success) {
+        throw new Error(`Agent hooks at ${filename} have an unexpected shape.`, {
+            cause: parsed.error,
+        });
+    }
+    return { file: parsed.data, mode };
+}
+async function writeHookFile(filename, file, mode) {
+    await fs.mkdir(path.dirname(filename), { recursive: true });
+    // Settings kept in a dotfiles repository are often symlinks; replacing the
+    // link with a file would silently detach them from that repository.
+    const target = await fs.realpath(filename).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return filename;
+        throw error;
+    });
+    const temporary = `${target}.iteration-${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`, {
+        encoding: "utf8",
+        mode,
+    });
+    await fs.rename(temporary, target);
+}
+function withoutCommand(groups, command) {
+    return groups.flatMap((group) => {
+        const hooks = group.hooks?.filter((hook) => hook.command !== command);
+        if (hooks === undefined || hooks.length === group.hooks?.length)
+            return [group];
+        return hooks.length === 0 ? [] : [{ ...group, hooks }];
+    });
+}
+function hasCommand(groups, command) {
+    return groups.some((group) => group.hooks?.some((hook) => hook.command === command));
+}
+export async function installTurnSummary(config) {
+    const paths = turnSummaryPaths(config.dataDirectory);
+    await ensurePrivateDirectory(paths.directory);
+    await Promise.all([paths.requests, paths.lines, paths.shown].map(ensurePrivateDirectory));
+    await fs.writeFile(paths.script, hookScript(paths), {
+        encoding: "utf8",
+        mode: 0o700,
+    });
+    await fs.chmod(paths.script, 0o700);
+    const filename = agentHookFile(config);
+    const { file, mode } = await readHookFile(filename);
+    const command = hookCommand(paths);
+    const stop = file.hooks?.Stop ?? [];
+    if (hasCommand(stop, command))
+        return;
+    await writeHookFile(filename, {
+        ...file,
+        hooks: {
+            ...file.hooks,
+            Stop: [
+                ...stop,
+                {
+                    hooks: [
+                        { type: "command", command, timeout: HOOK_TIMEOUT_SECONDS },
+                    ],
+                },
+            ],
+        },
+    }, mode);
+}
+export async function uninstallTurnSummary(config) {
+    const filename = agentHookFile(config);
+    const { file, mode } = await readHookFile(filename);
+    const stop = file.hooks?.Stop ?? [];
+    const command = hookCommand(turnSummaryPaths(config.dataDirectory));
+    if (!hasCommand(stop, command))
+        return;
+    const remaining = withoutCommand(stop, command);
+    const { Stop: _removed, ...otherEvents } = file.hooks ?? {};
+    await writeHookFile(filename, {
+        ...file,
+        hooks: remaining.length === 0
+            ? otherEvents
+            : { ...otherEvents, Stop: remaining },
+    }, mode);
+}
+export function turnSummaryMessage(summary) {
+    if (summary.weekEpisodes === 0)
+        return null;
+    const episodes = `${summary.weekEpisodes} friction episode${summary.weekEpisodes === 1 ? "" : "s"}`;
+    const recent = summary.dayEpisodes === 0
+        ? ""
+        : ` · ${summary.dayEpisodes} new since yesterday`;
+    return `◆ Iteration · ${episodes} in this repo this week${recent}`;
+}
+export class TurnSummaryRefreshError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TurnSummaryRefreshError";
+    }
+}
+async function fetchSummary(config, directory, fetcher, signal) {
+    const url = new URL("/api/traces/friction-summary", config.endpoint);
+    url.searchParams.set("directory", directory);
+    let response;
+    try {
+        response = await fetcher(url, {
+            headers: { authorization: `Bearer ${config.token}` },
+            signal: signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+                : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        throw new TurnSummaryRefreshError("Friction summary could not reach Iteration.", { cause: error });
+    }
+    if (response.status !== 200) {
+        throw new TurnSummaryRefreshError(`Friction summary failed with HTTP ${response.status}.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new TurnSummaryRefreshError("Friction summary returned an unreadable response.", { cause: error });
+    }
+    const parsed = parseCollectorFrictionSummary(body);
+    if (!parsed.success)
+        throw new TurnSummaryRefreshError(parsed.error);
+    return parsed.value;
+}
+async function readRequest(filename) {
+    try {
+        const [directory] = (await fs.readFile(filename, "utf8")).split("\n");
+        return directory ?? null;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeLine(paths, key, directory, message) {
+    const filename = path.join(paths.lines, key);
+    if (message === null) {
+        await fs.rm(filename, { force: true });
+        return;
+    }
+    const temporary = `${filename}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${directory}\n${JSON.stringify({ systemMessage: message })}\n`, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(temporary, filename);
+}
+async function forget(paths, key) {
+    await Promise.all([paths.requests, paths.lines, paths.shown].map((directory) => fs.rm(path.join(directory, key), { force: true })));
+}
+// Refreshes the summary line for each repository the hook asked about. The
+// hook reads the result on a later turn, so a slow or failed request never
+// delays the agent.
+export async function refreshTurnSummaries(config, refreshedAt, nowMs, fetcher = fetch, signal) {
+    const paths = turnSummaryPaths(config.dataDirectory);
+    let keys;
+    try {
+        keys = await fs.readdir(paths.requests);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    let refreshed = 0;
+    for (const key of keys.sort()) {
+        signal?.throwIfAborted();
+        if (!REQUEST_KEY_PATTERN.test(key))
+            continue;
+        const filename = path.join(paths.requests, key);
+        const stats = await fs.stat(filename).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (stats === null)
+            continue;
+        const directory = await readRequest(filename);
+        if (nowMs - stats.mtimeMs > REQUEST_RETENTION_MS ||
+            directory === null ||
+            !isLaunchDirectory(directory)) {
+            await forget(paths, key);
+            refreshedAt.delete(key);
+            continue;
+        }
+        const previous = refreshedAt.get(key);
+        if (previous !== undefined &&
+            previous.directory === directory &&
+            nowMs - previous.atMs < REFRESH_INTERVAL_MS) {
+            continue;
+        }
+        if (refreshed === MAX_REFRESHES_PER_PASS)
+            break;
+        refreshedAt.set(key, { directory, atMs: nowMs });
+        refreshed += 1;
+        const summary = await fetchSummary(config, directory, fetcher, signal);
+        await writeLine(paths, key, directory, turnSummaryMessage(summary));
+    }
+    return refreshed;
+}
+export function turnSummaryApprovalHint(config) {
+    return collectorSource(config) === "codex"
+        ? " Approve Iteration's turn summary once with /hooks in Codex."
+        : "";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "zod": "4.6.4",
-    "iteration-trace-contracts": "0.5.0"
+    "iteration-trace-contracts": "0.6.0"
   },
   "scripts": {
     "build": "pnpm --filter iteration-trace-contracts build && tsc -p tsconfig.json"