elanous 0.2.17 → 0.2.19

package/src/nexus/api/ops-api.ts

@@ -18,13 +18,35 @@ let seatsCache: ReturnType<typeof createSeatsCache> | null = null;
 export function setSeatsCacheForTest(cache: ReturnType<typeof createSeatsCache> | null): void { seatsCache = cache; }
 const LOG_PATH = /^\/v1\/ops\/release\/runs\/([^/]+)\/nodes\/([^/]+)\/log$/;
 
-interface RunNode { nodeId: string; ok?: unknown; output?: unknown }
+interface RunNode { nodeId: string; ok?: unknown; output?: unknown; startedAt?: unknown; endedAt?: unknown }
 interface RunRecord {
   status: string;
   path: string[];
   startedAt: string;
   input?: unknown;
   nodes: RunNode[];
+  currentNode?: { nodeId?: unknown; startedAt?: unknown };
+}
+
+/** Node times come only from the ledger (GRAPH-NODE-TIMES); older ledgers have none and the screen says so. */
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+function isoTime(value: unknown): string | undefined {
+  return typeof value === 'string' && ISO_TIME.test(value) && Number.isFinite(Date.parse(value)) ? value : undefined;
+}
+
+function nodeTimes(node: RunNode): { startedAt?: string; endedAt?: string } {
+  const startedAt = isoTime(node.startedAt);
+  const endedAt = isoTime(node.endedAt);
+  return { ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}) };
+}
+
+/** The running node has no record yet — show it with its start time when the ledger names it as the path tail. */
+function runningNode(run: RunRecord, recorded: number): Array<{ nodeId: string; ok: null; summary: string; startedAt: string }> {
+  const current = run.currentNode;
+  const startedAt = isoTime(current?.startedAt);
+  if (run.status !== 'running' || !startedAt || typeof current?.nodeId !== 'string' ||
+      run.path.length !== recorded + 1 || run.path.at(-1) !== current.nodeId) return [];
+  return [{ nodeId: redactSecretText(current.nodeId), ok: null, summary: '', startedAt }];
 }
 
 function recordAt(path: string): RunRecord | null {
@@ -66,6 +88,77 @@ function runVersion(input: unknown): string | null {
   return typeof version === 'string' && VERSION.test(version) ? version : null;
 }
 
+/** Facts away mode prints for a node — only built when asked, so the HTTP shape stays as it was. */
+export interface ReleaseNodeFacts { verdict?: string; introduced?: number; preexisting?: number; waiver?: string }
+export interface ReleaseRunNodeView {
+  nodeId: string; ok: boolean | null; summary: string; startedAt?: string; endedAt?: string; facts?: ReleaseNodeFacts;
+}
+
+function parsedOutput(output: unknown): Record<string, unknown> | null {
+  let value = output;
+  if (typeof value === 'string') {
+    const text = value;
+    try { value = JSON.parse(text) as unknown; }
+    catch {
+      const last = text.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+      try { value = JSON.parse(last ?? '') as unknown; } catch { return null; }
+    }
+  }
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+export function releaseNodeFacts(output: unknown): ReleaseNodeFacts {
+  const value = parsedOutput(output);
+  if (!value) return {};
+  const verdict = typeof value.verdict === 'string' ? value.verdict : typeof value.outcome === 'string' ? value.outcome : undefined;
+  const introduced = Array.isArray(value.introduced) ? value.introduced.length : typeof value.introduced === 'number' ? value.introduced : undefined;
+  const preexisting = typeof value.preexisting === 'number' ? value.preexisting : undefined;
+  const waiver = typeof value.waiver === 'string' && value.waiver.trim() ? redactSecretText(value.waiver).slice(0, 200) : undefined;
+  return {
+    ...(verdict ? { verdict: redactSecretText(verdict).slice(0, 40) } : {}),
+    ...(introduced !== undefined ? { introduced } : {}),
+    ...(preexisting !== undefined ? { preexisting } : {}),
+    ...(waiver ? { waiver } : {}),
+  };
+}
+export interface ReleaseRunView {
+  runId: string; status: string; startedAt: string; version: string | null; path: string[]; nodes: ReleaseRunNodeView[];
+}
+
+/** The release run ledger as `/v1/ops/release/runs` serves it (newest 20) — shared with Telegram /release and away mode
+ *  so every surface reads the same verdicts. `'unavailable'` = the directory exists but cannot be read. */
+export function readReleaseRuns(version: string | null = null,
+  dir: string = join(effectiveInstanceRoot(), 'graph-runs', 'release-loop'),
+  opts: { facts?: boolean } = {}): ReleaseRunView[] | 'unavailable' {
+  let filenames: string[];
+  try {
+    filenames = readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json')
+        && IDENTIFIER.test(entry.name.slice(0, -5)))
+      .map((entry) => entry.name);
+  }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    return 'unavailable';
+  }
+  return filenames.flatMap((filename) => {
+    const run = recordAt(join(dir, filename));
+    if (!run) return [];
+    const v = runVersion(run.input);
+    if (version !== null && v !== version) return [];
+    return [{
+      runId: redactSecretText(filename.slice(0, -5)), status: redactSecretText(run.status),
+      startedAt: redactSecretText(run.startedAt), version: v,
+      path: run.path.filter((step): step is string => typeof step === 'string').map(redactSecretText),
+      nodes: [...run.nodes.filter((node) => node && typeof node.nodeId === 'string').map((node) => ({
+        nodeId: redactSecretText(node.nodeId), ok: typeof node.ok === 'boolean' ? node.ok : null,
+        summary: nodeSummary(node.output), ...nodeTimes(node),
+        ...(opts.facts ? { facts: releaseNodeFacts(node.output) } : {}),
+      })), ...runningNode(run, run.nodes.length)],
+    }];
+  }).sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, 20);
+}
+
 /** The sole data gate for every read-only /v1/ops endpoint. */
 export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Response | Promise<Response> {
   const url = new URL(req.url);
@@ -103,33 +196,8 @@ export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Re
   }
   if (pathname === '/v1/ops/release/runs') {
     if (version !== null && !VERSION.test(version)) return jsonResponse({ error: 'invalid-version' }, 400);
-    const dir = join(effectiveInstanceRoot(), 'graph-runs', 'release-loop');
-    let filenames: string[];
-    try {
-      filenames = readdirSync(dir, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.json')
-          && IDENTIFIER.test(entry.name.slice(0, -5)))
-        .map((entry) => entry.name);
-    }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return served(jsonResponse([]));
-      return jsonResponse({ error: 'runs-unavailable' }, 500);
-    }
-    const runs = filenames.flatMap((filename) => {
-      const run = recordAt(join(dir, filename));
-      if (!run) return [];
-      const v = runVersion(run.input);
-      if (version !== null && v !== version) return [];
-      return [{
-        runId: redactSecretText(filename.slice(0, -5)), status: redactSecretText(run.status),
-        startedAt: redactSecretText(run.startedAt), version: v,
-        path: run.path.filter((step): step is string => typeof step === 'string').map(redactSecretText),
-        nodes: run.nodes.filter((node) => node && typeof node.nodeId === 'string').map((node) => ({
-          nodeId: redactSecretText(node.nodeId), ok: typeof node.ok === 'boolean' ? node.ok : null,
-          summary: nodeSummary(node.output),
-        })),
-      }];
-    }).sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, 20);
+    const runs = readReleaseRuns(version);
+    if (runs === 'unavailable') return jsonResponse({ error: 'runs-unavailable' }, 500);
     return served(jsonResponse(runs));
   }
   // WHATWG URL normalizes a literal runs/../nodes/... before routing.

package/src/nexus/api/ops-seats-sources.ts

@@ -2,7 +2,7 @@
 // removed — same rule as decision replies), the release checklist, and the decision ledger. Each failure becomes null upstream.
 import { DecisionLedger } from '../../decisions/decision-ledger.js';
 import { listCoordEvents, type CoordEvent } from '../../context-bus/coord-events.js';
-import { devVersion, listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
+import { checklistDevVersion, listChecklist, type ChecklistItem } from '../../release-loop/checklist.js';
 import { getUserConfig } from '../../user-config.js';
 import { SEATS, kstDayRange, type ChannelComment, type ChannelSource, type MergedPr, type SeatsSources } from './ops-seats.js';
 
@@ -82,7 +82,7 @@ export function liveSeatsSources(deps: { listEvents?: typeof listCoordEvents; gi
       return lines?.map((line) => JSON.parse(line) as MergedPr) ?? null;
     },
     checklist() {
-      const dev = devVersion();
+      const dev = checklistDevVersion();
       const next = listChecklist(nextPatch(dev)).items;
       const current = listChecklist(dev).items;
       const all: ChecklistItem[] = [...current, ...next];

package/src/nexus/api/workflow-templates.ts

@@ -4,6 +4,7 @@
 
 import { readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { debug } from '../../debug/log.js';
 import { jsonResponse } from './http-server.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 
@@ -47,6 +48,8 @@ export function listTemplateCatalog(dir = findTemplateDir()): WorkflowTemplateEn
   try {
     files = readdirSync(dir).filter((f) => f.endsWith('.yaml'));
   } catch {
+    // An installed package without this folder used to answer «No templates available» silently (10-06 · files list).
+    debug.log('nexus.workflow-templates', 'template-dir-missing', { dir });
     return [];
   }
   const out: WorkflowTemplateEntry[] = [];

package/src/nexus/index.ts

@@ -136,6 +136,7 @@ import {
   type DailyReflectionSchedulerHandle,
 } from '../notes/daily-reflection-scheduler.js';
 import { type ScheduleRunnerHandle } from '../domains/schedule-runner.js';
+import { startWatchDefaultScheduler } from '../domains/watch-default-scheduler.js';
 import { resolvePwaStaticDir } from './static-dir-resolve.js';
 import {
   createHitlPendingCallbacks,
@@ -1310,6 +1311,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   // the daily-reflection scheduler regardless of which branch booted
   // it. Tests with detachForTesting set leave this undefined.
   let dailyReflectionScheduler: DailyReflectionSchedulerHandle | undefined;
+  let watchDefaultScheduler: ReturnType<typeof startWatchDefaultScheduler> | undefined;
   // RFC #2161 FU A8 (2026-05-11) — discovery cron via NEXUS. Dormant
   // by default (opt-in via `ELANOUS_DISCOVERY_CRON_INTERVAL_MS`); when
   // configured, fires runDiscovery every interval and pushes the
@@ -3198,6 +3200,8 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
       //  schedule migrate 로 이관.) 롤백: 아래 한 줄 복원.
       // try { scheduleRunner = startScheduleRunner(); } catch { /* fail-soft */ }
       void scheduleRunner; // 은퇴(undefined 유지)
+      try { watchDefaultScheduler = startWatchDefaultScheduler(); }
+      catch (error) { debug.log('watch.default', 'failed', { stage: 'boot', reason: error instanceof Error ? error.message : String(error) }); }
     }
   }
 
@@ -3335,6 +3339,9 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     }
     // S2 (2026-07-07) · stop the schedule runner so its node-cron tasks +
     // reconcile interval don't keep firing/holding the loop past shutdown.
+    if (watchDefaultScheduler) {
+      try { watchDefaultScheduler.stop(); } catch { /* swallow */ }
+    }
     if (scheduleRunner) {
       try { scheduleRunner.stop(); } catch { /* swallow */ }
     }

package/src/oauth/codex.ts

@@ -554,6 +554,44 @@ export function codexAccessHoursLeft(accessToken: unknown, now: number = Date.no
   return typeof exp === 'number' ? Math.round(((exp * 1000 - now) / 3_600_000) * 10) / 10 : null;
 }
 
+/** PREREFRESH-LOCK (10-06 · post-review of #24449) — the per-account host refresh lock path.
+ *  🩸 Two Pod launches on one host picked the same expiring account at once: both refreshed, the server
+ *  rotated the refresh token under the second, its refresh failed and that run dropped the account.
+ *  The lock file sits NEXT TO the account's credential state (`<codexHome>/.elanous-prerefresh.lock`) —
+ *  ⛔ never inside a token file, and it carries only the holder's pid/nonce. null = no named home to lock. */
+export function codexAccountRefreshLockPath(name: string, storePath: string = authStorePath()): string | null {
+  if (name === DEFAULT_CODEX_ACCOUNT || !isValidAccountName(name)) return null;
+  const codexHome = loadTokens(codexStoreKey(name), storePath)?.codexHome;
+  return codexHome ? join(codexHome, '.elanous-prerefresh.lock') : null;
+}
+
+/** A refresh (network + rotate + atomic write + import) can take tens of seconds — wait up to ~90 s,
+ *  and treat a lock as stale only after 2 min (the async holder heartbeats its mtime meanwhile). */
+export const CODEX_REFRESH_LOCK_OPTS = { staleMs: 120_000, retryBusyMs: 100, maxTries: 900 } as const;
+
+/** The refresh lock could not be acquired (timeout · ENOENT · EACCES …) — `fn` never ran, so nothing was refreshed. */
+export class CodexRefreshLockUnavailableError extends Error {
+  constructor(readonly reason: 'lock-timeout' | 'lock-error', cause: unknown) {
+    super(`codex refresh lock unavailable (${reason}): ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = 'CodexRefreshLockUnavailableError';
+  }
+}
+
+/** Runs `fn` while holding the account's refresh lock (cross-process · same-process). null path = no lock.
+ *  Any failure to acquire the lock throws `CodexRefreshLockUnavailableError` (fn not run); fn's own errors pass through. */
+export async function withCodexAccountRefreshLock<T>(lockPath: string | null, fn: () => Promise<T>, opts: { staleMs?: number; retryBusyMs?: number; maxTries?: number } = CODEX_REFRESH_LOCK_OPTS): Promise<T> {
+  if (!lockPath) return fn();
+  const { acquireLockAsync } = await import('../storage/file-lock.js');
+  let handle: Awaited<ReturnType<typeof acquireLockAsync>>;
+  try { handle = await acquireLockAsync(lockPath, opts); }
+  catch (error) {
+    const timedOut = error instanceof Error && error.message.startsWith('acquireLockAsync: timed out');
+    throw new CodexRefreshLockUnavailableError(timedOut ? 'lock-timeout' : 'lock-error', error);
+  }
+  try { return await fn(); }
+  finally { handle.release(); }
+}
+
 export async function refreshCodexAccountHome(
   name: string,
   opts: {

package/src/onboarding/first-chat-gate.ts

@@ -0,0 +1,29 @@
+import { debug } from '../debug/log.js';
+import { needsFirstRun, needsOnboarding } from '../onboarding.js';
+import type { UserConfig } from '../user-config.js';
+import type { FirstRunDeps, runFirstRun } from './first-run.js';
+import { UNATTENDED_SETUP_COMMAND } from './entry-hints.js';
+
+export interface FirstChatGateDeps {
+  isTTY: boolean;
+  runFirstRun: (deps: FirstRunDeps) => ReturnType<typeof runFirstRun>;
+  runInteractive: () => Promise<boolean>;
+  print: (line: string) => void;
+}
+
+export async function firstChatGate(cfg: UserConfig, deps: FirstChatGateDeps): Promise<'continue' | 'stop'> {
+  const decide = (decision: 'continue' | 'stop', outcome: string): 'continue' | 'stop' => {
+    debug.log('onboarding.first-chat', decision, { isTTY: deps.isTTY, outcome });
+    return decision;
+  };
+  if (!needsOnboarding(cfg)) return decide('continue', 'completed');
+  if (deps.isTTY) {
+    return decide(await deps.runInteractive() ? 'continue' : 'stop', 'interactive');
+  }
+  if (!needsFirstRun(cfg)) return decide('continue', 'already-ready');
+  const result = await deps.runFirstRun({ config: cfg, isTTY: false, print: () => {} });
+  if (result.outcome === 'ready') return decide('continue', result.outcome);
+  deps.print(`다음: elanous setup llm (또는 ${UNATTENDED_SETUP_COMMAND})`);
+  process.exitCode = 2;
+  return decide('stop', result.outcome);
+}

package/src/release-loop/checklist.ts

@@ -1,5 +1,6 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import * as store from './feature-store.js';
 import { debug } from '../debug/log.js';
 import { CliUserError } from '../cli/cli-user-error.js';
@@ -20,6 +21,8 @@ export interface ChecklistItem {
   ceoDate?: string;
   /** 다른 칸의 처리량을 올리는 칸(자율성·효율성·동시성). 없으면 가속 등급이 아니다. */
   accelerator?: true;
+  /** 이 칸이 근거로 삼는 문서(저장소 상대 경로, 선택적으로 `#절`). 없으면 칸에 실리지 않는다. */
+  refs?: string[];
   evidence?: string;
   disposition?: ChecklistDisposition;
   kind?: ChecklistKind;
@@ -37,6 +40,7 @@ export interface ChecklistHistory {
   dev: string;
   force?: true;
   reason?: string;
+  generation?: number;
 }
 export interface Checklist {
   version: string;
@@ -50,6 +54,12 @@ export function devVersion(): string {
   return (JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version: string }).version;
 }
 
+/** The checklist version of the development tree: package.json says `0.2.18-dev.0` once a release branch is cut,
+ * but the checklist only knows `0.2.18` (10-07: every server caller that passed devVersion() raw got null/throw). */
+export function checklistDevVersion(version = devVersion()): string {
+  return version.replace(/-dev\.\d+$/, '');
+}
+
 export function parseOwner(value: string): { seat: string; sub?: string } {
   const match = /^([A-Z]{2,8})(?:\/([a-z][a-z0-9-]{0,31}))?$/.exec(value);
   if (!match || match[0] !== value) throw new CliUserError(`잘못된 담당: ${value}`, 'TC 또는 TC/rel');
@@ -92,6 +102,7 @@ export function statusChangesSince(history: readonly ChecklistHistory[], sinceIs
 }
 
 function mutate(v: string, apply: (data: Checklist, otherItems: (id: string) => store.ChecklistCollision[]) => boolean): Checklist {
+  // addItem/setItem/claimItem/removeItem/seedFromRoadmap reach the generation-fenced ledger write here.
   return decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply));
 }
 
@@ -100,12 +111,82 @@ function change(data: Checklist, id: string, field: string, from: unknown, to: u
   debug.log('release-loop.checklist', 'change', { version: data.version, id, field, from: from ?? null, to: to ?? null, by });
 }
 
+const REPO_ROOT = join(import.meta.dir, '..', '..');
+
+/** `--ref` 문서를 찾는 뿌리들 — 이 코드의 트리 ⊕ 지금 작업 디렉토리의 git 뿌리.
+ *  ⭐ 설치본(`~/.local/share/elanous/current`)에는 `docs/` 가 없다 — 저장소 안에서 부른 설치본도 저장소 문서를 인용할 수 있게. */
+export function refRoots(cwd = process.cwd()): string[] {
+  const roots = [REPO_ROOT];
+  try {
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 5_000 });
+    const path = top.status === 0 ? top.stdout.trim() : '';
+    if (path && !roots.includes(path)) roots.push(path);
+  } catch { /* git 없음 — 코드 트리만 */ }
+  return roots;
+}
+
+/** `--ref` 값 검사: 저장소 상대 경로(⊕ `#절`)이고 그 파일이 뿌리들 중 하나에 있어야 한다. 중복은 순서를 지키며 지운다. */
+export function normalizeRefs(refs: readonly string[], root: string | readonly string[] = refRoots()): string[] {
+  const roots = typeof root === 'string' ? [root] : root;
+  const out: string[] = [];
+  for (const raw of refs) {
+    const ref = raw.trim();
+    const path = ref.split('#')[0] ?? '';
+    if (!path || isAbsolute(path) || path.split(/[\\/]/).some((part) => part === '..')) throw new CliUserError(`잘못된 문서 참조: ${raw}`, '저장소 상대 경로[#절] — 예: docs/manual/MANUAL-x.md#§1');
+    let isFile = false;
+    for (const base of roots) {
+      try { if (statSync(join(base, path)).isFile()) { isFile = true; break; } } catch { /* 없음 */ }
+    }
+    if (!isFile) throw new CliUserError(`없는 문서: ${path}`, '저장소 상대 «파일» 경로로 준다(폴더는 안 된다)');
+    if (!out.includes(ref)) out.push(ref);
+  }
+  return out;
+}
+
+/** 한 문서를 인용하는 칸 한 줄 — `release checklist refs <doc>` 의 «구현 현황» 행. */
+export interface DocRefRow { version: string; id: string; title: string; status: ChecklistStatus; owner: string | null; section: string | null }
+
+function splitRef(ref: string): { path: string; section: string | null } {
+  const at = ref.indexOf('#');
+  const path = (at < 0 ? ref : ref.slice(0, at)).trim().replace(/^\.\//, '');
+  return { path, section: at < 0 ? null : ref.slice(at + 1) };
+}
+
+/** 읽기 전용: 칸의 refs 중 경로(`#` 앞)가 doc 의 경로와 같은 것을 행으로 낸다. doc 에 `#절`이 붙으면 그 절과 정확히 같은 ref 만. */
+export function cellsReferencingDoc(doc: string, checklists: readonly Checklist[]): DocRefRow[] {
+  const want = splitRef(doc.trim());
+  const rows: DocRefRow[] = [];
+  for (const data of checklists) {
+    for (const item of data.items) {
+      // 칸마다 한 행 — 같은 문서의 절을 여럿 인용해도 절을 모아 한 줄로(절 없는 인용이 섞이면 문서 전체로 본다).
+      const sections: string[] = [];
+      let whole = false;
+      for (const ref of item.refs ?? []) {
+        const got = splitRef(ref);
+        if (got.path !== want.path) continue;
+        if (want.section !== null && got.section !== want.section) continue;
+        if (got.section === null) whole = true;
+        else if (!sections.includes(got.section)) sections.push(got.section);
+      }
+      if (!whole && sections.length === 0) continue;
+      rows.push({ version: data.version, id: item.id, title: item.title, status: item.status, owner: item.owner ?? null, section: whole ? null : sections.join(' · ') });
+    }
+  }
+  return rows;
+}
+
+/** `| 판 | 칸 | 상태 | 절 | 제목 |` 마크다운 표 — 행이 없으면 머리줄 둘만. */
+export function renderRefsStatus(rows: readonly DocRefRow[]): string {
+  const cell = (value: string) => value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+  return ['| 판 | 칸 | 상태 | 절 | 제목 |', '| --- | --- | --- | --- | --- |', ...rows.map((row) => `| ${cell(row.version)} | ${cell(row.id)} | ${row.status} | ${cell(row.section ?? '-')} | ${cell(row.title)} |`)].join('\n');
+}
+
 export function validateCeoLoad(input: { ceoMinutes?: number; ceoDate?: string }): void {
   if (input.ceoMinutes !== undefined && (!Number.isSafeInteger(input.ceoMinutes) || input.ceoMinutes < 0)) throw new CliUserError('대표 손 분량은 0 이상의 정수 분이어야 한다');
   if (input.ceoDate !== undefined && (!/^\d{4}-\d{2}-\d{2}$/.test(input.ceoDate) || !Number.isFinite(Date.parse(`${input.ceoDate}T00:00:00Z`)) || new Date(`${input.ceoDate}T00:00:00Z`).toISOString().slice(0, 10) !== input.ceoDate)) throw new CliUserError('대표 손 날짜는 YYYY-MM-DD 이어야 한다');
 }
 
-export function addItem(v: string, input: { id: string; title: string; owner?: string; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean }, options: { allowDuplicateId?: boolean } = {}): Checklist {
+export function addItem(v: string, input: { id: string; title: string; refs?: string[]; owner?: string; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean }, options: { allowDuplicateId?: boolean } = {}): Checklist {
   if (!input.id.trim()) throw new CliUserError('칸 id 가 비었다');
   if (!input.title.trim()) throw new CliUserError('칸 제목이 비었다');
   if (input.kind !== undefined && input.kind !== 'screen') throw new CliUserError(`잘못된 종류: ${input.kind}`, 'screen');
@@ -115,6 +196,7 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
   if (input.deadlineVersion !== undefined) store.validateVersion(input.deadlineVersion);
   if (input.accelerator !== undefined && input.accelerator !== true) throw new CliUserError('가속 등급은 true 이거나 생략한다');
   validateCeoLoad(input);
+  const refs = input.refs !== undefined && input.refs.length ? normalizeRefs(input.refs) : undefined;
   return mutate(v, (data, otherItems) => {
     if (data.items.some((item) => item.id === input.id)) throw new CliUserError(`이미 있는 칸: ${input.id}`, 'set <id> 로 고친다');
     const collisions = otherItems(input.id);
@@ -125,14 +207,14 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
     }
     const by = process.env.ELANOUS_TRACK || 'cli';
     const at = new Date().toISOString();
-    const item: ChecklistItem = { id: input.id, title: input.title, status: 'yellow', ...(input.owner !== undefined ? { owner: input.owner } : {}), ...(input.kind !== undefined ? { kind: input.kind } : {}), ...(input.priority !== undefined ? { priority: input.priority } : {}), ...(input.predecessors !== undefined ? { predecessors: input.predecessors } : {}), ...(input.deadlineVersion !== undefined ? { deadlineVersion: input.deadlineVersion } : {}), ...(input.ceoMinutes !== undefined ? { ceoMinutes: input.ceoMinutes } : {}), ...(input.ceoDate !== undefined ? { ceoDate: input.ceoDate } : {}), ...(input.accelerator === true ? { accelerator: true as const } : {}), updatedAt: at, updatedBy: by };
+    const item: ChecklistItem = { id: input.id, title: input.title, status: 'yellow', ...(input.owner !== undefined ? { owner: input.owner } : {}), ...(input.kind !== undefined ? { kind: input.kind } : {}), ...(input.priority !== undefined ? { priority: input.priority } : {}), ...(input.predecessors !== undefined ? { predecessors: input.predecessors } : {}), ...(input.deadlineVersion !== undefined ? { deadlineVersion: input.deadlineVersion } : {}), ...(input.ceoMinutes !== undefined ? { ceoMinutes: input.ceoMinutes } : {}), ...(input.ceoDate !== undefined ? { ceoDate: input.ceoDate } : {}), ...(input.accelerator === true ? { accelerator: true as const } : {}), ...(refs ? { refs } : {}), updatedAt: at, updatedBy: by };
     data.items.push(item);
     change(data, item.id, 'add', null, item, by, at);
     return true;
   });
 }
 
-export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
+export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; refs?: string[]; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
   return mutate(v, (data) => {
     const item = data.items.find((i) => i.id === id);
     if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
@@ -144,13 +226,15 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
     if (patch.deadlineVersion !== undefined) store.validateVersion(patch.deadlineVersion);
     if (patch.accelerator !== undefined && patch.accelerator !== true && patch.accelerator !== null) throw new CliUserError('가속 등급은 true(부여) 또는 null(해제)이다');
     validateCeoLoad(patch);
+    // --ref 는 «더하기»다 — 기존 참조 뒤에 붙이고 중복을 지운다.
+    if (patch.refs !== undefined) patch = { ...patch, refs: normalizeRefs([...(item.refs ?? []), ...patch.refs]) };
     if (patch.owner !== undefined) {
       parseOwner(patch.owner);
       if (item.owner && patch.owner !== item.owner) {
         throw new CliUserError(`지금 주인: ${item.owner} — --force 로만 바꾼다`, 'release checklist claim <id> --by <자리> --force');
       }
     }
-    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
+    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
     if (fields.length === 0) return false;
     const at = new Date().toISOString();
     for (const field of fields) {
@@ -269,6 +353,22 @@ export function checklistGate(v: string): ChecklistGate {
   return result;
 }
 
+/** GATE-ENTRY-ALIGN: the cut-time judgement shared by `release run`'s entry check and the checklist-gate node —
+ *  past the landing deadline a non-P0 yellow without a disposition is carried (moved), and a P0 yellow always blocks. */
+export function cutChecklistGate(v: string, landBy: string | null | undefined, now: Date = new Date()): ChecklistGate & { autoMoved: string[] } {
+  const items = listChecklist(v).items;
+  const overdue = landBy !== null && landBy !== undefined && now.getTime() > Date.parse(landBy);
+  const autoMoved = overdue ? items.filter((item) => item.status === 'yellow' && item.priority !== 'P0' && item.disposition === undefined).map((item) => item.id) : [];
+  const p0 = items.filter((item) => item.status === 'yellow' && item.priority === 'P0').map((item) => item.id);
+  const gate = checklistGate(v);
+  gate.undecided = gate.undecided.filter((id) => !autoMoved.includes(id) && !p0.includes(id));
+  gate.moved = gate.moved.filter((id) => !p0.includes(id)).concat(autoMoved);
+  gate.knownIssues = gate.knownIssues.filter((item) => !p0.includes(item.id));
+  gate.blocked.push(...p0.filter((id) => !gate.blocked.includes(id)));
+  gate.ok = gate.red.length === 0 && gate.undecided.length === 0 && gate.blocked.length === 0;
+  return { ...gate, autoMoved };
+}
+
 export function seedFromRoadmap(v: string, markdown: string): Checklist {
   return mutate(v, (data) => {
     let added = false;