@askdkc/dsh-cli 0.11.7 → 0.12.1

package/node_modules/dsh-working-activity/lib/types/invariant.js

@@ -0,0 +1,72 @@
+/**
+ * Package-owned `activity/status` snapshot invariants.
+ * @module dsh-working-activity/invariant
+ */
+/** Cordis companion plugin name. */
+export const name = 'working-activity-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+const PACKAGE_NAME = 'dsh-working-activity';
+const PHASES = new Set(['idle', 'waiting', 'thinking', 'tool', 'done']);
+/** Validate one published activity snapshot before it reaches the durable log. */
+function validateStatus(data, fail) {
+    const record = data;
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+        fail('activity/status data must be an object');
+        return;
+    }
+    if (typeof record.phase !== 'string' || !PHASES.has(record.phase)) {
+        fail(`activity/status carries unknown phase ${JSON.stringify(record.phase)}`);
+    }
+    if (typeof record.line !== 'string' || record.line.length === 0) {
+        fail('activity/status line must be a non-empty string');
+    }
+    for (const key of ['toolCount', 'turnElapsedMs', 'phaseStartedAt']) {
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            fail(`activity/status ${key} must be a non-negative finite number`);
+        }
+    }
+    for (const key of ['label', 'detail', 'phrase']) {
+        if (record[key] !== undefined && typeof record[key] !== 'string') {
+            fail(`activity/status ${key} must be a string when present`);
+        }
+    }
+}
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate the package-owned event shape and ignore unrelated events. */
+function validateEvent(event, fail) {
+    if (event.type === 'activity/status')
+        validateStatus(event.data, fail);
+}
+/**
+ * The events of one already-loaded session across those two read shapes. A host
+ * exposing neither yields an empty log instead of aborting the companion: the
+ * bootstrap scan is best-effort, while the live `internal/dispatch` half must
+ * keep validating appended snapshots.
+ */
+function loadedEvents(session) {
+    if (typeof session.snapshotEvents === 'function')
+        return session.snapshotEvents();
+    return session.events ?? [];
+}
+/** Install validation for loaded and newly appended activity snapshots. */
+const install = Object.assign((ctx, fail) => {
+    for (const session of ctx.sessions.list()) {
+        for (const event of loadedEvents(session))
+            validateEvent(event, fail);
+    }
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const event = args[1];
+        validateEvent(event, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register the working-activity invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/node_modules/dsh-working-activity/lib/types/japanese.d.ts

@@ -0,0 +1,28 @@
+/** Japanese progress copy. Tool names and user-supplied details stay verbatim. */
+export declare const THINKING: readonly string[];
+export declare const THINKING_TIERS: readonly {
+    atMs: number;
+    pool: readonly string[];
+}[];
+export declare const WAITING: readonly string[];
+export declare const NIGHT: readonly string[];
+export declare const RARE: readonly string[];
+export declare const WEEKEND: readonly string[];
+export declare const RETRY: readonly string[];
+export declare const APPROVAL: readonly string[];
+export declare const COMPACTION_START: readonly string[];
+export declare const CONTINUE: readonly string[];
+export declare const COMPACT: readonly string[];
+export declare const OVERFLOW: readonly string[];
+export declare const COMPACT_RETRY: readonly string[];
+export declare const TOOL_OPENING: readonly string[];
+export declare const FAIL: readonly string[];
+export declare const DONE: readonly string[];
+export declare const NEW_YEAR: readonly string[];
+export declare const HOLIDAYS: Readonly<Record<string, readonly string[]>>;
+export declare const MODEL_QUIPS: Readonly<Record<string, readonly string[]>>;
+export declare const ACTION_MAP: readonly {
+    test: RegExp;
+    actions: readonly string[];
+}[];
+export declare const FALLBACK_ACTIONS: readonly string[];

package/node_modules/dsh-working-activity/lib/types/japanese.js

@@ -0,0 +1,47 @@
+/** Japanese progress copy. Tool names and user-supplied details stay verbatim. */
+export const THINKING = ['考えています', '確認しています', '手順を整理しています'];
+export const THINKING_TIERS = [
+    { atMs: 300_000, pool: ['時間をかけて確認しています'] },
+    { atMs: 60_000, pool: ['引き続き調べています'] },
+    { atMs: 30_000, pool: ['もう少し確認しています'] },
+];
+export const WAITING = ['モデルの応答を待っています'];
+export const NIGHT = ['作業を続けています'];
+export const RARE = ['確認を進めています'];
+export const WEEKEND = ['作業を進めています'];
+export const RETRY = ['再試行を待っています'];
+export const APPROVAL = ['承認を待っています'];
+export const COMPACTION_START = ['会話を整理しています'];
+export const CONTINUE = ['作業を再開します'];
+export const COMPACT = ['会話を整理しました'];
+export const OVERFLOW = ['会話の整理を試みています'];
+export const COMPACT_RETRY = ['会話を整理し直しています'];
+export const TOOL_OPENING = ['ツールを使って確認します'];
+export const FAIL = ['ツールの実行に失敗しました'];
+export const DONE = ['完了しました'];
+export const NEW_YEAR = ['作業を進めています'];
+export const HOLIDAYS = {};
+export const MODEL_QUIPS = {
+    claude: ['Claude に切り替えました'],
+    gpt: ['GPT に切り替えました'],
+    grok: ['Grok に切り替えました'],
+    gemini: ['Gemini に切り替えました'],
+    deepseek: ['DeepSeek に切り替えました'],
+    haiku: ['Haiku に切り替えました'],
+    sonnet: ['Sonnet に切り替えました'],
+    opus: ['Opus に切り替えました'],
+    flash: ['Flash に切り替えました'],
+    pro: ['Pro に切り替えました'],
+    mini: ['Mini に切り替えました'],
+};
+export const ACTION_MAP = [
+    { test: /^(read|read_file|cat)$/i, actions: ['読み取り'] },
+    { test: /^(write|write_file|create_file)$/i, actions: ['書き込み'] },
+    { test: /^(edit|edit_file|str_replace|apply_patch|search_replace)$/i, actions: ['編集'] },
+    { test: /^(bash|shell|run|exec|powershell|cmd)$/i, actions: ['コマンド実行'] },
+    { test: /^(grep|rg|search|search_in_files|ffgrep)$/i, actions: ['検索'] },
+    { test: /^(find|glob|fffind)$/i, actions: ['ファイル検索'] },
+    { test: /^(subagent|agent|task)$/i, actions: ['サブエージェント実行'] },
+    { test: /^(web_search|browse|fetch)$/i, actions: ['Web 検索'] },
+];
+export const FALLBACK_ACTIONS = ['ツール実行'];

package/node_modules/dsh-working-activity/lib/types/lang.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Language resolution + copy dictionary for the working-activity plugin.
+ *
+ * The plugin follows the dsh-tui UI language without importing it: the same
+ * chain dsh-tui resolves (`DSH_TUI_LANG` env → `~/.dsh-tui/lang.json` → OS
+ * locale → zh) is read here directly, so a `/lang en|zh` switch (or the
+ * /settings language pick) hot-swaps this plugin's narration and status-line
+ * copy on the next render tick.
+ *
+ * Resolution order:
+ *   1. `setLangOverride()` — a plugin-level `lang: zh|en` config key
+ *      (cordis.yml) or an explicit test pin.
+ *   2. `DSH_TUI_LANG` env var — pinned at process start.
+ *   3. `~/.dsh-tui/lang.json` — the persisted dsh-tui choice, mtime-cached
+ *      so the per-tick status render never re-reads an unchanged file.
+ *   4. OS locale guess (`LC_ALL` / `LC_MESSAGES` / `LANG`); POSIX/C means
+ *      "no locale selected" and maps to English.
+ *   5. `zh` — the original hard-coded language.
+ *
+ * The dictionary is a flat key → per-language string map; `t(key, params)`
+ * substitutes `{{name}}` placeholders. Missing keys render the key itself so
+ * a typo is visible instead of silently blank.
+ * @module @deepseek-ai/dsh-working-activity/lang
+ */
+export type Lang = 'zh' | 'en' | 'ja';
+/** The languages shipped with the plugin, in display order. */
+export declare const LANGS: readonly ["zh", "en", "ja"];
+/** Scope a rendered status line to its own session without changing the UI language. */
+export declare function withProgressLang<T>(lang: Lang, render: () => T): T;
+/** Use the terminal locale only for the first ambiguous prompt in a session. */
+export declare function terminalProgressLang(): Lang;
+/** Detect only confident language signals in user-authored prose. */
+export declare function detectInputLanguage(input: string): Lang | undefined;
+declare const dict: {
+    readonly 'narrate-instruction': {
+        readonly zh: "[状态栏] 你有一个状态栏展示给用户。【必须】在每个步骤/子任务开始时（不只是调用工具前），在回复正文的最前面单独写一行：⏵ 你在做的具体事情（不超过20字），然后换行继续正常回复。整轮回复只写一行 ⏵，不要重复。信息为主——让人一眼知道你在干什么，风格自然、可以带点俏皮。例：⏵ 修复登录页样式、⏵ 查一下报错原因、⏵ 给补丁跑个验证。切换任务时必须更新。";
+        readonly en: "[Status line] You have a status line visible to the user. [Required] At the start of each step or subtask (not only before tool calls), write exactly one standalone line at the very beginning of your response: ⏵ a concrete description of what you are doing (20 words max), then continue with the normal response on the next line. Write only one ⏵ line per response and do not repeat it. Prioritize information so the user can understand the current work at a glance; keep the style natural and optionally playful. Examples: ⏵ Fixing the login page styles, ⏵ Investigating the error, ⏵ Running validation for the patch. Update it when the task changes.";
+    };
+    /** Plain (non-playful) phase labels. */
+    readonly 'waiting-label': {
+        readonly zh: "等待模型响应";
+        readonly en: "Waiting for model";
+        readonly ja: "モデルの応答待ち";
+    };
+    readonly 'thinking-label': {
+        readonly zh: "思考中";
+        readonly en: "Thinking";
+        readonly ja: "考えています";
+    };
+    /** Elapsed suffix: zh glues the char, en keeps a space. */
+    readonly 'line-elapsed': {
+        readonly zh: "总{{elapsed}}";
+        readonly en: "total {{elapsed}}";
+        readonly ja: "合計 {{elapsed}}";
+    };
+    /** Plain-mode completion prefix (playful pools pick their own). */
+    readonly 'done-prefix': {
+        readonly zh: "搞定 ✓";
+        readonly en: "Finished";
+        readonly ja: "完了 ✓";
+    };
+    /** Turn-completion summary. */
+    readonly 'done-summary': {
+        readonly zh: "{{tools}} · 想{{thinking}} 干{{tooling}}";
+        readonly en: "{{tools}} · thought {{thinking}} worked {{tooling}}";
+        readonly ja: "{{tools}} · 思考 {{thinking}} 作業 {{tooling}}";
+    };
+    readonly 'tool-count-one': {
+        readonly zh: "{{count}} 工具";
+        readonly en: "{{count}} tool";
+        readonly ja: "ツール {{count}} 件";
+    };
+    readonly 'tool-count-many': {
+        readonly zh: "{{count}} 工具";
+        readonly en: "{{count}} tools";
+        readonly ja: "ツール {{count}} 件";
+    };
+    /** Consecutive-tool streak badge (replaces the old flame emoji). */
+    readonly 'tool-streak': {
+        readonly zh: "工具x{{count}}";
+        readonly en: "tool x{{count}}";
+        readonly ja: "ツール連続 {{count}} 件";
+    };
+    /** Approval badge while a tool is parked on the user's decision. */
+    readonly 'tool-waiting-approval': {
+        readonly zh: "在等你批准";
+        readonly en: "awaiting your approval";
+        readonly ja: "承認待ち";
+    };
+    /** Subagent count in the done summary. */
+    readonly 'subagent-count': {
+        readonly zh: "子代理 {{count}} 个";
+        readonly en: "{{count}} subagents";
+        readonly ja: "サブエージェント {{count}} 件";
+    };
+    /** Work-reminder copy after `workRemindAt` turn-hours. */
+    readonly 'work-remind': {
+        readonly zh: "已连续工作 {{hours}} 小时，歇会儿？";
+        readonly en: "Worked {{hours}}h straight — take a break?";
+        readonly ja: "{{hours}} 時間続けて作業しています。少し休みますか？";
+    };
+};
+export type I18nKey = keyof typeof dict;
+export type I18nParams = Record<string, string | number>;
+/** Force (or release) the active language; `auto` re-enables the chain. */
+export declare function setLangOverride(lang: Lang | 'auto'): void;
+/** The currently active language. */
+export declare function langNow(): Lang;
+/** Translate a dictionary key, substituting `{{name}}` placeholders. */
+export declare function t(key: I18nKey, params?: I18nParams): string;
+/** Is a value a valid shipped language code? */
+export declare function isLang(value: unknown): value is Lang;
+/**
+ * Read the persisted dsh-tui language choice.
+ *
+ * The probe is cached twice over: the parsed value is reused while the file's
+ * mtime is unchanged, and even the `statSync` itself is skipped for
+ * {@link LANG_FILE_PROBE_TTL_MS}. Both halves matter — one render translates
+ * several keys, and a host that never wrote the file would otherwise pay a
+ * FAILED stat on every one of them (issue #14).
+ *
+ * @param nowMs - Instant to measure the probe cache against.
+ * @returns the persisted language, or `undefined` when the file is absent or
+ * holds no valid `{ lang }` value.
+ */
+export declare function readLangFile(nowMs?: number): Lang | undefined;
+/**
+ * Drop the file cache so the next read probes the filesystem immediately.
+ * Called whenever the language is pinned explicitly, so a switch is never
+ * delayed by the probe TTL.
+ */
+export declare function invalidateLangCache(): void;
+/**
+ * Guess the language from the OS locale (`LC_ALL`, `LC_MESSAGES`, `LANG`),
+ * defaulting to `zh`. POSIX/C means "no locale selected" and conventionally
+ * maps to English (what CI runners report). An absent locale variable
+ * (typical on Windows) defaults to `zh`.
+ */
+export declare function detectLocaleLang(): Lang;
+export {};

package/node_modules/dsh-working-activity/lib/types/lang.js

@@ -0,0 +1,209 @@
+/**
+ * Language resolution + copy dictionary for the working-activity plugin.
+ *
+ * The plugin follows the dsh-tui UI language without importing it: the same
+ * chain dsh-tui resolves (`DSH_TUI_LANG` env → `~/.dsh-tui/lang.json` → OS
+ * locale → zh) is read here directly, so a `/lang en|zh` switch (or the
+ * /settings language pick) hot-swaps this plugin's narration and status-line
+ * copy on the next render tick.
+ *
+ * Resolution order:
+ *   1. `setLangOverride()` — a plugin-level `lang: zh|en` config key
+ *      (cordis.yml) or an explicit test pin.
+ *   2. `DSH_TUI_LANG` env var — pinned at process start.
+ *   3. `~/.dsh-tui/lang.json` — the persisted dsh-tui choice, mtime-cached
+ *      so the per-tick status render never re-reads an unchanged file.
+ *   4. OS locale guess (`LC_ALL` / `LC_MESSAGES` / `LANG`); POSIX/C means
+ *      "no locale selected" and maps to English.
+ *   5. `zh` — the original hard-coded language.
+ *
+ * The dictionary is a flat key → per-language string map; `t(key, params)`
+ * substitutes `{{name}}` placeholders. Missing keys render the key itself so
+ * a typo is visible instead of silently blank.
+ * @module @deepseek-ai/dsh-working-activity/lang
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The languages shipped with the plugin, in display order. */
+export const LANGS = ['zh', 'en', 'ja'];
+const progressLanguage = new AsyncLocalStorage();
+/** Scope a rendered status line to its own session without changing the UI language. */
+export function withProgressLang(lang, render) {
+    return progressLanguage.run(lang, render);
+}
+/** Use the terminal locale only for the first ambiguous prompt in a session. */
+export function terminalProgressLang() {
+    const locale = (process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '').toLowerCase();
+    if (locale.startsWith('ja'))
+        return 'ja';
+    if (locale.startsWith('zh'))
+        return 'zh';
+    return 'en';
+}
+/** Detect only confident language signals in user-authored prose. */
+export function detectInputLanguage(input) {
+    const prose = input.normalize('NFKC')
+        .replace(/```[\s\S]*?(?:```|$)/g, ' ')
+        .replace(/`[^`]*`/g, ' ')
+        .replace(/^\s*>.*$/gm, ' ')
+        .replace(/\b(?:https?|file):\/\/\S+/gi, ' ')
+        .replace(/(?:^|\s)(?:[A-Za-z]:\\|\/|\.\.?\/)[^\s]+/g, ' ');
+    if (/[\p{Script=Hiragana}\p{Script=Katakana}]/u.test(prose))
+        return 'ja';
+    const han = prose.match(/\p{Script=Han}/gu)?.length ?? 0;
+    const latin = prose.match(/[A-Za-z]/g)?.length ?? 0;
+    if (han >= 4 && han > latin)
+        return 'zh';
+    if ((prose.match(/\b[A-Za-z]+(?:'[A-Za-z]+)?\b/g)?.length ?? 0) >= 3)
+        return 'en';
+    return undefined;
+}
+/** The dsh-tui prefs file this plugin mirrors (shared language contract). */
+const LANG_FILE = join(homedir(), '.dsh-tui', 'lang.json');
+const dict = {
+    // ── ⏵ self-narration contract (system prompt, /lang aware) ──────────
+    'narrate-instruction': {
+        zh: '[状态栏] 你有一个状态栏展示给用户。【必须】在每个步骤/子任务开始时（不只是调用工具前），在回复正文的最前面单独写一行：⏵ 你在做的具体事情（不超过20字），然后换行继续正常回复。整轮回复只写一行 ⏵，不要重复。信息为主——让人一眼知道你在干什么，风格自然、可以带点俏皮。例：⏵ 修复登录页样式、⏵ 查一下报错原因、⏵ 给补丁跑个验证。切换任务时必须更新。',
+        en: '[Status line] You have a status line visible to the user. [Required] At the start of each step or subtask (not only before tool calls), write exactly one standalone line at the very beginning of your response: ⏵ a concrete description of what you are doing (20 words max), then continue with the normal response on the next line. Write only one ⏵ line per response and do not repeat it. Prioritize information so the user can understand the current work at a glance; keep the style natural and optionally playful. Examples: ⏵ Fixing the login page styles, ⏵ Investigating the error, ⏵ Running validation for the patch. Update it when the task changes.',
+    },
+    // ── status-line structural copy ─────────────────────────────────────
+    /** Plain (non-playful) phase labels. */
+    'waiting-label': { zh: '等待模型响应', en: 'Waiting for model', ja: 'モデルの応答待ち' },
+    'thinking-label': { zh: '思考中', en: 'Thinking', ja: '考えています' },
+    /** Elapsed suffix: zh glues the char, en keeps a space. */
+    'line-elapsed': { zh: '总{{elapsed}}', en: 'total {{elapsed}}', ja: '合計 {{elapsed}}' },
+    /** Plain-mode completion prefix (playful pools pick their own). */
+    'done-prefix': { zh: '搞定 ✓', en: 'Finished', ja: '完了 ✓' },
+    /** Turn-completion summary. */
+    'done-summary': {
+        zh: '{{tools}} · 想{{thinking}} 干{{tooling}}',
+        en: '{{tools}} · thought {{thinking}} worked {{tooling}}',
+        ja: '{{tools}} · 思考 {{thinking}} 作業 {{tooling}}',
+    },
+    'tool-count-one': { zh: '{{count}} 工具', en: '{{count}} tool', ja: 'ツール {{count}} 件' },
+    'tool-count-many': { zh: '{{count}} 工具', en: '{{count}} tools', ja: 'ツール {{count}} 件' },
+    /** Consecutive-tool streak badge (replaces the old flame emoji). */
+    'tool-streak': { zh: '工具x{{count}}', en: 'tool x{{count}}', ja: 'ツール連続 {{count}} 件' },
+    /** Approval badge while a tool is parked on the user's decision. */
+    'tool-waiting-approval': { zh: '在等你批准', en: 'awaiting your approval', ja: '承認待ち' },
+    /** Subagent count in the done summary. */
+    'subagent-count': { zh: '子代理 {{count}} 个', en: '{{count}} subagents', ja: 'サブエージェント {{count}} 件' },
+    /** Work-reminder copy after `workRemindAt` turn-hours. */
+    'work-remind': { zh: '已连续工作 {{hours}} 小时，歇会儿？', en: 'Worked {{hours}}h straight — take a break?', ja: '{{hours}} 時間続けて作業しています。少し休みますか？' },
+};
+/** Explicit pin set by plugin config or tests; `auto` restores the chain. */
+let override = 'auto';
+/** Force (or release) the active language; `auto` re-enables the chain. */
+export function setLangOverride(lang) {
+    override = lang;
+    // Releasing (or re-setting) the pin decides the language from the file again,
+    // and an explicit switch must not wait out the probe TTL.
+    invalidateLangCache();
+}
+/** The currently active language. */
+export function langNow() {
+    const scoped = progressLanguage.getStore();
+    if (scoped !== undefined)
+        return scoped;
+    if (override !== 'auto')
+        return override;
+    const env = process.env.DSH_TUI_LANG;
+    if (env === 'zh' || env === 'en')
+        return env;
+    return readLangFile() ?? detectLocaleLang();
+}
+/** Translate a dictionary key, substituting `{{name}}` placeholders. */
+export function t(key, params = {}) {
+    const entry = dict[key];
+    const template = entry?.[langNow()] ?? entry?.en ?? key;
+    return template.replace(/\{\{(\w+)\}\}/g, (match, name) => name in params ? String(params[name]) : match);
+}
+/** Is a value a valid shipped language code? */
+export function isLang(value) {
+    return value === 'zh' || value === 'en' || value === 'ja';
+}
+/**
+ * How long one filesystem probe is trusted. Long enough that a 500 ms status
+ * render does not stat the file on every translation, short enough that a
+ * `/lang` switch written by the UI still lands within a second.
+ */
+const LANG_FILE_PROBE_TTL_MS = 1000;
+/**
+ * Read the persisted dsh-tui language choice.
+ *
+ * The probe is cached twice over: the parsed value is reused while the file's
+ * mtime is unchanged, and even the `statSync` itself is skipped for
+ * {@link LANG_FILE_PROBE_TTL_MS}. Both halves matter — one render translates
+ * several keys, and a host that never wrote the file would otherwise pay a
+ * FAILED stat on every one of them (issue #14).
+ *
+ * @param nowMs - Instant to measure the probe cache against.
+ * @returns the persisted language, or `undefined` when the file is absent or
+ * holds no valid `{ lang }` value.
+ */
+export function readLangFile(nowMs = Date.now()) {
+    if (lastProbeAt !== 0 && nowMs - lastProbeAt < LANG_FILE_PROBE_TTL_MS)
+        return cachedLang;
+    lastProbeAt = nowMs;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(LANG_FILE).mtimeMs;
+    }
+    catch {
+        // Absence is cached like any other answer: the common case on a host that
+        // never ran the UI's language picker.
+        cachedMtime = -1;
+        cachedLang = undefined;
+        return undefined;
+    }
+    if (cachedMtime === mtimeMs)
+        return cachedLang;
+    try {
+        const parsed = JSON.parse(readFileSync(LANG_FILE, 'utf8'));
+        const lang = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed.lang
+            : undefined;
+        cachedLang = isLang(lang) ? lang : undefined;
+    }
+    catch {
+        cachedLang = undefined;
+    }
+    cachedMtime = mtimeMs;
+    return cachedLang;
+}
+/**
+ * Drop the file cache so the next read probes the filesystem immediately.
+ * Called whenever the language is pinned explicitly, so a switch is never
+ * delayed by the probe TTL.
+ */
+export function invalidateLangCache() {
+    lastProbeAt = 0;
+    cachedMtime = -1;
+    cachedLang = undefined;
+}
+let cachedMtime = -1;
+let cachedLang;
+/** When the file was last probed; `0` means "never probed in this process". */
+let lastProbeAt = 0;
+/**
+ * Guess the language from the OS locale (`LC_ALL`, `LC_MESSAGES`, `LANG`),
+ * defaulting to `zh`. POSIX/C means "no locale selected" and conventionally
+ * maps to English (what CI runners report). An absent locale variable
+ * (typical on Windows) defaults to `zh`.
+ */
+export function detectLocaleLang() {
+    const raw = process.env.LC_ALL ||
+        process.env.LC_MESSAGES ||
+        process.env.LANG ||
+        '';
+    const locale = raw.split('.')[0]?.toLowerCase() ?? '';
+    if (locale.startsWith('zh'))
+        return 'zh';
+    if (locale.startsWith('en'))
+        return 'en';
+    if (locale === 'c' || locale === 'posix')
+        return 'en';
+    return 'zh';
+}