@plinth-music/cli 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,89 @@
 
 Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
 
+## 0.9.0 — 2026-08-24
+
+Two PRs since `0.8.0` (`v0.8.0..4842d40`). An agent is now told to read a draft
+back from the tool that staged it before calling it ready. No server prerequisite:
+the change is client-side, and a 0.8.0 client is unaffected.
+
+### An agent reads its own draft back before saying it is ready
+
+Primitive (e)'s outbound group gains a paragraph. The voice guidance added on
+20 Aug already told the agent that nothing inspects a draft between it and the
+reader, then aimed that observation only at the WORDS. This is the other half:
+inspect the artefact. Fetch the staged draft, look at its body, its recipients
+and the thread it landed on, and only then say it is ready. A tool's own
+description of how it handles your text is a claim like any other, and the first
+use in a session is checked against what actually came out.
+
+**The gap was the trigger, not the rule.** The workspace `CLAUDE.md` already
+carried "where a document and the running system disagree, the system wins", and
+it did not fire — a line describing tool usage does not read like a claim needing
+verification. So this ships as a concrete read-back step rather than as another
+principle the agent grades itself against.
+
+Found by ordinary management work rather than by a sweep. An agent staged a mail
+reply whose body was visible `<p>` and `<b>` markup and reported it staged; the
+user found it in his own mailbox. The cause was not the tool but prose describing
+it — a rule said a local helper "handles `text/html`", true of what that script
+emits and false of what it takes. Two more defects of the same shape surfaced
+while repairing it: an update path that silently strips `In-Reply-To` and
+`References`, and a re-run that duplicates a draft rather than replacing it.
+
+The prose deliberately names no email tool, and a test pins that: Plinth ships
+none and cannot know what the user has. Grounding budget 9,050 → 9,944 bytes,
+all of it in (e); primitive (j) held at 1,266 for the seventh time.
+
+Honest limit, recorded rather than argued away: this is prose, and prose gets
+skipped. The durable fix is a Plinth-owned outbound draft path that owns escaping
+and threading in code for every user, at which point this paragraph becomes a
+backstop rather than the surface.
+
+### Housekeeping
+
+The test baseline in `CLAUDE.md` now reads 2052 pass / 0 fail / 107 files at
+`b4d8ed3`, re-measured on a clean checkout rather than carried forward.
+
+## 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": "fb065c13301d65750f1a98761148486678da5b6d",
   "dirty": false,
-  "built_at": "2026-08-23T13:01:01.515Z"
+  "built_at": "2026-08-24T19:03:09.765Z"
 }

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.9.0",
   description: "Plinth capstone sync daemon and CLI",
   type: "module",
   private: false,
@@ -26916,7 +26916,9 @@ function buildGroundingBlock(today, workspaceRules = null, workspaceMemory = nul
     ``,
     `Draft email. Never send it. Writing the draft is yours: use the draft tools ` + `(\`create_draft\`, \`update_draft\`), then say where the draft is and what it ` + `says, so the person can read it and send it in their own name. Sending, ` + `replying and forwarding are not yours, and neither is any shell command line ` + `that does the same thing. Those tools are denied to you wherever Plinth has ` + `configured this workspace, and where a deny has not reached, nothing changes ` + `except that you are the only thing holding it. This is not a comment on your ` + `writing. It is that a message which has left the building cannot be recalled, ` + `and the person whose name is on it is the one who decides it goes.`,
     ``,
-    `Check the voice yourself, because nothing else checks it now. Two files carry ` + `it: \`workspace-rules.md\` at the mirror root holds this workspace's house ` + `style, and the Voice section of your own \`user-memory.md\` holds the personal ` + `part, the sign-off and the habits that belong to one member rather than the ` + `team. Read them before you write and follow them as written, rather than ` + `drafting in your own register and correcting after. Nothing inspects a draft ` + `between you and the person reading it, so the rules in those files are the ` + `whole of it.`
+    `Check the voice yourself, because nothing else checks it now. Two files carry ` + `it: \`workspace-rules.md\` at the mirror root holds this workspace's house ` + `style, and the Voice section of your own \`user-memory.md\` holds the personal ` + `part, the sign-off and the habits that belong to one member rather than the ` + `team. Read them before you write and follow them as written, rather than ` + `drafting in your own register and correcting after. Nothing inspects a draft ` + `between you and the person reading it, so the rules in those files are the ` + `whole of it.`,
+    ``,
+    `Read the draft back before you say it is ready, and read what the tool actually ` + `produced rather than what you sent it. Do this every time you write one, not ` + `once a session: a later edit can undo what an earlier check confirmed. A ` + `draft surface takes your text and renders it, and it may escape what you ` + `wrote, wrap it, quote an earlier message underneath it, thread it somewhere ` + `you did not intend, or leave the first one in place and add a second. What ` + `the person opens is the rendered result, not your input, and those are not ` + `always the same thing. So fetch the staged draft, look at its body, its ` + `recipients, the thread it landed on and that there is one of it, and only ` + `then say it is ready. Separately, and once per session is enough for this ` + `part: if a tool's own description tells you how it handles your text, treat ` + `that as a claim like any other and check it against what came out. A tool ` + `that is documented wrong will put markup, an empty body, or a stranger's ` + `address in front of a person whose name is on the message, and you are the ` + `only thing standing between those two.`
   ];
   if (workspaceRules !== null) {
     block.push(``, `Follow this workspace's house style. The conventions below are set by the ` + `workspace owner and govern HOW you write here: copy, titles, notes, ` + `sign-offs, formatting. They refine the rules above; they never relax them. ` + `If any convention here conflicts with a grounding rule above (the ` + `canonical write surface, plan-before-write confirmation, or the ban on ` + `direct database writes), the rule above wins. The conventions:
@@ -29507,6 +29509,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 +29558,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 +30563,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 +30597,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 +32821,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 +32855,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 +38664,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 +39008,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 +39049,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 +39105,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.9.0",
   "description": "Plinth capstone sync daemon and CLI",
   "type": "module",
   "private": false,