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

package/src/runtime/obsidian/pipeline.mjs

@@ -1,7 +1,10 @@
+import { createCooperativeBudget, prepareViewCooperatively } from '../../projection/obsidian/materialize/prepare-view.mjs'
 import { createHash } from 'node:crypto'
 import path from 'node:path'
-import { buildCanonicalGraph, createGraphFileCache } from '../../graph/graph.mjs'
-import { EMITTER_VERSION, createPreparationCache, prepareView, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { buildCanonicalGraph, buildCanonicalGraphSteps, createGraphFileCache } from '../../graph/graph.mjs'
+import { markdownMetadata } from '../../graph/knowledge-graph.mjs'
+import { EMITTER_VERSION, createPreparationCache, prepareView, readMarkdownLens, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { personalWorkspaceGraph } from '../../projection/obsidian/personal-workspace.mjs'
 import { publishView } from '../../projection/obsidian/publication/publisher.mjs'
 import { recheckDisplacedFiles } from '../../projection/obsidian/recovery/late-writer.mjs'
 import { createRecoveryStore, readFileBytes } from '../../projection/obsidian/recovery/store.mjs'
@@ -31,6 +34,68 @@ export const DEFAULT_ELIGIBILITY = Object.freeze({
   isEligible: (node) => node.classification === 'classified',
 })
 
+// A vault that is the person's own also shows the notes that carry no classification, when they decided so: the
+// audience decision `only-you` with `unclassified: 'shown'`, which no other audience decision may carry. Those notes
+// are the person's own files, in a vault only they see. One is admitted only when its bytes read as a note (the byte
+// lens the emitter reads it with), so a file the emitter would refuse never stops the vault: it stays withheld, as does
+// one that cannot be read. A note whose labels are unknown is never admitted: front matter Atelier could not read
+// (`malformed-frontmatter`: a block scalar, a wrapped value), or any top-level `kg` key that is not a
+// block, may carry an audience such as `sensitive` that "only you" leaves out. Only a note with no front matter, or
+// front matter of plain top-level keys at column 0 none of which is `kg` (plainTopLevelKeys) and in which the graph
+// reads no `kg` either, is the person's plain note. Assets follow the documents that
+// embed them, as always.
+export function onlyYouEligibility({ project }) {
+  const roots = new Map((project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => [repo.name, repo.path]))
+  const readsAsNote = (node) => {
+    const root = roots.get(node.repo)
+    if (root === undefined || node.extension !== 'md' || typeof node.path !== 'string') return false
+    let bytes
+    let lens
+    try { bytes = readFileBytes(path.join(root, ...node.path.split('/'))); lens = readMarkdownLens(bytes) } catch { return false }
+    // Read now, not as the graph saw it: a file that gained front matter since is judged by what it holds now.
+    if (lens.frontmatter === null) return node.classificationReason === 'absent-frontmatter'
+    if (node.classificationReason !== 'missing-kg-block') return false
+    const text = bytes.toString('utf8')
+    const block = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+    if (block === null || !plainTopLevelKeys(block[1])) return false
+    // A second layer: the graph's own reading of the front matter has no kg key either.
+    try { return !('kg' in markdownMetadata(text)) } catch { return false }
+  }
+  return Object.freeze({
+    revision: () => 'classified-documents/v2+unclassified-notes-read-as-notes-for-only-you/v4+assets-embedded-by-eligible-documents/v1',
+    isEligible: (node) => node.classification === 'classified' || (node.classification === 'unclassified' && readsAsNote(node)),
+  })
+}
+
+// Whether front matter is plain `key: value` lines at its top level, none of them `kg`: every line that is not blank,
+// a comment, or indented (a nested value or a continuation) starts with a bare key. A quoted key, a flow or JSON
+// mapping, a complex key (`? `), a top-level list or anything else unusual is not plain, so a label it may hold (a
+// `kg.audience: sensitive` Atelier did not read) keeps the note withheld. An allow-list, never a pattern to find.
+const PLAIN_KEY = /^([A-Za-z_][A-Za-z0-9_-]*)[ \t]*:(?:[ \t]|$)/
+function plainTopLevelKeys(frontmatter) {
+  // Line breaks YAML 1.1 readers honour and this reading does not (NEL, LS, PS) could hide a kg from it.
+  if (/[\u0085\u2028\u2029]/.test(frontmatter)) return false
+  let rooted = false
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    // An indented line is a nested value or a continuation only below a key at column 0; YAML also lets a whole root
+    // mapping be indented, and then its keys (kg among them) are indented too.
+    if (/^[ \t]/.test(line)) { if (!rooted) return false; continue }
+    const key = PLAIN_KEY.exec(line)
+    if (key === null || key[1] === 'kg') return false
+    rooted = true
+  }
+  return true
+}
+
+// The eligibility a workspace's machine settings decide: the one above only for "only you" with unclassified notes
+// shown, and the default, which withholds them, for every other decision and for none.
+export function eligibilityFor({ machine, project }) {
+  const audience = machine?.decisions?.audience
+  return audience?.choice === 'only-you' && audience.unclassified === 'shown' ? onlyYouEligibility({ project }) : DEFAULT_ELIGIBILITY
+}
+
 export function assetEligibilityFor({ graph, eligibility }) {
   const eligibleSources = new Set(graph.nodes.filter((node) => eligibility.isEligible(node) === true).map((node) => node.id))
   const embeds = Array.isArray(graph.embeds) ? graph.embeds : []
@@ -59,9 +124,47 @@ export function profileFor({ project, workspaceId, audienceAllow }) {
 // `index` is the engine's observation index. With both, a source whose observed digest is the cached one is not
 // opened: observation already decided by digest that it did not change, under the stat-hint bound observation
 // documents, and a full reconciliation hashes it again. Without an index every source is read and hashed here.
-export function buildGraph({ project, eligibility, cache = null, index = null }) {
-  const observedDigest = cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null
-  const canonical = buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+// A project bound to a personal workspace (personal-workspace.mjs) is built by that route, for every caller, with the
+// same caches: the composition's graph, served only under a validity key the composition confirmed. With
+// `deferPersonalValidation` (the engine), an unconfirmed key refuses `personal-validation-pending` instead of composing
+// on this thread.
+export function buildGraph({ project, eligibility, cache = null, index = null, deferPersonalValidation = false }) {
+  const observedDigest = observedDigestOf(cache, index)
+  const canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation }) ?? buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+  return eligibleGraph(canonical, eligibility)
+}
+
+// The same graph, built with the event loop given a turn between the Markdown sources of the census, under the
+// caller's cooperative budget (`scheduling`: createCooperativeBudget's options, its guard checked at every wait). For
+// the maintenance engine's tick: a first tick reads every source, and a large corpus would hold the service's
+// listener for the whole census. A project bound to a personal workspace is built by its own route, in one stretch,
+// as buildGraph builds it.
+export async function buildGraphCooperatively({ project, eligibility, cache = null, index = null, deferPersonalValidation = false, scheduling = {} }) {
+  const observedDigest = observedDigestOf(cache, index)
+  // The personal route answers for a bound project, and refuses a project that carries the reserved key unbound.
+  const personal = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation })
+  if (personal !== null) return eligibleGraph(personal, eligibility)
+  const budget = createCooperativeBudget(scheduling)
+  budget.check()
+  const steps = buildCanonicalGraphSteps(project, { fileCache: cache, observedDigest })
+  let canonical
+  try {
+    for (;;) {
+      const step = steps.next()
+      if (step.done) { canonical = step.value; break }
+      await budget.checkpoint(step.value)
+    }
+  } catch (error) {
+    steps.return?.()
+    throw error
+  }
+  budget.finish('graph-assembled')
+  return eligibleGraph(canonical, eligibility)
+}
+
+const observedDigestOf = (cache, index) => (cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null)
+
+function eligibleGraph(canonical, eligibility) {
   if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
   return withEligibility(canonical, eligibility.isEligible, assetEligibilityFor({ graph: canonical, eligibility }))
 }
@@ -73,6 +176,12 @@ export function buildGraph({ project, eligibility, cache = null, index = null })
 // its pinned digest is unchanged and the cached bytes are the ones that digest
 // describes, so bytes that drift under an unchanged pin are not consulted
 // until observation hashes the file again (the same bound as the graph stage).
+// The engine keeps that bound when it prepares cooperatively. Called on its
+// own, prepareViewCooperatively waits between notes and so reads every
+// selected source against its pin once more before it returns. The engine
+// turns that second reading off and checks the selected sources itself, after
+// the preparation and again before the commit, as observation does: by stat
+// hint, and by digest only where the hint moved.
 export function captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt }) {
   const roots = new Map((project.repos ?? []).filter((repo) => !repo.external).map((repo) => [repo.name, repo.path]))
   const absolute = (repoId, relative) => {
@@ -118,5 +227,5 @@ export function captureSnapshot({ project, graph, workspaceId, index, configDige
 // that note and reuses the rest. Both caches are derived, in-memory state: a
 // test may replace either seam with `() => null` to build or prepare in full.
 export function createProductionSeams() {
-  return { buildGraph, captureSnapshot, profileFor, prepareView, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
+  return { buildGraph, buildGraphCooperatively, captureSnapshot, profileFor, prepareView, prepareViewCooperatively, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
 }

package/src/runtime/obsidian/plugin-channel.mjs

@@ -2,6 +2,7 @@ import { createHash, randomBytes as cryptoRandomBytes, timingSafeEqual } from 'n
 import fs from 'node:fs'
 import path from 'node:path'
 import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow, realPathAsStored } from '../../project/private-state.mjs'
+import { assertAllocatedFolder, vaultRootFor } from '../../projection/obsidian/recovery/store.mjs'
 import {
   PLUGIN_BEARER, PLUGIN_CHALLENGE_WINDOW_MS, PLUGIN_CHANNEL_PROTOCOL, PLUGIN_HANDSHAKE_TTL_MS, PLUGIN_LEASE_TTL_MS, PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE, PLUGIN_MAX_SESSION_AGE_MS, PLUGIN_MAX_SESSIONS_PER_SCOPE,
   PLUGIN_RENEW_INTERVAL_MS, PLUGIN_STATUS_SCHEMA, pluginClientProof, pluginKeyHint, pluginRequestMac, pluginResponseMac, pluginServerProof, pluginSessionKey, pluginVaultProof,
@@ -158,9 +159,16 @@ export function createPluginChannelForOracleTests({
   onSessionOpened = () => {},
 }, primitives = PLUGIN_CHANNEL_PRIMITIVES) {
   const rules = { ...PLUGIN_CHANNEL_PRIMITIVES, ...primitives }
-  // As the file system stores the path, as the store registers the vault in the app (realPathAsStored): a data root given
-  // in another letter case names the same vault.
-  const vaultRootOf = (scopeId) => { try { return realPathAsStored(path.join(workspaceRoot, 'vaults', segment(scopeId))) } catch { return null } }
+  // The view's vault wherever it is (vaultRootFor: allocated for the view, else under the data root), and an allocated one
+  // only while it is the folder recorded; as the file system stores the path, as the store registers the vault in the app
+  // (realPathAsStored): a data root given in another letter case names the same vault.
+  const vaultRootOf = (scopeId) => {
+    try {
+      const found = vaultRootFor({ workspaceRoot, workspaceId, scopeId })
+      if (found.allocation !== null) assertAllocatedFolder(found.allocation)
+      return realPathAsStored(found.path)
+    } catch { return null }
+  }
   const keyDigestOf = (bearer) => createHash('sha256').update(bearer, 'utf8').digest()
   const handshakes = new Map()
   const pruneHandshakes = () => { const at = now(); for (const [handshakeId, handshake] of handshakes) if (handshake.expiresAt <= at) handshakes.delete(handshakeId) }

package/src/runtime/obsidian/plugin-choice.mjs

@@ -4,6 +4,7 @@ import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularF
 import { PLUGIN_ID } from '../../projection/obsidian/plugin-bridge/channel.mjs'
 import { COMMUNITY_PLUGINS_PATH } from '../../projection/obsidian/materialize/settings.mjs'
 import { sha256Digest } from '../../projection/obsidian/materialize/byte-lens.mjs'
+import { vaultRootFor } from '../../projection/obsidian/recovery/store.mjs'
 import { canonicalJson, isPlainObject, isoTime } from './documents.mjs'
 
 // Whether the person wants Atelier's plugin in one vault, as the vault itself
@@ -42,8 +43,14 @@ const MAX_SETTINGS_BYTES = 256 * 1024
 const segment = (identifier) => identifier.replaceAll(':', '_')
 
 export const pluginChoiceDirectory = (workspaceRoot) => path.join(workspaceRoot, 'state', 'plugin', 'choices')
-// Where the recovery store places a view's vault.
-export const viewVaultRoot = (workspaceRoot, scopeId) => path.join(workspaceRoot, 'vaults', segment(scopeId))
+// Where a view's vault is, as the recovery store finds it (vaultRootFor): the folder allocated to the view where the
+// workspace decided its vaults live, else its folder under the data root. A record that cannot be read, or was lost,
+// refuses, typed. Pass `workspaceId`; every caller here does. The two-argument form of earlier releases still works:
+// it takes the name of the workspace's private-state folder as the id, which a record of another workspace (or a
+// folder reached through a link) does not match, and such a record refuses, typed, rather than answering another vault.
+export function viewVaultRoot(workspaceRoot, scopeId, workspaceId = path.basename(String(workspaceRoot))) {
+  return vaultRootFor({ workspaceRoot, workspaceId, scopeId }).path
+}
 const choiceFile = (workspaceRoot, scopeId) => path.join(pluginChoiceDirectory(workspaceRoot), `${segment(scopeId)}.json`)
 
 function validChoice(document, { workspaceId, scopeId }) {
@@ -142,7 +149,10 @@ export function decidePluginChoice({ workspaceRoot, workspaceId, scopeId, vaultR
 // `pending` (the view's next preparation records it).
 export function currentPluginChoice({ workspaceRoot, workspaceId, scopeId }) {
   const recorded = readPluginChoice({ workspaceRoot, workspaceId, scopeId })
-  const change = changeShown(recorded, readCommunityEntry(viewVaultRoot(workspaceRoot, scopeId)).entry)
+  // A view whose vault cannot be found (its record cannot be read) shows what was recorded; its view says why.
+  let vaultRoot
+  try { vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId) } catch (error) { if (typeof error?.code !== 'string') throw error; return recorded }
+  const change = changeShown(recorded, readCommunityEntry(vaultRoot).entry)
   return change === null ? recorded : { ...change, since: null, pending: true }
 }
 
@@ -150,7 +160,9 @@ export function currentPluginChoice({ workspaceRoot, workspaceId, scopeId }) {
 // no app ran, it is confirmed: an app reads the list, entry and all, when it
 // next opens the vault. Published through a running app, it is only offered:
 // that app may not have read it, and the plugin running there confirms it
-// (confirmPluginSeen).
+// (confirmPluginSeen). So is one published into a vault no Obsidian listed
+// while one ran (`direct-unheld`): the evidence covers only the lists Atelier
+// can read, not another profile's or another machine's.
 const IN_PLACE = new Set(['policy-satisfied', 'created', 'published', 'published-external-captured', 'already-current'])
 export function confirmPluginEntry({ workspaceRoot, workspaceId, scopeId, result, clock }) {
   const unit = (result?.notes ?? []).find((entry) => entry.path === COMMUNITY_PLUGINS_PATH)

package/src/runtime/obsidian/plugin-drift.mjs

@@ -18,6 +18,10 @@ import { viewVaultRoot } from './plugin-choice.mjs'
 // where a file goes) is asked about once, not at every tick; a change to it is
 // asked about again. Where the plugin is turned off in the vault, a pinned
 // file that is gone is no drift: the publisher never makes one again.
+// `settle(scopeIds)` looks again after each tick, and takes as seen what a
+// publication of that tick could not change, so a drift publishing cannot
+// repair is not published a second time at the next look (at a service's
+// start, say).
 
 const segment = (identifier) => identifier.replaceAll(':', '_')
 const TURNED_OFF = 'turned-off-in-this-vault'
@@ -33,7 +37,7 @@ function pinnedPlugin(workspaceRoot, workspaceId, scopeId) {
     if (sha256Digest(bytes) !== pointer.manifestDigest) return null
     const owned = JSON.parse(bytes.toString('utf8'))?.ext?.[OBSIDIAN_EXT_KEY]?.settings?.pluginOwned
     if (!Array.isArray(owned?.files)) return null
-    return { files: owned.files.filter((file) => typeof file?.path === 'string' && typeof file?.digest === 'string'), off: owned.withheldBecause === TURNED_OFF }
+    return { manifest: pointer.manifestDigest, files: owned.files.filter((file) => typeof file?.path === 'string' && typeof file?.digest === 'string'), off: owned.withheldBecause === TURNED_OFF }
   } catch {
     return null
   }
@@ -53,24 +57,68 @@ function onDisk(vaultRoot, relativePath) {
   try { return readFileDigest(path.join(vaultRoot, relativePath)) ?? 'absent' } catch { return 'unreadable' }
 }
 
+// A look, as it is compared: the vault root, and each pinned file with its pin and what the disk holds.
+const signatureOf = (record) => JSON.stringify([record.root, record.files.map((file) => file.digest), record.files.map((file) => file.state)])
+// Never what a look finds on disk: a path recorded so is asked about at the next look whatever it holds then.
+const NOT_SEEN = 'not-seen'
+
 export function createPluginDriftObserver({ workspaceRoot, workspaceId }) {
+  // Per view: the last look ({ root, files: [{ path, digest, state }], manifest }).
   const looked = new Map()
+  // The views the last observe asked to be prepared again: the tick that follows publishes them.
+  let asked = new Set()
+  // What the pinned plugin files of a view look like on disk now; null when its committed generation pins none.
+  const look = (scopeId) => {
+    const pinned = pinnedPlugin(workspaceRoot, workspaceId, scopeId)
+    if (pinned === null || pinned.files.length === 0) return null
+    // The view's vault wherever it is; one that cannot be found is refused by the engine, not observed here.
+    let vaultRoot
+    try { vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId) } catch (error) { if (typeof error?.code !== 'string') throw error; return null }
+    let root = 'absent'
+    try { const stat = fs.lstatSync(vaultRoot); root = stat.isSymbolicLink() ? 'link' : (stat.mode & 0o777).toString(8) } catch { root = 'absent' }
+    const files = pinned.files.map((file) => ({ path: file.path, digest: file.digest, state: onDisk(vaultRoot, file.path) }))
+    const drifted = (file) => file.state !== file.digest && !(pinned.off && file.state === 'absent')
+    return { root, files, manifest: pinned.manifest, drifted, differs: files.some(drifted) }
+  }
   return {
     observe(scopeIds) {
       const drifted = []
       for (const scopeId of scopeIds) {
-        const pinned = pinnedPlugin(workspaceRoot, workspaceId, scopeId)
-        if (pinned === null || pinned.files.length === 0) { looked.delete(scopeId); continue }
-        const vaultRoot = viewVaultRoot(workspaceRoot, scopeId)
-        let root = 'absent'
-        try { const stat = fs.lstatSync(vaultRoot); root = stat.isSymbolicLink() ? 'link' : (stat.mode & 0o777).toString(8) } catch { root = 'absent' }
-        const disk = pinned.files.map((file) => onDisk(vaultRoot, file.path))
-        const differs = disk.some((found, index) => found !== pinned.files[index].digest && !(pinned.off && found === 'absent'))
-        const signature = JSON.stringify([root, pinned.files.map((file) => file.digest), disk])
-        if (differs && looked.get(scopeId) !== signature) drifted.push(scopeId)
-        looked.set(scopeId, signature)
+        const seen = look(scopeId)
+        if (seen === null) { looked.delete(scopeId); continue }
+        const last = looked.get(scopeId)
+        if (seen.differs && (last === undefined || signatureOf(last) !== signatureOf(seen))) drifted.push(scopeId)
+        looked.set(scopeId, { root: seen.root, files: seen.files, manifest: seen.manifest })
       }
+      asked = new Set(drifted)
       return drifted
     },
+    // After a tick. A view this tick published (one the last observe asked for, one whose committed generation
+    // changed since the last look, or one never looked at before) had its plugin files written or left for the person
+    // by its publisher. Of what the disk shows now, only what that publication could not change is taken as seen,
+    // without asking: a file as it pins it, or one that holds what it held before the tick under the same pin and the
+    // same vault root. So a drift publishing cannot repair (the data file of a vault root that is a link, say) is not
+    // asked about again once it was asked about under its pin. Anything else is not taken as seen, and the next look
+    // asks about it: a file another writer removed or changed after the publication, while the tick went on, or
+    // brought back to what it held under a pin the tick replaced; a file the publication left for the person, which
+    // the person may have repaired before the tick ended; and any file, when the vault root changed during the tick.
+    // Asking about a file that is still left writes no vault file: the publisher does not publish a committed
+    // generation again for it (pluginFilesDrifted). Any other view keeps its last look.
+    settle(scopeIds) {
+      for (const scopeId of scopeIds) {
+        const seen = look(scopeId)
+        if (seen === null) { looked.delete(scopeId); continue }
+        const last = looked.get(scopeId)
+        if (!asked.has(scopeId) && last !== undefined && last.manifest === seen.manifest) continue
+        // Keyed by path and pin: what a file held under a pin this tick replaced says nothing about the new one.
+        const key = (file) => `${file.path}\u0000${file.digest}`
+        const before = new Map((last?.files ?? []).map((file) => [key(file), file.state]))
+        // And only under the same vault root: a root made private during the tick changes what the publisher leaves.
+        const sameRoot = last !== undefined && last.root === seen.root
+        const files = seen.files.map((file) => (!seen.drifted(file) || (sameRoot && before.get(key(file)) === file.state) ? file : { ...file, state: NOT_SEEN }))
+        looked.set(scopeId, { root: seen.root, files, manifest: seen.manifest })
+      }
+      asked = new Set()
+    },
   }
 }

package/src/runtime/obsidian/plugin-presence.mjs

@@ -9,6 +9,18 @@ export const PLUGIN_PRESENCE_REASONS = Object.freeze(['live-lease', 'no-live-lea
 // The two ways back, for a view whose vault turned the plugin off.
 export const turnPluginOnNext = (scopeId) => `turn Atelier on in Obsidian (Settings, Community plugins), or run \`atelier obsidian plugin on --scope ${scopeId}\`, which restores it at the view's next publication`
 
+// A view kept `current` while a plugin file its committed generation pins waits for an app that qualifies: the notes
+// are verified, the plugin file (often `data.json`) is not written yet (engine.mjs). Its freshness reason says so.
+export const PLUGIN_FILES_WAIT_FOR_APP = 'verified-by-read-back-plugin-waits-for-app'
+export const PLUGIN_FILES_WAIT_NEXT = 'the view\'s notes are current, but a file of Atelier\'s plugin in this vault is not written yet, since Obsidian could not be coordinated with (it runs without its command line answering, say): it is written once Obsidian answers its command line or is quit, and it is retried automatically'
+
+// The presence, with the plugin files that wait for the app when the view's freshness says so (`files`, and the next
+// step unless the presence has its own).
+export function withPluginFilesPending(presence, freshness) {
+  if (freshness?.state !== 'current' || freshness.reason !== PLUGIN_FILES_WAIT_FOR_APP) return presence
+  return { ...presence, files: 'waits-for-app', next: presence.next ?? PLUGIN_FILES_WAIT_NEXT }
+}
+
 export function pluginPresenceOf(statusDocument, scopeId) {
   if (!isPlainObject(statusDocument)) return { present: false, reason: 'service-not-running' }
   const scopes = isPlainObject(statusDocument.plugins) && Array.isArray(statusDocument.plugins.scopes) ? statusDocument.plugins.scopes : null
@@ -40,7 +52,8 @@ export function withPluginReportedVersion(appProbe, readPresence, { maxAgeMs = 1
   return {
     async inspect() {
       const [observation, presence] = await Promise.all([appProbe.inspect(), presenceNow()])
-      if (presence?.present !== true || observation?.installed !== true || observation?.cli !== true || observation.running === false || typeof observation.version === 'string') return observation
+      // A command line that answered it is turned off stays that answer: a plugin's version never hides it.
+      if (presence?.present !== true || observation?.installed !== true || observation?.cli !== true || observation.running === false || typeof observation.version === 'string' || observation.cliOff === true) return observation
       return { ...observation, running: true, version: presence.appVersion, noVaultOpen: false, versionSource: 'plugin' }
     },
     vaultState: (input) => appProbe.vaultState(input),

package/src/runtime/obsidian/private-lock.mjs

@@ -89,6 +89,20 @@ function listGenerations(directory) {
 
 const ticketName = (generation, kind) => `${String(generation).padStart(12, '0')}.${kind}`
 
+// A ticket is removed only while it holds the given bytes: one that holds others is another holder's. Answers whether
+// nothing of these bytes is left at the path (removed now, or gone already); throws what reading or removing it threw.
+function removeIfStill(file, body) {
+  let current
+  try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') return true; throw error }
+  if (current !== body) return true
+  fs.unlinkSync(file)
+  return true
+}
+
+// Tickets this process published and could not remove after its acquisition failed, by lock directory. Each is
+// removed at this process's next acquisition in that directory, before the directory is looked at.
+const UNWITHDRAWN = new Map()
+
 // Read-only. { available, reason, generation, ticket }
 export async function inspectPrivateGenerationLock({ directory, workspaceId, proveAbandoned = createAbandonmentProof(), nowMs = Date.now() }) {
   const { names, highest, unknown } = listGenerations(directory)
@@ -116,6 +130,11 @@ export async function inspectPrivateGenerationLock({ directory, workspaceId, pro
 // Never waits and never throws for a lock that is merely held.
 export async function acquirePrivateGenerationLock({ workspaceRoot, directory, workspaceId, purpose, service = null, clock, proveAbandoned, randomBytes = cryptoRandomBytes }) {
   const contained = ensureContainedPrivateDirectory({ workspaceRoot, directory, label: 'private lock' })
+  const owed = UNWITHDRAWN.get(contained)
+  if (owed !== undefined) {
+    // Still failing: the ticket stays, and this acquisition finds it as held by this process, as before.
+    try { if (removeIfStill(owed.file, owed.body)) UNWITHDRAWN.delete(contained) } catch { /* tried again at the next acquisition */ }
+  }
   const acquiredAt = isoTime(clock)
   const status = await inspectPrivateGenerationLock({ directory: contained, workspaceId, proveAbandoned, nowMs: Date.parse(acquiredAt) })
   const holder = status.ticket ? { pid: status.ticket.pid, purpose: status.ticket.purpose, runtimeId: status.ticket.service?.runtimeId ?? null } : null
@@ -125,12 +144,25 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
   const ticket = validateTicket({ schema: LOCK_TICKET_SCHEMA, workspaceId, purpose, pid: process.pid, machine: machineDigest(), nonce: randomBytes(16).toString('hex'), acquiredAt, service }, workspaceId)
   const body = JSON.stringify(ticket)
   const file = path.join(contained, ticketName(generation, 'json'))
+  // A ticket published and then not handed to its caller, because a later step failed (the directory sync or the
+  // read-back of the publication, the listing that confirms it), is removed while it still holds these bytes: nobody
+  // would release it, and every later acquisition by this process would find it held by this process. One that does
+  // not hold them is another holder's and is left alone. A removal that fails too (the same fault, say) is owed, and
+  // made at the next acquisition in this directory.
+  const withdraw = () => {
+    try { removeIfStill(file, body) } catch { UNWITHDRAWN.set(contained, { file, body }) }
+  }
   try { publishPrivateFile(file, body) } catch (error) {
     if (error.code === 'EEXIST') return { acquired: false, reason: 'lost-the-race-for-this-generation', holder: null }
+    withdraw()
     throw error
   }
   // Confirm: a decision made on an old listing finds the newer ticket here and withdraws.
-  const after = listGenerations(contained)
+  let after
+  try { after = listGenerations(contained) } catch (error) {
+    withdraw()
+    throw error
+  }
   if (after.highest !== generation) {
     try { fs.unlinkSync(file) } catch { /* a lower generation is ignored and pruned by the next holder */ }
     return { acquired: false, reason: 'a-newer-holder-exists', holder: null }
@@ -138,18 +170,21 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
   for (const name of after.names) {
     if (Number(TICKET_NAME.exec(name)[1]) < generation) try { fs.unlinkSync(path.join(contained, name)) } catch { /* pruned by somebody else */ }
   }
+  // Settled once the lock is given back, or found not to be ours any more. A release that throws (a full disk, an
+  // I/O error while the released ticket is written) settles nothing: the lock is still held, and calling release()
+  // again tries again. Writing the same released ticket a second time is harmless.
   let released = false
   return {
     acquired: true,
     generation,
     release() {
       if (released) return false
-      released = true
       let current
-      try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') return false; throw error }
+      try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') { released = true; return false } throw error }
       // Taken over after a proof of abandonment (this process was thought gone): nothing here is ours to release.
-      if (current !== body) return false
+      if (current !== body) { released = true; return false }
       publishPrivateFile(path.join(contained, ticketName(generation, 'released')), body)
+      released = true
       return true
     },
   }

package/src/runtime/obsidian/process-identity.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
+import path from 'node:path'
 import { executableIdentity } from './service-record.mjs'
 
 // Whether a live PID provably runs the executable a service record names,
@@ -32,27 +33,36 @@ export function readProcessCommandLine(pid, { platform = process.platform, readF
   return null
 }
 
-// Pure. The command line must name the recorded entry module, and a runtime
-// identifier it carries must be the recorded one.
-export function commandLineNamesRecord(commandLine, record) {
-  const entry = record?.executable?.path
-  if (typeof entry !== 'string' || entry === '' || typeof record.runtimeId !== 'string') return false
+// Pure. The command line must name the recorded entry module, by one of
+// `entries` (its recorded path, and the path it was started by when that is
+// another name for it), and a runtime identifier it carries must be the
+// recorded one.
+export function commandLineNamesRecord(commandLine, record, entries = [record?.executable?.path]) {
+  const names = entries.filter((entry) => typeof entry === 'string' && entry !== '')
+  if (names.length === 0 || typeof record?.runtimeId !== 'string') return false
   if (Array.isArray(commandLine)) {
-    if (!commandLine.slice(1).includes(entry)) return false
+    if (!commandLine.slice(1).some((word) => names.includes(word))) return false
     const named = commandLine.filter((word) => word.startsWith(RUNTIME_ARGUMENT)).map((word) => word.slice(RUNTIME_ARGUMENT.length))
     return named.every((runtimeId) => runtimeId === record.runtimeId)
   }
   if (typeof commandLine !== 'string') return false
-  if (!` ${commandLine} `.includes(` ${entry} `)) return false
+  if (!names.some((entry) => ` ${commandLine} `.includes(` ${entry} `))) return false
   const named = [...commandLine.matchAll(/(?:^|\s)--runtime-id=(\S+)/g)].map((match) => match[1])
   return named.every((runtimeId) => runtimeId === record.runtimeId)
 }
 
 // The recorded executable is still the bytes that were recorded, and the live
-// process was started on it.
-export function processRunsRecordedExecutable(record, { commandLineOf = readProcessCommandLine, identityOf = executableIdentity } = {}) {
+// process was started on it: by its recorded path, or by the path the record
+// says it was started by (a login item names the installed entry by its path),
+// when that still leads to the recorded one.
+export function processRunsRecordedExecutable(record, { commandLineOf = readProcessCommandLine, identityOf = executableIdentity, realpathOf = fs.realpathSync } = {}) {
   try {
     if (identityOf(record.executable.path).digest !== record.executable.digest) return false
   } catch { return false }
-  return commandLineNamesRecord(commandLineOf(record.pid), record)
+  const entries = [record.executable.path]
+  const invokedAs = record.executable.ext?.invokedAs
+  if (typeof invokedAs === 'string' && path.isAbsolute(invokedAs)) {
+    try { if (realpathOf(invokedAs) === record.executable.path) entries.push(invokedAs) } catch { /* not another name for it */ }
+  }
+  return commandLineNamesRecord(commandLineOf(record.pid), record, entries)
 }