iteration-cli 0.6.0 → 0.7.0

package/README.md

@@ -7,7 +7,7 @@ npm install --global iteration-cli
 iteration connect
 ```
 
-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.
+The collectors run on macOS or Linux with Node.js 22 or later. 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 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.
 

package/dist/auto-connect.js

@@ -4,7 +4,7 @@ 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 { installBackgroundService } from "./background-service.js";
 import { installTurnSummary } from "./turn-summary.js";
 import { assertFreshCollectorDirectory, collectorPaths, defaultCollectorDirectory, ensurePrivateDirectory, loadConfig, prepareSourceInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
 const consentSchema = z
@@ -159,7 +159,7 @@ export async function activateSource(source, home, endpoint, enrollment, state)
     await saveConfig(config, paths);
     try {
         await saveState(state, paths);
-        await installLaunchAgent(directory, source);
+        await installBackgroundService(directory, source);
     }
     catch (error) {
         throw new Error(`${source} was connected, but local startup failed. Run iteration start ${source} to repair it.`, { cause: error });

package/dist/background-service.d.ts

@@ -0,0 +1,7 @@
+import type { CollectorSource } from "iteration-trace-contracts";
+export declare function requireCollectorPlatform(): void;
+export declare function prepareBackgroundPersistence(): Promise<void>;
+export declare function collectorLogPath(source: CollectorSource): string;
+export declare function installBackgroundService(directory: string, source: CollectorSource): Promise<string>;
+export declare function uninstallBackgroundService(source: CollectorSource): Promise<void>;
+export declare function backgroundServiceStatus(source: CollectorSource): Promise<boolean>;

package/dist/background-service.js

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
+import { installSystemdUserService, ensureSystemdUserLinger, systemdLogPath, systemdUserServiceStatus, uninstallSystemdUserService, } from "./systemd-user.js";
+export function requireCollectorPlatform() {
+    if (process.platform !== "darwin" && process.platform !== "linux") {
+        throw new Error("Automatic startup is supported on macOS and Linux only.");
+    }
+}
+export async function prepareBackgroundPersistence() {
+    requireCollectorPlatform();
+    if (process.platform === "linux")
+        await ensureSystemdUserLinger();
+}
+export function collectorLogPath(source) {
+    if (process.platform === "linux")
+        return systemdLogPath(source);
+    return path.join(os.homedir(), "Library", "Logs", `iteration-${source}-collector.error.log`);
+}
+export async function installBackgroundService(directory, source) {
+    requireCollectorPlatform();
+    return process.platform === "darwin"
+        ? installLaunchAgent(directory, source)
+        : installSystemdUserService(directory, source);
+}
+export async function uninstallBackgroundService(source) {
+    requireCollectorPlatform();
+    return process.platform === "darwin"
+        ? uninstallLaunchAgent(source)
+        : uninstallSystemdUserService(source);
+}
+export async function backgroundServiceStatus(source) {
+    requireCollectorPlatform();
+    return process.platform === "darwin"
+        ? launchAgentStatus(source)
+        : systemdUserServiceStatus(source);
+}

package/dist/cli.js

@@ -11,8 +11,8 @@ import { activateSource, connectedConfig, detectedSources, expandSource, loadMac
 import { importSourceHistory } from "./history-import.js";
 import { runCollector } from "./service.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 { installTurnSummary, codexTurnSummaryApproval, uninstallTurnSummary, } from "./turn-summary.js";
+import { backgroundServiceStatus, collectorLogPath, installBackgroundService, prepareBackgroundPersistence, requireCollectorPlatform, uninstallBackgroundService, } from "./background-service.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";
 function argumentsForCli() {
@@ -55,14 +55,14 @@ 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         Connect all detected agents on this computer",
             "  iteration connect codex",
             "  iteration connect claude",
             "",
             "Existing local sessions and new activity are collected automatically.",
             "",
             "Options for advanced setups:",
-            "  --device-name NAME      Name this Mac in Iteration",
+            "  --device-name NAME      Name this computer in Iteration",
             "  --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",
@@ -118,7 +118,7 @@ async function defaultCommand() {
         });
         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`);
+            process.stdout.write(`\n${missing.map(collectorSourceLabel).join(" and ")} found on this computer but not connected. Run iteration connect to include ${missing.length === 1 ? "it" : "them"}.\n`);
         }
         return;
     }
@@ -135,16 +135,17 @@ function dataDirectory(source, values) {
 async function turnSummaryNotice(config) {
     try {
         await installTurnSummary(config);
-        return ` A one-line friction summary now appears after agent turns in your repositories.${turnSummaryApprovalHint(config)}`;
+        if ((await codexTurnSummaryApproval(config)) === "needs_approval") {
+            return "\nOne more step: in Codex, type /hooks and approve Iteration to see your friction summary after each turn.";
+        }
+        return " A one-line friction summary now appears after agent turns in your repositories.";
     }
     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.");
-    }
+    requireCollectorPlatform();
     const endpoint = optionalString(values, "endpoint") ?? DEFAULT_INGEST_ENDPOINT;
     const endpointUrl = validateCollectorEndpoint(endpoint);
     const deviceName = optionalString(values, "device-name") ?? os.hostname();
@@ -160,6 +161,7 @@ async function initialize(source, values) {
             path.join(os.homedir(), ".claude")));
     await assertFreshCollectorDirectory(paths, source);
     const preparedState = await prepareSourceInitialState(source, sourceHome, true);
+    await prepareBackgroundPersistence();
     const enrollment = await authenticateAndEnrollCollector(endpointUrl, deviceName, organizationId, source);
     const connection = {
         endpoint: endpointUrl.toString(),
@@ -179,7 +181,7 @@ async function initialize(source, values) {
         throw new Error(`Collector access was approved, but local setup did not finish. Run iteration start ${source} to repair it.`, { cause: error });
     }
     try {
-        await installLaunchAgent(directory, source);
+        await installBackgroundService(directory, source);
     }
     catch (error) {
         throw new Error(`Collector access was approved, but background startup failed. Run iteration start ${source} to retry it.`, { cause: error });
@@ -191,8 +193,8 @@ async function initialize(source, values) {
 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`);
+    process.stdout.write(`Detected ${names || "no saved agent sessions"} on this computer.\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.${process.platform === "linux" ? " Collection will continue after you log out." : ""}\n`);
     if (yes)
         return;
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -214,9 +216,7 @@ async function approveAllSources(sources, workspaceName, yes) {
     }
 }
 async function connectAll(values) {
-    if (process.platform !== "darwin") {
-        throw new Error("Automatic startup is currently supported on macOS only.");
-    }
+    requireCollectorPlatform();
     if (values["data-directory"] !== undefined) {
         throw new Error("--data-directory requires a source-specific connect command.");
     }
@@ -234,7 +234,7 @@ async function connectAll(values) {
     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");
+        process.stdout.write("No supported local coding agents found yet. Run iteration connect after using Codex or Claude Code on this computer.\n");
         return;
     }
     const anchorSource = existing[0]?.source ?? detected[0];
@@ -272,6 +272,7 @@ async function connectAll(values) {
         previousConsent.sourceHomes.claude !== sourceHomes.claude) {
         await approveAllSources(detected, existingScopes[0]?.scope.organizationName ?? null, values.yes === true);
     }
+    await prepareBackgroundPersistence();
     let anchor = anchorExisting ?? (await initialize(anchorSource, values));
     let organizationId = requestedOrganizationId ??
         existingScopes[0]?.scope.organizationId ??
@@ -307,16 +308,14 @@ async function connectAll(values) {
     });
     for (const item of existing) {
         await ensureStartableState(item.config, collectorPaths(item.config.dataDirectory));
-        await installLaunchAgent(item.config.dataDirectory, item.source);
+        await installBackgroundService(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");
+    process.stdout.write("Detected agents are connected. New supported agents on this computer will connect automatically.\n");
 }
 async function importHistory(source, values) {
-    if (process.platform !== "darwin") {
-        throw new Error("Automatic startup is currently supported on macOS only.");
-    }
+    requireCollectorPlatform();
     const directory = dataDirectory(source, values);
     const paths = collectorPaths(directory);
     const config = await loadConfig(paths);
@@ -332,16 +331,14 @@ async function importHistory(source, values) {
     process.stdout.write(`History scan scheduled for ${result.size.files} local session files (${result.size.bytes} bytes). Scanning and uploads run in bounded batches and may take time. Older sessions appear under the date Iteration receives them. Use iteration status ${source} to see local scan progress and pending uploads.${result.backgroundRunning ? "" : ` The collector was not running; run iteration start ${source} to begin scanning.`}\n`);
 }
 async function start(source, values) {
-    if (process.platform !== "darwin") {
-        throw new Error("Automatic startup is currently supported on macOS only.");
-    }
+    requireCollectorPlatform();
     const directory = dataDirectory(source, values);
     const paths = collectorPaths(directory);
     const config = await loadConfig(paths);
     if (collectorSource(config) !== source)
         throw new Error(`This collector directory belongs to ${collectorSource(config)}.`);
     const repairedState = await ensureStartableState(config, paths);
-    await installLaunchAgent(directory, source);
+    await installBackgroundService(directory, source);
     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`);
 }
@@ -360,12 +357,13 @@ async function statusSnapshot(source, values) {
     const config = await loadConfig(paths);
     if (collectorSource(config) !== source)
         throw new Error(`This collector directory belongs to ${collectorSource(config)}.`);
-    const [running, size, ids, scan, localHealth] = await Promise.all([
-        launchAgentStatus(source),
+    const [running, size, ids, scan, localHealth, approval] = await Promise.all([
+        backgroundServiceStatus(source),
         outboxSize(paths),
         pendingEventIds(paths),
         historyScanProgress(collectorSourceDirectory(config), paths, source),
         healthSnapshot(paths),
+        codexTurnSummaryApproval(config),
     ]);
     const pendingEvents = size === 0 ? 0 : ids.size;
     const pendingBytes = ids.size === 0 ? 0 : size;
@@ -378,8 +376,9 @@ async function statusSnapshot(source, values) {
         pendingBytes,
         health: localHealth.health,
         healthAvailable: localHealth.kind === "available",
+        turnSummaryNeedsApproval: approval === "needs_approval",
         tracesUrl: new URL("/app/sessions", config.endpoint).toString(),
-        logPath: path.join(os.homedir(), "Library", "Logs", `iteration-${source}-collector.error.log`),
+        logPath: collectorLogPath(source),
     };
 }
 async function status(source, values) {
@@ -439,7 +438,7 @@ async function main() {
     if (command === "start" && selectedSource !== null)
         return start(selectedSource, values);
     if (command === "disconnect" && selectedSource !== null) {
-        await uninstallLaunchAgent(selectedSource);
+        await uninstallBackgroundService(selectedSource);
         const paths = collectorPaths(dataDirectory(selectedSource, values));
         if (await fileExists(paths.config)) {
             await uninstallTurnSummary(await loadConfig(paths));

package/dist/history-import.js

@@ -1,16 +1,16 @@
 import path from "node:path";
-import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
+import { backgroundServiceStatus, installBackgroundService, uninstallBackgroundService, } from "./background-service.js";
 import { waitForCollectorLock } from "./service.js";
 import { collectorSource, collectorSourceDirectory, historyImportSize, loadState, resetHistoryCursors, } from "./storage.js";
-function macControl(source) {
+function backgroundControl(source) {
     return {
-        isRunning: () => launchAgentStatus(source),
-        stop: () => uninstallLaunchAgent(source),
-        start: (directory) => installLaunchAgent(directory, source),
+        isRunning: () => backgroundServiceStatus(source),
+        stop: () => uninstallBackgroundService(source),
+        start: (directory) => installBackgroundService(directory, source),
         acquireLock: waitForCollectorLock,
     };
 }
-export async function importSourceHistory(config, paths, confirmed, control = macControl(collectorSource(config))) {
+export async function importSourceHistory(config, paths, confirmed, control = backgroundControl(collectorSource(config))) {
     const source = collectorSource(config);
     const directory = collectorSourceDirectory(config);
     const state = await loadState(paths);

package/dist/status-view.d.ts

@@ -22,6 +22,7 @@ export type CliStatus = Readonly<{
     pendingBytes: number;
     health: CollectorHealth;
     healthAvailable: boolean;
+    turnSummaryNeedsApproval: boolean;
     tracesUrl: string;
     logPath: string;
 }>;

package/dist/status-view.js

@@ -1,4 +1,5 @@
 import { collectorSourceLabel, } from "iteration-trace-contracts";
+const CODEX_APPROVAL_STEP = "Friction summary is off: in Codex, type /hooks and approve Iteration.";
 function sourceName(source) {
     return collectorSourceLabel(source);
 }
@@ -43,7 +44,7 @@ function relativeTime(atMs, nowMs) {
     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`;
+    return `${status.pendingEvents} event${status.pendingEvents === 1 ? "" : "s"} (${readableBytes(status.pendingBytes)}) waiting on this computer`;
 }
 function progressDescription(scan, source) {
     if (scan.kind === "waiting")
@@ -82,7 +83,7 @@ function failureDescription(status, source) {
         if (failure.status === 401 || failure.status === 403) {
             return {
                 heading: `${name} upload access needs attention`,
-                explanation: `Iteration denied this collector (${code}). Queued data stays on this Mac. Contact Iteration support to reconnect it safely.`,
+                explanation: `Iteration denied this collector (${code}). Queued data stays on this computer. Contact Iteration support to reconnect it safely.`,
             };
         }
         if (failure.status !== null &&
@@ -132,8 +133,8 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
             `${name} 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.",
+                ? `${readableBytes(status.pendingBytes)} of queued data remains on this computer.`
+                : "Existing local progress remains on this computer.",
             `Run iteration status ${source} for recovery details.`,
         ].join("\n");
     }
@@ -183,7 +184,7 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
         lines.push(`${name} is uploading captured sessions`, `${pendingDescription(status)}.`);
     }
     else if (status.scan.totalBytes === 0) {
-        lines.push(`${name} is connected`, `Waiting for ${name} sessions on this Mac.`);
+        lines.push(`${name} is connected`, `Waiting for ${name} sessions on this computer.`);
     }
     else if (status.scan.kind === "scanning" &&
         status.scan.scannedBytes < status.scan.totalBytes) {
@@ -197,6 +198,8 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
         status.health.lastUploadAtMs !== null) {
         lines.push(`Last successful upload ${relativeTime(status.health.lastUploadAtMs, nowMs)}.`);
     }
+    if (status.turnSummaryNeedsApproval)
+        lines.push("", CODEX_APPROVAL_STEP);
     lines.push("", `Explore traces  ${status.tracesUrl}`);
     return lines.join("\n");
 }
@@ -239,6 +242,8 @@ export function renderDetailedStatus(status, nowMs = Date.now(), source = "codex
                     : "Local collector error";
         lines.push(`Last issue: ${label} (${relativeTime(failure.atMs, nowMs)})`, `Collector log: ${status.logPath}`);
     }
+    if (status.turnSummaryNeedsApproval)
+        lines.push(CODEX_APPROVAL_STEP);
     if (!status.running)
         lines.push(`Resume: iteration start ${source}`);
     lines.push(`Explore traces: ${status.tracesUrl}`);

package/dist/systemd-user.d.ts

@@ -0,0 +1,7 @@
+import type { CollectorSource } from "iteration-trace-contracts";
+export declare function ensureSystemdUserLinger(): Promise<void>;
+export declare function systemdLogPath(source: CollectorSource): string;
+export declare function systemdUserUnit(cliPath?: string, nodePath?: string, dataDirectory?: string, source?: CollectorSource, outputPath?: string, errorPath?: string): string;
+export declare function installSystemdUserService(dataDirectory: string, source: CollectorSource): Promise<string>;
+export declare function uninstallSystemdUserService(source: CollectorSource): Promise<void>;
+export declare function systemdUserServiceStatus(source: CollectorSource): Promise<boolean>;

package/dist/systemd-user.js

@@ -0,0 +1,137 @@
+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 { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCallback);
+const SYSTEMCTL_TIMEOUT_MS = 10_000;
+const LOGINCTL_TIMEOUT_MS = 10_000;
+function currentUserId() {
+    const userId = process.getuid?.();
+    if (userId === undefined)
+        throw new Error("Could not determine the current Linux user id.");
+    return String(userId);
+}
+async function lingerState(userId) {
+    const { stdout } = await execFile("loginctl", ["show-user", userId, "--property=Linger", "--value"], { timeout: LOGINCTL_TIMEOUT_MS });
+    const state = stdout.trim();
+    if (state === "yes" || state === "no")
+        return state;
+    throw new Error(`Could not read Linux background service setting: ${state || "empty response"}.`);
+}
+export async function ensureSystemdUserLinger() {
+    const userId = currentUserId();
+    let state = "no";
+    let queryFailure;
+    try {
+        state = await lingerState(userId);
+    }
+    catch (error) {
+        queryFailure = error;
+    }
+    if (state === "yes")
+        return;
+    try {
+        await execFile("loginctl", ["--no-ask-password", "enable-linger", userId], {
+            timeout: LOGINCTL_TIMEOUT_MS,
+        });
+    }
+    catch (userError) {
+        try {
+            await execFile("sudo", ["-n", "loginctl", "enable-linger", userId], {
+                timeout: LOGINCTL_TIMEOUT_MS,
+            });
+        }
+        catch (adminError) {
+            throw new Error("This server does not allow Iteration to keep collecting after you log out. Ask an administrator to allow background services for your account, then run iteration connect again.", {
+                cause: new AggregateError(queryFailure
+                    ? [queryFailure, userError, adminError]
+                    : [userError, adminError], "Could not enable Linux background collection."),
+            });
+        }
+    }
+    try {
+        if ((await lingerState(userId)) === "yes")
+            return;
+    }
+    catch (error) {
+        throw new Error("Could not verify Linux background collection after logout.", {
+            cause: error,
+        });
+    }
+    throw new Error("Linux did not enable background collection after logout.");
+}
+function unitName(source) {
+    return `iteration-${source}-collector.service`;
+}
+function unitPath(source) {
+    return path.join(os.homedir(), ".config", "systemd", "user", unitName(source));
+}
+export function systemdLogPath(source) {
+    return path.join(os.homedir(), ".config", "iteration", "logs", `iteration-${source}-collector.error.log`);
+}
+function unitValue(value) {
+    if (/[\r\n\0]/.test(value))
+        throw new Error("Collector paths cannot contain line breaks.");
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+export function systemdUserUnit(cliPath = fileURLToPath(new URL("./cli.js", import.meta.url)), nodePath = process.execPath, dataDirectory = path.join(os.homedir(), ".config", "iteration", "codex-collector"), source = "codex", outputPath = path.join(os.homedir(), ".config", "iteration", "logs", `iteration-${source}-collector.log`), errorPath = systemdLogPath(source)) {
+    return [
+        "[Unit]",
+        `Description=Iteration ${source} collector`,
+        "[Service]",
+        "Type=exec",
+        `ExecStart=${[nodePath, cliPath, "run", source, "--data-directory", dataDirectory].map(unitValue).join(" ")}`,
+        "Restart=always",
+        "RestartSec=5",
+        `StandardOutput=append:${unitValue(outputPath)}`,
+        `StandardError=append:${unitValue(errorPath)}`,
+        "[Install]",
+        "WantedBy=default.target",
+        "",
+    ].join("\n");
+}
+async function systemctl(...args) {
+    const { stdout } = await execFile("systemctl", ["--user", ...args], {
+        timeout: SYSTEMCTL_TIMEOUT_MS,
+    });
+    return stdout.trim();
+}
+export async function installSystemdUserService(dataDirectory, source) {
+    await ensureSystemdUserLinger();
+    const file = unitPath(source);
+    const logDirectory = path.dirname(systemdLogPath(source));
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    await fs.mkdir(logDirectory, { recursive: true, mode: 0o700 });
+    await fs.writeFile(file, systemdUserUnit(undefined, undefined, dataDirectory, source), {
+        encoding: "utf8",
+        mode: 0o644,
+    });
+    await systemctl("daemon-reload");
+    await systemctl("enable", unitName(source));
+    await systemctl("restart", unitName(source));
+    return file;
+}
+export async function uninstallSystemdUserService(source) {
+    const file = unitPath(source);
+    try {
+        await fs.access(file);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    await systemctl("disable", "--now", unitName(source));
+    await fs.rm(file);
+    await systemctl("daemon-reload");
+}
+export async function systemdUserServiceStatus(source) {
+    const state = await systemctl("show", "--property=ActiveState", "--value", unitName(source));
+    if (state === "active")
+        return true;
+    if (state === "inactive" || state === "failed")
+        return false;
+    throw new Error(`Could not determine ${source} collector service state: ${state || "empty response"}.`);
+}

package/dist/turn-summary.d.ts

@@ -18,4 +18,5 @@ export declare function refreshTurnSummaries(config: CollectorConfig, refreshedA
     directory: string;
     atMs: number;
 }>>, nowMs: number, fetcher?: typeof fetch, signal?: AbortSignal): Promise<number>;
-export declare function turnSummaryApprovalHint(config: CollectorConfig): string;
+export type TurnSummaryApproval = "approved" | "needs_approval" | "not_installed";
+export declare function codexTurnSummaryApproval(config: CollectorConfig): Promise<TurnSummaryApproval>;

package/dist/turn-summary.js

@@ -1,8 +1,9 @@
+import { createHash } from "node:crypto";
 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";
+import { 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;
@@ -295,8 +296,67 @@ export async function refreshTurnSummaries(config, refreshedAt, nowMs, fetcher =
     }
     return refreshed;
 }
-export function turnSummaryApprovalHint(config) {
-    return collectorSource(config) === "codex"
-        ? " Approve Iteration's turn summary once with /hooks in Codex."
-        : "";
+function tomlBasicString(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+// Codex runs a hook only after the developer trusts it in /hooks, and records
+// that trust as a hash of the normalized hook. Recomputing the same hash tells
+// whether Codex will run this exact entry; any other result keeps the reminder.
+function codexHookHash(command) {
+    const identity = {
+        event_name: "stop",
+        hooks: [
+            {
+                async: false,
+                command,
+                timeout: HOOK_TIMEOUT_SECONDS,
+                type: "command",
+            },
+        ],
+    };
+    return `sha256:${createHash("sha256").update(JSON.stringify(identity)).digest("hex")}`;
+}
+function codexTrustedHash(configToml, key) {
+    const lines = configToml.split(/\r?\n/);
+    const header = `[hooks.state.${tomlBasicString(key)}]`;
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start < 0)
+        return null;
+    let trustedHash = null;
+    for (const line of lines.slice(start + 1)) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("["))
+            break;
+        if (/^enabled\s*=\s*false\b/.test(trimmed))
+            return null;
+        const match = /^trusted_hash\s*=\s*"(sha256:[0-9a-f]{64})"/.exec(trimmed);
+        if (match?.[1] !== undefined)
+            trustedHash = match[1];
+    }
+    return trustedHash;
+}
+export async function codexTurnSummaryApproval(config) {
+    if ("claudeHome" in config)
+        return "approved";
+    const filename = agentHookFile(config);
+    const { file } = await readHookFile(filename);
+    const command = hookCommand(turnSummaryPaths(config.dataDirectory));
+    const stop = file.hooks?.Stop ?? [];
+    for (const [groupIndex, group] of stop.entries()) {
+        const handlerIndex = group.hooks?.findIndex((hook) => hook.command === command) ?? -1;
+        if (handlerIndex < 0)
+            continue;
+        let configToml;
+        try {
+            configToml = await fs.readFile(path.join(config.codexHome, "config.toml"), "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return "needs_approval";
+            throw new Error("Could not read the Codex config.", { cause: error });
+        }
+        const trusted = codexTrustedHash(configToml, `${filename}:stop:${groupIndex}:${handlerIndex}`);
+        return trusted === codexHookHash(command) ? "approved" : "needs_approval";
+    }
+    return "not_installed";
 }

package/package.json

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