hippo-memory 1.69.0 → 1.71.0

package/dist/{cli → hooks}/hook-blocks.d.ts

@@ -2,11 +2,15 @@ export declare const HOOK_MARKERS: {
     start: string;
     end: string;
 };
-export declare const HOOKS: Record<string, {
+export interface HookSpec {
     file: string;
     content: string;
     description: string;
-}>;
+}
+export interface HookTable {
+    [agent: string]: HookSpec;
+}
+export declare const HOOKS: HookTable;
 /** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
 export declare function hippoBlock(text: string): {
     start: number;

package/dist/{cli → hooks}/hook-blocks.js

@@ -1,75 +1,26 @@
 // The hippo block each agent's instruction file carries, and how init recognises one it wrote earlier.
 import { createHash } from 'node:crypto';
-import { escapeRegex } from '../escape.js';
+import { escapeRegex } from '../util/escape.js';
 export const HOOK_MARKERS = {
     start: '<!-- hippo:start -->',
     end: '<!-- hippo:end -->',
 };
-export const HOOKS = {
-    'claude-code': {
-        file: 'CLAUDE.md',
-        description: 'Claude Code',
-        content: `
-## Project Memory (Hippo)
-
-Pinned rules and recent writes auto-inject at every prompt via the installed
-UserPromptSubmit hook; never re-run that part manually. At the START of a
-task (not per prompt), additionally load task-specific context: git-aware
-recall over the full store that per-prompt injection does not cover. Also
-run it if the hook is not installed:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-
-When you find out why something failed, record it right then, while you
-work, never as a closing step:
-\`\`\`bash
-hippo remember "<what went wrong and why>" --error
-\`\`\`
-
-The installed hooks store failed tool calls and capture the session when it
-ends, so there is nothing to run before you finish.
-`.trim(),
-    },
-    'codex': {
-        file: 'AGENTS.md',
-        description: 'OpenAI Codex',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every task, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
-\`\`\`bash
-hippo remember "<what you learned and why>"
-\`\`\`
-
-When Hippo's Codex wrapper is installed, session-end capture runs automatically.
-If the wrapper is not installed, capture a brief summary manually:
+// Shared by the agents that differ only in the noun, an optional recall paragraph and an optional footer.
+const PI_FOOTER = 'For full integration, copy the hippo-memory Pi extension to `~/.pi/agent/extensions/hippo-memory/`.';
+function agentsBlock(noun, opts = {}) {
+    const recall = opts.recall
+        ? `
+When stuck or repeating yourself, check if this happened before:
 \`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+hippo recall "<what's going wrong>" --budget 2000
 \`\`\`
-`.trim(),
-    },
-    'cursor': {
-        file: 'AGENTS.md',
-        description: 'Cursor',
-        content: `
+`
+        : '';
+    const footer = opts.footer ? `\n${opts.footer}\n` : '';
+    return `
 ## Project Memory (Hippo)
 
-At the start of every task, run:
+At the start of every ${noun}, run:
 \`\`\`bash
 hippo context --auto --budget 1500
 \`\`\`
@@ -87,47 +38,42 @@ work, never as a closing step. Leave out secrets and personal details:
 \`\`\`bash
 hippo remember "<what you learned and why>"
 \`\`\`
-
+${recall}
 When ending a session, capture a brief summary:
 \`\`\`bash
 hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
 \`\`\`
-`.trim(),
-    },
-    'openclaw': {
-        file: 'AGENTS.md',
-        description: 'OpenClaw',
+${footer}`.trim();
+}
+export const HOOKS = {
+    'claude-code': {
+        file: 'CLAUDE.md',
+        description: 'Claude Code',
         content: `
 ## Project Memory (Hippo)
 
-At the start of every session, run:
+Pinned rules and recent writes auto-inject at every prompt via the installed
+UserPromptSubmit hook; never re-run that part manually. At the START of a
+task (not per prompt), additionally load task-specific context: git-aware
+recall over the full store that per-prompt injection does not cover. Also
+run it if the hook is not installed:
 \`\`\`bash
 hippo context --auto --budget 1500
 \`\`\`
-Read the output before writing any code.
 
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
+When you find out why something failed, record it right then, while you
+work, never as a closing step:
 \`\`\`bash
-hippo remember "<what you learned and why>"
+hippo remember "<what went wrong and why>" --error
 \`\`\`
 
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
-\`\`\`
+The installed hooks store failed tool calls and capture the session when it
+ends, so there is nothing to run before you finish.
 `.trim(),
     },
-    'opencode': {
+    'codex': {
         file: 'AGENTS.md',
-        description: 'OpenCode',
+        description: 'OpenAI Codex',
         content: `
 ## Project Memory (Hippo)
 
@@ -150,50 +96,17 @@ work, never as a closing step. Leave out secrets and personal details:
 hippo remember "<what you learned and why>"
 \`\`\`
 
-When stuck or repeating yourself, check if this happened before:
-\`\`\`bash
-hippo recall "<what's going wrong>" --budget 2000
-\`\`\`
-
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
-\`\`\`
-`.trim(),
-    },
-    'pi': {
-        file: 'AGENTS.md',
-        description: 'Pi',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every session, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour, record it right then, while you work,
-never as a closing step:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-When you learn something that should outlive this session (a decision and
-its reason, a user preference, a lesson), record it right then, while you
-work, never as a closing step. Leave out secrets and personal details:
-\`\`\`bash
-hippo remember "<what you learned and why>"
-\`\`\`
-
-When ending a session, capture a brief summary:
+When Hippo's Codex wrapper is installed, session-end capture runs automatically.
+If the wrapper is not installed, capture a brief summary manually:
 \`\`\`bash
 hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
 \`\`\`
-
-For full integration, copy the hippo-memory Pi extension to \`~/.pi/agent/extensions/hippo-memory/\`.
 `.trim(),
     },
+    'cursor': { file: 'AGENTS.md', description: 'Cursor', content: agentsBlock('task') },
+    'openclaw': { file: 'AGENTS.md', description: 'OpenClaw', content: agentsBlock('session') },
+    'opencode': { file: 'AGENTS.md', description: 'OpenCode', content: agentsBlock('task', { recall: true }) },
+    'pi': { file: 'AGENTS.md', description: 'Pi', content: agentsBlock('session', { footer: PI_FOOTER }) },
 };
 // sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited. Add the old hash when a block changes.
 const SHIPPED_HOOK_HASHES = new Map([

package/dist/hooks/json-hooks.d.ts

@@ -1,40 +1,7 @@
-/**
- * Hook install/uninstall for AI coding tools.
- *
- * Two integration models live in this file:
- *
- * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
- *    tool's settings.json with two entries:
- *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
- *        child that runs `hippo sleep` then `hippo capture --last-session` in
- *        sequence, writing both outputs to the log file. The parent returns in
- *        <100ms so the TUI teardown can't kill the child before it finishes.
- *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker on stderr and
- *        clears it. Stdout carries only a `systemMessage` problems line,
- *        because Claude Code shows that to the user, not the model.
- *    Earlier Claude Code forms are detected and migrated automatically:
- *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
- *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
- *      - 0.22.x: separate sleep + capture SessionEnd entries.
- *    PreCompact and PostCompact entries go in too: the first records the compaction and
- *    asks the summariser for a "Memories for hippo" list, the second saves that list.
- *    Codex's hooks.json gets only two groups (per-prompt memory and
- *    compact-resume); see installCodexHooks. Copilot gets a file of its own; see installCopilotHooks.
- *
- * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
- *    JSON-hook schema — its config has `additionalProperties: false` and no
- *    `hooks` key, so a JSON-hook install breaks opencode launch. Hippo
- *    installs a TypeScript plugin at
- *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
- *    `session.idle` (→ `hippo session-end`) and `session.created` (→
- *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
- *    plugin file content + design rationale; see installOpencodePlugin for
- *    the installer + the migration that removes any pre-existing broken
- *    `hooks` block from opencode.json.
- */
+/** Hook install/uninstall for AI coding tools. Claude Code gets a JSON `hooks` block in settings.json; older forms are migrated automatically.
+ * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import { type JsonHookTarget } from './shared.js';
-import { type JsonValue } from '../json.js';
+import { type JsonValue } from '../util/json.js';
 /** A target's hook settings file, the log its SessionEnd hook writes, and the tool's display name. */
 export interface JsonHookPaths {
     settings: string;
@@ -71,6 +38,7 @@ export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
 export declare function writeSettingsFile(file: string, settings: JsonValue): void;
 /** Removes hippo's own hook handlers from `target`'s settings file and keeps every other handler; true when the file changed. */
 export declare function uninstallJsonHooks(target: JsonHookTarget): boolean;
-/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists
+ * but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
 export declare function checkUninstallable(target: JsonHookTarget): Pick<InstallResult, 'settingsPath' | 'invalidJson'>;
 //# sourceMappingURL=json-hooks.d.ts.map

package/dist/hooks/json-hooks.js

@@ -1,44 +1,11 @@
-/**
- * Hook install/uninstall for AI coding tools.
- *
- * Two integration models live in this file:
- *
- * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
- *    tool's settings.json with two entries:
- *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
- *        child that runs `hippo sleep` then `hippo capture --last-session` in
- *        sequence, writing both outputs to the log file. The parent returns in
- *        <100ms so the TUI teardown can't kill the child before it finishes.
- *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker on stderr and
- *        clears it. Stdout carries only a `systemMessage` problems line,
- *        because Claude Code shows that to the user, not the model.
- *    Earlier Claude Code forms are detected and migrated automatically:
- *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
- *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
- *      - 0.22.x: separate sleep + capture SessionEnd entries.
- *    PreCompact and PostCompact entries go in too: the first records the compaction and
- *    asks the summariser for a "Memories for hippo" list, the second saves that list.
- *    Codex's hooks.json gets only two groups (per-prompt memory and
- *    compact-resume); see installCodexHooks. Copilot gets a file of its own; see installCopilotHooks.
- *
- * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
- *    JSON-hook schema — its config has `additionalProperties: false` and no
- *    `hooks` key, so a JSON-hook install breaks opencode launch. Hippo
- *    installs a TypeScript plugin at
- *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
- *    `session.idle` (→ `hippo session-end`) and `session.created` (→
- *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
- *    plugin file content + design rationale; see installOpencodePlugin for
- *    the installer + the migration that removes any pre-existing broken
- *    `hooks` block from opencode.json.
- */
+/** Hook install/uninstall for AI coding tools. Claude Code gets a JSON `hooks` block in settings.json; older forms are migrated automatically.
+ * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import * as fs from 'fs';
 import * as path from 'path';
-import { isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
-import { isJsonString, readJsonFile } from '../json.js';
-import { escapeRegex } from '../escape.js';
-import { errorMessage, log } from '../log.js';
+import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
+import { isJsonString, readJsonFile, isJsonObjectLiteral } from '../util/json.js';
+import { escapeRegex } from '../util/escape.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 /** The paths for `target` under the current home directory; reads and writes nothing. */
 export function resolveJsonHookPaths(target) {
     const home = homeDir();
@@ -66,20 +33,21 @@ export function resolveJsonHookPaths(target) {
 }
 // An unterminated quote runs to the end, as in a shell, which also keeps the scan linear.
 const QUOTED_SPAN = /'[^']*(?:'|$)|"(?:[^"\\]|\\[\s\S]?)*(?:"|$)/g;
-/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
+/** Hippo's command only at string start or after `(`, past env assignments and an install path, with quoted
+ * text ignored: `say hippo sleep`, `echo "a; hippo sleep"` and `./backup.sh && hippo sleep` stay a user's. */
 function isHippoCommand(command, marker) {
     const unquoted = command.replace(QUOTED_SPAN, '');
     return new RegExp(`(?:^|\\()\\s*(?:[A-Za-z_]\\w*=\\S*\\s+)*(?:[^\\s(]*[/\\\\])?${escapeRegex(marker)}(?![\\w.-])`).test(unquoted);
 }
 const runsHippo = (...markers) => (command) => markers.some((m) => isHippoCommand(command, m));
 function handlerCommand(handler) {
-    return isJsonObject(handler) && isJsonString(handler.command) ? handler.command : null;
+    return isJsonObjectLiteral(handler) && isJsonString(handler.command) ? handler.command : null;
 }
 /** `groups` minus the handlers `isOurs` picks; a group goes only once it has no handler left. Null when no handler matched. */
 function withoutHandlers(groups, isOurs) {
     let removed = false;
     const kept = groups.flatMap((group) => {
-        if (!isJsonObject(group) || !Array.isArray(group.hooks))
+        if (!isJsonObjectLiteral(group) || !Array.isArray(group.hooks))
             return [group];
         const handlers = group.hooks.filter((h) => {
             const command = handlerCommand(h);
@@ -108,7 +76,7 @@ function stripHandlers(hooks, event, isOurs) {
 }
 /** Every command string in `groups`; a group or handler of an unexpected shape adds none. */
 function handlerCommands(groups) {
-    return groups.flatMap((group) => (isJsonObject(group) && Array.isArray(group.hooks) ? group.hooks.flatMap((h) => handlerCommand(h) ?? []) : []));
+    return groups.flatMap((group) => (isJsonObjectLiteral(group) && Array.isArray(group.hooks) ? group.hooks.flatMap((h) => handlerCommand(h) ?? []) : []));
 }
 /** The loose "already installed?" test, on purpose weaker than isHippoCommand: a launcher or env prefix still counts, and a false hit only skips an append. */
 function hookArrayContains(hookArray, marker) {
@@ -126,13 +94,13 @@ function migratePinnedInjectRecentCommands(hookArray) {
         return false;
     let changed = false;
     for (const entry of hookArray) {
-        if (!isJsonObject(entry))
+        if (!isJsonObjectLiteral(entry))
             continue;
         const innerHooks = entry.hooks;
         if (!Array.isArray(innerHooks))
             continue;
         for (const hook of innerHooks) {
-            if (!isJsonObject(hook))
+            if (!isJsonObjectLiteral(hook))
                 continue;
             if (!isJsonString(hook.command))
                 continue;
@@ -167,19 +135,20 @@ function nothingInstalled(target, settingsPath) {
 function codexCommandHook(command, timeout) {
     return { type: 'command', command, commandWindows: command.replace(/^hippo /, 'hippo.cmd '), timeout };
 }
-/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose `events`, where present, are arrays; null when appending would overwrite anything else. */
+/** Assigns `settings.hooks = {}` when it is absent, then returns it if it is an object whose
+ * `events`, where present, are arrays; null when appending would overwrite anything else. */
 function ensureHooksObject(settings, events) {
     if (settings.hooks === undefined)
         settings.hooks = {};
     const hooks = settings.hooks;
-    if (!isJsonObject(hooks) || events.some((e) => hooks[e] !== undefined && !Array.isArray(hooks[e])))
+    if (!isJsonObjectLiteral(hooks) || events.some((e) => hooks[e] !== undefined && !Array.isArray(hooks[e])))
         return null;
     return hooks;
 }
 /** Codex keys trust to each hook's position and hash and re-asks for a changed one, so hippo only appends and never edits an entry. */
 function installCodexHooks(settingsPath, settings) {
     const result = nothingInstalled('codex', settingsPath);
-    if (!isJsonObject(settings))
+    if (!isJsonObjectLiteral(settings))
         return { ...result, invalidJson: true };
     const hooks = ensureHooksObject(settings, ['UserPromptSubmit', 'SessionStart']);
     if (hooks === null)
@@ -225,7 +194,7 @@ function copilotHooksTable() {
 /** The events in hippo's Copilot hooks file, in file order, for setup to name. */
 export function copilotHookEvents() {
     const hooks = copilotHooksTable().hooks;
-    return isJsonObject(hooks) ? Object.keys(hooks) : [];
+    return isJsonObjectLiteral(hooks) ? Object.keys(hooks) : [];
 }
 /** Hippo owns this whole file, so install writes the full table and a second install changes no byte. */
 function installCopilotHooks(settingsPath) {
@@ -256,112 +225,13 @@ export function installJsonHooks(target) {
     }
     if (target === 'codex')
         return installCodexHooks(settingsPath, settings);
-    if (!isJsonObject(settings))
+    if (!isJsonObjectLiteral(settings))
         return { ...nothingInstalled(target, settingsPath), invalidJson: true };
     return installClaudeCodeHooks(settingsPath, settings, logFile);
 }
-const RENAME_RETRY_MS = 1000;
-const WINDOWS_RENAME_REFUSALS = ['EPERM', 'EACCES', 'EBUSY'];
-// A rename can be refused where an in-place write still works (a bind-mounted file, a read-only folder), so these fall back to one.
-const REPLACE_REFUSALS = ['EBUSY', 'EXDEV', 'EACCES', 'EPERM'];
-// Matches the usual SYMLOOP_MAX, so a link cycle ends in an error instead of a hang.
-const MAX_LINK_HOPS = 40;
-function errnoCode(err) {
-    return 'code' in err ? String(err.code) : '';
-}
-/** Windows refuses a rename onto a file another program has open, usually for a moment, so a refusal is retried before it is reported. */
-function renameOnto(tmp, target) {
-    const deadline = Date.now() + RENAME_RETRY_MS;
-    const idle = new Int32Array(new SharedArrayBuffer(4));
-    for (let pause = 10;; pause = Math.min(pause * 2, 200)) {
-        try {
-            fs.renameSync(tmp, target);
-            return;
-        }
-        catch (err) {
-            const transient = process.platform === 'win32' && err instanceof Error && WINDOWS_RENAME_REFUSALS.includes(errnoCode(err));
-            const left = deadline - Date.now();
-            if (!transient || left <= 0)
-                throw err;
-            Atomics.wait(idle, 0, 0, Math.min(pause, left));
-        }
-    }
-}
-/** Where a write to `file` lands: through any symlink, a dangling one included, so a dotfile manager's link survives. */
-function writeTarget(file) {
-    let target = file;
-    for (let hop = 0; hop < MAX_LINK_HOPS && fs.lstatSync(target, { throwIfNoEntry: false })?.isSymbolicLink(); hop++) {
-        target = path.resolve(path.dirname(target), fs.readlinkSync(target));
-    }
-    return fs.existsSync(target) ? fs.realpathSync(target) : target;
-}
-/** Gives the replacement the old file's exact mode (umask trims the create mode) and, for root, its owner. */
-function keepAccess(tmp, old) {
-    fs.chmodSync(tmp, old.mode & 0o777);
-    if (process.getuid?.() === 0)
-        fs.chownSync(tmp, old.uid, old.gid);
-}
-/** Cleanup must not hide the failure that made it necessary, so a cleanup error is logged and the first error stays the one thrown. */
-function removeTemp(tmp) {
-    try {
-        fs.rmSync(tmp, { force: true });
-    }
-    catch (err) {
-        log.warn(`could not remove the temporary file ${tmp}: ${errorMessage(err)}`);
-    }
-}
-function replaceViaTemp(target, text, old) {
-    const tmp = `${target}.${process.pid}.tmp`;
-    try {
-        fs.writeFileSync(tmp, text, { encoding: 'utf8', mode: (old?.mode ?? 0o666) & 0o777 });
-        if (old)
-            keepAccess(tmp, old);
-        renameOnto(tmp, target);
-    }
-    catch (err) {
-        removeTemp(tmp);
-        throw err;
-    }
-}
-/** The pre-rename write: it truncates first, so it is only the fallback, but it needs just a writable file and keeps hard links together. */
-function writeInPlace(target, text) {
-    try {
-        fs.writeFileSync(target, text, 'utf8');
-    }
-    catch (err) {
-        if (!(err instanceof Error))
-            throw err;
-        const reason = errnoCode(err) === 'EBUSY'
-            ? 'is in use by another program, so hippo could not replace it; close that program and run the command again'
-            : `could not be replaced (${errnoCode(err) || err.message})`;
-        throw new Error(`${target} ${reason}`, { cause: err });
-    }
-}
 /** Swaps the file in with one rename, so a crash mid-write cannot leave a truncated settings.json that Claude Code cannot parse. */
 export function writeSettingsFile(file, settings) {
-    const target = writeTarget(file);
-    const text = JSON.stringify(settings, null, 2) + '\n';
-    const old = fs.statSync(target, { throwIfNoEntry: false });
-    if (old === undefined) {
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-    }
-    else {
-        // A rename replaces a read-only file that the in-place write refused, and Windows would retry that refusal for a second.
-        fs.accessSync(target, fs.constants.W_OK);
-    }
-    if (old !== undefined && old.nlink > 1) {
-        // A rename gives the file a new inode, which would leave the other hard links on the old content.
-        writeInPlace(target, text);
-        return;
-    }
-    try {
-        replaceViaTemp(target, text, old);
-    }
-    catch (err) {
-        if (!(err instanceof Error) || !REPLACE_REFUSALS.includes(errnoCode(err)))
-            throw err;
-        writeInPlace(target, text);
-    }
+    writeFileAtomic(file, JSON.stringify(settings, null, 2) + '\n');
 }
 function migrateLegacyClaudeHooks(hooks) {
     const migratedFromStop = stripHandlers(hooks, 'Stop', runsHippo(HIPPO_SLEEP_MARKER));
@@ -406,40 +276,38 @@ const CLAUDE_HOOK_MARKERS = [
 ];
 // Stop is only ever migrated away, so install never appends to it and a Stop that is not a list does not block the install.
 const CLAUDE_APPENDED_EVENTS = CLAUDE_HOOK_MARKERS.map(([event]) => event).filter((event) => event !== 'Stop');
-function installClaudeCodeHooks(settingsPath, settings, logFile) {
-    const merge = ensureHooksObject(settings, CLAUDE_APPENDED_EVENTS);
-    if (merge === null)
-        return { ...nothingInstalled('claude-code', settingsPath), invalidJson: true };
-    // SAFETY: ensureHooksObject left every event hippo appends to absent or an array.
-    const hooks = merge;
-    const migration = migrateLegacyClaudeHooks(hooks);
+function appendSessionHooks(hooks, logFile) {
     const installedSessionEnd = appendHookIfMissing(hooks, 'SessionEnd', HIPPO_SESSION_END_MARKER, claudeCommandGroup(`hippo session-end --log-file "${logFile}"`, 5));
     const installedSessionStart = appendHookIfMissing(hooks, 'SessionStart', HIPPO_LAST_SLEEP_MARKER, claudeCommandGroup(`hippo last-sleep --path "${logFile}"`, 5));
-    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn,
-    // so pinned memories stay in context even after the model would otherwise
-    // "forget" them in a long session. Include the fresh write tail so lessons
-    // saved earlier in the same session become visible on the next prompt even
-    // before the user pins them explicitly.
+    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn, so pinned memories stay in context; the fresh write tail
+    // makes lessons saved earlier in the session visible on the next prompt even before they are pinned.
     const migratedPinnedInjectRecent = migratePinnedInjectRecentCommands(hooks.UserPromptSubmit);
     const installedUserPromptSubmit = appendHookIfMissing(hooks, 'UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, claudeCommandGroup(HIPPO_PINNED_INJECT_COMMAND, 5));
-    // PreCompact: fires on manual AND auto compaction (no matcher). Records the compaction, asks the
-    // summariser for a "Memories for hippo" list and saves a working-state snapshot before the summary drops detail.
-    // Exit-0 contract lives in the verb itself (src/capture.ts cmdPreCompact),
-    // not here — this is install-time wiring only.
+    return { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit };
+}
+function appendCompactionHooks(hooks) {
+    // PreCompact: fires on manual AND auto compaction (no matcher); records it, asks the summariser for a "Memories for hippo" list and saves a snapshot.
+    // The exit-0 contract lives in the verb itself (cmdPreCompact, src/capture/compact.ts), not in this install-time wiring.
     const installedPreCompact = appendHookIfMissing(hooks, 'PreCompact', HIPPO_PRE_COMPACT_MARKER, claudeCommandGroup(`hippo pre-compact --log-file "${defaultPreCompactLogPath()}"`, 30));
-    // SessionStart(compact): a SECOND SessionStart entry alongside the
-    // un-matched last-sleep entry above. The matcher is an optimization, not
-    // a dependency — compact-resume itself checks payload.source too, so an
-    // older Claude Code that ignores the matcher just runs a silent no-op on
-    // normal starts. Marker check keys on the command string, so this stays
-    // idempotent alongside the sibling last-sleep entry.
+    // SessionStart(compact): a second SessionStart entry beside the unmatched last-sleep one. The matcher is an optimization, not a dependency:
+    // compact-resume checks payload.source itself, and the marker check keys on the command string, so this stays idempotent.
     const installedCompactResume = appendHookIfMissing(hooks, 'SessionStart', HIPPO_COMPACT_RESUME_MARKER, claudeCommandGroup('hippo compact-resume', 10, 'compact'));
     // PostCompact: saves the memories the summariser listed and prints one line, which Claude Code only shows.
     // PreCompact stdout, by contrast, is handed to the summariser as instructions, so pre-compact prints just the request.
     const installedPostCompact = appendHookIfMissing(hooks, 'PostCompact', HIPPO_POST_COMPACT_MARKER, claudeCommandGroup(`hippo post-compact --log-file "${defaultPreCompactLogPath()}"`, 10));
-    // PostToolUseFailure: a failed tool call becomes an error memory, after
-    // `hippo capture-error` drops routine failures (interrupts, declined
-    // permissions, empty searches) and repeats. Same hook the plugin ships.
+    return { installedPreCompact, installedCompactResume, installedPostCompact };
+}
+function installClaudeCodeHooks(settingsPath, settings, logFile) {
+    const merge = ensureHooksObject(settings, CLAUDE_APPENDED_EVENTS);
+    if (merge === null)
+        return { ...nothingInstalled('claude-code', settingsPath), invalidJson: true };
+    // SAFETY: ensureHooksObject left every event hippo appends to absent or an array.
+    const hooks = merge;
+    const migration = migrateLegacyClaudeHooks(hooks);
+    const { installedSessionEnd, installedSessionStart, migratedPinnedInjectRecent, installedUserPromptSubmit } = appendSessionHooks(hooks, logFile);
+    const { installedPreCompact, installedCompactResume, installedPostCompact } = appendCompactionHooks(hooks);
+    // PostToolUseFailure: a failed tool call becomes an error memory, after `hippo capture-error` drops routine failures
+    // (interrupts, declined permissions, empty searches) and repeats. Same hook the plugin ships.
     const installedCaptureError = appendHookIfMissing(hooks, 'PostToolUseFailure', HIPPO_CAPTURE_ERROR_MARKER, claudeCommandGroup('hippo capture-error', 10, '.*'));
     const result = {
         target: 'claude-code',
@@ -471,7 +339,8 @@ function uninstallCodexHooks(hooks) {
         changed = stripHandlers(hooks, event, (c) => c === command) || changed;
     return changed;
 }
-/** One stderr line naming the handlers uninstall kept that still mention a hippo command (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
+/** One stderr line naming the handlers uninstall kept that still mention a hippo command
+ * (`nice hippo sleep`, `pnpm exec hippo ...`), so the user can remove them by hand. */
 function warnKeptHippoHandlers(settingsPath, hooks) {
     const kept = CLAUDE_HOOK_MARKERS.flatMap(([event, markers]) => {
         const groups = hooks[event];
@@ -499,7 +368,7 @@ export function uninstallJsonHooks(target) {
         // Never rewrite a settings file we cannot parse; report nothing uninstalled.
         return false;
     }
-    if (!isJsonObject(settings) || !isJsonObject(settings.hooks))
+    if (!isJsonObjectLiteral(settings) || !isJsonObjectLiteral(settings.hooks))
         return false;
     const hooks = settings.hooks;
     const changed = target === 'codex' ? uninstallCodexHooks(hooks) : uninstallClaudeCodeHooks(hooks);
@@ -512,14 +381,15 @@ export function uninstallJsonHooks(target) {
     writeSettingsFile(settingsPath, settings);
     return true;
 }
-/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists
+ * but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
 export function checkUninstallable(target) {
     const { settings: settingsPath } = resolveJsonHookPaths(target);
     if (!fs.existsSync(settingsPath))
         return { settingsPath, invalidJson: false };
     try {
         const settings = readJsonFile(settingsPath);
-        return { settingsPath, invalidJson: !isJsonObject(settings) || (settings.hooks !== undefined && !isJsonObject(settings.hooks)) };
+        return { settingsPath, invalidJson: !isJsonObjectLiteral(settings) || (settings.hooks !== undefined && !isJsonObjectLiteral(settings.hooks)) };
     }
     catch {
         return { settingsPath, invalidJson: true };