nterminal 1.3.4 → 1.3.5

package/dist/server/hooks/hookInstallation.js

@@ -0,0 +1,978 @@
+import { constants } from 'node:fs';
+import { access, lstat, readFile, readdir, realpath } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HookControlError as InstallationError, ensureDirectory, missing, snapshot, replace } from './hookFiles.js';
+import { acquireVerifiedLock } from './verifiedLock.js';
+import { HelperJournal } from './helperJournal.js';
+// Subagent events are not registered: the runtime ignores child lifecycle events.
+const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PermissionRequest', 'Stop', 'Interrupt', 'SessionEnd'];
+const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PermissionRequest', 'Stop', 'StopFailure', 'PostToolUseFailure', 'Notification', 'SessionEnd'];
+// NTerminal never uses a hook response. Only turn/session boundaries stay synchronous:
+// they are infrequent, ordered, and the provider may exit right after them (Codex
+// also rejects async SessionEnd). Per-tool and notification events never block.
+const ASYNC_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionRequest', 'Notification', 'Interrupt']);
+// Definitions written by earlier NTerminal versions; recognized only for removal/upgrade.
+const LEGACY_BASE = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PermissionRequest', 'Stop', 'SubagentStart', 'SubagentStop'];
+const LEGACY_EVENTS = {
+    codex: [...LEGACY_BASE, 'Interrupt', 'SessionEnd'],
+    claude: [...LEGACY_BASE, 'StopFailure', 'PostToolUseFailure', 'Notification', 'SessionEnd']
+};
+const NOTIFY_BEGIN = '# BEGIN NTerminal notify';
+const NOTIFY_END = '# END NTerminal notify';
+export class HookInstallation {
+    options;
+    hooksDir;
+    lexicalHooksDir;
+    helperPath;
+    helperOwnershipPath;
+    helperJournal;
+    endpointPath;
+    nodeExecutable;
+    homes;
+    resolved = {};
+    constructor(options) {
+        this.options = options;
+        const home = options.homeDir ?? os.homedir();
+        const base = options.baseDir ?? process.cwd();
+        this.lexicalHooksDir = path.resolve(base, options.stateDir, 'hooks');
+        this.hooksDir = this.lexicalHooksDir;
+        this.helperPath = path.join(this.hooksDir, 'forward.cjs');
+        this.helperOwnershipPath = path.join(this.hooksDir, 'helper-installation.json');
+        this.helperJournal = new HelperJournal(this.helperPath, this.helperOwnershipPath);
+        this.endpointPath = path.join(this.hooksDir, 'endpoint.json');
+        this.nodeExecutable = options.nodeExecutable ?? process.execPath;
+        this.homes = {
+            codex: path.resolve(base, (options.providerHomes?.codex ?? process.env.CODEX_HOME) || path.join(home, '.codex')),
+            claude: path.resolve(base, (options.providerHomes?.claude ?? process.env.CLAUDE_CONFIG_DIR) || path.join(home, '.claude'))
+        };
+    }
+    /**
+     * Resolve symlinks once per operation. The receiver authenticates the helper
+     * by comparing its argv with realpath(stateDir)/hooks, so commands must use the
+     * resolved path. Provider homes may be user-owned symlinks (dotfiles); all I/O
+     * then targets the resolved path, which has no symlink components left.
+     */
+    async prepare() {
+        const state = await resolveChecked(path.dirname(this.lexicalHooksDir));
+        const hooksDir = path.join(state, 'hooks');
+        if (hooksDir !== this.hooksDir) {
+            this.hooksDir = hooksDir;
+            this.helperPath = path.join(hooksDir, 'forward.cjs');
+            this.helperOwnershipPath = path.join(hooksDir, 'helper-installation.json');
+            this.helperJournal = new HelperJournal(this.helperPath, this.helperOwnershipPath);
+            this.endpointPath = path.join(hooksDir, 'endpoint.json');
+        }
+        const resolved = {};
+        // Failures are per provider: an unsafe Codex home must not block Claude.
+        for (const provider of ['codex', 'claude']) {
+            const display = this.displayPaths(provider);
+            try {
+                resolved[provider] = { config: await resolveChecked(display.config),
+                    notify: display.notify === null ? null : await resolveChecked(display.notify) };
+            }
+            catch (error) {
+                resolved[provider] = { error };
+            }
+        }
+        this.resolved = resolved;
+    }
+    async status(provider) {
+        const display = this.result(provider);
+        if (this.options.previewMode)
+            return { ...display, reason: 'preview_mode' };
+        try {
+            await this.prepare();
+            const context = this.context(provider);
+            const result = this.result(provider);
+            const warnings = [];
+            const config = jsonConfig(await snapshot(context.configPath));
+            const manifest = await this.manifest(context);
+            const toml = context.notifyPath ? scanToml((await snapshot(context.notifyPath))?.text ?? '') : [];
+            let disabled = config.disableAllHooks === true || config.allowManagedHooksOnly === true;
+            if (provider === 'codex')
+                disabled = await this.codexPolicy(toml, warnings) || disabled;
+            else
+                disabled = await this.claudePolicy(warnings) || disabled;
+            const ownedNotify = manifest ? this.ownedNotify(manifest) : [];
+            const rootNotify = toml.filter((entry) => entry.statement && entry.key[0] === 'notify');
+            const oursPresent = rootNotify.some((entry) => this.isOwnedNotify(entry, ownedNotify));
+            if (rootNotify.length && !oursPresent)
+                warnings.push('notify_foreign');
+            if (oursPresent && toml.some((entry) => entry.key[0] === 'profiles' && entry.key[2] === 'notify'))
+                warnings.push('notify_profile_override');
+            const finish = (value) => warnings.length ? { ...value, warnings } : value;
+            if (!manifest)
+                return finish(disabled ? { ...result, reason: 'hooks_disabled' } : result);
+            if (manifest.phase !== 'installed')
+                return finish({ ...result, reason: 'installation_incomplete' });
+            if (!hasEntries(config, manifest.entries))
+                return finish({ ...result, reason: 'ownership_conflict' });
+            // An edited copy of NTerminal's legacy notify is never adopted or ignored.
+            if (ownedNotify.length && !oursPresent && rootNotify.some((entry) => this.referencesHelper(entry))) {
+                return finish({ ...result, reason: 'ownership_conflict' });
+            }
+            let current = false;
+            try {
+                current = equal(manifest.entries, this.entries(provider, manifest.nodeExecutable));
+            }
+            catch { /* legacy-only path */ }
+            if (!current)
+                warnings.push('legacy_definitions');
+            if (!await snapshot(this.helperPath))
+                return finish({ ...result, reason: 'helper_missing' });
+            try {
+                await access(manifest.nodeExecutable, constants.X_OK);
+            }
+            catch {
+                return finish({ ...result, reason: 'node_unavailable' });
+            }
+            return finish({ ...result, installed: true, ...(disabled ? { reason: 'hooks_disabled' }
+                    : provider === 'codex' ? { reason: 'approval_unknown' } : {}) });
+        }
+        catch (error) {
+            return { ...display, ...failure(error) };
+        }
+    }
+    async install(provider) {
+        return this.change(provider, false);
+    }
+    async remove(provider) {
+        return this.change(provider, true);
+    }
+    async refreshManagedHelper() {
+        if (this.options.previewMode)
+            return { updated: false, reason: 'preview_mode' };
+        let release;
+        try {
+            await this.prepare();
+            const manifestPath = (provider) => path.join(this.hooksDir, `${provider}-installation.json`);
+            let optedIn = !!await snapshot(this.helperOwnershipPath);
+            for (const provider of ['codex', 'claude'])
+                if (await snapshot(manifestPath(provider)))
+                    optedIn = true;
+            if (!optedIn)
+                return { updated: false, reason: 'not_installed' };
+            release = (await acquireVerifiedLock(path.join(this.hooksDir, '.installation.lock'), this.options.procRoot, this.options.machineIdPath)).release;
+            const state = await this.helperJournal.resolve();
+            optedIn = false;
+            for (const provider of ['codex', 'claude']) {
+                // A provider without a manifest is irrelevant even if its home is unusable.
+                if (!await snapshot(manifestPath(provider)))
+                    continue;
+                const context = this.context(provider);
+                const manifest = await this.manifest(context);
+                if (!manifest)
+                    continue;
+                const status = await this.status(context.provider);
+                if (!status.installed)
+                    return { updated: false, reason: status.reason ?? 'ownership_conflict' };
+                optedIn = true;
+            }
+            if (!optedIn)
+                return { updated: false, reason: 'not_installed' };
+            if (!state.owned)
+                return { updated: false, reason: 'helper_ownership_unknown' };
+            if (!state.helper)
+                return { updated: false, reason: 'helper_missing' };
+            const source = await snapshot(this.options.helperSource ?? await packagedHelper(), false);
+            if (!source)
+                return { updated: false, reason: 'helper_unavailable' };
+            if (state.helper.text === source.text)
+                return { updated: false };
+            // No native config rewrite: command bytes and native trust hashes stay stable.
+            await this.helperJournal.transition(state, source.text);
+            return { updated: true };
+        }
+        catch (error) {
+            return { updated: false, reason: errorCode(error) };
+        }
+        finally {
+            if (release)
+                await release();
+        }
+    }
+    async helperReferenced() {
+        try {
+            for (const provider of ['codex', 'claude']) {
+                const context = this.context(provider);
+                const config = jsonConfig(await snapshot(context.configPath));
+                if (JSON.stringify(config.hooks ?? {}).includes('forward.cjs'))
+                    return true;
+                if (context.notifyPath && (await snapshot(context.notifyPath))?.text.includes('forward.cjs'))
+                    return true;
+            }
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
+    displayPaths(provider) {
+        if (provider !== 'codex' && provider !== 'claude')
+            throw new InstallationError('invalid_provider');
+        return { config: path.join(this.homes[provider], provider === 'codex' ? 'hooks.json' : 'settings.json'),
+            notify: provider === 'codex' ? path.join(this.homes.codex, 'config.toml') : null };
+    }
+    context(provider) {
+        const display = this.displayPaths(provider);
+        const resolved = this.resolved[provider] ?? display;
+        if ('error' in resolved)
+            throw resolved.error;
+        return {
+            provider, displayConfigPath: display.config, configPath: resolved.config,
+            notifyPath: resolved.notify,
+            manifestPath: path.join(this.hooksDir, `${provider}-installation.json`)
+        };
+    }
+    result(provider) {
+        const display = this.displayPaths(provider);
+        return { provider, installed: false, configPath: display.config,
+            ...(display.notify ? { notifyConfigPath: display.notify } : {}),
+            approvalRequired: provider === 'codex' ? null : false };
+    }
+    /** Current definitions: guarded POSIX command, async where the response is unused. */
+    entries(provider, node = this.nodeExecutable) {
+        const argv = this.argv(provider, node).map((value) => shellQuote(value));
+        // Codex runs hooks through the user's shell with -c and Claude through bash/$SHELL.
+        // Use only POSIX test/exec/exit syntax that sh, bash, zsh, and fish all accept.
+        // `exec` keeps the helper's argv[1] for the receiver's process proof. A moved
+        // node or a deleted state directory exits 0 silently instead of a hook error.
+        const command = `[ -x ${argv[0]} ] && [ -f ${argv[1]} ] && exec ${argv.join(' ')} || exit 0`;
+        return (provider === 'claude' ? CLAUDE_EVENTS : CODEX_EVENTS).map((event) => ({
+            event, group: {
+                ...(event === 'Notification' ? { matcher: '^(permission_prompt|idle_prompt|elicitation_dialog)$' } : {}),
+                hooks: [{ type: 'command', command, timeout: 1, ...(ASYNC_EVENTS.has(event) ? { async: true } : {}) }]
+            }
+        }));
+    }
+    argv(provider, node = this.nodeExecutable, hooksDir = this.hooksDir) {
+        if (!path.isAbsolute(node) || /[\x00-\x1f\x7f]/.test(node))
+            throw new InstallationError('node_unavailable');
+        return [node, path.join(hooksDir, 'forward.cjs'), '--provider', provider, '--endpoint', path.join(hooksDir, 'endpoint.json')];
+    }
+    /** Every definition shape an earlier NTerminal version could have written for this node. */
+    generations(provider, node) {
+        const result = [];
+        try {
+            result.push({ entries: this.entries(provider, node), notifyBlock: null });
+        }
+        catch { /* legacy shapes only */ }
+        for (const hooksDir of new Set([this.hooksDir, this.lexicalHooksDir])) {
+            const argv = this.argv(provider, node, hooksDir);
+            const command = argv.map((value) => shellQuote(value, false)).join(' ');
+            const entries = LEGACY_EVENTS[provider].map((event) => ({ event, group: {
+                    ...(event === 'Notification' ? { matcher: '^(permission_prompt|idle_prompt|elicitation_dialog)$' } : {}),
+                    hooks: [{ type: 'command', command, timeout: 1 }]
+                } }));
+            const notifyArgv = [...this.argv('codex', node, hooksDir), '--notify'];
+            const notifyBlock = provider === 'codex'
+                ? `${NOTIFY_BEGIN}\nnotify = [${notifyArgv.map((value) => JSON.stringify(value)).join(', ')}]\n${NOTIFY_END}\n` : null;
+            result.push({ entries, notifyBlock });
+            result.push({ entries: entries.filter((entry) => !['Interrupt', 'SessionEnd'].includes(entry.event)), notifyBlock });
+        }
+        return result;
+    }
+    /** Exact argv arrays of NTerminal's own legacy notify commands recorded in this manifest. */
+    ownedNotify(manifest) {
+        return [manifest, ...(manifest.prior ?? [])].flatMap((generation) => {
+            if (!generation.notifyBlock)
+                return [];
+            return [JSON.parse(generation.notifyBlock.split('\n')[1].slice('notify = '.length))];
+        });
+    }
+    /** Root `notify = [...]` whose decoded argv exactly equals an owned legacy command, however Codex reformatted it. */
+    isOwnedNotify(entry, owned) {
+        return entry.statement && !entry.header && entry.key.length === 1 && owned.some((argv) => equal(entry.strings, argv));
+    }
+    referencesHelper(entry) {
+        const helpers = [this.helperPath, path.join(this.lexicalHooksDir, 'forward.cjs')];
+        return entry.strings ? entry.strings.some((value) => helpers.includes(value)) : helpers.some((helper) => entry.value.includes(helper));
+    }
+    async manifest(context, saved) {
+        const source = saved === undefined ? await snapshot(context.manifestPath) : saved;
+        if (!source)
+            return null;
+        let value;
+        try {
+            value = JSON.parse(source.text);
+        }
+        catch {
+            throw new InstallationError('manifest_malformed');
+        }
+        const known = new Set([...LEGACY_EVENTS[context.provider], ...(context.provider === 'claude' ? CLAUDE_EVENTS : CODEX_EVENTS)]);
+        if (!record(value) || value.version !== 1 || value.provider !== context.provider
+            || (value.format !== undefined && value.format !== 2)
+            || value.configPath !== context.displayConfigPath || typeof value.nodeExecutable !== 'string'
+            || !['installing', 'installed', 'removing'].includes(String(value.phase)) || typeof value.createdHooks !== 'boolean'
+            || (value.createdConfig !== undefined && typeof value.createdConfig !== 'boolean')
+            || !Array.isArray(value.createdEvents) || value.createdEvents.some((event) => typeof event !== 'string' || !known.has(event))) {
+            throw new InstallationError('manifest_malformed');
+        }
+        const validGeneration = (generation) => {
+            if (!record(generation) || typeof generation.nodeExecutable !== 'string')
+                return false;
+            try {
+                return this.generations(context.provider, generation.nodeExecutable)
+                    .some((shape) => equal(generation.entries, shape.entries) && generation.notifyBlock === shape.notifyBlock);
+            }
+            catch {
+                return false;
+            }
+        };
+        if (!validGeneration(value) || (value.helperSha256 !== undefined
+            && (typeof value.helperSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.helperSha256)))
+            || (value.prior !== undefined && (value.phase === 'installed' || !Array.isArray(value.prior)
+                || value.prior.length > 64 || value.prior.some((generation) => !validGeneration(generation))))) {
+            throw new InstallationError('manifest_malformed');
+        }
+        return value;
+    }
+    /** Cheap, read-only policy checks. Unknown managed state is a warning, never an install blocker. */
+    async codexPolicy(toml, warnings) {
+        const feature = (entries, prefix) => {
+            const find = (name) => entries.find((entry) => equal(entry.key, [...prefix, 'features', name]))?.value;
+            // The canonical key overrides the deprecated alias in Codex 0.157.1.
+            // Missing feature keys retain the native default (enabled); never opt in here.
+            return (find('hooks') ?? find('codex_hooks')) === 'false';
+        };
+        const managedOnly = (entries) => entries.some((entry) => equal(entry.key, ['allow_managed_hooks_only']) && entry.value === 'true');
+        let disabled = feature(toml, []) || managedOnly(toml);
+        const active = toml.find((entry) => entry.statement && equal(entry.key, ['profile']))?.text;
+        const profiles = new Set(toml.filter((entry) => entry.key[0] === 'profiles' && entry.key.length > 1).map((entry) => entry.key[1]));
+        for (const profile of profiles) {
+            if (!feature(toml, ['profiles', profile]))
+                continue;
+            if (profile === active)
+                disabled = true;
+            else if (!warnings.includes('profile_hooks_disabled'))
+                warnings.push('profile_hooks_disabled');
+        }
+        const system = this.options.codexSystemDir ?? '/etc/codex';
+        for (const name of ['requirements.toml', 'managed_config.toml']) {
+            try {
+                const saved = await snapshot(path.join(system, name), false);
+                if (!saved)
+                    continue;
+                const managed = scanToml(saved.text);
+                if (managedOnly(managed) || feature(managed, []))
+                    disabled = true;
+            }
+            catch {
+                warnings.push('managed_policy_unreadable');
+            }
+        }
+        return disabled;
+    }
+    async claudePolicy(warnings) {
+        const directory = this.options.claudeManagedDir
+            ?? (process.platform === 'darwin' ? '/Library/Application Support/ClaudeCode' : '/etc/claude-code');
+        const files = [path.join(directory, 'managed-settings.json')];
+        try {
+            const dropIns = (await readdir(path.join(directory, 'managed-settings.d'))).filter((name) => name.endsWith('.json')).sort();
+            files.push(...dropIns.slice(0, 32).map((name) => path.join(directory, 'managed-settings.d', name)));
+        }
+        catch (error) {
+            if (!missing(error) && error.code !== 'ENOTDIR')
+                warnings.push('managed_policy_unreadable');
+        }
+        let disabled = false;
+        for (const file of files) {
+            try {
+                const saved = await snapshot(file, false);
+                if (!saved)
+                    continue;
+                const value = JSON.parse(saved.text);
+                if (record(value) && (value.disableAllHooks === true || value.allowManagedHooksOnly === true))
+                    disabled = true;
+            }
+            catch {
+                if (!warnings.includes('managed_policy_unreadable'))
+                    warnings.push('managed_policy_unreadable');
+            }
+        }
+        return disabled;
+    }
+    async change(provider, remove) {
+        const display = this.result(provider);
+        if (this.options.previewMode)
+            return { ...display, reason: 'preview_mode' };
+        const releases = [];
+        try {
+            await this.prepare();
+            const context = this.context(provider);
+            if (remove && !await snapshot(context.manifestPath))
+                return this.status(provider);
+            await ensureDirectory(this.hooksDir);
+            releases.push((await acquireVerifiedLock(path.join(this.hooksDir, '.installation.lock'), this.options.procRoot, this.options.machineIdPath)).release);
+            const helperBefore = await this.helperJournal.resolve();
+            await ensureDirectory(path.dirname(context.configPath));
+            releases.push((await acquireVerifiedLock(path.join(path.dirname(context.configPath), '.nterminal-hooks.lock'), this.options.procRoot, this.options.machineIdPath)).release);
+            const originalManifest = await snapshot(context.manifestPath);
+            const previous = await this.manifest(context, originalManifest);
+            if (remove && !previous)
+                return this.status(provider);
+            const originalConfig = await snapshot(context.configPath);
+            const config = jsonConfig(originalConfig);
+            const originalNotify = context.notifyPath ? await snapshot(context.notifyPath) : null;
+            const toml = originalNotify?.text ?? '';
+            const tomlEntries = context.notifyPath ? scanToml(toml) : [];
+            const createdHooks = previous?.createdHooks ?? !Object.hasOwn(config, 'hooks');
+            const createdConfig = previous ? previous.createdConfig === true : originalConfig === null;
+            let next = null;
+            let helperText;
+            const entries = remove ? null : this.entries(provider);
+            // Cumulative: also keeps event keys NTerminal created for since-dropped events
+            // (e.g. Subagent*) deletable across an interrupted upgrade. Only empty keys are deleted.
+            const createdEvents = remove ? previous.createdEvents : [...new Set([...(previous?.createdEvents ?? []), ...entries.map((entry) => entry.event)
+                        .filter((event) => !record(config.hooks) || !Object.hasOwn(config.hooks, event))])];
+            const owned = previous ? [previous, ...(previous.prior ?? [])].map((generation) => generation.entries) : [];
+            // Update NTerminal's groups in place: their index is part of Codex's trust key,
+            // and moving them would also shift every later user group into re-review.
+            const removedGroups = applyEntries(config, owned, previous?.phase === 'installed' ? previous.entries : null, entries, createdEvents);
+            let notify = toml;
+            if (previous) {
+                const ownedArgv = this.ownedNotify(previous);
+                const rootNotify = tomlEntries.filter((entry) => entry.statement && entry.key[0] === 'notify');
+                const ours = rootNotify.filter((entry) => this.isOwnedNotify(entry, ownedArgv));
+                if (ours.length)
+                    notify = removeNotify(notify, ours);
+                else if (ownedArgv.length && rootNotify.some((entry) => this.referencesHelper(entry)))
+                    throw new InstallationError('ownership_conflict');
+            }
+            if (removedGroups.length && context.notifyPath) {
+                notify = removeTrust(notify, [...new Set([context.displayConfigPath, context.configPath])], removedGroups);
+            }
+            const changes = [];
+            if (!remove) {
+                this.argv(provider);
+                try {
+                    await access(this.nodeExecutable, constants.X_OK);
+                }
+                catch {
+                    throw new InstallationError('node_unavailable');
+                }
+                const source = await snapshot(this.options.helperSource ?? await packagedHelper(), false);
+                if (!source)
+                    throw new InstallationError('helper_unavailable');
+                if (!helperBefore.owned && helperBefore.helper && helperBefore.helper.text !== source.text)
+                    throw new InstallationError('helper_conflict');
+                helperText = source.text;
+                next = { version: 1, format: 2, provider, configPath: context.displayConfigPath, nodeExecutable: this.nodeExecutable,
+                    phase: 'installed', createdHooks, createdConfig, createdEvents, entries: entries, notifyBlock: null };
+            }
+            else if (createdHooks && record(config.hooks) && Object.keys(config.hooks).length === 0) {
+                delete config.hooks;
+            }
+            const configText = remove && createdConfig && Object.keys(config).length === 0 ? null : serializeJson(originalConfig?.text ?? null, config);
+            changes.push({ target: context.configPath, before: originalConfig, text: configText });
+            if (context.notifyPath && notify !== toml)
+                changes.push({ target: context.notifyPath, before: originalNotify, text: notify });
+            // Persist exact ownership before any provider changes, allowing recovery
+            // after interruption without adopting similarly named user hooks.
+            const journal = { ...(next ?? previous), phase: next ? 'installing' : 'removing' };
+            if (next && previous) {
+                // Retain exact old definitions until the new configuration is committed.
+                // A process can exit between writing the manifest and either config file.
+                journal.prior = [previous, ...(previous.prior ?? [])]
+                    .map(({ nodeExecutable, entries, notifyBlock }) => ({ nodeExecutable, entries, notifyBlock }))
+                    .filter((generation, index, all) => all.findIndex((other) => equal(other, generation)) === index);
+                if (journal.prior.length > 64)
+                    throw new InstallationError('installation_incomplete');
+            }
+            let manifestSnapshot = await replace(context.manifestPath, originalManifest, JSON.stringify(journal, null, 2) + '\n', { durable: true });
+            const written = [];
+            try {
+                if (helperText !== undefined)
+                    await this.helperJournal.transition(helperBefore, helperText);
+                for (const change of changes) {
+                    await replace(change.target, change.before, change.text, { durable: true,
+                        onApplied: (after) => written.push({ ...change, after }) });
+                }
+                manifestSnapshot = await replace(context.manifestPath, manifestSnapshot, next ? JSON.stringify(next, null, 2) + '\n' : null, { durable: true, onApplied: (after) => { manifestSnapshot = after; } });
+            }
+            catch (error) {
+                // The final manifest rename/unlink may have succeeded before its fsync
+                // failed. Re-establish durable incomplete ownership before compensation;
+                // otherwise an exit during rollback leaves installed ownership for
+                // partially restored files. A failed journal barrier forbids rollback.
+                manifestSnapshot = await replace(context.manifestPath, manifestSnapshot, JSON.stringify(journal, null, 2) + '\n', { durable: true });
+                let restored = true;
+                for (const change of written.reverse()) {
+                    try {
+                        await replace(change.target, change.after, change.before?.text ?? null, { durable: true });
+                    }
+                    catch {
+                        restored = false;
+                    }
+                }
+                // Native config rollback comes first. A failed CAS may leave a hook
+                // referencing the committed helper, so never remove it in that case.
+                if (restored && helperText !== undefined) {
+                    try {
+                        if (!helperBefore.helper && await this.helperReferenced())
+                            restored = false;
+                        else
+                            await this.helperJournal.transition(await this.helperJournal.resolve(), helperBefore.helper?.text ?? null);
+                    }
+                    catch {
+                        restored = false;
+                    }
+                }
+                if (restored)
+                    await replace(context.manifestPath, manifestSnapshot, originalManifest?.text ?? null, { durable: true });
+                throw error;
+            }
+            return this.status(provider);
+        }
+        catch (error) {
+            return { ...await this.status(provider), ...failure(error) };
+        }
+        finally {
+            for (const release of releases.reverse())
+                await release();
+        }
+    }
+}
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function canonical(value) {
+    return JSON.stringify(value, (_key, entry) => record(entry)
+        ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b))) : entry) ?? 'undefined';
+}
+function equal(a, b) { return canonical(a) === canonical(b); }
+function jsonConfig(saved) {
+    if (!saved)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(saved.text);
+    }
+    catch {
+        throw new InstallationError('config_malformed');
+    }
+    if (!record(value) || (Object.hasOwn(value, 'hooks') && !record(value.hooks)))
+        throw new InstallationError('config_malformed');
+    if (record(value.hooks) && Object.values(value.hooks).some((groups) => !Array.isArray(groups)
+        || groups.some((group) => !record(group) || !Array.isArray(group.hooks) || group.hooks.some((hook) => !record(hook))))) {
+        throw new InstallationError('config_malformed');
+    }
+    return value;
+}
+/**
+ * Keep the user's formatting where practical: unchanged content keeps its exact
+ * bytes; otherwise preserve indentation, line endings, the trailing newline, and
+ * key order (JSON.parse/stringify retain insertion order).
+ */
+function serializeJson(original, value) {
+    if (original !== null) {
+        try {
+            if (equal(JSON.parse(original), value))
+                return original;
+        }
+        catch { /* rewritten below */ }
+    }
+    const indent = original === null ? '  ' : /\n([ \t]+)\S/.exec(original)?.[1] ?? (original.trim().includes('\n') ? '  ' : '');
+    let text = JSON.stringify(value, null, indent);
+    if (original === null || /\n\s*$/.test(original))
+        text += '\n';
+    if (original?.includes('\r\n'))
+        text = text.replaceAll('\n', '\r\n');
+    return text;
+}
+function hasEntries(config, entries) {
+    if (!record(config.hooks))
+        return false;
+    const hooks = config.hooks;
+    return entries.every((entry) => Array.isArray(hooks[entry.event])
+        && hooks[entry.event].filter((group) => equal(group, entry.group)).length === 1);
+}
+function commands(group) {
+    return record(group) && Array.isArray(group.hooks) ? group.hooks.map((hook) => hook.command) : [];
+}
+/**
+ * Replace owned groups in place (or remove them when `next` lacks the event),
+ * append genuinely new events, and return the original index of every owned
+ * group that was removed. Unknown groups carrying an owned command fail closed.
+ */
+function applyEntries(config, owned, current, next, createdEvents) {
+    const removed = [];
+    if (!record(config.hooks)) {
+        if (current?.length)
+            throw new InstallationError('ownership_conflict');
+        if (!next)
+            return removed;
+    }
+    const hooks = record(config.hooks) ? config.hooks : {};
+    const events = [...new Set([...owned.flat().map((entry) => entry.event), ...(next ?? []).map((entry) => entry.event)])];
+    for (const event of events) {
+        const existing = Object.hasOwn(hooks, event);
+        const groups = (existing ? hooks[event] : []);
+        const ownedGroups = owned.flatMap((generation) => generation.filter((entry) => entry.event === event).map((entry) => entry.group));
+        const ownedCommands = new Set(ownedGroups.flatMap(commands));
+        const currentGroup = current?.find((entry) => entry.event === event)?.group;
+        if (currentGroup && groups.filter((group) => equal(group, currentGroup)).length !== 1)
+            throw new InstallationError('ownership_conflict');
+        if (ownedGroups.some((owned) => groups.filter((group) => equal(group, owned)).length > 1))
+            throw new InstallationError('ownership_conflict');
+        const isOwned = groups.map((group) => ownedGroups.some((owned) => equal(group, owned)));
+        if (groups.some((group, index) => !isOwned[index] && commands(group).some((command) => ownedCommands.has(command)))) {
+            throw new InstallationError('ownership_conflict');
+        }
+        const nextGroup = next?.find((entry) => entry.event === event)?.group;
+        const nextCommands = new Set(commands(nextGroup));
+        if (groups.some((group, index) => !isOwned[index] && commands(group).some((command) => nextCommands.has(command)))) {
+            throw new InstallationError('ownership_conflict');
+        }
+        const result = [];
+        let placed = false;
+        groups.forEach((group, index) => {
+            if (!isOwned[index])
+                result.push(group);
+            else if (nextGroup && !placed) {
+                result.push(nextGroup);
+                placed = true;
+            }
+            else
+                removed.push({ event, index });
+        });
+        if (nextGroup && !placed)
+            result.push(nextGroup);
+        if (result.length || (existing && !createdEvents.includes(event)))
+            hooks[event] = result;
+        else
+            delete hooks[event];
+    }
+    if (next || record(config.hooks))
+        config.hooks = hooks;
+    return removed;
+}
+function shellQuote(value, strict = true) {
+    // Backslashes are literal in POSIX single quotes but not in fish; refuse them.
+    if (/[\x00-\x1f\x7f]/.test(value) || (strict && value.includes('\\')))
+        throw new InstallationError('unsafe_path', value);
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function failure(error) {
+    const reason = errorCode(error);
+    return reason === 'unsafe_path' && error instanceof InstallationError && error.path ? { reason, unsafePath: error.path } : { reason };
+}
+function errorCode(error) {
+    if (error instanceof InstallationError)
+        return error.code;
+    return error?.code === 'ELOOP' ? 'unsafe_path' : 'installation_unavailable';
+}
+async function packagedHelper() {
+    let directory = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const metadata = JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+            if (record(metadata) && metadata.name === 'nterminal')
+                return path.join(directory, 'scripts', 'nterminal-hook.cjs');
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            throw new InstallationError('helper_unavailable');
+        directory = parent;
+    }
+}
+/** realpath of the deepest existing ancestor plus the missing remainder. */
+async function resolveExisting(target) {
+    try {
+        return await realpath(target);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ELOOP')
+            throw new InstallationError('unsafe_path', target);
+        if (!missing(error) && code !== 'ENOTDIR')
+            throw error;
+        const parent = path.dirname(target);
+        return parent === target ? target : path.join(await resolveExisting(parent), path.basename(target));
+    }
+}
+/**
+ * Accept a symlinked path component only when the resolved directory NTerminal
+ * writes into belongs to this user (or, when not yet created, sits in a
+ * directory owned by this user or root) and is not writable by others.
+ */
+async function resolveChecked(target) {
+    const resolved = await resolveExisting(target);
+    if (resolved === target)
+        return resolved;
+    let directory = path.dirname(resolved);
+    const leaf = await lstat(resolved).catch((error) => { if (missing(error))
+        return null; throw error; });
+    if (leaf?.isDirectory())
+        directory = resolved;
+    for (let first = true;; first = false) {
+        const info = await lstat(directory).catch((error) => { if (missing(error))
+            return null; throw error; });
+        if (info) {
+            const uid = process.getuid?.();
+            const ownerOk = uid === undefined || info.uid === uid || (!first && info.uid === 0);
+            if (!info.isDirectory() || !ownerOk || (info.mode & 0o002) !== 0)
+                throw new InstallationError('unsafe_path', directory);
+            return resolved;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return resolved;
+        directory = parent;
+    }
+}
+function snakeCase(event) { return event.replace(/(?<!^)[A-Z]/g, (letter) => `_${letter}`).toLowerCase(); }
+function removeRanges(source, ranges) {
+    let result = source;
+    for (const [start, end] of [...ranges].sort((a, b) => b[0] - a[0]))
+        result = result.slice(0, start) + result.slice(end);
+    return result;
+}
+/** Remove NTerminal's legacy notify statement and its marker comments; nothing else. */
+function removeNotify(source, statements) {
+    const ranges = statements.map((entry) => [entry.start, entry.end]);
+    for (const marker of [NOTIFY_BEGIN, NOTIFY_END]) {
+        const match = new RegExp(`(^|\\n)(${marker.replaceAll(' ', '[ ]')}[ \\t]*(?:\\r?\\n|$))`).exec(source);
+        if (match)
+            ranges.push([match.index + match[1].length, match.index + match[0].length]);
+    }
+    return removeRanges(source, ranges);
+}
+/**
+ * Remove Codex trust records keyed to NTerminal groups that were just removed
+ * (`[hooks.state."<hooks.json>:<event>:<group>:0"]`). Other bytes are unchanged.
+ */
+function removeTrust(source, configPaths, removed) {
+    const keys = new Set(removed.flatMap(({ event, index }) => configPaths.flatMap((file) => [...new Set([event, snakeCase(event)])].map((name) => `${file}:${name}:${index}:0`))));
+    const entries = scanToml(source);
+    const ranges = [];
+    entries.forEach((entry, index) => {
+        if (!entry.statement || entry.key.length < 3 || entry.key[0] !== 'hooks' || entry.key[1] !== 'state' || !keys.has(entry.key[2]))
+            return;
+        if (!entry.header) {
+            // Dotted (`hooks.state."K".trusted_hash`) or inline-table (`"K" = {...}`) records.
+            ranges.push([entry.start, entry.end]);
+            return;
+        }
+        if (entry.key.length !== 3)
+            return;
+        let end = entry.end;
+        for (const member of entries.slice(index + 1)) {
+            if (member.header)
+                break;
+            if (member.statement)
+                end = member.end;
+        }
+        let start = entry.start;
+        // Drop the blank separator line that preceded the removed table.
+        if (source.slice(0, start).endsWith('\n\n'))
+            start -= 1;
+        else if (source.slice(0, start).endsWith('\r\n\r\n'))
+            start -= 2;
+        ranges.push([start, end]);
+    });
+    return ranges.length ? removeRanges(source, ranges) : source;
+}
+// A lossless, narrow TOML editor: only inspect statement boundaries and keys;
+// never serialize user tables/arrays. Unrecognized value syntax fails closed.
+function scanToml(source) {
+    if (source.includes('') || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(source))
+        throw new InstallationError('config_malformed');
+    let position = 0;
+    let table = [];
+    const result = [];
+    const rootKeys = new Set();
+    const fail = () => { throw new InstallationError('config_malformed'); };
+    const space = () => { while (source[position] === ' ' || source[position] === '\t')
+        position++; };
+    const trivia = () => {
+        while (position < source.length) {
+            if (/\s/.test(source[position])) {
+                position++;
+                continue;
+            }
+            if (source[position] === '#') {
+                while (position < source.length && source[position] !== '\n')
+                    position++;
+                continue;
+            }
+            break;
+        }
+    };
+    const string = (key = false) => {
+        const quote = source[position++];
+        const triple = !key && source.slice(position, position + 2) === quote.repeat(2);
+        if (triple)
+            position += 2;
+        let decoded = '';
+        while (position < source.length) {
+            const char = source[position++];
+            if (char === quote) {
+                if (!triple)
+                    return decoded;
+                if (source.slice(position, position + 2) === quote.repeat(2)) {
+                    position += 2;
+                    for (let extra = 0; extra < 2 && source[position] === quote; extra++) {
+                        decoded += quote;
+                        position++;
+                    }
+                    return decoded;
+                }
+            }
+            if (!triple && /[\r\n]/.test(char))
+                fail();
+            if (char < ' ' && char !== '\t' && !(triple && /[\r\n]/.test(char)))
+                fail();
+            if (char === '\\' && quote === '"') {
+                const escaped = source[position++] ?? fail();
+                if (triple && /\s/.test(escaped)) {
+                    while (position < source.length && /\s/.test(source[position]))
+                        position++;
+                    continue;
+                }
+                if ('btnfr"\\'.includes(escaped))
+                    decoded += { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r' }[escaped] ?? escaped;
+                else if (escaped === 'u' || escaped === 'U') {
+                    const count = escaped === 'u' ? 4 : 8;
+                    const hex = source.slice(position, position + count);
+                    if (hex.length !== count || !/^[0-9a-f]+$/i.test(hex))
+                        fail();
+                    const code = parseInt(hex, 16);
+                    if (code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff))
+                        fail();
+                    decoded += String.fromCodePoint(code);
+                    position += count;
+                }
+                else
+                    fail();
+            }
+            else
+                decoded += char;
+        }
+        return fail();
+    };
+    const key = () => {
+        const parts = [];
+        while (true) {
+            space();
+            if (source[position] === '"' || source[position] === "'")
+                parts.push(string(true));
+            else {
+                const match = /^[A-Za-z0-9_-]+/.exec(source.slice(position));
+                if (!match)
+                    fail();
+                parts.push(match[0]);
+                position += match[0].length;
+            }
+            space();
+            if (source[position] !== '.')
+                return parts;
+            position++;
+        }
+    };
+    // Returns a decoded string, or the decoded elements of an all-string array.
+    const value = (depth = 0, prefix) => {
+        if (depth > 64)
+            fail();
+        space();
+        const start = source[position];
+        if (start === '"' || start === "'")
+            return { text: string() };
+        if (start === '[' || start === '{') {
+            position++;
+            const end = start === '[' ? ']' : '}';
+            let strings = start === '[' ? [] : undefined;
+            trivia();
+            while (source[position] !== end) {
+                let parts;
+                if (start === '{') {
+                    const keys = key();
+                    parts = prefix && [...prefix, ...keys];
+                    if (source[position++] !== '=')
+                        fail();
+                }
+                const begin = position;
+                const element = value(depth + 1, parts);
+                if (strings) {
+                    if (element.text === undefined)
+                        strings = undefined;
+                    else
+                        strings.push(element.text);
+                }
+                if (parts)
+                    result.push({ key: parts, value: source.slice(begin, position).trim(), start: begin, end: position, header: false, statement: false, ...element });
+                trivia();
+                if (source[position] === end)
+                    break;
+                if (source[position++] !== ',')
+                    fail();
+                trivia();
+            }
+            position++;
+            return strings ? { strings } : {};
+        }
+        const begin = position;
+        while (position < source.length && !/[\r\n,#\]}]/.test(source[position]))
+            position++;
+        const token = source.slice(begin, position).trim();
+        if (!/^(?:true|false|[+-]?(?:inf|nan)|[+-]?(?:0|[1-9](?:_?\d)*)(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?|0x[\da-fA-F](?:_?[\da-fA-F])*|0o[0-7](?:_?[0-7])*|0b[01](?:_?[01])*|\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})?)?|\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/.test(token))
+            fail();
+        return {};
+    };
+    const lineEnd = () => {
+        space();
+        if (source[position] === '#')
+            while (position < source.length && source[position] !== '\n')
+                position++;
+        if (position < source.length && !/[\r\n]/.test(source[position]))
+            fail();
+        if (source[position] === '\r' && source[position + 1] === '\n')
+            position += 2;
+        else if (source[position] === '\n')
+            position++;
+        else if (source[position] === '\r')
+            fail();
+        return position;
+    };
+    while (position < source.length) {
+        trivia();
+        if (position === source.length)
+            break;
+        const statementStart = position;
+        if (source[position] === '[') {
+            position++;
+            const array = source[position] === '[';
+            if (array)
+                position++;
+            table = key();
+            if (source[position++] !== ']' || (array && source[position++] !== ']'))
+                fail();
+            const entry = { key: table, value: '', start: statementStart, end: 0, header: true, statement: true };
+            entry.end = lineEnd();
+            result.push(entry);
+        }
+        else {
+            const parts = key();
+            if (source[position++] !== '=')
+                fail();
+            const start = position;
+            const element = value(0, [...table, ...parts]);
+            if (table.length === 0) {
+                const name = JSON.stringify(parts);
+                if (rootKeys.has(name))
+                    fail();
+                rootKeys.add(name);
+            }
+            const entry = { key: [...table, ...parts], value: source.slice(start, position).trim(), start: statementStart, end: 0,
+                header: false, statement: true, ...element };
+            entry.end = lineEnd();
+            result.push(entry);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=hookInstallation.js.map