@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/context-review-transitions.js

@@ -0,0 +1,412 @@
+'use strict';
+const { isDeepStrictEqual } = require('node:util');
+const guards = require("./guards");
+const { isRecord } = guards;
+const validateSections = require("./validate-sections");
+const { normalizeFinding, normalizeRoundFindings, CONTEXT_REVIEW_STATUS } = validateSections;
+function fail(reason, cause, next) {
+    return { ok: false, reason, cause, next };
+}
+/**
+ * 병합된 finding 목록에서 둘 이상이 공유하는 fingerprint를 처음 나온 순서로 돌려준다.
+ * collectFindingFailures를 통째로 부르면 round·본문 검사 메시지가 섞이므로 중복만 센다.
+ * fingerprint가 문자열이 아닌 finding은 건너뛴다(형식 오류는 close 시점 검사가 맡는다).
+ *
+ * @param {Array<{fingerprint?: unknown}>} findings 이전 round와 합친 finding
+ * @returns {string[]} 중복된 fingerprint
+ */
+function duplicateFingerprints(findings) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const f of findings) {
+        if (typeof f.fingerprint !== 'string')
+            continue;
+        if (seen.has(f.fingerprint))
+            dup.add(f.fingerprint);
+        seen.add(f.fingerprint);
+    }
+    return [...dup];
+}
+/**
+ * 이번 입력 finding의 정규화 id를 입력 순서로 중복 없이 돌려준다. noop 응답도 첫 적용과
+ * 같은 값을 내야 하므로 fold 없이 finding 하나씩 정규화해 계산한다(id는 결정적이다).
+ *
+ * @param {Finding[]} findings - 이번 round 입력 findings(readReportInput 통과분)
+ * @returns {string[]} 정규화 id 목록
+ */
+function inputFindingIds(findings) {
+    const ids = [];
+    for (const f of findings) {
+        const id = normalizeFinding(f, 'context').id;
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/**
+ * 저장된 projection의 finding을 정규화한 사본을 만든다. 정규화 도입 전에 닫힌 state는
+ * 틀린 fingerprint를 projection에 담고 있을 수 있어, noop 재실행이 문서를 다시 쓸 때
+ * 그대로 쓰면 형식 검증에서 막힌다. state.json 자체는 고치지 않는다(파생 값만 복구).
+ *
+ * @param {{ findings: Finding[]; rounds: unknown[] }} projection - state에 저장된 projection
+ * @returns {{ findings: Finding[]; rounds: unknown[] }} findings만 정규화한 사본
+ */
+function normalizeProjection(projection) {
+    return { ...projection, findings: projection.findings.map((f) => normalizeFinding(f, 'context')) };
+}
+/**
+ * closure 투영을 만든다. resolved 또는 note 있는 accepted만 통과하고, must_fix
+ * accepted는 사용자가 명시한 --accept-risk ID와 정확히 일치해야 한다.
+ *
+ * @param {Finding[]} findings - ID별 최신 처분
+ * @param {string[]} acceptRisk - 명시 동의된 finding ID
+ * @returns {Finding[] | Fail} 투영된 findings 또는 unresolved 거절
+ */
+function projectClosure(findings, acceptRisk) {
+    const bad = [];
+    const risky = new Set();
+    for (const f of findings) {
+        const noted = typeof f.note === 'string' && f.note.trim() !== '';
+        if (f.status === 'open')
+            bad.push(`${String(f.id)} open`);
+        else if (f.status === 'accepted' && !noted)
+            bad.push(`${String(f.id)} accepted without note`);
+        else if (f.status === 'accepted' && f.actionability === 'must_fix') {
+            if (acceptRisk.includes(f.id))
+                risky.add(f.id);
+            else
+                bad.push(`${String(f.id)} must_fix accepted without --accept-risk`);
+        }
+    }
+    for (const id of acceptRisk) {
+        if (!risky.has(id))
+            bad.push(`--accept-risk ${id} is not an accepted must_fix finding`);
+    }
+    if (bad.length > 0) {
+        return fail('context-review-unresolved-findings', bad, 'resolve open findings or record explicit user-approved accepted-risk with note');
+    }
+    // 통과한 finding 중 사용자 동의가 명시된 accepted must_fix에만 accepted_risk: true 표식을 붙인다.
+    // 사람이 손으로 붙인 값은 배제하고 CLI projection에서만 부여해 기록 판정에 넘긴다.
+    return findings.map((f) => {
+        if (f.status === 'accepted' && f.actionability === 'must_fix' && risky.has(f.id)) {
+            return { ...f, accepted_risk: true };
+        }
+        return { ...f };
+    });
+}
+/**
+ * 검증된 payload에서 본문 비교에 필요한 값만 취한다. 불완전한 입력은 해결 증거로 쓰지 않는다.
+ * @param {Record<string, unknown>} payload - 호출자가 이미 읽은 dispatch
+ * @returns {Record<string, { body: string }> | undefined} 경로별 본문 또는 문서 정보 없음; I/O 없음
+ */
+function contentOf(payload) {
+    const raw = payload.documents_content;
+    if (!isRecord(raw))
+        return undefined;
+    const out = {};
+    for (const [file, doc] of Object.entries(raw)) {
+        if (isRecord(doc) && typeof doc.body === 'string')
+            out[file] = { body: doc.body };
+    }
+    return out;
+}
+/**
+ * finding symbol과 heading 텍스트를 같은 꼴로 줄인다: 소문자로 바꾸고 영숫자(한글 포함)가 아닌 문자를 지운다.
+ * 예: `goal-intent`와 `Goal & intent`는 모두 `goalintent`.
+ * @param {string} text - 비교할 heading 또는 symbol
+ * @returns {string} 구두점을 제거한 비교 키; 부작용 없음
+ */
+function sectionKey(text) {
+    return text.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+}
+/**
+ * 본문에서 symbol과 일치하는 첫 heading의 섹션 본문을 뽑는다. 섹션은 그 heading 줄부터 같은 단계 이상
+ * (# 개수가 같거나 적은)의 다음 heading 직전까지다. 코드 펜스 안의 `#`은 heading이 아니다.
+ *
+ * @param {string} body - 문서 본문
+ * @param {string} symbol - finding symbol(heading slug)
+ * @returns {string | undefined} 섹션 본문, heading을 못 찾으면 undefined
+ */
+function extractSection(body, symbol) {
+    const want = sectionKey(symbol);
+    if (want === '')
+        return undefined;
+    const lines = body.split('\n');
+    let fenced = false;
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (/^\s*(```|~~~)/.test(lines[i])) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        const m = /^(#{1,6})\s+(.*)$/.exec(lines[i]);
+        if (!m)
+            continue;
+        if (start >= 0) {
+            if (m[1].length <= level)
+                return lines.slice(start, i).join('\n');
+        }
+        else if (sectionKey(m[2]) === want) {
+            start = i;
+            level = m[1].length;
+        }
+    }
+    return start >= 0 ? lines.slice(start).join('\n') : undefined;
+}
+/**
+ * 열린 must_fix 모두의 대상이 기준 대비 고쳐졌는지 판정한다. payload의 changed_documents·revision_diff는
+ * loadDispatch가 대조하지 않아 위조될 수 있으므로 입력으로 쓰지 않고, 재계산 대조를 통과한
+ * documents_content 본문만 비교한다. 파일을 읽지 않는다.
+ *
+ * @param {Finding[]} findings - 판정할 finding. open must_fix만 본다
+ * @param {Record<string, {body: string}> | undefined} baseline - 기준(latest 저장본) 문서 본문. 없으면 false
+ * @param {Record<string, {body: string}> | undefined} current - 이번 dispatch의 문서 본문
+ * @returns {boolean} 모든 대상이 고쳐졌으면 true. 하나라도 그대로이거나 file/섹션을 한쪽에서
+ *   못 찾으면 false
+ */
+function openMustFixesFixed(findings, baseline, current) {
+    if (!baseline || !current)
+        return false;
+    return findings
+        .filter((f) => f.status === 'open' && f.actionability === 'must_fix')
+        .every((f) => {
+        const file = f.file;
+        const symbol = f.symbol;
+        if (typeof file !== 'string' || typeof symbol !== 'string')
+            return false;
+        if (!Object.hasOwn(baseline, file) || !Object.hasOwn(current, file))
+            return false;
+        const before = baseline[file].body;
+        const after = current[file].body;
+        // symbol `-`는 섹션 지정이 없는 finding이라 file 본문 전체를 비교한다.
+        if (symbol === '-')
+            return before !== after;
+        const a = extractSection(before, symbol);
+        const b = extractSection(after, symbol);
+        return a !== undefined && b !== undefined && a !== b;
+    });
+}
+/**
+ * 두 plan payload의 문서 집합·structure_parts(구조)와 scope_parts(Interface·Touch 계약)가 같은지 본다.
+ * scope_parts의 해시 공식은 plan-snapshot 소유라 여기서는 값만 비교한다.
+ *
+ * @param {Record<string, unknown>} a - 기준 payload(저장된 latest dispatch)
+ * @param {Record<string, unknown>} b - 비교 payload 또는 현재 계산값
+ * @returns {{ structure: boolean, scope: boolean }} 구조 동일 여부와 계약 동일 여부
+ */
+function compareShape(a, b) {
+    const docs = (x) => (Array.isArray(x.documents) ? x.documents
+        : (isRecord(x.target) ? x.target.documents : undefined));
+    return {
+        structure: isDeepStrictEqual(docs(a), docs(b)) && isDeepStrictEqual(a.structure_parts, b.structure_parts),
+        scope: isDeepStrictEqual(a.scope_parts, b.scope_parts),
+    };
+}
+/**
+ * close가 본문 수정만 인증하도록 구조와 계약을 함께 대조한다.
+ * @param {Record<string, unknown>} a - 기존 payload
+ * @param {Record<string, unknown>} b - 새 payload 또는 이미 계산한 parts
+ * @returns {boolean} 두 경계가 모두 같으면 true; 입력 변경과 I/O 없음
+ */
+function sameStructureAndScope(a, b) {
+    const shape = compareShape(a, b);
+    return shape.structure && shape.scope;
+}
+/**
+ * 읽어 둔 처분을 finding 사본에 적용한다. 거절 시 입력과 기존 상태를 바꾸지 않는다.
+ * @param {Finding[]} findings - 정규화된 기존 findings
+ * @param {unknown[]} parsed - 파싱한 처분 배열
+ * @returns {Finding[] | Fail} 처분 사본 또는 기존 reason의 거절
+ */
+function applyDispositions(findings, parsed) {
+    const seenIds = new Set();
+    const merged = findings.map((f) => ({ ...f }));
+    for (const item of parsed) {
+        if (!isRecord(item) || typeof item.id !== 'string') {
+            return fail('context-review-input-invalid', 'disposition item missing valid id', 'each disposition must be an object with string id');
+        }
+        if (seenIds.has(item.id)) {
+            return fail('context-review-input-invalid', `duplicate disposition id ${item.id}`, 'each finding id must appear at most once in dispositions');
+        }
+        seenIds.add(item.id);
+        const targetIndex = merged.findIndex((f) => f.id === item.id);
+        if (targetIndex < 0) {
+            return fail('context-review-input-invalid', `finding id ${item.id} not found in recorded findings`, 'only dispose recorded findings');
+        }
+        if (!CONTEXT_REVIEW_STATUS.includes(item.status)) {
+            return fail('context-review-input-invalid', `disposition status ${String(item.status)} invalid`, 'disposition status must be resolved or accepted');
+        }
+        merged[targetIndex] = {
+            ...merged[targetIndex],
+            status: item.status,
+            ...(item.note !== undefined ? { note: item.note } : {}),
+        };
+    }
+    return merged;
+}
+/**
+ * 뒤 보고가 같은 ID의 finding 전체를 대체하게 사본을 병합한다.
+ * @param {Finding[]} prior - 이전 정규화 findings
+ * @param {Finding[]} incoming - 이번 정규화 findings
+ * @returns {Finding[]} 입력 배열을 변경하지 않은 최신 ID별 목록
+ */
+function mergeFindings(prior, incoming) {
+    const merged = [...prior];
+    for (const f of incoming) {
+        const at = merged.findIndex((x) => x.id === f.id);
+        if (at >= 0)
+            merged[at] = f;
+        else
+            merged.push(f);
+    }
+    return merged;
+}
+/**
+ * 새 round를 정규화·병합하고 중복 fingerprint를 쓰기 전에 거절한다.
+ * @param {Finding[]} findings - 이번 입력 findings
+ * @param {Finding[]} prior - 이전 보고를 합친 findings
+ * @returns {object | Fail} 정규화 IDs와 병합 결과 또는 거절; 입력 변경과 I/O 없음
+ */
+function prepareFindings(findings, prior) {
+    const normalized = normalizeRoundFindings(findings, prior, 'context');
+    if (!normalized.ok) {
+        return fail('context-review-input-invalid', normalized.messages, 'give each finding a non-empty string id or omit the id key; resolve id collisions, then retry');
+    }
+    const incoming = normalized.findings;
+    const merged = mergeFindings(prior, incoming);
+    // 중복 fingerprint는 status와 무관하게 쓰기 전에 거부한다. accepted 때만 막으면 중복이 requested/addressed
+    // record를 통과한 뒤 close에서야 막혀, 같은 round를 다시 기록할 수 없고 restart만 남기 때문이다.
+    const duplicates = duplicateFingerprints(merged);
+    if (duplicates.length > 0) {
+        return fail('context-review-input-invalid', duplicates.map((fp) => `context-review duplicate fingerprint ${fp}`), 'merge the findings sharing a fingerprint into one and record the same round again');
+    }
+    return { normalized, incoming, merged };
+}
+/**
+ * 검증을 마친 전이의 새 상태를 계산한다. 기존 상태와 입력은 변경하지 않는다.
+ * @param {State} state - 기존 상태
+ * @param {ReportInput} report - 검증된 보고
+ * @param {string} status - 요청 상태
+ * @param {string[]} acceptRisk - 명시 동의 IDs
+ * @param {Dispatch} dispatch - 검증된 dispatch
+ * @param {Ref} dispatchRef - 저장 참조
+ * @param {string} reportRel - 저장 보고 경로
+ * @param {string} reportSha - 보고 digest
+ * @param {string} key - 전이 키
+ * @param {State['projection']} projection - 검증된 투영
+ * @returns {State} 저장할 새 상태; I/O와 추가 검증은 호출부가 기존 시점에 수행한다
+ */
+function recordState(state, report, status, acceptRisk, dispatch, dispatchRef, reportRel, reportSha, key, projection) {
+    const cycle = state.cycle;
+    const round = report.round.round;
+    return {
+        ...state,
+        cycle: {
+            ...cycle,
+            active_reports: [...cycle.active_reports, {
+                    round: round, mode: report.round.mode, status, path: reportRel,
+                    sha256: reportSha, dispatch: dispatchRef, key,
+                }],
+            latest_dispatch: dispatchRef,
+        },
+        transitions: [...state.transitions, key],
+        closed: status === 'accepted',
+        ...(status === 'accepted'
+            ? { closure: { accept_risk: acceptRisk, closure_target_digest: dispatch.digest } }
+            : {}),
+        projection,
+    };
+}
+/**
+ * 검증을 마친 전이의 새 상태를 계산한다. 기존 상태와 입력은 변경하지 않는다.
+ * @param {State} state - 기존 상태
+ * @param {string} key - 전이 키
+ * @param {Ref} dispRef - 처분 저장 참조
+ * @param {string[]} acceptRisk - 명시 동의 IDs
+ * @param {string} digest - 인증 digest
+ * @param {State['projection']} projection - 검증된 투영
+ * @returns {State} 저장할 새 상태; I/O와 추가 검증은 호출부가 기존 시점에 수행한다
+ */
+function closeState(state, key, dispRef, acceptRisk, digest, projection) {
+    return {
+        ...state,
+        transitions: [...state.transitions, key],
+        closed: true,
+        closure: { dispositions: dispRef, accept_risk: acceptRisk, closure_target_digest: digest },
+        projection,
+    };
+}
+/**
+ * 검증을 마친 전이의 새 상태를 계산한다. 기존 상태와 입력은 변경하지 않는다.
+ * @param {State} base - 기존 상태 또는 legacy 틀
+ * @param {Record<string, unknown>} archive - 이전 증거
+ * @param {Ref} dispatchRef - 새 dispatch 저장 참조
+ * @param {string} key - 전이 키
+ * @returns {State} 저장할 새 상태; I/O와 추가 검증은 호출부가 기존 시점에 수행한다
+ */
+function restartState(base, archive, dispatchRef, key) {
+    return {
+        ...base,
+        cycle: {
+            id: base.cycle.id,
+            restart_count: 1,
+            history: [...base.cycle.history, archive],
+            active_reports: [],
+            latest_dispatch: dispatchRef,
+        },
+        transitions: [...base.transitions, key],
+        closed: false,
+        closure: undefined,
+        projection: null,
+    };
+}
+/**
+ * 읽어 둔 증거로 restart 가능 여부와 archive를 계산한다. 미해결 finding을 snapshot 동일성보다 먼저 거절한다.
+ * @param {State} state - 기존 상태
+ * @param {object} folded - 저장 보고 합성 결과
+ * @param {Record<string, unknown>} latest - 마지막 저장 dispatch
+ * @param {Record<string, unknown>} current - 검증된 새 dispatch
+ * @param {string} digest - 새 snapshot digest
+ * @param {string} reason - 보관할 재시작 사유
+ * @returns {Record<string, unknown> | Fail} archive 또는 기존 reason의 거절; 입력 변경과 I/O 없음
+ */
+function restartArchive(state, folded, latest, current, digest, reason) {
+    // 닫힌 cycle은 미해결 검사를 projection 기준으로 판정한다.
+    // 열려 있는 cycle은 fold된 active 보고의 open must_fix를 검사한다.
+    const findingsToCheck = (state.closed && state.projection)
+        ? state.projection.findings
+        : folded.findings;
+    // delta 뒤 열린 must_fix는 대상 섹션이 실제로 고쳐졌을 때만 restart를 받아들인다.
+    // 기준은 이미 읽은 latest 저장본이고 새 내용은 loadDispatch가 재계산 대조한 payload다.
+    if (state.cycle.active_reports.length >= 2
+        && findingsToCheck.some((f) => f.status === 'open' && f.actionability === 'must_fix')
+        && !openMustFixesFixed(findingsToCheck, contentOf(latest), contentOf(current))) {
+        return fail('context-review-unresolved-findings', 'must_fix remains open after the delta round', 'record explicit user-approved accepted-risk with context-review close, or fix the target section '
+            + 'of every open must_fix: route then guides close or restart');
+    }
+    // 닫힌 cycle은 close가 인증한 digest가 마지막 certified target이다(본문 재close가 latest_dispatch를
+    // 바꾸지 않으므로 round digest만 보면 이미 인증된 snapshot으로 restart할 수 있다).
+    const previousDigest = state.closure?.closure_target_digest
+        ?? latest.target.digest;
+    if (previousDigest === digest) {
+        return fail('context-review-state-conflict', 'plan snapshot is unchanged since the last certified target', 'restart only after the plan documents changed');
+    }
+    const dispatches = [...state.cycle.active_reports.map((r) => r.dispatch), state.cycle.latest_dispatch];
+    return {
+        restart_index: 1,
+        reason,
+        rounds: folded.rounds,
+        findings: findingsToCheck,
+        reports: state.cycle.active_reports,
+        dispatches: dispatches.filter((d, i) => dispatches.findIndex((x) => x.sha256 === d.sha256) === i),
+        ...(state.closure ? { closure: state.closure } : {}),
+    };
+}
+module.exports = {
+    inputFindingIds, normalizeProjection, projectClosure, contentOf, openMustFixesFixed,
+    compareShape, sameStructureAndScope, applyDispositions, prepareFindings,
+    recordState, closeState, restartState, restartArchive,
+};

package/dist/coordinate-advance.js

@@ -0,0 +1,253 @@
+'use strict';
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+// judge 없이 argv만으로 끝낼 수 있는 행동. next가 이 집합 밖을 주면 advance는
+// 실행하지 않고 worker/judge 정지로 넘긴다 — commit 순서를 advance가 만들지 않게.
+const AUTO_ACTIONS = new Set([
+    'prepare', 'integrate', 'verification_node', 'verify', 'commit',
+]);
+// yield는 세션 경계 신호라 실행할 argv가 없다. worker로 오분류되면 coordinator가 없는
+// worker를 찾아 헤매므로 단말 행동으로 둔다 — 정지만 하고 새 세션 여부는 root가 정한다.
+const TERMINAL_ACTIONS = new Set(['blocked', 'done', 'none', 'yield']);
+// fence가 한 박자 늦은 경우만 재시도한다. stale-lease 등은 원장·lease를
+// 다시 읽어도 같은 argv로는 낫지 않아 즉시 실패로 넘긴다.
+const RETRYABLE_REASONS = new Set([
+    'stale-ledger-checkpoint', 'stale-integration-head',
+]);
+const DEFAULT_MAX_STEPS = 20;
+/**
+ * `coordinate next` argv를 기본 경로에서 실행한다. 첫 토큰 `bouncer`는
+ * 이 패키지 launcher로 치환해 PATH에 bouncer가 없어도 같은 설치본을 쓴다.
+ *
+ * @param {string[]} argv - next가 준 argv(`bouncer`로 시작)
+ * @param {string} cwd - 실행 cwd(next 응답의 cwd)
+ * @returns {{ stdout: string, status: number }} 자식 stdout과 종료 코드
+ */
+function defaultRunArgv(argv, cwd) {
+    const launcher = path.join(__dirname, '..', 'bin', 'bouncer');
+    const result = spawnSync(process.execPath, [launcher, ...argv.slice(1)], {
+        cwd,
+        encoding: 'utf8',
+        // stderr는 파이프에 모아 호출자 stdout JSON과 섞이지 않게 한다.
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const status = typeof result.status === 'number' ? result.status : 1;
+    return { stdout: result.stdout || '', status };
+}
+/**
+ * 기본 next 의존성. advance CLI가 deps를 안 넘길 때 coordinateNext를 부른다.
+ *
+ * @param {{ repoRoot: string, blueprint: string, task?: string }} opts - advance 옵션
+ * @returns {NextShape} coordinateNext 결과
+ */
+function defaultNext(opts) {
+    const { coordinateNext } = require('./coordinate-next');
+    // next CLI와 같이 호출자 cwd를 넘긴다. integration이 아니면 next가 거절한다.
+    return coordinateNext({
+        repoRoot: opts.repoRoot,
+        blueprint: opts.blueprint,
+        cwd: process.cwd(),
+        task: opts.task,
+    });
+}
+/**
+ * argv 결과 JSON에서 비교·보고용 실패 reason을 고른다.
+ * 검증 실패는 reason 키가 없고 failures[0].code만 있는 경우가 있다.
+ *
+ * @param {Record<string, unknown>} body - 파싱된 stdout JSON
+ * @returns {string | undefined} reason 또는 첫 failures[].code
+ */
+function failureReasonOf(body) {
+    if (typeof body.reason === 'string' && body.reason !== '')
+        return body.reason;
+    const failures = body.failures;
+    if (Array.isArray(failures) && failures.length > 0) {
+        const code = failures[0].code;
+        if (typeof code === 'string' && code !== '')
+            return code;
+    }
+    return undefined;
+}
+/**
+ * stdout을 JSON 객체로 파싱한다. 배열·원시값은 결과 계약이 아니라 실패로 본다.
+ *
+ * @param {string} stdout - runArgv stdout
+ * @returns {Record<string, unknown> | null} 객체면 본문, 아니면 null
+ */
+function parseResultJson(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        // JSON이 아니면 unclear-result로 올린다. SyntaxError만 흡수한다.
+        return null;
+    }
+}
+/**
+ * runArgv 한 번의 stdout·status를 성공·실패·불명확으로 분류한다.
+ *
+ * @param {{ stdout: string, status: number }} attempt - runArgv 결과
+ * @returns {RunOutcome} 분류 결과
+ */
+function classifyRun(attempt) {
+    if (attempt.status !== 0 && attempt.status !== 1) {
+        return { kind: 'unclear', detail: `automatic action exited with status ${attempt.status}` };
+    }
+    const body = parseResultJson(attempt.stdout);
+    if (body === null) {
+        return { kind: 'unclear', detail: 'automatic action stdout was not a JSON object' };
+    }
+    const hasFailureCodes = Array.isArray(body.failures)
+        && body.failures.some((f) => f && typeof f.code === 'string');
+    if (body.ok === false || hasFailureCodes) {
+        return {
+            kind: 'failure',
+            body,
+            reason: failureReasonOf(body) || 'failed',
+        };
+    }
+    if (body.ok === true && attempt.status === 0) {
+        return { kind: 'success', exit: attempt.status };
+    }
+    return {
+        kind: 'unclear',
+        detail: 'automatic action result was not a clear success or failure',
+    };
+}
+/**
+ * 자동 행동 실패를 advance 실패 응답으로 옮긴다. 원 응답 필드를 유지하고
+ * executed만 붙인다 — 클라이언트가 기존 coordinate 실패와 같이 파싱한다.
+ *
+ * @param {Record<string, unknown>} body - argv 실패 JSON
+ * @param {string} reason - 보고 reason
+ * @param {ExecutedStep[]} executed - 지금까지 성공한 단계
+ * @returns {AdvanceErr} ok:false 응답
+ */
+function failFromBody(body, reason, executed) {
+    // 원 argv 실패 필드(failures 등)를 유지하고 executed만 붙인다.
+    return {
+        ...body,
+        ok: false,
+        reason,
+        cause: body.cause !== undefined ? body.cause : reason,
+        next: body.next !== undefined ? body.next : '',
+        executed,
+    };
+}
+/**
+ * unclear-result / advance-argv-invalid처럼 advance가 만든 실패.
+ * 검증기 소스를 읽으라는 안내는 넣지 않고 cause·next만 돌린다.
+ *
+ * @param {string} reason - advance 실패 reason
+ * @param {string} cause - 짧은 원인
+ * @param {string} nextHint - 다음에 할 일
+ * @param {ExecutedStep[]} executed - 지금까지 성공한 단계
+ * @returns {AdvanceErr} ok:false 응답
+ */
+function failAdvance(reason, cause, nextHint, executed) {
+    return { ok: false, reason, cause, next: nextHint, executed };
+}
+/**
+ * `coordinate next`가 준 결정적 argv를 연쇄 실행하다 판단·worker·한도·오류에서 멈춘다.
+ * 원장·pointer는 직접 쓰지 않고 next가 준 argv만 실행하며, 단계마다 next를
+ * 다시 불러 fence를 갱신한다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} opts.blueprint - blueprint 상대 경로
+ * @param {string} [opts.task] - task 범위 next에 넘길 id
+ * @param {number} [opts.maxSteps] - 자동 실행 상한(기본 20). 양의 정수만
+ * @param {AdvanceDeps} [opts.deps] - next·runArgv 주입 seam
+ * @returns {AdvanceOk | AdvanceErr} 정지(ok:true) 또는 실패(ok:false)
+ */
+function advance(opts) {
+    const maxSteps = opts.maxSteps === undefined ? DEFAULT_MAX_STEPS : opts.maxSteps;
+    const nextFn = opts.deps?.next ?? defaultNext;
+    const runArgv = opts.deps?.runArgv ?? defaultRunArgv;
+    const executed = [];
+    const nextOpts = {
+        repoRoot: opts.repoRoot,
+        blueprint: opts.blueprint,
+        task: opts.task,
+    };
+    // 1. 매 단계 next를 새로 부른다. 이전 argv의 fence를 재사용하지 않는다.
+    while (true) {
+        const step = nextFn(nextOpts);
+        if (step.ok !== true) {
+            return {
+                ok: false,
+                reason: typeof step.reason === 'string' ? step.reason : 'next-failed',
+                cause: step.cause !== undefined ? step.cause : step.reason,
+                next: step.next !== undefined ? step.next : '',
+                executed,
+            };
+        }
+        const action = typeof step.action === 'string' ? step.action : '';
+        // 2. 단말 행동·판단·worker는 실행 없이 정지. stop.next에 이 next 전체를 담는다.
+        if (TERMINAL_ACTIONS.has(action)) {
+            return {
+                ok: true,
+                executed,
+                stop: { reason: action, next: step },
+            };
+        }
+        if (step.judge !== undefined && step.judge !== null) {
+            return { ok: true, executed, stop: { reason: 'judge', next: step } };
+        }
+        const argv = Array.isArray(step.argv) ? step.argv : undefined;
+        const isAuto = AUTO_ACTIONS.has(action) && argv !== undefined && argv.length > 0;
+        if (!isAuto) {
+            // drive_tasks(argv 없음)·implement(inline 포함)·그 밖 worker 위임.
+            return { ok: true, executed, stop: { reason: 'worker', next: step } };
+        }
+        // 3. 한도에 닿으면 이번 argv는 실행하지 않는다. executed 길이가 곧 단계 수다.
+        if (executed.length >= maxSteps) {
+            return { ok: true, executed, stop: { reason: 'max-steps', next: step } };
+        }
+        if (argv[0] !== 'bouncer') {
+            return failAdvance('advance-argv-invalid', 'next argv must start with bouncer', 'Inspect coordinate next argv; do not invent a replacement command.', executed);
+        }
+        const cwd = typeof step.cwd === 'string' && step.cwd !== '' ? step.cwd : process.cwd();
+        let outcome = classifyRun(runArgv(argv, cwd));
+        // 4. stale fence만 next를 다시 불러 한 번 재실행한다. 같은 reason이면
+        // repeated-failure, 다른 실패면 그 응답, 성공이면 executed에 넣고 루프.
+        if (outcome.kind === 'failure' && RETRYABLE_REASONS.has(outcome.reason)) {
+            const firstReason = outcome.reason;
+            const again = nextFn(nextOpts);
+            if (again.ok === true
+                && again.action === action
+                && Array.isArray(again.argv)
+                && again.argv.length > 0
+                && again.argv[0] === 'bouncer') {
+                const retryCwd = typeof again.cwd === 'string' && again.cwd !== ''
+                    ? again.cwd : process.cwd();
+                outcome = classifyRun(runArgv(again.argv, retryCwd));
+                if (outcome.kind === 'failure' && outcome.reason === firstReason) {
+                    return {
+                        ok: false,
+                        reason: 'repeated-failure',
+                        cause: firstReason,
+                        next: outcome.body.next !== undefined ? outcome.body.next : '',
+                        executed,
+                    };
+                }
+            }
+        }
+        if (outcome.kind === 'unclear') {
+            return failAdvance('unclear-result', outcome.detail, 'Re-read state with coordinate next or coordinate status and run only the action it names; '
+                + 'do not re-run the same mutation argv first.', executed);
+        }
+        if (outcome.kind === 'failure') {
+            return failFromBody(outcome.body, outcome.reason, executed);
+        }
+        const entry = { action, exit: outcome.exit };
+        if (typeof step.task === 'string' && step.task !== '')
+            entry.task = step.task;
+        executed.push(entry);
+    }
+}
+module.exports = { advance };