@blastin-dev/clocktopus-cli 0.1.4 → 0.2.1

package/README.md

@@ -47,10 +47,10 @@ clocktopus clock (in|out) [--ago <duration> | --at <time>]
 Record the start or end of a work session. Defaults to "now" when no
 flag is passed.
 
-| Option | Description |
-| --- | --- |
+| Option             | Description                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------- |
 | `--ago <duration>` | Backdate by a duration from now (`15m`, `1h`, `1h30m`). Mutually exclusive with `--at`. |
-| `--at <time>` | Backdate to an absolute wall-clock time today (`HH:mm` or `HH:mm:ss`). |
+| `--at <time>`      | Backdate to an absolute wall-clock time today (`HH:mm` or `HH:mm:ss`).                  |
 
 ### `clocktopus clock status`
 
@@ -60,10 +60,162 @@ clocktopus clock status [-d <YYYY-MM-DD>]
 
 Show clock signals for a given date.
 
-| Option | Description |
-| --- | --- |
+| Option              | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
 | `-d, --date <date>` | Show signals for a specific date in `YYYY-MM-DD` format. Defaults to today. |
 
+### `clocktopus agent setup`
+
+```
+clocktopus agent setup [--name <label>] [--force] [--agent <ids>]
+```
+
+Configures this machine to report AI agent spend — token cost, active time,
+and the repository each session worked in — so the true cost of a piece of
+work can be measured as human time × rate **plus** agent spend.
+
+One command, however many agents you have. It looks for each supported CLI
+on PATH and configures what it finds:
+
+```
+Agents on this machine
+
+  1  Claude Code   2.1.234   already configured
+  2  Codex CLI     0.147.0   not configured
+
+Which should report to Clocktopus? [all]:
+```
+
+With one agent installed there is no question to ask, so it just runs. With
+several it prompts; `--agent` skips the prompt, and a non-interactive shell
+configures everything found and says so.
+
+| Agent       | `--agent` id | Writes                                        |
+| ----------- | ------------ | --------------------------------------------- |
+| Claude Code | `claude`     | `~/.claude/settings.json`                     |
+| Codex CLI   | `codex`      | `~/.codex/config.toml`, `~/.codex/hooks.json` |
+| OpenCode    | `opencode`   | `~/.config/opencode/plugin/clocktopus.js`     |
+
+It mints **one** ingest token for the machine, writes each agent's exporter
+configuration and `SessionStart` / `SessionEnd` hooks, then confirms the
+receiver accepts the token before reporting success.
+
+| Option           | Description                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| `--name <label>` | Label for this machine's token. Defaults to the hostname — keep it recognisable, since revocation is per token. |
+| `--force`        | Mint a replacement token instead of reusing the one already installed.                                          |
+| `-a, --agent`    | Configure only these agents. Repeatable, or comma-separated: `--agent claude,codex`.                            |
+
+Re-running without `--force` is safe and idempotent: it repairs the hooks and
+refreshes the endpoint while keeping the existing token. Installing a second
+agent later and re-running costs nothing — the new one inherits the token the
+first is already using rather than minting a second against the same machine.
+
+**Restart the agent afterwards.** Every exporter and hook reads its
+configuration once, at process start, so a session that is already open will
+not pick any of it up. This is the most common reason a correct setup appears
+to do nothing.
+
+**OpenCode is a plugin, not a hook.** It has no hook system, so setup
+writes one generated file into `~/.config/opencode/plugin/`, which OpenCode
+auto-loads. Your `opencode.json` is not touched — that file is your model,
+provider and permission configuration, and leaving it alone removes a whole
+class of ways to break your setup. Uninstalling is deleting the file.
+
+OpenCode also has `experimental.openTelemetry`, which looks like an easier
+route and is not one: its spans carry your prompts and the model's replies
+verbatim, with no way to switch that off, and no cost or repository. The
+plugin reads OpenCode's own per-message totals instead and sends counts and
+identifiers only.
+
+**Codex needs one extra step, once.** It will not run a `hooks.json` it has
+not been shown, so the next Codex session asks — answer _Trust all and
+continue_. Until you do, Codex reports what your sessions cost but not which
+repository they were spent on. `clocktopus agent doctor` reports the state
+until it is approved.
+
+Everything for an agent lands in that agent's own config rather than a shell
+profile. That single source of truth per agent is what lets `agent doctor`
+say which value is actually in force. Note the ingest token is stored there
+in plaintext: if you keep `~/.claude` or `~/.codex` in a dotfiles repository,
+ignore the file.
+
+Setup then checks the repository you ran it in, because configuring the
+machine is only half the job — sessions will arrive either way, but two
+things decide whether they mean anything, and neither is visible locally:
+
+| Check                            | If it fails                                                                      |
+| -------------------------------- | -------------------------------------------------------------------------------- |
+| Repository attached to a project | Spend is recorded, but lands in the unattributed row instead of against a client |
+| Push webhook delivering          | No human time entries, so there is nothing to compare the spend against          |
+
+The second does **not** stop agent→commit links — the SessionEnd hook
+resolves `git rev-list before..after` locally and posts the list, so those
+are created with no webhook involved. What is missing is the other side of
+the comparison: true cost is human time × rate _plus_ agent spend, and one
+term alone is not a smaller answer.
+
+Both are reported separately, with the exact next step, because they send
+you to two different places. Setup only tells you — it never changes your
+GitHub settings. Note the webhook URL is **per person, not per repository**,
+so on a shared repo each teammate adds their own.
+
+### `clocktopus agent status`
+
+Shows what the receiver has actually received. Local configuration is a
+claim; this is the evidence.
+
+The two ingest lanes are reported separately because they fail separately:
+
+| Lane  | Carries                          | If it alone goes quiet                                   |
+| ----- | -------------------------------- | -------------------------------------------------------- |
+| Hook  | repository, branch, commit range | spend is recorded but cannot be attributed to a project  |
+| Spend | tokens, cost, active time        | sessions show `$0.00`, indistinguishable from cheap work |
+
+It also lists every supported agent found on this machine, including any
+that are installed but _not_ reporting — a state the server-side lanes
+cannot show, because those sessions simply never arrive.
+
+That second failure is why there is no single "connected" line — it is the
+one that silently understates what work cost.
+
+### `clocktopus agent doctor`
+
+Checks every link in the chain, per agent, and names the first one that is
+broken: the config file parses, the exporter is configured, both hooks are
+installed, the hook command actually executes, Codex has approved its hooks,
+the receiver accepts the token, no other file is shadowing the
+configuration, and whether that agent needs restarting. The repository
+checks — attached to a project, delivering commits — run once at the end,
+since they are facts about the repo rather than about any one agent.
+
+The receiver check is the one that cannot be done locally — it crosses the
+network to a different host than the dashboard, so a wrong endpoint and a
+revoked token are otherwise indistinguishable from an idle afternoon.
+
+### `clocktopus agent disable`
+
+```
+clocktopus agent disable [--revoke] [--agent <ids>]
+```
+
+Removes this machine's telemetry configuration from every agent, leaving any
+hooks and settings you added yourself untouched.
+
+| Option        | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| `--revoke`    | Also revoke the ingest token, making it useless everywhere.                 |
+| `-a, --agent` | Remove only these agents (`claude`, `codex`), leaving the others reporting. |
+
+`--revoke` is ignored when combined with `--agent`: the token is shared by
+every agent on the machine, so killing it while another one still has it
+written would leave that agent posting into a 401 forever — which looks
+like an idle week rather than a broken install.
+
+Stopping and revoking are separate on purpose: removing the local
+configuration stops _this_ machine reporting, but does nothing about a token
+that has already been copied elsewhere or committed.
+
 ## Token Storage
 
 Credentials are stored in a platform-specific config directory:
@@ -74,3 +226,9 @@ ig.json`
 - **Windows**: `%APPDATA%/clocktopus-cli-nodejs/config.json`
 
 Run `clocktopus logout` to clear stored credentials.
+
+The agent telemetry setup deliberately keeps **no** copy of the ingest token
+here. It has to live in each agent's own config for that agent's exporter to
+read it, and a second copy would be another thing to leak and another thing
+to fall out of date. Only the token id (needed to revoke) and its display
+prefix are kept.

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

@@ -0,0 +1,21 @@
+/**
+ * Removes this machine's telemetry configuration, from every agent.
+ *
+ * Stopping and revoking are separate on purpose. Removing the local
+ * configuration stops *this* machine reporting; it does nothing about a
+ * token that has already been copied elsewhere or committed to a dotfiles
+ * repository. `--revoke` is the one that makes the token useless everywhere,
+ * and it is opt-in because the common case — moving machines, reinstalling —
+ * should not invalidate a token that CI or another workstation still uses.
+ *
+ * `--agent` narrows it to one, which is the only way to stop reporting from
+ * Codex while leaving Claude Code alone. Without it every agent is cleaned,
+ * including ones no longer installed — an uninstalled agent's config file
+ * outlives it, and a token left in a file nobody looks at is the worst
+ * place for one to sit.
+ */
+export declare function disableCommand(options: {
+    revoke?: boolean;
+    agent?: string[];
+}): Promise<void>;
+//# sourceMappingURL=disable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disable.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/disable.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyFhB"}

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

@@ -0,0 +1,106 @@
+import { clearHookState } from "../../lib/agent-hook-state.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
+import { ApiError, request } from "../../lib/api.js";
+import { clearAgentConfig, getAgentConfig, isLoggedIn, } from "../../lib/config.js";
+/**
+ * Removes this machine's telemetry configuration, from every agent.
+ *
+ * Stopping and revoking are separate on purpose. Removing the local
+ * configuration stops *this* machine reporting; it does nothing about a
+ * token that has already been copied elsewhere or committed to a dotfiles
+ * repository. `--revoke` is the one that makes the token useless everywhere,
+ * and it is opt-in because the common case — moving machines, reinstalling —
+ * should not invalidate a token that CI or another workstation still uses.
+ *
+ * `--agent` narrows it to one, which is the only way to stop reporting from
+ * Codex while leaving Claude Code alone. Without it every agent is cleaned,
+ * including ones no longer installed — an uninstalled agent's config file
+ * outlives it, and a token left in a file nobody looks at is the worst
+ * place for one to sit.
+ */
+export async function disableCommand(options) {
+    const survey = surveyAgents();
+    const requested = (options.agent ?? []).flatMap((value) => value.split(",").map((part) => part.trim().toLowerCase()));
+    if (requested.length > 0) {
+        const unknown = requested.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);
+        }
+    }
+    const targets = requested.length > 0
+        ? survey.filter((entry) => requested.includes(entry.agent.id))
+        : survey;
+    const cleaned = [];
+    for (const entry of targets) {
+        try {
+            const { removed } = entry.agent.remove();
+            if (removed.length > 0)
+                cleaned.push({ label: entry.agent.label, removed });
+        }
+        catch (error) {
+            if (isConfigParseError(error)) {
+                console.error(`✗ ${error.message}`);
+                process.exit(1);
+            }
+            // A failure on one agent must not leave the others reporting.
+            console.error(`✗ ${entry.agent.label}: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+    }
+    const agent = getAgentConfig();
+    // Revoking while another agent on this machine still has the token
+    // written would leave that one posting into a 401 forever, which looks
+    // like an idle week rather than a broken install.
+    const partial = requested.length > 0 && requested.length < survey.length;
+    if (options.revoke && partial) {
+        console.log("⚠ --revoke was ignored: it kills the token everywhere, and this run only\n" +
+            "  cleaned some of the agents on this machine. Re-run without --agent to\n" +
+            "  remove all of them, then revoke.");
+    }
+    else if (options.revoke) {
+        await revokeToken(agent);
+    }
+    if (!partial) {
+        clearAgentConfig();
+        clearHookState();
+    }
+    if (cleaned.length === 0) {
+        console.log("Nothing to remove — agent telemetry was not configured here.");
+        return;
+    }
+    for (const { label, removed } of cleaned) {
+        console.log(`✓ ${label}: removed ${removed.join(", ")}.`);
+    }
+    if (!options.revoke || partial) {
+        console.log("\nThe ingest token is still valid. Revoke it with\n" +
+            "  clocktopus agent disable --revoke");
+    }
+    console.log(`\nRestart ${cleaned
+        .map((c) => c.label)
+        .join(" and ")} to stop the current session reporting.`);
+}
+async function revokeToken(agent) {
+    if (!agent.tokenId) {
+        console.log("⚠ No token id on record, so nothing was revoked. This machine's token\n" +
+            "  was minted by an older version or on another machine — revoke it\n" +
+            "  from the dashboard instead.");
+        return;
+    }
+    if (!isLoggedIn()) {
+        console.log("⚠ Not logged in, so the token could not be revoked. Run 'clocktopus\n" +
+            "  login' and try again — the local configuration was still removed.");
+        return;
+    }
+    try {
+        await request(`/api/agent/ingest-token?tokenId=${encodeURIComponent(agent.tokenId)}`, { method: "DELETE" });
+        console.log(`✓ Revoked ${agent.tokenPrefix ?? "the ingest token"}.`);
+    }
+    catch (error) {
+        console.error(`✗ Could not revoke the token: ${error instanceof ApiError || error instanceof Error
+            ? error.message
+            : "unknown error"}`);
+        console.error("  The local configuration was still removed.");
+    }
+}

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

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

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

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

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

@@ -0,0 +1,306 @@
+import { execSync } from "node:child_process";
+import { isAfter, parseISO } from "date-fns";
+import { findShadowedExports, maskToken, resolveAgentCredentials, } from "../../lib/agent-config.js";
+import { readLastRun } from "../../lib/agent-hook-state.js";
+import { verifyReceiver } from "../../lib/agent-receiver.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
+import { isLoggedIn } from "../../lib/config.js";
+import { formatAgo } from "../../lib/format.js";
+import { fetchRepoStatus, repoChecks } from "../../lib/repo-guidance.js";
+export async function doctorCommand() {
+    const sections = [];
+    sections.push({
+        title: "This machine",
+        checks: [
+            {
+                label: "Logged in",
+                ok: isLoggedIn(),
+                detail: isLoggedIn() ? "yes" : "no",
+                fix: "clocktopus login",
+            },
+        ],
+    });
+    const survey = surveyAgents();
+    const relevant = survey.filter((entry) => entry.installed || entry.configured || entry.unreadable);
+    if (relevant.length === 0) {
+        sections[0].checks.push({
+            label: "Agents",
+            ok: false,
+            detail: `none of ${survey.map((e) => e.agent.binary).join(", ")} found on PATH`,
+            fix: "Install a supported agent, then run 'clocktopus agent setup'",
+        });
+    }
+    for (const entry of relevant) {
+        sections.push({
+            title: `${entry.agent.label}${entry.version ? ` ${entry.version}` : ""}`,
+            checks: await agentChecks(entry),
+        });
+    }
+    // Past this point the pipeline works; these decide whether what it carries
+    // can be turned into a number. Both are server-side facts about the
+    // repository, not about any one agent.
+    const tail = [];
+    const repoStatus = await fetchRepoStatus();
+    if (repoStatus)
+        tail.push(...repoChecks(repoStatus));
+    tail.push(checkLastHookRun());
+    sections.push({ title: "Repository and delivery", checks: tail });
+    report(sections);
+}
+async function agentChecks(entry) {
+    const checks = [];
+    if (entry.unreadable) {
+        return [
+            {
+                label: "Config",
+                ok: false,
+                detail: "could not be parsed",
+                fix: entry.unreadable,
+            },
+        ];
+    }
+    checks.push({
+        label: "Installed",
+        ok: entry.installed ? true : "warn",
+        detail: entry.installed
+            ? `${entry.agent.binary} ${entry.version ?? ""}`.trim()
+            : `${entry.agent.binary} is not on PATH`,
+        fix: "Config here is harmless, but nothing will report until it is installed",
+    });
+    let state;
+    try {
+        state = entry.agent.read();
+    }
+    catch (error) {
+        if (!isConfigParseError(error))
+            throw error;
+        return [
+            {
+                label: "Config",
+                ok: false,
+                detail: "could not be parsed",
+                fix: error.message,
+            },
+        ];
+    }
+    checks.push({
+        label: "Config",
+        ok: state.token !== null,
+        detail: state.token !== null
+            ? `${state.paths.join(", ")} (modified ${formatAgo(state.modifiedAt?.toISOString() ?? null)})`
+            : `not configured in ${state.paths.join(", ")}`,
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
+    });
+    // Both events are required, and for different reasons: SessionStart is the
+    // only source of the *before* SHA and of `cwd`, SessionEnd is the only
+    // source of the exact commit list. One without the other silently
+    // degrades what can be attributed.
+    const hookStart = state.hookCommands.SessionStart;
+    const hookEnd = state.hookCommands.SessionEnd;
+    checks.push({
+        label: "Hooks installed",
+        ok: Boolean(hookStart && hookEnd),
+        detail: hookStart && hookEnd
+            ? `SessionStart, SessionEnd → ${hookStart}`
+            : `missing ${[!hookStart && "SessionStart", !hookEnd && "SessionEnd"]
+                .filter(Boolean)
+                .join(", ")}`,
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
+    });
+    if (hookStart)
+        checks.push(checkHookRuns(hookStart));
+    // A warning, not a failure: a plugin from an older generation still
+    // reports. What it does not have is whatever the newer one fixed, and
+    // nothing else in this report would ever say so — the token is valid, the
+    // hook resolves, the receiver answers.
+    const stale = entry.agent.staleReason?.() ?? null;
+    if (stale) {
+        checks.push({
+            label: "Generated config",
+            ok: "warn",
+            detail: stale,
+            fix: `clocktopus agent setup --agent ${entry.agent.id}`,
+        });
+    }
+    for (const action of entry.agent.pendingActions()) {
+        checks.push({
+            label: "Hooks enabled",
+            ok: "warn",
+            detail: "installed but not yet approved by the agent",
+            fix: action,
+        });
+    }
+    const credentials = resolveAgentCredentials(entry.agent.id);
+    checks.push({
+        label: "Token in force",
+        ok: credentials.token !== null,
+        detail: credentials.token
+            ? `${maskToken(credentials.token)} (from ${credentials.tokenSource === "settings"
+                ? credentials.sourcePath
+                : credentials.tokenSource})`
+            : "none resolved",
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
+    });
+    if (credentials.token && credentials.endpoint) {
+        const check = await verifyReceiver(credentials.endpoint, credentials.token);
+        checks.push({
+            label: "Receiver",
+            ok: check.ok,
+            detail: check.ok
+                ? `${credentials.endpoint} accepted the token`
+                : check.reason === "invalid_token"
+                    ? `${credentials.endpoint} rejected the token (401)`
+                    : check.reason === "unexpected_status"
+                        ? `${credentials.endpoint} answered HTTP ${check.status}`
+                        : `${credentials.endpoint} unreachable — ${check.message}`,
+            fix: check.ok || check.reason !== "invalid_token"
+                ? "Check the endpoint is reachable from this network"
+                : "clocktopus agent setup --force  (mints a replacement token)",
+        });
+    }
+    // Only Claude Code applies config `env` over the inherited environment,
+    // so only it can be shadowed by a shell export.
+    if (entry.agent.id === "claude")
+        checks.push(checkShadowedExports());
+    checks.push(checkRestartNeeded(entry, state.modifiedAt));
+    return checks;
+}
+/**
+ * Runs the installed hook command with empty stdin.
+ *
+ * This is a genuine no-op — the hook returns immediately when stdin carries
+ * no payload — so it sends nothing and records nothing, while still proving
+ * the exact command line in the agent's config resolves and executes. Worth
+ * checking directly: hooks run under a shell whose PATH may differ from the
+ * interactive one, and a command that fails to resolve there fails
+ * silently, costing every session its repository context.
+ */
+function checkHookRuns(command) {
+    try {
+        execSync(command, {
+            input: "",
+            timeout: 15_000,
+            stdio: ["pipe", "ignore", "ignore"],
+        });
+        return {
+            label: "Hook executes",
+            ok: true,
+            detail: "command resolved and ran",
+        };
+    }
+    catch (error) {
+        return {
+            label: "Hook executes",
+            ok: false,
+            detail: `'${command}' failed — ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}`,
+            fix: "clocktopus agent setup  (rewrites the hook with a resolvable path)",
+        };
+    }
+}
+function checkShadowedExports() {
+    const shadowed = findShadowedExports();
+    if (shadowed.length === 0) {
+        return {
+            label: "Config conflicts",
+            ok: true,
+            detail: "settings.json is the only source",
+        };
+    }
+    return {
+        label: "Config conflicts",
+        ok: "warn",
+        detail: shadowed
+            .map(({ path, keys }) => `${path} exports ${keys.join(", ")}`)
+            .join("; "),
+        fix: "settings.json is applied over the inherited environment, so these are\n" +
+            "      ignored inside Claude Code. Remove them — two sources that\n" +
+            "      disagree is how spend lands on the wrong account.",
+    };
+}
+/**
+ * Did the configuration change after the last session used it?
+ *
+ * The exporter and the hook both read their configuration once, at process
+ * start, so a session already open when setup ran is still using the old
+ * values. This is the most common reason a correct configuration looks dead.
+ *
+ * Scoped to the agent whose hook last ran: one receipt file is shared by all
+ * of them, and comparing Claude Code's last run against Codex's config
+ * mtime would report a restart that has already happened, or miss one that
+ * has not.
+ */
+function checkRestartNeeded(entry, configModifiedAt) {
+    const lastRun = readLastRun();
+    const ranThisAgent = lastRun?.provider === entry.agent.provider;
+    if (!configModifiedAt || !lastRun?.at || !ranThisAgent) {
+        return {
+            label: "Restart",
+            ok: "warn",
+            detail: `${entry.agent.label} has not run a hook since this configuration was written`,
+            fix: `Restart ${entry.agent.label}, then run 'clocktopus agent status'`,
+        };
+    }
+    const ranAfterConfig = isAfter(parseISO(lastRun.at), configModifiedAt);
+    return {
+        label: "Restart",
+        ok: ranAfterConfig ? true : "warn",
+        detail: ranAfterConfig
+            ? "a session has run since the last configuration change"
+            : "the config changed after the last session started",
+        fix: `Restart ${entry.agent.label} so the exporter and hook pick up the new values`,
+    };
+}
+function checkLastHookRun() {
+    const lastRun = readLastRun();
+    if (!lastRun) {
+        return {
+            label: "Last hook run",
+            ok: "warn",
+            detail: "no record — no hook has run on this machine",
+            fix: "Restart your agent and start a session",
+        };
+    }
+    const failed = lastRun.status === null ||
+        lastRun.status === undefined ||
+        lastRun.status < 200 ||
+        lastRun.status >= 300;
+    const who = lastRun.provider ? ` (${lastRun.provider})` : "";
+    return {
+        label: "Last hook run",
+        ok: !failed,
+        detail: failed
+            ? `${formatAgo(lastRun.at)}${who} — ${lastRun.status ? `HTTP ${lastRun.status}` : (lastRun.error ?? "no response")}`
+            : `${formatAgo(lastRun.at)}${who} — HTTP ${lastRun.status}`,
+        fix: lastRun.status === 401
+            ? "clocktopus agent setup --force  (the token was rejected)"
+            : "Check network access to the receiver",
+    };
+}
+function report(sections) {
+    console.log("\nAgent telemetry diagnosis");
+    for (const section of sections) {
+        if (section.checks.length === 0)
+            continue;
+        console.log(`\n${section.title}\n`);
+        for (const check of section.checks) {
+            const symbol = check.ok === true ? "✓" : check.ok === "warn" ? "⚠" : "✗";
+            console.log(`  ${symbol} ${check.label.padEnd(18)}${check.detail}`);
+            if (check.ok !== true && check.fix) {
+                console.log(`    → ${check.fix}`);
+            }
+        }
+    }
+    const all = sections.flatMap((section) => section.checks);
+    const failures = all.filter((check) => check.ok === false).length;
+    const warnings = all.filter((check) => check.ok === "warn").length;
+    console.log("");
+    if (failures === 0 && warnings === 0) {
+        console.log("Everything checks out. 'clocktopus agent status' shows what has arrived.");
+    }
+    else {
+        console.log(`${failures} failing, ${warnings} to review. Fix the first failure above —\n` +
+            "the later ones are usually consequences of it.");
+    }
+    if (failures > 0)
+        process.exitCode = 1;
+}

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

@@ -0,0 +1,5 @@
+export declare function hookCommand(options: {
+    provider?: string;
+    detached?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/hook.ts"],"names":[],"mappings":"AAwaA,wBAAsB,WAAW,CAAC,OAAO,EAAE;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}