@toddzheng024/dscode-bundle 0.7.12 → 0.7.14

package/vendor/tui/lib/session-directory.mjs

@@ -0,0 +1,329 @@
+/** Lightweight session-directory projection for the /resume picker. */
+import { basename, dirname, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session';
+import { t } from './i18n.mjs';
+/** Case-insensitive filesystems (Windows, macOS) compare paths by lowercased form. */
+const CASE_INSENSITIVE_FS = process.platform === 'win32' || process.platform === 'darwin';
+/** True only for delegated subagents; ordinary forks also carry lineage. */
+export function isSubagentSession(header) {
+    return header.origin === 'subagent';
+}
+function comparablePath(value) {
+    const resolved = resolve(value);
+    // Codex's paths_match_after_normalization pattern: canonicalize through the
+    // filesystem when the path exists (resolving symlinks, subst drives, and
+    // junctions that plain `resolve` keeps distinct), falling back to lexical
+    // resolution when the directory no longer does.
+    const fold = (path) => CASE_INSENSITIVE_FS ? path.toLowerCase() : path;
+    try {
+        return fold(realpathSync(resolved));
+    }
+    catch {
+        return fold(resolved);
+    }
+}
+/** Platform-consistent path equality for session cwd comparisons. */
+function samePath(left, right) {
+    if (left === undefined)
+        return false;
+    return comparablePath(left) === comparablePath(right);
+}
+/**
+ * Unique header match by exact id or unique id prefix (root and subagent
+ * headers alike); the caller applies any lineage gate.
+ * @param headers - the persisted headers.
+ * @param wanted - the id or id prefix.
+ * @returns the uniquely matched header.
+ * @throws when nothing matches or the prefix is ambiguous.
+ */
+export function matchSessionId(headers, wanted) {
+    const exact = headers.filter(header => header.id === wanted);
+    const matches = exact.length > 0 ? exact : headers.filter(header => header.id.startsWith(wanted));
+    if (matches.length === 0)
+        throw new Error(`no persisted session matches "${wanted}"`);
+    if (matches.length > 1) {
+        throw new Error(`session prefix "${wanted}" is ambiguous (${matches.length} matches): use more of the id`);
+    }
+    return matches[0];
+}
+/** The newest persisted ROOT session pinned to this cwd, or undefined. */
+export function newestRootForCwd(headers, cwd) {
+    const local = headers
+        .filter(header => !isSubagentSession(header) && samePath(header.cwd, cwd))
+        .sort((left, right) => right.createdAt - left.createdAt);
+    return local[0];
+}
+/**
+ * Filter/sort header-only records. No session log is loaded here. Sorting is
+ * by LAST ACTIVITY (`updated` — artifact mtime when the caller resolved one,
+ * else createdAt), matching the codex resume picker's default UpdatedAt
+ * ordering: a session you kept talking in outranks one created later but idle.
+ * @param records - the header-only records.
+ * @param options - filter/sort options.
+ * @param updated - per-session last-activity timestamps, when resolved.
+ */
+export function projectSessionRows(records, options, updated) {
+    const needle = options.query.trim().toLowerCase();
+    return records
+        .filter(record => options.sessions === 'all' || !isSubagentSession(record.header))
+        .filter(record => options.cwd === 'all' || samePath(record.header.cwd, options.currentCwd))
+        .map(record => {
+        const cwd = record.header.cwd ?? '';
+        const subagent = isSubagentSession(record.header);
+        const activity = updated?.get(record.header.id);
+        return {
+            id: record.header.id,
+            createdAt: record.header.createdAt,
+            updatedAt: activity === undefined || !Number.isFinite(activity) || activity < record.header.createdAt
+                ? record.header.createdAt
+                : activity,
+            cwd,
+            workspace: cwd === '' ? '(no workspace)' : basename(cwd),
+            parent: record.header.parentSession,
+            subagent,
+            resumable: !subagent,
+            live: record.live,
+            persisted: record.persisted,
+            preset: record.header.agentPreset ?? 'standard',
+        };
+    })
+        .filter(row => needle === '' || `${row.id} ${row.cwd} ${row.workspace} ${row.preset}`.toLowerCase().includes(needle))
+        .sort((left, right) => options.sort === 'newest'
+        ? right.updatedAt - left.updatedAt || right.createdAt - left.createdAt
+        : left.updatedAt - right.updatedAt || left.createdAt - right.createdAt);
+}
+/** Merge page-local title observations without disturbing directory order. */
+export function mergeSessionTitles(rows, observations) {
+    const titles = new Map();
+    for (const observation of observations) {
+        if (observation.status !== 'fulfilled')
+            continue;
+        const title = observation.value?.title?.title;
+        if (title !== undefined && title.trim() !== '')
+            titles.set(observation.sessionId, title);
+    }
+    return rows.map(row => titles.has(row.id) ? { ...row, title: titles.get(row.id) } : row);
+}
+/**
+ * Encode a session id the way the JSONL backend does for its on-disk layout
+ * (`encodeSegment`: safe units literal, everything else `~XXXX`). Used to
+ * validate and derive session directories — a local copy of the pure upstream
+ * contract, kept in sync with `session-persistence-jsonl/src/format.ts`.
+ */
+export function encodeSessionSegment(raw) {
+    if (raw.length === 0)
+        throw new Error('cannot encode an empty path segment');
+    if (raw === '.')
+        return '~002E';
+    if (raw === '..')
+        return '~002E~002E';
+    let out = '';
+    for (let i = 0; i < raw.length; i += 1) {
+        const code = raw.charCodeAt(i);
+        const ch = String.fromCharCode(code);
+        if (ch !== '~' && /^[A-Za-z0-9._-]$/u.test(ch)) {
+            out += ch;
+        }
+        else {
+            out += `~${code.toString(16).toUpperCase().padStart(4, '0')}`;
+        }
+    }
+    return out;
+}
+/**
+ * Encode a project cwd the way the JSONL backend groups sessions on disk
+ * (`projectKey`: separators collapse to one `-`, everything else mirrors
+ * `encodeSegment`, bounded to 251 chars). A local copy of the pure upstream
+ * contract, kept in sync with `session-persistence-jsonl/src/format.ts`.
+ */
+export function encodeProjectKey(cwd) {
+    if (cwd.length === 0)
+        throw new Error('cannot encode an empty project path');
+    let readable = '';
+    let separatorRun = false;
+    for (let i = 0; i < cwd.length; i += 1) {
+        const code = cwd.charCodeAt(i);
+        const ch = String.fromCharCode(code);
+        if (ch === '/' || ch === '\\' || ch === ':') {
+            if (!separatorRun)
+                readable += '-';
+            separatorRun = true;
+        }
+        else if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+            readable += ch;
+            separatorRun = false;
+        }
+        else {
+            readable += `~${code.toString(16).toUpperCase().padStart(4, '0')}`;
+            separatorRun = false;
+        }
+    }
+    const slug = readable.replace(/^-+/, '') || 'root';
+    return `--${slug.slice(0, 251)}--`;
+}
+/** The project-level directory name the JSONL backend uses for a missing cwd. */
+const NO_CWD_DIRECTORY = '_no-cwd';
+/**
+ * Derive one session's artifact directory under the JSONL backend root,
+ * mirroring the upstream `<root>/<projectKey(cwd)>/<encodeSegment(id)>/`
+ * layout (0.1.5 `sessionDir`/`projectDir`).
+ * @param root - the JSONL backend's configured session root.
+ * @param cwd - the session's pinned working directory, when the header has one.
+ * @param id - the session id.
+ * @returns the absolute session directory path.
+ */
+export function sessionDirectoryFor(root, cwd, id) {
+    const project = cwd === undefined || cwd === '' ? NO_CWD_DIRECTORY : encodeProjectKey(cwd);
+    return resolve(root, project, encodeSessionSegment(id));
+}
+/**
+ * The canonical session-log artifact filenames the JSONL backend may create:
+ * format v0 writes the bare `session.jsonl` name; v1+ write
+ * `session.vN.jsonl`, each generation optionally zstd-compressed. Multiple
+ * immutable generations may coexist in one session directory (0.1.5). The
+ * range follows the installed session package's `SESSION_FORMAT_VERSION`, so
+ * a future generation joins the enumeration with the dependency bump.
+ */
+export function sessionArtifactNames() {
+    const names = ['session.jsonl', 'session.jsonl.zstd'];
+    for (let version = 1; version <= SESSION_FORMAT_VERSION; version += 1) {
+        names.push(`session.v${version}.jsonl`, `session.v${version}.jsonl.zstd`);
+    }
+    return names;
+}
+/** Canonical generation-log filenames as a lookup set (bare v0 or `vN`-suffixed, ± zstd). */
+const SESSION_ARTIFACT_NAME_SET = new Set(sessionArtifactNames());
+/** True for one canonical session-log artifact filename the backend may own. */
+export function isSessionArtifactName(name) {
+    return SESSION_ARTIFACT_NAME_SET.has(name);
+}
+/**
+ * Guard a derived session directory before deletion (codex's scoped-path
+ * check, adapted to the JSONL layout): the directory's base name must be
+ * exactly `encodeSegment(id)` beneath its project grouping.
+ * @param dir - the derived session artifact directory.
+ * @param id - the session id the directory claims to belong to.
+ * @returns the guarded directory, or undefined when the layout is unexpected.
+ */
+export function sessionArtifactDirectory(dir, id) {
+    if (basename(dir) !== encodeSessionSegment(id))
+        return undefined;
+    if (basename(dirname(dir)) === NO_CWD_DIRECTORY)
+        return dir;
+    return /^--.*--$|^~/.test(basename(dirname(dir))) ? dir : undefined;
+}
+/**
+ * The JSONL backend's configured session root, when the mounted backend
+ * exposes one. The upstream service contract dropped `locate()` in 0.1.5
+ * (artifact paths are backend-private; only refusal diagnostics carry them),
+ * so the TUI derives artifact paths from the backend's public plugin config.
+ * Backends without a JSONL-style config (or a foreign shape) yield undefined
+ * and callers degrade: mtime sorting falls back to createdAt and /delete
+ * refuses, exactly as before.
+ */
+export function jsonlSessionRoot(persistence) {
+    const root = persistence?.config?.root;
+    return typeof root === 'string' && root !== '' ? root : undefined;
+}
+/**
+ * Collect one session's deletion subtree: the id plus every record whose
+ * parent chain leads to it (codex deletes subagent threads with their root).
+ * @param records - the full directory listing.
+ * @param id - the root session id to delete.
+ * @returns the ids to delete, root first.
+ */
+export function collectDeletionSubtree(records, id) {
+    const parentOf = new Map();
+    for (const record of records)
+        parentOf.set(record.header.id, record.header.parentSession);
+    const doomed = new Set([id]);
+    // Iterate to a fixed point: children may be listed before their parents.
+    for (let pass = 0; pass < 2; pass += 1) {
+        for (const candidate of parentOf.keys()) {
+            if (doomed.has(candidate))
+                continue;
+            let ancestor = parentOf.get(candidate);
+            let depth = 0;
+            while (ancestor !== undefined && depth < 64) {
+                if (doomed.has(ancestor)) {
+                    doomed.add(candidate);
+                    break;
+                }
+                ancestor = parentOf.get(ancestor);
+                depth += 1;
+            }
+        }
+    }
+    return [...doomed];
+}
+/**
+ * Plan one session-subtree deletion with NO filesystem side effects: collect
+ * the doomed lineage, refuse when the root or ANY member is live (a live
+ * child would outlive its deleted parent) or missing from the listing, and
+ * order the result children-first so the executor can never leave a deleted
+ * parent behind surviving children. Artifact-location guards stay at the
+ * call site; this is the pure preflight they complete.
+ * @param records - the full directory listing.
+ * @param id - the root session id to delete.
+ * @returns the ordered plan, or a user-facing refusal reason.
+ */
+export function planSessionDeletion(records, id) {
+    const target = records.find(record => record.header.id === id);
+    if (target === undefined)
+        return { ok: false, reason: `no persisted session matches "${id}"` };
+    if (target.live)
+        return { ok: false, reason: 'cannot delete a live session — it is open in this or another process' };
+    const doomed = collectDeletionSubtree(records, id);
+    const byId = new Map(records.map(record => [record.header.id, record]));
+    const parentOf = new Map();
+    for (const record of records)
+        parentOf.set(record.header.id, record.header.parentSession);
+    const nodes = [];
+    for (const candidate of doomed) {
+        const record = byId.get(candidate);
+        if (record === undefined)
+            return { ok: false, reason: `no persisted session matches "${candidate}"` };
+        if (record.live) {
+            return {
+                ok: false,
+                reason: `cannot delete: child session ${candidate.slice(-12)} is live — close it (and any process using it) first`,
+            };
+        }
+        let depth = 0;
+        let ancestor = parentOf.get(candidate);
+        while (ancestor !== undefined && depth < 64) {
+            depth += 1;
+            ancestor = parentOf.get(ancestor);
+        }
+        nodes.push({ id: candidate, depth });
+    }
+    // Deepest first: a mid-deletion failure then leaves the shallowest lineage
+    // intact, never a deleted parent with surviving children.
+    nodes.sort((left, right) => right.depth - left.depth);
+    return { ok: true, nodes };
+}
+/**
+ * Codex-style relative time for session rows ("now", "5m ago", "3h ago",
+ * "2d ago"; older than a week falls back to the local date).
+ * @param timestamp - epoch milliseconds of the last activity.
+ * @param now - the pinned reference clock (one value per list render).
+ */
+export function formatRelativeTime(timestamp, now) {
+    const seconds = Math.round((now - timestamp) / 1000);
+    if (seconds < 60)
+        return t('time.justNow');
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return t('time.minutesAgo', { n: minutes });
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return t('time.hoursAgo', { n: hours });
+    const days = Math.round(hours / 24);
+    if (days < 7)
+        return t('time.daysAgo', { n: days });
+    const date = new Date(timestamp);
+    const month = `${date.getMonth() + 1}`.padStart(2, '0');
+    const day = `${date.getDate()}`.padStart(2, '0');
+    return `${date.getFullYear()}-${month}-${day}`;
+}

package/vendor/tui/lib/session-query.mjs

@@ -0,0 +1,184 @@
+/**
+ * Skip-tolerant session-query engine for this terminal.
+ *
+ * The upstream SqliteSessionQueryEngine reconciliation observes EVERY
+ * persisted session before each search, and ONE unreadable source (for
+ * example a pre-release session artifact the frozen format codecs reject)
+ * fails the whole pass with SESSION_QUERY_PERSISTENCE_FAILED — every
+ * cross-session search dies because of a single old file nobody opened
+ * otherwise. This subclass overrides only the observation loop so an
+ * unreadable source is skipped with a warning and the rest of the corpus
+ * indexes normally; skipped sessions are retried on later reconciliations
+ * and rejoin automatically once a host that can read them is installed.
+ *
+ * Vendored surface note: `_observeStable` and its module-local helpers are
+ * private upstream; this file re-declares the observation loop against the
+ * pinned @deepseek-ai line (see package.json peers) and must be re-checked
+ * whenever that line moves. The engine class and the tool boundary also
+ * share ONE physical parent-package instance through this bundle, which
+ * restores instanceof-based typed error messages on the search path.
+ */
+import { createHash } from 'node:crypto';
+import SqliteSessionQueryEngine from '@deepseek-ai/dsh-session-query-sqlite';
+import { assertSessionHeadersCompatible, buildSessionEventSearchDocuments, readColdSessionLog, SessionQueryError, } from '@deepseek-ai/dsh-session-query';
+const STABLE_OBSERVATION_ATTEMPTS = 2;
+function assertNotAborted(signal) {
+    if (signal?.aborted) {
+        throw new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED');
+    }
+}
+function isAbort(error) {
+    return error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED';
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'unknown error';
+}
+function observeSession(header, inheritedEventCount, events) {
+    const detachedHeader = structuredClone(header);
+    const detachedEvents = events.map(event => structuredClone(event));
+    return {
+        header: detachedHeader,
+        inheritedEventCount,
+        documents: buildSessionEventSearchDocuments(detachedHeader.id, detachedEvents),
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify({ header: detachedHeader, inheritedEventCount, events: detachedEvents }))
+            .digest('base64url'),
+    };
+}
+function sameHeader(a, b) {
+    return a.id === b.id
+        && a.createdAt === b.createdAt
+        && a.cwd === b.cwd
+        && a.parentSession === b.parentSession
+        && a.isSeeded === b.isSeeded
+        && (a.delegationDepth ?? 0) === (b.delegationDepth ?? 0)
+        && a.agentPreset === b.agentPreset;
+}
+function materializePersistenceSnapshots(snapshots) {
+    // `Array.isArray` narrows a declared array type to `any[]`, which would let
+    // every later access escape the type system. Step through `unknown` so the
+    // guard stays a runtime assertion and the element type stays declared.
+    const candidate = snapshots;
+    if (!Array.isArray(candidate))
+        throw new Error('persistence snapshots must be an array');
+    const result = new Map();
+    for (const snapshot of candidate) {
+        if (typeof snapshot.revision !== 'string') {
+            throw new Error('persistence snapshot revision must be a string');
+        }
+        const header = structuredClone(snapshot.header);
+        if (result.has(header.id)) {
+            throw new Error(`persistence listed duplicate session "${header.id}"`);
+        }
+        result.set(header.id, { header, revision: snapshot.revision });
+    }
+    return result;
+}
+function samePersistenceSnapshots(before, after) {
+    if (before.size !== after.size)
+        return false;
+    for (const [id, first] of before) {
+        const second = after.get(id);
+        if (second === undefined || first.revision !== second.revision || !sameHeader(first.header, second.header))
+            return false;
+    }
+    return true;
+}
+/**
+ * The skip-tolerant observation pass: structurally the upstream loop, with
+ * the per-source cold read wrapped so one unreadable session degrades to a
+ * warning instead of failing every search. Exported for unit tests with an
+ * injectable cold reader.
+ */
+export async function observeStableWithSkip(engine, indexed, signal, readCold = readColdSessionLog) {
+    for (let attempt = 0; attempt < STABLE_OBSERVATION_ATTEMPTS; attempt += 1) {
+        assertNotAborted(signal);
+        const persistenceBinding = engine._persistenceBinding;
+        const persistence = persistenceBinding.service;
+        const initiallyLive = new Set(engine.ctx.sessions.list().map(session => session.id));
+        let persisted = new Map();
+        if (persistence !== undefined) {
+            try {
+                const canReuseIndexed = engine._lastPersistenceIdentity === undefined
+                    || engine._lastPersistenceIdentity === persistenceBinding.identity;
+                const listOptions = signal === undefined ? undefined : { signal };
+                const before = await persistence.list(listOptions);
+                assertNotAborted(signal);
+                persisted = materializePersistenceSnapshots(before);
+                for (const entry of persisted.values()) {
+                    if (canReuseIndexed && indexed.get(entry.header.id)?.revision === entry.revision)
+                        continue;
+                    if (initiallyLive.has(entry.header.id) || engine.ctx.sessions.get(entry.header.id) !== undefined)
+                        continue;
+                    assertNotAborted(signal);
+                    // The skip: a session whose cold log fails to migrate or decode
+                    // stays OUT of the index with one warning; the remaining corpus
+                    // indexes normally. `loaded` stays undefined exactly like a
+                    // not-yet-read entry, so the stable-snapshot comparison and the
+                    // live-preferred merge below are unaffected.
+                    try {
+                        const loaded = await readCold(persistence, entry.header.id, signal);
+                        assertNotAborted(signal);
+                        assertSessionHeadersCompatible(entry.header, loaded.header);
+                        entry.loaded = observeSession(loaded.header, loaded.inheritedEventCount, loaded.events);
+                    }
+                    catch (error) {
+                        if (isAbort(error) || signal?.aborted)
+                            throw error;
+                        if (engine._persistenceBinding !== persistenceBinding)
+                            break;
+                        entry.unreadable = errorMessage(error);
+                        engine.ctx.logger?.warn('session-search skipped unreadable session %s: %s', entry.header.id, entry.unreadable);
+                    }
+                }
+                assertNotAborted(signal);
+                const afterSnapshots = await persistence.list(listOptions);
+                assertNotAborted(signal);
+                const after = materializePersistenceSnapshots(afterSnapshots);
+                if (!samePersistenceSnapshots(persisted, after))
+                    continue;
+                if (engine._persistenceBinding !== persistenceBinding)
+                    continue;
+            }
+            catch (error) {
+                if (isAbort(error) || signal?.aborted) {
+                    throw new SessionQueryError('session-search aborted', 'SESSION_QUERY_ABORTED', { cause: error });
+                }
+                if (engine._persistenceBinding !== persistenceBinding)
+                    continue;
+                if (error instanceof SessionQueryError)
+                    throw error;
+                throw new SessionQueryError(`session-search persistence observation failed: ${errorMessage(error)}`, 'SESSION_QUERY_PERSISTENCE_FAILED', { cause: error });
+            }
+        }
+        const live = new Map();
+        for (const session of engine.ctx.sessions.list()) {
+            const observed = observeSession(session.header, session.inheritedEventCount, session.snapshotEvents());
+            const durable = persisted.get(session.id);
+            if (durable !== undefined && durable.loaded === undefined) {
+                // A live owner always wins over a skipped durable copy.
+                live.set(session.id, observed);
+                continue;
+            }
+            if (durable !== undefined)
+                assertSessionHeadersCompatible(observed.header, durable.header);
+            live.set(session.id, observed);
+        }
+        const sameLive = initiallyLive.size === live.size && [...initiallyLive].every(id => live.has(id));
+        if (!sameLive)
+            continue;
+        return { persistenceBinding, persisted, live };
+    }
+    throw new SessionQueryError('session-search persistence observation did not stabilize after one retry', 'SESSION_QUERY_PERSISTENCE_FAILED');
+}
+// The opaque-base cast keeps the private `_observeStable` override legal in
+// TypeScript while inheriting every runtime static (inject, Config, Service
+// metadata) from the real engine class.
+const EngineBase = SqliteSessionQueryEngine;
+/** The engine this bundle mounts in place of the base `session-query-sqlite` row. */
+export class SkipTolerantSessionQueryEngine extends EngineBase {
+    async _observeStable(indexed, signal) {
+        return await observeStableWithSkip(this, indexed, signal);
+    }
+}
+export default SkipTolerantSessionQueryEngine;

package/vendor/tui/lib/session-switch.mjs

@@ -0,0 +1,51 @@
+/** Latest-wins, idle-bound queue for safe Agent session changes. */
+export class SessionSwitchQueue {
+    pending;
+    pumping = false;
+    execute;
+    failed;
+    constructor(execute, failed) {
+        this.execute = execute;
+        this.failed = failed;
+    }
+    /** Queue a request; a later request replaces any request still waiting. */
+    request(activity, value) {
+        this.pending = { activity, value };
+        const outcome = activity.status === 'running' || this.pumping ? 'queued' : 'started';
+        if (!this.pumping)
+            void this.pump();
+        return outcome;
+    }
+    /** Cancel only work that has not begun activation. */
+    cancel() {
+        if (this.pending === undefined)
+            return false;
+        this.pending = undefined;
+        return true;
+    }
+    async pump() {
+        this.pumping = true;
+        try {
+            while (this.pending !== undefined) {
+                const observed = this.pending;
+                await observed.activity.whenIdle();
+                // Another request replaced this one while the turn was converging.
+                if (this.pending !== observed)
+                    continue;
+                this.pending = undefined;
+                try {
+                    await this.execute(observed.value);
+                }
+                catch (error) {
+                    this.failed(error);
+                }
+            }
+        }
+        finally {
+            this.pumping = false;
+            // A request may land between the loop condition and finally.
+            if (this.pending !== undefined)
+                void this.pump();
+        }
+    }
+}

package/vendor/tui/lib/settings-file.mjs

@@ -0,0 +1,75 @@
+/**
+ * Serialized, crash-atomic persistence for the small user-level JSON files
+ * under the DSH home (statusline.json, theme.json). Two guarantees the bare
+ * floating `writeFile` path could not give:
+ *
+ * 1. Every save is appended to ONE chain, so rapid consecutive edits land
+ *    in submission order and the last snapshot is the one on disk (parallel
+ *    floating writes let an older snapshot finish last and win).
+ * 2. Each write goes to a sibling temp file first and is renamed into
+ *    place, so a crash mid-write can never leave a half-written JSON
+ *    document behind.
+ *
+ * The chain itself never rejects: a failed write is reported to that
+ * save's caller while later saves keep their turn.
+ *
+ * @module @deepseek-ai/dsh-code/settings-file
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * Run one file operation with a bounded retry: one initial try plus at
+ * most `retries` more. Creating or replacing a file can fail transiently
+ * with EPERM/EACCES while an antivirus scanner or search indexer holds
+ * it — the standard graceful-fs remedy, not a workaround for a
+ * persistent permission problem. A save that still fails leaves its
+ * uniquely named temp file behind, so repeated crashed saves accumulate
+ * distinct leftovers rather than corrupting a shared one.
+ */
+async function withTransientRetry(operation, retries = 5) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await operation();
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (attempt >= retries || (code !== 'EPERM' && code !== 'EACCES'))
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, 30 * (attempt + 1)));
+        }
+    }
+}
+/**
+ * Write one file atomically: create the parent directory, write to a
+ * uniquely named temp file, and rename it into place. A crash midway
+ * can never leave a half-written document behind. Unique temp names
+ * keep concurrent writers (two terminals, two chains in one process)
+ * from sharing one temp path.
+ */
+export async function writeFileAtomically(path, text) {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await withTransientRetry(() => writeFile(temp, text, 'utf8'));
+    await withTransientRetry(() => rename(temp, path));
+}
+/**
+ * Create the shared settings-write chain. One instance per process keeps
+ * every user-level JSON file mutually serialized.
+ * @returns the persistence handle.
+ */
+export function createUserSettingsPersistence() {
+    let chain = Promise.resolve();
+    return {
+        save(path, text) {
+            const write = chain.then(() => writeFileAtomically(path, text));
+            // A failed write must not break the chain for later saves.
+            chain = write.catch(() => { });
+            return write;
+        },
+        flush() {
+            return chain;
+        },
+    };
+}