elanous 0.2.42 → 0.2.43

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

@@ -44,6 +44,30 @@ export interface GuardVerdict { status: 'allow' | 'refuse' | 'unknown'; reasons:
   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;
@@ -554,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);

package/src/registry/catalog-server.ts

@@ -0,0 +1,232 @@
+import { createPublicKey, sign, verify, type KeyObject } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../debug/log.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import type { ModelSpec, ProviderRegistration } from './types.js';
+
+export const CATALOG_SERVER_URL = 'https://storage.googleapis.com/elanous-catalog/v1/catalog.json';
+export const CATALOG_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const CATALOG_STARTUP_TIMEOUT_MS = 2_000;
+
+export interface SignedCatalogPayload {
+  catalogVersion: number;
+  generatedAt: string;
+  providers: ProviderRegistration[];
+  models: ModelSpec[];
+}
+
+export interface SignedCatalogDocument extends SignedCatalogPayload {
+  signature: string;
+}
+
+export interface VerifiedCatalog {
+  payload: SignedCatalogPayload;
+  stale: boolean;
+}
+
+function catalogVersionFromFile(path: string): number | undefined {
+  try {
+    const match = readFileSync(path, 'utf8').match(/^catalogVersion:\s*(\d+)\s*$/m);
+    const version = match ? Number(match[1]) : NaN;
+    return Number.isSafeInteger(version) && version >= 1 ? version : undefined;
+  } catch { return undefined; }
+}
+
+function bundledCatalogVersion(): number | undefined {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(current, 'catalog', 'meta', 'catalogVersion.yaml');
+    if (existsSync(candidate)) return catalogVersionFromFile(candidate);
+    current = dirname(current);
+  }
+  return undefined;
+}
+
+export function catalogCachePath(): string {
+  const override = process.env.ELANOUS_CATALOG_SERVER_CACHE?.trim();
+  if (override) return override;
+  return join(getElanousConfigDir(), 'catalog', 'cache.json');
+}
+
+function bundledPublicKeyPath(): string {
+  const override = process.env.ELANOUS_CATALOG_PUBLIC_KEY_FILE?.trim();
+  if (override) return override;
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = join(current, 'catalog', 'signing', 'catalog-signing-public.pem');
+    if (existsSync(candidate)) return candidate;
+    current = dirname(current);
+  }
+  return join(dirname(fileURLToPath(import.meta.url)), '../../catalog/signing/catalog-signing-public.pem');
+}
+
+export function canonicalCatalogPayload(payload: SignedCatalogPayload): string {
+  return JSON.stringify({
+    catalogVersion: payload.catalogVersion,
+    generatedAt: payload.generatedAt,
+    providers: payload.providers,
+    models: payload.models,
+  });
+}
+
+export function signCatalogPayload(payload: SignedCatalogPayload, privateKey: string | Buffer | KeyObject): SignedCatalogDocument {
+  return { ...payload, signature: sign(null, Buffer.from(canonicalCatalogPayload(payload)), privateKey).toString('base64') };
+}
+
+function parsePayload(value: unknown): SignedCatalogPayload | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  if (!Number.isSafeInteger(raw.catalogVersion) || (raw.catalogVersion as number) < 1) return null;
+  if (typeof raw.generatedAt !== 'string' || !Number.isFinite(Date.parse(raw.generatedAt))) return null;
+  if (!Array.isArray(raw.providers) || !Array.isArray(raw.models)) return null;
+  if (!raw.providers.every((p) => p && typeof p === 'object' && typeof (p as Record<string, unknown>).id === 'string')) return null;
+  if (!raw.models.every((m) => m && typeof m === 'object'
+    && typeof (m as Record<string, unknown>).id === 'string'
+    && typeof (m as Record<string, unknown>).provider === 'string')) return null;
+  return {
+    catalogVersion: raw.catalogVersion as number,
+    generatedAt: raw.generatedAt,
+    providers: raw.providers as ProviderRegistration[],
+    models: raw.models as ModelSpec[],
+  };
+}
+
+export function verifyCatalogDocument(
+  value: unknown,
+  publicKeyPem: string,
+): SignedCatalogPayload | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.signature !== 'string') return null;
+  const payload = parsePayload(raw);
+  if (!payload) return null;
+  try {
+    const signature = Buffer.from(raw.signature, 'base64');
+    return verify(null, Buffer.from(canonicalCatalogPayload(payload)), createPublicKey(publicKeyPem), signature)
+      ? payload
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readVerifiedCatalogCache(opts: {
+  cachePath?: string;
+  publicKeyPem?: string;
+  now?: number;
+} = {}): VerifiedCatalog | null {
+  const path = opts.cachePath ?? catalogCachePath();
+  try {
+    const key = opts.publicKeyPem ?? readFileSync(bundledPublicKeyPath(), 'utf8');
+    const payload = verifyCatalogDocument(JSON.parse(readFileSync(path, 'utf8')), key);
+    if (!payload) return null;
+    const age = Math.max(0, (opts.now ?? Date.now()) - Date.parse(payload.generatedAt));
+    const stale = age > CATALOG_REFRESH_INTERVAL_MS;
+    debug.log('registry.catalog', 'catalog.source', { source: 'server-cache', stale, catalogVersion: payload.catalogVersion });
+    if (stale) debug.log('registry.catalog', 'catalog.stale', { source: 'server-cache', stale: true, ageMs: age, catalogVersion: payload.catalogVersion }, { level: 'warn' });
+    return { payload, stale };
+  } catch {
+    return null;
+  }
+}
+
+export type RefreshCatalogResult =
+  | { ok: true; payload: SignedCatalogPayload }
+  | { ok: false; reason: 'key-unavailable' | 'fetch-failed' | 'http-error' | 'invalid-json' | 'signature-rejected' | 'version-rejected' | 'cache-write-failed' };
+
+export async function refreshServerCatalog(opts: {
+  fetchImpl?: typeof fetch;
+  url?: string;
+  cachePath?: string;
+  publicKeyPem?: string;
+  timeoutMs?: number;
+} = {}): Promise<RefreshCatalogResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const cachePath = opts.cachePath ?? catalogCachePath();
+  const timeoutMs = opts.timeoutMs ?? CATALOG_STARTUP_TIMEOUT_MS;
+  let key: string;
+  try {
+    key = opts.publicKeyPem ?? readFileSync(bundledPublicKeyPath(), 'utf8');
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'key-unavailable', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'key-unavailable' };
+  }
+  const previous = readVerifiedCatalogCache({ cachePath, publicKeyPem: key });
+  let response: Response;
+  try {
+    response = await fetchImpl(opts.url ?? CATALOG_SERVER_URL, { signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'fetch-failed', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'fetch-failed' };
+  }
+  if (!response.ok) return { ok: false, reason: 'http-error' };
+  let document: unknown;
+  try { document = await response.json(); }
+  catch { return { ok: false, reason: 'invalid-json' }; }
+  const payload = verifyCatalogDocument(document, key);
+  if (!payload) {
+    debug.log('registry.catalog', 'catalog.signature-rejected', { source: 'server', reason: 'invalid-signature-or-schema' }, { level: 'warn' });
+    return { ok: false, reason: 'signature-rejected' };
+  }
+  // A cold install has no signed server receipt yet, so the packaged catalog is its rollback floor.
+  const versionFloor = Math.max(previous?.payload.catalogVersion ?? 0,
+    bundledCatalogVersion() ?? 0);
+  if (payload.catalogVersion < versionFloor) {
+    debug.log('registry.catalog', 'catalog.version-rejected', {
+      source: 'server', reason: 'version-rollback', currentVersion: versionFloor, receivedVersion: payload.catalogVersion,
+    }, { level: 'warn' });
+    return { ok: false, reason: 'version-rejected' };
+  }
+  const signedDocument = document as SignedCatalogDocument;
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    const temporary = `${cachePath}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(signedDocument, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, cachePath);
+  } catch (error) {
+    debug.log('registry.catalog', 'catalog.refresh-failed', { source: 'server', reason: 'cache-write-failed', message: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+    return { ok: false, reason: 'cache-write-failed' };
+  }
+  const ageMs = Math.max(0, Date.now() - Date.parse(payload.generatedAt));
+  debug.log('registry.catalog', 'catalog.source', {
+    source: 'server', stale: ageMs > CATALOG_REFRESH_INTERVAL_MS, catalogVersion: payload.catalogVersion,
+  });
+  return { ok: true, payload };
+}
+
+let scheduledRefresh: Promise<void> | null = null;
+let lastRefreshAttempt = 0;
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+/** Kick remote refresh behind startup; the callback rebuilds the catalog only after a verified cache write. */
+export function scheduleServerCatalogRefresh(onUpdated: () => void): void {
+  if (process.env.NODE_ENV === 'test') return;
+  if (scheduledRefresh || refreshTimer) return;
+  const now = Date.now();
+  const cached = readVerifiedCatalogCache();
+  const cacheAgeMs = cached ? Math.max(0, now - Date.parse(cached.payload.generatedAt)) : Number.POSITIVE_INFINITY;
+  const untilCacheStale = cached && !cached.stale ? Math.max(1_000, CATALOG_REFRESH_INTERVAL_MS - cacheAgeMs) : 0;
+  const untilRetry = Math.max(0, CATALOG_REFRESH_INTERVAL_MS - (now - lastRefreshAttempt));
+  const delay = Math.max(untilCacheStale, untilRetry);
+  if (delay > 0) {
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      scheduleServerCatalogRefresh(onUpdated);
+    }, delay);
+    refreshTimer.unref?.();
+    return;
+  }
+  lastRefreshAttempt = now;
+  scheduledRefresh = refreshServerCatalog().then((result) => {
+    if (result.ok) onUpdated();
+  }).finally(() => {
+    scheduledRefresh = null;
+    refreshTimer = setTimeout(() => {
+      refreshTimer = null;
+      scheduleServerCatalogRefresh(onUpdated);
+    }, CATALOG_REFRESH_INTERVAL_MS);
+    refreshTimer.unref?.();
+  });
+}