devcontour-harness 0.1.0-alpha.26 → 0.1.0-alpha.28

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 (69) hide show
  1. package/README.md +15 -2
  2. package/docs/architecture.md +59 -0
  3. package/docs/compatibility.md +25 -12
  4. package/docs/connectors.md +5 -2
  5. package/docs/contracts.md +80 -25
  6. package/docs/release-notes/0.1.0-alpha.27.md +36 -0
  7. package/docs/release-notes/0.1.0-alpha.28.md +37 -0
  8. package/docs/review-protocol.md +10 -4
  9. package/docs/toolchains.md +83 -0
  10. package/docs/upgrade.md +22 -0
  11. package/lib/cli.js +13 -0
  12. package/lib/contracts/cli.d.ts +147 -19
  13. package/lib/contracts/cli.js +66 -0
  14. package/lib/contracts/diagnosis.d.ts +1 -1
  15. package/lib/contracts/events.d.ts +6 -6
  16. package/lib/contracts/execution.d.ts +268 -16
  17. package/lib/contracts/execution.js +3 -1
  18. package/lib/contracts/policy.d.ts +37 -5
  19. package/lib/contracts/policy.js +42 -2
  20. package/lib/contracts/profiles.d.ts +2 -0
  21. package/lib/contracts/published.d.ts +226 -20
  22. package/lib/contracts/result.d.ts +268 -12
  23. package/lib/contracts/result.js +66 -0
  24. package/lib/control/harness.d.ts +64 -7
  25. package/lib/control/harness.js +4 -0
  26. package/lib/control/recovery.d.ts +1 -1
  27. package/lib/control/review.js +6 -1
  28. package/lib/engine/engine.d.ts +117 -12
  29. package/lib/engine/joint-runner.d.ts +96 -6
  30. package/lib/engine/joint-runner.js +47 -1
  31. package/lib/engine/runner.d.ts +29 -0
  32. package/lib/engine/runner.js +200 -2
  33. package/lib/engine/worktree-cleanup.d.ts +131 -0
  34. package/lib/engine/worktree-cleanup.js +520 -0
  35. package/lib/environment/isolation.d.ts +1 -0
  36. package/lib/environment/isolation.js +2 -1
  37. package/lib/environment/os-tools.d.ts +4 -2
  38. package/lib/environment/os-tools.js +4 -2
  39. package/lib/environment/process.d.ts +5 -0
  40. package/lib/environment/process.js +40 -17
  41. package/lib/environment/resources.d.ts +9 -0
  42. package/lib/environment/resources.js +24 -0
  43. package/lib/index.d.ts +1 -0
  44. package/lib/index.js +1 -0
  45. package/lib/integrations/connector/commands.d.ts +2 -1
  46. package/lib/integrations/connector/commands.js +10 -2
  47. package/lib/integrations/connector/store.d.ts +1 -1
  48. package/lib/integrations/connector/store.js +11 -6
  49. package/lib/profiles/resolve.d.ts +8 -0
  50. package/lib/storage/document.d.ts +132 -12
  51. package/lib/toolchains/inspect.d.ts +1 -1
  52. package/lib/toolchains/inspect.js +29 -1
  53. package/lib/toolchains/probe.d.ts +16 -0
  54. package/lib/toolchains/probe.js +20 -0
  55. package/lib/verification/confirm.d.ts +3 -1
  56. package/lib/verification/confirm.js +16 -2
  57. package/lib/verification/dependencies.d.ts +3 -0
  58. package/lib/verification/dependencies.js +11 -0
  59. package/lib/verification/dependency-store.d.ts +117 -0
  60. package/lib/verification/dependency-store.js +811 -0
  61. package/lib/verification/gate-artifacts.d.ts +34 -0
  62. package/lib/verification/gate-artifacts.js +303 -0
  63. package/lib/verification/gates-at.js +18 -0
  64. package/lib/verification/gates.js +15 -0
  65. package/lib/verification/joint.d.ts +48 -3
  66. package/package.json +1 -1
  67. package/schemas/execution-document.schema.json +372 -0
  68. package/schemas/execution-policy.schema.json +56 -0
  69. package/schemas/joint-verification.schema.json +279 -0
@@ -0,0 +1,520 @@
1
+ import { execFile } from 'node:child_process';
2
+ import { createHash, randomUUID } from 'node:crypto';
3
+ import { existsSync } from 'node:fs';
4
+ import { link, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
5
+ import { tmpdir } from 'node:os';
6
+ import { basename, dirname, join, relative } from 'node:path';
7
+ import { HarnessError } from "../contracts/index.js";
8
+ import { command, hostGitArgs } from "../environment/process.js";
9
+ import { assertTrustedCheckout, forgetWorktree, worktreeKey } from "../environment/git-trust.js";
10
+ const terminalWork = ['done', 'failed', 'cancelled'];
11
+ /** Сколько верхних путей игнорируемого называет отчёт. */
12
+ const IGNORED_PATHS = 20;
13
+ /** Почему попытку нельзя лишить дерева: идёт, или её работа ещё может продолжиться. */
14
+ export function attemptRefusal(attempt, work, latest, running) {
15
+ if (attempt.status === 'active' || running)
16
+ return 'active';
17
+ if (latest && !(work && terminalWork.includes(work.status)))
18
+ return 'recoverable';
19
+ return undefined;
20
+ }
21
+ /** Незавершённая очистка: дерево — вход `cleanup --run`, его нельзя убирать мимо teardown. */
22
+ export async function cleanupUnfinished(artifacts, receipts) {
23
+ const file = join(artifacts, 'cleanup-pending.json');
24
+ if (existsSync(file)) {
25
+ const { reason } = JSON.parse(await readFile(file, 'utf8'));
26
+ if (reason !== 'remove-failed')
27
+ return true;
28
+ }
29
+ for (const receipt of receipts) {
30
+ const { status } = JSON.parse(await readFile(receipt, 'utf8'));
31
+ if (status === 'active' || status === 'cleanup-failed')
32
+ return true;
33
+ }
34
+ return false;
35
+ }
36
+ /**
37
+ * Вывод git целиком. Решения очистки не могут опираться на обрезанный вывод:
38
+ * `command` держит только хвост в 2 МБ, здесь буфер ограничен отказом, а не
39
+ * усечением. `allowed` — коды выхода, которые не ошибка (check-ignore: 1).
40
+ */
41
+ function gitOutput(cwd, args, options = {}) {
42
+ return new Promise((resolve, reject) => {
43
+ const child = execFile('git', hostGitArgs(cwd, args), {
44
+ cwd,
45
+ env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...options.env },
46
+ encoding: 'buffer',
47
+ maxBuffer: 2 ** 29,
48
+ timeout: options.timeoutMs ?? 600_000,
49
+ }, (error, stdout, stderr) => {
50
+ if (error && error.code !== options.allowed)
51
+ reject(new Error(`git ${args[0]}: ${stderr.toString().trim() || error.message}`));
52
+ else
53
+ resolve(stdout.toString());
54
+ });
55
+ child.stdin?.end(options.input ?? '');
56
+ });
57
+ }
58
+ /** Зарегистрированные рабочие деревья репозитория: настоящий путь → заперто ли. */
59
+ export async function registered(repoPath) {
60
+ const out = await gitOutput(repoPath, ['worktree', 'list', '--porcelain']);
61
+ const found = new Map();
62
+ for (const block of out.split('\n\n')) {
63
+ const path = /^worktree (.+)$/m.exec(block)?.[1];
64
+ if (path)
65
+ found.set(worktreeKey(path), { locked: /^locked\b/m.test(block) });
66
+ }
67
+ return found;
68
+ }
69
+ /** Вершина самого дерева: список деревьев снят раньше, а работа в дереве могла идти. */
70
+ export const treeHead = (dir) => gitOutput(dir, ['rev-parse', '--verify', 'HEAD']).then((out) => out.trim(), () => undefined);
71
+ /**
72
+ * Вершину держит ref, который переживёт дерево. Запрос идёт из общего репозитория,
73
+ * а не из дерева: `refs/worktree`, `refs/bisect` и `refs/rewritten` принадлежат
74
+ * рабочему дереву и исчезают вместе с ним.
75
+ */
76
+ async function headSurvives(repoPath, head) {
77
+ const refs = await gitOutput(repoPath, [
78
+ 'for-each-ref',
79
+ '--contains',
80
+ head,
81
+ '--format=%(refname)',
82
+ ]);
83
+ return refs.split('\n').some((r) => r && !/^refs\/(worktree|bisect|rewritten)\//.test(r));
84
+ }
85
+ /**
86
+ * Настоящее дерево вместе с игнорируемым: вложенный репозиторий (`.git` файлом
87
+ * или каталогом, либо голый) git-командам внешнего не виден, если каталог
88
+ * игнорируется. В `node_modules` тоже смотрим: зависимость из git-источника или
89
+ * правка на месте бывает единственной копией работы. Обход ограничен: дошедший
90
+ * до предела обход не доказал ничего. Символические ссылки не проходятся.
91
+ */
92
+ export async function scanTree(root, limit) {
93
+ const scan = { limited: false, ignoreFiles: [] };
94
+ const stack = [root];
95
+ let entries = 0;
96
+ while (stack.length) {
97
+ const dir = stack.pop();
98
+ const rel = relative(root, dir);
99
+ if (!((await lstat(dir)).mode & 0o200))
100
+ scan.readOnly ??= rel || '.';
101
+ const items = await readdir(dir, { withFileTypes: true });
102
+ entries += items.length;
103
+ if (entries > limit)
104
+ return { ...scan, limited: true };
105
+ const names = new Set(items.map((i) => i.name));
106
+ if (dir !== root &&
107
+ (names.has('.git') || ['HEAD', 'objects', 'refs'].every((n) => names.has(n))))
108
+ return { ...scan, embedded: rel };
109
+ for (const item of items) {
110
+ // Имя не в UTF-8 дошло бы до git уже другими байтами.
111
+ if (item.name.includes('\uFFFD'))
112
+ scan.undecodable ??= join(rel, item.name);
113
+ if (item.name === '.git')
114
+ continue;
115
+ if (item.name === '.gitignore')
116
+ scan.ignoreFiles.push(join(rel, item.name));
117
+ if (item.isDirectory())
118
+ stack.push(join(dir, item.name));
119
+ }
120
+ }
121
+ return scan;
122
+ }
123
+ /** Записи индекса: gitlink — чужой репозиторий; assume-unchanged и skip-worktree прячут правки. */
124
+ async function indexFlags(dir) {
125
+ const out = await gitOutput(dir, ['--no-optional-locks', 'ls-files', '-v', '-s', '-z']);
126
+ let gitlink = false;
127
+ let hidden = false;
128
+ for (const line of out.split('\0')) {
129
+ if (!line)
130
+ continue;
131
+ const [tag, mode] = line.split(' ');
132
+ if (mode === '160000')
133
+ gitlink = true;
134
+ if (tag === 'S' || (tag && tag !== tag.toUpperCase()))
135
+ hidden = true;
136
+ }
137
+ return { gitlink, hidden };
138
+ }
139
+ const blobId = (content, head) => createHash(head.length > 40 ? 'sha256' : 'sha1')
140
+ .update(`blob ${content.length}\0`)
141
+ .update(content)
142
+ .digest('hex');
143
+ /**
144
+ * Правила игнорирования скрывают работу: изменённый `.gitignore` убрал бы её из
145
+ * статуса и из патча. Считается только то, что git читает: `.gitignore` внутри
146
+ * каталога, игнорируемого неизменёнными правилами (пакет в `node_modules`), ни
147
+ * на что не влияет. У `info/exclude` нет версии в HEAD, а шаблон git и настройки
148
+ * человека держат там правила и без попытки, поэтому отказ — когда его правило
149
+ * скрывает путь, существующий в дереве.
150
+ */
151
+ async function ignoreRulesChanged(dir, head, files, present) {
152
+ if (present.length) {
153
+ const fields = (await gitOutput(dir, ['check-ignore', '--stdin', '-z', '-v'], {
154
+ input: present.map((p) => p.replace(/\/$/, '')).join('\0') + '\0',
155
+ allowed: 1,
156
+ })).split('\0');
157
+ for (let i = 0; i + 3 < fields.length; i += 4)
158
+ if (fields[i].endsWith('info/exclude'))
159
+ return true;
160
+ }
161
+ const tree = await gitOutput(dir, ['ls-tree', '-r', '-z', head]);
162
+ const inHead = new Map();
163
+ for (const line of tree.split('\0')) {
164
+ const m = /^(\d+) \w+ (\w+)\t(.+)$/s.exec(line);
165
+ if (m && basename(m[3]) === '.gitignore')
166
+ inHead.set(m[3], { mode: m[1], id: m[2] });
167
+ }
168
+ const changed = new Set();
169
+ for (const file of files) {
170
+ const known = inHead.get(file);
171
+ const path = join(dir, file);
172
+ if (!known ||
173
+ known.mode === '120000' ||
174
+ (await lstat(path)).isSymbolicLink() ||
175
+ blobId(await readFile(path), head) !== known.id)
176
+ changed.add(file);
177
+ }
178
+ for (const file of inHead.keys())
179
+ if (!files.includes(file))
180
+ changed.add(file);
181
+ const dirs = [...changed].map(dirname);
182
+ if (dirs.includes('.'))
183
+ return true;
184
+ if (!dirs.length)
185
+ return false;
186
+ const ignored = await gitOutput(dir, ['check-ignore', '--stdin', '-z'], {
187
+ input: dirs.join('\0') + '\0',
188
+ allowed: 1,
189
+ });
190
+ const inert = new Set(ignored.split('\0'));
191
+ return dirs.some((d) => !inert.has(d));
192
+ }
193
+ /**
194
+ * Путь дерева идёт через настроенный clean-фильтр: `git add` сохранил бы его
195
+ * вывод, а не файл, и проверка патча этого не заметит — фильтр потерял бы данные
196
+ * на обеих сторонах сравнения.
197
+ */
198
+ async function cleanFilterApplies(dir) {
199
+ const names = await gitOutput(dir, ['config', '--name-only', '-z', '--get-regexp', '^filter\\..*\\.(clean|process)$'], { allowed: 1 });
200
+ const configured = new Set(names.split('\0').flatMap((key) => /^filter\.(.+)\.(clean|process)$/s.exec(key)?.[1] ?? []));
201
+ if (!configured.size)
202
+ return false;
203
+ const paths = await gitOutput(dir, ['ls-files', '-z', '--cached', '--others']);
204
+ const fields = (await gitOutput(dir, ['check-attr', '--stdin', '-z', 'filter'], { input: paths })).split('\0');
205
+ for (let i = 2; i < fields.length; i += 3)
206
+ if (configured.has(fields[i]))
207
+ return true;
208
+ return false;
209
+ }
210
+ /**
211
+ * Настоящий индекс хранит то, чего не будет в патче: патч строится из файлов дерева
212
+ * без учёта игнорируемого. Файл, добавленный через `git add -f`, в него не войдёт, а
213
+ * проиндексированная версия, отличная от файла, потеряется. Единственная копия тогда
214
+ * лежит в индексе дерева. Добавлять такое через `-f` нельзя: индекс мог получить
215
+ * игнорируемое и случайно. Индекс, равный файлу дерева, правки не теряет.
216
+ */
217
+ async function stagedRefusal(dir, head) {
218
+ const raw = (...args) => gitOutput(dir, [
219
+ '--no-optional-locks',
220
+ 'diff',
221
+ '--raw',
222
+ '-z',
223
+ '--no-abbrev',
224
+ '--no-renames',
225
+ ...args,
226
+ ]);
227
+ const fields = (await raw('--cached', head)).split('\0');
228
+ const added = [];
229
+ const staged = new Set();
230
+ for (let i = 0; i + 1 < fields.length; i += 2) {
231
+ const status = fields[i].split(' ')[4];
232
+ if (status === 'D')
233
+ continue;
234
+ staged.add(fields[i + 1]);
235
+ if (status === 'A')
236
+ added.push(fields[i + 1]);
237
+ }
238
+ if (!staged.size)
239
+ return undefined;
240
+ if (added.length) {
241
+ const ignored = await gitOutput(dir, ['check-ignore', '--no-index', '--stdin', '-z'], {
242
+ input: added.join('\0') + '\0',
243
+ allowed: 1,
244
+ });
245
+ if (ignored)
246
+ return 'staged-ignored';
247
+ }
248
+ const worktree = (await raw()).split('\0');
249
+ for (let i = 1; i < worktree.length; i += 2)
250
+ if (staged.has(worktree[i]))
251
+ return 'staged-differs';
252
+ return undefined;
253
+ }
254
+ /** Неподтверждённые правки и игнорируемое без записи в индекс дерева. */
255
+ async function treeStatus(dir) {
256
+ const out = await gitOutput(dir, [
257
+ '--no-optional-locks',
258
+ 'status',
259
+ '--porcelain',
260
+ '-z',
261
+ '--no-renames',
262
+ '--ignored=matching',
263
+ '-uall',
264
+ ]);
265
+ let uncommitted = 0;
266
+ const entries = [];
267
+ for (const entry of out.split('\0')) {
268
+ if (!entry)
269
+ continue;
270
+ if (!entry.startsWith('!! '))
271
+ uncommitted++;
272
+ else
273
+ entries.push(entry.slice(3));
274
+ }
275
+ const top = new Set(entries.map((path) => path.split('/')[0]));
276
+ return {
277
+ raw: out,
278
+ entries,
279
+ uncommitted,
280
+ ignored: { count: entries.length, paths: [...top].sort().slice(0, IGNORED_PATHS) },
281
+ };
282
+ }
283
+ /** Что мешает удалить дерево, и что в нём лежит. Ничего не пишет. */
284
+ export async function inspectTree(dir, repoPath, head, limit) {
285
+ let scan;
286
+ try {
287
+ scan = await scanTree(dir, limit);
288
+ }
289
+ catch {
290
+ return { refusal: 'scan-failed' };
291
+ }
292
+ if (scan.limited)
293
+ return { refusal: 'scan-limit' };
294
+ if (scan.embedded)
295
+ return { refusal: 'embedded-repository' };
296
+ if (scan.undecodable)
297
+ return { refusal: 'undecodable-path' };
298
+ const { entries, raw, ...counts } = await treeStatus(dir);
299
+ const status = { ...counts, status: raw };
300
+ const refused = (refusal) => ({ refusal, ...status });
301
+ const flags = await indexFlags(dir);
302
+ if (flags.gitlink)
303
+ return refused('embedded-repository');
304
+ if (!head || !(await headSurvives(repoPath, head)))
305
+ return refused('unreachable-head');
306
+ if (await ignoreRulesChanged(dir, head, scan.ignoreFiles, entries))
307
+ return refused('ignore-rules-changed');
308
+ if (flags.hidden)
309
+ return refused('hidden-changes');
310
+ const staged = await stagedRefusal(dir, head);
311
+ if (staged)
312
+ return refused(staged);
313
+ if (await cleanFilterApplies(dir))
314
+ return refused('clean-filter');
315
+ if (scan.readOnly)
316
+ return refused('read-only-path');
317
+ return status;
318
+ }
319
+ /** Первое свободное имя: уже сохранённый патч не перезаписывается. */
320
+ async function publish(temporary, directory, name) {
321
+ for (let n = 1;; n++) {
322
+ const path = join(directory, `${name}${n > 1 ? `-${n}` : ''}.patch`);
323
+ try {
324
+ await link(temporary, path);
325
+ return path;
326
+ }
327
+ catch (error) {
328
+ if (error.code !== 'EEXIST')
329
+ throw error;
330
+ }
331
+ }
332
+ }
333
+ /** Дерево всех неигнорируемых файлов поверх вершины; индекс попытки не меняется. */
334
+ async function editsTree(dir, head, env) {
335
+ await gitOutput(dir, ['read-tree', head], { env });
336
+ await gitOutput(dir, ['add', '-A', '--', '.'], { env });
337
+ return (await gitOutput(dir, ['write-tree'], { env })).trim();
338
+ }
339
+ /**
340
+ * Дерево то же, что при проверках: та же вершина, тот же статус, те же правки.
341
+ * Узкое окно до удаления остаётся: запись после этой сверки не будет замечена.
342
+ */
343
+ export async function treeUnchanged(dir, head, status, edits) {
344
+ if ((await treeHead(dir)) !== head || (await treeStatus(dir)).raw !== status)
345
+ return false;
346
+ if (!edits)
347
+ return true;
348
+ const scratch = await mkdtemp(join(tmpdir(), 'harness-worktree-index-'));
349
+ try {
350
+ return (await editsTree(dir, head, { GIT_INDEX_FILE: join(scratch, 'index') })) === edits;
351
+ }
352
+ finally {
353
+ await rm(scratch, { recursive: true, force: true });
354
+ }
355
+ }
356
+ /**
357
+ * Неподтверждённые правки дерева — патчем к закреплённой вершине `head`, той же,
358
+ * что в записи об удалении. Индекс попытки не
359
+ * меняется: всё идёт через временные индексы. Формат закреплён против настроек
360
+ * пользователя, а патч проверен до удаления: наложенный на HEAD, он обязан дать
361
+ * то же дерево, что и правки. Иначе отказ, и дерево остаётся.
362
+ */
363
+ export async function savePatch(dir, artifacts, name, head) {
364
+ const scratch = await mkdtemp(join(tmpdir(), 'harness-worktree-index-'));
365
+ const temporary = join(artifacts, `.${name}.${process.pid}.tmp`);
366
+ try {
367
+ await mkdir(artifacts, { recursive: true });
368
+ const inIndex = (file, ...args) => gitOutput(dir, args, { env: { GIT_INDEX_FILE: join(scratch, file) } });
369
+ const edits = await editsTree(dir, head, { GIT_INDEX_FILE: join(scratch, 'edits') });
370
+ if (/^:\d+ 160000 /m.test(await inIndex('edits', 'diff', '--cached', '--raw', head)))
371
+ return { refusal: 'embedded-repository' };
372
+ await inIndex('edits', '-c', 'diff.noprefix=false', '-c', 'diff.mnemonicPrefix=false', '-c', 'diff.relative=false', 'diff', '--cached', '--binary', '--full-index', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', '--unified=3', '-O/dev/null', '--src-prefix=a/', '--dst-prefix=b/', `--output=${temporary}`, head);
373
+ try {
374
+ await inIndex('proof', 'read-tree', head);
375
+ await inIndex('proof', 'apply', '--cached', '--whitespace=nowarn', temporary);
376
+ if ((await inIndex('proof', 'write-tree')).trim() !== edits)
377
+ return { refusal: 'patch-unusable' };
378
+ }
379
+ catch {
380
+ return { refusal: 'patch-unusable' };
381
+ }
382
+ return { edits, patch: await publish(temporary, artifacts, name) };
383
+ }
384
+ finally {
385
+ await rm(temporary, { force: true });
386
+ await rm(scratch, { recursive: true, force: true });
387
+ }
388
+ }
389
+ /** Дерево на диске — именно зарегистрированное дерево этого репозитория. */
390
+ export function trusted(dir, repoPath) {
391
+ try {
392
+ return assertTrustedCheckout(dir) === assertTrustedCheckout(repoPath);
393
+ }
394
+ catch {
395
+ return false;
396
+ }
397
+ }
398
+ export async function sizeKb(dir) {
399
+ const result = await command(['du', '-sk', dir], tmpdir());
400
+ return Number(/^\d+/.exec(result.stdout)?.[0] ?? 0);
401
+ }
402
+ /** Убрать дерево с пределом для больших деревьев: `command` ждёт по умолчанию 120 с. */
403
+ export async function removeTree(repoPath, path, timeoutMs) {
404
+ await gitOutput(repoPath, ['worktree', 'remove', '--force', path], { timeoutMs });
405
+ forgetWorktree(path);
406
+ }
407
+ export const recordFile = (artifacts, path) => join(artifacts, `worktree-cleanup-${basename(path)}.json`);
408
+ /** Запись об удалении этого дерева; нечитаемая запись — как незавершённое удаление. */
409
+ export async function readRemoval(artifacts, path) {
410
+ const file = recordFile(artifacts, path);
411
+ if (!existsSync(file))
412
+ return undefined;
413
+ try {
414
+ return JSON.parse(await readFile(file, 'utf8'));
415
+ }
416
+ catch {
417
+ return { status: 'incomplete' };
418
+ }
419
+ }
420
+ /**
421
+ * Запись рядом с артефактами попытки: с какой вершины убрано и где патч. Пишется
422
+ * и до удаления: прерванное удаление не теряет указатель на патч и видно
423
+ * следующему запуску. Замена атомарна.
424
+ */
425
+ export async function recordRemoval(artifacts, entry, status, previous) {
426
+ await mkdir(artifacts, { recursive: true });
427
+ const file = recordFile(artifacts, entry.path);
428
+ const temporary = `${file}.${process.pid}.tmp`;
429
+ const record = {
430
+ ...entry,
431
+ status,
432
+ at: new Date().toISOString(),
433
+ ...(previous ? { previous } : {}),
434
+ };
435
+ await writeFile(temporary, JSON.stringify(record, null, 2));
436
+ await rename(temporary, file);
437
+ }
438
+ const alive = (pid) => {
439
+ try {
440
+ process.kill(pid, 0);
441
+ return true;
442
+ }
443
+ catch (error) {
444
+ return error.code === 'EPERM';
445
+ }
446
+ };
447
+ const lockBusy = (file) => new HarnessError('NOT_READY', `Очистка деревьев уже идёт или прервана: ${file}. Если запуска нет, удалите этот файл`);
448
+ /**
449
+ * Снять замок умершего процесса. Снимают по одному: иначе второй претендент,
450
+ * прочитавший тот же умерший PID, удалил бы уже новый замок. Служебный файл
451
+ * захвата держится миллисекунды; файл замка переносится под уникальное имя и
452
+ * сверяется. Пустой замок и живой PID (в том числе занятый другим процессом)
453
+ * не снимаются: это решение человека.
454
+ */
455
+ async function takeOver(file) {
456
+ const claim = `${file}.takeover`;
457
+ const handle = await open(claim, 'wx').catch((error) => {
458
+ if (error.code === 'EEXIST')
459
+ throw lockBusy(claim);
460
+ throw error;
461
+ });
462
+ try {
463
+ await handle.close();
464
+ const seen = await readFile(file, 'utf8').catch(() => undefined);
465
+ if (seen === undefined)
466
+ return;
467
+ const pid = Number(seen.trim().split(' ')[0]);
468
+ if (!pid || alive(pid))
469
+ throw lockBusy(file);
470
+ const moved = `${file}.stale.${randomUUID()}`;
471
+ await rename(file, moved);
472
+ if ((await readFile(moved, 'utf8')) !== seen) {
473
+ await link(moved, file).catch(() => undefined);
474
+ await rm(moved, { force: true });
475
+ throw lockBusy(file);
476
+ }
477
+ await rm(moved, { force: true });
478
+ }
479
+ finally {
480
+ await rm(claim, { force: true });
481
+ }
482
+ }
483
+ /**
484
+ * Один запуск очистки на каталог состояния: два запуска делили бы патчи и записи.
485
+ * Замок сверяет PID, поэтому каталог состояния должен принадлежать одному
486
+ * пространству PID: контейнер со своим пространством увидел бы чужой замок умершим.
487
+ */
488
+ export async function lockCleanup(file) {
489
+ const mine = `${process.pid} ${randomUUID()}`;
490
+ for (let attempt = 0; attempt < 3; attempt++) {
491
+ try {
492
+ const handle = await open(file, 'wx');
493
+ await handle.writeFile(mine);
494
+ await handle.close();
495
+ // Снимается только свой замок: чужой человек мог заменить его вручную.
496
+ return async () => {
497
+ if ((await readFile(file, 'utf8').catch(() => '')) === mine)
498
+ await rm(file, { force: true });
499
+ };
500
+ }
501
+ catch (error) {
502
+ if (error.code !== 'EEXIST')
503
+ throw error;
504
+ await takeOver(file);
505
+ }
506
+ }
507
+ throw lockBusy(file);
508
+ }
509
+ /** Что осталось после отказа удаления; `registered` — только если git ответил. */
510
+ export async function treeState(repoPath, path) {
511
+ const live = await registered(repoPath).catch(() => undefined);
512
+ return {
513
+ ...(live ? { registered: live.has(worktreeKey(path)) } : {}),
514
+ treePresent: existsSync(path),
515
+ };
516
+ }
517
+ export const isWithin = (path, root) => {
518
+ const rest = relative(root, path);
519
+ return !!rest && !rest.startsWith('..') && !rest.startsWith('/');
520
+ };
@@ -201,6 +201,7 @@ export declare function sandboxDenials(violations: SandboxViolation[], policy: I
201
201
  path: string;
202
202
  rule: string;
203
203
  }[];
204
+ export declare const snapshotLimit = 200000;
204
205
  /**
205
206
  * Защищённые элементы checkout вне `node_modules`: путь → подпись.
206
207
  *
@@ -128,6 +128,7 @@ const controllerEntries = [
128
128
  'resources.sqlite',
129
129
  'artifacts',
130
130
  'dependencies',
131
+ 'dependency-store',
131
132
  'deliveries',
132
133
  ];
133
134
  function closedEntries(policy) {
@@ -507,7 +508,7 @@ export function sandboxDenials(violations, policy, output, cwd) {
507
508
  */
508
509
  const protectedNames = new Set([...DANGEROUS_FILES, ...ideDirectories, '.claude', '.git']);
509
510
  const isProtected = (name) => protectedNames.has(name.toLowerCase());
510
- const snapshotLimit = 200_000;
511
+ export const snapshotLimit = 200_000;
511
512
  /**
512
513
  * Подпись каталога, в дереве которого нет ни файлов, ни символьных ссылок, и
513
514
  * ни один каталог не открыт на запись всем (`mode & 0o002`): такой каталог —
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`) и
3
- * владение вызовами (`sysctl`). Они ищутся по фиксированным абсолютным путям
2
+ * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`),
3
+ * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`). Они ищутся по фиксированным абсолютным путям
4
4
  * ОС раньше PATH: урезанный PATH (только node и git) не лишает ядро
5
5
  * containment, а файл из проекта или worktree с тем же именем не
6
6
  * запускается. PATH — только запасной путь, когда ни одного штатного
@@ -10,6 +10,8 @@ export declare const OS_TOOL_CANDIDATES: {
10
10
  readonly ps: readonly ["/bin/ps", "/usr/bin/ps"];
11
11
  readonly lsof: readonly ["/usr/sbin/lsof", "/usr/bin/lsof", "/sbin/lsof", "/bin/lsof"];
12
12
  readonly sysctl: readonly ["/usr/sbin/sysctl", "/sbin/sysctl", "/usr/bin/sysctl"];
13
+ readonly cp: readonly ["/bin/cp", "/usr/bin/cp"];
14
+ readonly df: readonly ["/bin/df", "/usr/bin/df"];
13
15
  };
14
16
  export type OsTool = keyof typeof OS_TOOL_CANDIDATES;
15
17
  /** Исполняемый файл утилиты: первый существующий штатный путь, иначе имя для PATH. */
@@ -1,7 +1,7 @@
1
1
  import { accessSync, constants } from 'node:fs';
2
2
  /**
3
- * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`) и
4
- * владение вызовами (`sysctl`). Они ищутся по фиксированным абсолютным путям
3
+ * Системные утилиты, которыми ядро наблюдает процессы (`ps`, `lsof`),
4
+ * владение вызовами (`sysctl`) и клонирует хранилище зависимостей (`cp`, `df`). Они ищутся по фиксированным абсолютным путям
5
5
  * ОС раньше PATH: урезанный PATH (только node и git) не лишает ядро
6
6
  * containment, а файл из проекта или worktree с тем же именем не
7
7
  * запускается. PATH — только запасной путь, когда ни одного штатного
@@ -11,6 +11,8 @@ export const OS_TOOL_CANDIDATES = {
11
11
  ps: ['/bin/ps', '/usr/bin/ps'],
12
12
  lsof: ['/usr/sbin/lsof', '/usr/bin/lsof', '/sbin/lsof', '/bin/lsof'],
13
13
  sysctl: ['/usr/sbin/sysctl', '/sbin/sysctl', '/usr/bin/sysctl'],
14
+ cp: ['/bin/cp', '/usr/bin/cp'],
15
+ df: ['/bin/df', '/usr/bin/df'],
14
16
  };
15
17
  const resolved = new Map();
16
18
  /** Исполняемый файл утилиты: первый существующий штатный путь, иначе имя для PATH. */
@@ -42,4 +42,9 @@ export declare function command(argv: string[], cwd: string, options?: {
42
42
  * исполняемые настройки сняты. Один путь для всех вызовов git хоста.
43
43
  */
44
44
  export declare function hostGitArgs(cwd: string, args: string[]): string[];
45
+ /**
46
+ * Вывод git целиком. `git` хранит только хвост вывода (предел `command`): для
47
+ * содержимого файла, которое разбирают, усечение незаметно и опасно.
48
+ */
49
+ export declare function gitOutput(cwd: string, ...args: string[]): Promise<string>;
45
50
  export declare function git(cwd: string, ...args: string[]): Promise<string>;