elanous 0.2.19 → 0.2.20

package/src/hq/fence-outcomes.ts

@@ -0,0 +1,63 @@
+// LOOPCHECK-FENCE (0.2.20): an hq-fence cron execution is one process, not a loop.
+// Each wrapped run leaves its rc in a per-role streak file; the wrapper's owner alert
+// raises a seat request only when the same role failed in consecutive runs, keyed per
+// role so the seat request journal holds at most one `loopcheck:hq-fence:<role>` per day.
+// No loops/ import here: hq.ts records through this module and loops/registry imports hq.ts.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Database } from 'bun:sqlite';
+import { debug } from '../debug/log.js';
+
+/** The role is the file name; `lastAt` is shown in the owner alert so TC sees when the streak last grew. */
+export interface FenceOutcome { consecutiveFailures: number; lastRc: number; lastAt: string }
+
+/** Two failures in a row: one rc=1 from a job that recovers on the next fire is not a fence fault. */
+export const FENCE_FAILURE_STREAK = 2;
+
+const safeRole = (role: string): string => role.replace(/[^\w.-]/g, '_') || 'unknown';
+
+export function fenceOutcomePath(dir: string, role: string): string {
+  return join(dir, `${safeRole(role)}.json`);
+}
+
+/** Default directory next to the host-local lease view (`<config>/hq/fence-outcomes`). */
+export function fenceOutcomeDir(localPath: string): string {
+  return join(dirname(localPath), 'fence-outcomes');
+}
+
+export function readFenceOutcome(dir: string, role: string): FenceOutcome | null {
+  try {
+    const parsed = JSON.parse(readFileSync(fenceOutcomePath(dir, role), 'utf8')) as Partial<FenceOutcome>;
+    return typeof parsed.consecutiveFailures === 'number' ? parsed as FenceOutcome : null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    debug.log('hq.fence-outcome', 'read-failed', { role, error: String(error) });
+    return null;
+  }
+}
+
+/** rc 0 resets the streak; any other rc extends it. A skipped (not-holder) run is not recorded.
+ * Overlapping runs of one role serialize the read-modify-write on an SQLite lock (released even on SIGKILL). */
+export function recordFenceOutcome(dir: string, role: string, rc: number, now: Date = new Date()): FenceOutcome {
+  const path = fenceOutcomePath(dir, role);
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = new Database(`${path}.lock.sqlite`);
+  try {
+    lock.exec('PRAGMA busy_timeout = 10000');
+    lock.exec('BEGIN EXCLUSIVE');
+    try {
+      const previous = readFenceOutcome(dir, role);
+      const outcome: FenceOutcome = { consecutiveFailures: rc === 0 ? 0 : (previous?.consecutiveFailures ?? 0) + 1, lastRc: rc, lastAt: now.toISOString() };
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(outcome));
+      renameSync(tmp, path);
+      lock.exec('COMMIT');
+      return outcome;
+    } catch (error) { lock.exec('ROLLBACK'); throw error; }
+  } finally { lock.close(); }
+}
+
+/** `hq-fence: fence failed (rc=1, role=seat-loop)` → `seat-loop`; other wrapper reasons have no role. */
+export function fenceAlertRole(reason: string): string | null {
+  return /\brole=([\w.-]+)/.exec(reason)?.[1] ?? null;
+}

package/src/hq/fence-wrapper.ts

@@ -3,6 +3,9 @@ import { chmodSync, constants, copyFileSync, lstatSync, mkdirSync, mkdtempSync,
 import { dirname, isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { createPatch } from 'diff';
+import { debug } from '../debug/log.js';
+import { notifyOwners } from '../loops/checker.js';
+import { FENCE_FAILURE_STREAK, fenceAlertRole, readFenceOutcome } from './fence-outcomes.js';
 
 const quote = (value: string): string => `'${value.replaceAll("'", "'\"'\"'")}'`;
 
@@ -121,3 +124,33 @@ export function installHqFenceWrapper(configDir: string, body: string, yes: bool
   } finally { rmSync(tempDir, { recursive: true, force: true }); }
   return { path, preview, ...(backup ? { backup } : {}) };
 }
+
+export interface FenceAlertDeps { root: string; outcomeDir: string; now?: Date }
+
+/**
+ * The wrapper's owner alert. Returns the number of seat requests queued (0 or 1).
+ * - `fence failed (rc, role)`: queued only when that role's streak reached FENCE_FAILURE_STREAK
+ *   (an unknown streak is not read as «first failure» — it is queued, still capped per role/day).
+ * - Any other wrapper failure (entry missing, bun missing, role missing): queued under `hq-fence:wrapper`.
+ */
+export function hqFenceAlert(reason: string, deps: FenceAlertDeps): number {
+  const now = deps.now ?? new Date();
+  const fenceFailure = /fence failed \(rc=/.test(reason);
+  const role = fenceAlertRole(reason);
+  let streak: number | null = null;
+  let lastAt: string | undefined;
+  if (fenceFailure && role) {
+    const outcome = readFenceOutcome(deps.outcomeDir, role);
+    streak = outcome?.consecutiveFailures ?? null;
+    lastAt = outcome?.lastAt;
+    if (streak !== null && streak < FENCE_FAILURE_STREAK) {
+      debug.log('hq.fence-wrapper', 'alert-suppressed', { role, streak, threshold: FENCE_FAILURE_STREAK, reason });
+      return 0;
+    }
+  }
+  const id = `hq-fence:${fenceFailure && role ? role : 'wrapper'}`;
+  const text = streak !== null ? `${reason} · ${streak} consecutive runs (last ${lastAt ?? 'unknown'})` : reason;
+  const added = notifyOwners([{ id, owner: 'TC', enabled: true, registered: true, state: 'failing', reason: text }], { root: deps.root, now });
+  debug.log('hq.fence-wrapper', added ? 'alert-queued' : 'alert-deduplicated', { id, role, streak, reason });
+  return added;
+}

package/src/hq/hq.ts

@@ -10,6 +10,7 @@ import { debug } from '../debug/log.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { getUserConfig, type HqConfig, type HqFenceRole } from '../user-config.js';
+import { fenceOutcomeDir, recordFenceOutcome } from './fence-outcomes.js';
 import { promoteHq, proposeHqPromotion, writeOpSeatRequest } from './promote.js';
 import type { HqOpRequestWriter, PromoteResult } from './promote.js';
 import {
@@ -42,6 +43,8 @@ export interface HqDeps {
   /** Holder/standby views and the arbiter's check use this tailnet probe — never ssh (OP 10-04 09:04). */
   probe?: HostProbe;
   localPath?: string;
+  /** Per-role streak files of wrapped-run rc (LOOPCHECK-FENCE · default next to localPath). */
+  outcomeDir?: string;
   /** Host-local identity, deliberately outside the replicated config/state directory. */
   hostPath?: string;
   /** Seen-generation marker (default hq.seenGenerationFile · ~/.elanous-hq/seen-generation). */
@@ -391,5 +394,12 @@ export function hqFenceRun(role: HqFenceRole, command: string[], deps: HqDeps =
   const [cmd, ...args] = command;
   if (!cmd) throw new Error('hq fence: command required after --');
   const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...process.env, ELANOUS_HQ_GENERATION: String(decided.generation ?? '') } });
-  return r.status ?? 1;
+  const rc = r.status ?? 1;
+  // LOOPCHECK-FENCE: the wrapper's alert reads this streak, so a lone failure is not a seat request.
+  try {
+    const dir = deps.outcomeDir ?? fenceOutcomeDir(deps.localPath ?? join(getElanousConfigDir(), 'hq', 'local.json'));
+    const outcome = recordFenceOutcome(dir, role, rc, new Date(deps.now?.() ?? Date.now()));
+    if (rc !== 0) debug.log('hq.fence', 'run-failed', { role, rc, consecutiveFailures: outcome.consecutiveFailures });
+  } catch (error) { try { debug.log('hq.fence', 'outcome-record-failed', { role, rc, error: String(error) }); } catch { /* fail-soft */ } }
+  return rc;
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import type { SelfDevRunParticipant, SelfDevRunState } from './self-dev/run-stor
 import { applyConfigDirFlagFromArgv } from './cli/config-dir-flag.js';
 import { LOGS_SINCE_OPTION, registerLogsCommands } from './cli/logs-cli.js';
 import { registerDocsCommands } from './cli/docs-cli.js';
+import { registerRetroCommands } from './cli/retro-cli.js';
 import { registerA2ACommands } from './cli/a2a-cli.js';
 import { registerPluginCommands } from './cli/plugin-cli.js';
 import { registerMakeCommand } from './cli/make-cli.js';
@@ -219,13 +220,14 @@ program.enablePositionalOptions();
 
 program.command('preview <target>')
   .description('Isolated PR/branch-head TUI + PWA preview; publish the TUI-COMFORT friction table to a PR')
-  .option('--scenario <id>', 'TUI-COMFORT scenario (default S2)', 'S2')
+  .option('--scenario <id>', 'TUI-COMFORT scenario IDs (comma-separated; default S2)', 'S2')
   .option('--flag <path>', 'Enable an existing config feature flag in main-based preview (repeatable)', (value: string, all: string[]) => [...all, value], [] as string[])
+  .option('--bundle-pr <number>', 'Merge PR head into isolated main preview (repeatable; no flags)', (value: string, all: number[]) => [...all, Number(value)], [] as number[])
   .option('--comment-pr <number>', 'PR to receive a branch/main preview report', (value: string) => Number(value))
-  .action(async (target: string, opts: { scenario: string; flag: string[]; commentPr?: number }) => {
+  .action(async (target: string, opts: { scenario: string; flag: string[]; bundlePr: number[]; commentPr?: number }) => {
     try {
       const { runPrPreview } = await import('./self-dev/pr-preview.js');
-      const result = await runPrPreview({ target, repoRoot: process.cwd(), scenario: opts.scenario, flags: opts.flag, ...(opts.commentPr === undefined ? {} : { commentPr: opts.commentPr }) });
+      const result = await runPrPreview({ target, repoRoot: process.cwd(), scenario: opts.scenario, flags: opts.flag, bundlePrs: opts.bundlePr, ...(opts.commentPr === undefined ? {} : { commentPr: opts.commentPr }) });
       console.log(`preview ${result.status} · ${result.head} · PR #${result.prNumber} · comment posted`);
       if (result.status !== 'passed') process.exitCode = 1;
     } catch (error) {
@@ -1059,10 +1061,12 @@ fenceWrapperCmd.command('install').description('래퍼 제안 또는 백업 후
 fenceWrapperCmd.command('alert <reason>').description('HQ 울타리 실패를 기존 루프 소유자 요청 원장에 적재')
   .action(async (reason: string) => {
     try {
-      const { notifyOwners } = await import('./loops/checker.js');
+      // LOOPCHECK-FENCE: keyed per role (not per pid) and only after consecutive failures of that role.
+      const { fenceOutcomeDir } = await import('./hq/fence-outcomes.js');
+      const { hqFenceAlert } = await import('./hq/fence-wrapper.js');
       const { getElanousConfigDir } = await import('./elanous-config-dir.js');
-      notifyOwners([{ id: `hq-fence:${Date.now()}:${process.pid}`, owner: 'TC', enabled: true, registered: true,
-        state: 'failing', reason }], { root: getElanousConfigDir() });
+      const root = getElanousConfigDir();
+      hqFenceAlert(reason, { root, outcomeDir: fenceOutcomeDir(_joinPath(root, 'hq', 'local.json')) });
     } catch (error) { console.error(`hq fence-wrapper alert: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; }
   });
 hqCmd.command('fence-audit').description('운영 crontab 의 HQ 울타리 밖 쓰기 잡 목록과 감싼 줄 제안(읽기 전용)')
@@ -1905,6 +1909,7 @@ program
   });
 
 registerAutopilotCommands(program);
+registerRetroCommands(program);
 
 // ── memory ──
 const memCmd = program.command('memory').description('Persistent memories injected into every chat turn (user / feedback / project / reference)');
@@ -7679,6 +7684,11 @@ configCmd
   .description('Print all config or one dotted path, e.g. llm.provider (secrets redacted by default)')
   .option('--reveal', 'Print unredacted output and record the reveal')
   .action(async (path: string | undefined, opts: { reveal?: boolean }) => {
+    const { resolveCurrentInstance } = await import('./instance/current.js');
+    const instance = resolveCurrentInstance();
+    if (instance.kind === 'test' && instance.layer === 'tree-derived') {
+      console.error('⚠️ test 우주의 config를 읽습니다 — 운영 값은 --config-dir ~/.elanous');
+    }
     const cfg = getUserConfig() as unknown as Record<string, unknown>;
     const value = path ? getConfigPath(cfg, path) : cfg;
     if (value === undefined) {
@@ -7773,6 +7783,59 @@ configCmd
     ui.info(`unset ${path}`);
   });
 
+// ── config drift / explain (CFG-STORE1 · 0.2.20 · 2026-10-08) — 읽기 전용 «유효 config ⊕ 출처» ──
+// 집(~/.elanous)과 파생 시험 우주(<트리>/.elanous-test) config 사본의 드리프트를 한 명령으로.
+// ⛔ 쓰기 0 · 못 읽음 ≠ 같음 · 비밀 값 가림. 계산 = src/cli/config-drift.ts.
+async function configDriftDiscover(o: { registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) {
+  const { discoverUniverses } = await import('./cli/config-drift.js');
+  return discoverUniverses({
+    ...(o.registry === false ? { registryPath: null } : typeof o.registry === 'string' ? { registryPath: o.registry } : {}),
+    ...(o.treeScan === false ? { treeScanRoots: [] } : o.scanRoot?.length ? { treeScanRoots: o.scanRoot } : {}),
+  });
+}
+
+configCmd
+  .command('drift')
+  .description('읽기 전용 — 운영 config 와 파생 시험 우주(.elanous-test) config 사본이 다른 키 표 (CFG-STORE1)')
+  .option('--key <key>', '이 키(또는 그 아래)만')
+  .option('--json', 'JSON 출력')
+  .option('--limit <n>', '표시할 키 수 (0=전부 · 기본 50)', '50')
+  .option('--registry <path>', '인스턴스 레지스트리 경로 (기본 ~/.elanous/logs/instances.json)')
+  .option('--scan-root <dir...>', '명시 트리 뿌리 (기본 = config-drift.ts defaultTreeScanRoots)')
+  .option('--no-tree-scan', '트리 뿌리 훑기 끔 — 레지스트리만')
+  .option('--no-registry', '레지스트리 끔 — 명시 트리 뿌리(자리·작업 트리)만')
+  .option('--include-expected', 'sync-test 의 test-safe 변환(비밀 제거·발송 끔)과 _test 메타 키 차이도 드리프트로 센다')
+  .action(async (o: { key?: string; json?: boolean; limit: string; includeExpected?: boolean; registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) => {
+    const { computeDrift, renderDrift } = await import('./cli/config-drift.js');
+    const report = computeDrift(await configDriftDiscover(o), { key: o.key, includeExpected: o.includeExpected });
+    debug.log('config.drift', 'computed', {
+      key: o.key ?? null, rows: report.rows.length, prodStatus: report.prodStatus, ...report.universes,
+    });
+    debug.flush();
+    console.log(o.json ? JSON.stringify(report, null, 2) : renderDrift(report, { limit: Number(o.limit) || 0 }));
+    if (report.prodStatus !== 'ok') process.exit(1);
+  });
+
+configCmd
+  .command('explain <key>')
+  .description('읽기 전용 — 운영 값 ⊕ 출처 층 ⊕ 파생 시험 우주별 값 (CFG-STORE1)')
+  .option('--json', 'JSON 출력')
+  .option('--registry <path>', '인스턴스 레지스트리 경로')
+  .option('--scan-root <dir...>', '명시 트리 뿌리')
+  .option('--no-tree-scan', '트리 뿌리 훑기 끔 — 레지스트리만')
+  .option('--no-registry', '레지스트리 끔 — 명시 트리 뿌리만')
+  .action(async (key: string, o: { json?: boolean; registry?: string | boolean; scanRoot?: string[]; treeScan?: boolean }) => {
+    const { computeExplain, renderExplain } = await import('./cli/config-drift.js');
+    const { buildUserConfig } = await import('./user-config.js');
+    const report = computeExplain(await configDriftDiscover(o), key, {
+      codeDefaults: () => buildUserConfig('/nonexistent/elanous-config-drift/config.json'),
+    });
+    debug.log('config.explain', 'computed', { key, layer: report.prod.layer, ...report.universes });
+    debug.flush();
+    console.log(o.json ? JSON.stringify(report, null, 2) : renderExplain(report));
+    if (report.prod.layer === 'prod-unreadable') process.exit(1);
+  });
+
 // ── config 격리 sync (ISO-1 · 2026-07-13) — 운영→테스트 물질화 동기화 ──
 // 격리 테스트 인스턴스는 운영 config 를 공유하지 않는다(overlay 은퇴 방향).
 configCmd

package/src/maturity/feature-maturity.ts

@@ -74,7 +74,7 @@ export const FEATURE_MATURITY = {
     loops: 'beta', buzz: 'beta', harness: 'stable', self: 'beta', factcheck: 'beta',
     provider: 'stable', 'provider:set': 'beta', 'provider:restore': 'beta',
     'provider:rotate': 'beta', 'provider:use': 'beta', 'status-bar': 'beta',
-    schedule: 'beta', guardian: 'beta', intake: 'beta', logs: 'stable', ad: 'beta', docs: 'beta',
+    schedule: 'beta', guardian: 'beta', intake: 'beta', logs: 'stable', retro: 'beta', ad: 'beta', docs: 'beta',
     decisions: 'beta', directives: 'beta', claims: 'beta', lesson: 'beta', fleet: 'beta', ops: 'stable', outputs: 'beta', publish: 'beta',
     env: 'beta', 'agent-mission': 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
     config: 'stable', tasks: 'stable', brief: 'beta', notify: 'beta', away: 'beta', labels: 'beta', msg: 'beta', ask: 'stable',
@@ -160,7 +160,7 @@ export const FEATURE_MATURITY = {
     ping: 'stable', provider: 'stable', sessions: 'stable', fork: 'stable', resume: 'stable',
     decisions: 'stable', work: 'stable', cancel: 'stable',
     skills: 'beta', skill: 'beta', digest: 'beta', intake: 'beta', ad: 'beta',
-    taste: 'beta', missions: 'beta', attach: 'beta', detach: 'beta', now: 'beta', loops: 'beta', release: 'beta', away: 'beta', project: 'beta', wish: 'beta',
+    taste: 'beta', missions: 'beta', attach: 'beta', detach: 'beta', now: 'beta', loops: 'beta', runs: 'beta', release: 'beta', away: 'beta', project: 'beta', wish: 'beta',
     brain: 'tool', cc: 'tool', cdx: 'tool', gem: 'tool', local: 'tool',
     harness: 'ops',
     // Existing commands outside the CXO four-grade menu list are owner-only.

package/src/nexus/api/graph-kinds.ts

@@ -58,12 +58,18 @@ export async function handleGraphsValidatePost(req: Request, opts: MetaApiOpts):
     return jsonResponse({ error: 'bad_request', reason: 'graph (harness|workflow) and yaml (string) required' }, 400);
   }
   const { graph, yaml } = body as { graph: GraphKind; yaml: string };
+  const { ok, errors, ignoredKeys } = validateGraphYaml(graph, yaml);
+  debug.log('graph.kinds', 'validate', { graph, ok, errors, ignored: ignoredKeys });
+  return jsonResponse({ ok, errors, ignoredKeys }, ok ? 200 : 422);
+}
+
+/** The one validator behind `POST /v1/graphs/validate` and the graph save path. */
+export function validateGraphYaml(graph: GraphKind, yaml: string): { ok: boolean; errors: readonly unknown[]; ignoredKeys: string[]; graphId?: string } {
   const result = graph === 'harness' ? parseGraphTemplateYaml(yaml) : parseWorkflowYaml(yaml);
-  const errors = graph === 'harness' ? (result as ReturnType<typeof parseGraphTemplateYaml>).errors : (result as ReturnType<typeof parseWorkflowYaml>).issues;
+  const errors: readonly unknown[] = graph === 'harness' ? (result as ReturnType<typeof parseGraphTemplateYaml>).errors : (result as ReturnType<typeof parseWorkflowYaml>).issues;
   let input: unknown;
   try { input = parseYaml(yaml); } catch { /* The parser already reports the YAML error. */ }
   const ignoredKeys = ignoredPaths(input, graph === 'harness' ? harnessShape : workflowShape);
-  const ok = errors.length === 0;
-  debug.log('graph.kinds', 'validate', { graph, ok, errors, ignored: ignoredKeys });
-  return jsonResponse({ ok, errors, ignoredKeys }, ok ? 200 : 422);
+  const graphId = graph === 'harness' ? (result as ReturnType<typeof parseGraphTemplateYaml>).template?.graphId : undefined;
+  return { ok: errors.length === 0, errors, ignoredKeys, ...(graphId === undefined ? {} : { graphId }) };
 }

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

@@ -1,15 +1,31 @@
-import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
+import { debug } from '../../debug/log.js';
 import { defaultGraphsDir, loadGraphTemplatesFrom } from '../../self-implement/graph-templates.js';
 import { loadGraphTemplates } from '../../self-implement/graph-yaml.js';
+import { validateGraphYaml } from './graph-kinds.js';
 import { jsonResponse } from './json-response.js';
 
 /** Declared graph ids only. A user string is never joined onto a filesystem path. */
 const GRAPH_ID = /^[a-z0-9-]+$/;
 
+/**
+ * Sidecar names a graph directory loads specially. `recipes.yaml` next to a graph is what
+ * the graph runner executes (`cmd:` recipes), so an HTTP write to `<mine>/recipes.yaml`
+ * would be a remote command path. These ids are never created, saved or reverted, and
+ * these files are never indexed as graphs.
+ */
+export const RESERVED_GRAPH_IDS: ReadonlySet<string> = new Set(['recipes', 'overlay', 'overlays']);
+
+function reserved(id: string): Response | null {
+  if (!RESERVED_GRAPH_IDS.has(id)) return null;
+  debug.log('nexus.graphs', 'rejected-reserved', { id });
+  return jsonResponse({ error: 'reserved-id', id }, 400);
+}
+
 export interface GraphCatalogEntry {
   id: string;
   source: 'core' | 'mine';
@@ -45,6 +61,7 @@ function readDirYaml(dir: string): string[] {
 function indexByDeclaredId(dir: string): Map<string, { file: string; text: string }> {
   const found = new Map<string, { file: string; text: string }>();
   for (const file of readDirYaml(dir)) {
+    if (RESERVED_GRAPH_IDS.has(file.replace(/\.ya?ml$/, ''))) continue;
     let text: string;
     try { text = readFileSync(join(dir, file), 'utf8'); }
     catch { continue; }
@@ -125,6 +142,21 @@ function validateInTemp(text: string, expectedId: string): { ok: true } | { ok:
   }
 }
 
+/** Same validator as POST /v1/graphs/validate. Invalid → 422; declared graph_id ≠ id → 400. Null = ok. */
+function rejectGraphYaml(text: string, id: string, version?: string): Response | null {
+  const checked = validateGraphYaml('harness', text);
+  if (!checked.ok) {
+    debug.log('nexus.graphs', 'rejected-invalid', { id, ...(version ? { version } : {}), issues: checked.errors });
+    return jsonResponse({ error: 'invalid-graph', errors: checked.errors, ignoredKeys: checked.ignoredKeys }, 422);
+  }
+  if (checked.graphId !== id) {
+    const errors = [{ path: `${id}/graph_id`, message: 'graph_id 가 요청 id 와 다르다' }];
+    debug.log('nexus.graphs', 'rejected-invalid', { id, issues: errors });
+    return jsonResponse({ error: 'graph-id-mismatch', errors }, 400);
+  }
+  return null;
+}
+
 /** Core graphs are read from the same YAML loader as the harness, never rewritten by this API. */
 export function handleGraphsGet(pathname: string, dir = defaultGraphsDir(), deps: GraphsApiDeps = {}): Response {
   const coreDir = deps.coreDir ?? dir;
@@ -168,6 +200,8 @@ export async function handleGraphsPut(pathname: string, req: Request, deps: Grap
   if (!match) return jsonResponse({ error: 'not-found' }, 404);
   const id = resolveId(match[1]!);
   if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
   const core = coreCatalog(coreDir);
@@ -178,12 +212,146 @@ export async function handleGraphsPut(pathname: string, req: Request, deps: Grap
   let body: { yaml?: unknown };
   try { body = await req.json() as { yaml?: unknown }; }
   catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
-  if (typeof body.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
-  const checked = validateInTemp(body.yaml, id);
-  if (!checked.ok) return jsonResponse({ error: 'invalid-graph', errors: checked.errors }, 400);
+  if (typeof body?.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
+  const rejected = rejectGraphYaml(body.yaml, id);
+  if (rejected) return rejected;
   const existing = indexByDeclaredId(mineDir).get(id)!;
-  writeFileSync(join(mineDir, existing.file), body.yaml);
-  return jsonResponse({ id, source: 'mine', editable: true, saved: true });
+  // Writes go only to <mine>/<id>.yaml; a hand-placed file under another name is not edited over HTTP.
+  if (existing.file !== `${id}.yaml`) return jsonResponse({ error: 'file-name-mismatch', id, file: existing.file }, 409);
+  const { version, previous } = writeWithVersion(mineDir, id, existing, body.yaml);
+  debug.log('nexus.graphs', 'saved', { id, version, previous });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous });
+}
+
+const VERSION_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z(?:-\d{4})?$/;
+export const GRAPH_VERSION_CAP = 20;
+
+function versionsDir(mineDir: string, id: string): string {
+  return join(mineDir, '.versions', id);
+}
+
+/** Version ids are ISO timestamps (`:`/`.` → `-`), so name order is save order. */
+export function listGraphVersions(mineDir: string, id: string): Array<{ version: string; savedAt: string; bytes: number }> {
+  const dir = versionsDir(mineDir, id);
+  // Only `.yaml` is ever written, read and reverted — a stray `.yml` is not a version.
+  return readDirYaml(dir)
+    .filter((file) => file.endsWith('.yaml'))
+    .map((file) => file.replace(/\.yaml$/, ''))
+    .filter((version) => VERSION_ID.test(version))
+    .sort()
+    .map((version) => {
+      const iso = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/.exec(version);
+      let bytes = 0;
+      try { bytes = statSync(join(dir, `${version}.yaml`)).size; } catch { /* listed above; raced away */ }
+      return { version, savedAt: iso ? `${iso[1]}T${iso[2]}:${iso[3]}:${iso[4]}.${iso[5]}Z` : version, bytes };
+    });
+}
+
+function recordVersion(mineDir: string, id: string, text: string): string {
+  const dir = versionsDir(mineDir, id);
+  mkdirSync(dir, { recursive: true });
+  const base = new Date().toISOString().replace(/[:.]/g, '-');
+  let version = base;
+  for (let n = 1; existsSync(join(dir, `${version}.yaml`)); n += 1) version = `${base}-${String(n).padStart(4, '0')}`;
+  writeFileSync(join(dir, `${version}.yaml`), text);
+  const all = listGraphVersions(mineDir, id);
+  for (const old of all.slice(0, Math.max(0, all.length - GRAPH_VERSION_CAP))) {
+    rmSync(join(dir, `${old.version}.yaml`), { force: true });
+  }
+  return version;
+}
+
+/**
+ * Every saved state is a version. A graph with no history yet (e.g. a fresh clone)
+ * first records its current bytes, so `previous` always points at restorable bytes.
+ */
+function writeWithVersion(mineDir: string, id: string, existing: { file: string; text: string }, text: string): { version: string; previous: string } {
+  const history = listGraphVersions(mineDir, id);
+  const previous = history.at(-1)?.version ?? recordVersion(mineDir, id, existing.text);
+  // Version first, then an atomic replace of the current file: a crash in between leaves
+  // the old current bytes intact (they are `previous`), never bytes that no version holds.
+  const version = recordVersion(mineDir, id, text);
+  const target = join(mineDir, `${id}.yaml`);
+  const temp = join(mineDir, `.${id}.yaml.${process.pid}.tmp`);
+  writeFileSync(temp, text);
+  renameSync(temp, target);
+  return { version, previous };
+}
+
+function mineOwnership(id: string, deps: GraphsApiDeps): { mineDir: string; existing: { file: string; text: string } } | Response {
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
+  const coreDir = deps.coreDir ?? defaultGraphsDir();
+  const mineDir = deps.mineDir ?? mineGraphsDir();
+  const existing = indexByDeclaredId(mineDir).get(id);
+  if (!existing) {
+    const core = coreCatalog(coreDir);
+    if (core.ok && indexByDeclaredId(coreDir).has(id)) return jsonResponse({ error: 'core-read-only', id }, 403);
+    return jsonResponse({ error: 'not-found', id }, 404);
+  }
+  return { mineDir, existing };
+}
+
+/** GET /v1/graphs/<id>/versions — only «mine» graphs have history. */
+export function handleGraphVersionsGet(pathname: string, deps: GraphsApiDeps = {}): Response {
+  const match = /^\/v1\/graphs\/([^/]+)\/versions$/.exec(pathname);
+  if (!match) return jsonResponse({ error: 'not-found' }, 404);
+  const id = resolveId(match[1]!);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  return jsonResponse({ id, versions: listGraphVersions(owned.mineDir, id) });
+}
+
+/** POST /v1/graphs/<id>/revert {version} — restores that version; the restore is itself a new version. */
+export async function handleGraphsRevert(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  const match = /^\/v1\/graphs\/([^/]+)\/revert$/.exec(pathname);
+  if (!match) return jsonResponse({ error: 'not-found' }, 404);
+  const id = resolveId(match[1]!);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const owned = mineOwnership(id, deps);
+  if (owned instanceof Response) return owned;
+  if (owned.existing.file !== `${id}.yaml`) return jsonResponse({ error: 'file-name-mismatch', id, file: owned.existing.file }, 409);
+  let body: { version?: unknown };
+  try { body = await req.json() as { version?: unknown }; }
+  catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  if (typeof body?.version !== 'string' || !VERSION_ID.test(body.version)) {
+    return jsonResponse({ error: 'bad_request', reason: 'version string required' }, 400);
+  }
+  const target = body.version;
+  // Only a listed version id is ever joined onto a path.
+  if (!listGraphVersions(owned.mineDir, id).some((entry) => entry.version === target)) {
+    return jsonResponse({ error: 'version-not-found', id, version: target }, 404);
+  }
+  const text = readFileSync(join(versionsDir(owned.mineDir, id), `${target}.yaml`), 'utf8');
+  const rejected = rejectGraphYaml(text, id, target);
+  if (rejected) return rejected;
+  const { version, previous } = writeWithVersion(owned.mineDir, id, owned.existing, text);
+  debug.log('nexus.graphs', 'reverted', { id, version, previous, restoredFrom: target });
+  return jsonResponse({ id, source: 'mine', editable: true, reverted: true, version, previous, restoredFrom: target });
+}
+
+/** POST /v1/graphs {id, yaml} — a brand-new «mine» graph (blank canvas → save). Records version v1. */
+export async function handleGraphsCreate(req: Request, deps: GraphsApiDeps = {}): Promise<Response> {
+  let body: { id?: unknown; yaml?: unknown };
+  try { body = await req.json() as { id?: unknown; yaml?: unknown }; }
+  catch { return jsonResponse({ error: 'bad_request', reason: 'json body required' }, 400); }
+  const id = typeof body?.id === 'string' ? resolveId(body.id) : null;
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'id must match [a-z0-9-]' }, 400);
+  const reservedId = reserved(id);
+  if (reservedId) return reservedId;
+  if (typeof body.yaml !== 'string') return jsonResponse({ error: 'bad_request', reason: 'yaml string required' }, 400);
+  const coreDir = deps.coreDir ?? defaultGraphsDir();
+  const mineDir = deps.mineDir ?? mineGraphsDir();
+  if (indexByDeclaredId(coreDir).has(id)) return jsonResponse({ error: 'core-read-only', id }, 403);
+  if (indexByDeclaredId(mineDir).has(id) || existsSync(join(mineDir, `${id}.yaml`))) return jsonResponse({ error: 'exists', id }, 409);
+  const rejected = rejectGraphYaml(body.yaml, id);
+  if (rejected) return rejected;
+  mkdirSync(mineDir, { recursive: true });
+  writeFileSync(join(mineDir, `${id}.yaml`), body.yaml, { flag: 'wx' });
+  const version = recordVersion(mineDir, id, body.yaml);
+  debug.log('nexus.graphs', 'saved', { id, version, created: true });
+  return jsonResponse({ id, source: 'mine', editable: true, saved: true, version, previous: null }, 201);
 }
 
 /** Copy core bytes into «my graphs», changing only the declared graph_id. */
@@ -198,6 +366,8 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
   if (typeof body.newId !== 'string' || !GRAPH_ID.test(body.newId) || body.newId === id) {
     return jsonResponse({ error: 'bad_request', reason: 'newId must match [a-z0-9-]' }, 400);
   }
+  const reservedId = reserved(body.newId);
+  if (reservedId) return reservedId;
   const coreDir = deps.coreDir ?? defaultGraphsDir();
   const mineDir = deps.mineDir ?? mineGraphsDir();
   const source = indexByDeclaredId(coreDir).get(id) ?? indexByDeclaredId(mineDir).get(id);
@@ -215,7 +385,9 @@ export async function handleGraphsClone(pathname: string, req: Request, deps: Gr
 }
 
 export async function handleGraphsMutation(pathname: string, req: Request, deps: GraphsApiDeps = {}): Promise<Response | null> {
+  if (req.method === 'POST' && pathname === '/v1/graphs') return handleGraphsCreate(req, deps);
   if (req.method === 'PUT' && /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname)) return handleGraphsPut(pathname, req, deps);
   if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/clone$/.test(pathname)) return handleGraphsClone(pathname, req, deps);
+  if (req.method === 'POST' && /^\/v1\/graphs\/[^/]+\/revert$/.test(pathname)) return handleGraphsRevert(pathname, req, deps);
   return null;
 }

package/src/nexus/api/http-server.ts

@@ -24,6 +24,7 @@ import { createProject, listProjects } from '../../project/project-store.js';
 import { handleOutputsGet, type OutputsDeps } from './outputs-route.js';
 import { buildGridData, type GridDeps } from './grid.js';
 import { DECISIONS_PATH, handleDecisions, type DecisionsRouteDeps } from './decisions-route.js';
+import { OPS_BOARD_PATH, handleOpsBoard, type OpsBoardDeps } from './ops-board-route.js';
 import { CARD_FOLLOWUP_PATH, createCardFollowupJobs, type CardFollowupJobs } from './card-followup-route.js';
 import { SKILL_EXEC_PATH, createSkillExecJobs, type SkillExecJobs } from './skill-exec-route.js';
 import { compareTokenConstTime } from '../../acp/transport/auth.js';
@@ -166,7 +167,8 @@ import { handleHarnessAskPost, handleHarnessAskStatusGet, handleHarnessRunEvents
 import { handleLoopEdgesGet } from './loop-edges.js';
 import { handleFabricPlans, type FabricPlansRouteOpts } from './fabric-plans.js';
 import { dispatchPersonaRoute } from './personas.js';
-import { handleMe } from './operator.js';
+import { handleMe, operatorSignal } from './operator.js';
+import { handleGraphRunRoute } from '../../graph-runner/graph-run-api.js';
 import { handleOpsApi } from './ops-api.js';
 import { handleRoleJudge } from './role-judge.js';
 import { handleAudioStt } from './audio-stt.js';
@@ -363,7 +365,7 @@ import {
 } from './workflows.js';
 import { handleTriggersSnapshot } from './triggers.js';
 import { handleWorkflowTemplatesList } from './workflow-templates.js';
-import { handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
+import { handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
 import { handleGraphKindsGet, handleGraphsValidatePost } from './graph-kinds.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
@@ -484,6 +486,7 @@ export interface NexusHttpServerOpts {
   /** Read-only grid measurement seam; omitted in production for live HQ and Pod pool reads. */
   grid?: GridDeps;
   decisions?: Pick<DecisionsRouteDeps, 'ledger'>;
+  opsBoard?: Pick<OpsBoardDeps, 'openStore'>;
   cardFollowup?: CardFollowupJobs;
   skillExec?: SkillExecJobs;
   execRequests?: ExecRequestRunner;
@@ -938,6 +941,20 @@ export async function routeRequest(
     }
     return pitch.handlePitchApi(req, opts.metaApi);
   }
+  // CGE-RUN — 편집기 «실행»은 운영자 전용이다: 사용자 그래프가 셸 노드를 부를 수 있으므로 같은 출처 무토큰 통과는 받지 않는다
+  // (운영자 프록시 헤더 · owner bearer 일치 · owner 가 발급한 짧은 임시 토큰만 — 명시 토큰은 언제나 필요).
+  if (/^\/v1\/graphs\/[^/]+\/(?:run|runs\/[^/]+)$/.test(pathname)) {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+    const signal = operatorSignal(req, opts.metaApi);
+    const credential = bearerCredential(req, opts.metaApi);
+    if (!signal.operator || (signal.operatorSource !== 'op-proxy' && credential !== 'bearer-match' && credential !== 'temp-token')) {
+      debug.log('graphs.run', 'refused', { path: pathname, source: signal.operatorSource });
+      return jsonResponse({ error: 'forbidden' }, 403);
+    }
+    const routed = handleGraphRunRoute(method, pathname);
+    if (routed) return routed;
+    return jsonResponse({ error: 'method-not-allowed' }, 405);
+  }
 
   // Default-deny for every `/v1/` path that is not on PUBLIC_ROUTES.
   // Reuses checkAuth (same-origin exemption + constant-time bearer).
@@ -1392,6 +1409,21 @@ export async function routeRequest(
     return (opts.cardFollowup ?? defaultCardFollowupJobs()).get(pathname.slice(CARD_FOLLOWUP_PATH.length + 1));
   }
 
+  if (pathname === OPS_BOARD_PATH && (method === 'GET' || method === 'POST')) {
+    const peerAddress = (server as BunServerLike & { requestIP?: (request: Request) => { address: string } | null }).requestIP?.(req)?.address;
+    const host = req.headers.get('host') ?? new URL(req.url).host;
+    const tailnetPeer = peerAddress !== undefined && (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(peerAddress)
+      || /^fd7a:115c:a1e0:/i.test(peerAddress));
+    const localPeer = peerAddress === '127.0.0.1' || peerAddress === '::1';
+    const tailnetHost = /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3}(?::\d+)?$/.test(host)
+      || /^\[fd7a:115c:a1e0:[0-9a-f:]+\](?::\d+)?$/i.test(host) || /^[a-z0-9-]+(?:\.[a-z0-9-]+)*\.ts\.net(?::\d+)?$/i.test(host);
+    const localHost = /^(?:localhost|127\.0\.0\.1)(?::\d+)?$/.test(host) || /^\[::1\](?::\d+)?$/.test(host);
+    if ((!tailnetPeer && !localPeer) || (!tailnetHost && !localHost)) return jsonResponse({ error: 'forbidden' }, 403);
+    return handleOpsBoard(req, {
+      authorize: request => !!opts.metaApi && opts.metaApi.noAuth !== true && checkAuth(request, opts.metaApi),
+      ...opts.opsBoard,
+    });
+  }
   if (method === 'GET' && pathname === DECISIONS_PATH) {
     return handleDecisions(req, {
       authorize: request => !!opts.metaApi && checkAuth(request, opts.metaApi),
@@ -1471,7 +1503,7 @@ export async function routeRequest(
       if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
       return handlePluginsRemove(req, pluginRemove[1]!, opts.metaApi, opts.pluginStateRoot);
     }
-    if ((method === 'PUT' || method === 'POST') && pathname.startsWith('/v1/graphs/')) {
+    if ((method === 'PUT' || method === 'POST') && (pathname.startsWith('/v1/graphs/') || pathname === '/v1/graphs')) {
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
       if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
       const mutated = await handleGraphsMutation(pathname, req);
@@ -2785,6 +2817,9 @@ export async function routeRequest(
   if (method === 'GET' && (pathname === '/v1/graphs' || /^\/v1\/graphs\/[^/]+$/.test(pathname) || /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname))) {
     return handleGraphsGet(pathname);
   }
+  if (method === 'GET' && /^\/v1\/graphs\/[^/]+\/versions$/.test(pathname)) {
+    return handleGraphVersionsGet(pathname);
+  }
   // Archon-port T2.3 (2026-05-08) — workflow GET surface.
   // (POST /validate · POST /:name/run · PUT/DELETE /:name landed
   // inside the mutation block above.)