@mnstry/atelier 0.2.0-alpha.10 → 0.2.0-alpha.12

package/src/projection/obsidian/publication/transport.mjs

@@ -1,9 +1,12 @@
 import { execFile, execFileSync } from 'node:child_process'
+import { readlinkSync } from 'node:fs'
+import path from 'node:path'
 import { POLICY_SETTINGS_PATH, buildEvalCode, createInProcessHost, runInProcess, validatePayload } from './bridge-script.mjs'
+import { obsidianUserDataDir, readObsidianSettings, vaultRoute } from './vault-list.mjs'
 
 // Editor coordination adapter.
 //
-//   adapter.probe({ vaultRoot })  -> { state: 'coordinated' | 'absent' | 'uncoordinated', reason }
+//   adapter.probe({ vaultRoot })  -> { state: 'coordinated' | 'absent' | 'uncoordinated', reason, code? }
 //   adapter.inspect(payload)      -> reply          read-only, may retry
 //   adapter.collect(payload)      -> reply          read-only, may retry
 //   adapter.publish(payload)      -> reply          sent at most once
@@ -24,11 +27,28 @@ export class TransportTimeout extends Error {
   }
 }
 
+// A call that no route can take: the app's list says no call reaches only
+// this vault. `code` says why; the call is never made.
+export class RouteRefusal extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`)
+    this.name = 'RouteRefusal'
+    this.code = code
+  }
+}
+
 const READ_RETRIES = 2
 
-export function createEditorAdapter({ call, processProbe, kind = 'custom' }) {
+// `qualification`, when given, is the app qualification this adapter was
+// constructed under (`qualifyApp`). An adapter qualified while no app ran was
+// never shown a version, so it never coordinates with an app found running
+// later, whose version nobody checked: it is `uncoordinated` until an adapter
+// qualified with a checked version replaces it. Without a qualification the
+// adapter coordinates as before.
+export function createEditorAdapter({ call, processProbe, kind = 'custom', qualification }) {
   if (typeof call !== 'function') throw new TypeError('createEditorAdapter needs a call function')
   if (typeof processProbe !== 'function') throw new TypeError('createEditorAdapter needs a processProbe function')
+  const versionUnchecked = qualification !== undefined && qualification?.versionChecked !== true
   const retries = []
   let tail = Promise.resolve()
   const serialized = (operation) => {
@@ -62,18 +82,21 @@ export function createEditorAdapter({ call, processProbe, kind = 'custom' }) {
     }),
     // Path selection. `absent` is returned only when the process probe says,
     // positively, that no Obsidian is running. A running or unknowable app
-    // that does not answer for this exact vault is `uncoordinated`.
+    // that does not answer for this exact vault is `uncoordinated`, and so is
+    // any app while this adapter's qualification checked no version. When no
+    // call could be routed to only this vault, `code` names the route's refusal.
     probe: ({ vaultRoot }) => serialized(async () => {
       let processes
       try { processes = await processProbe() } catch { processes = 'unknown' }
       if (processes === 'absent') return { state: 'absent', reason: 'no Obsidian process is running' }
+      if (versionUnchecked) return { state: 'uncoordinated', reason: 'app-version-unchecked: an Obsidian process may be running, and this adapter was qualified while none ran, so its version was never checked' }
       try {
         const reply = await readOnly({ op: 'inspect', vaultRoot, path: POLICY_SETTINGS_PATH })
         // `path-unsafe` for the probe path still proves the app answered for this vault; the settings unit reports the path.
         if (['inspected', 'path-unsafe'].includes(reply.status) && reply.vaultBasePath === vaultRoot) return { state: 'coordinated', reason: 'the app answered for this vault' }
         return { state: 'uncoordinated', reason: reply.status === 'vault-mismatch' ? 'the app answered for another vault' : `the app answered ${reply.status}` }
       } catch (error) {
-        return { state: 'uncoordinated', reason: `an Obsidian process may be running and the bridge did not answer: ${String(error.message || error).slice(0, 200)}` }
+        return { state: 'uncoordinated', ...(error instanceof RouteRefusal ? { code: error.code } : {}), reason: `an Obsidian process may be running and the bridge did not answer: ${String(error.message || error).slice(0, 200)}` }
       }
     }),
   }
@@ -101,13 +124,55 @@ export function defaultCliPath(platform = process.platform) {
   return 'obsidian-cli'
 }
 
+// A directory that is no vault, for a call that must not choose one by where it runs.
+export const NEUTRAL_DIRECTORY = (() => { try { return path.parse(process.cwd()).root } catch { return path.sep } })()
+
+// The working directory and leading arguments of a call that goes where a
+// `vaultRoute` says: into the vault's folder, or naming the vault's id first
+// from a directory that is no vault (`neutral`), or, for any other route, from
+// that directory naming no vault.
+export function routedCall(route, neutral = NEUTRAL_DIRECTORY) {
+  if (route?.how === 'folder') return { cwd: route.cwd, args: [] }
+  if (route?.how === 'id') return { cwd: neutral, args: [`vault=${route.id}`] }
+  return { cwd: neutral, args: [] }
+}
+
+// Which window a publication call reaches. The app answers a command in the
+// window of the vault its list routes the call to (see vault-list.mjs),
+// opening that vault first when it is closed, and otherwise in the vault
+// window that had focus last, which may be any vault the person uses. While
+// the app lists this vault as open, a call therefore runs in its folder, or,
+// when a vault listed at a folder above it would take a call run there, names
+// its id; when neither reaches only this vault, no call is made (the error
+// says `vault-inside-another-vault`), nor when the app has the vault open in
+// more than one window, one per entry of its list that names this folder
+// (`vault-open-in-several-windows`): a call would coordinate with one of them
+// only. Otherwise a call runs in a directory
+// that is no vault and names none: a closed vault is never reopened by
+// maintenance, no other vault is reached through this one's folder, and the
+// working directory of whoever started the service never picks a vault. The
+// script still checks that it answered for exactly this vault.
+export function publicationRoute({ env = process.env, platform = process.platform } = {}) {
+  const userDataDir = obsidianUserDataDir({ platform, env })
+  return (payload) => {
+    const settings = readObsidianSettings({ userDataDir })
+    const route = settings.ok ? vaultRoute({ vaults: settings.vaults, vaultRoot: payload.vaultRoot, open: true }) : { how: 'unlisted' }
+    if (route.how === 'ambiguous') throw new RouteRefusal('vault-inside-another-vault', 'Obsidian lists a vault at a folder above this one, and no call reaches only this vault; no call was made')
+    if (route.how === 'duplicated') throw new RouteRefusal('vault-open-in-several-windows', `Obsidian has this vault open in ${route.entries.length} windows (${route.entries.map((entry) => entry.id).join(', ')}), and a call reaches one of them only; no call was made`)
+    return routedCall(route)
+  }
+}
+
 // The CLI reaches the app through a socket under $HOME, so `env` selects the
 // app instance. It is passed explicitly and never edited here. A call that
 // outlives its timeout is killed with SIGKILL: the CLI ignores SIGTERM while
-// it waits on the app.
-export function createObsidianCliCall({ cliPath = defaultCliPath(), env = process.env, timeoutMs = 20000 } = {}) {
+// it waits on the app. `route(payload)` says where a call runs and what it
+// names first ({ cwd, args }); a route that throws makes no call.
+export function createObsidianCliCall({ cliPath = defaultCliPath(), env = process.env, timeoutMs = 20000, route = () => routedCall(null) } = {}) {
   return (payload) => new Promise((resolve, reject) => {
-    execFile(cliPath, ['eval', `code=${buildEvalCode(payload)}`], { env, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+    let where
+    try { where = route(payload) } catch (error) { return reject(error) }
+    execFile(cliPath, [...where.args, 'eval', `code=${buildEvalCode(payload)}`], { env, cwd: where.cwd, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
       if (error) return reject(error.killed ? new TransportTimeout(`CLI call timed out: ${payload.op}`) : new Error(`CLI call failed: ${String(error.message).slice(0, 300)}`))
       const out = stdout || stderr || ''
       const start = out.indexOf('=> ')
@@ -127,13 +192,48 @@ export function createObsidianCliCall({ cliPath = defaultCliPath(), env = proces
 //          directory: a moved or renamed bundle still counts, and so does a
 //          process whose path ps cannot read and names by its short name.
 //   Linux  `obsidian`, the executable of the .deb, snap, AppImage and Flatpak
-//          builds. A distribution that runs the app under a system Electron
-//          shows only `electron`, and which app it hosts is not known.
+//          builds, by name or, for a name that is not recognised, by the
+//          executable it resolves to. A distribution that runs the app under
+//          a system Electron shows only `electron`, and which app it hosts is
+//          not known.
 //
 // The command-line tool is a client of the app, not the app: counting it would
 // make every call this package makes through it look like a running app.
 const APP_EXECUTABLE = Object.freeze({ darwin: /^obsidian(?: helper\b.*)?$/i, linux: /^obsidian$/i })
 const ELECTRON_HOST = /^\.?electron(?:\d+|-wrap.*)?$/i
+// A `ps` that has not answered by then is killed, and the reading is unknown.
+const PS_TIMEOUT_MS = 5000
+// A process that exited since the table was read, or whose executable this
+// user may not read: another user's process, or one of this user's that hides
+// it from tracing (ssh-agent, a sandboxed renderer). Such a process is judged
+// by its name alone.
+const EXECUTABLE_UNREADABLE = new Set(['ENOENT', 'ESRCH', 'EACCES', 'EPERM'])
+
+const baseName = (text) => text.slice(text.lastIndexOf('/') + 1)
+const readProcessExecutable = (pid) => readlinkSync(`/proc/${pid}/exe`)
+
+// Linux names a process after the path it was started through, so an app
+// started through a differently named link or launcher shows another name.
+// The executable `/proc/<pid>/exe` resolves to does not change with the name.
+// Any failure other than the expected ones is unknown, and so is a table in
+// which no executable could be resolved at all: without `/proc`, nothing
+// below the names can be established.
+function resolveLinuxExecutables(rows, readExe) {
+  let resolved = 0
+  let unknown = false
+  for (const { pid } of rows) {
+    let target
+    try { target = String(readExe(pid)) } catch (error) {
+      if (!EXECUTABLE_UNREADABLE.has(error?.code)) unknown = true
+      continue
+    }
+    resolved += 1
+    const name = baseName(target.replace(/ \(deleted\)$/, ''))
+    if (APP_EXECUTABLE.linux.test(name)) return 'running'
+    if (ELECTRON_HOST.test(name)) unknown = true
+  }
+  return unknown || resolved === 0 ? 'unknown' : 'absent'
+}
 
 // Default process probe: 'absent' only when the process table was read and
 // holds no Obsidian. Limits: it sees this machine's processes as this user
@@ -141,20 +241,27 @@ const ELECTRON_HOST = /^\.?electron(?:\d+|-wrap.*)?$/i
 // vault through a shared or synchronized folder, an app packaged under another
 // executable name, or an app that starts after the probe. Anything it cannot
 // establish is 'unknown', which the adapter treats as a running app: an empty
-// table, a failed read, and on Linux a system Electron process.
-export function defaultObsidianProcessProbe({ platform = process.platform, run = execFileSync } = {}) {
+// table, a failed or slow read, and on Linux a system Electron process or an
+// executable that cannot be resolved for an unexpected reason.
+export function defaultObsidianProcessProbe({ platform = process.platform, run = execFileSync, readExe = readProcessExecutable } = {}) {
   if (!Object.hasOwn(APP_EXECUTABLE, platform)) return 'unknown'
+  const linux = platform === 'linux'
   try {
-    const table = run('/bin/ps', ['-A', '-o', 'comm='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 })
+    const table = run('/bin/ps', ['-A', '-o', linux ? 'pid=,comm=' : 'comm='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024, timeout: PS_TIMEOUT_MS, killSignal: 'SIGKILL' })
     if (typeof table !== 'string' || table.trim() === '') return 'unknown'
-    const names = table.split('\n').map((line) => line.trim()).filter((line) => line !== '').map((line) => line.slice(line.lastIndexOf('/') + 1))
-    if (names.some((name) => APP_EXECUTABLE[platform].test(name))) return 'running'
-    return platform === 'linux' && names.some((name) => ELECTRON_HOST.test(name)) ? 'unknown' : 'absent'
+    const rows = table.split('\n').map((line) => line.trim()).filter((line) => line !== '').map((line) => {
+      const match = linux ? /^(\d+)\s+(.*)$/.exec(line) : null
+      return match ? { pid: Number(match[1]), comm: match[2] } : { pid: null, comm: line }
+    })
+    if (rows.some((row) => APP_EXECUTABLE[platform].test(baseName(row.comm)))) return 'running'
+    if (!linux) return 'absent'
+    if (rows.some((row) => row.pid === null || ELECTRON_HOST.test(baseName(row.comm)))) return 'unknown'
+    return resolveLinuxExecutables(rows, readExe)
   } catch {
     return 'unknown'
   }
 }
 
-export function createObsidianCliAdapter({ cliPath, env, timeoutMs, processProbe = () => defaultObsidianProcessProbe() } = {}) {
-  return createEditorAdapter({ call: createObsidianCliCall({ cliPath, env, timeoutMs }), processProbe, kind: 'obsidian-cli' })
+export function createObsidianCliAdapter({ cliPath, env = process.env, timeoutMs, processProbe = () => defaultObsidianProcessProbe(), qualification, route = publicationRoute({ env }) } = {}) {
+  return createEditorAdapter({ call: createObsidianCliCall({ cliPath, env, timeoutMs, route }), processProbe, kind: 'obsidian-cli', qualification })
 }

package/src/projection/obsidian/publication/vault-list.mjs

@@ -0,0 +1,199 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { openRegularFileNoFollow, realPathAsStored } from '../../../project/private-state.mjs'
+
+// Obsidian's own list of the folders it knows as vaults, read only.
+//
+// The app keeps the list in `obsidian.json` in its user-data directory, as
+// `{ "vaults": { "<id>": { "path", "ts", "open"? } }, ...other settings }`.
+// It reads the file when it starts and rewrites the whole file whenever the
+// list changes. `open` is true while a window of that vault is open, and stays
+// true for the vaults that were open when the app quit, which it reopens on its
+// next start. `obsidian://open?path=` finds a vault only through this list.
+//
+// Nothing here writes the file. The one write Atelier makes to it is in
+// src/runtime/obsidian/app-registration.mjs, and only while no Obsidian runs.
+//
+// The list also decides which window answers a command-line call (1.13.7): a
+// first argument `vault=<value>` names the first listed vault whose id is the
+// value, or whose folder's name is the value in any letter case; without one,
+// the first listed vault whose folder is the tool's working directory or
+// contains it takes the call, the folders compared as written; failing both,
+// the vault window that had focus last. The first in list order, not the
+// deepest: a vault listed at a folder above another one takes the calls run
+// inside it. The app opens a vault that takes a call when it is closed.
+
+export const OBSIDIAN_SETTINGS_FILE = 'obsidian.json'
+// Far more than a list of vaults and a few settings; a larger file is not read.
+export const MAX_OBSIDIAN_SETTINGS_BYTES = 4 * 1024 * 1024
+
+// The user-data directory of the app for this account: Electron's, for an app
+// named `obsidian`. Null where it is not known (another platform, no HOME). A
+// Flatpak or snap build keeps its own elsewhere and is not found here (see
+// obsidianSandboxedBuild). Both known platforms have POSIX paths, whatever
+// platform asks.
+export function obsidianUserDataDir({ platform = process.platform, env = process.env } = {}) {
+  const home = env.HOME
+  if (platform !== 'darwin' && platform !== 'linux') return null
+  if (typeof home !== 'string' || !path.posix.isAbsolute(home)) return null
+  if (platform === 'darwin') return path.posix.join(home, 'Library', 'Application Support', 'obsidian')
+  const config = typeof env.XDG_CONFIG_HOME === 'string' && path.posix.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.posix.join(home, '.config')
+  return path.posix.join(config, 'obsidian')
+}
+
+// A Flatpak or snap build of Obsidian on Linux keeps its user-data directory
+// inside its sandbox (`~/.var/app/md.obsidian.Obsidian/config/obsidian`,
+// `~/snap/obsidian/current/.config/obsidian`), where Atelier does not write,
+// and reads no file outside it. Which build this account uses: the one whose
+// vault list was written last, since every build rewrites its own whenever a
+// vault window opens or closes ('flatpak', 'snap', or null for the native
+// build); only when no build wrote one, a Flatpak or snap installation, or a
+// Flatpak or snap left by one. Null on any other platform. `exists` answers
+// whether a path exists, `modified` when a file was last written (or null).
+const modifiedAt = (file) => { try { return fs.statSync(file).mtimeMs } catch { return null } }
+export function obsidianSandboxedBuild({ platform = process.platform, env = process.env, exists = fs.existsSync, modified = modifiedAt } = {}) {
+  if (platform !== 'linux') return null
+  const home = typeof env.HOME === 'string' && path.posix.isAbsolute(env.HOME) ? env.HOME : null
+  const under = (...parts) => (home === null ? [] : [path.posix.join(home, ...parts)])
+  const native = obsidianUserDataDir({ platform, env })
+  const lists = [
+    [null, native === null ? [] : [path.posix.join(native, OBSIDIAN_SETTINGS_FILE)]],
+    ['flatpak', under('.var', 'app', 'md.obsidian.Obsidian', 'config', 'obsidian', OBSIDIAN_SETTINGS_FILE)],
+    ['snap', under('snap', 'obsidian', 'current', '.config', 'obsidian', OBSIDIAN_SETTINGS_FILE)],
+  ].flatMap(([build, files]) => files.map((file) => { let at; try { at = modified(file) } catch { at = null } return { build, at } })).filter(({ at }) => typeof at === 'number')
+  if (lists.length > 0) return lists.reduce((latest, list) => (list.at > latest.at ? list : latest)).build
+  const found = (paths) => paths.some((candidate) => { try { return exists(candidate) } catch { return false } })
+  if (found([...under('.var', 'app', 'md.obsidian.Obsidian'), ...under('.local', 'share', 'flatpak', 'app', 'md.obsidian.Obsidian'), '/var/lib/flatpak/app/md.obsidian.Obsidian'])) return 'flatpak'
+  if (found([...under('snap', 'obsidian'), '/snap/obsidian', '/var/lib/snapd/snap/obsidian'])) return 'snap'
+  return null
+}
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+// The real path as stored (realPathAsStored): what the operating system reports as a working directory.
+const realOrResolved = (target) => { try { return realPathAsStored(target) } catch { return path.resolve(target) } }
+const listedFolders = (vaults) => (isPlainObject(vaults) ? Object.entries(vaults).filter(([, entry]) => isPlainObject(entry) && typeof entry.path === 'string' && path.isAbsolute(entry.path)) : [])
+
+// A folder the list names, against a vault root spelled as given (`spelled`)
+// and as its real path (`target`). Compared as written first; the real path of
+// a listed folder is read only when its last component is the vault root's,
+// as it is for the root reached through a linked parent. So a vault on a
+// mount that does not answer is never waited on; a link to the vault root
+// under another name is not recognised.
+const namesFolder = (entryPath, { spelled, target }) => {
+  const written = path.resolve(entryPath)
+  if (written === spelled || written === target) return true
+  return path.basename(written) === path.basename(target) && realOrResolved(entryPath) === target
+}
+const rootOf = (vaultRoot) => ({ spelled: path.resolve(vaultRoot), target: realOrResolved(vaultRoot) })
+
+// The listed entries (listedFolders) whose folder is this vault root (see
+// namesFolder), in list order. One folder can be listed more than once, under
+// another letter case or through a link, say.
+const entriesOf = (listed, root) => listed.filter(([, entry]) => namesFolder(entry.path, root))
+
+// The entry of the app's vault map whose folder is this vault root (see
+// namesFolder), one the app lists open first; null when there is none. `vaults`
+// is the map as the app keeps it, from its file or from the app itself.
+export function findVaultEntry(vaults, vaultRoot) {
+  if (!isPlainObject(vaults) || typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return null
+  const entries = entriesOf(listedFolders(vaults), rootOf(vaultRoot))
+  const found = entries.find(([, entry]) => entry.open === true) ?? entries[0]
+  return found === undefined ? null : { id: found[0], path: found[1].path, open: found[1].open === true }
+}
+
+const refused = (code, message) => ({ ok: false, code, message })
+const currentUid = () => (typeof process.getuid === 'function' ? process.getuid() : null)
+
+// Reads the settings file without following a link and without writing:
+// { ok: true, file, document, vaults, bytes, mode } or a typed refusal
+// { ok: false, code, message }. The user-data directory and the file must be
+// this user's own, a real directory and a regular file; the file must be a
+// JSON object whose `vaults`, when present, is an object. A missing directory
+// or file means Obsidian has not run on this account.
+export function readObsidianSettings({ userDataDir, uid = currentUid() } = {}) {
+  if (typeof userDataDir !== 'string' || !path.isAbsolute(userDataDir)) return refused('obsidian-settings-location-unknown', 'where Obsidian keeps its settings on this system is not known')
+  const owned = (stat) => uid === null || stat.uid === uid
+  let directory
+  try { directory = fs.lstatSync(userDataDir) } catch (error) {
+    if (error.code === 'ENOENT') return refused('obsidian-settings-missing', 'Obsidian has no settings directory on this account; it has not run here')
+    return refused('obsidian-settings-unreadable', 'the Obsidian settings directory cannot be read')
+  }
+  if (directory.isSymbolicLink() || !directory.isDirectory()) return refused('obsidian-settings-unsafe', 'the Obsidian settings directory is a link or not a directory')
+  if (!owned(directory)) return refused('obsidian-settings-not-owned', 'the Obsidian settings directory belongs to another user')
+  const file = path.join(userDataDir, OBSIDIAN_SETTINGS_FILE)
+  let leaf
+  try { leaf = fs.lstatSync(file) } catch (error) {
+    if (error.code === 'ENOENT') return refused('obsidian-settings-missing', 'Obsidian has no settings file on this account; it has not run here')
+    return refused('obsidian-settings-unreadable', 'the Obsidian settings file cannot be read')
+  }
+  if (leaf.isSymbolicLink() || !leaf.isFile()) return refused('obsidian-settings-unsafe', 'the Obsidian settings file is a link or not a regular file')
+  if (!owned(leaf)) return refused('obsidian-settings-not-owned', 'the Obsidian settings file belongs to another user')
+  if (leaf.size > MAX_OBSIDIAN_SETTINGS_BYTES) return refused('obsidian-settings-unreadable', 'the Obsidian settings file is larger than a settings file can be')
+  let bytes
+  let descriptor
+  try {
+    descriptor = openRegularFileNoFollow(file)
+    const opened = fs.fstatSync(descriptor)
+    if (!owned(opened)) return refused('obsidian-settings-not-owned', 'the Obsidian settings file belongs to another user')
+    bytes = fs.readFileSync(descriptor)
+  } catch {
+    return refused('obsidian-settings-unreadable', 'the Obsidian settings file cannot be read')
+  } finally {
+    if (descriptor !== undefined) try { fs.closeSync(descriptor) } catch { /* read already, or refused */ }
+  }
+  let document
+  try { document = JSON.parse(bytes.toString('utf8')) } catch { return refused('obsidian-settings-unreadable', 'the Obsidian settings file is not JSON') }
+  if (!isPlainObject(document)) return refused('obsidian-settings-not-object', 'the Obsidian settings file is not a JSON object')
+  if (document.vaults !== undefined && !isPlainObject(document.vaults)) return refused('obsidian-settings-not-object', 'the vault list in the Obsidian settings file is not an object')
+  return { ok: true, file, document, vaults: document.vaults ?? {}, bytes, mode: leaf.mode & 0o777, links: leaf.nlink }
+}
+
+// Where a command-line call about this vault reaches the app, predicted from
+// the app's list as the app routes a call (see above):
+//
+//   { how: 'id', id }       run in a directory that is no vault, with `vault=<id>` first: the id names this vault first.
+//                           Preferred: it does not depend on how a working directory is spelled;
+//   { how: 'folder', cwd }  run in the vault's folder (its real path as stored, which the tool reports), when the id
+//                           names another vault first and the first listed vault that is or contains the folder is this one;
+//   { how: 'unlisted' }     the list has no entry for this folder (with `open`, none that the app lists open);
+//   { how: 'ambiguous' }    the id names another vault first, and a vault listed above it takes a call run in its folder;
+//   { how: 'duplicated', entries }
+//                           the list has this folder open more than once, one window per entry ({ id, path }): each
+//                           window holds the vault, and a call reaches one of them only.
+//
+// With `open`, only an entry the app lists open may take the call, so a
+// closed vault window is never reopened. Without it, so does an entry the app
+// lists open when there is one: another entry of the same folder is not opened
+// beside it.
+export function vaultRoute({ vaults, vaultRoot, open = false } = {}) {
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return { how: 'unlisted' }
+  const root = rootOf(vaultRoot)
+  const { target } = root
+  const listed = listedFolders(vaults)
+  const entries = entriesOf(listed, root)
+  const windows = entries.filter(([, entry]) => entry.open === true)
+  if (windows.length > 1) return { how: 'duplicated', entries: windows.map(([id, entry]) => ({ id, path: entry.path })) }
+  const own = open || windows.length > 0 ? windows : entries
+  if (own.length === 0) return { how: 'unlisted' }
+  const takes = ([id]) => own.some(([ownId]) => ownId === id)
+  const byName = (value) => listed.find(([id, entry]) => id === value || path.basename(entry.path).toUpperCase() === value.toUpperCase())
+  const named = own.find(([id]) => byName(id)?.[0] === id)
+  if (named !== undefined) return { how: 'id', id: named[0] }
+  const byFolder = listed.find(([, entry]) => { const folder = path.resolve(entry.path); return target === folder || target.startsWith(folder + path.sep) })
+  return byFolder !== undefined && takes(byFolder) ? { how: 'folder', cwd: target } : { how: 'ambiguous' }
+}
+
+// The listed vaults whose folder contains this vault root, as written, against
+// the root as given and as its real path: the app would show this vault's
+// notes in their windows too, and a call run in this vault's folder may reach
+// them. No vault is added inside another one. No listed folder's real path is
+// read, so a vault above the root only through a link is not found.
+export function enclosingVaults({ vaults, vaultRoot } = {}) {
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return []
+  const { spelled, target } = rootOf(vaultRoot)
+  const inside = (folder, root) => folder !== root && root.startsWith(folder.endsWith(path.sep) ? folder : folder + path.sep)
+  return listedFolders(vaults).filter(([, entry]) => {
+    const folder = path.resolve(entry.path)
+    return !namesFolder(entry.path, { spelled, target }) && (inside(folder, target) || inside(folder, spelled))
+  }).map(([id, entry]) => ({ id, path: entry.path }))
+}

package/src/projection/obsidian/recovery/restart.mjs

@@ -300,6 +300,8 @@ export function recoverPublications({ store, clock = () => new Date() }) {
 // Digests this view has published since its trusted manifest was committed,
 // by journals that did not reach a commit. They are valid bases: without them
 // a note published by an interrupted run would look like an outside edit.
+// Settings and Atelier's plugin files are planned from the disk, never from a
+// base, so they have no place here.
 export function publishedSinceCommit({ store }) {
   const pointer = store.readCurrent()
   const ledger = new Map()
@@ -308,7 +310,7 @@ export function publishedSinceCommit({ store }) {
     if (document.state === 'committed' || document.expectedGeneration !== (pointer?.generationId ?? null)) continue
     for (const entry of document.entries) {
       const detail = journalDetail(entry)
-      if (entry.step !== 'conditional-update' || entry.outcome !== 'ok' || detail.kind === 'settings') continue
+      if (entry.step !== 'conditional-update' || entry.outcome !== 'ok' || detail.kind === 'settings' || detail.kind === 'plugin') continue
       ledger.set(entry.notePath, detail.op === 'remove' ? null : entry.afterDigest)
     }
   }

package/src/projection/obsidian/recovery/store.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { acquirePrivateLock, publishPrivateFile } from '../../../project/durable-state.mjs'
 import { checkManagedRoots } from '../../../project/file-class.mjs'
-import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../../project/private-state.mjs'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow, realPathAsStored } from '../../../project/private-state.mjs'
 
 // Private per-workspace state for one Obsidian view:
 //
@@ -128,11 +128,14 @@ export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vault
   const guard = checkManagedRoots({ managedRoots: [workspaceRoot, ...(vaultRoot === undefined ? [] : [vaultRoot])], repositoryRoots })
   if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals })
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
-  const root = fs.realpathSync(workspaceRoot)
+  // Both as the file system stores them: the vault root is what the app is told, and what it compares its own
+  // working-directory spelling with.
+  const root = realPathAsStored(workspaceRoot)
   const privateDir = (...parts) => ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, ...parts), label: 'Obsidian publication state' })
   const requestedVault = vaultRoot ?? path.join(root, 'vaults', segment(scopeId))
-  fs.mkdirSync(requestedVault, { recursive: true })
-  const vault = fs.realpathSync(requestedVault)
+  // A vault this store places itself is private to this user from the start: it will hold the plugin's bearer.
+  fs.mkdirSync(requestedVault, { recursive: true, ...(vaultRoot === undefined ? { mode: 0o700 } : {}) })
+  const vault = realPathAsStored(requestedVault)
   const inside = (parent, child) => { const relative = path.relative(parent, child); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)) }
   for (const area of ['state', 'recovery', 'staging']) {
     if (inside(path.join(root, area), vault) || inside(vault, path.join(root, area))) throw new TypeError('the vault may not overlap private publication state')
@@ -149,6 +152,10 @@ export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vault
     workspaceId,
     scopeId,
     vaultRoot: vault,
+    // Placed by this store under the workspace state, rather than named by the caller, and really there: a vault path
+    // that is a link leads to a folder someone else chose, which is only looked at and never receives the bearer.
+    managedVaultRoot: vaultRoot === undefined && vault === requestedVault,
+    linkedVaultRoot: vaultRoot === undefined && vault !== requestedVault,
     journalsRoot: journals,
     lockPath: path.join(locks, `${segment(scopeId)}.lock`),
     // One publisher per vault, whichever view or workspace state it belongs to.

package/src/projection/obsidian/selection-ui/focus.mjs

@@ -3,8 +3,11 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 
 // Focus: the full vault stays on disk and the native Graph view is filtered
 // with a "Search files" query derived from the selected set. The query names
-// every selected note by its exact vault-relative path, quoted and escaped
-// the way the app's search syntax reads a quoted term, joined with OR.
+// every selected note by its exact vault-relative path, as an anchored regular
+// expression in the app's `path:/…/` search, joined with OR: a path search
+// matches substrings, and with titles as names one path can lie inside
+// another (`r/a/Plan.md` inside `qr/a/Plan.md`), so only an anchored term
+// matches exactly one note.
 //
 // Nothing here writes a file. The query and the core-Bookmark payload are
 // values a person, an agent or the acceptance procedure applies in the app;
@@ -13,7 +16,9 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 // Atelier. Whether the installed app applies the query as built is an
 // acceptance question (AP-02), not something this module can answer.
 
-export const FOCUS_QUERY_VERSION = 'obsidian-graph-search-paths/v1'
+export const FOCUS_QUERY_VERSION = 'obsidian-graph-search-paths/v2'
+// Versions a persisted focus may carry and still be read: v1 quoted each path as a substring term.
+export const FOCUS_QUERY_VERSIONS_READ = Object.freeze(['obsidian-graph-search-paths/v1', FOCUS_QUERY_VERSION])
 export const FOCUS_BOOKMARK_TYPE = 'graph'
 // The files under .obsidian/ the app's UI owns. Atelier reads none of them
 // and writes none of them; a focus is applied through the app, never by
@@ -21,14 +26,16 @@ export const FOCUS_BOOKMARK_TYPE = 'graph'
 export const UI_OWNED_SETTINGS_FILES = Object.freeze(['workspace.json', 'graph.json', 'bookmarks.json'])
 export const MAX_FOCUS_PATHS = 100000
 
-// A quoted search term: backslash and double quote are escaped; anything
-// that is not printable text cannot be typed into a search box and refuses.
+// An anchored regular-expression term: every metacharacter and the `/`
+// delimiter escaped, a space and a double quote written as hexadecimal escapes
+// so the search box neither splits nor quotes the term; anything that is not
+// printable text cannot be typed into a search box and refuses.
 export const FOCUS_QUERY_PRIMITIVES = Object.freeze({
   escape(value) {
-    return value.replace(/[\\"]/g, (character) => `\\${character}`)
+    return value.replace(/[\\^$.*+?()[\]{}|/]/g, (character) => `\\${character}`).replace(/ /g, '\\x20').replace(/"/g, '\\x22')
   },
   term(path) {
-    return `path:"${path}"`
+    return `path:/^${path}$/`
   },
   join(terms) {
     return terms.join(' OR ')

package/src/projection/obsidian/selection-ui/selection-state.mjs

@@ -6,7 +6,7 @@ import { refuse } from '../../../runtime/obsidian/errors.mjs'
 import { assertOutsideRepositories } from '../../../runtime/obsidian/machine-settings.mjs'
 import { SCOPE_MODES, assertObsidianContract } from '../contracts.mjs'
 import { SETTINGS_ROOT } from '../materialize/settings.mjs'
-import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSION } from './focus.mjs'
+import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSIONS_READ } from './focus.mjs'
 import { SELECTION_SCHEMA } from './selection.mjs'
 
 // Where a selector is kept: Atelier's own private state of the workspace,
@@ -38,7 +38,7 @@ export function validateSelectionState(document, workspaceId) {
   assertObsidianContract('scope', { schema: 'atelier-obsidian-scope/v1', scopeId: document.scopeId, mode: document.mode, selector: document.selector, ...(document.expansion === null ? {} : { expansion: document.expansion }) })
   if (document.focus !== null) {
     closedObject(document.focus, { required: ['version', 'query', 'queryDigest', 'paths', 'bookmark'] }, code, 'the persisted focus')
-    if (document.focus.version !== FOCUS_QUERY_VERSION || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
+    if (!FOCUS_QUERY_VERSIONS_READ.includes(document.focus.version) || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
     if (!Array.isArray(document.focus.paths) || document.focus.paths.length === 0 || document.focus.paths.some((item) => typeof item !== 'string')) refuse(code, 'the persisted focus names no path')
     closedObject(document.focus.bookmark, { required: ['type', 'title', 'options'] }, code, 'the persisted bookmark payload')
     if (document.focus.bookmark.type !== FOCUS_BOOKMARK_TYPE) refuse(code, 'the persisted bookmark payload is not a graph bookmark')

package/src/projection/obsidian/selection-ui/selection.mjs

@@ -1,6 +1,6 @@
 import { refuse } from '../../../runtime/obsidian/errors.mjs'
 import { EXPANSION_DIRECTIONS, EXPANSION_ORDERS, MAX_EXPANSION_DEPTH, ObsidianContractRefusal, SCOPE_MODES, assertObsidianContract, selectScope } from '../contracts.mjs'
-import { allocateWorkspacePaths } from '../materialize/path-registry.mjs'
+import { allocateViewPaths, viewsOfRegistry } from '../materialize/path-registry.mjs'
 import { buildFocusQuery, focusBookmarkPayload } from './focus.mjs'
 
 // Selection: a requested scope (full, scoped or focus, with an optional
@@ -78,9 +78,14 @@ export function resolveSelection({ canonicalSnapshot, profile, scope, allowEmpty
 
   const workspaceId = typeof profile?.workspaceId === 'string' ? profile.workspaceId : 'ws-unnamed'
   const nodeById = new Map(canonicalSnapshot.nodes.map((node) => [node.id, node]))
-  const vaultNodes = result.vaultNodes.map((id) => nodeById.get(id))
+  // Paths are allocated among the view's own notes, as a prepared view allocates them, seeded from the view's last
+  // allocation in the registry: a name that collides takes a qualifier, so which name a note gets depends on the notes
+  // of the view.
   let pathOf
-  try { ({ pathOf } = allocateWorkspacePaths({ registry: pathRegistry, workspaceId, nodes: vaultNodes })) } catch (error) { contractRefusalToTyped(error) }
+  try {
+    const section = viewsOfRegistry(pathRegistry, workspaceId)[document.scopeId] ?? null
+    ;({ pathOf } = allocateViewPaths({ published: section, nodes: result.vaultNodes.map((id) => nodeById.get(id)) }))
+  } catch (error) { contractRefusalToTyped(error) }
   const notePaths = Object.fromEntries(result.nodes.map((id) => [id, pathOf(nodeById.get(id).repo, id)]))
 
   let focus = null