nilometer 0.0.0-stage → 0.1.0

package/dist/core/ingest/results.js

@@ -0,0 +1,201 @@
+/** Every line class, so the report lists zero counts too. */
+const CLASSES = [
+    "malformed",
+    "limit_hit",
+    "api_error",
+    "synthetic_other",
+    "request",
+    "retry_notice",
+    "model_fallback",
+    "ignored_type",
+];
+/** SQL selecting the seven total columns for a group; NULL cache writes count as 0. */
+const TOTALS_COLUMNS = `
+  COUNT(*) AS requests,
+  SUM(input_tokens) AS input_tokens,
+  SUM(output_tokens) AS output_tokens,
+  SUM(cache_read_tokens) AS cache_read_tokens,
+  COALESCE(SUM(cache_write_5m_tokens), 0) AS cache_write_5m_tokens,
+  COALESCE(SUM(cache_write_1h_tokens), 0) AS cache_write_1h_tokens,
+  COALESCE(SUM(cache_write_unsplit_tokens), 0) AS cache_write_unsplit_tokens`;
+/** SQL joining a derived row to its source position. `x` must alias a table with raw_line_id. */
+const POSITION_JOIN = `
+  JOIN raw_lines l ON l.id = x.raw_line_id
+  JOIN source_files f ON f.id = l.source_file_id`;
+/** SQL ordering by (file, first run, line), the canonical order. */
+const CANONICAL_ORDER = "ORDER BY f.root, f.relative_path, l.first_run_id, l.line_number";
+/**
+ * Parses a stored raw timestamp back to its JSON value.
+ * @param text - JSON text, or null when the line had no timestamp.
+ * @returns The original value; null when absent.
+ */
+export function rawTimestamp(text) {
+    return text === null ? null : JSON.parse(text);
+}
+/**
+ * Removes the totals columns' group key and returns the totals object.
+ * @param row - A row with the seven totals columns.
+ * @returns Totals in the documented field order.
+ */
+export function toTotals(row) {
+    return {
+        requests: row.requests,
+        input_tokens: row.input_tokens,
+        output_tokens: row.output_tokens,
+        cache_read_tokens: row.cache_read_tokens,
+        cache_write_5m_tokens: row.cache_write_5m_tokens,
+        cache_write_1h_tokens: row.cache_write_1h_tokens,
+        cache_write_unsplit_tokens: row.cache_write_unsplit_tokens,
+    };
+}
+/**
+ * Reads the full result for everything ingested so far.
+ * @param db - Open database with derived tables up to date.
+ * @returns Requests, totals, events, and report in the fixture shape.
+ */
+export function readResult(db) {
+    const requests = db
+        .prepare("SELECT * FROM requests_dedup ORDER BY root, relative_path, first_run_id, line_number")
+        .all().map((row) => ({
+        dedup_key: row["dedup_key"],
+        file: row["relative_path"],
+        line: row["line_number"],
+        session_id: row["session_id"],
+        message_id: row["message_id"],
+        request_id: row["request_id"],
+        model: row["model"],
+        timestamp: rawTimestamp(row.timestamp_raw),
+        is_sidechain: row.is_sidechain === 1,
+        cwd: row["cwd"],
+        input_tokens: row["input_tokens"],
+        output_tokens: row["output_tokens"],
+        cache_read_tokens: row["cache_read_tokens"],
+        cache_write_5m_tokens: row["cache_write_5m_tokens"],
+        cache_write_1h_tokens: row["cache_write_1h_tokens"],
+        cache_write_unsplit_tokens: row["cache_write_unsplit_tokens"],
+    }));
+    const totalsByModel = {};
+    for (const row of db
+        .prepare(`SELECT model, ${TOTALS_COLUMNS} FROM requests_dedup GROUP BY model ORDER BY model`)
+        .all()) {
+        totalsByModel[row.model] = toTotals(row);
+    }
+    const totalsByDay = {};
+    for (const row of db
+        .prepare(`SELECT substr(timestamp_utc, 1, 10) AS day, model, ${TOTALS_COLUMNS}
+       FROM requests_dedup WHERE timestamp_utc IS NOT NULL
+       GROUP BY day, model ORDER BY day, model`)
+        .all()) {
+        (totalsByDay[row.day] ??= {})[row.model] = toTotals(row);
+    }
+    const events = db
+        .prepare(`SELECT x.class, p.session_id, p.timestamp_raw, f.relative_path, l.line_number,
+                x.error, x.api_error_status, x.window, x.reset_text,
+                x.quota_window, x.quota_resets_at_utc,
+                x.fallback_original_model, x.fallback_model, x.fallback_request_id
+         FROM events x JOIN parsed_lines p ON p.raw_line_id = x.raw_line_id ${POSITION_JOIN}
+         ${CANONICAL_ORDER}`)
+        .all().map((row) => ({
+        class: row.class,
+        session_id: row.session_id,
+        timestamp: rawTimestamp(row.timestamp_raw),
+        file: row.relative_path,
+        line: row.line_number,
+        error: row.error,
+        api_error_status: row.api_error_status,
+        window: row.window,
+        reset_text: row.reset_text,
+        quota_window: row.quota_window,
+        quota_resets_at: row.quota_resets_at_utc,
+        // The refusal category is stored but never shown (D-080), so it isn't part of this output.
+        fallback_original_model: row.fallback_original_model,
+        fallback_model: row.fallback_model,
+        fallback_request_id: row.fallback_request_id,
+    }));
+    return {
+        requests,
+        totals_by_model: totalsByModel,
+        totals_by_day_utc: totalsByDay,
+        events,
+        report: readReport(db),
+    };
+}
+/**
+ * Reads the report section.
+ * @param db - Open database with derived tables up to date.
+ * @returns Line counts by class and every reported problem, in canonical order.
+ */
+export function readReport(db) {
+    const lines = Object.fromEntries(CLASSES.map((name) => [name, 0]));
+    for (const row of db
+        .prepare("SELECT class, COUNT(*) AS n FROM parsed_lines GROUP BY class")
+        .all()) {
+        lines[row.class] = row.n;
+    }
+    const malformed = db
+        .prepare(`SELECT f.relative_path AS file, l.line_number AS line
+       FROM parsed_lines x ${POSITION_JOIN} WHERE x.class = 'malformed' ${CANONICAL_ORDER}`)
+        .all();
+    const ignoredTypes = {};
+    for (const row of db
+        .prepare(`SELECT CASE WHEN subtype IS NULL THEN type ELSE type || '/' || subtype END AS label,
+              COUNT(*) AS n
+       FROM parsed_lines WHERE class = 'ignored_type' GROUP BY label ORDER BY label`)
+        .all()) {
+        ignoredTypes[row.label] = row.n;
+    }
+    const unknownErrors = {};
+    for (const row of db
+        .prepare(`SELECT unknown_error_key AS label, COUNT(*) AS n FROM events
+       WHERE unknown_error_key IS NOT NULL GROUP BY label ORDER BY label`)
+        .all()) {
+        unknownErrors[row.label] = row.n;
+    }
+    /**
+     * Lists one kind of line problem in canonical order.
+     * @param problem - The problem code.
+     * @returns File, line, and detail for each occurrence.
+     */
+    const problems = (problem) => db
+        .prepare(`SELECT f.relative_path AS file, l.line_number AS line, x.detail
+         FROM line_problems x ${POSITION_JOIN} WHERE x.problem = ? ${CANONICAL_ORDER}, x.id`)
+        .all(problem);
+    const counts = db
+        .prepare(`SELECT (SELECT COUNT(*) FROM requests WHERE dedup_key IS NULL) AS unkeyed,
+              (SELECT COALESCE(SUM(retry_rate_limits_present), 0) FROM events) AS retry_rate_limits`)
+        .get();
+    return {
+        lines,
+        malformed,
+        ignored_types: ignoredTypes,
+        unkeyed_requests: counts.unkeyed,
+        unknown_error_values: unknownErrors,
+        missing_fields: problems("missing_field").map(({ file, line, detail }) => ({
+            file,
+            line,
+            field: detail,
+        })),
+        unparsed_timestamps: problems("unparsed_timestamp").map(({ file, line, detail }) => ({
+            file,
+            line,
+            raw: JSON.parse(detail),
+        })),
+        non_message_iterations: problems("non_message_iteration").map(({ file, line, detail }) => ({
+            file,
+            line,
+            type: detail,
+        })),
+        retry_rate_limits_present: counts.retry_rate_limits,
+        unusable_quota_fields: problems("unusable_quota_field").map(({ file, line, detail }) => ({
+            file,
+            line,
+            field: detail,
+        })),
+        // The detail holds both windows for the database's own report; the fixture shape is the line.
+        quota_window_disagreements: problems("quota_window_disagrees").map(({ file, line }) => ({
+            file,
+            line,
+        })),
+    };
+}
+//# sourceMappingURL=results.js.map

package/dist/core/ingest/spool.js

@@ -0,0 +1,165 @@
+/**
+ * @file Decoding and validating status line spool lines (docs/development.md P4.7, D-008, D-018).
+ *
+ * The hook writes `{"captured_at_s":N,"hook_version":N,"payload_b64":"..."}` per turn without
+ * looking inside the payload. Every check happens here, and every problem is recorded rather than
+ * repaired (`statusline-collector` skill, "Ingesting the spool"): a malformed or interleaved line, a
+ * payload that isn't base64 or isn't JSON, and window values out of range. Monitor clamps
+ * percentages up to 101 down to 100; this module doesn't.
+ */
+import { blobBytes, transaction } from "../db/database.js";
+import { isNumber, isObject, objectField } from "./classify.js";
+/** Rate-limit windows the payload is documented to carry. */
+export const KNOWN_WINDOWS = ["five_hour", "seven_day", "spend_limit"];
+/** Strict base64: standard alphabet, correct padding, length a multiple of four. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/**
+ * Decodes one spool line.
+ * @param bytes - The raw spool line.
+ * @returns The status and, as far as decoding got, the capture time, hook version, and payload.
+ */
+export function decodeSpoolLine(bytes) {
+    let line;
+    try {
+        line = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        line = null;
+    }
+    // Lines from concurrent sessions can interleave (D-018); they fail here and are reported.
+    if (!isObject(line) ||
+        !isNumber(line["captured_at_s"]) ||
+        !isNumber(line["hook_version"]) ||
+        typeof line["payload_b64"] !== "string") {
+        return { status: "malformed_line", capturedAtS: null, hookVersion: null, payload: null };
+    }
+    const header = { capturedAtS: line["captured_at_s"], hookVersion: line["hook_version"] };
+    const encoded = line["payload_b64"];
+    // Buffer.from(..., "base64") silently skips invalid characters, so validate first.
+    if (!BASE64.test(encoded)) {
+        return { status: "malformed_payload_encoding", ...header, payload: null };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+    }
+    catch {
+        payload = null;
+    }
+    if (!isObject(payload)) {
+        return { status: "malformed_payload", ...header, payload: null };
+    }
+    return { status: "ok", ...header, payload };
+}
+/** Epoch seconds below this are implausible for a reset time (2001-09-09). */
+export const MIN_EPOCH_SECONDS = 1_000_000_000;
+/** Epoch seconds at or above this are implausible for a reset time (2286-11-20). */
+export const MAX_EPOCH_SECONDS = 10_000_000_000;
+/**
+ * Validates one window's values.
+ * @param window - The window name.
+ * @param value - The value under `rate_limits.<window>`.
+ * @returns The values as written with a validity label.
+ */
+export function validateWindow(window, value) {
+    const percentage = value["used_percentage"];
+    const resets = value["resets_at"];
+    const usedPercentage = isNumber(percentage) ? percentage : null;
+    const resetsAt = isNumber(resets) ? resets : null;
+    /**
+     * Builds the reading with a validity label.
+     * @param validity - The label.
+     * @returns The window reading.
+     */
+    const reading = (validity) => ({
+        window,
+        usedPercentage,
+        resetsAt,
+        validity,
+    });
+    if (!KNOWN_WINDOWS.includes(window)) {
+        return reading("unknown_window");
+    }
+    if (usedPercentage === null) {
+        return reading("invalid_percentage");
+    }
+    // Claude Code bug #52326 (reported via Monitor): the reset epoch sometimes lands in the percentage.
+    if (usedPercentage >= MIN_EPOCH_SECONDS) {
+        return reading("invalid_epoch_in_percentage");
+    }
+    // Above 100 is a real reading, not an error: Claude Code 2.1.281 reported a 5-hour window just
+    // above 100% while it was over its limit (2026-09-24, D-068), as the docs already said a spend
+    // limit can. Only a negative value is out of range; the epoch check above catches the one known
+    // corruption, and nothing is clamped.
+    if (usedPercentage < 0) {
+        return reading("invalid_percentage");
+    }
+    if (resetsAt === null || resetsAt < MIN_EPOCH_SECONDS || resetsAt >= MAX_EPOCH_SECONDS) {
+        return reading("invalid_resets_at");
+    }
+    return reading("valid");
+}
+/**
+ * Returns a value when it's a string, else null.
+ * @param value - Any parsed JSON value.
+ * @returns The string or null.
+ */
+function stringOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Derives the reading and its windows from one spool line. Pure: no database access.
+ * @param bytes - The raw spool line.
+ * @returns The reading row and one window row per object-valued key under `rate_limits`.
+ */
+export function deriveSpoolLine(bytes) {
+    const decoded = decodeSpoolLine(bytes);
+    const payload = decoded.payload ?? {};
+    const rateLimits = objectField(payload, "rate_limits");
+    const cost = objectField(payload, "cost")?.["total_cost_usd"];
+    return {
+        reading: {
+            status: decoded.status,
+            capturedAtS: decoded.capturedAtS,
+            hookVersion: decoded.hookVersion,
+            sessionId: stringOrNull(payload["session_id"]),
+            transcriptPath: stringOrNull(payload["transcript_path"]),
+            modelId: stringOrNull(objectField(payload, "model")?.["id"]),
+            ccVersion: stringOrNull(payload["version"]),
+            costTotalUsd: isNumber(cost) ? cost : null,
+            hasRateLimits: rateLimits !== null,
+        },
+        // A missing window means it reset or isn't reported: no row, and no carried-forward value.
+        windows: rateLimits === null
+            ? []
+            : Object.entries(rateLimits)
+                .filter((entry) => isObject(entry[1]))
+                .map(([window, value]) => validateWindow(window, value)),
+    };
+}
+/**
+ * Derives and stores readings for every spool raw line that has none yet.
+ * @param db - Open, migrated database.
+ * @returns Number of spool lines derived.
+ */
+export function deriveNewSpoolLines(db) {
+    const pending = db
+        .prepare(`SELECT l.id, l.bytes FROM raw_lines l
+       JOIN source_files f ON f.id = l.source_file_id AND f.kind = 'spool'
+       LEFT JOIN status_readings s ON s.raw_line_id = l.id
+       WHERE s.raw_line_id IS NULL ORDER BY l.id`)
+        .all();
+    const insertReading = db.prepare("INSERT INTO status_readings (raw_line_id, status, captured_at_s, hook_version, session_id, transcript_path, model_id, cc_version, cost_total_usd, has_rate_limits) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertWindow = db.prepare("INSERT INTO rate_limit_windows (raw_line_id, window, used_percentage, resets_at, validity) VALUES (?, ?, ?, ?, ?)");
+    transaction(db, () => {
+        for (const { id, bytes } of pending) {
+            const { reading: r, windows } = deriveSpoolLine(blobBytes(bytes));
+            insertReading.run(id, r.status, r.capturedAtS, r.hookVersion, r.sessionId, r.transcriptPath, r.modelId, r.ccVersion, r.costTotalUsd, r.hasRateLimits ? 1 : 0);
+            for (const w of windows) {
+                insertWindow.run(id, w.window, w.usedPercentage, w.resetsAt, w.validity);
+            }
+        }
+    });
+    return pending.length;
+}
+//# sourceMappingURL=spool.js.map

package/dist/core/ingest/store.js

@@ -0,0 +1,99 @@
+/**
+ * @file Writing ingest runs, file positions, and raw lines to the database (docs/development.md P4.3, D-002).
+ *
+ * Raw lines are append-only and identified by (file, SHA-256 of their bytes). Storing a line that is
+ * already there does nothing, which makes every read safe to repeat: after a rewrite, a `--full`
+ * rescan, or a crash mid-run.
+ */
+import { createHash } from "node:crypto";
+/**
+ * Hashes line bytes for identity.
+ * @param bytes - The exact line bytes.
+ * @returns Lowercase hex SHA-256.
+ */
+export function contentHash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Records the start of an ingest run.
+ * @param db - Open database.
+ * @param mode - `incremental` or `full`.
+ * @param now - Current time.
+ * @returns The new run's ID.
+ */
+export function startRun(db, mode, now) {
+    const result = db
+        .prepare("INSERT INTO ingest_runs (started_at, mode) VALUES (?, ?)")
+        .run(now.toISOString(), mode);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Records the end of an ingest run. A run left without `finished_at` crashed or is still running.
+ * @param db - Open database.
+ * @param runId - The run to close.
+ * @param now - Current time.
+ */
+export function finishRun(db, runId, now) {
+    db.prepare("UPDATE ingest_runs SET finished_at = ? WHERE id = ?").run(now.toISOString(), runId);
+}
+/**
+ * Finds a source file's row, creating it if this is the first time the file has been seen.
+ * @param db - Open database.
+ * @param file - Kind, root, path relative to the root, and current size and inode.
+ * @param runId - Current run, recorded as the first run for a new file.
+ * @returns The row ID and the previously stored state (null for a new file).
+ */
+export function findOrCreateSourceFile(db, file, runId) {
+    const existing = db
+        .prepare("SELECT id, byte_offset, line_count, size, inode FROM source_files WHERE root = ? AND relative_path = ?")
+        .get(file.root, file.relativePath);
+    if (existing !== undefined) {
+        return {
+            id: existing.id,
+            state: {
+                byteOffset: existing.byte_offset,
+                lineCount: existing.line_count,
+                size: existing.size,
+                inode: existing.inode,
+            },
+        };
+    }
+    // A new file starts at offset 0 with no lines; its real position is saved after reading.
+    const result = db
+        .prepare("INSERT INTO source_files (kind, root, relative_path, byte_offset, line_count, size, inode, first_run_id, last_run_id) VALUES (?, ?, ?, 0, 0, ?, ?, ?, ?)")
+        .run(file.kind, file.root, file.relativePath, file.stat.size, file.stat.inode, runId, runId);
+    return { id: Number(result.lastInsertRowid), state: null };
+}
+/**
+ * Saves a file's reading position after this run read it.
+ * @param db - Open database.
+ * @param fileId - Source file row ID.
+ * @param state - New offset, line count, size, and inode.
+ * @param runId - Current run.
+ */
+export function saveFileState(db, fileId, state, runId) {
+    db.prepare("UPDATE source_files SET byte_offset = ?, line_count = ?, size = ?, inode = ?, last_run_id = ? WHERE id = ?").run(state.byteOffset, state.lineCount, state.size, state.inode, runId, fileId);
+}
+/**
+ * Returns a function that stores raw lines for one file, preparing the statement once.
+ * @param db - Open database.
+ * @param fileId - Source file the lines belong to.
+ * @param runId - Current run, recorded as the first run for newly stored lines.
+ * @returns A function storing one line; it returns true if the line was new.
+ */
+export function rawLineWriter(db, fileId, runId) {
+    // OR IGNORE leans on UNIQUE (source_file_id, content_hash): a line seen before keeps its first
+    // run and line number, which is exactly the identity rule in fixtures/README.md.
+    const insert = db.prepare("INSERT OR IGNORE INTO raw_lines (source_file_id, line_number, byte_offset, content_hash, bytes, first_run_id) VALUES (?, ?, ?, ?, ?, ?)");
+    return (line) => insert.run(fileId, line.lineNumber, line.offset, contentHash(line.bytes), line.bytes, runId)
+        .changes === 1;
+}
+/**
+ * Records a run-level or file-level problem in the ingest report.
+ * @param db - Open database.
+ * @param entry - Run, optional file, problem code, and optional detail.
+ */
+export function recordProblem(db, entry) {
+    db.prepare("INSERT INTO ingest_report (run_id, source_file_id, problem, detail) VALUES (?, ?, ?, ?)").run(entry.runId, entry.fileId, entry.problem, entry.detail);
+}
+//# sourceMappingURL=store.js.map

package/dist/core/install/install.js

@@ -0,0 +1,185 @@
+/**
+ * @file The `init` and `uninstall` operations: register the status line hook, and reverse it.
+ *
+ * Implements README § How it works ("Chaining, not clobbering"), docs/development.md P1.3, and the
+ * `statusline-collector` skill's `init` steps: back up first, wrap an existing command, write
+ * atomically, be idempotent, and make `uninstall` restore the original exactly.
+ *
+ * Both operations return a plain outcome object. Wording for the user belongs to the CLI layer,
+ * so outcomes can be tested without asserting on prose.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { backupSettings, locateSettings, readSettings, serializeSettings, writeFileAtomic, } from "../settings/settings-file.js";
+import { buildHookCommand, dataDirFromHookCommand, isCommandEntry, planInstall, planUninstall, } from "../settings/statusline.js";
+import { HOOK_RELATIVE_PATH, INSTALLED_HOOK_FILE, resolveDataDir } from "./locations.js";
+import { ensurePrivateDir, installHook, removePath } from "./private-files.js";
+import { readInstallRecord, removeInstallRecord, writeInstallRecord } from "./record.js";
+/** Layout used when `init` creates a settings file from scratch: what Claude Code writes. */
+export const DEFAULT_FORMAT = { indent: 2, trailingNewline: true };
+/**
+ * Resolves the settings path, data directory, and hook command for a run.
+ * @param options - Install options.
+ * @returns The three resolved locations.
+ */
+export function resolveTargets(options) {
+    const settingsPath = locateSettings({
+        home: options.home,
+        override: options.settingsOverride,
+        claudeConfigDir: options.env.CLAUDE_CONFIG_DIR,
+    });
+    const dataDir = resolveDataDir({
+        home: options.home,
+        env: options.env,
+        override: options.dataDirOverride,
+    });
+    // The command names the copy in the data directory, which nothing moves, not the one in the
+    // package, whose path changes with the Node version or the checkout's location (D-056).
+    const hookPath = join(dataDir, INSTALLED_HOOK_FILE);
+    const hookCommand = buildHookCommand(hookPath, dataDir);
+    return { settingsPath, dataDir, hookCommand, hookPath };
+}
+/**
+ * Registers the status line hook in Claude Code's settings. Safe to run repeatedly.
+ * @param options - Locations, environment, and clock.
+ * @returns What happened, with the paths involved.
+ * @throws {import("../settings/settings-file.js").SettingsError} If the settings file can't be
+ *   parsed; nothing is changed.
+ * @throws {import("./record.js").InstallRecordError} If an existing install record is corrupt.
+ */
+export function runInit(options) {
+    const { settingsPath, dataDir, hookCommand, hookPath } = resolveTargets(options);
+    const read = readSettings(settingsPath);
+    const settings = read.kind === "ok" ? read.settings : null;
+    const plan = planInstall(settings, hookCommand);
+    // Before the settings can name it, and on every run: a package whose hook changed needs the copy
+    // refreshed, even when the command itself is already correct (D-056).
+    const platform = options.platform ?? process.platform;
+    let hookRefreshed = false;
+    if (plan.action !== "refuse") {
+        ensurePrivateDir(dataDir, platform);
+        hookRefreshed = installHook(join(options.packageRoot, HOOK_RELATIVE_PATH), hookPath, platform);
+    }
+    const base = { settingsPath, dataDir, hookRefreshed };
+    switch (plan.action) {
+        case "none":
+            return { ...base, action: "already-installed", backupPath: null, wrappedCommand: wrapped() };
+        case "refuse":
+            return { ...base, action: "refused-unsupported", backupPath: null, wrappedCommand: null };
+        case "update-command": {
+            // The record lives in the data directory. If this data directory has none, the hook was
+            // installed with another one, and moving on would lose the user's original command.
+            if (readInstallRecord(dataDir) === null) {
+                return { ...base, action: "refused-other-install", backupPath: null, wrappedCommand: null };
+            }
+            const backupPath = backupSettings(settingsPath, options.now);
+            writeSettings(settingsPath, plan.settings, read.kind === "ok" ? read.format : DEFAULT_FORMAT);
+            return { ...base, action: "updated", backupPath, wrappedCommand: wrapped() };
+        }
+        case "install": {
+            const backupPath = backupSettings(settingsPath, options.now);
+            // Record first: once settings point at the hook, its next run must find the original command.
+            writeInstallRecord(dataDir, {
+                version: 1,
+                settingsPath,
+                settingsExisted: read.kind === "ok",
+                backupPath,
+                original: plan.original,
+                installedAt: options.now.toISOString(),
+            });
+            writeSettings(settingsPath, plan.settings, read.kind === "ok" ? read.format : DEFAULT_FORMAT);
+            return { ...base, action: "installed", backupPath, wrappedCommand: wrapped() };
+        }
+    }
+    /**
+     * Reads which original command the hook wraps, from the record in this data directory.
+     * @returns The wrapped command, or null if there is none.
+     */
+    function wrapped() {
+        return readInstallRecord(dataDir)?.original?.command ?? null;
+    }
+}
+/**
+ * Serializes settings and writes them atomically, creating the directory if needed.
+ * @param path - Settings file path.
+ * @param settings - Settings to write.
+ * @param format - Layout to use.
+ */
+function writeSettings(path, settings, format) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileAtomic(path, serializeSettings(settings, format));
+}
+/**
+ * Removes the hook from Claude Code's settings and restores what `init` replaced.
+ * Collected data (spool, error log) is kept.
+ * @param options - Locations, environment, and clock.
+ * @returns What happened, with the paths involved.
+ * @throws {import("../settings/settings-file.js").SettingsError} If the settings file can't be
+ *   parsed; nothing is changed.
+ * @throws {import("./record.js").InstallRecordError} If the install record is corrupt.
+ */
+export function runUninstall(options) {
+    const targets = resolveTargets(options);
+    let dataDir = targets.dataDir;
+    let record = readInstallRecord(dataDir);
+    // The record knows which file was changed, even if flags or environment differ today.
+    const settingsPath = record?.settingsPath ?? targets.settingsPath;
+    const read = readSettings(settingsPath);
+    if (record === null && read.kind === "ok") {
+        // `init --data-dir X` followed by a plain `uninstall` looks for the record in the default
+        // directory and doesn't find it. Without the record, the plan below would delete the user's
+        // own status line instead of restoring it, so recover the directory from the command that's
+        // about to be removed — the one other place `init` wrote that path down (D-050).
+        const entry = read.settings["statusLine"];
+        const installedAt = isCommandEntry(entry) ? dataDirFromHookCommand(entry.command) : null;
+        const recovered = installedAt === null ? null : readInstallRecord(installedAt);
+        if (installedAt !== null && recovered !== null) {
+            record = recovered;
+            dataDir = installedAt;
+        }
+    }
+    const settings = read.kind === "ok" ? read.settings : null;
+    const plan = planUninstall(settings, record?.original ?? null);
+    const base = {
+        settingsPath,
+        dataDir,
+        recordMissing: record === null,
+        restoredCommand: record?.original?.command ?? null,
+        notRemoved: [],
+    };
+    if (plan.action === "none" || read.kind !== "ok") {
+        const action = plan.action === "none" ? plan.reason : "not-installed";
+        return { ...base, action, backupPath: null, exactBytes: false };
+    }
+    const backupPath = backupSettings(settingsPath, options.now);
+    // init created this file and nothing else was added since: the faithful undo is no file at all.
+    if (record !== null && !record.settingsExisted && Object.keys(plan.settings).length === 0) {
+        // Verified, not assumed: a removal that silently does nothing would leave the hook registered
+        // while `uninstall` reported success, and it would keep recording (D-061).
+        const gone = removePath(settingsPath);
+        removeInstallRecord(dataDir);
+        return {
+            ...base,
+            action: "removed-settings-file",
+            backupPath,
+            exactBytes: true,
+            notRemoved: gone ? [] : [settingsPath],
+        };
+    }
+    // If the result equals the pre-install file, write its exact bytes: a re-serialization could
+    // differ in whitespace the JSON parser discarded.
+    const original = record?.backupPath ?? null;
+    if (original !== null && existsSync(original)) {
+        const originalRaw = readFileSync(original, "utf8");
+        if (isDeepStrictEqual(JSON.parse(originalRaw), plan.settings)) {
+            writeFileAtomic(settingsPath, originalRaw);
+            removeInstallRecord(dataDir);
+            return { ...base, action: "restored", backupPath, exactBytes: true };
+        }
+    }
+    writeFileAtomic(settingsPath, serializeSettings(plan.settings, read.format));
+    removeInstallRecord(dataDir);
+    return { ...base, action: "restored", backupPath, exactBytes: false };
+}
+//# sourceMappingURL=install.js.map