elanous 0.2.0 → 0.2.5

package/src/plugin-hooks/dispatcher.ts

@@ -19,6 +19,7 @@
 
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
 import { join } from 'node:path';
 import {
   ALL_HOOK_EVENTS,
@@ -106,10 +107,15 @@ export class HookDispatcher {
     if (handler.priority <= RESERVED_PRIORITY_MAX) {
       // Advisory only — built-in Andon/Budget/Termination own this
       // range. User plugins must stay ≥10.
-      this.warn(
-        `hook '${handler.id}' registered with reserved priority ${handler.priority} ` +
-        `(range 0-${RESERVED_PRIORITY_MAX} is reserved for built-ins)`,
-      );
+      const message = `hook '${handler.id}' registered with reserved priority ${handler.priority} ` +
+        `(range 0-${RESERVED_PRIORITY_MAX} is reserved for built-ins)`;
+      // 내장 훅(`core:*`)은 이 구간의 «주인»이다 — 경고 대상이 아니다. 종전엔 `core:andon` 만 뺐고
+      // `core:route-banner`·`core:missions` 경고가 TUI 입력줄 위로 새어 화면을 깼다(🅢 2026-09-27 실측 · /research status).
+      if (handler.id.startsWith('core:')) {
+        debug.log('plugin-hooks', 'reserved-priority', { message });
+      } else {
+        this.warn(message);
+      }
     }
     list.push(handler);
     this.handlers.set(handler.event, list);

package/src/plugins/core/host.ts

@@ -15,7 +15,9 @@
 // commands. Full key-routing and LLM tool dispatch land in Phase 4.
 
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'fs';
-import { join, resolve } from 'path';
+import { basename, dirname, join, resolve } from 'path';
+import { listInstalledPlugins } from '../install/plugin-install.js';
+import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { homedir } from 'os';
 import type {
   ElanousPlugin, PluginContext, SlashCommand, PaneSlot, KeyEvent, Action, LLMToolDef,
@@ -51,6 +53,8 @@ import { buildPromptInjection, getPromptBankStore } from '../../prompt-bank/inde
 import { getGlobalElementRegistry, publishElementEvent } from '../../element-registry/index.js';
 import { mintPluginUri } from '../../mss/uri/builder.js';
 import type { PluginUri } from '../../mss/uri/brand.js';
+import { loadPluginNodes } from '../../graph-kinds/plugin-nodes.js';
+import { getNodeKindRegistration, listNodeKinds, unregisterPluginNodeKind, type NodeKindEntry } from '../../graph-kinds/registry.js';
 
 /** Clamp a tool handler's return value to something short enough for
  *  the debug log. Preserves the shape for JSON.stringify so small
@@ -203,6 +207,8 @@ export interface PluginHostOptions {
   statePersistence?: import('../../plugin-state/persistence.js').PluginStatePersistence;
   /** Optional user plugin directory, primarily for isolated host instances. */
   userDir?: string;
+  /** Optional pack directory for isolated discovery tests. */
+  packsDir?: string;
 }
 
 // Parse a Keybinding.key string ('C-S-p', 'tab', 'escape') into its
@@ -224,10 +230,20 @@ export function matchesKey(spec: string, ev: KeyEvent): boolean {
 }
 
 export const BUILTIN_DIR = resolve(import.meta.dir, '..', '..', '..', 'plugins');
+export const PACKS_DIR = resolve(import.meta.dir, '..', '..', '..', 'packs');
 export const USER_DIR = join(homedir(), '.claude', 'plugins');
 
+/** 코드 없이 스킬·그래프만 싣는 팩인가 — 진입점이 기본값(`./plugin.ts`)이고 파일이 없으며, 스킬·그래프를 선언하거나 `skills/` 폴더가 있다. */
+export function isSkillOnlyPack(pluginDir: string, manifest: { main: string; contributes?: { skills?: unknown[]; graphs?: unknown[] } }, hasLegacyEntry: boolean): boolean {
+  if (hasLegacyEntry) return false;
+  if (manifest.main !== './plugin.ts') return false; // 명시한 진입점이 없으면 그건 결함이다 — 경고를 유지한다.
+  const declares = (manifest.contributes?.skills?.length ?? 0) > 0 || (manifest.contributes?.graphs?.length ?? 0) > 0;
+  return declares || existsSync(join(pluginDir, 'skills'));
+}
+
 export class PluginHost {
   private available = new Map<string, PluginEntry>();
+  private discoveredNodeKinds = new Map<string, NodeKindEntry>();
   private activeEntry: ActivePlugin | null = null;
   private hooks: HostHooks;
   /** Optional widget host. When set, plugin-host calls buildLayout on
@@ -241,6 +257,7 @@ export class PluginHost {
   private capabilityPolicy = new PluginCapabilityPolicy();
   private trustStore: PluginTrustStore;
   private userDir: string;
+  private packsDir: string;
   private tasks = new PluginTaskService();
   private themeCache = new Map<string, { mtimeMs: number; tokens: ThemeTokenInput }>();
   /** PX-2 P4: plugin-state persistence backend (optional). */
@@ -259,6 +276,7 @@ export class PluginHost {
     this.widgetHost = widgetHost;
     this.trustStore = opts.trustStore ?? new PluginTrustStore();
     this.userDir = opts.userDir ?? USER_DIR;
+    this.packsDir = opts.packsDir ?? PACKS_DIR;
     this.statePersistence = opts.statePersistence ?? null;
     this.registerExecutionHistoryTools();
     this.registerThemeTools();
@@ -474,15 +492,86 @@ export class PluginHost {
     this.widgetHost = widgetHost;
   }
 
-  /** Scan both built-in and user directories, importing every plugin.ts. */
+  /** Scan built-in and user directories, then ledger-listed installations and declared nodes from plugins and packs. */
   async discover(): Promise<void> {
+    for (const owner of this.discoveredNodeKinds.values()) {
+      if (owner.plugin) unregisterPluginNodeKind(owner.graph, owner.kind, owner.plugin, owner);
+    }
+    this.discoveredNodeKinds.clear();
     this.available.clear();
     await this.scanDir(BUILTIN_DIR, 'builtin');
     await this.scanDir(this.userDir, 'user');
+    try {
+      const root = elanousStateRoot();
+      const ledgerPath = join(root, 'plugins', 'installed.json');
+      if (existsSync(ledgerPath)) {
+        const ledger: unknown = JSON.parse(readFileSync(ledgerPath, 'utf8'));
+        if (!Array.isArray(ledger) || !ledger.every(row => row && typeof row === 'object'
+          && typeof row.name === 'string' && typeof row.version === 'string' && typeof row.market === 'string')) throw new Error('invalid plugin ledger');
+        const registered = new Set(ledger.map(row => `${row.market}/${row.name}/${row.version}`));
+        for (const installed of listInstalledPlugins(root)) {
+          if (!registered.has(`${installed.market}/${installed.name}/${installed.version}`)) continue;
+          await this.scanDir(dirname(installed.path), 'installed', basename(installed.path), installed.name);
+        }
+      }
+    } catch {
+      this.hooks.log('⚠ plugin installed.json is invalid; skipping installed plugins');
+      debug.log('plugin.discovery', 'error', { reason: 'invalid installed plugin ledger' }, { level: 'warn' });
+    }
+    for (const entry of this.available.values()) {
+      this.loadDiscoveredNodes(entry.path, entry.manifest);
+    }
+    this.scanPackNodes();
     debug.log('plugin.discovery', 'complete', { count: this.available.size });
   }
 
-  private async scanDir(dir: string, source: PluginSource): Promise<void> {
+  private loadDiscoveredNodes(pluginDir: string, manifest: PluginManifest): void {
+    const before = new Set(listNodeKinds().map((entry) => `${entry.graph}:${entry.kind}`));
+    try {
+      const result = loadPluginNodes(pluginDir, manifest);
+      for (const error of result.errors) {
+        this.hooks.log(`⚠ plugin "${manifest.id}" node skipped: ${error}`);
+        debug.log('plugin.discovery', 'error', { plugin: manifest.id, reason: String(error) }, { level: 'error' });
+      }
+    } catch (err: any) {
+      const reason = err?.message || String(err);
+      this.hooks.log(`⚠ plugin "${manifest.id}" nodes failed to load: ${reason}`);
+      debug.log('plugin.discovery', 'error', { plugin: manifest.id, reason }, { level: 'error' });
+    } finally {
+      for (const entry of listNodeKinds()) {
+        const key = `${entry.graph}:${entry.kind}`;
+        if (!before.has(key) && entry.plugin === manifest.id) {
+          const registered = getNodeKindRegistration(entry.graph, entry.kind);
+          if (registered) this.discoveredNodeKinds.set(key, registered);
+        }
+      }
+    }
+  }
+
+  private scanPackNodes(): void {
+    if (!existsSync(this.packsDir)) return;
+    let names: string[];
+    try {
+      names = readdirSync(this.packsDir);
+    } catch (err: any) {
+      debug.log('plugin.discovery', 'error', { plugin: null, reason: err?.message || String(err) }, { level: 'error' });
+      return;
+    }
+    for (const name of names) {
+      const packDir = join(this.packsDir, name);
+      try {
+        if (!statSync(packDir).isDirectory() || !existsSync(join(packDir, 'plugin.json'))) continue;
+        const { manifest } = loadPluginManifestFromDir(packDir, { id: name, main: './plugin.ts' });
+        this.loadDiscoveredNodes(packDir, manifest);
+      } catch (err: any) {
+        const reason = err?.message || String(err);
+        this.hooks.log(`⚠ failed to load pack manifest ${name}: ${reason}`);
+        debug.log('plugin.discovery', 'error', { plugin: name, reason }, { level: 'error' });
+      }
+    }
+  }
+
+  private async scanDir(dir: string, source: PluginSource, onlyEntry?: string, expectedId?: string): Promise<void> {
     const exists = existsSync(dir);
     if (!exists) {
       debug.log('plugin.discovery', 'scan', { dir, source, exists, count: 0 });
@@ -490,7 +579,7 @@ export class PluginHost {
     }
     let entries: string[] = [];
     try {
-      entries = readdirSync(dir);
+      entries = onlyEntry ? [onlyEntry] : readdirSync(dir);
     } catch (err: any) {
       debug.log('plugin.discovery', 'scan', { dir, source, exists, count: 0 });
       debug.log('plugin.discovery', 'error', {
@@ -505,6 +594,13 @@ export class PluginHost {
       let isDir = false;
       try { isDir = statSync(pluginDir).isDirectory(); } catch { continue; }
       if (!isDir) continue;
+      // Portable graph bundles are installer inputs, not legacy repository plugins.
+      if (source === 'builtin' && existsSync(join(pluginDir, 'plugin.json'))) {
+        try {
+          const raw = JSON.parse(readFileSync(join(pluginDir, 'plugin.json'), 'utf8'));
+          if (raw?.extensions?.['ai.elanous'] && !raw.main) continue;
+        } catch { /* manifest loader below reports malformed files */ }
+      }
       const hasLegacyEntry = existsSync(join(pluginDir, 'plugin.ts'));
       let manifestLoad: ReturnType<typeof loadPluginManifestFromDir>;
       try {
@@ -515,6 +611,8 @@ export class PluginHost {
         debug.log('plugin.discovery', 'error', { plugin: name, reason }, { level: 'error' });
         continue;
       }
+      if (expectedId && manifestLoad.manifest.id !== expectedId) continue;
+      if (source === 'installed' && this.available.has(manifestLoad.manifest.id)) continue;
       const entry = join(pluginDir, manifestLoad.manifest.main);
       if (!existsSync(entry)) {
         // Only warn when the directory *looks like* a plugin — i.e. it
@@ -524,6 +622,12 @@ export class PluginHost {
         // ~/.claude/plugins/{cache,data,marketplaces} internal state)
         // are silently skipped: they never intended to be plugins.
         const looksLikePlugin = hasLegacyEntry || !manifestLoad.inferred;
+        // 스킬·그래프만 싣는 팩(공식 `elanous-basics` 등)은 코드 진입점이 없다 — 매니페스트가 `main` 을
+        // 적지 않아 기본값 `./plugin.ts` 가 들어온 것뿐이다. 부팅마다 «main not found» 경고를 내지 않는다.
+        if (looksLikePlugin && isSkillOnlyPack(pluginDir, manifestLoad.manifest, hasLegacyEntry)) {
+          debug.log('plugin.discovery', 'skill-only', { plugin: manifestLoad.manifest.id });
+          continue;
+        }
         if (looksLikePlugin) {
           this.hooks.log(`⚠ plugin "${manifestLoad.manifest.id}" main not found: ${manifestLoad.manifest.main}`);
           debug.log('plugin.discovery', 'error', {

package/src/plugins/core/manifest.ts

@@ -15,7 +15,7 @@ import type {
 } from '../../plugin-workflows/types.js';
 import { WORKFLOW_DEFAULTS } from '../../plugin-workflows/types.js';
 
-export type PluginSource = 'builtin' | 'user' | 'workspace';
+export type PluginSource = 'builtin' | 'user' | 'workspace' | 'installed';
 
 export type PluginCapability =
   | { kind: 'process:spawn'; commands?: string[] }
@@ -74,6 +74,19 @@ export interface PluginManifestContributes {
   mcpServers?: PluginNamedContribution[];
   /** Portable provider contributions (classifier bucket). */
   providers?: PluginNamedContribution[];
+  /** Declarative node definitions, relative to the plugin root. */
+  nodes?: string[];
+  /** Agent Plugins extension assets; paths remain relative to the plugin root. */
+  graphs?: string[];
+  vocab?: string[];
+  connectors?: PluginConnectorContribution[];
+}
+
+export interface PluginConnectorContribution {
+  id: string;
+  fields?: Array<{ name: string; secret?: boolean; [key: string]: unknown }>;
+  userConfig?: Array<{ key: string; label?: string; secret?: boolean; [key: string]: unknown }>;
+  [key: string]: unknown;
 }
 
 /** Generic named contribution used by portable classifier buckets. */
@@ -247,7 +260,7 @@ export interface PluginManifestLoadResult {
   inferred: boolean;
 }
 
-const MANIFEST_FILES = ['plugin.json', join('.elanous-plugin', 'plugin.json')];
+const MANIFEST_FILES = ['plugin.json', join('.elanous-plugin', 'plugin.json'), join('.codex-plugin', 'plugin.json')];
 
 export function loadPluginManifestFromDir(
   pluginDir: string,
@@ -264,7 +277,11 @@ export function loadPluginManifestFromDir(
       throw new Error(`${rel}: invalid JSON: ${err?.message || err}`);
     }
     return {
-      manifest: parsePluginManifest(json, { fallbackId: fallback.id, fallbackMain: fallback.main ?? './plugin.ts' }),
+      manifest: parsePluginManifest(json, {
+        fallbackId: fallback.id,
+        fallbackMain: fallback.main ?? './plugin.ts',
+        agentPlugin: rel === join('.codex-plugin', 'plugin.json'),
+      }),
       path,
       inferred: false,
     };
@@ -289,19 +306,27 @@ export function loadPluginManifestFromDir(
 
 export function parsePluginManifest(
   value: unknown,
-  opts: { fallbackId?: string; fallbackMain?: string } = {},
+  opts: { fallbackId?: string; fallbackMain?: string; agentPlugin?: boolean } = {},
 ): PluginManifest {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('plugin manifest must be an object');
   }
   const raw = value as Record<string, unknown>;
-  const id = normalizeId(stringOr(raw.id, opts.fallbackId), 'id');
+  const agentPlugin = opts.agentPlugin === true
+    || (typeof raw.$schema === 'string' && raw.$schema.startsWith('https://agentplugins.dev/'));
+  const id = normalizeId(stringOr(raw.id, (agentPlugin || opts.fallbackId === undefined)
+    && typeof raw.name === 'string' && raw.name.trim() ? raw.name : opts.fallbackId), 'id');
   const name = stringOr(raw.name, id);
   const version = stringOr(raw.version, '0.0.0');
   const main = normalizeMain(stringOr(raw.main, opts.fallbackMain ?? './plugin.ts'));
   const activationEvents = stringArrayOr(raw.activationEvents, ['onCommand']);
-  const contributes = parseContributes(raw.contributes);
-  const capabilities = parseCapabilities(raw.capabilities);
+  const extension = parseElanousExtension(raw.extensions);
+  const contributes = parseContributes({ ...extension.contributes, ...objectOrEmpty(raw.contributes, 'contributes') });
+  const capabilities = parseCapabilities(raw.capabilities === undefined
+    ? extension.capabilities
+    : extension.capabilities === undefined
+      ? raw.capabilities
+      : [...parseCapabilities(raw.capabilities), ...parseCapabilities(extension.capabilities)]);
   const dependencies = parseDependencies(raw.dependencies);
   const description = typeof raw.description === 'string' ? raw.description : undefined;
   const allowMultiActive = typeof raw.allowMultiActive === 'boolean' ? raw.allowMultiActive : undefined;
@@ -323,6 +348,26 @@ export function parsePluginManifest(
   };
 }
 
+function objectOrEmpty(value: unknown, label: string): Record<string, unknown> {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function parseElanousExtension(value: unknown): { contributes: Record<string, unknown>; capabilities?: unknown } {
+  const extensions = objectOrEmpty(value, 'extensions');
+  const extension = objectOrEmpty(extensions['ai.elanous'], 'extensions["ai.elanous"]');
+  const contributes = objectOrEmpty(extension.contributes, 'extensions["ai.elanous"].contributes');
+  return {
+    contributes: {
+      ...contributes,
+      ...Object.fromEntries(['nodes', 'graphs', 'vocab', 'connectors'].filter(key => extension[key] !== undefined)
+        .map(key => [key, extension[key]])),
+    },
+    capabilities: extension.capabilities,
+  };
+}
+
 function parseActivePeerCompat(value: unknown): PluginManifest['activePeerCompat'] {
   if (value === undefined) return undefined;
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -390,6 +435,10 @@ function parseContributes(value: unknown): PluginManifestContributes {
     ...(raw.tools !== undefined ? { tools: parseNamedContributions(raw.tools, 'contributes.tools') } : {}),
     ...(raw.mcpServers !== undefined ? { mcpServers: parseNamedContributions(raw.mcpServers, 'contributes.mcpServers') } : {}),
     ...(raw.providers !== undefined ? { providers: parseNamedContributions(raw.providers, 'contributes.providers') } : {}),
+    ...(raw.nodes !== undefined ? { nodes: parseNodePaths(raw.nodes) } : {}),
+    ...(raw.graphs !== undefined ? { graphs: parseAssetPaths(raw.graphs, 'contributes.graphs') } : {}),
+    ...(raw.vocab !== undefined ? { vocab: parseAssetPaths(raw.vocab, 'contributes.vocab') } : {}),
+    ...(raw.connectors !== undefined ? { connectors: parseConnectors(raw.connectors) } : {}),
   };
 }
 
@@ -913,6 +962,54 @@ function parseThemes(value: unknown): NonNullable<PluginManifestContributes['the
   });
 }
 
+function parseNodePaths(value: unknown): string[] {
+  const label = 'contributes.nodes';
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  return value.map((item, idx) => {
+    const field = `${label}[${idx}]`;
+    if (typeof item !== 'string' || !item.startsWith('./') || item.length <= 2 || item.includes('\0')) {
+      throw new Error(`${field} must be a path starting with ./ inside the plugin dir`);
+    }
+    return validatePluginRelativePath(item, field);
+  });
+}
+
+function parseAssetPaths(value: unknown, label: string): string[] {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  return value.map((item, idx) => {
+    if (typeof item !== 'string') throw new Error(`${label}[${idx}] must be a path`);
+    return validatePluginRelativePath(item, `${label}[${idx}]`);
+  });
+}
+
+function parseConnectors(value: unknown): PluginConnectorContribution[] {
+  if (!Array.isArray(value)) throw new Error('contributes.connectors must be an array');
+  const seen = new Set<string>();
+  return value.map((item, idx) => {
+    const label = `contributes.connectors[${idx}]`;
+    const raw = objectOrEmpty(item, label);
+    const id = normalizeId(stringOr(raw.id), `${label}.id`);
+    if (seen.has(id)) throw new Error(`${label}.id '${id}' is duplicated`);
+    seen.add(id);
+    const fields = raw.fields === undefined ? undefined : parseConnectorFields(raw.fields, `${label}.fields`, 'name');
+    const userConfig = raw.userConfig === undefined ? undefined : parseConnectorFields(raw.userConfig, `${label}.userConfig`, 'key');
+    return { ...raw, id, ...(fields ? { fields } : {}), ...(userConfig ? { userConfig } : {}) } as PluginConnectorContribution;
+  });
+}
+
+function parseConnectorFields(value: unknown, label: string, key: 'name' | 'key') {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  return value.map((item, idx) => {
+    const raw = objectOrEmpty(item, `${label}[${idx}]`);
+    const field = stringOr(raw[key]);
+    if (raw.secret !== undefined && typeof raw.secret !== 'boolean') throw new Error(`${label}[${idx}].secret must be a boolean`);
+    if (key === 'key' && raw.label !== undefined && typeof raw.label !== 'string') {
+      throw new Error(`${label}[${idx}].label must be a string`);
+    }
+    return { ...raw, [key]: field };
+  });
+}
+
 function parseNamedContributions(value: unknown, label: string): PluginNamedContribution[] {
   if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
   return value.map((item, idx) => {

package/src/plugins/install/market-fetch.ts

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { withFileLockSync } from '../../storage/file-lock.js';
+import { dirname, join, resolve } from 'node:path';
+import { elanousStateRoot } from '../../autopilot/state-paths.js';
+import { userConfigPath } from '../../user-config.js';
+import { OFFICIAL_INDEX_KEYS } from '../../market/official-keys.js';
+import { verifyIndex, type MarketplaceIndex } from '../../market/signed-index.js';
+
+// Official marketplace (🅞 #21756 · GitHub Pages of ElanvitalAI/elanous-plugins). 🩸 09-29: this was `elanous.pages.dev`,
+// which does not resolve — every `<name>@elanous` install would have failed. Measured: marketplace.json ⊕ index.sig = 200.
+export const ELANOUS_MARKET_URL = 'https://elanvitalai.github.io/elanous-plugins/';
+const NAME = /^[a-z0-9][a-z0-9-]{1,39}$/;
+const MAX_INDEX_BYTES = 8 * 1024 * 1024;
+
+export interface MarketConfig { name: string; url: string }
+export interface MarketFetchOptions {
+  root?: string;
+  marketDir?: string;
+  configPath?: string;
+  fetcher?: typeof fetch;
+  verifySignature?: typeof verifyIndex;
+  trustedKeys?: ReadonlyArray<{ keyId: string; publicKey: string }>;
+  refresh?: boolean;
+}
+export interface MarketIndex {
+  market: MarketConfig;
+  index: MarketplaceIndex;
+  directory: string;
+  signature: 'ok';
+  keyId: string;
+}
+export class MarketFetchError extends Error {
+  constructor(public readonly reason: 'io' | 'signature', message: string) {
+    super(message);
+    this.name = 'MarketFetchError';
+  }
+}
+
+function configPath(opts: MarketFetchOptions): string { return opts.configPath ?? userConfigPath(); }
+function config(opts: MarketFetchOptions): Record<string, unknown> {
+  const path = configPath(opts);
+  if (!existsSync(path)) return {};
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (value && typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown>;
+  } catch { /* reported below */ }
+  throw new MarketFetchError('io', 'invalid user market configuration');
+}
+function marketSettings(value: Record<string, unknown>): Record<string, unknown> {
+  const settings = value.market;
+  if (settings === undefined) return {};
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new MarketFetchError('io', 'invalid market configuration');
+  return settings as Record<string, unknown>;
+}
+function marketUrl(value: unknown): string {
+  if (typeof value !== 'string') throw new MarketFetchError('io', 'invalid market URL: expected HTTPS URL');
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || !url.hostname) throw new Error('unsafe URL');
+    if (!url.pathname.endsWith('/')) url.pathname += '/';
+    return url.href;
+  } catch { throw new MarketFetchError('io', 'invalid market URL: expected HTTPS URL without credentials, query or fragment'); }
+}
+function configuredMarkets(settings: Record<string, unknown>): MarketConfig[] {
+  const entries = settings.markets;
+  if (entries === undefined) return [];
+  if (!Array.isArray(entries)) throw new MarketFetchError('io', 'invalid market configuration: markets must be an array');
+  const names = new Set(['elanous']);
+  return entries.map((entry: unknown) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new MarketFetchError('io', 'invalid market configuration: expected name and url');
+    const { name, url } = entry as Record<string, unknown>;
+    if (typeof name !== 'string' || !NAME.test(name) || names.has(name)) throw new MarketFetchError('io', `invalid or duplicate market name: ${String(name)}`);
+    names.add(name);
+    return { name, url: marketUrl(url) };
+  });
+}
+function trust(settings: Record<string, unknown>, opts: MarketFetchOptions): ReadonlyArray<{ keyId: string; publicKey: string }> {
+  const additional = settings.trustedKeys;
+  if (additional !== undefined && (!Array.isArray(additional) || !additional.every(key => key && typeof key.keyId === 'string' && typeof key.publicKey === 'string'))) {
+    throw new MarketFetchError('io', 'invalid trusted keys configuration');
+  }
+  // A configured key cannot replace an official key with the same identifier.
+  const keys = new Map(OFFICIAL_INDEX_KEYS.map(key => [key.keyId, key]));
+  for (const key of [...(additional ?? []), ...(opts.trustedKeys ?? [])] as Array<{ keyId: string; publicKey: string }>) {
+    if (keys.has(key.keyId) && keys.get(key.keyId)?.publicKey !== key.publicKey) throw new MarketFetchError('io', `conflicting trusted key: ${key.keyId}`);
+    keys.set(key.keyId, key);
+  }
+  return [...keys.values()];
+}
+
+export function listMarkets(opts: MarketFetchOptions = {}): MarketConfig[] {
+  return [{ name: 'elanous', url: ELANOUS_MARKET_URL }, ...configuredMarkets(marketSettings(config(opts)))];
+}
+
+export function addMarket(name: string, url: string, opts: MarketFetchOptions = {}): MarketConfig {
+  if (!NAME.test(name) || name === 'elanous') throw new MarketFetchError('io', `invalid market name: ${name}`);
+  const market = { name, url: marketUrl(url) };
+  const value = config(opts);
+  const settings = marketSettings(value);
+  if (configuredMarkets(settings).some(existing => existing.name === name)) throw new MarketFetchError('io', `market already exists: ${name}`);
+  const path = configPath(opts);
+  const temp = `${path}.${process.pid}.tmp`;
+  mkdirSync(dirname(path), { recursive: true });
+  try {
+    writeFileSync(temp, JSON.stringify({ ...value, market: { ...settings, markets: [...configuredMarkets(settings), market] } }, null, 2));
+    // Keep the original permission bits (a config holding secrets is often 0600); a new file starts private.
+    chmodSync(temp, existsSync(path) ? statSync(path).mode & 0o777 : 0o600);
+    renameSync(temp, path);
+  } finally { rmSync(temp, { force: true }); }
+  return market;
+}
+
+function location(name: string, opts: MarketFetchOptions): string {
+  return join(resolve(opts.marketDir ?? join(opts.root ?? elanousStateRoot(), 'markets')), name);
+}
+
+interface CacheState { url: string; lastSequence: number; indexHash: string; signatureHash: string }
+
+function cacheState(path: string): CacheState | undefined {
+  if (!existsSync(path)) return undefined;
+  let value: unknown;
+  try { value = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw new MarketFetchError('io', 'invalid market cache state'); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new MarketFetchError('io', 'invalid market cache state');
+  const { url, lastSequence, indexHash, signatureHash } = value as Record<string, unknown>;
+  if (typeof url !== 'string' || !Number.isSafeInteger(lastSequence) || (lastSequence as number) < 0
+    || typeof indexHash !== 'string' || !/^[a-f0-9]{64}$/.test(indexHash)
+    || typeof signatureHash !== 'string' || !/^[a-f0-9]{64}$/.test(signatureHash)) {
+    throw new MarketFetchError('io', 'invalid market cache state');
+  }
+  return { url, lastSequence: lastSequence as number, indexHash, signatureHash };
+}
+
+function digest(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function checked(bytes: Uint8Array, signatureText: string, name: string, keys: ReturnType<typeof trust>, opts: MarketFetchOptions, lastSequence?: number): { index: MarketplaceIndex; keyId: string } {
+  const result = (opts.verifySignature ?? verifyIndex)({ marketplaceBytes: bytes, signatureText, trustedKeys: keys, lastSequence });
+  if (!result.ok) throw new MarketFetchError('signature', `${result.reason}: ${result.detail}`);
+  if (result.index.name !== name) throw new MarketFetchError('io', `market index name mismatch: ${name}`);
+  return { index: result.index, keyId: result.keyId };
+}
+
+// Serialize cache reads, verification and publication for callers sharing a market directory.
+const marketIndexQueues = new Map<string, Promise<void>>();
+
+export function ensureMarketIndex(name: string, opts: MarketFetchOptions = {}): Promise<MarketIndex> {
+  const directory = location(name, opts);
+  const previous = marketIndexQueues.get(directory) ?? Promise.resolve();
+  const result = previous.then(() => fetchMarketIndex(name, opts));
+  const tail = result.then(() => {}, () => {});
+  marketIndexQueues.set(directory, tail);
+  void tail.then(() => {
+    if (marketIndexQueues.get(directory) === tail) marketIndexQueues.delete(directory);
+  });
+  return result;
+}
+
+async function fetchMarketIndex(name: string, opts: MarketFetchOptions): Promise<MarketIndex> {
+  const market = listMarkets(opts).find(entry => entry.name === name);
+  if (!market) throw new MarketFetchError('io', `market not configured: ${name}`);
+  const keys = trust(marketSettings(config(opts)), opts);
+  const directory = location(name, opts);
+  const indexFile = join(directory, 'marketplace.json');
+  const sigFile = join(directory, 'index.sig');
+  const stateFile = join(directory, 'cache-state.json');
+  const state = cacheState(stateFile);
+  // The URL is part of the cache identity, not just the market name.
+  const lastSequence = state?.url === market.url ? state.lastSequence : undefined;
+  let cached: ReturnType<typeof checked> | undefined;
+  if (state?.url === market.url && existsSync(indexFile) && existsSync(sigFile)) {
+    const indexBytes = readFileSync(indexFile);
+    const signatureText = readFileSync(sigFile, 'utf8');
+    if (digest(indexBytes) === state.indexHash && digest(signatureText) === state.signatureHash) {
+      try {
+        cached = checked(indexBytes, signatureText, name, keys, opts, lastSequence);
+      } catch (error) {
+        if (!(error instanceof MarketFetchError)) throw error;
+      }
+    }
+    if (cached && !opts.refresh) return { market, directory, signature: 'ok', ...cached };
+  }
+  const fetcher = opts.fetcher ?? fetch;
+  const load = async (file: string): Promise<Uint8Array> => {
+    const url = new URL(file, market.url);
+    let response: Response;
+    try { response = await fetcher(url.href, { redirect: 'error' }); }
+    catch { throw new MarketFetchError('io', `market fetch failed (${file}): network error`); }
+    if (!response.ok) throw new MarketFetchError('io', `market fetch failed (${file}): HTTP ${response.status}`);
+    if (response.redirected || (response.url && response.url !== url.href)) throw new MarketFetchError('io', `market fetch was redirected (${file})`);
+    if (!response.body) throw new MarketFetchError('io', `market fetch failed (${file}): missing response body`);
+    const reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let length = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        length += value.byteLength;
+        if (length > MAX_INDEX_BYTES) throw new MarketFetchError('io', `market file too large: ${file}`);
+        chunks.push(value);
+      }
+    } catch (error) {
+      if (error instanceof MarketFetchError) throw error;
+      throw new MarketFetchError('io', `market fetch failed (${file}): network error`);
+    } finally {
+      void reader.cancel().catch(() => {});
+      reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+    return bytes;
+  };
+  const bytes = await load('marketplace.json');
+  const signature = new TextDecoder('utf-8', { fatal: true }).decode(await load('index.sig'));
+  const verified = checked(bytes, signature, name, keys, opts, lastSequence);
+  mkdirSync(directory, { recursive: true });
+  // Cross-process: another CLI may have published a newer index since we read cache-state. Re-check the high-water
+  // mark under a file lock right before publishing, so a slower process cannot roll the cache back (review R3).
+  return withFileLockSync(join(directory, '.publish.lock'), () => {
+  const current = cacheState(stateFile);
+  if (current?.url === market.url && current.lastSequence !== undefined && current.lastSequence > verified.index.sequence) {
+    throw new MarketFetchError('signature', `market index rollback refused: ${name} sequence ${verified.index.sequence} < ${current.lastSequence}`);
+  }
+  const staging = mkdtempSync(join(directory, '.index-'));
+  try {
+    const tempIndex = join(staging, 'marketplace.json');
+    const tempSig = join(staging, 'index.sig');
+    const tempState = join(staging, 'cache-state.json');
+    writeFileSync(tempIndex, bytes);
+    writeFileSync(tempSig, signature);
+    writeFileSync(tempState, JSON.stringify({ url: market.url, lastSequence: verified.index.sequence, indexHash: digest(bytes), signatureHash: digest(signature) } satisfies CacheState));
+    // Commit the verified high-water mark before replacing either cache file.
+    // An interrupted publication then cannot roll back a previously verified index.
+    renameSync(tempState, stateFile);
+    renameSync(tempIndex, indexFile);
+    renameSync(tempSig, sigFile);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  return { market, directory, signature: 'ok', ...verified } as MarketIndex;
+  });
+}
+
+export async function updateMarket(name: string, opts: MarketFetchOptions = {}): Promise<MarketIndex> {
+  return ensureMarketIndex(name, { ...opts, refresh: true });
+}