@deftai/directive-core 0.78.0 → 0.79.1

package/dist/issue-sync/sync-from-xbrief.d.ts

@@ -0,0 +1,46 @@
+import { type RunGhApiFn } from "../intake/github-body.js";
+export declare const SYNC_COMMENT_HEADER = "## xBRIEF sync (deft issue:sync-from-xbrief)";
+export interface OriginIssueTarget {
+    readonly repo: string;
+    readonly number: number;
+    readonly uri: string;
+}
+export interface SyncSnapshot {
+    readonly status: string;
+    readonly title: string;
+    readonly acceptance: string;
+    readonly items: readonly {
+        title: string;
+        status: string;
+    }[];
+}
+export interface ResolveOriginOptions {
+    readonly fallbackRepo?: string | null;
+}
+export declare function resolveOriginIssue(data: Record<string, unknown>, options?: ResolveOriginOptions): OriginIssueTarget | null;
+export declare function extractSyncSnapshot(data: Record<string, unknown>): SyncSnapshot;
+export declare function fingerprintSyncSnapshot(snapshot: SyncSnapshot): string;
+export declare function readStoredFingerprint(data: Record<string, unknown>): string | null;
+export declare function hasMaterialChanges(data: Record<string, unknown>): boolean;
+export declare function sanitizeMarkdownInline(text: string): string;
+export declare function buildSyncComment(data: Record<string, unknown>, xbriefPath: string): string;
+export interface SyncFromXbriefOptions {
+    readonly xbriefPath: string;
+    readonly dryRun?: boolean;
+    readonly projectRoot?: string;
+    readonly repo?: string;
+    readonly runFn?: RunGhApiFn;
+    readonly writeErr?: (message: string) => void;
+    readonly writeOut?: (message: string) => void;
+    readonly writeFingerprint?: (absPath: string, data: Record<string, unknown>) => void;
+}
+export declare function stampIssueSyncFingerprint(data: Record<string, unknown>, origin: OriginIssueTarget): Record<string, unknown>;
+export declare function syncFromXbrief(options: SyncFromXbriefOptions): number;
+export interface SyncFromXbriefCliArgs {
+    readonly path?: string;
+    readonly dryRun?: boolean;
+    readonly projectRoot?: string;
+    readonly repo?: string;
+}
+export declare function syncFromXbriefMain(args: SyncFromXbriefCliArgs): number;
+//# sourceMappingURL=sync-from-xbrief.d.ts.map

package/dist/issue-sync/sync-from-xbrief.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createIssueComment } from "../intake/github-body.js";
+import { provenanceIssueNumber, repoSlugFromUrl } from "../intake/issue-ingest.js";
+import { extractReferencesFromVbrief, GITHUB_ISSUE_REF_TYPES, parseIssueNumber, } from "../intake/reconcile-issues.js";
+import { resolveProjectRoot } from "../scope/project-context.js";
+import { resolveProjectRepo } from "../slice/project-context.js";
+export const SYNC_COMMENT_HEADER = "## xBRIEF sync (deft issue:sync-from-xbrief)";
+export function resolveOriginIssue(data, options = {}) {
+    const refs = extractReferencesFromVbrief(data);
+    const githubRefs = [];
+    for (const ref of refs) {
+        if (!GITHUB_ISSUE_REF_TYPES.has(String(ref.type ?? ""))) {
+            continue;
+        }
+        const num = parseIssueNumber(ref);
+        if (num !== null) {
+            githubRefs.push({ ref, number: num });
+        }
+    }
+    if (githubRefs.length === 0) {
+        return null;
+    }
+    const provenanceNum = provenanceIssueNumber(data);
+    let chosen = githubRefs[0];
+    if (provenanceNum !== null) {
+        const match = githubRefs.find((entry) => entry.number === provenanceNum);
+        if (match !== undefined) {
+            chosen = match;
+        }
+    }
+    const uri = (typeof chosen.ref.uri === "string" && chosen.ref.uri.length > 0 ? chosen.ref.uri : null) ??
+        (typeof chosen.ref.url === "string" && chosen.ref.url.length > 0 ? chosen.ref.url : null) ??
+        "";
+    let repo = repoSlugFromUrl(uri);
+    if (repo === null && options.fallbackRepo !== undefined && options.fallbackRepo !== null) {
+        repo = options.fallbackRepo;
+    }
+    if (repo === null) {
+        return null;
+    }
+    return {
+        repo,
+        number: chosen.number,
+        uri: uri.length > 0 ? uri : `https://github.com/${repo}/issues/${chosen.number}`,
+    };
+}
+export function extractSyncSnapshot(data) {
+    const plan = (data.plan ?? {});
+    const narratives = (plan.narratives ?? {});
+    const acceptance = typeof narratives.Acceptance === "string"
+        ? narratives.Acceptance
+        : typeof narratives.acceptance === "string"
+            ? narratives.acceptance
+            : "";
+    const items = [];
+    const walk = (raw) => {
+        if (!Array.isArray(raw)) {
+            return;
+        }
+        for (const item of raw) {
+            if (item === null || typeof item !== "object" || Array.isArray(item)) {
+                continue;
+            }
+            const obj = item;
+            items.push({
+                title: String(obj.title ?? ""),
+                status: String(obj.status ?? "unknown"),
+            });
+            walk(obj.subItems);
+            walk(obj.items);
+        }
+    };
+    walk(plan.items);
+    return {
+        status: String(plan.status ?? "unknown"),
+        title: String(plan.title ?? ""),
+        acceptance,
+        items,
+    };
+}
+export function fingerprintSyncSnapshot(snapshot) {
+    return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex").slice(0, 16);
+}
+export function readStoredFingerprint(data) {
+    const plan = (data.plan ?? {});
+    const metadata = plan.metadata;
+    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return null;
+    }
+    const issueSync = metadata.issueSync;
+    if (issueSync === null || typeof issueSync !== "object" || Array.isArray(issueSync)) {
+        return null;
+    }
+    const fp = issueSync.fingerprint;
+    return typeof fp === "string" && fp.length > 0 ? fp : null;
+}
+export function hasMaterialChanges(data) {
+    const current = fingerprintSyncSnapshot(extractSyncSnapshot(data));
+    const stored = readStoredFingerprint(data);
+    return stored === null || stored !== current;
+}
+export function sanitizeMarkdownInline(text) {
+    return text.replace(/\r?\n/g, " ");
+}
+export function buildSyncComment(data, xbriefPath) {
+    const snapshot = extractSyncSnapshot(data);
+    const safeTitle = sanitizeMarkdownInline(snapshot.title);
+    const lines = [
+        SYNC_COMMENT_HEADER,
+        "",
+        `**Scope:** ${safeTitle}`,
+        `**Status:** \`${sanitizeMarkdownInline(snapshot.status)}\``,
+        `**xBRIEF:** \`${xbriefPath}\``,
+    ];
+    if (snapshot.items.length > 0) {
+        lines.push("", "### Plan items", "");
+        for (const item of snapshot.items) {
+            lines.push(`- **${sanitizeMarkdownInline(item.status)}** — ${sanitizeMarkdownInline(item.title)}`);
+        }
+    }
+    if (snapshot.acceptance.length > 0) {
+        lines.push("", "### Acceptance criteria", "", snapshot.acceptance);
+    }
+    lines.push("", "_Posted by `task issue:sync-from-xbrief`._");
+    return lines.join("\n");
+}
+export function stampIssueSyncFingerprint(data, origin) {
+    const plan = (data.plan ?? {});
+    const metadata = { ...(plan.metadata ?? {}) };
+    metadata.issueSync = {
+        fingerprint: fingerprintSyncSnapshot(extractSyncSnapshot(data)),
+        syncedAt: new Date().toISOString(),
+        issueNumber: origin.number,
+        repo: origin.repo,
+    };
+    plan.metadata = metadata;
+    return { ...data, plan };
+}
+export function syncFromXbrief(options) {
+    const writeErr = options.writeErr ?? ((message) => process.stderr.write(`${message}\n`));
+    const writeOut = options.writeOut ?? ((message) => process.stdout.write(`${message}\n`));
+    const absPath = resolve(options.xbriefPath);
+    let data;
+    try {
+        data = JSON.parse(readFileSync(absPath, "utf8"));
+    }
+    catch (exc) {
+        writeErr(`issue:sync-from-xbrief: cannot read ${options.xbriefPath}: ${exc instanceof Error ? exc.message : String(exc)}`);
+        return 1;
+    }
+    const projectRoot = resolveProjectRoot(options.projectRoot) ?? process.cwd();
+    const fallbackRepo = resolveProjectRepo(options.repo, projectRoot);
+    const origin = resolveOriginIssue(data, { fallbackRepo });
+    if (origin === null) {
+        writeErr("issue:sync-from-xbrief: no linked GitHub issue origin in xBRIEF references (x-xbrief/github-issue); skip or add origin reference.");
+        return 1;
+    }
+    if (!hasMaterialChanges(data)) {
+        writeOut(`issue:sync-from-xbrief: no material AC/status changes since last sync for #${origin.number}; nothing to post.`);
+        return 0;
+    }
+    const relPath = options.xbriefPath.replace(/\\/g, "/");
+    const comment = buildSyncComment(data, relPath);
+    if (options.dryRun) {
+        writeOut(`issue:sync-from-xbrief: dry-run would post comment to ${origin.repo}#${origin.number}:\n`);
+        writeOut(comment);
+        return 0;
+    }
+    let commentResult;
+    try {
+        commentResult = createIssueComment(origin.repo, origin.number, {
+            body: comment,
+            runFn: options.runFn,
+        });
+    }
+    catch (exc) {
+        writeErr(`issue:sync-from-xbrief: failed to post comment: ${exc instanceof Error ? exc.message : String(exc)}`);
+        return 1;
+    }
+    writeOut(`issue:sync-from-xbrief: posted comment to ${origin.repo}#${origin.number} (id: ${commentResult.id}).`);
+    const writeFingerprint = options.writeFingerprint ??
+        ((targetPath, stamped) => {
+            writeFileSync(targetPath, `${JSON.stringify(stamped, null, 2)}\n`, "utf8");
+        });
+    try {
+        writeFingerprint(absPath, stampIssueSyncFingerprint(data, origin));
+    }
+    catch (exc) {
+        writeErr(`issue:sync-from-xbrief: comment posted (id: ${commentResult.id}) but failed to persist sync fingerprint in ${options.xbriefPath}: ${exc instanceof Error ? exc.message : String(exc)}`);
+        return 1;
+    }
+    return 0;
+}
+export function syncFromXbriefMain(args) {
+    if (args.path === undefined || args.path.length === 0) {
+        process.stderr.write("issue:sync-from-xbrief: xBRIEF path required\n");
+        return 2;
+    }
+    return syncFromXbrief({
+        xbriefPath: args.path,
+        dryRun: args.dryRun,
+        projectRoot: args.projectRoot,
+        repo: args.repo,
+    });
+}
+//# sourceMappingURL=sync-from-xbrief.js.map

package/dist/platform/index.d.ts

@@ -6,5 +6,6 @@ export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";
 export * from "./resolve-changelog-unreleased.js";
 export * from "./resolve-version.js";
+export * from "./shell-context.js";
 export * from "./slug-normalize.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/index.js

@@ -6,5 +6,6 @@ export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";
 export * from "./resolve-changelog-unreleased.js";
 export * from "./resolve-version.js";
+export * from "./shell-context.js";
 export * from "./slug-normalize.js";
 //# sourceMappingURL=index.js.map

package/dist/platform/platform-capabilities.d.ts

@@ -1,3 +1,4 @@
+import { type ShellContext } from "./shell-context.js";
 export interface UidMapEntry {
     readonly insideId: number;
     readonly outsideId: number;
@@ -10,6 +11,8 @@ export interface OwnershipFacts {
     readonly interpretedAsSandboxView: boolean;
 }
 export interface RuntimeCapabilityReport {
+    readonly hostPlatform: NodeJS.Platform;
+    readonly shell: ShellContext;
     readonly runtimeMode: string;
     readonly identityKind: string;
     readonly effectiveUid: number | null;
@@ -33,6 +36,8 @@ export declare function classifyIdentityKind(options: {
 export declare function classifyRuntimeMode(environ: Readonly<Record<string, string>>, sandboxUidRemap: boolean): string;
 export interface ProbeRuntimeOptions {
     readonly environ?: Readonly<Record<string, string>>;
+    readonly platform?: NodeJS.Platform;
+    readonly userShell?: string | null;
     readonly uidMapPath?: string;
     readonly cwd?: string;
     readonly effectiveUidOverride?: number | null;

package/dist/platform/platform-capabilities.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { IDENTITY_LOCAL_USER, IDENTITY_REAL_ROOT, IDENTITY_SANDBOX_REMAPPED_LOCAL_USER, IDENTITY_UNKNOWN, RUNTIME_MODE_CLOUD_HEADLESS, RUNTIME_MODE_CURSOR_NATIVE_SANDBOX, RUNTIME_MODE_LOCAL_UNSANDBOXED, } from "./constants.js";
+import { detectEnvironmentContext, environmentContextToDict, } from "./shell-context.js";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 const CURSOR_SIGNAL_VARS = [
     "CURSOR_SANDBOX",
@@ -118,6 +119,11 @@ export function probeRuntimeCapabilities(options = {}) {
     const env = options.environ === undefined
         ? { ...process.env }
         : { ...options.environ };
+    const environment = detectEnvironmentContext({
+        environ: env,
+        platform: options.platform,
+        userShell: options.userShell,
+    });
     let effectiveUid;
     if (options.effectiveUidOverride !== undefined) {
         effectiveUid = options.effectiveUidOverride;
@@ -147,6 +153,8 @@ export function probeRuntimeCapabilities(options = {}) {
     const cwdPath = options.cwd ?? process.cwd();
     const ownership = readOwnership(cwdPath, sandboxUidRemap);
     return {
+        hostPlatform: environment.hostPlatform,
+        shell: environment.shell,
         runtimeMode,
         identityKind,
         effectiveUid,
@@ -164,6 +172,7 @@ export function getPlatformCapabilities(options = {}) {
 }
 export function reportToDict(report) {
     return {
+        ...environmentContextToDict({ hostPlatform: report.hostPlatform, shell: report.shell }),
         runtime_mode: report.runtimeMode,
         identity_kind: report.identityKind,
         effective_uid: report.effectiveUid,

package/dist/platform/shell-context.d.ts

@@ -0,0 +1,30 @@
+/** Describes whether a shell signal names the executor, a user default, or no known shell. */
+export type ShellContextKind = "execution" | "default" | "unknown";
+/** Names the source used to resolve shell orientation. */
+export type ShellContextSource = "DEFT_EXECUTION_SHELL" | "SHELL" | "os.userInfo().shell" | "ComSpec" | "unknown";
+/** Validated shell orientation with explicit semantics and provenance. */
+export interface ShellContext {
+    readonly name: string;
+    readonly path: string | null;
+    readonly kind: ShellContextKind;
+    readonly source: ShellContextSource;
+}
+/** Host platform and shell facts safe to surface in session orientation. */
+export interface EnvironmentContext {
+    readonly hostPlatform: NodeJS.Platform;
+    readonly shell: ShellContext;
+}
+/** Injectable inputs for deterministic shell-context detection. */
+export interface DetectEnvironmentContextOptions {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+    readonly userShell?: string | null;
+    readonly readUserShell?: () => string | null;
+}
+/** Detect host platform and the best validated shell signal without inferring executor semantics. */
+export declare function detectEnvironmentContext(options?: DetectEnvironmentContextOptions): EnvironmentContext;
+/** Convert environment orientation to the stable snake-case CLI JSON contract. */
+export declare function environmentContextToDict(context: EnvironmentContext): Record<string, unknown>;
+/** Format one injection-safe, source-attributed session orientation line. */
+export declare function formatEnvironmentContext(context: EnvironmentContext): string;
+//# sourceMappingURL=shell-context.d.ts.map

package/dist/platform/shell-context.js

@@ -0,0 +1,111 @@
+import { userInfo } from "node:os";
+import { posix, win32 } from "node:path";
+const MAX_SHELL_CANDIDATE_LENGTH = 4096;
+function readAccountShell(readUserShell) {
+    try {
+        return readUserShell();
+    }
+    catch {
+        return null;
+    }
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.charCodeAt(0);
+        if (codePoint <= 31 ||
+            (codePoint >= 127 && codePoint <= 159) ||
+            codePoint === 0x2028 ||
+            codePoint === 0x2029) {
+            return true;
+        }
+    }
+    return false;
+}
+function normalizeCandidate(candidate) {
+    const raw = candidate.value;
+    if (raw === null || raw === undefined)
+        return null;
+    if (raw.length > MAX_SHELL_CANDIDATE_LENGTH || hasControlCharacter(raw))
+        return null;
+    const value = raw.trim();
+    if (!value)
+        return null;
+    const lastSeparator = Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\"));
+    const basename = value.slice(lastSeparator + 1);
+    if (!basename)
+        return null;
+    const name = basename.replace(/\.exe$/i, "");
+    if (!name || name === "." || name === "..")
+        return null;
+    return {
+        name,
+        path: lastSeparator >= 0 && (posix.isAbsolute(value) || win32.isAbsolute(value)) ? value : null,
+        kind: candidate.kind,
+        source: candidate.source,
+    };
+}
+function renderValue(value) {
+    return /^[A-Za-z0-9_./:\\+()-]+$/.test(value) ? value : JSON.stringify(value);
+}
+/** Detect host platform and the best validated shell signal without inferring executor semantics. */
+export function detectEnvironmentContext(options = {}) {
+    const environ = options.environ ?? process.env;
+    const hostPlatform = options.platform ?? process.platform;
+    const accountShell = hostPlatform === "win32"
+        ? null
+        : options.userShell === undefined
+            ? readAccountShell(options.readUserShell ?? (() => userInfo().shell || null))
+            : options.userShell;
+    const candidates = [
+        {
+            value: environ.DEFT_EXECUTION_SHELL,
+            kind: "execution",
+            source: "DEFT_EXECUTION_SHELL",
+        },
+        { value: environ.SHELL, kind: "default", source: "SHELL" },
+        ...(hostPlatform === "win32"
+            ? [
+                {
+                    value: environ.ComSpec ?? environ.COMSPEC,
+                    kind: "default",
+                    source: "ComSpec",
+                },
+            ]
+            : [
+                {
+                    value: accountShell,
+                    kind: "default",
+                    source: "os.userInfo().shell",
+                },
+            ]),
+    ];
+    for (const candidate of candidates) {
+        const shell = normalizeCandidate(candidate);
+        if (shell)
+            return { hostPlatform, shell };
+    }
+    return {
+        hostPlatform,
+        shell: { name: "unknown", path: null, kind: "unknown", source: "unknown" },
+    };
+}
+/** Convert environment orientation to the stable snake-case CLI JSON contract. */
+export function environmentContextToDict(context) {
+    return {
+        host_platform: context.hostPlatform,
+        shell: {
+            name: context.shell.name,
+            path: context.shell.path,
+            kind: context.shell.kind,
+            source: context.shell.source,
+        },
+    };
+}
+/** Format one injection-safe, source-attributed session orientation line. */
+export function formatEnvironmentContext(context) {
+    const path = context.shell.path === null ? "unknown" : renderValue(context.shell.path);
+    return (`[deft environment] os=${renderValue(context.hostPlatform)}; ` +
+        `shell=${renderValue(context.shell.name)}; kind=${context.shell.kind}; ` +
+        `path=${path}; source=${context.shell.source}`);
+}
+//# sourceMappingURL=shell-context.js.map

package/dist/pr-monitor/cadence.d.ts

@@ -1,3 +1,9 @@
 /** Expand cadence tuple into per-poll interval seconds. */
 export declare function cadenceIntervals(cadence?: ReadonlyArray<readonly [number, number]>): number[];
+/**
+ * Seconds to sleep after poll `pollIndex` (1-based). Repeats the final cadence
+ * tier once the configured repeats are exhausted so the monitor can run until
+ * the cap instead of stopping after a fixed poll budget (#2581).
+ */
+export declare function cadenceIntervalAfterPoll(pollIndex: number, cadence?: ReadonlyArray<readonly [number, number]>): number;
 //# sourceMappingURL=cadence.d.ts.map

package/dist/pr-monitor/cadence.js

@@ -9,4 +9,17 @@ export function cadenceIntervals(cadence = DEFAULT_CADENCE) {
     }
     return intervals;
 }
+/**
+ * Seconds to sleep after poll `pollIndex` (1-based). Repeats the final cadence
+ * tier once the configured repeats are exhausted so the monitor can run until
+ * the cap instead of stopping after a fixed poll budget (#2581).
+ */
+export function cadenceIntervalAfterPoll(pollIndex, cadence = DEFAULT_CADENCE) {
+    const intervals = cadenceIntervals(cadence);
+    if (intervals.length === 0) {
+        return 60;
+    }
+    const idx = Math.min(Math.max(pollIndex, 1) - 1, intervals.length - 1);
+    return intervals[idx] ?? intervals[intervals.length - 1] ?? 60;
+}
 //# sourceMappingURL=cadence.js.map

package/dist/pr-monitor/index.d.ts

@@ -1,4 +1,4 @@
-export { cadenceIntervals } from "./cadence.js";
+export { cadenceIntervalAfterPoll, cadenceIntervals } from "./cadence.js";
 export { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 export { cmdPrMonitor, parseMonitorArgs, runMonitor } from "./main.js";
 export { formatPollStatus, isTerminalPrState, mergeStateFromPayload, monitor, summaryLabelForExit, } from "./monitor.js";

package/dist/pr-monitor/index.js

@@ -1,4 +1,4 @@
-export { cadenceIntervals } from "./cadence.js";
+export { cadenceIntervalAfterPoll, cadenceIntervals } from "./cadence.js";
 export { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 export { cmdPrMonitor, parseMonitorArgs, runMonitor } from "./main.js";
 export { formatPollStatus, isTerminalPrState, mergeStateFromPayload, monitor, summaryLabelForExit, } from "./monitor.js";

package/dist/pr-monitor/monitor.d.ts

@@ -1,4 +1,11 @@
 import type { MonitorOptions, MonitorRunResult, PollResult } from "./types.js";
+/**
+ * Truncate blocked-on text for one-line heartbeats while preserving
+ * distinguishable SHA prefixes during update-branch races (#2581).
+ */
+export declare function truncateBlockedOn(failure: string, maxLen?: number): string;
+/** Emit interim stderr heartbeats during long sleeps (#2581 / #2260). */
+export declare function sleepWithCadenceHeartbeats(totalSeconds: number, priorCadenceSeconds: number, nextPollIndex: number, sleepFn: (seconds: number) => void): void;
 /** Pull GitHub's merge-state signal out of a readiness payload, if present. */
 export declare function mergeStateFromPayload(payload: Record<string, unknown>): string;
 /**

package/dist/pr-monitor/monitor.js

@@ -1,4 +1,4 @@
-import { cadenceIntervals } from "./cadence.js";
+import { cadenceIntervalAfterPoll } from "./cadence.js";
 import { DEFAULT_CADENCE, EXIT_CAP_REACHED, EXIT_CLEAN, EXIT_CONFIG_ERROR, EXIT_PR_TERMINAL, } from "./constants.js";
 import { callReadiness } from "./readiness.js";
 const systemMonotonicClock = {
@@ -13,6 +13,52 @@ function defaultSleep(seconds) {
         // busy-wait fallback when no injectable sleep in production CLI path
     }
 }
+const GREPTILE_STALE_SHA_RE = /^Greptile last reviewed ([0-9a-f]+) but PR HEAD is ([0-9a-f]+)\./i;
+/**
+ * Truncate blocked-on text for one-line heartbeats while preserving
+ * distinguishable SHA prefixes during update-branch races (#2581).
+ */
+export function truncateBlockedOn(failure, maxLen = 80) {
+    const match = GREPTILE_STALE_SHA_RE.exec(failure);
+    if (match !== null) {
+        const reviewedSha = match[1];
+        const headSha = match[2];
+        if (reviewedSha !== undefined && headSha !== undefined) {
+            const compact = `Greptile last reviewed ${reviewedSha.slice(0, 12)}... ` +
+                `but PR HEAD is ${headSha.slice(0, 12)}...`;
+            if (compact.length <= maxLen) {
+                return compact;
+            }
+        }
+    }
+    return failure.slice(0, maxLen);
+}
+/** Emit interim stderr heartbeats during long sleeps (#2581 / #2260). */
+export function sleepWithCadenceHeartbeats(totalSeconds, priorCadenceSeconds, nextPollIndex, sleepFn) {
+    if (totalSeconds <= 0) {
+        return;
+    }
+    const maxSilentGap = Math.max(1, priorCadenceSeconds * 2);
+    if (totalSeconds <= maxSilentGap) {
+        sleepFn(totalSeconds);
+        return;
+    }
+    let remaining = totalSeconds;
+    let emittedWait = false;
+    while (remaining > 0) {
+        const chunk = Math.min(remaining, maxSilentGap);
+        if (!emittedWait) {
+            process.stderr.write(`[monitor_pr] waiting ${Math.ceil(remaining)}s until poll #${nextPollIndex} ` +
+                `(heartbeat cap ${maxSilentGap}s)\n`);
+            emittedWait = true;
+        }
+        else {
+            process.stderr.write(`[monitor_pr] still waiting ${Math.ceil(remaining)}s until poll #${nextPollIndex}\n`);
+        }
+        sleepFn(chunk);
+        remaining -= chunk;
+    }
+}
 /** Pull GitHub's merge-state signal out of a readiness payload, if present. */
 export function mergeStateFromPayload(payload) {
     const partialRaw = payload.partial_data;
@@ -61,7 +107,7 @@ export function formatPollStatus(pollIndex, pollResult, elapsedSeconds = 0) {
     let line = `[monitor_pr] poll #${pollIndex} t=${elapsed}s via=${via} head=${headDisplay} ` +
         `mergeState=${mergeState} ${label} (${failures.length} failures)`;
     if (firstFailure.length > 0) {
-        line += ` -- blocked-on: ${firstFailure.slice(0, 80)}`;
+        line += ` -- blocked-on: ${truncateBlockedOn(firstFailure)}`;
     }
     return line;
 }
@@ -75,7 +121,7 @@ export function isTerminalPrState(payload) {
 }
 /** Loop readiness with adaptive cadence until CLEAN / cap / terminal. */
 export function monitor(prNumber, repo, options = {}) {
-    const intervals = cadenceIntervals(options.cadence ?? DEFAULT_CADENCE);
+    const cadence = options.cadence ?? DEFAULT_CADENCE;
     const capSeconds = (options.capMinutes ?? 60) * 60;
     const clockFn = options.clockFn ?? systemMonotonicClock;
     const sleepFn = options.sleepFn ?? defaultSleep;
@@ -84,7 +130,8 @@ export function monitor(prNumber, repo, options = {}) {
     let pollIndex = 0;
     let lastPayload = {};
     let lastExit = EXIT_CAP_REACHED;
-    for (const interval of intervals) {
+    let priorCadenceSeconds = cadenceIntervalAfterPoll(1, cadence);
+    while (true) {
         pollIndex += 1;
         const elapsed = clockFn.now() - startedAt;
         if (elapsed > capSeconds) {
@@ -106,17 +153,16 @@ export function monitor(prNumber, repo, options = {}) {
         if (isTerminalPrState(lastPayload)) {
             return { exitCode: EXIT_PR_TERMINAL, payload: lastPayload, pollCount: pollIndex };
         }
-        if (pollIndex < intervals.length) {
-            const elapsedAfterPoll = clockFn.now() - startedAt;
-            const remaining = capSeconds - elapsedAfterPoll;
-            if (remaining <= 0) {
-                return { exitCode: EXIT_CAP_REACHED, payload: lastPayload, pollCount: pollIndex };
-            }
-            sleepFn(Math.min(interval, Math.max(1, Math.trunc(remaining))));
+        const elapsedAfterPoll = clockFn.now() - startedAt;
+        const remaining = capSeconds - elapsedAfterPoll;
+        if (remaining <= 0) {
+            const finalExit = lastExit === EXIT_CONFIG_ERROR ? EXIT_CONFIG_ERROR : EXIT_CAP_REACHED;
+            return { exitCode: finalExit, payload: lastPayload, pollCount: pollIndex };
         }
+        const sleepSeconds = Math.min(cadenceIntervalAfterPoll(pollIndex, cadence), Math.max(1, Math.trunc(remaining)));
+        sleepWithCadenceHeartbeats(sleepSeconds, priorCadenceSeconds, pollIndex + 1, sleepFn);
+        priorCadenceSeconds = sleepSeconds;
     }
-    const finalExit = lastExit === EXIT_CONFIG_ERROR ? EXIT_CONFIG_ERROR : EXIT_CAP_REACHED;
-    return { exitCode: finalExit, payload: lastPayload, pollCount: pollIndex };
 }
 export const summaryLabelForExit = (exitCode) => {
     switch (exitCode) {

package/dist/pr-wait-mergeable/wrappers.d.ts

@@ -17,6 +17,15 @@ export interface CaptureExecOptions {
 }
 /** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
 export declare function captureExec(executable: string, args: readonly string[], timeoutMs: number, options?: CaptureExecOptions): CaptureExecResult;
+/**
+ * Resolve a CLI entry script for subprocess spawn (#2615).
+ *
+ * Published npm layout nests `@deftai/directive-core` under `@deftai/directive`,
+ * so the old `../../../cli/dist` relative path resolved to a non-existent
+ * `@deftai/cli` sibling. Prefer the published package root, then monorepo path,
+ * then nested `@deftai/directive/dist`.
+ */
+export declare function cliScriptPath(name: string): string;
 export interface RunProtectedCheckOptions {
     readonly nodeExecutable?: string;
     readonly timeout?: number;