@blastin-dev/clocktopus-cli 0.1.3 → 0.2.0

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

@@ -0,0 +1,231 @@
+import { execFileSync } from "node:child_process";
+import { maskToken, resolveAgentCredentials } from "../../lib/agent-config.js";
+import { clearStartState, listStartStates, readStartState, recordLastRun, writeStartState, } from "../../lib/agent-hook-state.js";
+/**
+ * Claude Code SessionStart / SessionEnd hook → Clocktopus.
+ *
+ * Claude Code pipes its hook JSON to stdin. That JSON is the only place
+ * `cwd` appears anywhere in the telemetry pipeline — the OTLP metric export
+ * carries no path, repository or branch data at all — so without this hook
+ * every agent session is unattributable and the ledger can only show
+ * totals.
+ *
+ * Previously a standalone script under `scripts/agent-telemetry/`, which
+ * meant `settings.json` had to reference an absolute path inside a checkout
+ * of this repository. Shipping it as a subcommand is what makes the feature
+ * installable by anyone: the hook is wherever the CLI is.
+ *
+ * Contract with the host process, all three parts load-bearing: never write
+ * to stdout (Claude Code parses it), never throw, always exit 0. Telemetry
+ * must not be able to break the session it measures.
+ */
+const TIMEOUT_MS = 4000;
+/**
+ * How long a state file must sit untouched before its session is presumed
+ * dead. A file only survives SessionEnd if the session never got one —
+ * SIGKILL, a crash, or the machine going down — but a long-running session
+ * is perfectly normal, so this sits well past a working day rather than at
+ * the point a session merely looks idle.
+ */
+const ABANDONED_AFTER_MS = 12 * 60 * 60 * 1000;
+/** Bound on one sweep, so a directory left full of state cannot stall a start. */
+const MAX_SWEEP_PER_RUN = 10;
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+async function post(endpoint, token, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const response = await fetch(`${endpoint.replace(/\/$/, "")}/v1/agent-session`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        return { status: response.status, error: null };
+    }
+    catch (error) {
+        // Telemetry must never break the session it measures. The failure is
+        // recorded for `agent doctor` instead of surfaced here.
+        return {
+            status: null,
+            error: error instanceof Error ? error.message : "request failed",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Closes sessions that were never given a SessionEnd.
+ *
+ * A state file outlives its session only when the process died without
+ * running the hook, and until something closes it the session keeps a null
+ * `ended_at` and a null `git_head_after` forever.
+ *
+ * It deliberately does **not** send `commit_shas`. The honest range for a
+ * dead session is unknowable after the fact: `before..HEAD` also contains
+ * everything committed in the hours since it died, and the receiver records
+ * hook-supplied commits as `declared`, which outranks a `time_window` link
+ * and would make a bad guess permanent. Closing the session is enough —
+ * with a real `ended_at` the webhook's time-window pass can then link its
+ * commits from the commit timestamps, which are bounded by data rather than
+ * by assumption.
+ *
+ * For the same reason it sends its own `ended_at` rather than letting the
+ * receiver stamp one: this runs when the *next* session starts, potentially
+ * a day later.
+ */
+async function sweepAbandonedSessions(endpoint, token, currentSessionId) {
+    let swept = 0;
+    for (const { sessionId, ageMs, lastActivityAt } of listStartStates()) {
+        if (swept >= MAX_SWEEP_PER_RUN)
+            return;
+        if (sessionId === currentSessionId)
+            continue;
+        if (ageMs < ABANDONED_AFTER_MS)
+            continue;
+        swept++;
+        const state = readStartState(sessionId);
+        // Nothing recoverable without the originating checkout — drop the file
+        // rather than resolve its SHA against an unrelated repository.
+        if (!state?.cwd) {
+            clearStartState(sessionId);
+            continue;
+        }
+        const head = git(state.cwd, ["rev-parse", "HEAD"]);
+        if (head) {
+            await post(endpoint, token, {
+                session_id: sessionId,
+                hook_event_name: "SessionEnd",
+                cwd: state.cwd,
+                reason: "abandoned",
+                // Never "now": this session died hours ago, and the receiver would
+                // otherwise record a window spanning everything since. The receiver
+                // treats this as a fallback and keeps a telemetry-stamped end if it
+                // has one; this value only fills the gap when it has none.
+                ended_at: lastActivityAt.toISOString(),
+                repository_url: git(state.cwd, ["remote", "get-url", "origin"]),
+                git_branch: git(state.cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+                git_head_before: state.sha,
+                git_head_after: head,
+            });
+        }
+        clearStartState(sessionId);
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function run() {
+    const { token, endpoint } = resolveAgentCredentials();
+    if (!token || !endpoint) {
+        // Not configured. Silence is correct: agent telemetry is opt-in, and a
+        // machine that never ran `clocktopus agent setup` should notice nothing.
+        return;
+    }
+    const raw = await readStdin();
+    if (!raw)
+        return;
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : null;
+    const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
+    if (!sessionId || !cwd)
+        return;
+    const eventName = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+    const isSessionStart = eventName === "SessionStart";
+    // HEAD at SessionStart is the *before* SHA; HEAD at SessionEnd is the
+    // *after*. Sending both under one field would let SessionEnd overwrite the
+    // start SHA, collapsing the range to a single point and making
+    // `git rev-list before..after` — the authoritative commit↔session link —
+    // impossible to compute.
+    const head = git(cwd, ["rev-parse", "HEAD"]);
+    const repositoryUrl = git(cwd, ["remote", "get-url", "origin"]);
+    const body = {
+        session_id: sessionId,
+        hook_event_name: eventName,
+        cwd,
+        source: typeof payload.source === "string" ? payload.source : undefined,
+        reason: typeof payload.reason === "string" ? payload.reason : undefined,
+        repository_url: repositoryUrl,
+        git_branch: git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+        ...(isSessionStart ? { git_head_before: head } : { git_head_after: head }),
+    };
+    // Resolve the SHA range into an actual commit list, here on the machine
+    // that has the git object graph. The receiver cannot do this — it has no
+    // checkout — so a range alone would be unusable.
+    //
+    // SessionStart and SessionEnd are separate processes, so the starting SHA
+    // is stashed on disk under the session id rather than passed in the
+    // environment.
+    if (isSessionStart) {
+        if (head)
+            writeStartState(sessionId, head, cwd);
+    }
+    else {
+        const before = readStartState(sessionId)?.sha;
+        if (before && head && before !== head) {
+            const shas = git(cwd, [
+                "rev-list",
+                "--max-count=200",
+                `${before}..${head}`,
+            ]);
+            if (shas)
+                body.commit_shas = shas.split("\n").filter(Boolean);
+        }
+        if (before)
+            body.git_head_before = before;
+        clearStartState(sessionId);
+    }
+    // transcript_path is intentionally NOT forwarded. Claude Code provides it,
+    // and it points at the full conversation on disk — exactly the content
+    // BLA-421 says we must never collect.
+    const result = await post(endpoint, token, body);
+    recordLastRun({
+        at: new Date().toISOString(),
+        event: eventName,
+        sessionId,
+        endpoint,
+        tokenPrefix: maskToken(token),
+        status: result.status,
+        error: result.error,
+        repository: repositoryUrl ?? null,
+    });
+    // After this session's own event, never before it: the sweep talks to the
+    // network once per abandoned session and must not delay the event it is
+    // piggybacking on.
+    if (isSessionStart) {
+        await sweepAbandonedSessions(endpoint, token, sessionId);
+    }
+}
+export async function hookCommand() {
+    try {
+        await run();
+    }
+    catch {
+        // Every failure path is silent by design.
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Configures this machine to report agent spend to Clocktopus.
+ *
+ * Everything lands in one file — `~/.claude/settings.json` — holding both
+ * the exporter's environment and the session hooks. A single source of
+ * truth 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. `--force` mints a replacement instead.
+ */
+export declare function setupCommand(options: {
+    name?: string;
+    force?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+IhB"}

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

@@ -0,0 +1,194 @@
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { findShadowedExports, maskToken, resolveHookCommand, } from "../../lib/agent-config.js";
+import { verifyReceiver } from "../../lib/agent-receiver.js";
+import { ApiError, get, post } from "../../lib/api.js";
+import { applyTelemetrySettings, claudeConfigDir, readInstalledTelemetry, readSettings, SettingsParseError, writeSettings, } from "../../lib/claude-settings.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 to report agent spend to Clocktopus.
+ *
+ * Everything lands in one file — `~/.claude/settings.json` — holding both
+ * the exporter's environment and the session hooks. A single source of
+ * truth 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. `--force` mints a replacement instead.
+ */
+export async function setupCommand(options) {
+    if (!isLoggedIn()) {
+        console.error("Not logged in. Run 'clocktopus login' first.");
+        process.exit(1);
+    }
+    let installed;
+    try {
+        installed = readInstalledTelemetry();
+    }
+    catch (error) {
+        if (error instanceof SettingsParseError) {
+            console.error(`✗ ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    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;
+    }
+    // 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, not a bad token.
+    let token = installed.env.CLOCKTOPUS_INGEST_TOKEN ?? null;
+    let tokenId = null;
+    let minted = false;
+    if (token && !options.force) {
+        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;
+        }
+    }
+    else if (options.force) {
+        token = null;
+    }
+    if (!token) {
+        try {
+            const response = await post("/api/agent/ingest-token", {
+                name: options.name ?? `${hostname()} (claude code)`,
+            }).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 hook = resolveHookCommand();
+    let backupPath = null;
+    try {
+        const current = readSettings();
+        const next = applyTelemetrySettings(current.settings, {
+            token,
+            endpoint,
+            hookCommand: hook.command,
+        });
+        ({ backupPath } = writeSettings(next, current.path));
+    }
+    catch (error) {
+        console.error(`✗ Could not write ${installed.path}: ${error instanceof Error ? error.message : "unknown error"}`);
+        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)"}`));
+    console.log(labelled("Settings", installed.path));
+    console.log(labelled("Hook", `${hook.command}  (SessionStart, SessionEnd)`));
+    if (backupPath)
+        console.log(labelled("Backup", backupPath));
+    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({
+        hookUsesAbsolutePath: hook.usesAbsolutePath,
+    })) {
+        console.log(`\n${warning}`);
+    }
+    // The single most common reason a correct setup appears dead. Both the
+    // OTLP 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 Claude Code — the exporter and the hook read their configuration\nonce, at process start.");
+    console.log("\nThen confirm it end to end:  clocktopus agent status");
+}
+function collectWarnings(input) {
+    const warnings = [];
+    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 settings.json means the ingest token is about to be
+    // committed. Worth saying plainly; the CLI cannot prevent it.
+    if (existsSync(join(claudeConfigDir(), ".git"))) {
+        warnings.push(`⚠ ${claudeConfigDir()} is a git repository, and settings.json now holds\n` +
+            "  your ingest token in plaintext. Ignore the file, or revoke with\n" +
+            "  'clocktopus agent disable --revoke' if it gets committed.");
+    }
+    if (input.hookUsesAbsolutePath) {
+        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 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":"AA8BA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAoFnD"}

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

@@ -0,0 +1,160 @@
+import { differenceInMilliseconds, parseISO } from "date-fns";
+import { readLastRun } from "../../lib/agent-hook-state.js";
+import { ApiError, get } from "../../lib/api.js";
+import { readInstalledTelemetry, SettingsParseError, } from "../../lib/claude-settings.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 the exporter reads its
+ * environment once at process start, Claude Code swallows 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 metrics
+ * do not produces sessions with a repository, a branch and no spend, 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("Metrics 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 OTLP exporter is not reaching the receiver — every session will\n" +
+                "  show $0.00, which is indistinguishable from cheap work. Check the\n" +
+                "  OTEL_* values 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 the metric stream carries no 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 = [];
+    try {
+        const installed = readInstalledTelemetry();
+        if (!installed.exists || Object.keys(installed.env).length === 0) {
+            lines.push(labelled("Config", "not set up here — run 'clocktopus agent setup'"));
+            return lines;
+        }
+        lines.push(labelled("Config", installed.path));
+    }
+    catch (error) {
+        if (error instanceof SettingsParseError) {
+            lines.push(labelled("Config", `unreadable — ${error.message}`));
+            return lines;
+        }
+        throw error;
+    }
+    // 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 ?? "?"}) ${outcome}`));
+    }
+    else {
+        lines.push(labelled("Last hook", "has not run since setup"));
+    }
+    return lines;
+}

package/dist/src/commands/clock.d.ts

@@ -1,11 +1,33 @@
 /**
- * Record a clock-in signal for today
+ * Record a clock-in signal for today.
+ *
+ * Accepts the same backdate flags as `clock out`:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The server silently clamps the requested time if it would fall outside
+ * the allowed window (before start-of-today, before the day's last
+ * clock-out, or after the first existing time entry on the day).
  */
-export declare function clockInCommand(): Promise<void>;
+export declare function clockInCommand(options?: {
+    ago?: string;
+    at?: string;
+}): Promise<void>;
 /**
- * Record a clock-out signal for today
+ * Record a clock-out signal for today.
+ *
+ * Accepts optional backdate flags:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The two flags are mutually exclusive. The server silently clamps the
+ * requested time if it would predate the session's clock-in or the
+ * session's last time entry.
  */
-export declare function clockOutCommand(): Promise<void>;
+export declare function clockOutCommand(options?: {
+    ago?: string;
+    at?: string;
+}): Promise<void>;
 /**
  * Show clock signals status for a given date (default: today)
  */

package/dist/src/commands/clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/commands/clock.ts"],"names":[],"mappings":"AAuDA;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAqCpD;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAuCrD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/commands/clock.ts"],"names":[],"mappings":"AAgFA;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,OAAO,CAAC,IAAI,CAAC,CA0Ef;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,OAAO,CAAC,IAAI,CAAC,CAsEf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}