@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/src/runtime/effective-capabilities.ts

@@ -0,0 +1,84 @@
+/**
+ * Effective capabilities — trust-class capabilities COMPOSED with runtime context.
+ *
+ * `resolveCapabilities` (`capabilities.ts`) answers "what may this trust class
+ * do" from the actor's class alone, and stays deliberately pure (no context
+ * dependencies) so it remains the single fail-closed trust boundary. Some real
+ * decisions additionally depend on runtime context — the channel a request
+ * arrived on, surface actions, task authorization, a feature flag. Those
+ * compositions belong here, in named/testable helpers, rather than re-derived
+ * inline at each call site (which scatters a single policy across the codebase).
+ *
+ * Scope: this module composes capabilities with *actor/request* context. It does
+ * not read global config or feature flags itself — callers resolve those and
+ * pass the result in (e.g. `lockdownEnabled`), keeping this layer focused on the
+ * capability composition. `resolveRoutingState` in `trust-context-resolver.ts`
+ * is the same shape (capability + guardian-route context → `promptWaitingAllowed`)
+ * and predates this module; it stays where it is.
+ */
+import type { TrustClass } from "./actor-trust-resolver.js";
+import { resolveCapabilities } from "./capabilities.js";
+
+type RawTrustClass = TrustClass | (string & {}) | undefined;
+
+/**
+ * Channels that are themselves privileged document surfaces. Actors on these get
+ * privileged document access regardless of trust class — the `vellum` first-party
+ * console is the operator's own surface, not an external contact channel.
+ */
+const PRIVILEGED_DOCUMENT_CHANNELS = new Set<string>(["vellum"]);
+
+/**
+ * Whether an actor may perform privileged (non-conversation-scoped) document
+ * operations. True when the trust class grants it OR the request arrived on a
+ * privileged channel.
+ */
+export function canActOnPrivilegedDocuments(actor: {
+  trustClass: RawTrustClass;
+  executionChannel?: string;
+}): boolean {
+  return (
+    resolveCapabilities(actor.trustClass).canAccessPrivilegedDocuments ||
+    (actor.executionChannel != null &&
+      PRIVILEGED_DOCUMENT_CHANNELS.has(actor.executionChannel))
+  );
+}
+
+/**
+ * Whether the CES shell lockdown applies to this actor. Active when the lockdown
+ * flag is enabled AND the actor's trust class cannot run an unsandboxed shell.
+ * Callers resolve the flag (`isCesShellLockdownEnabled(config)`) and pass it in.
+ */
+export function isUntrustedShellLockdownActive(actor: {
+  trustClass: RawTrustClass;
+  lockdownEnabled: boolean;
+}): boolean {
+  return (
+    actor.lockdownEnabled &&
+    !resolveCapabilities(actor.trustClass).canRunUnsandboxedShell
+  );
+}
+
+/**
+ * Whether an archive-by-sender invocation is authorized. Any one of a surface
+ * action, a task-batch authorization, or an explicit prompt approval suffices.
+ * Absent those, the actor's own `user_approved` flag only counts when its trust
+ * class may self-authorize archive-by-sender.
+ */
+export function isArchiveBySenderAuthorized(args: {
+  trustClass: RawTrustClass;
+  triggeredBySurfaceAction?: boolean;
+  batchAuthorizedByTask?: boolean;
+  approvedViaPrompt?: boolean;
+  userApproved?: boolean;
+}): boolean {
+  const selfAuthorized =
+    args.userApproved === true &&
+    resolveCapabilities(args.trustClass).canSelfAuthorizeArchiveBySender;
+  return (
+    args.triggeredBySurfaceAction === true ||
+    args.batchAuthorizedByTask === true ||
+    args.approvedViaPrompt === true ||
+    selfAuthorized
+  );
+}

package/src/runtime/guardian-reply-router.ts

@@ -30,6 +30,7 @@ import {
   type CanonicalGuardianRequest,
   getCanonicalGuardianRequest,
   getCanonicalGuardianRequestByCode,
+  getPendingCanonicalRequestByDestinationMessage,
   isRequestExpired,
   listCanonicalGuardianRequests,
 } from "../memory/canonical-guardian-store.js";
@@ -47,6 +48,7 @@ import type {
   ApprovalConversationContext,
   ApprovalConversationGenerator,
 } from "./http-types.js";
+import { parseReactionCallbackData } from "./routes/channel-route-shared.js";
 
 const log = getLogger("guardian-reply-router");
 
@@ -54,6 +56,26 @@ const log = getLogger("guardian-reply-router");
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * How to scope a guardian's pending requests when resolving an inbound reply.
+ * The three states are mutually exclusive and named so the security-critical
+ * `blocked` cannot be confused with the absence of a hint:
+ *
+ *   - `scoped`: resolve only these request ids, and constrain request-code
+ *     routing to this set (delivery-/conversation-scoped hints).
+ *   - `blocked`: fail closed — no pending requests and no identity fallback.
+ *     The Slack cross-chat guard: a guardian's unrelated message in a chat
+ *     where no card was delivered must not resolve a request delivered
+ *     elsewhere. Explicit callbacks and request codes still work (they carry
+ *     their own request id).
+ *   - `identity-fallback`: discover pending requests by guardian identity,
+ *     conversation, or principal. The default when no scope is supplied.
+ */
+export type GuardianPendingScope =
+  | { mode: "scoped"; requestIds: string[] }
+  | { mode: "blocked" }
+  | { mode: "identity-fallback" };
+
 /** Context for an inbound message that may be a guardian reply. */
 export interface GuardianReplyContext {
   /** The raw message text (trimmed). */
@@ -66,8 +88,18 @@ export interface GuardianReplyContext {
   conversationId: string;
   /** Callback data from button presses (e.g. `apr:<requestId>:<action>`). */
   callbackData?: string;
-  /** IDs of known pending canonical requests for this guardian. */
-  pendingRequestIds?: string[];
+  /**
+   * For emoji-reaction decisions (`callbackData` of `reaction:<emoji>`): the
+   * channel-native id (e.g. Slack `ts`) of the message the reaction was
+   * attached to. Used to recover the target request from its delivery record.
+   */
+  reactedMessageTs?: string;
+  /**
+   * How to scope this guardian's pending requests (see {@link
+   * GuardianPendingScope}). Omitted is equivalent to
+   * `{ mode: "identity-fallback" }`.
+   */
+  pendingScope?: GuardianPendingScope;
   /** Conversation generator for NL classification (injected by daemon). */
   approvalConversationGenerator?: ApprovalConversationGenerator;
   /** Optional channel delivery context for resolver-driven side effects. */
@@ -204,30 +236,33 @@ function parseRequestCode(
 /** Find all pending canonical requests for a guardian actor. */
 function findPendingCanonicalRequests(
   actor: ActorContext,
-  pendingRequestIds?: string[],
+  scope: GuardianPendingScope,
   conversationId?: string,
 ): CanonicalGuardianRequest[] {
+  // `blocked` fails closed: no pending requests and no identity fallback — the
+  // Slack cross-chat hijack guard.
+  if (scope.mode === "blocked") {
+    return [];
+  }
+
   let results: CanonicalGuardianRequest[];
 
-  // When explicit IDs are provided, look them up directly
-  if (pendingRequestIds) {
-    if (pendingRequestIds.length === 0) {
-      return [];
-    }
-    results = pendingRequestIds
+  if (scope.mode === "scoped") {
+    // Resolve exactly the supplied ids.
+    results = scope.requestIds
       .map(getCanonicalGuardianRequest)
       .filter((r): r is CanonicalGuardianRequest => r?.status === "pending");
   } else if (actor.actorExternalUserId) {
-    // Query by guardian identity when available
+    // identity-fallback: query by guardian identity when available
     results = listCanonicalGuardianRequests({
       status: "pending",
       guardianExternalUserId: actor.actorExternalUserId,
     });
   } else if (conversationId) {
-    // Actors without an actorExternalUserId: scope by conversationId so the NL
-    // path can discover pending requests bound to this conversation.
-    // Include guardianPrincipalId filter when available so the guardian only
-    // sees requests they are authorized to act on.
+    // identity-fallback without an actorExternalUserId: scope by conversationId
+    // so the NL path can discover pending requests bound to this conversation.
+    // Include guardianPrincipalId when available so the guardian only sees
+    // requests they are authorized to act on.
     results = listCanonicalGuardianRequests({
       status: "pending",
       conversationId,
@@ -236,9 +271,8 @@ function findPendingCanonicalRequests(
         : {}),
     });
   } else if (actor.guardianPrincipalId) {
-    // Actors with a guardianPrincipalId but no actorExternalUserId or
-    // conversationId: query by principal so desktop sessions can still
-    // discover pending guardian work via their bound principal.
+    // identity-fallback by principal: desktop sessions discover pending
+    // guardian work via their bound principal.
     results = listCanonicalGuardianRequests({
       status: "pending",
       guardianPrincipalId: actor.guardianPrincipalId,
@@ -284,22 +318,68 @@ export async function routeGuardianReply(
 ): Promise<GuardianReplyResult> {
   const {
     messageText,
+    channel,
     actor,
     conversationId,
     callbackData,
+    reactedMessageTs,
     approvalConversationGenerator,
     channelDeliveryContext,
     emissionContext,
   } = ctx;
+
+  // ── 0. Reaction decisions (emoji on a delivered approval card) ──
+  // A reaction carries an emoji plus the message it is attached to. Map the
+  // emoji to an action and recover the target request from that card's
+  // delivery record. Addressing by the reacted message disambiguates precisely
+  // even when several cards are pending in the same chat, so — unlike the
+  // text/NL paths — no clarification prompt is ever needed. `reaction_removed`
+  // never expresses intent and is filtered out before reaching the router.
+  if (
+    callbackData?.startsWith("reaction:") &&
+    !callbackData.startsWith("reaction_removed:")
+  ) {
+    const reaction = parseReactionCallbackData(callbackData);
+    const guardianChatId = channelDeliveryContext?.guardianChatId;
+    if (!reaction || !reactedMessageTs || !guardianChatId) {
+      // Unknown emoji, or missing addressing context — not an actionable
+      // approval reaction. Leave it for the caller to persist as a transcript
+      // signal (it must not trigger an agent turn).
+      return notConsumed();
+    }
+    const request = getPendingCanonicalRequestByDestinationMessage(
+      channel,
+      guardianChatId,
+      reactedMessageTs,
+    );
+    if (!request) {
+      // The reacted message is not a known pending approval card (a stray
+      // reaction, or one whose request was already resolved). Never approve
+      // off an unrecognized message.
+      return notConsumed();
+    }
+    return applyDecision(
+      request.id,
+      reaction.action,
+      actor,
+      undefined,
+      channelDeliveryContext,
+      emissionContext,
+    );
+  }
+
+  const pendingScope: GuardianPendingScope = ctx.pendingScope ?? {
+    mode: "identity-fallback",
+  };
   const pendingRequests = findPendingCanonicalRequests(
     actor,
-    ctx.pendingRequestIds,
+    pendingScope,
     conversationId,
   );
+  // Request codes carry their own id, so constrain them only under an explicit
+  // scope; under blocked/identity-fallback they still resolve cross-chat.
   const scopedPendingRequestIds =
-    ctx.pendingRequestIds && ctx.pendingRequestIds.length > 0
-      ? new Set(ctx.pendingRequestIds)
-      : null;
+    pendingScope.mode === "scoped" ? new Set(pendingScope.requestIds) : null;
 
   // ── 1. Deterministic callback parsing (button presses) ──
   // No conversationId scoping here — the guardian's reply comes from a
@@ -800,6 +880,7 @@ function resolveRequestInstructionMode(
 type CanonicalFailureReason =
   | "already_resolved"
   | "identity_mismatch"
+  | "request_misconfigured"
   | "invalid_action"
   | "expired";
 
@@ -819,6 +900,10 @@ function failureReplyText(
       return "This request has expired.";
     case "identity_mismatch":
       return "You don't have permission to decide on this request.";
+    case "request_misconfigured":
+      // The actor is authorized; the request record itself is incomplete
+      // (e.g. missing its bound principal). Do not imply a permission problem.
+      return "Something went wrong with this request on our end, so I couldn't apply your decision.";
     case "invalid_action":
       return buildGuardianInvalidActionReply(
         resolveRequestInstructionMode(request),

package/src/runtime/invite-redemption-service.ts

@@ -164,20 +164,12 @@ export function redeemInvite(params: {
     // Sentinel error used to trigger a transaction rollback when the invite
     // was concurrently revoked/expired between pre-validation and write time.
     const STALE_INVITE = Symbol("stale_invite");
-    const canonicalMemberId = existingChannel.externalUserId
-      ? canonicalizeInboundIdentity(
-          sourceChannel as ChannelId,
-          existingChannel.externalUserId,
-        )
-      : null;
+    const canonicalMemberId = existingChannel.address;
     const canonicalCallerId = externalUserId
       ? canonicalizeInboundIdentity(sourceChannel as ChannelId, externalUserId)
       : null;
-    const memberMatchesSender = !!(
-      canonicalMemberId &&
-      canonicalCallerId &&
-      canonicalMemberId === canonicalCallerId
-    );
+    const memberMatchesSender =
+      !!canonicalCallerId && canonicalMemberId === canonicalCallerId;
     const preservedDisplayName =
       memberMatchesSender && existingContact?.displayName?.trim().length
         ? existingContact.displayName
@@ -542,20 +534,12 @@ export function redeemInviteByCode(params: {
   // an invite use atomically.
   if (existingChannel && !targetMismatch) {
     const STALE_INVITE_REACTIVATE = Symbol("stale_invite_reactivate");
-    const canonicalMemberId = existingChannel.externalUserId
-      ? canonicalizeInboundIdentity(
-          sourceChannel as ChannelId,
-          existingChannel.externalUserId,
-        )
-      : null;
+    const canonicalMemberId = existingChannel.address;
     const canonicalCallerId = externalUserId
       ? canonicalizeInboundIdentity(sourceChannel as ChannelId, externalUserId)
       : null;
-    const memberMatchesSender = !!(
-      canonicalMemberId &&
-      canonicalCallerId &&
-      canonicalMemberId === canonicalCallerId
-    );
+    const memberMatchesSender =
+      !!canonicalCallerId && canonicalMemberId === canonicalCallerId;
     const preservedDisplayName =
       memberMatchesSender && existingContact?.displayName?.trim().length
         ? existingContact.displayName

package/src/runtime/migrations/__tests__/vbundle-builder-fd-leak.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Regression test for descriptor hygiene in the vbundle export path.
+ *
+ * `streamExportVBundle` opens every file in the workspace twice — once to hash
+ * it (Pass 1) and once to stream it into the tar (Pass 2). This test pins the
+ * invariant that those reads release their descriptors: the number of open
+ * descriptors held by the process must not grow proportionally to the number
+ * of files exported. Without that guarantee a workspace-sized export exhausts
+ * the daemon's descriptor limit (EMFILE) and every subsequent subprocess spawn
+ * fails.
+ *
+ * Descriptor counting uses `/proc/self/fd`, which only exists on Linux. The
+ * assertion is skipped on platforms without it (e.g. macOS dev machines); CI
+ * runs on Linux, so the regression stays covered there.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { assertNotLiveDb } from "../../../__tests__/assert-not-live-db.js";
+import { streamExportVBundle } from "../vbundle-builder.js";
+import { defaultV1Options } from "./v1-test-helpers.js";
+
+const PROC_SELF_FD = "/proc/self/fd";
+const hasProcFd = existsSync(PROC_SELF_FD);
+
+/** Count the descriptors currently open by this process. */
+function openFdCount(): number {
+  return readdirSync(PROC_SELF_FD).length;
+}
+
+/**
+ * Build a workspace with enough distinct files (across nested directories) that
+ * a per-file descriptor leak would be obvious against the assertion bound.
+ */
+function createPopulatedWorkspace(fileCount: number): {
+  dir: string;
+  cleanup: () => void;
+} {
+  const dir = join(
+    tmpdir(),
+    `vbundle-fd-leak-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "config.json"), JSON.stringify({ test: true }));
+  const dbDir = join(dir, "data", "db");
+  mkdirSync(dbDir, { recursive: true });
+  writeFileSync(join(dbDir, "assistant.db"), "fake-db-content");
+
+  // A spread of files under a few nested directories, each with non-trivial
+  // (multi-chunk) content so the read loop iterates more than once.
+  const filler = "x".repeat(200 * 1024);
+  for (let i = 0; i < fileCount; i++) {
+    const sub = join(dir, "data", "files", `dir-${i % 5}`);
+    mkdirSync(sub, { recursive: true });
+    writeFileSync(join(sub, `file-${i}.txt`), `${filler}\n${i}`);
+  }
+
+  return {
+    dir,
+    cleanup: () => {
+      assertNotLiveDb(dir);
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("streamExportVBundle — descriptor lifecycle", () => {
+  test.skipIf(!hasProcFd)(
+    "does not leak a file descriptor per exported file",
+    async () => {
+      const fileCount = 60;
+      const workspace = createPopulatedWorkspace(fileCount);
+
+      // Warm-up export: first run can open and cache descriptors that legitimately
+      // persist (loggers, the daemon DB, etc.). Measuring the delta around a
+      // second export isolates per-file leakage from one-time setup.
+      let warmup: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
+      try {
+        warmup = await streamExportVBundle({
+          workspaceDir: workspace.dir,
+          ...defaultV1Options(),
+        });
+      } finally {
+        await warmup?.cleanup();
+      }
+
+      const before = openFdCount();
+
+      let result: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
+      try {
+        result = await streamExportVBundle({
+          workspaceDir: workspace.dir,
+          ...defaultV1Options(),
+        });
+        // Manifest covers every file we wrote — proves the walk actually read
+        // them (otherwise a no-op export would trivially leak nothing).
+        expect(result.manifest.contents.length).toBeGreaterThanOrEqual(
+          fileCount,
+        );
+      } finally {
+        await result?.cleanup();
+        workspace.cleanup();
+      }
+
+      const after = openFdCount();
+      const delta = after - before;
+
+      // Each export reads 2×fileCount files (hash pass + tar pass). A per-file
+      // leak would push the delta past `fileCount`. Allow a small constant for
+      // incidental descriptors (temp output file already cleaned up, jitter).
+      expect(delta).toBeLessThan(8);
+    },
+  );
+});

package/src/runtime/migrations/vbundle-builder.ts

@@ -11,7 +11,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
   closeSync,
-  createReadStream,
   createWriteStream,
   existsSync,
   lstatSync,
@@ -21,7 +20,7 @@ import {
   readSync,
   realpathSync,
 } from "node:fs";
-import { stat, unlink } from "node:fs/promises";
+import { type FileHandle, open, stat, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -886,9 +885,10 @@ export function walkDirectoryForMetadata(
 }
 
 /**
- * Compute SHA-256 hex digest of a file by streaming — never buffers the
- * entire file in memory. When `size` is provided, only hashes the first
- * `size` bytes to match what will be archived in the tar entry.
+ * Compute SHA-256 hex digest of a file by reading it in bounded chunks —
+ * never buffers the entire file in memory. When `size` is provided, only
+ * hashes the first `size` bytes to match what will be archived in the tar
+ * entry.
  */
 async function computeFileSha256(
   filePath: string,
@@ -896,11 +896,28 @@ async function computeFileSha256(
 ): Promise<string> {
   const hash = createHash("sha256");
   if (size === 0) return hash.digest("hex");
-  const streamOpts =
-    size !== undefined ? { start: 0, end: size - 1 } : undefined;
-  const stream = createReadStream(filePath, streamOpts);
-  for await (const chunk of stream) {
-    hash.update(chunk);
+
+  // Read through an explicitly-managed FileHandle so the descriptor is
+  // always released in `finally`. This pass opens every file in the
+  // workspace, so any per-file descriptor leak here would exhaust the
+  // daemon's file-descriptor limit (EMFILE). A bounded read loop keeps peak
+  // memory flat regardless of file size.
+  const readChunkBytes = 64 * 1024;
+  const handle = await open(filePath, "r");
+  try {
+    const chunk = Buffer.allocUnsafe(readChunkBytes);
+    let position = 0;
+    for (;;) {
+      const remaining = size !== undefined ? size - position : Infinity;
+      if (remaining <= 0) break;
+      const toRead = Math.min(chunk.length, remaining);
+      const { bytesRead } = await handle.read(chunk, 0, toRead, position);
+      if (bytesRead === 0) break;
+      hash.update(chunk.subarray(0, bytesRead));
+      position += bytesRead;
+    }
+  } finally {
+    await handle.close();
   }
   return hash.digest("hex");
 }
@@ -1056,21 +1073,33 @@ async function* generateTarStream(
       // alignment. The WAL checkpoint before export is the primary
       // consistency mechanism for the database.
       let bytesWritten = 0;
-      if (file.size > 0) {
+      if (entrySize > 0) {
+        // Read through an explicitly-managed FileHandle so the descriptor is
+        // released in `finally` even when the consumer abandons the generator
+        // mid-file. Each read uses a fresh buffer so a yielded chunk is never
+        // overwritten by the next read before the consumer drains it.
+        let handle: FileHandle | undefined;
         try {
-          const stream = createReadStream(file.diskPath, {
-            start: 0,
-            end: file.size - 1,
-          });
-          for await (const chunk of stream) {
-            const data =
-              chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
-            bytesWritten += data.length;
-            yield data;
+          handle = await open(file.diskPath, "r");
+          const readChunkBytes = 64 * 1024;
+          while (bytesWritten < entrySize) {
+            const toRead = Math.min(readChunkBytes, entrySize - bytesWritten);
+            const buf = Buffer.allocUnsafe(toRead);
+            const { bytesRead } = await handle.read(
+              buf,
+              0,
+              toRead,
+              bytesWritten,
+            );
+            if (bytesRead === 0) break;
+            bytesWritten += bytesRead;
+            yield bytesRead === buf.length ? buf : buf.subarray(0, bytesRead);
           }
         } catch {
           // File was deleted or rotated between passes — emit zeros for
           // the full declared size so the tar structure stays valid
+        } finally {
+          if (handle) await handle.close();
         }
       }
 

package/src/runtime/pending-interactions.ts

@@ -19,6 +19,7 @@
  */
 
 import type { InteractionResolutionState } from "../api/events/interaction-resolved.js";
+import type { QuestionEntry } from "../api/events/question-request.js";
 import type { UserDecision } from "../permissions/types.js";
 import { getLogger } from "../util/logger.js";
 import { broadcastMessage } from "./assistant-event-hub.js";
@@ -50,6 +51,18 @@ export interface ConfirmationDetails {
   }>;
 }
 
+/**
+ * Full batched question payload carried on a pending `question` interaction, so
+ * a history-load render can stamp the outstanding prompt back onto its tool
+ * call and rehydrate the question card on a cold reconnect. Mirrors the
+ * `question_request` event's `questions[]` — `metadata` only retains the
+ * `orderedIds`/`optionsById` the response route needs to validate submissions,
+ * which is insufficient to reconstruct the card.
+ */
+export interface QuestionDetails {
+  entries: QuestionEntry[];
+}
+
 export interface PendingInteraction {
   /**
    * Owning conversation, when the interaction was raised inside one. Absent
@@ -69,6 +82,8 @@ export interface PendingInteraction {
     | "host_transfer"
     | "acp_confirmation";
   confirmationDetails?: ConfirmationDetails;
+  /** For a pending `question`: the full batched entries, so a history-load render can rehydrate the question card. */
+  questionDetails?: QuestionDetails;
   /** For ACP permissions: resolves directly without a Conversation object. */
   directResolve?: (decision: UserDecision) => void;
   /** When set, the host_bash request should be routed to this specific client. */

package/src/runtime/routes/__tests__/client-routes.test.ts

@@ -51,6 +51,7 @@ type ListClientsResponse = {
     machineName?: string;
     connectedAt: string;
     lastActiveAt: string;
+    degraded?: boolean;
   }>;
 };
 
@@ -152,4 +153,16 @@ describe("list_clients route — same-user filter", () => {
     const ids = result.clients.map((c) => c.clientId).sort();
     expect(ids).toEqual(["client-A1", "client-B1", "client-noprincipal"]);
   });
+
+  test("includes a degraded flag (false for a freshly connected client)", () => {
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-A" },
+    }) as ListClientsResponse;
+
+    expect(result.clients).toHaveLength(1);
+    expect(result.clients[0].degraded).toBe(false);
+  });
 });