@opengeni/core 2.8.0-canary.0 → 2.8.2-canary.0

package/dist/transcription.d.ts

@@ -28,6 +28,9 @@ export type TranscriptionRequest = {
     providerDeadlineAt?: Date | undefined;
     /** Exact provider selected before a resumable segment is first sent upstream. */
     providerId?: string | undefined;
+    preferredProvider?: string | null | undefined;
+    fallbackEnabled?: boolean | undefined;
+    excludedProviders?: readonly string[] | undefined;
 };
 export type TranscriptionResult = TranscribeAudioResponse & {
     /** Server-private provider id for operational metrics only. Never returned to clients. */
@@ -39,23 +42,31 @@ export declare class TranscriptionServiceError extends Error {
     readonly code: VoiceInputErrorCode;
     readonly status: number;
     readonly retryable: boolean;
+    /** Explicit rejection before any transcription result; safe to try another provider. */
+    readonly fallbackSafe: boolean;
     constructor(input: {
         code: VoiceInputErrorCode;
         message: string;
         status?: number;
         retryable?: boolean;
+        fallbackSafe?: boolean;
     });
 }
 export declare function statusForVoiceInputError(code: VoiceInputErrorCode): number;
 /** Optional workspace scope for readiness checks during provider selection. */
 export type TranscriptionAvailabilityContext = {
+    afterProvider?: string | undefined;
+    preferredProvider?: string | null | undefined;
+    fallbackEnabled?: boolean | undefined;
+    excludedProviders?: readonly string[] | undefined;
     workspaceId?: string | undefined;
     subjectId?: string | undefined;
 };
 /**
  * Extensible transcription provider port. Implementations own credentials and
  * upstream request shape. Selection happens before audio is sent; providers must
- * not fall back to another vendor after an upstream request may have started.
+ * only fall back after an explicit rejection and before any successful or
+ * uncertain provider attempt. Recording persistence owns that eligibility.
  */
 export type TranscriptionProvider = {
     readonly id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "2.8.0-canary.0",
+  "version": "2.8.2-canary.0",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -54,17 +54,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "^0.3.3-canary.0",
-    "@opengeni/codex": "^0.2.22-canary.0",
-    "@opengeni/config": "^1.0.1-canary.0",
-    "@opengeni/contracts": "^2.14.0-canary.0",
-    "@opengeni/db": "^4.1.0-canary.0",
-    "@opengeni/documents": "^0.8.20-canary.0",
-    "@opengeni/events": "^0.4.18-canary.0",
-    "@opengeni/network": "^0.3.1-canary.0",
-    "@opengeni/observability": "^0.8.20-canary.0",
-    "@opengeni/runtime": "^2.4.0-canary.0",
-    "@opengeni/storage": "^0.2.121-canary.0",
+    "@opengeni/capabilities": "^0.3.3-canary.2",
+    "@opengeni/codex": "^0.2.22-canary.2",
+    "@opengeni/config": "^1.0.3-canary.0",
+    "@opengeni/contracts": "^2.15.1-canary.0",
+    "@opengeni/db": "^4.2.1-canary.0",
+    "@opengeni/documents": "^0.8.22-canary.0",
+    "@opengeni/events": "^0.4.20-canary.0",
+    "@opengeni/network": "^0.3.1-canary.2",
+    "@opengeni/observability": "^0.8.22-canary.0",
+    "@opengeni/runtime": "^2.4.2-canary.0",
+    "@opengeni/storage": "^0.2.123-canary.0",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/application/session-tenancy.ts

@@ -287,6 +287,7 @@ export async function forkManagedHumanSession(
   const forkInput = {
     sourceWorkspaceId: workspaceId,
     sourceSessionId,
+    ...(request.sourceEventId ? { sourceEventId: request.sourceEventId } : {}),
     actorSubjectId: authorization.grant.subjectId,
     destinationWorkspaceId: workspaceId,
     destinationVisibility:

package/src/dependencies.ts

@@ -9,7 +9,7 @@ import type {
   SessionAuthorizationPort,
   TurnInitiator,
 } from "@opengeni/contracts";
-import type { Database } from "@opengeni/db";
+import type { Database, SessionWorkflowWakeDeliveryResult } from "@opengeni/db";
 import type { DocumentServices } from "@opengeni/documents";
 import type { EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
@@ -44,7 +44,9 @@ export type SessionWorkflowClient = {
     workflowId: string;
     wakeRevision: number;
     interruptionRequested?: boolean;
-  }) => Promise<void>;
+    /** Called after transport acceptance, before the fallible durable ACK. */
+    onSignalAccepted?: () => void;
+  }) => Promise<SessionWorkflowWakeDeliveryResult | void>;
   /** Trigger one bounded drain of already-committed workflow-wake revisions. */
   requestSessionWorkflowWakeDispatch: () => Promise<void>;
   // Dedicated, revision-carrying nudge for a durable Codex capacity waiter.

package/src/domain/github-skill-source.ts

@@ -0,0 +1,142 @@
+import type { Settings } from "@opengeni/config";
+import type { GitHubSkillSourceClient, GitHubSkillTreeEntry } from "./skill-imports";
+import { pinnedFetch, readResponseJsonBounded, readResponseTextBounded } from "@opengeni/network";
+
+const githubApiBase = "https://api.github.com";
+const githubRequestTimeoutMs = 15_000;
+const githubMetadataMaxBytes = 4 * 1024 * 1024;
+const githubBlobResponseMaxBytes = 512 * 1024;
+
+type GitHubJsonRequest = (path: string, maxBytes: number, label: string) => Promise<unknown>;
+
+export function createGitHubSkillSourceClient(
+  settings: Settings,
+  requestJson: GitHubJsonRequest = (path, maxBytes, label) =>
+    githubJson(settings, path, maxBytes, label),
+): GitHubSkillSourceClient {
+  return {
+    resolveCommit: async (owner, repository, ref) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/commits/${encodeURIComponent(ref)}`,
+          githubMetadataMaxBytes,
+          "GitHub Skill commit",
+        ),
+        "GitHub commit",
+      );
+      const sha = stringValue(payload.sha);
+      if (!sha) throw new Error("GitHub commit response omitted sha");
+      return sha.toLowerCase();
+    },
+    listTree: async (owner, repository, commit) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/git/trees/${encodeURIComponent(commit)}?recursive=1`,
+          githubMetadataMaxBytes,
+          "GitHub Skill tree",
+        ),
+        "GitHub tree",
+      );
+      if (payload.truncated === true) {
+        throw new Error("GitHub repository tree is too large to import safely");
+      }
+      if (!Array.isArray(payload.tree)) throw new Error("GitHub tree response omitted entries");
+      return payload.tree.map((entry, index): GitHubSkillTreeEntry => {
+        const record = recordValue(entry, `GitHub tree entry ${index}`);
+        const path = stringValue(record.path);
+        const type = stringValue(record.type);
+        const mode = stringValue(record.mode);
+        const sha = stringValue(record.sha);
+        const size = record.size;
+        if (
+          !path ||
+          (type !== "blob" && type !== "tree" && type !== "commit") ||
+          !mode ||
+          !sha ||
+          (size !== undefined &&
+            size !== null &&
+            (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0))
+        ) {
+          throw new Error(`GitHub tree entry ${index} is invalid`);
+        }
+        return { path, type, mode, sha, size: typeof size === "number" ? size : null };
+      });
+    },
+    readBlob: async (owner, repository, sha) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/git/blobs/${encodeURIComponent(sha)}`,
+          githubBlobResponseMaxBytes,
+          "GitHub Skill file",
+        ),
+        "GitHub blob",
+      );
+      if (payload.encoding !== "base64" || typeof payload.content !== "string") {
+        throw new Error("GitHub Skill file did not use base64 encoding");
+      }
+      const normalized = payload.content.replace(/\s+/gu, "");
+      if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(normalized)) {
+        throw new Error("GitHub Skill file contained invalid base64");
+      }
+      const bytes = Uint8Array.from(Buffer.from(normalized, "base64"));
+      if (
+        typeof payload.size === "number" &&
+        Number.isSafeInteger(payload.size) &&
+        payload.size !== bytes.byteLength
+      ) {
+        throw new Error("GitHub Skill file size did not match its payload");
+      }
+      return bytes;
+    },
+  };
+}
+
+async function githubJson(
+  settings: Settings,
+  path: string,
+  maxBytes: number,
+  label: string,
+): Promise<unknown> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), githubRequestTimeoutMs);
+  try {
+    const response = await pinnedFetch(
+      `${githubApiBase}${path}`,
+      {
+        method: "GET",
+        headers: {
+          accept: "application/vnd.github+json",
+          "user-agent": "OpenGeni-Capabilities",
+          "x-github-api-version": "2022-11-28",
+        },
+        signal: controller.signal,
+      },
+      settings,
+      { label, requireHttpsOutsideLocalTest: true },
+    );
+    if (!response.ok) {
+      await readResponseTextBounded(response, 8_192, `${label} error`).catch(() => undefined);
+      if (response.status === 404) throw new Error(`${label} was not found or is not public`);
+      if (response.status === 403 || response.status === 429) {
+        throw new Error(`${label} is temporarily unavailable because GitHub limited the request`);
+      }
+      throw new Error(`${label} failed with HTTP ${response.status}`);
+    }
+    return await readResponseJsonBounded(response, maxBytes, label, {
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function recordValue(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} response is invalid`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}

package/src/domain/packs.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 
 import {
   CapabilityPack,
+  StoredCapabilityPack,
   OPENGENI_PR_REVIEW_PACK_ID,
   OPENGENI_PR_REVIEW_SESSION_ROLE,
   stableJson,
@@ -298,9 +299,8 @@ export function isBuiltInCapabilityPack(packId: string): boolean {
 
 /**
  * Built-in packs plus the manifests registered for this workspace. Stored
- * manifests were validated at registration time; rows that no longer parse
- * (for example after a contract tightening) are skipped instead of breaking
- * the whole catalog.
+ * manifests retain exact historical bytes. Execution views derive Skill labels
+ * from their files, but malformed content needs explicit repair, not omission.
  */
 export async function listWorkspaceCapabilityPacks(
   db: Database,
@@ -310,9 +310,13 @@ export async function listWorkspaceCapabilityPacks(
   const builtInIds = new Set(packs.map((pack) => pack.id));
   const registeredPacks = registered
     .filter((registration) => !builtInIds.has(registration.pack.id))
-    .flatMap((registration) => {
-      const parsed = CapabilityPack.safeParse(registration.pack);
-      return parsed.success ? [parsed.data] : [];
+    .map((registration) => {
+      const parsed = StoredCapabilityPack.safeParse(registration.pack);
+      if (!parsed.success)
+        throw new HTTPException(422, {
+          message: `Stored Pack ${registration.pack.id} requires repair before it can be used: ${parsed.error.message}`,
+        });
+      return parsed.data;
     });
   return [...packs, ...registeredPacks];
 }
@@ -330,8 +334,12 @@ export async function resolveCapabilityPack(
   if (!registration) {
     return null;
   }
-  const parsed = CapabilityPack.safeParse(registration.pack);
-  return parsed.success ? parsed.data : null;
+  const parsed = StoredCapabilityPack.safeParse(registration.pack);
+  if (!parsed.success)
+    throw new HTTPException(422, {
+      message: `Stored Pack ${packId} requires repair before it can be used: ${parsed.error.message}`,
+    });
+  return parsed.data;
 }
 
 export function capabilityPackManifestDigest(pack: CapabilityPack): string {

package/src/domain/product-integration-pack.ts

@@ -37,6 +37,7 @@ The desired outcome is a native-feeling product experience backed by a standalon
 - When an unknown choice is reversible and low-risk, choose the best-fitting default, state the assumption, and continue. When it changes privacy, tenant authority, write access, cost exposure, or an external mutation, resolve it before crossing that boundary.
 - Possession of a credential or access to a cloud, repository, or deployment is technical capability, not authorization. Match the user's requested delivery autonomy and the repository's stated workflow.
 - Keep alternatives open until evidence eliminates them. Use strict rules only for actual security, privacy, protocol, or authorization invariants.
+- For packaged React chat, use SessionConversation or compose MessageTimeline and ChatComposer with the normal SDK and authenticated session routes. For a custom or compatible frontend, use the optional backend chat handler.
 
 Read the references selectively:
 

package/src/domain/remember.ts

@@ -50,6 +50,7 @@ export class RememberError extends Error {
       | "proposal_unavailable"
       | "proposal_not_confirmable"
       | "human_confirmation_unavailable"
+      | "preference_retired"
       | "baseline_stale",
     message: string,
   ) {
@@ -327,6 +328,12 @@ export function createRememberRouter(options: RememberRouterOptions): {
     async remember(input) {
       const attempt = await attemptOf(input.attempt);
       const request = RememberRequest.parse(input.request);
+      if (request.lane === "preference") {
+        throw new RememberError(
+          "preference_retired",
+          "The Remember preference lane is retired; use skill_save for shared Skill files. No note or proposal was created.",
+        );
+      }
       const note = await createNote(options.db, {
         ...attempt,
         operationId: derivedRememberOperationId(request.operationId, "note"),

package/src/domain/scheduled-tasks.ts

@@ -21,6 +21,7 @@ import {
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   resolveWorkspaceSessionToolDefaults,
+  resolveBundledSkillSelection,
   SessionAgentAccess,
   SessionEndUser,
   SessionMemoryScope,
@@ -480,6 +481,14 @@ export async function validateScheduledTaskTarget(input: {
   if (!session || session.accountId !== input.grant.accountId) {
     throw new HTTPException(404, { message: "target session not found" });
   }
+  if (
+    input.agentConfig.bundledSkillIds !== undefined &&
+    !isDeepStrictEqual(input.agentConfig.bundledSkillIds, session.bundledSkillIds)
+  ) {
+    throw new HTTPException(422, {
+      message: "An existing-session schedule cannot change that session's bundled Skill selection",
+    });
+  }
   if (session.status === "cancelled") {
     throw new HTTPException(409, {
       message: "target session is cancelled; choose a revivable session",
@@ -1301,6 +1310,24 @@ async function validateScheduledTaskAgentConfig(input: {
   workspaceId: string;
   toolsProvided?: boolean;
 }): Promise<ScheduledTaskAgentConfig> {
+  const actor = creationInitiatorForGrant(input.grant).actor;
+  const parent = actor ? await getSession(input.db, input.workspaceId, actor.sessionId) : null;
+  if (actor && (!parent || parent.accountId !== input.grant.accountId)) {
+    throw new HTTPException(403, {
+      message: "Scheduled Skill selection requires the creating agent's session",
+    });
+  }
+  let bundledSkillIds: ScheduledTaskAgentConfig["bundledSkillIds"];
+  try {
+    bundledSkillIds = resolveBundledSkillSelection(
+      input.payload.agentConfig.bundledSkillIds,
+      parent?.bundledSkillIds,
+    );
+  } catch (error) {
+    throw new HTTPException(422, {
+      message: error instanceof Error ? error.message : "Invalid bundled Skill selection",
+    });
+  }
   // Reject a curated-out model before touching the DB: a scheduled task is a
   // session the worker runs later, so it must pass the same allow-list as the
   // session choke points (a `scheduled_tasks:manage` holder could otherwise set
@@ -1382,6 +1409,7 @@ async function validateScheduledTaskAgentConfig(input: {
   }
   const validated = {
     ...input.payload.agentConfig,
+    ...(bundledSkillIds !== undefined ? { bundledSkillIds } : {}),
     ...(model === undefined || model === null ? {} : { model }),
     prompt,
     resources,

package/src/domain/sessions.ts

@@ -22,6 +22,7 @@ import {
   FIRST_PARTY_MCP_TOOL_NAMES,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   SessionSkills,
+  resolveBundledSkillSelection,
   SessionSpawnDenial,
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
@@ -747,6 +748,7 @@ export async function createAndStartSessionWithOutcome(input: {
   modelContext?: string | null;
   resources: ResourceRef[];
   skills?: SessionSkill[];
+  bundledSkillIds?: import("@opengeni/contracts").BundledSkillId[] | undefined;
   tools: ToolRef[];
   // Public admission always supplies provenance; optional keeps internal
   // callers that predate durable tool-policy provenance source-compatible
@@ -995,6 +997,7 @@ export async function createAndStartSessionWithOutcome(input: {
       initialModelContext: input.modelContext ?? null,
       resources: input.resources,
       skills: input.skills ?? [],
+      bundledSkillIds: input.bundledSkillIds,
       tools: input.tools,
       toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
@@ -1088,6 +1091,7 @@ export async function createAndStartSessionWithOutcome(input: {
       initialModelContext: input.modelContext ?? null,
       resources: input.resources,
       skills: input.skills ?? [],
+      bundledSkillIds: input.bundledSkillIds,
       tools: input.tools,
       toolPolicy: input.toolPolicy,
       metadata: sessionMetadata,
@@ -2038,6 +2042,17 @@ export async function createSessionForRequestWithOutcome(
       message: error instanceof Error ? error.message : "invalid child visibility",
     });
   }
+  let bundledSkillIds: import("@opengeni/contracts").BundledSkillId[] | undefined;
+  try {
+    bundledSkillIds = resolveBundledSkillSelection(
+      payload.bundledSkillIds,
+      parentSession?.bundledSkillIds,
+    );
+  } catch (error) {
+    throw new HTTPException(422, {
+      message: error instanceof Error ? error.message : "Invalid bundled Skill selection",
+    });
+  }
   // Agent-access/end-user/memory scope inherit and narrow exactly like
   // visibility: presence is read from the raw request because the Zod
   // defaults erase absent-vs-explicit, and the parent side comes from the
@@ -2092,6 +2107,7 @@ export async function createSessionForRequestWithOutcome(
   ) {
     try {
       const initializedReplay = await getInitializedSessionCreateReplay(db, {
+        bundledSkillIds,
         accountId: grant.accountId,
         workspaceId,
         subjectId: replayManagedHumanSubjectId ?? grant.subjectId,
@@ -2941,6 +2957,7 @@ export async function createSessionForRequestWithOutcome(
       modelContext: payload.modelContext ?? null,
       resources,
       skills,
+      bundledSkillIds,
       tools,
       toolPolicy,
       ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),

package/src/domain/skill-imports.ts

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
 import type { SkillImportPreview, SkillImportSource } from "@opengeni/contracts";
 import {
   buildPortableSkillArtifact,
+  parsePortableSkillFrontmatter,
+  PORTABLE_SKILL_MAX_FILE_BYTES,
   PORTABLE_SKILL_MAX_FILES,
   PORTABLE_SKILL_MAX_TOTAL_BYTES,
   type SkillLibraryFile,
@@ -55,7 +57,18 @@ export async function resolveSkillImport(
     throw new HTTPException(422, { message: "GitHub returned an invalid source commit" });
   }
   const tree = await client.listTree(parsed.owner, parsed.repository, sourceCommit);
-  const sourcePath = selectSkillRoot(parsed, tree);
+  // Metadata discovery and the selected artifact share immutable blobs. This
+  // avoids reading SKILL.md twice without caching mutable refs or remote URLs.
+  const blobs = new Map<string, Promise<Uint8Array>>();
+  const readBlob = (sha: string) => {
+    let pending = blobs.get(sha);
+    if (!pending) {
+      pending = client.readBlob(parsed.owner, parsed.repository, sha);
+      blobs.set(sha, pending);
+    }
+    return pending;
+  };
+  const sourcePath = await selectSkillRoot(parsed, tree, readBlob, sourceCommit);
   const entries = skillFilesUnderRoot(tree, sourcePath);
   const declaredBytes = entries.reduce((sum, entry) => sum + (entry.size ?? 0), 0);
   if (entries.length > PORTABLE_SKILL_MAX_FILES) {
@@ -69,11 +82,11 @@ export async function resolveSkillImport(
     });
   }
   const files = await mapConcurrent(entries, maxConcurrentBlobReads, async (entry) => {
+    // Keep provider/network failures distinct from UTF-8 validation failures.
+    const bytes = await readBlob(entry.sha);
     let content: string;
     try {
-      content = new TextDecoder("utf-8", { fatal: true }).decode(
-        await client.readBlob(parsed.owner, parsed.repository, entry.sha),
-      );
+      content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
     } catch {
       throw new HTTPException(422, {
         message: `Skill file is not valid UTF-8 text: ${relativeSkillPath(entry.path, sourcePath)}`,
@@ -159,7 +172,12 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
       message: "Skill imports require a credential-free HTTPS URL without a fragment",
     });
   }
-  const segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  let segments: string[];
+  try {
+    segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  } catch {
+    throw new HTTPException(422, { message: "The Skill URL contains invalid encoding" });
+  }
   if (url.hostname === "skills.sh" || url.hostname === "www.skills.sh") {
     if (segments.length !== 3) {
       throw new HTTPException(422, {
@@ -212,14 +230,14 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
   const ref = segments[3];
   if (!ref) throw new HTTPException(422, { message: "The GitHub URL is missing a revision" });
   const pathSegments = segments.slice(4);
-  if (pathSegments.length === 0) {
+  if (pathSegments.length === 0 && mode === "blob") {
     throw new HTTPException(422, { message: "The GitHub URL is missing a Skill folder" });
   }
-  const requestedPath = normalizeGitHubPath(
+  const folderSegments =
     mode === "blob" && pathSegments.at(-1)?.toLowerCase() === "skill.md"
       ? pathSegments.slice(0, -1)
-      : pathSegments,
-  );
+      : pathSegments;
+  const requestedPath = folderSegments.length === 0 ? "." : normalizeGitHubPath(folderSegments);
   return {
     source: "github",
     owner,
@@ -231,7 +249,12 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
   };
 }
 
-function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTreeEntry[]): string {
+async function selectSkillRoot(
+  source: ParsedSkillSource,
+  tree: readonly GitHubSkillTreeEntry[],
+  readBlob: (sha: string) => Promise<Uint8Array>,
+  sourceCommit: string,
+): Promise<string> {
   const skillFiles = tree
     .filter(
       (entry) =>
@@ -239,7 +262,7 @@ function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTr
         entry.mode !== "120000" &&
         (entry.path === "SKILL.md" || entry.path.endsWith("/SKILL.md")),
     )
-    .map((entry) => entry.path.slice(0, -"/SKILL.md".length) || ".")
+    .map((entry) => (entry.path === "SKILL.md" ? "." : entry.path.slice(0, -"/SKILL.md".length)))
     .sort();
   if (source.requestedPath) {
     const root = source.requestedPath;
@@ -250,9 +273,61 @@ function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTr
     }
     return root;
   }
-  const candidates = source.skillSlug
-    ? skillFiles.filter((path) => path.split("/").at(-1) === source.skillSlug)
-    : skillFiles;
+  let candidates = skillFiles;
+  if (source.skillSlug) {
+    // skills.sh identifies frontmatter names, not necessarily folder basenames
+    // (e.g. vercel-react-best-practices lives in skills/react-best-practices).
+    // Bound discovery as well as the eventual artifact; exact folder URLs avoid
+    // this scan for very large repositories or duplicate names.
+    if (skillFiles.length > PORTABLE_SKILL_MAX_FILES) {
+      throw new HTTPException(422, {
+        message: "Too many Skill candidates; paste the exact GitHub folder URL",
+      });
+    }
+    let metadataBytes = 0;
+    const entriesByPath = new Map(tree.map((entry) => [entry.path, entry]));
+    const matches = await mapConcurrent(skillFiles, maxConcurrentBlobReads, async (root) => {
+      const entry = entriesByPath.get(root === "." ? "SKILL.md" : `${root}/SKILL.md`)!;
+      if ((entry.size ?? 0) > PORTABLE_SKILL_MAX_FILE_BYTES) {
+        throw new HTTPException(422, {
+          message: "Skill metadata is too large; paste the exact GitHub folder URL",
+        });
+      }
+      const bytes = await readBlob(entry.sha);
+      metadataBytes += bytes.byteLength;
+      if (
+        bytes.byteLength > PORTABLE_SKILL_MAX_FILE_BYTES ||
+        metadataBytes > PORTABLE_SKILL_MAX_TOTAL_BYTES
+      ) {
+        throw new HTTPException(422, {
+          message: "Skill metadata is too large; paste the exact GitHub folder URL",
+        });
+      }
+      let markdown: string;
+      try {
+        markdown = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+      } catch {
+        throw new HTTPException(422, {
+          message: "Skill metadata is not valid UTF-8; paste the exact GitHub folder URL",
+        });
+      }
+      return (
+        parsePortableSkillFrontmatter(markdown).name?.toLowerCase() ===
+        source.skillSlug!.toLowerCase()
+      );
+    });
+    candidates = skillFiles.filter((_, index) => matches[index]);
+    if (candidates.length === 0) {
+      // A folder basename is not a skills.sh identity. Never silently import a
+      // different frontmatter name from a stale directory-shaped link.
+      const folders = skillFiles.filter((path) => path.split("/").at(-1) === source.skillSlug);
+      const exactPath =
+        folders.length === 1 ? encodeGitHubPath(folders[0]!) : "<exact-skill-folder-path>";
+      throw new HTTPException(422, {
+        message: `No Skill frontmatter name matches skills.sh slug "${source.skillSlug}"; the link may be stale. Check the current Skill name, or explicitly select the intended Skill using its exact GitHub folder URL: https://github.com/${source.owner}/${source.repository}/tree/${sourceCommit}/${exactPath}`,
+      });
+    }
+  }
   if (candidates.length === 0) {
     throw new HTTPException(422, { message: "No Skill folder with SKILL.md was found" });
   }
@@ -332,13 +407,22 @@ async function mapConcurrent<Input, Output>(
 ): Promise<Output[]> {
   const output = new Array<Output>(values.length);
   let next = 0;
+  let failed = false;
   await Promise.all(
     Array.from({ length: Math.min(concurrency, values.length) }, async () => {
       for (;;) {
+        if (failed) return;
         const index = next;
         next += 1;
         if (index >= values.length) return;
-        output[index] = await map(values[index]!);
+        try {
+          output[index] = await map(values[index]!);
+        } catch (error) {
+          // Let existing reads settle, but do not launch further provider calls
+          // after any peer detects a failed request or an exceeded byte budget.
+          failed = true;
+          throw error;
+        }
       }
     }),
   );