pr-shepherd 0.59.0 → 0.59.2

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -1,12 +1,24 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { isDraftReadinessVerification } from "./stack-work.mjs";
 /** Every selected row already returned `CANCEL` or `ESCALATE`: no autonomous work remains. */
 export function isHandedOffSelection(result) {
     return (result.prs.length > 0 &&
         result.prs.every((item) => item.action === "cancel" || item.action === "escalate"));
 }
+/** A final full-review probe can finish this selection without another aggregate read. */
+export function onlyDraftVerificationSelection(result) {
+    return (result.prs.some(isDraftReadinessVerification) &&
+        result.prs.every((item) => item.action === "cancel" ||
+            item.action === "escalate" ||
+            isDraftReadinessVerification(item)));
+}
 export function explicitInstructions(result) {
     if (result.reason === "all_terminal")
-        return ["1. Stop — every selected PR is terminal."];
+        return [
+            result.prs.some((item) => item.reasons.includes("draft-auto-mark-ready-disabled"))
+                ? "1. Stop — every selected PR is complete for this Shepherd run."
+                : "1. Stop — every selected PR is terminal.",
+        ];
     if (result.quotaWarning && result.reason !== "actionable") {
         return [
             buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
@@ -20,7 +32,11 @@ export function explicitInstructions(result) {
         "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
         "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
     ];
-    if (isHandedOffSelection(result)) {
+    if (onlyDraftVerificationSelection(result)) {
+        instructions[2] =
+            "3. If every draft verification probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, stop this selection and report any `ESCALATE` rows; leave the drafts unchanged. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow the probes' instructions and rerun this aggregate selector when that work completes.";
+    }
+    else if (isHandedOffSelection(result)) {
         instructions[2] =
             "3. Stop after reporting each `ESCALATE` handoff; every selected row is `CANCEL` or `ESCALATE`, so do not run this aggregate poll again.";
     }

package/bin/commands/poll-summary-instructions.mjs

@@ -2,7 +2,7 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
 import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
-import { appendMarkReadyInstructions, appendStackRerunInstruction, splitStackWork, } from "./stack-work.mjs";
+import { appendStackRerunInstruction, onlyDraftReadinessVerification, splitStackWork, } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
     return planPollSummary(result, mergeRequested).result;
@@ -19,7 +19,8 @@ export function planPollSummary(result, mergeRequested) {
         prs: prs.map((item) => {
             const needsOwnSession = item.state === "OPEN" &&
                 (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
-                ["cancel", "merge"].includes(item.action);
+                ["cancel", "merge"].includes(item.action) &&
+                (!item.reasons.includes("draft-auto-mark-ready-disabled") || staleChildren.has(item.pr));
             const layer = needsOwnSession
                 ? {
                     ...item,
@@ -51,6 +52,11 @@ export function planPollSummary(result, mergeRequested) {
                     reasons: [...layer.reasons, "unverified-stack-state"],
                 };
             }
+            if (layer.reasons.includes("draft-auto-mark-ready-disabled") &&
+                !staleChildren.has(layer.pr)) {
+                const { pollCommand: _pollCommand, pollProbe: _pollProbe, ...held } = layer;
+                return held;
+            }
             return layer;
         }),
     };
@@ -84,9 +90,9 @@ function planStack(result, mergeRequested) {
     const work = splitStackWork(open.filter((item) => (!isStackLayerReady(item) || staleChildren.has(item.pr)) && item.action !== "escalate"), staleChildren);
     const runnableCandidates = work.sessions.filter((item) => item.pollCommand);
     const missingCommands = work.sessions.filter((item) => !item.pollCommand);
-    const agentWork = runnableCandidates.length > 0 || work.markReady.length > 0;
+    const agentWork = runnableCandidates.length > 0;
     // Only owned work defers a human handoff: rerunning cannot advance another author's layer.
-    const ownedWork = [...runnableCandidates, ...work.markReady].some((item) => item.owned);
+    const ownedWork = runnableCandidates.some((item) => item.owned);
     const drain = planPrefixDrain(result, mergeRequested);
     if (drain)
         return drain;
@@ -94,14 +100,17 @@ function planStack(result, mergeRequested) {
     if (handoffs) {
         const instructions = [];
         appendAutonomousInstructions(instructions, runnableCandidates);
-        appendMarkReadyInstructions(instructions, work.markReady);
         const stop = !ownedWork;
         appendHumanHandoffInstructions(instructions, handoffs, stop);
         for (const item of missingCommands) {
             instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. Ask for direction.`);
         }
         if (ownedWork) {
-            appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
+            const rerun = onlyDraftReadinessVerification(work.sessions, work.idle) &&
+                work.sessions.every((item) => item.owned)
+                ? "If every listed one-PR probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, report the human handoff above and stop this selector. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same `--stack` selector when that work completes."
+                : "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.";
+            appendStackRerunInstruction(instructions, runnableCandidates, rerun);
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
     }
@@ -116,21 +125,34 @@ function planStack(result, mergeRequested) {
         if (missingCommands.length > 0) {
             const instructions = [];
             appendAutonomousInstructions(instructions, runnableCandidates);
-            appendMarkReadyInstructions(instructions, work.markReady);
             for (const item of missingCommands) {
                 instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${ownedWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
             }
             if (ownedWork) {
-                appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
+                appendStackRerunInstruction(instructions, runnableCandidates, "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
             }
             return { action: ownedWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
-        if (!agentWork)
+        if (!agentWork) {
+            if (work.held.length > 0 && work.idle.length === 0) {
+                return {
+                    action: "cancel",
+                    stackMergeable: false,
+                    instructions: [
+                        `1. Stop shepherding this stack. Automatic mark-ready is disabled and ${work.held.map((item) => `PR #${item.pr}`).join(", ")} ${work.held.length === 1 ? "is" : "are"} clean but still in draft.`,
+                    ],
+                };
+            }
             return idleWaitPlan(work.idle);
+        }
         const instructions = [];
         appendAutonomousInstructions(instructions, work.sessions);
-        appendMarkReadyInstructions(instructions, work.markReady);
-        const action = appendStackRerunInstruction(instructions, [...work.sessions, ...work.markReady], "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        if (onlyDraftReadinessVerification(work.sessions, work.idle) &&
+            work.sessions.every((item) => item.owned)) {
+            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same \`--stack\` selector when that work completes.`);
+            return { action: "shepherd", stackMergeable: false, instructions };
+        }
+        const action = appendStackRerunInstruction(instructions, work.sessions, "After the selected one-PR sessions, rerun this same `--stack` selector.");
         return { action, stackMergeable: false, instructions };
     }
     if (open.some((item) => item.isInMergeQueue)) {

package/bin/commands/stack-drain.mjs

@@ -2,7 +2,7 @@ import { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-hando
 export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
-import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+import { splitStackWork } from "./stack-work.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { buildMergeCommandPlan, renderMergeCommand } from "./iterate/merge.mjs";
 function readyPrefixTop(result) {
@@ -89,7 +89,6 @@ export function planPrefixDrain(result, mergeRequested) {
         instructions[0] = `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\`, then rerun that merge command. Do not rebase, push, or run \`gh stack push\`.`;
     }
     appendAutonomousInstructions(instructions, above.sessions);
-    appendMarkReadyInstructions(instructions, above.markReady);
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);

package/bin/commands/stack-work.d.mts

@@ -1,37 +1,24 @@
 import type { PollSummaryItem } from "../types.mts";
-type ProbedLayer = PollSummaryItem & {
-    pollCommand: string;
-    pollProbe: true;
-};
-/**
- * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
- * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
- */
-export declare const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
 /** How the stack selector routes the autonomous layers that still need work. */
 export interface StackWork {
     /** Layers that need a one-PR Shepherd session, with or without a known command. */
     sessions: PollSummaryItem[];
-    /** Clean, unblocked drafts that the agent marks ready because the poll loop will not. */
-    markReady: ProbedLayer[];
+    /** Clean drafts held by the disabled ready transition. No more work is scheduled for them. */
+    held: PollSummaryItem[];
     /** Layers whose bounded probe could only report that they are still waiting. */
-    idle: ProbedLayer[];
+    idle: PollSummaryItem[];
 }
+export declare function isDraftReadinessVerification(item: PollSummaryItem): boolean;
+/** A full one-PR check is the final task when the compact review sample was incomplete. */
+export declare function onlyDraftReadinessVerification(sessions: PollSummaryItem[], idle: PollSummaryItem[]): boolean;
 /**
- * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
- * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * Split autonomous stack candidates by what the agent can do for each. A clean draft held by
+ * disabled mark-ready is complete for this run. Other bounded waits stay idle.
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
-/**
- * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context.
- */
-export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
 /**
  * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
  */
 export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";
-export {};

package/bin/commands/stack-work.mjs

@@ -1,24 +1,23 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { formatPrUrl } from "../pr-reference.mjs";
-/**
- * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
- * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
- */
-export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+export function isDraftReadinessVerification(item) {
+    return item.reasons?.includes("draft-readiness-verification-required") === true;
+}
+/** A full one-PR check is the final task when the compact review sample was incomplete. */
+export function onlyDraftReadinessVerification(sessions, idle) {
+    return sessions.length > 0 && idle.length === 0 && sessions.every(isDraftReadinessVerification);
+}
 /**
- * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
- * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * Split autonomous stack candidates by what the agent can do for each. A clean draft held by
+ * disabled mark-ready is complete for this run. Other bounded waits stay idle.
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export function splitStackWork(candidates, staleChildren) {
-    const work = { sessions: [], markReady: [], idle: [] };
+    const work = { sessions: [], held: [], idle: [] };
     for (const item of candidates) {
-        if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
-            work.sessions.push(item);
+        if (item.reasons.includes("draft-auto-mark-ready-disabled") && !staleChildren.has(item.pr)) {
+            work.held.push(item);
         }
-        else if (item.reasons.includes("draft-auto-mark-ready-disabled")) {
-            work.markReady.push(item);
+        else if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
+            work.sessions.push(item);
         }
         else {
             work.idle.push(item);
@@ -26,29 +25,6 @@ export function splitStackWork(candidates, staleChildren) {
     }
     return work;
 }
-/**
- * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context.
- */
-export function appendMarkReadyInstructions(instructions, layers) {
-    for (const item of layers) {
-        if (!item.owned) {
-            instructions.push(`${instructions.length + 1}. PR #${item.pr} is not owned. Leave its draft state unchanged.`);
-            continue;
-        }
-        if (item.transport === "rest") {
-            const command = buildPrShepherdCommand([
-                "iterate",
-                formatPrUrl(item.repo, item.pr),
-                "--transport",
-                "rest",
-            ]).text;
-            instructions.push(`${instructions.length + 1}. Run \`${item.pollCommand}\` first for PR #${item.pr}. If it returns \`[WAIT]\` saying the draft is held only because automatic mark-ready is disabled, run \`${command}\` to authorize the CCR ready transition; otherwise follow the probe's instructions.`);
-            continue;
-        }
-        instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
-    }
-}
 function isProbed(item) {
     return item.pollProbe === true && item.pollCommand !== undefined;
 }

package/bin/exit-codes.d.mts

@@ -12,7 +12,7 @@
 import type { IterateResult } from "./types.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
 export declare const EXIT: Readonly<{
-    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    /** Clean terminal stop, including a draft held by disabled automatic mark-ready. */
     readonly OK: 0;
     /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     readonly WAIT: 10;

package/bin/exit-codes.mjs

@@ -10,7 +10,7 @@
  * ran to completion and is reporting PR state. See docs/exit-codes.md.
  */
 export const EXIT = Object.freeze({
-    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    /** Clean terminal stop, including a draft held by disabled automatic mark-ready. */
     OK: 0,
     /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     WAIT: 10,
@@ -55,6 +55,7 @@ export class ShepherdError extends Error {
 const CANCEL_REASON_EXIT_CODE = {
     merged: EXIT.OK,
     "ready-delay-elapsed": EXIT.OK,
+    "auto-mark-ready-disabled": EXIT.OK,
     closed: EXIT.CLOSED,
 };
 export function iterateResultToExitCode(result) {

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

@@ -28,7 +28,9 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
     let remainingSeconds;
     if (raw.isDraft &&
         blockingReviewerInProgress &&
-        (action === "mark_ready" || reasons.includes("draft-auto-mark-ready-disabled"))) {
+        (action === "mark_ready" ||
+            reasons.includes("draft-auto-mark-ready-disabled") ||
+            reasons.includes("draft-readiness-verification-required"))) {
         action = "wait";
         reasons = ["blocking-reviewer-in-progress"];
     }

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

@@ -40,18 +40,17 @@ export function routePollSummary(raw, checks, review, opts) {
     }
     if (raw.isDraft) {
         const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
-        // The stack selector asks the agent to mark a disabled draft ready, so
-        // that transition needs the same capability as the automatic one.
-        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready") &&
-            (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+        if (autoMarkReadyDisabled && (checks.incomplete || review.incomplete))
+            return { action: "fix_code", reasons: ["draft-readiness-verification-required"] };
+        if (autoMarkReadyDisabled)
+            return { action: "cancel", reasons: ["draft-auto-mark-ready-disabled"] };
+        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready")) {
             const unsupported = getGithubTransport() === "rest" && raw.viewerCanUpdate !== false && !isCcrTransport();
             if (unsupported)
                 return { action: "escalate", reasons: ["transport-unsupported"] };
             return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
-        return autoMarkReadyDisabled
-            ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
-            : { action: "mark_ready", reasons: ["draft-appears-ready"] };
+        return { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
     if (opts.merge && (raw.isInMergeQueue || raw.autoMergeRequest)) {
         return {

package/bin/journal/journal-container.d.mts

@@ -0,0 +1,6 @@
+import type { scanMarkdownLines } from "./markdown-line.mts";
+export declare const LEGACY: RegExp;
+export declare const JOURNAL_SUMMARY: RegExp;
+export declare const CLOSE = "</details>";
+/** Return the line of the canonical `</details>` closing a journal container, or null. */
+export declare function closeJournalContainer(lines: string[], syntax: ReturnType<typeof scanMarkdownLines>, start: number): number | null;

package/bin/journal/journal-container.mjs

@@ -0,0 +1,33 @@
+import { detailsTags, rawDetailsTags, rawHtmlState } from "./markdown-details.mjs";
+export const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+export const JOURNAL_SUMMARY = /^<summary>\s*Shepherd\s+Journal\b/i;
+export const CLOSE = "</details>";
+/** Return the line of the canonical `</details>` closing a journal container, or null. */
+export function closeJournalContainer(lines, syntax, start) {
+    let depth = 1;
+    let html = rawHtmlState();
+    for (let i = start; i < lines.length; i++) {
+        if (syntax[i].nested)
+            continue;
+        if (syntax[i].rawHtml) {
+            for (const tag of rawDetailsTags(lines[i], html))
+                if ((depth += tag) === 0)
+                    return null;
+            continue;
+        }
+        html = rawHtmlState();
+        if (syntax[i].ignored)
+            continue;
+        const visible = syntax[i].visiblePrefix;
+        if (JOURNAL_SUMMARY.test(visible.trimStart()) || LEGACY.test(visible))
+            return null;
+        depth += detailsTags(visible, false);
+        const closes = detailsTags(visible, true);
+        if (closes) {
+            depth -= closes;
+            if (depth <= 0)
+                return depth === 0 && lines[i] === CLOSE ? i : null;
+        }
+    }
+    return null;
+}

package/bin/journal/markdown-details.d.mts

@@ -0,0 +1,15 @@
+export declare function detailsTags(line: string, closing: boolean): number;
+/** Tokenizer state carried across the lines of one raw HTML block. */
+export type RawHtmlState = {
+    mode: "comment" | "data" | "raw-text" | "tag";
+    quote: '"' | "'" | null;
+    rawTag: string | null;
+    terminator: RegExp;
+};
+export declare const rawHtmlState: () => RawHtmlState;
+/**
+ * Return `1` per `<details>` opener and `-1` per closer that the browser
+ * creates from a raw HTML block line. Tags inside comments, CDATA, raw-text
+ * elements, and (possibly multiline) attribute values do not count.
+ */
+export declare function rawDetailsTags(line: string, state: RawHtmlState): Array<1 | -1>;

package/bin/journal/markdown-details.mjs

@@ -0,0 +1,92 @@
+import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { structuralDetailsStart } from "./markdown-structure.mjs";
+export function detailsTags(line, closing) {
+    if (structuralDetailsStart(line) === null)
+        return 0;
+    const expression = closing ? /<\/details>/gi : /<details(?:\s+[^>]*)?\/?>/gi;
+    return [...line.matchAll(expression)].filter((match) => !inQuotedHtmlAttribute(line, match.index)).length;
+}
+const RAW_TEXT = new Set([
+    "iframe",
+    "noembed",
+    "noframes",
+    "script",
+    "style",
+    "textarea",
+    "title",
+    "xmp",
+]);
+export const rawHtmlState = () => ({
+    mode: "data",
+    quote: null,
+    rawTag: null,
+    terminator: /--!?>/,
+});
+// Comments, CDATA sections, and bogus comments such as `<!x>`, `<?x>`, and `</ x>`.
+const COMMENTS = [
+    [/^<!--/, /--!?>/],
+    [/^<!\[CDATA\[/, /\]\]>/],
+    [/^<(?:[!?]|\/[^A-Za-z>])/, />/],
+];
+/**
+ * Return `1` per `<details>` opener and `-1` per closer that the browser
+ * creates from a raw HTML block line. Tags inside comments, CDATA, raw-text
+ * elements, and (possibly multiline) attribute values do not count.
+ */
+export function rawDetailsTags(line, state) {
+    const tags = [];
+    let i = 0;
+    while (i < line.length) {
+        if (state.mode === "comment") {
+            const end = state.terminator.exec(line.slice(i));
+            if (!end)
+                break;
+            state.mode = "data";
+            i += end.index + end[0].length;
+        }
+        else if (state.mode === "raw-text") {
+            const end = new RegExp(`</${state.rawTag}(?=[\\s/>]|$)`, "i").exec(line.slice(i));
+            if (!end)
+                break;
+            state.mode = "tag";
+            state.rawTag = null;
+            i += end.index + end[0].length;
+        }
+        else if (state.mode === "tag") {
+            const char = line[i++];
+            if (state.quote) {
+                if (char === state.quote)
+                    state.quote = null;
+            }
+            else if (char === '"' || char === "'")
+                state.quote = char;
+            else if (char === ">")
+                state.mode = state.rawTag ? "raw-text" : "data";
+        }
+        else {
+            const open = line.indexOf("<", i);
+            if (open === -1)
+                break;
+            const comment = COMMENTS.map(([start, end]) => [start.exec(line.slice(open)), end]).find(([start]) => start);
+            if (comment) {
+                state.mode = "comment";
+                state.terminator = comment[1];
+                i = open + comment[0][0].length;
+                continue;
+            }
+            // Tag names run until whitespace, `/`, or `>`, so `details:x` is not `details`.
+            const tag = /^<(\/?)([A-Za-z][^\s/>]*)/.exec(line.slice(open));
+            if (!tag) {
+                i = open + 1;
+                continue;
+            }
+            const name = tag[2].toLowerCase();
+            if (name === "details")
+                tags.push(tag[1] ? -1 : 1);
+            state.mode = "tag";
+            state.rawTag = !tag[1] && RAW_TEXT.has(name) ? name : null;
+            i = open + tag[0].length;
+        }
+    }
+    return tags;
+}

package/bin/journal/markdown-line.d.mts

@@ -1,6 +1,8 @@
+/** `rawHtml` marks lines inside a blank-line-terminated raw HTML block, whose tags still render. */
 type MarkdownLine = {
     ignored: boolean;
     nested: boolean;
+    rawHtml: boolean;
     visiblePrefix: string;
 };
 /** Return whether a Markdown line starts a block that interrupts inline content. */

package/bin/journal/markdown-line.mjs

@@ -35,7 +35,7 @@ function scanMarkdown(lines) {
         const container = resolveMarkdownContainer(line, activeContainer);
         activeContainer = container.tokens;
         const nested = container.tokens.length > 0;
-        const push = (ignored, visiblePrefix) => result.push({ ignored, nested, visiblePrefix });
+        const push = (ignored, visiblePrefix, rawHtml = false) => result.push({ ignored, nested, rawHtml, visiblePrefix });
         if (indentedCodeContainer) {
             if (stripMarkdownContainer(line, indentedCodeContainer) !== null) {
                 push(true, "");
@@ -53,7 +53,7 @@ function scanMarkdown(lines) {
             else {
                 const end = rawHtmlEnd(html, content);
                 if (end === null) {
-                    push(true, "");
+                    push(true, "", html.kind === "blank-line");
                     continue;
                 }
                 html = null;
@@ -100,7 +100,7 @@ function scanMarkdown(lines) {
                 const end = rawHtmlEnd(openingHtml, content);
                 if (end === null) {
                     html = openingHtml;
-                    push(true, "");
+                    push(true, "", openingHtml.kind === "blank-line");
                     continue;
                 }
                 allowCodeOpeners = false;

package/bin/journal/reconcile.mjs

@@ -1,42 +1,16 @@
-import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { detailsTags, rawDetailsTags, rawHtmlState } from "./markdown-details.mjs";
+import { CLOSE, closeJournalContainer, JOURNAL_SUMMARY, LEGACY } from "./journal-container.mjs";
 import { isSafeMarkdownInsertionPoint, scanMarkdownLines } from "./markdown-line.mjs";
 import { setextParagraphStart } from "./markdown-setext.mjs";
-import { structuralDetailsStart } from "./markdown-structure.mjs";
-const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
-const JOURNAL_SUMMARY = /^<summary>\s*Shepherd\s+Journal\b/i;
 const SETEXT = /^ {0,3}(?:=+|-+)[ \t]*$/;
-const CLOSE = "</details>";
 const OPEN = "<details>";
 const SUMMARY = "<summary>Shepherd Journal</summary>";
 const stripCr = (s) => s.replace(/\r$/, "");
-function detailsTags(line, closing) {
-    if (structuralDetailsStart(line) === null)
-        return 0;
-    const expression = closing ? /<\/details>/gi : /<details(?:\s+[^>]*)?\/?>/gi;
-    return [...line.matchAll(expression)].filter((match) => !inQuotedHtmlAttribute(line, match.index)).length;
-}
-function close(lines, syntax, start) {
-    let depth = 1;
-    for (let i = start; i < lines.length; i++) {
-        if (syntax[i].ignored || syntax[i].nested)
-            continue;
-        const visible = syntax[i].visiblePrefix;
-        if (JOURNAL_SUMMARY.test(visible.trimStart()) || LEGACY.test(visible))
-            return null;
-        depth += detailsTags(visible, false);
-        const closes = detailsTags(visible, true);
-        if (closes) {
-            depth -= closes;
-            if (depth <= 0)
-                return depth === 0 && lines[i] === CLOSE ? i : null;
-        }
-    }
-    return null;
-}
 export function scanShepherdJournal(lines) {
     const syntax = scanMarkdownLines(lines);
     const found = [];
     let detailsDepth = 0;
+    let html = rawHtmlState();
     let legacy = null;
     for (let i = 0; i < lines.length; i++) {
         if (!syntax[i].ignored &&
@@ -48,7 +22,16 @@ export function scanShepherdJournal(lines) {
             legacy.contentEnd = legacy.end = i;
             continue;
         }
-        if (syntax[i].ignored || syntax[i].nested)
+        if (syntax[i].nested)
+            continue;
+        if (syntax[i].rawHtml) {
+            // Raw-HTML details stay open past the block; stray closers are ignored, as in the browser.
+            for (const tag of rawDetailsTags(lines[i], html))
+                detailsDepth = Math.max(0, detailsDepth + tag);
+            continue;
+        }
+        html = rawHtmlState();
+        if (syntax[i].ignored)
             continue;
         const visible = syntax[i].visiblePrefix;
         detailsDepth += detailsTags(visible, false);
@@ -66,7 +49,7 @@ export function scanShepherdJournal(lines) {
                 lines[i - 1] !== OPEN ||
                 lines[i + 1] !== "")
                 return "error";
-            const end = close(lines, syntax, i + 2);
+            const end = closeJournalContainer(lines, syntax, i + 2);
             if (end === null)
                 return "error";
             detailsDepth--;

package/bin/types/iterate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, MergedBasePullRequest, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
-import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
+import type { MergeRequirements } from "./merge-requirements.mts";
 import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
@@ -75,14 +75,13 @@ interface IterateResultWait extends IterateResultBase {
     action: "wait";
     log: string;
     deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
-    stackDraftHold?: StackDraftHold;
 }
 /** Clean PR whose ready-delay is still counting. `--until-terminal` returns this instead of sleeping. */
 interface IterateResultReady extends IterateResultBase {
     action: "ready";
     log: string;
 }
-export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
+export type CancelReason = "merged" | "closed" | "ready-delay-elapsed" | "auto-mark-ready-disabled";
 interface IterateResultCancel extends IterateResultBase {
     action: "cancel";
     reason: CancelReason;