elanous 0.2.0 → 0.2.5

package/src/roles/machine-name.ts

@@ -0,0 +1,48 @@
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { assertJoinedMachineId, readMachineProfile, writeMachineProfile } from './machine-profile.js';
+import { readPrimaryJoin } from '../control-plane/primary.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+
+export const MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+export type MachineNameSource = 'option' | 'config' | 'join' | 'hostname';
+export interface ResolvedMachineName { readonly machine: string; readonly source: MachineNameSource }
+
+export function machineConfigPath(root: string = effectiveInstanceRoot()): string {
+  return join(root, 'control', 'machine.json');
+}
+
+/** A missing or damaged file is not a name — fall through to the next source. */
+export function readConfiguredMachine(root: string = effectiveInstanceRoot()): string | undefined {
+  return readMachineProfile(root)?.id;
+}
+
+export function writeConfiguredMachine(machine: string, root: string = effectiveInstanceRoot()): void {
+  if (!MACHINE_NAME.test(machine)) throw new Error(`invalid machine: ${machine}`);
+  const previous = readMachineProfile(root);
+  writeMachineProfile({ id: machine, duties: previous?.duties ?? [], seats: previous?.seats ?? {} }, root);
+}
+
+/**
+ * The lease uses a configured machine identifier, not the OS hostname.
+ * Explicit wins: option → control/machine.json → valid join ID → lowercased hostname.
+ */
+export function resolveMachineName(opts: {
+  option?: string; root?: string; host?: string;
+  readJoinMachine?: (root: string) => string | undefined;
+} = {}): ResolvedMachineName {
+  const root = opts.root ?? effectiveInstanceRoot();
+  if (opts.option !== undefined) return { machine: opts.option, source: 'option' };
+  const configured = readConfiguredMachine(root);
+  if (configured) {
+    assertJoinedMachineId(configured, root);
+    return { machine: configured, source: 'config' };
+  }
+  const joined = (opts.readJoinMachine ?? ((r) => readPrimaryJoin(r)?.machine))(root);
+  if (joined) {
+    if (!MACHINE_NAME.test(joined)) throw new Error(`invalid joined machine id: ${joined}`);
+    return { machine: joined, source: 'join' };
+  }
+  return { machine: (opts.host ?? hostname()).split('.')[0]!.toLowerCase(), source: 'hostname' };
+}

package/src/roles/machine-profile.ts

@@ -0,0 +1,65 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debug } from '../debug/log.js';
+import { readPrimaryJoin } from '../control-plane/primary.js';
+import { MACHINE_NAME, machineConfigPath } from './machine-name.js';
+
+export interface MachineProfile {
+  id: string;
+  duties: string[];
+  seats: Record<string, { rank: number }>;
+}
+
+export function validSeatRank(rank: number): boolean {
+  return Number.isSafeInteger(rank) && rank >= 1 && rank <= 99;
+}
+
+export function readMachineProfile(root?: string): MachineProfile | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(machineConfigPath(root), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const doc = value as Record<string, unknown>;
+    const id = doc.id === undefined ? doc.machine : doc.id;
+    if (typeof id !== 'string' || !MACHINE_NAME.test(id)) return undefined;
+    const duties = doc.duties === undefined ? [] : doc.duties;
+    const seats = doc.seats === undefined ? {} : doc.seats;
+    if (!Array.isArray(duties) || !duties.every(d => typeof d === 'string' && MACHINE_NAME.test(d)) ||
+        !seats || typeof seats !== 'object' || Array.isArray(seats) ||
+        !Object.entries(seats).every(([seat, value]) => MACHINE_NAME.test(seat) && value && typeof value === 'object' &&
+          !Array.isArray(value) && validSeatRank((value as { rank?: number }).rank as number))) return undefined;
+    return { id, duties: [...duties], seats: { ...seats } as MachineProfile['seats'] };
+  } catch { return undefined; }
+}
+
+export function assertJoinedMachineId(id: string, root?: string): void {
+  const joined = readPrimaryJoin(root)?.machine;
+  if (joined && joined !== id) {
+    throw new Error(`machine id ${id} differs from joined machine ${joined}`);
+  }
+}
+
+export function writeMachineProfile(profile: MachineProfile, root?: string): void {
+  if (typeof profile.id !== 'string' || !MACHINE_NAME.test(profile.id) || !Array.isArray(profile.duties) ||
+      !profile.duties.every(d => typeof d === 'string' && MACHINE_NAME.test(d)) ||
+      !profile.seats || typeof profile.seats !== 'object' || Array.isArray(profile.seats) ||
+      !Object.entries(profile.seats).every(([seat, value]) => MACHINE_NAME.test(seat) && validSeatRank(value?.rank))) {
+    throw new Error('invalid machine profile (id, duties, seats or rank)');
+  }
+  assertJoinedMachineId(profile.id, root);
+  const path = machineConfigPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(profile)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+  debug.log('roles.machine', 'profile-written', { id: profile.id, duties: profile.duties, seats: profile.seats });
+}
+
+export function seatRank(profile: MachineProfile | undefined, seat: string): number | undefined {
+  return profile && Object.hasOwn(profile.seats, seat) ? profile.seats[seat]?.rank : undefined;
+}

package/src/roles/role-lease-read.ts

@@ -0,0 +1,81 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { isAbsentSaid } from './lease-cas.js';
+import { debug } from '../debug/log.js';
+import { gcloudSearchPaths } from '../cli/role-cli.js';
+import { ROLE_LEASE_OBJECT_PATH, parseRoleLease, type RoleLeaseRead } from './role-lease.js';
+
+interface CommandResult {
+  code: number | null;
+  stdout: string;
+  said: string;
+}
+
+async function runGcloud(args: string[]): Promise<CommandResult> {
+  let binary: string | undefined;
+  for (const path of gcloudSearchPaths()) {
+    try { await access(path, constants.X_OK); if ((await stat(path)).isFile()) { binary = path; break; } }
+    catch { /* try the next executable */ }
+  }
+  if (!binary) return { code: null, stdout: '', said: 'gcloud not found' };
+  return new Promise(resolve => {
+    const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '', error = '', settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGKILL');
+      resolve({ code: null, stdout, said: 'gcloud timeout (8s)' });
+    }, 8_000);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => { stdout += chunk; });
+    child.stderr.on('data', (chunk: string) => { stderr += chunk; });
+    child.on('error', (err: Error) => { error = err.message; });
+    child.on('close', code => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      resolve({ code, stdout, said: `${stdout}${stderr}${error}` });
+    });
+  });
+}
+
+export async function readRoleLeaseAsync(bucket: string, { run = runGcloud }: {
+  run?: (args: string[]) => Promise<CommandResult>;
+} = {}): Promise<RoleLeaseRead> {
+  const started = Date.now();
+  let result: RoleLeaseRead;
+  const uri = `${bucket}/${ROLE_LEASE_OBJECT_PATH}`;
+  const describe = async (): Promise<{ kind: 'present'; gen: string } | { kind: 'absent' } | { kind: 'unmeasured'; why: string }> => {
+    const response = await run(['storage', 'objects', 'describe', uri, '--format=value(generation)']);
+    if (response.code !== 0) {
+      return response.code !== null && isAbsentSaid(response.said)
+        ? { kind: 'absent' } : { kind: 'unmeasured', why: response.said.trim() || 'gcloud describe failed' };
+    }
+    const gen = response.stdout.trim();
+    return /^\d+$/.test(gen) ? { kind: 'present', gen } : { kind: 'unmeasured', why: 'invalid GCS generation' };
+  };
+  try {
+    const before = await describe();
+    if (before.kind !== 'present') result = before;
+    else {
+      const body = await run(['storage', 'cat', uri]);
+      if (body.code !== 0) result = { kind: 'unmeasured', why: body.said.trim() || 'gcloud cat failed' };
+      else {
+        const after = await describe();
+        result = after.kind !== 'present' || before.gen !== after.gen
+          ? { kind: 'unmeasured', why: 'lease changed during read; retry' }
+          : parseRoleLease(body.stdout);
+      }
+    }
+  } catch (error) {
+    result = { kind: 'unmeasured', why: error instanceof Error ? error.message : String(error) };
+  }
+  debug.log('control.lease', 'read', {
+    kind: result.kind, holder: result.kind === 'present' ? result.doc.holder : null,
+    generation: result.kind === 'present' ? result.doc.generation : null, ms: Date.now() - started,
+  });
+  return result;
+}

package/src/roles/role-lease.ts

@@ -0,0 +1,63 @@
+export const ROLE_LEASE_OBJECT_PATH = 'lease/control-primary.json';
+
+export interface RoleLeaseDoc {
+  readonly holder: string;
+  /** Document fencing token, distinct from the GCS object's server generation. */
+  readonly generation: number;
+  readonly state: 'held' | 'handing-off';
+  readonly from?: string;
+  readonly renewedAt: number;
+}
+
+export type RoleLeaseRead =
+  | { readonly kind: 'present'; readonly doc: RoleLeaseDoc }
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'unmeasured'; readonly why: string };
+
+export function parseRoleLease(text: string): RoleLeaseRead {
+  if (text.trim() === '') return { kind: 'unmeasured', why: 'empty lease body' };
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { return { kind: 'unmeasured', why: 'invalid lease JSON' }; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { kind: 'unmeasured', why: 'lease is not an object' };
+  const o = value as Record<string, unknown>;
+  if (typeof o.holder !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(o.holder)) return { kind: 'unmeasured', why: 'invalid holder' };
+  if (!Number.isSafeInteger(o.generation) || (o.generation as number) < 1) return { kind: 'unmeasured', why: 'invalid generation' };
+  if (typeof o.renewedAt !== 'number' || !Number.isFinite(o.renewedAt)) return { kind: 'unmeasured', why: 'invalid renewedAt' };
+  if (o.state !== 'held' && o.state !== 'handing-off') return { kind: 'unmeasured', why: 'invalid state' };
+  if (o.state === 'handing-off' && (typeof o.from !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(o.from) || o.from === o.holder)) {
+    return { kind: 'unmeasured', why: 'invalid handoff origin' };
+  }
+  if (o.state === 'held' && 'from' in o) return { kind: 'unmeasured', why: 'held lease has handoff origin' };
+  if ('expiresAt' in o) return { kind: 'unmeasured', why: 'client-side expiration is not supported' };
+  return { kind: 'present', doc: {
+    holder: o.holder, generation: o.generation as number, state: o.state,
+    ...(o.state === 'handing-off' ? { from: o.from as string } : {}), renewedAt: o.renewedAt,
+  } };
+}
+
+function checkedNext(generation: number): number {
+  if (!Number.isSafeInteger(generation + 1)) throw new Error('lease generation exhausted');
+  return generation + 1;
+}
+
+export function nextClaim(prev: RoleLeaseRead, me: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.kind === 'unmeasured') throw new Error(`lease unreadable: ${prev.why}`);
+  if (prev.kind === 'present' && (prev.doc.state !== 'held' || prev.doc.holder !== me)) throw new Error('another machine holds the lease');
+  return { holder: me, generation: checkedNext(prev.kind === 'present' ? prev.doc.generation : 0), state: 'held', renewedAt: now };
+}
+
+export function nextHandoff(prev: RoleLeaseDoc, me: string, to: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'held' || prev.holder !== me) throw new Error('only the current holder can hand off');
+  if (me === to) throw new Error('handoff target must differ from holder');
+  return { holder: to, generation: checkedNext(prev.generation), state: 'handing-off', from: me, renewedAt: now };
+}
+
+export function nextAccept(prev: RoleLeaseDoc, me: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'handing-off' || prev.holder !== me || !prev.from) throw new Error('no handoff addressed to this machine');
+  return { holder: me, generation: checkedNext(prev.generation), state: 'held', renewedAt: now };
+}
+
+export function nextRevert(prev: RoleLeaseDoc, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'handing-off' || !prev.from) throw new Error('no pending handoff to revert');
+  return { holder: prev.from, generation: checkedNext(prev.generation), state: 'held', renewedAt: now };
+}

package/src/roles/role-watch.ts

@@ -0,0 +1,69 @@
+import type { RoleObjectRead } from '../cli/role-cli.js';
+import { validSeatRank } from './machine-profile.js';
+import { nextAccept, nextClaim, parseRoleLease, type RoleLeaseDoc } from './role-lease.js';
+
+export interface WatchState {
+  readonly generation?: number;
+  readonly objectGen?: string;
+  readonly unchangedTicks: number;
+  readonly absentTicks?: number;
+}
+
+export const initialWatchState: WatchState = { unchangedTicks: 0, absentTicks: 0 };
+
+// One missed observation can precede a healthy holder's next 60-second renewal.
+export const MIN_TAKEOVER_TICKS = 2;
+
+export interface WatchConfig {
+  readonly me: string;
+  readonly rank?: number;
+  readonly takeoverTicks: number;
+  readonly now: number;
+}
+
+type TickDecision = {
+  readonly state: WatchState;
+  readonly action: 'claim' | 'renew' | 'takeover' | 'accept' | 'observe';
+  readonly holder?: string;
+  readonly generation?: number;
+  readonly doc?: RoleLeaseDoc;
+  readonly ifGen?: string;
+};
+
+function nextGeneration(generation: number): number {
+  if (!Number.isSafeInteger(generation + 1)) throw new Error('lease generation exhausted');
+  return generation + 1;
+}
+
+/** Only successful server-generation CAS writes establish ownership; timestamps never decide expiry. */
+export function decideTick(state: WatchState, read: RoleObjectRead, cfg: WatchConfig): TickDecision {
+  if (!Number.isSafeInteger(cfg.takeoverTicks) || cfg.takeoverTicks < MIN_TAKEOVER_TICKS) {
+    throw new Error(`takeover-ticks must be at least ${MIN_TAKEOVER_TICKS} (one missed renewal can precede a live holder)`);
+  }
+  if (cfg.rank !== undefined && !validSeatRank(cfg.rank)) throw new Error('rank must be an integer from 1 to 99');
+  if (read.kind === 'unmeasured') throw new Error(`lease unreadable: ${read.why}`);
+  if (read.kind === 'absent') {
+    const absentTicks = (state.absentTicks ?? 0) + 1;
+    const next: WatchState = { unchangedTicks: 0, absentTicks };
+    return cfg.rank !== undefined && absentTicks >= (cfg.rank - 1) * cfg.takeoverTicks
+      ? { state: next, action: 'claim', doc: nextClaim({ kind: 'absent' }, cfg.me, cfg.now), ifGen: '0', holder: cfg.me, generation: 1 }
+      : { state: next, action: 'observe' };
+  }
+  const parsed = parseRoleLease(read.text);
+  if (parsed.kind !== 'present') throw new Error(`lease unreadable: ${parsed.kind === 'unmeasured' ? parsed.why : 'lease absent'}`);
+  const doc = parsed.doc;
+  const changed = state.generation !== doc.generation || state.objectGen !== read.gen;
+  const unchangedTicks = changed ? 0 : state.unchangedTicks + 1;
+  const next: WatchState = { generation: doc.generation, objectGen: read.gen, unchangedTicks, absentTicks: 0 };
+  const base = { state: next, holder: doc.holder, generation: doc.generation };
+  if (doc.holder === cfg.me) {
+    if (doc.state === 'handing-off') return { ...base, action: 'accept', doc: nextAccept(doc, cfg.me, cfg.now), ifGen: read.gen };
+    return { ...base, action: 'renew', doc: nextClaim({ kind: 'present', doc }, cfg.me, cfg.now), ifGen: read.gen };
+  }
+  if (doc.state === 'held' && cfg.rank !== undefined && unchangedTicks >= cfg.takeoverTicks * cfg.rank) {
+    return { ...base, action: 'takeover', doc: {
+      holder: cfg.me, generation: nextGeneration(doc.generation), state: 'held', renewedAt: cfg.now,
+    }, ifGen: read.gen };
+  }
+  return { ...base, action: 'observe' };
+}

package/src/self-dev/ask-launch-flow.ts

@@ -37,31 +37,22 @@ import {
 } from '../self-implement/goal-author-clarification.js';
 import { classifyReauthoredAsk, countMissingAuthoredConstraintMarkers, askGoalTypeDeclaration, declaredGoalType, parseGoalId } from '../self-implement/goal-author.js';
 import { observeFrontNodeEntry } from './graph-front-nodes.js';
+import { emitDecision } from '../live/detail-switch.js';
 import { decomposeSelfDevGoal, type SelfDevDecomposeOptions, type SelfDevDecomposition } from './decompose.js';
 import { observeDecomposerSelection, readFabricDecomposeConfig, selectFabricDecomposer } from './self-orchestrate-runtime.js';
 import type { GoalDocumentClarification } from '../self-implement/goal-author-clarification.js';
-import { getUserConfig } from '../user-config.js';
 
-export type SelfResolveClarificationsSource = 'flag' | 'config' | 'default' | 'config-read-failure';
+export type SelfResolveClarificationsSource = 'flag' | 'default';
 
 interface ResolvedSelfResolveClarifications {
   readonly value: boolean;
   readonly source: SelfResolveClarificationsSource;
 }
 
-function resolveSelfResolveClarifications(
-  explicit: boolean | undefined,
-  readConfig: () => { readonly tools: { readonly selfImplement: { readonly selfResolveClarifications?: boolean } } },
-): ResolvedSelfResolveClarifications {
-  if (explicit !== undefined) return { value: explicit, source: 'flag' };
-  try {
-    const configured = readConfig().tools.selfImplement.selfResolveClarifications;
-    return configured === undefined
-      ? { value: true, source: 'default' }
-      : { value: configured, source: 'config' };
-  } catch {
-    return { value: true, source: 'config-read-failure' };
-  }
+// 설정 졸업 1-c(2026-09-26 · 대표 «기본으로 켜진 것은 옵션으로 두지 않는다»): 설정 키는 폐기됐다 — 읽지 않는다.
+//   프로그램 인자(시험·내부 호출)만 끌 수 있다.
+function resolveSelfResolveClarifications(explicit: boolean | undefined): ResolvedSelfResolveClarifications {
+  return explicit !== undefined ? { value: explicit, source: 'flag' } : { value: true, source: 'default' };
 }
 
 /** 저작기 산출 — `runGoalAuthorCli` 의 반환에서 이 흐름이 «실제로 쓰는» 것만. */
@@ -179,7 +170,6 @@ export interface AskLaunchFlowDeps {
   /** 골 문서 경로를 cwd 기준 상대 경로로 — `--from-clarification` 문법이 그것을 요구한다. */
   relativeToCwd(path: string): string;
   /** Optional config seam: failures resolve to default ON and remain observable. */
-  readSelfResolveClarificationsConfig?(): { readonly tools: { readonly selfImplement: { readonly selfResolveClarifications?: boolean } } };
 }
 
 export interface AskLaunchFlowInput {
@@ -497,10 +487,11 @@ function preflightAxesForObservation(result: LaunchPreflightResult) {
   };
 }
 
-function observeLaunchPreflight(
+export function observeLaunchPreflight(
   deps: AskLaunchFlowDeps,
   phase: 'before-authoring' | 'before-launch',
   decision: ReturnType<typeof decideAskPreflight>,
+  runId?: string,
 ): void {
   const blockers = blockersForObservation(decision.result.blockers);
   deps.log('harness.preflight', {
@@ -510,6 +501,35 @@ function observeLaunchPreflight(
     blockerReasons: blockers,
     axes: preflightAxesForObservation(decision.result),
   }, 'info');
+  if (phase === 'before-authoring') {
+    try { emitAuthoringPreflightDecision(decision, runId); }
+    catch { /* Live detail cannot change the preflight outcome. */ }
+  }
+}
+
+function emitAuthoringPreflightDecision(
+  decision: ReturnType<typeof decideAskPreflight>,
+  runId?: string,
+): void {
+  const firstBlocker = decision.result.blockers[0];
+  if (firstBlocker && !decision.shouldLaunch) emitDecision({
+    kind: 'ESCALATE',
+    what: firstBlocker.detail.replace(/\s+/g, ' ').trim(),
+    reason: `${firstBlocker.name} — 예비 검사에서 막는 것 ${decision.result.blockers.length}건`,
+    purpose: '저작 전 막힘을 사람이 판단한다',
+    target: '사람(되묻기)',
+    ...(runId === undefined ? {} : { runId }),
+  });
+  else emitDecision({
+    kind: 'PLAN',
+    what: '저작 시작',
+    reason: firstBlocker
+      ? `예비 검사 통과 — --force-preflight 로 ${decision.result.blockers.length}건 우회; 저작 뒤 확정 재검사`
+      : '예비 검사 통과 — 막는 것 없음; 저작 뒤 확정 재검사',
+    purpose: '골을 저작하고 확정 재검사한다',
+    target: '저작',
+    ...(runId === undefined ? {} : { runId }),
+  });
 }
 
 /** ⛔⭐⭐ 막힘 처리는 «한 곳»에서만 — ⓪(저작 전)과 ⑵⑶⑷(저작 후)가 같은 물음·같은 계수를 쓴다.
@@ -640,7 +660,7 @@ async function runPrePreflight(
   );
   deps.print(`[ask] ⓪ 저작 전 예비 검사 — ask 힌트 경로 ${hints.length}개(추정)`);
   deps.print(renderLaunchPreflight(preDecision.result, input.forceRequested && preDecision.result.blockers.length > 0, 'before-authoring'));
-  observeLaunchPreflight(deps, 'before-authoring', preDecision);
+  observeLaunchPreflight(deps, 'before-authoring', preDecision, input.runId);
   // ⛔⭐ A2 「맹점 창」 — 원장에 «쓰지» 않고 이미 남는 관측을 «읽어» 같은 경로의 최근 저작을 본다.
   //   ⚠️ 순서: 내 `ask-pre-preflight` 를 «남기기 전에» 읽는다(자기 자신과 안 겹치게).
   const authoringSamples = deps.recentAuthoringSamples();
@@ -778,10 +798,7 @@ export async function runAskLaunchFlow(
 ): Promise<AskLaunchFlowResult> {
   const entrance = input.entrance;
   const askStartedAt = deps.now();
-  const selfResolveClarifications = resolveSelfResolveClarifications(
-    input.selfResolveClarifications,
-    deps.readSelfResolveClarificationsConfig ?? getUserConfig,
-  );
+  const selfResolveClarifications = resolveSelfResolveClarifications(input.selfResolveClarifications);
   deps.log('harness.entrance', {
     entrance: entrance.id,
     entranceStatus: entrance.status,

package/src/self-dev/ask-launch-io.ts

@@ -263,7 +263,7 @@ export async function buildAskPreflightDeps(options: BuildAskPreflightDepsOption
       const counts: Record<string, number> = {};
       for (const path of paths) {
         // git-spawn-allow: Reads recent commit hashes for this path to count changes and does not modify repository state.
-        const raw = execFileSync('git', ['log', `--since=${windowDays}.days`, '--format=%h', '--', path], { encoding: 'utf8' });
+        const raw = execFileSync('git', ['log', `--since=${windowDays}.days`, '--format=%h', '--', path], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });   // stderr 가 TUI 화면에 새지 않게
         counts[path] = raw.split('\n').filter((line) => line.trim() !== '').length;
       }
       return counts;