elanous 0.2.41 → 0.2.43

package/src/onboarding/first-run.ts

@@ -4,6 +4,12 @@ import { debug } from '../debug/log.js';
 import { detectLocale, type Locale } from '../expression/locale.js';
 import { unattendedNextStepLine } from './entry-hints.js';
 import { resolveProviderCredential } from '../llm/provider-credentials.js';
+import { zaiCodingPlanAvailable } from '../llm/zai-coding-plan.js';
+import { collectServiceKeys, printKeySetupReport } from './key-setup.js';
+import { getSecretAsync, setSecretAsync } from '../nexus/config/secrets/index.js';
+import { probeProvider } from '../llm/provider-probe.js';
+import { createSecretPrompt } from './secret-prompt.js';
+import { parseMenuAnswer as parseNumericMenuAnswer } from './menu-answer.js';
 import {
   getUserConfig, saveUserConfig, userConfigPath,
   type LLMProviderName, type UserConfig,
@@ -11,44 +17,45 @@ import {
 
 export interface FirstRunDeps {
   config?: UserConfig;
+  env?: NodeJS.ProcessEnv;
   path?: string;
   detectProviders?: () => Promise<DetectedProvider[]>;
   isTTY?: boolean;
   /** Locale for user-facing wording; defaults to the shared ambient decision (detectLocale). */
   locale?: Locale;
   chooseProvider?: (detected: readonly LLMProviderName[]) => Promise<LLMProviderName | null>;
+  promptSecret?: (message: string) => Promise<string | undefined>;
+  getSecretAsync?: typeof getSecretAsync;
+  setSecretAsync?: typeof setSecretAsync;
+  probeKey?: typeof probeProvider;
+  setupWhenNoProvider?: (config: UserConfig) => Promise<FirstRunProviderSetupResult>;
   print?: (message: string) => void;
   saveConfig?: (config: UserConfig, path: string) => void;
 }
 
-const CHOICE_BASE: readonly LLMProviderName[] = ['openai-codex', 'grok', 'anthropic'];
-const CHOICE_LABEL: Partial<Record<LLMProviderName, string>> = { 'openai-codex': 'Codex', grok: 'Grok', anthropic: 'Claude' };
-const SUBSCRIPTION_PRIORITY = ['openai-codex', 'grok', 'anthropic', 'gemini', 'openai', 'openrouter'] as const;
+export type FirstRunProviderSetupResult = LLMProviderName | null | { kind: 'needs-llm' };
 
-/** Menu order: detected subscriptions first (in priority order), then the remaining base choices. */
+const CHOICE_BASE: readonly LLMProviderName[] = ['openai-codex', 'grok', 'anthropic', 'openrouter', 'glm'];
+const CHOICE_LABEL: Partial<Record<LLMProviderName, string>> = { 'openai-codex': 'Codex', grok: 'Grok', anthropic: 'Claude', openrouter: 'OpenRouter', glm: 'GLM' };
+const SUBSCRIPTION_PRIORITY = ['openai-codex', 'grok', 'anthropic', 'gemini', 'openai', 'glm', 'openrouter'] as const;
+
+/** Menu order: detected usable providers first, then the remaining supported choices. */
 export function orderProviderChoices(detected: readonly LLMProviderName[] = []): LLMProviderName[] {
   return [...detected, ...CHOICE_BASE.filter((name) => !detected.includes(name))];
 }
 
-export type MenuAnswer =
-  | { kind: 'chosen'; provider: LLMProviderName }
-  | { kind: 'cancel' }
-  | { kind: 'miss' };
+export type MenuAnswer = import('./menu-answer.js').MenuAnswer<LLMProviderName>;
 
 // FIRST10-FIX: 첫 화면의 오타 한 번이 first-run 전체를 취소하던 마찰 — 빈 입력(취소 의사)과 달리
 // 선택지를 가리키지 못하는 입력(범위 밖·전각·비정수)은 취소가 아니라 다시 묻는다.
 // 메뉴 답으로 인정하는 건 반각 십진 자릿수 문자열뿐이다 — Number() 는 '1e0'·'0x1'·'+1' 같은
 // 수식 표기를 정수로 강제 변환해 선택지로 샌다(0.2.35 재측정).
 export function parseMenuAnswer(answer: string, choices: readonly LLMProviderName[]): MenuAnswer {
-  const trimmed = answer.trim();
-  if (trimmed === '') return { kind: 'cancel' };
-  if (!/^[0-9]+$/.test(trimmed)) return { kind: 'miss' };
-  const provider = choices[Number(trimmed) - 1];
-  return provider !== undefined ? { kind: 'chosen', provider } : { kind: 'miss' };
+  return parseNumericMenuAnswer(answer, choices);
 }
 
 /**
- * The fixed choice line of the first-run menu (`1 Codex, 2 Grok, 3 Claude`).
+ * The choice line of the first-run menu.
  * Single source of the wording: the prompt below renders it, and the ux-sim
  * first-run device asserts against it, so a wording change cannot drift apart.
  */
@@ -56,6 +63,8 @@ export function formatProviderMenu(choices: readonly LLMProviderName[]): string
   return choices.map((name, i) => `${i + 1} ${CHOICE_LABEL[name] ?? name}`).join(', ');
 }
 
+export const FIRST_RUN_PROVIDER_MENU_PROMPT = 'Choose LLM';
+
 export async function promptProviderMenu(
   ask: (prompt: string) => Promise<string>,
   detected: readonly LLMProviderName[] = [],
@@ -63,7 +72,7 @@ export async function promptProviderMenu(
   const choices = orderProviderChoices(detected);
   const menu = formatProviderMenu(choices);
   for (;;) {
-    const parsed = parseMenuAnswer(await ask(`Choose LLM (${menu}; Enter to cancel): `), choices);
+    const parsed = parseMenuAnswer(await ask(`${FIRST_RUN_PROVIDER_MENU_PROMPT} (${menu}; Enter to cancel): `), choices);
     if (parsed.kind === 'chosen') return parsed.provider;
     if (parsed.kind === 'cancel') return null;
   }
@@ -84,6 +93,8 @@ const FIRST_RUN_TEXT = {
     detectedPrefix: '감지: ',
     subscription: ' 구독',
     needsLlm: 'eln setup llm 으로 고르세요',
+    keyStoredNotReady: '키를 저장하고 검증했지만 첫 실행에서 사용할 provider 연결은 아직 완료되지 않았습니다.',
+    keySetupFailed: '키 설정을 완료하지 못했습니다. 비밀 값을 표시하지 않고 중단했습니다.',
     claudeNoPath: 'claude-code 구독은 구독으로 쓸 수 있는 경로가 없어 자동 선택하지 않음',
     multipleDetected: '둘 이상 감지되어 고르세요',
   },
@@ -91,6 +102,8 @@ const FIRST_RUN_TEXT = {
     detectedPrefix: 'detected: ',
     subscription: ' subscription',
     needsLlm: 'pick a provider via eln setup llm',
+    keyStoredNotReady: 'The key was saved and verified, but first-run provider setup is not complete yet.',
+    keySetupFailed: 'Key setup could not be completed. It stopped without displaying secret values.',
     claudeNoPath: 'claude-code subscription has no usable path in elanous; not auto-selecting',
     multipleDetected: 'more than one detected; pick one',
   },
@@ -105,7 +118,19 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   const text = FIRST_RUN_TEXT[(deps.locale ?? detectLocale()) === 'en' ? 'en' : 'ko'];
   const detectionLabel = (provider: string) =>
     `${provider === 'openai-codex' ? 'codex' : provider}${text.subscription}`;
+  // An incomplete onboarding marker does not mean the user's LLM is unconfigured.
+  // Keep an already usable provider, key and model rather than replacing it with a detected subscription.
+  const existing = cfg.llm.provider !== 'auto'
+    ? resolveProviderCredential({ provider: cfg.llm.provider, rotation: cfg.llm.rotation,
+        baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey, env: deps.env })
+    : undefined;
+  const configured = existing && existing.source !== 'none'
+    ? cfg.llm.provider
+    // Z.ai's coding-plan credential is stored in its dedicated cache/env, not llm.apiKey.
+    : cfg.llm.provider === 'glm' && zaiCodingPlanAvailable() ? 'glm' : undefined;
   let detected: DetectedProvider[] = [];
+  // This read-only scan is unconditional, even with an incomplete existing config;
+  // provider availability must not depend on the setup marker/config being absent.
   try { detected = await (deps.detectProviders ?? detectProviders)(); }
   catch { /* Detection is advisory; a TTY can still choose. */ }
   const subscriptions = detected.filter((d) => d.available && (d.auth === 'oauth' || d.auth === 'agent-cli'));
@@ -113,14 +138,6 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   const observe = (event: 'detected' | 'chosen' | 'ready' | 'needs-llm', inputs: number) =>
     debug.log('onboarding.first-run', event, { providers, inputs });
   observe('detected', 0);
-  // An incomplete onboarding marker does not mean the user's LLM is unconfigured.
-  // Keep an already usable provider, key and model rather than replacing them with a detected subscription.
-  const existing = cfg.llm.provider !== 'auto'
-    ? resolveProviderCredential({ provider: cfg.llm.provider, rotation: cfg.llm.rotation,
-        baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey })
-    : undefined;
-  const configured = existing && existing.source !== 'none'
-    ? cfg.llm.provider : undefined;
   // claude-code is detected but has no subscription path in elanous: mapping it to the 'anthropic'
   // API-key provider would save a provider whose first call fails for a subscription-only user.
   const usable = SUBSCRIPTION_PRIORITY.filter((name) => providers.includes(name));
@@ -134,6 +151,7 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   let provider: LLMProviderName | null | undefined = configured ?? (usable.length === 1 ? usable[0] : undefined);
   if (!configured && provider) print(detectionLine(provider));
   let inputs = 0;
+  let providerSetUpInPlace = false;
   if (!provider) {
     if (providers.length > 0) {
       print(detectionLine(usable.length === 0
@@ -144,23 +162,64 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
       // FIRST-CHAT-NONTTY — bare `elanous` with no TTY gets the same one-line next step as the other entrances.
       return needsLlm(0, [unattendedNextStepLine()]);
     }
+    if (deps.setupWhenNoProvider && usable.length === 0) {
+      inputs = 1;
+      const setupResult = await deps.setupWhenNoProvider(cfg);
+      if (typeof setupResult === 'object' && setupResult !== null && setupResult.kind === 'needs-llm') {
+        return needsLlm(inputs);
+      }
+      provider = typeof setupResult === 'string' ? setupResult : null;
+      if (!provider) {
+        print('LLM 없이 첫 화면을 엽니다. LLM 기능은 사용할 수 없습니다. 다시 설정: `elanous setup keys` 또는 `elanous login openai-codex`.');
+        (deps.saveConfig ?? saveUserConfig)({ ...cfg, onboarding: { ...cfg.onboarding, ready: true } }, path);
+        observe('ready', inputs);
+        return { outcome: 'ready', inputs };
+      }
+      providerSetUpInPlace = true;
+      observe('chosen', inputs);
+    } else {
     inputs = 1;
     provider = await (deps.chooseProvider ?? chooseProvider)(usable);
     if (!provider) return { outcome: 'cancelled', inputs };
     observe('chosen', inputs);
+    }
   }
   const credential = inputs === 1 || provider !== cfg.llm.provider
     ? resolveProviderCredential({
         provider, rotation: cfg.llm.rotation,
         baseProvider: cfg.llm.provider, baseApiKey: cfg.llm.apiKey,
+        env: deps.env,
       })
     : undefined;
-  if (inputs === 1 && credential?.source === 'none') return needsLlm(inputs);
+  if (inputs === 1 && credential?.source === 'none'
+    && !(providerSetUpInPlace && provider === 'openai-codex')) {
+    if ((deps.isTTY ?? process.stdin.isTTY) !== true) return needsLlm(inputs);
+    try {
+      const results = await collectServiceKeys({
+        config: cfg,
+        promptSecret: deps.promptSecret ?? createSecretPrompt(),
+        print,
+        getSecret: deps.getSecretAsync,
+        setSecret: deps.setSecretAsync,
+        probe: deps.probeKey,
+        providers: [provider],
+      });
+      printKeySetupReport(results, print);
+      if (results.length === 0 || results.some((result) => result.status !== 'success')) return needsLlm(inputs);
+      return needsLlm(inputs, [text.keyStoredNotReady]);
+    } catch {
+      return needsLlm(inputs, [text.keySetupFailed]);
+    }
+  }
   (deps.saveConfig ?? saveUserConfig)({
     ...cfg,
     llm: { ...cfg.llm, provider,
-      ...(provider !== cfg.llm.provider ? { apiKey: credential?.apiKey, baseUrl: credential?.baseUrl, model: undefined } : {}),
-      ...(credential?.apiKey ? { apiKey: credential.apiKey } : {}),
+      ...(provider !== cfg.llm.provider ? {
+        apiKey: credential?.source === 'rotation' ? credential.apiKey : undefined,
+        baseUrl: credential?.baseUrl,
+        model: undefined,
+      } : {}),
+      ...(credential?.source === 'rotation' && credential.apiKey ? { apiKey: credential.apiKey } : {}),
       ...(credential?.baseUrl ? { baseUrl: credential.baseUrl } : {}) },
     onboarding: { ...cfg.onboarding, ready: true },
   }, path);

package/src/onboarding/key-setup.ts

@@ -0,0 +1,103 @@
+import { getProviderForConfig, type LLMProvider } from '../llm.js';
+import { providerEnvKey, resolveProviderCredential } from '../llm/provider-credentials.js';
+import { probeProvider } from '../llm/provider-probe.js';
+import type { UserConfig } from '../user-config.js';
+import { getSecretAsync, setSecretAsync } from '../nexus/config/secrets/index.js';
+
+export const KEY_SETUP_SERVICES = [
+  { provider: 'anthropic', label: 'Anthropic' },
+  { provider: 'grok', label: 'Grok' },
+  { provider: 'gemini', label: 'Gemini' },
+  { provider: 'openrouter', label: 'OpenRouter' },
+  { provider: 'opengateway', label: 'OpenGateway' },
+  { provider: 'openai', label: 'OpenAI' },
+] as const;
+
+type KeySetupService = (typeof KEY_SETUP_SERVICES)[number];
+type KeyStatus = 'success' | 'failed' | 'skipped';
+
+export interface KeySetupResult {
+  provider: string;
+  label: string;
+  status: KeyStatus;
+}
+
+export interface KeySetupDeps {
+  config: UserConfig;
+  promptSecret: (message: string) => Promise<string | undefined>;
+  print: (message: string) => void;
+  getSecret?: (id: string) => Promise<string | undefined>;
+  setSecret?: (id: string, value: string) => Promise<void>;
+  probe?: (provider: LLMProvider) => Promise<{ success: boolean }>;
+  providers?: readonly string[];
+}
+
+function importedKeys(value: string | undefined): Map<string, string> {
+  const keys = new Map<string, string>();
+  for (const line of value?.split(/\r?\n/) ?? []) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!match) continue;
+    const raw = match[2] ?? '';
+    const unquoted = (raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))
+      ? raw.slice(1, -1) : raw;
+    if (unquoted) keys.set(match[1]!, unquoted);
+  }
+  return keys;
+}
+
+function serviceKey(service: KeySetupService): string | undefined {
+  return providerEnvKey(service.provider);
+}
+
+function serviceSelected(service: KeySetupService, providers: readonly string[] | undefined): boolean {
+  return providers === undefined || providers.includes(service.provider);
+}
+
+/** Collect API keys without rendering values, then probe each newly supplied key once. */
+export async function collectServiceKeys(deps: KeySetupDeps): Promise<KeySetupResult[]> {
+  const getSecret = deps.getSecret ?? getSecretAsync;
+  const setSecret = deps.setSecret ?? setSecretAsync;
+  const probe = deps.probe ?? probeProvider;
+  const pasted = importedKeys(await deps.promptSecret('.env 형식 키를 붙여 넣고 빈 줄로 끝내세요 (건너뛰려면 Enter): '));
+  const results: KeySetupResult[] = [];
+  for (const service of KEY_SETUP_SERVICES) {
+    if (!serviceSelected(service, deps.providers)) continue;
+    const id = serviceKey(service);
+    if (!id) continue;
+    const existing = await getSecret(id);
+    const configured = resolveProviderCredential({
+      provider: service.provider,
+      rotation: deps.config.llm.rotation,
+      baseProvider: deps.config.llm.provider,
+      baseApiKey: deps.config.llm.apiKey,
+    }).source !== 'none';
+    if (existing || configured) {
+      results.push({ ...service, status: 'skipped' });
+      continue;
+    }
+    const value = pasted.get(id) ?? (await deps.promptSecret(`${service.label} 키 (${id}, 건너뛰려면 Enter): `))?.trim();
+    if (!value) {
+      results.push({ ...service, status: 'skipped' });
+      continue;
+    }
+    await setSecret(id, value);
+    let success = false;
+    try {
+      const provider = getProviderForConfig({
+        ...deps.config,
+        llm: { ...deps.config.llm, provider: service.provider as UserConfig['llm']['provider'], apiKey: value, model: undefined },
+      });
+      success = (await probe(provider)).success;
+    } catch { /* The status table deliberately keeps provider failures value-free. */ }
+    results.push({ ...service, status: success ? 'success' : 'failed' });
+  }
+  return results;
+}
+
+export function printKeySetupReport(results: readonly KeySetupResult[], print: (message: string) => void): void {
+  print('키 설정 결과');
+  for (const result of results) {
+    print(`${result.status === 'success' ? '✅' : result.status === 'failed' ? '❌' : '건너뜀'} ${result.label}`);
+  }
+  print('Telegram 봇 설정: https://t.me/BotFather');
+}

package/src/onboarding/menu-answer.ts

@@ -0,0 +1,13 @@
+export type MenuAnswer<T> =
+  | { kind: 'chosen'; provider: T }
+  | { kind: 'cancel' }
+  | { kind: 'miss' };
+
+/** Parse a menu answer using the first-run chooser contract: blank cancels, only ASCII decimal indices select. */
+export function parseMenuAnswer<T>(answer: string, choices: readonly T[]): MenuAnswer<T> {
+  const trimmed = answer.trim();
+  if (trimmed === '') return { kind: 'cancel' };
+  if (!/^[0-9]+$/.test(trimmed)) return { kind: 'miss' };
+  const provider = choices[Number(trimmed) - 1];
+  return provider !== undefined ? { kind: 'chosen', provider } : { kind: 'miss' };
+}

package/src/onboarding/secret-prompt.ts

@@ -0,0 +1,37 @@
+import { createInterface } from 'node:readline';
+import type { Readable, Writable } from 'node:stream';
+
+/** Hidden one-line secret input, or a hidden multi-line .env paste terminated by a blank line. */
+export function createSecretPrompt(input: Readable = process.stdin, output: Writable = process.stdout) {
+  return async (message: string): Promise<string | undefined> => {
+    const rl = createInterface({ input, output });
+    const writable = rl as unknown as { _writeToOutput?: (value: string) => void };
+    const original = writable._writeToOutput;
+    output.write(message);
+    writable._writeToOutput = () => {};
+    try {
+      if (!message.includes('.env')) return await new Promise((resolve) => rl.question('', resolve));
+      return await new Promise<string | undefined>((resolve) => {
+        const lines: string[] = [];
+        let settled = false;
+        const finish = (value: string | undefined) => {
+          if (settled) return;
+          settled = true;
+          resolve(value);
+        };
+        rl.on('line', (line) => {
+          if (line.length === 0) {
+            finish(lines.length > 0 ? lines.join('\n') : undefined);
+            return;
+          }
+          lines.push(line);
+        });
+        rl.on('close', () => finish(lines.length > 0 ? lines.join('\n') : undefined));
+      });
+    } finally {
+      writable._writeToOutput = original;
+      rl.close();
+      output.write('\n');
+    }
+  };
+}

package/src/plugins/install/plugin-install.ts

@@ -18,6 +18,65 @@ const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][a-zA-Z0-9.-]+)?$/;
 const SHA = /^[a-fA-F0-9]{40}$/;
 const HASH = /^[a-fA-F0-9]{64}$/;
 
+/** Curated scene packages offered by the default install group. Service-key
+ *  declarations live in each package manifest and use the shared key catalog. */
+export const DEFAULT_PLUGIN_GROUP = [
+  { id: 'demo-research', label: '리서치', requiredServiceKeys: [], optionalServiceKeys: ['exa', 'firecrawl', 'xai', 'tavily'], requiredPrerequisites: ['llm-provider'], optionalPrerequisites: [] },
+  { id: 'demo-linear-secretary', label: '리니어 비서', requiredServiceKeys: ['linear'], optionalServiceKeys: ['telegram', 'telegram-chat'], requiredPrerequisites: ['llm-provider'], optionalPrerequisites: [] },
+  { id: 'demo-absorption-briefing', label: '흡수 브리핑', requiredServiceKeys: [], optionalServiceKeys: ['exa', 'firecrawl', 'xai', 'telegram', 'telegram-chat', 'linear'], requiredPrerequisites: ['llm-provider'], optionalPrerequisites: [] },
+  { id: 'demo-browser-hand', label: '브라우저 손', requiredServiceKeys: [], optionalServiceKeys: ['linear'], requiredPrerequisites: ['llm-provider', 'aside'], optionalPrerequisites: [] },
+  { id: 'demo-video-briefing', label: '영상 브리핑', requiredServiceKeys: [], optionalServiceKeys: ['elevenlabs', 'telegram', 'telegram-chat'], requiredPrerequisites: ['llm-provider'], optionalPrerequisites: [] },
+  { id: 'demo-plugin-wizard', label: '플러그인 마법사', requiredServiceKeys: [], optionalServiceKeys: [], requiredPrerequisites: ['llm-provider'], optionalPrerequisites: ['claude-cli', 'github-cli'] },
+] as const;
+
+export type DefaultPluginStatus = {
+  id: typeof DEFAULT_PLUGIN_GROUP[number]['id'];
+  label: string;
+  status: 'ready' | 'key-needed';
+  missingRequiredKeys: string[];
+  missingPrerequisites: string[];
+  optionalKeysMissing: string[];
+  optionalPrerequisitesMissing: string[];
+};
+
+/** Public readiness identifiers only; callers must never pass secret values. */
+export function defaultPluginStatuses(input: {
+  readyServiceKeyIds?: readonly string[];
+  satisfiedPrerequisites?: readonly string[];
+} = {}): DefaultPluginStatus[] {
+  const readyKeys = new Set(input.readyServiceKeyIds ?? []);
+  const satisfied = new Set(input.satisfiedPrerequisites ?? []);
+  return DEFAULT_PLUGIN_GROUP.map(plugin => {
+    const missingRequiredKeys = plugin.requiredServiceKeys.filter(id => !readyKeys.has(id));
+    const missingPrerequisites = plugin.requiredPrerequisites.filter(id => !satisfied.has(id));
+    return {
+      id: plugin.id,
+      label: plugin.label,
+      status: missingRequiredKeys.length || missingPrerequisites.length ? 'key-needed' : 'ready',
+      missingRequiredKeys,
+      missingPrerequisites,
+      optionalKeysMissing: plugin.optionalServiceKeys.filter(id => !readyKeys.has(id)),
+      optionalPrerequisitesMissing: plugin.optionalPrerequisites.filter(id => !satisfied.has(id)),
+    };
+  });
+}
+
+const DEFAULT_PLUGIN_ROOT = resolve(import.meta.dir, '../../../plugins');
+
+/** Install the curated default group from this distribution's packaged plugin assets. */
+export async function installDefaultPluginGroup(opts: InstallOptions = {}): Promise<InstalledPlugin[]> {
+  const root = resolve(opts.root ?? elanousStateRoot());
+  const installed: InstalledPlugin[] = [];
+  for (const plugin of DEFAULT_PLUGIN_GROUP) {
+    const packageRoot = join(DEFAULT_PLUGIN_ROOT, plugin.id);
+    const manifest = loadPluginManifestFromDir(packageRoot, { id: plugin.id }).manifest;
+    const existing = listInstalledPlugins(root).find(item =>
+      item.market === 'local' && item.name === manifest.id && item.version === manifest.version);
+    installed.push(existing ?? await installPlugin(packageRoot, { ...opts, root }));
+  }
+  return installed;
+}
+
 export type InstallEvent =
   | { event: 'resolve'; plugin: string; version: string; sha256: string | null }
   | { event: 'verify'; signature: 'ok' | 'missing' | 'bad'; scan: 'safe' | 'caution' | 'dangerous' }

package/src/pr-tool/census.ts

@@ -41,9 +41,33 @@ export interface GuardReason { code: GuardCode; detail: string; prs?: readonly n
 /** PR-GUARD-HUNK-WARN (대표 10-17): 줄 겹침은 기본 경고 — 착지 쪽 스마트 머지가 푼다. 'refuse' = 옛 거부 동작. */
 export type HunkOverlapMode = 'refuse' | 'warn';
 export interface GuardVerdict { status: 'allow' | 'refuse' | 'unknown'; reasons: readonly GuardReason[]; warnings: readonly GuardReason[];
-  sameCellConflicts?: readonly { pr: number; cardId: string | null; slice?: { slice: number; total: number } | null }[];
+  sameCellConflicts?: readonly { pr: number; branch: string | null; headSha: string; cardId: string | null; slice?: { slice: number; total: number } | null }[];
   sameCellReuse?: { number: number; branch: string; headSha: string; cellId: string; cardId: string; legacyBound?: true } }
 
+export interface PrLineageField<T> {
+  status: 'observed' | 'unknown';
+  value: T | null;
+  evidence: string;
+  reason?: string;
+}
+
+/** First, read-only slice: report observed PR facts and leave every unmeasured close criterion unknown. */
+export interface PrLineageObservation {
+  status: 'observed' | 'unknown';
+  pr: number;
+  observedAt: string;
+  currentHead: PrLineageField<string>;
+  supersedes: PrLineageField<number>;
+  sourceCard: PrLineageField<string>;
+  olderScopeCarriedForward: PrLineageField<boolean>;
+  newerProtected: PrLineageField<boolean>;
+  cellStatus: PrLineageField<string>;
+  owner: PrLineageField<string>;
+  mergeSubstitution: PrLineageField<boolean>;
+  closeEligible: false;
+  reason?: string;
+}
+
 const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
 const DEFAULT_SEAT_CAP = 30;
 const DRAFT_STALE_MS = 2 * 24 * 60 * 60 * 1000;
@@ -511,7 +535,8 @@ export function guardNewPr(input: { files: readonly string[] | null; seat?: Seat
     ? { number: sameCell[0].number, branch: sameCell[0].headRefName, headSha: sameCell[0].headSha,
       cellId: input.cellId!, cardId: input.cardId, ...(legacyBound ? { legacyBound: true as const } : {}) } : undefined;
   return { status, reasons, warnings,
-    ...(sameCell.length ? { sameCellConflicts: sameCell.map(pr => ({ pr: pr.number, cardId: pr.cardId ?? null, slice: pr.slice ?? null })) } : {}),
+    ...(sameCell.length ? { sameCellConflicts: sameCell.map(pr => ({ pr: pr.number, branch: pr.headRefName ?? null,
+      headSha: pr.headSha, cardId: pr.cardId ?? null, slice: pr.slice ?? null })) } : {}),
     ...(reusable ? { sameCellReuse: reusable } : {}) };
 }
 
@@ -553,3 +578,109 @@ export function recordGuardUnmeasured(input: { seat: Seat | null; reason: string
     return { count: 0, blocked: true, reason };
   }
 }
+
+const LINEAGE_READ_FIELDS = 'number,headRefOid,body';
+const LINEAGE_NOT_MEASURED = '첫 PR lineage 조각의 관측 범위 밖이라 아직 판정하지 않음';
+
+function lineageUnknown<T>(reason: string, evidence: string): PrLineageField<T> {
+  return { status: 'unknown', value: null, evidence, reason };
+}
+
+function lineageUnmeasured<T>(): PrLineageField<T> {
+  return lineageUnknown<T>(LINEAGE_NOT_MEASURED, '이 필드는 조회하지 않음');
+}
+
+/**
+ * Read only the PR head and explicit `Supersedes: #N` marker. This deliberately
+ * does not infer whether the PR is safe to close; later lineage fields remain unknown.
+ */
+export function observePrLineage(input: {
+  pr: number;
+  run?: PrToolCommand;
+  cwd?: string;
+  now?: () => Date;
+}): PrLineageObservation {
+  const observedAt = (input.now ?? (() => new Date()))().toISOString();
+  const readEvidence = `gh pr view #${input.pr} --json ${LINEAGE_READ_FIELDS}`;
+  const unknownObservation = (reason: string, currentHead = lineageUnknown<string>(reason, readEvidence),
+    supersedes = lineageUnknown<number>(reason, readEvidence)): PrLineageObservation => ({
+    status: 'unknown', pr: input.pr, observedAt, currentHead, supersedes,
+    sourceCard: lineageUnmeasured<string>(),
+    olderScopeCarriedForward: lineageUnmeasured<boolean>(),
+    newerProtected: lineageUnmeasured<boolean>(),
+    cellStatus: lineageUnmeasured<string>(),
+    owner: lineageUnmeasured<string>(),
+    mergeSubstitution: lineageUnmeasured<boolean>(),
+    closeEligible: false,
+    reason,
+  });
+
+  if (!Number.isSafeInteger(input.pr) || input.pr < 1) return unknownObservation('PR 번호는 1 이상의 정수여야 함');
+  const run = input.run ?? ((command: string, args: readonly string[], options?: { cwd?: string }): PrToolCommandResult => {
+    try {
+      const r = spawnSync(command, [...args], {
+        encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024,
+        ...(options?.cwd ? { cwd: options.cwd } : {}),
+      });
+      return {
+        ok: r.status === 0 && !r.error,
+        out: (r.stdout ?? '').trim(),
+        err: [(r.stderr ?? '').trim(), r.error?.message ?? ''].filter(Boolean).join('\n'),
+      };
+    } catch (error) {
+      return { ok: false, out: '', err: error instanceof Error ? error.message : String(error) };
+    }
+  });
+  const result = run('gh', ['pr', 'view', String(input.pr), '--json', LINEAGE_READ_FIELDS], { cwd: input.cwd });
+  if (!result.ok) return unknownObservation(`PR 읽기 실패: ${result.err?.trim() || '명령 실패'}`);
+
+  let value: unknown;
+  try { value = JSON.parse(result.out); }
+  catch { return unknownObservation('PR 읽기 결과가 JSON이 아님'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return unknownObservation('PR 읽기 결과가 객체가 아님');
+  const pr = value as Record<string, unknown>;
+  if (pr.number !== input.pr) return unknownObservation('응답 PR 번호가 요청한 번호와 다름');
+
+  const head = typeof pr.headRefOid === 'string' && pr.headRefOid.trim() !== ''
+    ? { status: 'observed' as const, value: pr.headRefOid.trim(), evidence: `${readEvidence}: headRefOid` }
+    : lineageUnknown<string>('headRefOid가 응답에 없어 현재 head를 확인할 수 없음', `${readEvidence}: headRefOid 누락`);
+
+  const bodyWasRead = Object.hasOwn(pr, 'body') && (typeof pr.body === 'string' || pr.body === null);
+  let supersedes: PrLineageField<number>;
+  if (!bodyWasRead) {
+    supersedes = lineageUnknown<number>('body가 응답에 없어 Supersedes 관계를 확인할 수 없음', `${readEvidence}: body 누락`);
+  } else {
+    const lines = (typeof pr.body === 'string' ? pr.body : '').split(/\r?\n/);
+    const markers = lines.filter(line => /^\s*Supersedes\s*:/i.test(line));
+    if (markers.length === 0) {
+      supersedes = { status: 'observed', value: null, evidence: `${readEvidence}: body에서 명시적 Supersedes 줄 0개` };
+    } else if (markers.length !== 1) {
+      supersedes = lineageUnknown<number>('Supersedes 표지가 둘 이상이라 관계가 모호함', `${readEvidence}: Supersedes 줄 ${markers.length}개`);
+    } else {
+      const match = /^\s*Supersedes:\s*#([1-9]\d*)\s*$/i.exec(markers[0]!);
+      const number = match ? Number(match[1]) : NaN;
+      if (!Number.isSafeInteger(number) || number < 1 || number === input.pr) {
+        supersedes = lineageUnknown<number>('Supersedes 줄이 유효한 다른 PR 번호가 아님', `${readEvidence}: Supersedes 형식 오류`);
+      } else {
+        supersedes = { status: 'observed', value: number, evidence: `${readEvidence}: body의 명시적 줄 “Supersedes: #${number}”` };
+      }
+    }
+  }
+
+  const status = head.status === 'observed' && supersedes.status === 'observed' ? 'observed' : 'unknown';
+  return {
+    status,
+    pr: input.pr,
+    observedAt,
+    currentHead: head,
+    supersedes,
+    sourceCard: lineageUnmeasured<string>(),
+    olderScopeCarriedForward: lineageUnmeasured<boolean>(),
+    newerProtected: lineageUnmeasured<boolean>(),
+    cellStatus: lineageUnmeasured<string>(),
+    owner: lineageUnmeasured<string>(),
+    mergeSubstitution: lineageUnmeasured<boolean>(),
+    closeEligible: false,
+    ...(status === 'unknown' ? { reason: '일부 PR 사실을 읽지 못함' } : {}),
+  };
+}

package/src/pty-shell/pty-control-ipc.ts

@@ -48,6 +48,8 @@ export type PtyControlPayload =
 export interface PtyControlRequestOptions {
   /** 요청자가 주장하는 쓰기 주체. `'agent'` 는 run-identity 일치를 요구한다(`resolveRemoteControlActor`). */
   readonly actor?: PtyWriteActor;
+  /** Bound child identity for an agent-originated control message (e.g. mission HandReply). */
+  readonly requesterRunId?: string;
   readonly timeoutMs?: number;
   /** 대상 PTY를 발견한 매니페스트 뿌리. 연합 조회는 이 DB에 제어 요청을 남겨 그 행의 owner가 처리하게 한다. */
   readonly manifestDbPath?: string;
@@ -467,7 +469,8 @@ export async function requestRemotePtyControl(id: string, action: PtyControlActi
     const now = Date.now();
     // ⭐ 요청자의 run anchor 를 요청에 실어 보낸다 — 인가는 **owner 가** 자기 PTY 의 run 과 대조해 내린다
     //    (요청자 자기 신고를 그대로 믿지 않는다는 뜻이 아니라, 판정 지점이 자원 소유자라는 뜻).
-    d.run(`INSERT INTO pty_control_requests (request_id, pty_id, action, payload_json, actor, requester_run_id, owner_pid, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [requestId, targetId, action, payload ? JSON.stringify(payload) : null, actor, getHarnessRunId(process.env), ownerPid, 'pending', now, now]);
+  const requesterRunId = actor === 'agent' ? (options.requesterRunId?.trim() || getHarnessRunId(process.env)) : getHarnessRunId(process.env);
+  d.run(`INSERT INTO pty_control_requests (request_id, pty_id, action, payload_json, actor, requester_run_id, owner_pid, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [requestId, targetId, action, payload ? JSON.stringify(payload) : null, actor, requesterRunId, ownerPid, 'pending', now, now]);
     // ⭐ 깊은 유휴 감속 중인 owner 를 즉시 깨운다 — 행을 넣은 «뒤» 표식을 남기므로 그 재읽기가 이 행을 본다.
     //    표식은 그 행의 `ownerPid` «별» 파일이다 — 같은 원장을 공유하는 다른 owner 가 가져가지 못한다.
     signalPtyControlWake(queuePath ?? ptyManifestDbPath(), ownerPid);