loreli 0.0.0 → 2.0.0

package/packages/mcp/src/tools/start.js

@@ -0,0 +1,904 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Config, check } from 'loreli/config';
+import { hub as createHub, definitions } from 'loreli/hub';
+import { logger, bind } from 'loreli/log';
+import { models } from 'loreli/agent';
+import { ENTRY, CODEX_TOML, prune as pruneWorkspaces } from 'loreli/workspace';
+import { Tmux } from 'loreli/tmux';
+import { responder } from 'loreli/workflow';
+import { capability } from 'loreli/identity';
+import { select } from './repo.js';
+
+const log = logger('start');
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLDING = join(__dirname, '..', '..', 'scaffolding');
+const MERGE_BASE_RETRIES = 5;
+const MERGE_BASE_MIN_DELAY = 200;
+const MERGE_BASE_MAX_DELAY = 2000;
+
+/**
+ * Manifest of required files that start discovers and repairs.
+ *
+ * Single-file entries have a `source` string pointing to a scaffolding file.
+ * Directory entries have a `sourceDir` string pointing to a scaffolding
+ * directory whose contents are each scaffolded as individual files.
+ *
+ * @type {Array<{key: string, target: string, source?: string, sourceDir?: string}>}
+ */
+const REQUIRED = [
+  { key: 'pr', target: '.github/pull_request_template.md', source: 'pull-request.md' },
+  { key: 'issue', target: '.github/ISSUE_TEMPLATE', sourceDir: 'ISSUE_TEMPLATE' },
+  { key: 'config', target: 'loreli.yml', source: 'loreli.yml' },
+  { key: 'contextSkill', target: '.agents/skills/loreli-context/SKILL.md', source: '.agents/skills/loreli-context/SKILL.md' }
+];
+
+export default {
+  start: {
+    title: 'Start',
+    description: 'Initialize orchestration for a target GitHub repository. Validates access, discovers or scaffolds templates and loreli.yml, loads config, and reports the detected environment. Safe to re-run — only creates files that are absent.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository in "owner/name" format.' },
+        theme: {
+          oneOf: [
+            { type: 'string' },
+            { type: 'array', items: { type: 'string' } }
+          ],
+          description: 'Agent theme or list of themes to randomize per work item. Valid: transformers, pokemon, marvel, digimon, starwars, lotr, dragonball, avatar, zelda.'
+        },
+        reviewers: {
+          type: 'array', items: { type: 'string' },
+          description: 'GitHub usernames for Human In The Loop. Empty = auto-merge.'
+        }
+      }
+    },
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context (hub, registry, storage, etc.).
+     * @returns {Promise<object>} Start result with environment info and templates.
+     */
+    async exec(args, ctx) {
+      if (args.theme) check.theme(args.theme);
+      const repo = select(args.repo, ctx);
+      if (!repo) {
+        return {
+          content: [{ type: 'text', text: 'No repository configured. Pass --repo, set LORELI_REPO, or set repo in loreli.yml.' }],
+          isError: true
+        };
+      }
+
+      // Agent MCP servers (spawned from .mcp.json by Claude Code, Codex, etc.)
+      // are hydrated from env vars during _hydrate(). If a session ID is
+      // already set, this is an agent server — not a parent orchestrator.
+      // Re-starting would overwrite the session context and break
+      // the agent's ability to resolve its identity and task.
+      if (ctx.sessionId && ctx.agentName) {
+        log.info(`start skipped: agent server for ${ctx.agentName} (session: ${ctx.sessionId})`);
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              `This is an agent server for ${ctx.agentName} — start is not needed.`,
+              'Your session, identity, and repository context are already configured.',
+              'Use the plan, pr, and comment tools to interact with the repository.'
+            ].join('\n')
+          }]
+        };
+      }
+
+      log.info(`starting: ${repo}`);
+
+      // 0. Create hub if not yet attached (token comes from env or config)
+      if (!ctx.hub) {
+        ctx.hub = createHub({ config: ctx.config });
+      }
+
+      // 1. Discover environment + existing files in parallel
+      const backendRegistry = ctx.backendRegistry;
+
+      const templates = { pr: null, issue: null, codeowners: null, contributing: null, config: null };
+      const checks = [
+        ['.github/pull_request_template.md', 'pr'],
+        ['.github/PULL_REQUEST_TEMPLATE.md', 'pr'],
+        ['.github/ISSUE_TEMPLATE', 'issue'],
+        ['CODEOWNERS', 'codeowners'],
+        ['CONTRIBUTING.md', 'contributing'],
+        ['loreli.yml', 'config'],
+        ['.agents/skills/loreli-context/SKILL.md', 'contextSkill']
+      ];
+
+      const [/* discover result */, ...fileResults] = await Promise.all([
+        backendRegistry.discover(),
+        ...checks.map(function probe([path]) {
+          return ctx.hub.read(repo, path).then(function found() { return path; }, function miss() { return null; });
+        })
+      ]);
+
+      for (let i = 0; i < checks.length; i += 1) {
+        if (fileResults[i]) templates[checks[i][1]] = fileResults[i];
+      }
+
+      const backends = backendRegistry.available();
+      const providers = backendRegistry.providers();
+      const sideInfo = capability(providers);
+
+      let strategy = 'error';
+      if (sideInfo.mode === 'dual') strategy = 'yin-yang';
+      else if (sideInfo.mode === 'single') strategy = 'fresh-instance';
+
+      log.info(`backends: ${backends.map(function name(b) { return b.name; }).join(', ') || 'none'}, strategy: ${strategy}`);
+
+      // 3. Scaffold any missing required files
+      const scaffolded = [];
+      const toScaffold = [];
+
+      for (const entry of REQUIRED) {
+        if (!templates[entry.key]) {
+          if (entry.sourceDir) {
+            // Directory-based template: read all files in the source directory
+            const dir = join(SCAFFOLDING, entry.sourceDir);
+            const files = await readdir(dir);
+            for (const file of files) {
+              const content = await readFile(join(dir, file), 'utf8');
+              toScaffold.push({ path: `${entry.target}/${file}`, content });
+            }
+          } else {
+            const content = await readFile(join(SCAFFOLDING, entry.source), 'utf8');
+            toScaffold.push({ path: entry.target, content });
+          }
+          scaffolded.push(entry.target);
+        }
+      }
+
+      // Inline: scaffold() was a simple hub iteration over write()
+      if (toScaffold.length) {
+        log.info(`scaffolding ${toScaffold.length} files: ${scaffolded.join(', ')}`);
+        for (const file of toScaffold) {
+          await ctx.hub.write(repo, file.path, {
+            content: file.content,
+            message: `chore: scaffold ${file.path}`
+          });
+        }
+      }
+
+      // Run ensure* operations and config load in parallel — each
+      // targets different files so there are no ordering dependencies.
+      const config = new Config();
+      await Promise.all([
+        ensureDependency(ctx.hub, repo, scaffolded),
+        ensureMcpConfigs(ctx.hub, repo, scaffolded, backendRegistry.configPaths()),
+        ensureGitignore(ctx.hub, repo, scaffolded),
+        config.load(ctx.hub, repo)
+      ]);
+
+      // 5. Merge start param overrides
+      const overrides = {};
+      if (args.theme) overrides.theme = args.theme;
+      if (args.reviewers) overrides.reviewers = args.reviewers;
+      config.merge(overrides);
+
+      const theme = config.get('theme');
+      const mergeBase = config.get('merge.base') ?? 'main';
+
+      // 6. Ensure merge base and labels in parallel — both depend on
+      // config but are independent of each other.
+      let ensuredLabels = [];
+      const labelPromise = (async function ensureLabels() {
+        if (config.get('labels.track') === false) return [];
+        const labelNames = [
+          'loreli',
+          'loreli:planner', 'loreli:action', 'loreli:reviewer',
+          'loreli:approved', 'loreli:changes-requested'
+        ];
+        for (const backend of backends) {
+          if (backend.provider && backend.provider !== 'unknown') {
+            labelNames.push(`loreli:${backend.provider}`);
+          }
+        }
+        const extra = config.get('labels.extra') ?? [];
+        for (const name of extra) labelNames.push(name);
+
+        const unique = [...new Set(labelNames)];
+        return ctx.hub.ensure(repo, definitions(unique));
+      })();
+
+      const [baseProvision, labels] = await Promise.all([
+        ensureMergeBase(ctx.hub, repo, mergeBase),
+        labelPromise
+      ]);
+      ensuredLabels = labels;
+
+      // 7. Initialize session storage
+      const sessionId = `${repo.replace('/', '-')}-${Date.now()}`;
+      await ctx.storage.init(sessionId, config.toJSON());
+
+      // 8. Prune stale sessions, orphaned workspaces, and stale tmux sessions
+      if (config.get('cleanup.autoprune') !== false) {
+        const retention = config.get('cleanup.retention');
+        try {
+          const pruned = await ctx.storage.prune(retention);
+          if (pruned.length) log.info(`pruned ${pruned.length} stale sessions`);
+          const wsRemoved = await pruneWorkspaces(sessionId);
+          if (wsRemoved.length) log.info(`pruned ${wsRemoved.length} orphaned workspaces`);
+          const swept = await ctx.storage.sweep();
+          if (swept.length) log.info(`swept ${swept.length} stray files: ${swept.join(', ')}`);
+
+          // Destroy tmux sessions left behind by a previous MCP server.
+          // A stale tmux session contains agent panes running with outdated
+          // env (API keys, budgets, tokens). Spawning new agents into it
+          // inherits that stale env from the tmux server process.
+          if (Tmux.available()) {
+            const tmux = new Tmux();
+            const sessionName = config.get('tmux.session');
+            const result = await tmux.reap(sessionName);
+            if (result.killed) {
+              log.info(`reaped stale tmux session "${sessionName}" (${result.panes} panes)`);
+            }
+          }
+        } catch (err) {
+          log.warn(`cleanup failed (non-fatal): ${err.message}`);
+        }
+      }
+
+      // 9. Bind the logging subsystem to this session and config
+      bind({ session: sessionId, config });
+      log.info(`session initialized: ${sessionId}`);
+
+      // Wire rate limit warnings to the logger
+      if (ctx.hub.onRateLimitWarning !== undefined || Object.getOwnPropertyDescriptor(Object.getPrototypeOf(ctx.hub), 'onRateLimitWarning')) {
+        ctx.hub.onRateLimitWarning = function warnRateLimit(info) {
+          log.warn(`rate limit low: ${info.remaining}/${info.limit} (${Math.round(info.ratio * 100)}%), resets ${info.reset}`);
+        };
+      }
+
+      // Attach config and repo to context for downstream tools
+      ctx.config = config;
+      ctx.repo = repo;
+      ctx.sessionId = sessionId;
+
+      // Wire the orchestrator with the now-available hub, config, and repo
+      if (ctx.orchestrator) {
+        ctx.orchestrator.hub = ctx.hub;
+        ctx.orchestrator.cfg = ctx.config;
+        ctx.orchestrator.sessionId = sessionId;
+        ctx.orchestrator.repo = repo;
+        ctx.orchestrator.clientIdentity = ctx.clientIdentity ?? null;
+      }
+
+      // Wire workflow instances with the now-available hub
+      if (ctx.planner) ctx.planner.hub = ctx.hub;
+      if (ctx.action) ctx.action.hub = ctx.hub;
+      if (ctx.risk) ctx.risk.hub = ctx.hub;
+      if (ctx.review) ctx.review.hub = ctx.hub;
+
+      // Register risk workflow reactor handlers BEFORE review so
+      // labels are applied before scan() checks for them.
+      if (ctx.risk && ctx.orchestrator) {
+        const handlers = ctx.risk.reactor();
+        for (const [name, handler] of Object.entries(handlers)) {
+          ctx.orchestrator.register(name, handler);
+        }
+      }
+
+      // Register review workflow reactor handlers with the orchestrator
+      if (ctx.review && ctx.orchestrator) {
+        const handlers = ctx.review.reactor();
+        for (const [name, handler] of Object.entries(handlers)) {
+          ctx.orchestrator.register(name, handler);
+        }
+      }
+
+      // Register planner workflow reactor handlers
+      if (ctx.planner && ctx.orchestrator) {
+        const handlers = ctx.planner.reactor();
+        for (const [name, handler] of Object.entries(handlers)) {
+          ctx.orchestrator.register(name, handler);
+        }
+      }
+
+      // Register action workflow reactor handlers (dispatch dormant agents)
+      if (ctx.action && ctx.orchestrator) {
+        const handlers = ctx.action.reactor();
+        for (const [name, handler] of Object.entries(handlers)) {
+          ctx.orchestrator.register(name, handler);
+        }
+      }
+
+      // Register proof-of-life responder — scans issues/PRs for requests
+      // targeting our agents and posts health check responses.
+      if (ctx.orchestrator && ctx.hub) {
+        ctx.orchestrator.register('proof-of-life', responder(ctx.orchestrator, ctx.hub));
+      }
+
+      // Knowledge reactor — detect recurring feedback patterns and
+      // dispatch planning via planner when threshold is met.
+      if (ctx.orchestrator && ctx.hub) {
+        ctx.orchestrator.register('knowledge', async function knowledge(repo) {
+          const cfg = ctx.orchestrator.cfg;
+          if (!(cfg?.get?.('feedback.enabled') ?? true)) return;
+
+          const threshold = cfg?.get?.('feedback.threshold') ?? 5;
+          const { patterns, objective } = await import('loreli/knowledge');
+
+          const found = await patterns(ctx.hub, repo, { threshold });
+
+          const cat = await ctx.hub.category(repo, 'Loreli');
+          const discussions = await ctx.hub.discussions(repo, cat.id);
+          const openTitles = new Set(
+            discussions.filter(function open(d) { return !d.closed; })
+              .map(function title(d) { return d.title; })
+          );
+
+          for (const pattern of found) {
+            const title = `${pattern.category} feedback pattern`;
+            if (openTitles.has(title) || ctx._feedbackDispatched?.has(pattern.category)) continue;
+
+            await ctx.planner.plan(repo, objective(pattern), {
+              feedbackCategory: pattern.category
+            });
+
+            ctx._feedbackDispatched ??= new Set();
+            ctx._feedbackDispatched.add(pattern.category);
+          }
+        });
+      }
+
+      // Register workflows with orchestrator for demand-driven scaling.
+      // Each workflow reports its demand signal so scale() can spawn
+      // agents proportional to current workload.
+      if (ctx.orchestrator) {
+        const roleMap = { risk: ctx.risk, review: ctx.review, planner: ctx.planner, action: ctx.action };
+        for (const [role, workflow] of Object.entries(roleMap)) {
+          if (workflow) ctx.orchestrator.workflows.set(role, workflow);
+        }
+
+        // Demand-driven scaling — runs after all workflow handlers so
+        // demand signals reflect the latest hydrated state. Spawns agents
+        // to fill deficits respecting global/per-role caps and cooldowns.
+        ctx.orchestrator.register('scale', async function scale(repo) {
+          await ctx.orchestrator.scale(repo);
+        });
+      }
+
+      // Global reap safety net — catches dormant agents that the
+      // event-driven handlers (promote, land) missed. Runs last
+      // in the reactor chain.
+      if (ctx.orchestrator) {
+        ctx.orchestrator.register('reap', async function reap(repo) {
+          await ctx.orchestrator.reap(repo);
+        });
+      }
+
+      // Wire workflow event listeners to orchestrator events
+      for (const workflow of [ctx.planner, ctx.action, ctx.risk, ctx.review].filter(Boolean)) {
+        const listeners = workflow.events();
+        for (const [event, handler] of Object.entries(listeners)) {
+          ctx.orchestrator?.on(event, handler);
+        }
+      }
+
+      // Start the reactor loop — every started MCP instance joins
+      // the distributed system. The reactor polls for unclaimed issues,
+      // PRs needing review, and plans needing verdict. Agents are spawned
+      // on demand and reaped when idle.
+      if (ctx.orchestrator) {
+        ctx.orchestrator.watch(repo);
+        ctx.orchestrator.monitor();
+      }
+
+      // Dynamically update the add_agent tool description with discovered
+      // backends and model aliases so MCP clients see what's available.
+      if (ctx.server?.updateTool) {
+        const backendList = backends.map(function name(b) { return `${b.name} (${b.provider})`; }).join(', ');
+        const aliases = [...new Set(backends.flatMap(function aliases(b) { return models.list(b.name, ctx.config); }))];
+        const modelList = aliases.join(', ');
+        const providerList = providers.join(', ');
+
+        ctx.server.updateTool('add_agent', {
+          description: [
+            'Add an agent to the team. Acquires a themed identity, selects a backend, and prepares the agent for spawning.',
+            `Available backends: ${backendList || 'none detected'}.`,
+            `Model aliases: ${modelList}.`,
+            `Providers: ${providerList || 'none detected'}.`
+          ].join(' ')
+        });
+      }
+
+      // 10. Build found list
+      const found = Object.entries(templates)
+        .filter(function exists([, v]) { return v; })
+        .map(function entry([k]) { return k; });
+
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            `Started: ${repo}`,
+            `Session: ${sessionId}`,
+            `Theme: ${theme}`,
+            `Backends: ${backends.map(function name(b) { return `${b.name} (${b.provider})`; }).join(', ') || 'none detected'}`,
+            `Review strategy: ${strategy}`,
+            `Merge HITL: ${config.get('merge.hitl')}`,
+            baseProvision.created ? `Merge base provisioned: ${mergeBase} (from ${baseProvision.from})` : '',
+            found.length ? `Found: ${found.join(', ')}` : '',
+            scaffolded.length ? `Scaffolded: ${scaffolded.join(', ')}` : '',
+            ensuredLabels.length ? `Labels ensured: ${ensuredLabels.join(', ')}` : ''
+          ].filter(Boolean).join('\n')
+        }]
+      };
+    }
+  },
+
+  environment: {
+    title: 'Environment',
+    description: 'Report the detected environment: tmux version, available agent backends, providers, and review strategy.',
+    schema: { type: 'object', properties: {} },
+    /**
+     * @param {object} _args - Tool arguments (none).
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Environment report.
+     */
+    async exec(_args, ctx) {
+      try {
+        const backendRegistry = ctx.backendRegistry;
+        await backendRegistry.discover();
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              backends: backendRegistry.available(),
+              providers: backendRegistry.providers(),
+              capability: capability(backendRegistry.providers()),
+              tmux: (await import('loreli/tmux')).Tmux.available()
+            }, null, 2)
+          }]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `Environment detection failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  }
+};
+
+/**
+ * Determine whether an API error indicates a missing resource.
+ *
+ * @param {any} err - Error object from hub calls.
+ * @returns {boolean} True when the response status is 404.
+ */
+function isNotFound(err) {
+  return err?.status === 404;
+}
+
+/**
+ * Determine whether branch creation raced with another caller.
+ *
+ * @param {any} err - Error object from hub.fork().
+ * @returns {boolean} True when the remote branch already exists.
+ */
+function isBranchExists(err) {
+  if (err?.status !== 422) return false;
+  const body = JSON.stringify(err?.response?.data ?? '').toLowerCase();
+  if (body.includes('reference already exists')) return true;
+
+  const errors = err?.response?.data?.errors;
+  if (!Array.isArray(errors)) return false;
+
+  return errors.some(function alreadyExists(item) {
+    return item?.code === 'already_exists' || item?.message?.toLowerCase?.().includes('already exists');
+  });
+}
+
+/**
+ * Ensure the configured merge base branch exists in the remote repository.
+ * When missing, create it from the repository default branch.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string} base - Configured merge base branch.
+ * @returns {Promise<{created: boolean, from: string|null}>}
+ */
+async function ensureMergeBase(hub, repo, base, options = {}) {
+  if (!base) return { created: false, from: null };
+  if (typeof hub?.branch !== 'function') return { created: false, from: null };
+  if (typeof hub?.repo !== 'function') return { created: false, from: null };
+  if (typeof hub?.fork !== 'function') return { created: false, from: null };
+
+  try {
+    await hub.branch(repo, base);
+    return { created: false, from: null };
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+
+  const info = await hub.repo(repo);
+  const from = info?.default_branch ?? 'main';
+
+  try {
+    await hub.fork(repo, { name: base, from });
+    log.info(`start: provisioned merge base "${base}" from "${from}"`);
+  } catch (err) {
+    if (!isBranchExists(err)) throw err;
+    log.info(`start: merge base "${base}" already exists (race), continuing`);
+  }
+
+  await waitForBranch(hub, repo, base, options);
+  return { created: true, from };
+}
+
+/**
+ * Wait until a branch becomes visible through the branch endpoint.
+ * This absorbs short post-create consistency gaps from the GitHub API.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string} base - Branch name to verify.
+ * @param {object} [options] - Retry options.
+ * @param {number} [options.retries=5] - Maximum branch-read attempts.
+ * @param {number} [options.minDelay=200] - Initial delay in milliseconds.
+ * @param {number} [options.maxDelay=2000] - Maximum backoff delay in milliseconds.
+ * @param {(ms: number) => Promise<void>} [options.wait] - Delay function override for tests.
+ * @returns {Promise<void>}
+ */
+async function waitForBranch(hub, repo, base, options = {}) {
+  const retries = options.retries ?? MERGE_BASE_RETRIES;
+  const minDelay = options.minDelay ?? MERGE_BASE_MIN_DELAY;
+  const maxDelay = options.maxDelay ?? MERGE_BASE_MAX_DELAY;
+
+  for (let attempt = 0; attempt < retries; attempt += 1) {
+    try {
+      await hub.branch(repo, base);
+      return;
+    } catch (err) {
+      if (!isNotFound(err) || attempt === retries - 1) throw err;
+      const wait = Math.min(minDelay * (2 ** attempt), maxDelay);
+      log.debug(`start: merge base "${base}" not yet visible (${attempt + 1}/${retries}) — waiting ${wait}ms`);
+      await pause(wait, options.wait);
+    }
+  }
+}
+
+/**
+ * Wait for a number of milliseconds.
+ *
+ * @param {number} ms - Delay duration.
+ * @param {(ms: number) => Promise<void>} [wait] - Optional delay override.
+ * @returns {Promise<void>}
+ */
+async function pause(ms, wait) {
+  if (typeof wait === 'function') {
+    await wait(ms);
+    return;
+  }
+
+  await new Promise(function onTimeout(resolve) {
+    setTimeout(resolve, ms);
+  });
+}
+
+export { ensureMergeBase, normalizeCodexEnvVars };
+
+/**
+ * Ensure `loreli` exists in the target repo's devDependencies.
+ *
+ * - If `package.json` doesn't exist, creates one with `{ devDependencies: { loreli: "*" } }`.
+ * - If it exists but `loreli` is missing from devDependencies, reads the
+ *   current content, merges the dependency, and writes back — preserving
+ *   all existing fields.
+ * - If `loreli` is already present, does nothing.
+ *
+ * @param {object} hub - GitHub hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string[]} scaffolded - Mutable list of scaffolded file descriptions (for reporting).
+ * @returns {Promise<void>}
+ */
+// MCP config constants (ENTRY, CODEX_TOML) imported from @loreli/workspace
+// LORELI_TOML needs a leading newline for appending to existing TOML files
+const CODEX_ENV_VARS = 'env_vars = ["GITHUB_TOKEN"]';
+const LORELI_TOML = `\n${CODEX_TOML}`;
+
+/**
+ * Find the next TOML table header index at or after `start`.
+ *
+ * @param {string[]} lines - TOML content split by line.
+ * @param {number} start - Start index.
+ * @returns {number} Index of next table header or lines.length.
+ */
+function nextTomlTable(lines, start) {
+  for (let index = start; index < lines.length; index += 1) {
+    if (/^\[[^\]]+\]\s*$/.test(lines[index].trim())) return index;
+  }
+  return lines.length;
+}
+
+/**
+ * Find a TOML table header line index.
+ *
+ * @param {string[]} lines - TOML content split by line.
+ * @param {number} start - Start index.
+ * @param {string} header - Exact table header text.
+ * @returns {number} Header index or -1 when missing.
+ */
+function findTomlHeader(lines, start, header) {
+  for (let index = start; index < lines.length; index += 1) {
+    if (lines[index].trim() === header) return index;
+  }
+  return -1;
+}
+
+/**
+ * Normalize `.codex/config.toml` loreli token forwarding.
+ *
+ * Ensures `env_vars = ["GITHUB_TOKEN"]` is defined in the
+ * `[mcp_servers.loreli]` table and not inside the nested
+ * `[mcp_servers.loreli.env]` table.
+ *
+ * @param {string} content - Existing TOML content.
+ * @returns {string|null} Updated content when changed, else null.
+ */
+function normalizeCodexEnvVars(content) {
+  if (/^\s*mcp_servers\.loreli\.env_vars\s*=.*$/m.test(content)) return null;
+
+  const lines = content.split('\n');
+  const loreli = findTomlHeader(lines, 0, '[mcp_servers.loreli]');
+  if (loreli === -1) return null;
+
+  let changed = false;
+  let env = findTomlHeader(lines, loreli + 1, '[mcp_servers.loreli.env]');
+
+  if (env !== -1) {
+    const envEnd = nextTomlTable(lines, env + 1);
+    const envLines = lines.slice(env + 1, envEnd);
+    const kept = envLines.filter(function keepLine(line) {
+      return !/^\s*env_vars\s*=/.test(line);
+    });
+    if (kept.length !== envLines.length) {
+      lines.splice(env + 1, envEnd - env - 1, ...kept);
+      changed = true;
+      env = findTomlHeader(lines, loreli + 1, '[mcp_servers.loreli.env]');
+    }
+  }
+
+  const loreliEnd = env === -1 ? nextTomlTable(lines, loreli + 1) : env;
+  const hasEnvVars = lines.slice(loreli + 1, loreliEnd).some(function hasLine(line) {
+    return /^\s*env_vars\s*=/.test(line);
+  });
+
+  if (!hasEnvVars) {
+    lines.splice(loreliEnd, 0, CODEX_ENV_VARS);
+    changed = true;
+  }
+
+  if (!changed) return null;
+  return lines.join('\n');
+}
+
+/**
+ * Ensure the loreli MCP server is configured in all supported agent CLI
+ * config files (.mcp.json, .cursor/mcp.json, .codex/config.toml).
+ *
+ * For each config file:
+ * - If it doesn't exist, creates it with the loreli server entry.
+ * - If it exists but loreli is missing, merges/appends the entry.
+ * - If loreli is already configured, does nothing.
+ *
+ * JSON configs are parsed, merged, and re-serialized to preserve
+ * existing server entries. TOML configs are appended (TOML sections
+ * are order-independent).
+ *
+ * @param {object} hub - GitHub hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string[]} scaffolded - Mutable list of scaffolded file descriptions.
+ * @param {Array<{path: string, format: string, marker: string}>} configs - Config entries from backend registry.
+ * @returns {Promise<void>}
+ */
+async function ensureMcpConfigs(hub, repo, scaffolded, configs) {
+  for (const entry of configs) {
+    let existing;
+    try {
+      existing = await hub.read(repo, entry.path);
+    } catch { /* file doesn't exist */ }
+
+    if (!existing) {
+      // File doesn't exist — create from template
+      const content = await readFile(join(SCAFFOLDING, 'mcp-configs', entry.path), 'utf8');
+      await hub.write(repo, entry.path, {
+        content,
+        message: `chore: scaffold ${entry.path} with loreli MCP server`
+      });
+      scaffolded.push(entry.path);
+      log.info(`created ${entry.path} with loreli MCP server`);
+      continue;
+    }
+
+    // File exists — check if loreli is already configured
+    if (existing.content.includes(entry.marker)) {
+      if (entry.path === '.codex/config.toml') {
+        const updated = normalizeCodexEnvVars(existing.content);
+        if (updated) {
+          await hub.write(repo, entry.path, {
+            content: updated,
+            message: 'chore: add codex env_vars forwarding for loreli MCP server'
+          });
+          scaffolded.push(`${entry.path} (added env_vars forwarding)`);
+          log.info(`normalized env_vars forwarding in existing ${entry.path}`);
+          continue;
+        }
+      }
+
+      log.info(`loreli already in ${entry.path} — skipping`);
+      continue;
+    }
+
+    // Merge loreli into existing config
+    if (entry.format === 'json') {
+      const config = JSON.parse(existing.content);
+      config.mcpServers = { ...config.mcpServers, loreli: ENTRY };
+      await hub.write(repo, entry.path, {
+        content: JSON.stringify(config, null, 2) + '\n',
+        message: `chore: add loreli MCP server to ${entry.path}`
+      });
+    } else {
+      // TOML: append the section (order-independent in TOML)
+      const updated = existing.content.trimEnd() + LORELI_TOML;
+      await hub.write(repo, entry.path, {
+        content: updated,
+        message: `chore: add loreli MCP server to ${entry.path}`
+      });
+    }
+
+    scaffolded.push(`${entry.path} (added loreli)`);
+    log.info(`added loreli to existing ${entry.path}`);
+  }
+}
+
+async function ensureDependency(hub, repo, scaffolded) {
+  let existing;
+  try {
+    existing = await hub.read(repo, 'package.json');
+  } catch { /* file doesn't exist */ }
+
+  const pkg = existing ? JSON.parse(existing.content) : {};
+  let changed = false;
+  const changes = [];
+
+  if (!pkg.devDependencies?.loreli) {
+    pkg.devDependencies = { ...pkg.devDependencies, loreli: '*' };
+    changed = true;
+    changes.push('devDependency:loreli');
+  }
+
+  if (!pkg.scripts?.test) {
+    pkg.scripts = { ...pkg.scripts, test: 'node --test' };
+    changed = true;
+    changes.push('script:test');
+  }
+
+  if (!changed) {
+    log.info('package.json already has loreli devDependency and npm test script — skipping');
+    return;
+  }
+
+  await hub.write(repo, 'package.json', {
+    content: JSON.stringify(pkg, null, 2) + '\n',
+    message: existing
+      ? `chore: update package.json (${changes.join(', ')})`
+      : 'chore: scaffold package.json with loreli and npm test script'
+  });
+
+  if (existing) {
+    scaffolded.push(`package.json (updated ${changes.join(', ')})`);
+    log.info(`updated package.json (${changes.join(', ')})`);
+    return;
+  }
+
+  scaffolded.push('package.json (created with loreli and npm test script)');
+  log.info('created package.json with loreli devDependency and npm test script');
+}
+
+/**
+ * Marker string used to detect whether the Loreli gitignore block is
+ * already present. Checked via `String.includes()`.
+ * @type {string}
+ */
+const GITIGNORE_MARKER = '.loreli/';
+
+/**
+ * Ensure `.gitignore` contains Loreli artifact ignore rules.
+ *
+ * Prevents agent-generated files (`.loreli/`, `.claude/`, `.codex/`,
+ * `.cursor/hooks.json`) from leaking into PRs. This is the primary
+ * defense — committed to the repo, it survives clones and works
+ * regardless of how agents run git.
+ *
+ * - If `.gitignore` doesn't exist, creates it from the scaffolding template.
+ * - If it exists but doesn't contain the marker, appends the Loreli block.
+ * - If the marker is already present, does nothing.
+ *
+ * @param {object} hub - GitHub hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {string[]} scaffolded - Mutable list of scaffolded file descriptions.
+ * @returns {Promise<void>}
+ */
+async function ensureGitignore(hub, repo, scaffolded) {
+  const block = await readFile(join(SCAFFOLDING, '.gitignore'), 'utf8');
+
+  let existing;
+  try {
+    existing = await hub.read(repo, '.gitignore');
+  } catch { /* file doesn't exist */ }
+
+  if (!existing) {
+    try {
+      await hub.write(repo, '.gitignore', {
+        content: block,
+        message: 'chore: scaffold .gitignore with loreli artifact rules'
+      });
+      scaffolded.push('.gitignore');
+      log.info('created .gitignore with loreli artifact rules');
+      return;
+    } catch (err) {
+      if (err?.status !== 409) throw err;
+      log.warn('ensureGitignore: create conflict detected, reloading and retrying merge path');
+    }
+  }
+
+  if (!existing) {
+    try {
+      existing = await hub.read(repo, '.gitignore');
+    } catch { /* file may still not exist after conflict */ }
+
+    if (!existing) {
+      await hub.write(repo, '.gitignore', {
+        content: block,
+        message: 'chore: scaffold .gitignore with loreli artifact rules'
+      });
+      scaffolded.push('.gitignore');
+      log.info('created .gitignore with loreli artifact rules');
+      return;
+    }
+  }
+
+  if (existing.content.includes(GITIGNORE_MARKER)) {
+    log.info('loreli already in .gitignore — skipping');
+    return;
+  }
+
+  // Append the Loreli block to the existing .gitignore, separated by
+  // a blank line so it's visually distinct from existing entries.
+  const updated = existing.content.trimEnd() + '\n\n' + block;
+  try {
+    await hub.write(repo, '.gitignore', {
+      content: updated,
+      message: 'chore: add loreli artifact rules to .gitignore'
+    });
+    scaffolded.push('.gitignore (added loreli rules)');
+    log.info('added loreli artifact rules to existing .gitignore');
+  } catch (err) {
+    if (err?.status !== 409) throw err;
+
+    // Shared test repos can race with another writer between read and write.
+    // Re-read once: if loreli rules already landed, we're done; otherwise retry.
+    const latest = await hub.read(repo, '.gitignore');
+    if (latest.content.includes(GITIGNORE_MARKER)) {
+      log.info('loreli artifact rules already present after conflict — skipping');
+      return;
+    }
+
+    const retried = latest.content.trimEnd() + '\n\n' + block;
+    await hub.write(repo, '.gitignore', {
+      content: retried,
+      message: 'chore: add loreli artifact rules to .gitignore'
+    });
+    scaffolded.push('.gitignore (added loreli rules)');
+    log.info('added loreli artifact rules to existing .gitignore (after conflict retry)');
+  }
+}