elanous 0.2.0 → 0.2.5

package/src/pty-shell/registry.ts

@@ -17,6 +17,7 @@ import { existsSync } from 'node:fs';
 import { requirePosixShell } from '../platform/default-shell.js';
 import { randomBytes } from 'node:crypto';
 import { Terminal as XtermHeadless } from '@xterm/headless';
+import { trackPtyMouseOutput, forgetPtyMouseMode } from './pty-mouse.js';
 import { getGlobalElementRegistry, publishElementEvent } from '../element-registry/index.js';
 import { getSessionCwd } from '../session/working-dir.js';
 import { buildPtyEnv } from '../agent/identity-env.js';
@@ -26,6 +27,7 @@ import { resolvePtyRef, canTransitionAccessMode, ptyIdSeparatorIndex, type PtyAc
 import { resolveWriteDecision, resolveTakeover, type PtyWriteActor } from './pty-write-arbiter.js';
 import { addPtyManifestOutputBytes, upsertPtyManifest, updatePtyManifestSnapshot, updatePtyManifestNickname, markPtyManifestClosed, removePtyManifest, touchLivePtyManifest } from './pty-manifest.js';
 import { processPtyControlRequests } from './pty-control-ipc.js';
+import { tapPtyOutput, autoStopPtyRecording } from './pty-recording.js';
 import { forgetExternalWriteProvenance, noteExternalWrite } from './pty-write-provenance.js';
 import { resolveRunIdentity } from '../harness/harness-space.js';
 import { addSelfDevRunParticipant, selfDevRunsDir } from '../self-dev/run-store.js';
@@ -168,6 +170,8 @@ function renderAnsiLine(line: { length: number; getCell(x: number): XtermCell |
 
 export interface PtyControlTarget {
   readonly id: string;
+  readonly cols?: number;
+  readonly rows?: number;
   accessMode: PtyAccessMode;
   transitionPolicy: PtyTransitionPolicy;
   setAccessMode(mode: PtyAccessMode): boolean;
@@ -211,6 +215,8 @@ export interface PtyHandle extends PtyControlTarget {
   readonly pid: number;
   readonly workdir: string | undefined;
   readonly startedAt: number;
+  readonly cols: number;
+  readonly rows: number;
   /** Last time the PTY produced output OR was driven (write/drain). Used
    *  for LRU eviction when the concurrency cap is hit — recently-driven
    *  PTYs (a session the user may still resume) are protected; only the
@@ -329,6 +335,7 @@ export function emitPtyEvent(ev: PtyEvent): void {
       publishElementEvent('pty', ev.id, 'output', { bytes: ev.chunk.length });
       break;
     case 'exit':
+      forgetPtyMouseMode(ev.id);
       publishElementEvent('pty', ev.id, 'exit', { exitCode: ev.exitCode, signal: ev.signal });
       break;
     case 'stalled':
@@ -337,6 +344,7 @@ export function emitPtyEvent(ev: PtyEvent): void {
     case 'write-denied':
       break;
     case 'unregistered':
+      forgetPtyMouseMode(ev.id);
       publishElementEvent('pty', ev.id, 'delete');
       break;
   }
@@ -469,6 +477,8 @@ export function startPty(opts: StartOpts): PtyHandle {
    *  the alternative was a dead PTY reporting itself alive forever. Splitting
    *  the two lets `exitCode: null` honestly mean "죽었지만 모름". */
   let exited = false;
+  let currentCols = opts.cols ?? 80;
+  let currentRows = opts.rows ?? 24;
   let lastActivityAt = Date.now();
 
   // Screen emulator (@xterm/headless) — parses the same byte stream the
@@ -514,6 +524,8 @@ export function startPty(opts: StartOpts): PtyHandle {
     pid: adapter.pid,
     workdir: opts.workdir,
     startedAt: Date.now(),
+    get cols() { return currentCols; },
+    get rows() { return currentRows; },
     get lastActivityAt() { return lastActivityAt; },
     detach: opts.detach ?? false,
     get exitCode() { return exitCode; },
@@ -526,6 +538,7 @@ export function startPty(opts: StartOpts): PtyHandle {
     appendOutput(chunk: string): void {
       lastActivityAt = Date.now();
       delta += chunk;
+      trackPtyMouseOutput(id, chunk);
       // Feed the screen emulator so renderScreen() reflects live state.
       if (term) { try { term.write(chunk); } catch { /* parser hiccup — buffer still ok */ } }
       // Head: fill until cap.
@@ -634,7 +647,10 @@ export function startPty(opts: StartOpts): PtyHandle {
     resize(cols: number, rows: number): void {
       const c = Math.max(2, Math.floor(cols));
       const r = Math.max(2, Math.floor(rows));
-      try { adapter.resize?.(c, r); } catch { /* ignore */ }
+      // The reported size (recording headers) follows the PTY only once the adapter took it.
+      try {
+        if (adapter.resize) { adapter.resize(c, r); currentCols = c; currentRows = r; }
+      } catch { /* ignore */ }
       if (term) { try { term.resize(c, r); } catch { /* ignore */ } }
     },
   };
@@ -692,6 +708,8 @@ export function startPty(opts: StartOpts): PtyHandle {
 
   adapter.onData(chunk => {
     handle.appendOutput(chunk);
+    try { tapPtyOutput(id, chunk); }
+    catch (error) { debug.log('pty.record', 'tap-error', { ptyId: id, error: String(error) }); }
     emitPtyEvent({ type: 'output', id, chunk });
     // ★ 크로스-프로세스 관측(2026-07-23) — throttled 스냅샷을 공유 매니페스트에(데몬 PWA 유니온). getter 라 throttle 통과 시에만 snapshot().
     if (PTY_MANIFEST_ENABLED) {
@@ -714,6 +732,8 @@ export function startPty(opts: StartOpts): PtyHandle {
     killEscalationTimer = null;
     exitCode = code;
     exitSignal = signal;
+    try { autoStopPtyRecording(id); }
+    catch (error) { debug.log('pty.record', 'auto-stop-error', { ptyId: id, error: String(error) }); }
     emitPtyEvent({ type: 'exit', id, exitCode: code, signal });
     if (PTY_MANIFEST_ENABLED) {
       const now = Date.now();
@@ -802,7 +822,31 @@ function ensurePtyManifestHeartbeat(): void {
  * deliberately separate from spawned PTYs: it has no child lifecycle. */
 export function registerPtyControlTarget(handle: PtyControlTarget): () => void {
   controlTargets.set(handle.id, handle);
-  return () => { if (controlTargets.get(handle.id) === handle) controlTargets.delete(handle.id); };
+  // The self-reporting foreground TUI owns its stdout. The mirror installed later
+  // delegates through this tap, preserving its existing output and overlay path.
+  const stream = process.stdout;
+  const previousWrite = stream.write;
+  let tappedWrite: typeof stream.write | undefined;
+  if (handle.id.startsWith('tui:')) {
+    // Streaming decode: a multibyte character split across two Buffer writes stays intact.
+    const decoder = new TextDecoder('utf-8');
+    tappedWrite = function (this: typeof stream, ...args: Parameters<typeof stream.write>) {
+      const chunk = args[0];
+      if (chunk !== undefined) {
+        try { tapPtyOutput(handle.id, typeof chunk === 'string' ? chunk : decoder.decode(chunk as Uint8Array, { stream: true })); }
+        catch (error) { debug.log('pty.record', 'tap-error', { ptyId: handle.id, error: String(error) }); }
+      }
+      return previousWrite.apply(this, args);
+    } as typeof stream.write;
+    stream.write = tappedWrite;
+  }
+  return () => {
+    if (controlTargets.get(handle.id) !== handle) return;
+    try { autoStopPtyRecording(handle.id); }
+    catch (error) { debug.log('pty.record', 'auto-stop-error', { ptyId: handle.id, error: String(error) }); }
+    controlTargets.delete(handle.id);
+    if (tappedWrite && stream.write === tappedWrite) stream.write = previousWrite;
+  };
 }
 
 /** Run the existing cross-process control protocol for live targets. This
@@ -896,6 +940,8 @@ export function requestPtyTakeover(id: string, actor: PtyWriteActor): boolean {
 export function unregisterPty(id: string): boolean {
   const existed = processes.delete(id);
   if (existed) {
+    try { autoStopPtyRecording(id); }
+    catch (error) { debug.log('pty.record', 'auto-stop-error', { ptyId: id, error: String(error) }); }
     const outputFlush = pendingManifestOutputFlushers.get(id);
     outputFlush?.flush(Date.now());
     outputFlush?.cancel();
@@ -939,7 +985,8 @@ export function killNonDetached(): number {
     if (handle.isAlive()) {
       try { handle.kill('SIGTERM'); killed++; } catch { /* ignore */ }
     }
-    // The adapter's later onExit owns closure. Keep a failed trailing-output flush retryable until then.
+    // The adapter's later onExit owns recording closure (including trailing bytes).
+    // Keep a failed trailing-output flush retryable until then.
     pendingManifestOutputFlushers.get(id)?.flush(Date.now());
     processes.delete(id);
     getGlobalElementRegistry().unregister('pty', id);
@@ -1111,6 +1158,9 @@ export function resetForTesting(): void {
   const registry = getGlobalElementRegistry();
   for (const handle of processes.values()) {
     if (handle.isAlive()) try { handle.kill('SIGKILL'); } catch { /* ignore */ }
+    try { autoStopPtyRecording(handle.id); }
+    catch (error) { debug.log('pty.record', 'auto-stop-error', { ptyId: handle.id, error: String(error) }); }
+    forgetPtyMouseMode(handle.id);
     const outputFlush = pendingManifestOutputFlushers.get(handle.id);
     outputFlush?.flush(Date.now());
     outputFlush?.cancel();

package/src/python/resolve-python.ts

@@ -202,7 +202,7 @@ export function evaluatePythonEnv(input: {
   if (!versionAtLeast(probe.version, floor)) {
     const remedy = windows
       ? windowsPythonRemedy(resolution.source)
-      : `pyenv install ${pin} (build deps per distro: RFC-doctor-fix-build-toolchain-and-python-by-distro A2) · then: elanous python setup --yes`;
+      : `pyenv install ${pin} (install your distribution's Python build dependencies first) · then: elanous python setup --yes`;
     return { status: 'manual', evidence: `${resolution.source} python ${v} is older than the minimum ${floor}`, remedy, resolution };
   }
   if (!venvExists) return { status: 'fixable', evidence: `python ${v} (${resolution.source}) · elanous venv missing`, remedy: 'elanous python setup --yes', resolution };

package/src/release-loop/checklist.ts

@@ -0,0 +1,191 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+import { releaseLedgerRoot } from '../instance/resolve.js';
+
+export type ChecklistStatus = 'green' | 'yellow' | 'red' | 'done';
+export interface ChecklistItem {
+  id: string;
+  title: string;
+  status: ChecklistStatus;
+  owner?: string;
+  evidence?: string;
+  updatedAt: string;
+  updatedBy: string;
+}
+export interface ChecklistHistory {
+  at: string;
+  by: string;
+  id: string;
+  field: string;
+  from: unknown;
+  to: unknown;
+  released: string;
+  dev: string;
+}
+export interface Checklist {
+  version: string;
+  released: string;
+  dev: string;
+  items: ChecklistItem[];
+  history: ChecklistHistory[];
+}
+
+export function devVersion(): string {
+  return (JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version: string }).version;
+}
+
+function releasedVersion(): string {
+  const dir = join(releaseLedgerRoot(), 'release');
+  if (!existsSync(dir)) return '';
+  return readdirSync(dir).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && existsSync(join(dir, v, 'release.json')))
+    .filter((v) => {
+      try { const record = JSON.parse(readFileSync(join(dir, v, 'release.json'), 'utf8')) as { version?: string; publishedAt?: string }; return record.version === v && typeof record.publishedAt === 'string'; }
+      catch { return false; }
+    })
+    .sort((a, b) => {
+      const aa = a.split('.').map(Number), bb = b.split('.').map(Number);
+      return (bb[0]! - aa[0]!) || (bb[1]! - aa[1]!) || (bb[2]! - aa[2]!);
+    })[0] ?? '';
+}
+
+function pathFor(v: string): string {
+  if (!/^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/.test(v)) throw new Error(`체크리스트 판이 아니다: ${v}`);
+  return join(releaseLedgerRoot(), 'release', v, 'checklist.json');
+}
+
+export function listChecklist(v: string): Checklist {
+  const path = pathFor(v);
+  if (existsSync(path)) {
+    const data = JSON.parse(readFileSync(path, 'utf8')) as Checklist;
+    refresh(data);
+    return data;
+  }
+  return { version: v, released: releasedVersion(), dev: devVersion(), items: [], history: [] };
+}
+
+// SQLite's OS-backed write lock is released when the owning process exits, even without a finally block.
+// Hold it across the JSON read/modify/atomic-rename sequence so writers never use stale snapshots.
+function mutate(v: string, apply: (data: Checklist) => boolean): Checklist {
+  const path = pathFor(v);
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.mutex.sqlite`;
+  const db = new Database(lock, { create: true, strict: true });
+  try {
+    chmodSync(lock, 0o600);
+    db.exec('PRAGMA busy_timeout = 10000');
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      const data = listChecklist(v);
+      if (apply(data)) save(v, data);
+      db.exec('COMMIT');
+      return data;
+    } catch (error) {
+      db.exec('ROLLBACK');
+      throw error;
+    }
+  } finally { db.close(); }
+}
+
+function save(v: string, data: Checklist): void {
+  const path = pathFor(v);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(temp, 0o600);
+    renameSync(temp, path);
+  } finally { if (existsSync(temp)) rmSync(temp); }
+}
+
+function change(data: Checklist, id: string, field: string, from: unknown, to: unknown, by: string, at: string): void {
+  data.history.push({ at, by, id, field, from: from ?? null, to: to ?? null, released: data.released, dev: data.dev });
+  debug.log('release-loop.checklist', 'change', { version: data.version, id, field, from: from ?? null, to: to ?? null, by });
+}
+
+function refresh(data: Checklist): void { data.released = releasedVersion(); data.dev = devVersion(); }
+
+export function addItem(v: string, input: { id: string; title: string; owner?: string }): Checklist {
+  if (!input.id.trim()) throw new Error('칸 id 가 비었다');
+  if (!input.title.trim()) throw new Error('칸 제목이 비었다');
+  return mutate(v, (data) => {
+    if (data.items.some((item) => item.id === input.id)) throw new Error(`이미 있는 칸: ${input.id}`);
+    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 } : {}), 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 }, by: string): Checklist {
+  return mutate(v, (data) => {
+    const item = data.items.find((i) => i.id === id);
+    if (!item) throw new Error(`없는 칸: ${id}`);
+    if (patch.status !== undefined && !['green', 'yellow', 'red', 'done'].includes(patch.status)) throw new Error(`잘못된 상태: ${patch.status}`);
+    const fields = (['evidence', 'owner', 'status'] as const).filter((field) => patch[field] !== undefined && patch[field] !== item[field]);
+    if (fields.length === 0) return false;
+    const at = new Date().toISOString();
+    for (const field of fields) {
+      const from = item[field];
+      const to = patch[field]!;
+      (item as unknown as Record<string, unknown>)[field] = to;
+      item.updatedAt = at;
+      item.updatedBy = by;
+      change(data, id, field, from, to, by, at);
+    }
+    return true;
+  });
+}
+
+export function removeItem(v: string, id: string, by: string): Checklist {
+  return mutate(v, (data) => {
+    const index = data.items.findIndex((i) => i.id === id);
+    if (index < 0) throw new Error(`없는 칸: ${id}`);
+    const at = new Date().toISOString();
+    const [item] = data.items.splice(index, 1);
+    change(data, id, 'remove', item, null, by, at);
+    return true;
+  });
+}
+
+export function summarize(v: string): ChecklistSummary {
+  return summarizeChecklist(listChecklist(v));
+}
+
+export interface ChecklistSummary { green: number; yellow: number; red: number; done: number; blocked: string[]; byOwner: Record<string, number> }
+
+export function summarizeChecklist(data: Checklist): ChecklistSummary {
+  const summary = { green: 0, yellow: 0, red: 0, done: 0, blocked: [] as string[], byOwner: Object.create(null) as Record<string, number> };
+  for (const item of data.items) {
+    summary[item.status]++;
+    if (item.status === 'red') summary.blocked.push(item.id);
+    const owner = item.owner ?? 'unassigned';
+    summary.byOwner[owner] = (summary.byOwner[owner] ?? 0) + 1;
+  }
+  return summary;
+}
+
+export function seedFromRoadmap(v: string, markdown: string): Checklist {
+  return mutate(v, (data) => {
+    let added = false;
+    for (const line of markdown.split('\n')) {
+      const match = /^\|\s*(K\d+[a-z]?[′']?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|/.exec(line);
+      if (!match || data.items.some((i) => i.id === match[1])) continue;
+      const id = match[1]!;
+      const title = match[2]!;
+      const icon = match[3]!.trim();
+      const status: ChecklistStatus = icon.startsWith('🟢') ? 'green' : icon.startsWith('🔴') ? 'red' : icon.startsWith('✅') ? 'done' : 'yellow';
+      const at = new Date().toISOString();
+      const by = process.env.ELANOUS_TRACK || 'cli';
+      const item: ChecklistItem = { id, title, status, updatedAt: at, updatedBy: by };
+      data.items.push(item);
+      change(data, id, 'add', null, item, by, at);
+      added = true;
+    }
+    return added;
+  });
+}

package/src/release-loop/manifest.ts

@@ -0,0 +1,65 @@
+import type { ReleaseNoteFragment } from './release-note.js';
+
+export interface ReleaseLanding {
+  sha: string;
+  title: string;
+  prNumber?: number;
+  changedFiles: string[];
+  goalPath?: string;
+  releaseTarget?: 'next' | 'later';
+}
+
+export interface ReleaseManifestInput {
+  version: string;
+  baseline: { ref: string; sha: string };
+  cutoff: { sha: string };
+  landings: ReleaseLanding[];
+  notes?: Map<number, ReleaseNoteFragment>;
+  runningGoalPaths: string[];
+  publicCommandsBefore: string[];
+  publicCommandsAfter: string[];
+}
+
+export interface ReleaseManifest {
+  version: string;
+  baseline: ReleaseManifestInput['baseline'];
+  cutoff: ReleaseManifestInput['cutoff'];
+  in: Array<{ sha: string; title: string; prNumber?: number; docs: 'present' | 'missing' | 'n/a'; line?: string; kind?: ReleaseNoteFragment['kind'] | 'unknown'; note?: 'missing' }>;
+  deferred: Array<{ sha: string; reason: 'release-target-later' | 'run-in-flight' }>;
+  escalate: Array<{ kind: 'command-removed'; command: string }>;
+}
+
+/** Classify the already-observed landings without reading git, run ledgers or the filesystem. */
+export function buildReleaseManifest(input: ReleaseManifestInput): ReleaseManifest {
+  const running = new Set(input.runningGoalPaths);
+  const after = new Set(input.publicCommandsAfter);
+  const result: ReleaseManifest = {
+    version: input.version,
+    baseline: { ...input.baseline },
+    cutoff: { ...input.cutoff },
+    in: [],
+    deferred: [],
+    escalate: [],
+  };
+  for (const landing of input.landings) {
+    const fragment = landing.prNumber === undefined ? undefined : input.notes?.get(landing.prNumber);
+    if (landing.goalPath && running.has(landing.goalPath)) {
+      result.deferred.push({ sha: landing.sha, reason: 'run-in-flight' });
+    // ⭐ 줄이 없으면 IN — 명시 `release-target: later` 만 미룬다(METHOD v115 ④ · 흡수 골은 머리에 later 를 «명시»한다).
+    } else if (fragment?.target === 'later' || (!fragment && landing.releaseTarget === 'later')) {
+      result.deferred.push({ sha: landing.sha, reason: 'release-target-later' });
+    } else {
+      const docs = fragment ? ('path' in fragment.docs ? 'present' : 'n/a')
+        : landing.changedFiles.some((file) => file.startsWith('release/public/docs/')) ? 'present'
+        : landing.changedFiles.some((file) => file.startsWith('src/cli/') || file === 'src/index.ts') ? 'missing'
+        : 'n/a';
+      result.in.push({ sha: landing.sha, title: landing.title, ...(landing.prNumber === undefined ? {} : { prNumber: landing.prNumber }), docs,
+        ...(fragment ? { line: fragment.line, kind: fragment.kind } : input.notes ? { line: landing.title, kind: 'unknown', note: 'missing' as const } : {}),
+      });
+    }
+  }
+  for (const command of input.publicCommandsBefore) {
+    if (!after.has(command)) result.escalate.push({ kind: 'command-removed', command });
+  }
+  return result;
+}

package/src/release-loop/release-note.ts

@@ -0,0 +1,177 @@
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+export interface ReleaseNoteFragment {
+  pr: number;
+  line: string;
+  kind: 'fix' | 'feat' | 'security' | 'internal';
+  docs: { path: string } | { none: string };
+  target: 'next' | 'later';
+  source: 'pr-body' | 'harness' | 'backfill';
+  mergeSha?: string;
+}
+
+type Section = Omit<ReleaseNoteFragment, 'pr' | 'source' | 'mergeSha'>;
+
+/** Blank out fenced code blocks (``` / ~~~) line-for-line so example headings and fields inside them are never read as the real section. */
+function blankFencedCode(text: string): string {
+  let fence: string | null = null;
+  return text.split('\n').map((line) => {
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence === null) {
+      if (open) { fence = open[1]!; return ''; }
+      return line;
+    }
+    if (open && open[1]![0] === fence[0] && open[1]!.length >= fence.length && /^ {0,3}[`~]+[ \t]*\r?$/.test(line)) fence = null;
+    return '';
+  }).join('\n');
+}
+
+export function parseReleaseNoteSection(rawPrBody: string): { fragment?: Section; problems: string[] } {
+  const prBody = blankFencedCode(rawPrBody);
+  const sections = [...prBody.matchAll(/^## 릴리스 노트[ \t]*\r?$/gm)];
+  const start = sections.at(-1);
+  if (!start) return { problems: [] };
+  const rest = prBody.slice(start.index! + start[0].length).replace(/^\r?\n/, '');
+  const nextHeading = /^ {0,3}#{1,6}(?:[ \t]+|$)/m.exec(rest);
+  const body = nextHeading ? rest.slice(0, nextHeading.index) : rest;
+  const fields = new Map<string, string>();
+  const duplicates = new Set<string>();
+  for (const match of body.matchAll(/^[ \t]*- (한 줄|종류|문서|대상):[ \t]*(.*?)[ \t]*\r?$/gm)) {
+    const name = match[1]!;
+    if (fields.has(name)) duplicates.add(name);
+    else fields.set(name, match[2]!);
+  }
+  const line = fields.get('한 줄');
+  const kind = fields.get('종류');
+  const doc = fields.get('문서');
+  const target = fields.get('대상');
+  const problems: string[] = [];
+  if (duplicates.has('한 줄') || !line?.trim()) problems.push('한 줄');
+  if (duplicates.has('종류') || !kind || !['fix', 'feat', 'security', 'internal'].includes(kind)) problems.push('종류');
+  if (duplicates.has('문서') || !doc || (doc.startsWith('없음') ? !/^없음\([^\s()]+(?:[^()]*)\)$/.test(doc) : !/^\S+$/.test(doc))) problems.push('문서');
+  if (duplicates.has('대상') || (target !== 'next' && target !== 'later')) problems.push('대상');
+  const invalid = problems.length > 0;
+  if (sections.length > 1) problems.push(`multiple release-note sections (${sections.length}); using the last`);
+  if (invalid) return { problems };
+  return {
+    fragment: {
+      line: line!, kind: kind as Section['kind'],
+      docs: doc!.startsWith('없음(') ? { none: doc!.slice(3, -1) } : { path: doc! },
+      target: target as Section['target'],
+    },
+    problems,
+  };
+}
+
+export function renderReleaseNoteSection(fragment: Section): string {
+  return `## 릴리스 노트\n- 한 줄: ${fragment.line}\n- 종류: ${fragment.kind}\n- 문서: ${'path' in fragment.docs ? fragment.docs.path : `없음(${fragment.docs.none})`}\n- 대상: ${fragment.target}\n`;
+}
+
+export function harnessReleaseNote(goalDocument: string, title: string): Section {
+  const document = blankFencedCode(goalDocument);
+  const goal = /^ {0,3}## 목표[ \t]*\r?$/m.exec(document);
+  let section = '';
+  if (goal) {
+    const rest = document.slice(goal.index + goal[0].length);
+    let end = rest.length;
+    for (const heading of rest.matchAll(/^ {0,3}(#{1,2})[ \t]+([^\r\n]*?)[ \t]*\r?$/gm)) {
+      if (heading[1] !== '##' || heading[2] !== '릴리스 노트') {
+        end = heading.index;
+        break;
+      }
+    }
+    section = rest.slice(0, end);
+  }
+  return parseReleaseNoteSection(section).fragment ?? {
+    line: title,
+    kind: 'internal',
+    docs: { none: '하니스 자동 생성' },
+    target: 'next',
+  };
+}
+
+export function releaseNotesDir(instanceRoot: string): string {
+  return join(instanceRoot, 'release', 'notes');
+}
+
+function validFragment(value: unknown): value is ReleaseNoteFragment {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return Number.isSafeInteger(v.pr) && (v.pr as number) > 0
+    && (v.mergeSha === undefined || (typeof v.mergeSha === 'string' && v.mergeSha.trim().length > 0))
+    && typeof v.line === 'string' && v.line.trim().length > 0
+    && ['fix', 'feat', 'security', 'internal'].includes(v.kind as string)
+    && (v.target === 'next' || v.target === 'later')
+    && ['pr-body', 'harness', 'backfill'].includes(v.source as string)
+    && !!v.docs && typeof v.docs === 'object'
+    && (('path' in v.docs && typeof v.docs.path === 'string' && v.docs.path.trim().length > 0 && !('none' in v.docs))
+      || ('none' in v.docs && typeof v.docs.none === 'string' && v.docs.none.trim().length > 0 && !('path' in v.docs)));
+}
+
+const priority: Record<ReleaseNoteFragment['source'], number> = { backfill: 0, harness: 1, 'pr-body': 2 };
+
+export function writeReleaseNote(dir: string, fragment: ReleaseNoteFragment): void {
+  if (!validFragment(fragment)) throw new Error('invalid release note fragment');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${fragment.pr}.json`);
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + 10_000;
+  const wait = new Int32Array(new SharedArrayBuffer(4));
+  let descriptor: number;
+  while (true) {
+    try { descriptor = openSync(lock, 'wx'); break; }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error;
+      if (Date.now() >= deadline) throw new Error(`release note lock timed out: ${lock}`);
+      Atomics.wait(wait, 0, 0, 10);
+    }
+  }
+  try {
+    let existing: unknown;
+    try { existing = JSON.parse(readFileSync(path, 'utf8')); }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    }
+    if (existing !== undefined && !validFragment(existing)) throw new Error(`invalid release note: ${path}`);
+    if (validFragment(existing) && priority[existing.source] >= priority[fragment.source]) return;
+    const temporary = join(dir, `.${fragment.pr}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, JSON.stringify(fragment, null, 2) + '\n');
+      renameSync(temporary, path);
+    } finally {
+      try { unlinkSync(temporary); }
+      catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+      }
+    }
+  } finally {
+    closeSync(descriptor);
+    unlinkSync(lock);
+  }
+}
+
+export type ReleaseNotes = Map<number, ReleaseNoteFragment> & { problems: string[] };
+
+export function readReleaseNotes(dir: string): ReleaseNotes {
+  const notes = new Map<number, ReleaseNoteFragment>() as ReleaseNotes;
+  notes.problems = [];
+  let files: string[];
+  try { files = readdirSync(dir); }
+  catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return notes;
+    throw error;
+  }
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const value: unknown = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+      if (!validFragment(value) || file !== `${value.pr}.json`) throw new Error('invalid fragment or PR filename');
+      notes.set(value.pr, value);
+    } catch (error) {
+      notes.problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return notes;
+}

package/src/roles/lease-cas.ts

@@ -0,0 +1,52 @@
+// 임대 CAS 판정(순수) — 공개 코어(`elanous role …`)가 쓰는 부분.
+// 원래 scripts/botlab/core-lease.ts 에 있었으나 scripts/botlab/** 는 공개본에서 빠진다(release/public-export.yaml)
+// ⇒ 공개판에서 `role-cli.ts` 가 모듈을 못 찾아 PWA 빌드·기동이 깨졌다(📏 2026-09-27 0.2.3 prepare). botlab 은 여기서 다시 내보낸다.
+
+/**
+ * 🔎⛔⭐ **「없다」와 「못 읽었다」를 gcloud 문면에서 «가른다»**
+ *
+ * 🩸 계기(라이브): 첫 판은 `404|not found` 만 봤는데 gcloud 는 이렇게 낸다 —
+ *    ***`The following URLs matched no objects or files`***. ⇒ ***진짜 「없다」가 「못 읽었다」로 떨어졌다.***
+ * ⛔ 그 둘이 갈려야 하는 이유: 「없다」는 ***CAS 를 `--if-generation-match=0` 으로 시도할 수 있는*** 상태이고,
+ *    「못 읽었다」는 ***아무것도 하면 안 되는*** 상태다.
+ * 📌 그래서 이 판정을 «순수»로 꺼냈다 — 시험이 gcloud 문면을 «그대로» 물 수 있게.
+ */
+export function isAbsentSaid(said: string): boolean {
+  return /\b404\b/.test(said)
+    || /not found/i.test(said)
+    || /does not exist/i.test(said)
+    || /matched no objects/i.test(said);     // ⇐ 🩸 라이브가 잡은 문면
+}
+
+
+export type CasOutcome =
+  /** 이겼다 — 내가 잡았다/갱신했다. */
+  | { readonly kind: 'won' }
+  /** ⭐ ***졌다*** — 그 사이 남이 썼다(412). ⛔ 「실패」가 아니라 «정상 결과»다. */
+  | { readonly kind: 'lost'; readonly detail: string }
+  /** ⛔ 「졌다」로 접지 «않는다» — 네트워크·자격·버킷 문제일 수 있다. */
+  | { readonly kind: 'unmeasured'; readonly why: string };
+
+/**
+ * 🔐⭐⭐ **CAS 산출을 «셋»으로 가른다** — ⛔ 이것이 이 파일에서 가장 중요한 함수다.
+ *
+ * 🔑 ***「졌다」와 「못 쟀다」를 뭉치면 이 설계가 무너진다***:
+ * ```
+ * 「졌다」    ⇒ 남이 primary 다 — ***정상***이고, 나는 조용히 물러난다
+ * 「못 쟀다」 ⇒ 내가 «모른다» — ⛔ 그때 ***물러나도 안 되고 잡아도 안 된다***
+ * ```
+ * ⛔ 그 둘을 같은 값으로 내면 「네트워크가 끊겼을 뿐인데 primary 를 넘겨준다」가 된다.
+ */
+export function interpretCasResult(r: { readonly code: number | null; readonly said: string }): CasOutcome {
+  if (r.code === 0) return { kind: 'won' };
+  const said = r.said ?? '';
+  // 📏 gcloud 는 전제조건 실패를 `412` ⊕ `PreconditionFailed`/`does not match` 로 낸다.
+  //    ⛔ 코드 하나에 안 기댄다 — 문면과 «둘 다» 본다(gcloud 판이 바뀌어도 한쪽이 남는다).
+  if (/\b412\b/.test(said) || /precondition/i.test(said) || /generation.*(match|mismatch)/i.test(said)) {
+    return { kind: 'lost', detail: said.trim().split('\n').slice(-2).join(' / ').slice(0, 200) };
+  }
+  return {
+    kind: 'unmeasured',
+    why: `CAS 가 «졌는지 못 쟀는지» 모른다(code=${r.code}) — ${said.trim().split('\n').slice(-2).join(' / ').slice(0, 160)}`,
+  };
+}