hippo-memory 1.69.0 → 1.71.0

package/dist/graph/write.js

@@ -1,285 +1,13 @@
-/**
- * Graph layer over consolidated state - the graph-on-consolidated guard.
- *
- * A graph of canonical `entities` (person/project/customer/system/policy/decision) and
- * `relations` (owns/supersedes/depends-on/blocked-by/references) sits ON TOP OF
- * consolidated memories. The hard rule: the graph NEVER indexes the raw layer - every
- * entity and relation references a memory whose `kind IN ('distilled','superseded')`,
- * never `kind='raw'`. Enforced at the DB level (CHECK on source_kind/kind + BEFORE
- * INSERT and BEFORE UPDATE triggers that tie source_kind/kind to the FK'd memory's
- * actual kind and enforce tenant-match - relations also reject cross-tenant edges), so
- * the forbidden state is unrepresentable regardless of code path. These helpers
- * surface the same guard as clear throws BEFORE hitting the trigger backstop.
- */
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { assertTenantId } from '../tenant.js';
-import { log } from '../log.js';
-import { clock } from '../write-budget.js';
-import { GRAPH_ENTITY_TYPES, GRAPH_RELATION_TYPES, MAX_ENTITY_NAME_LEN } from './types.js';
-import { rowToEntity, rowToRelation, rowToQueueItem, ENTITY_COLS, RELATION_COLS, QUEUE_COLS } from './rows.js';
-const SOURCE_OBJECT_TABLE = {
-    decision: 'decisions',
-    policy: 'policies',
-    customer: 'customer_notes',
-    project: 'project_briefs',
-};
-function resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, label) {
-    let memKind = null;
-    let effectiveMemoryId = memoryId;
-    if (memoryId != null) {
-        // SAFETY: row's shape matches the two columns (kind, tenant_id) named in
-        // the SELECT above.
-        const row = db.prepare(`SELECT kind, tenant_id FROM memories WHERE id = ?`).get(memoryId);
-        if (!row) {
-            // Stale / forgotten mirror. Tolerate it IFF a valid source object provides provenance:
-            // graph-extract reads object rows then inserts, and a mirror forgotten/pruned in that window
-            // must NOT roll back the whole tenant rebuild - the active object survives mirror loss.
-            // Anchor to the object; drop the dead memory pointer.
-            if (sourceObject == null) {
-                throw new Error(`${label}: source memory ${memoryId} not found`);
-            }
-            effectiveMemoryId = null;
-        }
-        else if (row.tenant_id !== tenantId) {
-            throw new Error(`${label}: source memory ${memoryId} belongs to another tenant`);
-        }
-        else if (row.kind === 'raw') {
-            throw new Error(`${label}: source memory ${memoryId} is raw; the graph indexes consolidated state only`);
-        }
-        else if (row.kind !== 'distilled' && row.kind !== 'superseded') {
-            throw new Error(`${label}: source memory ${memoryId} has unsupported kind '${row.kind}'`);
-        }
-        else {
-            memKind = row.kind;
-        }
-    }
-    // Validate the object pointer WHENEVER it is provided, not only when memory is null:
-    // a dual-set row whose object is wrong/closed/cross-tenant would become
-    // the active provenance after ON DELETE SET NULL and could then block the memory delete.
-    if (sourceObject != null) {
-        const table = SOURCE_OBJECT_TABLE[sourceObject.type];
-        if (!table) {
-            throw new Error(`${label}: unsupported source_object_type '${sourceObject.type}'`);
-        }
-        // `table` is a fixed value from the SOURCE_OBJECT_TABLE map (never user-supplied), so
-        // this string interpolation is safe; `id`/`tenant_id` stay parametrized.
-        // SAFETY: row's shape matches the single `status` column named in the
-        // SELECT above.
-        const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(sourceObject.id, tenantId);
-        if (!row) {
-            throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} not found for tenant ${tenantId}`);
-        }
-        if (row.status !== 'active' && row.status !== 'superseded') {
-            throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} has status '${row.status}' (must be active|superseded)`);
-        }
-    }
-    // source_kind is the memory's kind when a memory is present, else 'distilled' for an
-    // object-only row (objects are consolidated by construction). All-null is rejected.
-    if (memKind != null)
-        return { sourceKind: memKind, memoryId: effectiveMemoryId };
-    if (sourceObject != null)
-        return { sourceKind: 'distilled', memoryId: null };
-    throw new Error(`${label}: graph row needs a memory or a source object`);
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Insert a graph entity extracted from a consolidated memory. Throws if the source
- * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
- */
-export function insertEntity(hippoRoot, tenantId, opts, txDb) {
-    assertTenantId('insertEntity', tenantId);
-    if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
-        throw new Error(`insertEntity: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
-    }
-    const name = checkedName('insertEntity', opts.name);
-    const now = new Date().toISOString();
-    const memoryId = opts.memoryId ?? null;
-    const sourceObject = opts.sourceObject ?? null;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertEntity');
-        const result = db.prepare(`
-      INSERT INTO entities(tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(tenantId, opts.entityType, name, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
-        const id = Number(result.lastInsertRowid ?? 0);
-        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
-        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ?`).get(id);
-        if (!row)
-            throw new Error('insertEntity: failed to reload inserted entity');
-        return rowToEntity(row);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-function checkedName(label, raw) {
-    const name = (raw ?? '').trim();
-    if (name.length === 0)
-        throw new Error(`${label}: name is required`);
-    if (name.length > MAX_ENTITY_NAME_LEN) {
-        throw new Error(`${label}: name exceeds the ${MAX_ENTITY_NAME_LEN}-char cap`);
-    }
-    return name;
-}
-/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
- *  A delete plus an insert would cascade away every relation that points at it. */
-export function updateEntity(hippoRoot, tenantId, id, opts, txDb) {
-    assertTenantId('updateEntity', tenantId);
-    const name = checkedName('updateEntity', opts.name);
-    const db = txDb ?? openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
-        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-        if (!row)
-            return null;
-        const entity = rowToEntity(row);
-        const sourceObject = entity.sourceObjectType === undefined || entity.sourceObjectId === undefined
-            ? null
-            : { type: entity.sourceObjectType, id: entity.sourceObjectId };
-        const resolved = resolveConsolidatedSource(db, tenantId, opts.memoryId ?? null, sourceObject, 'updateEntity');
-        db.prepare(`UPDATE entities SET name = ?, memory_id = ?, source_kind = ? WHERE id = ? AND tenant_id = ?`)
-            .run(name, resolved.memoryId, resolved.sourceKind, id, tenantId);
-        return { ...entity, name, memoryId: resolved.memoryId, sourceKind: resolved.sourceKind };
-    }
-    finally {
-        if (db !== txDb)
-            closeHippoDb(db);
-    }
-}
-/**
- * Insert a graph relation between two entities, sourced from a consolidated memory.
- * Both entities must exist in the same tenant; the source memory must be consolidated.
- */
-export function insertRelation(hippoRoot, tenantId, opts, txDb) {
-    assertTenantId('insertRelation', tenantId);
-    if (!GRAPH_RELATION_TYPES.has(opts.relType)) {
-        throw new Error(`insertRelation: relType must be one of ${Array.from(GRAPH_RELATION_TYPES).join('|')}; got ${opts.relType}`);
-    }
-    const now = new Date().toISOString();
-    const memoryId = opts.memoryId ?? null;
-    const sourceObject = opts.sourceObject ?? null;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        for (const [eid, role] of [[opts.fromEntityId, 'from'], [opts.toEntityId, 'to']]) {
-            // SAFETY: ent's shape matches the single `tenant_id` column named in
-            // the SELECT above.
-            const ent = db.prepare(`SELECT tenant_id FROM entities WHERE id = ?`).get(eid);
-            if (!ent)
-                throw new Error(`insertRelation: ${role}_entity ${eid} not found`);
-            if (ent.tenant_id !== tenantId) {
-                throw new Error(`insertRelation: ${role}_entity ${eid} belongs to another tenant (no cross-tenant edges)`);
-            }
-        }
-        const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertRelation');
-        const result = db.prepare(`
-      INSERT INTO relations(tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(tenantId, opts.fromEntityId, opts.toEntityId, opts.relType, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
-        const id = Number(result.lastInsertRowid ?? 0);
-        // SAFETY: row's shape matches the columns named in RELATION_COLS above.
-        const row = db.prepare(`SELECT ${RELATION_COLS} FROM relations WHERE id = ?`).get(id);
-        if (!row)
-            throw new Error('insertRelation: failed to reload inserted relation');
-        return rowToRelation(row);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-// ---------------------------------------------------------------------------
-// Extraction queue
-// ---------------------------------------------------------------------------
-/**
- * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
- * cross-tenant memory (the DB trigger is the backstop).
- */
-export function enqueueExtraction(hippoRoot, tenantId, memoryId) {
-    assertTenantId('enqueueExtraction', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        // enqueue is memory-keyed (no source object), so a missing memory still throws (correct -
-        // you cannot enqueue a forgotten mirror); memoryId is non-null here by construction.
-        const { sourceKind } = resolveConsolidatedSource(db, tenantId, memoryId, null, 'enqueueExtraction');
-        const result = db.prepare(`
-      INSERT INTO graph_extraction_queue(tenant_id, memory_id, kind, status, enqueued_at, processed_at)
-      VALUES (?, ?, ?, 'pending', ?, NULL)
-    `).run(tenantId, memoryId, sourceKind, now);
-        const id = Number(result.lastInsertRowid ?? 0);
-        // SAFETY: row's shape matches the columns named in QUEUE_COLS above.
-        const row = db.prepare(`SELECT ${QUEUE_COLS} FROM graph_extraction_queue WHERE id = ?`).get(id);
-        if (!row)
-            throw new Error('enqueueExtraction: failed to reload queue item');
-        return rowToQueueItem(row);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
- * change, so the consolidated-source guard trigger (which fires on
- * memory_id/kind/tenant_id changes) is not involved. CAS on the current status to a
- * non-terminal 'pending'.
- */
-export function markExtractionProcessed(hippoRoot, tenantId, id, status = 'processed') {
-    assertTenantId('markExtractionProcessed', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        const updated = db.prepare(`
-      UPDATE graph_extraction_queue
-      SET status = ?, processed_at = ?
-      WHERE id = ? AND tenant_id = ? AND status = 'pending'
-    `).run(status, now, id, tenantId);
-        if (updated.changes === 0) {
-            // SAFETY: existing's shape matches the single `status` column named in
-            // the SELECT above.
-            const existing = db.prepare(`SELECT status FROM graph_extraction_queue WHERE id = ? AND tenant_id = ?`)
-                .get(id, tenantId);
-            if (!existing)
-                throw new Error(`markExtractionProcessed: queue item ${id} not found for tenant ${tenantId}`);
-            throw new Error(`markExtractionProcessed: queue item ${id} is not pending (status='${existing.status}')`);
-        }
-        // SAFETY: row's shape matches the columns named in QUEUE_COLS above.
-        const row = db.prepare(`SELECT ${QUEUE_COLS} FROM graph_extraction_queue WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        if (!row)
-            throw new Error(`markExtractionProcessed: queue item ${id} not found after UPDATE`);
-        return rowToQueueItem(row);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
-function objectInForce(db, tenantId, ref) {
-    // `table` comes from the fixed SOURCE_OBJECT_TABLE map, never from input.
-    const table = SOURCE_OBJECT_TABLE[ref.type];
-    // SAFETY: row's shape matches the single `status` column named in the SELECT.
-    const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(ref.id, tenantId);
-    return row?.status === 'active' || row?.status === 'superseded';
-}
-function entityIdByKey(db, tenantId, key) {
-    // SAFETY: row's shape matches the single `id` column named in the SELECT.
-    const row = db.prepare(`SELECT id FROM entities WHERE tenant_id = ? AND entity_type = ? AND source_object_type = ? AND source_object_id = ? ORDER BY id LIMIT 1`).get(tenantId, key.entityType, key.sourceObject.type, key.sourceObject.id);
-    return row?.id;
-}
+// Applies a rebuild's op list on the caller's transaction. The statements and the consolidated-source guard sit in the store's graph writers.
+import { assertTenantId } from '../store/tenant.js';
+import { clock } from '../util/write-budget.js';
+import { deleteEntityRow, deleteRelationRow, entityIdBySource, insertEntity, insertRelation, objectInForce, relationPresent, updateEntity } from '../store/graph-writes.js';
 function insertDesiredRelation(db, hippoRoot, tenantId, rel) {
-    const fromEntityId = entityIdByKey(db, tenantId, rel.from);
-    const toEntityId = entityIdByKey(db, tenantId, rel.to);
+    const fromEntityId = entityIdBySource(db, tenantId, rel.from.entityType, rel.from.sourceObject);
+    const toEntityId = entityIdBySource(db, tenantId, rel.to.entityType, rel.to.sourceObject);
     if (fromEntityId === undefined || toEntityId === undefined || !objectInForce(db, tenantId, rel.sourceObject))
         return false;
-    // SAFETY: row's shape matches the single aliased column named in the SELECT.
-    const present = db.prepare(`SELECT 1 AS hit FROM relations WHERE tenant_id = ? AND from_entity_id = ? AND to_entity_id = ? AND rel_type = ? LIMIT 1`).get(tenantId, fromEntityId, toEntityId, rel.relType);
-    if (present)
+    if (relationPresent(db, tenantId, fromEntityId, toEntityId, rel.relType))
         return false;
     insertRelation(hippoRoot, tenantId, { fromEntityId, toEntityId, relType: rel.relType, memoryId: rel.memoryId, sourceObject: rel.sourceObject }, db);
     return true;
@@ -288,10 +16,10 @@ function insertDesiredRelation(db, hippoRoot, tenantId, rel) {
 function applyGraphOp(db, hippoRoot, tenantId, op) {
     switch (op.op) {
         case 'deleteEntity':
-            db.prepare(`DELETE FROM entities WHERE id = ? AND tenant_id = ?`).run(op.id, tenantId);
+            deleteEntityRow(db, tenantId, op.id);
             return true;
         case 'deleteRelation':
-            db.prepare(`DELETE FROM relations WHERE id = ? AND tenant_id = ?`).run(op.id, tenantId);
+            deleteRelationRow(db, tenantId, op.id);
             return true;
         case 'updateEntity':
             if (!objectInForce(db, tenantId, op.entity.sourceObject))
@@ -299,7 +27,7 @@ function applyGraphOp(db, hippoRoot, tenantId, op) {
             return updateEntity(hippoRoot, tenantId, op.id, op.entity, db) !== null;
         case 'insertEntity':
             // A mirrorless object closed since the load is never enqueued again, so a stale insert would stay for good.
-            if (!objectInForce(db, tenantId, op.entity.sourceObject) || entityIdByKey(db, tenantId, op.entity) !== undefined)
+            if (!objectInForce(db, tenantId, op.entity.sourceObject) || entityIdBySource(db, tenantId, op.entity.entityType, op.entity.sourceObject) !== undefined)
                 return false;
             insertEntity(hippoRoot, tenantId, op.entity, db);
             return true;
@@ -307,13 +35,13 @@ function applyGraphOp(db, hippoRoot, tenantId, op) {
             return insertDesiredRelation(db, hippoRoot, tenantId, op.relation);
     }
 }
-/** Applies `ops` from index `from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
+/** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
  *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export function applyGraphOps(db, hippoRoot, tenantId, ops, from, opts) {
+export function applyGraphOps(db, hippoRoot, tenantId, ops, opts) {
     assertTenantId('applyGraphOps', tenantId);
     const now = opts.clock ?? clock;
     const begunAt = now();
-    let next = from;
+    let next = opts.from;
     let skipped = 0;
     while (next < ops.length) {
         if (!applyGraphOp(db, hippoRoot, tenantId, ops[next]))
@@ -324,116 +52,4 @@ export function applyGraphOps(db, hippoRoot, tenantId, ops, from, opts) {
     }
     return { next, skipped };
 }
-/** Runs one tenant's graph writes in `fn` on `txDb` under one BEGIN IMMEDIATE, so two rebuilds serialize instead of
- *  interleaving and a throw rolls back the whole chunk. The sole sanctioned place to wrap graph writes in a transaction. */
-export function runGraphRebuildTransaction(hippoRoot, tenantId, fn, opts) {
-    assertTenantId('runGraphRebuildTransaction', tenantId);
-    const db = openHippoDb(hippoRoot, opts);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        let committed = false;
-        try {
-            const out = fn(db);
-            db.exec('COMMIT');
-            committed = true;
-            return out;
-        }
-        finally {
-            if (!committed) {
-                try {
-                    db.exec('ROLLBACK');
-                }
-                catch { /* preserve the original throw */ }
-            }
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-// ---------------------------------------------------------------------------
-// Sleep enqueue-hook: producer helper + drain support
-// ---------------------------------------------------------------------------
-/**
- * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
- * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
- * graph-dirty signal failing must not abort a core object write. Graph staleness is
- * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
- * not. Called POST-COMMIT from the graph-source save/close mutations of
- * decision, policy, customer_note and project_brief. A null memoryId (a
- * forgotten mirror) is a no-op.
- */
-export function markGraphDirty(hippoRoot, tenantId, memoryId) {
-    if (!memoryId)
-        return;
-    try {
-        enqueueExtraction(hippoRoot, tenantId, memoryId);
-    }
-    catch (err) {
-        // Logged (warn) so a SYSTEMATIC enqueue failure surfaces to operators, but
-        // swallowed so the already-committed object write is never rolled back.
-        log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-/**
- * Remove the graph rows sourced from one first-class object, by its (type, id). Used when a
- * MIRRORLESS object is closed: it has no mirror memory, so `markGraphDirty` cannot
- * enqueue a rebuild (the queue is memory-keyed). Closing must still drop the object's
- * now-stale entity + edges from the graph, so we remove them directly here. Fail-soft
- * like `markGraphDirty` (never throws into the object close caller; graph staleness is
- * recoverable). Deleting the entity cascade-deletes any relation where it is an endpoint
- * (relations FK entities ON DELETE CASCADE); the explicit relations DELETE also covers a
- * relation whose OWN provenance is this object (defensive — every such edge has the object
- * as an endpoint today, so the cascade already covers it). DELETE fires no BEFORE
- * INSERT/UPDATE guard trigger.
- */
-export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectType, sourceObjectId) {
-    try {
-        assertTenantId('removeGraphEntitiesForObject', tenantId);
-        const db = openHippoDb(hippoRoot);
-        try {
-            db.exec('BEGIN IMMEDIATE');
-            db.prepare(`DELETE FROM relations WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
-                .run(tenantId, sourceObjectType, sourceObjectId);
-            db.prepare(`DELETE FROM entities WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
-                .run(tenantId, sourceObjectType, sourceObjectId);
-            db.exec('COMMIT');
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* preserve original throw */ }
-            throw e;
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    catch (err) {
-        log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-/**
- * Mark every pending queue item for a tenant with `id <= maxId` processed, in
- * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
- * is not involved (same as markExtractionProcessed). Returns the count marked.
- * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
- */
-export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
-    assertTenantId('markPendingProcessedUpTo', tenantId);
-    const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
-        const res = db.prepare(`
-      UPDATE graph_extraction_queue
-      SET status = 'processed', processed_at = ?
-      WHERE tenant_id = ? AND status = 'pending' AND id <= ?
-    `).run(now, tenantId, maxId);
-        return Number(res.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 //# sourceMappingURL=write.js.map

package/dist/hooks/codex-session.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { isJsonString } from '../json.js';
+import { isJsonString } from '../util/json.js';
 function collectFiles(dir) {
     if (!fs.existsSync(dir))
         return [];

package/dist/hooks/codex-wrapper.js

@@ -1,9 +1,11 @@
-import { envPath } from '../env.js';
+import { envPath } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { fileURLToPath } from 'url';
+import { PACKAGE_ROOT } from '../core/package-root.js';
+import { errorMessage, log } from '../util/log.js';
 import { HIPPO_CODEX_WRAPPER_MARKER, homeDir, codexHomeDir, ensureDir } from './shared.js';
-import { isJsonString } from '../json.js';
+import { isJsonString } from '../util/json.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 export function resolveCodexWrapperPaths() {
     const home = homeDir();
     const codexHome = codexHomeDir(home);
@@ -66,7 +68,7 @@ function isCodexWrapperMetadataValid(metadata) {
         isHippoCodexWrapperFile(metadata.commandPath));
 }
 function resolveHippoCliPath() {
-    return fileURLToPath(new URL('../bin/hippo.js', import.meta.url));
+    return path.join(PACKAGE_ROOT, 'bin', 'hippo.js');
 }
 function quoteForShell(value) {
     return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
@@ -152,26 +154,20 @@ export function detectRealCodexPath() {
     return null;
 }
 function writeExecutableFile(filePath, content) {
-    fs.writeFileSync(filePath, content, 'utf8');
+    writeFileAtomic(filePath, content);
     try {
         fs.chmodSync(filePath, 0o755);
     }
-    catch {
-        // chmod is best-effort on Windows
+    catch (err) {
+        // The mode bit means nothing on Windows; elsewhere a wrapper that is not executable breaks `codex`, so say so.
+        log.warn(`could not mark ${filePath} executable: ${errorMessage(err)}`);
     }
 }
 export function installCodexWrapper(realCodexPath) {
     const existingMetadata = readCodexWrapperMetadata();
     if (isCodexWrapperMetadataValid(existingMetadata) && !realCodexPath) {
         cleanupLegacyCodexPathWrappers(resolveCodexWrapperPaths());
-        return {
-            installed: true,
-            metadataPath: resolveCodexWrapperPaths().metadataPath,
-            realCodexPath: existingMetadata.realCodexPath,
-            commandPath: existingMetadata.commandPath,
-            backupPath: existingMetadata.backupPath,
-            installMode: existingMetadata.installMode,
-        };
+        return installResult(resolveCodexWrapperPaths().metadataPath, existingMetadata);
     }
     const resolvedRealCodexPath = realCodexPath ?? detectRealCodexPath();
     if (!resolvedRealCodexPath) {
@@ -200,10 +196,13 @@ export function installCodexWrapper(realCodexPath) {
         logFile: paths.logFile,
         installedAt: new Date().toISOString(),
     };
-    fs.writeFileSync(paths.metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf8');
+    writeFileAtomic(paths.metadataPath, JSON.stringify(metadata, null, 2) + '\n');
+    return installResult(paths.metadataPath, metadata);
+}
+function installResult(metadataPath, metadata) {
     return {
         installed: true,
-        metadataPath: paths.metadataPath,
+        metadataPath,
         realCodexPath: metadata.realCodexPath,
         commandPath: metadata.commandPath,
         backupPath: metadata.backupPath,

package/dist/hooks/copilot.d.ts

@@ -1,7 +1,4 @@
-import type { JsonObject } from '../working-memory.js';
-/** Copilot drops what a per-prompt hook prints, so per-task recall goes through the MCP tool the block names. */
-export declare const COPILOT_INSTRUCTIONS: string;
-export declare const VSCODE_INSTRUCTIONS: string;
+import type { JsonObject } from '../store/working-memory.js';
 /** The files hippo writes in one VS Code User folder. */
 export interface VscodePaths {
     readonly userDir: string;
@@ -30,8 +27,6 @@ export declare const VSCODE_MCP: McpHost;
 /** What to paste under the host's key when hippo cannot edit the file itself. */
 export declare function copilotMcpSnippet(host?: McpHost): string;
 export type McpMergeStatus = 'added' | 'present' | 'user-owned' | 'unreadable';
-/** Adds hippo's server and keeps every other key; a file hippo cannot parse, or a "hippo" key it did not write, stays as it is. */
-export declare function mergeMcpServer(file: string, host?: McpHost): McpMergeStatus;
 export type McpRemoveStatus = 'removed' | 'absent' | 'user-owned' | 'unreadable';
 /** Removes the "hippo" key only when hippo wrote it. */
 export declare function removeMcpServer(file: string, host?: McpHost): McpRemoveStatus;
@@ -42,8 +37,6 @@ export interface McpFailure {
 export declare function isMcpFailure(status: string | McpFailure): status is McpFailure;
 /** `kept`: a hippo block that is not the Copilot text (edited, or another agent's in a shared file); `unclosed`: a start marker with no end. */
 export type InstructionsInstallStatus = 'written' | 'present' | 'kept' | 'unclosed';
-/** Creates the file when missing; any block but hippo's own Copilot one, and a start marker with no end, leave the file as it is. */
-export declare function ensureInstructionsBlock(file: string): InstructionsInstallStatus;
 export type InstructionsRemoveStatus = 'removed' | 'absent' | 'kept' | 'unclosed';
 /** Splices out only hippo's own Copilot block and keeps every other byte; a file left with nothing but whitespace goes. */
 export declare function removeInstructionsBlock(file: string): InstructionsRemoveStatus;

package/dist/hooks/copilot.js

@@ -3,13 +3,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { isDeepStrictEqual } from 'node:util';
-import { readJsonFile } from '../json.js';
-import { HOOK_MARKERS, hippoBlock } from '../cli/hook-blocks.js';
-import { copilotHomeDir, isJsonObject, vscodeUserDirs } from './shared.js';
+import { readJsonFile, isJsonObjectLiteral } from '../util/json.js';
+import { HOOK_MARKERS, hippoBlock } from './hook-blocks.js';
+import { copilotHomeDir, vscodeUserDirs } from './shared.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 import { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from './json-hooks.js';
 const MCP_KEY = 'hippo';
 /** Copilot drops what a per-prompt hook prints, so per-task recall goes through the MCP tool the block names. */
-export const COPILOT_INSTRUCTIONS = `
+const COPILOT_INSTRUCTIONS = `
 ## Project Memory (Hippo)
 
 At the start of each task, call the \`hippo_recall\` tool with a short query that
@@ -44,7 +45,7 @@ before you finish.
 ];
 /** VS Code attaches a User `*.instructions.md` file to every chat request its `applyTo` glob matches. */
 const withApplyToAll = (text) => `---\napplyTo: "**"\n---\n${text}\n`;
-export const VSCODE_INSTRUCTIONS = withApplyToAll(COPILOT_INSTRUCTIONS);
+const VSCODE_INSTRUCTIONS = withApplyToAll(COPILOT_INSTRUCTIONS);
 function isHipposVscodeInstructions(text) {
     return SHIPPED_COPILOT_INSTRUCTIONS.some((shipped) => text === withApplyToAll(shipped));
 }
@@ -76,9 +77,10 @@ function hippoCommand() {
 export const COPILOT_CLI_MCP = { key: 'mcpServers', server: () => ({ type: 'local', command: hippoCommand(), args: ['mcp'], env: {}, tools: ['*'] }) };
 /** VS Code's mcp.json keeps stdio servers under "servers"; it has no "mcpServers" key. */
 export const VSCODE_MCP = { key: 'servers', server: () => ({ type: 'stdio', command: hippoCommand(), args: ['mcp'] }) };
-/** Only a server hippo wrote counts as hippo's: another command, other args, or any key or value setup does not write (an env you added) makes it the user's. */
+/** Only a server hippo wrote counts as hippo's: another command, other args, or
+ * any key or value setup does not write (an env you added) makes it the user's. */
 function isHipposServer(entry, host) {
-    if (!isJsonObject(entry) || !('command' in entry) || !('args' in entry))
+    if (!isJsonObjectLiteral(entry) || !('command' in entry) || !('args' in entry))
         return false;
     const ours = host.server();
     return Object.entries(entry).every(([key, value]) => (key === 'command' ? value === 'hippo' || value === 'hippo.cmd' : isDeepStrictEqual(value, ours[key])));
@@ -103,15 +105,15 @@ function readMcpConfig(file, host) {
                 return null;
         }
     }
-    if (!isJsonObject(config))
+    if (!isJsonObjectLiteral(config))
         return null;
     if (config[host.key] === undefined)
         config[host.key] = {};
     const servers = config[host.key];
-    return isJsonObject(servers) ? { config, servers } : null;
+    return isJsonObjectLiteral(servers) ? { config, servers } : null;
 }
 /** Adds hippo's server and keeps every other key; a file hippo cannot parse, or a "hippo" key it did not write, stays as it is. */
-export function mergeMcpServer(file, host = COPILOT_CLI_MCP) {
+function mergeMcpServer(file, host = COPILOT_CLI_MCP) {
     const read = readMcpConfig(file, host);
     if (read === null)
         return 'unreadable';
@@ -172,7 +174,7 @@ function withCopilotBlock(text, found) {
     return `${text}${text.endsWith('\n') ? '\n' : '\n\n'}${block}`;
 }
 /** Creates the file when missing; any block but hippo's own Copilot one, and a start marker with no end, leave the file as it is. */
-export function ensureInstructionsBlock(file) {
+function ensureInstructionsBlock(file) {
     const old = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
     const found = hippoBlock(old);
     if (found === null && old.includes(HOOK_MARKERS.start))
@@ -182,8 +184,7 @@ export function ensureInstructionsBlock(file) {
     const next = withCopilotBlock(old, found);
     if (next === old)
         return 'present';
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, next, 'utf8');
+    writeFileAtomic(file, next);
     return 'written';
 }
 /** `text` without the block and its markers, plus the line break after the end marker, else the one before the start marker. */
@@ -208,7 +209,7 @@ export function removeInstructionsBlock(file) {
     if (left.trim() === '')
         fs.rmSync(file);
     else
-        fs.writeFileSync(file, left, 'utf8');
+        writeFileAtomic(file, left);
     return 'removed';
 }
 /** The file is hippo's alone, so it is written whole; an earlier hippo text is upgraded, and any other text already there stays. */
@@ -220,8 +221,7 @@ export function ensureVscodeInstructions(file) {
         if (!isHipposVscodeInstructions(old))
             return 'kept';
     }
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, VSCODE_INSTRUCTIONS, 'utf8');
+    writeFileAtomic(file, VSCODE_INSTRUCTIONS);
     return 'written';
 }
 /** Deletes the file only when it still holds exactly what a hippo release wrote. */