@raidiant/notifai 11.0.6 → 11.2.0

package/dist/install-hooks.js

@@ -5,22 +5,13 @@ 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 { OPENCODE_PLUGIN_FILENAME, opencodePluginPath, opencodePluginTarget, } from './opencode-plugin.js';
-import { OPENCLAW_EVENTS, legacyOpenclawProjectPluginPath, openclawHasGlobalEvidence, openclawPluginPath, openclawPluginTarget, } from './openclaw-plugin.js';
+import { OPENCODE_PLUGIN_FILENAME, opencodeConfigDir, opencodePluginPath, opencodePluginTarget, } from './opencode-plugin.js';
+import { legacyOpenclawProjectPluginPath, openclawHasGlobalEvidence, openclawPluginPath, openclawPluginTarget, } from './openclaw-plugin.js';
 import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js';
+import { HOOK_EVENT_COMMAND_RE, HOOK_EVENT_PATTERN, HOOK_EVENT_TABLE, OPENCLAW_EVENTS, OPENCODE_EVENTS, } from './hook-events.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
- * `notifai hook` event it runs). The plugin is a module and has no settings
- * entries to read, so `findInstallations` reconstructs its handlers from this.
- */
-const OPENCODE_EVENTS = [
-    ['UserPromptSubmit', 'user-prompt-submit'],
-    ['Stop', 'stop'],
-    ['SessionEnd', 'session-end'],
-];
 /**
  * The command each hook runs. Harness definitions know only the stable
  * user-level adapter. Mutable Node, package-manager, version, and checkout
@@ -98,30 +89,47 @@ export { QUESTION_STOP_TIMEOUT_SECONDS } from './question-timing.js';
 /**
  * Whether this harness's Stop handler runs detached from the turn.
  *
- * The installer and doctor share this predicate so they agree whether Claude
- * runs out of band. Owner lifetime is route-neutral and lives in
+ * The installer and doctor share this predicate so they agree which harnesses
+ * run out of band. Owner lifetime is route-neutral and lives in
  * `question-timing.ts`.
+ *
+ * Codex is detached on every platform because its delivery route is a write to
+ * the thread's own durable inbox rather than this hook's stdout: there is no
+ * continuation to keep a turn open for, and the queue has no platform
+ * dependency to gate on. Claude Code still needs its turn held on Windows,
+ * where no inbox socket exists.
  */
 export function stopHandlerIsDetached(harness, platform) {
+    if (harness === 'codex')
+        return true;
     return harness === 'claude-code' && hookHostPlatform(platform) === 'posix';
 }
 /**
  * The turn-end handler, whose shape is the whole per-harness difference.
  *
- * Claude Code takes the answer over its own inbox socket, so its Stop hook is
- * `async: true`: it returns immediately, the terminal is never held, and the
- * waiter finishes out of band. Codex and Claude on Windows block and print a
- * continuation to stdout. Every Question Routing owner declares the same
- * complete-window timeout; changing Codex's definition requires one explicit
- * trust approval.
+ * Claude Code takes the answer over its own inbox socket and Codex takes it
+ * through its thread's durable inbox, so both Stop hooks are `async: true`:
+ * they return immediately, the terminal is never held, and the waiter finishes
+ * out of band. Only Claude on Windows still blocks and prints a continuation to
+ * stdout, because no inbox socket exists there. Every Question Routing owner
+ * declares the same complete-window timeout, because the detached waiter must
+ * outlive the answer window in every case; what changed for Codex is that a
+ * short or missing timeout no longer truncates a held *turn*. Blocking hosts
+ * also set `statusMessage` so the held turn is not mistaken for a hang.
  */
+export const BLOCKING_STOP_STATUS_MESSAGE = 'Notifai: waiting for your answer';
 function stopHandler(adapterPath, harness, options) {
     const command = hookCommand(adapterPath, 'stop', harness, options);
     if (stopHandlerIsDetached(harness, options.platform)) {
         return { type: 'command', command, timeout: QUESTION_STOP_TIMEOUT_SECONDS, async: true };
     }
     if (harness === 'codex' || harness === 'claude-code') {
-        return { type: 'command', command, timeout: QUESTION_STOP_TIMEOUT_SECONDS };
+        return {
+            type: 'command',
+            command,
+            timeout: QUESTION_STOP_TIMEOUT_SECONDS,
+            statusMessage: BLOCKING_STOP_STATUS_MESSAGE,
+        };
     }
     return { type: 'command', command, timeout: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS };
 }
@@ -134,97 +142,44 @@ function commandOptionsFrom(options) {
 export function buildHookConfig(options) {
     const { adapterPath } = options;
     const commandOptions = commandOptionsFrom(options);
-    return {
-        SessionStart: [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand(adapterPath, 'session-start', options.harness, commandOptions),
-                        // Activation is local context only: no config, credentials, or network.
-                        timeout: 5,
-                    },
-                ],
-            },
-        ],
-        SubagentStart: [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand(adapterPath, 'subagent-start', options.harness, commandOptions),
-                        timeout: 5,
-                    },
-                ],
-            },
-        ],
-        UserPromptSubmit: [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookCommand(adapterPath, 'user-prompt-submit', options.harness, commandOptions),
-                        // Claude Code defaults UserPromptSubmit to 30s. Choose a shorter
-                        // explicit budget so a slow network cannot delay the user's prompt.
-                        timeout: 15,
-                    },
-                ],
-            },
-        ],
-        Stop: [{ hooks: [stopHandler(adapterPath, options.harness, commandOptions)] }],
-        SessionEnd: [
+    const hooks = Object.create(null);
+    for (const row of HOOK_EVENT_TABLE) {
+        if (row.document === null)
+            continue;
+        if (row.notifai === 'stop') {
+            hooks[row.document] = [{ hooks: [stopHandler(adapterPath, options.harness, commandOptions)] }];
+            continue;
+        }
+        hooks[row.document] = [
             {
                 hooks: [
                     {
                         type: 'command',
-                        command: hookCommand(adapterPath, 'session-end', options.harness, commandOptions),
-                        // Both harnesses give SessionEnd a ~1-3s budget, so this handler
-                        // only touches local state.
-                        timeout: 3,
+                        command: hookCommand(adapterPath, row.notifai, options.harness, commandOptions),
+                        timeout: row.timeoutSeconds,
                     },
                 ],
             },
-        ],
-    };
+        ];
+    }
+    return hooks;
 }
 /** Cursor's native schema is flat and uses lower-camel lifecycle event names. */
 export function buildCursorHookConfig(options) {
     const commandOptions = commandOptionsFrom(options);
-    return {
-        sessionStart: [
-            {
-                command: hookCommand(options.adapterPath, 'session-start', 'cursor', commandOptions),
-                // Activation only emits local context and must not depend on setup.
-                timeout: 5,
-            },
-        ],
-        beforeSubmitPrompt: [
-            {
-                command: hookCommand(options.adapterPath, 'user-prompt-submit', 'cursor', commandOptions),
-                timeout: 15,
-            },
-        ],
-        stop: [
-            {
-                command: hookCommand(options.adapterPath, 'activation-stop', 'cursor', commandOptions),
-                timeout: 5,
-                loop_limit: 1,
-            },
-            {
-                command: hookCommand(options.adapterPath, 'stop', 'cursor', commandOptions),
-                timeout: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
-                // A continuation may register a real follow-up question. Match the
-                // session-state cap so those chains are useful but never unbounded.
-                loop_limit: 3,
-            },
-        ],
-        sessionEnd: [
-            {
-                command: hookCommand(options.adapterPath, 'session-end', 'cursor', commandOptions),
-                timeout: 3,
-            },
-        ],
-    };
+    const hooks = Object.create(null);
+    for (const row of HOOK_EVENT_TABLE) {
+        if (row.cursor === null)
+            continue;
+        const handler = {
+            command: hookCommand(options.adapterPath, row.notifai, 'cursor', commandOptions),
+            timeout: row.notifai === 'stop' ? NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS : row.timeoutSeconds,
+        };
+        if ('cursorLoopLimit' in row)
+            handler.loop_limit = row.cursorLoopLimit;
+        hooks[row.cursor] = [...(hooks[row.cursor] ?? []), handler];
+    }
+    return hooks;
 }
 /**
  * The one file each harness reads Notifai's lifecycle wiring from: the current
@@ -441,10 +396,7 @@ export function codexLegacyProjectLayers(cwd) {
     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`.
+ * Where Notifai writes in this Codex layer.
  *
  * `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
@@ -454,9 +406,12 @@ export function codexLegacyProjectLayers(cwd) {
  * 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.
+ * `config.toml` the layer's established representation. Notifai-owned inline
+ * handlers with no foreign inline neighbours are moved to `hooks.json`. Codex
+ * keys approval by source path, so that move is a User-owned `/hooks` review,
+ * not a silent identity-preserving refresh. `[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);
@@ -472,13 +427,9 @@ export function inspectCodexLayer(paths) {
         ourJsonEvents,
         ourTomlEvents,
         foreignTomlHooks,
-        writeTarget: ourTomlEvents.length > 0 && ourJsonEvents.length === 0
+        writeTarget: foreignTomlHooks && !(ourJsonEvents.length > 0 && ourTomlEvents.length === 0)
             ? paths.configToml
-            : ourJsonEvents.length > 0 && ourTomlEvents.length === 0
-                ? paths.hooksJson
-                : foreignTomlHooks
-                    ? paths.configToml
-                    : paths.hooksJson,
+            : paths.hooksJson,
     };
 }
 /**
@@ -629,7 +580,7 @@ function globalHarnessEvidence(env = process.env, platform = process.platform) {
         found.push('codex');
     if (existsSync(path.join(home, '.cursor')))
         found.push('cursor');
-    if (existsSync(path.join(home, '.config', 'opencode')))
+    if (existsSync(opencodeConfigDir(env, platform)))
         found.push('opencode');
     if (openclawHasGlobalEvidence(existsSync, env, platform))
         found.push('openclaw');
@@ -689,13 +640,13 @@ function isOurCommand(command, scriptPath) {
 }
 /** Cleanup-only recognition for unmistakable pre-marker Notifai commands. */
 function isLegacyNotifaiCommand(command) {
-    const hook = `['"]?\\s+hook (?:session-start|subagent-start|activation-stop|user-prompt-submit|stop|session-end)\\b`;
+    const hook = `['"]?\\s+hook (?:${HOOK_EVENT_PATTERN})\\b`;
     return (new RegExp(`(?:^|[\\s'"])notifai(?:\\.cmd)?${hook}`).test(command) ||
         new RegExp(`(?:^|[/\\\\])(?:notifai-public|notifai)[/\\\\]apps[/\\\\]cli[/\\\\]dist[/\\\\]main\\.js${hook}`, 'i').test(command) ||
         new RegExp(`[/\\\\]node_modules[/\\\\]@raidiant[/\\\\]notifai[/\\\\]dist[/\\\\]main\\.js${hook}`, 'i').test(command));
 }
 export function mergeCursorHooks(existing, incoming, scriptPath) {
-    const hooks = {};
+    const hooks = Object.create(null);
     const added = [];
     const replaced = [];
     const removed = [];
@@ -718,7 +669,7 @@ export function mergeCursorHooks(existing, incoming, scriptPath) {
     return { document: { ...existing, version: 1, hooks }, added, replaced, removed };
 }
 export function removeCursorHooks(existing, scriptPath) {
-    const hooks = {};
+    const hooks = Object.create(null);
     const replaced = [];
     for (const [event, handlers] of Object.entries(existing.hooks ?? {})) {
         const foreign = handlers.filter((handler) => !isOurCommand(handler.command, scriptPath));
@@ -786,7 +737,7 @@ function withoutOurs(groups, scriptPath) {
  * failure that reinstalling could not clear.
  */
 export function mergeHooks(existing, incoming, scriptPath) {
-    const hooks = {};
+    const hooks = Object.create(null);
     const added = [];
     const replaced = [];
     const removed = [];
@@ -815,7 +766,7 @@ export function mergeHooks(existing, incoming, scriptPath) {
     return { document: { ...existing, hooks }, added, replaced, removed };
 }
 export function removeHooks(existing, scriptPath) {
-    const hooks = {};
+    const hooks = Object.create(null);
     const replaced = [];
     for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
         if (!Array.isArray(groups)) {
@@ -848,30 +799,38 @@ export function removeHooks(existing, scriptPath) {
  * support.
  */
 export function applyPlan(file, document) {
+    preparePlan(file, document)();
+}
+/** Validate a proposed document before any file in a multi-file edit changes. */
+export function preparePlan(file, document, previous = readOptionalOwnedRegularFile(file)) {
     const body = isTomlSettingsPath(file)
-        ? tomlBody(file, document)
+        ? tomlBody(file, document, previous)
         : `${JSON.stringify(document, null, 2)}\n`;
-    // 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 });
-        return;
+    const empty = isTomlSettingsPath(file) ? body.trim() === '' : isEmptyJsonDocument(body);
+    return prepareFileWrite(file, previous, empty ? null : body);
+}
+function readOptionalOwnedRegularFile(file) {
+    try {
+        return readOwnedRegularFile(file);
     }
-    if (existsSync(file)) {
-        try {
-            if (readOwnedRegularFile(file) === body)
-                return;
-        }
-        catch {
-            // A file we cannot re-read still needs the replacement below.
-        }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
     }
-    atomicWriteFileSync(file, body, {
-        requireCurrentUserOwner: true,
-    });
+}
+function prepareFileWrite(file, previous, next) {
+    return () => {
+        const current = readOptionalOwnedRegularFile(file);
+        if (current !== previous)
+            throw new Error(`Configuration changed while preparing ${file}; retry.`);
+        if (current === next)
+            return;
+        if (next === null)
+            rmSync(file, { force: true });
+        else
+            atomicWriteFileSync(file, next, { requireCurrentUserOwner: true });
+    };
 }
 function isEmptyJsonDocument(body) {
     try {
@@ -921,73 +880,136 @@ export function cleanupEmptiedCodexLayer(paths) {
  * came in as, and only the hooks tables are regenerated — re-emitted at the end
  * of the file, because TOML does not care where a table sits and splicing into
  * the middle would mean reasoning about a region line by line. If the result
- * cannot be proven to parse back to the document asked for, this falls back to
- * the whole-file rewrite rather than risk a file it half-understood.
+ * cannot be proven to parse back to the document asked for, refuse the write.
  */
-function tomlBody(file, document) {
-    const whole = `${stringifyToml(document)}\n`;
-    if (!existsSync(file))
-        return whole;
-    let previous;
-    try {
-        previous = readOwnedRegularFile(file);
-    }
-    catch {
-        return whole;
+function tomlBody(file, document, previous) {
+    if (previous === null)
+        return `${stringifyToml(document)}\n`;
+    if (sameTomlValue(parseToml(previous), document))
+        return previous;
+    const next = spliceTomlHooks(previous, document);
+    if (next === null)
+        throw new Error(`Cannot preserve unrelated TOML configuration in ${file}; no changes written.`);
+    return next;
+}
+/** Only locate syntax; smol-toml owns validity and decoded key identity. */
+function tomlStatements(source) {
+    parseToml(source);
+    const statements = [];
+    let offset = 0;
+    while (offset < source.length) {
+        if (/\s/.test(source[offset])) {
+            offset++;
+            continue;
+        }
+        if (source[offset] === '#') {
+            while (offset < source.length && source[offset] !== '\n')
+                offset++;
+            continue;
+        }
+        const start = offset;
+        let depth = 0;
+        let equals = -1;
+        const comments = [];
+        while (offset < source.length) {
+            const char = source[offset];
+            if (char === '"' || char === "'") {
+                const multiline = source.slice(offset, offset + 3) === char.repeat(3);
+                offset += multiline ? 3 : 1;
+                while (offset < source.length) {
+                    if (char === '"' && source[offset] === '\\') {
+                        offset += 2;
+                        continue;
+                    }
+                    if (source[offset] === char) {
+                        let count = 1;
+                        while (source[offset + count] === char)
+                            count++;
+                        if (!multiline || count >= 3) {
+                            offset += multiline ? count : 1;
+                            break;
+                        }
+                        offset += count;
+                    }
+                    else
+                        offset++;
+                }
+                continue;
+            }
+            if (char === '#') {
+                if (depth === 0)
+                    break;
+                const commentStart = offset;
+                while (offset < source.length && source[offset] !== '\n')
+                    offset++;
+                comments.push({ start: commentStart, end: offset });
+                continue;
+            }
+            if (char === '\n' && depth === 0)
+                break;
+            if (char === '[' || char === '{')
+                depth++;
+            if (char === ']' || char === '}')
+                depth--;
+            if (char === '=' && depth === 0 && equals === -1)
+                equals = offset;
+            offset++;
+        }
+        const table = source[start] === '[';
+        const syntax = source.slice(start, offset).trim();
+        // A standalone table or a dummy assignment decodes dotted/quoted/escaped
+        // keys without interpreting brackets, dots or quotes inside a key as syntax.
+        let decoded = parseToml(table ? syntax : `${source.slice(start, equals)} = 0`);
+        const keys = [];
+        while (decoded !== null && typeof decoded === 'object') {
+            if (Array.isArray(decoded)) {
+                decoded = decoded[0];
+                continue;
+            }
+            const entries = Object.entries(decoded);
+            if (entries.length !== 1)
+                break;
+            const [key, value] = entries[0];
+            keys.push(key);
+            decoded = value;
+        }
+        statements.push({ start, end: offset, table, path: keys, comments });
     }
-    return spliceTomlHooks(previous, document) ?? whole;
-}
-/** A TOML table header line, e.g. `[hooks.state."…"]` or `[[hooks.Stop]]`. */
-const TOML_TABLE_HEADER = /^\s*\[\[?([^[\]]+)\]\]?\s*(?:#.*)?$/;
-/**
- * The first key in a dotted TOML key path, unquoting it if it is quoted.
- * `hooks.state."/a/b:stop:0:0"` is rooted at `hooks`, and so is `hooks.Stop`.
- */
-function firstTomlKey(keyPath) {
-    const trimmed = keyPath.trim();
-    const quote = trimmed[0];
-    if (quote === '"' || quote === "'") {
-        const end = trimmed.indexOf(quote, 1);
-        return end === -1 ? trimmed.slice(1) : trimmed.slice(1, end);
+    return statements;
+}
+/** Splice syntax spans only; even comments inside removed arrays survive. */
+function omitTomlStatements(source, removed) {
+    let next = '';
+    let offset = 0;
+    for (const statement of removed) {
+        next += source.slice(offset, statement.start);
+        for (const comment of statement.comments)
+            next += `${source.slice(comment.start, comment.end)}\n`;
+        offset = statement.end;
     }
-    const dot = trimmed.indexOf('.');
-    return (dot === -1 ? trimmed : trimmed.slice(0, dot)).trim();
+    return next + source.slice(offset);
 }
-/**
- * `source` with its hooks tables replaced by `document`'s, or null when that
- * cannot be done safely — an inline top-level `hooks` key, or a result that
- * does not parse back to exactly the document asked for.
- */
+/** Replace hook syntax only, validating all unrelated parsed values. */
 function spliceTomlHooks(source, document) {
-    const kept = [];
-    let inHooks = false;
-    for (const line of source.split('\n')) {
-        const header = TOML_TABLE_HEADER.exec(line);
-        if (header !== null)
-            inHooks = firstTomlKey(header[1] ?? '') === 'hooks';
-        // A root-level `hooks = …` or `hooks.x = …` would survive the splice and
-        // then collide with the tables appended below.
-        if (!inHooks && /^\s*hooks\s*[.=]/.test(line))
-            return null;
-        if (!inHooks)
-            kept.push(line);
-    }
-    const hooks = document.hooks;
-    const body = hooks === undefined ? '' : stringifyToml({ hooks });
-    const head = kept.join('\n').trimEnd();
-    const spliced = body === '' ? `${head}\n` : head === '' ? `${body}\n` : `${head}\n\n${body}\n`;
     try {
-        if (!sameTomlValue(parseToml(spliced), document))
-            return null;
+        let table = [];
+        const removed = tomlStatements(source).filter((statement) => {
+            if (statement.table)
+                table = statement.path;
+            return (statement.table ? table : [...table, ...statement.path])[0] === 'hooks';
+        });
+        const head = omitTomlStatements(source, removed);
+        const body = document.hooks === undefined ? '' : stringifyToml({ hooks: document.hooks });
+        const spliced = body === '' ? head : `${head}${head === '' || head.endsWith('\n') ? '' : '\n'}${body}\n`;
+        return sameTomlValue(parseToml(spliced), document) ? spliced : null;
     }
     catch {
         return null;
     }
-    return spliced;
 }
 /** Structural equality for parsed TOML, which carries dates as well as data. */
 function sameTomlValue(a, b) {
-    if (a === b)
+    if (Object.is(a, b))
         return true;
     if (a instanceof Date && b instanceof Date)
         return a.getTime() === b.getTime();
@@ -1003,12 +1025,12 @@ function sameTomlValue(a, b) {
     const keys = Object.keys(left);
     if (keys.length !== Object.keys(right).length)
         return false;
-    return keys.every((key) => key in right && sameTomlValue(left[key], right[key]));
+    return keys.every((key) => Object.hasOwn(right, key) && sameTomlValue(left[key], right[key]));
 }
 export function loadSettings(file) {
     return isTomlSettingsPath(file) ? readTomlSettings(file) : readSettings(file);
 }
-function isTomlSettingsPath(file) {
+export function isTomlSettingsPath(file) {
     return file.endsWith('.toml');
 }
 function readTomlSettings(file) {
@@ -1164,7 +1186,139 @@ export function codexTrustProblems(installations, env = process.env) {
  * evidence that it has (and is itself worth reporting).
  */
 function isNotifaiCommand(command) {
-    return / hook (session-start|subagent-start|activation-stop|user-prompt-submit|stop|session-end)\b/.test(command);
+    return HOOK_EVENT_COMMAND_RE.test(command);
+}
+/**
+ * Native plugin ids that would fire beside document hooks if left enabled.
+ *
+ * Notifai no longer wires through harness plugins. A leftover enablement from
+ * a trial or an older experiment still runs the same adapter command, so
+ * document handlers plus that plugin fire every event twice. Matching is the
+ * plugin name `notifai` with an optional `@marketplace` suffix — never a
+ * substring of someone else's plugin id.
+ */
+function isNotifaiNativePluginKey(key) {
+    const id = key.split('@')[0]?.trim() ?? '';
+    return id.toLowerCase() === 'notifai';
+}
+function pluginEntryIsEnabled(value) {
+    if (value === false)
+        return false;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return value['enabled'] !== false;
+    }
+    return true;
+}
+export function notifaiNativePluginEnablementKeys(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.entries(value)
+        .filter(([key, enabled]) => isNotifaiNativePluginKey(key) && pluginEntryIsEnabled(enabled))
+        .map(([key]) => key);
+}
+export function stripObsoleteNotifaiPluginEnablement(document) {
+    const next = { ...document };
+    const removed = [];
+    for (const field of ['enabledPlugins', 'plugins']) {
+        const value = next[field];
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const record = { ...value };
+        let changed = false;
+        for (const key of Object.keys(record)) {
+            if (!isNotifaiNativePluginKey(key) || !pluginEntryIsEnabled(record[key]))
+                continue;
+            delete record[key];
+            removed.push(key);
+            changed = true;
+        }
+        if (!changed)
+            continue;
+        if (Object.keys(record).length === 0)
+            delete next[field];
+        else
+            next[field] = record;
+    }
+    return { document: next, removed };
+}
+/**
+ * Remove enabled Notifai plugin tables only after lexical ownership and full
+ * semantic preservation are proven. Unsupported dotted/inline definitions
+ * fail before mutation, rather than silently leaving a second firing path.
+ */
+export function spliceOutNotifaiPluginTables(source) {
+    const expected = parseToml(source);
+    const plugins = expected['plugins'];
+    const removed = notifaiNativePluginEnablementKeys(plugins);
+    if (removed.length === 0)
+        return { next: source, removed };
+    const remaining = { ...plugins };
+    for (const key of removed)
+        delete remaining[key];
+    expected['plugins'] = remaining;
+    let dropping = false;
+    const omitted = tomlStatements(source).filter((statement) => {
+        if (statement.table) {
+            dropping = statement.path[0] === 'plugins' && removed.includes(statement.path[1] ?? '');
+        }
+        return dropping;
+    });
+    const next = omitTomlStatements(source, omitted);
+    const parsed = parseToml(next);
+    // Removing the last child table may also remove its implicit parent.
+    for (const value of [expected, parsed]) {
+        const entries = value['plugins'];
+        if (entries && typeof entries === 'object' && !Array.isArray(entries) && Object.keys(entries).length === 0) {
+            delete value['plugins'];
+        }
+    }
+    if (!sameTomlValue(parsed, expected)) {
+        throw new Error('Cannot safely remove obsolete native plugin wiring from this TOML form; disable the Notifai plugin or use [plugins."notifai"] table form and retry. No changes written.');
+    }
+    return { next, removed };
+}
+/**
+ * Leftover native plugin enablement that would fire beside document hooks.
+ *
+ * Reads only harness settings files this installer already owns inspecting.
+ * It never shells out to a plugin CLI and never writes a plugin.
+ */
+export function findObsoleteNotifaiPluginWiring(env = process.env, platform = process.platform) {
+    const found = [];
+    const claudeFile = settingsFile('claude-code', env, platform);
+    if (existsSync(claudeFile)) {
+        try {
+            const keys = notifaiNativePluginEnablementKeys(loadSettings(claudeFile)['enabledPlugins']);
+            if (keys.length > 0)
+                found.push({ harness: 'claude-code', file: claudeFile, keys });
+        }
+        catch {
+            // Unreadable settings are reported by the ordinary install/doctor path.
+        }
+    }
+    const codexToml = codexMachineLayerPaths(env, platform).configToml;
+    if (existsSync(codexToml)) {
+        try {
+            const keys = notifaiNativePluginEnablementKeys(loadSettings(codexToml)['plugins']);
+            if (keys.length > 0)
+                found.push({ harness: 'codex', file: codexToml, keys });
+        }
+        catch {
+            // Same: leave diagnosis to the settings reader that already ran.
+        }
+    }
+    return found;
+}
+/**
+ * Plan native plugin retirement without changing configuration. The caller
+ * validates every destination before applying this plan under the layer lock.
+ */
+export function prepareCodexPluginCleanup(file) {
+    const previous = readOptionalOwnedRegularFile(file);
+    if (previous === null)
+        return { source: null, removed: [], apply: prepareFileWrite(file, null, null) };
+    const { next, removed } = spliceOutNotifaiPluginTables(previous);
+    return { source: next, removed, apply: prepareFileWrite(file, previous, next) };
 }
 /**
  * The one Machine installation each harness would read a Notifai handler from.
@@ -1334,7 +1488,7 @@ export function handlerEvent(command) {
 function readOwnedRegularFile(file) {
     const stat = lstatSync(file);
     if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw new Error(`${file} is not a regular file; refusing to read it.`);
+        throw new Error(`${file} is not a regular file${stat.isSymbolicLink() ? ' (symlink)' : ''}; refusing to read it.`);
     }
     const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
     if (uid !== undefined && stat.uid !== uid) {