elanous 0.2.4 → 0.2.5

package/src/nexus/api/mcp-oauth-hint.ts

@@ -3,15 +3,16 @@
 // 사람은 무엇을 해야 할지 몰랐다(🅢 09-28 · 대표 승인 수리). Elanous 는 OAuth 를 쓰지 않는다 — 고정 Bearer 토큰이다.
 // ⇒ 두 자리에서 «할 일»을 말한다: ① 401 의 `WWW-Authenticate` ② `/register` 의 RFC 7591 오류 본문(Claude Code 가 그대로 보여 준다).
 
-/** 토큰 «값»은 절대 싣지 않는다 — 파일 경로와 명령만. */
-export const MCP_AUTH_HINT =
-  'Elanous 는 OAuth 를 쓰지 않는다(고정 Bearer 토큰). 권장: stdio 로 등록 — `claude mcp add elanous -- elanous mcp serve`. '
-  + 'HTTP 가 필요하면 ~/.elanous/acp-token 의 값을 Authorization 헤더로: '
-  + '`claude mcp add --transport http elanous http://127.0.0.1:31415/v1/mcp --header "Authorization: Bearer <acp-token>"`';
+/** 토큰 «값»은 절대 싣지 않는다 — 파일 경로와 명령만. 주소는 포트를 짐작하지 않고 «요청이 닿은 origin»을 쓴다(대표 09-28 통합관제). */
+export function mcpAuthHint(origin: string): string {
+  return 'Elanous 는 OAuth 를 쓰지 않는다(고정 Bearer 토큰). 권장: stdio 로 등록 — `claude mcp add elanous -- elanous mcp serve`. '
+    + 'HTTP 가 필요하면 ~/.elanous/acp-token 의 값을 Authorization 헤더로: '
+    + `\`claude mcp add --transport http elanous ${origin}/v1/mcp --header "Authorization: Bearer <acp-token>"\``;
+}
 
 /** `/v1/mcp` 401 — 무엇을 해야 하는지 헤더로도 말한다(WWW-Authenticate 의 error_description 은 ASCII 만). */
-export function mcpUnauthorizedResponse(): Response {
-  return new Response(JSON.stringify({ error: 'unauthorized', hint: MCP_AUTH_HINT }), {
+export function mcpUnauthorizedResponse(origin: string): Response {
+  return new Response(JSON.stringify({ error: 'unauthorized', hint: mcpAuthHint(origin) }), {
     status: 401,
     headers: {
       'content-type': 'application/json; charset=utf-8',
@@ -22,8 +23,8 @@ export function mcpUnauthorizedResponse(): Response {
 }
 
 /** OAuth 동적 클라이언트 등록 거절 — RFC 7591 §3.2.2 오류 형식(Claude Code 가 본문을 사람에게 보여 준다). */
-export function oauthRegistrationRejected(): Response {
-  return new Response(JSON.stringify({ error: 'invalid_client_metadata', error_description: MCP_AUTH_HINT }), {
+export function oauthRegistrationRejected(origin: string): Response {
+  return new Response(JSON.stringify({ error: 'invalid_client_metadata', error_description: mcpAuthHint(origin) }), {
     status: 400,
     headers: { 'content-type': 'application/json; charset=utf-8', 'access-control-allow-origin': '*' },
   });

package/src/nexus/api/merge-approvals.ts

@@ -98,13 +98,14 @@ function asItem(pr: RawPr) {
 }
 
 // A page load fires the list twice (the daemon client settles) and polls cards — identical reads share one gh call.
+// Failures are shared too: during a GitHub rate-limit window a retry per request only deepens the limit (GIT-S83).
 const readCache = new Map<string, { at: number; value: Promise<GhResult> }>();
 export function clearApprovalsReadCache(): void { readCache.clear(); }
 function cachedRead(args: string[], ttlMs: number, now: number, call: () => Promise<GhResult>): Promise<GhResult> {
   const key = args.join('\u0000');
   const hit = readCache.get(key);
   if (hit && now - hit.at < ttlMs) return hit.value;
-  const value = call().then((result) => { if (!result.ok) readCache.delete(key); return result; });
+  const value = call();
   readCache.set(key, { at: now, value });
   return value;
 }

package/src/nexus/api/meta-api.ts

@@ -254,6 +254,10 @@ function decideAuth(req: Request, opts: MetaApiOpts): { ok: boolean; reason: Aut
   if (isSameOriginRequest(req, peerAddress)) return { ok: true, reason: 'same-origin' };
   const peerRejected = req.headers.get('sec-fetch-site') === 'same-origin'
     && !isTrustedSameOriginPeer(peerAddress);
+  return decideBearer(req, opts, peerRejected);
+}
+
+function decideBearer(req: Request, opts: MetaApiOpts, peerRejected = false): { ok: boolean; reason: AuthReason } {
   const token = opts.bearerToken;
   if (!token) return { ok: false, reason: peerRejected ? 'untrusted-same-origin-peer' : 'no-bearer-configured' };
   const auth = req.headers.get('authorization') ?? '';
@@ -273,6 +277,16 @@ function decideAuth(req: Request, opts: MetaApiOpts): { ok: boolean; reason: Aut
     : { ok: false, reason: 'bearer-mismatch' };
 }
 
+/** Bearer-only credential check that ignores the same-origin shortcut. `checkAuth` returns
+ * `same-origin` before it ever looks at the Authorization header, so a paired PWA that sends its
+ * token is still reported as same-origin — write paths that must not trust same-origin alone
+ * (graph approvals) ask this instead. Returns the credential kind, or undefined if none matched. */
+export function bearerCredential(req: Request, opts: MetaApiOpts): 'noauth' | 'bearer-match' | 'temp-token' | undefined {
+  if (opts.noAuth) return 'noauth';
+  const decision = decideBearer(req, opts);
+  return decision.ok && (decision.reason === 'bearer-match' || decision.reason === 'temp-token') ? decision.reason : undefined;
+}
+
 // Exported so sibling NEXUS API modules (e.g. T5.G `tasks-scheduler.ts`)
 // can reuse the exact same gate — same-origin + constant-time bearer
 // check — without duplicating security-sensitive code.

package/src/nexus/api/plugins-credentials-api.ts

@@ -0,0 +1,47 @@
+import { debug } from '../../debug/log.js';
+import { credentialStatus, setPluginCredentials } from '../../plugins/install/plugin-credentials.js';
+import { checkAuth, type MetaApiOpts } from './meta-api.js';
+import { jsonResponse } from './json-response.js';
+
+const NAME = /^[a-z0-9][a-z0-9-]{1,39}$/;
+
+function failure(error: unknown): Response {
+  if (error instanceof Error && error.message.startsWith('plugin not installed:')) return jsonResponse({ error: 'not_found' }, 404);
+  if (error instanceof Error && (error.message === 'invalid plugin name' || error.message === 'invalid plugin credential field'
+    || error.message === 'invalid plugin credential fields')) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  return jsonResponse({ error: 'credential_error' }, 500);
+}
+
+export function handlePluginsCredentialsGet(req: Request, name: string, opts: MetaApiOpts, root?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  try { return jsonResponse(credentialStatus(name, root), 200); }
+  catch (error) { return failure(error); }
+}
+
+/** `reload` re-spawns the daemon's MCP clients so a running plugin server picks up the new values
+ *  (the spawn reads `pluginEnv` fresh). A failed reload never fails the write — the reply says so. */
+export async function handlePluginsCredentialsPut(req: Request, name: string, opts: MetaApiOpts, root?: string, reload?: () => Promise<unknown>): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const fields = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>).fields : undefined;
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields)
+    || Object.values(fields).some(value => typeof value !== 'string' && value !== null)) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  try {
+    const result = setPluginCredentials(name, fields as Record<string, string | null>, root);
+    debug.log('plugin.credentials', 'set', { plugin: name, fields: Object.keys(fields), count: Object.keys(fields).length });
+    let reloaded = false;
+    if (reload) {
+      try { await reload(); reloaded = true; }
+      catch { debug.log('plugin.credentials', 'reload-failed', { plugin: name }, { level: 'warn' }); }
+    }
+    return jsonResponse({ ...result, reloaded }, 200);
+  } catch (error) { return failure(error); }
+}

package/src/nexus/api/plugins-market.ts

@@ -4,7 +4,8 @@ import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { debug } from '../../debug/log.js';
 import { OFFICIAL_INDEX_KEYS } from '../../market/official-keys.js';
 import { verifyIndex, type MarketplaceIndex } from '../../market/signed-index.js';
-import { listInstalledPlugins } from '../../plugins/install/plugin-install.js';
+import { installPlugin, listInstalledPlugins, removePlugin, type InstallEvent } from '../../plugins/install/plugin-install.js';
+import { updateMarket, type MarketFetchOptions } from '../../plugins/install/market-fetch.js';
 import { userConfigPath } from '../../user-config.js';
 import { jsonResponse } from './json-response.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
@@ -66,7 +67,7 @@ export function readMarketIndex(root = elanousStateRoot(), trustedKeys: Readonly
     const dir = join(base, entry.name);
     const indexPath = [join(dir, 'marketplace.json'), join(dir, '.agents', 'plugins', 'marketplace.json')].find(existsSync);
     if (!indexPath) {
-      markets.push({ name: entry.name, signature: 'malformed', detail: 'marketplace.json: not found', plugins: [] });
+      markets.push({ name: entry.name, signature: 'malformed', detail: '마켓 인덱스를 찾지 못했습니다.', plugins: [] });
       continue;
     }
     let signature: MarketSignature = 'missing';
@@ -93,7 +94,7 @@ export function readMarketIndex(root = elanousStateRoot(), trustedKeys: Readonly
       signature = 'malformed';
       detail = 'marketplace.json: invalid market index';
     }
-    markets.push({ name: entry.name, signature, ...(detail ? { detail } : {}), plugins });
+    markets.push({ name: entry.name, signature, ...(detail ? { detail: '마켓 인덱스를 확인하지 못했습니다.' } : {}), plugins });
   }
   markets.sort((a, b) => a.name.localeCompare(b.name));
   debug.log('nexus.plugins-market', 'index', { markets: markets.length, ok: markets.filter(m => m.signature === 'ok').length, notOk: markets.filter(m => m.signature !== 'ok').length });
@@ -123,3 +124,86 @@ export function handlePluginsGet(req: Request, opts: MetaApiOpts, root?: string)
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   return jsonResponse(listInstalledPlugins(root));
 }
+
+const MARKET_NAME = /^[a-z0-9][a-z0-9-]{1,39}$/;
+const MARKET_SPEC = /^[a-z0-9][a-z0-9-]{1,39}@[a-z0-9][a-z0-9-]{1,39}$/;
+
+/** 실패 원인 한 줄 — 사용자가 «왜» 를 볼 수 있게(2026-09-29 실물: «설치 중 오류가 발생했습니다» 만 보여 아티팩트 누락을 못 봤다). 홈 경로는 `~` 로 · 200자 · 한 줄. */
+export function safeDetail(error: unknown): string | undefined {
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
+  if (!message) return undefined;
+  return message.replace(/\/(?:Users|home)\/[^/\s]+/g, '~').replace(/\s+/g, ' ').trim().slice(0, 200) || undefined;
+}
+
+function safeReason(error: unknown): string {
+  const reason = error && typeof error === 'object' && 'reason' in error ? error.reason : undefined;
+  return typeof reason === 'string' && ['signature', 'scan', 'consent-denied', 'credentials', 'conflict', 'io'].includes(reason)
+    ? reason : 'io';
+}
+
+export async function handlePluginsMarketRefresh(req: Request, name: string, opts: MetaApiOpts, fetchOptions: MarketFetchOptions = {}): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!MARKET_NAME.test(name)) return jsonResponse({ ok: false, reason: 'invalid-market' }, 400);
+  try {
+    const result = await updateMarket(name, fetchOptions);
+    const plugins = projectPlugins(result.index, name);
+    debug.log('nexus.plugins-market', 'refresh', { name, ok: true, count: plugins.length });
+    return jsonResponse({ ok: true, plugins });
+  } catch (error) {
+    const reason = safeReason(error);
+    debug.log('nexus.plugins-market', 'refresh', { name, ok: false, reason });
+    return jsonResponse({ ok: false, reason });
+  }
+}
+
+export async function handlePluginsInstall(req: Request, opts: MetaApiOpts, root?: string, configPath?: string): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  let body: unknown;
+  try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const input = body as { spec?: unknown; acceptedCapabilities?: unknown } | null;
+  if (!input || typeof input.spec !== 'string' || !MARKET_SPEC.test(input.spec) ||
+    !Array.isArray(input.acceptedCapabilities) || !input.acceptedCapabilities.every(cap => typeof cap === 'string')) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  const spec = input.spec;
+  const accepted = new Set(input.acceptedCapabilities as string[]);
+  const trustedKeys = configuredTrustedKeys(configPath);
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      const send = (value: Record<string, unknown>) => controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`));
+      const onEvent = (event: InstallEvent) => {
+        if (event.event === 'consent') send({ event: 'consent', capabilities: event.capabilities, required: event.required });
+        else if (event.event === 'credentials') send({ event: 'credentials', required: event.connectors.some(c => c.fields.length > 0) });
+        else send({ event: event.event });
+      };
+      try {
+        await installPlugin(spec, {
+          ...(root ? { root } : {}), trustedKeys: [...OFFICIAL_INDEX_KEYS, ...trustedKeys],
+          onEvent, consent: capabilities => capabilities.every(cap => accepted.has(cap)),
+        });
+        debug.log('nexus.plugins-market', 'install', { spec, ok: true });
+      } catch (error) {
+        const reason = safeReason(error);
+        const detail = safeDetail(error);
+        debug.log('nexus.plugins-market', 'install', { spec, ok: false, reason, ...(detail ? { detail } : {}) });
+        send({ event: 'failed', reason, ...(detail ? { detail } : {}) });
+      } finally { controller.close(); }
+    },
+  });
+  return new Response(stream, { headers: { 'content-type': 'application/x-ndjson; charset=utf-8', 'cache-control': 'no-store' } });
+}
+
+export function handlePluginsRemove(req: Request, name: string, opts: MetaApiOpts, root?: string): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!MARKET_NAME.test(name)) return jsonResponse({ error: 'bad_request' }, 400);
+  try {
+    const removed = removePlugin(name, root);
+    debug.log('nexus.plugins-market', 'remove', { name, removed });
+    return jsonResponse({ removed });
+  } catch (error) {
+    const reason = safeReason(error);
+    debug.log('nexus.plugins-market', 'remove', { name, reason });
+    return jsonResponse({ error: reason }, 500);
+  }
+}

package/src/nexus/api/pod-credential-api.ts

@@ -4,10 +4,14 @@
  *  응답 키는 `key`·`expires_at` 둘뿐. refresh·계정 id·파일 경로는 응답·로그·에러에 싣지 않는다.
  */
 import { debug } from '../../debug/log.js';
-import { verifyGroundingToken, type GroundingTokenDeps } from '../../grounding/token.js';
+import { githubInstallationCredential } from '../../auth/github-app-token.js';
+import { verifyGroundingToken, type GroundingTokenDeps, type GroundingTokenScope } from '../../grounding/token.js';
 import { isGrokSubscriptionExpiring, readGrokSubscriptionAccess, refreshGrokSubscriptionToken } from '../../grok/credential.js';
 
 export const POD_CREDENTIAL_GROK_PATH = '/v1/pod/credential/grok';
+export const POD_CREDENTIAL_GITHUB_PATH = '/v1/pod/credential/github';
+export const POD_GITHUB_CREDENTIAL_TOKEN_ENV = 'ELANOUS_POD_GITHUB_CREDENTIAL_TOKEN';
+export const POD_GITHUB_CREDENTIAL_URL_ENV = 'ELANOUS_POD_GITHUB_CREDENTIAL_URL';
 /** 만료까지 이 안이면 기존 호스트 갱신(`refreshGrokSubscriptionToken`)을 한 번 부른다. */
 export const POD_CREDENTIAL_HOST_REFRESH_WINDOW_MS = 10 * 60 * 1000;
 /** runId 당 분당 1회. */
@@ -27,34 +31,45 @@ export interface PodCredentialDeps {
   readonly loadAccess?: (home: string | undefined, env: NodeJS.ProcessEnv) => { key: string; expiresAt: string } | null;
 }
 
+export interface PodGithubCredentialDeps {
+  readonly token?: GroundingTokenDeps;
+  readonly now?: () => number;
+  readonly mintInstallation?: (repository: string) => { token: string; expires_at: string } | null;
+  readonly installationRepositories?: (token: string) => Promise<readonly string[] | null>;
+}
+
 interface HitWindow {
   readonly stamps: number[];
 }
 
 const hitsByRun = new Map<string, HitWindow>();
 const globalHits: number[] = [];
+const githubHitsByRun = new Map<string, HitWindow>();
+const githubGlobalHits: number[] = [];
 
 export function resetPodCredentialRateForTesting(): void {
   hitsByRun.clear();
   globalHits.length = 0;
+  githubHitsByRun.clear();
+  githubGlobalHits.length = 0;
 }
 
 function prune(stamps: number[], now: number): number[] {
   return stamps.filter((t) => now - t < 60_000);
 }
 
-function takeRate(runId: string, now: number): boolean {
-  const prev = prune(hitsByRun.get(runId)?.stamps ?? [], now);
-  const global = prune(globalHits, now);
-  globalHits.length = 0;
-  globalHits.push(...global);
-  if (prev.length >= POD_CREDENTIAL_PER_RUN_PER_MIN || globalHits.length >= POD_CREDENTIAL_GLOBAL_PER_MIN) {
-    hitsByRun.set(runId, { stamps: prev });
+function takeRate(runId: string, now: number, byRun = hitsByRun, all = globalHits): boolean {
+  const prev = prune(byRun.get(runId)?.stamps ?? [], now);
+  const global = prune(all, now);
+  all.length = 0;
+  all.push(...global);
+  if (prev.length >= POD_CREDENTIAL_PER_RUN_PER_MIN || all.length >= POD_CREDENTIAL_GLOBAL_PER_MIN) {
+    byRun.set(runId, { stamps: prev });
     return false;
   }
   prev.push(now);
-  globalHits.push(now);
-  hitsByRun.set(runId, { stamps: prev });
+  all.push(now);
+  byRun.set(runId, { stamps: prev });
   return true;
 }
 
@@ -109,25 +124,64 @@ export async function handlePodGrokCredential(req: Request, deps: PodCredentialD
   return Response.json({ key: loaded.key, expires_at: expiresAt });
 }
 
+export async function installationRepositories(token: string): Promise<readonly string[] | null> {
+  const response = await fetch('https://api.github.com/installation/repositories?per_page=100', {
+    headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28' },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) return null;
+  const data: unknown = await response.json();
+  if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray((data as { repositories?: unknown }).repositories)) return null;
+  const body = data as { total_count?: unknown; repositories: unknown[] };
+  if (body.repositories.length !== 1 || body.total_count !== 1) return null;
+  const name = body.repositories[0] && typeof body.repositories[0] === 'object' && !Array.isArray(body.repositories[0]) ? (body.repositories[0] as { full_name?: unknown }).full_name : undefined;
+  return typeof name === 'string' ? [name] : null;
+}
+
+/** No repository is accepted from the request body: the host signed its owner/name into the run token. */
+export async function handlePodGithubCredential(req: Request, deps: PodGithubCredentialDeps = {}): Promise<Response> {
+  const gate = await authenticatePodCredential(req, deps, 'gh-credential');
+  if (!gate.ok) return gate.response;
+  if (!gate.repository || !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(gate.repository)) return Response.json({ error: 'unauthorized' }, { status: 401 });
+  if (!takeRate(gate.runId, (deps.now ?? Date.now)(), githubHitsByRun, githubGlobalHits)) return reasonResponse(429, 'rate');
+
+  let issued: { token: string; expires_at: string } | null;
+  try {
+    issued = (deps.mintInstallation ?? ((repository) => githubInstallationCredential({ scope: { repository: repository.split('/')[1]! } })))(gate.repository);
+  } catch {
+    return reasonResponse(503, 'unavailable');
+  }
+  if (!issued?.token || typeof issued.expires_at !== 'string' || !Number.isFinite(Date.parse(issued.expires_at)) || Date.parse(issued.expires_at) <= (deps.now ?? Date.now)()) return reasonResponse(503, 'unavailable');
+  try {
+    const available = await (deps.installationRepositories ?? installationRepositories)(issued.token);
+    if (available?.length !== 1 || available[0]?.toLowerCase() !== gate.repository.toLowerCase()) return reasonResponse(503, 'unavailable');
+  } catch {
+    return reasonResponse(503, 'unavailable');
+  }
+  debug.log('pod.credential', 'github-issued', { runId: gate.runId, job: gate.job, expiresAt: issued.expires_at });
+  return Response.json({ token: issued.token, expires_at: issued.expires_at });
+}
+
 /**
  * 쓰기 관문. 본문을 읽지 않는다. 토큰이 없거나 서명이 깨지면 401,
  * scope·만료·회수는 403 과 사유만.
  */
 export async function authenticatePodCredential(
   req: Request,
-  deps: PodCredentialDeps = {},
+  deps: Pick<PodCredentialDeps, 'token'> = {},
+  expectedScope: GroundingTokenScope = 'llm-credential',
 ): Promise<
-  | { readonly ok: true; readonly runId: string; readonly job: string; readonly exp: number }
+  | { readonly ok: true; readonly runId: string; readonly job: string; readonly repository?: string; readonly exp: number }
   | { readonly ok: false; readonly response: Response }
 > {
   const token = bearerOf(req);
   if (!token) return { ok: false, response: Response.json({ error: 'unauthorized' }, { status: 401 }) };
-  const verified = await verifyGroundingToken(token, { ...(deps.token ?? {}), expectedScope: 'llm-credential' });
+  const verified = await verifyGroundingToken(token, { ...(deps.token ?? {}), expectedScope });
   if (!verified.ok) {
     if (verified.reason === 'expired' || verified.reason === 'revoked' || verified.reason === 'scope') {
       return { ok: false, response: reasonResponse(403, verified.reason) };
     }
     return { ok: false, response: Response.json({ error: 'unauthorized' }, { status: 401 }) };
   }
-  return { ok: true, runId: verified.runId, job: verified.job, exp: verified.exp };
+  return { ok: true, runId: verified.runId, job: verified.job, ...(verified.repository ? { repository: verified.repository } : {}), exp: verified.exp };
 }

package/src/nexus/api/public-routes.ts

@@ -49,6 +49,13 @@ export const PUBLIC_ROUTES: Array<PublicRoute> = [
     selfVerified: true,
     why: 'Pod grok access relay (#20789); Pods hold no nexus bearer — pod-credential-api.ts verifies its own llm-credential token (verifyGroundingToken expectedScope) before reading the body',
   },
+  {
+    method: 'POST',
+    match: 'exact',
+    path: '/v1/pod/credential/github',
+    selfVerified: true,
+    why: 'Pod GitHub App credential relay verifies its own run-scoped gh-credential token before minting a repository-scoped installation token',
+  },
   {
     method: 'GET',
     match: 'prefix',

package/src/nexus/api/trace.ts

@@ -1,12 +1,13 @@
 import { getDefaultLogStore, resolveLogInstanceName, LogStore, type LogStoreRow, type LogQuery } from '../../mss/logging/log-store.js';
 import { readLogInstances, type LogInstanceView } from '../../mss/logging/instance-registry.js';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { prodInstanceRoot } from '../../instance/resolve.js';
 import { debug, redactSecretText, redactSecrets } from '../../debug/log.js';
-import { activeStoreNames, parseSinceParam, type LogFabricDeps } from './log-fabric.js';
+import { activeStoreNames, parseSinceParam, type LogFabricDeps, registeredLogStoreCount } from './log-fabric.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './json-response.js';
+import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
 
 export type TraceLevel = 'L0' | 'L1' | 'L2' | 'L3';
 export interface TraceEvent {
@@ -201,12 +202,19 @@ export function buildRunTrace(
 
 export interface TraceDeps extends LogFabricDeps {
   queryLog?: (details: { stores: string[]; level: TraceLevel; count: number; truncated: boolean; mode: 'rows' | 'runs'; runs: number }) => void;
+  ledgerStat?: (path: string) => void;
 }
 function storeNames(url: URL, deps: TraceDeps): string[] {
   const names = [...new Set(url.searchParams.getAll('store').flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean))];
-  return names.includes('@active') ? [...new Set([...activeStoreNames(deps), ...names.filter((n) => n !== '@active')])]
-    : (names.length ? names : [url.searchParams.get('universe') || resolveLogInstanceName()]);
+  if (names.includes('@active')) {
+    let active: string[];
+    try { active = activeStoreNames(deps); }
+    catch { active = [resolveLogInstanceName()]; }
+    return [...new Set([...active, ...names.filter((n) => n !== '@active')])];
+  }
+  return names.length ? names : [url.searchParams.get('universe') || resolveLogInstanceName()];
 }
+const registeredStoreCount = (deps: TraceDeps): number | null => registeredLogStoreCount(deps);
 function selectedStores(names: string[], deps: TraceDeps): { name: string; store: LogStore | null; remote: boolean; error?: string }[] {
   const selfName = resolveLogInstanceName();
   const self = names.includes(selfName) ? (deps.store ?? getDefaultLogStore)() : null;
@@ -266,6 +274,22 @@ function sortRows(a: LogStoreRow, b: LogStoreRow): number {
   return b.ts_ms - a.ts_ms || b.id - a.id || a.instance.localeCompare(b.instance);
 }
 
+function findRunUniverse(runId: string, selected: readonly string[], deps: TraceDeps): { universe?: string; checked: number } {
+  let checked = 0;
+  const views = (deps.instances ?? readLogInstances)();
+  for (const view of [...views.filter((v) => selected.includes(v.name)), ...views.filter((v) => !selected.includes(v.name))]) {
+    checked++;
+    try {
+      (deps.ledgerStat ?? statSync)(runLedgerPath(runId, runLedgerDir(view.stateDir)));
+      return { universe: view.name, checked };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw new Error(`unable to check run ledger for '${view.name}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return { checked };
+}
+
 /** Read-only bounded log-fabric fan-in, authenticated before any store access. */
 export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {}): Response {
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
@@ -300,7 +324,7 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       const trace = buildRunTrace(runs, parsed.level as 'L0' | 'L1');
       trace.truncated = runLimitReached || failures.length > 0;
       try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'runs', runs: runs.length }); } catch { /* query logging must not block reads */ }
-      return jsonResponse({ ok: true, ...trace, stores: names, ...(failures.length ? { failedStores: failures } : {}) }, 200);
+      return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(failures.length ? { failedStores: failures } : {}) }, 200);
     }
     const failures: Array<{ name: string; reason: string }> = [];
     const rows: LogStoreRow[] = [];
@@ -321,10 +345,37 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       } catch (e) { failures.push({ name: entry.name, reason: e instanceof Error ? e.message : String(e) }); }
     }
     if (!opened) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: failures }, 503);
+    const runId = url.searchParams.get('runId');
+    let resolution: { universe?: string; checked: number } | undefined;
+    if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url)) && !requestedUniverse) {
+      // A store with no log db at all («has no log store yet» — e.g. the daemon's own tree-derived universe) cannot
+      // hold the run, so it must not block the ledger lookup. A store that exists but failed to open/read still does:
+      // «could not read» is never answered as «not there». The reply keeps `failedStores` either way.
+      const blocking = failures.filter((failure) => !/has no log store yet/.test(failure.reason));
+      if (blocking.length) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: failures }, 503);
+      try { resolution = findRunUniverse(runId, names, deps); }
+      catch (error) { return jsonResponse({ ok: false, error: 'run-universe-unavailable', reason: error instanceof Error ? error.message : String(error) }, 503); }
+      try { debug.log('nexus.trace', 'run-universe-resolved', { runId, universe: resolution.universe ?? 'not-found', checked: resolution.checked }); } catch { /* observation must not block reads */ }
+      if (resolution.universe && !names.includes(resolution.universe)) {
+        const name = resolution.universe;
+        names.push(name);
+        const [entry] = selectedStores([name], deps);
+        if (!entry?.store) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: entry?.error ?? 'log-store-unavailable' }] }, 503);
+        stores.push(entry);
+        try {
+          const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1 };
+          const search = url.searchParams.get('q');
+          if (search) query.grep = search;
+          const page = entry.store.queryTraceRun(runId, query);
+          if (page.length > TRACE_LIMIT) candidateLimitReached = true;
+          rows.push(...page.map((row) => ({ ...row, instance: row.instance || name })));
+        } catch (e) { return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: e instanceof Error ? e.message : String(e) }] }, 503); }
+      }
+    }
     const filtered = rows.filter((row) => matches(row, url)).sort(sortRows);
     const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0);
     try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'rows', runs: trace.nodes.filter((node) => node.level === 'L1' && node.count > 0).length }); } catch { /* query logging must not block reads */ }
-    return jsonResponse({ ok: true, ...trace, stores: names, ...(failures.length ? { failedStores: failures } : {}) }, 200);
+    return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom: 'ledger' as const, runUniverse: resolution.universe } : { runUniverse: 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);
   } finally { closeStores(stores, deps); }
 }