@pellux/goodvibes-agent 1.0.31 → 1.0.34

package/src/tools/agent-harness-pairing-posture.ts

@@ -0,0 +1,265 @@
+import { networkInterfaces } from 'node:os';
+import type { CommandContext } from '../input/command-registry.ts';
+import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
+import { resolveRuntimeEndpointBinding } from '../cli/endpoints.ts';
+import { connectedHostOperatorTokenFingerprint, readConnectedHostOperatorToken } from '../runtime/connected-host-auth.ts';
+import { requirePlatform, requireShellPaths } from '../input/commands/runtime-services.ts';
+
+export interface AgentHarnessPairingArgs {
+  readonly pairingRouteId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type PairingResolution =
+  | { readonly status: 'found'; readonly route: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+type PairingLookupSource = 'pairingRouteId' | 'target' | 'query';
+
+interface PairingRoute {
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly effect: 'read-only' | 'visible-navigation' | 'external-network' | 'confirmation-gated-secret-display';
+  readonly command?: string;
+  readonly harnessRoute?: string;
+  readonly capabilityIds?: readonly string[];
+  readonly requiresConfirmation?: boolean;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function localNetworkIp(): string {
+  try {
+    const nets = networkInterfaces();
+    for (const name of Object.keys(nets)) {
+      for (const netInfo of nets[name] ?? []) {
+        if (netInfo.family === 'IPv4' && !netInfo.internal) return netInfo.address;
+      }
+    }
+  } catch {
+    return '127.0.0.1';
+  }
+  return '127.0.0.1';
+}
+
+function urlHostForBindHost(host: string): string {
+  if (host === '0.0.0.0' || host === '::') return localNetworkIp();
+  return host || '127.0.0.1';
+}
+
+function lookupFromArgs(args: AgentHarnessPairingArgs): { readonly source: PairingLookupSource; readonly input: string } | null {
+  const pairingRouteId = readString(args.pairingRouteId);
+  if (pairingRouteId) return { source: 'pairingRouteId', input: pairingRouteId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function pairingRoutes(): readonly PairingRoute[] {
+  return [
+    {
+      id: 'qr-pairing',
+      label: 'QR pairing',
+      detail: 'Visible companion pairing route that prints QR setup details in the Agent TUI without printing the raw token.',
+      effect: 'external-network',
+      command: '/pair',
+      harnessRoute: 'agent_harness mode:"run_command" command:"/pair" confirm:true explicitUserRequest:"..."',
+      requiresConfirmation: true,
+    },
+    {
+      id: 'manual-token-display',
+      label: 'Manual token display',
+      detail: 'Explicitly confirmed fallback route that prints the raw companion token only when the user asks for manual setup.',
+      effect: 'confirmation-gated-secret-display',
+      command: '/pair --show-token --yes',
+      harnessRoute: 'agent_harness mode:"run_command" command:"/pair --show-token --yes" confirm:true explicitUserRequest:"..."',
+      requiresConfirmation: true,
+    },
+    {
+      id: 'pairing-ui',
+      label: 'Pairing workspace route',
+      detail: 'Visible Agent workspace route for companion pairing and channel setup.',
+      effect: 'visible-navigation',
+      command: '/agent channels',
+      harnessRoute: 'agent_harness mode:"workspace_action" target:"pair"',
+      capabilityIds: ['companion-pairing', 'mobile-command-routing'],
+    },
+    {
+      id: 'connected-host-status',
+      label: 'Connected host live posture',
+      detail: 'Read-only reachability, token posture, SDK compatibility, and route readiness used before companion setup.',
+      effect: 'read-only',
+      harnessRoute: 'agent_harness mode:"connected_host_status"',
+      capabilityIds: ['connected-host-status'],
+    },
+    {
+      id: 'companion-capabilities',
+      label: 'Companion capability map',
+      detail: 'Allowed and blocked companion route families for pairing, shared sessions, tasks, approvals, provider/model changes, attachments, and mobile command surfaces.',
+      effect: 'read-only',
+      harnessRoute: 'agent_harness mode:"connected_host"',
+      capabilityIds: [
+        'companion-pairing',
+        'shared-session',
+        'task-management',
+        'approval-actions',
+        'provider-model-routing',
+        'attachment-upload',
+        'mobile-command-routing',
+      ],
+    },
+    {
+      id: 'channels-readiness',
+      label: 'Channel readiness',
+      detail: 'Read-only channel setup and delivery posture used after pairing when messages or reminders need an explicit delivery target.',
+      effect: 'read-only',
+      command: '/channels',
+      harnessRoute: 'agent_harness mode:"channels"',
+      capabilityIds: ['channels', 'notifications'],
+    },
+  ];
+}
+
+function routeSearchText(route: PairingRoute): string {
+  return [
+    route.id,
+    route.label,
+    route.detail,
+    route.effect,
+    route.command ?? '',
+    route.harnessRoute ?? '',
+    ...(route.capabilityIds ?? []),
+  ].join('\n').toLowerCase();
+}
+
+function describeCandidate(route: PairingRoute): Record<string, unknown> {
+  return {
+    pairingRouteId: route.id,
+    label: route.label,
+    effect: route.effect,
+    requiresConfirmation: route.requiresConfirmation === true,
+  };
+}
+
+function describeRoute(route: PairingRoute, options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {}): Record<string, unknown> {
+  return {
+    pairingRouteId: route.id,
+    label: route.label,
+    detail: route.detail,
+    effect: route.effect,
+    ...(route.command ? { command: route.command } : {}),
+    ...(route.harnessRoute ? { harnessRoute: route.harnessRoute } : {}),
+    ...(route.capabilityIds ? { capabilityIds: route.capabilityIds } : {}),
+    requiresConfirmation: route.requiresConfirmation === true,
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      policy: {
+        effect: route.effect,
+        values: 'Pairing posture returns endpoint binding and token fingerprint only; raw companion tokens and QR payloads are never returned by this read-only mode.',
+        mutation: 'Pairing display, manual token display, companion connection, channel sends, provider/model changes, approval actions, and attachment flows stay explicit visible user flows.',
+      },
+      modelAccess: {
+        inspectPairing: 'agent_harness mode:"pairing_posture"',
+        inspectRoute: 'agent_harness mode:"pairing_route"',
+        connectedHostStatus: 'agent_harness mode:"connected_host_status"',
+        connectedHostCapabilities: 'agent_harness mode:"connected_host"',
+        channels: 'agent_harness mode:"channels"',
+      },
+    } : {}),
+  };
+}
+
+function pairingState(context: CommandContext): Record<string, unknown> {
+  const shellPaths = requireShellPaths(context);
+  const configManager = requirePlatform(context).configManager;
+  const tokenRecord = readConnectedHostOperatorToken(shellPaths.homeDirectory);
+  const binding = resolveRuntimeEndpointBinding(configManager, 'controlPlane');
+  const host = urlHostForBindHost(binding.host);
+  return {
+    surface: GOODVIBES_AGENT_PAIRING_SURFACE,
+    endpoint: {
+      endpointId: 'controlPlane',
+      bindHost: binding.host,
+      advertisedHost: host,
+      port: binding.port,
+      url: `http://${host}:${binding.port}`,
+    },
+    token: {
+      present: Boolean(tokenRecord.token),
+      path: tokenRecord.path,
+      fingerprint: tokenRecord.token ? `sha256:${connectedHostOperatorTokenFingerprint(tokenRecord.token)}` : null,
+      rawValueReturned: false,
+    },
+    companionPayloadReturned: false,
+  };
+}
+
+export function pairingPostureCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const state = pairingState(context);
+  return {
+    modes: ['pairing_posture', 'pairing_route'],
+    routes: pairingRoutes().length,
+    tokenPresent: (state.token as { readonly present?: boolean }).present === true,
+    readOnly: true,
+  };
+}
+
+export function pairingPostureSummary(context: CommandContext, args: AgentHarnessPairingArgs): Record<string, unknown> {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const routes = pairingRoutes();
+  const filtered = routes
+    .filter((route) => !query || routeSearchText(route).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    status: 'available',
+    pairing: pairingState(context),
+    routes: filtered.map((route) => describeRoute(route, { includeParameters })),
+    returned: filtered.length,
+    total: routes.length,
+    policy: 'Read-only pairing posture. QR display, manual token display, companion connection, channel delivery, task, approval, provider/model, and attachment actions remain explicit visible user flows.',
+  };
+}
+
+export function describeHarnessPairingRoute(_context: CommandContext, args: AgentHarnessPairingArgs): PairingResolution {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'pairing_route requires pairingRouteId, target, or query. Use mode:"pairing_posture" to inspect pairing route ids.',
+    };
+  }
+  const routes = pairingRoutes();
+  const normalized = lookup.input.toLowerCase();
+  const exact = routes.find((route) => route.id === lookup.input);
+  if (exact) return { status: 'found', route: describeRoute(exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = routes.find((route) => route.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', route: describeRoute(insensitive, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = routes.filter((route) => routeSearchText(route).includes(normalized));
+  if (searched.length === 1) return { status: 'found', route: describeRoute(searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown pairing route ${lookup.input}. Use mode:"pairing_posture" to inspect pairing route ids.`,
+  };
+}

package/src/tools/agent-harness-panel-metadata.ts

@@ -7,6 +7,7 @@ export interface AgentHarnessPanelArgs {
   readonly panelId?: unknown;
   readonly target?: unknown;
   readonly category?: unknown;
+  readonly includeParameters?: unknown;
   readonly limit?: unknown;
   readonly pane?: unknown;
 }
@@ -39,6 +40,11 @@ function readLimit(value: unknown, fallback: number): number {
   return Math.max(1, Math.min(500, Math.trunc(parsed)));
 }
 
+function previewText(value: string, maxLength = 120): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+}
+
 function panelManager(context: CommandContext) {
   return context.workspace.panelManager ?? null;
 }
@@ -50,6 +56,7 @@ function panelMatches(panel: Record<string, unknown>, query: string): boolean {
     panel.name,
     panel.category,
     panel.description,
+    panel.summary,
     panel.workspaceRoute,
   ].map((value) => typeof value === 'object' ? JSON.stringify(value) : String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
 }
@@ -69,7 +76,7 @@ function panelCandidate(registration: PanelRegistration): Record<string, unknown
     id: registration.id,
     name: registration.name,
     category: registration.category,
-    description: registration.description,
+    summary: previewText(registration.description),
     workspaceRoute: {
       categoryId: agentWorkspaceCategoryForPanel(registration.id),
       command: agentWorkspaceCommandForPanel(registration.id),
@@ -103,7 +110,11 @@ function resolveHarnessPanel(context: CommandContext, args: AgentHarnessPanelArg
   return null;
 }
 
-function describePanelRegistration(context: CommandContext, registration: PanelRegistration, lookup?: PanelLookup): Record<string, unknown> {
+function describePanelRegistration(
+  context: CommandContext,
+  registration: PanelRegistration,
+  options: { readonly includeParameters?: boolean; readonly lookup?: PanelLookup } = {},
+): Record<string, unknown> {
   const manager = panelManager(context);
   const openPanel = manager?.getPanel(registration.id) ?? null;
   const pane = manager?.getPaneOf(registration.id) ?? null;
@@ -113,8 +124,8 @@ function describePanelRegistration(context: CommandContext, registration: PanelR
     name: registration.name,
     icon: registration.icon,
     category: registration.category,
-    description: registration.description,
-    ...(lookup ? { lookup } : {}),
+    ...(options.includeParameters ? { description: registration.description } : { summary: previewText(registration.description) }),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
     preload: registration.preload === true,
     open: openPanel !== null,
     pane,
@@ -124,11 +135,13 @@ function describePanelRegistration(context: CommandContext, registration: PanelR
       categoryId: agentWorkspaceCategoryForPanel(registration.id),
       command: agentWorkspaceCommandForPanel(registration.id),
     },
-    policy: {
-      effect: 'ui-navigation',
-      confirmation: 'agent_harness mode:"open_panel" requires confirm:true and explicitUserRequest.',
-      boundary: 'Panels are Agent/TUI operator views. The model can inspect panel catalog/open state; panel routing uses the existing Agent workspace bridge and does not mutate connected-host lifecycle.',
-    },
+    ...(options.includeParameters ? {
+      policy: {
+        effect: 'ui-navigation',
+        confirmation: 'agent_harness mode:"open_panel" requires confirm:true and explicitUserRequest.',
+        boundary: 'Panels are Agent/TUI operator views. The model can inspect panel catalog/open state; panel routing uses the existing Agent workspace bridge and does not mutate connected-host lifecycle.',
+      },
+    } : {}),
   };
 }
 
@@ -142,8 +155,9 @@ export function listHarnessPanels(context: CommandContext, args: AgentHarnessPan
   const query = readString(args.query);
   const category = readString(args.category);
   const limit = readLimit(args.limit, 200);
+  const includeParameters = args.includeParameters === true;
   return manager.getRegisteredTypes()
-    .map((registration) => describePanelRegistration(context, registration))
+    .map((registration) => describePanelRegistration(context, registration, { includeParameters }))
     .filter((panel) => !category || panel.category === category)
     .filter((panel) => panelMatches(panel, query))
     .sort((a, b) => String(a.id).localeCompare(String(b.id)))
@@ -152,7 +166,7 @@ export function listHarnessPanels(context: CommandContext, args: AgentHarnessPan
 
 export function describeHarnessPanel(context: CommandContext, args: AgentHarnessPanelArgs): Record<string, unknown> | null {
   const resolved = resolveHarnessPanel(context, args);
-  if (resolved?.status === 'found') return describePanelRegistration(context, resolved.registration, resolved.lookup);
+  if (resolved?.status === 'found') return describePanelRegistration(context, resolved.registration, { includeParameters: true, lookup: resolved.lookup });
   if (resolved?.status === 'ambiguous') {
     return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
   }
@@ -171,7 +185,7 @@ export function openHarnessPanel(context: CommandContext, args: AgentHarnessPane
       availablePanels: listHarnessPanels(context, { limit: 50 }).map((entry) => entry.id),
     };
   }
-  const panel = describePanelRegistration(context, resolved.registration, resolved.lookup);
+  const panel = describePanelRegistration(context, resolved.registration, { includeParameters: true, lookup: resolved.lookup });
   const requestedPane = readString(args.pane);
   const pane = requestedPane === 'bottom' || requestedPane === 'top' ? requestedPane : undefined;
   if (!context.showPanel) {

package/src/tools/agent-harness-provider-account-metadata.ts

@@ -0,0 +1,205 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import type { ProviderAccountRecord, ProviderAccountSnapshot } from '../panels/provider-account-snapshot.ts';
+import { buildProviderAccountSnapshot } from '../panels/provider-account-snapshot.ts';
+import { requireProvider, requireServiceRegistry, requireSubscriptionManager } from '../input/commands/runtime-services.ts';
+
+export interface AgentHarnessProviderAccountArgs {
+  readonly providerId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type ProviderAccountLookupSource = 'providerId' | 'target' | 'query';
+
+type ProviderAccountResolution =
+  | { readonly status: 'found'; readonly account: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+async function loadSnapshot(context: CommandContext): Promise<ProviderAccountSnapshot> {
+  return await buildProviderAccountSnapshot({
+    providerModels: requireProvider(context).providerRegistry,
+    services: requireServiceRegistry(context),
+    subscriptions: requireSubscriptionManager(context),
+    environment: {
+      hasEnvironmentVariable: (name: string) => Boolean(process.env[name]),
+    },
+  });
+}
+
+function lookupFromArgs(args: AgentHarnessProviderAccountArgs): { readonly source: ProviderAccountLookupSource; readonly input: string } | null {
+  const providerId = readString(args.providerId);
+  if (providerId) return { source: 'providerId', input: providerId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function accountSearchText(account: ProviderAccountRecord): string {
+  return [
+    account.providerId,
+    account.authFreshness,
+    account.activeRoute,
+    account.preferredRoute,
+    account.activeRouteReason,
+    account.fallbackRoute ?? '',
+    account.fallbackRisk ?? '',
+    ...account.availableRoutes,
+    ...account.issues,
+    ...account.notes,
+    ...account.recommendedActions,
+    ...account.usageWindows.flatMap((window) => [window.label, window.detail]),
+    ...account.routeRecords.flatMap((route) => [route.route, route.freshness, route.detail, ...route.issues]),
+  ].join('\n').toLowerCase();
+}
+
+function describeCandidate(account: ProviderAccountRecord): Record<string, unknown> {
+  return {
+    providerId: account.providerId,
+    activeRoute: account.activeRoute,
+    preferredRoute: account.preferredRoute,
+    authFreshness: account.authFreshness,
+    configured: account.configured,
+    issues: account.issues.length,
+  };
+}
+
+function describeAccount(
+  account: ProviderAccountRecord,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    providerId: account.providerId,
+    active: account.active,
+    configured: account.configured,
+    modelCount: account.modelCount,
+    oauthReady: account.oauthReady,
+    pendingLogin: account.pendingLogin,
+    availableRoutes: account.availableRoutes,
+    preferredRoute: account.preferredRoute,
+    activeRoute: account.activeRoute,
+    activeRouteReason: account.activeRouteReason,
+    authFreshness: account.authFreshness,
+    ...(account.fallbackRoute ? { fallbackRoute: account.fallbackRoute } : {}),
+    ...(account.fallbackRisk ? { fallbackRisk: account.fallbackRisk } : {}),
+    ...(account.expiresAt ? { expiresAt: new Date(account.expiresAt).toISOString() } : {}),
+    ...(account.tokenType ? { tokenType: account.tokenType } : {}),
+    issueCount: account.issues.length,
+    recommendedActionCount: account.recommendedActions.length,
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      routeRecords: account.routeRecords.map((route) => ({
+        route: route.route,
+        usable: route.usable,
+        freshness: route.freshness,
+        detail: route.detail,
+        issues: route.issues,
+      })),
+      usageWindows: account.usageWindows,
+      issues: account.issues,
+      notes: account.notes,
+      recommendedActions: account.recommendedActions,
+      policy: {
+        effect: 'read-only',
+        values: 'Provider account posture reports route and freshness metadata only; raw tokens, authorization codes, and secret values are never returned.',
+        mutation: 'Provider login, logout, subscription bundle export, and account repair actions stay explicit confirmation-gated workspace or slash-command flows.',
+      },
+      modelAccess: {
+        reviewCommand: '/accounts review',
+        showCommand: `/accounts show ${account.providerId}`,
+        routesCommand: `/accounts routes ${account.providerId}`,
+        repairCommand: `/accounts repair ${account.providerId}`,
+        subscriptionInspectCommand: `/subscription inspect ${account.providerId}`,
+        workspaceActions: [
+          'provider-accounts',
+          'provider-account-repair',
+          'subscription-review',
+          'subscription-inspect',
+        ],
+        loginStartCommand: `/subscription login ${account.providerId} start --yes`,
+        loginFinishCommand: `/subscription login ${account.providerId} finish <code-or-url> --yes`,
+        logoutCommand: `/subscription logout ${account.providerId} --yes`,
+        confirmationRequired: true,
+      },
+    } : {}),
+  };
+}
+
+export async function providerAccountCatalogStatus(context: CommandContext): Promise<Record<string, unknown>> {
+  const snapshot = await loadSnapshot(context);
+  return {
+    modes: ['provider_accounts', 'provider_account'],
+    providers: snapshot.providers.length,
+    configured: snapshot.configuredCount,
+    issues: snapshot.issueCount,
+    readOnly: true,
+  };
+}
+
+export async function providerAccountSummary(
+  context: CommandContext,
+  args: AgentHarnessProviderAccountArgs,
+): Promise<Record<string, unknown>> {
+  const snapshot = await loadSnapshot(context);
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const accounts = snapshot.providers
+    .filter((account) => !query || accountSearchText(account).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    capturedAt: new Date(snapshot.capturedAt).toISOString(),
+    providers: accounts.map((account) => describeAccount(account, { includeParameters })),
+    returned: accounts.length,
+    total: snapshot.providers.length,
+    configured: snapshot.configuredCount,
+    issues: snapshot.issueCount,
+    policy: 'Read-only provider account posture. Use confirmed workspace actions or slash-command mirrors for login/logout/bundle mutations.',
+  };
+}
+
+export async function describeHarnessProviderAccount(
+  context: CommandContext,
+  args: AgentHarnessProviderAccountArgs,
+): Promise<ProviderAccountResolution> {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'provider_account requires providerId, target, or query. Use mode:"provider_accounts" to inspect provider ids.',
+    };
+  }
+  const snapshot = await loadSnapshot(context);
+  const normalized = lookup.input.toLowerCase();
+  const exact = snapshot.providers.find((account) => account.providerId === lookup.input);
+  if (exact) return { status: 'found', account: describeAccount(exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = snapshot.providers.find((account) => account.providerId.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', account: describeAccount(insensitive, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = snapshot.providers.filter((account) => accountSearchText(account).includes(normalized));
+  if (searched.length === 1) {
+    return { status: 'found', account: describeAccount(searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown provider account ${lookup.input}. Use mode:"provider_accounts" to inspect provider ids.`,
+  };
+}