@blastin-dev/clocktopus-cli 0.1.3 → 0.2.0

package/dist/src/commands/clock.js

@@ -16,8 +16,30 @@ const ClockSignalResponseSchema = z.object({
         signalTimestamp: z.string(),
         alreadyExists: z.boolean(),
         blockedReason: z.enum(["already_clocked_in", "not_clocked_in"]).nullable(),
+        clamped: z.boolean().optional(),
+        requestedTime: z.string().nullable().optional(),
+        reopened: z.boolean().optional(),
     }),
 });
+/**
+ * Parses "15m", "1h", "1h30m" → whole minutes. Mirrors
+ * `packages/core/src/utils/duration.ts` (the CLI is a standalone package
+ * and doesn't depend on @repo/core).
+ */
+function parseDurationToMinutes(input) {
+    const trimmed = input.trim().toLowerCase();
+    const match = /^(?:(\d+)h)?(?:(\d+)m)?$/.exec(trimmed);
+    if (!match || (!match[1] && !match[2])) {
+        throw new Error(`Invalid duration "${input}". Use formats like 15m, 1h, or 1h30m.`);
+    }
+    const hours = match[1] ? Number(match[1]) : 0;
+    const minutes = match[2] ? Number(match[2]) : 0;
+    const total = hours * 60 + minutes;
+    if (total <= 0) {
+        throw new Error(`Duration must be greater than zero: "${input}".`);
+    }
+    return total;
+}
 /**
  * Schema for clock signals list response
  */
@@ -44,14 +66,43 @@ function formatSignalType(type) {
     return type === "clock_in" ? "Clock In" : "Clock Out";
 }
 /**
- * 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 async function clockInCommand() {
+export async function clockInCommand(options = {}) {
     if (!checkAuth()) {
         process.exit(1);
     }
+    if (options.ago && options.at) {
+        console.error("Cannot use --ago and --at together. Pick one.");
+        process.exit(1);
+    }
+    const body = { signalType: "clock_in" };
+    if (options.ago) {
+        try {
+            body.minutesAgo = parseDurationToMinutes(options.ago);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    if (options.at) {
+        if (!/^\d{2}:\d{2}(:\d{2})?$/.test(options.at)) {
+            console.error(`Invalid time "${options.at}". Use HH:mm or HH:mm:ss format.`);
+            process.exit(1);
+        }
+        body.effectiveTime = options.at;
+    }
     try {
-        const data = await post("/api/clock-signal", { signalType: "clock_in" });
+        const data = await post("/api/clock-signal", body);
         const response = ClockSignalResponseSchema.parse(data);
         if (response.signal.alreadyExists) {
             console.log(`\nAlready clocked in - must clock out first.`);
@@ -60,11 +111,21 @@ export async function clockInCommand() {
             console.log(`    Time: ${response.signal.effectiveTime}`);
             console.log(`    Timezone: ${response.signal.timezone}`);
         }
+        else if (response.signal.reopened) {
+            console.log(`\nPrevious session reopened — clock-out removed.`);
+            console.log(`  Clocked in since:`);
+            console.log(`    Date: ${response.signal.workDate}`);
+            console.log(`    Time: ${response.signal.effectiveTime}`);
+            console.log(`    Timezone: ${response.signal.timezone}`);
+        }
         else {
             console.log(`\nClock In recorded!`);
             console.log(`  Date: ${response.signal.workDate}`);
             console.log(`  Time: ${response.signal.effectiveTime}`);
             console.log(`  Timezone: ${response.signal.timezone}`);
+            if (response.signal.clamped && response.signal.requestedTime) {
+                console.log(`  Adjusted: you asked for ${response.signal.requestedTime}, but that's outside the allowed window for this day.`);
+            }
         }
     }
     catch (error) {
@@ -83,14 +144,43 @@ export async function clockInCommand() {
     }
 }
 /**
- * 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 async function clockOutCommand() {
+export async function clockOutCommand(options = {}) {
     if (!checkAuth()) {
         process.exit(1);
     }
+    if (options.ago && options.at) {
+        console.error("Cannot use --ago and --at together. Pick one.");
+        process.exit(1);
+    }
+    const body = { signalType: "clock_out" };
+    if (options.ago) {
+        try {
+            body.minutesAgo = parseDurationToMinutes(options.ago);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    if (options.at) {
+        if (!/^\d{2}:\d{2}(:\d{2})?$/.test(options.at)) {
+            console.error(`Invalid time "${options.at}". Use HH:mm or HH:mm:ss format.`);
+            process.exit(1);
+        }
+        body.effectiveTime = options.at;
+    }
     try {
-        const data = await post("/api/clock-signal", { signalType: "clock_out" });
+        const data = await post("/api/clock-signal", body);
         const response = ClockSignalResponseSchema.parse(data);
         if (response.signal.alreadyExists) {
             console.log(`\nNot clocked in - must clock in first.`);
@@ -106,6 +196,9 @@ export async function clockOutCommand() {
             console.log(`  Date: ${response.signal.workDate}`);
             console.log(`  Time: ${response.signal.effectiveTime}`);
             console.log(`  Timezone: ${response.signal.timezone}`);
+            if (response.signal.clamped && response.signal.requestedTime) {
+                console.log(`  Adjusted: you asked for ${response.signal.requestedTime}, but that's before this session's earliest allowed time.`);
+            }
         }
     }
     catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/commands/login.ts"],"names":[],"mappings":"AAKA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAsFlD"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/commands/login.ts"],"names":[],"mappings":"AAKA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAmFlD"}

package/dist/src/commands/login.js

@@ -1,12 +1,12 @@
 import { get } from "../lib/api.js";
 import { pollForToken, requestDeviceCode, sleep } from "../lib/auth.js";
-import { isLoggedIn, setToken } from "../lib/config.js";
+import { setToken } from "../lib/config.js";
 import { UserSchema } from "../lib/validators.js";
 export async function loginCommand() {
-    if (isLoggedIn()) {
-        console.log("You are already logged in. Use 'clocktopus logout' to log out first.");
-        return;
-    }
+    // If the user is already logged in we still start a fresh device flow
+    // — `setToken` on success overwrites the existing token. We don't
+    // clear the old token up-front, so a failed/cancelled/timed-out login
+    // leaves the previously-valid session intact.
     console.log("Starting device authorization...\n");
     try {
         const deviceCode = await requestDeviceCode();

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA4EA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA4IA,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";
@@ -16,12 +21,12 @@ 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);
@@ -45,17 +50,51 @@ const clock = program
     .description("Record clock-in and clock-out signals");
 clock
     .command("in")
-    .description("Record clock-in for today")
-    .action(clockInCommand);
+    .description("Record clock-in for today (optionally backdated)")
+    .option("--ago <duration>", "Backdate by a duration relative to now (e.g. 45m, 1h, 1h30m)")
+    .option("--at <time>", "Backdate to an absolute time in your timezone (HH:mm or HH:mm:ss)")
+    .action((options) => clockInCommand(options));
 clock
     .command("out")
-    .description("Record clock-out for today")
-    .action(clockOutCommand);
+    .description("Record clock-out for today (optionally backdated)")
+    .option("--ago <duration>", "Backdate by a duration relative to now (e.g. 45m, 1h, 1h30m)")
+    .option("--at <time>", "Backdate to an absolute time in your timezone (HH:mm or HH:mm:ss)")
+    .action((options) => clockOutCommand(options));
 clock
     .command("status")
     .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 Claude Code 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")
+    .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")
+    .action((options) => disableCommand(options));
+// Invoked by Claude Code, 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.
+agent
+    .command("hook", { hidden: true })
+    .description("Internal: Claude Code SessionStart/SessionEnd hook")
+    .action(hookCommand);
 export function run() {
     program.parse();
 }

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export type CredentialSource = "environment" | "settings" | "none";
+export type ResolvedAgentCredentials = {
+    token: string | null;
+    endpoint: string | null;
+    tokenSource: CredentialSource;
+    endpointSource: CredentialSource;
+};
+export declare function resolveAgentCredentials(): 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 settings.json for the hook.
+ *
+ * Prefers the bare name, but only after confirming that `clocktopus` on
+ * PATH resolves to *this* executable. Hooks run through a shell whose PATH
+ * may differ from the interactive one, and a bare name that does not
+ * resolve there fails silently — the session runs fine and every bit of
+ * repository context is lost. An absolute path is uglier and survives that;
+ * `doctor` checks it still exists.
+ */
+export declare function resolveHookCommand(): {
+    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":"AAYA;;;;;;;;;;GAUG;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;CAClC,CAAC;AAEF,wBAAgB,uBAAuB,IAAI,wBAAwB,CA2BlE;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;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CA8BA"}

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

@@ -0,0 +1,143 @@
+import { accessSync, constants, existsSync, readFileSync, realpathSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { readInstalledTelemetry } from "./claude-settings.js";
+export function resolveAgentCredentials() {
+    const envToken = process.env.CLOCKTOPUS_INGEST_TOKEN?.trim();
+    const envEndpoint = process.env.CLOCKTOPUS_OTEL_ENDPOINT?.trim();
+    let settingsToken;
+    let settingsEndpoint;
+    try {
+        const installed = readInstalledTelemetry();
+        settingsToken = installed.env.CLOCKTOPUS_INGEST_TOKEN;
+        settingsEndpoint = installed.env.CLOCKTOPUS_OTEL_ENDPOINT;
+    }
+    catch {
+        // A malformed settings.json is reported properly by `setup` and
+        // `doctor`. Credential resolution must not throw — the hook calls it on
+        // every session start.
+    }
+    return {
+        token: envToken || settingsToken || null,
+        endpoint: (envEndpoint || settingsEndpoint || null)?.replace(/\/$/, "") ?? null,
+        tokenSource: envToken ? "environment" : settingsToken ? "settings" : "none",
+        endpointSource: envEndpoint
+            ? "environment"
+            : settingsEndpoint
+                ? "settings"
+                : "none",
+    };
+}
+/** Masks a token for display: never print more than the stored prefix. */
+export function maskToken(token) {
+    return token.length <= 15 ? "…" : `${token.slice(0, 15)}…`;
+}
+/**
+ * Files that commonly export the same variables, and would be shadowed.
+ *
+ * Scanned rather than guessed at, because "your `.envrc` is being ignored"
+ * is only useful advice when it names the file. The repo-local `.envrc` is
+ * included because that is exactly how this project was dogfooded before
+ * the CLI existed.
+ */
+const SHELL_FILES = [
+    ".bashrc",
+    ".bash_profile",
+    ".zshrc",
+    ".zshenv",
+    ".profile",
+    ".config/fish/config.fish",
+];
+export function findShadowedExports(cwd = process.cwd()) {
+    const candidates = [
+        ...SHELL_FILES.map((file) => join(homedir(), file)),
+        join(cwd, ".envrc"),
+    ];
+    const found = [];
+    for (const path of candidates) {
+        let contents;
+        try {
+            if (!existsSync(path))
+                continue;
+            contents = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const keys = [
+            "CLOCKTOPUS_INGEST_TOKEN",
+            "CLOCKTOPUS_OTEL_ENDPOINT",
+            "OTEL_EXPORTER_OTLP_ENDPOINT",
+            "OTEL_EXPORTER_OTLP_HEADERS",
+            "CLAUDE_CODE_ENABLE_TELEMETRY",
+        ].filter((key) => new RegExp(`^\\s*(export\\s+)?${key}=`, "m").test(contents));
+        if (keys.length > 0)
+            found.push({ path, keys });
+    }
+    return found;
+}
+/**
+ * The command to write into settings.json for the hook.
+ *
+ * Prefers the bare name, but only after confirming that `clocktopus` on
+ * PATH resolves to *this* executable. Hooks run through a shell whose PATH
+ * may differ from the interactive one, and a bare name that does not
+ * resolve there fails silently — the session runs fine and every bit of
+ * repository context is lost. An absolute path is uglier and survives that;
+ * `doctor` checks it still exists.
+ */
+export function resolveHookCommand() {
+    const script = process.argv[1] ? resolve(process.argv[1]) : null;
+    const quote = (value) => /[\s"']/.test(value) ? `"${value}"` : value;
+    if (script && resolvesOnPath("clocktopus", script)) {
+        return {
+            command: "clocktopus agent hook",
+            usesAbsolutePath: false,
+            binaryPath: script,
+        };
+    }
+    if (script) {
+        // `node <script>` rather than executing the script directly: the file in
+        // a published package keeps its shebang, but a checkout may not have the
+        // executable bit, and the hook must not depend on that.
+        return {
+            command: `${quote(process.execPath)} ${quote(script)} agent hook`,
+            usesAbsolutePath: true,
+            binaryPath: script,
+        };
+    }
+    return {
+        command: "clocktopus agent hook",
+        usesAbsolutePath: false,
+        binaryPath: null,
+    };
+}
+function resolvesOnPath(name, expected) {
+    const searchPath = process.env.PATH;
+    if (!searchPath)
+        return false;
+    let expectedReal;
+    try {
+        expectedReal = realpathSync(expected);
+    }
+    catch {
+        return false;
+    }
+    for (const dir of searchPath.split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (realpathSync(candidate) === expectedReal)
+                return true;
+            // A different `clocktopus` earlier on PATH would shadow this one, so
+            // stop rather than keep looking for a match further down.
+            return false;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,36 @@
+import { z } from "zod";
+declare const LastRunSchema: z.ZodObject<{
+    at: z.ZodString;
+    event: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    tokenPrefix: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type HookLastRun = z.infer<typeof LastRunSchema>;
+declare const StartStateSchema: z.ZodObject<{
+    sha: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HookStartState = z.infer<typeof StartStateSchema>;
+export declare function writeStartState(sessionId: string, sha: string, cwd: string): void;
+export declare function readStartState(sessionId: string): HookStartState | undefined;
+export declare function clearStartState(sessionId: string): void;
+export declare function listStartStates(): Array<{
+    sessionId: string;
+    ageMs: number;
+    /**
+     * When the state file was last touched — the newest moment this machine
+     * has evidence the session existed. The sweep sends it as the abandoned
+     * session's `ended_at` so the receiver does not stamp its own clock,
+     * hours later, as the end of a window used to attribute commits.
+     */
+    lastActivityAt: Date;
+}>;
+export declare function recordLastRun(run: HookLastRun): void;
+export declare function readLastRun(): HookLastRun | null;
+export declare function clearHookState(): void;
+export {};
+//# sourceMappingURL=agent-hook-state.d.ts.map

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

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

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

@@ -0,0 +1,136 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * On-disk state the SessionStart/SessionEnd hook keeps between its two
+ * invocations, plus the record of what the last invocation achieved.
+ *
+ * Under the cache directory rather than the repository so it never shows up
+ * in `git status`. The path is unchanged from the standalone script this
+ * command replaced (`scripts/agent-telemetry/claude-hook.mjs`, since
+ * deleted) on purpose: a session that started under the old script must
+ * still be able to close under the new one, and a sweep must still find
+ * what the old one abandoned.
+ */
+const CACHE_DIR = join(homedir(), ".cache", "clocktopus");
+const STATE_DIR = join(CACHE_DIR, "agent-sessions");
+/**
+ * The hook's last outcome, written every run.
+ *
+ * This is the only place the pipeline reports on itself from the machine's
+ * own side. The hook must stay silent — it cannot warn, prompt or print —
+ * so instead it leaves a receipt, and `agent status` / `agent doctor` read
+ * it. Without this, a token that started returning 401 mid-week is
+ * invisible locally: the session runs normally and nothing is written
+ * anywhere the user looks.
+ */
+const LAST_RUN_FILE = join(CACHE_DIR, "agent-hook-last.json");
+const LastRunSchema = z.object({
+    at: z.string(),
+    event: z.string().optional(),
+    sessionId: z.string().optional(),
+    endpoint: z.string().optional(),
+    tokenPrefix: z.string().optional(),
+    /** HTTP status from the receiver, or null when the request never landed. */
+    status: z.number().nullable().optional(),
+    error: z.string().nullable().optional(),
+    repository: z.string().nullable().optional(),
+});
+const StartStateSchema = z.object({
+    sha: z.string(),
+    cwd: z.string().optional(),
+});
+const stateFile = (sessionId) => join(STATE_DIR, `${sessionId.replace(/[^\w-]/g, "")}.sha`);
+export function writeStartState(sessionId, sha, cwd) {
+    try {
+        mkdirSync(STATE_DIR, { recursive: true });
+        // `cwd` is stored alongside the SHA because the sweep runs from
+        // whatever repository the *next* session happens to start in.
+        // Resolving an abandoned session's SHA against the wrong checkout would
+        // either fail or, worse, succeed against an unrelated history.
+        writeFileSync(stateFile(sessionId), JSON.stringify({ sha, cwd }), "utf8");
+    }
+    catch {
+        // Losing the start SHA costs the exact commit list, not the session.
+    }
+}
+export function readStartState(sessionId) {
+    try {
+        const raw = readFileSync(stateFile(sessionId), "utf8").trim();
+        if (!raw)
+            return undefined;
+        try {
+            const parsed = StartStateSchema.safeParse(JSON.parse(raw));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            // Files written by earlier versions hold a bare SHA. A session that
+            // started under the old format must still close correctly.
+            return { sha: raw };
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearStartState(sessionId) {
+    try {
+        rmSync(stateFile(sessionId), { force: true });
+    }
+    catch {
+        // Best effort; a stale file is overwritten by the next session anyway.
+    }
+}
+export function listStartStates() {
+    try {
+        const now = Date.now();
+        return readdirSync(STATE_DIR)
+            .filter((name) => name.endsWith(".sha"))
+            .flatMap((name) => {
+            try {
+                const { mtimeMs } = statSync(join(STATE_DIR, name));
+                return [
+                    {
+                        sessionId: name.replace(/\.sha$/, ""),
+                        ageMs: now - mtimeMs,
+                        lastActivityAt: new Date(mtimeMs),
+                    },
+                ];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function recordLastRun(run) {
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        writeFileSync(LAST_RUN_FILE, JSON.stringify(run, null, 2), "utf8");
+    }
+    catch {
+        // A missing receipt degrades diagnostics; it must never fail a session.
+    }
+}
+export function readLastRun() {
+    try {
+        const parsed = LastRunSchema.safeParse(JSON.parse(readFileSync(LAST_RUN_FILE, "utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearHookState() {
+    try {
+        rmSync(STATE_DIR, { recursive: true, force: true });
+        rmSync(LAST_RUN_FILE, { force: true });
+    }
+    catch {
+        // Nothing to clean up, or not ours to clean up.
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Talks to the OTLP receiver directly, which is the whole point.
+ *
+ * The receiver is a different host from the web app — its own Router, its
+ * own Lambda, its own domain — so a token that works against the dashboard
+ * proves nothing about whether telemetry can reach ingest. This check is
+ * the only local way to tell "nothing has happened yet" apart from "nothing
+ * can happen": a wrong endpoint, a revoked token and an idle afternoon all
+ * look identical otherwise.
+ */
+export type ReceiverCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_token";
+} | {
+    ok: false;
+    reason: "unexpected_status";
+    status: number;
+} | {
+    ok: false;
+    reason: "unreachable";
+    message: string;
+};
+export declare function verifyReceiver(endpoint: string, token: string): Promise<ReceiverCheck>;
+//# sourceMappingURL=agent-receiver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-receiver.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-receiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC,CA+BxB"}