elanous 0.2.29 → 0.2.31

package/graphs/release/recipes.yaml

@@ -11,6 +11,9 @@ gate:
   command: 'bun scripts/release-loop/gate-node.ts --json'
   # 4h — the Pod gate took 2h02m on 09-30 (G1f ②) and the 0.2.5 loop was cut at exactly 2h with no verdict; K9 (≤15 min) is the real fix.
   timeout_ms: 14400000
+gate-triage:
+  command: 'bun scripts/release-loop/gate-triage-node.ts'
+  timeout_ms: 60000
 mac-smoke:
   command: 'bun scripts/release-loop/mac-smoke-node.ts'
   timeout_ms: 1800000

package/graphs/release/release-loop.yaml

@@ -15,10 +15,13 @@ nodes:
   - { node_id: cutoff, kind: judge, recipe: 'cmd:cutoff', max_visits: 1 }
   - { node_id: checklist-gate, kind: gate, recipe: 'cmd:checklist-gate', max_visits: 1 }
   # cmd:docs dispatches by graph node ID: bounded prefetch before gate, TUI join after upgrade, docs write after both.
+  # Public export is checked before expensive prefetch/gate work; a leak stops the release immediately.
+  - { node_id: export-check, kind: gate, recipe: 'cmd:export-check', max_visits: 1 }
   - { node_id: prefetch, kind: agent, recipe: 'cmd:docs', max_visits: 1 }
   - { node_id: gate, kind: gate, recipe: 'cmd:gate', max_visits: 1, notify: { on: [fail] } }
+  # S1 shadow: classify and record only; all exits still terminate through the existing failed node.
+  - { node_id: gate-triage, kind: judge, recipe: 'cmd:gate-triage', max_visits: 1 }
   - { node_id: mac-smoke, kind: gate, recipe: 'cmd:mac-smoke', max_visits: 1 }
-  - { node_id: export-check, kind: gate, recipe: 'cmd:export-check', max_visits: 1 }
   - { node_id: pwa, kind: gate, recipe: 'cmd:pwa', max_visits: 1, notify: { on: [fail] } }
   - { node_id: prepare, kind: agent, recipe: 'cmd:prepare', max_visits: 1, notify: { on: [fail] } }
   - { node_id: upgrade, kind: gate, recipe: 'cmd:upgrade', max_visits: 1 }
@@ -42,13 +45,14 @@ nodes:
 edges:
   - { from: version-release, on: outcome, map: { ok: cutoff, fail: failed, error: failed } }
   - { from: cutoff, on: outcome, map: { ok: checklist-gate, fail: failed, error: failed } }
-  - { from: checklist-gate, on: outcome, map: { ok: prefetch, fail: failed, error: failed } }
+  - { from: checklist-gate, on: outcome, map: { ok: export-check, fail: failed, error: failed } }
+  - { from: export-check, on: outcome, map: { ok: prefetch, fail: failed, error: failed } }
   # Prefetch never gates: even a crashed prefetch node is a cache miss — the late nodes take their original paths.
   - { from: prefetch, on: outcome, map: { ok: gate, fail: gate, error: gate } }
-  - { from: gate, on: outcome, map: { ok: mac-smoke, fail: failed, error: failed } }
+  - { from: gate, on: outcome, map: { ok: mac-smoke, fail: gate-triage, error: gate-triage } }
+  - { from: gate-triage, on: outcome, map: { ok: failed, fail: failed, error: failed } }
   # Warning-only: a macOS failure or unmeasured run never blocks publishing — auto-approve shows it as a warning row.
-  - { from: mac-smoke, on: outcome, map: { ok: export-check, fail: export-check, error: export-check } }
-  - { from: export-check, on: outcome, map: { ok: pwa, fail: failed, error: failed } }
+  - { from: mac-smoke, on: outcome, map: { ok: pwa, fail: pwa, error: pwa } }
   - { from: pwa, on: outcome, map: { ok: prepare, fail: failed, error: failed } }
   - { from: prepare, on: outcome, map: { ok: upgrade, fail: failed, error: failed } }
   - { from: upgrade, on: outcome, map: { ok: tui, fail: failed, error: failed } }

package/graphs/units/recipes.yaml

@@ -0,0 +1,3 @@
+plan:
+  command: 'bun scripts/release-loop/gate-recheck-plan-node.ts'
+  timeout_ms: 60000

package/graphs/units/release-gate-recheck.yaml

@@ -0,0 +1,15 @@
+# Shadow G1 unit: plan only. TC connects gate-node's existing sweep to kind: recheck after #27800.
+graph_id: release-gate-recheck
+version: 1
+unit:
+  inputs: [version, commit, measuredCommit, failures, errors, ledgerRoot]
+  outputs: [planPath, files]
+  exits: [done, failed]
+entry_node: plan
+terminal_nodes: [done, failed]
+nodes:
+  - { node_id: plan, kind: agent, recipe: 'cmd:plan', max_visits: 1 }
+  - { node_id: done, kind: gate, recipe: none, max_visits: 1 }
+  - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }
+edges:
+  - { from: plan, on: outcome, map: { ok: done, fail: failed } }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elanous",
   "mcpName": "io.github.ElanvitalAI/elanous",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Self-healing coding harness where eyes, hands, and memory all turn on one sentence — it authors its own goals, implements them in isolated worktrees, and reviews its own work.",
   "license": "Apache-2.0",
   "author": "Elanvital AI",
@@ -129,6 +129,7 @@
     "telegram": "^2.26.22"
   },
   "devDependencies": {
+    "@copilotkit/aimock": "1.45.1",
     "@types/bun": "^1.2.0",
     "@types/diff": "^8.0.0",
     "@types/node-cron": "^3.0.11",

package/scripts/check-native-tool-wiring.ts

@@ -28,6 +28,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { nativeToolCatalog } from '../src/native-tool-catalog.js';
+import { TUI_SOURCE_DIRS, tuiSourceText } from '../test/helpers/dashboard-source.js';
 
 const verbose = process.argv.includes('--verbose');
 const strict  = process.argv.includes('--strict');
@@ -68,7 +69,7 @@ const SKIP_TOOLS: ReadonlySet<string> = new Set([
 //      ⇒ 그러므로 이 스크립트가 내는 issue 수는 «결함 수가 아니라 이 자로 잰 수»다. 분류는 후속.
 const root = resolve(import.meta.dir, '..');
 const skillDispatchSrc = readFileSync(resolve(root, 'src/tool-runtime/registry.ts'), 'utf8');
-const tuiSrc   = readFileSync(resolve(root, 'src/dashboard/index.ts'), 'utf8');
+const tuiSrc   = tuiSourceText(root); // TUI 소스 묶음(src/dashboard/** ⊕ src/tui/**) — 경로 무관
 
 interface Issue { tool: string; surface: string; kind: 'missing' | 'extra'; detail: string; }
 
@@ -103,7 +104,7 @@ for (const entry of nativeToolCatalog) {
         tool: entry.id,
         surface: 'tui',
         kind: 'missing',
-        detail: `dashboard/index.ts does not mention alias "${pascal}" (catalog lists host:'tui')`,
+        detail: `TUI source bundle (${TUI_SOURCE_DIRS.join(' + ')}) does not mention alias "${pascal}" (catalog lists host:'tui')`,
       });
     }
   }

package/scripts/ci-android-unit-tests.ts

@@ -26,6 +26,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { androidToolchainMissing } from './lib/android-toolchain.js';
 
 const ROOT = join(import.meta.dir, '..');
 
@@ -225,6 +226,8 @@ export type AndroidGateIo = {
   readonly cwd?: string;
   readonly log?: (line: string) => void;
   readonly error?: (line: string) => void;
+  /** 툴체인 판정 심 — 기본은 bun 시험의 skip 관문과 «같은» `androidToolchainMissing()`. 다 있으면 null. */
+  readonly toolchainMissing?: () => string | null;
   /** 시험 실행 심 — 시험에서 주입한다. */
   readonly runGradle?: (androidDir: string) => { readonly status: number | null; readonly output: string };
   /** 결과 XML 읽기 심. */
@@ -382,6 +385,19 @@ export function runAndroidUnitTestGate(io: AndroidGateIo = {}): number {
       log(`[android-gate] 해당 없음 — 변경 ${changed.length}개 중 ${ANDROID_PREFIX} 아래 파일 0개.`);
       return 0;
     }
+    // ⭐ R5a(0.2.31 · OP #8961): 바뀐 안드로이드 파일이 «전부» bun 시험(.test.ts)이고 이 호스트에 툴체인이 없으면
+    //    Gradle 축은 «측정 대상 아님»이다 — 그 파일들은 Kotlin 컴파일러가 안 읽어 Gradle 결과를 못 바꾸고,
+    //    그 자체는 bun 러너가 잰다(툴체인이 없으면 시험이 «전제 없음» 이유를 찍고 skip).
+    //    ⛔ 「Gradle 통과」로 말하지 않는다. Kotlin·Gradle 설정이 하나라도 바뀌었으면 아래 기존 판정(0 = 실패) 그대로다.
+    //    면제는 «Kotlin 소스셋 안»의 bun 시험만이다(`androidKotlinSourcesetTestTsFiles` · r2 리뷰) — 그 밖의 .test.ts 는 기존 판정.
+    if (androidKotlinSourcesetTestTsFiles(hits).length === hits.length) {
+      const missing = (io.toolchainMissing ?? androidToolchainMissing)();
+      if (missing) {
+        log(`[android-gate] 측정 대상 아님 — 이 호스트에 안드로이드 툴체인이 없다: ${missing}`);
+        log(`   바뀐 안드로이드 파일 ${hits.length}개가 전부 bun 시험(.test.ts)이라 Gradle 결과를 바꾸지 못한다 — 그 시험은 bun 러너가 잰다. ⛔ 「Gradle 통과」가 아니라 「Gradle 안 잼」이다.`);
+        return 0;
+      }
+    }
     log(`[android-gate] 대상 ${hits.length}개 (변경 ${changed.length}개 중) — 시험을 돌린다.`);
   }
 

package/scripts/ci-typecheck-changed.ts

@@ -25,6 +25,7 @@ import {
   type BaselineCacheOptions,
 } from './tsc-baseline-cache.js';
 import { TSC_OOM_RETRY_HEAP_MB, TSC_HEAP_MB, tscEnv } from '../src/typecheck-ratchet.js';
+import { runIncrementalCachedTsc } from './tsc-incremental-cache.js';
 
 /** Inherited GIT_DIR / GIT_WORK_TREE would make `--cwd <other tree>` still read the launcher's repo. */
 function gitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
@@ -49,7 +50,7 @@ function sh(cmd: string, cwd = process.cwd()): string {
   return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd, env: gitEnv() });
 }
 
-export type TscRun = { out: string; ran: boolean; why?: string };
+export type TscRun = { out: string; ran: boolean; why?: string; exitCode?: number };
 
 export { TSC_HEAP_MB, TSC_OOM_RETRY_HEAP_MB, tscEnv } from '../src/typecheck-ratchet.js';
 /** V8 힙 부족의 얼굴 — 「타입 에러」와 «다른 값»이다. */
@@ -70,7 +71,7 @@ export function runTsc(cmd: string, exec = execSync): TscRun {
   const result = (attempt: Attempt, env: NodeJS.ProcessEnv): TscRun => {
     const { out, error: e } = attempt;
     if (OOM.test(out)) return { out, ran: false, why: `tsc 가 V8 힙 부족(OOM)으로 죽었다 — 타입 에러가 아니다 (NODE_OPTIONS=${env.NODE_OPTIONS})` };
-    if (!e) return { out, ran: true };
+    if (!e) return { out, ran: true, exitCode: 0 };
     if (e.signal || e.code === 'ENOENT' || e.status === null || e.status === undefined) {
       return { out, ran: false, why: `tsc 실행 실패 (signal=${String(e.signal)} code=${String(e.code)} status=${String(e.status)})` };
     }
@@ -81,7 +82,7 @@ export function runTsc(cmd: string, exec = execSync): TscRun {
     if (!/error TS\d+/.test(out)) {
       return { out, ran: false, why: `tsc 가 종료코드 ${e.status} 로 끝났는데 TS 진단이 한 건도 없다(래퍼 실패로 본다)` };
     }
-    return { out, ran: true };
+    return { out, ran: true, exitCode: e.status };
   };
 
   const initialEnv = tscEnv();
@@ -140,6 +141,10 @@ export function changedTsFiles(run: (cmd: string) => string = sh, env: NodeJS.Pr
   const quietRevision = (command: string): string => { try { return run(command).trim(); } catch { return ''; } };
   const head = quietRevision('git rev-parse HEAD') || undefined;
   const warnings: string[] = [];
+  // base==HEAD ⊕ HEAD 가 origin/main 의 조상(merge-base 가 HEAD 자신) — 아래 수집이 git diff --name-only HEAD
+  // (커밋 안 된 변경) ⊕ git ls-files --others(untracked) 를 계속 모으므로 «변경을 셀 수 없다» 판정은
+  // 그 수집 결과에 따라 갈린다. 결정만 여기서 미뤄 수집 뒤에 넣는다.
+  let uncountableBase: { command: string; why: string } | undefined;
   if (head && quietRevision(`git rev-parse ${base}`) === head) {
     const main = quietRevision('git rev-parse origin/main');
     const merged = main && main !== head ? quietRevision('git merge-base HEAD origin/main') : '';
@@ -148,14 +153,18 @@ export function changedTsFiles(run: (cmd: string) => string = sh, env: NodeJS.Pr
       base = merged;
       baseSource = 'recomputed merge-base(origin/main)';
     } else if (main && main !== head) {
-      failures.push({ command: `git rev-parse ${base}`, why: `base 가 HEAD(${head}) 와 같아 변경을 셀 수 없다 — TSC_BASE_REF 로 base 를 주라 (못 셌음 ≠ 0)` });
+      uncountableBase = { command: `git rev-parse ${base}`, why: `base 가 HEAD(${head}) 와 같아 변경을 셀 수 없다 — TSC_BASE_REF 로 base 를 주라 (못 셌음 ≠ 0)` };
     }
   }
 
   const files = new Set<string>();
   const diffFiles = new Set<string>();
+  // 커밋 안 된 변경 ⊕ untracked 를 내는 명령 — uncountableBase 판정의 분모다.
+  const dirtyCommands = new Set(['git diff --name-only HEAD', 'git ls-files --others --exclude-standard']);
+  let dirtyCount = 0;
   const commands = [`git diff --name-only ${base}...HEAD`, 'git diff --name-only HEAD', 'git ls-files --others --exclude-standard'];
   for (const command of commands) {
+    const countsDirty = uncountableBase !== undefined && dirtyCommands.has(command);
     try {
       for (const line of run(command).split('\n')) {
         const file = line.trim().replace(/^\.\//, '');
@@ -164,13 +173,22 @@ export function changedTsFiles(run: (cmd: string) => string = sh, env: NodeJS.Pr
         // A deleted .ts is not a compile candidate, so it must not count as «should have been collected».
         // existsSync is bound to the landing tree — process.cwd() would count the launcher's files.
         const present = existsSync(join(cwd, file));
-        if (!ts || present) diffFiles.add(file);
+        if ((!ts || present) && !diffFiles.has(file)) {
+          diffFiles.add(file);
+          if (countsDirty) dirtyCount += 1;
+        }
         if (ts && present) files.add(file);
       }
     } catch (cause) {
       failures.push({ command, why: cause instanceof Error ? cause.message : String(cause) });
     }
   }
+  if (uncountableBase) {
+    // 커밋 안 된 변경·untracked 를 1개라도 셌으면 그 수(N)와 baseSource 를 경고에 실어 판정을 지속한다 —
+    // «못 셌음 ≠ 0» 실패는 둘 다 0일 때만 그대로 남긴다.
+    if (dirtyCount > 0) warnings.push(`base=HEAD — 커밋 안 된 변경 ${dirtyCount} 개만 센다 (baseSource=${baseSource})`);
+    else failures.push(uncountableBase);
+  }
   return { files, base, baseSource, head, diffFiles, warnings, failures };
 }
 
@@ -1144,13 +1162,22 @@ export function runGate(io: Partial<GateIo> = {}): void {
   const rootCommand = `${tscBin} --noEmit -p ${TYPECHECK_GATE_CONFIG}`;
   const pwaCommand = `${tscBin} --noEmit -p apps/pwa/tsconfig.json`;
   const pwaEnvCommand = `${tscBin} --noEmit -p tsconfig.pwa-env.json`;
+  const cacheDir = (io.env ?? process.env).ELANOUS_TSC_CACHE_DIR;
+  const cacheEnabled = !!cacheDir && !io.runTscCmd && base !== 'injected test seam';
+  const checkedTsc = (command: string, config: string, scope: ReadonlySet<string>, excluded: readonly string[], included: readonly string[], promotionBaseline?: BaselineDiagnostics, excludeTests = false): TscRun => {
+    if (!cacheEnabled) return runTscCmd(command);
+    return runIncrementalCachedTsc({
+      cwd, base, head, changed, config, command, cacheDir: cacheDir!, run: runTscCmd, log,
+      decision: (result) => result.ran && inspectTscResult(result, scope, baseline, () => {}, () => {}, wholeRepository, excluded, included, promotionBaseline, excludeTests),
+    });
+  };
   const rootPromotionBaseline = wholeRepository ? readBaselineDiagnostics(base, rootCommand) : undefined;
   const pwaPromotionBaseline = wholeRepository && runsPwa ? readBaselineDiagnostics(base, pwaCommand) : undefined;
   const pwaEnvPromotionBaseline = wholeRepository && runsPwaEnv ? readBaselineDiagnostics(base, pwaEnvCommand) : undefined;
   let rootPlan = planRootCheck({ wholeRepository, rootChanged, env: io.env ?? process.env, cwd, affectedRoots: io.affectedRoots ?? reverseImportAffectedRoots });
   let rootsConfig: string | undefined;
   if (rootPlan.mode === 'affected') {
-    rootsConfig = `tsconfig.gate-roots.${process.pid}.${Date.now()}.json`;
+    rootsConfig = cacheEnabled ? 'tsconfig.gate-roots.incremental.json' : `tsconfig.gate-roots.${process.pid}.${Date.now()}.json`;
     try {
       // `include` is replaced (not merged) so only the listed roots plus ambient declarations enter the program.
       writeFileSync(join(cwd, rootsConfig), JSON.stringify({ extends: `./${TYPECHECK_GATE_CONFIG}`, include: ['src/**/*.d.ts', 'scripts/**/*.d.ts', 'test/**/*.d.ts'], files: rootPlan.roots }, null, 2), { flag: 'wx' });
@@ -1173,19 +1200,20 @@ export function runGate(io: Partial<GateIo> = {}): void {
     debug.log('typecheck.gate', 'roots', { mode: 'full', roots: rootPlan.roots ?? null, fallbackReason: rootPlan.fallbackReason }, { level: 'info' });
   }
   let rootTsc: TscRun;
-  try { rootTsc = runTscCmd(rootsConfig ? `${tscBin} --noEmit -p ${rootsConfig}` : rootCommand); }
+  try { rootTsc = checkedTsc(rootsConfig ? `${tscBin} --noEmit -p ${rootsConfig}` : rootCommand,
+    rootsConfig ?? TYPECHECK_GATE_CONFIG, rootScope, ['apps/pwa/'], [], rootPromotionBaseline); }
   finally { if (rootsConfig) rmSync(join(cwd, rootsConfig), { force: true }); }
   let unmeasured = !rootTsc.ran;
   let passed = inspectTscResult(rootTsc, rootScope, baseline, error, warn, wholeRepository, ['apps/pwa/'], [], rootPromotionBaseline);
   if (runsPwa) {
     log(`[tsc-gate] PWA 변경 ${pwaChanged.size}개 관측 — apps/pwa/tsconfig.json 검사.`);
-    const pwaTsc = runTscCmd(pwaCommand);
+    const pwaTsc = checkedTsc(pwaCommand, 'apps/pwa/tsconfig.json', pwaScope, [], ['apps/pwa/'], pwaPromotionBaseline);
     unmeasured = unmeasured || !pwaTsc.ran;
     passed = inspectTscResult(pwaTsc, pwaScope, baseline, error, warn, wholeRepository, [], ['apps/pwa/'], pwaPromotionBaseline) && passed;
   }
   if (runsPwaEnv) {
     log(`[tsc-gate] PWA env 패스 — 루트 비시험 ${nonTestRootChanged.size}개 (Next ProcessEnv 선언 포함).`);
-    const pwaEnvTsc = runTscCmd(pwaEnvCommand);
+    const pwaEnvTsc = checkedTsc(pwaEnvCommand, 'tsconfig.pwa-env.json', pwaEnvScope, ['apps/pwa/'], [], pwaEnvPromotionBaseline, true);
     unmeasured = unmeasured || !pwaEnvTsc.ran;
     passed = inspectTscResult(pwaEnvTsc, pwaEnvScope, baseline, error, warn, wholeRepository, ['apps/pwa/'], [], pwaEnvPromotionBaseline, true) && passed;
   }

package/scripts/coord-channel-watch.sh

@@ -49,16 +49,35 @@
 set -u
 set -o pipefail
 
+# WATCH1: help must still report a fixed token, even when the archived manual
+# no longer has a current channel heading.
+if [ -n "${GH_TOKEN:-}${GITHUB_TOKEN:-}" ]; then
+  if [ "${WATCH_KEEP_TOKEN:-}" = "1" ]; then
+    echo "⚠️ [watch] GH_TOKEN/GITHUB_TOKEN 고정 토큰으로 읽는다(WATCH_KEEP_TOKEN=1) — 만료되면 «⛔ 조회 실패» 줄이 뜬다"
+  else
+    echo "⚠️ [watch] GH_TOKEN/GITHUB_TOKEN 이 들어 있어 비웠다 — 읽기는 keyring gh 인증으로(고정 토큰은 만료돼 감시가 눈이 먼다 · WATCH1)"
+    unset GH_TOKEN GITHUB_TOKEN
+  fi
+fi
+
+for arg in "$@"; do
+  case "$arg" in -h|--help)
+    echo '⛔ PR 조율 채널은 퇴역했다. 자리 간 소통은 eln msg post/list 를 사용한다.'
+    sed -n '1,40p' "$0"
+    exit 0 ;;
+  esac
+done
+
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) || { echo '⛔ 스크립트 위치를 못 읽었다' >&2; exit 3; }
 CANON="$SCRIPT_DIR/../docs/manual/MANUAL-multi-agent-coordination-channel-2026-07-28.md"
 resolve_pr() {
   [ -f "$CANON" ] || return 3
   # 머리말의 실제 인용 제목만 읽는다. 설명·과거 채널·손상된 제목에서 추측하지 않는다.
   head -40 "$CANON" | awk '
-    /^> ## / && /현재 채널/ {
+    /^> ## / && /마지막 채널/ {
       count++
-      if ($0 !~ /^> ## .*현재 채널 = \[PR #[0-9]+\]\(https:\/\/github\.com\/ElanvitalAI\/elanous-agent\/pull\/[0-9]+\)/) { bad=1; next }
-      id=$0; sub(/^.*현재 채널 = \[PR #/, "", id); sub(/\].*$/, "", id)
+      if ($0 !~ /^> ## .*마지막 채널 = \[PR #[0-9]+\]\(https:\/\/github\.com\/ElanvitalAI\/elanous-agent\/pull\/[0-9]+\)/) { bad=1; next }
+      id=$0; sub(/^.*마지막 채널 = \[PR #/, "", id); sub(/\].*$/, "", id)
       url=$0; sub(/^.*\]\(https:\/\/github\.com\/ElanvitalAI\/elanous-agent\/pull\//, "", url); sub(/\).*$/, "", url)
       if (id != url) bad=1
     }
@@ -100,18 +119,6 @@ WATCH_EXIT_ANNOUNCED=0    # 종료 줄 중복 방지(INT→EXIT 로 trap 이 두
 # 「거의 비었다」로 «의심»할 자수 — 이 아래로 떨어지면 «변경»이 아니라 «의심»으로 말한다.
 BODY_MIN="${CH_BODY_MIN:-100}"
 
-# ⛔⭐ WATCH1(10-03 MK 6시간 실명): 감시자에 고정 토큰(GH_TOKEN·GITHUB_TOKEN — App 토큰은 1시간)을 넣어 띄우면
-#   만료 뒤 조회가 조용히 계속 실패한다. 읽기는 신원이 필요 없다 ⇒ 고정 토큰을 «비우고» keyring gh 인증으로 읽는다.
-#   그 토큰을 꼭 써야 하면 WATCH_KEEP_TOKEN=1 (그때도 경고 줄은 낸다).
-if [ -n "${GH_TOKEN:-}${GITHUB_TOKEN:-}" ]; then
-  if [ "${WATCH_KEEP_TOKEN:-}" = "1" ]; then
-    echo "⚠️ [watch] GH_TOKEN/GITHUB_TOKEN 고정 토큰으로 읽는다(WATCH_KEEP_TOKEN=1) — 만료되면 «⛔ 조회 실패» 줄이 뜬다"
-  else
-    echo "⚠️ [watch] GH_TOKEN/GITHUB_TOKEN 이 들어 있어 비웠다 — 읽기는 keyring gh 인증으로(고정 토큰은 만료돼 감시가 눈이 먼다 · WATCH1)"
-    unset GH_TOKEN GITHUB_TOKEN
-  fi
-fi
-
 CMD="ensure"
 TRACK=""
 ADOPT_PID=""
@@ -121,7 +128,6 @@ while [ $# -gt 0 ]; do
     ensure|status|stop|restart|adopt|discover|delivery) CMD="$1" ;;
     --track) shift; TRACK="${1:-}" ;;
     --pid)   shift; ADOPT_PID="${1:-}" ;;
-    -h|--help) sed -n '1,40p' "$0"; exit 0 ;;
     *) echo "⛔ 모르는 인자: $1" >&2; exit 2 ;;
   esac
   shift

package/scripts/coord-role-pack.ts

@@ -2,6 +2,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { KnowhowLintError, lintKnowhow } from '../src/seat-loop/knowhow-lint.js';
 
 export type RolePackRole = 'coordinator' | 'guardian';
 
@@ -10,6 +11,7 @@ export interface RolePack {
   version: string;
   sha256: string;
   body: string;
+  /** Built-in C/G rule identifiers; verified KNOWHOW identifiers appear in the body. */
   includedCardIds: string[];
   excludedCardIds: string[];
   sources: Array<{ path: string; sha256: string }>;
@@ -17,6 +19,76 @@ export interface RolePack {
   missingSources: string[];
 }
 
+const KNOWHOW_PATH = 'docs/roles/OP/KNOWHOW.md';
+
+/**
+ * KNOWHOW.md 를 `##` 제목 단위 카드로 자른다(코드 울타리 안은 본문으로 본다).
+ * 유효한 `## K-<role>-<number>` 제목을 가진 카드만 반환한다.
+ */
+export function splitKnowhowCards(body: string): Array<{ id: string; title: string; text: string }> {
+  const segments: Array<{ heading: string | null; lines: string[] }> = [{ heading: null, lines: [] }];
+  let fence: { marker: string; length: number } | null = null;
+  for (const line of body.split(/\r?\n/u)) {
+    const fenceLine = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/u);
+    if (fence) {
+      if (fenceLine && fenceLine[1]![0] === fence.marker && fenceLine[1]!.length >= fence.length && /^[ \t]*$/u.test(fenceLine[2]!)) fence = null;
+      segments.at(-1)!.lines.push(line);
+      continue;
+    }
+    if (fenceLine) {
+      fence = { marker: fenceLine[1]![0]!, length: fenceLine[1]!.length };
+      segments.at(-1)!.lines.push(line);
+      continue;
+    }
+    if (/^##\s/u.test(line)) {
+      segments.push({ heading: line, lines: [] });
+      continue;
+    }
+    segments.at(-1)!.lines.push(line);
+  }
+  const cards: Array<{ id: string; title: string; text: string }> = [];
+  for (const segment of segments) {
+    if (!segment.heading) continue;
+    const heading = segment.heading.match(/^##\s+(K-[A-Za-z]+-\d+)\s*(.*)$/u);
+    if (!heading) continue;
+    cards.push({ id: heading[1]!, title: heading[2]!.trim(), text: [segment.heading, ...segment.lines].join('\n') });
+  }
+  return cards;
+}
+
+/**
+ * KNOWHOW 카드 중 src/seat-loop/knowhow-lint.ts 의 린트를 통과한 항목만 검증된 출처로 싣는다.
+ * 실패 항목(비밀값 포함)은 제외하고 그 아이디만 남긴다. 파일이 없으면 아무것도 싣지 않는다.
+ */
+export function collectVerifiedKnowhow(repo: string): {
+  included: Array<{ id: string; title: string; text: string }>;
+  excluded: string[];
+  fileBody: string | null;
+} {
+  let body: string;
+  try {
+    body = readFileSync(resolve(repo, KNOWHOW_PATH), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { included: [], excluded: [], fileBody: null };
+    throw error;
+  }
+  const included: Array<{ id: string; title: string; text: string }> = [];
+  const excluded: string[] = [];
+  for (const card of splitKnowhowCards(body)) {
+    try {
+      lintKnowhow(card.text, KNOWHOW_PATH);
+      included.push({ id: card.id, title: card.title, text: card.text });
+    } catch (error) {
+      if (error instanceof KnowhowLintError) {
+        excluded.push(card.id);
+        continue;
+      }
+      throw error;
+    }
+  }
+  return { included, excluded, fileBody: body };
+}
+
 const SOURCE_PATHS = [
   'AGENTS.md',
   'docs/roles/OP.md',
@@ -70,6 +142,8 @@ export function buildCoordRolePackManifest(role: RolePackRole, root = resolve(im
   const present = SOURCE_PATHS.filter((path) => existsSync(resolve(repo, path)));
   const missingSources = SOURCE_PATHS.filter((path) => !present.includes(path));
   const sources = present.map((path) => ({ path, sha256: sha256(readFileSync(resolve(repo, path), 'utf8')) }));
+  const knowhow = collectVerifiedKnowhow(repo);
+  if (knowhow.fileBody !== null) sources.push({ path: KNOWHOW_PATH, sha256: sha256(knowhow.fileBody) });
   const packageJson = resolve(repo, 'package.json');
   const version = existsSync(packageJson)
     ? (JSON.parse(readFileSync(packageJson, 'utf8')) as { version: string }).version : 'unknown';
@@ -109,20 +183,25 @@ export function buildCoordRolePackManifest(role: RolePackRole, root = resolve(im
     '재는 명령: `eln release checklist status --version <판> --json`(칸·선행·판) · `eln config get harness.podPool`(Pod 풀) · `uptime`(부하 추세) · `eln self gate --help`(호스트·게이트 옵션). 명령이 못 재는 슬롯·런 상태는 담당 원장의 현행 명령을 확인한다.',
     ...cards.map(([id, rule]) => `- ${id} · ${rule} → 팩 ${role === 'coordinator' ? '조율자' : '수호자'} v1`),
     '',
+    '## KNOWHOW — 검증된 출처',
+    `docs/roles/OP/KNOWHOW.md 항목 중 src/seat-loop/knowhow-lint.ts 의 린트를 통과한 항목만 싣는다. 실패 항목·비밀값은 제외한다.`,
+    ...knowhow.included.map((card) => `- ${card.id} · ${card.title}`),
+    ...knowhow.included.flatMap((card) => ['', card.text]),
+    '',
     '## 판단 순서',
     '1. 원 요청과 지금의 우편 스레드·확인표 칸을 대조한다.',
     '2. 코드·설정·실행 결과를 읽고, 문서와 충돌하면 현재 실행 결과를 따른다.',
     '3. 관측·판단 근거·다음 행동을 분리해 답한다. 쓰기는 현재 확인 단계가 허용한 명령으로만 한다.',
     '4. 근거가 없거나 안전 난간과 충돌하면 보류하고 담당 자리 또는 사람에게 올린다.',
     '',
-    '위에 명시한 검증된 C/G 카드 외의 노하우 카드는 포함하지 않는다. 현재 관측과 담당 자리의 검증된 원장을 직접 확인한다.',
+    '위에 명시한 검증된 C/G 카드와 KNOWHOW 린트 통과 항목 외의 노하우는 포함하지 않는다. 현재 관측과 담당 자리의 검증된 원장을 직접 확인한다.',
     '## 출처 해시',
     ...sources.map((source) => `- ${source.path}: ${source.sha256}`),
     ...missingSources.map((path) => `- ${path}: 없음(이 설치본에 미포함)`),
     '',
   ];
   const body = lines.join('\n');
-  return { role, version, sha256: sha256(body), body, includedCardIds: cards.map(([id]) => id), excludedCardIds: [], sources, missingSources };
+  return { role, version, sha256: sha256(body), body, includedCardIds: cards.map(([id]) => id), excludedCardIds: knowhow.excluded, sources, missingSources };
 }
 
 /** Prompt body consumed by coordinator and guardian agents. */

package/scripts/cron-run.ts

@@ -16,7 +16,7 @@ import { ensureCronNodePath } from '../src/domains/cron-path.js';
 ensureCronNodePath();
 
 async function main(): Promise<void> {
-  const argv = process.argv.slice(2);
+  const { argv, maxRuntimeMs } = extractMaxRuntimeArgs(process.argv.slice(2)); // 래퍼 옵션은 대상 앞에서만 소비한다.
   const hasScheduleId = argv[0] === '--schedule-id';
   const scheduleId = hasScheduleId ? argv.splice(0, 2)[1] : undefined;
   if (hasScheduleId && (!scheduleId?.trim() || scheduleId === '--shell')) {
@@ -90,6 +90,9 @@ async function main(): Promise<void> {
   const child = spawn(interpreter, [target, ...targetArgs], {
     stdio: ['ignore', 'inherit', 'pipe'],
     env: { ...process.env },
+    // ⓐ detached — 자식이 프로세스 그룹 리더가 된다. 상한 초과 kill 은 그룹 전체
+    // (자식의 자식까지)를 죽린다: process.kill(-pid).
+    detached: true,
   });
   let errTail = '';
   child.stderr?.on('data', (chunk: Buffer) => {
@@ -97,14 +100,53 @@ async function main(): Promise<void> {
     errTail = (errTail + chunk.toString()).slice(-2000); // 바운디드
   });
 
+  // ⓐ 상한 타이머 — 넘으면 자식 프로세스 그룹 전체를 SIGKILL 하고 관측 플래그를 올린다.
+  // 진단(stderr 한 줄)은 여기서, 관측 기록은 기존 finish() 경로가 그대로 맡는다(fail-open 불변).
+  // ⚠ 리더가 이미 종료했다고 조기 반환하지 않는다(리뷰 must-fix): 리더만 죽고 손자가 stderr
+  //   파이프를 쥔 채 남으면 close 가 영영 안 와 관측도 반환도 없다. 이 경로에서도 그룹(트리)
+  //   종료를 시도하고, close 가 오지 않으면 finish 를 직접 불러 관측·반환을 마무리한다.
+  let overrun = false;
+  let finished = false;
+  let forwardedExit: number | null = null;
+  let signalKillTimer: ReturnType<typeof setTimeout> | null = null;
+  const timer: ReturnType<typeof setTimeout> | null = maxRuntimeMs > 0
+    ? setTimeout(() => {
+        if (child.pid === undefined || finished) return;
+        overrun = true;
+        const leaderGone = child.exitCode !== null || child.signalCode !== null;
+        try { process.stderr.write(`cron-run overrun: ${maxRuntimeMs}ms 상한 초과 — 자식 트리(pid ${child.pid}) 종료${leaderGone ? ' — 리더 이미 종료, 파이프를 쥔 손자 정리' : ''}\n`); } catch { /* */ }
+        try { process.kill(-child.pid, 'SIGKILL'); }
+        catch { try { child.kill('SIGKILL'); } catch { /* 이미 종료 */ } }
+        // 그룹 밖(setsid) 잔존자가 파이프를 계속 쥐면 close 가 오지 않는다 — 관측까지 여기서
+        // 마무리한다. close 가 정상적으로 오면 finish 의 멱등 가드가 이 호출을 흡수한다.
+        setTimeout(() => finish(child.exitCode), OVERRUN_CLOSE_GRACE_MS);
+      }, maxRuntimeMs)
+    : null;
+
   const finish = (code: number | null): void => {
-    const exit = code ?? 0;
+    if (finished) return; // 멱등 — close·error·상한 유예 경로가 겹쳐도 관측·반환은 1회
+    finished = true;
+    // 신호를 받은 뒤 리더가 먼저 닫혀도, SIGTERM을 무시하고 stdio를 닫은 손자가
+    // 그룹에 남을 수 있다. close가 온 시점에도 그룹 전체를 마지막으로 거둔다.
+    if (forwardedExit !== null && child.pid !== undefined) {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { /* 그룹 이미 종료 */ }
+    }
+    if (timer !== null) clearTimeout(timer);
+    if (signalKillTimer !== null) clearTimeout(signalKillTimer);
+    process.removeListener('SIGINT', onSigInt);
+    process.removeListener('SIGTERM', onSigTerm);
+    const exit = overrun ? 124 : forwardedExit ?? code ?? 0;
     try {
       const durationMs = Date.now() - start;
       const status: 'ok' | 'error' = exit === 0 ? 'ok' : 'error';
+      const overrunNote = overrun
+        ? `cron-run overrun: killed ${target} (pid ${child.pid ?? '?'}) after ${durationMs}ms — cap ${maxRuntimeMs}ms`
+        : null;
       const record = {
         status, exit, durationMs, via: 'crontab' as const,
-        error: exit === 0 ? null : errTail.trim().split('\n').slice(-3).join('\n') || `exit ${exit}`,
+        error: overrunNote
+          ? [overrunNote, ...errTail.trim().split('\n').slice(-3).filter(Boolean)].join('\n')
+          : exit === 0 ? null : errTail.trim().split('\n').slice(-3).join('\n') || `exit ${exit}`,
       };
       const options = { ...(db ? { db } : {}), ...(id ? { id } : {}), prevStatus };
       const diagnostic = (kind: 'prerequisite' | 'registry record skipped' | 'registry selection ambiguous' | 'import' | 'record', error: unknown): Promise<void> => {
@@ -144,8 +186,59 @@ async function main(): Promise<void> {
       process.exit(exit);
     }
   };
+  const forwardSignal = (signal: 'SIGINT' | 'SIGTERM'): void => {
+    if (finished || forwardedExit !== null) return;
+    forwardedExit = signal === 'SIGINT' ? 130 : 143;
+    if (child.pid === undefined) { finish(forwardedExit); return; }
+    try { process.kill(-child.pid, signal); }
+    catch { try { child.kill(signal); } catch { /* 이미 종료 */ } }
+    signalKillTimer = setTimeout(() => {
+      try { process.kill(-child.pid!, 'SIGKILL'); }
+      catch { try { child.kill('SIGKILL'); } catch { /* 이미 종료 */ } }
+      finish(forwardedExit);
+    }, OVERRUN_CLOSE_GRACE_MS);
+  };
+  const onSigInt = (): void => forwardSignal('SIGINT');
+  const onSigTerm = (): void => forwardSignal('SIGTERM');
+  process.on('SIGINT', onSigInt);
+  process.on('SIGTERM', onSigTerm);
   child.on('close', finish);
   child.on('error', (e) => { process.stderr.write(`cron-run spawn error: ${e.message}\n`); finish(1); });
 }
 
+const MAX_TIMER_MS = 2_147_483_647;
 void main().catch(() => process.exit(0));
+
+// ⓐ LOGS-RETENTION-46MIN: 실행 시간 상한 — 상한 없이 살아남은 옛 판 크론이 6시간마다
+// «오래된 행 50%» 삭제를 겹쳐 돌려 보존 창을 무너뜨린 사고(10-12)의 재발 방지.
+// 우선순위: --max-runtime-ms > CRON_RUN_MAX_RUNTIME_MS > 기본 30분. 0 이하는 상한 끔.
+//
+// 래퍼 플래그는 대상 앞에서만 읽는다. 대상 뒤의 같은 이름은 자식 인자다.
+// ⚠ main() 안쪽이 아니라 여기(helper)에 두는 이유: main() 머리에 줄을 늘리면 위쪽
+//   registerLogStoreSink 호출의 줄번호가 움직여 log-store-retention-callers.test.ts
+//   가 git 색인과 대비하는 검사를 깬다(부메랑).
+function extractMaxRuntimeArgs(argv: string[]): { argv: string[]; maxRuntimeMs: number } {
+  const args = [...argv];
+  if (args[0] === '--schedule-id') args.splice(0, 2);
+  if (args[0] === '--max-runtime-ms') {
+    const raw = args[1];
+    const parsed = Number(raw);
+    if (!raw || !Number.isSafeInteger(parsed) || parsed < 0 || parsed > MAX_TIMER_MS) {
+      process.stderr.write(`cron-run: --max-runtime-ms 인자는 0~${MAX_TIMER_MS} 사이의 정수여야 합니다\n`);
+      process.exit(2);
+    }
+    const flagIndex = argv.indexOf('--max-runtime-ms');
+    return { argv: argv.filter((_, index) => index !== flagIndex && index !== flagIndex + 1), maxRuntimeMs: parsed };
+  }
+  const rawEnv = process.env.CRON_RUN_MAX_RUNTIME_MS;
+  const fromEnv = Number(rawEnv);
+  if (rawEnv?.trim() && fromEnv > MAX_TIMER_MS) {
+    process.stderr.write(`cron-run: CRON_RUN_MAX_RUNTIME_MS 인자는 0~${MAX_TIMER_MS} 사이의 정수여야 합니다\n`);
+    process.exit(2);
+  }
+  return { argv, maxRuntimeMs: rawEnv?.trim() && Number.isSafeInteger(fromEnv) && fromEnv >= 0 && fromEnv <= MAX_TIMER_MS ? fromEnv : 30 * 60_000 };
+}
+
+// ⓐ 상한 시점의 그룹 종료 뒤에도 close 가 오지 않는 경로(파이프를 쥔 그룹 밖 손자)에서
+// 관측(finish)을 마무리할 때까지 기다리는 유예.
+const OVERRUN_CLOSE_GRACE_MS = 2_000;