pr-shepherd 0.60.1 → 1.0.0

package/bin/github/poll-summary-route.mjs

@@ -3,26 +3,26 @@ import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evi
 import { canGenerateGithubMutation } from "./mutation-policy.mjs";
 import { getGithubTransport, isCcrTransport } from "./transport.mjs";
 export function routePollSummary(raw, checks, review, opts) {
-    const actions = loadConfig().actions;
+    const config = loadConfig();
     const state = normalizePollSummaryState(raw.state);
     if (state === "MERGED" || state === "CLOSED") {
         return { action: "cancel", reasons: [state.toLowerCase()] };
     }
     if (raw.mergeable === "CONFLICTING" || raw.mergeStateStatus === "DIRTY") {
-        return { action: "fix_code", reasons: ["merge-conflicts"] };
+        return { action: "triage", reasons: ["merge-conflicts"] };
     }
     if ((checks.failing ?? 0) > 0)
-        return { action: "fix_code", reasons: ["failing-checks"] };
+        return { action: "triage", reasons: ["failing-checks"] };
     if ((review.actionable ?? 0) > 0) {
-        if (opts.merge && raw.isInMergeQueue && actions.workWhileQueued !== true) {
+        if (opts.merge && raw.isInMergeQueue && config.actions["work-while-queued"] !== true) {
             return { action: "wait", reasons: ["review-work-deferred-while-queued"] };
         }
-        return { action: "fix_code", reasons: ["review-work"] };
+        return { action: "triage", reasons: ["review-work"] };
     }
     if ((checks.unreportedRequired?.length ?? 0) > 0 &&
         checks.actionsWorkflowInProgress !== true &&
         (checks.inProgress ?? 0) === 0) {
-        return { action: "fix_code", reasons: ["unreported-required-checks"] };
+        return { action: "triage", reasons: ["unreported-required-checks"] };
     }
     if ((checks.inProgress ?? 0) > 0 ||
         !isKnownMergeStateStatus(raw.mergeStateStatus) ||
@@ -39,9 +39,9 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "wait", reasons: ["pending-or-unknown"] };
     }
     if (raw.isDraft) {
-        const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
+        const autoMarkReadyDisabled = opts.noAutoMarkReady || config["mark-ready"].auto === false;
         if (autoMarkReadyDisabled && (checks.incomplete || review.incomplete))
-            return { action: "fix_code", reasons: ["draft-readiness-verification-required"] };
+            return { action: "triage", reasons: ["draft-readiness-verification-required"] };
         if (autoMarkReadyDisabled)
             return { action: "cancel", reasons: ["draft-auto-mark-ready-disabled"] };
         if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready")) {
@@ -59,7 +59,7 @@ export function routePollSummary(raw, checks, review, opts) {
         };
     }
     if (opts.merge && raw.stack && opts.stackPrNumber === undefined) {
-        return { action: "fix_code", reasons: ["authoritative-poll-required"] };
+        return { action: "triage", reasons: ["authoritative-poll-required"] };
     }
     if (opts.merge && raw.stack) {
         return { action: "merge", reasons: ["appears-ready"] };

package/bin/github/poll-summary-unreported.mjs

@@ -33,7 +33,7 @@ export function applyUnreportedRequiredChecks(raw, checks, required) {
         return;
     checks.unreportedRequired = missing;
     const suites = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
-    if (actionsWorkflowInProgress(suites, new Set(loadConfig().checks.ciTriggerEvents))) {
+    if (actionsWorkflowInProgress(suites, new Set(loadConfig().checks["ci-trigger-events"]))) {
         checks.actionsWorkflowInProgress = true;
     }
 }

package/bin/github/poll-summary.mjs

@@ -20,7 +20,7 @@ async function fetchSelectedPollSummary(opts, repo) {
         return fetchStackSummary(opts, repo);
     const requested = [...new Set(opts.prNumbers ?? [])];
     if (requested.length === 0) {
-        throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
+        throw new ShepherdError("Aggregate poll requires at least two PRs or a stack PR", EXIT.USAGE);
     }
     const raw = [];
     let viewerCanAdminister;

package/bin/github/queries.d.mts

@@ -43,7 +43,7 @@ export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */
 export declare const MERGED_BASE_PULL_REQUESTS_QUERY: string;
-/** PR head fields plus a single review thread for `commit-suggestion`. */
+/** PR head fields plus the requested review threads for `suggest`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;

package/bin/github/queries.mjs

@@ -48,7 +48,7 @@ export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.gql");
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */
 export const MERGED_BASE_PULL_REQUESTS_QUERY = gql("merged-base-pull-requests.gql");
-/** PR head fields plus a single review thread for `commit-suggestion`. */
+/** PR head fields plus the requested review threads for `suggest`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");

package/bin/mcp/server.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
 import { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrReference, } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
+import { formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
 import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { projectStackOverview } from "../cli/stack-overview.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
@@ -13,6 +13,7 @@ import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 import { formatApplyMergeResult } from "../cli/apply-merge-handler.mjs";
 import { extractShepherdJournal } from "../journal/index.mjs";
 import { formatPlaybookResult, runPlaybook } from "../commands/playbook.mjs";
+import { formatCheckBlockerResult } from "../commands/apply-check-blocker.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
     .string()
@@ -20,12 +21,8 @@ const pr = z
     .describe("GitHub pull-request URL or owner/repo#number; the explicit repository may differ from the server working directory");
 const ids = z.array(z.string().min(1)).optional();
 const transport = z.enum(["auto", "graphql", "rest"]).optional();
-const iterateInputSchema = z
-    .object({
+const tickOptionsSchema = {
     transport,
-    pr: pr.optional(),
-    prs: z.array(pr).min(1).optional(),
-    stack: pr.optional(),
     readyDelaySeconds: z.number().nonnegative().optional(),
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
@@ -33,25 +30,20 @@ const iterateInputSchema = z
     instructions: z
         .enum(["playbook", "inline"])
         .optional()
-        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Fix-code loop playbook."),
-    pollMode: z
-        .enum(["auto", "poll", "event"])
-        .optional()
-        .describe("Overrides poll.mode. event returns one tick with pollMode and nextCheck so the caller owns the wake-up; auto (default) selects event when CLAUDE_CODE_REMOTE=true."),
-    noAutoCancelActionable: z
-        .boolean()
-        .optional()
-        .describe("Deprecated no-op; Shepherd never cancels workflow runs."),
-    neverCancelRuns: z
-        .array(z.string())
-        .optional()
-        .describe("Deprecated per-call no-op retained for compatibility."),
+        .describe("triage instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Triage loop playbook."),
+};
+const iterateInputSchema = z
+    .object({
+    ...tickOptionsSchema,
+    pr: pr.optional(),
+    prs: z.array(pr).min(1).optional(),
 })
-    .refine((input) => [input.pr, input.prs, input.stack].filter((value) => value !== undefined).length === 1, {
-    message: "exactly one of pr, prs, or stack is required",
+    .refine((input) => (input.pr === undefined) !== (input.prs === undefined), {
+    message: "exactly one of pr or prs is required",
 })
     .refine((input) => !input.prs ||
     new Set(input.prs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? ""))).size === 1, { message: "all prs must belong to the same repository" });
+const stackInputSchema = z.object({ ...tickOptionsSchema, pr });
 const reviewMutationsOperationSchema = z.object({
     type: z.literal("review_mutations"),
     resolveThreadIds: ids,
@@ -78,6 +70,16 @@ const acknowledgeQueueRemovalOperationSchema = z.object({
     queueCommitOid: z.string().regex(/^[0-9a-f]{40}$/),
     removedAtUnix: z.number().int().positive().safe(),
 });
+const checkBlockerOperationSchema = z.object({
+    type: z.literal("check_blocker"),
+    check: z.string().min(1).describe("Exact check name."),
+    blockedBy: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Blocking PR/issue URL, owner/repo#N, or issue:owner/repo#N."),
+    clear: z.boolean().optional().describe("Clear the recorded blocker instead of setting one."),
+});
 const mergeOperationSchema = z.object({
     type: z.literal("merge"),
     requireSha: z.string().regex(/^[0-9a-f]{40}$/),
@@ -109,17 +111,11 @@ const applyInputSchema = z.object({
         markFilesViewedOperationSchema,
         appendJournalOperationSchema,
         acknowledgeQueueRemovalOperationSchema,
+        checkBlockerOperationSchema,
     ]))
         .min(1),
 });
-const suggestionPatchInputSchema = z.object({
-    transport,
-    pr,
-    threadId: z.string().min(1),
-    message: z.string().min(1),
-    description: z.string().optional(),
-});
-const suggestionPatchesInputSchema = z.object({
+const suggestInputSchema = z.object({
     transport,
     pr,
     suggestions: z
@@ -136,7 +132,7 @@ export function createPrShepherdMcpServer(options = {}) {
     const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd, transport: options.transport }));
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
-        description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
+        description: "Inspect one pull request (pr) or an explicit same-repository set (prs) and return one Shepherd tick.",
         inputSchema: iterateInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -151,14 +147,20 @@ export function createPrShepherdMcpServer(options = {}) {
         };
         return runTool(() => runIterateSelector(getShepherd(), requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
-            : formatIterateResult(result, opts), (result) => isPollSummary(result)
-            ? result.selection.kind === "stack"
-                ? projectStackOverview(result)
-                : result
-            : projectIterateLean(result, opts));
+            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
     });
+    server.registerTool("stack", {
+        description: "Inspect the native stack containing one pull request and return one aggregate Shepherd tick.",
+        inputSchema: stackInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => getShepherd().stack(requireRepositoryQualifiedPr(input)), formatPollSummaryResult, projectStackOverview));
     server.registerTool("apply", {
-        description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
+        description: "Apply ordered merge, review, file-view, journal, check-blocker, and queue-removal operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -202,38 +204,28 @@ export function createPrShepherdMcpServer(options = {}) {
             openWorldHint: false,
         },
     }, async (input) => runTool(async () => runPlaybook(input.name), formatPlaybookResult));
-    server.registerTool("build_suggestion_patches", {
+    server.registerTool("suggest", {
         description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
-        inputSchema: suggestionPatchesInputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
-    }, async (input) => runTool(() => getShepherd().buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
-    server.registerTool("build_suggestion_patch", {
-        description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
-        inputSchema: suggestionPatchInputSchema,
+        inputSchema: suggestInputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => getShepherd().buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
+    }, async (input) => runTool(() => getShepherd().suggest(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     return server;
 }
 function runIterateSelector(shepherd, input) {
-    return "prs" in input || "stack" in input
+    return "prs" in input && input.prs !== undefined
         ? shepherd.iterate(input)
         : shepherd.iterate(input);
 }
 function requireRepositoryQualifiedIterate(input) {
-    if ([input.pr, input.prs, input.stack].filter((value) => value !== undefined).length !== 1) {
-        throw new PrShepherdValidationError("exactly one of pr, prs, or stack is required");
+    if ((input.pr === undefined) === (input.prs === undefined)) {
+        throw new PrShepherdValidationError("exactly one of pr or prs is required");
     }
-    const refs = Array.isArray(input.prs) ? input.prs : [input.pr ?? input.stack];
+    const refs = Array.isArray(input.prs) ? input.prs : [input.pr];
     if (refs.length === 0 || refs.some((ref) => !isRepositoryQualifiedPrReference(ref))) {
         throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);
     }
@@ -264,7 +256,7 @@ function toolResult(structured, text) {
 }
 /**
  * `project` mirrors the CLI's `--format=json` treatment of the same result. Tools
- * whose CLI JSON is the raw result object (apply, build_suggestion_patch(es) — see
+ * whose CLI JSON is the raw result object (apply, suggest — see
  * handlers.mts and cli-parser.mts, which JSON.stringify the result directly) omit
  * `project` and return the result unchanged, matching their own CLI JSON output.
  */
@@ -290,6 +282,8 @@ function formatApplyResult(result) {
                 return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
             case "append_journal":
                 return `${heading}\n\n${formatJournalResult(operation.result)}`;
+            case "check_blocker":
+                return `${heading}\n\n${formatCheckBlockerResult(operation.result)}`;
             case "acknowledge_queue_removal": {
                 const result = operation.result;
                 return [

package/bin/merge-status/derive.mjs

@@ -70,7 +70,7 @@ function detectBlockingBotReview(pr) {
     // A blocking bot review is "in progress" when:
     //   1. Any reviewRequest has a login starting with one of the configured prefixes, OR
     //   2. Any latestReview has such a login AND state == "PENDING"
-    const prefixes = loadConfig().mergeStatus.blockingReviewerLogins.map((l) => l.toLowerCase());
+    const prefixes = loadConfig()["mark-ready"]["blocking-reviewer-logins"].map((l) => l.toLowerCase());
     const isBlocking = (login) => prefixes.some((p) => login.toLowerCase().startsWith(p));
     const requested = pr.reviewRequests.some((r) => isBlocking(r.login));
     const pendingReview = pr.latestReviews.some((r) => isBlocking(r.login) && r.state === "PENDING");

package/bin/state/durable-state.d.mts

@@ -1,6 +1,4 @@
-/** Run work whose state (seen markers, stall timers, reply records) must outlive a temp dir. */
-export declare function runWithDurableState<T>(work: () => T): T;
-/** Cloud sessions are always durable; other callers opt in through `runWithDurableState`. */
+/** Cloud sessions keep state (seen markers, stall timers, reply records) beyond a temp dir. */
 export declare function durableStateRequested(): boolean;
 /** `<git-common-dir>/pr-shepherd-state`, or null when not requested or outside a repository. */
 export declare function resolveDurableStateBase(): string | null;

package/bin/state/durable-state.mjs

@@ -1,5 +1,4 @@
 import { execFileSync } from "node:child_process";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { join, resolve } from "node:path";
 import { getEffectiveCwd } from "../execution-context.mjs";
 /**
@@ -7,15 +6,10 @@ import { getEffectiveCwd } from "../execution-context.mjs";
  * directory lives with the repository checkout, so state stored there survives whatever the
  * session does with `TMPDIR`. Only a read-only `git rev-parse` is ever invoked.
  */
-const durableScope = new AsyncLocalStorage();
 const commonDirByCwd = new Map();
-/** Run work whose state (seen markers, stall timers, reply records) must outlive a temp dir. */
-export function runWithDurableState(work) {
-    return durableScope.run(true, work);
-}
-/** Cloud sessions are always durable; other callers opt in through `runWithDurableState`. */
+/** Cloud sessions keep state (seen markers, stall timers, reply records) beyond a temp dir. */
 export function durableStateRequested() {
-    return durableScope.getStore() === true || process.env["CLAUDE_CODE_REMOTE"] === "true";
+    return process.env["CLAUDE_CODE_REMOTE"] === "true";
 }
 /** `<git-common-dir>/pr-shepherd-state`, or null when not requested or outside a repository. */
 export function resolveDurableStateBase() {

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

@@ -2,14 +2,14 @@
  * Persistent attempt counter for the iterate escalation guard.
  *
  * Tracks how many caller-visible times each review thread has been dispatched to
- * the fix_code handler without being resolved. Body edits reset the count.
+ * the triage handler without being resolved. Body edits reset the count.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
     /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */
     headSha: string;
-    /** Map from thread ID → number of fix_code dispatches that included this thread. */
+    /** Map from thread ID → number of triage 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>;

package/bin/state/fix-attempts.mjs

@@ -2,7 +2,7 @@
  * Persistent attempt counter for the iterate escalation guard.
  *
  * Tracks how many caller-visible times each review thread has been dispatched to
- * the fix_code handler without being resolved. Body edits reset the count.
+ * the triage handler without being resolved. Body edits reset the count.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/fix-attempts.json`.
  */

package/bin/state/merge-request.mjs

@@ -100,7 +100,7 @@ export async function replaceFailedMergeRequest(key, previous, next) {
                 throw error;
             persisted = parseRecord(await readFile(`${stem}.json`, "utf8"));
             if (!persisted.replacementToken)
-                throw new Error("Legacy merge successor has no recovery token; reconcile its outcome");
+                throw new Error("Merge successor has no recovery token; reconcile its outcome");
             if (persisted.options.requireSha !== next.options.requireSha ||
                 persisted.options.mergeAction !== next.options.mergeAction ||
                 persisted.options.mergeMethod !== next.options.mergeMethod ||

package/bin/state/pr-fingerprint.mjs

@@ -5,7 +5,7 @@ import { dirname } from "node:path";
 import { resolvePrStatePath } from "./base.mjs";
 import { discoverRuleFiles } from "../classify/loader.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
-const VERSION = 4;
+const VERSION = 5;
 let packageVersion;
 /** Bundled standard rules change with the package, so their digest input is its version. */
 function readPackageVersion() {
@@ -15,18 +15,11 @@ function readPackageVersion() {
 export function fingerprintInputDigest(config) {
     const hash = createHash("sha256");
     hash.update(JSON.stringify({
-        ignoreChecks: config.ignoreChecks,
-        botUsernames: config.botUsernames,
+        "bot-usernames": config["bot-usernames"],
         iterate: config.iterate,
-        watch: { readyDelayMinutes: config.watch.readyDelayMinutes },
         checks: config.checks,
-        mergeStatus: config.mergeStatus,
-        actions: {
-            autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-            autoMarkReady: config.actions.autoMarkReady,
-            neverCancelRuns: config.actions.neverCancelRuns,
-            workWhileQueued: config.actions.workWhileQueued,
-        },
+        "mark-ready": config["mark-ready"],
+        actions: config.actions,
         standardRules: (config.standardRules?.length ?? 0) > 0
             ? { names: config.standardRules, version: readPackageVersion() }
             : undefined,

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

@@ -16,8 +16,8 @@ export declare function hashBody(body: string): string;
  * - "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).
+ * - "unchanged" — marker exists and hash matches (or marker has no hash and no
+ *                 inline thread IDs, which is treated conservatively as unchanged).
  */
 export declare function classifyItem(id: string, body: string, map: Map<string, SeenMarker>): "new" | "edited" | "unchanged";
 /**
@@ -31,9 +31,8 @@ export declare function loadSeenSet(key: StateKey): Promise<Set<string>>;
  * 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.
+ * Map keys are the stored `id` field (guarding against case-insensitive
+ * filesystem collisions); markers without one are skipped.
  */
 export declare function loadSeenMap(key: StateKey): Promise<Map<string, SeenMarker>>;
 /** Return true if a "seen" marker exists for this id. */

package/bin/state/seen-comments.mjs

@@ -17,8 +17,8 @@ export function hashBody(body) {
  * - "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).
+ * - "unchanged" — marker exists and hash matches (or marker has no hash and no
+ *                 inline thread IDs, which is treated conservatively as unchanged).
  */
 export function classifyItem(id, body, map) {
     const m = map.get(id);
@@ -48,9 +48,8 @@ export async function loadSeenSet(key) {
  * 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.
+ * Map keys are the stored `id` field (guarding against case-insensitive
+ * filesystem collisions); markers without one are skipped.
  */
 export async function loadSeenMap(key) {
     const map = new Map();
@@ -63,14 +62,8 @@ export async function loadSeenMap(key) {
             try {
                 const raw = await readFile(join(dir, entry), "utf8");
                 const marker = JSON.parse(raw);
-                // Prefer the stored id field; fall back to filename stem for legacy markers.
-                const mapKey = typeof marker.id === "string" ? marker.id : entry.slice(0, -5);
-                // Hash-based markers (those with an id field) take priority over legacy
-                // filename-based markers so that a stale legacy file cannot overwrite a
-                // newer hash-based entry that maps to the same key.
-                if (!map.has(mapKey) || typeof marker.id === "string") {
-                    map.set(mapKey, marker);
-                }
+                if (typeof marker.id === "string")
+                    map.set(marker.id, marker);
             }
             catch {
                 // unreadable or malformed — skip
@@ -155,7 +148,8 @@ async function writeSeenMarker(key, id, markerFields) {
             // no existing marker — will create below
         }
         const unchanged = Object.entries(markerFields).every(([field, value]) => markerFieldEqual(existing?.[field], value));
-        if (existing !== null && unchanged)
+        // A marker without its `id` is ignored by loadSeenMap, so rewrite it even when unchanged.
+        if (existing !== null && unchanged && existing.id === id)
             return;
         const seenAt = existing?.seenAt ?? Date.now();
         tmp = `${path}.${randomUUID()}.tmp`;

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

@@ -1,5 +1,5 @@
 /**
- * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * Persistent stall-detection state for an aggregate `stack` selection whose open layers can
  * only wait. Keyed by native stack number because the anchor PR can merge or change.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.

package/bin/state/stack-stall.mjs

@@ -1,5 +1,5 @@
 /**
- * Persistent stall-detection state for an aggregate `--stack` selection whose open layers can
+ * Persistent stall-detection state for an aggregate `stack` selection whose open layers can
  * only wait. Keyed by native stack number because the anchor PR can merge or change.
  *
  * State lives in `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/stack-<number>/stack-stall.json`.

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

@@ -27,7 +27,7 @@ export interface StallStateStore<Key> {
     clear(key: Key): Promise<void>;
 }
 /**
- * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `stack` stall guards.
  * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
  * so the caller can hand off instead of treating every tick as the first sighting.
  * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one

package/bin/state/stall-state-store.mjs

@@ -2,7 +2,7 @@ import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 /**
- * `{fingerprint, firstSeenAt}` files behind the one-PR and `--stack` stall guards.
+ * `{fingerprint, firstSeenAt}` files behind the one-PR and `stack` stall guards.
  * A missing file is a miss. An unwritable directory or an unsafe key is a persistence failure
  * so the caller can hand off instead of treating every tick as the first sighting.
  * `ENOENT` is the only read error treated as a miss. Corrupt JSON is also a miss, so one

package/bin/types/escalate.d.mts

@@ -2,7 +2,7 @@ import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "transport-unsupported" | "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
+export type EscalateTrigger = "transport-unsupported" | "triage-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -32,7 +32,7 @@ export interface EscalateDetails {
         attempts: number;
     }>;
     /**
-     * Set only when `iterate.reviewOutputMaxChars` held review items back on the tick that
+     * Set only when `iterate.review-output-max-chars` held review items back on the tick that
      * escalated: `shown` of `total` review items appear here. The held items stay unmarked, so the
      * next run shows them.
      */