long-run

1/**
2 * long-run mod — 맵을 미는 세션의 상태줄과 Stop 판정.
3 *
4 * 판정 규칙은 `scripts/lib/guard-core.mjs`, 입력 조립과 문구는 `scripts/lib/mod-view.mjs` 가 소유한다.
5 * 여기는 배선뿐이다: 마커·열린 자식은 `frontier-guard.mjs status` 로 묻고(키 계산을 두 벌로 만들지 않는다),
6 * 컨텍스트는 세션이 잰 값을 쓴다.
7 *
8 * mod 가 안 뜨는 환경(구버전, 조직 정책, `--safe-mode`)에서는 `hooks.json` 의 node Stop 훅이 혼자
9 * 판정한다. mod 가 뜨면 Stop 에 `MOD_FLAG` 를 실어 넘기고 node 훅은 그것을 보고 빠진다.
10 *
11 * 🚨 `classic.Stop` 훅에 `.catch` 를 달지 않는다. 엔진의 기본 처리가 원하는 동작이다 — `next` 전에
12 * 터지면 이 훅만 건너뛰어 표지 없는 Stop 이 node 훅까지 가서 판정되고, `next` 뒤에 터지면 그 결과(통과)가
13 * 선다. 어느 쪽도 막는 쪽으로 고장나지 않는다.
14 *
15 * @param {(event: string, ...rest: unknown[]) => unknown} on
16 */
17
18import { MOD_FLAG } from '../scripts/lib/guard-core.mjs';
19import { parseStatus, statusLine, stopVerdict } from '../scripts/lib/mod-view.mjs';
20
21/** 이 worktree 의 마커 경로. 첫 status 에서 배운다 — 마커가 없는 동안은 bd 를 부르지 않고 파일만 본다. */
22let markerPath = null;
23
24async function readStatus($, cwd) {
25  const cli = `${$.plugin.root}/scripts/frontier-guard.mjs`;
26  try {
27    const { exitCode, stdout } = await $.process.run(['node', cli, 'status'], cwd ? { cwd } : undefined);
28    if (exitCode !== 0) return null;
29    const status = parseStatus(stdout);
30    if (status?.markerPath) markerPath = status.markerPath;
31    return status;
32  } catch {
33    return null;
34  }
35}
36
37/** 선언이 없다고 확실할 때만 false. 경로를 아직 모르면 status 로 확인해야 한다. */
38async function mayBeClaimed($) {
39  if (!markerPath) return true;
40  try {
41    return await $.fs.exists(markerPath);
42  } catch {
43    return true;
44  }
45}
46
47async function refreshStatusLine($, usage) {
48  if (!(await mayBeClaimed($))) {
49    $.ui.status(undefined);
50    return;
51  }
52  $.ui.status(statusLine(await readStatus($), usage));
53}
54
55export function register(on) {
56  // 인계받은 세션은 시작부터 선언을 물려받으므로 첫 프롬프트 전에 그린다.
57  on('session.start', async ($, e, next) => {
58    await refreshStatusLine($, await $.session.usage());
59    return next(e);
60  });
61
62  // map-run 이 claim 한 다음 턴부터 나타나고, 가드가 마커를 지우면 사라진다.
63  on('session.measure', async ($, e, next) => {
64    await refreshStatusLine($, e);
65    return next(e);
66  });
67
68  on('classic.Stop', async ($, e, next) => {
69    const result = await next({ ...e, [MOD_FLAG]: true });
70    if (result?.block || !(await mayBeClaimed($))) return result;
71
72    const status = await readStatus($, e.cwd);
73    const verdict = stopVerdict({
74      status,
75      usage: await $.session.usage(),
76      stopHookActive: e.stop_hook_active === true,
77    });
78    if (verdict.clear) {
79      await $.process.run(['node', `${$.plugin.root}/scripts/frontier-guard.mjs`, 'clear'], e.cwd ? { cwd: e.cwd } : undefined);
80      $.ui.status(undefined);
81    }
82    return verdict.block ? { ...result, block: verdict.reason } : result;
83  });
84}
85

1/**
2 * 프론티어 가드의 순수 로직 — «이 세션이 지금 멈춰도 되는가» 를 판정한다.
3 *
4 * 규약은 사람이 지키는 것이 아니라 하네스가 막는 것이다. 맵의 운영 규약이 «묻지 않고 완료조건까지
5 * 간다» 라고 적어 두었어도, 티켓 하나를 닫은 자리에서 «다음으로 갈까요?» 로 멈추는 일이 반복됐다.
6 * 그래서 Stop hook 이 그 자리를 막는다.
7 *
8 * ## 판정의 축은 셋이다
9 *
10 * | 축 | 근거 |
11 * |---|---|
12 * | 이 세션이 미는 맵이 있는가 | 마커 파일(`claim` 이 쓴다). 없으면 가드는 아무것도 안 한다 |
13 * | 컨텍스트가 얼마나 찼는가 | 트랜스크립트의 마지막 `usage` — 추정이 아니라 API 가 센 값이다 |
14 * | 프론티어가 남았는가 | `bd list --parent <epic>` 의 열린 자식 |
15 *
16 * 🚨 **`stop_hook_active` 면 무조건 통과시킨다.** 그 값이 참이라는 것은 이미 이 훅 때문에 한 번
17 * 되돌려 보냈다는 뜻이다. 거기서 또 막으면 세션이 영영 안 끝난다. 즉 가드의 힘은 «멈춤 시도마다
18 * 한 번 되민다» 이지 «못 멈추게 한다» 가 아니다 — 그 선을 넘으면 사용자가 Ctrl+C 로만 빠져나오게 된다.
19 */
20
21/** 컨텍스트가 이만큼 차면 이어가지 말고 넘긴다. 맵 운영 규약의 «50% 에서 session-handoff». */
22export const HANDOFF_RATIO = 0.5;
23
24/** 인계를 지시할 때 부를 스킬. 문구를 여기 한 곳에 둬서 스킬 이름이 바뀔 때 갈라지지 않게 한다. */
25export const HANDOFF_SKILL = '/long-run:session-handoff';
26
27/**
28 * mod 가 판정을 맡은 Stop 에 붙이는 필드. mod 는 `next({ ...e, [MOD_FLAG]: true })` 로 넘기고, 그 아래에서
29 * 도는 node 훅은 stdin 에서 이 필드를 보고 빠진다. 환경변수가 아니라 이벤트에 싣는 이유: 환경변수는
30 * mod 가 꺼진 뒤에도 프로세스에 남아 node 훅까지 입을 다물게 만든다.
31 */
32export const MOD_FLAG = 'long_run_mod';
33
34/** 이 Stop 을 mod 가 이미 판정했는가. 표지가 없으면 mod 가 안 뜬 환경이므로 node 훅이 판정한다. */
35export const isDelegatedToMod = (input) => input?.[MOD_FLAG] === true;
36
37/** 「멈춰도 되는 자리」 중 승인이 필요한 바깥 쓰기의 예시. */
38const EXTERNAL_WRITES = '이슈 트래커·문서·push·외부 시스템';
39
40/**
41 * 멈춰도 되는 네 자리. 문구는 헌장의 운영 규약과 **같아야 한다** — 훅이 되밀 때 헌장과 다른 목록을
42 * 내밀면 세션이 어느 쪽을 따를지 모른다.
43 *
44 * 넷째 항이 있는 이유: 목적지를 바꾸는 갈림길에서까지 「묻지 않는다」로 되밀면, 되돌리기 비싼 선택을
45 * 에이전트가 혼자 확정하게 된다. 반대로 국소 선택(어느 쪽이어도 완료 조건의 참/거짓이 같은 것)까지
46 * 물으면 맵이 굴러가지 않으므로, 그 둘을 가르는 기준은 헌장이 소유한다.
47 */
48const STOP_PLACES = (pct) =>
49  `프론티어가 비었다 · 컨텍스트 ${pct} 초과(그때는 session-handoff) · 승인이 필요한 바깥 쓰기(${EXTERNAL_WRITES}) · ` +
50  `목적지·완료조건을 바꾸는 갈림길(A/B). 국소 선택(A.1/A.2)은 묻지 않고 고르고 이유를 close reason 에 남긴다`;
51
52/**
53 * 모델 이름에 창 크기가 실려 온다 — `claude-opus-5[1m]`. 없으면 표준 창으로 본다.
54 *
55 * 🚨 **`message.model` 에는 그 접미사가 없다.** 거기에는 `claude-opus-5` 만 실리고, 창을 말하는 것은
56 * 트랜스크립트의 `attachment.identity.modelId` 다(실측: 같은 세션에서 앞은 `claude-opus-5`,
57 * 뒤는 `claude-opus-5[1m]`). 앞만 보면 100만 창 세션을 20만으로 재서 **한참 이른 인계**를 시킨다.
58 */
59export function contextLimitOf(model) {
60  if (typeof model === 'string' && /\[1m\]/i.test(model)) return 1_000_000;
61  return 200_000;
62}
63
64/**
65 * 한 턴이 실제로 점유한 컨텍스트. 캐시에서 읽은 토큰도 창을 차지한다 — `cache_read` 를 빼면
66 * 긴 세션이 영원히 «비어 있음» 으로 보인다.
67 */
68export function contextTokensOf(usage) {
69  if (!usage) return 0;
70  return (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0);
71}
72
73/**
74 * 트랜스크립트(jsonl)에서 마지막 `usage` 와 모델을 뽑는다.
75 *
76 * 줄 하나가 깨져 있어도 멈추지 않는다 — 훅이 죽으면 세션이 못 멈추는 것이 아니라 가드가 조용히
77 * 사라지므로, 파싱 실패는 «모름» 으로 떨어뜨린다.
78 */
79export function readTranscriptTail(text) {
80  let usage = null;
81  let model = null;
82  for (const line of String(text ?? '').split('\n')) {
83    if (!line) continue;
84    let json;
85    try {
86      json = JSON.parse(line);
87    } catch {
88      continue;
89    }
90    if (json?.message?.usage) usage = json.message.usage;
91    // 창을 아는 쪽이 이긴다 — `attachment.identity.modelId` 에만 `[1m]` 이 붙는다(위 함수 주석).
92    const identity = json?.attachment?.identity?.modelId;
93    if (identity) model = identity;
94    else if (json?.message?.model && !model) model = json.message.model;
95  }
96  return { usage, model };
97}
98
99/**
100 * 멈춰도 되는가.
101 *
102 * @param {{
103 *   marker: {epic: string} | null,
104 *   contextTokens: number,
105 *   contextLimit: number,
106 *   openChildren: {id: string, priority?: number}[],
107 *   stopHookActive: boolean,
108 *   isStopEvent?: boolean,
109 *   handoffRatio?: number,
110 * }} input
111 * @returns {{block: boolean, reason?: string, clear?: boolean, ratio: number}}
112 */
113export function decide({ marker, contextTokens, contextLimit, openChildren, stopHookActive, isStopEvent = true, handoffRatio = HANDOFF_RATIO }) {
114  const ratio = contextLimit > 0 ? contextTokens / contextLimit : 0;
115  const pct = `${Math.round(ratio * 100)}%`;
116
117  // 🚨 Stop 이 아닌 이벤트에서는 아무 말도 하지 않는다. 배선이 `PostToolUse` 로 들어가면 파일을
118  // 고칠 때마다 판정이 터져 «작업 중» 을 «멈추려 함» 으로 오해한 잔소리가 된다(실측으로 밟았다).
119  if (!isStopEvent) return { block: false, ratio };
120  // 🚨 두 번째 막음은 없다(머리말).
121  if (stopHookActive) return { block: false, ratio };
122  // 가드는 선언한 세션에만 붙는다 — 맵을 밀고 있지 않은 세션까지 막으면 못 쓰는 도구가 된다.
123  if (!marker?.epic) return { block: false, ratio };
124
125  const open = openChildren ?? [];
126  if (open.length === 0) {
127    return { block: false, clear: true, ratio };
128  }
129
130  if (ratio >= handoffRatio) {
131    return {
132      block: true,
133      ratio,
134      reason:
135        `컨텍스트 ${pct} 다(${contextTokens.toLocaleString()} / ${contextLimit.toLocaleString()}). ${marker.epic} 의 프론티어가 ` +
136        `${open.length}건 남았지만 이 세션에서 더 밀지 않는다 — **${HANDOFF_SKILL} 로 넘긴다**(\`--bd ${marker.epic}\`). ` +
137        `🚨 마커는 지우지 않는다 — worktree 당 파일 하나라 지우면 새 세션이 가드 없이 출발한다. ` +
138        `보내는 세션은 지우지 않아도 멈출 수 있다(두 번째 멈춤은 무조건 통과한다). ` +
139        `사용자에게 넘길지 묻지 않는다 — 그것이 규약이다.`,
140    };
141  }
142
143  return {
144    block: true,
145    ratio,
146    reason:
147      `${marker.epic} 의 프론티어가 ${open.length}건 남았다(${open.map((c) => c.id).join(', ')}). ` +
148      `**곧장 다음 티켓을 \`bd update <id> --claim\` 하고 이어간다 — «다음으로 갈까요?» 라고 묻지 않는다.** ` +
149      `컨텍스트는 ${pct} 라 아직 넘길 자리가 아니다. 멈춰도 되는 자리는 넷뿐이다: ` +
150      `${STOP_PLACES(`${Math.round(handoffRatio * 100)}%`)}. ` +
151      `그 넷이 아니면 보고는 작업 사이가 아니라 세션 끝에 한 번 한다.`,
152  };
153}
154

1/**
2 * mod(`hooks/register.mjs`)의 순수 로직 — `frontier-guard.mjs status` 출력과 세션의 컨텍스트 측정값을
3 * 상태줄 문구와 Stop 판정으로 바꾼다.
4 *
5 * 마커 경로·열린 자식은 CLI 가 계속 소유한다. mod 는 `node:` 모듈을 못 쓰므로 키 계산을 다시 짜면
6 * 같은 규칙이 두 벌이 된다. mod 가 새로 가져오는 것은 컨텍스트뿐이다 — 세션이 실제 창 크기와 점유를
7 * 알려주므로 트랜스크립트를 파싱하거나 모델 이름에서 창을 추측할 필요가 없다.
8 *
9 * `node:` import 를 두지 않는다. 이 파일은 hooks module 이 import 하므로 mod 의 실행 환경에서 돌아야 한다.
10 */
11
12import { HANDOFF_RATIO, contextLimitOf, decide } from './guard-core.mjs';
13
14/**
15 * `frontier-guard.mjs status` 의 stdout 을 읽는다. 못 읽으면 null(«모름»)이고, 가드는 모를 때 통과시킨다.
16 *
17 * @param {string | undefined} stdout
18 * @returns {{markerPath: string, marker: {epic: string} | null, open: string[]} | null}
19 */
20export function parseStatus(stdout) {
21  try {
22    const json = JSON.parse(stdout);
23    return json && typeof json === 'object' ? json : null;
24  } catch {
25    return null;
26  }
27}
28
29/** 세션 측정값에서 판정 입력의 컨텍스트 두 값. 측정 전이면 점유 0 — 인계가 아니라 다음 티켓으로 되민다. */
30function contextOf(usage) {
31  const context = usage?.context;
32  return {
33    contextTokens: context?.tokens ?? 0,
34    contextLimit: context?.window > 0 ? context.window : contextLimitOf(null),
35  };
36}
37
38/**
39 * 상태줄 한 줄. 선언하지 않은 세션이면 undefined(상태줄을 지운다).
40 *
41 * @param {ReturnType<typeof parseStatus>} status
42 * @param {{context?: {tokens?: number, window: number, percent?: number}} | null} usage
43 * @returns {string | undefined}
44 */
45export function statusLine(status, usage) {
46  const epic = status?.marker?.epic;
47  if (!epic) return undefined;
48  const parts = [`long-run ${epic}`, `프론티어 ${(status.open ?? []).length}`];
49  const percent = usage?.context?.percent;
50  if (typeof percent !== 'number') {
51    parts.push('컨텍스트 측정 전');
52  } else {
53    parts.push(`컨텍스트 ${percent}%`);
54    if (percent >= HANDOFF_RATIO * 100) parts.push('인계할 때');
55  }
56  return parts.join(' · ');
57}
58
59/**
60 * Stop 판정. 판정 규칙은 `decide()` 그대로고, 입력만 status 출력과 세션 측정값에서 만든다.
61 *
62 * @param {{status: ReturnType<typeof parseStatus>, usage: object | null, stopHookActive: boolean}} input
63 * @returns {{block: boolean, reason?: string, clear?: boolean, ratio: number}}
64 */
65export function stopVerdict({ status, usage, stopHookActive }) {
66  return decide({
67    marker: status?.marker ?? null,
68    ...contextOf(usage),
69    openChildren: (status?.open ?? []).map((id) => ({ id })),
70    stopHookActive,
71  });
72}
73