@blastin-dev/clocktopus-cli 0.2.0 → 0.3.0

package/dist/src/lib/agent-config.js

@@ -1,45 +1,58 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
-import { readInstalledTelemetry } from "./claude-settings.js";
-export function resolveAgentCredentials() {
+import { readInstalledTelemetry, settingsPath } from "./claude-settings.js";
+import { codexConfigPath, readCodexTelemetry } from "./codex-config.js";
+import { opencodePluginPath, readOpencodePlugin } from "./opencode-config.js";
+export function resolveAgentCredentials(agent = "claude") {
     const envToken = process.env.CLOCKTOPUS_INGEST_TOKEN?.trim();
     const envEndpoint = process.env.CLOCKTOPUS_OTEL_ENDPOINT?.trim();
-    let settingsToken;
-    let settingsEndpoint;
+    let fileToken;
+    let fileEndpoint;
     try {
-        const installed = readInstalledTelemetry();
-        settingsToken = installed.env.CLOCKTOPUS_INGEST_TOKEN;
-        settingsEndpoint = installed.env.CLOCKTOPUS_OTEL_ENDPOINT;
+        if (agent === "codex") {
+            const codex = readCodexTelemetry();
+            fileToken = codex.token ?? undefined;
+            fileEndpoint = codex.endpoint ?? undefined;
+        }
+        else if (agent === "opencode") {
+            const plugin = readOpencodePlugin();
+            fileToken = plugin.config?.token ?? undefined;
+            fileEndpoint = plugin.config?.endpoint ?? undefined;
+        }
+        else {
+            const installed = readInstalledTelemetry();
+            fileToken = installed.env.CLOCKTOPUS_INGEST_TOKEN;
+            fileEndpoint = installed.env.CLOCKTOPUS_OTEL_ENDPOINT;
+        }
     }
     catch {
-        // A malformed settings.json is reported properly by `setup` and
-        // `doctor`. Credential resolution must not throw — the hook calls it on
-        // every session start.
+        // A malformed config file is reported properly by `setup` and `doctor`. Credential
+        // resolution must not throw — the hook calls it on every session start.
     }
     return {
-        token: envToken || settingsToken || null,
-        endpoint: (envEndpoint || settingsEndpoint || null)?.replace(/\/$/, "") ?? null,
-        tokenSource: envToken ? "environment" : settingsToken ? "settings" : "none",
+        token: envToken || fileToken || null,
+        endpoint: (envEndpoint || fileEndpoint || null)?.replace(/\/$/, "") ?? null,
+        tokenSource: envToken ? "environment" : fileToken ? "settings" : "none",
         endpointSource: envEndpoint
             ? "environment"
-            : settingsEndpoint
+            : fileEndpoint
                 ? "settings"
                 : "none",
+        sourcePath: agent === "codex"
+            ? codexConfigPath()
+            : agent === "opencode"
+                ? opencodePluginPath()
+                : settingsPath(),
     };
 }
 /** Masks a token for display: never print more than the stored prefix. */
 export function maskToken(token) {
     return token.length <= 15 ? "…" : `${token.slice(0, 15)}…`;
 }
-/**
- * Files that commonly export the same variables, and would be shadowed.
- *
- * Scanned rather than guessed at, because "your `.envrc` is being ignored"
- * is only useful advice when it names the file. The repo-local `.envrc` is
- * included because that is exactly how this project was dogfooded before
- * the CLI existed.
- */
+// Files that commonly export the same variables, and would be shadowed. Scanned rather
+// than guessed at, because "your `.envrc` is being ignored" is only useful advice when it
+// names the file.
 const SHELL_FILES = [
     ".bashrc",
     ".bash_profile",
@@ -76,22 +89,23 @@ export function findShadowedExports(cwd = process.cwd()) {
     }
     return found;
 }
-/**
- * The command to write into settings.json for the hook.
- *
- * Prefers the bare name, but only after confirming that `clocktopus` on
- * PATH resolves to *this* executable. Hooks run through a shell whose PATH
- * may differ from the interactive one, and a bare name that does not
- * resolve there fails silently — the session runs fine and every bit of
- * repository context is lost. An absolute path is uglier and survives that;
- * `doctor` checks it still exists.
- */
-export function resolveHookCommand() {
+// The command to write into an agent's hook configuration.
+//
+// Prefers the bare name, but only after confirming `clocktopus` on PATH resolves to *this*
+// executable. Hooks run through a shell whose PATH may differ from the interactive one, and
+// a bare name that does not resolve there fails silently — the session runs fine and every
+// bit of repository context is lost. An absolute path is uglier and survives that.
+//
+// The provider is baked into the command because the two agents send identical hook
+// payloads, with no marker of any kind: which agent is calling can only be known from how
+// the hook was installed.
+export function resolveHookCommand(provider) {
     const script = process.argv[1] ? resolve(process.argv[1]) : null;
     const quote = (value) => /[\s"']/.test(value) ? `"${value}"` : value;
+    const args = `agent hook --provider ${provider}`;
     if (script && resolvesOnPath("clocktopus", script)) {
         return {
-            command: "clocktopus agent hook",
+            command: `clocktopus ${args}`,
             usesAbsolutePath: false,
             binaryPath: script,
         };
@@ -101,13 +115,13 @@ export function resolveHookCommand() {
         // a published package keeps its shebang, but a checkout may not have the
         // executable bit, and the hook must not depend on that.
         return {
-            command: `${quote(process.execPath)} ${quote(script)} agent hook`,
+            command: `${quote(process.execPath)} ${quote(script)} ${args}`,
             usesAbsolutePath: true,
             binaryPath: script,
         };
     }
     return {
-        command: "clocktopus agent hook",
+        command: `clocktopus ${args}`,
         usesAbsolutePath: false,
         binaryPath: null,
     };

package/dist/src/lib/agent-hook-state.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 declare const LastRunSchema: z.ZodObject<{
     at: z.ZodString;
     event: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
     sessionId: z.ZodOptional<z.ZodString>;
     endpoint: z.ZodOptional<z.ZodString>;
     tokenPrefix: z.ZodOptional<z.ZodString>;
@@ -13,20 +14,23 @@ export type HookLastRun = z.infer<typeof LastRunSchema>;
 declare const StartStateSchema: z.ZodObject<{
     sha: z.ZodString;
     cwd: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    closed: z.ZodOptional<z.ZodBoolean>;
+    startedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type HookStartState = z.infer<typeof StartStateSchema>;
-export declare function writeStartState(sessionId: string, sha: string, cwd: string): void;
+export declare function writeStartState(sessionId: string, state: {
+    sha: string;
+    cwd: string;
+    provider: string;
+    closed?: boolean;
+    startedAt?: string;
+}): void;
 export declare function readStartState(sessionId: string): HookStartState | undefined;
 export declare function clearStartState(sessionId: string): void;
 export declare function listStartStates(): Array<{
     sessionId: string;
     ageMs: number;
-    /**
-     * When the state file was last touched — the newest moment this machine
-     * has evidence the session existed. The sweep sends it as the abandoned
-     * session's `ended_at` so the receiver does not stamp its own clock,
-     * hours later, as the end of a window used to attribute commits.
-     */
     lastActivityAt: Date;
 }>;
 export declare function recordLastRun(run: HookLastRun): void;

package/dist/src/lib/agent-hook-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-hook-state.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-hook-state.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6BxB,QAAA,MAAM,aAAa;;;;;;;;;iBAUjB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;iBAGpB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,IAAI,CAWN;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAgB5E;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED,wBAAgB,eAAe,IAAI,KAAK,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,cAAc,EAAE,IAAI,CAAC;CACtB,CAAC,CAsBD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAOpD;AAED,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAShD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAOrC"}
+{"version":3,"file":"agent-hook-state.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-hook-state.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqBxB,QAAA,MAAM,aAAa;;;;;;;;;;iBAYjB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;;;;iBAgBpB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,IAAI,CAUN;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAe5E;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED,wBAAgB,eAAe,IAAI,KAAK,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IAId,cAAc,EAAE,IAAI,CAAC;CACtB,CAAC,CAsBD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAOpD;AAED,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAShD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAOrC"}

package/dist/src/lib/agent-hook-state.js

@@ -2,33 +2,27 @@ import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync,
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
-/**
- * On-disk state the SessionStart/SessionEnd hook keeps between its two
- * invocations, plus the record of what the last invocation achieved.
- *
- * Under the cache directory rather than the repository so it never shows up
- * in `git status`. The path is unchanged from the standalone script this
- * command replaced (`scripts/agent-telemetry/claude-hook.mjs`, since
- * deleted) on purpose: a session that started under the old script must
- * still be able to close under the new one, and a sweep must still find
- * what the old one abandoned.
- */
+// On-disk state the SessionStart/SessionEnd hook keeps between its two invocations, plus
+// the record of what the last invocation achieved.
+//
+// Under the cache directory rather than the repository so it never shows up in
+// `git status`. The path is unchanged from the standalone script this command replaced,
+// on purpose: a session that started under the old script must still close under the new
+// one, and a sweep must still find what the old one abandoned.
 const CACHE_DIR = join(homedir(), ".cache", "clocktopus");
 const STATE_DIR = join(CACHE_DIR, "agent-sessions");
-/**
- * The hook's last outcome, written every run.
- *
- * This is the only place the pipeline reports on itself from the machine's
- * own side. The hook must stay silent — it cannot warn, prompt or print —
- * so instead it leaves a receipt, and `agent status` / `agent doctor` read
- * it. Without this, a token that started returning 401 mid-week is
- * invisible locally: the session runs normally and nothing is written
- * anywhere the user looks.
- */
+// The hook's last outcome, written every run.
+//
+// The only place the pipeline reports on itself from the machine's own side. The hook
+// must stay silent — it cannot warn, prompt or print — so it leaves a receipt, and
+// `agent status` / `agent doctor` read it. Without this, a token that started returning
+// 401 mid-week is invisible locally.
 const LAST_RUN_FILE = join(CACHE_DIR, "agent-hook-last.json");
 const LastRunSchema = z.object({
     at: z.string(),
     event: z.string().optional(),
+    // One receipt file is shared by all of them.
+    provider: z.string().optional(),
     sessionId: z.string().optional(),
     endpoint: z.string().optional(),
     tokenPrefix: z.string().optional(),
@@ -40,16 +34,28 @@ const LastRunSchema = z.object({
 const StartStateSchema = z.object({
     sha: z.string(),
     cwd: z.string().optional(),
+    // The agent that opened this session. Recorded because the sweep runs from whichever
+    // agent starts *next*, and closing a Codex session as `claude_code` would open a second,
+    // empty session row under the wrong provider and leave the real one hanging.
+    provider: z.string().optional(),
+    // Set once the session has had a real SessionEnd, and kept only because its host can send
+    // another one — see `hostRepeatsSessionEnd`. The file still holds the starting SHA the
+    // next SessionEnd needs, but the session is already closed, so the sweep must delete it
+    // rather than close it again with a stale HEAD.
+    closed: z.boolean().optional(),
+    // When SessionStart fired, ISO. Bounds the reflog read SessionEnd declares from —
+    // see `declared-commits.ts`. Optional because sessions opened by an older CLI have
+    // no such stamp, and those declare nothing rather than read an unbounded reflog.
+    startedAt: z.string().optional(),
 });
 const stateFile = (sessionId) => join(STATE_DIR, `${sessionId.replace(/[^\w-]/g, "")}.sha`);
-export function writeStartState(sessionId, sha, cwd) {
+export function writeStartState(sessionId, state) {
     try {
         mkdirSync(STATE_DIR, { recursive: true });
-        // `cwd` is stored alongside the SHA because the sweep runs from
-        // whatever repository the *next* session happens to start in.
-        // Resolving an abandoned session's SHA against the wrong checkout would
-        // either fail or, worse, succeed against an unrelated history.
-        writeFileSync(stateFile(sessionId), JSON.stringify({ sha, cwd }), "utf8");
+        // `cwd` is stored alongside the SHA because the sweep runs from whatever repository the
+        // *next* session happens to start in. Resolving an abandoned session's SHA against the
+        // wrong checkout would either fail or, worse, succeed against an unrelated history.
+        writeFileSync(stateFile(sessionId), JSON.stringify(state), "utf8");
     }
     catch {
         // Losing the start SHA costs the exact commit list, not the session.
@@ -65,8 +71,7 @@ export function readStartState(sessionId) {
             return parsed.success ? parsed.data : undefined;
         }
         catch {
-            // Files written by earlier versions hold a bare SHA. A session that
-            // started under the old format must still close correctly.
+            // Files written by earlier versions hold a bare SHA.
             return { sha: raw };
         }
     }

package/dist/src/lib/agents.d.ts

@@ -0,0 +1,52 @@
+export type AgentId = "claude" | "codex" | "opencode";
+/** How the ingested session is labelled — must match `AgentProvider` in core. */
+export type AgentProviderId = "claude_code" | "codex_cli" | "opencode";
+export type AgentTelemetryState = {
+    token: string | null;
+    endpoint: string | null;
+    /** Per-event, because a half-installed hook pair degrades silently. */
+    hookCommands: Partial<Record<"SessionStart" | "SessionEnd", string>>;
+    /** Newest mtime across the agent's config files, for the restart check. */
+    modifiedAt: Date | null;
+    /** Files we would write, whether or not they exist yet. */
+    paths: string[];
+};
+export type AgentAdapter = {
+    id: AgentId;
+    label: string;
+    provider: AgentProviderId;
+    /** Executable name, used both to detect an install and to name it in help. */
+    binary: string;
+    hostRunsHooksAsync: boolean;
+    hostRepeatsSessionEnd: boolean;
+    /** Files this agent's telemetry configuration lives in. */
+    paths(): string[];
+    read(): AgentTelemetryState;
+    apply(input: {
+        token: string;
+        endpoint: string;
+        hookCommand: string;
+    }): {
+        backupPaths: string[];
+    };
+    remove(): {
+        removed: string[];
+    };
+    pendingActions(): string[];
+    staleReason?(): string | null;
+};
+/** `true` when the parse error is one of ours, whichever agent raised it. */
+export declare function isConfigParseError(error: unknown): error is Error;
+export declare const AGENTS: readonly AgentAdapter[];
+export type AgentSurvey = {
+    agent: AgentAdapter;
+    /** Version string when the binary is on PATH, `null` when it is not. */
+    version: string | null;
+    installed: boolean;
+    /** True once our token is written into this agent's config. */
+    configured: boolean;
+    /** Set when the agent's config exists but could not be parsed. */
+    unreadable: string | null;
+};
+export declare function surveyAgents(): AgentSurvey[];
+//# sourceMappingURL=agents.d.ts.map

package/dist/src/lib/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/lib/agents.ts"],"names":[],"mappings":"AAyDA,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAEtD,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,GAAG,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACrE,2EAA2E;IAC3E,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAKf,kBAAkB,EAAE,OAAO,CAAC;IAU5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,KAAK,IAAI,MAAM,EAAE,CAAC;IAClB,IAAI,IAAI,mBAAmB,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG;QACtE,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAGhC,cAAc,IAAI,MAAM,EAAE,CAAC;IAI3B,WAAW,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAKjE;AAkND,eAAO,MAAM,MAAM,EAAE,SAAS,YAAY,EAIzC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAOF,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAqB5C"}

package/dist/src/lib/agents.js

@@ -0,0 +1,238 @@
+import { execFileSync } from "node:child_process";
+import { applyTelemetrySettings, readInstalledTelemetry, readSettings, removeTelemetrySettings, SettingsParseError, settingsPath, writeSettings, } from "./claude-settings.js";
+import { applyCodexHooks, applyCodexOtel, CodexConfigParseError, codexConfigPath, codexHooksPath, HOOK_EVENT_COUNT, readCodexConfig, readCodexHooks, readCodexHookTrust, readCodexTelemetry, removeCodexHooks, removeCodexOtel, writeCodexConfig, writeCodexHooks, } from "./codex-config.js";
+import { buildOpencodePlugin, OPENCODE_PLUGIN_VERSION, opencodePluginPath, readOpencodePlugin, removeOpencodePlugin, splitCommandLine, writeOpencodePlugin, } from "./opencode-config.js";
+/** `true` when the parse error is one of ours, whichever agent raised it. */
+export function isConfigParseError(error) {
+    return (error instanceof SettingsParseError ||
+        error instanceof CodexConfigParseError);
+}
+const claudeAdapter = {
+    id: "claude",
+    label: "Claude Code",
+    provider: "claude_code",
+    binary: "claude",
+    hostRunsHooksAsync: true,
+    hostRepeatsSessionEnd: false,
+    paths: () => [settingsPath()],
+    read() {
+        const installed = readInstalledTelemetry();
+        return {
+            token: installed.env.CLOCKTOPUS_INGEST_TOKEN ?? null,
+            endpoint: installed.env.CLOCKTOPUS_OTEL_ENDPOINT ?? null,
+            hookCommands: installed.hookCommands,
+            modifiedAt: installed.modifiedAt,
+            paths: [installed.path],
+        };
+    },
+    apply(input) {
+        const current = readSettings();
+        const next = applyTelemetrySettings(current.settings, input);
+        const { backupPath } = writeSettings(next, current.path);
+        return { backupPaths: backupPath ? [backupPath] : [] };
+    },
+    remove() {
+        const current = readSettings();
+        if (!current.exists)
+            return { removed: [] };
+        const result = removeTelemetrySettings(current.settings);
+        if (result.removedEnvKeys.length === 0 && !result.removedHooks)
+            return { removed: [] };
+        writeSettings(result.settings, current.path);
+        return {
+            removed: [
+                ...result.removedEnvKeys,
+                ...(result.removedHooks ? ["SessionStart/SessionEnd hooks"] : []),
+            ],
+        };
+    },
+    pendingActions: () => [],
+};
+const codexAdapter = {
+    id: "codex",
+    label: "Codex CLI",
+    provider: "codex_cli",
+    binary: "codex",
+    hostRunsHooksAsync: false,
+    hostRepeatsSessionEnd: false,
+    paths: () => [codexConfigPath(), codexHooksPath()],
+    read() {
+        const telemetry = readCodexTelemetry();
+        const hooks = readCodexHooks();
+        return {
+            token: telemetry.token,
+            endpoint: telemetry.endpoint,
+            hookCommands: hooks.commands,
+            modifiedAt: newest([telemetry.modifiedAt, hooks.modifiedAt]),
+            paths: [telemetry.path, hooks.path],
+        };
+    },
+    apply(input) {
+        const backupPaths = [];
+        const config = readCodexConfig();
+        const nextText = applyCodexOtel(config, input);
+        const written = writeCodexConfig({
+            path: config.path,
+            previousText: config.text,
+            previousConfig: config.config,
+            nextText,
+        });
+        if (written.backupPath)
+            backupPaths.push(written.backupPath);
+        const hooks = readCodexHooks();
+        const nextHooks = applyCodexHooks(hooks.file, input);
+        const hooksWritten = writeCodexHooks(nextHooks, hooks.path);
+        if (hooksWritten.backupPath)
+            backupPaths.push(hooksWritten.backupPath);
+        return { backupPaths };
+    },
+    remove() {
+        const removed = [];
+        const config = readCodexConfig();
+        if (config.exists) {
+            const { nextText, removedKeys } = removeCodexOtel(config);
+            if (removedKeys.length > 0) {
+                writeCodexConfig({
+                    path: config.path,
+                    previousText: config.text,
+                    previousConfig: config.config,
+                    nextText,
+                });
+                removed.push(...removedKeys.map((key) => `otel.${key}`));
+            }
+        }
+        const hooks = readCodexHooks();
+        if (hooks.exists) {
+            const result = removeCodexHooks(hooks.file);
+            if (result.removed) {
+                writeCodexHooks(result.file, hooks.path);
+                removed.push("SessionStart/SessionEnd hooks");
+            }
+        }
+        return { removed };
+    },
+    pendingActions() {
+        // Codex refuses to run a hooks.json it has not been shown, and there is no way to
+        // approve it from here — the prompt is part of the TUI. Left unsaid, this looks
+        // exactly like a broken install: telemetry arrives, repository context never does.
+        if (!readCodexHooks().exists)
+            return [];
+        const { untrusted } = readCodexHookTrust();
+        if (untrusted.length === 0)
+            return [];
+        // Says what is missing, never what is already fine. Trust is keyed on a hash of the
+        // hook entry, so rewriting hooks.json invalidates every approval it had — `trusted`
+        // can be stale the moment setup runs.
+        const missing = untrusted.length === HOOK_EVENT_COUNT
+            ? "its hooks"
+            : `its ${untrusted.join(" and ")} hook`;
+        return [
+            "Start Codex once and answer 'Trust all and continue' when it asks\n" +
+                `  about ${missing}. Until then Codex records your spend but not the\n` +
+                "  repository it was spent on — it will not run an unapproved hook.",
+        ];
+    },
+};
+const opencodeAdapter = {
+    id: "opencode",
+    label: "OpenCode",
+    provider: "opencode",
+    binary: "opencode",
+    // The plugin runs inside OpenCode's own event loop and does not await the work it
+    // starts, so the hook is already off the critical path by the time it reaches the CLI.
+    hostRunsHooksAsync: true,
+    // `session.idle` is the closest thing OpenCode has to a session end, and it fires
+    // after every turn rather than once.
+    hostRepeatsSessionEnd: true,
+    paths: () => [opencodePluginPath()],
+    read() {
+        const plugin = readOpencodePlugin();
+        return {
+            token: plugin.config?.token ?? null,
+            endpoint: plugin.config?.endpoint ?? null,
+            // Both events come from the one plugin file, so they are installed together or not at
+            // all — unlike the hook agents, where each event can go missing on its own.
+            hookCommands: plugin.config
+                ? {
+                    SessionStart: plugin.config.hookArgv.join(" "),
+                    SessionEnd: plugin.config.hookArgv.join(" "),
+                }
+                : {},
+            modifiedAt: plugin.modifiedAt,
+            paths: [plugin.path],
+        };
+    },
+    apply(input) {
+        const { backupPath } = writeOpencodePlugin(buildOpencodePlugin({
+            endpoint: input.endpoint,
+            token: input.token,
+            hookArgv: splitCommandLine(input.hookCommand),
+        }));
+        return { backupPaths: backupPath ? [backupPath] : [] };
+    },
+    remove() {
+        return { removed: removeOpencodePlugin() ? ["the Clocktopus plugin"] : [] };
+    },
+    pendingActions: () => [],
+    staleReason() {
+        const plugin = readOpencodePlugin();
+        if (!plugin.exists || !plugin.config)
+            return null;
+        if (plugin.version === OPENCODE_PLUGIN_VERSION)
+            return null;
+        return (`the installed plugin was generated by an older CLI ` +
+            `(generation ${plugin.version ?? "unstamped"}, current is ` +
+            `${OPENCODE_PLUGIN_VERSION})`);
+    },
+};
+export const AGENTS = [
+    claudeAdapter,
+    codexAdapter,
+    opencodeAdapter,
+];
+// What is on this machine, and what is already wired up.
+//
+// Detection is by `--version` rather than by config directory: `~/.claude` and
+// `~/.codex` both outlive an uninstall, so a stale directory would offer to configure
+// an agent that is no longer there.
+export function surveyAgents() {
+    return AGENTS.map((agent) => {
+        const version = detectVersion(agent.binary);
+        let configured = false;
+        let unreadable = null;
+        try {
+            configured = agent.read().token !== null;
+        }
+        catch (error) {
+            if (isConfigParseError(error))
+                unreadable = error.message;
+            else
+                throw error;
+        }
+        return {
+            agent,
+            version,
+            installed: version !== null,
+            configured,
+            unreadable,
+        };
+    });
+}
+function detectVersion(binary) {
+    try {
+        const output = execFileSync(binary, ["--version"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+        // Both CLIs print a line with the version somewhere in it; the number is the only
+        // part worth showing.
+        return (/\d+\.\d+\.\d+/.exec(output)?.[0] ?? output.trim().split("\n")[0] ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+function newest(dates) {
+    return dates.reduce((latest, date) => (date && (!latest || date > latest) ? date : latest), null);
+}

package/dist/src/lib/claude-settings.d.ts

@@ -1,36 +1,7 @@
-/**
- * Reads and edits `~/.claude/settings.json` on the user's behalf.
- *
- * Two rules govern everything here, both of them about not destroying a file
- * we do not own:
- *
- * 1. **Never write over JSON we could not parse.** A malformed settings file
- *    is far more likely to be a half-finished edit than something to
- *    overwrite, and overwriting it would lose the user's own hooks,
- *    permissions and MCP servers. Parse failures raise instead.
- * 2. **Only ever touch keys we put there.** Merging into `env` and appending
- *    to `hooks` leaves everything else untouched, and removal matches our
- *    own hook command rather than clearing the arrays.
- */
 export declare const SETTINGS_FILENAME = "settings.json";
 /** Env keys `clocktopus agent setup` owns — and the only ones it removes. */
 export declare const TELEMETRY_ENV_KEYS: readonly ["CLAUDE_CODE_ENABLE_TELEMETRY", "OTEL_METRICS_EXPORTER", "OTEL_EXPORTER_OTLP_PROTOCOL", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_METRICS_INCLUDE_SESSION_ID", "OTEL_METRIC_EXPORT_INTERVAL", "CLOCKTOPUS_INGEST_TOKEN", "CLOCKTOPUS_OTEL_ENDPOINT"];
-/**
- * How often Claude Code's exporter ships metrics.
- *
- * Also the resolution of every "last export received" answer the status
- * command can give — a session that started 30s ago has genuinely not
- * exported yet, which is why status treats silence under one interval as
- * "waiting" rather than "broken".
- */
 export declare const METRIC_EXPORT_INTERVAL_MS = 60000;
-/**
- * Seconds Claude Code will wait for the hook before giving up on it.
- *
- * Comfortably above the hook's own 4s request timeout, so a slow network
- * produces the hook's own recorded failure — which `agent doctor` can read
- * back — rather than a kill from the host, which leaves no trace anywhere.
- */
 export declare const HOOK_TIMEOUT_SECONDS = 10;
 export type ClaudeSettings = Record<string, unknown>;
 export declare class SettingsParseError extends Error {
@@ -45,13 +16,6 @@ export declare function readSettings(path?: string): {
     modifiedAt: Date | null;
     settings: ClaudeSettings;
 };
-/**
- * Writes settings, keeping a one-deep backup of what was there before.
- *
- * The rename is what makes it atomic: a crash midway leaves either the old
- * file or the new one, never a truncated file that Claude Code would refuse
- * to start with.
- */
 export declare function writeSettings(settings: ClaudeSettings, path?: string): {
     backupPath: string | null;
 };

package/dist/src/lib/claude-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-settings.d.ts","sourceRoot":"","sources":["../../../src/lib/claude-settings.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,yRAUrB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASrD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAMzC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,YAAY,CAAC,IAAI,SAAiB,GAAG;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CA6BA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,IAAI,SAAiB,GACpB;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiB/B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBzB;AAED,QAAA,MAAM,WAAW,yCAA0C,CAAC;AAqC5D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D,cAAc,CA6ChB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG;IACjE,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;CACvB,CAmCA;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,IAAI,SAAiB,GAAG;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CACrE,CAmCA"}
+{"version":3,"file":"claude-settings.d.ts","sourceRoot":"","sources":["../../../src/lib/claude-settings.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,yRAUrB,CAAC;AAKX,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAMhD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASrD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAMzC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,YAAY,CAAC,IAAI,SAAiB,GAAG;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CA6BA;AAKD,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,IAAI,SAAiB,GACpB;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiB/B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBzB;AAED,QAAA,MAAM,WAAW,yCAA0C,CAAC;AAgC5D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D,cAAc,CA0ChB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG;IACjE,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;CACvB,CAmCA;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,IAAI,SAAiB,GAAG;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CACrE,CAmCA"}