neuvikon 0.2.7 → 0.2.9

package/README.md

@@ -57,6 +57,9 @@ into `.claude/settings.json` for you, whenever that project already has one:
 {
   "hooks": {
     "Stop": [{ "hooks": [{ "type": "command", "command": "npx neuvikon report" }] }],
+    "Notification": [
+      { "hooks": [{ "type": "command", "command": "npx neuvikon report --heartbeat" }] }
+    ],
     "SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx neuvikon stop" }] }]
   }
 }
@@ -66,6 +69,12 @@ into `.claude/settings.json` for you, whenever that project already has one:
 turn adds that turn rather than re-counting the conversation. It is silent and
 always exits 0 — a token count is never worth interrupting someone's work.
 
+`Notification` fires when Claude Code is blocked mid-turn — a permission
+prompt, a question, waiting on you — exactly when `Stop` doesn't fire yet. The
+`--heartbeat` flag tells `report` to still check in even when there's no new
+token usage to send, so a session that's genuinely just waiting on you doesn't
+read as stopped on the board.
+
 If `.claude/settings.json` doesn't exist yet, or another agent is the one
 being used, add the block above by hand.
 

package/dist/index.mjs

@@ -1,11 +1,429 @@
 #!/usr/bin/env node
-import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
+//#region src/config.ts
+/**
+* The two deployments this CLI knows about. The browser origin is kept here
+* rather than read back from the server, because the API answers on a Convex
+* domain while approval happens on the web app's — one is not derivable from
+* the other, and guessing wrong sends people to a page that does not exist.
+*/
+const DEPLOYMENTS = {
+	production: {
+		api: "https://flexible-bird-801.eu-west-1.convex.site",
+		web: "https://www.neuvikon.space"
+	},
+	development: {
+		api: "https://calm-sturgeon-831.eu-west-1.convex.site",
+		web: "http://localhost:3000"
+	}
+};
+/**
+* `--dev` targets the development deployment; NEUVIKON_URL overrides the API
+* for a self-hosted install, in which case the web origin is unknowable and
+* falls back to the matching default.
+*/
+function resolveDeployment(flags) {
+	const base = flags.has("dev") ? DEPLOYMENTS.development : DEPLOYMENTS.production;
+	const override = flags.get("url") || process.env.NEUVIKON_URL;
+	return override ? {
+		api: override.trim().replace(/\/+$/, ""),
+		web: base.web
+	} : base;
+}
+const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? DEPLOYMENTS.production.api;
+const CONFIG_DIR = join(homedir(), ".neuvikon");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+/**
+* Somewhere a browser cannot open — CI, a container, a remote box — there is no
+* way to complete a device login, so a token handed in through the environment
+* stands in for one. It wins over the config file: an explicit env var is the
+* more specific instruction.
+*/
+function credentialsFromEnv() {
+	const token = process.env.NEUVIKON_TOKEN;
+	if (!token) return null;
+	return {
+		token,
+		url: DEFAULT_SITE_URL
+	};
+}
+function readCredentials() {
+	const fromEnv = credentialsFromEnv();
+	if (fromEnv) return fromEnv;
+	let raw;
+	try {
+		raw = readFileSync(CONFIG_PATH, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { token, url } = parsed;
+		if (typeof token !== "string" || !token) return null;
+		if (typeof url !== "string" || !url) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/**
+* A token on disk is only as safe as its permissions, so directory and file are
+* locked to the owner on every write, not just on first create — an earlier
+* version may have left them readable.
+*/
+function writeCredentials(credentials) {
+	mkdirSync(CONFIG_DIR, {
+		recursive: true,
+		mode: 448
+	});
+	chmodSync(CONFIG_DIR, 448);
+	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
+	chmodSync(CONFIG_PATH, 384);
+}
+function clearCredentials() {
+	try {
+		rmSync(CONFIG_PATH);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/api.ts
+var ApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "ApiError";
+	}
+};
+/** A request that never reached the server: offline, DNS, TLS, timeout. */
+var NetworkError = class extends Error {
+	constructor(cause) {
+		super("Could not reach Neuvikon", { cause });
+		this.name = "NetworkError";
+	}
+};
+const TIMEOUT_MS = 15e3;
+/**
+* The one place an HTTP failure becomes a typed error. Callers decide what a
+* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
+* wants to shout about it.
+*/
+async function post(url, path, body) {
+	let response;
+	try {
+		response = await fetch(`${url}${path}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new NetworkError(error);
+	}
+	const payload = await response.json().catch(() => ({}));
+	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
+	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
+	return payload;
+}
+function normalizeUrl(url) {
+	return url.trim().replace(/\/+$/, "");
+}
+//#endregion
+//#region src/session.ts
+/**
+* Distinguishes concurrent agents working in the *same* checkout — two Claude
+* Code panes both running `claude` in this directory get two session files,
+* because each one's process tree carries its own CLAUDE_CODE_SESSION_ID. A
+* tool that doesn't set it (or a person typing the command by hand) falls
+* back to the pre-multi-agent behavior of one session per directory.
+*/
+function instanceKey() {
+	return process.env.CLAUDE_CODE_SESSION_ID?.trim() || null;
+}
+/**
+* Scoped to the working directory rather than the machine: two checkouts driven
+* in parallel are two sessions, which is what running two agents means. Within
+* one checkout, `instanceKey()` further scopes it per agent so two panes in the
+* same directory don't stop each other's session out from under them.
+*/
+function sessionPath() {
+	const key = instanceKey();
+	const filename = key ? `.neuvikon-session.${key}` : ".neuvikon-session";
+	return join(process.cwd(), filename);
+}
+function readSession() {
+	let raw;
+	try {
+		raw = readFileSync(sessionPath(), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { sessionKey, ticket } = parsed;
+		if (typeof sessionKey !== "string" || typeof ticket !== "string") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function writeSession(session) {
+	writeFileSync(sessionPath(), `${JSON.stringify(session, null, 2)}\n`);
+}
+function clearSession() {
+	try {
+		rmSync(sessionPath());
+	} catch {}
+}
+//#endregion
+//#region src/ticket.ts
+/**
+* Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
+* server's — it pulls *candidates* out of arbitrary pasted prose and lets the
+* server decide which one is a real ticket in the caller's organization, so the
+* authoritative rule lives in exactly one place.
+*/
+const CANDIDATE = /\b([A-Z0-9]{2,8})-(\d{1,9})\b/g;
+/** Every distinct ref-shaped token in `text`, in the order it appears. */
+function extractTicketRefs(text) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of text.toUpperCase().matchAll(CANDIDATE)) {
+		if (/^\d+$/.test(match[1])) continue;
+		seen.add(`${match[1]}-${match[2]}`);
+	}
+	return [...seen];
+}
+/** Reads piped input, if any. Returns "" when stdin is a terminal. */
+async function readStdin() {
+	if (process.stdin.isTTY) return "";
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+//#endregion
+//#region src/usage.ts
+/**
+* Sums token usage out of a JSONL agent transcript, starting from `offset`.
+*
+* Reading incrementally is what makes a per-turn hook safe to call repeatedly:
+* each call reports only what was appended since the last one. Anything that
+* doesn't parse is skipped rather than fatal — a transcript being appended to
+* while we read it will have a torn final line, and that is normal, not an
+* error worth failing a user's turn over.
+*/
+/**
+* Where the transcript currently ends, so a session that starts mid-conversation
+* can mark its starting point instead of counting what came before it.
+*/
+function transcriptSize(path) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return null;
+	}
+	try {
+		return fstatSync(fd).size;
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+function readUsageSince(path, offset) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return null;
+	}
+	try {
+		const size = fstatSync(fd).size;
+		const from = offset > size ? 0 : offset;
+		if (size === from) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: size
+		};
+		const buffer = Buffer.alloc(size - from);
+		readSync(fd, buffer, 0, buffer.length, from);
+		const text = buffer.toString("utf8");
+		const lastNewline = text.lastIndexOf("\n");
+		if (lastNewline === -1) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: from
+		};
+		let tokensIn = 0;
+		let tokensOut = 0;
+		for (const line of text.slice(0, lastNewline).split("\n")) {
+			if (!line.trim()) continue;
+			let row;
+			try {
+				row = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			const usage = extractUsage(row);
+			if (!usage) continue;
+			tokensIn += usage.tokensIn;
+			tokensOut += usage.tokensOut;
+		}
+		return {
+			tokensIn,
+			tokensOut,
+			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1))
+		};
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+function toCount$1(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function extractUsage(row) {
+	if (typeof row !== "object" || row === null) return null;
+	const message = row.message;
+	if (typeof message !== "object" || message === null) return null;
+	const usage = message.usage;
+	if (typeof usage !== "object" || usage === null) return null;
+	const fields = usage;
+	return {
+		tokensIn: toCount$1(fields.input_tokens) + toCount$1(fields.cache_read_input_tokens) + toCount$1(fields.cache_creation_input_tokens),
+		tokensOut: toCount$1(fields.output_tokens)
+	};
+}
+/**
+* Claude Code's transcript for the session this command was spawned from.
+*
+* Hooks are handed a `transcript_path` on stdin, but `start` and `stop` are run
+* by the agent's own shell, which only gets the session id in the environment.
+* That id is a uuid, so finding the file by name is exact — and doesn't depend
+* on how Claude Code derives a project directory name from the working
+* directory, which is not a documented format.
+*/
+function claudeTranscriptPath() {
+	const sessionId = process.env.CLAUDE_CODE_SESSION_ID?.trim();
+	if (!sessionId) return void 0;
+	const projects = join(homedir(), ".claude", "projects");
+	let directories;
+	try {
+		directories = readdirSync(projects);
+	} catch {
+		return;
+	}
+	for (const directory of directories) {
+		const candidate = join(projects, directory, `${sessionId}.jsonl`);
+		if (existsSync(candidate)) return candidate;
+	}
+}
+//#endregion
+//#region src/ui.ts
+/**
+* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
+* command's stdout stays a clean, pipeable value.
+*/
+const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
+function paint(code, text) {
+	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+const dim = (text) => paint("2", text);
+const bold = (text) => paint("1", text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31", text);
+const cyan = (text) => paint("36", text);
+function info(message) {
+	process.stderr.write(`${message}\n`);
+}
+function success(message) {
+	process.stderr.write(`${green("✓")} ${message}\n`);
+}
+function warn(message) {
+	process.stderr.write(`${red("!")} ${message}\n`);
+}
+/** Ends the process. Every user-facing failure funnels through here. */
+function fail(message, hint) {
+	process.stderr.write(`${red("✗")} ${message}\n`);
+	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
+	process.exit(1);
+}
+//#endregion
+//#region src/commands/hook-start.ts
+/**
+* `UserPromptSubmit` fires before the turn runs, which is what lets it capture
+* a token baseline at the transcript's current size — anything read from that
+* offset onward is this ticket's usage. Reading it here, instead of lazily on
+* the first `Stop`, is what `report.ts` used to do: by the time `Stop` fires
+* the first turn's usage is already appended, so that baseline came too late
+* and silently discarded a whole turn's tokens (NS-33).
+*/
+function parsePayload(raw) {
+	if (!raw.trim()) return {};
+	try {
+		const payload = JSON.parse(raw);
+		if (typeof payload !== "object" || payload === null) return {};
+		const record = payload;
+		return {
+			prompt: typeof record.prompt === "string" ? record.prompt : void 0,
+			transcriptPath: typeof record.transcript_path === "string" ? record.transcript_path : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/**
+* The `UserPromptSubmit` counterpart to `start`. Unlike `start`, this runs on
+* *every* prompt regardless of whether it mentions a ticket, so it must never
+* fail the hook and block the user's message — no credentials, no ticket ref,
+* or a dead network are all just "nothing to do here", not errors.
+*/
+async function hookStart() {
+	try {
+		const credentials = readCredentials();
+		if (!credentials) return;
+		const { prompt, transcriptPath } = parsePayload(await readStdin());
+		const [ref] = extractTicketRefs(prompt ?? "");
+		if (!ref) return;
+		const existing = readSession();
+		if (existing?.ticket === ref) return;
+		const result = await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "start",
+			ticketRef: ref,
+			tool: "claude-code"
+		});
+		if (existing) await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "stop",
+			sessionKey: existing.sessionKey
+		}).catch(() => void 0);
+		const transcript = transcriptPath ?? claudeTranscriptPath();
+		const transcriptOffset = transcript ? transcriptSize(transcript) ?? void 0 : void 0;
+		writeSession({
+			sessionKey: result.sessionKey,
+			ticket: ref,
+			startedAt: Date.now(),
+			transcriptOffset
+		});
+		success(`Tracking work on ${bold(ref)}`);
+	} catch {}
+}
+//#endregion
 //#region src/agents/hooks.ts
 const REPORT_COMMAND = "npx neuvikon report";
+const HEARTBEAT_COMMAND = "npx neuvikon report --heartbeat";
 const STOP_COMMAND = "npx neuvikon stop";
+const HOOK_START_COMMAND = "npx neuvikon hook-start";
 function hasCommand(groups, command) {
 	return (groups ?? []).some((group) => group.hooks.some((hook) => hook.command === command));
 }
@@ -21,8 +439,20 @@ function withCommand(groups, command) {
 * whose transcript exposes usage, per `usage.ts`. `Stop` fires after every
 * turn, exactly when `report` should read what the transcript gained since
 * last time; `SessionEnd` is the backstop for `stop` when nobody remembered
-* to run it by hand. Without this, `start`/`stop` are the only events an
-* agent ever sends and token usage never leaves zero.
+* to run it by hand.
+*
+* `UserPromptSubmit` covers `start`: relying on the agent to notice a ticket
+* ref in the prompt and remember to run `start` itself is exactly the failure
+* mode reported in NS-31 — an LLM that's mid-instruction-following skips it
+* often enough to be unreliable bookkeeping. The hook makes it deterministic
+* for Claude Code; other tools still fall back to the AGENTS.md instruction.
+*
+* `Notification` fires when Claude Code is blocked mid-turn — a permission
+* prompt, a question, waiting on the user — which is exactly when `Stop`
+* does *not* fire, since the turn hasn't finished. Without a heartbeat there
+* too, a session that's genuinely just waiting on a person reads as stale on
+* the board after `AGENT_SESSION_STALE_MS`, indistinguishable from one that
+* actually stopped (NS-32).
 */
 function installClaudeHooks(root) {
 	const relativePath = join(".claude", "settings.json");
@@ -39,7 +469,7 @@ function installClaudeHooks(root) {
 		};
 	}
 	const hooks = settings.hooks ?? {};
-	if (hasCommand(hooks.Stop, REPORT_COMMAND) && hasCommand(hooks.SessionEnd, STOP_COMMAND)) return {
+	if (hasCommand(hooks.Stop, REPORT_COMMAND) && hasCommand(hooks.Notification, HEARTBEAT_COMMAND) && hasCommand(hooks.SessionEnd, STOP_COMMAND) && hasCommand(hooks.UserPromptSubmit, HOOK_START_COMMAND)) return {
 		path: relativePath,
 		action: "unchanged"
 	};
@@ -48,7 +478,9 @@ function installClaudeHooks(root) {
 		hooks: {
 			...hooks,
 			Stop: withCommand(hooks.Stop, REPORT_COMMAND),
-			SessionEnd: withCommand(hooks.SessionEnd, STOP_COMMAND)
+			Notification: withCommand(hooks.Notification, HEARTBEAT_COMMAND),
+			SessionEnd: withCommand(hooks.SessionEnd, STOP_COMMAND),
+			UserPromptSubmit: withCommand(hooks.UserPromptSubmit, HOOK_START_COMMAND)
 		}
 	};
 	mkdirSync(dirname(path), { recursive: true });
@@ -195,197 +627,34 @@ function installAgentInstructions(root) {
 	}
 	if (existsSync(join(root, ".cursor"))) results.push(writeCursorRule(root));
 	if (existsSync(join(root, ".claude"))) results.push(installClaudeHooks(root));
-	const gitignore = ignoreSessionFile(root);
-	if (gitignore) results.push(gitignore);
-	return results;
-}
-/** Whether this project already carries the instruction, for `status`. */
-function isInstalled(root) {
-	for (const target of [
-		"AGENTS.md",
-		"CLAUDE.md",
-		join(".cursor", "rules", "neuvikon.mdc")
-	]) {
-		const path = join(root, target);
-		if (existsSync(path) && hasInstructions(readFileSync(path, "utf8"))) return true;
-	}
-	return false;
-}
-//#endregion
-//#region src/config.ts
-/**
-* The two deployments this CLI knows about. The browser origin is kept here
-* rather than read back from the server, because the API answers on a Convex
-* domain while approval happens on the web app's — one is not derivable from
-* the other, and guessing wrong sends people to a page that does not exist.
-*/
-const DEPLOYMENTS = {
-	production: {
-		api: "https://flexible-bird-801.eu-west-1.convex.site",
-		web: "https://www.neuvikon.space"
-	},
-	development: {
-		api: "https://calm-sturgeon-831.eu-west-1.convex.site",
-		web: "http://localhost:3000"
-	}
-};
-/**
-* `--dev` targets the development deployment; NEUVIKON_URL overrides the API
-* for a self-hosted install, in which case the web origin is unknowable and
-* falls back to the matching default.
-*/
-function resolveDeployment(flags) {
-	const base = flags.has("dev") ? DEPLOYMENTS.development : DEPLOYMENTS.production;
-	const override = flags.get("url") || process.env.NEUVIKON_URL;
-	return override ? {
-		api: override.trim().replace(/\/+$/, ""),
-		web: base.web
-	} : base;
-}
-const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? DEPLOYMENTS.production.api;
-const CONFIG_DIR = join(homedir(), ".neuvikon");
-const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-/**
-* Somewhere a browser cannot open — CI, a container, a remote box — there is no
-* way to complete a device login, so a token handed in through the environment
-* stands in for one. It wins over the config file: an explicit env var is the
-* more specific instruction.
-*/
-function credentialsFromEnv() {
-	const token = process.env.NEUVIKON_TOKEN;
-	if (!token) return null;
-	return {
-		token,
-		url: DEFAULT_SITE_URL
-	};
-}
-function readCredentials() {
-	const fromEnv = credentialsFromEnv();
-	if (fromEnv) return fromEnv;
-	let raw;
-	try {
-		raw = readFileSync(CONFIG_PATH, "utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const { token, url } = parsed;
-		if (typeof token !== "string" || !token) return null;
-		if (typeof url !== "string" || !url) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-/**
-* A token on disk is only as safe as its permissions, so directory and file are
-* locked to the owner on every write, not just on first create — an earlier
-* version may have left them readable.
-*/
-function writeCredentials(credentials) {
-	mkdirSync(CONFIG_DIR, {
-		recursive: true,
-		mode: 448
-	});
-	chmodSync(CONFIG_DIR, 448);
-	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
-	chmodSync(CONFIG_PATH, 384);
-}
-function clearCredentials() {
-	try {
-		rmSync(CONFIG_PATH);
-		return true;
-	} catch {
-		return false;
-	}
-}
-//#endregion
-//#region src/ui.ts
-/**
-* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
-* command's stdout stays a clean, pipeable value.
-*/
-const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
-function paint(code, text) {
-	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
-}
-const dim = (text) => paint("2", text);
-const bold = (text) => paint("1", text);
-const green = (text) => paint("32", text);
-const red = (text) => paint("31", text);
-const cyan = (text) => paint("36", text);
-function info(message) {
-	process.stderr.write(`${message}\n`);
-}
-function success(message) {
-	process.stderr.write(`${green("✓")} ${message}\n`);
-}
-function warn(message) {
-	process.stderr.write(`${red("!")} ${message}\n`);
-}
-/** Ends the process. Every user-facing failure funnels through here. */
-function fail(message, hint) {
-	process.stderr.write(`${red("✗")} ${message}\n`);
-	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
-	process.exit(1);
-}
-//#endregion
-//#region src/commands/init.ts
-/**
-* Separate from `login` because instructions are per-project and credentials
-* are per-machine: a second checkout needs this, not another login.
-*/
-function init() {
-	const results = installAgentInstructions(process.cwd());
-	for (const result of results) if (result.action === "unchanged") info(dim(`  ${result.path} — already up to date`));
-	else if (result.action === "skipped") warn(`${result.path} — skipped (${result.reason})`);
-	else success(`${result.path} — ${result.action}`);
-	if (!readCredentials()) warn("Not logged in yet — run `npx neuvikon login`.");
-}
-//#endregion
-//#region src/api.ts
-var ApiError = class extends Error {
-	status;
-	constructor(message, status) {
-		super(message);
-		this.status = status;
-		this.name = "ApiError";
-	}
-};
-/** A request that never reached the server: offline, DNS, TLS, timeout. */
-var NetworkError = class extends Error {
-	constructor(cause) {
-		super("Could not reach Neuvikon", { cause });
-		this.name = "NetworkError";
-	}
-};
-const TIMEOUT_MS = 15e3;
-/**
-* The one place an HTTP failure becomes a typed error. Callers decide what a
-* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
-* wants to shout about it.
-*/
-async function post(url, path, body) {
-	let response;
-	try {
-		response = await fetch(`${url}${path}`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify(body),
-			signal: AbortSignal.timeout(TIMEOUT_MS)
-		});
-	} catch (error) {
-		throw new NetworkError(error);
+	const gitignore = ignoreSessionFile(root);
+	if (gitignore) results.push(gitignore);
+	return results;
+}
+/** Whether this project already carries the instruction, for `status`. */
+function isInstalled(root) {
+	for (const target of [
+		"AGENTS.md",
+		"CLAUDE.md",
+		join(".cursor", "rules", "neuvikon.mdc")
+	]) {
+		const path = join(root, target);
+		if (existsSync(path) && hasInstructions(readFileSync(path, "utf8"))) return true;
 	}
-	const payload = await response.json().catch(() => ({}));
-	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
-	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
-	return payload;
+	return false;
 }
-function normalizeUrl(url) {
-	return url.trim().replace(/\/+$/, "");
+//#endregion
+//#region src/commands/init.ts
+/**
+* Separate from `login` because instructions are per-project and credentials
+* are per-machine: a second checkout needs this, not another login.
+*/
+function init() {
+	const results = installAgentInstructions(process.cwd());
+	for (const result of results) if (result.action === "unchanged") info(dim(`  ${result.path} — already up to date`));
+	else if (result.action === "skipped") warn(`${result.path} — skipped (${result.reason})`);
+	else success(`${result.path} — ${result.action}`);
+	if (!readCredentials()) warn("Not logged in yet — run `npx neuvikon login`.");
 }
 //#endregion
 //#region src/browser.ts
@@ -465,54 +734,6 @@ async function login(flags) {
 	}
 }
 //#endregion
-//#region src/session.ts
-/**
-* Distinguishes concurrent agents working in the *same* checkout — two Claude
-* Code panes both running `claude` in this directory get two session files,
-* because each one's process tree carries its own CLAUDE_CODE_SESSION_ID. A
-* tool that doesn't set it (or a person typing the command by hand) falls
-* back to the pre-multi-agent behavior of one session per directory.
-*/
-function instanceKey() {
-	return process.env.CLAUDE_CODE_SESSION_ID?.trim() || null;
-}
-/**
-* Scoped to the working directory rather than the machine: two checkouts driven
-* in parallel are two sessions, which is what running two agents means. Within
-* one checkout, `instanceKey()` further scopes it per agent so two panes in the
-* same directory don't stop each other's session out from under them.
-*/
-function sessionPath() {
-	const key = instanceKey();
-	const filename = key ? `.neuvikon-session.${key}` : ".neuvikon-session";
-	return join(process.cwd(), filename);
-}
-function readSession() {
-	let raw;
-	try {
-		raw = readFileSync(sessionPath(), "utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const { sessionKey, ticket } = parsed;
-		if (typeof sessionKey !== "string" || typeof ticket !== "string") return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-function writeSession(session) {
-	writeFileSync(sessionPath(), `${JSON.stringify(session, null, 2)}\n`);
-}
-function clearSession() {
-	try {
-		rmSync(sessionPath());
-	} catch {}
-}
-//#endregion
 //#region src/commands/logout.ts
 /**
 * Deleting the local file is not enough: the token stays valid until the server
@@ -549,126 +770,6 @@ async function logout() {
 	info(dim("  Could not reach Neuvikon to revoke the token — revoke it in settings if it leaked."));
 }
 //#endregion
-//#region src/ticket.ts
-/**
-* Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
-* server's — it pulls *candidates* out of arbitrary pasted prose and lets the
-* server decide which one is a real ticket in the caller's organization, so the
-* authoritative rule lives in exactly one place.
-*/
-const CANDIDATE = /\b([A-Z0-9]{2,8})-(\d{1,9})\b/g;
-/** Every distinct ref-shaped token in `text`, in the order it appears. */
-function extractTicketRefs(text) {
-	const seen = /* @__PURE__ */ new Set();
-	for (const match of text.toUpperCase().matchAll(CANDIDATE)) {
-		if (/^\d+$/.test(match[1])) continue;
-		seen.add(`${match[1]}-${match[2]}`);
-	}
-	return [...seen];
-}
-/** Reads piped input, if any. Returns "" when stdin is a terminal. */
-async function readStdin() {
-	if (process.stdin.isTTY) return "";
-	const chunks = [];
-	for await (const chunk of process.stdin) chunks.push(chunk);
-	return Buffer.concat(chunks).toString("utf8");
-}
-//#endregion
-//#region src/usage.ts
-/**
-* Sums token usage out of a JSONL agent transcript, starting from `offset`.
-*
-* Reading incrementally is what makes a per-turn hook safe to call repeatedly:
-* each call reports only what was appended since the last one. Anything that
-* doesn't parse is skipped rather than fatal — a transcript being appended to
-* while we read it will have a torn final line, and that is normal, not an
-* error worth failing a user's turn over.
-*/
-/**
-* Where the transcript currently ends, so a session that starts mid-conversation
-* can mark its starting point instead of counting what came before it.
-*/
-function transcriptSize(path) {
-	let fd;
-	try {
-		fd = openSync(path, "r");
-	} catch {
-		return null;
-	}
-	try {
-		return fstatSync(fd).size;
-	} catch {
-		return null;
-	} finally {
-		closeSync(fd);
-	}
-}
-function readUsageSince(path, offset) {
-	let fd;
-	try {
-		fd = openSync(path, "r");
-	} catch {
-		return null;
-	}
-	try {
-		const size = fstatSync(fd).size;
-		const from = offset > size ? 0 : offset;
-		if (size === from) return {
-			tokensIn: 0,
-			tokensOut: 0,
-			offset: size
-		};
-		const buffer = Buffer.alloc(size - from);
-		readSync(fd, buffer, 0, buffer.length, from);
-		const text = buffer.toString("utf8");
-		const lastNewline = text.lastIndexOf("\n");
-		if (lastNewline === -1) return {
-			tokensIn: 0,
-			tokensOut: 0,
-			offset: from
-		};
-		let tokensIn = 0;
-		let tokensOut = 0;
-		for (const line of text.slice(0, lastNewline).split("\n")) {
-			if (!line.trim()) continue;
-			let row;
-			try {
-				row = JSON.parse(line);
-			} catch {
-				continue;
-			}
-			const usage = extractUsage(row);
-			if (!usage) continue;
-			tokensIn += usage.tokensIn;
-			tokensOut += usage.tokensOut;
-		}
-		return {
-			tokensIn,
-			tokensOut,
-			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1))
-		};
-	} catch {
-		return null;
-	} finally {
-		closeSync(fd);
-	}
-}
-function toCount$1(value) {
-	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
-}
-function extractUsage(row) {
-	if (typeof row !== "object" || row === null) return null;
-	const message = row.message;
-	if (typeof message !== "object" || message === null) return null;
-	const usage = message.usage;
-	if (typeof usage !== "object" || usage === null) return null;
-	const fields = usage;
-	return {
-		tokensIn: toCount$1(fields.input_tokens) + toCount$1(fields.cache_read_input_tokens) + toCount$1(fields.cache_creation_input_tokens),
-		tokensOut: toCount$1(fields.output_tokens)
-	};
-}
-//#endregion
 //#region src/commands/report.ts
 /**
 * Agent hooks hand their context to the command on stdin as JSON. Reading the
@@ -693,54 +794,87 @@ function toCount(raw) {
 	return Number.isFinite(value) && value >= 0 ? value : void 0;
 }
 /**
-* Called from an agent hook on every turn, so it is deliberately silent and
-* never exits non-zero: a token count is not worth interrupting someone's work
-* over, and a hook that fails loudly is a hook people uninstall.
+* What the transcript has accumulated since this session's baseline.
+*
+* A session with no baseline yet establishes one here rather than counting
+* from the top: everything before the ticket started belongs to whatever the
+* agent was doing beforehand, not to this ticket.
 */
-async function report(flags) {
-	const credentials = readCredentials();
-	const session = readSession();
-	if (!credentials || !session) {
-		if (flags.has("verbose")) info(dim(credentials ? "No ticket is being tracked here." : "Not logged in."));
-		return;
-	}
-	let tokensIn = toCount(flags.get("tokens-in"));
-	let tokensOut = toCount(flags.get("tokens-out"));
-	let nextOffset;
-	const transcript = flags.get("transcript") || await transcriptFromHookPayload();
-	if (transcript) {
-		const baseline = session.transcriptOffset ?? transcriptSize(transcript);
-		if (session.transcriptOffset === void 0 && baseline !== null) writeSession({
+function pendingUsage(session, transcript) {
+	if (!transcript) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	let baseline = session.transcriptOffset;
+	if (baseline === void 0) {
+		baseline = transcriptSize(transcript) ?? void 0;
+		if (baseline !== void 0) writeSession({
 			...session,
 			transcriptOffset: baseline
 		});
-		const usage = baseline === null ? null : readUsageSince(transcript, baseline);
-		if (usage) {
-			tokensIn = (tokensIn ?? 0) + usage.tokensIn;
-			tokensOut = (tokensOut ?? 0) + usage.tokensOut;
-			nextOffset = usage.offset;
-		}
-	}
-	if (!tokensIn && !tokensOut) {
-		if (flags.has("verbose")) info(dim("No new usage to report."));
-		return;
 	}
+	if (baseline === void 0) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	const usage = readUsageSince(transcript, baseline);
+	if (!usage) return {
+		tokensIn: 0,
+		tokensOut: 0
+	};
+	return {
+		tokensIn: usage.tokensIn,
+		tokensOut: usage.tokensOut,
+		nextOffset: usage.offset
+	};
+}
+/**
+* Hands a delta to the server, advancing the local offset only once it is
+* accepted — a dropped request leaves the window to be retried by the next
+* call instead of silently losing those tokens.
+*/
+async function postUsage(credentials, session, delta) {
 	try {
 		await post(credentials.url, "/api/agent/events", {
 			token: credentials.token,
 			event: "report",
 			sessionKey: session.sessionKey,
-			tokensIn,
-			tokensOut
+			tokensIn: delta.tokensIn,
+			tokensOut: delta.tokensOut
 		});
 	} catch {
-		return;
+		return false;
 	}
-	if (nextOffset !== void 0) writeSession({
+	if (delta.nextOffset !== void 0) writeSession({
 		...session,
-		transcriptOffset: nextOffset
+		transcriptOffset: delta.nextOffset
 	});
-	if (flags.has("verbose")) info(dim(`Reported ${tokensIn ?? 0} in / ${tokensOut ?? 0} out`));
+	return true;
+}
+/**
+* Called from an agent hook on every turn, so it is deliberately silent and
+* never exits non-zero: a token count is not worth interrupting someone's work
+* over, and a hook that fails loudly is a hook people uninstall.
+*/
+async function report(flags) {
+	const credentials = readCredentials();
+	const session = readSession();
+	if (!credentials || !session) {
+		if (flags.has("verbose")) info(dim(credentials ? "No ticket is being tracked here." : "Not logged in."));
+		return;
+	}
+	const fromTranscript = pendingUsage(session, flags.get("transcript") || await transcriptFromHookPayload() || claudeTranscriptPath());
+	const delta = {
+		tokensIn: (toCount(flags.get("tokens-in")) ?? 0) + fromTranscript.tokensIn,
+		tokensOut: (toCount(flags.get("tokens-out")) ?? 0) + fromTranscript.tokensOut,
+		nextOffset: fromTranscript.nextOffset
+	};
+	if (!delta.tokensIn && !delta.tokensOut && !flags.has("heartbeat")) {
+		if (flags.has("verbose")) info(dim("No new usage to report."));
+		return;
+	}
+	await postUsage(credentials, session, delta);
+	if (flags.has("verbose")) info(dim(`Reported ${delta.tokensIn} in / ${delta.tokensOut} out`));
 }
 //#endregion
 //#region src/commands/start.ts
@@ -761,11 +895,18 @@ async function resolveRef(flags, positional) {
 	if (refs.length === 0) fail("No ticket reference found.", "Pass one with --ticket EWWQ-1, or pipe the ticket text in.");
 	return refs[0];
 }
+/**
+* An agent shelling out to `start` rarely passes `--tool`, and "other" is a
+* worse answer than the one the environment already gives us.
+*/
+function detectTool() {
+	return process.env.CLAUDE_CODE_SESSION_ID ? "claude-code" : "other";
+}
 async function start(flags, positional) {
 	const credentials = readCredentials();
 	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
 	const ref = await resolveRef(flags, positional);
-	const tool = flags.get("tool") ?? "other";
+	const tool = flags.get("tool") ?? detectTool();
 	if (!TOOLS.has(tool)) fail(`Unknown tool "${tool}".`, `Expected one of: ${[...TOOLS].join(", ")}.`);
 	const existing = readSession();
 	if (existing?.ticket === ref) {
@@ -793,10 +934,12 @@ async function start(flags, positional) {
 		event: "stop",
 		sessionKey: existing.sessionKey
 	}).catch(() => void 0);
+	const transcript = flags.get("transcript") || claudeTranscriptPath();
 	writeSession({
 		sessionKey: result.sessionKey,
 		ticket: ref,
-		startedAt: Date.now()
+		startedAt: Date.now(),
+		transcriptOffset: transcript ? transcriptSize(transcript) ?? void 0 : void 0
 	});
 	success(`Tracking work on ${bold(ref)}`);
 }
@@ -820,18 +963,23 @@ function status() {
 }
 //#endregion
 //#region src/commands/stop.ts
-async function stop() {
+async function stop(flags) {
 	const session = readSession();
 	if (!session) {
 		info(dim("No ticket is being tracked here."));
 		return;
 	}
 	const credentials = readCredentials();
-	if (credentials) await post(credentials.url, "/api/agent/events", {
-		token: credentials.token,
-		event: "stop",
-		sessionKey: session.sessionKey
-	}).catch(() => void 0);
+	if (credentials) {
+		const usage = pendingUsage(session, flags.get("transcript") || claudeTranscriptPath());
+		await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "stop",
+			sessionKey: session.sessionKey,
+			tokensIn: usage.tokensIn,
+			tokensOut: usage.tokensOut
+		}).catch(() => void 0);
+	}
 	clearSession();
 	success(`Stopped tracking ${session.ticket}`);
 }
@@ -890,8 +1038,9 @@ async function main() {
 		case "logout": return logout();
 		case "init": return init();
 		case "start": return start(flags, positional);
+		case "hook-start": return hookStart();
 		case "report": return report(flags);
-		case "stop": return stop();
+		case "stop": return stop(flags);
 		case "status": return status();
 		case void 0:
 		case "help":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuvikon",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Tell Neuvikon which ticket your coding agent is working on.",
   "keywords": [
     "neuvikon",