@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/drive-metrics.js

@@ -0,0 +1,691 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash, randomBytes } = require('node:crypto');
+const guards = require("./guards");
+const { isRecord, isEnoentError } = guards;
+/**
+ * drive 계측 기록(`.bouncer/runtime/drive-metrics.json`)의 읽기·쓰기·요약.
+ *
+ * 원칙: 호스트가 준 값만 기록한다. 토큰·시간·비용을 추정해 채우지 않고, 얻지 못한 값은
+ * `null`과 사유 문자열로 남겨 합계가 누락을 0으로 세지 않게 한다. 원장은 읽기만 하며
+ * 기록 파일 쓰기는 임시 파일 뒤 rename이다.
+ */
+const SESSION_KINDS = ['coordinator-session', 'context-review', 'root-direct-session'];
+// 이 kind의 decision, 또는 outcome이 accepted가 아닌 report는 "예외 판단"이다.
+const EXCEPTION_KINDS = new Set([
+    'stale-report', 'stale-lease', 'repair', 'supplement', 'rerecord',
+    'critical-recovery', 'fanin-verification-failed', 'revoke',
+]);
+/**
+ * 기록 파일의 절대 경로. runtime 디렉터리는 gitignore라 기록이 커밋에 섞이지 않는다.
+ *
+ * @param {string} mainRoot - main worktree 루트(`runtimePaths().projectRoot`)
+ * @returns {string} drive-metrics.json 절대 경로
+ */
+function metricsFilePath(mainRoot) {
+    return path.join(mainRoot, '.bouncer', 'runtime', 'drive-metrics.json');
+}
+// blueprint 비교용 정규화. 호출자마다 끝 슬래시·역슬래시가 달라도 같은 blueprint로 묶는다.
+function normalizeBlueprint(value) {
+    return value.replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/**
+ * 기록 파일을 읽는다. 파일 없음(ENOENT)만 빈 기록이고, 깨진 JSON·모양 불일치는
+ * `metrics-file-invalid`다 — 거절해야 이후 쓰기가 깨진 파일을 덮어쓰지 않는다.
+ *
+ * @param {string} file - drive-metrics.json 경로
+ * @returns {{ok: true, data: MetricsFile} | Failure} 읽은 기록 또는 거절
+ */
+function readMetrics(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // ENOENT만 "아직 기록 없음". 권한 오류 등은 삼키지 않고 그대로 던진다.
+        if (isEnoentError(error))
+            return { ok: true, data: { version: 1, sessions: [] } };
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_error) {
+        // SyntaxError만 여기로 온다(입력이 문자열). 깨진 파일은 invalid로 접는다.
+        return { ok: false, reason: 'metrics-file-invalid' };
+    }
+    if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.sessions)
+        || !parsed.sessions.every((s) => isRecord(s) && typeof s.id === 'string'
+            && typeof s.kind === 'string' && typeof s.blueprint === 'string')) {
+        return { ok: false, reason: 'metrics-file-invalid' };
+    }
+    return { ok: true, data: parsed };
+}
+// 임시 파일 뒤 rename: 쓰는 도중 중단돼도 기존 기록이 반쯤 쓰인 채 남지 않는다.
+function writeMetrics(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+}
+/**
+ * 원장의 진행 snapshot을 읽는다. 원장은 읽기만 한다. 원장이 아직 없으면 snapshot은 null이고,
+ * 깨진 원장은 진행 차이를 추정하지 않고 `metrics-ledger-invalid`로 거절한다.
+ *
+ * @param {string} ledgerFile - integration worktree의 coordinator.json 경로
+ * @param {SnapshotFs} [fsx] - 읽기 seam. 기본은 node:fs
+ * @returns {LedgerRead} snapshot과 decision 배열, 또는 거절
+ */
+function readLedgerSnapshot(ledgerFile, fsx = fs) {
+    let bytes;
+    try {
+        bytes = fsx.readFileSync(ledgerFile);
+    }
+    catch (error) {
+        if (isEnoentError(error))
+            return { ok: true, snapshot: null, decisions: [] };
+        throw error;
+    }
+    let ledger;
+    try {
+        ledger = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (_error) {
+        return { ok: false, reason: 'metrics-ledger-invalid' };
+    }
+    if (!isRecord(ledger))
+        return { ok: false, reason: 'metrics-ledger-invalid' };
+    const decisions = Array.isArray(ledger.decisions) ? ledger.decisions : [];
+    const tasks = Array.isArray(ledger.tasks) ? ledger.tasks : [];
+    const completed = tasks
+        .filter((t) => isRecord(t) && t.status === 'integrated' && typeof t.id === 'string')
+        .map((t) => t.id);
+    return {
+        ok: true,
+        snapshot: {
+            decisions: decisions.length,
+            completed_tasks: completed,
+            ledger_sha256: createHash('sha256').update(bytes).digest('hex'),
+        },
+        decisions,
+    };
+}
+/**
+ * 원장 항목이 "예외 판단"인지 가른다. 세션 경계 판정(`coordinate next`)과 metrics의
+ * 예외 수 계산이 같은 정의를 쓰도록 export한다.
+ *
+ * @param {unknown} entry - 원장 decision 항목
+ * @returns {boolean} 예외 kind이거나 accepted가 아닌 report면 true
+ */
+function isException(entry) {
+    if (!isRecord(entry))
+        return false;
+    if (typeof entry.kind === 'string' && EXCEPTION_KINDS.has(entry.kind))
+        return true;
+    return entry.kind === 'report' && entry.outcome !== 'accepted';
+}
+/**
+ * 세션 시작을 기록한다. coordinator-session은 그 시점의 원장 snapshot을, context-review는
+ * `target_digest`를 남기고 원장 진행 필드를 만들지 않는다.
+ *
+ * @param {object} opts - 시작 입력
+ * @param {string} opts.file - drive-metrics.json 경로
+ * @param {string} opts.ledgerFile - 해당 blueprint의 integration 원장 경로
+ * @param {string} opts.kind - `coordinator-session` | `context-review` | `root-direct-session`
+ * @param {string} opts.blueprint - blueprint 디렉터리
+ * @param {string} [opts.label] - 세션 라벨(context-review는 perspective)
+ * @param {string} [opts.targetDigest] - context-review 필수 64 hex
+ * @param {Clock} [opts.now] - 테스트 seam. 기본 현재 시각
+ * @param {() => string} [opts.randomId] - 테스트 seam. 16 hex를 돌려준다
+ * @returns {{ok: true, id: string} | Failure} 새 세션 id 또는 거절 사유
+ */
+function startSession(opts) {
+    const now = opts.now ?? (() => new Date());
+    const randomId = opts.randomId ?? (() => randomBytes(8).toString('hex'));
+    const invalid = { ok: false, reason: 'invalid-metrics-input' };
+    if (!SESSION_KINDS.includes(opts.kind)
+        || typeof opts.blueprint !== 'string' || opts.blueprint === '')
+        return invalid;
+    const kind = opts.kind;
+    const isReview = kind === 'context-review';
+    // target-digest는 context-review의 호출 식별자다. 다른 kind에 주면 오타 가능성이 커서 거절한다.
+    if (isReview !== (opts.targetDigest !== undefined))
+        return invalid;
+    if (isReview && !/^[a-f0-9]{64}$/.test(opts.targetDigest))
+        return invalid;
+    // 깨진 기록 파일은 어떤 쓰기보다 먼저 거절한다.
+    const current = readMetrics(opts.file);
+    if (current.ok === false)
+        return current;
+    const session = {
+        id: `m-${randomId()}`,
+        kind,
+        blueprint: normalizeBlueprint(opts.blueprint),
+        label: opts.label ?? null,
+        started_at: now().toISOString(),
+        ended_at: null,
+    };
+    if (isReview) {
+        session.target_digest = opts.targetDigest;
+    }
+    else {
+        const ledger = readLedgerSnapshot(opts.ledgerFile);
+        if (ledger.ok === false)
+            return ledger;
+        session.start = ledger.snapshot;
+    }
+    current.data.sessions.push(session);
+    writeMetrics(opts.file, current.data);
+    return { ok: true, id: session.id };
+}
+// 비용은 호스트가 준 모델·입출력 토큰과 설정 단가가 모두 있을 때만 계산한다.
+function computeCost(model, input, output, pricing) {
+    if (model === null)
+        return { cost: null, reason: 'no-model' };
+    if (input === null || output === null)
+        return { cost: null, reason: 'no-token-split' };
+    if (pricing === null)
+        return { cost: null, reason: 'invalid-pricing' };
+    if (!Object.hasOwn(pricing, model))
+        return { cost: null, reason: 'no-pricing' };
+    const price = pricing[model];
+    return { cost: (input / 1e6) * price.input_per_mtok + (output / 1e6) * price.output_per_mtok };
+}
+/**
+ * 세션 종료를 기록한다. 호스트가 준 토큰·시간만 쓰고, 없으면 `null`과 사유를 남긴다.
+ *
+ * @param {object} opts - 종료 입력
+ * @param {string} opts.file - drive-metrics.json 경로
+ * @param {(blueprint: string) => string | null} opts.resolveLedger - 세션 blueprint의 integration 원장 경로.
+ *   null이면 기록된 blueprint를 경로로 풀 수 없다는 뜻이라 기록 파일 손상으로 거절한다
+ * @param {string} opts.id - start가 돌려준 세션 id
+ * @param {number} [opts.tokens] - 호스트가 준 총 토큰
+ * @param {number} [opts.inputTokens] - 호스트가 준 입력 토큰
+ * @param {number} [opts.outputTokens] - 호스트가 준 출력 토큰
+ * @param {number} [opts.cacheReadTokens] - 호스트가 준 cache read 토큰(독립 필드, 총합·비용에 안 더함)
+ * @param {number} [opts.cacheWriteTokens] - 호스트가 준 cache write 토큰(독립 필드, 총합·비용에 안 더함)
+ * @param {string} [opts.model] - 모델 slug
+ * @param {number} [opts.hostDurationMs] - 호스트가 준 소요 시간
+ * @param {PricingTable | null} opts.pricing - 단가 표. 깨진 설정이면 null
+ * @param {Clock} [opts.now] - 테스트 seam
+ * @returns {{ok: true} | Failure} 성공 또는 거절 사유
+ */
+function endSession(opts) {
+    const now = opts.now ?? (() => new Date());
+    const current = readMetrics(opts.file);
+    if (current.ok === false)
+        return current;
+    const session = current.data.sessions.find((s) => s.id === opts.id);
+    if (!session)
+        return { ok: false, reason: 'metrics-session-not-found' };
+    if (session.ended_at !== null)
+        return { ok: false, reason: 'metrics-session-ended' };
+    const endedAt = now();
+    session.ended_at = endedAt.toISOString();
+    session.wall_ms = Math.max(0, endedAt.getTime() - Date.parse(session.started_at));
+    session.host_duration_ms = opts.hostDurationMs ?? null;
+    session.model = opts.model ?? null;
+    session.input_tokens = opts.inputTokens ?? null;
+    session.output_tokens = opts.outputTokens ?? null;
+    // 총합은 호스트가 준 --tokens를 우선하고, 없을 때만 입출력이 둘 다 있으면 그 합이다(추정 아님).
+    session.tokens = opts.tokens
+        ?? (opts.inputTokens !== undefined && opts.outputTokens !== undefined
+            ? opts.inputTokens + opts.outputTokens : null);
+    if (session.tokens === null)
+        session.tokens_unavailable_reason = 'not-reported';
+    // cache는 호스트가 준 값만 쓴다. 둘 다 없을 때만 사유를 남기고, 하나라도 있으면 사유 키를 쓰지 않는다.
+    session.cache_read_tokens = opts.cacheReadTokens ?? null;
+    session.cache_write_tokens = opts.cacheWriteTokens ?? null;
+    if (session.cache_read_tokens === null && session.cache_write_tokens === null) {
+        session.cache_unavailable_reason = 'not-reported';
+    }
+    const cost = computeCost(session.model, session.input_tokens, session.output_tokens, opts.pricing);
+    session.cost = cost.cost;
+    if (cost.reason !== undefined)
+        session.cost_unavailable_reason = cost.reason;
+    if (session.kind === 'coordinator-session') {
+        const ledgerFile = opts.resolveLedger(session.blueprint);
+        if (ledgerFile === null)
+            return { ok: false, reason: 'metrics-file-invalid' };
+        const ledger = readLedgerSnapshot(ledgerFile);
+        if (ledger.ok === false)
+            return ledger;
+        session.end = ledger.snapshot;
+        if (ledger.snapshot === null) {
+            session.tasks_completed = null;
+            session.exception_decisions = null;
+        }
+        else {
+            const before = new Set(session.start?.completed_tasks ?? []);
+            session.tasks_completed = ledger.snapshot.completed_tasks.filter((id) => !before.has(id));
+            session.exception_decisions = ledger.decisions
+                .slice(session.start?.decisions ?? 0).filter(isException).length;
+        }
+    }
+    writeMetrics(opts.file, current.data);
+    return { ok: true, id: session.id };
+}
+/**
+ * 관측값 하나를 kind 합계에 반영한다. 숫자(명시적 0 포함)만 더하고, `null`·필드 부재(legacy 기록)는
+ * 합에 넣지 않고 missing으로 센다. 누락을 0으로 접으면 측정 못 한 세션이 값 0처럼 읽히기 때문이다.
+ * 첫 관측값이 들어올 때 total이 null에서 숫자로 바뀐다.
+ *
+ * @param {KindSummary} sum - 갱신할 kind 합계
+ * @param {TotalKey} totalKey - 합계 필드
+ * @param {MissingKey} missingKey - 누락 수 필드
+ * @param {unknown} value - 세션에 기록된 값
+ * @returns {void}
+ */
+function observe(sum, totalKey, missingKey, value) {
+    if (typeof value === 'number')
+        sum[totalKey] = (sum[totalKey] ?? 0) + value;
+    else
+        sum[missingKey] += 1;
+}
+/**
+ * blueprint의 kind별 합계. 끝난 세션만 토큰·시간·비용에 합산하고, `null`은 합에서 빼
+ * 누락 수로 따로 센다. 0으로 세면 측정하지 못한 세션이 값이 0인 세션처럼 읽힌다.
+ *
+ * @param {{file: string, blueprint: string, resolveLedger?: Function}} opts - 기록 파일, blueprint,
+ *   원장 경로 해석기 `(blueprint) => string | null`(주입)
+ * 토큰(total·input·output)·host 소요 시간·wall 시간은 관측값이 하나도 없으면 total이 `null`이고,
+ * 일부만 있으면 알려진 합과 `*_missing`을 함께 낸다. cost_total은 기존 입력 호환으로 0 시작을 유지한다.
+ * worker_tokens는 원장의 `worker-model`·`worker-tokens` decision에서 따로 합산한다. coordinator
+ * 총량에 이미 포함됐는지 알 수 없으므로 `kinds`에 더하지 않는다. 원장이 없거나 resolveLedger가
+ * 없으면 0이고, 깨진 원장은 `metrics-ledger-invalid`로 거절한다. 원장 파일이 없으면 정리 전에 저장한
+ * snapshot(`commonGitDir` 아래)으로 복원하고, 그것도 없을 때만 0이다. 출처는 `worker_tokens_source`
+ * (`ledger`|`snapshot`|`unavailable`)로 구별해 복원값과 실제 0이 섞이지 않게 한다.
+ * cache read·write는 kind와 무관하게 blueprint 전체 합을 최상위 `cache`에 낸다. 숫자만 합산하고
+ * `null`·필드 부재(필드가 생기기 전 기록)는 `missing`으로 센다. `0`은 값이다.
+ *
+ * @returns {{ok: true, blueprint: string, kinds: Record<string, KindSummary>, cache: CacheSummary} | Failure} 합계 또는 거절
+ */
+function summarize(opts) {
+    const current = readMetrics(opts.file);
+    if (current.ok === false)
+        return current;
+    const blueprint = normalizeBlueprint(opts.blueprint);
+    const kinds = {};
+    for (const kind of SESSION_KINDS) {
+        kinds[kind] = {
+            sessions: 0, open: 0, tokens_total: null, tokens_missing: 0,
+            input_tokens_total: null, input_tokens_missing: 0,
+            output_tokens_total: null, output_tokens_missing: 0,
+            host_duration_ms_total: null, host_duration_ms_missing: 0,
+            wall_ms_total: null, wall_ms_missing: 0, cost_total: 0, cost_missing: 0,
+        };
+        if (kind === 'coordinator-session')
+            kinds[kind].tasks_completed = 0;
+    }
+    const cache = { read: { total: 0, missing: 0 }, write: { total: 0, missing: 0 } };
+    for (const s of current.data.sessions) {
+        if (s.blueprint !== blueprint || !Object.hasOwn(kinds, s.kind))
+            continue;
+        const sum = kinds[s.kind];
+        sum.sessions += 1;
+        if (s.ended_at === null) {
+            sum.open += 1;
+            continue;
+        }
+        observe(sum, 'tokens_total', 'tokens_missing', s.tokens);
+        observe(sum, 'input_tokens_total', 'input_tokens_missing', s.input_tokens);
+        observe(sum, 'output_tokens_total', 'output_tokens_missing', s.output_tokens);
+        // 호스트가 준 소요 시간과 직접 잰 wall time은 출처가 달라 서로 대신 채우지 않는다.
+        observe(sum, 'host_duration_ms_total', 'host_duration_ms_missing', s.host_duration_ms);
+        observe(sum, 'wall_ms_total', 'wall_ms_missing', s.wall_ms);
+        if (typeof s.cache_read_tokens === 'number')
+            cache.read.total += s.cache_read_tokens;
+        else
+            cache.read.missing += 1;
+        if (typeof s.cache_write_tokens === 'number')
+            cache.write.total += s.cache_write_tokens;
+        else
+            cache.write.missing += 1;
+        if (typeof s.cost === 'number')
+            sum.cost_total += s.cost;
+        else
+            sum.cost_missing += 1;
+        if (sum.tasks_completed !== undefined && Array.isArray(s.tasks_completed)) {
+            sum.tasks_completed += s.tasks_completed.length;
+        }
+    }
+    const workerTokens = summarizeWorkerTokens(opts.resolveLedger?.(blueprint) ?? null, opts.commonGitDir ?? null, blueprint);
+    if (workerTokens.ok === false)
+        return workerTokens;
+    return {
+        ok: true, blueprint, kinds, cache,
+        worker_tokens: workerTokens.summary, worker_tokens_source: workerTokens.source,
+    };
+}
+const WORKER_ROLES = ['implementer', 'reviewer', 'debugger'];
+function emptyWorkerSummary() {
+    return {
+        total: 0, missing: 0,
+        by_role: {
+            implementer: { total: 0, missing: 0 }, reviewer: { total: 0, missing: 0 },
+            debugger: { total: 0, missing: 0 },
+        },
+    };
+}
+/**
+ * 원장 decision 배열에서 하위 에이전트 토큰을 합산한다. 키 `(task, role, perspective)`마다
+ * `runs`(worker-model 수)와 `reported`(숫자 tokens가 달린 worker-model + worker-tokens 수)를
+ * 세어, 누락은 `max(0, runs - reported)`다. 늦게 온 worker-tokens가 같은 키의 토큰 없는
+ * worker-model을 메우므로 한 호출이 두 번 세이지 않는다. 호스트가 주지 않은 값은 만들지 않는다.
+ *
+ * @param {unknown[]} decisions - 원장 decisions
+ * @returns {WorkerTokensSummary} 합계와 역할별 합계
+ */
+function sumWorkerDecisions(decisions) {
+    const summary = emptyWorkerSummary();
+    const counts = new Map();
+    for (const d of decisions) {
+        if (!isRecord(d) || (d.kind !== 'worker-model' && d.kind !== 'worker-tokens'))
+            continue;
+        const role = WORKER_ROLES.find((r) => r === d.role);
+        if (role === undefined)
+            continue;
+        const key = JSON.stringify([d.task ?? '', role, d.perspective ?? '']);
+        const entry = counts.get(key) ?? { role, runs: 0, reported: 0 };
+        if (d.kind === 'worker-model')
+            entry.runs += 1;
+        if (typeof d.tokens === 'number') {
+            entry.reported += 1;
+            summary.by_role[role].total += d.tokens;
+            summary.total += d.tokens;
+        }
+        counts.set(key, entry);
+    }
+    for (const { role, runs, reported } of counts.values()) {
+        const missing = Math.max(0, runs - reported);
+        summary.by_role[role].missing += missing;
+        summary.missing += missing;
+    }
+    return summary;
+}
+/**
+ * worker 집계의 출처를 정해 합산한다. 우선순위는 live 원장 → 저장 snapshot → unavailable이다.
+ * 원장 파일이 있으면(깨졌으면 거절) 언제나 원장이 이기므로 오래된 snapshot이 live 자료를
+ * 대신하지 않는다. 원장이 없을 때만 snapshot을 읽고, 깨진 snapshot은 0으로 접지 않고 거절한다.
+ *
+ * @param {string | null} ledgerFile - 원장 경로. null이면 원장 없음으로 본다
+ * @param {string | null} commonGitDir - snapshot 저장소가 있는 Git common dir. null이면 snapshot 없음
+ * @param {string} blueprint - 정규화된 blueprint 경로
+ * @returns {{ok: true, summary: WorkerTokensSummary, source: WorkerTokensSource} | Failure}
+ *   합계와 출처, 또는 깨진 원장·snapshot 거절
+ */
+function summarizeWorkerTokens(ledgerFile, commonGitDir, blueprint) {
+    const ledger = ledgerFile === null
+        ? { ok: true, snapshot: null, decisions: [] } : readLedgerSnapshot(ledgerFile);
+    if (ledger.ok === false)
+        return ledger;
+    if (ledger.snapshot !== null) {
+        return { ok: true, summary: sumWorkerDecisions(ledger.decisions), source: 'ledger' };
+    }
+    if (commonGitDir !== null) {
+        const saved = loadWorkerSnapshot({ commonGitDir, blueprint });
+        if (saved.ok === false)
+            return saved;
+        if (saved.snapshot !== null) {
+            return { ok: true, summary: saved.snapshot.worker_tokens, source: 'snapshot' };
+        }
+    }
+    return { ok: true, summary: emptyWorkerSummary(), source: 'unavailable' };
+}
+/**
+ * snapshot 파일 경로. 파일명은 blueprint 경로(UTF-8)의 SHA-256이라 blueprint 문자열이
+ * 경로 조각으로 새지 않는다. 프로젝트 경로가 아니라 Git common dir 아래다 — worktree
+ * 정리와 `git clean`이 지우지 못하는 자리여야 정리 뒤에도 살아남는다.
+ *
+ * @param {string} commonGitDir - `git rev-parse --git-common-dir`의 절대 경로
+ * @param {string} blueprint - blueprint 경로(정규화 전이어도 된다)
+ * @returns {string} snapshot 파일 절대 경로
+ */
+function workerSnapshotPath(commonGitDir, blueprint) {
+    const name = createHash('sha256').update(normalizeBlueprint(blueprint), 'utf8').digest('hex');
+    return path.join(commonGitDir, 'bouncer', 'metrics-snapshots', `${name}.json`);
+}
+// realpath가 상위가 아닌 곳으로 새는지 본다(심볼릭 링크로 common dir 밖을 가리키는 경우).
+function isInsideReal(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+// 파일 시스템 오류(code가 문자열인 Error)인지 가른다. 프로그래밍 오류(TypeError 등)는 I/O 실패로 삼키지 않는다.
+function isFsError(error) {
+    return error instanceof Error && typeof error.code === 'string';
+}
+/**
+ * snapshot 파일 자리가 Git common dir 안쪽이고 파일 자체가 symlink가 아닌지 검사한다.
+ * mkdir 전에도 호출되므로 아직 없는 하위 경로는 "가장 가까운 기존 조상"까지 거슬러 올라가
+ * 그 realpath가 경계 안인지 본다 — 미존재 디렉터리를 이유로 바로 통과시키면 조상이 외부를
+ * 가리키는 symlink일 때 recursive mkdir이 외부에 디렉터리를 만든다. realpath가 ENOENT인데
+ * lstat은 성공하는 조상은 가리키는 곳이 없는(dangling) symlink이므로 안전하지 않다고 본다.
+ * 경계 검사 중의 ENOENT 외 I/O 오류(EACCES 등)는 안전을 확인할 수 없으므로 false이고,
+ * 프로그래밍 오류는 그대로 던진다.
+ *
+ * @param {string} commonGitDir - Git common dir
+ * @param {string} file - workerSnapshotPath 결과
+ * @param {SnapshotFs} [fsx] - 검사 seam. 없는 메서드는 node:fs로 fallback한다
+ * @returns {boolean} 경계 안쪽이고 symlink가 아니면 true
+ */
+function snapshotLocationSafe(commonGitDir, file, fsx = fs) {
+    const realpath = fsx.realpathSync ?? fs.realpathSync;
+    const lstat = fsx.lstatSync ?? fs.lstatSync;
+    try {
+        const base = realpath(commonGitDir);
+        let dir = path.dirname(file);
+        for (;;) {
+            try {
+                return isInsideReal(realpath(dir), base) && !lstatIsSymlink(lstat, file);
+            }
+            catch (error) {
+                if (!isEnoentError(error))
+                    throw error;
+            }
+            // realpath ENOENT: 진짜 없는 조상이면 한 칸 위로, lstat이 성공하면 dangling symlink라 거절.
+            try {
+                lstat(dir);
+                return false;
+            }
+            catch (error) {
+                if (!isEnoentError(error))
+                    throw error;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return false;
+            dir = parent;
+        }
+    }
+    catch (error) {
+        if (isFsError(error))
+            return false;
+        throw error;
+    }
+}
+// 파일이 아직 없는 것(ENOENT)만 "첫 저장"으로 보아 symlink가 아니라고 답한다.
+function lstatIsSymlink(lstat, file) {
+    try {
+        return lstat(file).isSymbolicLink();
+    }
+    catch (error) {
+        if (isEnoentError(error))
+            return false;
+        throw error;
+    }
+}
+function isWorkerTotal(value) {
+    return isRecord(value) && Number.isSafeInteger(value.total) && Number.isSafeInteger(value.missing);
+}
+function isWorkerSnapshotFile(value, blueprint) {
+    if (!isRecord(value) || value.version !== 1 || value.blueprint !== blueprint
+        || typeof value.recorded_at !== 'string'
+        || typeof value.ledger_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.ledger_sha256))
+        return false;
+    const tokens = value.worker_tokens;
+    return isWorkerTotal(tokens) && isRecord(tokens.by_role)
+        && WORKER_ROLES.every((r) => isWorkerTotal(tokens.by_role[r]));
+}
+/**
+ * 저장된 worker 집계 snapshot을 읽는다. 파일 없음만 "snapshot 없음"이고, 경계 밖·symlink·
+ * 깨진 JSON·다른 blueprint·모양 불일치는 `metrics-snapshot-invalid`다 — 복원값으로
+ * 잘못된 숫자를 내느니 거절해야 한다.
+ *
+ * @param {object} opts - 읽기 입력
+ * @param {string} opts.commonGitDir - Git common dir
+ * @param {string} opts.blueprint - blueprint 경로
+ * @param {SnapshotFs} [opts.fs] - 읽기 seam
+ * @returns {{ok: true, snapshot: WorkerSnapshotFile | null} | Failure} snapshot 또는 거절
+ */
+function loadWorkerSnapshot(opts) {
+    const invalid = { ok: false, reason: 'metrics-snapshot-invalid' };
+    const file = workerSnapshotPath(opts.commonGitDir, opts.blueprint);
+    if (!snapshotLocationSafe(opts.commonGitDir, file, opts.fs))
+        return invalid;
+    let raw;
+    try {
+        raw = (opts.fs ?? fs).readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (isEnoentError(error))
+            return { ok: true, snapshot: null };
+        // EACCES·EISDIR 같은 읽기 오류는 값을 신뢰할 수 없으므로 던지지 않고 invalid로 접는다.
+        if (isFsError(error))
+            return invalid;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_error) {
+        // SyntaxError만 온다. 깨진 파일은 invalid로 접는다.
+        return invalid;
+    }
+    return isWorkerSnapshotFile(parsed, normalizeBlueprint(opts.blueprint))
+        ? { ok: true, snapshot: parsed } : invalid;
+}
+// 이 호출이 방금 만든 temp를 지운다. 정리 실패(fs 오류)는 원래의 저장 실패 보고를 가리지 않도록
+// 삼킨다: 남는 것은 우리 pid가 붙은 .tmp뿐이고 최종 snapshot은 건드리지 않는다.
+function removeOwnTemporary(fsx, temporary) {
+    try {
+        (fsx.unlinkSync ?? fs.unlinkSync)(temporary);
+    }
+    catch (error) {
+        if (!isFsError(error))
+            throw error;
+    }
+}
+/**
+ * 실제 원장에서 worker 집계와 원장 SHA-256을 읽어 snapshot으로 atomic 저장한다.
+ * 같은 원장 hash의 snapshot은 다시 쓰지 않고(`reused: true`), 새 원장이면 갱신한다.
+ * 원장이 없으면 새 값을 만들지 않는다: 유효한 기존 snapshot은 그대로 보존해 돌려주고,
+ * 둘 다 없으면 `metrics-ledger-unavailable`이다. 기존 snapshot이 깨졌으면 덮어쓰지 않고
+ * `metrics-snapshot-invalid`로 거절한다. 경계 검사·snapshot 읽기의 I/O 오류도 invalid이고,
+ * mkdir·temp 생성·쓰기·rename 실패는 `metrics-snapshot-write-failed`다.
+ *
+ * @param {object} opts - 저장 입력
+ * @param {string} opts.commonGitDir - Git common dir
+ * @param {string | null} opts.ledgerFile - integration 원장 경로. null이면 원장 없음
+ * @param {string} opts.blueprint - blueprint 경로
+ * @param {SnapshotFs} [opts.fs] - I/O seam(optional 메서드는 node:fs fallback)
+ * @param {Clock} [opts.now] - 시계 seam
+ * @returns {{ok: true, blueprint: string, path: string, ledger_sha256: string, reused: boolean} | Failure}
+ *   저장(또는 재사용)된 snapshot 정보 또는 거절 사유
+ */
+function saveWorkerSnapshot(opts) {
+    const fsx = opts.fs ?? fs;
+    const blueprint = normalizeBlueprint(opts.blueprint);
+    const file = workerSnapshotPath(opts.commonGitDir, blueprint);
+    const existing = loadWorkerSnapshot({ commonGitDir: opts.commonGitDir, blueprint, fs: fsx });
+    if (existing.ok === false)
+        return existing;
+    const ledger = opts.ledgerFile === null
+        ? { ok: true, snapshot: null, decisions: [] } : readLedgerSnapshot(opts.ledgerFile, fsx);
+    if (ledger.ok === false)
+        return ledger;
+    if (ledger.snapshot === null) {
+        if (existing.snapshot === null)
+            return { ok: false, reason: 'metrics-ledger-unavailable' };
+        return { ok: true, blueprint, path: file, ledger_sha256: existing.snapshot.ledger_sha256, reused: true };
+    }
+    const hash = ledger.snapshot.ledger_sha256;
+    if (existing.snapshot !== null && existing.snapshot.ledger_sha256 === hash) {
+        return { ok: true, blueprint, path: file, ledger_sha256: hash, reused: true };
+    }
+    const data = {
+        version: 1, blueprint, recorded_at: (opts.now ?? (() => new Date()))().toISOString(),
+        ledger_sha256: hash, worker_tokens: sumWorkerDecisions(ledger.decisions),
+    };
+    const temporary = `${file}.${process.pid}.tmp`;
+    const invalid = { ok: false, reason: 'metrics-snapshot-invalid' };
+    const writeFailed = { ok: false, reason: 'metrics-snapshot-write-failed' };
+    // 위 loadWorkerSnapshot이 mkdir 전에 기존 조상까지 경계를 검사했다. 여기서는 만들기만 한다.
+    try {
+        (fsx.mkdirSync ?? fs.mkdirSync)(path.dirname(file), { recursive: true });
+    }
+    catch (error) {
+        // 디렉터리 생성 실패(EACCES·ENOSPC 등 fs 오류)만 저장 실패로 접는다. 프로그래밍 오류는 던진다.
+        if (!isFsError(error))
+            throw error;
+        return writeFailed;
+    }
+    // mkdir 뒤에 다시 검사한다: 검사와 mkdir 사이에 조상이 바뀌었다면 이제야 드러난다.
+    if (!snapshotLocationSafe(opts.commonGitDir, file, fsx))
+        return invalid;
+    try {
+        // 'wx' 배타 생성: 예측 가능한 temp 자리에 누가 symlink·파일을 심어 두었더라도 따라 쓰지 않고
+        // EEXIST로 실패한다. 이 경우 temp는 우리 것이 아니므로 지우지 않는다.
+        fsx.writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, { flag: 'wx' });
+    }
+    catch (error) {
+        if (!isFsError(error))
+            throw error;
+        // 파일이 만들어진 뒤에만 생기는 오류(공간 부족 등)일 때만 자신의 부분 temp를 정리한다.
+        if (['ENOSPC', 'EDQUOT', 'EIO', 'EFBIG'].includes(error.code)) {
+            removeOwnTemporary(fsx, temporary);
+        }
+        return writeFailed;
+    }
+    try {
+        fsx.renameSync(temporary, file);
+    }
+    catch (error) {
+        if (!isFsError(error))
+            throw error;
+        removeOwnTemporary(fsx, temporary);
+        return writeFailed;
+    }
+    return { ok: true, blueprint, path: file, ledger_sha256: hash, reused: false };
+}
+/**
+ * `coordinate status` checkpoint에 실을 같은 blueprint의 coordinator-session 요약.
+ * status는 읽기 전용 관측이라 기록 파일이 없거나 깨져도 실패시키지 않고 빈 배열을 낸다.
+ * 깨진 파일의 거절은 `metrics` 명령이 맡는다.
+ *
+ * @param {{file: string, blueprint: string}} opts - 기록 파일과 blueprint
+ * @returns {object[]} `{id,label,started_at,ended_at,tasks_completed,exception_decisions,tokens}` 목록
+ */
+function listCoordinatorSessions(opts) {
+    const current = readMetrics(opts.file);
+    if (current.ok === false)
+        return [];
+    const blueprint = normalizeBlueprint(opts.blueprint);
+    return current.data.sessions
+        .filter((s) => s.kind === 'coordinator-session' && s.blueprint === blueprint)
+        .map((s) => ({
+        id: s.id,
+        label: s.label ?? null,
+        started_at: s.started_at,
+        ended_at: s.ended_at ?? null,
+        tasks_completed: s.tasks_completed ?? null,
+        exception_decisions: s.exception_decisions ?? null,
+        tokens: s.tokens ?? null,
+    }));
+}
+module.exports = {
+    EXCEPTION_KINDS, isException, metricsFilePath, startSession, endSession, summarize,
+    listCoordinatorSessions, saveWorkerSnapshot,
+};