elanous 0.2.28 → 0.2.31

package/src/panes/log-pane.ts

@@ -7,7 +7,7 @@
 import { C, stripAnsi, truncate, visibleWidth } from '../tui.js';
 import type { FoldMode } from '../log-entry.js';
 import { paneTitle } from './pane-title.js';
-import { highlightLineSegments } from '../log-pane/search.js';
+import { highlightLineSegments, type LogSearchResult } from '../log-pane/search.js';
 import type { PaneSpec, RenderCtx } from '../plugins/core/types.js';
 
 export interface LogPaneState {
@@ -60,6 +60,64 @@ export interface LogPaneViewport {
   visibleLineIndices: number[];
 }
 
+/** Dashboard scroll offsets count painted rows, while freeze/copy indices
+ *  still address original entries. Match the pane's filter before scrolling.
+ *  The common no-filter path counts delimiters without allocating rows. */
+export function physicalLogRowCount(
+  lines: readonly string[],
+  beforeIndex = lines.length,
+  filterQuery = '',
+): number {
+  let count = 0;
+  const query = filterQuery.trim().toLowerCase();
+  for (let i = 0; i < Math.min(beforeIndex, lines.length); i++) {
+    const entry = lines[i] ?? '';
+    if (query) {
+      count += entry.split(/\r\n|\r|\n/).filter(line => stripAnsi(line).toLowerCase().includes(query)).length;
+      continue;
+    }
+    count++;
+    for (let j = 0; j < entry.length; j++) {
+      if (entry[j] === '\n') count++;
+      else if (entry[j] === '\r') {
+        count++;
+        if (entry[j + 1] === '\n') j++;
+      }
+    }
+  }
+  return count;
+}
+
+export function visibleSearchRowOffset(
+  lines: readonly string[],
+  result: LogSearchResult,
+  filterQuery = '',
+): number {
+  const precedingRows = physicalLogRowCount(lines, result.lineIdx, filterQuery);
+  const entryRowsBeforeMatch = (lines[result.lineIdx] ?? '')
+    .split(/\r\n|\r|\n/)
+    .slice(0, result.physicalRowInEntry ?? 0);
+  const filter = filterQuery.trim().toLowerCase();
+  const withinEntry = filter
+    ? entryRowsBeforeMatch.filter(line => stripAnsi(line).toLowerCase().includes(filter)).length
+    : entryRowsBeforeMatch.length;
+  return precedingRows + withinEntry;
+}
+
+export function logPaneContentHeight(height: number, hasFooter: boolean, hasQueueRow: boolean): number {
+  return Math.max(0, height - 1 - (hasFooter ? (hasQueueRow ? 3 : 2) : 0));
+}
+
+export function maxLogPaneScroll(
+  lines: readonly string[],
+  height: number,
+  opts: { filterQuery?: string; frozenTailIndex?: number | null; hasFooter?: boolean; hasQueueRow?: boolean } = {},
+): number {
+  const sourceCount = opts.frozenTailIndex ?? lines.length;
+  const visibleRows = physicalLogRowCount(lines, sourceCount, opts.filterQuery);
+  return Math.max(0, visibleRows - logPaneContentHeight(height, !!opts.hasFooter, !!opts.hasQueueRow));
+}
+
 function buildScrollStatusLine(opts: {
   start: number;
   visibleCount: number;
@@ -96,11 +154,13 @@ export function buildLogPaneViewport(state: LogPaneState, ctx: RenderCtx): LogPa
   const frozenLines = frozen != null ? state.lines.slice(0, frozen) : state.lines;
   const hiddenBehindFreeze = frozen != null ? Math.max(0, state.lines.length - frozen) : 0;
   const filterQuery = state.filterQuery?.trim() ?? '';
-  const filtered = frozenLines.flatMap((line, index) => {
-    if (!filterQuery) return [{ line, index }];
-    return stripAnsi(line).toLowerCase().includes(filterQuery.toLowerCase())
-      ? [{ line, index }]
-      : [];
+  // Each source entry can contain embedded newlines. Expand it before
+  // viewport math so one array item never paints over the footer/input rows.
+  const physicalLines = frozenLines.flatMap((entry, index) =>
+    entry.split(/\r\n|\r|\n/).map(line => ({ line, index })));
+  const filtered = physicalLines.filter(({ line }) => {
+    if (!filterQuery) return true;
+    return stripAnsi(line).toLowerCase().includes(filterQuery.toLowerCase());
   });
   const visibleLines = filtered.map(item => item.line);
   const visibleLineIndices = filtered.map(item => item.index);
@@ -130,8 +190,7 @@ export function buildLogPaneViewport(state: LogPaneState, ctx: RenderCtx): LogPa
   // breathing gap above + 1-row footer) so the streamed text doesn't
   // feel crammed against the indicator.
   const hasQueueRow = hasFooter && state.queueRow != null && state.queueRow !== '';
-  const footerReserve = hasFooter ? (hasQueueRow ? 3 : 2) : 0;
-  const contentH = Math.max(0, bodyH - footerReserve);
+  const contentH = logPaneContentHeight(ctx.height, hasFooter, hasQueueRow);
   const maxScroll = Math.max(0, visibleLines.length - contentH);
   const start = state.scrollOffset < 0
     ? maxScroll

package/src/persona/presets.ts

@@ -225,3 +225,47 @@ export function describePreset(p: PersonaPreset): string[] {
     `  하지 않는 것: ${p.doesNot.join(' / ')}`,
   ];
 }
+
+// ── 0.2.29 PERSONA-STARTER — 첫 실행 직업 질문의 «경영» 스타터 계약 ────────
+//
+// persona-presets/*.yaml(MK 카탈로그)와는 다른 층이다: 첫 실행 wizard 의 직업
+// 질문에서 «경영»을 고른 순간 «한 장» 만들어 주는 계약 원본. 카탈로그 YAML
+// 원본은 그대로 두고 이 계약은 presets.ts 에서 정의해 기존 clonePreset 파이프라인으로
+// persona store 에 복제한다(마케팅·현장·교육 스타터는 후속 조각).
+
+/** 첫 실행 «경영» 스타터 — persona store 에 정확히 한 장 쓰인다. */
+const MANAGEMENT_STARTER_PRESET: PersonaPreset = {
+  personaId: 'starter-management',
+  displayName: '경영 스타터',
+  names: ['경영 스타터', '경영', 'starter-management'],
+  role: '경영 파트너',
+  title: '첫 실행 스타터',
+  oneLine: '회사 방향·판단·운영을 같이 세우는 짝.',
+  voice: {
+    rule: '짧고 단정하게 — 결론 먼저, 근거 한 줄.',
+    examples: [
+      '이번 주 우선순위는 셋뿐입니다. 첫째는 매출 회수입니다.',
+      '그 결정은 근거가 부족합니다 — 가장 싼 실험부터 하시죠.',
+    ],
+  },
+  tasks: [
+    { when: '아침 루프', what: '할 일·일정·미결 회의를 한 화면에 모아 첫 판단을 준다' },
+    { when: '판단이 갈릴 때', what: '선택지를 셋으로 좁혀 근거·비용·되돌림 수단을 나란히 놓는다' },
+    { when: '주간 정산', what: '지난 결정과 실제 결과를 대조해 다음 판단 기준을 고친다' },
+  ],
+  tools: [],
+  firstQuestions: [
+    '지금 가장 급한 경영 판단은 무엇인가요?',
+    '이번 주에 꼭 정해야 할 일이 있나요?',
+  ],
+  doesNot: [
+    '회사 기밀을 외부에 전송하지 않는다',
+    '합의되지 않은 지출·계약을 대신 실행하지 않는다',
+  ],
+  forWhom: '처음 elanous 를 여는 경영자 — 방향·판단·운영을 함께 시작하려는 사람.',
+};
+
+/** 첫 실행 «경영» 선택이 부르는 유일한 제작 입구 — 스타터 계약 한 장을 persona store 에 쓴다. */
+export function createManagementStarterContract(opts: PersonaWriteOptions = {}): PersonaWriteResult {
+  return clonePreset(MANAGEMENT_STARTER_PRESET, MANAGEMENT_STARTER_PRESET.displayName, opts);
+}

package/src/plugins/maker/connector-maker.ts

@@ -0,0 +1,41 @@
+import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { loadPluginManifestFromDir } from '../core/manifest.js';
+import type { PluginDraft } from './plugin-maker.js';
+
+export interface MakeConnectorOptions {
+  dir: string;
+  gap: PluginDraft['connectors'][number];
+  id: string;
+}
+
+/** Add one connector's credential-name-only draft to the existing extension manifest. */
+export function makeConnector({ dir: inputDir, gap, id }: MakeConnectorOptions): string {
+  if (!/^[a-z0-9][a-z0-9-]{1,31}$/.test(id) || !gap || !gap.name.trim() || gap.name === '미확인'
+    || !gap.use.trim() || !Array.isArray(gap.evidence) || !gap.evidence.every(source => typeof source === 'string')
+    || !Array.isArray(gap.missingCredentials)) throw new Error('invalid connector gap or id');
+  const dir = resolve(inputDir);
+  const path = join(dir, 'plugin.json');
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (!stat?.isFile() || stat.isSymbolicLink() || lstatSync(dir).isSymbolicLink()
+    || realpathSync(dir) !== join(realpathSync(dirname(dir)), basename(dir))) {
+    throw new Error('plugin.json missing or unsafe');
+  }
+  const raw: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('invalid plugin.json');
+  const data = raw as Record<string, unknown>;
+  const extensions = data.extensions as Record<string, unknown> | undefined;
+  const extension = extensions?.['ai.elanous'];
+  if (!extension || typeof extension !== 'object' || Array.isArray(extension)) throw new Error('missing ai.elanous extension');
+  const entry = extension as Record<string, unknown>;
+  if (entry.connectors !== undefined && !Array.isArray(entry.connectors)) throw new Error('invalid connectors');
+  const manifest = loadPluginManifestFromDir(dir, { id: 'local-plugin' }).manifest;
+  if (manifest.contributes.connectors?.some(connector => connector.id === id)) throw new Error(`connector already exists: ${id}`);
+  const credentials = gap.missingCredentials.filter(name => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(name));
+  if (new Set(credentials).size !== credentials.length) throw new Error('duplicate connector credential name');
+  entry.connectors = [...(entry.connectors as unknown[] | undefined ?? []), {
+    id, fields: credentials.map(name => ({ name, secret: true })),
+  }];
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+  return path;
+}

package/src/plugins/maker/skill-maker.ts

@@ -0,0 +1,42 @@
+import { lstatSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { loadPluginManifestFromDir } from '../core/manifest.js';
+import type { PluginDraft } from './plugin-maker.js';
+
+export interface MakeSkillOptions {
+  dir: string;
+  gap: PluginDraft['skills'][number];
+  id: string;
+}
+
+/** Write one researched skill as the wizard's SKILL.md draft, without altering the plugin manifest. */
+export function makeSkill({ dir: inputDir, gap, id }: MakeSkillOptions): string {
+  if (!/^[a-z0-9][a-z0-9-]{1,31}$/.test(id) || !gap || !gap.name.trim() || gap.name === '미확인'
+    || !gap.use.trim() || !Array.isArray(gap.evidence) || !gap.evidence.every(source => typeof source === 'string')) {
+    throw new Error('invalid skill gap or id');
+  }
+  const dir = resolve(inputDir);
+  const manifestPath = join(dir, 'plugin.json');
+  const manifestEntry = lstatSync(manifestPath, { throwIfNoEntry: false });
+  if (!manifestEntry?.isFile() || manifestEntry.isSymbolicLink()) {
+    throw new Error('plugin.json missing or unsafe');
+  }
+  loadPluginManifestFromDir(dir, { id: 'local-plugin' });
+  const skillsDir = join(dir, 'skills');
+  const skillDir = join(skillsDir, id);
+  const path = join(skillDir, 'SKILL.md');
+  // An ancestor can be a platform alias (macOS /var -> /private/var); the plugin directory itself cannot be a link.
+  if (lstatSync(dir).isSymbolicLink()
+    || realpathSync(dir) !== join(realpathSync(dirname(dir)), basename(dir))) {
+    throw new Error('unsafe plugin directory');
+  }
+  const skillsEntry = lstatSync(skillsDir, { throwIfNoEntry: false });
+  if (skillsEntry && !skillsEntry.isDirectory()) throw new Error('unsafe skills directory');
+  if (lstatSync(skillDir, { throwIfNoEntry: false })) throw new Error(`skill already exists: ${id}`);
+  const instructions = gap.use + (gap.evidence.length ? `\n\nResearch sources:\n${gap.evidence.join(', ')}` : '');
+  const content = `---\n${stringifyYaml({ name: id, description: gap.use, requires: [] })}---\n\n${instructions}\n`;
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(path, content, { flag: 'wx' });
+  return path;
+}

package/src/plugins/maker/wizard-generate.ts

@@ -63,8 +63,9 @@ export function generateWizardFiles(dir: string, slug: string, draft: WizardRese
   }
   const skillPath = join(dir, `skills/${slug}/SKILL.md`);
   const readmePath = join(dir, 'README.md');
-  const wizardReadme = options.regenerate && existsSync(readmePath) &&
-    readFileSync(readmePath, 'utf8').includes('Research draft only. Connector declarations contain credential names, not values.');
+  const readmeNotice = 'Research draft only. Connector declarations contain credential names, not values. The graph cannot perform the requested processing yet: implement and validate its steps, then remove extensions["ai.elanous"].researchDraft from plugin.json before installing or running it. No messages are sent.';
+  const wizardReadme = options.regenerate && existing && existsSync(readmePath) &&
+    readFileSync(readmePath, 'utf8') === `# ${slug}\n\n${existing.description}\n\n${readmeNotice}\n`;
   if (options.regenerate) {
     if (!existing || existing.extensions['ai.elanous'].researchDraft !== true || !existsSync(skillPath)) {
       throw new Error('wizard regeneration requires an existing research draft');
@@ -80,7 +81,8 @@ export function generateWizardFiles(dir: string, slug: string, draft: WizardRese
     requires: undefined as { knowledgePacks?: string[]; [key: string]: unknown } | undefined,
     extensions: { 'ai.elanous': { graphs: [`./graphs/${slug}.yaml`],
       capabilities: ['fs:workdir', 'proc:bun', 'proc:elanous'], connectors: [] as unknown[], researchDraft: true } } };
-  if (options.regenerate) manifest.description = draft.description;
+  // A maker scaffold may have no description or an earlier description; the research draft owns this field.
+  manifest.description = draft.description;
   if (draft.requires?.knowledgePacks !== undefined) {
     manifest.requires = { ...manifest.requires, knowledgePacks: [...new Set(draft.requires.knowledgePacks)] };
   }
@@ -108,7 +110,7 @@ console.log(JSON.stringify({ outcome: 'fail', error: step === 'prepare' || step
 process.exitCode = 1;
 `],
     ['examples/input.json', '{}\n'],
-    ['README.md', `# ${slug}\n\n${draft.description}\n\nResearch draft only. Connector declarations contain credential names, not values. The graph cannot perform the requested processing yet: implement and validate its steps, then remove extensions["ai.elanous"].researchDraft from plugin.json before installing or running it. No messages are sent.\n`],
+    ['README.md', `# ${slug}\n\n${draft.description}\n\n${readmeNotice}\n`],
     [`skills/${slug}/SKILL.md`, `---\n${stringifyYaml({ name: slug, description: draft.skill?.description ?? draft.description, requires: [...new Set(requires)] })}---\n\n${draft.skill?.instructions ?? draft.description}\n`],
   ];
   const generated = existing ? files.filter(([path]) => path === 'plugin.json' || path.startsWith('skills/') ||

package/src/pr-tool/census.ts

@@ -0,0 +1,288 @@
+/** Shared PR inventory and creation guard for the CLI and harness. All incomplete reads stay unknown. */
+import { debug } from '../debug/log.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+import { resolveHostId } from '../platform/host-id.js';
+
+export interface PrToolCommandResult { ok: boolean; out: string; err?: string }
+export type PrToolCommand = (command: string, args: readonly string[], opts?: { cwd?: string }) => PrToolCommandResult;
+export type Seat = 'OP' | 'TC' | 'MK' | 'UX';
+export interface OpenPr {
+  number: number;
+  title: string;
+  draft: boolean;
+  updatedAt: string;
+  headSha: string;
+  labels: readonly string[];
+  files: readonly string[];
+  seat: Seat | null;
+  lastCommitAt?: string;
+  cellId: string | null;
+  hunks?: readonly DiffHunk[];
+}
+export type Inventory = { status: 'checked'; prs: readonly OpenPr[] } | { status: 'unknown'; reason: string };
+export interface CensusRow { seat: Seat | 'unknown'; open: number; goalOnly: number; staleDraft: number; supersededOpen: number }
+export type Census = { status: 'checked'; total: number; rows: readonly CensusRow[]; closeCandidates: readonly { number: number; reason: 'goal-only' | 'stale-draft' | 'superseded-open' }[] }
+  | { status: 'unknown'; reason: string };
+export interface DiffHunk { path: string; start: number; end: number }
+export type GuardCode = 'inventory-unknown' | 'candidate-unknown' | 'goal-only' | 'file-overlap' | 'hunk-overlap' | 'same-cell' | 'seat-cap' | 'seat-unattributed';
+export interface GuardReason { code: GuardCode; detail: string; prs?: readonly number[] }
+export interface GuardVerdict { status: 'allow' | 'refuse' | 'unknown'; reasons: readonly GuardReason[]; warnings: readonly GuardReason[] }
+
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+const DEFAULT_SEAT_CAP = 30;
+const DRAFT_STALE_MS = 2 * 24 * 60 * 60 * 1000;
+const MAX_PAGES = 100;
+const MAX_FILES = 3000; // GitHub does not expose more than 3000 PR files.
+const UNMEASURED_WINDOW_MS = 60 * 60 * 1000;
+const UNMEASURED_ALLOW_COUNT = 3;
+
+function unknown(reason: string): Inventory { return { status: 'unknown', reason }; }
+function seatValue(value: unknown): Seat | null { return SEATS.find(seat => seat === value) ?? null; }
+function seatFromLabels(labels: readonly string[]): Seat | null {
+  return SEATS.find(seat => labels.includes(`seat:${seat}`)) ?? null;
+}
+export function cellIdFromBody(body: string): string | null {
+  return /^\s*(?:[-*]\s*)?칸\s*:\s*([A-Z][A-Z0-9-]{2,})\s*$/m.exec(body)?.[1] ?? null;
+}
+
+export function parseDiffHunks(patch: string): DiffHunk[] {
+  const hunks: DiffHunk[] = [];
+  let path: string | null = null;
+  let fileHeaderPending = false;
+  for (const line of patch.split('\n')) {
+    if (line.startsWith('diff --git ')) { path = null; fileHeaderPending = true; continue; }
+    if (fileHeaderPending && line.startsWith('--- ')) {
+      if (line.startsWith('--- a/')) path = line.slice('--- a/'.length);
+      continue;
+    }
+    if (fileHeaderPending && line.startsWith('+++ ')) {
+      if (line.startsWith('+++ b/')) path = line.slice('+++ b/'.length);
+      fileHeaderPending = false;
+      continue;
+    }
+    const match = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (path && match) {
+      // This is an approximate comparison of old-side lines; PRs with different
+      // base trees can shift line numbers. The full merge gate remains authoritative.
+      // An insertion or new file has no old-side lines: use its insertion anchor.
+      const oldStart = Number(match[1]);
+      const oldCount = match[2] === undefined ? 1 : Number(match[2]);
+      const start = oldCount === 0 && oldStart === 0 ? Number(match[3]) : oldStart;
+      const count = oldCount === 0 ? 1 : oldCount;
+      hunks.push({ path, start, end: start + Math.max(1, count) - 1 });
+    }
+  }
+  return hunks;
+}
+
+/** `gh api --paginate --slurp` must return every REST page, including the last page. */
+function pages(run: PrToolCommand, endpoint: string, cwd?: string): readonly unknown[] {
+  const result = run('gh', ['api', '--paginate', '--slurp', endpoint], cwd ? { cwd } : undefined);
+  if (!result.ok) throw new Error(`gh api ${endpoint}: ${result.err || result.out || '조회 실패'}`);
+  let parsed: unknown;
+  try { parsed = JSON.parse(result.out); } catch { throw new Error(`gh api ${endpoint}: JSON 오류`); }
+  if (!Array.isArray(parsed) || parsed.length >= MAX_PAGES || !parsed.every(page => Array.isArray(page) && page.length <= 100)) {
+    throw new Error(`gh api ${endpoint}: 페이지 형식·상한 판정 불가`);
+  }
+  return parsed.flat();
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('PR 응답 행 형식 오류');
+  return value as Record<string, unknown>;
+}
+function text(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} 누락`);
+  return value;
+}
+function date(value: unknown, name: string): string {
+  const raw = text(value, name);
+  if (!Number.isFinite(Date.parse(raw))) throw new Error(`${name} 날짜 오류`);
+  return raw;
+}
+function pathsForPr(run: PrToolCommand, number: number, cwd?: string): string[] {
+  const rows = pages(run, `repos/{owner}/{repo}/pulls/${number}/files?per_page=100`, cwd);
+  if (rows.length >= MAX_FILES) throw new Error(`PR #${number}: 파일 ${MAX_FILES}개 GitHub 상한에 닿음`);
+  return rows.map(row => text(object(row).filename, `PR #${number} 파일명`));
+}
+
+/** Fast file projection; the REST page census below remains the authority for which PRs exist. */
+function projectedFiles(run: PrToolCommand, count: number, cwd?: string): Map<number, string[]> {
+  const result = run('gh', ['pr', 'list', '--state', 'open', '--limit', String(Math.max(count, 1)), '--json', 'number,changedFiles,files'], cwd ? { cwd } : undefined);
+  if (!result.ok) return new Map();
+  let rows: unknown;
+  try { rows = JSON.parse(result.out); } catch { return new Map(); }
+  if (!Array.isArray(rows)) return new Map();
+  const projection = new Map<number, string[]>();
+  for (const value of rows) {
+    try {
+      const row = object(value);
+      if (!Number.isSafeInteger(row.number) || (row.number as number) <= 0 || !Number.isSafeInteger(row.changedFiles) || (row.changedFiles as number) < 0 || !Array.isArray(row.files)) continue;
+      const paths = row.files.map(file => text(object(file).path, 'PR 파일명'));
+      if (paths.length === row.changedFiles && paths.length < MAX_FILES && !projection.has(row.number as number)) projection.set(row.number as number, paths);
+    } catch { /* malformed projection: REST file endpoint below decides this PR */ }
+  }
+  return projection;
+}
+
+export function readOpenPrs(run: PrToolCommand, options: {
+  cwd?: string;
+  seatOfPr?: (pr: { number: number; headRefName: string; body: string; labels: readonly string[] }) => Seat | null;
+  includeDraftCommitDates?: boolean;
+  candidateFiles?: readonly string[];
+} = {}): Inventory {
+  try {
+    const rows = pages(run, 'repos/{owner}/{repo}/pulls?state=open&per_page=100', options.cwd);
+    const projected = projectedFiles(run, rows.length, options.cwd);
+    const prs: OpenPr[] = [];
+    const seen = new Set<number>();
+    for (const value of rows) {
+      const row = object(value);
+      const number = row.number;
+      if (!Number.isSafeInteger(number) || (number as number) <= 0 || seen.has(number as number)) throw new Error('PR 번호 누락·중복');
+      seen.add(number as number);
+      if (row.state !== 'open' || typeof row.draft !== 'boolean') throw new Error(`PR #${number}: OPEN 상태·draft 판정 불가`);
+      const head = object(row.head);
+      const labels = row.labels;
+      if (!Array.isArray(labels)) throw new Error(`PR #${number}: 라벨 판정 불가`);
+      const labelNames = labels.map(label => text(object(label).name, `PR #${number} 라벨`));
+      const headRefName = text(head.ref, `PR #${number} head ref`);
+      const headSha = text(head.sha, `PR #${number} head sha`);
+      const body = typeof row.body === 'string' ? row.body : '';
+      const seat = seatValue(options.seatOfPr?.({ number: number as number, headRefName, body, labels: labelNames })) ?? seatFromLabels(labelNames);
+      const pr: OpenPr = {
+        number: number as number, title: text(row.title, `PR #${number} title`), draft: row.draft,
+        updatedAt: date(row.updated_at, `PR #${number} updated_at`), headSha, labels: labelNames,
+        files: projected.get(number as number) ?? pathsForPr(run, number as number, options.cwd), seat,
+        cellId: cellIdFromBody(body),
+      };
+      if (options.candidateFiles?.some(file => pr.files.includes(file))) {
+        const patch = run('gh', ['pr', 'diff', String(number), '--patch'], options.cwd ? { cwd: options.cwd } : undefined);
+        if (!patch.ok) throw new Error(`PR #${number}: 수정 줄 조회 실패: ${patch.err || patch.out}`);
+        pr.hunks = parseDiffHunks(patch.out);
+      }
+      if (pr.draft && options.includeDraftCommitDates) {
+        const commit = run('gh', ['api', `repos/{owner}/{repo}/commits/${headSha}`, '--jq', '.commit.committer.date'], options.cwd ? { cwd: options.cwd } : undefined);
+        if (!commit.ok) throw new Error(`PR #${number}: 마지막 커밋 날짜 조회 실패: ${commit.err || commit.out}`);
+        pr.lastCommitAt = date(commit.out.trim(), `PR #${number} 마지막 커밋`);
+      }
+      prs.push(pr);
+    }
+    return { status: 'checked', prs };
+  } catch (error) {
+    return unknown(error instanceof Error ? error.message : String(error));
+  }
+}
+
+export function isGoalOnly(files: readonly string[]): boolean {
+  return files.length > 0 && files.every(path => path.startsWith('docs/goals/') && path.length > 'docs/goals/'.length);
+}
+
+export function censusOpenPrs(inventory: Inventory, now = Date.now()): Census {
+  if (inventory.status === 'unknown') {
+    debug.log('pr.tool', 'census', { status: 'unknown', reason: inventory.reason });
+    return inventory;
+  }
+  const rows = new Map<Seat | 'unknown', CensusRow>();
+  const closeCandidates: Array<{ number: number; reason: 'goal-only' | 'stale-draft' | 'superseded-open' }> = [];
+  for (const pr of inventory.prs) {
+    const key = pr.seat ?? 'unknown';
+    const row = rows.get(key) ?? { seat: key, open: 0, goalOnly: 0, staleDraft: 0, supersededOpen: 0 };
+    row.open += 1;
+    if (isGoalOnly(pr.files)) { row.goalOnly += 1; closeCandidates.push({ number: pr.number, reason: 'goal-only' }); }
+    if (pr.draft) {
+      if (!pr.lastCommitAt) {
+        const reason = `PR #${pr.number}: draft 마지막 커밋 날짜 없음`;
+        debug.log('pr.tool', 'census', { status: 'unknown', reason });
+        return { status: 'unknown', reason };
+      }
+      if (now - Date.parse(pr.lastCommitAt) >= DRAFT_STALE_MS) { row.staleDraft += 1; closeCandidates.push({ number: pr.number, reason: 'stale-draft' }); }
+    }
+    if (pr.labels.includes('elanous:superseded')) { row.supersededOpen += 1; closeCandidates.push({ number: pr.number, reason: 'superseded-open' }); }
+    rows.set(key, row);
+  }
+  const result: Census = { status: 'checked', total: inventory.prs.length, rows: [...rows.values()], closeCandidates };
+  debug.log('pr.tool', 'census', { status: 'checked', total: result.total, candidates: closeCandidates.length });
+  return result;
+}
+
+export function guardNewPr(input: { files: readonly string[] | null; seat?: Seat | null; seatCap?: number; cellId?: string | null; hunks?: readonly DiffHunk[] }, inventory: Inventory): GuardVerdict {
+  if (!input.files || input.files.length === 0 || input.files.some(file => !file || file.startsWith('/') || file.includes('..'))) {
+    const reasons: GuardReason[] = [{ code: 'candidate-unknown', detail: '새 PR 변경 파일을 확인할 수 없음' }];
+    debug.log('pr.tool', 'guard-refuse', { status: 'unknown', reasons });
+    return { status: 'unknown', reasons, warnings: [] };
+  }
+  if (inventory.status === 'unknown') {
+    const reasons: GuardReason[] = [{ code: 'inventory-unknown', detail: inventory.reason }];
+    return { status: 'unknown', reasons, warnings: [] };
+  }
+  const reasons: GuardReason[] = [];
+  const warnings: GuardReason[] = [];
+  if (isGoalOnly(input.files)) reasons.push({ code: 'goal-only', detail: '골 문서만 변경 · 구현 0' });
+  const candidate = new Set(input.files);
+  const sameCell = input.cellId ? inventory.prs.filter(pr => pr.cellId === input.cellId) : [];
+  if (sameCell.length) reasons.push({ code: 'same-cell', detail: `같은 칸 ${input.cellId} OPEN PR이 있음`, prs: sameCell.map(pr => pr.number) });
+  const overlaps = inventory.prs.filter(pr => pr.files.some(file => candidate.has(file)));
+  const sameHunk = overlaps.filter(pr => pr.hunks?.some(other => input.hunks?.some(own => own.path === other.path && own.start <= other.end && other.start <= own.end)));
+  if (sameHunk.length) reasons.push({ code: 'hunk-overlap', detail: '같은 파일의 수정 줄 범위가 겹침', prs: sameHunk.map(pr => pr.number) });
+  if (overlaps.length) warnings.push({ code: 'file-overlap', detail: '같은 파일의 OPEN PR이 있음 · 줄 겹침은 별도 판정', prs: overlaps.map(pr => pr.number) });
+  const seat = seatValue(input.seat);
+  if (input.seat !== undefined && input.seat !== null && !seat) reasons.push({ code: 'candidate-unknown', detail: '호출자 자리 값 오류' });
+  const cap = input.seatCap ?? DEFAULT_SEAT_CAP;
+  if (!Number.isSafeInteger(cap) || cap < 1) {
+    reasons.push({ code: 'candidate-unknown', detail: '자리별 PR 상한 설정 오류' });
+  } else if (!seat) {
+    warnings.push({ code: 'seat-unattributed', detail: `호출자 자리 미상 · 전체 OPEN PR ${inventory.prs.length}건` });
+  } else {
+    const count = inventory.prs.filter(pr => pr.seat === seat).length;
+    if (count >= cap) warnings.push({ code: 'seat-cap', detail: `${seat} OPEN PR ${count}건 · 상한 ${cap}` });
+    const unattributed = inventory.prs.filter(pr => pr.seat === null).length;
+    if (unattributed) warnings.push({ code: 'seat-unattributed', detail: `귀속 미상 ${unattributed}건 · 전체 OPEN PR ${inventory.prs.length}건` });
+  }
+  const status = reasons.some(reason => reason.code === 'candidate-unknown') ? 'unknown' : reasons.length ? 'refuse' : 'allow';
+  if (status !== 'allow') debug.log('pr.tool', 'guard-refuse', { status, reasons, warnings });
+  else if (warnings.length) debug.log('pr.tool', 'guard-warn', { warnings });
+  return { status, reasons, warnings };
+}
+
+/** Persist the unknown-read budget across harness processes sharing one instance state root. */
+export function recordGuardUnmeasured(input: { seat: Seat | null; reason: string; stateRoot?: string; host?: string; now?: number }): { count: number; blocked: boolean; reason?: string } {
+  const now = input.now ?? Date.now();
+  const seat = input.seat ?? 'unknown';
+  const host = input.host ?? resolveHostId();
+  try {
+    const dir = join(input.stateRoot ?? effectiveInstanceRoot(), 'pr-tool');
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, 'guard-unmeasured.jsonl');
+    return withFileLockSync(`${file}.lock`, () => {
+      const rows = existsSync(file) ? readFileSync(file, 'utf8').split('\n').filter(Boolean) : [];
+      const retained: Array<{ at: number; seat: string; host: string }> = [];
+      let count = 0;
+      for (const line of rows) {
+        let value: unknown;
+        try { value = JSON.parse(line); } catch { return { count: 0, blocked: true, reason: '판정 불가 원장 JSON 오류' }; }
+        if (value && typeof value === 'object') {
+          const row = value as { at?: unknown; seat?: unknown; host?: unknown };
+          if (typeof row.at !== 'number' || typeof row.seat !== 'string' || typeof row.host !== 'string') return { count: 0, blocked: true, reason: '판정 불가 원장 행 형식 오류' };
+          if (row.at > now - UNMEASURED_WINDOW_MS && row.at <= now) {
+            retained.push({ at: row.at, seat: row.seat, host: row.host });
+            if (row.seat === seat && row.host === host) count += 1;
+          }
+        } else return { count: 0, blocked: true, reason: '판정 불가 원장 행 형식 오류' };
+      }
+      retained.push({ at: now, seat, host });
+      count += 1;
+      writeFileSync(file, `${retained.map(row => JSON.stringify(row)).join('\n')}\n`);
+      const blocked = count > UNMEASURED_ALLOW_COUNT;
+      debug.log('pr-tool.open-guard', 'guard-unmeasured', { seat, host, count, blocked, reason: input.reason });
+      return { count, blocked };
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    debug.log('pr-tool.open-guard', 'guard-unmeasured', { seat, host, blocked: true, reason: `원장 오류: ${reason}` });
+    return { count: 0, blocked: true, reason };
+  }
+}

package/src/preview/terminal.ts

@@ -85,6 +85,13 @@ export interface PreviewTerminalOpts {
    *  로 받아 같은 에뮬레이터/탭에 먹인다(정체성·크로스서피스 goto 획득). bun onData-死는 registry bun-native
    *  openpty 가 해결. ⚠️ 라이브 렌더(yazi DA2·마우스·커서·alt-screen) 검증은 기기 세션 필요(대표) → 기본 off. */
   useRegistry?: boolean;
+  /** Shared PTY identity for registry-backed popups. Defaults to preview. */
+  registryKind?: string;
+  /** Human-readable purpose shown by PTY inventory. */
+  registryNickname?: string;
+  registryOrigin?: { originRoot: string; controller?: string };
+  registryPurpose?: string;
+  registrySeat?: string;
   /** P13 — OSC 9/99/777 notification hook. Fires when the child
    *  emits one of:
    *    ESC ] 9 ; <title> BEL                  (iTerm2 growl)
@@ -337,7 +344,13 @@ export class PreviewTerminal {
       this.registryHandle = this.registryDeps.startPty({
         // 합성자 = registry(resolveSpawnShape) — 여기서는 overlay 만 넘긴다.
         cmd: shell, args, workdir: this.opts.cwd, env: childEnv,
-        cols: this.term.cols, rows: this.term.rows, kind: 'preview', accessMode: 'write',
+        cols: this.term.cols, rows: this.term.rows,
+        kind: this.opts.registryKind ?? 'preview',
+        nickname: this.opts.registryNickname,
+        origin: this.opts.registryOrigin,
+        purpose: this.opts.registryPurpose,
+        seat: this.opts.registrySeat,
+        accessMode: 'write',
       });
       this.alive = true;
     } else {

package/src/prompt-cache/types.ts

@@ -15,6 +15,8 @@
 export interface LLMUsage {
   /** Origin provider — lets the metrics module tag accumulated tokens. */
   provider?: 'anthropic' | 'openai';
+  /** 이 사용량을 낸 턴의 모델(내보내는 쪽이 알 때만). 턴 지표가 설정 모델 대신 이것으로 ctx 최대치·단가를 잡는다. */
+  model?: string;
   inputTokens?: number;
   outputTokens?: number;
   cacheReadInputTokens?: number;