ralph-hero-mcp-server 2.5.140 → 2.5.149

package/dist/index.js

@@ -31,6 +31,7 @@ import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
 import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 import { registerActivityTools } from "./tools/activity-tools.js";
+import { registerDelegationTools } from "./tools/delegation-tools.js";
 import { registerTrendsTools } from "./tools/trends-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
@@ -445,6 +446,8 @@ async function main() {
     registerPlanGraphTools(server, client);
     // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
     registerActivityTools(server);
+    // Delegation telemetry reader (delegation_stats tool — pure filesystem, no GitHub client)
+    registerDelegationTools(server);
     // Trends tools (capture_snapshot — JSONL persistence under ~/.ralph-hero/snapshots/)
     registerTrendsTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)

package/dist/lib/debug-issue-shape.js

@@ -0,0 +1,202 @@
+/**
+ * Issue body + comment body builders for `ralph_hero__collate_debug` Phase 3b.
+ *
+ * Each `SignatureGroup` returned by `groupSpansBySignature` becomes either:
+ *   - a fresh GitHub issue (when no existing `debug-auto` issue carries the
+ *     same hash within the dedup window), or
+ *   - a comment on an existing issue (occurrence-update).
+ *
+ * The body MUST include a machine-parseable hash marker on its own line —
+ * `**Hash**: \`<8-char-hash>\`` — because dedup in Phase 3b matches on this
+ * exact line via GitHub's code-search index.
+ *
+ * Token-shaped values are scrubbed from every emitted field. The regex set
+ * mirrors `redactTokenAttributes` in `telemetry.ts`: GitHub tokens
+ * (`^gh[ps]_`), basic-auth headers, and any attribute key ending in
+ * `_TOKEN` are replaced with `[REDACTED]`.
+ */
+// ---------------------------------------------------------------------------
+// Token redaction (kept local to avoid cross-module coupling at runtime; the
+// shape mirrors telemetry.ts:redactTokenAttributes for consistency)
+// ---------------------------------------------------------------------------
+const GH_TOKEN_VALUE_RE = /\bgh[psour]_[A-Za-z0-9_]{16,}\b/g;
+const TOKEN_KEY_RE = /(_TOKEN|authorization)$/i;
+const BASIC_AUTH_RE = /\bBasic\s+[A-Za-z0-9+/=]{8,}\b/g;
+/**
+ * Scrub token-shaped substrings from a free-form string. Used for error
+ * messages and serialised metadata before they land in an issue body.
+ */
+export function scrubTokensFromString(input) {
+    if (!input)
+        return input;
+    return input.replace(GH_TOKEN_VALUE_RE, "[REDACTED]").replace(BASIC_AUTH_RE, "Basic [REDACTED]");
+}
+/**
+ * Scrub token-shaped values from a plain attribute bag. Keys matching
+ * `_TOKEN` or `authorization` (case-insensitive) are replaced with
+ * `[REDACTED]`; values matching the GitHub token regex are scrubbed too.
+ *
+ * The result is a shallow copy — callers can serialise it without mutating
+ * the input. Nested objects are stringified before scrubbing to keep the
+ * function flat and predictable.
+ */
+export function scrubTokensFromAttrs(attrs) {
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (TOKEN_KEY_RE.test(key)) {
+            out[key] = "[REDACTED]";
+            continue;
+        }
+        if (typeof value === "string") {
+            out[key] = scrubTokensFromString(value);
+        }
+        else if (value !== null && typeof value === "object") {
+            out[key] = scrubTokensFromString(JSON.stringify(value));
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const TITLE_MAX = 100;
+const NORMALIZED_MAX = 60;
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + "…"; // ellipsis
+}
+/**
+ * Pull a short, human-readable error blurb out of a span. Falls back through
+ * statusMessage -> exception.message -> metadata.error -> the span name.
+ */
+function extractMessage(span) {
+    if (!span)
+        return "";
+    if (span.message)
+        return span.message;
+    const meta = span.metadata ?? {};
+    const exception = meta.exception;
+    if (exception &&
+        typeof exception === "object" &&
+        "message" in exception &&
+        typeof exception.message === "string") {
+        return exception.message;
+    }
+    if (typeof meta.error === "string")
+        return meta.error;
+    if (typeof meta.message === "string")
+        return meta.message;
+    return "";
+}
+/**
+ * Take the third segment of a `${spanName}:${errorType}:${normalized}`
+ * signature string. Used to populate the title when no sample span message
+ * is available.
+ */
+function normalizedFromSignature(signature) {
+    const parts = signature.split(":");
+    if (parts.length < 3)
+        return signature;
+    return parts.slice(2).join(":");
+}
+// ---------------------------------------------------------------------------
+// buildIssueBody
+// ---------------------------------------------------------------------------
+/**
+ * Build the title + body for a freshly-filed `debug-auto` issue.
+ *
+ * The body layout is deliberately stable so Phase 3b's dedup regex
+ * (`/^\*\*Hash\*\*: `([0-9a-f]{8})`/m`) keeps matching across versions.
+ */
+export function buildIssueBody(group, env) {
+    const sample = group.sampleSpans[0];
+    const rawMessage = extractMessage(sample) || normalizedFromSignature(group.signature);
+    const message = scrubTokensFromString(rawMessage);
+    const spanName = sample?.name ?? "ralph_hero.error";
+    const title = truncate(`[Debug] ${spanName}: ${truncate(message, NORMALIZED_MAX)}`, TITLE_MAX);
+    const occurrenceRows = [
+        `| Count | First seen | Last seen |`,
+        `|---|---|---|`,
+        `| ${group.count} | ${group.firstSeen} | ${group.lastSeen} |`,
+    ].join("\n");
+    const sampleAttrs = sample?.metadata
+        ? scrubTokensFromAttrs(sample.metadata)
+        : {};
+    const errorDetails = Object.keys(sampleAttrs).length
+        ? "```json\n" + JSON.stringify(sampleAttrs, null, 2) + "\n```"
+        : "_(no attributes captured on sample span)_";
+    const reproduction = sample
+        ? "```json\n" +
+            JSON.stringify({
+                spanName: sample.name,
+                traceId: sample.traceId,
+                startTime: sample.startTime,
+                errorType: sample.errorType,
+                message: scrubTokensFromString(extractMessage(sample)),
+            }, null, 2) +
+            "\n```"
+        : "_(no sample span available)_";
+    const body = [
+        `**Hash**: \`${group.hash}\``,
+        ``,
+        `**Signature**: \`${scrubTokensFromString(group.signature)}\``,
+        ``,
+        `## First seen`,
+        ``,
+        `- mcp-server version: \`${env.mcpVersion}\``,
+        `- node: \`${env.nodeVersion}\``,
+        `- os: \`${env.os}\``,
+        ``,
+        `## Error details`,
+        ``,
+        errorDetails,
+        ``,
+        `## Reproduction (sample span)`,
+        ``,
+        reproduction,
+        ``,
+        `## Occurrences`,
+        ``,
+        occurrenceRows,
+        ``,
+        `## Langfuse trace`,
+        ``,
+        `[Open latest example trace](${group.exampleTraceUrl})`,
+        ``,
+        `---`,
+        ``,
+        `_Filed automatically by \`ralph_hero__collate_debug\` — Phase 3b (GH-1100). ` +
+            `Re-running collation over the same window will append occurrence ` +
+            `comments here instead of creating a duplicate issue._`,
+    ].join("\n");
+    return { title, body };
+}
+// ---------------------------------------------------------------------------
+// buildCommentBody
+// ---------------------------------------------------------------------------
+/**
+ * Build the occurrence-update comment body posted when an existing
+ * `debug-auto` issue is matched by hash. `newCount` is the count returned by
+ * the current `groupSpansBySignature` run — i.e., occurrences in the *new*
+ * window, not the cumulative total (we don't have read access to historical
+ * comment counts without extra queries).
+ */
+export function buildCommentBody(group, newCount, latestTraceUrl) {
+    return [
+        `## Recurring occurrence`,
+        ``,
+        `Detected **${newCount}** new occurrence${newCount === 1 ? "" : "s"} of this signature in the latest collation window.`,
+        ``,
+        `- Hash: \`${group.hash}\``,
+        `- First seen (this window): ${group.firstSeen}`,
+        `- Last seen (this window): ${group.lastSeen}`,
+        `- [Latest example trace](${scrubTokensFromString(latestTraceUrl)})`,
+        ``,
+        `_Posted automatically by \`ralph_hero__collate_debug\` (Phase 3b)._`,
+    ].join("\n");
+}
+//# sourceMappingURL=debug-issue-shape.js.map

package/dist/lib/delegation-log.js

@@ -0,0 +1,199 @@
+/**
+ * Pure read library for the local ralph-delegate JSONL audit log.
+ *
+ * The log lives at `~/.ralph-hero/delegate.log` (overridable via
+ * `RALPH_DELEGATE_LOG_PATH`). One JSON object per line, append-only,
+ * written by `plugin/ralph-hero/scripts/ralph-delegate.sh`. This library
+ * only reads — it never writes.
+ *
+ * Schema versioning: F1 (issue #1185) does NOT emit an explicit
+ * `schemaVersion` field on each line. F5 treats lines containing the
+ * required fields `{ts, task, status, ms}` as **implicit v1**. A future
+ * issue MAY add an explicit `schemaVersion >= 2` — when that happens, the
+ * shape-check should be expanded to honor it. TODO: revisit when the
+ * producer side emits `schemaVersion`.
+ *
+ * Determinism: pure functions. Filesystem reads are the only side effect.
+ * Missing log file resolves to a zero-state result with no throw, matching
+ * the activity.ts precedent (the steady state for opt-out users).
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Test hook + default path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Optional override used only by tests. Production code never sets this.
+ * Mirrors `__setSnapshotRoot` in `snapshots.ts`.
+ */
+let delegateLogPathOverride = null;
+/** Test hook: override the default log path. Pass `null` to restore. */
+export function __setDelegateLogPath(path) {
+    delegateLogPathOverride = path;
+}
+/**
+ * Resolve the default log path: env var override, then `~/.ralph-hero/delegate.log`.
+ * Expands a leading `~/` (mirrors `ralph-delegate.sh:208-211`).
+ */
+export function defaultDelegationLogPath() {
+    if (delegateLogPathOverride !== null)
+        return delegateLogPathOverride;
+    const fromEnv = process.env.RALPH_DELEGATE_LOG_PATH;
+    if (fromEnv && fromEnv.length > 0) {
+        return expandHome(fromEnv);
+    }
+    return path.join(os.homedir(), ".ralph-hero", "delegate.log");
+}
+function expandHome(p) {
+    if (p.startsWith("~/")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/**
+ * Read the delegation audit log. Returns a zero-state result with
+ * `fileExists: false` when the file is missing — never throws on ENOENT.
+ * Lines that fail JSON.parse OR lack required fields are skipped and
+ * counted in `skippedLines`; each skip emits a `console.warn` with a
+ * truncated prefix of the offending line.
+ */
+export async function readDelegationLog(config) {
+    const logPath = config.logPath;
+    let content;
+    try {
+        content = await fs.readFile(logPath, "utf8");
+    }
+    catch (e) {
+        if (e &&
+            typeof e === "object" &&
+            "code" in e &&
+            e.code === "ENOENT") {
+            return { events: [], skippedLines: 0, fileExists: false, logPath };
+        }
+        throw e;
+    }
+    const events = [];
+    let skipped = 0;
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skipped++;
+            console.warn(`[delegation-log] Skipping malformed line in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        if (!isDelegationEventShape(parsed)) {
+            skipped++;
+            console.warn(`[delegation-log] Skipping line with missing required fields in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        events.push(parsed);
+    }
+    return { events, skippedLines: skipped, fileExists: true, logPath };
+}
+/**
+ * Implicit-v1 shape check: presence of `{ts, task, status, ms}` with
+ * correct primitive types. A future explicit `schemaVersion >= 2` may
+ * extend this gate.
+ */
+function isDelegationEventShape(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    return (typeof o.ts === "string" &&
+        typeof o.task === "string" &&
+        typeof o.status === "string" &&
+        typeof o.ms === "number");
+}
+// ---------------------------------------------------------------------------
+// Aggregator
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate parsed events into per-task + totals. Pure function — does
+ * no I/O. Percentiles use the nearest-rank method against successful
+ * (status=ok) calls only.
+ */
+export function aggregateDelegationStats(events) {
+    const byTask = {};
+    const okMsByTask = {};
+    let totalCalls = 0;
+    let totalFallbacks = 0;
+    let totalBytesIn = 0;
+    let totalBytesOut = 0;
+    for (const ev of events) {
+        const task = ev.task;
+        if (!byTask[task]) {
+            byTask[task] = {
+                calls: 0,
+                fallbacks: 0,
+                p50Ms: null,
+                p99Ms: null,
+                bytesIn: 0,
+                bytesOut: 0,
+                tokens: null,
+            };
+            okMsByTask[task] = [];
+        }
+        byTask[task].calls += 1;
+        totalCalls += 1;
+        if (isFallbackStatus(ev.status)) {
+            byTask[task].fallbacks += 1;
+            totalFallbacks += 1;
+        }
+        const bIn = typeof ev.bytes_in === "number" ? ev.bytes_in : 0;
+        const bOut = typeof ev.bytes_out === "number" ? ev.bytes_out : 0;
+        byTask[task].bytesIn += bIn;
+        byTask[task].bytesOut += bOut;
+        totalBytesIn += bIn;
+        totalBytesOut += bOut;
+        if (ev.status === "ok") {
+            okMsByTask[task].push(ev.ms);
+        }
+    }
+    // Compute percentiles
+    for (const task of Object.keys(byTask)) {
+        const samples = okMsByTask[task];
+        byTask[task].p50Ms = percentile(samples, 0.5);
+        byTask[task].p99Ms = percentile(samples, 0.99);
+    }
+    return {
+        totals: {
+            calls: totalCalls,
+            fallbacks: totalFallbacks,
+            bytesIn: totalBytesIn,
+            bytesOut: totalBytesOut,
+        },
+        byTask,
+    };
+}
+/**
+ * A fallback is any non-`ok`, non-`dry_run` status: timeout, unreachable,
+ * parse_error, http_*. `dry_run` is operator-driven and not a real
+ * delegation failure, so it does not count.
+ */
+function isFallbackStatus(status) {
+    return status !== "ok" && status !== "dry_run";
+}
+/**
+ * Nearest-rank percentile: `sorted[ceil(q * n) - 1]`. Returns `null`
+ * when the sample is empty.
+ */
+function percentile(samples, q) {
+    if (samples.length === 0)
+        return null;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.ceil(q * sorted.length);
+    // Guard the edge case q=0 (would index -1)
+    const idx = Math.max(0, rank - 1);
+    return sorted[idx];
+}
+//# sourceMappingURL=delegation-log.js.map

package/dist/tools/debug-tools.js

@@ -3,8 +3,9 @@
  *
  * Provides:
  *   - `ralph_hero__collate_debug` (v2 — queries Langfuse for error spans,
- *     groups by normalized signature, returns the grouped report; GitHub
- *     issue creation lands in Phase 3b / GH-1100)
+ *     groups by normalized signature, dedupes against open `debug-auto`
+ *     issues, and either creates new issues or appends occurrence comments
+ *     when `dryRun=false`)
  *   - `ralph_hero__debug_stats` (v1 — aggregates JSONL logs; preserved for
  *     backward compat, not extended)
  *
@@ -12,14 +13,18 @@
  * `debug_stats`; the new Langfuse path is fully separate.
  */
 import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, platform, release } from "node:os";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
 import { zBoolish } from "../lib/zod-helpers.js";
 import { createLangfuseClient, } from "../lib/langfuse-client.js";
 import { groupSpansBySignature, observationToSpan, } from "../lib/error-signature.js";
+import { buildIssueBody, buildCommentBody, } from "../lib/debug-issue-shape.js";
+import { resolveConfig } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // JSONL Parsing
 // ---------------------------------------------------------------------------
@@ -181,6 +186,208 @@ export function aggregateStats(events, groupBy) {
         groups,
     };
 }
+/**
+ * Look for an open `debug-auto` issue whose body carries the given 8-char
+ * hash on a `**Hash**: \`<hash>\`` line. Only issues updated within the last
+ * `withinDays` are considered (default 7), matching the spec's "dedup window".
+ *
+ * Returns the first matching issue `{ number, id }` or `null` if no match.
+ * Search rate-limit errors are swallowed (caller will create a duplicate;
+ * the next run will collapse it via comment).
+ */
+export async function findExistingDebugIssue(client, owner, repo, hash, withinDays = 7) {
+    const sinceIso = new Date(Date.now() - withinDays * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .slice(0, 10); // YYYY-MM-DD
+    // The hash marker `**Hash**: ` is too punctuation-heavy for GitHub's text
+    // search index — search on the bare 8-char hex; the marker line is verified
+    // by inspecting the issue body below.
+    const q = `repo:${owner}/${repo} is:issue is:open label:debug-auto ${hash} in:body updated:>=${sinceIso}`;
+    try {
+        const data = await client.query(`query DebugIssueSearch($q: String!) {
+        search(query: $q, type: ISSUE, first: 10) {
+          nodes {
+            ... on Issue {
+              number
+              id
+              body
+            }
+          }
+        }
+      }`, { q });
+        const marker = new RegExp(`^\\*\\*Hash\\*\\*: \`${hash}\``, "m");
+        for (const node of data.search.nodes ?? []) {
+            if (typeof node.number === "number" &&
+                typeof node.id === "string" &&
+                typeof node.body === "string" &&
+                marker.test(node.body)) {
+                return { number: node.number, id: node.id };
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        console.error(`[debug-tools] findExistingDebugIssue search failed (treating as no-match): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Resolve the repository's GraphQL node ID, with SessionCache memoization.
+ */
+async function resolveRepoNodeId(client, owner, repo) {
+    const cacheKey = `repo-node-id:${owner}/${repo}`;
+    const cached = client.getCache().get(cacheKey);
+    if (cached)
+        return cached;
+    const result = await client.query(`query($owner: String!, $repo: String!) {
+      repository(owner: $owner, name: $repo) { id }
+    }`, { owner, repo });
+    const id = result.repository?.id;
+    if (!id) {
+        throw new Error(`Repository ${owner}/${repo} not found`);
+    }
+    client.getCache().set(cacheKey, id, 60 * 60 * 1000); // 1 hour
+    return id;
+}
+/**
+ * Resolve repo-scoped label IDs for `debug-auto` and `ralph-self-report`.
+ * Labels that don't exist in the repo are skipped silently — issue creation
+ * still proceeds, the label just won't be applied.
+ */
+async function resolveLabelIds(client, owner, repo, labelNames) {
+    const cacheKey = `repo-labels:${owner}/${repo}`;
+    let labels = client.getCache().get(cacheKey);
+    if (!labels) {
+        const result = await client.query(`query($owner: String!, $repo: String!) {
+        repository(owner: $owner, name: $repo) {
+          labels(first: 100) { nodes { id name } }
+        }
+      }`, { owner, repo });
+        labels = result.repository?.labels.nodes ?? [];
+        client.getCache().set(cacheKey, labels, 5 * 60 * 1000);
+    }
+    return labelNames
+        .map((n) => labels.find((l) => l.name === n)?.id)
+        .filter((id) => typeof id === "string");
+}
+/**
+ * Create a fresh `debug-auto` issue for a new signature. Returns the new
+ * issue number + node ID. Project board placement (Backlog state) is
+ * delegated to the existing route-issues.yml workflow — we set labels and
+ * the body marker; the workflow handles board routing.
+ */
+async function createDebugIssue(client, owner, repo, title, body) {
+    const repoId = await resolveRepoNodeId(client, owner, repo);
+    const labelIds = await resolveLabelIds(client, owner, repo, [
+        "debug-auto",
+        "ralph-self-report",
+    ]);
+    const result = await client.mutate(`mutation($repoId: ID!, $title: String!, $body: String!, $labelIds: [ID!]) {
+      createIssue(input: {
+        repositoryId: $repoId,
+        title: $title,
+        body: $body,
+        labelIds: $labelIds
+      }) {
+        issue { id number url }
+      }
+    }`, {
+        repoId,
+        title,
+        body,
+        labelIds: labelIds.length ? labelIds : null,
+    });
+    const issue = result.createIssue.issue;
+    client
+        .getCache()
+        .set(`issue-node-id:${owner}/${repo}#${issue.number}`, issue.id, 30 * 60 * 1000);
+    return issue;
+}
+/**
+ * Append an occurrence-update comment to an existing `debug-auto` issue.
+ */
+async function commentOnDebugIssue(client, issueNodeId, body) {
+    const result = await client.mutate(`mutation($subjectId: ID!, $body: String!) {
+      addComment(input: { subjectId: $subjectId, body: $body }) {
+        commentEdge { node { id } }
+      }
+    }`, { subjectId: issueNodeId, body });
+    return result.addComment.commentEdge.node.id;
+}
+/**
+ * Read the MCP server semver from package.json next to this module. Falls
+ * back to `"unknown"` if the file is missing or unreadable. Mirrors the
+ * approach used in `telemetry.ts:resolveServiceVersion` but kept local so
+ * the debug surface has zero cross-dependency on telemetry init order.
+ */
+function readMcpServerVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(here, "..", "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Default `IssueShapeEnv` builder — captures the MCP server version, the
+ * Node version, and a short OS descriptor at call time. Exposed so tests
+ * can override (e.g., deterministic version stamps).
+ */
+function defaultEnv(mcpVersion) {
+    return {
+        mcpVersion: mcpVersion === "unknown" ? readMcpServerVersion() : mcpVersion,
+        nodeVersion: process.version,
+        os: `${platform()} ${release()}`,
+    };
+}
+/**
+ * Iterate groups, dedupe each against existing issues, and either create a
+ * new issue or post a comment. Returns the counts the tool surfaces back to
+ * the caller. Per-group failures are recorded and surfaced but do NOT abort
+ * the loop — partial success is preferable to losing the whole run.
+ */
+export async function fileOrCommentForGroups(client, owner, repo, groups, env) {
+    const results = [];
+    let issuesCreated = 0;
+    let issuesUpdated = 0;
+    for (const group of groups) {
+        try {
+            const existing = await findExistingDebugIssue(client, owner, repo, group.hash);
+            if (existing) {
+                const commentBody = buildCommentBody(group, group.count, group.exampleTraceUrl);
+                await commentOnDebugIssue(client, existing.id, commentBody);
+                issuesUpdated += 1;
+                results.push({
+                    hash: group.hash,
+                    action: "commented",
+                    issueNumber: existing.number,
+                });
+            }
+            else {
+                const { title, body } = buildIssueBody(group, env);
+                const created = await createDebugIssue(client, owner, repo, title, body);
+                issuesCreated += 1;
+                results.push({
+                    hash: group.hash,
+                    action: "created",
+                    issueNumber: created.number,
+                });
+            }
+        }
+        catch (error) {
+            results.push({
+                hash: group.hash,
+                action: "error",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { issuesCreated, issuesUpdated, results };
+}
 let langfuseClientFactory = () => createLangfuseClient();
 /**
  * Override the Langfuse client factory. Returns a disposer that restores the
@@ -193,23 +400,20 @@ export function setLangfuseClientFactory(factory) {
         langfuseClientFactory = prev;
     };
 }
-export function registerDebugTools(server, client) {
+export function registerDebugTools(server, client, mcpVersion = "unknown") {
     const logDir = join(homedir(), ".ralph-hero", "logs");
-    // `client` is referenced by `debug_stats` (legacy) and reserved for Phase 3b
-    // (GH-1100), which will use it for GitHub dedup + issue creation.
-    void client;
     // -------------------------------------------------------------------------
-    // ralph_hero__collate_debug (v2 — Langfuse path)
+    // ralph_hero__collate_debug (v2 — Langfuse + GitHub dedup)
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__collate_debug", "Query Langfuse for error spans in a time window, normalize messages, and group by signature. Phase 3a returns the grouped report only (dryRun forced true); Phase 3b (GH-1100) adds GitHub issue dedup + create/comment. Returns: { since, errorGroups, totalOccurrences, dryRun, groups[] }.", {
+    server.tool("ralph_hero__collate_debug", "Query Langfuse for error spans in a time window, normalize messages, group by signature, then either return the grouped report (dryRun=true) or dedupe against open `debug-auto` issues and create / comment (dryRun=false, default). Returns: { since, errorGroups, totalOccurrences, dryRun, issuesCreated?, issuesUpdated?, groups[] }.", {
         since: z
             .string()
             .optional()
             .describe("ISO date string. Only spans whose startTime >= this value are considered (default: 24h ago)."),
         dryRun: zBoolish()
             .optional()
-            .default(true)
-            .describe("Phase 3a only honors dryRun=true; passing false returns a stub error until Phase 3b lands."),
+            .default(false)
+            .describe("If true, return the grouped report without touching GitHub. Default false — creates / comments on `debug-auto` issues per signature."),
         minOccurrences: z
             .number()
             .int()
@@ -220,13 +424,10 @@ export function registerDebugTools(server, client) {
         projectNumber: z
             .number()
             .optional()
-            .describe("Project number override (reserved for Phase 3b)."),
+            .describe("Project number override. Currently informational — issues land in the configured project via the existing route-issues workflow."),
     }, async (args) => {
         try {
-            const dryRun = args.dryRun ?? true;
-            if (!dryRun) {
-                return toolError("dryRun=false requires GH-1100 (Phase 3b) — not yet implemented");
-            }
+            const dryRun = args.dryRun ?? false;
             const minOccurrences = args.minOccurrences ?? 3;
             const sinceDate = args.since
                 ? new Date(args.since)
@@ -254,20 +455,46 @@ export function registerDebugTools(server, client) {
                 langfuseHost: langfuse.host,
             });
             const totalOccurrences = groups.reduce((sum, g) => sum + g.count, 0);
+            const summaryGroups = groups.map((g) => ({
+                signature: g.signature,
+                hash: g.hash,
+                count: g.count,
+                firstSeen: g.firstSeen,
+                lastSeen: g.lastSeen,
+                exampleTraceUrl: g.exampleTraceUrl,
+                sampleSpans: g.sampleSpans.slice(0, 3),
+            }));
+            if (dryRun) {
+                return toolSuccess({
+                    since: fromStartTime,
+                    errorGroups: groups.length,
+                    totalOccurrences,
+                    dryRun: true,
+                    groups: summaryGroups,
+                });
+            }
+            // dryRun=false — file or comment per signature.
+            let owner;
+            let repo;
+            try {
+                const resolved = resolveConfig(client, {});
+                owner = resolved.owner;
+                repo = resolved.repo;
+            }
+            catch (error) {
+                return toolError(`Cannot resolve owner/repo for issue creation: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const env = defaultEnv(mcpVersion);
+            const fileResult = await fileOrCommentForGroups(client, owner, repo, groups, env);
             return toolSuccess({
                 since: fromStartTime,
                 errorGroups: groups.length,
                 totalOccurrences,
-                dryRun: true,
-                groups: groups.map((g) => ({
-                    signature: g.signature,
-                    hash: g.hash,
-                    count: g.count,
-                    firstSeen: g.firstSeen,
-                    lastSeen: g.lastSeen,
-                    exampleTraceUrl: g.exampleTraceUrl,
-                    sampleSpans: g.sampleSpans.slice(0, 3),
-                })),
+                dryRun: false,
+                issuesCreated: fileResult.issuesCreated,
+                issuesUpdated: fileResult.issuesUpdated,
+                results: fileResult.results,
+                groups: summaryGroups,
             });
         }
         catch (error) {

package/dist/tools/delegation-tools.js

@@ -0,0 +1,44 @@
+/**
+ * Registers the `ralph_hero__delegation_stats` MCP tool. Pure read-only
+ * surface over the JSONL audit log written by `ralph-delegate.sh` (F1).
+ *
+ * Follows the same registration convention as `activity-tools.ts`: no
+ * GitHub client argument, defaults pulled from env var with a homedir
+ * fallback, returns `toolSuccess` on missing-file (zero-state) so callers
+ * can render a dashboard without an error path.
+ */
+import { z } from "zod";
+import { readDelegationLog, aggregateDelegationStats, defaultDelegationLogPath, } from "../lib/delegation-log.js";
+import { toolSuccess, toolError } from "../types.js";
+const TOKENS_REASON = "F1 audit-log does not capture token usage; bytes used as a proxy";
+export function registerDelegationTools(server) {
+    server.tool("ralph_hero__delegation_stats", "Read-only telemetry over the local ralph-delegate JSONL audit log. Returns per-task call counts, fallback counts (non-ok/non-dry_run), p50/p99 latency from successful calls, and bytes_in/bytes_out aggregates. Reads RALPH_DELEGATE_LOG_PATH (default ~/.ralph-hero/delegate.log). Missing log file returns a zero-state result, never errors.", {
+        logPath: z
+            .string()
+            .optional()
+            .describe("Optional override for the JSONL log path. Defaults to RALPH_DELEGATE_LOG_PATH or ~/.ralph-hero/delegate.log."),
+    }, async (params) => {
+        try {
+            const resolvedPath = params.logPath ?? defaultDelegationLogPath();
+            const read = await readDelegationLog({ logPath: resolvedPath });
+            const stats = aggregateDelegationStats(read.events);
+            return toolSuccess({
+                logPath: read.logPath,
+                fileExists: read.fileExists,
+                totals: {
+                    calls: stats.totals.calls,
+                    fallbacks: stats.totals.fallbacks,
+                    bytesIn: stats.totals.bytesIn,
+                    bytesOut: stats.totals.bytesOut,
+                    skippedLines: read.skippedLines,
+                },
+                byTask: stats.byTask,
+                tokensReason: TOKENS_REASON,
+            });
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=delegation-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.140",
+  "version": "2.5.149",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",