devcontour-harness 0.1.0-alpha.21 → 0.1.0-alpha.23

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.
Files changed (42) hide show
  1. package/README.md +21 -2
  2. package/docs/architecture.md +10 -1
  3. package/docs/compatibility.md +11 -11
  4. package/docs/contracts.md +17 -2
  5. package/docs/quickstart.md +1 -1
  6. package/docs/release-notes/0.1.0-alpha.22.md +57 -0
  7. package/docs/release-notes/0.1.0-alpha.23.md +122 -0
  8. package/docs/toolchains.md +2 -1
  9. package/docs/upgrade.md +17 -17
  10. package/lib/agents/cli-adapter.js +1 -0
  11. package/lib/agents/review-probe.d.ts +1 -0
  12. package/lib/agents/review-probe.js +4 -0
  13. package/lib/cli.js +1 -1
  14. package/lib/contracts/cli.d.ts +20 -0
  15. package/lib/contracts/cli.js +11 -0
  16. package/lib/contracts/ports.d.ts +6 -0
  17. package/lib/control/base-move.d.ts +2 -0
  18. package/lib/control/base-move.js +13 -2
  19. package/lib/control/doctor.d.ts +10 -0
  20. package/lib/control/doctor.js +19 -3
  21. package/lib/control/harness.d.ts +6 -0
  22. package/lib/control/harness.js +2 -0
  23. package/lib/engine/joint-runner.d.ts +5 -0
  24. package/lib/engine/joint-runner.js +28 -5
  25. package/lib/engine/runner.d.ts +18 -0
  26. package/lib/engine/runner.js +73 -10
  27. package/lib/environment/checkout-root.d.ts +78 -0
  28. package/lib/environment/checkout-root.js +133 -0
  29. package/lib/environment/git-trust.js +4 -0
  30. package/lib/environment/isolation.d.ts +48 -9
  31. package/lib/environment/isolation.js +132 -37
  32. package/lib/index.d.ts +5 -0
  33. package/lib/index.js +5 -0
  34. package/lib/verification/confirm.d.ts +7 -4
  35. package/lib/verification/confirm.js +4 -2
  36. package/lib/verification/gates-at.d.ts +9 -5
  37. package/lib/verification/gates-at.js +30 -5
  38. package/lib/verification/gates.d.ts +13 -4
  39. package/lib/verification/gates.js +15 -2
  40. package/lib/verification/spike.d.ts +7 -4
  41. package/lib/verification/spike.js +4 -2
  42. package/package.json +1 -1
@@ -0,0 +1,133 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { lstatSync, mkdirSync, realpathSync, statSync } from 'node:fs';
3
+ import { homedir } from 'node:os';
4
+ import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
5
+ import { HarnessError } from "../contracts/index.js";
6
+ /** Настоящий путь и для ещё не созданного каталога: от ближайшего существующего предка. */
7
+ export function realish(path) {
8
+ const absolute = resolve(path);
9
+ try {
10
+ return realpathSync(absolute);
11
+ }
12
+ catch {
13
+ const parent = dirname(absolute);
14
+ return parent === absolute ? absolute : join(realish(parent), basename(absolute));
15
+ }
16
+ }
17
+ const within = (path, root) => path === root || path.startsWith(root + sep);
18
+ /** Номер тома ближайшего существующего предка пути. */
19
+ function deviceOf(path) {
20
+ for (let dir = resolve(path);; dir = dirname(dir)) {
21
+ try {
22
+ return statSync(dir).dev;
23
+ }
24
+ catch {
25
+ if (dirname(dir) === dir)
26
+ return undefined;
27
+ }
28
+ }
29
+ }
30
+ /** Каталог кэша пользователя для рабочих деревьев (без хэша). */
31
+ export function checkoutCacheBase(platform = process.platform, env = process.env, home = homedir()) {
32
+ if (platform === 'darwin')
33
+ return join(home, 'Library', 'Caches', 'devcontour-harness');
34
+ const xdg = env.XDG_CACHE_HOME;
35
+ // Относительный XDG_CACHE_HOME спецификация велит игнорировать.
36
+ return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.cache'), 'devcontour-harness');
37
+ }
38
+ /** Устойчивый хэш каталога состояния: тот же путь — тот же корень. */
39
+ export const stateHash = (stateDir) => createHash('sha256').update(realish(stateDir)).digest('hex').slice(0, 16);
40
+ /**
41
+ * Каталог кэша безопасен для рабочих деревьев: настоящий каталог (не ссылка)
42
+ * этого пользователя. `create` — создать недостающий с правами 0700.
43
+ * Возвращает причину отказа или `undefined`.
44
+ */
45
+ function unsafeDir(path, create, uid) {
46
+ let stat;
47
+ try {
48
+ stat = lstatSync(path);
49
+ }
50
+ catch {
51
+ if (!create)
52
+ return undefined;
53
+ try {
54
+ mkdirSync(path, { mode: 0o700 });
55
+ stat = lstatSync(path);
56
+ }
57
+ catch (error) {
58
+ return `${path} не создан: ${error.code ?? String(error)}`;
59
+ }
60
+ }
61
+ if (stat.isSymbolicLink())
62
+ return `${path} — символическая ссылка`;
63
+ if (!stat.isDirectory())
64
+ return `${path} не каталог`;
65
+ if (uid !== undefined && stat.uid !== uid)
66
+ return `${path} принадлежит другому пользователю`;
67
+ return undefined;
68
+ }
69
+ export function chooseCheckoutRoot(input) {
70
+ const states = input.stateDirs.map(realish);
71
+ const repos = input.repositories.map(realish);
72
+ const hidden = (input.hidden ?? []).map(realish);
73
+ // Корень внутри репозитория, закрытого пути или каталога состояния вернул
74
+ // бы ту же вложенность (или открыл бы закрытое).
75
+ const enclosing = (root) => [...repos, ...hidden, ...states].find((p) => within(root, p));
76
+ const uid = input.uid !== undefined ? input.uid : process.getuid?.();
77
+ const create = input.create ?? true;
78
+ if (input.configured) {
79
+ const root = realish(input.configured);
80
+ const inside = enclosing(root);
81
+ if (inside)
82
+ throw new HarnessError('INVALID_INPUT', `checkoutRoot ${root} внутри ${inside}: корень рабочих деревьев должен лежать вне репозиториев, закрытых путей и каталога состояния`);
83
+ const unsafe = unsafeDir(root, false, uid);
84
+ if (unsafe)
85
+ throw new HarnessError('INVALID_INPUT', 'checkoutRoot: ' + unsafe);
86
+ return { root, placement: 'configured' };
87
+ }
88
+ // Каталог состояния внутри репозитория (или им и являющийся) либо строго
89
+ // внутри другого закрытого пути: предки его рабочих деревьев были бы закрыты.
90
+ const nested = states.find((s) => repos.some((r) => within(s, r)) || hidden.some((h) => s !== h && within(s, h)));
91
+ if (!nested)
92
+ return { placement: 'in-place' };
93
+ const base = checkoutCacheBase(input.platform, input.env, input.home);
94
+ const root = join(base, stateHash(input.stateDirs[0] ?? nested));
95
+ const stay = (why) => ({
96
+ placement: 'in-place',
97
+ note: `${why}: рабочие деревья остаются в каталоге состояния ${nested} (внутри закрытого дерева инструменты, ищущие конфигурацию вверх по дереву, получат EPERM); задайте checkoutRoot`,
98
+ });
99
+ const inside = enclosing(realish(root));
100
+ if (inside)
101
+ return stay(`каталог кэша ${root} внутри ${inside}`);
102
+ const device = input.device ?? deviceOf;
103
+ const at = device(root);
104
+ const other = repos.find((r) => {
105
+ const d = device(r);
106
+ return at !== undefined && d !== undefined && d !== at;
107
+ });
108
+ if (other)
109
+ return {
110
+ placement: 'cross-volume',
111
+ note: `каталог кэша ${root} на другом томе, чем репозиторий ${other}: жёсткие ссылки и reflink менеджера пакетов там не работают, рабочие деревья остаются в каталоге состояния ${nested} (внутри закрытого дерева инструменты, ищущие конфигурацию вверх по дереву, получат EPERM); задайте checkoutRoot на томе репозитория`,
112
+ };
113
+ // Общий каталог кэша — только существующий предок: создаются и
114
+ // проверяются каталог harness и каталог этого состояния.
115
+ for (const dir of [base, root]) {
116
+ const unsafe = unsafeDir(dir, create, uid);
117
+ if (unsafe)
118
+ return stay('каталог кэша небезопасен: ' + unsafe);
119
+ }
120
+ return {
121
+ root,
122
+ placement: 'cache',
123
+ note: `каталог состояния ${nested} внутри репозитория или закрытого пути: рабочие деревья — вне дерева, в ${root}`,
124
+ };
125
+ }
126
+ /**
127
+ * Каталог рабочего дерева вида `kind` (`worktrees`, `dependencies`,
128
+ * `gates-at`…). Корень вне дерева: `<root>/<repositoryId>/<kind>/…`; иначе —
129
+ * прежний путь `legacy`.
130
+ */
131
+ export function checkoutPath(choice, legacy, repositoryId, kind, ...rest) {
132
+ return choice.root ? join(choice.root, repositoryId, kind, ...rest) : legacy;
133
+ }
@@ -85,6 +85,10 @@ export function assertTrustedCheckout(cwd) {
85
85
  /* нет `.git` на этом уровне */
86
86
  }
87
87
  const nested = insideKnown(dir);
88
+ // Файл `.git` созданного хостом дерева удалён: git ушёл бы в репозиторий
89
+ // предка (каталог состояния внутри checkout человека, чужой `.git` выше).
90
+ if (!stat && knownWorktrees.has(dir))
91
+ refuse(`${dotgit} рабочего дерева удалён`);
88
92
  if (stat) {
89
93
  if (nested)
90
94
  refuse(`вложенный репозиторий ${dotgit} внутри рабочего дерева ${nested}`);
@@ -41,6 +41,16 @@ export declare function isolation(options: {
41
41
  domains?: string[];
42
42
  /** Элементы каталога контура хоста, которые закрываются и до своего появления. */
43
43
  entries?: string[];
44
+ /**
45
+ * Корни рабочих деревьев вне каталога состояния (`checkout-root.ts`):
46
+ * закрыты целиком, как каталог состояния; свои деревья проверки открыты
47
+ * более конкретным разрешением (`write`, `readable`). Деревья других
48
+ * попыток закрыты, и появившиеся после построения политики тоже. Поиск
49
+ * конфигурации вверх по дереву не ломается: в корне нет файлов
50
+ * конфигурации, а `stat` отсутствующего файла под запретом Seatbelt
51
+ * отвечает ENOENT, метаданные каталогов-предков открыты.
52
+ */
53
+ checkouts?: string[];
44
54
  }): Isolation;
45
55
  /** Sandbox Claude Code: применяется к Bash; без запасного выхода из песочницы. */
46
56
  export declare function claudeSandbox(policy: Isolation, review: boolean, cwd: string): {
@@ -114,6 +124,15 @@ export declare function isolationSupport(): {
114
124
  * «кроме node_modules», поэтому дерево перечисляется: новый каталог глубже
115
125
  * существующего уровня не закрыт (у srt на Linux закрыты только уже
116
126
  * существующие файлы до глубины 3).
127
+ * - Регистр. Правила srt (`subpath`, `regex`) записаны в нижнем регистре, но
128
+ * Seatbelt на нечувствительном к регистру томе (APFS по умолчанию)
129
+ * сравнивает путь без регистра: проба под песочницей отказывает в записи в
130
+ * `.IDEA/x`, `.VSCode/x`, `.Bashrc`, `.Claude/commands/x` и `x/.GIT/hooks/x`
131
+ * так же, как в именах нижнего регистра. На Linux ФС обычно различает
132
+ * регистр, и `.Claude` хост не читает как `.claude`. Имена, которых в
133
+ * запретах нет (`.claude/settings.json` в любом регистре), и пути глубже
134
+ * перечисленных уровней ловит сверка снимков (`protectedSnapshot`) — она
135
+ * сравнивает имена без регистра везде.
117
136
  *
118
137
  * Путь с символами глоба нельзя записать шаблоном без риска не совпасть ни
119
138
  * с чем; тогда возвращается `undefined`, и srt остаётся в прежнем каталоге с
@@ -158,11 +177,26 @@ export declare function watchSandboxLog(tag: string): Promise<{
158
177
  stop(drainMs: number): Promise<SandboxViolation[]>;
159
178
  } | undefined>;
160
179
  /**
161
- * Отказы обязательной политики в открытых проверке каталогах, которые
162
- * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
163
- * а не среды: её здесь нет.
180
+ * Запрет чтения, которым песочница закрыла путь: путь внутри закрытого и не
181
+ * внутри более конкретного открытого (srt: открытое внутри закрытого
182
+ * побеждает, закрытое внутри открытого — снова закрыто).
183
+ */
184
+ export declare function hiddenReadRule(policy: Isolation, path: string): string | undefined;
185
+ /**
186
+ * Отказы песочницы, которые подтвердило ядро и которые правкой кода не снять.
187
+ *
188
+ * - Запись: обязательная политика в открытых проверке каталогах. Запись вне
189
+ * открытых каталогов — ошибка кода проверки, а не среды: её здесь нет.
190
+ * - Чтение (и `stat`): закрытый файл в предке рабочего каталога проверки
191
+ * (`cwd`), на котором она упала с EPERM. Инструменты ищут конфигурацию
192
+ * вверх по дереву и на EPERM (в отличие от ENOENT) падают. Нужны все
193
+ * признаки — запись ядра для тега этой проверки, форма поиска вверх
194
+ * (каталог файла — строгий предок `cwd`) и EPERM с этим путём в выводе
195
+ * (`output`). Чтение другого закрытого пути (`~/.ssh/id_rsa`), отказ,
196
+ * который проверка пережила, и обычный провал тестов отказом среды не
197
+ * становятся: отказ среды не тратит попытку и останавливает очередь.
164
198
  */
165
- export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation): {
199
+ export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation, output?: string, cwd?: string): {
166
200
  path: string;
167
201
  rule: string;
168
202
  }[];
@@ -178,11 +212,16 @@ export declare function protectedSnapshot(root: string): Map<string, string>;
178
212
  /**
179
213
  * Защищённые пути, которые появились или изменились после снимка `before`.
180
214
  *
181
- * Пустые каталоги (только каталоги, рекурсивно) нарушением не считаются,
182
- * если до снимка пути не было или он тоже был без файлов: исполняемой
183
- * конфигурации в них нет, а CLI исполнителя создаёт такие служебные каталоги
184
- * (`.claude/.cc-writes`) рядом с каждым записанным файлом. Путь, где раньше
185
- * были файлы, по-прежнему нарушение при любом изменении.
215
+ * Путь, который сверка не может прочитать (кроме ENOENT), — `SandboxPolicyError`
216
+ * из снимка, а не пропуск: вызывающий решает, отказ ли это среды (снимок до
217
+ * работы) или нарушение области (после).
218
+ *
219
+ * Пустые каталоги (только каталоги, рекурсивно, без записи всем)
220
+ * нарушением не считаются, если до снимка пути не было или он тоже был без
221
+ * файлов: исполняемой конфигурации в них нет, а CLI исполнителя создаёт
222
+ * такие служебные каталоги (`.claude/.cc-writes`) рядом с каждым записанным
223
+ * файлом. Путь, где раньше были файлы, по-прежнему нарушение при любом
224
+ * изменении.
186
225
  */
187
226
  export declare function protectedChanges(before: Map<string, string>, root: string): string[];
188
227
  /**
@@ -44,7 +44,7 @@ export function isolation(options) {
44
44
  ];
45
45
  return {
46
46
  write: real(options.write),
47
- hidden: real([...options.controller, ...credentialPaths()]),
47
+ hidden: real([...options.controller, ...(options.checkouts ?? []), ...credentialPaths()]),
48
48
  // Установленные пакеты рантайма лежат внутри закрытого каталога его
49
49
  // учётных данных: без них codex не запускает даже помощника своей
50
50
  // песочницы. Более конкретный путь открыт; токены и сессии — нет.
@@ -220,6 +220,15 @@ export function isolationSupport() {
220
220
  * «кроме node_modules», поэтому дерево перечисляется: новый каталог глубже
221
221
  * существующего уровня не закрыт (у srt на Linux закрыты только уже
222
222
  * существующие файлы до глубины 3).
223
+ * - Регистр. Правила srt (`subpath`, `regex`) записаны в нижнем регистре, но
224
+ * Seatbelt на нечувствительном к регистру томе (APFS по умолчанию)
225
+ * сравнивает путь без регистра: проба под песочницей отказывает в записи в
226
+ * `.IDEA/x`, `.VSCode/x`, `.Bashrc`, `.Claude/commands/x` и `x/.GIT/hooks/x`
227
+ * так же, как в именах нижнего регистра. На Linux ФС обычно различает
228
+ * регистр, и `.Claude` хост не читает как `.claude`. Имена, которых в
229
+ * запретах нет (`.claude/settings.json` в любом регистре), и пути глубже
230
+ * перечисленных уровней ловит сверка снимков (`protectedSnapshot`) — она
231
+ * сравнивает имена без регистра везде.
223
232
  *
224
233
  * Путь с символами глоба нельзя записать шаблоном без риска не совпасть ни
225
234
  * с чем; тогда возвращается `undefined`, и srt остаётся в прежнем каталоге с
@@ -331,7 +340,11 @@ export function mandatoryDenyRule(policy, path) {
331
340
  const root = policy.write.find((w) => path === w || path.startsWith(w + sep));
332
341
  if (!root)
333
342
  return undefined;
334
- const parts = relative(root, path).split(sep);
343
+ const raw = relative(root, path).split(sep);
344
+ // Seatbelt на нечувствительном к регистру томе (APFS по умолчанию) отказывает
345
+ // и в `.IDEA/x`, и в `.Claude/commands`: имена сравниваются без регистра.
346
+ // `node_modules` — как в перечислении `protectedWriteDenies`, точно.
347
+ const parts = raw.map((p) => p.toLowerCase());
335
348
  const at = (i, ...names) => names.every((n, k) => parts[i + k] === n);
336
349
  const rule = (what) => `обязательный запрет записи sandbox-runtime: ${what}`;
337
350
  for (let i = 0; i < parts.length; i++) {
@@ -339,18 +352,18 @@ export function mandatoryDenyRule(policy, path) {
339
352
  if (DANGEROUS_FILES.includes(name) && i === parts.length - 1)
340
353
  return rule(name);
341
354
  // Каталоги IDE внутри дерева зависимостей открыты (`protectedWriteDenies`).
342
- if (ideDirectories.includes(name) && !parts.slice(0, i).includes('node_modules'))
355
+ if (ideDirectories.includes(name) && !raw.slice(0, i).includes('node_modules'))
343
356
  return rule(`каталог IDE ${name}`);
344
357
  if (at(i, '.git', 'hooks') || at(i, '.git', 'config'))
345
- return rule(parts.slice(i, i + 2).join('/'));
358
+ return rule(raw.slice(i, i + 2).join('/'));
346
359
  if (name === '.git' && i === 0 && parts.length === 1)
347
360
  return rule('файл .git рабочего дерева');
348
361
  if (name === '.git' && i === 0 && gitRedirects.includes(parts[1] ?? ''))
349
- return rule(`.git/${parts[1]}`);
362
+ return rule(`.git/${raw[1]}`);
350
363
  if (name === '.git' && i > 0)
351
364
  return rule('вложенный репозиторий .git');
352
365
  if (at(i, '.claude', 'commands') || at(i, '.claude', 'agents'))
353
- return rule(parts.slice(i, i + 2).join('/'));
366
+ return rule(raw.slice(i, i + 2).join('/'));
354
367
  }
355
368
  return undefined;
356
369
  }
@@ -421,26 +434,80 @@ export async function watchSandboxLog(tag) {
421
434
  };
422
435
  }
423
436
  /**
424
- * Отказы обязательной политики в открытых проверке каталогах, которые
425
- * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
426
- * а не среды: её здесь нет.
437
+ * Запрет чтения, которым песочница закрыла путь: путь внутри закрытого и не
438
+ * внутри более конкретного открытого (srt: открытое внутри закрытого
439
+ * побеждает, закрытое внутри открытого — снова закрыто).
427
440
  */
428
- export function sandboxDenials(violations, policy) {
441
+ export function hiddenReadRule(policy, path) {
442
+ const within = (p, root) => p === root || p.startsWith(root + sep);
443
+ const longest = (paths) => paths.filter((p) => within(path, p)).reduce((a, b) => (b.length > a.length ? b : a), '');
444
+ const hidden = longest(policy.hidden);
445
+ if (!hidden)
446
+ return undefined;
447
+ if (longest([...policy.readable, ...policy.write]).length >= hidden.length)
448
+ return undefined;
449
+ return `запрет чтения песочницы: ${hidden} закрыт проверке`;
450
+ }
451
+ /** Путь в выводе проверки в любом написании (macOS: /private/var и /var). */
452
+ const mentions = (output, path) => output.includes(path) ||
453
+ (path.startsWith('/private/') && output.includes(path.slice('/private'.length)));
454
+ /**
455
+ * Отказы песочницы, которые подтвердило ядро и которые правкой кода не снять.
456
+ *
457
+ * - Запись: обязательная политика в открытых проверке каталогах. Запись вне
458
+ * открытых каталогов — ошибка кода проверки, а не среды: её здесь нет.
459
+ * - Чтение (и `stat`): закрытый файл в предке рабочего каталога проверки
460
+ * (`cwd`), на котором она упала с EPERM. Инструменты ищут конфигурацию
461
+ * вверх по дереву и на EPERM (в отличие от ENOENT) падают. Нужны все
462
+ * признаки — запись ядра для тега этой проверки, форма поиска вверх
463
+ * (каталог файла — строгий предок `cwd`) и EPERM с этим путём в выводе
464
+ * (`output`). Чтение другого закрытого пути (`~/.ssh/id_rsa`), отказ,
465
+ * который проверка пережила, и обычный провал тестов отказом среды не
466
+ * становятся: отказ среды не тратит попытку и останавливает очередь.
467
+ */
468
+ export function sandboxDenials(violations, policy, output, cwd) {
429
469
  const found = new Map();
470
+ const eperm = output !== undefined && /\bEPERM\b|operation not permitted/i.test(output);
471
+ // Поиск вверх: файл лежит прямо в строгом предке рабочего каталога.
472
+ const walkUp = (path) => cwd !== undefined && cwd.startsWith(dirname(path) + sep);
430
473
  for (const v of violations) {
431
- if (!v.operation.startsWith('file-write'))
474
+ if (found.has(v.path))
432
475
  continue;
433
- const rule = mandatoryDenyRule(policy, v.path);
434
- if (rule && !found.has(v.path))
476
+ const rule = v.operation.startsWith('file-write')
477
+ ? mandatoryDenyRule(policy, v.path)
478
+ : v.operation.startsWith('file-read') && eperm && walkUp(v.path) && mentions(output, v.path)
479
+ ? hiddenReadRule(policy, v.path)
480
+ : undefined;
481
+ if (rule)
435
482
  found.set(v.path, rule);
436
483
  }
437
484
  return [...found].map(([path, rule]) => ({ path, rule }));
438
485
  }
439
- /** Имена, которые проверка и исполнитель не создают и не меняют. */
486
+ /**
487
+ * Имена, которые проверка и исполнитель не создают и не меняют.
488
+ *
489
+ * Сравниваются без регистра на любой платформе: на APFS и NTFS `.Claude`,
490
+ * `.VSCode` или `.Bashrc` хост читает как `.claude`, `.vscode`, `.bashrc`.
491
+ * На чувствительной к регистру ФС такое имя никто не читает, но и создавать
492
+ * его незачем — лишняя строгость дешевле развилки по ФС.
493
+ */
440
494
  const protectedNames = new Set([...DANGEROUS_FILES, ...ideDirectories, '.claude', '.git']);
495
+ const isProtected = (name) => protectedNames.has(name.toLowerCase());
441
496
  const snapshotLimit = 200_000;
442
- /** Подпись каталога, в дереве которого нет ни файлов, ни символьных ссылок. */
497
+ /**
498
+ * Подпись каталога, в дереве которого нет ни файлов, ни символьных ссылок, и
499
+ * ни один каталог не открыт на запись всем (`mode & 0o002`): такой каталог —
500
+ * место, куда любой пользователь положит конфигурацию после сверки. Запись
501
+ * группе разрешена: при umask 002 (общие и dev-машины) CLI исполнителя
502
+ * создаёт `.claude` с правами 775.
503
+ */
443
504
  const emptyTree = 'd:empty';
505
+ /** Ошибка доступа к пути, которую сверка не может обойти: отказ, а не пропуск. */
506
+ const unreadable = (root, path, error) => {
507
+ const code = error?.code ?? String(error);
508
+ throw new SandboxPolicyError(`сверка защищённых путей не выполнена: нет доступа к ${relative(root, path) || '.'} (${code}) — путь, который нельзя прочитать, мог скрыть конфигурацию IDE, shell, git или Claude`);
509
+ };
510
+ const missing = (error) => error?.code === 'ENOENT';
444
511
  /**
445
512
  * Защищённые элементы checkout вне `node_modules`: путь → подпись.
446
513
  *
@@ -459,36 +526,59 @@ export function protectedSnapshot(root) {
459
526
  const signature = (path) => {
460
527
  count();
461
528
  let stat;
529
+ // Только ENOENT значит «пути нет». Любой другой отказ (EACCES под
530
+ // каталогом без права поиска, каталог mode 000) — отказ сверки: иначе
531
+ // `chmod 0444 sub` спрятал бы `sub/.claude/settings.json`.
462
532
  try {
463
533
  stat = lstatSync(path);
464
534
  }
465
- catch {
466
- return 'missing';
535
+ catch (error) {
536
+ if (missing(error))
537
+ return 'missing';
538
+ return unreadable(root, path, error);
539
+ }
540
+ try {
541
+ if (stat.isSymbolicLink())
542
+ return 'l:' + readlinkSync(path);
543
+ // Не каталог и не ссылка — файл, FIFO, сокет, устройство: всё это
544
+ // содержимое, пустым деревом не бывает.
545
+ if (!stat.isDirectory())
546
+ return `f:${stat.size}:${stat.mtimeMs}:${stat.ino}`;
547
+ const mode = stat.mode & 0o7777;
548
+ const names = readdirSync(path).sort();
549
+ const inner = names.map((name) => signature(join(path, name)));
550
+ // Дерево из одних закрытых для чужой записи каталогов не несёт ни
551
+ // конфигурации, ни ссылки наружу: его подпись одна для любого такого
552
+ // дерева (см. `protectedChanges`). Открытый всем каталог
553
+ // подписывается с правами и потому виден как изменение.
554
+ if ((mode & 0o002) === 0 && inner.every((sig) => sig === emptyTree))
555
+ return emptyTree;
556
+ return `d:${stat.ino}:${mode.toString(8)}[${names.map((name, i) => `${name}=${inner[i]}`).join(',')}]`;
557
+ }
558
+ catch (error) {
559
+ if (error instanceof SandboxPolicyError)
560
+ throw error;
561
+ if (missing(error))
562
+ return 'missing';
563
+ return unreadable(root, path, error);
467
564
  }
468
- if (stat.isSymbolicLink())
469
- return 'l:' + readlinkSync(path);
470
- if (!stat.isDirectory())
471
- return `f:${stat.size}:${stat.mtimeMs}:${stat.ino}`;
472
- const names = readdirSync(path).sort();
473
- const inner = names.map((name) => signature(join(path, name)));
474
- // Дерево из одних каталогов не несёт ни конфигурации, ни ссылки наружу:
475
- // его подпись одна для любого такого дерева (см. `protectedChanges`).
476
- if (inner.every((sig) => sig === emptyTree))
477
- return emptyTree;
478
- return `d:${stat.ino}[${names.map((name, i) => `${name}=${inner[i]}`).join(',')}]`;
479
565
  };
480
566
  const walk = (dir) => {
481
567
  let entries;
482
568
  try {
483
569
  entries = readdirSync(dir, { withFileTypes: true });
484
570
  }
485
- catch {
486
- return;
571
+ catch (error) {
572
+ // Исчезнувший каталог сверять нечего; непрочитанный мог спрятать
573
+ // защищённое имя — отказ.
574
+ if (missing(error))
575
+ return;
576
+ return unreadable(root, dir, error);
487
577
  }
488
578
  for (const entry of entries) {
489
579
  count();
490
580
  const path = join(dir, entry.name);
491
- if (entry.name === '.git' && dir === root && entry.isDirectory()) {
581
+ if (entry.name.toLowerCase() === '.git' && dir === root && entry.isDirectory()) {
492
582
  // Обычный `.git`: объекты и индекс меняет и git хоста; сверяются
493
583
  // только конфигурация, hooks и перенаправления. Сам вид элемента
494
584
  // тоже: файл `.git` worktree, заменённый каталогом, — изменение,
@@ -498,7 +588,7 @@ export function protectedSnapshot(root) {
498
588
  found.set(join(path, name), signature(join(path, name)));
499
589
  continue;
500
590
  }
501
- if (protectedNames.has(entry.name)) {
591
+ if (isProtected(entry.name)) {
502
592
  found.set(path, signature(path));
503
593
  continue;
504
594
  }
@@ -512,11 +602,16 @@ export function protectedSnapshot(root) {
512
602
  /**
513
603
  * Защищённые пути, которые появились или изменились после снимка `before`.
514
604
  *
515
- * Пустые каталоги (только каталоги, рекурсивно) нарушением не считаются,
516
- * если до снимка пути не было или он тоже был без файлов: исполняемой
517
- * конфигурации в них нет, а CLI исполнителя создаёт такие служебные каталоги
518
- * (`.claude/.cc-writes`) рядом с каждым записанным файлом. Путь, где раньше
519
- * были файлы, по-прежнему нарушение при любом изменении.
605
+ * Путь, который сверка не может прочитать (кроме ENOENT), — `SandboxPolicyError`
606
+ * из снимка, а не пропуск: вызывающий решает, отказ ли это среды (снимок до
607
+ * работы) или нарушение области (после).
608
+ *
609
+ * Пустые каталоги (только каталоги, рекурсивно, без записи всем)
610
+ * нарушением не считаются, если до снимка пути не было или он тоже был без
611
+ * файлов: исполняемой конфигурации в них нет, а CLI исполнителя создаёт
612
+ * такие служебные каталоги (`.claude/.cc-writes`) рядом с каждым записанным
613
+ * файлом. Путь, где раньше были файлы, по-прежнему нарушение при любом
614
+ * изменении.
520
615
  */
521
616
  export function protectedChanges(before, root) {
522
617
  const after = protectedSnapshot(root);
package/lib/index.d.ts CHANGED
@@ -63,6 +63,11 @@ export { ReviewProbes, probeLimits, observeReproductions } from './agents/review
63
63
  export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, type Redactor, } from './environment/redaction.ts';
64
64
  export { hostGitArgs } from './environment/process.ts';
65
65
  export { UntrustedCheckoutError, assertTrustedCheckout, forgetWorktree, gitHardening, rememberWorktree, resetGitTrust, worktreeAddPath, worktreeKey, } from './environment/git-trust.ts';
66
+ /**
67
+ * Корень рабочих деревьев попыток: хост выбирает его сам (`checkoutRoot`)
68
+ * или показывает в диагностике выбор по умолчанию.
69
+ */
70
+ export { checkoutCacheBase, checkoutPath, chooseCheckoutRoot, type CheckoutPlacement, type CheckoutRoot, type CheckoutRootInput, } from './environment/checkout-root.ts';
66
71
  export { closeIfBasisChanged } from './engine/property-recovery.ts';
67
72
  export { analyzeRecovery, applyCases, recoveryBrief, recoveryOutputSchema, recoveryResultSchema, } from './control/recovery.ts';
68
73
  export { BlockedError, classifyFailure, providerRefusal } from './engine/classify.ts';
package/lib/index.js CHANGED
@@ -65,6 +65,11 @@ export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, }
65
65
  // git над теми же деревьями, сверяет репозиторий теми же правилами.
66
66
  export { hostGitArgs } from "./environment/process.js";
67
67
  export { UntrustedCheckoutError, assertTrustedCheckout, forgetWorktree, gitHardening, rememberWorktree, resetGitTrust, worktreeAddPath, worktreeKey, } from "./environment/git-trust.js";
68
+ /**
69
+ * Корень рабочих деревьев попыток: хост выбирает его сам (`checkoutRoot`)
70
+ * или показывает в диагностике выбор по умолчанию.
71
+ */
72
+ export { checkoutCacheBase, checkoutPath, chooseCheckoutRoot, } from "./environment/checkout-root.js";
68
73
  export { closeIfBasisChanged } from "./engine/property-recovery.js";
69
74
  export { analyzeRecovery, applyCases, recoveryBrief, recoveryOutputSchema, recoveryResultSchema, } from "./control/recovery.js";
70
75
  // Классы отказов и правила отказов: хост бросает их из своих хуков и
@@ -1,6 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  import { type ContractArtifact, type ExecutionPolicy } from '../contracts/index.ts';
3
3
  import { type CorpusStore } from './corpus.ts';
4
+ import { type Boundary } from './gates.ts';
4
5
  /**
5
6
  * Быстрый маршрут: подтверждённый пример становится обязательным случаем.
6
7
  *
@@ -56,10 +57,12 @@ export interface ConfirmContext {
56
57
  stateDir: string;
57
58
  repoPath(repo: ExecutionPolicy['repositories'][number]): string;
58
59
  /** Закрытое проверке и открытое внутри него. */
59
- boundary(): {
60
- hidden: string[];
61
- readable: string[];
62
- };
60
+ boundary(): Boundary;
61
+ /**
62
+ * Каталог рабочего дерева вида `kind` (корень вне дерева, `checkout-root.ts`);
63
+ * без него — прежнее место в каталоге состояния.
64
+ */
65
+ checkout?(repositoryId: string, kind: string, id: string): string;
63
66
  /** Источник переменных окружения (по умолчанию — процесс). */
64
67
  environment?: NodeJS.ProcessEnv;
65
68
  }
@@ -278,8 +278,9 @@ async function decide(ctx, work, ref, input, source) {
278
278
  };
279
279
  const runs = [];
280
280
  const durations = [];
281
- await mkdir(join(ctx.stateDir, 'case-checks'), { recursive: true });
282
- const dir = await realpath(await mkdtemp(join(ctx.stateDir, 'case-checks', 'case-')));
281
+ const cases = ctx.checkout?.(repo.id, 'case-checks', '') ?? join(ctx.stateDir, 'case-checks');
282
+ await mkdir(cases, { recursive: true });
283
+ const dir = await realpath(await mkdtemp(join(cases, 'case-')));
283
284
  await rm(dir, { recursive: true, force: true });
284
285
  await git(repoPath, 'worktree', 'add', '--detach', dir, source.sha);
285
286
  const io = await realpath(await mkdtemp(join(tmpdir(), 'harness-case-')));
@@ -314,6 +315,7 @@ async function decide(ctx, work, ref, input, source) {
314
315
  write: [dir, io],
315
316
  readable: boundary.readable,
316
317
  controller: boundary.hidden,
318
+ ...(boundary.checkouts?.length ? { checkouts: boundary.checkouts } : {}),
317
319
  settingsDir: join(io, `settings-${i}`),
318
320
  });
319
321
  durations.push(Date.now() - started);
@@ -1,16 +1,20 @@
1
1
  import { type EvidenceRecord, type ExecutionPolicy } from '../contracts/index.ts';
2
+ import { type Boundary } from './gates.ts';
2
3
  type Repo = ExecutionPolicy['repositories'][number];
3
4
  /** Что нужно проверке на SHA от controller (как у эксперимента выполнимости). */
4
5
  export interface GatesAtContext {
5
6
  policy: ExecutionPolicy;
6
- /** Каталог состояния: здесь рабочее дерево, снимки зависимостей и логи. */
7
+ /** Каталог состояния: здесь логи, а при прежнем размещении — и рабочее дерево со снимками. */
7
8
  stateDir: string;
9
+ /**
10
+ * Корень рабочего дерева и снимков зависимостей проверки
11
+ * (`<checkoutRoot>/<repositoryId>/gates-at/<id>`). Без него —
12
+ * `chooseCheckoutRoot` по каталогу состояния и репозиториям политики.
13
+ */
14
+ checkoutRoot?: string;
8
15
  repoPath(repo: Repo): string;
9
16
  /** Закрытое проверке и открытое внутри него — та же граница, что у gates попыток. */
10
- boundary(): {
11
- hidden: string[];
12
- readable: string[];
13
- };
17
+ boundary(): Boundary;
14
18
  environment?: NodeJS.ProcessEnv;
15
19
  resourceDatabase?: string;
16
20
  }