elanous 0.2.6 → 0.2.8

package/src/acp/server.ts

@@ -26,6 +26,7 @@
 //
 // Related: src/acp/client.ts (elanous-as-client path — pre-MT5 work).
 
+import { ACP_LOGIN_METHOD_ID, acpAuthMethods } from './auth-methods.js';
 import { AgentSideConnection, ndJsonStream, RequestError } from '@agentclientprotocol/sdk';
 import type {
   InitializeRequest, InitializeResponse,
@@ -66,6 +67,7 @@ import {
   type ElanousTermPayload,
 } from './elanous-extensions.js';
 import { createMissionTurnEmitter } from './mission-turn-emit.js';
+import { ElanousAwarePeers } from './elanous-aware-peers.js';
 import { enqueuePendingUserInput } from '../session/pending-input.js';
 import {
   ELANOUS_ASK_CANCEL_METHOD,
@@ -879,6 +881,10 @@ let activeAcpBroadcaster:
   | ((sessionId: string, update: unknown) => Promise<{ delivered: number }>)
   | null = null;
 
+let activeAcpFeedbackBroadcaster:
+  | ((sessionId: string, env: FeedbackEnvelope) => Promise<{ delivered: number }>)
+  | null = null;
+
 // P0b(DESIGN-cross-surface-autonomy-membrane §10) — ACP ask pusher(elanous/ask → iPhone/PWA 시트)를 모듈-레벨로
 // 노출. daemon-runtime 이 코어 데몬 턴(SelfImplement dispatch)에 SurfaceUx confirm/question 채널을 주입할 때
 // createAcp*Channel(sessionId, getActiveAcpAskPusher()) 로 사용. sessionPeers 로 라우팅(연결 무관)·fail-soft(null=drop).
@@ -894,8 +900,8 @@ export function getActiveAcpBroadcaster():
 }
 
 /** PLAN-ios-rich-dev-feedback-hydrate · M1-S (2026-05-13) — typed
- *  adapter on top of `activeAcpBroadcaster` that fans out a
- *  `FeedbackEnvelope` as a `elanous/feedback/emit` envelope packaged
+ *  adapter that fans out a `FeedbackEnvelope` only to peers advertising
+ *  `_meta.elanous`, as a `elanous/feedback/emit` envelope packaged
  *  inside an `agent_thought_chunk` sessionUpdate.
  *
  *  Why `agent_thought_chunk` instead of a native `sessionUpdate:
@@ -912,15 +918,7 @@ export function getActiveAcpBroadcaster():
 export function getActiveAcpFeedbackBroadcaster():
   | ((sessionId: string, env: FeedbackEnvelope) => Promise<{ delivered: number }>)
   | null {
-  const inner = activeAcpBroadcaster;
-  if (!inner) return null;
-  return (sessionId, env) => {
-    const text = formatElanousFeedbackEnvelope({ method: 'emit', payload: env });
-    return inner(sessionId, {
-      sessionUpdate: 'agent_thought_chunk',
-      content: { type: 'text', text },
-    });
-  };
+  return activeAcpFeedbackBroadcaster;
 }
 
 /** PLAN-ios-rich-dev-feedback-hydrate M4 (HUD) — fan-out across ALL
@@ -989,6 +987,9 @@ interface AcpServerContext {
    *  fan-out walks the set so multi-surface clients (e.g. web PWA
    *  + TUI on the same id) all see the same stream. */
   sessionPeers: Map<string, Set<SessionPeer>>;
+  awarePeers: ElanousAwarePeers<SessionPeer>;
+  /** One skip diagnostic per session, cleared when its last peer leaves. */
+  plainEnvelopeLogged: Set<string>;
   dualRole: DualRoleManager;
   /** Mints the unique suffix of a new session id. Injected so tests can
    *  pin it deterministically — production wires `mintAcpSessionToken`. */
@@ -1029,6 +1030,21 @@ interface SessionPeer {
   peerId: string | null;
 }
 
+function isFeedbackTextUpdate(update: unknown): boolean {
+  if (!update || typeof update !== 'object') return false;
+  const u = update as { sessionUpdate?: unknown; content?: { type?: unknown; text?: unknown } };
+  return u.sessionUpdate === 'agent_thought_chunk'
+    && u.content?.type === 'text'
+    && typeof u.content.text === 'string'
+    && u.content.text.startsWith('[elanous/feedback/emit] ');
+}
+
+function logSkippedPlainEnvelope(ctx: AcpServerContext, sessionId: string, kind: string): void {
+  if (ctx.plainEnvelopeLogged.has(sessionId)) return;
+  ctx.plainEnvelopeLogged.add(sessionId);
+  debug.log('acp.envelope', 'skipped-plain-client', { sessionId, kind });
+}
+
 /** Wire a single `AgentSideConnection` onto the provided ndJsonStream.
  *  Owns all per-connection state (clientUiCaps, boundConnection ref,
  *  per-peer `AcpServerHandle`) so stdio and transport paths diverge
@@ -1038,7 +1054,7 @@ function wireAcpConnection(
   stream: ReturnType<typeof ndJsonStream>,
   ctx: AcpServerContext,
 ): AgentSideConnection {
-  const { sessions, sessionPeers, dualRole, opts } = ctx;
+  const { sessions, sessionPeers, awarePeers, plainEnvelopeLogged, dualRole, opts } = ctx;
   // 2026-05-13 (M2 of AskUserQuestion cross-surface) — bound connection
   // widened to expose `extMethod` + `extNotification` (SDK's elanous
   // extension escape hatch). pushAskRequest / pushAskCancel route through
@@ -1132,6 +1148,10 @@ function wireAcpConnection(
       }
       return { delivered: 0 };
     }
+    if (isFeedbackTextUpdate(update) && !awarePeers.isElanousAware(sessionId)) {
+      logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+      return { delivered: 0 };
+    }
     let delivered = 0;
     let dedupedByPeerId = 0;
     const tasks: Promise<unknown>[] = [];
@@ -1141,6 +1161,10 @@ function wireAcpConnection(
     // 은 모두 distinct peer 으로 취급해 send (degraded compat).
     const seenPeerIds = new Set<string>();
     for (const p of peers) {
+      if (isFeedbackTextUpdate(update) && !awarePeers.isPeerAware(p)) {
+        logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+        continue;
+      }
       if (opts2?.uiGate && !p.getUiCaps()[opts2.uiGate]) continue;
       if (opts2?.termGate && !p.getTermCaps()[opts2.termGate]) continue;
       if (p.peerId !== null) {
@@ -1380,6 +1404,7 @@ function wireAcpConnection(
       clientUiCaps = parsed.ui;
       clientTermCaps = parsed.term;
       clientAskCaps = parsed.ask;
+      awarePeers.markPeer(peer, req.clientCapabilities);
       debug.log('acp.session', 'initialize', {
         protocolVersion: req.protocolVersion,
         clientName: req.clientInfo?.name ?? 'absent',
@@ -1391,14 +1416,13 @@ function wireAcpConnection(
         agentCapabilities: opts.agentBrand !== undefined && opts.agentModel !== undefined
           ? buildAgentDeclaration({ brand: opts.agentBrand, model: opts.agentModel })
           : buildAgentDeclaration(),
-        authMethods: [],
+        authMethods: acpAuthMethods(req.clientCapabilities),
       };
     },
 
-    async authenticate(_req: AuthenticateRequest): Promise<AuthenticateResponse> {
-      // No auth flow — we advertise authMethods: [] so the client
-      // shouldn't call this, but the Agent interface requires the
-      // method to be present.
+    async authenticate(req: AuthenticateRequest): Promise<AuthenticateResponse> {
+      // EN10a — sign-in happens in a terminal (`--acp-server --login`); this only acknowledges the method so the client retries.
+      debug.log('acp.session', 'authenticate', { methodId: req.methodId === ACP_LOGIN_METHOD_ID ? req.methodId : 'other' });
       return {};
     },
 
@@ -3316,7 +3340,10 @@ function wireAcpConnection(
       if (!set) continue;
       set.delete(peer);
       const remaining = set.size;
-      if (remaining === 0) sessionPeers.delete(sid);
+      if (remaining === 0) {
+        sessionPeers.delete(sid);
+        plainEnvelopeLogged.delete(sid);
+      }
       if (debug.enabled) {
         debug.log('acp.peer.unregister', sid, { remainingPeers: remaining });
       }
@@ -3451,10 +3478,14 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
     return true;
   });
   const sessionPeers = new Map<string, Set<SessionPeer>>();
+  const awarePeers = new ElanousAwarePeers(sessionPeers);
+  const plainEnvelopeLogged = new Set<string>();
   const dualRole = opts.dualRoleManager ?? globalDualRoleManager();
   const ctx: AcpServerContext = {
     sessions,
     sessionPeers,
+    awarePeers,
+    plainEnvelopeLogged,
     dualRole,
     nextSessionToken: mintAcpSessionToken,
     agentName: opts.agentName ?? 'elanous-agent',
@@ -3478,9 +3509,17 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
       }
       return { delivered: 0 };
     }
+    if (isFeedbackTextUpdate(update) && !awarePeers.isElanousAware(sessionId)) {
+      logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+      return { delivered: 0 };
+    }
     const tasks: Promise<unknown>[] = [];
     let delivered = 0;
     for (const p of peers) {
+      if (isFeedbackTextUpdate(update) && !awarePeers.isPeerAware(p)) {
+        logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+        continue;
+      }
       delivered += 1;
       tasks.push(p.sessionUpdate({ sessionId, update }));
     }
@@ -3496,19 +3535,52 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
     await Promise.allSettled(tasks);
     return { delivered };
   };
+  activeAcpFeedbackBroadcaster = async (sessionId, env) => {
+    const text = formatElanousFeedbackEnvelope({ method: 'emit', payload: env });
+    const peers = sessionPeers.get(sessionId);
+    if (!peers || peers.size === 0) return { delivered: 0 };
+    if (!awarePeers.isElanousAware(sessionId)) {
+      logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+      return { delivered: 0 };
+    }
+    let delivered = 0;
+    const tasks: Promise<unknown>[] = [];
+    for (const peer of peers) {
+      if (!awarePeers.isPeerAware(peer)) {
+        logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+        continue;
+      }
+      delivered += 1;
+      tasks.push(peer.sessionUpdate({
+        sessionId,
+        update: { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text } },
+      }));
+    }
+    await Promise.allSettled(tasks);
+    return { delivered };
+  };
   // PLAN-ios-rich-dev-feedback-hydrate M4 (2026-05-13) — all-sessions
   // fan-out for process-wide envelope kinds (hud.segment). Iterates
-  // sessionPeers + delegates each session to activeAcpBroadcaster
+  // sessionPeers and gates each attached connection independently
   // (consistent transport · same agent_thought_chunk text-in-text shape).
   activeAcpAllSessionsFeedbackBroadcaster = async (envProto) => {
     let fannedTo = 0;
     let delivered = 0;
     for (const [sessionId, peers] of sessionPeers) {
       if (peers.size === 0) continue;
-      fannedTo += 1;
+      if (!awarePeers.isElanousAware(sessionId)) {
+        logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+        continue;
+      }
       const env = { ...envProto, sessionId } as FeedbackEnvelope;
       const text = formatElanousFeedbackEnvelope({ method: 'emit', payload: env });
+      let any = false;
       for (const peer of peers) {
+        if (!awarePeers.isPeerAware(peer)) {
+          logSkippedPlainEnvelope(ctx, sessionId, 'feedback');
+          continue;
+        }
+        any = true;
         try {
           await peer.sessionUpdate({
             sessionId,
@@ -3522,6 +3594,7 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
           /* swallow — best-effort fan-out */
         }
       }
+      if (any) fannedTo += 1;
     }
     return { delivered, fannedTo };
   };
@@ -3593,6 +3666,7 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
       try { await transport.close(); } catch { /* ignore */ }
       acpServerDisposeSessions(sessions, dualRole);
       activeAcpBroadcaster = null;
+      activeAcpFeedbackBroadcaster = null;
       activeAcpAskPusher = null;
       activeAcpAllSessionsFeedbackBroadcaster = null;
       activeAcpAllSessionsTermFrameBroadcaster = null;
@@ -3621,7 +3695,9 @@ export async function runAcpServer(opts: AcpServerOptions = {}): Promise<void> {
   } finally {
     acpServerDisposeSessions(sessions, dualRole);
     activeAcpBroadcaster = null;
+    activeAcpFeedbackBroadcaster = null;
     activeAcpAskPusher = null;
+    activeAcpAllSessionsFeedbackBroadcaster = null;
     activeAcpAllSessionsTermFrameBroadcaster = null;
     if (debug.enabled) {
       debug.log('acp.broadcaster.lifecycle', 'clear', { mode: 'stdio' });

package/src/agent/monad-agent-turn.ts

@@ -30,6 +30,7 @@ import { surfaceEventsDbPath, openSurfaceEventsDb, recentSentDigest, recordInbou
 import { elanousSelfAccessPrompt, elanousSelfAmbientParts } from './self-ambient.js';
 import { localRefGroundingAmbient } from './ref-grounding.js';
 import { resolveRouteDecision } from '../llm/route-decision.js';
+import { explicitTurnTier } from '../model-tier/turn-tier.js';
 import type { RouteDecision } from '../llm/route-decision.js';
 import { debug } from '../debug/log.js';
 import { setEventLoopActivity } from '../debug/event-loop-watchdog.js';
@@ -59,7 +60,7 @@ function recentSentContext(): string {
  *  Bash + PtyShell + search), plus — when the finance domain pack is
  *  enabled (A0) — the analyst orientation + resource map + first-class
  *  finance tools. Drop-in for the hosting bot's `runTurnImpl`. */
-export function makeElanousAgentRunTurn(cfg: UserConfig, surface: SessionSource): typeof runTurn {
+export function makeElanousAgentRunTurn(cfg: UserConfig, surface: SessionSource, runTurnImpl: typeof runTurn = runTurn): typeof runTurn {
   if (surface !== 'telegram' && surface !== 'discord') {
     throw new Error(`Unsupported elanous agent session source: ${surface}`);
   }
@@ -110,7 +111,13 @@ export function makeElanousAgentRunTurn(cfg: UserConfig, surface: SessionSource)
     // ⛔ 호출자가 모델을 핀했으면 «건드리지 않는다». 실패는 fail-soft — config 기본을 유지한다.
     let llmOpts = opts.llmOpts;
     let routeDecision: RouteDecision | undefined;
-    if (cfg.llm.provider === 'openai-codex') {
+    const explicitTier = opts.llmOpts?.model ? undefined : explicitTurnTier(cfg, opts.sessionId);
+    if (cfg.llm.provider === 'openai-codex' && explicitTier) {
+      llmOpts = { ...(llmOpts ?? {}), model: explicitTier.model };
+      debug.log('llm.route-decision', 'self-turn', {
+        surface, provider: cfg.llm.provider, model: explicitTier.model, skipped: 'explicit-tier',
+      });
+    } else if (cfg.llm.provider === 'openai-codex') {
       try {
         const decision = resolveRouteDecision({
           provider: cfg.llm.provider,
@@ -212,8 +219,19 @@ export function makeElanousAgentRunTurn(cfg: UserConfig, surface: SessionSource)
       ...(surfaceFileSink ? { fileSink: surfaceFileSink } : {}),
     });
     llmOpts = terminal.llmOpts;
-    return runTurn({
+    let currentMessage = '';
+    let sawToolCall = false;
+    return runTurnImpl({
       ...opts,
+      onDelta: (delta) => {
+        currentMessage += delta;
+        opts.onDelta?.(delta);
+      },
+      onToolCall: (call) => {
+        currentMessage = '';
+        sawToolCall = true;
+        opts.onToolCall?.(call);
+      },
       llmOpts,
       systemPrompt: terminal.systemPromptParts.join('\n\n'),
       tools: terminal.specs,
@@ -226,11 +244,12 @@ export function makeElanousAgentRunTurn(cfg: UserConfig, surface: SessionSource)
       // NEXT turn's memory_recall knows the task was CANCELLED, not silently
       // dropped or still running. Only turnAbort (=/cancel) aborts this signal.
       const wasAborted = opts.signal?.aborted === true;
+      const answer = sawToolCall ? currentMessage.trim() : result.text;
       const responseText = wasAborted
-        ? (result.text?.trim()
-            ? `${result.text}\n\n⏹️ 이 작업은 /cancel 로 취소되었습니다 (실행 중이던 Bash/PTY 종료됨).`
+        ? (answer?.trim()
+            ? `${answer}\n\n⏹️ 이 작업은 /cancel 로 취소되었습니다 (실행 중이던 Bash/PTY 종료됨).`
             : '⏹️ 작업이 /cancel 로 취소되었습니다. 실행 중이던 Bash/PTY 를 종료했습니다.')
-        : result.text;
+        : answer;
       // Block 3 — 대화 턴을 크로스서피스 기억에 기록(질의+응답·direction=inbound).
       // fail-soft·비동기(대화 지연 없음). 이후 memory_recall 이 과거 대화도 회상.
       try { recordInboundTurn({ surface, userText: opts.userText, responseText, sessionId: opts.sessionId }); } catch { /* noop */ }

package/src/agent/shared-app-tools.ts

@@ -12,6 +12,7 @@
 //   financeEnabled(cfg) 게이트(operator opt-in·미enable/미cfg 시 core 만·무회귀).
 
 import { buildCoreTools } from '../domains/core-tools.js';
+import type { ToolRuntimeContext } from '../tool-runtime/types.js';
 import { buildFinanceTools } from '../domains/finance-tools.js';
 import { financeEnabled } from '../domains/finance.js';
 import { skillExecRuntime } from '../tool-runtime/skill-exec-runtime.js';
@@ -24,7 +25,7 @@ import type { LLMToolSpec } from '../llm.js';
 export interface SharedAppTools {
   specs: LLMToolSpec[];
   names: Set<string>;
-  dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  dispatch: (name: string, args: Record<string, unknown>, context?: ToolRuntimeContext) => Promise<unknown>;
 }
 
 /** L2 core + L3 finance(gated) + skill discovery/execution 단일 조립. specs 순서 = core, finance, discovery, execution. */
@@ -35,9 +36,10 @@ export function buildSharedAppTools(cfg?: UserConfig): SharedAppTools {
   const skill = skillExecRuntime;
   const specs: LLMToolSpec[] = [...core.specs, ...(fin ? fin.specs : []), skillsList, skill.spec];
   const names = new Set<string>([...core.names, ...(fin ? fin.names : []), skillsList.name, skill.id]);
-  const dispatch = async (name: string, args: Record<string, unknown>): Promise<unknown> =>
+  // context(B5) — 기억 조회 같은 긴 코어 도구가 진행 한 줄(emitFeedback)을 낼 수 있게 코어까지 넘긴다.
+  const dispatch = async (name: string, args: Record<string, unknown>, context?: ToolRuntimeContext): Promise<unknown> =>
     name === skillsList.name ? dispatchElanousSkillsList(args as ElanousSkillsListArgs) :
       name === skill.id ? skill.run(args as unknown as SkillExecArgs, { surface: 'skill' }) :
-        fin && fin.names.has(name) ? fin.dispatch(name, args) : core.dispatch(name, args);
+        fin && fin.names.has(name) ? fin.dispatch(name, args) : core.dispatch(name, args, undefined, context);
   return { specs, names, dispatch };
 }

package/src/agent-substrate/review-intent.ts

@@ -16,6 +16,7 @@ import { parseGoalType, type GoalType } from '../self-implement/goal-author.js';
 import type { DesignCheckOutcome } from '../design/design-check.js';
 import type { DesignGateResult } from '../design/design-gate.js';
 import type { PriorDraftFinding } from '../self-implement/prior-draft-findings.js';
+import { parseShardIdentity, shardBoundaryBlock, withoutShardIdentity } from './shard-boundary-intent.js';
 
 export interface ReviewIntentInput {
   /** 무엇을 왜 — 골 원문. */
@@ -534,7 +535,9 @@ export function buildReviewIntent(i: Readonly<ReviewIntentInput>): string {
   // ⚠️ 목표 블록에는 **추출된 절을 뺀 나머지**를 넣는다(리뷰 should-fix) — 골 원문을 통째로 넣고
   //   그 안의 수용기준을 다시 목록으로 붙이면 **같은 내용이 두 번** 들어가 4000자 예산을 먹고,
   //   후순위 블록(스코프 경계)이 불필요하게 잘린다.
-  const goalBody = stripExtractedSections(i.goal).trim();
+  const identity = parseShardIdentity(i.goal);
+  const shardBoundary = identity ? { title: '조각 경계', text: `조각 경계\n${shardBoundaryBlock(identity)}` } : undefined;
+  const goalBody = stripExtractedSections(identity ? withoutShardIdentity(i.goal) : i.goal).trim();
   const goal = goalBody ? { title: '목표', text: `목표\n${goalBody}` } : undefined;
   // ⭐ **자식이 낸 증거**(diff 밖 이행 · base 적색 · 직전 반영분)를 한 묶음으로 잡아 둔다 — 아래 예산
   //   배분에서 **목표 본문보다 먼저** 채우기 위해서다. 제목 문자열이 아니라 **동일성**으로 가른다.
@@ -563,6 +566,7 @@ export function buildReviewIntent(i: Readonly<ReviewIntentInput>): string {
     priorFindings,
     goalFile,
     goalType,
+    shardBoundary,
     goal,
     listBlock('수용기준', acceptance),
     applied,
@@ -584,7 +588,7 @@ export function buildReviewIntent(i: Readonly<ReviewIntentInput>): string {
   //   `…[N개 생략됨]`** 이 됐다. 그러면 리뷰는 *"실행하지 않았다 · 증거가 없다"* 를 적고 — 그것이
   //   **리뷰 입장에서 사실**이라 반박도 안 된다. 두 트랙 합쳐 **여섯 런**이 이 사인으로 죽었다.
   //   ⭐ 목표 본문을 뒤로 미뤄도 잃는 것이 적다 — **수용기준·경계는 이미 추출돼 보호 블록**에 있다.
-  const evidenceBlocks = [priorFindings, designGate, applied, preexisting, importerTestsNotRun, gateEvidence, designCheck, shardSiblings, coverage, claims, runFacts, goalFile].filter((b): b is Block => Boolean(b));
+  const evidenceBlocks = [shardBoundary, priorFindings, designGate, applied, preexisting, importerTestsNotRun, gateEvidence, designCheck, shardSiblings, coverage, claims, runFacts, goalFile].filter((b): b is Block => Boolean(b));
   const otherBlocks = blocks.filter((block) => !protectedBlocks.includes(block) && !evidenceBlocks.includes(block) && block !== goal);
   const order = [...protectedBlocks, ...evidenceBlocks, ...otherBlocks, ...(goal ? [goal] : [])];
   // ⛔⭐⭐⭐ 1차는 우선순위와 무관하게 공정 몫까지만 준다. 목표 본문은 이미 추출된

package/src/agent-substrate/shard-boundary-intent.ts

@@ -0,0 +1,70 @@
+interface ShardIdentity {
+  readonly shardId: string;
+  readonly totalShards: number;
+  readonly position: number;
+  readonly summary: string;
+  readonly siblings: readonly { readonly shardId: string; readonly summary: string }[];
+}
+
+const SHARD_IDENTITY_SUFFIX = /(?:^|\n)## Shard identity\r?\n([\s\S]+?)\s*$/;
+const MAX_BLOCK_CHARS = 800;
+
+/** Read the JSON footer emitted by shardIdentityFeature, without treating other goal text as identity. */
+export function parseShardIdentity(goalText: string): ShardIdentity | undefined {
+  const match = SHARD_IDENTITY_SUFFIX.exec(goalText);
+  if (!match) return undefined;
+  try {
+    const value: unknown = JSON.parse(match[1]!);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const identity = value as Record<string, unknown>;
+    if (typeof identity.shardId !== 'string' || !identity.shardId.trim()
+      || typeof identity.summary !== 'string'
+      || !Number.isInteger(identity.totalShards) || (identity.totalShards as number) < 1
+      || !Number.isInteger(identity.position) || (identity.position as number) < 1
+      || (identity.position as number) > (identity.totalShards as number)
+      || !Array.isArray(identity.siblings)
+      || !identity.siblings.every((sibling: unknown) => {
+        if (!sibling || typeof sibling !== 'object' || Array.isArray(sibling)) return false;
+        const item = sibling as Record<string, unknown>;
+        return typeof item.shardId === 'string' && !!item.shardId.trim() && typeof item.summary === 'string';
+      })) return undefined;
+    return identity as unknown as ShardIdentity;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Remove only a successfully parsed footer; malformed metadata remains ordinary goal text. */
+export function withoutShardIdentity(goalText: string): string {
+  return parseShardIdentity(goalText) ? goalText.replace(SHARD_IDENTITY_SUFFIX, '') : goalText;
+}
+
+function oneLine(value: string, limit: number): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length > limit ? `${normalized.slice(0, limit - 1)}…` : normalized;
+}
+
+/** Keep the sibling contract ahead of the goal body, with an explicit omission count. */
+export function shardBoundaryBlock(identity: ShardIdentity): string {
+  const prefix = [
+    `이 PR 은 조각 ${oneLine(String(identity.position), 20)}/${oneLine(String(identity.totalShards), 20)}(${oneLine(identity.shardId, 80)}): ${oneLine(identity.summary, 240)}.`,
+    '형제 조각이 맡는 일(예: 등록·배선·화면)이 이 PR 에 없다는 이유로 must-fix 를 내지 말 것. 없어서 이 조각이 동작하지 않으면 should-fix 로 «형제 조각 <id> 에 의존» 한 줄.',
+    '형제 조각이 맡는 일:',
+  ];
+  const items = identity.siblings.map((sibling) => `- ${oneLine(sibling.shardId, 80)}: ${oneLine(sibling.summary, 240)}`);
+  const header = prefix.join('\n');
+  if (header.length > MAX_BLOCK_CHARS) return header.slice(0, MAX_BLOCK_CHARS);
+  const kept: string[] = [];
+  for (const [index, item] of items.entries()) {
+    const omitted = items.length - index - 1;
+    const marker = omitted ? `…외 ${omitted}` : '';
+    if ([...prefix, ...kept, item, ...(marker ? [marker] : [])].join('\n').length > MAX_BLOCK_CHARS) break;
+    kept.push(item);
+  }
+  const omitted = items.length - kept.length;
+  const marker = omitted ? `…외 ${omitted}` : '';
+  if (marker && header.length + marker.length + 1 > MAX_BLOCK_CHARS) {
+    return `${header.slice(0, MAX_BLOCK_CHARS - marker.length - 1)}\n${marker}`;
+  }
+  return [...prefix, ...kept, ...(marker ? [marker] : [])].join('\n');
+}

package/src/auth/github-app-token.ts

@@ -55,7 +55,10 @@ export function githubInstallationCredential(deps: GithubAutomationTokenDeps = {
     const rel = join('secrets', 'github-app', 'app.json');
     const own = join(getElanousConfigDir(), rel);
     // An explicit config-dir override (tests · `--config-dir`) is a deliberate boundary — never reach past it.
-    path = deps.configPath ?? (existsSync(own) || getElanousConfigDirOverride() ? own : join(prodInstanceRoot(), rel));
+    // ELANOUS_GITHUB_APP_CONFIG_PATH pins the machine-level fallback (the bun test preload points it at nothing,
+    // so tests never mint); an explicit config-dir override still wins.
+    const pinned = process.env.ELANOUS_GITHUB_APP_CONFIG_PATH?.trim();
+    path = deps.configPath ?? (getElanousConfigDirOverride() ? own : pinned || (existsSync(own) ? own : join(prodInstanceRoot(), rel)));
   }
   catch {
     try { debug.log('auth.github-app', 'token-failed', { reason: 'config-path-failed' }); } catch { /* fail open */ }

package/src/autopilot/track-agent-shadow.ts

@@ -0,0 +1,151 @@
+import { execFile } from 'node:child_process';
+import { appendFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { TrackAgentDecision, TrackAgentInput, TrackAgentResult } from './track-agent.js';
+
+const exec = promisify(execFile);
+const dateInKst = (now: Date): string => new Intl.DateTimeFormat('en-CA', {
+  timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit',
+}).format(now);
+
+export type ShadowLedgerEntry = {
+  at: string;
+  missionId: string;
+  taskId: string;
+  track: string;
+  event: 'decision-started' | 'decision' | 'orchestrate-started' | 'orchestrate';
+  action?: TrackAgentDecision['action'];
+  status?: TrackAgentResult['status'];
+  workdir?: string | null;
+  workdirs?: (string | null)[];
+};
+
+export type ShadowOptions = {
+  ledgerDir?: string;
+  now?: () => Date;
+  maxDecisionsPerDay?: number;
+  orchestrate?: (args: string[]) => Promise<{ stdout: string }>;
+};
+
+export function shadowLedgerPath(options: ShadowOptions = {}): string {
+  const now = options.now?.() ?? new Date();
+  return join(options.ledgerDir ?? join(effectiveInstanceRoot(), 'autopilot', 'track-agent-shadow'), `${dateInKst(now)}.jsonl`);
+}
+
+function append(entry: ShadowLedgerEntry, path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', flag: 'a' });
+}
+
+function entryFor(input: TrackAgentInput, event: ShadowLedgerEntry['event'], now: Date): ShadowLedgerEntry {
+  return { at: now.toISOString(), missionId: input.missionId, taskId: input.taskId, track: input.track, event };
+}
+
+/** Reserve a daily decision slot on disk before invoking the agent. An unreadable ledger never grants a slot. */
+export async function decideShadowTrackAction(
+  input: TrackAgentInput,
+  decide: (input: TrackAgentInput) => Promise<TrackAgentDecision> | TrackAgentDecision,
+  options: ShadowOptions = {},
+): Promise<TrackAgentDecision> {
+  const now = options.now?.() ?? new Date();
+  const path = shadowLedgerPath({ ...options, now: () => now });
+  const configured = options.maxDecisionsPerDay ?? 20;
+  const limit = Number.isSafeInteger(configured) && configured >= 0 ? configured : 20;
+  const lockPath = `${path}.lock`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    // The lock spans only count + reservation, never the callback. A contested slot fails closed.
+    mkdirSync(lockPath);
+  } catch {
+    return { action: 'hold', reason: 'shadow 원장 확인 실패' };
+  }
+  let reserved = false;
+  let capped = false;
+  try {
+    let rows: string[];
+    try { rows = readFileSync(path, 'utf8').split('\n').filter(Boolean); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      rows = [];
+    }
+    const count = rows.reduce((total, row) => {
+      const value: unknown = JSON.parse(row);
+      if (!value || typeof value !== 'object' || !('event' in value)) throw new Error('invalid shadow ledger');
+      return total + ((value as { event: unknown }).event === 'decision-started' ? 1 : 0);
+    }, 0);
+    if (count >= limit) capped = true;
+    else { append(entryFor(input, 'decision-started', now), path); reserved = true; }
+  } catch { /* The callback cannot run without a durable reservation. */ }
+  finally {
+    try { rmdirSync(lockPath); }
+    catch { reserved = false; }
+  }
+  if (capped) return { action: 'hold', reason: '일일 판정 상한' };
+  if (!reserved) return { action: 'hold', reason: 'shadow 원장 확인 실패' };
+  try {
+    const decision = await decide(input);
+    append({ ...entryFor(input, 'decision', now), action: decision.action }, path);
+    return decision;
+  } catch {
+    return { action: 'hold', reason: '판정 실패 — 사람 확인' };
+  }
+}
+
+function outcomeFromOutput(stdout: string): { workdirs: (string | null)[]; succeeded: boolean } {
+  const parsed: unknown = JSON.parse(stdout.trim());
+  const results = parsed && typeof parsed === 'object' && 'results' in parsed
+    ? (parsed as { results: unknown }).results : parsed;
+  const items: unknown[] = Array.isArray(results) ? results : [results];
+  const workdirs = items.map((item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const value = item as Record<string, unknown>;
+    const path = value.worktreePath ?? value.workdir;
+    return typeof path === 'string' && path.length > 0 ? path : null;
+  });
+  return {
+    workdirs,
+    succeeded: items.length > 0 && items.every((item, index) =>
+      item !== null && typeof item === 'object' && !Array.isArray(item)
+      && (item as Record<string, unknown>).status === 'done' && workdirs[index] !== null),
+  };
+}
+
+/** Called only after the ordinary track/forbidden-task/budget gates approve the work. */
+export async function launchTrackAgentShadow(input: TrackAgentInput, options: ShadowOptions = {}): Promise<TrackAgentResult> {
+  const now = options.now?.() ?? new Date();
+  const path = shadowLedgerPath({ ...options, now: () => now });
+  try {
+    append(entryFor(input, 'orchestrate-started', now), path);
+  } catch { return { status: 'failed', detail: 'shadow 원장 기록 실패' }; }
+  const args = ['self', 'orchestrate', '--json', `${input.title}\n${input.prompt}`];
+  let status: TrackAgentResult['status'] = 'failed';
+  let workdirs: (string | null)[] = [];
+  try {
+    const run = options.orchestrate ?? (async (values: string[]) => {
+      const instanceRoot = effectiveInstanceRoot();
+      const { stdout } = await exec('bun', ['bin/elanous.mjs', '--config-dir', instanceRoot, ...values], {
+        cwd: process.env.ELANOUS_TOOL_CWD?.trim() || resolve(import.meta.dir, '../..'),
+        env: { ...process.env, ELANOUS_STATE_DIR: instanceRoot },
+        encoding: 'utf8', maxBuffer: 1024 * 1024,
+      });
+      return { stdout };
+    });
+    const outcome = outcomeFromOutput((await run(args)).stdout);
+    workdirs = outcome.workdirs;
+    if (outcome.succeeded) status = 'launched';
+  } catch (error) {
+    // self orchestrate may exit nonzero after writing its JSON results; retain every observed workdir.
+    const stdout = (error as { stdout?: unknown }).stdout;
+    if (typeof stdout === 'string') {
+      try { workdirs = outcomeFromOutput(stdout).workdirs; } catch { /* malformed result has no observed workdir */ }
+    }
+  }
+  try {
+    append({ ...entryFor(input, 'orchestrate', now), status, workdir: workdirs[0] ?? null, workdirs }, path);
+  } catch { return { status: 'failed', detail: 'shadow 원장 기록 실패' }; }
+  return status === 'launched'
+    ? { status, detail: workdirs.join(', ') }
+    : { status, detail: 'shadow 실행 실패 또는 workdir 미관측' };
+}