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

package/src/runtime/obsidian/opening.mjs

@@ -1,8 +1,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { enclosingVaults, findVaultEntry, vaultRoute } from '../../projection/obsidian/publication/vault-list.mjs'
-import { createRecoveryStore as createStore, readFileBytes, sha256Digest } from '../../projection/obsidian/recovery/store.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'
@@ -30,20 +31,32 @@ import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs
 //
 // 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). 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.
+// 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` and `launcher` are injected, and there is no default for any.
+// `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' },
@@ -80,11 +93,16 @@ const QUIT = 'quit Obsidian (on Linux, also any app that runs on a system Electr
 // 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({
-  'cli-turned-off': 'Obsidian\'s command line is turned off (the default of a new installation): turn it on in Obsidian under Settings > General > Advanced > Command line interface, then open again',
-  'no-vault-open': 'open any vault in Obsidian, or quit Obsidian, then open again; open then adds this view\'s vault to Obsidian itself',
+  '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 not run on this account yet: start it once (it creates its settings), then open again with it running or quit',
+  '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}`,
@@ -105,6 +123,18 @@ export const REASON_NEXT = Object.freeze({
   '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',
+  'selection-history-shortened': 'the selection history of the personal home ends at an earlier record than the running maintenance service has read: records were removed by something other than a confirmation, and the service publishes nothing while the history is shorter. Put the removed records back, and it goes on as before. Or accept the history as it now stands: a service started again (`atelier obsidian service stop`, then open again) reads the history as it is and follows the selection it then ends with, publishing it if its generation still holds (`atelier obsidian status` reports that selection, or why it cannot be used); a confirmation made after the records were removed is followed without a restart once the history is as long as it was',
   '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',
 })
 
@@ -136,11 +166,13 @@ export const OPENING_PRIMITIVES = Object.freeze({
   // 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.
-  keptByApp: (view) => ['publisher-conflict', 'stale-readable', 'not-prepared'].includes(view.outcome) && ['editor-uncoordinated', 'vault-open-in-several-windows', 'app-version-unsupported'].includes(view.reason),
+  // 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.
@@ -148,7 +180,13 @@ const STORE_AREAS = (scopeId) => [['vaults', segment(scopeId)], ['state', 'manif
 // 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 {
@@ -204,8 +242,14 @@ 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), 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),
@@ -226,6 +270,9 @@ 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 } }
@@ -250,28 +297,29 @@ const attempt = async (operation) => { try { return await operation() } catch {
 // (`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, vaults } with the path the app knows the vault by and
-// the list it was found in, or { ok: false, reason }.
+// { 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 }) {
+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', vaults }
+    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', vaults: listed.vaults }
+    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' }
@@ -280,16 +328,30 @@ async function ensureAppKnowsVault({ registry, observation, vaultRoot, sleep, po
     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', vaults: again.vaults }
+      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 }))
+  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' }
-  if (written.confirmed !== true) return { ok: false, reason: written.reason === 'registration-not-read-back' ? 'registration-not-read-back' : 'app-started-during-registration' }
-  return { ok: true, path: written.entry.path, how: written.registered === 'already' ? 'listed' : 'added-to-settings', vaults: written.vaults }
+  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
@@ -297,7 +359,7 @@ async function ensureAppKnowsVault({ registry, observation, vaultRoot, sleep, po
 // 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, registry, service = {}, consent, allowStale = false, extensions = null,
+    loadProject, locateProject, 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
@@ -311,18 +373,24 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   const project = loadProject()
   const enablement = readObsidianEnablement(project)
   const applyAvailable = extensions !== null && extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
+  // 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
-    return { ok: outcome === 'current', ...describeOutcome(outcome), next: nextStep(outcome, shown.reason, { afterOpen }), launched: false, ...shown }
+    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 }) }
+  const lifecycle = { loadProject, ...(locateProject === undefined ? {} : { locateProject }), dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
 
   // 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 {
@@ -331,8 +399,10 @@ 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
   }
   let runtimeId = status.record?.runtimeId ?? null
@@ -346,7 +416,7 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
     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 }) }
+    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()
@@ -372,8 +442,45 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   if (view.outcome !== 'current' && !readable && !keptByApp) return finish(view.outcome, common)
 
   // 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.
-  const before = qualifyApp(await inspectApp(appProbe), { requireVersion: false })
+  let before = qualifyApp(await inspectApp(appProbe), { requireVersion: false })
   const app = (qualification) => ({ outcome: qualification.outcome, reason: qualification.reason, version: qualification.version, floor: qualification.floor })
+
+  // 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
@@ -386,19 +493,27 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   //    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') return finish('not-prepared', { ...common, reason: 'no-vault-folder', app: app(before) })
+  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 known = await ensureAppKnowsVault({ registry, observation: { answering: typeof before.version === 'string' && !fromPlugin, noVaultOpen: noVaultOpen || fromPlugin, fromPlugin }, vaultRoot, sleep, pollMs: appPollMs })
+  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) 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) })
+  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') 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') return finish('launch-failed', { ...common, reason: route.how === 'ambiguous' ? 'vault-inside-another-vault' : 'registration-not-verified', app: app(before), registration })
+  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
@@ -408,11 +523,21 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   // 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), registration })
@@ -420,13 +545,23 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
       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.
-      if (vault?.answered !== true && after.versionSource === 'plugin') return finish('app-cli-unavailable', { ...common, launched: true, reason: 'vault-open-cli-silent', app: app(after), registration })
-    }
+      // 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), 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 })
 

package/src/runtime/obsidian/personal-selection.mjs

@@ -0,0 +1,125 @@
+import path from 'node:path'
+import { PersonalWorkspaceRefusal, readPersonalSelectionHead } from '@mnstry/atelier/personal-workspace'
+import { ensureLocalState } from '@mnstry/atelier/project'
+import { assertPersonalSelection, loadBoundProject, loadBoundProjectOffThread, notePersonalSelectionHead, personalSelectionOf, pinPersonalSelection } from '../../projection/obsidian/personal-workspace.mjs'
+import { refuse } from './errors.mjs'
+
+// A person's confirmed selection, bound to the maintenance runtime.
+//
+// A personal home keeps a history of the generations its person confirmed
+// (`selectPersonalGeneration` of the personal-workspace module). The loaders
+// here follow that history instead of naming a generation themselves:
+//
+//   read the head -> load the generation it names -> read the head again
+//
+// The head is read from the history alone, in the caller's thread: one
+// directory listing and one bounded read per record. Whether the generation
+// may be used is composition's to decide, as for any binding: in a worker for
+// a service, in the calling thread for a command run once. A head that moved
+// while the generation was loaded is another selection, and refuses
+// `personal-selection-changed`.
+//
+// Nothing is confirmed here and nothing is chosen for the person. A history
+// with no record, one that does not hold, a home that cannot be read and a
+// generation its composition refuses each refuse as a maintenance refusal
+// with the module's own code (`nothing-selected`, `selection-history-corrupt`,
+// `personal-home-unavailable`, `root-missing`, `stale-generation` and the
+// rest). There is no project to fall back to: an engine whose loader refuses
+// publishes nothing, and every view it knows says why.
+//
+// A loaded project is pinned to the record it was loaded under
+// (pinPersonalSelection), so the engine observes that record and the place of
+// the next one, and loads again at the tick after a confirmation or after the
+// history was cut short. At every full reconciliation the history is read
+// again, and a project whose record it no longer ends with is refused.
+//
+// A history never gets shorter through the module: selections are appended and
+// nothing removes one. So a history that ends at a lower record than this
+// process has read it ending at was cut short by something else, and following
+// it back could publish what nobody confirmed after the records removed. Every
+// read of the history's end is noted (notePersonalSelectionHead): the first
+// read here, the read once the generation is loaded, the recheck of a project
+// already loaded, and a read the engine asks for when its guard stops a view
+// because an observed file changed or could not be read (once for views
+// stopped one after another). A
+// history that ends earlier than the highest record noted refuses
+// `selection-history-shortened` at a load and at a recheck, and nothing is
+// loaded or used from it while it is shorter; the guard's read only notes, and
+// its view says `mixed-read`. An engine whose project is pinned below the
+// highest record noted loads it again at its next tick
+// (personalSelectionBehind). A record added and removed between two of those
+// reads was never read, and does not count.
+//
+// Only the record number is kept, and only in this process. A record in a
+// place already read, with other content, is read as a confirmation. A process
+// started after the cut reads the history as it then stands and publishes what
+// it ends with: starting the service again accepts the shorter history, and so
+// does any start of it (a login, a restart after an upgrade or a failure).
+//
+// Who may see a vault is not decided here: that stays the machine's setting.
+//
+// Where the workspace is does not wait for a load: a bound project's folder is
+// its private home, so the home alone locates it (locatePersonalHome). A
+// service resolves its workspace from that at once, and starts, whether or not
+// a selection is confirmed; its engine then awaits the loader at each tick.
+
+// The decisions the oracles in test/obsidian-personal-selection.test.mjs are
+// sensitive to. Production always uses these; a test hands a loader a broken
+// one (`rules`) to prove that its oracle can fail.
+export const SELECTION_PRIMITIVES = Object.freeze({
+  // A history that ends at a lower record than this process has read is refused, at every read of it.
+  refusesShortened: true,
+  // The head is read again once the generation is loaded.
+  readsHeadAgain: true,
+  // What the loaded project is pinned for (pinPersonalSelection).
+  pin: Object.freeze({ observe: true, recheck: true }),
+})
+
+const SOURCE = Object.freeze({ source: 'personal-workspace' })
+const LOCATED = Symbol('atelier.obsidian.located-personal-home')
+
+// The record the history ends with. A history without one refuses, and so does one shorter than this process read it.
+function confirmedHead(personalHome, rules) {
+  let head
+  try { head = readPersonalSelectionHead({ personalHome }) } catch (error) {
+    if (!(error instanceof PersonalWorkspaceRefusal)) throw error
+    refuse(error.code, 'the selection history of the personal workspace could not be read; nothing is loaded from it', SOURCE)
+  }
+  notePersonalSelectionHead(personalHome, head, rules)
+  if (head.selected === null) refuse('nothing-selected', 'no generation of the personal workspace is confirmed; nothing is loaded until one is', SOURCE)
+  return head
+}
+
+function pinned(project, head, rules) {
+  pinPersonalSelection(project, head, { ...rules.pin, refusesShortened: rules.refusesShortened })
+  if (rules.readsHeadAgain) assertPersonalSelection(project)
+  return project
+}
+
+// What the workspace of a bound personal home is resolved from, without loading anything: a project that holds the home
+// as its folder and nothing else, as a bound project's folder is. Its pointer is under the home, the data root is the
+// pointer's or the caller's, and a home is outside every Git worktree. Synchronous; nothing is composed.
+export function locatePersonalHome({ personalHome } = {}) {
+  if (typeof personalHome !== 'string' || !path.isAbsolute(personalHome) || path.resolve(personalHome) !== personalHome) refuse('path-not-absolute', 'a personal home is named by its absolute path', SOURCE)
+  const located = { configDir: personalHome, [LOCATED]: personalHome }
+  located.localState = ensureLocalState(located, { write: false, env: { PATH: process.env.PATH } })
+  return located
+}
+
+// The personal home a located or a loaded project follows, which a service it starts or a login item it installs is
+// given instead of a project (--personal-home); null for any other project.
+export const personalHomeOf = (project) => project?.[LOCATED] ?? personalSelectionOf(project)?.personalHome ?? null
+export { personalSelectionOf }
+
+// The project of the confirmed selection, for a loader that may block (a command run once). `bind` and `rules` are
+// test seams.
+export function loadSelectedProject({ personalHome } = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const head = confirmedHead(personalHome, rules)
+  return pinned(loadBoundProject({ personalHome, generationId: head.selected }, { bind }), head, rules)
+}
+
+// The same, for a loader on a service's event loop: the composition runs in a worker, and the engine awaits it.
+export async function loadSelectedProjectOffThread({ personalHome } = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const head = confirmedHead(personalHome, rules)
+  return pinned(await loadBoundProjectOffThread({ personalHome, generationId: head.selected }, { bind }), head, rules)
+}