elanous 0.2.6 → 0.2.7

package/scripts/release-loop/known-issues-node.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { emitNodeResult, readGraphContext, runCommand, type CommandRunner, type GraphContext } from './node-verdict.js';
+
+const FALLBACK = 'Known issues have been reported for this release.';
+// No fix schedule is promised here — the inputs do not carry one (review R2).
+const INTRO = 'The following issues are known in this release.';
+// A known-issues bullet describes a problem that is still there; «fixed / resolved» wording turns it into a false claim.
+const resolved = /\b(?:fixed|resolved|no longer|has been addressed|is addressed|was addressed)\b/i;
+const unsafe = /[^\x20-\x7e]|#\d+|\/Users\/|\.test\.ts\b|\[(?:TC|MK|OP|UX|S|T|F|O)\]|\b(?:TC|MK|OP|UX)\s+track\b|\b(?:PR|pull request)\s*\d+\b|\b(?:scripts|src|test)\/\S+|\bfile:\/\/|(?<![\w:/])\/(?!\/)[\w.-]+(?:\/[\w.-]+)*|\b[A-Z]:\\(?:[^\s\\]+\\)*[^\s\\]+|\b(?:RFC|HANDOFF|MANUAL)-/i;
+
+type Issue = { id: string; title?: string; evidence?: string; note?: string };
+
+function issues(value: unknown, kind: 'checklist' | 'accepted'): Issue[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every((item) => item && typeof item === 'object'
+    && typeof item.id === 'string' && item.id.trim()
+    && (kind === 'checklist' ? typeof item.title === 'string' && typeof item.evidence === 'string' : typeof item.note === 'string'))) {
+    throw new Error(`invalid ${kind} known issues`);
+  }
+  return value as Issue[];
+}
+
+function generatedBullets(raw: string, sourceIds: string[]): string[] {
+  const envelope: unknown = JSON.parse(raw.trim());
+  const reply = envelope && typeof envelope === 'object' && !Array.isArray(envelope) && 'reply' in envelope
+    ? envelope.reply : envelope;
+  if (typeof reply !== 'string') throw new Error('empty ask reply');
+  const entries: unknown = JSON.parse(reply.replace(/^```(?:json)?\s*\n|\n```\s*$/g, '').trim());
+  if (!Array.isArray(entries) || entries.length !== sourceIds.length || new Set(sourceIds).size !== sourceIds.length) {
+    throw new Error('known issues response does not cover every input ID');
+  }
+  const byId = new Map<string, string>();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)
+      || typeof entry.id !== 'string' || typeof entry.bullet !== 'string'
+      || byId.has(entry.id) || !sourceIds.includes(entry.id)) {
+      throw new Error('known issues response does not cover every input ID');
+    }
+    byId.set(entry.id, entry.bullet);
+  }
+  if (sourceIds.some((id) => !byId.has(id))) throw new Error('known issues response does not cover every input ID');
+  return sourceIds.map((id) => byId.get(id)!);
+}
+
+function coversIssue(bullet: string, issue: Issue, others: Issue[]): boolean {
+  const source = issue.title ?? issue.note ?? '';
+  const words = source.toLowerCase().match(/[a-z]{5,}/g) ?? [];
+  const otherWords = new Set(others.flatMap((other) => ((other.title ?? other.note ?? '').toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5))));
+  const publicWords = new Set((bullet.toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5)));
+  const distinctive = [...new Set(words.map((word) => word.slice(0, 5)))].filter((word) => !otherWords.has(word));
+  const negative = /\b(?:not|never|no|cannot|can't|doesn't|don't|won't|fails? to|isn't|aren't)\b/i;
+  if (negative.test(source) && !negative.test(bullet)) return false;
+  // A source with no English words to compare (e.g. a Korean checklist title) is covered structurally —
+  // one bullet per input ID — instead of blocking the release (review R2).
+  if (words.length === 0) return true;
+  return distinctive.length > 0 && distinctive.filter((word) => publicWords.has(word)).length >= Math.min(issue.note === undefined ? 1 : 2, distinctive.length);
+}
+
+function cleanBullet(text: string): string | null {
+  const line = text.trim();
+  if (!line || /^[-*]\s/.test(line) || unsafe.test(line) || /[{}<>\[\]`]/.test(line) || (line.match(/[.!?](?:\s|$)/g) ?? []).length > 2) return null;
+  return line;
+}
+
+function command(run: CommandRunner, program: string, args: string[], cwd?: string): string {
+  const result = run(program, args, cwd);
+  if (result.status !== 0) throw new Error(`${program} ${args[0]} failed: ${result.stderr || result.stdout}`);
+  return result.stdout;
+}
+
+export function runKnownIssues(context: GraphContext = readGraphContext(), run: CommandRunner = runCommand) {
+  const version = context.input.version;
+  const worktree = context.outputs.docs?.worktree;
+  if (typeof worktree !== 'string' || !worktree || !existsSync(worktree)) throw new Error('docs 워크트리 없음');
+  if (context.outputs.docs?.branch !== `release-docs/${version}`) throw new Error('docs branch/version mismatch');
+  const notes = join(worktree, 'release/public/docs/releases', `${version}.md`);
+  if (!existsSync(notes)) throw new Error(`release notes missing: ${notes}`);
+  const checklist = issues(context.outputs['checklist-gate']?.knownIssues, 'checklist');
+  const accepted = issues(context.input.acceptedRegressions, 'accepted');
+  const sources = { checklist: checklist.length, accepted: accepted.length };
+  if (!checklist.length && !accepted.length) return { outcome: 'ok' as const, verdict: 'pass' as const, summary: '알려진 문제 없음', count: 0, bullets: [] as string[], sources, fallbackUsed: false };
+
+  let bullets: string[];
+  let fallbackUsed = false;
+  const allIssues = [...checklist, ...accepted];
+  const sourceIds = allIssues.map((issue) => issue.id);
+  const prompt = `Write public English release-note bullets for these known issues. Describe only user-visible impact; include a one-line workaround when available. No internal names, test paths, track names, PR numbers, or people. Each bullet must have at most two sentences. Return ONLY a JSON array with exactly one object {"id":"input ID","bullet":"English public sentence"} for each input, using each input ID exactly once. Do not include IDs in bullet text. Input: ${JSON.stringify({ checklist, acceptedRegressions: accepted })}`;
+  let response: ReturnType<CommandRunner>;
+  try {
+    response = run('elanous', ['--test', 'ask', '--json', prompt]);
+  } catch {
+    response = { status: 1, stdout: '', stderr: '' };
+  }
+  if (response.status !== 0) {
+    bullets = [FALLBACK];
+    fallbackUsed = true;
+  } else {
+    try {
+      bullets = generatedBullets(response.stdout, sourceIds).map((line, index) => {
+        const safe = cleanBullet(line);
+        if (!safe) {
+          fallbackUsed = true;
+          return FALLBACK;
+        }
+        if (resolved.test(safe)) throw new Error(`bullet for ${sourceIds[index]} claims the issue is resolved`);
+        if (!coversIssue(safe, allIssues[index]!, allIssues.filter((_, otherIndex) => otherIndex !== index))) {
+          throw new Error(`bullet does not identify input ${sourceIds[index]}`);
+        }
+        return safe;
+      });
+      if (new Set(bullets).size !== bullets.length && bullets.some((bullet) => bullet !== FALLBACK)) {
+        throw new Error('known issues response repeats an issue instead of covering each input');
+      }
+      bullets = [...new Set(bullets)];
+    } catch (error) {
+      throw new Error(`known issues coverage not verified: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const original = readFileSync(notes, 'utf8');
+  const heading = /^## Known issues\s*$/m;
+  const match = heading.exec(original);
+  let updated: string;
+  if (match) {
+    const start = match.index + match[0].length;
+    const next = /^## /gm;
+    next.lastIndex = start;
+    const end = next.exec(original)?.index ?? original.length;
+    const section = original.slice(start, end);
+    const additions = bullets.filter((bullet) => !section.split(/\r?\n/).some((line) => line.trim() === `- ${bullet}`));
+    const before = original.slice(0, end);
+    updated = additions.length ? `${before}${before.endsWith('\n') ? '' : '\n'}${additions.map((bullet) => `- ${bullet}`).join('\n')}\n\n${original.slice(end)}` : original;
+  } else {
+    updated = `${original.trimEnd()}\n\n## Known issues\n\n${INTRO}\n\n${bullets.map((bullet) => `- ${bullet}`).join('\n')}\n`;
+  }
+  if (updated !== original) {
+    writeFileSync(notes, updated);
+    command(run, 'git', ['add', '--', `release/public/docs/releases/${version}.md`], worktree);
+    command(run, 'git', ['commit', '-m', `docs: known issues for ${version}`], worktree);
+  }
+  // Push whenever the branch is ahead of its remote — a rerun after a failed push finds the bullets already in the file (review R2).
+  command(run, 'git', ['fetch', 'origin', `release-docs/${version}`], worktree);
+  const ahead = Number(command(run, 'git', ['rev-list', '--count', `origin/release-docs/${version}..HEAD`], worktree).trim());
+  if (!Number.isFinite(ahead)) throw new Error('could not compare release-docs branch with its remote');
+  if (ahead > 0) command(run, 'git', ['push', 'origin', `release-docs/${version}`], worktree);
+  return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `known issues: ${bullets.length}`, count: bullets.length, bullets, sources, fallbackUsed };
+}
+
+if (import.meta.main) {
+  try {
+    const result = runKnownIssues();
+    emitNodeResult(result);
+    process.exitCode = 0;
+  } catch (error) {
+    emitNodeResult({ outcome: 'fail', verdict: 'fail', summary: error instanceof Error ? error.message : String(error), count: 0, bullets: [], sources: { checklist: 0, accepted: 0 }, fallbackUsed: false });
+    process.exitCode = 1;
+  }
+}

package/scripts/release-loop/npm-publish-node.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { sendOutbound } from '../../src/domains/outbound-alert.js';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { emitNodeResult, readGraphContext, type GraphContext } from './node-verdict.js';
+
+type Result = { outcome: 'ok' | 'fail'; verdict: 'pass' | 'fail'; summary: string; npm?: 'published' | 'already-published' | 'staged-not-visible'; humanAction?: 'npm-support' };
+type Exec = (command: string, args: string[], env?: NodeJS.ProcessEnv) => { status: number | null; stdout: string; stderr: string };
+type Registry = (url: string) => Promise<{ status: number; body: unknown }>;
+export interface NpmPublishDeps {
+  exec?: Exec;
+  registry?: Registry;
+  sleep?: (ms: number) => Promise<void>;
+  stateDir?: string;
+  alert?: (text: string, kind: string) => boolean;
+  log?: (version: string, waitedMinutes: number) => void;
+}
+
+const exec: Exec = (command, args, env) => {
+  const result = spawnSync(command, args, { encoding: 'utf8', env: env ?? process.env, maxBuffer: 1024 * 1024, timeout: 300_000 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? String(result.error ?? '') };
+};
+const registry: Registry = async (url) => {
+  const response = await fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+  return { status: response.status, body: response.ok ? await response.json() : null };
+};
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+const PACKAGE_URL = 'https://registry.npmjs.org/elanous';
+
+function redact(text: string, token: string): string {
+  return token ? text.replaceAll(token, '[REDACTED]') : text;
+}
+function reason(error: unknown, token: string): string {
+  return redact(error instanceof Error ? error.message : String(error), token).replace(/[\r\n]+/g, ' ').slice(0, 500);
+}
+function metadata(value: unknown): { name?: string; version?: string } {
+  if (!value || typeof value !== 'object') return {};
+  return value as { name?: string; version?: string };
+}
+
+export async function runNpmPublish(context: GraphContext = readGraphContext(), deps: NpmPublishDeps = {}): Promise<Result> {
+  const version = context.input.version;
+  let token = '';
+  try {
+    if (context.outputs.publish?.outcome !== 'ok') throw new Error('publish must succeed before npm publish');
+    const stateDir = deps.stateDir ?? effectiveInstanceRoot();
+    const candidate = join(stateDir, 'release', version, 'prepared', 'dist', 'elanous.tgz');
+    const run = deps.exec ?? exec;
+    const readRegistry = deps.registry ?? registry;
+    const wait = deps.sleep ?? sleep;
+    const waitMinutes = context.input.npmWaitMinutes ?? 40;
+    if (typeof waitMinutes !== 'number' || !Number.isFinite(waitMinutes) || waitMinutes < 0 || waitMinutes > 40) throw new Error('input.npmWaitMinutes must be between 0 and 40');
+    const archive = run('tar', ['-xOzf', candidate, 'package/package.json']);
+    if (archive.status !== 0) throw new Error(`npm archive invalid: ${archive.stderr}`);
+    const pkg = metadata(JSON.parse(archive.stdout));
+    if (pkg.name !== 'elanous' || pkg.version !== version) throw new Error('npm archive package name/version mismatch');
+    const inspect = async (): Promise<{ visible: boolean; tagged: boolean }> => {
+      const [manifest, tags] = await Promise.all([readRegistry(`${PACKAGE_URL}/${version}`), readRegistry(PACKAGE_URL)]);
+      if (manifest.status !== 200 && manifest.status !== 404) throw new Error(`npm registry version lookup failed (${manifest.status})`);
+      if (tags.status !== 200) throw new Error(`npm registry tags lookup failed (${tags.status})`);
+      const latest = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
+        ? (tags.body as { 'dist-tags'?: { latest?: unknown } })['dist-tags']?.latest : undefined;
+      if (manifest.status === 200 && (metadata(manifest.body).name !== 'elanous' || metadata(manifest.body).version !== version))
+        throw new Error('npm registry version metadata mismatch');
+      return { visible: manifest.status === 200, tagged: manifest.status === 200 && latest === version };
+    };
+    const before = await inspect();
+    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with latest tag` };
+    if (!before.visible) {
+      const tokenFile = context.input.npmTokenFile ?? join(stateDir, 'secrets', 'npm-token');
+      if (typeof tokenFile !== 'string' || !tokenFile.trim()) throw new Error('input.npmTokenFile must be a path');
+      token = readFileSync(tokenFile, 'utf8').trim();
+      if (!token) throw new Error('npm token file empty');
+      const dir = mkdtempSync(join(tmpdir(), 'release-npmrc-'));
+      let published;
+      try {
+        const npmrc = join(dir, 'npmrc');
+        writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600, flag: 'wx' });
+        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', 'latest', '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
+      } finally { rmSync(dir, { recursive: true, force: true }); }
+      const output = `${published.stdout}\n${published.stderr}`;
+      const staged = published.status !== 0 && /\bE409\b/i.test(output) && /previously staged/i.test(output);
+      if (published.status !== 0 && !staged) throw new Error(`npm publish failed (rc=${published.status}): ${redact(output, token)}`);
+    }
+    const polls = Math.ceil(waitMinutes * 60 / 30);
+    let last = before;
+    for (let i = 0; i <= polls; i++) {
+      last = await inspect();
+      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with latest tag` };
+      if (i < polls) await wait(Math.min(30_000, waitMinutes * 60_000 - i * 30_000));
+    }
+    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.latest did not reach ${version} within ${waitMinutes} minutes`);
+    try { (deps.log ?? ((v, minutes) => debug.log('release-loop.npm', 'staged-not-visible', { version: v, waitedMinutes: minutes })))(version, waitMinutes); } catch { /* observation must not mask npm's staged state */ }
+    try { (deps.alert ?? sendOutbound)(`npm ${version} 가 스테이징에 멈춤 — 계정 소유자 확인 필요`, 'alert'); } catch { /* alert failure must not block docs */ }
+    return { outcome: 'ok', verdict: 'pass', npm: 'staged-not-visible', humanAction: 'npm-support', summary: 'npm 스테이징 — 레지스트리에 아직 없음' };
+  } catch (error) {
+    return { outcome: 'fail', verdict: 'fail', summary: `npm ${version} failed: ${reason(error, token)}` };
+  }
+}
+
+if (import.meta.main) {
+  let version = '';
+  try {
+    const context = readGraphContext();
+    version = context.input.version;
+    const result = await runNpmPublish(context);
+    debug.log('release-loop.npm', 'result', { version, outcome: result.outcome, npm: result.npm });
+    emitNodeResult(result);
+    process.exitCode = result.outcome === 'ok' ? 0 : 1;
+  } catch {
+    emitNodeResult({ outcome: 'fail', verdict: 'fail', summary: 'npm publish context unavailable' });
+    process.exitCode = 1;
+  }
+}

package/scripts/release-loop/ops-upgrade-node.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+import { homedir } from 'node:os';
+import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandResult, type CommandRunner } from './node-verdict.js';
+
+interface HostResult { host: string; ok: boolean; before: string; after: string; error?: string; skipped?: string }
+
+function firstLine(text: string): string { return text.trim().split(/\r?\n/)[0]?.trim() ?? ''; }
+
+function reason(result: CommandResult): string {
+  const data = lastResult(result);
+  const message = [data?.error, data?.reason, data?.message, result.stderr, result.stdout].find((part) => typeof part === 'string' && part.trim());
+  const line = firstLine(String(message ?? `명령 실패 (rc=${result.status})`));
+  return /\b404\b/.test(line) ? `공급원에 판 없음 (404): ${line}` : line;
+}
+
+function quote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+export function runOpsUpgrade(run: CommandRunner = runCommand) {
+  const context = readGraphContext();
+  const hosts = context.input.opsHosts;
+  if (hosts === undefined || (Array.isArray(hosts) && hosts.length === 0)) {
+    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: '운영 대상 없음 — 건너뜀', hosts: [] as HostResult[] };
+  }
+  if (!Array.isArray(hosts) || !hosts.every((host) => typeof host === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(host))) throw new Error('input.opsHosts must be an array of host names');
+  if (context.outputs.verify?.outcome !== 'ok') throw new Error('verify must pass before ops upgrade');
+  const version = context.input.version;
+  if (nodeOutput(context, 'publish', 'tag') !== `v${version}`) throw new Error('published tag/version mismatch');
+  const internalDist = context.input.internalDist;
+  if (internalDist !== undefined && (typeof internalDist !== 'string' || !internalDist.trim())) throw new Error('input.internalDist must be a path string');
+  const feedPath = typeof internalDist === 'string' && internalDist.startsWith('~/') ? `${homedir()}/${internalDist.slice(2)}` : internalDist;
+  let feedError = '';
+  if (typeof feedPath === 'string') {
+    try {
+      const feed = run('bun', ['scripts/publish-internal-dist.ts', '--checkout', process.cwd(), '--out', feedPath]);
+      const data = lastResult(feed);
+      if (feed.status !== 0 || data?.ok !== true || data.version !== version) feedError = `내부 피드 발행 실패: ${feed.status === 0 && data?.ok === true ? `판 불일치 (${String(data.version)})` : reason(feed)}`;
+    } catch (error) { feedError = `내부 피드 발행 실패: ${firstLine(String(error))}`; }
+  }
+  const results: HostResult[] = [];
+  for (const host of hosts as string[]) {
+    if (host !== 'local' && feedError) {
+      results.push({ host, ok: false, before: '', after: '', skipped: '내부 피드 발행 실패', error: feedError });
+      continue;
+    }
+    const command = (args: string[]): CommandResult => host === 'local'
+      ? run('elanous', args)
+      : run('ssh', [host, `PATH="$HOME/.local/bin:$HOME/.bun/bin:$PATH"; export PATH; elanous ${args.map(quote).join(' ')}`]);
+    let before = '';
+    let after = '';
+    try {
+      const previous = command(['--version']);
+      if (previous.status === 0) before = firstLine(previous.stdout);
+      const updated = command(['update', '--version', version, '--json', ...(context.input.opsRestart === true ? ['--restart'] : [])]);
+      const updateResult = lastResult(updated);
+      if (updated.status !== 0 || updateResult?.exitCode !== 0 || updateResult.installedVersion !== version) {
+        const error = updated.status === 0 && updateResult?.exitCode === 0
+          ? `설치판 불일치 (기대 ${version}, 실제 ${String(updateResult.installedVersion)})` : reason(updated);
+        results.push({ host, ok: false, before, after, error });
+        continue;
+      }
+      const current = command(['--version']);
+      if (current.status !== 0) {
+        results.push({ host, ok: false, before, after, error: reason(current) });
+        continue;
+      }
+      after = firstLine(current.stdout);
+      if (after.split(/\s+/)[0] !== version) {
+        results.push({ host, ok: false, before, after, error: `올렸는데 판이 그대로 (기대 ${version}, 실제 ${after || '없음'})` });
+        continue;
+      }
+      results.push({ host, ok: true, before, after });
+    } catch (error) {
+      results.push({ host, ok: false, before, after, error: firstLine(String(error)) });
+    }
+  }
+  const failures = results.filter((result) => !result.ok);
+  return { outcome: failures.length || feedError ? 'fail' as const : 'ok' as const,
+    verdict: failures.length || feedError ? 'fail' as const : 'pass' as const,
+    summary: failures.length ? `운영 판올림 실패: ${failures.map(({ host, error }) => `${host}: ${error}`).join('; ')}${feedError && !failures.some((item) => item.skipped) ? `; ${feedError}` : ''}`
+      : feedError || `운영 판올림 ${version} · ${results.length}대 확인`, hosts: results };
+}
+
+if (import.meta.main) {
+  let version = '';
+  try { version = readGraphContext().input.version; process.exitCode = finishNode('ops-upgrade', version, runOpsUpgrade()); }
+  catch (error) { process.exitCode = finishNode('ops-upgrade', version, errorResult(error)); }
+}

package/scripts/release-loop/release-readiness.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { checklistGate, type ChecklistGate } from '../../src/release-loop/checklist.js';
+
+export type ReleaseReadiness =
+  | { ready: false; reason: 'already-published'; details: string }
+  | { ready: false; reason: 'already-running'; details: string }
+  | { ready: false; reason: 'checklist-blocked'; details: ChecklistGate }
+  | { ready: true; reason: 'ready'; details: ChecklistGate };
+
+export interface ReleaseReadinessDeps {
+  ledgerRoot?: string;
+  checklist?: typeof checklistGate;
+  isPidAlive?: (pid: number) => boolean;
+}
+
+function readIfPresent(path: string): string | undefined {
+  try { return readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+    if ((error as NodeJS.ErrnoException).code === 'EPERM') return true;
+    throw error;
+  }
+}
+
+/** Read-only preflight; callers own acquiring and releasing run.lock around the graph. */
+export function releaseReadiness(version: string, deps: ReleaseReadinessDeps = {}): ReleaseReadiness {
+  if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(deps.ledgerRoot ?? releaseLedgerRoot(), 'release', version);
+  const record = readIfPresent(join(dir, 'release.json'));
+  if (record) {
+    const data = JSON.parse(record) as { publishedAt?: unknown };
+    if (typeof data.publishedAt === 'string' && data.publishedAt.trim()) {
+      return { ready: false, reason: 'already-published', details: data.publishedAt };
+    }
+  }
+  const lock = readIfPresent(join(dir, 'run.lock'));
+  if (lock) {
+    let pid: unknown;
+    try { pid = (JSON.parse(lock) as { pid?: unknown } | null)?.pid; }
+    catch { pid = undefined; }
+    if (typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 && (deps.isPidAlive ?? isPidAlive)(pid)) {
+      return { ready: false, reason: 'already-running', details: String(pid) };
+    }
+  }
+  const gate = (deps.checklist ?? checklistGate)(version);
+  if (!gate.ok) return { ready: false, reason: 'checklist-blocked', details: gate };
+  return { ready: true, reason: 'ready', details: gate };
+}

package/scripts/release-loop/unattended-release.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
+import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { userConfigPath } from '../../src/user-config.js';
+import { checklistGate } from '../../src/release-loop/checklist.js';
+import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
+
+export interface ReleaseLoopConfig {
+  gatePodPool?: string;
+  gatePodBunCache?: string;
+  gatePodShards?: number;
+  gatePodShardTimeoutSeconds?: number;
+  gateRemote?: string;
+  gateRemoteMirror?: string;
+  opsHosts?: string[];
+  internalDist?: string;
+  opsRestart?: boolean;
+}
+
+export interface ReleaseRunInput extends ReleaseLoopConfig {
+  version: string;
+  previousVersion: string;
+  gatePodPool: string;
+}
+
+export interface UnattendedReleaseDeps {
+  ledgerRoot?: string;
+  config?: ReleaseLoopConfig;
+  configPath?: string;
+  graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
+  checklist?: typeof checklistGate;
+}
+
+function compareVersions(a: string, b: string): number {
+  const aa = a.split('.').map(BigInt), bb = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (aa[i]! < bb[i]!) return -1;
+    if (aa[i]! > bb[i]!) return 1;
+  }
+  return 0;
+}
+
+/** Only completed publications in the release ledger count as a prior release. */
+export function latestPublishedPreviousVersion(version: string, ledgerRoot = releaseLedgerRoot()): string {
+  if (!VERSION.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(ledgerRoot, 'release');
+  const versions = existsSync(dir) ? readdirSync(dir) : [];
+  const published = versions.filter((candidate) => {
+    if (!VERSION.test(candidate) || compareVersions(candidate, version) >= 0) return false;
+    try {
+      const record = JSON.parse(readFileSync(join(dir, candidate, 'release.json'), 'utf8')) as { version?: unknown; publishedAt?: unknown };
+      return record.version === candidate && typeof record.publishedAt === 'string' && record.publishedAt.trim().length > 0;
+    } catch { return false; }
+  });
+  const previous = published.sort((a, b) => compareVersions(b, a))[0];
+  if (!previous) throw new Error(`no published previous release before ${version} in ${dir}`);
+  return previous;
+}
+
+export function releaseLoopConfig(configPath = getElanousConfigDirOverride() ? join(effectiveInstanceRoot(), 'config.json') : userConfigPath()): ReleaseLoopConfig {
+  if (!existsSync(configPath)) return {};
+  const raw = JSON.parse(readFileSync(configPath, 'utf8')) as { release?: { loop?: ReleaseLoopConfig } };
+  return raw.release?.loop ?? {};
+}
+
+export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDeps = {}): ReleaseRunInput {
+  const config = deps.config ?? releaseLoopConfig(deps.configPath);
+  const pool = config.gatePodPool;
+  if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
+  const previousVersion = latestPublishedPreviousVersion(version, deps.ledgerRoot);
+  return {
+    ...config,
+    version, previousVersion,
+    gatePodPool: pool.trim(),
+  };
+}
+
+/** Fail closed at the entry boundary, before any graph node can change a release. */
+export async function runUnattendedRelease(
+  opts: { version: string; dryRun?: boolean },
+  deps: UnattendedReleaseDeps = {},
+): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  const input = buildReleaseRunInput(opts.version, deps);
+  if (opts.dryRun) return { input, dryRun: true };
+  const gate = (deps.checklist ?? checklistGate)(opts.version);
+  if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  const state = await (deps.graph ?? runGraph)(GRAPH, { input });
+  return { input, dryRun: false, state };
+}

package/scripts/ux/measure-first-text.ts

@@ -0,0 +1,102 @@
+// Usage: bun scripts/ux/measure-first-text.ts --questions questions.json [--url http://127.0.0.1:3456] [--token-stdin] [--json]
+// questions.json is a nonempty JSON array of nonempty question strings. Each question starts a fresh session.
+import { readFileSync } from 'node:fs';
+
+export interface FirstTextMeasurement {
+  question: string;
+  firstTextMs: number;
+  delta: string;
+}
+
+/** Stop the clock on the first complete, nonempty text-delta SSE event, not on response headers or turn-begin. */
+export async function measureFirstText(
+  question: string,
+  url: string,
+  options: { token?: string; fetch?: typeof fetch; now?: () => number } = {},
+): Promise<FirstTextMeasurement> {
+  const fetchFn = options.fetch ?? fetch;
+  const now = options.now ?? (() => performance.now());
+  const controller = new AbortController();
+  const started = now();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  try {
+    const response = await fetchFn(new URL('/v1/prompt/stream', url), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'text/event-stream',
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+      },
+      body: JSON.stringify({ userText: question }),
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    if (!response.body) throw new Error('SSE response has no body');
+    reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      // SSE separators can straddle arbitrary UTF-8 chunks (including CRLF boundaries).
+      let boundary: RegExpExecArray | null;
+      while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null) {
+        const frame = buffer.slice(0, boundary.index);
+        buffer = buffer.slice(boundary.index + boundary[0].length);
+        const event = /^event:\s*(.*)$/m.exec(frame)?.[1]?.trim();
+        const data = frame.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trimStart()).join('\n');
+        if (event === 'text-delta') {
+          const payload: unknown = JSON.parse(data);
+          const delta = payload && typeof payload === 'object' && 'delta' in payload ? payload.delta : undefined;
+          if (typeof delta === 'string' && delta.length > 0) {
+            return { question, firstTextMs: now() - started, delta };
+          }
+        }
+        if (event === 'error') throw new Error(`SSE error: ${data}`);
+        if (event === 'turn-end') throw new Error('Turn ended without a text-delta');
+      }
+    }
+    throw new Error('SSE stream ended without a text-delta');
+  } finally {
+    // Do not leave the daemon generating the rest of a turn after the measurement.
+    if (reader) await reader.cancel().catch(() => {});
+    controller.abort();
+  }
+}
+
+export async function run(argv: string[], deps: { fetch?: typeof fetch; now?: () => number; stdin?: () => Promise<string> } = {}): Promise<FirstTextMeasurement[]> {
+  let url = 'http://127.0.0.1:3456';
+  let questionsPath: string | undefined;
+  let json = false;
+  let tokenStdin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--token-stdin') tokenStdin = true;
+    else if (arg === '--url' || arg === '--questions') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--url') url = value;
+      else questionsPath = value;
+    } else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!questionsPath) throw new Error('Usage: --questions <JSON file> [--url <base URL>] [--token-stdin] [--json]');
+  const questions: unknown = JSON.parse(readFileSync(questionsPath, 'utf8'));
+  if (!Array.isArray(questions) || !questions.length || !questions.every((q) => typeof q === 'string' && q.trim().length > 0)) {
+    throw new Error('--questions must be a nonempty JSON array of nonempty strings');
+  }
+  const token = tokenStdin ? (await (deps.stdin ?? (() => Bun.stdin.text()))()).trim() : undefined;
+  const results: FirstTextMeasurement[] = [];
+  for (const question of questions as string[]) {
+    results.push(await measureFirstText(question, url, { token, fetch: deps.fetch, now: deps.now }));
+  }
+  if (json) console.log(JSON.stringify(results));
+  else for (const result of results) console.log(`${result.firstTextMs.toFixed(1)} ms\t${result.question}`);
+  return results;
+}
+
+if (import.meta.main) {
+  try { await run(process.argv.slice(2)); }
+  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+}