@goodea/olimpyx 0.1.0

package/src/init-apply.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { OlimpyxClient } from './client.js';
+import { LocalState } from './state.js';
+import { CHARACTERS, characterById, publicProfile, writeCatalog } from './characters.js';
+import { configPath, ownerHome, readVault, vaultExists, writeVault } from './vault.js';
+import { installStarterSkill, loadPlaybookSource, toGlobalPlaybook } from './skill-install.js';
+
+export const DEFAULT_SERVER = 'https://olimpyx.mrciphersmith.com';
+
+export function isTransientNetworkError(error) {
+  if (!error) return false;
+  if (error instanceof TypeError && /fetch failed/i.test(error.message)) return true;
+  const code = error.code || error.cause?.code;
+  return Boolean(code && ['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET', 'ECONNREFUSED', 'EAI_AGAIN'].includes(code));
+}
+
+export function friendlyInitError(error, serverUrl = DEFAULT_SERVER) {
+  if (error?.status === 409) return 'Этот email уже зарегистрирован. Выберите вход.';
+  if (error?.status === 401) return 'Неверный email или пароль.';
+  if (error?.status === 422) return 'Проверьте поля: пароль не короче 12 символов, корректный email, имя не пустое.';
+  if (error?.status === 429) return 'Слишком много попыток. Подождите немного и повторите.';
+  if (isTransientNetworkError(error) || error instanceof TypeError) {
+    return `Не удалось связаться с ${serverUrl}. Проверьте сеть и адрес сервера.`;
+  }
+  return error?.message || 'Неизвестная ошибка';
+}
+
+export function agentHomeFor(id, plan, env = process.env) {
+  const root = plan.skillScope === 'local' ? join(plan.projectPath, '.olimpyx') : ownerHome(env);
+  return join(root, 'agents', id);
+}
+
+export function summarizePlan(plan) {
+  const characters = (plan.characterIds || []).map((id) => characterById(id)?.name || id);
+  const skillWhere = plan.skillScope === 'global'
+    ? 'глобально (~/.claude и ~/.agents)'
+    : `в проекте ${plan.projectPath}`;
+  return [
+    `Сервер: ${plan.serverUrl}`,
+    `Аккаунт: ${plan.mode === 'register' ? 'новая регистрация' : 'вход'} · ${plan.email}`,
+    plan.displayName ? `Имя: ${plan.displayName}` : null,
+    `Скилл: ${skillWhere}`,
+    `Хосты: ${(plan.hosts || []).join(', ') || '—'}`,
+    `Агенты: ${characters.length ? characters.join(', ') : 'пока никого'}`
+  ].filter(Boolean).join('\n');
+}
+
+async function authenticate(plan, client) {
+  if (plan.mode === 'register') {
+    return client.request('POST', '/v1/owners/register', {
+      email: plan.email,
+      password: plan.password,
+      display_name: plan.displayName
+    });
+  }
+  return client.request('POST', '/v1/owners/login', {
+    email: plan.email,
+    password: plan.password
+  });
+}
+
+async function enrollOne(plan, ownerClient, character, env) {
+  const profile = publicProfile(character);
+  const enrollment = await ownerClient.request('POST', '/v1/owners/me/enrollment-tokens', { label: character.id });
+  const result = await ownerClient.request('POST', '/v1/agents/enroll', {
+    enrollment_token: enrollment.data.enrollment_token,
+    installation_id: crypto.randomUUID(),
+    profile
+  }, { token: null });
+  const home = agentHomeFor(character.id, plan, env);
+  const state = new LocalState(home);
+  await state.saveCredential(result.data.agent_token);
+  await state.saveConfig({
+    serverUrl: plan.serverUrl,
+    agentId: result.data.agent.agent_id,
+    profileRevision: result.data.agent.profile_revision,
+    characterId: character.id,
+    ownerId: plan.ownerId ?? null
+  });
+  await state.savePersona(profile, 'init catalog');
+  return {
+    id: character.id,
+    agent_id: result.data.agent.agent_id,
+    credential: result.data.agent_token,
+    home
+  };
+}
+
+export async function applyInit(plan, { env = process.env, fetchImpl = fetch, onProgress = () => {} } = {}) {
+  const home = ownerHome(env);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const client = new OlimpyxClient({ serverUrl: plan.serverUrl, token: null, fetchImpl });
+
+  onProgress('account');
+  let auth;
+  try {
+    auth = await authenticate(plan, client);
+  } catch (error) {
+    const wrapped = new Error(friendlyInitError(error, plan.serverUrl));
+    wrapped.cause = error;
+    throw wrapped;
+  }
+  const owner = auth.data.owner;
+  const accessToken = auth.data.access_token;
+  plan.ownerId = owner.owner_id;
+  const ownerClient = new OlimpyxClient({ serverUrl: plan.serverUrl, token: accessToken, fetchImpl });
+
+  onProgress('vault');
+  const enrolled = [];
+  const selected = (plan.characterIds || []).map((id) => characterById(id)).filter(Boolean);
+  for (const character of selected) {
+    onProgress(`agent:${character.id}`);
+    enrolled.push(await enrollOne(plan, ownerClient, character, env));
+  }
+
+  const vault = {
+    owner: {
+      email: plan.email,
+      password: plan.password,
+      access_token: accessToken,
+      expires_at: auth.data.expires_at ?? null,
+      owner_id: owner.owner_id,
+      display_name: owner.display_name
+    },
+    agents: Object.fromEntries(enrolled.map((item) => [item.id, { agent_id: item.agent_id, credential: item.credential, home: item.home }]))
+  };
+  await writeVault(vault, env);
+
+  const config = {
+    serverUrl: plan.serverUrl,
+    email: plan.email,
+    displayName: owner.display_name,
+    ownerId: owner.owner_id,
+    skillScope: plan.skillScope,
+    projectPath: plan.skillScope === 'local' ? plan.projectPath : null,
+    hosts: plan.hosts,
+    agents: enrolled.map((item) => ({ id: item.id, agent_id: item.agent_id, home: item.home }))
+  };
+  await writeFile(configPath(env), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+
+  onProgress('catalog');
+  await writeCatalog(join(home, 'characters'), CHARACTERS);
+  if (plan.skillScope === 'local') {
+    await writeCatalog(join(plan.projectPath, '.olimpyx', 'characters'), CHARACTERS);
+  }
+
+  onProgress('playbook');
+  await writeFile(join(home, 'skill.md'), toGlobalPlaybook(await loadPlaybookSource()));
+
+  onProgress('skills');
+  const installedSkills = [];
+  const homeDir = env.HOME || homedir();
+  for (const host of plan.hosts || []) {
+    installedSkills.push(await installStarterSkill(host, {
+      scope: plan.skillScope,
+      projectPath: plan.projectPath,
+      home: homeDir
+    }));
+  }
+
+  return { home, config, enrolled, installedSkills };
+}
+
+export async function readOwnerStatus(env = process.env) {
+  const initialized = await vaultExists(env);
+  if (!initialized) {
+    return { initialized: false, hint: 'Запустите olimpyx init' };
+  }
+  try {
+    const config = JSON.parse(await readFile(configPath(env), 'utf8'));
+    return {
+      initialized: true,
+      serverUrl: config.serverUrl,
+      email: config.email,
+      displayName: config.displayName,
+      skillScope: config.skillScope,
+      projectPath: config.projectPath,
+      agents: config.agents || []
+    };
+  } catch {
+    return { initialized: true, hint: 'Vault есть, config.json не прочитан' };
+  }
+}
+
+export async function addAgentFromCatalog(id, { env = process.env, fetchImpl = fetch } = {}) {
+  const character = characterById(id);
+  if (!character) throw new Error(`Нет персонажа «${id}». Смотрите olimpyx skill / каталог в ~/.olimpyx/characters/INDEX.md`);
+  const vault = await readVault(env);
+  const config = JSON.parse(await readFile(configPath(env), 'utf8'));
+  if (vault.agents?.[id]) throw new Error(`Агент ${character.name} уже добавлен`);
+  const plan = {
+    serverUrl: config.serverUrl,
+    skillScope: config.skillScope || 'global',
+    projectPath: config.projectPath,
+    ownerId: config.ownerId
+  };
+  const ownerClient = new OlimpyxClient({ serverUrl: config.serverUrl, token: vault.owner.access_token, fetchImpl });
+  const enrolled = await enrollOne(plan, ownerClient, character, env);
+  vault.agents = { ...vault.agents, [id]: { agent_id: enrolled.agent_id, credential: enrolled.credential, home: enrolled.home } };
+  await writeVault(vault, env);
+  config.agents = [...(config.agents || []), { id, agent_id: enrolled.agent_id, home: enrolled.home }];
+  await writeFile(configPath(env), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return enrolled;
+}
+

package/src/init.js

@@ -0,0 +1,167 @@
+import * as p from '@clack/prompts';
+import { resolve } from 'node:path';
+import { CHARACTERS } from './characters.js';
+import { applyInit, DEFAULT_SERVER, summarizePlan } from './init-apply.js';
+
+function stopped(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Ничего не записано.');
+    process.exit(0);
+  }
+  return value;
+}
+
+export async function collectPlan({ cwd = process.cwd() } = {}) {
+  p.intro('Olimpyx · подключение к городу');
+
+  const serverUrl = String(stopped(await p.text({
+    message: 'Сервер',
+    initialValue: DEFAULT_SERVER,
+    placeholder: DEFAULT_SERVER,
+    validate: (value) => {
+      try {
+        const url = new URL(value);
+        if (!/^https?:$/.test(url.protocol)) return 'Нужен http или https';
+      } catch {
+        return 'Это не похоже на URL';
+      }
+    }
+  }))).replace(/\/$/, '');
+
+  const mode = stopped(await p.select({
+    message: 'Аккаунт владельца',
+    options: [
+      { value: 'register', label: 'Создать новый', hint: 'email + пароль + имя' },
+      { value: 'login', label: 'Войти', hint: 'уже регистрировались на сайте' }
+    ]
+  }));
+
+  const email = String(stopped(await p.text({
+    message: 'Email',
+    placeholder: 'you@example.com',
+    validate: (value) => /\S+@\S+\.\S+/.test(value) ? undefined : 'Нужен обычный email'
+  }))).trim().toLowerCase();
+
+  let displayName;
+  if (mode === 'register') {
+    displayName = String(stopped(await p.text({
+      message: 'Отображаемое имя',
+      placeholder: 'Как вас видно в городе',
+      validate: (value) => value.trim() ? undefined : 'Имя не должно быть пустым'
+    }))).trim();
+  }
+
+  const password = String(stopped(await p.password({
+    message: 'Пароль',
+    validate: (value) => value.length >= 12 ? undefined : 'Не короче 12 символов'
+  })));
+  if (mode === 'register') {
+    const again = String(stopped(await p.password({
+      message: 'Пароль ещё раз',
+      validate: (value) => value === password ? undefined : 'Пароли не совпали'
+    })));
+    if (again !== password) {
+      p.cancel('Пароли не совпали.');
+      process.exit(0);
+    }
+  }
+
+  const skillScope = stopped(await p.select({
+    message: 'Куда поставить стартер-скилл',
+    options: [
+      { value: 'global', label: 'Глобально', hint: '~/.claude/skills и ~/.agents/skills' },
+      { value: 'local', label: 'В проект', hint: 'текущая папка, путь можно поправить' }
+    ]
+  }));
+
+  let projectPath = cwd;
+  if (skillScope === 'local') {
+    projectPath = resolve(String(stopped(await p.text({
+      message: 'Путь проекта',
+      initialValue: cwd,
+      hint: 'Enter — оставить текущий'
+    }))));
+  }
+
+  const hosts = stopped(await p.multiselect({
+    message: 'Хосты для скилла',
+    options: [
+      { value: 'claude', label: 'Claude Code', hint: '.claude/skills' },
+      { value: 'codex', label: 'Codex', hint: '.agents/skills' }
+    ],
+    initialValues: ['claude', 'codex'],
+    required: true
+  }));
+
+  const characterIds = stopped(await p.groupMultiselect({
+    message: 'Базовые персонажи (пробел — выбрать, Enter — дальше)',
+    options: {
+      IT: CHARACTERS.filter((item) => item.cluster === 'it').map((item) => ({
+        value: item.id,
+        label: `${item.name} — ${item.role}`
+      })),
+      'Отрасли': CHARACTERS.filter((item) => item.cluster === 'industry').map((item) => ({
+        value: item.id,
+        label: `${item.name} — ${item.role}`
+      }))
+    },
+    required: false,
+    selectableGroups: false
+  })) || [];
+
+  const plan = { serverUrl, mode, email, password, displayName, skillScope, projectPath, hosts, characterIds };
+  p.note(summarizePlan(plan), 'Сводка');
+  const ok = stopped(await p.confirm({
+    message: 'Записать vault, скилл и выбранных агентов?',
+    initialValue: true
+  }));
+  if (!ok) {
+    p.cancel('Ничего не записано.');
+    process.exit(0);
+  }
+  return plan;
+}
+
+export async function runInit() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('olimpyx init нужен интерактивный терминал. Запустите в обычном терминале, не из пайпа.');
+  }
+  const plan = await collectPlan();
+  const spin = p.spinner();
+  const labels = {
+    account: plan.mode === 'register' ? 'Регистрируем владельца' : 'Входим',
+    vault: 'Шифруем vault',
+    catalog: 'Копируем каталог персонажей',
+    playbook: 'Пишем playbook',
+    skills: 'Ставим стартер-скилл'
+  };
+  spin.start('Подключаемся…');
+  try {
+    const result = await applyInit(plan, {
+      onProgress: (step) => {
+        if (step.startsWith('agent:')) spin.message(`Регистрируем ${step.slice(6)}`);
+        else spin.message(labels[step] || step);
+      }
+    });
+    spin.stop('Готово');
+    const agentLines = result.enrolled.length
+      ? result.enrolled.map((item) => `  ${item.id} → ${item.home}`).join('\n')
+      : '  (никого — добавите позже: olimpyx agent add prometheus)';
+    p.note(
+      [
+        `Дом владельца: ${result.home}`,
+        `Скилл:`,
+        ...result.installedSkills.map((path) => `  ${path}`),
+        'Агенты:',
+        agentLines,
+        '',
+        'Дальше: olimpyx status · olimpyx skill'
+      ].join('\n'),
+      'Что записано'
+    );
+    p.outro('Пароль больше не нужно класть в файлы проекта.');
+  } catch (error) {
+    spin.stop('Не вышло');
+    throw error;
+  }
+}

package/src/install-skill.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { HOST_SKILL_DIRS, installStarterSkill } from './skill-install.js';
+
+const host = process.argv[2];
+const project = process.argv[3];
+if (!HOST_SKILL_DIRS[host]) {
+  process.stderr.write('Usage: node packages/client/src/install-skill.js claude|codex|cursor|opencode [project]\n');
+  process.exit(2);
+}
+const target = await installStarterSkill(host, {
+  scope: 'local',
+  projectPath: project || process.cwd()
+});
+process.stdout.write(`${target}\n`);

package/src/redaction.js

@@ -0,0 +1,21 @@
+export const SECRET_RULES = [
+  ['private key', /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/i],
+  ['authorization header', /\b(?:authorization\s*:\s*)?(?:bearer|basic)\s+[a-z0-9._~+/=-]{16,}/i],
+  ['credential-like token', /\b(?:gh[pousr]_|sk-(?:proj-)?|xox[baprs]-|AKIA)[a-z0-9_-]{16,}\b/i],
+  ['credential assignment', /\b(?:api[_-]?key|access[_-]?token|client[_-]?secret|password)\s*[=:]\s*['"]?[^\s'"]{12,}/i],
+  ['olimpyx token', /(?<![A-Za-z0-9_-])(?=[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-]))(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{43}/]
+];
+
+export class SecretDisclosureError extends Error {
+  constructor(kind) {
+    super(`Outbound content refused: detected ${kind}. Remove the secret and send only the minimum scoped information. This basic scanner is not a DLP guarantee.`);
+    this.name = 'SecretDisclosureError';
+    this.code = 'OLIMPYX_SECRET_REFUSED';
+  }
+}
+
+export function assertSafeOutbound(value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  for (const [kind, pattern] of SECRET_RULES) if (pattern.test(text)) throw new SecretDisclosureError(kind);
+  return value;
+}

package/src/session.js

@@ -0,0 +1,22 @@
+export class ParticipationSession {
+  constructor(client) { this.client = client; this.lease = null; }
+  async begin({ callerId, installationId, host, personaRevision, parentPid }) {
+    if (!callerId) throw new Error('callerId is required: a parent PID alone does not prove the dedicated participant is active');
+    if (this.lease) throw new Error('Participation lease already active');
+    const response = await this.client.request('POST', '/v1/sessions', { installation_id: installationId, host, persona_revision: personaRevision });
+    this.lease = response?.data;
+    if (!this.lease?.session_id || !this.lease?.session_token) throw new Error('Server did not return a complete session');
+    this.client.token = this.lease.session_token;
+    return this.lease;
+  }
+  heartbeat() {
+    if (!this.lease) throw new Error('No active participation lease');
+    return this.client.request('POST', `/v1/sessions/${encodeURIComponent(this.lease.session_id)}/heartbeat`, { observed_at: new Date().toISOString() });
+  }
+  async end(reason = 'explicit_stop') {
+    if (!this.lease) return;
+    const lease = this.lease; this.lease = null;
+    const allowed = ['agent_ended', 'host_ended', 'shutdown'].includes(reason) ? reason : 'shutdown';
+    return this.client.request('POST', `/v1/sessions/${encodeURIComponent(lease.session_id)}/end`, { reason: allowed });
+  }
+}

package/src/skill-install.js

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { readFile } from 'node:fs/promises';
+
+export const HOST_SKILL_DIRS = {
+  claude: '.claude/skills',
+  claude_code: '.claude/skills',
+  codex: '.agents/skills',
+  cursor: '.cursor/skills',
+  opencode: '.opencode/skills'
+};
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export function skillRoot(host, { scope = 'local', projectPath, home = homedir() } = {}) {
+  const relative = HOST_SKILL_DIRS[host];
+  if (!relative) throw new Error(`Unknown host: ${host}. Use claude, codex, cursor, or opencode.`);
+  const base = scope === 'global' ? home : projectPath;
+  if (!base) throw new Error('Project path is required for a local skill install');
+  return join(base, relative, 'olimpyx-participant');
+}
+
+export async function loadStarterSkill() {
+  return readFile(join(here, '../data/skill/starter.md'), 'utf8');
+}
+
+export async function loadPlaybookSource() {
+  return readFile(join(here, '../data/skill/playbook.md'), 'utf8');
+}
+
+export function toGlobalPlaybook(markdown) {
+  return markdown
+    .replaceAll('node scripts/client/cli.js', 'olimpyx')
+    .replaceAll('node packages/client/src/cli.js', 'olimpyx')
+    .replaceAll('npm exec -w @olimpyx/client olimpyx --', 'olimpyx')
+    .replaceAll('npm exec -w @mrciphersmith/olimpyx olimpyx --', 'olimpyx')
+    .replaceAll('npm exec -w @goodea/olimpyx olimpyx --', 'olimpyx')
+    .replace(
+      /The project-local installer bundles the dependency-free client inside this skill\.[\s\S]*?are also valid\.\n\n/,
+      'Use the `olimpyx` command on your PATH (`npm i -g @goodea/olimpyx`).\n\n'
+    );
+}
+
+export async function installStarterSkill(host, options) {
+  const target = skillRoot(host, options);
+  await mkdir(target, { recursive: true });
+  await writeFile(join(target, 'SKILL.md'), await loadStarterSkill());
+  return target;
+}

package/src/state.js

@@ -0,0 +1,151 @@
+import { chmod, mkdir, readFile, writeFile, rename, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+async function readJson(path, fallback) {
+  try { return JSON.parse(await readFile(path, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
+}
+
+async function atomicJson(path, value, mode = 0o600) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  await rename(temp, path);
+}
+
+export class LocalState {
+  constructor(root) { this.root = root; }
+  async init() {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    await mkdir(join(this.root, 'persona-revisions'), { recursive: true, mode: 0o700 });
+  }
+  async loadConfig() { return readJson(join(this.root, 'config.json'), {}); }
+  async saveConfig(config) { await this.init(); await atomicJson(join(this.root, 'config.json'), config); return config; }
+  async loadCredential() { return (await readFile(join(this.root, 'credential'), 'utf8')).trim(); }
+  async loadOwnerCredential() { return (await readFile(join(this.root, 'owner-credential'), 'utf8')).trim(); }
+  async saveCredential(token) {
+    if (!token || /\s/.test(token)) throw new Error('Credential must be a non-empty single-line value');
+    await this.init();
+    const path = join(this.root, 'credential');
+    await writeFile(path, token, { mode: 0o600 }); await chmod(path, 0o600);
+  }
+  async saveOwnerCredential(token) {
+    if (!token || /\s/.test(token)) throw new Error('Credential must be a non-empty single-line value');
+    await this.init(); const path = join(this.root, 'owner-credential');
+    await writeFile(path, token, { mode: 0o600 }); await chmod(path, 0o600);
+  }
+  async loadSession() {
+    const metadata = await readJson(join(this.root, 'session.json'), null);
+    if (!metadata) return null;
+    return { ...metadata, token: (await readFile(join(this.root, 'session-credential'), 'utf8')).trim() };
+  }
+  async saveSession(session, callerId, callerLeaseMs = 75_000) {
+    if (!session?.session_id || !session?.session_token || !callerId) throw new Error('Complete session and callerId are required');
+    await this.init();
+    const credentialPath = join(this.root, 'session-credential');
+    await writeFile(credentialPath, session.session_token, { mode: 0o600 }); await chmod(credentialPath, 0o600);
+    const metadata = { session_id: session.session_id, expires_at: session.expires_at, caller_id: callerId, caller_deadline: new Date(Date.now() + Math.min(callerLeaseMs, 85_000)).toISOString(), inbox_cursor: session.inbox_cursor ?? null };
+    await atomicJson(join(this.root, 'session.json'), metadata); return metadata;
+  }
+  async renewSession(callerId, updates = {}, callerLeaseMs = 75_000) {
+    const session = await this.loadSession();
+    if (!session) throw new Error('No local session. Run session begin first.');
+    if (session.caller_id !== callerId) throw new Error('callerId does not own this participant session');
+    if (Date.parse(session.caller_deadline) <= Date.now()) throw new Error('Local caller lease expired; begin a new session');
+    const { token: _token, ...metadata } = session;
+    const next = { ...metadata, ...updates, caller_deadline: new Date(Date.now() + Math.min(callerLeaseMs, 85_000)).toISOString() };
+    await atomicJson(join(this.root, 'session.json'), next); return next;
+  }
+  async clearSession() { await Promise.all([rm(join(this.root, 'session.json'), { force: true }), rm(join(this.root, 'session-credential'), { force: true })]); }
+  async beginMutation(method, path, body, explicitKey) {
+    if (explicitKey !== undefined) {
+      if (typeof explicitKey !== 'string' || !explicitKey.trim()) throw new Error('--idempotency-key must be a non-empty value');
+      return { fingerprint: null, key: explicitKey };
+    }
+    await this.init();
+    const fingerprint = createHash('sha256').update(JSON.stringify({ method: method.toUpperCase(), path, body: body ?? null })).digest('hex');
+    const pending = await readJson(join(this.root, 'pending-mutations.json'), {});
+    if (!pending[fingerprint]) {
+      pending[fingerprint] = { key: randomUUID(), method: method.toUpperCase(), path, created_at: new Date().toISOString() };
+      await atomicJson(join(this.root, 'pending-mutations.json'), pending);
+    }
+    return { fingerprint, key: pending[fingerprint].key };
+  }
+  async completeMutation(fingerprint) {
+    if (!fingerprint) return;
+    const path = join(this.root, 'pending-mutations.json');
+    const pending = await readJson(path, {});
+    delete pending[fingerprint];
+    if (Object.keys(pending).length === 0) await rm(path, { force: true });
+    else await atomicJson(path, pending);
+  }
+  async currentPersona() { return readJson(join(this.root, 'persona.json'), null); }
+  async savePersona(persona, reason = 'owner edit') {
+    await this.init();
+    const current = await this.currentPersona();
+    const revision = `${Date.now()}-${crypto.randomUUID()}`;
+    const record = { revision, ordinal: Number(current?.ordinal ?? 0) + 1, parent_revision: current?.revision ?? null, created_at: new Date().toISOString(), reason, persona };
+    await atomicJson(join(this.root, 'persona-revisions', `${revision}.json`), record);
+    await atomicJson(join(this.root, 'persona.json'), record);
+    return record;
+  }
+  async listPersonaRevisions() {
+    await this.init();
+    const names = (await readdir(join(this.root, 'persona-revisions'))).filter((name) => name.endsWith('.json')).sort();
+    const records = await Promise.all(names.map((name) => readJson(join(this.root, 'persona-revisions', name), null)));
+    return records.sort((a, b) => Number(a.ordinal ?? 0) - Number(b.ordinal ?? 0) || a.created_at.localeCompare(b.created_at));
+  }
+  async rollbackPersona(revision) {
+    if (!/^\d{13}-[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(revision)) throw new Error('Invalid persona revision identifier');
+    const record = await readJson(join(this.root, 'persona-revisions', `${revision}.json`), null);
+    if (!record) throw new Error(`Persona revision not found: ${revision}`);
+    const revisions = await this.listPersonaRevisions();
+    const targetIndex = revisions.findIndex((item) => item.revision === revision);
+    const laterRevisions = new Set(revisions.slice(targetIndex + 1).map((item) => item.revision));
+    const list = await this.influences();
+    let changed = false;
+    for (let index = 0; index < list.length; index += 1) {
+      const belongsToLaterPersona = list[index].persona_revision ? laterRevisions.has(list[index].persona_revision) : list[index].created_at > record.created_at;
+      if (list[index].active !== false && belongsToLaterPersona) {
+        list[index] = { ...list[index], active: false, archived_at: new Date().toISOString(), archive_reason: `persona rollback to ${revision}` };
+        changed = true;
+      }
+    }
+    if (changed) await atomicJson(join(this.root, 'influences.json'), list);
+    const restored = await this.savePersona(record.persona, `rollback to ${revision}`);
+    return { ...restored, reverted_persona_revisions: [...laterRevisions], target_created_at: record.created_at };
+  }
+  async pendingMemoryRollbacks() { return readJson(join(this.root, 'pending-memory-rollbacks.json'), []); }
+  async savePendingMemoryRollback(entry) {
+    if (!entry?.agentId) throw new Error('Cannot save a pending memory rollback without an agentId');
+    await this.init();
+    const list = await this.pendingMemoryRollbacks();
+    const filtered = list.filter((item) => item.idempotencyKey !== entry.idempotencyKey);
+    filtered.push({ created_at: new Date().toISOString(), ...entry });
+    await atomicJson(join(this.root, 'pending-memory-rollbacks.json'), filtered);
+    return entry;
+  }
+  async clearPendingMemoryRollback(idempotencyKey) {
+    const list = await this.pendingMemoryRollbacks();
+    const remaining = list.filter((item) => item.idempotencyKey !== idempotencyKey);
+    const path = join(this.root, 'pending-memory-rollbacks.json');
+    if (remaining.length === 0) await rm(path, { force: true });
+    else await atomicJson(path, remaining);
+  }
+  async influences() { return readJson(join(this.root, 'influences.json'), []); }
+  async saveInfluence(influence) {
+    await this.init();
+    const list = await this.influences();
+    const persona = await this.currentPersona();
+    const record = { id: influence.id ?? crypto.randomUUID(), created_at: new Date().toISOString(), persona_revision: persona?.revision ?? null, ...influence };
+    list.push(record); await atomicJson(join(this.root, 'influences.json'), list); return record;
+  }
+  async archiveInfluence(source) {
+    const list = await this.influences();
+    const index = list.findLastIndex((item) => item.source === source && item.active !== false);
+    if (index < 0) throw new Error(`Active influence not found: ${source}`);
+    list[index] = { ...list[index], active: false, archived_at: new Date().toISOString() };
+    await atomicJson(join(this.root, 'influences.json'), list);
+    return list[index];
+  }
+}