@fieldwangai/agentflow 0.1.135 → 0.1.137

package/bin/lib/ui-server.mjs

@@ -156,6 +156,7 @@ import {
   ensurePrdWorkflowCollaboration,
   getPrdWorkflowCollaborationById,
   getPrdWorkflowCollaborationByShareToken,
+  getPrdWorkflowCollaborationByTapdId,
   getPrdWorkflowCollaborationForUser,
   ensurePrdWorkflowShareLink,
   listPrdWorkflowCollaborationsForUser,
@@ -164,6 +165,7 @@ import {
   prdWorkflowCollaborationSummary,
   removePrdWorkflowCollaborationMember,
   revokePrdWorkflowShareLink,
+  syncPrdWorkflowAuthority,
 } from "./prd-workflow-collaboration.mjs";
 import {
   createTeam,
@@ -176,6 +178,7 @@ import {
 } from "./teams.mjs";
 import {
   legacyOverallToGlobalState,
+  materializeWorkflowExtensions,
   materializeWorkflowGlobalState,
   materializeWorkflowProjections,
   mergeWorkflowArtifactLists,
@@ -183,7 +186,10 @@ import {
   mergeWorkflowGlobalState,
   normalizeWorkflowReference,
   normalizeWorkflowReport,
+  removeWorkflowGlobalStatePath,
+  workflowReportResourceKeys,
   workflowRuntimeRevision,
+  workflowSnapshotResourceVersions,
 } from "./workflow-report.mjs";
 
 const MIME = {
@@ -1445,11 +1451,31 @@ function skillhubInstallArgs(payload, { uninstall = false } = {}) {
   return args;
 }
 
-function readBody(req) {
+function readBody(req, maxBytes = 5 * 1024 * 1024) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    let total = 0;
+    let exceeded = false;
+    req.on("data", (chunk) => {
+      if (exceeded) return;
+      const value = Buffer.from(chunk);
+      total += value.length;
+      if (total > maxBytes) {
+        exceeded = true;
+        chunks.length = 0;
+        return;
+      }
+      chunks.push(value);
+    });
+    req.on("end", () => {
+      if (exceeded) {
+        const error = new Error(`Request body exceeds ${maxBytes} bytes`);
+        error.status = 413;
+        reject(error);
+        return;
+      }
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
     req.on("error", reject);
   });
 }
@@ -3314,6 +3340,21 @@ function findWorkspaceShareUser(username) {
   return null;
 }
 
+function workflowAuthorityIdentity(value) {
+  if (typeof value === "string" || typeof value === "number") return String(value || "").trim();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+  return String(value.username || value.userId || value.user_id || value.nick || value.name || "").trim();
+}
+
+function workflowAuthorityIdentities(value) {
+  const values = Array.isArray(value) ? value : value == null ? [] : [value];
+  return [...new Set(values.flatMap((item) => {
+    if (typeof item === "string") return item.split(/[;,，；]/).map((entry) => entry.trim()).filter(Boolean);
+    const identity = workflowAuthorityIdentity(item);
+    return identity ? [identity] : [];
+  }))];
+}
+
 function workspaceCollaborationSummaryWithUsers(record, userId) {
   const summary = workspaceCollaborationSummary(record, userId);
   if (!summary) return null;
@@ -7779,6 +7820,7 @@ const workspaceCollaborationSequences = new Map();
 const prdWorkflowSubscribers = new Map();
 const prdWorkflowIdempotency = new Map();
 const prdWorkflowActionLocks = new Map();
+const prdWorkflowWriteQueues = new Map();
 const PRD_WORKFLOW_IDEMPOTENCY_MAX = 1000;
 const PRD_WORKFLOW_RUNTIME_EVENTS_MAX = 1000;
 const WORKSPACE_SCHEDULES_FILENAME = "workspace-schedules.json";
@@ -7787,6 +7829,22 @@ const WORKSPACE_IMPLEMENTATION_REFERENCE_ENABLED = true;
 const WORKSPACE_IMPLEMENTATION_SUMMARY_ENABLED = false;
 const WORKSPACE_NODE_HISTORY_MAX_CHARS = 80000;
 
+async function prdWorkflowAcquireWriteLock(key) {
+  const lockKey = String(key || "").trim();
+  const previous = prdWorkflowWriteQueues.get(lockKey) || Promise.resolve();
+  let releaseCurrent;
+  const current = new Promise((resolve) => { releaseCurrent = resolve; });
+  prdWorkflowWriteQueues.set(lockKey, current);
+  await previous.catch(() => {});
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    releaseCurrent();
+    if (prdWorkflowWriteQueues.get(lockKey) === current) prdWorkflowWriteQueues.delete(lockKey);
+  };
+}
+
 function resolvePrdWorkflowScope(workspaceRoot, params = {}, userCtx = {}, capability = "read") {
   const tapdId = String(params.tapdId || params.tapd_id || "").trim();
   const flowId = String(params.flowId || "").trim();
@@ -7811,6 +7869,10 @@ function resolvePrdWorkflowScope(workspaceRoot, params = {}, userCtx = {}, capab
   const memberCollaboration = tapdId
     ? getPrdWorkflowCollaborationForUser(tapdId, userCtx?.userId)
     : null;
+  const existingCollaboration = tapdId ? getPrdWorkflowCollaborationByTapdId(tapdId) : null;
+  if (!adminOwner && !linkCollaboration && existingCollaboration && !memberCollaboration) {
+    return { error: "PRD Workflow collaboration permission denied", status: 403 };
+  }
   const collaboration = adminOwner ? null : (linkCollaboration || memberCollaboration);
   const access = adminOwner
     ? { allowed: true, writable: false, role: "admin-viewer", via: "admin-review" }
@@ -7824,7 +7886,8 @@ function resolvePrdWorkflowScope(workspaceRoot, params = {}, userCtx = {}, capab
     return { error: "PRD Workflow collaboration edit permission denied", status: 403 };
   }
   const ownerId = String(adminOwner?.userId || collaboration?.ownerId || userCtx?.userId || "").trim();
-  const stateRoot = path.resolve(getAgentflowUserDataRoot(ownerId));
+  const stateOwnerId = String(adminOwner?.userId || collaboration?.stateOwnerId || collaboration?.ownerId || userCtx?.userId || "").trim();
+  const stateRoot = path.resolve(getAgentflowUserDataRoot(stateOwnerId));
   let executionRoot = path.resolve(workspaceRoot);
   if (flowId) {
     const projectScope = resolveWorkspaceScopeRoot(workspaceRoot, {
@@ -7846,6 +7909,7 @@ function resolvePrdWorkflowScope(workspaceRoot, params = {}, userCtx = {}, capab
     executionRoot,
     stateRoot,
     ownerId,
+    stateOwnerId,
     collaboration,
     collaborationAccess: access,
     shareToken,
@@ -7862,7 +7926,7 @@ function prdWorkflowKey(userCtx = {}, flowSource = "user", flowId = "", tapdId =
   const collaboration = getPrdWorkflowCollaborationByShareToken(shareToken)
     || getPrdWorkflowCollaborationForUser(id, userCtx?.userId);
   const adminOwnerId = userCtx?.isAdmin === true ? String(userCtx?.adminOwnerId || "").trim() : "";
-  const actorScope = `user:${String(collaboration?.ownerId || adminOwnerId || userCtx?.userId || "")}`;
+  const actorScope = `user:${String(collaboration?.stateOwnerId || collaboration?.ownerId || adminOwnerId || userCtx?.userId || "")}`;
   return [actorScope, id].join("\t");
 }
 
@@ -7997,7 +8061,17 @@ function prdWorkflowSafeStateId(value) {
 }
 
 function prdWorkflowReviewIdFromRequest(tapdId, payload = {}, durability = "temporary") {
-  if (durability === "temporary") return `r-${crypto.randomBytes(5).toString("hex")}`;
+  if (durability === "temporary") {
+    const idempotencyKey = String(payload.idempotencyKey || payload.idempotency_key || "").trim();
+    if (!idempotencyKey) return `r-${crypto.randomBytes(5).toString("hex")}`;
+    const source = String(payload.source || "agentflow-cli").trim().toLowerCase() || "agentflow-cli";
+    const digest = crypto
+      .createHash("sha256")
+      .update(JSON.stringify({ tapdId: String(tapdId || ""), source, idempotencyKey }))
+      .digest("hex")
+      .slice(0, 12);
+    return `r-${digest}`;
+  }
   const requested = String(payload.reviewId || payload.review_id || "").trim();
   if (!requested) return `review_${Date.now().toString(36)}_${crypto.randomBytes(4).toString("hex")}`;
   const safeRequested = prdWorkflowSafeStateId(requested);
@@ -8064,6 +8138,11 @@ function prdWorkflowEventsPath(scopedRoot, tapdId) {
   return path.join(rootDir, ".workspace", "prd-flow", "workflow-state", `${prdWorkflowSafeStateId(tapdId)}.events.json`);
 }
 
+function prdWorkflowEventsArchivePath(scopedRoot, tapdId) {
+  const rootDir = scopedRoot || process.cwd();
+  return path.join(rootDir, ".workspace", "prd-flow", "workflow-state", `${prdWorkflowSafeStateId(tapdId)}.events.archive.jsonl`);
+}
+
 function prdWorkflowAuditPath(scopedRoot, tapdId) {
   const rootDir = scopedRoot || process.cwd();
   return path.join(rootDir, ".workspace", "prd-flow", "workflow-state", `${prdWorkflowSafeStateId(tapdId)}.audit.jsonl`);
@@ -9701,10 +9780,20 @@ export function prdWorkflowReviewHtml(title, markdown, meta = {}) {
 }
 
 function prdWorkflowCreateReview(scopedRoot, tapdId, payload = {}, urlBase = "", ownerId = "") {
-  const content = String(payload.markdown || payload.content || payload.rawOutput || "").slice(0, 500000);
+  const content = String(payload.markdown || payload.content || payload.rawOutput || "");
   if (!content.trim()) throw new Error("Missing review markdown");
+  if (Buffer.byteLength(content, "utf-8") > 500000) {
+    const error = new Error("Review markdown exceeds 500000 bytes");
+    error.status = 413;
+    throw error;
+  }
   const title = String(payload.title || payload.label || "PRD Workflow Review").trim().slice(0, 160) || "PRD Workflow Review";
   const durability = String(payload.durability || (payload.durable === true || payload.permanent === true ? "durable" : "temporary")).trim().toLowerCase() || "temporary";
+  if (!["temporary", "durable"].includes(durability)) {
+    const error = new Error("durability must be temporary or durable");
+    error.status = 400;
+    throw error;
+  }
   const reviewId = prdWorkflowReviewIdFromRequest(tapdId, payload, durability);
   const paths = prdWorkflowReviewPaths(scopedRoot, tapdId, reviewId);
   const ttlDaysRaw = Number(payload.ttlDays || payload.ttl_days || (durability === "temporary" ? 7 : 0));
@@ -9924,11 +10013,13 @@ function prdWorkflowReadClientStateWithFallback(root, scopedRoot, tapdId) {
 
 function prdWorkflowWriteClientObservation(scopedRoot, tapdId, meta, snapshot) {
   const state = prdWorkflowReadClientState(scopedRoot, tapdId);
-  const clientId = prdWorkflowSafeStateId(meta.clientId || "anonymous");
+  const reportSource = String(meta.reportSource || meta.source || "legacy").trim().toLowerCase() || "legacy";
+  const clientId = prdWorkflowSafeStateId(`${reportSource}:${meta.clientId || "anonymous"}`);
   const nextClients = {
     ...state.clients,
     [clientId]: {
       clientId: String(meta.clientId || clientId),
+      source: reportSource,
       userId: String(meta.userId || ""),
       observedAt: String(meta.observedAt || ""),
       reportedAt: String(meta.reportedAt || new Date().toISOString()),
@@ -10161,6 +10252,7 @@ function prdWorkflowSnapshotMetaFromReport(payload = {}, rawSnapshot = {}, req =
     reportedAt,
     observedAt: String(payload.observedAt || payload.observed_at || rawSnapshot.observedAt || rawSnapshot.observed_at || sources.observedAt || sources.checkedAt || headerObservedAt || reportedAt),
     clientId: String(payload.clientId || payload.client_id || sources.clientId || headerClientId || userCtx?.userId || "anonymous").slice(0, 160),
+    reportSource: String(payload.reportSource || payload.report_source || payload.source || "legacy").trim().toLowerCase().slice(0, 120) || "legacy",
     userId: String(userCtx?.userId || payload.userId || payload.user_id || "").slice(0, 160),
     baseRevision: String(payload.baseRevision || payload.base_revision || payload.expectedRevision || payload.expected_revision || rawSnapshot.baseRevision || sources.baseRevision || "").trim(),
     scope: String(payload.scope || rawSnapshot.scope || rawSnapshot.next?.scope || sources.scope || "client").trim().toLowerCase() || "client",
@@ -10171,6 +10263,89 @@ function prdWorkflowSnapshotMetaFromReport(payload = {}, rawSnapshot = {}, req =
   };
 }
 
+function prdWorkflowStoreClientObservation({
+  scopedRoot,
+  tapdId,
+  rawState,
+  payload = {},
+  req = null,
+  userCtx = {},
+  flowSource = "user",
+  flowId = "",
+}) {
+  const normalizedSnapshot = {
+    ...prdWorkflowSnapshotFromParsed(scopedRoot, tapdId, rawState, userCtx, { flowSource, flowId }),
+    clientReportedAt: new Date().toISOString(),
+    sources: {
+      ...(rawState.sources && typeof rawState.sources === "object" ? rawState.sources : {}),
+      executionMode: "workflow-report",
+    },
+  };
+  const reportMeta = prdWorkflowSnapshotMetaFromReport(payload, rawState, req, userCtx);
+  const reportSource = {
+    ...(normalizedSnapshot.sources && typeof normalizedSnapshot.sources === "object" ? normalizedSnapshot.sources : {}),
+    executionMode: "workflow-report",
+    truth: "observation",
+    authority: "client",
+    persistence: "runtime",
+    clientId: reportMeta.clientId,
+    clientUserId: reportMeta.userId,
+    clientReportedAt: reportMeta.reportedAt,
+    clientObservedAt: reportMeta.observedAt,
+    baseRevision: reportMeta.baseRevision,
+    scope: reportMeta.scope,
+    platform: reportMeta.platform,
+    issueKey: reportMeta.issueKey,
+    stageKey: reportMeta.stageKey,
+  };
+  const existingClientState = prdWorkflowReadClientState(scopedRoot, tapdId);
+  const existingClientId = prdWorkflowSafeStateId(`${reportMeta.reportSource || "legacy"}:${reportMeta.clientId || "anonymous"}`);
+  const previousClientSnapshot = existingClientState.clients?.[existingClientId]?.snapshot || null;
+  const stampedSnapshot = prdWorkflowStampCurrentActionEntryTimes(
+    scopedRoot,
+    tapdId,
+    normalizedSnapshot,
+    existingClientState,
+    reportMeta,
+  );
+  const storedObservationSnapshot = prdWorkflowStoredObservationSnapshot(stampedSnapshot, reportSource);
+  const actionChanges = prdWorkflowSnapshotActionChanges(previousClientSnapshot || {}, storedObservationSnapshot);
+  prdWorkflowWriteClientObservation(scopedRoot, tapdId, reportMeta, storedObservationSnapshot);
+  prdWorkflowAppendAudit(scopedRoot, tapdId, {
+    type: "workflow-report-observation-stored",
+    flowSource,
+    flowId,
+    clientId: reportMeta.clientId,
+    userId: reportMeta.userId,
+    observedAt: reportMeta.observedAt,
+    reportedAt: reportMeta.reportedAt,
+    phase: String(storedObservationSnapshot?.phase || ""),
+    pointer: String(storedObservationSnapshot?.pointer || ""),
+    revision: String(storedObservationSnapshot?.revision || ""),
+    actionCount: prdWorkflowSnapshotActionCount(storedObservationSnapshot),
+    truth: "observation",
+    authority: "client",
+    persistence: "runtime",
+    note: "producer observation accepted through the canonical Workflow Report endpoint",
+  });
+  for (const change of actionChanges) {
+    prdWorkflowAppendAudit(scopedRoot, tapdId, {
+      type: "snapshot-action-change",
+      source: "workflow-report",
+      clientId: reportMeta.clientId,
+      userId: reportMeta.userId,
+      observedAt: reportMeta.observedAt,
+      reportedAt: reportMeta.reportedAt,
+      revision: String(storedObservationSnapshot.revision || ""),
+      previousRevision: String(previousClientSnapshot?.revision || ""),
+      pointer: String(storedObservationSnapshot.pointer || ""),
+      previousPointer: String(previousClientSnapshot?.pointer || ""),
+      ...change,
+    });
+  }
+  return { reportMeta, storedObservationSnapshot, previousClientSnapshot };
+}
+
 function prdWorkflowSnapshotReportConflict(existingRecord, incomingSnapshot, meta) {
   if (!existingRecord?.snapshot || meta.force) return null;
   const current = existingRecord.snapshot;
@@ -10285,6 +10460,7 @@ function prdWorkflowMaterializeSnapshot(root, scopedRoot, tapdId, userCtx = {},
   );
   const clientObservations = prdWorkflowClientObservationRows(root, scopedRoot, tapdId).map((item) => ({
     clientId: item.clientId,
+    source: item.source || "legacy",
     userId: item.userId || "",
     phase: item.phase || "",
     pointer: item.pointer || "",
@@ -10477,13 +10653,22 @@ function prdWorkflowNormalizeStoredRuntimeEvent(tapdId, event = {}) {
 function prdWorkflowReadRuntimeEvents(scopedRoot, tapdId) {
   try {
     const p = prdWorkflowEventsPath(scopedRoot, tapdId);
-    if (!fs.existsSync(p)) return { version: 1, tapdId: String(tapdId || ""), events: [] };
-    const data = JSON.parse(fs.readFileSync(p, "utf-8"));
-    const events = Array.isArray(data?.events)
-      ? data.events
-          .map((item) => prdWorkflowNormalizeStoredRuntimeEvent(data?.tapdId || tapdId, item))
-          .filter((item) => item && typeof item === "object")
+    const archivePath = prdWorkflowEventsArchivePath(scopedRoot, tapdId);
+    const data = fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf-8")) : {};
+    const archivedEvents = fs.existsSync(archivePath)
+      ? fs.readFileSync(archivePath, "utf-8").split("\n").filter(Boolean).flatMap((line) => {
+          try { return [JSON.parse(line)]; } catch { return []; }
+        })
       : [];
+    const normalizedEvents = [...archivedEvents, ...(Array.isArray(data?.events) ? data.events : [])]
+      .map((item) => prdWorkflowNormalizeStoredRuntimeEvent(data?.tapdId || tapdId, item))
+      .filter((item) => item && typeof item === "object");
+    const eventsByKey = new Map();
+    for (const event of normalizedEvents) {
+      const key = `${prdWorkflowRuntimeEventProducer(event)}:${prdWorkflowRuntimeEventOperation(event)}:${String(event.id || "")}`;
+      eventsByKey.set(key, event);
+    }
+    const events = [...eventsByKey.values()];
     return {
       version: 1,
       tapdId: String(data?.tapdId || tapdId || ""),
@@ -10498,11 +10683,17 @@ function prdWorkflowReadRuntimeEvents(scopedRoot, tapdId) {
 function prdWorkflowWriteRuntimeEvents(scopedRoot, tapdId, events) {
   const p = prdWorkflowEventsPath(scopedRoot, tapdId);
   fs.mkdirSync(path.dirname(p), { recursive: true });
+  const allEvents = Array.isArray(events) ? events : [];
+  const overflow = allEvents.slice(0, Math.max(0, allEvents.length - PRD_WORKFLOW_RUNTIME_EVENTS_MAX));
+  const archivePath = prdWorkflowEventsArchivePath(scopedRoot, tapdId);
+  const archiveTmp = `${archivePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(archiveTmp, overflow.length ? `${overflow.map((event) => JSON.stringify(event)).join("\n")}\n` : "", "utf-8");
+  fs.renameSync(archiveTmp, archivePath);
   const data = {
     version: 1,
     tapdId: String(tapdId || ""),
     updatedAt: new Date().toISOString(),
-    events: Array.isArray(events) ? events.slice(-PRD_WORKFLOW_RUNTIME_EVENTS_MAX) : [],
+    events: allEvents.slice(-PRD_WORKFLOW_RUNTIME_EVENTS_MAX),
   };
   const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
@@ -10565,6 +10756,19 @@ function prdWorkflowRuntimeEventCanonicalAction(stage = "") {
     : "";
 }
 
+function prdWorkflowRuntimeEventProducer(event = {}) {
+  return String(event.source || event.producer || "agentflow")
+    .trim()
+    .toLowerCase()
+    .slice(0, 120) || "agentflow";
+}
+
+function prdWorkflowRuntimeEventOperation(event = {}) {
+  return String(event.operation || (event.type === "review-link" ? "artifact.publish" : "report"))
+    .trim()
+    .toLowerCase() || "report";
+}
+
 function prdWorkflowRuntimeOwnedArtifacts(values, stage = "") {
   if (!Array.isArray(values)) return values;
   const ownsOnlyChangedArtifact = /^(?:issue-plan|implementation|bugfix|integration):/.test(String(stage || ""));
@@ -10586,16 +10790,21 @@ function prdWorkflowRuntimeEventId(event = {}) {
   const scope = String(event.scope || "").trim();
   const platform = String(event.platform || "").trim();
   const aggregateByStage = event.aggregateByStage !== false && event.aggregate_by_stage !== false;
+  const operation = prdWorkflowRuntimeEventOperation(event);
+  const stableActionKey = String(event?.actionModel?.key || "").trim();
+  if (stableActionKey && aggregateByStage && String(event?.type || "") === "workflow-report") {
+    return `stage_${prdWorkflowSafeStateId([prdWorkflowRuntimeEventProducer(event), operation, stableActionKey].join(":"))}`;
+  }
   if ((stage || action) && aggregateByStage) {
     const issue = String(event.issueKey || event.issue_key || event.issue || "").trim();
-    const key = [scope, issue, platform, stage || action].filter(Boolean).join(":");
+    const key = [prdWorkflowRuntimeEventProducer(event), operation, scope, issue, platform, stage || action].filter(Boolean).join(":");
     return `stage_${prdWorkflowSafeStateId(key)}`;
   }
   const existing = String(event.id || event.eventId || event.event_id || "").trim();
   if (existing) return existing.slice(0, 160);
   if (stage || action) {
     const issue = String(event.issueKey || event.issue_key || event.issue || "").trim();
-    const key = [scope, issue, platform, stage || action].filter(Boolean).join(":");
+    const key = [prdWorkflowRuntimeEventProducer(event), operation, scope, issue, platform, stage || action].filter(Boolean).join(":");
     return `stage_${prdWorkflowSafeStateId(key)}`;
   }
   return `evt_${Date.now().toString(36)}_${crypto.randomBytes(4).toString("hex")}`;
@@ -10659,8 +10868,13 @@ function prdWorkflowNormalizeRuntimeEvent(tapdId, event = {}) {
     entry.stage = stage;
     entry.stageKey = stage;
   }
-  entry.artifacts = prdWorkflowRuntimeOwnedArtifacts(entry.artifacts, stage);
-  entry.links = prdWorkflowRuntimeOwnedArtifacts(entry.links, stage);
+  const attachProducer = (values) => (Array.isArray(values) ? values.map((item) => (
+    item && typeof item === "object" && !Array.isArray(item)
+      ? { ...item, producer: String(item.producer || source).trim().toLowerCase() || source }
+      : item
+  )) : values);
+  entry.artifacts = attachProducer(prdWorkflowRuntimeOwnedArtifacts(entry.artifacts, stage));
+  entry.links = attachProducer(prdWorkflowRuntimeOwnedArtifacts(entry.links, stage));
   if (scope) entry.scope = scope;
   if (platform) entry.platform = platform;
   if (!entry.createdAt) entry.createdAt = event.startedAt || now;
@@ -10759,8 +10973,14 @@ function prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, event = {}) {
     const current = prdWorkflowReadRuntimeEvents(scopedRoot, tapdId);
     const entry = prdWorkflowNormalizeRuntimeEvent(tapdId, event);
     const entryIdem = String(entry.idempotencyKey || "").trim();
+    const entryProducer = prdWorkflowRuntimeEventProducer(entry);
+    const entryOperation = prdWorkflowRuntimeEventOperation(entry);
+    const entryDedupeKey = prdWorkflowRuntimeEventDedupeKey(entry);
     const index = current.events.findIndex((item) => {
+      if (prdWorkflowRuntimeEventProducer(item) !== entryProducer) return false;
       if (String(item?.id || "") === entry.id) return true;
+      if (prdWorkflowRuntimeEventOperation(item) !== entryOperation) return false;
+      if (prdWorkflowRuntimeEventDedupeKey(item) === entryDedupeKey) return true;
       if (!entryIdem) return false;
       if (String(item?.idempotencyKey || "").trim() === entryIdem) return true;
       return Array.isArray(item?.idempotencyHistory) && item.idempotencyHistory.includes(entryIdem);
@@ -10795,17 +11015,43 @@ function prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, event = {}) {
               incomingGlobalStatePatch,
             )
           : previousGlobalStatePatch;
+      const incomingPatchPaths = Array.isArray(entry?.globalStateOwnerPaths) ? entry.globalStateOwnerPaths : [];
+      const previousRemovePaths = Array.isArray(events[index]?.globalStateRemove || events[index]?.global_state_remove)
+        ? (events[index].globalStateRemove || events[index].global_state_remove)
+        : [];
+      const incomingRemovePaths = Array.isArray(entry?.globalStateRemove || entry?.global_state_remove)
+        ? (entry.globalStateRemove || entry.global_state_remove)
+        : [];
+      const overlapsPath = (left, right) => left === right || left.startsWith(`${right}.`) || right.startsWith(`${left}.`);
+      const mergedGlobalStateRemove = [...new Set([
+        ...previousRemovePaths.filter((removedPath) => !incomingPatchPaths.some((patchPath) => overlapsPath(String(removedPath), String(patchPath)))),
+        ...incomingRemovePaths,
+      ])];
+      let normalizedGlobalStatePatch = mergedGlobalStatePatch;
+      for (const removedPath of incomingRemovePaths) {
+        normalizedGlobalStatePatch = removeWorkflowGlobalStatePath(normalizedGlobalStatePatch, removedPath);
+      }
       const prevArtifact = prdWorkflowRuntimeEventArtifactSignature(events[index]);
       const nextArtifact = prdWorkflowRuntimeEventArtifactSignature(entry);
       artifactConflict = Boolean(prevArtifact && nextArtifact && prevArtifact !== nextArtifact &&
         prdWorkflowRuntimeEventShouldConflictOnArtifact(events[index]) &&
         prdWorkflowRuntimeEventShouldConflictOnArtifact(entry));
-      const idempotencyHistory = [
-        ...(events[index].idempotencyKey ? [events[index].idempotencyKey] : []),
-        ...(entry.idempotencyKey ? [entry.idempotencyKey] : []),
+      const idempotencyHistory = [...new Set([
         ...(Array.isArray(events[index].idempotencyHistory) ? events[index].idempotencyHistory : []),
+        ...(events[index].idempotencyKey ? [events[index].idempotencyKey] : []),
         ...(Array.isArray(entry.idempotencyHistory) ? entry.idempotencyHistory : []),
-      ];
+        ...(entry.idempotencyKey ? [entry.idempotencyKey] : []),
+      ])].slice(-50);
+      const allIdempotencyFingerprints = {
+        ...(events[index].idempotencyFingerprints || {}),
+        ...(events[index].idempotencyKey && events[index].idempotencyFingerprint
+          ? { [events[index].idempotencyKey]: events[index].idempotencyFingerprint }
+          : {}),
+        ...(entry.idempotencyFingerprints || {}),
+        ...(entry.idempotencyKey && entry.idempotencyFingerprint
+          ? { [entry.idempotencyKey]: entry.idempotencyFingerprint }
+          : {}),
+      };
       events[index] = {
         ...events[index],
         ...entry,
@@ -10814,19 +11060,28 @@ function prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, event = {}) {
         outputs: prdWorkflowMergeRuntimeEventArrays(events[index].outputs, entry.outputs),
         results: prdWorkflowMergeRuntimeEventArrays(events[index].results, entry.results),
         actionModel: mergeWorkflowGlobalState(events[index].actionModel, entry.actionModel),
-        globalStateRemove: prdWorkflowMergeRuntimeEventArrays(
-          events[index].globalStateRemove || events[index].global_state_remove,
-          entry.globalStateRemove || entry.global_state_remove,
+        globalStateRemove: mergedGlobalStateRemove,
+        extensionsPatch: entry.extensionsPatch
+          ? mergeWorkflowGlobalState(events[index].extensionsPatch, entry.extensionsPatch)
+          : events[index].extensionsPatch,
+        globalStateOwnerPaths: prdWorkflowMergeRuntimeEventArrays(
+          events[index].globalStateOwnerPaths,
+          entry.globalStateOwnerPaths,
         ),
         createdAt: events[index].createdAt || entry.createdAt,
         startedAt: events[index].startedAt || entry.startedAt,
-        idempotencyHistory: [...new Set(idempotencyHistory)].slice(-50),
+        idempotencyHistory,
+        idempotencyFingerprints: Object.fromEntries(
+          idempotencyHistory
+            .filter((key) => allIdempotencyFingerprints[key])
+            .map((key) => [key, allIdempotencyFingerprints[key]]),
+        ),
       };
       if (mergedImplementationMetadata && typeof mergedImplementationMetadata === "object" && !Array.isArray(mergedImplementationMetadata)) {
         events[index].implementationMetadata = mergedImplementationMetadata;
       }
-      if (mergedGlobalStatePatch && typeof mergedGlobalStatePatch === "object" && !Array.isArray(mergedGlobalStatePatch)) {
-        events[index].globalStatePatch = mergedGlobalStatePatch;
+      if (normalizedGlobalStatePatch && typeof normalizedGlobalStatePatch === "object" && !Array.isArray(normalizedGlobalStatePatch)) {
+        events[index].globalStatePatch = normalizedGlobalStatePatch;
       }
       if (artifactConflict) {
         events[index] = {
@@ -10871,36 +11126,128 @@ function prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, event = {}) {
   }
 }
 
-function prdWorkflowFindCompletedIdempotencyEvent(scopedRoot, tapdId, idempotencyKey) {
+function prdWorkflowFindIdempotencyEvent(scopedRoot, tapdId, idempotencyKey, source = "", completedOnly = true, operation = "") {
   const key = String(idempotencyKey || "").trim();
   if (!key) return null;
+  const producer = String(source || "").trim().toLowerCase();
+  const operationKey = String(operation || "").trim().toLowerCase();
   const events = prdWorkflowReadRuntimeEvents(scopedRoot, tapdId).events;
   return [...events].reverse().find((event) => (
+    (!producer || prdWorkflowRuntimeEventProducer(event) === producer) &&
+    (!operationKey || String(event?.operation || (event?.type === "review-link" ? "artifact.publish" : "report")).toLowerCase() === operationKey) &&
     (String(event?.idempotencyKey || "") === key || (Array.isArray(event?.idempotencyHistory) && event.idempotencyHistory.includes(key))) &&
-    ["done", "success", "completed"].includes(String(event?.status || "").toLowerCase())
+    (!completedOnly || ["done", "success", "completed"].includes(String(event?.status || "").toLowerCase()))
   )) || null;
 }
 
+function prdWorkflowFindCompletedIdempotencyEvent(scopedRoot, tapdId, idempotencyKey, source = "") {
+  return prdWorkflowFindIdempotencyEvent(scopedRoot, tapdId, idempotencyKey, source, false, "report");
+}
+
+function prdWorkflowIdempotencyFingerprint(event = {}, idempotencyKey = "") {
+  const key = String(idempotencyKey || "").trim();
+  return String(
+    event?.idempotencyFingerprints?.[key]
+    || (String(event?.idempotencyKey || "").trim() === key ? event?.idempotencyFingerprint : "")
+    || "",
+  );
+}
+
+function prdWorkflowResourceVersionConflicts(expectedVersions = {}, currentVersions = {}) {
+  const conflicts = [];
+  for (const [resourceKey, expectedVersion] of Object.entries(expectedVersions || {})) {
+    const currentVersion = String(currentVersions?.[resourceKey] || "absent");
+    const expected = String(expectedVersion || "absent");
+    if (expected === currentVersion) continue;
+    conflicts.push({ resourceKey, expectedVersion: expected, currentVersion });
+  }
+  return conflicts;
+}
+
+function prdWorkflowGlobalPathOwners(snapshot = {}) {
+  const owners = new Map();
+  for (const event of Array.isArray(snapshot.runtimeEvents) ? snapshot.runtimeEvents : []) {
+    const source = prdWorkflowRuntimeEventProducer(event);
+    for (const path of Array.isArray(event?.globalStateOwnerPaths) ? event.globalStateOwnerPaths : []) {
+      const normalized = String(path || "").trim();
+      if (normalized) owners.set(normalized, source);
+    }
+  }
+  return owners;
+}
+
+function prdWorkflowGlobalOwnershipConflicts(report, currentSnapshot = {}) {
+  const source = prdWorkflowRuntimeEventProducer(report?.event || {});
+  const owners = prdWorkflowGlobalPathOwners(currentSnapshot);
+  const conflicts = [];
+  for (const path of Array.isArray(report?.event?.globalStateOwnerPaths) ? report.event.globalStateOwnerPaths : []) {
+    const normalizedPath = String(path || "");
+    const match = [...owners.entries()].find(([ownedPath, owner]) => (
+      owner !== source && (
+        ownedPath === normalizedPath ||
+        ownedPath.startsWith(`${normalizedPath}.`) ||
+        normalizedPath.startsWith(`${ownedPath}.`)
+      )
+    ));
+    if (match) conflicts.push({ path: normalizedPath, owner: match[1], source });
+  }
+  return conflicts;
+}
+
+function prdWorkflowMergeProducerTimeline(report, currentSnapshot = {}) {
+  if (!report?.projections || !Array.isArray(report.projections.timeline)) return report;
+  const source = prdWorkflowRuntimeEventProducer(report.event);
+  const current = Array.isArray(currentSnapshot?.projections?.timeline) ? currentSnapshot.projections.timeline : [];
+  const incoming = report.projections.timeline;
+  const foreignCurrent = current.filter((item) => prdWorkflowRuntimeEventProducer(item) !== source);
+  const ownIncoming = incoming.filter((item) => prdWorkflowRuntimeEventProducer(item) === source);
+  const foreignIncoming = incoming.filter((item) => prdWorkflowRuntimeEventProducer(item) !== source);
+  const foreignByKey = new Map(foreignCurrent.map((item) => [String(item?.key || `${item?.source}:${item?.kind}:${item?.id}`), item]));
+  for (const item of foreignIncoming) {
+    const key = String(item?.key || `${item?.source}:${item?.kind}:${item?.id}`);
+    const existing = foreignByKey.get(key);
+    const existingVersion = existing
+      ? Object.values(workflowSnapshotResourceVersions({ projections: { timeline: [existing] } }))[0]
+      : "";
+    const incomingVersion = Object.values(workflowSnapshotResourceVersions({ projections: { timeline: [item] } }))[0] || "";
+    if (!existing || existingVersion !== incomingVersion) {
+      return { error: `projections.timeline may not modify entries owned by source ${item?.source || "unknown"}` };
+    }
+  }
+  const timeline = [...foreignCurrent, ...ownIncoming];
+  return {
+    ...report,
+    projections: { ...report.projections, timeline },
+    event: { ...report.event, projections: { ...report.event.projections, timeline } },
+  };
+}
+
 function prdWorkflowRuntimeEventDedupeKey(event = {}, index = 0) {
+  const producer = prdWorkflowRuntimeEventProducer(event);
+  const operation = prdWorkflowRuntimeEventOperation(event);
   const stage = prdWorkflowRuntimeEventCanonicalStage(event);
   const aggregateByStage = event.aggregateByStage !== false && event.aggregate_by_stage !== false;
+  const stableActionKey = String(event?.actionModel?.key || "").trim();
+  if (stableActionKey && aggregateByStage && String(event?.type || "") === "workflow-report") {
+    return `producer:${producer}:operation:${operation}:action:${stableActionKey}`;
+  }
   if (stage) {
     const issue = event?.issueKey || event?.issue_key || event?.issue;
     const platform = event?.platform;
     if (aggregateByStage || issue || platform) {
-      return ["stage", event?.scope, issue, platform, stage]
+      return ["producer", producer, "operation", operation, "stage", event?.scope, issue, platform, stage]
         .map((value) => String(value || "").trim())
         .join(":");
     }
   }
   const id = String(event?.id || event?.eventId || event?.event_id || "").trim();
-  if (id) return `id:${id}`;
+  if (id) return `producer:${producer}:operation:${operation}:id:${id}`;
   if (stage) {
-    return ["stage", event?.scope, event?.issueKey || event?.issue_key || event?.issue, event?.platform, stage]
+    return ["producer", producer, "operation", operation, "stage", event?.scope, event?.issueKey || event?.issue_key || event?.issue, event?.platform, stage]
       .map((value) => String(value || "").trim())
       .join(":");
   }
-  return `idx:${index}`;
+  return `producer:${producer}:operation:${operation}:idx:${index}`;
 }
 
 function prdWorkflowMergeRuntimeEventList(snapshotEvents = [], runtimeEvents = []) {
@@ -11169,14 +11516,24 @@ function prdWorkflowMergeRuntimeEvents(scopedRoot, tapdId, snapshot) {
   const globalState = prdWorkflowGlobalStateFromEvents(tapdId, snapshot, runtimeEvents);
   const artifacts = mergeWorkflowArtifacts(snapshot?.artifacts, runtimeEvents);
   const projections = materializeWorkflowProjections(snapshot, runtimeEvents);
-  return {
+  const extensions = materializeWorkflowExtensions(snapshot, runtimeEvents);
+  const prdFlowExtension = extensions["prd-flow"] && typeof extensions["prd-flow"] === "object"
+    ? extensions["prd-flow"]
+    : {};
+  const prdFlowExtensionView = {};
+  for (const key of ["issues", "issueGroups", "issue_groups", "epics", "epicGroups", "epic_groups", "aiDocs", "ai_docs"]) {
+    if (Object.prototype.hasOwnProperty.call(prdFlowExtension, key)) prdFlowExtensionView[key] = prdFlowExtension[key];
+  }
+  const materialized = {
     ...snapshot,
+    ...prdFlowExtensionView,
     workflow: globalState.workflow,
     overall,
     globalState,
     artifacts,
     projections,
-    runtimeRevision: workflowRuntimeRevision(globalState, artifacts, runtimeEvents, projections),
+    extensions,
+    runtimeRevision: workflowRuntimeRevision(globalState, artifacts, runtimeEvents, projections, extensions),
     runtimeEvents,
     events,
     sources: {
@@ -11184,6 +11541,8 @@ function prdWorkflowMergeRuntimeEvents(scopedRoot, tapdId, snapshot) {
       runtimeEventsUpdatedAt: runtime.updatedAt || "",
     },
   };
+  materialized.resourceVersions = workflowSnapshotResourceVersions(materialized);
+  return materialized;
 }
 
 function prdWorkflowMockSnapshot(scopedRoot, tapdId = "mock-prd") {
@@ -12587,6 +12946,95 @@ export function startUiServer({
       json(res, 200, { token: getSessionTokenFromRequest(req) || "" });
       return;
     }
+    if (req.method === "POST" && url.pathname === "/api/workflows/access/sync") {
+      if (!authUser?.userId) {
+        json(res, 401, { error: "Authentication required" });
+        return;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(await readBody(req, 256 * 1024));
+      } catch (error) {
+        json(res, error?.status === 413 ? 413 : 400, { error: error?.status === 413 ? error.message : "Invalid JSON body" });
+        return;
+      }
+      try {
+        const workflow = normalizeWorkflowReference(payload);
+        if (workflow.error) {
+          json(res, 400, { error: workflow.error });
+          return;
+        }
+        if (workflow.namespace !== "tapd") {
+          json(res, 400, { error: `Unsupported Workflow authority namespace: ${workflow.namespace}` });
+          return;
+        }
+        const authorityPayload = payload?.authority && typeof payload.authority === "object" && !Array.isArray(payload.authority)
+          ? payload.authority
+          : {};
+        const authorityType = String(authorityPayload.type || payload.authorityType || "tapd").trim().toLowerCase();
+        const ownerIdentity = workflowAuthorityIdentity(authorityPayload.owner ?? payload.owner);
+        const participantIdentities = workflowAuthorityIdentities(authorityPayload.participants ?? payload.participants);
+        if (!ownerIdentity) {
+          json(res, 400, { error: "authority.owner is required" });
+          return;
+        }
+        const ownerUser = findWorkspaceShareUser(ownerIdentity);
+        if (!ownerUser) {
+          json(res, 422, {
+            error: "TAPD owner has not registered or logged in to AgentFlow",
+            owner: ownerIdentity,
+          });
+          return;
+        }
+        const resolvedParticipants = [];
+        const unresolvedParticipants = [];
+        for (const identity of participantIdentities) {
+          const user = findWorkspaceShareUser(identity);
+          if (user) resolvedParticipants.push(user);
+          else unresolvedParticipants.push(identity);
+        }
+        const result = syncPrdWorkflowAuthority({
+          tapdId: workflow.id,
+          userId: userCtx.userId,
+          isAdmin: userCtx.isAdmin === true,
+          authority: authorityType,
+          ownerUserId: ownerUser.userId,
+          ownerIdentity,
+          participantUserIds: resolvedParticipants.map((user) => user.userId),
+          participantIdentities,
+          unresolvedParticipants,
+          observedAt: authorityPayload.observedAt || authorityPayload.observed_at || payload.observedAt || payload.observed_at,
+          revision: authorityPayload.revision || payload.revision,
+        });
+        if (result.error) {
+          json(res, result.status || 400, { error: result.error });
+          return;
+        }
+        const collaboration = prdWorkflowCollaborationSummaryWithUsers(result.record, userCtx.userId);
+        prdWorkflowBroadcast(prdWorkflowKey(userCtx, "", "", workflow.id), {
+          type: "authority.synced",
+          tapdId: workflow.id,
+          ownerId: result.record.ownerId,
+        });
+        json(res, 200, {
+          ok: true,
+          workflow,
+          created: result.created === true,
+          ownerChanged: result.ownerChanged === true,
+          collaboration,
+          matchedParticipants: resolvedParticipants.map((user) => ({
+            userId: user.userId,
+            username: user.username,
+            role: "viewer",
+            source: "tapd",
+          })),
+          unresolvedParticipants,
+        });
+      } catch (error) {
+        json(res, 500, { error: (error && error.message) || String(error) });
+      }
+      return;
+    }
     if (req.method === "GET" && url.pathname === "/api/prd-workflows") {
       if (!authUser?.userId) {
         json(res, 401, { error: "Unauthorized" });
@@ -12610,7 +13058,7 @@ export function startUiServer({
           records = listPrdWorkflowCollaborationsForUser(userCtx.userId);
         }
         const workflows = records.map((record) => {
-          const stateRoot = path.resolve(getAgentflowUserDataRoot(record.ownerId));
+          const stateRoot = path.resolve(getAgentflowUserDataRoot(record.stateOwnerId || record.ownerId));
           const tapdId = String(record.tapdId || "").trim();
           const project = prdWorkflowReadProjectState(stateRoot, tapdId);
           const latestClient = prdWorkflowLatestClientSnapshot(stateRoot, stateRoot, tapdId);
@@ -12803,7 +13251,12 @@ export function startUiServer({
         json(res, 200, {
           ok: true,
           collaboration: prdWorkflowCollaborationSummaryWithUsers(record, userCtx.userId),
-          member: { userId: targetUser.userId, username: targetUser.username, role: "editor" },
+          member: {
+            userId: targetUser.userId,
+            username: targetUser.username,
+            role: payload?.role === "viewer" ? "viewer" : "reporter",
+            source: "explicit",
+          },
         });
       } catch (error) {
         json(res, 400, { error: (error && error.message) || String(error) });
@@ -12955,6 +13408,8 @@ export function startUiServer({
     }
 
     if (req.method === "POST" && url.pathname === "/api/prd-workflow/snapshot") {
+      res.setHeader("Deprecation", "true");
+      res.setHeader("Link", "</api/workflows/report>; rel=\"successor-version\"");
       if (!authUser?.userId) {
         json(res, 401, { error: "Authentication required" });
         return;
@@ -13030,7 +13485,7 @@ export function startUiServer({
           stageKey: reportMeta.stageKey,
         };
         const existingClientState = prdWorkflowReadClientState(scopedRoot, tapdId);
-        const existingClientId = prdWorkflowSafeStateId(reportMeta.clientId || "anonymous");
+        const existingClientId = prdWorkflowSafeStateId(`${reportMeta.reportSource || "legacy"}:${reportMeta.clientId || "anonymous"}`);
         const previousClientSnapshot = existingClientState.clients?.[existingClientId]?.snapshot || null;
         const stampedSnapshot = prdWorkflowStampCurrentActionEntryTimes(
           scopedRoot,
@@ -13188,6 +13643,10 @@ export function startUiServer({
         json(res, 200, {
           ok: true,
           snapshot: withDiagnostic,
+          compatibility: {
+            deprecatedEndpoint: "/api/prd-workflow/snapshot",
+            replacement: "/api/workflows/report with observation.state",
+          },
           ...(workflowShare ? { workflowShare, shareUrl: workflowShare.shortUrl || workflowShare.url } : {}),
         });
       } catch (e) {
@@ -13701,13 +14160,14 @@ export function startUiServer({
       }
       let payload;
       try {
-        payload = JSON.parse(await readBody(req));
-      } catch {
-        json(res, 400, { error: "Invalid JSON body" });
+        payload = JSON.parse(await readBody(req, 1024 * 1024));
+      } catch (error) {
+        json(res, error?.status === 413 ? 413 : 400, { error: error?.status === 413 ? error.message : "Invalid JSON body" });
         return;
       }
+      let releaseWorkflowWriteLock = null;
       try {
-        const report = normalizeWorkflowReport(payload);
+        let report = normalizeWorkflowReport(payload);
         if (report.error) {
           json(res, 400, { error: report.error });
           return;
@@ -13740,6 +14200,7 @@ export function startUiServer({
         }
         const scopedRoot = workflowScope.stateRoot;
         prdWorkflowMigrateLegacyState(workflowScope.executionRoot, scopedRoot, tapdId);
+        releaseWorkflowWriteLock = await prdWorkflowAcquireWriteLock(`${scopedRoot}\t${tapdId}`);
         const currentSnapshot = prdWorkflowMaterializeSnapshot(
           workflowScope.executionRoot,
           scopedRoot,
@@ -13747,26 +14208,28 @@ export function startUiServer({
           userCtx,
           { flowSource, flowId },
         );
-        const acceptedRevisions = new Set([
-          String(currentSnapshot.runtimeRevision || "").trim(),
-          String(currentSnapshot.revision || "").trim(),
-        ].filter(Boolean));
-        if (report.expectedRevision && acceptedRevisions.size && !acceptedRevisions.has(report.expectedRevision)) {
-          json(res, 409, {
-            error: "Workflow state changed; refresh before reporting",
-            conflict: {
-              type: "workflow-revision-conflict",
-              expectedRevision: report.expectedRevision,
-              currentRevision: currentSnapshot.runtimeRevision || currentSnapshot.revision || "",
-              workflow: report.workflow,
-            },
-            snapshot: currentSnapshot,
-          });
-          return;
-        }
+        const currentRuntimeRevision = String(currentSnapshot.runtimeRevision || "").trim();
         if (report.idempotencyKey) {
-          const existing = prdWorkflowFindCompletedIdempotencyEvent(scopedRoot, tapdId, report.idempotencyKey);
+          const existing = prdWorkflowFindCompletedIdempotencyEvent(
+            scopedRoot,
+            tapdId,
+            report.idempotencyKey,
+            report.event.source,
+          );
           if (existing) {
+            const existingFingerprint = prdWorkflowIdempotencyFingerprint(existing, report.idempotencyKey);
+            if (existingFingerprint && existingFingerprint !== report.event.idempotencyFingerprint) {
+              json(res, 409, {
+                error: "Idempotency key was already used for a different Workflow report",
+                conflict: {
+                  type: "workflow-idempotency-conflict",
+                  idempotencyKey: report.idempotencyKey,
+                  workflow: report.workflow,
+                },
+                snapshot: currentSnapshot,
+              });
+              return;
+            }
             json(res, 200, {
               ok: true,
               alreadyApplied: true,
@@ -13777,15 +14240,101 @@ export function startUiServer({
             return;
           }
         }
-        const event = prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, {
+        const ownershipConflicts = prdWorkflowGlobalOwnershipConflicts(report, currentSnapshot);
+        if (ownershipConflicts.length) {
+          json(res, 409, {
+            error: "Workflow globalState paths are owned by another report source",
+            conflict: {
+              type: "workflow-resource-ownership-conflict",
+              conflicts: ownershipConflicts,
+              workflow: report.workflow,
+            },
+            snapshot: currentSnapshot,
+          });
+          return;
+        }
+        const resourceKeys = workflowReportResourceKeys(report, currentSnapshot);
+        const missingExpectedVersionKeys = Object.keys(report.expectedVersions).length
+          ? resourceKeys.filter((key) => !Object.prototype.hasOwnProperty.call(report.expectedVersions, key))
+          : [];
+        if (missingExpectedVersionKeys.length) {
+          json(res, 400, {
+            error: "expectedVersions must include every resource key touched by this report",
+            missingExpectedVersionKeys,
+            resourceKeys,
+          });
+          return;
+        }
+        const expectedTouchedVersions = Object.fromEntries(
+          resourceKeys
+            .filter((key) => Object.prototype.hasOwnProperty.call(report.expectedVersions, key))
+            .map((key) => [key, report.expectedVersions[key]]),
+        );
+        const resourceConflicts = prdWorkflowResourceVersionConflicts(
+          expectedTouchedVersions,
+          currentSnapshot.resourceVersions || {},
+        );
+        if (resourceConflicts.length) {
+          json(res, 409, {
+            error: "Workflow resources changed; refresh the conflicting keys before reporting",
+            conflict: {
+              type: "workflow-resource-conflict",
+              conflicts: resourceConflicts,
+              workflow: report.workflow,
+            },
+            snapshot: currentSnapshot,
+          });
+          return;
+        }
+        if (!Object.keys(report.expectedVersions).length && report.expectedRevision && currentRuntimeRevision && report.expectedRevision !== currentRuntimeRevision) {
+          json(res, 409, {
+            error: "Workflow state changed; refresh before reporting",
+            conflict: {
+              type: "workflow-revision-conflict",
+              expectedRevision: report.expectedRevision,
+              currentRevision: currentRuntimeRevision,
+              workflow: report.workflow,
+            },
+            snapshot: currentSnapshot,
+          });
+          return;
+        }
+        report = prdWorkflowMergeProducerTimeline(report, currentSnapshot);
+        if (report.error) {
+          json(res, 400, { error: report.error });
+          return;
+        }
+        let observation = null;
+        if (report.observation) {
+          const observationPayload = {
+            ...payload,
+            tapdId,
+            clientId: report.observation.clientId || payload.clientId || payload.source || "workflow-reporter",
+            observedAt: report.observation.observedAt || payload.observedAt || "",
+            scope: report.observation.scope || payload.scope || "client",
+            reportSource: report.event.source,
+          };
+          observation = prdWorkflowStoreClientObservation({
+            scopedRoot,
+            tapdId,
+            rawState: report.observation.state,
+            payload: observationPayload,
+            req,
+            userCtx,
+            flowSource,
+            flowId,
+          });
+        }
+        const shouldStoreEvent = report.hasRuntimeUpdate || Boolean(report.idempotencyKey);
+        const event = shouldStoreEvent ? prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, {
           ...report.event,
           tapdId,
           actor: {
             userId: String(userCtx.userId || ""),
             username: String(authUser.username || userCtx.userId || ""),
           },
-        });
-        if (!event) throw new Error("Failed to store workflow report");
+        }) : null;
+        if (shouldStoreEvent && !event) throw new Error("Failed to store workflow report");
         const snapshot = prdWorkflowWithAgentflowTokenDiagnostic(
           prdWorkflowMaterializeSnapshot(
             workflowScope.executionRoot,
@@ -13798,16 +14347,32 @@ export function startUiServer({
         );
         prdWorkflowBroadcast(
           prdWorkflowKey(userCtx, flowSource, flowId, tapdId),
-          { type: "workflow-report", tapdId, workflow: report.workflow, event, snapshot },
+          { type: "workflow-report", tapdId, workflow: report.workflow, event, observation: Boolean(observation), snapshot },
         );
-        json(res, 200, { ok: true, report, event, snapshot });
+        json(res, 200, {
+          ok: true,
+          report,
+          resourceKeys,
+          event,
+          observation: observation ? {
+            accepted: true,
+            clientId: observation.reportMeta.clientId,
+            observedAt: observation.reportMeta.observedAt,
+            schema: report.observation.schema,
+          } : null,
+          snapshot,
+        });
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });
+      } finally {
+        releaseWorkflowWriteLock?.();
       }
       return;
     }
 
     if (req.method === "POST" && url.pathname === "/api/prd-workflow/event") {
+      res.setHeader("Deprecation", "true");
+      res.setHeader("Link", "</api/workflows/report>; rel=\"successor-version\"");
       if (!authUser?.userId) {
         json(res, 401, { error: "Authentication required" });
         return;
@@ -13858,31 +14423,49 @@ export function startUiServer({
           getSessionTokenFromRequest(req) || "",
         );
         prdWorkflowBroadcast(prdWorkflowKey(userCtx, flowSource, flowId, tapdId), { type: "runtime-event", tapdId, event, snapshot });
-        json(res, 200, { ok: true, event, snapshot });
+        json(res, 200, {
+          ok: true,
+          event,
+          snapshot,
+          compatibility: {
+            deprecatedEndpoint: "/api/prd-workflow/event",
+            replacement: "/api/workflows/report with action/artifacts/extensions",
+          },
+        });
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });
       }
       return;
     }
 
-    if (req.method === "POST" && url.pathname === "/api/prd-workflow/review-link") {
+    if (req.method === "POST" && (
+      url.pathname === "/api/workflow-artifacts/publish" ||
+      url.pathname === "/api/prd-workflow/review-link"
+    )) {
+      const legacyReviewEndpoint = url.pathname === "/api/prd-workflow/review-link";
       if (!authUser?.userId) {
         json(res, 401, { error: "Authentication required" });
         return;
       }
       let payload;
       try {
-        payload = JSON.parse(await readBody(req));
-      } catch {
-        json(res, 400, { error: "Invalid JSON body" });
+        payload = JSON.parse(await readBody(req, 600000));
+      } catch (error) {
+        json(res, error?.status === 413 ? 413 : 400, { error: error?.status === 413 ? error.message : "Invalid JSON body" });
         return;
       }
+      let releaseWorkflowWriteLock = null;
       try {
-        const tapdId = String(payload.tapdId || payload.tapd_id || "").trim();
-        if (!tapdId) {
-          json(res, 400, { error: "Missing tapdId" });
+        const workflow = normalizeWorkflowReference(payload);
+        if (workflow.error) {
+          json(res, 400, { error: workflow.error });
+          return;
+        }
+        if (workflow.namespace !== "tapd") {
+          json(res, 400, { error: `Unsupported workflow namespace: ${workflow.namespace}` });
           return;
         }
+        const tapdId = workflow.id;
         const flowId = String(payload.flowId || "").trim();
         const flowSource = String(payload.flowSource || "user").trim() || "user";
         const archived = payload.archived === true || payload.flowArchived === true;
@@ -13899,6 +14482,194 @@ export function startUiServer({
         }
         const scopedRoot = workflowScope.stateRoot;
         prdWorkflowMigrateLegacyState(workflowScope.executionRoot, scopedRoot, tapdId);
+        const producer = String(payload.source || (legacyReviewEndpoint ? "prd-flow" : "")).trim().toLowerCase();
+        if (!producer) {
+          json(res, 400, { error: "Workflow artifact publish requires source" });
+          return;
+        }
+        if (!/^[a-z][a-z0-9._-]{0,119}$/.test(producer)) {
+          json(res, 400, { error: "Invalid workflow report source" });
+          return;
+        }
+        const fieldLimits = [
+          [payload.title || payload.label, 160, "title"],
+          [payload.stage || payload.stageKey || payload.stage_key, 240, "stage"],
+          [payload.issueKey || payload.issue_key || payload.issue, 240, "issueKey"],
+          [payload.platform, 80, "platform"],
+          [payload.artifactLabel, 500, "artifactLabel"],
+          [payload.reviewId || payload.review_id, 500, "reviewId"],
+        ];
+        const oversizedField = fieldLimits.find(([value, max]) => String(value || "").trim().length > max);
+        if (oversizedField) {
+          json(res, 400, { error: `${oversizedField[2]} exceeds ${oversizedField[1]} characters` });
+          return;
+        }
+        const markdown = String(payload.markdown || payload.content || payload.rawOutput || "");
+        if (!markdown.trim()) {
+          json(res, 400, { error: "Missing review markdown" });
+          return;
+        }
+        if (Buffer.byteLength(markdown, "utf-8") > 500000) {
+          json(res, 413, { error: "Review markdown exceeds 500000 bytes" });
+          return;
+        }
+        const requestedDurability = String(
+          payload.durability || (payload.durable === true || payload.permanent === true ? "durable" : "temporary"),
+        ).trim().toLowerCase() || "temporary";
+        if (!["temporary", "durable"].includes(requestedDurability)) {
+          json(res, 400, { error: "durability must be temporary or durable" });
+          return;
+        }
+        const ttlInput = payload.ttlDays ?? payload.ttl_days;
+        if (requestedDurability === "temporary" && ttlInput != null) {
+          const ttlDays = Number(ttlInput);
+          if (!Number.isInteger(ttlDays) || ttlDays < 1 || ttlDays > 30) {
+            json(res, 400, { error: "ttlDays must be an integer between 1 and 30" });
+            return;
+          }
+        }
+        const explicitExpiresAt = String(payload.expiresAt || payload.expires_at || "").trim();
+        if (explicitExpiresAt && (!Number.isFinite(Date.parse(explicitExpiresAt)) || Date.parse(explicitExpiresAt) <= Date.now())) {
+          json(res, 400, { error: "expiresAt must be a valid future date" });
+          return;
+        }
+        const idempotencyKey = String(
+          payload.idempotencyKey || payload.idempotency_key || "",
+        ).trim();
+        if (idempotencyKey.length > 500) {
+          json(res, 400, { error: "idempotencyKey exceeds 500 characters" });
+          return;
+        }
+        if (String(payload.artifactKey || payload.artifact_key || "").trim().length > 500) {
+          json(res, 400, { error: "artifactKey exceeds 500 characters" });
+          return;
+        }
+        const artifactKey = prdWorkflowReviewArtifactKey(tapdId, payload);
+        const idempotencyFingerprint = prdWorkflowRevisionHash({
+          operation: "artifact.publish",
+          workflow,
+          producer,
+          title: String(payload.title || payload.label || "").trim(),
+          markdown,
+          stage: String(payload.stage || payload.stageKey || payload.stage_key || "").trim(),
+          issueKey: String(payload.issueKey || payload.issue_key || payload.issue || "").trim(),
+          platform: String(payload.platform || "").trim(),
+          artifactKey,
+          artifactLabel: String(payload.artifactLabel || "").trim(),
+          durability: requestedDurability,
+          ttlDays: ttlInput ?? null,
+          expiresAt: explicitExpiresAt,
+        });
+        releaseWorkflowWriteLock = await prdWorkflowAcquireWriteLock(`${scopedRoot}\t${tapdId}`);
+        const currentSnapshot = prdWorkflowMaterializeSnapshot(
+          workflowScope.executionRoot,
+          scopedRoot,
+          tapdId,
+          userCtx,
+          { flowSource, flowId },
+        );
+        const expectedRevision = String(payload.expectedRevision || payload.expected_revision || "").trim();
+        if (expectedRevision.length > 500) {
+          json(res, 400, { error: "expectedRevision exceeds 500 characters" });
+          return;
+        }
+        const currentRuntimeRevision = String(currentSnapshot.runtimeRevision || "").trim();
+        if (idempotencyKey) {
+          const existing = prdWorkflowFindIdempotencyEvent(
+            scopedRoot,
+            tapdId,
+            idempotencyKey,
+            producer,
+            false,
+            "artifact.publish",
+          );
+          if (existing) {
+            const existingFingerprint = prdWorkflowIdempotencyFingerprint(existing, idempotencyKey);
+            if (existingFingerprint && existingFingerprint !== idempotencyFingerprint) {
+              json(res, 409, {
+                error: "Idempotency key was already used for different Artifact content",
+                conflict: { type: "workflow-idempotency-conflict", idempotencyKey, workflow },
+                snapshot: currentSnapshot,
+              });
+              return;
+            }
+            const artifact = Array.isArray(existing.artifacts) ? existing.artifacts[0] : null;
+            json(res, 200, {
+              ok: true,
+              alreadyApplied: true,
+              workflow,
+              artifact,
+              review: artifact ? {
+                id: existing.reviewId || "",
+                url: artifact.canonicalUrl || artifact.url || "",
+                shortUrl: artifact.shortUrl || "",
+                shortCode: existing.reviewShortCode || "",
+                durability: existing.durability || artifact.durability || "",
+                expiresAt: existing.expiresAt || artifact.expiresAt || "",
+              } : null,
+              event: existing,
+              snapshot: currentSnapshot,
+            });
+            return;
+          }
+        }
+        const resourceKey = `artifact:${producer}:${artifactKey}`;
+        const hasExpectedVersionsField = Object.prototype.hasOwnProperty.call(payload, "expectedVersions")
+          || Object.prototype.hasOwnProperty.call(payload, "expected_versions");
+        const rawExpectedVersionsInput = Object.prototype.hasOwnProperty.call(payload, "expectedVersions")
+          ? payload.expectedVersions
+          : payload.expected_versions;
+        if (hasExpectedVersionsField && (!rawExpectedVersionsInput || typeof rawExpectedVersionsInput !== "object" || Array.isArray(rawExpectedVersionsInput))) {
+          json(res, 400, { error: "expectedVersions must be an object" });
+          return;
+        }
+        const rawExpectedVersions = hasExpectedVersionsField ? rawExpectedVersionsInput : {};
+        const invalidExpectedVersionEntry = Object.entries(rawExpectedVersions).find(([key, value]) => (
+          !String(key || "").trim() || String(key).length > 800 || /[\0\r\n]/.test(String(key)) ||
+          String(value == null || value === "" ? "absent" : value).trim().length > 160
+        ));
+        if (invalidExpectedVersionEntry) {
+          json(res, 400, { error: "expectedVersions contains an invalid resource key or version" });
+          return;
+        }
+        if (Object.keys(rawExpectedVersions).length && !Object.prototype.hasOwnProperty.call(rawExpectedVersions, resourceKey)) {
+          json(res, 400, {
+            error: "expectedVersions must include the Artifact resource key touched by this publish",
+            missingExpectedVersionKeys: [resourceKey],
+            resourceKeys: [resourceKey],
+          });
+          return;
+        }
+        const expectedArtifactVersion = Object.prototype.hasOwnProperty.call(rawExpectedVersions, resourceKey)
+          ? String(rawExpectedVersions[resourceKey] || "absent")
+          : null;
+        const resourceConflicts = expectedArtifactVersion == null
+          ? []
+          : prdWorkflowResourceVersionConflicts(
+              { [resourceKey]: expectedArtifactVersion },
+              currentSnapshot.resourceVersions || {},
+            );
+        if (resourceConflicts.length) {
+          json(res, 409, {
+            error: "Workflow artifact changed; refresh before publishing",
+            conflict: { type: "workflow-resource-conflict", conflicts: resourceConflicts, workflow },
+            snapshot: currentSnapshot,
+          });
+          return;
+        }
+        if (!Object.keys(rawExpectedVersions).length && expectedRevision && currentRuntimeRevision && expectedRevision !== currentRuntimeRevision) {
+          json(res, 409, {
+            error: "Workflow state changed; refresh before publishing",
+            conflict: {
+              type: "workflow-revision-conflict",
+              expectedRevision,
+              currentRevision: currentRuntimeRevision,
+              workflow,
+            },
+            snapshot: currentSnapshot,
+          });
+          return;
+        }
         const review = prdWorkflowCreateReview(
           scopedRoot,
           tapdId,
@@ -13920,7 +14691,6 @@ export function startUiServer({
         const shortUrl = shortLink?.shortUrl || "";
         const displayUrl = shortUrl || reviewUrl;
         const durability = review.durability || "temporary";
-        const artifactKey = prdWorkflowReviewArtifactKey(tapdId, payload);
         const reviewStageKey = prdWorkflowRuntimeEventCanonicalStage(payload)
           || payload.stageKey
           || payload.stage_key
@@ -13932,9 +14702,6 @@ export function startUiServer({
         const reviewSource = review.source && typeof review.source === "object" && !Array.isArray(review.source)
           ? review.source
           : { kind: durability === "durable" ? "ai-doc" : "local-draft", durability };
-        const idempotencyKey = String(
-          payload.idempotencyKey || payload.idempotency_key || "",
-        ).trim();
         const artifact = {
           key: artifactKey,
           label: payload.artifactLabel || "Markdown Review",
@@ -13950,6 +14717,7 @@ export function startUiServer({
           issueKey: payload.issueKey || payload.issue_key || "",
           platform: payload.platform || "",
           stageKey: reviewStageKey,
+          producer,
           ...(reviewMrUrl ? { mrUrl: reviewMrUrl } : {}),
           ...(reviewMrIid ? { mrIid: reviewMrIid } : {}),
           ...(reviewCommitSha ? { commitSha: reviewCommitSha } : {}),
@@ -13957,6 +14725,8 @@ export function startUiServer({
         const event = prdWorkflowAppendRuntimeEvent(scopedRoot, tapdId, {
           id: `review-link:${artifactKey}`,
           type: "review-link",
+          operation: "artifact.publish",
+          source: producer,
           auxiliary: true,
           aggregateByStage: false,
           conflictOnArtifact: false,
@@ -13974,6 +14744,8 @@ export function startUiServer({
           ...(reviewMrIid ? { mrIid: reviewMrIid } : {}),
           ...(reviewCommitSha ? { commitSha: reviewCommitSha } : {}),
           idempotencyKey,
+          idempotencyFingerprint,
+          idempotencyFingerprints: idempotencyKey ? { [idempotencyKey]: idempotencyFingerprint } : {},
           durability,
           sourceArtifact: reviewSource,
           expiresAt: review.expiresAt || "",
@@ -13988,6 +14760,7 @@ export function startUiServer({
             persistence: "runtime",
             durability,
             source: reviewSource,
+            producer,
             expiresAt: review.expiresAt || "",
             issueKey: artifact.issueKey,
             platform: artifact.platform,
@@ -14004,8 +14777,15 @@ export function startUiServer({
           getSessionTokenFromRequest(req) || "",
         );
         prdWorkflowBroadcast(prdWorkflowKey(userCtx, flowSource, flowId, tapdId), { type: "review-link", tapdId, event, snapshot });
+        if (legacyReviewEndpoint) {
+          res.setHeader("Deprecation", "true");
+          res.setHeader("Link", "</api/workflow-artifacts/publish>; rel=\"successor-version\"");
+        }
         json(res, 200, {
           ok: true,
+          workflow,
+          artifact,
+          resourceKeys: [resourceKey],
           review: {
             ...review,
             url: reviewUrl,
@@ -14014,9 +14794,18 @@ export function startUiServer({
           },
           event,
           snapshot,
+          ...(legacyReviewEndpoint ? {
+            compatibility: {
+              deprecatedEndpoint: "/api/prd-workflow/review-link",
+              replacement: "/api/workflow-artifacts/publish",
+            },
+          } : {}),
         });
       } catch (e) {
-        json(res, 500, { error: (e && e.message) || String(e) });
+        const status = Number(e?.status);
+        json(res, status >= 400 && status < 500 ? status : 500, { error: (e && e.message) || String(e) });
+      } finally {
+        releaseWorkflowWriteLock?.();
       }
       return;
     }