elanous 0.2.18 → 0.2.20

package/src/onboarding/entry-hints.ts

@@ -5,4 +5,9 @@ export function unattendedSetupHint(): string {
   return `unattended: \`${UNATTENDED_SETUP_COMMAND}\``;
 }
 
+/** One-line next step printed after a non-TTY onboarding refusal (FIRST-CHAT-NONTTY). */
+export function unattendedNextStepLine(): string {
+  return `next: ${unattendedSetupHint()}`;
+}
+
 export const SKILLS_LIST_DESCRIPTION = 'List elanous skills from configured skill directories (skills.activeSet / skills.dirs and packaged skills): subdirectories and the first non-heading line of each SKILL.md. Read-only.';

package/src/onboarding.ts

@@ -59,7 +59,7 @@ import type {
 import { showStepOr, chooseFrom } from './onboarding/io-extended.js';
 import { askWithHelp } from './onboarding/wire-helpers.js';
 import { stepTransition } from './onboarding/transition.js';
-import { unattendedSetupHint } from './onboarding/entry-hints.js';
+import { unattendedNextStepLine, unattendedSetupHint } from './onboarding/entry-hints.js';
 import { continueHereLines } from './onboarding/continue-here.js';
 import type { NexusShowResult } from './cli/nexus-show.js';
 import type { TailscaleProbe } from './nexus/onboarding/tailscale-probe.js';
@@ -1370,15 +1370,33 @@ export class OnboardingRefusedError extends Error {
   }
 }
 
-/** Handle only typed refusals; the agent setup hint applies to its non-TTY path alone. */
-export function handleOnboardingRefusal(error: unknown, entrance: 'agent' | 'other'): boolean {
+export interface OnboardingRefusalIO {
+  printError: (line: string) => void;
+  setExitCode: (code: number) => void;
+}
+
+const defaultRefusalIO: OnboardingRefusalIO = {
+  printError: (line) => console.error(line),
+  setExitCode: (code) => { process.exitCode = code; },
+};
+
+/** Handle only typed refusals; the agent setup hint applies to its non-TTY path alone.
+ *  FIRST-CHAT-NONTTY: on the non-TTY path of any other entrance the refusal ends with a
+ *  one-line next step (`unattendedNextStepLine()`), so a script or app that called first knows
+ *  what to run. The exit code stays 2. */
+export function handleOnboardingRefusal(
+  error: unknown,
+  entrance: 'agent' | 'other',
+  io: OnboardingRefusalIO = defaultRefusalIO,
+): boolean {
   if (!(error instanceof OnboardingRefusedError) || error.code !== 'onboarding-refused') return false;
   if (entrance === 'agent' && error.reason === 'non-tty') {
-    console.error(`elanous agent needs a configured LLM. Run \`elanous onboarding\` in a terminal, or ${unattendedSetupHint()} for unattended setup.`);
+    io.printError(`elanous agent needs a configured LLM. Run \`elanous onboarding\` in a terminal, or ${unattendedSetupHint()} for unattended setup.`);
   } else {
-    console.error(error.message);
+    io.printError(error.message);
+    if (error.reason === 'non-tty') io.printError(unattendedNextStepLine());
   }
-  process.exitCode = 2;
+  io.setExitCode(2);
   return true;
 }
 

package/src/release-loop/checklist.ts

@@ -40,6 +40,7 @@ export interface ChecklistHistory {
   dev: string;
   force?: true;
   reason?: string;
+  generation?: number;
 }
 export interface Checklist {
   version: string;
@@ -101,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));
 }
 

package/src/release-loop/feature-store.ts

@@ -5,6 +5,8 @@ import { Database } from 'bun:sqlite';
 import { releaseLedgerRoot } from '../instance/resolve.js';
 import { CliUserError } from '../cli/cli-user-error.js';
 import { debug } from '../debug/log.js';
+import { getUserConfig } from '../user-config.js';
+import { hqSeenGenerationPath, readHqLease, readSeenGeneration } from '../hq/hq.js';
 import { devVersion, type Checklist, type ChecklistHistory, type ChecklistItem } from './checklist.js';
 
 export function validateVersion(version: string): void {
@@ -32,9 +34,9 @@ export function releasedVersion(ledgerRoot = releaseLedgerRoot()): string {
 const walWait = new Int32Array(new SharedArrayBuffer(4));
 const SCHEMA_COLUMNS: Record<string, readonly string[]> = {
   imported_versions: ['json_hash', 'imported_at'],
-  events: ['reason'],
+  events: ['reason', 'generation'],
   assignments: ['priority', 'predecessors', 'deadline_version', 'ceo_minutes', 'ceo_date', 'accelerator', 'refs'],
-  release_schedules: ['freeze_from', 'freeze_until'],
+  release_schedules: ['freeze_from', 'freeze_until', 'publish_at'],
 };
 function schemaCurrent(db: Database): boolean {
   return Object.entries(SCHEMA_COLUMNS).every(([table, names]) => {
@@ -72,23 +74,25 @@ function open(root = releaseLedgerRoot()): Database {
       const columns = db.query('PRAGMA table_info(imported_versions)').all() as Array<{ name: string }>;
       if (!columns.some((column) => column.name === 'json_hash')) db.exec('ALTER TABLE imported_versions ADD COLUMN json_hash TEXT');
       if (!columns.some((column) => column.name === 'imported_at')) db.exec('ALTER TABLE imported_versions ADD COLUMN imported_at TEXT');
-      if (!(db.query('PRAGMA table_info(events)').all() as Array<{ name: string }>).some((column) => column.name === 'reason')) db.exec('ALTER TABLE events ADD COLUMN reason TEXT');
+      const eventColumns = db.query('PRAGMA table_info(events)').all() as Array<{ name: string }>;
+      if (!eventColumns.some((column) => column.name === 'reason')) db.exec('ALTER TABLE events ADD COLUMN reason TEXT');
+      if (!eventColumns.some((column) => column.name === 'generation')) db.exec('ALTER TABLE events ADD COLUMN generation INTEGER');
       db.exec('CREATE TABLE IF NOT EXISTS release_schedules (version TEXT PRIMARY KEY, cut_at TEXT NOT NULL, land_by TEXT, updated_at TEXT NOT NULL, updated_by TEXT NOT NULL)');
       const assignmentColumns = db.query('PRAGMA table_info(assignments)').all() as Array<{ name: string }>;
       for (const [name, sql] of [['priority', 'TEXT'], ['predecessors', 'TEXT'], ['deadline_version', 'TEXT'], ['ceo_minutes', 'INTEGER'], ['ceo_date', 'TEXT'], ['accelerator', 'INTEGER'], ['refs', 'TEXT']] as const) {
         if (!assignmentColumns.some((column) => column.name === name)) db.exec(`ALTER TABLE assignments ADD COLUMN ${name} ${sql}`);
       }
       const scheduleColumns = db.query('PRAGMA table_info(release_schedules)').all() as Array<{ name: string }>;
-      for (const name of ['freeze_from', 'freeze_until']) if (!scheduleColumns.some((column) => column.name === name)) db.exec(`ALTER TABLE release_schedules ADD COLUMN ${name} TEXT`);
+      for (const name of ['freeze_from', 'freeze_until', 'publish_at']) if (!scheduleColumns.some((column) => column.name === name)) db.exec(`ALTER TABLE release_schedules ADD COLUMN ${name} TEXT`);
     }).immediate();
     return db;
   } catch (error) { db.close(); throw error; }
 }
 
-export interface ScheduleRow { version: string; cutAt: string; landBy: string | null; freezeFrom?: string | null; freezeUntil?: string | null; updatedAt: string; updatedBy: string }
-type StoredSchedule = { version: string; cut_at: string; land_by: string | null; freeze_from: string | null; freeze_until: string | null; updated_at: string; updated_by: string };
+export interface ScheduleRow { version: string; cutAt: string; landBy: string | null; freezeFrom?: string | null; freezeUntil?: string | null; publishAt?: string | null; updatedAt: string; updatedBy: string }
+type StoredSchedule = { version: string; cut_at: string; land_by: string | null; freeze_from: string | null; freeze_until: string | null; publish_at?: string | null; updated_at: string; updated_by: string };
 function scheduleRow(row: StoredSchedule): ScheduleRow {
-  return { version: row.version, cutAt: row.cut_at, landBy: row.land_by, ...(row.freeze_from ? { freezeFrom: row.freeze_from } : {}), ...(row.freeze_until ? { freezeUntil: row.freeze_until } : {}), updatedAt: row.updated_at, updatedBy: row.updated_by };
+  return { version: row.version, cutAt: row.cut_at, landBy: row.land_by, ...(row.freeze_from ? { freezeFrom: row.freeze_from } : {}), ...(row.freeze_until ? { freezeUntil: row.freeze_until } : {}), ...(row.publish_at ? { publishAt: row.publish_at } : {}), updatedAt: row.updated_at, updatedBy: row.updated_by };
 }
 
 export function readSchedule(version: string, root?: string): ScheduleRow | null {
@@ -115,7 +119,7 @@ export function assignedVersions(root = releaseLedgerRoot()): string[] {
   finally { db.close(); }
 }
 
-export function writeSchedule(version: string, patch: { cutAt?: string; landBy?: string; freezeFrom?: string; freezeUntil?: string }, by: string, root?: string): ScheduleRow {
+export function writeSchedule(version: string, patch: { cutAt?: string; landBy?: string; freezeFrom?: string; freezeUntil?: string; publishAt?: string }, by: string, root?: string): ScheduleRow {
   validateVersion(version);
   const db = open(root);
   try {
@@ -126,19 +130,22 @@ export function writeSchedule(version: string, patch: { cutAt?: string; landBy?:
       const landBy = patch.landBy ?? previous?.land_by ?? null;
       const freezeFrom = patch.freezeFrom ?? previous?.freeze_from ?? null;
       const freezeUntil = patch.freezeUntil ?? previous?.freeze_until ?? null;
+      const publishAt = patch.publishAt ?? previous?.publish_at ?? null;
+      if (publishAt && Date.parse(publishAt) <= Date.parse(cutAt)) throw new CliUserError('발행 시각은 컷보다 뒤여야 한다');
       if (Boolean(freezeFrom) !== Boolean(freezeUntil) || (freezeFrom && freezeUntil && Date.parse(freezeFrom) >= Date.parse(freezeUntil))) throw new CliUserError('동결 시작·끝은 함께 주고 시작이 끝보다 앞서야 한다');
-      if (previous && previous.cut_at === cutAt && previous.land_by === landBy && previous.freeze_from === freezeFrom && previous.freeze_until === freezeUntil) return scheduleRow(previous);
+      if (previous && previous.cut_at === cutAt && previous.land_by === landBy && previous.freeze_from === freezeFrom && previous.freeze_until === freezeUntil && (previous.publish_at ?? null) === publishAt) return scheduleRow(previous);
       const at = new Date().toISOString();
-      db.query(`INSERT INTO release_schedules (version, cut_at, land_by, freeze_from, freeze_until, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT(version) DO UPDATE SET cut_at=excluded.cut_at, land_by=excluded.land_by, freeze_from=excluded.freeze_from, freeze_until=excluded.freeze_until, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
-        .run(version, cutAt, landBy, freezeFrom, freezeUntil, at, by);
+      db.query(`INSERT INTO release_schedules (version, cut_at, land_by, freeze_from, freeze_until, publish_at, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(version) DO UPDATE SET cut_at=excluded.cut_at, land_by=excluded.land_by, freeze_from=excluded.freeze_from, freeze_until=excluded.freeze_until, publish_at=excluded.publish_at, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
+        .run(version, cutAt, landBy, freezeFrom, freezeUntil, publishAt, at, by);
       for (const [field, from, to] of [
         ['cut_at', previous?.cut_at ?? null, cutAt], ['land_by', previous?.land_by ?? null, landBy],
         ['freeze_from', previous?.freeze_from ?? null, freezeFrom], ['freeze_until', previous?.freeze_until ?? null, freezeUntil],
+        ['publish_at', previous?.publish_at ?? null, publishAt],
       ] as const) {
         if (from !== to) record(db, version, { at, by, id: '@version', field, from, to, released: releasedVersion(root), dev: devVersion() });
       }
-      return { version, cutAt, landBy, updatedAt: at, updatedBy: by };
+      return { version, cutAt, landBy, ...(publishAt ? { publishAt } : {}), updatedAt: at, updatedBy: by };
     });
   } finally { db.close(); }
 }
@@ -155,15 +162,15 @@ function readTransaction<T>(db: Database, work: () => T): T {
   catch (error) { db.exec('ROLLBACK'); throw error; }
 }
 
-type EventRow = { seq: number; at: string; by: string; feature_id: string; version: string; field: string; from: string; to: string; released: string; dev: string; reason: string | null };
+type EventRow = { seq: number; at: string; by: string; feature_id: string; version: string; field: string; from: string; to: string; released: string; dev: string; reason: string | null; generation: number | null };
 function decode(value: string | null): unknown { return value === null ? null : JSON.parse(value); }
 function historyRow(row: EventRow): ChecklistHistory {
   return { at: row.at, by: row.by, id: row.feature_id, field: row.field, from: decode(row.from), to: decode(row.to), released: row.released, dev: row.dev,
-    ...(row.reason !== null ? { reason: row.reason } : {}) };
+    ...(row.reason !== null ? { reason: row.reason } : {}), ...(row.generation !== null ? { generation: row.generation } : {}) };
 }
 function record(db: Database, version: string, entry: ChecklistHistory): void {
-  db.query('INSERT INTO events (at, by, feature_id, version, field, "from", "to", released, dev, reason) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
-    .run(entry.at, entry.by, entry.id, version, entry.field, JSON.stringify(entry.from ?? null), JSON.stringify(entry.to ?? null), entry.released, entry.dev, entry.reason ?? null);
+  db.query('INSERT INTO events (at, by, feature_id, version, field, "from", "to", released, dev, reason, generation) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+    .run(entry.at, entry.by, entry.id, version, entry.field, JSON.stringify(entry.from ?? null), JSON.stringify(entry.to ?? null), entry.released, entry.dev, entry.reason ?? null, entry.generation ?? null);
 }
 function evidenceRefs(db: Database, version: string, id: string): string[] {
   return (db.query('SELECT ref FROM evidence WHERE feature_id = ? AND version = ? ORDER BY rowid').all(id, version) as Array<{ ref: string }>).map((row) => row.ref);
@@ -334,6 +341,30 @@ export interface ChecklistCollision { version: string; owner?: string; title: st
 
 export function mutate(version: string, released: string, dev: string, apply: (data: Checklist, otherItems: (id: string) => ChecklistCollision[]) => boolean): Checklist {
   validateVersion(version);
+  // COORD-HA ①(RFC-loop-agent-map §A8b): a write carries the generation this process saw; a stale one is refused only
+  // under hq.boardFencing 'enforce' (default shadow = write and log). The lease is read ONCE, before the write transaction —
+  // with an ssh arbiter a lease read inside the transaction would hold the ledger write lock across the network.
+  // Only 'enforce' (opt-in) re-reads once inside the transaction just before writing, so a lease taken over meanwhile
+  // still rolls the write back; shadow never touches the lease under the lock.
+  const hq = getUserConfig().hq;
+  const writerGeneration = hq ? readSeenGeneration(hqSeenGenerationPath(hq)) : null;
+  let recordedGeneration: number | null = null;
+  let firstMeasured = false;
+  if (hq) {
+    let lease: ReturnType<typeof readHqLease>['record'] | undefined;
+    try { lease = readHqLease({ config: hq }).record; }
+    catch (error) { debug.log('hq.fence', 'board-lease-unmeasured', { writer: writerGeneration, version, reason: String(error).slice(0, 200) }); }
+    // A missing lease (null) and a broken one (parseLease throws → caught above with its reason) are both «unmeasured».
+    if (lease === null) debug.log('hq.fence', 'board-lease-unmeasured', { writer: writerGeneration, version, reason: 'no-lease' });
+    if (lease) {
+      firstMeasured = true;
+      recordedGeneration = writerGeneration;
+      if (writerGeneration !== null && writerGeneration < lease.generation) {
+        debug.log('hq.fence', 'board-stale-write', { writer: writerGeneration, lease: lease.generation, version });
+        if (hq.boardFencing === 'enforce') throw new CliUserError(`낡은 세대 ${writerGeneration} < ${lease.generation} — 쓰기 거부`);
+      }
+    }
+  }
   const db = open();
   try {
     let imported = false;
@@ -352,6 +383,22 @@ export function mutate(version: string, released: string, dev: string, apply: (d
             return { version: item.version, ...(item.owner !== null ? { owner: item.owner } : {}), title: item.title };
           });
       })) {
+        if (hq?.boardFencing === 'enforce') {
+          let late: ReturnType<typeof readHqLease>['record'] = null;
+          let lateReason = 'no-lease';
+          try { late = readHqLease({ config: hq }).record; }
+          catch (error) { late = null; lateReason = String(error).slice(0, 200); }
+          if (!late) {
+            // Unmeasured right before the write: the write still goes through, but carries no generation it cannot vouch for.
+            // (Logged only when the first read had measured — an unmeasured first read was already logged once.)
+            if (firstMeasured) debug.log('hq.fence', 'board-lease-unmeasured', { writer: writerGeneration, version, reason: lateReason, phase: 'before-write' });
+            recordedGeneration = null;
+          }
+          if (late && writerGeneration !== null && writerGeneration < late.generation) {
+            debug.log('hq.fence', 'board-stale-write', { writer: writerGeneration, lease: late.generation, version });
+            throw new CliUserError(`낡은 세대 ${writerGeneration} < ${late.generation} — 쓰기 거부`);
+          }
+        }
         for (const item of data.items) if (before.get(item.id) !== JSON.stringify(item)) {
           const previous = before.get(item.id);
           const evidenceChanged = previous && (JSON.parse(previous) as ChecklistItem).evidence !== item.evidence;
@@ -365,7 +412,10 @@ export function mutate(version: string, released: string, dev: string, apply: (d
           db.query('DELETE FROM evidence WHERE feature_id = ? AND version = ?').run(id, version);
           db.query('DELETE FROM assignments WHERE feature_id = ? AND version = ?').run(id, version);
         }
-        for (const entry of data.history.slice(count)) record(db, version, entry);
+        for (const entry of data.history.slice(count)) {
+          if (recordedGeneration !== null) entry.generation = recordedGeneration;
+          record(db, version, entry);
+        }
       }
       return data;
     });

package/src/release-loop/gate-shards.ts

@@ -0,0 +1,158 @@
+// GATE-LIVE-OBS — 게이트 «조각 상태» 한 장(`<ledger>/release/<v>/gate-logs/cut/shards.json`)의 계약.
+// 쓰는 쪽 = gate-node(TC · GATE-TIMEOUT-HEAL) · 읽는 쪽 = /v1/ops/release/runs ⊕ 외출 알림(UX).
+// 로그가 아니라 발행 원장 파일인 이유: 게이트 사건은 실행 트리의 test 우주로 가지만 원장은 운영 한 곳이다(TC·OP 10-07 19:12).
+// ⛔ 못 읽으면 `null` — 「조각 0」으로 읽지 않는다.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { releaseLedgerRoot } from '../instance/resolve.js';
+
+export const SHARD_STATES = ['pending', 'running', 'done', 'retry', 'timeout', 'failed'] as const;
+export type ShardState = typeof SHARD_STATES[number];
+
+export interface GateShard {
+  id: string;
+  state: ShardState;
+  startedAt?: string;
+  endedAt?: string;
+  /** 설치(install) 단계에 쓴 초. */
+  installSec?: number;
+  rc?: number;
+  /** 대기 이유(예: «CPU 부족 31.2/32»). pending 일 때 화면이 그대로 보인다. */
+  waitReason?: string;
+  /** 계획 분 — 남은 시간 추정의 재료. */
+  plannedMin?: number;
+}
+
+export interface GateShardsFile {
+  v: 1;
+  version: string;
+  updatedAt: string;
+  shards: GateShard[];
+}
+
+export function gateShardsPath(version: string, root: string = releaseLedgerRoot()): string {
+  return join(root, 'release', version, 'gate-logs', 'cut', 'shards.json');
+}
+
+const str = (value: unknown, max = 160): string | undefined =>
+  typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined;
+const num = (value: unknown): number | undefined => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+
+function shardOf(value: unknown): GateShard | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  const id = str(raw.id, 80);
+  const state = SHARD_STATES.find((s) => s === raw.state);
+  if (!id || !state) return null;
+  const startedAt = str(raw.startedAt, 40);
+  const endedAt = str(raw.endedAt, 40);
+  const installSec = num(raw.installSec);
+  const rc = num(raw.rc);
+  const waitReason = str(raw.waitReason);
+  const plannedMin = num(raw.plannedMin);
+  return {
+    id, state,
+    ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}),
+    ...(installSec !== undefined ? { installSec } : {}), ...(rc !== undefined ? { rc } : {}),
+    ...(waitReason ? { waitReason } : {}), ...(plannedMin !== undefined ? { plannedMin } : {}),
+  };
+}
+
+/** 파일이 없거나 깨졌으면 null. 알 수 없는 상태값의 조각은 버리되 파일 전체는 살린다. */
+export function readGateShards(path: string): GateShardsFile | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const raw = parsed as Record<string, unknown>;
+  if (raw.v !== 1 || !Array.isArray(raw.shards)) return null;
+  const version = str(raw.version, 40);
+  const updatedAt = str(raw.updatedAt, 40);
+  if (!version || !updatedAt) return null;
+  return { v: 1, version, updatedAt, shards: raw.shards.map(shardOf).filter((s): s is GateShard => s !== null) };
+}
+
+/** tmp → rename — 읽는 쪽이 반쯤 쓴 파일을 보지 않게. */
+export function writeGateShards(path: string, file: GateShardsFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(file)}\n`);
+  renameSync(tmp, path);
+}
+
+export interface GateShardsSummary {
+  total: number;
+  counts: Record<ShardState, number>;
+  /** 대기 이유별 조각 수(많은 순). */
+  waitReasons: Array<{ reason: string; count: number }>;
+  /** 남은 분 추정 — 계획 분이 모자라면 null(«추정 불가»). */
+  etaMin: number | null;
+  /** 도는 조각 중 계획 분을 가장 많이 넘긴 분(없으면 0). 넘겼으면 etaMin 은 «하한»일 뿐이라 화면이 그렇게 말한다
+   *  — canary 10-07 실측: 계획 0.1분 · 실제 22분 → 넘김을 안 보이면 내내 «남은 약 0분». */
+  overrunMin: number;
+  /** 파일이 마지막으로 바뀐 뒤 지난 분. 크면 쓰는 쪽이 멎었다는 뜻이다. */
+  staleMin: number | null;
+}
+
+const minutesBetween = (fromIso: string | undefined, now: number): number | null => {
+  const at = fromIso ? Date.parse(fromIso) : Number.NaN;
+  return Number.isFinite(at) ? Math.max(0, (now - at) / 60_000) : null;
+};
+
+/**
+ * 남은 시간 추정: 도는 조각은 «계획 − 경과», 기다리는 조각(pending·retry)은 계획 분을 지금 도는 자리 수로 나눠 뒤에 잇는다.
+ * 도는 조각이 없으면 자리 1로 본다. 계획 분이 없는 조각이 하나라도 남아 있으면 null.
+ */
+function estimate(shards: GateShard[], now: number): number | null {
+  const running = shards.filter((s) => s.state === 'running');
+  const waiting = shards.filter((s) => s.state === 'pending' || s.state === 'retry');
+  if (!running.length && !waiting.length) return 0;
+  if ([...running, ...waiting].some((s) => s.plannedMin === undefined)) return null;
+  const runningLeft = running.map((s) => Math.max(0, s.plannedMin! - (minutesBetween(s.startedAt, now) ?? 0)));
+  const slots = Math.max(1, running.length);
+  const waitingSum = waiting.reduce((sum, s) => sum + s.plannedMin!, 0);
+  return Math.ceil(Math.max(0, ...runningLeft) + waitingSum / slots);
+}
+
+export function summarizeShards(file: GateShardsFile, now: number = Date.now()): GateShardsSummary {
+  const counts = Object.fromEntries(SHARD_STATES.map((s) => [s, 0])) as Record<ShardState, number>;
+  const reasons = new Map<string, number>();
+  for (const shard of file.shards) {
+    counts[shard.state] += 1;
+    if (shard.waitReason && (shard.state === 'pending' || shard.state === 'retry')) {
+      reasons.set(shard.waitReason, (reasons.get(shard.waitReason) ?? 0) + 1);
+    }
+  }
+  const stale = minutesBetween(file.updatedAt, now);
+  const overrun = Math.max(0, ...file.shards
+    .filter((s) => s.state === 'running' && s.plannedMin !== undefined)
+    .map((s) => (minutesBetween(s.startedAt, now) ?? 0) - s.plannedMin!));
+  return {
+    total: file.shards.length,
+    counts,
+    waitReasons: [...reasons].map(([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count),
+    etaMin: estimate(file.shards, now),
+    overrunMin: Math.floor(overrun),
+    staleMin: stale === null ? null : Math.floor(stale),
+  };
+}
+
+export const SHARD_WORD: Record<ShardState, string> = {
+  pending: '대기', running: '돌기', done: '통과', retry: '재시도', timeout: '잘림', failed: '실패',
+};
+
+/** 외출 알림·/release 한 줄 — «조각 24 · 돌기 5 · 대기 8(CPU 부족 8) · 잘림 2 · 통과 9 · 남은 약 40분». */
+export function shardsLine(summary: GateShardsSummary): string {
+  const order: ShardState[] = ['running', 'pending', 'retry', 'timeout', 'failed', 'done'];
+  const parts = [`조각 ${summary.total}`];
+  for (const state of order) {
+    const n = summary.counts[state];
+    if (!n) continue;
+    const why = state === 'pending' && summary.waitReasons.length
+      ? `(${summary.waitReasons.slice(0, 2).map((w) => `${w.reason} ${w.count}`).join(' · ')})` : '';
+    parts.push(`${SHARD_WORD[state]} ${n}${why}`);
+  }
+  if (summary.overrunMin >= 1) parts.push(`계획보다 ${summary.overrunMin}분 넘게 도는 중 — 남은 시간 추정 불가`);
+  else parts.push(summary.etaMin === null ? '남은 시간 추정 불가(계획 분 없음)' : `남은 약 ${summary.etaMin}분`);
+  if (summary.staleMin !== null && summary.staleMin >= 15) parts.push(`⚠️ ${summary.staleMin}분째 갱신 없음`);
+  return parts.join(' · ');
+}

package/src/release-loop/light-rc.ts

@@ -0,0 +1,173 @@
+/** LIGHT-RC (0.2.19) — a light release-candidate check between cuts: the changed-file self gate over everything that
+ *  landed since the previous release's cut, plus an always-run test list (release/light-rc-always.txt), on the remote
+ *  gate host (GATE-REMOTE). Read-only for the release ledger: it reads the previous published version and never writes.
+ *  It does not touch the landing freeze or launch Pods. */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { runSelfGateCli, type SelfGateCliOptions, type SelfGateCliResult } from '../self-implement/gate-cli.js';
+import { dispatchHeavyCheck, isValidGateHost, type DispatchDeps, type DispatchOptions } from '../self-implement/gate-remote.js';
+import { latestPublishedPreviousVersion } from '../../scripts/release-loop/unattended-release.js';
+import { baseVersion, isReleaseVersion } from '../../scripts/release-loop/release-version.js';
+
+export const LIGHT_RC_ALWAYS_FILE = 'release/light-rc-always.txt';
+export const LIGHT_RC_DEFAULT_SHARDS = 4;
+export const LIGHT_RC_NO_PREVIOUS_CUT = '직전 판 컷을 못 찾았다 — --base 로 준다';
+
+export interface LightRcOptions {
+  base?: string;
+  /** Gate host; absent = config gateRemote.host (the dispatch's own default). */
+  remote?: string;
+  /** Run on this machine (the remote child is re-invoked with it). */
+  local?: boolean;
+  shards?: number;
+  /** Release ledger root for the previous-version lookup (release run's deps.ledgerRoot). */
+  ledgerRoot?: string;
+  log?: (line: string) => void;
+}
+
+export interface LightRcResult {
+  version: string;
+  base: string;
+  /** New failures vs. the base; null = the gate produced no measurement (never read as green). */
+  introduced: number | null;
+  preexisting: number | null;
+  /** Failures the baseline could not classify (unknown + precondition-unmet); null = unmeasured. Non-zero is not green. */
+  unclassified: number | null;
+  alwaysInclude: number;
+  alwaysIncludeMissing: string[];
+  shards: number;
+  /** Host the gate ran on; null = this machine. */
+  remote: string | null;
+  gateExitCode: number;
+  ok: boolean;
+}
+
+export interface LightRcDeps {
+  cwd?: string;
+  git?: (args: string[], cwd: string) => { rc: number | null; stdout: string };
+  previousVersion?: (version: string, ledgerRoot?: string) => string;
+  readFile?: (path: string) => string | undefined;
+  runGate?: (cwd: string, options: SelfGateCliOptions) => SelfGateCliResult;
+  dispatch?: (opts: DispatchOptions, deps?: DispatchDeps) => Promise<number>;
+  /** Extra dispatch deps (runner · settings) — tests drive the real dispatch with a fake host. */
+  dispatchDeps?: Omit<DispatchDeps, 'write'>;
+}
+
+/** Shown when the gate ran remotely but the host name did not come back. */
+export const LIGHT_RC_UNKNOWN_HOST = '(remote · host unknown)';
+
+const defaultGit = (args: string[], cwd: string) => {
+  const run = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return { rc: run.error ? null : run.status, stdout: run.stdout ?? '' };
+};
+
+/** One repository-relative path per line; `#` starts a comment; blank lines are skipped. */
+export function parseAlwaysIncludeList(text: string): string[] {
+  return [...new Set(text.split('\n').map((line) => line.replace(/#.*/, '').trim()).filter(Boolean))];
+}
+
+/** The previous release's cut: merge-base of origin/main and origin/release/<previous published version>. */
+export function previousCutBase(version: string, deps: LightRcDeps & { cwd: string; ledgerRoot?: string }): string {
+  let previous: string;
+  try {
+    previous = (deps.previousVersion ?? latestPublishedPreviousVersion)(baseVersion(version), deps.ledgerRoot);
+  } catch (error) {
+    throw new Error(`${LIGHT_RC_NO_PREVIOUS_CUT} (${error instanceof Error ? error.message : String(error)})`);
+  }
+  const mergeBase = (deps.git ?? defaultGit)(['merge-base', 'origin/main', `origin/release/${previous}`], deps.cwd);
+  const sha = mergeBase.stdout.trim();
+  if (mergeBase.rc !== 0 || !sha) throw new Error(`${LIGHT_RC_NO_PREVIOUS_CUT} (git merge-base origin/main origin/release/${previous} rc=${mergeBase.rc})`);
+  return sha;
+}
+
+function repoRoot(deps: LightRcDeps): string {
+  if (deps.cwd) return deps.cwd;
+  const top = defaultGit(['rev-parse', '--show-toplevel'], process.cwd());
+  if (top.rc !== 0 || !top.stdout.trim()) throw new Error('release light-rc: not inside a git repository');
+  return top.stdout.trim();
+}
+
+function parseRemoteResult(stdout: string): Partial<LightRcResult> | undefined {
+  const line = stdout.split('\n').map((l) => l.trim()).reverse().find((l) => l.startsWith('{'));
+  if (!line) return undefined;
+  try {
+    const parsed = JSON.parse(line) as Partial<LightRcResult> & { host?: unknown };
+    return parsed && typeof parsed === 'object' ? parsed : undefined;
+  } catch { return undefined; }
+}
+
+export async function runLightRc(version: string, opts: LightRcOptions = {}, deps: LightRcDeps = {}): Promise<LightRcResult> {
+  if (!isReleaseVersion(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const shards = opts.shards ?? LIGHT_RC_DEFAULT_SHARDS;
+  if (!Number.isSafeInteger(shards) || shards < 1) throw new Error(`invalid --shards count: ${opts.shards}`);
+  if (opts.remote !== undefined && !isValidGateHost(opts.remote)) throw new Error(`invalid --remote host: ${opts.remote}`);
+  const log = opts.log ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const cwd = repoRoot(deps);
+  const base = opts.base ?? previousCutBase(version, { ...deps, cwd, ledgerRoot: opts.ledgerRoot });
+  const listPath = join(cwd, LIGHT_RC_ALWAYS_FILE);
+  const listText = (deps.readFile ?? ((path: string) => existsSync(path) ? readFileSync(path, 'utf8') : undefined))(listPath);
+  if (listText === undefined) throw new Error(`release light-rc: ${LIGHT_RC_ALWAYS_FILE} not found`);
+  const alwaysInclude = parseAlwaysIncludeList(listText);
+
+  let local: SelfGateCliResult | undefined;
+  const runLocal = () => {
+    local = (deps.runGate ?? runSelfGateCli)(cwd, { base, shards, alwaysInclude });
+    for (const line of local.lines) log(line);
+    return local.exitCode;
+  };
+  const captured: Buffer[] = [];
+  const rc = await (deps.dispatch ?? dispatchHeavyCheck)({
+    tool: 'self-gate', repo: cwd, installPwa: true, refs: [base], json: true,
+    // The host re-runs this command with --local (and ELANOUS_GATE_REMOTE_CHILD=1), so it never recurses.
+    remoteArgv: (sha) => ['bun', 'bin/elanous.mjs', 'release', 'light-rc', '--version', version, '--base', sha(base), '--shards', String(shards), '--local', '--json'],
+    flags: { remote: opts.local ? undefined : opts.remote ?? true, local: !!opts.local },
+    runLocal,
+  }, {
+    ...deps.dispatchDeps,
+    write: {
+      out: (data) => { captured.push(Buffer.from(data)); },
+      err: (data) => { process.stderr.write(data); },
+    },
+  });
+
+  let result: LightRcResult;
+  if (local) {
+    result = {
+      version, base,
+      introduced: local.baseline?.introduced ?? null,
+      preexisting: local.baseline?.preexisting ?? null,
+      unclassified: local.baseline ? local.baseline.unknown + local.baseline.preconditionUnmet : null,
+      alwaysInclude: alwaysInclude.length,
+      alwaysIncludeMissing: [...local.alwaysIncludeMissing],
+      shards, remote: null, gateExitCode: local.exitCode, ok: false,
+    };
+  } else {
+    const remote = parseRemoteResult(Buffer.concat(captured).toString('utf8'));
+    if (!remote) throw new Error(`release light-rc: remote gate returned no result (rc=${rc})`);
+    const host = (remote as { host?: unknown }).host;
+    result = {
+      version, base,
+      introduced: typeof remote.introduced === 'number' ? remote.introduced : null,
+      preexisting: typeof remote.preexisting === 'number' ? remote.preexisting : null,
+      unclassified: typeof remote.unclassified === 'number' ? remote.unclassified : null,
+      alwaysInclude: alwaysInclude.length,
+      alwaysIncludeMissing: Array.isArray(remote.alwaysIncludeMissing) ? remote.alwaysIncludeMissing.map(String) : [],
+      shards, remote: typeof host === 'string' && host ? host : opts.remote ?? LIGHT_RC_UNKNOWN_HOST,
+      gateExitCode: typeof remote.gateExitCode === 'number' ? remote.gateExitCode : rc, ok: false,
+    };
+  }
+  // Unmeasured (null) or unclassified failures are never green; policy-gate findings in the gate output are reported
+  // (gate rc), not a regression.
+  result.ok = result.introduced === 0 && result.unclassified === 0;
+  debug.log('release.light-rc', 'done', { version, base, introduced: result.introduced, preexisting: result.preexisting, unclassified: result.unclassified, shards, remote: result.remote });
+  return result;
+}
+
+export function formatLightRc(result: LightRcResult): string[] {
+  return [
+    `${result.ok ? '✅' : '⛔'} light-rc ${result.version} · base ${result.base.slice(0, 12)} · ${result.remote ? `host ${result.remote}` : 'local'} · shards ${result.shards}`,
+    `  introduced ${result.introduced ?? '못 쟀다'} · preexisting ${result.preexisting ?? '못 쟀다'} · unclassified ${result.unclassified ?? '못 쟀다'} · always-include ${result.alwaysInclude}${result.alwaysIncludeMissing.length ? ` (missing: ${result.alwaysIncludeMissing.join(', ')})` : ''} · gate rc ${result.gateExitCode}`,
+  ];
+}