elanous 0.2.41 → 0.2.43

package/src/llm.ts

@@ -27,6 +27,7 @@ import {
   DEFAULT_PROVIDER,
 } from './config.js';
 import { debug, redactSecrets, redactSecretText } from './debug/log.js';
+import { estimateMessagesTokens } from './tokens.js';
 import { isVerifiedOpenGatewayModel } from './llm/opengateway-models.js';
 import { llmUsageCostFields } from './budget/llm-cost.js';
 import { accumulateByokUsage } from './llm/openrouter-byok-cost.js';
@@ -274,6 +275,13 @@ export interface LLMMessage {
   phase?: 'commentary' | 'partial_answer' | 'final_answer';
   /** Opaque Codex stateless reasoning items, before this assistant message. */
   codexReasoningItems?: Array<{ type: 'reasoning'; encrypted_content: string; summary: unknown[]; id?: string }>;
+  /** TUI-PROMPT-CACHE-PREFIX — a `system` message whose text changes between
+   *  requests of one session (seat boot card · git snapshot · memory · self
+   *  health · per-turn guidance). The Codex Responses serializer keeps these
+   *  OUT of `instructions` (which must stay byte-stable for prompt-cache
+   *  prefix reuse) and sends them as a `developer` item placed just before
+   *  the latest user message. Other providers ignore the flag. */
+  cacheVolatile?: boolean;
 }
 
 /** JSONSchema-shaped tool definition sent to the provider (no handler). */
@@ -1707,6 +1715,15 @@ export interface MessagesToResponsesInputOpts {
   replayCodexReasoning?: boolean;
   acceptUserMessageImages?: boolean;
   onOrphanToolResult?: (callId: string) => void;
+  /** TUI-PROMPT-CACHE-PREFIX — keep `instructions` stable for the prompt
+   *  cache prefix. When true: (a) leading `system` messages flagged
+   *  `cacheVolatile` are merged into ONE `developer` item inserted right
+   *  before the latest user text message (after the cached history), and
+   *  (b) `system` messages that appear after the conversation started
+   *  (loop self-notes, mid-turn hints) are emitted IN PLACE as `developer`
+   *  items instead of being folded into `instructions`. Default false keeps
+   *  the legacy "every system → instructions" fold. */
+  stablePrefix?: boolean;
 }
 
 /** Exported for tests. Converts the unified LLMMessage shape into the
@@ -1747,6 +1764,11 @@ export function messagesToResponsesInput(
 
   const sys: string[] = [];
   const input: ResponsesInputItem[] = [];
+  const stablePrefix = opts.stablePrefix === true;
+  // Leading volatile system text (stablePrefix only) — spliced in before the
+  // latest user text message once the whole input is assembled.
+  const volatileSys: string[] = [];
+  let conversationStarted = false;
   for (const m of messages) {
     // Build typed content blocks: text accumulated into one block,
     // images appended as separate input_image entries. The old
@@ -1873,9 +1895,20 @@ export function messagesToResponsesInput(
     }
 
     if (m.role === 'system') {
+      if (stablePrefix && conversationStarted) {
+        // Mid-conversation system note → in-place developer item. Folding it
+        // into `instructions` would rewrite the cache prefix every round.
+        if (textBuf) input.push({ role: 'developer', content: [{ type: 'input_text', text: textBuf }] });
+        continue;
+      }
+      if (stablePrefix && m.cacheVolatile) {
+        if (textBuf) volatileSys.push(textBuf);
+        continue;
+      }
       sys.push(textBuf);
       continue;
     }
+    conversationStarted = true;
 
     // Stateless Codex requires the opaque reasoning item in its original
     // position before the corresponding assistant message/tool calls.
@@ -1901,6 +1934,13 @@ export function messagesToResponsesInput(
     }
     input.push(...trailingItems);
   }
+  if (volatileSys.length > 0) {
+    const developerItem: ResponsesInputItem = {
+      role: 'developer',
+      content: [{ type: 'input_text', text: volatileSys.join('\n\n') }],
+    };
+    input.splice(latestUserTextIndex(input), 0, developerItem);
+  }
   if (input.length === 0) input.push({ role: 'user', content: [{ type: 'input_text', text: '' }] });
   return {
     instructions: sys.length ? sys.join('\n\n') : 'You are a helpful assistant.',
@@ -1908,6 +1948,17 @@ export function messagesToResponsesInput(
   };
 }
 
+/** Index of the latest user message carrying text/image content (not a bare
+ *  tool output). Volatile per-turn context goes right before it, so the
+ *  history before it stays a stable cached prefix. No such message → end. */
+function latestUserTextIndex(input: readonly ResponsesInputItem[]): number {
+  for (let i = input.length - 1; i >= 0; i--) {
+    const item = input[i]!;
+    if ('role' in item && item.role === 'user') return i;
+  }
+  return input.length;
+}
+
 /** store=true wave: compute the incremental tail when `current` is a
  *  strict extension of `prev`. Returns null when the previous input
  *  isn't usable as a baseline — caller falls back to full input + no
@@ -1960,6 +2011,35 @@ export function computePromptCacheKey(model: string, instructions: string): stri
   return createHash('sha256').update(`${model}::${prefix}`).digest('hex').slice(0, 32);
 }
 
+/** TUI-PROMPT-CACHE-PREFIX — per-conversation cache affinity for the Codex
+ *  Responses backend. Mirrors ref/codex `core/src/client.rs`
+ *  (`PromptCacheKey::SessionDerived` → the session id itself is the
+ *  `prompt_cache_key`, and the same id rides the `session-id` header —
+ *  `codex-api/src/requests/headers.rs`; the underscored `session_id` alias
+ *  was dropped upstream in #22193 because proxies reject `_` headers).
+ *
+ *  Precedence: chat `sessionId` → harness run `ELANOUS_RUN_ID`. Neither →
+ *  null and the caller falls back to the legacy instructions-prefix key.
+ *  Ids that are long (> 64 chars — the prompt_cache_key limit) or carry
+ *  characters outside `[A-Za-z0-9._:-]` fold to `elanous-<sha256/32>`. */
+export function codexSessionCacheKey(
+  sessionId: string | undefined,
+  runId: string | undefined,
+): { key: string; source: 'session' | 'run'; hashed: boolean } | null {
+  const s = sessionId && sessionId.trim() ? sessionId : undefined;
+  const r = runId && runId.trim() ? runId : undefined;
+  const raw = s ?? r;
+  if (!raw) return null;
+  const source = s ? 'session' : 'run';
+  if (raw.length <= 64 && /^[A-Za-z0-9._:-]+$/.test(raw)) return { key: raw, source, hashed: false };
+  return { key: `elanous-${createHash('sha256').update(raw).digest('hex').slice(0, 32)}`, source, hashed: true };
+}
+
+/** Short content hash for request-stability observation (logs only). */
+function stabilityHash(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+
 /** Cycle order for the HUD pill click + `/reasoning` no-arg form. */
 export const REASONING_CYCLE: readonly import('./user-config.js').ReasoningLevel[] =
   ['off', 'low', 'medium', 'high', 'xhigh'] as const;
@@ -2240,8 +2320,12 @@ function buildCodexResponsesWireBody(
     previousResponseId?: string;
   },
   promptCache: boolean,
+  /** Session-derived key (codexSessionCacheKey). Absent → legacy key. */
+  sessionCacheKey?: string,
 ): Record<string, unknown> {
-  const cacheKey = promptCache ? computePromptCacheKey(body.model, body.instructions) : undefined;
+  const cacheKey = promptCache
+    ? (sessionCacheKey ?? computePromptCacheKey(body.model, body.instructions))
+    : undefined;
   return {
     ...body,
     stream: true,
@@ -2259,8 +2343,9 @@ function buildCodexResponsesWireBody(
 function serializeCodexResponsesWireBody(
   body: Parameters<typeof buildCodexResponsesWireBody>[0],
   promptCache: boolean,
+  sessionCacheKey?: string,
 ): string {
-  return JSON.stringify(buildCodexResponsesWireBody(body, promptCache));
+  return JSON.stringify(buildCodexResponsesWireBody(body, promptCache, sessionCacheKey));
 }
 
 export async function* streamCodexResponsesEvents(
@@ -2320,9 +2405,14 @@ export async function* streamCodexResponsesEvents(
     onResponseCreated?: (id: string) => void;
     /** Unused configured fallbacks. Overload k times switches before retries. */
     remainingFallbacks?: number;
+    /** TUI-PROMPT-CACHE-PREFIX — conversation id for cache affinity. When
+     *  set (or `ELANOUS_RUN_ID` is), `prompt_cache_key` is session-derived
+     *  and the `session-id` header is sent (ref/codex parity). */
+    sessionId?: string;
   } = {},
 ): AsyncGenerator<LLMStreamEvent, void, unknown> {
   const startedAt = Date.now();
+  const sessionAffinity = codexSessionCacheKey(extra.sessionId, process.env.ELANOUS_RUN_ID);
   // See comment in streamOpenAIEvents — we drop the raw body by
   // default. `/debug verbose on` restores the full body for deep
   // reproduction.
@@ -2340,6 +2430,16 @@ export async function* streamCodexResponsesEvents(
       inputChars: (() => { try { return JSON.stringify(body.input).length; } catch { return -1; } })(),
       toolChars: (() => { try { return JSON.stringify(body.tools ?? []).length; } catch { return -1; } })(),
       instructionChars: body.instructions.length,
+      // TUI-PROMPT-CACHE-PREFIX — prefix stability: two requests of one
+      // session must log the same instructionsHash ⊕ toolsHash ⊕ cacheKey.
+      instructionsHash: stabilityHash(body.instructions),
+      toolsHash: (() => { try { return stabilityHash(JSON.stringify(body.tools ?? [])); } catch { return 'unhashable'; } })(),
+      toolChoice: body.tool_choice ?? null,
+      promptCacheKey: extra.promptCache === false
+        ? null
+        : (sessionAffinity?.key ?? computePromptCacheKey(body.model, body.instructions)).slice(0, 24),
+      cacheKeySource: extra.promptCache === false ? 'off' : (sessionAffinity?.source ?? 'instructions-prefix'),
+      sessionHeader: sessionAffinity !== null,
       tools: observeRequestTools(body.tools),
       instructions: body.instructions.slice(0, 200),
       accountId: extra.accountId ? `${extra.accountId.slice(0, 8)}…` : '(none)',
@@ -2367,7 +2467,7 @@ export async function* streamCodexResponsesEvents(
   const promptCache = extra.promptCache !== false;
   // TUI-REQUEST-SIZE-COMPACT — the exact serializer is shared with the
   // preflight guard, so the size decision and fetch body cannot drift.
-  const wireBody = buildCodexResponsesWireBody(body, promptCache);
+  const wireBody = buildCodexResponsesWireBody(body, promptCache, sessionAffinity?.key);
   const wireJson = extra.serializedWireBody ?? JSON.stringify(wireBody);
   debug.log('llm.request', 'request-size', {
     provider: 'openai-codex',
@@ -2391,6 +2491,9 @@ export async function* streamCodexResponsesEvents(
         // is treated as an old client → 400 "requires a newer version of
         // Codex". See getCodexUserAgent (oauth/codex.ts).
         'User-Agent': getCodexUserAgent(),
+        // ChatGPT derives cache affinity from this header (ref/codex
+        // client.rs `responses_session_id` → `build_session_headers`).
+        ...(sessionAffinity ? { 'session-id': sessionAffinity.key } : {}),
       },
       body: wireJson,
       signal,
@@ -4474,7 +4577,8 @@ function configuredFallbackChainSteps(): readonly string[] {
   try {
     const { getUserConfig } = require('./user-config.js') as typeof import('./user-config.js');
     const { normalizeFallbackChain } = require('./oauth/fallback-chain.js') as typeof import('./oauth/fallback-chain.js');
-    return normalizeFallbackChain(getUserConfig().llm.fallbackChain).chain;
+    const llm = getUserConfig().llm;
+    return normalizeFallbackChain(llm.fallbackChain, llm.provider).chain;
   } catch (err) {
     // ⛔ 조용히 삼키면 「설정을 못 읽었다」가 「폴백 후보가 없다」로 «둔갑»한다 —
     //   호출자는 그것을 `fallback candidates exhausted` 로 보고 사람에게 그렇게 말한다.
@@ -5828,8 +5932,19 @@ async function tryForceSynthesisPass(args: {
    *  / error), this function emits a clear signal to wipe any
    *  partial text it streamed. */
   streamingHandlers?: { onText: (delta: string, accumulated: string) => void };
+  /** TUI-PROMPT-CACHE-PREFIX — the turn's session + tools. On Codex the pass
+   *  keeps the same tools array (tool_choice:'none') and session cache key so
+   *  it reuses the cached prefix instead of rewriting it with tools dropped. */
+  sessionId?: string;
+  tools?: LLMToolSpec[];
 }): Promise<string | null> {
   const { provider, model, history, turn, modelFamily, streamingHandlers } = args;
+  const keepToolsNoCall = provider.name === 'openai-codex' && (args.tools?.length ?? 0) > 0;
+  const synthesisOpts: LLMOpts = {
+    model,
+    ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+    ...(keepToolsNoCall ? { tools: args.tools, toolChoice: 'none' as const } : {}),
+  };
   const synthesisPromptMsg: LLMMessage = {
     role: 'user',
     content:
@@ -5862,7 +5977,7 @@ async function tryForceSynthesisPass(args: {
   try {
     let collected = '';
     const MAX_OUTPUT_CHARS = 8000;
-    for await (const delta of provider.chat(synthesisHistory, { model, signal: f2Controller.signal })) {
+    for await (const delta of provider.chat(synthesisHistory, { ...synthesisOpts, signal: f2Controller.signal })) {
       collected += delta;
       // Live progressive emit — TUI shows synthesis text as it
       // generates instead of all-at-once at the end (user-reported
@@ -8889,6 +9004,10 @@ export async function streamLLMWithTools(
   //   read-time projection 등 교체. 문맥관리를 substrate 프리미티브로 통일(streamLLMWithTools 인라인 산재 해소).
   const { createDefaultContextStrategy: _makeContextStrategy } = require('./agent-substrate/context-strategy.js') as typeof import('./agent-substrate/context-strategy.js');
   const _contextStrategy = opts.contextStrategy ?? _makeContextStrategy();
+  // Latest provider prompt usage is the trigger baseline. Add estimated growth
+  // appended to history after that request (usually tool output) at the next loop.
+  let previousInputTokens: number | undefined;
+  let previousRequestEstimatedTokens: number | undefined;
   let loopTermination: 'budget-exhausted' | 'aborted' = 'budget-exhausted';
   let terminalTurn = maxTurns;
 
@@ -8976,7 +9095,21 @@ export async function streamLLMWithTools(
             // ★ 조각2 — pluggable context 전략(기본=2-tier compaction·무회귀 이관). 판정+압축을 substrate 프리미티브가
             //   수행 → caller 는 splice/관측/breaker 만. 주입(opts.contextStrategy)으로 read-time projection 등 교체 가능.
             const beforeLen = history.length;
-            const outcome = await _contextStrategy.compact(history, { model: effectiveModel, ...(opts.sessionId ? { sessionId: opts.sessionId } : {}), config: acCfg });
+            const outcome = await _contextStrategy.compact(history, {
+              model: effectiveModel,
+              ...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+              config: acCfg,
+              ...(previousInputTokens !== undefined ? {
+                observedInputTokens: previousInputTokens + Math.max(
+                  0,
+                  estimateMessagesTokens(history) - (previousRequestEstimatedTokens ?? estimateMessagesTokens(history)),
+                ),
+              } : {}),
+            });
+            // This usage event belongs to the request before this compaction
+            // decision; do not carry it into another loop iteration.
+            previousInputTokens = undefined;
+            previousRequestEstimatedTokens = undefined;
             if (outcome.fired && outcome.reduced) {
               history.splice(0, history.length, ...outcome.messages);
               // ★ 관측(2026-07-21) — beforeTokens/afterTokens 포함(reduced 는 개수 아닌 **토큰** 감소로 판정).
@@ -9029,7 +9162,19 @@ export async function streamLLMWithTools(
     // revert to auto (see above).
     const buildTurnOpts = () => {
       const remainingFallbacks = opts.provider ? 0 : remainingFallbackProviderNames(attemptedProviders, opts).length;
-      const base = { ...opts, model: activeModel, tools: completionNeedsFinalTurn ? [] : activeTools, remainingFallbacks };
+      // TUI-PROMPT-CACHE-PREFIX — on Codex the final-answer turn shares the
+      // session cache key, so dropping tools would rewrite the cached prefix
+      // (measured toolChars 67k → 2). Keep the same tools and forbid calls
+      // with tool_choice:'none' instead. Other providers keep the legacy
+      // empty tools (some ignore toolChoice).
+      const keepToolsNoCall = completionNeedsFinalTurn && activeProvider.name === 'openai-codex';
+      const base = {
+        ...opts,
+        model: activeModel,
+        tools: completionNeedsFinalTurn && !keepToolsNoCall ? [] : activeTools,
+        remainingFallbacks,
+      };
+      if (keepToolsNoCall) return { ...base, toolChoice: 'none' as const };
       return turn === 0 ? base : { ...base, toolChoice: undefined };
     };
     let turnOpts = buildTurnOpts();
@@ -9148,6 +9293,7 @@ export async function streamLLMWithTools(
               : turnOpts.toolChoice,
           };
           const providerMessages = mapProviderToolNamesInMessages(history, nameMap.toProviderName);
+          previousRequestEstimatedTokens = estimateMessagesTokens(providerMessages);
           streamIter = restoreProviderToolCallNames(
             activeProvider.streamChat!(providerMessages, providerOpts),
             nameMap.toOriginalName,
@@ -9397,6 +9543,10 @@ export async function streamLLMWithTools(
       } else if (ev.type === 'usage') {
         // Provider parsers normalize inputTokens to uncached input; cache
         // reads/writes are separate fields (prompt-cache/types.ts contract).
+        const observedPromptTokens = (ev.usage.inputTokens ?? 0)
+          + (ev.usage.cacheReadInputTokens ?? 0)
+          + (ev.usage.cacheCreationInputTokens ?? 0);
+        if (observedPromptTokens > 0) previousInputTokens = observedPromptTokens;
         // ⭐ 주 에이전트 턴의 토큰·비용을 «게이트 없이» 남긴다(2026-09-24 실측: 이 줄이 없어 3시간 `llm.usage`
         //   18행이 전부 곁가지 두 자리였고, 하니스 런 비용의 거의 전부가 관측 밖이었다). 곁가지와 같은 모양 ·
         //   모르는 모델은 금액 대신 `cost.kind='unknown'`. runId 는 debug.log 가 붙인다. 실패해도 턴은 계속.
@@ -11552,6 +11702,8 @@ export async function streamLLMWithTools(
           history,
           turn,
           modelFamily,
+          ...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+          tools: activeTools,
           // Live progressive streaming — deltas emit through handlers
           // during collection so TUI shows synthesis text as it
           // generates instead of one big chunk at the end.
@@ -12198,6 +12350,7 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
           acceptToolImages: codexAcceptToolImages,
           acceptUserMessageImages: codexAcceptUserImages,
           replayCodexReasoning: !useStore,
+          stablePrefix: true,
           onOrphanToolResult: (callId) => {
             try { debug.log('llm.codex', 'orphan-tool-output-dropped', { callId }); }
             catch { /* observation must not block the request */ }
@@ -12254,6 +12407,7 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
           ? messagesToResponsesInput(messages, {
               acceptToolImages: codexAcceptToolImages,
               acceptUserMessageImages: codexAcceptUserImages,
+              stablePrefix: true,
             }).input
           : input);
         const wirePrevId = (delta && lastResponseId) ? lastResponseId : undefined;
@@ -12274,9 +12428,12 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
         };
         const requestGuard = opts.requestSizeGuard;
         const promptCache = opts.promptCache !== false;
+        // TUI-PROMPT-CACHE-PREFIX — the preflight must measure the same body
+        // streamCodexResponsesEvents would build (session-derived key).
+        const sessionCacheKey = codexSessionCacheKey(opts.sessionId, process.env.ELANOUS_RUN_ID)?.key;
         let serializedWireBody: string | undefined;
         if (requestGuard) {
-          serializedWireBody = serializeCodexResponsesWireBody(requestBody, promptCache);
+          serializedWireBody = serializeCodexResponsesWireBody(requestBody, promptCache, sessionCacheKey);
           let requestChars = serializedWireBody.length;
           const initialRequestChars = requestChars;
           let requestCompacted = false;
@@ -12295,9 +12452,10 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
                   // Compaction runs only when store threading is off, matching
                   // the original non-threaded wire input policy.
                   replayCodexReasoning: !useStore,
+                  stablePrefix: true,
                 });
                 const compactBody = { ...requestBody, instructions: compactInput.instructions, input: compactInput.input };
-                const compactWireBody = serializeCodexResponsesWireBody(compactBody, promptCache);
+                const compactWireBody = serializeCodexResponsesWireBody(compactBody, promptCache, sessionCacheKey);
                 const compactChars = compactWireBody.length;
                 if (compactChars < requestChars) {
                   messages.splice(0, messages.length, ...compacted.messages);
@@ -12341,6 +12499,7 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
         yield* streamCodexResponsesEvents(responsesUrl, tokens.accessToken, requestBody, opts.signal, {
           accountId,
           promptCache,
+          ...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
           ...(serializedWireBody ? { serializedWireBody } : {}),
           // Capture the new response id from the SSE stream so the
           // next call can thread it. If the backend skips the event

package/src/loops/orchestrator/coordinator-shadow.ts

@@ -0,0 +1,226 @@
+/**
+ * COORD-ENTRANCE-FOLD · 0.2.42 칸 · TASK-AGENT(OP 디스패처) — 셸 디스패처 은퇴 결정 카드.
+ *
+ * 배경: 대표 10-19 «중간층(런 닥터 r3·rework · 입구 디스패처)이 0.2.35 최우선 병목» ·
+ * seat-state/OP/PLAN-mid-tier-loops-2026-10-19.md §5.
+ *
+ * 판정 신호: 조율자 그림자가 ④ 빌더로 같은 칸·같은 지시서를 달력 기준 3일 연속
+ * 디스패치하면 «셸 디스패처 은퇴» 결정 카드를 기존 결정 원장(src/decisions/decision-ledger.ts,
+ * `decisions/decisions.jsonl`) 부가 형식 그대로 정확히 1장 올린다.
+ *
+ * 그림자 디스패치 원장(<root>/seat-state/OP/coordinator-shadow-dispatch.jsonl)은
+ * 조율자 그림자 디스패처가 한 줄씩 적는 JSONL 이다:
+ *   {"date":"2026-03-02","agent":"builder-4","cell":"src/x/y.ts","directive":"DIR-123"}
+ * (별칭 허용: date=day · agent=target · cell=lane · directive=directiveId)
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DecisionLedger } from '../../decisions/decision-ledger.js';
+import { withFileLockSync } from '../../storage/file-lock.js';
+import { findGitDir } from '../../git-fs/locate.js';
+
+export interface CoordinatorShadowDispatch {
+  /** 달력 날짜(YYYY-MM-DD, 생산 기록은 UTC ISO 날짜). */
+  date: string;
+  /** 대상 에이전트(예: builder-4). */
+  agent: string;
+  /** 작업을 받은 과제 소유 seat (`tasks hand --seat`). */
+  recipient?: string;
+  /** 칸(대상 경로). */
+  cell: string;
+  /** 지시서 id. */
+  directive: string;
+}
+
+export interface CoordinatorShadowStreak {
+  agent: string;
+  recipient?: string;
+  cell: string;
+  directive: string;
+  /** 연속을 이룬 세 달력 날짜(직전2일·오늘, 오름차순). */
+  dates: [string, string, string];
+}
+
+export interface CoordinatorShadowTickOptions {
+  /** 저장소/worktree 루트 — 그림자 디스패치 원장 기준 경로. 생산 기본: cwd 트리. */
+  root?: string;
+  /** 결정 원장 stateDir. 생산 기본: elanousStateRoot(). */
+  stateDir?: string;
+  /** 시계 주입(생산: 실제 Date). */
+  now?: () => Date;
+  /** 원장 행 직접 주입(시험용 — 생산 호출 경로는 그대로 지나간다). */
+  dispatches?: CoordinatorShadowDispatch[];
+}
+
+export interface CoordinatorShadowTickResult {
+  /** 판정 기준일(YYYY-MM-DD). */
+  checked: string;
+  evidence: CoordinatorShadowStreak | null;
+  /** 올라간(또는 이미 있던) 결정 카드 id. */
+  cardId?: string;
+  /** 같은 스탬프(칸+지시서+마지막 날) 카드가 이미 있어 1장만 유지됐을 때. */
+  skipped?: 'duplicate';
+}
+
+/** 그림자 디스패치 원장 생산 기본 경로. */
+export function coordinatorShadowJournalPath(root: string): string {
+  return join(root, 'seat-state', 'OP', 'coordinator-shadow-dispatch.jsonl');
+}
+
+/** Resolve the containing checkout when the CLI was started from a repository subdirectory. */
+export function resolveCoordinatorShadowRoot(cwd = process.cwd()): string {
+  return findGitDir(cwd)?.root ?? cwd;
+}
+
+/** launcher가 work-order를 받아들인 뒤 그림자 근거만 덧붙인다. 발사 결정·인자는 읽거나 바꾸지 않는다. */
+export function recordCoordinatorShadowDispatch(
+  root: string,
+  row: CoordinatorShadowDispatch,
+): void {
+  const path = coordinatorShadowJournalPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  withFileLockSync(`${path}.lock`, () => appendFileSync(path, `${JSON.stringify(row)}\n`));
+}
+
+/** ④ 빌더 판별 — «빌더④» «④빌더» «builder-4» «builder_4» «builder 4» «b4» 계열을 받는다. */
+function fourthBuilderAgentKey(agent: string): string | null {
+  const key = agent.normalize('NFC').replace(/\s+/g, '').toLowerCase();
+  return /^(?:builder|b)[-_]?4$/.test(key) || /^④?빌더4$/.test(key) || key === '④빌더' || key === '빌더④'
+    ? 'builder-4'
+    : null;
+}
+
+export function isFourthBuilderAgent(agent: string): boolean {
+  return fourthBuilderAgentKey(agent) !== null;
+}
+
+function shiftDay(isoDay: string, delta: number): string {
+  const date = new Date(`${isoDay}T00:00:00Z`);
+  date.setUTCDate(date.getUTCDate() + delta);
+  return date.toISOString().slice(0, 10);
+}
+
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * 조율자 그림자 디스패치 기록에서 오늘과 직전 2일치를 읽어,
+ * 대상이 ④ 빌더이고 칸·지시서가 같은 달력 기준 3일 연속인 모든 쌍을 반환한다.
+ * 연속 끊김(칸·지시서·대상이 다르거나 하루 무디스패치)이면 해당 streak 는 성립하지 않는다.
+ */
+export function detectBuilderThreeDayStreak(
+  dispatches: readonly CoordinatorShadowDispatch[],
+  today: string,
+): CoordinatorShadowStreak | null {
+  return detectBuilderThreeDayStreaks(dispatches, today)[0] ?? null;
+}
+
+/** 오늘의 3일 창에서 모든 적격 (agent, cell, directive) 쌍을 돌려 각 쌍의 카드를 독립 판정한다. */
+export function detectBuilderThreeDayStreaks(
+  dispatches: readonly CoordinatorShadowDispatch[],
+  today: string,
+): CoordinatorShadowStreak[] {
+  if (!DAY_PATTERN.test(today)) throw new Error(`calendar day required: ${today}`);
+  const window: [string, string, string] = [shiftDay(today, -2), shiftDay(today, -1), today];
+  const groups = new Map<string, { agent: string; recipient?: string; recipientDate?: string; cell: string; directive: string; days: Set<string> }>();
+  for (const row of dispatches) {
+    if (!row || typeof row.date !== 'string' || !DAY_PATTERN.test(row.date)) continue;
+    const builderKey = fourthBuilderAgentKey(String(row.agent ?? ''));
+    if (!builderKey) continue;
+    const recipient = typeof row.recipient === 'string' ? row.recipient : undefined;
+    const cell = String(row.cell ?? '');
+    const directive = String(row.directive ?? '');
+    if (!cell || !directive) continue;
+    const key = `${builderKey}\u0000${cell}\u0000${directive}`;
+    const group = groups.get(key) ?? { agent: row.agent, cell, directive, days: new Set<string>() };
+    if (recipient && window.includes(row.date as typeof window[number])
+      && (!group.recipientDate || row.date >= group.recipientDate)) {
+      group.recipient = recipient;
+      group.recipientDate = row.date;
+    }
+    group.days.add(row.date);
+    groups.set(key, group);
+  }
+  const keys = [...groups.keys()].sort();
+  return keys.flatMap(key => {
+    const group = groups.get(key)!;
+    return window.every(day => group.days.has(day))
+      ? [{ agent: group.agent, ...(group.recipient ? { recipient: group.recipient } : {}), cell: group.cell, directive: group.directive, dates: [...window] as [string, string, string] }]
+      : [];
+  });
+}
+
+function readDispatchJournal(path: string): CoordinatorShadowDispatch[] {
+  if (!existsSync(path)) return [];
+  const rows: CoordinatorShadowDispatch[] = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let raw: Record<string, unknown>;
+    try { raw = JSON.parse(line) as Record<string, unknown>; } catch { continue; }
+    // JSON.parse 가 성공하는 비객체 행(`null`·스칼라 등)도 파손 행이다 — 판독에서 건너뛴다.
+    if (typeof raw !== 'object' || raw === null) continue;
+    const date = raw.day ?? raw.date;
+    const agent = raw.target ?? raw.agent;
+    const recipient = raw.recipient ?? raw.seat;
+    const cell = raw.lane ?? raw.cell;
+    const directive = raw.directiveId ?? raw.directive;
+    if (typeof date === 'string' && typeof agent === 'string' && typeof cell === 'string' && typeof directive === 'string') {
+      rows.push({ date, agent, ...(typeof recipient === 'string' ? { recipient } : {}), cell, directive });
+    }
+  }
+  return rows;
+}
+
+/** «셸 디스패처 은퇴» 결정 카드의 영구 idempotency ref(같은 칸+지시서에는 한 장만). */
+export function retirementCardStamp(evidence: CoordinatorShadowStreak): string {
+  return `coordinator-shadow-streak:${evidence.cell}:${evidence.directive}`;
+}
+
+/**
+ * 조율자 루프의 하루 틱 — 그림자 디스패치 3일 연속 판정 → 셸 디스패처 은퇴 결정 카드 1장.
+ * 카드는 기존 결정 원장(DecisionLedger.raise) 부가 형식 그대로 append 되고,
+ * 같은 3일 창에서 성립한 모든 칸+지시서 쌍을 각자 판정하고, 카드가 이미 있으면 재사용한다.
+ * (날짜가 바뀌어도 쌍마다 1장 유지).
+ */
+export async function tick(options: CoordinatorShadowTickOptions = {}): Promise<CoordinatorShadowTickResult> {
+  const root = resolveCoordinatorShadowRoot(options.root ?? process.cwd());
+  const now = options.now ?? (() => new Date());
+  const dispatches = options.dispatches ?? readDispatchJournal(coordinatorShadowJournalPath(root));
+  const today = now().toISOString().slice(0, 10);
+  const evidences = detectBuilderThreeDayStreaks(dispatches, today);
+  const evidence = evidences[0] ?? null;
+  if (!evidence) return { checked: today, evidence: null };
+
+  const ledger = new DecisionLedger({ ...(options.stateDir ? { stateDir: options.stateDir } : {}), now, repoRoot: root });
+  const outcomes = evidences.map(item => {
+    const stamp = retirementCardStamp(item);
+    const alreadyRaised = ledger.list({ status: 'all' }).some(entry =>
+      Array.isArray(entry.refs) && entry.refs.includes(stamp));
+    const entry = ledger.raiseOnce({
+      title: `셸 디스패처 은퇴 — ${item.cell} × ${item.directive} 3일 연속`,
+      category: 'other',
+      scqa: {
+        s: '조율자 그림자가 ④ 빌더로 같은 칸·같은 지시서를 달력 기준 3일 연속 디스패치했다.',
+        c: '중간층 입구 디스패처가 같은 지시를 반복 산출하는 0.2.35 최우선 병목 신호가 실측됐다.',
+        q: '셸 디스패처를 은퇴시키고 입구를 조율자 그림자로 고정할까?',
+        a: '셸 디스패처 은퇴 결정 카드를 원장에 올리고 후속 조치를 연다.',
+      },
+      options: [
+        { key: 'a', label: '은퇴 승인', consequence: '입구 디스패처를 조율자 그림자로 고정하고 셸 디스패처를 은퇴시킨다' },
+        { key: 'b', label: '관찰 연장', consequence: '은퇴를 보류하고 3일 연속 판정 관찰을 계속한다' },
+      ],
+      recommendation: { option: 'a', why: '같은 칸·같은 지시서가 달력 기준 3일 연속 — 판정 신호 충족' },
+      raisedBy: { agent: 'orchestrator-tick', track: 'OP' },
+      refs: [
+        stamp,
+        `agent:${item.agent}`,
+        ...(item.recipient ? [`recipient:${item.recipient}`] : []),
+        `cell:${item.cell}`,
+        `directive:${item.directive}`,
+        `dates:${item.dates.join(',')}`,
+      ],
+    }, stamp);
+    return { evidence: item, cardId: entry.id, alreadyRaised };
+  });
+  return { checked: today, evidence, cardId: outcomes[0]!.cardId,
+    ...(outcomes.every(outcome => outcome.alreadyRaised) ? { skipped: 'duplicate' as const } : {}) };
+}

package/src/loops/orchestrator/tick.ts

@@ -1062,6 +1062,13 @@ export async function degradationDeps(node: Node, deps: { config?: () => Partial
   return mode === 'live' ? { degradation: () => ({ llm: signal.llm, board: signal.board }) } : {};
 }
 
+// COORD-ENTRANCE-FOLD (0.2.42 칸 · TASK-AGENT OP 디스패처) — 조율자 루프 하루 틱 생산 진입이
+// tick() 을 호출하게 배선한다: 그림자 디스패치(날짜·대상 에이전트·칸·지시서 id)에서 ④ 빌더
+// 같은 칸·같은 지시서 달력 기준 3일 연속을 감지하면 «셸 디스패처 은퇴» 결정 카드를 기존 결정
+// 원장(DecisionLedger) 부가 형식 그대로 1장 적는다(같은 스탬프=칸+지시서 중복 방지).
+// 구현 본체: src/loops/orchestrator/coordinator-shadow.ts · 완료 경계 시험: tick.test.ts.
+import { tick as runCoordinatorShadowTick } from './coordinator-shadow.js';
+
 if (import.meta.main) {
   const node = process.argv[2];
   const index = process.argv.indexOf('--window');
@@ -1078,6 +1085,12 @@ if (import.meta.main) {
     void (async () => {
       try { await (await import('../../domains/standalone-log-sink.js')).registerStandaloneLogSink('orchestrator'); }
       catch { /* local execution can still use the per-run file */ }
+      // 관측(그림자 틱)은 본 루프를 봉쇄할 수 없다: 파손 원장 등으로 reject 하면 원인만 warn 로그로 남기고 본 노드 실행은 계속한다.
+      try { await runCoordinatorShadowTick({}); }
+      catch (error) {
+        try { debug.log('loop.orchestrator', 'coordinator-shadow-tick-failed', { node, error: String(error).slice(0, 200) }, { level: 'warn' }); }
+        catch { /* even the diagnostic sink must not block the node */ }
+      }
       await runOrchestratorNode(node as Node, { window: window as Window | undefined, ...await degradationDeps(node as Node) });
     })().catch(error => { console.error(`orchestrator ${node}: ${String(error)}`); process.exitCode = 1; });
   }

package/src/maturity/feature-maturity.ts

@@ -59,10 +59,10 @@ export const FEATURE_MATURITY = {
   },
   // Canonical CLI command names only; aliases inherit their command's grade.
   cliRoot: {
-    preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta',
+    preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta', catalog: 'beta',
     where: 'stable', bench: 'beta', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', herdr: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', life: 'beta', freeze: 'beta', herdr: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', resource: 'beta', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',
@@ -77,12 +77,12 @@ export const FEATURE_MATURITY = {
     'provider:rotate': 'beta', 'provider:use': 'beta', 'status-bar': 'beta',
     schedule: 'beta', guardian: 'beta', intake: 'beta', logs: 'stable', retro: 'beta', ad: 'beta', docs: 'beta',
     decisions: 'beta', directives: 'beta', claims: 'beta', lesson: 'beta', fleet: 'beta', ops: 'stable', outputs: 'beta', publish: 'beta',
-    env: 'beta', 'agent-mission': 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
+    env: 'beta', 'agent-mission': 'beta', mission: 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
     config: 'stable', tasks: 'stable', brief: 'beta', notify: 'beta', away: 'beta', labels: 'beta', msg: 'beta', ask: 'stable',
     onboarding: 'beta', login: 'stable', session: 'beta', chat: 'stable', repl: 'stable',
     agent: 'stable', registry: 'beta', tier: 'stable', local: 'beta', scheduler: 'beta',
     attach: 'beta', wf: 'beta', nexus: 'stable', phone: 'beta', token: 'beta',
-    acp: 'beta', voice: 'beta', sim: 'beta',
+    acp: 'beta', voice: 'beta', sim: 'beta', tui: 'system',
     'run-detached': 'system', dogfood: 'system', run: 'system',
   },
   // Canonical names only; aliases inherit their command's grade at lookup.