@vellumai/assistant 0.5.16 → 0.6.1

package/src/daemon/conversation-tool-setup.ts

@@ -7,6 +7,7 @@
  */
 
 import { isHttpAuthDisabled } from "../config/env.js";
+import { getIsPlatform } from "../config/env-registry.js";
 import type { CesClient } from "../credential-execution/client.js";
 import { getBindingByConversation } from "../memory/external-conversation-store.js";
 import {
@@ -192,6 +193,7 @@ export function createToolExecutor(
       toolUseId,
       hostBashProxy: ctx.hostBashProxy,
       hostFileProxy: ctx.hostFileProxy,
+      isPlatformHosted: getIsPlatform(),
       cesClient: ctx.cesClient,
       onToolLifecycleEvent: handleToolLifecycleEvent,
       sendToClient: (msg) => {
@@ -320,8 +322,7 @@ export function createProxyApprovalCallback(
       input.matching_patterns = decision.matchingPatterns;
     }
 
-    const riskLevel =
-      decision.kind === "ask_missing_credential" ? "high" : "medium";
+    const riskLevel: string = "medium";
 
     // Check trust store before prompting — build candidates that mirror
     // buildCommandCandidates() in checker.ts for network_request.
@@ -342,10 +343,7 @@ export function createProxyApprovalCallback(
     );
     if (existingRule && existingRule.decision !== "ask") {
       if (existingRule.decision === "deny") return false;
-      // For high-risk proxy decisions, a plain allow rule (without allowHighRisk)
-      // must fall through to prompting — mirroring the checker's behavior.
-      if (riskLevel !== "high" || existingRule.allowHighRisk === true)
-        return true;
+      return true;
     }
 
     // Use the checker's built-in allowlist generation for network_request
@@ -384,12 +382,13 @@ export function createProxyApprovalCallback(
       response.selectedPattern &&
       response.selectedScope
     ) {
+      const allowHighRisk = response.decision === "always_allow_high_risk";
       log.info(
         {
           toolName,
           pattern: response.selectedPattern,
           scope: response.selectedScope,
-          highRisk: response.decision === "always_allow_high_risk",
+          allowHighRisk,
         },
         "Persisting always-allow trust rule (proxy)",
       );
@@ -399,9 +398,7 @@ export function createProxyApprovalCallback(
         response.selectedScope,
         "allow",
         100,
-        response.decision === "always_allow_high_risk"
-          ? { allowHighRisk: true }
-          : undefined,
+        allowHighRisk ? { allowHighRisk: true } : undefined,
       );
     }
     if (
@@ -436,7 +433,7 @@ export function createProxyApprovalCallback(
  * history or explicit preactivation. Without this, their tools are
  * unavailable in fresh conversations until `skill_load` is called.
  */
-const DEFAULT_PREACTIVATED_SKILL_IDS = ["tasks", "notifications"];
+const DEFAULT_PREACTIVATED_SKILL_IDS = ["tasks", "notifications", "subagent"];
 
 /**
  * Subset of Conversation state that the resolveTools callback reads at each
@@ -454,9 +451,14 @@ export interface SkillProjectionContext {
   readonly channelCapabilities?: {
     channel: string;
     supportsDynamicUi: boolean;
+    clientOS?: string;
   };
   /** True when no client is connected (HTTP-only). */
   readonly hasNoClient?: boolean;
+  /** When set, only tools in this set are included in the resolved tool list (subagent delegation). */
+  subagentAllowedTools?: Set<string>;
+  /** True when this conversation belongs to a subagent spawned by SubagentManager. */
+  readonly isSubagent?: boolean;
 }
 
 // ── Conditional tool sets ────────────────────────────────────────────
@@ -471,6 +473,16 @@ const HOST_TOOL_NAMES = new Set([
 const CLIENT_CAPABILITY_TOOL_NAMES = new Set(["app_open"]);
 const PLATFORM_TOOL_NAMES = new Set(["request_system_permission"]);
 
+/**
+ * Tools that should only be visible to subagent conversations. Main (parent)
+ * conversations never see these in the LLM tool definitions. Subsequent PRs
+ * will populate this set; it starts empty so there is no behavioral change.
+ */
+export const SUBAGENT_ONLY_TOOL_NAMES = new Set<string>([
+  "file_list",
+  "notify_parent",
+]);
+
 /**
  * Determine whether a tool should be included in the LLM tool definitions
  * for the current turn based on conversation context. Tools not active for the
@@ -495,7 +507,12 @@ export function isToolActiveForContext(
     return !ctx.hasNoClient;
   }
   if (PLATFORM_TOOL_NAMES.has(name)) {
-    return process.platform === "darwin" && !ctx.hasNoClient;
+    // Check the *client's* platform, not the daemon's process.platform.
+    // In Docker the daemon runs on Linux but the connected client may be macOS.
+    return ctx.channelCapabilities?.clientOS === "macos" && !ctx.hasNoClient;
+  }
+  if (SUBAGENT_ONLY_TOOL_NAMES.has(name)) {
+    return ctx.isSubagent === true;
   }
   return true;
 }
@@ -548,18 +565,27 @@ export function createResolveToolsCallback(
       isToolActiveForContext(d.name, ctx),
     );
 
+    // When the conversation is acting as a subagent, restrict core tools to
+    // only those explicitly allowed by the parent orchestrator.
+    const scopedCoreDefs = ctx.subagentAllowedTools
+      ? filteredCoreDefs.filter((d) => ctx.subagentAllowedTools!.has(d.name))
+      : filteredCoreDefs;
+
     // Re-read MCP tool definitions from the registry each turn so conversations
     // automatically pick up tools added/removed by `vellum mcp reload`.
     const currentMcpDefs = getMcpToolDefinitions();
     log.debug(
       {
-        coreCount: filteredCoreDefs.length,
+        coreCount: scopedCoreDefs.length,
         mcpCount: currentMcpDefs.length,
         mcpTools: currentMcpDefs.map((d) => d.name),
       },
       "MCP tools resolved for turn",
     );
-    const allBaseDefs = [...filteredCoreDefs, ...currentMcpDefs];
+    const scopedMcpDefs = ctx.subagentAllowedTools
+      ? currentMcpDefs.filter((d) => ctx.subagentAllowedTools!.has(d.name))
+      : currentMcpDefs;
+    const allBaseDefs = [...scopedCoreDefs, ...scopedMcpDefs];
 
     const effectivePreactivated = [
       ...DEFAULT_PREACTIVATED_SKILL_IDS,
@@ -572,6 +598,10 @@ export function createResolveToolsCallback(
     });
     const turnAllowed = new Set(allBaseDefs.map((d) => d.name));
     for (const name of projection.allowedToolNames) {
+      // When a subagent allowlist is active, exclude skill tools not on it.
+      if (ctx.subagentAllowedTools && !ctx.subagentAllowedTools.has(name)) {
+        continue;
+      }
       turnAllowed.add(name);
     }
     ctx.allowedToolNames = turnAllowed;

package/src/daemon/conversation-workspace.ts

@@ -33,8 +33,7 @@ export function refreshWorkspaceTopLevelContextIfNeeded(
     currentConversationPath = `conversations/${resolvedDirName}/`;
   }
   ctx.workspaceTopLevelContext = renderWorkspaceTopLevelContext(snapshot, {
-    currentConversationPath,
-    currentConversationAttachmentsPath: currentConversationPath
+    conversationAttachmentsPath: currentConversationPath
       ? `${currentConversationPath}attachments/`
       : null,
   });

package/src/daemon/conversation.ts

@@ -44,6 +44,7 @@ import { registerToolTraceListener } from "../events/tool-trace-listener.js";
 import { getHookManager } from "../hooks/manager.js";
 import { resolveCanonicalGuardianRequest } from "../memory/canonical-guardian-store.js";
 import { updateConversationContextWindow } from "../memory/conversation-crud.js";
+import { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { SecretPrompter } from "../permissions/secret-prompter.js";
 import { patternMatchesCandidate } from "../permissions/trust-store.js";
@@ -57,6 +58,7 @@ import type { AuthContext } from "../runtime/auth/types.js";
 import * as approvalOverrides from "../runtime/conversation-approval-overrides.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { ToolExecutor } from "../tools/executor.js";
+import { getLogger } from "../util/logger.js";
 import type { AssistantAttachmentDraft } from "./assistant-attachments.js";
 import { runAgentLoopImpl } from "./conversation-agent-loop.js";
 import type { HistoryConversationContext } from "./conversation-history.js";
@@ -118,6 +120,8 @@ import type {
 } from "./message-types/messages.js";
 import { TraceEmitter } from "./trace-emitter.js";
 
+const log = getLogger("conversation");
+
 export interface ConversationMemoryPolicy {
   scopeId: string;
   includeDefaultFallback: boolean;
@@ -156,6 +160,7 @@ export class Conversation {
   /** @internal */ allowedToolNames?: Set<string>;
   /** @internal */ toolsDisabledDepth = 0;
   /** @internal */ preactivatedSkillIds?: string[];
+  /** @internal */ subagentAllowedTools?: Set<string>;
   /** @internal */ coreToolNames: Set<string>;
   /** @internal */ readonly skillProjectionState = new Map<string, string>();
   /** @internal */ readonly skillProjectionCache: SkillProjectionCache = {};
@@ -170,6 +175,7 @@ export class Conversation {
   /** @internal */ contextCompactedAt: number | null = null;
   /** @internal */ currentRequestId?: string;
   /** @internal */ hasNoClient = false;
+  /** @internal */ isSubagent = false;
   /** @internal */ headlessLock = false;
   /** @internal */ taskRunId?: string;
   /** @internal */ callSessionId?: string;
@@ -243,6 +249,9 @@ export class Conversation {
   public readonly traceEmitter: TraceEmitter;
   public readonly hasSystemPromptOverride: boolean;
   public memoryPolicy: ConversationMemoryPolicy;
+  /** @internal */ readonly graphMemory: ConversationGraphMemory;
+  /** @internal */ activeContextNodeIds?: string[];
+  /** @internal */ memoryScopeId?: string;
   /** @internal */ streamThinking: boolean;
   /** @internal */ turnCount = 0;
   public lastAssistantAttachments: AssistantAttachmentDraft[] = [];
@@ -251,6 +260,8 @@ export class Conversation {
   /** @internal */ currentTurnInterfaceContext: TurnInterfaceContext | null =
     null;
   /** @internal */ activityVersion = 0;
+  /** Last emitted activity state message, retained for replay on SSE reconnection. */
+  /** @internal */ lastActivityStateMsg: ServerMessage | null = null;
   /** Set by the agent loop to track confirmation outcomes for persistence. */
   onConfirmationOutcome?: (
     requestId: string,
@@ -270,6 +281,7 @@ export class Conversation {
     memoryPolicy?: ConversationMemoryPolicy,
     sharedCesClient?: CesClient,
     speedOverride?: Speed,
+    cacheTtl?: "5m" | "1h",
   ) {
     this.conversationId = conversationId;
     this.systemPrompt = systemPrompt;
@@ -280,6 +292,10 @@ export class Conversation {
     this.memoryPolicy = memoryPolicy
       ? { ...memoryPolicy }
       : { ...DEFAULT_MEMORY_POLICY };
+    this.graphMemory = new ConversationGraphMemory(
+      this.memoryPolicy.scopeId,
+      conversationId,
+    );
     this.traceEmitter = new TraceEmitter(conversationId, sendToClient);
     this.prompter = new PermissionPrompter(sendToClient);
     this.prompter.setOnStateChanged((requestId, state, source, toolUseId) => {
@@ -404,6 +420,7 @@ export class Conversation {
         ...(fastModeEnabled && resolvedSpeed === "fast"
           ? { speed: resolvedSpeed }
           : {}),
+        ...(cacheTtl ? { cacheTtl } : {}),
       },
       toolDefs.length > 0 ? toolDefs : undefined,
       toolDefs.length > 0 ? toolExecutor : undefined,
@@ -428,6 +445,7 @@ export class Conversation {
   async loadFromDb(): Promise<void> {
     await loadFromDbImpl(this);
     this.restoreSurfaceStateFromHistory();
+    this.graphMemory.restoreState();
   }
 
   /**
@@ -486,6 +504,19 @@ export class Conversation {
       this.hostCuProxy?.updateSender(sendToClient, !hasNoClient);
       this.hostFileProxy?.updateSender(sendToClient, !hasNoClient);
     }
+
+    // Replay last activity state so a reconnecting client sees the current phase
+    // instead of being stuck on the last state it received before disconnection.
+    if (!hasNoClient && this.lastActivityStateMsg) {
+      try {
+        sendToClient(this.lastActivityStateMsg);
+      } catch (err) {
+        log.warn(
+          { err, conversationId: this.conversationId },
+          "Failed to replay activity state on client reconnection",
+        );
+      }
+    }
   }
 
   /** Returns the current sendToClient reference for identity comparison. */
@@ -513,6 +544,14 @@ export class Conversation {
     this.sandboxOverride = enabled;
   }
 
+  setSubagentAllowedTools(tools: Set<string> | undefined): void {
+    this.subagentAllowedTools = tools;
+  }
+
+  setIsSubagent(value: boolean): void {
+    this.isSubagent = value;
+  }
+
   isProcessing(): boolean {
     return this.processing;
   }
@@ -540,6 +579,9 @@ export class Conversation {
     // CES client is owned by DaemonServer — just drop the reference.
     // Do NOT close it here; the server manages the CES lifecycle.
     this.cesClient = undefined;
+    this.activeContextNodeIds = this.graphMemory.tracker.getActiveNodeIds();
+    this.memoryScopeId = this.memoryPolicy.scopeId;
+    this.graphMemory.persistState();
     disposeConversation(this);
   }
 
@@ -862,7 +904,14 @@ export class Conversation {
       type: "confirmation_state_changed",
       ...params,
     } as ServerMessage;
-    this.sendToClient(msg);
+    try {
+      this.sendToClient(msg);
+    } catch (err) {
+      log.warn(
+        { err, conversationId: this.conversationId },
+        "sendToClient threw in emitConfirmationStateChanged",
+      );
+    }
   }
 
   emitActivityState(
@@ -883,7 +932,15 @@ export class Conversation {
       reason,
       ...(statusText ? { statusText } : {}),
     } as ServerMessage;
-    this.sendToClient(msg);
+    this.lastActivityStateMsg = msg;
+    try {
+      this.sendToClient(msg);
+    } catch (err) {
+      log.warn(
+        { err, conversationId: this.conversationId },
+        "sendToClient threw in emitActivityState",
+      );
+    }
   }
 
   async forceCompact(): Promise<ContextWindowResult> {

package/src/daemon/daemon-control.ts

@@ -12,12 +12,14 @@ import { resolve } from "node:path";
 import { getRuntimeHttpHost, getRuntimeHttpPort } from "../config/env.js";
 import { getIsContainerized } from "../config/env-registry.js";
 import { loadOrCreateSigningKey } from "../runtime/auth/token-service.js";
+import { ensureBun } from "../util/bun-runtime.js";
 import { DaemonError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import {
   ensureDataDir,
   getDaemonStartupLockPath,
   getDaemonStderrLogPath,
+  getDataDir,
   getPidPath,
   getWorkspaceConfigPath,
 } from "../util/platform.js";
@@ -371,6 +373,10 @@ async function startDaemonLocked(): Promise<{
     }
   }
 
+  // Resolve bun before opening stderrFd to avoid leaking the file
+  // descriptor if ensureBun() throws (same pattern as loadOrCreateSigningKey).
+  const bunPath = await ensureBun();
+
   // Redirect the child's stderr to a file instead of piping it back to the
   // parent. A pipe's read end is destroyed when the parent exits, leaving
   // fd 2 broken in the child. Bun (unlike Node.js) does not ignore SIGPIPE,
@@ -378,7 +384,7 @@ async function startDaemonLocked(): Promise<{
   const stderrPath = getDaemonStderrLogPath();
   const stderrFd = openSync(stderrPath, "w");
 
-  const child = spawn("bun", ["run", mainPath], {
+  const child = spawn(bunPath, ["run", mainPath], {
     detached: true,
     stdio: ["ignore", "ignore", stderrFd],
     env: spawnEnv,
@@ -413,7 +419,7 @@ async function startDaemonLocked(): Promise<{
       const stderr = readFileSync(stderrPath, "utf-8").trim();
       const detail = stderr
         ? `\n${stderr}`
-        : `\nCheck logs at ~/.vellum/workspace/data/logs/ for details.`;
+        : `\nCheck logs at ${getDataDir()}/logs/ for details.`;
       throw new DaemonError(
         `Daemon exited immediately (code ${
           childExitCode ?? "unknown"

package/src/daemon/date-context.ts

@@ -290,31 +290,14 @@ function formatLocalDate(date: Date, timeZone: string): string {
 }
 
 /**
- * Format HH:MM and UTC offset for the given instant in the given timezone.
- */
-function formatCompactTimeAndOffset(
-  date: Date,
-  timeZone: string,
-): { time: string; offset: string } {
-  const fmt = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    hour: "2-digit",
-    minute: "2-digit",
-    hourCycle: "h23",
-    timeZoneName: "shortOffset",
-  });
-  const parts = fmt.formatToParts(date);
-  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
-  const hour = get("hour");
-  const minute = get("minute");
-  const offset = normalizeOffsetToken(get("timeZoneName"));
-  return { time: `${hour}:${minute}`, offset };
-}
-
-/**
- * Build a compact temporal context string for model injection.
+ * Format time as HH:MM:SS with UTC offset and timezone name.
+ *
+ * Uses the timezone resolution cascade:
+ * explicit override → configured user tz → profile user tz → host fallback.
+ *
+ * Returns format: `2026-04-02 (Thu) 01:52:33 -05:00 (America/Chicago)`
  */
-export function buildTemporalContext(
+export function formatTurnTimestamp(
   options: TemporalContextOptions = {},
 ): string {
   const now = new Date(options.nowMs ?? Date.now());
@@ -336,36 +319,26 @@ export function buildTemporalContext(
     resolvedConfiguredUserTimeZone ??
     resolvedUserTimeZone ??
     resolvedHostTimeZone;
-  const userTimeZone = resolvedConfiguredUserTimeZone ?? resolvedUserTimeZone;
-  const timeZoneSource = resolvedTimeZone
-    ? "explicit_override"
-    : resolvedConfiguredUserTimeZone
-      ? "user_settings"
-      : resolvedUserTimeZone
-        ? "user_profile_memory"
-        : "assistant_host_fallback";
-  const todayParts = localDateParts(now, timeZone);
-  const todayStr = formatLocalDate(now, timeZone);
-  const todayWeekday = WEEKDAY_SHORT[todayParts.weekday];
-  const { time, offset } = formatCompactTimeAndOffset(now, timeZone);
-
-  const tzSuffix =
-    timeZoneSource === "assistant_host_fallback" ? " (host fallback)" : "";
 
-  const lines = [
-    `<temporal_context>`,
-    `Today: ${todayStr} (${todayWeekday}) ${time} ${offset}`,
-    `TZ: ${timeZone}${tzSuffix}`,
-  ];
-
-  if (userTimeZone && userTimeZone !== timeZone) {
-    lines.push(`User TZ: ${userTimeZone}`);
-  }
-  if (resolvedHostTimeZone !== timeZone) {
-    lines.push(`Host TZ: ${resolvedHostTimeZone}`);
-  }
+  const dateStr = formatLocalDate(now, timeZone);
+  const todayParts = localDateParts(now, timeZone);
+  const dayName = WEEKDAY_SHORT[todayParts.weekday];
 
-  lines.push(`</temporal_context>`);
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23",
+    timeZoneName: "shortOffset",
+  });
+  const parts = fmt.formatToParts(now);
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+  const hour = get("hour");
+  const minute = get("minute");
+  const second = get("second");
+  const offset = normalizeOffsetToken(get("timeZoneName"));
 
-  return lines.join("\n");
+  return `${dateStr} (${dayName}) ${hour}:${minute}:${second} ${offset} (${timeZone})`;
 }
+

package/src/daemon/first-greeting.ts

@@ -8,7 +8,7 @@ import { getWorkspacePromptPath } from "../util/platform.js";
  * time," "I'm ready to be useful," and "you're in control."
  */
 export const CANNED_FIRST_GREETING =
-  "Hey. I'm brand new, no name, no memories, nothing yet. The more we work together, the more context and memory I build, and the better I get. But let's not wait around. Throw a question at me, give me a task, or ask what I can do.";
+  "Hey, I'm brand new. No name, no memories, nothing yet. Think of me like a new colleague on their first day: I'll get better the more we work together. First things first, let's figure out how we work best. What should I call you?";
 
 /**
  * Returns `true` when all of the following are true:

package/src/daemon/handlers/conversations.ts

@@ -103,13 +103,10 @@ export function makeEventSender(params: {
             guardianPrincipalId: trustContext?.guardianPrincipalId ?? undefined,
             toolName: event.toolName,
             commandPreview:
-              redactSecrets(
-                summarizeToolInput(event.toolName, inputRecord),
-              ) || undefined,
+              redactSecrets(summarizeToolInput(event.toolName, inputRecord)) ||
+              undefined,
             riskLevel: event.riskLevel,
-            activityText: activityRaw
-              ? redactSecrets(activityRaw)
-              : undefined,
+            activityText: activityRaw ? redactSecrets(activityRaw) : undefined,
             executionTarget: event.executionTarget,
             status: "pending",
             requestCode: generateCanonicalRequestCode(),
@@ -304,7 +301,7 @@ export async function handleConversationCreate(
     // Only create the host bash proxy for desktop client interfaces that can
     // execute commands on the user's machine. Set before updateClient so
     // updateClient's call to hostBashProxy.updateSender targets the new proxy.
-    if (transportInterface === "macos" || transportInterface === "ios") {
+    if (transportInterface === "macos") {
       const proxy = new HostBashProxy(sendEvent, (requestId) => {
         pendingInteractions.resolve(requestId);
       });

package/src/daemon/handlers/shared.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+
+import { compareSemver } from "./shared.js";
+
+describe("compareSemver", () => {
+  // ── Basic numeric comparison ──────────────────────────────────────
+  test("equal versions return 0", () => {
+    expect(compareSemver("1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("higher major returns positive", () => {
+    expect(compareSemver("2.0.0", "1.0.0")).toBeGreaterThan(0);
+  });
+
+  test("lower major returns negative", () => {
+    expect(compareSemver("1.0.0", "2.0.0")).toBeLessThan(0);
+  });
+
+  test("higher minor returns positive", () => {
+    expect(compareSemver("1.3.0", "1.2.0")).toBeGreaterThan(0);
+  });
+
+  test("higher patch returns positive", () => {
+    expect(compareSemver("1.2.4", "1.2.3")).toBeGreaterThan(0);
+  });
+
+  // ── v/V prefix handling ───────────────────────────────────────────
+  test("strips v prefix", () => {
+    expect(compareSemver("v1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("strips V prefix", () => {
+    expect(compareSemver("V1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("compares with mixed v prefix", () => {
+    expect(compareSemver("v2.0.0", "1.0.0")).toBeGreaterThan(0);
+  });
+
+  // ── Pre-release vs release ────────────────────────────────────────
+  test("pre-release sorts lower than release", () => {
+    expect(compareSemver("0.6.0-staging.1", "0.6.0")).toBeLessThan(0);
+  });
+
+  test("release sorts higher than pre-release", () => {
+    expect(compareSemver("0.6.0", "0.6.0-staging.1")).toBeGreaterThan(0);
+  });
+
+  test("both without pre-release and same version return 0", () => {
+    expect(compareSemver("0.6.0", "0.6.0")).toBe(0);
+  });
+
+  // ── Pre-release numeric comparison ────────────────────────────────
+  test("staging.1 < staging.2", () => {
+    expect(compareSemver("0.6.0-staging.1", "0.6.0-staging.2")).toBeLessThan(0);
+  });
+
+  test("staging.10 > staging.2 (numeric, not lexical)", () => {
+    expect(
+      compareSemver("0.6.0-staging.10", "0.6.0-staging.2"),
+    ).toBeGreaterThan(0);
+  });
+
+  test("equal pre-release returns 0", () => {
+    expect(compareSemver("0.6.0-staging.5", "0.6.0-staging.5")).toBe(0);
+  });
+
+  // ── Pre-release lexical comparison ────────────────────────────────
+  test("alpha < beta (lexical)", () => {
+    expect(compareSemver("1.0.0-alpha", "1.0.0-beta")).toBeLessThan(0);
+  });
+
+  test("rc < staging (lexical)", () => {
+    expect(compareSemver("1.0.0-rc", "1.0.0-staging")).toBeLessThan(0);
+  });
+
+  // ── Pre-release fewer identifiers sorts earlier ───────────────────
+  test("fewer pre-release identifiers sorts earlier", () => {
+    expect(compareSemver("1.0.0-alpha", "1.0.0-alpha.1")).toBeLessThan(0);
+  });
+
+  // ── Mixed numeric vs non-numeric per §11.4.4 ─────────────────────
+  test("numeric identifier sorts lower than non-numeric", () => {
+    expect(compareSemver("1.0.0-1", "1.0.0-alpha")).toBeLessThan(0);
+  });
+
+  test("non-numeric identifier sorts higher than numeric", () => {
+    expect(compareSemver("1.0.0-alpha", "1.0.0-1")).toBeGreaterThan(0);
+  });
+
+  // ── Multi-segment pre-release ─────────────────────────────────────
+  test("multi-segment pre-release comparison", () => {
+    expect(
+      compareSemver("1.0.0-alpha.beta.1", "1.0.0-alpha.beta.2"),
+    ).toBeLessThan(0);
+  });
+
+  // ── Hyphenated pre-release identifiers ────────────────────────────
+  test("pre-release with multiple hyphens", () => {
+    expect(
+      compareSemver("1.0.0-pre-release-1", "1.0.0-pre-release-2"),
+    ).toBeLessThan(0);
+  });
+
+  // ── Different major.minor.patch trumps pre-release ────────────────
+  test("higher patch wins regardless of pre-release", () => {
+    expect(compareSemver("0.6.1", "0.6.0-staging.99")).toBeGreaterThan(0);
+  });
+
+  test("lower patch loses regardless of pre-release absence", () => {
+    expect(compareSemver("0.5.9", "0.6.0-staging.1")).toBeLessThan(0);
+  });
+
+  // ── Edge cases ────────────────────────────────────────────────────
+  test("missing segments default to 0", () => {
+    expect(compareSemver("1", "1.0.0")).toBe(0);
+  });
+
+  test("two-segment version", () => {
+    expect(compareSemver("1.2", "1.2.0")).toBe(0);
+  });
+
+  // ── Sort integration ──────────────────────────────────────────────
+  test("Array.sort produces correct semver order", () => {
+    const versions = [
+      "0.6.0",
+      "0.6.0-staging.2",
+      "0.5.9",
+      "0.6.0-staging.10",
+      "v0.6.0-staging.1",
+      "0.6.1",
+    ];
+    const sorted = [...versions].sort(compareSemver);
+    expect(sorted).toEqual([
+      "0.5.9",
+      "v0.6.0-staging.1",
+      "0.6.0-staging.2",
+      "0.6.0-staging.10",
+      "0.6.0",
+      "0.6.1",
+    ]);
+  });
+});