@blastin-dev/clocktopus-cli 0.1.4 → 0.2.1

package/dist/src/commands/agent/setup.js

@@ -0,0 +1,333 @@
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { findShadowedExports, maskToken, resolveHookCommand, } from "../../lib/agent-config.js";
+import { verifyReceiver } from "../../lib/agent-receiver.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
+import { ApiError, get, post } from "../../lib/api.js";
+import { isLoggedIn, setAgentConfig } from "../../lib/config.js";
+import { labelled } from "../../lib/format.js";
+import { fetchRepoStatus, renderRepoBlock } from "../../lib/repo-guidance.js";
+import { AgentEndpointSchema, IngestTokenSchema, UserSchema, } from "../../lib/validators.js";
+/**
+ * Configures this machine's coding agents to report spend to Clocktopus.
+ *
+ * One command, however many agents are installed. It looks for each
+ * supported CLI on PATH and configures what it finds — silently when
+ * there is only one, after a prompt when there are several, and from
+ * `--agent` when there is neither a person nor a terminal to ask.
+ *
+ * Everything for a given agent lands in that agent's own config, and
+ * nowhere else. A single source of truth per agent is not a tidiness
+ * preference: it is what makes `agent doctor` able to say which value is in
+ * force. Configuration spread over `.envrc`, a shell profile and a CLI
+ * config file can be reported on but never resolved, and this project
+ * already lost real spend to exactly that (one session split across two
+ * accounts, silently, because two files disagreed about the token).
+ *
+ * Idempotent by default. Re-running repairs the hooks and refreshes the
+ * endpoint while keeping the existing token, so the common case — "did my
+ * setup drift?" — costs nothing, and adding a newly-installed agent later
+ * reuses the token the first one already has. `--force` mints a
+ * replacement instead.
+ */
+export async function setupCommand(options) {
+    if (!isLoggedIn()) {
+        console.error("Not logged in. Run 'clocktopus login' first.");
+        process.exit(1);
+    }
+    const survey = surveyAgents();
+    const unreadable = survey.filter((entry) => entry.unreadable);
+    if (unreadable.length > 0) {
+        for (const entry of unreadable)
+            console.error(`✗ ${entry.unreadable}`);
+        process.exit(1);
+    }
+    const installed = survey.filter((entry) => entry.installed);
+    if (installed.length === 0) {
+        console.error("No supported coding agent found on PATH.");
+        console.error(`\nClocktopus can track: ${survey
+            .map((entry) => `${entry.agent.label} (${entry.agent.binary})`)
+            .join(", ")}.`);
+        console.error("Install one, or re-run with --agent <id> if yours lives somewhere PATH\ncannot see.");
+        process.exit(1);
+    }
+    const selected = await selectAgents(survey, installed, options.agent);
+    if (selected.length === 0) {
+        console.log("Nothing selected — no configuration was changed.");
+        return;
+    }
+    let email = null;
+    let endpoint;
+    try {
+        const [user, endpointResponse] = await Promise.all([
+            get("/api/auth/me").then((data) => UserSchema.parse(data)),
+            get("/api/agent/ingest-token").then((data) => AgentEndpointSchema.parse(data)),
+        ]);
+        email = user.user.email;
+        endpoint = endpointResponse.endpoint;
+    }
+    catch (error) {
+        reportApiFailure(error, "Failed to reach Clocktopus");
+        return;
+    }
+    // One machine, one token, however many agents. Reuse before minting:
+    // every mint leaves another live token on the account, and a machine that
+    // already has a working one has nothing to gain from a second — the
+    // reason to re-run setup is almost always a broken hook path or a newly
+    // installed agent, not a bad token.
+    let token = options.force ? null : findExistingToken(survey);
+    let tokenId = null;
+    let minted = false;
+    if (token) {
+        const check = await verifyReceiver(endpoint, token);
+        if (!check.ok) {
+            console.log(check.reason === "invalid_token"
+                ? "Existing token was rejected by the receiver — minting a replacement."
+                : "Could not confirm the existing token — minting a replacement.");
+            token = null;
+        }
+    }
+    if (!token) {
+        try {
+            const response = await post("/api/agent/ingest-token", {
+                name: options.name ?? hostname(),
+            }).then((data) => IngestTokenSchema.parse(data));
+            token = response.token;
+            tokenId = response.tokenId;
+            endpoint = response.endpoint;
+            minted = true;
+        }
+        catch (error) {
+            reportApiFailure(error, "Failed to mint an ingest token");
+            return;
+        }
+    }
+    const configured = [];
+    for (const entry of selected) {
+        const hook = resolveHookCommand(entry.agent.provider);
+        try {
+            const { backupPaths } = entry.agent.apply({
+                token,
+                endpoint,
+                hookCommand: hook.command,
+            });
+            configured.push({
+                entry,
+                hookCommand: hook.command,
+                hookUsesAbsolutePath: hook.usesAbsolutePath,
+                backupPaths,
+            });
+        }
+        catch (error) {
+            // One agent failing must not strand the others half-configured, so
+            // the loop continues and the failure is reported in the summary.
+            console.error(`✗ ${entry.agent.label}: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+    }
+    if (configured.length === 0) {
+        console.error("\nNothing was configured.");
+        process.exit(1);
+    }
+    setAgentConfig({
+        tokenId: tokenId ?? undefined,
+        tokenPrefix: maskToken(token),
+        endpoint,
+        configuredAt: new Date().toISOString(),
+    });
+    const check = await verifyReceiver(endpoint, token);
+    console.log("\nClocktopus agent telemetry\n");
+    if (email)
+        console.log(labelled("Account", email));
+    console.log(labelled("Receiver", endpoint));
+    console.log(labelled("Token", `${maskToken(token)}${minted ? "  (new)" : "  (reused)"}`));
+    for (const { entry, hookCommand, backupPaths } of configured) {
+        console.log(`\n${entry.agent.label} ${entry.version ?? ""}`.trimEnd());
+        for (const path of entry.agent.paths()) {
+            console.log(labelled("Config", path));
+        }
+        console.log(labelled("Hook", `${hookCommand}  (SessionStart, SessionEnd)`));
+        for (const backup of backupPaths)
+            console.log(labelled("Backup", backup));
+    }
+    console.log("");
+    console.log(check.ok
+        ? "✓ The receiver accepted this token."
+        : `✗ The receiver did not accept this token (${describeCheck(check)}).`);
+    // Configuring this machine is only half the job: sessions will arrive,
+    // but whether they mean anything depends on the repository being attached
+    // to a project and on commits reaching us. Both are invisible from here,
+    // and staying quiet about them is how spend ends up stranded.
+    const repoStatus = await fetchRepoStatus();
+    if (repoStatus) {
+        for (const line of renderRepoBlock(repoStatus))
+            console.log(line);
+    }
+    for (const warning of collectWarnings(configured)) {
+        console.log(`\n${warning}`);
+    }
+    // The single most common reason a correct setup appears dead. Both the
+    // exporter and the hook read their configuration once, when the process
+    // starts, so a session already running will never see any of this.
+    console.log(`\nRestart ${labelList(configured.map((c) => c.entry.agent.label))} — the exporter and the hook\nread their configuration once, at process start.`);
+    // Agent-specific steps a person still has to take, most importantly
+    // Codex's hook trust prompt, which no command can answer for them.
+    for (const { entry } of configured) {
+        for (const action of entry.agent.pendingActions()) {
+            console.log(`\n→ ${entry.agent.label}: ${action}`);
+        }
+    }
+    console.log("\nThen confirm it end to end:  clocktopus agent status");
+}
+/**
+ * Decides which agents to configure, asking only when the answer is
+ * genuinely ambiguous.
+ *
+ * The precedence is about respecting what the caller already told us:
+ * `--agent` is an explicit instruction, a lone install has no decision in
+ * it, and a non-interactive shell has nobody to ask — so only a person at a
+ * terminal with a real choice ever sees a prompt.
+ */
+async function selectAgents(survey, installed, requested) {
+    if (requested && requested.length > 0) {
+        const ids = requested.flatMap((value) => value.split(",").map((part) => part.trim().toLowerCase()));
+        const chosen = survey.filter((entry) => ids.includes(entry.agent.id));
+        const unknown = ids.filter((id) => !survey.some((entry) => entry.agent.id === id));
+        if (unknown.length > 0) {
+            console.error(`Unknown agent: ${unknown.join(", ")}. Valid ids: ${survey
+                .map((entry) => entry.agent.id)
+                .join(", ")}.`);
+            process.exit(1);
+        }
+        // Deliberately not filtered by `installed`: --agent is an instruction,
+        // and someone pointing it at an agent PATH cannot see has said what they
+        // want. Setup writes the config; the agent picks it up when it appears.
+        for (const entry of chosen) {
+            if (!entry.installed) {
+                console.log(`⚠ ${entry.agent.label} was not found on PATH — configuring it anyway.`);
+            }
+        }
+        return chosen;
+    }
+    if (installed.length === 1)
+        return installed;
+    if (!process.stdin.isTTY) {
+        console.log(`Configuring every agent found: ${labelList(installed.map((entry) => entry.agent.label))}.\nPass --agent <id> to narrow it.`);
+        return installed;
+    }
+    console.log("\nAgents on this machine\n");
+    installed.forEach((entry, index) => {
+        const state = entry.configured ? "already configured" : "not configured";
+        console.log(`  ${index + 1}  ${entry.agent.label.padEnd(14)}${(entry.version ?? "").padEnd(10)}${state}`);
+    });
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question("\nWhich should report to Clocktopus? [all]: ")).trim();
+        if (answer === "" || answer.toLowerCase() === "all")
+            return installed;
+        const picked = answer
+            .split(/[,\s]+/)
+            .filter(Boolean)
+            .flatMap((part) => {
+            const index = Number(part);
+            if (Number.isInteger(index) && index >= 1 && index <= installed.length)
+                return [installed[index - 1]];
+            const byId = installed.find((entry) => entry.agent.id === part.toLowerCase() ||
+                entry.agent.binary === part.toLowerCase());
+            return byId ? [byId] : [];
+        });
+        return [...new Set(picked)];
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * The token this machine already has, from whichever agent holds one.
+ *
+ * Reading across agents is what makes "install Codex next month and re-run
+ * setup" cost nothing: the new agent inherits the token the old one has
+ * been using rather than minting a second one against the same machine.
+ */
+function findExistingToken(survey) {
+    for (const entry of survey) {
+        try {
+            const token = entry.agent.read().token;
+            if (token)
+                return token;
+        }
+        catch (error) {
+            if (!isConfigParseError(error))
+                throw error;
+        }
+    }
+    return null;
+}
+function collectWarnings(configured) {
+    const warnings = [];
+    // Only Claude Code applies config `env` over the inherited environment,
+    // so only Claude Code can silently shadow a shell export. Codex reads its
+    // token straight out of config.toml and has nothing to shadow.
+    if (configured.some(({ entry }) => entry.agent.id === "claude")) {
+        const shadowed = findShadowedExports();
+        if (shadowed.length > 0) {
+            const lines = shadowed
+                .map(({ path, keys }) => `    ${path} — ${keys.join(", ")}`)
+                .join("\n");
+            warnings.push(`⚠ These files export the same variables:\n${lines}\n` +
+                "  settings.json is applied over the inherited environment, so those\n" +
+                "  exports are now ignored inside Claude Code. Remove them — two\n" +
+                "  sources that disagree is how spend ends up on the wrong account.");
+        }
+    }
+    // A versioned config directory means the ingest token is about to be
+    // committed. Worth saying plainly; the CLI cannot prevent it.
+    const versioned = new Set();
+    for (const { entry } of configured) {
+        for (const path of entry.agent.paths()) {
+            const dir = dirname(path);
+            if (existsSync(join(dir, ".git")))
+                versioned.add(dir);
+        }
+    }
+    for (const dir of versioned) {
+        warnings.push(`⚠ ${dir} is a git repository, and its config now holds your ingest\n` +
+            "  token in plaintext. Ignore the file, or revoke with\n" +
+            "  'clocktopus agent disable --revoke' if it gets committed.");
+    }
+    const absolute = configured.filter((c) => c.hookUsesAbsolutePath);
+    if (absolute.length > 0) {
+        warnings.push("⚠ 'clocktopus' is not on PATH as this executable, so the hook was\n" +
+            "  installed with an absolute path. Reinstalling the CLI elsewhere will\n" +
+            "  break it — re-run 'clocktopus agent setup' if that happens.");
+    }
+    return warnings;
+}
+function labelList(labels) {
+    if (labels.length <= 1)
+        return labels[0] ?? "";
+    return `${labels.slice(0, -1).join(", ")} and ${labels[labels.length - 1]}`;
+}
+function describeCheck(check) {
+    switch (check.reason) {
+        case "invalid_token":
+            return "401 — token unknown or revoked";
+        case "unexpected_status":
+            return `HTTP ${check.status}`;
+        case "unreachable":
+            return check.message;
+    }
+}
+function reportApiFailure(error, prefix) {
+    if (error instanceof ApiError && error.status === 401) {
+        console.error("Session expired. Run 'clocktopus login' again.");
+    }
+    else if (error instanceof Error) {
+        console.error(`${prefix}: ${error.message}`);
+    }
+    else {
+        console.error(`${prefix}: unknown error`);
+    }
+    process.exit(1);
+}

package/dist/src/commands/agent/status.d.ts

@@ -0,0 +1,2 @@
+export declare function statusCommand(): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/src/commands/agent/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/status.ts"],"names":[],"mappings":"AA2BA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAoFnD"}

package/dist/src/commands/agent/status.js

@@ -0,0 +1,182 @@
+import { differenceInMilliseconds, parseISO } from "date-fns";
+import { readLastRun } from "../../lib/agent-hook-state.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
+import { ApiError, get } from "../../lib/api.js";
+import { isLoggedIn } from "../../lib/config.js";
+import { formatAgo, labelled, microUsdToDisplay } from "../../lib/format.js";
+import { AgentStatusSchema } from "../../lib/validators.js";
+/**
+ * Answers "is agent telemetry actually connected?" from received data.
+ *
+ * Deliberately server-first. Local configuration is a claim — the files can
+ * be perfect while nothing arrives, because an exporter reads its
+ * configuration once at process start, agents swallow OTLP transport
+ * errors, and a revoked token produces a 401 nobody sees.
+ *
+ * The two lanes are reported separately because they fail separately, and
+ * the asymmetric failure is the expensive one: hooks landing while spend
+ * does not produces sessions with a repository, a branch and no cost, which
+ * reads as cheap work rather than a severed pipeline. A single "connected"
+ * line would hide precisely the case worth surfacing.
+ */
+/** Past this, a lane has been quiet long enough to be worth flagging. */
+const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+export async function statusCommand() {
+    if (!isLoggedIn()) {
+        console.error("Not logged in. Run 'clocktopus login' first.");
+        process.exit(1);
+    }
+    let status;
+    try {
+        status = await get("/api/agent/status").then((data) => AgentStatusSchema.parse(data));
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 401) {
+            console.error("Session expired. Run 'clocktopus login' again.");
+        }
+        else {
+            console.error(`Failed to fetch agent status: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+        process.exit(1);
+    }
+    const hookAge = ageOf(status.hookLane.lastSessionStartedAt);
+    const metricsAge = ageOf(status.metricsLane.lastExportReceivedAt);
+    console.log("\nAgent telemetry\n");
+    console.log(labelled("Receiver", status.endpoint));
+    console.log("\nLanes (what the receiver has stored)\n");
+    console.log(labelled("Hook lane", `${mark(hookAge)}  ${formatAgo(status.hookLane.lastSessionStartedAt)}`, 14));
+    if (status.hookLane.repositoryUrl || status.hookLane.cwd) {
+        const where = status.hookLane.repositoryUrl ?? status.hookLane.cwd;
+        const branch = status.hookLane.gitBranch
+            ? ` @ ${status.hookLane.gitBranch}`
+            : "";
+        console.log(labelled("", `${where}${branch}`, 14));
+    }
+    if (status.hookLane.attributed === false) {
+        console.log(labelled("", "not attributed to a project — see 'agent doctor'", 14));
+    }
+    console.log(labelled("Spend lane", `${mark(metricsAge)}  ${formatAgo(status.metricsLane.lastExportReceivedAt)}`, 14));
+    if (status.metricsLane.lastModel) {
+        console.log(labelled("", status.metricsLane.lastModel, 14));
+    }
+    console.log("\nLast 7 days\n");
+    console.log(labelled("Sessions", String(status.window.sessions)));
+    console.log(labelled("Spend", microUsdToDisplay(status.window.costMicroUsd)));
+    if (status.window.unattributedSessions > 0) {
+        console.log(labelled("Unattributed", `${status.window.unattributedSessions} session(s) — no matching project`));
+    }
+    const local = readLocalSummary();
+    if (local.length > 0) {
+        console.log("\nThis machine\n");
+        for (const line of local)
+            console.log(line);
+    }
+    for (const diagnosis of diagnose({ hookAge, metricsAge })) {
+        console.log(`\n${diagnosis}`);
+    }
+}
+function ageOf(value) {
+    if (!value)
+        return null;
+    try {
+        return differenceInMilliseconds(new Date(), parseISO(value));
+    }
+    catch {
+        return null;
+    }
+}
+function mark(ageMs) {
+    if (ageMs === null)
+        return "✗";
+    return ageMs > STALE_AFTER_MS ? "⚠" : "✓";
+}
+/**
+ * The asymmetric-failure callouts — the reason the lanes are split.
+ *
+ * Each names the single next action, because "one lane is quiet" is only
+ * actionable once you know which half of the pipeline it implicates.
+ */
+function diagnose(input) {
+    const { hookAge, metricsAge } = input;
+    const hookLive = hookAge !== null && hookAge <= STALE_AFTER_MS;
+    const metricsLive = metricsAge !== null && metricsAge <= STALE_AFTER_MS;
+    if (hookAge === null && metricsAge === null) {
+        return [
+            "✗ Nothing has ever arrived. Run 'clocktopus agent doctor' to find out\n" +
+                "  where it stops.",
+        ];
+    }
+    if (hookLive && !metricsLive) {
+        return [
+            "⚠ Sessions are arriving with repository context, but no spend is.\n" +
+                "  The telemetry exporter is not reaching the receiver — every session\n" +
+                "  will show $0.00, which is indistinguishable from cheap work. Check\n" +
+                "  the exporter config with 'clocktopus agent doctor'.",
+        ];
+    }
+    if (metricsLive && !hookLive) {
+        return [
+            "⚠ Spend is arriving, but no repository context is. The SessionStart /\n" +
+                "  SessionEnd hook is not running, and no telemetry stream carries path\n" +
+                "  data at all — so these sessions cannot be attributed to a project.\n" +
+                "  Check the hook with 'clocktopus agent doctor'.",
+        ];
+    }
+    return [];
+}
+function readLocalSummary() {
+    const lines = [];
+    // Every agent, not just the configured ones: an installed agent that is
+    // *not* reporting is the thing worth seeing here, and it is invisible in
+    // the server-side lanes above — its sessions simply never arrive.
+    const survey = surveyAgents().filter((entry) => entry.installed || entry.configured || entry.unreadable);
+    if (survey.length === 0) {
+        lines.push(labelled("Agents", "none found on PATH"));
+        return lines;
+    }
+    let anyConfigured = false;
+    for (const entry of survey) {
+        if (entry.unreadable) {
+            lines.push(labelled(entry.agent.label, "config unreadable — see 'agent doctor'"));
+            continue;
+        }
+        if (!entry.configured) {
+            lines.push(labelled(entry.agent.label, `not reporting — run 'clocktopus agent setup --agent ${entry.agent.id}'`));
+            continue;
+        }
+        anyConfigured = true;
+        const pending = safePendingActions(entry.agent);
+        lines.push(labelled(entry.agent.label, pending.length > 0
+            ? "configured, waiting on approval — see 'agent doctor'"
+            : "configured"));
+    }
+    if (!anyConfigured)
+        return lines;
+    // The hook's own receipt of its last run. It cannot print or warn during a
+    // session, so this is the only place a 401 or a connection failure from
+    // the machine's side becomes visible.
+    const lastRun = readLastRun();
+    if (lastRun) {
+        const outcome = lastRun.status === null || lastRun.status === undefined
+            ? `failed — ${lastRun.error ?? "no response"}`
+            : lastRun.status >= 200 && lastRun.status < 300
+                ? `HTTP ${lastRun.status}`
+                : `HTTP ${lastRun.status} — rejected`;
+        lines.push(labelled("Last hook", `${formatAgo(lastRun.at)} (${lastRun.event ?? "?"}${lastRun.provider ? `, ${lastRun.provider}` : ""}) ${outcome}`));
+    }
+    else {
+        lines.push(labelled("Last hook", "has not run since setup"));
+    }
+    return lines;
+}
+/** `pendingActions` reads config; a broken file must not fail `status`. */
+function safePendingActions(agent) {
+    try {
+        return agent.pendingActions();
+    }
+    catch (error) {
+        if (isConfigParseError(error))
+            return [];
+        throw error;
+    }
+}

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAgGA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAyKA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}

package/dist/src/index.js

@@ -1,6 +1,11 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { z } from "zod";
+import { disableCommand } from "./commands/agent/disable.js";
+import { doctorCommand } from "./commands/agent/doctor.js";
+import { hookCommand } from "./commands/agent/hook.js";
+import { setupCommand } from "./commands/agent/setup.js";
+import { statusCommand } from "./commands/agent/status.js";
 import { clockInCommand, clockOutCommand, clockStatusCommand, } from "./commands/clock.js";
 import { loginCommand } from "./commands/login.js";
 import { logoutCommand } from "./commands/logout.js";
@@ -11,17 +16,21 @@ const parsedJson = z
     .object({ version: z.string() })
     .safeParse(require("../../package.json"));
 const version = parsedJson.success ? parsedJson.data.version : "0.0.0";
+/** Lets `--agent` be repeated as well as comma-separated. */
+function collect(value, previous = []) {
+    return [...previous, value];
+}
 const program = new Command();
 program
     .name("clocktopus")
     .description("CLI for Clocktopus time tracking")
     .version(version)
-    .option("-e, --env <environment>", "Use environment (dev or prod)")
+    .option("-e, --env <environment>", "Use environment (dev, staging or prod)")
     .hook("preAction", (thisCommand) => {
     const opts = thisCommand.opts();
     if (opts.env) {
         if (!(opts.env in ENVIRONMENTS)) {
-            console.error(`Invalid environment: ${opts.env}. Use 'dev' or 'prod'.`);
+            console.error(`Invalid environment: ${opts.env}. Use 'dev', 'staging' or 'prod'.`);
             process.exit(1);
         }
         setRuntimeEnvironment(opts.env);
@@ -60,6 +69,46 @@ clock
     .description("Show clock signals for a specific date")
     .option("-d, --date <date>", "Date in YYYY-MM-DD format (default: today)")
     .action(clockStatusCommand);
+// Agent telemetry — tracks what AI agents cost, alongside human time.
+const agent = program
+    .command("agent")
+    .description("Track AI agent spend from this machine");
+agent
+    .command("setup")
+    .description("Point your coding agents at Clocktopus and install the session hooks")
+    .option("--name <name>", "Label for this machine's ingest token")
+    .option("--force", "Mint a replacement token instead of reusing the existing one")
+    .option("-a, --agent <ids>", "Configure only these agents (claude, codex). Repeatable or comma-separated.", collect)
+    .action((options) => setupCommand(options));
+agent
+    .command("status")
+    .description("Show what the receiver has actually received")
+    .action(statusCommand);
+agent
+    .command("doctor")
+    .description("Check every link in the telemetry chain and report failures")
+    .action(doctorCommand);
+agent
+    .command("disable")
+    .description("Remove this machine's telemetry configuration")
+    .option("--revoke", "Also revoke the ingest token, everywhere")
+    .option("-a, --agent <ids>", "Remove only these agents (claude, codex). Repeatable or comma-separated.", collect)
+    .action((options) => disableCommand(options));
+// Invoked by an agent, never by a person: it reads the hook payload from
+// stdin and must not write to stdout. Hidden so it does not read as
+// something to run by hand.
+//
+// `--provider` is not a convenience. Claude Code and Codex send byte-identical
+// hook payloads, so the flag baked into the installed command is the only
+// thing that says which agent is calling.
+agent
+    .command("hook", { hidden: true })
+    .description("Internal: SessionStart/SessionEnd hook")
+    .option("--provider <provider>", "Which agent installed this hook")
+    // Set only by the hook when it re-spawns itself for an agent that will
+    // not background it. Marks the copy that does the work.
+    .option("--detached", "Internal: this is the backgrounded copy")
+    .action((options) => hookCommand(options));
 export function run() {
     program.parse();
 }

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

@@ -0,0 +1,56 @@
+import type { AgentId, AgentProviderId } from "./agents.js";
+/**
+ * Where the ingest credentials come from, and what shadows what.
+ *
+ * The order matters and is not arbitrary. Inside a Claude Code session the
+ * process environment is what the exporter and the hook actually read, and
+ * `settings.json` `env` is applied *over* the inherited shell environment —
+ * so a value in settings.json wins over one exported from `.envrc` or a
+ * shell profile, silently. That is the failure this resolver is built to
+ * make visible rather than to paper over: it reports the source alongside
+ * the value so `doctor` can name the file that is winning.
+ *
+ * Codex is the mirror image and needs its own branch. It injects nothing
+ * into the hook's environment, so `~/.codex/config.toml` is not one source
+ * among several — it is the only one, and the token has to be read back out
+ * of the exporter's `Authorization` header. Nothing shadows it, which is
+ * why the Codex path cannot produce the split-brain failure the Claude path
+ * is written to detect.
+ */
+export type CredentialSource = "environment" | "settings" | "none";
+export type ResolvedAgentCredentials = {
+    token: string | null;
+    endpoint: string | null;
+    tokenSource: CredentialSource;
+    endpointSource: CredentialSource;
+    /** The file `settings` refers to, so `doctor` can name it. */
+    sourcePath: string;
+};
+export declare function resolveAgentCredentials(agent?: AgentId): ResolvedAgentCredentials;
+/** Masks a token for display: never print more than the stored prefix. */
+export declare function maskToken(token: string): string;
+export declare function findShadowedExports(cwd?: string): Array<{
+    path: string;
+    keys: string[];
+}>;
+/**
+ * The command to write into an agent's hook configuration.
+ *
+ * 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.
+ *
+ * The provider is baked into the command because the two agents send
+ * *identical* hook payloads — same field names, same event spellings, no
+ * marker of any kind. Which agent is calling can only be known from how the
+ * hook was installed.
+ */
+export declare function resolveHookCommand(provider: AgentProviderId): {
+    command: string;
+    usesAbsolutePath: boolean;
+    binaryPath: string | null;
+};
+//# sourceMappingURL=agent-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-config.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK5D;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,cAAc,EAAE,gBAAgB,CAAC;IACjC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,KAAK,GAAE,OAAkB,GACxB,wBAAwB,CA0C1B;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAmBD,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC,CA+BD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAgCA"}