@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/runtime/routes/notification-routes.ts

@@ -5,98 +5,120 @@
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 
+import { FeedItemSchema } from "../../api/responses/home.js";
 import { getDb } from "../../memory/db-connection.js";
 import { notificationDeliveries } from "../../memory/schema.js";
 import { bufferIfDeferred } from "../../notifications/deferred-emit.js";
 import { editNotification } from "../../notifications/edit-notification.js";
 import { emitNotificationSignal } from "../../notifications/emit-signal.js";
 import { listEvents } from "../../notifications/events-store.js";
-import type { AttentionHints } from "../../notifications/signal.js";
+import {
+  AttentionHintsSchema,
+  NotificationSourceChannelSchema,
+  RoutingIntentSchema,
+  UrgencySchema,
+} from "../../notifications/signal.js";
 import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-function handleNotificationIntentResult({ body = {} }: RouteHandlerArgs) {
-  const { deliveryId, success, errorMessage, errorCode } = body as {
-    deliveryId?: string;
-    success?: boolean;
-    errorMessage?: string;
-    errorCode?: string;
-  };
+// ── Notification intent result (client delivery ack) ──────────────────
+
+const NotificationIntentResultParams = z.object({
+  deliveryId: z.string().min(1).describe("Notification delivery ID"),
+  success: z.boolean().describe("Whether delivery succeeded").optional(),
+  errorMessage: z
+    .string()
+    .describe("Error message if delivery failed")
+    .optional(),
+  errorCode: z.string().describe("Error code if delivery failed").optional(),
+});
 
-  if (!deliveryId || typeof deliveryId !== "string") {
+function handleNotificationIntentResult({ body = {} }: RouteHandlerArgs) {
+  const parsed = NotificationIntentResultParams.safeParse(body);
+  if (!parsed.success) {
     throw new BadRequestError("deliveryId is required");
   }
+  const validated = parsed.data;
 
   const db = getDb();
   const now = Date.now();
 
-  const updates: Record<string, unknown> = {
-    clientDeliveryStatus: success ? "delivered" : "client_failed",
-    clientDeliveryAt: now,
-    updatedAt: now,
-  };
-  if (errorMessage) {
-    updates.clientDeliveryError = errorMessage;
-  }
-  if (errorCode) {
-    updates.errorCode = errorCode;
-  }
-
   db.update(notificationDeliveries)
-    .set(updates)
-    .where(eq(notificationDeliveries.id, deliveryId))
+    .set({
+      clientDeliveryStatus: validated.success ? "delivered" : "client_failed",
+      clientDeliveryAt: now,
+      updatedAt: now,
+      ...(validated.errorMessage
+        ? { clientDeliveryError: validated.errorMessage }
+        : {}),
+      ...(validated.errorCode ? { errorCode: validated.errorCode } : {}),
+    })
+    .where(eq(notificationDeliveries.id, validated.deliveryId))
     .run();
 
   return { ok: true };
 }
 
-// ── Notification pipeline schemas ─────────────────────────────────────
-
-const AttentionHintsSchema = z.object({
-  requiresAction: z.boolean(),
-  urgency: z.enum(["low", "medium", "high", "critical"]),
-  deadlineAt: z.number().optional(),
-  isAsyncBackground: z.boolean(),
-  visibleInSourceNow: z.boolean(),
-});
+// ── Emit signal ───────────────────────────────────────────────────────
 
 const EmitSignalParams = z.object({
   sourceEventName: z.string().min(1),
-  sourceChannel: z.enum([
-    "assistant_tool",
-    "vellum",
-    "phone",
-    "telegram",
-    "slack",
-    "scheduler",
-    "watcher",
-  ]),
+  sourceChannel: NotificationSourceChannelSchema,
   sourceContextId: z.string().min(1),
   attentionHints: AttentionHintsSchema,
   contextPayload: z.record(z.string(), z.unknown()).optional(),
-  routingIntent: z
-    .enum(["single_channel", "multi_channel", "all_channels"])
-    .optional(),
+  routingIntent: RoutingIntentSchema.optional(),
   conversationAffinityHint: z.record(z.string(), z.string()).optional(),
   dedupeKey: z.string().optional(),
   throwOnError: z.boolean().optional(),
-  // Conversation that originated this signal — used by `deferred-emit` to
-  // buffer notifications during in-band background-job tool calls.
   originatingConversationId: z.string().optional(),
 });
 
-const ListNotificationEventsParams = z.object({
-  limit: z.number().int().positive().optional(),
-  sourceEventName: z.string().optional(),
+const EmitSignalResponse = z.object({
+  signalId: z.string(),
+  dispatched: z.boolean(),
+  deduplicated: z.boolean(),
+  reason: z.string(),
 });
 
+async function handleEmitSignal({ body = {} }: RouteHandlerArgs) {
+  const parsed = EmitSignalParams.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      parsed.error.issues[0]?.message ?? "Invalid signal parameters",
+    );
+  }
+  const validated = parsed.data;
+  const buffered = bufferIfDeferred(
+    validated.originatingConversationId,
+    validated,
+  );
+  if (buffered) {
+    return {
+      signalId: buffered.signalId,
+      dispatched: buffered.dispatched,
+      deduplicated: buffered.deduplicated,
+      reason: buffered.reason,
+    };
+  }
+  const result = await emitNotificationSignal(validated);
+  return {
+    signalId: result.signalId,
+    dispatched: result.dispatched,
+    deduplicated: result.deduplicated,
+    reason: result.reason,
+  };
+}
+
+// ── Edit notification ─────────────────────────────────────────────────
+
 const EditNotificationParams = z
   .object({
     id: z.string().min(1).describe("Feed item id (notif:<uuid>) or bare uuid"),
     title: z.string().optional(),
     body: z.string().optional(),
-    urgency: z.enum(["low", "medium", "high", "critical"]).optional(),
+    urgency: UrgencySchema.optional(),
     status: z.enum(["new", "seen", "acted_on", "dismissed"]).optional(),
   })
   .refine(
@@ -111,44 +133,27 @@ const EditNotificationParams = z
     },
   );
 
-// ── Notification pipeline handlers ───────────────────────────────────
+const ChannelEditOutcomeSchema = z.object({
+  channel: z.string(),
+  deliveryId: z.string(),
+  outcome: z.enum(["updated", "unsupported", "skipped", "failed"]),
+  reason: z.string().optional(),
+});
 
-async function handleEmitSignal({ body = {} }: RouteHandlerArgs) {
-  const validated = EmitSignalParams.parse(body);
-  const params = {
-    sourceEventName: validated.sourceEventName,
-    sourceChannel: validated.sourceChannel,
-    sourceContextId: validated.sourceContextId,
-    attentionHints: validated.attentionHints as AttentionHints,
-    contextPayload: validated.contextPayload as Record<string, unknown>,
-    routingIntent: validated.routingIntent,
-    conversationAffinityHint: validated.conversationAffinityHint,
-    dedupeKey: validated.dedupeKey,
-    throwOnError: validated.throwOnError,
-  };
-  const buffered = bufferIfDeferred(
-    validated.originatingConversationId,
-    params,
-  );
-  if (buffered) {
-    return {
-      signalId: buffered.signalId,
-      dispatched: buffered.dispatched,
-      deduplicated: buffered.deduplicated,
-      reason: buffered.reason,
-    };
-  }
-  const result = await emitNotificationSignal(params);
-  return {
-    signalId: result.signalId,
-    dispatched: result.dispatched,
-    deduplicated: result.deduplicated,
-    reason: result.reason,
-  };
-}
+const EditNotificationResponse = z.object({
+  ok: z.boolean(),
+  feedItem: FeedItemSchema,
+  channels: z.array(ChannelEditOutcomeSchema),
+});
 
 async function handleEditNotification({ body = {} }: RouteHandlerArgs) {
-  const validated = EditNotificationParams.parse(body);
+  const parsed = EditNotificationParams.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      parsed.error.issues[0]?.message ?? "Invalid notification parameters",
+    );
+  }
+  const validated = parsed.data;
   const result = await editNotification(validated);
   if (!result) {
     throw new NotFoundError(`No notification found for id ${validated.id}`);
@@ -160,8 +165,31 @@ async function handleEditNotification({ body = {} }: RouteHandlerArgs) {
   };
 }
 
+// ── List events ───────────────────────────────────────────────────────
+
+const ListNotificationEventsParams = z.object({
+  limit: z.number().int().positive().optional(),
+  sourceEventName: z.string().optional(),
+});
+
+const NotificationEventSchema = z.object({
+  id: z.string(),
+  sourceEventName: z.string(),
+  sourceChannel: z.string(),
+  sourceContextId: z.string(),
+  urgency: z.string(),
+  dedupeKey: z.string().nullable(),
+  createdAt: z.string(),
+});
+
 function handleListEvents({ body = {} }: RouteHandlerArgs) {
-  const validated = ListNotificationEventsParams.parse(body);
+  const parsed = ListNotificationEventsParams.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      parsed.error.issues[0]?.message ?? "Invalid query parameters",
+    );
+  }
+  const validated = parsed.data;
   const rows = listEvents({
     limit: validated.limit,
     sourceEventName: validated.sourceEventName,
@@ -169,12 +197,10 @@ function handleListEvents({ body = {} }: RouteHandlerArgs) {
   return rows.map((row) => {
     let urgency = "unknown";
     try {
-      const hints = JSON.parse(row.attentionHintsJson) as {
-        urgency?: string;
-      };
-      if (hints.urgency) {
-        urgency = hints.urgency;
-      }
+      const hints = AttentionHintsSchema.parse(
+        JSON.parse(row.attentionHintsJson),
+      );
+      urgency = hints.urgency;
     } catch {
       // Leave urgency as "unknown" if parsing fails.
     }
@@ -207,12 +233,7 @@ export const ROUTES: RouteDefinition[] = [
       "Emit a notification signal into the pipeline for routing and delivery.",
     tags: ["notifications"],
     requestBody: EmitSignalParams,
-    responseBody: z.object({
-      signalId: z.string(),
-      dispatched: z.boolean(),
-      deduplicated: z.boolean(),
-      reason: z.string(),
-    }),
+    responseBody: EmitSignalResponse,
   },
   {
     operationId: "edit_notification",
@@ -228,18 +249,7 @@ export const ROUTES: RouteDefinition[] = [
       "Patch the home-feed entry for a notification and, where supported (Slack today), update the delivered message in place.",
     tags: ["notifications"],
     requestBody: EditNotificationParams,
-    responseBody: z.object({
-      ok: z.boolean(),
-      feedItem: z.record(z.string(), z.unknown()),
-      channels: z.array(
-        z.object({
-          channel: z.string(),
-          deliveryId: z.string(),
-          outcome: z.enum(["updated", "unsupported", "skipped", "failed"]),
-          reason: z.string().optional(),
-        }),
-      ),
-    }),
+    responseBody: EditNotificationResponse,
     additionalResponses: {
       "404": {
         description: "No notification found for the supplied id",
@@ -260,17 +270,7 @@ export const ROUTES: RouteDefinition[] = [
       "List recent notification events, optionally filtered by source event name.",
     tags: ["notifications"],
     requestBody: ListNotificationEventsParams,
-    responseBody: z.array(
-      z.object({
-        id: z.string(),
-        sourceEventName: z.string(),
-        sourceChannel: z.string(),
-        sourceContextId: z.string(),
-        urgency: z.string(),
-        dedupeKey: z.string().nullable(),
-        createdAt: z.string(),
-      }),
-    ),
+    responseBody: z.array(NotificationEventSchema),
   },
   {
     operationId: "notificationintentresult_post",
@@ -285,18 +285,7 @@ export const ROUTES: RouteDefinition[] = [
       "Client acknowledgment for local notification delivery outcome.",
     tags: ["notifications"],
     handler: handleNotificationIntentResult,
-    requestBody: z.object({
-      deliveryId: z.string().describe("Notification delivery ID"),
-      success: z.boolean().describe("Whether delivery succeeded").optional(),
-      errorMessage: z
-        .string()
-        .describe("Error message if delivery failed")
-        .optional(),
-      errorCode: z
-        .string()
-        .describe("Error code if delivery failed")
-        .optional(),
-    }),
+    requestBody: NotificationIntentResultParams,
     responseBody: z.object({
       ok: z.boolean(),
     }),

package/src/runtime/routes/platform-routes.ts

@@ -29,7 +29,7 @@ import {
 } from "../../security/secure-keys.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
-import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
+import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   InternalError,
@@ -360,7 +360,7 @@ export const ROUTES: RouteDefinition[] = [
     method: "GET",
     policy: {
       requiredScopes: ["settings.read"],
-      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Get platform deployment context and connection status",
     description:

package/src/runtime/routes/plugins-routes.ts

@@ -25,6 +25,10 @@
 
 import { z } from "zod";
 
+import {
+  diffPlugin,
+  PluginDiffUnavailableError,
+} from "../../cli/lib/diff-plugin.js";
 import {
   inspectPlugin,
   PluginInspectNotFoundError,
@@ -58,7 +62,9 @@ import {
   uninstallPlugin,
 } from "../../cli/lib/uninstall-plugin.js";
 import {
+  PluginMergeBaselineError,
   PluginNotUpgradableError,
+  type PluginUpgradeStrategy,
   upgradePlugin,
 } from "../../cli/lib/upgrade-plugin.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
@@ -366,6 +372,26 @@ const pluginRemoteInfoSchema = z
   })
   .describe("The marketplace's current pin and advertised metadata.");
 
+const pluginSurfacesSchema = z
+  .object({
+    skills: z
+      .array(z.string())
+      .describe("Skill ids shipped at `skills/<id>/SKILL.md`."),
+    hooks: z
+      .array(z.string())
+      .describe(
+        "Lifecycle hook names from `hooks/<name>.{ts,js}` (e.g. `pre-model-call`).",
+      ),
+    tools: z
+      .array(z.string())
+      .describe(
+        "Registered tool names from `tools/<name>.{ts,js}` (filenames derived to tool names, e.g. `create-issue` \u2192 `create_issue`).",
+      ),
+  })
+  .describe(
+    "Surfaces the installed copy contributes, read from its on-disk tree.",
+  );
+
 const pluginInspectResponseSchema = z.object({
   name: z
     .string()
@@ -401,6 +427,11 @@ const pluginInspectResponseSchema = z.object({
     .describe(
       "Marketplace fetch error message, when the catalog could not be read.",
     ),
+  surfaces: pluginSurfacesSchema
+    .nullable()
+    .describe(
+      "Surfaces the installed copy contributes (skills, hooks, tools); null when the plugin is not installed.",
+    ),
 });
 
 const pluginUpgradeRequestSchema = z.object({
@@ -410,6 +441,12 @@ const pluginUpgradeRequestSchema = z.object({
     .describe(
       "Report what would change without modifying the install. Defaults to false.",
     ),
+  strategy: z
+    .enum(["ours", "theirs", "overwrite", "assistant"])
+    .optional()
+    .describe(
+      "How to reconcile local edits with the pin. `overwrite` (default) discards local edits and re-installs the pin; `ours`/`theirs` three-way merge, resolving conflicting hunks toward the local edit or the pin respectively; `assistant` is not yet supported.",
+    ),
 });
 
 const pluginUpgradeResponseSchema = z.object({
@@ -452,6 +489,19 @@ const pluginUpgradeResponseSchema = z.object({
       "Files materialized by the upgrade; null for a no-op or dry run.",
     ),
   dryRun: z.boolean().describe("Whether this was a dry run (no changes made)."),
+  strategy: z
+    .enum(["ours", "theirs", "overwrite", "assistant"])
+    .describe("Conflict-resolution strategy the upgrade applied."),
+  conflicts: z
+    .array(z.string())
+    .describe(
+      "Paths left for the assistant to resolve under the `assistant` strategy: text files carry git conflict markers, modify/delete divergences keep the surviving content. Empty for other strategies.",
+    ),
+  binaryConflicts: z
+    .array(z.string())
+    .describe(
+      "Binary files that conflicted under the `assistant` strategy; the local copy was kept since markers cannot be written into binary content. Empty for other strategies.",
+    ),
   provenanceWasUnknown: z
     .boolean()
     .describe(
@@ -459,6 +509,62 @@ const pluginUpgradeResponseSchema = z.object({
     ),
 });
 
+const pluginFileDiffSchema = z
+  .object({
+    path: z.string().describe("POSIX-relative path within the plugin root."),
+    status: z
+      .enum(["modified", "added", "removed"])
+      .describe(
+        "Whether the file was edited, newly added, or deleted since install.",
+      ),
+    diff: z
+      .string()
+      .describe(
+        "Unified diff (`--- a/… / +++ b/…`) of the file. A short `Binary files differ` marker for binary files, or a `Baseline unavailable` marker when `reconstructed` is false.",
+      ),
+    binary: z
+      .boolean()
+      .describe(
+        "True when either side was detected as binary (NUL byte present).",
+      ),
+    reconstructed: z
+      .boolean()
+      .describe(
+        "True when the install-time baseline for this file was faithfully recovered (re-materialized bytes hash-match the install fingerprint). False when it could not be reconstructed (e.g. the curated adapter overlay changed since install), in which case `diff` is a marker, not a patch. Always true for added files.",
+      ),
+  })
+  .describe("Unified diff of a single drifted file.");
+
+const pluginDiffResponseSchema = z.object({
+  name: z
+    .string()
+    .describe("Install name. Matches `assistant plugins install <name>`."),
+  target: z
+    .string()
+    .describe("Absolute path to the installed plugin directory on the host."),
+  commit: z
+    .string()
+    .describe(
+      "Commit the baseline was re-materialized from (the recorded install SHA).",
+    ),
+  committedAt: z
+    .string()
+    .nullable()
+    .describe(
+      "ISO-8601 committer timestamp (UTC) of `commit`; null when not recorded.",
+    ),
+  clean: z
+    .boolean()
+    .describe(
+      "True when the on-disk tree exactly matches the re-materialized baseline.",
+    ),
+  files: z
+    .array(pluginFileDiffSchema)
+    .describe(
+      "One entry per drifted file, sorted by path. Empty when `clean`.",
+    ),
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -740,6 +846,45 @@ async function handleInspectPlugin({ pathParams = {} }: RouteHandlerArgs) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Handler — diff
+// ---------------------------------------------------------------------------
+
+async function handleDiffPlugin({ pathParams = {} }: RouteHandlerArgs) {
+  const rawName = pathParams.name ?? "";
+
+  try {
+    return await diffPlugin(
+      { name: rawName },
+      { fetch: globalThis.fetch.bind(globalThis) },
+    );
+  } catch (err) {
+    if (err instanceof InvalidPluginNameError) {
+      throw new BadRequestError(err.message);
+    }
+    if (
+      err instanceof PluginNotInstalledError ||
+      err instanceof PluginNotFoundError
+    ) {
+      throw new NotFoundError(err.message);
+    }
+    // The install exists but recorded no commit to re-materialize a baseline
+    // from — a permanent state the caller cannot resolve by retrying. 409
+    // marks the request as well-formed but not actionable in the current state.
+    if (err instanceof PluginDiffUnavailableError) {
+      throw new ConflictError(err.message);
+    }
+    // A rate-limited or temporarily-down source (the plugin repo) is a
+    // retryable outage, not a conflict — 503.
+    if (err instanceof PluginSourceUnavailableError) {
+      throw new ServiceUnavailableError(err.message);
+    }
+    throw new InternalError(
+      err instanceof Error ? err.message : "plugin diff failed",
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Handler — upgrade
 // ---------------------------------------------------------------------------
@@ -750,6 +895,10 @@ async function handleUpgradePlugin({
 }: RouteHandlerArgs) {
   const rawName = pathParams.name ?? "";
   const dryRun = typeof body.dryRun === "boolean" ? body.dryRun : undefined;
+  const strategy =
+    typeof body.strategy === "string"
+      ? (body.strategy as PluginUpgradeStrategy)
+      : undefined;
 
   // Like install, the upgrade target ref is the curated marketplace pin
   // (resolved inside `upgradePlugin` via `inspectPlugin`), never a
@@ -757,7 +906,7 @@ async function handleUpgradePlugin({
   // upgrade at an unreviewed revision.
   try {
     const result = await upgradePlugin(
-      { name: rawName, dryRun },
+      { name: rawName, dryRun, strategy },
       { fetch: globalThis.fetch.bind(globalThis) },
     );
     return {
@@ -770,6 +919,9 @@ async function handleUpgradePlugin({
       target: result.target,
       fileCount: result.fileCount,
       dryRun: result.dryRun,
+      strategy: result.strategy,
+      conflicts: result.conflicts,
+      binaryConflicts: result.binaryConflicts,
       provenanceWasUnknown: result.provenanceWasUnknown,
     };
   } catch (err) {
@@ -782,6 +934,12 @@ async function handleUpgradePlugin({
     if (err instanceof PluginNotFoundError) {
       throw new NotFoundError(err.message);
     }
+    // A merge strategy was requested but the install-time baseline can't be
+    // reconstructed — a well-formed request that isn't actionable in the
+    // current state (the caller can retry with `overwrite` or reinstall).
+    if (err instanceof PluginMergeBaselineError) {
+      throw new ConflictError(err.message);
+    }
     // The install exists but has no marketplace entry to advance to — a
     // permanent state the caller cannot resolve by retrying. 409 marks the
     // request as well-formed but not actionable in the current state.
@@ -992,6 +1150,47 @@ export const ROUTES: RouteDefinition[] = [
     },
     handler: handleInspectPlugin,
   },
+  {
+    operationId: "plugins_diff",
+    endpoint: "plugins/:name/diff",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Diff a plugin against its install commit",
+    description:
+      "Show a unified diff of local edits to an installed plugin against the exact commit it was installed at (recorded in its `install-meta.json`). Computing the diff re-materializes the baseline through the install pipeline — a network clone plus a temp-dir write — so this is a POST: it is not a safe, cacheable GET even though it leaves persistent state untouched (requires only `settings.read`). Drift is classified against the install-time fingerprint so an adapter overlay that moved since install never reads as a local change. Returns the baseline `commit`, a `clean` flag, and a `files` array of `{ path, status, diff, binary, reconstructed }` for each modified/added/removed file. The baseline is the install commit, not the marketplace pin — comparing against the current pin is `POST /v1/plugins/:name/upgrade` with `dryRun`. A name with no installed copy returns 404; an install that recorded no commit or fingerprint returns 409; an unreachable source returns 503. Mirrors the CLI's `assistant plugins diff <name>`.",
+    tags: ["plugins"],
+    pathParams: [
+      {
+        name: "name",
+        type: "string",
+        description:
+          "Install name. Must match the kebab-case name accepted by `assistant plugins install`.",
+      },
+    ],
+    responseBody: pluginDiffResponseSchema,
+    additionalResponses: {
+      "400": {
+        description:
+          "The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).",
+      },
+      "404": {
+        description:
+          "No copy of the plugin is installed, or its recorded commit resolves to nothing.",
+      },
+      "409": {
+        description:
+          "The install recorded no commit or no fingerprint to re-materialize and verify a baseline from.",
+      },
+      "503": {
+        description:
+          "The plugin source (GitHub) was temporarily unavailable; the diff is retryable.",
+      },
+    },
+    handler: handleDiffPlugin,
+  },
   {
     operationId: "plugins_upgrade",
     endpoint: "plugins/:name/upgrade",
@@ -1002,7 +1201,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Upgrade a plugin to the marketplace pin",
     description:
-      'Move an installed plugin to the marketplace\'s current pinned commit, re-materializing it under `<workspaceDir>/plugins/<name>/`. Always resolves against the curated marketplace pin (no caller-supplied ref), mirroring `plugins install`\'s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching the install. Installs lacking provenance are re-pinned to the current SHA. The assistant must be restarted to load the upgraded code. This does not gate on local edits — callers should consult `GET /v1/plugins/:name/inspect` (`local.localChanges`) first and confirm before overwriting. Mirrors the CLI\'s `assistant plugins upgrade <name>`.',
+      'Move an installed plugin to the marketplace\'s current pinned commit, re-materializing it under `<workspaceDir>/plugins/<name>/`. Always resolves against the curated marketplace pin (no caller-supplied ref), mirroring `plugins install`\'s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching the install. Installs lacking provenance are re-pinned to the current SHA. The assistant must be restarted to load the upgraded code. `strategy` controls how local edits are reconciled: `overwrite` (default) discards them and re-installs the pin wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local edit (`ours`) or the pin (`theirs`), or writing git conflict markers into the file and reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy whose install-time baseline cannot be reconstructed returns 409. Mirrors the CLI\'s `assistant plugins upgrade <name> [--strategy <s>]`.',
     tags: ["plugins"],
     pathParams: [
       {
@@ -1025,7 +1224,7 @@ export const ROUTES: RouteDefinition[] = [
       },
       "409": {
         description:
-          "The install exists but has no marketplace entry to advance to.",
+          "The install exists but has no marketplace entry to advance to, or a merge strategy was requested whose install-time baseline cannot be reconstructed.",
       },
       "503": {
         description: