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
@@ -2,9 +2,10 @@ import { execFileSync } from 'node:child_process';
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { existsSync } from 'node:fs';
4
4
  import { mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
5
- import { isAbsolute, join, resolve } from 'node:path';
5
+ import { isAbsolute, join, relative, resolve } from 'node:path';
6
6
  import { roleBinding, selectReviewer, mcpEnvironment, HarnessError, digestOf, contextDigest, implementationResultSchema, codeReviewHistory, codeReviewScope, checkCodeReview, logicalReview, DEFAULT_REVIEW_PROTOCOL_RETRIES, reviewResultSchema, sha256, } from "../contracts/index.js";
7
- import { git } from "../environment/process.js";
7
+ import { git, hostGitArgs } from "../environment/process.js";
8
+ import { protectedChanges, protectedSnapshot } from "../environment/isolation.js";
8
9
  import { executionEnvironment, runSteps, withEnvironment } from "../environment/lifecycle.js";
9
10
  import { redactDeep } from "../environment/redaction.js";
10
11
  import { alreadySatisfiedReviewOutputSchema, implementationOutputSchema, reviewOutputSchema, } from "../agents/schemas.js";
@@ -20,6 +21,7 @@ import { defaultResourceDatabase, withResources } from "../environment/resources
20
21
  import { REQUIREMENT_GATE, assertRequirements } from "../verification/requirements.js";
21
22
  import { BlockedError, classifyFailure } from "./classify.js";
22
23
  import { TaskFailure } from "./failure.js";
24
+ import { activeOf, namesFailingCases } from "./engine.js";
23
25
  import { prompt } from "./prompt.js";
24
26
  import { contractDocuments, orderCheckManifest, referenceCodeNote, referenceSetFiles, setFileReference, } from "../verification/checks.js";
25
27
  import { CorpusStore, localRoots } from "../verification/corpus.js";
@@ -271,7 +273,7 @@ export class Runner {
271
273
  this.engine.pinLegacyCalls();
272
274
  }
273
275
  const now = this.engine.clock();
274
- const stale = this.engine.read((v) => v.attempts().filter((a) => a.status === 'active' && a.leaseUntil <= now));
276
+ const stale = this.engine.read((v) => activeOf(v).filter((a) => a.leaseUntil <= now));
275
277
  for (const a of stale) {
276
278
  if (!a.integrationSha)
277
279
  continue;
@@ -761,6 +763,10 @@ export class Runner {
761
763
  if (context)
762
764
  await writeFile(join(dir, 'context.json'), JSON.stringify(context, null, 2));
763
765
  await this.prepareSelfCheck(attempt, repo, join(artifacts, 'self-check'));
766
+ // Защищённые пути до работы исполнителя: перенос каталога,
767
+ // собранного там, где запрет песочницы не действует, виден
768
+ // только сверкой.
769
+ const guarded = this.policy.isolation.mode === 'os' ? protectedSnapshot(cwd) : undefined;
764
770
  const response = await this.call(this.adapter(attempt.runtime), {
765
771
  task: 'implement',
766
772
  attempt,
@@ -798,6 +804,13 @@ export class Runner {
798
804
  result.data.summary.slice(0, 500));
799
805
  this.engine.heartbeat(attempt.id, attempt.token);
800
806
  signal.throwIfAborted();
807
+ const planted = guarded ? protectedChanges(guarded, cwd) : [];
808
+ if (planted.length)
809
+ throw new TaskFailure('scope-violation', 'Исполнитель создал или изменил защищённые пути (конфигурация IDE, shell, git или Claude): ' +
810
+ planted
811
+ .slice(0, 5)
812
+ .map((p) => relative(cwd, p))
813
+ .join(', '));
801
814
  if ((await git(cwd, 'rev-parse', 'HEAD')) !== base)
802
815
  throw new TaskFailure('scope-violation', 'Исполнитель изменил HEAD; интеграцией владеет harness');
803
816
  await git(cwd, 'add', '-A');
@@ -1047,15 +1060,63 @@ export class Runner {
1047
1060
  JSON.parse(await readFile(file, 'utf8')).errors.join('; '));
1048
1061
  return { status: 'cleaned', receipts: cleaned };
1049
1062
  }
1050
- async gate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer) {
1063
+ async gate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer,
1064
+ /** ID записи провала, которую повторяет этот запуск (`recheckIntegration`). */
1065
+ recheck) {
1051
1066
  // Время проверок потребителя — отдельная стадия: в метриках области оно
1052
- // не смешивается с собственными gates поручения.
1067
+ // не смешивается с собственными gates поручения. Повтор — тоже своя
1068
+ // стадия: оценка длительности gate не удваивается из-за него.
1053
1069
  const stage = consumer
1054
1070
  ? `${phase}-consumer:${consumer.repositoryId}:${gate.id}`
1055
- : `${phase}-test:${gate.id}`;
1056
- await this.timed(attempt, stage, () => this.runOneGate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer));
1071
+ : recheck
1072
+ ? `${phase}-recheck:${gate.id}`
1073
+ : `${phase}-test:${gate.id}`;
1074
+ await this.timed(attempt, stage, () => this.runOneGate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer, recheck));
1057
1075
  }
1058
- async runOneGate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer) {
1076
+ /**
1077
+ * Gate интеграции с одним повтором на кандидата. Провал собственного gate на
1078
+ * integration, когда тот же gate прошёл на кандидате, часто вызван средой
1079
+ * (бюджет времени под конкуренцией за CPU), а не кодом; без повтора такой
1080
+ * провал оплачивался новой реализацией. Повтор — тот же gate на том же
1081
+ * integration SHA, один раз за интеграцию кандидата; обе записи остаются,
1082
+ * у повтора — `recheck` со ссылкой на первую и исходом (`flaky` — повтор
1083
+ * прошёл, `confirmed` — провал подтвердился и засчитывается как прежде).
1084
+ */
1085
+ async integrationGate(attempt, cwd, sha, gate, artifacts, signal, execution, budget) {
1086
+ try {
1087
+ await this.gate(attempt, cwd, sha, 'integration', gate, artifacts, signal, execution);
1088
+ }
1089
+ catch (error) {
1090
+ if (!budget.recheck || signal.aborted || !(error instanceof TaskFailure))
1091
+ throw error;
1092
+ if (error.kind !== 'gate')
1093
+ throw error;
1094
+ const { failed, candidatePassed, spent } = this.engine.read((v) => {
1095
+ const evidence = v.attempt(attempt.id)?.evidence ?? [];
1096
+ const own = (e, phase, at) => e.kind === 'test' &&
1097
+ e.gate === gate.id &&
1098
+ e.phase === phase &&
1099
+ e.sha === at &&
1100
+ !e.consumer;
1101
+ return {
1102
+ failed: evidence.findLast((e) => own(e, 'integration', sha)),
1103
+ candidatePassed: evidence.findLast((e) => own(e, 'candidate', attempt.candidateSha))?.passed === true,
1104
+ // Один повтор на кандидата: переиспользованный следующей попыткой
1105
+ // кандидат второго не получает.
1106
+ spent: v
1107
+ .attempts(attempt.workId)
1108
+ .some((x) => x.candidateSha === attempt.candidateSha && x.evidence.some((e) => e.recheck)),
1109
+ };
1110
+ });
1111
+ // Контрпример свойства или провал случая корпуса не повторяется: удачный
1112
+ // второй запуск недетерминированной проверки не отменяет найденного входа.
1113
+ if (!failed || failed.passed || namesFailingCases(failed) || !candidatePassed || spent)
1114
+ throw error;
1115
+ budget.recheck = false;
1116
+ await this.gate(attempt, cwd, sha, 'integration', gate, artifacts, signal, execution, undefined, failed.id);
1117
+ }
1118
+ }
1119
+ async runOneGate(attempt, cwd, sha, phase, gate, artifacts, signal, execution, consumer, recheck) {
1059
1120
  // Генеративный gate — всегда; gate эталонных наборов — когда манифест
1060
1121
  // поручения ждёт от него отчёта (без договора — прежний уровень).
1061
1122
  const run = this.propertyRun(attempt, gate, consumer);
@@ -1067,9 +1128,14 @@ export class Runner {
1067
1128
  sha,
1068
1129
  phase,
1069
1130
  gate,
1131
+ // Лог и отчёт повтора — в своём каталоге: первая запись ссылается на
1132
+ // свой лог по digest, и повтор его не перезаписывает.
1070
1133
  artifactDir: consumer
1071
1134
  ? join(artifacts, phase, 'consumer', consumer.repositoryId)
1072
- : join(artifacts, phase),
1135
+ : recheck
1136
+ ? join(artifacts, phase, 'recheck')
1137
+ : join(artifacts, phase),
1138
+ ...(recheck ? { recheck } : {}),
1073
1139
  signal,
1074
1140
  execution,
1075
1141
  boundary: this.boundary(consumer?.dependencies ?? attempt.dependencies),
@@ -1893,8 +1959,9 @@ export class Runner {
1893
1959
  const execution = this.environment(attempt, 'integration', cwd);
1894
1960
  await withEnvironment(repo.lifecycle ?? this.policy.lifecycle, cwd, join(artifacts, 'integration', 'environment'), execution, signal, async () => {
1895
1961
  await runSteps(repo.prepare, cwd, join(artifacts, 'integration', 'prepare'), execution, signal);
1962
+ const budget = { recheck: true };
1896
1963
  for (const gate of gates)
1897
- await this.gate(attempt, cwd, sha, 'integration', gate, artifacts, signal, execution);
1964
+ await this.integrationGate(attempt, cwd, sha, gate, artifacts, signal, execution, budget);
1898
1965
  await this.consumers(attempt, cwd, sha, artifacts, signal);
1899
1966
  this.requirements(attempt, work, repoPath, cwd, sha, 'integration');
1900
1967
  rearm();
@@ -1920,7 +1987,11 @@ export class Runner {
1920
1987
  assertRequirements(work.order, repoPath);
1921
1988
  // Внутри транзакции: без hooks репозитория (они исполнили бы чужой код
1922
1989
  // под блокировкой записи) и с конечным пределом, короче lease.
1923
- execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'update-ref', repo.targetRef, sha, base], { cwd: repoPath, stdio: 'pipe', timeout: Runner.refTimeoutMs });
1990
+ execFileSync('git', hostGitArgs(repoPath, ['update-ref', repo.targetRef, sha, base]), {
1991
+ cwd: repoPath,
1992
+ stdio: 'pipe',
1993
+ timeout: Runner.refTimeoutMs,
1994
+ });
1924
1995
  });
1925
1996
  }
1926
1997
  catch (error) {
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Git на хосте над деревом, в котором исполнялся чужой код.
3
+ *
4
+ * Исполнитель и проверки пишут в checkout. Git, запущенный потом на хосте,
5
+ * читает конфигурацию того репозитория, который найдёт от рабочего каталога,
6
+ * а она способна запускать программы (`core.fsmonitor`, hooks, драйверы
7
+ * фильтров и diff). Подменённый файл `.git` (`gitdir: <checkout>/evil`),
8
+ * `.git/commondir` в обычном checkout или вложенный `.git` уводили git в
9
+ * конфигурацию, которую написал чужой код, — и она исполнялась вне песочницы.
10
+ *
11
+ * Поэтому каждый вызов git хоста сначала сверяет, куда git придёт: файл
12
+ * `.git` рабочего дерева, созданного через `worktree add`, должен остаться
13
+ * тем же; gitdir и общий каталог репозитория лежат вне дерева и согласованы
14
+ * между собой; общий каталог — уже известный хосту репозиторий, если он
15
+ * известен; вложенный репозиторий внутри известного дерева и перенаправление
16
+ * обычного `.git` — отказ. Флаги `gitHardening` поверх этого снимают
17
+ * исполняемые настройки, которые git читает сам.
18
+ */
19
+ export declare const gitHardening: string[];
20
+ export declare class UntrustedCheckoutError extends Error {
21
+ name: string;
22
+ }
23
+ /**
24
+ * Сверяет репозиторий, который git найдёт от `cwd`. Возвращает его общий
25
+ * каталог или `undefined`, если репозитория нет (git откажет сам).
26
+ */
27
+ export declare function assertTrustedCheckout(cwd: string): string | undefined;
28
+ /** Рабочее дерево создано хостом: дальше его `.git` обязан остаться прежним. */
29
+ export declare function rememberWorktree(path: string): void;
30
+ /** Ключ дерева — настоящий путь (/var → /private/var). */
31
+ export declare const worktreeKey: (path: string) => string;
32
+ export declare function forgetWorktree(key: string): void;
33
+ /** Путь, который `git worktree add` получит как каталог дерева. */
34
+ export declare function worktreeAddPath(args: string[]): string | undefined;
35
+ /** Только для тестов: забыть, что известно процессу. */
36
+ export declare function resetGitTrust(): void;
@@ -0,0 +1,174 @@
1
+ import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
2
+ import { basename, dirname, join, resolve, sep } from 'node:path';
3
+ /**
4
+ * Git на хосте над деревом, в котором исполнялся чужой код.
5
+ *
6
+ * Исполнитель и проверки пишут в checkout. Git, запущенный потом на хосте,
7
+ * читает конфигурацию того репозитория, который найдёт от рабочего каталога,
8
+ * а она способна запускать программы (`core.fsmonitor`, hooks, драйверы
9
+ * фильтров и diff). Подменённый файл `.git` (`gitdir: <checkout>/evil`),
10
+ * `.git/commondir` в обычном checkout или вложенный `.git` уводили git в
11
+ * конфигурацию, которую написал чужой код, — и она исполнялась вне песочницы.
12
+ *
13
+ * Поэтому каждый вызов git хоста сначала сверяет, куда git придёт: файл
14
+ * `.git` рабочего дерева, созданного через `worktree add`, должен остаться
15
+ * тем же; gitdir и общий каталог репозитория лежат вне дерева и согласованы
16
+ * между собой; общий каталог — уже известный хосту репозиторий, если он
17
+ * известен; вложенный репозиторий внутри известного дерева и перенаправление
18
+ * обычного `.git` — отказ. Флаги `gitHardening` поверх этого снимают
19
+ * исполняемые настройки, которые git читает сам.
20
+ */
21
+ export const gitHardening = [
22
+ '-c',
23
+ 'core.fsmonitor=false',
24
+ '-c',
25
+ 'core.hooksPath=/dev/null',
26
+ '-c',
27
+ 'protocol.ext.allow=never',
28
+ ];
29
+ export class UntrustedCheckoutError extends Error {
30
+ name = 'UntrustedCheckoutError';
31
+ }
32
+ /** Общие каталоги репозиториев, которые хост открывал сам. */
33
+ const trustedCommon = new Set();
34
+ /** Рабочие деревья, созданные через `worktree add`: путь → содержимое `.git`. */
35
+ const knownWorktrees = new Map();
36
+ const real = (path) => {
37
+ try {
38
+ return realpathSync(path);
39
+ }
40
+ catch {
41
+ return resolve(path);
42
+ }
43
+ };
44
+ const within = (path, root) => path === root || path.startsWith(root + sep);
45
+ const isFile = (path) => {
46
+ try {
47
+ return statSync(path).isFile();
48
+ }
49
+ catch {
50
+ return false;
51
+ }
52
+ };
53
+ const isDir = (path) => {
54
+ try {
55
+ return statSync(path).isDirectory();
56
+ }
57
+ catch {
58
+ return false;
59
+ }
60
+ };
61
+ /** Признак каталога-репозитория без рабочего дерева: git находит такой и сам. */
62
+ const bareLike = (dir) => isFile(join(dir, 'HEAD')) && isDir(join(dir, 'objects')) && isDir(join(dir, 'refs'));
63
+ const insideKnown = (dir) => [...knownWorktrees.keys()].find((w) => dir !== w && within(dir, w));
64
+ const refuse = (reason) => {
65
+ throw new UntrustedCheckoutError('Git на хосте не запущен: ' + reason);
66
+ };
67
+ function readGitFile(path) {
68
+ const m = /^gitdir: (.+)$/m.exec(readFileSync(path, 'utf8'));
69
+ if (!m)
70
+ refuse(`${path} не указывает gitdir`);
71
+ return m[1].trim();
72
+ }
73
+ /**
74
+ * Сверяет репозиторий, который git найдёт от `cwd`. Возвращает его общий
75
+ * каталог или `undefined`, если репозитория нет (git откажет сам).
76
+ */
77
+ export function assertTrustedCheckout(cwd) {
78
+ for (let dir = real(cwd);; dir = dirname(dir)) {
79
+ const dotgit = join(dir, '.git');
80
+ let stat;
81
+ try {
82
+ stat = lstatSync(dotgit);
83
+ }
84
+ catch {
85
+ /* нет `.git` на этом уровне */
86
+ }
87
+ const nested = insideKnown(dir);
88
+ if (stat) {
89
+ if (nested)
90
+ refuse(`вложенный репозиторий ${dotgit} внутри рабочего дерева ${nested}`);
91
+ if (stat.isSymbolicLink())
92
+ refuse(`${dotgit} — символическая ссылка`);
93
+ const known = knownWorktrees.get(dir);
94
+ if (stat.isDirectory()) {
95
+ if (known !== undefined)
96
+ refuse(`${dotgit} рабочего дерева заменён каталогом`);
97
+ // Обычный `.git` с перенаправлением ведёт git в чужой общий каталог.
98
+ for (const name of ['commondir', 'gitdir'])
99
+ if (existsSync(join(dotgit, name)))
100
+ refuse(`${join(dotgit, name)} перенаправляет git`);
101
+ const common = real(dotgit);
102
+ trustedCommon.add(common);
103
+ return common;
104
+ }
105
+ const content = readFileSync(dotgit, 'utf8');
106
+ if (known !== undefined && content !== known)
107
+ refuse(`${dotgit} рабочего дерева изменён после создания`);
108
+ const gitdir = real(resolve(dir, readGitFile(dotgit)));
109
+ if (within(gitdir, dir))
110
+ refuse(`${dotgit} указывает внутрь самого дерева: ${gitdir}`);
111
+ const commondirFile = join(gitdir, 'commondir');
112
+ if (!isFile(commondirFile))
113
+ refuse(`${gitdir} не рабочее дерево репозитория`);
114
+ const common = real(resolve(gitdir, readFileSync(commondirFile, 'utf8').trim()));
115
+ if (within(common, dir))
116
+ refuse(`общий каталог ${common} внутри самого дерева`);
117
+ if (join(common, 'worktrees', basename(gitdir)) !== gitdir || !bareLike(common))
118
+ refuse(`${gitdir} не принадлежит репозиторию ${common}`);
119
+ const back = join(gitdir, 'gitdir');
120
+ if (!isFile(back) || real(readFileSync(back, 'utf8').trim()) !== real(dotgit))
121
+ refuse(`${gitdir} не ссылается обратно на ${dotgit}`);
122
+ // Дерево, созданное этим процессом, ведёт только в известный репозиторий.
123
+ if (known !== undefined && !trustedCommon.has(common))
124
+ refuse(`общий каталог ${common} не тот, от которого создано дерево`);
125
+ return common;
126
+ }
127
+ if (bareLike(dir)) {
128
+ if (nested)
129
+ refuse(`вложенный репозиторий ${dir} внутри рабочего дерева ${nested}`);
130
+ const common = real(dir);
131
+ trustedCommon.add(common);
132
+ return common;
133
+ }
134
+ if (dirname(dir) === dir)
135
+ return undefined;
136
+ }
137
+ }
138
+ /** Рабочее дерево создано хостом: дальше его `.git` обязан остаться прежним. */
139
+ export function rememberWorktree(path) {
140
+ const dir = real(path);
141
+ try {
142
+ knownWorktrees.set(dir, readFileSync(join(dir, '.git'), 'utf8'));
143
+ }
144
+ catch {
145
+ /* `worktree add` не создал дерево: git уже сообщил об отказе */
146
+ }
147
+ }
148
+ /** Ключ дерева — настоящий путь (/var → /private/var). */
149
+ export const worktreeKey = real;
150
+ export function forgetWorktree(key) {
151
+ knownWorktrees.delete(key);
152
+ }
153
+ /** Путь, который `git worktree add` получит как каталог дерева. */
154
+ export function worktreeAddPath(args) {
155
+ const at = args.findIndex((a, i) => a === 'worktree' && args[i + 1] === 'add');
156
+ if (at < 0)
157
+ return undefined;
158
+ const withValue = new Set(['-b', '-B', '--reason']);
159
+ for (let i = at + 2; i < args.length; i++) {
160
+ const arg = args[i];
161
+ if (arg === '--')
162
+ return args[i + 1];
163
+ if (withValue.has(arg))
164
+ i++;
165
+ else if (!arg.startsWith('-'))
166
+ return arg;
167
+ }
168
+ return undefined;
169
+ }
170
+ /** Только для тестов: забыть, что известно процессу. */
171
+ export function resetGitTrust() {
172
+ trustedCommon.clear();
173
+ knownWorktrees.clear();
174
+ }
@@ -89,6 +89,94 @@ export declare function isolationSupport(): {
89
89
  ok: boolean;
90
90
  detail: string;
91
91
  };
92
+ /**
93
+ * Обязательные запреты записи sandbox-runtime для корней проверки — без
94
+ * каталогов IDE внутри дерева зависимостей.
95
+ *
96
+ * srt всегда запрещает запись в конфигурацию shell, git, IDE и Claude
97
+ * (README «Mandatory Deny Paths»), и отключить это можно только вместе со
98
+ * всей файловой политикой. На macOS запрет `.idea`/`.vscode` действует на
99
+ * любой глубине под текущим каталогом процесса srt, в том числе внутри
100
+ * `node_modules`; на Linux тот же запрет `node_modules` пропускает. Пакеты
101
+ * публикуют `.idea/` (так поставляются и распространённые транзитивные
102
+ * зависимости), и установка зависимостей в чистом worktree падала с EPERM
103
+ * при любом коде.
104
+ *
105
+ * Запрет защищает от конфигурации, которую песочница подложит, а человек
106
+ * потом откроет в IDE или git исполнит на хосте. Дерево зависимостей IDE как
107
+ * конфигурацию проекта не открывает, поэтому на macOS srt запускается из
108
+ * собственного каталога проверки, а запреты для корней задаются здесь явно:
109
+ *
110
+ * - конфигурация shell и git, `.mcp.json`, `.claude/commands|agents`,
111
+ * `.git/hooks`, `.git/config` — в корне и на любой глубине, как у srt;
112
+ * - `.idea` и `.vscode` — в корне и в каждом подкаталоге существующих
113
+ * каталогов до глубины `ideDepth`, кроме `node_modules`. Глоб srt не умеет
114
+ * «кроме node_modules», поэтому дерево перечисляется: новый каталог глубже
115
+ * существующего уровня не закрыт (у srt на Linux закрыты только уже
116
+ * существующие файлы до глубины 3).
117
+ *
118
+ * Путь с символами глоба нельзя записать шаблоном без риска не совпасть ни
119
+ * с чем; тогда возвращается `undefined`, и srt остаётся в прежнем каталоге с
120
+ * полным собственным запретом.
121
+ */
122
+ export declare const ideDirectories: string[];
123
+ /**
124
+ * Отказ собрать политику песочницы: проверка не запускается, а не идёт с
125
+ * молча урезанными запретами.
126
+ */
127
+ export declare class SandboxPolicyError extends Error {
128
+ name: string;
129
+ }
130
+ export declare function protectedWriteDenies(roots: string[]): string[] | undefined;
131
+ /**
132
+ * Явные запреты для Linux. srt там закрывает только уже существующие пути и
133
+ * сам пропускает `node_modules`; файл `.git` рабочего дерева добавляется.
134
+ */
135
+ export declare function linuxWriteDenies(roots: string[]): string[];
136
+ /**
137
+ * Обязательный запрет записи, под который попадает `path` внутри открытых
138
+ * проверке каталогов. `undefined` — путь вне таких запретов: отказ в нём —
139
+ * не следствие обязательной политики песочницы.
140
+ */
141
+ export declare function mandatoryDenyRule(policy: Isolation, path: string): string | undefined;
142
+ export interface SandboxViolation {
143
+ operation: string;
144
+ path: string;
145
+ }
146
+ /**
147
+ * Отказы песочницы из журнала ядра macOS для одной проверки.
148
+ *
149
+ * srt помечает каждое правило запрета тегом с началом команды (base64) и
150
+ * суффиксом сессии `_SBX`; команда проверки начинается с уникального
151
+ * токена, и записи чужих песочниц на той же машине сюда не попадают. Текст
152
+ * вывода проверки свидетельством не служит: его печатает сама проверка.
153
+ */
154
+ export declare function parseSandboxLog(text: string, tag: string): SandboxViolation[];
155
+ /** Наблюдение за журналом песочницы на время проверки; без `log` — `undefined`. */
156
+ export declare function watchSandboxLog(tag: string): Promise<{
157
+ /** Ждёт `drainMs`, пока ядро допишет записи, и возвращает отказы проверки. */
158
+ stop(drainMs: number): Promise<SandboxViolation[]>;
159
+ } | undefined>;
160
+ /**
161
+ * Отказы обязательной политики в открытых проверке каталогах, которые
162
+ * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
163
+ * а не среды: её здесь нет.
164
+ */
165
+ export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation): {
166
+ path: string;
167
+ rule: string;
168
+ }[];
169
+ /**
170
+ * Защищённые элементы checkout вне `node_modules`: путь → подпись.
171
+ *
172
+ * Запреты песочницы проверяют только путь операции. Каталог, собранный
173
+ * внутри `node_modules` (там каталоги IDE открыты) и затем перенесённый в
174
+ * дерево проекта, или новый каталог глубже перечисленных уровней ими не
175
+ * закрыты; сверка снимков до и после проверки находит такой результат.
176
+ */
177
+ export declare function protectedSnapshot(root: string): Map<string, string>;
178
+ /** Защищённые пути, которые появились или изменились после снимка `before`. */
179
+ export declare function protectedChanges(before: Map<string, string>, root: string): string[];
92
180
  /**
93
181
  * Команда проверки внутри sandbox-runtime.
94
182
  *
@@ -96,15 +184,29 @@ export declare function isolationSupport(): {
96
184
  * не откатывается к умолчаниям. Собственный служебный сокет srt кладёт во
97
185
  * временный каталог процесса, поэтому srt получает короткий системный
98
186
  * TMPDIR, а команде внутри передаётся свой scratch.
187
+ *
188
+ * `cwd` — каталог, из которого запускается srt (см. `protectedWriteDenies`):
189
+ * на macOS это каталог метки старта, а в рабочий каталог проверки обёртка
190
+ * переходит сама перед exec.
99
191
  */
100
192
  export declare function isolatedCommand(policy: Isolation, argv: string[], settingsDir: string, scratch: string,
101
193
  /**
102
194
  * Файл, который обёртка создаёт внутри песочницы перед exec команды. Его
103
195
  * отсутствие — единственный достоверный признак, что команда не начиналась.
104
196
  */
105
- started: string): Promise<{
197
+ started: string,
198
+ /** Рабочий каталог команды. */
199
+ workdir: string,
200
+ /** Корни, которым нужны обязательные запреты записи (checkout проверки). */
201
+ protect?: string[], platform?: NodeJS.Platform,
202
+ /**
203
+ * Токен в начале команды: srt кладёт начало команды в тег записей журнала
204
+ * ядра, и по нему отказы этой проверки отличаются от чужих (`parseSandboxLog`).
205
+ */
206
+ tag?: string): Promise<{
106
207
  argv: string[];
107
208
  env: {
108
209
  TMPDIR: string;
109
210
  };
211
+ cwd: string;
110
212
  }>;