@magic-markdown/cli 0.3.13 → 0.3.17

package/dist/index.js

@@ -270,8 +270,8 @@ var require_punycode = __commonJS({
 });
 
 // src/index.ts
-import { readFile as readFile6 } from "node:fs/promises";
-import { resolve as resolve5 } from "node:path";
+import { readFile as readFile7 } from "node:fs/promises";
+import { resolve as resolve6 } from "node:path";
 
 // ../core/src/types.ts
 var SIDECAR_SCHEMA_VERSION = 1;
@@ -339,6 +339,7 @@ var POLLUTING_PATTERNS = [
   { name: "CriticMarkup substitution", pattern: /\{~~[\s\S]*?~~\}/ },
   { name: "CriticMarkup comment", pattern: /\{>>[\s\S]*?<<\}/ },
   { name: "mdocs HTML marker", pattern: /<!--\s*mdocs:/i },
+  { name: "mdocs suggestion marker", pattern: /<!--\s*\/?\s*mdocs-suggestion\b/i },
   { name: "mdocs directive", pattern: /:{1,3}(?:comment|suggestion|anchor)\b/i }
 ];
 function findCleanMarkdownViolations(markdown) {
@@ -405,7 +406,7 @@ function replacementLinesForRange(replacement) {
 function extractMarkdownImages(markdown, documentPath) {
   const masked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, masked);
-  const lineStarts = getLineStarts(markdown);
+  const lineStarts2 = getLineStarts(markdown);
   const images = [];
   let index = 0;
   while (index < masked.length) {
@@ -423,7 +424,7 @@ function extractMarkdownImages(markdown, documentPath) {
     }
     const alt = markdown.slice(labelOpen + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts, start);
+    const position = positionAt(lineStarts2, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -491,7 +492,7 @@ function extractMarkdownLinks(markdown) {
   const codeMasked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, codeMasked);
   const masked = maskReferenceDefinitions(markdown, codeMasked);
-  const lineStarts = getLineStarts(markdown);
+  const lineStarts2 = getLineStarts(markdown);
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -508,7 +509,7 @@ function extractMarkdownLinks(markdown) {
     }
     const label = markdown.slice(start + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts, start);
+    const position = positionAt(lineStarts2, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -564,7 +565,7 @@ function extractMarkdownLinks(markdown) {
     }
     index = labelClose + 1;
   }
-  extractWikilinks(markdown, masked, lineStarts).forEach((link2) => links.push(link2));
+  extractWikilinks(markdown, masked, lineStarts2).forEach((link2) => links.push(link2));
   return links.sort((left, right) => left.line - right.line || left.column - right.column);
 }
 function toImageReference(image2) {
@@ -591,7 +592,7 @@ function toLinkReference(link2) {
     syntax: link2.syntax
   };
 }
-function extractWikilinks(markdown, masked, lineStarts) {
+function extractWikilinks(markdown, masked, lineStarts2) {
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -608,7 +609,7 @@ function extractWikilinks(markdown, masked, lineStarts) {
     }
     const parsed = parseWikilinkBody(markdown.slice(start + 2, close2));
     if (parsed) {
-      const position = positionAt(lineStarts, start);
+      const position = positionAt(lineStarts2, start);
       links.push({
         label: parsed.label ?? parsed.target,
         target: parsed.target,
@@ -888,12 +889,12 @@ function getLineStarts(value) {
   }
   return starts;
 }
-function positionAt(lineStarts, index) {
+function positionAt(lineStarts2, index) {
   let low = 0;
-  let high = lineStarts.length - 1;
+  let high = lineStarts2.length - 1;
   while (low <= high) {
     const middle = Math.floor((low + high) / 2);
-    const start = lineStarts[middle] ?? 0;
+    const start = lineStarts2[middle] ?? 0;
     if (start <= index) {
       low = middle + 1;
     } else {
@@ -903,7 +904,7 @@ function positionAt(lineStarts, index) {
   const lineIndex = Math.max(0, high);
   return {
     line: lineIndex + 1,
-    column: index - (lineStarts[lineIndex] ?? 0) + 1
+    column: index - (lineStarts2[lineIndex] ?? 0) + 1
   };
 }
 
@@ -979,270 +980,455 @@ function contextSuffix(value) {
   return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") ?? "";
 }
 
-// ../core/src/text-merge.ts
-var MAX_DIFF_CELLS = 25e6;
-function mergeText(base, ours, theirs) {
-  if (ours === theirs) return { ok: true, text: ours };
-  if (base === ours) return { ok: true, text: theirs };
-  if (base === theirs) return { ok: true, text: ours };
-  const baseLines = base.split("\n");
-  const ourLines = ours.split("\n");
-  const theirLines = theirs.split("\n");
-  let regionsA;
-  let regionsB;
-  try {
-    regionsA = diffTextRegions(baseLines, ourLines);
-    regionsB = diffTextRegions(baseLines, theirLines);
-  } catch {
-    return { ok: false, reason: "too_large" };
-  }
-  const clusters = clusterRegions(regionsA, regionsB);
-  const merged = [];
-  let baseCursor = 0;
-  for (const cluster of clusters) {
-    for (let line = baseCursor; line < cluster.lo; line += 1) merged.push(baseLines[line]);
-    const baseText = baseLines.slice(cluster.lo, cluster.hi);
-    const ourText = sideSlice(ourLines, regionsA, cluster.lo, cluster.hi);
-    const theirText = sideSlice(theirLines, regionsB, cluster.lo, cluster.hi);
-    const oursChanged = !linesEqual(ourText, baseText);
-    const theirsChanged = !linesEqual(theirText, baseText);
-    if (oursChanged && theirsChanged && !linesEqual(ourText, theirText)) {
-      return { ok: false, reason: "overlapping_changes" };
-    }
-    merged.push(...oursChanged ? ourText : theirText);
-    baseCursor = cluster.hi;
-  }
-  for (let line = baseCursor; line < baseLines.length; line += 1) merged.push(baseLines[line]);
-  return { ok: true, text: merged.join("\n") };
-}
-function diffTextRegions(base, side) {
-  let prefix = 0;
-  while (prefix < base.length && prefix < side.length && base[prefix] === side[prefix]) prefix += 1;
-  let suffix = 0;
-  while (suffix < base.length - prefix && suffix < side.length - prefix && base[base.length - 1 - suffix] === side[side.length - 1 - suffix]) {
-    suffix += 1;
-  }
-  const baseCore = base.slice(prefix, base.length - suffix);
-  const sideCore = side.slice(prefix, side.length - suffix);
-  if (!baseCore.length && !sideCore.length) return [];
-  if ((baseCore.length + 1) * (sideCore.length + 1) > MAX_DIFF_CELLS) throw new Error("diff too large");
-  const rows = baseCore.length + 1;
-  const cols = sideCore.length + 1;
-  const lcs = new Uint32Array(rows * cols);
-  for (let row2 = baseCore.length - 1; row2 >= 0; row2 -= 1) {
-    for (let col2 = sideCore.length - 1; col2 >= 0; col2 -= 1) {
-      lcs[row2 * cols + col2] = baseCore[row2] === sideCore[col2] ? lcs[(row2 + 1) * cols + col2 + 1] + 1 : Math.max(lcs[(row2 + 1) * cols + col2], lcs[row2 * cols + col2 + 1]);
-    }
-  }
-  const regions = [];
-  let row = 0;
-  let col = 0;
-  let pendingBase = -1;
-  let pendingSide = -1;
-  const flush = (baseEnd, sideEnd) => {
-    if (pendingBase < 0) return;
-    regions.push({
-      baseStart: prefix + pendingBase,
-      baseLength: baseEnd - pendingBase,
-      sideStart: prefix + pendingSide,
-      sideLength: sideEnd - pendingSide
-    });
-    pendingBase = -1;
-    pendingSide = -1;
-  };
-  while (row < baseCore.length || col < sideCore.length) {
-    if (row < baseCore.length && col < sideCore.length && baseCore[row] === sideCore[col]) {
-      flush(row, col);
-      row += 1;
-      col += 1;
-    } else {
-      if (pendingBase < 0) {
-        pendingBase = row;
-        pendingSide = col;
-      }
-      if (col >= sideCore.length || row < baseCore.length && lcs[(row + 1) * cols + col] >= lcs[row * cols + col + 1]) {
-        row += 1;
-      } else {
-        col += 1;
-      }
-    }
-  }
-  flush(row, col);
-  return regions;
-}
-function clusterRegions(regionsA, regionsB) {
-  const spans = [...regionsA, ...regionsB].map((region) => ({ lo: region.baseStart, hi: region.baseStart + region.baseLength })).sort((left, right) => left.lo - right.lo || left.hi - right.hi);
-  const clusters = [];
-  for (const span of spans) {
-    const last = clusters.at(-1);
-    if (last && span.lo <= last.hi) {
-      last.hi = Math.max(last.hi, span.hi);
-    } else {
-      clusters.push({ lo: span.lo, hi: span.hi });
+// ../core/src/review-markdown.ts
+var START_MARKER = "<!--mdocs-suggestion";
+var END_MARKER = "<!--/mdocs-suggestion-->";
+function parseReviewMarkdown(reviewMarkdown) {
+  const segments = [];
+  const suggestions = [];
+  let cursor = 0;
+  let canonicalOffset = 0;
+  while (cursor < reviewMarkdown.length) {
+    const markerStart = reviewMarkdown.indexOf(START_MARKER, cursor);
+    if (markerStart === -1) {
+      appendTextSegment(reviewMarkdown, segments, cursor, reviewMarkdown.length, canonicalOffset);
+      break;
     }
+    appendTextSegment(reviewMarkdown, segments, cursor, markerStart, canonicalOffset);
+    canonicalOffset += markerStart - cursor;
+    const startClose = reviewMarkdown.indexOf("-->", markerStart);
+    if (startClose === -1) throw invalidReviewMarkdown("Unclosed mdocs suggestion marker.");
+    const attrs2 = parseMarkerAttributes(reviewMarkdown.slice(markerStart + START_MARKER.length, startClose));
+    if (!attrs2.id) throw invalidReviewMarkdown("Suggestion marker is missing an id.");
+    if (attrs2.kind !== "insert" && attrs2.kind !== "delete" && attrs2.kind !== "replace") {
+      throw invalidReviewMarkdown(`Suggestion ${attrs2.id} has an invalid kind.`);
+    }
+    const bodyStart = startClose + 3;
+    const markerEnd = reviewMarkdown.indexOf(END_MARKER, bodyStart);
+    if (markerEnd === -1) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} is missing its closing marker.`);
+    const body = reviewMarkdown.slice(bodyStart, markerEnd);
+    if (body.includes(START_MARKER)) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} contains a nested suggestion.`);
+    const parsedBody = parseSuggestionBody(attrs2.kind, body, attrs2.id);
+    const token = {
+      id: attrs2.id,
+      kind: attrs2.kind,
+      form: parsedBody.before.includes("\n") || parsedBody.after.includes("\n") ? "block" : "inline",
+      author: actorFromAttributes(attrs2),
+      message: attrs2.message,
+      createdAt: attrs2.createdAt,
+      updatedAt: attrs2.updatedAt,
+      before: parsedBody.before,
+      after: parsedBody.after,
+      markerStart,
+      markerEnd: markerEnd + END_MARKER.length,
+      canonicalStart: canonicalOffset,
+      canonicalEnd: canonicalOffset + parsedBody.before.length,
+      raw: reviewMarkdown.slice(markerStart, markerEnd + END_MARKER.length)
+    };
+    segments.push({ type: "suggestion", token });
+    suggestions.push(token);
+    canonicalOffset += token.before.length;
+    cursor = token.markerEnd;
   }
-  return clusters;
-}
-function sideSlice(side, regions, lo, hi) {
-  return side.slice(lo + sideDeltaBefore(regions, lo, false), hi + sideDeltaBefore(regions, hi, true));
+  return {
+    reviewMarkdown,
+    canonicalMarkdown: canonicalFromSegments(segments, statusLookup(void 0)),
+    segments,
+    suggestions
+  };
 }
-function sideDeltaBefore(regions, basePos, includeInsertionAt) {
-  let delta = 0;
-  for (const region of regions) {
-    const end = region.baseStart + region.baseLength;
-    if (end > basePos) break;
-    if (end === basePos && region.baseLength === 0 && !includeInsertionAt) break;
-    delta += region.sideLength - region.baseLength;
+function projectCanonicalMarkdown(reviewMarkdown, sidecarStatuses) {
+  return canonicalFromSegments(parseReviewMarkdown(reviewMarkdown).segments, statusLookup(sidecarStatuses));
+}
+function deriveSidecarFromReviewMarkdown(sidecar, reviewMarkdown, options) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const existingSuggestions = new Map(sidecar.suggestions.map((suggestion) => [suggestion.id, suggestion]));
+  const existingAnchors = new Map(sidecar.anchors.map((anchor) => [anchor.id, anchor]));
+  const anchors = sidecar.anchors.filter((anchor) => anchor.kind !== "suggestion");
+  const suggestions = [];
+  const base = { contentHash: contentHashForText(parsed.canonicalMarkdown), ...options.baseHead ? { head: options.baseHead } : {} };
+  for (const token of parsed.suggestions) {
+    const existing = existingSuggestions.get(token.id);
+    const anchorId = existing?.anchorId ?? stableAnchorIdForSuggestion(token.id);
+    const range = lineRangeForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
+    const selector = selectorForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
+    const anchor = {
+      ...existingAnchors.get(anchorId) ?? {},
+      id: anchorId,
+      kind: "suggestion",
+      status: "mapped",
+      selector,
+      range,
+      confidence: 1,
+      updatedAt: now
+    };
+    const author = token.author ?? existing?.author ?? options.author;
+    const message = token.message ?? existing?.message ?? "Suggested edit";
+    const suggestion = {
+      ...existing ?? {},
+      id: token.id,
+      anchorId,
+      status: "open",
+      kind: token.kind,
+      author,
+      message,
+      patch: {
+        type: "replace_lines",
+        range,
+        before: token.before,
+        after: token.after
+      },
+      base: existing?.base ?? base,
+      diff: {
+        before: token.before,
+        after: token.after,
+        summary: diffSummary(token.before, token.after)
+      },
+      projectionStatus: "clean",
+      reviewRange: { start: token.markerStart, end: token.markerEnd },
+      createdAt: token.createdAt ?? existing?.createdAt ?? now,
+      updatedAt: token.updatedAt ?? now
+    };
+    anchors.push(anchor);
+    suggestions.push(suggestion);
   }
-  return delta;
-}
-function linesEqual(left, right) {
-  return left.length === right.length && left.every((line, index) => line === right[index]);
+  return {
+    ...sidecar,
+    reviewMarkdown,
+    anchors,
+    suggestions,
+    updatedAt: now
+  };
 }
-
-// ../core/src/patches.ts
-function applySuggestion(markdown, suggestion, input) {
-  if (suggestion.status !== "open") {
-    throw new MdocsError(
-      "validation_error",
-      `Suggestion ${suggestion.id} is not open (status: ${suggestion.status}).`,
-      "Only open suggestions can be applied. List open suggestions with the suggestions command."
-    );
-  }
-  const context = applySuggestionContext(input);
-  const baseResult = applySuggestionFromBase(markdown, suggestion, context.baseMarkdown);
-  if (baseResult.kind === "applied") return baseResult.markdown;
-  if (baseResult.kind === "conflict") {
+function createSuggestionMarkup(reviewMarkdown, patch, metadata) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  assertNoDuplicateSuggestionId(parsed, metadata.suggestionId);
+  const [contentStart, contentEnd] = lineRangeOffsets(parsed.canonicalMarkdown, patch.range);
+  const selected = parsed.canonicalMarkdown.slice(contentStart, contentEnd);
+  if (selected !== patch.before) {
     throw new MdocsError(
       "conflict",
-      `Suggestion ${suggestion.id} no longer applies cleanly: the document changed inside the suggested edit.`,
-      "Review the current text around the suggestion, then accept it manually or ask the agent for a fresh suggestion."
+      "Suggestion target does not match the review document projection.",
+      "Re-read the document and create the suggestion against the current canonical text."
     );
   }
-  const range = currentSuggestionRange(markdown, suggestion, context.anchor);
-  if (!range) {
+  const [canonicalStart, canonicalEnd] = lineRangeReplacementOffsets(parsed.canonicalMarkdown, patch.range);
+  if (selectionTouchesSuggestion(parsed.suggestions, canonicalStart, canonicalEnd)) {
     throw new MdocsError(
       "conflict",
-      `Suggestion ${suggestion.id} no longer applies cleanly: the document changed since it was created.`,
-      "Re-read the document, then create a fresh suggestion against the current content."
+      "Suggestion overlaps an unresolved suggestion.",
+      "Accept or reject the existing suggestion before creating another edit over the same text."
     );
   }
-  const next = replaceLineRange(markdown, range, suggestion.patch.after);
-  assertCleanMarkdown(next);
-  return next;
+  const rawStart = rawOffsetForCanonicalOffset(parsed.segments, canonicalStart);
+  const rawEnd = rawOffsetForCanonicalOffset(parsed.segments, canonicalEnd);
+  const before = parsed.canonicalMarkdown.slice(canonicalStart, canonicalEnd);
+  const after = replacementTextForSpan(parsed.canonicalMarkdown, patch, canonicalStart, canonicalEnd);
+  const marker = formatSuggestionMarker(metadata, kindForText(before, after), before, after);
+  const nextReviewMarkdown = `${reviewMarkdown.slice(0, rawStart)}${marker}${reviewMarkdown.slice(rawEnd)}`;
+  const token = parseReviewMarkdown(nextReviewMarkdown).suggestions.find((candidate) => candidate.id === metadata.suggestionId);
+  if (!token) throw invalidReviewMarkdown(`Failed to create suggestion ${metadata.suggestionId}.`);
+  return { reviewMarkdown: nextReviewMarkdown, token };
+}
+function projectReviewMarkdown(canonicalMarkdown, suggestions) {
+  let reviewMarkdown = canonicalMarkdown;
+  const open = suggestions.filter((suggestion) => suggestion.status === "open" && suggestion.patch?.type === "replace_lines").slice().sort((left, right) => left.patch.range.startLine - right.patch.range.startLine);
+  for (const suggestion of open) {
+    try {
+      reviewMarkdown = createSuggestionMarkup(reviewMarkdown, suggestion.patch, {
+        suggestionId: suggestion.id,
+        author: suggestion.author,
+        message: suggestion.message,
+        createdAt: suggestion.createdAt,
+        updatedAt: suggestion.updatedAt
+      }).reviewMarkdown;
+    } catch {
+    }
+  }
+  return reviewMarkdown;
 }
-function applySuggestionContext(input) {
-  if (!input) return {};
-  if ("selector" in input) return { anchor: input };
-  return input;
-}
-function applySuggestionFromBase(markdown, suggestion, baseMarkdown) {
-  if (!baseMarkdown || !suggestion.base?.contentHash) return { kind: "unavailable" };
-  if (contentHashForText(baseMarkdown) !== suggestion.base.contentHash) return { kind: "unavailable" };
-  if (!rangeIsWithin(baseMarkdown, suggestion.patch.range) || extractLineRange(baseMarkdown, suggestion.patch.range) !== suggestion.patch.before) {
-    return { kind: "conflict" };
-  }
-  const rebased = rebaseSuggestionPatch(baseMarkdown, markdown, suggestion);
-  if (rebased !== void 0) return { kind: "applied", markdown: rebased };
-  const suggestedMarkdown = replaceLineRange(baseMarkdown, suggestion.patch.range, suggestion.patch.after);
-  assertCleanMarkdown(suggestedMarkdown);
-  const merged = mergeText(baseMarkdown, markdown, suggestedMarkdown);
-  if (!merged.ok) return { kind: "conflict" };
-  assertCleanMarkdown(merged.text);
-  return { kind: "applied", markdown: merged.text };
-}
-function rebaseSuggestionPatch(baseMarkdown, markdown, suggestion) {
-  const baseLines = getLines(baseMarkdown);
-  const currentLines = getLines(markdown);
-  let regions;
-  try {
-    regions = diffTextRegions(baseLines, currentLines);
-  } catch {
-    return void 0;
+function resolveSuggestionMarkup(reviewMarkdown, suggestionId, resolution) {
+  const parsed = parseReviewMarkdown(reviewMarkdown);
+  const token = parsed.suggestions.find((candidate) => candidate.id === suggestionId);
+  if (!token) {
+    throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "Refresh review state and try again.");
   }
-  const baseStart = suggestion.patch.range.startLine - 1;
-  const baseEnd = suggestion.patch.range.endLine;
-  if (regions.some((region) => regionTouchesSuggestionRange(region, baseStart, baseEnd))) return void 0;
-  const currentStart = baseStart + sideDeltaBefore(regions, baseStart, true);
-  const currentEnd = baseEnd + sideDeltaBefore(regions, baseEnd, false);
-  const currentRange = { startLine: currentStart + 1, endLine: currentEnd };
-  if (!rangeIsWithin(markdown, currentRange)) return void 0;
-  if (extractLineRange(markdown, currentRange) !== suggestion.patch.before) return void 0;
-  const next = replaceLineRange(markdown, currentRange, suggestion.patch.after);
-  assertCleanMarkdown(next);
-  return next;
+  const resolved = resolutionText(token, resolution);
+  return `${reviewMarkdown.slice(0, token.markerStart)}${resolved}${reviewMarkdown.slice(token.markerEnd)}`;
 }
-function regionTouchesSuggestionRange(region, baseStart, baseEnd) {
-  if (region.baseLength === 0) return region.baseStart > baseStart && region.baseStart < baseEnd;
-  const regionEnd = region.baseStart + region.baseLength;
-  return region.baseStart < baseEnd && regionEnd > baseStart;
-}
-function currentSuggestionRange(markdown, suggestion, anchor) {
-  const anchoredRange = currentAnchorRange(markdown, suggestion, anchor);
-  if (anchoredRange) return anchoredRange;
-  if (anchor && !anchorIsReliable(anchor)) return void 0;
-  const hintedRange = suggestion.patch.range;
-  if (rangeIsWithin(markdown, hintedRange) && extractLineRange(markdown, hintedRange) === suggestion.patch.before) return hintedRange;
-  const candidates = findBeforeCandidates(markdown, suggestion.patch.before);
-  if (candidates.length === 0) return void 0;
-  if (candidates.length === 1) return candidates[0];
-  if (!anchor) return void 0;
-  const scored = candidates.map((range) => ({ range, score: scoreContext2(markdown, range, anchor) })).sort((left, right) => right.score - left.score);
-  const best = scored[0];
-  if (!best) return void 0;
-  const tied = scored.filter((candidate) => candidate.score === best.score);
-  if (tied.length > 1) return void 0;
-  if (best.score < 0.7) return void 0;
-  return best.range;
+function escapeReviewSuggestionText(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll("{++", "\\{++").replaceAll("++}", "\\++}").replaceAll("{--", "\\{--").replaceAll("--}", "\\--}").replaceAll("{~~", "\\{~~").replaceAll("~>", "\\~>").replaceAll("~~}", "\\~~}");
 }
-function currentAnchorRange(markdown, suggestion, anchor) {
-  if (!anchor || !anchorIsReliable(anchor) || !anchor.range) return void 0;
-  if (!rangeIsWithin(markdown, anchor.range)) return void 0;
-  return extractLineRange(markdown, anchor.range) === suggestion.patch.before ? anchor.range : void 0;
+function lineRangeForCanonicalSpan(markdown, start, end) {
+  assertCanonicalSpan(markdown, start, end);
+  return lineRangeForOffsets(markdown, start, end);
 }
-function anchorIsReliable(anchor) {
-  return anchor.status === "mapped" && anchor.confidence >= 0.65;
+function selectorForCanonicalSpan(markdown, start, end) {
+  assertCanonicalSpan(markdown, start, end);
+  const context = 160;
+  const prefix = markdown.slice(Math.max(0, start - context), start);
+  const suffix = markdown.slice(end, Math.min(markdown.length, end + context));
+  return {
+    quote: markdown.slice(start, end),
+    ...prefix ? { prefix } : {},
+    ...suffix ? { suffix } : {}
+  };
 }
-function findBeforeCandidates(markdown, before) {
-  const lines = getLines(markdown);
-  const beforeLines = linePattern(before);
-  if (beforeLines.length === 0 || beforeLines.length > lines.length) return [];
-  const ranges = [];
-  const beforeText = beforeLines.join("\n");
-  for (let index = 0; index <= lines.length - beforeLines.length; index += 1) {
-    if (lines.slice(index, index + beforeLines.length).join("\n") === beforeText) {
-      ranges.push({ startLine: index + 1, endLine: index + beforeLines.length });
+function appendTextSegment(source, segments, start, end, canonicalStart) {
+  if (end <= start) return;
+  segments.push({
+    type: "text",
+    text: source.slice(start, end),
+    start,
+    end,
+    canonicalStart,
+    canonicalEnd: canonicalStart + (end - start)
+  });
+}
+function canonicalFromSegments(segments, statuses) {
+  return segments.map((segment) => {
+    if (segment.type === "text") return segment.text;
+    const status = statuses(segment.token.id);
+    if (status === "accepted") return acceptedText(segment.token);
+    return originalText(segment.token);
+  }).join("");
+}
+function parseMarkerAttributes(raw) {
+  const attrs2 = {};
+  const pattern = /\s+([a-zA-Z][\w:-]*)="([^"]*)"/g;
+  let match2;
+  while ((match2 = pattern.exec(raw)) !== null) {
+    const key = match2[1];
+    if (key === "id" || key === "kind" || key === "authorId" || key === "authorKind" || key === "authorName" || key === "authorEmail" || key === "message" || key === "createdAt" || key === "updatedAt") {
+      attrs2[key] = decodeAttribute(match2[2] ?? "");
     }
   }
-  return ranges;
+  return attrs2;
 }
-function rangeIsWithin(markdown, range) {
-  const lineCount = getLines(markdown).length;
-  return range.startLine >= 1 && range.endLine >= range.startLine && range.endLine <= lineCount;
+function actorFromAttributes(attrs2) {
+  if (!attrs2.authorId || !attrs2.authorName) return void 0;
+  const kind = attrs2.authorKind === "agent" || attrs2.authorKind === "system" || attrs2.authorKind === "human" ? attrs2.authorKind : "human";
+  return {
+    id: attrs2.authorId,
+    kind,
+    name: attrs2.authorName,
+    ...attrs2.authorEmail ? { email: attrs2.authorEmail } : {}
+  };
+}
+function parseSuggestionBody(kind, body, id) {
+  if (kind === "insert") {
+    return { before: "", after: parseWrappedBody(body, "{++", "++}", id) };
+  }
+  if (kind === "delete") {
+    return { before: parseWrappedBody(body, "{--", "--}", id), after: "" };
+  }
+  if (!body.startsWith("{~~") || !body.endsWith("~~}")) {
+    throw invalidReviewMarkdown(`Replacement suggestion ${id} has invalid CriticMarkup payload.`);
+  }
+  const inner = body.slice(3, -3);
+  const separator = findUnescaped2(inner, "~>");
+  if (separator === -1) throw invalidReviewMarkdown(`Replacement suggestion ${id} is missing a separator.`);
+  return {
+    before: unescapeReviewSuggestionText(inner.slice(0, separator)),
+    after: unescapeReviewSuggestionText(inner.slice(separator + 2))
+  };
+}
+function parseWrappedBody(body, open, close2, id) {
+  if (!body.startsWith(open) || !body.endsWith(close2) || isEscapedAt(body, body.length - close2.length)) {
+    throw invalidReviewMarkdown(`Suggestion ${id} has invalid CriticMarkup payload.`);
+  }
+  return unescapeReviewSuggestionText(body.slice(open.length, -close2.length));
+}
+function formatSuggestionMarker(metadata, kind, before, after) {
+  const attrs2 = [
+    ["id", metadata.suggestionId],
+    ["kind", kind]
+  ];
+  if (metadata.author) {
+    attrs2.push(["authorId", metadata.author.id]);
+    attrs2.push(["authorKind", metadata.author.kind]);
+    attrs2.push(["authorName", metadata.author.name]);
+    if (metadata.author.email) attrs2.push(["authorEmail", metadata.author.email]);
+  }
+  if (metadata.message) attrs2.push(["message", metadata.message]);
+  if (metadata.createdAt) attrs2.push(["createdAt", metadata.createdAt]);
+  if (metadata.updatedAt) attrs2.push(["updatedAt", metadata.updatedAt]);
+  const attrText = attrs2.map(([key, value]) => `${key}="${encodeAttribute(value)}"`).join(" ");
+  const body = kind === "insert" ? `{++${escapeReviewSuggestionText(after)}++}` : kind === "delete" ? `{--${escapeReviewSuggestionText(before)}--}` : `{~~${escapeReviewSuggestionText(before)}~>${escapeReviewSuggestionText(after)}~~}`;
+  return `${START_MARKER} ${attrText} -->${body}${END_MARKER}`;
+}
+function stableAnchorIdForSuggestion(suggestionId) {
+  return `anchor_${suggestionId.replace(/[^a-zA-Z0-9_:-]/g, "_")}`;
+}
+function diffSummary(before, after) {
+  if (!before && after) return "Inserted text";
+  if (before && !after) return "Deleted text";
+  return "Replaced text";
+}
+function unescapeReviewSuggestionText(value) {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    if (value[index] !== "\\") {
+      result += value[index];
+      continue;
+    }
+    const next = value[index + 1];
+    if (next === void 0) {
+      result += "\\";
+      continue;
+    }
+    result += next;
+    index += 1;
+  }
+  return result;
 }
-function linePattern(value) {
-  return value.replace(/\r\n?/g, "\n").split("\n");
+function findUnescaped2(value, needle, from = 0) {
+  let index = value.indexOf(needle, from);
+  while (index !== -1) {
+    if (!isEscapedAt(value, index)) return index;
+    index = value.indexOf(needle, index + needle.length);
+  }
+  return -1;
+}
+function isEscapedAt(value, index) {
+  let slashes = 0;
+  for (let cursor = index - 1; cursor >= 0 && value[cursor] === "\\"; cursor -= 1) slashes += 1;
+  return slashes % 2 === 1;
 }
-function scoreContext2(markdown, range, anchor) {
+function statusLookup(statuses) {
+  if (!statuses) return () => "open";
+  if (isStatusMap(statuses)) return (suggestionId) => statuses.get(suggestionId) ?? "open";
+  if (Array.isArray(statuses)) {
+    const map = /* @__PURE__ */ new Map();
+    for (const item of statuses) {
+      const id = item.id ?? item.suggestionId;
+      if (id && item.status) map.set(id, item.status);
+    }
+    return (suggestionId) => map.get(suggestionId) ?? "open";
+  }
+  const record = statuses;
+  return (suggestionId) => record[suggestionId] ?? "open";
+}
+function isStatusMap(value) {
+  return typeof value.get === "function";
+}
+function acceptedText(token) {
+  return token.kind === "delete" ? "" : token.after;
+}
+function originalText(token) {
+  return token.kind === "insert" ? "" : token.before;
+}
+function resolutionText(token, resolution) {
+  return resolution === "accept" ? acceptedText(token) : originalText(token);
+}
+function kindForText(before, after) {
+  if (before.length === 0) return "insert";
+  if (after.length === 0) return "delete";
+  return "replace";
+}
+function assertNoDuplicateSuggestionId(parsed, suggestionId) {
+  if (parsed.suggestions.some((suggestion) => suggestion.id === suggestionId)) {
+    throw new MdocsError("validation_error", `Duplicate suggestion id: ${suggestionId}`, "Suggestion ids must be stable and unique per document.");
+  }
+}
+function assertCanonicalSpan(markdown, start, end) {
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > markdown.length) {
+    throw new MdocsError("invalid_range", `Invalid canonical span ${start}:${end}.`, "Re-read the document and try again.");
+  }
+}
+function selectionTouchesSuggestion(tokens, start, end) {
+  return tokens.some((token) => {
+    if (token.canonicalStart === token.canonicalEnd) return start <= token.canonicalStart && end >= token.canonicalEnd;
+    return start < token.canonicalEnd && end > token.canonicalStart;
+  });
+}
+function rawOffsetForCanonicalOffset(segments, offset) {
+  for (const segment of segments) {
+    if (segment.type === "text") {
+      if (offset >= segment.canonicalStart && offset <= segment.canonicalEnd) {
+        return segment.start + (offset - segment.canonicalStart);
+      }
+      continue;
+    }
+    const token = segment.token;
+    if (offset > token.canonicalStart && offset < token.canonicalEnd) {
+      throw new MdocsError(
+        "conflict",
+        "Selection falls inside an unresolved suggestion.",
+        "Accept or reject the existing suggestion before editing inside it."
+      );
+    }
+  }
+  if (offset === segmentsEndCanonicalOffset(segments)) return segmentsEndRawOffset(segments);
+  throw new MdocsError("invalid_range", "Could not map canonical offset into review Markdown.", "Re-read the document and try again.");
+}
+function segmentsEndCanonicalOffset(segments) {
+  const last = segments[segments.length - 1];
+  if (!last) return 0;
+  return last.type === "text" ? last.canonicalEnd : last.token.canonicalEnd;
+}
+function segmentsEndRawOffset(segments) {
+  const last = segments[segments.length - 1];
+  if (!last) return 0;
+  return last.type === "text" ? last.end : last.token.markerEnd;
+}
+function lineRangeOffsets(markdown, range) {
   const lines = getLines(markdown);
-  let score = anchor.selector.quote === extractLineRange(markdown, range) ? 0.7 : 0.65;
-  const expectedPrefix = contextPrefix2(anchor.selector.prefix);
-  if (expectedPrefix) {
-    const actualPrefix = contextPrefix2(lines.slice(Math.max(0, range.startLine - 4), range.startLine - 1).join("\n"));
-    if (actualPrefix?.endsWith(expectedPrefix)) score += 0.15;
+  if (range.startLine < 1 || range.endLine < range.startLine || range.endLine > lines.length) {
+    throw new MdocsError("invalid_range", `Invalid line range ${range.startLine}:${range.endLine}.`, "Re-read the document and try again.");
   }
-  const expectedSuffix = contextSuffix2(anchor.selector.suffix);
-  if (expectedSuffix) {
-    const actualSuffix = contextSuffix2(lines.slice(range.endLine, range.endLine + 3).join("\n"));
-    if (actualSuffix?.startsWith(expectedSuffix)) score += 0.15;
+  let start = 0;
+  for (let index = 0; index < range.startLine - 1; index += 1) start += lines[index].length + 1;
+  let end = start;
+  for (let index = range.startLine - 1; index < range.endLine; index += 1) {
+    if (index > range.startLine - 1) end += 1;
+    end += lines[index].length;
+  }
+  return [start, end];
+}
+function lineRangeReplacementOffsets(markdown, range) {
+  const [start, contentEnd] = lineRangeOffsets(markdown, range);
+  if (contentEnd < markdown.length && markdown[contentEnd] === "\n") return [start, contentEnd + 1];
+  return [start, contentEnd];
+}
+function replacementTextForSpan(markdown, patch, start, end) {
+  const applied = replaceLineRange(markdown, patch.range, patch.after);
+  const suffixLength = markdown.length - end;
+  const replacementEnd = applied.length - suffixLength;
+  if (replacementEnd < start) return "";
+  return applied.slice(start, replacementEnd);
+}
+function lineRangeForOffsets(markdown, start, end) {
+  const starts = lineStarts(markdown);
+  return {
+    startLine: lineNumberAt(starts, start),
+    endLine: lineNumberAt(starts, Math.max(start, end - 1))
+  };
+}
+function lineStarts(markdown) {
+  const starts = [0];
+  for (let index = 0; index < markdown.length; index += 1) {
+    if (markdown[index] === "\n") starts.push(index + 1);
   }
-  return Math.min(1, score);
+  return starts;
 }
-function contextPrefix2(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(-3).join("\n") || void 0;
+function lineNumberAt(starts, offset) {
+  let line = 1;
+  for (let index = 0; index < starts.length; index += 1) {
+    if (starts[index] <= offset) line = index + 1;
+    else break;
+  }
+  return line;
+}
+function encodeAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function decodeAttribute(value) {
+  return value.replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
 }
-function contextSuffix2(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") || void 0;
+function invalidReviewMarkdown(message) {
+  return new MdocsError("validation_error", `Invalid review Markdown: ${message}`, "Repair or remove the malformed suggestion markup.");
 }
 
 // ../core/src/graph.ts
@@ -1547,6 +1733,7 @@ async function getDocumentState(io, pathOrDocId) {
     path: entry.path,
     title: entry.title,
     markdown,
+    reviewMarkdown: nextSidecar.reviewMarkdown ?? markdown,
     sidecar: nextSidecar,
     anchors: remappedAnchors.map((anchor) => ({
       id: anchor.id,
@@ -1634,6 +1821,7 @@ async function addSuggestion(io, pathOrDocId, range, replacement, message, autho
     id: createId("suggestion"),
     anchorId: anchor.id,
     status: "open",
+    kind: replacement.length === 0 ? "delete" : before.length === 0 ? "insert" : "replace",
     author,
     message,
     patch: {
@@ -1650,53 +1838,72 @@ async function addSuggestion(io, pathOrDocId, range, replacement, message, autho
     createdAt: now,
     updatedAt: now
   };
-  await writeSidecar(io, {
-    ...state.sidecar,
-    anchors: [...state.sidecar.anchors, anchor],
-    suggestions: [...state.sidecar.suggestions, suggestion],
+  const review = createSuggestionMarkup(state.sidecar.reviewMarkdown ?? state.markdown, suggestion.patch, {
+    suggestionId: suggestion.id,
+    author,
+    message,
+    createdAt: now,
     updatedAt: now
   });
-  return suggestion;
+  const nextSidecar = deriveSidecarFromReviewMarkdown(
+    { ...state.sidecar, reviewMarkdown: review.reviewMarkdown, anchors: [...state.sidecar.anchors, anchor] },
+    review.reviewMarkdown,
+    { author, baseHead: entry?.currentSha, now }
+  );
+  await writeSidecar(io, nextSidecar);
+  const enriched = nextSidecar.suggestions.find((candidate) => candidate.id === suggestion.id);
+  if (!enriched) throw new MdocsError("validation_error", `Could not derive suggestion ${suggestion.id}.`, "Refresh review state and try again.");
+  return enriched;
 }
-async function updateSuggestionStatus(io, suggestionId, status, actor = defaultActor()) {
+async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
   for (const entry of manifest.docs) {
+    const markdown = await io.readText(entry.path);
     const sidecar = await readSidecar(io, entry.docId);
     const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     if (!suggestion) continue;
     const now = nowIso();
-    const updated = {
-      ...suggestion,
-      status,
-      updatedAt: now,
-      resolvedAt: now,
-      resolvedBy: actor
-    };
-    await writeSidecar(io, {
-      ...sidecar,
-      suggestions: sidecar.suggestions.map((candidate) => candidate.id === suggestionId ? updated : candidate),
-      updatedAt: now
-    });
-    return updated;
+    const reviewMarkdown = sidecar.reviewMarkdown ?? markdown;
+    const resolvedReviewMarkdown = resolveSuggestionMarkup(reviewMarkdown, suggestionId, "accept");
+    const nextMarkdown = projectCanonicalMarkdown(resolvedReviewMarkdown);
+    assertCleanMarkdown(nextMarkdown);
+    const nextSidecar = deriveSidecarFromReviewMarkdown(
+      { ...sidecar, reviewMarkdown: resolvedReviewMarkdown },
+      resolvedReviewMarkdown,
+      { author: suggestion.author, baseHead: entry.currentSha, now }
+    );
+    await io.writeText(entry.path, nextMarkdown);
+    await writeSidecar(io, nextSidecar);
+    return resolvedSuggestion(suggestion, "accepted", actor, now);
   }
   throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
 }
-async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
+async function rejectSuggestion(io, suggestionId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
   for (const entry of manifest.docs) {
-    const markdown = await io.readText(entry.path);
     const sidecar = await readSidecar(io, entry.docId);
     const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
     if (!suggestion) continue;
-    const anchor = sidecar.anchors.find((candidate) => candidate.id === suggestion.anchorId);
-    const nextMarkdown = applySuggestion(markdown, suggestion, anchor);
-    await io.writeText(entry.path, nextMarkdown);
-    return updateSuggestionStatus(io, suggestionId, "accepted", actor);
+    const now = nowIso();
+    const updated = resolvedSuggestion(suggestion, "rejected", actor, now);
+    const reviewMarkdown = resolveSuggestionMarkup(sidecar.reviewMarkdown ?? "", suggestionId, "reject");
+    const nextSidecar = deriveSidecarFromReviewMarkdown({ ...sidecar, reviewMarkdown }, reviewMarkdown, {
+      author: suggestion.author,
+      now
+    });
+    await writeSidecar(io, nextSidecar);
+    return updated;
   }
   throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
 }
-async function rejectSuggestion(io, suggestionId, actor = defaultActor()) {
-  return updateSuggestionStatus(io, suggestionId, "rejected", actor);
+function resolvedSuggestion(suggestion, status, actor, now) {
+  return {
+    ...suggestion,
+    status,
+    updatedAt: now,
+    resolvedAt: now,
+    resolvedBy: actor
+  };
 }
 async function resolveComment(io, commentId, actor = defaultActor()) {
   const manifest = await indexWorkspace(io);
@@ -11056,7 +11263,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.13";
+var CLI_VERSION = "0.3.17";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11233,7 +11440,7 @@ var AGENT_COMMANDS = [
   },
   {
     name: "suggest",
-    summary: "Create a sidecar replacement suggestion without modifying clean Markdown.",
+    summary: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown.",
     usage: "mdocs suggest <path|docId> --range <start:end> --with <markdown> --message <text> --json",
     output: "json",
     mutates: true,
@@ -11343,20 +11550,39 @@ var AGENT_COMMANDS = [
   {
     name: "bridge resume",
     summary: "Backfill missed Magic changes after an agent restart, then keep the bridge running.",
-    usage: "mdocs bridge resume --root <path> [--url <base-url>] [--workspace <id>] [--root-id <id>] [--request-token] [--once]",
+    usage: "mdocs bridge resume --root <path> [--url <base-url>] [--workspace <id>] [--root-id <id>] [--request-token] [--forever] [--once]",
     output: "long-running",
     mutates: true,
     examples: [
-      "mdocs bridge resume --root . --request-token",
+      "mdocs bridge resume --root . --forever --request-token",
       "mdocs bridge resume --root . --once --request-token"
     ],
     notes: [
       "Reads non-secret connection defaults from .mdocs/bridge.json written by bridge setup.",
       "Use this after a sandbox/container/agent session restarts. It backfills canonical Magic changes before publishing local edits.",
+      "--forever is the intended startup/sandbox command: keep it running for live collaboration and liveness heartbeats.",
       "--request-token opens a human approval URL when no MDOCS_BRIDGE_TOKEN is available; do not ask users to paste bridge tokens by default.",
       "--once performs only the backfill/reconcile step and exits."
     ]
   },
+  {
+    name: "bridge startup",
+    summary: "Write a bridge runner and optional launchd/systemd startup hook for long-lived bridge environments.",
+    usage: "mdocs bridge startup --root <path> [--mode auto|shell|launchd|systemd] [--install] [--json]",
+    output: "json",
+    mutates: true,
+    examples: [
+      "mdocs bridge startup --root . --json",
+      "mdocs bridge startup --root . --mode shell --json",
+      "mdocs bridge startup --root . --mode systemd --install --json"
+    ],
+    notes: [
+      "Run this after bridge setup has written .mdocs/bridge.json.",
+      "Sandbox providers should put the returned startupCommand in their on-start hook.",
+      "--install installs and starts the generated launchd/systemd user service when the host supports it.",
+      "The generated runner stores no bridge token; provide MDOCS_BRIDGE_TOKEN through platform secrets if you use manual tokens."
+    ]
+  },
   {
     name: "bridge",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
@@ -11424,7 +11650,7 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 4. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --summary --json\` instead. Project-scoped joins cover one root; workspace-scoped joins cover Home and can target duplicate paths as \`<rootId>:<path-or-docId>\`.
 5. Run \`mdocs graph --json\` or project-scoped \`mdocs remote graph --json\` before broad edits to inspect the Obsidian-style document graph built from Markdown links and wikilinks.
 6. For a document, run \`mdocs context <path|docId> --summary --json\` locally or \`mdocs remote context <path|docId> --summary --json\` for a joined share before reading full content. Then page Markdown with \`--start-line\` / \`--end-line\` and \`--no-review\` when you only need document text.
-7. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
+7. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not hand-edit canonical Markdown files or \`.mdocs\` reviewMarkdown syntax directly.
 
 ## Filesystem Bridge / Resume
 
@@ -11445,16 +11671,24 @@ Return the Magic approval link and keep the bridge process running after approva
 If your sandbox, container, terminal, or agent session restarts after setup, do not ask for a raw bridge token. Start the latest CLI again and resume from the same root:
 
 \`\`\`bash
-npx --yes --package=@magic-markdown/cli@latest mdocs bridge resume --root . --request-token
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge resume --root . --forever --request-token
 \`\`\`
 
-\`bridge resume\` reads non-secret defaults from \`.mdocs/bridge.json\`, backfills missed Magic changes before publishing local edits, and then keeps polling/watching. Use \`--once\` only when the user asked for a one-shot backfill rather than a live bridge.
+\`bridge resume --forever\` reads non-secret defaults from \`.mdocs/bridge.json\`, backfills missed Magic changes before publishing local edits, and then keeps polling/watching with liveness heartbeats. Use \`--once\` only when the user asked for a one-shot backfill rather than a live bridge.
+
+For sandboxes, VPSs, or local machines that support startup hooks, generate a durable runner after setup:
+
+\`\`\`bash
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge startup --root . --json
+\`\`\`
+
+Put the returned \`startupCommand\` into the provider's on-start hook. On local macOS or systemd Linux hosts, \`mdocs bridge startup --root . --install\` writes and starts a user service. The generated runner stores no bridge token; use platform secrets for \`MDOCS_BRIDGE_TOKEN\` if you manage tokens manually.
 
 If Magic and the local root both changed the same document while you were offline, the bridge keeps the Magic canonical path, saves your local divergent version as a \`.conflict-...\` Markdown copy, and lets the conflict copy sync as a normal file. If Magic reports a server-side conflict, wait for the human to resolve it in Magic Markdown before retrying content pushes.
 
 ## Editing Rules
 
-- Comments and suggestions are sidecar operations. They should not modify clean Markdown until a suggestion is accepted.
+- Comments are sidecar operations; suggestions are reviewMarkdown operations derived into sidecar state. They should not modify canonical Markdown until a suggestion is accepted.
 - \`--range <start:end>\` is 1-based and inclusive, and validated against the current document: read the document first and quote line numbers from what you just read.
 - Prefer the smallest coherent suggestion range that contains the actual change. If one sentence, list item, table row, or short paragraph changes, suggest that unit rather than replacing surrounding unchanged paragraphs or sections.
 - Broader paragraph, section, or multi-section rewrites are appropriate when the edit genuinely changes structure, ordering, transitions, or multiple interdependent ideas. Do not avoid a long edit when it is the clearest correct revision.
@@ -12085,7 +12319,7 @@ var tools = [
   },
   {
     name: "mdocs_suggest",
-    description: "Create a sidecar replacement suggestion without modifying clean Markdown. Prefer the smallest coherent range; use longer ranges only when the broader rewrite is genuinely needed.",
+    description: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown. Prefer the smallest coherent range; use longer ranges only when the broader rewrite is genuinely needed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -12842,7 +13076,6 @@ function joinStoreDir(root) {
 }
 
 // src/remote.ts
-var PUSH_REBASE_ATTEMPTS = 3;
 async function runJoinCommand(root, parsed) {
   const target = parsed.command[1];
   const existingId = typeof parsed.flags.id === "string" ? parsed.flags.id : void 0;
@@ -13172,6 +13405,7 @@ async function remoteCreateFile(root, record, parsed) {
     path: normalizedPath,
     title,
     markdown,
+    reviewMarkdown: markdown,
     sidecar,
     anchors: [],
     images: [],
@@ -13238,7 +13472,7 @@ async function remoteSuggest(root, record, parsed) {
   const result = await postReviewOperation(
     documentRecord,
     document.docId,
-    { kind: "create_suggestion", payload: { ...range, replacement, message } },
+    { kind: "create_suggestion", baseHead: document.currentSha, payload: { ...range, replacement, message } },
     actorForRecord(record)
   );
   if (result.document) await recordHead(root, record, result.document);
@@ -13333,44 +13567,14 @@ async function remoteReject(root, record, parsed) {
       hint: "Only open suggestions can be rejected."
     });
   }
-  try {
-    const additions = { anchors: [], comments: [], suggestions: [], withdrawSuggestionIds: [suggestionId] };
-    const pushed = await postReview(documentRecord, document.docId, additions, actor);
-    await recordHead(root, record, pushed);
-    const updated = pushed.sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
-    return { suggestion: updated ?? suggestion, document: pushed };
-  } catch (error) {
-    if (!isWithdrawalUnsupported(error)) throw error;
-  }
-  if (suggestion.author.id !== actor.id) {
-    throw new CliError("unauthorized", "You can only withdraw your own suggestions; rejecting another author's requires edit access.", {
-      hint: "Ask a human collaborator to reject it from the editor."
-    });
-  }
-  for (let index = 0; index < PUSH_REBASE_ATTEMPTS; index += 1) {
-    if (index > 0) document = await fetchDocument(record, document.docId);
-    documentRecord = rootScopedRecordFor(record, document.rootId);
-    const io = new RemoteDocumentIO(document);
-    const rejected = await rejectSuggestion(io, suggestionId, actor);
-    const state = await getDocumentState(io, document.docId);
-    try {
-      const pushed = await pushDocument(documentRecord, document, state.markdown, state.sidecar);
-      await recordHead(root, record, pushed);
-      return { suggestion: rejected, document: pushed };
-    } catch (error) {
-      const conflicted = isCliError(error) && error.code === "conflict";
-      if (!conflicted || index === PUSH_REBASE_ATTEMPTS - 1) throw error;
-    }
-  }
-  throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
-  });
-}
-function isWithdrawalUnsupported(error) {
-  if (isReviewEndpointUnsupported(error)) return true;
-  if (!isCliError(error)) return false;
-  const details = error.details ?? {};
-  return details.error === "empty_review";
+  const result = await postReviewOperation(
+    documentRecord,
+    document.docId,
+    { kind: "reject_suggestion", baseHead: document.currentSha, payload: { suggestionId } },
+    actor
+  );
+  if (result.document) await recordHead(root, record, result.document);
+  return { suggestion: result.suggestion ?? { ...suggestion, status: "rejected" }, reviewRecord: result.reviewRecord, document: result.document };
 }
 async function submitReview(root, record, pathOrDocId, mutate) {
   if (!pathOrDocId) {
@@ -13391,43 +13595,14 @@ async function submitReview(root, record, pathOrDocId, mutate) {
       additions: {
         anchors: state.sidecar.anchors.filter((anchor) => anchor.id === created.anchorId),
         comments: state.sidecar.comments.filter((comment2) => comment2.id === created.id),
-        suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.id === created.id)
+        reviewMarkdown: state.sidecar.reviewMarkdown
       }
     };
   };
-  let attempt = await build(document);
-  try {
-    const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
-    await recordHead(root, record, pushed);
-    return { created: attempt.created, document: pushed };
-  } catch (error) {
-    if (!isReviewEndpointUnsupported(error)) throw error;
-  }
-  for (let index = 0; index < PUSH_REBASE_ATTEMPTS; index += 1) {
-    if (index > 0) {
-      document = await fetchDocument(record, document.docId);
-      documentRecord = rootScopedRecordFor(record, document.rootId);
-      attempt = await build(document);
-    }
-    try {
-      const pushed = await pushDocument(documentRecord, document, attempt.state.markdown, attempt.state.sidecar);
-      await recordHead(root, record, pushed);
-      return { created: attempt.created, document: pushed };
-    } catch (error) {
-      const conflicted = isCliError(error) && error.code === "conflict";
-      if (!conflicted || index === PUSH_REBASE_ATTEMPTS - 1) throw error;
-    }
-  }
-  throw new CliError("conflict", "Remote change was not accepted after retries.", {
-    hint: "The document is changing rapidly. Refetch with mdocs remote context --summary --json, then retry against the needed content range."
-  });
-}
-function isReviewEndpointUnsupported(error) {
-  if (!isCliError(error)) return false;
-  if (error.code === "unauthorized") return true;
-  if (error.code !== "not_found") return false;
-  const details = error.details ?? {};
-  return details.error !== "document_not_found";
+  const attempt = await build(document);
+  const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
+  await recordHead(root, record, pushed);
+  return { created: attempt.created, document: pushed };
 }
 async function recordHead(root, record, document) {
   await writeJoinRecord(root, { ...record, updatedAt: (/* @__PURE__ */ new Date()).toISOString(), currentHead: document.currentSha });
@@ -13602,6 +13777,8 @@ function optionalFolderTarget(value) {
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
 import { basename as basename2, resolve as resolve4 } from "node:path";
 var BRIDGE_CONFIG_PATH = ".mdocs/bridge.json";
+var BRIDGE_STATUS_PATH = ".mdocs/bridge-status.json";
+var BRIDGE_HEARTBEAT_INTERVAL_MS = 1e4;
 function bridgeSetupIdentity(input) {
   const actorName = input.actorName?.trim() || "Agent";
   return {
@@ -13667,9 +13844,11 @@ async function runBridgeResume(options) {
 }
 async function runBridge(options) {
   const root = resolve4(options.root);
+  if (options.once && options.forever) {
+    throw new Error("Use either --once or --forever, not both.");
+  }
   const localManifestSource = await readLocalSource(root);
   const rootId = options.rootId ?? options.sourceId ?? localManifestSource?.sourceId ?? rootIdForPath(root);
-  const token = options.token ?? (options.requestToken ? await requestBridgeToken(options, rootId) : void 0);
   const replicaId = `replica_${createHash2("sha256").update(`${root}:${options.actorId}`).digest("hex").slice(0, 12)}`;
   const replicaKind = actorKindForBridge(options.actorId) === "agent" ? "agent_runtime" : "local";
   const mapping = createSourceMapping({
@@ -13692,7 +13871,29 @@ async function runBridge(options) {
   const claimMode = Boolean(options.claimToken || localManifestSource?.canonicalHead);
   let lastAppliedHead = localManifestSource?.canonicalHead;
   let socket;
-  const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
+  let lastSuccessfulSyncAt;
+  let lastHeartbeatAt;
+  let lastHeartbeatSentMs = 0;
+  let lastError;
+  await writeCurrentBridgeStatus("starting");
+  let token = options.token;
+  if (!token && options.requestToken) {
+    try {
+      token = await requestBridgeToken(options, rootId);
+    } catch (error) {
+      lastError = errorMessage(error);
+      await writeCurrentBridgeStatus("error");
+      throw error;
+    }
+  }
+  let registeredRoot;
+  try {
+    registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
+  } catch (error) {
+    lastError = errorMessage(error);
+    await writeCurrentBridgeStatus("error");
+    throw error;
+  }
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
   await writeBridgeConfig(root, {
@@ -13710,20 +13911,30 @@ async function runBridge(options) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   const backfilled = await resumeFromCanonical();
-  if (options.once) return;
+  if (options.once) {
+    lastSuccessfulSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+    await writeCurrentBridgeStatus("once_complete");
+    return;
+  }
   connect();
   if (claimMode && !backfilled) await primeLocalSignatures();
   else await publishSnapshot("initial");
   const timer = setInterval(() => {
     void publishSnapshot("poll").catch((error) => {
-      process.stderr.write(`bridge poll failed: ${error instanceof Error ? error.message : String(error)}
+      lastError = errorMessage(error);
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
+      sendHeartbeat("error", lastError);
+      process.stderr.write(`bridge poll failed: ${lastError}
 `);
     });
   }, options.intervalMs);
-  process.on("SIGINT", () => {
+  process.once("SIGINT", () => {
     clearInterval(timer);
-    socket?.close();
-    process.exit(0);
+    sendHeartbeat("offline", void 0, false);
+    void writeCurrentBridgeStatus("stopped").catch(() => void 0).finally(() => {
+      socket?.close();
+      process.exit(0);
+    });
   });
   await new Promise(() => void 0);
   function connect() {
@@ -13734,8 +13945,11 @@ async function runBridge(options) {
     if (token) url.searchParams.set("token", token);
     socket = new WebSocket(url);
     socket.addEventListener("open", () => {
+      lastError = void 0;
       process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
 `);
+      sendHeartbeat("synced");
+      void writeCurrentBridgeStatus("connected").catch(() => void 0);
     });
     socket.addEventListener("message", (event) => {
       if (typeof event.data !== "string") return;
@@ -13748,9 +13962,12 @@ async function runBridge(options) {
     });
     socket.addEventListener("close", () => {
       socket = void 0;
+      void writeCurrentBridgeStatus("offline").catch(() => void 0);
       setTimeout(connect, 1e3);
     });
     socket.addEventListener("error", () => {
+      lastError = "WebSocket error";
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
       socket?.close();
     });
   }
@@ -13759,7 +13976,7 @@ async function runBridge(options) {
     const currentDocIds = new Set(map.docs.map((doc) => doc.docId));
     const treeSignature = hashJson(map.docs.map((doc) => ({ docId: doc.docId, path: doc.path })));
     if (treeSignature !== lastTreeSignature) {
-      if (send("file-tree", { reason, docs: map.docs, mapping, canonicalHead: lastAppliedHead })) {
+      if (send("file-tree", { reason, docs: map.docs, mapping: bridgeReplicaMetadata("synced"), canonicalHead: lastAppliedHead })) {
         lastTreeSignature = treeSignature;
       }
     }
@@ -13787,6 +14004,9 @@ async function runBridge(options) {
         pendingDeletes.add(docId);
       }
     }
+    lastError = void 0;
+    lastSuccessfulSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+    maybeSendHeartbeat("synced");
   }
   async function resumeFromCanonical() {
     if (!options.resume && !token) return false;
@@ -13899,7 +14119,9 @@ async function runBridge(options) {
     }
     if (message.type === "sync-error") {
       const payload = message.payload;
-      process.stderr.write(`sync rejected${payload.code ? ` (${payload.code})` : ""}: ${payload.hint ?? "see workspace settings"}
+      lastError = `sync rejected${payload.code ? ` (${payload.code})` : ""}: ${payload.hint ?? "see workspace settings"}`;
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
+      process.stderr.write(`${lastError}
 `);
       if (!payload.docId) return;
       pendingDocs.delete(payload.docId);
@@ -13938,6 +14160,12 @@ async function runBridge(options) {
     await io.writeTextAtomic(payload.path, payload.markdown);
     await io.writeTextAtomic(sidecarPath(payload.docId), `${JSON.stringify(payload.sidecar, null, 2)}
 `);
+    const reviewMarkdown = projectReviewMarkdown(payload.markdown, payload.sidecar.suggestions);
+    if (reviewMarkdown === payload.markdown) {
+      await io.deleteFile(reviewFilePath(payload.path)).catch(() => void 0);
+    } else {
+      await io.writeTextAtomic(reviewFilePath(payload.path), reviewMarkdown);
+    }
     await upsertManifestDocument(payload);
     signatures.set(payload.docId, remoteSignature);
     deniedSignatures.delete(payload.docId);
@@ -14018,6 +14246,63 @@ async function runBridge(options) {
     );
     return true;
   }
+  function maybeSendHeartbeat(status) {
+    if (Date.now() - lastHeartbeatSentMs < BRIDGE_HEARTBEAT_INTERVAL_MS) return;
+    sendHeartbeat(status);
+  }
+  function sendHeartbeat(status, error, writeLocalStatus = true) {
+    const heartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
+    const sent = send("bridge-heartbeat", {
+      reason: "heartbeat",
+      canonicalHead: lastAppliedHead,
+      mapping: bridgeReplicaMetadata(status, error, heartbeatAt)
+    });
+    if (sent) {
+      lastHeartbeatAt = heartbeatAt;
+      lastHeartbeatSentMs = Date.now();
+      if (writeLocalStatus) {
+        void writeCurrentBridgeStatus(status === "error" ? "error" : status === "offline" ? "offline" : "connected").catch(() => void 0);
+      }
+    }
+    return sent;
+  }
+  function bridgeReplicaMetadata(status, error, now = (/* @__PURE__ */ new Date()).toISOString()) {
+    return {
+      ...mapping,
+      lastAppliedHead,
+      status,
+      updatedAt: now,
+      lastSeenAt: now,
+      bridgeVersion: CLI_VERSION,
+      pendingDocuments: pendingDocs.size,
+      pendingDeletes: pendingDeletes.size,
+      ...error ? { lastError: error } : {}
+    };
+  }
+  function currentBridgeStatus(state) {
+    return {
+      schemaVersion: 1,
+      workspaceId: options.workspaceId,
+      rootId,
+      actorId: options.actorId,
+      actorName: options.actorName,
+      sourceName: options.sourceName,
+      baseUrl: options.baseUrl,
+      state,
+      connected: state === "connected",
+      bridgeVersion: CLI_VERSION,
+      lastAppliedHead,
+      lastSuccessfulSyncAt,
+      lastHeartbeatAt,
+      lastError,
+      pendingDocuments: pendingDocs.size,
+      pendingDeletes: pendingDeletes.size,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async function writeCurrentBridgeStatus(state) {
+    await writeBridgeStatus(root, currentBridgeStatus(state));
+  }
   async function primeLocalSignatures() {
     const map = await getWorkspaceMap(io);
     for (const doc of map.docs) {
@@ -14145,6 +14430,12 @@ async function writeBridgeConfig(root, config2) {
   await io.writeTextAtomic(BRIDGE_CONFIG_PATH, `${JSON.stringify(config2, null, 2)}
 `);
 }
+async function writeBridgeStatus(root, status) {
+  const io = new NodeWorkspaceIO(root);
+  await io.mkdir(".mdocs");
+  await io.writeTextAtomic(BRIDGE_STATUS_PATH, `${JSON.stringify(status, null, 2)}
+`);
+}
 async function fetchCanonicalSnapshot(options, rootId) {
   const response = await fetch(new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/sync`, options.baseUrl), {
     headers: authHeaders(options.token)
@@ -14215,11 +14506,14 @@ function parseBridgeSyncMessage(data) {
   }
 }
 function delay(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 function authHeaders(token) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 async function fetchScopedRoot(options, rootId) {
   const response = await fetch(
     new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}`, options.baseUrl),
@@ -14323,6 +14617,9 @@ function conflictCopyPath(path) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "").slice(0, 15);
   return path.replace(/(\.[^./]+)?$/, (extension) => `.conflict-${stamp}${extension || ".md"}`);
 }
+function reviewFilePath(path) {
+  return path.replace(/(\.md)?$/i, ".review.md");
+}
 function hashJson(value) {
   return createHash2("sha256").update(JSON.stringify(value)).digest("hex");
 }
@@ -14354,10 +14651,246 @@ function readDocumentPayload(payload) {
   };
 }
 
+// src/bridge-startup.ts
+import { execFile as execFile2 } from "node:child_process";
+import { createHash as createHash3 } from "node:crypto";
+import { chmod, copyFile, mkdir as mkdir4, readFile as readFile6, stat as stat3, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname as dirname5, join as join4, resolve as resolve5 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+var execFileAsync2 = promisify2(execFile2);
+async function runBridgeStartup(options) {
+  const root = resolve5(options.root);
+  await assertBridgeConfigured(root);
+  const requestedMode = readBridgeStartupMode(options.mode);
+  const mode = requestedMode === "auto" ? await autoBridgeStartupMode() : requestedMode;
+  const startupDir = join4(root, ".mdocs", "startup");
+  await mkdir4(startupDir, { recursive: true });
+  const runnerPath = join4(startupDir, "bridge-runner.sh");
+  const runnerArgs = bridgeResumeArgs(root, options);
+  const runnerScript = bridgeRunnerScript(root, runnerArgs);
+  await writeFile4(runnerPath, runnerScript, "utf8");
+  await chmod(runnerPath, 493);
+  const nativePlan = mode === "launchd" ? await writeLaunchdPlan(root, startupDir, runnerPath) : mode === "systemd" ? await writeSystemdPlan(root, startupDir, runnerPath) : void 0;
+  if (options.install && !nativePlan) {
+    throw new CliError("usage_error", "Shell startup mode does not have a native service to install.", {
+      hint: "Use the printed startupCommand in your sandbox/provider startup hook, or pass --mode launchd/systemd on a supported host."
+    });
+  }
+  if (options.install && nativePlan) await nativePlan.install();
+  const result = {
+    ok: true,
+    root,
+    mode,
+    runnerPath,
+    startupCommand: shellCommand(["sh", runnerPath]),
+    servicePath: nativePlan?.servicePath,
+    installPath: nativePlan?.installPath,
+    installed: Boolean(options.install && nativePlan),
+    installCommands: nativePlan?.installCommands ?? [],
+    notes: [
+      "Sandbox providers such as Daytona, Sprites, and Modal should run startupCommand from their on-start hook.",
+      "The runner stores no bridge token. If you use manual tokens, provide MDOCS_BRIDGE_TOKEN through the platform secret environment.",
+      "If no MDOCS_BRIDGE_TOKEN is present, the runner uses --request-token and logs a Magic approval URL."
+    ]
+  };
+  await writeFile4(join4(startupDir, "bridge-startup.json"), `${JSON.stringify(result, null, 2)}
+`, "utf8");
+  return result;
+}
+function formatBridgeStartupResult(result) {
+  const lines = [
+    `Wrote Magic Markdown bridge runner: ${result.runnerPath}`,
+    `Startup command: ${result.startupCommand}`
+  ];
+  if (result.servicePath) lines.push(`Wrote ${result.mode} service file: ${result.servicePath}`);
+  if (result.installed && result.installPath) {
+    lines.push(`Installed ${result.mode} service: ${result.installPath}`);
+  } else if (result.installCommands.length > 0) {
+    lines.push("", "To install and start it manually:", ...result.installCommands.map((command) => `  ${command}`));
+  }
+  lines.push("", ...result.notes.map((note) => `Note: ${note}`));
+  return lines.join("\n");
+}
+function bridgeRunnerScript(root, args) {
+  return `#!/usr/bin/env sh
+set -eu
+cd ${shellQuote(root)}
+exec npx --yes --package=@magic-markdown/cli@latest mdocs ${shellCommand(args)} "$@"
+`;
+}
+function bridgeResumeArgs(root, options) {
+  const args = ["bridge", "resume", "--root", root, "--forever"];
+  if (options.requestToken !== false) args.push("--request-token");
+  if (options.baseUrl) args.push("--url", options.baseUrl);
+  if (options.intervalMs) args.push("--interval", String(options.intervalMs));
+  return args;
+}
+function readBridgeStartupMode(value) {
+  if (!value || value === "auto" || value === "shell" || value === "launchd" || value === "systemd") {
+    return value || "auto";
+  }
+  throw new CliError("usage_error", `Unknown bridge startup mode: ${value}`, {
+    hint: "Use --mode auto, shell, launchd, or systemd."
+  });
+}
+async function autoBridgeStartupMode() {
+  if (platform() === "darwin") return "launchd";
+  if (platform() === "linux" && await pathExists("/run/systemd/system")) return "systemd";
+  return "shell";
+}
+async function assertBridgeConfigured(root) {
+  const configPath = join4(root, ".mdocs", "bridge.json");
+  try {
+    const config2 = JSON.parse(await readFile6(configPath, "utf8"));
+    if (config2.schemaVersion !== 1) throw new Error("invalid schema");
+  } catch {
+    throw new CliError("usage_error", "This root does not have a bridge configuration yet.", {
+      hint: "Run mdocs bridge setup first, then run mdocs bridge startup from the same root."
+    });
+  }
+}
+async function writeLaunchdPlan(root, startupDir, runnerPath) {
+  const label = serviceLabel(root);
+  const servicePath = join4(startupDir, `${label}.plist`);
+  const installPath = join4(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+  const outLog = join4(root, ".mdocs", "bridge.log");
+  const errLog = join4(root, ".mdocs", "bridge.err.log");
+  await writeFile4(servicePath, launchdPlist(label, root, runnerPath, outLog, errLog), "utf8");
+  const target = `gui/$(id -u)`;
+  return {
+    servicePath,
+    installPath,
+    installCommands: [
+      shellCommand(["mkdir", "-p", dirname5(installPath)]),
+      shellCommand(["cp", servicePath, installPath]),
+      `launchctl bootout ${target} ${shellQuote(installPath)} 2>/dev/null || true`,
+      `launchctl bootstrap ${target} ${shellQuote(installPath)}`,
+      `launchctl enable ${target}/${label}`,
+      `launchctl kickstart -k ${target}/${label}`
+    ],
+    install: async () => {
+      await mkdir4(dirname5(installPath), { recursive: true });
+      await copyFile(servicePath, installPath);
+      const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+      if (uid === void 0) return;
+      const launchTarget = `gui/${uid}`;
+      await runOptionalCommand("launchctl", ["bootout", launchTarget, installPath]);
+      await runCommand("launchctl", ["bootstrap", launchTarget, installPath]);
+      await runCommand("launchctl", ["enable", `${launchTarget}/${label}`]);
+      await runCommand("launchctl", ["kickstart", "-k", `${launchTarget}/${label}`]);
+    }
+  };
+}
+async function writeSystemdPlan(root, startupDir, runnerPath) {
+  const unitName = `${serviceLabel(root)}.service`;
+  const servicePath = join4(startupDir, unitName);
+  const installPath = join4(homedir(), ".config", "systemd", "user", unitName);
+  await writeFile4(servicePath, systemdUnit(unitName, root, runnerPath), "utf8");
+  return {
+    servicePath,
+    installPath,
+    installCommands: [
+      shellCommand(["mkdir", "-p", dirname5(installPath)]),
+      shellCommand(["cp", servicePath, installPath]),
+      "systemctl --user daemon-reload",
+      shellCommand(["systemctl", "--user", "enable", "--now", unitName])
+    ],
+    install: async () => {
+      await mkdir4(dirname5(installPath), { recursive: true });
+      await copyFile(servicePath, installPath);
+      await runCommand("systemctl", ["--user", "daemon-reload"]);
+      await runCommand("systemctl", ["--user", "enable", "--now", unitName]);
+    }
+  };
+}
+function launchdPlist(label, root, runnerPath, outLog, errLog) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>${escapeXml(runnerPath)}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(root)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(outLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(errLog)}</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(unitName, root, runnerPath) {
+  return `[Unit]
+Description=Magic Markdown bridge (${unitName})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(root)}
+ExecStart=/bin/sh ${systemdQuote(runnerPath)}
+Restart=always
+RestartSec=5
+Environment=PATH=${systemdQuote(process.env.PATH || "/usr/local/bin:/usr/bin:/bin")}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function serviceLabel(root) {
+  const digest = createHash3("sha256").update(root).digest("hex").slice(0, 12);
+  return `com.magic-markdown.bridge.${digest}`;
+}
+async function runOptionalCommand(command, args) {
+  try {
+    await execFileAsync2(command, args);
+  } catch {
+  }
+}
+async function runCommand(command, args) {
+  try {
+    await execFileAsync2(command, args);
+  } catch (error) {
+    const detail = error;
+    throw new CliError("internal_error", `${command} ${args.join(" ")} failed: ${detail.stderr || detail.message || String(error)}`);
+  }
+}
+async function pathExists(path) {
+  try {
+    await stat3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function shellCommand(args) {
+  return args.map(shellQuote).join(" ");
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function systemdQuote(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
 // src/index.ts
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
-  const cwd = resolve5(String(parsed.flags.cwd ?? process.cwd()));
+  const cwd = resolve6(String(parsed.flags.cwd ?? process.cwd()));
   const io = new NodeWorkspaceIO(cwd);
   const [command, subcommand] = parsed.command;
   if (parsed.flags.version || command === "version") {
@@ -14372,7 +14905,7 @@ async function main() {
   }
   switch (command) {
     case "init": {
-      const target = resolve5(parsed.command[1] ?? cwd);
+      const target = resolve6(parsed.command[1] ?? cwd);
       const targetIo = new NodeWorkspaceIO(target);
       const manifest = await indexWorkspace(targetIo);
       print(manifest, parsed.flags);
@@ -14409,7 +14942,7 @@ async function main() {
         markdown,
         images: state.images.map((image2) => ({
           ...image2,
-          ...image2.workspacePath ? { absolutePath: resolve5(cwd, image2.workspacePath) } : {}
+          ...image2.workspacePath ? { absolutePath: resolve6(cwd, image2.workspacePath) } : {}
         })),
         links: state.links,
         ...parsed.flags["no-review"] ? {} : {
@@ -14513,7 +15046,7 @@ async function main() {
       return;
     }
     case "bridge": {
-      const root = resolve5(String(parsed.flags.root ?? cwd));
+      const root = resolve6(String(parsed.flags.root ?? cwd));
       const baseOptions = {
         root,
         rootId: typeof parsed.flags["root-id"] === "string" ? parsed.flags["root-id"] : void 0,
@@ -14529,8 +15062,21 @@ async function main() {
         token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
         requestToken: Boolean(parsed.flags["request-token"] || parsed.flags.pair),
         pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0,
-        once: Boolean(parsed.flags.once)
+        once: Boolean(parsed.flags.once),
+        forever: Boolean(parsed.flags.forever)
       };
+      if (subcommand === "startup" || subcommand === "daemon") {
+        const result = await runBridgeStartup({
+          root,
+          mode: typeof parsed.flags.mode === "string" ? parsed.flags.mode : void 0,
+          install: Boolean(parsed.flags.install),
+          requestToken: !parsed.flags["no-request-token"],
+          baseUrl: optionalBridgeBaseUrl(parsed.flags),
+          intervalMs: typeof parsed.flags.interval === "string" ? Number(parsed.flags.interval) : void 0
+        });
+        print(parsed.flags.json ? result : formatBridgeStartupResult(result), parsed.flags);
+        return;
+      }
       if (subcommand === "resume") {
         await runBridgeResume({
           ...baseOptions,
@@ -14669,7 +15215,7 @@ async function readRequiredTextFlag2(flags, cwd, names) {
 async function readOptionalTextFlag2(flags, cwd, names) {
   for (const name of names) {
     const fileValue = flags[`${name}-file`];
-    if (typeof fileValue === "string") return readFile6(resolve5(cwd, fileValue), "utf8");
+    if (typeof fileValue === "string") return readFile7(resolve6(cwd, fileValue), "utf8");
     const value = flags[name];
     if (typeof value === "string") return value;
   }
@@ -14717,9 +15263,9 @@ Commands:
   comments <path> --json              List comments
   comment <path> --range 3:5 --body   Add a sidecar comment
   suggestions <path> --json           List suggestions
-  suggest <path> --range 3:5 --with   Add a sidecar suggestion
+  suggest <path> --range 3:5 --with   Add a reviewMarkdown suggestion
   suggest <path> --range 3:5 --with-file replacement.md
-                                      Add a multiline sidecar suggestion
+                                      Add a multiline reviewMarkdown suggestion
   accept <suggestionId>               Apply and accept a suggestion
   reject <suggestionId>               Reject a suggestion
   resolve-comment <commentId>         Resolve a comment thread
@@ -14742,9 +15288,12 @@ Commands:
   bridge setup --workspace <id> --root . --url <base-url> [--folder-id <id>] --request-token
                                       Initialize, validate, request approval,
                                       and start an agent filesystem bridge
-  bridge resume --root . --request-token [--once]
+  bridge resume --root . --forever --request-token [--once]
                                       Backfill missed Magic changes, then keep
                                       the bridge running unless --once is set
+  bridge startup|daemon --root . [--mode auto|shell|launchd|systemd] [--install]
+                                      Write a bridge runner and startup hook
+                                      for sandboxes, launchd, or systemd
   bridge --workspace <id> --root . --url <base-url> --request-token
                                       Request human approval, then sync an
                                       approved local root with the workspace
@@ -14764,7 +15313,8 @@ Exit codes: 0 ok, 1 internal, 2 usage, 3 conflict, 4 not found, 5 network, 6 una
 `);
 }
 function commandHelp(commandPath) {
-  const candidates = [commandPath.slice(0, 2).join(" "), commandPath[0] ?? ""].filter(Boolean);
+  const normalizedPath = commandPath[0] === "bridge" && commandPath[1] === "daemon" ? ["bridge", "startup"] : commandPath;
+  const candidates = [normalizedPath.slice(0, 2).join(" "), normalizedPath[0] ?? ""].filter(Boolean);
   const spec = AGENT_COMMANDS.find((command) => candidates.includes(command.name));
   if (!spec) return false;
   const lines = [
@@ -14785,7 +15335,8 @@ function commandHelp(commandPath) {
   return true;
 }
 function usageFor(commandPath) {
-  const candidates = [commandPath.slice(0, 2).join(" "), commandPath[0] ?? ""].filter(Boolean);
+  const normalizedPath = commandPath[0] === "bridge" && commandPath[1] === "daemon" ? ["bridge", "startup"] : commandPath;
+  const candidates = [normalizedPath.slice(0, 2).join(" "), normalizedPath[0] ?? ""].filter(Boolean);
   return AGENT_COMMANDS.find((command) => candidates.includes(command.name))?.usage;
 }
 main().catch((error) => {