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

package/src/readiness/readiness.mjs

@@ -123,6 +123,13 @@ function buildPackageReadiness({
   }
 }
 
+// Paths in the written artifact are relative to the project config directory
+// in POSIX form, so `readiness --check` does not depend on where the project
+// is checked out and the artifact names no machine-specific directory.
+function configRelative(project, file) {
+  return path.relative(project.configDir, file).split(path.sep).join('/') || '.'
+}
+
 function buildProjectReadiness({ project, graph = null } = {}) {
   const loadedGraph = graph || (fs.existsSync(project.graphPath) ? readJson(project.graphPath) : null)
   const projectionEntry = path.join(project.outputRoot, 'index.html')
@@ -142,14 +149,14 @@ function buildProjectReadiness({ project, graph = null } = {}) {
     blockers,
     warnings,
     graph: {
-      path: project.graphPath,
+      path: configRelative(project, project.graphPath),
       nodes: loadedGraph?.counts?.nodes ?? loadedGraph?.nodes?.length ?? 0,
       edges: loadedGraph?.counts?.edges ?? loadedGraph?.edges?.length ?? 0,
       diagnostics: loadedGraph?.counts?.diagnostics ?? loadedGraph?.diagnostics?.length ?? 0,
     },
     projection: {
-      outputRoot: project.outputRoot,
-      entry: projectionEntry,
+      outputRoot: configRelative(project, project.outputRoot),
+      entry: configRelative(project, projectionEntry),
     },
     support: {
       telemetry: 'none',

package/src/reflection/index.mjs

@@ -0,0 +1,56 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-interaction.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true }); addFormats(ajv)
+const validators = new Map()
+export function validateInteraction(value, shape) {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  if (!['observation', 'assessment', 'act', 'policy'].includes(shape)) return ['unsupported interaction shape']
+  if (!validators.has(shape)) validators.set(shape, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(shape)
+  return validate(value) ? [] : validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+}
+export function assertInteraction(value, shape) {
+  const errors = validateInteraction(value, shape)
+  if (errors.length) throw new Error(`invalid ${shape}: ${errors.join('; ')}`)
+  return value
+}
+export function reflectionReference(record) {
+  const kind = record?.schema === 'atelier-reflection-observation@v1' ? 'observation' : 'assessment'
+  assertInteraction(record, kind)
+  return { kind, id: record.id, digest: digest(record) }
+}
+export function qualifyReflection({ assessment, observations, scope, purpose }) {
+  assertInteraction(assessment, 'assessment'); boundedLearningValue(observations)
+  if (!Array.isArray(observations) || observations.length > 128) throw new Error('bounded observations required')
+  for (const o of observations) assertInteraction(o, 'observation')
+  if (new Set(observations.map(o => o.id)).size !== observations.length) throw new Error('ambiguous observation identity')
+  const reasons = []
+  if (assessment.scope !== scope || assessment.purpose !== purpose || assessment.status !== 'active') reasons.push('assessment-outside-active-purpose')
+  if (!assessment.evidence.length) reasons.push('assessment-without-evidence')
+  if (new Set(assessment.evidence.map(e => `${e.kind}:${e.id}`)).size !== assessment.evidence.length) reasons.push('duplicate-evidence')
+  const admitted = []
+  for (const pin of assessment.evidence) {
+    const o = observations.find(o => o.id === pin.id)
+    if (pin.kind !== 'observation' || !o || digest(o) !== pin.digest || o.status !== 'active' || o.scope !== scope || o.purpose !== purpose) reasons.push(`evidence-stale-or-outside-purpose:${pin.id}`)
+    else admitted.push(o)
+  }
+  if (assessment.claimKind === 'independent-capacity' && (assessment.subject.kind !== 'person' || admitted.some(o => o.assistance !== 'independent' || o.subject.kind !== 'person' || o.subject.id !== assessment.subject.id))) reasons.push('independent-capacity-not-supported-by-admitted-evidence')
+  if (assessment.claimKind === 'system-friction' && assessment.subject.kind === 'person') reasons.push('system-friction-cannot-be-a-personal-capacity-claim')
+  return { reference: reflectionReference(assessment), current: reasons.length === 0, reasons,
+    uncertainty: assessment.uncertainty, limits: assessment.limits, semanticTruthVerified: false, observationAuthorityTransferred: false }
+}
+// The caller supplies an attributed judgment. This function qualifies its exact
+// evidence, never invents a developmental score or silently persists a profile.
+export function prepareReflectiveAct({ assessment, observations, act }) {
+  assertInteraction(act, 'act')
+  const result = qualifyReflection({ assessment, observations, scope: act.scope, purpose: act.purpose })
+  if (!result.current) throw new Error(`reflection unavailable: ${result.reasons.join('; ')}`)
+  if (act.origin !== 'witness' || !['reflective', 'coaching'].includes(act.mode)) throw new Error('reflective contribution requires Witness origin and declared mode')
+  const required = [reflectionReference(assessment), ...assessment.evidence]
+  for (const pin of required) if (!act.dependencies.some(p => digest(p) === digest(pin))) throw new Error('reflective act must pin its assessment and evidence')
+  if (act.mode === 'coaching' && !act.dependencies.some(p => p.kind === 'intention')) throw new Error('coaching requires a current chosen intention')
+  return { act: structuredClone(act), assessment: result, deliverable: false, executionAuthorized: false }
+}

package/src/runtime/obsidian/app-production-seams.mjs

@@ -1,25 +1,28 @@
-import { execFile, spawnSync } from 'node:child_process'
+import { execFile, execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
+import { performance } from 'node:perf_hooks'
 import path from 'node:path'
 import { NEUTRAL_DIRECTORY, defaultCliPath, defaultObsidianProcessProbe, routedCall } from '../../projection/obsidian/publication/transport.mjs'
 import { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
 import { realPathAsStored } from '../../project/private-state.mjs'
 import { appAnswered, readEvalAnswer, readVersionAnswer } from './app-capability.mjs'
-import { registerVaultInObsidianSettings } from './app-registration.mjs'
+import { backupObsidianSettings, registerVaultInObsidianSettings } from './app-registration.mjs'
+import { createAppQuitter } from './app-restart.mjs'
 import { launchPlan, runLaunchPlan, urlProcessed } from './launch-plan.mjs'
 
 // The production seams of `obsidian open` and of the service's adapter
-// factory: the only code that asks the installed Obsidian anything or asks the
-// operating system to open it.
+// factory: the only code that asks the installed Obsidian anything, asks the
+// operating system to open it, or quits it (for a restart a person asked for).
 //
 // This module is imported by exactly two places, both real command-line
 // entries and both behind an explicit `--adapter=obsidian-cli`: the service
 // entry (service-main.mjs) and the command entry (src/commands/obsidian.mjs,
 // `production: true`). No test of the default suite imports it in-process, and
-// importing it leaves a trace below that the test suite asserts is absent. One
-// test imports it in a child process, with a stand-in for the command-line
-// tool, to read the version answers it parses; the opt-in real-app suite
-// imports it to reach an isolated app through that app's private HOME.
+// importing it leaves a trace below that the test suite asserts is absent.
+// Tests import it in child processes only, with a private HOME: with a
+// stand-in for the command-line tool, to read the answers it parses, and with
+// a stand-in execFile, to check the launcher's executors; the opt-in real-app
+// suite imports it to reach an isolated app through that app's private HOME.
 //
 // Status: exercised against an isolated Obsidian 1.13.7 (installer 1.12.7) on
 // macOS by the opt-in real-app suite in test/obsidian-first-open-real-app.test.mjs;
@@ -127,7 +130,8 @@ function vaultRegisterCode(vaultRoot) {
 //   listThroughApp()                  -> { answered: true, vaults } | { answered: false, reason }
 //   registerThroughApp({ vaultRoot }) -> { answered: true, result } | { answered: false, reason }
 //   readSettings()                    -> readObsidianSettings answer (never writes)
-//   registerInSettings({ vaultRoot }) -> registerVaultInObsidianSettings answer
+//   registerInSettings({ vaultRoot, keepBackups }) -> registerVaultInObsidianSettings answer
+//   backupSettings()                  -> backupObsidianSettings answer (a copy beside the file; the file is not written)
 //
 // Through the app only while it runs and answers; in its settings file only
 // while no Obsidian runs, which registerVaultInObsidianSettings checks itself.
@@ -155,9 +159,13 @@ export function createProductionAppRegistry({
       return answer.answered ? { answered: true, result: answer.value?.result ?? null } : answer
     },
     readSettings: () => (sandbox === null ? readObsidianSettings({ userDataDir }) : sandboxed),
-    registerInSettings: ({ vaultRoot }) => (sandbox !== null ? sandboxed : userDataDir === null
+    // A copy of the settings file as it is, before a restart sends the app any signal (backupObsidianSettings).
+    backupSettings: () => (sandbox !== null ? sandboxed : userDataDir === null
       ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
-      : registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe })),
+      : backupObsidianSettings({ userDataDir })),
+    registerInSettings: ({ vaultRoot, keepBackups = [] }) => (sandbox !== null ? sandboxed : userDataDir === null
+      ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
+      : registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, keepBackups })),
   }
 }
 
@@ -167,18 +175,25 @@ export function createProductionAppRegistry({
 // the app itself answers the tool; a running app is handed the URL through its
 // tool, which takes a URL even with its command line turned off, and through the
 // operating system when the tool did not take it. A URL is never handed to the
-// operating system for an app this launch started. No shell.
+// operating system for an app this launch started. No shell. `execFile` is
+// node's, and a stand-in in the test of these executors, which runs in a child
+// process (the default suite never imports this module in-process).
 export function createProductionLauncher({
-  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep,
+  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep, execFile: runFile = execFile,
 } = {}) {
   const osCommand = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
   const run = (file, args, timeout = 15_000) => new Promise((resolve) => {
-    execFile(file, args, { env, cwd: workingDirectory, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve({ failed: Boolean(error), stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }))
+    runFile(file, args, { env, cwd: workingDirectory, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve({ failed: Boolean(error), stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }))
   })
   return {
-    open({ vaultId = null, vaultPath = null, appRunning }) {
+    // Starts a quit app with no URL, so it reopens the vaults its list flags open: for giving back an app `open`
+    // quit to restart it, when the vault could not be added after all. macOS only, as the restart is.
+    startPlain: async () => platform === 'darwin' && !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
+    // `startedByThisOpen`: this `open` started the app with an earlier launch; the link goes through its tool only.
+    open({ vaultId = null, vaultPath = null, appRunning, startedByThisOpen = false }) {
       const plan = launchPlan({ platform, appRunning, vaultId, vaultPath })
       return runLaunchPlan(plan, {
+        startedEarlier: startedByThisOpen === true,
         start: async () => !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
         answered: async () => { const reply = await run(cliPath, ['version'], CLI_TIMEOUT_MS); return appAnswered({ stdout: reply.stdout, stderr: reply.stderr, exited: !reply.failed }) },
         handLink: async (uri) => urlProcessed((await run(cliPath, [uri], CLI_TIMEOUT_MS)).stdout),
@@ -189,6 +204,23 @@ export function createProductionLauncher({
   }
 }
 
+// Quits the running app for a restart a person asked for (app-restart.mjs): SIGTERM to its main process only, proven
+// from this machine's process table (`ps`, never a pattern search) as this account's, then waits until the process
+// probe says no Obsidian runs. The table is `pid ppid uid executable`; one process is described again by its parent,
+// user, start time and executable immediately before the signal.
+export function createProductionAppQuitter({ platform = process.platform, processProbe = () => defaultObsidianProcessProbe({ platform }), waitMs } = {}) {
+  const ps = (args) => execFileSync('/bin/ps', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024, timeout: 5000, killSignal: 'SIGKILL' })
+  return createAppQuitter({
+    platform, uid: typeof process.getuid === 'function' ? process.getuid() : null, processProbe,
+    readTable: () => ps(['-ww', '-A', '-o', 'pid=,ppid=,uid=,comm=']),
+    readProcess: (pid) => ps(['-ww', '-o', 'ppid=,uid=,lstart=,comm=', '-p', String(pid)]),
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    // The wait and the linger are measured on a monotonic clock: a step of the wall clock changes neither.
+    now: () => performance.now(),
+    ...(waitMs === undefined ? {} : { waitMs }),
+  })
+}
+
 export function createProductionAppSeams(options = {}) {
-  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options) }
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options), quitter: createProductionAppQuitter(options) }
 }

package/src/runtime/obsidian/app-registration.mjs

@@ -5,7 +5,7 @@ import { MAX_OBSIDIAN_SETTINGS_BYTES, OBSIDIAN_SETTINGS_FILE, enclosingVaults, f
 import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from '../../project/private-state.mjs'
 
 // Adding a view's vault to Obsidian's own vault list while Obsidian is not
-// running, so that `obsidian://open?path=` finds it when the app starts.
+// running, so that the app opens it when it starts.
 //
 // Outside Atelier's own storage, it is the only file of another application
 // Atelier writes. The list is `obsidian.json` in the app's user-data directory
@@ -18,10 +18,11 @@ import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from
 //
 //   - never for a Flatpak or snap build, which reads its list inside its
 //     sandbox and never this file (`sandbox`, see obsidianSandboxedBuild);
-//   - only an existing file, in an existing user-data directory, both this
+//   - an existing file only in an existing user-data directory, both this
 //     user's own, a real directory and a regular file (no link, and no second
-//     name: a hard link would keep the old list), holding a JSON object: a file
-//     Obsidian has not written is never created;
+//     name: a hard link would keep the old list), holding a JSON object;
+//   - a file that does not exist (Obsidian never started on this account) is
+//     created, and only then: see createObsidianSettings below;
 //   - never for a vault inside a folder the list has as a vault already: the
 //     app would show its notes in that vault too, and a call run in its folder
 //     would reach that vault (see vault-list.mjs);
@@ -29,6 +30,12 @@ import { openRegularFileNoFollow, realPathAsStored, syncPrivateDirectory } from
 //     it, as values: the app itself rewrites the file with JSON.stringify;
 //   - the new entry is { path: the vault root's real path, ts: now, open:
 //     true } under a fresh 16-hex id that no entry has;
+//   - the command-line switch: whenever the list is written, `cli` is set to
+//     true when it is not (the default of a new installation is off, and
+//     `open` needs the command line while the app holds the vault). A vault the
+//     list has already, with `cli` not true, is written for the switch alone.
+//     Only here, so only while no Obsidian runs: a running app keeps its
+//     switch in memory and would write it back;
 //   - the new file is no larger than a settings file this module reads;
 //   - the bytes as they were are kept beside it in
 //     `obsidian.json.atelier-backup-<UTC time>`, fsynced, before the file is
@@ -46,13 +53,14 @@ const currentUid = () => (typeof process.getuid === 'function' ? process.getuid(
 const compactUtc = (ms) => new Date(ms).toISOString().replace(/[-:.]/g, '')
 const BACKUP = new RegExp(`^${OBSIDIAN_SETTINGS_FILE.replaceAll('.', '\\.')}\\.atelier-backup-\\d{8}T\\d{9}Z$`)
 
-// Keeps the first backup, the list as it was before Atelier ever wrote it, and `latest`; removes the ones between.
-// Their names sort as their times. A backup that cannot be removed stays.
-function pruneBackups(directory, latest) {
+// Keeps the first backup, the list as it was before Atelier ever wrote it, `latest`, and the names in `keep` (a copy
+// the same run took before it quit the app); removes the others between. Their names sort as their times. A backup
+// that cannot be removed stays.
+function pruneBackups(directory, latest, keep = []) {
   let names
   try { names = fs.readdirSync(directory).filter((name) => BACKUP.test(name)).sort() } catch { return }
   for (const name of names.slice(1)) {
-    if (name === latest) continue
+    if (name === latest || keep.includes(name)) continue
     const file = path.join(directory, name)
     try { if (fs.lstatSync(file).isFile()) fs.unlinkSync(file) } catch { /* it stays */ }
   }
@@ -82,35 +90,113 @@ function readBytesNoFollow(file) {
   try { return fs.readFileSync(descriptor) } finally { try { fs.closeSync(descriptor) } catch { /* read already, or failed */ } }
 }
 
-// { ok: true, registered: 'already' | 'written', entry: { id, path, open }, confirmed, vaults, backupPath?, reason? }
-// or a typed refusal { ok: false, code, message }. `confirmed` is false when an
-// app appeared right after the rename (`app-started-during-registration`): it
-// may have read the list before it, so whoever asked verifies through the
-// app; and when the written file could not be read back to find the entry
-// (`registration-not-read-back`). `vaults` is the list as it was found or
-// written. `processProbe()` answers 'absent', 'running' or 'unknown'; only
-// 'absent' allows a write. `sandbox` names a Flatpak or snap build found for
+// Creates the settings file of an Obsidian that never started on this account:
+// the file does not exist, and the process table says, positively, that no
+// Obsidian runs, read before and again immediately before the file appears.
+// The app reads the file when it starts (a missing or unreadable one reads as
+// no settings) and opens every vault flagged open, so a plain start opens this
+// one, with its command line on. Only:
+//
+//   - in the user-data directory as it is when that is this user's own real
+//     directory, or, when it does not exist, in one created here with mode
+//     0700 inside an existing real parent directory (a missing parent is
+//     `obsidian-settings-missing`: nothing is created above the directory);
+//   - with exactly { "vaults": { "<16 hex>": { path, ts, open: true } },
+//     "cli": true }, mode 0600;
+//   - by an exclusive create: the complete bytes are written, fsynced, to a
+//     temporary file in the directory, which is then linked to the file's name
+//     (a link fails on any name there, a file the app wrote meanwhile
+//     included, which is kept: `obsidian-settings-changed`), and the
+//     temporary name removed. A reader never sees a part of the file.
+//
+// There is nothing to back up. A refusal removes what it created, the
+// directory included.
+function createObsidianSettings({ userDataDir, vaultRoot, absent, now, randomBytes, uid }) {
+  const owned = (stat) => uid === null || stat.uid === uid
+  let directory = null
+  try { directory = fs.lstatSync(userDataDir) } catch (error) { if (error.code !== 'ENOENT') return refused('obsidian-settings-unreadable', 'the Obsidian settings directory cannot be read') }
+  let folder
+  try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
+  if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
+  let madeDirectory = false
+  if (directory === null) {
+    const parent = path.dirname(userDataDir)
+    let above
+    try { above = fs.lstatSync(parent) } catch { above = null }
+    if (above === null || above.isSymbolicLink() || !above.isDirectory() || !owned(above)) return refused('obsidian-settings-missing', 'Obsidian has no settings directory on this account, and the folder it would be in is missing, a link or not this user\'s own')
+    try { fs.mkdirSync(userDataDir, { mode: 0o700 }) } catch (error) {
+      return refused(error.code === 'EEXIST' ? 'obsidian-settings-changed' : 'obsidian-settings-unwritable', 'the Obsidian settings directory cannot be created')
+    }
+    madeDirectory = true
+    directory = fs.lstatSync(userDataDir)
+  }
+  const removeDirectory = () => { if (madeDirectory) try { fs.rmdirSync(userDataDir) } catch { /* something else is in it now: it stays */ } }
+  if (directory.isSymbolicLink() || !directory.isDirectory()) return refused('obsidian-settings-unsafe', 'the Obsidian settings directory is a link or not a directory')
+  if (!owned(directory)) return refused('obsidian-settings-not-owned', 'the Obsidian settings directory belongs to another user')
+  const id = randomBytes(8).toString('hex')
+  const at = now()
+  const document = { vaults: { [id]: { path: folder, ts: at, open: true } }, cli: true }
+  const bytes = Buffer.from(JSON.stringify(document), 'utf8')
+  if (bytes.length > MAX_OBSIDIAN_SETTINGS_BYTES) { removeDirectory(); return refused('obsidian-settings-too-large', 'with this vault the Obsidian settings file would be larger than a settings file can be') }
+  const file = path.join(userDataDir, OBSIDIAN_SETTINGS_FILE)
+  const temporary = path.join(userDataDir, `.${OBSIDIAN_SETTINGS_FILE}.atelier-${randomBytes(6).toString('hex')}.tmp`)
+  const undo = () => { try { fs.unlinkSync(temporary) } catch { /* already gone */ } removeDirectory() }
+  try { writeNewFile(temporary, bytes, 0o600) } catch { undo(); return refused('obsidian-settings-unwritable', 'the Obsidian settings directory cannot be written') }
+  // Immediately before the file appears: still no app.
+  if (!absent()) { undo(); return refused('app-may-be-running', 'an Obsidian process appeared, and its settings belong to it') }
+  try { fs.linkSync(temporary, file) } catch (error) {
+    undo()
+    return refused(error.code === 'EEXIST' ? 'obsidian-settings-changed' : 'obsidian-settings-unwritable', error.code === 'EEXIST' ? 'an Obsidian settings file appeared while it was being created, and it was kept as it is' : 'the Obsidian settings file cannot be created')
+  }
+  try { fs.unlinkSync(temporary) } catch { /* the file is complete; a second name is refused by the next write */ }
+  try { syncPrivateDirectory(userDataDir); if (madeDirectory) syncPrivateDirectory(path.dirname(userDataDir)) } catch { /* the file exists; a directory that cannot be fsynced is not undone */ }
+  const stillAbsent = absent()
+  const written = readObsidianSettings({ userDataDir, uid })
+  const entry = written.ok ? findVaultEntry(written.vaults, vaultRoot) : null
+  const reason = !stillAbsent ? 'app-started-during-registration' : entry === null ? 'registration-not-read-back' : null
+  return {
+    ok: true, registered: 'created', entry: entry ?? { id, path: folder, open: true }, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
+    file, created: { directory: madeDirectory }, cliTurnedOn: true, ...(reason === null ? {} : { reason }),
+  }
+}
+
+// { ok: true, registered: 'already' | 'written' | 'created', entry: { id, path, open }, confirmed, vaults, file, cliTurnedOn,
+// backupPath?, created?, reason? } or a typed refusal { ok: false, code, message }. `registered` is 'already' when the
+// list had the vault (then the file was written only to turn the command line on, `cliTurnedOn`), 'written' when this
+// vault was added to an existing file, 'created' when the file was created (createObsidianSettings). `confirmed` is
+// false when an app appeared right after the rename (`app-started-during-registration`): it may have read the list
+// before it, so whoever asked verifies through the app; and when the written file could not be read back to find the
+// entry (`registration-not-read-back`). `vaults` is the list as it was found or written. `processProbe()` answers
+// 'absent', 'running' or 'unknown'; only 'absent' allows a write. `sandbox` names a Flatpak or snap build found for
 // this account, which refuses (`obsidian-sandboxed`).
-export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, sandbox = null, now = () => Date.now(), randomBytes = cryptoRandomBytes, uid = currentUid() } = {}) {
+// `keepBackups`: backup names (in the file's directory) this write must not prune: the copy `open` kept before it
+// quit the app for this write.
+export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, sandbox = null, now = () => Date.now(), randomBytes = cryptoRandomBytes, uid = currentUid(), keepBackups = [] } = {}) {
   if (typeof processProbe !== 'function') throw new TypeError('registering a vault needs a process probe')
   if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot) || vaultRoot.includes('\u0000')) throw new TypeError('vaultRoot must be an absolute path')
   if (sandbox !== null) return refused('obsidian-sandboxed', `this Obsidian is a ${sandbox} build, which reads its vault list inside its sandbox, where Atelier does not write`)
   const absent = () => { try { return processProbe() === 'absent' } catch { return false } }
   if (!absent()) return refused('app-may-be-running', 'an Obsidian process may be running, and its vault list belongs to it')
   const settings = readObsidianSettings({ userDataDir, uid })
+  // No file: Obsidian never started on this account. A missing directory is refused as missing when it has no parent.
+  if (!settings.ok && settings.code === 'obsidian-settings-missing' && typeof userDataDir === 'string' && path.isAbsolute(userDataDir)) return createObsidianSettings({ userDataDir, vaultRoot, absent, now, randomBytes, uid })
   if (!settings.ok) return settings
   const known = findVaultEntry(settings.vaults, vaultRoot)
-  if (known) return { ok: true, registered: 'already', entry: known, confirmed: true, vaults: settings.vaults }
+  const switchOn = settings.document.cli !== true
+  if (known && !switchOn) return { ok: true, registered: 'already', entry: known, confirmed: true, vaults: settings.vaults, file: settings.file, cliTurnedOn: false }
   if (settings.links > 1) return refused('obsidian-settings-unsafe', 'the Obsidian settings file has a second name (a hard link), which a replacement would leave with the old list')
-  if (enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return refused('vault-inside-another-vault', 'Obsidian lists a vault at a folder that contains this vault\'s folder')
+  if (!known && enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return refused('vault-inside-another-vault', 'Obsidian lists a vault at a folder that contains this vault\'s folder')
 
-  let folder
-  try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
-  if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
-  let id
-  do { id = randomBytes(8).toString('hex') } while (Object.hasOwn(settings.vaults, id))
+  let folder = null
+  let id = null
+  if (!known) {
+    try { folder = realPathAsStored(vaultRoot) } catch { return refused('vault-root-missing', 'the view\'s vault folder does not exist') }
+    if (!fs.statSync(folder).isDirectory()) return refused('vault-root-missing', 'the view\'s vault folder is not a directory')
+    do { id = randomBytes(8).toString('hex') } while (Object.hasOwn(settings.vaults, id))
+  }
   const at = now()
-  const document = { ...settings.document, vaults: { ...settings.vaults, [id]: { path: folder, ts: at, open: true } } }
+  // The switch keeps its place when the file has one; otherwise it is added last, as the app would.
+  const document = { ...settings.document, ...(known ? {} : { vaults: { ...settings.vaults, [id]: { path: folder, ts: at, open: true } } }), ...(switchOn ? { cli: true } : {}) }
   const bytes = Buffer.from(JSON.stringify(document), 'utf8')
   if (bytes.length > MAX_OBSIDIAN_SETTINGS_BYTES) return refused('obsidian-settings-too-large', 'with this vault the Obsidian settings file would be larger than a settings file can be')
   const directory = path.dirname(settings.file)
@@ -140,15 +226,76 @@ export function registerVaultInObsidianSettings({ userDataDir, vaultRoot, proces
   }
   created.splice(0)
   try { syncPrivateDirectory(directory) } catch { /* the rename is done; a directory that cannot be fsynced is not undone */ }
-  pruneBackups(directory, path.basename(backupPath))
+  pruneBackups(directory, path.basename(backupPath), (Array.isArray(keepBackups) ? keepBackups : []).filter((name) => typeof name === 'string').map((name) => path.basename(name)))
   const stillAbsent = absent()
   const written = readObsidianSettings({ userDataDir, uid })
   const entry = written.ok ? findVaultEntry(written.vaults, vaultRoot) : null
   const reason = !stillAbsent ? 'app-started-during-registration' : entry === null ? 'registration-not-read-back' : null
   return {
-    ok: true, registered: 'written', entry: entry ?? { id, path: folder, open: true }, backupPath, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
-    ...(reason === null ? {} : { reason }),
+    ok: true, registered: known ? 'already' : 'written', entry: entry ?? known ?? { id, path: folder, open: true }, backupPath, confirmed: reason === null, vaults: written.ok ? written.vaults : document.vaults,
+    file: settings.file, cliTurnedOn: switchOn, ...(reason === null ? {} : { reason }),
+  }
+}
+
+// Read-only, for `open` before it quits a running app to restart it: whether registerVaultInObsidianSettings would
+// write this vault into the settings file `settings` (a readObsidianSettings answer, read while the app runs), as far
+// as a read can tell. { ok: true, create } or { ok: false, code } with the refusal the write would give: an
+// unreadable, linked, foreign, sandboxed or too large file, a vault inside another listed vault, a vault folder that
+// is missing. A file that does not exist (an app that has shown only its starter window writes none) is the create
+// case, `create: true`, checked as createObsidianSettings checks before it writes: the vault folder is a directory,
+// and the user-data directory is this user's own real directory, or is absent inside this user's own real parent.
+// What only the moment of the write can tell (an app that appears, a file that changes) is still checked then.
+export function settingsWriteOutlook({ settings, vaultRoot, now = () => Date.now(), uid = currentUid() } = {}) {
+  const no = (code) => ({ ok: false, code })
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return no('vault-root-missing')
+  if (settings?.ok !== true && settings?.code === 'obsidian-settings-missing') {
+    const userDataDir = settings.userDataDir
+    if (typeof userDataDir !== 'string' || !path.isAbsolute(userDataDir)) return no('obsidian-settings-location-unknown')
+    try { if (!fs.statSync(realPathAsStored(vaultRoot)).isDirectory()) return no('vault-root-missing') } catch { return no('vault-root-missing') }
+    const owned = (stat) => uid === null || stat.uid === uid
+    let directory = null
+    try { directory = fs.lstatSync(userDataDir) } catch (error) { if (error.code !== 'ENOENT') return no('obsidian-settings-unreadable') }
+    if (directory !== null) {
+      if (directory.isSymbolicLink() || !directory.isDirectory()) return no('obsidian-settings-unsafe')
+      return owned(directory) ? { ok: true, create: true } : no('obsidian-settings-not-owned')
+    }
+    let above = null
+    try { above = fs.lstatSync(path.dirname(userDataDir)) } catch { above = null }
+    return above !== null && !above.isSymbolicLink() && above.isDirectory() && owned(above) ? { ok: true, create: true } : no('obsidian-settings-missing')
+  }
+  if (settings?.ok !== true) return no(typeof settings?.code === 'string' ? settings.code : 'obsidian-settings-unreadable')
+  if (typeof settings.links === 'number' && settings.links > 1) return no('obsidian-settings-unsafe')
+  const size = Buffer.isBuffer(settings.bytes) ? settings.bytes.length : 0
+  const known = findVaultEntry(settings.vaults, vaultRoot)
+  if (known) return size + 16 > MAX_OBSIDIAN_SETTINGS_BYTES ? no('obsidian-settings-too-large') : { ok: true, create: false }
+  if (enclosingVaults({ vaults: settings.vaults, vaultRoot }).length > 0) return no('vault-inside-another-vault')
+  let folder
+  try { folder = realPathAsStored(vaultRoot); if (!fs.statSync(folder).isDirectory()) return no('vault-root-missing') } catch { return no('vault-root-missing') }
+  const entry = Buffer.byteLength(JSON.stringify({ '0123456789abcdef': { path: folder, ts: now(), open: true } }), 'utf8')
+  return size + entry + 16 > MAX_OBSIDIAN_SETTINGS_BYTES ? no('obsidian-settings-too-large') : { ok: true, create: false }
+}
+
+// Keeps a copy of the settings file as it is, beside it, under the backup name the write uses
+// (`obsidian.json.atelier-backup-<UTC time>`), fsynced, with the file's mode. Read-only for the file itself. `open`
+// takes it right before the first signal to a running app, so a list the app was writing when it ended can be
+// restored. { ok: true, backupPath } or a typed refusal (readObsidianSettings's, or `obsidian-settings-unwritable`).
+// The write that follows in the same run keeps it (`keepBackups`); a later write prunes it as any other backup.
+export function backupObsidianSettings({ userDataDir, now = () => Date.now(), uid = currentUid() } = {}) {
+  const settings = readObsidianSettings({ userDataDir, uid })
+  if (!settings.ok) return settings
+  const directory = path.dirname(settings.file)
+  for (let offset = 0; offset < 3; offset += 1) {
+    const backupPath = path.join(directory, `${OBSIDIAN_SETTINGS_FILE}.atelier-backup-${compactUtc(now() + offset)}`)
+    try {
+      writeNewFile(backupPath, settings.bytes, settings.mode)
+    } catch (error) {
+      if (error.code === 'EEXIST') continue
+      return refused('obsidian-settings-unwritable', 'a copy of the Obsidian settings file cannot be kept beside it')
+    }
+    try { syncPrivateDirectory(directory) } catch { /* the copy is written */ }
+    return { ok: true, backupPath }
   }
+  return refused('obsidian-settings-unwritable', 'a copy of the Obsidian settings file cannot be kept beside it')
 }
 
 // What the app looks like, as one comparable text, from what can be seen