loreli 0.0.0 → 2.0.0

package/packages/workspace/src/index.js

@@ -0,0 +1,1127 @@
+import { readFile, writeFile, mkdir, rm, access, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/**
+ * Timeout for git network operations (fetch, clone, push) in ms.
+ * Prevents hung network connections from blocking the orchestrator.
+ * @type {number}
+ */
+const GIT_TIMEOUT = 30_000;
+
+/**
+ * Run a child process with an optional timeout.
+ *
+ * @param {string} cmd - Command to execute.
+ * @param {string[]} args - Arguments.
+ * @param {object} [opts] - execFile options.
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+function run(cmd, args, opts = {}) {
+  return exec(cmd, args, opts);
+}
+
+/**
+ * Pattern for safe path segments — alphanumeric, hyphens, and underscores only.
+ * Prevents path traversal, tmux injection, and shell metacharacter issues.
+ * @type {RegExp}
+ */
+const SAFE_NAME = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate that a name is safe for use in file paths and tmux session IDs.
+ *
+ * @param {string} value - The name to validate.
+ * @param {string} label - Human-readable label for error messages.
+ * @throws {Error} When the value contains unsafe characters.
+ */
+function assertSafe(value, label) {
+  if (!SAFE_NAME.test(value))
+    throw new Error(`Invalid ${label} "${value}": must match ${SAFE_NAME}`);
+}
+
+/**
+ * Default root directory for agent workspaces.
+ * Lives under the loreli home so all state is colocated.
+ * @type {string}
+ */
+const DEFAULT_ROOT = join(process.env.LORELI_HOME ?? join(homedir(), '.loreli'), 'workspaces');
+
+/**
+ * Loreli MCP server entry for JSON-based CLI tools.
+ *
+ * @type {{command: string, args: string[]}}
+ */
+export const ENTRY = { command: 'npx', args: ['loreli', 'mcp'] };
+
+/**
+ * MCP config for JSON-based CLI tools (Claude, Cursor).
+ *
+ * Points the loreli MCP server entry at `npx loreli mcp`, which is
+ * the same content start writes to the target GitHub repo. By
+ * scaffolding it into the agent's cwd before spawn, the CLI backend
+ * discovers Loreli tools immediately on startup.
+ *
+ * @type {string}
+ */
+export const MCP_JSON = JSON.stringify({
+  mcpServers: { loreli: ENTRY }
+}, null, 2) + '\n';
+
+/**
+ * MCP config for TOML-based CLI tools (Codex).
+ * @type {string}
+ */
+export const CODEX_TOML = [
+  '[mcp_servers.loreli]',
+  'command = "npx"',
+  'args = ["loreli", "mcp"]',
+  'env_vars = ["GITHUB_TOKEN"]',
+  ''
+].join('\n');
+
+/**
+ * Build Codex TOML config, optionally injecting agent context env vars.
+ *
+ * @param {object} [context] - Agent context for env injection.
+ * @param {string} [context.session] - Session ID.
+ * @param {string} [context.agent] - Agent identity name.
+ * @param {string} [context.repo] - Target repository (owner/name).
+ * @returns {string} TOML string for .codex/config.toml.
+ */
+export function codexToml(context) {
+  let toml = CODEX_TOML;
+  if (context?.session) {
+    toml += `\n[mcp_servers.loreli.env]\nLORELI_SESSION = "${context.session}"\nLORELI_AGENT = "${context.agent}"\nLORELI_REPO = "${context.repo}"\n`;
+    if (context.home) toml += `LORELI_HOME = "${context.home}"\n`;
+  }
+  return toml;
+}
+
+
+/**
+ * Generate the common deny shell script content.
+ *
+ * Produces a bash script that reads JSON from stdin, extracts the
+ * command to be executed (supporting both Claude Code `tool_input.command`
+ * and Cursor Agent `command` formats), and exits with code 2 (block)
+ * if the first token matches a denied command.
+ *
+ * Exit code 2 is the universal block signal recognized by both
+ * Claude Code PreToolUse hooks and Cursor Agent beforeShellExecution hooks.
+ *
+ * @param {string[]} denied - List of command names to block.
+ * @returns {string} Shell script content.
+ */
+export function denyScript(denied) {
+  const pattern = denied.join('|');
+  const lines = [
+    '#!/bin/bash',
+    '# .loreli/deny.sh — Loreli agent command deny hook',
+    '# Exit 2 = block (universal signal for Claude Code and Cursor Agent).',
+    '',
+    'INPUT=$(cat)',
+    'CMD=$(echo "$INPUT" | jq -r \'.tool_input.command // .command // empty\' 2>/dev/null)',
+    'FIRST=$(echo "$CMD" | awk \'{print $1}\')',
+    '',
+    '# Protected-path whitelist: block any command referencing scaffolding',
+    '# or security files unless the command is clearly read-only.',
+    'PROTECTED=\'\\.(gitignore|mcp\\.json|secretlintrc)|\\.(git/hooks|cursor/|codex/|claude/|loreli/)\'',
+    'if echo "$CMD" | grep -qE "$PROTECTED"; then',
+    '  case "$FIRST" in',
+    '    cat|less|head|tail|grep|rg|wc|file|ls|stat|find|diff|loreli) exit 0 ;;',
+    '  esac',
+    '  echo "$CMD" | grep -qE \'(^|[[:space:]])git[[:space:]]+(diff|log|show|status|branch|remote)\' && exit 0',
+    '  exit 2',
+    'fi',
+    '',
+    '# Commit-family --no-verify blocking: prevent agents from bypassing',
+    '# pre-commit hooks regardless of how they invoke git.',
+    'if echo "$CMD" | grep -qE \'(commit|merge|cherry-pick|revert|rebase)\'; then',
+    '  echo "$CMD" | grep -qE \'(--no-verify|[[:space:]]-n[[:space:]]|[[:space:]]-n$)\' && exit 2',
+    'fi',
+    '',
+    '# Scaffolding-file staging check: block commits that include loreli',
+    '# scaffolding files in the staging area.',
+    'if echo "$CMD" | grep -qE \'(^|[[:space:]])git[[:space:]]+(commit|merge|cherry-pick|revert)\'; then',
+    '  SCAFFOLDING=\'^\\.mcp\\.json$|^\\.codex/|^\\.cursor/|^\\.claude/|^\\.loreli/|^\\.gitignore$|^\\.secretlintrc\'',
+    '  git diff --cached --name-only 2>/dev/null | grep -qE "$SCAFFOLDING" && exit 2',
+    '',
+    '  # Secretlint check: scan staged files for secrets before commit.',
+    '  # Conditional on secretlint being installed in the workspace.',
+    '  FILES=$(git diff --cached --name-only 2>/dev/null)',
+    '  if [ -n "$FILES" ] && [ -x ./node_modules/.bin/secretlint ]; then',
+    '    echo "$FILES" | xargs ./node_modules/.bin/secretlint 2>/dev/null',
+    '    [ $? -ne 0 ] && exit 2',
+    '  fi',
+    'fi',
+    '',
+    '# First-token deny list',
+    'case "$FIRST" in',
+    `  ${pattern}) exit 2 ;;`,
+    '  *) exit 0 ;;',
+    'esac',
+    ''
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Generate the protect shell script for Claude file-write interception.
+ *
+ * Reads JSON from stdin (Claude PreToolUse hook format), extracts the
+ * file path from `tool_input.file_path` or `tool_input.path`, normalizes
+ * it (removes `./` prefix, resolves `../`), and blocks writes to
+ * protected scaffolding and security paths.
+ *
+ * Exit code 2 = block (universal signal for Claude Code hooks).
+ *
+ * @returns {string} Shell script content.
+ */
+export function protectScript() {
+  return [
+    '#!/bin/bash',
+    '# .loreli/protect.sh — Loreli agent file-write protection hook',
+    '# Blocks writes to scaffolding and security files.',
+    '',
+    'INPUT=$(cat)',
+    'FILE=$(echo "$INPUT" | jq -r \'.tool_input.file_path // .tool_input.path // empty\' 2>/dev/null)',
+    '',
+    '# Normalize path: strip leading ./, collapse /./,  resolve ../',
+    'FILE=$(echo "$FILE" | sed \'s|^\\./||; s|/\\./|/|g\')',
+    'while echo "$FILE" | grep -q \'[^/][^/]*/\\.\\./\'; do',
+    '  FILE=$(echo "$FILE" | sed \'s|[^/][^/]*/\\.\\./||\')',
+    'done',
+    '',
+    'echo "$FILE" | grep -qE \'(^|/)\\.(gitignore)$\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.mcp\\.json$\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.secretlintrc\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.git/\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.cursor/\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.codex/\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.claude/\' && exit 2',
+    'echo "$FILE" | grep -qE \'(^|/)\\.loreli/\' && exit 2',
+    'exit 0',
+    ''
+  ].join('\n');
+}
+
+/**
+ * Generate Claude Code project hook config content.
+ *
+ * Produces `.claude/settings.local.json` with a PreToolUse hook that
+ * fires for Bash tool invocations, delegating to the common deny script.
+ *
+ * @returns {string} JSON string for `.claude/settings.local.json`.
+ */
+export function claudeHooks() {
+  return JSON.stringify({
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Bash',
+        hooks: [{
+          type: 'command',
+          command: 'bash "$CLAUDE_PROJECT_DIR/.loreli/deny.sh"'
+        }]
+      }]
+    }
+  }, null, 2) + '\n';
+}
+
+/**
+ * Build a regex matcher string for Cursor's beforeShellExecution hook.
+ *
+ * Matches commands whose first token is any of the denied binaries.
+ * Handles both "cmd args..." (with trailing space) and bare "cmd"
+ * (end of string) patterns.
+ *
+ * @param {string[]} denied - List of command names to match.
+ * @returns {string} Regex pattern string.
+ */
+export function cursorMatcher(denied) {
+  const parts = denied.map(function toPattern(cmd) {
+    return `^${cmd} |^${cmd}$`;
+  });
+  return parts.join('|');
+}
+
+/**
+ * Generate Cursor Agent hook config content.
+ *
+ * Produces `.cursor/hooks.json` with a beforeShellExecution hook that
+ * uses a regex matcher to pre-filter commands, then delegates to the
+ * common deny script for the actual block decision.
+ *
+ * @param {string[]} denied - List of command names to block.
+ * @returns {string} JSON string for `.cursor/hooks.json`.
+ */
+export function cursorHooks(denied) {
+  return JSON.stringify({
+    version: 1,
+    hooks: {
+      beforeShellExecution: [{
+        command: '.loreli/deny.sh',
+        matcher: cursorMatcher(denied)
+      }]
+    }
+  }, null, 2) + '\n';
+}
+
+/**
+ * Read-merge-write a hook entry into an existing JSON hooks file.
+ *
+ * Preserves all existing content (hooks, permissions, other keys).
+ * Identifies the Loreli entry by searching for `marker` in the
+ * command string. If found, updates in place; otherwise appends.
+ *
+ * If the file does not exist or contains invalid JSON, starts fresh.
+ *
+ * @param {string} path - Absolute path to the hooks JSON file.
+ * @param {string} key - Hook event name (e.g. 'PreToolUse', 'beforeShellExecution').
+ * @param {object} entry - The hook entry object to merge.
+ * @param {string} marker - String to search for in existing entries to detect Loreli's hook.
+ * @param {object} [rootDefaults] - Default root-level keys to set if missing (e.g. `{ version: 1 }`).
+ * @returns {Promise<void>}
+ */
+async function mergeHook(path, key, entry, marker, rootDefaults) {
+  let config = {};
+  try {
+    config = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+  }
+
+  if (rootDefaults) {
+    for (const [k, v] of Object.entries(rootDefaults)) {
+      if (config[k] === undefined) config[k] = v;
+    }
+  }
+
+  if (!config.hooks) config.hooks = {};
+  if (!Array.isArray(config.hooks[key])) config.hooks[key] = [];
+
+  // Find existing Loreli entry by marker in command string.
+  // Claude hooks nest command inside `.hooks[0].command`;
+  // Cursor hooks use `.command` directly.
+  const idx = config.hooks[key].findIndex(
+    function isLoreli(h) {
+      return h.command?.includes(marker) || h.hooks?.[0]?.command?.includes(marker);
+    }
+  );
+
+  if (idx >= 0) config.hooks[key][idx] = entry;
+  else config.hooks[key].push(entry);
+
+  await writeFile(path, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Ensure a bare mirror of a remote repository exists locally.
+ *
+ * On first call, clones the repository as a bare repo under
+ * `<home>/repos/`. On subsequent calls, fetches to update refs.
+ * The bare mirror is shared across all agents and used as the
+ * source for `git worktree add` — eliminating per-agent clones.
+ *
+ * @param {string} url - Repository URL (https or file://).
+ * @param {object} [opts] - Options.
+ * @param {string} [opts.home] - Loreli home directory (default: ~/.loreli).
+ * @param {string} [opts.token] - GitHub token for authenticated clone.
+ * @returns {Promise<string>} Absolute path to the bare mirror.
+ */
+export async function mirror(url, opts = {}) {
+  const home = opts.home ?? process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+  const reposDir = join(home, 'repos');
+
+  // Derive a stable directory name from the URL
+  const slug = url
+    .replace(/^file:\/\//, '')
+    .replace(/^https?:\/\/[^/]+\//, '')
+    .replace(/\.git$/, '')
+    .replace(/\//g, '-');
+
+  const dir = join(reposDir, `${slug}.git`);
+
+  // Inject token into HTTPS URLs for authenticated clone/fetch
+  let authUrl = url;
+  if (opts.token && url.startsWith('https://')) {
+    const parsed = new URL(url);
+    parsed.username = 'x-access-token';
+    parsed.password = opts.token;
+    authUrl = parsed.toString();
+  }
+
+  const gitEnv = { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, timeout: GIT_TIMEOUT };
+
+  let exists = false;
+  try {
+    await access(dir);
+    exists = true;
+  } catch { /* directory doesn't exist */ }
+
+  if (exists) {
+    await run('git', ['-C', dir, 'fetch', '--prune'], gitEnv);
+  } else {
+    await mkdir(reposDir, { recursive: true });
+    await run('git', ['clone', '--bare', authUrl, dir], gitEnv);
+  }
+
+  return dir;
+}
+
+/**
+ * Compute the deterministic workspace path for an agent.
+ *
+ * All agents get a predictable `loreli-{name}` directory under the
+ * workspace root. This convention is shared across factory, orchestrator,
+ * and cleanup code to avoid path coordination bugs.
+ *
+ * @param {string} name - Agent identity name (e.g. 'optimus-0').
+ * @param {string} [root] - Base directory for workspaces (default: ~/.loreli/workspaces).
+ * @returns {string} Absolute path to the agent's workspace.
+ */
+export function pathFor(name, root = DEFAULT_ROOT) {
+  assertSafe(name, 'agent name');
+  return join(root, `loreli-${name}`);
+}
+
+/**
+ * Build MCP JSON config content, optionally injecting agent context env vars.
+ *
+ * When context is provided, the env block enables the agent's MCP server
+ * to hydrate session state on startup without the agent knowing its own
+ * identifiers — eliminating hallucination vectors.
+ *
+ * @param {object} [context] - Agent context for env injection.
+ * @param {string} [context.session] - Session ID.
+ * @param {string} [context.agent] - Agent identity name.
+ * @param {string} [context.repo] - Target repository (owner/name).
+ * @param {object} [opts] - Generation options.
+ * @param {string} [opts.tokenRef] - Host-specific interpolation
+ *   reference for GITHUB_TOKEN. Each MCP host resolves env
+ *   references with its own syntax:
+ *   - Claude Code: `${GITHUB_TOKEN}`
+ *   - Cursor IDE:  `${env:GITHUB_TOKEN}`
+ *   The file only contains a reference — never the literal secret.
+ * @param {string} [opts.envFile] - Path to a `.env` file that the
+ *   MCP host loads at spawn time. Used as a fallback for Cursor
+ *   startup paths where interpolation may not be available. The
+ *   secret lives in the referenced file (inside `.git/`,
+ *   unstageable), not in the JSON config itself.
+ * @returns {string} JSON string for .mcp.json files.
+ */
+export function mcpJson(context, { tokenRef, envFile } = {}) {
+  const entry = { ...ENTRY };
+  if (context?.session) {
+    entry.env = {
+      LORELI_SESSION: context.session,
+      LORELI_AGENT: context.agent,
+      LORELI_REPO: context.repo
+    };
+    if (context.home) entry.env.LORELI_HOME = context.home;
+    if (tokenRef) entry.env.GITHUB_TOKEN = tokenRef;
+  }
+  if (envFile) entry.envFile = envFile;
+  return JSON.stringify({ mcpServers: { loreli: entry } }, null, 2) + '\n';
+}
+
+/**
+ * Build legacy scaffold descriptors when no backends provide them.
+ *
+ * Replicates the hardcoded Claude + Cursor + Codex scaffolding that
+ * prepare() previously contained inline. Used as a backward-compat
+ * fallback when callers don't pass explicit descriptors.
+ *
+ * @param {object} [context] - Agent context for env injection.
+ * @returns {object[]} Array of scaffold descriptors.
+ */
+function legacyDescriptors(context) {
+  const denied = context?.denied ?? [];
+  const dangerousCommands = [
+    ...denied,
+    'git', 'rm', 'mv', 'chmod', 'sed', 'perl', 'tee', 'truncate',
+    'node', 'python', 'python3', 'ruby'
+  ];
+  const unique = [...new Set(dangerousCommands)];
+
+  return [
+    {
+      configs: [{
+        path: '.mcp.json',
+        content: mcpJson(context, context ? { tokenRef: '${GITHUB_TOKEN}' } : {}),
+        marker: 'loreli',
+        format: 'json'
+      }],
+      hooks: [
+        {
+          path: '.claude/settings.local.json',
+          key: 'PreToolUse',
+          entry: {
+            matcher: 'Bash',
+            hooks: [{ type: 'command', command: 'bash "$CLAUDE_PROJECT_DIR/.loreli/deny.sh"' }]
+          },
+          marker: 'deny.sh'
+        },
+        {
+          path: '.claude/settings.local.json',
+          key: 'PreToolUse',
+          entry: {
+            matcher: 'Write|Edit|MultiEdit',
+            hooks: [{ type: 'command', command: 'bash "$CLAUDE_PROJECT_DIR/.loreli/protect.sh"' }]
+          },
+          marker: 'protect.sh'
+        }
+      ],
+      files: []
+    },
+    {
+      configs: [{
+        path: '.cursor/mcp.json',
+        content: mcpJson(context, context ? {
+          envFile: '.git/loreli.env'
+        } : {}),
+        marker: 'loreli',
+        format: 'json'
+      }],
+      hooks: [{
+        path: '.cursor/hooks.json',
+        key: 'beforeShellExecution',
+        entry: { command: '.loreli/deny.sh', matcher: cursorMatcher(unique) },
+        marker: 'deny.sh',
+        defaults: { version: 1 }
+      }],
+      files: context?.token
+        ? [{ path: '.git/loreli.env', content: `GITHUB_TOKEN=${context.token}\n`, mode: 0o600 }]
+        : []
+    },
+    {
+      configs: [{
+        path: '.codex/config.toml',
+        content: codexToml(context),
+        marker: 'mcp_servers.loreli',
+        format: 'toml'
+      }],
+      hooks: [],
+      files: []
+    }
+  ];
+}
+
+/**
+ * Prepare an agent's working directory with MCP configs, hooks, and
+ * security scaffolding.
+ *
+ * When `descriptors` are provided (from `BackendRegistry.scaffoldAll()`),
+ * uses them to determine which config files and hooks to write — no
+ * backend-specific knowledge needed. When omitted, falls back to
+ * built-in legacy descriptors for backward compatibility.
+ *
+ * Shared security scaffolding (deny.sh, protect.sh, secretlintrc,
+ * .gitignore) is always written regardless of descriptors.
+ *
+ * Uses `{ flag: 'wx' }` (exclusive create) when no context is
+ * provided so existing files are never overwritten. When context
+ * is present, overwrites with `'w'` because session identity
+ * changes between runs.
+ *
+ * @param {string} cwd - Absolute path to the agent workspace.
+ * @param {object} [context] - Agent context for env injection.
+ * @param {string} [context.session] - Session ID.
+ * @param {string} [context.agent] - Agent identity name.
+ * @param {string} [context.repo] - Target repository (owner/name).
+ * @param {object[]} [descriptors] - Scaffold descriptors from backends.
+ * @returns {Promise<void>}
+ */
+export async function prepare(cwd, context, descriptors) {
+  await mkdir(cwd, { recursive: true });
+
+  const descs = descriptors ?? legacyDescriptors(context);
+
+  // When context is provided, always overwrite config files because
+  // the session/agent identity changes between runs. Without context,
+  // use wx (exclusive create) to avoid clobbering user-modified configs.
+  const flag = context ? 'w' : 'wx';
+
+  // Read-then-merge .gitignore: preserve existing rules, append loreli
+  // rules only if missing. Prevents destroying the repo's gitignore.
+  const LORELI_MARKER = '.loreli/';
+  const loreligitignore = [
+    '.mcp.json', '.codex/', '.cursor/', '.claude/', '.loreli/',
+    'node_modules/', '.secretlintrc.json'
+  ];
+
+  let existingIgnore = '';
+  try {
+    existingIgnore = await readFile(join(cwd, '.gitignore'), 'utf8');
+  } catch { /* file doesn't exist — will create */ }
+
+  if (!existingIgnore.includes(LORELI_MARKER)) {
+    const block = '\n# loreli scaffolding\n' + loreligitignore.join('\n') + '\n';
+    await writeFile(join(cwd, '.gitignore'), existingIgnore + block);
+  }
+
+  // Generic config write loop — writes each descriptor's configs
+  const writes = [];
+  for (const desc of descs) {
+    for (const cfg of desc.configs ?? []) {
+      const target = join(cwd, cfg.path);
+      const dir = dirname(target);
+      if (dir !== cwd) {
+        writes.push(
+          mkdir(dir, { recursive: true })
+            .then(() => writeFile(target, cfg.content, { flag }))
+        );
+      } else {
+        writes.push(writeFile(target, cfg.content, { flag }));
+      }
+    }
+  }
+
+  // Security scripts and secretlint — always scaffolded
+  const denied = context?.denied ?? [];
+  const secretlintrc = JSON.stringify({
+    rules: [{ id: '@secretlint/secretlint-rule-preset-recommend' }]
+  }, null, 2) + '\n';
+
+  writes.push(
+    writeFile(join(cwd, '.secretlintrc.json'), secretlintrc),
+    mkdir(join(cwd, '.loreli'), { recursive: true })
+      .then(() => Promise.all([
+        writeFile(join(cwd, '.loreli', 'deny.sh'), denyScript(denied), { mode: 0o755 }),
+        writeFile(join(cwd, '.loreli', 'protect.sh'), protectScript(), { mode: 0o755 })
+      ]))
+  );
+
+  // Generic hook merge loop — groups hooks by target file to avoid
+  // race conditions when multiple descriptors write the same file.
+  // Hooks for the same file are chained sequentially; different
+  // files run in parallel.
+  const hooksByPath = new Map();
+  for (const desc of descs) {
+    for (const hook of desc.hooks ?? []) {
+      const target = join(cwd, hook.path);
+      if (!hooksByPath.has(target)) hooksByPath.set(target, []);
+      hooksByPath.get(target).push(hook);
+    }
+  }
+
+  for (const [target, hooks] of hooksByPath) {
+    const dir = dirname(target);
+    let chain = mkdir(dir, { recursive: true });
+    for (const hook of hooks) {
+      chain = chain.then(() => mergeHook(target, hook.key, hook.entry, hook.marker, hook.defaults));
+    }
+    writes.push(chain);
+  }
+
+  const results = await Promise.allSettled(writes);
+
+  // wx throws EEXIST when the file already exists — that's expected.
+  // Any other error is a real problem.
+  for (const result of results) {
+    if (result.status === 'rejected' && result.reason?.code !== 'EEXIST') {
+      throw result.reason;
+    }
+  }
+}
+
+/**
+ * Scaffolding paths that must stay invisible to `git add -A`.
+ *
+ * When a previous run committed these to main, they become tracked.
+ * `.gitignore` cannot prevent `git add -A` from staging modifications
+ * to tracked files. `skip-worktree` tells git to ignore local changes,
+ * so even a raw `git add -A && git commit` never captures config diffs.
+ *
+ * @type {string[]}
+ */
+const SKIP_PATHS = [
+  '.mcp.json', '.cursor/mcp.json', '.codex/config.toml',
+  '.gitignore', '.secretlintrc.json'
+];
+
+/**
+ * Mark scaffolding files as skip-worktree so `git add -A` ignores them.
+ *
+ * Only operates on files that are actually tracked in the index —
+ * untracked files are already covered by `.gitignore`. Silently skips
+ * non-git directories and untracked paths.
+ *
+ * @param {string} cwd - Workspace root (must contain `.git/`).
+ * @returns {Promise<void>}
+ */
+async function shield(cwd) {
+  for (const path of SKIP_PATHS) {
+    try {
+      await run('git', ['-C', cwd, 'update-index', '--skip-worktree', path]);
+    } catch {
+      // File not tracked or not in index — nothing to shield
+    }
+  }
+}
+
+/**
+ * Create a git worktree for an agent.
+ *
+ * Adds a new worktree at the deterministic path for the agent name,
+ * checking out the specified branch. After worktree creation, scaffolds
+ * MCP configs so CLI backends discover Loreli tools on startup.
+ *
+ * When context is provided, MCP config files include agent-specific
+ * env vars (session, identity, repo) so the agent's MCP server can
+ * hydrate state on startup.
+ *
+ * @param {string} repo - Path to the git repository (local bare or checkout).
+ * @param {string} branch - Branch to checkout in the worktree.
+ * @param {string} name - Agent identity name.
+ * @param {string} [root] - Base directory for workspaces.
+ * @param {object} [context] - Agent context for MCP config env injection.
+ * @param {object[]} [descriptors] - Scaffold descriptors from backends.
+ * @returns {Promise<string>} Absolute path to the created worktree.
+ */
+export async function create(repo, branch, name, root = DEFAULT_ROOT, context, descriptors) {
+  const cwd = pathFor(name, root);
+  const marker = join(cwd, '.loreli', 'session');
+
+  // Guard: reuse existing workspace only when it belongs to the current
+  // session. Stale workspaces from previous sessions carry old branches,
+  // commits, and working-tree state that confuse newly spawned agents.
+  try {
+    await access(join(cwd, '.git'));
+    const stored = context?.session
+      ? (await readFile(marker, 'utf8').catch(() => '')).trim()
+      : null;
+
+    if (!context?.session || stored === context.session) {
+      await prepare(cwd, context, descriptors);
+      await shield(cwd);
+      return cwd;
+    }
+    // Session mismatch — stale workspace, fall through to fresh clone
+  } catch {
+    // .git missing or inaccessible — proceed with fresh clone
+  }
+
+  // Remove stale workspace from a previous run. Also attempt worktree
+  // unregistration in case an older version created this as a worktree.
+  try { await run('git', ['-C', repo, 'worktree', 'remove', '--force', cwd]); } catch { /* ok */ }
+  await rm(cwd, { recursive: true, force: true });
+
+  // Clone from the bare mirror instead of creating a worktree.
+  // Worktrees store metadata (refs, HEAD, index) in the parent bare
+  // repo directory. Sandboxed agents (Codex) can only write to their
+  // workspace — git operations that touch refs fail silently, forcing
+  // agents to waste tokens building .git2/.git-local workarounds.
+  // A clone puts .git/ inside the workspace so all git state is local.
+  const cloneArgs = ['clone', '--single-branch'];
+  if (branch && branch !== 'HEAD') cloneArgs.push('--branch', branch);
+  cloneArgs.push(repo, cwd);
+  await run('git', cloneArgs, { timeout: GIT_TIMEOUT });
+
+  // Create a named branch for the agent. A named branch lets agents
+  // commit and push without extra setup — no "HEAD (no branch)" state.
+  const agentBranch = `${name}/work`;
+  await run('git', ['-C', cwd, 'checkout', '-b', agentBranch]);
+
+  // Configure authenticated push URL when context provides credentials.
+  // The clone's origin points to the local bare mirror. Agents need to
+  // push to GitHub, so override origin with the authenticated URL.
+  if (context?.repo && context?.token) {
+    const url = `https://x-access-token:${context.token}@github.com/${context.repo}.git`;
+    await run('git', ['-C', cwd, 'remote', 'set-url', 'origin', url]);
+
+    // Configure a credential helper that reads GITHUB_TOKEN from the
+    // environment. Defense-in-depth: if an agent creates an alternate
+    // git directory (e.g. /tmp/git-dir) without our pre-configured
+    // push URL, git push will still authenticate via this helper.
+    const helper = [
+      '#!/bin/sh',
+      'echo "protocol=https"',
+      'echo "host=github.com"',
+      'echo "username=x-access-token"',
+      'echo "password=$GITHUB_TOKEN"'
+    ].join('\n') + '\n';
+    await mkdir(join(cwd, '.loreli'), { recursive: true });
+    await writeFile(join(cwd, '.loreli', 'git-credential.sh'), helper, { mode: 0o755 });
+    await run('git', ['-C', cwd, 'config', 'credential.helper',
+      `!${join(cwd, '.loreli', 'git-credential.sh')}`]);
+  }
+
+  // Write descriptor files that require .git/ to exist (e.g.
+  // .git/loreli.env for cursor-agent envFile token propagation).
+  // When no descriptors provided, fall back to legacy behavior.
+  const descs = descriptors ?? legacyDescriptors(context);
+  for (const desc of descs) {
+    for (const file of desc.files ?? []) {
+      const target = join(cwd, file.path);
+      const dir = dirname(target);
+      await mkdir(dir, { recursive: true });
+      const opts = file.mode ? { mode: file.mode } : {};
+      await writeFile(target, file.content, opts);
+    }
+  }
+
+  // Persist session marker so subsequent spawns in the same session
+  // reuse this workspace, but a new session triggers a fresh clone.
+  if (context?.session) {
+    await mkdir(join(cwd, '.loreli'), { recursive: true });
+    await writeFile(marker, context.session, 'utf8');
+  }
+
+  await prepare(cwd, context, descriptors);
+  await shield(cwd);
+  return cwd;
+}
+
+/**
+ * Remove an agent's workspace directory and git worktree registration.
+ *
+ * Attempts to remove the git worktree entry first (if the directory
+ * was created via `create()`), then force-removes the directory.
+ * Silently ignores missing directories and non-worktree paths.
+ *
+ * @param {string} name - Agent identity name.
+ * @param {string} [root] - Base directory for workspaces (default: ~/.loreli/workspaces).
+ * @returns {Promise<void>}
+ */
+export async function clean(name, root = DEFAULT_ROOT) {
+  const cwd = pathFor(name, root);
+
+  // Attempt git worktree remove — silently ignore if not a worktree
+  try {
+    await run('git', ['worktree', 'remove', '--force', cwd]);
+  } catch {
+    // Not a worktree or already removed — fall through to rm
+  }
+
+  await rm(cwd, { recursive: true, force: true });
+}
+
+/**
+ * Prune workspaces that do not belong to the current session.
+ *
+ * Reads the `.loreli/session` marker inside each `loreli-*` directory
+ * under the workspace root. Workspaces whose marker does not match
+ * `sessionId` — or that have no marker — are removed via `clean()`.
+ *
+ * Non-loreli directories are left untouched.
+ *
+ * @param {string} sessionId - Current session ID to keep.
+ * @param {string} [root] - Base directory for workspaces.
+ * @returns {Promise<string[]>} Agent names whose workspaces were removed.
+ */
+export async function prune(sessionId, root = DEFAULT_ROOT) {
+  let entries;
+  try {
+    entries = await readdir(root);
+  } catch {
+    return [];
+  }
+
+  const PREFIX = 'loreli-';
+  const pruned = [];
+
+  for (const entry of entries) {
+    if (!entry.startsWith(PREFIX)) continue;
+
+    const name = entry.slice(PREFIX.length);
+    const marker = join(root, entry, '.loreli', 'session');
+
+    let owner = '';
+    try {
+      owner = (await readFile(marker, 'utf8')).trim();
+    } catch {
+      // No marker — legacy or broken workspace
+    }
+
+    if (owner !== sessionId) {
+      await rm(join(root, entry), { recursive: true, force: true });
+      pruned.push(name);
+    }
+  }
+
+  return pruned;
+}
+
+/**
+ * Stage all changes, commit, and push to the remote.
+ *
+ * Designed for MCP tool use — the PR tool calls this before creating
+ * a pull request so agents never need to run shell git commands.
+ * This sidesteps macOS `com.apple.provenance` xattr issues that cause
+ * Codex models to hallucinate permission errors when they see `@` flags
+ * in `ls -la` output and refuse to run `git add`.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @param {string} message - Commit message.
+ * @returns {Promise<{pushed: boolean, sha: string}>} Push result.
+ */
+/**
+ * Reset an agent's workspace branch to the latest remote main.
+ *
+ * After an agent completes work on an issue and its PR is
+ * created, the workspace branch still has the previous issue's
+ * changes. This function fetches the latest remote state and
+ * force-recreates the agent's branch from the configured base, giving the
+ * agent a clean workspace for the next issue.
+ *
+ * When an issue number is provided, the branch is named per-issue
+ * (`name/issue-N`) so each issue gets its own PR branch. This
+ * prevents branch collisions when an agent works on multiple issues
+ * sequentially.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @param {string} name - Agent identity name (used for branch naming).
+ * @param {number} [issue] - Optional issue number for per-issue branch naming.
+ * @returns {Promise<void>}
+ */
+/**
+ * Remove ignored scaffolding files that would block branch checkout.
+ *
+ * `git clean -fd` only removes untracked non-ignored files. Scaffolding
+ * files (written by prepare() and listed in .gitignore) survive the clean.
+ * If a previous agent merged these files into main, `git checkout -B`
+ * fails because the untracked-but-ignored local copies conflict with
+ * the tracked versions on the target branch.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @returns {Promise<void>}
+ */
+async function cleanScaffolding(cwd) {
+  const targets = [
+    '.secretlintrc.json', '.secretlintrc', '.mcp.json', '.gitignore'
+  ];
+  for (const file of targets) {
+    await rm(join(cwd, file), { force: true }).catch(() => {});
+  }
+  const dirs = ['.codex', '.cursor', '.claude', '.loreli'];
+  for (const dir of dirs) {
+    await rm(join(cwd, dir), { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Reset a workspace to a clean state branched from the configured base.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @param {string} name - Agent identity name.
+ * @param {number} [issue] - Issue number for per-issue branches.
+ * @param {string} [base='main'] - Base branch to reset onto (from merge.base config).
+ * @param {object} [opts] - Optional re-scaffolding options.
+ * @param {object} [opts.context] - Agent context for config regeneration.
+ * @param {object[]} [opts.descriptors] - Scaffold descriptors from backends.
+ * @returns {Promise<void>}
+ */
+export async function reset(cwd, name, issue, base = 'main', opts = {}) {
+  // Explicit base ref fetch required: agent workspaces are cloned with
+  // --single-branch, so a bare `fetch origin` only downloads the clone's
+  // tracked branch. When merge.base differs (e.g. 'loreli'), the ref
+  // won't exist locally without an explicit refspec.
+  await run('git', ['-C', cwd, 'fetch', 'origin',
+    `+refs/heads/${base}:refs/remotes/origin/${base}`], { timeout: GIT_TIMEOUT });
+
+  // Discard any uncommitted changes from the previous run
+  await run('git', ['-C', cwd, 'checkout', '--', '.']);
+  try { await run('git', ['-C', cwd, 'clean', '-fd']); } catch { /* ok */ }
+  await cleanScaffolding(cwd);
+
+  // Per-issue branches avoid collisions when an agent handles
+  // multiple issues sequentially — each issue gets its own PR branch.
+  const branch = issue ? `${name}/issue-${issue}` : `${name}/work`;
+  await run('git', ['-C', cwd, 'checkout', '-B', branch, `origin/${base}`]);
+
+  // Keep local base in sync so reviewer agents running
+  // `git diff <base>...` see correct diffs, not stale refs.
+  await run('git', ['-C', cwd, 'branch', '-f', base, `origin/${base}`]);
+
+  await restoreScaffolding(cwd, opts);
+}
+
+/**
+ * Checkout a remote branch in a workspace.
+ *
+ * Fetches the specific branch from origin, discards local changes, and
+ * checks out the given remote branch. Used by the review workflow to
+ * place reviewer agents on the PR's head branch so they can browse
+ * the actual code.
+ *
+ * The explicit branch fetch is required because agent workspaces are
+ * cloned with `--single-branch`, which restricts the default fetch
+ * refspec to only the initial branch. A bare `fetch origin`
+ * would never download PR branches — `git fetch origin <branch>`
+ * bypasses that restriction.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @param {string} branch - Remote branch name (e.g. 'megatron-0/issue-42').
+ * @param {string} [base='main'] - Base branch to keep in sync (from merge.base config).
+ * @param {object} [opts] - Optional re-scaffolding options.
+ * @param {object} [opts.context] - Agent context for config regeneration.
+ * @param {object[]} [opts.descriptors] - Scaffold descriptors from backends.
+ * @returns {Promise<void>}
+ */
+export async function checkout(cwd, branch, base = 'main', opts = {}) {
+  await run('git', ['-C', cwd, 'fetch', 'origin',
+    `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+    `+refs/heads/${base}:refs/remotes/origin/${base}`], { timeout: GIT_TIMEOUT });
+  await run('git', ['-C', cwd, 'checkout', '--', '.']);
+  try { await run('git', ['-C', cwd, 'clean', '-fd']); } catch { /* ok */ }
+  await cleanScaffolding(cwd);
+  await run('git', ['-C', cwd, 'checkout', '-B', branch, `origin/${branch}`]);
+  await run('git', ['-C', cwd, 'branch', '-f', base, `origin/${base}`]);
+
+  await restoreScaffolding(cwd, opts);
+}
+
+/**
+ * Re-create workspace scaffolding after branch transitions when context is available.
+ *
+ * reset()/checkout() delete scaffolding first to avoid untracked-vs-tracked
+ * path conflicts on branch switches. When caller provides agent context,
+ * re-prepare the workspace immediately so CLI-based skills continue to work.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @param {object} [opts] - Re-scaffolding options.
+ * @param {object} [opts.context] - Agent context for generated config env.
+ * @param {object[]} [opts.descriptors] - Scaffold descriptors from backends.
+ * @returns {Promise<void>}
+ */
+async function restoreScaffolding(cwd, opts = {}) {
+  if (opts.context) {
+    await prepare(cwd, opts.context);
+    await shield(cwd);
+    return;
+  }
+
+  if (!opts.descriptors) return;
+  await prepare(cwd, opts.context, opts.descriptors);
+  await shield(cwd);
+}
+
+/**
+ * Check if a workspace has uncommitted or untracked changes.
+ *
+ * Uses `git status --porcelain` — any output means there are changes.
+ * Used to detect uncommitted work in an agent's workspace, e.g.
+ * before branch reset or cleanup.
+ *
+ * @param {string} cwd - Workspace directory path.
+ * @returns {Promise<boolean>} True if there are uncommitted changes.
+ */
+export async function hasChanges(cwd) {
+  const { stdout } = await run('git', ['-C', cwd, 'status', '--porcelain']);
+  return stdout.trim().length > 0;
+}
+
+export async function commitAndPush(cwd, message) {
+  await run('git', ['-C', cwd, 'add', '-A']);
+
+  // Unstage scaffolding files after git add -A. If a previous E2E run
+  // merged these into main, they're tracked and .gitignore can't prevent
+  // `git add -A` from staging modifications. `git reset HEAD` unstages
+  // them so the commit diff ONLY contains agent-authored work — no
+  // deletions, no modifications to config files. This avoids reviewer
+  // agents flagging scaffolding changes as "scope violations."
+  // Legacy root-level patterns (.loreli-prompt-*, .loreli-task-*,
+  // .loreli-mcp-ready) kept for repos where a previous run leaked
+  // these into main. git reset HEAD -- .loreli only covers the
+  // directory, not root-level files with a .loreli- prefix.
+  const scaffolding = [
+    '.mcp.json', '.codex', '.cursor', '.claude', '.loreli', '.gitignore',
+    '.secretlintrc.json', '.secretlintrc',
+    '.loreli-prompt-*', '.loreli-task-*', '.loreli-mcp-ready'
+  ];
+  for (const pattern of scaffolding) {
+    try {
+      await run('git', ['-C', cwd, 'reset', 'HEAD', '--', pattern]);
+    } catch { /* not staged or not tracked — nothing to unstage */ }
+  }
+
+  // Secretlint backstop: scan staged files for secrets before committing.
+  // This is the hard enforcement layer — covers all backends including
+  // Codex which has no IDE-level hook support.
+  // Conditional on secretlint being installed in the workspace.
+  const secretlintBin = join(cwd, 'node_modules', '.bin', 'secretlint');
+  let hasSecretlint = true;
+  try { await access(secretlintBin); } catch { hasSecretlint = false; }
+
+  if (hasSecretlint) {
+    const { stdout: staged } = await run('git', ['-C', cwd, 'diff', '--cached', '--name-only']);
+    if (staged.trim()) {
+      const files = staged.trim().split('\n');
+      try {
+        await run(secretlintBin, files, { cwd });
+      } catch {
+        throw new Error('commitAndPush blocked: secretlint detected secrets in staged files');
+      }
+    }
+  }
+
+  await run('git', ['-C', cwd, 'commit', '-m', message]);
+
+  const { stdout } = await run('git', ['-C', cwd, 'rev-parse', 'HEAD']);
+  const sha = stdout.trim();
+
+  // Push may fail if remote is a local bare mirror (unit tests).
+  // The caller decides whether push failure is fatal.
+  let pushed = false;
+  try {
+    await run('git', ['-C', cwd, 'push', '-u', 'origin', 'HEAD'], { timeout: GIT_TIMEOUT });
+    pushed = true;
+  } catch { /* push failure is non-fatal — caller may retry */ }
+
+  return { pushed, sha };
+}
+
+/**
+ * Run git blame on a specific line and parse porcelain output.
+ *
+ * @param {string} cwd - Working directory (repo clone).
+ * @param {string} file - Relative file path.
+ * @param {number} line - 1-based line number.
+ * @returns {Promise<{sha: string, author: string, date: string, summary: string}>}
+ */
+export async function blame(cwd, file, line) {
+  const { stdout } = await run('git', [
+    '-C', cwd, 'blame', '--porcelain', `-L${line},${line}`, '--', file
+  ]);
+  const lines = stdout.split('\n');
+  const sha = lines[0]?.split(' ')[0] ?? '';
+  let author = '';
+  let date = '';
+  let summary = '';
+  for (const ln of lines) {
+    if (ln.startsWith('author ')) author = ln.slice(7);
+    else if (ln.startsWith('author-time ')) date = new Date(parseInt(ln.slice(12), 10) * 1000).toISOString();
+    else if (ln.startsWith('summary ')) summary = ln.slice(8);
+  }
+  return { sha, author, date, summary };
+}
+
+/**
+ * Run git log for a file and parse commit entries.
+ *
+ * @param {string} cwd - Working directory (repo clone).
+ * @param {string} file - Relative file path.
+ * @param {object} [opts] - Options.
+ * @param {number} [opts.limit=10] - Maximum commits to return.
+ * @returns {Promise<Array<{sha: string, date: string, message: string}>>}
+ */
+export async function gitlog(cwd, file, opts = {}) {
+  const limit = opts.limit ?? 10;
+  const { stdout } = await run('git', [
+    '-C', cwd, 'log', '--follow', `--format=%H %aI %s`, `-n${limit}`, '--', file
+  ]);
+  return stdout.trim().split('\n').filter(Boolean).map(function entry(line) {
+    const first = line.indexOf(' ');
+    const second = line.indexOf(' ', first + 1);
+    return {
+      sha: line.slice(0, first),
+      date: line.slice(first + 1, second),
+      message: line.slice(second + 1)
+    };
+  });
+}