@plinth-music/cli 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
 
+## 0.17.0 - 2026-09-03
+
+One code PR since `0.16.0` (`v0.16.0..a6209c8`, #165; #167 is tests and comments,
+#163 / #164 / #166 docs). A minor because sync gains a new refusal and a file on your
+disk can now move on its own.
+
+- ⚠️ **Renaming a task or project in Plinth now moves the mirror file instead of
+  writing a second one.** The server regenerates a row's slug when its name changes.
+  Until now the mirror wrote the new name to a new file and left the old one orphaned,
+  and an edit to that orphan created a duplicate row in Plinth. The file is moved now,
+  and a local copy that had diverged from the cloud is stashed to
+  `~/.plinth/_conflicts/<workspace>/` before the move rather than pushed.
+- ⚠️ **A rename that would land on a file already sitting there is refused, not
+  overwritten.** Nothing is moved, `plinth status` names it, and Plinth re-offers the
+  rename on every poll until the name is free. Where the file in the way belongs to
+  another record the message says so and tells you **not** to delete it — deleting it
+  would delete that record in Plinth. Where it is a file of yours, rename or move it
+  and the rename lands on the next poll.
+- **An unreadable file at a renamed row's old path no longer stalls the whole sync.**
+  It used to abort the pull, and in the daemon back that off to a five-minute retry
+  indefinitely, leaving the mirror silently stale behind a notice naming no file. Only
+  that row is held now, and `plinth status` names the file and says to check its
+  permissions.
+
+⚠️ **One boundary changed underneath this release, with no CLI change in it.** Plinth's
+MCP server renamed its calendar tools (`create_calendar_event` and its siblings became
+`create_calendar_entry`), which is what lets the cockpit write calendar entries. The
+side effect is that the generated deny list no longer covers calendar *deletion* on
+Plinth's own server, which it had been doing by accident of the name. No such tool
+exists today, so the hole is latent rather than open. #167 measured this and pinned it
+with tests; no deny pattern was added, removed or edited, and the list stays at 91.
+
+The desktop app pins `@plinth-music/cli` exact (0.16.0 as of v1.9.4) and picks none of
+this up until its own release repins.
+
 ## 0.16.0 - 2026-09-02
 
 Three code PRs since `0.15.0` (`v0.15.0..5c60627`, #157, #159, #161; #158 and #160 are

package/README.md

@@ -23,7 +23,7 @@ plinth start                      # run the daemon: continuous pull + watch + pu
 ## Commands
 
 - `plinth login --workspace <slug> [--reset-sync]` — issue a personal access token in the browser, paste it back, store it in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager). Logging in again to the same workspace is a token rotation and **keeps your sync cursors**, so the next sync picks up where the last one left off; it clears them only when the token belongs to a different workspace or user. `--reset-sync` discards them deliberately, making the next sync a full re-pull — use it after rebuilding a mirror from scratch, which is otherwise unreachable now that rotation preserves them.
-- `plinth sync [--workspace <slug>]` — one-shot pull into `~/Plinth/<workspace>/`. Also generates the workspace-root `CLAUDE.md` (a thin TOC + entity model + skill pointers), an empty `CLAUDE.local.md` stub on first sync, and the two session-boundary commands (below), and silently refreshes `CLAUDE.md` on a schema-version change. Defaults to the active workspace if `--workspace` is omitted. **Every mirrored task, project, document, artist, meeting and thread file carries its row `id:` in frontmatter**, so an agent holding a file can address the MCP write for that row directly instead of going through `search_entities` and risking a duplicate on an empty result; files already on disk when you upgrade get it from a one-time backfill, since a cursor feed never re-sends an unchanged row. The key is server-authoritative and stripped before the wire, so it moves no hash and pushes nothing. It also **scaffolds `files/` and the six entity folders**, so a new workspace arrives with somewhere to put things instead of an empty directory, and the folder map in the generated `CLAUDE.md` reads the disk rather than asserting what ought to be there.
+- `plinth sync [--workspace <slug>]` — one-shot pull into `~/Plinth/<workspace>/`. Also generates the workspace-root `CLAUDE.md` (a thin TOC + entity model + skill pointers), an empty `CLAUDE.local.md` stub on first sync, and the two session-boundary commands (below), and silently refreshes `CLAUDE.md` on a schema-version change. Defaults to the active workspace if `--workspace` is omitted. **Every mirrored task, project, document, artist, meeting and thread file carries its row `id:` in frontmatter**, so an agent holding a file can address the MCP write for that row directly instead of going through `search_entities` and risking a duplicate on an empty result; files already on disk when you upgrade get it from a one-time backfill, since a cursor feed never re-sends an unchanged row. The key is server-authoritative and stripped before the wire, so it moves no hash and pushes nothing. Since 0.17.0 a row **renamed in Plinth moves its mirror file** rather than leaving a second copy at the old name; a file already sitting at the new name is never overwritten, and `plinth status` names the clash until it clears. It also **scaffolds `files/` and the six entity folders**, so a new workspace arrives with somewhere to put things instead of an empty directory, and the folder map in the generated `CLAUDE.md` reads the disk rather than asserting what ought to be there.
 - `plinth start` — run the long-running sync daemon: pull the latest, then watch the mirror for local edits and push them. It also projects each mapped artist's Google calendar into `views/calendar/` in the mirror — a file per artist plus an `upcoming.md` — on its own 15-minute timer (`PLINTH_CALENDAR_INTERVAL_MS`), with one run at boot. That is deliberately not the 15-second pull cadence: one tick makes a Google call per mapped calendar, which would breach the server route's rate limit inside a minute. A refresh that fails keeps the last known bodies and rewrites only the header, so a stale view says it is stale rather than reading as an empty diary. Logs to `~/.plinth/daemon.log`. **One daemon per workspace:** it holds an exclusive kernel lock on `~/.plinth/daemon-<workspace>.lock` for its life (macOS only; other platforms are refused and told why), so a second `plinth start`, or a standalone `plinth sync` while it runs, exits 1 naming the holder's pid. **Never delete the lock file** — the lock lives on the inode, and removing the path is what lets a second daemon in beside a live one. It also writes `views/conflicts.md` on every sync: every local edit the cloud won and the daemon set aside in `~/.plinth/_conflicts/`, each with a `cp` command that restores it; the zero case is written too, so an absent file means an old daemon, not a clean one.
 - `plinth status` — local sync state: daemon liveness, last sync and per-type counts, any destructive batches being held, writes awaiting retry or permanently rejected, **every local write that has not reached Plinth** (scanned from the mirror against the last acknowledged state, with the remedy that clears each — start the daemon, or open and save a file that was created while it was down), the state of `voice.md`, and any conflict stashes in `~/.plinth/_conflicts/<workspace>/` — local copies that were set aside when the cloud version won. Warns when a source install's `dist/` is behind its checkout. Four further rows. **Commands** warns when the customisable block in a generated command still names machinery that command retired — the block is preserved verbatim forever and renders after the generated body, so a hand-written step that runs a retired ritual wins, and the generator may never edit it. **Its verdict is derived from the command registry, not asserted**: a token that still resolves to a live subcommand is described as still working and left to you, because the one token it lists is `memory-gate`, which the grounding block hands every session. **Links** names `[[pointers]]` in `workspace-memory.md` and `artists/*/memory.md` that resolve to nothing — a memory fact is a hook plus a pointer to its source, so a dead pointer can mean the hook is the only surviving copy of the fact. It reuses `plinth backlinks`'s resolution ladder, reports prose links only (never one inside a code fence), never reports an ambiguous target, and strips anchors before resolving. **Injection** reports the session-start block's size against its 20,000-byte budget and **where those bytes go** — seven categories that sum to the block by construction, marking which are yours to change — plus how many facts of each index ride whole, how many ride as their opening line only, and which file to shorten. **Too long** names each memory file past the size it is useful at: a rule file (`voice.md`, `workspace-rules.md`) at **6,000 bytes**, a fact store (`artists/<slug>/memory.md`) at **12,000**. The two bars are not one bar: what a long rule file spends is the model's instruction-following budget, which reference facts do not touch. A file under its bar renders nothing at all. Since 0.16.0 it also reports master-context walls (one block past 2,000 characters), played entries still under an "upcoming" label, and a "Current state" heading with no as-of or a stale one.
 - `plinth confirm` — review and release destructive batches the daemon has quarantined (apply, or `--discard`).

package/dist/build-stamp.json

@@ -1,5 +1,5 @@
 {
-  "sha": "4d6d17c915cb0b2fd774da4ae8876a450a658eb0",
+  "sha": "bc49180c1d2e3f217f3eedda18bd075870cc36aa",
   "dirty": false,
-  "built_at": "2026-09-02T18:56:56.610Z"
+  "built_at": "2026-09-03T21:05:22.806Z"
 }

package/dist/cli.js

@@ -7584,7 +7584,7 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
 // package.json
 var package_default = {
   name: "@plinth-music/cli",
-  version: "0.16.0",
+  version: "0.17.0",
   description: "Plinth capstone sync daemon and CLI",
   type: "module",
   private: false,
@@ -23654,6 +23654,46 @@ function writeMirrorFile(workspaceSlug, entityType, entitySlug, content) {
     throw err;
   }
 }
+
+class MirrorDestinationOccupiedError extends MirrorPathError {
+  fromSlug;
+  toSlug;
+  constructor(fromSlug, toSlug) {
+    super(`Cannot move ${JSON.stringify(fromSlug)} to ${JSON.stringify(toSlug)}: ` + `a file already exists there`);
+    this.name = "MirrorDestinationOccupiedError";
+    this.fromSlug = fromSlug;
+    this.toSlug = toSlug;
+  }
+}
+function moveEntityFile(workspaceSlug, entityType, fromSlug, toSlug, beforeMove) {
+  const strategy = getStrategy(entityType);
+  const rel = strategy ? strategy.mirrorRelativePath(fromSlug) : flatMirrorRelativePath(entityType)(fromSlug);
+  if (rel.split("/").length !== 2) {
+    throw new MirrorPathError(`Entity type ${JSON.stringify(entityType)} keeps its rows in a folder; ` + `moving one is not supported`);
+  }
+  const from = entityFilePath(workspaceSlug, entityType, fromSlug);
+  const to = entityFilePath(workspaceSlug, entityType, toSlug);
+  if (from === to)
+    return "absent";
+  try {
+    lstatSync(to);
+    throw new MirrorDestinationOccupiedError(fromSlug, toSlug);
+  } catch (err) {
+    if (err instanceof MirrorDestinationOccupiedError)
+      throw err;
+    if (err?.code !== "ENOENT")
+      throw err;
+  }
+  beforeMove?.();
+  try {
+    renameSync(from, to);
+    return "moved";
+  } catch (err) {
+    if (err?.code === "ENOENT")
+      return "absent";
+    throw err;
+  }
+}
 var ARTIST_MEMORY_ANCHOR = "memory.md";
 function artistMemoryFilePath(workspaceSlug, entitySlug) {
   assertSlug("entity slug", entitySlug);
@@ -31007,6 +31047,31 @@ function recordEntitySymlinkRefused(args) {
     rejected_at: args.now().toISOString()
   }));
 }
+function recordEntitySlugClash(args) {
+  const path3 = args.mirrorRelativePath;
+  const withoutStale = removeUnsynced(args.state, "entity", path3).state;
+  const held = `Until then new ${args.entityType} changes are held on this machine.`;
+  const message = args.reason === "source_unreadable" ? `${args.entityType}/${args.fromSlug} was renamed in Plinth to ` + `${args.toSlug}, but ${path3} could not be read, so it was left exactly ` + `where it is. Check the file's permissions; Plinth will move it once ` + `it can read it. ${held}` : args.occupantTracked ? `${args.entityType}/${args.fromSlug} was renamed in Plinth to ` + `${args.toSlug}, but ${args.entityType}/${args.toSlug}.md belongs to ` + `another ${args.entityType}, so nothing was moved or overwritten. ` + `This usually clears itself once that record's own rename arrives. ` + `Do not delete that file — it would delete that record in Plinth. ` + `${held}` : `${args.entityType}/${args.fromSlug} was renamed in Plinth to ` + `${args.toSlug}, but ${args.entityType}/${args.toSlug}.md already ` + `exists here, so nothing was moved or overwritten. Rename or remove ` + `that file and Plinth will move this one into place. ${held}`;
+  const existing = (withoutStale.rejected ?? []).find((r) => r.target === "entity" && r.path === path3 && r.reason === "slug_clash");
+  if (existing && existing.message === message)
+    return args.state;
+  return persist(withoutStale, upsertRejected(withoutStale, {
+    target: "entity",
+    op: "upsert",
+    path: path3,
+    status: 0,
+    reason: "slug_clash",
+    message,
+    rejected_at: args.now().toISOString()
+  }));
+}
+function clearSlugClash(state, mirrorRelativePaths) {
+  const list = state.rejected ?? [];
+  const next = list.filter((o) => !(o.target === "entity" && o.reason === "slug_clash" && mirrorRelativePaths.includes(o.path)));
+  if (next.length === list.length)
+    return state;
+  return commitState(state, { ...state, rejected: next });
+}
 function clearSymlinkRefused(state, target, path3) {
   const list = state.rejected ?? [];
   const next = list.filter((o) => !(o.target === target && o.path === path3 && o.reason === "symlink"));
@@ -32727,10 +32792,102 @@ function computeMirrorHashes(strategy, content) {
 function hashableBody(strategy, body) {
   return strategy.stripLocalBlocks?.(body) ?? body;
 }
-function writeMirrorWithBodyPreserve(workspaceSlug, strategy, doc2, suppressor) {
+function relocateForSlugChange(args) {
+  const { workspaceSlug, strategy, fromSlug, toSlug, acked, echo, now } = args;
+  if (fromSlug === toSlug)
+    return { kind: "not_needed", writeSlug: toSlug };
+  if (!echo) {
+    return { kind: "skipped", writeSlug: toSlug, fromSlug, reason: "unguarded" };
+  }
+  if (strategy.mirrorRelativePath(fromSlug).split("/").length !== 2) {
+    return { kind: "skipped", writeSlug: toSlug, fromSlug, reason: "foldered" };
+  }
+  let fromPath;
+  try {
+    fromPath = entityFilePath(workspaceSlug, strategy.type, fromSlug);
+    entityFilePath(workspaceSlug, strategy.type, toSlug);
+  } catch (err) {
+    if (err instanceof MirrorPathError) {
+      return {
+        kind: "skipped",
+        writeSlug: toSlug,
+        fromSlug,
+        reason: "unresolvable"
+      };
+    }
+    throw err;
+  }
+  let raw = null;
+  try {
+    raw = readFileSync15(fromPath, "utf8");
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT") {
+      return { kind: "absent", writeSlug: toSlug, fromSlug };
+    }
+    return {
+      kind: "refused",
+      writeSlug: fromSlug,
+      fromSlug,
+      reason: "source_unreadable"
+    };
+  }
+  let diverged = true;
+  try {
+    const hashes = computeMirrorHashes(strategy, raw);
+    diverged = hashes.bodyHash !== acked.bodyHash || hashes.frontmatterHash !== acked.frontmatterHash;
+  } catch {
+    diverged = true;
+  }
+  const stashPath = diverged ? stashConflict({
+    workspaceSlug,
+    entityType: strategy.type,
+    entitySlug: fromSlug,
+    timestamp: now(),
+    contents: raw,
+    side: "local"
+  }) : undefined;
+  try {
+    let registered = false;
+    const result = moveEntityFile(workspaceSlug, strategy.type, fromSlug, toSlug, () => {
+      if (echo.watcher === "live") {
+        echo.suppressor.registerDelete(fromPath);
+        registered = true;
+      }
+    });
+    if (result === "moved") {
+      return { kind: "moved", writeSlug: toSlug, fromSlug, stashPath };
+    }
+    if (registered && echo.watcher === "live") {
+      echo.suppressor.cancelDelete(fromPath);
+    }
+    return { kind: "absent", writeSlug: toSlug, fromSlug };
+  } catch (err) {
+    if (err instanceof MirrorDestinationOccupiedError) {
+      return {
+        kind: "refused",
+        writeSlug: fromSlug,
+        fromSlug,
+        reason: "destination_occupied",
+        stashPath
+      };
+    }
+    if (err instanceof MirrorPathError) {
+      return {
+        kind: "skipped",
+        writeSlug: toSlug,
+        fromSlug,
+        reason: "unresolvable"
+      };
+    }
+    throw err;
+  }
+}
+function writeMirrorWithBodyPreserve(workspaceSlug, strategy, doc2, suppressor, pathSlug) {
+  const targetSlug = pathSlug ?? doc2.slug;
   let content = strategy.serialise(doc2);
   if (strategy.preserveLocalBodyOnPull) {
-    const target = entityFilePath(workspaceSlug, strategy.type, doc2.slug);
+    const target = entityFilePath(workspaceSlug, strategy.type, targetSlug);
     let existing = null;
     try {
       existing = readFileSync15(target, "utf8");
@@ -32748,10 +32905,10 @@ function writeMirrorWithBodyPreserve(workspaceSlug, strategy, doc2, suppressor)
     }
   }
   if (suppressor) {
-    const target = entityFilePath(workspaceSlug, strategy.type, doc2.slug);
+    const target = entityFilePath(workspaceSlug, strategy.type, targetSlug);
     suppressor.registerWrite(target, computeMirrorHashes(strategy, content));
   }
-  writeMirrorFile(workspaceSlug, strategy.type, doc2.slug, content);
+  writeMirrorFile(workspaceSlug, strategy.type, targetSlug, content);
   return content;
 }
 
@@ -32859,7 +33016,8 @@ function cloudMatchesAcked(strategy, cloud, acked) {
 }
 function stampStateFromMirror(args) {
   const { strategy, workspaceSlug, doc: doc2, state, priorMemoryHash } = args;
-  const mirrorPath = entityFilePath(workspaceSlug, strategy.type, doc2.slug);
+  const targetSlug = args.pathSlug ?? doc2.slug;
+  const mirrorPath = entityFilePath(workspaceSlug, strategy.type, targetSlug);
   const mirrorRaw = readFileSync16(mirrorPath, "utf8");
   const mirrorParsed = import_gray_matter10.default(mirrorRaw);
   const mirrorFm = mirrorParsed.data ?? {};
@@ -32868,7 +33026,7 @@ function stampStateFromMirror(args) {
   const mirrorHashBody = hashableBody(strategy, mirrorParsed.content);
   const refreshed = {
     id: doc2.id,
-    slug: doc2.slug,
+    slug: targetSlug,
     updated_at: doc2.updated_at,
     revision: doc2.revision,
     body_hash: stableHash(mirrorHashBody),
@@ -32879,6 +33037,73 @@ function stampStateFromMirror(args) {
   };
   return persistEntry(state, strategy.type, refreshed);
 }
+function adoptCloudCopy(args) {
+  const { strategy, workspaceSlug, doc: doc2, output } = args;
+  const now = args.now ?? (() => new Date);
+  let state = args.state;
+  const prior = getEntry(state, strategy.type, doc2.id);
+  let writeSlug = doc2.slug;
+  let refused = false;
+  if (prior && prior.slug !== doc2.slug) {
+    const relocation = relocateForSlugChange({
+      workspaceSlug,
+      strategy,
+      fromSlug: prior.slug,
+      toSlug: doc2.slug,
+      acked: {
+        bodyHash: prior.body_hash,
+        frontmatterHash: prior.frontmatter_hash
+      },
+      echo: args.echo,
+      now
+    });
+    writeSlug = relocation.writeSlug;
+    const move = `entityType=${strategy.type} from=${prior.slug} to=${doc2.slug} id=${doc2.id}`;
+    if (relocation.kind === "moved") {
+      output?.log(`[SLUG_MOVE ${move} source=push]`);
+      state = clearSlugClash(state, [
+        strategy.mirrorRelativePath(prior.slug),
+        strategy.mirrorRelativePath(doc2.slug)
+      ]);
+    } else if (relocation.kind === "refused") {
+      output?.log(`[SLUG_MOVE_REFUSED ${move} reason=${relocation.reason} source=push]`);
+      refused = true;
+      state = recordEntitySlugClash({
+        state,
+        mirrorRelativePath: strategy.mirrorRelativePath(prior.slug),
+        entityType: strategy.type,
+        fromSlug: prior.slug,
+        toSlug: doc2.slug,
+        reason: relocation.reason,
+        occupantTracked: getEntryBySlug(state, strategy.type, doc2.slug) !== undefined,
+        now
+      });
+    } else if (relocation.kind === "skipped") {
+      output?.log(`[SLUG_MOVE_SKIP ${move} reason=${relocation.reason} source=push]`);
+    }
+    if (relocation.kind === "moved" || relocation.kind === "refused") {
+      if (relocation.stashPath) {
+        output?.warn(`Unsynced local edit on ${strategy.type}/${prior.slug} → stashed to ` + `${relocation.stashPath} (the row was renamed in Plinth; the cloud ` + `copy is authoritative).`);
+      }
+    }
+  }
+  if (refused) {
+    return prior ? persistEntry(state, strategy.type, {
+      ...prior,
+      updated_at: doc2.updated_at,
+      revision: doc2.revision
+    }) : state;
+  }
+  writeMirrorWithBodyPreserve(workspaceSlug, strategy, doc2, undefined, writeSlug);
+  return stampStateFromMirror({
+    strategy,
+    workspaceSlug,
+    doc: doc2,
+    state,
+    priorMemoryHash: args.priorMemoryHash,
+    pathSlug: writeSlug
+  });
+}
 async function pullAndWriteMirror(args) {
   const cloud = await getEntity({
     strategy: args.strategy,
@@ -32887,13 +33112,15 @@ async function pullAndWriteMirror(args) {
     id: args.id,
     fetchImpl: args.fetchImpl
   });
-  writeMirrorWithBodyPreserve(args.workspaceSlug, args.strategy, cloud);
-  return stampStateFromMirror({
+  return adoptCloudCopy({
     strategy: args.strategy,
     workspaceSlug: args.workspaceSlug,
     doc: cloud,
     state: args.state,
-    priorMemoryHash: getEntry(args.state, args.strategy.type, args.id)?.memory_hash
+    priorMemoryHash: getEntry(args.state, args.strategy.type, args.id)?.memory_hash,
+    echo: args.echo,
+    output: args.output,
+    now: args.now
   });
 }
 async function pushFile(args) {
@@ -32914,6 +33141,7 @@ async function pushFile(args) {
   const mutex = deps?.mutex ?? new PerIdMutex;
   const output = deps?.output;
   const suppressor = deps?.suppressor;
+  const echo = deps?.echo;
   const strategy = getStrategy(entityType);
   if (!strategy) {
     return {
@@ -32927,6 +33155,8 @@ async function pushFile(args) {
   }
   if (!exists) {
     return runPushDelete({
+      echo,
+      now,
       strategy,
       workspaceSlug,
       baseUrl,
@@ -32945,6 +33175,8 @@ async function pushFile(args) {
   } catch (err) {
     if (err?.code === "ENOENT") {
       return runPushDelete({
+        echo,
+        now,
         strategy,
         workspaceSlug,
         baseUrl,
@@ -33004,6 +33236,7 @@ async function pushFile(args) {
   const stateEntry = identity === "path" ? byInode : byInode ?? getEntryBySlug(state, entityType, slug);
   if (!stateEntry) {
     return runPushCreate({
+      echo,
       strategy,
       workspaceSlug,
       baseUrl,
@@ -33024,6 +33257,7 @@ async function pushFile(args) {
     });
   }
   return runPushUpsert({
+    echo,
     strategy,
     workspaceSlug,
     baseUrl,
@@ -33082,7 +33316,10 @@ async function reconcileContextDocConflict(args) {
       pat,
       id: existingId,
       state,
-      fetchImpl
+      fetchImpl,
+      echo: args.echo,
+      output,
+      now
     });
     output?.log(contextDocConflictLine({
       entityType: strategy.type,
@@ -33199,7 +33436,10 @@ async function reconcileContextDocConflict(args) {
       pat,
       id: existingId,
       state,
-      fetchImpl
+      fetchImpl,
+      echo: args.echo,
+      output,
+      now
     });
     output?.log(contextDocConflictLine({
       entityType: strategy.type,
@@ -33421,6 +33661,7 @@ async function runPushUpsert(args) {
     }
     if (patchResult.reason === "context_doc_conflict") {
       return reconcileContextDocConflict({
+        echo: args.echo,
         strategy,
         workspaceSlug: args.workspaceSlug,
         baseUrl: args.baseUrl,
@@ -33439,6 +33680,7 @@ async function runPushUpsert(args) {
     }
     if (strategy.fieldTypedConflict) {
       return reconcileTaskConflict({
+        echo: args.echo,
         strategy,
         workspaceSlug: args.workspaceSlug,
         baseUrl: args.baseUrl,
@@ -33469,7 +33711,10 @@ async function runPushUpsert(args) {
       pat: args.pat,
       id: liveEntry.id,
       state: workingState,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      echo: args.echo,
+      output: args.output,
+      now: args.now
     });
     return {
       outcome: {
@@ -33517,7 +33762,10 @@ async function reconcileTaskConflict(args) {
       pat,
       id: liveEntry.id,
       state,
-      fetchImpl
+      fetchImpl,
+      echo: args.echo,
+      output,
+      now
     });
     return {
       outcome: {
@@ -33566,13 +33814,15 @@ async function reconcileTaskConflict(args) {
   });
   if (patchResult.ok) {
     const stashPath2 = stashCloudSide();
-    writeMirrorWithBodyPreserve(workspaceSlug, strategy, patchResult.doc);
-    state = stampStateFromMirror({
+    state = adoptCloudCopy({
       strategy,
       workspaceSlug,
       doc: patchResult.doc,
       state,
-      priorMemoryHash: liveEntry.memory_hash
+      priorMemoryHash: liveEntry.memory_hash,
+      echo: args.echo,
+      output,
+      now
     });
     output?.log(`[PATCH entityType=${strategy.type} slug=${patchResult.doc.slug} id=${patchResult.doc.id} revision=${patchResult.doc.revision} note=field_typed_conflict]`);
     return {
@@ -33604,7 +33854,10 @@ async function reconcileTaskConflict(args) {
     pat,
     id: liveEntry.id,
     state,
-    fetchImpl
+    fetchImpl,
+    echo: args.echo,
+    output,
+    now
   });
   return {
     outcome: {
@@ -33641,6 +33894,7 @@ async function runPushCreate(args) {
     const inLock = args.identity === "path" ? undefined : getEntryBySlug(args.state, strategy.type, args.slug);
     if (inLock) {
       return runPushUpsert({
+        echo: args.echo,
         strategy,
         workspaceSlug: args.workspaceSlug,
         baseUrl: args.baseUrl,
@@ -33737,6 +33991,7 @@ async function runPushCreate(args) {
     }
     if (createResult.reason === "context_doc_conflict") {
       return reconcileContextDocConflict({
+        echo: args.echo,
         strategy,
         workspaceSlug: args.workspaceSlug,
         baseUrl: args.baseUrl,
@@ -33768,7 +34023,10 @@ async function runPushCreate(args) {
       pat: args.pat,
       id: createResult.existing.id,
       state: args.state,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      echo: args.echo,
+      output: args.output,
+      now: args.now
     });
     return {
       outcome: {
@@ -33856,7 +34114,10 @@ async function runPushDelete(args) {
       pat: args.pat,
       id,
       state: args.state,
-      fetchImpl: args.fetchImpl
+      fetchImpl: args.fetchImpl,
+      echo: args.echo,
+      output: args.output,
+      now: args.now
     });
     return {
       outcome: {
@@ -33887,6 +34148,7 @@ async function pushRename(args) {
   const now = deps?.now ?? (() => new Date);
   const mutex = deps?.mutex ?? new PerIdMutex;
   const output = deps?.output;
+  const echo = deps?.echo;
   const strategy = requireStrategy(entityType);
   let toSlug;
   try {
@@ -33995,7 +34257,10 @@ async function pushRename(args) {
         pat,
         id: patchResult.existing.id,
         state,
-        fetchImpl
+        fetchImpl,
+        echo,
+        output,
+        now
       });
       const finalState = await pullAndWriteMirror({
         strategy,
@@ -34004,7 +34269,10 @@ async function pushRename(args) {
         pat,
         id,
         state: afterColliding,
-        fetchImpl
+        fetchImpl,
+        echo,
+        output,
+        now
       });
       return {
         outcome: {
@@ -34036,7 +34304,10 @@ async function pushRename(args) {
       pat,
       id,
       state,
-      fetchImpl
+      fetchImpl,
+      echo,
+      output,
+      now
     });
     return {
       outcome: {
@@ -34094,7 +34365,8 @@ async function applyBatch(batch, deps, mutex) {
           fetchImpl: deps.fetchImpl,
           now: deps.now,
           mutex,
-          output: deps.output
+          output: deps.output,
+          echo: deps.echo
         }
       });
       deps.setState(result.state);
@@ -34163,7 +34435,10 @@ async function discardBatchOps(batch, deps) {
         pat: deps.pat,
         id: op.id,
         state: deps.getState(),
-        fetchImpl: deps.fetchImpl
+        fetchImpl: deps.fetchImpl,
+        echo: deps.echo,
+        output: deps.output,
+        now: deps.now
       });
       deps.setState(next);
     } catch (err) {
@@ -34756,7 +35031,7 @@ function recordFileUnsynced(args) {
   });
 }
 async function drainUnsyncedOps(args) {
-  const { workspaceSlug, baseUrl, pat, getState, setState, fetchImpl, mutex, output } = args;
+  const { workspaceSlug, baseUrl, pat, getState, setState, fetchImpl, mutex, output, echo } = args;
   const now = args.now ?? (() => new Date);
   const ops = listUnsynced(getState());
   let attempted = 0;
@@ -34789,7 +35064,7 @@ async function drainUnsyncedOps(args) {
           state: getState(),
           exists: op.op === "upsert",
           unlinkContext: null,
-          deps: { fetchImpl, now, mutex, output }
+          deps: { fetchImpl, now, mutex, output, echo }
         });
         setState(result.state);
       } else {
@@ -38304,6 +38579,11 @@ class PullSuppressor {
       expiresAt: this.now() + this.ttlMs
     });
   }
+  cancelDelete(absPath) {
+    const entry2 = this.entries.get(absPath);
+    if (entry2?.kind === "delete")
+      this.entries.delete(absPath);
+  }
   shouldSuppressUpsert(absPath, hashes) {
     const entry2 = this.entries.get(absPath);
     if (!entry2)
@@ -38872,7 +39152,7 @@ async function reconcileDivergedRows(args) {
         state,
         exists: true,
         unlinkContext: null,
-        deps: { fetchImpl, now, output }
+        deps: { fetchImpl, now, output, echo: args.echo }
       });
       state = result.state;
       switch (result.outcome.kind) {
@@ -41373,7 +41653,13 @@ async function runSync(workspaceSlug, deps = {}) {
       let cursor = startCursor;
       let lastAdvancedCursor = startCursor;
       let cursorBlocked = false;
-      const ctr = { fetched: 0, written: 0, deleted: 0 };
+      const ctr = {
+        fetched: 0,
+        written: 0,
+        deleted: 0,
+        moved: 0,
+        refused: 0
+      };
       while (true) {
         const page = await syncEntity({
           strategy,
@@ -41407,6 +41693,12 @@ async function runSync(workspaceSlug, deps = {}) {
             ctr.written++;
           else if (outcome.action === "deleted")
             ctr.deleted++;
+          else if (outcome.action === "moved")
+            ctr.moved = (ctr.moved ?? 0) + 1;
+          else if (outcome.action === "slug_refused") {
+            ctr.refused = (ctr.refused ?? 0) + 1;
+            cursorBlocked = true;
+          }
         }
         commitPending();
         if (page.next_cursor === null)
@@ -41628,7 +41920,9 @@ async function runSync(workspaceSlug, deps = {}) {
   await syncFileRejections();
   const totalWritten = Object.values(counters).reduce((sum, c) => sum + c.written, 0);
   const totalDeleted = Object.values(counters).reduce((sum, c) => sum + c.deleted, 0);
-  if (totalWritten === 0 && totalDeleted === 0) {
+  const totalMoved = Object.values(counters).reduce((sum, c) => sum + (c.moved ?? 0), 0);
+  const totalRefused = Object.values(counters).reduce((sum, c) => sum + (c.refused ?? 0), 0);
+  if (totalWritten === 0 && totalDeleted === 0 && totalMoved === 0 && totalRefused === 0) {
     out.success("Already up to date.");
     return { exitCode: 0, applied: 0 };
   }
@@ -41639,12 +41933,16 @@ async function runSync(workspaceSlug, deps = {}) {
     const parts = [`${c.fetched} fetched`];
     if (c.written > 0)
       parts.push(`${c.written} written`);
+    if ((c.moved ?? 0) > 0)
+      parts.push(`${c.moved} renamed`);
+    if ((c.refused ?? 0) > 0)
+      parts.push(`${c.refused} rename held`);
     if (c.deleted > 0)
       parts.push(`${c.deleted} deleted`);
     out.info(`  ${type}: ${parts.join(", ")}`);
   }
   out.success(`Done in ${elapsed}s.`);
-  return { exitCode: 0, applied: totalWritten + totalDeleted };
+  return { exitCode: 0, applied: totalWritten + totalMoved + totalDeleted };
 }
 function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = () => new Date, isFrozen, loggedTombstoneSkips) {
   if (isFrozen?.(strategy.type, row.id)) {
@@ -41704,7 +42002,59 @@ function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = ()
   if (strategy.shouldMirror && !strategy.shouldMirror(live) && !existingEntry) {
     return { state, action: "skipped" };
   }
-  if (existingEntry && existingEntry.updated_at === live.updated_at) {
+  let relocation = { kind: "not_needed", writeSlug: live.slug };
+  if (existingEntry && existingEntry.slug !== live.slug) {
+    const echo = suppressor ? { watcher: "live", suppressor } : { watcher: "none" };
+    relocation = relocateForSlugChange({
+      workspaceSlug,
+      strategy,
+      fromSlug: existingEntry.slug,
+      toSlug: live.slug,
+      acked: {
+        bodyHash: existingEntry.body_hash,
+        frontmatterHash: existingEntry.frontmatter_hash
+      },
+      echo,
+      now
+    });
+    const move = `entityType=${strategy.type} from=${existingEntry.slug} to=${live.slug} id=${live.id}`;
+    switch (relocation.kind) {
+      case "moved":
+        out.log(`[SLUG_MOVE ${move}]`);
+        state = clearSlugClash(state, [
+          strategy.mirrorRelativePath(existingEntry.slug),
+          strategy.mirrorRelativePath(live.slug)
+        ]);
+        break;
+      case "refused":
+        out.log(`[SLUG_MOVE_REFUSED ${move} reason=${relocation.reason}]`);
+        const occupantTracked = getEntryBySlug(state, strategy.type, live.slug) !== undefined;
+        state = recordEntitySlugClash({
+          state,
+          mirrorRelativePath: strategy.mirrorRelativePath(existingEntry.slug),
+          entityType: strategy.type,
+          fromSlug: existingEntry.slug,
+          toSlug: live.slug,
+          reason: relocation.reason,
+          occupantTracked,
+          now
+        });
+        out.warn(relocation.reason === "source_unreadable" ? `${strategy.type}/${existingEntry.slug} was renamed to ${live.slug} in ` + `Plinth, but ${strategy.mirrorRelativePath(existingEntry.slug)} could ` + `not be read — it was left exactly where it is. Check its permissions.` : occupantTracked ? `${strategy.type}/${existingEntry.slug} was renamed to ${live.slug} in ` + `Plinth, but ${strategy.mirrorRelativePath(live.slug)} belongs to ` + `another ${strategy.type} — nothing was moved or overwritten. This ` + `usually clears itself once that row's own rename arrives; do not ` + `delete the file, which would delete that record in Plinth.` : `${strategy.type}/${existingEntry.slug} was renamed to ${live.slug} in ` + `Plinth, but ${strategy.mirrorRelativePath(live.slug)} already exists ` + `here — nothing was moved or overwritten. Rename or remove that file ` + `and Plinth will move this one into place.`);
+        return { state, action: "slug_refused" };
+      case "skipped":
+        out.log(`[SLUG_MOVE_SKIP ${move} reason=${relocation.reason}]`);
+        break;
+      case "absent":
+      case "not_needed":
+        break;
+    }
+    const stashPath = relocation.kind === "moved" ? relocation.stashPath : undefined;
+    if (stashPath) {
+      out.warn(`Unsynced local edit on ${strategy.type}/${existingEntry.slug} → stashed ` + `to ${stashPath} (the row was renamed in Plinth; the cloud copy is ` + `authoritative).`);
+    }
+  }
+  const writeSlug = relocation.writeSlug;
+  if (existingEntry && existingEntry.updated_at === live.updated_at && relocation.kind === "not_needed") {
     const path5 = entityFilePath(workspaceSlug, strategy.type, live.slug);
     if (existsSync7(path5)) {
       if (strategy.type === "artists") {
@@ -41730,10 +42080,10 @@ function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = ()
       return { state, action: "noop_overwrite" };
     }
   }
-  if (!suppressor && existingEntry && existingEntry.updated_at !== live.updated_at) {
+  if (!suppressor && existingEntry && existingEntry.updated_at !== live.updated_at && relocation.kind !== "moved") {
     let localRaw = null;
     try {
-      localRaw = readFileSync24(entityFilePath(workspaceSlug, strategy.type, live.slug), "utf8");
+      localRaw = readFileSync24(entityFilePath(workspaceSlug, strategy.type, writeSlug), "utf8");
     } catch {
       localRaw = null;
     }
@@ -41753,11 +42103,11 @@ function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = ()
       }
     }
   }
-  const content = writeMirrorWithBodyPreserve(workspaceSlug, strategy, live, suppressor);
+  const content = writeMirrorWithBodyPreserve(workspaceSlug, strategy, live, suppressor, writeSlug);
   const hashes = computeMirrorHashes(strategy, content);
   let inode;
   try {
-    inode = statSync16(entityFilePath(workspaceSlug, strategy.type, live.slug)).ino;
+    inode = statSync16(entityFilePath(workspaceSlug, strategy.type, writeSlug)).ino;
   } catch {
     inode = undefined;
   }
@@ -41780,7 +42130,7 @@ function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = ()
   }
   const { state: nextState } = upsertEntry(state, strategy.type, {
     id: live.id,
-    slug: live.slug,
+    slug: writeSlug,
     updated_at: live.updated_at,
     revision: live.revision,
     body_hash: hashes.bodyHash,
@@ -41790,7 +42140,8 @@ function applyRow(workspaceSlug, strategy, row, state, out, suppressor, now = ()
     memory_hash: memoryHash,
     memory_generated: memoryGenerated
   });
-  return { state: nextState, action: "written" };
+  const action = relocation.kind === "moved" ? "moved" : "written";
+  return { state: nextState, action };
 }
 var syncCommand = defineCommand({
   meta: {
@@ -42266,6 +42617,22 @@ function makeWatchHandler(deps) {
         });
         if (!classifiedFrom)
           return;
+        if (suppressor?.shouldSuppressDelete(event.fromPath)) {
+          const strategy = getStrategy(classifiedFrom.entityType);
+          let toRaw = null;
+          try {
+            toRaw = readFileSync25(event.toPath, "utf8");
+          } catch {
+            toRaw = null;
+          }
+          const isEcho = strategy !== undefined && toRaw !== null && suppressor.shouldSuppressUpsert(event.toPath, computeMirrorHashes(strategy, toRaw));
+          if (isEcho) {
+            output?.log(`[RENAME_SUPPRESSED entityType=${classifiedFrom.entityType} ` + `from=${event.fromSlug} id=${event.id} reason=pull_echo]`);
+            return;
+          }
+          await handle({ kind: "upsert", absolutePath: event.toPath });
+          return;
+        }
         const result2 = await pushRename({
           workspaceSlug,
           baseUrl,
@@ -42277,7 +42644,13 @@ function makeWatchHandler(deps) {
           expectedUpdatedAt: event.expectedUpdatedAt,
           fromSlug: event.fromSlug,
           state: getState(),
-          deps: { fetchImpl, now, mutex, output }
+          deps: {
+            fetchImpl,
+            now,
+            mutex,
+            output,
+            echo: suppressor ? { watcher: "live", suppressor } : undefined
+          }
         });
         setState(result2.state);
         reportOutcome(spinner, workspaceSlug, result2.state, result2.outcome);
@@ -42409,7 +42782,14 @@ function makeWatchHandler(deps) {
           slug: event.stateEntry.slug,
           updated_at: event.stateEntry.updated_at
         } : null,
-        deps: { fetchImpl, now, mutex, output, suppressor }
+        deps: {
+          fetchImpl,
+          now,
+          mutex,
+          output,
+          suppressor,
+          echo: suppressor ? { watcher: "live", suppressor } : undefined
+        }
       });
       setState(clearEntityRejected(result.state, workspaceSlug, absolutePath));
       reportOutcome(spinner, workspaceSlug, getState(), result.outcome);
@@ -42470,7 +42850,8 @@ async function flushHeldEntityOp(deps) {
         fetchImpl: deps.fetchImpl,
         now,
         mutex: deps.mutex,
-        output: deps.output
+        output: deps.output,
+        echo: deps.echo
       }
     });
     deps.setState(result.state);
@@ -42606,6 +42987,7 @@ async function runStart(workspaceSlug, deps = {}) {
     frozenFiles = computeFrozenFiles(slug);
   };
   const recon = await reconcileDivergedRows({
+    echo: { watcher: "none" },
     workspaceSlug: slug,
     baseUrl: entry2.api_base_url,
     pat,
@@ -42819,6 +43201,7 @@ async function runStart(workspaceSlug, deps = {}) {
   spinner.start(`Watching ${slug} · ${watchingSummary(state)}`);
   const mutex = new PerIdMutex;
   const bootDrain = await drainResolvedBatches({
+    echo: { watcher: "none" },
     workspaceSlug: slug,
     baseUrl: entry2.api_base_url,
     pat,
@@ -42836,6 +43219,7 @@ async function runStart(workspaceSlug, deps = {}) {
     out.info(`Resolved ${bootDrain.applied + bootDrain.discarded} held batch${bootDrain.applied + bootDrain.discarded === 1 ? "" : "es"}: ${bootDrain.applied} applied, ${bootDrain.discarded} discarded.`);
   }
   const bootUnsynced = await drainUnsyncedOps({
+    echo: { watcher: "none" },
     workspaceSlug: slug,
     baseUrl: entry2.api_base_url,
     pat,
@@ -42873,6 +43257,7 @@ async function runStart(workspaceSlug, deps = {}) {
   };
   const suppressor = new PullSuppressor;
   const flushHeldOp = (op) => flushHeldEntityOp({
+    echo: { watcher: "live", suppressor },
     workspaceSlug: slug,
     baseUrl: entry2.api_base_url,
     pat,
@@ -43060,6 +43445,7 @@ async function runStart(workspaceSlug, deps = {}) {
         draining = true;
         try {
           const drained = await drainResolvedBatches({
+            echo: { watcher: "live", suppressor },
             workspaceSlug: slug,
             baseUrl: entry2.api_base_url,
             pat,
@@ -43077,6 +43463,7 @@ async function runStart(workspaceSlug, deps = {}) {
             spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
           }
           const redriven = await drainUnsyncedOps({
+            echo: { watcher: "live", suppressor },
             workspaceSlug: slug,
             baseUrl: entry2.api_base_url,
             pat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plinth-music/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Plinth capstone sync daemon and CLI",
   "type": "module",
   "private": false,