pi-weave 0.3.8 → 0.3.10

package/src/core/history.ts

@@ -0,0 +1,417 @@
+import { promises as fs } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { OKF_MANIFEST } from "./paths";
+
+/**
+ * Note history: a copy of every note after every change, so the viewer can
+ * replay how a note was written from its first words to now.
+ *
+ * ## Why a log file and not git
+ *
+ * The vault is not guaranteed to be a git repository, and when it is, the
+ * repository belongs to the user: committing on every append would bury their
+ * own history under ours. A plain append-only file per note keeps the
+ * project's rule that knowledge lives in readable files, needs no binary, and
+ * travels with the vault (the backup ZIP walks the whole vault root).
+ *
+ * ## Format
+ *
+ * `<vault>/history/<slug>.jsonl`, one JSON object per revision, oldest first.
+ * A revision is either a full copy of the body (`full`) or a delta against
+ * the revision before it: keep `keep[0]` characters from the start and
+ * `keep[1]` from the end, and put `text` between them. Appends and small
+ * edits cost a few bytes. Every {@link KEYFRAME_EVERY}th revision is full, so
+ * one damaged line cannot take the rest of the log with it.
+ *
+ * Bodies only, not front matter: the `updated` stamp changes on every write
+ * and would turn every delta into a copy of the whole file.
+ *
+ * ## Who wrote it
+ *
+ * Every write path in `vault.ts` says who is writing. An edit made outside
+ * pi-weave (an editor, a sync tool) is noticed the next time pi-weave writes
+ * or replays the note: the body on disk no longer matches the last revision,
+ * so it is recorded as an `outside` revision before anything else.
+ *
+ * ## Size limits
+ *
+ * A note's log is compacted once it holds more than {@link MAX_REVISIONS}
+ * revisions or {@link MAX_LOG_BYTES} bytes. Compaction drops the oldest
+ * revisions until the log is back under {@link COMPACT_TO} of both limits
+ * (so it does not run again on the next write), rewrites what is left with
+ * a full copy first, and marks that line `trimmed`. The newest revision is
+ * always kept, however large the note.
+ *
+ * ## Off switch
+ *
+ * `"history": false` in the vault's `okf.json` stops recording. Existing logs
+ * are kept, and nothing is recorded while it is off — including outside edits.
+ */
+
+export const HISTORY_DIR = "history";
+const LOG_EXT = ".jsonl";
+/** A full copy every this many revisions bounds the damage of a bad line. */
+export const KEYFRAME_EVERY = 32;
+/** Most revisions one note's log keeps. */
+export const MAX_REVISIONS = 500;
+/** Largest one note's log may grow, in bytes, before it is compacted. */
+export const MAX_LOG_BYTES = 4 * 1024 * 1024;
+/** Compaction brings a log back to this share of both limits. */
+export const COMPACT_TO = 0.8;
+
+/** Who made a change. `outside` is any editor other than pi-weave. */
+export type HistoryAuthor = "human" | "agent" | "outside" | "system";
+export const HISTORY_AUTHORS: readonly HistoryAuthor[] = ["human", "agent", "outside", "system"];
+
+/** What kind of change it was. `baseline` is a note as history first found it. */
+export type HistoryOp =
+  | "create"
+  | "edit"
+  | "append"
+  | "raw"
+  | "finalize"
+  | "generate"
+  | "repair"
+  | "outside"
+  | "baseline";
+export const HISTORY_OPS: readonly HistoryOp[] = [
+  "create",
+  "edit",
+  "append",
+  "raw",
+  "finalize",
+  "generate",
+  "repair",
+  "outside",
+  "baseline",
+];
+
+/** One revision of a note, with its body reconstructed. */
+export interface NoteRevision {
+  /** ISO-8601 time of the change. */
+  at: string;
+  by: HistoryAuthor;
+  op: HistoryOp;
+  body: string;
+}
+
+/** A line of the log, as stored, and the shape the viewer receives. */
+export interface LogEntry {
+  at: string;
+  by: HistoryAuthor;
+  op: HistoryOp;
+  full?: string;
+  keep?: [number, number];
+  text?: string;
+  /** On the first line only: older revisions were dropped to keep the log small. */
+  trimmed?: true;
+}
+
+/** The note body as it stood before a write, and when it got that way. */
+export interface PriorBody {
+  body: string;
+  at: string;
+}
+
+export interface RecordInput {
+  by: HistoryAuthor;
+  op: HistoryOp;
+  /** The body before this write; null for a brand-new note. */
+  before: PriorBody | null;
+  /** The body after this write. */
+  after: string;
+  at: Date;
+}
+
+/** Resolve a note's log path, or null when the slug would escape the log directory. */
+export function historyPath(root: string, slug: string): string | null {
+  if (slug.trim().length === 0) return null;
+  const dir = join(root, HISTORY_DIR);
+  const candidate = join(dir, `${slug}${LOG_EXT}`);
+  const rel = relative(dir, candidate);
+  if (rel.startsWith("..") || isAbsolute(rel)) return null;
+  return candidate;
+}
+
+function folderPath(root: string, folder: string): string | null {
+  const parts = folder.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) return null;
+  return join(root, HISTORY_DIR, ...parts);
+}
+
+// --- settings ----------------------------------------------------------------
+
+async function readManifest(root: string): Promise<Record<string, unknown> | null> {
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(join(root, OKF_MANIFEST), "utf8"));
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether revisions are being recorded. On unless `okf.json` says `"history": false`. */
+export async function historyEnabled(root: string): Promise<boolean> {
+  return (await readManifest(root))?.["history"] !== false;
+}
+
+/** Turn recording on or off, keeping every other manifest field. */
+export async function setHistoryEnabled(root: string, enabled: boolean): Promise<void> {
+  const manifest = (await readManifest(root)) ?? { okfVersion: 1, scope: "vault" };
+  manifest["history"] = enabled;
+  await fs.mkdir(root, { recursive: true });
+  await fs.writeFile(join(root, OKF_MANIFEST), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+
+// --- the log -------------------------------------------------------------------
+
+function isEntry(value: unknown): value is LogEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  if (typeof entry["at"] !== "string") return false;
+  if (!HISTORY_AUTHORS.includes(entry["by"] as HistoryAuthor)) return false;
+  if (!HISTORY_OPS.includes(entry["op"] as HistoryOp)) return false;
+  if (typeof entry["full"] === "string") return true;
+  const keep = entry["keep"];
+  return (
+    Array.isArray(keep) &&
+    keep.length === 2 &&
+    keep.every((n) => Number.isInteger(n) && (n as number) >= 0) &&
+    typeof entry["text"] === "string"
+  );
+}
+
+/**
+ * Replay a log into revisions. A line that is not JSON, or a delta that does
+ * not fit the body before it, is skipped, and so is every delta after it up
+ * to the next full copy: guessing would show the user text nobody wrote.
+ *
+ * With `lastOnly`, only the newest revision is kept. Recording a write needs
+ * nothing else, and keeping every body would cost the sum of all of them.
+ */
+function replay(text: string, lastOnly = false): NoteRevision[] {
+  const revisions: NoteRevision[] = [];
+  let body: string | null = null;
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      body = null;
+      continue;
+    }
+    if (!isEntry(entry)) {
+      body = null;
+      continue;
+    }
+    if (entry.full !== undefined) {
+      body = entry.full;
+    } else if (body !== null) {
+      const [head, tail] = entry.keep as [number, number];
+      if (head + tail > body.length) {
+        body = null;
+        continue;
+      }
+      body = body.slice(0, head) + (entry.text as string) + body.slice(body.length - tail);
+    } else {
+      continue;
+    }
+    if (lastOnly) revisions.length = 0;
+    revisions.push({ at: entry.at, by: entry.by, op: entry.op, body });
+  }
+  return revisions;
+}
+
+async function readLog(path: string, lastOnly = false): Promise<{ revisions: NoteRevision[]; lines: number }> {
+  let text: string;
+  try {
+    text = await fs.readFile(path, "utf8");
+  } catch {
+    return { revisions: [], lines: 0 };
+  }
+  return { revisions: replay(text, lastOnly), lines: text.split("\n").filter((line) => line.trim() !== "").length };
+}
+
+/** The smallest prefix/suffix-preserving edit that turns `from` into `to`. */
+export function diffBodies(from: string, to: string): { keep: [number, number]; text: string } {
+  const max = Math.min(from.length, to.length);
+  let head = 0;
+  while (head < max && from.charCodeAt(head) === to.charCodeAt(head)) head++;
+  let tail = 0;
+  while (tail < max - head && from.charCodeAt(from.length - 1 - tail) === to.charCodeAt(to.length - 1 - tail)) tail++;
+  return { keep: [head, tail], text: to.slice(head, to.length - tail) };
+}
+
+function entryFor(
+  meta: { at: string; by: HistoryAuthor; op: HistoryOp },
+  previous: string | null,
+  body: string,
+  index: number,
+): LogEntry {
+  if (previous === null || index % KEYFRAME_EVERY === 0) return { ...meta, full: body };
+  return { ...meta, ...diffBodies(previous, body) };
+}
+
+/** Times never run backwards in a log, even when a clock or mtime does. */
+function notBefore(at: string, last: NoteRevision | undefined): string {
+  return last !== undefined && at < last.at ? last.at : at;
+}
+
+async function appendEntries(
+  path: string,
+  log: { revisions: NoteRevision[]; lines: number },
+  pending: Array<{ at: string; by: HistoryAuthor; op: HistoryOp; body: string }>,
+): Promise<void> {
+  if (pending.length === 0) return;
+  let previous = log.revisions.at(-1)?.body ?? null;
+  let index = log.lines;
+  const lines: string[] = [];
+  for (const { body, ...meta } of pending) {
+    lines.push(JSON.stringify(entryFor(meta, previous, body, index)));
+    previous = body;
+    index++;
+  }
+  await fs.mkdir(dirname(path), { recursive: true });
+  await fs.appendFile(path, lines.join("\n") + "\n", "utf8");
+  if (index > MAX_REVISIONS || (await fs.stat(path)).size > MAX_LOG_BYTES) await compact(path);
+}
+
+/**
+ * Encode revisions as log lines: a full copy first, deltas after, a full
+ * copy every {@link KEYFRAME_EVERY}. The viewer receives the same shape, so
+ * the download is about as small as the file.
+ */
+export function encodeRevisions(revisions: readonly NoteRevision[], trimmed = false): LogEntry[] {
+  let previous: string | null = null;
+  return revisions.map(({ body, ...meta }, index) => {
+    const entry = entryFor(meta, previous, body, index);
+    previous = body;
+    return index === 0 && trimmed ? { ...entry, trimmed: true } : entry;
+  });
+}
+
+/** Whether a log's oldest revisions were dropped by compaction. */
+function isTrimmed(text: string): boolean {
+  const first = text.slice(0, text.indexOf("\n") + 1 || text.length);
+  try {
+    return (JSON.parse(first) as { trimmed?: unknown }).trimmed === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Drop the oldest revisions until the log fits {@link COMPACT_TO} of both limits. */
+async function compact(path: string): Promise<void> {
+  const revisions = replay(await fs.readFile(path, "utf8"));
+  const maxBytes = MAX_LOG_BYTES * COMPACT_TO;
+  let keep = Math.min(revisions.length, Math.floor(MAX_REVISIONS * COMPACT_TO));
+  let text = "";
+  for (;;) {
+    text = encodeRevisions(revisions.slice(-keep), true).map((entry) => JSON.stringify(entry)).join("\n") + "\n";
+    if (keep === 1 || Buffer.byteLength(text, "utf8") <= maxBytes) break;
+    keep = Math.max(1, Math.floor(keep * 0.75));
+  }
+  // A temporary file and a rename: a crash mid-write leaves the old log, not half a new one.
+  const temp = `${path}.compact`;
+  await fs.writeFile(temp, text, "utf8");
+  await fs.rename(temp, path);
+}
+
+/** Whether a note's history has had its oldest revisions dropped. */
+export async function historyTrimmed(root: string, slug: string): Promise<boolean> {
+  const path = historyPath(root, slug);
+  if (path === null) return false;
+  try {
+    return isTrimmed(await fs.readFile(path, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Record one write. Called by `vault.ts` while it holds the vault lock, after
+ * the note file has been written. A failure here never fails the write that
+ * caused it: losing a revision is better than losing the user's edit.
+ */
+export async function recordRevision(root: string, slug: string, input: RecordInput): Promise<void> {
+  try {
+    const path = historyPath(root, slug);
+    if (path === null || !(await historyEnabled(root))) return;
+    const log = await readLog(path, true);
+    const pending: Array<{ at: string; by: HistoryAuthor; op: HistoryOp; body: string }> = [];
+    let last = log.revisions.at(-1);
+    if (input.before !== null && last?.body !== input.before.body) {
+      const op: HistoryOp = last === undefined ? "baseline" : "outside";
+      const outside = { at: notBefore(input.before.at, last), by: "outside" as const, op, body: input.before.body };
+      pending.push(outside);
+      last = outside;
+    }
+    if (last?.body !== input.after) {
+      pending.push({ at: notBefore(input.at.toISOString(), last), by: input.by, op: input.op, body: input.after });
+    }
+    await appendEntries(path, log, pending);
+  } catch {
+    // Deliberately silent; see the doc comment.
+  }
+}
+
+/**
+ * Every revision of a note, oldest first. When `current` is given and differs
+ * from the last revision, the difference was made outside pi-weave; it is
+ * recorded (if history is on) and returned as the final revision either way,
+ * so the slider always ends on what the note says now.
+ */
+export async function readHistory(root: string, slug: string, current?: PriorBody): Promise<NoteRevision[]> {
+  const path = historyPath(root, slug);
+  if (path === null) return [];
+  const log = await readLog(path);
+  const last = log.revisions.at(-1);
+  if (current === undefined || last?.body === current.body) return log.revisions;
+  const outside: NoteRevision = {
+    at: notBefore(current.at, last),
+    by: "outside",
+    op: last === undefined ? "baseline" : "outside",
+    body: current.body,
+  };
+  if (await historyEnabled(root)) {
+    try {
+      await appendEntries(path, log, [outside]);
+    } catch {
+      // Still shown; recording is best effort.
+    }
+  }
+  return [...log.revisions, outside];
+}
+
+async function move(from: string | null, to: string | null): Promise<void> {
+  if (from === null || to === null || from === to) return;
+  try {
+    await fs.mkdir(dirname(to), { recursive: true });
+    await fs.rename(from, to);
+  } catch {
+    // No log yet, or nothing to move.
+  }
+}
+
+/** Carry a note's log to its new slug after a rename or move. */
+export async function moveHistory(root: string, from: string, to: string): Promise<void> {
+  await move(historyPath(root, from), historyPath(root, to));
+}
+
+/** Carry a folder's logs along when the folder is renamed. */
+export async function moveHistoryFolder(root: string, from: string, to: string): Promise<void> {
+  await move(folderPath(root, from), folderPath(root, to));
+}
+
+/** Drop a deleted note's log, so a new note with the same name starts clean. */
+export async function removeHistory(root: string, slug: string): Promise<void> {
+  const path = historyPath(root, slug);
+  if (path !== null) await fs.rm(path, { force: true });
+}
+
+/** Drop the logs of every note in a deleted folder. */
+export async function removeHistoryFolder(root: string, folder: string): Promise<void> {
+  const path = folderPath(root, folder);
+  if (path !== null) await fs.rm(path, { recursive: true, force: true });
+}

package/src/core/index.ts

@@ -9,6 +9,7 @@ export { findGitRoot } from "./git";
 export {
   assessStaleness,
   buildRepoIndex,
+  ensureRepoIndex,
   readRepoIndex,
   summarizeIndex,
   writeRepoIndex,
@@ -92,6 +93,14 @@ export {
   type LinkFix,
   type UnresolvableLink,
 } from "./links/repair";
+export {
+  historyEnabled,
+  readHistory,
+  setHistoryEnabled,
+  type HistoryAuthor,
+  type HistoryOp,
+  type NoteRevision,
+} from "./history";
 export type { HtmlArtifact } from "./types";
 export { withMutationQueue } from "./mutex";
 export { formatDashboard, formatStatusLine, getWorkspaceStatus } from "./workspace";
@@ -102,6 +111,16 @@ export {
   type NoteActionInput,
   type NoteActionResult,
 } from "./noteAction";
+export {
+  RecallTrail,
+  recallTrail,
+  TRAIL_CAPACITY,
+  TURN_GAP_MS,
+  type TrailEntry,
+  type TrailEvent,
+  type TrailKind,
+  type TrailSnapshot,
+} from "./trail";
 export {
   executeRepoAction,
   WEAVE_REPO_DESCRIPTION,

package/src/core/links/repair.ts

@@ -42,15 +42,14 @@
 
 import { slugify } from "../slug";
 import type { HtmlArtifact, Note } from "../types";
+import { fenceRanges, rawTailStart } from "../view/rawTail";
 
 /**
- * The append-only tail heading.
- *
- * Defined here rather than in `vault.ts` (which re-exports it, so its public
- * API is unchanged) because repair is the module that must *not* cross it,
- * and vault imports repair. One definition, no cycle.
+ * The tail helpers live in `../view/rawTail`, a node-free module the browser
+ * editor can reach through `src/web/shared/view.ts`. Re-exported here so
+ * repair's public surface is unchanged.
  */
-export const RAW_NOTES_HEADING = "## Raw";
+export { RAW_NOTES_HEADING, fenceRanges, rawTailStart } from "../view/rawTail";
 
 /** One `[[wiki-link]]` found in a body, with enough context to rewrite it. */
 export interface LinkOccurrence {
@@ -85,68 +84,6 @@ export function normalizeTarget(raw: string): string {
 }
 
 const WIKILINK_RE = /\[\[([^\][|]+)(?:\|([^\]]*))?\]\]/g;
-const FENCE_RE = /^[ \t]*(`{3,}|~{3,})(.*)$/gm;
-/** A `## Raw` heading on a line of its own — not `## Rawhide`. */
-const RAW_HEADING_RE = new RegExp(`^${RAW_NOTES_HEADING}[ \\t]*\\r?$`, "m");
-
-/**
- * Half-open `[start, end)` ranges covering fenced code blocks.
- *
- * CommonMark, not "every third-backtick-line toggles": a fence is closed only
- * by the **same marker character**, at **at least the opening length**, and
- * with no info string. Treating fences as a blind alternation gets two cases
- * backwards — a `~~~` nested inside a ``` block would close it, and a ```
- * inside a ```` block would too — and each mistake ends the protected region
- * early, exposing example links in documentation to rewriting.
- */
-export function fenceRanges(body: string): [number, number][] {
-  const ranges: [number, number][] = [];
-  let open: { at: number; marker: string; length: number } | null = null;
-  for (const match of body.matchAll(FENCE_RE)) {
-    const run = match[1]!;
-    // Group 2 is `(.*)`, which always participates: the info string.
-    const info = match[2]!;
-    if (open === null) {
-      open = { at: match.index, marker: run[0]!, length: run.length };
-    } else if (run[0] === open.marker && run.length >= open.length && info.trim() === "") {
-      ranges.push([open.at, match.index + match[0].length]);
-      open = null;
-    }
-  }
-  // An unterminated fence runs to the end of the body, the way a renderer
-  // treats it.
-  if (open !== null) ranges.push([open.at, body.length]);
-  return ranges;
-}
-
-/**
- * The byte offset where the `## Raw` tail begins, or the body length when
- * there is none.
- *
- * The tail is append-only and verbatim — "NEVER edit below this line" is
- * written into every note that has one. A link inside a user's dictation is
- * *their* text, quoted; repairing it would edit words the vault promises not
- * to touch.
- *
- * Fence-aware, and for the opposite reason to everything else here: a note
- * *documenting* the raw-tail convention contains `## Raw` inside a code
- * sample, and treating that as the real tail would silently protect — and so
- * refuse to repair — every link below it. Matching a whole heading line also
- * keeps `## Rawhide` from starting a tail.
- */
-export function rawTailStart(body: string, fences: readonly [number, number][]): number {
-  let from = 0;
-  for (;;) {
-    const rest = body.slice(from);
-    const hit = RAW_HEADING_RE.exec(rest);
-    if (hit === null) return body.length;
-    const at = from + hit.index;
-    const fence = fences.find(([a, b]) => at >= a && at < b);
-    if (fence === undefined) return at;
-    from = fence[1]; // skip the whole fenced block and keep looking
-  }
-}
-
 /**
  * Every repairable `[[wiki-link]]` in a body, in order.
  *

package/src/core/noteAction.ts

@@ -16,12 +16,13 @@ import {
 import { relatedNotes, suggestLinks, type RelatedNote, type SuggestionReport } from "./links/similar";
 import { NOTES_DIR, resolveVaultRoot } from "./paths";
 import { withMutationQueue } from "./mutex";
+import { recallTrail, type RecallTrail, type TrailEntry } from "./trail";
 import type { Note, NoteSearchHit } from "./types";
 
 export const WEAVE_NOTE_DESCRIPTION =
   "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
   "of Markdown notes. Actions: list (all notes — avoid on large vaults, prefer search), get (one note by slug), add (new note), " +
-  "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail), " +
+  "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail; add with raw=true starts the note there), " +
   "finalize (restructure a note above its raw tail), search (ranked slug/title/tags/body matches plus linked, tagged, and lexically related notes; returns the full note when one result or one exact identity resolves), " +
   "links (audit stale [[wiki-links]]; fix=true repairs the unambiguous ones), " +
   "suggest (rank unlinked notes that share distinctive vocabulary; reports only, never writes). " +
@@ -186,10 +187,71 @@ function formatLinkReport(result: LinkRepairResult, applied: boolean): string {
   return lines.join("\n");
 }
 
+/**
+ * Run one `weave_note` action and record what it touched on the recall trail
+ * (`./trail.ts`). Recording never fails the action: the trail is presentation,
+ * and a tool call must not break because a viewer would have liked to know.
+ */
 export async function executeNoteAction(
   params: NoteActionInput,
   vault = resolveVaultRoot(),
   now: () => Date = () => new Date(),
+  trail: RecallTrail | null = recallTrail,
+): Promise<NoteActionResult> {
+  const result = await runNoteAction(params, vault, now);
+  if (trail !== null) {
+    const at = now();
+    for (const step of trailSteps(params, result)) trail.record({ ...step, vault, at });
+  }
+  return result;
+}
+
+type TrailStep = Omit<TrailEntry, "vault" | "at">;
+
+function slugOf(value: unknown): string | null {
+  return typeof value === "object" && value !== null && typeof (value as { slug?: unknown }).slug === "string"
+    ? (value as { slug: string }).slug
+    : null;
+}
+
+/** What an action's result says it touched. List and suggest touch nothing worth showing. */
+export function trailSteps(params: NoteActionInput, result: NoteActionResult): TrailStep[] {
+  const { details } = result;
+  switch (params.action) {
+    case "get": {
+      const slug = slugOf(details.note);
+      return slug === null ? [] : [{ kind: "read", action: "get", slugs: [slug] }];
+    }
+    case "search": {
+      const hits = Array.isArray(details.hits) ? details.hits : [];
+      const slugs = hits.flatMap((hit: unknown) => {
+        const slug = slugOf((hit as { summary?: unknown }).summary);
+        return slug === null ? [] : [slug];
+      });
+      const steps: TrailStep[] = [{ kind: "searched", action: "search", slugs, query: params.query }];
+      const resolved = slugOf(details.resolved);
+      if (resolved !== null) steps.push({ kind: "read", action: "search", slugs: [resolved] });
+      return steps;
+    }
+    case "add":
+    case "append":
+    case "finalize": {
+      const slug = slugOf(details.note);
+      return slug === null ? [] : [{ kind: "wrote", action: params.action, slugs: [slug] }];
+    }
+    case "links": {
+      const notes = Array.isArray(details.notes) ? details.notes.filter((slug): slug is string => typeof slug === "string") : [];
+      return notes.length === 0 ? [] : [{ kind: "wrote", action: "links", slugs: notes }];
+    }
+    default:
+      return [];
+  }
+}
+
+async function runNoteAction(
+  params: NoteActionInput,
+  vault: string,
+  now: () => Date,
 ): Promise<NoteActionResult> {
   switch (params.action) {
     case "list": {
@@ -222,9 +284,17 @@ export async function executeNoteAction(
           body: params.text!,
           ...(params.tags ? { tags: params.tags } : {}),
           ...(params.source ? { source: params.source } : {}),
+          ...(params.raw ? { raw: true, now: now() } : {}),
+          // The agent wrote the file even when the words are the user's.
+          by: "agent",
         }),
       );
-      return { text: `Note created: ${note.slug} (${vault})`, details: { action: "add", note } };
+      return {
+        text: params.raw
+          ? `Note created: ${note.slug} (${vault}), text preserved verbatim in its ## Raw tail.`
+          : `Note created: ${note.slug} (${vault})`,
+        details: { action: "add", note },
+      };
     }
 
     case "append": {

package/src/core/openInEditor.ts

@@ -1,14 +1,9 @@
 /**
  * Open a vault note in the user's editor.
  *
- * Originally `src/pi/viewer/tui/openNote.ts`, promoted into core because the
- * browser workspace needs it too and `src/web/server/**` may not import
- * `src/pi` (weave-workspace §2). It belongs here on the merits regardless:
- * it is a pure fan-out over `core/vault` plus one `execFile`, with no
- * harness and no terminal concept in it, and the same reasoning that put
- * `readNoteForView` in core applies unchanged.
- *
- * The old path re-exports these two names, so no TUI file changed.
+ * Lives in core because the browser workspace's server uses it and
+ * `src/web/server/**` may not import `src/pi`. It is a pure fan-out over
+ * `core/vault` plus one `execFile`, with no harness in it.
  *
  * Security: the slug is validated against the vault (traversal-safe) before
  * any shell-out, and the command is invoked with `execFile`, not a shell, so