@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/runtime/obsidian/opening.mjs

@@ -1,7 +1,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { createRecoveryStore as createStore, readFileBytes, sha256Digest } from '../../projection/obsidian/recovery/store.mjs'
+import { enclosingVaults, findVaultEntry, vaultRoute } from '../../projection/obsidian/publication/vault-list.mjs'
+import { createRecoveryStore as createStore, readFileBytes, sha256Digest, vaultRootFor } from '../../projection/obsidian/recovery/store.mjs'
 import { inspectApp, qualifyApp } from './app-capability.mjs'
+import { settingsWriteOutlook } from './app-registration.mjs'
 import { readObsidianEnablement } from './enablement.mjs'
 import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { UNAVAILABLE_APPLY_OPERATION } from './extension-points.mjs'
@@ -24,25 +26,44 @@ import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs
 //     that same generation and every note in the vault has the bytes that
 //     generation was published with;
 //   - the installed app is present, has its command-line capability, meets
-//     the minimum version, was asked to open the vault, answers for exactly
-//     this vault and has finished reading it.
+//     the minimum version, knows the vault as one of its vaults, was asked to
+//     open it, answers for exactly this vault and has finished reading it.
 //
-// Nothing here talks to an app or an operating system itself: `appProbe` and
-// `launcher` are injected, and there is no default for either.
+// Nothing a person does by hand is needed on the way. The app is made to know
+// the vault: through the app itself while it runs and answers, or, while no
+// Obsidian runs, in the app's own vault list (app-registration.mjs), which is
+// created for an Obsidian that never started, and whose command-line switch is
+// turned on in the same write. A view that the app kept from being published
+// (an app that runs without the vault, or that could not be qualified) is
+// published again once the app holds the vault, through the app, before the
+// answer is given.
+//
+// Two states of a running app cannot be got through that way: its command line
+// is turned off, or it has no vault open and does not list this one. Only when
+// the person asked for it (`restartApp`, `--restart-obsidian`; never implied),
+// and only after a read-only check that the write can succeed and a copy of the
+// settings file kept beside it, the app is quit (app-restart.mjs), the vault
+// added with the switch on while it is quit, and the app started again plainly,
+// which reopens every vault it had open. Without that, those states are
+// answered, naming the flag.
+//
+// Nothing here talks to an app or an operating system itself: `appProbe`,
+// `registry`, `launcher` and `quitter` are injected, and there is no default for
+// any.
 
 export const OPENING_OUTCOMES = Object.freeze({
   current: { summary: 'the vault is the present generation, verified by read-back, and the app has it open', next: 'nothing to do' },
   updating: { summary: 'maintenance is publishing or has not finished; the vault is not confirmed current', next: 'run `obsidian open` again in a moment' },
   'held-for-your-edit': { summary: 'a note you edited is preserved and held; the view is not republished over it', next: 'apply or withdraw the pending edit, then open again' },
   'stale-readable': { summary: 'a last good vault exists and can be read, but it is not proven to be the present generation', next: 'see `obsidian status` for the reason; `obsidian open --allow-stale` opens it as it is' },
-  'not-prepared': { summary: 'no generation of this view has been published yet', next: 'see `obsidian status` for the reason' },
+  'not-prepared': { summary: 'no generation of this view can be read back: none was published yet, or its vault cannot be found or used (the reason says which)', next: 'see `obsidian status` for the reason' },
   'app-missing': { summary: 'no Obsidian installation was found', next: 'install Obsidian, then open again' },
   'app-version-unsupported': { summary: 'the installed Obsidian is below the minimum supported version, or its version cannot be read', next: 'update Obsidian, then open again' },
   'app-cli-unavailable': { summary: 'the installed Obsidian has no usable command-line capability', next: 'enable the command-line interface in Obsidian, then open again' },
   indexing: { summary: 'the app answered for this vault but has not finished reading it', next: 'wait for Obsidian to finish indexing, then open again' },
   'publisher-conflict': { summary: 'another publisher or an uncoordinated editor holds this vault', next: 'close the other publisher or let it finish; it is retried automatically' },
-  'launch-failed': { summary: 'the operating system or the app did not open this vault', next: 'open the vault folder in Obsidian once by hand, then open again' },
-  'service-unavailable': { summary: 'the maintenance service of this workspace could not be started or reached as ours', next: 'see `obsidian service status`' },
+  'launch-failed': { summary: 'the operating system or the app did not open this vault', next: 'run `obsidian open` again; if it fails the same way, start Obsidian with any vault open and open again' },
+  'service-unavailable': { summary: 'the maintenance service of this workspace could not be started or reached as ours, or runs a later release than this command', next: 'see `obsidian service status`' },
   busy: { summary: 'the maintenance service runs but is in a long tick and did not answer in time', next: 'run `obsidian open` again in a moment; nothing was stopped or restarted' },
   disabled: { summary: 'the Obsidian integration is not enabled for this project, or this view is not configured', next: 'enable it in the project configuration' },
 })
@@ -57,34 +78,77 @@ export function describeOutcome(code) {
 
 // A reason whose next step is not its outcome's. With no vault open the app's
 // command line answers nothing, its version included, so the version floor
-// cannot be checked until a vault is open or the app is quit.
+// cannot be checked, and a vault the app does not know yet cannot be added
+// through it, until a vault is open or the app is quit.
 // `editor-uncoordinated` is the publisher stopping because an Obsidian that may
 // hold this vault could not be coordinated with. There is no other publisher to
 // wait for, and the cause is not known here: the app runs without this vault,
 // or with it but its command line did not answer, or the process table was
 // unknown (on Linux, any app that runs on a system Electron), or an app started
-// while the view was published with the app closed. Every cause clears once no
-// such process runs, and a view that was published before can instead be
-// opened in the app as it is, which then answers for it.
+// while the view was published with the app closed. `open` makes the app hold
+// the vault and publishes through it; every cause also clears once no such
+// process runs.
 const UNCOORDINATED = 'an Obsidian that may hold this vault could not be coordinated with, so publication stopped'
 const QUIT = 'quit Obsidian (on Linux, also any app that runs on a system Electron)'
+// Obsidian's settings file could not be used to add the vault while the app was quit: adding it through the app works instead.
+const THROUGH_THE_APP = 'start Obsidian with any vault open, then open again: the vault is then added through the app'
 export const REASON_NEXT = Object.freeze({
-  'no-vault-open': 'open any vault in Obsidian, or quit Obsidian, then open again',
-  'editor-uncoordinated': `${UNCOORDINATED}; ${QUIT}, or open this view in it with \`atelier obsidian open --allow-stale\`; it is retried automatically`,
+  'cli-turned-off': 'Obsidian\'s command line is turned off (the default of a new installation), and it runs, so its settings are its own: run `atelier obsidian open --restart-obsidian` to let Atelier quit Obsidian, turn its command line on, add this view\'s vault and start it again (the vaults it has open reopen); or turn it on yourself in Obsidian under Settings > General > Advanced > Command line interface, then open again',
+  'no-vault-open': 'Obsidian runs with no vault open, so it can be asked nothing: run `atelier obsidian open --restart-obsidian` to let Atelier quit Obsidian (no vault is open, so nothing closes), add this view\'s vault and start it again; or open any vault in Obsidian, or quit Obsidian, then open again',
+  'restart-platform-unqualified': 'Atelier restarts Obsidian on macOS only; turn its command line on yourself (Settings > General > Advanced > Command line interface), or open any vault in Obsidian, or quit it, then open again',
+  'restart-unavailable': 'this command was given no way to quit Obsidian; quit Obsidian yourself, then open again',
+  'app-main-process-unproven': 'Obsidian was not asked to quit: its main process could not be proven from the process table (`restart.detail` says why: more than one Obsidian main process, an Obsidian process of another user, a helper that is not its child, or a table that could not be read); quit Obsidian yourself, then open again',
+  'app-did-not-quit': 'Obsidian was asked to quit and did not within the wait; nothing was written to its settings. Quit it yourself, or wait until it has quit, then open again',
+  'app-not-started-again': 'Obsidian was quit to add this view\'s vault and could not be started again; start Obsidian yourself: it reopens the vaults it had open',
+  'vault-open-cli-silent': 'Obsidian has this view\'s vault open, as Atelier\'s plugin in it shows, but its command line did not answer, so the vault can be neither found nor opened through it; make sure the command-line interface is turned on in Obsidian\'s settings, then open again',
+  'editor-uncoordinated': `${UNCOORDINATED}; \`atelier obsidian open\` adds this view's vault to Obsidian and publishes through it, or ${QUIT}; it is retried automatically`,
+  'obsidian-settings-missing': 'Obsidian has no settings file on this account, and the folder it would be in does not exist or is not yours, so Atelier cannot create it: open any vault in Obsidian (starting it if it is not running; it then writes its settings), then open again',
+  'obsidian-settings-location-unknown': THROUGH_THE_APP,
+  'obsidian-settings-unsafe': `Obsidian's settings file is a link or not a regular file, so it is not written; ${THROUGH_THE_APP}`,
+  'obsidian-settings-not-owned': `Obsidian's settings file belongs to another user, so it is not written; ${THROUGH_THE_APP}`,
+  'obsidian-settings-unreadable': `Obsidian's settings file cannot be read as JSON, so it is not written; ${THROUGH_THE_APP}`,
+  'obsidian-settings-not-object': `Obsidian's settings file is not a JSON object, so it is not written; ${THROUGH_THE_APP}`,
+  'obsidian-settings-unwritable': `Obsidian's settings directory cannot be written (space or permissions); ${THROUGH_THE_APP}`,
+  'obsidian-settings-too-large': `with this view's vault, Obsidian's settings file would be larger than a settings file can be, so it is not written; ${THROUGH_THE_APP}`,
+  'obsidian-sandboxed': `this Obsidian is a Flatpak or snap build, which keeps its vault list inside its sandbox, where Atelier does not write; ${THROUGH_THE_APP}`,
+  'obsidian-settings-changed': 'Obsidian\'s settings file changed while the vault was being added, and nothing was written; open again',
+  'app-may-be-running': 'Obsidian started while the vault was being added, and nothing was written; open again',
+  'app-started-during-registration': 'Obsidian started just as this view\'s vault was added to its list and may not have read it; open again: a vault it missed is then added through it',
+  'registration-not-read-back': 'this view\'s vault was added to Obsidian\'s settings file, but the file could not be read back to confirm it; open again',
+  'addition-not-answered': 'Obsidian did not answer when asked to add this view\'s vault, and its vault list does not show it; open again, or quit Obsidian and open again',
+  'app-did-not-list-its-vaults': 'Obsidian runs but did not answer with its vault list; open again, or quit Obsidian and open again',
+  'app-refused-registration': 'Obsidian did not accept this view\'s vault folder as a vault; quit Obsidian and open again',
+  'registration-not-verified': 'Obsidian answered, but its vault list does not show this view\'s vault; quit Obsidian and open again',
+  'restarted-service-in-its-first-tick': 'the maintenance service ran an earlier release and was restarted on the installed one, which is still in its first tick; run `obsidian open` again in a moment',
+  'service-outdated': 'the maintenance service runs an earlier release of Atelier that could not be replaced; run `atelier obsidian service stop`, then open again',
+  'service-other-release': 'the maintenance service runs a later release of Atelier than this command, which never replaces a later release by itself; run `atelier obsidian service stop`, then open again, or open with the later release',
+  'vault-open-in-several-windows': 'Obsidian\'s vault list marks this view\'s folder open under more than one entry (in another letter case, or through a link), so it may hold the vault in more than one window, and a publication coordinates with one window only; remove the extra entries from Obsidian\'s vault list (Obsidian keeps the last window it closed marked open, so closing windows does not clear this), then open again',
+  'vault-allocation-lost': 'this view was published, but its vault is not where Atelier can find it: no record of a folder allocated for it (state/allocations/<view>.json in Atelier\'s private state), and no folder under the data root (vaults/<view>); restore that record from a backup if its vault was allocated elsewhere, or else make the folder vaults/<view> under the data root: the view is published there at the next change at its sources',
+  'vault-allocation-moved': 'this view\'s vault is now reached through a link, or leads somewhere other than where it was allocated, and Atelier publishes only into the folder at the path it recorded; put that folder back at the path `atelier obsidian location show` names, with no link on the way',
+  'vault-allocation-replaced': 'another folder, or a link, is where this view\'s vault was allocated, and Atelier publishes only into the folder it made; put the vault back there, or move what is there away: a folder that is gone is made again at the next tick, and the view published into it',
+  'vault-note-missing': 'a note of the generation this view last published is missing from its vault; the view is published again, and the note written back, at the next change at its sources',
+  'vault-root-moved': 'this view\'s vault was removed, moved or replaced by a link while it was being published, and nothing more was written into it; a vault allocated for the view is made again at the next tick and published into; a vault under the data root is asked for as lost until its folder is there again',
+  'vault-allocation-missing': 'the folder allocated to this view is gone; the maintenance service makes it again at its next tick, and publishes the view into it',
+  // A publisher-conflict whose first blocking cause is a file Atelier writes in the vault's settings folder. One change
+  // is enough to stop a publication, and the reason names only the first file that did: nothing says that no other
+  // publisher or editor is involved.
+  'plugin-file-changed': 'a file of Atelier\'s plugin in this vault (under .obsidian/plugins) changed while the view was published, by another program or by you, so the publication did not finish; it is retried automatically, and if this keeps happening, stop what keeps writing there (a sync tool, say)',
+  'settings-changed': 'a settings file Atelier writes in this vault (the plugin list or a plugin setting under .obsidian) changed while the view was published, by Obsidian, another program or you, and was not written over; it is retried automatically, reading the file as it is then',
+  'vault-inside-another-vault': 'Obsidian lists another vault at a folder that contains this view\'s vault; open never adds a vault inside another one, and never sends a call that could reach that vault instead: remove that vault from Obsidian\'s vault list, or keep Atelier\'s data root outside that folder, then open again',
 })
 
-// Before a first publication there is no vault to open in the app: the view is
-// published only while no such process runs.
-const FIRST_PUBLICATION_NEXT = Object.freeze({
-  'editor-uncoordinated': `${UNCOORDINATED}; ${QUIT} so the view is published, then \`atelier obsidian open\` starts Obsidian on it`,
+// What `open` answers when it could not clear the refusal itself (the app held the vault and the publication still
+// stopped, or no app answered to be asked): no step is left that open could take.
+const AFTER_OPEN_NEXT = Object.freeze({
+  'editor-uncoordinated': `${UNCOORDINATED}, and open could not clear it; ${QUIT} so the view is published, then open again`,
 })
 
 // The next step for an outcome and its reason; null for a code that is not an
-// opening outcome. `published` says whether a published generation of the view
-// reads back.
-export function nextStep(outcome, reason, { published = true } = {}) {
+// opening outcome. `afterOpen` says that the answer is `open`'s own, after it
+// tried what it can.
+export function nextStep(outcome, reason, { afterOpen = false } = {}) {
   if (typeof reason === 'string') {
-    if (!published && Object.hasOwn(FIRST_PUBLICATION_NEXT, reason)) return FIRST_PUBLICATION_NEXT[reason]
+    if (afterOpen && Object.hasOwn(AFTER_OPEN_NEXT, reason)) return AFTER_OPEN_NEXT[reason]
     if (Object.hasOwn(REASON_NEXT, reason)) return REASON_NEXT[reason]
   }
   return Object.hasOwn(OPENING_OUTCOMES, outcome) ? OPENING_OUTCOMES[outcome].next : null
@@ -98,16 +162,30 @@ export const OPENING_PRIMITIVES = Object.freeze({
   readBackAgrees: ({ entry, verification }) => verification.readable && verification.generationId === entry.preparedGenerationId && verification.intact,
   // Whether the app may be shown this vault at all.
   appQualifies: (qualification) => qualification.outcome === 'qualified',
+  // Whether a view that is not current was kept from publication by the app: then making the app hold the vault
+  // and asking for the view again can make it current. A vault open in several windows is asked for again once one
+  // window is left; while more are open, open names them instead.
+  // A view the service did not publish because the app's command line is turned off is one of them: once the app runs
+  // with it on and holds the vault, it is published through it.
+  keptByApp: (view) => ['publisher-conflict', 'stale-readable', 'not-prepared'].includes(view.outcome) && ['editor-uncoordinated', 'vault-open-in-several-windows', 'app-version-unsupported', 'app-cli-unavailable'].includes(view.reason),
 })
 
 const segment = (identifier) => identifier.replaceAll(':', '_')
-const STORE_AREAS = (scopeId) => [['vaults', segment(scopeId)], ['state', 'manifests', segment(scopeId)], ['state', 'journals', segment(scopeId)], ['state', 'locks'], ['recovery', 'objects'], ['staging']]
+const STORE_AREAS = (scopeId) => [['state', 'manifests', segment(scopeId)], ['state', 'journals', segment(scopeId)], ['state', 'locks'], ['recovery', 'objects'], ['staging']]
 
 // Reads the trusted pointer of a view and every note of its vault. Read-only:
 // the store is only constructed when everything it would create already exists.
+// `vaultRoot` is the folder the store publishes this view into, whenever the
+// store could be constructed, even before a first generation.
 export function readBackTrustedGeneration({ workspaceRoot, workspaceId, scopeId, repositoryRoots, createRecoveryStore = createStore }) {
   const unreadable = (reason) => ({ readable: false, reason, generationId: null, intact: false, noteCount: 0, differing: 0, missing: 0 })
-  if (!STORE_AREAS(scopeId).every((parts) => fs.existsSync(path.join(workspaceRoot, ...parts)))) return unreadable('no-published-vault')
+  // The view's vault wherever it is: allocated for the view, or under the data root.
+  let vault
+  try { vault = vaultRootFor({ workspaceRoot, workspaceId, scopeId }) } catch (error) {
+    if (typeof error?.code === 'string') return unreadable(error.code)
+    throw error
+  }
+  if (!fs.existsSync(vault.path) || !STORE_AREAS(scopeId).every((parts) => fs.existsSync(path.join(workspaceRoot, ...parts)))) return unreadable('no-published-vault')
   let store
   let trusted
   try {
@@ -117,7 +195,7 @@ export function readBackTrustedGeneration({ workspaceRoot, workspaceId, scopeId,
     if (typeof error?.code === 'string') return unreadable(error.code)
     throw error
   }
-  if (!trusted.pointer || !trusted.manifest) return unreadable('no-trusted-generation')
+  if (!trusted.pointer || !trusted.manifest) return { ...unreadable('no-trusted-generation'), vaultRoot: store.vaultRoot }
   let differing = 0
   let missing = 0
   for (const [notePath, base] of trusted.bases) {
@@ -163,11 +241,19 @@ export function scopeReport({ workspace, scopeId, repositoryRoots, serviceState,
     reason = edited ? 'vault-differs-from-trusted-generation' : verification.readable ? 'trusted-generation-differs' : verification.reason
   } else if (serviceState !== 'healthy') { outcome = 'stale-readable'; reason = serviceState === 'busy' ? 'maintenance-busy-not-rechecked' : 'maintenance-not-running' }
   else { outcome = 'current'; reason = entry.reason }
+  // Where the view's vault is, published or not: allocated for the view, or under the data root.
+  let vault
+  try { const found = vaultRootFor({ ...workspace, scopeId }); vault = { path: found.path, origin: found.origin } } catch (error) {
+    if (typeof error?.code !== 'string') throw error
+    vault = { path: null, origin: 'unreadable', reason: error.code }
+  }
   return {
-    scopeId, ...describeOutcome(outcome), next: nextStep(outcome, reason, { published: verification.readable }), reason,
+    scopeId, ...describeOutcome(outcome), next: nextStep(outcome, reason), reason, vault,
     freshness: entry === null ? null : { state: entry.state, reason: entry.reason, verified: entry.verified, generationId: entry.generationId, preparedGenerationId: entry.preparedGenerationId, heldNoteCount: entry.heldNotes.length, retainedEdits: entry.retainedEdits, checkedAt: entry.checkedAt },
     readBack: { readable: verification.readable, reason: verification.reason, generationId: verification.generationId, intact: verification.intact, noteCount: verification.noteCount, differing: verification.differing, missing: verification.missing },
     pendingEdits: pendingSummary(stateStore, scopeId, applyAvailable),
+    // Notes of the view worth naming, and the rule concerned; see "Notes that were laid out anyway" in docs/obsidian-contract.md.
+    ...(entry?.diagnostics ? { diagnostics: entry.diagnostics } : {}),
     vaultRoot: verification.vaultRoot ?? null,
   }
 }
@@ -183,12 +269,96 @@ const defaultSleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms)
 const READABLE = new Set(['stale-readable', 'held-for-your-edit', 'updating', 'publisher-conflict'])
 // After a launch: the app is still starting, or still opening the vault it was asked for.
 const NOT_UP_YET = new Set(['version-unknown', 'no-vault-open'])
+// After a launch: how many rounds in a row the command line must be silent, with only the plugin giving the version,
+// before `open` says the command line is what is missing.
+const SILENT_ROUNDS = 2
+const REGISTRY_OPERATIONS = ['listThroughApp', 'registerThroughApp', 'readSettings', 'registerInSettings']
+
+const attempt = async (operation) => { try { return await operation() } catch { return null } }
+
+// Makes the app know this vault as one of its vaults, by the state it is in:
+//
+//   - answering its command line (it gave its version): its own list is read;
+//     a vault it does not list is added and opened through the app, and read
+//     back from its list (findVaultEntry);
+//   - running with no vault open: its command line answers nothing, and its
+//     settings file is the running app's, so it is only read: a vault it lists
+//     is opened by path, and one it does not list is `no-vault-open`. So is an
+//     app whose version only Atelier's plugin reported: its command line gave
+//     none, so nothing is asked through it, and a vault its settings do not
+//     show is `vault-open-cli-silent` (the plugin shows the vault open);
+//   - not running: the vault is added to its settings file, which is written
+//     only while no Obsidian runs (registerVaultInObsidianSettings). An app
+//     that started just after that write may have read its list before it, and
+//     would then not find the vault by path: that is answered, never launched.
+//
+// A vault inside a folder the list has as a vault already is never added
+// (`vault-inside-another-vault`): the app would show its notes in that vault
+// too, and a call run in its folder would reach that vault.
+//
+// { ok: true, path, how, open, vaults } with the path the app knows the vault
+// by, whether its list flags it open (an app started plainly reopens it then),
+// and the list it was found in, or { ok: false, reason }.
+//
+// The window the app opens for an added vault takes the next command-line
+// call while it may still be loading, and can then answer that a command
+// does not exist yet: the list is asked again, a bounded number of times,
+// before an addition counts as not verified.
+const VERIFY_ATTEMPTS = 10
+async function ensureAppKnowsVault({ registry, observation, vaultRoot, sleep, pollMs, keepBackups = [] }) {
+  const inside = (vaults) => enclosingVaults({ vaults, vaultRoot }).length > 0
+  if (observation.noVaultOpen === true) {
+    const settings = await attempt(() => registry.readSettings())
+    const vaults = settings?.ok === true ? settings.vaults : null
+    const entry = findVaultEntry(vaults, vaultRoot)
+    if (entry) return { ok: true, path: entry.path, how: 'listed', open: entry.open === true, vaults }
+    return { ok: false, reason: inside(vaults) ? 'vault-inside-another-vault' : observation.fromPlugin === true ? 'vault-open-cli-silent' : 'no-vault-open' }
+  }
+  if (observation.answering === true) {
+    const listed = await attempt(() => registry.listThroughApp())
+    if (listed?.answered !== true) return { ok: false, reason: listed?.reason === 'no-vault-open' ? 'no-vault-open' : 'app-did-not-list-its-vaults' }
+    const known = findVaultEntry(listed.vaults, vaultRoot)
+    if (known) return { ok: true, path: known.path, how: 'listed', open: known.open === true, vaults: listed.vaults }
+    if (inside(listed.vaults)) return { ok: false, reason: 'vault-inside-another-vault' }
+    const asked = await attempt(() => registry.registerThroughApp({ vaultRoot }))
+    if (asked?.answered !== true && asked?.reason === 'no-vault-open') return { ok: false, reason: 'no-vault-open' }
+    if (asked?.answered === true && asked.result !== true) return { ok: false, reason: 'app-refused-registration' }
+    // An addition that was not answered (a call that timed out, say) may still have been made: the list tells.
+    for (let attempts = 1; ; attempts += 1) {
+      const again = await attempt(() => registry.listThroughApp())
+      const added = again?.answered === true ? findVaultEntry(again.vaults, vaultRoot) : null
+      if (added) return { ok: true, path: added.path, how: 'added-through-app', open: true, vaults: again.vaults }
+      if (attempts >= VERIFY_ATTEMPTS) return { ok: false, reason: asked?.answered === true ? 'registration-not-verified' : 'addition-not-answered' }
+      await sleep(pollMs)
+    }
+  }
+  const written = await attempt(() => registry.registerInSettings({ vaultRoot, keepBackups }))
+  if (written === null) return { ok: false, reason: 'obsidian-settings-unwritable' }
+  if (written.ok !== true) return { ok: false, reason: typeof written.code === 'string' ? written.code : 'obsidian-settings-unwritable' }
+  const settings = settingsWritten(written)
+  if (written.confirmed !== true) return { ok: false, reason: written.reason === 'registration-not-read-back' ? 'registration-not-read-back' : 'app-started-during-registration', ...(settings === null ? {} : { settings }) }
+  const how = written.registered === 'created' ? 'created-settings' : written.registered === 'already' ? 'listed' : 'added-to-settings'
+  // A vault already listed keeps its own open flag; one written here is written flagged open.
+  return { ok: true, path: written.entry.path, how, open: written.registered === 'already' ? written.entry.open === true : true, vaults: written.vaults, ...(settings === null ? {} : { settings }) }
+}
+
+// What was written to Obsidian's settings file, for the answer to show: null when nothing was.
+function settingsWritten(written) {
+  const created = written.registered === 'created'
+  const cliTurnedOn = written.cliTurnedOn === true
+  if (!created && written.registered !== 'written' && !cliTurnedOn) return null
+  return {
+    ...(typeof written.file === 'string' ? { file: written.file } : {}), created, ...(created ? { directoryCreated: written.created?.directory === true } : {}),
+    vaultAdded: written.registered !== 'already', cliTurnedOn, ...(typeof written.backupPath === 'string' ? { backupPath: written.backupPath } : {}),
+  }
+}
 
 // Starts or reconnects the owned service, asks it for a tick, reads the view
-// back, qualifies the app, has the vault opened and reports one outcome.
+// back, qualifies the app, makes the app know the vault, has it opened, asks
+// again for a view the app kept from being published, and reports one outcome.
 export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIMITIVES, lifecycleRules = LIFECYCLE_PRIMITIVES) {
   const {
-    loadProject, dataRoot, scopeId: requestedScope, appProbe, launcher, service = {}, consent, allowStale = false, extensions = null,
+    loadProject, dataRoot, scopeId: requestedScope, appProbe, launcher, registry, quitter = null, restartApp = false, service = {}, consent, allowStale = false, extensions = null,
     tickTimeoutMs = 120 * 1000, appWaitMs = 30 * 1000, appPollMs = 500, sleep = defaultSleep, monotonic = () => Date.now(),
     env = process.env, platform = process.platform, probeTimeoutMs,
   } = options
@@ -196,19 +366,30 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   // No defaults: reaching an app or the operating system is a decision of the entry that composes this.
   if (typeof appProbe?.inspect !== 'function' || typeof appProbe?.vaultState !== 'function') throw new TypeError('open needs an injected appProbe')
   if (typeof launcher?.open !== 'function') throw new TypeError('open needs an injected launcher')
+  if (!REGISTRY_OPERATIONS.every((name) => typeof registry?.[name] === 'function')) throw new TypeError('open needs an injected registry')
   if (typeof service.entryPath !== 'string') throw new TypeError('open needs the service entry it may start')
 
   const project = loadProject()
   const enablement = readObsidianEnablement(project)
   const applyAvailable = extensions !== null && extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
-  const finish = (outcome, extra = {}) => ({ ok: outcome === 'current', ...describeOutcome(outcome), next: nextStep(outcome, extra.reason, { published: extra.readBack?.readable !== false }), launched: false, ...extra })
+  // A restart this run made, and what it wrote to Obsidian's settings: every answer after them shows both.
+  let restart = null
+  let settingsShown = null
+  const finish = (outcome, extra = {}) => {
+    const { afterOpen = false, ...shown } = extra
+    const next = restart?.quit === true && restart.startedAgain === false ? REASON_NEXT['app-not-started-again'] : nextStep(outcome, shown.reason, { afterOpen })
+    return { ok: outcome === 'current', ...describeOutcome(outcome), next, launched: false, ...shown, ...(restart === null ? {} : { restart }), ...(settingsShown === null ? {} : { obsidianSettings: settingsShown }) }
+  }
   if (enablement.state === 'disabled') return finish('disabled', { reason: enablement.reason, scopeId: requestedScope ?? null })
   const scopeId = resolveScope(enablement, requestedScope)
   const lifecycle = { loadProject, dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
 
-  // 1. The owned service: reconnect, or start. Never adopt, never replace.
+  // 1. The owned service: reconnect, or start. Never adopt; a runtime of ours is replaced only when it runs an earlier
+  //    release, under the consent already recorded, when a tick is asked of it (requestServiceTick).
   let status = await serviceStatus(lifecycle, lifecycleRules)
   if (status.state === 'busy') return finish('busy', { scopeId, reason: status.reason, service: { state: status.state } })
+  // How a login item took part in starting the service (started through it, refreshed, or not used and why).
+  let loginItem = null
   if (status.state !== 'healthy') {
     let started
     try {
@@ -217,61 +398,186 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
       if (!(error instanceof ObsidianMaintenanceRefusal)) throw error
       return finish('service-unavailable', { scopeId, reason: error.code, service: { state: status.state } })
     }
-    if (started.state === 'busy') return finish('busy', { scopeId, reason: started.reason, service: { state: 'busy', started: started.started } })
-    if (started.state !== 'healthy') return finish('service-unavailable', { scopeId, reason: started.reason ?? started.state, service: { state: started.state } })
+    loginItem = started.loginItem ?? null
+    const item = loginItem === null ? {} : { loginItem }
+    if (started.state === 'busy') return finish('busy', { scopeId, reason: started.reason, service: { state: 'busy', started: started.started, ...item } })
+    if (started.state !== 'healthy') return finish('service-unavailable', { scopeId, reason: started.reason ?? started.state, service: { state: started.state, ...item } })
     status = started
   }
-
-  // 2. A tick that starts after this request, bounded.
-  const asked = await requestServiceTick({ ...lifecycle, tickTimeoutMs }, lifecycleRules)
-  const serviceShown = { state: asked.state, runtimeId: status.record?.runtimeId ?? null }
-  if (asked.state === 'busy') return finish('busy', { scopeId, reason: asked.reason, service: serviceShown })
-  if (!asked.requested) return finish('service-unavailable', { scopeId, reason: asked.reason, service: serviceShown })
+  let runtimeId = status.record?.runtimeId ?? null
+  let restarted = null
   const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
   const report = (freshnessOverride) => scopeReport({ workspace, scopeId, repositoryRoots: protectedRoots(project), serviceState: 'healthy', applyAvailable, ...(freshnessOverride === undefined ? {} : { freshness: freshnessOverride }) }, rules)
-  let view = report()
-  const tick = asked.pending ? null : asked.tick
-  if (asked.pending && view.outcome === 'current') view = { ...view, ...describeOutcome('updating'), reason: 'tick-still-running' }
-  else if (!asked.pending && tick?.state === 'busy') return finish('busy', { scopeId, reason: 'engine-lock-held', service: serviceShown })
-  else if (!asked.pending && (tick === null || tick.ok !== true || tick.state !== 'ticked') && view.outcome === 'current') {
-    // The tick after this request did not complete: what was current before is not proven current now.
-    view = { ...view, ...describeOutcome('stale-readable'), reason: `tick-${tick?.state ?? tick?.error?.code ?? 'unanswered'}` }
+
+  // A tick that starts after this request, bounded, which prepares and publishes this view once more, and the view as
+  // it left it. { view, serviceShown } or { answer }.
+  const tickAndReport = async () => {
+    const asked = await requestServiceTick({ ...lifecycle, tickTimeoutMs, scopeId, service }, lifecycleRules)
+    if (asked.restarted) restarted = asked.restarted
+    if (typeof asked.runtimeId === 'string') runtimeId = asked.runtimeId
+    const serviceShown = { state: asked.state, runtimeId, ...(restarted === null ? {} : { restarted }), ...(loginItem === null ? {} : { loginItem }) }
+    if (asked.state === 'busy') return { answer: { outcome: 'busy', extra: { scopeId, reason: asked.reason, service: serviceShown } } }
+    if (!asked.requested) return { answer: { outcome: 'service-unavailable', extra: { scopeId, reason: asked.reason, service: serviceShown } } }
+    let view = report()
+    const tick = asked.pending ? null : asked.tick
+    if (asked.pending && view.outcome === 'current') view = { ...view, ...describeOutcome('updating'), reason: 'tick-still-running' }
+    else if (!asked.pending && tick?.state === 'busy') return { answer: { outcome: 'busy', extra: { scopeId, reason: 'engine-lock-held', service: serviceShown } } }
+    else if (!asked.pending && (tick === null || tick.ok !== true || tick.state !== 'ticked') && view.outcome === 'current') {
+      // The tick after this request did not complete: what was current before is not proven current now.
+      view = { ...view, ...describeOutcome('stale-readable'), reason: `tick-${tick?.state ?? tick?.error?.code ?? 'unanswered'}` }
+    }
+    return { view, serviceShown }
   }
-  const common = { scopeId, reason: view.reason, service: serviceShown, freshness: view.freshness, readBack: view.readBack, pendingEdits: view.pendingEdits }
-  if (view.outcome !== 'current' && !(allowStale && READABLE.has(view.outcome) && view.readBack.readable)) return finish(view.outcome, common)
+  const shownOf = (view, serviceShown) => ({ scopeId, reason: view.reason, service: serviceShown, freshness: view.freshness, readBack: view.readBack, pendingEdits: view.pendingEdits })
+
+  // 2. The view, after a tick.
+  const first = await tickAndReport()
+  if (first.answer) return finish(first.answer.outcome, first.answer.extra)
+  let { view } = first
+  let common = shownOf(view, first.serviceShown)
+  // A view the app kept from being published goes on: the app is made to hold the vault, and the view asked for again.
+  const readable = allowStale && READABLE.has(view.outcome) && view.readBack.readable
+  const keptByApp = view.outcome !== 'current' && rules.keptByApp(view)
+  if (view.outcome !== 'current' && !readable && !keptByApp) return finish(view.outcome, common)
 
-  // 3. The app, before anything is launched.
-  const before = qualifyApp(await inspectApp(appProbe), { requireVersion: false })
+  // 3. The app, before anything is launched. With no vault open it answers nothing; a vault it already lists can still be opened by path.
+  let before = qualifyApp(await inspectApp(appProbe), { requireVersion: false })
   const app = (qualification) => ({ outcome: qualification.outcome, reason: qualification.reason, version: qualification.version, floor: qualification.floor })
-  if (!rules.appQualifies(before)) return finish(before.outcome, { ...common, reason: before.reason, app: app(before) })
 
-  // 4. Launch, then wait, bounded, for the app to answer for exactly this vault.
+  // A running app that cannot be reached (`state`: its command line is off, or it has no vault open and does not list
+  // this one) is quit, only when the person asked for it. { quit: true } with the app gone, or { answer } to give.
+  const QUIT_APP = { installed: true, cli: true, running: false, version: null }
+  const quitToRestart = async (state, stateOutcome) => {
+    if (!restartApp) return { answer: finish(stateOutcome, { ...common, reason: state, app: app(before) }) }
+    if (typeof quitter?.quit !== 'function' || typeof launcher.startPlain !== 'function' || typeof registry.backupSettings !== 'function') return { answer: finish(stateOutcome, { ...common, reason: 'restart-unavailable', app: app(before) }) }
+    // Read-only, before anything is sent: the write the restart is for can succeed. What it would refuse is answered
+    // now, with the app left running.
+    const notRestarted = (outcome, reason) => { restart = { asked: true, state, quit: false, signalled: false, signals: 0, reason }; return { answer: finish(outcome, { ...common, reason, app: app(before) }) } }
+    if (typeof view.vaultRoot !== 'string') return notRestarted('not-prepared', 'no-vault-folder')
+    const outlook = settingsWriteOutlook({ settings: await attempt(() => registry.readSettings()), vaultRoot: view.vaultRoot })
+    if (!outlook.ok) return notRestarted('launch-failed', outlook.code)
+    // A copy of the settings as they are, kept beside them once the main process is proven, right before the first
+    // signal; a copy that cannot be kept sends nothing. An app that has shown only its starter window has no file yet:
+    // there is nothing to copy, and the write creates it.
+    const quit = await attempt(() => quitter.quit({ beforeSignal: outlook.create === true ? null : () => registry.backupSettings() }))
+    restart = {
+      asked: true, state, quit: quit?.quit === true, signalled: quit?.signalled === true, ...(Number.isSafeInteger(quit?.pid) ? { pid: quit.pid } : {}),
+      signals: Number.isSafeInteger(quit?.signals) ? quit.signals : 0, ...(typeof quit?.settingsCopy === 'string' ? { settingsCopy: quit.settingsCopy } : {}),
+    }
+    if (quit?.quit === true) { before = qualifyApp(QUIT_APP, { requireVersion: false }); return { quit: true } }
+    restart.reason = typeof quit?.reason === 'string' ? quit.reason : 'app-did-not-quit'
+    if (typeof quit?.detail === 'string') restart.detail = quit.detail
+    // An app that was signalled and has not gone is neither started again nor written for: the person decides.
+    return { answer: finish(quit?.signalled === true ? 'launch-failed' : stateOutcome, { ...common, reason: restart.reason, app: app(before) }) }
+  }
+  // After a restart, every answer given before the launch starts the app again as it was: plainly, so it reopens the
+  // vaults it had open. Nothing was added for this view.
+  const giveBack = async () => {
+    if (restart?.quit !== true || restart.startedAgain !== undefined) return
+    restart.startedAgain = (await attempt(() => launcher.startPlain())) === true
+  }
+  if (before.reason === 'cli-turned-off') {
+    const stopped = await quitToRestart('cli-turned-off', before.outcome)
+    if (stopped.answer) return stopped.answer
+  }
+  const noVaultOpen = before.reason === 'no-vault-open'
+  if (!rules.appQualifies(before) && !noVaultOpen) {
+    // No app answered and none is known to run (a process table that could not be read, on Linux any app on a system
+    // Electron): for a view that app kept, the view's own reason says what to do.
+    if (keptByApp && !readable && before.running !== true && before.version === null) return finish(view.outcome, { ...common, app: app(before), afterOpen: true })
+    return finish(before.outcome, { ...common, reason: before.reason, app: app(before) })
+  }
+
+  // 4. The app knows this vault as one of its vaults: the folder the view is published into, wherever that is. Every
+  //    call about it then reaches it and no other vault: in its folder, or by its id when a vault listed at a folder
+  //    above it would take a call run there.
+  const { vaultRoot } = view
+  if (typeof vaultRoot !== 'string') { await giveBack(); return finish('not-prepared', { ...common, reason: 'no-vault-folder', app: app(before) }) }
+  // A version Atelier's plugin reported is not the command line answering (withPluginReportedVersion).
+  const fromPlugin = before.versionSource === 'plugin'
+  const knowVault = () => ensureAppKnowsVault({ registry, observation: { answering: typeof before.version === 'string' && !fromPlugin, noVaultOpen: before.reason === 'no-vault-open' || fromPlugin, fromPlugin }, vaultRoot, sleep, pollMs: appPollMs, keepBackups: typeof restart?.settingsCopy === 'string' ? [restart.settingsCopy] : [] })
+  let known = await knowVault()
+  // With no vault open, a vault the app does not list cannot be added while it runs: a restart the person asked for.
+  if (!known.ok && known.reason === 'no-vault-open' && restart === null) {
+    const stopped = await quitToRestart('no-vault-open', 'app-version-unsupported')
+    if (stopped.answer) return stopped.answer
+    known = await knowVault()
+  }
+  if (known.settings) settingsShown = known.settings
+  // An app that answered its version and then closed its last vault window is one with no vault open; one that holds
+  // this vault open but whose command line does not answer has no usable command line.
+  if (!known.ok) { await giveBack(); return finish(known.reason === 'no-vault-open' ? 'app-version-unsupported' : known.reason === 'vault-open-cli-silent' ? 'app-cli-unavailable' : 'launch-failed', { ...common, reason: known.reason, app: app(before) }) }
+  const registration = { how: known.how }
+  const route = vaultRoute({ vaults: known.vaults, vaultRoot })
+  // Open in several windows, one per entry of the list that names its folder: each holds the vault, and a publication
+  // coordinates with one only. Nothing is launched; the entries are named.
+  if (route.how === 'duplicated') { await giveBack(); return finish('publisher-conflict', { ...common, reason: 'vault-open-in-several-windows', duplicates: route.entries, app: app(before), registration }) }
+  if (route.how !== 'folder' && route.how !== 'id') { await giveBack(); return finish('launch-failed', { ...common, reason: route.how === 'ambiguous' ? 'vault-inside-another-vault' : 'registration-not-verified', app: app(before), registration }) }
+
+  // 5. Launch, then wait, bounded, for the app to answer for exactly this vault.
   let launch
-  try { launch = await launcher.open({ vaultRoot: view.vaultRoot }) } catch { launch = { launched: false, reason: 'launcher-threw' } }
-  if (launch?.launched !== true) return finish('launch-failed', { ...common, reason: typeof launch?.reason === 'string' ? launch.reason : 'launcher-refused', app: app(before) })
+  // A quit app is started plainly and handed the vault once it answers, so the vaults its list flags open come back
+  // (launch-plan.mjs).
+  // The id only where the route found it reaches this vault first (another vault's folder name may equal an id);
+  // otherwise the vault's own path, which the app matches exactly since the folder is listed.
+  const target = route.how === 'id' ? { vaultId: route.id, vaultPath: known.path } : { vaultPath: known.path }
+  try { launch = await launcher.open({ vaultRoot: known.path, ...target, appRunning: before.running === true }) } catch { launch = { launched: false, reason: 'launcher-threw' } }
+  // A restart ends here: the app was started again, or could not be (the next step then says to start it).
+  if (restart?.quit === true) restart.startedAgain = launch?.launched === true
+  if (launch?.launched !== true) return finish('launch-failed', { ...common, reason: typeof launch?.reason === 'string' ? launch.reason : 'launcher-refused', app: app(before), registration })
   const deadline = monotonic() + appWaitMs
   let after = before
   let vault = { answered: false, indexReady: false }
+  // Rounds in a row in which only Atelier's plugin gave the version and the command line did not answer for the vault.
+  let silentRounds = 0
+  // A quit app started plainly reopens only the vaults its list flags open. A listed vault that is closed opens through
+  // the link alone, so a link the started app did not take (it answered its tool, then refused the link) is handed
+  // once more, to the app that now runs, one round later, before the vault counts as not answering.
+  let linkRetry = launch.reason === 'app-started-link-not-taken' && known.open !== true ? 'due' : 'none'
+  let rounds = 0
   for (;;) {
+    rounds += 1
     after = qualifyApp(await inspectApp(appProbe), { requireVersion: true })
     // A running app below the floor is final; an app that has not come up yet, or not yet opened a vault, is asked again.
-    if (!rules.appQualifies(after) && !NOT_UP_YET.has(after.reason)) return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after) })
+    if (!rules.appQualifies(after) && !NOT_UP_YET.has(after.reason)) return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after), registration })
     if (rules.appQualifies(after)) {
-      try { vault = await appProbe.vaultState({ vaultRoot: view.vaultRoot }) } catch { vault = { answered: false, indexReady: false } }
+      try { vault = await appProbe.vaultState({ vaultRoot, route }) } catch { vault = { answered: false, indexReady: false } }
       if (vault?.answered === true && vault.indexReady === true) break
-    }
+      // Only the command line answers for a vault. An app whose version still only Atelier's plugin reports gives no
+      // answer there, and waiting changes nothing: its command line is what is missing, not a launch. One such round
+      // is not enough: a tool call that timed out while the app was busy opening the window looks the same once, so
+      // the answer is given at the second round in a row.
+      silentRounds = vault?.answered !== true && after.versionSource === 'plugin' ? silentRounds + 1 : 0
+      if (silentRounds >= SILENT_ROUNDS) return finish('app-cli-unavailable', { ...common, launched: true, reason: 'vault-open-cli-silent', app: app(after), registration })
+      if (linkRetry === 'due' && rounds >= 2 && vault?.answered !== true) {
+        linkRetry = 'done'
+        // Through the app's tool only: this `open` started the app, so the link never goes to the operating system.
+        try { await launcher.open({ vaultRoot: known.path, ...target, appRunning: true, startedByThisOpen: true }) } catch { /* the wait decides */ }
+      }
+    } else silentRounds = 0
     if (monotonic() >= deadline) break
     await sleep(appPollMs)
   }
-  if (!rules.appQualifies(after)) return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after) })
-  if (vault?.answered !== true) return finish('launch-failed', { ...common, launched: true, reason: 'app-did-not-answer-for-this-vault', app: app(after) })
-  if (vault.indexReady !== true) return finish('indexing', { ...common, launched: true, reason: 'metadata-cache-not-ready', app: app(after) })
+  if (!rules.appQualifies(after)) return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after), registration })
+  // The wait ended on a silent round with only the plugin giving the version: the command line is what did not answer.
+  if (vault?.answered !== true && silentRounds > 0) return finish('app-cli-unavailable', { ...common, launched: true, reason: 'vault-open-cli-silent', app: app(after), registration })
+  if (vault?.answered !== true) return finish('launch-failed', { ...common, launched: true, reason: 'app-did-not-answer-for-this-vault', app: app(after), registration })
+  if (vault.indexReady !== true) return finish('indexing', { ...common, launched: true, reason: 'metadata-cache-not-ready', app: app(after), registration })
+
+  // 6. The app holds the vault now: a view it kept from being published is asked for again, and published through it.
+  if (keptByApp) {
+    const second = await tickAndReport()
+    if (second.answer) return finish(second.answer.outcome, { ...second.answer.extra, launched: true, app: app(after), registration })
+    view = second.view
+    common = shownOf(view, second.serviceShown)
+    if (view.outcome !== 'current') return finish(view.outcome, { ...common, launched: true, app: app(after), registration, afterOpen: true })
+  }
 
-  // 5. Still what was verified? The launch took time.
-  if (view.outcome !== 'current') return finish(view.outcome, { ...common, launched: true, app: app(after) })
+  // 7. Still what was verified? The launch took time.
+  if (view.outcome !== 'current') return finish(view.outcome, { ...common, launched: true, app: app(after), registration })
   const again = report()
-  if (again.outcome !== 'current') return finish(again.outcome, { ...common, launched: true, reason: again.reason, freshness: again.freshness, readBack: again.readBack, app: app(after) })
-  return finish('current', { ...common, launched: true, app: app(after) })
+  if (again.outcome !== 'current') return finish(again.outcome, { ...common, launched: true, reason: again.reason, freshness: again.freshness, readBack: again.readBack, app: app(after), registration })
+  return finish('current', { ...common, launched: true, app: app(after), registration })
 }
 
 // Production entry point: the production decisions, always.