@plinth-music/cli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
 
+## 0.8.0 — 2026-08-23
+
+Two PRs and two direct commits since `0.7.0` (`v0.7.0..af83c59`). The daemon
+survives a failed confirm gate, and the map it writes tells an agent which
+command answers which question. No server prerequisite: both changes are
+client-side, and a 0.7.0 client is unaffected.
+
+### A failing confirm gate no longer takes the daemon down with it
+
+Both destructive gates fire their settle window fire-and-forget, so a rejecting
+`onSettle` surfaced as an unhandled rejection and **terminated the long-running
+daemon** — with the batch already lifted out of the gate's pending buffer, so its
+remaining operations were neither pushed nor quarantined. Work disappeared behind
+a process that had simply stopped.
+
+Three layers now catch it. The gate reports a settle failure through a new
+`onError` callback instead of rejecting into the void. The under-threshold flush
+catches per-operation failures, logs the same `[PUSH_FAILED]` / `[FILE_PUSH_FAILED]`
+lines the watch path already used, and hands recordable ones to the unsynced net
+so the poll tick re-drives them — one operation failing no longer skips its
+siblings. And a failed quarantine write warns on the banner rather than rejecting.
+
+### Every mirror's `CLAUDE.md` says how to traverse the corpus
+
+A new **Navigating the corpus** section: three lookup lines mapping a traversal
+question to the surface that answers it — what points at X (`plinth backlinks`),
+what this file links to (grep `[[`), and how to find a file by name, text inside a
+PDF, or an entity by field.
+
+`plinth backlinks` shipped in `0.6.0` and appeared in no generated context.
+Measured on the live mirror, the generated text carried no `backlinks`, no
+`wikilink` and no `[[`, while the command answered a real query with 7 files and
+16 occurrences. A/B on the live mirror, same question in two fresh sessions: with
+the section, the first tool call was `plinth backlinks`; without it, `grep -ril`.
+
+The generated file's line bound moves 51 → 56. Its schema-version stamp does not —
+the section is inline literal text, and none of the five constants the stamp hashes
+changed.
+
 ## 0.7.0 — 2026-08-23
 
 One PR and one docs commit since `0.6.0` (`v0.6.0..71c775c`). The mirror gains a

package/dist/build-stamp.json

@@ -1,5 +1,5 @@
 {
-  "sha": "c8ca82b2d16c0ed618813268f475e63ba0c4d26d",
+  "sha": "4a3be5d977539351a0cc5c0adc5617cb706b676b",
   "dirty": false,
-  "built_at": "2026-08-23T13:01:01.515Z"
+  "built_at": "2026-08-23T20:04:35.148Z"
 }

package/dist/cli.js

@@ -9193,7 +9193,7 @@ async function runMain(cmd, opts = {}) {
 // package.json
 var package_default = {
   name: "@plinth-music/cli",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Plinth capstone sync daemon and CLI",
   type: "module",
   private: false,
@@ -29507,6 +29507,7 @@ function backupStamp2(d2) {
 }
 
 // src/lib/context/workspace-claude-md.ts
+var EXTRACTED_TEXT_DIR = extractedTextRelPath("x").replace(/x\.md$/, "");
 function rosterBlock(roster, activeProjectCountBySlug) {
   if (roster.length === 0)
     return "_No artists synced yet._";
@@ -29555,6 +29556,11 @@ function buildWorkspaceClaudeMd(input) {
     `- Per-artist long-term facts → \`artists/<slug>/memory.md\`, which syncs to that artist's Plinth record; most have none yet, and creating the file is how you start one · rolling activity → \`artists/<slug>/daily-log.md\`, local-only and never the place for a durable fact`,
     `- ${MCP_AVAILABILITY_POINTER}`,
     ``,
+    `## Navigating the corpus`,
+    `- **What points at X?** → \`plinth backlinks "<name>"\`, a mirror path, or a wikilink target as written. Render-only blocks, code spans and comments are narrowed out; \`--unfiltered\` shows them. A bare name several files answer to is refused with the candidates listed, so re-run with the path it names`,
+    `- **What does this file link to?** → grep \`[[\` in it`,
+    `- **Find a file by name** → glob under \`files/\` \`documents/\` \`artists/\` · **text inside a PDF** → \`${EXTRACTED_TEXT_DIR}\` (folder map above) · **a task, project, artist or contact by field** → the \`mcp__plinth__*\` \`search_entities\` / \`list_*\` tools`,
+    ``,
     `## Entity model: ${MCP_INTROSPECTION_POINTER}`,
     ...entityLines,
     ``,
@@ -30555,10 +30561,12 @@ class DestructiveGate {
   settleMs;
   maxBatch;
   onSettle;
+  onError;
   constructor(opts) {
     this.settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
     this.maxBatch = opts.maxBatch ?? DEFAULT_MAX_BATCH;
     this.onSettle = opts.onSettle;
+    this.onError = opts.onError;
   }
   consider(op) {
     this.pending.push(op);
@@ -30587,7 +30595,11 @@ class DestructiveGate {
       return;
     const batch = this.pending;
     this.pending = [];
-    await this.onSettle(batch);
+    try {
+      await this.onSettle(batch);
+    } catch (err) {
+      this.onError?.(err);
+    }
   }
 }
 
@@ -32807,10 +32819,12 @@ class FileDestructiveGate {
   settleMs;
   maxBatch;
   onSettle;
+  onError;
   constructor(opts) {
     this.settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS2;
     this.maxBatch = opts.maxBatch ?? DEFAULT_MAX_BATCH2;
     this.onSettle = opts.onSettle;
+    this.onError = opts.onError;
   }
   consider(op) {
     this.pending.push(op);
@@ -32839,7 +32853,11 @@ class FileDestructiveGate {
       return;
     const batch = this.pending;
     this.pending = [];
-    await this.onSettle(batch);
+    try {
+      await this.onSettle(batch);
+    } catch (err) {
+      this.onError?.(err);
+    }
   }
 }
 
@@ -38644,6 +38662,97 @@ function discardSink() {
   const stream = { write: () => true };
   return { stdout: stream, stderr: stream };
 }
+async function flushHeldEntityOp(deps) {
+  const now = deps.now ?? (() => new Date);
+  try {
+    const result = await pushFile({
+      workspaceSlug: deps.workspaceSlug,
+      baseUrl: deps.baseUrl,
+      pat: deps.pat,
+      absolutePath: deps.op.absolutePath,
+      entityType: deps.op.entityType,
+      state: deps.getState(),
+      exists: deps.op.kind === "overwrite",
+      unlinkContext: deps.op.kind === "delete" ? { id: deps.op.id, slug: deps.op.slug, updated_at: deps.op.updatedAt } : null,
+      deps: {
+        fetchImpl: deps.fetchImpl,
+        now,
+        mutex: deps.mutex,
+        output: deps.output
+      }
+    });
+    deps.setState(result.state);
+    reportOutcome(deps.spinner, deps.workspaceSlug, deps.getState(), result.outcome);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "unknown push error";
+    deps.output?.log(pushFailedLine({
+      entityType: deps.op.entityType,
+      slug: deps.op.slug,
+      id: deps.op.id,
+      ...categorizeError(err)
+    }));
+    deps.spinner.warn(`Push failed for ${deps.op.entityType}/${deps.op.slug}: ${msg}`);
+    if (isRecordableFailure(err)) {
+      deps.setState(recordEntityUnsynced({
+        state: deps.getState(),
+        workspaceSlug: deps.workspaceSlug,
+        absolutePath: deps.op.absolutePath,
+        op: deps.op.kind === "delete" ? "delete" : "upsert",
+        err,
+        now
+      }));
+    }
+  }
+}
+async function flushHeldFileOpImpl(deps) {
+  const now = deps.now ?? (() => new Date);
+  const fileDeps = {
+    fetchImpl: deps.fetchImpl,
+    now,
+    output: deps.output,
+    suppressor: deps.suppressor
+  };
+  const run = async () => {
+    try {
+      const result = deps.op.kind === "delete" ? await pushFilesDelete({
+        workspaceSlug: deps.workspaceSlug,
+        baseUrl: deps.baseUrl,
+        pat: deps.pat,
+        relPath: deps.op.relPath,
+        state: deps.getState(),
+        deps: fileDeps
+      }) : await pushFilesUpsert({
+        workspaceSlug: deps.workspaceSlug,
+        baseUrl: deps.baseUrl,
+        pat: deps.pat,
+        absolutePath: deps.op.absolutePath,
+        relPath: deps.op.relPath,
+        state: deps.getState(),
+        deps: fileDeps
+      });
+      deps.setState(result.state);
+      reportFileOutcome(deps.spinner, deps.workspaceSlug, deps.getState(), result.outcome);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "unknown push error";
+      deps.output?.log(fileFailedLine({ path: deps.op.relPath, ...categorizeError(err) }));
+      deps.spinner.warn(`File push failed for files/${deps.op.relPath}: ${msg}`);
+      if (isRecordableFailure(err)) {
+        deps.setState(recordFileUnsynced({
+          state: deps.getState(),
+          relPath: deps.op.relPath,
+          op: deps.op.kind === "delete" ? "delete" : "upsert",
+          err,
+          now
+        }));
+      }
+    }
+  };
+  if (deps.mutex) {
+    await deps.mutex.run(`files:${deps.op.relPath}`, run);
+  } else {
+    await run();
+  }
+}
 async function runStart(workspaceSlug, deps = {}) {
   const daemonLog = deps.logSink ?? new DaemonLog({ path: daemonLogPath(), now: deps.now });
   const out = new Output({
@@ -38897,22 +39006,25 @@ async function runStart(workspaceSlug, deps = {}) {
     return r3 ? { entityType: r3.entityType, slug: r3.entitySlug } : null;
   };
   const suppressor = new PullSuppressor;
-  const flushHeldOp = async (op) => {
-    const result = await pushFile({
-      workspaceSlug: slug,
-      baseUrl: entry2.api_base_url,
-      pat,
-      absolutePath: op.absolutePath,
-      entityType: op.entityType,
-      state,
-      exists: op.kind === "overwrite",
-      unlinkContext: op.kind === "delete" ? { id: op.id, slug: op.slug, updated_at: op.updatedAt } : null,
-      deps: { fetchImpl, now: deps.now, mutex, output: out }
-    });
-    state = result.state;
-    reportOutcome(spinner, slug, state, result.outcome);
-  };
+  const flushHeldOp = (op) => flushHeldEntityOp({
+    workspaceSlug: slug,
+    baseUrl: entry2.api_base_url,
+    pat,
+    op,
+    getState: () => state,
+    setState: (s2) => {
+      state = s2;
+    },
+    mutex,
+    fetchImpl,
+    now: deps.now,
+    output: out,
+    spinner
+  });
   const gate = new DestructiveGate({
+    onError: (err) => {
+      out.log(`[DESTRUCTIVE_SETTLE_FAILED source=entity-watch reason=${categorizeError(err).reason}]`);
+    },
     onSettle: async (ops) => {
       const batch = dedupeOps(ops);
       if (batch.length === 0)
@@ -38935,43 +39047,49 @@ async function runStart(workspaceSlug, deps = {}) {
         prior_len: op.kind === "overwrite" ? op.priorLen : undefined,
         new_len: op.kind === "overwrite" ? op.newLen : undefined
       }));
-      const stashPath = stashPendingBatch({
-        workspaceSlug: slug,
-        batchId,
-        timestamp: ts,
-        tripReason: result.reason,
-        ops: pendingOps
-      });
+      let stashPath;
+      try {
+        stashPath = stashPendingBatch({
+          workspaceSlug: slug,
+          batchId,
+          timestamp: ts,
+          tripReason: result.reason,
+          ops: pendingOps
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "unknown error";
+        out.log(`[DESTRUCTIVE_HELD_STASH_FAILED source=entity-watch reason=${categorizeError(err).reason}]`);
+        spinner.warn(`Could not quarantine ${batch.length} destructive op${batch.length === 1 ? "" : "s"} (${msg}); they were dropped and stay local-only.`);
+        spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+        refreshFrozen();
+        return;
+      }
       refreshFrozen();
       out.log(`[DESTRUCTIVE_HELD batch=${batchId} ops=${batch.length} reason=${result.reason.kind}]`);
       spinner.warn(`Held ${batch.length} destructive op${batch.length === 1 ? "" : "s"} pending confirm → ${stashPath}. Run \`plinth confirm\` to review.`);
       spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
     }
   });
-  const flushHeldFileOp = async (op) => {
-    const fileDeps = { fetchImpl, now: deps.now, output: out, suppressor };
-    await mutex.run(`files:${op.relPath}`, async () => {
-      const result = op.kind === "delete" ? await pushFilesDelete({
-        workspaceSlug: slug,
-        baseUrl: entry2.api_base_url,
-        pat,
-        relPath: op.relPath,
-        state,
-        deps: fileDeps
-      }) : await pushFilesUpsert({
-        workspaceSlug: slug,
-        baseUrl: entry2.api_base_url,
-        pat,
-        absolutePath: op.absolutePath,
-        relPath: op.relPath,
-        state,
-        deps: fileDeps
-      });
-      state = result.state;
-      reportFileOutcome(spinner, slug, state, result.outcome);
-    });
-  };
+  const flushHeldFileOp = (op) => flushHeldFileOpImpl({
+    workspaceSlug: slug,
+    baseUrl: entry2.api_base_url,
+    pat,
+    op,
+    getState: () => state,
+    setState: (s2) => {
+      state = s2;
+    },
+    mutex,
+    fetchImpl,
+    now: deps.now,
+    output: out,
+    spinner,
+    suppressor
+  });
   const fileGate = new FileDestructiveGate({
+    onError: (err) => {
+      out.log(`[DESTRUCTIVE_SETTLE_FAILED source=files-watch reason=${categorizeError(err).reason}]`);
+    },
     onSettle: async (ops) => {
       const batch = dedupeFileOps(ops);
       if (batch.length === 0)
@@ -38985,13 +39103,23 @@ async function runStart(workspaceSlug, deps = {}) {
       const ts = (deps.now ?? (() => new Date))();
       const batchId = batchIdFromTimestamp(ts);
       const pendingOps = batch.map(fileOpToPendingOp);
-      const stashPath = stashPendingBatch({
-        workspaceSlug: slug,
-        batchId,
-        timestamp: ts,
-        tripReason: result.reason,
-        ops: pendingOps
-      });
+      let stashPath;
+      try {
+        stashPath = stashPendingBatch({
+          workspaceSlug: slug,
+          batchId,
+          timestamp: ts,
+          tripReason: result.reason,
+          ops: pendingOps
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "unknown error";
+        out.log(`[DESTRUCTIVE_HELD_STASH_FAILED source=files-watch reason=${categorizeError(err).reason}]`);
+        spinner.warn(`Could not quarantine ${batch.length} destructive file op${batch.length === 1 ? "" : "s"} (${msg}); they were dropped and stay local-only.`);
+        spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+        refreshFrozen();
+        return;
+      }
       refreshFrozen();
       out.log(`[DESTRUCTIVE_HELD batch=${batchId} ops=${batch.length} reason=${result.reason.kind} source=files-watch]`);
       spinner.warn(`Held ${batch.length} destructive file op${batch.length === 1 ? "" : "s"} pending confirm → ${stashPath}. Run \`plinth confirm\` to review.`);

package/package.json

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