devcontour-harness 0.1.0-alpha.22 → 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 (40) hide show
  1. package/README.md +13 -2
  2. package/docs/compatibility.md +11 -11
  3. package/docs/contracts.md +17 -2
  4. package/docs/quickstart.md +1 -1
  5. package/docs/release-notes/0.1.0-alpha.23.md +122 -0
  6. package/docs/toolchains.md +2 -1
  7. package/docs/upgrade.md +17 -17
  8. package/lib/agents/cli-adapter.js +1 -0
  9. package/lib/agents/review-probe.d.ts +1 -0
  10. package/lib/agents/review-probe.js +4 -0
  11. package/lib/cli.js +1 -1
  12. package/lib/contracts/cli.d.ts +20 -0
  13. package/lib/contracts/cli.js +11 -0
  14. package/lib/contracts/ports.d.ts +6 -0
  15. package/lib/control/base-move.d.ts +2 -0
  16. package/lib/control/base-move.js +13 -2
  17. package/lib/control/doctor.d.ts +10 -0
  18. package/lib/control/doctor.js +19 -3
  19. package/lib/control/harness.d.ts +6 -0
  20. package/lib/control/harness.js +2 -0
  21. package/lib/engine/joint-runner.d.ts +5 -0
  22. package/lib/engine/joint-runner.js +28 -5
  23. package/lib/engine/runner.d.ts +18 -0
  24. package/lib/engine/runner.js +48 -7
  25. package/lib/environment/checkout-root.d.ts +78 -0
  26. package/lib/environment/checkout-root.js +133 -0
  27. package/lib/environment/git-trust.js +4 -0
  28. package/lib/environment/isolation.d.ts +29 -4
  29. package/lib/environment/isolation.js +42 -8
  30. package/lib/index.d.ts +5 -0
  31. package/lib/index.js +5 -0
  32. package/lib/verification/confirm.d.ts +7 -4
  33. package/lib/verification/confirm.js +4 -2
  34. package/lib/verification/gates-at.d.ts +9 -5
  35. package/lib/verification/gates-at.js +30 -5
  36. package/lib/verification/gates.d.ts +13 -4
  37. package/lib/verification/gates.js +3 -1
  38. package/lib/verification/spike.d.ts +7 -4
  39. package/lib/verification/spike.js +4 -2
  40. package/package.json +1 -1
@@ -29,6 +29,12 @@ export interface HarnessOptions {
29
29
  policySource?: PolicySource;
30
30
  /** База блокировок ресурсов; по умолчанию — общая для машины. */
31
31
  resourceDatabase?: string;
32
+ /**
33
+ * Корень рабочих деревьев попыток и совместных проверок; без него —
34
+ * `chooseCheckoutRoot` (кэш пользователя, если каталог состояния внутри
35
+ * репозитория, иначе каталог состояния).
36
+ */
37
+ checkoutRoot?: string;
32
38
  /**
33
39
  * Дополнения хоста к попыткам (например, история работы внешнего
34
40
  * хранилища задач до исполнения). Приёмку не решают: отказ хука — отказ
@@ -71,6 +71,7 @@ export class Harness {
71
71
  ...(options.environment ? { environment: options.environment } : {}),
72
72
  ...(options.resourceDatabase ? { resourceDatabase: options.resourceDatabase } : {}),
73
73
  ...(options.hooks ? { hooks: options.hooks } : {}),
74
+ ...(options.checkoutRoot ? { checkoutRoot: options.checkoutRoot } : {}),
74
75
  });
75
76
  this.joint = new JointRunner({
76
77
  engine: this.engine,
@@ -78,6 +79,7 @@ export class Harness {
78
79
  baseDir: options.baseDir,
79
80
  ...(options.environment ? { environment: options.environment } : {}),
80
81
  ...(options.resourceDatabase ? { resourceDatabase: options.resourceDatabase } : {}),
82
+ ...(options.checkoutRoot ? { checkoutRoot: options.checkoutRoot } : {}),
81
83
  });
82
84
  }
83
85
  close() {
@@ -7,6 +7,11 @@ export interface JointRunnerOptions {
7
7
  baseDir: string;
8
8
  environment?: NodeJS.ProcessEnv;
9
9
  resourceDatabase?: string;
10
+ /**
11
+ * Корень снимков компонентов (`<checkoutRoot>/.joint/<id>/components`: ID репозитория с точки не начинается); без
12
+ * него — `chooseCheckoutRoot` по каталогу состояния и каталогу проверки.
13
+ */
14
+ checkoutRoot?: string;
10
15
  /** Каталог проверки (по умолчанию `<stateDir>/joint/<id>`). */
11
16
  directory?: (verification: JointVerificationState) => string;
12
17
  /** Дополнительные переменные окружения gates этой проверки (у хоста — его идентификаторы). */
@@ -1,8 +1,10 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
3
- import { isAbsolute, join, resolve, sep } from 'node:path';
3
+ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
4
4
  import { digestOf, } from "../contracts/index.js";
5
5
  import { git } from "../environment/process.js";
6
+ import { chooseCheckoutRoot } from "../environment/checkout-root.js";
7
+ import { credentialPaths } from "../environment/isolation.js";
6
8
  import { CleanupFailure, availableRedactor, executionEnvironment, withEnvironment, } from "../environment/lifecycle.js";
7
9
  import { composeRedactors } from "../environment/redaction.js";
8
10
  import { defaultResourceDatabase, withResources } from "../environment/resources.js";
@@ -55,6 +57,17 @@ export class JointRunner {
55
57
  }
56
58
  }, Math.max(1000, this.policy.leaseMs / 3));
57
59
  const dir = this.options.directory?.(v) ?? join(this.options.stateDir, 'joint', v.id);
60
+ // Снимки компонентов — вне дерева, если каталог проверки лежит внутри
61
+ // репозитория: gate, ищущий конфигурацию вверх, не упирается в закрытый checkout.
62
+ const placement = chooseCheckoutRoot({
63
+ stateDirs: [this.options.stateDir, dir],
64
+ repositories: this.policy.repositories.map((r) => this.repoPath(r)),
65
+ hidden: credentialPaths(),
66
+ ...(this.options.checkoutRoot ? { configured: this.options.checkoutRoot } : {}),
67
+ });
68
+ const components = placement.root
69
+ ? join(placement.root, '.joint', v.id, 'components')
70
+ : join(dir, 'components');
58
71
  const worktrees = [];
59
72
  const source = this.options.environment ?? process.env;
60
73
  // Незавершённая очистка окружения оставляет снимки: их разбирает cleanup.
@@ -66,7 +79,10 @@ export class JointRunner {
66
79
  resourceDatabase: this.options.resourceDatabase ?? defaultResourceDatabase(),
67
80
  }, [...new Set(this.policy.workspaceGates.flatMap((g) => g.resources ?? []))], `${this.options.stateDir}:${v.id}`, signal, async (signal, resources) => {
68
81
  await this.options.prepare?.(signal);
69
- await mkdir(join(dir, 'components'), { recursive: true });
82
+ // Каталог проверки (impact, manifest, логи) — и тогда, когда
83
+ // компоненты лежат под корнем вне дерева.
84
+ await mkdir(dir, { recursive: true });
85
+ await mkdir(components, { recursive: true });
70
86
  const works = this.engine.read((view) => v.workIds.map((id) => view.work(id)));
71
87
  const manifest = {};
72
88
  const paths = {};
@@ -78,7 +94,7 @@ export class JointRunner {
78
94
  await git(path, 'merge-base', '--is-ancestor', w.resultSha, sha).catch(() => {
79
95
  throw new Error(`Результат ${w.id} отсутствует в ${repo.targetRef} ${repo.id}`);
80
96
  });
81
- const cwd = join(dir, 'components', repo.id);
97
+ const cwd = join(components, repo.id);
82
98
  await git(path, 'worktree', 'add', '--detach', cwd, sha);
83
99
  worktrees.push({ repo: path, cwd });
84
100
  manifest[repo.id] = { sha, tree: await git(cwd, 'rev-parse', 'HEAD^{tree}') };
@@ -163,6 +179,7 @@ export class JointRunner {
163
179
  this.options.stateDir,
164
180
  ...this.policy.repositories.map((r) => this.repoPath(r)),
165
181
  ],
182
+ ...(placement.root ? { checkouts: [placement.root] } : {}),
166
183
  settingsDir: join(dir, gate.id),
167
184
  env: {
168
185
  ...environment.env,
@@ -246,8 +263,14 @@ export class JointRunner {
246
263
  if (!preserve) {
247
264
  for (const w of worktrees)
248
265
  await git(w.repo, 'worktree', 'remove', '--force', w.cwd).catch(() => undefined);
249
- if (dir.startsWith(this.options.stateDir + sep))
250
- await rm(join(dir, 'components'), { recursive: true, force: true }).catch(() => undefined);
266
+ // Убирается только каталог, созданный здесь: в каталоге состояния или
267
+ // под корнем вне дерева.
268
+ const owned = placement.root ?? this.options.stateDir;
269
+ if (components.startsWith(owned + sep))
270
+ await rm(placement.root ? dirname(components) : components, {
271
+ recursive: true,
272
+ force: true,
273
+ }).catch(() => undefined);
251
274
  }
252
275
  }
253
276
  }
@@ -1,4 +1,5 @@
1
1
  import { type ImplementationResult, type AttemptState, type ContextSnapshot, type ExecutionPolicy, type RuntimeAdapter, type RuntimeName, type WorkState } from '../contracts/index.ts';
2
+ import { type CheckoutRoot } from '../environment/checkout-root.ts';
2
3
  import { type FailureKind } from './failure.ts';
3
4
  import { type Engine } from './engine.ts';
4
5
  import { CorpusStore } from '../verification/corpus.ts';
@@ -13,6 +14,15 @@ export interface RunnerOptions {
13
14
  * туда и его попытки.
14
15
  */
15
16
  stateDirFor?: (repositoryId: string) => string;
17
+ /**
18
+ * Корень рабочих деревьев, снимков зависимостей и проверок потребителей
19
+ * (`<checkoutRoot>/<repositoryId>/worktrees/<attempt>`…). Без него —
20
+ * `chooseCheckoutRoot`: каталог кэша пользователя, если каталог состояния
21
+ * лежит внутри репозитория, иначе прежнее место в каталоге состояния.
22
+ * Лучше на том же томе, что репозитории: менеджеры пакетов ставят
23
+ * зависимости жёсткими ссылками и reflink.
24
+ */
25
+ checkoutRoot?: string;
16
26
  /** Каталог, от которого разрешаются относительные пути репозиториев политики. */
17
27
  baseDir: string;
18
28
  adapters: Partial<Record<RuntimeName, RuntimeAdapter>>;
@@ -90,6 +100,14 @@ export declare class Runner {
90
100
  constructor(options: RunnerOptions);
91
101
  /** Каталог попыток репозитория. */
92
102
  private dirOf;
103
+ private placement?;
104
+ /**
105
+ * Действующий корень рабочих деревьев (`checkout-root.ts`): хост
106
+ * показывает его в диагностике. Выбирается один раз на исполнитель.
107
+ */
108
+ checkoutRoot(): CheckoutRoot;
109
+ /** Каталог рабочего дерева вида `kind`: вне дерева или прежний в каталоге попыток. */
110
+ private checkout;
93
111
  repoPath(repo: Repo): string;
94
112
  private repo;
95
113
  /**
@@ -2,11 +2,13 @@ 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, relative, resolve } from 'node:path';
5
+ import { dirname, 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
7
  import { git, hostGitArgs } from "../environment/process.js";
8
8
  import { protectedChanges, protectedSnapshot, SandboxPolicyError, } from "../environment/isolation.js";
9
9
  import { executionEnvironment, runSteps, withEnvironment } from "../environment/lifecycle.js";
10
+ import { checkoutPath, chooseCheckoutRoot, realish, } from "../environment/checkout-root.js";
11
+ import { credentialPaths } from "../environment/isolation.js";
10
12
  import { redactDeep } from "../environment/redaction.js";
11
13
  import { alreadySatisfiedReviewOutputSchema, implementationOutputSchema, reviewOutputSchema, } from "../agents/schemas.js";
12
14
  import { reviewInspection } from "../agents/inspect.js";
@@ -75,6 +77,23 @@ export class Runner {
75
77
  dirOf(repositoryId) {
76
78
  return this.options.stateDirFor?.(repositoryId) ?? this.options.stateDir;
77
79
  }
80
+ placement;
81
+ /**
82
+ * Действующий корень рабочих деревьев (`checkout-root.ts`): хост
83
+ * показывает его в диагностике. Выбирается один раз на исполнитель.
84
+ */
85
+ checkoutRoot() {
86
+ return (this.placement ??= chooseCheckoutRoot({
87
+ stateDirs: [this.options.stateDir, ...this.policy.repositories.map((r) => this.dirOf(r.id))],
88
+ repositories: this.policy.repositories.map((r) => this.repoPath(r)),
89
+ hidden: credentialPaths(),
90
+ ...(this.options.checkoutRoot ? { configured: this.options.checkoutRoot } : {}),
91
+ }));
92
+ }
93
+ /** Каталог рабочего дерева вида `kind`: вне дерева или прежний в каталоге попыток. */
94
+ checkout(repositoryId, kind, ...rest) {
95
+ return checkoutPath(this.checkoutRoot(), join(this.dirOf(repositoryId), kind, ...rest), repositoryId, kind, ...rest);
96
+ }
78
97
  repoPath(repo) {
79
98
  return isAbsolute(repo.path) ? repo.path : resolve(this.options.baseDir, repo.path);
80
99
  }
@@ -90,7 +109,11 @@ export class Runner {
90
109
  */
91
110
  boundary(dependencies = []) {
92
111
  const repos = this.policy.repositories.map((r) => this.repoPath(r));
112
+ const root = this.checkoutRoot().root;
93
113
  return {
114
+ // Корень вне дерева закрыт целиком, как каталог состояния: свои
115
+ // деревья открыты более конкретным разрешением.
116
+ checkouts: root ? [root] : [],
94
117
  hidden: [
95
118
  ...new Set([
96
119
  this.options.stateDir,
@@ -374,6 +397,7 @@ export class Runner {
374
397
  mode: this.policy.isolation.mode,
375
398
  writable: review ? [] : [input.cwd],
376
399
  denied: boundary.hidden,
400
+ ...(boundary.checkouts.length ? { checkouts: boundary.checkouts } : {}),
377
401
  readable: [
378
402
  input.cwd,
379
403
  ...boundary.readable,
@@ -668,7 +692,7 @@ export class Runner {
668
692
  controller.abort();
669
693
  }
670
694
  }, Math.max(1000, this.policy.leaseMs / 3));
671
- const cwd = join(this.dirOf(repo.id), 'worktrees', attempt.id);
695
+ const cwd = this.checkout(repo.id, 'worktrees', attempt.id);
672
696
  const integrationCwd = cwd + '-integration';
673
697
  const artifacts = join(this.dirOf(repo.id), 'artifacts', attempt.id);
674
698
  const worktrees = [];
@@ -720,7 +744,7 @@ export class Runner {
720
744
  const dependencies = await snapshotDependencies({
721
745
  repos: this.repositories(),
722
746
  repositoryId: repo.id,
723
- dir: join(this.dirOf(repo.id), 'dependencies', attempt.id),
747
+ dir: this.checkout(repo.id, 'dependencies', attempt.id),
724
748
  artifacts,
725
749
  runId: attempt.id,
726
750
  policy: this.policy,
@@ -743,7 +767,7 @@ export class Runner {
743
767
  // берётся ли кандидат предыдущей попытки вместо нового кода.
744
768
  const reuse = this.engine.implementationBasis(attempt.id, attempt.token, implementationBasis(work, attempt, base, this.engine.version));
745
769
  attempt = { ...attempt, ...(reuse.reusedFrom ? { reusedFrom: reuse.reusedFrom } : {}) };
746
- await mkdir(join(this.dirOf(repo.id), 'worktrees'), { recursive: true });
770
+ await mkdir(dirname(cwd), { recursive: true });
747
771
  await git(repoPath, 'worktree', 'add', '-b', `${this.options.branchPrefix ?? 'harness/run-'}${attempt.id}`, cwd, reuse.reusedFrom?.candidateSha ?? base);
748
772
  worktrees.push(cwd);
749
773
  this.engine.phase(attempt.id, attempt.token, 'running', { baseSha: base, worktree: cwd });
@@ -1060,10 +1084,14 @@ export class Runner {
1060
1084
  ],
1061
1085
  snapshots: [],
1062
1086
  };
1087
+ // Окружения прежних попыток лежат в каталоге состояния, новых — под
1088
+ // корнем рабочих деревьев вне дерева.
1089
+ const outside = this.checkoutRoot().root;
1063
1090
  const roots = [
1064
1091
  ...new Set([
1065
1092
  await realpath(this.options.stateDir),
1066
1093
  await realpath(this.dirOf(attempt.repositoryId)),
1094
+ ...(outside ? [realish(outside)] : []),
1067
1095
  ]),
1068
1096
  ];
1069
1097
  const cleaned = [];
@@ -1206,9 +1234,9 @@ export class Runner {
1206
1234
  const repo = this.repo(consumer.repositoryId);
1207
1235
  const checkout = this.repoPath(repo);
1208
1236
  const id = `${attempt.id}-consumer-${repo.id}-${randomUUID().slice(0, 8)}`;
1209
- const dir = join(this.dirOf(repo.id), 'consumers', id);
1237
+ const dir = this.checkout(repo.id, 'consumers', id);
1210
1238
  const own = join(artifacts, 'integration', 'consumer', repo.id);
1211
- await mkdir(join(this.dirOf(repo.id), 'consumers'), { recursive: true });
1239
+ await mkdir(dirname(dir), { recursive: true });
1212
1240
  await git(checkout, 'worktree', 'add', '--detach', dir, repo.targetRef);
1213
1241
  let dependencies = [];
1214
1242
  let failure;
@@ -1225,7 +1253,7 @@ export class Runner {
1225
1253
  dependencies = await snapshotDependencies({
1226
1254
  repos: this.repositories(),
1227
1255
  repositoryId: repo.id,
1228
- dir: join(this.dirOf(repo.id), 'dependencies', id),
1256
+ dir: this.checkout(repo.id, 'dependencies', id),
1229
1257
  artifacts: own,
1230
1258
  runId: attempt.id,
1231
1259
  policy: this.policy,
@@ -1332,6 +1360,7 @@ export class Runner {
1332
1360
  cwd,
1333
1361
  controller: boundary.hidden,
1334
1362
  readable: [cwd, ...boundary.readable],
1363
+ ...(boundary.checkouts.length ? { checkouts: boundary.checkouts } : {}),
1335
1364
  isolation: this.policy.isolation,
1336
1365
  commandTimeoutMs: limits.commandTimeoutMs,
1337
1366
  budgetMs,
@@ -1895,6 +1924,12 @@ export class Runner {
1895
1924
  stateDir: this.options.stateDir,
1896
1925
  repoPath: (repo) => this.repoPath(repo),
1897
1926
  boundary: () => this.boundary(),
1927
+ // Прежнее место эксперимента — общий каталог состояния: меняется только корень вне дерева.
1928
+ ...(this.checkoutRoot().root
1929
+ ? {
1930
+ checkout: (repositoryId, kind, id) => this.checkout(repositoryId, kind, id),
1931
+ }
1932
+ : {}),
1898
1933
  ...(this.options.environment ? { environment: this.options.environment } : {}),
1899
1934
  }, raw);
1900
1935
  }
@@ -1909,6 +1944,12 @@ export class Runner {
1909
1944
  stateDir: this.options.stateDir,
1910
1945
  repoPath: (repo) => this.repoPath(repo),
1911
1946
  boundary: () => this.boundary(),
1947
+ // Прежнее место эксперимента — общий каталог состояния: меняется только корень вне дерева.
1948
+ ...(this.checkoutRoot().root
1949
+ ? {
1950
+ checkout: (repositoryId, kind, id) => this.checkout(repositoryId, kind, id),
1951
+ }
1952
+ : {}),
1912
1953
  ...(this.options.environment ? { environment: this.options.environment } : {}),
1913
1954
  }, raw);
1914
1955
  }
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Где harness создаёт рабочие деревья попыток, снимки зависимостей, деревья
3
+ * переноса базы, проверки на SHA и проверки потребителей.
4
+ *
5
+ * Прежде они лежали в каталоге состояния. При встроенном размещении каталог
6
+ * состояния находится внутри репозитория человека (`<W>/.devcontour-local`),
7
+ * и тогда checkout кандидата оказывался вложен в его рабочее дерево. Песочница
8
+ * закрывает `<W>` целиком и открывает только сам checkout, а инструменты,
9
+ * которые ищут конфигурацию вверх по дереву (browserslist, Metro, postcss,
10
+ * tsconfig, prettier), доходили до `<W>/package.json` и получали EPERM вместо
11
+ * ENOENT. Без песочницы они бы прочитали конфигурацию рабочего дерева
12
+ * человека — кандидат проверялся бы не сам по себе.
13
+ *
14
+ * Поэтому корень рабочих деревьев выбирается так:
15
+ * - корень, заданный хостом (`checkoutRoot`), — как есть, если он не внутри
16
+ * репозитория, закрытого пути или каталога состояния (иначе отказ);
17
+ * - каталог состояния внутри репозитория политики или внутри закрытого
18
+ * песочницей пути — каталог кэша пользователя вне дерева: macOS
19
+ * `~/Library/Caches/devcontour-harness/<hash>`, Linux
20
+ * `$XDG_CACHE_HOME/devcontour-harness/<hash>` или
21
+ * `~/.cache/devcontour-harness/<hash>`; `<hash>` — устойчивый хэш
22
+ * настоящего пути каталога состояния;
23
+ * - иначе — прежнее место (отдельное размещение не меняется).
24
+ *
25
+ * Кэш на другом томе, чем репозиторий, ломает жёсткие ссылки и reflink
26
+ * менеджеров пакетов (pnpm store): тогда корень остаётся прежним, а причина
27
+ * видна в `note` (doctor хоста её показывает). Так же — кэш внутри
28
+ * репозитория, закрытого пути или каталога состояния (`XDG_CACHE_HOME=<W>/.cache`)
29
+ * и каталог кэша, который оказался ссылкой или принадлежит другому
30
+ * пользователю: каталоги кэша создаются с правами 0700.
31
+ *
32
+ * Корни кэша не убираются, когда workspace переносят или удаляют: каталоги
33
+ * `<кэш>/devcontour-harness/<hash>` без живого каталога состояния можно удалить
34
+ * вручную, когда harness не запущен.
35
+ */
36
+ export type CheckoutPlacement = 'configured' | 'in-place' | 'cache' | 'cross-volume';
37
+ export interface CheckoutRoot {
38
+ /** Корень вне каталога состояния; без него — прежнее место. */
39
+ root?: string;
40
+ placement: CheckoutPlacement;
41
+ /** Пояснение для диагностики: почему корень такой. */
42
+ note?: string;
43
+ }
44
+ export interface CheckoutRootInput {
45
+ /** Каталоги состояния (общий и каталоги попыток репозиториев); первый задаёт хэш. */
46
+ stateDirs: string[];
47
+ /** Пути репозиториев политики. */
48
+ repositories: string[];
49
+ /** Что ещё закрыто песочницей (учётные данные, каталоги хоста). */
50
+ hidden?: string[];
51
+ /** Корень, заданный хостом. */
52
+ configured?: string;
53
+ platform?: NodeJS.Platform;
54
+ env?: NodeJS.ProcessEnv;
55
+ home?: string;
56
+ /** Номер тома пути (`stat.dev`); тест подменяет его. */
57
+ device?: (path: string) => number | undefined;
58
+ /**
59
+ * Создать каталоги кэша (0700). Без записи (`false`, диагностика) —
60
+ * только проверка существующих.
61
+ */
62
+ create?: boolean;
63
+ /** Владелец каталогов кэша; по умолчанию — текущий пользователь. */
64
+ uid?: number;
65
+ }
66
+ /** Настоящий путь и для ещё не созданного каталога: от ближайшего существующего предка. */
67
+ export declare function realish(path: string): string;
68
+ /** Каталог кэша пользователя для рабочих деревьев (без хэша). */
69
+ export declare function checkoutCacheBase(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
70
+ /** Устойчивый хэш каталога состояния: тот же путь — тот же корень. */
71
+ export declare const stateHash: (stateDir: string) => string;
72
+ export declare function chooseCheckoutRoot(input: CheckoutRootInput): CheckoutRoot;
73
+ /**
74
+ * Каталог рабочего дерева вида `kind` (`worktrees`, `dependencies`,
75
+ * `gates-at`…). Корень вне дерева: `<root>/<repositoryId>/<kind>/…`; иначе —
76
+ * прежний путь `legacy`.
77
+ */
78
+ export declare function checkoutPath(choice: CheckoutRoot, legacy: string, repositoryId: string, kind: string, ...rest: string[]): string;
@@ -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): {
@@ -167,11 +177,26 @@ export declare function watchSandboxLog(tag: string): Promise<{
167
177
  stop(drainMs: number): Promise<SandboxViolation[]>;
168
178
  } | undefined>;
169
179
  /**
170
- * Отказы обязательной политики в открытых проверке каталогах, которые
171
- * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
172
- * а не среды: её здесь нет.
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
+ * становятся: отказ среды не тратит попытку и останавливает очередь.
173
198
  */
174
- export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation): {
199
+ export declare function sandboxDenials(violations: SandboxViolation[], policy: Isolation, output?: string, cwd?: string): {
175
200
  path: string;
176
201
  rule: string;
177
202
  }[];