@cohortapp/agent-sdk 2.18.14 → 2.18.16

package/scripts/fleet/rollout.mjs

@@ -102,6 +102,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_THRESHOLDS } from "../../lib/telemetry/alerts.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const REPO_ROOT = resolvePath(dirname(__filename), "..", "..");
@@ -394,6 +395,130 @@ export function seatVersions(entry) {
   return { installed, running, version, basis: version === null ? null : running ? "running" : "installed" };
 }
 
+/**
+ * How long a failed upgrade attempt may stand, unrepeated, before a seat that
+ * is still on the version it failed FROM counts as stuck rather than merely
+ * recovering. Two full failed-target holds (the autoupdater's default is 24 h):
+ * one hold is the seat being deliberately left alone, two means the retry it
+ * was owed has been and gone.
+ */
+export const ATTEMPT_STALE_MS = 48 * 60 * 60 * 1000;
+
+/**
+ * Consecutive failed attempts that make a seat stuck.
+ *
+ * DERIVED, NOT RESTATED. This used to be `= 3` with a comment promising it
+ * "matches lib/telemetry/alerts.mjs upgradeStuck.warnStreak" — a prose promise
+ * about a literal, which is the exact shape the repo doctrine bans and which no
+ * test could have caught: this file's own tests use the constant symbolically
+ * (`at(STUCK_STREAK - 1)` / `at(STUCK_STREAK)`), so they pass at ANY value and
+ * the two copies could have drifted silently. The seat-side alert rule is the
+ * authority — it is what actually fires on a live beat — so this reads it.
+ *
+ * The third copy lives in the shell (`STUCK_STREAK` in
+ * scripts/local-triggers/autoupdate.sh), which cannot import this; it is pinned
+ * against this value by a source-reading test instead
+ * (scripts/local-triggers/autoupdate.test.mjs, "source: the shell's streak
+ * threshold is the same number the alert fires on").
+ */
+export const STUCK_STREAK = DEFAULT_THRESHOLDS.upgradeStuck.warnStreak;
+
+/**
+ * The first SDK release whose `write_last` keeps a `failStreak` in
+ * state/autoupdate/last.json. A seat below this reports one upgrade outcome and
+ * no count — not because its beat is stale, but because the collector that
+ * would write the count is the code it has not got.
+ *
+ * This exists because the "attempt" basis used to explain itself with "this
+ * seat's beat is too old to carry a count", attached unconditionally to every
+ * attempt-basis row. At rollout time NO released SDK wrote `failStreak`, so
+ * every seat in the fleet — including ones beating every 30 seconds with
+ * `reason` and `healthy` on the record — was told its beat was too old. The
+ * beat age was never the reason; the seat's VERSION is.
+ */
+export const FAILSTREAK_SINCE = "2.18.15";
+
+/**
+ * IS THIS SEAT STUCK — i.e. has it tried to reach @latest and failed, and will
+ * it keep failing?
+ *
+ * `classifySeat` says a seat is `stale`. That is a snapshot and it is not the
+ * finding: a seat is stale for twenty minutes after every publish, and three
+ * seats were stale for three weeks. What separates them is whether the seat has
+ * ATTEMPTED the hop and failed, and how many times — and that fact has always
+ * been in the beat (`machine.upgrade`) without anything reading it.
+ *
+ * TWO BASES, BECAUSE THE SEATS THIS MATTERS FOR REPORT THE LEAST. A seat that
+ * has been left behind for weeks is by definition running the oldest collector
+ * in the fleet, so it emits the smallest beat: on 2026-09-25 the three seats on
+ * 2.17.0 were the only three in the org with no `machine.daemon` block and no
+ * `machine.stranded` — staleness hides itself by removing the fields that would
+ * announce it. So this reads what a 2.17-era beat DOES carry, and names which
+ * basis it used rather than pretending to one answer:
+ *
+ *   basis "streak"  — the seat counted its own consecutive failures
+ *                     (`machine.upgrade.failStreak`, SDK {@link FAILSTREAK_SINCE}
+ *                     and later). Stuck at {@link STUCK_STREAK}. The real signal.
+ *   basis "attempt" — an old beat, which carries one outcome and no count. A
+ *                     failed attempt (`ok:false`, `to` != `from`) with the seat
+ *                     STILL reporting `from` proves the hop did not take; older
+ *                     than {@link ATTEMPT_STALE_MS} it also proves the retry it
+ *                     was owed came and went. Below that age it is `failing`,
+ *                     not `stuck` — which is the same rule the streak obeys and
+ *                     the same rule (d) asks for: a seat that has not been
+ *                     ASKED again is not a stuck seat.
+ *
+ * Returns null when the beat carries no upgrade record at all: never tried is
+ * not the same as tried and failed, and must not print as one.
+ *
+ * Pure; `now` is a parameter because the "attempt" basis is about a duration.
+ *
+ * @param {object} entry   a directory member, or anything {@link seatVersions} accepts
+ * @param {number} [now]   epoch ms
+ * @returns {{verdict:"stuck"|"failing", basis:"streak"|"attempt", failStreak:number|null,
+ *            target:string|null, since:string|null, ageMs:number|null}|null}
+ */
+export function seatStuck(entry, now = Date.now()) {
+  const e = entry && typeof entry === "object" ? entry : {};
+  const st = (e.status && typeof e.status === "object" && e.status) || {};
+  const mach = (st.machine && typeof st.machine === "object" && st.machine) || (e.machine && typeof e.machine === "object" && e.machine) || {};
+  const u = mach.upgrade && typeof mach.upgrade === "object" ? mach.upgrade : null;
+  if (!u) return null;
+
+  const streak = Number.isInteger(u.failStreak) && u.failStreak > 0 ? u.failStreak : null;
+  const target = firstString([u.streakTarget, u.to]);
+  if (streak !== null) {
+    const sinceS = firstString([u.stuckSince, u.at]);
+    const sinceMs = sinceS ? Date.parse(sinceS) : NaN;
+    return {
+      verdict: streak >= STUCK_STREAK ? "stuck" : "failing",
+      basis: "streak",
+      failStreak: streak,
+      target,
+      since: sinceS,
+      ageMs: Number.isFinite(sinceMs) ? now - sinceMs : null,
+    };
+  }
+
+  // Degraded read: one outcome, no count.
+  if (u.ok !== false) return null;
+  const from = typeof u.from === "string" ? u.from : "";
+  const to = typeof u.to === "string" ? u.to : "";
+  if (!from || !to || from === to) return null;           // not an upgrade attempt
+  const installed = seatVersions(e).installed;
+  if (installed && installed !== from) return null;       // it has moved since; whatever failed is history
+  const atMs = typeof u.at === "string" ? Date.parse(u.at) : NaN;
+  const ageMs = Number.isFinite(atMs) ? now - atMs : null;
+  return {
+    verdict: ageMs !== null && ageMs > ATTEMPT_STALE_MS ? "stuck" : "failing",
+    basis: "attempt",
+    failStreak: null,
+    target: to,
+    since: typeof u.at === "string" ? u.at : null,
+    ageMs,
+  };
+}
+
 /**
  * The single version a seat is judged on, or null when the read carries none.
  * Kept as its own export because it is the whole of what `classifySeat` needs;
@@ -420,8 +545,17 @@ export function seatVersion(entry) {
  * cannot see, and it would be wrong on whichever side of the hq deploy it was
  * not written for.
  *
+ * Each row also carries `wedged` (bool) and `wedgeReason` (string|null),
+ * derived from the same `machine` block {@link seatStuck} reads: a seat is
+ * wedged when the beat itself reports `machine.wedge.reason` (published by
+ * collect.mjs's sessionWedge — beating, but not reading its inbox/handoffs),
+ * OR when `machine.frontDoor === "session"` and `machine.sessionLive === false`
+ * (the front door is shut outright). The version stays on the row either way —
+ * wedged is a verdict {@link classifySeat} applies, not a fact this function
+ * withholds.
+ *
  * @param {object[]} members
- * @param {{seatWindowMs?:number}} [o]
+ * @param {{seatWindowMs?:number, now?:number}} [o]
  * @returns {{seats:object[], nonSeats:object[], readCarriesVersionField:boolean}}
  */
 export function toSeats(members, o = {}) {
@@ -438,6 +572,10 @@ export function toSeats(members, o = {}) {
     }
     const p = m.presence && typeof m.presence === "object" ? m.presence : null;
     const beatMs = p && Number.isFinite(p.lastBeatMs) ? p.lastBeatMs : null;
+    // Same accessor seatStuck uses: the beat's machine block, wherever it hangs.
+    const mach = (m.status && typeof m.status === "object" && m.status.machine) || m.machine || {};
+    const wedge = mach.wedge && typeof mach.wedge === "object" ? mach.wedge : null;
+    const doorDown = mach.frontDoor === "session" && mach.sessionLive === false;
     const row = {
       id: String(m.id || ""),
       slug: String(m.slug || ""),
@@ -446,6 +584,9 @@ export function toSeats(members, o = {}) {
       detail: (p && p.detail) || "",
       lastBeatMs: beatMs,
       ...seatVersions(m),
+      stuck: seatStuck(m, o.now),
+      wedged: !!((wedge && wedge.reason) || doorDown),
+      wedgeReason: (wedge && typeof wedge.reason === "string" && wedge.reason) || (doorDown ? "front-door-not-live" : null),
     };
     if (beatMs !== null && beatMs <= windowMs) seats.push(row);
     else nonSeats.push(row);
@@ -456,14 +597,18 @@ export function toSeats(members, o = {}) {
 
 /**
  * Verdict for one seat against the target version. Pure.
+ *   wedged       — beating, but its front door is not answering (a shut
+ *                  session or an overdue handoff); outranks current/stale —
+ *                  the version stays on the row for display, unread here
  *   current      — reported version equals the target
  *   stale        — reported a different (older or newer) version
  *   unverifiable — beating, but the read carries no version at all
  * @param {object} seat
  * @param {string} target
- * @returns {"current"|"stale"|"unverifiable"}
+ * @returns {"wedged"|"current"|"stale"|"unverifiable"}
  */
 export function classifySeat(seat, target) {
+  if (seat && seat.wedged) return "wedged";
   const v = seat && seat.version;
   if (!v) return "unverifiable";
   return compareVersions(v, target) === 0 ? "current" : "stale";
@@ -478,17 +623,43 @@ export function classifySeat(seat, target) {
  */
 export function summarise(fleet, target) {
   const rows = (fleet.seats || []).map((s) => ({ ...s, verdict: classifySeat(s, target) }));
-  const counts = { current: 0, stale: 0, unverifiable: 0 };
+  const counts = { current: 0, stale: 0, unverifiable: 0, wedged: 0 };
   for (const r of rows) counts[r.verdict] += 1;
+  // Behind AND proved it cannot arrive — a strictly stronger statement than
+  // `stale`, which clears itself on the next hourly run.
+  //
+  // `stuck` IS NOT A SUBSET OF `stale`, and the code used to assume it was. A
+  // seat's verdict is about THIS run's target; its streak is about whatever
+  // `@latest` was when it last tried, and the two are different versions
+  // whenever a rollout is verified against anything but the registry's head —
+  // `--dry-run`, `--verify-only`, or simply a publish that has since been
+  // followed by another. Demonstrated: one seat on target 2.18.14 whose record
+  // is {ok:false, from:"2.18.14", to:"2.18.15", failStreak:5} classifies
+  // `current`, so `stale` is empty, `done` was true, and renderVerdict's early
+  // return printed "All 1 seat(s) report 2.18.14." — five consecutive failed
+  // upgrades reported as a fully current fleet. So the two sets are kept and
+  // named apart, and `done` answers BOTH questions: every seat is on the target
+  // AND no seat is known to be unable to move.
+  const stuck = rows.filter((r) => r.stuck && r.stuck.verdict === "stuck");
+  const stale = rows.filter((r) => r.verdict === "stale");
+  const wedged = rows.filter((r) => r.verdict === "wedged");
+  const staleSlugs = new Set(stale.map((r) => r.slug));
   return {
     target,
     rows,
     counts,
     nonSeats: fleet.nonSeats || [],
-    stale: rows.filter((r) => r.verdict === "stale"),
+    stale,
     unverifiable: rows.filter((r) => r.verdict === "unverifiable"),
+    stuck,
+    /** The stuck seats that are ALSO behind this run's target — "N of those". */
+    stuckBehind: stuck.filter((r) => staleSlugs.has(r.slug)),
+    /** Stuck against some other version while current on this one. Still a finding. */
+    stuckElsewhere: stuck.filter((r) => !staleSlugs.has(r.slug)),
+    /** Beating, but its front door is not answering — a 4th verdict beside stale. */
+    wedged,
     readCarriesVersionField: fleet.readCarriesVersionField === true,
-    done: rows.length > 0 && counts.current === rows.length,
+    done: rows.length > 0 && counts.current === rows.length && stuck.length === 0 && wedged.length === 0,
   };
 }
 
@@ -518,7 +689,7 @@ export function renderSeatTable(summary, o = {}) {
     r.slug,
     ageLabel(r.lastBeatMs),
     r.version ? (r.basis === "installed" ? `${r.version} (installed)` : r.version) : "unknown",
-    r.verdict,
+    r.stuck ? `${r.verdict} · ${r.stuck.verdict}${r.stuck.failStreak ? ` ×${r.stuck.failStreak}` : ""}` : r.verdict,
   ]);
   const widths = head.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length), 0));
   const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
@@ -538,9 +709,19 @@ export function renderSeatTable(summary, o = {}) {
   return out.join("\n");
 }
 
-/** The closing sentence naming exactly which seats are behind. Pure. */
+/**
+ * The closing sentence naming exactly which seats are behind, and which of them
+ * will never arrive unaided. Pure.
+ *
+ * NO EARLY RETURN ON `done`. It used to open with
+ * `if (summary.done) return "All N seat(s) report X."`, which swallowed the
+ * STUCK line whole for any seat that was stuck against a version other than
+ * this run's target — see the note in {@link summarise}. `done` now accounts
+ * for stuck seats, and the "all clear" sentence is built at the END, from the
+ * absence of every finding, so a future finding cannot be skipped past by a
+ * `done` that did not learn about it.
+ */
 export function renderVerdict(summary) {
-  if (summary.done) return `All ${summary.rows.length} seat(s) report ${summary.target}.`;
   const parts = [];
   if (summary.stale.length) {
     parts.push(
@@ -548,6 +729,27 @@ export function renderVerdict(summary) {
         summary.stale.map((r) => `${r.name} (${r.slug}, reports ${r.version})`).join(", ")
     );
   }
+  const stuck = (summary.stuck && summary.stuck.length ? summary.stuck : []);
+  if (stuck.length) {
+    // Said SEPARATELY from "behind", and after it, because the response is
+    // different: a behind seat is waited on, a stuck one is visited. The line
+    // that was missing for three weeks is this one.
+    const behind = summary.stuckBehind || stuck.filter((r) => r.verdict === "stale");
+    const elsewhere = summary.stuckElsewhere || stuck.filter((r) => r.verdict !== "stale");
+    // "N of those" is only true of the ones that ARE among the seats just named
+    // as behind. A seat that is current on this target and stuck against a
+    // later one is not "one of those" and must not be counted as if it were.
+    const head =
+      elsewhere.length === 0
+        ? `${behind.length} of those ${behind.length === 1 ? "is" : "are"} STUCK`
+        : behind.length === 0
+          ? `${elsewhere.length} seat(s) ${elsewhere.length === 1 ? "is" : "are"} STUCK — on ${summary.target}, but unable to move off it`
+          : `${stuck.length} seat(s) are STUCK (${behind.length} of those just named as behind, ${elsewhere.length} current on ${summary.target} but unable to move off it)`;
+    parts.push(
+      `${head} — attempted and failed, and will not arrive unaided: ` +
+        stuck.map((r) => `${r.name} (${r.slug}, ${stuckClause(r, summary.target)})`).join(", ")
+    );
+  }
   if (summary.unverifiable.length) {
     parts.push(
       `${summary.unverifiable.length} seat(s) could not be verified — the org read carries no sdkVersion: ` +
@@ -555,9 +757,46 @@ export function renderVerdict(summary) {
     );
   }
   if (!summary.rows.length) parts.push("no beating seats found in the org directory — nothing to verify.");
+  if (!parts.length) return `All ${summary.rows.length} seat(s) report ${summary.target}.`;
   return parts.join("\n");
 }
 
+/**
+ * One stuck seat's parenthetical: what it tried, how many times, and — only
+ * when it is true — why it cannot say how many times.
+ *
+ * THE "no count" SENTENCE IS GATED ON THE SEAT'S VERSION, NOT ON THE BRANCH
+ * THAT PRODUCED THE VERDICT. It used to hang off `basis === "attempt"` and
+ * read "this seat's beat is too old to carry a count". Every attempt-basis row
+ * got it, which at the time this landed was every row in the fleet — no
+ * released SDK wrote `failStreak` yet — including seats beating every thirty
+ * seconds whose records demonstrably carried `reason` and `healthy`. The beat
+ * was never old; the seat's SDK simply predates {@link FAILSTREAK_SINCE}. When
+ * the seat is new enough to count and still did not, that is a DIFFERENT and
+ * more interesting fact, so it gets its own words. Pure.
+ *
+ * @param {object} row  a summarise() row with a non-null `stuck`
+ * @param {string} target
+ * @returns {string}
+ */
+export function stuckClause(row, target) {
+  const st = row.stuck;
+  const attempts = st.failStreak ? `${st.failStreak} consecutive failed attempts` : "a failed attempt";
+  const oldest = Number.isFinite(st.ageMs) ? `, oldest ${ageLabel(st.ageMs)} ago` : "";
+  let why = "";
+  if (st.basis === "attempt") {
+    const v = row.version;
+    if (v && compareVersions(v, FAILSTREAK_SINCE) < 0) {
+      why = `; it reports ${v}, which predates the failure count (SDK ${FAILSTREAK_SINCE}), so one attempt is all it can report`;
+    } else if (v) {
+      why = `; it reports ${v}, new enough to count its failures, but this record carries none — read state/autoupdate/last.json on the machine`;
+    } else {
+      why = "; this seat reports no version, so there is no telling whether it could have counted";
+    }
+  }
+  return `${attempts} to ${st.target || target}${oldest}${why}`;
+}
+
 /**
  * What stage 3's exit code will be, and WHY — as data, so a caller can tell the
  * three very different things a `3` means apart.
@@ -576,10 +815,18 @@ export function renderVerdict(summary) {
  * exit code: `behind` and `unverifiable` are different problems with different
  * fixes, and only the first is answered by waiting.
  *
+ * `wedged` is a fourth problem with a fourth fix: the seat is beating (so it is
+ * not `unverifiable`, and waiting for its next beat proves nothing) but its
+ * front door is not answering — a shut session or an overdue handoff. It is
+ * checked after `stuck` (stuck is the longer-standing, already-acted-on
+ * signal) and before `empty-fleet`/`unverifiable`/`behind`: reporting a wedged
+ * seat as merely "behind" would invite waiting it out, and waiting does
+ * nothing for a seat that is not reading.
+ *
  * Pure.
  *
  * @param {ReturnType<typeof summarise>|null|undefined} summary
- * @returns {{code:number, reason:"verified"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
+ * @returns {{code:number, reason:"verified"|"stuck"|"wedged"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
  */
 export function propagationOutcome(summary) {
   if (!summary || !Array.isArray(summary.rows)) {
@@ -590,6 +837,42 @@ export function propagationOutcome(summary) {
     };
   }
   if (summary.done) return { code: 0, reason: "verified", note: null };
+  // STUCK OUTRANKS BEHIND, and is checked before both `empty-fleet` and the
+  // unverifiable branch, because it is the only one of the three that a person
+  // must ACT on rather than wait out.
+  //
+  // This is also the automation the seat-side alert cannot provide. `upgrade_stuck`
+  // is derived by lib/telemetry/alerts.mjs running ON the seat, so a seat too
+  // stale to install the SDK never emits it — by construction the alert cannot
+  // reach the seats it is for. What CAN reach them is this: the fleet-side
+  // derivation runs on every publish, because stage 3 runs on every publish,
+  // and a stuck seat now makes the release command exit non-zero and name the
+  // machine. Nobody has to decide to go looking.
+  if (summary.stuck && summary.stuck.length) {
+    return {
+      code: 3,
+      reason: "stuck",
+      note:
+        `${summary.stuck.length} seat(s) have attempted @latest and failed repeatedly. They will not arrive on their own: ` +
+        `each needs a person at the machine (maestro doctor; state/autoupdate/last.json carries the reason). ` +
+        `Stage 3 still polls to its deadline in case someone clears one while it runs, but it will not clear itself. ` +
+        renderVerdict(summary),
+    };
+  }
+  // WEDGED comes after stuck (stuck is longer-standing and still the one a
+  // person must act on first) but before empty-fleet/unverifiable/behind: a
+  // seat that is beating but not reading is not a seat anyone can wait out
+  // either, and it must not be reported as merely "behind" — waiting changes
+  // nothing when the front door itself is what is not answering.
+  if (summary.wedged && summary.wedged.length) {
+    return {
+      code: 3,
+      reason: "wedged",
+      note:
+        `${summary.wedged.length} seat(s) are beating but their front door is not answering (wedged) — the ` +
+        `daemon revive or a person must clear them; a version cannot be verified on a seat that is not reading.`,
+    };
+  }
   if (!summary.rows.length) {
     return {
       code: 3,

package/scripts/hooks/pre-write-yaml-validate.mjs

@@ -17,7 +17,14 @@
  * old_string replaced by new_string) and REFUSES — exit 2, a permissionDecision:"deny" JSON on
  * stdout and the reason on stderr — when:
  *   - an Edit's old_string is absent from the file, or matches more than once without
- *     replace_all (the edit would land somewhere the writer did not look at);
+ *     replace_all (the edit would land somewhere the writer did not look at); when that repeated
+ *     match is an `id:` line, the refusal names the real cause — the file already carries a
+ *     duplicate id and is unwritable via id-anchored edits until the collision is resolved;
+ *   - the would-be top-level `items:` list (or a top-level sequence) would carry two rows sharing
+ *     the same `id` value that was not already colliding on disk. A duplicate id slips past js-yaml
+ *     (the rows are distinct list entries, not duplicate map keys) but makes every id-anchored edit
+ *     ambiguous — the "collision then silently unwritable all day" failure — so it is refused loudly
+ *     as a WHOLE FILE BLOCK at the write boundary;
  *   - the result does not parse as YAML (js-yaml, which also rejects duplicate keys);
  *   - a provenance-keyed value NEW in this write ends on a dangling connector. The delta is
  *     judged, not the whole file, so a pre-existing truncated row never blocks an unrelated
@@ -108,6 +115,39 @@ export function guardedRowCount(doc) {
   return null;
 }
 
+/** The top-level list the id-uniqueness guard protects: `items:` or a top-level sequence, else null. */
+function guardedList(doc) {
+  if (Array.isArray(doc)) return doc;
+  if (doc && typeof doc === "object" && Array.isArray(doc.items)) return doc.items;
+  return null;
+}
+
+/**
+ * First `id` value that appears on two or more rows of the guarded top-level list, else null.
+ * A duplicate id makes every id-anchored edit ambiguous, so js-yaml lets it through (the rows are
+ * distinct list entries, not duplicate map keys) but the file becomes unwritable via id-anchored edits.
+ */
+export function duplicateItemId(doc) {
+  const list = guardedList(doc);
+  if (!list) return null;
+  const seen = new Set();
+  for (const row of list) {
+    if (!row || typeof row !== "object") continue;
+    const id = row.id;
+    if (typeof id !== "string" && typeof id !== "number") continue;
+    const key = String(id);
+    if (seen.has(key)) return key;
+    seen.add(key);
+  }
+  return null;
+}
+
+/** If `oldStr` is anchored on an `id:` line, return the id value; else null. */
+function repeatedIdAnchor(oldStr) {
+  const m = /(?:^|\n)\s*(?:-\s+)?id:\s*(.+?)\s*(?:\n|$)/.exec(oldStr);
+  return m ? m[1].replace(/^["']|["']$/g, "") : null;
+}
+
 /** Count non-overlapping occurrences of `needle` in `hay`. */
 function countOccurrences(hay, needle) {
   if (!needle) return 0;
@@ -138,7 +178,15 @@ export function wouldBeContent(toolName, ti, current) {
     if (typeof oldStr !== "string" || oldStr === "") return { refuse: "Edit with an empty old_string" };
     const n = countOccurrences(current, oldStr);
     if (n === 0) return { refuse: "old_string is not present in the file on disk — the edit would not land where you looked" };
-    if (n > 1 && !ti.replace_all) return { refuse: `old_string matches ${n} places — anchor it to one row or pass replace_all` };
+    if (n > 1 && !ti.replace_all) {
+      // A repeated `id:` line means the file already carries a duplicate id — the collision, not the
+      // anchor, is why every id-anchored edit matches twice. Name that instead of the generic advice.
+      const dupId = repeatedIdAnchor(oldStr);
+      if (dupId !== null) {
+        return { refuse: `WHOLE FILE BLOCKED — the file already contains a duplicate id '${dupId}', so this id-anchored edit matches ${n} places and cannot land. The file is unwritable via id-anchored edits until the duplicate id is resolved (give one of the colliding rows a unique id).` };
+      }
+      return { refuse: `old_string matches ${n} places — anchor it to one row or pass replace_all` };
+    }
     return { content: ti.replace_all ? current.split(oldStr).join(newStr) : current.replace(oldStr, () => newStr) };
   }
   if (toolName === "MultiEdit" && Array.isArray(ti.edits)) {
@@ -200,6 +248,19 @@ export function evaluate(payload, o = {}) {
     try { prev = yaml.load(current); prevParsed = true; } catch { prevParsed = false; }
   }
 
+  // Duplicate-id guard (id-uniqueness reserved at the write boundary). A second row sharing an id
+  // slips past js-yaml — the rows are distinct list entries, not duplicate map keys — but it makes
+  // every id-anchored edit ambiguous and the file effectively unwritable. Judged on the DELTA: a
+  // brand-new collision this write introduces always blocks; a pre-existing one the write leaves in
+  // place is surfaced by the id-anchored-Edit match-count path, not penalised twice here.
+  const nextDup = duplicateItemId(next);
+  if (nextDup !== null && (!prevParsed || duplicateItemId(prev) !== nextDup)) {
+    return {
+      decision: "deny",
+      reason: `${toolName} ${fp}: WHOLE FILE BLOCKED — two rows share id '${nextDup}'. A duplicate id makes every id-anchored edit ambiguous and the file unwritable. Give the new row a unique id before writing.`,
+    };
+  }
+
   // Provenance truncation — judged on the DELTA so pre-existing rows never block a new write.
   const before = new Set(prevParsed ? provenanceHits(prev).map((h) => `${h.id}\u0000${h.key}\u0000${h.value}`) : []);
   const fresh = provenanceHits(next).filter((h) => !before.has(`${h.id}\u0000${h.key}\u0000${h.value}`));