@stravica-ai/digital-operator-pa 0.1.68 → 0.1.69

package/dist/engineering-pa-workspace/README.md

@@ -199,6 +199,37 @@ Live reload was temporarily removed pending a workspace rebuild. Refresh the bro
 - **Writes.** The PA writes the board only with `pa status set | patch | show` (validated, atomic temp-then-rename). Bare `pa status` is still the environment probe.
 - **Behaviour.** Refreshes every 60 seconds and when the tab comes back into view, without reloading (scroll position and the "Done today" open state survive). The freshness pill turns amber at 45 minutes and red at 90 since `updatedAt`. A bad file (unparseable or off-schema) keeps the last good copy on screen behind a red banner. No board yet shows a plain "No status board yet today" card and keeps checking.
 
+## Notes page (notes API)
+
+`app/notes.html` is the core **Notes** page. It lists every note the PA and the operator keep, newest first, and opens each one in the viewer. The home page notes rail shows the first eight of the same list.
+
+- **Roots.** `GET /__api/notes` walks these notes roots, in order:
+  1. `operator/notes`, the instance's canonical notes directory (the scaffold creates it). Always first.
+  2. `agents/<paName>/workspace/notes`, where the running PA writes its session notes beside its status board. `paName` resolves the same way the Status page does.
+  3. Each repo-relative path in the preferences key `notesRoots` (an array of strings in `operator/config/preferences.json` or the local overlay), in the order given. Example: `"notesRoots": ["agents/<other-agent>/workspace/notes", "shared/notes"]`.
+
+  With no `notesRoots` key the first two roots are walked; that is the default. Discovery covers the resolved PA only, not every `agents/*` folder, so a second agent's notes need a `notesRoots` entry. A configured root that is not a non-empty string, names the repo root itself or resolves outside the repo (by path or through a symlink) is refused: the server logs a warning and never walks it. A root named twice is walked once, and a note under a root nested inside an earlier root is listed once, under the earlier root.
+- **What counts as a note.** In every root: files ending `.md` or `.html` (the viewer renders `.md` and serves `.html` as is), at any depth, except under a top-level `assets/` folder of that root. Nothing inside a file is read. The title is the filename without its extension and without one leading `discuss-`, `research-`, `draft-`, `spec-`, `pickup-` or `marketing-` prefix, hyphens as spaces, each word capitalised. A same-basename `.md` and `.html` pair in one folder lists as two notes; the page tags the `.html` one.
+- **Response.**
+
+  ```json
+  {
+    "notes": [
+      { "name": "x.md", "title": "X", "path": "operator/notes/topic/x.md",
+        "root": "operator/notes", "folder": "topic", "modified": "2026-01-02T03:04:05.000Z" }
+    ],
+    "notesDir": "present",
+    "notesDirPath": "operator/notes",
+    "roots": [
+      { "path": "operator/notes", "state": "present", "count": 1 },
+      { "path": "agents/<paName>/workspace/notes", "state": "missing", "count": 0 }
+    ]
+  }
+  ```
+
+  `notes` is one list, newest `modified` (file mtime) first across all roots, ties broken by `path` ascending. `path` is repo-relative, the value `viewer.html?file=` takes. `root` is the note's repo-relative root and `folder` is relative to that root (`''` at its top level). `notesDir` (`missing`, `empty` or `present`) and `notesDirPath` describe `operator/notes` alone. `roots` has one entry per root walked, with its own state and the count of notes listed under it. A failure is a 500 with `{ "error": "..." }`.
+- **Page.** Each row shows its root under the title when more than one root is walked, and a chip per root (with its count) filters the list. Search matches the root, the folder, the title and, for fetched notes, the first lines of the content. With no notes at all, the empty state names every root walked and its state.
+
 ## Tests
 
 ```bash

package/dist/engineering-pa-workspace/app/home.html

@@ -688,7 +688,7 @@
     var tagMatch = /^([a-z]+)-/i.exec(name);
     var tag = tagMatch ? tagMatch[1] : 'note';
     var age = fmtRelativeDate(n.modified);
-    var summary = name.replace(/\.md$/, '').replace(/^[a-z]+-/i, '').replace(/-/g, ' ');
+    var summary = name.replace(/\.(md|html)$/, '').replace(/^[a-z]+-/i, '').replace(/-/g, ' ');
     return (
       '<a class="card note-card" onclick="nav(\'/viewer.html?file=' + encodeURIComponent(n.path) + '\')">' +
         '<div class="id">' + esc((age ? age + ' · ' : '') + tag) + '</div>' +

package/dist/engineering-pa-workspace/app/notes.html

@@ -37,6 +37,14 @@
   .note-snippet { font-size: 0.7rem; color: var(--text-dim); margin-top: 0.1rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 400px; }
   .note-snippet mark { background: rgba(122,162,247,0.15); color: var(--accent); border-radius: 2px; }
   .note-meta { color: var(--text-dim); font-size: 0.68rem; white-space: nowrap; margin-left: 0.75rem; flex-shrink: 0; }
+  .note-root { font-size: 0.68rem; color: var(--text-dim); margin-top: 0.1rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 400px; }
+
+  /* Root filter: one chip per notes root walked */
+  .root-filter { display: flex; flex-wrap: wrap; gap: 0.35rem; margin-bottom: 0.75rem; }
+  .root-filter[hidden] { display: none; }
+  .root-chip { font-family: inherit; font-size: 0.7rem; padding: 0.15rem 0.55rem; border: 1px solid var(--border); border-radius: 999px; background: var(--bg-surface); color: var(--text-dim); cursor: pointer; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .root-chip:hover { border-color: var(--accent); }
+  .root-chip.active { border-color: var(--accent); color: var(--accent); }
   .badge { display: inline-block; padding: 0.08rem 0.35rem; border-radius: 3px; font-size: 0.62rem; font-weight: 600; white-space: nowrap; flex-shrink: 0; }
   .b-discuss  { background: rgba(122,162,247,0.15); color: var(--accent); }
   .b-research { background: rgba(158,206,106,0.15); color: var(--green); }
@@ -59,6 +67,8 @@
   <span class="search-count" id="search-count"></span>
 </div>
 
+<div class="root-filter" id="root-filter" hidden></div>
+
 <div id="container"><div class="empty">Loading…</div></div>
 
 <noscript><div style="padding:2rem;color:var(--text-dim);text-align:center;">Enable JavaScript to view notes.</div></noscript>
@@ -66,6 +76,9 @@
   var allNotes = [];
   var notesDirState = 'present';
   var notesDirPath = 'operator/notes';
+  // Every notes root the server walked: [{ path, state, count }].
+  var notesRoots = [];
+  var rootFilter = '';
   var noteContents = {};
   var searchTimer = null;
 
@@ -73,6 +86,8 @@
     var el = document.createElement('span'); el.textContent = s == null ? '' : String(s); return el.innerHTML;
   }
 
+  function escAttr(s) { return esc(s).replace(/"/g, '&quot;'); }
+
   function navTo(path) {
     if (window.parent && window.parent.navigate) window.parent.navigate(path);
     else window.location.href = path;
@@ -97,6 +112,35 @@
     return '';
   }
 
+  function rootStateText(r) {
+    if (r.state === 'missing') return r.path + ' (no directory)';
+    if (r.state === 'empty') return r.path + ' (empty)';
+    return r.path;
+  }
+
+  function joinOr(items) {
+    if (items.length <= 1) return items.join('');
+    return items.slice(0, -1).join(', ') + ' or ' + items[items.length - 1];
+  }
+
+  function renderRootFilter() {
+    var el = document.getElementById('root-filter');
+    if (notesRoots.length < 2) { el.hidden = true; el.innerHTML = ''; return; }
+    var html = '<button type="button" class="root-chip' + (rootFilter ? '' : ' active') + '" data-root="">All roots (' + allNotes.length + ')</button>';
+    notesRoots.forEach(function(r) {
+      html += '<button type="button" class="root-chip' + (rootFilter === r.path ? ' active' : '') + '" data-root="' + escAttr(r.path) + '" title="' + escAttr(rootStateText(r)) + '">' + esc(r.path) + ' (' + (r.count || 0) + ')</button>';
+    });
+    el.innerHTML = html;
+    el.hidden = false;
+  }
+
+  document.getElementById('root-filter').addEventListener('click', function(e) {
+    var chip = e.target.closest('.root-chip'); if (!chip) return;
+    rootFilter = chip.getAttribute('data-root') || '';
+    renderRootFilter();
+    render(document.getElementById('search').value.trim());
+  });
+
   // Simple fuzzy match: all query words must appear in target (case-insensitive)
   function fuzzyMatch(target, query) {
     if (!query) return true;
@@ -133,12 +177,13 @@
     var countEl = document.getElementById('search-count');
 
     var filtered = allNotes.filter(function(n) {
+      if (rootFilter && n.root !== rootFilter) return false;
       if (!query) return true;
       var contentSnippet = (noteContents[n.path] || '').slice(0, 200);
-      return fuzzyMatch((n.folder || '') + ' ' + n.title + ' ' + contentSnippet, query);
+      return fuzzyMatch((n.root || '') + ' ' + (n.folder || '') + ' ' + n.title + ' ' + contentSnippet, query);
     });
 
-    countEl.textContent = query ? filtered.length + ' / ' + allNotes.length : '';
+    countEl.textContent = (query || rootFilter) ? filtered.length + ' / ' + allNotes.length : '';
 
     if (filtered.length === 0) {
       // 0.1.54 (w-2026-09-21-dave-002, F7a/B3): distinguish missing vs
@@ -147,6 +192,12 @@
       var emptyMsg;
       if (query) {
         emptyMsg = 'No notes match "' + esc(query) + '".';
+      } else if (rootFilter) {
+        emptyMsg = 'No notes in ' + esc(rootFilter) + '.';
+      } else if (notesRoots.length && notesRoots.every(function(r) { return r.state === 'missing'; })) {
+        emptyMsg = 'No notes directory at ' + esc(joinOr(notesRoots.map(function(r) { return r.path; }))) + '. Create one and add a .md or .html file to see it here.';
+      } else if (notesRoots.length) {
+        emptyMsg = 'No notes yet. Looked in ' + esc(notesRoots.map(rootStateText).join(', ')) + '.';
       } else if (notesDirState === 'missing') {
         emptyMsg = 'No notes directory at ' + esc(notesDirPath) + '. Create it and add a .md file to see it here.';
       } else {
@@ -167,8 +218,10 @@
       html += '<li class="note-item" onclick="openNote(' + idx + ')">';
       html += '<div class="note-item-left"><div>';
       html += noteBadge(note.name);
+      if (/\.html$/.test(note.name)) html += ' <span class="badge b-other">html</span> ';
       if (note.folder) html += '<span class="note-folder">' + highlight(note.folder + '/', query) + '</span>';
       html += '<span class="note-title">' + highlight(note.title, query) + '</span>';
+      if (note.root && notesRoots.length > 1) html += '<div class="note-root">' + highlight(note.root, query) + '</div>';
       if (snippet) html += snippet;
       html += '</div></div>';
       html += '<span class="note-meta">' + relativeTime(note.modified) + '</span>';
@@ -202,6 +255,8 @@
       allNotes = data.notes || [];
       notesDirState = data.notesDir || 'present';
       notesDirPath = data.notesDirPath || 'operator/notes';
+      notesRoots = Array.isArray(data.roots) ? data.roots : [];
+      renderRootFilter();
       render('');
     }).catch(function(err) {
       document.getElementById('container').innerHTML = '<div class="empty">Failed to load: ' + esc(err.message) + '</div>';

package/dist/engineering-pa-workspace/src/api.mjs

@@ -1,5 +1,5 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, sep } from 'node:path';
 import { execSync, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
@@ -36,7 +36,9 @@ import {
  * @param {URL} url
  * @param {string} repoRoot  -- absolute path to the project root
  * @param {object} [deps]    -- injectable bridges (tests only). Currently:
- *                              deps.scheduler = { detect, list }.
+ *                              deps.scheduler = { detect, list },
+ *                              deps.warn = (message) => void (notes-root
+ *                              refusals; default console.warn, once each).
  * @returns {boolean}
  */
 const SERVER_STARTED_AT = new Date().toISOString();
@@ -224,20 +226,30 @@ export function handleApi(req, res, url, repoRoot, deps = {}) {
   }
 
   // GET /__api/notes
-  // 0.1.54 fix (w-2026-09-21-dave-002, F7a/B3): missing-vs-empty is
-  // now visible to the client. The 0.1.53 shape (`{notes: []}`) could
-  // not distinguish "no notes directory on disk" from "directory
-  // exists and holds zero .md files"; the Notes page said "you have
-  // no notes" for both. `notesDir` carries `missing` / `empty` /
-  // `present`, and the page now says "no notes directory at
-  // operator/notes" when the scaffold seam has not run.
+  // The notes index across every notes root (see resolveNotesRoots):
+  //   {
+  //     notes: [{ name, title, path, root, folder, modified }],
+  //     notesDir: 'missing' | 'empty' | 'present',
+  //     notesDirPath: 'operator/notes',
+  //     roots: [{ path, state: 'missing' | 'empty' | 'present', count }],
+  //   }
+  // `notes` is one list, newest `modified` first across all roots, ties
+  // broken by `path` ascending. `path` is repo-relative (what
+  // viewer.html?file= takes), `root` is the note's repo-relative root and
+  // `folder` is relative to that root ('' at its top level). `notesDir`
+  // and `notesDirPath` describe operator/notes alone, so a page that
+  // predates `roots` keeps its missing-versus-empty message. `roots`
+  // lists each root walked, in walk order, with the state and count of
+  // the notes listed under it. A throw is a 500 with `{ error }`.
   if (method === 'GET' && pathname === '/__api/notes') {
     try {
-      const walked = walkNotes(repoRoot);
+      const walked = walkNotes(repoRoot, { warn: deps.warn });
+      const canonical = walked.roots[0];
       sendJson(res, 200, {
         notes: walked.notes,
-        notesDir: walked.state,
-        notesDirPath: 'operator/notes',
+        notesDir: canonical.state,
+        notesDirPath: canonical.path,
+        roots: walked.roots,
       });
     } catch (err) {
       sendJson(res, 500, { error: err.message });
@@ -841,46 +853,152 @@ function walkWork(repoRoot) {
   return items;
 }
 
-function walkNotes(repoRoot) {
-  const notesDir = join(repoRoot, 'operator', 'notes');
-  if (!existsSync(notesDir)) return { notes: [], state: 'missing' };
-  // Recursive: notes written into subfolders (operator/notes/<topic>/x.md)
-  // are listed too, carrying `folder` relative to operator/notes ('' at
-  // the top level). assets/ holds images and attachments, never notes.
+// Notes roots, in walk order:
+//   1. operator/notes, the instance's canonical notes directory (the
+//      scaffold creates it), always first;
+//   2. agents/<paName>/workspace/notes, where the running PA writes its
+//      session notes beside its status board (paName from
+//      resolveAgentName, the same resolution the status board uses);
+//   3. each repo-relative path in preferences `notesRoots` (an array of
+//      strings), in the order given.
+// Discovery covers the resolved PA only, not every agents/* folder: a
+// second agent's notes, or any other notes folder, need a `notesRoots`
+// entry. A configured root that is not a non-empty string, names the repo
+// root itself, or resolves outside the repo (by path or through a
+// symlink) is refused: logged and never walked. A root named twice is
+// walked once.
+const CANONICAL_NOTES_ROOT = 'operator/notes';
+const NOTES_ROOTS_PREFERENCE = 'notesRoots';
+// Every root follows the same rules: any depth, a top-level assets/
+// skipped (images and attachments, never notes), .md and .html accepted
+// (the viewer renders .md and serves .html as is). Nothing inside a file
+// is read: the title comes from the filename.
+const NOTE_FILE_RE = /\.(md|html)$/;
+const NOTE_TITLE_PREFIXES = ['discuss-', 'research-', 'draft-', 'spec-', 'pickup-', 'marketing-'];
+
+const warnedNotesRoots = new Set();
+function warnNotesRootOnce(repoRoot, message) {
+  const key = repoRoot + '\0' + message;
+  if (warnedNotesRoots.has(key)) return;
+  warnedNotesRoots.add(key);
+  console.warn('[workspace] ' + message);
+}
+
+function isOutsideRel(rel) {
+  return rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel);
+}
+
+function normaliseNotesRoot(repoRoot, raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return { error: 'not a non-empty string' };
+  const abs = resolve(repoRoot, raw.trim());
+  const rel = relative(repoRoot, abs);
+  if (rel === '') return { error: 'names the repo root itself' };
+  if (isOutsideRel(rel)) return { error: 'resolves outside the repo' };
+  if (existsSync(abs)) {
+    let realRel = null;
+    try { realRel = relative(realpathSync(repoRoot), realpathSync(abs)); } catch { realRel = null; }
+    if (realRel !== null && (realRel === '' || isOutsideRel(realRel))) {
+      return { error: 'resolves outside the repo through a symlink' };
+    }
+  }
+  return { path: rel.split(sep).join('/') };
+}
+
+function resolveNotesRoots(repoRoot, opts = {}) {
+  const warn = typeof opts.warn === 'function'
+    ? opts.warn
+    : function (message) { warnNotesRootOnce(repoRoot, message); };
+  const roots = [CANONICAL_NOTES_ROOT];
+  const paName = resolveAgentName(repoRoot);
+  if (isValidAgentName(paName)) {
+    roots.push('agents/' + paName + '/workspace/notes');
+  } else {
+    warn('notes: paName ' + JSON.stringify(paName) + ' is not a valid agent folder name; its workspace notes are not walked');
+  }
+  let prefs = null;
+  try { prefs = readPreferencesSync(repoRoot); } catch { prefs = null; }
+  const configured = prefs ? prefs[NOTES_ROOTS_PREFERENCE] : undefined;
+  if (configured !== undefined && configured !== null) {
+    if (!Array.isArray(configured)) {
+      warn(NOTES_ROOTS_PREFERENCE + ': expected an array of repo-relative paths; ignored');
+    } else {
+      for (const raw of configured) {
+        const r = normaliseNotesRoot(repoRoot, raw);
+        if (r.error) {
+          warn(NOTES_ROOTS_PREFERENCE + ': refused ' + JSON.stringify(raw) + ' (' + r.error + '); not walked');
+          continue;
+        }
+        roots.push(r.path);
+      }
+    }
+  }
+  return roots.filter(function (r, i) { return roots.indexOf(r) === i; });
+}
+
+function noteTitle(name) {
+  let title = name.replace(NOTE_FILE_RE, '');
+  for (const prefix of NOTE_TITLE_PREFIXES) {
+    if (title.startsWith(prefix)) { title = title.slice(prefix.length); break; }
+  }
+  return title.replace(/-/g, ' ').replace(/\b\w/g, function (c) { return c.toUpperCase(); });
+}
+
+// Note files under one root: [{ name, folder, relPath }], relPath and
+// folder relative to the root ('' folder at its top level).
+function listNoteFiles(absRoot) {
   const files = [];
   (function walk(rel) {
-    const entries = readdirSync(join(notesDir, rel), { withFileTypes: true });
+    const entries = readdirSync(rel ? join(absRoot, rel) : absRoot, { withFileTypes: true });
     for (const e of entries) {
       const relPath = rel ? rel + '/' + e.name : e.name;
       if (e.isDirectory()) {
         if (relPath !== 'assets') walk(relPath);
-      } else if (e.name.endsWith('.md')) {
+      } else if (NOTE_FILE_RE.test(e.name)) {
         files.push({ name: e.name, folder: rel, relPath: relPath });
       }
     }
   })('');
-  var prefixes = ['discuss-', 'research-', 'draft-', 'spec-', 'pickup-', 'marketing-'];
-  var notes = [];
-  for (var i = 0; i < files.length; i++) {
-    var name = files[i].name;
-    var absPath = join(notesDir, files[i].relPath);
-    var st;
-    try { st = statSync(absPath); } catch(e) { continue; }
-    var title = name.replace(/\.md$/, '');
-    for (var j = 0; j < prefixes.length; j++) {
-      if (title.startsWith(prefixes[j])) { title = title.slice(prefixes[j].length); break; }
+  return files;
+}
+
+function walkNotes(repoRoot, opts = {}) {
+  const notes = [];
+  const roots = [];
+  const listed = new Set();
+  for (const rootPath of resolveNotesRoots(repoRoot, opts)) {
+    const absRoot = join(repoRoot, ...rootPath.split('/'));
+    let isDir = false;
+    try { isDir = statSync(absRoot).isDirectory(); } catch { isDir = false; }
+    if (!isDir) {
+      roots.push({ path: rootPath, state: 'missing', count: 0 });
+      continue;
     }
-    title = title.replace(/-/g, ' ').replace(/\b\w/g, function(c) { return c.toUpperCase(); });
-    notes.push({
-      name: name,
-      title: title,
-      path: 'operator/notes/' + files[i].relPath,
-      folder: files[i].folder,
-      modified: st.mtime.toISOString(),
-    });
+    let count = 0;
+    for (const f of listNoteFiles(absRoot)) {
+      const path = rootPath + '/' + f.relPath;
+      // A root nested inside an earlier root: its notes stay with the
+      // earlier root, listed once.
+      if (listed.has(path)) continue;
+      let st;
+      try { st = statSync(join(absRoot, f.relPath)); } catch { continue; }
+      listed.add(path);
+      notes.push({
+        name: f.name,
+        title: noteTitle(f.name),
+        path: path,
+        root: rootPath,
+        folder: f.folder,
+        modified: st.mtime.toISOString(),
+      });
+      count++;
+    }
+    roots.push({ path: rootPath, state: count === 0 ? 'empty' : 'present', count: count });
   }
-  notes.sort(function(a, b) { return b.modified.localeCompare(a.modified); });
-  return { notes: notes, state: notes.length === 0 ? 'empty' : 'present' };
+  notes.sort(function (a, b) {
+    if (a.modified !== b.modified) return a.modified < b.modified ? 1 : -1;
+    return a.path < b.path ? -1 : (a.path > b.path ? 1 : 0);
+  });
+  return { notes: notes, roots: roots };
 }
 
 function walkDocuments(dir, repoRoot, result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "description": "Digital Operator PA: single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",