sidecarsync 2.1.0 → 2.1.2

package/dist/cli.js

@@ -216,12 +216,15 @@ function utcTimestamp() {
 function nowIso() {
   return new Date().toISOString();
 }
-var SidecarError;
+var DIRTY_CHECKOUT_EXIT = 75, SidecarError;
 var init_util = __esm(() => {
   SidecarError = class SidecarError extends Error {
-    constructor(message) {
+    reason;
+    stage;
+    constructor(message, options = {}) {
       super(message);
       this.name = "SidecarError";
+      this.reason = options.reason;
     }
   };
 });
@@ -1402,7 +1405,7 @@ function isDirty(repo) {
 }
 function ensureClean(repo) {
   if (isDirty(repo))
-    throw new SidecarError("sidecar checkout has uncommitted changes");
+    throw new SidecarError("sidecar checkout has uncommitted changes", { reason: "dirty-checkout" });
 }
 function sidecarIdentity() {
   return { name: currentUser(), email: `${slug(currentUser())}@${slug(currentHost())}.local` };
@@ -1446,15 +1449,142 @@ var init_git = __esm(() => {
 });
 
 // src/redaction.ts
+function redactShellDefaults(text) {
+  let output = "";
+  let copied = 0;
+  for (const match of text.matchAll(SHELL_DEFAULT_REGEX)) {
+    const [whole, open, name, operator] = match;
+    if (match.index < copied)
+      continue;
+    if (SHELL_DIRECTORY_NAMES.has(name) || !isSensitiveKey(name))
+      continue;
+    const wordStart = match.index + whole.length;
+    const end = shellWordEnd(text, wordStart, "}");
+    const wordEnd = end === -1 ? lineEnd(text, wordStart) : end;
+    const word = text.slice(wordStart, wordEnd);
+    output += text.slice(copied, wordStart);
+    output += !word || isPlaceholder(word) || isShellReference(word) ? word : placeholderForKey(name);
+    copied = wordEnd;
+  }
+  return output + text.slice(copied);
+}
+function shellWordEnd(text, start, close, depth = 0) {
+  if (depth > SHELL_NESTING_LIMIT)
+    return -1;
+  let parens = 0;
+  for (let index = start;index < text.length; index += 1) {
+    const char = text[index];
+    if (char === `
+` || char === "\r")
+      return -1;
+    if (char === "\\") {
+      index += 1;
+    } else if (char === "'" || char === '"' || char === "`") {
+      index = closingQuote(text, index + 1, char, depth + 1);
+      if (index === -1)
+        return -1;
+    } else if (char === "$" && (text[index + 1] === "{" || text[index + 1] === "(")) {
+      index = shellWordEnd(text, index + 2, text[index + 1] === "{" ? "}" : ")", depth + 1);
+      if (index === -1)
+        return -1;
+    } else if (close === ")" && char === "(") {
+      parens += 1;
+    } else if (close === ")" && char === ")" && parens > 0) {
+      parens -= 1;
+    } else if (char === close) {
+      return index;
+    }
+  }
+  return -1;
+}
+function closingQuote(text, start, quote, depth) {
+  if (depth > SHELL_NESTING_LIMIT)
+    return -1;
+  for (let index = start;index < text.length; index += 1) {
+    const char = text[index];
+    if (char === `
+` || char === "\r")
+      return -1;
+    if (char === quote)
+      return index;
+    if (quote === "'")
+      continue;
+    if (char === "\\") {
+      index += 1;
+    } else if (quote === '"' && char === "$" && (text[index + 1] === "{" || text[index + 1] === "(")) {
+      index = shellWordEnd(text, index + 2, text[index + 1] === "{" ? "}" : ")", depth + 1);
+      if (index === -1)
+        return -1;
+    } else if (quote === '"' && char === "`") {
+      index = closingQuote(text, index + 1, "`", depth + 1);
+      if (index === -1)
+        return -1;
+    }
+  }
+  return -1;
+}
+function lineEnd(text, start) {
+  const match = /[\r\n]/.exec(text.slice(start));
+  return match ? start + match.index : text.length;
+}
+function isShellReadOfKey(text, offset, separator) {
+  if (SHELL_EXPANSION_KEY_PREFIX.test(text.slice(Math.max(0, offset - 64), offset)))
+    return true;
+  return text[offset - 1] === "$" && separator.trim().startsWith(":");
+}
+function isShellReference(value, depth = 0) {
+  if (depth > SHELL_NESTING_LIMIT)
+    return false;
+  const unquoted = value.length > 1 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+  if (SHELL_VARIABLE_REFERENCE.test(unquoted))
+    return true;
+  if (!unquoted.startsWith("${") || shellWordEnd(unquoted, 2, "}") !== unquoted.length - 1)
+    return false;
+  const rest = SHELL_EXPANSION_INNER.exec(unquoted.slice(2, -1))?.groups?.rest;
+  if (rest === undefined)
+    return false;
+  if (rest === "" || /^:?\?/.test(rest) || /^(?::[a-zA-Z0-9]+)+$/.test(rest))
+    return true;
+  const word = /^:?[-=+](?<word>.*)$/s.exec(rest)?.groups?.word;
+  return word !== undefined && (word === "" || isPlaceholder(word) || isShellReference(word, depth + 1));
+}
+function startsWithShellReference(text, start, value) {
+  if (SHELL_COMMAND_NAME_VALUE.test(value))
+    return true;
+  if (text[start] !== "$")
+    return false;
+  let end;
+  if (text[start + 1] === "{") {
+    end = shellWordEnd(text, start + 2, "}");
+    if (end === -1)
+      return false;
+    end += 1;
+  } else {
+    end = start + 1 + (/^[A-Za-z0-9_]*/.exec(text.slice(start + 1))?.[0].length ?? 0);
+  }
+  if (end < text.length && !/[\s;&|)]/.test(text[end]))
+    return false;
+  return isShellReference(text.slice(start, end));
+}
 function redactText(input, mode = DEFAULT_REDACTION_MODE) {
   if (mode === "none")
     return input;
-  let output = input.replace(PEM_PRIVATE_KEY_REGEX, "<PRIVATEKEY>").replace(AUTHORIZATION_HEADER_REGEX, (_match, prefix) => `${prefix}<TOKEN>`).replace(BARE_BEARER_TOKEN_REGEX, (_match, prefix) => `${prefix}<TOKEN>`).replace(URL_CREDENTIALS_REGEX, (_match, prefix) => `${prefix}:<SECRET>@`).replace(QUOTED_SECRET_REGEX, (match, ...args) => {
-    const { keyQuote = "", key, separator, valueQuote } = args.at(-1);
-    if (!isSensitiveKey(key))
+  let output = redactShellDefaults(input).replace(PEM_PRIVATE_KEY_REGEX, "<PRIVATEKEY>").replace(AUTHORIZATION_HEADER_REGEX, (_match, prefix) => `${prefix}<TOKEN>`).replace(BARE_BEARER_TOKEN_REGEX, (_match, prefix) => `${prefix}<TOKEN>`).replace(URL_CREDENTIALS_REGEX, (_match, prefix) => `${prefix}:<SECRET>@`).replace(QUOTED_SECRET_REGEX, (match, ...args) => {
+    const { keyQuote = "", key, separator, valueQuote, value } = args.at(-1);
+    const offset = args.at(-3);
+    const text = args.at(-2);
+    if (!isSensitiveKey(key) || isShellReadOfKey(text, offset + keyQuote.length, separator))
+      return match;
+    if (valueQuote === '"' && isShellReference(value))
       return match;
     return `${keyQuote}${key}${keyQuote}${separator}${valueQuote}${placeholderForKey(key)}${valueQuote}`;
-  }).replace(BARE_ASSIGNMENT_SECRET_REGEX, (match, key, separator) => isSensitiveKey(key) ? `${key}${separator}${placeholderForKey(key)}` : match);
+  }).replace(BARE_ASSIGNMENT_SECRET_REGEX, (match, key, separator, value, offset, text) => {
+    if (!isSensitiveKey(key) || isShellReadOfKey(text, offset, separator))
+      return match;
+    if (startsWithShellReference(text, offset + key.length + separator.length, value))
+      return match;
+    return `${key}${separator}${placeholderForKey(key)}`;
+  });
   for (const [pattern, replacement] of TOKEN_PATTERNS) {
     output = output.replace(pattern, replacement);
   }
@@ -1462,6 +1592,12 @@ function redactText(input, mode = DEFAULT_REDACTION_MODE) {
     return output;
   return output.replace(EMAIL_REGEX, "<EMAIL>").replace(PHONE_REGEX, "<PHONENUMBER>").replace(SSN_REGEX, "<SSN>").replace(CREDIT_CARD_CANDIDATE_REGEX, (candidate) => isLikelyCreditCard(candidate) ? "<CREDITCARD>" : candidate);
 }
+function isPlaceholder(text) {
+  return /^<(?:API_KEY|TOKEN|SECRET|PRIVATEKEY|EMAIL|PHONENUMBER|SSN|CREDITCARD)>$/.test(text);
+}
+function hasRedactionPlaceholder(text) {
+  return countRedactionPlaceholders(text) > 0;
+}
 function countRedactionPlaceholders(text) {
   return text.match(PLACEHOLDER_REGEX)?.length ?? 0;
 }
@@ -1515,12 +1651,20 @@ function isLikelyCreditCard(value) {
   }
   return sum % 10 === 0;
 }
-var DEFAULT_REDACTION_MODE = "secrets", REDACTION_MODES, KEY_NAME_PATTERN, QUOTED_SECRET_REGEX, BARE_ASSIGNMENT_SECRET_REGEX, AUTHORIZATION_HEADER_REGEX, PEM_PRIVATE_KEY_REGEX, URL_CREDENTIALS_REGEX, BARE_BEARER_TOKEN_REGEX, TOKEN_PATTERNS, EMAIL_REGEX, PHONE_REGEX, SSN_REGEX, CREDIT_CARD_CANDIDATE_REGEX, PLACEHOLDER_REGEX, COMPACT_SENSITIVE_KEYS;
+var DEFAULT_REDACTION_MODE = "secrets", REDACTION_MODES, KEY_NAME_PATTERN, QUOTED_SECRET_REGEX, BARE_ASSIGNMENT_SECRET_REGEX, SHELL_NAME_PATTERN, SHELL_EXPANSION_OPEN, SHELL_DEFAULT_REGEX, SHELL_EXPANSION_KEY_PREFIX, SHELL_EXPANSION_INNER, SHELL_DIRECTORY_NAMES, SHELL_VARIABLE_REFERENCE, SHELL_NESTING_LIMIT = 16, SHELL_COMMAND_NAME_VALUE, AUTHORIZATION_HEADER_REGEX, PEM_PRIVATE_KEY_REGEX, URL_CREDENTIALS_REGEX, BARE_BEARER_TOKEN_REGEX, TOKEN_PATTERNS, EMAIL_REGEX, PHONE_REGEX, SSN_REGEX, CREDIT_CARD_CANDIDATE_REGEX, PLACEHOLDER_REGEX, COMPACT_SENSITIVE_KEYS;
 var init_redaction = __esm(() => {
   REDACTION_MODES = ["none", "secrets", "secrets+pii"];
   KEY_NAME_PATTERN = String.raw`[A-Za-z0-9_][A-Za-z0-9_-]*`;
-  QUOTED_SECRET_REGEX = new RegExp(String.raw`(?:(?<keyQuote>["'])|\b)(?<key>${KEY_NAME_PATTERN})\k<keyQuote>` + String.raw`(?<separator>\s*[:=]\s*)(?<valueQuote>["'])(?:\\[^\r\n]|(?!\k<valueQuote>)[^\\\r\n])+\k<valueQuote>`, "g");
+  QUOTED_SECRET_REGEX = new RegExp(String.raw`(?:(?<keyQuote>["'])|\b)(?<key>${KEY_NAME_PATTERN})\k<keyQuote>` + String.raw`(?<separator>\s*[:=]\s*)(?<valueQuote>["'])(?<value>(?:\\[^\r\n]|(?!\k<valueQuote>)[^\\\r\n])+)\k<valueQuote>`, "g");
   BARE_ASSIGNMENT_SECRET_REGEX = new RegExp(String.raw`\b(${KEY_NAME_PATTERN})(\s*[:=]\s*)([^\s"',;` + "`" + String.raw`]+)`, "g");
+  SHELL_NAME_PATTERN = String.raw`[A-Za-z_][A-Za-z0-9_]*`;
+  SHELL_EXPANSION_OPEN = String.raw`\$\{(?:\([^()\s]*\))?[#!^=~]*`;
+  SHELL_DEFAULT_REGEX = new RegExp(String.raw`(${SHELL_EXPANSION_OPEN})(${SHELL_NAME_PATTERN})(:?[-=+])`, "g");
+  SHELL_EXPANSION_KEY_PREFIX = new RegExp(`${SHELL_EXPANSION_OPEN}$`);
+  SHELL_EXPANSION_INNER = new RegExp(String.raw`^(?:\([^()\s]*\))?[#!^=~]*${SHELL_NAME_PATTERN}(?<rest>.*)$`, "s");
+  SHELL_DIRECTORY_NAMES = new Set(["PWD", "OLDPWD"]);
+  SHELL_VARIABLE_REFERENCE = new RegExp(String.raw`^\$(?:[A-Z_][A-Z0-9_]*)$`);
+  SHELL_COMMAND_NAME_VALUE = /^\$\((?:[A-Za-z0-9_./+-]+|<(?:API_KEY|TOKEN|SECRET|PRIVATEKEY|EMAIL|PHONENUMBER|SSN|CREDITCARD)>)\)?$/;
   AUTHORIZATION_HEADER_REGEX = /\b(authorization\s*[:=]\s*(?:bearer|basic|token)\s+)([^\s"',;`]+)/gi;
   PEM_PRIVATE_KEY_REGEX = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/g;
   URL_CREDENTIALS_REGEX = /(\/\/[^\s/:@"'`]+):([^\s/@"'`]+)@/g;
@@ -3812,7 +3956,7 @@ function inboxBranchPrefix(template) {
   const slashIndex = staticPrefix.lastIndexOf("/");
   return slashIndex === -1 ? staticPrefix : staticPrefix.slice(0, slashIndex + 1);
 }
-var DEFAULT_PATH = "sidecar", DEFAULT_BRANCH = "main", DEFAULT_INBOX = "sidecar-inbox/{user}/{random}", branchValidity, DEFAULT_PEER = "default", PEER_ENV = "SIDECAR_PEER", SOFT_SYNC_ENV = "SIDECAR_SYNC_SOFT", LOCAL_SYNC_ENV = "SIDECAR_SYNC_LOCAL", PEER_NAME, RESERVED_PEER_SUFFIXES, RESOLVE_MODES, DEFAULT_RESOLVE = "fork", REVIEW_MODES, DEFAULT_REVIEW_TIMEOUT_SECONDS, CONFIG_VERSION = 1, CONFIG_KEYS, failuresArePrivate = false, PUBLIC_REFS = "refs/sidecar-public/";
+var DEFAULT_PATH = "sidecar", DEFAULT_BRANCH = "main", DEFAULT_INBOX = "sidecar-inbox/{user}/{random}", branchValidity, DEFAULT_PEER = "default", PEER_ENV = "SIDECAR_PEER", SOFT_SYNC_ENV = "SIDECAR_SYNC_SOFT", LOCAL_SYNC_ENV = "SIDECAR_SYNC_LOCAL", DEFAULT_DEBOUNCE_SECONDS = 60, PEER_NAME, RESERVED_PEER_SUFFIXES, RESOLVE_MODES, DEFAULT_RESOLVE = "fork", REVIEW_MODES, DEFAULT_REVIEW_TIMEOUT_SECONDS, CONFIG_VERSION = 1, CONFIG_KEYS, failuresArePrivate = false, PUBLIC_REFS = "refs/sidecar-public/";
 var init_config = __esm(() => {
   init_dist();
   init_util();
@@ -4200,6 +4344,37 @@ function syncLockIsStale(lockDir) {
     return error.code !== "EPERM";
   }
 }
+function reviewDueDir() {
+  return path6.join(sidecarStateDir(), "review-due");
+}
+function reviewDuePath(configPath) {
+  const key = `${realpathOr(path6.dirname(configPath))}\x00${path6.basename(configPath)}`;
+  return path6.join(reviewDueDir(), `${crypto3.createHash("sha256").update(key).digest("hex").slice(0, 16)}.json`);
+}
+function writeReviewDue(configPath, dueAt) {
+  const filePath = reviewDuePath(configPath);
+  fs6.mkdirSync(path6.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${crypto3.randomUUID()}.tmp`;
+  try {
+    fs6.writeFileSync(temporary, `${JSON.stringify({ configPath, dueAt: new Date(dueAt).toISOString() })}
+`, "utf8");
+    fs6.renameSync(temporary, filePath);
+  } finally {
+    fs6.rmSync(temporary, { force: true });
+  }
+}
+function clearReviewDue(configPath) {
+  fs6.rmSync(reviewDuePath(configPath), { force: true });
+}
+function readReviewDue(configPath) {
+  try {
+    const { dueAt } = JSON.parse(fs6.readFileSync(reviewDuePath(configPath), "utf8"));
+    const time = typeof dueAt === "string" ? Date.parse(dueAt) : Number.NaN;
+    return Number.isFinite(time) ? time : undefined;
+  } catch {
+    return;
+  }
+}
 var STATE_DIR_ENV = "SIDECAR_STATE_DIR", DEFAULT_SETTINGS, LOG_ROTATE_BYTES, SYNC_LOCK_WAIT_MS;
 var init_state = __esm(() => {
   init_util();
@@ -4692,7 +4867,7 @@ function createReview(options) {
   if (guidelines)
     writePrivateFile(path8.join(dir, "guidelines.md"), `${guidelines}
 `);
-  writePrivateFile(path8.join(dir, "instructions.md"), reviewInstructions(record, config, guidelines));
+  writePrivateFile(path8.join(dir, "instructions.md"), reviewInstructions(record, config, guidelines, addedPlaceholderLines(diff)));
   writePrivateJson(path8.join(dir, "review.json"), record);
   logSidecarEvent("review-open", { id, root, peer: config.peer, files: files.length });
   pruneClosedReviews(sidecarPath);
@@ -4751,6 +4926,102 @@ function pruneOrphanedReviews() {
       fs8.rmSync(review.dir, { recursive: true, force: true });
   }
 }
+function addedPlaceholderLines(patch) {
+  const found = [];
+  let file;
+  let oldLeft = 0;
+  let newLeft = 0;
+  let newLine = 0;
+  for (const raw of patch.split(`
+`)) {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (oldLeft > 0 || newLeft > 0) {
+      if (line.startsWith("+")) {
+        if (file && hasRedactionPlaceholder(line))
+          found.push({ file, line: newLine, text: line.slice(1) });
+        newLeft -= 1;
+        newLine += 1;
+      } else if (line.startsWith("-")) {
+        oldLeft -= 1;
+      } else if (!line.startsWith("\\")) {
+        oldLeft -= 1;
+        newLeft -= 1;
+        newLine += 1;
+      }
+      continue;
+    }
+    if (line.startsWith("diff --git ")) {
+      file = undefined;
+    } else if (line.startsWith("+++ ")) {
+      file = patchHeaderPath(line.slice(4));
+    } else {
+      const hunk = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+      if (hunk) {
+        oldLeft = Number(hunk[1] ?? 1);
+        newLine = Number(hunk[2]);
+        newLeft = Number(hunk[3] ?? 1);
+      }
+    }
+  }
+  return found;
+}
+function patchHeaderPath(header) {
+  const target = header.endsWith("\t") ? header.slice(0, -1) : header;
+  if (target === "/dev/null")
+    return;
+  const name = target.length > 1 && target.startsWith('"') && target.endsWith('"') ? unquoteGitPath(target.slice(1, -1)) : target;
+  return name.replace(/^b\//, "");
+}
+function unquoteGitPath(quoted) {
+  const parts = [];
+  let literal = "";
+  for (let index = 0;index < quoted.length; index += 1) {
+    if (quoted[index] !== "\\" || index + 1 === quoted.length) {
+      literal += quoted[index];
+      continue;
+    }
+    parts.push(Buffer.from(literal, "utf8"));
+    literal = "";
+    const octal = /^[0-3][0-7]{2}/.exec(quoted.slice(index + 1))?.[0];
+    if (octal) {
+      parts.push(Buffer.from([Number.parseInt(octal, 8)]));
+      index += 3;
+    } else {
+      const next = quoted[index + 1];
+      parts.push(GIT_PATH_ESCAPES[next] === undefined ? Buffer.from(next, "utf8") : Buffer.from([GIT_PATH_ESCAPES[next]]));
+      index += 1;
+    }
+  }
+  parts.push(Buffer.from(literal, "utf8"));
+  return Buffer.concat(parts).toString("utf8");
+}
+function placeholderSection(lines) {
+  if (!lines.length)
+    return "";
+  const shown = lines.slice(0, PLACEHOLDER_LINES_SHOWN);
+  const more = lines.length - shown.length;
+  return `
+## Redaction placeholders
+
+These lines in the change carry a placeholder (numbered as in the new file).
+For each one, check that the placeholder stands where a credential's value
+was, and only there. Reject, naming the line, if it replaced something that is
+not a credential — part of a shell expansion such as \`\${PWD:t}\`, a path, a
+command, ordinary words — or if the text around it no longer holds together
+(a script that no longer parses, a broken config file). That holds even when
+it did replace a real credential: the other machines still receive a broken
+file, and the credential belongs outside the synced file. Some placeholders
+may have been typed by hand or come from content already published; judge
+them the same way.
+
+${shown.map((entry) => `- ${entry.file}:${entry.line}
+
+      ${entry.text}
+`).join(`
+`)}${more ? `
+…and ${more} more; find them in \`diff.patch\`.
+` : ""}`;
+}
 function opaqueSection(record) {
   const opaque = record.files.filter((file) => file.artifact);
   if (!opaque.length)
@@ -4765,7 +5036,7 @@ ${opaque.map((file) => `- \`${file.artifact}\` — ${file.path}`).join(`
 `)}
 `;
 }
-function reviewInstructions(record, config, guidelines) {
+function reviewInstructions(record, config, guidelines, placeholders) {
   return `# Sidecar publish review ${record.id}
 
 A sidecar is a scratchpad repository that syncs automatically to a shared Git
@@ -4773,8 +5044,9 @@ remote (${redactText(config.remote)}). This machine wants to publish the change
 \`diff.patch\`. Everyone with access to that remote can read what you approve,
 and it stays in the remote's history.
 
-Decide whether anything in the change should not leave this machine. This is
-not a code review: ignore quality, style, and correctness.
+Decide whether anything in the change should not leave this machine, and
+whether redaction damaged it. This is not a code review: ignore the quality,
+style, and correctness of what the author wrote.
 
 Secret redaction has already run. Values it caught appear as placeholders such
 as \`<API_KEY>\`, \`<TOKEN>\`, or \`<SECRET>\`; they are not leaks. Look for what
@@ -4785,6 +5057,11 @@ pattern matching misses:
 - confidential material: customer names and data, unreleased plans, internal-only details
 - anything the repository's guidelines below rule out
 
+Pattern matching also has false positives, and they are not harmless. A
+placeholder replaces the original text in the published file; every other
+machine that syncs this repository gets the placeholder in its own copy, while
+this machine keeps the original, so the author never sees the damage.
+${placeholderSection(placeholders)}
 ## Files
 
 All in this directory (\`$SIDECAR_REVIEW_DIR\`):
@@ -4882,7 +5159,7 @@ function decideReview(review, verdict, reason) {
   review.state = verdict;
   logSidecarEvent("review-decision", { id: review.record.id, verdict });
 }
-var REVIEW_SCHEMA = 1, KEEP_CLOSED_REVIEWS = 10, ID_PATTERN, LAUNCH_GRACE_SECONDS = 60, PACKET_DIFF_OPTIONS;
+var REVIEW_SCHEMA = 1, KEEP_CLOSED_REVIEWS = 10, ID_PATTERN, LAUNCH_GRACE_SECONDS = 60, PACKET_DIFF_OPTIONS, GIT_PATH_ESCAPES, PLACEHOLDER_LINES_SHOWN = 200;
 var init_review = __esm(() => {
   init_util();
   init_git();
@@ -4892,6 +5169,7 @@ var init_review = __esm(() => {
   init_redaction();
   ID_PATTERN = /^[0-9a-f]+$/;
   PACKET_DIFF_OPTIONS = ["-r", "--no-renames", "--ignore-submodules=none"];
+  GIT_PATH_ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
 });
 
 // src/sync.ts
@@ -4924,8 +5202,9 @@ function syncProject(root, config, options) {
   }
   if (!options.remote)
     return {};
-  if (reviewRequired(config))
-    return publishReviewed(root, sidecarPath, config, inbox, siblings, stage);
+  if (reviewRequired(config)) {
+    return publishReviewed(root, sidecarPath, config, inbox, siblings, stage, options.reviewFloor ?? false);
+  }
   stage("push-inbox");
   syncBranchBeforePush(sidecarPath, inbox, config);
   pushBranch(sidecarPath, inbox);
@@ -5025,7 +5304,7 @@ function publicTip(repo, branch) {
 function isPublic(repo, commit) {
   return Boolean(git(repo, ["for-each-ref", "--contains", commit, "--format=%(refname)", PUBLIC_REFS]).stdout.trim());
 }
-function publishReviewed(root, sidecarPath, config, inbox, siblings, stage) {
+function publishReviewed(root, sidecarPath, config, inbox, siblings, stage, reviewFloor) {
   stage("fetch");
   withPublicGit(sidecarPath, () => {
     fetchPublic(sidecarPath);
@@ -5043,12 +5322,25 @@ function publishReviewed(root, sidecarPath, config, inbox, siblings, stage) {
   stage("settle-remote");
   settleCheckouts(sidecarPath, config, inbox, siblings);
   stage("review");
-  const gate = withPublicGit(sidecarPath, () => gateUnpublished(root, sidecarPath, config));
-  if (gate?.launch)
+  const gate = withPublicGit(sidecarPath, () => gateUnpublished(root, sidecarPath, config, reviewFloor));
+  if (!gate)
+    return {};
+  if ("due" in gate)
+    return { reviewDue: gate.due };
+  if (gate.launch)
     launchReviewer(gate.review);
-  return gate ? { held: { review: gate.review, attention: reviewAttention(gate.review) } } : {};
+  return { held: { review: gate.review, attention: reviewAttention(gate.review) } };
+}
+function gateUnpublished(root, sidecarPath, config, floor) {
+  const configPath = peerConfigPath(root, config.peer);
+  const result = gateReview(root, sidecarPath, config, floor);
+  if (result && "due" in result)
+    writeReviewDue(configPath, result.due);
+  else
+    clearReviewDue(configPath);
+  return result;
 }
-function gateUnpublished(root, sidecarPath, config) {
+function gateReview(root, sidecarPath, config, floor) {
   const head = git(sidecarPath, ["rev-parse", `refs/heads/${config.branch}`]).stdout.trim();
   const headTree = treeOf(sidecarPath, head);
   const publicMain = publicTip(sidecarPath, config.branch);
@@ -5070,10 +5362,25 @@ function gateUnpublished(root, sidecarPath, config) {
       return { review: open, launch: false };
     markSuperseded(open);
   }
+  if (floor) {
+    const due = reviewFloorEndsAt(sidecarPath, config);
+    if (due > Date.now()) {
+      console.log(`the next review opens in ${Math.ceil((due - Date.now()) / 1000)}s; reviews open at most once per debounce`);
+      return { due };
+    }
+  }
   const review = createReview({ root, config, sidecarPath, base, head });
   console.log(`opened review ${paint("brand", review.record.id)} for ${review.record.files.length} changed file(s)`);
   return { review, launch: hasReviewer };
 }
+function reviewFloorEndsAt(sidecarPath, config) {
+  const previous = listReviews(sidecarPath)[0];
+  if (!previous)
+    return 0;
+  const { createdAt, launchedAt } = previous.record;
+  const started = Math.max(Date.parse(createdAt), launchedAt ? Date.parse(launchedAt) : 0);
+  return started + (config.debounce ?? DEFAULT_DEBOUNCE_SECONDS) * 1000;
+}
 function publishApprovedReview(sidecarPath, config, inbox, review) {
   const { record } = review;
   const target = record.publishing ?? { inbox, commit: cutPublishCommit(sidecarPath, config, inbox, record) };
@@ -5333,7 +5640,6 @@ function readFleetHealth(sidecarPath) {
   return entries.sort((left, right) => rank[left.state] - rank[right.state] || left.record.machine.localeCompare(right.record.machine) || left.branch.localeCompare(right.branch));
 }
 function mergeInboxBranches(sidecarPath, config, options) {
-  ensureClean(sidecarPath);
   ensureCommitIdentity(sidecarPath);
   if (options.remote)
     fetch(sidecarPath, false);
@@ -5353,9 +5659,11 @@ function mergeInboxBranches(sidecarPath, config, options) {
     }
   }
   if (!hasAnyCommit(sidecarPath)) {
+    ensureClean(sidecarPath);
     return mergeInboxBranchesAt(sidecarPath, config, options);
   }
   if (git(sidecarPath, ["branch", "--show-current"]).stdout.trim() === config.branch) {
+    ensureClean(sidecarPath);
     ensureInboxBranch(sidecarPath, config, expandInbox(config, sidecarPath));
   }
   return withScratchWorktree(sidecarPath, config, "HEAD", (worktree) => mergeInboxBranchesAt(worktree, config, options));
@@ -5915,7 +6223,7 @@ function syncBranchBeforePush(repo, branch, config) {
   if (isAncestor(repo, remoteBranch, "HEAD"))
     return;
   if (isDirty(repo)) {
-    throw new SidecarError(`${remoteBranch} has commits not in local ${branch}, and the sidecar checkout has uncommitted changes`);
+    throw new SidecarError(`${remoteBranch} has commits not in local ${branch}, and the sidecar checkout has uncommitted changes`, { reason: "dirty-checkout" });
   }
   if (isAncestor(repo, "HEAD", remoteBranch)) {
     git(repo, ["merge", "--ff-only", remoteBranch]);
@@ -5926,12 +6234,19 @@ function syncBranchBeforePush(repo, branch, config) {
 function refreshInboxFromMain(repo, config, inbox) {
   if (!branchExists(repo, inbox) || !branchExists(repo, config.branch))
     return;
-  ensureClean(repo);
+  if (isDirty(repo)) {
+    logSidecarEvent("settle-deferred", { sidecarPath: repo });
+    return;
+  }
   git(repo, ["switch", inbox]);
   const result = git(repo, ["merge", "--ff-only", config.branch], { check: false });
-  if (result.status !== 0) {
-    throw new SidecarError(result.stderr.trim() || `could not fast-forward ${inbox} to ${config.branch}`);
+  if (result.status === 0)
+    return;
+  if (isDirty(repo)) {
+    logSidecarEvent("settle-deferred", { sidecarPath: repo });
+    return;
   }
+  throw new SidecarError(result.stderr.trim() || `could not fast-forward ${inbox} to ${config.branch}`);
 }
 function pushBranch(repo, branch) {
   git(repo, ["push", "--no-follow-tags", "-u", "origin", `HEAD:refs/heads/${branch}`]);
@@ -6203,7 +6518,7 @@ function pendingInboxBranches(repo, config) {
   });
   return [...local, ...remote].sort();
 }
-var REVIEW_POLICY_KEY = "sidecar.review", WRITTEN_TRAILER = "written:", WRITTEN_TRAILER_LIMIT = 500, REDACTION_FILTER_NAME = "sidecar-redact", REDACTION_FILTER_REVISION = "2", REDACTION_POLICY_FILE = "sidecar-redaction-policy";
+var REVIEW_POLICY_KEY = "sidecar.review", WRITTEN_TRAILER = "written:", WRITTEN_TRAILER_LIMIT = 500, REDACTION_FILTER_NAME = "sidecar-redact", REDACTION_FILTER_REVISION = "3", REDACTION_POLICY_FILE = "sidecar-redaction-policy";
 var init_sync = __esm(() => {
   init_color();
   init_util();
@@ -8229,6 +8544,7 @@ __export(exports_daemon, {
   selectWatchTargets: () => selectWatchTargets,
   scheduleFor: () => scheduleFor,
   runDaemonLoop: () => runDaemonLoop,
+  reviewDueAt: () => reviewDueAt,
   refreshWatchers: () => refreshWatchers,
   compileGitignoreMatcher: () => compileGitignoreMatcher,
   checkAndInstallUpdate: () => checkAndInstallUpdate,
@@ -8299,6 +8615,7 @@ async function runDaemonLoop(options) {
   await acquireDaemonPid();
   installShutdownHandlers();
   await watchRegistry(state);
+  await watchReviewDue(state);
   const bootVersion = packageVersion();
   while (true) {
     maybeAdoptNewerInstall(state, bootVersion);
@@ -8411,10 +8728,11 @@ async function syncInstance(state, key, trigger, options = {}) {
   state.syncingFamilies.add(family);
   if (!options.localOnly) {
     state.lastRemoteSyncAt.set(key, Date.now());
-    clearTimeout(state.remoteTimers.get(key));
+    clearTimeout(state.remoteTimers.get(key)?.timer);
     state.remoteTimers.delete(key);
   }
   let succeeded = false;
+  let dirtyCheckout = false;
   try {
     const localCli = localSidecarCliPath(root);
     const cli = localCli ?? currentCliPath();
@@ -8431,19 +8749,27 @@ async function syncInstance(state, key, trigger, options = {}) {
       },
       timeoutMs: SYNC_TIMEOUT_MS
     });
+    dirtyCheckout = !result.timedOut && result.status === DIRTY_CHECKOUT_EXIT;
     if (result.status === 0) {
-      state.failures.delete(key);
-      state.skipUntilCycle.delete(key);
+      if (!options.localOnly) {
+        state.failures.delete(key);
+        state.skipUntilCycle.delete(key);
+      }
       logSidecarEvent("daemon-sync", { ...peerFields(key), trigger, local: Boolean(localCli) });
       succeeded = true;
     } else {
-      const failures = (state.failures.get(key) ?? 0) + 1;
-      state.failures.set(key, failures);
-      state.skipUntilCycle.set(key, state.cycleCount + Math.min(2 ** (failures - 1), MAX_BACKOFF_CYCLES));
+      if (!dirtyCheckout) {
+        const failures = (state.failures.get(key) ?? 0) + 1;
+        state.failures.set(key, failures);
+        state.skipUntilCycle.set(key, state.cycleCount + Math.min(2 ** (failures - 1), MAX_BACKOFF_CYCLES));
+      }
+      if (!options.localOnly)
+        state.lastRemoteSyncAt.set(key, Date.now());
       logSidecarEvent("failure", {
         command: "daemon",
         ...peerFields(key),
         trigger,
+        reason: result.timedOut ? "timeout" : dirtyCheckout ? "dirty-checkout" : `exit-${result.status}`,
         message: result.timedOut ? "sync timed out" : !outputIsPrivate(key) && result.output.trim().slice(-500) || `sync exited ${result.status}`
       });
     }
@@ -8453,12 +8779,24 @@ async function syncInstance(state, key, trigger, options = {}) {
     if (options.localOnly)
       armRemoteSync(state, key);
   }
-  if (succeeded)
+  if (succeeded) {
+    if (!options.localOnly)
+      armReviewDue(state, key, "after-sync");
     await followUpTrailingSync(state, key);
-  else
-    state.trailingPending.delete(key);
+  } else {
+    followUpFailedSync(state, key, { dirtyCheckout, remote: !options.localOnly });
+  }
   return succeeded;
 }
+function followUpFailedSync(state, key, failure) {
+  if (failure.dirtyCheckout) {
+    state.trailingPending.add(key);
+    if (failure.remote)
+      armRemoteSync(state, key);
+  }
+  if (state.trailingPending.has(key) && !state.pendingTimers.has(key))
+    openTrailingWindow(state, key, SETTLE_WINDOW_MS);
+}
 async function followUpTrailingSync(state, key) {
   if (!state.trailingPending.delete(key))
     return;
@@ -8474,7 +8812,9 @@ async function checkoutIsDirty(key) {
   if (!sidecarPath || !fs14.existsSync(sidecarPath))
     return false;
   const result = await runChild("git", ["-C", sidecarPath, "status", "--porcelain"], { timeoutMs: 30000 });
-  return result.status === 0 && Boolean(result.stdout.trim());
+  if (result.status !== 0)
+    return true;
+  return Boolean(result.stdout.trim());
 }
 function localSidecarCliPath(root) {
   if (!projectDependsOnSidecar(root))
@@ -8602,14 +8942,38 @@ async function beginWatchSync(state, key) {
     state.trailingPending.add(key);
 }
 function armRemoteSync(state, key) {
-  if (state.remoteTimers.has(key))
-    return;
   const elapsed = Date.now() - (state.lastRemoteSyncAt.get(key) ?? 0);
+  armRemoteAt(state, key, Date.now() + Math.max(SETTLE_WINDOW_MS, scheduleFor(key, state.options).debounceSeconds * 1000 - elapsed), "remote-due");
+}
+function armRemoteAt(state, key, at, trigger) {
+  const booked = state.remoteTimers.get(key);
+  if (booked && booked.at <= at)
+    return;
+  clearTimeout(booked?.timer);
   const timer = setTimeout(() => {
     state.remoteTimers.delete(key);
-    syncInstance(state, key, "remote-due");
-  }, Math.max(SETTLE_WINDOW_MS, scheduleFor(key, state.options).debounceSeconds * 1000 - elapsed));
-  state.remoteTimers.set(key, timer);
+    syncInstance(state, key, trigger);
+  }, Math.max(0, at - Date.now()));
+  state.remoteTimers.set(key, { timer, at });
+}
+function armReviewDue(state, key, when) {
+  const at = reviewDueAt(readReviewDue(key), when, Date.now(), scheduleFor(key, state.options).debounceSeconds * 1000, comingBack(state, key));
+  if (at !== undefined)
+    armRemoteAt(state, key, at, "review-due");
+}
+function comingBack(state, key) {
+  return state.syncing.has(key) || state.remoteTimers.has(key) || state.cycleCount < (state.skipUntilCycle.get(key) ?? 0);
+}
+function reviewDueAt(due, when, now, debounceMs, comingBack2) {
+  if (due === undefined)
+    return;
+  if (due > now)
+    return due;
+  if (when === "start")
+    return now;
+  if (when === "after-sync")
+    return now + Math.max(SETTLE_WINDOW_MS, debounceMs);
+  return comingBack2 ? undefined : now;
 }
 function remoteIsDue(state, key) {
   const last = state.lastRemoteSyncAt.get(key) ?? 0;
@@ -8653,6 +9017,34 @@ async function watchRegistry(state) {
     });
   }
 }
+async function watchReviewDue(state) {
+  const scan = (when) => {
+    for (const instance of readInstances())
+      armReviewDue(state, instance.configPath, when);
+  };
+  scan("start");
+  const chokidar = await loadChokidar();
+  if (!chokidar)
+    return;
+  try {
+    fs14.mkdirSync(reviewDueDir(), { recursive: true });
+    const watcher = chokidar.watch(reviewDueDir(), { ignoreInitial: true, depth: 0 });
+    let timer;
+    watcher.on("all", () => {
+      if (timer)
+        return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        scan("change");
+      }, 500);
+    });
+  } catch (error) {
+    logSidecarEvent("failure", {
+      command: "daemon",
+      message: `could not watch review due times: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+}
 function compileGitignoreMatcher(lines) {
   const rules = import_ignore.default({ ignorecase: false }).add(lines);
   return (relativePath) => {
@@ -8978,7 +9370,7 @@ async function cmdDaemonRun(args) {
   if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
     throw new SidecarError("--interval must be > 0");
   }
-  const debounceSeconds = Number(getValue(parsed, "--debounce", "60"));
+  const debounceSeconds = Number(getValue(parsed, "--debounce", String(DEFAULT_DEBOUNCE_SECONDS)));
   if (!Number.isFinite(debounceSeconds) || debounceSeconds < 0) {
     throw new SidecarError("--debounce must be >= 0");
   }
@@ -9102,7 +9494,8 @@ function cmdSync(args) {
     lock: soft ? "skip" : "throw",
     remote: !parsed.flags.has("--local") && process.env[LOCAL_SYNC_ENV] !== "1",
     snapshot: !parsed.flags.has("--no-snapshot"),
-    message: getValue(parsed, "--message", getValue(parsed, "-m", "")) || undefined
+    message: getValue(parsed, "--message", getValue(parsed, "-m", "")) || undefined,
+    reviewFloor: soft
   };
   for (const peer of peers) {
     announcePeer(peer, peers);
@@ -9113,12 +9506,13 @@ function cmdSync(args) {
     } catch (error) {
       if (peers.length === 1)
         throw error;
-      failed.push(peer.name);
+      failed.push({ name: peer.name, error });
       console.error(`sidecar: ${peer.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
   if (failed.length) {
-    throw new SidecarError(`${failed.length} of ${peers.length} peers failed to sync: ${failed.join(", ")}`);
+    const dirty = failed.every(({ error }) => error instanceof SidecarError && error.reason === "dirty-checkout");
+    throw new SidecarError(`${failed.length} of ${peers.length} peers failed to sync: ${failed.map(({ name }) => name).join(", ")}`, dirty ? { reason: "dirty-checkout" } : {});
   }
   return 0;
 }
@@ -9135,6 +9529,7 @@ function syncPeer(peer, options) {
         snapshot: options.snapshot,
         remote,
         message: options.message,
+        reviewFloor: options.reviewFloor,
         onStage: (name) => {
           stage = name;
         }
@@ -9142,6 +9537,8 @@ function syncPeer(peer, options) {
       registerCurrentInstance(root, config, remote ? { event: "sync", lastSyncAt: nowIso() } : { event: "sync-local" });
     });
   } catch (error) {
+    if (error instanceof SidecarError)
+      error.stage ??= stage;
     if (remote)
       reportSyncHealth(root, config, {
         status: "failed",
@@ -9156,8 +9553,9 @@ function syncPeer(peer, options) {
       const { id } = held.review.record;
       console.log(held.attention ? `sidecar: publishing is held — review ${id} needs attention: ${held.attention}; \`sidecar review show ${id}\`` : `sidecar: publishing is held for review ${id}; \`sidecar review show ${id}\``);
     }
-    if (remote)
-      reportSyncHealth(root, config, held ? { status: "ok", review: held.attention ? "attention" : "pending" } : { status: "ok" });
+    if (remote) {
+      reportSyncHealth(root, config, held ? { status: "ok", review: held.attention ? "attention" : "pending" } : outcome.reviewDue ? { status: "ok", review: "pending" } : { status: "ok" });
+    }
     if (!soft) {
       const sidecarPath = resolveSidecarPath(root, config);
       if (checkoutIsUnlinkedFromFamily(root, config, sidecarPath)) {
@@ -9425,7 +9823,20 @@ function decideCommand(verdict, args) {
     return 0;
   }
   const peer = loadPeer(selected.record.root, selected.record.peer);
-  syncPeer(peer, { lock: "wait", remote: true, snapshot: true });
+  try {
+    syncPeer(peer, { lock: "wait", remote: true, snapshot: true, reviewFloor: true });
+  } catch (error) {
+    if (readReview(id)?.state !== "published") {
+      console.error(`sidecar: review ${id} is approved, but this sync could not confirm it published; the next sync finishes publishing it`);
+      throw error;
+    }
+    logSidecarEvent("review-followup-failure", {
+      id,
+      ...error instanceof SidecarError && error.reason ? { reason: error.reason } : {},
+      ...error instanceof SidecarError && error.stage ? { stage: error.stage } : {}
+    });
+    console.error(`sidecar: published review ${id}; the sync after it stopped early and the next sync finishes it: ${error instanceof Error ? error.message : String(error)}`);
+  }
   return 0;
 }
 function retryCommand(args) {
@@ -9680,12 +10091,14 @@ async function main(argv = process.argv.slice(2)) {
     if (command !== "redact" && command !== "deinit" && shouldUseGlobalRegistry()) {
       logSidecarEvent("failure", {
         command,
+        ...error instanceof SidecarError && error.reason ? { reason: error.reason } : {},
+        ...error instanceof SidecarError && error.stage ? { stage: error.stage } : {},
         ...privateFailures() ? {} : { message: error instanceof Error ? error.message : String(error) }
       });
     }
     if (error instanceof SidecarError) {
       console.error(`${paint("bad", "sidecar:", colorLevel(process.stderr))} ${error.message}`);
-      return 1;
+      return error.reason === "dirty-checkout" ? DIRTY_CHECKOUT_EXIT : 1;
     }
     if (error instanceof Error && error.name === "AbortError") {
       console.error("sidecar: stopped");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecarsync",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "A Git-backed sidecar inbox for repo-local development metadata.",
   "license": "MIT",
   "repository": {