@inkobytes/nexus 1.0.0

package/src/commands/release.js

@@ -0,0 +1,107 @@
+/**
+ * nexus release <path> "<commit message>"
+ * Unlock, auto-commit, update blackboard, log to report.
+ */
+
+import { appendFileSync } from 'fs';
+import { removeEntry } from '../lib/blackboard.js';
+import { listLocks, readGitHead, releaseLock } from '../lib/lockManager.js';
+import { stageAndCommit } from '../lib/git.js';
+import { getConfig } from '../lib/config.js';
+import { normalizeTarget } from '../lib/pathSafety.js';
+import { appendCompletedLedgerEntries } from './ledger.js';
+
+export default function release(args) {
+  let target = args[0];
+
+  if (!target) {
+    console.error('Usage: nexus release <filepath_or_dir> "<commit message>"');
+    process.exit(1);
+  }
+
+  try {
+    target = normalizeTarget(target);
+  } catch (err) {
+    console.error(`[ERROR] ${err.message}`);
+    process.exit(1);
+  }
+
+  const commitMsg = args[1] || `chore: agent updated ${target}`;
+  const lock = listLocks().find((entry) => entry.target === target);
+  const config = getConfig();
+  const releaseHead = readGitHead(config.root);
+  const claimHead = lock?.claimHead || 'unknown';
+  const hasHeadDrift = claimHead !== 'unknown' && releaseHead !== 'unknown' && claimHead !== releaseHead;
+
+  if (hasHeadDrift) {
+    console.warn(`[WARN] HEAD changed since claim for ${target}: claimed ${shortSha(claimHead)}, releasing from ${shortSha(releaseHead)}. Review interleaved commits if needed.`);
+  }
+
+  // Stage and commit first
+  const gitResult = stageAndCommit(target, commitMsg, lock?.agent || '');
+  if (!gitResult.success && !gitResult.message?.includes('clean')) {
+    console.error(`[ERROR] ${gitResult.message}`);
+    process.exit(1);
+  }
+
+  // Release the lock
+  const lockResult = releaseLock(target);
+  if (!lockResult.success) {
+    console.warn(`[WARN] ${lockResult.message}`);
+  }
+
+  // Remove from blackboard
+  removeEntry(`🔒 **${target}**`);
+
+  if (target === '_NEXUS_REPORT.md') {
+    console.log('[INFO] Skipped report append for _NEXUS_REPORT.md release to avoid self-noise.');
+    console.log('[LOCK RELEASED & COMMITTED]');
+    return;
+  }
+
+  // Append to report
+  const timestamp = formatReportTimestamp(new Date());
+  const reportLine = `## [${timestamp}] ${target}
+
+- Agent: ${lock?.agent || 'unknown'}
+- Target: ${target}
+- Claim HEAD: ${claimHead}
+- Release HEAD: ${releaseHead}
+- Drift: ${hasHeadDrift ? 'yes' : 'no'}
+- SHA: ${gitResult.sha || 'unknown'}
+- Commit: ${commitMsg}
+
+`;
+
+  try {
+    appendFileSync(config.report, reportLine, 'utf-8');
+  } catch { /* report file might not exist yet */ }
+
+  try {
+    const count = appendCompletedLedgerEntries({
+      target,
+      agent: lock?.agent || 'unknown',
+      sha: gitResult.sha || 'unknown',
+      commit: commitMsg,
+    });
+    if (count) console.log(`[LEDGER] Added ${count} completed task entr${count === 1 ? 'y' : 'ies'}.`);
+  } catch { /* ledger is reporting only; release should still complete */ }
+
+  console.log('[LOCK RELEASED & COMMITTED]');
+}
+
+function shortSha(sha) {
+  return sha === 'unknown' ? sha : sha.slice(0, 7);
+}
+
+function formatReportTimestamp(date) {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, '0');
+  const dd = String(date.getDate()).padStart(2, '0');
+  const rawHour = date.getHours();
+  const hour = rawHour % 12 || 12;
+  const minute = String(date.getMinutes()).padStart(2, '0');
+  const second = String(date.getSeconds()).padStart(2, '0');
+  const period = rawHour < 12 ? 'AM' : 'PM';
+  return `${yyyy}-${mm}-${dd} ${String(hour).padStart(2, '0')}:${minute}:${second} ${period}`;
+}

package/src/commands/soul.js

@@ -0,0 +1,156 @@
+/**
+ * nexus soul - apply a local soul overlay to agent instruction files
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { cwd } from 'process';
+
+const DEFAULT_OVERLAY_PATH = '.nexus/local/agent-overlay.md';
+const START_MARKER_PREFIX = '<!-- NEXUS-LOCAL-SOUL:START';
+const END_MARKER = '<!-- NEXUS-LOCAL-SOUL:END -->';
+
+const AGENT_ENTRYPOINTS = [
+  '.agy/AGENTS.md',
+  '.codex/AGENTS.md',
+  '.claude/CLAUDE.md',
+  '.gemini/GEMINI.md',
+];
+
+const DEFAULT_OVERLAY = `# Local Soul Overlay
+
+Add your local agent behavior notes here. This file is local workspace flavor:
+tone, response rhythm, naming defaults, and other private context that should
+sit outside the public Nexus protocol block.
+`;
+
+function parseArgs(args) {
+  const fileIndex = args.indexOf('--file');
+  const mode = args.includes('--status') ? 'status' : args.includes('--remove') ? 'remove' : 'apply';
+  if (fileIndex === -1) return { overlayPath: DEFAULT_OVERLAY_PATH, mode };
+  if (!args[fileIndex + 1]) {
+    throw new Error('Usage: nexus soul [--file <path>] [--status | --remove]');
+  }
+  return { overlayPath: args[fileIndex + 1], mode };
+}
+
+function localSoulBlock(overlayPath, content) {
+  return `${START_MARKER_PREFIX} ${overlayPath} -->
+${content.trim()}
+${END_MARKER}`;
+}
+
+function upsertSoulBlock(existing, overlayPath, overlayContent) {
+  const start = existing.indexOf(START_MARKER_PREFIX);
+  const end = existing.indexOf(END_MARKER);
+  const block = localSoulBlock(overlayPath, overlayContent);
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const before = existing.slice(0, start).trimEnd();
+    const after = existing.slice(end + END_MARKER.length).trimStart();
+    return `${before}\n\n${block}\n${after ? `\n${after}` : ''}`;
+  }
+
+  const firstHeadingEnd = existing.indexOf('\n');
+  if (firstHeadingEnd !== -1 && existing.startsWith('# ')) {
+    const title = existing.slice(0, firstHeadingEnd).trimEnd();
+    const body = existing.slice(firstHeadingEnd).trimStart();
+    return `${title}\n\n${block}\n\n${body}`;
+  }
+
+  return `${block}\n\n${existing.trimStart()}`;
+}
+
+function removeSoulBlock(existing) {
+  const start = existing.indexOf(START_MARKER_PREFIX);
+  const end = existing.indexOf(END_MARKER);
+  if (start === -1 || end === -1 || end <= start) return existing;
+
+  const before = existing.slice(0, start).trimEnd();
+  const after = existing.slice(end + END_MARKER.length).trimStart();
+  return `${before}${before && after ? '\n\n' : ''}${after ? `${after}\n` : ''}`;
+}
+
+function hasSoulBlock(existing) {
+  const start = existing.indexOf(START_MARKER_PREFIX);
+  const end = existing.indexOf(END_MARKER);
+  return start !== -1 && end !== -1 && end > start;
+}
+
+export default function soul(args) {
+  const root = cwd();
+  const { overlayPath, mode } = parseArgs(args);
+  const fullOverlayPath = join(root, overlayPath);
+
+  if (mode === 'status') {
+    console.log('Nexus soul status');
+    console.log(`Overlay: ${overlayPath} (${existsSync(fullOverlayPath) ? 'exists' : 'missing'})`);
+
+    for (const entrypoint of AGENT_ENTRYPOINTS) {
+      const path = join(root, entrypoint);
+      const state = existsSync(path) && hasSoulBlock(readFileSync(path, 'utf-8')) ? 'applied' : 'missing';
+      console.log(`  - ${entrypoint}: ${state}`);
+    }
+    return;
+  }
+
+  if (mode === 'remove') {
+    const removed = [];
+    for (const entrypoint of AGENT_ENTRYPOINTS) {
+      const path = join(root, entrypoint);
+      if (!existsSync(path)) continue;
+      const existing = readFileSync(path, 'utf-8');
+      const next = removeSoulBlock(existing);
+      if (next === existing) continue;
+      writeFileSync(path, next, 'utf-8');
+      removed.push(entrypoint);
+    }
+
+    if (removed.length) {
+      console.log('Removed local soul overlay:');
+      for (const entrypoint of removed) console.log(`  - ${entrypoint}`);
+    } else {
+      console.log('No local soul overlay blocks found.');
+    }
+    return;
+  }
+
+  mkdirSync(dirname(fullOverlayPath), { recursive: true });
+
+  if (!existsSync(fullOverlayPath)) {
+    writeFileSync(fullOverlayPath, DEFAULT_OVERLAY, 'utf-8');
+    console.log(`Created ${overlayPath}`);
+  }
+
+  const overlayContent = readFileSync(fullOverlayPath, 'utf-8');
+  const updated = [];
+  const missing = [];
+
+  for (const entrypoint of AGENT_ENTRYPOINTS) {
+    const path = join(root, entrypoint);
+    if (!existsSync(path)) {
+      missing.push(entrypoint);
+      continue;
+    }
+
+    const existing = readFileSync(path, 'utf-8');
+    const next = upsertSoulBlock(existing, overlayPath, overlayContent);
+    if (next === existing) continue;
+
+    writeFileSync(path, next, 'utf-8');
+    updated.push(entrypoint);
+  }
+
+  if (updated.length) {
+    console.log('Applied local soul overlay:');
+    for (const entrypoint of updated) console.log(`  - ${entrypoint}`);
+  } else {
+    console.log('Local soul overlay already up to date.');
+  }
+
+  if (missing.length) {
+    console.log('\nSkipped missing agent files:');
+    for (const entrypoint of missing) console.log(`  - ${entrypoint}`);
+    console.log('Run `nexus init` first to scaffold agent files.');
+  }
+}

package/src/commands/standup.js

@@ -0,0 +1,59 @@
+/**
+ * nexus standup "YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message"
+ * Append a validated one-line standup message.
+ */
+
+import { appendFileSync, existsSync, writeFileSync } from 'fs';
+import { getConfig } from '../lib/config.js';
+
+const STANDUP_FORMAT = 'YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message';
+const STANDUP_LINE_RE = /^(\d{4})-(\d{2})-(\d{2}) (0[1-9]|1[0-2]):([0-5]\d) (AM|PM) (@[a-z0-9][a-z0-9_-]*) \[([A-Z][A-Z0-9_-]*)\]: (.+)$/;
+
+export function validateStandupLine(line) {
+  const text = typeof line === 'string' ? line.trim() : '';
+
+  if (!text) {
+    return { ok: false, error: 'Missing standup message.' };
+  }
+
+  const match = text.match(STANDUP_LINE_RE);
+  if (!match) {
+    if (!/@[a-z0-9][a-z0-9_-]*/i.test(text)) {
+      return { ok: false, error: 'Missing or invalid standup agent.' };
+    }
+    return { ok: false, error: 'Invalid standup message format.' };
+  }
+
+  const [, yearText, monthText, dayText] = match;
+  if (!isRealDate(Number(yearText), Number(monthText), Number(dayText))) {
+    return { ok: false, error: 'Invalid standup date.' };
+  }
+
+  return { ok: true, line: text };
+}
+
+export default function standup(args = []) {
+  const line = args.join(' ').trim();
+  const result = validateStandupLine(line);
+
+  if (!result.ok) {
+    console.error(`[ERROR] ${result.error}`);
+    console.error(`Use: nexus standup "${STANDUP_FORMAT}"`);
+    process.exit(1);
+  }
+
+  const config = getConfig();
+  if (!existsSync(config.standup)) {
+    writeFileSync(config.standup, '# Nexus Standup\n\n', 'utf-8');
+  }
+
+  appendFileSync(config.standup, `${result.line}\n`, 'utf-8');
+  console.log('[STANDUP] Message recorded.');
+}
+
+function isRealDate(year, month, day) {
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}

package/src/commands/start.js

@@ -0,0 +1,126 @@
+/**
+ * nexus start - orient an agent entering a repo
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { cwd, env } from 'process';
+import { spawnSync } from 'child_process';
+import { listLocks } from '../lib/lockManager.js';
+import { AGENT_SCOPE_ENTRIES, AGENT_SCOPES, normalizeAgentHandle } from '../lib/agentScopes.js';
+import { loadPermissions, getChmodPath } from '../lib/permissions.js';
+
+function git(args) {
+  const result = spawnSync('git', args, { cwd: cwd(), encoding: 'utf-8', stdio: 'pipe' });
+  return result.status === 0 ? result.stdout.trim() : '';
+}
+
+function readFirstLines(path, maxLines = 8) {
+  if (!existsSync(path)) return null;
+  return readFileSync(path, 'utf-8').split('\n').slice(0, maxLines).join('\n').trim();
+}
+
+function optionValue(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? null : args[index + 1] || null;
+}
+
+function latestMemoryEntry(root, scopeDir) {
+  const memoryDir = join(root, scopeDir, 'memories');
+  if (!existsSync(memoryDir)) return null;
+
+  const entries = [];
+  for (const month of readdirSync(memoryDir)) {
+    const monthPath = join(memoryDir, month);
+    try {
+      if (!statSync(monthPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    for (const file of readdirSync(monthPath)) {
+      if (!file.endsWith('.md')) continue;
+      const path = join(monthPath, file);
+      try {
+        entries.push({ path: `${scopeDir}/memories/${month}/${file}`, mtimeMs: statSync(path).mtimeMs });
+      } catch { /* ignore unreadable entries */ }
+    }
+  }
+
+  entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return entries[0]?.path || null;
+}
+
+export default function start(args = []) {
+  const root = cwd();
+  const agent = normalizeAgentHandle(optionValue(args, '--agent') || args[0] || env.NEXUS_AGENT);
+  const scope = agent ? AGENT_SCOPES[agent] : null;
+  const branch = git(['branch', '--show-current']) || '(unknown)';
+  const commits = git(['log', '--oneline', '-n', '3']).split('\n').filter(Boolean);
+  const dirtyFiles = git(['status', '--porcelain']).split('\n').filter(Boolean);
+  const locks = listLocks();
+  const continuityPath = scope ? `${scope.dir}/CONTINUITY.md` : null;
+  const memoryIndexPath = scope ? `${scope.dir}/memories/INDEX.md` : null;
+  const continuity = scope ? readFirstLines(join(root, continuityPath)) : null;
+  const memoryEntry = scope ? latestMemoryEntry(root, scope.dir) : null;
+
+  console.log('Nexus start');
+  console.log(`Repo: ${root}`);
+  console.log(`Branch: ${branch}`);
+  console.log(`Agent: ${scope ? `${scope.label} (${agent})` : 'unspecified'}`);
+
+  console.log('\nLast commits:');
+  if (commits.length) {
+    for (const commit of commits) console.log(`  - ${commit}`);
+  } else {
+    console.log('  none');
+  }
+
+  console.log(`\nDirty files: ${dirtyFiles.length}`);
+  for (const file of dirtyFiles.slice(0, 20)) console.log(`  - ${file}`);
+  if (dirtyFiles.length > 20) console.log(`  ... ${dirtyFiles.length - 20} more`);
+
+  console.log(`\nLocks: ${locks.length}`);
+  for (const lock of locks) {
+    const age = lock.age === null ? 'unknown age' : `${lock.age}s old`;
+    console.log(`  - ${lock.target} (${age})`);
+  }
+
+  if (scope) {
+    console.log(`\nContinuity (${continuityPath}):`);
+    console.log(continuity ? continuity.split('\n').map((line) => `  ${line}`).join('\n') : '  missing');
+
+    console.log(`\nLatest local memory (${memoryIndexPath}):`);
+    console.log(`  ${memoryEntry || 'none'}`);
+  } else {
+    console.log('\nAgent memory scopes:');
+    for (const [handle, item] of AGENT_SCOPE_ENTRIES) {
+      console.log(`  - ${handle}: ${item.dir}/CONTINUITY.md, ${item.dir}/memories/INDEX.md`);
+    }
+    console.log('  Pick your model scope; do not read another model memory unless the user asks.');
+  }
+
+  // promptCHMOD — surface reference-only files so agents know what not to execute
+  if (existsSync(getChmodPath())) {
+    const perms = loadPermissions();
+    const xOff = perms.filter(e => e.perms[2] !== 'x' && (e.agent === 'all' || e.agent === agent));
+    const xOn  = perms.filter(e => e.perms[2] === 'x' && (e.agent === 'all' || e.agent === agent));
+    console.log('\npromptCHMOD:');
+    if (xOff.length) console.log(`  Reference only (do not execute): ${xOff.map(e => e.path).join(', ')}`);
+    if (xOn.length)  console.log(`  Authoritative (execute as instructions): ${xOn.map(e => e.path).join(', ')}`);
+  }
+
+  // Trigger presence heartbeat
+  if (agent) {
+    spawnSync('node', [join(root, 'bin', 'nexus.js'), 'checkin', agent], { stdio: 'ignore' });
+  }
+
+  console.log('\nNext:');
+  if (scope) {
+    console.log('  Start is orientation only, not clearance to edit.');
+    console.log(`  Read ${continuityPath} and latest ${scope.dir}/memories entry.`);
+    console.log(`  Then: pick work -> nexus claim <path> ${agent} "intent" -> work only there -> nexus release <path> "message".`);
+  } else {
+    console.log('  Set NEXUS_AGENT or run `nexus start --agent @agy|@claude|@codex|@gemini`, then restart before claiming work.');
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,109 @@
+/**
+ * nexus status — pretty-print the current blackboard
+ */
+
+import { readBoard } from '../lib/blackboard.js';
+import { listLocks } from '../lib/lockManager.js';
+import { getConfig } from '../lib/config.js';
+import { spawnSync } from 'child_process';
+
+export default function status(args) {
+  const config = getConfig();
+  const locks = listLocks();
+  const generatedArtifacts = scanGeneratedArtifacts(config.root);
+
+  if (locks.length === 0) {
+    console.log('🐝 No active locks. The swarm is idle.');
+    printGeneratedArtifacts(generatedArtifacts);
+    return;
+  }
+
+  console.log(`🐝 NEXUS STATUS — ${locks.length} active lock(s)\n`);
+
+  // Read the blackboard for agent info
+  const board = readBoard();
+  const boardLines = board.split('\n').filter(l => l.includes('🔒'));
+
+  for (const lock of locks) {
+    const ageStr = lock.age !== null ? formatAge(lock.age) : '??';
+    const stale = lock.age !== null && lock.age >= config.staleThreshold;
+
+    // Find matching board line for agent info
+    const boardLine = boardLines.find(l => l.includes(lock.target));
+    const agentMatch = boardLine?.match(/Locked by \*\*(.+?)\*\*/);
+    const agent = agentMatch ? agentMatch[1] : 'unknown';
+
+    const staleTag = stale ? ' ⚠️  STALE' : '';
+    console.log(`  🔒 ${lock.target}`);
+    console.log(`     Agent: ${agent} | Age: ${ageStr}${staleTag}`);
+  }
+
+  console.log('');
+  printGeneratedArtifacts(generatedArtifacts);
+}
+
+function formatAge(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+}
+
+function printGeneratedArtifacts(artifacts) {
+  if (artifacts.length === 0) return;
+
+  console.log('Generated-looking artifacts need owner decision:');
+  for (const artifact of artifacts) {
+    console.log(`  • ${artifact}`);
+  }
+  console.log('    Decide keep/delete/ignore, or claim and release intentionally.');
+}
+
+function scanGeneratedArtifacts(root) {
+  const result = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  });
+  if (result.status !== 0) return [];
+
+  const seen = new Set();
+  const artifacts = [];
+  for (const line of result.stdout.split('\n')) {
+    if (!line.startsWith('?? ')) continue;
+    const file = parseGitStatusPath(line.slice(3).trim());
+    const ownerPath = generatedArtifactOwnerPath(file);
+    if (!ownerPath || seen.has(ownerPath)) continue;
+    seen.add(ownerPath);
+    artifacts.push(ownerPath);
+  }
+
+  return artifacts;
+}
+
+function generatedArtifactOwnerPath(file) {
+  const normalized = file.replace(/\\/g, '/');
+  if (/(^|\/)(dist|build|coverage|tmp|temp|exports?|reports?|ledgers?|screenshots?)(\/|$)/i.test(normalized)) {
+    return firstPathSegment(normalized);
+  }
+  if (/(^|\/)[^/]*\bcopy\b[^/]*(\/|$)/i.test(normalized)) {
+    return firstPathSegment(normalized);
+  }
+  if (/\.(png|jpe?g|gif|webp|pdf|log|tmp)$/i.test(normalized)) {
+    return normalized;
+  }
+  return '';
+}
+
+function parseGitStatusPath(file) {
+  if (!file.startsWith('"') || !file.endsWith('"')) return file;
+
+  try {
+    return JSON.parse(file);
+  } catch {
+    return file.slice(1, -1);
+  }
+}
+
+function firstPathSegment(file) {
+  return file.split('/')[0];
+}

package/src/hooks/pre-migration-backup.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook — auto-backup databases before migration commands.
+ * Reads Claude Code tool input from stdin, detects migration patterns,
+ * runs `nexus db backup --auto` if matched, then exits 0 (allow).
+ * Philosophy: backup-then-allow, never block.
+ */
+
+import { readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+
+const MIGRATION_PATTERNS = /\b(migrate|db:migrate|alembic\s+upgrade|flyway|sequelize.*migrate|knex.*migrate|prisma\s+migrate)\b/i;
+
+let input;
+try {
+  input = JSON.parse(readFileSync('/dev/stdin', 'utf-8'));
+} catch {
+  process.exit(0);
+}
+
+const command = input?.tool_input?.command || '';
+
+if (MIGRATION_PATTERNS.test(command)) {
+  console.log('[nexus db] Migration detected — running backup before proceeding...');
+  const result = spawnSync('nexus', ['db', 'backup', '--auto'], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: process.cwd(),
+  });
+  if (result.status !== 0) {
+    console.error('[nexus db] Backup failed — proceeding anyway (check .nexus/db-backups/)');
+  }
+}
+
+process.exit(0);

package/src/lib/agentScopes.js

@@ -0,0 +1,61 @@
+export const AGENT_SCOPES = {
+  '@agy': {
+    label: 'Antigravity',
+    dir: '.agy',
+    entrypoint: '.agy/AGENTS.md',
+    continuity: '.agy/CONTINUITY.md',
+    memoryIndex: '.agy/memories/INDEX.md',
+    memoryDir: '.agy/memories',
+    aliases: ['agy', 'antigravity'],
+  },
+  '@claude': {
+    label: 'Claude',
+    dir: '.claude',
+    entrypoint: '.claude/CLAUDE.md',
+    continuity: '.claude/CONTINUITY.md',
+    memoryIndex: '.claude/memories/INDEX.md',
+    memoryDir: '.claude/memories',
+    aliases: ['claude'],
+  },
+  '@codex': {
+    label: 'Codex',
+    dir: '.codex',
+    entrypoint: '.codex/AGENTS.md',
+    continuity: '.codex/CONTINUITY.md',
+    memoryIndex: '.codex/memories/INDEX.md',
+    memoryDir: '.codex/memories',
+    aliases: ['codex'],
+  },
+  '@gemini': {
+    label: 'Gemini',
+    dir: '.gemini',
+    entrypoint: '.gemini/GEMINI.md',
+    continuity: '.gemini/CONTINUITY.md',
+    memoryIndex: '.gemini/memories/INDEX.md',
+    memoryDir: '.gemini/memories',
+    aliases: ['gemini'],
+  },
+};
+
+export const CANONICAL_MODEL_HANDLES = Object.keys(AGENT_SCOPES);
+export const CANONICAL_MODEL_HANDLES_TEXT = `${CANONICAL_MODEL_HANDLES.slice(0, -1).join(', ')}, or ${CANONICAL_MODEL_HANDLES.at(-1)}`;
+export const CANONICAL_MODEL_HANDLE_SET = new Set(CANONICAL_MODEL_HANDLES);
+export const AGENT_SCOPE_ENTRIES = Object.entries(AGENT_SCOPES);
+export const AGENT_SCOPE_LIST = Object.values(AGENT_SCOPES);
+
+export function normalizeAgentHandle(agent) {
+  if (!agent) return null;
+  const normalized = agent.toLowerCase();
+  if (AGENT_SCOPES[normalized]) return normalized;
+
+  for (const [handle, scope] of AGENT_SCOPE_ENTRIES) {
+    if (scope.aliases.some((alias) => normalized.includes(alias))) return handle;
+  }
+
+  return null;
+}
+
+export function hasAgentAlias(value) {
+  const normalized = value.toLowerCase();
+  return AGENT_SCOPE_LIST.some((scope) => scope.aliases.some((alias) => normalized.includes(alias)));
+}