mulmoclaude 0.6.2 → 0.6.3

package/server/agent/mcpPreflight.ts

@@ -0,0 +1,185 @@
+// Boot-time + per-agent-run preflight for external MCP servers
+// (#1352).
+//
+// Built-in MCP-only tools have always done this via
+// `isMcpToolEnabled` + `logMcpStatus` (server/index.ts:750) — when an
+// env var listed in `requiredEnv` is unset, the tool drops out of
+// the list and the operator sees an info log explaining why. External
+// MCP servers (the `mcp.json` ones — Notion / GitHub / Linear /…)
+// had no equivalent, so a half-configured catalog entry would still
+// spawn a subprocess and every tool call would fail silently with
+// 401. This module is the parity fix.
+//
+// The catalog (`src/config/mcpCatalog.ts`) declares which config
+// fields are `required: true`. The user's saved `mcp.json` holds
+// resolved values. Cross-referencing the two tells us which servers
+// are ready to boot and which should be excluded from the config
+// handed to Claude Code.
+
+import type { McpServerSpec } from "../system/config.js";
+import { findCatalogEntry, requiredKeysOf, type McpCatalogEntry } from "../../src/config/mcpCatalog.js";
+import { log } from "../system/logger/index.js";
+
+export interface McpPreflightResult {
+  /** Servers that passed preflight, keyed by the same id used in
+   *  the input. Safe to pass straight into `prepareUserServers` /
+   *  `buildMcpConfig`. */
+  ready: Record<string, McpServerSpec>;
+  /** Servers excluded by preflight, with the catalog field keys
+   *  whose values were unset / unresolved. */
+  skipped: { serverId: string; missing: string[] }[];
+}
+
+const PLACEHOLDER_PATTERN = /\$\{([A-Z0-9_]+)\}/g;
+const SINGLE_PLACEHOLDER = /^\$\{([A-Z0-9_]+)\}$/;
+
+/** Returns the catalog field keys whose values are unresolved in
+ *  the user's saved spec — `""`, missing, or still carrying a
+ *  `${KEY}` placeholder.
+ *
+ *  Mapping goes: catalog `configSchema[].key` → spec env key, via
+ *  the catalog template's env value. E.g. catalog template
+ *  `env: { NOTION_TOKEN: "${NOTION_API_KEY}" }` binds the field
+ *  `NOTION_API_KEY` to the env key `NOTION_TOKEN`. We then check
+ *  the user's saved spec's `env.NOTION_TOKEN`.
+ *
+ *  HTTP-type catalog entries currently have no required fields
+ *  (deepwiki is empty) — they fall through with `[]`. When a
+ *  required HTTP header lands in the catalog, extend this helper. */
+export function findMissingRequiredEnv(entry: McpCatalogEntry, spec: McpServerSpec): string[] {
+  // Transport mismatch (e.g. catalog stdio entry but user pointed
+  // the same id at an HTTP URL) means the catalog's env template
+  // doesn't apply to this user spec — see `preflightUserServers`'s
+  // header comment for the rationale. Guard here too so callers that
+  // skip the wrapper still get the correct answer.
+  if (entry.spec.type !== spec.type) return [];
+  if (entry.spec.type !== "stdio" || !entry.spec.env) return [];
+  const fieldToEnvKey = buildFieldToEnvKeyMap(entry.spec.env);
+  const userEnv = spec.type === "stdio" ? spec.env : undefined;
+  const required = requiredKeysOf(entry);
+  const missing: string[] = [];
+  for (const fieldKey of required) {
+    const envKey = fieldToEnvKey.get(fieldKey);
+    if (envKey === undefined) continue;
+    const value = userEnv?.[envKey];
+    if (!isResolved(value)) missing.push(fieldKey);
+  }
+  return missing;
+}
+
+function buildFieldToEnvKeyMap(templateEnv: Record<string, string>): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [envKey, value] of Object.entries(templateEnv)) {
+    const match = SINGLE_PLACEHOLDER.exec(value);
+    if (match) out.set(match[1], envKey);
+  }
+  return out;
+}
+
+function isResolved(value: string | undefined): boolean {
+  if (typeof value !== "string") return false;
+  // Trim before the empty check — `"   "` (whitespace-only) is just
+  // as misconfigured as `""` and would otherwise let preflight
+  // greenlight a server that can't actually authenticate (Codex
+  // review on #1355).
+  if (value.trim().length === 0) return false;
+  PLACEHOLDER_PATTERN.lastIndex = 0;
+  return !PLACEHOLDER_PATTERN.test(value);
+}
+
+/** Filter user MCP servers by checking the catalog's required
+ *  fields. Servers without a catalog match (= user-added custom
+ *  servers) pass through — we have no metadata to validate them
+ *  against.
+ *
+ *  Two other shapes also pass through unvalidated:
+ *
+ *  - `enabled: false` entries (CodeRabbit review on #1355). They're
+ *    intentionally disabled by the user; running them through
+ *    preflight produces spurious "missing required config" warnings
+ *    AND skews the boot summary's `started` count. The downstream
+ *    `prepareUserServers` already drops disabled entries before
+ *    spawning anything, so we just forward them.
+ *
+ *  - Type-mismatched catalog hits. If the user's mcp.json has
+ *    `gmail: { type: "http", url: ... }` but the catalog's `gmail`
+ *    entry is `type: "stdio"` with env templates, the catalog's
+ *    requirement list doesn't apply to the user's spec — they've
+ *    pointed `gmail` at a different transport, effectively making it
+ *    a custom server. Treat as custom (no preflight) rather than
+ *    false-flagging missing env. */
+export function preflightUserServers(userServers: Record<string, McpServerSpec> | undefined | null): McpPreflightResult {
+  const ready: Record<string, McpServerSpec> = {};
+  const skipped: McpPreflightResult["skipped"] = [];
+  // Defensive default (Sourcery review on #1355): a malformed
+  // mcp.json — or a future refactor that nulls `mcpServers` — would
+  // otherwise throw `Object.entries(null)` at boot.
+  for (const [serverId, spec] of Object.entries(userServers ?? {})) {
+    if (spec.enabled === false) {
+      ready[serverId] = spec;
+      continue;
+    }
+    const entry = findCatalogEntry(serverId);
+    if (entry === null || entry.spec.type !== spec.type) {
+      ready[serverId] = spec;
+      continue;
+    }
+    const missing = findMissingRequiredEnv(entry, spec);
+    if (missing.length > 0) {
+      skipped.push({ serverId, missing: missing.sort() });
+      continue;
+    }
+    ready[serverId] = spec;
+  }
+  return { ready, skipped };
+}
+
+// Snapshot of the previous run's skipped set so per-agent-run logging
+// only fires on state changes. Boot-time logging always fires (clean
+// startup signal) and seeds the snapshot for subsequent runs.
+//
+// The earlier shape — a monotonic Set that only ever grew — would
+// swallow a `missing → fixed → missing again` regression: the second
+// "missing" emitted no warning because the key had already been
+// logged on the first one (Codex review on #1355). Snapshot diffing
+// fixes that without losing the dedup property: identical state
+// across turns still logs at most once.
+let lastSkippedKeys = new Set<string>();
+
+function dedupKey(entry: { serverId: string; missing: string[] }): string {
+  return `${entry.serverId}:${entry.missing.join(",")}`;
+}
+
+/** Emit structured logs for the preflight outcome.
+ *  - `source: "boot"`  — runs once at startup; always logs and
+ *    seeds the snapshot.
+ *  - `source: "agent-run"` — runs per agent invocation; logs only
+ *    entries that are new vs the previous run's snapshot. A server
+ *    that re-enters a broken state after being fixed will log again
+ *    because the key is absent from the snapshot. */
+export function logPreflightResult(result: McpPreflightResult, source: "boot" | "agent-run"): void {
+  const isBoot = source === "boot";
+  const currentKeys = new Set(result.skipped.map(dedupKey));
+  for (const entry of result.skipped) {
+    const key = dedupKey(entry);
+    if (!isBoot && lastSkippedKeys.has(key)) continue;
+    log.warn("mcp", "preflight: skipping server — missing required config", {
+      source,
+      serverId: entry.serverId,
+      missing: entry.missing,
+    });
+  }
+  lastSkippedKeys = currentKeys;
+  if (isBoot) {
+    log.info("mcp", "preflight summary", {
+      started: Object.keys(result.ready).length,
+      skipped: result.skipped.length,
+    });
+  }
+}
+
+/** Test seam — reset the snapshot between tests so each case sees a
+ *  fresh logging state. */
+export function _resetPreflightLogCache(): void {
+  lastSkippedKeys = new Set();
+}

package/server/agent/stream.ts

@@ -15,6 +15,11 @@ export type AgentEvent =
       type: typeof EVENT_TYPES.toolCallResult;
       toolUseId: string;
       content: string;
+      /** Anthropic's `tool_result` block carries `is_error: true` when
+       *  the MCP server (or other tool) reported an error. Surfaced
+       *  here so the failure monitor (#1353) can attribute repeated
+       *  errors to a specific MCP server and warn / notify. */
+      isError?: boolean;
     }
   | { type: typeof EVENT_TYPES.claudeSessionId; id: string };
 
@@ -27,6 +32,10 @@ export interface ClaudeContentBlock {
   content?: unknown;
   /** Text content — present in `text` type blocks. */
   text?: string;
+  /** Tool-result error flag from the Anthropic API. Present on
+   *  `tool_result` blocks when the tool itself reported failure
+   *  (MCP server returned an error, 401, ECONNREFUSED, …). */
+  is_error?: boolean;
 }
 
 export interface ClaudeMessage {
@@ -73,11 +82,13 @@ export function blockToEvent(block: ClaudeContentBlock): AgentEvent | null {
   if (block.type === "tool_result" && block.tool_use_id) {
     const raw = block.content;
     const content = typeof raw === "string" ? raw : raw === undefined ? "" : JSON.stringify(raw);
-    return {
+    const event: AgentEvent = {
       type: EVENT_TYPES.toolCallResult,
       toolUseId: block.tool_use_id,
       content,
     };
+    if (block.is_error === true) event.isError = true;
+    return event;
   }
   return null;
 }

package/server/api/routes/mulmo-script.ts

@@ -27,7 +27,8 @@ import { mulmoScriptSchema, type MulmoBeat, type MulmoImagePromptMedia } from "@
 import { slugify } from "../../utils/slug.js";
 import { resolveWithinRoot } from "../../utils/files/safe.js";
 import { errorMessage } from "../../utils/errors.js";
-import { badRequest, notFound, serverError } from "../../utils/httpError.js";
+import { badRequest, notFound, sendError, serverError } from "../../utils/httpError.js";
+import { depStatus } from "../../system/optionalDeps.js";
 import { getOptionalStringQuery, getSessionQuery } from "../../utils/request.js";
 import { log } from "../../system/logger/index.js";
 import { validateUpdateBeatBody, validateUpdateScriptBody } from "./mulmoScriptValidate.js";
@@ -37,6 +38,20 @@ import { publishGeneration } from "../../events/session-store/index.js";
 import { GENERATION_KINDS } from "../../../src/types/events.js";
 
 const router = Router();
+
+// mulmocast shells out to ffmpeg for movie / beat rendering. When
+// ffmpeg is absent the optional-deps probe (#1385) marks it
+// unavailable; intercept here with a clear 503 instead of letting
+// the library throw an opaque spawn ENOENT mid-stream. `undefined`
+// means the boot probe hasn't completed — assume available so a
+// brief startup window never blocks a render.
+function ffmpegUnavailable(res: Response): boolean {
+  if (depStatus("ffmpeg")?.available === false) {
+    sendError(res, 503, "ffmpeg is not installed — movie and beat rendering are unavailable. Install ffmpeg and restart the server.");
+    return true;
+  }
+  return false;
+}
 const storiesDir = path.resolve(WORKSPACE_PATHS.stories);
 
 // The downloadMovie handler expects "stories/<rel>" (historical
@@ -591,6 +606,7 @@ bindRoute(router, API_ROUTES.mulmoScript.renderBeat, async (req: Request<object,
     badRequest(res, "filePath and beatIndex are required");
     return;
   }
+  if (ffmpegUnavailable(res)) return;
 
   const key = String(beatIndex);
   publishGeneration(chatSessionId, GENERATION_KINDS.beatImage, filePath, key, false);
@@ -693,6 +709,8 @@ bindRoute(router, API_ROUTES.mulmoScript.generateMovie, async (req: Request<obje
     return;
   }
 
+  if (ffmpegUnavailable(res)) return;
+
   const absoluteFilePath = resolveStoryPath(filePath, res);
   if (!absoluteFilePath) return;
 

package/server/api/routes/schedulerHandlers.ts

@@ -28,6 +28,34 @@ export type SchedulerActionResult =
       jsonData: Record<string, unknown>;
     };
 
+// Coerces the untrusted `props` payload into a safe-to-store
+// object. Two responsibilities:
+//
+// 1. Non-object input (a number / string / array / null from
+//    untrusted JSON) becomes an empty props object — `"endDate"
+//    in 1` would otherwise throw a TypeError and surface as a
+//    500 via the asyncHandler.
+// 2. Non-string `endDate` (number / array / object) is dropped —
+//    downstream comparisons (`end < start`) only make sense for
+//    strings, and a stray number triggers a coercion bug.
+//
+// Notably we DO preserve malformed `endDate` STRINGS (e.g. "next
+// Friday", "2026-05-25" before a start of "2026-05-27"). The view
+// surfaces those as a "broken range" chip so the user/LLM gets
+// visible feedback instead of having the bad data silently erased.
+export function sanitizeProps(props: unknown): ScheduledItem["props"] {
+  if (typeof props !== "object" || props === null || Array.isArray(props)) {
+    return {};
+  }
+  const record = props as ScheduledItem["props"];
+  if (!("endDate" in record)) return record;
+  if (typeof record.endDate === "string") return record;
+  if (record.endDate === null) return record;
+  const next = { ...record };
+  Reflect.deleteProperty(next, "endDate");
+  return next;
+}
+
 export function sortItems(items: ScheduledItem[]): ScheduledItem[] {
   return [...items].sort((left, right) => {
     const leftDate = typeof left.props.date === "string" ? left.props.date : null;
@@ -57,7 +85,7 @@ export function handleAdd(items: ScheduledItem[], input: SchedulerActionInput):
     id: makeId("sched"),
     title: input.title,
     createdAt: Date.now(),
-    props: input.props ?? {},
+    props: sanitizeProps(input.props ?? {}),
   };
   const next = sortItems([...items, item]);
   return {
@@ -107,10 +135,11 @@ export function handleUpdate(items: ScheduledItem[], input: SchedulerActionInput
       jsonData: {},
     };
   }
+  const mergedProps = input.props !== undefined ? applyPropPatch(target.props, input.props) : target.props;
   const updated: ScheduledItem = {
     ...target,
     title: input.title !== undefined ? input.title : target.title,
-    props: input.props !== undefined ? applyPropPatch(target.props, input.props) : target.props,
+    props: sanitizeProps(mergedProps),
   };
   const next = sortItems(items.map((i) => (i.id === input.id ? updated : i)));
   return {
@@ -121,16 +150,35 @@ export function handleUpdate(items: ScheduledItem[], input: SchedulerActionInput
   };
 }
 
+// `replace` accepts an arbitrary array from untrusted JSON, so
+// every item needs the same shape narrowing the in-memory store
+// guarantees: a non-empty string `id` (the dispatch primary key
+// AND the input to the per-event colour-hash, both of which crash
+// or misbehave on non-strings), a string `title`, a numeric
+// `createdAt`, and a sanitised `props`. Non-object items are
+// dropped; objects with missing/malformed required fields get a
+// safe default (newly minted id, empty title, current timestamp)
+// rather than failing the whole replace.
+export function sanitizeItem(raw: unknown): ScheduledItem | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const obj = raw as Partial<ScheduledItem>;
+  const itemId = typeof obj.id === "string" && obj.id.length > 0 ? obj.id : makeId("sched");
+  const title = typeof obj.title === "string" ? obj.title : "";
+  const createdAt = typeof obj.createdAt === "number" && Number.isFinite(obj.createdAt) ? obj.createdAt : Date.now();
+  return { id: itemId, title, createdAt, props: sanitizeProps(obj.props) };
+}
+
 export function handleReplace(_items: ScheduledItem[], input: SchedulerActionInput): SchedulerActionResult {
   if (!Array.isArray(input.items)) {
     return { kind: "error", status: 400, error: "items array required" };
   }
-  const next = sortItems(input.items);
+  const sanitized = input.items.map(sanitizeItem).filter((item): item is ScheduledItem => item !== null);
+  const next = sortItems(sanitized);
   return {
     kind: "success",
     items: next,
     message: `Replaced all items (${next.length} total)`,
-    jsonData: { count: next.length },
+    jsonData: { count: next.length, dropped: input.items.length - next.length },
   };
 }
 

package/server/api/routes/sessions.ts

@@ -79,7 +79,18 @@ export interface SessionSummary {
   isBookmarked?: boolean;
   // Live state from the in-memory session store. Absent when the
   // session has no active entry in the store (i.e. idle / historical).
+  //
+  // `isRunning` is the BROAD predicate: agent turn live OR any
+  // background generation (image/audio/movie) still pending. Drives
+  // the sidebar "busy" indicator that must stay lit across nav.
+  //
+  // `liveIsRunning` is the NARROW predicate: exactly the
+  // `DELETE /api/sessions/:id` 409 gate (`getSession()?.isRunning`).
+  // Exposed for cleanup-style callers (e2e-live `waitForSessionIdle`)
+  // that need to poll "is DELETE accepted yet" without over-waiting
+  // on lingering pendingGenerations. See issue #1195.
   isRunning?: boolean;
+  liveIsRunning?: boolean;
   hasUnread?: boolean;
   statusMessage?: string;
 }
@@ -149,6 +160,10 @@ function buildSessionSummary(
     // "busy" even when the agent turn has ended, so the sidebar
     // indicator stays lit across view navigation.
     summary.isRunning = live.isRunning || Object.keys(live.pendingGenerations).length > 0;
+    // Narrow predicate — must stay byte-identical to the DELETE
+    // 409 gate (`getSession(sessionId)?.isRunning`) so a caller
+    // polling this can trust "false ⇒ DELETE will be accepted".
+    summary.liveIsRunning = live.isRunning;
     summary.statusMessage = live.statusMessage;
   }
   return summary;

package/server/api/routes/skills.ts

@@ -15,6 +15,20 @@
 import { Router, Request, Response } from "express";
 import { deleteProjectSkill, discoverSkills, saveProjectSkill, updateProjectSkill } from "../../workspace/skills/index.js";
 import type { Skill, SkillSummary } from "../../workspace/skills/index.js";
+import {
+  isCatalogSource,
+  listCatalogEntries,
+  readCatalogEntryDetail,
+  readExternalDetailAsCatalog,
+  starCatalogEntry,
+  starExternalAsCatalog,
+  type CatalogEntry,
+  type CatalogEntryDetail,
+  type CatalogDetailResult,
+  type StarResult,
+} from "../../workspace/skills/catalog.js";
+import { installExternalRepo, listInstalledRepos, uninstallExternalRepo, type InstalledRepo } from "../../workspace/skills/external/install.js";
+import { EXTERNAL_PRESETS, type ExternalPresetSuggestion } from "../../workspace/skills/external/presets.js";
 import { workspacePath } from "../../workspace/workspace.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { bindRoute } from "../../utils/router.js";
@@ -65,6 +79,255 @@ bindRoute(router, API_ROUTES.skills.list, async (_req: Request, res: Response<Sk
   });
 });
 
+// Catalog endpoints (#1335 PR-B). Reads from
+// `<workspace>/data/skills/catalog/<source>/<slug>/` (populated by
+// `syncPresetSkills`); the star endpoint copies catalog entries
+// into `.claude/skills/<slug>/` so Claude Code's discovery picks
+// them up. Catalog entries themselves are NOT in `.claude/skills/`
+// by design — that's the prompt-bloat fix from #1335.
+//
+// Route ordering matters: these `/catalog*` routes register
+// BEFORE `GET /:name` below because Express matches in
+// registration order. A request for `/catalog` would otherwise
+// land in the detail handler with `req.params.name = "catalog"`
+// and 404. Keep all `/catalog*` specifics ahead of any `:name`
+// parameter route in this file.
+
+interface CatalogListResponse {
+  entries: CatalogEntry[];
+}
+
+interface StarResponse {
+  starred: true;
+  slug: string;
+}
+
+bindRoute(router, API_ROUTES.skills.catalogList, async (_req: Request, res: Response<CatalogListResponse>) => {
+  const entries = await listCatalogEntries();
+  log.info("skills", "catalog list: ok", { count: entries.length });
+  res.json({ entries });
+});
+
+interface CatalogPreviewQuery {
+  source?: unknown;
+  slug?: unknown;
+  /** External-source only — repoId + skillFolder identify the entry
+   *  in place of `slug`. */
+  repoId?: unknown;
+  skillFolder?: unknown;
+}
+
+interface CatalogPreviewResponse {
+  detail: CatalogEntryDetail;
+}
+
+function previewResponse(result: CatalogDetailResult, source: string, ident: string, res: Response<CatalogPreviewResponse | ErrorResponse>): void {
+  if (result.kind === "ok") {
+    log.info("skills", "catalog preview: ok", { source, slug: result.detail.slug });
+    res.json({ detail: result.detail });
+    return;
+  }
+  if (result.kind === "not-found") {
+    log.warn("skills", "catalog preview: not found", { source, ident });
+    notFound(res, `catalog entry not found: ${result.source}/${result.slug}`);
+    return;
+  }
+  log.warn("skills", "catalog preview: invalid slug", { ident });
+  badRequest(res, `invalid slug: ${result.slug}`);
+}
+
+bindRoute(
+  router,
+  API_ROUTES.skills.catalogPreview,
+  async (req: Request<object, unknown, unknown, CatalogPreviewQuery>, res: Response<CatalogPreviewResponse | ErrorResponse>) => {
+    const { source, slug, repoId, skillFolder } = req.query;
+    if (!isCatalogSource(source)) {
+      badRequest(res, "source must be a known catalog source");
+      return;
+    }
+    if (source === "external") {
+      if (typeof repoId !== "string" || repoId.length === 0 || typeof skillFolder !== "string" || skillFolder.length === 0) {
+        badRequest(res, "repoId and skillFolder are required for external preview");
+        return;
+      }
+      const result = await readExternalDetailAsCatalog(repoId, skillFolder);
+      previewResponse(result, source, `${repoId}/${skillFolder}`, res);
+      return;
+    }
+    if (typeof slug !== "string" || slug.length === 0) {
+      badRequest(res, "slug is required");
+      return;
+    }
+    const result = await readCatalogEntryDetail(source, slug);
+    previewResponse(result, source, slug, res);
+  },
+);
+
+function starResponse(result: StarResult, source: string, ident: string, res: Response<StarResponse | ErrorResponse>): void {
+  if (result.kind === "starred") {
+    log.info("skills", "catalog star: ok", { source, slug: result.slug });
+    res.json({ starred: true, slug: result.slug });
+    return;
+  }
+  if (result.kind === "already-active") {
+    log.info("skills", "catalog star: already-active", { source, slug: result.slug });
+    conflict(res, `skill "${result.slug}" is already active`);
+    return;
+  }
+  if (result.kind === "not-found") {
+    log.warn("skills", "catalog star: not found", { source, ident });
+    notFound(res, `catalog entry not found: ${result.source}/${result.slug}`);
+    return;
+  }
+  log.warn("skills", "catalog star: invalid slug", { ident });
+  badRequest(res, `invalid slug: ${result.slug}`);
+}
+
+interface ExternalStarBody {
+  source?: unknown;
+  repoId?: unknown;
+  skillFolder?: unknown;
+  slug?: unknown;
+}
+
+bindRoute(router, API_ROUTES.skills.catalogStar, async (req: Request<object, unknown, ExternalStarBody>, res: Response<StarResponse | ErrorResponse>) => {
+  const { source, slug, repoId, skillFolder } = req.body;
+  if (!isCatalogSource(source)) {
+    badRequest(res, "source must be a known catalog source");
+    return;
+  }
+  if (source === "external") {
+    if (typeof repoId !== "string" || repoId.length === 0 || typeof skillFolder !== "string" || skillFolder.length === 0) {
+      badRequest(res, "repoId and skillFolder are required for external star");
+      return;
+    }
+    const result = await starExternalAsCatalog(repoId, skillFolder);
+    starResponse(result, source, `${repoId}/${skillFolder}`, res);
+    return;
+  }
+  if (typeof slug !== "string" || slug.length === 0) {
+    badRequest(res, "slug is required");
+    return;
+  }
+  const result = await starCatalogEntry(source, slug);
+  starResponse(result, source, slug, res);
+});
+
+// External-repo lifecycle endpoints (#1383 / #1335 PR-C). They live
+// under `/api/skills/external/*` so they sort cleanly alongside the
+// catalog endpoints AND register BEFORE the `/:name` detail handler
+// below. Express matches in registration order — a `:name` route
+// declared first would swallow `/external/...` as a skill named
+// "external".
+
+interface ExternalSuggestionsResponse {
+  suggestions: readonly ExternalPresetSuggestion[];
+}
+
+interface ExternalReposResponse {
+  repos: InstalledRepo[];
+}
+
+interface InstallRepoBody {
+  url?: unknown;
+  subpath?: unknown;
+  ref?: unknown;
+}
+
+interface InstallRepoResponse {
+  installed: true;
+  repoId: string;
+  url: string;
+  sha: string;
+  skillCount: number;
+}
+
+interface UninstallRepoResponse {
+  uninstalled: true;
+  repoId: string;
+}
+
+bindRoute(router, API_ROUTES.skills.externalSuggestions, (_req: Request, res: Response<ExternalSuggestionsResponse>) => {
+  res.json({ suggestions: EXTERNAL_PRESETS });
+});
+
+bindRoute(router, API_ROUTES.skills.externalReposList, async (_req: Request, res: Response<ExternalReposResponse>) => {
+  const repos = await listInstalledRepos();
+  log.info("skills", "external repos list: ok", { count: repos.length });
+  res.json({ repos });
+});
+
+bindRoute(
+  router,
+  API_ROUTES.skills.externalReposInstall,
+  async (req: Request<object, unknown, InstallRepoBody>, res: Response<InstallRepoResponse | ErrorResponse>) => {
+    const { url, subpath, ref } = req.body ?? {};
+    if (typeof url !== "string" || url.length === 0) {
+      badRequest(res, "url is required");
+      return;
+    }
+    if (subpath !== undefined && typeof subpath !== "string") {
+      badRequest(res, "subpath must be a string when provided");
+      return;
+    }
+    if (ref !== undefined && typeof ref !== "string") {
+      badRequest(res, "ref must be a string when provided");
+      return;
+    }
+    const result = await installExternalRepo({ url, subpath, ref });
+    if (result.kind === "installed") {
+      log.info("skills", "external install: ok", { repoId: result.detail.repoId, skillCount: result.detail.skillCount });
+      res.json({
+        installed: true,
+        repoId: result.detail.repoId,
+        url: result.detail.url,
+        sha: result.detail.sha,
+        skillCount: result.detail.skillCount,
+      });
+      return;
+    }
+    if (result.kind === "no-skills") {
+      log.warn("skills", "external install: no skills discovered", { repoId: result.repoId });
+      res.status(422).json({ error: `no SKILL.md found in repo (${result.repoId})` });
+      return;
+    }
+    if (result.kind === "invalid-url") {
+      log.warn("skills", "external install: invalid url", { url: result.url });
+      badRequest(res, "url must be a github.com HTTPS URL: https://github.com/<owner>/<repo>");
+      return;
+    }
+    if (result.kind === "invalid-subpath") {
+      log.warn("skills", "external install: invalid subpath", { subpath: result.subpath });
+      badRequest(res, "subpath must be a relative path with no '..', leading '/', or backslash segments");
+      return;
+    }
+    if (result.kind === "id-collision") {
+      log.warn("skills", "external install: repoId collision", { repoId: result.repoId, existingUrl: result.existingUrl });
+      conflict(res, `repo id "${result.repoId}" is already in use by ${result.existingUrl}. Uninstall it first if you intend to replace it.`);
+      return;
+    }
+    log.warn("skills", "external install: error", { reason: result.reason });
+    res.status(502).json({ error: `external install failed: ${result.reason}` });
+  },
+);
+
+bindRoute(router, API_ROUTES.skills.externalReposRemove, async (req: Request<{ repoId: string }>, res: Response<UninstallRepoResponse | ErrorResponse>) => {
+  const { repoId } = req.params;
+  const result = await uninstallExternalRepo(repoId);
+  if (result.kind === "uninstalled") {
+    log.info("skills", "external uninstall: ok", { repoId: result.repoId });
+    res.json({ uninstalled: true, repoId: result.repoId });
+    return;
+  }
+  if (result.kind === "not-found") {
+    log.warn("skills", "external uninstall: not found", { repoId: result.repoId });
+    notFound(res, `external repo not installed: ${result.repoId}`);
+    return;
+  }
+  log.warn("skills", "external uninstall: invalid repoId", { repoId: result.repoId });
+  badRequest(res, `invalid repoId: ${result.repoId}`);
+});
+
 bindRoute(router, API_ROUTES.skills.detail, async (req: Request<{ name: string }>, res: Response<SkillDetailResponse | ErrorResponse>) => {
   log.info("skills", "detail: start", { name: req.params.name });
   const skills = await discoverSkills({ workspaceRoot: workspacePath });