elanous 0.2.9 → 0.2.11

package/src/ops-now/ops-now-refresh.ts

@@ -0,0 +1,100 @@
+import { debug } from '../debug/log.js';
+import { listMemories, makeMemoryJudge, memoryRoot, saveMemory } from '../memory.js';
+
+export interface OpsNowComment { body: string; createdAt: string; url: string }
+export interface OpsNowDeps {
+  listComments?: (sinceIso: string) => Promise<OpsNowComment[] | null>;
+  summarize?: (prompt: string) => Promise<string>;
+  now?: () => Date;
+  root?: string;
+  dryRun?: boolean;
+}
+export interface OpsNowResult {
+  outcome: 'updated' | 'unchanged' | 'no-notices' | 'summarize-failed' | 'channel-unreadable';
+  notices: number;
+  memoryId?: string;
+  /** Only populated for dry-run, so callers can inspect the proposed write. */
+  body?: string;
+}
+
+const HEADER = /^갱신: [^\n]* · 출처 글 \d+개\n/;
+const CITED_ITEM = /^- .+ \(출처: (https?:\/\/[^\s)]+)\)$/;
+
+function citedItems(body: string): string[] | null {
+  const lines = body.trim().split('\n').filter((line) => line.trim());
+  if (!lines.length) return null;
+  const sources: string[] = [];
+  for (const line of lines) {
+    const match = CITED_ITEM.exec(line);
+    if (!match || line.match(/\(출처:/g)?.length !== 1) return null;
+    sources.push(match[1]!);
+  }
+  return sources;
+}
+
+function channelIssue(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === 'github.com' && /^\/[^/]+\/[^/]+\/(?:issues|pull)\/\d+$/.test(parsed.pathname) &&
+      /^#issuecomment-\d+$/.test(parsed.hash) ? `${parsed.origin}${parsed.pathname}` : null;
+  } catch { return null; }
+}
+
+export async function refreshOpsNow(deps: OpsNowDeps = {}): Promise<OpsNowResult> {
+  const now = (deps.now ?? (() => new Date()))();
+  const root = deps.root ?? memoryRoot();
+  const finish = (outcome: OpsNowResult['outcome'], notices: number, chars: number, memoryId?: string, body?: string): OpsNowResult => {
+    debug.log('ops-now.refresh', outcome, { notices, chars });
+    return { outcome, notices, ...(memoryId ? { memoryId } : {}), ...(body !== undefined ? { body } : {}) };
+  };
+  let comments: OpsNowComment[] | null;
+  try {
+    const listComments = deps.listComments ?? (await import('../nexus/api/ops-seats-sources.js')).channelCommentsSince;
+    comments = await listComments(new Date(now.getTime() - 86_400_000).toISOString());
+  } catch {
+    comments = null;
+  }
+  if (!comments) return finish('channel-unreadable', 0, 0);
+  const notices = comments.filter((c) => c.body.includes('📌안내') &&
+    Number.isFinite(Date.parse(c.createdAt)) && Date.parse(c.createdAt) >= now.getTime() - 86_400_000 && Date.parse(c.createdAt) <= now.getTime())
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  if (!notices.length) return finish('no-notices', 0, 0);
+
+  const existing = listMemories({}, root).find((m) => m.name === 'ops-now');
+  const oldBody = existing?.body.trim() ?? '';
+  const issue = channelIssue(notices[0]!.url);
+  const oldSources = (issue ? oldBody.replace(HEADER, '').split('\n').map((line) => CITED_ITEM.exec(line)?.[1]) : [])
+    .filter((url): url is string => !!url && channelIssue(url) === issue);
+  const allowedSources = new Set([...notices.map((c) => c.url), ...oldSources]);
+  const prompt = [
+    '너는 봇의 ops-now 고정 기억을 diff 갱신한다. 기존 본문과 채널 📌안내 글을 대조해 지금 유효한 안내만 한국어로 반환한다.',
+    '새 글의 정정이 앞 글과 충돌하면 새 글이 이긴다. 이미 유효한 기존 안내는 유지하되 낡거나 정정된 안내는 제거한다.',
+    '각 항목은 한 줄의 "- 안내 (출처: <코멘트 URL>)" 꼴로 쓰고 다른 문장은 출력하지 않는다. 출처는 아래 새 글 URL 또는 기존 본문의 검증 가능한 채널 URL만 사용한다. 출처가 확인되지 않는 항목은 쓰지 않는다.',
+    '비밀 값·토큰·개인 메모·계정 이름은 옮기지 않는다.',
+    '본문만 출력한다. 갱신 시각 헤더는 출력하지 않는다. 2,000자 이하.',
+    '## 기존 ops-now 본문', oldBody || '(없음)', '## 📌안내 (오래된 글 → 새로운 글)',
+    ...notices.map((c) => {
+      const seat = /^\s*\*\*\[(OP|MK|TC|UX)\]\*/.exec(c.body)?.[1] ?? '미상';
+      return `시각: ${c.createdAt} · 자리: ${seat} · URL: ${c.url}\n${c.body.slice(0, 1500)}`;
+    }),
+  ].join('\n\n');
+  let summary: string;
+  try {
+    summary = (await (deps.summarize ?? makeMemoryJudge())(prompt)).trim().replace(HEADER, '').trim();
+    const sources = citedItems(summary);
+    if (!sources || sources.some((url) => !allowedSources.has(url)) ||
+      `갱신: ${now.toISOString()} · 출처 글 ${notices.length}개\n${summary}`.length > 2000) throw new Error('invalid summary');
+  } catch {
+    return finish('summarize-failed', notices.length, 0, existing?.id);
+  }
+  if (summary === oldBody.replace(HEADER, '').trim() && existing?.pinned && existing.staleAfterMinutes === 120) {
+    return finish('unchanged', notices.length, summary.length, existing.id, deps.dryRun ? existing.body.trimStart() : undefined);
+  }
+  const body = `갱신: ${now.toISOString()} · 출처 글 ${notices.length}개\n${summary}`;
+  if (deps.dryRun) return finish('updated', notices.length, body.length, existing?.id, body);
+  const saved = saveMemory({
+    type: 'project', name: 'ops-now', description: existing?.description ?? '지금 운영 상태 — 채널 📌안내 갱신',
+    body, id: existing?.id, priority: existing?.priority, pinned: true, staleAfterMinutes: 120,
+  }, root);
+  return finish('updated', notices.length, body.length, saved.id);
+}

package/src/org/seat-budget.ts

@@ -0,0 +1,48 @@
+import { getUserConfig, type UserConfig } from '../user-config.js';
+import type { SeatEntry } from '../seat-loop/seat-loop.js';
+
+export const DEFAULT_DAILY_GOALS = 6;
+export const DEFAULT_CONCURRENT_PODS = 2;
+
+export type SeatBudgetResult = { allowed: true } | { allowed: false; reason: string };
+export type RunningSeatPod = { seat: string; substrate?: string; status?: string };
+export type SeatBudgetInput = {
+  seat: string;
+  now: Date;
+  ledger: readonly SeatEntry[];
+  running: readonly RunningSeatPod[];
+  config?: Pick<UserConfig, 'org'>;
+};
+
+function limit(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+
+function day(date: Date): string {
+  return new Intl.DateTimeFormat('en-CA', { timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit' }).format(date);
+}
+
+/** A read-only seat quota judgment; the caller owns the launch and ledger write. */
+export function checkSeatBudget({ seat, now, ledger, running, config }: SeatBudgetInput): SeatBudgetResult {
+  const override = (config ?? getUserConfig()).org?.budget?.[seat];
+  const dailyGoals = limit(override?.dailyGoals, DEFAULT_DAILY_GOALS);
+  const concurrentPods = limit(override?.concurrentPods, DEFAULT_CONCURRENT_PODS);
+  const today = day(now);
+  const launchedToday = ledger.filter((entry) => entry.seat === seat && entry.status === 'launched'
+    && Number.isFinite(Date.parse(entry.ts ?? entry.at))
+    && day(new Date(entry.ts ?? entry.at)) === today).length;
+  if (launchedToday >= dailyGoals) {
+    return { allowed: false, reason: `${seat} daily goals budget reached (${launchedToday}/${dailyGoals})` };
+  }
+  const active = running.filter((run) => run.seat === seat && (run.status === undefined || run.status === 'running' || run.status === 'unknown'));
+  // Confirmed = a Pod known to be running; an unknown substrate OR unknown liveness only counts as «cannot verify».
+  const pods = active.filter((run) => run.substrate === 'pod' && run.status !== 'unknown').length;
+  if (pods >= concurrentPods) {
+    return { allowed: false, reason: `${seat} concurrent Pods budget reached (${pods}/${concurrentPods})` };
+  }
+  const unknown = active.filter((run) => run.substrate === undefined || run.status === 'unknown').length;
+  if (pods + unknown >= concurrentPods) {
+    return { allowed: false, reason: `${seat} concurrent Pods budget cannot be verified (${pods} confirmed, ${unknown} unknown; limit ${concurrentPods})` };
+  }
+  return { allowed: true };
+}

package/src/org/stall-escalation.ts

@@ -0,0 +1,63 @@
+import type { Checklist, ChecklistItem } from '../release-loop/checklist.js';
+import { parseOwner } from '../release-loop/checklist.js';
+import type { SeatLoopConfig } from '../user-config.js';
+
+export interface StallEscalation {
+  item: ChecklistItem;
+  from: string;
+  to: string;
+  stalledMin: number;
+  /** Stable start of this uninterrupted stall interval (independent of the observation clock). */
+  startedAt: string;
+  reason: 'red' | 'blocked';
+}
+
+/** A missing parent is intentional: OP has no automatic escalation destination. */
+export const DEFAULT_STALL_PARENTS: Readonly<Record<string, string>> = { MK: 'OP', TC: 'OP', UX: 'OP' };
+export const DEFAULT_RED_MINUTES = 30;
+export const DEFAULT_BLOCKED_MINUTES = 60;
+
+function stallReason(item: ChecklistItem): StallEscalation['reason'] | null {
+  if (item.status === 'red') return 'red';
+  return item.status === 'yellow' && item.disposition === 'block' ? 'blocked' : null;
+}
+
+/** Find the beginning of the current uninterrupted red/blocked interval, not the most recent evidence edit. */
+function stallStart(item: ChecklistItem, history: Checklist['history'], reason: StallEscalation['reason']): number {
+  const changes = history.filter((entry) => entry.id === item.id && (entry.field === 'status' || entry.field === 'disposition'))
+    .filter((entry) => Number.isFinite(Date.parse(entry.at)))
+    .sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+  let status = item.status;
+  let disposition = item.disposition;
+  for (const entry of changes) {
+    const current = status === 'red' ? 'red' : status === 'yellow' && disposition === 'block' ? 'blocked' : null;
+    if (entry.field === 'status') status = entry.from as ChecklistItem['status'];
+    else disposition = entry.from as ChecklistItem['disposition'];
+    const previous = status === 'red' ? 'red' : status === 'yellow' && disposition === 'block' ? 'blocked' : null;
+    if (current === reason && previous !== reason) return Date.parse(entry.at);
+  }
+  return Date.parse(item.updatedAt);
+}
+
+/** Pure checklist snapshot judgment. Age is measured in minutes against the injected clock. */
+export function findStalls(checklist: Checklist, config: SeatLoopConfig = { mode: 'off' }, now: Date = new Date()): StallEscalation[] {
+  const nowMs = now.getTime();
+  const parents = { ...DEFAULT_STALL_PARENTS, ...config.stall?.parents };
+  const results: StallEscalation[] = [];
+  for (const item of checklist.items) {
+    const reason = stallReason(item);
+    if (!reason || !item.owner) continue;
+    let from: string;
+    try { from = parseOwner(item.owner).seat; } catch { continue; }
+    const to = parents[from];
+    if (!to || to === from) continue;
+    const start = stallStart(item, checklist.history, reason);
+    if (!Number.isFinite(start) || start > nowMs) continue;
+    const stalledMin = (nowMs - start) / 60_000;
+    const threshold = reason === 'red' ? config.stall?.redMinutes ?? DEFAULT_RED_MINUTES
+      : config.stall?.blockedMinutes ?? DEFAULT_BLOCKED_MINUTES;
+    if (stalledMin < threshold) continue;
+    results.push({ item, from, to, stalledMin, startedAt: new Date(start).toISOString(), reason });
+  }
+  return results;
+}

package/src/outputs/ledger.ts

@@ -0,0 +1,120 @@
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync } from 'node:fs';
+import { dlopen, FFIType } from 'bun:ffi';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { OUTPUT_KINDS, type OutputKind } from '../exec-requests/default-outputs.js';
+
+export interface OutputEntry {
+  kind: OutputKind | 'file';
+  title: string;
+  path?: string;
+  url?: string;
+  source: 'exec' | 'field-reel' | 'field-feed';
+  sourceId: string;
+  seat?: string;
+  at: string;
+}
+
+type NewOutput = Omit<OutputEntry, 'at'> & { at?: string };
+const validKinds = new Set<unknown>([...Object.keys(OUTPUT_KINDS), 'file']);
+
+function kstMonth(at: Date): string {
+  return new Date(at.getTime() + 9 * 60 * 60 * 1000).toISOString().slice(0, 7);
+}
+
+function ledgerPath(root: string, month: string): string { return join(root, 'outputs', `outputs-${month}.jsonl`); }
+
+function readEntries(file: string): { entries: OutputEntry[]; newline: boolean } {
+  let text: string;
+  try { text = readFileSync(file, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { entries: [], newline: true };
+    throw error;
+  }
+  const entries: OutputEntry[] = [];
+  text.split('\n').forEach((line, index) => {
+    if (!line.trim()) return;
+    try {
+      const entry: unknown = JSON.parse(line);
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)
+        || !('source' in entry) || (entry.source !== 'exec' && entry.source !== 'field-reel' && entry.source !== 'field-feed')
+        || !('sourceId' in entry) || typeof entry.sourceId !== 'string' || !entry.sourceId
+        || !('kind' in entry) || !validKinds.has(entry.kind)
+        || !('title' in entry) || typeof entry.title !== 'string' || !entry.title
+        || !('at' in entry) || typeof entry.at !== 'string' || !entry.at
+        || (!('path' in entry) || typeof entry.path !== 'string' || !entry.path)
+          && (!('url' in entry) || typeof entry.url !== 'string' || !entry.url)
+        || ('path' in entry && entry.path !== undefined && typeof entry.path !== 'string')
+        || ('url' in entry && entry.url !== undefined && typeof entry.url !== 'string')
+        || ('seat' in entry && entry.seat !== undefined && typeof entry.seat !== 'string')) throw new Error('invalid output entry');
+      entries.push(entry as OutputEntry);
+    } catch (error) {
+      debug.log('outputs.ledger', 'invalid-line', { line: index + 1, error: String(error) });
+    }
+  });
+  return { entries, newline: !text || text.endsWith('\n') };
+}
+
+// Keep the lock inode in place: unlinking it lets a second writer lock a new inode while the first still holds the old one.
+const flock = dlopen(process.platform === 'darwin' ? 'libSystem.B.dylib' : 'libc.so.6',
+  { flock: { args: [FFIType.int, FFIType.int], returns: FFIType.int } }).symbols.flock;
+function acquireLock(file: string): () => void {
+  const fd = openSync(`${file}.lock`, 'a+', 0o600);
+  const deadline = Date.now() + 5_000;
+  try {
+    while (flock(fd, 2 | 4) !== 0) {
+      if (Date.now() >= deadline) throw new Error('outputs ledger lock timed out');
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  } catch (error) { closeSync(fd); throw error; }
+  return () => { try { flock(fd, 8); } finally { closeSync(fd); } };
+}
+
+/** The optional root keeps writers with an explicitly selected instance in the same universe. */
+export function recordOutput(output: NewOutput, root?: string): void {
+  try {
+    const instanceRoot = root ?? effectiveInstanceRoot();
+    const file = ledgerPath(instanceRoot, kstMonth(new Date()));
+    mkdirSync(join(instanceRoot, 'outputs'), { recursive: true, mode: 0o700 });
+    const release = acquireLock(file);
+    try {
+      const { entries, newline } = readEntries(file);
+      if (entries.some(entry => entry.source === output.source && entry.sourceId === output.sourceId
+        && (entry.path ?? entry.url) === (output.path ?? output.url))) return;
+      appendFileSync(file, `${newline ? '' : '\n'}${JSON.stringify({ ...output, at: output.at ?? new Date().toISOString() })}\n`, { mode: 0o600 });
+      debug.log('outputs.ledger', 'recorded', { source: output.source, kind: output.kind });
+    } finally { release(); }
+  } catch (error) {
+    debug.log('outputs.ledger', 'write-failed', { source: output.source, kind: output.kind, error: String(error) });
+  }
+}
+
+export function listOutputs({ since, source, limit }: { since?: string; source?: OutputEntry['source']; limit?: number } = {}, root = effectiveInstanceRoot()): OutputEntry[] {
+  let months = 0;
+  let rows = 0;
+  const entries: OutputEntry[] = [];
+  const take = (file: string) => {
+    try {
+      const read = readEntries(file).entries;
+      rows += read.length;
+      for (const entry of read) {
+        if ((!since || entry.at >= since) && (!source || entry.source === source)) entries.push(entry);
+      }
+    } catch { /* A damaged month does not hide the other months. */ }
+  };
+  try {
+    const dir = join(root, 'outputs');
+    const files = readdirSync(dir).filter(name => /^outputs-\d{4}-(0[1-9]|1[0-2])\.jsonl$/.test(name)).sort().reverse();
+    // Month names reflect write time, not entry.at; an older file may hold the newest entry.
+    for (const name of files) {
+      take(join(dir, name));
+      months++;
+    }
+    // The unrotated ledger has no month boundary; its rows can be newer than any monthly row.
+    take(join(dir, 'outputs.jsonl'));
+  } catch { /* Missing outputs directory. */ }
+  entries.sort((a, b) => b.at.localeCompare(a.at));
+  debug.log('outputs.ledger', 'rotated-read', { months, rows });
+  return entries.slice(0, limit === undefined ? undefined : Math.max(0, limit));
+}

package/src/persona/persona-todo.ts

@@ -0,0 +1,79 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface PersonaTodo {
+  id: string;
+  title: string;
+  status: 'open' | 'done';
+  createdAt: string;
+}
+
+export interface PersonaTodoReadResult {
+  todos: PersonaTodo[];
+  errors: { line: number; message: string }[];
+}
+
+/** One JSONL file per persona. Reject path components in the id. */
+export function personaTodoPath(dir: string, personaId: string): string {
+  if (!personaId || personaId === '.' || personaId === '..' || /[/\\]/.test(personaId)) {
+    throw new Error('Invalid persona id');
+  }
+  return join(dir, `${personaId}.todo.jsonl`);
+}
+
+function isPersonaTodo(value: unknown): value is PersonaTodo {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const item = value as Record<string, unknown>;
+  return typeof item.id === 'string' && item.id.length > 0
+    && typeof item.title === 'string' && item.title.length > 0
+    && (item.status === 'open' || item.status === 'done')
+    && typeof item.createdAt === 'string'
+    && Number.isFinite(Date.parse(item.createdAt));
+}
+
+/** Missing files are empty; malformed lines are skipped and returned for observation. */
+export function readPersonaTodos(dir: string, personaId: string): PersonaTodoReadResult {
+  const path = personaTodoPath(dir, personaId);
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { todos: [], errors: [] };
+    throw error;
+  }
+
+  const todos: PersonaTodo[] = [];
+  const errors: PersonaTodoReadResult['errors'] = [];
+  for (const [index, line] of text.split('\n').entries()) {
+    if (!line.trim()) continue;
+    try {
+      const item: unknown = JSON.parse(line);
+      if (!isPersonaTodo(item)) throw new Error('Invalid todo record');
+      todos.push(item);
+    } catch (error) {
+      errors.push({ line: index + 1, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { todos, errors };
+}
+
+/** Replace a persona's JSONL file with one valid record per line. */
+export function writePersonaTodos(dir: string, personaId: string, todos: readonly PersonaTodo[]): void {
+  const path = personaTodoPath(dir, personaId);
+  for (const todo of todos) {
+    if (!isPersonaTodo(todo)) throw new Error('Invalid todo record');
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, todos.map(todo => JSON.stringify(todo)).join('\n') + (todos.length ? '\n' : ''), 'utf8');
+}
+
+/** Earliest created open item; original order breaks equal-timestamp ties. */
+export function nextPersonaTodo(todos: readonly PersonaTodo[]): PersonaTodo | null {
+  let oldest: PersonaTodo | null = null;
+  for (const todo of todos) {
+    if (todo.status === 'open' && (!oldest || Date.parse(todo.createdAt) < Date.parse(oldest.createdAt))) {
+      oldest = todo;
+    }
+  }
+  return oldest;
+}

package/src/persona/presets.ts

@@ -1,10 +1,12 @@
 // PS1 — 페르소나 프리셋(MK 문면 · persona-presets/<id>.yaml)을 «내 페르소나»로 만든다.
 // 용어: «페르소나»(대표 10-01) — 사용자가 고르고 꾸미는 AI 동료. ⚠️ `SessionSurfaceId`(이름만 Surface 인 캐릭터 축) ·
-// `modelTier.persona`(모델 등급 축)와는 «다른 것»이다 — 여기서 만드는 것은 기존 페르소나 저장소(`resolveStatePersonaDir()`,
+// `modelTier.profile`(모델 등급 프로필 축)와는 «다른 것»이다 — 여기서 만드는 것은 기존 페르소나 저장소(`resolveStatePersonaDir()`,
 // Discord·PWA 가 이미 읽는 `<id>.yaml`)의 한 파일이다. 프리셋 원본은 고치지 않는다.
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse, stringify } from 'yaml';
+import { resolveRepositoryPersonaDir, resolveStatePersonaDir } from './global-registry.js';
+import { parsePersonaYaml } from './loader.js';
 
 export interface PersonaPreset {
   personaId: string;
@@ -91,6 +93,118 @@ export function presetToProfileYaml(p: PersonaPreset, common: PresetCommon, opts
   return `# 프리셋 «${p.personaId}» 에서 만든 페르소나 — elanous persona add (원본: persona-presets/${p.personaId}.yaml)\n${stringify(profile, { lineWidth: 0 })}`;
 }
 
+export interface PersonaWriteOptions { dir?: string; dryRun?: boolean }
+export interface PersonaWriteResult { personaId: string; displayName: string; path: string; yaml: string; dryRun: boolean }
+
+// Only fields in the runtime persona schema may be edited; provenance (`preset`) is retained, not editable.
+const PROFILE_KEYS = new Set([
+  'personaId', 'displayName', 'description', 'systemPrompt', 'actionHosts', 'offsiteNavigation',
+  'brand', 'models', 'mentionPatterns', 'avatarUrl', 'brandColor', 'browserPort', 'residence', 'capabilities',
+]);
+const NESTED_KEYS: Record<string, readonly string[]> = {
+  models: ['primary', 'fallback', 'providers'], 'models.providers': ['ollama', 'openai'],
+  'models.providers.ollama': ['model'], 'models.providers.openai': ['model'],
+  capabilities: ['core', 'extended', 'evidence'],
+};
+
+function mapping(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertSchemaKeys(value: Record<string, unknown>, parent = ''): void {
+  const allowed: ReadonlySet<string> = parent ? new Set(NESTED_KEYS[parent] ?? []) : PROFILE_KEYS;
+  for (const [key, child] of Object.entries(value)) {
+    if (!allowed.has(key)) {
+      throw new Error(`unknown persona schema key: ${parent ? `${parent}.` : ''}${key}`);
+    }
+    const path = parent ? `${parent}.${key}` : key;
+    if (NESTED_KEYS[path] && mapping(child)) assertSchemaKeys(child, path);
+  }
+}
+
+function storedProfiles(dir: string): Array<{ path: string; data: Record<string, unknown> }> {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((file) => file.endsWith('.yaml') && !file.startsWith('_')).map((file) => {
+    const path = join(dir, file);
+    const text = readFileSync(path, 'utf8');
+    const checked = parsePersonaYaml(text, path);
+    if (!checked.ok) throw new Error(`invalid stored persona ${path}: ${checked.error.message}`);
+    const data: unknown = parse(text);
+    if (!mapping(data)) throw new Error(`invalid stored persona ${path}`);
+    return { path, data };
+  });
+}
+
+function normalizedName(name: string): string { return name.trim().toLocaleLowerCase(); }
+function assertUnusedName(name: string, dir: string, except?: string): void {
+  if (!name.trim()) throw new Error('persona name is required');
+  const all = [...storedProfiles(dir), ...(dir === resolveRepositoryPersonaDir() ? [] : storedProfiles(resolveRepositoryPersonaDir()))];
+  if (all.some(({ path, data }) => path !== except &&
+    (normalizedName(String(data.displayName)) === normalizedName(name) || normalizedName(String(data.personaId)) === normalizedName(name)))) {
+    throw new Error(`persona name already exists: ${name}`);
+  }
+}
+
+function checkedYaml(data: Record<string, unknown>, path: string): { yaml: string; personaId: string; displayName: string } {
+  const yaml = stringify(data, { lineWidth: 0 });
+  const check = parsePersonaYaml(yaml, path);
+  if (!check.ok) throw new Error(`invalid persona: ${check.error.message}`);
+  return { yaml, personaId: check.profile.personaId, displayName: check.profile.displayName };
+}
+
+/** Write beside the destination, then atomically replace it (or install a new file without overwriting). */
+function atomicPersonaWrite(path: string, yaml: string, create: boolean): void {
+  const temp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, yaml, { flag: 'wx' });
+    if (create) linkSync(temp, path); // atomic, exclusive: concurrent creations cannot replace a persona
+    else renameSync(temp, path);
+  } finally {
+    if (existsSync(temp)) unlinkSync(temp);
+  }
+}
+
+/** Edit a stored persona by exact id or display name; dry-run validates but never creates a directory or file. */
+export function editPersona(name: string, edits: Record<string, unknown>, opts: PersonaWriteOptions = {}): PersonaWriteResult {
+  const dir = opts.dir ?? resolveStatePersonaDir();
+  if (!name.trim()) throw new Error('persona name is required');
+  if (!mapping(edits)) throw new Error('persona edits must be a mapping');
+  assertSchemaKeys(edits);
+  const matches = storedProfiles(dir).filter(({ data }) =>
+    normalizedName(String(data.personaId)) === normalizedName(name) || normalizedName(String(data.displayName)) === normalizedName(name));
+  if (matches.length !== 1) throw new Error(matches.length ? `ambiguous persona name: ${name}` : `persona not found: ${name}`);
+  const { path, data } = matches[0]!;
+  if (edits.personaId !== undefined && edits.personaId !== data.personaId) throw new Error('personaId cannot be changed');
+  const updated = { ...data, ...edits };
+  const result = checkedYaml(updated, path);
+  assertUnusedName(result.displayName, dir, path);
+  if (!opts.dryRun) atomicPersonaWrite(path, result.yaml, false);
+  return { ...result, path, dryRun: Boolean(opts.dryRun) };
+}
+
+/** Clone a shipped preset into the state persona store under a new, unique display name. */
+export function clonePreset(preset: PersonaPreset | string, name: string, opts: PersonaWriteOptions = {}): PersonaWriteResult {
+  const source = typeof preset === 'string' ? findPreset(loadPresets(), preset) : preset;
+  if (!source) throw new Error(`preset not found: ${preset}`);
+  const dir = opts.dir ?? resolveStatePersonaDir();
+  assertUnusedName(name, dir);
+  const taken = new Set([...storedProfiles(dir), ...storedProfiles(resolveRepositoryPersonaDir())]
+    .map(({ data }) => String(data.personaId)));
+  const personaId = choosePersonaId(source, name, taken);
+  const path = join(dir, `${personaId}.yaml`);
+  if (existsSync(path)) throw new Error(`persona already exists: ${personaId}`);
+  const generated = presetToProfileYaml(source, loadPresetIndex().common, { personaId, name });
+  const raw: unknown = parse(generated);
+  if (!mapping(raw)) throw new Error('invalid generated persona');
+  const result = checkedYaml(raw, path);
+  assertUnusedName(result.displayName, dir);
+  if (!opts.dryRun) {
+    mkdirSync(dir, { recursive: true });
+    atomicPersonaWrite(path, generated, true);
+  }
+  return { ...result, yaml: generated, path, dryRun: Boolean(opts.dryRun) };
+}
+
 /** Short block for `persona show` and `persona list`. */
 export function describePreset(p: PersonaPreset): string[] {
   return [