devcontour-harness 0.1.0-alpha.18 → 0.1.0-alpha.20

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 (56) hide show
  1. package/README.md +20 -2
  2. package/docs/architecture.md +48 -0
  3. package/docs/contracts.md +3 -0
  4. package/docs/quickstart.md +1 -1
  5. package/docs/release-notes/0.1.0-alpha.19.md +96 -0
  6. package/docs/release-notes/0.1.0-alpha.20.md +42 -0
  7. package/docs/upgrade.md +17 -16
  8. package/lib/agents/review-probe.js +2 -1
  9. package/lib/cli.js +7 -1
  10. package/lib/contracts/cli.d.ts +30 -2
  11. package/lib/contracts/events.d.ts +21 -0
  12. package/lib/contracts/events.js +7 -0
  13. package/lib/contracts/execution.d.ts +24 -3
  14. package/lib/contracts/execution.js +14 -2
  15. package/lib/contracts/planning.js +2 -2
  16. package/lib/contracts/policy.d.ts +1 -1
  17. package/lib/contracts/ports.d.ts +6 -0
  18. package/lib/contracts/primitives.d.ts +13 -0
  19. package/lib/contracts/primitives.js +15 -0
  20. package/lib/contracts/profiles.js +2 -2
  21. package/lib/contracts/published.d.ts +23 -2
  22. package/lib/contracts/review.d.ts +2 -2
  23. package/lib/contracts/review.js +2 -2
  24. package/lib/contracts/work.js +3 -3
  25. package/lib/control/base-move.js +2 -2
  26. package/lib/control/harness.d.ts +1 -1
  27. package/lib/control/harness.js +7 -2
  28. package/lib/control/workflow.js +6 -0
  29. package/lib/engine/budget.d.ts +1 -1
  30. package/lib/engine/engine.d.ts +14 -2
  31. package/lib/engine/engine.js +40 -1
  32. package/lib/engine/runner.d.ts +11 -1
  33. package/lib/engine/runner.js +82 -11
  34. package/lib/environment/git-trust.d.ts +36 -0
  35. package/lib/environment/git-trust.js +174 -0
  36. package/lib/environment/isolation.d.ts +103 -1
  37. package/lib/environment/isolation.js +340 -5
  38. package/lib/environment/live-calls.js +3 -2
  39. package/lib/environment/os-tools.d.ts +15 -0
  40. package/lib/environment/os-tools.js +35 -0
  41. package/lib/environment/process.d.ts +5 -0
  42. package/lib/environment/process.js +43 -6
  43. package/lib/index.d.ts +2 -0
  44. package/lib/index.js +4 -0
  45. package/lib/integrations/connector/config.js +2 -2
  46. package/lib/storage/document.d.ts +10 -2
  47. package/lib/verification/confirm.js +2 -2
  48. package/lib/verification/gates.d.ts +12 -1
  49. package/lib/verification/gates.js +81 -8
  50. package/lib/verification/requirements.js +6 -1
  51. package/package.json +1 -1
  52. package/schemas/execution-document.schema.json +27 -5
  53. package/schemas/plan-draft.schema.json +2 -2
  54. package/schemas/run-event.schema.json +22 -0
  55. package/schemas/work-graph.schema.json +2 -2
  56. package/schemas/work-order.schema.json +2 -2
@@ -1,9 +1,11 @@
1
1
  import { homedir, tmpdir } from 'node:os';
2
- import { join, sep } from 'node:path';
2
+ import { dirname, join, relative, sep } from 'node:path';
3
3
  import { createRequire } from 'node:module';
4
4
  import { writeFile, mkdir } from 'node:fs/promises';
5
- import { realpathSync, readdirSync } from 'node:fs';
5
+ import { existsSync, lstatSync, readlinkSync, realpathSync, readdirSync } from 'node:fs';
6
+ import { spawn } from 'node:child_process';
6
7
  import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
8
+ import { DANGEROUS_FILES, getDangerousDirectories, } from '@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-utils.js';
7
9
  /**
8
10
  * Каталоги учётных данных. Закрыть весь $HOME нельзя — там проверяемый
9
11
  * checkout и инструменты, — поэтому закрываются известные места ключей и
@@ -193,6 +195,319 @@ export function isolationSupport() {
193
195
  ? { ok: false, detail: 'Не хватает зависимостей песочницы: ' + errors.join('; ') }
194
196
  : { ok: true, detail: warnings.join('; ') };
195
197
  }
198
+ /**
199
+ * Обязательные запреты записи sandbox-runtime для корней проверки — без
200
+ * каталогов IDE внутри дерева зависимостей.
201
+ *
202
+ * srt всегда запрещает запись в конфигурацию shell, git, IDE и Claude
203
+ * (README «Mandatory Deny Paths»), и отключить это можно только вместе со
204
+ * всей файловой политикой. На macOS запрет `.idea`/`.vscode` действует на
205
+ * любой глубине под текущим каталогом процесса srt, в том числе внутри
206
+ * `node_modules`; на Linux тот же запрет `node_modules` пропускает. Пакеты
207
+ * публикуют `.idea/` (так поставляются и распространённые транзитивные
208
+ * зависимости), и установка зависимостей в чистом worktree падала с EPERM
209
+ * при любом коде.
210
+ *
211
+ * Запрет защищает от конфигурации, которую песочница подложит, а человек
212
+ * потом откроет в IDE или git исполнит на хосте. Дерево зависимостей IDE как
213
+ * конфигурацию проекта не открывает, поэтому на macOS srt запускается из
214
+ * собственного каталога проверки, а запреты для корней задаются здесь явно:
215
+ *
216
+ * - конфигурация shell и git, `.mcp.json`, `.claude/commands|agents`,
217
+ * `.git/hooks`, `.git/config` — в корне и на любой глубине, как у srt;
218
+ * - `.idea` и `.vscode` — в корне и в каждом подкаталоге существующих
219
+ * каталогов до глубины `ideDepth`, кроме `node_modules`. Глоб srt не умеет
220
+ * «кроме node_modules», поэтому дерево перечисляется: новый каталог глубже
221
+ * существующего уровня не закрыт (у srt на Linux закрыты только уже
222
+ * существующие файлы до глубины 3).
223
+ *
224
+ * Путь с символами глоба нельзя записать шаблоном без риска не совпасть ни
225
+ * с чем; тогда возвращается `undefined`, и srt остаётся в прежнем каталоге с
226
+ * полным собственным запретом.
227
+ */
228
+ export const ideDirectories = ['.idea', '.vscode'];
229
+ const ideDepth = 3;
230
+ const ideDirsLimit = 2000;
231
+ const glob = /[*?[\]]/;
232
+ /**
233
+ * Отказ собрать политику песочницы: проверка не запускается, а не идёт с
234
+ * молча урезанными запретами.
235
+ */
236
+ export class SandboxPolicyError extends Error {
237
+ name = 'SandboxPolicyError';
238
+ }
239
+ /** Файлы обычного `.git`, которые уводят git в другой репозиторий или конфигурацию. */
240
+ const gitRedirects = ['commondir', 'gitdir', 'config.worktree'];
241
+ export function protectedWriteDenies(roots) {
242
+ if (roots.some((r) => glob.test(r)))
243
+ return undefined;
244
+ const strict = [
245
+ ...DANGEROUS_FILES,
246
+ ...getDangerousDirectories().filter((d) => !ideDirectories.includes(d)),
247
+ '.git/hooks',
248
+ '.git/config',
249
+ ];
250
+ const denies = [];
251
+ for (const root of roots) {
252
+ for (const name of strict)
253
+ denies.push(join(root, name), join(root, '**', name));
254
+ for (const name of ideDirectories)
255
+ denies.push(join(root, name));
256
+ // Git хоста потом читает этот checkout: подменённый файл `.git`,
257
+ // перенаправление обычного `.git` или вложенный репозиторий увели бы его
258
+ // в конфигурацию, написанную проверкой (`git-trust.ts`).
259
+ denies.push(...rootGitDenies(root), join(root, '*', '**', '.git'));
260
+ // Обход в ширину: сначала мелкие уровни. Предел держит профиль песочницы
261
+ // в разумном размере; дерево больше предела — отказ, а не урезанные запреты.
262
+ let level = [root], seen = 0;
263
+ for (let depth = 0; depth < ideDepth && level.length; depth++) {
264
+ const next = [];
265
+ for (const dir of level) {
266
+ if (++seen > ideDirsLimit)
267
+ throw new SandboxPolicyError(`песочница проверки не собрана: в ${root} больше ${ideDirsLimit} каталогов до глубины ${ideDepth} вне node_modules — запреты каталогов IDE не перечислить`);
268
+ const safe = !glob.test(dir);
269
+ for (const name of ideDirectories) {
270
+ // Любой подкаталог, и появившийся во время проверки: `node_modules/.idea`
271
+ // этим правилом тоже закрыт, но пакеты лежат уровнем ниже.
272
+ if (safe)
273
+ denies.push(join(dir, '*', name));
274
+ }
275
+ let entries = [];
276
+ try {
277
+ entries = readdirSync(dir, { withFileTypes: true });
278
+ }
279
+ catch {
280
+ continue;
281
+ }
282
+ for (const entry of entries) {
283
+ if (!entry.isDirectory() || entry.name === 'node_modules' || entry.name === '.git')
284
+ continue;
285
+ const child = join(dir, entry.name);
286
+ if (!safe || glob.test(entry.name))
287
+ // Шаблоном такой каталог не записать: закрываются его собственные имена.
288
+ for (const name of ideDirectories)
289
+ denies.push(join(child, name));
290
+ next.push(child);
291
+ }
292
+ }
293
+ level = next;
294
+ }
295
+ }
296
+ return [...new Set(denies)];
297
+ }
298
+ /** Запреты для `.git` корня: файл рабочего дерева целиком, у каталога — перенаправления. */
299
+ function rootGitDenies(root) {
300
+ const dotgit = join(root, '.git');
301
+ try {
302
+ if (lstatSync(dotgit).isDirectory())
303
+ return gitRedirects.map((n) => join(dotgit, n));
304
+ }
305
+ catch {
306
+ return [];
307
+ }
308
+ return [dotgit];
309
+ }
310
+ /**
311
+ * Явные запреты для Linux. srt там закрывает только уже существующие пути и
312
+ * сам пропускает `node_modules`; файл `.git` рабочего дерева добавляется.
313
+ */
314
+ export function linuxWriteDenies(roots) {
315
+ return roots.flatMap((root) => {
316
+ const dotgit = join(root, '.git');
317
+ try {
318
+ return lstatSync(dotgit).isFile() ? [dotgit] : [];
319
+ }
320
+ catch {
321
+ return [];
322
+ }
323
+ });
324
+ }
325
+ /**
326
+ * Обязательный запрет записи, под который попадает `path` внутри открытых
327
+ * проверке каталогов. `undefined` — путь вне таких запретов: отказ в нём —
328
+ * не следствие обязательной политики песочницы.
329
+ */
330
+ export function mandatoryDenyRule(policy, path) {
331
+ const root = policy.write.find((w) => path === w || path.startsWith(w + sep));
332
+ if (!root)
333
+ return undefined;
334
+ const parts = relative(root, path).split(sep);
335
+ const at = (i, ...names) => names.every((n, k) => parts[i + k] === n);
336
+ const rule = (what) => `обязательный запрет записи sandbox-runtime: ${what}`;
337
+ for (let i = 0; i < parts.length; i++) {
338
+ const name = parts[i];
339
+ if (DANGEROUS_FILES.includes(name) && i === parts.length - 1)
340
+ return rule(name);
341
+ // Каталоги IDE внутри дерева зависимостей открыты (`protectedWriteDenies`).
342
+ if (ideDirectories.includes(name) && !parts.slice(0, i).includes('node_modules'))
343
+ return rule(`каталог IDE ${name}`);
344
+ if (at(i, '.git', 'hooks') || at(i, '.git', 'config'))
345
+ return rule(parts.slice(i, i + 2).join('/'));
346
+ if (name === '.git' && i === 0 && parts.length === 1)
347
+ return rule('файл .git рабочего дерева');
348
+ if (name === '.git' && i === 0 && gitRedirects.includes(parts[1] ?? ''))
349
+ return rule(`.git/${parts[1]}`);
350
+ if (name === '.git' && i > 0)
351
+ return rule('вложенный репозиторий .git');
352
+ if (at(i, '.claude', 'commands') || at(i, '.claude', 'agents'))
353
+ return rule(parts.slice(i, i + 2).join('/'));
354
+ }
355
+ return undefined;
356
+ }
357
+ /**
358
+ * Отказы песочницы из журнала ядра macOS для одной проверки.
359
+ *
360
+ * srt помечает каждое правило запрета тегом с началом команды (base64) и
361
+ * суффиксом сессии `_SBX`; команда проверки начинается с уникального
362
+ * токена, и записи чужих песочниц на той же машине сюда не попадают. Текст
363
+ * вывода проверки свидетельством не служит: его печатает сама проверка.
364
+ */
365
+ export function parseSandboxLog(text, tag) {
366
+ const found = [];
367
+ const lines = text.split('\n');
368
+ for (let i = 0; i < lines.length; i++) {
369
+ const m = /Sandbox: .*? deny\(\d+\) (file-[\w-]+) (\/.*)$/.exec(lines[i]);
370
+ if (!m)
371
+ continue;
372
+ const cmd = /^CMD64_(.+?)_END/.exec(lines[i + 1] ?? '');
373
+ if (!cmd || !Buffer.from(cmd[1], 'base64').toString('utf8').includes(tag))
374
+ continue;
375
+ found.push({ operation: m[1], path: m[2].trim() });
376
+ }
377
+ return found;
378
+ }
379
+ /** Наблюдение за журналом песочницы на время проверки; без `log` — `undefined`. */
380
+ export async function watchSandboxLog(tag) {
381
+ if (process.platform !== 'darwin' || !existsSync('/usr/bin/log'))
382
+ return undefined;
383
+ const child = spawn('/usr/bin/log', ['stream', '--style', 'compact', '--predicate', 'eventMessage ENDSWITH "_SBX"'], { stdio: ['ignore', 'pipe', 'ignore'] });
384
+ let text = '';
385
+ child.stdout.setEncoding('utf8');
386
+ const ready = await new Promise((done) => {
387
+ const timer = setTimeout(() => done(false), 3000);
388
+ child.stdout.on('data', (chunk) => {
389
+ text += chunk;
390
+ // Заголовок `log stream` печатается, когда подписка уже действует.
391
+ if (text.includes('Filtering the log data')) {
392
+ clearTimeout(timer);
393
+ done(true);
394
+ }
395
+ });
396
+ child.once('error', () => {
397
+ clearTimeout(timer);
398
+ done(false);
399
+ });
400
+ child.once('exit', () => {
401
+ clearTimeout(timer);
402
+ done(false);
403
+ });
404
+ });
405
+ const stop = () => {
406
+ child.stdout.removeAllListeners('data');
407
+ child.kill();
408
+ };
409
+ if (!ready) {
410
+ stop();
411
+ return undefined;
412
+ }
413
+ return {
414
+ /** Ждёт `drainMs`, пока ядро допишет записи, и возвращает отказы проверки. */
415
+ async stop(drainMs) {
416
+ if (drainMs)
417
+ await new Promise((r) => setTimeout(r, drainMs));
418
+ stop();
419
+ return parseSandboxLog(text, tag);
420
+ },
421
+ };
422
+ }
423
+ /**
424
+ * Отказы обязательной политики в открытых проверке каталогах, которые
425
+ * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
426
+ * а не среды: её здесь нет.
427
+ */
428
+ export function sandboxDenials(violations, policy) {
429
+ const found = new Map();
430
+ for (const v of violations) {
431
+ if (!v.operation.startsWith('file-write'))
432
+ continue;
433
+ const rule = mandatoryDenyRule(policy, v.path);
434
+ if (rule && !found.has(v.path))
435
+ found.set(v.path, rule);
436
+ }
437
+ return [...found].map(([path, rule]) => ({ path, rule }));
438
+ }
439
+ /** Имена, которые проверка и исполнитель не создают и не меняют. */
440
+ const protectedNames = new Set([...DANGEROUS_FILES, ...ideDirectories, '.claude', '.git']);
441
+ const snapshotLimit = 200_000;
442
+ /**
443
+ * Защищённые элементы checkout вне `node_modules`: путь → подпись.
444
+ *
445
+ * Запреты песочницы проверяют только путь операции. Каталог, собранный
446
+ * внутри `node_modules` (там каталоги IDE открыты) и затем перенесённый в
447
+ * дерево проекта, или новый каталог глубже перечисленных уровней ими не
448
+ * закрыты; сверка снимков до и после проверки находит такой результат.
449
+ */
450
+ export function protectedSnapshot(root) {
451
+ const found = new Map();
452
+ let seen = 0;
453
+ const count = () => {
454
+ if (++seen > snapshotLimit)
455
+ throw new SandboxPolicyError(`сверка защищённых путей не выполнена: в ${root} больше ${snapshotLimit} элементов вне node_modules`);
456
+ };
457
+ const signature = (path) => {
458
+ count();
459
+ let stat;
460
+ try {
461
+ stat = lstatSync(path);
462
+ }
463
+ catch {
464
+ return 'missing';
465
+ }
466
+ if (stat.isSymbolicLink())
467
+ return 'l:' + readlinkSync(path);
468
+ if (!stat.isDirectory())
469
+ return `f:${stat.size}:${stat.mtimeMs}:${stat.ino}`;
470
+ const inner = readdirSync(path)
471
+ .sort()
472
+ .map((name) => `${name}=${signature(join(path, name))}`);
473
+ return `d:${stat.ino}[${inner.join(',')}]`;
474
+ };
475
+ const walk = (dir) => {
476
+ let entries;
477
+ try {
478
+ entries = readdirSync(dir, { withFileTypes: true });
479
+ }
480
+ catch {
481
+ return;
482
+ }
483
+ for (const entry of entries) {
484
+ count();
485
+ const path = join(dir, entry.name);
486
+ if (entry.name === '.git' && dir === root && entry.isDirectory()) {
487
+ // Обычный `.git`: объекты и индекс меняет и git хоста; сверяются
488
+ // только конфигурация, hooks и перенаправления.
489
+ for (const name of ['config', 'hooks', ...gitRedirects])
490
+ found.set(join(path, name), signature(join(path, name)));
491
+ continue;
492
+ }
493
+ if (protectedNames.has(entry.name)) {
494
+ found.set(path, signature(path));
495
+ continue;
496
+ }
497
+ if (entry.isDirectory() && entry.name !== 'node_modules')
498
+ walk(path);
499
+ }
500
+ };
501
+ walk(root);
502
+ return found;
503
+ }
504
+ /** Защищённые пути, которые появились или изменились после снимка `before`. */
505
+ export function protectedChanges(before, root) {
506
+ const after = protectedSnapshot(root);
507
+ return [...after]
508
+ .filter(([path, sig]) => sig !== 'missing' && before.get(path) !== sig)
509
+ .map(([path]) => path);
510
+ }
196
511
  /**
197
512
  * Команда проверки внутри sandbox-runtime.
198
513
  *
@@ -200,20 +515,36 @@ export function isolationSupport() {
200
515
  * не откатывается к умолчаниям. Собственный служебный сокет srt кладёт во
201
516
  * временный каталог процесса, поэтому srt получает короткий системный
202
517
  * TMPDIR, а команде внутри передаётся свой scratch.
518
+ *
519
+ * `cwd` — каталог, из которого запускается srt (см. `protectedWriteDenies`):
520
+ * на macOS это каталог метки старта, а в рабочий каталог проверки обёртка
521
+ * переходит сама перед exec.
203
522
  */
204
523
  export async function isolatedCommand(policy, argv, settingsDir, scratch,
205
524
  /**
206
525
  * Файл, который обёртка создаёт внутри песочницы перед exec команды. Его
207
526
  * отсутствие — единственный достоверный признак, что команда не начиналась.
208
527
  */
209
- started) {
528
+ started,
529
+ /** Рабочий каталог команды. */
530
+ workdir,
531
+ /** Корни, которым нужны обязательные запреты записи (checkout проверки). */
532
+ protect = [workdir], platform = process.platform,
533
+ /**
534
+ * Токен в начале команды: srt кладёт начало команды в тег записей журнала
535
+ * ядра, и по нему отказы этой проверки отличаются от чужих (`parseSandboxLog`).
536
+ */
537
+ tag = '') {
538
+ if (!/^[a-z0-9]*$/.test(tag))
539
+ throw new Error('Токен журнала песочницы — только [a-z0-9]');
210
540
  await mkdir(settingsDir, { recursive: true });
211
541
  const settings = join(settingsDir, 'isolation.json');
542
+ const denies = platform === 'darwin' ? protectedWriteDenies(protect) : undefined;
212
543
  await writeFile(settings, JSON.stringify({
213
544
  network: { allowedDomains: policy.domains, deniedDomains: [], allowLocalBinding: true },
214
545
  filesystem: {
215
546
  allowWrite: policy.write,
216
- denyWrite: [],
547
+ denyWrite: denies ?? (platform === 'linux' ? linuxWriteDenies(protect) : []),
217
548
  denyRead: policy.hidden,
218
549
  allowRead: policy.readable,
219
550
  },
@@ -227,12 +558,16 @@ started) {
227
558
  '--',
228
559
  '/bin/sh',
229
560
  '-c',
230
- ': > "$0" && exec "$@"',
561
+ `${tag ? `: ${tag}; ` : ''}: > "$0" && cd -- "$1" && shift && exec "$@"`,
231
562
  started,
563
+ workdir,
232
564
  '/usr/bin/env',
233
565
  `TMPDIR=${scratch}`,
234
566
  ...argv,
235
567
  ],
236
568
  env: { TMPDIR: tmpdir() },
569
+ // Без явных запретов srt остаётся в рабочем каталоге: его собственный
570
+ // обязательный запрет действует от него.
571
+ cwd: denies ? dirname(started) : workdir,
237
572
  };
238
573
  }
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from 'node:crypto';
2
- import { osTool } from "./os-tools.js";
2
+ import { osTool, osToolEnv } from "./os-tools.js";
3
3
  import { execFileSync } from 'node:child_process';
4
4
  import { readFileSync } from 'node:fs';
5
5
  import { registerMonotonic, registerProcess } from "../engine/usage.js";
@@ -9,7 +9,7 @@ export function processStartedAt(pid) {
9
9
  try {
10
10
  const out = execFileSync(osTool('ps'), ['-o', 'lstart=', '-p', String(pid)], {
11
11
  encoding: 'utf8',
12
- env: { ...process.env, LC_ALL: 'C' },
12
+ env: osToolEnv(),
13
13
  stdio: ['ignore', 'pipe', 'ignore'],
14
14
  timeout: 2000,
15
15
  }).trim();
@@ -59,6 +59,7 @@ export const BOOT_ID = (() => {
59
59
  try {
60
60
  const out = execFileSync(osTool('sysctl'), ['-n', 'kern.boottime'], {
61
61
  encoding: 'utf8',
62
+ env: osToolEnv(),
62
63
  stdio: ['ignore', 'pipe', 'ignore'],
63
64
  timeout: 2000,
64
65
  });
@@ -14,3 +14,18 @@ export declare const OS_TOOL_CANDIDATES: {
14
14
  export type OsTool = keyof typeof OS_TOOL_CANDIDATES;
15
15
  /** Исполняемый файл утилиты: первый существующий штатный путь, иначе имя для PATH. */
16
16
  export declare function osTool(name: OsTool, candidates?: readonly string[]): string;
17
+ /**
18
+ * Окружение утилиты, чей вывод ядро разбирает: даты, числа и сообщения — в
19
+ * локали C при любой локали пользователя. В ru_RU `ps -o lstart=` печатает
20
+ * «среда, 28 октября 2026 г. 16:42:10», и `Date.parse` его не читает. Только
21
+ * LC_CTYPE остаётся пользовательским: в локали C `lsof` экранирует байты
22
+ * не-ASCII путей (`\xd0\xbb…`), и каталог с кириллицей не узнаётся. Поэтому не
23
+ * `LC_ALL=C`: LC_ALL перекрыл бы LC_CTYPE, и его значение переносится в LC_CTYPE.
24
+ */
25
+ export declare function osToolEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
26
+ /**
27
+ * Имя файла из вывода `lsof`: в локали без UTF-8 он экранирует байты вне
28
+ * ASCII как `\xNN`, обратную косую — как `\\`, управляющие — как `\t`, `\n` и
29
+ * т. п. Здесь экранирование снимается, и путь сравним с настоящим.
30
+ */
31
+ export declare function lsofName(name: string): string;
@@ -33,3 +33,38 @@ export function osTool(name, candidates = OS_TOOL_CANDIDATES[name]) {
33
33
  resolved.set(name, found);
34
34
  return found;
35
35
  }
36
+ /**
37
+ * Окружение утилиты, чей вывод ядро разбирает: даты, числа и сообщения — в
38
+ * локали C при любой локали пользователя. В ru_RU `ps -o lstart=` печатает
39
+ * «среда, 28 октября 2026 г. 16:42:10», и `Date.parse` его не читает. Только
40
+ * LC_CTYPE остаётся пользовательским: в локали C `lsof` экранирует байты
41
+ * не-ASCII путей (`\xd0\xbb…`), и каталог с кириллицей не узнаётся. Поэтому не
42
+ * `LC_ALL=C`: LC_ALL перекрыл бы LC_CTYPE, и его значение переносится в LC_CTYPE.
43
+ */
44
+ export function osToolEnv(env = process.env) {
45
+ const { LC_ALL, ...rest } = env;
46
+ const ctype = LC_ALL || env.LC_CTYPE || env.LANG;
47
+ return {
48
+ ...rest,
49
+ LC_TIME: 'C',
50
+ LC_NUMERIC: 'C',
51
+ LC_MESSAGES: 'C',
52
+ ...(ctype ? { LC_CTYPE: ctype } : {}),
53
+ };
54
+ }
55
+ /**
56
+ * Имя файла из вывода `lsof`: в локали без UTF-8 он экранирует байты вне
57
+ * ASCII как `\xNN`, обратную косую — как `\\`, управляющие — как `\t`, `\n` и
58
+ * т. п. Здесь экранирование снимается, и путь сравним с настоящим.
59
+ */
60
+ export function lsofName(name) {
61
+ if (!name.includes('\\'))
62
+ return name;
63
+ const simple = { b: 8, t: 9, n: 10, f: 12, r: 13, '\\': 92 };
64
+ const bytes = name.split(/(\\x[0-9a-fA-F]{2}|\\[btnfr\\])/).flatMap((part, i) => {
65
+ if (i % 2 === 0)
66
+ return [...Buffer.from(part, 'utf8')];
67
+ return [part[1] === 'x' ? parseInt(part.slice(2), 16) : simple[part[1]]];
68
+ });
69
+ return Buffer.from(bytes).toString('utf8');
70
+ }
@@ -37,4 +37,9 @@ export declare function command(argv: string[], cwd: string, options?: {
37
37
  dirs: string[];
38
38
  };
39
39
  }): Promise<CommandResult>;
40
+ /**
41
+ * Аргументы git хоста над `cwd`: репозиторий сверен (`assertTrustedCheckout`),
42
+ * исполняемые настройки сняты. Один путь для всех вызовов git хоста.
43
+ */
44
+ export declare function hostGitArgs(cwd: string, args: string[]): string[];
40
45
  export declare function git(cwd: string, ...args: string[]): Promise<string>;
@@ -1,8 +1,10 @@
1
1
  import { spawn, spawnSync, execFile } from 'node:child_process';
2
- import { osTool } from "./os-tools.js";
2
+ import { lsofName, osTool, osToolEnv } from "./os-tools.js";
3
3
  import { randomUUID } from 'node:crypto';
4
4
  import { readdirSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
5
5
  import { StringDecoder } from 'node:string_decoder';
6
+ import { resolve } from 'node:path';
7
+ import { assertTrustedCheckout, forgetWorktree, worktreeKey, gitHardening, rememberWorktree, worktreeAddPath, } from "./git-trust.js";
6
8
  import { outputRedactor } from "./redaction.js";
7
9
  export async function command(argv, cwd, options = {}) {
8
10
  const [file, ...args] = argv;
@@ -198,6 +200,7 @@ function captureProcessTree(pid) {
198
200
  };
199
201
  const result = spawnSync(osTool('ps'), ['-axo', 'pid=,ppid=,pgid=,comm='], {
200
202
  encoding: 'utf8',
203
+ env: osToolEnv(),
201
204
  timeout: 250,
202
205
  maxBuffer: 1_000_000,
203
206
  });
@@ -225,8 +228,21 @@ function captureProcessTree(pid) {
225
228
  }
226
229
  return { available: true, processes: rows.filter((r) => ids.has(r.pid)).slice(0, 100) };
227
230
  }
231
+ /**
232
+ * Аргументы git хоста над `cwd`: репозиторий сверен (`assertTrustedCheckout`),
233
+ * исполняемые настройки сняты. Один путь для всех вызовов git хоста.
234
+ */
235
+ export function hostGitArgs(cwd, args) {
236
+ assertTrustedCheckout(cwd);
237
+ return [...gitHardening, ...args];
238
+ }
228
239
  export async function git(cwd, ...args) {
229
- const result = await command(['git', ...args], cwd, {
240
+ const added = worktreeAddPath(args);
241
+ // Путь убираемого дерева — до удаления: потом настоящий путь уже не узнать.
242
+ const removed = args[0] === 'worktree' && args[1] === 'remove'
243
+ ? worktreeKey(resolve(cwd, args.at(-1)))
244
+ : undefined;
245
+ const result = await command(['git', ...hostGitArgs(cwd, args)], cwd, {
230
246
  env: {
231
247
  ...process.env,
232
248
  GIT_TERMINAL_PROMPT: '0',
@@ -238,12 +254,19 @@ export async function git(cwd, ...args) {
238
254
  });
239
255
  if (result.code !== 0)
240
256
  throw new Error(`git ${args[0]}: ${result.stderr.trim() || result.stdout.trim()}`);
257
+ if (added)
258
+ rememberWorktree(resolve(cwd, added));
259
+ if (removed)
260
+ forgetWorktree(removed);
241
261
  return result.stdout.trim();
242
262
  }
243
- /** Вывод команды или null, если она не выполнилась. Не блокирует event loop. */
263
+ /**
264
+ * Вывод системной утилиты или null, если она не выполнилась. Не блокирует
265
+ * event loop. Локаль фиксирована (`osToolEnv`): вывод разбирается.
266
+ */
244
267
  function output(command, args, timeout) {
245
268
  return new Promise((resolve) => {
246
- execFile(command, args, { encoding: 'utf8', timeout, maxBuffer: 64_000_000 }, (error, stdout) => resolve(error ? null : stdout));
269
+ execFile(command, args, { encoding: 'utf8', env: osToolEnv(), timeout, maxBuffer: 64_000_000 }, (error, stdout) => resolve(error ? null : stdout));
247
270
  });
248
271
  }
249
272
  /** Процессы пользователя, в окружении которых есть метка. */
@@ -315,7 +338,18 @@ async function inside(dirs, since) {
315
338
  }
316
339
  });
317
340
  const started = new Map((await processTable()).map((r) => [r.pid, Date.parse(r.start)]));
318
- const fresh = (pid) => (started.get(pid) ?? 0) >= since - 1000;
341
+ // Нечитаемое время старта — не повод оставить процесс: каталоги принадлежат
342
+ // только этой команде, и утечка её потомка хуже ошибочной остановки.
343
+ // Отсекается только процесс, о котором точно известно, что он старше
344
+ // команды. Процесса нет в снимке — он запущен после снимка; это и сам
345
+ // lsof с текущим каталогом внутри, поэтому такой процесс не берётся: его
346
+ // потомка найдёт следующий проход.
347
+ const fresh = (pid) => {
348
+ if (!started.has(pid))
349
+ return false;
350
+ const at = started.get(pid);
351
+ return !Number.isFinite(at) || at >= since - 1000;
352
+ };
319
353
  const within = (path) => dirs.some((d) => path === d || path.startsWith(d + '/'));
320
354
  if (process.platform === 'linux')
321
355
  return readdirSync('/proc').flatMap((entry) => {
@@ -336,7 +370,10 @@ async function inside(dirs, since) {
336
370
  for (const line of (stdout ?? '').split('\n')) {
337
371
  if (line.startsWith('p'))
338
372
  pid = Number(line.slice(1));
339
- else if (line.startsWith('n') && within(line.slice(1)) && pid !== process.pid && fresh(pid))
373
+ else if (line.startsWith('n') &&
374
+ within(lsofName(line.slice(1))) &&
375
+ pid !== process.pid &&
376
+ fresh(pid))
340
377
  pids.push(pid);
341
378
  }
342
379
  return pids;
package/lib/index.d.ts CHANGED
@@ -61,6 +61,8 @@ export { explicitPrerequisites, gatePrerequisites, orderedScope, standaloneScope
61
61
  export { requirementProof, uncoveredGates, unprovenReason } from './verification/proof.ts';
62
62
  export { ReviewProbes, probeLimits, observeReproductions } from './agents/review-probe.ts';
63
63
  export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, type Redactor, } from './environment/redaction.ts';
64
+ export { hostGitArgs } from './environment/process.ts';
65
+ export { UntrustedCheckoutError, assertTrustedCheckout, forgetWorktree, gitHardening, rememberWorktree, resetGitTrust, worktreeAddPath, worktreeKey, } from './environment/git-trust.ts';
64
66
  export { closeIfBasisChanged } from './engine/property-recovery.ts';
65
67
  export { analyzeRecovery, applyCases, recoveryBrief, recoveryOutputSchema, recoveryResultSchema, } from './control/recovery.ts';
66
68
  export { BlockedError, classifyFailure, providerRefusal } from './engine/classify.ts';
package/lib/index.js CHANGED
@@ -61,6 +61,10 @@ export { explicitPrerequisites, gatePrerequisites, orderedScope, standaloneScope
61
61
  export { requirementProof, uncoveredGates, unprovenReason } from "./verification/proof.js";
62
62
  export { ReviewProbes, probeLimits, observeReproductions } from "./agents/review-probe.js";
63
63
  export { composeRedactors, outputRedactor, redactDeep, redactError, redactor, } from "./environment/redaction.js";
64
+ // Git хоста над checkout, где исполнялся чужой код: хост, запускающий свой
65
+ // git над теми же деревьями, сверяет репозиторий теми же правилами.
66
+ export { hostGitArgs } from "./environment/process.js";
67
+ export { UntrustedCheckoutError, assertTrustedCheckout, forgetWorktree, gitHardening, rememberWorktree, resetGitTrust, worktreeAddPath, worktreeKey, } from "./environment/git-trust.js";
64
68
  export { closeIfBasisChanged } from "./engine/property-recovery.js";
65
69
  export { analyzeRecovery, applyCases, recoveryBrief, recoveryOutputSchema, recoveryResultSchema, } from "./control/recovery.js";
66
70
  // Классы отказов и правила отказов: хост бросает их из своих хуков и
@@ -1,7 +1,7 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { dirname, isAbsolute, resolve } from 'node:path';
3
3
  import { z } from 'zod';
4
- import { HarnessError, digestOf, gateRefSchema, idSchema, relativePathSchema, roleIdSchema, sha256, } from "../../contracts/index.js";
4
+ import { HarnessError, digestOf, gateRefSchema, idSchema, relativePathSchema, roleIdSchema, sha256, gateScopeSchema, } from "../../contracts/index.js";
5
5
  /**
6
6
  * Конфигурация коннектора внешнего хранилища задач.
7
7
  *
@@ -53,7 +53,7 @@ export const taskMappingSchema = z.strictObject({
53
53
  .array(z.union([z.literal('.'), relativePathSchema]))
54
54
  .min(1)
55
55
  .max(100),
56
- gates: z.array(gateRefSchema).max(20).optional(),
56
+ gates: gateScopeSchema(gateRefSchema).optional(),
57
57
  criteria: z.array(criterionMappingSchema).max(100).default([]),
58
58
  /** Документы, без которых запуск блокируется (ID, ключ или имя). Остальные — дополнительные. */
59
59
  requiredDocuments: z.array(z.string().min(1).max(200)).max(30).default([]),