@bridge4dev/runner 0.42.0 → 0.44.1

package/dist/claude-settings.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Безопасное слияние привратника в `~/.claude/settings.json`.
+ *
+ * Этот файл принадлежит РАЗРАБОТЧИКУ, а не нам: там его модель, тема, плагины и
+ * его собственные хуки. Мы добавляем ровно один ключ и обязаны уметь снять ровно
+ * его. Требования целиком — `docs/plans/active/claude-code-regex-guard.md` §4.
+ *
+ * Прецедент в проекте — `merge-mcp.cjs` в установщике: он тоже сливает наше в
+ * чужой файл и тоже отказывается работать с тем, что не разбирается.
+ */
+/**
+ * ВЫКЛЮЧАТЕЛЬ ПРИВРАТНИКА — одна строка, которой всё снимается.
+ *
+ * Поставь `false`, выпусти раннер — и каждая машина при первом же запуске демона
+ * СНИМЕТ запись из `~/.claude/settings.json` и вернёт файл как было. Ничего
+ * больше менять не нужно: ни установщик, ни настройки на машинах, ни руками.
+ *
+ * Когда это делать и как сначала проверить, что дефект действительно починили, —
+ * тикет «Привратник шаблонов поиска» и `docs/plans/active/claude-code-regex-guard.md` §3.3.
+ */
+export declare const SEARCH_GUARD_ENABLED = true;
+/** По этой строке наша запись опознаётся при снятии. Меняя её, сломаешь удаление. */
+export declare const GUARD_MARKER = "devbridge-regex-guard";
+/** Версия записи. Растёт, когда меняется правило или путь до хука. */
+export declare const GUARD_VERSION = 1;
+export interface MergeResult {
+    text: string;
+    /** Файл действительно изменился. `false` — переписывать нечего. */
+    changed: boolean;
+}
+/** Добавляет привратника, не трогая ничего чужого. */
+export declare function mergeGuardIntoSettings(text: string, command: string, nodeExists?: (p: string) => boolean): MergeResult;
+/** Снимает привратника и возвращает файл к прежнему виду. */
+export declare function removeGuardFromSettings(text: string): MergeResult;
+/**
+ * Чей `~/.claude` мы правим.
+ *
+ * Через `systemdUserHome()`, а не `os.homedir()` напрямую — потому что раннер сюда
+ * ПИШЕТ. `paths.ts` описывает ровно эту ловушку: `service-unit.ts` когда-то брал
+ * домашний каталог напрямую, и первый же тестовый прогон начал переписывать
+ * сервис самого разработчика. Здесь цена ошибки такая же — чужой файл настроек.
+ */
+export declare function searchGuardHome(): string;
+/** Путь к файлу настроек Claude Code. `home` подменяется в тестах. */
+export declare function claudeSettingsPath(home: string): string;
+/**
+ * Путь к исполняемому привратнику рядом с самим раннером.
+ *
+ * Считается от запущенного файла, а не зашивается: префикс установки бывает
+ * `/usr`, `/usr/local` и домашний, и жёсткий путь развалился бы на первой же
+ * машине с другим префиксом.
+ *
+ * `realpathSync` здесь обязателен, а не «на всякий случай». Глобальная установка
+ * npm кладёт в `bin` СИМЛИНК:
+ *
+ *     /usr/bin/devbridge-runner -> ../lib/node_modules/@bridge4dev/runner/dist/index.js
+ *
+ * а `process.argv[1]` отдаёт именно симлинк — node его не разворачивает
+ * (проверено на живой машине). Без разворачивания путь считался бы как
+ * `/usr/bin/regex-guard-hook.js`, файла там нет, и привратник МОЛЧА не
+ * установился бы ни на одной реальной машине. Тот же приём и по той же причине
+ * применяет `unitExecTarget` в `service-unit.ts`.
+ */
+export declare function searchGuardHookPath(entry?: string): string;
+/**
+ * Готовая команда для настроек Claude Code: node плюс путь к хуку.
+ *
+ * Через `node`, а не файлом напрямую, по измеренной причине: `tsc` не ставит бит
+ * исполняемости на выходные файлы, поэтому прямой запуск отдаёт
+ * «Permission denied». Claude Code при этом НЕ блокирует команду — он просто
+ * считает хук сбойным, и машина молча остаётся без защиты.
+ *
+ * `process.execPath` — тот самый node, которым запущен раннер. Голое `node`
+ * зависело бы от PATH оболочки, в которой Claude Code исполняет хук, а он там
+ * не обязан быть (nvm, fnm, systemd-юнит с урезанным окружением).
+ */
+export declare function searchGuardCommand(entry?: string): string;
+type Warn = (message: string) => void;
+/**
+ * Ставит привратника в настройки Claude Code. Возвращает `false`, когда
+ * менять нечего или файл трогать нельзя.
+ *
+ * Отказ никогда не является аварией: раннер обязан подняться и работать даже
+ * на машине, где файл настроек сломан руками.
+ */
+export declare function installSearchGuard(hookPath: string, home: string, warn?: Warn): boolean;
+/** Снимает привратника. Возвращает `false`, если снимать было нечего. */
+export declare function removeSearchGuard(home: string, warn?: Warn): boolean;
+export interface SearchGuardStatus {
+    path: string;
+    /** Файл настроек прочитан и разобран. `false` — нет файла либо он сломан. */
+    settingsReadable: boolean;
+    /** Наша запись присутствует. */
+    installed: boolean;
+    /** Версия установленной записи; `null`, если её нет или прочитать не вышло. */
+    version: number | null;
+}
+/**
+ * Состояние привратника на этой машине — то, что печатает `doctor`.
+ *
+ * Существует ради проверки «дефект починили, можно снимать»: чтобы через месяц
+ * можно было пройтись по паркам и увидеть, где привратник ещё стоит, а где уже
+ * снят, не разбирая JSON руками.
+ */
+export declare function searchGuardStatus(home: string): SearchGuardStatus;
+export {};
+//# sourceMappingURL=claude-settings.d.ts.map

package/dist/claude-settings.js

@@ -0,0 +1,415 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { systemdUserHome } from './paths.js';
+/**
+ * Безопасное слияние привратника в `~/.claude/settings.json`.
+ *
+ * Этот файл принадлежит РАЗРАБОТЧИКУ, а не нам: там его модель, тема, плагины и
+ * его собственные хуки. Мы добавляем ровно один ключ и обязаны уметь снять ровно
+ * его. Требования целиком — `docs/plans/active/claude-code-regex-guard.md` §4.
+ *
+ * Прецедент в проекте — `merge-mcp.cjs` в установщике: он тоже сливает наше в
+ * чужой файл и тоже отказывается работать с тем, что не разбирается.
+ */
+/**
+ * ВЫКЛЮЧАТЕЛЬ ПРИВРАТНИКА — одна строка, которой всё снимается.
+ *
+ * Поставь `false`, выпусти раннер — и каждая машина при первом же запуске демона
+ * СНИМЕТ запись из `~/.claude/settings.json` и вернёт файл как было. Ничего
+ * больше менять не нужно: ни установщик, ни настройки на машинах, ни руками.
+ *
+ * Когда это делать и как сначала проверить, что дефект действительно починили, —
+ * тикет «Привратник шаблонов поиска» и `docs/plans/active/claude-code-regex-guard.md` §3.3.
+ */
+export const SEARCH_GUARD_ENABLED = true;
+/** По этой строке наша запись опознаётся при снятии. Меняя её, сломаешь удаление. */
+export const GUARD_MARKER = 'devbridge-regex-guard';
+/**
+ * Пометка «контейнер `hooks` в этом файле создали мы».
+ *
+ * Без неё снятие приходилось выбирать между двумя потерями: либо удалять
+ * опустевший `hooks` — и тогда пропадал чужой пустой `"hooks": {}`, стоявший там
+ * до нас; либо не удалять — и тогда на машине, где файла не было вовсе, после
+ * снятия оставался `{"hooks":{}}` вместо `{}` (QA MEDIUM-7). Пометка снимает
+ * выбор: удаляем ровно то, что сами и завели.
+ */
+const OWNS_HOOKS = 'owns-hooks';
+/** Версия записи. Растёт, когда меняется правило или путь до хука. */
+export const GUARD_VERSION = 1;
+/** На какие инструменты Claude Code вешается привратник. */
+const GUARD_MATCHER = 'Bash|Grep';
+/**
+ * Потолок времени на хук. Привратник — чистый разбор строки, ему хватает
+ * миллисекунд; секунды здесь на случай холодного старта node.
+ */
+const GUARD_TIMEOUT_SEC = 10;
+function detectFormat(text) {
+    const indented = text.split('\n').find((l) => /^\s+\S/.test(l));
+    const lead = indented?.match(/^\s+/)?.[0] ?? '';
+    // Таб считать «одним пробелом» — значит переформатировать весь чужой файл при
+    // снятии привратника (QA MEDIUM-7). `JSON.stringify` принимает строку отступа,
+    // так что таб отдаётся как таб.
+    const indent = lead.startsWith('\t') ? '\t' : lead.length > 0 ? lead.length : 2;
+    return { indent, trailingNewline: text.endsWith('\n') };
+}
+function serialize(value, format) {
+    return JSON.stringify(value, null, format.indent) + (format.trailingNewline ? '\n' : '');
+}
+/**
+ * Разбирает файл настроек. Всё, что не объект, — отказ.
+ *
+ * Отказ, а не «починим»: пустой или сломанный файл настроек чинится
+ * разработчиком, а перезапись поверх непонятного содержимого — это ровно тот
+ * способ потерять чужую работу, от которого написан весь этот модуль.
+ */
+function parseSettings(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error('settings.json does not parse — left untouched', { cause });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('settings.json is not an object — left untouched');
+    }
+    return parsed;
+}
+function guardCommand(hookPath, ownsHooks = false) {
+    // Маркер — обычный комментарий оболочки: он виден в файле, не меняет
+    // выполнение команды и не требует от схемы настроек знать наши поля.
+    return `${hookPath} # ${GUARD_MARKER}:${GUARD_VERSION}${ownsHooks ? ` ${OWNS_HOOKS}` : ''}`;
+}
+function isOurs(group) {
+    return (group.hooks ?? []).some((h) => typeof h.command === 'string' && h.command.includes(GUARD_MARKER));
+}
+/** Команда нашей записи, если она в этой группе есть. */
+function ourCommand(group) {
+    return (group.hooks ?? []).find((h) => h.command?.includes(GUARD_MARKER))?.command ?? null;
+}
+/**
+ * Достаточно ли свежа уже стоящая запись, чтобы её не переписывать?
+ *
+ * Сравнение НЕ побайтовое, и это важно. Команда содержит путь к `node`
+ * (`process.execPath`), а на машине с nvm/fnm демон и запущенный из оболочки
+ * `doctor` легко работают разными интерпретаторами. Побайтовое сравнение
+ * заставляло бы их переписывать ЧУЖОЙ файл по очереди на каждом запуске, засыпая
+ * каталог разработчика резервными копиями.
+ *
+ * Значение имеют только путь к хуку и версия. Но если записанный `node` исчез
+ * (снесли ту версию nvm), запись переписать НАДО: иначе хук молча не запускается
+ * и машина остаётся без защиты, а `doctor` продолжает показывать «installed».
+ */
+function guardEntryIsCurrent(existingCommand, desiredCommand, nodeExists) {
+    const parse = (command) => {
+        const [invocation = '', tail = ''] = command.split(` # ${GUARD_MARKER}:`);
+        // Версия — первое слово после маркера; за ней может стоять пометка
+        // `owns-hooks`, и на «свежесть» записи она не влияет.
+        const version = tail.split(' ')[0] ?? '';
+        // Основная форма — оба пути в одинарных кавычках. Разбор по кавычкам, а не по
+        // последнему пробелу: путь с пробелом иначе рвался посередине, и запись
+        // считалась устаревшей на КАЖДОМ запуске (QA MEDIUM-6).
+        const quoted = invocation.match(/^'([^']*)'\s+'([^']*)'$/);
+        if (quoted)
+            return { node: quoted[1] ?? '', hook: quoted[2] ?? '', version };
+        const cut = invocation.lastIndexOf(' ');
+        // Без кавычек и без пробела — просто путь к хуку. Так задают тесты и так
+        // выглядели бы записи, дописанные руками.
+        return cut < 0
+            ? { node: '', hook: invocation, version }
+            : { node: invocation.slice(0, cut), hook: invocation.slice(cut + 1), version };
+    };
+    const was = parse(existingCommand);
+    const wants = parse(desiredCommand);
+    if (was.hook !== wants.hook || was.version !== wants.version)
+        return false;
+    // Интерпретатор в записи не указан — сравнивать нечего, запись считается свежей.
+    return was.node === '' || nodeExists(was.node);
+}
+/**
+ * `hooks` как объект — или отказ.
+ *
+ * Без проверки спред строки давал `{ "0":".", "1":"/", … }`, то есть ЧУЖОЕ
+ * значение уничтожалось (QA HIGH-3). Дисциплина та же, что у `parseSettings`:
+ * что не понимаем — не трогаем.
+ */
+function asHooksObject(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('settings.json has a "hooks" value we do not understand — left untouched');
+    }
+    return value;
+}
+/** Добавляет привратника, не трогая ничего чужого. */
+export function mergeGuardIntoSettings(text, command, nodeExists = (p) => fs.existsSync(p)) {
+    const format = detectFormat(text);
+    const settings = parseSettings(text);
+    const hooksExisted = settings['hooks'] !== undefined && settings['hooks'] !== null;
+    const hooks = { ...asHooksObject(settings['hooks']) };
+    const existing = hooks['PreToolUse'] ?? [];
+    const foreign = existing.filter((g) => !isOurs(g));
+    const mine = existing.filter(isOurs);
+    // «Наш» контейнер один раз и навсегда: на втором запуске `hooks` уже есть —
+    // потому что его завели мы, — и потерять этот факт значило бы оставить след.
+    const ownsHooks = (ourCommand(mine[0] ?? {}) ?? '').includes(OWNS_HOOKS) || !hooksExisted;
+    const ours = {
+        matcher: GUARD_MATCHER,
+        hooks: [
+            { type: 'command', command: guardCommand(command, ownsHooks), timeout: GUARD_TIMEOUT_SEC },
+        ],
+    };
+    const alreadyCurrent = mine.length === 1 &&
+        guardEntryIsCurrent(ourCommand(mine[0]) ?? '', guardCommand(command, ownsHooks), nodeExists);
+    if (alreadyCurrent)
+        return { text, changed: false };
+    // Наша запись идёт последней: чужие проверки должны отработать раньше нашей.
+    hooks['PreToolUse'] = [...foreign, ours];
+    return { text: serialize({ ...settings, hooks }, format), changed: true };
+}
+/** Снимает привратника и возвращает файл к прежнему виду. */
+export function removeGuardFromSettings(text) {
+    const format = detectFormat(text);
+    const settings = parseSettings(text);
+    const hooksValue = settings['hooks'];
+    if (!hooksValue)
+        return { text, changed: false };
+    const existing = hooksValue['PreToolUse'] ?? [];
+    const foreign = existing.filter((g) => !isOurs(g));
+    if (foreign.length === existing.length)
+        return { text, changed: false };
+    const hooks = { ...hooksValue };
+    // Пустой массив — тоже след, убираем ключ целиком.
+    if (foreign.length === 0)
+        delete hooks['PreToolUse'];
+    else
+        hooks['PreToolUse'] = foreign;
+    const next = { ...settings };
+    // Опустевший `hooks` удаляем ТОЛЬКО если его завели мы — это записано
+    // пометкой в самой записи. Чужой пустой `"hooks": {}` остаётся на месте.
+    const weOwnHooks = existing
+        .filter(isOurs)
+        .some((g) => (ourCommand(g) ?? '').includes(OWNS_HOOKS));
+    if (Object.keys(hooks).length === 0 && weOwnHooks)
+        delete next['hooks'];
+    else
+        next['hooks'] = hooks;
+    return { text: serialize(next, format), changed: true };
+}
+/**
+ * Чей `~/.claude` мы правим.
+ *
+ * Через `systemdUserHome()`, а не `os.homedir()` напрямую — потому что раннер сюда
+ * ПИШЕТ. `paths.ts` описывает ровно эту ловушку: `service-unit.ts` когда-то брал
+ * домашний каталог напрямую, и первый же тестовый прогон начал переписывать
+ * сервис самого разработчика. Здесь цена ошибки такая же — чужой файл настроек.
+ */
+export function searchGuardHome() {
+    return systemdUserHome();
+}
+/** Путь к файлу настроек Claude Code. `home` подменяется в тестах. */
+export function claudeSettingsPath(home) {
+    return path.join(home, '.claude', 'settings.json');
+}
+/**
+ * Путь к исполняемому привратнику рядом с самим раннером.
+ *
+ * Считается от запущенного файла, а не зашивается: префикс установки бывает
+ * `/usr`, `/usr/local` и домашний, и жёсткий путь развалился бы на первой же
+ * машине с другим префиксом.
+ *
+ * `realpathSync` здесь обязателен, а не «на всякий случай». Глобальная установка
+ * npm кладёт в `bin` СИМЛИНК:
+ *
+ *     /usr/bin/devbridge-runner -> ../lib/node_modules/@bridge4dev/runner/dist/index.js
+ *
+ * а `process.argv[1]` отдаёт именно симлинк — node его не разворачивает
+ * (проверено на живой машине). Без разворачивания путь считался бы как
+ * `/usr/bin/regex-guard-hook.js`, файла там нет, и привратник МОЛЧА не
+ * установился бы ни на одной реальной машине. Тот же приём и по той же причине
+ * применяет `unitExecTarget` в `service-unit.ts`.
+ */
+export function searchGuardHookPath(entry = process.argv[1] ?? '') {
+    let script;
+    try {
+        script = fs.realpathSync(entry);
+    }
+    catch {
+        // Путь не существует (тесты, странная установка) — работаем с тем, что дали.
+        script = path.resolve(entry);
+    }
+    return path.join(path.dirname(script), 'regex-guard-hook.js');
+}
+/**
+ * Готовая команда для настроек Claude Code: node плюс путь к хуку.
+ *
+ * Через `node`, а не файлом напрямую, по измеренной причине: `tsc` не ставит бит
+ * исполняемости на выходные файлы, поэтому прямой запуск отдаёт
+ * «Permission denied». Claude Code при этом НЕ блокирует команду — он просто
+ * считает хук сбойным, и машина молча остаётся без защиты.
+ *
+ * `process.execPath` — тот самый node, которым запущен раннер. Голое `node`
+ * зависело бы от PATH оболочки, в которой Claude Code исполняет хук, а он там
+ * не обязан быть (nvm, fnm, systemd-юнит с урезанным окружением).
+ */
+export function searchGuardCommand(entry = process.argv[1] ?? '') {
+    // Кавычки обязательны: путь установки может содержать пробел, и без них
+    // оболочка выполнит `node /home/dev` вместо хука — молча, а `doctor` при этом
+    // продолжит рапортовать «installed» (QA MEDIUM-6).
+    return `'${process.execPath}' '${searchGuardHookPath(entry)}'`;
+}
+/**
+ * Запись «через временный файл и переименование».
+ *
+ * `rename` внутри одной файловой системы атомарен: читатель видит либо старый
+ * файл целиком, либо новый целиком. Обычная запись поверх оставила бы при обрыве
+ * половину файла — то есть сломанный Claude Code у разработчика.
+ */
+function writeAtomically(target, contents, mode) {
+    // Пишем ПО РЕАЛЬНОМУ пути. `settings.json` часто оказывается симлинком на
+    // dotfiles-репозиторий, и `rename` поверх симлинка заменил бы саму ссылку
+    // обычным файлом: связь с репозиторием рвётся молча, `git status` там чист
+    // (QA MEDIUM-4). Временный файл кладём рядом с целью, иначе `rename` уедет
+    // через границу файловых систем и перестанет быть атомарным.
+    let real = target;
+    try {
+        real = fs.realpathSync(target);
+    }
+    catch {
+        // Файла ещё нет — пишем по исходному пути.
+    }
+    const tmp = path.join(path.dirname(real), `.${path.basename(real)}.devbridge-${process.pid}`);
+    try {
+        fs.writeFileSync(tmp, contents, { mode });
+        // `writeFileSync` пропускает режим через umask (0640 при umask 077 давало
+        // 0600), поэтому права выставляем отдельно и уже наверняка (QA LOW-10).
+        fs.chmodSync(tmp, mode);
+        fs.renameSync(tmp, real);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            // Временный файл мог не появиться вовсе — это не отдельная беда.
+        }
+        throw error;
+    }
+}
+/** Копия рядом с оригиналом, до любых изменений (§4.4). */
+function backup(target) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    // `copyFileSync` читает по ссылке — копия получается настоящая, а не битая.
+    fs.copyFileSync(target, `${target}.devbridge-backup-${stamp}`);
+}
+function applyOwnership(target, from) {
+    try {
+        fs.chownSync(target, from.uid, from.gid);
+    }
+    catch {
+        // Не root — владельца не сменить. Файл и так остаётся своего владельца,
+        // потому что мы пишем от его имени; молчим намеренно.
+    }
+}
+function readExisting(file) {
+    try {
+        return { text: fs.readFileSync(file, 'utf8'), stats: fs.statSync(file) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ставит привратника в настройки Claude Code. Возвращает `false`, когда
+ * менять нечего или файл трогать нельзя.
+ *
+ * Отказ никогда не является аварией: раннер обязан подняться и работать даже
+ * на машине, где файл настроек сломан руками.
+ */
+export function installSearchGuard(hookPath, home, warn = () => { }) {
+    const file = claudeSettingsPath(home);
+    const existing = readExisting(file);
+    let merged;
+    try {
+        merged = mergeGuardIntoSettings(existing?.text ?? '{}\n', hookPath);
+    }
+    catch (error) {
+        warn(`search guard: ${file} left untouched — ${error.message}`);
+        return false;
+    }
+    if (!merged.changed)
+        return false;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        if (existing)
+            backup(file);
+        writeAtomically(file, merged.text, existing ? existing.stats.mode & 0o777 : 0o600);
+        if (existing)
+            applyOwnership(file, existing.stats);
+    }
+    catch (error) {
+        warn(`search guard: could not write ${file} — ${error.message}`);
+        return false;
+    }
+    return true;
+}
+/** Снимает привратника. Возвращает `false`, если снимать было нечего. */
+export function removeSearchGuard(home, warn = () => { }) {
+    const file = claudeSettingsPath(home);
+    const existing = readExisting(file);
+    if (!existing)
+        return false;
+    let cleaned;
+    try {
+        cleaned = removeGuardFromSettings(existing.text);
+    }
+    catch (error) {
+        warn(`search guard: ${file} left untouched — ${error.message}`);
+        return false;
+    }
+    if (!cleaned.changed)
+        return false;
+    try {
+        backup(file);
+        writeAtomically(file, cleaned.text, existing.stats.mode & 0o777);
+        applyOwnership(file, existing.stats);
+    }
+    catch (error) {
+        warn(`search guard: could not write ${file} — ${error.message}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Состояние привратника на этой машине — то, что печатает `doctor`.
+ *
+ * Существует ради проверки «дефект починили, можно снимать»: чтобы через месяц
+ * можно было пройтись по паркам и увидеть, где привратник ещё стоит, а где уже
+ * снят, не разбирая JSON руками.
+ */
+export function searchGuardStatus(home) {
+    const file = claudeSettingsPath(home);
+    const existing = readExisting(file);
+    if (!existing)
+        return { path: file, settingsReadable: false, installed: false, version: null };
+    let settings;
+    try {
+        settings = parseSettings(existing.text);
+    }
+    catch {
+        return { path: file, settingsReadable: false, installed: false, version: null };
+    }
+    const groups = settings['hooks']?.['PreToolUse'] ?? [];
+    const ours = groups.find(isOurs);
+    if (!ours)
+        return { path: file, settingsReadable: true, installed: false, version: null };
+    const command = (ours.hooks ?? []).map((h) => h.command).find((c) => c?.includes(GUARD_MARKER));
+    const version = Number.parseInt(command?.split(`${GUARD_MARKER}:`)[1] ?? '', 10);
+    return {
+        path: file,
+        settingsReadable: true,
+        installed: true,
+        version: Number.isFinite(version) ? version : null,
+    };
+}
+//# sourceMappingURL=claude-settings.js.map

package/dist/index.js

@@ -18,6 +18,7 @@ import { readStatusFile, isPidAlive, writeStatusFile, STATUS_FRESH_MS } from './
 import { RunnerWsClient } from './ws-client.js';
 import { RUNNER_VERSION } from './version.js';
 import { buildUnit, cpuQuotaPercent, limitsOverrideIsOutdated, limitsOverridePath, memoryPolicy, readMemoryFacts, unitExecTarget, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
+import { SEARCH_GUARD_ENABLED, claudeSettingsPath, installSearchGuard, removeSearchGuard, searchGuardCommand, searchGuardHome, searchGuardHookPath, searchGuardStatus, } from './claude-settings.js';
 import { readOomKills, recordCrash, takeLastExit } from './crash-note.js';
 import { agentAuthStatuses } from './auth-relay.js';
 import { addSafeDirectory, agentConfigContour, dockerCheck, ensureAgentPath, firstUnreachableAncestor, hasSafeDirectory, inspectPath, knownWorkspacePaths, lingerEnabled, nodeCheck, otherHomeWithAgents, runnerIdentity, safeDirectoryCommand, systemctlHint, systemdUserBusReachable, systemdUserEnv, } from './environment.js';
@@ -534,6 +535,57 @@ async function repairResourceLimits() {
         });
     }
 }
+/**
+ * Приводит настройки Claude Code в соответствие с тем, что решает
+ * `SEARCH_GUARD_ENABLED`. Одна функция на все три точки вызова — старт демона,
+ * `install-service` и `doctor --fix`, — чтобы они не разъехались в поведении.
+ *
+ * Никогда не бросает: раннер обязан подняться и на машине, где файл настроек
+ * сломан руками.
+ */
+function applySearchGuard(report) {
+    try {
+        if (!SEARCH_GUARD_ENABLED) {
+            return removeSearchGuard(searchGuardHome(), report) ? 'removed' : 'unchanged';
+        }
+        // Раннер может быть запущен из дерева разработки, где `dist` не собран.
+        // Запись, указывающая в пустоту, хуже отсутствующей: Claude Code будет
+        // звать несуществующий файл перед каждой командой.
+        if (!fs.existsSync(searchGuardHookPath()))
+            return 'unchanged';
+        return installSearchGuard(searchGuardCommand(), searchGuardHome(), report)
+            ? 'installed'
+            : 'unchanged';
+    }
+    catch (error) {
+        report(`search guard: ${String(error instanceof Error ? error.message : error)}`);
+        return 'unchanged';
+    }
+}
+/**
+ * Ставит (или снимает) привратника шаблонов поиска на старте демона.
+ *
+ * Живёт рядом с `repairResourceLimits` и по тем же правилам: идемпотентно по
+ * маркеру, никогда не фатально. Разница в том, что здесь мы пишем в ЧУЖОЙ файл —
+ * поэтому любое сомнение решается в пользу «не трогать» (`claude-settings.ts`).
+ *
+ * СНЯТИЕ на всём парке: `SEARCH_GUARD_ENABLED = false` и выпуск раннера.
+ */
+function repairSearchGuard() {
+    const outcome = applySearchGuard((message) => log.warn(`daemon: ${message}`));
+    if (outcome === 'installed') {
+        log.warn('daemon: search-pattern guard installed into Claude Code settings', {
+            settings: claudeSettingsPath(searchGuardHome()),
+            command: searchGuardCommand(),
+            why: 'docs/standards/project-gotchas.md §345',
+        });
+    }
+    else if (outcome === 'removed') {
+        log.warn('daemon: search-pattern guard removed from Claude Code settings', {
+            settings: claudeSettingsPath(searchGuardHome()),
+        });
+    }
+}
 /**
  * How often the daemon re-measures the machine after the first time.
  *
@@ -615,6 +667,7 @@ async function cmdDaemon() {
     log.info('daemon starting', { version: RUNNER_VERSION, server: config.server.name });
     sweepOrphanedMcpConfigs();
     await repairResourceLimits();
+    repairSearchGuard();
     // A Claude token this runner captured through the sign-in relay. Applied
     // BEFORE any adapter exists, because `scrubbedEnv()` copies it out of this
     // process's environment for every session it starts.
@@ -787,6 +840,16 @@ async function cmdInstallService() {
     // service rather than from `/proc/self`, which here is the installing shell.
     writeLimitsOverride(true, undefined, readMemoryFacts(await serviceMemoryCurrent()));
     print(`Wrote ${limitsOverridePath()}`);
+    // Привратник шаблонов поиска — та же логика, что и у политики ресурсов:
+    // свежая установка должна получить его сразу. Пишем в ЧУЖОЙ файл настроек,
+    // поэтому молча пропускаем, если тронуть его нельзя (`claude-settings.ts`).
+    const guardOutcome = applySearchGuard(print);
+    if (guardOutcome === 'installed') {
+        print(`Installed search-pattern guard into ${claudeSettingsPath(searchGuardHome())}`);
+    }
+    else if (guardOutcome === 'removed') {
+        print(`Removed search-pattern guard from ${claudeSettingsPath(searchGuardHome())}`);
+    }
     if (!exec.viaCommand) {
         // Worth saying out loud: a unit pinned to a file inside the package directory
         // breaks if that directory ever moves (which a package rename does).
@@ -1249,6 +1312,19 @@ async function cmdDoctor(args) {
     print('Effective (systemd)');
     for (const line of effective)
         print(`  ${line}`);
+    // Привратник шаблонов поиска. Печатается всегда, в том числе когда он ВЫКЛЮЧЕН
+    // в коде: «стоит, хотя выключен» — это и есть та машина, которую пропустило
+    // обновление, и увидеть её больше неоткуда.
+    const guard = searchGuardStatus(searchGuardHome());
+    const guardMismatch = SEARCH_GUARD_ENABLED !== guard.installed;
+    print('');
+    print('Search-pattern guard (Claude Code §345)');
+    print(`  enabled in this runner: ${SEARCH_GUARD_ENABLED ? 'yes' : 'NO — should be removed'}`);
+    print(`  installed on this machine: ${guard.installed ? `yes (v${guard.version ?? '?'})` : 'no'}`);
+    print(`  settings file: ${guard.settingsReadable ? guard.path : `${guard.path} (unreadable or broken)`}`);
+    if (guardMismatch) {
+        print('  MISMATCH — run `devbridge-runner doctor --fix` to reconcile');
+    }
     // The two settings that turned one agent's OOM into a dead server.
     const bad = effective.filter((l) => (l.startsWith('OOMPolicy=') && !l.endsWith('=continue')) ||
         (l.startsWith('MemoryMax=') && !l.endsWith('=infinity')) ||
@@ -1286,9 +1362,13 @@ async function cmdDoctor(args) {
         print(`Previous process exit: ${LAST_EXIT.kind}${LAST_EXIT.at ? ` at ${LAST_EXIT.at}` : ''}`);
     }
     if (!fix) {
-        if (outdated || bad.length > 0) {
+        if (outdated || bad.length > 0 || guardMismatch) {
             print('');
             print('Run `devbridge-runner doctor --fix` to write the drop-in, then restart the service.');
+            // `guardMismatch` попадает сюда намеренно: весь смысл `searchGuardStatus` —
+            // обойти парк и найти машины, которых обновление не достало. Машина, где
+            // привратник не встал, не должна выглядеть здоровой для автоматики
+            // (QA LOW-12).
             process.exit(1);
         }
         // A readiness problem is a real finding too: exiting 0 over «the agent has
@@ -1302,6 +1382,13 @@ async function cmdDoctor(args) {
     writeLimitsOverride(true, undefined, fixFacts);
     print('');
     print(`Wrote ${limitsOverridePath()}`);
+    const guardOutcome = applySearchGuard(print);
+    if (guardOutcome === 'installed') {
+        print(`Installed search-pattern guard into ${claudeSettingsPath(searchGuardHome())}`);
+    }
+    else if (guardOutcome === 'removed') {
+        print(`Removed search-pattern guard from ${claudeSettingsPath(searchGuardHome())}`);
+    }
     // Say it out loud when the ceiling had to be raised above the honest answer to
     // avoid killing whatever is running right now. Lowering a ceiling under load is
     // a decision, not a side effect of running a diagnostic — and without this line