loreli 0.0.0 → 2.0.0

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

@@ -0,0 +1,1163 @@
+import { Identity } from 'loreli/identity';
+import { commitAndPush, pathFor } from 'loreli/workspace';
+import { logger } from 'loreli/log';
+import { mark, excise, has, parse } from 'loreli/marker';
+import { trace, output } from 'loreli/agent';
+import { context } from './agent-context.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const log = logger('github-tools');
+const run = promisify(execFile);
+
+/**
+ * In-memory self-review checkpoints keyed by session/agent.
+ * Requires an explicit preview call before confirm=true can proceed.
+ *
+ * @type {Map<string, {head: string, base: string, at: string}>}
+ */
+const SELF_REVIEW_PENDING = new Map();
+
+/**
+ * Valid actions for the plan tool.
+ *
+ * @type {Set<string>}
+ */
+const PLAN_ACTIONS = new Set(['create', 'revise', 'verdict', 'escalate', 'resolve']);
+
+/**
+ * Valid decisions for the verdict action.
+ *
+ * @type {Set<string>}
+ */
+const DECISIONS = new Set(['approved', 'changes-requested', 'rejected']);
+
+/**
+ * Valid actions for the pr tool.
+ *
+ * @type {Set<string>}
+ */
+const PR_ACTIONS = new Set(['create', 'review']);
+
+/**
+ * Valid review events for the pr tool.
+ *
+ * @type {Set<string>}
+ */
+const EVENTS = new Set(['APPROVE', 'REQUEST_CHANGES']);
+
+/**
+ * Maps review events to the loreli label that should be applied.
+ * Mirrors the plan verdict's label behavior for PRs.
+ *
+ * @type {Record<string, string>}
+ */
+const EVENT_LABELS = {
+  APPROVE: 'loreli:approved',
+  REQUEST_CHANGES: 'loreli:changes-requested'
+};
+
+/**
+ * The inverse label for each event — removed when the new label is
+ * applied so a PR never carries both at the same time.
+ *
+ * @type {Record<string, string>}
+ */
+const EVENT_LABEL_INVERSE = {
+  APPROVE: 'loreli:changes-requested',
+  REQUEST_CHANGES: 'loreli:approved'
+};
+
+
+/**
+ * Capture tmux pane output and build a trace block for the given agent.
+ * Reused across plan, pr, and comment tool actions.
+ *
+ * @param {object} agent - Agent context with identity, paneId.
+ * @param {object} [opts] - Options.
+ * @param {string} [opts.reasoning] - Agent reasoning text.
+ * @param {string} [opts.prefix] - Log prefix for debug messages.
+ * @returns {Promise<string>} Formatted trace block, or empty string.
+ */
+async function captureTrace(agent, opts = {}) {
+  const { reasoning, prefix = 'trace' } = opts;
+  let captured = '';
+  if (agent.paneId) {
+    try {
+      const { Tmux } = await import('loreli/tmux');
+      const tmux = new Tmux();
+      captured = await tmux.capture(agent.paneId);
+      captured = output.clean(captured);
+    } catch (err) { log.debug(`${prefix}: pane capture failed: ${err.message}`); }
+  }
+
+  const usage = captured ? trace.tokens(captured) : null;
+  return trace.format(agent.identity.name, {
+    reasoning,
+    output: captured || undefined,
+    usage,
+    model: agent.identity.model
+  });
+}
+
+/**
+ * Build a stable key for per-agent pending state.
+ *
+ * @param {object} ctx - Execution context.
+ * @returns {string|null} Pending-state key, or null when unavailable.
+ */
+function pendingKey(ctx) {
+  if (!ctx.sessionId || !ctx.agentName) return null;
+  return `${ctx.sessionId}:${ctx.agentName}`;
+}
+
+/**
+ * Truncate long command output for MCP responses.
+ *
+ * @param {string} text - Raw output.
+ * @param {number} [max=4000] - Max output characters.
+ * @returns {string} Truncated output.
+ */
+function clip(text, max = 4000) {
+  if (!text) return '';
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n...[truncated]`;
+}
+
+/**
+ * Determine whether a GitHub API error indicates an existing PR for head/base.
+ *
+ * @param {any} err - Error object from hub.propose().
+ * @returns {boolean} True when the API reports an already-existing PR.
+ */
+function isDuplicatePrError(err) {
+  return err?.status === 422 &&
+    JSON.stringify(err?.response?.data ?? '').includes('already exists');
+}
+
+/**
+ * Determine whether a GitHub API error indicates invalid PR head/base refs.
+ *
+ * @param {any} err - Error object from hub.propose().
+ * @returns {boolean} True when pull request head/base refs are invalid.
+ */
+function isInvalidRefError(err) {
+  if (err?.status !== 422) return false;
+  const errors = err?.response?.data?.errors;
+  if (!Array.isArray(errors)) return false;
+
+  return errors.some(function invalidRef(e) {
+    return e?.resource === 'PullRequest' &&
+      e?.code === 'invalid' &&
+      (e?.field === 'head' || e?.field === 'base');
+  });
+}
+
+/**
+ * Determine whether an API error indicates a missing resource.
+ *
+ * @param {any} err - Error object from hub calls.
+ * @returns {boolean} True when the API response is 404/not found.
+ */
+function isNotFoundError(err) {
+  return err?.status === 404;
+}
+
+/**
+ * Determine whether a branch creation request raced with another creator.
+ *
+ * @param {any} err - Error object from hub.fork().
+ * @returns {boolean} True when the branch already exists remotely.
+ */
+function isBranchExistsError(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(e) {
+    return e?.code === 'already_exists' || e?.message?.toLowerCase?.().includes('already exists');
+  });
+}
+
+/**
+ * Ensure the requested PR base branch exists remotely.
+ * When missing, create it from the repository default branch.
+ *
+ * @param {object} ctx - Execution context with hub.
+ * @param {string} repo - Repository in "owner/name" format.
+ * @param {string} base - Target base branch name.
+ * @returns {Promise<void>}
+ */
+async function ensureBase(ctx, repo, base) {
+  if (typeof ctx?.hub?.branch !== 'function') return;
+  if (typeof ctx?.hub?.repo !== 'function') return;
+
+  try {
+    await ctx.hub.branch(repo, base);
+    return;
+  } catch (err) {
+    if (!isNotFoundError(err)) throw err;
+  }
+
+  if (typeof ctx?.hub?.fork !== 'function') {
+    throw new Error(
+      `Configured merge base "${base}" does not exist and this hub cannot create branches.`
+    );
+  }
+
+  const info = await ctx.hub.repo(repo);
+  const from = info?.default_branch ?? 'main';
+
+  try {
+    await ctx.hub.fork(repo, { name: base, from });
+    log.info(`pr/create: provisioned missing base branch "${base}" from "${from}"`);
+  } catch (err) {
+    if (!isBranchExistsError(err)) throw err;
+    log.info(`pr/create: base branch "${base}" already exists (race), continuing`);
+  }
+
+  await ctx.hub.branch(repo, base);
+}
+
+/**
+ * Run a git command in a workspace and return stdout.
+ * Returns an empty string on failure so preview generation degrades safely.
+ *
+ * @param {string} cwd - Workspace path.
+ * @param {string[]} args - Git args (without `-C`).
+ * @returns {Promise<string>} Trimmed stdout, or empty string on error.
+ */
+async function gitOut(cwd, args) {
+  try {
+    const { stdout } = await run('git', ['-C', cwd, ...args], {
+      maxBuffer: 1024 * 1024 * 4,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    });
+    return stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Build a self-review summary for the current workspace.
+ *
+ * @param {string} cwd - Workspace path.
+ * @param {string} base - Base branch for comparison.
+ * @returns {Promise<string>} Human-readable diff/stat preview.
+ */
+async function preview(cwd, base) {
+  const [status, staged, unstaged, committed] = await Promise.all([
+    gitOut(cwd, ['status', '--short']),
+    gitOut(cwd, ['diff', '--cached', '--stat']),
+    gitOut(cwd, ['diff', '--stat']),
+    gitOut(cwd, ['diff', '--stat', `origin/${base}...HEAD`])
+  ]);
+
+  const lines = ['Self-review preview before PR creation', `Workspace: ${cwd}`, `Base: ${base}`, ''];
+
+  lines.push('## Working tree status');
+  lines.push(status ? `\`\`\`\n${clip(status)}\n\`\`\`` : '_clean_');
+  lines.push('');
+
+  lines.push('## Staged diff stat');
+  lines.push(staged ? `\`\`\`\n${clip(staged)}\n\`\`\`` : '_none_');
+  lines.push('');
+
+  lines.push('## Unstaged diff stat');
+  lines.push(unstaged ? `\`\`\`\n${clip(unstaged)}\n\`\`\`` : '_none_');
+  lines.push('');
+
+  lines.push(`## Branch diff stat (origin/${base}...HEAD)`);
+  lines.push(committed ? `\`\`\`\n${clip(committed)}\n\`\`\`` : '_unavailable_');
+
+  return lines.join('\n');
+}
+
+/**
+ * Run configured pre-PR validation command.
+ *
+ * @param {string} cwd - Workspace path.
+ * @param {string} command - Validation shell command.
+ * @returns {Promise<{ok: boolean, code: number, stdout: string, stderr: string}>}
+ */
+async function validateBeforePr(cwd, command) {
+  try {
+    const { stdout, stderr } = await run('sh', ['-lc', command], {
+      cwd,
+      maxBuffer: 1024 * 1024 * 8,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    });
+    return {
+      ok: true,
+      code: 0,
+      stdout: stdout?.trim() ?? '',
+      stderr: stderr?.trim() ?? ''
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: Number(err?.code ?? 1),
+      stdout: err?.stdout?.trim?.() ?? '',
+      stderr: err?.stderr?.trim?.() ?? ''
+    };
+  }
+}
+
+/**
+ * Agent-facing GitHub interaction tools.
+ *
+ * These tools are called by agents running in tmux panes via their
+ * `.mcp.json` connection to Loreli. Every tool reads repo, identity,
+ * role, and task context from the agent's session — zero identifier
+ * parameters. This eliminates hallucination vectors where an agent
+ * could affect the wrong repo or resource.
+ */
+export default {
+  plan: {
+    title: 'Plan',
+    description: [
+      'Manage plan discussions in the Loreli category. Use this tool for all discussion',
+      'operations — creating plans, revising after feedback, rendering review verdicts,',
+      'or escalating concerns. Your identity, repository, and target discussion are',
+      'resolved automatically from your session.',
+      '',
+      'Actions:',
+      '- "create": Create a new plan discussion. Provide title and body. Your agent stamp and labels are applied automatically. (Planner only)',
+      '- "revise": Submit a revised plan after reviewer feedback. Provide the updated body and a comment explaining your changes. The changes-requested label is removed automatically. (Planner only)',
+      '- "verdict": Render your review decision on a plan discussion. Provide decision ("approved" or "changes-requested") and a comment with your reasoning. The label is applied automatically. (Reviewer only)',
+      '- "escalate": Flag a concern or discovery for the planner. Provide title and body. Any agent role can escalate.',
+      '- "resolve": Close the objective with no work needed. Provide body explaining why. Creates a closed discussion as a visible record. (Planner only)'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          description: 'Operation to perform: "create", "revise", "verdict", "escalate", or "resolve".',
+          enum: ['create', 'revise', 'verdict', 'escalate', 'resolve']
+        },
+        title: { type: 'string', description: 'Discussion title (required for create, escalate).' },
+        body: { type: 'string', description: 'Discussion body or updated body (required for create, revise, escalate).' },
+        comment: { type: 'string', description: 'Comment explaining changes or verdict reasoning (required for revise, verdict).' },
+        decision: { type: 'string', description: 'Review decision: "approved" or "changes-requested" (required for verdict).' },
+        reasoning: { type: 'string', description: 'Summary of your approach, key decisions, and trade-offs. Included as a collapsible trace for human review.' }
+      },
+      required: ['action']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool result.
+     */
+    async exec(args, ctx) {
+      const { action } = args;
+
+      if (!PLAN_ACTIONS.has(action)) {
+        return {
+          content: [{ type: 'text', text: `Unknown action: "${action}". Valid: ${[...PLAN_ACTIONS].join(', ')}` }],
+          isError: true
+        };
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Hub not initialized. Run start first.' }], isError: true };
+      }
+
+      let agent;
+      try {
+        agent = await context(ctx);
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      if (action === 'create') {
+        if (agent.role !== 'planner') {
+          return { content: [{ type: 'text', text: 'create is restricted to planner agents.' }], isError: true };
+        }
+        if (!args.title || !args.body) {
+          return { content: [{ type: 'text', text: 'create requires title and body.' }], isError: true };
+        }
+
+        const cat = await ctx.hub.category(agent.repo, 'Loreli');
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        const labels = [...(agent.identity.labels?.(agent.role) ?? ['loreli'])];
+
+        const feedbackData = parse(args.body, 'feedback');
+        if (feedbackData?.category) {
+          labels.push(`loreli:feedback:${feedbackData.category}`);
+        }
+
+        let body = args.body;
+        const traceBlock = await captureTrace(agent, { reasoning: args.reasoning, prefix: 'plan/create' });
+        if (traceBlock) body = `${body}\n\n${traceBlock}`;
+
+        const disc = await scoped.discuss(agent.repo, {
+          title: args.title,
+          body,
+          categoryId: cat.id,
+          repositoryId: cat.repositoryId,
+          labels
+        });
+
+        log.info(`plan/create: "${args.title}" → discussion #${disc.number}`);
+        return {
+          content: [{ type: 'text', text: `Created plan discussion #${disc.number}: ${args.title}\nURL: ${disc.url}` }]
+        };
+      }
+
+      if (action === 'revise') {
+        if (agent.role !== 'planner') {
+          return { content: [{ type: 'text', text: 'revise is restricted to planner agents.' }], isError: true };
+        }
+        if (!args.body || !args.comment) {
+          return { content: [{ type: 'text', text: 'revise requires body and comment.' }], isError: true };
+        }
+
+        const discussionId = agent.task?.discussionId;
+        if (!discussionId) {
+          return { content: [{ type: 'text', text: 'No discussion assigned. Task context missing discussionId.' }], isError: true };
+        }
+
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        let body = args.body;
+        const traceBlock = await captureTrace(agent, { reasoning: args.reasoning, prefix: 'plan/revise' });
+        if (traceBlock) body = `${body}\n\n${traceBlock}`;
+        await scoped.updateDiscussion(discussionId, { body });
+        await ctx.hub.removeDiscussionLabels(agent.repo, discussionId, ['loreli:changes-requested']);
+        await scoped.discussionComment(discussionId, args.comment);
+
+        log.info(`plan/revise: discussion ${discussionId} updated`);
+        return {
+          content: [{ type: 'text', text: `Revised plan discussion. Changes-requested label removed. Comment posted.` }]
+        };
+      }
+
+      if (action === 'verdict') {
+        if (agent.role !== 'reviewer') {
+          return { content: [{ type: 'text', text: 'verdict is restricted to reviewer agents.' }], isError: true };
+        }
+        if (!args.decision || !args.comment) {
+          return { content: [{ type: 'text', text: 'verdict requires decision and comment.' }], isError: true };
+        }
+
+        if (!DECISIONS.has(args.decision)) {
+          return {
+            content: [{ type: 'text', text: `Invalid decision: "${args.decision}". Valid: ${[...DECISIONS].join(', ')}` }],
+            isError: true
+          };
+        }
+
+        const discussionId = agent.task?.discussionId;
+        if (!discussionId) {
+          return { content: [{ type: 'text', text: 'No discussion assigned. Task context missing discussionId.' }], isError: true };
+        }
+
+        // Verify this reviewer is the one who claimed the discussion.
+        // Prevents agents dispatched through degraded fallback paths
+        // from overriding the original claimer's review.
+        const discNumber = agent.task?.discussion;
+        if (discNumber && ctx.hub.discussion) {
+          try {
+            const disc = await ctx.hub.discussion(agent.repo, discNumber);
+            const claimComment = disc.comments?.findLast(function isClaim(c) { return has(c.body, 'review-claim'); });
+            const claimedBy = parse(claimComment?.body, 'review-claim')?.agent;
+            if (claimedBy && claimedBy !== agent.identity.name) {
+              return {
+                content: [{ type: 'text', text: `Verdict rejected: discussion claimed by ${claimedBy}, not ${agent.identity.name}.` }],
+                isError: true
+              };
+            }
+          } catch (err) {
+            log.warn(`plan/verdict: claim check failed — ${err.message}`);
+          }
+        }
+
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        let comment = args.comment;
+        let feedbackTag = '';
+        let feedbackLabel = '';
+
+        if (args.decision === 'changes-requested') {
+          try {
+            const { classify } = await import('loreli/knowledge');
+            const { category, confidence } = await classify(args.comment, {
+              backends: ctx.backendRegistry ?? ctx.orchestrator?.backendRegistry,
+              config: ctx.config ?? ctx.orchestrator?.cfg
+            });
+            if (confidence > 0) {
+              const provider = agent.identity?.provider ?? 'unknown';
+              feedbackTag = mark('feedback', {
+                category,
+                confidence: confidence.toFixed(2),
+                provider,
+                source: 'plan'
+              });
+              feedbackLabel = `${category} (${confidence.toFixed(2)})`;
+            }
+          } catch (err) {
+            log.debug(`plan/verdict: feedback classification failed: ${err.message}`);
+          }
+        }
+
+        if (feedbackTag) comment = `${comment}\n\n${feedbackTag}`;
+        const traceBlock = await captureTrace(agent, { reasoning: args.reasoning, prefix: 'plan/verdict' });
+        if (traceBlock) comment = `${comment}\n\n${traceBlock}`;
+
+        await scoped.discussionComment(discussionId, comment);
+        await ctx.hub.applyDiscussionLabels(agent.repo, discussionId, [`loreli:${args.decision}`]);
+        if (feedbackLabel) log.debug(`plan/verdict: classified feedback as ${feedbackLabel}`);
+
+        // Rejected discussions are terminal — close immediately so
+        // revise() and promote() skip them without further processing.
+        if (args.decision === 'rejected') {
+          try {
+            await ctx.hub.closeDiscussion(discussionId);
+          } catch (err) { log.warn(`plan/verdict: close failed for rejected discussion: ${err.message}`); }
+        }
+
+        log.info(`plan/verdict: discussion ${discussionId} — ${args.decision}`);
+        return {
+          content: [{ type: 'text', text: `Verdict: ${args.decision}. Label applied and comment posted.` }]
+        };
+      }
+
+      if (action === 'escalate') {
+        if (!args.title || !args.body) {
+          return { content: [{ type: 'text', text: 'escalate requires title and body.' }], isError: true };
+        }
+
+        const cat = await ctx.hub.category(agent.repo, 'Loreli');
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+
+        const disc = await scoped.discuss(agent.repo, {
+          title: args.title,
+          body: args.body,
+          categoryId: cat.id,
+          repositoryId: cat.repositoryId
+        });
+
+        log.info(`plan/escalate: "${args.title}" → discussion #${disc.number}`);
+        return {
+          content: [{ type: 'text', text: `Escalated: "${args.title}" created as discussion #${disc.number}.` }]
+        };
+      }
+
+      if (action === 'resolve') {
+        if (agent.role !== 'planner') {
+          return { content: [{ type: 'text', text: 'resolve is restricted to planner agents.' }], isError: true };
+        }
+        if (!args.body) {
+          return { content: [{ type: 'text', text: 'resolve requires body explaining why no work is needed.' }], isError: true };
+        }
+
+        const cat = await ctx.hub.category(agent.repo, 'Loreli');
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        const labels = agent.identity.labels?.(agent.role) ?? ['loreli'];
+
+        const disc = await scoped.discuss(agent.repo, {
+          title: args.title ?? 'Objective resolved — no work needed',
+          body: args.body,
+          categoryId: cat.id,
+          repositoryId: cat.repositoryId,
+          labels: [...labels, 'loreli:resolved']
+        });
+
+        try {
+          await ctx.hub.ensure(agent.repo, [
+            { name: 'loreli:resolved', color: '0e8a16', description: 'Objective resolved without work' }
+          ]);
+          await ctx.hub.closeDiscussion(disc.id);
+        } catch (err) { log.warn(`plan/resolve: close failed for discussion #${disc.number}: ${err.message}`); }
+
+        log.info(`plan/resolve: discussion #${disc.number} — no work needed`);
+        return {
+          content: [{ type: 'text', text: `Resolved: discussion #${disc.number} created and closed. No work needed.` }]
+        };
+      }
+    }
+  },
+
+  pr: {
+    title: 'Pull Request',
+    description: [
+      'Manage pull requests. Use this tool to create PRs after implementing work or to',
+      'submit reviews on PRs assigned to you. Your identity, repository, and target PR',
+      'are resolved automatically from your session.',
+      '',
+      'Actions:',
+      '- "create": Open a pull request for your work. Provide title, body, head branch, and optionally base branch (defaults to merge.base from config). Include reasoning to document your approach and decisions. When pr.selfReview.enabled is true, call create once to review diff/stat output, then call again with confirm=true to proceed. When pr.validation.command is configured, Loreli runs it and blocks PR creation on failure. Your claimed issue is auto-referenced with "Closes #N". Your agent stamp and identity labels are applied automatically. (Action only)',
+      '- "review": Submit your review on the assigned PR. Provide event ("APPROVE" or "REQUEST_CHANGES") and body with your assessment. Include reasoning to document how you evaluated the code. Your agent stamp is applied automatically. (Reviewer only)'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          description: 'Operation to perform: "create" or "review".',
+          enum: ['create', 'review']
+        },
+        title: { type: 'string', description: 'PR title (required for create).' },
+        body: { type: 'string', description: 'PR body or review body (required for both).' },
+        head: { type: 'string', description: 'Head branch name (required for create).' },
+        base: { type: 'string', description: 'Base branch name (optional for create, defaults to merge.base from config).' },
+        confirm: { type: 'boolean', description: 'Self-review confirmation flag for create when pr.selfReview.enabled is true.' },
+        event: { type: 'string', description: 'Review event: "APPROVE" or "REQUEST_CHANGES" (required for review).' },
+        reasoning: { type: 'string', description: 'Summary of your approach, key decisions, and trade-offs. Included as a collapsible trace in the PR body or review for human review.' }
+      },
+      required: ['action']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool result.
+     */
+    async exec(args, ctx) {
+      const { action } = args;
+
+      if (!PR_ACTIONS.has(action)) {
+        return {
+          content: [{ type: 'text', text: `Unknown action: "${action}". Valid: ${[...PR_ACTIONS].join(', ')}` }],
+          isError: true
+        };
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Hub not initialized. Run start first.' }], isError: true };
+      }
+
+      let agent;
+      try {
+        agent = await context(ctx);
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      if (action === 'create') {
+        if (agent.role !== 'action') {
+          return { content: [{ type: 'text', text: 'create is restricted to action agents.' }], isError: true };
+        }
+        if (!args.title || !args.body || !args.head) {
+          return { content: [{ type: 'text', text: 'create requires title, body, and head.' }], isError: true };
+        }
+
+        const base = args.base ?? ctx.config?.get?.('merge.base') ?? 'main';
+        const validationRaw = ctx.config?.get?.('pr.validation.command');
+        const validation = typeof validationRaw === 'string' ? validationRaw.trim() : '';
+        const selfReviewEnabled = ctx.config?.get?.('pr.selfReview.enabled') ?? false;
+
+        const home = ctx.home ?? process.env.LORELI_HOME;
+        const wsRoot = home ? `${home}/workspaces` : undefined;
+        const cwd = pathFor(ctx.agentName, wsRoot);
+        const key = pendingKey(ctx);
+
+        if (selfReviewEnabled) {
+          if (!args.confirm) {
+            if (key) {
+              SELF_REVIEW_PENDING.set(key, {
+                head: args.head,
+                base,
+                at: new Date().toISOString()
+              });
+            }
+            const summary = await preview(cwd, base);
+            return {
+              content: [{
+                type: 'text',
+                text: [
+                  summary,
+                  '',
+                  'Self-review is required before PR creation.',
+                  'Re-run pr/create with confirm=true after reviewing this summary.'
+                ].join('\n')
+              }]
+            };
+          }
+
+          const pending = key ? SELF_REVIEW_PENDING.get(key) : null;
+          if (!pending || pending.head !== args.head || pending.base !== base) {
+            return {
+              content: [{
+                type: 'text',
+                text: 'Self-review confirmation missing or stale. Call pr/create once without confirm, review the diff/stat output, then call again with confirm=true.'
+              }],
+              isError: true
+            };
+          }
+        }
+
+        if (validation) {
+          const check = await validateBeforePr(cwd, validation);
+          if (!check.ok) {
+            if (key) SELF_REVIEW_PENDING.delete(key);
+            const details = [check.stdout, check.stderr].filter(Boolean).join('\n');
+            return {
+              content: [{
+                type: 'text',
+                text: [
+                  `PR creation blocked: pre-PR validation failed.`,
+                  `Command: ${validation}`,
+                  `Exit code: ${check.code}`,
+                  details ? `Output:\n\`\`\`\n${clip(details)}\n\`\`\`` : 'Output: (none)'
+                ].join('\n')
+              }],
+              isError: true
+            };
+          }
+        }
+
+        // Auto-commit and push workspace changes before creating the PR.
+        // Codex agents on macOS see `@` xattr flags in `ls -la` output
+        // and hallucinate a permission error — they never run `git add`,
+        // wasting their token budget investigating .git/ internals.
+        // By handling git operations server-side, the agent only needs
+        // to create files and call this tool.
+        try {
+          const result = await commitAndPush(cwd, args.title);
+          log.info(`pr/create: auto-committed ${result.sha?.slice(0, 7)} and pushed=${result.pushed}`);
+        } catch (err) {
+          log.warn(`pr/create: auto-commit failed (agent may have committed manually): ${err.message}`);
+        }
+
+        let body = args.body;
+        if (agent.issue) {
+          body = `Closes #${agent.issue}\n\n${body}`;
+        }
+
+        const traceBlock = await captureTrace(agent, { reasoning: args.reasoning, prefix: 'pr/create' });
+        if (traceBlock) body = `${body}\n\n${traceBlock}`;
+
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        const labels = agent.identity.labels?.(agent.role) ?? ['loreli'];
+
+        let pr;
+        let updated = false;
+        let head = args.head;
+        let targetBase = base;
+
+        await ensureBase(ctx, agent.repo, targetBase);
+
+        /**
+         * Build PR propose payload for the current target refs.
+         *
+         * @param {string} nextHead - Head branch.
+         * @param {string} nextBase - Base branch.
+         * @returns {{title: string, body: string, head: string, base: string, labels: string[]}}
+         */
+        function payload(nextHead, nextBase) {
+          return {
+            title: args.title,
+            body,
+            head: nextHead,
+            base: nextBase,
+            labels
+          };
+        }
+
+        try {
+          pr = await scoped.propose(agent.repo, payload(head, targetBase));
+        } catch (err) {
+          let failure = err;
+
+          if (isInvalidRefError(failure)) {
+            const errors = failure?.response?.data?.errors ?? [];
+            let retryHead = head;
+            let retry = false;
+
+            const headInvalid = Array.isArray(errors) &&
+              errors.some(function invalidHead(e) { return e?.field === 'head' && e?.code === 'invalid'; });
+            const baseInvalid = Array.isArray(errors) &&
+              errors.some(function invalidBase(e) { return e?.field === 'base' && e?.code === 'invalid'; });
+
+            if (headInvalid) {
+              const current = await gitOut(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+              if (current && current !== head) {
+                retryHead = current;
+                retry = true;
+              }
+            }
+
+            if (baseInvalid) {
+              await ensureBase(ctx, agent.repo, targetBase);
+              retry = true;
+            }
+
+            if (retry) {
+              log.warn(
+                `pr/create: retrying with recovered refs (head: ${head} -> ${retryHead}, base: ${targetBase})`
+              );
+              head = retryHead;
+              try {
+                pr = await scoped.propose(agent.repo, payload(head, targetBase));
+              } catch (retryErr) {
+                failure = retryErr;
+              }
+            }
+          }
+
+          if (!pr) {
+            const duplicate = isDuplicatePrError(failure);
+            if (!duplicate) throw failure;
+
+            const heads = [...new Set([head, args.head])];
+            log.info(`pr/create: PR already exists for ${heads.join(' | ')}, updating`);
+            const open = await ctx.hub.pulls(agent.repo);
+            const existing = open.find(function match(p) { return heads.includes(p.head); });
+            if (!existing) throw failure;
+
+            await ctx.hub.update(agent.repo, existing.number, { title: args.title, body });
+            pr = existing;
+            updated = true;
+          }
+        }
+
+        // Persist the PR number in the agent's task so subsequent
+        // comment tool calls target the PR instead of the issue.
+        if (ctx.sessionId && ctx.storage && ctx.agentName) {
+          try {
+            const session = await ctx.storage.load(ctx.sessionId, ctx.agentName);
+            if (session?.task) {
+              session.task.pr = pr.number;
+              await ctx.storage.save(ctx.sessionId, ctx.agentName, session);
+            }
+          } catch (err) { log.debug(`pr/create: task update failed: ${err.message}`); }
+        }
+
+        if (key) SELF_REVIEW_PENDING.delete(key);
+
+        const verb = updated ? 'Updated' : 'Created';
+        log.info(`pr/${verb.toLowerCase()}: "${args.title}" → PR #${pr.number}`);
+        return {
+          content: [{ type: 'text', text: `${verb} PR #${pr.number}: ${args.title}\nURL: ${pr.url}` }]
+        };
+      }
+
+      if (action === 'review') {
+        if (agent.role !== 'reviewer') {
+          return { content: [{ type: 'text', text: 'review is restricted to reviewer agents.' }], isError: true };
+        }
+        if (!args.event || !args.body) {
+          return { content: [{ type: 'text', text: 'review requires event and body.' }], isError: true };
+        }
+
+        if (!EVENTS.has(args.event)) {
+          return {
+            content: [{ type: 'text', text: `Invalid event: "${args.event}". Valid: ${[...EVENTS].join(', ')}` }],
+            isError: true
+          };
+        }
+
+        const prNum = agent.task?.pr;
+        if (!prNum) {
+          return { content: [{ type: 'text', text: 'No PR assigned. Task context missing pr number.' }], isError: true };
+        }
+
+        let reviewBody = args.body;
+        const traceBlock = await captureTrace(agent, { reasoning: args.reasoning, prefix: 'pr/review' });
+        if (traceBlock) reviewBody = `${reviewBody}\n\n${traceBlock}`;
+
+        const scoped = ctx.hub.as(agent.identity, agent.role);
+        await scoped.review(agent.repo, prNum, { event: args.event, body: reviewBody });
+
+        // Apply verdict label — mirrors plan verdict's labeling behavior.
+        // Remove the inverse label first so a PR never carries both
+        // loreli:approved and loreli:changes-requested simultaneously.
+        const addLabel = EVENT_LABELS[args.event];
+        const removeLabel = EVENT_LABEL_INVERSE[args.event];
+        if (addLabel) {
+          if (removeLabel) {
+            try { await ctx.hub.unlabel(agent.repo, prNum, removeLabel); }
+            catch (err) { log.debug(`pr/review: unlabel ${removeLabel} failed: ${err.message}`); }
+          }
+          try { await ctx.hub.label(agent.repo, prNum, [addLabel]); }
+          catch (err) { log.warn(`pr/review: label ${addLabel} failed: ${err.message}`); }
+        }
+
+        log.info(`pr/review: PR #${prNum} — ${args.event}`);
+        return {
+          content: [{ type: 'text', text: `Review submitted on PR #${prNum}: ${args.event}. Label applied.` }]
+        };
+      }
+    }
+  },
+
+  comment: {
+    title: 'Comment',
+    description: [
+      'Post a comment on your current work item. When a PR exists in your session,',
+      'the comment targets the PR — once a PR is open, all conversation belongs there.',
+      'Before a PR is created, comments target the claimed issue. Use this to communicate',
+      'progress, notify reviewers that changes are addressed, or add context.',
+      'Provide only the comment body — the target is resolved from your session and your',
+      'agent stamp is applied automatically.',
+      '',
+      'Set claim=true to claim the current issue. When claim is true, the body is ignored —',
+      'a themed claim message with a machine-readable marker is posted on the issue.',
+      '',
+      'Set risk=true for a risk assessment verdict. Requires level: LOW, MEDIUM, or CRITICAL.',
+      '',
+      'Set abandon=true to abandon the current issue as impossible. Requires reason.',
+      'Posts a stamped abandon comment, applies loreli:abandoned + loreli:needs-attention,',
+      'and closes the issue. Use only when the issue is fundamentally impossible — not for',
+      '"this is hard" or "I need more time."'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        body: { type: 'string', description: 'Comment body text (ignored when claim=true or abandon=true).' },
+        claim: { type: 'boolean', description: 'Post a claim comment instead of a freeform comment.' },
+        risk: { type: 'boolean', description: 'If true, this is a risk assessment verdict. Requires level.' },
+        level: { type: 'string', enum: ['LOW', 'MEDIUM', 'CRITICAL'], description: 'Risk level (required when risk is true).' },
+        abandon: { type: 'boolean', description: 'Abandon the current issue as impossible. Requires reason.' },
+        reason: { type: 'string', description: 'Explanation of why the issue is impossible (required when abandon=true).' }
+      },
+      required: []
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool result.
+     */
+    async exec(args, ctx) {
+      if (!args.claim && !args.abandon && !args.body) {
+        return { content: [{ type: 'text', text: 'body is required (or set claim=true / abandon=true).' }], isError: true };
+      }
+
+      if (args.abandon && !args.reason) {
+        return { content: [{ type: 'text', text: 'abandon requires reason.' }], isError: true };
+      }
+
+      if (args.risk) {
+        const level = args.level?.toUpperCase();
+        if (!['LOW', 'MEDIUM', 'CRITICAL'].includes(level)) {
+          return { content: [{ type: 'text', text: 'risk requires level: LOW, MEDIUM, or CRITICAL.' }], isError: true };
+        }
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Hub not initialized. Run start first.' }], isError: true };
+      }
+
+      let agent;
+      try {
+        agent = await context(ctx);
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      const scoped = ctx.hub.as(agent.identity, agent.role);
+
+      if (args.abandon) {
+        const issueNum = agent.issue;
+        if (!issueNum) {
+          return { content: [{ type: 'text', text: 'No issue to abandon. Agent has no claimed issue in session.' }], isError: true };
+        }
+
+        const abandonMarker = mark('abandon', { agent: agent.identity.name, reason: args.reason });
+        const visible = `**Abandoned** by \`${agent.identity.name}\` — ${args.reason}`;
+        await scoped.comment(agent.repo, issueNum, `${abandonMarker}\n${visible}`);
+
+        const labels = ['loreli:abandoned', 'loreli:needs-attention'];
+        try {
+          await ctx.hub.ensure(agent.repo, [
+            { name: 'loreli:abandoned', color: 'b60205', description: 'Issue abandoned by agent as impossible' },
+            { name: 'loreli:needs-attention', color: 'e11d48', description: 'Requires human attention' }
+          ]);
+          await ctx.hub.label(agent.repo, issueNum, labels);
+        } catch (err) { log.warn(`abandon: labeling failed for #${issueNum}: ${err.message}`); }
+
+        try {
+          await ctx.hub.update(agent.repo, issueNum, { state: 'closed' });
+        } catch (err) { log.warn(`abandon: close failed for #${issueNum}: ${err.message}`); }
+
+        // Mention configured reviewers so humans are notified
+        const reviewers = ctx.config?.get?.('reviewers') ?? [];
+        if (reviewers.length) {
+          const mentions = reviewers.map(function mention(r) { return `@${r}`; }).join(' ');
+          try {
+            await scoped.comment(agent.repo, issueNum, `${mentions} This issue was abandoned by the action agent. Please review.`);
+          } catch (err) { log.warn(`abandon: reviewer mention failed for #${issueNum}: ${err.message}`); }
+        }
+
+        log.info(`abandon: #${issueNum} by ${agent.identity.name} — ${args.reason}`);
+        return { content: [{ type: 'text', text: `Abandoned #${issueNum}. Issue closed with loreli:abandoned + loreli:needs-attention.` }] };
+      }
+
+      // Claims always target the issue — that is the resource being claimed.
+      if (args.claim) {
+        const issueNum = agent.issue;
+        if (!issueNum) {
+          return { content: [{ type: 'text', text: 'No issue to claim. Agent has no claimed issue in session.' }], isError: true };
+        }
+        const marker = mark('claim', { agent: agent.identity.name });
+        const visible = agent.identity.claim?.() ?? `Claimed by **${agent.identity.name}**`;
+        await scoped.comment(agent.repo, issueNum, `${marker}\n${visible}`);
+        log.info(`claim: #${issueNum} by ${agent.identity.name} on ${agent.repo}`);
+        return { content: [{ type: 'text', text: `Claimed #${issueNum}.` }] };
+      }
+
+      // Regular comments prefer the PR when one exists — once a PR is
+      // open, all conversation belongs there (review feedback, re-review
+      // requests, progress updates). Fall back to the issue pre-PR.
+      const number = agent.task?.pr ?? agent.issue;
+      if (!number) {
+        return {
+          content: [{ type: 'text', text: 'No work item assigned. Neither claimed issue nor PR found in session.' }],
+          isError: true
+        };
+      }
+
+      let body = args.body;
+      if (args.risk) {
+        const level = args.level?.toUpperCase();
+        body = `${mark('risk', { level })}\n${body}`;
+      }
+      if (args.risk) {
+        const traceBlock = await captureTrace(agent, { prefix: 'comment/risk' });
+        if (traceBlock) body = `${body}\n\n${traceBlock}`;
+      }
+
+      await scoped.comment(agent.repo, number, body);
+
+      // Apply a filterable risk label when posting a risk verdict
+      if (args.risk) {
+        const level = args.level?.toUpperCase();
+        const label = `loreli:${level.toLowerCase()}-risk`;
+        const color = { LOW: '0e8a16', MEDIUM: 'fbca04', CRITICAL: 'e11d48' }[level];
+        try {
+          await ctx.hub.ensure(agent.repo, [{ name: label, color, description: `Risk: ${level}` }]);
+          await ctx.hub.label(agent.repo, number, [label]);
+        } catch (err) {
+          log.warn(`comment: failed to apply risk label ${label}: ${err.message}`);
+        }
+      }
+
+      log.info(`comment: #${number} on ${agent.repo}`);
+      return {
+        content: [{ type: 'text', text: `Comment posted on #${number}.` }]
+      };
+    }
+  },
+
+  read: {
+    title: 'Read',
+    description: [
+      'Read any issue, pull request, or discussion by number. Use this to look up',
+      'acceptance criteria, review linked issues, understand PR context, or read',
+      'discussion plans. Returns the title, body, state, labels, and optionally',
+      'all comments for full context. Your repository is resolved from your session.',
+      '',
+      'Works with any GitHub item number — the tool automatically detects whether',
+      'it is an issue, pull request, or discussion.'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        number: {
+          type: 'number',
+          description: 'The issue, PR, or discussion number to read.'
+        },
+        comments: {
+          type: 'boolean',
+          description: 'Include comments for full context. Defaults to true.'
+        }
+      },
+      required: ['number']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {number} args.number - Item number to read.
+     * @param {boolean} [args.comments=true] - Include comments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool result.
+     */
+    async exec(args, ctx) {
+      if (!args.number) {
+        return { content: [{ type: 'text', text: 'number is required.' }], isError: true };
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Hub not initialized. Run start first.' }], isError: true };
+      }
+
+      let agent;
+      try {
+        agent = await context(ctx);
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      const num = args.number;
+      const includeComments = args.comments !== false;
+
+      // GitHub uses unified numbering for issues and PRs — the issues
+      // API returns both. Discussions use a separate sequence and require
+      // the GraphQL endpoint, so we fall back to that on 404.
+      try {
+        const item = await ctx.hub.issue(agent.repo, num);
+        const itemBody = excise(item.body, 'trace') ?? item.body;
+        const lines = [
+          `# #${item.number}: ${item.title}`,
+          `**State**: ${item.state} | **Author**: ${item.author}`,
+          item.labels.length ? `**Labels**: ${item.labels.join(', ')}` : '',
+          '',
+          itemBody || '*(no body)*'
+        ];
+
+        if (includeComments) {
+          const comments = await ctx.hub.comments(agent.repo, num);
+          if (comments.length) {
+            lines.push('', '---', '## Comments', '');
+            for (const c of comments) {
+              lines.push(`**@${c.author}** (${c.created}):`);
+              lines.push(c.body);
+              lines.push('');
+            }
+          }
+        }
+
+        log.info(`read: issue/PR #${num} on ${agent.repo}`);
+        return { content: [{ type: 'text', text: lines.filter(Boolean).join('\n') }] };
+      } catch {
+        // Not an issue/PR — try discussion
+      }
+
+      try {
+        const disc = await ctx.hub.discussion(agent.repo, num);
+        const discBody = excise(disc.body, 'trace') ?? disc.body;
+        const lines = [
+          `# Discussion #${disc.number}: ${disc.title}`,
+          `**Author**: ${disc.author} | **Closed**: ${disc.closed}`,
+          disc.labels.length ? `**Labels**: ${disc.labels.join(', ')}` : '',
+          '',
+          discBody || '*(no body)*'
+        ];
+
+        // Discussions already include comments from the GraphQL query
+        if (includeComments && disc.comments?.length) {
+          lines.push('', '---', '## Comments', '');
+          for (const c of disc.comments) {
+            lines.push(`**@${c.author}** (${c.created}):`);
+            lines.push(c.body);
+            lines.push('');
+          }
+        }
+
+        log.info(`read: discussion #${num} on ${agent.repo}`);
+        return { content: [{ type: 'text', text: lines.filter(Boolean).join('\n') }] };
+      } catch {
+        return {
+          content: [{ type: 'text', text: `Item #${num} not found in ${agent.repo}. It may not exist or may be inaccessible.` }],
+          isError: true
+        };
+      }
+    }
+  }
+};