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
@@ -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
  // песочницы. Более конкретный путь открыт; токены и сессии — нет.
@@ -434,17 +434,51 @@ export async function watchSandboxLog(tag) {
434
434
  };
435
435
  }
436
436
  /**
437
- * Отказы обязательной политики в открытых проверке каталогах, которые
438
- * подтвердило ядро. Запись вне открытых каталогов — ошибка кода проверки,
439
- * а не среды: её здесь нет.
437
+ * Запрет чтения, которым песочница закрыла путь: путь внутри закрытого и не
438
+ * внутри более конкретного открытого (srt: открытое внутри закрытого
439
+ * побеждает, закрытое внутри открытого — снова закрыто).
440
440
  */
441
- 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) {
442
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);
443
473
  for (const v of violations) {
444
- if (!v.operation.startsWith('file-write'))
474
+ if (found.has(v.path))
445
475
  continue;
446
- const rule = mandatoryDenyRule(policy, v.path);
447
- 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)
448
482
  found.set(v.path, rule);
449
483
  }
450
484
  return [...found].map(([path, rule]) => ({ path, rule }));
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
  }
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from 'node:crypto';
2
- import { mkdir, rm } from 'node:fs/promises';
3
- import { join } from 'node:path';
2
+ import { mkdir, rm, rmdir } from 'node:fs/promises';
3
+ import { dirname, join } from 'node:path';
4
4
  import { HarnessError } from "../contracts/index.js";
5
5
  import { TaskFailure } from "../engine/failure.js";
6
6
  import { git } from "../environment/process.js";
@@ -8,6 +8,8 @@ import { executionEnvironment, runSteps, withEnvironment } from "../environment/
8
8
  import { defaultResourceDatabase, withResources } from "../environment/resources.js";
9
9
  import { removeSnapshots, snapshotDependencies } from "./dependencies.js";
10
10
  import { runGate } from "./gates.js";
11
+ import { checkoutPath, chooseCheckoutRoot } from "../environment/checkout-root.js";
12
+ import { credentialPaths } from "../environment/isolation.js";
11
13
  import { explicitPrerequisites, orderedScope, standaloneScope } from "./gate-scope.js";
12
14
  /**
13
15
  * Gates компонента на закреплённом SHA вне попытки — тем же исполнением, что
@@ -40,7 +42,16 @@ export async function runGatesAt(ctx, input) {
40
42
  throw new HarnessError('NOT_FOUND', `Commit ${input.sha} недоступен в ${repo.id}`);
41
43
  });
42
44
  const root = join(ctx.stateDir, 'gates-at', id);
43
- const cwd = join(root, 'worktree');
45
+ // Рабочее дерево и снимки — под корнем вне дерева, если каталог состояния
46
+ // лежит внутри репозитория; логи остаются в каталоге состояния.
47
+ const placement = chooseCheckoutRoot({
48
+ stateDirs: [ctx.stateDir],
49
+ repositories: ctx.policy.repositories.map((r) => ctx.repoPath(r)),
50
+ hidden: [...ctx.boundary().hidden, ...credentialPaths()],
51
+ ...(ctx.checkoutRoot ? { configured: ctx.checkoutRoot } : {}),
52
+ });
53
+ const trees = checkoutPath(placement, root, repo.id, 'gates-at', id);
54
+ const cwd = join(trees, 'worktree');
44
55
  const artifacts = join(root, 'artifacts');
45
56
  const timeout = AbortSignal.timeout(ctx.policy.runTimeoutMs);
46
57
  const signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout;
@@ -51,6 +62,7 @@ export async function runGatesAt(ctx, input) {
51
62
  let snapshots = [];
52
63
  let added = false;
53
64
  await mkdir(root, { recursive: true });
65
+ await mkdir(dirname(cwd), { recursive: true });
54
66
  try {
55
67
  await withResources({
56
68
  resources: ctx.policy.resources,
@@ -70,7 +82,7 @@ export async function runGatesAt(ctx, input) {
70
82
  snapshots = await snapshotDependencies({
71
83
  repos,
72
84
  repositoryId: repo.id,
73
- dir: join(root, 'dependencies'),
85
+ dir: join(trees, 'dependencies'),
74
86
  artifacts,
75
87
  runId: id,
76
88
  policy: ctx.policy,
@@ -131,6 +143,14 @@ export async function runGatesAt(ctx, input) {
131
143
  boundary: {
132
144
  hidden: boundary.hidden,
133
145
  readable: [...boundary.readable, ...snapshots.map((d) => d.path)],
146
+ // Корень вне дерева закрыт (свои деревья открыты), и тогда,
147
+ // когда хост его в своей границе не назвал.
148
+ checkouts: [
149
+ ...new Set([
150
+ ...(boundary.checkouts ?? []),
151
+ ...(placement.root ? [placement.root] : []),
152
+ ]),
153
+ ],
134
154
  },
135
155
  // Генеративный gate получает seed от этой проверки; договора
136
156
  // поручения у неё нет — прежний уровень отчёта свойств.
@@ -160,7 +180,12 @@ export async function runGatesAt(ctx, input) {
160
180
  repo: (rid) => ctx.policy.repositories.find((r) => r.id === rid),
161
181
  path: (r) => ctx.repoPath(r),
162
182
  }, snapshots);
163
- await rm(join(root, 'worktree'), { recursive: true, force: true }).catch(() => undefined);
183
+ await rm(cwd, { recursive: true, force: true }).catch(() => undefined);
184
+ // Пустой каталог проверки вне дерева не копится; непустой (снимок, который
185
+ // не удалось убрать) остаётся как есть.
186
+ if (trees !== root)
187
+ for (const dir of [join(trees, 'dependencies'), trees])
188
+ await rmdir(dir).catch(() => undefined);
164
189
  }
165
190
  return {
166
191
  id,
@@ -78,6 +78,8 @@ export declare function runCheck(h: {
78
78
  write: string[];
79
79
  readable: string[];
80
80
  controller: string[];
81
+ /** Корни рабочих деревьев вне каталога состояния: закрыты целиком, свои деревья открыты. */
82
+ checkouts?: string[];
81
83
  settingsDir: string;
82
84
  /**
83
85
  * Собрать отказы песочницы из журнала ядра (macOS): по ним, а не по
@@ -143,6 +145,16 @@ export declare function sandboxBlockedHosts(output: string, allowed: string[]):
143
145
  */
144
146
  export declare const propertyReportEnv = "DEVCONTOUR_PROPERTY_REPORT";
145
147
  export declare function freshnessEnv(kind: GatePolicy['kind'], env: NodeJS.ProcessEnv): Record<string, string>;
148
+ /**
149
+ * Граница проверки: закрытое (состояние controller, исходные checkout),
150
+ * открытое внутри него и корни рабочих деревьев вне каталога состояния,
151
+ * закрытые целиком (свои деревья проверки открыты).
152
+ */
153
+ export interface Boundary {
154
+ hidden: string[];
155
+ readable: string[];
156
+ checkouts?: string[];
157
+ }
146
158
  /** Что нужно для запуска gate попытки. */
147
159
  export interface GateRun {
148
160
  policy: Pick<ExecutionPolicy, 'isolation'>;
@@ -160,10 +172,7 @@ export interface GateRun {
160
172
  redact: (value: string) => string;
161
173
  };
162
174
  /** Закрытое проверке (состояние controller, чужие checkout) и открытое внутри него. */
163
- boundary: {
164
- hidden: string[];
165
- readable: string[];
166
- };
175
+ boundary: Boundary;
167
176
  /** Проверка потребителя: evidence несёт его компонент и не закрывает собственные gates. */
168
177
  consumer?: string;
169
178
  /** Повтор провала: ID записи, которую повторяет запуск; исход пишется в `recheck`. */
@@ -277,6 +277,7 @@ h, options) {
277
277
  controller: options.controller,
278
278
  readable: options.readable,
279
279
  domains: h.config.isolation.domains,
280
+ ...(options.checkouts?.length ? { checkouts: options.checkouts } : {}),
280
281
  });
281
282
  started = join(marks, 'started');
282
283
  // Обязательные запреты записи — для checkout проверки целиком, а не
@@ -506,6 +507,7 @@ export async function runGate(run) {
506
507
  write: [cwd, ...(propertyDir ? [propertyDir] : [])],
507
508
  readable: [...run.boundary.readable, ...(corpusDir ? [corpusDir] : [])],
508
509
  controller: run.boundary.hidden,
510
+ ...(run.boundary.checkouts?.length ? { checkouts: run.boundary.checkouts } : {}),
509
511
  settingsDir: join(artifactDir, gate.id),
510
512
  violations: true,
511
513
  });
@@ -546,7 +548,7 @@ export async function runGate(run) {
546
548
  // Отказ файловой песочницы — отказ среды: правка кода его не снимет,
547
549
  // а класс gate сжигал бы бюджет ремонтов.
548
550
  const denied = result.isolation && result.violations
549
- ? sandboxDenials(result.violations, result.isolation)
551
+ ? sandboxDenials(result.violations, result.isolation, result.stdout + '\n' + result.stderr, gateCwd)
550
552
  : [];
551
553
  if (denied.length) {
552
554
  kind = 'environment';
@@ -1,5 +1,6 @@
1
1
  import { type ExecutionPolicy, type ExecutionView, type Spike } from '../contracts/index.ts';
2
2
  import type { Engine } from '../engine/engine.ts';
3
+ import { type Boundary } from './gates.ts';
3
4
  /** Что нужно эксперименту от controller. */
4
5
  export interface SpikeContext {
5
6
  engine: Engine;
@@ -7,10 +8,12 @@ export interface SpikeContext {
7
8
  stateDir: string;
8
9
  repoPath(repo: ExecutionPolicy['repositories'][number]): string;
9
10
  /** Закрытое проверке и открытое внутри него. */
10
- boundary(): {
11
- hidden: string[];
12
- readable: string[];
13
- };
11
+ boundary(): Boundary;
12
+ /**
13
+ * Каталог рабочего дерева вида `kind` (корень вне дерева, `checkout-root.ts`);
14
+ * без него — прежнее место в каталоге состояния.
15
+ */
16
+ checkout?(repositoryId: string, kind: string, id: string): string;
14
17
  environment?: NodeJS.ProcessEnv;
15
18
  }
16
19
  /** Эксперимент репозитория по ID или undefined. */
@@ -1,7 +1,7 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { mkdir } from 'node:fs/promises';
3
3
  import { arch, cpus, platform } from 'node:os';
4
- import { join } from 'node:path';
4
+ import { dirname, join } from 'node:path';
5
5
  import { HarnessError, digestOf, spikeInputSchema, spikeSchema, } from "../contracts/index.js";
6
6
  import { git } from "../environment/process.js";
7
7
  import { executionEnvironment } from "../environment/lifecycle.js";
@@ -46,8 +46,9 @@ export async function runSpike(ctx, raw) {
46
46
  });
47
47
  const id = 'SP-' + randomUUID();
48
48
  const root = join(ctx.stateDir, 'spikes');
49
- const dir = join(root, id);
49
+ const dir = ctx.checkout?.(repo.id, 'spikes', id) ?? join(root, id);
50
50
  await mkdir(root, { recursive: true });
51
+ await mkdir(dirname(dir), { recursive: true });
51
52
  await git(path, 'worktree', 'add', '--detach', dir, sha);
52
53
  const results = [];
53
54
  try {
@@ -65,6 +66,7 @@ export async function runSpike(ctx, raw) {
65
66
  write: [dir],
66
67
  readable: boundary.readable,
67
68
  controller: boundary.hidden,
69
+ ...(boundary.checkouts?.length ? { checkouts: boundary.checkouts } : {}),
68
70
  settingsDir: join(root, `${id}-settings`),
69
71
  });
70
72
  results.push({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "devcontour-harness",
3
- "version": "0.1.0-alpha.22",
3
+ "version": "0.1.0-alpha.23",
4
4
  "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
5
5
  "type": "module",
6
6
  "license": "MIT",