@blastin-dev/clocktopus-cli 0.2.1 → 0.3.1

package/dist/src/lib/agents.js

@@ -112,20 +112,17 @@ const codexAdapter = {
         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.
+        // 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 already had — `trusted` can be stale the moment setup
-        // runs, and promising the user that half of it is done would be a lie
-        // as often as not.
+        // 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`;
@@ -141,12 +138,11 @@ const opencodeAdapter = {
     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. Re-spawning would only add a process.
+    // 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.
+    // `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() {
@@ -154,9 +150,8 @@ const opencodeAdapter = {
         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 is
-            // a separate entry that can go missing on its own.
+            // 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(" "),
@@ -195,13 +190,11 @@ export const AGENTS = [
     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.
- */
+// 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);
@@ -232,8 +225,8 @@ function detectVersion(binary) {
             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, and neither format is worth parsing hard.
+        // 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 {

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/auth.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA4BnE;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CA8CrB;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/lib/auth.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA4BnE;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CA0DrB;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/src/lib/auth.js

@@ -38,6 +38,17 @@ export async function pollForToken(deviceCode, interval) {
             grant_type: "urn:ietf:params:oauth:grant-type:device_code",
         }),
     });
+    // The web app rate-limits `/device/token` on top of the interval this loop
+    // already respects, and a 429 carries Better Auth's own body — no `error`
+    // field — so it used to fall through to "Unexpected response" and kill a
+    // login that was doing nothing wrong. Back off and keep waiting instead.
+    if (response.status === 429) {
+        const retryAfter = Number(response.headers.get("x-retry-after"));
+        return {
+            status: "slow_down",
+            newInterval: retryAfter > 0 ? retryAfter + interval : interval + 5,
+        };
+    }
     const data = (await response.json());
     if ("access_token" in data) {
         return { status: "success", accessToken: data.access_token };

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"}

package/dist/src/lib/claude-settings.js

@@ -1,20 +1,16 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-/**
- * 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.
- */
+// Reads and edits `~/.claude/settings.json` on the user's behalf.
+//
+// Two rules govern everything here, both 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
+//    would lose the user's own hooks, permissions and MCP servers.
+// 2. Only ever touch keys we put there. Merging into `env` and appending to `hooks`
+//    leaves everything else alone, and removal matches our own hook command rather
+//    than clearing the arrays.
 export const SETTINGS_FILENAME = "settings.json";
 /** Env keys `clocktopus agent setup` owns — and the only ones it removes. */
 export const TELEMETRY_ENV_KEYS = [
@@ -28,22 +24,14 @@ export const TELEMETRY_ENV_KEYS = [
     "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".
- */
+// How often Claude Code's exporter ships metrics — and the resolution of every "last
+// export received" answer status can give, which is why silence under one interval
+// reads as "waiting" rather than "broken".
 export const METRIC_EXPORT_INTERVAL_MS = 60_000;
-/**
- * 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.
- */
+// Seconds Claude Code will wait for the hook. 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.
 export const HOOK_TIMEOUT_SECONDS = 10;
 export class SettingsParseError extends Error {
     path;
@@ -54,8 +42,8 @@ export class SettingsParseError extends Error {
     }
 }
 export function claudeConfigDir() {
-    // Claude Code honours CLAUDE_CONFIG_DIR; following it means setup writes
-    // where that installation actually reads.
+    // Claude Code honours CLAUDE_CONFIG_DIR; following it means setup writes where that
+    // installation actually reads.
     return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
 }
 export function settingsPath() {
@@ -67,8 +55,8 @@ export function readSettings(path = settingsPath()) {
     }
     const raw = readFileSync(path, "utf8");
     const modifiedAt = statSync(path).mtime;
-    // An empty file is a normal state (some installers touch it) and is safe
-    // to treat as an empty object; anything else that fails to parse is not.
+    // An empty file is a normal state (some installers touch it) and is safe to treat as
+    // an empty object; anything else that fails to parse is not.
     if (raw.trim() === "") {
         return { path, exists: true, modifiedAt, settings: {} };
     }
@@ -90,13 +78,9 @@ export function readSettings(path = settingsPath()) {
         throw new SettingsParseError(path);
     }
 }
-/**
- * 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.
- */
+// Writes settings, keeping a one-deep backup. The rename is what makes it atomic: a
+// crash midway leaves either the old file or the new one, never a truncated file
+// Claude Code would refuse to start with.
 export function writeSettings(settings, path = settingsPath()) {
     mkdirSync(dirname(path), { recursive: true });
     let backupPath = null;
@@ -117,13 +101,12 @@ export function buildTelemetryEnv(input) {
     return {
         CLAUDE_CODE_ENABLE_TELEMETRY: "1",
         OTEL_METRICS_EXPORTER: "otlp",
-        // The receiver answers protobuf with an explicit 415 rather than a
-        // parse error, but only JSON actually works.
+        // The receiver answers protobuf with an explicit 415, but only JSON actually works.
         OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
         OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
         OTEL_EXPORTER_OTLP_HEADERS: `Authorization=Bearer ${input.token}`,
-        // Without the session id the metric stream cannot be joined to the hook
-        // stream, and every session loses its repository and branch.
+        // Without the session id the metric stream cannot be joined to the hook stream, and
+        // every session loses its repository and branch.
         OTEL_METRICS_INCLUDE_SESSION_ID: "true",
         OTEL_METRIC_EXPORT_INTERVAL: String(METRIC_EXPORT_INTERVAL_MS),
         // The hook's own channel. Same token, different transport.
@@ -132,15 +115,10 @@ export function buildTelemetryEnv(input) {
     };
 }
 const HOOK_EVENTS = ["SessionStart", "SessionEnd"];
-/**
- * Recognises a hook entry as ours, across every spelling we have shipped.
- *
- * The `claude-hook.mjs` clause matters for upgrades: before this command
- * existed the hook was a script inside a checkout of the Clocktopus repo,
- * and anyone who set that up by hand still has it. Failing to recognise it
- * would leave it installed next to the new one and POST every SessionStart
- * twice.
- */
+// Recognises a hook entry as ours, across every spelling we have shipped. The
+// `claude-hook.mjs` clause matters for upgrades: before this command existed the hook
+// was a script inside a checkout of this repo, and anyone who set that up by hand
+// still has it. Failing to recognise it would POST every SessionStart twice.
 function isClocktopusHook(entry) {
     const command = typeof entry.command === "string" ? entry.command : "";
     if (/claude-hook\.mjs/.test(command))
@@ -157,8 +135,8 @@ function withoutOurHooks(matchers) {
         ...matcher,
         hooks: (matcher.hooks ?? []).filter((entry) => !isClocktopusHook(entry)),
     }))
-        // A matcher group that only ever held our hook is ours to remove; one
-        // that still has entries belongs to the user and stays.
+        // A matcher group that only ever held our hook is ours to remove; one that still has
+        // entries belongs to the user and stays.
         .filter((matcher) => (matcher.hooks ?? []).length > 0));
 }
 export function applyTelemetrySettings(settings, input) {
@@ -174,9 +152,8 @@ export function applyTelemetrySettings(settings, input) {
         : {};
     const hooks = { ...existingHooks };
     for (const event of HOOK_EVENTS) {
-        // Remove-then-append rather than append: re-running setup after a
-        // reinstall must not leave two hooks firing per session, which would
-        // double every SessionStart POST.
+        // Remove-then-append rather than append: re-running setup after a reinstall must not
+        // leave two hooks firing per session, which would double every SessionStart POST.
         hooks[event] = [
             ...withoutOurHooks(asMatchers(existingHooks[event])),
             {
@@ -184,10 +161,8 @@ export function applyTelemetrySettings(settings, input) {
                     {
                         type: "command",
                         command: input.hookCommand,
-                        // Both fields are about not making the user wait on telemetry.
-                        // The hook does network I/O — its own POST, plus a sweep of
-                        // abandoned sessions at SessionStart — and running it inline
-                        // would add that latency to the start of every session.
+                        // Both fields are about not making the user wait on telemetry: the hook does network
+                        // I/O, and running it inline would add that latency to the start of every session.
                         timeout: HOOK_TIMEOUT_SECONDS,
                         async: true,
                     },

package/dist/src/lib/codex-config.d.ts

@@ -1,48 +1,6 @@
-/**
- * Reads and edits Codex CLI's configuration on the user's behalf.
- *
- * Codex splits what Claude Code keeps in one file: telemetry goes in
- * `~/.codex/config.toml` under `[otel]`, hooks go in a separate
- * `~/.codex/hooks.json`. Both are edited here under the same two rules as
- * `claude-settings.ts` — never write over something we could not parse, and
- * only ever touch keys we put there — plus a third that TOML forces on us:
- *
- * **Splice, don't re-serialise.** A round trip through a TOML parser throws
- * away every comment and blank line in the file. `config.toml` is a file
- * people hand-write and annotate, so only the `[otel]` region is replaced
- * textually; everything else survives byte for byte. `writeCodexConfig`
- * re-parses the spliced result and refuses to write if anything outside
- * `[otel]` moved, which is what makes the textual approach safe.
- *
- * ## What Codex does with these, and why it matters here
- *
- * - `otel.exporter` is the **log** exporter, and Codex POSTs to the URL
- *   verbatim — it does not append `/v1/logs` the way the OTel SDK does. The
- *   path is therefore part of the configured endpoint, and
- *   `readCodexTelemetry` strips it back off to recover the receiver base.
- * - Codex will not run a `hooks.json` it has not been shown: the first
- *   session after this file changes prompts "Hooks need review" and
- *   persists the answer under `[hooks.state]`. Setup cannot do that for the
- *   user, so it tells them instead — see `setup.ts`.
- */
 export declare const CODEX_CONFIG_FILENAME = "config.toml";
 export declare const CODEX_HOOKS_FILENAME = "hooks.json";
-/**
- * The receiver path Codex's log exporter is pointed at.
- *
- * Load-bearing in both directions: written onto the endpoint because Codex
- * sends to the literal URL, and stripped when reading because the hook and
- * `/v1/verify` need the base.
- */
 export declare const CODEX_LOGS_PATH = "/v1/logs";
-/**
- * Seconds Codex will wait for each hook.
- *
- * SessionEnd is 3 rather than 10 because Codex hard-clamps it to 3 and
- * prints `warning: clamping SessionEnd hook timeout to 3s` on every single
- * session start otherwise — a permanent warning about a value we chose is
- * worse than the shorter budget, and the hook's own request timeout is 4s.
- */
 export declare const CODEX_HOOK_TIMEOUT_SECONDS: {
     SessionStart: number;
     SessionEnd: number;
@@ -70,23 +28,7 @@ export declare function buildCodexOtel(input: {
     token: string;
     endpoint: string;
 }): TomlTable;
-/**
- * Replaces the `[otel]` region of a TOML document, preserving everything else.
- *
- * Returns the new text. Region detection is deliberately dumb — table
- * headers only — and `writeCodexConfig` verifies the result by re-parsing,
- * so a document this misreads is refused rather than mangled.
- */
 export declare function spliceOtelSection(text: string, otel: TomlTable | null): string;
-/**
- * Writes config.toml, keeping a one-deep backup and verifying the splice.
- *
- * The verification is the point: it re-parses what is about to be written
- * and compares every top-level key *except* `otel` against what was there
- * before. If the textual splice disturbed anything else — an exotic layout
- * the region scanner misread — the write is refused with the user's file
- * still intact.
- */
 export declare function writeCodexConfig(input: {
     path?: string;
     previousText: string;
@@ -137,27 +79,6 @@ export declare function removeCodexHooks(file: Record<string, unknown>): {
 export declare function writeCodexHooks(file: Record<string, unknown>, path?: string): {
     backupPath: string | null;
 };
-/**
- * Which of our hooks Codex has been shown and told to run.
- *
- * Trust is recorded **per hook entry**, not per file:
- *
- * ```toml
- * [hooks.state."/home/you/.codex/hooks.json:session_end:0:0"]
- * trusted_hash = "sha256:…"
- * ```
- *
- * The key is `<path>:<event>:<group index>:<hook index>`, with the event in
- * snake_case. Per-entry granularity is why this reports each event rather
- * than a single boolean: partial trust is a real state, and the one that
- * matters. A machine whose `SessionEnd` is trusted and whose `SessionStart`
- * is not records spend with no repository attached to it — which is exactly
- * what an `async: true` SessionStart used to produce on Codex 0.147, since
- * the hook was skipped before it could ever be offered for approval.
- *
- * The hash is Codex's own and is not recomputed here; changing `hooks.json`
- * invalidates it and Codex re-prompts, which is the behaviour we want.
- */
 export declare function readCodexHookTrust(path?: string): {
     trusted: HookEvent[];
     untrusted: HookEvent[];

package/dist/src/lib/codex-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex-config.d.ts","sourceRoot":"","sources":["../../../src/lib/codex-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex-config.d.ts","sourceRoot":"","sources":["../../../src/lib/codex-config.ts"],"names":[],"mappings":"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"}