elanous 0.2.21 → 0.2.23

package/src/shell-env-bootstrap.ts

@@ -65,6 +65,12 @@ const POSIX_SHELLS = new Set(['zsh', 'bash', 'fish', 'sh', 'dash', 'ksh']);
 let cached: Record<string, string> | null = null;
 let captured = false;
 
+// Both the daemon warm path (nexus/index.ts) and PTY's first synchronous capture
+// pass through here. Keep the existing capture events intact; these are additive timings.
+function logBootPhase(phase: string, start: number, outcome: string): void {
+  debug.log('boot.phase', phase, { ms: performance.now() - start, outcome });
+}
+
 /** Parse `KEY=VALUE\n` output from `printenv`. Tolerates values that
  *  themselves contain `=`; does not attempt to unescape newlines
  *  (bash/zsh `printenv` emits them literally, which is fine for
@@ -121,10 +127,13 @@ function acceptCapture(stdout: string): Record<string, string> | null {
 }
 
 export function runPrintenvCapture(): Record<string, string> | null {
+  const seedStart = performance.now();
   const seed = captureSeed();
+  logBootPhase('login-env.seed', seedStart, seed ? 'ready' : 'unavailable');
   if (!seed) return null;
   const { shell, seedEnv } = seed;
 
+  const shellStart = performance.now();
   let res: ReturnType<typeof spawnSync>;
   try {
     res = spawnSync(shell, ['-l', '-i', '-c', 'printenv'], {
@@ -137,13 +146,14 @@ export function runPrintenvCapture(): Record<string, string> | null {
       // OSC sequences would corrupt our TUI output otherwise.
     });
   } catch {
+    logBootPhase('login-env.shell', shellStart, 'error');
     return null;
   }
   // ETIMEDOUT with status 0 = the shell outlived the timeout; never trust a late capture.
-  if (res.error) return null;
-  if (res.status !== 0 && res.status !== null) return null;
-  if (res.signal) return null;
-  return acceptCapture(typeof res.stdout === 'string' ? res.stdout : '');
+  const parsed = !res.error && (res.status === 0 || res.status === null) && !res.signal
+    ? acceptCapture(typeof res.stdout === 'string' ? res.stdout : '') : null;
+  logBootPhase('login-env.shell', shellStart, parsed ? 'ok' : 'failed');
+  return parsed;
 }
 
 /** Fill the login-env cache off the event loop (daemon boot). The first web-terminal spawn otherwise ran the
@@ -152,9 +162,12 @@ export function runPrintenvCapture(): Record<string, string> | null {
 export async function warmCapturedEnv(spawn: typeof Bun.spawn = Bun.spawn): Promise<boolean> {
   if (captured) return cached !== null;
   if (process.env.ELANOUS_SKIP_LOGIN_ENV === '1' || process.env.TERM_PROGRAM === 'monad-agent-nested') return false;
+  const seedStart = performance.now();
   const seed = captureSeed();
+  logBootPhase('login-env.seed', seedStart, seed ? 'ready' : 'unavailable');
   if (!seed) return false;
   const start = Date.now();
+  const shellStart = performance.now();
   try {
     const proc = spawn([seed.shell, '-l', '-i', '-c', 'printenv'], { env: seed.seedEnv as Record<string, string>, stdin: 'ignore', stdout: 'pipe', stderr: 'ignore' });
     // A grandchild (e.g. a pyenv rehash) can keep the stdout pipe open after the shell is killed,
@@ -167,6 +180,7 @@ export async function warmCapturedEnv(spawn: typeof Bun.spawn = Bun.spawn): Prom
     const result = await Promise.race([finished, timedOut]);
     clearTimeout(timer);
     const parsed = result && result[1] === 0 ? acceptCapture(result[0]) : null;
+    logBootPhase('login-env.shell', shellStart, parsed ? 'ok' : result ? 'failed' : 'timeout');
     if (captured) return cached !== null; // a synchronous capture won the race
     if (!parsed) return false;
     cached = parsed;
@@ -174,6 +188,7 @@ export async function warmCapturedEnv(spawn: typeof Bun.spawn = Bun.spawn): Prom
     debug.log('shell.envbootstrap.capture', 'warmed', { ok: true, ms: Date.now() - start, keyCount: Object.keys(parsed).length });
     return true;
   } catch {
+    logBootPhase('login-env.shell', shellStart, 'error');
     return false;
   }
 }

package/src/skills/gift-install.ts

@@ -3,7 +3,13 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, existsSync, lstatSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
 import { debug } from '../debug/log.js';
+import { ensureInternalMarketIndex, ensureMarketIndex, type MarketFetchOptions } from '../plugins/install/market-fetch.js';
+import { scanPackInternalRefs } from '../market/pack-internal-refs.js';
+import { createPack } from '../knowledge/kgs/pack.js';
+import { KgsSqliteStore } from '../knowledge/kgs/sqlite-store.js';
+import type { KnowledgeCard, KnowledgeKind } from '../knowledge/kgs/types.js';
 
 export interface GiftInstallOptions {
   pack: string;
@@ -23,6 +29,119 @@ export type GiftInstallResult =
   | { ok: true; names: string[]; paths: string[]; collisions: string[]; needsKeys: boolean; message: string }
   | { ok: false; reason: string; message: string };
 
+export type KnowledgePackInstallResult =
+  | { ok: true; packId: string; citations: string[] }
+  | { ok: false; reason: string };
+
+/** Install a named knowledge pack from a configured, signed market; no gift code or skill target is involved. */
+export async function installMarketKnowledgePack(input: {
+  pack: string;
+  market: string;
+  enterpriseId?: string;
+  marketOptions?: MarketFetchOptions;
+  fetch?: typeof fetch;
+  store?: Pick<KgsSqliteStore, 'writePack'>;
+}): Promise<KnowledgePackInstallResult> {
+  try {
+    const verified = input.enterpriseId
+      ? await ensureInternalMarketIndex(input.market, input.enterpriseId, input.marketOptions)
+      : await ensureMarketIndex(input.market, input.marketOptions);
+    const entry = verified.index.knowledgePacks?.find(item => item.name === input.pack);
+    if (!entry || (input.enterpriseId ? entry.visibility !== 'internal' || entry.enterpriseId !== input.enterpriseId : entry.visibility !== 'public')) {
+      return { ok: false, reason: 'pack-not-in-verified-market' };
+    }
+    const key = entry.artifact.key;
+    if (!key || key.startsWith('/') || key.includes('\\') || key.split('/').some(part => !part || part === '.' || part === '..')) {
+      return { ok: false, reason: 'invalid-artifact-key' };
+    }
+    const base = new URL(verified.market.url);
+    const artifactUrl = new URL(key, base);
+    if (key.includes('%') || key.includes('?') || key.includes('#') || base.protocol !== 'https:') return { ok: false, reason: 'invalid-artifact-key' };
+    if (artifactUrl.origin !== base.origin || !artifactUrl.pathname.startsWith(base.pathname) || artifactUrl.search || artifactUrl.hash) {
+      return { ok: false, reason: 'invalid-artifact-key' };
+    }
+    if (entry.artifact.bytes > MAX_DOWNLOAD_BYTES) return { ok: false, reason: 'artifact-mismatch' };
+    const response = await (input.fetch ?? fetch)(artifactUrl.href, { redirect: 'error' });
+    if (!response.ok || response.redirected || (response.url && response.url !== artifactUrl.href)) return { ok: false, reason: 'artifact-download-failed' };
+    const reader = response.body?.getReader();
+    if (!reader) return { ok: false, reason: 'artifact-download-failed' };
+    const chunks: Uint8Array[] = [];
+    let length = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > MAX_DOWNLOAD_BYTES || length > entry.artifact.bytes) { await reader.cancel(); return { ok: false, reason: 'artifact-mismatch' }; }
+      chunks.push(value);
+    }
+    const bytes = Buffer.concat(chunks);
+    if (bytes.length !== entry.artifact.bytes ||
+      createHash('sha256').update(bytes).digest('hex').toLowerCase() !== entry.artifact.sha256.toLowerCase()) {
+      return { ok: false, reason: 'artifact-mismatch' };
+    }
+    const archive = gunzipSync(bytes, { maxOutputLength: MAX_UNPACKED_BYTES });
+    const files = new Map<string, string>();
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    let endOffset = 0;
+    for (let offset = 0; offset + 512 <= archive.length;) {
+      const header = archive.subarray(offset, offset + 512);
+      if (header.every(byte => byte === 0)) { endOffset = offset; break; }
+      const field = (start: number, end: number) => header.subarray(start, end).toString('utf8').replace(/\0.*$/, '');
+      const checksum = parseInt(field(148, 156).trim(), 8);
+      const actualChecksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+      if (checksum !== actualChecksum) return { ok: false, reason: 'invalid-archive' };
+      const size = parseInt(field(124, 136).trim(), 8);
+      const name = field(0, 100);
+      const prefix = field(345, 500);
+      const path = prefix ? `${prefix}/${name}` : name;
+      if (!Number.isSafeInteger(size) || size < 0 || !path || path.includes('\\') ||
+        path.split('/').some(part => !part || part === '.' || part === '..') || header[156] !== 48 ||
+        offset + 512 + size > archive.length || files.has(path)) return { ok: false, reason: 'invalid-archive' };
+      files.set(path, decoder.decode(archive.subarray(offset + 512, offset + 512 + size)));
+      offset += 512 + Math.ceil(size / 512) * 512;
+      if (files.size > MAX_ENTRIES) return { ok: false, reason: 'invalid-archive' };
+    }
+    if (!endOffset || archive.length - endOffset < 1024 || !archive.subarray(endOffset).every(byte => byte === 0)) return { ok: false, reason: 'invalid-archive' };
+    const manifest = JSON.parse(files.get('knowledge-pack.json') ?? 'null') as Record<string, unknown> | null;
+    if (files.size !== (Array.isArray(manifest?.content) ? manifest.content.length + 1 : -1)) return { ok: false, reason: 'invalid-content' };
+    if (!manifest || manifest.kind !== 'knowledge-pack' || manifest.name !== entry.name || manifest.version !== entry.version ||
+      !/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(entry.name) || !/^\d+\.\d+\.\d+$/.test(entry.version) ||
+      typeof manifest.description !== 'string' || !manifest.description || manifest.description.length > 200 ||
+      !Array.isArray(manifest.content) || !manifest.content.length ||
+      !Array.isArray(manifest.dependencies) || manifest.dependencies.length !== 0 ||
+      manifest.visibility !== entry.visibility || typeof manifest.license !== 'string' || !manifest.license ||
+      !manifest.signature || typeof manifest.signature !== 'object' ||
+      (manifest.signature as Record<string, unknown>).algorithm !== 'ed25519' ||
+      (manifest.signature as Record<string, unknown>).keyId !== verified.keyId) return { ok: false, reason: 'invalid-manifest' };
+    const now = new Date().toISOString();
+    const cards: KnowledgeCard[] = [];
+    for (const item of manifest.content) {
+      if (!item || typeof item !== 'object') return { ok: false, reason: 'invalid-content' };
+      const { path, kind } = item as Record<string, unknown>;
+      if (typeof path !== 'string' || !/^content\/[a-z0-9-]+(?:\/[a-z0-9-]+)*\.md$/.test(path) || typeof kind !== 'string' ||
+        !['document', 'glossary', 'procedure', 'rule', 'qa'].includes(kind) || !files.has(path)) return { ok: false, reason: 'invalid-content' };
+      const body = files.get(path)!;
+      cards.push({ schema_version: 2, id: path, createdAt: now, updatedAt: now, author: entry.name,
+        title: body.match(/^# (.+)$/m)?.[1] ?? path, body, nature: 'fact',
+        kind: ({ procedure: 'playbook', glossary: 'wiki', qa: 'card', rule: 'checklist', document: 'note' } as Record<string, KnowledgeKind>)[kind]!,
+        reliability: 'self-reported', source: { kind: 'external', url: artifactUrl.href }, tags: [entry.name] });
+    }
+    if (cards.length > 200 || new Set(cards.map(card => card.id)).size !== cards.length ||
+      scanPackInternalRefs([...files].map(([path, text]) => ({ path, text }))).length) return { ok: false, reason: 'invalid-content' };
+    const pack = createPack({ id: { slug: entry.name, version: entry.version }, title: manifest.description as string,
+      intent: manifest.description as string, audience: input.enterpriseId ? 'team' : 'public', kind: 'generic',
+      author: entry.name, cards });
+    if (input.store) input.store.writePack(pack);
+    else {
+      const store = new KgsSqliteStore();
+      try { store.writePack(pack); } finally { store.close(); }
+    }
+    return { ok: true, packId: `pack:${entry.name}@${entry.version}`, citations: cards.map(card => `pack:${entry.name}@${entry.version}#${card.id}`) };
+  } catch {
+    return { ok: false, reason: 'knowledge-pack-install-failed' };
+  }
+}
+
 // GK1 public bundle: packs/elanous-essentials/plugin.json extensions.ai.elanous.bundle.
 const ESSENTIAL_SKILLS = ['youtube-master', 'omni-crawl', 'omni-digest', 'diagram-master', 'lecture-note-digitizer'];
 // A malicious or broken gift must not exhaust the temp disk: cap the download, the unpacked total and the entry count.

package/src/skills/runner.ts

@@ -3,6 +3,9 @@
 // substitute template variables, and run them through the selected LLM provider.
 
 import { debug } from '../debug/log.js';
+import type { SkillTier } from './skill-tier.js';
+import { randomUUID } from 'node:crypto';
+import { recordSkillRunSafe, type SkillRun } from './skill-feedback.js';
 import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { LOCAL_SKILLS_DIR } from '../config.js';
@@ -307,7 +310,7 @@ export interface SkillManifest {
 }
 
 /** Ordered weak→strong. Session 21. */
-export type SkillTier = 'T3' | 'T2' | 'T1';
+export type { SkillTier } from './skill-tier.js';
 const TIER_RANK: Record<SkillTier, number> = { T3: 1, T2: 2, T1: 3 };
 
 /** True when `active` is at least as strong as `min`. Missing `min`
@@ -690,6 +693,9 @@ export interface ExecuteSkillOpts {
    *  pure-builder input so tests and future callers can reason about
    *  the final message shape without opening the SQLite store. */
   promptBankContext?: string;
+  /** Use this provider instead of resolving one from config/model hint
+   *  (tests and hosts that already hold a provider). */
+  provider?: LLMProvider;
 }
 
 export interface ExecuteSkillResult {
@@ -968,6 +974,57 @@ export async function executeSkill(
   args: string,
   onChunk: (delta: string, full: string) => void,
   opts: ExecuteSkillOpts = {},
+): Promise<ExecuteSkillResult> {
+  // SK1: one feedback ledger line per run. Recording is fail-soft — the
+  // result returned and the exception thrown are exactly the run's own.
+  let started: number | undefined;
+  try { started = Date.now(); } catch { /* clock trouble must not block the skill */ }
+  const feedback = (outcome: SkillRun['outcome'], failureKind?: string): SkillRun => ({
+    skill: manifest.name,
+    runId: randomUUID(),
+    outcome,
+    ...(failureKind ? { failureKind } : {}),
+    userCorrected: false,
+    retries: 0,
+    durationMs: started === undefined ? 0 : Math.max(0, Date.now() - started),
+    at: new Date().toISOString(),
+  });
+  const record = (outcome: SkillRun['outcome'], failureKind?: string): void => {
+    try {
+      recordSkillRunSafe(feedback(outcome, failureKind));
+    } catch (error) {
+      // Building the record itself failed — still fail-soft, still observed.
+      try {
+        debug.log('skill.feedback', 'record-failed', { skill: manifest.name, error: String(error) }, { level: 'warn' });
+      } catch { /* never let observation change the skill outcome */ }
+    }
+  };
+  let result: ExecuteSkillResult;
+  try {
+    result = await executeSkillUnrecorded(manifest, args, onChunk, opts);
+  } catch (error) {
+    record('failure', skillFailureKind(error));
+    throw error;
+  }
+  record('success');
+  return result;
+}
+
+/** Failure kind for the feedback ledger: the exception's name, else 'error'. */
+function skillFailureKind(error: unknown): string {
+  try {
+    const name = (error as { name?: unknown } | null)?.name;
+    return typeof name === 'string' && name !== '' ? name : 'error';
+  } catch {
+    return 'error';
+  }
+}
+
+async function executeSkillUnrecorded(
+  manifest: SkillManifest,
+  args: string,
+  onChunk: (delta: string, full: string) => void,
+  opts: ExecuteSkillOpts,
 ): Promise<ExecuteSkillResult> {
   debug.log('skill.router', 'executeSkill', {
     skill: manifest.name,
@@ -982,7 +1039,7 @@ export async function executeSkill(
   // vars. Previously getProvider(modelHint) — env-only — meant a user
   // with config.provider=openai-codex but XAI_API_KEY still in env
   // would see every skill fall back to Grok.
-  const provider: LLMProvider = resolveDefaultProvider(rawModelHint);
+  const provider: LLMProvider = opts.provider ?? resolveDefaultProvider(rawModelHint);
   // If the skill's declared model belongs to a DIFFERENT provider
   // family than the one user-config resolved to, drop it. Example:
   // user has openai-codex configured but a skill's SKILL.md says

package/src/skills/skill-feedback.ts

@@ -1,5 +1,7 @@
-import { appendFileSync, readFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
 
 export interface SkillRun {
   skill: string;
@@ -25,6 +27,34 @@ export function appendSkillRun(ledgerPath: string, run: SkillRun): void {
   appendFileSync(ledgerPath, `${JSON.stringify(run)}\n`, 'utf8');
 }
 
+/**
+ * Ledger for skill runs: `<root>/skills/feedback.jsonl`, root defaulting to the
+ * effective instance (state) root — never a skill folder. Creates the directory.
+ */
+export function skillFeedbackLedgerPath(root: string = effectiveInstanceRoot()): string {
+  const dir = join(root, 'skills');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, 'feedback.jsonl');
+}
+
+/**
+ * Fail-soft record of one skill run: resolving or writing the ledger never
+ * throws to the caller; a failure leaves a single `record-failed` observation.
+ */
+export function recordSkillRunSafe(run: SkillRun, ledgerPath?: string): void {
+  try {
+    appendSkillRun(ledgerPath ?? skillFeedbackLedgerPath(), run);
+  } catch (error) {
+    try {
+      debug.log('skill.feedback', 'record-failed', { skill: run.skill, error: String(error) }, { level: 'warn' });
+    } catch { /* observation must not break the skill result either */ }
+    return;
+  }
+  try {
+    debug.log('skill.feedback', 'recorded', { skill: run.skill, outcome: run.outcome, durationMs: run.durationMs });
+  } catch { /* fail-soft */ }
+}
+
 /** Read the JSONL ledger in append order; an absent ledger has no runs. */
 export function readSkillRuns(ledgerPath: string): SkillRun[] {
   let text: string;

package/src/skills/skill-tier.ts

@@ -0,0 +1 @@
+export type SkillTier = 'T3' | 'T2' | 'T1';

package/src/smart-wizard/capability-index.ts

@@ -0,0 +1,231 @@
+import { Database } from 'bun:sqlite';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { buildCapabilityMatrix } from '../agent-mission/capability-matrix.js';
+import { createCapabilityReaders } from '../agent-mission/capability-readers.js';
+import type { CapabilityEntry } from '../agent-mission/capability-types.js';
+import { readCodexPluginsFromAppServer, type CodexPluginObservation } from '../acp/codex-plugins.js';
+import { kgsDefaultDbPath } from '../knowledge/kgs/sqlite-store.js';
+import { OFFICIAL_INDEX_KEYS } from '../market/official-keys.js';
+import { verifyIndex, type MarketplaceIndex } from '../market/signed-index.js';
+import { readClaudePackageLedger, type ClaudePackageLedger } from '../plugins/adapters/claude-package.js';
+import { ELANOUS_MARKET_URL } from '../plugins/install/market-fetch.js';
+import { buildSkillIndex, skillIndexProblems, type SkillIndexEntry } from '../skills/index.js';
+import { defaultSkillDirs } from '../user-config.js';
+
+export type CapabilitySource = 'skills' | 'plugins' | 'knowledge' | 'codex' | 'claude' | 'market';
+export type CapabilityAuth = 'subscription' | 'free' | 'api-key' | 'paid' | 'unknown';
+export interface IndexedCapability {
+  readonly id: string;
+  readonly kind: 'skill' | 'plugin' | 'knowledge' | 'connector';
+  readonly source: CapabilitySource;
+  readonly provenance: string;
+  readonly auth: CapabilityAuth;
+  readonly state: 'installed' | 'candidate' | 'ready' | 'unavailable' | 'unknown';
+  readonly capabilities: readonly string[];
+}
+export interface CapabilityIndex {
+  readonly sources: Record<CapabilitySource, 'ok' | 'unknown'>;
+  readonly entries: readonly IndexedCapability[];
+}
+
+export interface CapabilityIndexReaders {
+  skills?: () => readonly SkillIndexEntry[];
+  skillProblems?: () => readonly { name: string; dir: string }[];
+  plugins?: () => readonly { name: string; market: string }[];
+  knowledge?: () => readonly { name: string; provenance: string }[];
+  codex?: () => Promise<CodexPluginObservation>;
+  claude?: () => ClaudePackageLedger;
+  /** Production verifies fetched bytes; tests may inject a checked fixture. */
+  market?: () => Promise<MarketplaceIndex>;
+  matrix?: () => readonly CapabilityEntry[];
+  /** Default-path observations (used only when `skills` / `plugins` are not injected). */
+  localSkills?: () => LocalSkillsObservation;
+  localPlugins?: () => LocalPluginsObservation;
+  /** Already verified by the caller (never accepts unverified JSON). */
+  verifiedMarket?: MarketplaceIndex;
+}
+
+export interface LocalSkillsObservation {
+  readonly entries: readonly SkillIndexEntry[];
+  /** Roots that exist (or could not be proven absent) but could not be read. */
+  readonly unreadableRoots: readonly string[];
+}
+
+/** Per-root read: an unreadable root is reported, readable roots keep their candidates. */
+export function readLocalSkills(dirs: readonly string[] = defaultSkillDirs()): LocalSkillsObservation {
+  // A missing root is optional; any other stat/read failure must remain unknown.
+  const readable: string[] = [];
+  const unreadableRoots: string[] = [];
+  for (const dir of dirs) {
+    try {
+      if (!statSync(dir).isDirectory()) throw new Error('skill root is not a directory');
+      readdirSync(dir);
+      readable.push(dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      unreadableRoots.push(dir);
+    }
+  }
+  return { entries: readable.length ? buildSkillIndex(readable) : [], unreadableRoots };
+}
+
+/** Strict form: throws when any root is unreadable. */
+export function listLocalSkills(dirs: readonly string[] = defaultSkillDirs()): readonly SkillIndexEntry[] {
+  const observed = readLocalSkills(dirs);
+  if (observed.unreadableRoots.length) throw new Error(`unreadable skill roots: ${observed.unreadableRoots.join(', ')}`);
+  return observed.entries;
+}
+
+export interface LocalPluginsObservation {
+  readonly plugins: readonly { name: string; market: string }[];
+  /** `absent` = ENOENT (no installs recorded); `unreadable` = exists but stat/read/parse failed. */
+  readonly ledger: 'ok' | 'absent' | 'unreadable';
+  /** Plugin directories that exist (or could not be proven absent) but could not be listed. */
+  readonly unreadableDirs: readonly string[];
+}
+
+/** ENOENT → absent; every other failure is a read failure, never "no candidates". */
+function statKind(path: string, want: 'any' | 'file' = 'any'): 'present' | 'absent' | 'unreadable' {
+  try { const stat = statSync(path); return want === 'file' && !stat.isFile() ? 'absent' : 'present'; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'unreadable'; }
+}
+
+export function readLocalPlugins(
+  ledgerPath: string = join(elanousStateRoot(), 'plugins', 'installed.json'),
+  localDirs: readonly string[] = [resolve(import.meta.dir, '../../plugins')],
+): LocalPluginsObservation {
+  const plugins: { name: string; market: string }[] = [];
+  let ledger: LocalPluginsObservation['ledger'] = 'absent';
+  const ledgerKind = statKind(ledgerPath);
+  if (ledgerKind === 'unreadable') ledger = 'unreadable';
+  else if (ledgerKind === 'present') {
+    try {
+      const rows: unknown = JSON.parse(readFileSync(ledgerPath, 'utf8'));
+      if (!Array.isArray(rows) || !rows.every(row => row && typeof row.name === 'string' && typeof row.market === 'string')) throw new Error('invalid installed plugin ledger');
+      plugins.push(...rows.map(row => ({ name: row.name as string, market: row.market as string })));
+      ledger = 'ok';
+    } catch { ledger = 'unreadable'; }
+  }
+  const unreadableDirs: string[] = [];
+  for (const dir of localDirs) {
+    const kind = statKind(dir);
+    if (kind === 'absent') continue;
+    const found: { name: string; market: string }[] = [];
+    try {
+      if (kind === 'unreadable') throw new Error('plugin directory unreadable');
+      for (const item of readdirSync(dir, { withFileTypes: true })) {
+        if (!item.isDirectory()) continue;
+        const path = join(dir, item.name);
+        const manifests = [statKind(join(path, 'plugin.ts'), 'file'), statKind(join(path, 'plugin.json'), 'file')];
+        if (manifests.includes('present')) found.push({ name: item.name, market: dir });
+        else if (manifests.includes('unreadable')) unreadableDirs.push(path);
+      }
+      plugins.push(...found);
+    } catch { unreadableDirs.push(dir); }
+  }
+  return { plugins, ledger, unreadableDirs };
+}
+
+function listLocalKnowledge(): readonly { name: string; provenance: string }[] {
+  const path = kgsDefaultDbPath();
+  if (!existsSync(path)) throw new Error('knowledge store unavailable');
+  const db = new Database(path, { readonly: true, create: false });
+  try {
+    return (db.query('SELECT slug, version FROM kgs_pack ORDER BY slug, version').all() as Array<{ slug: string; version: string }>)
+      .map(row => ({ name: `${row.slug}@${row.version}`, provenance: path }));
+  } finally { db.close(); }
+}
+
+async function readOfficialMarket(): Promise<MarketplaceIndex> {
+  const url = new URL('marketplace.json', ELANOUS_MARKET_URL);
+  const [raw, sig] = await Promise.all([fetch(url), fetch(new URL('index.sig', url))]);
+  if (!raw.ok || !sig.ok) throw new Error('official index unavailable');
+  const checked = verifyIndex({ marketplaceBytes: new Uint8Array(await raw.arrayBuffer()), signatureText: await sig.text(), trustedKeys: OFFICIAL_INDEX_KEYS });
+  if (!checked.ok || checked.index.name !== 'elanous') throw new Error('official index unverified');
+  return checked.index;
+}
+
+function marketAuth(entry: MarketplaceIndex['plugins'][number]): CapabilityAuth {
+  const policy = entry.policy?.authentication?.toLowerCase();
+  if (policy === 'api-key' || policy === 'api_key') return 'api-key';
+  if (policy === 'subscription') return 'subscription';
+  if (policy === 'paid') return 'paid';
+  if (policy === 'none' || policy === 'free') return 'free';
+  return 'unknown';
+}
+
+/** Read-only, per-source index. No source failure is interpreted as an empty inventory. */
+export async function buildCapabilityIndex(readers: CapabilityIndexReaders = {}): Promise<CapabilityIndex> {
+  const sources: CapabilityIndex['sources'] = { skills: 'ok', plugins: 'ok', knowledge: 'ok', codex: 'ok', claude: 'ok', market: 'ok' };
+  const entries: IndexedCapability[] = [];
+  const attempt = async (source: CapabilitySource, read: () => Promise<void> | void): Promise<void> => {
+    const start = entries.length;
+    try { await read(); } catch { sources[source] = 'unknown'; entries.splice(start); }
+  };
+  await attempt('skills', () => {
+    const observed: LocalSkillsObservation = readers.skills
+      ? { entries: readers.skills(), unreadableRoots: [] }
+      : (readers.localSkills ?? readLocalSkills)();
+    for (const skill of observed.entries) entries.push({ id: skill.name, kind: 'skill', source: 'skills', provenance: skill.rootDir, auth: 'unknown', state: 'installed', capabilities: [skill.name] });
+    if (observed.unreadableRoots.length) {
+      sources.skills = 'unknown';
+      for (const dir of observed.unreadableRoots) entries.push({ id: dir, kind: 'skill', source: 'skills', provenance: dir, auth: 'unknown', state: 'unknown', capabilities: [] });
+    }
+    const problems = (readers.skillProblems ?? skillIndexProblems)();
+    if (problems.length) {
+      sources.skills = 'unknown';
+      for (const problem of problems) entries.push({ id: problem.name, kind: 'skill', source: 'skills', provenance: problem.dir, auth: 'unknown', state: 'unknown', capabilities: [problem.name] });
+    }
+  });
+  let installed: readonly { name: string; market: string }[] | undefined;
+  await attempt('plugins', () => {
+    if (readers.plugins) installed = readers.plugins();
+    else {
+      const observed = (readers.localPlugins ?? readLocalPlugins)();
+      installed = observed.plugins;
+      // Absent ledger keeps the earlier contract (unknown); unreadable ledger/dirs never read as "no installs".
+      if (observed.ledger !== 'ok' || observed.unreadableDirs.length) sources.plugins = 'unknown';
+      for (const dir of observed.unreadableDirs) entries.push({ id: dir, kind: 'plugin', source: 'plugins', provenance: dir, auth: 'unknown', state: 'unknown', capabilities: [] });
+    }
+    for (const plugin of installed) entries.push({ id: plugin.name, kind: 'plugin', source: 'plugins', provenance: plugin.market, auth: 'unknown', state: 'installed', capabilities: [plugin.name] });
+  });
+  await attempt('knowledge', () => {
+    for (const pack of (readers.knowledge ?? listLocalKnowledge)()) entries.push({ id: pack.name, kind: 'knowledge', source: 'knowledge', provenance: pack.provenance, auth: 'unknown', state: 'installed', capabilities: [pack.name] });
+  });
+  await attempt('codex', async () => {
+    const observation = await (readers.codex ?? readCodexPluginsFromAppServer)();
+    if (observation.status === 'unknown') { sources.codex = 'unknown'; return; }
+    for (const plugin of observation.plugins) entries.push({ id: plugin.name, kind: 'plugin', source: 'codex', provenance: plugin.marketplace, auth: 'unknown', state: plugin.enabled ? 'installed' : 'unavailable', capabilities: [plugin.name] });
+  });
+  await attempt('claude', () => {
+    const ledger = (readers.claude ?? readClaudePackageLedger)();
+    if (ledger.status !== 'ok') sources.claude = 'unknown';
+    for (const pkg of ledger.packages) entries.push({ id: pkg.plugin, kind: 'plugin', source: 'claude', provenance: `${pkg.marketplace}:${pkg.source}`, auth: 'unknown', state: 'installed', capabilities: [pkg.plugin] });
+  });
+  await attempt('market', async () => {
+    const index = readers.verifiedMarket ?? await (readers.market ?? readOfficialMarket)();
+    if (index.name !== 'elanous') throw new Error('not official market');
+    for (const plugin of index.plugins) {
+      entries.push({ id: plugin.name, kind: 'plugin', source: 'market', provenance: `${index.name}:${plugin.source.source}`, auth: marketAuth(plugin),
+        state: sources.plugins === 'unknown' ? 'unknown' : installed?.some(row => row.name === plugin.name && row.market === index.name) ? 'installed' : 'candidate',
+        capabilities: [plugin.name, ...plugin['ai.elanous'].capabilities, ...(plugin['ai.elanous'].vocab ?? [])] });
+      for (const connector of plugin['ai.elanous'].connectors) entries.push({ id: connector.id, kind: 'connector', source: 'market', provenance: `${index.name}:${plugin.name}`, auth: marketAuth(plugin), state: sources.plugins === 'unknown' ? 'unknown' : 'candidate', capabilities: [connector.id] });
+    }
+    for (const pack of index.knowledgePacks ?? []) {
+      if (pack.visibility !== 'public') continue;
+      entries.push({ id: pack.name, kind: 'knowledge', source: 'market', provenance: index.name, auth: 'unknown', state: 'candidate', capabilities: [pack.name] });
+    }
+  });
+  // Matrix is an additional service observation, not proof of plugin installation.
+  let matrix: readonly CapabilityEntry[] = [];
+  try { matrix = (readers.matrix ?? (() => buildCapabilityMatrix(createCapabilityReaders())))(); }
+  catch { /* Matrix is supplementary; plugin inventories keep their own observation status. */ }
+  for (const service of matrix) {
+    // Only backends that are index sources are attributed; grok has no source row here, so it is not relabelled.
+    if (!service.service || service.service === '*' || (service.backend !== 'codex' && service.backend !== 'claude')) continue;
+    entries.push({ id: service.service, kind: 'connector', source: service.backend, provenance: `${service.backend}:mcp`, auth: 'unknown', state: service.state, capabilities: [service.service] });
+  }
+  return { sources, entries };
+}

package/src/smart-wizard/rung.ts

@@ -0,0 +1,74 @@
+// The condition extraction (including any LLM judgment) happens before this deterministic selector.
+export type WizardRung = 'a' | 'b' | 'c' | 'd' | 'e';
+export type GraphValueSignal = 'verification' | 'rework' | 'approval' | 'branching' | 'resume' | 'parallel' | 'resolution';
+
+export type RungConditions = {
+  capabilityGaps: number;
+  graphSignals: readonly GraphValueSignal[];
+  recurring: boolean;
+  needsMemory: boolean;
+  unattended: boolean;
+  roles: number;
+  differentCadences: boolean;
+  differentPermissions: boolean;
+  handoffs: number;
+};
+
+export type RungDecision = {
+  rung: WizardRung;
+  reasons: string[];
+  rejectedHigher: string[];
+};
+
+const graphSignalNames: readonly GraphValueSignal[] = [
+  'verification', 'rework', 'approval', 'branching', 'resume', 'parallel', 'resolution',
+];
+const rungOrder: readonly WizardRung[] = ['a', 'b', 'c', 'd', 'e'];
+
+/** Select the lowest rung sufficient for the supplied, already-established conditions. */
+export function classifyRung(conditions: RungConditions): RungDecision {
+  const { capabilityGaps, graphSignals, recurring, needsMemory, unattended, roles,
+    differentCadences, differentPermissions, handoffs } = conditions;
+  for (const [name, value] of Object.entries({ capabilityGaps, roles, handoffs })) {
+    if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+  if (graphSignals.some(signal => !graphSignalNames.includes(signal))) {
+    throw new TypeError('graphSignals contains an unknown signal');
+  }
+
+  const distinctSignals = graphSignalNames.filter(signal => graphSignals.includes(signal));
+  const graphWorthwhile = distinctSignals.length >= 2;
+  const loopNeeded = recurring && (needsMemory || unattended);
+  const collectiveNeeded = roles >= 2 && (differentCadences || differentPermissions) && handoffs >= 1;
+  let rung: WizardRung = 'a';
+  const reasons: string[] = [];
+  if (capabilityGaps > 0) {
+    rung = 'b';
+    reasons.push(`b: capability gaps ${capabilityGaps} > 0`);
+  }
+  if (graphWorthwhile) {
+    rung = 'c';
+    reasons.push(`c: ${distinctSignals.length} graph value signals >= 2 (${distinctSignals.join(', ')})`);
+  }
+  if (loopNeeded) {
+    rung = 'd';
+    reasons.push(`d: recurring and ${[needsMemory && 'needs memory', unattended && 'unattended'].filter(Boolean).join(' / ')}`);
+  }
+  if (collectiveNeeded) {
+    rung = 'e';
+    reasons.push(`e: ${roles} roles >= 2, ${[differentCadences && 'different cadences', differentPermissions && 'different permissions'].filter(Boolean).join(' / ')}, handoffs ${handoffs} >= 1`);
+  }
+  if (reasons.length === 0) reasons.push('a: no higher-rung condition met; one skill call or short chain suffices');
+
+  const rejected = {
+    b: `b: capability gaps ${capabilityGaps} = 0`,
+    c: `c: ${distinctSignals.length} distinct graph value signals < 2`,
+    d: `d: ${!recurring ? 'not recurring' : 'neither memory nor unattended execution'}`,
+    e: `e: ${[
+      roles < 2 && `roles ${roles} < 2`,
+      !differentCadences && !differentPermissions && 'neither different cadences nor different permissions',
+      handoffs < 1 && `handoffs ${handoffs} < 1`,
+    ].filter(Boolean).join('; ')}`,
+  };
+  return { rung, reasons, rejectedHigher: rungOrder.slice(rungOrder.indexOf(rung) + 1).map(higher => rejected[higher as keyof typeof rejected]) };
+}