@getpaseo/server 0.1.97-beta.3 → 0.1.98

package/dist/server/services/quota-fetcher/providers/zai.d.ts

@@ -0,0 +1,17 @@
+import type { Logger } from "pino";
+import type { ProviderUsage } from "../../../server/messages.js";
+import type { ProviderApiFetch, ProviderUsageFetcher } from "../provider.js";
+interface ZaiQuotaProviderOptions {
+    logger: Logger;
+    fetch?: ProviderApiFetch;
+}
+export declare class ZaiQuotaProvider implements ProviderUsageFetcher {
+    readonly providerId = "zai";
+    readonly displayName = "Z.ai";
+    private readonly logger;
+    private readonly fetchApi;
+    constructor(options: ZaiQuotaProviderOptions);
+    fetchUsage(): Promise<ProviderUsage>;
+}
+export {};
+//# sourceMappingURL=zai.d.ts.map

package/dist/server/services/quota-fetcher/providers/zai.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { ApiOptionalStringSchema, fetchProviderApi, unavailableUsage } from "../usage.js";
+const ZaiUsageResponseSchema = z.object({
+    data: z
+        .array(z.object({
+        productName: ApiOptionalStringSchema,
+        status: ApiOptionalStringSchema,
+        purchaseTime: ApiOptionalStringSchema,
+        valid: ApiOptionalStringSchema,
+    }))
+        .optional(),
+});
+export class ZaiQuotaProvider {
+    constructor(options) {
+        this.providerId = "zai";
+        this.displayName = "Z.ai";
+        this.logger = options.logger;
+        this.fetchApi = options.fetch ?? fetch;
+    }
+    async fetchUsage() {
+        const token = process.env["ZAI_API_KEY"] || process.env["GLM_API_KEY"];
+        if (!token)
+            return unavailableUsage(this);
+        const res = await fetchProviderApi(this.fetchApi, "https://api.z.ai/api/biz/subscription/list", {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/json",
+            },
+        });
+        if (!res.ok) {
+            this.logger.debug({ status: res.status }, "Z.ai usage fetch failed");
+            return unavailableUsage(this);
+        }
+        const resp = ZaiUsageResponseSchema.parse(await res.json());
+        const sub = resp.data?.[0];
+        if (!sub)
+            return unavailableUsage(this);
+        const details = [];
+        if (sub.status)
+            details.push({ id: "status", label: "Status", value: sub.status });
+        if (sub.valid)
+            details.push({ id: "valid", label: "Valid", value: sub.valid });
+        if (sub.purchaseTime) {
+            details.push({ id: "purchase_time", label: "Purchased", value: sub.purchaseTime });
+        }
+        return {
+            providerId: this.providerId,
+            displayName: this.displayName,
+            status: "available",
+            planLabel: sub.productName || null,
+            windows: [],
+            balances: [],
+            details,
+            error: null,
+        };
+    }
+}
+//# sourceMappingURL=zai.js.map

package/dist/server/services/quota-fetcher/service.d.ts

@@ -0,0 +1,28 @@
+import type { Logger } from "pino";
+import type { ProviderUsage } from "../../server/messages.js";
+import type { ProviderApiFetch, ProviderUsageFetcher } from "./provider.js";
+export interface ProviderUsageServiceOptions {
+    logger: Logger;
+    fetchers?: ProviderUsageFetcher[];
+    fetch?: ProviderApiFetch;
+    cacheTtlMs?: number;
+    now?: () => number;
+}
+export interface ProviderUsageListResult {
+    fetchedAt: string;
+    providers: ProviderUsage[];
+}
+export declare class ProviderUsageService {
+    private readonly logger;
+    private readonly fetchers;
+    private readonly cacheTtlMs;
+    private readonly now;
+    private cached;
+    private inFlight;
+    constructor(options: ProviderUsageServiceOptions);
+    listUsage(options?: {
+        forceRefresh?: boolean;
+    }): Promise<ProviderUsageListResult>;
+    private fetchFreshUsage;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/server/services/quota-fetcher/service.js

@@ -0,0 +1,58 @@
+import { createProviderUsageFetchers } from "./manifest.js";
+import { unavailableUsage } from "./usage.js";
+const DEFAULT_PROVIDER_USAGE_CACHE_TTL_MS = 5 * 60 * 1000;
+export class ProviderUsageService {
+    constructor(options) {
+        this.cached = null;
+        this.inFlight = null;
+        this.logger = options.logger.child({ module: "provider-usage-service" });
+        this.fetchers =
+            options.fetchers ??
+                createProviderUsageFetchers({
+                    logger: this.logger,
+                    fetch: options.fetch,
+                });
+        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_PROVIDER_USAGE_CACHE_TTL_MS;
+        this.now = options.now ?? Date.now;
+    }
+    async listUsage(options) {
+        const nowMs = this.now();
+        if (!options?.forceRefresh &&
+            this.cached &&
+            nowMs - this.cached.fetchedAtMs < this.cacheTtlMs) {
+            return this.cached.result;
+        }
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        const request = this.fetchFreshUsage(nowMs);
+        this.inFlight = request;
+        try {
+            return await request;
+        }
+        finally {
+            if (this.inFlight === request) {
+                this.inFlight = null;
+            }
+        }
+    }
+    async fetchFreshUsage(nowMs) {
+        const settled = await Promise.allSettled(this.fetchers.map((fetcher) => fetcher.fetchUsage()));
+        const providers = settled.map((result, index) => {
+            const fetcher = this.fetchers[index];
+            if (result.status === "fulfilled") {
+                return result.value;
+            }
+            this.logger.debug({ err: result.reason, providerId: fetcher.providerId }, "Provider usage fetch failed");
+            return unavailableUsage({
+                providerId: fetcher.providerId,
+                displayName: fetcher.displayName,
+                error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+            });
+        });
+        const result = { fetchedAt: new Date(nowMs).toISOString(), providers };
+        this.cached = { fetchedAtMs: nowMs, result };
+        return result;
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/server/services/quota-fetcher/usage.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { ProviderUsage, ProviderUsageBalance, ProviderUsageWindow } from "../../server/messages.js";
+import type { ProviderApiFetch } from "./provider.js";
+export declare const ApiNumberSchema: z.ZodCoercedNumber<unknown>;
+export declare const ApiNullableNumberSchema: z.ZodPreprocess<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
+export declare const ApiOptionalStringSchema: z.ZodPreprocess<z.ZodOptional<z.ZodCoercedString<unknown>>>;
+export declare function fetchProviderApi(fetchApi: ProviderApiFetch, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function unavailableUsage(provider: {
+    providerId: string;
+    displayName: string;
+    error?: string | null;
+}): ProviderUsage;
+export declare function windowFromUsedPct(input: {
+    id: string;
+    label: string;
+    utilizationPct: number | null | undefined;
+    resetsAt?: string | null;
+    tone?: ProviderUsageWindow["tone"];
+}): ProviderUsageWindow;
+export declare function balanceToneFromRemaining(remaining: number | null | undefined): ProviderUsageBalance["tone"];
+export declare function toIsoStringOrNull(timestampMs: number): string | null;
+//# sourceMappingURL=usage.d.ts.map

package/dist/server/services/quota-fetcher/usage.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+const PROVIDER_HTTP_TIMEOUT_MS = 15000;
+export const ApiNumberSchema = z.coerce.number().finite();
+export const ApiNullableNumberSchema = z.preprocess((value) => (value == null ? null : value), ApiNumberSchema.nullable());
+export const ApiOptionalStringSchema = z.preprocess((value) => (value == null ? undefined : value), z.coerce.string().optional());
+export function fetchProviderApi(fetchApi, input, init = {}) {
+    return fetchApi(input, {
+        ...init,
+        signal: init.signal ?? AbortSignal.timeout(PROVIDER_HTTP_TIMEOUT_MS),
+    });
+}
+export function unavailableUsage(provider) {
+    return {
+        providerId: provider.providerId,
+        displayName: provider.displayName,
+        status: provider.error ? "error" : "unavailable",
+        planLabel: null,
+        windows: [],
+        balances: [],
+        details: [],
+        error: provider.error ?? null,
+    };
+}
+export function windowFromUsedPct(input) {
+    const usedPct = typeof input.utilizationPct === "number" ? input.utilizationPct : null;
+    const window = {
+        id: input.id,
+        label: input.label,
+        usedPct,
+        remainingPct: usedPct === null ? null : Math.max(0, 100 - usedPct),
+        resetsAt: input.resetsAt ?? null,
+    };
+    if (input.tone) {
+        window.tone = input.tone;
+    }
+    return window;
+}
+export function balanceToneFromRemaining(remaining) {
+    if (typeof remaining !== "number")
+        return "default";
+    if (remaining <= 0)
+        return "danger";
+    return "ok";
+}
+export function toIsoStringOrNull(timestampMs) {
+    const date = new Date(timestampMs);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+}
+//# sourceMappingURL=usage.js.map

package/dist/server/terminal/terminal-session-controller.d.ts

@@ -9,10 +9,15 @@ export interface TerminalSessionControllerOptions {
     hasBinaryChannel: () => boolean;
     isPathWithinRoot: (rootPath: string, candidatePath: string) => boolean;
     sessionLogger: pino.Logger;
+    listTerminalWorkspaceRefs?: () => Promise<readonly TerminalWorkspaceRef[]>;
     listTerminalWorkspaceRoots?: () => Promise<readonly string[]>;
     clientSupportsWrapReflow?: () => boolean;
     getClientBufferedAmount?: () => number | null;
 }
+interface TerminalWorkspaceRef {
+    workspaceId: string;
+    cwd: string;
+}
 export interface TerminalSessionControllerMetrics {
     directorySubscriptionCount: number;
     streamSubscriptionCount: number;
@@ -24,6 +29,7 @@ export declare class TerminalSessionController {
     private readonly hasBinaryChannel;
     private readonly isPathWithinRoot;
     private readonly sessionLogger;
+    private readonly listTerminalWorkspaceRefs;
     private readonly listTerminalWorkspaceRoots;
     private readonly clientSupportsWrapReflow;
     private readonly getClientBufferedAmount;
@@ -59,6 +65,7 @@ export declare class TerminalSessionController {
     private resolveTerminalOwnerRoot;
     private isSamePath;
     private handleCreateTerminalRequest;
+    private resolveLegacyTerminalWorkspaceId;
     private handleRenameTerminalRequest;
     private handleSubscribeTerminalRequest;
     private handleUnsubscribeTerminalRequest;
@@ -74,4 +81,5 @@ export declare class TerminalSessionController {
     private allocateSlot;
     private detachStream;
 }
+export {};
 //# sourceMappingURL=terminal-session-controller.d.ts.map

package/dist/server/terminal/terminal-session-controller.js

@@ -34,7 +34,10 @@ export class TerminalSessionController {
         this.hasBinaryChannel = options.hasBinaryChannel;
         this.isPathWithinRoot = options.isPathWithinRoot;
         this.sessionLogger = options.sessionLogger;
-        this.listTerminalWorkspaceRoots = options.listTerminalWorkspaceRoots ?? (async () => []);
+        this.listTerminalWorkspaceRefs = options.listTerminalWorkspaceRefs ?? (async () => []);
+        this.listTerminalWorkspaceRoots =
+            options.listTerminalWorkspaceRoots ??
+                (async () => (await this.listTerminalWorkspaceRefs()).map((workspace) => workspace.cwd));
         this.clientSupportsWrapReflow = options.clientSupportsWrapReflow ?? (() => false);
         this.getClientBufferedAmount = options.getClientBufferedAmount ?? (() => 0);
     }
@@ -331,7 +334,8 @@ export class TerminalSessionController {
                 });
                 return;
             }
-            if (!msg.workspaceId) {
+            const workspaceId = msg.workspaceId ?? (await this.resolveLegacyTerminalWorkspaceId(msg.cwd));
+            if (!workspaceId) {
                 this.emit({
                     type: "create_terminal_response",
                     payload: {
@@ -344,7 +348,7 @@ export class TerminalSessionController {
             }
             const session = await this.terminalManager.createTerminal({
                 cwd: msg.cwd,
-                workspaceId: msg.workspaceId,
+                workspaceId,
                 name: msg.name,
                 command: msg.command,
                 args: msg.args,
@@ -378,6 +382,22 @@ export class TerminalSessionController {
             });
         }
     }
+    async resolveLegacyTerminalWorkspaceId(cwd) {
+        const workspaceRefs = await this.listTerminalWorkspaceRefs();
+        if (workspaceRefs.length === 0) {
+            return null;
+        }
+        const exactMatch = workspaceRefs.find((workspace) => this.isSamePath(workspace.cwd, cwd));
+        if (exactMatch) {
+            return exactMatch.workspaceId;
+        }
+        const ownerRoot = this.resolveTerminalOwnerRoot(cwd, workspaceRefs.map((workspace) => workspace.cwd));
+        if (!ownerRoot) {
+            return null;
+        }
+        return (workspaceRefs.find((workspace) => this.isSamePath(workspace.cwd, ownerRoot))?.workspaceId ??
+            null);
+    }
     async handleRenameTerminalRequest(msg) {
         const respond = (success, error) => {
             this.emit({

package/dist/server/utils/checkout-git.js

@@ -375,7 +375,6 @@ function buildGitDiffArgs(args) {
     return ["diff", ...(args.ignoreWhitespace ? ["-w"] : []), ...args.extra];
 }
 const TRACKED_DIFF_NUMSTAT_MAX_BYTES = 2 * 1024 * 1024; // 2MB
-const TRACKED_DIFF_PER_FILE_MAX_CHARS = 1024 * 1024;
 const EMPTY_TREE_OBJECT_ID = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 function isUnbornHeadDiffError(error) {
     return (error instanceof Error &&
@@ -423,56 +422,20 @@ async function getTrackedNumstatByPath(cwd, refs, ignoreWhitespace = false) {
     }
     return stats;
 }
-function extractTrackedDiffMetadataPath(section, prefix) {
-    const line = section.split("\n").find((candidate) => candidate.startsWith(prefix));
-    if (!line) {
-        return null;
-    }
-    const path = line.slice(prefix.length).replace(/\t.*$/, "").trimEnd();
-    if (path === "/dev/null") {
-        return null;
-    }
-    return path.startsWith("a/") || path.startsWith("b/") ? path.slice(2) : path;
-}
-function extractTrackedDiffSectionPath(section) {
-    const firstLineEnd = section.indexOf("\n");
-    const firstLine = firstLineEnd === -1 ? section : section.slice(0, firstLineEnd);
-    const header = firstLine.startsWith("diff --git ") ? firstLine.slice("diff --git ".length) : "";
-    const prefixedPathMatch = header.match(/^a\/(.+) b\/(.+)$/);
-    if (prefixedPathMatch) {
-        return prefixedPathMatch[2] ?? null;
-    }
-    const metadataPath = extractTrackedDiffMetadataPath(section, "+++ ") ??
-        extractTrackedDiffMetadataPath(section, "--- ");
-    if (metadataPath) {
-        return metadataPath;
-    }
-    const pathMatch = header.match(/^(\S+)\s+(\S+)$/);
-    return pathMatch?.[2] ?? null;
-}
-function splitTrackedDiffSections(diffText) {
-    const starts = [];
-    const diffHeaderPattern = /^diff --git /gm;
-    let match;
-    while ((match = diffHeaderPattern.exec(diffText))) {
-        starts.push(match.index);
-    }
-    const sections = [];
-    for (let index = 0; index < starts.length; index += 1) {
-        const start = starts[index];
-        const end = starts[index + 1] ?? diffText.length;
-        const text = diffText.slice(start, end);
-        const path = extractTrackedDiffSectionPath(text);
-        if (!path) {
-            continue;
-        }
-        sections.push({
-            path,
-            text,
-            isTooLarge: text.length > TRACKED_DIFF_PER_FILE_MAX_CHARS,
-        });
-    }
-    return sections;
+async function getTrackedDiffTextForPath(input) {
+    const result = await runGitCommand(buildGitDiffArgs({
+        ignoreWhitespace: input.ignoreWhitespace,
+        extra: [...getCheckoutDiffRefArgs(input.refsForDiff), "--", input.path],
+    }), {
+        cwd: input.cwd,
+        envOverlay: READ_ONLY_GIT_ENV,
+        maxOutputBytes: PER_FILE_DIFF_MAX_BYTES,
+    });
+    return {
+        path: input.path,
+        text: result.stdout,
+        truncated: result.truncated,
+    };
 }
 export class NotGitRepoError extends Error {
     constructor(cwd) {
@@ -1441,7 +1404,7 @@ export function warmCheckoutShortstatInBackground(cwd, context, onComplete) {
     });
 }
 async function appendStructuredTrackedDiffs(input) {
-    const { cwd, trackedChanges, trackedChangeByPath, trackedNumstatByPath, trackedPlaceholderByPath, trackedDiffText, trackedDiffTruncated, refsForDiff, ignoreWhitespace, structured, appendTrackedPlaceholderComment, } = input;
+    const { cwd, trackedChanges, trackedChangeByPath, trackedNumstatByPath, trackedPlaceholderByPath, trackedDiffText, refsForDiff, ignoreWhitespace, structured, appendTrackedPlaceholderComment, } = input;
     const parsedTrackedFiles = trackedDiffText.length > 0
         ? await parseAndHighlightDiff(trackedDiffText, cwd, {
             getOldFileContent: async (file) => {
@@ -1487,7 +1450,6 @@ async function appendStructuredTrackedDiffs(input) {
         // whitespace-filtered patch and numstat are both empty. Skip emitting a
         // structured placeholder in that case so whitespace-only edits truly disappear.
         if (ignoreWhitespace &&
-            !trackedDiffTruncated &&
             change.status.startsWith("M") &&
             (!stat || (!stat.isBinary && stat.additions === 0 && stat.deletions === 0))) {
             continue;
@@ -1499,7 +1461,7 @@ async function appendStructuredTrackedDiffs(input) {
             additions: stat?.additions ?? 0,
             deletions: stat?.deletions ?? 0,
             hunks: [],
-            status: trackedDiffTruncated ? "too_large" : "ok",
+            status: "ok",
         });
     }
 }
@@ -1564,43 +1526,42 @@ async function processTrackedChanges(input) {
         trackedDiffPaths.push(change.path);
     }
     let trackedDiffText = "";
-    let trackedDiffTruncated = false;
+    let trackedDiffBytes = 0;
     if (trackedDiffPaths.length > 0) {
-        const trackedDiffResult = await runGitCommand(buildGitDiffArgs({
-            ignoreWhitespace,
-            extra: [...getCheckoutDiffRefArgs(refsForDiff), "--", ...trackedDiffPaths],
-        }), {
+        const trackedDiffs = await Promise.all(trackedDiffPaths.map((path) => getTrackedDiffTextForPath({
             cwd,
-            envOverlay: READ_ONLY_GIT_ENV,
-            maxOutputBytes: TOTAL_DIFF_MAX_BYTES,
-        });
-        trackedDiffTruncated = trackedDiffResult.truncated;
+            refsForDiff,
+            path,
+            ignoreWhitespace,
+        })));
         const visibleTrackedDiffs = [];
-        const sections = splitTrackedDiffSections(trackedDiffResult.stdout);
-        for (let index = 0; index < sections.length; index += 1) {
-            const section = sections[index];
-            const isTruncatedTail = trackedDiffTruncated && index === sections.length - 1;
-            if (section.isTooLarge || isTruncatedTail) {
-                trackedPlaceholderByPath.set(section.path, {
+        for (const fileDiff of trackedDiffs) {
+            if (fileDiff.truncated) {
+                trackedPlaceholderByPath.set(fileDiff.path, {
                     status: "too_large",
-                    stat: trackedNumstatByPath.get(section.path) ?? null,
+                    stat: trackedNumstatByPath.get(fileDiff.path) ?? null,
                 });
                 continue;
             }
-            visibleTrackedDiffs.push(section.text);
+            const diffBytes = Buffer.byteLength(fileDiff.text, "utf8");
+            if (trackedDiffBytes + diffBytes > TOTAL_DIFF_MAX_BYTES) {
+                trackedPlaceholderByPath.set(fileDiff.path, {
+                    status: "too_large",
+                    stat: trackedNumstatByPath.get(fileDiff.path) ?? null,
+                });
+                continue;
+            }
+            trackedDiffBytes += diffBytes;
+            visibleTrackedDiffs.push(fileDiff.text);
         }
         trackedDiffText = visibleTrackedDiffs.join("");
         appendDiff(trackedDiffText);
-        if (trackedDiffTruncated) {
-            appendDiff("# tracked diff truncated\n");
-        }
     }
     return {
         trackedChangeByPath,
         trackedNumstatByPath,
         trackedPlaceholderByPath,
         trackedDiffText,
-        trackedDiffTruncated,
     };
 }
 async function resolveCheckoutDiffRefs(cwd, compare, context) {
@@ -1690,7 +1651,6 @@ export async function getCheckoutDiff(cwd, compare, context) {
             trackedNumstatByPath: trackedDiff.trackedNumstatByPath,
             trackedPlaceholderByPath: trackedDiff.trackedPlaceholderByPath,
             trackedDiffText: trackedDiff.trackedDiffText,
-            trackedDiffTruncated: trackedDiff.trackedDiffTruncated,
             refsForDiff: effectiveRefsForDiff,
             ignoreWhitespace,
             structured,

package/dist/server/utils/directory-suggestions.js

@@ -24,6 +24,15 @@ const IGNORED_SUGGESTION_DIRECTORY_NAMES = new Set([
     "coverage",
     "vendor",
     "__pycache__",
+    ".git",
+]);
+const TRAVERSABLE_HIDDEN_WORKSPACE_DIRECTORY_NAMES = new Set([
+    ".agents",
+    ".claude",
+    ".codex",
+    ".github",
+    ".paseo",
+    ".vscode",
 ]);
 export async function searchHomeDirectories(options) {
     const query = options.query.trim();
@@ -71,6 +80,17 @@ export async function searchWorkspaceEntries(options) {
         return [];
     }
     const matchMode = options.matchMode ?? "fuzzy";
+    const exactEntry = queryParts.isPathQuery && matchMode === "suffix"
+        ? await resolveWorkspaceExactEntry({
+            workspaceRoot,
+            query: options.query,
+            includeDirectories,
+            includeFiles,
+        })
+        : null;
+    if (exactEntry && limit <= 1) {
+        return [exactEntry];
+    }
     if (queryParts.isPathQuery && matchMode !== "suffix") {
         return searchWorkspaceWithinParentDirectory({
             workspaceRoot,
@@ -84,7 +104,7 @@ export async function searchWorkspaceEntries(options) {
     const searchTerm = matchMode === "suffix"
         ? [queryParts.parentPart, queryParts.searchTerm].filter(Boolean).join("/")
         : queryParts.searchTerm;
-    return searchWorkspaceAcrossTree({
+    const entries = await searchWorkspaceAcrossTree({
         workspaceRoot,
         searchTerm,
         limit,
@@ -94,6 +114,53 @@ export async function searchWorkspaceEntries(options) {
         maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
         maxEntriesScanned: options.maxEntriesScanned ?? DEFAULT_MAX_DIRECTORIES_SCANNED,
     });
+    return exactEntry ? prependWorkspaceEntry(exactEntry, entries).slice(0, limit) : entries;
+}
+async function resolveWorkspaceExactEntry(input) {
+    const normalized = input.query
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/{2,}/g, "/");
+    if (!normalized) {
+        return null;
+    }
+    const candidatePath = path.isAbsolute(normalized)
+        ? path.resolve(normalized)
+        : path.resolve(input.workspaceRoot, normalized);
+    let resolvedPath;
+    try {
+        resolvedPath = await realpath(candidatePath);
+    }
+    catch {
+        return null;
+    }
+    if (!isPathInsideRoot(input.workspaceRoot, resolvedPath)) {
+        return null;
+    }
+    const stats = await stat(resolvedPath).catch(() => null);
+    if (!stats) {
+        return null;
+    }
+    if (stats.isFile() && input.includeFiles) {
+        return {
+            path: normalizeRelativePath(input.workspaceRoot, resolvedPath),
+            kind: "file",
+        };
+    }
+    if (stats.isDirectory() && input.includeDirectories) {
+        return {
+            path: normalizeRelativePath(input.workspaceRoot, resolvedPath),
+            kind: "directory",
+        };
+    }
+    return null;
+}
+function prependWorkspaceEntry(entry, entries) {
+    return [
+        entry,
+        ...entries.filter((candidate) => candidate.kind !== entry.kind || candidate.path !== entry.path),
+    ];
 }
 function normalizeLimit(limit) {
     const candidate = limit ?? DEFAULT_LIMIT;
@@ -185,6 +252,9 @@ async function searchWorkspaceWithinParentDirectory(input) {
         if (entry.kind === "file" && !input.includeFiles) {
             continue;
         }
+        if (isHiddenWorkspaceSuggestion(entry)) {
+            continue;
+        }
         const rankedEntry = rankWorkspaceEntry({
             absolutePath: entry.absolutePath,
             kind: entry.kind,
@@ -230,6 +300,10 @@ async function searchWorkspaceAcrossTree(input) {
             if (entry.kind === "directory" && !input.includeDirectories) {
                 continue;
             }
+            // Hidden directories are traversed, but not offered as suggestions.
+            if (isHiddenWorkspaceSuggestion(entry)) {
+                continue;
+            }
             if (entry.kind === "file" && !input.includeFiles) {
                 continue;
             }
@@ -618,7 +692,23 @@ async function listWorkspaceChildEntries(input) {
         return cached.entries;
     }
     const dirents = await readdir(input.directory, { withFileTypes: true }).catch(() => []);
-    const candidates = dirents.filter((dirent) => !isHiddenDirectoryName(dirent.name) && !isIgnoredSuggestionDirectoryName(dirent.name));
+    const candidates = dirents.filter((dirent) => {
+        if (isIgnoredSuggestionDirectoryName(dirent.name)) {
+            return false;
+        }
+        if (isHiddenDirectoryName(dirent.name) &&
+            !dirent.isFile() &&
+            !isTraversableHiddenWorkspaceDirectoryName(dirent.name)) {
+            return false;
+        }
+        // Allowlisted hidden directories remain traversable so file links like
+        // `.claude/settings.local.json` can resolve, but hidden files (e.g.
+        // `.DS_Store`) should never be suggested.
+        if (dirent.isFile() && isHiddenDirectoryName(dirent.name)) {
+            return false;
+        }
+        return true;
+    });
     const resolved = await Promise.all(candidates.map(async (dirent) => {
         const candidatePath = path.join(input.directory, dirent.name);
         const entry = await resolveWorkspaceCandidate({
@@ -687,9 +777,15 @@ async function resolveWorkspaceCandidate(input) {
 function isHiddenDirectoryName(name) {
     return name.startsWith(".");
 }
+function isHiddenWorkspaceSuggestion(entry) {
+    return isHiddenDirectoryName(entry.name);
+}
 function isIgnoredSuggestionDirectoryName(name) {
     return IGNORED_SUGGESTION_DIRECTORY_NAMES.has(name);
 }
+function isTraversableHiddenWorkspaceDirectoryName(name) {
+    return TRAVERSABLE_HIDDEN_WORKSPACE_DIRECTORY_NAMES.has(name);
+}
 function setDirectoryListCache(cacheKey, entry) {
     directoryListCache.set(cacheKey, entry);
     pruneDirectoryListCache();