kennel 0.2.1 → 0.2.3

package/kernel/packages/api/src/server/folder-metadata-plugin.ts

@@ -0,0 +1,1758 @@
+import { createHash } from "node:crypto";
+import { sendContract, validateQuery } from "./contracts";
+import { realpathSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import type { ServerResponse } from "node:http";
+import type { ApiHost } from "./host";
+import { markdownMetadata } from "@raggle-ai/markdown";
+import { readFolder } from "@raggle-ai/markdown/node";
+import { execFile } from "node:child_process";
+import { sameOrigin } from "@raggle-ai/folder-plugin/endpoint";
+import { parse as parseYaml } from "yaml";
+
+import type { FolderPluginServer } from "@raggle-ai/folder-plugin/server";
+import type { LocalMarkdownFileSummary, LocalProject } from "@raggle-ai/local";
+import type { MailApiContext, MailPreviewer } from "@raggle-ai/mail/api";
+import type { FolderSkill } from "@raggle-ai/ui/lib/folder-activity";
+import { runApiRoute } from "@raggle-ai/folder-plugin/endpoint";
+import { FolderPluginFailure } from "@raggle-ai/folder-plugin/server";
+import { folderWorkspace } from "@raggle-ai/schemas/workspace";
+import { createSchemaCollectionServer } from "@raggle-ai/schemas/server";
+import local from "@raggle-ai/local";
+import { handleMailApiRoutes } from "@raggle-ai/mail/api";
+import { handleTasksApiRoutes } from "@raggle-ai/tasks/api";
+import {
+  listFolderSessions,
+  readSessionTranscript,
+} from "@raggle-ai/session-finding";
+
+import { loadEntityWorkspace } from "./entity-folder.js";
+import { documentEditRoute } from "./api/document-edit";
+import { createAgentFileRoute } from "./api/create-agent-file";
+import { openPathRoute } from "./api/open-path";
+import { folderWebsite } from "./folder-favicon.js";
+import { folderIcon, workspaceBreadcrumbIcons } from "./folder-icons.js";
+import { faviconService } from "@raggle-ai/schemas/favicon";
+import {
+  configuredFolderServerRegistry,
+  folderServerRegistryAsync,
+  type FolderPluginRegistryConfig,
+} from "./plugins.js";
+import { createProjectDiscovery } from "./project-discovery";
+import {
+  createLinkedFolderDiscovery,
+  type LinkedFolderLoader,
+} from "./linked-folder-discovery";
+import {
+  mediaRawMime,
+  previewKind,
+  previewRawMime,
+  previewTextKind,
+} from "@raggle-ai/kennel-kinds";
+
+const {
+  applyProjectFavorites,
+  buildProjectCatalog,
+  buildProjectSearchIndex,
+  catalogProjectToLocalProject,
+  discoverProjectIcon,
+  discoverProjectsUnderFolder,
+  listLocalMarkdownFiles,
+  projectRepositoryAccessory,
+  projectSubtitle,
+  projectTitle,
+  readRaggleUserSettings,
+  searchProjectIndex,
+  sortProjectList,
+} = local;
+
+type SkillSchema = {
+  description?: unknown;
+};
+
+function skillDescription(content: string) {
+  if (!content.startsWith("---\n")) return undefined;
+  const end = content.indexOf("\n---", 4);
+  if (end < 0) return undefined;
+  const schema = parseYaml(content.slice(4, end)) as SkillSchema;
+  return typeof schema.description === "string"
+    ? schema.description
+    : undefined;
+}
+
+function skillSource(folder: string, root: string): FolderSkill["source"] {
+  if (root === folder) return "local";
+  if (root.startsWith(resolve(folder, ".gtl") + sep)) return "local";
+  return "global";
+}
+
+type IconAsset = {
+  mediaType: "image/jpeg" | "image/png";
+  source: "local" | "favicon";
+  url: string;
+};
+
+type ProjectWithIcon = {
+  iconAssetKey?: string;
+  worktree: string;
+};
+
+const maxIconBytes = 512 * 1024;
+const iconTypes = new Map<string, "image/jpeg" | "image/png">([
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".png", "image/png"],
+]);
+const iconExtensions = new Map<"image/jpeg" | "image/png", string>([
+  ["image/jpeg", "jpg"],
+  ["image/png", "png"],
+]);
+const searchIconTypes = new Map<string, string>([
+  [".gif", "image/gif"],
+  [".ico", "image/x-icon"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".png", "image/png"],
+  [".svg", "image/svg+xml"],
+  [".webp", "image/webp"],
+]);
+
+type SessionFinding = {
+  listFolderSessions: typeof listFolderSessions;
+  readSessionTranscript: typeof readSessionTranscript;
+};
+
+export type FolderMetadataPluginOptions = {
+  viewerName?: string;
+  restrictToRoot?: boolean;
+  root: string;
+  sessionFinding?: SessionFinding;
+  mailPreviewer?: MailPreviewer;
+  /**
+   * Inject a MailOS service (tests only). Defaults to a real subprocess
+   * service resolved from PATH.
+   */
+  mailos?: MailApiContext["mailos"];
+  /**
+   * Override MailOS mail directory. Intended for tests.
+   * Defaults to ~/.email/drafts.
+   */
+  mailDir?: string;
+  /** Override the home directory used for Agent global files. Intended for tests. */
+  agentsHomeDir?: string;
+  /** Override isolated linked-project discovery, for tests. */
+  linkedFolderLoader?: LinkedFolderLoader;
+  /**
+   * Serve an explicitly remote address (0.0.0.0/LAN). Disables server host
+   * actions (open in default app) and ACP live sessions; the plugin reports
+   * a capability surface the client can render against.
+   */
+  remoteAccess?: boolean;
+  /**
+   * Single-file pop lock (`kennel pop <file>`): document reads (and metadata
+   * file listings) resolve only this one file; siblings are not served.
+   */
+  lockedFile?: string;
+};
+
+type LocalProjectSearchCache = {
+  index: ReturnType<typeof buildProjectSearchIndex<LocalProject>>;
+  loadedAt: number;
+};
+
+const projectSearchCacheMs = 5_000;
+
+const metadataExtensions = new Set([
+  ".html",
+  ".jpeg",
+  ".jpg",
+  ".json",
+  ".md",
+  ".png",
+  ".rtf",
+  ".svg",
+  ".txt",
+]);
+
+function metadataFile(path: string, root: string) {
+  const candidate = relative(root, path);
+  if (!candidate || candidate.startsWith("..") || isAbsolute(candidate))
+    return false;
+  const parts = candidate.split(sep);
+  if (parts.some((part) => part === "node_modules")) return false;
+  return metadataExtensions.has(extname(candidate).toLowerCase());
+}
+
+async function configuredAiInputModule(folder: string) {
+  const config = folderWorkspace(folder).config as {
+    aiInput?: { module?: unknown };
+  };
+  const module = config.aiInput?.module;
+  return typeof module === "string" && module.trim() ? module.trim() : null;
+}
+
+function label(value: string) {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+function folderPath(value: string | null, root: string, lockedRoot?: string) {
+  const folder = realpathSync(resolve(value ?? root));
+  if (!lockedRoot) return folder;
+  const path = relative(lockedRoot, folder);
+  if (!path || (!path.startsWith("..") && !isAbsolute(path))) return folder;
+  throw new Error(`Folder is outside the viewer root: ${folder}`);
+}
+
+function openPathHref(path: string) {
+  const url = new URL("/api/open-path", "http://127.0.0.1");
+  url.searchParams.set("path", path);
+  return `${url.pathname}${url.search}`;
+}
+
+const loopbackServerHosts = new Set([
+  "127.0.0.1",
+  "::1",
+  "localhost",
+  undefined,
+  false,
+] as const);
+
+export function isLoopbackServerHost(host: unknown): boolean {
+  if (host === undefined || host === false) return true;
+  if (typeof host !== "string") return false;
+  return (
+    loopbackServerHosts.has(host as "localhost") ||
+    host.startsWith("127.") ||
+    host === "::ffff:127.0.0.1"
+  );
+}
+
+/**
+ * DNS-rebinding guard for the API middleware. Loopback aliases always pass;
+ * remote servers additionally accept IP literals, `.local` mDNS names, and
+ * hosts from the environment allowlist (`KENNEL_VIEWER_HOSTS`). Arbitrary
+ * domain Host headers are rejected before any data is served.
+ */
+export function apiHostAllowed(
+  value: string | undefined,
+  remote: boolean,
+): boolean {
+  // A request without a Host header is not a browser (curl, tests, bots):
+  // DNS-rebinding protection targets browser requests, which always send
+  // Host, so missing-host requests stay allowed. Arbitrary domain Host
+  // headers are still rejected before any data is served.
+  if (!value) return true;
+  let hostname = value;
+  try {
+    const parsed = new URL(
+      hostname.includes("://") ? hostname : `http://${hostname}`,
+    );
+    hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  } catch {
+    return false;
+  }
+  if (isLoopbackServerHost(hostname)) return true;
+  if (!remote) return false;
+  if (/^[\d.]+$/.test(hostname) || hostname.includes(":")) return true;
+  if (hostname.endsWith(".local") || !hostname.includes(".")) return true;
+  const allowlist = (process.env.KENNEL_VIEWER_HOSTS ?? "")
+    .split(",")
+    .map((host) => host.trim().toLowerCase())
+    .filter(Boolean);
+  return allowlist.includes(hostname);
+}
+
+function assetKey(value: Buffer) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function encodeBase64Url(value: string) {
+  return Buffer.from(value, "utf8")
+    .toString("base64")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+function decodeBase64Url(value: string) {
+  const padded = `${value}${"=".repeat((4 - (value.length % 4)) % 4)}`;
+  return Buffer.from(
+    padded.replaceAll("-", "+").replaceAll("_", "/"),
+    "base64",
+  ).toString("utf8");
+}
+
+function iconUrl(
+  folder: string,
+  hash: string,
+  mediaType: IconAsset["mediaType"],
+) {
+  return `/api/folders/${encodeBase64Url(folder)}/assets/${hash}.${iconExtensions.get(mediaType)}`;
+}
+
+async function searchIconDataUrl(icon: string | undefined) {
+  if (!icon) return undefined;
+  if (icon.startsWith("data:")) return icon;
+
+  const mediaType = searchIconTypes.get(extname(icon).toLowerCase());
+  if (!mediaType) return undefined;
+
+  const details = await stat(icon).catch(() => undefined);
+  if (!details?.size || details.size > maxIconBytes) return undefined;
+
+  return `data:${mediaType};base64,${(await readFile(icon)).toString("base64")}`;
+}
+
+async function iconWithFaviconFallback(
+  folder: string,
+  assets: Record<string, IconAsset>,
+  assetFiles: Map<string, { mediaType: IconAsset["mediaType"]; path: string }>,
+) {
+  return folderIcon(folder, assets, assetFiles, async (folderName) => {
+    if (process.env.KENNEL_EXTERNAL_ICONS !== "1") return undefined;
+    const host = await folderWebsite(folderName);
+    if (!host) return undefined;
+    const key = `favicon:${host}`;
+    assets[key] = {
+      mediaType: "image/png",
+      source: "favicon",
+      url: `/api/folder-favicon?path=${encodeURIComponent(folderName)}&host=${encodeURIComponent(host)}`,
+    };
+    return key;
+  });
+}
+
+async function hydrateAssets(
+  metadata: {
+    folder: string;
+    projects?: { items: ProjectWithIcon[] };
+  },
+  assetFiles: Map<string, { mediaType: IconAsset["mediaType"]; path: string }>,
+) {
+  const assets: Record<string, IconAsset> = {};
+  const projects = metadata.projects?.items ?? [];
+  const [iconAssetKey, projectItems] = await Promise.all([
+    iconWithFaviconFallback(metadata.folder, assets, assetFiles),
+    Promise.all(
+      projects.map(async (project) => ({
+        ...project,
+        iconAssetKey: await iconWithFaviconFallback(
+          project.worktree,
+          assets,
+          assetFiles,
+        ),
+      })),
+    ),
+  ]);
+  return {
+    assets,
+    iconAssetKey,
+    projects: { items: projectItems },
+  };
+}
+
+function unique(values: string[]) {
+  return [...new Set(values)];
+}
+
+async function existingDirectory(path: string) {
+  const details = await stat(path).catch(() => undefined);
+  return details?.isDirectory() ? path : undefined;
+}
+
+function metadataPaths(metadata: {
+  files?: { items: Array<{ path?: string; relativePath?: string }> };
+}) {
+  return (metadata.files?.items ?? [])
+    .flatMap((file) => [file.path, file.relativePath])
+    .filter((path): path is string => Boolean(path));
+}
+
+function ancestorFolders(folder: string) {
+  const folders = [];
+  for (
+    let current = folder;
+    dirname(current) !== current;
+    current = dirname(current)
+  ) {
+    folders.push(current);
+  }
+  return folders;
+}
+
+async function linkedSkillRoots(
+  folder: string,
+  metadata: {
+    files?: { items: Array<{ path?: string; relativePath?: string }> };
+  },
+) {
+  const gtlNames = metadataPaths(metadata)
+    .map((path) => path.split(/[\\/]\.gtl[\\/]/)[1])
+    .filter((path): path is string => Boolean(path))
+    .map((path) => path.split(/[\\/]/)[0])
+    .filter((name): name is string => Boolean(name));
+  const gtlRoots = gtlNames.flatMap((name) => [
+    resolve(folder, ".gtl", name),
+    ...ancestorFolders(folder).map((ancestor) => resolve(ancestor, name)),
+  ]);
+
+  const name = folder
+    .replace(/[\\/]+$/, "")
+    .split(/[\\/]/)
+    .at(-1);
+  const siblingIndex = name
+    ? [
+        resolve(dirname(folder), `${name}-index`),
+        resolve(dirname(dirname(folder)), `${name}-index`),
+      ]
+    : [];
+  const roots = await Promise.all(
+    unique([...gtlRoots, ...siblingIndex]).map(existingDirectory),
+  );
+  return roots.filter((path): path is string => Boolean(path));
+}
+
+async function listFolderSkills(
+  folder: string,
+  metadata: {
+    files?: { items: Array<{ path?: string; relativePath?: string }> };
+  },
+) {
+  const roots = unique([folder, ...(await linkedSkillRoots(folder, metadata))]);
+  const skills = await Promise.all(
+    roots.map(async (root) => {
+      const skillsFolder = resolve(root, ".agents", "skills");
+      const entries = await readdir(skillsFolder, {
+        withFileTypes: true,
+      }).catch(() => []);
+      return (
+        await Promise.all(
+          entries
+            .filter(
+              (entry) => entry.isDirectory() && !entry.name.startsWith("."),
+            )
+            .map(async (entry) => {
+              const path = resolve(skillsFolder, entry.name);
+              const skillPath = resolve(path, "SKILL.md");
+              const details = await stat(skillPath).catch(() => undefined);
+              if (!details?.isFile()) return undefined;
+              const content = await readFile(skillPath, "utf8").catch(() => "");
+              return {
+                description: skillDescription(content),
+                name: label(entry.name),
+                openHref: openPathHref(path),
+                relativePath: relative(root, path),
+                source: skillSource(folder, root),
+              };
+            }),
+        )
+      ).filter((skill) => skill);
+    }),
+  );
+  return unique(skills.flat().map((skill) => JSON.stringify(skill)))
+    .map((skill) => JSON.parse(skill) as FolderSkill)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function isMachineRoot(folder: string) {
+  return folder === homedir() || dirname(folder) === folder;
+}
+
+async function shallowMetadata(folder: string) {
+  const entries = await readdir(folder, { withFileTypes: true });
+  const visible = entries.filter(
+    (entry) => !entry.name.startsWith(".") && entry.name !== "node_modules",
+  );
+  const files = await Promise.all(
+    visible
+      .filter(
+        (entry) =>
+          entry.isFile() &&
+          [".markdown", ".md"].includes(extname(entry.name).toLowerCase()),
+      )
+      .map(async (entry) => {
+        const path = resolve(folder, entry.name);
+        const details = await stat(path);
+        const content = await readFile(path, "utf8").catch(() => "");
+        const title = markdownMetadata(content).title;
+        return {
+          activityAt: details.mtimeMs,
+          localEditAt: details.mtimeMs,
+          name: title ?? entry.name,
+          openHref: openPathHref(path),
+          path,
+          relativePath: entry.name,
+          size: details.size,
+        };
+      }),
+  );
+  const projects = visible
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      id: createHash("sha1").update(resolve(folder, entry.name)).digest("hex"),
+      name: entry.name,
+      relativePath: entry.name,
+      worktree: resolve(folder, entry.name),
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    changes: { items: [] },
+    files: {
+      items: files.sort((left, right) => right.activityAt - left.activityAt),
+    },
+    folder,
+    instructions: { items: [] },
+    projects: { items: projects },
+    schemaVersion: 3 as const,
+    sessions: { items: [] },
+    skills: { items: [] },
+  };
+}
+
+async function loadFolderData(folder: string) {
+  const [files, projects] = await Promise.all([
+    listLocalMarkdownFiles({ folder, limit: 200 }),
+    discoverProjectsUnderFolder({ folder }),
+  ]);
+  return {
+    files: { items: files },
+    folder,
+    projects: {
+      items: projects.map((project) => ({
+        id: project.id,
+        worktree: project.worktree,
+        name: project.name ?? basename(project.worktree),
+        relativePath: relative(folder, project.worktree),
+      })),
+    },
+  };
+}
+
+async function notesFiles(
+  folder: string,
+  files: LocalMarkdownFileSummary[],
+  origin?: string,
+) {
+  return {
+    items: await Promise.all(
+      files.map(async (file) => {
+        const path =
+          file.path ??
+          (file.relativePath ? resolve(folder, file.relativePath) : undefined);
+        if (!path) return origin ? { ...file, folder: origin } : file;
+        const content = [".markdown", ".md"].includes(
+          extname(path).toLowerCase(),
+        )
+          ? await readFile(path, "utf8").catch(() => "")
+          : "";
+        const title = content ? markdownMetadata(content).title : undefined;
+        return {
+          ...file,
+          folder: origin,
+          name: title ?? file.name,
+          openHref: openPathHref(path),
+        };
+      }),
+    ),
+  };
+}
+
+async function localProjectSearchCache(
+  cache: LocalProjectSearchCache | undefined,
+) {
+  if (cache && Date.now() - cache.loadedAt < projectSearchCacheMs) return cache;
+
+  const settings = readRaggleUserSettings();
+  const projects = applyProjectFavorites(
+    (
+      await buildProjectCatalog({
+        cloneSources: settings.cloneDirectories.map((cloneDirectory) => ({
+          cloneDirectory,
+        })),
+        localRepositoryLinks: settings.localRepositoryLinks,
+        projectRoots: settings.projectDirectories,
+        repositoryLocations: settings.repositoryLocations,
+        schemaScanRoots: settings.projectDirectories,
+      })
+    ).map(catalogProjectToLocalProject),
+    settings.favoriteProjects,
+  );
+  const ordered = sortProjectList(projects, "recentActivity");
+  return {
+    index: buildProjectSearchIndex(ordered),
+    loadedAt: Date.now(),
+  };
+}
+
+/**
+ * Resolves a media file (image/video/audio) referenced by a document. Mirrors
+ * `documentTarget` containment: the target must live inside the folder, must
+ * be a regular file, and must have a servable media type. Unlike documents,
+ * no preview-kind gating — any media-typed file inside the folder is fair
+ * game, since notes legitimately reference assets in sibling directories.
+ */
+function mediaTarget(
+  folder: string,
+  file: string | null,
+  lockedTarget?: string,
+) {
+  if (!file) return undefined;
+  const rootReal = realpathSync(resolve(folder));
+  const path = resolve(folder, file);
+  let pathReal: string;
+  try {
+    pathReal = realpathSync(path);
+  } catch {
+    // Missing, unreadable, or dangling-symlink targets are not media.
+    return undefined;
+  }
+  const rel = relative(rootReal, pathReal);
+  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  // Single-file pop lock: only the popped file is previewable.
+  if (lockedTarget && pathReal !== lockedTarget) return undefined;
+  const mime = mediaRawMime(pathReal);
+  if (!mime) return undefined;
+  return { mime, path: pathReal, root: rootReal };
+}
+
+/** Parses a single `bytes=start-end` Range header into a satisfiable slice. */
+export function parseByteRange(
+  header: string | undefined,
+  size: number,
+): { end: number; start: number } | "invalid" | undefined {
+  if (!header) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!match) return undefined;
+  const [, rawStart, rawEnd] = match;
+  if (!rawStart && !rawEnd) return undefined;
+  if (!rawStart) {
+    // Suffix range: last N bytes.
+    const length = Number(rawEnd);
+    if (!length) return "invalid";
+    return { end: size - 1, start: Math.max(0, size - length) };
+  }
+  const start = Number(rawStart);
+  const end = rawEnd ? Math.min(Number(rawEnd), size - 1) : size - 1;
+  if (start >= size || start > end) return "invalid";
+  return { end, start };
+}
+
+function documentError(response: ServerResponse) {
+  response.writeHead(404, {
+    "Content-Type": "application/json; charset=utf-8",
+  });
+  response.end(JSON.stringify({ error: "Document not found." }));
+}
+
+function documentTarget(
+  folder: string,
+  file: string | null,
+  lockedTarget?: string,
+) {
+  if (!file) return undefined;
+  const rootReal = realpathSync(resolve(folder));
+  const path = resolve(folder, file);
+  let pathReal: string;
+  try {
+    pathReal = realpathSync(path);
+  } catch {
+    // Missing, unreadable, or dangling-symlink targets are not documents.
+    return undefined;
+  }
+  const rel = relative(rootReal, pathReal);
+  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  // Single-file pop lock: only the popped file is previewable.
+  if (lockedTarget && pathReal !== lockedTarget) return undefined;
+  const kind = previewKind(pathReal);
+  if (!kind) return undefined;
+  return { kind, path: pathReal, root: rootReal };
+}
+
+function documentEtag(details: { mtimeMs: number; size: number }) {
+  return `"${createHash("sha256")
+    .update(`${details.mtimeMs}:${details.size}`)
+    .digest("hex")}"`;
+}
+
+async function projectSearchItem(
+  project: LocalProject,
+  match?: {
+    matchedField: string;
+    matchTier: string;
+    score: number;
+  },
+) {
+  const icon =
+    (await searchIconDataUrl(project.icon)) ??
+    (await searchIconDataUrl(discoverProjectIcon(project.worktree)));
+
+  return {
+    id: project.id,
+    icon,
+    latestSessionTitle: project.latestSessionTitle,
+    matchedField: match?.matchedField ?? "none",
+    matchTier: match?.matchTier ?? "emptyQuery",
+    relativePath: project.relativePath,
+    repositoryLabel: projectRepositoryAccessory(project),
+    score: match?.score ?? 0,
+    subtitle: projectSubtitle(project),
+    title: projectTitle(project.name, project.worktree),
+    worktree: project.worktree,
+  };
+}
+
+const defaultPluginRegistryConfig: FolderPluginRegistryConfig = {
+  plugins: { disable: [], order: [] },
+};
+
+type RawPluginRegistryConfig = {
+  plugins?: {
+    disable?: unknown;
+    order?: unknown;
+  };
+};
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function parsePluginRegistryConfig(content: string): FolderPluginRegistryConfig {
+  const parsed = JSON.parse(content) as unknown;
+  const config: RawPluginRegistryConfig =
+    parsed && typeof parsed === "object"
+      ? (parsed as RawPluginRegistryConfig)
+      : {};
+  return {
+    plugins: {
+      disable: stringArray(config.plugins?.disable),
+      order: stringArray(config.plugins?.order),
+    },
+  };
+}
+
+async function nearestKennelConfig(folder: string) {
+  for (let current = folder; ; current = dirname(current)) {
+    const candidate = resolve(current, "kennel.json");
+    const details = await stat(candidate).catch(() => undefined);
+    if (details?.isFile()) return candidate;
+    if (dirname(current) === current) return undefined;
+  }
+}
+
+async function folderPluginRegistryConfig(
+  folder: string,
+): Promise<FolderPluginRegistryConfig> {
+  const path = await nearestKennelConfig(folder);
+  if (!path) return defaultPluginRegistryConfig;
+  try {
+    return parsePluginRegistryConfig(await readFile(path, "utf8"));
+  } catch {
+    return defaultPluginRegistryConfig;
+  }
+}
+
+function pluginConfigWarnings(
+  registry: Map<string, FolderPluginServer>,
+  config: FolderPluginRegistryConfig,
+) {
+  const ids = unique([...config.plugins.disable, ...config.plugins.order]);
+  return ids
+    .filter((id) => !registry.has(id))
+    .map((id) => `unknown plugin id "${id}" — not bundled in this build`);
+}
+
+async function pluginAvailability(
+  registry: Map<string, FolderPluginServer>,
+  folder: string,
+  linkedFolders: string[],
+  configWarnings: string[] = [],
+) {
+  const items: Array<{
+    count?: number;
+    error?: string;
+    id: string;
+    label: string;
+  }> = [];
+  for (const plugin of registry.values()) {
+    try {
+      const detection = await plugin.detect({
+        folder,
+        linkedFolders,
+      });
+      if (detection.status === "available") {
+        items.push({
+          count: detection.count,
+          id: plugin.id,
+          label: plugin.label,
+        });
+      } else if (detection.status === "error") {
+        // A plugin that found its content file but could not validate it is
+        // still a hit: keep the item visible and flag the problem so the
+        // shell can surface it instead of treating it as absent content.
+        items.push({
+          error: detection.error,
+          id: plugin.id,
+          label: plugin.label,
+        });
+      }
+    } catch {
+      // Isolate plugin detection: a failure hides the item but never blocks
+      // the folder or other plugins.
+    }
+  }
+  return { configWarnings, items };
+}
+
+export function createFolderApi({
+  viewerName = "kennel-core",
+  restrictToRoot = false,
+  root,
+  sessionFinding,
+  mailPreviewer,
+  mailDir,
+  mailos,
+  agentsHomeDir,
+  linkedFolderLoader,
+  remoteAccess = false,
+  lockedFile,
+}: FolderMetadataPluginOptions) {
+  let lockedRoot = restrictToRoot ? realpathSync(root) : undefined;
+  const lockedTarget = lockedFile ? realpathSync(lockedFile) : undefined;
+  const resolveSession = sessionFinding ?? {
+    listFolderSessions,
+    readSessionTranscript,
+  };
+  const basePlugins = folderServerRegistryAsync({
+    mailDir,
+    previewer: mailPreviewer,
+    agentsHomeDir,
+  });
+  const assetFiles = new Map<
+    string,
+    { mediaType: IconAsset["mediaType"]; path: string }
+  >();
+  let projectSearchCache: LocalProjectSearchCache | undefined;
+  const projectDiscovery = createProjectDiscovery();
+  let discoveryChanged = (_folder: string) => {};
+  const linkedDiscovery = createLinkedFolderDiscovery(
+    linkedFolderLoader,
+    (folder) => discoveryChanged(folder),
+  );
+  const linkedState = (folder: string) =>
+    lockedRoot || isMachineRoot(folder)
+      ? { folders: [], status: "ready" as const }
+      : linkedDiscovery.read(folder);
+  const resolveLinkedFolders = (folder: string) =>
+    lockedRoot || isMachineRoot(folder)
+      ? Promise.resolve([])
+      : linkedDiscovery.folders(folder);
+  const favicon = faviconService();
+
+  return {
+    name: "kennel-folder-metadata",
+    close() {
+      linkedDiscovery.close();
+      projectDiscovery.close();
+    },
+    attach(server: ApiHost) {
+      discoveryChanged = (path) =>
+        server.emit({
+          data: { path },
+          event: "kennel:linked-folders-changed",
+          type: "custom",
+        });
+      // Effective remote mode comes from the explicit flag OR the resolved
+      // Vite host (0.0.0.0/true/non-loopback), so a bare `vite dev
+      // --host 0.0.0.0` gets the same restricted surface as the CLI's --lan.
+      const serverHost = server.host;
+      const remote =
+        remoteAccess ||
+        serverHost === true ||
+        (typeof serverHost === "string" && !isLoopbackServerHost(serverHost));
+      if (remote) lockedRoot = lockedRoot ?? realpathSync(root);
+
+      const collectionServer = createSchemaCollectionServer(server, {
+        boundary: lockedRoot,
+        lockedTarget,
+      });
+      const readWorkspace = collectionServer.summaries;
+      const watched = new Set<string>();
+      const contexts = new Set<string>();
+      const watch = (folder: string) => {
+        if (watched.has(folder)) return;
+        watched.add(folder);
+        server.watch(folder);
+      };
+      const refresh = (path: string) => {
+        collectionServer.invalidate(path);
+        if (contexts.has(path))
+          server.emit({
+            data: { path },
+            event: "kennel:workspace-changed",
+            type: "custom",
+          });
+        const folder = [...watched].find((candidate) =>
+          metadataFile(path, candidate),
+        );
+        if (!folder) return;
+        server.emit({
+          data: { path: relative(folder, path) },
+          event: "kennel:metadata-changed",
+          type: "custom",
+        });
+      };
+
+      if (restrictToRoot || remote) watch(root);
+      server.onChange(refresh);
+
+      server.use(async (request, response, next) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (!apiHostAllowed(request.headers.host, remote)) {
+          response.writeHead(403, {
+            "Content-Type": "text/plain; charset=utf-8",
+          });
+          response.end("Untrusted Host header");
+          return;
+        }
+        if (!validateQuery(request, response, url)) return;
+        if (url.pathname === "/api/capabilities") {
+          sendContract(
+            response,
+            url,
+            {
+              acp: !remote,
+              download: true,
+              hostActions: remote ? "none" : "local",
+              local: !remote,
+              viewer: viewerName,
+            },
+            { "Cache-Control": "no-store" },
+          );
+          return;
+        }
+
+        if (url.pathname === "/api/config") {
+          const folder = folderPath(
+            url.searchParams.get("path"),
+            root,
+            lockedRoot,
+          );
+          sendContract(
+            response,
+            url,
+            { aiInputModule: await configuredAiInputModule(folder) },
+            { "Cache-Control": "no-store" },
+          );
+          return;
+        }
+
+        if (url.pathname === "/api/health") {
+          sendContract(
+            response,
+            url,
+            { viewer: viewerName, root, kernelKey: process.env.KENNEL_KERNEL_KEY ?? "core" },
+            { "Cache-Control": "no-store" },
+          );
+          return;
+        }
+        if (url.pathname === "/api/folder-favicon") {
+          const data = await (async () => {
+            if (process.env.KENNEL_EXTERNAL_ICONS !== "1") return undefined;
+            const folder = folderPath(
+              url.searchParams.get("path"),
+              root,
+              lockedRoot,
+            );
+            const host = await folderWebsite(folder);
+            if (!host || host !== url.searchParams.get("host"))
+              return undefined;
+            return favicon(host);
+          })().catch(() => undefined);
+          response.writeHead(data ? 200 : 404, {
+            "Cache-Control": data
+              ? "private, max-age=86400"
+              : "private, max-age=300",
+            "Content-Type": data ? "image/png" : "text/plain; charset=utf-8",
+            "X-Content-Type-Options": "nosniff",
+          });
+          response.end(data ?? "Icon unavailable");
+          return;
+        }
+        const assetMatch =
+          /^\/api\/folders\/([^/]+)\/assets\/([a-f0-9]{64})\.(?:jpg|png)$/.exec(
+            url.pathname,
+          );
+        if (assetMatch) {
+          try {
+            const [, folderId, hash] = assetMatch;
+            if (!folderId || !hash) throw new Error("Asset not found");
+            const folder = folderPath(
+              decodeBase64Url(folderId),
+              root,
+              lockedRoot,
+            );
+            watch(folder);
+            let asset = assetFiles.get(hash);
+            if (!asset) {
+              const assets: Record<string, IconAsset> = {};
+              await iconWithFaviconFallback(folder, assets, assetFiles);
+              asset = assetFiles.get(hash);
+            }
+            if (!asset) {
+              response.writeHead(404, {
+                "Content-Type": "text/plain; charset=utf-8",
+              });
+              response.end("Asset not found");
+              return;
+            }
+            response.writeHead(200, {
+              "Cache-Control": "private, max-age=31536000, immutable",
+              "Content-Type": asset.mediaType,
+              ETag: `"${hash}"`,
+            });
+            response.end(await readFile(asset.path));
+          } catch (error) {
+            response.writeHead(404, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end(
+              error instanceof Error ? error.message : "Asset not found",
+            );
+          }
+          return;
+        }
+        if (
+          remote &&
+          ["/api/project-search", "/api/entities"].includes(url.pathname)
+        ) {
+          response.writeHead(403);
+          response.end("Global discovery is disabled for remote access");
+          return;
+        }
+        if (url.pathname === "/api/project-search") {
+          const query = url.searchParams.get("q")?.trim() ?? "";
+          const cache = await localProjectSearchCache(projectSearchCache);
+          projectSearchCache = cache;
+          const result = searchProjectIndex(cache.index, query, {
+            limit: query ? 40 : 20,
+          });
+          sendContract(
+            response,
+            url,
+            {
+              items: await Promise.all(
+                result.hits.map((hit) => projectSearchItem(hit.project, hit)),
+              ),
+              query,
+              scanned: result.scanned,
+              total: result.total,
+            },
+            { "Cache-Control": "no-store" },
+          );
+          return;
+        }
+        if (url.pathname === "/api/entities") {
+          try {
+            const workspace = await loadEntityWorkspace(
+              url.searchParams.get("root") ?? undefined,
+              url.searchParams.get("q") ?? "",
+              url.searchParams.get("entity"),
+              root,
+            );
+            sendContract(response, url, workspace, {
+              "Cache-Control": "no-store",
+            });
+          } catch (error) {
+            response.writeHead(400, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end(
+              error instanceof Error
+                ? error.message
+                : "Could not load entities",
+            );
+          }
+          return;
+        }
+        if (url.pathname === "/api/document/edit") {
+          if (remote) {
+            response.writeHead(403, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end("Host actions are disabled for remote access");
+            return;
+          }
+          await runApiRoute(request, response, url, documentEditRoute, {
+            lockedFile: lockedTarget,
+            authorize: (folder) => folderPath(folder, root, lockedRoot),
+          });
+          return;
+        }
+        if (url.pathname === "/api/open-folder") {
+          if (remote || request.method !== "POST" || !sameOrigin(request)) {
+            response.writeHead(remote || request.method === "POST" ? 403 : 405);
+            response.end("Folder action not allowed");
+            return;
+          }
+          const folder = folderPath(
+            url.searchParams.get("path"),
+            root,
+            lockedRoot,
+          );
+          const command =
+            process.platform === "darwin"
+              ? "open"
+              : process.platform === "win32"
+                ? "explorer.exe"
+                : "xdg-open";
+          await new Promise<void>((done, fail) =>
+            execFile(command, [folder], (error) =>
+              error ? fail(error) : done(),
+            ),
+          );
+          response.writeHead(204);
+          response.end();
+          return;
+        }
+        if (url.pathname === "/api/documents") {
+          const folder = folderPath(
+            url.searchParams.get("path"),
+            root,
+            lockedRoot,
+          );
+          const target = lockedTarget
+            ? documentTarget(
+                folder,
+                relative(folder, lockedTarget),
+                lockedTarget,
+              )
+            : undefined;
+          const dataset = lockedTarget
+            ? {
+                root: folder,
+                documents: target
+                  ? [
+                      {
+                        path: relative(folder, target.path),
+                        kind: target.kind,
+                        content: previewTextKind(target.kind)
+                          ? await readFile(target.path, "utf8")
+                          : "",
+                      },
+                    ]
+                  : [],
+              }
+            : await readFolder(folder);
+          watch(folder);
+          sendContract(response, url, dataset, { "Cache-Control": "no-store" });
+          return;
+        }
+        if (url.pathname === "/api/document") {
+          try {
+            const folder = folderPath(
+              url.searchParams.get("path"),
+              root,
+              lockedRoot,
+            );
+            const target = documentTarget(
+              folder,
+              url.searchParams.get("file"),
+              lockedTarget,
+            );
+            if (!target) {
+              documentError(response);
+              return;
+            }
+            const details = await stat(target.path);
+            if (!details.isFile()) {
+              documentError(response);
+              return;
+            }
+            const etag = documentEtag(details);
+            if (request.headers["if-none-match"] === etag) {
+              response.writeHead(304, { ETag: etag });
+              response.end();
+              return;
+            }
+            watch(folder);
+            const content = previewTextKind(target.kind)
+              ? await readFile(target.path, "utf8")
+              : "";
+            sendContract(
+              response,
+              url,
+              {
+                content,
+                kind: target.kind,
+                path: relative(target.root, target.path),
+                root: folder,
+                ...(previewTextKind(target.kind)
+                  ? {}
+                  : {
+                      rawUrl: `/api/raw?${new URLSearchParams({
+                        path: folder,
+                        file: relative(target.root, target.path),
+                      })}`,
+                    }),
+              },
+              {
+                "Cache-Control": "private, max-age=0, must-revalidate",
+                ETag: etag,
+              },
+            );
+          } catch (error) {
+            documentError(response);
+          }
+          return;
+        }
+        if (url.pathname === "/api/raw") {
+          try {
+            const folder = folderPath(
+              url.searchParams.get("path"),
+              root,
+              lockedRoot,
+            );
+            const target = documentTarget(
+              folder,
+              url.searchParams.get("file"),
+              lockedTarget,
+            );
+            if (!target) {
+              documentError(response);
+              return;
+            }
+            const details = await stat(target.path);
+            if (!details.isFile()) {
+              documentError(response);
+              return;
+            }
+            const etag = documentEtag(details);
+            if (request.headers["if-none-match"] === etag) {
+              response.writeHead(304, { ETag: etag });
+              response.end();
+              return;
+            }
+            watch(folder);
+            // Active content stays inert from the raw endpoint: HTML download
+            // only as opaque bytes; SVG (scripts allowed in top-level/iframe
+            // navigation) always downloads as an attachment with nosniff.
+            const active =
+              target.kind === "html" ||
+              target.path.toLowerCase().endsWith(".svg");
+            const download = url.searchParams.get("download") === "1" || active;
+            const mime =
+              target.kind === "html"
+                ? "application/octet-stream"
+                : (previewRawMime(target.path) ?? "application/octet-stream");
+            response.writeHead(200, {
+              "Cache-Control": "private, max-age=0, must-revalidate",
+              "Content-Type": mime,
+              ETag: etag,
+              "X-Content-Type-Options": "nosniff",
+              ...(download
+                ? {
+                    "Content-Disposition": `attachment; filename="${basename(target.path)}"`,
+                  }
+                : {}),
+            });
+            response.end(await readFile(target.path));
+          } catch (error) {
+            documentError(response);
+          }
+          return;
+        }
+        if (url.pathname === "/api/media") {
+          try {
+            const folder = folderPath(
+              url.searchParams.get("path"),
+              root,
+              lockedRoot,
+            );
+            const target = mediaTarget(
+              folder,
+              url.searchParams.get("file"),
+              lockedTarget,
+            );
+            if (!target) {
+              documentError(response);
+              return;
+            }
+            const details = await stat(target.path);
+            if (!details.isFile()) {
+              documentError(response);
+              return;
+            }
+            const etag = documentEtag(details);
+            if (request.headers["if-none-match"] === etag) {
+              response.writeHead(304, { ETag: etag });
+              response.end();
+              return;
+            }
+            watch(folder);
+            // Media is read whole and sliced for ranges: clips are small
+            // (single-digit MB) and browsers need 206 support to seek.
+            const data = await readFile(target.path);
+            const baseHeaders = {
+              "Accept-Ranges": "bytes",
+              "Cache-Control": "private, max-age=0, must-revalidate",
+              "Content-Type": target.mime,
+              ETag: etag,
+              "X-Content-Type-Options": "nosniff",
+            };
+            const range = parseByteRange(request.headers.range, data.length);
+            if (range === "invalid") {
+              response.writeHead(416, {
+                ...baseHeaders,
+                "Content-Range": `bytes */${data.length}`,
+              });
+              response.end();
+              return;
+            }
+            if (range) {
+              const slice = data.subarray(range.start, range.end + 1);
+              response.writeHead(206, {
+                ...baseHeaders,
+                "Content-Length": String(slice.length),
+                "Content-Range": `bytes ${range.start}-${range.end}/${data.length}`,
+              });
+              response.end(slice);
+              return;
+            }
+            response.writeHead(200, {
+              ...baseHeaders,
+              "Content-Length": String(data.length),
+            });
+            response.end(data);
+          } catch (error) {
+            documentError(response);
+          }
+          return;
+        }
+        if (url.pathname === "/api/session") {
+          try {
+            const sessionId = url.searchParams.get("sessionId");
+            if (!sessionId) throw new Error("No sessionId parameter");
+            const session =
+              await resolveSession.readSessionTranscript(sessionId);
+            response.writeHead(200, {
+              "Cache-Control": "private, max-age=10, must-revalidate",
+              "Content-Type": "application/json; charset=utf-8",
+            });
+            response.end(JSON.stringify(session));
+          } catch (error) {
+            response.writeHead(404, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end(
+              error instanceof Error ? error.message : "Session not found",
+            );
+          }
+          return;
+        }
+        const pluginMatch = /^\/api\/plugins\/([^/]+)$/.exec(url.pathname);
+        if (pluginMatch) {
+          try {
+            const pluginId = pluginMatch[1];
+            if (!pluginId) throw new Error("Unknown plugin");
+            const folder = folderPath(
+              url.searchParams.get("path"),
+              root,
+              lockedRoot,
+            );
+            const pluginConfig = await folderPluginRegistryConfig(folder);
+            const plugins = configuredFolderServerRegistry(
+              await basePlugins,
+              pluginConfig,
+            );
+            const plugin = plugins.get(pluginId);
+            if (!plugin) throw new Error("Unknown plugin");
+            watch(folder);
+            const subpath = url.searchParams.get("subpath") ?? "";
+            // Local content never waits for optional linked-project discovery.
+            if (
+              !lockedRoot &&
+              !isMachineRoot(folder) &&
+              request.headers["x-kennel-retry-linked"] === "1"
+            )
+              linkedDiscovery.retry(folder);
+            const discovery =
+              pluginId === "agents" || pluginId === "tasks"
+                ? linkedState(folder)
+                : undefined;
+            const result = await plugin.handle(
+              {
+                folder,
+                linkedFolders: discovery?.folders ?? [],
+              },
+              subpath,
+            );
+            if (result.kind === "unavailable") {
+              response.writeHead(200, {
+                "Cache-Control": "private, max-age=0, must-revalidate",
+                "Content-Type": "application/json; charset=utf-8",
+              });
+              response.end(
+                JSON.stringify({
+                  folder,
+                  plugin: pluginId,
+                  status: "unavailable",
+                  ...(discovery ? { linkedStatus: discovery.status } : {}),
+                }),
+              );
+              return;
+            }
+            response.writeHead(200, {
+              "Cache-Control": "private, max-age=0, must-revalidate",
+              "Content-Type": "application/json; charset=utf-8",
+            });
+            const data = result.data as Record<string, unknown>;
+            response.end(
+              JSON.stringify({
+                folder,
+                plugin: pluginId,
+                ...data,
+                ...(discovery ? { linkedStatus: discovery.status } : {}),
+              }),
+            );
+          } catch (error) {
+            if (error instanceof FolderPluginFailure) {
+              response.writeHead(500, {
+                "Content-Type": "text/plain; charset=utf-8",
+              });
+              response.end(error.message);
+              return;
+            }
+            response.writeHead(404, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end(
+              error instanceof Error ? error.message : "Plugin not found",
+            );
+          }
+          return;
+        }
+        if (
+          await handleMailApiRoutes(request, response, {
+            authorizeFolder: (value) => folderPath(value, root, lockedRoot),
+            mailDir,
+            mailos,
+            mailPreviewer,
+            watch,
+          })
+        )
+          return;
+        if (
+          await handleTasksApiRoutes(request, response, {
+            authorizeFolder: (value) => folderPath(value, root, lockedRoot),
+            readOnly: remote,
+            watch,
+          })
+        )
+          return;
+        if (url.pathname === "/api/create-agent-file") {
+          if (remote) {
+            response.writeHead(403, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end("Host actions are disabled for remote access");
+            return;
+          }
+          await runApiRoute(request, response, url, createAgentFileRoute, {
+            resolve: (value: string | null) =>
+              folderPath(value, root, lockedRoot),
+          });
+          return;
+        }
+        if (url.pathname === "/api/open-path") {
+          if (remote) {
+            response.writeHead(403, {
+              "Content-Type": "text/plain; charset=utf-8",
+            });
+            response.end("Host actions are disabled for remote access");
+            return;
+          }
+          await runApiRoute(request, response, url, openPathRoute, {
+            resolve: (value: string | null) =>
+              folderPath(value, root, lockedRoot),
+          });
+          return;
+        }
+        if (url.pathname !== "/api/metadata") {
+          next();
+          return;
+        }
+
+        try {
+          const part = url.searchParams.get("part");
+          const folder = folderPath(
+            url.searchParams.get("path"),
+            root,
+            lockedRoot,
+          );
+          if (lockedTarget && part !== "workspace") {
+            // Single-file pop lock: workspace stays (config resolution, no
+            // file contents); every other metadata part returns a folder-only
+            // body so siblings are never listed or summarized.
+            if (part === "collections") {
+              response.writeHead(404, { "Content-Type": "application/json" });
+              response.end(JSON.stringify({ error: "Collection not found" }));
+              return;
+            }
+            sendContract(
+              response,
+              url,
+              {
+                assets: {},
+                files: { items: [] },
+                folder,
+                projects: { items: [] },
+                sessions: { items: [] },
+                skills: { items: [] },
+                workspace: await readWorkspace(folder),
+              },
+              { "Cache-Control": "private, max-age=0, must-revalidate" },
+            );
+            return;
+          }
+          if (part === "workspace") {
+            const workspace = await readWorkspace(folder);
+            workspace.breadcrumbs = await workspaceBreadcrumbIcons(
+              workspace.breadcrumbs ?? [],
+              assetFiles,
+            );
+            const files = [
+              workspace.configPath,
+              resolve(workspace.root, "raggle.json"),
+            ].filter((path): path is string => Boolean(path));
+            for (const path of files) contexts.add(path);
+            server.watch(files);
+            sendContract(
+              response,
+              url,
+              { folder, workspace },
+              { "Cache-Control": "private, max-age=0, must-revalidate" },
+            );
+            return;
+          }
+          watch(folder);
+          if (part === "collections") {
+            const sort = url.searchParams.get("sort");
+            await collectionServer.handleMetadataPart({
+              folder,
+              id: url.searchParams.get("id"),
+              response,
+              send: (body, headers) =>
+                sendContract(response, url, body, headers),
+              sort: sort === "alpha" || sort === "recent" ? sort : undefined,
+              url,
+            });
+            return;
+          }
+
+          // Sessions functionality is commented out (can be re-enabled).
+          // if (part === "sessions") {
+          //   const sessions = isMachineRoot(folder)
+          //     ? { items: [] }
+          //     : await resolveSession.listFolderSessions({ folder, limit: 100 })
+          //   response.writeHead(200, {
+          //     "Cache-Control": "private, max-age=0, must-revalidate",
+          //     "Content-Type": "application/json; charset=utf-8",
+          //   })
+          //   response.end(JSON.stringify({ folder, sessions }))
+          //   return
+          // }
+
+          const machine = isMachineRoot(folder);
+
+          if (part === "notes") {
+            // The viewer requests local and linked notes independently so slow
+            // repository discovery cannot hold the local list hostage. Omitted
+            // scope preserves the combined API response for existing clients.
+            const scope = url.searchParams.get("notesScope");
+            const localFiles =
+              scope === "linked"
+                ? Promise.resolve({ items: [] })
+                : (machine
+                    ? shallowMetadata(folder).then((data) => data.files.items)
+                    : listLocalMarkdownFiles({ folder, limit: 200 })
+                  ).then((files) => notesFiles(folder, files));
+            const linkedFiles = async () => {
+              if (scope === "local" || machine || lockedRoot) return [];
+              if (request.headers["x-kennel-retry-linked"] === "1")
+                linkedDiscovery.retry(folder);
+              const linkedFolders = await resolveLinkedFolders(folder);
+              if (linkedState(folder).status === "error")
+                throw new Error(
+                  "Linked notes discovery failed. Retry to try again.",
+                );
+              return Promise.all(
+                linkedFolders.map(async (linkedFolder) => {
+                  watch(linkedFolder);
+                  return notesFiles(
+                    linkedFolder,
+                    await listLocalMarkdownFiles({
+                      folder: linkedFolder,
+                      limit: 200,
+                    }),
+                    linkedFolder,
+                  );
+                }),
+              );
+            };
+            const [files, linked] = await Promise.all([
+              localFiles,
+              linkedFiles(),
+            ]);
+            sendContract(
+              response,
+              url,
+              {
+                files: {
+                  items: [
+                    ...files.items,
+                    ...linked.flatMap((group) => group.items),
+                  ],
+                },
+                folder,
+              },
+              { "Cache-Control": "private, max-age=0, must-revalidate" },
+            );
+            return;
+          }
+
+          // Plugin availability is isolated from core discovery: a plugin
+          // failure hides its own item but never blocks Notes or other plugins.
+          if (part === "plugins") {
+            const pluginConfig = await folderPluginRegistryConfig(folder);
+            const registry = await basePlugins;
+            const plugins = configuredFolderServerRegistry(
+              registry,
+              pluginConfig,
+            );
+            const configWarnings = pluginConfigWarnings(
+              registry,
+              pluginConfig,
+            );
+            sendContract(
+              response,
+              url,
+              {
+                configWarnings,
+                folder,
+                plugins: await pluginAvailability(
+                  plugins,
+                  folder,
+                  lockedRoot || isMachineRoot(folder)
+                    ? []
+                    : linkedDiscovery.peek(folder).folders,
+                  configWarnings,
+                ),
+              },
+              { "Cache-Control": "private, max-age=0, must-revalidate" },
+            );
+            return;
+          }
+
+          const respond = (body: unknown) =>
+            sendContract(response, url, body, {
+              "Cache-Control": "private, max-age=0, must-revalidate",
+            });
+
+          if (part === "identity") {
+            const hydrated = await hydrateAssets({ folder }, assetFiles);
+            respond({
+              assets: hydrated.assets,
+              folder,
+              iconAssetKey: hydrated.iconAssetKey,
+            });
+            return;
+          }
+
+          if (part === "discovery") {
+            // Navigation needs projects, not a recursive Markdown inventory.
+            const controller = new AbortController();
+            const cancel = () => controller.abort();
+            response.once("close", cancel);
+            let projects;
+            try {
+              projects = machine
+                ? (await shallowMetadata(folder)).projects.items
+                : await projectDiscovery.read(folder, controller.signal);
+            } finally {
+              response.off("close", cancel);
+            }
+            const [hydrated, workspace] = await Promise.all([
+              hydrateAssets(
+                { folder, projects: { items: projects } },
+                assetFiles,
+              ),
+              readWorkspace(folder),
+            ]);
+            workspace.breadcrumbs = await workspaceBreadcrumbIcons(
+              workspace.breadcrumbs ?? [],
+              assetFiles,
+              hydrated.assets,
+            );
+            respond({
+              assets: hydrated.assets,
+              folder,
+              projects: hydrated.projects,
+              workspace,
+            });
+            return;
+          }
+
+          const metadata = machine
+            ? await shallowMetadata(folder)
+            : await loadFolderData(folder);
+
+          if (part === "skills") {
+            respond({
+              folder: metadata.folder,
+              skills: {
+                items: await listFolderSkills(metadata.folder, metadata),
+              },
+            });
+            return;
+          }
+
+          const [assets, skills] = await Promise.all([
+            hydrateAssets(metadata, assetFiles),
+            listFolderSkills(metadata.folder, metadata),
+          ]);
+          const body = {
+            ...metadata,
+            ...assets,
+            sessions: { items: [] },
+            files: await notesFiles(metadata.folder, metadata.files.items),
+            skills: { items: skills },
+          };
+          respond(body);
+        } catch (error) {
+          response.writeHead(404, {
+            "Content-Type": "text/plain; charset=utf-8",
+          });
+          response.end(
+            error instanceof Error ? error.message : "Folder activity failed",
+          );
+        }
+      });
+    },
+  };
+}