dsh-reference-anything 0.2.0

package/lib/search.js

@@ -0,0 +1,126 @@
+/**
+ * Query parsing and relevance scoring for conversation discovery. Pure — no
+ * Node builtins, no cordis — because both the Host source and the browser
+ * bundle import it.
+ *
+ * The `@` mention path constrains this more than it looks: the trigger token
+ * ends at the first whitespace (ui-input-trigger `core/detect.ts`), so a
+ * mention query is always a single space-free run of characters. That rules
+ * out `@chatgpt cache` and it rules out multi-word title search, which is why
+ * the provider separator is `:`/`/` and why matching falls back to a
+ * subsequence pass rather than demanding a contiguous substring.
+ */
+/** Spellings accepted in a provider prefix, including short forms worth typing. */
+const PROVIDER_ALIASES = {
+    chatgpt: 'chatgpt', gpt: 'chatgpt', openai: 'chatgpt',
+    claude: 'claude',
+    gemini: 'gemini',
+    deepseek: 'deepseek', ds: 'deepseek',
+    grok: 'grok',
+    kimi: 'kimi',
+};
+/** Provider prefix followed by a separator that survives `@` token detection, or by nothing. */
+const PROVIDER_PREFIX = /^@?([A-Za-z]+)(?:[:/\s]+([\s\S]*))?$/u;
+/**
+ * Split a leading provider scope off a query.
+ *
+ * `:` and `/` are the separators that survive `@` token detection; whitespace
+ * is accepted too because the model-facing `reference_list` path is not bound
+ * by the token rules. A bare provider name scopes to that provider with an
+ * empty query — `@claude` is the fast "show me my Claude chats" gesture.
+ * @param value - raw query, with or without a provider prefix.
+ * @returns the recognized provider (if any) and the remaining query.
+ */
+export function parseProviderQuery(value) {
+    const trimmed = value.trim();
+    const match = PROVIDER_PREFIX.exec(trimmed);
+    if (!match)
+        return { query: trimmed };
+    const provider = PROVIDER_ALIASES[match[1].toLocaleLowerCase()];
+    if (!provider)
+        return { query: trimmed };
+    return { provider, query: (match[2] ?? '').trim() };
+}
+/**
+ * Match quality bands, best last. Ordered, and a band always outranks every
+ * weaker one — within-band tiebreakers never cross a band boundary.
+ */
+export const MATCH_TIER = {
+    subsequence: 1,
+    substring: 2,
+    wordBoundary: 3,
+    prefix: 4,
+    exact: 5,
+};
+/** Separators a user might type that should not affect matching. */
+const LOOSE = /[\s\-_.]/u;
+const LOOSE_ALL = /[\s\-_.]+/gu;
+/**
+ * Score one title against a needle.
+ *
+ * The subsequence band is what makes a space-free query usable: `cachedes`
+ * and `cache-design` both reach "Cache design notes", which no substring
+ * search can do once the token cannot hold a space.
+ * @param title - conversation title.
+ * @param needle - user query, already stripped of any provider prefix.
+ * @returns the match, or undefined when the title does not match at all.
+ */
+export function scoreTitle(title, needle) {
+    const query = needle.trim().toLocaleLowerCase();
+    if (query === '')
+        return undefined;
+    const haystack = title.toLocaleLowerCase();
+    if (haystack === query)
+        return { tier: MATCH_TIER.exact, at: 0, span: query.length };
+    const at = haystack.indexOf(query);
+    if (at === 0)
+        return { tier: MATCH_TIER.prefix, at, span: query.length };
+    if (at > 0) {
+        const tier = LOOSE.test(haystack.charAt(at - 1)) ? MATCH_TIER.wordBoundary : MATCH_TIER.substring;
+        return { tier, at, span: query.length };
+    }
+    return subsequence(haystack, query.replace(LOOSE_ALL, ''));
+}
+/**
+ * Locate `query`'s characters in order, not necessarily adjacent.
+ * @returns the match spanning the earliest greedy run, or undefined.
+ */
+function subsequence(haystack, query) {
+    if (query === '')
+        return undefined;
+    let first = -1;
+    let cursor = 0;
+    for (const char of query) {
+        const found = haystack.indexOf(char, cursor);
+        if (found < 0)
+            return undefined;
+        if (first < 0)
+            first = found;
+        cursor = found + char.length;
+    }
+    return { tier: MATCH_TIER.subsequence, at: first, span: cursor - first };
+}
+/**
+ * Order two matches best-first. Band dominates; within a band a tighter,
+ * earlier match wins. Callers break remaining ties on recency.
+ * @returns negative when `a` should sort before `b`.
+ */
+export function compareMatches(a, b) {
+    return (b.tier - a.tier) || (a.span - b.span) || (a.at - b.at);
+}
+/**
+ * Excerpt the text around a hit for display beside a search result.
+ *
+ * UI only: this is mirrored conversation content, and it must not reach the
+ * model outside the untrusted-data envelope `reference_read` builds.
+ * @param text - the full text the hit was found in.
+ * @param at - offset of the hit.
+ * @param radius - characters of context to keep on each side.
+ * @returns a whitespace-collapsed excerpt, elided where it was cut.
+ */
+export function snippet(text, at, radius = 30) {
+    const start = Math.max(0, at - radius);
+    const end = Math.min(text.length, at + radius);
+    const body = text.slice(start, end).replace(/\s+/gu, ' ').trim();
+    return `${start > 0 ? '…' : ''}${body}${end < text.length ? '…' : ''}`;
+}

package/lib/serialize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tag-safe JSON for text that is framed inside pseudo-XML tags.
+ *
+ * @module dsh-reference-anything/serialize
+ */
+/**
+ * Serialize a value as JSON in which no `<` survives literally.
+ *
+ * Referenced material is untrusted text placed inside a
+ * `<referenced-conversations>` frame. Without this, a conversation whose
+ * content spells that frame's closing tag would appear to end the data region,
+ * and everything after it would read to the model as the harness speaking
+ * rather than as quoted material.
+ *
+ * Each one becomes its six-character JSON unicode escape instead. That escape
+ * is valid only inside a JSON string, and a literal `<` only ever occurs
+ * inside string literals in `JSON.stringify` output, so the substitution is
+ * lossless: parsing the result yields the original value exactly.
+ * @param value - any JSON-serializable value.
+ * @returns indented JSON carrying no literal `<`.
+ */
+export declare function stringifyTagSafeJson(value: unknown): string;

package/lib/serialize.js

@@ -0,0 +1,24 @@
+/**
+ * Tag-safe JSON for text that is framed inside pseudo-XML tags.
+ *
+ * @module dsh-reference-anything/serialize
+ */
+/**
+ * Serialize a value as JSON in which no `<` survives literally.
+ *
+ * Referenced material is untrusted text placed inside a
+ * `<referenced-conversations>` frame. Without this, a conversation whose
+ * content spells that frame's closing tag would appear to end the data region,
+ * and everything after it would read to the model as the harness speaking
+ * rather than as quoted material.
+ *
+ * Each one becomes its six-character JSON unicode escape instead. That escape
+ * is valid only inside a JSON string, and a literal `<` only ever occurs
+ * inside string literals in `JSON.stringify` output, so the substitution is
+ * lossless: parsing the result yields the original value exactly.
+ * @param value - any JSON-serializable value.
+ * @returns indented JSON carrying no literal `<`.
+ */
+export function stringifyTagSafeJson(value) {
+    return JSON.stringify(value, null, 2).replace(/</gu, '\\u003c');
+}

package/lib/sources/file.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Reference source over exported conversations stored on disk.
+ *
+ * Every chat product can export a conversation, and an exported file is the
+ * one form of outside material that needs no browser, no credentials, and no
+ * network — which also makes it the source that end-to-end tests can drive.
+ *
+ * @module dsh-reference-anything/file
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ConversationItem, ReferenceRef, ReferenceSnapshot, ReferenceSource, ReferenceSummary, ReferenceWindow } from '../types.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "reference-file";
+/** The registry this source registers into. */
+export declare const inject: string[];
+/** Registry id, and the `source` half of every reference this source owns. */
+export declare const FILE_SOURCE_ID = "file";
+/** Deployment settings for the file source. */
+export interface Config {
+    /**
+     * Directories holding exported conversations. Required and never defaulted:
+     * a reference source that reads an unbounded part of the filesystem by
+     * default is not a safe thing to mount.
+     */
+    roots?: string[];
+    /** File extensions treated as exports. */
+    extensions?: string[];
+}
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * On-disk export document.
+ *
+ * Deliberately smaller than {@link ReferenceSnapshot}: this is a format people
+ * and export scripts write by hand, so it carries only what cannot be derived.
+ */
+interface ExportDocument {
+    readonly label?: string;
+    readonly origin?: string;
+    readonly updatedAt?: number;
+    readonly messages: readonly ConversationItem[];
+}
+/** Reads exported conversations out of a fixed set of directories. */
+export declare class FileReferenceSource implements ReferenceSource {
+    private readonly roots;
+    private readonly extensions;
+    readonly id = "file";
+    /**
+     * @param roots - absolute or process-relative directories to search.
+     * @param extensions - file extensions treated as exports.
+     */
+    constructor(roots: readonly string[], extensions: readonly string[]);
+    /** @returns whether at least one configured root is a readable directory. */
+    available(): Promise<boolean>;
+    /**
+     * List exports whose label, id, or filename contains `query`.
+     * @param query - case-insensitive substring; empty matches everything.
+     * @param limit - maximum items to return.
+     * @param signal - cancellation from the caller.
+     * @returns matching exports, at most `limit`.
+     */
+    list(query: string, limit: number, signal?: AbortSignal): Promise<ReferenceSummary[]>;
+    /**
+     * Read one window of turns from an export.
+     * @param ref - a reference this source owns; `ref.id` is a root-relative path.
+     * @param window - which turns to return.
+     * @param signal - cancellation from the caller.
+     * @returns the requested turns and their position in the conversation.
+     */
+    read(ref: ReferenceRef, window: ReferenceWindow, signal?: AbortSignal): Promise<ReferenceSnapshot>;
+    /**
+     * Resolve a root-relative id to a real path inside a configured root.
+     *
+     * The check runs against the resolved real path, so neither `..` segments
+     * nor a symlink pointing outside a root can reach a file the deployment did
+     * not offer.
+     */
+    private locate;
+    private walk;
+    private summarize;
+}
+/**
+ * Register the file reference source.
+ * @param ctx - the mounting context.
+ * @param config - validated deployment settings.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+/**
+ * Validate one export document.
+ *
+ * A file is an untrusted durable boundary — hand-written, produced by an
+ * exporter this package does not control, possibly written by an older
+ * version — so its shape is checked rather than assumed.
+ * @param raw - the file's UTF-8 contents.
+ * @param path - the path, for the diagnostic.
+ * @returns the validated document.
+ */
+export declare function parseExport(raw: string, path: string): ExportDocument;
+export {};

package/lib/sources/file.js

@@ -0,0 +1,236 @@
+/**
+ * Reference source over exported conversations stored on disk.
+ *
+ * Every chat product can export a conversation, and an exported file is the
+ * one form of outside material that needs no browser, no credentials, and no
+ * network — which also makes it the source that end-to-end tests can drive.
+ *
+ * @module dsh-reference-anything/file
+ */
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { ReferenceAnythingError } from "../errors.js";
+import { sliceTurns } from "../window.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'reference-file';
+/** The registry this source registers into. */
+export const inject = ['references'];
+/** Registry id, and the `source` half of every reference this source owns. */
+export const FILE_SOURCE_ID = 'file';
+/** Directory depth walked below each root. */
+const MAX_DEPTH = 4;
+/** Runtime schema for {@link Config}. */
+export const Config = z.object({
+    roots: z.array(z.string()).default([]),
+    extensions: z.array(z.string()).default(['.json']),
+});
+/** Reads exported conversations out of a fixed set of directories. */
+export class FileReferenceSource {
+    roots;
+    extensions;
+    id = FILE_SOURCE_ID;
+    /**
+     * @param roots - absolute or process-relative directories to search.
+     * @param extensions - file extensions treated as exports.
+     */
+    constructor(roots, extensions) {
+        this.roots = roots;
+        this.extensions = extensions;
+    }
+    /** @returns whether at least one configured root is a readable directory. */
+    async available() {
+        const checks = await Promise.all(this.roots.map(async (root) => {
+            try {
+                return (await stat(root)).isDirectory();
+            }
+            catch {
+                // A root that does not exist yet is an ordinary state (the user has
+                // not exported anything), not a misconfiguration to fail on.
+                return false;
+            }
+        }));
+        return checks.includes(true);
+    }
+    /**
+     * List exports whose label, id, or filename contains `query`.
+     * @param query - case-insensitive substring; empty matches everything.
+     * @param limit - maximum items to return.
+     * @param signal - cancellation from the caller.
+     * @returns matching exports, at most `limit`.
+     */
+    async list(query, limit, signal) {
+        const needle = query.toLocaleLowerCase();
+        const found = [];
+        for (const root of this.roots) {
+            for (const path of await this.walk(root, root, 0, signal)) {
+                if (found.length >= limit)
+                    return found;
+                const summary = await this.summarize(root, path);
+                if (summary === undefined)
+                    continue;
+                const haystack = `${summary.label} ${summary.ref.id}`.toLocaleLowerCase();
+                if (needle !== '' && !haystack.includes(needle))
+                    continue;
+                found.push(summary);
+            }
+        }
+        return found.slice(0, limit);
+    }
+    /**
+     * Read one window of turns from an export.
+     * @param ref - a reference this source owns; `ref.id` is a root-relative path.
+     * @param window - which turns to return.
+     * @param signal - cancellation from the caller.
+     * @returns the requested turns and their position in the conversation.
+     */
+    async read(ref, window, signal) {
+        signal?.throwIfAborted();
+        const path = await this.locate(ref.id);
+        const document = parseExport(await readFile(path, 'utf8'), path);
+        const slice = sliceTurns(document.messages, window);
+        return {
+            ref,
+            label: labelOf(document, ref.id),
+            ...document.origin === undefined ? {} : { origin: document.origin },
+            ...document.updatedAt === undefined ? {} : { updatedAt: document.updatedAt },
+            body: slice,
+            // The whole file is read every time, so nothing is beyond this source's reach.
+            partial: false,
+            capturedAt: Date.now(),
+        };
+    }
+    /**
+     * Resolve a root-relative id to a real path inside a configured root.
+     *
+     * The check runs against the resolved real path, so neither `..` segments
+     * nor a symlink pointing outside a root can reach a file the deployment did
+     * not offer.
+     */
+    async locate(id) {
+        for (const root of this.roots) {
+            const candidate = resolve(root, id);
+            let real;
+            let realRoot;
+            try {
+                real = await realpath(candidate);
+                realRoot = await realpath(root);
+            }
+            catch {
+                continue;
+            }
+            if (real !== realRoot && !real.startsWith(realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`)) {
+                throw new ReferenceAnythingError(`exported conversation ${JSON.stringify(id)} resolves outside its configured root`, 'REFERENCE_NOT_FOUND');
+            }
+            return real;
+        }
+        throw new ReferenceAnythingError(`no exported conversation named ${JSON.stringify(id)} exists under the configured roots`, 'REFERENCE_NOT_FOUND');
+    }
+    async walk(root, dir, depth, signal) {
+        signal?.throwIfAborted();
+        if (depth > MAX_DEPTH)
+            return [];
+        // An unreadable directory is one the user cannot reference from anyway;
+        // the other roots still list.
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        const paths = [];
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                paths.push(...await this.walk(root, path, depth + 1, signal));
+            }
+            else if (this.extensions.includes(extname(entry.name))) {
+                paths.push(path);
+            }
+        }
+        return paths;
+    }
+    async summarize(root, path) {
+        const id = relative(root, path);
+        let document;
+        try {
+            document = parseExport(await readFile(path, 'utf8'), path);
+        }
+        catch {
+            // Discovery skips a malformed file so one bad export does not hide the
+            // rest; naming it by reference still fails loudly through read().
+            return undefined;
+        }
+        return {
+            ref: { source: FILE_SOURCE_ID, id },
+            label: labelOf(document, id),
+            origin: path,
+            ...document.updatedAt === undefined ? {} : { updatedAt: document.updatedAt },
+        };
+    }
+}
+/**
+ * Register the file reference source.
+ * @param ctx - the mounting context.
+ * @param config - validated deployment settings.
+ */
+export function apply(ctx, config = {}) {
+    const roots = config.roots ?? [];
+    const extensions = config.extensions ?? ['.json'];
+    if (roots.length === 0) {
+        throw new ReferenceAnythingError('reference-file needs at least one directory in "roots"; mounting it with none can never resolve a reference', 'REFERENCE_INVALID_CONFIG');
+    }
+    const source = new FileReferenceSource(roots, extensions);
+    ctx.effect(() => ctx.references.registerSource(source), 'reference-file.registerSource()');
+}
+/**
+ * Validate one export document.
+ *
+ * A file is an untrusted durable boundary — hand-written, produced by an
+ * exporter this package does not control, possibly written by an older
+ * version — so its shape is checked rather than assumed.
+ * @param raw - the file's UTF-8 contents.
+ * @param path - the path, for the diagnostic.
+ * @returns the validated document.
+ */
+export function parseExport(raw, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw invalid(path, 'is not valid JSON', error);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw invalid(path, 'is not a JSON object');
+    }
+    const record = parsed;
+    const { label, origin, updatedAt, messages } = record;
+    if (!Array.isArray(messages))
+        throw invalid(path, 'has no "messages" array');
+    const items = messages.map((entry, index) => {
+        if (typeof entry !== 'object' || entry === null)
+            throw invalid(path, `message ${index} is not an object`);
+        const { role, text } = entry;
+        if (role !== 'user' && role !== 'assistant') {
+            throw invalid(path, `message ${index} has role ${JSON.stringify(role)}, expected "user" or "assistant"`);
+        }
+        if (typeof text !== 'string')
+            throw invalid(path, `message ${index} has no string "text"`);
+        return { role, text };
+    });
+    if (label !== undefined && typeof label !== 'string')
+        throw invalid(path, 'has a non-string "label"');
+    if (origin !== undefined && typeof origin !== 'string')
+        throw invalid(path, 'has a non-string "origin"');
+    if (updatedAt !== undefined && typeof updatedAt !== 'number')
+        throw invalid(path, 'has a non-numeric "updatedAt"');
+    return {
+        ...label === undefined ? {} : { label },
+        ...origin === undefined ? {} : { origin },
+        ...updatedAt === undefined ? {} : { updatedAt },
+        messages: items,
+    };
+}
+function labelOf(document, id) {
+    const label = document.label?.trim() ?? '';
+    return label === '' ? id : label;
+}
+function invalid(path, detail, cause) {
+    return new ReferenceAnythingError(`exported conversation ${JSON.stringify(path)} ${detail}`, 'REFERENCE_READ_FAILED', cause === undefined ? undefined : { cause });
+}

package/lib/sources/web-chat/index.d.ts

@@ -0,0 +1,114 @@
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ConversationAttachment, ReferenceSnapshot, ReferenceSource, ReferenceSummary, ReferenceWindow } from '../../types.ts';
+import type { ChatProvider, SettingsRecord } from '../../store/spec.ts';
+import { ConversationStore, type MatchedVia } from '../../store/store.ts';
+import { ConversationSyncManager } from '../../sync/index.ts';
+import { type OpenCliDiscovery } from '../../opencli.ts';
+import { parseProviderQuery } from '../../search.ts';
+export { parseProviderQuery };
+export declare const name = "reference-web-chat";
+export declare const inject: string[];
+export interface Config {
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+export declare const Config: z<Config>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        referenceChatHistory: WebChatHistoryService;
+    }
+}
+/** The stored facts about one mirrored conversation, shared by both list surfaces. */
+export interface ConversationRow {
+    uriId: string;
+    provider: ChatProvider;
+    title: string;
+    url: string;
+    updatedAt: string;
+    turnCount: number;
+    partial: boolean;
+    syncedAt: string;
+}
+/** One ranked hit from the mention/search surface. */
+export interface ConversationSearchResult extends ConversationRow {
+    /** How this row was found, so the mention menu can say why it matched. */
+    matchedVia: MatchedVia;
+    /** Excerpt around a body hit. UI-only — never part of what the model reads. */
+    snippet?: string;
+}
+/** One row in the management list — unranked, but carrying whether the provider still lists it. */
+export interface ManagedConversation extends ConversationRow {
+    remoteMissing: boolean;
+}
+export type { ProviderSyncState } from '../../store/store.ts';
+export default class WebChatHistoryService extends Service implements ReferenceSource {
+    private readonly config;
+    static inject: string[];
+    static Config: z<Config>;
+    readonly id = "web-chat";
+    private storeValue?;
+    private syncValue?;
+    private autoSyncInterval?;
+    private autoSyncCatchUp?;
+    private readonly liveAttachments;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    get store(): ConversationStore;
+    get sync(): ConversationSyncManager;
+    available(): Promise<boolean>;
+    list(query: string, limit: number): Promise<ReferenceSummary[]>;
+    read(ref: {
+        source: string;
+        id: string;
+    }, window: ReferenceWindow, signal?: AbortSignal): Promise<ReferenceSnapshot>;
+    /** Resolve an attachment locator captured by a recent metadata-only read. Never persisted. */
+    liveAttachment(conversationKey: string, attachmentId: string): (ConversationAttachment & {
+        locator?: string;
+    }) | undefined;
+    private readRemote;
+    search(query: string, provider: ChatProvider | undefined, limit: number, signal?: AbortSignal): Promise<ConversationSearchResult[]>;
+    stats(): import("../../store/store.ts").ProviderStats[];
+    storageStats(): import("../../store/store.ts").StorageStats;
+    /** Paginated browse for the management list — unlike {@link search}, includes `remoteMissing` rows. */
+    browse(query: string, provider: ChatProvider | undefined, limit: number, offset: number): {
+        items: ManagedConversation[];
+        total: number;
+    };
+    /** Permanently delete a synced conversation; refused while a sync could resurrect it mid-delete. */
+    remove(uriId: string): Promise<boolean>;
+    removeProvider(provider: ChatProvider): Promise<number>;
+    removeOlderThan(days: number): Promise<number>;
+    removeRemoteMissing(): Promise<number>;
+    removeOldAccounts(): Promise<number>;
+    /** Durable per-provider sync status, independent of any single in-flight job. */
+    syncStates(): import("../../store/store.ts").ProviderSyncState[];
+    getSettings(): SettingsRecord;
+    restartDaemon(signal?: AbortSignal): Promise<boolean>;
+    discoverOpenCli(signal?: AbortSignal): Promise<OpenCliDiscovery>;
+    installOpenCli(signal?: AbortSignal): Promise<OpenCliDiscovery>;
+    updateSettings(value: unknown): Promise<SettingsRecord>;
+    health(signal?: AbortSignal): Promise<import("../../opencli.ts").OpenCliHealth>;
+    profiles(signal?: AbortSignal): Promise<import("../../opencli.ts").BrowserProfile[]>;
+    private runner;
+    installAdapter(signal?: AbortSignal): Promise<boolean>;
+    /**
+     * (Re)arm the background sync timer from the current settings.
+     *
+     * Clears its own timers rather than swapping a `ctx.effect` disposer:
+     * disposing is asynchronous, so re-arming through it left a window — one
+     * that a couple of quick settings saves is enough to hit — where two
+     * intervals were live at once.
+     */
+    private armAutoSync;
+    /**
+     * How long to wait before a catch-up pass, or undefined when the last one
+     * is recent enough that the regular interval will do.
+     *
+     * A plain interval only ever fires a full period after arming, so enabling
+     * background sync — or restarting dsh after a day off — used to mean the
+     * mirror stayed stale for up to a day before anything happened.
+     */
+    private catchUpDelay;
+    private clearAutoSync;
+}