@dzhechkov/p-replicator 1.10.4 → 1.13.1

package/templates/.claude/hooks/check-source-version.cjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * check-source-version.cjs — правка и вывод объявляют ВЕРСИЮ источника, на которой построены?
+ *
+ * NOT an event hook. Like its ten siblings in this directory it is a plain Node utility; nothing
+ * registers it in settings.json, because this package's hooks are NON-BLOCKING by contract (pinned
+ * by tests/unit/hooks-project-anchored.test.js, which requires exit 0) — a hook could only print, it
+ * could never refuse. Invoke it:
+ *
+ *   node .claude/hooks/check-source-version.cjs [path-to-project]
+ *
+ * WHAT IS ALREADY PRESCRIBED, AND IS NOT RE-OPENED HERE. The half «take the status from the FILE,
+ * not from the worker's narrative» is already required: the coordinator checks each receipt for
+ * existence, non-emptiness and mtime freshness before merging, and the decisive field diagnosis
+ * there was an `ls -la` comparing mtimes taken BEFORE the run. That half stands. This file adds the
+ * one it does not reach.
+ *
+ * THE UNCOVERED HALF: FRESHNESS IS CHECKED ON THE RECEIPT, NEVER ON THE SOURCE THE RECEIPT WAS
+ * DERIVED FROM.
+ *
+ * A read copy is a snapshot of the MOMENT OF READING, not of the file. So an edit addressed by a
+ * literal string is a race BY CONSTRUCTION: read at T1, the file changes at T2, write at T3 against
+ * a string that no longer exists — or, worse, that now means something else. The field case is
+ * exact: an edit to `Refinement.md` died on an assertion because a worker had renumbered the guards
+ * between the read and the write. And the symmetric case is quieter and worse: three reports saying
+ * «the defect is still there» were written from stale copies, and each report was itself perfectly
+ * FRESH. A freshness check on the receipt cannot see that — it answers a neighbouring question and
+ * hands the answer over as if it were the asked one.
+ *
+ * WHY A HASH AND NOT AN INSTRUCTION. The obvious cure — a rule saying «re-read immediately before
+ * editing» — is UNVERIFIABLE, and that is not a quibble: inspecting the finished file cannot show
+ * whether a re-read happened, so the rule's failure is silent, which puts it on the weakest layer of
+ * this package's own ladder. A DECLARED VERSION is checkable by anyone at any later time. The
+ * promise is not; that is the whole argument for this shape.
+ *
+ * WHY A MISMATCH IS A REFUSAL WITHOUT MUTATION. When the declared version and the live file
+ * disagree, the correct action is to STOP — not to apply the edit against the newer text and hope.
+ * This checker embodies that literally: it never writes anything, anywhere. It reads, it decides,
+ * it exits. «Отказ без мутации» is a property of the tool, not an instruction to its user.
+ *
+ * WHAT THIS FILE CAN AND CANNOT DECIDE — read before trusting exit 0.
+ *
+ * It settles that every declared edit and every declared verdict names a source that EXISTS and
+ * whose live sha256 EQUALS the recorded one — that is, that nothing the run's conclusions rest on
+ * has moved since those conclusions were drawn. It does NOT decide whether the conclusion follows
+ * from the source, nor whether the worker really re-read anything: a matching hash proves the ground
+ * did not move, never that the reasoning standing on it is right. That stays layer 3.
+ *
+ * THE EXACT FORM OF `docs/source-versions.md` — kept here on purpose: this file is not part of the
+ * always-loaded corpus, so the long form costs nothing per run.
+ *
+ *   **Правки и выводы:** да              (да | нет — `нет` is a legitimate answer)
+ *   **Проверка версий:** ВЫПОЛНЕНА       (ВЫПОЛНЕНА | НЕ ВЫПОЛНЕНА)
+ *   **Причина:** —                       (required when НЕ ВЫПОЛНЕНА; one of the closed REASONS)
+ *
+ *   ## Выводы и правки
+ *
+ *   | Что | Вид | Источник | Хеш источника |
+ *   |---|---|---|---|
+ *   | перенумеровать стражей | правка | docs/Refinement.md | <64 hex> |
+ *   | дефект F1 всё ещё жив   | вывод  | docs/Refinement.md | <64 hex> |
+ *
+ * Exit codes — three, and the third is the point:
+ *   0  every edit and every verdict names a source that exists and still hashes to the declared
+ *      value
+ *   1  a defect is PROVEN and named: a declared version that no longer matches the live file (the
+ *      race, caught before the write), a source that does not exist, a row with no source or no
+ *      hash, or an empty table under «Правки и выводы: да»
+ *   2  THE CHECK DID NOT RUN — no declaration file, an unrecognised value, a malformed hash,
+ *      duplicate rows, or the legitimate answers «правок и выводов нет» and «проверка НЕ
+ *      ВЫПОЛНЕНА, причина такая-то»
+ *
+ * A checker that answers "clean" when it could not look converts an unknown into a reassurance.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DECL = path.join('docs', 'source-versions.md');
+
+/** Are there edits or verdicts to answer for? A CLOSED set — `нет` is legitimate and exits 2. */
+const HAS_WORK = { 'ДА': true, 'НЕТ': false };
+
+/** Was the version review performed? CLOSED, and the negative answer is honest, not a failure —
+ *  `honest-configuration` CFG-I4: an unreachable truth yields UNKNOWN, never a plausible value. */
+const RUN_STATUS = { 'ВЫПОЛНЕНА': 'done', 'НЕ ВЫПОЛНЕНА': 'not-done' };
+
+/**
+ * Why versions were not settled. CLOSED list — each entry names a DIFFERENT repair:
+ *   источник-не-назван   — the edits exist but nobody recorded what they were built on
+ *   источник-недоступен  — the source is outside this tree; get it, then pin it
+ *   решение-отложено     — take the decision (this is the one that becomes a lost update)
+ *   вне-объёма           — decide it is out of scope and record the decision
+ */
+const REASONS = ['источник-не-назван', 'источник-недоступен', 'решение-отложено', 'вне-объёма'];
+
+/**
+ * What a row is. CLOSED, and the two halves are kept apart on purpose: an EDIT mutates a file and a
+ * VERDICT only asserts, but both are built on a snapshot and both are wrong in the same way when
+ * the snapshot has aged. The field case produced one of each — a failed edit, and three reports
+ * that were themselves perfectly fresh while their source was not.
+ */
+const KIND = { 'правка': 'edit', 'вывод': 'verdict' };
+
+const HEX64 = /^[0-9a-f]{64}$/i;
+
+function say(s) { process.stdout.write(s + '\n'); }
+
+/** Exit 2 with a reason. Never merged with "clean": not-run and not-violated are different facts. */
+function cannotCheck(reason, hint) {
+  say('⚠️  проверка НЕ выполнена: ' + reason);
+  if (hint) say('    ' + hint);
+  process.exit(2);
+}
+
+/** Exit 1 with the defect NAMED. A violation that cannot be named is a 2, not a 1. */
+function proven(title, lines, tail) {
+  say('❌ ' + title);
+  for (const line of lines) say('   • ' + line);
+  if (tail) say('   ' + tail);
+  process.exit(1);
+}
+
+/** The value of a `**Label:** value` header line, or null when the label is absent entirely. */
+function header(text, label) {
+  const re = new RegExp('^\\s*\\*\\*' + label + ':?\\*\\*\\s*:?(.*)$', 'im');
+  const m = re.exec(text);
+  if (!m) return null;
+  return m[1].trim().replace(/^[«"`]|[»"`]$/g, '').trim();
+}
+
+/** A header value read against a CLOSED map, with both failure modes kept apart. */
+function closedHeader(text, label, map, what) {
+  const raw = header(text, label);
+  if (raw === null) {
+    cannotCheck('в объявлении нет строки `**' + label + ':**`',
+      what + ' — допустимы ровно: ' + Object.keys(map).join(' | '));
+  }
+  const key = raw.toUpperCase().replace(/\s+/g, ' ').trim();
+  if (!Object.prototype.hasOwnProperty.call(map, key)) {
+    cannotCheck('нераспознанное значение `' + label + '`: ' + (key === '' ? '(пусто)' : key),
+      'допустимы ровно: ' + Object.keys(map).join(' | '));
+  }
+  return map[key];
+}
+
+/**
+ * The declaration table.
+ *
+ * A row is a markdown table row with at least four cells whose SECOND cell is one of the two kinds —
+ * so the header row and the `|---|` separator cannot be mistaken for data, and a row whose kind is
+ * misspelled is REPORTED rather than silently dropped. Dropping it silently would be the same class
+ * of defect the whole file is about: an unread declaration is indistinguishable from an absent one.
+ */
+function declRows(text) {
+  const rows = [];
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line.startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    if (cells.length < 6) continue;                    // '' + 4 columns + ''
+    const what = cells[1];
+    if (!what || /^:?-+:?$/.test(what) || what.toLowerCase() === 'что') continue;
+    rows.push({
+      what,
+      kind: cells[2].toLowerCase(),
+      source: cells[3].replace(/^[`«"]|[`»"]$/g, '').trim(),
+      hash: cells[4].replace(/^[`«"]|[`»"]$/g, '').trim(),
+    });
+  }
+  return rows;
+}
+
+function main() {
+  const root = process.argv[2] || '.';
+  try { if (!fs.statSync(root).isDirectory()) cannotCheck('это не каталог: ' + root); }
+  catch { cannotCheck('путь не существует: ' + root); }
+
+  const abs = path.join(root, DECL);
+  let text;
+  try {
+    if (!fs.statSync(abs).isFile()) cannotCheck(DECL + ' существует, но это не файл');
+    text = fs.readFileSync(abs, 'utf-8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      cannotCheck('нет файла ' + DECL,
+        'это значит, что вопрос о версии источника НЕ ЗАДАВАЛСЯ — а НЕ что правки построены на '
+        + 'свежем чтении; прогон без правок и выводов отвечает `**Правки и выводы:** нет`, и это '
+        + 'законный ответ');
+    }
+    cannotCheck('не читается ' + DECL + ': ' + ((e && e.message) || e));
+  }
+
+  // 1. Is there anything built on a source at all? Nothing to pin → 2, never 0.
+  const hasWork = closedHeader(text, 'Правки и выводы', HAS_WORK,
+    'без этой строки «правок не было» неотличимо от «про источники не подумали»');
+  if (!hasWork) {
+    cannotCheck('объявление говорит «Правки и выводы: нет» — ни одна правка и ни один вывод не '
+      + 'построены на прочитанном файле',
+      'это законный ответ, а не нарушение: закреплять версию не на чем');
+  }
+
+  // 2. A named refusal is honest and exits 2.
+  const run = closedHeader(text, 'Проверка версий', RUN_STATUS,
+    'без этой строки «версии не сверяли» неотличимо от «сверили»');
+  if (run === 'not-done') {
+    const raw = header(text, 'Причина');
+    if (raw === null || raw === '') {
+      cannotCheck('проверка версий НЕ ВЫПОЛНЕНА без строки `**Причина:**`',
+        'причина обязательна и берётся из закрытого списка: ' + REASONS.join(' | ')
+        + ' — каждая означает СВОЙ ремонт');
+    }
+    const picked = REASONS.filter((r) => raw.includes(r));
+    if (picked.length !== 1) {
+      cannotCheck('причина «' + raw + '» не из закрытого списка (или названо сразу несколько)',
+        'допустимы ровно: ' + REASONS.join(' | '));
+    }
+    cannotCheck('проверка версий НЕ ВЫПОЛНЕНА, причина: ' + picked[0],
+      'честное «неизвестно», а не «правки построены на актуальном чтении»; пока причина не '
+      + 'закрыта, свежая квитанция может добросовестно излагать выводы из устаревшего источника');
+  }
+
+  // 3. The rows.
+  const rows = declRows(text);
+  if (rows.length === 0) {
+    proven('объявлены правки и выводы, но ни один не назван',
+      ['таблица `## Выводы и правки` пуста'],
+      'нельзя сверить версию источника у правки, которой нет в списке. Пустая таблица под «да» — '
+      + 'доказанный пропуск, а не неизвестность.');
+  }
+  const keys = rows.map((r) => (r.what + '|' + r.source).toLowerCase());
+  const dupes = [...new Set(keys.filter((k, i) => keys.indexOf(k) !== i))];
+  if (dupes.length) {
+    cannotCheck('в таблице повторяются строки: ' + dupes.join(', '),
+      'одна правка над одним источником — одна строка; иначе одна сверка закрывает две разные');
+  }
+  const badKind = rows.filter((r) => !Object.prototype.hasOwnProperty.call(KIND, r.kind));
+  if (badKind.length) {
+    cannotCheck('нераспознанный `Вид`: '
+      + badKind.map((r) => r.what + ' → ' + (r.kind || '(пусто)')).join(', '),
+      'допустимы ровно: ' + Object.keys(KIND).join(' | ')
+      + ' — правка меняет файл, вывод утверждает о нём, и устаревают они одинаково');
+  }
+
+  const noSource = rows.filter((r) => !r.source || r.source === '—');
+  if (noSource.length) {
+    proven('источник не назван', noSource.map((r) => r.what),
+      'правка или вывод, не назвавшие файл, на котором построены, не могут быть сверены НИКОГДА: '
+      + 'проверять нечего, а выглядит это как проверенное.');
+  }
+  const noHash = rows.filter((r) => !r.hash || r.hash === '—');
+  if (noHash.length) {
+    proven('версия источника не записана', noHash.map((r) => r.what + ' ← ' + r.source),
+      'без записанной версии «источник не менялся» и «источник переписали после чтения» '
+      + 'выглядят одинаково: путь остаётся тем же в обоих случаях. Обещание перечитать проверить '
+      + 'нельзя, записанный хеш — можно.');
+  }
+  const malformed = rows.filter((r) => !HEX64.test(r.hash));
+  if (malformed.length) {
+    cannotCheck('`Хеш источника` не похож на sha256: '
+      + malformed.map((r) => r.what + ' → ' + r.hash).join(', '),
+      'нужны ровно 64 шестнадцатеричных знака — `sha256sum <источник>`');
+  }
+
+  // 4. THE LOAD-BEARING CHECK. Compare each declared version against the live file. Nothing is
+  //    written here, by construction: a mismatch is a refusal, and a refusal does not mutate.
+  const missing = [];
+  const moved = [];
+  for (const row of rows) {
+    const src = path.join(root, row.source);
+    let bytes;
+    try {
+      if (!fs.statSync(src).isFile()) { missing.push(row.what + ' ← ' + row.source); continue; }
+      bytes = fs.readFileSync(src);
+    } catch { missing.push(row.what + ' ← ' + row.source); continue; }
+    const live = crypto.createHash('sha256').update(bytes).digest('hex');
+    if (live.toLowerCase() !== row.hash.toLowerCase()) {
+      moved.push(row.what + ' (' + KIND[row.kind] + ') ← ' + row.source
+        + ': объявлено ' + row.hash.toLowerCase().slice(0, 12) + '…, на диске ' + live.slice(0, 12) + '…');
+    }
+  }
+  if (missing.length) {
+    proven('источник назван, но его нет на диске', missing,
+      'ссылка указывает в пустоту, а правка при этом объявлена построенной на нём.');
+  }
+  if (moved.length) {
+    proven('источник изменился после чтения — правка ОТКЛОНЕНА, мутации нет', moved,
+      'прочитанная копия — снимок МОМЕНТА ЧТЕНИЯ, а не состояния файла: между чтением и записью '
+      + 'источник переписали, и правка по литеральной строке попала бы либо мимо, либо в текст, '
+      + 'который теперь значит другое. Симметрично и тише: свежий отчёт может добросовестно '
+      + 'излагать вывод из устаревшего источника — квитанция при этом свежа, и её проверка '
+      + 'отвечает не на тот вопрос. Перечитайте источник, перезапишите хеш и постройте правку '
+      + 'заново — не применяйте её к новому тексту.');
+  }
+
+  const edits = rows.filter((r) => KIND[r.kind] === 'edit').length;
+  say('✅ ' + rows.length + ' объявлени(й) сверено с диском: ' + edits + ' правк(и), '
+    + (rows.length - edits) + ' вывод(ов) — каждый источник на месте и не изменился с момента чтения');
+  say('   Ограничение: совпавший хеш доказывает, что почва НЕ СДВИНУЛАСЬ, — но не то, что вывод из '
+    + 'неё следует и не то, что кто-то действительно перечитал файл. Это остаётся слоем 3.');
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  // Even an unexpected failure must not read as "clean".
+  cannotCheck('внутренняя ошибка проверки: ' + String((err && err.message) || err));
+}

package/templates/.claude/hooks/check-swarm-receipts.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * check-swarm-receipts.cjs — did the parallel work units actually DELIVER, or is the coordinator
+ * about to aggregate silence?
+ *
+ * THE FAILURE THIS EXISTS FOR. A worker that died looks exactly like a worker that is still
+ * running: both are silent. Silence therefore reads as "in progress", and a coordinator can
+ * report in good faith that the review is running when no review exists. The cure is to make the
+ * RESULT of every unit a FILE at a named path: no file, no work — and that is a fact a machine can
+ * establish, not a feeling a reader has to trust. This utility is that machine.
+ *
+ * NOT an event hook. Like `check-ports.cjs`, `check-growth-trace.cjs` and `check-look-trace.cjs`,
+ * it lives here because this directory already carries plain Node utilities; nothing registers it
+ * in settings.json. That is deliberate and load-bearing: this package's hooks are NON-BLOCKING by
+ * contract (pinned by tests/unit/hooks-project-anchored.test.js, which requires exit 0), so a hook
+ * could never refuse anything — it could only print. Invoke it:
+ *
+ *   node .claude/hooks/check-swarm-receipts.cjs <path-to-receipts-manifest.json>
+ *
+ * Exit codes — three, and the third is the point:
+ *   0  every required receipt is a fresh, substantive, terminal file ending `Status: completed`
+ *   1  at least one unit is UNDELIVERED or delivered a `Status: failed` — refuse aggregation
+ *   2  THE CHECK DID NOT RUN — no manifest, malformed assignment, or an inconclusive probe
+ *
+ * A checker that answers "clean" when it could not look converts an unknown into a reassurance,
+ * which is the same substitution the whole contract exists to refuse. So an unreadable trace is
+ * exit 2, never 0; and a missing trace whose worker PID is still ALIVE is exit 2 as well — a live
+ * worker may extend waiting, but liveness has never been delivery.
+ *
+ * MANIFEST SHAPE (the coordinator writes it BEFORE dispatch, which is what makes freshness
+ * checkable at all — `launchMs` has to be recorded before the workers can write):
+ *
+ *   {
+ *     "runId":    "<run-unique id>",
+ *     "launchMs": 1756728000000,          // Date.now() captured immediately before dispatch
+ *     "units": [
+ *       { "workUnitId": "api",  "tracePath": "/abs/path/api.md",  "pid": 12345 },
+ *       { "workUnitId": "docs", "tracePath": "/abs/path/docs.md" }
+ *     ]
+ *   }
+ *
+ * `pid` is optional and can only ever move an ABSENT trace between "undelivered" and "still
+ * waiting". It can never turn a missing file into a delivery.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TERMINAL = /^Status: (completed|failed)$/;
+
+function say(s) { process.stdout.write(s + '\n'); }
+
+/** Exit 2 with a reason. Never merged with "clean": not-run and not-violated are different facts. */
+function cannotCheck(reason, hint) {
+  say('⚠️  проверка НЕ выполнена: ' + reason);
+  if (hint) say('    ' + hint);
+  process.exit(2);
+}
+
+/**
+ * Is the worker behind this unit still alive?
+ *
+ * Three answers, because two would be a lie. `signal 0` tells us the process exists (`live`) or is
+ * gone (`dead`); anything else — EPERM on a process we do not own, a malformed pid — is `unknown`,
+ * and an unknown liveness must never be read as either.
+ */
+function liveness(pid) {
+  if (pid === undefined || pid === null) return 'unknown';
+  if (!Number.isInteger(pid) || pid <= 0) return 'unknown';
+  try { process.kill(pid, 0); return 'live'; } catch (e) {
+    return e && e.code === 'ESRCH' ? 'dead' : 'unknown';
+  }
+}
+
+/**
+ * The whole verdict for ONE unit, as a state plus a reason.
+ *
+ * The order of the checks is the contract, not a convenience. Assignment first: a relative or
+ * duplicated `TRACE_PATH` means the DISPATCH was wrong, and a wrong dispatch cannot produce a
+ * meaningful verdict about delivery. Then existence, then regular-file, then freshness, then
+ * substance, then the terminal marker LAST — because the marker is written last, so a file that
+ * has a body but no marker is a PARTIAL write, not a failure and not a success.
+ */
+function inspectReceipt(unit, launchMs) {
+  const { workUnitId, tracePath } = unit;
+  if (!workUnitId || typeof tracePath !== 'string' || !path.isAbsolute(tracePath)) {
+    return { state: 'inconclusive', reason: 'assignment' };
+  }
+  const alive = liveness(unit.pid);
+  let stat;
+  try { stat = fs.lstatSync(tracePath); } catch (error) {
+    if (error.code !== 'ENOENT') return { state: 'inconclusive', reason: 'unreadable' };
+    // A live worker may only EXTEND waiting. It can never stand in for the file.
+    if (alive === 'live') return { state: 'waiting', reason: 'positive-liveness-only' };
+    return { state: 'undelivered', reason: alive === 'dead' ? 'dead-worker' : 'missing' };
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) return { state: 'undelivered', reason: 'not-regular' };
+  if (stat.mtimeMs <= launchMs) return { state: 'undelivered', reason: 'stale' };
+  let body;
+  try { body = fs.readFileSync(tracePath, 'utf-8'); } catch { return { state: 'inconclusive', reason: 'unreadable' }; }
+  // Whitespace is exactly as empty as nothing. A size check alone would pass a lone newline.
+  if (!body.trim()) return { state: 'undelivered', reason: 'empty' };
+  const lines = body.trimEnd().split(/\r?\n/);
+  const terminal = lines.at(-1);
+  if (!TERMINAL.test(terminal)) return { state: 'undelivered', reason: 'non-terminal' };
+  // A marker with nothing above it is a receipt for no work.
+  if (!lines.slice(0, -1).join('\n').trim()) return { state: 'undelivered', reason: 'empty-payload' };
+  return terminal === 'Status: completed'
+    ? { state: 'completed', reason: 'terminal-receipt' }
+    : { state: 'failed', reason: 'delivered-failure' };
+}
+
+function readManifest(file) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf-8'); } catch {
+    cannotCheck('не читается манифест квитанций: ' + file,
+      'манифест пишет КООРДИНАТОР до диспатча — его отсутствие значит, что рой запускали без учёта, '
+      + 'а не что все отчитались');
+  }
+  let manifest;
+  try { manifest = JSON.parse(raw); } catch (e) {
+    cannotCheck('манифест не разбирается как JSON: ' + ((e && e.message) || e));
+  }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    cannotCheck('манифест не является объектом');
+  }
+  if (!Number.isFinite(manifest.launchMs)) {
+    cannotCheck('в манифесте нет числового launchMs',
+      'без момента запуска нельзя отличить свежий след от файла, лежавшего здесь до роя');
+  }
+  const units = Array.isArray(manifest.units) ? manifest.units : null;
+  if (!units) cannotCheck('в манифесте нет массива units');
+  if (!units.length) {
+    cannotCheck('в манифесте ноль рабочих единиц',
+      'пустой рой нечего проверять — сказать «всё чисто» значило бы отчитаться о проверке, '
+      + 'которой не было');
+  }
+  const ids = units.map((u) => u && u.workUnitId);
+  const paths = units.map((u) => u && u.tracePath);
+  const dupeIds = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))];
+  if (dupeIds.length) {
+    cannotCheck('WORK_UNIT_ID повторяется: ' + dupeIds.join(', '),
+      'один идентификатор на две единицы — одна квитанция зачлась бы за обе');
+  }
+  const dupePaths = [...new Set(paths.filter((p, i) => paths.indexOf(p) !== i))];
+  if (dupePaths.length) {
+    cannotCheck('TRACE_PATH повторяется: ' + dupePaths.join(', '),
+      'два работника на один путь — второй перезапишет первого, и потеря будет молчаливой');
+  }
+  return manifest;
+}
+
+function main() {
+  const file = process.argv[2];
+  if (!file) {
+    cannotCheck('не передан путь к манифесту квитанций',
+      'использование: node .claude/hooks/check-swarm-receipts.cjs <manifest.json>');
+  }
+  const manifest = readManifest(file);
+  const results = manifest.units.map((unit) => ({ unit, verdict: inspectReceipt(unit, manifest.launchMs) }));
+
+  const bad = results.filter((r) => r.verdict.state === 'undelivered' || r.verdict.state === 'failed');
+  const unknown = results.filter((r) => r.verdict.state === 'inconclusive' || r.verdict.state === 'waiting');
+  const ok = results.filter((r) => r.verdict.state === 'completed');
+
+  const line = (r) => '   • ' + (r.unit.workUnitId || '<без WORK_UNIT_ID>') + ' [' + r.verdict.state
+    + '/' + r.verdict.reason + '] ' + (r.unit.tracePath || '<без TRACE_PATH>');
+
+  if (bad.length) {
+    say('❌ квитанции не собраны: ' + ok.length + ' из ' + results.length + ' завершены');
+    for (const r of bad) say(line(r));
+    for (const r of unknown) say(line(r));
+    say('   Сведение, синтез и завершение ЗАПРЕЩЕНЫ, пока каждая требуемая квитанция не '
+      + 'terminal-completed. Доклад агента — не квитанция; тишина — не прогресс.');
+    process.exit(1);
+  }
+  if (unknown.length) {
+    say('⚠️  проверка НЕ выполнена: ' + unknown.length + ' из ' + results.length
+      + ' единиц не дали определённого ответа');
+    for (const r of unknown) say(line(r));
+    say('    Живой PID продлевает ожидание, но не заменяет файл; нечитаемый след — неизвестность, '
+      + 'а не успех. Дождитесь следа или диагностируйте единицу и перезапустите проверку.');
+    process.exit(2);
+  }
+  say('✅ все ' + results.length + ' квитанций свежие, содержательные и завершены Status: completed');
+  say('   Ограничение: это доказывает, что работа ДОСТАВЛЕНА, а не что она верна.');
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  // Even an unexpected failure must not read as "clean".
+  cannotCheck('внутренняя ошибка проверки: ' + String((err && err.message) || err));
+}