@raidiant/notifai 10.1.7 → 11.0.2

package/dist/install-hooks.js

@@ -5,10 +5,11 @@ import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { atomicWriteFileSync } from './atomic-file.js';
 import { withTargetFileLock } from './file-lock.js';
 import { hookAdapterPath, hookHostPlatform, inspectHookAdapter, } from './hook-adapter.js';
-import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js';
-import { OPENCLAW_EVENTS, openclawHasGlobalEvidence, openclawPluginPath, openclawPluginTarget, } from './openclaw-plugin.js';
+import { OPENCODE_PLUGIN_FILENAME, opencodePluginPath, opencodePluginTarget, } from './opencode-plugin.js';
+import { OPENCLAW_EVENTS, legacyOpenclawProjectPluginPath, openclawHasGlobalEvidence, openclawPluginPath, openclawPluginTarget, } from './openclaw-plugin.js';
 import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js';
 import { accountHome } from './platform.js';
+import { sameLocalPath } from './local-path.js';
 import { NON_ROUTING_STOP_TIMEOUT_SECONDS, QUESTION_STOP_TIMEOUT_SECONDS, } from './question-timing.js';
 /**
  * The three joints the OpenCode plugin hooks into, as (harness event, the
@@ -142,6 +143,10 @@ export function buildHookConfig(options) {
                         command: hookCommand(adapterPath, 'session-start', options.harness, commandOptions),
                         // Activation is local context only: no config, credentials, or network.
                         timeout: 5,
+                        // Codex spills additionalContext above ~2,500 tokens to a preview
+                        // file. SessionStart may emit up to 24,000 bytes, so pass the full
+                        // context. Changing this field requires one `/hooks` re-approval.
+                        ...(options.harness === 'codex' ? { additionalContextLimit: 0 } : {}),
                     },
                 ],
             },
@@ -226,30 +231,48 @@ export function buildCursorHookConfig(options) {
     };
 }
 /**
- * Where each harness reads hooks from. Project installs deliberately target the
- * gitignored file where one exists: which devices a person wants their
- * questions pushed to is not a property of the repository.
+ * The one file each harness reads Notifai's lifecycle wiring from: the current
+ * User's account, in that harness's active home.
  */
-export function settingsFile(harness, global, cwd, env = process.env, platform = process.platform) {
+export function settingsFile(harness, env = process.env, platform = process.platform) {
     switch (harness) {
         // OpenCode has no settings document to merge into — its adapter is a
         // generated plugin module, so it owns a whole file instead.
         case 'opencode':
-            return opencodePluginPath(global, cwd, env, platform);
+            return opencodePluginPath(env, platform);
         case 'openclaw':
-            return openclawPluginPath(global, cwd, env, platform);
-        case 'cursor': {
-            const home = harnessAccountHome(env, platform);
-            return global
-                ? path.join(home, '.cursor', 'hooks.json')
-                : path.join(cwd, '.cursor', 'hooks.json');
-        }
+            return openclawPluginPath(env, platform);
+        case 'cursor':
+            return path.join(harnessAccountHome(env, platform), '.cursor', 'hooks.json');
         case 'claude-code':
-            return global
-                ? path.join(configHome(env, 'CLAUDE_CONFIG_DIR', '.claude', platform), 'settings.json')
-                : path.join(cwd, '.claude', 'settings.local.json');
+            return path.join(configHome(env, 'CLAUDE_CONFIG_DIR', '.claude', platform), 'settings.json');
         case 'codex':
-            return inspectCodexLayer(codexLayerPaths(global, cwd, env, platform)).writeTarget;
+            return inspectCodexLayer(codexMachineLayerPaths(env, platform)).writeTarget;
+        default:
+            return assertNeverHarness(harness);
+    }
+}
+/**
+ * Files an older build may have left inside this Project, which Notifai now
+ * only ever reads in order to remove.
+ *
+ * Nothing installs here any more. Every path is still enumerated because a
+ * leftover Project-scoped handler keeps firing beside the Machine one, and
+ * silently leaving it would be exactly the duplicate-routing defect dropping
+ * the second scope was meant to end.
+ */
+export function legacyProjectHookFiles(harness, cwd) {
+    switch (harness) {
+        case 'opencode':
+            return [path.join(cwd, '.opencode', 'plugins', OPENCODE_PLUGIN_FILENAME)];
+        case 'openclaw':
+            return [legacyOpenclawProjectPluginPath(cwd)];
+        case 'cursor':
+            return [path.join(cwd, '.cursor', 'hooks.json')];
+        case 'claude-code':
+            return [path.join(cwd, '.claude', 'settings.local.json')];
+        case 'codex':
+            return codexLegacyProjectLayers(cwd).flatMap((paths) => [paths.hooksJson, paths.configToml]);
         default:
             return assertNeverHarness(harness);
     }
@@ -288,8 +311,7 @@ export function codexProjectRoot(cwd) {
     try {
         if (statSync(entry).isDirectory())
             return path.dirname(entry);
-        const linked = worktreeGitDir(entry);
-        return linked === null ? cwd : path.dirname(commonGitDir(linked));
+        return linkedWorktreeMainRoot(entry) ?? cwd;
     }
     catch {
         // An unreadable or exotic checkout is not worth failing an install over;
@@ -297,29 +319,6 @@ export function codexProjectRoot(cwd) {
         return cwd;
     }
 }
-/**
- * The `.codex` directory that has to exist for Codex to load project hooks at
- * all, or null when nothing extra is needed.
- *
- * Codex splits the two halves of "which project am I in": it discovers the
- * project layer by walking up from cwd for a `.codex` directory, but resolves
- * the hook file inside that layer against the main repository. In an ordinary
- * checkout both land on the same directory and the split is invisible. In a
- * worktree they diverge, and writing only the main repository's file leaves it
- * unread — Codex never looks, because nothing at or above cwd told it there was
- * a project layer to load. Proven 2026-08-03: with cwd in a worktree, an *empty*
- * `.codex` directory there was the difference between the main repository's
- * handler running and nothing running.
- */
-export function codexLayerDir(cwd) {
-    const entry = findGitEntry(cwd);
-    if (entry === null)
-        return null;
-    const worktreeRoot = path.dirname(entry);
-    if (path.resolve(worktreeRoot) === path.resolve(codexProjectRoot(cwd)))
-        return null;
-    return path.join(worktreeRoot, '.codex');
-}
 /** The nearest `.git` at or above `from`, or null outside a repository. */
 function findGitEntry(from) {
     let dir = path.resolve(from);
@@ -333,22 +332,58 @@ function findGitEntry(from) {
         dir = parent;
     }
 }
-/** `.git` in a linked worktree is a file naming that worktree's git directory. */
-function worktreeGitDir(file) {
-    const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(file, 'utf8'));
-    if (match === null)
-        return null;
-    return path.resolve(path.dirname(file), match[1].trim());
-}
 /**
- * A worktree's git directory records the shared one in `commondir`; that shared
- * directory is the main repository's `.git`, whose parent is its root.
+ * Resolve the main checkout only from Git's reciprocal linked-worktree
+ * metadata. A repository can contain an arbitrary `.git` file, so its one-way
+ * `gitdir`/`commondir` claims are not authority to write outside the Project.
  */
-function commonGitDir(gitDir) {
-    const marker = path.join(gitDir, 'commondir');
-    if (!existsSync(marker))
-        return gitDir;
-    return path.resolve(gitDir, readFileSync(marker, 'utf8').trim());
+function linkedWorktreeMainRoot(gitFile) {
+    if (!isOwnedRegularFile(gitFile))
+        return null;
+    const gitdirClaim = readPathMarker(gitFile, /^gitdir:[ \t]+([^\r\n]+)\r?\n?$/);
+    if (gitdirClaim === null)
+        return null;
+    const gitDir = path.resolve(path.dirname(gitFile), gitdirClaim);
+    if (!isOwnedDirectory(gitDir))
+        return null;
+    const commonClaim = readPathMarker(path.join(gitDir, 'commondir'), /^([^\r\n]+)\r?\n?$/);
+    const backlinkClaim = readPathMarker(path.join(gitDir, 'gitdir'), /^([^\r\n]+)\r?\n?$/);
+    if (commonClaim === null || backlinkClaim === null)
+        return null;
+    const commonDir = path.resolve(gitDir, commonClaim);
+    const backlink = path.resolve(gitDir, backlinkClaim);
+    const worktreesDir = path.join(commonDir, 'worktrees');
+    if (path.basename(commonDir).toLowerCase() !== '.git' ||
+        !isOwnedDirectory(commonDir) ||
+        !isOwnedDirectory(worktreesDir) ||
+        !sameLocalPath(path.dirname(realpathSync(gitDir)), realpathSync(worktreesDir)) ||
+        !sameLocalPath(backlink, gitFile)) {
+        return null;
+    }
+    const mainRoot = path.dirname(commonDir);
+    return isOwnedDirectory(mainRoot) ? mainRoot : null;
+}
+function readPathMarker(file, pattern) {
+    if (!isOwnedRegularFile(file))
+        return null;
+    const match = pattern.exec(readFileSync(file, 'utf8'));
+    const claim = match?.[1]?.trim();
+    return claim === undefined || claim === '' ? null : claim;
+}
+function isOwnedRegularFile(file) {
+    return isOwnedEntry(file, 'file');
+}
+function isOwnedDirectory(file) {
+    return isOwnedEntry(file, 'directory');
+}
+function isOwnedEntry(file, kind) {
+    const metadata = lstatSync(file);
+    if (metadata.isSymbolicLink())
+        return false;
+    if (kind === 'file' ? !metadata.isFile() : !metadata.isDirectory())
+        return false;
+    const uid = process.getuid?.();
+    return uid === undefined || metadata.uid === uid;
 }
 /**
  * Harness-specific home variables relocate the whole active harness home.
@@ -379,54 +414,75 @@ export function configHome(env, variable, fallback, platform = process.platform)
 export function codexGlobalDir(env = process.env, platform = process.platform) {
     return configHome(env, 'CODEX_HOME', '.codex', platform);
 }
-/** The two files Codex will look at for one config layer. */
-export function codexLayerPaths(global, cwd, env = process.env, platform = process.platform) {
-    const dir = global
-        ? codexGlobalDir(env, platform)
-        : path.join(codexProjectRoot(cwd), '.codex');
+function codexLayerPathsIn(dir) {
     return {
         dir,
         hooksJson: path.join(dir, 'hooks.json'),
         configToml: path.join(dir, 'config.toml'),
     };
 }
+/** The two files Codex will look at in the Machine layer Notifai installs into. */
+export function codexMachineLayerPaths(env = process.env, platform = process.platform) {
+    return codexLayerPathsIn(codexGlobalDir(env, platform));
+}
 /**
- * Where Notifai writes in this Codex layer: wherever Notifai already is, then
- * whichever single hook representation the layer already uses, and inline
- * `config.toml` for a hook-empty or already-mixed layer.
+ * Project layers an older build may have written into, for removal only.
  *
- * Codex supports `hooks.json` and inline `[hooks]` side by side, loads both,
- * and runs every matching handler. Reusing the one populated representation is
- * the generic layer contract: it avoids creating Codex's dual-representation
- * warning and, for a managed layer, writes through the same authority that
- * persists the layer rather than a sibling file it may regenerate away.
+ * Codex resolves a project hook file against the main repository, so a linked
+ * worktree has two candidate directories: the main checkout's `.codex`, which
+ * Codex reads, and the worktree's own, which older builds sometimes created and
+ * Codex never reads. Both are legacy residue and both are enumerated here.
+ */
+export function codexLegacyProjectLayers(cwd) {
+    const dirs = [path.join(codexProjectRoot(cwd), '.codex')];
+    const entry = findGitEntry(cwd);
+    if (entry !== null) {
+        const worktreeLayer = path.join(path.dirname(entry), '.codex');
+        if (!dirs.some((dir) => path.resolve(dir) === path.resolve(worktreeLayer))) {
+            dirs.push(worktreeLayer);
+        }
+    }
+    return dirs.map(codexLayerPathsIn);
+}
+/**
+ * Where Notifai writes in this Codex layer. An existing single Notifai
+ * representation is stable: upgrades refresh it in place because Codex keys
+ * approval by both handler identity and source path. Only a fresh installation
+ * chooses between `hooks.json` and inline `config.toml`.
  *
- * Staying put where Notifai already is also keeps reinstalls idempotent and
- * preserves the `[hooks.state]` trust hash, which Codex keys by file path and
- * handler index. `[hooks.state]` is the trust store, not a hook definition, so
- * it does not count as a representation.
+ * `config.toml` is the User's whole Codex configuration and Codex rewrites it
+ * itself for `[hooks.state]`; keeping Notifai out of it bounds the blast radius
+ * to hooks, removes a second writer racing those trust records, and replaces
+ * TOML splicing with the same JSON merge Claude Code uses. Joining an inline
+ * layer that already has the User's handlers is the one exception, and it
+ * exists only so Codex never prints its dual-representation warning.
+ *
+ * A fresh installation uses `hooks.json` unless foreign inline handlers make
+ * `config.toml` the layer's established representation. `[hooks.state]` is the
+ * trust store rather than a hook definition, so it never counts as a
+ * representation and is preserved through every write.
  */
 export function inspectCodexLayer(paths) {
     const jsonDocument = tryLoadSettings(paths.hooksJson);
     const tomlDocument = tryLoadSettings(paths.configToml);
-    const jsonEvents = hookEventNames(jsonDocument?.hooks);
-    const tomlEvents = hookEventNames(tomlDocument?.hooks);
     const ourJsonEvents = ourHandlerEvents(jsonDocument);
     const ourTomlEvents = ourHandlerEvents(tomlDocument);
-    const writeTarget = ourJsonEvents.length > 0 && ourTomlEvents.length === 0
-        ? paths.hooksJson
-        : ourTomlEvents.length > 0
-            ? paths.configToml
-            : jsonEvents.length > 0 && tomlEvents.length === 0
-                ? paths.hooksJson
-                : paths.configToml;
+    const foreignTomlHooks = tomlDocument !== null &&
+        locateAllHandlers(tomlDocument).some((handler) => !isNotifaiCommand(handler.command));
     return {
         paths,
-        jsonEvents,
-        tomlEvents,
+        jsonEvents: hookEventNames(jsonDocument?.hooks),
+        tomlEvents: hookEventNames(tomlDocument?.hooks),
         ourJsonEvents,
         ourTomlEvents,
-        writeTarget,
+        foreignTomlHooks,
+        writeTarget: ourTomlEvents.length > 0 && ourJsonEvents.length === 0
+            ? paths.configToml
+            : ourJsonEvents.length > 0 && ourTomlEvents.length === 0
+                ? paths.hooksJson
+                : foreignTomlHooks
+                    ? paths.configToml
+                    : paths.hooksJson,
     };
 }
 /**
@@ -436,15 +492,15 @@ export function inspectCodexLayer(paths) {
 export function withCodexLayerTransaction(paths, action) {
     return withTargetFileLock(paths.configToml, () => action(inspectCodexLayer(paths)));
 }
-/** Every file in this layer Codex might already be reading hooks from. */
-export function hookDefinitionFiles(harness, global, cwd, env = process.env, platform = process.platform) {
+/** Every Machine-layer file this harness might already be reading hooks from. */
+export function machineHookFiles(harness, env = process.env, platform = process.platform) {
     if (harness !== 'codex')
-        return [settingsFile(harness, global, cwd, env, platform)];
-    const paths = codexLayerPaths(global, cwd, env, platform);
+        return [settingsFile(harness, env, platform)];
+    const paths = codexMachineLayerPaths(env, platform);
     return [paths.hooksJson, paths.configToml];
 }
 /**
- * Layers where *Notifai* is installed in both Codex representations.
+ * The Machine layer with *Notifai* installed in both Codex representations.
  *
  * A layer that uses `hooks.json` and inline `[hooks]` at once is not by itself
  * a Notifai fault: Codex supports both, loads both, runs every matching
@@ -460,23 +516,21 @@ export function hookDefinitionFiles(harness, global, cwd, env = process.env, pla
  * the other one. Uninstall strips Notifai from both files, so the remedy is
  * exact — and it never touches a foreign handler.
  */
-export function codexRepresentationProblems(cwd, env = process.env, platform = process.platform) {
-    return [false, true].flatMap((global) => {
-        const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env, platform));
-        if (layer.ourJsonEvents.length === 0 || layer.ourTomlEvents.length === 0)
-            return [];
-        const doubled = layer.ourJsonEvents.filter((event) => layer.ourTomlEvents.includes(event));
-        const consequence = doubled.length > 0
-            ? `Codex runs every matching handler, so this layer notifies twice per turn for ${doubled.join(', ')}`
-            : `Codex runs both files, so this layer's Notifai handlers are split between them (${[...new Set([...layer.ourJsonEvents, ...layer.ourTomlEvents])].join(', ')}) and the next install refreshes only one file`;
-        const scope = global ? ' --global' : '';
-        return [
-            `Notifai hooks are installed in both ${layer.paths.hooksJson} and ${layer.paths.configToml}; ${consequence}. Run \`notifai hooks uninstall --harness codex${scope}\` and then \`notifai hooks install --harness codex${scope}\` to leave exactly one copy; foreign hooks in either file are left alone.`,
-        ];
-    });
+export function codexRepresentationProblems(env = process.env, platform = process.platform) {
+    const layer = inspectCodexLayer(codexMachineLayerPaths(env, platform));
+    if (layer.ourJsonEvents.length === 0 || layer.ourTomlEvents.length === 0)
+        return [];
+    const doubled = layer.ourJsonEvents.filter((event) => layer.ourTomlEvents.includes(event));
+    const consequence = doubled.length > 0
+        ? `Codex runs every matching handler, so this layer notifies twice per turn for ${doubled.join(', ')}`
+        : `Codex runs both files, so this layer's Notifai handlers are split between them (${[...new Set([...layer.ourJsonEvents, ...layer.ourTomlEvents])].join(', ')}) and the next install refreshes only one file`;
+    return [
+        `Notifai hooks are installed in both ${layer.paths.hooksJson} and ${layer.paths.configToml}; ${consequence}. Run \`notifai hooks uninstall --harness codex\` and then \`notifai hooks install --harness codex\` to leave exactly one copy; foreign hooks in either file are left alone.`,
+    ];
 }
 /**
- * Layers where Notifai and someone else each own one Codex representation.
+ * The Machine layer where Notifai and someone else each own one Codex
+ * representation.
  *
  * This is not a fault and never fails a check. Codex loads `hooks.json` and
  * inline `[hooks]` together and runs every matching handler, so both sets fire
@@ -485,25 +539,23 @@ export function codexRepresentationProblems(cwd, env = process.env, platform = p
  * Notifai's, which is not, and that Notifai will not touch the one it does not
  * own. Saying nothing here is what made the warning look like Notifai's bug.
  */
-export function codexCoexistenceNotes(cwd, env = process.env, platform = process.platform) {
-    return [false, true].flatMap((global) => {
-        const layer = inspectCodexLayer(codexLayerPaths(global, cwd, env, platform));
-        const inJson = layer.ourJsonEvents.length > 0;
-        const inToml = layer.ourTomlEvents.length > 0;
-        if (inJson === inToml)
-            return [];
-        const ours = inJson ? layer.paths.hooksJson : layer.paths.configToml;
-        const theirs = inJson ? layer.paths.configToml : layer.paths.hooksJson;
-        const theirEvents = inJson ? layer.tomlEvents : layer.jsonEvents;
-        if (theirEvents.length === 0)
-            return [];
-        const stop = theirEvents.includes('Stop')
-            ? " That file's Stop handler can end a turn before Notifai's answer arrives, because Codex lets any Stop handler stop continuation."
-            : '';
-        return [
-            `Notifai's Codex hooks are in ${ours}. ${theirs} defines hooks Notifai does not own (${theirEvents.join(', ')}) and Notifai will not modify it. Codex loads both files and runs every matching handler, so each set fires exactly once; its "prefer one representation per layer" startup warning is reporting that, not a Notifai fault.${stop}`,
-        ];
-    });
+export function codexCoexistenceNotes(env = process.env, platform = process.platform) {
+    const layer = inspectCodexLayer(codexMachineLayerPaths(env, platform));
+    const inJson = layer.ourJsonEvents.length > 0;
+    const inToml = layer.ourTomlEvents.length > 0;
+    if (inJson === inToml)
+        return [];
+    const ours = inJson ? layer.paths.hooksJson : layer.paths.configToml;
+    const theirs = inJson ? layer.paths.configToml : layer.paths.hooksJson;
+    const theirEvents = inJson ? layer.tomlEvents : layer.jsonEvents;
+    if (theirEvents.length === 0)
+        return [];
+    const stop = theirEvents.includes('Stop')
+        ? " That file's Stop handler can end a turn before Notifai's answer arrives, because Codex lets any Stop handler stop continuation."
+        : '';
+    return [
+        `Notifai's Codex hooks are in ${ours}. ${theirs} defines hooks Notifai does not own (${theirEvents.join(', ')}) and Notifai will not modify it. Codex loads both files and runs every matching handler, so each set fires exactly once; its "prefer one representation per layer" startup warning is reporting that, not a Notifai fault.${stop}`,
+    ];
 }
 /**
  * What `CODEX_HOME` is doing to this shell, when it is doing anything.
@@ -679,7 +731,16 @@ export function removeCursorHooks(existing, scriptPath) {
         if (foreign.length > 0)
             hooks[event] = foreign;
     }
-    return { document: { ...existing, version: 1, hooks }, added: [], replaced, removed: [] };
+    const document = { ...existing };
+    if (Object.keys(hooks).length > 0)
+        document.hooks = hooks;
+    else
+        delete document.hooks;
+    // `version` is Cursor's schema marker, which Notifai writes only because it
+    // is writing hooks. Alone it is residue, not settings.
+    if (Object.keys(document).length === 1 && document.version !== undefined)
+        delete document.version;
+    return { document, added: [], replaced, removed: [] };
 }
 function readSettings(file) {
     if (!existsSync(file))
@@ -794,7 +855,10 @@ export function applyPlan(file, document) {
     const body = isTomlSettingsPath(file)
         ? tomlBody(file, document)
         : `${JSON.stringify(document, null, 2)}\n`;
-    if ((path.basename(file) === 'hooks.json' && isEmptyJsonDocument(body)) ||
+    // A document with nothing left in it is a file Notifai created and has just
+    // emptied. Keeping it would leave `{}` behind as the visible residue of an
+    // uninstall; a file that still holds anything of the User's is never empty.
+    if ((!isTomlSettingsPath(file) && isEmptyJsonDocument(body)) ||
         (isTomlSettingsPath(file) && body.trim() === '')) {
         if (existsSync(file))
             rmSync(file, { force: true });
@@ -982,10 +1046,16 @@ function canonicalValue(value) {
 }
 /**
  * Best-effort mirror of the identity current Codex builds compare with
- * `hooks.state.*.trusted_hash`. This persisted format is diagnostic evidence,
- * not an API: Codex's `/hooks` UI remains authoritative and Notifai never
- * writes the trust store.
+ * `hooks.state.*.trusted_hash`. Codex hashes `type`, `command`, `timeout`,
+ * `async`, `statusMessage`, and `additionalContextLimit` (omitting the 2,500
+ * default). This persisted format is diagnostic evidence, not an API: Codex's
+ * `/hooks` UI remains authoritative and Notifai never writes the trust store.
+ */
+/**
+ * Codex's default additionalContext spill threshold, in approximate tokens.
+ * Codex strips this value before hashing, so an explicit 2,500 matches omit.
  */
+const CODEX_DEFAULT_ADDITIONAL_CONTEXT_LIMIT = 2_500;
 export function codexHookIdentityHash(handler) {
     const command = {
         type: 'command',
@@ -993,6 +1063,10 @@ export function codexHookIdentityHash(handler) {
         timeout: Math.max(1, handler.timeout ?? 600),
         async: handler.async ?? false,
         ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
+        ...(handler.additionalContextLimit === undefined
+            || handler.additionalContextLimit === CODEX_DEFAULT_ADDITIONAL_CONTEXT_LIMIT
+            ? {}
+            : { additionalContextLimit: handler.additionalContextLimit }),
     };
     const normalized = canonicalValue({
         event_name: codexEventName(handler.event),
@@ -1096,92 +1170,105 @@ export function codexTrustProblems(installations, env = process.env) {
 function isNotifaiCommand(command) {
     return / hook (session-start|subagent-start|activation-stop|user-prompt-submit|stop|session-end)\b/.test(command);
 }
-/** Every place either harness would read a Notifai handler from. */
-export function findInstallations(cwd, env = process.env, adapterHome, platform = process.platform) {
+/**
+ * The one Machine installation each harness would read a Notifai handler from.
+ */
+export function findInstallations(env = process.env, adapterHome, platform = process.platform) {
+    return HOOK_INSTALLABLE_HARNESSES.flatMap((harness) => collectInstallations(harness, machineHookFiles(harness, env, platform), adapterHome, platform));
+}
+/**
+ * Notifai handlers a previous build left in Project-scoped files.
+ *
+ * These are never an install target and never a fallback: they are residue to
+ * report and remove once the Machine installation is proven current. Foreign
+ * handlers sharing those files are not returned and are never touched.
+ */
+export function findLegacyProjectInstallations(cwd, env = process.env, adapterHome, platform = process.platform) {
+    const machine = new Set(HOOK_INSTALLABLE_HARNESSES.flatMap((harness) => machineHookFiles(harness, env, platform).map((file) => path.resolve(file))));
+    return HOOK_INSTALLABLE_HARNESSES.flatMap((harness) => collectInstallations(harness, 
+    // A Project checkout that happens to be the harness home would otherwise
+    // report the Machine installation as legacy residue and delete it.
+    legacyProjectHookFiles(harness, cwd).filter((file) => !machine.has(path.resolve(file))), adapterHome, platform));
+}
+function collectInstallations(harness, files, adapterHome, platform) {
     const nodePath = inspectHookAdapter(adapterHome, platform).target?.execPath;
     const commandOptions = {
         platform,
         ...(nodePath === undefined ? {} : { nodePath }),
     };
     const found = [];
-    for (const harness of HOOK_INSTALLABLE_HARNESSES) {
-        for (const global of [false, true]) {
-            const files = hookDefinitionFiles(harness, global, cwd, env, platform);
-            for (const file of files) {
-                if (!existsSync(file))
-                    continue;
-                // OpenCode's adapter is a plugin module, not a settings document, so it
-                // is reported as one installation covering all three events rather than
-                // parsed for handlers.
-                if (harness === 'opencode' || harness === 'openclaw') {
-                    let source;
-                    try {
-                        source = readOwnedRegularFile(file);
-                    }
-                    catch {
-                        continue;
-                    }
-                    const target = harness === 'openclaw' ? openclawPluginTarget(source) : opencodePluginTarget(source);
-                    if (target === null)
-                        continue;
-                    const label = harness === 'openclaw' ? 'OpenClaw' : 'OpenCode';
-                    const problems = [
-                        ...(!target.current
-                            ? [`obsolete ${label} event wiring; rerun \`notifai hooks install --harness ${harness}\``]
-                            : []),
-                        ...(target.adapter !== hookAdapterPath(adapterHome)
-                            ? [
-                                `${label} still names a mutable CLI or runtime path; rerun \`notifai hooks install --harness ${harness}\``,
-                            ]
-                            : []),
-                    ];
-                    const events = harness === 'openclaw' ? OPENCLAW_EVENTS : OPENCODE_EVENTS;
-                    found.push({
-                        harness,
-                        file,
-                        global,
-                        ...(problems.length > 0 ? { problems } : {}),
-                        handlers: events.map(([event, hookEvent]) => ({
-                            event,
-                            groupIndex: 0,
-                            handlerIndex: 0,
-                            command: hookCommand(target.adapter, hookEvent, harness, {
-                                ...commandOptions,
-                                ...(target.nodePath === undefined ? {} : { nodePath: target.nodePath }),
-                            }),
-                            ...(target.timeoutSeconds === undefined ? {} : { timeout: target.timeoutSeconds }),
-                        })),
-                    });
-                    continue;
-                }
-                if (harness === 'cursor') {
-                    let document;
-                    try {
-                        document = readCursorSettings(file);
-                    }
-                    catch {
-                        continue;
-                    }
-                    const handlers = locateCursorHandlers(document);
-                    if (handlers.length > 0) {
-                        const problems = harnessMarkerProblems(harness, handlers, adapterHome, commandOptions);
-                        found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) });
-                    }
-                    continue;
-                }
-                let document;
-                try {
-                    document = loadSettings(file);
-                }
-                catch {
-                    continue;
-                }
-                const handlers = locateHandlers(document);
-                if (handlers.length > 0) {
-                    const problems = harnessMarkerProblems(harness, handlers, adapterHome, commandOptions);
-                    found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) });
-                }
+    for (const file of files) {
+        if (!existsSync(file))
+            continue;
+        // OpenCode's adapter is a plugin module, not a settings document, so it
+        // is reported as one installation covering all three events rather than
+        // parsed for handlers.
+        if (harness === 'opencode' || harness === 'openclaw') {
+            let source;
+            try {
+                source = readOwnedRegularFile(file);
+            }
+            catch {
+                continue;
+            }
+            const target = harness === 'openclaw' ? openclawPluginTarget(source) : opencodePluginTarget(source);
+            if (target === null)
+                continue;
+            const label = harness === 'openclaw' ? 'OpenClaw' : 'OpenCode';
+            const problems = [
+                ...(!target.current
+                    ? [`obsolete ${label} event wiring; rerun \`notifai hooks install --harness ${harness}\``]
+                    : []),
+                ...(target.adapter !== hookAdapterPath(adapterHome)
+                    ? [
+                        `${label} still names a mutable CLI or runtime path; rerun \`notifai hooks install --harness ${harness}\``,
+                    ]
+                    : []),
+            ];
+            const events = harness === 'openclaw' ? OPENCLAW_EVENTS : OPENCODE_EVENTS;
+            found.push({
+                harness,
+                file,
+                ...(problems.length > 0 ? { problems } : {}),
+                handlers: events.map(([event, hookEvent]) => ({
+                    event,
+                    groupIndex: 0,
+                    handlerIndex: 0,
+                    command: hookCommand(target.adapter, hookEvent, harness, {
+                        ...commandOptions,
+                        ...(target.nodePath === undefined ? {} : { nodePath: target.nodePath }),
+                    }),
+                    ...(target.timeoutSeconds === undefined ? {} : { timeout: target.timeoutSeconds }),
+                })),
+            });
+            continue;
+        }
+        if (harness === 'cursor') {
+            let document;
+            try {
+                document = readCursorSettings(file);
+            }
+            catch {
+                continue;
             }
+            const handlers = locateCursorHandlers(document);
+            if (handlers.length > 0) {
+                const problems = harnessMarkerProblems(harness, handlers, adapterHome, commandOptions);
+                found.push({ harness, file, handlers, ...(problems.length > 0 ? { problems } : {}) });
+            }
+            continue;
+        }
+        let document;
+        try {
+            document = loadSettings(file);
+        }
+        catch {
+            continue;
+        }
+        const handlers = locateHandlers(document);
+        if (handlers.length > 0) {
+            const problems = harnessMarkerProblems(harness, handlers, adapterHome, commandOptions);
+            found.push({ harness, file, handlers, ...(problems.length > 0 ? { problems } : {}) });
         }
     }
     return found;
@@ -1231,6 +1318,9 @@ function locateAllHandlers(document) {
                     ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
                     ...(handler.async === undefined ? {} : { async: handler.async }),
                     ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
+                    ...(typeof handler.additionalContextLimit === 'number'
+                        ? { additionalContextLimit: handler.additionalContextLimit }
+                        : {}),
                 });
             });
         });