argus-decision-mcp 1.2.0 → 1.3.0

package/dist/lib/ambient-elicit.js

@@ -0,0 +1,225 @@
+import fs from 'fs';
+import path from 'path';
+import { elicit, canElicit } from './elicit.js';
+import { replayLedger } from './ledger-replay.js';
+import { resolveToday } from './resolve-today.js';
+import { resolveResponseLocale } from './surfaces.js';
+import { resolveToolArgusDir } from './argus-dir.js';
+import { configPath } from './layout.js';
+import { atomicWriteJson } from './atomic-write.js';
+import { logError } from './log.js';
+import { sanitizeLine } from '../v2/sanitize.js';
+/**
+ * Out-of-band ambient elicitation — the MCP-side firing gate (창업자 컨셉
+ * 2026-07-15, 스파이크 spikes/ambient-elicit/ 가 프로토콜 층을 실증).
+ *
+ * The wire is bidirectional: `elicitation/create` is a server→client request
+ * and nothing ties it to an in-flight tool call. So after a tool call ends and
+ * the user goes back to their main work, THIS module may ask them the one due
+ * question — the wait becomes judgment time, no plugin required.
+ *
+ * Gate BEFORE form (spine mirror clause — don't judge WHETHER to intervene in
+ * the user's stead; default is restraint):
+ *
+ *   arm-time  — host declared elicitation? not already spent? then debounce:
+ *               each tool call re-arms one quiet-delay timer (fire only when
+ *               Argus goes quiet — mid-conversation is not the wait).
+ *   fire-time — EVERYTHING re-checked: capability, `ambient_mute: true` in
+ *               config.yaml (the SAME escape hatch as the due-note tail — one
+ *               mute, not two), cross-session cooldown (4h, state file), and
+ *               due recomputed from the ledger (zero due = silence).
+ *   budget    — at most ONE ask per server process (one question per sitting);
+ *               an argus_check_in call spends the budget (the user just saw
+ *               their dues — asking again in a minute is nagging, the same
+ *               principle as due-note's SKIP_TOOLS mark).
+ *   decline   — is an answer. Nothing written, budget stays spent, the state
+ *               file's cooldown keeps the next session from insta-re-asking.
+ *
+ * Form (spine §9.2): only the settlement outcome — the ONE spine-SAFE
+ * structured pick (reality, not a verdict; same enum as argus_settle's
+ * in-band elicit). Premise re-checks and open questions are deliberately NOT
+ * asked out-of-band in v1: their honest form is free text, and free text
+ * without conversational context invites fabricated-feeling answers. The
+ * recording brain is NOT duplicated: an accepted answer is fed to the real
+ * settle handler (injected via init), which runs every guard, receipt, and
+ * dual-write exactly as an in-band settle would. still_pending composes for
+ * free — the settle handler's own defer elicitation runs over the same
+ * out-of-band channel.
+ *
+ * Honest limits: real-host rendering of out-of-band pickers is per-host
+ * empirical (spike README table); an unanswered ask times out to null and is
+ * treated as a decline. Any internal failure is swallowed — an ambient extra
+ * must never tax the session it rides on.
+ */
+const COOLDOWN_MS = 4 * 60 * 60 * 1000; // 세션(연결)을 넘는 재발사 간격
+const DEFAULT_ASK_TIMEOUT_MS = 120_000; // 렌더 안 하는 호스트에서 조용히 접는 시한
+const DEFAULT_QUIET_MS = 45_000; // 마지막 툴 호출 뒤 이만큼 조용하면 발사
+function askTimeoutMs() {
+    const raw = Number(process.env['ARGUS_AMBIENT_ASK_TIMEOUT_MS']);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_ASK_TIMEOUT_MS;
+}
+let _settleHandler = null;
+let _serialize = (fn) => fn();
+let _timer = null;
+let _spent = false; // 프로세스당 질문 1개 — 한 자리에 한 질문
+let _inFlight = false;
+/** server.ts가 시동 시 배선한다. 미배선이면 arm은 완전 no-op (정직한 미연결). */
+export function initAmbientElicit(deps) {
+    _settleHandler = deps.settleHandler;
+    if (deps.serialize)
+        _serialize = deps.serialize;
+}
+/** 테스트 리셋 — 타이머·예산·배선을 모두 되돌린다. */
+export function resetAmbientElicit() {
+    if (_timer)
+        clearTimeout(_timer);
+    _timer = null;
+    _spent = false;
+    _inFlight = false;
+    _settleHandler = null;
+    _serialize = (fn) => fn();
+}
+function quietMs() {
+    const raw = Number(process.env['ARGUS_AMBIENT_DELAY_MS']);
+    return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_QUIET_MS;
+}
+function muted(dir) {
+    try {
+        return /^ambient_mute:\s*true\b/m.test(fs.readFileSync(configPath(dir), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+const statePath = (dir) => path.join(dir, 'ambient-elicit-state.json');
+function underCooldown(dir) {
+    try {
+        const st = JSON.parse(fs.readFileSync(statePath(dir), 'utf8'));
+        return typeof st.last_fired_at === 'number' && Date.now() - st.last_fired_at < COOLDOWN_MS;
+    }
+    catch {
+        return false; // 상태 부재·파손 = 이력 없음
+    }
+}
+function withTimeout(p, ms) {
+    return new Promise((res) => {
+        const t = setTimeout(() => res(null), ms);
+        t.unref?.();
+        p.then((v) => { clearTimeout(t); res(v); }, () => { clearTimeout(t); res(null); });
+    });
+}
+/**
+ * 디스패처가 매 툴 호출 뒤에 부른다 (fire-and-forget, 절대 던지지 않음).
+ * 타이머는 디바운스 — 새 호출이 오면 리셋되어, Argus가 조용해진 뒤에만 발사.
+ */
+export function armAmbientElicit(toolName, args) {
+    try {
+        if (!_settleHandler)
+            return; // 미배선 = no-op
+        if (toolName === 'argus_check_in') {
+            _spent = true;
+            return;
+        } // due를 방금 봤다 — 예산 소진
+        if (_spent || !canElicit())
+            return;
+        let dir;
+        try {
+            dir = resolveToolArgusDir(args['argus_dir']);
+        }
+        catch {
+            return;
+        }
+        const todayOverride = typeof args['today_override'] === 'string' ? args['today_override'] : undefined;
+        if (_timer)
+            clearTimeout(_timer);
+        _timer = setTimeout(() => { void fire(dir, todayOverride); }, quietMs());
+        _timer.unref?.();
+    }
+    catch { /* ambient는 절대 본 호출에 세금을 물리지 않는다 */ }
+}
+async function fire(dir, todayOverride) {
+    try {
+        if (_spent || _inFlight || !_settleHandler || !canElicit())
+            return;
+        if (muted(dir) || underCooldown(dir))
+            return;
+        const today = resolveToday({ override: todayOverride });
+        const state = replayLedger(dir, today);
+        const first = state.overdue[0];
+        if (!first)
+            return; // due 0건 = 침묵 (빈 질문은 표현 불가)
+        // 여기서부터는 시도 = 예산 소진. 상태 기록이 실패하면 발사하지 않는다 —
+        // 상한 없는 질문보다 한 번 거르는 쪽이 안전하다 (driver 훅과 같은 자세).
+        _spent = true;
+        _inFlight = true;
+        try {
+            await atomicWriteJson(statePath(dir), { last_fired_at: Date.now() });
+        }
+        catch {
+            return;
+        }
+        const ko = resolveResponseLocale(dir) === 'ko';
+        const text = sanitizeLine(first.text || first.id, 120);
+        // 물음 1 — 정산 outcome (spine-SAFE 구조 픽: 현실이지 평결이 아니다).
+        // 대화 맥락이 없는 사용자를 위해 그의 예측을 그대로 되비춘다 (우정 1조).
+        const picked = await withTimeout(elicit(ko
+            ? `Argus — 확인일이 지난 예측이 있어요: "${text}" (확인일 ${first.date}). 현실이 어떻게 답했나요? 지금 어려우면 닫아도 됩니다 — 다시 조르지 않아요.`
+            : `Argus — a prediction passed its check-by: "${text}" (due ${first.date}). What did reality do? Dismiss if now is a bad time — no re-asking.`, {
+            type: 'object',
+            required: ['outcome'],
+            properties: {
+                outcome: {
+                    type: 'string',
+                    enum: ['held', 'avoided', 'partial', 'still_pending', 'missed'],
+                    enumNames: ko
+                        ? ['그렇게 됐다 (held)', '피했다 (avoided)', '부분적으로 (partial)', '아직 불분명 (still pending)', '빗나갔다 (missed)']
+                        : ['It held', 'Avoided it', 'Partially', 'Still pending', 'Missed — my read was wrong'],
+                    description: ko ? '봉인한 예측에 현실이 어떻게 답했는지.' : 'What reality did to your sealed prediction.',
+                },
+            },
+        }), askTimeoutMs());
+        const outcome = picked?.['outcome'];
+        if (outcome !== 'held' && outcome !== 'avoided' && outcome !== 'partial' && outcome !== 'still_pending' && outcome !== 'missed') {
+            return; // 거절·시간초과·미렌더 = 답이다. 아무것도 쓰지 않는다.
+        }
+        // still_pending은 실제 settle 핸들러의 defer elicitation이 같은 채널로
+        // 이어서 묻는다 (두뇌 하나). 종결 outcome은 what_happened를 사용자의
+        // 말로 받아야만 기록한다 — 비면 기록하지 않는다 (날조 금지, 정직한 공백).
+        let whatHappened;
+        if (outcome !== 'still_pending') {
+            const wh = await withTimeout(elicit(ko
+                ? '실제로 무슨 일이 있었나요? 한 줄이면 됩니다 — 당신의 말 그대로 기록됩니다.'
+                : 'What actually happened, in one line? Recorded verbatim, in your words.', {
+                type: 'object',
+                required: ['what_happened'],
+                properties: {
+                    what_happened: {
+                        type: 'string', maxLength: 600,
+                        description: ko ? '당신의 말, 그대로.' : 'Your words, verbatim.',
+                    },
+                },
+            }), askTimeoutMs());
+            whatHappened = typeof wh?.['what_happened'] === 'string' ? wh['what_happened'].trim() : '';
+            if (!whatHappened)
+                return; // 현실 서술 없이는 종결 정산을 쓰지 않는다
+        }
+        // 기록은 실제 settle 핸들러로 — 가드·영수증·이중쓰기 전부 본 경로 그대로.
+        // 툴 호출 직렬화 사슬에 태워 원장 read-replay-append가 절대 끼어들지 않게.
+        const result = await _serialize(() => _settleHandler({
+            argus_dir: dir,
+            id: first.id,
+            outcome,
+            outcome_source: 'user_stated',
+            ...(whatHappened ? { what_happened: whatHappened } : {}),
+            ...(todayOverride ? { today_override: todayOverride } : {}),
+        }));
+        if (result.isError)
+            logError('[ambient-elicit] settle refused', result.structuredContent?.['error_code']);
+    }
+    catch (e) {
+        logError('[ambient-elicit] fire failed', e);
+    }
+    finally {
+        _inFlight = false;
+    }
+}

package/dist/lib/argus-dir.js

@@ -3,17 +3,21 @@ import os from 'os';
 import path from 'path';
 import { boundMarkerPath } from './layout.js';
 /**
- * argus_dir resolution + precedence (blueprint §4.0 + addendum A/B).
+ * argus_dir resolution + precedence (blueprint §4.0 + addendum A/B; §9.7 O1).
  *
  * The `${workspaceFolder}` config variable only expands in VS Code — Claude
  * Code expands `${CLAUDE_PROJECT_DIR}`, others expand nothing. So env
  * interpolation is the LEAST reliable channel and must come last. Tools always
  * receive a per-call `argus_dir`, which works on every host, so that wins.
  *
- * Precedence:
- *   1. per-call `argus_dir` argument            (works on every host)
- *   2. last dir written to `.bound` by argus_init (read-side for Resources)
- *   3. ARGUS_DIR env                            (host-dependent interpolation)
+ * Precedence (tools and resources must tell the same storage story):
+ *   tools:     1. per-call `argus_dir`  2. ARGUS_DIR env  3. ~/.argus default
+ *   resources: (no per-call channel)   1. ARGUS_DIR env  2. ~/.argus default
+ *
+ * One deliberate asymmetry: an ARGUS_DIR that is SET but invalid makes a tool
+ * THROW (requireArgusDir) but makes a resource return null/unbound — resources
+ * can't error usefully, and silently reading a ledger the user didn't
+ * configure would be worse than degrading.
  */
 export class ArgusDirError extends Error {
     code = 'ARGUS_DIR_INVALID';
@@ -123,12 +127,26 @@ function readBoundList(argusDir) {
 }
 /**
  * Resolve argus_dir for a Resource read (no per-call arg available).
- * Returns null (unbound) rather than throwing — the Resource degrades cleanly.
+ *
+ * Mirrors the tool chain minus the per-call arg: ARGUS_DIR env, else the same
+ * zero-config `~/.argus` default that tools write to — so a zero-config
+ * install's passive attention surface reads the SAME ledger its tools use.
+ * (§9.7 O1 방2. Previously env-only, which left every zero-config install's
+ * `argus://attention` permanently `{unbound}` while argus_predict happily
+ * wrote to ~/.argus — the return loop's front door was dark.)
+ *
+ * Stays null (unbound, cleanly degraded) ONLY when ARGUS_DIR is set but
+ * invalid — unexpanded `${...}`/`%...%` or a relative path. Falling back to
+ * ~/.argus in that case would silently read a different ledger than the one
+ * the user configured; unbound-with-hint is the resource's honest-failure
+ * form of the requireArgusDir throw.
  */
 export function resolveArgusDirForResource() {
     const env = process.env['ARGUS_DIR'];
-    if (typeof env === 'string' && env.length > 0 && path.isAbsolute(env)) {
+    if (typeof env === 'string' && env.length > 0) {
+        if (/\$\{[^}]*\}|%[A-Za-z_]+%/.test(env) || !path.isAbsolute(env))
+            return null;
         return path.resolve(env);
     }
-    return null;
+    return path.join(os.homedir(), '.argus');
 }

package/dist/lib/calendar.js

@@ -35,9 +35,9 @@ export function renderReturnCalendarEvent(args) {
     const stamp = args.created_at.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
     const summary = `Argus return: ${args.predicate.slice(0, 80)}`;
     const description = [
-        'Your sealed Argus decision is due today.',
+        'An Argus prediction has reached its check date.',
         `Predicate: ${args.predicate}`,
-        'Open your terminal and run argus_check_in, then argus_settle if reality is clear.',
+        'Open your terminal and run argus_check_in, then argus_resolve if reality is clear.',
     ].join('\n');
     const lines = [
         'BEGIN:VCALENDAR',

package/dist/lib/due-note.js

@@ -73,11 +73,11 @@ export function appendDueNote(toolName, args, result) {
         // ── channel 1: machine counts (host-choice; unchanged) ──
         const parts = [];
         if (due.premiseFactsDue > 0)
-            parts.push(`${due.premiseFactsDue} premise fact(s) to re-check (argus_recheck)`);
+            parts.push(`${due.premiseFactsDue} premise fact(s) to re-check (argus_capture action=update_fact)`);
         if (due.openQuestionsDue > 0)
-            parts.push(`${due.openQuestionsDue} open question(s) to reconsider (argus_premises)`);
+            parts.push(`${due.openQuestionsDue} open question(s) to reconsider (argus_capture)`);
         if (due.contractsDue > 0)
-            parts.push(`${due.contractsDue} contract(s) to settle (argus_settle)`);
+            parts.push(`${due.contractsDue} prediction result(s) to record (argus_resolve)`);
         const data = (sc['data'] ??= {});
         if (!('due_note' in data))
             data['due_note'] = parts.join(' · ');

package/dist/lib/elicit.js

@@ -10,10 +10,22 @@
  * the text flow — no crash, no dead end.
  */
 let _elicit = null;
-export function setElicitor(fn) {
+let _capable = null;
+/** Wire the elicitor and, optionally, a live capability probe. The probe must
+ *  reflect the ACTUAL host: the MCP spec (and the SDK) only permit elicitInput
+ *  when the client DECLARED the `elicitation` capability at initialize — calling
+ *  it otherwise throws. Without an accurate probe, `canElicit()` would report
+ *  true on a host that will actually throw, and a caller that reads a null result
+ *  as "the user declined" (rather than "no picker here") silently drops work.
+ *  The probe closes that gap: no declared capability ⇒ callers skip the picker
+ *  and take their text path. */
+export function setElicitor(fn, capable) {
     _elicit = fn;
+    _capable = capable ?? null;
 }
 export function canElicit() {
+    if (_capable)
+        return _capable();
     return _elicit !== null;
 }
 /** Ask the user; returns null if unsupported / errored / not accepted. */

package/dist/lib/ledger-replay.js

@@ -118,11 +118,18 @@ export function replayLedger(argusDir, today) {
                 stats.total_settled++;
                 const outcome = ev['outcome'];
                 cur.outcome = outcome;
-                if (typeof ev['ts'] === 'string' && ev['ts'].length >= 10)
-                    cur.settled_on = ev['ts'].slice(0, 10);
+                // Timestamp field is two-vocab across surfaces: this binary stamps `ts`,
+                // the plugin CLI stamps `at` — read both so a plugin-settled decision
+                // still gets its settled date on the receipt (O2 방1 finding ⑤).
+                const settledTs = typeof ev['ts'] === 'string' ? ev['ts'] : typeof ev['at'] === 'string' ? ev['at'] : undefined;
+                if (settledTs && settledTs.length >= 10)
+                    cur.settled_on = settledTs.slice(0, 10);
                 if (typeof ev['broken_premise_id'] === 'string')
                     cur.broken_premise_id = ev['broken_premise_id'];
-                if (outcome === 'held')
+                // `happened` is the plugin CLI's legacy spelling of `held` (pre plain-canon
+                // unification). Old ledgers keep their bytes — the alias lives at read time
+                // so the frequency buckets stay complete (total_settled == sum of buckets).
+                if (outcome === 'held' || outcome === 'happened')
                     stats.held++;
                 else if (outcome === 'avoided')
                     stats.avoided++;
@@ -275,6 +282,15 @@ export function replayLedger(argusDir, today) {
             }
             case 'gate_input':
                 break; // known meta event (over-fire gate audit) — not a state change, not corrupt
+            case 'wake':
+                // Plugin-side event (sail Step 7.5: the in-session 1st settlement of the
+                // BIND lean — did the user's own read hold once the reviewers were in?).
+                // Session-scoped, not part of the decision state machine; the plugin's
+                // own reducer folds it. Until 2026-07-17 this binary counted it as a
+                // DROPPED line (plugin events carried no `v` stamp), so a ledger shared
+                // between the plugin and the MCP raised a false corruption alarm on
+                // check_in (O2 방1 cross-surface finding ①).
+                break;
             // ── 당직 루프 (§9) — outside the decision state machine. No contract
             //    entry is created; nothing touches stats. Anchor is a note, not a bet.
             case 'watch_anchor': {

package/dist/lib/locale-mismatch.js

@@ -0,0 +1,52 @@
+import fs from 'fs';
+import path from 'path';
+import { contentLocaleFromArgs } from './locale.js';
+import { configLocale } from './surfaces.js';
+/**
+ * Locale-mismatch once-note (§9.7 O1 product contract: "locale은 대화-언어
+ * 우선 — 설정과 대화 언어가 어긋나면 1회 확인, 감지 1회 영구 고착 금지").
+ *
+ * The escape hatch stays intact: an explicit config locale is never silently
+ * overridden (that guarantee is what makes the pin trustworthy). But until
+ * now the pin was also never QUESTIONED — the 2026-06-15 incident wrote
+ * `locale: en` into a real config during an English-driven eval run, and a
+ * Korean founder then got English surfaces for a month with nothing ever
+ * saying "your saved language disagrees with your words".
+ *
+ * Contract: when an explicit pin exists AND the user's own content confidently
+ * speaks the other language, append ONE note — a fact plus the argus_settings
+ * handle, in the language the user is speaking — to the next successful
+ * surface. Once per ledger, ever (marker file); declining by ignoring it is a
+ * valid answer and is never re-asked. No auto-update, no directive: the config
+ * change stays an authorial act the user performs.
+ */
+const MARKER = 'locale-mismatch-noted';
+export function appendLocaleMismatchNote(argusDir, args, result) {
+    try {
+        if (!argusDir)
+            return result;
+        const pinned = configLocale(argusDir);
+        if (!pinned)
+            return result; // no pin → the text-detection chain already speaks the user's language
+        const spoken = contentLocaleFromArgs(args);
+        if (!spoken || spoken === pinned)
+            return result;
+        const marker = path.join(argusDir, MARKER);
+        if (fs.existsSync(marker))
+            return result; // asked once already — silence forever
+        const sc = result.structuredContent;
+        if (!sc || sc['ok'] !== true || typeof sc['surface'] !== 'string')
+            return result; // never decorate errors
+        fs.writeFileSync(marker, new Date().toISOString());
+        const note = spoken === 'ko'
+            ? '\n(설정 언어가 English로 고정되어 있어요. 한국어로 바꾸려면 argus_settings에 locale="ko" 한 번이면 돼요 — 이 안내는 다시 나오지 않아요.)'
+            : '\n(Your saved language is Korean. To switch, call argus_settings with locale="en" once — this note will not appear again.)';
+        const next = { ...sc, surface: `${sc['surface']}${note}` };
+        result.structuredContent = next;
+        result.content = [{ type: 'text', text: JSON.stringify(next, null, 2) }];
+        return result;
+    }
+    catch {
+        return result; // a broken note must never wedge a tool call
+    }
+}

package/dist/lib/locale.js

@@ -1,10 +1,89 @@
 import fs from 'fs';
 import { detect } from 'tinyld/light';
 import { configPath } from './layout.js';
+/** The user-authored text fields worth sniffing for the session's language.
+ *  Incidental fields (ids, notes on machine actions) are excluded so a stray
+ *  token can't flip a session. */
+const CONTENT_FIELDS = [
+    'decision', 'predicate', 'what_happened', 'finding', 'text', 'question',
+    'human_judgment', 'observation_text', 'statement', 'review_question',
+];
+/**
+ * Persist a Korean locale the FIRST time the user's own words are Korean, so the
+ * whole session stays Korean — including later surfaces with no text to sniff
+ * (validation errors, recall, check_in). This is content-driven, never env:
+ *   - only a POSITIVE Korean content signal ever writes (English never pins);
+ *   - never overrides an explicit locale already in config.
+ * Fixes mid-session English leaks on a Korean session (2026-07-14 locale sweep).
+ */
+export function learnLocaleFromContent(argusDir, args) {
+    if (!argusDir)
+        return;
+    if (contentLocaleFromArgs(args) !== 'ko')
+        return;
+    try {
+        const p = configPath(argusDir);
+        let cfg = '';
+        try {
+            cfg = fs.readFileSync(p, 'utf8');
+        }
+        catch { /* no config yet → auto-init writes one before the handler returns */ }
+        if (/^locale:\s*(ko|en)\b/m.test(cfg))
+            return; // explicit locale already set — never override
+        const next = cfg
+            ? `${cfg.endsWith('\n') ? cfg : `${cfg}\n`}locale: ko\n`
+            : 'schema_version: 5\nlocale: ko\n';
+        fs.writeFileSync(p, next);
+    }
+    catch { /* best-effort: a failed persist just means the next Korean surface re-sniffs from content */ }
+}
+/** The language the user is ACTUALLY speaking in this call, judged only from
+ *  their own content fields (never ids/env). Null when there is no confident
+ *  signal. Shared by learnLocaleFromContent (pins ko on a fresh config) and
+ *  the locale-mismatch once-note (§9.7 O1 — a pinned config that contradicts
+ *  the conversation language must be surfaced once, not silently obeyed
+ *  forever: the 2026-06-15 locale:en contamination stayed invisible for a
+ *  month precisely because nothing ever said "your config disagrees with
+ *  your words"). */
+export function contentLocaleFromArgs(args) {
+    const sample = CONTENT_FIELDS
+        .map((k) => args[k])
+        .filter((v) => typeof v === 'string' && v.trim().length > 0)
+        .join('\n');
+    return sample ? detectLocaleFromText(sample) : null;
+}
+/**
+ * osLocaleHint — THE one OS-environment locale probe (§9.7 O1 방1: one env
+ * resolver, consumed by every locale chain).
+ *
+ * Until 2026-07-16 this env→Intl chain lived in two copies (detectLocale here,
+ * resolveResponseLocale in surfaces.ts) and both treated env as a KO-DETECTOR
+ * ONLY: `LANG=en_US` didn't pin en — the chain fell through to Intl and a
+ * Korean-locale OS still resolved ko. That asymmetry is why the release suite
+ * was machine-dependent (4 reds on a ko OS; overhaul review §10) and why an
+ * explicit English env could never assert itself.
+ *
+ * Rule: a NON-EMPTY LANG/LC_ALL names the user's working language explicitly —
+ * ko iff it starts with ko, else en (Argus is binary ko/en). Only an EMPTY env
+ * falls through to the OS Intl locale. Explicit config wins ABOVE this at
+ * every call site, and Korean CONTENT re-claims ko later regardless (the text
+ * step / learnLocaleFromContent) — so an en hint never locks a Korean user out.
+ */
+export function osLocaleHint() {
+    const env = process.env['LANG'] || process.env['LC_ALL'] || '';
+    if (env)
+        return /^ko/i.test(env) ? 'ko' : 'en';
+    try {
+        if (/^ko/i.test(Intl.DateTimeFormat().resolvedOptions().locale))
+            return 'ko';
+    }
+    catch { /* Intl unavailable */ }
+    return 'en';
+}
 /**
  * detectLocale — CONFIG/ENV detection seeded at argus_init write time.
  *
- * Chain (write-time): explicit config > env (LANG/LC_ALL) > Intl > 'en'.
+ * Chain (write-time): explicit config > osLocaleHint (env, then Intl) > 'en'.
  * The runtime input-text step lives in resolveResponseLocale (surfaces.ts),
  * which layers text detection on TOP of a persisted config. This function
  * stays env-only so a fresh dir on a KST machine seeds locale:ko once.
@@ -17,15 +96,7 @@ export function detectLocale(argusDir) {
             return m[1];
     }
     catch { /* no config */ }
-    const env = process.env['LANG'] || process.env['LC_ALL'] || '';
-    if (/^ko/i.test(env))
-        return 'ko';
-    try {
-        if (/^ko/i.test(Intl.DateTimeFormat().resolvedOptions().locale))
-            return 'ko';
-    }
-    catch { /* Intl unavailable */ }
-    return 'en';
+    return osLocaleHint();
 }
 /**
  * detectLocaleFromText — the runtime language sniff (M4, spec §4).