@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/lessons/matcher.ts

@@ -0,0 +1,346 @@
+/**
+ * Lesson trigger matching. Pure -- no fs, no config, no pi, no clock. Every
+ * input is passed in, which is what lets the table be tested exhaustively and
+ * what lets one implementation answer for a live tool result, a plan step and
+ * an eval fixture.
+ *
+ * Three deliberate properties:
+ *
+ * - **`isError` is not an input.** A lesson fires on what a result SAYS, not on
+ *   whether pi called it an error. Galaxy reports a failed invocation inside a
+ *   perfectly successful tool result (`invocation-failure-hint.ts` relies on
+ *   the same thing), so gating on `isError` would miss the cases that matter.
+ * - **A lesson with a non-empty `graduated_to` never matches.** Its advice
+ *   already ships somewhere else, and surfacing both is noise. The lesson stays
+ *   in the corpus as the record of what happened.
+ * - **Signatures are matched after normalizing BOTH sides with C1's own
+ *   function.** A stored signature already carries C1's placeholders, so a raw
+ *   substring test could never hit, and a second implementation of those rules
+ *   would drift from the one that normalized the corpus. Two matching-only
+ *   additions on top: it is applied PER LINE (its "first line only" clause
+ *   turns one error into one signature; applied to a whole tool result it would
+ *   see only line 1), and both sides are lowercased, because a lesson author
+ *   will not match the tool's capitalization.
+ */
+
+import { normalizeSignature, UNKNOWN_SIGNATURE } from "../../../shared/observation-contract.js";
+import type { Lesson, Match, MatchTrigger } from "./types";
+
+/** Lower is more specific, so a signature hit beats an ambient step-text hit. */
+const TRIGGER_RANK: Record<MatchTrigger, number> = {
+  signature: 0,
+  tool: 1,
+  host: 2,
+  extension: 3,
+  step_keyword: 4,
+  search: 5,
+};
+
+/** Caps so a hostile result or a pathological lesson cannot burn the turn. */
+const MAX_RESULT_CHARS = 200_000;
+const MAX_ARG_CHARS = 20_000;
+const MAX_VALUE_DEPTH = 6;
+const MAX_VALUES = 500;
+const MAX_STEP_CHARS = 4_000;
+
+/** A short "signature" would match nearly every result (C3 sets the same floor). */
+const MIN_SIGNATURE_CHARS = 8;
+
+/** Shorter than this a tool id or keyword cannot discriminate. */
+const MIN_TOOL_CHARS = 3;
+
+/**
+ * `normalizeSignature` keeps one line and truncates at 200 (C1's cap), so a
+ * long single line -- a serialized JSON blob, a stack frame -- is scanned in
+ * overlapping windows instead. Each window's normalized text is itself cut at
+ * 200, so a window starting at most STRIDE characters before a signature
+ * holds it whole when the signature normalizes to at most 200 - STRIDE = 150
+ * characters. Longer signatures (C1 allows 200) can be missed on lines over
+ * WINDOW characters; the shipped corpus tops out well under 100.
+ */
+const WINDOW = 256;
+const STRIDE = 50;
+
+/** Every line of the result, run through `normalizeSignature` and lowercased. */
+export function matchHaystack(resultText: string): string[] {
+  const out: string[] = [];
+  const push = (raw: string): void => {
+    const normalized = normalizeSignature(raw);
+    if (normalized !== UNKNOWN_SIGNATURE) out.push(normalized.toLowerCase());
+  };
+
+  for (const line of resultText.slice(0, MAX_RESULT_CHARS).split("\n")) {
+    if (!line.trim()) continue;
+    if (line.length <= WINDOW) {
+      push(line);
+      continue;
+    }
+    // Run to the very end: the window that first touches it is also cut at
+    // 200 once normalized, so the line's tail needs the shorter ones too.
+    for (let i = 0; i < line.length; i += STRIDE) push(line.slice(i, i + WINDOW));
+  }
+  return out;
+}
+
+/**
+ * Every string VALUE in a call's arguments, recursively. Values only: matching
+ * key names would let a lesson fire on a schema field rather than on data.
+ */
+export function collectStringValues(value: unknown, depth = 0, out: string[] = []): string[] {
+  if (depth > MAX_VALUE_DEPTH || out.length >= MAX_VALUES) return out;
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) {
+    for (const v of value) collectStringValues(v, depth + 1, out);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) collectStringValues(v, depth + 1, out);
+  }
+  return out;
+}
+
+const URL_HOST = /\b[a-z][a-z0-9+.-]*:\/\/([^/?#\s"'`\\]+)/gi;
+
+export function extractHosts(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of text.matchAll(URL_HOST)) {
+    let host = m[1];
+    const at = host.lastIndexOf("@");
+    if (at >= 0) host = host.slice(at + 1);
+    host = host.replace(/:\d*$/, "").replace(/\.$/, "").toLowerCase();
+    if (host) out.add(host);
+  }
+  return out;
+}
+
+/**
+ * A lesson host matches the exact host or any subdomain of it, on a dot
+ * boundary. Without the boundary `ncbi.nlm.nih.gov` would also match
+ * `evilncbi.nlm.nih.gov`.
+ */
+export function hostMatches(seen: Set<string>, want: string): boolean {
+  const w = want.trim().toLowerCase().replace(/^\.+/, "");
+  if (!w) return false;
+  for (const host of seen) {
+    if (host === w || host.endsWith(`.${w}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Letter-led, so a version segment (`tool/2.0.1`) never reads as an extension.
+ * A following `.` counts as a boundary because double suffixes are everywhere
+ * here -- `.fastq.gz` has to yield both halves.
+ */
+const EXT_TOKEN = /\.([A-Za-z][A-Za-z0-9]{0,7})(?=[."'\s,;:)\]}\\]|$)/g;
+
+export function extractExtensions(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of text.matchAll(EXT_TOKEN)) out.add(m[1].toLowerCase());
+  return out;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * A lesson extension (".gtf", ".tsv.gz") on the end of a file name somewhere
+ * in the arguments. Matched as one dotted unit so a two-part extension means
+ * what its author wrote, and anchored on a name character before the dot so a
+ * bare ".gtf" in prose is not a file.
+ */
+export function extensionMatches(haystack: string, want: string): boolean {
+  const w = want.trim().toLowerCase().replace(/^\.+/, "");
+  if (!w) return false;
+  const re = new RegExp(`[A-Za-z0-9_-]\\.${escapeRegExp(w)}(?![A-Za-z0-9])`, "i");
+  return re.test(haystack);
+}
+
+/**
+ * `<host>/repos/<owner>/<repo>/<name>[/<version>]` -> `<name>`. Lesson tool
+ * triggers are short ids or families (C3 forbids `/` in them), while a Galaxy
+ * call carries the full ToolShed GUID, so the GUID's name segment is the part
+ * a lesson can name.
+ */
+const TOOLSHED_GUID =
+  /^(?:https?:\/\/)?[^/\s]+\/repos\/[^/\s]+\/[^/\s]+\/([^/\s]+)(?:\/[^/\s]+)?$/i;
+
+/**
+ * Every string argument that could be a tool id, as lowercased candidates: the
+ * value itself (a bare id like `Filter1`) and, for a ToolShed GUID, its name
+ * segment. A lesson's `trigger.tools` entry has to equal one of them.
+ */
+export function toolCandidates(values: readonly string[]): Set<string> {
+  const out = new Set<string>();
+  for (const raw of values) {
+    const v = raw.trim();
+    if (!v || v.length > 300) continue;
+    out.add(v.toLowerCase());
+    const guid = TOOLSHED_GUID.exec(v);
+    if (guid) out.add(guid[1].toLowerCase());
+  }
+  return out;
+}
+
+export function toolMatches(candidates: Set<string>, want: string): boolean {
+  const w = want.trim().toLowerCase();
+  return w.length >= MIN_TOOL_CHARS && candidates.has(w);
+}
+
+/**
+ * Lessons written before the in-process tools named Galaxy tools this way; a
+ * user's lessons dir can still hold them, so they keep firing on the bare call.
+ */
+const LEGACY_LESSON_PREFIX = "mcp__galaxy__";
+
+/**
+ * The Galaxy tool behind a name, or undefined when it is not one. The remainder
+ * is held to the Galaxy tools' own name shape -- no leading "_", no "__" -- on
+ * both sides, so a lesson naming `galaxy__x` cannot line up with another
+ * server's `mcp__<server>__x` spelling.
+ */
+function galaxyToolOf(name: string): string | undefined {
+  const raw = name.trim();
+  const tool = raw.toLowerCase().startsWith("galaxy_") ? raw.slice("galaxy_".length) : raw;
+  if (!tool || tool.startsWith("_") || tool.includes("__")) return undefined;
+  return tool.toLowerCase();
+}
+
+/**
+ * Compared after stripping the `galaxy_` prefix from both sides, so a lesson
+ * written against `galaxy_run_tool` still fires when the call arrived as
+ * `run_tool`. The legacy prefix is stripped from the lesson only: a call named
+ * `mcp__galaxy__x` comes from a server the user added, not the Galaxy tools.
+ */
+export function mcpToolMatches(toolName: string, want: string): boolean {
+  const lessonTool = want.trim().toLowerCase().startsWith(LEGACY_LESSON_PREFIX)
+    ? want.trim().slice(LEGACY_LESSON_PREFIX.length)
+    : want;
+  const a = galaxyToolOf(toolName);
+  const b = galaxyToolOf(lessonTool);
+  return a !== undefined && b !== undefined && a === b;
+}
+
+export function isMatchable(lesson: Lesson): boolean {
+  return !(lesson.graduated_to ?? []).some((g) => typeof g === "string" && g.trim().length > 0);
+}
+
+function firstHit(
+  trigger: MatchTrigger,
+  values: readonly string[] | undefined,
+  test: (value: string) => boolean,
+): { trigger: MatchTrigger; matched: string } | null {
+  for (const value of values ?? []) {
+    if (typeof value !== "string") continue;
+    if (test(value)) return { trigger, matched: value };
+  }
+  return null;
+}
+
+function originRank(lesson: Lesson): number {
+  // A lesson you recorded yourself is about your machine and your data, so on
+  // an equal trigger it goes ahead of the shipped corpus.
+  return lesson.origin === "user" ? 0 : 1;
+}
+
+function rank(matches: Match[]): Match[] {
+  return matches.sort((a, b) => {
+    const byTrigger = TRIGGER_RANK[a.trigger] - TRIGGER_RANK[b.trigger];
+    if (byTrigger !== 0) return byTrigger;
+    const byOrigin = originRank(a.lesson) - originRank(b.lesson);
+    if (byOrigin !== 0) return byOrigin;
+    return a.lesson.id < b.lesson.id ? -1 : a.lesson.id > b.lesson.id ? 1 : 0;
+  });
+}
+
+export interface ToolEventInput {
+  /**
+   * pi's tool name: the Galaxy tools by their bare names, Orbit's own as
+   * `galaxy_<name>`. mcpToolMatches strips the `galaxy_` prefix, so a lesson can
+   * name the tool either way.
+   */
+  toolName: string;
+  /** The call's arguments. */
+  input: Record<string, unknown>;
+  /** Every text block of the result, joined with newlines. */
+  resultText: string;
+}
+
+/** One match per lesson, most specific trigger first. */
+export function matchToolEvent(ev: ToolEventInput, lessons: readonly Lesson[]): Match[] {
+  const lines = matchHaystack(ev.resultText);
+  const values = collectStringValues(ev.input);
+  const args = values.join("\n").slice(0, MAX_ARG_CHARS);
+  const hosts = extractHosts(args);
+  const exts = extractExtensions(args);
+  const tools = toolCandidates(values);
+  const argValues = new Set(values.map((v) => v.trim().toLowerCase()));
+
+  const out: Match[] = [];
+  for (const lesson of lessons) {
+    if (!isMatchable(lesson)) continue;
+    const t = lesson.trigger ?? {};
+    const hit =
+      firstHit("signature", t.signatures, (s) => {
+        // Normalized on this side too: a corpus signature already is, and the
+        // function is idempotent.
+        const needle = normalizeSignature(s).toLowerCase();
+        return (
+          needle !== UNKNOWN_SIGNATURE &&
+          needle.length >= MIN_SIGNATURE_CHARS &&
+          lines.some((l) => l.includes(needle))
+        );
+      }) ??
+      firstHit("tool", t.mcp_tools, (s) => mcpToolMatches(ev.toolName, s)) ??
+      firstHit("tool", t.tools, (s) => toolMatches(tools, s)) ??
+      firstHit("host", t.hosts, (s) => hostMatches(hosts, s)) ??
+      firstHit("extension", t.extensions, (s) => extensionMatches(args, s)) ??
+      // C5 has no `format` trigger value, so a datatype hit reports as the
+      // nearest one. Matched two ways because C3 uses `formats` for both Galaxy
+      // datatype names and extensions: a `file_type: "gtf"` argument, and a
+      // `.gtf` on a file name.
+      firstHit("extension", t.formats, (s) => {
+        const f = s.trim().toLowerCase().replace(/^\.+/, "");
+        return f.length > 0 && (exts.has(f) || argValues.has(f));
+      });
+    if (hit) out.push({ lesson, trigger: hit.trigger, matched: hit.matched });
+  }
+  return rank(out);
+}
+
+/**
+ * Fold to lowercase words separated by single spaces, padded with spaces, so
+ * a keyword test is a whole-word (or whole-phrase) test -- `gtf` must not
+ * match `gtfoobar`, and `sample to condition` has to match
+ * "sample-to-condition".
+ */
+export function wordHaystack(text: string): string {
+  const folded = text
+    .slice(0, MAX_STEP_CHARS)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+  return ` ${folded} `;
+}
+
+/**
+ * Plan-step matching. `/execute` already parses the next step's text before
+ * building its prompt, so matched lessons can ride along at no extra cost. It
+ * only reaches what the step says -- there is no stage state to ask instead,
+ * and no regex answers "is this a normalizing step?". That gap is why the
+ * reproduction index exists.
+ */
+export function matchStepText(text: string, lessons: readonly Lesson[]): Match[] {
+  const hay = wordHaystack(text);
+  if (hay.trim().length === 0) return [];
+
+  const out: Match[] = [];
+  for (const lesson of lessons) {
+    if (!isMatchable(lesson)) continue;
+    const hit = firstHit("step_keyword", lesson.trigger?.step_keywords, (kw) => {
+      const needle = wordHaystack(kw);
+      return needle.trim().length >= MIN_TOOL_CHARS && hay.includes(needle);
+    });
+    if (hit) out.push({ lesson, trigger: hit.trigger, matched: hit.matched });
+  }
+  return rank(out);
+}

package/extensions/orbit/lessons/paths.ts

@@ -0,0 +1,286 @@
+/**
+ * Where local lessons and staged drafts live on disk.
+ *
+ * Two placements carry weight:
+ *
+ * - Lessons go under getConfigDir(), which is ~/.loom today and ~/.orbit after
+ *   the rename (shared/state-dir.js). Nothing here joins homedir() with
+ *   ".loom" itself, so the move stays one switch. LOOM_LESSONS_DIR replaces
+ *   that directory for the writer and the store alike (./user-dir), so a
+ *   lesson saved here is a lesson the store loads.
+ * - Staged drafts go in a SIBLING directory, not inside lessons/. A draft the
+ *   user has not approved must not be loadable as a lesson, and a separate
+ *   directory guarantees that without the lesson store having to know the
+ *   difference. The flat `<namespace>__<slug>.md` name also cannot satisfy
+ *   lessonIdFromPath, which requires exactly `<namespace>/<slug>.md`.
+ */
+
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { getConfigDir } from "../../../shared/orbit-config.js";
+import { userLessonsDir } from "./user-dir";
+import {
+  LESSON_NAMESPACES,
+  MAX_FILE_BYTES,
+  isValidLessonNamespace,
+  isValidLessonSlug,
+  lessonIdFromPath,
+} from "../../../shared/lesson-rules.js";
+
+export interface LocalLesson {
+  id: string;
+  namespace: string;
+  slug: string;
+  path: string;
+}
+
+export function lessonsDir(): string {
+  return userLessonsDir();
+}
+
+export function draftsDir(): string {
+  return path.join(getConfigDir(), "lesson-drafts");
+}
+
+/**
+ * Throws rather than returning null: every caller has already validated, so a
+ * bad value here means a check was skipped, and building a path anyway would
+ * be a traversal write.
+ */
+function assertId(namespace: string, slug: string): void {
+  if (!isValidLessonNamespace(namespace)) {
+    throw new Error(`not a lesson namespace: ${JSON.stringify(namespace)}`);
+  }
+  if (!isValidLessonSlug(slug)) {
+    throw new Error(`not a lesson slug: ${JSON.stringify(slug)}`);
+  }
+}
+
+export function lessonFilePath(namespace: string, slug: string): string {
+  assertId(namespace, slug);
+  return path.join(lessonsDir(), namespace, `${slug}.md`);
+}
+
+export function draftFilePath(namespace: string, slug: string): string {
+  assertId(namespace, slug);
+  return path.join(draftsDir(), `${namespace}__${slug}.md`);
+}
+
+/** Split `<namespace>/<slug>` into its parts, or null if it is not a lesson id. */
+export function parseLessonId(raw: unknown): { namespace: string; slug: string } | null {
+  if (typeof raw !== "string") return null;
+  const parts = raw.replace(/^[ \t]+|[ \t]+$/g, "").split("/");
+  if (parts.length !== 2) return null;
+  const [namespace, slug] = parts;
+  if (!isValidLessonNamespace(namespace) || !isValidLessonSlug(slug)) return null;
+  return { namespace, slug };
+}
+
+export function listLocalLessons(): LocalLesson[] {
+  const root = lessonsDir();
+  const out: LocalLesson[] = [];
+  for (const namespace of LESSON_NAMESPACES) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(path.join(root, namespace), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      // isFile() is false for a symlink file; a symlinked directory is caught
+      // when the file is read (parentIsReal).
+      if (!entry.isFile()) continue;
+      const id = lessonIdFromPath(`${namespace}/${entry.name}`);
+      if (!id) continue;
+      out.push({
+        id,
+        namespace,
+        slug: entry.name.slice(0, -3),
+        path: path.join(root, namespace, entry.name),
+      });
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function listDrafts(): LocalLesson[] {
+  const root = draftsDir();
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: LocalLesson[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const parts = entry.name.slice(0, -3).split("__");
+    if (parts.length !== 2) continue;
+    const [namespace, slug] = parts;
+    if (!isValidLessonNamespace(namespace) || !isValidLessonSlug(slug)) continue;
+    out.push({ id: `${namespace}/${slug}`, namespace, slug, path: path.join(root, entry.name) });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export type ReadResult = { ok: true; text: string } | { ok: false; detail: string };
+
+/**
+ * Read a lesson or draft, refusing anything over the schema's byte cap or that
+ * is not a regular file. lstat rather than stat so a symlink is refused rather
+ * than followed, and the cap is checked before the read so a planted 2 GB file
+ * costs a syscall, not the heap.
+ */
+export function readLessonFile(filePath: string): ReadResult {
+  try {
+    if (!parentIsReal(filePath)) return { ok: false, detail: "inside a symlinked directory" };
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile()) return { ok: false, detail: "not a regular file" };
+    if (stat.size > MAX_FILE_BYTES) {
+      return { ok: false, detail: `file is too large (cap is ${MAX_FILE_BYTES} bytes)` };
+    }
+    return { ok: true, text: fs.readFileSync(filePath, "utf-8") };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    return { ok: false, detail: code === "ENOENT" ? "no such file" : (code ?? "unreadable") };
+  }
+}
+
+export type WriteResult = { ok: true } | { ok: false; reason: "exists" | "error"; detail?: string };
+
+function errorDetail(err: unknown): string {
+  return (err as NodeJS.ErrnoException)?.code ?? (err instanceof Error ? err.message : "error");
+}
+
+/**
+ * The directory a path under the lessons tree is measured from. With
+ * LOOM_LESSONS_DIR set, the directory the user named is the root for anything
+ * under it -- itself possibly a link, wherever it sits, the same as the store
+ * reads it. Otherwise the state dir, so a linked lessons/ inside it is refused.
+ * The state dir itself may be a link (dotfile setups do that).
+ */
+function rootOf(p: string): string | undefined {
+  const stateDir = getConfigDir();
+  const overridden = lessonsDir() !== path.join(stateDir, "lessons");
+  const roots = overridden ? [lessonsDir(), stateDir] : [stateDir];
+  return roots.find((r) => {
+    const rel = path.relative(r, p);
+    return !rel.startsWith("..") && !path.isAbsolute(rel);
+  });
+}
+
+/** True when `p` exists and nothing between its root and it is a link. */
+function resolvesInPlace(root: string, p: string): boolean {
+  return fs.realpathSync(p) === path.join(fs.realpathSync(root), path.relative(root, p));
+}
+
+/**
+ * True when no directory between the root and `filePath` is a symlink.
+ * lstat on the file only covers its last component; a linked lessons/ or
+ * namespace directory would otherwise send reads and writes somewhere else.
+ * A directory that does not exist yet is judged by its nearest existing
+ * ancestor, so the check can run before mkdir creates anything through a link.
+ */
+function parentIsReal(filePath: string): boolean {
+  const dir = path.dirname(filePath);
+  const root = rootOf(dir);
+  if (!root) return false;
+  for (let probe = dir; ; probe = path.dirname(probe)) {
+    try {
+      return resolvesInPlace(root, probe);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") return false;
+      // A dangling link is something there, not nothing.
+      if (fs.lstatSync(probe, { throwIfNoEntry: false })) return false;
+      // Nothing there yet means nothing to follow; the caller's own fs call
+      // reports the missing file.
+      if (probe === root) return true;
+    }
+  }
+}
+
+/** Write the bytes beside `filePath` under a name nothing else will pick. */
+function writeTemp(filePath: string, text: string): string {
+  const tmp = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${crypto.randomBytes(6).toString("hex")}.tmp`,
+  );
+  const fd = fs.openSync(tmp, "wx", 0o644);
+  try {
+    fs.writeSync(fd, text);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return tmp;
+}
+
+/**
+ * Create the lesson or fail -- never replace one. The bytes go to a temp file
+ * first and are hard-linked into place, so the lesson appears whole or not at
+ * all, and link() refuses an existing target in the same syscall that would
+ * otherwise race an exists-check. Nothing on this path rewrites a lesson: an
+ * id that is taken is a new slug's problem, not an overwrite.
+ */
+export function writeNoClobber(filePath: string, text: string): WriteResult {
+  const refused: WriteResult = { ok: false, reason: "error", detail: "symlinked directory" };
+  let tmp: string;
+  try {
+    if (!parentIsReal(filePath)) return refused;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (!parentIsReal(filePath)) return refused;
+    tmp = writeTemp(filePath, text);
+  } catch (err) {
+    return { ok: false, reason: "error", detail: errorDetail(err) };
+  }
+  try {
+    fs.linkSync(tmp, filePath);
+    // The checks above run before the write, so a directory swapped for a
+    // link in between would carry the lesson out of the tree. Look at where
+    // it actually landed and take it back if that is somewhere else.
+    const root = rootOf(filePath);
+    let inPlace = false;
+    try {
+      inPlace = root !== undefined && resolvesInPlace(root, filePath);
+    } catch {
+      /* unresolvable counts as not in place */
+    }
+    if (!inPlace) {
+      fs.unlinkSync(filePath);
+      return refused;
+    }
+    return { ok: true };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "EEXIST") return { ok: false, reason: "exists" };
+    return { ok: false, reason: "error", detail: errorDetail(err) };
+  } finally {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* a stray dot-file is harmless; the lesson write already reported */
+    }
+  }
+}
+
+/** Drafts are scratch space, so a re-proposal replaces one. Still atomic. */
+export function writeOverwrite(
+  filePath: string,
+  text: string,
+): { ok: true } | { ok: false; detail: string } {
+  try {
+    if (!parentIsReal(filePath)) return { ok: false, detail: "symlinked directory" };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (!parentIsReal(filePath)) return { ok: false, detail: "symlinked directory" };
+    const tmp = writeTemp(filePath, text);
+    try {
+      fs.renameSync(tmp, filePath);
+    } catch (err) {
+      fs.rmSync(tmp, { force: true });
+      throw err;
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: errorDetail(err) };
+  }
+}