@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/runtime-state.js

@@ -0,0 +1,1038 @@
+'use strict';
+const guards = require("./guards");
+const { isRecord, catchMessage, isEnoentError } = guards;
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { execFileSync: realExecFileSync } = require('node:child_process');
+const paths = require("./paths");
+const { toPosix, parsePathIds } = paths;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const schema = require("./schema");
+const { DEFAULT_COMMIT_TYPE, COMMIT_TYPE_ENUM } = schema;
+const validateSections = require("./validate-sections");
+const { REPAIR_WAVE_LIMIT } = validateSections;
+const contextIds = require("./context-ids");
+const { parseContextPath, parsePointerKey: parseContextPointerKey } = contextIds;
+const time = require("./time");
+const { nowIsoKst } = time;
+const GIT_REQUIRED = 'Bouncer requires a Git repository for an active blueprint';
+class BranchNameError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * blueprint 경로가 slug 형식(`epics/<slug>/blueprints/<slug>`)인지 본다.
+ * 번호 형식·해석 불가 경로는 false라 기존(구형) 이름 규칙이 그대로 적용된다.
+ *
+ * @param {unknown} blueprint - blueprint 디렉터리 상대 경로
+ * @returns {boolean} slug 형식이면 true
+ */
+function isSlugBlueprint(blueprint) {
+    const ids = parseContextPath(blueprint);
+    return ids !== null && ids.blueprintKey !== null && ids.format === 'slug';
+}
+/**
+ * blueprint 메타데이터와 경로에서 coordinator가 공유할 branch 이름을 만든다.
+ * index.md가 없거나 읽히지 않으면 기존 fixture와 이전 blueprint를 보존하기 위해
+ * DEFAULT_COMMIT_TYPE으로 계속 진행하지만, 명시된 잘못된 commit_type은 새 worktree
+ * 생성 전에 거절한다.
+ *
+ * @param {{ repoRoot: string, blueprint: string, task?: string }} opts - 저장소와 blueprint 식별자
+ * @returns {BranchNames} integration·standalone 및 선택 worker branch 이름
+ * @throws {BranchNameError} 명시 commit_type 또는 Git ref 형식이 유효하지 않을 때
+ */
+function branchNamesFor({ repoRoot, blueprint, task }) {
+    const { epicId, blueprintId } = parsePathIds(blueprint);
+    const slugFormat = isSlugBlueprint(blueprint);
+    const slug = path.basename(blueprint).replace(new RegExp(`^${blueprintId}-`), '');
+    let commitType = DEFAULT_COMMIT_TYPE;
+    try {
+        const doc = readDoc(path.join(repoRoot, blueprint, 'index.md'));
+        const bouncer = doc.data.bouncer;
+        if (bouncer && Object.prototype.hasOwnProperty.call(bouncer, 'commit_type'))
+            commitType = bouncer.commit_type;
+    }
+    catch (_error) {
+        // index.md 부재·frontmatter 오류는 기존 bootstrap fixture와 같은 폴백이다.
+    }
+    if (typeof commitType !== 'string' || !COMMIT_TYPE_ENUM.includes(commitType)) {
+        throw new BranchNameError('invalid-commit-type');
+    }
+    // slug 형식은 구분자 `--`로 epic·bp slug를 잇는다. slug 규칙이 `--`를 막으므로 분해가 모호하지
+    // 않고, bp slug가 이미 이름이라 뒤에 다시 붙이지 않는다. 구형은 진행 중 drive가 옛 이름으로
+    // 끝나도록 번호 이름을 바이트까지 유지한다.
+    const integration = slugFormat
+        ? `${commitType}/${epicId}--${blueprintId}`
+        : `${commitType}/${epicId}-${blueprintId}-${slug}`;
+    const result = { integration, standalone: integration };
+    if (task !== undefined) {
+        result.worker = slugFormat
+            ? `bouncer/${epicId}--${blueprintId}--${task}`
+            : `bouncer/${epicId}-${blueprintId}-${task}`;
+    }
+    for (const branch of Object.values(result)) {
+        if (!branch || branch.includes('..') || /[ ~^:?*\\[\\]/.test(branch)) {
+            throw new BranchNameError('invalid-branch-name');
+        }
+    }
+    return result;
+}
+/**
+ * 등록된 checkout은 실제 branch를 유지하고, 새 checkout만 예상 branch를 만든다.
+ * 같은 branch를 다른 worktree가 잡고 있으면 suffix로 피해 provenance를 흐리지 않고
+ * 명시적으로 충돌을 돌려준다.
+ *
+ * @param {{ repoRoot: string, worktreePath: string, branch: string, execFileSync?: ExecFileSyncFn }} opts
+ *   - Git 저장소와 예상 checkout/branch
+ * @returns {WorktreeBranch} 기존 branch 재사용 또는 새 branch 생성 지시
+ * @throws {BranchNameError} ref 형식 오류나 다른 checkout의 branch 충돌일 때
+ */
+function resolveWorktreeBranch({ repoRoot, worktreePath, branch, execFileSync = realExecFileSync }) {
+    let listed;
+    try {
+        listed = String(execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+        }));
+    }
+    catch (_error) {
+        listed = '';
+    }
+    const entries = listed.trim().split(/\n\n+/).filter(Boolean).map((block) => {
+        const lines = block.split('\n');
+        return { path: lines.find((line) => line.startsWith('worktree '))?.slice(9),
+            branch: lines.find((line) => line.startsWith('branch refs/heads/'))?.slice('branch refs/heads/'.length) };
+    });
+    const existing = entries.find((entry) => entry.path && path.resolve(entry.path) === path.resolve(worktreePath));
+    if (existing?.branch)
+        return { action: 'reuse', branch: existing.branch };
+    try {
+        execFileSync('git', ['check-ref-format', '--branch', branch], {
+            cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (_error) {
+        throw new BranchNameError('invalid-branch-name');
+    }
+    try {
+        execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], {
+            cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        throw new BranchNameError('branch-conflict');
+    }
+    catch (error) {
+        if (error instanceof BranchNameError)
+            throw error;
+    }
+    return { action: 'create', branch };
+}
+function stringList(value, nonEmpty = false) {
+    return Array.isArray(value) && (!nonEmpty || value.length > 0)
+        && value.every((entry) => nonEmptyString(entry));
+}
+function dagDecision(value) {
+    return Array.isArray(value) && value.every((entry) => Boolean(entry && typeof entry === 'object'
+        && !Array.isArray(entry) && nonEmptyString(entry.id)
+        && stringList(entry.depends_on)));
+}
+/** coordinator가 기록한 task별 critical recovery 한 번의 shape를 고정한다. */
+function validCriticalRecovery(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const recovery = value;
+    return recovery.used === 1 && stringList(recovery.findings, true)
+        && nonEmptyString(recovery.reason)
+        && (recovery.outcome === null || recovery.outcome === 'resolved' || recovery.outcome === 'blocked');
+}
+const DISPATCH_REPORT_OUTCOMES = new Set([
+    'accepted', 'rework', 'scope_revision', 'task_change', 'blocked',
+]);
+/**
+ * 최신 dispatch attempt 메타 shape. attempt·hash·status가 깨지면 재개 시
+ * stale/accepted 판정이 다른 답을 내므로 critical recovery와 같이 엄격히 막는다.
+ *
+ * @param {unknown} value - task.dispatch 후보
+ * @returns {boolean} 유효하면 true
+ */
+function validDispatch(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const dispatch = value;
+    if (!Number.isInteger(dispatch.attempt) || dispatch.attempt < 1)
+        return false;
+    if (typeof dispatch.task_brief_hash !== 'string'
+        || !/^[a-f0-9]{64}$/.test(dispatch.task_brief_hash))
+        return false;
+    if (!nonEmptyString(dispatch.base_head))
+        return false;
+    if (typeof dispatch.initial_worktree_state !== 'string')
+        return false;
+    if (dispatch.status !== 'active' && dispatch.status !== 'reported')
+        return false;
+    if (dispatch.status === 'reported') {
+        if (!DISPATCH_REPORT_OUTCOMES.has(dispatch.outcome))
+            return false;
+        if (!nonEmptyString(dispatch.summary))
+            return false;
+    }
+    return true;
+}
+/**
+ * partial close가 신뢰하는 canonical repair 항목의 전체 shape를 검사한다.
+ * task/wave 식별자만 맞춘 복사본은 scope·DAG·실패 근거를 바꿔치기할 수 있으므로,
+ * 원장 사본 비교 전에 각 필드와 실제 실패 경로를 먼저 고정한다.
+ * `failure.findings`는 리뷰 원인 repair만 갖는다. 키가 없으면 CI 증적으로
+ * 읽고, 있으면 비어 있지 않은 문자열 배열이어야 한다 — 문자열 하나로는
+ * 반복 `--review-finding` 순서를 보존할 수 없다.
+ *
+ * @param {unknown} value - repair 결정 후보
+ * @param {number} expectedWave - 1부터 세는 기대 wave
+ * @returns {boolean} canonical repair 결정이면 true
+ */
+function validRepairDecision(value, expectedWave) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const decision = value;
+    const failure = decision.failure;
+    if (!failure || typeof failure !== 'object' || Array.isArray(failure))
+        return false;
+    const evidence = failure;
+    if (evidence.findings !== undefined && !stringList(evidence.findings, true))
+        return false;
+    return decision.kind === 'repair' && decision.wave === expectedWave
+        && nonEmptyString(decision.task) && nonEmptyString(decision.reason)
+        && nonEmptyString(evidence.task) && nonEmptyString(evidence.command)
+        && nonEmptyString(evidence.summary) && stringList(evidence.paths, true)
+        && typeof evidence.exitCode === 'number' && evidence.exitCode !== 0
+        && evidence.repairWave === expectedWave - 1
+        && dagDecision(decision.previousDag) && dagDecision(decision.nextDag)
+        && stringList(decision.previousScope) && stringList(decision.nextScope, true)
+        && nonEmptyString(decision.necessity)
+        && nonEmptyString(decision.revision) && /^r[1-9]\d*$/.test(decision.revision);
+}
+/**
+ * coordinator 원장의 repair/partial-close 불변조건을 검증한다.
+ * 활성 원장은 레거시 필드 부재를 허용하지만 partial_closed는 두 wave, 마지막
+ * 실패 증적, 명시적 사용자 확인이 모두 있어야만 유효하다.
+ *
+ * @param {unknown} value - 파싱된 coordinator 원장
+ * @returns {{ok: true} | {ok: false, reason: string}} 검증 결과
+ */
+function validateCoordinatorLedger(value, options = {}) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, reason: 'invalid-ledger' };
+    }
+    const ledger = value;
+    if (ledger.seedManifest !== undefined && (!Array.isArray(ledger.seedManifest)
+        || ledger.seedManifest.some((entry) => !entry || typeof entry !== 'object' || Array.isArray(entry)
+            || !nonEmptyString(entry.path)
+            || !/^[a-f0-9]{64}$/.test(entry.sha256)))) {
+        return { ok: false, reason: 'invalid-seed-manifest' };
+    }
+    // partial_closed 여부와 무관하게 먼저 검사한다. 조기 성공 반환 뒤에 두면 active
+    // ledger가 used 2를 품은 채 다음 coordinator 명령의 기준점이 될 수 있다.
+    const tasksForRecovery = Array.isArray(ledger.tasks) ? ledger.tasks : [];
+    if (tasksForRecovery.some((task) => task.criticalRecovery !== undefined
+        && !validCriticalRecovery(task.criticalRecovery))) {
+        return { ok: false, reason: 'critical-recovery-invalid' };
+    }
+    // dispatch는 레거시 원장에 없을 수 있다. 필드가 있을 때만 shape를 강제해
+    // 손상 attempt가 재개 기준이 되는 일을 막는다.
+    if (tasksForRecovery.some((task) => task.dispatch !== undefined
+        && !validDispatch(task.dispatch))) {
+        return { ok: false, reason: 'dispatch-invalid' };
+    }
+    // lease·leaseSeq도 필드가 있을 때만 검사한다. 손상 lease가 재개 기준이 되면
+    // revoke·stale 판정이 갈라지므로 dispatch와 같은 엄격도로 막는다.
+    const { isValidLease, isValidLeaseSeq } = require('./lease');
+    if (!isValidLeaseSeq(ledger.leaseSeq)) {
+        return { ok: false, reason: 'lease-invalid' };
+    }
+    if (tasksForRecovery.some((task) => task.lease !== undefined && !isValidLease(task.lease))) {
+        return { ok: false, reason: 'lease-invalid' };
+    }
+    // fanin은 부재(legacy)·null(비움)·shape 맞는 객체만 허용한다. 잘못된 status·
+    // tasks면 integrate 재개가 잘못된 candidate를 기준으로 삼을 수 있어 여기서 막는다.
+    if (ledger.fanin !== undefined && !validCoordinatorFanin(ledger.fanin)) {
+        return { ok: false, reason: 'fanin-invalid' };
+    }
+    // branch 필드는 이전 원장에는 없을 수 있지만, 있으면 이후 재개가 Git의 실제
+    // checkout을 신뢰할 수 있도록 문자열이어야 한다. 여기서 느슨하게 받으면
+    // prepare가 잘못된 값을 정상 branch 기록으로 덮어쓴 것처럼 보일 수 있다.
+    if (ledger.integrationBranch !== undefined && !nonEmptyString(ledger.integrationBranch)) {
+        return { ok: false, reason: 'invalid-ledger-branch' };
+    }
+    if (Array.isArray(ledger.tasks) && ledger.tasks.some((entry) => entry && typeof entry === 'object'
+        && entry.branch !== undefined
+        && !nonEmptyString(entry.branch))) {
+        return { ok: false, reason: 'invalid-ledger-branch' };
+    }
+    if (options.requirePartialClose && ledger.status !== 'awaiting_confirmation') {
+        return { ok: false, reason: 'partial-close-awaiting-confirmation-required' };
+    }
+    const waves = ledger.repairWaves === undefined ? [] : ledger.repairWaves;
+    if (!Array.isArray(waves) || waves.length > REPAIR_WAVE_LIMIT)
+        return { ok: false, reason: 'repair-wave-limit' };
+    if (ledger.status !== 'partial_closed')
+        return { ok: true };
+    const handoff = ledger.handoff;
+    if (!handoff || typeof handoff !== 'object' || Array.isArray(handoff)) {
+        return { ok: false, reason: 'partial-close-handoff-required' };
+    }
+    const handoffRef = handoff;
+    if (!nonEmptyString(handoffRef.path) || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}\+09:00$/.test(handoffRef.timestamp)
+        || !nonEmptyString(handoffRef.source_digest)) {
+        return { ok: false, reason: 'partial-close-handoff-invalid' };
+    }
+    if (waves.length !== REPAIR_WAVE_LIMIT)
+        return { ok: false, reason: 'partial-close-repair-waves-required' };
+    const repairs = waves;
+    if (repairs.some((entry, index) => !validRepairDecision(entry, index + 1))) {
+        return { ok: false, reason: 'partial-close-repair-decision-required' };
+    }
+    const decisions = Array.isArray(ledger.decisions) ? ledger.decisions : [];
+    const tasks = Array.isArray(ledger.tasks) ? ledger.tasks : [];
+    let previousGlobalIndex = -1;
+    for (const repair of repairs) {
+        // repairWaves가 canonical이고 task/global 항목은 그 전체 deep copy여야 한다.
+        // 부분 key 비교는 서로 다른 scope나 failure evidence를 같은 결정으로 오인한다.
+        const matches = (entry) => isDeepStrictEqual(entry, repair);
+        const globalIndex = decisions.findIndex(matches);
+        if (globalIndex < 0)
+            return { ok: false, reason: 'partial-close-global-repair-log-required' };
+        if (globalIndex <= previousGlobalIndex) {
+            return { ok: false, reason: 'partial-close-repair-waves-ordered-required' };
+        }
+        previousGlobalIndex = globalIndex;
+        const task = tasks.find((entry) => entry && entry.id === repair.task);
+        if (!task || !Array.isArray(task.decisions) || !task.decisions.some(matches)) {
+            return { ok: false, reason: 'partial-close-task-repair-log-required' };
+        }
+        if (task.status !== 'integrated') {
+            return { ok: false, reason: 'partial-close-repair-wave-not-integrated' };
+        }
+    }
+    const failure = ledger.terminalFailure;
+    if (!failure || typeof failure !== 'object' || Array.isArray(failure)) {
+        return { ok: false, reason: 'partial-close-failure-evidence-required' };
+    }
+    const evidence = failure;
+    if (!nonEmptyString(evidence.task) || !nonEmptyString(evidence.command)
+        || !nonEmptyString(evidence.summary) || !stringList(evidence.paths, true)
+        || typeof evidence.exitCode !== 'number') {
+        return { ok: false, reason: 'partial-close-failure-evidence-required' };
+    }
+    if (evidence.exitCode === 0 || evidence.repairWave !== 2) {
+        return { ok: false, reason: 'partial-close-post-wave2-nonzero-failure-required' };
+    }
+    const terminal = tasks.find((entry) => entry && entry.id === evidence.task);
+    if (!terminal || terminal.execution_kind !== 'verification' || terminal.status !== 'verifying') {
+        return { ok: false, reason: 'partial-close-terminal-failure-state-required' };
+    }
+    if (handoffRef.source_digest !== evidence.source_digest) {
+        return { ok: false, reason: 'partial-close-handoff-source-mismatch' };
+    }
+    if (ledger.userConfirmed !== true)
+        return { ok: false, reason: 'partial-close-user-confirmation-required' };
+    return { ok: true };
+}
+// coordinator.ts fence·checkpoint와 같은 상대 경로 문자열이어야 path/hash 쌍이
+// 모듈마다 다른 정본을 가리키지 않는다. 한 상수만 export하고 양쪽에서 import한다.
+const COORDINATOR_LEDGER_REL = '.bouncer/runtime/coordinator.json';
+const COMPLETED_SUMMARY_FORBIDDEN = new Set([
+    'dispatch', 'decisions', 'workerPath', 'branch', 'criticalRecovery',
+]);
+/**
+ * compact coordinator checkpoint와 원장 참조 shape를 검증한다. 완료 summary에
+ * dispatch·decisions 본문이 실리면 status compaction이 무의미해지므로 여기서 막는다.
+ * `recent_failure`는 null이어도 키가 있어야 status가 실패 증적 유무를 놓치지 않는다.
+ *
+ * @param {unknown} value - projectCheckpoint 결과 후보
+ * @returns {{ok: true} | {ok: false, reason: string}} 검증 결과
+ */
+function validateCoordinatorCheckpoint(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    const checkpoint = value;
+    if (!Array.isArray(checkpoint.ready) || !checkpoint.ready.every((id) => nonEmptyString(id))) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    if (!Array.isArray(checkpoint.active_tasks) || !Array.isArray(checkpoint.completed_tasks)
+        || !Array.isArray(checkpoint.unresolved_decisions)) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    // notes는 구 checkpoint 호환을 위해 선택이지만, 있으면 각 항목이 비지 않은 text·written_at을 가져야 한다.
+    if (Object.prototype.hasOwnProperty.call(checkpoint, 'notes')) {
+        if (!Array.isArray(checkpoint.notes) || !checkpoint.notes.every((n) => (!!n && typeof n === 'object' && !Array.isArray(n)
+            && nonEmptyString(n.text)
+            && nonEmptyString(n.written_at)))) {
+            return { ok: false, reason: 'invalid-checkpoint' };
+        }
+    }
+    // 키 부재와 null은 다르다. null은 "실패 없음"이고 키 누락은 projection 결함이다.
+    if (!Object.prototype.hasOwnProperty.call(checkpoint, 'recent_failure')) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    if (checkpoint.recent_failure !== null) {
+        if (!checkpoint.recent_failure || typeof checkpoint.recent_failure !== 'object'
+            || Array.isArray(checkpoint.recent_failure)) {
+            return { ok: false, reason: 'invalid-checkpoint' };
+        }
+    }
+    for (const entry of checkpoint.completed_tasks) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            return { ok: false, reason: 'invalid-completed-summary' };
+        }
+        const summary = entry;
+        if (!nonEmptyString(summary.id) || !nonEmptyString(summary.status)) {
+            return { ok: false, reason: 'invalid-completed-summary' };
+        }
+        for (const key of COMPLETED_SUMMARY_FORBIDDEN) {
+            if (Object.prototype.hasOwnProperty.call(summary, key)) {
+                return { ok: false, reason: 'invalid-completed-summary' };
+            }
+        }
+    }
+    for (const entry of checkpoint.active_tasks) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            return { ok: false, reason: 'invalid-checkpoint' };
+        }
+        if (!nonEmptyString(entry.id)
+            || !nonEmptyString(entry.status)) {
+            return { ok: false, reason: 'invalid-checkpoint' };
+        }
+    }
+    const ledger = checkpoint.ledger;
+    if (!ledger || typeof ledger !== 'object' || Array.isArray(ledger)) {
+        return { ok: false, reason: 'invalid-ledger-ref' };
+    }
+    const ref = ledger;
+    if (typeof ref.path !== 'string' || path.isAbsolute(ref.path) || ref.path !== COORDINATOR_LEDGER_REL
+        || ref.path.includes('..')) {
+        return { ok: false, reason: 'invalid-ledger-ref' };
+    }
+    if (typeof ref.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(ref.sha256)) {
+        return { ok: false, reason: 'invalid-ledger-ref' };
+    }
+    if (ref.revision !== null && !nonEmptyString(ref.revision)) {
+        return { ok: false, reason: 'invalid-ledger-ref' };
+    }
+    if (checkpoint.integration_head !== null && !nonEmptyString(checkpoint.integration_head)) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    if (checkpoint.revision !== null && !nonEmptyString(checkpoint.revision)) {
+        return { ok: false, reason: 'invalid-checkpoint' };
+    }
+    return { ok: true };
+}
+function runtimePaths({ repoRoot, execFileSync = realExecFileSync, 
+// env/platform은 호출부 호환용; worktree는 이제 repo 내부.
+platform = process.platform, }) {
+    const pathApi = platform === 'win32' ? path.win32 : path;
+    let commonDir;
+    try {
+        // encoding utf8이라 런타임은 문자열이다. Node 오버로드 유니온이 trim을 막아
+        // 단언만 한다 — String()으로 감싸면 Buffer 경로의 표현이 달라진다.
+        commonDir = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch (error) {
+        return { unavailable: true, reason: catchMessage(error) || 'Git common directory unavailable' };
+    }
+    if (!commonDir) {
+        return { unavailable: true, reason: 'Git common directory unavailable' };
+    }
+    const commonGitDir = pathApi.resolve(repoRoot, commonDir);
+    // dirname(.git)은 일반 repo의 main worktree root이므로, linked checkout이
+    // 자기 아래에 중첩되지 않고 같은 `.worktrees/`를 공유한다.
+    // projectRoot는 그 값을 스킬·훅 소비용으로 노출한다 — Git 계산을
+    // 스킬이나 별도 helper에서 복제하지 않기 위한 단일 정본.
+    const mainRoot = pathApi.dirname(commonGitDir);
+    const bouncerDir = pathApi.join(commonGitDir, 'bouncer');
+    return {
+        commonGitDir,
+        currentFile: pathApi.join(bouncerDir, 'current'),
+        // 레거시 단일 파일과 namespace 루트를 같이 노출한다. 이관은 current.ts가
+        // 조합하고, 여기서는 경로만 계산한다 — 두 저장소를 한 경로로 합치면
+        // 이관 실패 시 어느 쪽이 남았는지 호출부가 구분하지 못한다.
+        pointersRoot: pathApi.join(bouncerDir, 'pointers'),
+        // pointers와 형제로 둔다. 승인 파일을 포인터 JSON에 섞으면
+        // parsePointerBody가 모르는 키를 버려 재승인 증적이 사라진다.
+        approvalsRoot: pathApi.join(bouncerDir, 'approvals'),
+        worktreeRoot: pathApi.join(mainRoot, '.worktrees'),
+        projectRoot: mainRoot,
+    };
+}
+function resolvedPaths({ repoRoot, deps }) {
+    const d = deps || {};
+    return runtimePaths({
+        repoRoot,
+        execFileSync: d.execFileSync,
+        env: d.env,
+        platform: d.platform,
+    });
+}
+/**
+ * 레거시 `<git-common-dir>/bouncer/current`만 읽는다. namespace 전환 뒤에는
+ * 이 파일이 없을 수 있다. current.ts의 충돌·이관 판정은 실제 레거시 파일이
+ * 필요한데, `readRuntimeCurrent`는 유일한 namespace 키를 돌려주므로 둘을
+ * 섞으면 병렬 `--set`을 레거시 충돌로 오인한다.
+ *
+ * @param {{ repoRoot: string, deps?: RuntimeDeps | null }} opts - 저장소 루트와 주입 의존성
+ * @returns {RuntimePointer | null} 파싱된 레거시 포인터. 없거나 깨지면 null
+ */
+function readLegacyRuntimeCurrent({ repoRoot, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable || !d.fs.existsSync(paths.currentFile))
+        return null;
+    try {
+        const data = JSON.parse(d.fs.readFileSync(paths.currentFile, 'utf8').trim());
+        if (!data || typeof data.blueprint !== 'string' || typeof data.base !== 'string')
+            return null;
+        // task 키 부재·비문자열은 미지정. 마이그레이션 없이 기존 파일을 그대로 읽는다.
+        const task = typeof data.task === 'string' ? toPosix(data.task) : null;
+        return { blueprint: toPosix(data.blueprint), base: data.base, task };
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * 활성 포인터 primitive. migrate-task-layout·import-history는 namespace
+ * 열거를 모르므로, 유일한 namespace 키가 있으면 그것을 돌려 첫 `--set`
+ * 이후에도 포인터가 보이게 한다. 키가 없으면 레거시 파일로 폴백한다.
+ * 깨진 namespace 파일은 null로 숨기지 않는다 — 다른 키를 고르거나 레거시로
+ * 넘어가면 손상된 주기를 삼킨다. 경로와 실패 원인을 담아 throw한다.
+ *
+ * @param {{ repoRoot: string, deps?: RuntimeDeps | null }} opts - 저장소 루트와 주입 의존성
+ * @returns {RuntimePointer | null} 유일한 namespace 포인터, 없으면 레거시, 둘 다 없으면 null
+ * @throws {Error} 깨진 namespace 파일 또는 키가 둘 이상일 때. 메시지에 경로를 포함한다
+ */
+function readRuntimeCurrent({ repoRoot, deps }) {
+    const listed = listNamespacePointers({ repoRoot, deps });
+    const issues = listed.filter((e) => e.issue);
+    if (issues.length > 0) {
+        const detail = issues
+            .map((e) => `${e.issue.path}: ${e.issue.reason}`)
+            .join('; ');
+        throw new Error(detail);
+    }
+    const valid = listed.filter((e) => e.pointer != null);
+    if (valid.length > 1) {
+        throw new Error(`ambiguous namespace pointers: ${valid.map((e) => e.path).join(', ')}`);
+    }
+    if (valid.length === 1)
+        return valid[0].pointer;
+    return readLegacyRuntimeCurrent({ repoRoot, deps });
+}
+// pointer가 제거되면 true, 없었으면 false. 호출자는 "이미 없음"을
+// 성공으로 보므로, 파일이 없어도 throw하면 안 된다.
+function clearRuntimeCurrent({ repoRoot, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable || !d.fs.existsSync(paths.currentFile))
+        return false;
+    d.fs.rmSync(paths.currentFile);
+    return true;
+}
+/**
+ * blueprint 경로에서 세 자리 epic·blueprint id로 namespace 키를 만든다.
+ * 경로 문자열이나 worktree 위치를 키로 쓰지 않는다 — 같은 문서가 다른
+ * checkout에서 다른 파일로 갈라지면 병렬 주기가 서로 덮어쓴다.
+ *
+ * @param {unknown} blueprint - blueprint 디렉터리 상대 경로
+ * @returns {{ epicId: string, blueprintId: string, key: string }} `key`는 `epicId/blueprintId`
+ */
+function pointerKeyFromBlueprint(blueprint) {
+    const { epicId, blueprintId } = parsePathIds(blueprint);
+    if (!epicId || !blueprintId) {
+        throw new Error(`Cannot derive epic/blueprint ids from blueprint path: ${blueprint}`);
+    }
+    return { epicId, blueprintId, key: `${epicId}/${blueprintId}` };
+}
+function pathApiFor(platform) {
+    return platform === 'win32' ? path.win32 : path;
+}
+function namespacePointerPath(pointersRoot, epicId, blueprintId, pathApi) {
+    return pathApi.join(pointersRoot, epicId, `${blueprintId}.json`);
+}
+// 형식 판단은 context-ids 한 곳에 위임한다 — 번호 쌍과 slug 쌍만 받고 섞인 쌍은 null이다.
+function parsePointerKey(key) {
+    const parsed = parseContextPointerKey(key);
+    if (!parsed)
+        return null;
+    return { epicId: parsed.epicKey, blueprintId: parsed.blueprintKey, key: key };
+}
+function parsePointerBody(raw) {
+    try {
+        const data = JSON.parse(raw.trim());
+        if (!data || typeof data.blueprint !== 'string' || typeof data.base !== 'string') {
+            return { reason: 'missing blueprint or base' };
+        }
+        const task = typeof data.task === 'string' ? toPosix(data.task) : null;
+        return { pointer: { blueprint: toPosix(data.blueprint), base: data.base, task } };
+    }
+    catch (error) {
+        return { reason: catchMessage(error) || 'invalid JSON' };
+    }
+}
+function isDir(d, abs) {
+    try {
+        return d.fs.statSync(abs).isDirectory();
+    }
+    catch (_e) {
+        return false;
+    }
+}
+/**
+ * namespace 포인터 파일을 열거한다. 깨진 파일은 건너뛰지 않고 issue로 남긴다 —
+ * null로 숨기면 다른 키가 선택된 것처럼 보여 병렬 주기를 덮어쓴다.
+ *
+ * @param {{ repoRoot: string, deps?: RuntimeDeps | null }} opts - 저장소 루트와 주입 의존성
+ * @returns {NamespaceEntry[]} 키(`epic/blueprint`) 사전순
+ */
+function listNamespacePointers({ repoRoot, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable || !paths.pointersRoot)
+        return [];
+    const pathApi = pathApiFor(d.platform);
+    const root = paths.pointersRoot;
+    if (!d.fs.existsSync(root) || !isDir(d, root))
+        return [];
+    const entries = [];
+    let epicNames;
+    try {
+        epicNames = d.fs.readdirSync(root);
+    }
+    catch (_e) {
+        return [];
+    }
+    for (const epicName of epicNames) {
+        // 번호·slug 어느 epic 디렉터리 이름이든 파일 단계에서 쌍을 검증한다.
+        if (!/^[a-z0-9-]+$/.test(epicName))
+            continue;
+        const epicDir = pathApi.join(root, epicName);
+        if (!isDir(d, epicDir))
+            continue;
+        let files;
+        try {
+            files = d.fs.readdirSync(epicDir);
+        }
+        catch (_e) {
+            continue;
+        }
+        for (const file of files) {
+            const idMatch = /^([a-z0-9-]+)\.json$/.exec(file);
+            if (!idMatch)
+                continue;
+            const blueprintId = idMatch[1];
+            const key = `${epicName}/${blueprintId}`;
+            // 두 이름이 같은 형식의 쌍이 아니면(예: `001/registry-gates`) 기존처럼 조용히 건너뛴다.
+            if (!parsePointerKey(key))
+                continue;
+            const filePath = pathApi.join(epicDir, file);
+            try {
+                const parsed = parsePointerBody(d.fs.readFileSync(filePath, 'utf8'));
+                if ('pointer' in parsed) {
+                    entries.push({ key, path: filePath, pointer: parsed.pointer });
+                }
+                else {
+                    entries.push({
+                        key, path: filePath, pointer: null,
+                        issue: { path: filePath, reason: parsed.reason },
+                    });
+                }
+            }
+            catch (error) {
+                entries.push({
+                    key, path: filePath, pointer: null,
+                    issue: { path: filePath, reason: catchMessage(error) || 'unreadable pointer file' },
+                });
+            }
+        }
+    }
+    entries.sort((a, b) => a.key.localeCompare(b.key));
+    return entries;
+}
+/**
+ * namespace 파일에 포인터를 원자적으로 쓴다. 레거시 파일은 건드리지 않는다 —
+ * 이관 삭제는 쓰기가 성공한 뒤에야 current.ts가 수행한다.
+ *
+ * @param {{ repoRoot: string, blueprint: unknown, base: string, task?: unknown, deps?: RuntimeDeps | null }} opts
+ * @returns {string} 쓴 namespace 파일 절대 경로
+ */
+function writeRuntimeCurrent({ repoRoot, blueprint, base, task, deps, }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable)
+        throw new Error(GIT_REQUIRED);
+    const { epicId, blueprintId } = pointerKeyFromBlueprint(blueprint);
+    const pathApi = pathApiFor(d.platform);
+    const target = namespacePointerPath(paths.pointersRoot, epicId, blueprintId, pathApi);
+    d.fs.mkdirSync(pathApi.dirname(target), { recursive: true });
+    // task는 문자열일 때만 파일에 쓴다 — 없으면 키 자체를 생략해 레거시 형태를 유지.
+    const data = {
+        blueprint: toPosix(blueprint),
+        base,
+    };
+    if (typeof task === 'string')
+        data.task = toPosix(task);
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    // 같은 디렉터리에 tmp를 만들고 rename으로 교체한다. 다른 볼륨의 tmp는
+    // rename이 copy+unlink가 되어 이관 전에 레거시를 지운 것과 같은 구멍이 난다.
+    const tmp = pathApi.join(pathApi.dirname(target), `.${blueprintId}.${process.pid}.${Date.now()}.tmp`);
+    d.fs.writeFileSync(tmp, payload);
+    try {
+        d.fs.renameSync(tmp, target);
+    }
+    catch (error) {
+        try {
+            d.fs.rmSync(tmp);
+        }
+        catch (_cleanup) {
+            // tmp 정리는 best-effort. rename 실패 원인을 가리면 호출부가 재시도 지점을 잃는다.
+        }
+        throw error;
+    }
+    return target;
+}
+function approvalSnapshotPath(approvalsRoot, epicId, blueprintId, pathApi) {
+    return pathApi.join(approvalsRoot, epicId, `${blueprintId}.json`);
+}
+/**
+ * 같은 디렉터리 tmp→rename으로 파일을 교체한다.
+ * OS tmp를 쓰면 볼륨이 다를 때 rename이 copy+unlink가 되어 부분 파일이 남는다.
+ *
+ * @param {{ fs: InjectedFs }} d - 주입 가능 fs
+ * @param {{ join: (...parts: string[]) => string, dirname: (p: string) => string }} pathApi - 플랫폼 path
+ * @param {string} target - 최종 파일 절대 경로
+ * @param {string} payload - 쓸 문자열
+ * @param {string} tmpName - 같은 디렉터리에 만들 tmp 파일명
+ * @returns {void}
+ */
+function atomicWriteFile(d, pathApi, target, payload, tmpName) {
+    d.fs.mkdirSync(pathApi.dirname(target), { recursive: true });
+    const tmp = pathApi.join(pathApi.dirname(target), tmpName);
+    d.fs.writeFileSync(tmp, payload);
+    try {
+        d.fs.renameSync(tmp, target);
+    }
+    catch (error) {
+        try {
+            d.fs.rmSync(tmp);
+        }
+        catch (_cleanup) {
+            // tmp 정리는 best-effort. rename 실패 원인을 가리면 호출부가 재시도 지점을 잃는다.
+        }
+        throw error;
+    }
+}
+function isApprovalParts(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.values(value).every((entry) => typeof entry === 'string');
+}
+/**
+ * 승인 스냅샷 파일 경로를 계산한다. Git common dir 아래에 두어 linked worktree가
+ * 같은 승인 파일을 보고, `.git/` 안이라 staging에 실리지 않게 한다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: unknown, deps?: RuntimeDeps | null }} opts
+ *   - `blueprintDir`은 저장소 상대 blueprint 경로
+ * @returns {{ unavailable: true, reason?: string } | { path: string }} 비-Git이면 unavailable, 아니면 절대 경로
+ */
+function approvalSnapshotPathFor({ repoRoot, blueprintDir, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable || !paths.approvalsRoot) {
+        return { unavailable: true, reason: paths.reason };
+    }
+    const { epicId, blueprintId } = pointerKeyFromBlueprint(blueprintDir);
+    const pathApi = pathApiFor(d.platform);
+    return { path: approvalSnapshotPath(paths.approvalsRoot, epicId, blueprintId, pathApi) };
+}
+/**
+ * 승인 스냅샷을 읽는다. 파일이 없으면 null — 이 변경 전에 활성화된 blueprint는
+ * G24 대조를 건너뛴다. JSON이 깨졌거나 version이 1이 아니면 경로를 담아
+ * 호출부가 G24 unreadable로 거절하게 한다. 권한 오류를 부재로 접지 않는다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: unknown, deps?: RuntimeDeps | null }} opts
+ * @returns {ApprovalRead} 없음 null, 파손 `{ ok: false, path }`, 유효 `{ ok: true, snapshot }`
+ */
+function readApprovalSnapshot({ repoRoot, blueprintDir, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const located = approvalSnapshotPathFor({ repoRoot, blueprintDir, deps: d });
+    if (!('path' in located))
+        return null;
+    const target = located.path;
+    if (!d.fs.existsSync(target))
+        return null;
+    let raw;
+    try {
+        raw = d.fs.readFileSync(target, 'utf8');
+    }
+    catch (error) {
+        // ENOENT는 existsSync 이후 삭제 경합만. 그 외 읽기 오류는 부재가 아니다 —
+        // G24 skip으로 접으면 권한 문제가 승인 없음으로 통과한다.
+        if (isEnoentError(error))
+            return null;
+        return { ok: false, path: target };
+    }
+    try {
+        const parsed = JSON.parse(raw.trim());
+        if (!isRecord(parsed) || parsed.version !== 1) {
+            return { ok: false, path: target };
+        }
+        if (typeof parsed.digest !== 'string' || !isApprovalParts(parsed.parts)) {
+            return { ok: false, path: target };
+        }
+        return { ok: true, snapshot: { digest: parsed.digest, parts: parsed.parts } };
+    }
+    catch (error) {
+        // SyntaxError만 흡수한다. 그 외 throw를 unreadable로 접으면 호출부가
+        // 파일 손상을 디스크 실패와 구분하지 못한다.
+        if (error instanceof SyntaxError)
+            return { ok: false, path: target };
+        throw error;
+    }
+}
+/**
+ * 승인 스냅샷을 원자적으로 쓴다. pointer 파일과 같은 디렉터리 rename을 써서
+ * 다른 볼륨 tmp의 copy+unlink 구멍을 피한다. `--clear`/`--replace`는 이 파일을
+ * 지우지 않는다 — 다음 최초 `--set`이 덮어쓴다.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   blueprintDir: unknown,
+ *   digest: string,
+ *   parts: Record<string, string>,
+ *   deps?: RuntimeDeps | null,
+ * }} opts
+ * @returns {string} 쓴 승인 파일 절대 경로
+ */
+function writeApprovalSnapshot({ repoRoot, blueprintDir, digest, parts, deps, }) {
+    const d = { fs, ...(deps || {}) };
+    const located = approvalSnapshotPathFor({ repoRoot, blueprintDir, deps: d });
+    if (!('path' in located))
+        throw new Error(GIT_REQUIRED);
+    const { blueprintId } = pointerKeyFromBlueprint(blueprintDir);
+    const pathApi = pathApiFor(d.platform);
+    const body = {
+        version: 1,
+        blueprint: toPosix(blueprintDir),
+        digest,
+        parts,
+        recorded_at: nowIsoKst(),
+    };
+    const payload = `${JSON.stringify(body, null, 2)}\n`;
+    atomicWriteFile(d, pathApi, located.path, payload, `.${blueprintId}.${process.pid}.${Date.now()}.tmp`);
+    return located.path;
+}
+/**
+ * namespace 키 파일을 지운다. 파일이 없으면 false — 호출자는 이미 없음을 성공으로 본다.
+ *
+ * @param {{ repoRoot: string, key: string, deps?: RuntimeDeps | null }} opts - `key`는 `epicId/blueprintId`
+ * @returns {boolean} 지웠으면 true, 없었으면 false
+ */
+function removeNamespacePointer({ repoRoot, key, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable || !paths.pointersRoot)
+        return false;
+    const parsed = parsePointerKey(key);
+    if (!parsed)
+        return false;
+    const pathApi = pathApiFor(d.platform);
+    const target = namespacePointerPath(paths.pointersRoot, parsed.epicId, parsed.blueprintId, pathApi);
+    if (!d.fs.existsSync(target))
+        return false;
+    d.fs.rmSync(target);
+    return true;
+}
+// blueprint 경로만으로 execute worktree 절대 경로를 고른다.
+// 기본은 `.worktrees/<epic>/<bp>`이고, 중첩이 없는데 평면 `.worktrees/<bp>`만
+// 있으면 그 평면을 재사용한다(옮기지 않음). mkdir은 하지 않는다 —
+// `git worktree add`가 부모 디렉터리까지 만든다.
+function worktreePathFor({ repoRoot, blueprint, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable)
+        throw new Error(GIT_REQUIRED);
+    const { epicId, blueprintId } = parsePathIds(blueprint);
+    // 구형 EPIC-/BP- 접두는 parsePathIds가 흡수하지 않는다 — 숫자 id 경로만 유효.
+    if (!epicId || !blueprintId) {
+        throw new Error(`Cannot derive epic/blueprint ids from blueprint path: ${blueprint}`);
+    }
+    const platform = d.platform || process.platform;
+    const pathApi = platform === 'win32' ? path.win32 : path;
+    const nested = pathApi.join(paths.worktreeRoot, epicId, blueprintId);
+    const flat = pathApi.join(paths.worktreeRoot, blueprintId);
+    // 중첩이 디렉터리로 없고 평면만 디렉터리면 레거시 평면. 둘 다 있으면 중첩 우선.
+    const nestedIsDir = (() => {
+        try {
+            return d.fs.statSync(nested).isDirectory();
+        }
+        catch (_e) {
+            return false;
+        }
+    })();
+    const flatIsDir = (() => {
+        try {
+            return d.fs.statSync(flat).isDirectory();
+        }
+        catch (_e) {
+            return false;
+        }
+    })();
+    // 평면 fallback은 구형 번호 경로 전용이다. slug 경로는 bp slug만으로 다른 epic의 같은 이름
+    // 디렉터리를 잘못 재사용할 수 있어 항상 중첩 경로를 쓴다.
+    if (!nestedIsDir && flatIsDir && !isSlugBlueprint(blueprint))
+        return flat;
+    return nested;
+}
+/**
+ * coordinator 원장 `fanin` 필드의 shape를 본다. null은 "진행 중 없음"이고,
+ * 객체면 base/candidate/tasks/status가 재개·CAS에 쓸 수 있는 형태여야 한다.
+ *
+ * @param {unknown} value - ledger.fanin 후보
+ * @returns {boolean} 유효하면 true
+ */
+function validCoordinatorFanin(value) {
+    if (value === null)
+        return true;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const fanin = value;
+    if (!nonEmptyString(fanin.base_head))
+        return false;
+    if (fanin.candidate_head !== null && !nonEmptyString(fanin.candidate_head))
+        return false;
+    if (!Array.isArray(fanin.tasks)
+        || fanin.tasks.some((entry) => typeof entry !== 'string' || !/^\d{3}$/.test(entry))) {
+        return false;
+    }
+    return fanin.status === 'building' || fanin.status === 'verified';
+}
+// coordinator mode는 기존 execute worktree와 구분해 fan-in의 기준 checkout을
+// 하나로 고정한다. 기존 worktreePathFor의 평면 fallback은 건드리지 않는다.
+function coordinatorPathsFor({ repoRoot, blueprint, task, deps }) {
+    const d = { fs, ...(deps || {}) };
+    const paths = resolvedPaths({ repoRoot, deps: d });
+    if (paths.unavailable)
+        throw new Error(GIT_REQUIRED);
+    const { epicId, blueprintId } = parsePathIds(blueprint);
+    if (!epicId || !blueprintId)
+        throw new Error(`Cannot derive epic/blueprint ids from blueprint path: ${blueprint}`);
+    const pathApi = (d.platform || process.platform) === 'win32' ? path.win32 : path;
+    const root = pathApi.join(paths.worktreeRoot, epicId, blueprintId);
+    const integrationPath = pathApi.join(root, 'integration');
+    const result = {
+        integrationPath,
+        // COORDINATOR_LEDGER_REL과 같은 세그먼트로 절대 경로를 만들어 fence path 비교와
+        // 실제 파일이 어긋나지 않게 한다.
+        ledgerFile: pathApi.join(integrationPath, ...COORDINATOR_LEDGER_REL.split('/')),
+        // candidate는 integration 형제로 두어 ff 전에 canonical HEAD를 오염시키지 않는다.
+        faninPath: pathApi.join(root, 'fanin'),
+    };
+    if (typeof task === 'string' && /^\d{3}$/.test(task))
+        result.workerPath = pathApi.join(root, 'workers', task);
+    return result;
+}
+/**
+ * Git common directory 아래의 verify 원장 경로를 계산한다.
+ * evidenceId가 있으면 v2(내용 주소) 키를 쓰고, 없으면 verificationRel만
+ * 해시하는 legacy 경로를 돌려 — 구 원장은 읽을 수 있어도 reuse hit 키가
+ * 되지 않게 한다. linked worktree는 같은 common dir을 공유한다.
+ *
+ * @param {{ repoRoot: string, verificationRel: unknown, evidenceId?: unknown, deps?: RuntimeDeps | null }} opts
+ *   - `verificationRel`은 저장소 상대 verification.md 경로(legacy 키)
+ *   - `evidenceId`는 v2 evidence SHA-256. 있으면 legacy 키를 쓰지 않는다
+ * @returns {RuntimePaths} 성공 시 `ledgerFile`, 비-Git이면 `unavailable`
+ */
+function verifyLedgerPathFor({ repoRoot, verificationRel, evidenceId, deps }) {
+    const paths = resolvedPaths({ repoRoot, deps });
+    if (paths.unavailable) {
+        return { unavailable: true, reason: paths.reason };
+    }
+    const d = deps || {};
+    const platform = d.platform || process.platform;
+    const pathApi = platform === 'win32' ? path.win32 : path;
+    // 원장은 current 포인터와 같이 common dir 아래에 둔다. linked worktree가
+    // 같은 레코드를 보게 하고, `.git/` 안이라 커밋 스코프에 절대 안 실린다.
+    // v2는 evidence_id로 키를 잡아 scope·identity가 다르면 파일을 덮어쓰지
+    // 않는다. legacy는 rel만 해시해 구 판독기가 옛 경로를 열 수 있게 남긴다.
+    const key = typeof evidenceId === 'string' && evidenceId.trim()
+        ? `v2:${evidenceId.trim()}`
+        : toPosix(verificationRel);
+    const digest = createHash('sha256').update(key, 'utf8').digest('hex').slice(0, 16);
+    return {
+        ...paths,
+        ledgerFile: pathApi.join(paths.commonGitDir, 'bouncer', 'verify', `${digest}.json`),
+    };
+}
+/**
+ * 실행 Task 문서 경로의 intent bundle record 위치를 계산한다.
+ * verify ledger와 같이 Git common directory 아래에 두어 main·linked worktree가
+ * 같은 파일을 보고, `.git/` 안이라 staging에 실리지 않게 한다.
+ *
+ * @param {{ repoRoot: string, taskRel: unknown, deps?: RuntimeDeps | null }} opts
+ *   - `taskRel`은 저장소 상대 tasks.md 경로
+ * @returns {RuntimePaths} 성공 시 `intentFile`, 비-Git이면 `unavailable`
+ */
+function intentBundlePathFor({ repoRoot, taskRel, deps }) {
+    const paths = resolvedPaths({ repoRoot, deps });
+    if (paths.unavailable) {
+        return { unavailable: true, reason: paths.reason };
+    }
+    const d = deps || {};
+    const platform = d.platform || process.platform;
+    const pathApi = platform === 'win32' ? path.win32 : path;
+    // verify ledger와 같은 digest 길이·배치를 유지한다. 경로 문자를 파일명에
+    // 넣지 않으면서 worktree마다 다른 checkout 문자열이 섞이지 않게 한다.
+    const digest = createHash('sha256').update(toPosix(taskRel), 'utf8').digest('hex').slice(0, 16);
+    return {
+        ...paths,
+        intentFile: pathApi.join(paths.commonGitDir, 'bouncer', 'intent', `${digest}.json`),
+    };
+}
+/**
+ * porcelain 출력이 비어 있지 않으면 dirty. git 실패도 dirty로 본다 —
+ * migrate task-layout·import-history가 부분 쓰기를 남기지 않게 apply를 막기 위함.
+ */
+function isWorktreeDirty(repoRoot, execFileSync = realExecFileSync) {
+    try {
+        const out = execFileSync('git', ['status', '--porcelain'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return String(out).trim().length > 0;
+    }
+    catch (_e) {
+        return true;
+    }
+}
+module.exports = {
+    runtimePaths, readRuntimeCurrent, readLegacyRuntimeCurrent, writeRuntimeCurrent,
+    clearRuntimeCurrent, worktreePathFor, coordinatorPathsFor, verifyLedgerPathFor,
+    intentBundlePathFor, isWorktreeDirty,
+    pointerKeyFromBlueprint, listNamespacePointers, removeNamespacePointer,
+    readApprovalSnapshot, writeApprovalSnapshot, approvalSnapshotPathFor,
+    validateCoordinatorLedger,
+    validateCoordinatorCheckpoint,
+    branchNamesFor, resolveWorktreeBranch, parsePointerKey,
+    COORDINATOR_LEDGER_REL,
+};