pr-shepherd 0.34.0 → 0.36.0

package/bin/mcp-stdio.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPrShepherdMcpStdio } from "./mcp/index.mjs";
+runPrShepherdMcpStdio().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`pr-shepherd-mcp error: ${message}\n`);
+    process.exitCode = 1;
+});

package/bin/merge-status/derive.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Derives a shepherd `MergeStatusResult` from raw PR data.
+ *
+ * `pr.state` is passed through unchanged; `iterate` handles the cancel action
+ * for non-OPEN (merged/closed) PRs — this function does not branch on it.
+ *
+ * Interpretation order for `status` — first match wins:
+ *   1. mergeable == CONFLICTING       → CONFLICTS (hard conflict even for drafts)
+ *   2. blockingBotReviewInProgress        → BLOCKED
+ *   3. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts, even for drafts)
+ *   4. isDraft                        → DRAFT
+ *   5. mergeStateStatus BEHIND        → BEHIND
+ *   6. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
+ *   7. mergeStateStatus UNSTABLE      → UNSTABLE
+ *   8. mergeStateStatus UNKNOWN       → UNKNOWN
+ *   9. mergeStateStatus CLEAN         → CLEAN
+ */
+import type { BatchPrData, MergeStatusResult } from "../types.mts";
+export declare function deriveMergeStatus(pr: BatchPrData): MergeStatusResult;

package/bin/merge-status/derive.mjs

@@ -16,6 +16,7 @@
  *   9. mergeStateStatus CLEAN         → CLEAN
  */
 import { loadConfig } from "../config/load.mjs";
+import { deriveMergeRequirements } from "./requirements.mjs";
 export function deriveMergeStatus(pr) {
     const blockingBotReviewInProgress = detectBlockingBotReview(pr);
     let status;
@@ -55,6 +56,7 @@ export function deriveMergeStatus(pr) {
         reviewDecision: pr.reviewDecision,
         blockingBotReviewInProgress,
         mergeStateStatus: pr.mergeStateStatus,
+        mergeRequirements: deriveMergeRequirements(pr),
     };
 }
 // ---------------------------------------------------------------------------

package/bin/merge-status/requirements-format.d.mts

@@ -0,0 +1,3 @@
+import type { MergeRequirements } from "../types.mts";
+export declare function formatMergeRequirementLines(req: MergeRequirements): string[];
+export declare function blockedReasonFromRequirements(req: MergeRequirements | undefined): string | null;

package/bin/merge-status/requirements-format.mjs

@@ -0,0 +1,88 @@
+const REQUIRED = "[Required]";
+const NOT_REQUIRED = "[Not Required]";
+export function formatMergeRequirementLines(req) {
+    const lines = [
+        formatApprovals(req.approvals.current, req.approvals.requiredCount),
+        formatConversations(req.conversationsResolved),
+    ];
+    if (req.codeOwnerReview)
+        lines.push(`Code owner review: ${REQUIRED}`);
+    if (req.lastPushApproval)
+        lines.push(`Last-push approval: ${REQUIRED}`);
+    if (req.signedCommits)
+        lines.push(`Signed commits: ${REQUIRED}`);
+    if (req.linearHistory)
+        lines.push(`Linear history: ${REQUIRED}`);
+    if (req.branchUpToDate) {
+        const value = req.branchUpToDate.current ? "Yes" : "No";
+        lines.push(`Branch up to date: ${value} ${REQUIRED}`);
+    }
+    if (req.requiredStatusChecks) {
+        const n = req.requiredStatusChecks.contexts.length;
+        lines.push(`Required status checks: ${n} ${REQUIRED}`);
+    }
+    if (req.requiredDeployments) {
+        const envs = req.requiredDeployments.environments.join(", ");
+        lines.push(`Required deployments: ${envs} ${REQUIRED}`);
+    }
+    if (req.requiredWorkflows)
+        lines.push(`Required workflows: ${REQUIRED}`);
+    if (req.codeScanning)
+        lines.push(`Code scanning: ${REQUIRED}`);
+    if (req.mergeQueue)
+        lines.push(formatMergeQueue(req.mergeQueue));
+    if (req.stack) {
+        const { number, position, size, baseRefName } = req.stack;
+        lines.push(`Stack: #${number} ${position}/${size} (base ${baseRefName})`);
+    }
+    return lines;
+}
+export function blockedReasonFromRequirements(req) {
+    if (!req)
+        return null;
+    const unmet = [];
+    if (req.approvals.requiredCount > 0 && req.approvals.current < req.approvals.requiredCount) {
+        const need = req.approvals.requiredCount - req.approvals.current;
+        unmet.push(`awaiting ${need} approval${need === 1 ? "" : "s"}`);
+    }
+    if (req.conversationsResolved.required && !req.conversationsResolved.resolved) {
+        unmet.push("unresolved conversations are required");
+    }
+    if (req.branchUpToDate && !req.branchUpToDate.current) {
+        unmet.push("branch is behind base");
+    }
+    if (req.mergeQueue?.inQueue) {
+        const pos = req.mergeQueue.position != null ? ` position ${req.mergeQueue.position}` : "";
+        unmet.push(`in merge queue${pos}`);
+    }
+    else if (req.mergeQueue?.required) {
+        unmet.push("merge queue is required");
+    }
+    return unmet.length > 0 ? unmet.join("; ") : null;
+}
+function formatApprovals(current, requiredCount) {
+    const tag = requiredCount > 0 ? REQUIRED : NOT_REQUIRED;
+    if (current === 0 && requiredCount === 0)
+        return `Approvals: None ${NOT_REQUIRED}`;
+    if (current === 0)
+        return `Approvals: None ${REQUIRED}`;
+    if (requiredCount > 0)
+        return `Approvals: ${current}/${requiredCount} ${tag}`;
+    return `Approvals: ${current} ${NOT_REQUIRED}`;
+}
+function formatConversations(c) {
+    const value = c.resolved ? "Yes" : "No";
+    const tag = c.required ? REQUIRED : NOT_REQUIRED;
+    return `Conversations Resolved: ${value} ${tag}`;
+}
+function formatMergeQueue(q) {
+    const tag = q.required ? REQUIRED : NOT_REQUIRED;
+    if (q.inQueue) {
+        const pos = q.position != null ? `position ${q.position}` : "Yes";
+        const state = q.state ? ` ${q.state}` : "";
+        return `Merge queue: ${pos}${state} ${tag}`;
+    }
+    if (q.required || q.enabled)
+        return `Merge queue: No ${tag}`;
+    return `Merge queue: No ${NOT_REQUIRED}`;
+}

package/bin/merge-status/requirements.d.mts

@@ -0,0 +1,2 @@
+import type { BatchPrData, MergeRequirements } from "../types.mts";
+export declare function deriveMergeRequirements(pr: BatchPrData): MergeRequirements;

package/bin/merge-status/requirements.mjs

@@ -0,0 +1,51 @@
+import { EMPTY_BRANCH_RULES } from "../github/batch-parsers-rules.mjs";
+export function deriveMergeRequirements(pr) {
+    const rules = pr.branchRules ?? EMPTY_BRANCH_RULES;
+    const currentApprovals = pr.latestReviews.filter((r) => r.state === "APPROVED").length;
+    const unresolvedCount = pr.reviewThreads.filter((t) => !t.isResolved).length;
+    const req = {
+        approvals: {
+            current: currentApprovals,
+            requiredCount: rules.requiredApprovingReviewCount,
+        },
+        conversationsResolved: {
+            resolved: unresolvedCount === 0,
+            unresolvedCount,
+            required: rules.requiresConversationResolution,
+        },
+    };
+    if (rules.requiresCodeOwnerReviews)
+        req.codeOwnerReview = { required: true };
+    if (rules.requiresLastPushApproval)
+        req.lastPushApproval = { required: true };
+    if (rules.requiresCommitSignatures)
+        req.signedCommits = { required: true };
+    if (rules.requiresLinearHistory)
+        req.linearHistory = { required: true };
+    if (rules.requiresStrictStatusChecks) {
+        req.branchUpToDate = { current: pr.mergeStateStatus !== "BEHIND", required: true };
+    }
+    if (rules.requiredStatusCheckContexts.length > 0) {
+        req.requiredStatusChecks = { contexts: rules.requiredStatusCheckContexts };
+    }
+    if (rules.requiredDeploymentEnvironments.length > 0) {
+        req.requiredDeployments = { environments: rules.requiredDeploymentEnvironments };
+    }
+    if (rules.requiresWorkflows)
+        req.requiredWorkflows = { required: true };
+    if (rules.requiresCodeScanning)
+        req.codeScanning = { required: true };
+    const queueRequired = rules.requiresMergeQueue || Boolean(pr.isMergeQueueEnabled);
+    if (queueRequired || pr.isInMergeQueue) {
+        req.mergeQueue = {
+            required: queueRequired,
+            enabled: Boolean(pr.isMergeQueueEnabled),
+            inQueue: Boolean(pr.isInMergeQueue),
+            ...(pr.mergeQueueEntry?.position !== undefined && { position: pr.mergeQueueEntry.position }),
+            ...(pr.mergeQueueEntry?.state !== undefined && { state: pr.mergeQueueEntry.state }),
+        };
+    }
+    if (pr.stack)
+        req.stack = pr.stack;
+    return req;
+}

package/bin/reporters/agent.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Projections for the agent-facing iterate output.
+ *
+ * These strip fields that are always-false by the time items reach iterate
+ * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
+ * agent/iterate prompt never reads (event, status, category).
+ * conclusion is preserved on AgentCheck so the formatter can branch on run-level conclusions.
+ * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
+ * The original domain types are preserved as internal snapshot types.
+ */
+import type { ReviewThread, PrComment, TriagedCheck, ClassifiedCheck, AgentThread, AgentComment, AgentCheck, AgentStalledCheck } from "../types.mts";
+export declare function toAgentThread(t: ReviewThread): AgentThread;
+export declare function toAgentComment(c: PrComment & {
+    edited?: boolean;
+}): AgentComment;
+export declare function toAgentCheck(c: TriagedCheck): AgentCheck;
+export declare function toAgentStalledCheck(c: ClassifiedCheck, nowSeconds: number): AgentStalledCheck;
+/**
+ * Project failing checks for the agent. Deduplicates only null-runId external
+ * checks by name — when runId is present each check may have a distinct job and
+ * log tail, so they are all kept.
+ */
+export declare function toAgentChecks(checks: TriagedCheck[]): AgentCheck[];

package/bin/reporters/agent.mjs

@@ -21,6 +21,7 @@ export function toAgentThread(t) {
             t.startLine !== t.line && { startLine: t.startLine }),
         author: t.author,
         ...(t.authorType !== undefined && { authorType: t.authorType }),
+        ...(t.authorAssociation !== undefined && { authorAssociation: t.authorAssociation }),
         body: t.body,
         url: t.url,
         ...(t.edited === true && { edited: true }),
@@ -29,6 +30,7 @@ export function toAgentThread(t) {
                 id: c.id,
                 author: c.author,
                 ...(c.authorType !== undefined && { authorType: c.authorType }),
+                ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
                 body: c.body,
                 url: c.url,
             })),
@@ -41,6 +43,7 @@ export function toAgentComment(c) {
         id: c.id,
         author: c.author,
         ...(c.authorType !== undefined && { authorType: c.authorType }),
+        ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
         ...(c.edited === true && { edited: true }),

package/bin/state/base.d.mts

@@ -0,0 +1,10 @@
+export declare function resolveStateBase(): string;
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/...parts`.
+ * Owner, repo, PR number, and each extra part must be a safe path segment.
+ */
+export declare function resolvePrStatePath(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, ...parts: string[]): string;

package/bin/state/base.mjs

@@ -1,6 +1,29 @@
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { SAFE_PR_NUMBER, SAFE_SEGMENT } from "../util/path-segment.mjs";
 export function resolveStateBase() {
     const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
     return envDir ? envDir : join(tmpdir(), "pr-shepherd-state");
 }
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/...parts`.
+ * Owner, repo, PR number, and each extra part must be a safe path segment.
+ */
+export function resolvePrStatePath(key, ...parts) {
+    if (!SAFE_SEGMENT.test(key.owner)) {
+        throw new Error(`Invalid state key segment "owner": ${key.owner}`);
+    }
+    if (!SAFE_SEGMENT.test(key.repo)) {
+        throw new Error(`Invalid state key segment "repo": ${key.repo}`);
+    }
+    const pr = String(key.pr);
+    if (!SAFE_PR_NUMBER.test(pr)) {
+        throw new Error(`Invalid state key segment "pr": ${key.pr}`);
+    }
+    for (const part of parts) {
+        if (!SAFE_SEGMENT.test(part)) {
+            throw new Error(`Invalid state key segment: ${part}`);
+        }
+    }
+    return join(resolveStateBase(), `${key.owner}-${key.repo}`, pr, ...parts);
+}

package/bin/state/bot-cr-seen.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
+ *
+ * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
+ * `apply review:` command. If the agent drops that flag, the bot CR keeps the PR in
+ * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
+ * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
+ * — independent of the broader fingerprint-based `stall-timeout` mechanism in
+ * `iterate-stall.mts` (which only fires when no field of the iterate result
+ * changed).
+ *
+ * State lives in
+ * `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/bot-cr-seen.json`.
+ *
+ * `bodyHash` lets us reset `firstSeenAt` when the bot re-issues the review
+ * with a different body, so a fresh review gets the full timeout window.
+ */
+interface BotCrSeenEntry {
+    /** Unix timestamp (seconds) when this review was first observed undismissed. */
+    firstSeenAt: number;
+    /** SHA-256 body-hash prefix; reset firstSeenAt when this changes. */
+    bodyHash: string;
+}
+export interface BotCrSeenState {
+    reviews: Record<string, BotCrSeenEntry>;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function readBotCrSeenState(key: StateKey): Promise<BotCrSeenState | null>;
+export declare function writeBotCrSeenState(key: StateKey, state: BotCrSeenState): Promise<void>;
+/**
+ * Update tracked entries against the current set of bot CR reviews:
+ * - Insert any new IDs with `firstSeenAt = now` and the current body hash.
+ * - Reset `firstSeenAt` for entries whose body hash changed (review re-issued).
+ * - Drop entries whose IDs are no longer in the input (review was dismissed
+ *   or superseded by an approval).
+ *
+ * Pure function: returns the next state and the IDs whose age has reached the
+ * `stallTimeoutSeconds` threshold (escalate candidates).
+ */
+export declare function updateBotCrSeenState(previous: BotCrSeenState | null, currentBotCrReviews: ReadonlyArray<{
+    id: string;
+    body: string;
+}>, nowSeconds: number, stallTimeoutSeconds: number): {
+    next: BotCrSeenState;
+    staleIds: string[];
+};
+export {};

package/bin/state/bot-cr-seen.mjs

@@ -2,7 +2,7 @@
  * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
  *
  * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
- * `resolve:` command. If the agent drops that flag, the bot CR keeps the PR in
+ * `apply review:` command. If the agent drops that flag, the bot CR keeps the PR in
  * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
  * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
  * — independent of the broader fingerprint-based `stall-timeout` mechanism in
@@ -17,9 +17,8 @@
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
 import { hashBody } from "./seen-comments.mjs";
 export async function readBotCrSeenState(key) {
     try {
@@ -97,14 +96,5 @@ export function updateBotCrSeenState(previous, currentBotCrReviews, nowSeconds,
     return { next: { reviews: next }, staleIds };
 }
 function resolvePath(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "bot-cr-seen.json");
+    return resolvePrStatePath(key, "bot-cr-seen.json");
 }

package/bin/state/fix-attempts.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Persistent attempt counter for the iterate escalation guard.
+ *
+ * Tracks how many times each review thread has been dispatched to the fix_code
+ * handler without being resolved. Counts are reset automatically when the HEAD
+ * commit SHA changes (i.e. a new push landed).
+ *
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
+ */
+export interface FixAttemptsState {
+    /** HEAD SHA at the time the counts were last written. Reset key. */
+    headSha: string;
+    /** Map from thread ID → number of fix_code dispatches that included this thread. */
+    threadAttempts: Record<string, number>;
+    /** Map from thread ID → body hash used for the associated attempt count. */
+    threadBodyHashes?: Record<string, string>;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Read the current attempt state. Returns null on miss. */
+export declare function readFixAttempts(key: StateKey): Promise<FixAttemptsState | null>;
+/** Write attempt state (fire-and-forget — never throws). */
+export declare function writeFixAttempts(key: StateKey, state: FixAttemptsState): Promise<void>;
+export {};

package/bin/state/fix-attempts.mjs

@@ -9,9 +9,8 @@
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -54,14 +53,5 @@ export async function writeFixAttempts(key, state) {
 // Helpers
 // ---------------------------------------------------------------------------
 function resolvePath(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "fix-attempts.json");
+    return resolvePrStatePath(key, "fix-attempts.json");
 }

package/bin/state/iterate-stall.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Persistent stall-detection state for the iterate loop.
+ *
+ * Tracks the fingerprint of the last iterate result and when that fingerprint
+ * was first seen. If the fingerprint does not change for stallTimeoutSeconds
+ * the iterate command escalates instead of repeating the same action.
+ *
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/iterate-stall.json`.
+ */
+interface StallState {
+    /** Canonicalized JSON fingerprint of the material iterate inputs. */
+    fingerprint: string;
+    /** Unix timestamp (seconds) when this fingerprint was first seen. */
+    firstSeenAt: number;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Read the current stall state. Returns null on miss, corrupt data, or invalid shape. */
+export declare function readStallState(key: StateKey): Promise<StallState | null>;
+/** Clear stall state so the next invocation starts a fresh timer (fire-and-forget — never throws). */
+export declare function clearStallState(key: StateKey): Promise<void>;
+/** Write stall state (fire-and-forget — never throws). */
+export declare function writeStallState(key: StateKey, state: StallState): Promise<void>;
+export {};

package/bin/state/iterate-stall.mjs

@@ -9,9 +9,8 @@
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -70,14 +69,5 @@ export async function writeStallState(key, state) {
 // Helpers
 // ---------------------------------------------------------------------------
 function resolvePath(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "iterate-stall.json");
+    return resolvePrStatePath(key, "iterate-stall.json");
 }

package/bin/state/seen-comments.d.mts

@@ -0,0 +1,62 @@
+export interface SeenMarker {
+    seenAt: number;
+    id?: string;
+    [key: string]: unknown;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+/** Compute a 16-hex-char SHA-256 prefix of a comment body. */
+export declare function hashBody(body: string): string;
+/**
+ * Classify a candidate item against the seen map.
+ *
+ * - "new"       — no marker exists; surface the body and write the marker.
+ * - "edited"    — marker exists but stored hash differs from the current body;
+ *                 surface the updated body and update the marker hash.
+ * - "unchanged" — marker exists and hash matches (or marker has no hash, which
+ *                 is treated conservatively as unchanged).
+ */
+export declare function classifyItem(id: string, body: string, map: Map<string, SeenMarker>): "new" | "edited" | "unchanged";
+/**
+ * Read the seen/ directory once and return a Set of already-seen IDs.
+ * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
+ * Returns an empty Set if the directory does not yet exist.
+ */
+export declare function loadSeenSet(key: StateKey): Promise<Set<string>>;
+/**
+ * Read the seen/ directory and return a Map from ID to SeenMarker.
+ * Used when the caller needs the stored bodyHash to detect in-place edits.
+ * Returns an empty Map if the directory does not yet exist.
+ *
+ * Map keys are the stored `id` field when present (guarding against
+ * case-insensitive filesystem collisions), falling back to the filename for
+ * legacy markers that predate this field.
+ */
+export declare function loadSeenMap(key: StateKey): Promise<Map<string, SeenMarker>>;
+/** Return true if a "seen" marker exists for this id. */
+export declare function hasSeen(key: StateKey, id: string): Promise<boolean>;
+/**
+ * Write (or update) a "seen" marker for this id, storing the body hash so
+ * in-place edits can be detected on future fetches.
+ *
+ * - First call (no existing marker): creates `{ seenAt: now, bodyHash, id }`.
+ * - Subsequent call, hash unchanged: no-op (skips the write).
+ * - Subsequent call, hash changed: updates `bodyHash`, preserves original `seenAt`.
+ *
+ * All errors are silently swallowed — the marker is best-effort.
+ */
+export declare function markSeen(key: StateKey, id: string, body: string): Promise<void>;
+export declare function markReviewInlineThreads(key: StateKey, reviewId: string, inlineThreadIds: readonly string[]): Promise<void>;
+/**
+ * Write a marker after Shepherd successfully replies to a review thread.
+ *
+ * `previousBody` suppresses stale GitHub fetches that have not yet included the new reply.
+ * `body` suppresses the expected final transcript once GitHub includes Shepherd's reply.
+ */
+export declare function markReplySeen(key: StateKey, id: string, previousBody: string, body: string, replyBody: string): Promise<void>;
+/** Read the full marker for inspection (returns null on miss or error). */
+export declare function readSeenMarker(key: StateKey, id: string): Promise<SeenMarker | null>;
+export {};

package/bin/state/seen-comments.mjs

@@ -3,7 +3,7 @@ import { readFile, writeFile, rename, unlink, mkdir, access, readdir } from "nod
 import { join, dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { resolvePrStatePath } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -57,7 +57,9 @@ export async function loadSeenMap(key) {
     try {
         const dir = resolveDir(key);
         const entries = await readdir(dir);
-        for (const entry of entries.filter((e) => e.endsWith(".json"))) {
+        for (const entry of entries) {
+            if (!entry.endsWith(".json") || !SAFE_SEGMENT.test(entry))
+                continue;
             try {
                 const raw = await readFile(join(dir, entry), "utf8");
                 const marker = JSON.parse(raw);
@@ -182,16 +184,7 @@ export async function readSeenMarker(key, id) {
 // Helpers
 // ---------------------------------------------------------------------------
 function resolveDir(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "seen");
+    return resolvePrStatePath(key, "seen");
 }
 function resolvePath(key, id) {
     if (!SAFE_SEGMENT.test(id)) {
@@ -203,5 +196,5 @@ function resolvePath(key, id) {
     // causing seen-markers to overwrite each other and items to re-surface every
     // tick. SHA-256 is case-sensitive so distinct IDs get distinct files.
     const hash = createHash("sha256").update(id, "utf8").digest("hex");
-    return join(resolveDir(key), `${hash}.json`);
+    return resolvePrStatePath(key, "seen", `${hash}.json`);
 }

package/bin/suggestions/extract.d.mts

@@ -0,0 +1,8 @@
+import type { SuggestionBlock } from "../types.mts";
+export declare function extractSuggestion(thread: {
+    path: string | null;
+    line: number | null;
+    startLine: number | null;
+    body: string;
+    author: string;
+}): SuggestionBlock | null;

package/bin/suggestions/parse.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Parse GitHub review-comment "suggestion" blocks.
+ *
+ * GitHub's "Commit suggestion" UI button treats the first ```suggestion fenced
+ * block in a review comment as a replacement for the commented line range.
+ * This module extracts that block from the comment body.
+ *
+ * There is no GitHub API for applying suggestions — tools that reproduce the
+ * button (this one included) must parse + commit themselves.
+ */
+interface ParsedSuggestion {
+    /**
+     * Replacement lines to splice in. Empty array means "delete these lines".
+     * `[""]` means "replace with a single blank line". Array length equals the
+     * number of replacement lines in the suggestion snippet (not the number of
+     * lines in the resulting file).
+     */
+    lines: readonly string[];
+}
+/**
+ * Return the first ```suggestion block from a review-comment body, or null if none.
+ *
+ * Handles three distinct cases:
+ *   - Empty block (` ```suggestion\n``` `) → `lines: []` (deletion).
+ *   - Blank-line-only body (` ```suggestion\n\n``` `) → `lines: [""]`.
+ *   - Non-empty body → split into lines.
+ *
+ * The opening fence may be 3+ backticks; the closing fence must be at least
+ * as many backticks, at the start of a line (after the captured prefix). This
+ * means content lines that contain ` ``` ` in the middle (not at line-start)
+ * are treated as content rather than a closing fence — fixing the silent
+ * truncation in the original regex approach (issue #68).
+ *
+ * When the block is embedded in a quoted reply (e.g. `> ```suggestion …`),
+ * the leading prefix captured from the opening fence is stripped from each
+ * body line — but only when that exact prefix is present, so legitimate `>`
+ * characters inside the suggested code survive.
+ */
+export declare function parseSuggestion(body: string): ParsedSuggestion | null;
+/**
+ * True when a parsed suggestion's replacement is safe to commit: the joined
+ * replacement contains no nested ` ```suggestion ` marker and no unmatched
+ * ` ``` ` run (odd count). Both shapes previously masked silent truncation
+ * (issue #68). Conservative by design: reviewers whose suggestion content
+ * legitimately includes these markers must apply the change manually.
+ */
+export declare function isCommittableSuggestion(parsed: ParsedSuggestion): boolean;
+export {};