dsh-reference-anything 0.2.4 → 0.3.0

package/lib/contract.d.ts

@@ -1,18 +1,5 @@
 import { z } from 'zod';
 import type { InvocationDescriptor } from '@deepseek-ai/dsh-typert-protocol';
-export declare const workspaceEntrySchema: z.ZodReadonly<z.ZodObject<{
-    path: z.ZodString;
-    kind: z.ZodEnum<{
-        file: "file";
-        directory: "directory";
-    }>;
-}, z.core.$strip>>;
-export declare const sessionCandidateSchema: z.ZodReadonly<z.ZodObject<{
-    sessionId: z.ZodString;
-    label: z.ZodString;
-    cwd: z.ZodOptional<z.ZodString>;
-    createdAt: z.ZodNumber;
-}, z.core.$strip>>;
 export declare const searchInputSchema: z.ZodReadonly<z.ZodObject<{
     query: z.ZodString;
     provider: z.ZodOptional<z.ZodEnum<{
@@ -79,6 +66,7 @@ export declare const healthSchema: z.ZodReadonly<z.ZodObject<{
     daemonVersion: z.ZodOptional<z.ZodString>;
     daemonStale: z.ZodBoolean;
     connectivityOk: z.ZodBoolean;
+    connectivityChecked: z.ZodBoolean;
     pluginVersion: z.ZodOptional<z.ZodString>;
     adapterCommandsReady: z.ZodBoolean;
     adapterCompatible: z.ZodBoolean;
@@ -110,6 +98,19 @@ export declare const packageUpdateResultSchema: z.ZodReadonly<z.ZodObject<{
     version: z.ZodString;
     restartRequired: z.ZodBoolean;
 }, z.core.$strip>>;
+export declare const referenceUiModeInputSchema: z.ZodReadonly<z.ZodObject<{
+    mode: z.ZodEnum<{
+        plugin: "plugin";
+        official: "official";
+    }>;
+}, z.core.$strip>>;
+export declare const referenceUiSwitchResultSchema: z.ZodReadonly<z.ZodObject<{
+    mode: z.ZodEnum<{
+        plugin: "plugin";
+        official: "official";
+    }>;
+    restartRequired: z.ZodLiteral<false>;
+}, z.core.$strip>>;
 export declare const providerStatsSchema: z.ZodReadonly<z.ZodObject<{
     provider: z.ZodEnum<{
         chatgpt: "chatgpt";

package/lib/contract.js

@@ -1,9 +1,5 @@
 import { z } from 'zod';
-import { providerSchema, settingsRecordSchema } from "./wire.js";
-export const workspaceEntrySchema = z.object({ path: z.string(), kind: z.enum(['file', 'directory']) }).readonly();
-export const sessionCandidateSchema = z.object({ sessionId: z.string(), label: z.string(), cwd: z.string().optional(), createdAt: z.number() }).readonly();
-const agentLookup = { name: 'agent', wire: 'agentId', source: 'lookup', lookup: 'agent',
-    codec: { mode: 'strict', typeSymbol: '@deepseek-ai/dsh-session/types#SessionId', schema: z.string().min(1) } };
+import { providerSchema, referenceUiModeSchema, settingsRecordSchema } from "./wire.js";
 export const searchInputSchema = z.object({
     query: z.string(), provider: providerSchema.optional(), limit: z.number().int().min(1).max(100),
 }).readonly();
@@ -19,7 +15,7 @@ export const healthSchema = z.object({
     daemonRunning: z.boolean(), extensionConnected: z.boolean(), extensionState: extensionStateSchema,
     extensionVersion: z.string().optional(), profileCount: z.number().int().nonnegative().optional(),
     opencliCompatible: z.boolean(), daemonVersion: z.string().optional(), daemonStale: z.boolean(),
-    connectivityOk: z.boolean(), pluginVersion: z.string().optional(), adapterCommandsReady: z.boolean(), adapterCompatible: z.boolean(),
+    connectivityOk: z.boolean(), connectivityChecked: z.boolean(), pluginVersion: z.string().optional(), adapterCommandsReady: z.boolean(), adapterCompatible: z.boolean(),
     versionError: z.string().optional(), daemonError: z.string().optional(), pluginError: z.string().optional(), doctorError: z.string().optional(),
 }).readonly();
 export const browserProfileSchema = z.object({ id: z.string(), alias: z.string().optional(), connected: z.boolean(), isDefault: z.boolean() }).readonly();
@@ -33,6 +29,8 @@ export const packageUpdateStatusSchema = z.object({
 export const packageUpdateResultSchema = z.object({
     version: z.string(), restartRequired: z.boolean(),
 }).readonly();
+export const referenceUiModeInputSchema = z.object({ mode: referenceUiModeSchema }).readonly();
+export const referenceUiSwitchResultSchema = z.object({ mode: referenceUiModeSchema, restartRequired: z.literal(false) }).readonly();
 export const providerStatsSchema = z.object({
     provider: providerSchema, conversations: z.number().int().nonnegative(), lastSyncedAt: z.string(),
     status: z.enum(['ready', 'syncing', 'error', 'empty']), error: z.string().optional(),
@@ -72,10 +70,9 @@ export const providerSyncStateSchema = z.object({
     lastSyncAt: z.string(), lastCompleteScanAt: z.string(), error: z.string(),
 }).readonly();
 export const REFERENCE_ANYTHING_INVOCATIONS = [
-    descriptor('workspaceSearch', [agentLookup], strict('WorkspaceEntry[]', z.array(workspaceEntrySchema)), true),
-    descriptor('sessionSearch', [agentLookup, { name: 'input', wire: 'input', source: 'json', codec: strict('SessionSearchInput', z.object({ query: z.string(), limit: z.number().int().min(1).max(100) }).readonly()) }], strict('SessionCandidate[]', z.array(sessionCandidateSchema)), true),
     descriptor('search', [{ name: 'input', wire: 'input', source: 'json', codec: strict('SearchInput', searchInputSchema) }], strict('SearchResult[]', z.array(searchResultSchema)), true),
     descriptor('health', [], strict('Health', healthSchema), true),
+    descriptor('quickHealth', [], strict('Health', healthSchema), true),
     descriptor('profiles', [], strict('BrowserProfile[]', z.array(browserProfileSchema)), true),
     descriptor('discoverOpenCli', [], strict('OpenCliDiscovery', openCliDiscoverySchema), true),
     descriptor('installOpenCli', [], strict('OpenCliDiscovery', openCliDiscoverySchema), true),
@@ -84,6 +81,7 @@ export const REFERENCE_ANYTHING_INVOCATIONS = [
     descriptor('updateStatus', [], strict('PackageUpdateStatus', packageUpdateStatusSchema), true),
     descriptor('checkUpdate', [], strict('PackageUpdateStatus', packageUpdateStatusSchema), true),
     descriptor('installUpdate', [], strict('PackageUpdateResult', packageUpdateResultSchema), true),
+    descriptor('switchReferenceUiMode', [{ name: 'input', wire: 'input', source: 'json', codec: strict('ReferenceUiModeInput', referenceUiModeInputSchema) }], strict('ReferenceUiSwitchResult', referenceUiSwitchResultSchema), true),
     descriptor('stats', [], strict('ProviderStats[]', z.array(providerStatsSchema))),
     descriptor('syncStart', [{ name: 'input', wire: 'input', source: 'json', codec: strict('SyncStart', syncStartSchema) }], strict('JobId', z.string())),
     descriptor('syncStatus', [{ name: 'input', wire: 'input', source: 'json', codec: strict('JobInput', jobInputSchema) }], strict('SyncStatus?', syncStatusSchema.optional())),

package/lib/host.d.ts

@@ -1,26 +1,17 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { ChatProvider, SettingsRecord } from './store/spec.ts';
+import type { ReferenceUiMode } from './wire.ts';
 import type { SyncMode } from './sync/index.ts';
-import type { Agent } from '@deepseek-ai/dsh-agent';
 export declare class ReferenceAnythingRemote extends TypertRemoteService {
     constructor(ctx: Context);
-    workspaceSearch(agent: Agent, signal: AbortSignal): Promise<import("./workspace.ts").WorkspaceEntry[]>;
-    sessionSearch(agent: Agent, input: {
-        query: string;
-        limit: number;
-    }, signal: AbortSignal): Promise<{
-        sessionId: string;
-        label: string;
-        cwd?: string;
-        createdAt: number;
-    }[]>;
     search(input: {
         query: string;
         provider?: ChatProvider;
         limit: number;
     }, signal: AbortSignal): Promise<import("./sources/web-chat/index.ts").ConversationSearchResult[]>;
     health(signal: AbortSignal): Promise<import("./opencli.ts").OpenCliHealth>;
+    quickHealth(signal: AbortSignal): Promise<import("./opencli.ts").OpenCliHealth>;
     profiles(signal: AbortSignal): Promise<import("./opencli.ts").BrowserProfile[]>;
     discoverOpenCli(signal: AbortSignal): Promise<import("./opencli.ts").OpenCliDiscovery>;
     installOpenCli(signal: AbortSignal): Promise<import("./opencli.ts").OpenCliDiscovery>;
@@ -29,6 +20,9 @@ export declare class ReferenceAnythingRemote extends TypertRemoteService {
     updateStatus(signal: AbortSignal): Promise<import("./update.ts").PackageUpdateStatus>;
     checkUpdate(signal: AbortSignal): Promise<import("./update.ts").PackageUpdateStatus>;
     installUpdate(signal: AbortSignal): Promise<import("./update.ts").PackageUpdateResult>;
+    switchReferenceUiMode(input: {
+        mode: ReferenceUiMode;
+    }, signal: AbortSignal): Promise<import("./profile-mode.ts").ReferenceUiSwitchResult>;
     stats(): import("./store/store.ts").ProviderStats[];
     syncStart(input: {
         providers: ChatProvider[];
@@ -52,31 +46,38 @@ export declare class ReferenceAnythingRemote extends TypertRemoteService {
         enabledProviders: ("chatgpt" | "claude" | "gemini" | "deepseek" | "grok" | "kimi")[];
         maxReadTurns: number;
         inputRenderMode: "pill" | "raw-text";
+        referenceUiMode?: "plugin" | "official" | undefined;
         picker?: {
+            displayMode: "collapse" | "native-scroll";
             commands: {
                 enabled: boolean;
                 order: number;
                 limit: number;
+                maxCandidates: number;
             };
             skills: {
                 enabled: boolean;
                 order: number;
                 limit: number;
+                maxCandidates: number;
             };
             files: {
                 enabled: boolean;
                 order: number;
                 limit: number;
+                maxCandidates: number;
             };
             sessions: {
                 enabled: boolean;
                 order: number;
                 limit: number;
+                maxCandidates: number;
             };
             conversations: {
                 enabled: boolean;
                 order: number;
                 limit: number;
+                maxCandidates: number;
             };
         } | undefined;
     }>;

package/lib/host.js

@@ -1,18 +1,13 @@
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import { encodeSessionReferenceUri } from '@deepseek-ai/dsh-session-reference';
-import { indexWorkspace } from "./workspace.js";
+import { switchReferenceUiMode as switchProfileReferenceUiMode } from "./profile-mode.js";
 export class ReferenceAnythingRemote extends TypertRemoteService {
     constructor(ctx) { super(ctx, 'referenceAnything'); }
-    workspaceSearch(agent, signal) { return indexWorkspace(agent, signal); }
-    async sessionSearch(agent, input, signal) {
-        const rows = await this.ctx.sessionReferenceResolver.listCandidates(agent, input.query, input.limit, signal);
-        return rows.map(row => ({ ...row, sessionId: encodeSessionReferenceUri(row.sessionId) }));
-    }
     search(input, signal) {
         signal.throwIfAborted();
         return this.ctx.referenceChatHistory.search(input.query, input.provider, input.limit, signal);
     }
     health(signal) { return this.ctx.referenceChatHistory.health(signal); }
+    quickHealth(signal) { return this.ctx.referenceChatHistory.quickHealth(signal); }
     profiles(signal) { return this.ctx.referenceChatHistory.profiles(signal); }
     discoverOpenCli(signal) { return this.ctx.referenceChatHistory.discoverOpenCli(signal); }
     installOpenCli(signal) { return this.ctx.referenceChatHistory.installOpenCli(signal); }
@@ -21,6 +16,19 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
     updateStatus(signal) { return this.ctx.referenceChatHistory.updateStatus(signal); }
     checkUpdate(signal) { return this.ctx.referenceChatHistory.checkUpdate(signal); }
     installUpdate(signal) { return this.ctx.referenceChatHistory.installUpdate(signal); }
+    async switchReferenceUiMode(input, signal) {
+        const settings = this.ctx.referenceChatHistory.getSettings();
+        const previousMode = settings.referenceUiMode ?? 'plugin';
+        const result = await switchProfileReferenceUiMode({ mode: input.mode, signal });
+        try {
+            await this.ctx.referenceChatHistory.updateSettings({ ...settings, referenceUiMode: input.mode });
+        }
+        catch (error) {
+            await switchProfileReferenceUiMode({ mode: previousMode }).catch(() => undefined);
+            throw error;
+        }
+        return result;
+    }
     stats() { return this.ctx.referenceChatHistory.stats(); }
     syncStart(input) {
         return this.ctx.referenceChatHistory.sync.start(input.providers, input.mode);

package/lib/opencli.d.ts

@@ -1,7 +1,7 @@
 import type { ChatProvider } from './store/spec.ts';
 import type { ProviderConversationRow, ProviderTurnRow } from './store/store.ts';
 export declare const MIN_OPENCLI_VERSION = "1.8.6";
-export declare const MIN_ADAPTER_VERSION = "0.2.1";
+export declare const MIN_ADAPTER_VERSION = "0.2.2";
 export declare const OPENCLI_NPM_PACKAGE = "@jackwener/opencli";
 export type OpenCliErrorCode = 'EXTENSION_NOT_CONNECTED' | 'PROVIDER_TIMEOUT' | 'PROVIDER_NOT_LOGGED_IN' | 'PROVIDER_ACCOUNT_MISMATCH' | 'OPENCLI_CONFIGURATION' | 'OPENCLI_OUTPUT_TOO_LARGE' | 'OPENCLI_FAILED' | 'OPENCLI_INSTALL_FAILED';
 export declare class OpenCliError extends Error {
@@ -32,6 +32,7 @@ export interface OpenCliHealth {
     daemonVersion?: string;
     daemonStale: boolean;
     connectivityOk: boolean;
+    connectivityChecked: boolean;
     pluginVersion?: string;
     adapterCommandsReady: boolean;
     adapterCompatible: boolean;
@@ -96,6 +97,9 @@ export declare class OpenCliRunner {
     detail(provider: ChatProvider, id: string, signal?: AbortSignal, accountScope?: string): Promise<ProviderTurnRow[]>;
     attachment(provider: ChatProvider, locator: string, output: string, maxBytes: number, signal?: AbortSignal): Promise<Record<string, unknown>>;
     health(signal?: AbortSignal): Promise<OpenCliHealth>;
+    /** Inspect local OpenCLI, daemon, extension and plugin state without an active connectivity probe. */
+    quickHealth(signal?: AbortSignal): Promise<OpenCliHealth>;
+    private inspectHealth;
     /** Lightweight executable validation used by automatic path discovery. */
     version(signal?: AbortSignal): Promise<string>;
     /** Confirm the executable also exposes OpenCLI's plugin command, not merely a semver-looking --version. */

package/lib/opencli.js

@@ -5,7 +5,7 @@ import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
 const execFile = promisify(nodeExecFile);
 export const MIN_OPENCLI_VERSION = '1.8.6';
-export const MIN_ADAPTER_VERSION = '0.2.1';
+export const MIN_ADAPTER_VERSION = '0.2.2';
 export const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
 const SITE = {
     chatgpt: 'dsh-chatgpt', claude: 'dsh-claude', gemini: 'dsh-gemini',
@@ -13,13 +13,6 @@ const SITE = {
 };
 const REQUIRED_ADAPTER_COMMANDS = ['chatgpt', 'claude', 'gemini', 'deepseek', 'grok', 'kimi'];
 const ADAPTER_PLUGIN_NAME = 'dsh-chat-history';
-/**
- * A persistent OpenCLI site session owns one mutable browser tab. Serialize
- * commands that target the same executable/profile/site across runner
- * instances so concurrent detail workers cannot navigate that tab over one
- * another. Different provider sites still run in parallel.
- */
-const SITE_COMMAND_TAILS = new Map();
 export class OpenCliError extends Error {
     code;
     constructor(message, code, options) {
@@ -119,9 +112,16 @@ export class OpenCliRunner {
         return rows[0] ?? {};
     }
     async health(signal) {
+        return this.inspectHealth(true, signal);
+    }
+    /** Inspect local OpenCLI, daemon, extension and plugin state without an active connectivity probe. */
+    async quickHealth(signal) {
+        return this.inspectHealth(false, signal);
+    }
+    async inspectHealth(checkConnectivity, signal) {
         const [version, daemon, plugins, doctor] = await Promise.all([
             this.probe(['--version'], signal), this.probe(['daemon', 'status'], signal), this.probe(['plugin', 'list'], signal),
-            this.probe(['doctor'], signal),
+            checkConnectivity ? this.probe(['doctor'], signal) : Promise.resolve({ value: '', diagnostic: '' }),
         ]);
         const status = parseDaemonStatus(daemon.value);
         const cliVersion = normalizeVersion(version.value);
@@ -137,7 +137,7 @@ export class OpenCliRunner {
         return {
             version: cliVersion, daemon: daemon.value.trim(), pluginInstalled,
             daemonRunning: status.daemonRunning, extensionConnected: status.extensionConnected, extensionState: status.extensionState,
-            opencliCompatible, daemonStale, connectivityOk,
+            opencliCompatible, daemonStale, connectivityOk, connectivityChecked: checkConnectivity,
             ...(status.extensionVersion ? { extensionVersion: status.extensionVersion } : {}),
             ...(status.profileCount !== undefined ? { profileCount: status.profileCount } : {}),
             ...(daemonVersion ? { daemonVersion: normalizeVersion(daemonVersion) } : {}),
@@ -147,7 +147,7 @@ export class OpenCliRunner {
             ...(version.error ? { versionError: version.error } : {}),
             ...(daemon.error ? { daemonError: daemon.error } : {}),
             ...(plugins.error || adapterLoadError ? { pluginError: plugins.error || adapterLoadError } : {}),
-            ...(doctor.error ? { doctorError: doctor.error } : {}),
+            ...('error' in doctor && doctor.error ? { doctorError: doctor.error } : {}),
         };
     }
     /** Lightweight executable validation used by automatic path discovery. */
@@ -208,25 +208,21 @@ export class OpenCliRunner {
         }
     }
     async json(site, operation, args, signal) {
-        const queueKey = [this.executable, ...this.prefixArgs, this.profile, site].join('\0');
-        return serializeSiteCommand(queueKey, async () => {
-            // Pin adapter traffic to one persistent background session. OpenCLI
-            // otherwise lets caller flags override the adapter lifecycle metadata,
-            // which could release its tab or make an unattended sync steal focus.
-            const stdout = await this.raw([
-                site, operation, ...args,
-                '--site-session', 'persistent', '--window', 'background', '-f', 'json',
-            ], signal);
-            try {
-                const parsed = JSON.parse(stdout);
-                if (!Array.isArray(parsed) || parsed.some(row => !row || typeof row !== 'object' || Array.isArray(row)))
-                    throw new Error('expected object array');
-                return parsed;
-            }
-            catch (error) {
-                throw new OpenCliError('OpenCLI returned malformed JSON', 'OPENCLI_CONFIGURATION', { cause: error });
-            }
-        });
+        // Match the sync-index lifecycle: every command gets its own temporary
+        // background tab, so providers and detail workers can run independently.
+        const stdout = await this.raw([
+            site, operation, ...args,
+            '--site-session', 'ephemeral', '--window', 'background', '-f', 'json',
+        ], signal);
+        try {
+            const parsed = JSON.parse(stdout);
+            if (!Array.isArray(parsed) || parsed.some(row => !row || typeof row !== 'object' || Array.isArray(row)))
+                throw new Error('expected object array');
+            return parsed;
+        }
+        catch (error) {
+            throw new OpenCliError('OpenCLI returned malformed JSON', 'OPENCLI_CONFIGURATION', { cause: error });
+        }
     }
     async raw(args, signal) {
         return (await this.command(args, signal)).stdout;
@@ -263,19 +259,6 @@ function adapterPluginLoadError(diagnostic = '') {
         .filter(line => /Plugin dsh-chat-history\//i.test(line));
     return [...new Set(lines)].join('\n').slice(0, 2_000);
 }
-async function serializeSiteCommand(key, task) {
-    const previous = SITE_COMMAND_TAILS.get(key) ?? Promise.resolve();
-    const current = previous.then(task, task);
-    const settled = current.then(() => undefined, () => undefined);
-    SITE_COMMAND_TAILS.set(key, settled);
-    try {
-        return await current;
-    }
-    finally {
-        if (SITE_COMMAND_TAILS.get(key) === settled)
-            SITE_COMMAND_TAILS.delete(key);
-    }
-}
 /** Locate a working OpenCLI without asking a command-line newcomer for PATH details. */
 export async function discoverOpenCli(configured = 'opencli', signal) {
     const candidates = openCliCandidates(configured);

package/lib/profile-mode.d.ts

@@ -0,0 +1,30 @@
+import type { ReferenceUiMode } from './wire.ts';
+export declare const OFFICIAL_REFERENCE_PATCH_BEGIN = "# BEGIN dsh-reference-anything managed official-reference override";
+export declare const OFFICIAL_REFERENCE_PATCH_END = "# END dsh-reference-anything managed official-reference override";
+export interface ReferenceUiSwitchResult {
+    mode: ReferenceUiMode;
+    restartRequired: false;
+}
+interface SwitchReferenceUiModeOptions {
+    mode: ReferenceUiMode;
+    packageRoot?: string;
+    dshHome?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Switch only the visible @ implementation while keeping this package alive.
+ *
+ * The bundle patch remains untouched so updating or reinstalling the package
+ * cannot erase the user's choice. The plugin Host and settings entry remain
+ * active in both modes; the client separately registers or disposes its own
+ * picker sources.
+ */
+export declare function switchReferenceUiMode(options: SwitchReferenceUiModeOptions): Promise<ReferenceUiSwitchResult>;
+/** Write the managed override without exposing a partially-written YAML file. */
+export declare function writeReferenceUiModeOverride(path: string, mode: ReferenceUiMode, signal?: AbortSignal): Promise<void>;
+/**
+ * Preserve every user-owned row and append one idempotent block at the end,
+ * where Cordis' ordered patch semantics make it the effective override.
+ */
+export declare function withReferenceUiModeOverride(source: string, mode: ReferenceUiMode): string;
+export {};

package/lib/profile-mode.js

@@ -0,0 +1,90 @@
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { findOwningProfileDir } from "./update.js";
+export const OFFICIAL_REFERENCE_PATCH_BEGIN = '# BEGIN dsh-reference-anything managed official-reference override';
+export const OFFICIAL_REFERENCE_PATCH_END = '# END dsh-reference-anything managed official-reference override';
+/**
+ * Switch only the visible @ implementation while keeping this package alive.
+ *
+ * The bundle patch remains untouched so updating or reinstalling the package
+ * cannot erase the user's choice. The plugin Host and settings entry remain
+ * active in both modes; the client separately registers or disposes its own
+ * picker sources.
+ */
+export async function switchReferenceUiMode(options) {
+    options.signal?.throwIfAborted();
+    const profileDir = await findOwningProfileDir(options.packageRoot, options.dshHome);
+    await writeReferenceUiModeOverride(join(profileDir, 'cordis.patch.yml'), options.mode, options.signal);
+    return { mode: options.mode, restartRequired: false };
+}
+/** Write the managed override without exposing a partially-written YAML file. */
+export async function writeReferenceUiModeOverride(path, mode, signal) {
+    signal?.throwIfAborted();
+    let source = '';
+    try {
+        source = await readFile(path, { encoding: 'utf8', signal });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT')
+            throw error;
+    }
+    const next = withReferenceUiModeOverride(source, mode);
+    if (next === source)
+        return;
+    const temporary = join(dirname(path), `.cordis.patch.yml.dsh-reference-anything-${String(process.pid)}-${String(Date.now())}.tmp`);
+    try {
+        await writeFile(temporary, next, { encoding: 'utf8', signal });
+        signal?.throwIfAborted();
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Preserve every user-owned row and append one idempotent block at the end,
+ * where Cordis' ordered patch semantics make it the effective override.
+ */
+export function withReferenceUiModeOverride(source, mode) {
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const lines = source.split(/\r?\n/);
+    const beginRows = markerRows(lines, OFFICIAL_REFERENCE_PATCH_BEGIN);
+    const endRows = markerRows(lines, OFFICIAL_REFERENCE_PATCH_END);
+    if (beginRows.length > 1 || endRows.length > 1 || beginRows.length !== endRows.length) {
+        throw new Error('the managed official-reference block in cordis.patch.yml is malformed');
+    }
+    if (beginRows.length === 1) {
+        const begin = beginRows[0];
+        const end = endRows[0];
+        if (end < begin)
+            throw new Error('the managed official-reference block in cordis.patch.yml is malformed');
+        lines.splice(begin, end - begin + 1);
+    }
+    removeEmptyArrayDocument(lines);
+    while (lines.length > 0 && lines.at(-1)?.trim() === '')
+        lines.pop();
+    const block = [
+        OFFICIAL_REFERENCE_PATCH_BEGIN,
+        '# Switch only the visible @ implementation; Reference Anything stays loaded.',
+        '- id: ui-reference',
+        `  disabled: ${mode === 'official' ? 'false' : 'true'}`,
+        OFFICIAL_REFERENCE_PATCH_END,
+    ];
+    return [...lines, ...(lines.length > 0 ? [''] : []), ...block, ''].join(eol);
+}
+function markerRows(lines, marker) {
+    const rows = [];
+    lines.forEach((line, index) => { if (line.trim() === marker)
+        rows.push(index); });
+    return rows;
+}
+/** `[]` is the valid empty profile document, but cannot precede list rows. */
+function removeEmptyArrayDocument(lines) {
+    const meaningful = lines
+        .map((line, index) => ({ index, text: line.trim() }))
+        .filter(row => row.text !== '' && !row.text.startsWith('#'));
+    if (meaningful.length === 1 && meaningful[0]?.text === '[]')
+        lines.splice(meaningful[0].index, 1);
+}

package/lib/reference.d.ts

@@ -8,11 +8,9 @@
  * the loop durably appends, so injected material is logged by construction and
  * a replay reconstructs the request exactly.
  *
- * Two schemes are expanded. `dsh-ref:` names material outside the harness and
- * is resolved through `ctx.references`. `dsh-session:` names another harness
- * session and is delegated to `ctx.sessionReferenceResolver`, which owns
- * session-surface semantics — compaction folding, shadowed events, cited event
- * seqs — that do not generalize to an outside conversation.
+ * This plugin owns only `dsh-ref:`, which names material outside the harness
+ * and is resolved through `ctx.references`. Native file and DSH-session
+ * references are owned end-to-end by their official DSH services.
  *
  * @module dsh-reference-anything/reference
  */
@@ -32,12 +30,6 @@ export interface Config {
      * background, and the byte budget multiplies by the same factor.
      */
     maxReferences?: number;
-    /**
-     * Also expand `dsh-session:` mentions. Deployments that deliberately do not
-     * mount the cross-session resolver set this false, so such a mention is
-     * refused as unsupported rather than probed for on every message.
-     */
-    serveSessionScheme?: boolean;
 }
 /** Runtime schema for {@link Config}. */
 export declare const Config: z<Config>;