@poetic-ai/poetic 1.42.1-bootstrap.0

package/dist/chunk-NM6PMYY4.js

@@ -0,0 +1,768 @@
+import {
+  evaluateStaleReclaim
+} from "./chunk-P7CQGPLS.js";
+import {
+  atomicWriteJson
+} from "./chunk-A3YGID55.js";
+import {
+  resolvePoeticRoot
+} from "./chunk-LEIIWPWQ.js";
+import {
+  emitCustomWarning
+} from "./chunk-EJGCZGUF.js";
+
+// src/planning/backlog-execution-provenance.ts
+import { randomUUID } from "crypto";
+import * as fsSync from "fs";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+var BACKLOG_EXECUTION_STATUSES = [
+  "initialized",
+  "executing",
+  "blocked",
+  "pr-open",
+  "archive-sync-pending",
+  "delivered-local",
+  "merged",
+  "archived",
+  "failed"
+];
+var DELIVERY_BEARING_BACKLOG_EXECUTION_STATUSES = /* @__PURE__ */ new Set([
+  "pr-open",
+  "archive-sync-pending",
+  "delivered-local",
+  "merged",
+  "archived"
+]);
+function backlogExecutionStatusCarriesDelivery(status) {
+  return status !== null && status !== void 0 ? DELIVERY_BEARING_BACKLOG_EXECUTION_STATUSES.has(status) : false;
+}
+function resolveAdHocBacklogExecutionSuccessUpdates(outcome) {
+  const base = {
+    executingPid: null,
+    lastCompletedStep: "execute",
+    failedAtStep: null,
+    errorMessage: null
+  };
+  if (typeof outcome?.prNumber === "number" && Number.isFinite(outcome.prNumber)) {
+    return {
+      ...base,
+      status: "pr-open",
+      prNumber: outcome.prNumber
+    };
+  }
+  if (outcome?.deliveredLocal === true) {
+    return {
+      ...base,
+      status: "delivered-local",
+      prNumber: null
+    };
+  }
+  return base;
+}
+var BACKLOG_ITEM_COMMIT_TRAILER_KEY = "Poetic-Backlog-Item";
+function formatBacklogItemCommitTrailer(backlogItemId) {
+  return `${BACKLOG_ITEM_COMMIT_TRAILER_KEY}: ${backlogItemId}`;
+}
+function commitBodyContainsBacklogItemTrailer(commitBody, backlogItemId) {
+  const expected = formatBacklogItemCommitTrailer(backlogItemId);
+  return commitBody.split("\n").some((line) => line.trim() === expected || line.trim().startsWith(`${expected} `));
+}
+function evaluateAutoFinalizeEligibility(provenance, mergeCommit, evidence) {
+  if (provenance.status !== "pr-open") {
+    return { eligible: false, reason: `status is ${provenance.status} (expected pr-open)` };
+  }
+  if (provenance.prNumber === null || provenance.prNumber === void 0) {
+    return { eligible: false, reason: "missing prNumber on provenance record" };
+  }
+  if (!mergeCommit || mergeCommit.trim().length === 0) {
+    return { eligible: false, reason: `PR #${provenance.prNumber} is not merged` };
+  }
+  if (!evidence.validCommit) {
+    return { eligible: false, reason: `merge commit ${mergeCommit} is not a valid commit` };
+  }
+  if (!evidence.prMerged) {
+    return { eligible: false, reason: `PR #${provenance.prNumber} is not merged` };
+  }
+  if (!evidence.mergeCommitOnRemoteDefault) {
+    return {
+      eligible: false,
+      reason: `merge commit ${mergeCommit} is not on the remote default branch`
+    };
+  }
+  if (!evidence.mergeCommitMatchesPr) {
+    return {
+      eligible: false,
+      reason: `PR #${provenance.prNumber} merge commit does not match ${mergeCommit}`
+    };
+  }
+  if (!evidence.backlogItemMatchesPr) {
+    return {
+      eligible: false,
+      reason: `PR #${provenance.prNumber} is not linked to backlog item ${provenance.backlogItemId}`
+    };
+  }
+  return { eligible: true, mergeCommit: mergeCommit.trim() };
+}
+function evaluateArchiveSyncResumeEligibility(provenance, archiveSyncMergeCommit, evidence) {
+  if (provenance.status !== "archive-sync-pending") {
+    return {
+      eligible: false,
+      reason: `status is ${provenance.status} (expected archive-sync-pending)`
+    };
+  }
+  if (provenance.archiveSyncPrNumber === null) {
+    return { eligible: false, reason: "missing archiveSyncPrNumber on provenance record" };
+  }
+  if (provenance.prNumber === null) {
+    return { eligible: false, reason: "missing original prNumber on provenance record" };
+  }
+  if (!provenance.mergeCommit?.trim()) {
+    return { eligible: false, reason: "missing original mergeCommit on provenance record" };
+  }
+  if (!archiveSyncMergeCommit?.trim()) {
+    return {
+      eligible: false,
+      reason: `archive sync PR #${provenance.archiveSyncPrNumber} is not merged`
+    };
+  }
+  if (!evidence.validCommit) {
+    return {
+      eligible: false,
+      reason: `archive sync merge commit ${archiveSyncMergeCommit} is not a valid commit`
+    };
+  }
+  if (!evidence.prMerged) {
+    return {
+      eligible: false,
+      reason: `archive sync PR #${provenance.archiveSyncPrNumber} is not merged`
+    };
+  }
+  if (!evidence.mergeCommitOnRemoteDefault) {
+    return {
+      eligible: false,
+      reason: `archive sync merge commit ${archiveSyncMergeCommit} is not on the remote default branch`
+    };
+  }
+  if (!evidence.mergeCommitMatchesPr) {
+    return {
+      eligible: false,
+      reason: `archive sync PR #${provenance.archiveSyncPrNumber} merge commit does not match ${archiveSyncMergeCommit}`
+    };
+  }
+  return { eligible: true, mergeCommit: provenance.mergeCommit.trim() };
+}
+async function listBacklogExecutionProvenanceByStatus(projectRoot, status) {
+  const dir = provenanceDir(projectRoot);
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) {
+      continue;
+    }
+    const backlogItemId = entry.slice(0, -".json".length);
+    const provenance = await loadBacklogExecutionProvenance(projectRoot, backlogItemId, {
+      cleanupTerminalLocks: false
+    });
+    if (provenance?.status === status) {
+      matches.push(provenance);
+    }
+  }
+  matches.sort((a, b) => a.backlogItemId.localeCompare(b.backlogItemId));
+  return matches;
+}
+var DEFAULT_BACKLOG_EXECUTION_LOCK_RETRY_MS = 1e3;
+function emitBacklogExecutionProvenanceWarning(message, metadata) {
+  emitCustomWarning(
+    "WARN" /* WARN */,
+    "workspace_edits" /* WORKSPACE_EDITS */,
+    message,
+    {
+      taskId: "backlog-execution-provenance",
+      subsystem: "planning/backlog-execution-provenance",
+      executionPhase: "execution"
+    },
+    { metadata, skipConsole: true }
+  );
+}
+function isTerminalBacklogExecutionStatus(status) {
+  return status === "archived" || status === "merged";
+}
+function provenanceDir(projectRoot) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const sharedRoot = fsSync.existsSync(path.join(resolvedProjectRoot, ".git")) ? resolvePoeticRoot(resolvedProjectRoot) : resolvedProjectRoot;
+  return path.join(sharedRoot, ".poetic", "provenance");
+}
+function lockDir(projectRoot) {
+  return path.join(provenanceDir(projectRoot), "locks");
+}
+function lockPath(projectRoot, backlogItemId) {
+  return path.join(lockDir(projectRoot), `${backlogItemId}.lock`);
+}
+function getBacklogExecutionProvenancePath(projectRoot, backlogItemId) {
+  return path.join(provenanceDir(projectRoot), `${backlogItemId}.json`);
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizePendingBlockers(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") return [];
+    const candidate = entry;
+    if (typeof candidate.question !== "string" || candidate.question.trim().length === 0) {
+      return [];
+    }
+    return [
+      {
+        ...typeof candidate.id === "string" && candidate.id.trim().length > 0 ? { id: candidate.id } : {},
+        question: candidate.question,
+        ...Array.isArray(candidate.stageIds) ? {
+          stageIds: candidate.stageIds.filter(
+            (stageId) => typeof stageId === "string"
+          )
+        } : {}
+      }
+    ];
+  });
+}
+function normalizeLoadedBacklogExecutionProvenance(provenance) {
+  return {
+    ...provenance,
+    taskIds: Array.isArray(provenance.taskIds) ? provenance.taskIds : [],
+    pendingBlockers: normalizePendingBlockers(
+      provenance.pendingBlockers
+    )
+  };
+}
+function isBacklogExecutionStatus(value) {
+  return typeof value === "string" && BACKLOG_EXECUTION_STATUSES.includes(value);
+}
+function parseBacklogExecutionProvenanceFile(raw, filePath, expectedBacklogItemId) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    emitBacklogExecutionProvenanceWarning(
+      `[poetic] Corrupt backlog execution provenance at ${filePath}; treating it as absent and reinitializing execution state.`,
+      {
+        filePath,
+        error: error instanceof Error ? error.message : String(error),
+        operation: "parse-backlog-execution-provenance"
+      }
+    );
+    return null;
+  }
+  const candidate = parsed;
+  if (!candidate || typeof candidate !== "object" || typeof candidate.backlogItemId !== "string" || candidate.backlogItemId.trim().length === 0 || !isBacklogExecutionStatus(candidate.status)) {
+    emitBacklogExecutionProvenanceWarning(
+      `[poetic] Invalid backlog execution provenance at ${filePath} (missing or malformed backlogItemId/status); treating it as absent and reinitializing execution state.`,
+      {
+        filePath,
+        operation: "validate-backlog-execution-provenance"
+      }
+    );
+    return null;
+  }
+  if (candidate.backlogItemId !== expectedBacklogItemId) {
+    emitBacklogExecutionProvenanceWarning(
+      `[poetic] Backlog execution provenance at ${filePath} records backlogItemId ${candidate.backlogItemId}, which does not match the item it was loaded for (${expectedBacklogItemId}); treating it as absent. Remove or rename the file so each record identifies exactly one backlog item.`,
+      {
+        filePath,
+        expectedBacklogItemId,
+        recordedBacklogItemId: candidate.backlogItemId,
+        operation: "validate-backlog-execution-provenance-id-binding"
+      }
+    );
+    return null;
+  }
+  return normalizeLoadedBacklogExecutionProvenance(candidate);
+}
+async function ensureBacklogExecutionProvenanceDir(projectRoot) {
+  await fs.mkdir(provenanceDir(projectRoot), { recursive: true });
+  await fs.mkdir(lockDir(projectRoot), { recursive: true });
+}
+function ensureBacklogExecutionProvenanceDirSync(projectRoot) {
+  fsSync.mkdirSync(provenanceDir(projectRoot), { recursive: true });
+  fsSync.mkdirSync(lockDir(projectRoot), { recursive: true });
+}
+function createInitialBacklogExecutionProvenance(backlogItemId) {
+  const timestamp = nowIso();
+  return {
+    backlogItemId,
+    branch: null,
+    branchRole: null,
+    sourceBranch: null,
+    sourceBranchRole: null,
+    branchRoleAction: null,
+    branchRoleOverride: null,
+    workflowId: null,
+    sprintId: null,
+    taskIds: [],
+    planArtifact: null,
+    prNumber: null,
+    mergeCommit: null,
+    archiveSyncPrNumber: null,
+    archiveSyncWarning: null,
+    status: "initialized",
+    executingPid: null,
+    executingStartedAt: null,
+    lastCompletedStep: null,
+    failedAtStep: null,
+    errorMessage: null,
+    pendingBlockers: [],
+    createdAt: timestamp,
+    updatedAt: timestamp
+  };
+}
+async function loadBacklogExecutionProvenance(projectRoot, backlogItemId, options = {}) {
+  const filePath = getBacklogExecutionProvenancePath(projectRoot, backlogItemId);
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const provenance = parseBacklogExecutionProvenanceFile(raw, filePath, backlogItemId);
+    if (!provenance) {
+      return null;
+    }
+    if (options.cleanupTerminalLocks !== false) {
+      await cleanupTerminalBacklogExecutionLock(projectRoot, backlogItemId, provenance);
+    }
+    return provenance;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+}
+function backlogExecutionLockHostIdentity() {
+  const envHostname = process.env.HOSTNAME?.trim();
+  return envHostname || os.hostname() || "unknown";
+}
+var LOCK_HOST_LINE_PREFIX = "host=";
+function formatBacklogExecutionLockContent(ownerToken) {
+  return `${ownerToken}
+${(/* @__PURE__ */ new Date()).toISOString()}
+${LOCK_HOST_LINE_PREFIX}${backlogExecutionLockHostIdentity()}
+`;
+}
+function parseBacklogExecutionLockContent(content) {
+  const lines = content.split("\n");
+  const ownerToken = (lines[0] ?? "").trim();
+  const pid = Number.parseInt(ownerToken.split(":")[0] ?? "", 10);
+  const hostLine = lines.map((line) => line.trim()).find((line) => line.startsWith(LOCK_HOST_LINE_PREFIX));
+  const host = hostLine ? hostLine.slice(LOCK_HOST_LINE_PREFIX.length).trim() : "";
+  return {
+    ownerToken,
+    pid: Number.isFinite(pid) ? pid : null,
+    host: host.length > 0 ? host : null
+  };
+}
+function observeBacklogExecutionLockHolder(payload) {
+  if (payload.pid === null) {
+    return null;
+  }
+  const currentHost = backlogExecutionLockHostIdentity();
+  const sameHost = payload.host === null || payload.host !== "unknown" && payload.host === currentHost;
+  return { sameHost, pidAlive: sameHost ? isPidAlive(payload.pid) : false };
+}
+var FOREIGN_HOST_BACKLOG_EXECUTION_LOCK_STALE_MS = 3e5;
+var FOREIGN_HOST_BACKLOG_EXECUTION_LOCK_MULTIPLIER = 3;
+function shouldReclaimBacklogExecutionLock(payload, ageMs) {
+  const holder = observeBacklogExecutionLockHolder(payload);
+  if (holder === null) {
+    return true;
+  }
+  return evaluateStaleReclaim(
+    { ageMs, holder },
+    {
+      staleMs: FOREIGN_HOST_BACKLOG_EXECUTION_LOCK_STALE_MS,
+      corruptPayload: "reclaim",
+      foreignHost: {
+        kind: "after-multiplier",
+        multiplier: FOREIGN_HOST_BACKLOG_EXECUTION_LOCK_MULTIPLIER
+      },
+      sameHostDeadPid: "immediate"
+    }
+  ) === "reclaim";
+}
+async function backlogExecutionLockAgeMs(filePath) {
+  try {
+    const stat2 = await fs.stat(filePath);
+    return Math.max(0, Date.now() - stat2.mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+async function isBacklogExecutionLockHeldByLiveProcess(projectRoot, backlogItemId) {
+  const filePath = lockPath(projectRoot, backlogItemId);
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    const payload = parseBacklogExecutionLockContent(content);
+    return !shouldReclaimBacklogExecutionLock(payload, await backlogExecutionLockAgeMs(filePath));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function readBacklogExecutionLockPayload(projectRoot, backlogItemId) {
+  const filePath = lockPath(projectRoot, backlogItemId);
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    return parseBacklogExecutionLockContent(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+async function isBacklogExecutionProvenanceActivelyExecuting(projectRoot, provenance) {
+  if (provenance.status !== "executing") {
+    return false;
+  }
+  if (await isBacklogExecutionLockHeldByLiveProcess(projectRoot, provenance.backlogItemId)) {
+    const lock = await readBacklogExecutionLockPayload(projectRoot, provenance.backlogItemId);
+    const holder = lock ? observeBacklogExecutionLockHolder(lock) : null;
+    if (holder?.sameHost === true && lock?.pid === process.pid) {
+      if (provenance.executingPid == null) {
+        return false;
+      }
+      return isPidAlive(provenance.executingPid);
+    }
+    return true;
+  }
+  if (typeof provenance.executingPid === "number") {
+    return isPidAlive(provenance.executingPid);
+  }
+  return false;
+}
+async function cleanupTerminalBacklogExecutionLock(projectRoot, backlogItemId, provenance) {
+  if (!isTerminalBacklogExecutionStatus(provenance.status)) {
+    return;
+  }
+  const filePath = lockPath(projectRoot, backlogItemId);
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    const payload = parseBacklogExecutionLockContent(content);
+    if (await shouldReclaimBacklogExecutionLockFile(filePath, payload)) {
+      await removeBacklogExecutionLockIfOwnerMatches(filePath, payload.ownerToken);
+    }
+  } catch {
+    return;
+  }
+}
+async function shouldReclaimBacklogExecutionLockFile(filePath, payload) {
+  return shouldReclaimBacklogExecutionLock(payload, await backlogExecutionLockAgeMs(filePath));
+}
+async function removeBacklogExecutionLockIfOwnerMatches(filePath, expectedOwnerToken, expectedIdentity) {
+  const reclaimPath = `${filePath}.reclaim.${process.pid}.${Date.now().toString(36)}.${randomUUID()}`;
+  try {
+    await fs.link(filePath, reclaimPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    const currentContent = await fs.readFile(reclaimPath, "utf8");
+    const currentOwnerToken = (currentContent.split("\n")[0] ?? "").trim();
+    if (currentOwnerToken !== expectedOwnerToken) {
+      return false;
+    }
+    const [currentStat, reclaimStat] = await Promise.all([
+      fs.stat(filePath).catch(() => null),
+      fs.stat(reclaimPath)
+    ]);
+    if (expectedIdentity && (reclaimStat.dev !== expectedIdentity.dev || reclaimStat.ino !== expectedIdentity.ino)) {
+      return false;
+    }
+    if (!currentStat || currentStat.dev !== reclaimStat.dev || currentStat.ino !== reclaimStat.ino) {
+      return false;
+    }
+    await fs.unlink(filePath);
+    return true;
+  } finally {
+    await fs.unlink(reclaimPath).catch(() => void 0);
+  }
+}
+async function removeBacklogExecutionLockIfIdentityMatches(filePath, expectedIdentity) {
+  const reclaimPath = `${filePath}.reclaim.${process.pid}.${Date.now().toString(36)}.${randomUUID()}`;
+  try {
+    await fs.link(filePath, reclaimPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    const [currentStat, reclaimStat] = await Promise.all([
+      fs.stat(filePath).catch(() => null),
+      fs.stat(reclaimPath)
+    ]);
+    if (reclaimStat.dev !== expectedIdentity.dev || reclaimStat.ino !== expectedIdentity.ino || !currentStat || currentStat.dev !== reclaimStat.dev || currentStat.ino !== reclaimStat.ino) {
+      return false;
+    }
+    await fs.unlink(filePath);
+    return true;
+  } finally {
+    await fs.unlink(reclaimPath).catch(() => void 0);
+  }
+}
+function removeBacklogExecutionLockIfOwnerMatchesSync(filePath, expectedOwnerToken, expectedIdentity) {
+  const reclaimPath = `${filePath}.reclaim.${process.pid}.${Date.now().toString(36)}.${randomUUID()}`;
+  try {
+    fsSync.linkSync(filePath, reclaimPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    const currentContent = fsSync.readFileSync(reclaimPath, "utf8");
+    const currentOwnerToken = (currentContent.split("\n")[0] ?? "").trim();
+    if (currentOwnerToken !== expectedOwnerToken) {
+      return false;
+    }
+    const reclaimStat = fsSync.statSync(reclaimPath);
+    let currentStat;
+    try {
+      currentStat = fsSync.statSync(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+    if (reclaimStat.dev !== expectedIdentity.dev || reclaimStat.ino !== expectedIdentity.ino || currentStat.dev !== reclaimStat.dev || currentStat.ino !== reclaimStat.ino) {
+      return false;
+    }
+    fsSync.unlinkSync(filePath);
+    return true;
+  } finally {
+    try {
+      fsSync.unlinkSync(reclaimPath);
+    } catch {
+    }
+  }
+}
+async function cleanupTerminalBacklogExecutionLockFromStoredProvenance(projectRoot, backlogItemId) {
+  const filePath = getBacklogExecutionProvenancePath(projectRoot, backlogItemId);
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const provenance = parseBacklogExecutionProvenanceFile(raw, filePath, backlogItemId);
+    if (!provenance) {
+      return;
+    }
+    await cleanupTerminalBacklogExecutionLock(projectRoot, backlogItemId, provenance);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+function normalizeBacklogExecutionProvenance(provenance) {
+  if (!isTerminalBacklogExecutionStatus(provenance.status)) {
+    return provenance;
+  }
+  return {
+    ...provenance,
+    failedAtStep: null,
+    errorMessage: null,
+    pendingBlockers: []
+  };
+}
+function warnIfMergedWithoutCommit(provenance) {
+  if (provenance.status === "merged" && !provenance.mergeCommit) {
+    emitBacklogExecutionProvenanceWarning(
+      `[poetic] Persisting backlog item ${provenance.backlogItemId} as merged without a mergeCommit; the record cannot prove the merge landed.`,
+      {
+        backlogItemId: provenance.backlogItemId,
+        operation: "save-merged-without-merge-commit"
+      }
+    );
+  }
+}
+async function saveBacklogExecutionProvenance(projectRoot, provenance) {
+  warnIfMergedWithoutCommit(provenance);
+  await ensureBacklogExecutionProvenanceDir(projectRoot);
+  const filePath = getBacklogExecutionProvenancePath(projectRoot, provenance.backlogItemId);
+  const next = {
+    ...normalizeBacklogExecutionProvenance(provenance),
+    updatedAt: nowIso()
+  };
+  await atomicWriteJson(filePath, next);
+}
+function saveBacklogExecutionProvenanceSync(projectRoot, provenance) {
+  warnIfMergedWithoutCommit(provenance);
+  ensureBacklogExecutionProvenanceDirSync(projectRoot);
+  const filePath = getBacklogExecutionProvenancePath(projectRoot, provenance.backlogItemId);
+  const next = {
+    ...normalizeBacklogExecutionProvenance(provenance),
+    updatedAt: nowIso()
+  };
+  const dir = path.dirname(filePath);
+  const tempPath = path.join(dir, `.tmp.${process.pid}.${Date.now()}.${randomUUID()}`);
+  fsSync.writeFileSync(tempPath, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  fsSync.renameSync(tempPath, filePath);
+}
+async function updateBacklogExecutionProvenance(projectRoot, backlogItemId, updates) {
+  const current = await loadBacklogExecutionProvenance(projectRoot, backlogItemId) ?? createInitialBacklogExecutionProvenance(backlogItemId);
+  const next = {
+    ...current,
+    ...updates,
+    backlogItemId
+  };
+  if (updates.status && updates.status !== "blocked") {
+    next.pendingBlockers = [];
+  }
+  if (next.status === "merged" && !next.mergeCommit) {
+    throw new Error(
+      `Refusing to mark backlog item ${backlogItemId} as merged without a mergeCommit; include mergeCommit in the same update.`
+    );
+  }
+  await saveBacklogExecutionProvenance(projectRoot, next);
+  return next;
+}
+async function acquireBacklogExecutionLock(projectRoot, backlogItemId) {
+  await ensureBacklogExecutionProvenanceDir(projectRoot);
+  await cleanupTerminalBacklogExecutionLockFromStoredProvenance(projectRoot, backlogItemId);
+  const filePath = lockPath(projectRoot, backlogItemId);
+  const retryDeadlineMs = Date.now() + DEFAULT_BACKLOG_EXECUTION_LOCK_RETRY_MS;
+  const ownerToken = `${process.pid}:${randomUUID()}`;
+  const attemptCreate = async () => {
+    const handle = await fs.open(filePath, "wx");
+    let partialIdentity = null;
+    try {
+      const partialStat = await handle.stat();
+      partialIdentity = { dev: partialStat.dev, ino: partialStat.ino };
+      await handle.writeFile(formatBacklogExecutionLockContent(ownerToken), "utf8");
+      await handle.close();
+    } catch (error) {
+      await handle.close().catch(() => {
+      });
+      if (partialIdentity) {
+        await removeBacklogExecutionLockIfIdentityMatches(filePath, partialIdentity).catch(
+          () => false
+        );
+      }
+      throw error;
+    }
+    const stat2 = await fs.stat(filePath);
+    return { path: filePath, ownerToken, lockDev: stat2.dev, lockIno: stat2.ino };
+  };
+  const blockingError = new Error(
+    `Backlog item ${backlogItemId} is already being executed. Remove ${path.relative(projectRoot, filePath)} if the prior run is stale.`
+  );
+  while (true) {
+    try {
+      return await attemptCreate();
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      let isStale = false;
+      let stalePid = null;
+      let staleHost = null;
+      let staleOwnerToken = "";
+      try {
+        const content = await fs.readFile(filePath, "utf8");
+        const payload = parseBacklogExecutionLockContent(content);
+        staleOwnerToken = payload.ownerToken;
+        stalePid = payload.pid;
+        staleHost = payload.host;
+        isStale = await shouldReclaimBacklogExecutionLockFile(filePath, payload);
+      } catch {
+        isStale = true;
+      }
+      if (!isStale) {
+        if (Date.now() < retryDeadlineMs) {
+          await new Promise((resolve2) => setTimeout(resolve2, 10));
+          continue;
+        }
+        throw blockingError;
+      }
+      emitBacklogExecutionProvenanceWarning(
+        `[poetic] Stale lock detected for backlog item ${backlogItemId} (stale PID: ${stalePid ?? "unknown"}, host: ${staleHost ?? "unknown"}). Auto-recovering lock at ${filePath}.`,
+        {
+          backlogItemId,
+          filePath,
+          stalePid: stalePid ?? "unknown",
+          staleHost: staleHost ?? "unknown",
+          operation: "recover-stale-backlog-execution-lock"
+        }
+      );
+      await removeBacklogExecutionLockIfOwnerMatches(filePath, staleOwnerToken).catch(() => false);
+      await new Promise((resolve2) => setTimeout(resolve2, 10));
+    }
+  }
+}
+async function releaseBacklogExecutionLock(lock) {
+  try {
+    await removeBacklogExecutionLockIfOwnerMatches(lock.path, lock.ownerToken, {
+      dev: lock.lockDev,
+      ino: lock.lockIno
+    });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+function releaseBacklogExecutionLockSync(lock) {
+  try {
+    removeBacklogExecutionLockIfOwnerMatchesSync(lock.path, lock.ownerToken, {
+      dev: lock.lockDev,
+      ino: lock.lockIno
+    });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+export {
+  backlogExecutionStatusCarriesDelivery,
+  resolveAdHocBacklogExecutionSuccessUpdates,
+  BACKLOG_ITEM_COMMIT_TRAILER_KEY,
+  formatBacklogItemCommitTrailer,
+  commitBodyContainsBacklogItemTrailer,
+  evaluateAutoFinalizeEligibility,
+  evaluateArchiveSyncResumeEligibility,
+  listBacklogExecutionProvenanceByStatus,
+  getBacklogExecutionProvenancePath,
+  createInitialBacklogExecutionProvenance,
+  loadBacklogExecutionProvenance,
+  isBacklogExecutionProvenanceActivelyExecuting,
+  saveBacklogExecutionProvenance,
+  saveBacklogExecutionProvenanceSync,
+  updateBacklogExecutionProvenance,
+  acquireBacklogExecutionLock,
+  releaseBacklogExecutionLock,
+  releaseBacklogExecutionLockSync
+};
+//# sourceMappingURL=chunk-NM6PMYY4.js.map