@jpcasabiancai/cayenne 0.3.3 → 0.3.4

package/dist/cli.js

@@ -632,6 +632,48 @@ var init_content = __esm({
   }
 });
 
+// ../../packages/shared/src/protocol/documents.ts
+function documentFilename(relPath) {
+  const leaf = relPath.split(/[/\\]/).at(-1) ?? "";
+  const folded = leaf.replace(OUTSIDE_CLASS, "-");
+  const prefixed = /^[A-Za-z0-9]/.test(folded) ? folded : `d-${folded}`;
+  return prefixed.replace(DASH_RUN, "-").slice(0, MAX_FILENAME);
+}
+function documentKindFor(filename) {
+  const dot = filename.lastIndexOf(".");
+  const ext = dot === -1 ? "" : filename.slice(dot + 1).toLowerCase();
+  return KIND_BY_EXTENSION.get(ext) ?? "file";
+}
+function documentPath(workspaceId, documentId, filename) {
+  const path = `${workspaceId.toLowerCase()}/${documentId.toLowerCase()}/${filename}`;
+  if (!DOCUMENT_NAME.test(path)) {
+    throw new Error(`VALIDATION: not a valid document name: ${path}`);
+  }
+  return path;
+}
+var DOCUMENTS_BUCKET, DOCUMENT_MAX_BYTES, DOCUMENT_TITLE_MAX, DOCUMENTS_DIR, DOCUMENTS_MAX_FILES, DOCUMENT_REL_PATH_MAX, DOCUMENT_NAME, KIND_BY_EXTENSION, MAX_FILENAME, OUTSIDE_CLASS, DASH_RUN;
+var init_documents = __esm({
+  "../../packages/shared/src/protocol/documents.ts"() {
+    "use strict";
+    DOCUMENTS_BUCKET = "documents";
+    DOCUMENT_MAX_BYTES = 2 * 1024 * 1024;
+    DOCUMENT_TITLE_MAX = 200;
+    DOCUMENTS_DIR = ".cayenne/docs";
+    DOCUMENTS_MAX_FILES = 200;
+    DOCUMENT_REL_PATH_MAX = 1024;
+    DOCUMENT_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+    KIND_BY_EXTENSION = /* @__PURE__ */ new Map([
+      ["md", "markdown"],
+      ["markdown", "markdown"],
+      ["html", "html"],
+      ["htm", "html"]
+    ]);
+    MAX_FILENAME = 200;
+    OUTSIDE_CLASS = /[^A-Za-z0-9._-]/g;
+    DASH_RUN = /-{2,}/g;
+  }
+});
+
 // ../../packages/shared/src/protocol/events.ts
 import { z as z7 } from "zod";
 var SessionStatus, SessionEvent, SESSION_EVENT_NAME, sessionTopic, runnerTopic, terminalTopic;
@@ -816,6 +858,13 @@ var init_runner = __esm({
        * older runner will never handle. Absent reads as false; optional so an older row parses.
        */
       skills: z9.boolean().optional(),
+      /**
+       * Whether this runner mirrors `.cayenne/docs` into `public.documents` (D40, protocol §9). No kind
+       * carries documents, so the flag is the only signal: the tab says "this runner does not publish
+       * documents" instead of "nothing written yet". Absent reads as false; optional so an older row
+       * parses.
+       */
+      documents: z9.boolean().optional(),
       /**
        * The raw Ed25519 public key of the running process (32 bytes, unpadded base64url), which signs
        * the local server's `hello` (protocol §6.2). New on every start, republished by every capabilities refresh that changes the row;
@@ -861,6 +910,7 @@ var init_protocol = __esm({
     init_attachments();
     init_command();
     init_content();
+    init_documents();
     init_events();
     init_git();
     init_github();
@@ -3445,7 +3495,7 @@ function createTokenVerifier({
   ttlMs = LOCAL_TOKEN_CACHE_MS,
   negativeTtlMs = LOCAL_TOKEN_NEGATIVE_CACHE_MS,
   now = Date.now,
-  admit = () => true,
+  admit: admit2 = () => true,
   log
 }) {
   const cache = new LRUCache2({ max: 1024 });
@@ -3489,7 +3539,7 @@ function createTokenVerifier({
       }
       cache.delete(k);
       const claims = claimsOf(token);
-      if (!claims || claims.exp * 1e3 <= now() || !admit(claims.sub)) return refuse3(k);
+      if (!claims || claims.exp * 1e3 <= now() || !admit2(claims.sub)) return refuse3(k);
       if (!budgeted()) return { status: "unavailable" };
       const user = await db.auth.getUser(token).then(
         (r) => r.error ? retryable(r.error) ? void 0 : null : r.data.user,
@@ -4651,6 +4701,522 @@ var init_handlers = __esm({
   }
 });
 
+// src/documents/paths.ts
+import { realpathSync as realpathSync8 } from "fs";
+import { isAbsolute as isAbsolute10, join as join16, relative as relative4, sep as sep5 } from "path";
+function contained(dir, candidate) {
+  const rel = relative4(dir, candidate);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep5}`) && !isAbsolute10(rel);
+}
+function resolveDocsDir(cwd, log) {
+  const dir = docsDir(cwd);
+  let real;
+  try {
+    real = realpathSync8.native(dir);
+  } catch {
+    return null;
+  }
+  if (!contained(cwd, real)) {
+    log.warn(
+      { dir, resolved: real, cwd },
+      "documents directory skipped: it resolves outside the session working directory"
+    );
+    return null;
+  }
+  return real;
+}
+function assertInsideDocsDir(dir, candidate) {
+  let real;
+  try {
+    real = realpathSync8.native(candidate);
+  } catch {
+    throw new Error(`ROOT_NOT_ALLOWED: ${candidate} cannot be resolved`);
+  }
+  if (!contained(dir, real)) throw new Error(`ROOT_NOT_ALLOWED: ${candidate}`);
+  return real;
+}
+var docsDir;
+var init_paths2 = __esm({
+  "src/documents/paths.ts"() {
+    "use strict";
+    init_src();
+    docsDir = (cwd) => join16(cwd, ...DOCUMENTS_DIR.split("/"));
+  }
+});
+
+// src/documents/mirror.ts
+async function syncDocuments(deps, pass) {
+  const log = deps.log ?? logger;
+  const { db } = deps;
+  const result = { inserted: 0, updated: 0, missing: 0 };
+  let known = null;
+  try {
+    const { data, error } = await db.from("documents").select(SELECT).eq("session_id", deps.sessionId).eq("owner_id", deps.ownerId).limit(DOCUMENTS_MIRROR_MAX_ROWS);
+    if (error) throw new Error(error.message);
+    known = data ?? [];
+  } catch (err) {
+    log.warn(
+      { err: said(err), sessionId: deps.sessionId },
+      "could not read this session\u2019s document rows; writing nothing and reconciling nothing"
+    );
+    return result;
+  }
+  const byPath = /* @__PURE__ */ new Map();
+  for (const row of known) if (row.rel_path !== null) byPath.set(row.rel_path, row);
+  const upload = async (path, doc) => {
+    try {
+      const { error } = await db.storage.from(DOCUMENTS_BUCKET).upload(path, doc.bytes, { contentType: contentTypeFor(doc), upsert: true });
+      return error ? error.message : null;
+    } catch (err) {
+      return said(err);
+    }
+  };
+  const publish2 = async (row, doc) => {
+    let expected;
+    try {
+      expected = documentPath(deps.workspaceId, row.id, doc.filename);
+    } catch (err) {
+      return said(err);
+    }
+    if (row.storage_path !== expected) {
+      return `storage_path ${String(row.storage_path)} is not ${expected}`;
+    }
+    return upload(expected, doc);
+  };
+  const takeBack = async (id, relPath) => {
+    const { error } = await db.from("documents").delete().eq("id", id);
+    if (error) {
+      log.warn(
+        { err: error.message, id, relPath, sessionId: deps.sessionId },
+        "could not remove a document row that has no object"
+      );
+    }
+  };
+  for (const doc of pass.write) {
+    const before = byPath.get(doc.relPath);
+    try {
+      if (before === void 0) {
+        const { data, error: error2 } = await db.from("documents").insert(rowOf(deps, doc)).select("id, storage_path").single();
+        if (error2) throw new Error(error2.message);
+        const row = data;
+        if (!row?.id) throw new Error("the insert returned no row");
+        const failed3 = await publish2(row, doc);
+        if (failed3 !== null) {
+          log.warn(
+            { err: failed3, relPath: doc.relPath, sessionId: deps.sessionId },
+            "could not upload a document; removing the row so the next pass retries it"
+          );
+          await takeBack(row.id, doc.relPath);
+          continue;
+        }
+        result.inserted += 1;
+        continue;
+      }
+      const rewritten = before.content_hash !== doc.contentHash;
+      const restated = before.status !== "present" || before.title !== doc.title || before.kind !== doc.kind || before.size_bytes !== doc.size;
+      if (!rewritten && !restated) continue;
+      if (rewritten) {
+        const failed3 = await upload(before.storage_path, doc);
+        if (failed3 !== null) {
+          log.warn(
+            { err: failed3, relPath: doc.relPath, sessionId: deps.sessionId },
+            "could not overwrite a document; its row still describes the bytes in the bucket"
+          );
+          continue;
+        }
+      }
+      const { error } = await db.from("documents").update(patchOf(doc)).eq("id", before.id);
+      if (error) throw new Error(error.message);
+      result.updated += 1;
+    } catch (err) {
+      log.warn(
+        { err: said(err), relPath: doc.relPath, sessionId: deps.sessionId },
+        "could not mirror a document"
+      );
+    }
+  }
+  if (!pass.reconcile) return result;
+  const gone2 = known.filter((r) => r.rel_path !== null && r.status === "present" && !pass.present.has(r.rel_path)).map((r) => r.id);
+  if (gone2.length > 0) {
+    try {
+      const { error } = await db.from("documents").update({ status: "missing" }).in("id", gone2);
+      if (error) throw new Error(error.message);
+      result.missing = gone2.length;
+    } catch (err) {
+      log.warn(
+        { err: said(err), count: gone2.length, sessionId: deps.sessionId },
+        "could not mark vanished documents missing"
+      );
+    }
+  }
+  return result;
+}
+var DOCUMENTS_MIRROR_MAX_ROWS, SELECT, contentTypeFor, rowOf, patchOf, said;
+var init_mirror = __esm({
+  "src/documents/mirror.ts"() {
+    "use strict";
+    init_src();
+    init_log();
+    DOCUMENTS_MIRROR_MAX_ROWS = 1e3;
+    SELECT = "id, rel_path, storage_path, filename, kind, title, content_hash, size_bytes, status";
+    contentTypeFor = (doc) => doc.kind === "file" ? "application/octet-stream" : "text/plain";
+    rowOf = (deps, doc) => ({
+      // Stamped from the session by `stamp_document_insert`; `documents_insert` still checks
+      // `is_member(workspace_id)` against a non-null value, so it is sent.
+      workspace_id: deps.workspaceId,
+      owner_id: deps.ownerId,
+      session_id: deps.sessionId,
+      rel_path: doc.relPath,
+      filename: doc.filename,
+      kind: doc.kind,
+      title: doc.title,
+      content_hash: doc.contentHash,
+      size_bytes: doc.size,
+      source: "watcher",
+      status: "present"
+    });
+    patchOf = (doc) => ({
+      title: doc.title,
+      kind: doc.kind,
+      content_hash: doc.contentHash,
+      size_bytes: doc.size,
+      status: "present"
+    });
+    said = (err) => err instanceof Error ? err.message : String(err);
+  }
+});
+
+// src/documents/scan.ts
+import { createHash as createHash3 } from "crypto";
+import {
+  closeSync as closeSync2,
+  constants as fsConstants,
+  lstatSync as lstatSync4,
+  opendirSync,
+  openSync as openSync2,
+  readFileSync as readFileSync7
+} from "fs";
+import { open } from "fs/promises";
+import { join as join17 } from "path";
+function isNew(baseline, relPath, contentHash) {
+  const before = baseline.hashes.get(relPath);
+  if (before === void 0) return baseline.complete;
+  if (before === UNREADABLE) return false;
+  return before !== contentHash;
+}
+function readCapped(dir, st) {
+  const handle = opendirSync(dir);
+  const entries = [];
+  try {
+    for (; ; ) {
+      const entry = handle.readSync();
+      if (entry === null) break;
+      if (entries.length === DOCS_SCAN_MAX_ENTRIES) {
+        st.log.warn(
+          { dir, cap: DOCS_SCAN_MAX_ENTRIES },
+          `documents skipped: more than ${DOCS_SCAN_MAX_ENTRIES} entries in one directory`
+        );
+        st.complete = false;
+        break;
+      }
+      entries.push(entry);
+    }
+  } finally {
+    try {
+      handle.closeSync();
+    } catch {
+    }
+  }
+  return entries.sort((a, b) => a.name < b.name ? -1 : 1);
+}
+function admit(st, path, relPath) {
+  const skip = (reason) => {
+    st.log.warn({ path, relPath }, `document skipped: ${reason}`);
+  };
+  if (relPath.length > DOCUMENT_REL_PATH_MAX) {
+    skip(`its path is over ${DOCUMENT_REL_PATH_MAX} characters`);
+    return;
+  }
+  if (st.files.length >= DOCUMENTS_MAX_FILES) {
+    st.log.warn(
+      { dir: st.root, cap: DOCUMENTS_MAX_FILES },
+      `documents skipped: this session's directory holds more than ${DOCUMENTS_MAX_FILES} files`
+    );
+    st.complete = false;
+    st.stop = true;
+    return;
+  }
+  let real;
+  try {
+    real = assertInsideDocsDir(st.root, path);
+  } catch (err) {
+    skip(err instanceof Error ? err.message : String(err));
+    return;
+  }
+  let stat;
+  try {
+    stat = lstatSync4(real);
+  } catch {
+    skip("it cannot be read");
+    return;
+  }
+  if (!stat.isFile()) return;
+  if (stat.size > DOCUMENT_MAX_BYTES) {
+    skip(`it is over ${DOCUMENT_MAX_BYTES} bytes`);
+    return;
+  }
+  st.files.push({ relPath, path: real, size: stat.size });
+}
+function docFiles(root, log) {
+  const st = { root, files: [], complete: true, stop: false, log };
+  walk2(st, root, "", 0);
+  return st;
+}
+function walk2(st, dir, rel, depth) {
+  if (st.stop) return;
+  let entries;
+  try {
+    entries = readCapped(dir, st);
+  } catch {
+    st.complete = false;
+    return;
+  }
+  for (const entry of entries) {
+    if (st.stop) return;
+    if (entry.name.startsWith(".")) continue;
+    const path = join17(dir, entry.name);
+    const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+    if (entry.isSymbolicLink()) {
+      st.log.warn({ path, relPath }, `document skipped: ${SYMLINK_SKIPPED}`);
+      continue;
+    }
+    if (entry.isDirectory()) {
+      if (depth + 1 < DOCS_MAX_DEPTH) walk2(st, path, relPath, depth + 1);
+      continue;
+    }
+    if (entry.isFile()) admit(st, path, relPath);
+  }
+}
+async function readAtMost(fh, limit) {
+  const buffer = Buffer.allocUnsafe(limit);
+  let filled = 0;
+  while (filled < limit) {
+    const { bytesRead } = await fh.read(buffer, filled, limit - filled, filled);
+    if (bytesRead === 0) break;
+    filled += bytesRead;
+  }
+  return buffer.subarray(0, filled);
+}
+function documentTitle(text, kind, relPath) {
+  const head = text.slice(0, TITLE_SEARCH_MAX);
+  let raw = "";
+  if (kind === "markdown") raw = ATX.exec(head)?.[2] ?? "";
+  else if (kind === "html") raw = HTML_TITLE.exec(head)?.[1] ?? "";
+  const leaf = relPath.split("/").at(-1) ?? "";
+  return clean(raw) || clean(leaf) || "document";
+}
+async function openProved(real) {
+  return open(real, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+}
+async function readDocument(file, root, log) {
+  const skip = (reason) => {
+    log.warn({ path: file.path, relPath: file.relPath }, `document skipped: ${reason}`);
+    return null;
+  };
+  let real;
+  try {
+    real = assertInsideDocsDir(root, file.path);
+  } catch (err) {
+    return skip(err instanceof Error ? err.message : String(err));
+  }
+  if (real !== file.path) return skip(SYMLINK_SKIPPED);
+  let fh;
+  try {
+    fh = await openProved(real);
+  } catch {
+    return skip("it is no longer a readable file");
+  }
+  let bytes;
+  try {
+    const stat = await fh.stat();
+    if (!stat.isFile()) return skip("it is no longer a file");
+    if (stat.size > DOCUMENT_MAX_BYTES) return skip(`it is over ${DOCUMENT_MAX_BYTES} bytes`);
+    bytes = await readAtMost(fh, DOCUMENT_MAX_BYTES + 1);
+  } finally {
+    await fh.close().catch(() => void 0);
+  }
+  if (bytes.byteLength > DOCUMENT_MAX_BYTES) return skip(`it is over ${DOCUMENT_MAX_BYTES} bytes`);
+  const filename = documentFilename(file.relPath);
+  const kind = documentKindFor(filename);
+  return {
+    relPath: file.relPath,
+    path: real,
+    filename,
+    kind,
+    title: documentTitle(bytes.subarray(0, TITLE_SEARCH_MAX).toString("utf8"), kind, file.relPath),
+    contentHash: sha256(bytes),
+    size: bytes.byteLength,
+    bytes
+  };
+}
+async function scanDocuments(root, log) {
+  const walked = docFiles(root, log);
+  const documents = [];
+  const present = /* @__PURE__ */ new Set();
+  let complete = walked.complete;
+  let budget = DOCS_SCAN_MAX_BYTES;
+  for (const file of walked.files) {
+    if (budget <= 0) {
+      log.warn(
+        { dir: root, cap: DOCS_SCAN_MAX_BYTES },
+        "documents skipped: this pass reached its read budget"
+      );
+      complete = false;
+      break;
+    }
+    budget -= file.size;
+    const doc = await readDocument(file, root, log);
+    if (doc === null) continue;
+    documents.push(doc);
+    present.add(doc.relPath);
+  }
+  return { documents, present, complete };
+}
+function baselineOf(root, log) {
+  const hashes = /* @__PURE__ */ new Map();
+  if (root === null) return { hashes, complete: true };
+  const walked = docFiles(root, log);
+  for (const file of walked.files) {
+    let fd;
+    try {
+      fd = openSync2(file.path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    } catch {
+      hashes.set(file.relPath, UNREADABLE);
+      continue;
+    }
+    try {
+      hashes.set(file.relPath, sha256(readFileSync7(fd)));
+    } catch {
+      hashes.set(file.relPath, UNREADABLE);
+    } finally {
+      try {
+        closeSync2(fd);
+      } catch {
+      }
+    }
+  }
+  return { hashes, complete: walked.complete };
+}
+var DOCS_MAX_DEPTH, DOCS_SCAN_MAX_ENTRIES, DOCS_SCAN_MAX_BYTES, TITLE_SEARCH_MAX, UNREADABLE, sha256, SYMLINK_SKIPPED, WHITESPACE, ATX, HTML_TITLE, stripControl, firstCodePoints, clean;
+var init_scan = __esm({
+  "src/documents/scan.ts"() {
+    "use strict";
+    init_src();
+    init_paths2();
+    DOCS_MAX_DEPTH = 3;
+    DOCS_SCAN_MAX_ENTRIES = 500;
+    DOCS_SCAN_MAX_BYTES = 32 * 1024 * 1024;
+    TITLE_SEARCH_MAX = 64 * 1024;
+    UNREADABLE = "unreadable";
+    sha256 = (bytes) => createHash3("sha256").update(bytes).digest("hex");
+    SYMLINK_SKIPPED = "a symlink is never followed";
+    WHITESPACE = /\s+/g;
+    ATX = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/m;
+    HTML_TITLE = /<title[^>]*>([\s\S]*?)<\/title>/i;
+    stripControl = (raw) => [...raw].filter((ch) => {
+      const code = ch.codePointAt(0) ?? 0;
+      return code > 31 && (code < 127 || code > 159);
+    }).join("");
+    firstCodePoints = (s, max) => [...s].slice(0, max).join("");
+    clean = (raw) => firstCodePoints(stripControl(raw).replace(WHITESPACE, " ").trim(), DOCUMENT_TITLE_MAX).trim();
+  }
+});
+
+// src/documents/service.ts
+function createDocumentsService(deps) {
+  const log = deps.log ?? logger;
+  const scan = deps.scan ?? scanDocuments;
+  const sync = deps.sync ?? syncDocuments;
+  const mirror = {
+    db: deps.db,
+    workspaceId: deps.workspaceId,
+    ownerId: deps.ownerId,
+    sessionId: deps.sessionId,
+    log
+  };
+  const baseline = baselineOf(resolveDocsDir(deps.cwd, log), log);
+  const owned = /* @__PURE__ */ new Set();
+  let seen = false;
+  let closed = false;
+  let inFlight = null;
+  let dirty = false;
+  const pass = async () => {
+    const dir = resolveDocsDir(deps.cwd, log);
+    if (dir === null) {
+      if (!seen) return;
+      await sync(mirror, { write: [], present: /* @__PURE__ */ new Set(), reconcile: true });
+      return;
+    }
+    seen = true;
+    const { documents, present, complete } = await scan(dir, log);
+    const write = documents.filter(
+      (doc) => owned.has(doc.relPath) || isNew(baseline, doc.relPath, doc.contentHash)
+    );
+    const job = {
+      write,
+      present,
+      // A pass that saw only part of the directory reconciles nothing: the rows it did not see
+      // are not evidence that their files went away.
+      reconcile: complete
+    };
+    const result = await sync(mirror, job);
+    for (const doc of write) owned.add(doc.relPath);
+    if (result.inserted || result.updated || result.missing) {
+      log.info?.({ sessionId: deps.sessionId, ...result }, "documents mirrored for this session");
+    }
+  };
+  const start2 = () => {
+    dirty = false;
+    const started = pass().catch(
+      (err) => log.warn({ err: said2(err), sessionId: deps.sessionId }, "a documents pass failed")
+    ).finally(() => {
+      if (inFlight === started) inFlight = null;
+      if (dirty && !closed) void start2();
+    });
+    inFlight = started;
+    return started;
+  };
+  return {
+    refresh: () => {
+      if (closed) return Promise.resolve();
+      const running = inFlight;
+      if (running) {
+        dirty = true;
+        return running;
+      }
+      return start2();
+    },
+    close: async () => {
+      closed = true;
+      dirty = false;
+      await inFlight?.catch(() => void 0);
+    }
+  };
+}
+var DOCS_DEBOUNCE_MS, DOCS_RETRY_MS, said2;
+var init_service = __esm({
+  "src/documents/service.ts"() {
+    "use strict";
+    init_log();
+    init_mirror();
+    init_paths2();
+    init_scan();
+    DOCS_DEBOUNCE_MS = 1e3;
+    DOCS_RETRY_MS = 1e3;
+    said2 = (err) => err instanceof Error ? err.message : String(err);
+  }
+});
+
 // src/claude/auth-mode.ts
 function authModeFrom(info) {
   if (info.apiProvider && info.apiProvider !== "firstParty") return "third_party";
@@ -5149,8 +5715,8 @@ var init_policy = __esm({
 import { spawn as spawn2 } from "child_process";
 import { randomUUID as randomUUID4 } from "crypto";
 import { EventEmitter as EventEmitter2 } from "events";
-import { chmodSync as chmodSync4, lstatSync as lstatSync4, mkdirSync as mkdirSync6, rmdirSync, rmSync as rmSync6, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname7, join as join16 } from "path";
+import { chmodSync as chmodSync4, lstatSync as lstatSync5, mkdirSync as mkdirSync6, rmdirSync, rmSync as rmSync6, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname7, join as join18 } from "path";
 function removeFiles(files) {
   for (const file of files) rmSync6(file, { force: true });
 }
@@ -5303,14 +5869,14 @@ ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
           mkdirSync6(dir, { recursive: true, mode: 448 });
           assertStagingInsideHome(home, dir);
           for (const path of [dirname7(dir), dir]) {
-            const st = lstatSync4(path);
+            const st = lstatSync5(path);
             if (st.isSymbolicLink() || !st.isDirectory()) {
               throw new Error(`${path} is not a plain directory`);
             }
           }
           chmodSync4(dir, 448);
           for (const image of images) {
-            const path = join16(dir, `${randomUUID4()}.${ATTACHMENT_MEDIA_TYPES[image.mediaType]}`);
+            const path = join18(dir, `${randomUUID4()}.${ATTACHMENT_MEDIA_TYPES[image.mediaType]}`);
             writeFileSync5(path, image.data, { mode: 384, flag: "wx" });
             written.push(path);
           }
@@ -5600,15 +6166,15 @@ var init_types = __esm({
 });
 
 // src/skills/paths.ts
-import { realpathSync as realpathSync8 } from "fs";
-import { isAbsolute as isAbsolute10, join as join17, relative as relative4, sep as sep5 } from "path";
+import { realpathSync as realpathSync9 } from "fs";
+import { isAbsolute as isAbsolute11, join as join19, relative as relative5, sep as sep6 } from "path";
 function clearSessionSkills(home, runnerId, heldBy) {
-  clearRunnerStaging(home, join17(home, "session-skills"), runnerId, heldBy);
+  clearRunnerStaging(home, join19(home, "session-skills"), runnerId, heldBy);
 }
 function assertInsideScopeDir(path, scopeDir) {
   let dirNow;
   try {
-    dirNow = realpathSync8.native(scopeDir);
+    dirNow = realpathSync9.native(scopeDir);
   } catch {
     throw new Error(`ROOT_NOT_ALLOWED: ${scopeDir} does not exist`);
   }
@@ -5616,20 +6182,20 @@ function assertInsideScopeDir(path, scopeDir) {
     throw new Error(`ROOT_NOT_ALLOWED: ${scopeDir} no longer resolves to itself (${dirNow})`);
   }
   const real = assertInsideRoots(path, [scopeDir]);
-  const rel = relative4(scopeDir, real);
-  if (rel === "" || rel === ".." || rel.startsWith(`..${sep5}`) || isAbsolute10(rel)) {
+  const rel = relative5(scopeDir, real);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep6}`) || isAbsolute11(rel)) {
     throw new Error(`ROOT_NOT_ALLOWED: ${path}`);
   }
   return real;
 }
 var sessionSkillsRoot, sessionSkillsDir;
-var init_paths2 = __esm({
+var init_paths3 = __esm({
   "src/skills/paths.ts"() {
     "use strict";
     init_paths();
     init_attachments2();
-    sessionSkillsRoot = (home, runnerId) => join17(home, "session-skills", runnerId);
-    sessionSkillsDir = (home, runnerId, sessionId) => join17(sessionSkillsRoot(home, runnerId), sessionId);
+    sessionSkillsRoot = (home, runnerId) => join19(home, "session-skills", runnerId);
+    sessionSkillsDir = (home, runnerId, sessionId) => join19(sessionSkillsRoot(home, runnerId), sessionId);
   }
 });
 
@@ -5760,22 +6326,22 @@ var init_refusal = __esm({
 });
 
 // src/skills/scan.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import {
   existsSync as existsSync5,
-  constants as fsConstants,
-  lstatSync as lstatSync5,
-  realpathSync as realpathSync9
+  constants as fsConstants2,
+  lstatSync as lstatSync6,
+  realpathSync as realpathSync10
 } from "fs";
-import { open, opendir } from "fs/promises";
-import { isAbsolute as isAbsolute11, join as join18, relative as relative5, sep as sep6 } from "path";
+import { open as open2, opendir } from "fs/promises";
+import { isAbsolute as isAbsolute12, join as join20, relative as relative6, sep as sep7 } from "path";
 function inside(root, candidate) {
-  const rel = relative5(root, candidate);
-  return rel === "" || !rel.startsWith(`..${sep6}`) && rel !== ".." && !isAbsolute11(rel);
+  const rel = relative6(root, candidate);
+  return rel === "" || !rel.startsWith(`..${sep7}`) && rel !== ".." && !isAbsolute12(rel);
 }
 function canonical2(dir) {
   try {
-    return realpathSync9.native(dir);
+    return realpathSync10.native(dir);
   } catch {
     return dir;
   }
@@ -5797,11 +6363,11 @@ function scopeRoots(opts) {
   const isGitRepo = opts.isGitRepo ?? defaultIsGitRepo;
   const home = canonical2(opts.home);
   const homes = protectedHomes(opts);
-  const found = [{ scope: "personal", dir: join18(home, "skills"), base: home }];
+  const found = [{ scope: "personal", dir: join20(home, "skills"), base: home }];
   let skillsRepo;
   if (opts.skillsRepo !== void 0) {
     try {
-      if (!isAbsolute11(opts.skillsRepo)) throw new Error("skillsRepo must be an absolute path");
+      if (!isAbsolute12(opts.skillsRepo)) throw new Error("skillsRepo must be an absolute path");
       skillsRepo = resolveInsideRoots(opts.skillsRepo, opts.roots).real;
     } catch (err) {
       log.warn(
@@ -5813,12 +6379,12 @@ function scopeRoots(opts) {
   for (const root of opts.roots) {
     let real;
     try {
-      real = realpathSync9.native(root);
+      real = realpathSync10.native(root);
     } catch {
       continue;
     }
     if (!isGitRepo(real)) continue;
-    const dir = join18(real, ".cayenne", "skills");
+    const dir = join20(real, ".cayenne", "skills");
     const shared = skillsRepo !== void 0 && real === skillsRepo ? "workspace" : "project";
     if (overlapsHome(canonical2(dir), homes, shared, log)) continue;
     if (skillsRepo !== void 0 && real === skillsRepo) {
@@ -5836,7 +6402,7 @@ function resolveScopeRoots(opts) {
   for (const root of scopeRoots(opts)) {
     let dirReal;
     try {
-      dirReal = realpathSync9.native(root.dir);
+      dirReal = realpathSync10.native(root.dir);
     } catch {
       continue;
     }
@@ -5861,7 +6427,7 @@ async function scanSkills(opts) {
     if (exhausted) break;
     let entries;
     try {
-      entries = await readCapped(root.dirReal, log, root.scope);
+      entries = await readCapped2(root.dirReal, log, root.scope);
     } catch {
       continue;
     }
@@ -5880,7 +6446,7 @@ async function scanSkills(opts) {
       } catch (err) {
         log.warn(
           {
-            path: join18(root.dirReal, entry.name),
+            path: join20(root.dirReal, entry.name),
             scope: root.scope,
             err: err instanceof Error ? err.message : String(err)
           },
@@ -5895,7 +6461,7 @@ async function scanSkills(opts) {
   }
   return found;
 }
-async function readCapped(dir, log, scope) {
+async function readCapped2(dir, log, scope) {
   const handle = await opendir(dir);
   const entries = [];
   try {
@@ -5914,7 +6480,7 @@ async function readCapped(dir, log, scope) {
   }
   return entries.sort((a, b) => a.name < b.name ? -1 : 1);
 }
-async function readAtMost(fh, limit) {
+async function readAtMost2(fh, limit) {
   const buffer = Buffer.allocUnsafe(limit);
   let filled = 0;
   while (filled < limit) {
@@ -5925,13 +6491,13 @@ async function readAtMost(fh, limit) {
   return buffer.subarray(0, filled);
 }
 async function readEntry(root, entry, log, budget) {
-  const path = join18(root.dirReal, entry.name);
+  const path = join20(root.dirReal, entry.name);
   const skip = (reason) => {
     log.warn({ path, scope: root.scope }, `skill skipped: ${reason}`);
     return null;
   };
   if (entry.isDirectory()) {
-    const nested = existsSync5(join18(path, "SKILL.md"));
+    const nested = existsSync5(join20(path, "SKILL.md"));
     return skip(
       nested ? `a directory holding SKILL.md: Cayenne's store is flat, so move it to ${entry.name}.md beside this directory` : "a directory, and the scan does not recurse"
     );
@@ -5941,20 +6507,20 @@ async function readEntry(root, entry, log, budget) {
   if (!SKILL_SLUG.test(slug)) return skip("the filename is not a legal slug");
   let real;
   try {
-    real = realpathSync9.native(path);
+    real = realpathSync10.native(path);
   } catch {
     return skip("cannot be resolved");
   }
   if (!inside(root.dirReal, real)) return skip("a symlink whose target is outside the scope root");
   let proved;
   try {
-    proved = lstatSync5(real);
+    proved = lstatSync6(real);
   } catch {
     return skip("cannot be read");
   }
   let fh;
   try {
-    fh = await open(real, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    fh = await open2(real, fsConstants2.O_RDONLY | fsConstants2.O_NOFOLLOW);
   } catch {
     return skip("cannot be read");
   }
@@ -5965,7 +6531,7 @@ async function readEntry(root, entry, log, budget) {
     if (!stat.isFile()) return skip("not a regular file");
     if (stat.dev !== proved.dev || stat.ino !== proved.ino) return skip("changed while being read");
     if (stat.size > SKILL_BODY_MAX) return skip(`larger than ${SKILL_BODY_MAX} bytes`);
-    bytes = await readAtMost(fh, SKILL_BODY_MAX + 1);
+    bytes = await readAtMost2(fh, SKILL_BODY_MAX + 1);
   } catch {
     return skip("cannot be read");
   } finally {
@@ -5994,9 +6560,9 @@ async function readEntry(root, entry, log, budget) {
     ...parsed.ok && parsed.data.description !== void 0 ? { description: parsed.data.description } : {},
     declaredTools: parsed.ok ? parsed.data.tools : [],
     permission: parsed.ok ? parsed.data.permission : "inherit",
-    sourcePath: relative5(root.base, path),
+    sourcePath: relative6(root.base, path),
     ...root.projectPath !== void 0 ? { projectPath: root.projectPath } : {},
-    contentHash: createHash3("sha256").update(bytes).digest("hex"),
+    contentHash: createHash4("sha256").update(bytes).digest("hex"),
     ...fileMtime !== void 0 ? { fileMtime } : {},
     // The reason only: `refusal.detail` can quote the file's own frontmatter (protocol §2.3).
     refusal: refusal?.reason ?? null
@@ -6080,7 +6646,7 @@ function scalar(raw, prose = false) {
   return !prose && /:\s/.test(value) || /\s#/.test(value) ? null : value;
 }
 var SKILL_SCAN_MAX_PER_DIR, SKILL_SCAN_MAX_SKILLS, SKILL_SCAN_MAX_BYTES, defaultIsGitRepo, summariesOf, FRONTMATTER, KEY, ITEM;
-var init_scan = __esm({
+var init_scan2 = __esm({
   "src/skills/scan.ts"() {
     "use strict";
     init_src();
@@ -6091,7 +6657,7 @@ var init_scan = __esm({
     SKILL_SCAN_MAX_PER_DIR = 500;
     SKILL_SCAN_MAX_SKILLS = 500;
     SKILL_SCAN_MAX_BYTES = 32 * 1024 * 1024;
-    defaultIsGitRepo = (dir) => lstatSync5(join18(dir, ".git"), { throwIfNoEntry: false }) !== void 0;
+    defaultIsGitRepo = (dir) => lstatSync6(join20(dir, ".git"), { throwIfNoEntry: false }) !== void 0;
     summariesOf = (scan) => scan.map((s) => s.summary);
     FRONTMATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
     KEY = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]*(.*)$/;
@@ -6100,17 +6666,17 @@ var init_scan = __esm({
 });
 
 // src/skills/materialise.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import {
   chmodSync as chmodSync5,
-  constants as fsConstants2,
-  lstatSync as lstatSync6,
+  constants as fsConstants3,
+  lstatSync as lstatSync7,
   mkdirSync as mkdirSync7,
   readdirSync as readdirSync2,
   rmSync as rmSync7
 } from "fs";
-import { open as open2, writeFile } from "fs/promises";
-import { dirname as dirname8, isAbsolute as isAbsolute12, join as join19, relative as relative6, sep as sep7 } from "path";
+import { open as open3, writeFile } from "fs/promises";
+import { dirname as dirname8, isAbsolute as isAbsolute13, join as join21, relative as relative7, sep as sep8 } from "path";
 function isSkillRefusal(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return msg.startsWith("ROOT_NOT_ALLOWED") || msg.startsWith(BUDGET) || msg.includes("is not a plain directory") || msg.includes("is not part of the session skills plugin");
@@ -6157,7 +6723,7 @@ async function materialiseSkills(scan, t) {
   }
   const path = plainDirectory(t.home, sessionSkillsDir(t.home, t.runnerId, t.sessionId));
   await writeFile(
-    join19(plainDirectory(t.home, join19(path, ".claude-plugin")), "plugin.json"),
+    join21(plainDirectory(t.home, join21(path, ".claude-plugin")), "plugin.json"),
     `${JSON.stringify(
       {
         name: SKILL_PLUGIN_NAME,
@@ -6187,13 +6753,13 @@ async function materialiseSkills(scan, t) {
       );
     }
     try {
-      const dir = plainDirectory(t.home, join19(path, "skills", slug));
-      await writeFile(join19(dir, "SKILL.md"), bytes, { mode: 384, flag: "wx" });
+      const dir = plainDirectory(t.home, join21(path, "skills", slug));
+      await writeFile(join21(dir, "SKILL.md"), bytes, { mode: 384, flag: "wx" });
       slugs.push(slug);
     } catch (err) {
       note(log, err, { slug, scope, path: skill.path }, "skill not materialised for this session");
       try {
-        rmSync7(assertStagingInsideHome(t.home, join19(path, "skills", slug)), {
+        rmSync7(assertStagingInsideHome(t.home, join21(path, "skills", slug)), {
           recursive: true,
           force: true
         });
@@ -6220,7 +6786,7 @@ async function firstAcceptable(candidates, log, markStale) {
       note(log, err, fields, "skill not materialised for this session");
       continue;
     }
-    const hash = createHash4("sha256").update(bytes).digest("hex");
+    const hash = createHash5("sha256").update(bytes).digest("hex");
     if (hash !== skill.summary.contentHash) {
       markStale();
       say(
@@ -6257,21 +6823,21 @@ function assertSealed(path, slugs) {
     const want = new Set(expected);
     for (const entry of entries) {
       const ok = kind === "dir" ? entry.isDirectory() : entry.isFile();
-      if (!ok || !want.has(entry.name)) throw stray(join19(dir, entry.name));
+      if (!ok || !want.has(entry.name)) throw stray(join21(dir, entry.name));
     }
-    if (entries.length !== want.size) throw stray(join19(dir, [...want].join("|")));
+    if (entries.length !== want.size) throw stray(join21(dir, [...want].join("|")));
   };
   named(path, [".claude-plugin", "skills"], "dir");
-  named(join19(path, ".claude-plugin"), ["plugin.json"], "file");
-  named(join19(path, "skills"), slugs, "dir");
-  for (const slug of slugs) named(join19(path, "skills", slug), ["SKILL.md"], "file");
+  named(join21(path, ".claude-plugin"), ["plugin.json"], "file");
+  named(join21(path, "skills"), slugs, "dir");
+  for (const slug of slugs) named(join21(path, "skills", slug), ["SKILL.md"], "file");
 }
 function plainDirectory(home, dir) {
   const intended = assertStagingInsideHome(home, dir);
   mkdirSync7(intended, { recursive: true, mode: 448 });
   const proved = assertStagingInsideHome(home, intended);
   for (const p of [dirname8(proved), proved]) {
-    const st = lstatSync6(p);
+    const st = lstatSync7(p);
     if (st.isSymbolicLink() || !st.isDirectory()) throw new Error(`${p} is not a plain directory`);
   }
   chmodSync5(proved, 448);
@@ -6289,7 +6855,7 @@ async function readBody(skill) {
   }
   let fh;
   try {
-    fh = await open2(real, fsConstants2.O_RDONLY | fsConstants2.O_NOFOLLOW);
+    fh = await open3(real, fsConstants3.O_RDONLY | fsConstants3.O_NOFOLLOW);
   } catch {
     throw new Error("no longer on disk, or no longer a file the runner may follow");
   }
@@ -6299,7 +6865,7 @@ async function readBody(skill) {
     stat = await fh.stat();
     if (!stat.isFile()) throw new Error("no longer a regular file");
     if (stat.size > SKILL_BODY_MAX) throw new Error(`larger than ${SKILL_BODY_MAX} bytes`);
-    bytes = await readAtMost(fh, SKILL_BODY_MAX + 1);
+    bytes = await readAtMost2(fh, SKILL_BODY_MAX + 1);
   } finally {
     await fh.close().catch(() => void 0);
   }
@@ -6313,22 +6879,22 @@ var init_materialise = __esm({
     init_src();
     init_log();
     init_attachments2();
-    init_paths2();
-    init_scan();
+    init_paths3();
+    init_scan2();
     SKILL_PLUGIN_NAME = "cayenne";
     SESSION_SKILLS_MAX = 64;
     SESSION_SKILLS_MAX_BYTES = 8 * 1024 * 1024;
     BUDGET = "SKILL_BUDGET:";
     PRECEDENCE = { personal: 0, project: 1, workspace: 2 };
     isAtOrBelow = (p, dir) => {
-      const rel = relative6(dir, p);
-      return rel === "" || !rel.startsWith(`..${sep7}`) && rel !== ".." && !isAbsolute12(rel);
+      const rel = relative7(dir, p);
+      return rel === "" || !rel.startsWith(`..${sep8}`) && rel !== ".." && !isAbsolute13(rel);
     };
   }
 });
 
 // src/sessions/repo-settings.ts
-import { isAbsolute as isAbsolute13, relative as relative7, sep as sep8 } from "path";
+import { isAbsolute as isAbsolute14, relative as relative8, sep as sep9 } from "path";
 function repoSettingsPolicy(input) {
   const bypassLock = input.permissionMode === "bypassPermissions" ? {} : { permissions: { disableBypassPermissionsMode: "disable" } };
   const claudeMd = () => ({
@@ -6350,8 +6916,8 @@ function repoSettingsPolicy(input) {
   return { settingSources: ["user"], ...claudeMd(), settings: { ...bypassLock } };
 }
 function insideRoot2(candidate, root) {
-  const rel = relative7(root, candidate);
-  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep8}`) && !isAbsolute13(rel);
+  const rel = relative8(root, candidate);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep9}`) && !isAbsolute14(rel);
 }
 var init_repo_settings = __esm({
   "src/sessions/repo-settings.ts"() {
@@ -6361,8 +6927,8 @@ var init_repo_settings = __esm({
 
 // src/sessions/manager.ts
 import { randomUUID as randomUUID5 } from "crypto";
-import { realpathSync as realpathSync10 } from "fs";
-import { isAbsolute as isAbsolute14, sep as sep9 } from "path";
+import { realpathSync as realpathSync11 } from "fs";
+import { isAbsolute as isAbsolute15, sep as sep10 } from "path";
 import { isDeepStrictEqual } from "util";
 function narrowToSession(suggestions) {
   if (!suggestions) return suggestions;
@@ -6390,6 +6956,8 @@ var init_manager = __esm({
     "use strict";
     init_src();
     init_config();
+    init_paths2();
+    init_service();
     init_introspect();
     init_watch();
     init_worktree();
@@ -6401,7 +6969,7 @@ var init_manager = __esm({
     init_attachments2();
     init_repo_settings();
     roundUsd = (usd) => Math.round(usd * 1e6) / 1e6;
-    isAtOrBelow2 = (p, dir) => p === dir || p.startsWith(dir.endsWith(sep9) ? dir : `${dir}${sep9}`);
+    isAtOrBelow2 = (p, dir) => p === dir || p.startsWith(dir.endsWith(sep10) ? dir : `${dir}${sep10}`);
     DENY_MESSAGE_MAX = 2e3;
     EXIT_ERROR_MAX = 8 * 1024;
     INITIAL_PROMPT_MAX = 2e5;
@@ -6897,7 +7465,7 @@ var init_manager = __esm({
           if (stored === null) return false;
           if (isAtOrBelow2(stored, target)) return true;
           try {
-            return isAtOrBelow2(realpathSync10.native(stored), target);
+            return isAtOrBelow2(realpathSync11.native(stored), target);
           } catch {
             return false;
           }
@@ -7155,7 +7723,7 @@ var init_manager = __esm({
       }
       /** A path as the SDK reads it: relative means relative to the session's cwd. */
       fromCwd(cwd, value) {
-        return isAbsolute14(value) ? value : `${cwd}${sep9}${value}`;
+        return isAbsolute15(value) ? value : `${cwd}${sep10}${value}`;
       }
       /**
        * §2.9: a path in `updatedInput` passes the same boundary the session's `cwd` did, and the
@@ -7386,6 +7954,7 @@ var init_manager = __esm({
           inflight: /* @__PURE__ */ new Set(),
           changesVersion: this.nextChangesSeed(),
           watcher: null,
+          docs: null,
           costLast: 0,
           costTotal: null,
           costUnsaved: 0,
@@ -7393,10 +7962,64 @@ var init_manager = __esm({
         };
         this.live.set(sessionId, live);
         this.wire(sessionId, live);
+        live.docs = this.watchDocuments(sessionId, live);
         live.session.start();
         live.watcher = this.watchWorkingCopy(sessionId, live);
         return live;
       }
+      /**
+       * Arm this session's documents mirror: the service, one pass now, and the watch on
+       * `<cwd>/.cayenne/docs` (lane 5 design §3).
+       *
+       * The directory is never created. Most sessions never write a document, and making it would put
+       * a directory inside the person's repository that they did not ask for; `watchDirs` retries a
+       * directory that is not there and announces on attach, so a file written before it existed is
+       * still picked up — one retry tick plus one debounce, inside the feature's five-second budget.
+       *
+       * Nothing here can fail the session. A service that cannot be built and a watch that cannot be
+       * armed are both a Documents tab that does not update, logged once at warn.
+       */
+      watchDocuments(sessionId, live) {
+        const make = this.deps.documents ?? createDocumentsService;
+        let service2;
+        try {
+          service2 = make({
+            db: this.deps.db,
+            workspaceId: this.deps.workspaceId,
+            // The runner owner, always: it writes as the member it logged in as, and 0022's session
+            // clause is what hands the row to the member whose chat it is. There is no
+            // insert-on-behalf-of path and this must not grow one.
+            ownerId: this.deps.runnerUserId,
+            sessionId,
+            // The canonical directory the provider was spawned in — the worktree when one applies —
+            // never a path a payload carried.
+            cwd: live.cwd,
+            log: this.deps.log
+          });
+        } catch (err) {
+          this.deps.log.warn({ err, sessionId }, "the documents service could not be built");
+          return null;
+        }
+        const refresh = () => {
+          if (this.live.get(sessionId) !== live) return;
+          void service2.refresh().catch(
+            (err) => this.deps.log.warn({ err, sessionId }, "documents refresh failed")
+          );
+        };
+        const attach = this.deps.watchDocs ?? watchDirs;
+        let watcher = null;
+        try {
+          watcher = attach([docsDir(live.cwd)], refresh, {
+            debounceMs: DOCS_DEBOUNCE_MS,
+            retryMs: DOCS_RETRY_MS,
+            onError: (err) => this.deps.log.warn({ err, sessionId }, "documents watcher error; live refresh stopped")
+          });
+        } catch (err) {
+          this.deps.log.warn({ err, sessionId }, "the documents watcher failed to start");
+        }
+        refresh();
+        return { service: service2, watcher };
+      }
       /**
        * Watch the directory the provider was spawned in — `live.cwd`, the canonical path `start()` or
        * `ensureLive()` proved inside the roots (the worktree, when one applies) — and re-broadcast
@@ -7660,6 +8283,14 @@ var init_manager = __esm({
         await Promise.resolve().then(() => watcher?.close()).catch(
           (err) => this.deps.log.warn({ err, sessionId }, "closing the working-copy watcher failed")
         );
+        const docs = live.docs;
+        live.docs = null;
+        await Promise.resolve().then(async () => {
+          await docs?.watcher?.close();
+          await docs?.service.close();
+        }).catch(
+          (err) => this.deps.log.warn({ err, sessionId }, "closing the documents watch failed")
+        );
         if (this.live.get(sessionId) !== live) return;
         this.live.delete(sessionId);
         this.discardSkills(sessionId);
@@ -7804,7 +8435,7 @@ var init_manager = __esm({
 });
 
 // src/skills/mirror.ts
-function rowOf(deps, skill) {
+function rowOf2(deps, skill) {
   return {
     workspace_id: deps.workspaceId,
     scope: skill.scope,
@@ -7872,7 +8503,7 @@ async function syncSkills(deps, found) {
   const seen = /* @__PURE__ */ new Set();
   const rows = [];
   for (const skill of found) {
-    const row = rowOf(deps, skill);
+    const row = rowOf2(deps, skill);
     const key = keyOf2({
       scope: skill.scope,
       slug: skill.slug,
@@ -7933,7 +8564,7 @@ async function syncSkills(deps, found) {
   return { upserted, missing };
 }
 var SKILLS_IDENTITY, SKILLS_MIRROR_MAX_ROWS, keyOf2, instant;
-var init_mirror = __esm({
+var init_mirror2 = __esm({
   "src/skills/mirror.ts"() {
     "use strict";
     init_log();
@@ -7945,9 +8576,9 @@ var init_mirror = __esm({
 });
 
 // src/skills/service.ts
-import { createHash as createHash5 } from "crypto";
-import { constants as fsConstants3, realpathSync as realpathSync11 } from "fs";
-import { open as open3 } from "fs/promises";
+import { createHash as createHash6 } from "crypto";
+import { constants as fsConstants4, realpathSync as realpathSync12 } from "fs";
+import { open as open4 } from "fs/promises";
 function createSkillsService(deps) {
   const log = deps.log ?? logger;
   const scanner = deps.scanner ?? scanSkills;
@@ -8008,7 +8639,7 @@ function createSkillsService(deps) {
     let wanted;
     if (payload.scope === "project" && payload.projectPath !== void 0) {
       try {
-        wanted = realpathSync11.native(payload.projectPath);
+        wanted = realpathSync12.native(payload.projectPath);
       } catch {
         throw missing();
       }
@@ -8046,7 +8677,7 @@ function createSkillsService(deps) {
       const real = assertInsideScopeDir(skill.path, skill.scopeDir);
       let fh;
       try {
-        fh = await open3(real, fsConstants3.O_RDONLY | fsConstants3.O_NOFOLLOW);
+        fh = await open4(real, fsConstants4.O_RDONLY | fsConstants4.O_NOFOLLOW);
       } catch {
         throw refuse2(`skill ${payload.slug} is no longer on disk`);
       }
@@ -8056,28 +8687,28 @@ function createSkillsService(deps) {
         stat = await fh.stat();
         if (!stat.isFile()) throw refuse2(`skill ${payload.slug} is no longer a file`);
         if (stat.size > SKILL_BODY_MAX) throw refuse2("skill body too large");
-        bytes = await readAtMost(fh, SKILL_BODY_MAX + 1);
+        bytes = await readAtMost2(fh, SKILL_BODY_MAX + 1);
       } finally {
         await fh.close().catch(() => void 0);
       }
       if (bytes.byteLength > SKILL_BODY_MAX) throw refuse2("skill body too large");
       return {
         body: bytes.toString("utf8"),
-        contentHash: createHash5("sha256").update(bytes).digest("hex"),
+        contentHash: createHash6("sha256").update(bytes).digest("hex"),
         sourcePath: skill.summary.sourcePath
       };
     }
   };
 }
 var refuse2, SKILL_LIST_RESULT_MAX;
-var init_service = __esm({
+var init_service2 = __esm({
   "src/skills/service.ts"() {
     "use strict";
     init_src();
     init_log();
-    init_mirror();
-    init_paths2();
-    init_scan();
+    init_mirror2();
+    init_paths3();
+    init_scan2();
     refuse2 = (message) => new Error(`VALIDATION: ${message}`);
     SKILL_LIST_RESULT_MAX = 1024 * 1024;
   }
@@ -8126,9 +8757,9 @@ function createTerminalChannels({
       const inflight = joining.get(terminalId);
       if (inflight) return inflight;
       if (joined.has(terminalId)) return;
-      const join22 = attachOne(terminalId).finally(() => joining.delete(terminalId));
-      joining.set(terminalId, join22);
-      return join22;
+      const join24 = attachOne(terminalId).finally(() => joining.delete(terminalId));
+      joining.set(terminalId, join24);
+      return join24;
     },
     flush,
     detach,
@@ -8183,9 +8814,9 @@ var init_channels = __esm({
 });
 
 // src/terminal/env.ts
-import { readFileSync as readFileSync7, realpathSync as realpathSync12 } from "fs";
+import { readFileSync as readFileSync8, realpathSync as realpathSync13 } from "fs";
 import { lstat } from "fs/promises";
-import { dirname as dirname9, isAbsolute as isAbsolute15, relative as relative8 } from "path";
+import { dirname as dirname9, isAbsolute as isAbsolute16, relative as relative9 } from "path";
 function terminalEnv(base, { runnerOwner, claudeConfigDir }) {
   const env = {};
   for (const [key, value] of Object.entries(base)) {
@@ -8254,8 +8885,8 @@ function tryRealpath(fs, p) {
   }
 }
 function inside2(candidate, root) {
-  const rel = relative8(root, candidate);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute15(rel);
+  const rel = relative9(root, candidate);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute16(rel);
 }
 var SECRET_ENV, MEMBER_ENV_ALLOW, MEMBER_ENV_KEYS, LOCALE_ENV, nodeShellFs;
 var init_env = __esm({
@@ -8280,12 +8911,12 @@ var init_env = __esm({
     nodeShellFs = {
       readEtcShells: () => {
         try {
-          return readFileSync7("/etc/shells", "utf8");
+          return readFileSync8("/etc/shells", "utf8");
         } catch {
           return "";
         }
       },
-      realpath: (p) => realpathSync12.native(p),
+      realpath: (p) => realpathSync13.native(p),
       lstat: (p) => lstat(p)
     };
   }
@@ -9208,7 +9839,7 @@ function createTerminalService({
   };
 }
 var messageOf2;
-var init_service2 = __esm({
+var init_service3 = __esm({
   "src/terminal/service.ts"() {
     "use strict";
     init_manager2();
@@ -9225,7 +9856,7 @@ __export(start_exports, {
   start: () => start
 });
 import { homedir as homedir4, hostname } from "os";
-import { join as join20 } from "path";
+import { join as join22 } from "path";
 function protectedPaths(claudeConfigDir, home = homedir4()) {
   const inHome = [
     ".claude",
@@ -9233,12 +9864,12 @@ function protectedPaths(claudeConfigDir, home = homedir4()) {
     ".codex",
     ".ssh",
     ".aws",
-    join20(".config", "gh"),
+    join22(".config", "gh"),
     ".gnupg",
     ".git-credentials",
     ".npmrc",
     ".netrc"
-  ].map((p) => join20(home, p));
+  ].map((p) => join22(home, p));
   return [cayenneHome(), ...claudeConfigDir ? [claudeConfigDir] : [], ...inHome];
 }
 function logCodex(codex) {
@@ -9391,7 +10022,12 @@ async function compose(cfg, lock, host, preflight) {
     promptImages: true,
     // D38: this build scans `.cayenne/skills` and answers both `runner.skills.*` kinds, so the
     // Skills page can say "this runner cannot list skills" about an older one instead of waiting.
-    skills: true
+    skills: true,
+    // D40: this build mirrors what a session writes under `.cayenne/docs`, so the Documents tab
+    // can say "this runner does not publish documents" about an older one instead of "none yet".
+    // Nothing else is composed here: the mirror is one service per live session, built by the
+    // manager from the directory the provider actually runs in (lane 5 design §3).
+    documents: true
   });
   const registered = capabilities();
   let loggedCodex = null;
@@ -9478,9 +10114,9 @@ async function compose(cfg, lock, host, preflight) {
       // The roster's own array, mutated in place: `serves` reads the live list with no restart.
       allowedMemberIds: liveRoster.allowedMemberIds,
       // Outside every profile and repository: the creator of a worktree is the machine's record.
-      worktreeOwners: createWorktreeOwners(join20(cayenneHome(), "worktrees")),
+      worktreeOwners: createWorktreeOwners(join22(cayenneHome(), "worktrees")),
       // Beside it: where each session was spawned, the only source of a resumed directory.
-      sessionWorktrees: createSessionWorktrees(join20(cayenneHome(), "session-worktrees")),
+      sessionWorktrees: createSessionWorktrees(join22(cayenneHome(), "session-worktrees")),
       roots,
       allowBypass: cfg.allowBypassPermissions,
       trustedRoots,
@@ -9775,22 +10411,22 @@ var init_start = __esm({
     init_attachments2();
     init_handlers();
     init_manager();
-    init_paths2();
-    init_service();
+    init_paths3();
+    init_service2();
     init_supabase();
     init_channels();
     init_manager2();
     init_process_group();
     init_pty();
-    init_service2();
+    init_service3();
     init_version();
   }
 });
 
 // src/cli.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync8, readFileSync as readFileSync8, realpathSync as realpathSync13, rmSync as rmSync8, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync8, readFileSync as readFileSync9, realpathSync as realpathSync14, rmSync as rmSync8, writeFileSync as writeFileSync6 } from "fs";
 import { homedir as homedir5, hostname as hostname2, userInfo } from "os";
-import { dirname as dirname10, join as join21 } from "path";
+import { dirname as dirname10, join as join23 } from "path";
 import { Command } from "commander";
 import prompts from "prompts";
 
@@ -10392,7 +11028,7 @@ program.command("doctor").description("Check the install and say how to fix what
   if (checks.some((c) => !c.ok)) process.exitCode = 1;
 });
 program.command("logs").description("Show the service log").option("-f, --follow", "keep streaming").action(async (opts) => {
-  const file = join21(cayenneDir(), "logs", "runner.log");
+  const file = join23(cayenneDir(), "logs", "runner.log");
   if (!existsSync6(file)) throw new Error(`no log yet at ${file}. Run \`cayenne up\` first.`);
   const print = (chunk) => {
     for (const line of chunk.split("\n")) {
@@ -10405,12 +11041,12 @@ program.command("logs").description("Show the service log").option("-f, --follow
       }
     }
   };
-  print(readFileSync8(file, "utf8"));
+  print(readFileSync9(file, "utf8"));
   if (opts.follow) {
     const { watch: watch2 } = await import("fs");
-    let size = readFileSync8(file).length;
+    let size = readFileSync9(file).length;
     watch2(file, () => {
-      const buf = readFileSync8(file);
+      const buf = readFileSync9(file);
       if (buf.length > size) print(buf.subarray(size).toString("utf8"));
       size = buf.length;
     });
@@ -10438,7 +11074,7 @@ program.command("update").description("Re-pin the installed app and restart the
       cliPath: record.cliPath,
       profile: currentProfile(),
       pathEnv: record.pathEnv,
-      logDir: join21(dir, "logs")
+      logDir: join23(dir, "logs")
     })
   );
   await launchd.bootout(label);
@@ -10454,12 +11090,12 @@ program.command("uninstall").description("Stop the service and remove the launch
     console.log(`removed ${label}`);
     return;
   }
-  const dir = realpathSync13(cayenneDir());
-  const home = realpathSync13(homedir5());
+  const dir = realpathSync14(cayenneDir());
+  const home = realpathSync14(homedir5());
   if (dir === "/" || dir === home || home.startsWith(`${dir}/`)) {
     throw new Error(`refusing to purge ${dir}: it is the home directory or an ancestor of it`);
   }
-  if (!existsSync6(join21(dir, "config.json")) && !existsSync6(join21(dir, "app", "install.json"))) {
+  if (!existsSync6(join23(dir, "config.json")) && !existsSync6(join23(dir, "app", "install.json"))) {
     throw new Error(`refusing to purge ${dir}: it does not look like a Cayenne profile`);
   }
   if (!opts.yes) {