relic-mcp 0.7.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "relic",
       "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "source": "./",
       "author": {
         "name": "The Bushido Collective",
@@ -21,6 +21,6 @@
     }
   ],
   "metadata": {
-    "version": "0.7.0"
+    "version": "0.8.0"
   }
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "relic",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
   "mcpServers": "./mcp-servers.json",
   "author": {

package/dist/relic-mcp.js

@@ -4623,6 +4623,42 @@ async function resolveAnchors(relicId, comments2, deps) {
 }
 
 // src/comments.ts
+function previewCommentBody(body, maxChars = 80) {
+  if (body === null || body === undefined)
+    return "";
+  const trimmed = body.trim();
+  const firstLine = trimmed.split(`
+`)[0]?.trim() ?? "";
+  const text = firstLine.length > 0 ? firstLine : trimmed;
+  if (text.length <= maxChars)
+    return text;
+  return `${text.slice(0, maxChars - 3)}...`;
+}
+function formatUnaddressedRefusal(relicId, openComments, unreadableComments = []) {
+  const parts = [];
+  if (openComments.length > 0 && unreadableComments.length > 0) {
+    parts.push(`cannot republish relic ${relicId} while comments remain unaddressed. ` + `${openComments.length} comment(s) are unanswered, and ${unreadableComments.length} comment(s) could not be decrypted. ` + "Address unanswered comments either by replying with relic_comment or by passing addresses: [{ comment_id, note }] on republish.");
+  } else if (openComments.length > 0) {
+    parts.push(`cannot republish relic ${relicId} while comments remain unaddressed. ` + `${openComments.length} comment(s) are unanswered. ` + "Address each open comment either by replying with relic_comment or by passing addresses: [{ comment_id, note }] on republish.");
+  } else {
+    parts.push(`cannot republish relic ${relicId} because ${unreadableComments.length} comment(s) could not be decrypted. ` + "A comment this client cannot read cannot be verified as addressed.");
+  }
+  if (openComments.length > 0) {
+    const list = openComments.map((c) => `- [${c.comment_id}] from ${c.author} at ${c.created_at}: "${previewCommentBody(c.body)}"`).join(`
+`);
+    parts.push(`Open comments (${openComments.length}):
+${list}`);
+  }
+  if (unreadableComments.length > 0) {
+    const list = unreadableComments.map((c) => `- [${c.comment_id}] from ${c.author} at ${c.created_at}: unreadable (${c.unreadable_reason ?? "it did not decrypt under this relic's comment key"})`).join(`
+`);
+    parts.push(`Unreadable comments (${unreadableComments.length}):
+${list}`);
+  }
+  return parts.join(`
+
+`);
+}
 async function readComments(relicId, deps, options) {
   const state = await localState(relicId);
   const listed = await getJson(deps, `${deps.serviceOrigin}/api/relics/${relicId}/comments`);
@@ -4630,23 +4666,24 @@ async function readComments(relicId, deps, options) {
     throw new PublishError("app_response_unusable", "the comment list did not come back as a JSON array, so there is no " + "way to tell an empty conversation from an unreadable response", { relic_id: relicId, leg: "comments" });
   }
   const commentKey = await deriveCommentKey(decodeKey(state.key));
-  const comments2 = [];
-  let unreadable = 0;
+  const entries = [];
   for (const [index, entry] of listed.entries()) {
     const row = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? entry : {};
     const commentId = typeof row["comment_id"] === "string" ? row["comment_id"] : `unidentified-${index}`;
     const author = typeof row["author"] === "string" ? row["author"] : "unknown";
     const createdAt = typeof row["created_at"] === "string" ? row["created_at"] : "unknown";
     const ciphertext = row["ciphertext"];
+    const version = typeof row["version"] === "number" ? row["version"] : null;
     if (typeof ciphertext !== "string") {
-      unreadable += 1;
-      comments2.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
         display_name: null,
         body: null,
         anchor: null,
+        addresses: null,
+        version,
         readable: false,
         unreadable_reason: "the row carried no ciphertext"
       });
@@ -4654,36 +4691,79 @@ async function readComments(relicId, deps, options) {
     }
     try {
       const plaintext = await decryptComment(commentKey, ciphertext);
-      comments2.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
         display_name: plaintext.display_name,
         body: plaintext.body,
         anchor: plaintext.anchor ?? null,
+        addresses: plaintext.addresses ?? null,
+        version,
         readable: true,
         unreadable_reason: null
       });
     } catch (error) {
-      unreadable += 1;
-      comments2.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
         display_name: null,
         body: null,
         anchor: null,
+        addresses: null,
+        version,
         readable: false,
         unreadable_reason: `it did not decrypt under this relic's comment key: ${error.message}`
       });
     }
   }
+  const addressedByMap = new Map;
+  for (const entry of entries) {
+    if (entry.readable && entry.addresses !== null && entry.addresses !== entry.comment_id) {
+      if (!addressedByMap.has(entry.addresses)) {
+        addressedByMap.set(entry.addresses, {
+          comment_id: entry.comment_id,
+          version: entry.version
+        });
+      }
+    }
+  }
+  const comments2 = entries.map((entry) => {
+    const addressedBy = addressedByMap.get(entry.comment_id) ?? null;
+    const addressed = addressedBy !== null;
+    return {
+      comment_id: entry.comment_id,
+      author: entry.author,
+      created_at: entry.created_at,
+      display_name: entry.display_name,
+      body: entry.body,
+      anchor: entry.anchor,
+      addresses: entry.addresses,
+      readable: entry.readable,
+      unreadable_reason: entry.unreadable_reason,
+      addressed,
+      addressed_by: addressedBy,
+      addressed_by_comment_id: addressedBy?.comment_id ?? null,
+      addressed_by_version: addressedBy?.version ?? null
+    };
+  });
+  const addressedCount = comments2.filter((c) => c.addressed).length;
+  const unreadableCount = comments2.filter((c) => !c.readable).length;
+  const openCount = comments2.filter((c) => c.readable && !c.addressed && c.addresses === null).length;
+  const summary = {
+    total: comments2.length,
+    addressed: addressedCount,
+    open: openCount,
+    unreadable: unreadableCount
+  };
   if (options?.resolve_anchors === true) {
     const resolved = await resolveAnchors(relicId, comments2, deps);
     return {
       relic_id: relicId,
       count: comments2.length,
-      unreadable_count: unreadable,
+      unreadable_count: unreadableCount,
+      summary,
       comments: resolved.comments,
       content_blocks: resolved.imageBlocks
     };
@@ -4691,7 +4771,8 @@ async function readComments(relicId, deps, options) {
   return {
     relic_id: relicId,
     count: comments2.length,
-    unreadable_count: unreadable,
+    unreadable_count: unreadableCount,
+    summary,
     comments: comments2
   };
 }
@@ -4711,14 +4792,33 @@ async function postComment(input, deps) {
       throw new PublishError("local_comment_name_too_long", `the display name is ${nameBytes} bytes of UTF-8 and the limit is ` + `${COMMENT_DISPLAY_NAME_LIMIT_BYTES}.`, { name_bytes: nameBytes, limit_bytes: COMMENT_DISPLAY_NAME_LIMIT_BYTES });
     }
   }
+  let addresses = null;
+  if (input.addresses !== undefined && input.addresses !== null) {
+    if (typeof input.addresses !== "string" || input.addresses.trim().length === 0) {
+      throw new PublishError("local_comment_addresses_invalid", "addresses must be a non-empty string naming the comment being answered.");
+    }
+    const addressesBytes = new TextEncoder().encode(input.addresses).length;
+    if (addressesBytes > COMMENT_ADDRESSES_LIMIT_BYTES) {
+      throw new PublishError("local_comment_addresses_too_long", `addresses is ${addressesBytes} bytes of UTF-8 and the limit is ${COMMENT_ADDRESSES_LIMIT_BYTES}.`, {
+        addresses_bytes: addressesBytes,
+        limit_bytes: COMMENT_ADDRESSES_LIMIT_BYTES
+      });
+    }
+    addresses = input.addresses;
+  }
   const anchor = validateAndNormalizeAnchor(input.anchor);
   const commentKey = await deriveCommentKey(decodeKey(state.key));
   const ciphertext = await encryptComment(commentKey, {
     body: input.body,
     display_name: displayName,
-    anchor
+    anchor,
+    ...addresses == null ? {} : { addresses }
+  });
+  const posted = await postJson(deps, `${deps.serviceOrigin}/api/relics/${input.relic_id}/comments`, {
+    publish_token: state.publish_token,
+    ciphertext,
+    ...addresses == null ? {} : { addresses }
   });
-  const posted = await postJson(deps, `${deps.serviceOrigin}/api/relics/${input.relic_id}/comments`, { publish_token: state.publish_token, ciphertext });
   return {
     relic_id: input.relic_id,
     comment_id: String(posted["comment_id"]),
@@ -5627,6 +5727,60 @@ async function republish(input, deps) {
       throw error;
     throw new PublishError("local_state_unreadable", error.message);
   }
+  const addressesEntries = input.addresses;
+  if (addressesEntries !== undefined) {
+    if (!Array.isArray(addressesEntries)) {
+      throw new PublishError("invalid_acknowledgements", "addresses must be an array of { comment_id, note } entries.");
+    }
+    const seen = new Set;
+    for (const entry of addressesEntries) {
+      if (typeof entry !== "object" || entry === null || typeof entry.comment_id !== "string" || entry.comment_id.trim().length === 0) {
+        throw new PublishError("invalid_acknowledgement_comment_id", "acknowledgement comment_id must be a non-empty string.");
+      }
+      if (typeof entry.note !== "string" || entry.note.trim().length === 0) {
+        throw new PublishError("empty_acknowledgement_note", `acknowledgement note for comment ${entry.comment_id} cannot be empty or whitespace-only: it must say what was done to address the comment.`);
+      }
+      if (seen.has(entry.comment_id)) {
+        throw new PublishError("duplicate_acknowledgement", `duplicate acknowledgement entry for comment ${entry.comment_id}.`);
+      }
+      seen.add(entry.comment_id);
+    }
+  }
+  const commentResult = await readComments(input.relic_id, deps);
+  const unreadableComments = commentResult.comments.filter((c) => !c.readable);
+  const openComments = commentResult.comments.filter((c) => c.readable && !c.addressed && c.addresses === null);
+  if (addressesEntries && addressesEntries.length > 0) {
+    for (const entry of addressesEntries) {
+      const match = commentResult.comments.find((c) => c.comment_id === entry.comment_id);
+      if (!match) {
+        throw new PublishError("unknown_comment_id", `comment ${entry.comment_id} does not exist on relic ${input.relic_id}. The comment ids can only come from having read the relic's comments.`);
+      }
+      if (!match.readable) {
+        throw new PublishError("unreadable_comment_cannot_be_addressed", `comment ${entry.comment_id} cannot be addressed because it could not be decrypted.`);
+      }
+    }
+  }
+  const addressesSet = new Set(addressesEntries?.map((e) => e.comment_id) ?? []);
+  const remainingOpen = openComments.filter((c) => !addressesSet.has(c.comment_id));
+  if (unreadableComments.length > 0 || remainingOpen.length > 0) {
+    throw new PublishError("unaddressed_comments", formatUnaddressedRefusal(input.relic_id, remainingOpen, unreadableComments), {
+      relic_id: input.relic_id,
+      open_count: remainingOpen.length,
+      unreadable_count: unreadableComments.length,
+      open_comments: remainingOpen.map((c) => ({
+        comment_id: c.comment_id,
+        author: c.author,
+        created_at: c.created_at,
+        body: c.body
+      })),
+      unreadable_comments: unreadableComments.map((c) => ({
+        comment_id: c.comment_id,
+        author: c.author,
+        created_at: c.created_at,
+        unreadable_reason: c.unreadable_reason
+      }))
+    });
+  }
   const source = await readSource(input.path, deps.files);
   const filename = input.filename ?? source.basename;
   const normalizedTitle = normalizeTitle(input.title ?? filename);
@@ -5658,6 +5812,17 @@ async function republish(input, deps) {
   } catch (error) {
     throw new PublishError("local_state_write_failed", "the new version is live at the existing link, but updating the " + "local record failed, so the next republish from this machine may " + `report a stale version number: ${error.message}`, { relic_id: input.relic_id, version });
   }
+  const acknowledgements = [];
+  if (addressesEntries && addressesEntries.length > 0) {
+    for (const entry of addressesEntries) {
+      const ack = await postComment({
+        relic_id: input.relic_id,
+        body: entry.note,
+        addresses: entry.comment_id
+      }, deps);
+      acknowledgements.push(ack);
+    }
+  }
   return {
     relic_id: input.relic_id,
     version,
@@ -5668,7 +5833,8 @@ async function republish(input, deps) {
     resolved_path: source.resolvedPath,
     report_url: String(grant["report_url"]),
     disclosure_url: String(grant["disclosure_url"]),
-    key_phrase: keyToMnemonic(decodeKey(state.key)).join(" ")
+    key_phrase: keyToMnemonic(decodeKey(state.key)).join(" "),
+    ...acknowledgements.length > 0 ? { acknowledgements } : {}
   };
 }
 
@@ -5687,6 +5853,7 @@ var COMMENT_TOOL_NAME = "relic_comment";
 var COMMENT_MACHINE_BOUNDARY = "Only works for a relic this machine published: the comment key is derived " + "from that relic's key, which lives in local publish state and nowhere the " + "service can reach.";
 var MAX_TTL_DAYS = 3650;
 var VERSION_HISTORY_DISCLOSURE = "Anyone holding a relic's link can fetch every version it has ever held, " + "so republishing does not withdraw earlier content.";
+var REPUBLISH_DISCIPLINE_DISCLOSURE = " Before publishing, it reads the relic's comments and refuses if any are " + "unaddressed. Address open comments either by replying with `relic_comment` " + "or by passing `addresses: [{ comment_id, note }]` here to acknowledge them " + "in the new version. Unreadable comments block republishing. This is workflow " + "discipline in the client, not a boundary: the machine holding the publish " + "token can call the HTTP API directly, and the service cannot enforce this " + "because it cannot read comments.";
 var TOOL_DEFINITION = {
   name: TOOL_NAME,
   title: "Publish a relic",
@@ -5760,7 +5927,7 @@ var TOOL_DEFINITION = {
 var REPUBLISH_TOOL_DEFINITION = {
   name: REPUBLISH_TOOL_NAME,
   title: "Republish a relic",
-  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived.",
+  description: "Publish a new version of a relic this machine originally published, " + "encrypting under the same key so the existing share URL keeps working. " + VERSION_HISTORY_DISCLOSURE + " Only possible from the machine that holds the relic's key and publish " + "token; a relic that was taken down can never be revived." + REPUBLISH_DISCIPLINE_DISCLOSURE,
   inputSchema: {
     type: "object",
     properties: {
@@ -5785,6 +5952,25 @@ var REPUBLISH_TOOL_DEFINITION = {
         minimum: 1,
         maximum: MAX_TTL_DAYS,
         description: "Optional. A lifetime in days, forwarded on the republish " + "request. The service fixes a relic's lifetime at its first " + "publish, so treat this as reserved."
+      },
+      addresses: {
+        type: "array",
+        description: "Optional. Acknowledgement notes for open comments being addressed by this update. " + "Each entry posts an acknowledgement comment stamped with the new version after it lands. " + "Every open comment on the relic must be addressed either by an entry here or by a prior reply.",
+        items: {
+          type: "object",
+          properties: {
+            comment_id: {
+              type: "string",
+              description: "The id of the open comment being addressed."
+            },
+            note: {
+              type: "string",
+              description: "Required explanation of what changed in this version to address the comment. " + "Cannot be empty or whitespace-only."
+            }
+          },
+          required: ["comment_id", "note"],
+          additionalProperties: false
+        }
       }
     },
     required: ["relic_id", "path"],
@@ -6116,7 +6302,7 @@ var SHOW_TOOL_DEFINITION = {
 var READ_COMMENTS_TOOL_DEFINITION = {
   name: READ_COMMENTS_TOOL_NAME,
   title: "Read a relic's comments",
-  description: "Read the comments people have left on a relic, oldest first, decrypted " + "on this machine. Use it before changing content somebody was asked to " + "review, and after sharing a link, because a comment is the only way a " + "reader can answer back. " + "Each comment can be a remark on the relic as a whole or an exact mark: " + "a text quote with surrounding context, a stage pin, an artifact region, " + "a timestamp or span in audio or video, or a page in a document. " + "Pass `resolve_anchors: true` to fetch and decrypt the relic content and " + "resolve anchors against the actual content (source context runs for quotes, " + "crops and annotated views for image regions, and extracted video frames). " + "This defaults to false because content resolution spends a signed download " + "URL mint and download quota. " + COMMENT_MACHINE_BOUNDARY + " Takes the relic id, never the share URL: the URL carries the key in " + "its fragment. A comment that will not decrypt is returned marked " + "unreadable rather than dropped, so a shortened list never reads as " + "agreement.",
+  description: "Read the comments people have left on a relic, oldest first, decrypted " + "on this machine. Use it before changing content somebody was asked to " + "review, and after sharing a link, because a comment is the only way a " + "reader can answer back. " + "Each comment reports whether it has been addressed, and a compact summary " + "gives total, addressed, open, and unreadable counts. Its output is the input " + "to `relic_republish`, which requires every open comment to be addressed before " + "a new version can land. " + "Each comment can be a remark on the relic as a whole or an exact mark: " + "a text quote with surrounding context, a stage pin, an artifact region, " + "a timestamp or span in audio or video, or a page in a document. " + "Pass `resolve_anchors: true` to fetch and decrypt the relic content and " + "resolve anchors against the actual content (source context runs for quotes, " + "crops and annotated views for image regions, and extracted video frames). " + "This defaults to false because content resolution spends a signed download " + "URL mint and download quota. " + COMMENT_MACHINE_BOUNDARY + " Takes the relic id, never the share URL: the URL carries the key in " + "its fragment. A comment that will not decrypt is returned marked " + "unreadable rather than dropped, so a shortened list never reads as " + "agreement.",
   inputSchema: {
     type: "object",
     properties: {
@@ -6142,6 +6328,18 @@ var READ_COMMENTS_TOOL_DEFINITION = {
         minimum: 0,
         description: "How many of `count` did not decrypt. Above zero means part of the " + "conversation is unread, not absent."
       },
+      summary: {
+        type: "object",
+        description: "Compact counts of comment states on this relic.",
+        properties: {
+          total: { type: "integer", minimum: 0 },
+          addressed: { type: "integer", minimum: 0 },
+          open: { type: "integer", minimum: 0 },
+          unreadable: { type: "integer", minimum: 0 }
+        },
+        required: ["total", "addressed", "open", "unreadable"],
+        additionalProperties: false
+      },
       comments: {
         type: "array",
         items: {
@@ -6195,6 +6393,23 @@ var READ_COMMENTS_TOOL_DEFINITION = {
             },
             readable: { type: "boolean" },
             unreadable_reason: { type: ["string", "null"] },
+            addresses: {
+              type: ["string", "null"],
+              description: "The comment id this comment replies to or acknowledges, if any."
+            },
+            addressed: {
+              type: "boolean",
+              description: "Whether this comment has been addressed by a reply or update acknowledgement."
+            },
+            addressed_by: {
+              type: ["object", "null"],
+              description: "The comment that addressed this one, if addressed.",
+              properties: {
+                comment_id: { type: "string" },
+                version: { type: ["integer", "null"] }
+              },
+              required: ["comment_id"]
+            },
             resolved: {
               type: ["object", "null"],
               description: "The resolved content and status for this anchor, when resolve_anchors is enabled."
@@ -6208,13 +6423,16 @@ var READ_COMMENTS_TOOL_DEFINITION = {
             "body",
             "anchor",
             "readable",
-            "unreadable_reason"
+            "unreadable_reason",
+            "addresses",
+            "addressed",
+            "addressed_by"
           ],
           additionalProperties: false
         }
       }
     },
-    required: ["relic_id", "count", "unreadable_count", "comments"],
+    required: ["relic_id", "count", "unreadable_count", "summary", "comments"],
     additionalProperties: false
   }
 };
@@ -6237,6 +6455,10 @@ var COMMENT_TOOL_DEFINITION = {
         type: "string",
         description: "Optional. A name shown beside the comment, up to 64 bytes of " + "UTF-8. It aliases the attribution for presentation and never " + "replaces it."
       },
+      addresses: {
+        type: "string",
+        description: "Optional. The service-minted id of the comment this one answers or acknowledges. " + "Writing this marks that comment addressed so the relic can be republished. " + "The pointer is sealed into the encrypted comment and also passed to the service in the clear for notification routing."
+      },
       anchor: {
         type: "object",
         description: "Optional. Where the comment sits on the relic, so the reader sees " + "exactly what the comment is about. Can be a text selection " + '({kind: "quote", exact, prefix?, suffix?} or {kind: "text", quote}), ' + 'a point on the stage ({kind: "pin", x, y}), ' + 'a box on the artifact ({kind: "region", rect: {x, y, w, h}}), ' + 'a moment or span in audio/video ({kind: "time", t, t_end?, rect?}, with t ' + 'given as seconds or as a timecode like "1:23"), ' + 'or a page in a paged document ({kind: "page", page, rect?, exact?}). ' + "Omit for a remark about the whole relic.",
@@ -6326,7 +6548,7 @@ var DESCRIBE_TOOL_DEFINITION = {
     additionalProperties: false
   }
 };
-var SERVER_VERSION = "0.7.0";
+var SERVER_VERSION = "0.8.0";
 var SERVER_INFO = {
   name: "relic",
   title: "Relic",
@@ -6689,8 +6911,23 @@ async function callRepublish(id2, params, deps) {
   if (!ttlDays.ok) {
     return errorResponse(id2, ERROR_CODES.invalidParams, `\`ttl_days\` must be an integer between 1 and ${MAX_TTL_DAYS}, or ` + "omitted to leave the lifetime as the first publish set it");
   }
+  const rawAddresses = args["addresses"];
+  let addresses;
+  if (rawAddresses !== undefined) {
+    if (!Array.isArray(rawAddresses)) {
+      return errorResponse(id2, ERROR_CODES.invalidParams, "`addresses` must be an array of { comment_id, note } objects or omitted");
+    }
+    addresses = rawAddresses;
+  }
   try {
-    const result = await republish({ relic_id: relicId, path, filename, title: title2, ttl_days: ttlDays.days }, deps);
+    const result = await republish({
+      relic_id: relicId,
+      path,
+      filename,
+      title: title2,
+      ttl_days: ttlDays.days,
+      addresses
+    }, deps);
     return {
       jsonrpc: "2.0",
       id: id2,
@@ -6774,12 +7011,18 @@ async function callComment(id2, params, deps) {
   if (rawAnchor !== undefined && rawAnchor !== null && (typeof rawAnchor !== "object" || Array.isArray(rawAnchor))) {
     return errorResponse(id2, ERROR_CODES.invalidParams, "`anchor` must be an object or omitted");
   }
+  const rawAddresses = args["addresses"];
+  if (rawAddresses !== undefined && typeof rawAddresses !== "string") {
+    return errorResponse(id2, ERROR_CODES.invalidParams, "`addresses` must be a string or omitted");
+  }
+  const addresses = typeof rawAddresses === "string" ? rawAddresses : undefined;
   try {
     const result = await postComment({
       relic_id: relicId,
       body,
       display_name: displayName,
-      anchor: rawAnchor
+      anchor: rawAnchor,
+      addresses
     }, deps);
     return {
       jsonrpc: "2.0",
@@ -6866,11 +7109,17 @@ function commentTranscript(result) {
     }
     const mark = markLine(comment.anchor);
     const resolution = resolutionLine(comment.resolved);
+    const replyNote = comment.addresses !== null ? `[answers comment ${comment.addresses}]
+` : "";
+    const addressedNote = comment.addressed ? `[addressed by comment ${comment.addressed_by?.comment_id ?? "unknown"}${comment.addressed_by?.version != null ? ` in v${comment.addressed_by.version}` : ""}]
+` : "";
     return `${comment.created_at} ${who}:
-${mark}${resolution}${comment.body}`;
+${mark}${resolution}${replyNote}${addressedNote}${comment.body}`;
   });
   const header = result.unreadable_count === 0 ? `${result.count} comment(s) on relic ${result.relic_id}, oldest first.` : `${result.count} comment(s) on relic ${result.relic_id}, oldest ` + `first. ${result.unreadable_count} did not decrypt and are shown as ` + "unreadable rather than dropped, so treat this conversation as " + "partially unread.";
+  const summaryLine = `Summary: ${result.summary.total} total, ${result.summary.addressed} addressed, ${result.summary.open} open, ${result.summary.unreadable} unreadable.`;
   return `${header}
+${summaryLine}
 
 ${lines.join(`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relic-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Publish a file as an encrypted relic. The key is generated on your machine and never sent to the service.",
   "license": "MIT",
   "type": "module",

package/src/comments.ts

@@ -29,6 +29,7 @@
 
 import {
   type AnchorRect,
+  COMMENT_ADDRESSES_LIMIT_BYTES,
   COMMENT_ANCHOR_CONTEXT_LIMIT_BYTES,
   COMMENT_ANCHOR_MAX_PAGE,
   COMMENT_ANCHOR_MAX_SECONDS,
@@ -55,6 +56,11 @@ import {
 } from './resolve-anchor.ts';
 import { loadPublishState, type PublishState } from './state.ts';
 
+export interface CommentAddressedBy {
+  readonly comment_id: string;
+  readonly version: number | null;
+}
+
 /** One comment as an agent reads it. */
 export interface CommentRecord {
   readonly comment_id: string;
@@ -80,9 +86,23 @@ export interface CommentRecord {
    * the encrypted envelope, so it arrives with the body or not at all.
    */
   readonly anchor: CommentAnchor | null;
+  /**
+   * The comment this one answers or acknowledges, by service-minted id.
+   * Taken from the sealed copy only.
+   */
+  readonly addresses: string | null;
   readonly readable: boolean;
   /** Null exactly when `readable` is true. */
   readonly unreadable_reason: string | null;
+  /**
+   * True if some other comment carries addresses equal to this comment's id,
+   * taken from the sealed copy only.
+   */
+  readonly addressed: boolean;
+  /** The comment that addressed this one, if any. */
+  readonly addressed_by: CommentAddressedBy | null;
+  readonly addressed_by_comment_id?: string | null;
+  readonly addressed_by_version?: number | null;
   /**
    * Resolved content for this comment's anchor when anchor resolution is
    * requested. Null when freeform or when resolution was not requested.
@@ -90,6 +110,13 @@ export interface CommentRecord {
   readonly resolved?: ResolvedAnchor | null;
 }
 
+export interface CommentsSummary {
+  readonly total: number;
+  readonly addressed: number;
+  readonly open: number;
+  readonly unreadable: number;
+}
+
 export interface ReadCommentsResult {
   readonly relic_id: string;
   readonly count: number;
@@ -99,6 +126,7 @@ export interface ReadCommentsResult {
    * "nobody objected" when somebody did is the failure this member prevents.
    */
   readonly unreadable_count: number;
+  readonly summary: CommentsSummary;
   readonly comments: readonly CommentRecord[];
   readonly content_blocks?: readonly ContentBlock[];
 }
@@ -113,6 +141,66 @@ export interface ReadCommentsOptions {
   readonly resolve_anchors?: boolean;
 }
 
+/** First part of a comment body for refusal summaries, truncated if long. */
+export function previewCommentBody(body: string | null, maxChars = 80): string {
+  if (body === null || body === undefined) return '';
+  const trimmed = body.trim();
+  const firstLine = trimmed.split('\n')[0]?.trim() ?? '';
+  const text = firstLine.length > 0 ? firstLine : trimmed;
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 3)}...`;
+}
+
+/** Format the refusal message when republish is blocked by unaddressed comments. */
+export function formatUnaddressedRefusal(
+  relicId: string,
+  openComments: readonly CommentRecord[],
+  unreadableComments: readonly CommentRecord[] = []
+): string {
+  const parts: string[] = [];
+
+  if (openComments.length > 0 && unreadableComments.length > 0) {
+    parts.push(
+      `cannot republish relic ${relicId} while comments remain unaddressed. ` +
+        `${openComments.length} comment(s) are unanswered, and ${unreadableComments.length} comment(s) could not be decrypted. ` +
+        'Address unanswered comments either by replying with relic_comment or by passing addresses: [{ comment_id, note }] on republish.'
+    );
+  } else if (openComments.length > 0) {
+    parts.push(
+      `cannot republish relic ${relicId} while comments remain unaddressed. ` +
+        `${openComments.length} comment(s) are unanswered. ` +
+        'Address each open comment either by replying with relic_comment or by passing addresses: [{ comment_id, note }] on republish.'
+    );
+  } else {
+    parts.push(
+      `cannot republish relic ${relicId} because ${unreadableComments.length} comment(s) could not be decrypted. ` +
+        'A comment this client cannot read cannot be verified as addressed.'
+    );
+  }
+
+  if (openComments.length > 0) {
+    const list = openComments
+      .map(
+        (c) =>
+          `- [${c.comment_id}] from ${c.author} at ${c.created_at}: "${previewCommentBody(c.body)}"`
+      )
+      .join('\n');
+    parts.push(`Open comments (${openComments.length}):\n${list}`);
+  }
+
+  if (unreadableComments.length > 0) {
+    const list = unreadableComments
+      .map(
+        (c) =>
+          `- [${c.comment_id}] from ${c.author} at ${c.created_at}: unreadable (${c.unreadable_reason ?? "it did not decrypt under this relic's comment key"})`
+      )
+      .join('\n');
+    parts.push(`Unreadable comments (${unreadableComments.length}):\n${list}`);
+  }
+
+  return parts.join('\n\n');
+}
+
 export type CommentAnchorInput =
   | CommentAnchor
   | {
@@ -145,6 +233,11 @@ export interface CommentInput {
   readonly body: string;
   readonly display_name?: string | undefined;
   readonly anchor?: CommentAnchorInput | null | undefined;
+  /**
+   * Optional service-minted id of the comment this one answers or acknowledges.
+   * Sealed into the ciphertext and passed in the clear to the service for notification routing.
+   */
+  readonly addresses?: string | null | undefined;
 }
 
 export async function readComments(
@@ -171,8 +264,19 @@ export async function readComments(
   }
 
   const commentKey = await deriveCommentKey(decodeKey(state.key));
-  const comments: CommentRecord[] = [];
-  let unreadable = 0;
+  interface DecryptedCommentEntry {
+    comment_id: string;
+    author: string;
+    created_at: string;
+    display_name: string | null;
+    body: string | null;
+    anchor: CommentAnchor | null;
+    addresses: string | null;
+    version: number | null;
+    readable: boolean;
+    unreadable_reason: string | null;
+  }
+  const entries: DecryptedCommentEntry[] = [];
 
   for (const [index, entry] of listed.entries()) {
     const row =
@@ -188,16 +292,18 @@ export async function readComments(
     const createdAt =
       typeof row['created_at'] === 'string' ? row['created_at'] : 'unknown';
     const ciphertext = row['ciphertext'];
+    const version = typeof row['version'] === 'number' ? row['version'] : null;
 
     if (typeof ciphertext !== 'string') {
-      unreadable += 1;
-      comments.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
         display_name: null,
         body: null,
         anchor: null,
+        addresses: null,
+        version,
         readable: false,
         unreadable_reason: 'the row carried no ciphertext',
       });
@@ -206,7 +312,7 @@ export async function readComments(
 
     try {
       const plaintext = await decryptComment(commentKey, ciphertext);
-      comments.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
@@ -215,20 +321,23 @@ export async function readComments(
         // Absent and null both mean freeform. One shape crosses to the agent,
         // so a caller never has to distinguish two ways of saying no mark.
         anchor: plaintext.anchor ?? null,
+        addresses: plaintext.addresses ?? null,
+        version,
         readable: true,
         unreadable_reason: null,
       });
     } catch (error) {
       // One comment that will not open must not hide the ones that will, and
       // it must not vanish either. It comes back named, with the reason.
-      unreadable += 1;
-      comments.push({
+      entries.push({
         comment_id: commentId,
         author,
         created_at: createdAt,
         display_name: null,
         body: null,
         anchor: null,
+        addresses: null,
+        version,
         readable: false,
         unreadable_reason: `it did not decrypt under this relic's comment key: ${
           (error as Error).message
@@ -236,12 +345,74 @@ export async function readComments(
       });
     }
   }
+
+  // The sealed copy is authoritative. It sits inside the AEAD. A caller MAY
+  // also pass the same id to the service in the clear so the service can route
+  // a notification, and that clear copy is a routing hint the operator can see
+  // and could forge. Nothing user-facing may resolve "addressed" from the clear
+  // copy. We only inspect plaintext.addresses from the decrypted ciphertext.
+  const addressedByMap = new Map<
+    string,
+    { comment_id: string; version: number | null }
+  >();
+
+  for (const entry of entries) {
+    if (
+      entry.readable &&
+      entry.addresses !== null &&
+      entry.addresses !== entry.comment_id
+    ) {
+      if (!addressedByMap.has(entry.addresses)) {
+        addressedByMap.set(entry.addresses, {
+          comment_id: entry.comment_id,
+          version: entry.version,
+        });
+      }
+    }
+  }
+
+  const comments: CommentRecord[] = entries.map((entry) => {
+    const addressedBy = addressedByMap.get(entry.comment_id) ?? null;
+    const addressed = addressedBy !== null;
+    return {
+      comment_id: entry.comment_id,
+      author: entry.author,
+      created_at: entry.created_at,
+      display_name: entry.display_name,
+      body: entry.body,
+      anchor: entry.anchor,
+      addresses: entry.addresses,
+      readable: entry.readable,
+      unreadable_reason: entry.unreadable_reason,
+      addressed,
+      addressed_by: addressedBy,
+      addressed_by_comment_id: addressedBy?.comment_id ?? null,
+      addressed_by_version: addressedBy?.version ?? null,
+    };
+  });
+
+  const addressedCount = comments.filter((c) => c.addressed).length;
+  const unreadableCount = comments.filter((c) => !c.readable).length;
+  // A comment is open when it is readable, has not been addressed by another
+  // comment, and is not itself a reply or update acknowledgement.
+  const openCount = comments.filter(
+    (c) => c.readable && !c.addressed && c.addresses === null
+  ).length;
+
+  const summary: CommentsSummary = {
+    total: comments.length,
+    addressed: addressedCount,
+    open: openCount,
+    unreadable: unreadableCount,
+  };
+
   if (options?.resolve_anchors === true) {
     const resolved = await resolveAnchors(relicId, comments, deps);
     return {
       relic_id: relicId,
       count: comments.length,
-      unreadable_count: unreadable,
+      unreadable_count: unreadableCount,
+      summary,
       comments: resolved.comments,
       content_blocks: resolved.imageBlocks,
     };
@@ -250,7 +421,8 @@ export async function readComments(
   return {
     relic_id: relicId,
     count: comments.length,
-    unreadable_count: unreadable,
+    unreadable_count: unreadableCount,
+    summary,
     comments,
   };
 }
@@ -295,6 +467,31 @@ export async function postComment(
     }
   }
 
+  let addresses: string | null = null;
+  if (input.addresses !== undefined && input.addresses !== null) {
+    if (
+      typeof input.addresses !== 'string' ||
+      input.addresses.trim().length === 0
+    ) {
+      throw new PublishError(
+        'local_comment_addresses_invalid',
+        'addresses must be a non-empty string naming the comment being answered.'
+      );
+    }
+    const addressesBytes = new TextEncoder().encode(input.addresses).length;
+    if (addressesBytes > COMMENT_ADDRESSES_LIMIT_BYTES) {
+      throw new PublishError(
+        'local_comment_addresses_too_long',
+        `addresses is ${addressesBytes} bytes of UTF-8 and the limit is ${COMMENT_ADDRESSES_LIMIT_BYTES}.`,
+        {
+          addresses_bytes: addressesBytes,
+          limit_bytes: COMMENT_ADDRESSES_LIMIT_BYTES,
+        }
+      );
+    }
+    addresses = input.addresses;
+  }
+
   const anchor = validateAndNormalizeAnchor(input.anchor);
 
   const commentKey = await deriveCommentKey(decodeKey(state.key));
@@ -302,17 +499,23 @@ export async function postComment(
     body: input.body,
     display_name: displayName,
     anchor,
+    ...(addresses == null ? {} : { addresses }),
   });
 
   // The token travels in the body, where the republish grant already puts it,
   // so the two write paths authorize the same way and neither invents a
   // header the service has to learn.
+  // When addressing a comment, the pointer is also sent in the clear for
+  // notification routing.
   const posted = await postJson(
     deps,
     `${deps.serviceOrigin}/api/relics/${input.relic_id}/comments`,
-    { publish_token: state.publish_token, ciphertext }
+    {
+      publish_token: state.publish_token,
+      ciphertext,
+      ...(addresses == null ? {} : { addresses }),
+    }
   );
-
   return {
     relic_id: input.relic_id,
     comment_id: String(posted['comment_id']),

package/src/publish.ts

@@ -78,8 +78,16 @@ export type ClientCode =
   | 'local_comment_anchor_time_span_invalid'
   | 'local_comment_anchor_page_missing'
   | 'local_comment_anchor_page_out_of_range'
+  | 'local_comment_addresses_invalid'
+  | 'local_comment_addresses_too_long'
+  | 'unaddressed_comments'
+  | 'empty_acknowledgement_note'
+  | 'invalid_acknowledgement_comment_id'
+  | 'duplicate_acknowledgement'
+  | 'unknown_comment_id'
+  | 'unreadable_comment_cannot_be_addressed'
+  | 'invalid_acknowledgements'
   | 'app_response_unusable';
-
 export class PublishError extends Error {
   override readonly name = 'PublishError';
   constructor(

package/src/republish.ts

@@ -19,6 +19,12 @@ import {
   type RendererClass,
 } from '@relic/format';
 import { keyToMnemonic } from '@relic/format/mnemonic';
+import {
+  type CommentResult,
+  formatUnaddressedRefusal,
+  postComment,
+  readComments,
+} from './comments.ts';
 import {
   guessMimetype,
   type PublishDeps,
@@ -34,6 +40,11 @@ import {
   savePublishState,
 } from './state.ts';
 
+export interface RepublishAddressEntry {
+  readonly comment_id: string;
+  readonly note: string;
+}
+
 export interface RepublishInput {
   readonly relic_id: string;
   readonly path: string;
@@ -51,6 +62,13 @@ export interface RepublishInput {
    * change if that ever shifts.
    */
   readonly ttl_days?: number | undefined;
+  /**
+   * Optional acknowledgement notes for open comments being addressed by this
+   * update. Each entry posts an acknowledgement comment stamped with the new
+   * version after it lands. Every open comment on the relic must be addressed
+   * either by an entry here or by a prior reply.
+   */
+  readonly addresses?: readonly RepublishAddressEntry[] | undefined;
 }
 
 export interface RepublishResult {
@@ -74,6 +92,10 @@ export interface RepublishResult {
   readonly report_url: string;
   readonly disclosure_url: string;
   readonly key_phrase: string;
+  /**
+   * Acknowledgement comments posted for comments addressed by this update.
+   */
+  readonly acknowledgements?: readonly CommentResult[] | undefined;
   /**
    * Deliberately no `url` member. The share URL is unchanged by a new
    * version, and reprinting it would reprint the key for no new benefit;
@@ -118,6 +140,107 @@ export async function republish(
     if (error instanceof PublishError) throw error;
     throw new PublishError('local_state_unreadable', (error as Error).message);
   }
+  // Validate addresses entries up front before any network or file reads.
+  const addressesEntries = input.addresses;
+  if (addressesEntries !== undefined) {
+    if (!Array.isArray(addressesEntries)) {
+      throw new PublishError(
+        'invalid_acknowledgements',
+        'addresses must be an array of { comment_id, note } entries.'
+      );
+    }
+    const seen = new Set<string>();
+    for (const entry of addressesEntries) {
+      if (
+        typeof entry !== 'object' ||
+        entry === null ||
+        typeof entry.comment_id !== 'string' ||
+        entry.comment_id.trim().length === 0
+      ) {
+        throw new PublishError(
+          'invalid_acknowledgement_comment_id',
+          'acknowledgement comment_id must be a non-empty string.'
+        );
+      }
+      if (typeof entry.note !== 'string' || entry.note.trim().length === 0) {
+        throw new PublishError(
+          'empty_acknowledgement_note',
+          `acknowledgement note for comment ${entry.comment_id} cannot be empty or whitespace-only: it must say what was done to address the comment.`
+        );
+      }
+      if (seen.has(entry.comment_id)) {
+        throw new PublishError(
+          'duplicate_acknowledgement',
+          `duplicate acknowledgement entry for comment ${entry.comment_id}.`
+        );
+      }
+      seen.add(entry.comment_id);
+    }
+  }
+
+  // The comment gate: before publishing a new version, read the relic's
+  // comments, decrypt them locally, and verify every comment has been
+  // addressed. Unaddressed or unreadable comments refuse the republish.
+  const commentResult = await readComments(input.relic_id, deps);
+  const unreadableComments = commentResult.comments.filter((c) => !c.readable);
+  const openComments = commentResult.comments.filter(
+    (c) => c.readable && !c.addressed && c.addresses === null
+  );
+
+  if (addressesEntries && addressesEntries.length > 0) {
+    for (const entry of addressesEntries) {
+      const match = commentResult.comments.find(
+        (c) => c.comment_id === entry.comment_id
+      );
+      if (!match) {
+        throw new PublishError(
+          'unknown_comment_id',
+          `comment ${entry.comment_id} does not exist on relic ${input.relic_id}. The comment ids can only come from having read the relic's comments.`
+        );
+      }
+      if (!match.readable) {
+        throw new PublishError(
+          'unreadable_comment_cannot_be_addressed',
+          `comment ${entry.comment_id} cannot be addressed because it could not be decrypted.`
+        );
+      }
+    }
+  }
+
+  const addressesSet = new Set(
+    addressesEntries?.map((e) => e.comment_id) ?? []
+  );
+  const remainingOpen = openComments.filter(
+    (c) => !addressesSet.has(c.comment_id)
+  );
+
+  if (unreadableComments.length > 0 || remainingOpen.length > 0) {
+    throw new PublishError(
+      'unaddressed_comments',
+      formatUnaddressedRefusal(
+        input.relic_id,
+        remainingOpen,
+        unreadableComments
+      ),
+      {
+        relic_id: input.relic_id,
+        open_count: remainingOpen.length,
+        unreadable_count: unreadableComments.length,
+        open_comments: remainingOpen.map((c) => ({
+          comment_id: c.comment_id,
+          author: c.author,
+          created_at: c.created_at,
+          body: c.body,
+        })),
+        unreadable_comments: unreadableComments.map((c) => ({
+          comment_id: c.comment_id,
+          author: c.author,
+          created_at: c.created_at,
+          unreadable_reason: c.unreadable_reason,
+        })),
+      }
+    );
+  }
 
   const source = await readSource(input.path, deps.files);
   const filename = input.filename ?? source.basename;
@@ -189,6 +312,23 @@ export async function republish(
     );
   }
 
+  // After the new version lands, post an acknowledgement comment for each
+  // addressed entry, so the acknowledgement is stamped with the new version.
+  const acknowledgements: CommentResult[] = [];
+  if (addressesEntries && addressesEntries.length > 0) {
+    for (const entry of addressesEntries) {
+      const ack = await postComment(
+        {
+          relic_id: input.relic_id,
+          body: entry.note,
+          addresses: entry.comment_id,
+        },
+        deps
+      );
+      acknowledgements.push(ack);
+    }
+  }
+
   return {
     relic_id: input.relic_id,
     version,
@@ -203,5 +343,6 @@ export async function republish(
     report_url: String(grant['report_url']),
     disclosure_url: String(grant['disclosure_url']),
     key_phrase: keyToMnemonic(decodeKey(state.key)).join(' '),
+    ...(acknowledgements.length > 0 ? { acknowledgements } : {}),
   };
 }

package/src/server.ts

@@ -24,6 +24,7 @@ import { MNEMONIC_WORDS } from '@relic/format/mnemonic';
 import {
   type CommentAnchorInput,
   type CommentRecord,
+  type CommentsSummary,
   describeAnchor,
   formatTimecode,
   postComment,
@@ -57,7 +58,7 @@ import {
   republishToolCall,
   ServerRefusal,
 } from './publish.ts';
-import { republish } from './republish.ts';
+import { type RepublishAddressEntry, republish } from './republish.ts';
 
 export type { JsonRpcRequest, JsonRpcResponse };
 export {
@@ -197,6 +198,14 @@ const MAX_TTL_DAYS = 3650;
 const VERSION_HISTORY_DISCLOSURE =
   "Anyone holding a relic's link can fetch every version it has ever held, " +
   'so republishing does not withdraw earlier content.';
+export const REPUBLISH_DISCIPLINE_DISCLOSURE =
+  " Before publishing, it reads the relic's comments and refuses if any are " +
+  'unaddressed. Address open comments either by replying with `relic_comment` ' +
+  'or by passing `addresses: [{ comment_id, note }]` here to acknowledge them ' +
+  'in the new version. Unreadable comments block republishing. This is workflow ' +
+  'discipline in the client, not a boundary: the machine holding the publish ' +
+  'token can call the HTTP API directly, and the service cannot enforce this ' +
+  'because it cannot read comments.';
 
 export const TOOL_DEFINITION = {
   name: TOOL_NAME,
@@ -300,7 +309,8 @@ export const REPUBLISH_TOOL_DEFINITION = {
     'encrypting under the same key so the existing share URL keeps working. ' +
     VERSION_HISTORY_DISCLOSURE +
     " Only possible from the machine that holds the relic's key and publish " +
-    'token; a relic that was taken down can never be revived.',
+    'token; a relic that was taken down can never be revived.' +
+    REPUBLISH_DISCIPLINE_DISCLOSURE,
   inputSchema: {
     type: 'object',
     properties: {
@@ -334,6 +344,30 @@ export const REPUBLISH_TOOL_DEFINITION = {
           "request. The service fixes a relic's lifetime at its first " +
           'publish, so treat this as reserved.',
       },
+      addresses: {
+        type: 'array',
+        description:
+          'Optional. Acknowledgement notes for open comments being addressed by this update. ' +
+          'Each entry posts an acknowledgement comment stamped with the new version after it lands. ' +
+          'Every open comment on the relic must be addressed either by an entry here or by a prior reply.',
+        items: {
+          type: 'object',
+          properties: {
+            comment_id: {
+              type: 'string',
+              description: 'The id of the open comment being addressed.',
+            },
+            note: {
+              type: 'string',
+              description:
+                'Required explanation of what changed in this version to address the comment. ' +
+                'Cannot be empty or whitespace-only.',
+            },
+          },
+          required: ['comment_id', 'note'],
+          additionalProperties: false,
+        },
+      },
     },
     required: ['relic_id', 'path'],
     additionalProperties: false,
@@ -736,6 +770,10 @@ export const READ_COMMENTS_TOOL_DEFINITION = {
     'on this machine. Use it before changing content somebody was asked to ' +
     'review, and after sharing a link, because a comment is the only way a ' +
     'reader can answer back. ' +
+    'Each comment reports whether it has been addressed, and a compact summary ' +
+    'gives total, addressed, open, and unreadable counts. Its output is the input ' +
+    'to `relic_republish`, which requires every open comment to be addressed before ' +
+    'a new version can land. ' +
     'Each comment can be a remark on the relic as a whole or an exact mark: ' +
     'a text quote with surrounding context, a stage pin, an artifact region, ' +
     'a timestamp or span in audio or video, or a page in a document. ' +
@@ -780,6 +818,18 @@ export const READ_COMMENTS_TOOL_DEFINITION = {
           'How many of `count` did not decrypt. Above zero means part of the ' +
           'conversation is unread, not absent.',
       },
+      summary: {
+        type: 'object',
+        description: 'Compact counts of comment states on this relic.',
+        properties: {
+          total: { type: 'integer', minimum: 0 },
+          addressed: { type: 'integer', minimum: 0 },
+          open: { type: 'integer', minimum: 0 },
+          unreadable: { type: 'integer', minimum: 0 },
+        },
+        required: ['total', 'addressed', 'open', 'unreadable'],
+        additionalProperties: false,
+      },
       comments: {
         type: 'array',
         items: {
@@ -843,6 +893,25 @@ export const READ_COMMENTS_TOOL_DEFINITION = {
             },
             readable: { type: 'boolean' },
             unreadable_reason: { type: ['string', 'null'] },
+            addresses: {
+              type: ['string', 'null'],
+              description:
+                'The comment id this comment replies to or acknowledges, if any.',
+            },
+            addressed: {
+              type: 'boolean',
+              description:
+                'Whether this comment has been addressed by a reply or update acknowledgement.',
+            },
+            addressed_by: {
+              type: ['object', 'null'],
+              description: 'The comment that addressed this one, if addressed.',
+              properties: {
+                comment_id: { type: 'string' },
+                version: { type: ['integer', 'null'] },
+              },
+              required: ['comment_id'],
+            },
             resolved: {
               type: ['object', 'null'],
               description:
@@ -858,12 +927,15 @@ export const READ_COMMENTS_TOOL_DEFINITION = {
             'anchor',
             'readable',
             'unreadable_reason',
+            'addresses',
+            'addressed',
+            'addressed_by',
           ],
           additionalProperties: false,
         },
       },
     },
-    required: ['relic_id', 'count', 'unreadable_count', 'comments'],
+    required: ['relic_id', 'count', 'unreadable_count', 'summary', 'comments'],
     additionalProperties: false,
   },
 } as const;
@@ -905,6 +977,13 @@ export const COMMENT_TOOL_DEFINITION = {
           'UTF-8. It aliases the attribution for presentation and never ' +
           'replaces it.',
       },
+      addresses: {
+        type: 'string',
+        description:
+          'Optional. The service-minted id of the comment this one answers or acknowledges. ' +
+          'Writing this marks that comment addressed so the relic can be republished. ' +
+          'The pointer is sealed into the encrypted comment and also passed to the service in the clear for notification routing.',
+      },
       anchor: {
         type: 'object',
         description:
@@ -1710,10 +1789,29 @@ async function callRepublish(
         'omitted to leave the lifetime as the first publish set it'
     );
   }
+  const rawAddresses = args['addresses'];
+  let addresses: readonly RepublishAddressEntry[] | undefined;
+  if (rawAddresses !== undefined) {
+    if (!Array.isArray(rawAddresses)) {
+      return errorResponse(
+        id,
+        ERROR_CODES.invalidParams,
+        '`addresses` must be an array of { comment_id, note } objects or omitted'
+      );
+    }
+    addresses = rawAddresses as readonly RepublishAddressEntry[];
+  }
 
   try {
     const result = await republish(
-      { relic_id: relicId, path, filename, title, ttl_days: ttlDays.days },
+      {
+        relic_id: relicId,
+        path,
+        filename,
+        title,
+        ttl_days: ttlDays.days,
+        addresses,
+      },
       deps
     );
     return {
@@ -1856,6 +1954,16 @@ async function callComment(
     );
   }
 
+  const rawAddresses = args['addresses'];
+  if (rawAddresses !== undefined && typeof rawAddresses !== 'string') {
+    return errorResponse(
+      id,
+      ERROR_CODES.invalidParams,
+      '`addresses` must be a string or omitted'
+    );
+  }
+  const addresses = typeof rawAddresses === 'string' ? rawAddresses : undefined;
+
   try {
     const result = await postComment(
       {
@@ -1863,6 +1971,7 @@ async function callComment(
         body,
         display_name: displayName,
         anchor: rawAnchor as CommentAnchorInput | null | undefined,
+        addresses,
       },
       deps
     );
@@ -1970,6 +2079,7 @@ function commentTranscript(result: {
   readonly relic_id: string;
   readonly count: number;
   readonly unreadable_count: number;
+  readonly summary: CommentsSummary;
   readonly comments: readonly CommentRecord[];
 }): string {
   if (result.count === 0) {
@@ -1989,7 +2099,18 @@ function commentTranscript(result: {
     // would be the same defect this fixed, one layer up.
     const mark = markLine(comment.anchor);
     const resolution = resolutionLine(comment.resolved);
-    return `${comment.created_at} ${who}:\n${mark}${resolution}${comment.body}`;
+    const replyNote =
+      comment.addresses !== null
+        ? `[answers comment ${comment.addresses}]\n`
+        : '';
+    const addressedNote = comment.addressed
+      ? `[addressed by comment ${comment.addressed_by?.comment_id ?? 'unknown'}${
+          comment.addressed_by?.version != null
+            ? ` in v${comment.addressed_by.version}`
+            : ''
+        }]\n`
+      : '';
+    return `${comment.created_at} ${who}:\n${mark}${resolution}${replyNote}${addressedNote}${comment.body}`;
   });
 
   const header =
@@ -2000,7 +2121,9 @@ function commentTranscript(result: {
         'unreadable rather than dropped, so treat this conversation as ' +
         'partially unread.';
 
-  return `${header}\n\n${lines.join('\n\n')}`;
+  const summaryLine = `Summary: ${result.summary.total} total, ${result.summary.addressed} addressed, ${result.summary.open} open, ${result.summary.unreadable} unreadable.`;
+
+  return `${header}\n${summaryLine}\n\n${lines.join('\n\n')}`;
 }
 
 /**