@blastin-dev/clocktopus-cli 0.2.1 → 0.3.1

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

@@ -1,25 +1,3 @@
-/**
- * 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 declare function setupCommand(options: {
     name?: string;
     force?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8LhB"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/setup.ts"],"names":[],"mappings":"AAsCA,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0LhB"}

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

@@ -10,28 +10,21 @@ 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.
- */
+// Configures this machine's coding agents to report spend to Clocktopus.
+//
+// One command, however many agents are installed: it configures what it finds on PATH —
+// 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 what makes `agent doctor` able to say which value
+// is in force; configuration spread over `.envrc`, a shell profile and a CLI config can
+// be reported on but never resolved, and this project already lost real spend to exactly
+// that.
+//
+// Idempotent by default: re-running repairs the hooks and refreshes the endpoint while
+// keeping the existing token, so adding a newly-installed agent later reuses it.
+// `--force` mints a replacement.
 export async function setupCommand(options) {
     if (!isLoggedIn()) {
         console.error("Not logged in. Run 'clocktopus login' first.");
@@ -72,11 +65,9 @@ export async function setupCommand(options) {
         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.
+    // One machine, one token, however many agents. Every mint leaves another live token on
+    // the account, and 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;
@@ -121,8 +112,7 @@ export async function setupCommand(options) {
             });
         }
         catch (error) {
-            // One agent failing must not strand the others half-configured, so
-            // the loop continues and the failure is reported in the summary.
+            // One agent failing must not strand the others half-configured.
             console.error(`✗ ${entry.agent.label}: ${error instanceof Error ? error.message : "unknown error"}`);
         }
     }
@@ -155,10 +145,10 @@ export async function setupCommand(options) {
     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.
+    // 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 is how spend ends up
+    // stranded.
     const repoStatus = await fetchRepoStatus();
     if (repoStatus) {
         for (const line of renderRepoBlock(repoStatus))
@@ -167,12 +157,11 @@ export async function setupCommand(options) {
     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.
+    // The single most common reason a correct setup appears dead: both the exporter and the
+    // hook read their configuration once, at process start.
     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.
+    // 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}`);
@@ -180,15 +169,10 @@ export async function setupCommand(options) {
     }
     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.
- */
+// Decides which agents to configure, asking only when the answer is genuinely ambiguous.
+// `--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()));
@@ -200,9 +184,9 @@ async function selectAgents(survey, installed, requested) {
                 .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.
+        // 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.`);
@@ -243,13 +227,8 @@ async function selectAgents(survey, installed, requested) {
         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.
- */
+// 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.
 function findExistingToken(survey) {
     for (const entry of survey) {
         try {
@@ -266,9 +245,8 @@ function findExistingToken(survey) {
 }
 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.
+    // Only Claude Code applies config `env` over the inherited environment, so only it can
+    // silently shadow a shell export. Codex reads its token straight out of config.toml.
     if (configured.some(({ entry }) => entry.agent.id === "claude")) {
         const shadowed = findShadowedExports();
         if (shadowed.length > 0) {
@@ -281,8 +259,8 @@ function collectWarnings(configured) {
                 "  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.
+    // 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()) {

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

@@ -1,22 +1,4 @@
 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;
@@ -33,21 +15,6 @@ 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;

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

@@ -1 +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"}
+{"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;AAkB5D,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,CAyC1B;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAcD,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC,CA+BD;AAYD,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"}

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

@@ -27,9 +27,8 @@ export function resolveAgentCredentials(agent = "claude") {
         }
     }
     catch {
-        // A malformed config file is reported properly by `setup` and `doctor`.
-        // Credential resolution must not throw — the hook calls it on every
-        // session start.
+        // A malformed config file is reported properly by `setup` and `doctor`. Credential
+        // resolution must not throw — the hook calls it on every session start.
     }
     return {
         token: envToken || fileToken || null,
@@ -51,14 +50,9 @@ export function resolveAgentCredentials(agent = "claude") {
 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.
- */
+// 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.
 const SHELL_FILES = [
     ".bashrc",
     ".bash_profile",
@@ -95,21 +89,16 @@ export function findShadowedExports(cwd = process.cwd()) {
     }
     return found;
 }
-/**
- * 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.
- */
+// The command to write into an agent's hook configuration.
+//
+// Prefers the bare name, but only after confirming `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.
+//
+// The provider is baked into the command because the two agents send identical hook
+// payloads, with no marker of any kind: which agent is calling can only be known from how
+// the hook was installed.
 export function resolveHookCommand(provider) {
     const script = process.argv[1] ? resolve(process.argv[1]) : null;
     const quote = (value) => /[\s"']/.test(value) ? `"${value}"` : value;

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

@@ -16,6 +16,7 @@ declare const StartStateSchema: z.ZodObject<{
     cwd: z.ZodOptional<z.ZodString>;
     provider: z.ZodOptional<z.ZodString>;
     closed: z.ZodOptional<z.ZodBoolean>;
+    startedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type HookStartState = z.infer<typeof StartStateSchema>;
 export declare function writeStartState(sessionId: string, state: {
@@ -23,18 +24,13 @@ export declare function writeStartState(sessionId: string, state: {
     cwd: string;
     provider: string;
     closed?: boolean;
+    startedAt?: 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;

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

@@ -1 +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;;;;;;;;;;iBAYjB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;;;iBAoBpB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACtE,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"}
+{"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;AAqBxB,QAAA,MAAM,aAAa;;;;;;;;;;iBAYjB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;;;;iBAgBpB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,IAAI,CAUN;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAe5E;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;IAId,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

@@ -2,34 +2,26 @@ import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync,
 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.
- */
+// 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,
+// on purpose: a session that started under the old script must still 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.
- */
+// The hook's last outcome, written every run.
+//
+// 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 it leaves a receipt, and
+// `agent status` / `agent doctor` read it. Without this, a token that started returning
+// 401 mid-week is invisible locally.
 const LAST_RUN_FILE = join(CACHE_DIR, "agent-hook-last.json");
 const LastRunSchema = z.object({
     at: z.string(),
     event: z.string().optional(),
-    /** Which agent's hook ran — one receipt file is shared by all of them. */
+    // One receipt file is shared by all of them.
     provider: z.string().optional(),
     sessionId: z.string().optional(),
     endpoint: z.string().optional(),
@@ -42,32 +34,27 @@ const LastRunSchema = z.object({
 const StartStateSchema = z.object({
     sha: z.string(),
     cwd: z.string().optional(),
-    /**
-     * The agent that opened this session.
-     *
-     * Recorded because the sweep runs from whichever agent starts *next*, and
-     * closing a Codex session as `claude_code` would not close it at all — it
-     * would open a second, empty session row under the wrong provider and
-     * leave the real one hanging forever.
-     */
+    // The agent that opened this session. Recorded because the sweep runs from whichever
+    // agent starts *next*, and closing a Codex session as `claude_code` would open a second,
+    // empty session row under the wrong provider and leave the real one hanging.
     provider: z.string().optional(),
-    /**
-     * Set once the session has had a real SessionEnd, and kept only because
-     * its host can send another one — see `hostRepeatsSessionEnd`. The file
-     * still holds the starting SHA the next SessionEnd needs to diff against,
-     * but the session is already closed in the database, so the sweep must
-     * delete it rather than close it a second time with a stale HEAD.
-     */
+    // Set once the session has had a real SessionEnd, and kept only because its host can send
+    // another one — see `hostRepeatsSessionEnd`. The file still holds the starting SHA the
+    // next SessionEnd needs, but the session is already closed, so the sweep must delete it
+    // rather than close it again with a stale HEAD.
     closed: z.boolean().optional(),
+    // When SessionStart fired, ISO. Bounds the reflog read SessionEnd declares from —
+    // see `declared-commits.ts`. Optional because sessions opened by an older CLI have
+    // no such stamp, and those declare nothing rather than read an unbounded reflog.
+    startedAt: z.string().optional(),
 });
 const stateFile = (sessionId) => join(STATE_DIR, `${sessionId.replace(/[^\w-]/g, "")}.sha`);
 export function writeStartState(sessionId, state) {
     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.
+        // `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(state), "utf8");
     }
     catch {
@@ -84,8 +71,7 @@ export function readStartState(sessionId) {
             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.
+            // Files written by earlier versions hold a bare SHA.
             return { sha: raw };
         }
     }

package/dist/src/lib/agents.d.ts

@@ -1,27 +1,3 @@
-/**
- * The agents `clocktopus agent` can wire up, behind one interface.
- *
- * Everything agent-specific lives here: where the config is, how to detect
- * an install, what "configured" means, and how to add or remove our half of
- * it. `setup`, `status`, `doctor` and `disable` iterate this list, so
- * adding a third agent is a new entry rather than a new branch in five
- * commands.
- *
- * The two supported agents look similar and are not:
- *
- * |               | Claude Code                | Codex CLI                        |
- * | ------------- | -------------------------- | -------------------------------- |
- * | telemetry     | OTLP metrics, real dollars | OTLP **logs**, tokens only       |
- * | config        | `settings.json` (one file) | `config.toml` + `hooks.json`     |
- * | credentials   | env vars it injects        | read back out of `config.toml`   |
- * | takes effect  | restart                    | restart **and** a trust prompt   |
- *
- * The credentials row is the subtle one. Claude Code applies `settings.json`
- * `env` to the session, so our hook inherits the token from the process
- * environment. Codex injects nothing, so the Codex hook has to read the
- * token back out of `config.toml` — which is why `resolveAgentCredentials`
- * takes a provider.
- */
 export type AgentId = "claude" | "codex" | "opencode";
 /** How the ingested session is labelled — must match `AgentProvider` in core. */
 export type AgentProviderId = "claude_code" | "codex_cli" | "opencode";
@@ -41,28 +17,7 @@ export type AgentAdapter = {
     provider: AgentProviderId;
     /** Executable name, used both to detect an install and to name it in help. */
     binary: string;
-    /**
-     * Whether the agent runs hooks off the session's critical path itself.
-     *
-     * Claude Code does, given `"async": true`. Codex does not — 0.147 skips
-     * an async SessionStart outright and 0.148 still forces SessionEnd
-     * synchronous — so its hooks omit the key and `agent hook` backgrounds
-     * itself instead. See the header of `commands/agent/hook.ts`.
-     */
     hostRunsHooksAsync: boolean;
-    /**
-     * Whether the host can fire SessionEnd more than once for one session.
-     *
-     * Claude Code and Codex each end a session exactly once. OpenCode has no
-     * session-ended event at all — the plugin maps `session.idle` to
-     * SessionEnd, and that fires every time the agent stops and waits for a
-     * human, so a five-turn conversation sends five of them.
-     *
-     * The hook keeps its starting SHA in a state file keyed by session id and
-     * deletes it on SessionEnd. Deleting it after the first idle would leave
-     * every later turn with no range to diff, so nothing committed after the
-     * agent's first pause could ever be declared — see `commands/agent/hook.ts`.
-     */
     hostRepeatsSessionEnd: boolean;
     /** Files this agent's telemetry configuration lives in. */
     paths(): string[];
@@ -77,18 +32,7 @@ export type AgentAdapter = {
     remove(): {
         removed: string[];
     };
-    /**
-     * Anything the user must still do by hand before telemetry flows.
-     * Empty when the agent is ready apart from a restart.
-     */
     pendingActions(): string[];
-    /**
-     * Why the installed configuration is behind this CLI, or null when it is
-     * current. Only defined for agents whose integration is *generated
-     * source*, which is OpenCode alone: the others store a command string
-     * that means whatever the installed CLI means, so upgrading the CLI
-     * upgrades them and there is nothing to be behind.
-     */
     staleReason?(): string | null;
 };
 /** `true` when the parse error is one of ours, whichever agent raised it. */
@@ -104,12 +48,5 @@ export type AgentSurvey = {
     /** Set when the agent's config exists but could not be parsed. */
     unreadable: string | null;
 };
-/**
- * What is on this machine, and what is already wired up.
- *
- * Detection is by `--version` rather than by config directory: `~/.claude`
- * and `~/.codex` both outlive an uninstall, so a stale directory would
- * offer to configure an agent that is no longer there.
- */
 export declare function surveyAgents(): AgentSurvey[];
 //# sourceMappingURL=agents.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/lib/agents.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAEtD,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,GAAG,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACrE,2EAA2E;IAC3E,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,KAAK,IAAI,MAAM,EAAE,CAAC;IAClB,IAAI,IAAI,mBAAmB,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG;QACtE,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChC;;;OAGG;IACH,cAAc,IAAI,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAKjE;AAuND,eAAO,MAAM,MAAM,EAAE,SAAS,YAAY,EAIzC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAqB5C"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/lib/agents.ts"],"names":[],"mappings":"AAyDA,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAEtD,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvE,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,GAAG,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACrE,2EAA2E;IAC3E,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAKf,kBAAkB,EAAE,OAAO,CAAC;IAU5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,KAAK,IAAI,MAAM,EAAE,CAAC;IAClB,IAAI,IAAI,mBAAmB,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG;QACtE,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAGhC,cAAc,IAAI,MAAM,EAAE,CAAC;IAI3B,WAAW,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAKjE;AAkND,eAAO,MAAM,MAAM,EAAE,SAAS,YAAY,EAIzC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAOF,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAqB5C"}