pr-shepherd 0.9.0 → 0.10.1

package/bin/comments/resolve.mjs

@@ -1,32 +1,12 @@
-/**
- * Batched mutations for resolving threads, minimizing comments, and dismissing reviews.
- *
- * The three mutation types (resolve / minimize / dismiss) are run sequentially so total
- * in-flight mutations never exceed CONCURRENCY at once, keeping us well within GitHub's
- * secondary rate-limit window.
- *
- * Push-before-resolve safety:
- *   When `requireSha` is set, shepherd verifies that GitHub has received that
- *   commit before issuing any resolve/dismiss mutations. It polls up to 20 seconds.
- *   If the push hasn't landed, shepherd throws rather than resolving prematurely
- *   (which could allow auto-merge before reviewers see the fix).
- */
 import { graphql, getPrHeadSha } from "../github/client.mjs";
-import { RESOLVE_THREAD_MUTATION, MINIMIZE_COMMENT_MUTATION, DISMISS_REVIEW_MUTATION, } from "../github/queries.mjs";
 import { loadConfig } from "../config/load.mjs";
-/**
- * Execute all requested resolve/minimize/dismiss mutations.
- *
- * @throws Error if `requireSha` is set and GitHub hasn't received that commit
- *              within the polling window.
- */
 export async function applyResolveOptions(pr, repo, opts) {
-    // Require --message when dismissing reviews.
     if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
         throw new Error("--message is required when dismissing reviews");
     }
-    // Safety check: verify the push landed before resolving.
     if (opts.requireSha) {
+        // Verify GitHub received the commit before resolving — prevents auto-merge
+        // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
     const result = {
@@ -35,55 +15,87 @@ export async function applyResolveOptions(pr, repo, opts) {
         dismissedReviews: [],
         errors: [],
     };
-    await runBatched(opts.resolveThreadIds ?? [], (id) => resolveThread(id), result.resolvedThreads, result.errors);
-    await runBatched(opts.minimizeCommentIds ?? [], (id) => minimizeComment(id, "RESOLVED"), result.minimizedComments, result.errors);
-    await runBatched(opts.dismissReviewIds ?? [], (id) => dismissReview(id, opts.dismissMessage ?? ""), result.dismissedReviews, result.errors);
+    await bulkApply(opts.resolveThreadIds ?? [], opts.minimizeCommentIds ?? [], opts.dismissReviewIds ?? [], opts.dismissMessage ?? "", result);
     return result;
 }
-/**
- * Auto-resolve a batch of outdated threads via the resolveReviewThread mutation.
- */
 export async function autoResolveOutdated(threadIds) {
-    const resolved = [];
-    const errors = [];
-    await runBatched(threadIds, (id) => resolveThread(id), resolved, errors);
-    return { resolved, errors };
-}
-// ---------------------------------------------------------------------------
-// Mutation helpers
-// ---------------------------------------------------------------------------
-async function resolveThread(threadId) {
-    await graphql(RESOLVE_THREAD_MUTATION, { threadId });
-}
-async function minimizeComment(commentId, classifier) {
-    await graphql(MINIMIZE_COMMENT_MUTATION, { commentId, classifier });
+    const result = {
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    await bulkApply(threadIds, [], [], "", result);
+    return { resolved: result.resolvedThreads, errors: result.errors };
 }
-async function dismissReview(reviewId, message) {
-    await graphql(DISMISS_REVIEW_MUTATION, { reviewId, message });
+// Chunk at 50 so a single oversized list never fails the entire call.
+const BULK_CHUNK_SIZE = 50;
+function buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage) {
+    const ops = [];
+    for (let i = 0; i < resolveIds.length; i++) {
+        ops.push(`  r${i}: resolveReviewThread(input: { threadId: ${JSON.stringify(resolveIds[i])} }) { thread { isResolved } }`);
+    }
+    for (let i = 0; i < minimizeIds.length; i++) {
+        ops.push(`  m${i}: minimizeComment(input: { subjectId: ${JSON.stringify(minimizeIds[i])}, classifier: RESOLVED }) { minimizedComment { isMinimized } }`);
+    }
+    for (let i = 0; i < dismissIds.length; i++) {
+        ops.push(`  d${i}: dismissPullRequestReview(input: { pullRequestReviewId: ${JSON.stringify(dismissIds[i])}, message: ${JSON.stringify(dismissMessage)} }) { pullRequestReview { state } }`);
+    }
+    return `mutation BulkApply {\n${ops.join("\n")}\n}`;
 }
-// ---------------------------------------------------------------------------
-// Concurrency helper
-// ---------------------------------------------------------------------------
-async function runBatched(ids, fn, successList, errorList) {
-    const CONCURRENCY = loadConfig().resolve.concurrency;
-    // Process in chunks of CONCURRENCY.
-    for (let i = 0; i < ids.length; i += CONCURRENCY) {
-        const chunk = ids.slice(i, i + CONCURRENCY);
+async function bulkApply(resolveIds, minimizeIds, dismissIds, dismissMessage, result) {
+    const allOps = [
+        ...resolveIds.map((id) => ({ kind: "r", id })),
+        ...minimizeIds.map((id) => ({ kind: "m", id })),
+        ...dismissIds.map((id) => ({ kind: "d", id })),
+    ];
+    for (let i = 0; i < allOps.length; i += BULK_CHUNK_SIZE) {
+        const chunk = allOps.slice(i, i + BULK_CHUNK_SIZE);
         // eslint-disable-next-line no-await-in-loop
-        await Promise.all(chunk.map(async (id) => {
-            try {
-                await fn(id);
-                successList.push(id);
-            }
-            catch (err) {
-                errorList.push(`${id}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }));
+        await bulkApplyChunk(chunk.filter((o) => o.kind === "r").map((o) => o.id), chunk.filter((o) => o.kind === "m").map((o) => o.id), chunk.filter((o) => o.kind === "d").map((o) => o.id), dismissMessage, result);
+    }
+}
+async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessage, result) {
+    if (resolveIds.length === 0 && minimizeIds.length === 0 && dismissIds.length === 0)
+        return;
+    const doc = buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage);
+    let data;
+    try {
+        const resp = await graphql(doc, {});
+        data = resp.data;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        for (const id of resolveIds)
+            result.errors.push(`${id}: ${msg}`);
+        for (const id of minimizeIds)
+            result.errors.push(`${id}: ${msg}`);
+        for (const id of dismissIds)
+            result.errors.push(`${id}: ${msg}`);
+        return;
+    }
+    for (let i = 0; i < resolveIds.length; i++) {
+        const r = data[`r${i}`];
+        if (r?.thread?.isResolved === true)
+            result.resolvedThreads.push(resolveIds[i]);
+        else
+            result.errors.push(`${resolveIds[i]}: resolve returned null or thread not resolved`);
+    }
+    for (let i = 0; i < minimizeIds.length; i++) {
+        const m = data[`m${i}`];
+        if (m?.minimizedComment?.isMinimized === true)
+            result.minimizedComments.push(minimizeIds[i]);
+        else
+            result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
+    }
+    for (let i = 0; i < dismissIds.length; i++) {
+        const d = data[`d${i}`];
+        if (d?.pullRequestReview != null)
+            result.dismissedReviews.push(dismissIds[i]);
+        else
+            result.errors.push(`${dismissIds[i]}: dismiss returned null`);
     }
 }
-// ---------------------------------------------------------------------------
-// SHA polling
-// ---------------------------------------------------------------------------
 async function waitForSha(pr, repo, expectedSha) {
     const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
@@ -94,7 +106,6 @@ async function waitForSha(pr, repo, expectedSha) {
                 return;
         }
         catch (err) {
-            // Transient network / 5xx error — keep polling unless this is the last attempt.
             if (attempt === SHA_POLL_MAX_ATTEMPTS - 1)
                 throw err;
         }
@@ -103,7 +114,6 @@ async function waitForSha(pr, repo, expectedSha) {
             await sleep(SHA_POLL_INTERVAL_MS);
         }
     }
-    // Total actual wait = (SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS (no sleep after last poll).
     throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
 }
 function sleep(ms) {

package/bin/config.json

@@ -12,7 +12,6 @@
     "maxTurns": 50
   },
   "resolve": {
-    "concurrency": 4,
     "shaPoll": {
       "intervalMs": 2000,
       "maxAttempts": 10
@@ -21,7 +20,8 @@
   },
   "checks": {
     "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "logTailLines": 200
+    "logTailLines": 5,
+    "logTailChars": 200
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]

package/bin/github/batch-parsers.mjs

@@ -96,6 +96,8 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         mergeStateStatus: raw.mergeStateStatus,
         reviewDecision: (raw.reviewDecision ?? null),
         headRefOid: raw.headRefOid,
+        headRefName: raw.headRefName,
+        headRepoWithOwner: raw.headRepository?.nameWithOwner ?? null,
         baseRefName: raw.baseRefName,
         reviewRequests,
         latestReviews,

package/bin/github/client.mjs

@@ -8,7 +8,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { graphql as httpGraphql, rest } from "./http.mjs";
-import { PR_NUMBER_BY_BRANCH_QUERY } from "./queries.mjs";
+import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY } from "./queries.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly
@@ -42,38 +42,17 @@ export async function getCurrentPrNumber() {
 }
 /** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
 export async function getPrHeadSha(pr, owner, name) {
-    const data = await rest("GET", `/repos/${owner}/${name}/pulls/${pr}`);
-    return data.head.sha;
-}
-/**
- * Full head info for a PR — sha, branch name, and the head repository's full name.
- * Needed by commit-suggestions to target the correct branch via `createCommitOnBranch`.
- */
-export async function getPrHead(pr, owner, name) {
-    const data = await rest("GET", `/repos/${owner}/${name}/pulls/${pr}`);
-    if (!data.head.repo) {
-        throw new Error(`PR #${pr} head repository is unavailable (fork may have been deleted).`);
-    }
-    return {
-        sha: data.head.sha,
-        ref: data.head.ref,
-        repoWithOwner: data.head.repo.full_name,
-    };
-}
-/**
- * Fetch a file's raw text content at a given ref. Uses the REST contents endpoint,
- * which returns base64 for files under 1MB. Throws for binary / oversize files.
- */
-export async function getFileContents(repoWithOwner, path, ref) {
-    const data = await rest("GET", `/repos/${repoWithOwner}/contents/${encodePathForApi(path)}?ref=${encodeURIComponent(ref)}`);
-    if (!data.content || data.encoding !== "base64") {
-        throw new Error(`File ${path} could not be read as text (encoding=${data.encoding ?? "n/a"}).`);
+    const result = await httpGraphql(GET_PR_HEAD_SHA_QUERY, { owner, repo: name, pr });
+    const sha = result.data.repository?.pullRequest?.headRefOid;
+    if (!sha) {
+        const detail = !result.data.repository
+            ? "repository not found or access denied"
+            : !result.data.repository.pullRequest
+                ? "PR not found or access denied"
+                : "headRefOid missing";
+        throw new Error(`Could not resolve head SHA for ${owner}/${name} PR #${pr}: ${detail}`);
     }
-    return Buffer.from(data.content, "base64").toString("utf8");
-}
-// Encode every path segment but preserve the slashes between them.
-function encodePathForApi(path) {
-    return path.split("/").map(encodeURIComponent).join("/");
+    return sha;
 }
 /**
  * Fetches `mergeable` and `mergeStateStatus` via the REST API.

package/bin/github/gql/batch-pr.gql

@@ -19,6 +19,10 @@ query BatchPr(
       mergeStateStatus
       reviewDecision
       headRefOid
+      headRefName
+      headRepository {
+        nameWithOwner
+      }
       baseRefName
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {

package/bin/github/gql/get-pr-head-sha.gql

@@ -0,0 +1,7 @@
+query GetPrHeadSha($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      headRefOid
+    }
+  }
+}

package/bin/github/http.mjs

@@ -1,5 +1,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
+import { appendEntry, nextEntry } from "../log/log-file.mjs";
+import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 const execFile = promisify(execFileCb);
 const BASE_URL = "https://api.github.com";
 // ---------------------------------------------------------------------------
@@ -42,33 +44,87 @@ async function makeHeaders() {
 function sanitizeBody(body) {
     return body.replace(/Bearer\s+\S+/gi, "[REDACTED]").slice(0, 200);
 }
-async function requestWithTokenRetry(fn) {
+function redactToken(body) {
+    return body.replace(/Bearer\s+\S+/gi, "[REDACTED]");
+}
+function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
+async function requestWithTokenRetry(fn, t0, onIntermediate) {
     const res = await fn();
     if (res.status === 401 && _token !== undefined) {
+        onIntermediate?.(401, Math.round(performance.now() - t0));
         try {
             await res.arrayBuffer();
         }
         catch { }
         _token = undefined;
-        return fn();
+        const retryT0 = performance.now();
+        return { res: await fn(), attempt: 2, retryT0 };
     }
-    return res;
+    return { res, attempt: 1, retryT0: t0 };
 }
 // ---------------------------------------------------------------------------
 // GraphQL
 // ---------------------------------------------------------------------------
 async function graphqlInner(query, vars) {
-    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}/graphql`, {
+    const url = `${BASE_URL}/graphql`;
+    const n = nextEntry();
+    appendEntry(formatRequestEntry({
+        n,
+        kind: "GraphQL",
+        method: "POST",
+        url,
+        body: { query, variables: vars },
+    }));
+    const t0 = performance.now();
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
         method: "POST",
         headers: await makeHeaders(),
         body: JSON.stringify({ query, variables: vars }),
-    }));
+    }), t0, (status, firstDurationMs) => {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "GraphQL",
+            method: "POST",
+            url,
+            status,
+            durationMs: firstDurationMs,
+        }));
+    });
+    const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers);
     if (!res.ok) {
         const body = await res.text();
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "GraphQL",
+            method: "POST",
+            url,
+            status: res.status,
+            durationMs,
+            textBody: redactToken(body),
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
         throw new Error(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`);
     }
     const parsed = (await res.json());
+    appendEntry(formatResponseEntry({
+        n,
+        kind: "GraphQL",
+        method: "POST",
+        url,
+        status: res.status,
+        durationMs,
+        body: parsed,
+        attempt: attempt > 1 ? attempt : undefined,
+    }));
     if (parsed.data == null) {
         const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
         throw new Error(`GitHub GraphQL error (no data): ${messages}`);
@@ -91,31 +147,109 @@ export async function graphqlWithRateLimit(query, vars = {}) {
 // REST
 // ---------------------------------------------------------------------------
 export async function rest(method, path, body) {
-    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}${path}`, {
+    const url = `${BASE_URL}${path}`;
+    const n = nextEntry();
+    appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
+    const t0 = performance.now();
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
         method,
         headers: await makeHeaders(),
         body: body !== undefined ? JSON.stringify(body) : undefined,
-    }));
+    }), t0, (status, firstDurationMs) => {
+        appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs: firstDurationMs }));
+    });
+    const durationMs = Math.round(performance.now() - retryT0);
+    const ct = res.headers.get("content-type") ?? "";
     if (!res.ok) {
         const text = await res.text();
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "REST",
+            method,
+            url,
+            status: res.status,
+            durationMs,
+            textBody: redactToken(text),
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
         throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`);
     }
-    const ct = res.headers.get("content-type") ?? "";
     if (ct.includes("application/json")) {
-        return res.json();
+        const json = (await res.json());
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "REST",
+            method,
+            url,
+            status: res.status,
+            durationMs,
+            contentType: ct,
+            body: json,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
+        return json;
     }
+    appendEntry(formatResponseEntry({
+        n,
+        kind: "REST",
+        method,
+        url,
+        status: res.status,
+        durationMs,
+        contentType: ct || undefined,
+        attempt: attempt > 1 ? attempt : undefined,
+    }));
     return undefined;
 }
 export async function restText(path) {
-    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}${path}`, {
+    const url = `${BASE_URL}${path}`;
+    const n = nextEntry();
+    appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
+    const t0 = performance.now();
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
         method: "GET",
         headers: await makeHeaders(),
         redirect: "manual",
-    }));
+    }), t0, (status, firstDurationMs) => {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "restText",
+            method: "GET",
+            url,
+            status,
+            durationMs: firstDurationMs,
+        }));
+    });
+    const durationMs = Math.round(performance.now() - retryT0);
     if (res.status === 301 || res.status === 302 || res.status === 307 || res.status === 308) {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "restText",
+            method: "GET",
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
         const location = res.headers.get("location");
         if (location) {
+            const n2 = nextEntry();
+            const logUrl = redactUrl(location);
+            appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
+            const t1 = performance.now();
             const redirectRes = await fetch(location);
+            const duration2 = Math.round(performance.now() - t1);
+            const clRaw = redirectRes.headers.get("content-length");
+            const contentLength = clRaw !== null && Number.isFinite(Number(clRaw)) ? Number(clRaw) : undefined;
+            appendEntry(formatResponseEntry({
+                n: n2,
+                kind: "restText",
+                method: "GET",
+                url: logUrl,
+                status: redirectRes.status,
+                durationMs: duration2,
+                contentLength,
+            }));
             if (!redirectRes.ok) {
                 throw new Error(`redirect target ${location} failed: ${redirectRes.status}`);
             }
@@ -124,8 +258,29 @@ export async function restText(path) {
     }
     if (!res.ok) {
         const text = await res.text();
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "restText",
+            method: "GET",
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
         throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`);
     }
+    const clRaw = res.headers.get("content-length");
+    const contentLength = clRaw !== null && Number.isFinite(Number(clRaw)) ? Number(clRaw) : undefined;
+    appendEntry(formatResponseEntry({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        status: res.status,
+        durationMs,
+        contentLength,
+        attempt: attempt > 1 ? attempt : undefined,
+    }));
     return res.text();
 }
 // ---------------------------------------------------------------------------

package/bin/github/queries.mjs

@@ -1,23 +1,19 @@
 /**
  * GraphQL query strings used by pr-shepherd.
  *
- * Query strings live in src/github/gql/*.gql.
- * Never inline raw GraphQL strings in .ts source files.
+ * Static query strings live in src/github/gql/*.gql and are loaded here.
+ * Dynamic documents whose content varies per call (e.g. BulkApply in
+ * src/comments/resolve.mts) are built at runtime and are exempt — they
+ * cannot be expressed as static files.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = gql("batch-pr.gql");
-/** Resolve a single review thread. */
-export const RESOLVE_THREAD_MUTATION = gql("resolve-thread.gql");
-/** Minimize a PR comment (IssueComment). */
-export const MINIMIZE_COMMENT_MUTATION = gql("minimize-comment.gql");
-/** Dismiss a pull request review. */
-export const DISMISS_REVIEW_MUTATION = gql("dismiss-review.gql");
-/** Multi-PR status query for `shepherd status PR1 PR2 …`. */
-export const MULTI_PR_STATUS_QUERY = gql("multi-pr-status.gql");
-/** Paginated version — used when reviewThreads is truncated (totalCount > 100). */
+/** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
+export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
+/** Paginated follow-up for `shepherd status` — used when reviewThreads is truncated (totalCount > 100). */
 export const MULTI_PR_STATUS_QUERY_WITH_CURSOR = gql("multi-pr-status-paged.gql");
 /** Look up PR number by branch name (for getCurrentPrNumber). */
 export const PR_NUMBER_BY_BRANCH_QUERY = gql("pr-number-by-branch.gql");

package/bin/log/log-file.mjs

@@ -0,0 +1,88 @@
+/**
+ * Append-only per-worktree markdown log.
+ *
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ *
+ * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
+ * Write failures flip an internal disabled flag so the CLI never crashes because
+ * logging failed.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveStateBase } from "../state/base.mjs";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { getWorktreeKey } from "../util/worktree.mjs";
+function computeDisabled() {
+    if (process.env["PR_SHEPHERD_LOG_DISABLED"] === "1")
+        return true;
+    const ci = process.env["CI"];
+    return ci !== undefined && ci !== "" && ci !== "0" && ci !== "false";
+}
+let _disabled = computeDisabled();
+let _logPath = null;
+let _entryCounter = 0;
+/** Returns the next monotonically-increasing entry number for the current session. */
+export function nextEntry() {
+    return ++_entryCounter;
+}
+export function getLogFilePath(key) {
+    const { owner, repo } = key;
+    if (!SAFE_SEGMENT.test(owner) || !SAFE_SEGMENT.test(repo)) {
+        throw new Error(`Invalid repo key segments: ${owner}/${repo}`);
+    }
+    const base = resolveStateBase();
+    // Worktree key injected at init time; fall back to "unknown" if not yet set.
+    const wkey = _worktreeKey ?? "unknown";
+    return join(base, `${owner}-${repo}`, "worktrees", `${wkey}.md`);
+}
+let _worktreeKey = null;
+/**
+ * Initialize the log for this process. Must be called before appendEntry().
+ * Silently disables logging on any error (no git repo, bad repo name, etc.).
+ */
+export async function initLog(repoKey) {
+    if (_disabled)
+        return null;
+    try {
+        const { owner, repo } = repoKey;
+        if (!SAFE_SEGMENT.test(owner) || !SAFE_SEGMENT.test(repo))
+            return null;
+        _worktreeKey = await getWorktreeKey();
+        const path = getLogFilePath(repoKey);
+        mkdirSync(dirname(path), { recursive: true });
+        _logPath = path;
+        return path;
+    }
+    catch {
+        _disabled = true;
+        return null;
+    }
+}
+/** Append a pre-formatted markdown chunk to the log. No-op if disabled. */
+export function appendEntry(markdown) {
+    if (_disabled || _logPath === null)
+        return;
+    try {
+        appendFileSync(_logPath, markdown);
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: log write failed (disabling log): ${String(e)}\n`);
+        _disabled = true;
+    }
+}
+/** Resolve the log path without initializing (for the log-file subcommand). */
+export async function resolveLogPath(repoKey) {
+    if (!SAFE_SEGMENT.test(repoKey.owner) || !SAFE_SEGMENT.test(repoKey.repo)) {
+        throw new Error(`Invalid repo key segments: ${repoKey.owner}/${repoKey.repo}`);
+    }
+    const wkey = await getWorktreeKey();
+    const base = resolveStateBase();
+    return join(base, `${repoKey.owner}-${repoKey.repo}`, "worktrees", `${wkey}.md`);
+}
+/** Exposed for tests to reset module state. */
+export function _resetLogState() {
+    _disabled = computeDisabled();
+    _logPath = null;
+    _worktreeKey = null;
+    _entryCounter = 0;
+}