@kaydash9999/banker-plugins 0.16.1 → 0.16.3

package/hooks/progress.mjs

@@ -9,11 +9,20 @@
  * a call shows a short description under the list; a press on a step's arrow folds or unfolds its
  * calls.
  *
+ * Claude 5 models get no task list tool in Claude Code 2.1.296 (only older models, a background
+ * job, or CLAUDE_CODE_ENABLE_TODO_TOOLS do), so there prompts are the steps. Above them the pane
+ * shows the plan file the session touched last (progress-plan.mjs reads it), as steps of its own.
+ * A prompt's harness tags leave its title, and a background task's notice (or a teammate's message)
+ * goes on with the last prompt's step instead of becoming one: the step runs again while it does,
+ * and keeps its own end and time.
+ *
  * `/progress` and `/progress show` toggle the pane, `on` and `off` set it. The command is
  * registered `immediate`, so it answers while a turn runs. An engine without mods never loads
  * this file: commands/progress.md and hooks/progress-fallback.mjs answer there instead.
  */
 
+import { cells, clip, fit, isPlanPath, parsePlan, pick, readPrompt } from './progress-plan.mjs';
+
 const COMMAND = 'progress';
 const PANE = 'banker-progress';
 const TITLE = '진행 상황';
@@ -22,6 +31,9 @@ const HINT = '단계나 하위 항목을 누르면 설명이 여기에 나옵니
 const MAX_STEPS = 50;
 const MAX_KEPT_CALLS = 200;
 const MAX_SHOWN_CALLS = 30;
+const MAX_SHOWN_PLAN = 20;
+// The calls whose file, when it is a plan file, becomes the plan the pane shows.
+const PLAN_TOUCH = new Set(['Write', 'Edit', 'MultiEdit', 'Read', 'NotebookEdit']);
 // The id of the step made for work already under way when the module loaded mid-turn.
 const AT_HAND = 'now';
 // Bookkeeping calls: they become steps, not calls under a step.
@@ -30,6 +42,13 @@ const STATUS = {
   running: '진행 중', in_progress: '진행 중', pending: '대기', done: '완료', completed: '완료',
   stopped: '중단됨', refused: '거절됨', failed: '오류로 끝남',
 };
+// A plan step's state, as progress-plan.mjs names it.
+const PLAN_STATUS = { completed: '완료', in_progress: '진행 중', pending: '대기', failed: '실패', blocked: '막힘' };
+// A notice's row, by the status it came with.
+const NOTICE = {
+  completed: '백그라운드 작업 끝남', failed: '백그라운드 작업 실패', stopped: '백그라운드 작업 중지됨',
+  killed: '백그라운드 작업 중지됨', message: '팀원 메시지',
+};
 // How a prompt's turn ended (turn.complete's reason), as its step's state.
 const ENDED = { answer: 'done', aborted: 'stopped', refusal: 'refused', error: 'failed' };
 // Why a hook failed (the kind of the engine's HookFailure), for a failure that brings no message.
@@ -48,15 +67,12 @@ const tally = () => ({ calls: [], count: 0, failed: 0 });
 const looseStep = () => ({ key: 'loose', title: '작업 목록 밖의 작업', ...tally() });
 
 // `rev` counts the task changes (TaskCreate, TaskUpdate) taken in, to tell a stale TaskList or TaskGet.
-export const freshState = () => ({ turns: [], tasks: new Map(), todos: null, loose: looseStep(), open: new Set(), selected: null, seq: 0, rev: 0 });
-
-// One line of plain text, cut to `n` characters. Control characters go too: a pasted escape
-// sequence is not text to show.
-const clip = (text, n) => {
-  const s = String(text ?? '').replace(/\p{Cc}+/gu, ' ').replace(/\s+/g, ' ').trim();
-  const chars = [...s];
-  return chars.length > n ? `${chars.slice(0, n - 1).join('')}…` : s;
-};
+// `plan` is the plan last read from `planPath`, `planShut` whether its steps are folded. `touch` counts
+// the calls that touched a plan file and `taken` is the touch the plan came from, to tell a read that
+// a newer one overtook.
+export const freshState = () => ({ turns: [], tasks: new Map(), todos: null, loose: looseStep(), open: new Set(), selected: null, seq: 0, rev: 0,
+  plan: null, planPath: null, planShut: false, touch: 0, taken: 0 });
+
 const tail = (path) => String(path).split(/[\\/]/).filter(Boolean).slice(-2).join('/');
 const seconds = (ms) => {
   const all = Math.max(0, Math.round(ms / 1000));
@@ -72,14 +88,39 @@ export function callLabel(e) {
 
 // ── what the module learns from the session ──────────────────────────────────
 
-// A prompt as a step. A prompt whose end never came is done where the next one starts.
-function addTurn(s, e, now) {
-  for (const t of s.turns) if (t.status === 'running') Object.assign(t, { status: 'done', endedAt: now });
-  s.turns.push({ key: `t-${e.turnId}`, id: e.turnId, title: clip(e.text, 60) || '(이어서 진행)', text: String(e.text ?? ''),
-    startedAt: now, endedAt: null, status: 'running', ...tally() });
+// A prompt as a step. A prompt whose end never came is done where the next one starts, and so are
+// the notices still running on a step. `notices` holds the turns of the notices running on it.
+function addTurn(s, turnId, text, now, title) {
+  for (const t of s.turns) {
+    if (t.status === 'running') Object.assign(t, { status: 'done', endedAt: now });
+    t.notices.clear();
+  }
+  s.turns.push({ key: `t-${turnId}`, id: turnId, title: title ?? (clip(text, 60) || '(이어서 진행)'), text,
+    startedAt: now, endedAt: null, status: 'running', notices: new Set(), ...tally() });
   if (s.turns.length > MAX_STEPS) s.turns.shift();
 }
 
+// A step's state on the pane: a prompt's step runs again while a notice runs on it.
+const statusOf = (step) => (step.notices?.size ? 'running' : step.status);
+
+// A row under a step that is no tool call: it counts as none. `ok` false shows it failed.
+function note(s, step, label, ok, now) {
+  step.calls.push({ key: `c-${++s.seq}`, tool: '', label: clip(label, 60), detail: clip(label, 240), isNote: true,
+    startedAt: now, endedAt: now, ok, steps: [step] });
+  if (step.calls.length > MAX_KEPT_CALLS) step.calls.shift();
+}
+
+// A background task's end (or a teammate's message) opens a turn of its own: it runs on the last
+// prompt's step, under which a row says so, and the list stays as it is. Before any prompt it is a
+// step of its own.
+function noticeTurn(s, e, said, now) {
+  const word = pick(NOTICE, said.status) ?? '백그라운드 작업 알림';
+  if (!s.turns.length) addTurn(s, e.turnId, '', now, said.status === 'message' ? word : '백그라운드 작업 알림');
+  const t = s.turns.at(-1);
+  if (t.id !== e.turnId) t.notices.add(e.turnId);
+  if (said.text) note(s, t, `${word}: ${said.text}`, said.status !== 'failed', now);
+}
+
 // The task list's items, which are the steps while there are any: TodoWrite's, else the Tasks list's.
 function listItems(s) {
   return s.todos?.length ? s.todos : [...s.tasks.values()];
@@ -97,14 +138,22 @@ function dropFinished(s) {
 }
 
 export function startTurn(s, e, now) {
+  const said = readPrompt(e.text);
+  if (said.kind === 'notice') return noticeTurn(s, e, said, now);
   dropFinished(s);
-  addTurn(s, e, now);
+  addTurn(s, e.turnId, said.text, now);
 }
 
-// A main turn's end; a subagent's (it carries an agentId) ends no step. A turn the module never
-// saw start (it loaded mid-turn) ends the step for the work at hand.
+// A main turn's end; a subagent's (it carries an agentId) ends no step, and a notice's leaves its
+// step's own end as it was. A turn the module never saw start (it loaded mid-turn) ends the step for
+// the work at hand.
 export function endTurn(s, e, now) {
   if (e.agentId) return;
+  const host = s.turns.find((x) => x.notices.has(e.turnId));
+  if (host) {
+    host.notices.delete(e.turnId);
+    return;
+  }
   const t = s.turns.find((x) => x.id === e.turnId) ?? s.turns.find((x) => x.id === AT_HAND && x.status === 'running');
   if (!t) return;
   t.status = ENDED[e.reason] ?? 'failed';
@@ -118,7 +167,7 @@ function owners(s, now) {
   const items = listItems(s);
   const task = [...items].reverse().find((t) => t.status === 'in_progress');
   const first = task ?? (items.length ? s.loose : null);
-  if (!s.turns.length) addTurn(s, { turnId: AT_HAND, text: '지금 하는 작업' }, now);
+  if (!s.turns.length) addTurn(s, AT_HAND, '지금 하는 작업', now);
   return first ? [first, s.turns.at(-1)] : [s.turns.at(-1)];
 }
 
@@ -249,6 +298,50 @@ export function noteTaskTool(s, e, r, now, since) {
   if (CHANGES.has(e.tool)) s.rev += 1;
 }
 
+// The plan file a call touched, with the touch's count, when it is one and the call went through:
+// a write by anyone, a read by the session itself (an agent reviewing a plan does not make it the plan).
+export function planTouched(s, e, call) {
+  const path = e.file_path ?? e.notebook_path;
+  if (!call?.ok || !PLAN_TOUCH.has(e.tool) || !isPlanPath(path) || (e.tool === 'Read' && e.agentId)) return null;
+  s.touch += 1;
+  return { path, touch: s.touch };
+}
+
+function parsed(path, text) {
+  try {
+    return typeof text === 'string' ? parsePlan(path, text) : null;
+  } catch {
+    return null; /* a plan the parser trips on leaves the pane as it was */
+  }
+}
+
+// Whether a read may change the plan: a read for a touch newer than the one the plan came from, or a
+// read again of the plan's own file (begun when `since` touches were counted) that no touch taken
+// in the meantime overtook.
+function current(s, path, { touch, since }) {
+  if (touch !== undefined) return touch > s.taken;
+  return path === s.planPath && s.taken <= since;
+}
+
+const isPlanKey = (key) => key === 'plan' || /^p-\d+$/.test(key ?? '');
+
+// Whether what was read stays off the pane: no plan, or a file with no steps in place of a plan that
+// has some (a review written beside it).
+const keepsOff = (s, path, plan) => !plan || (path !== s.planPath && !plan.total && Boolean(s.plan?.total));
+
+// What a read of a plan file found (`read` is `{ touch }` for a touch's read, `{ since }` for a read
+// again). A file that cannot be read or is no plan leaves the plan as it was.
+export function takePlan(s, path, text, read = {}) {
+  if (!current(s, path, read)) return;
+  const plan = parsed(path, text);
+  if (keepsOff(s, path, plan)) return;
+  const moving = path !== s.planPath;
+  if (read.touch !== undefined) s.taken = read.touch;
+  if (moving && isPlanKey(s.selected)) s.selected = null;
+  s.planPath = path;
+  s.plan = { ...plan, path, steps: plan.steps.map((st, i) => ({ ...st, key: `p-${i}`, planStep: true })) };
+}
+
 // ── what the pane shows ──────────────────────────────────────────────────────
 
 // Nothing seen yet: one step that says so, with no state word beside it.
@@ -257,7 +350,8 @@ const IDLE = { key: 'idle', title: '진행 중인 작업 없음', status: null,
 // The calls outside the list are in progress while calls still go there: no task is in progress
 // and the prompt runs.
 function looseStatus(s, items) {
-  const going = !items.some((t) => t.status === 'in_progress') && s.turns.at(-1)?.status === 'running';
+  const last = s.turns.at(-1);
+  const going = !items.some((t) => t.status === 'in_progress') && last !== undefined && statusOf(last) === 'running';
   return going ? 'running' : 'done';
 }
 
@@ -272,9 +366,10 @@ function callCount(step) {
 }
 
 function stepState(step, now) {
-  const doing = step.status === 'in_progress' && step.activeForm ? `(${clip(step.activeForm, 40)})` : '';
+  const status = statusOf(step);
+  const doing = status === 'in_progress' && step.activeForm ? `(${clip(step.activeForm, 40)})` : '';
   const time = Number.isFinite(step.startedAt) ? `, ${seconds((step.endedAt ?? now) - step.startedAt)}` : '';
-  return `${STATUS[step.status] ?? step.status}${doing}${time}`;
+  return `${STATUS[status] ?? status}${doing}${time}`;
 }
 
 function stepWords(step, now) {
@@ -285,54 +380,127 @@ function stepWords(step, now) {
 }
 
 function callWords(call, now) {
+  if (call.isNote) return `${call.detail.replace(/[.!?。]+$/, '')}.`;
   const state = call.ok === null ? '실행 중' : call.ok ? '성공' : '실패';
   const who = call.isAgent ? '하위 에이전트의 ' : '';
   return `${who}${call.tool}${call.detail ? `: ${call.detail}` : ''}. ${state}, ${seconds((call.endedAt ?? now) - call.startedAt)}.`;
 }
 
-// What the person pressed last, while it is still on the pane: a step, or a call under one.
+function planWords(plan) {
+  const where = `계획 파일: ${clip(plan.path.split(/[\\/]/).filter(Boolean).slice(-3).join('/'), 120)}`;
+  const cut = plan.cut ? ' 파일이 길어 앞부분만 읽었습니다.' : '';
+  if (!plan.total) return `${where}. 단계를 찾지 못했습니다.${cut}`;
+  const done = plan.hasStates ? `, 완료 ${plan.done}개` : '';
+  return `${where}. 단계 ${plan.total}개${done}.${cut}`;
+}
+
+function planStepWords(st) {
+  const what = st.text.replace(/[.!?。]+$/, '');
+  return st.status ? `${what}. ${PLAN_STATUS[st.status]}.` : `${what}.`;
+}
+
+// What the person pressed last, while it is still on the pane: the plan or one of its steps, a
+// step, or a call under one.
 function pressed(s) {
+  if (s.plan && s.selected === 'plan') return { key: 'plan', isPlan: true };
+  const plan = s.plan?.steps.find((st) => st.key === s.selected);
+  if (plan) return plan;
   const all = steps(s);
   return all.find((x) => x.key === s.selected) ?? all.flatMap((x) => x.calls).find((c) => c.key === s.selected);
 }
 
+function itemWords(s, item, now) {
+  if (item.isPlan) return planWords(s.plan);
+  if (item.planStep) return planStepWords(item);
+  return item.tool !== undefined ? callWords(item, now) : stepWords(item, now);
+}
+
 // The description under the list: the pressed step's or call's, or how to get one.
 export function describe(s, now) {
   const item = pressed(s);
-  if (item) return item.tool ? callWords(item, now) : stepWords(item, now);
+  if (item) return itemWords(s, item, now);
   const all = steps(s);
   return all.length === 1 && all[0].key === 'idle' ? stepWords(IDLE, now) : HINT;
 }
 
+// A label cut so that it, the cells before it and the words after it fit on one row of the pane.
+const room = (label, act, before, after) => fit(label, (act.cols ?? Infinity) - before - (after ? cells(after) + 1 : 0));
+
 function callRows(ui, step, act) {
   const { Box, Text, Button } = ui;
   const shown = step.calls.slice(-MAX_SHOWN_CALLS);
-  const rows = shown.map((c) => Box({ key: `row-${c.key}`, flexDirection: 'row', columnGap: 1, paddingLeft: 4, children: [
-    Button({ key: c.key, label: c.label, plain: true, dimColor: c.ok !== false, onPress: () => act.select(c.key) }),
-    Text({ children: [c.ok === null ? '실행 중' : c.ok ? '' : '실패'], dimColor: true }),
-  ] }));
+  const rows = shown.map((c) => {
+    const state = c.ok === null ? '실행 중' : c.ok ? '' : '실패';
+    return Box({ key: `row-${c.key}`, flexDirection: 'row', columnGap: 1, paddingLeft: 4, children: [
+      Button({ key: c.key, label: room(c.label, act, 4, state), plain: true, dimColor: c.ok !== false, onPress: () => act.select(c.key) }),
+      ...stateWord(ui, state, false),
+    ] });
+  });
   const hidden = step.calls.length - shown.length;
   return hidden ? [Box({ paddingLeft: 4, children: [Text({ children: [`앞의 ${hidden}개는 줄였습니다`], dimColor: true })] }), ...rows] : rows;
 }
 
+// A row's state word, bold while it runs; none where the state is empty, so no gap is kept for it.
+function stateWord(ui, state, running) {
+  return state ? [ui.Text({ children: [state], dimColor: !running, bold: running })] : [];
+}
+
 function stepRow(ui, s, step, act) {
   const { Box, Text, Button } = ui;
   const isOpen = s.open.has(step.key);
   const arrow = step.calls.length
     ? Button({ key: `arrow-${step.key}`, label: isOpen ? '▾' : '▸', plain: true, onPress: () => act.fold(step.key) })
     : Text({ children: [' '] });
-  const running = step.status === 'running' || step.status === 'in_progress';
+  const status = statusOf(step);
+  const state = STATUS[status] ?? status ?? '';
   return Box({ key: `row-${step.key}`, flexDirection: 'row', columnGap: 1, children: [
     arrow,
-    Button({ key: step.key, label: step.title, plain: true, onPress: () => act.select(step.key) }),
-    Text({ children: [STATUS[step.status] ?? step.status ?? ''], dimColor: !running, bold: running }),
+    Button({ key: step.key, label: room(step.title, act, 2, state), plain: true, onPress: () => act.select(step.key) }),
+    ...stateWord(ui, state, status === 'running' || status === 'in_progress'),
+  ] });
+}
+
+// The plan's row: its title in bold (a Button draws its Text children in place of its label) and
+// how far along it is.
+function planHead(ui, s, act) {
+  const { Box, Text, Button } = ui;
+  const { plan } = s;
+  const count = !plan.total ? '단계 없음' : plan.hasStates ? `${plan.done}/${plan.total} 완료` : `${plan.total}단계`;
+  const arrow = plan.steps.length
+    ? Button({ key: 'arrow-plan', label: s.planShut ? '▸' : '▾', plain: true, onPress: () => act.foldPlan() })
+    : Text({ children: [' '] });
+  const label = room(`계획: ${plan.title}`, act, 2, count);
+  return Box({ key: 'row-plan', flexDirection: 'row', columnGap: 1, children: [
+    arrow,
+    Button({ key: 'plan', label, plain: true, onPress: () => act.select('plan'), children: [Text({ bold: true, children: [label] })] }),
+    Text({ children: [count], dimColor: true }),
   ] });
 }
 
-// The pane's tree. `ui` is the surface's element table; `act` holds what a press does.
+// The plan's rows: its title, then its first steps unless folded, then a line for the plan's rest.
+function planRows(ui, s, act) {
+  const { Box, Text, Button } = ui;
+  if (!s.plan) return [];
+  const rows = [planHead(ui, s, act)];
+  if (s.planShut) return [...rows, Box({ key: 'plan-gap', marginBottom: 1 })];
+  const shown = s.plan.steps.slice(0, MAX_SHOWN_PLAN);
+  for (const st of shown) {
+    const state = PLAN_STATUS[st.status] ?? '';
+    rows.push(Box({ key: `row-${st.key}`, flexDirection: 'row', columnGap: 1, paddingLeft: 2, children: [
+      Button({ key: st.key, label: room(st.title, act, 2, state), plain: true, onPress: () => act.select(st.key) }),
+      ...stateWord(ui, state, st.status === 'in_progress'),
+    ] }));
+  }
+  const rest = s.plan.total - shown.length;
+  if (rest > 0) rows.push(Box({ key: 'plan-more', paddingLeft: 2, children: [Text({ children: [`외 ${rest}개`], dimColor: true })] }));
+  return [...rows, Box({ key: 'plan-gap', marginBottom: 1 })];
+}
+
+// The pane's tree. `ui` is the surface's element table; `act` holds what a press does and `cols`,
+// the cells across the pane's body (Infinity where the engine gives none).
 export function draw(ui, s, now, act) {
   const { Box, Text } = ui;
-  const rows = [];
+  const rows = planRows(ui, s, act);
   for (const step of steps(s)) {
     rows.push(stepRow(ui, s, step, act));
     if (s.open.has(step.key)) rows.push(...callRows(ui, step, act));
@@ -385,10 +553,21 @@ async function watchCall($, e, next) {
   } finally {
     endCall(call, r, Date.now());
     if (TASK_TOOLS.has(e.tool)) noteTaskTool(s, e, r, Date.now(), since);
+    const touched = planTouched(s, e, call);
+    if (touched) takePlan(s, touched.path, await readText($, touched.path), { touch: touched.touch });
     $.ui.invalidate('ui.render');
   }
 }
 
+// A file's text, or null where it cannot be read (missing, over the engine's 4 MiB, refused).
+async function readText($, path) {
+  try {
+    return await $.fs.read(path);
+  } catch {
+    return null;
+  }
+}
+
 // The session's progress, one per loaded module.
 const ref = { s: freshState() };
 
@@ -405,9 +584,12 @@ export function registerProgress(on) {
   on('ui.render', { component: 'Pane' }, async ($, e, next) => {
     if (e.requestId !== PANE) return next(e);
     const redraw = () => $.ui.invalidate('ui.render');
+    const cols = Number.isFinite(e.props?.bodyColumns) ? e.props.bodyColumns : Infinity;
     const act = {
+      cols,
       select: (key) => { ref.s.selected = ref.s.selected === key ? null : key; redraw(); },
       fold: (key) => { if (!ref.s.open.delete(key)) ref.s.open.add(key); redraw(); },
+      foldPlan: () => { ref.s.planShut = !ref.s.planShut; redraw(); },
     };
     return draw($.ui.resolve(e), ref.s, Date.now(), act);
   });
@@ -425,3 +607,13 @@ export function progressTurnStarted(e) {
 export function progressTurnCompleted(e) {
   endTurn(ref.s, e, Date.now());
 }
+
+// The plan file to read again as a turn starts and ends (register.mjs reads it), with the touches
+// counted when the read begins; null without a plan.
+export function progressPlanTarget() {
+  return ref.s.planPath ? { path: ref.s.planPath, since: ref.s.touch } : null;
+}
+
+export function progressPlanRead(target, text) {
+  takePlan(ref.s, target.path, text, { since: target.since });
+}

package/hooks/register.mjs

@@ -16,7 +16,8 @@ import {
   registerGracefulPause,
 } from './graceful-pause.mjs';
 import {
-  SPEC as PROGRESS_SPEC, progressReset, progressTurnCompleted, progressTurnStarted, registerProgress,
+  SPEC as PROGRESS_SPEC, progressPlanRead, progressPlanTarget, progressReset, progressTurnCompleted, progressTurnStarted,
+  registerProgress,
 } from './progress.mjs';
 
 async function engineVersion($) {
@@ -45,6 +46,20 @@ async function registerCommands($) {
   await registerOne($, PROGRESS_SPEC);
 }
 
+// /progress's plan file, read again at a turn's start and end: a ralph PRD or a plan's checkboxes
+// change without a call this module sees. A read that fails keeps the plan as it was.
+async function rereadPlan($) {
+  const target = progressPlanTarget();
+  if (!target) return;
+  let text = null;
+  try {
+    text = await $.fs.read(target.path);
+  } catch {
+    /* missing or refused: the pane keeps the plan it read last */
+  }
+  progressPlanRead(target, text);
+}
+
 // A /graceful-pause request that came after its turn's last model request: a note voids it.
 async function voidLateRequest($, late) {
   try {
@@ -75,6 +90,7 @@ export const register = (on) => {
   on('turn.start', async ($, e, next) => {
     pauseTurnStarted(e);
     progressTurnStarted(e);
+    await rereadPlan($);
     $.ui.invalidate('ui.render');
     return next(e);
   });
@@ -83,6 +99,7 @@ export const register = (on) => {
     const late = pauseTurnCompleted(e);
     if (late) await voidLateRequest($, late);
     progressTurnCompleted(e);
+    await rereadPlan($);
     $.ui.invalidate('ui.render');
     return next(e);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/3d-intro-build/SKILL.md

@@ -50,11 +50,12 @@ description: "스크롤 위치에 맞춰 3D 플라이스루 영상이 움직이
 ```js
 import { resolveCreds, resolveFfmpeg } from './references/azure-adapter.mjs';
 const creds = resolveCreds({ projectDir });     // _source === null 이면 미설정
-// setup 이 ffmpeg 경로를 creds 에 FFMPEG_PATH 로 영속했으면 이 프로세스 env 에 적용(다른 세션/no-PATH 대비)
-if (creds.FFMPEG_PATH && !process.env.FFMPEG_PATH) process.env.FFMPEG_PATH = creds.FFMPEG_PATH;
+// ffmpeg 경로는 resolveFfmpeg 가 셸의 FFMPEG_PATH 와 홈의 설정 파일, 키 파일에서만 찾는다. 프로젝트 키 파일의 값은 쓰지 않는다.
+if (creds._ignored) console.log('프로젝트 키 파일에서 쓰지 않는 값:', Object.keys(creds._ignored).join(', '));   // 값은 출력하지 않는다
 ```
 
 - `creds._source` 가 `null` 이면 크리덴셜이 없다. `3d-intro-setup` 으로 보낸다.
+- `creds._ignored` 가 있으면 프로젝트 키 파일의 `FFMPEG_PATH` 를 쓰지 않은 것이다. 저장소와 함께 온 파일이 실행할 프로그램을 정하지 못하게 막은 것이다. 값은 출력하지 않으니 사람이 파일을 열어 확인하고, 그 경로가 필요하면 `3d-intro-setup` §2 로 홈 설정 파일에 남긴다.
   Claude Code: `/banker:setup` 에서 3d-intro-setup / Codex: `banker-3d-intro-setup`.
 - `resolveFfmpeg()` 가 throw 하면 ffmpeg 가 없다. 같은 `3d-intro-setup` 으로 보낸다.
 - 둘 다 통과해야 다음 단계로 간다.
@@ -64,7 +65,7 @@ if (creds.FFMPEG_PATH && !process.env.FFMPEG_PATH) process.env.FFMPEG_PATH = cre
   `malformed` 는 endpoint 가 https URL 이 아니거나(http 는 이 기기의 localhost 만 허용) 모델이 한 id 가 아닌 항목이다(`reason` 이 `endpoint` 또는 `model`). 영상 단계는 이 항목을 건너뛰고, 모두 `malformed` 면 영상 단계에서 멈춘다. 그러니 유료 스틸을 만들기 전에 사용자에게 알리고 `3d-intro-setup` 으로 고친다.
   Azure 호출도 같다. 키는 https 로만 보내고, `http://` endpoint 는 보내기 전에 막는다(Sora 영상 단계는 `invalid_request`, 이미지 생성 같은 그 밖의 호출은 `HTTP 0 (EINSECURE)` 오류).
   WAN 항목(`WAN_<n>_ENDPOINT`, `WAN_<n>_API_KEY`)이 하나도 없으면 영상은 처음부터 Sora 로 만든다. 이때 정지와 비행 모드(Step 4B)는 쓸 수 없다.
-- 독립 검증(Step 6)에는 Node 용 playwright 패키지와 Chromium 이 필요하다. `npx playwright install chromium`(`setup-playwright`)은 브라우저만 받으므로, 패키지도 `npm i -g playwright` 나 프로젝트의 `npm i -D playwright` 로 설치해 둔다.
+- 독립 검증(Step 6)에는 Node 용 playwright 패키지와 Chromium 이 필요하다. `npx playwright install chromium`(`setup-playwright`)은 브라우저만 받으므로, 패키지도 `npm i -g playwright` 로 설치해 둔다. 사용자가 자기 프로젝트에 `npm i -D playwright` 로 설치했다고 확인해 준 때만 Step 6 에 `--playwright-from-project` 를 준다. 프로젝트에 `node_modules/playwright` 가 있다는 이유만으로는 주지 않는다. 이 옵션이 없으면 프로젝트의 `node_modules` 는 읽지 않는다(저장소가 함께 가져온 코드가 실행되지 않게).
 
 ---