devcontour-harness 0.1.0-alpha.28 → 0.1.0-alpha.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.28` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.29` — предварительный выпуск (alpha). Договоры
9
9
  > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
10
10
  > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
11
11
  > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
28
28
  Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
29
29
 
30
30
  ```sh
31
- npm install --save-exact devcontour-harness@0.1.0-alpha.28 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.29 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -124,6 +124,12 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
124
124
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
125
125
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
126
126
 
127
+ ## Выпуск 0.1.0-alpha.29
128
+
129
+ Проверки под нагрузкой машины стартуют надёжно, а несостоявшийся старт песочницы
130
+ назван отказом среды; копия хранилища зависимостей готовится примерно в 4 раза быстрее.
131
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.29.md).
132
+
127
133
  ## Выпуск 0.1.0-alpha.28
128
134
 
129
135
  Файлы, которые gate оставляет в дереве (скриншоты, отчёты), сохраняются как
@@ -673,6 +673,22 @@ executable. Live smoke — отдельный opt-in с явно заданны
673
673
  проверки отличаются от чужих. Текст вывода свидетельством не служит, запись
674
674
  вне дерева — ошибка кода (`gate`). На Linux такого свидетельства нет, и
675
675
  отказ остаётся `gate`.
676
+ - **Запуск песочницы.** Признак старта — токен, который обёртка внутри
677
+ песочницы печатает в stderr перед `exec` команды, и метка-файл рядом.
678
+ Токен ищется и вырезается в сыром stderr до маски секретов: маска по
679
+ значениям окружения (`1`, `8080`) иначе задевала бы его. Метку команда
680
+ может стереть — каталог метки ей открыт на запись, — а напечатанный токен
681
+ нет; подделка токена лишь признаёт старт. Без токена и метки команда точно
682
+ не начиналась: запуск повторяется (до трёх попыток с паузой 0,5 и 1 с).
683
+ Если песочница не запустила её и тогда, а весь stderr состоит только из
684
+ строк известного отказа запуска srt (поиск shell или порождение процесса
685
+ песочницы), gate не проходит с классом `environment`; прочие отказы srt до
686
+ старта могут зависеть от содержимого дерева (на Linux — сборка запретов и
687
+ монтирований по дереву) и остаются `gate`. На Linux эта классификация не
688
+ проверялась. Процесс srt находит shell по PATH сам, только в абсолютных
689
+ каталогах: srt ищет его через `which` с таймаутом в секунду, и под
690
+ нагрузкой машины такой поиск отказывал до запуска команды. Не найденный
691
+ так shell по-прежнему ищет `which`.
676
692
  - **Корень рабочих деревьев.** При состоянии внутри репозитория checkout
677
693
  размещается в кэше пользователя вне дерева; хост может задать
678
694
  `checkoutRoot`. Корень не должен ни лежать внутри репозитория, состояния
@@ -0,0 +1,32 @@
1
+ # devcontour-harness 0.1.0-alpha.29
2
+
3
+ Проверки в песочнице ОС больше не срываются под нагрузкой машины, а копия
4
+ хранилища зависимостей готовится примерно в 4 раза быстрее. Обязательные gates,
5
+ fencing, привязка доказательств к SHA и граница доверия хранилища не меняются.
6
+
7
+ ## Изменения
8
+
9
+ - **Старт песочницы под нагрузкой.** sandbox-runtime искал shell через `which`
10
+ с таймаутом в секунду на каждый запуск; под нагрузкой проверка не стартовала
11
+ с ошибкой «Shell 'bash' not found in PATH», похожей на провал проекта. Теперь
12
+ shell находится без дочернего процесса и только в абсолютных каталогах PATH.
13
+ - **Доказанный старт.** Обёртка печатает в stderr случайный токен перед `exec`;
14
+ он ищется в сыром потоке до маски секретов. Команда, стёршая свою метку
15
+ старта, больше не считается не запущенной и не повторяется.
16
+ - **Отказ среды вместо провала проекта.** Если песочница так и не запустила
17
+ команду, а stderr состоит только из известных строк отказа запуска, gate
18
+ получает класс `environment` с понятным сообщением; probe reviewer —
19
+ `error`/`environment`. Прочие отказы до старта остаются провалом проверки.
20
+ На Linux классификация не проверялась.
21
+ - **Хранилище зависимостей быстрее.** На macOS копия seed делается одним
22
+ `clonefile(2)` каталога (при отказе — прежними порциями `cp -c`), байты и права
23
+ копии сверяются с закреплённым манифестом в пуле потоков. Seed 433 МБ /
24
+ 36 690 файлов: подготовка копии 2,35 с вместо 9,2 с.
25
+ - **Новый отказ.** Файл seed с setuid, setgid или sticky отклоняется (pnpm таких
26
+ не создаёт); удаление копий снимает BSD-флаги вроде `uchg`.
27
+
28
+ ## Обновление
29
+
30
+ Пакет alpha.28 остаётся неизменным. Форматы состояния, политики и манифест seed
31
+ прежние; seeds и копии подходят обеим версиям. Откат возвращает прежний поиск
32
+ shell и прежнюю классификацию отказов запуска (`gate`).
@@ -75,14 +75,14 @@ To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"
75
75
 
76
76
  ## Статусы
77
77
 
78
- | `status` | `failure` | Смысл |
79
- | ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
80
- | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
- | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
- | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
- | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы |
84
- | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
- | `budget-exhausted`, `rejected` | — | команда не запускалась |
78
+ | `status` | `failure` | Смысл |
79
+ | ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
+ | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
+ | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
+ | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы, песочница не запустила команду |
84
+ | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
+ | `budget-exhausted`, `rejected` | — | команда не запускалась |
86
86
 
87
87
  Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
88
88
  `failure: environment`, не получает `observed`.
@@ -109,8 +109,11 @@ target ref.
109
109
  ### Граница старта
110
110
 
111
111
  Запуск probe засчитывается по признаку `started` из `runCheck`: без песочницы — процесс порождён
112
- (событие `spawn`), в песочнице — обёртка создала метку старта перед `exec` (запуск самой обёртки
113
- не считается). Признак отмечается на границе и переживает исключение после неё.
112
+ (событие `spawn`), в песочнице — обёртка напечатала токен старта в stderr или создала метку перед
113
+ `exec` (запуск самой обёртки не считается). Признак отмечается на границе и переживает исключение
114
+ после неё. Без токена и метки запуск повторяется (до трёх попыток); песочница, так и не запустившая
115
+ команду, когда весь stderr — только строки известного отказа запуска srt (`Error: Shell '…' not
116
+ found in PATH`, `Failed to execute command: …`), даёт `error`/`environment`.
114
117
 
115
118
  | Событие | В `commands` |
116
119
  | ----------------------------------------------------------------------------------------- | ------------ |
@@ -150,6 +150,10 @@ Isolation `os` пишет только в worktree и временный кат
150
150
  2. Seed клонируется в `<checkout>/.pnpm-store` (копия-при-записи на APFS и reflink-томах, иначе
151
151
  обычная копия, если хватает места), копия сверяется с манифестом, менеджер получает путь через
152
152
  `npm_config_store_dir`. Каталог скрыт от git собственным `.gitignore`.
153
+ На macOS клон делается одним `clonefile(2)` всего каталога (через `/usr/bin/osascript`;
154
+ если вызов не удался — `cp -c` порциями), а сверка читает и хэширует файлы копии в
155
+ нескольких потоках: seed из 37 тысяч файлов и 430 МБ на APFS разворачивается и сверяется
156
+ примерно за 2–3 с, а не за 8–9.
153
157
  3. Gate установки — обычный `pnpm install --frozen-lockfile`. Он берёт пакеты из копии, а чего нет,
154
158
  скачивает через прокси песочницы.
155
159
 
@@ -178,7 +182,14 @@ Isolation `os` пишет только в worktree и временный кат
178
182
  кандидата не исполняют. `doctor` предупреждает о `dependencyStore` рядом с непустым `prepare`.
179
183
  - Seeds лежат под корнем рабочих деревьев или в каталоге состояния, закрытых песочницей на чтение
180
184
  и запись. Манифест закреплён digest в базе ресурсов, вне дерева seed.
181
- - Проверяются байты копии, а не источника: те, что прочитает менеджер.
185
+ - Проверяются байты копии, а не источника: те, что прочитает менеджер. Ускорение этого не
186
+ меняет: каждый файл копии открывается с `O_NOFOLLOW`, а хэш, права и тип берутся с того же
187
+ дескриптора, что и байты; ссылка, каталог или канал на месте файла — отказ. `O_NOFOLLOW`
188
+ защищает только последний компонент пути: каталог по пути к файлу, подменённый ссылкой между
189
+ обходом и чтением, не обнаруживается. Такая подмена требует процесса, который пишет в checkout
190
+ во время развёртывания, то есть до `prepare` и gates этого checkout; это вне модели угроз,
191
+ как и прежде (прежние `lstat` и `readFile` следовали и по последнему компоненту). Setuid, setgid и sticky у файлов seed — отказ, BSD-флаги вроде `uchg`
192
+ копия наследует, как и при `cp -c`, а удаление копии и seed их снимает.
182
193
  - Копия принадлежит своему checkout, в seed ничего не возвращается. Integration и следующая попытка
183
194
  получают новую копию. Поэтому байты seed проверены всегда, а докачанные байты и всё, что
184
195
  исполнитель изменил в своём дереве, доверены не больше, чем его `node_modules`: они не выходят
package/docs/upgrade.md CHANGED
@@ -189,6 +189,37 @@ gate и в записи совместной проверки прежние в
189
189
  Подробнее — [заметки выпуска](release-notes/0.1.0-alpha.28.md) и
190
190
  [договоры](contracts.md#executionpolicy).
191
191
 
192
+ ### alpha.29: запуск песочницы проверок
193
+
194
+ Форматы состояния, политики и публичные поля API прежние. sandbox-runtime
195
+ искал shell через `which` с таймаутом в секунду на каждый запуск проверки; под
196
+ нагрузкой машины поиск не успевал, и проверка не стартовала с ошибкой
197
+ «Shell 'bash' not found in PATH». Теперь процесс srt находит shell по PATH сам,
198
+ без порождения `which`, и только в абсолютных каталогах PATH; не найденный
199
+ shell по-прежнему ищет `which`. Старт команды доказывает токен, который обёртка
200
+ печатает в stderr перед `exec`; он ищется и вырезается в сыром потоке до маски
201
+ секретов: стёртая командой
202
+ метка-файл больше не выдаёт стартовавшую команду за не запущенную, и такая
203
+ команда не повторяется. Если песочница не запустила команду и после повторов
204
+ (до трёх попыток, только пока нет ни метки, ни токена), а весь stderr — только
205
+ строки известного отказа запуска srt (`Error: Shell '…' not found in PATH`,
206
+ `Failed to execute command: …`), gate не
207
+ проходит с классом `environment` и сообщением «песочница ОС не запустила
208
+ команду проверки», а не как провал проекта с кодом выхода; probe reviewer в
209
+ этом случае — `error`/`environment`. Прочие отказы srt до старта остаются
210
+ провалом проверки (`gate`). При откате возвращается прежний поиск shell и
211
+ прежняя классификация (`gate`).
212
+
213
+ ### alpha.29: быстрее копия хранилища зависимостей
214
+
215
+ Форматы состояния, манифест seed, политика и граница доверия прежние: сверяются
216
+ те же байты и права копии по тому же закреплённому манифесту. На macOS копия
217
+ делается одним `clonefile(2)` каталога через `/usr/bin/osascript`, при его отказе —
218
+ прежними порциями `cp -c`; сверка идёт в потоках. Новое: файл seed с setuid,
219
+ setgid или sticky — отказ (pnpm таких не создаёт). Откат — установка прежней
220
+ версии, seeds и копии подходят обеим. Подробнее —
221
+ [хранилище зависимостей](toolchains.md#хранилище-зависимостей).
222
+
192
223
  ## Перед обновлением
193
224
 
194
225
  1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
@@ -408,6 +408,16 @@ export class ReviewProbes {
408
408
  ...(gate ? { failure: 'environment' } : {}),
409
409
  }
410
410
  : {};
411
+ // Песочница так и не запустила команду: исполнять было нечего.
412
+ if (r.launchFailed && !r.timedOut && !signal.aborted)
413
+ return {
414
+ status: 'error',
415
+ failure: 'environment',
416
+ exitCode: r.code,
417
+ stdout: tail(r.stdout),
418
+ stderr: tail(r.stderr),
419
+ note: `Песочница ОС не запустила команду (попыток: ${r.attempts}): команда не исполнялась. Это ошибка среды, а не находка в коде.`,
420
+ };
411
421
  return {
412
422
  ...hint,
413
423
  status: signal.aborted
@@ -569,6 +579,14 @@ export class ReviewProbes {
569
579
  status: 'timeout',
570
580
  note: `Gate не завершился за ${limitMs} мс и остановлен вместе с потомками; это наблюдение, а не доказанный дефект. ${observation}`,
571
581
  };
582
+ else if (r.launchFailed)
583
+ outcome = {
584
+ ...base,
585
+ ...streams,
586
+ status: 'error',
587
+ failure: 'environment',
588
+ note: `Песочница ОС не запустила gate (попыток: ${r.attempts}): команда не исполнялась. Это ошибка среды, а не находка в коде.`,
589
+ };
572
590
  else if (blocked.length)
573
591
  outcome = {
574
592
  ...base,
@@ -94,6 +94,22 @@ export declare const claudeFileTools: string[];
94
94
  * исполнителя нужна запись вне проверяемого кода.
95
95
  */
96
96
  export declare function codexPermissions(policy: Isolation, network: boolean): string[];
97
+ /**
98
+ * Предзагрузка процесса srt: поиск shell без порождения `which`.
99
+ *
100
+ * srt на каждый запуск ищет shell через `spawnSync('which', [shell],
101
+ * { timeout: 1000 })`. Под нагрузкой машины порождение `which` не
102
+ * укладывается в секунду, srt печатает «Shell 'bash' not found in PATH» и
103
+ * выходит до запуска команды: проверка падала как будто по вине проекта.
104
+ * Передать srt путь shell нельзя: у CLI такой опции нет, а абсолютный путь
105
+ * он тоже проверяет через `which`. Поэтому такой вызов отвечается в процессе
106
+ * srt: исполняемый файл ищется по тому же PATH, что у `which`, но только в
107
+ * абсолютных каталогах — относительный или пустой элемент PATH указывает на
108
+ * текущий каталог, то есть, возможно, в проверяемое дерево. Не найденное и
109
+ * любые другие вызовы уходят в настоящий `spawnSync` — ответ «нет такого
110
+ * shell» по-прежнему даёт `which`, а не эта подмена.
111
+ */
112
+ export declare const srtShellLookup: string;
97
113
  /** Готов ли механизм изоляции проверок на этой машине. */
98
114
  export declare function isolationSupport(): {
99
115
  ok: boolean;
@@ -252,7 +268,13 @@ protect?: string[], platform?: NodeJS.Platform,
252
268
  * Токен в начале команды: srt кладёт начало команды в тег записей журнала
253
269
  * ядра, и по нему отказы этой проверки отличаются от чужих (`parseSandboxLog`).
254
270
  */
255
- tag?: string): Promise<{
271
+ tag?: string,
272
+ /**
273
+ * Токен старта: обёртка печатает его строкой в stderr перед exec команды.
274
+ * Метку-файл команда может стереть (каталог метки ей открыт на запись), а
275
+ * напечатанное до неё — нет: токен в выводе доказывает старт.
276
+ */
277
+ token?: string): Promise<{
256
278
  argv: string[];
257
279
  env: {
258
280
  TMPDIR: string;
@@ -187,6 +187,54 @@ export function codexPermissions(policy, network) {
187
187
  ];
188
188
  }
189
189
  const srtCli = createRequire(import.meta.url).resolve('@anthropic-ai/sandbox-runtime/dist/cli.js');
190
+ /**
191
+ * Предзагрузка процесса srt: поиск shell без порождения `which`.
192
+ *
193
+ * srt на каждый запуск ищет shell через `spawnSync('which', [shell],
194
+ * { timeout: 1000 })`. Под нагрузкой машины порождение `which` не
195
+ * укладывается в секунду, srt печатает «Shell 'bash' not found in PATH» и
196
+ * выходит до запуска команды: проверка падала как будто по вине проекта.
197
+ * Передать srt путь shell нельзя: у CLI такой опции нет, а абсолютный путь
198
+ * он тоже проверяет через `which`. Поэтому такой вызов отвечается в процессе
199
+ * srt: исполняемый файл ищется по тому же PATH, что у `which`, но только в
200
+ * абсолютных каталогах — относительный или пустой элемент PATH указывает на
201
+ * текущий каталог, то есть, возможно, в проверяемое дерево. Не найденное и
202
+ * любые другие вызовы уходят в настоящий `spawnSync` — ответ «нет такого
203
+ * shell» по-прежнему даёт `which`, а не эта подмена.
204
+ */
205
+ export const srtShellLookup = 'data:text/javascript,' +
206
+ encodeURIComponent(`
207
+ import cp from 'node:child_process';
208
+ import { syncBuiltinESMExports } from 'node:module';
209
+ import { accessSync, constants, statSync } from 'node:fs';
210
+ import { delimiter, isAbsolute, join } from 'node:path';
211
+ const original = cp.spawnSync;
212
+ const find = (bin, path) => {
213
+ if (bin.includes('/') && !isAbsolute(bin)) return;
214
+ const dirs = bin.includes('/') ? [''] : (path ?? '').split(delimiter).filter((d) => isAbsolute(d));
215
+ for (const dir of dirs) {
216
+ const file = dir ? join(dir, bin) : bin;
217
+ try {
218
+ if (!statSync(file).isFile()) continue;
219
+ accessSync(file, constants.X_OK);
220
+ return file;
221
+ } catch {}
222
+ }
223
+ };
224
+ cp.spawnSync = function spawnSync(command, args, options) {
225
+ if (command === 'which' && Array.isArray(args) && args.length === 1 &&
226
+ typeof args[0] === 'string' && args[0] && !args[0].startsWith('-') &&
227
+ options?.encoding === 'utf8') {
228
+ const file = find(args[0], (options.env ?? process.env).PATH);
229
+ if (file) {
230
+ const stdout = file + '\\n';
231
+ return { pid: 0, output: [null, stdout, ''], stdout, stderr: '', status: 0, signal: null };
232
+ }
233
+ }
234
+ return original.apply(this, arguments);
235
+ };
236
+ syncBuiltinESMExports();
237
+ `);
190
238
  /** Готов ли механизм изоляции проверок на этой машине. */
191
239
  export function isolationSupport() {
192
240
  if (!SandboxManager.isSupportedPlatform())
@@ -667,9 +715,17 @@ protect = [workdir], platform = process.platform,
667
715
  * Токен в начале команды: srt кладёт начало команды в тег записей журнала
668
716
  * ядра, и по нему отказы этой проверки отличаются от чужих (`parseSandboxLog`).
669
717
  */
670
- tag = '') {
718
+ tag = '',
719
+ /**
720
+ * Токен старта: обёртка печатает его строкой в stderr перед exec команды.
721
+ * Метку-файл команда может стереть (каталог метки ей открыт на запись), а
722
+ * напечатанное до неё — нет: токен в выводе доказывает старт.
723
+ */
724
+ token = '') {
671
725
  if (!/^[a-z0-9]*$/.test(tag))
672
726
  throw new Error('Токен журнала песочницы — только [a-z0-9]');
727
+ if (!/^[a-z0-9]*$/.test(token))
728
+ throw new Error('Токен старта — только [a-z0-9]');
673
729
  await mkdir(settingsDir, { recursive: true });
674
730
  const settings = join(settingsDir, 'isolation.json');
675
731
  const denies = platform === 'darwin' ? protectedWriteDenies(protect) : undefined;
@@ -685,14 +741,17 @@ tag = '') {
685
741
  return {
686
742
  argv: [
687
743
  process.execPath,
744
+ '--import',
745
+ srtShellLookup,
688
746
  srtCli,
689
747
  '--settings',
690
748
  settings,
691
749
  '--',
692
750
  '/bin/sh',
693
751
  '-c',
694
- `${tag ? `: ${tag}; ` : ''}: > "$0" && cd -- "$1" && shift && exec "$@"`,
752
+ `${tag ? `: ${tag}; ` : ''}: > "$0" && { [ -z "$1" ] || printf '%s\\n' "$1" >&2; } && cd -- "$2" && shift 2 && exec "$@"`,
695
753
  started,
754
+ token,
696
755
  workdir,
697
756
  '/usr/bin/env',
698
757
  `TMPDIR=${scratch}`,
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`),
3
- * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`). Они ищутся по фиксированным абсолютным путям
3
+ * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`, `osascript`, `chflags`). Они ищутся по фиксированным абсолютным путям
4
4
  * ОС раньше PATH: урезанный PATH (только node и git) не лишает ядро
5
5
  * containment, а файл из проекта или worktree с тем же именем не
6
6
  * запускается. PATH — только запасной путь, когда ни одного штатного
@@ -12,6 +12,8 @@ export declare const OS_TOOL_CANDIDATES: {
12
12
  readonly sysctl: readonly ["/usr/sbin/sysctl", "/sbin/sysctl", "/usr/bin/sysctl"];
13
13
  readonly cp: readonly ["/bin/cp", "/usr/bin/cp"];
14
14
  readonly df: readonly ["/bin/df", "/usr/bin/df"];
15
+ readonly osascript: readonly ["/usr/bin/osascript"];
16
+ readonly chflags: readonly ["/usr/bin/chflags"];
15
17
  };
16
18
  export type OsTool = keyof typeof OS_TOOL_CANDIDATES;
17
19
  /** Исполняемый файл утилиты: первый существующий штатный путь, иначе имя для PATH. */
@@ -1,7 +1,7 @@
1
1
  import { accessSync, constants } from 'node:fs';
2
2
  /**
3
3
  * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`),
4
- * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`). Они ищутся по фиксированным абсолютным путям
4
+ * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`, `osascript`, `chflags`). Они ищутся по фиксированным абсолютным путям
5
5
  * ОС раньше PATH: урезанный PATH (только node и git) не лишает ядро
6
6
  * containment, а файл из проекта или worktree с тем же именем не
7
7
  * запускается. PATH — только запасной путь, когда ни одного штатного
@@ -13,6 +13,8 @@ export const OS_TOOL_CANDIDATES = {
13
13
  sysctl: ['/usr/sbin/sysctl', '/sbin/sysctl', '/usr/bin/sysctl'],
14
14
  cp: ['/bin/cp', '/usr/bin/cp'],
15
15
  df: ['/bin/df', '/usr/bin/df'],
16
+ osascript: ['/usr/bin/osascript'],
17
+ chflags: ['/usr/bin/chflags'],
16
18
  };
17
19
  const resolved = new Map();
18
20
  /** Исполняемый файл утилиты: первый существующий штатный путь, иначе имя для PATH. */
@@ -20,6 +20,12 @@ export declare function command(argv: string[], cwd: string, options?: {
20
20
  * служебные строки JSON. Сохранять его нельзя.
21
21
  */
22
22
  onRawStdout?: (text: string) => void;
23
+ /**
24
+ * Фильтр stderr до маски: получает сырой текст (`final` — последний
25
+ * кусок) и возвращает то, что идёт дальше в маску и вывод. Служебные
26
+ * строки ищутся здесь: маска по значениям окружения могла бы их исказить.
27
+ */
28
+ rawStderr?: (text: string, final: boolean) => string;
23
29
  /** Процесс запущен (событие `spawn`): до него команда не исполнялась. */
24
30
  onSpawn?: () => void;
25
31
  /**
@@ -59,7 +59,8 @@ export async function command(argv, cwd, options = {}) {
59
59
  });
60
60
  child.stderr.on('data', (d) => {
61
61
  lastOutputAt = new Date().toISOString();
62
- append('stderr', maskErr(stderrDecoder.write(d)));
62
+ const raw = stderrDecoder.write(d);
63
+ append('stderr', maskErr(options.rawStderr ? options.rawStderr(raw, false) : raw));
63
64
  });
64
65
  const signalGroup = (signal) => {
65
66
  try {
@@ -170,7 +171,8 @@ export async function command(argv, cwd, options = {}) {
170
171
  const rest = stdoutDecoder.end();
171
172
  options.onRawStdout?.(rest);
172
173
  append('stdout', maskOut(rest, true));
173
- append('stderr', maskErr(stderrDecoder.end(), true));
174
+ const restErr = stderrDecoder.end();
175
+ append('stderr', maskErr(options.rawStderr ? options.rawStderr(restErr, true) : restErr, true));
174
176
  if (outputError) {
175
177
  reject(outputError);
176
178
  return;
@@ -96,8 +96,20 @@ export declare const storeTree: {
96
96
  */
97
97
  cloneable(from: string, to: string, sample: string, signal: AbortSignal): Promise<boolean>;
98
98
  freeBytes(path: string): Promise<number>;
99
- /** Копия-при-записи порциями: один `cp` на всё дерево вдвое медленнее. */
99
+ /**
100
+ * Копия-при-записи. На macOS — один `clonefile(2)` всего каталога: ядро клонирует
101
+ * дерево целиком, в разы быстрее `cp -c`, который клонирует по одному файлу.
102
+ * Не вышло — порции `cp`, как на Linux: один `cp` на всё дерево вдвое медленнее.
103
+ */
100
104
  clone(from: string, to: string, signal: AbortSignal): Promise<void>;
105
+ /**
106
+ * `clonefile(2)` каталога `from` в свободный путь `to`; `false` — не вышло, и `to`
107
+ * не осталось. В Node вызова нет, поэтому он идёт через JavaScript for Automation
108
+ * (`osascript` есть в каждой macOS). Тест подменяет способ, чтобы проверить порции.
109
+ */
110
+ cloneDirectory(from: string, to: string, signal: AbortSignal): Promise<boolean>;
111
+ /** Путь `osascript`; тест подменяет его, чтобы проверить отказ запуска. */
112
+ osascript: () => string;
101
113
  copy(from: string, to: string): Promise<void>;
102
114
  };
103
115
  /**
@@ -12,6 +12,7 @@ import { processStartedAt } from "../environment/live-calls.js";
12
12
  import { command, gitOutput } from "../environment/process.js";
13
13
  import { ResourcePool, resourceKey } from "../environment/resources.js";
14
14
  import { declaredManagerVersion, defaultProbe, dependencyStoreSupports, dependencyStoreVersions, versionOf, } from "../toolchains/probe.js";
15
+ import { fileDigests, NotRegularFile } from "./file-digests.js";
15
16
  import { runCheck } from "./gates.js";
16
17
  const managers = {
17
18
  pnpm: {
@@ -96,42 +97,55 @@ const within = async (items, limit, action) => {
96
97
  if (worker.status === 'rejected')
97
98
  throw worker.reason;
98
99
  };
99
- /** Файлы дерева. Ссылка и всё, что не обычный файл, — отказ: seed их не содержит. */
100
+ /** Пути файлов дерева. Ссылка и всё, что не обычный файл, — отказ: seed их не содержит. */
100
101
  async function regularFiles(root) {
101
102
  const top = await lstat(root);
102
103
  if (!top.isDirectory())
103
104
  throw new SeedRefused('корень хранилища — не каталог');
104
105
  const files = [];
105
106
  const walk = async (prefix) => {
107
+ const dirs = [];
106
108
  for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
107
109
  const rel = prefix ? prefix + '/' + entry.name : entry.name;
108
110
  if (entry.isDirectory())
109
- await walk(rel);
110
- else if (entry.isFile()) {
111
- const st = await lstat(join(root, rel));
112
- files.push({ rel, mode: st.mode & 0o777, size: st.size });
113
- }
111
+ dirs.push(rel);
112
+ else if (entry.isFile())
113
+ files.push(rel);
114
114
  else
115
115
  throw new SeedRefused(`в хранилище не обычный файл: ${rel}`);
116
116
  }
117
+ await within(dirs, FILE_CONCURRENCY, walk);
117
118
  };
118
119
  await walk('');
119
120
  return files;
120
121
  }
121
122
  class SeedRefused extends Error {
122
123
  }
123
- async function fingerprint(root) {
124
+ /**
125
+ * Хэш, права и размер каждого файла — с того же дескриптора, что и байты
126
+ * (`fileDigests`): файл, ставший ссылкой между обходом и чтением, не читается.
127
+ * Setuid, setgid и sticky — отказ: менеджер их не ставит, а манифест хранит только
128
+ * `0o777`, и копия с ними отличалась бы от сверенной.
129
+ */
130
+ async function fingerprint(root, signal) {
124
131
  const list = await regularFiles(root);
132
+ const digests = await fileDigests(root, list, signal).catch((error) => {
133
+ throw error instanceof NotRegularFile ? new SeedRefused(error.message) : error;
134
+ });
125
135
  // Map, а не объект: файл `__proto__` не должен исчезнуть из отпечатка.
126
136
  const files = new Map();
127
- await within(list, FILE_CONCURRENCY, async (f) => {
128
- files.set(f.rel, [sha256(await readFile(join(root, f.rel))), f.mode]);
129
- });
130
- return { files, bytes: list.reduce((sum, f) => sum + f.size, 0) };
137
+ let bytes = 0;
138
+ for (const f of digests) {
139
+ if (f.mode & 0o7000)
140
+ throw new SeedRefused(`особые права ${f.rel}`);
141
+ files.set(f.rel, [f.sha256, f.mode & 0o777]);
142
+ bytes += f.size;
143
+ }
144
+ return { files, bytes };
131
145
  }
132
146
  /** Дерево в точности равно манифесту: тот же набор файлов, байты и права. */
133
- async function assertMatches(root, manifest) {
134
- const { files } = await fingerprint(root);
147
+ async function assertMatches(root, manifest, signal) {
148
+ const { files } = await fingerprint(root, signal);
135
149
  const expected = Object.keys(manifest.files);
136
150
  if (files.size !== expected.length)
137
151
  throw new SeedRefused(`набор файлов изменён: ${files.size} вместо ${expected.length}`);
@@ -146,6 +160,29 @@ async function assertMatches(root, manifest) {
146
160
  throw new SeedRefused(`изменены права ${rel}`);
147
161
  }
148
162
  }
163
+ /**
164
+ * Удалить дерево. Клон (и `cp -c`) переносит BSD-флаги вроде `uchg`, с которыми
165
+ * `rm` получает EPERM: на macOS флаги снимаются без перехода по ссылкам, и удаление
166
+ * повторяется.
167
+ */
168
+ async function removeTree(path) {
169
+ try {
170
+ await rm(path, { recursive: true, force: true });
171
+ }
172
+ catch (error) {
173
+ const code = error.code;
174
+ const chflags = osTool('chflags');
175
+ if (process.platform !== 'darwin' || (code !== 'EPERM' && code !== 'EACCES'))
176
+ throw error;
177
+ if (!chflags.startsWith('/'))
178
+ throw error;
179
+ await command([chflags, '-R', '-P', '0', path], dirname(path), { timeoutMs: 120000 });
180
+ await rm(path, { recursive: true, force: true });
181
+ }
182
+ }
183
+ /** `clonefile(2)` на JXA: печатает результат вызова, `0` — успех. */
184
+ const CLONEFILE_JXA = "function run(argv){ObjC.bindFunction('clonefile',['int',['char *','char *','unsigned int']]);" +
185
+ 'return String($.clonefile(argv[0],argv[1],0))}';
149
186
  /** Способы размещения дерева; тест подменяет `cloneable`, чтобы проверить обычную копию. */
150
187
  export const storeTree = {
151
188
  /**
@@ -192,8 +229,14 @@ export const storeTree = {
192
229
  const free = await statfs(path);
193
230
  return Number(free.bavail) * Number(free.bsize);
194
231
  },
195
- /** Копия-при-записи порциями: один `cp` на всё дерево вдвое медленнее. */
232
+ /**
233
+ * Копия-при-записи. На macOS — один `clonefile(2)` всего каталога: ядро клонирует
234
+ * дерево целиком, в разы быстрее `cp -c`, который клонирует по одному файлу.
235
+ * Не вышло — порции `cp`, как на Linux: один `cp` на всё дерево вдвое медленнее.
236
+ */
196
237
  async clone(from, to, signal) {
238
+ if (process.platform === 'darwin' && (await storeTree.cloneDirectory(from, to, signal)))
239
+ return;
197
240
  const batches = [];
198
241
  const expand = async (src, dst, depth) => {
199
242
  await mkdir(dst, { recursive: true });
@@ -216,11 +259,42 @@ export const storeTree = {
216
259
  throw new Error(`Клонирование не удалось: ${done.stderr.trim()}`);
217
260
  });
218
261
  },
262
+ /**
263
+ * `clonefile(2)` каталога `from` в свободный путь `to`; `false` — не вышло, и `to`
264
+ * не осталось. В Node вызова нет, поэтому он идёт через JavaScript for Automation
265
+ * (`osascript` есть в каждой macOS). Тест подменяет способ, чтобы проверить порции.
266
+ */
267
+ async cloneDirectory(from, to, signal) {
268
+ const tool = storeTree.osascript();
269
+ // Не штатный путь — значит, из PATH: такой файл может принадлежать проекту.
270
+ if (!tool.startsWith('/') || (await lstat(to).catch(() => undefined)))
271
+ return false;
272
+ try {
273
+ const done = await command([tool, '-l', 'JavaScript', '-e', CLONEFILE_JXA, from, to], from, {
274
+ signal,
275
+ timeoutMs: 120000,
276
+ });
277
+ if (done.code === 0 && done.stdout.trim() === '0')
278
+ return true;
279
+ }
280
+ catch (error) {
281
+ // Запуск запрещён (EPERM, EACCES от контроля исполнения) — это не отказ
282
+ // хранилища, а повод клонировать по-старому.
283
+ if (signal.aborted)
284
+ throw error;
285
+ }
286
+ signal.throwIfAborted();
287
+ // Путь `to` перед вызовом был свободен: всё, что там есть, оставил clonefile.
288
+ await removeTree(to);
289
+ return false;
290
+ },
291
+ /** Путь `osascript`; тест подменяет его, чтобы проверить отказ запуска. */
292
+ osascript: () => osTool('osascript'),
219
293
  async copy(from, to) {
220
294
  const files = await regularFiles(from);
221
295
  await mkdir(to, { recursive: true });
222
- await within([...new Set(files.map((f) => dirname(join(to, f.rel))))].sort(), FILE_CONCURRENCY, async (dir) => void (await mkdir(dir, { recursive: true })));
223
- await within(files, FILE_CONCURRENCY, (f) => copyFile(join(from, f.rel), join(to, f.rel), constants.COPYFILE_EXCL));
296
+ await within([...new Set(files.map((rel) => dirname(join(to, rel))))].sort(), FILE_CONCURRENCY, async (dir) => void (await mkdir(dir, { recursive: true })));
297
+ await within(files, FILE_CONCURRENCY, (rel) => copyFile(join(from, rel), join(to, rel), constants.COPYFILE_EXCL));
224
298
  },
225
299
  };
226
300
  /** Элементы дерева вне `node_modules` и `.git`: столько же насчитает сверка защищённых путей. */
@@ -250,7 +324,7 @@ async function place(seed, to, signal) {
250
324
  throw new Error(`копия seed не помещается: нужно ${seed.manifest.bytes} байт, свободно ${available}`);
251
325
  await storeTree.copy(seed.store, to);
252
326
  }
253
- await assertMatches(to, seed.manifest);
327
+ await assertMatches(to, seed.manifest, signal);
254
328
  return cloned ? 'clone' : 'copy';
255
329
  }
256
330
  const pool = (s, action) => {
@@ -267,7 +341,7 @@ async function dropSeed(s, key) {
267
341
  const trash = join(s.root, 'tmp', randomUUID());
268
342
  await mkdir(dirname(trash), { recursive: true });
269
343
  await rename(join(s.root, 'seeds', key), trash).catch(() => undefined);
270
- await rm(trash, { recursive: true, force: true });
344
+ await removeTree(trash);
271
345
  pool(s, (p) => p.setSeedPin(s.root, key, undefined));
272
346
  }
273
347
  const refuse = async (s, key, why) => {
@@ -424,7 +498,7 @@ const buildFloor = (s) => Math.min(storeTree.minBuildMs, s.fullBudgetMs * FULL_B
424
498
  async function fetchInto(s, work, lock, settings, base) {
425
499
  const project = join(work, 'project');
426
500
  const store = join(work, 'store');
427
- await rm(work, { recursive: true, force: true });
501
+ await removeTree(work);
428
502
  await mkdir(project, { recursive: true });
429
503
  await writeFile(join(project, s.spec.lockfile.split('/').at(-1)), lock + '\n');
430
504
  for (const [name, text] of Object.entries(s.manager.buildFiles))
@@ -453,7 +527,7 @@ async function fetchInto(s, work, lock, settings, base) {
453
527
  throw new BuildFailed(`сборка seed: код ${result.code}${result.timedOut ? ', предел времени' : ''}: ${output.slice(-500)}`, !result.timedOut && s.manager.permanent.test(result.stdout + result.stderr));
454
528
  }
455
529
  try {
456
- return { store, ...(await fingerprint(store)) };
530
+ return { store, ...(await fingerprint(store, s.outer)) };
457
531
  }
458
532
  catch (error) {
459
533
  // Отказ относится к тому, что менеджер только что записал, а не к основе.
@@ -563,13 +637,13 @@ async function buildSeed(s, key, lock, lockSha256) {
563
637
  return undefined;
564
638
  }
565
639
  finally {
566
- await rm(tmp, { recursive: true, force: true }).catch(() => undefined);
640
+ await removeTree(tmp).catch(() => undefined);
567
641
  }
568
642
  }
569
643
  /** Брошенные каталоги сборки: вызывается под арендой, живых среди них нет. */
570
644
  async function sweep(s) {
571
645
  for (const name of await readdir(join(s.root, 'tmp')).catch(() => []))
572
- await rm(join(s.root, 'tmp', name), { recursive: true, force: true });
646
+ await removeTree(join(s.root, 'tmp', name));
573
647
  }
574
648
  /**
575
649
  * Предел диска: остаются последние по использованию seeds, не больше
@@ -767,7 +841,7 @@ export async function materializeStore(ctx, input) {
767
841
  summary.bytes = seed.manifest.bytes;
768
842
  }
769
843
  catch (error) {
770
- await rm(dest, { recursive: true, force: true });
844
+ await removeTree(dest);
771
845
  delete summary.mode;
772
846
  if (!(error instanceof SeedRefused))
773
847
  throw error;
@@ -789,11 +863,11 @@ export async function materializeStore(ctx, input) {
789
863
  delete summary[field];
790
864
  summary.reason = error instanceof Error ? error.message : String(error);
791
865
  env = {};
792
- await rm(dest, { recursive: true, force: true }).catch(() => undefined);
866
+ await removeTree(dest).catch(() => undefined);
793
867
  // Не вышло и это — в дереве ничего не остаётся, как без хранилища. Так же, если
794
868
  // причина промаха — предел.
795
869
  if (!summary.untouched)
796
- await seal().catch(() => rm(dest, { recursive: true, force: true }).catch(() => undefined));
870
+ await seal().catch(() => removeTree(dest).catch(() => undefined));
797
871
  }
798
872
  delete summary.untouched;
799
873
  const receipt = {
@@ -0,0 +1,33 @@
1
+ import { Worker } from 'node:worker_threads';
2
+ /**
3
+ * SHA-256 и права файлов дерева в потоках: сверка копии seed читает десятки
4
+ * тысяч мелких файлов, и асинхронное чтение по одному упирается в переходы
5
+ * через пул libuv из четырёх потоков, а хэш — в один главный поток. Здесь
6
+ * каждый поток сам открывает, читает и хэширует свою порцию синхронно.
7
+ *
8
+ * Байты и права берутся с одного дескриптора: файл открыт без перехода по
9
+ * ссылке и без ожидания устройства, а `fstat` того же дескриптора решает,
10
+ * обычный ли это файл. Подмена между обходом и чтением — отказ, а не чтение
11
+ * чужого файла.
12
+ */
13
+ export interface FileDigest {
14
+ rel: string;
15
+ sha256: string;
16
+ /** Права вместе с setuid, setgid и sticky (`0o7777`). */
17
+ mode: number;
18
+ size: number;
19
+ }
20
+ /** Файл оказался не обычным: ссылка, каталог, устройство. */
21
+ export declare class NotRegularFile extends Error {
22
+ readonly rel: string;
23
+ constructor(rel: string);
24
+ }
25
+ /** Запуск потока; тест подменяет его, чтобы проверить отказ запуска. */
26
+ export declare const digestWorker: {
27
+ create: () => Worker;
28
+ };
29
+ /**
30
+ * Отпечатки файлов `rels` под `root`. Первый отказ или отмена останавливает раздачу
31
+ * и все потоки; результат возвращается, только когда ни один поток не работает.
32
+ */
33
+ export declare function fileDigests(root: string, rels: string[], signal?: AbortSignal): Promise<FileDigest[]>;
@@ -0,0 +1,121 @@
1
+ import { availableParallelism } from 'node:os';
2
+ import { Worker } from 'node:worker_threads';
3
+ /** Файл оказался не обычным: ссылка, каталог, устройство. */
4
+ export class NotRegularFile extends Error {
5
+ rel;
6
+ constructor(rel) {
7
+ super(`в хранилище не обычный файл: ${rel}`);
8
+ this.rel = rel;
9
+ }
10
+ }
11
+ /** Порция файлов на одно сообщение: обмен не должен стоить больше чтения. */
12
+ const BATCH = 256;
13
+ const MAX_THREADS = 8;
14
+ // Код потока — строка: модуль работает и из исходников TypeScript, и из сборки.
15
+ const WORKER = `
16
+ const { parentPort } = require('node:worker_threads');
17
+ const { openSync, fstatSync, readSync, closeSync, constants } = require('node:fs');
18
+ const { createHash } = require('node:crypto');
19
+ const { join } = require('node:path');
20
+ const buffer = Buffer.allocUnsafe(1024 * 1024);
21
+ const flags = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
22
+ parentPort.on('message', ({ root, rels }) => {
23
+ const results = [];
24
+ for (const rel of rels) {
25
+ let fd;
26
+ try {
27
+ fd = openSync(join(root, rel), flags);
28
+ } catch (error) {
29
+ if (error.code === 'ELOOP') return parentPort.postMessage({ refused: rel });
30
+ return parentPort.postMessage({ error: { message: error.message, code: error.code } });
31
+ }
32
+ try {
33
+ const st = fstatSync(fd);
34
+ if (!st.isFile()) return parentPort.postMessage({ refused: rel });
35
+ const hash = createHash('sha256');
36
+ for (let n; (n = readSync(fd, buffer, 0, buffer.length, null)) > 0; )
37
+ hash.update(buffer.subarray(0, n));
38
+ results.push([rel, hash.digest('hex'), st.mode & 0o7777, st.size]);
39
+ } catch (error) {
40
+ return parentPort.postMessage({ error: { message: error.message, code: error.code } });
41
+ } finally {
42
+ closeSync(fd);
43
+ }
44
+ }
45
+ parentPort.postMessage({ results });
46
+ });
47
+ `;
48
+ /** Запуск потока; тест подменяет его, чтобы проверить отказ запуска. */
49
+ export const digestWorker = { create: () => new Worker(WORKER, { eval: true }) };
50
+ /**
51
+ * Отпечатки файлов `rels` под `root`. Первый отказ или отмена останавливает раздачу
52
+ * и все потоки; результат возвращается, только когда ни один поток не работает.
53
+ */
54
+ export async function fileDigests(root, rels, signal) {
55
+ signal?.throwIfAborted();
56
+ const batches = [];
57
+ for (let i = 0; i < rels.length; i += BATCH)
58
+ batches.push(rels.slice(i, i + BATCH));
59
+ const threads = Math.min(MAX_THREADS, Math.max(1, availableParallelism() - 1), batches.length);
60
+ const out = [];
61
+ let next = 0;
62
+ let failure;
63
+ const stops = new Set();
64
+ const fail = (error) => {
65
+ failure ??= error instanceof Error ? error : new Error(String(error));
66
+ for (const stop of stops)
67
+ stop();
68
+ };
69
+ const onAbort = () => fail(signal.reason);
70
+ signal?.addEventListener('abort', onAbort, { once: true });
71
+ const run = () => new Promise((resolve) => {
72
+ let worker;
73
+ try {
74
+ worker = digestWorker.create();
75
+ }
76
+ catch (error) {
77
+ fail(error);
78
+ return resolve();
79
+ }
80
+ let done = false;
81
+ const finish = (error) => {
82
+ if (done)
83
+ return;
84
+ done = true;
85
+ stops.delete(stop);
86
+ if (error !== undefined)
87
+ fail(error);
88
+ worker.removeAllListeners();
89
+ worker.on('error', () => undefined);
90
+ void worker.terminate().then(() => resolve());
91
+ };
92
+ const stop = () => finish();
93
+ stops.add(stop);
94
+ const feed = () => {
95
+ if (failure || next >= batches.length)
96
+ return finish();
97
+ worker.postMessage({ root, rels: batches[next++] });
98
+ };
99
+ worker.on('message', (reply) => {
100
+ if ('refused' in reply)
101
+ return finish(new NotRegularFile(reply.refused));
102
+ if ('error' in reply)
103
+ return finish(Object.assign(new Error(reply.error.message), { code: reply.error.code }));
104
+ for (const [rel, sha256, mode, size] of reply.results)
105
+ out.push({ rel, sha256, mode, size });
106
+ feed();
107
+ });
108
+ worker.on('error', (error) => finish(error));
109
+ worker.on('exit', () => finish(new Error('поток сверки завершился раньше времени')));
110
+ feed();
111
+ });
112
+ try {
113
+ await Promise.all(Array.from({ length: threads }, run));
114
+ }
115
+ finally {
116
+ signal?.removeEventListener('abort', onAbort);
117
+ }
118
+ if (failure)
119
+ throw failure;
120
+ return out;
121
+ }
@@ -41,12 +41,31 @@ export declare function junitSummary(xml: string, redact?: (value: string) => st
41
41
  };
42
42
  /**
43
43
  * Песочница отказала до запуска команды: процесс завершился неуспешно, а
44
- * метка старта, которую обёртка создаёт перед exec, не появилась. Текст
45
- * stderr признаком не служит — его может напечатать и сама проверка.
44
+ * обёртка не дошла до exec — нет ни метки-файла, ни токена старта, который
45
+ * она печатает в stderr перед exec (`printed`). Метку команда может стереть,
46
+ * напечатанный токен — нет; подделать токен значит лишь признать старт.
47
+ * Текст stderr сам признаком не служит — его может напечатать и проверка.
46
48
  */
47
49
  export declare function sandboxNotStarted(result: {
48
50
  code: number;
49
- }, started: string | undefined): boolean;
51
+ }, started: string | undefined, printed: boolean): boolean;
52
+ /**
53
+ * Фильтр сырого stderr, вырезающий строку токена старта, которую обёртка
54
+ * печатает перед exec. Ищет до маски: маска по значениям окружения (`1`,
55
+ * `8080`) задевала бы шестнадцатеричный токен, и старт не узнавался. Хвост,
56
+ * который может оказаться началом токена, придерживается до следующего
57
+ * куска. Вырезается только первое вхождение; `onSeen` — при нём.
58
+ */
59
+ export declare function startTokenFilter(token: string, onSeen: () => void): (text: string, final: boolean) => string;
60
+ /**
61
+ * Известные отказы запуска самой песочницы — не содержимого проверяемого
62
+ * дерева: поиск shell и порождение процесса песочницы. Только они при
63
+ * доказанном «не стартовала» делают отказ классом `environment`; прочие
64
+ * отказы srt до старта (например, сборка запретов по дереву на Linux) могут
65
+ * зависеть от кандидата и остаются провалом проверки. Весь stderr должен
66
+ * состоять только из таких строк srt: строка внутри другого вывода не в счёт.
67
+ */
68
+ export declare function sandboxLaunchFailure(stderr: string): boolean;
50
69
  /**
51
70
  * Путь отчёта внутри корня, созданный без выхода за него.
52
71
  *
@@ -88,7 +107,8 @@ export declare function runCheck(h: {
88
107
  violations?: boolean;
89
108
  /**
90
109
  * Запуск проверки подтверждён: без песочницы — порождён её процесс, в
91
- * песочнице — обёртка создала метку старта перед exec. Запуск самой
110
+ * песочнице — обёртка напечатала токен старта (или создала метку) перед
111
+ * exec. Запуск самой
92
112
  * обёртки песочницы запуском проверки не считается. Вызывается не более
93
113
  * одного раза, в том числе когда проверка затем завершилась исключением.
94
114
  */
@@ -98,6 +118,8 @@ export declare function runCheck(h: {
98
118
  isolation?: Isolation | undefined;
99
119
  attempts: number;
100
120
  started: boolean;
121
+ notStarted: boolean;
122
+ launchFailed: boolean;
101
123
  code: number;
102
124
  stdout: string;
103
125
  stderr: string;
@@ -110,6 +132,8 @@ export declare function completedCheck(error: unknown): {
110
132
  isolation?: Isolation | undefined;
111
133
  attempts: number;
112
134
  started: boolean;
135
+ notStarted: boolean;
136
+ launchFailed: boolean;
113
137
  code: number;
114
138
  stdout: string;
115
139
  stderr: string;
@@ -197,11 +197,63 @@ function failedCases(counts) {
197
197
  }
198
198
  /**
199
199
  * Песочница отказала до запуска команды: процесс завершился неуспешно, а
200
- * метка старта, которую обёртка создаёт перед exec, не появилась. Текст
201
- * stderr признаком не служит — его может напечатать и сама проверка.
200
+ * обёртка не дошла до exec — нет ни метки-файла, ни токена старта, который
201
+ * она печатает в stderr перед exec (`printed`). Метку команда может стереть,
202
+ * напечатанный токен — нет; подделать токен значит лишь признать старт.
203
+ * Текст stderr сам признаком не служит — его может напечатать и проверка.
202
204
  */
203
- export function sandboxNotStarted(result, started) {
204
- return started !== undefined && result.code !== 0 && !existsSync(started);
205
+ export function sandboxNotStarted(result, started, printed) {
206
+ return started !== undefined && result.code !== 0 && !printed && !existsSync(started);
207
+ }
208
+ /**
209
+ * Фильтр сырого stderr, вырезающий строку токена старта, которую обёртка
210
+ * печатает перед exec. Ищет до маски: маска по значениям окружения (`1`,
211
+ * `8080`) задевала бы шестнадцатеричный токен, и старт не узнавался. Хвост,
212
+ * который может оказаться началом токена, придерживается до следующего
213
+ * куска. Вырезается только первое вхождение; `onSeen` — при нём.
214
+ */
215
+ export function startTokenFilter(token, onSeen) {
216
+ const line = token + '\n';
217
+ let pending = '', seen = false;
218
+ return (text, final) => {
219
+ if (seen)
220
+ return text;
221
+ pending += text;
222
+ const at = pending.indexOf(line);
223
+ if (at >= 0) {
224
+ seen = true;
225
+ onSeen();
226
+ const out = pending.slice(0, at) + pending.slice(at + line.length);
227
+ pending = '';
228
+ return out;
229
+ }
230
+ let keep = 0;
231
+ if (!final)
232
+ for (let k = Math.min(line.length - 1, pending.length); k > 0; k--)
233
+ if (line.startsWith(pending.slice(-k))) {
234
+ keep = k;
235
+ break;
236
+ }
237
+ const out = pending.slice(0, pending.length - keep);
238
+ pending = pending.slice(pending.length - keep);
239
+ return out;
240
+ };
241
+ }
242
+ /**
243
+ * Известные отказы запуска самой песочницы — не содержимого проверяемого
244
+ * дерева: поиск shell и порождение процесса песочницы. Только они при
245
+ * доказанном «не стартовала» делают отказ классом `environment`; прочие
246
+ * отказы srt до старта (например, сборка запретов по дереву на Linux) могут
247
+ * зависеть от кандидата и остаются провалом проверки. Весь stderr должен
248
+ * состоять только из таких строк srt: строка внутри другого вывода не в счёт.
249
+ */
250
+ export function sandboxLaunchFailure(stderr) {
251
+ const lines = stderr
252
+ .split('\n')
253
+ .map((l) => l.trim())
254
+ .filter(Boolean);
255
+ return (lines.length > 0 &&
256
+ lines.every((l) => /^Error: Shell '[^']+' not found in PATH$|^Failed to execute command: \S/.test(l)));
205
257
  }
206
258
  /** Команда проверки находится — иначе ENOENT, как при обычном запуске. */
207
259
  function assertExecutable(name, path, cwd) {
@@ -277,7 +329,15 @@ h, options) {
277
329
  launched = true;
278
330
  options.onStart?.();
279
331
  };
280
- let argv = options.argv, env = options.env, cwd = options.cwd, policy, started, result, monitor, violations, attempts = 1;
332
+ let argv = options.argv, env = options.env, cwd = options.cwd, policy, started, result, monitor, violations, attempts = 1,
333
+ // Во всех попытках отказала сама песочница: команда не начиналась.
334
+ // Вычисляется до уборки, пока метка старта ещё на месте.
335
+ notStarted = false,
336
+ // Не стартовала по известному отказу запуска песочницы: отказ среды.
337
+ launchFailed = false,
338
+ // Токен старта в stderr текущей попытки.
339
+ printed = false;
340
+ const token = randomUUID().replace(/-/g, '');
281
341
  const scratch = await realpath(await mkdtemp(join(tmpdir(), 'dc-gate-')));
282
342
  // Метка старта — вне TMPDIR команды: проверка, чистящая свой временный
283
343
  // каталог, не должна стирать признак того, что она уже начиналась.
@@ -304,21 +364,32 @@ h, options) {
304
364
  const workdir = await realpath(options.cwd);
305
365
  const tag = options.violations ? 'dc' + randomUUID().replace(/-/g, '').slice(0, 16) : '';
306
366
  const roots = isolation({ write: options.write, controller: [] }).write.filter((w) => workdir === w || workdir.startsWith(w + sep));
307
- const wrapped = await isolatedCommand(policy, argv, options.settingsDir, scratch, started, workdir, roots.length ? roots : [workdir], process.platform, tag);
367
+ const wrapped = await isolatedCommand(policy, argv, options.settingsDir, scratch, started, workdir, roots.length ? roots : [workdir], process.platform, tag, token);
308
368
  argv = wrapped.argv;
309
369
  env = { ...env, ...wrapped.env };
310
370
  cwd = wrapped.cwd;
311
371
  if (tag)
312
372
  monitor = await watchSandboxLog(tag);
313
373
  }
314
- const execute = () => {
374
+ const execute = async () => {
315
375
  // Уже отменённый вызов не запускается: слушатель отмены на отменённом
316
376
  // сигнале не срабатывает, и команда шла бы до таймаута.
317
377
  if (options.signal.aborted)
318
378
  throw Object.assign(new Error('Проверка отменена до запуска'), { name: 'AbortError' });
379
+ printed = false;
319
380
  return command(argv, cwd, {
320
381
  signal: options.signal,
321
382
  ...(started === undefined ? { onSpawn: confirm } : {}),
383
+ // Токен старта ищется в сыром потоке до маски и вырезается из него:
384
+ // итоговый stderr хранит только хвост, а маска могла исказить токен.
385
+ ...(started !== undefined
386
+ ? {
387
+ rawStderr: startTokenFilter(token, () => {
388
+ printed = true;
389
+ confirm();
390
+ }),
391
+ }
392
+ : {}),
322
393
  timeoutMs: options.timeoutMs,
323
394
  env,
324
395
  redact: options.redact,
@@ -331,13 +402,16 @@ h, options) {
331
402
  };
332
403
  try {
333
404
  result = await execute();
334
- // sandbox-runtime ищет shell через `which` с таймаутом в секунду и под
335
- // нагрузкой отказывает до запуска команды. Повтор допустим, только если
336
- // команда точно не начиналась: метки старта нет.
337
- for (; attempts < 3 && sandboxNotStarted(result, started); attempts++) {
405
+ // Песочница может отказать до запуска команды (прежде так отказывал
406
+ // поиск shell через `which` под нагрузкой — см. `srtShellLookup`).
407
+ // Повтор допустим, только если команда точно не начиналась: нет ни
408
+ // метки, ни токена старта. Стёртая командой метка повтора не даёт.
409
+ for (; attempts < 3 && sandboxNotStarted(result, started, printed); attempts++) {
338
410
  await new Promise((r) => setTimeout(r, 500 * attempts));
339
411
  result = await execute();
340
412
  }
413
+ notStarted = sandboxNotStarted(result, started, printed);
414
+ launchFailed = notStarted && sandboxLaunchFailure(result.stderr);
341
415
  }
342
416
  finally {
343
417
  // Факт старта читается до удаления метки — и при исключении после него.
@@ -354,6 +428,8 @@ h, options) {
354
428
  ...result,
355
429
  attempts,
356
430
  started: launched,
431
+ notStarted,
432
+ launchFailed,
357
433
  ...(policy ? { isolation: policy } : {}),
358
434
  ...(violations ? { violations } : {}),
359
435
  };
@@ -379,6 +455,8 @@ h, options) {
379
455
  ...result,
380
456
  attempts,
381
457
  started: launched,
458
+ notStarted,
459
+ launchFailed,
382
460
  ...(policy ? { isolation: policy } : {}),
383
461
  ...(violations ? { violations } : {}),
384
462
  },
@@ -554,6 +632,15 @@ export async function runGate(run) {
554
632
  }
555
633
  if (result.timedOut || signal.aborted)
556
634
  throw new Error('Проверка прервана или превысила timeout');
635
+ // Песочница так и не запустила команду по известному отказу запуска:
636
+ // код проекта не исполнялся, и его правка ничего не изменит. Это отказ
637
+ // среды, а не провал проверки; текст srt вроде «Shell 'bash' not found
638
+ // in PATH» остаётся только причиной. Прочие отказы — провал проверки.
639
+ if (result.launchFailed) {
640
+ kind = 'environment';
641
+ throw new Error(`песочница ОС не запустила команду проверки (попыток: ${result.attempts}): проверка не исполнялась. ` +
642
+ `Код выхода ${result.code}: ${diagnostic(result.stderr, result.stdout, redact)}`);
643
+ }
557
644
  if (result.code !== 0) {
558
645
  // Сохраняем валидный отчёт и при отказе команды, до классификации
559
646
  // песочницы: после очистки worktree иначе остаётся только хвост лога.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "devcontour-harness",
3
- "version": "0.1.0-alpha.28",
3
+ "version": "0.1.0-alpha.29",
4
4
  "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
5
5
  "type": "module",
6
6
  "license": "MIT",