@indigoai-us/hq-cloud 6.11.12 → 6.11.14

package/src/daemon-worker.ts

@@ -4,11 +4,11 @@
  *
  * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
  * When re-enabled, this worker will need to resolve an EntityContext before
- * constructing the SyncWatcher. The process argv will need to include company
- * context (slug or UID) and vault-service config.
+ * constructing the active watcher/runner path. The process argv will need to
+ * include company context (slug or UID) and vault-service config.
  */
 
-// Day 1: SyncWatcher now requires an EntityContext.
+// Day 1: this worker still requires EntityContext-aware startup wiring.
 // This file is retained for the automatic-sync milestone but is not functional
 // until the daemon startup path is updated to resolve entity context.
 

package/src/index.ts

@@ -57,6 +57,15 @@ export {
 
 export type { JournalSummary } from "./journal.js";
 
+// Cross-process sync progress — every sync path writes one shared snapshot so
+// a watcher (the hq-sync menubar) can show live progress for ANY sync.
+export {
+  createSyncProgressRecorder,
+  readSyncProgress,
+  syncProgressPath,
+} from "./sync-progress.js";
+export type { SyncProgressSnapshot } from "./sync-progress.js";
+
 // Prefix coalescing helper (US-005)
 export {
   coalescePrefixes,

package/src/object-io.ts

@@ -540,7 +540,7 @@ export class PresignObjectIO implements ObjectIO {
   ) {}
 
   private cacheKey(op: PresignOp, key: string): string {
-    return `${op}${key}`;
+    return `${op}\u0000${key}`;
   }
 
   hasPrimedPut(key: string): boolean {

package/src/remote-pull.test.ts

@@ -1,7 +1,7 @@
 /**
  * Failing-test seed for the Auto-sync (Beta) remote-pull loop.
  *
- * Background: SyncWatcher (watcher.ts) pushes local edits to S3 in seconds,
+ * Background: the watcher push path ships local edits to S3 in seconds,
  * but pulls happen only on a manual sync today. Auto-sync adds a periodic
  * (every 10 min) remote-pull pass per company. The decision of *which* keys
  * to download / delete locally / skip is pure given a remote listing, the
@@ -25,6 +25,7 @@ import {
   POST_FILTER_THRESHOLD,
   pullCompany,
   resolveCompanyScope,
+  VEND_FANOUT_CONCURRENCY,
   VEND_PATH_CAP,
 } from "./remote-pull.js";
 import type { RemoteFile } from "./s3.js";
@@ -579,6 +580,34 @@ describe("listRemoteForScope", () => {
     expect(calls.size).toBe(VEND_PATH_CAP + 3); // every prefix listed
   });
 
+  it("F28: bounds concurrent per-prefix listings across vend-fanout batches", async () => {
+    const prefixes = Array.from(
+      { length: POST_FILTER_THRESHOLD },
+      (_, i) => `companies/indigo/p${i}/`,
+    );
+    let active = 0;
+    let maxActive = 0;
+
+    await listRemoteForScope({
+      ctx: makeCtx(),
+      scope: {
+        companyUid: "cmp_indigo",
+        syncMode: "shared",
+        prefixSet: prefixes,
+        strategy: "vend-fanout",
+      },
+      listFn: async () => {
+        active += 1;
+        maxActive = Math.max(maxActive, active);
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        active -= 1;
+        return [];
+      },
+    });
+
+    expect(maxActive).toBeLessThanOrEqual(VEND_FANOUT_CONCURRENCY);
+  });
+
   it("strategy=vend-fanout uses vendForBatchFn to narrow credentials per batch", async () => {
     const vendCalls: Array<{ paths: string[] }> = [];
     await listRemoteForScope({

package/src/remote-pull.ts

@@ -8,7 +8,7 @@
  * sync-runner.ts trivial: list S3 → call `decideRemotePulls` → drive S3 +
  * filesystem from the result.
  *
- * Pairs with `SyncWatcher` (push-side) — together they implement the
+ * Pairs with the TreeWatcher push path — together they implement the
  * bidirectional auto-sync the Settings toggle exposes.
  */
 import type { RemoteFile } from "./s3.js";
@@ -160,7 +160,7 @@ export const VEND_PATH_CAP = 10;
  */
 export const POST_FILTER_THRESHOLD = 50;
 
-/** Bounded parallelism for vend fan-out (5 concurrent STS+ListObjectsV2 calls). */
+/** Bounded parallelism for vend fan-out (5 concurrent vends/list paginators). */
 export const VEND_FANOUT_CONCURRENCY = 5;
 
 /**
@@ -291,6 +291,27 @@ async function mapWithConcurrency<T, R>(
   return results;
 }
 
+function createConcurrencyLimiter(
+  concurrency: number,
+): <R>(fn: () => Promise<R>) => Promise<R> {
+  const limit = Math.max(1, concurrency);
+  let active = 0;
+  const waiters: Array<() => void> = [];
+
+  return async function runLimited<R>(fn: () => Promise<R>): Promise<R> {
+    if (active >= limit) {
+      await new Promise<void>((resolve) => waiters.push(resolve));
+    }
+    active += 1;
+    try {
+      return await fn();
+    } finally {
+      active -= 1;
+      waiters.shift()?.();
+    }
+  };
+}
+
 export interface ListRemoteForScopeInput {
   ctx: EntityContext;
   scope: CompanyScope;
@@ -347,6 +368,7 @@ export async function listRemoteForScope(
   const scopeEntries = toScopePrefixEntries(scope.prefixSet);
   const listPrefixes = scopeEntries.map((entry) => entry.prefix);
   const batches = batchPrefixesForVend(listPrefixes);
+  const listWithLimit = createConcurrencyLimiter(VEND_FANOUT_CONCURRENCY);
   const perBatch = await mapWithConcurrency(
     batches,
     VEND_FANOUT_CONCURRENCY,
@@ -357,8 +379,11 @@ export async function listRemoteForScope(
       // For a coalesced batch we issue one ListObjectsV2 per prefix in the
       // batch. We can't issue one ListObjectsV2 across N prefixes (the API
       // takes a single Prefix); the per-batch grouping exists for the STS
-      // session policy ceiling, not the list call itself.
-      const lists = await Promise.all(paths.map((p) => list(batchCtx, p)));
+      // session policy ceiling, not the list call itself. The shared limiter
+      // keeps the total active prefix paginators bounded across all batches.
+      const lists = await Promise.all(
+        paths.map((p) => listWithLimit(() => list(batchCtx, p))),
+      );
       return lists.flat();
     },
   );

package/src/sync/push-receiver.test.ts

@@ -396,6 +396,41 @@ describe("US-009: SqsPushReceiver — reconnect / catch-up replay", () => {
     expect(sqs.deleted).not.toContain("rh-first-attempt");
     expect(sqs.deleted).toContain("rh-redelivery");
   });
+
+  it("F29: bounds dedupe state by evicting least-recently-used paths", async () => {
+    const sqs = new FakeSqs();
+    const processed: string[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      processed.push(ctx.event.relativePath);
+    };
+
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/a.md", sequenceNumber: 1 }), "rh-a1")]);
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/b.md", sequenceNumber: 1 }), "rh-b1")]);
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/c.md", sequenceNumber: 1 }), "rh-c1")]);
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/a.md", sequenceNumber: 1 }), "rh-a-redelivered")]);
+
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+      dedupeMaxPaths: 2,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 4);
+    await receiver.dispose();
+
+    expect(processed).toEqual([
+      "companies/indigo/a.md",
+      "companies/indigo/b.md",
+      "companies/indigo/c.md",
+      "companies/indigo/a.md",
+    ]);
+    expect(receiver.dedupedCount).toBe(0);
+    expect(sqs.deleted).toContain("rh-a-redelivered");
+  });
 });
 
 describe("US-009: SqsPushReceiver — flag gating", () => {

package/src/sync/push-receiver.ts

@@ -125,6 +125,39 @@ export const DEFAULT_MAX_MESSAGES = 10;
 export const DEFAULT_RECONNECT_INITIAL_MS = 250;
 export const DEFAULT_RECONNECT_MAX_MS = 30_000;
 
+/** Maximum distinct paths retained in receiver dedupe state. */
+export const DEFAULT_RECEIVER_DEDUPE_MAX_PATHS = 50_000;
+
+class BoundedSequenceDedupe {
+  private readonly maxPaths: number;
+  private readonly seen = new Map<string, number>();
+
+  constructor(maxPaths: number | undefined) {
+    this.maxPaths = Math.max(
+      1,
+      Math.floor(maxPaths ?? DEFAULT_RECEIVER_DEDUPE_MAX_PATHS),
+    );
+  }
+
+  get(relativePath: string): number | undefined {
+    const sequenceNumber = this.seen.get(relativePath);
+    if (sequenceNumber === undefined) return undefined;
+    this.seen.delete(relativePath);
+    this.seen.set(relativePath, sequenceNumber);
+    return sequenceNumber;
+  }
+
+  set(relativePath: string, sequenceNumber: number): void {
+    if (this.seen.has(relativePath)) this.seen.delete(relativePath);
+    this.seen.set(relativePath, sequenceNumber);
+    while (this.seen.size > this.maxPaths) {
+      const oldest = this.seen.keys().next().value;
+      if (oldest === undefined) return;
+      this.seen.delete(oldest);
+    }
+  }
+}
+
 // ─── Narrow SQS surface (the injectable transport seam) ──────────────────────
 
 /**
@@ -321,6 +354,8 @@ export interface SqsPushReceiverOptions {
   maxMessages?: number;
   /** Max time `dispose()` waits for an in-flight syncFn after abort. */
   disposeDrainMs?: number;
+  /** Maximum distinct paths retained in dedupe state. */
+  dedupeMaxPaths?: number;
   /** Reconnect backoff config. */
   reconnect?: {
     initialMs?: number;
@@ -384,7 +419,7 @@ export class SqsPushReceiver implements PushReceiver {
   private inFlightSync: Promise<void> | null = null;
 
   /** Per-path highest sequence number already PROCESSED by syncFn. */
-  private readonly seenSequencePerPath = new Map<string, number>();
+  private readonly seenSequencePerPath: BoundedSequenceDedupe;
 
   private _processedCount = 0;
   private _dedupedCount = 0;
@@ -413,6 +448,7 @@ export class SqsPushReceiver implements PushReceiver {
     this.maxMessages = opts.maxMessages ?? DEFAULT_MAX_MESSAGES;
     this.disposeDrainMs =
       opts.disposeDrainMs ?? DEFAULT_RECEIVER_DISPOSE_DRAIN_MS;
+    this.seenSequencePerPath = new BoundedSequenceDedupe(opts.dedupeMaxPaths);
     this.reconnectInitialMs =
       opts.reconnect?.initialMs ?? DEFAULT_RECONNECT_INITIAL_MS;
     this.reconnectMaxMs = opts.reconnect?.maxMs ?? DEFAULT_RECONNECT_MAX_MS;
@@ -821,6 +857,8 @@ export interface InMemoryPushReceiverOptions {
   flagProvider?: EventDrivenPushFlagProvider;
   env?: Record<string, string | undefined>;
   disposeDrainMs?: number;
+  /** Maximum distinct paths retained in dedupe state. */
+  dedupeMaxPaths?: number;
 }
 
 /**
@@ -846,7 +884,7 @@ export class InMemoryPushReceiver implements PushReceiver {
 
   private disconnectedFlag = false;
   private readonly pendingDuringDisconnect: PushEvent[] = [];
-  private readonly seenSequencePerPath = new Map<string, number>();
+  private readonly seenSequencePerPath: BoundedSequenceDedupe;
 
   private inFlightAbort: AbortController | null = null;
   private inFlightSync: Promise<void> | null = null;
@@ -862,6 +900,7 @@ export class InMemoryPushReceiver implements PushReceiver {
     this.logger = opts.logger ?? NOOP_LOGGER;
     this.disposeDrainMs =
       opts.disposeDrainMs ?? DEFAULT_RECEIVER_DISPOSE_DRAIN_MS;
+    this.seenSequencePerPath = new BoundedSequenceDedupe(opts.dedupeMaxPaths);
     this.enabled = resolveEnabled({
       explicit: opts.enabled,
       flagProvider: opts.flagProvider,

package/src/sync-core.ts

@@ -0,0 +1,58 @@
+import * as fs from "fs";
+import * as path from "path";
+import { normalizeEtag } from "./journal.js";
+
+/**
+ * Is this error the S3/STS "access denied" class? Expected when a scoped
+ * member/guest credential touches a key outside its granted ACL prefixes
+ * (the server's `SCOPE_EXCEEDS_PARENT` surfaces as a 403 AccessDenied /
+ * Forbidden).
+ */
+export function isAccessDenied(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    const name = (err as { name?: unknown }).name;
+    return name === "AccessDenied" || name === "Forbidden";
+  }
+  return false;
+}
+
+export function resolveTransferConcurrency(): number {
+  const raw = process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
+  if (raw === undefined || raw === "") return 16;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 16;
+}
+
+/**
+ * Resolve active company from .hq/config.json.
+ */
+export function resolveActiveCompany(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      return config.activeCompany ?? config.companySlug;
+    } catch {
+      // Ignore parse errors
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Returns true when the remote object appears to have moved since the
+ * journal entry's last-recorded sync. Prefers ETag equality; falls back to
+ * `lastModified > syncedAt` for legacy entries written before remoteEtag
+ * was tracked. Conservative on tie (`<=` skews "remote unchanged") so an
+ * S3-side mtime that exactly equals our syncedAt is not treated as drift.
+ */
+export function hasRemoteChanged(
+  remote: { lastModified: Date; etag: string },
+  entry: { syncedAt: string; remoteEtag?: string },
+): boolean {
+  if (entry.remoteEtag) {
+    return normalizeEtag(remote.etag) !== entry.remoteEtag;
+  }
+  const syncedAt = new Date(entry.syncedAt).getTime();
+  return remote.lastModified.getTime() > syncedAt;
+}

package/src/sync-progress.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import type { SyncProgressEvent } from "./cli/sync.js";
+import {
+  createSyncProgressRecorder,
+  readSyncProgress,
+} from "./sync-progress.js";
+
+const planEvent = (download: number, upload: number, del: number): SyncProgressEvent =>
+  ({
+    type: "plan",
+    filesToDownload: download,
+    bytesToDownload: 0,
+    filesToUpload: upload,
+    bytesToUpload: 0,
+    filesToSkip: 0,
+    filesToConflict: 0,
+    filesToDelete: del,
+  }) as SyncProgressEvent;
+
+describe("sync-progress", () => {
+  let stateDir: string;
+  beforeEach(() => {
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-progress-test-"));
+    process.env.HQ_STATE_DIR = stateDir;
+  });
+  afterEach(() => {
+    delete process.env.HQ_STATE_DIR;
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  it("returns null when no sync has written a snapshot", () => {
+    expect(readSyncProgress()).toBeNull();
+  });
+
+  it("accumulates plan totals, progress, and conflicts into the shared snapshot", () => {
+    const record = createSyncProgressRecorder({ company: "acme", phase: "pull" });
+    record(planEvent(3, 0, 1)); // 3 to download + 1 to delete = 4 total
+    record({ type: "progress", path: "a.md", bytes: 10 } as SyncProgressEvent);
+    record({ type: "progress", path: "b.md", bytes: 10 } as SyncProgressEvent);
+    record({
+      type: "conflict",
+      path: "c.md",
+      direction: "pull",
+      resolution: "keep",
+    } as SyncProgressEvent);
+
+    const snap = readSyncProgress();
+    expect(snap).not.toBeNull();
+    expect(snap!.company).toBe("acme");
+    expect(snap!.phase).toBe("pull");
+    expect(snap!.filesTotal).toBe(4);
+    expect(snap!.filesDone).toBe(2);
+    expect(snap!.conflicts).toBe(1);
+    expect(snap!.currentFile).toBe("b.md");
+    expect(snap!.status).toBe("syncing");
+    expect(snap!.pid).toBe(process.pid);
+    expect(typeof snap!.updatedAt).toBe("string");
+  });
+
+  it("records the push leg + personal scope (company null)", () => {
+    const record = createSyncProgressRecorder({ company: null, phase: "push" });
+    record(planEvent(0, 5, 0));
+    const snap = readSyncProgress();
+    expect(snap!.phase).toBe("push");
+    expect(snap!.company).toBeNull();
+    expect(snap!.filesTotal).toBe(5);
+  });
+
+  it("ignores non-progress events (no churn from new-files/reconciled)", () => {
+    const record = createSyncProgressRecorder({ company: "acme", phase: "pull" });
+    record(planEvent(1, 0, 0));
+    record({ type: "new-files", files: [] } as SyncProgressEvent);
+    record({ type: "reconciled", path: "x.md", direction: "pull" } as SyncProgressEvent);
+    const snap = readSyncProgress();
+    expect(snap!.filesDone).toBe(0);
+    expect(snap!.filesTotal).toBe(1);
+  });
+});

package/src/sync-progress.ts

@@ -0,0 +1,133 @@
+/**
+ * Cross-process sync progress.
+ *
+ * Every sync path — the menubar watch daemon (auto-sync), "Sync Now", and a
+ * CLI `hq sync` — runs through the same engine (`sync()` pull + `share()`
+ * push). Each writes one shared status snapshot here so a watcher (the menubar)
+ * can show LIVE progress for ANY sync, not just the one it spawned over stdout.
+ *
+ * Because syncs are serialized (the op-lock; the watch daemon coordinates with
+ * one-shots), there is at most one active sync, so this single file is
+ * unambiguous. Writes are atomic (temp + rename) — a torn read at worst shows
+ * slightly stale progress. There is intentionally no explicit "done": the
+ * engine simply stops writing when a sync ends, so a consumer treats the file
+ * as idle once `updatedAt` is older than a few seconds. Progress reporting must
+ * never break a sync, so every fs error here is swallowed.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import type { SyncProgressEvent } from "./cli/sync.js";
+
+/** Mirror operation-lock's stateDir so the file lands next to the journal/lock. */
+function stateDir(): string {
+  return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
+}
+
+/** Absolute path of the shared progress snapshot. Exported for the watcher + tests. */
+export function syncProgressPath(): string {
+  return path.join(stateDir(), "sync-progress.json");
+}
+
+export interface SyncProgressSnapshot {
+  schema: 1;
+  /** PID of the writing sync — lets a watcher detect a dead/stale holder. */
+  pid: number;
+  /** Company slug being synced, or null for the personal vault. */
+  company: string | null;
+  /** Which leg is running. */
+  phase: "pull" | "push";
+  filesTotal: number;
+  filesDone: number;
+  conflicts: number;
+  /** Path of the file currently transferring, or null before the first one. */
+  currentFile: string | null;
+  startedAt: string;
+  updatedAt: string;
+  status: "syncing";
+}
+
+export interface SyncProgressRecorderOptions {
+  company?: string | null;
+  phase: "pull" | "push";
+}
+
+/**
+ * Build an event sink that accumulates a sync's progress and atomic-writes the
+ * shared snapshot on each meaningful event. Wrap the engine's `onEvent` with
+ * it: `const emit = (e) => { baseEmit(e); record(e); }`.
+ */
+export function createSyncProgressRecorder(
+  opts: SyncProgressRecorderOptions,
+): (event: SyncProgressEvent) => void {
+  let filesTotal = 0;
+  let filesDone = 0;
+  let conflicts = 0;
+  let currentFile: string | null = null;
+  const startedAt = new Date().toISOString();
+  const file = syncProgressPath();
+
+  const flush = (): void => {
+    const snap: SyncProgressSnapshot = {
+      schema: 1,
+      pid: process.pid,
+      company: opts.company ?? null,
+      phase: opts.phase,
+      filesTotal,
+      filesDone,
+      conflicts,
+      currentFile,
+      startedAt,
+      updatedAt: new Date().toISOString(),
+      status: "syncing",
+    };
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(snap));
+      fs.renameSync(tmp, file);
+    } catch {
+      // Progress reporting is best-effort and must never break a sync.
+    }
+  };
+
+  return (event: SyncProgressEvent): void => {
+    switch (event.type) {
+      case "plan":
+        // Sum the work this leg will do. `plan` arrives once before any
+        // progress events for the leg.
+        filesTotal +=
+          event.filesToDownload + event.filesToUpload + event.filesToDelete;
+        flush();
+        break;
+      case "progress":
+        filesDone += 1;
+        currentFile = event.path;
+        flush();
+        break;
+      case "conflict":
+        conflicts += 1;
+        flush();
+        break;
+      default:
+        // error / new-files / reconciled / delete-refused etc. don't move the
+        // bar — skip the write to keep the file churn-free.
+        break;
+    }
+  };
+}
+
+/**
+ * Read the current snapshot, or null if absent/unreadable. Consumers should
+ * additionally treat a snapshot whose `updatedAt` is older than a few seconds
+ * (or whose `pid` is dead) as idle.
+ */
+export function readSyncProgress(): SyncProgressSnapshot | null {
+  try {
+    const raw = fs.readFileSync(syncProgressPath(), "utf8");
+    const parsed = JSON.parse(raw) as SyncProgressSnapshot;
+    return parsed && parsed.schema === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/src/vault-client.test.ts

@@ -440,6 +440,80 @@ describe("API surface", () => {
   });
 });
 
+describe("response validation (F26)", () => {
+  it("F26: validates a valid files/list response and returns typed data", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        objects: [
+          {
+            key: "shared/docs/a.txt",
+            size: 123,
+            lastModified: "2026-05-20T12:00:00.000Z",
+            etag: "abc123",
+            permission: "read",
+          },
+        ],
+        cursor: null,
+        truncated: false,
+      }),
+    );
+
+    const page = await client.listFiles("cmp_abc", "shared/docs/");
+
+    expect(page.objects[0]).toEqual({
+      key: "shared/docs/a.txt",
+      size: 123,
+      lastModified: "2026-05-20T12:00:00.000Z",
+      etag: "abc123",
+      permission: "read",
+    });
+    expect(page.cursor).toBeNull();
+    expect(page.truncated).toBe(false);
+  });
+
+  it("F26: defaults omitted files/list paging fields", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+
+    const page = await client.listFiles("cmp_abc", "shared/docs/");
+
+    expect(page).toEqual({
+      objects: [],
+      cursor: null,
+      truncated: false,
+    });
+  });
+
+  it("F26: defaults omitted telemetry opt-in fields to disabled", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+
+    const optIn = await client.getTelemetryOptIn();
+
+    expect(optIn).toEqual({ enabled: false, updatedAt: null });
+  });
+
+  it("F26: maps a malformed files/list response to VaultClientError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        objects: [
+          {
+            key: "shared/docs/a.txt",
+            size: 123,
+            lastModified: "2026-05-20T12:00:00.000Z",
+            permission: "read",
+          },
+        ],
+        cursor: null,
+        truncated: false,
+      }),
+    );
+
+    await expect(client.listFiles("cmp_abc")).rejects.toMatchObject({
+      name: "VaultClientError",
+      statusCode: 502,
+    });
+  });
+});
+
 describe("VaultClient identity bootstrap", () => {
   let client: VaultClient;
   let fetchSpy: MockInstance<typeof fetch>;