@oortmem/claude-code 0.0.0-stage → 0.1.0

package/dist/import.d.ts

@@ -0,0 +1,71 @@
+import { type ObserveResult } from '@oortmem/core';
+import type { HookDeps } from './deps.js';
+export interface ImportOptions {
+    /** Claude Code's projects directory, usually `~/.claude/projects`. */
+    projectsDir: string;
+    /** Only transcripts modified at or after this time. */
+    since?: Date;
+    /** Count and estimate only; write nothing. */
+    estimateOnly: boolean;
+    /** Share of observations expected to reach the writer (after the gate). Default 0.25. */
+    writerFraction?: number;
+    /**
+     * Import sessions whose project cannot be resolved into global scope.
+     * Default false: they are skipped, since a deleted private project's
+     * memories would otherwise surface in every project.
+     */
+    includeUnresolved?: boolean;
+}
+export interface ImportResult {
+    /** Sessions with at least one observation to import. */
+    sessions: number;
+    observations: number;
+    /** Writer tokens: Σ(chars / 4 + 400) × writerFraction. No price table in Phase 1. */
+    estimatedTokens: number;
+    /**
+     * Sessions with observations that were left out because their project could
+     * not be resolved (recorded `cwd` gone, or not in a git repository).
+     */
+    skippedUnresolved: number;
+    /** Transcripts that vanished or could not be read during the walk. */
+    skippedUnreadable: number;
+    results?: ObserveResult[];
+    /** Per-outcome counts, plus `failed` for observations whose observe threw. */
+    outcomes?: Record<string, number>;
+    /**
+     * Sessions that stopped at a failed observation: its cursor stays before it,
+     * and the session's later observations were not attempted (the Stop hook or
+     * a later import picks them up).
+     */
+    failedSessions?: Record<string, {
+        failed: number;
+        notAttempted: number;
+        reason: string;
+    }>;
+    /**
+     * Observations skipped because the failure is permanent for that input (the
+     * writer's output never fits the schema, or the model refused or truncated),
+     * keyed by `failureReason`. Their sessions continue and the cursor passes them.
+     */
+    unwritable?: Record<string, number>;
+}
+/**
+ * Why an observation failed, from the error's class and the typed fields our
+ * adapters set (`kind`, `status`, `fields`). Never the message: a provider's
+ * message may echo the observation it was given.
+ */
+export declare function failureReason(e: unknown): string;
+/**
+ * Imports existing Claude Code transcripts. Every transcript is parsed,
+ * paired and scrubbed; turns already behind a session's cursor (observed by
+ * the Stop hook or an earlier import) are skipped. With `estimateOnly` it
+ * only reports the estimate. Otherwise it observes oldest first across all
+ * sessions, advances each session's cursor so the Stop hook never re-observes
+ * imported turns, and appends one eval row per added memory to
+ * `$OORT_HOME/eval/import-<YYYY-MM-DD>.jsonl`.
+ *
+ * The scope of each transcript is derived from the `cwd` its rows recorded.
+ * A session whose project cannot be resolved is skipped (and counted in
+ * `skippedUnresolved`) unless `includeUnresolved` imports it as global.
+ */
+export declare function importTranscripts(opts: ImportOptions, deps: HookDeps): Promise<ImportResult>;

package/dist/import.js

@@ -0,0 +1,244 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { appendPrivateFile, localScope, observe, resolveProjectId, scrubObservation, } from '@oortmem/core';
+import { cursorKey, grantFor } from './hooks.js';
+import { parseTranscriptDetailed, selectAfterCursor } from './transcript.js';
+/** A failure a re-run would repeat for the same observation: skip it rather than stop the session. */
+function isPermanent(e) {
+    if (!(e instanceof Error))
+        return false;
+    if (e.name === 'WriterOutputError')
+        return true;
+    return e.name === 'WriterError' && e.kind === 'bad-response';
+}
+/**
+ * Why an observation failed, from the error's class and the typed fields our
+ * adapters set (`kind`, `status`, `fields`). Never the message: a provider's
+ * message may echo the observation it was given.
+ */
+export function failureReason(e) {
+    if (!(e instanceof Error))
+        return 'non-error thrown';
+    const { kind, status, fields } = e;
+    const parts = [];
+    if (typeof kind === 'string')
+        parts.push(kind);
+    if (typeof status === 'number')
+        parts.push(`HTTP ${status}`);
+    if (Array.isArray(fields) && fields.every((f) => typeof f === 'string'))
+        parts.push(`fields: ${fields.join(', ')}`);
+    return parts.length === 0 ? e.name : `${e.name} (${parts.join(', ')})`;
+}
+/** Fixed per-call writer overhead (system prompt, schema), in tokens. */
+const WRITER_OVERHEAD_TOKENS = 400;
+const DEFAULT_WRITER_FRACTION = 0.25;
+/**
+ * Session transcripts: `<projectsDir>/<project>/<session>.jsonl`. Subagent
+ * transcripts (one level deeper) and orphaned copies Claude Code set aside
+ * (`<session>.orphaned-…jsonl`) are not sessions of their own.
+ */
+function transcripts(projectsDir, since, skip) {
+    const out = [];
+    let projects;
+    try {
+        projects = fs.readdirSync(projectsDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const p of projects) {
+        if (!p.isDirectory())
+            continue;
+        const dir = path.join(projectsDir, p.name);
+        let files;
+        try {
+            files = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!f.isFile() || !f.name.endsWith('.jsonl') || f.name.includes('.orphaned-'))
+                continue;
+            const file = path.join(dir, f.name);
+            if (since !== undefined) {
+                let mtime;
+                try {
+                    mtime = fs.statSync(file).mtimeMs;
+                }
+                catch {
+                    skip(); // Vanished mid-walk.
+                    continue;
+                }
+                if (mtime < since.getTime())
+                    continue;
+            }
+            out.push(file);
+        }
+    }
+    return out.sort();
+}
+/**
+ * The session's project id, or undefined when it cannot be resolved. A missing
+ * directory is unresolved even inside a git repo: walking up from it would
+ * attribute the session to the enclosing repository instead.
+ */
+function resolveProject(cwd, home) {
+    if (cwd === undefined || !fs.existsSync(cwd))
+        return undefined;
+    return resolveProjectId(cwd, home);
+}
+function chars(o) {
+    return (o.userText.length + o.assistantText.length + o.toolSummaries.reduce((n, s) => n + s.length, 0));
+}
+/**
+ * Imports existing Claude Code transcripts. Every transcript is parsed,
+ * paired and scrubbed; turns already behind a session's cursor (observed by
+ * the Stop hook or an earlier import) are skipped. With `estimateOnly` it
+ * only reports the estimate. Otherwise it observes oldest first across all
+ * sessions, advances each session's cursor so the Stop hook never re-observes
+ * imported turns, and appends one eval row per added memory to
+ * `$OORT_HOME/eval/import-<YYYY-MM-DD>.jsonl`.
+ *
+ * The scope of each transcript is derived from the `cwd` its rows recorded.
+ * A session whose project cannot be resolved is skipped (and counted in
+ * `skippedUnresolved`) unless `includeUnresolved` imports it as global.
+ */
+export async function importTranscripts(opts, deps) {
+    const items = [];
+    let weighted = 0;
+    const sessions = new Set();
+    let skippedUnresolved = 0;
+    let skippedUnreadable = 0;
+    const skip = () => {
+        skippedUnreadable++;
+    };
+    for (const file of transcripts(opts.projectsDir, opts.since, skip)) {
+        const session = path.basename(file, '.jsonl');
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            skip();
+            continue;
+        }
+        const detailed = parseTranscriptDetailed(text);
+        const cwd = detailed.find((d) => d.turn.cwd.length > 0)?.turn.cwd;
+        const projectId = resolveProject(cwd, deps.config.home);
+        const scope = localScope(projectId);
+        const { fresh } = selectAfterCursor(detailed, await deps.store.getCursor(grantFor(scope), cursorKey(session)));
+        const mine = [];
+        for (const raw of fresh) {
+            const s = scrubObservation(raw);
+            if (s.dropped)
+                continue;
+            mine.push({ session, pos: mine.length, obs: s.obs, scope });
+        }
+        if (mine.length === 0)
+            continue;
+        if (projectId === undefined && opts.includeUnresolved !== true) {
+            skippedUnresolved++;
+            continue;
+        }
+        for (const item of mine)
+            weighted += chars(item.obs) / 4 + WRITER_OVERHEAD_TOKENS;
+        items.push(...mine);
+        sessions.add(session);
+    }
+    const fraction = opts.writerFraction ?? DEFAULT_WRITER_FRACTION;
+    const summary = {
+        sessions: sessions.size,
+        observations: items.length,
+        estimatedTokens: Math.ceil(weighted * fraction),
+        skippedUnresolved,
+        skippedUnreadable,
+    };
+    if (opts.estimateOnly)
+        return summary;
+    const { embed, decide, write } = deps;
+    if (embed === undefined || decide === undefined || write === undefined) {
+        throw new Error('import needs the embed, decide and write adapters');
+    }
+    // Oldest first across sessions, but never out of order within one: each item
+    // sorts at its session's running maximum timestamp (the sort is stable).
+    const runningMax = new Map();
+    const key = new Map();
+    for (const item of items) {
+        const t = Date.parse(item.obs.at);
+        const k = Math.max(runningMax.get(item.session) ?? 0, Number.isNaN(t) ? 0 : t);
+        runningMax.set(item.session, k);
+        key.set(item, k);
+    }
+    items.sort((a, b) => (key.get(a) ?? 0) - (key.get(b) ?? 0));
+    const day = (deps.now?.() ?? new Date()).toISOString().slice(0, 10);
+    const evalFile = path.join(deps.config.home, 'eval', `import-${day}.jsonl`);
+    const results = [];
+    const outcomes = {};
+    const failedSessions = {};
+    const unwritable = {};
+    const done = new Map();
+    // Only forward within a session, and only past observations that are finished with.
+    const advance = async (item) => {
+        const prev = done.get(item.session) ?? -1;
+        if (item.pos > prev && item.obs.turnRef !== undefined) {
+            await deps.store.setCursor(grantFor(item.scope), cursorKey(item.session), item.obs.turnRef);
+            done.set(item.session, item.pos);
+        }
+    };
+    for (const item of items) {
+        const stopped = failedSessions[item.session];
+        if (stopped !== undefined) {
+            // The session stopped at an earlier failure; its cursor must not pass it.
+            stopped.notAttempted++;
+            continue;
+        }
+        let r;
+        try {
+            r = await observe(item.obs, item.scope, {
+                store: deps.store,
+                embed,
+                decide,
+                write,
+                config: deps.config,
+                now: deps.now?.() ?? new Date(),
+                harness: 'claude-code',
+            });
+        }
+        catch (e) {
+            if (isPermanent(e)) {
+                outcomes['unwritable'] = (outcomes['unwritable'] ?? 0) + 1;
+                const why = failureReason(e);
+                unwritable[why] = (unwritable[why] ?? 0) + 1;
+                await advance(item);
+                continue;
+            }
+            outcomes['failed'] = (outcomes['failed'] ?? 0) + 1;
+            failedSessions[item.session] = { failed: 1, notAttempted: 0, reason: failureReason(e) };
+            continue;
+        }
+        results.push(r);
+        // A turn can become several memories (CON-56): count and log each one.
+        for (const m of r.memories) {
+            outcomes[m.outcome] = (outcomes[m.outcome] ?? 0) + 1;
+            if (m.outcome !== 'added' || m.memoryId === undefined)
+                continue;
+            const row = {
+                memoryId: m.memoryId,
+                question: '',
+                expectedMemoryIds: [m.memoryId],
+                asOf: item.obs.at,
+            };
+            appendPrivateFile(evalFile, `${JSON.stringify(row)}\n`);
+        }
+        await advance(item);
+    }
+    return {
+        ...summary,
+        results,
+        outcomes,
+        ...(Object.keys(failedSessions).length > 0 && { failedSessions }),
+        ...(Object.keys(unwritable).length > 0 && { unwritable }),
+    };
+}
+//# sourceMappingURL=import.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { HookDeps } from './deps.js';
+export { createHookLogger, HOOK_LOG_MAX_BYTES, type HookLogEntry, type HookLogger } from './log.js';
+export { HARNESS_TAGS, OORT_MEMORY_TAG, parseTranscript, parseTranscriptDetailed, selectAfterCursor, turnsToObservations, type DetailedTurn, type Turn, } from './transcript.js';
+export { cursorKey, filterFor, grantFor, handleSessionStart, handleStop, handleUserPromptSubmit, RECALL_TIMEOUT_MS, runHook, STOP_MAX_OBSERVATIONS, type HookEvent, type HookOutput, } from './hooks.js';
+export { drainQueue, enqueueObservations, queueDir, type DrainResult, type QueueLine, } from './queue.js';
+export { HOOK_EVENTS, HOOK_TIMEOUTS, hookStatus, installHooks, uninstallHooks, type HookEventStatus, } from './install.js';
+export { importTranscripts, type ImportOptions, type ImportResult } from './import.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createHookLogger, HOOK_LOG_MAX_BYTES } from './log.js';
+export { HARNESS_TAGS, OORT_MEMORY_TAG, parseTranscript, parseTranscriptDetailed, selectAfterCursor, turnsToObservations, } from './transcript.js';
+export { cursorKey, filterFor, grantFor, handleSessionStart, handleStop, handleUserPromptSubmit, RECALL_TIMEOUT_MS, runHook, STOP_MAX_OBSERVATIONS, } from './hooks.js';
+export { drainQueue, enqueueObservations, queueDir, } from './queue.js';
+export { HOOK_EVENTS, HOOK_TIMEOUTS, hookStatus, installHooks, uninstallHooks, } from './install.js';
+export { importTranscripts } from './import.js';
+//# sourceMappingURL=index.js.map

package/dist/install.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Installs Oort's hooks into a Claude Code settings file (usually
+ * `~/.claude/settings.json`). Schema, per https://code.claude.com/docs/en/hooks:
+ *
+ *     { "hooks": { "<Event>": [ { "matcher"?: string, "hooks": [ { "type": "command", "command": string, "timeout"?: seconds } ] } ] } }
+ *
+ * UserPromptSubmit and Stop take no matcher (one would be ignored); SessionStart's
+ * matcher filters the session source, and is omitted so it fires on every source.
+ */
+export declare const HOOK_EVENTS: readonly ['UserPromptSubmit', 'Stop', 'SessionStart'];
+export type InstalledEvent = (typeof HOOK_EVENTS)[number];
+/** Seconds. Claude Code's defaults are 30 (UserPromptSubmit) and 600 (others). */
+export declare const HOOK_TIMEOUTS: Record<InstalledEvent, number>;
+/** `cmd` as one shell word: as is when it is plainly safe, otherwise single-quoted. */
+export declare function shellQuote(cmd: string): string;
+/**
+ * Merges Oort's three hook entries (`<cmd> hook <Event>`) into the settings
+ * file, creating it if missing. Idempotent; replaces a stale Oort entry in
+ * place; never removes or reorders anyone else's hooks. Writes atomically and
+ * keeps a one-time backup of the original at `<settingsPath>.oort-backup`.
+ * Refuses (file untouched) settings that are not JSON, or whose `hooks` or
+ * hook event values have the wrong shape.
+ */
+export declare function installHooks(settingsPath: string, cmd: string): {
+    changed: boolean;
+};
+/**
+ * Removes only Oort's entries. A group left empty by the removal goes too; an
+ * event array or `hooks` object left empty goes only if Oort created it (it is
+ * absent from the pre-install backup). A missing file is left missing.
+ */
+export declare function uninstallHooks(settingsPath: string, cmd: string): {
+    changed: boolean;
+};
+export interface HookEventStatus {
+    event: InstalledEvent;
+    /**
+     * `current`: `<cmd> hook <event>` for this bin. `stale`: Oort's entry from
+     * another install path. `found`: Oort's entry, with no bin to compare
+     * against. `missing`: no Oort entry (a wrapper such as `cd x && oort hook
+     * Stop` is the user's own and does not count).
+     */
+    state: 'current' | 'stale' | 'found' | 'missing';
+    /** The bin the entry runs, unquoted, for `stale` and `found`. */
+    command?: string;
+}
+/**
+ * Read-only: which of Oort's hooks the settings file holds, for `oort
+ * doctor`. Throws, like `installHooks`, on settings that are not JSON or have
+ * the wrong shape.
+ */
+export declare function hookStatus(settingsPath: string, cmd?: string): {
+    exists: boolean;
+    events: HookEventStatus[];
+};

package/dist/install.js

@@ -0,0 +1,257 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomic } from './fsutil.js';
+/**
+ * Installs Oort's hooks into a Claude Code settings file (usually
+ * `~/.claude/settings.json`). Schema, per https://code.claude.com/docs/en/hooks:
+ *
+ *     { "hooks": { "<Event>": [ { "matcher"?: string, "hooks": [ { "type": "command", "command": string, "timeout"?: seconds } ] } ] } }
+ *
+ * UserPromptSubmit and Stop take no matcher (one would be ignored); SessionStart's
+ * matcher filters the session source, and is omitted so it fires on every source.
+ */
+export const HOOK_EVENTS = ['UserPromptSubmit', 'Stop', 'SessionStart'];
+/** Seconds. Claude Code's defaults are 30 (UserPromptSubmit) and 600 (others). */
+export const HOOK_TIMEOUTS = {
+    UserPromptSubmit: 10,
+    Stop: 5,
+    SessionStart: 10,
+};
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** `cmd` as one shell word: as is when it is plainly safe, otherwise single-quoted. */
+export function shellQuote(cmd) {
+    return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(cmd) ? cmd : `'${cmd.replaceAll("'", `'\\''`)}'`;
+}
+const commandFor = (cmd, event) => `${shellQuote(cmd)} hook ${event}`;
+/**
+ * Ours, under `event`: exactly `<cmd> hook <event>`, or exactly `oort hook
+ * <event>` from any install path (a stale entry from a moved binary). Anything
+ * with more around it (`cd x && oort hook Stop`, `oort hook Stop --flag`) is
+ * the user's own wrapper and is never touched.
+ */
+function isOurs(h, cmd, event) {
+    if (!isObject(h) || h['type'] !== 'command' || typeof h['command'] !== 'string')
+        return false;
+    const c = h['command'];
+    return (c === commandFor(cmd, event) ||
+        new RegExp(`^(?:\\S*/)?oort hook ${event}$`).test(c) ||
+        // A package's bin, as `oort install` writes it: `<prefix>/oort(mem)/dist/main.js`.
+        new RegExp(`^(?:'[^']*/oort(?:mem)?/dist/main\\.js'|[^'\\s]*/oort(?:mem)?/dist/main\\.js) hook ${event}$`).test(c));
+}
+function desired(cmd, event) {
+    return { type: 'command', command: commandFor(cmd, event), timeout: HOOK_TIMEOUTS[event] };
+}
+function parseSettings(text, file) {
+    let parsed;
+    try {
+        parsed = text.trim().length === 0 ? {} : JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`Claude Code settings ${file} is not valid JSON: ${e.message}`);
+    }
+    if (!isObject(parsed))
+        throw new Error(`Claude Code settings ${file} is not a JSON object`);
+    const hooks = parsed['hooks'];
+    if (hooks === undefined)
+        return parsed;
+    if (!isObject(hooks))
+        throw new Error(`Claude Code settings ${file}: "hooks" is not an object`);
+    for (const event of HOOK_EVENTS) {
+        if (hooks[event] !== undefined && !Array.isArray(hooks[event])) {
+            throw new Error(`Claude Code settings ${file}: "hooks.${event}" is not an array`);
+        }
+    }
+    return parsed;
+}
+function readSettings(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { settings: {}, existed: false, mode: 0o600 };
+        }
+        throw e;
+    }
+    return {
+        settings: parseSettings(text, file),
+        existed: true,
+        mode: fs.statSync(file).mode & 0o777,
+    };
+}
+const backupPath = (file) => `${file}.oort-backup`;
+function writeSettings(file, settings, existed, mode) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const backup = backupPath(file);
+    if (existed && !fs.existsSync(backup)) {
+        fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+        if (process.platform !== 'win32')
+            fs.chmodSync(backup, 0o600);
+    }
+    // A settings file symlinked from a dotfiles repo stays a symlink: write its target.
+    const target = existed ? fs.realpathSync(file) : file;
+    writeFileAtomic(target, `${JSON.stringify(settings, null, 2)}\n`, mode);
+}
+/**
+ * Containers (`hooks`, `hooks.<Event>`) that existed before Oort first
+ * installed, read from the one-time backup. No backup means the file did not
+ * exist then, so every container is ours. An unreadable backup keeps them all.
+ */
+function preexisting(file) {
+    let text;
+    try {
+        text = fs.readFileSync(backupPath(file), 'utf8');
+    }
+    catch {
+        return { hooks: false, events: new Set() };
+    }
+    try {
+        const before = parseSettings(text, backupPath(file));
+        const hooks = before['hooks'];
+        return {
+            hooks: isObject(hooks),
+            events: new Set(isObject(hooks) ? Object.keys(hooks) : []),
+        };
+    }
+    catch {
+        return { hooks: true, events: new Set(HOOK_EVENTS) };
+    }
+}
+/**
+ * Merges Oort's three hook entries (`<cmd> hook <Event>`) into the settings
+ * file, creating it if missing. Idempotent; replaces a stale Oort entry in
+ * place; never removes or reorders anyone else's hooks. Writes atomically and
+ * keeps a one-time backup of the original at `<settingsPath>.oort-backup`.
+ * Refuses (file untouched) settings that are not JSON, or whose `hooks` or
+ * hook event values have the wrong shape.
+ */
+export function installHooks(settingsPath, cmd) {
+    const { settings, existed, mode } = readSettings(settingsPath);
+    const before = JSON.stringify(settings);
+    const hooks = isObject(settings['hooks']) ? { ...settings['hooks'] } : {};
+    for (const event of HOOK_EVENTS) {
+        const want = desired(cmd, event);
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        // Replace the first of ours in place, drop any other copies.
+        let placed = false;
+        const next = [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks'])) {
+                next.push(g);
+                continue;
+            }
+            const hs = [];
+            let touched = false;
+            for (const h of g['hooks']) {
+                if (!isOurs(h, cmd, event)) {
+                    hs.push(h);
+                }
+                else if (!placed) {
+                    hs.push(want);
+                    placed = true;
+                    touched = true;
+                }
+                else {
+                    touched = true;
+                }
+            }
+            if (!touched)
+                next.push(g);
+            else if (hs.length > 0)
+                next.push({ ...g, hooks: hs });
+        }
+        if (!placed)
+            next.push({ hooks: [want] });
+        hooks[event] = next;
+    }
+    const updated = { ...settings, hooks };
+    if (JSON.stringify(updated) === before)
+        return { changed: false };
+    writeSettings(settingsPath, updated, existed, mode);
+    return { changed: true };
+}
+/**
+ * Removes only Oort's entries. A group left empty by the removal goes too; an
+ * event array or `hooks` object left empty goes only if Oort created it (it is
+ * absent from the pre-install backup). A missing file is left missing.
+ */
+export function uninstallHooks(settingsPath, cmd) {
+    if (!fs.existsSync(settingsPath))
+        return { changed: false };
+    const { settings, existed, mode } = readSettings(settingsPath);
+    if (!isObject(settings['hooks']))
+        return { changed: false };
+    const hooks = { ...settings['hooks'] };
+    const kept = preexisting(settingsPath);
+    let removed = false;
+    for (const event of HOOK_EVENTS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const next = [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks'])) {
+                next.push(g);
+                continue;
+            }
+            const hs = g['hooks'];
+            const left = hs.filter((h) => !isOurs(h, cmd, event));
+            if (left.length === hs.length)
+                next.push(g);
+            else if (left.length > 0)
+                next.push({ ...g, hooks: left });
+        }
+        if (next.length === groups.length && next.every((g, i) => g === groups[i]))
+            continue;
+        removed = true;
+        if (next.length === 0 && !kept.events.has(event))
+            delete hooks[event];
+        else
+            hooks[event] = next;
+    }
+    if (!removed)
+        return { changed: false };
+    const updated = { ...settings, hooks };
+    if (Object.keys(hooks).length === 0 && !kept.hooks)
+        delete updated['hooks'];
+    writeSettings(settingsPath, updated, existed, mode);
+    return { changed: true };
+}
+/** The bin part of `<bin> hook <event>`, with shellQuote's quoting undone. */
+function binOf(command, event) {
+    const bin = command.slice(0, -` hook ${event}`.length);
+    return bin.startsWith("'") && bin.endsWith("'") ? bin.slice(1, -1).replaceAll(`'\\''`, "'") : bin;
+}
+/**
+ * Read-only: which of Oort's hooks the settings file holds, for `oort
+ * doctor`. Throws, like `installHooks`, on settings that are not JSON or have
+ * the wrong shape.
+ */
+export function hookStatus(settingsPath, cmd) {
+    const { settings, existed } = readSettings(settingsPath);
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const events = HOOK_EVENTS.map((event) => {
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks']))
+                continue;
+            for (const h of g['hooks']) {
+                if (!isOurs(h, cmd ?? 'oort', event))
+                    continue;
+                const command = h.command;
+                if (cmd !== undefined && command === commandFor(cmd, event)) {
+                    return { event, state: 'current' };
+                }
+                return {
+                    event,
+                    state: cmd === undefined ? 'found' : 'stale',
+                    command: binOf(command, event),
+                };
+            }
+        }
+        return { event, state: 'missing' };
+    });
+    return { exists: existed, events };
+}
+//# sourceMappingURL=install.js.map

package/dist/log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One JSON line per hook run in `$OORT_HOME/logs/hooks.log`. Entries hold ids,
+ * outcomes, counts and timings only, never prompt, memory or transcript text:
+ * the logger takes no free-form string beyond the fields below, and callers
+ * pass outcome names they choose, never input.
+ */
+export interface HookLogEntry {
+    ts: string;
+    event: string;
+    /** Claude Code's session id (sanitised). */
+    session: string | null;
+    project: string | null;
+    outcome: string;
+    counts: Record<string, number>;
+    timings: Record<string, number>;
+    degraded?: string[];
+    /** Queue line ids (random uuids), e.g. for dead-lettered lines. */
+    ids?: string[];
+}
+export interface HookLogger {
+    /** Appends one line. Never throws: a broken log must not break a session. */
+    write(entry: Omit<HookLogEntry, 'ts'> & {
+        ts?: string;
+    }): void;
+}
+/** The log rotates to `hooks.log.1` (one rotation kept) once it exceeds this. */
+export declare const HOOK_LOG_MAX_BYTES: number;
+export declare function createHookLogger(home: string, opts?: {
+    maxBytes?: number;
+}): HookLogger;