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

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

@@ -0,0 +1,154 @@
+import path from 'node:path'
+import { performance } from 'node:perf_hooks'
+
+// Quitting a running Obsidian so that `open` can add a vault and turn its
+// command line on, only when a person asked for it (`--restart-obsidian`).
+//
+// `open` restarts the app in two states only, where it runs but cannot be
+// reached: its command line is turned off, or no vault is open (and the app
+// does not list the view's vault). The settings file then belongs to the
+// running app, which would write its own list back over any change, and the
+// app cannot be asked to add a vault. Before anything is sent, `open` checks,
+// read-only, that the write the restart is for can succeed (opening.mjs); right
+// before the first signal, once the main process is proven, `beforeSignal` keeps
+// a copy of the settings file, and a copy that cannot be kept sends nothing.
+//
+// SIGTERM, which Electron handles as a quit, is sent to one process: the app's
+// main process, proven from the process table, and never to anything else. The
+// main process is proven when, in a table of this machine's processes as
+// `pid ppid uid comm` (`comm` is the process's argv[0] as macOS reports it, not
+// a verified image: a process of this user can name itself anything, which is
+// why two candidates prove nothing):
+//
+//   - every process of the app (the names the process probe counts: `Obsidian`
+//     and the bundle's `Obsidian Helper…`) runs as this user;
+//   - exactly one of them names the app bundle's main executable by an absolute
+//     path (`…/Contents/MacOS/Obsidian`); a process shown by its short name
+//     only is not proven;
+//   - every other one is a child of that process (its helpers).
+//
+// Anything else (two instances, another user's app, a helper of another
+// parent, a table that cannot be read) is `app-main-process-unproven`, and no
+// signal is sent. Immediately before the signal the one process is read again
+// (`ppid uid start-time comm`) and must be of this user, under the parent the
+// table showed, with the same name, and read the same twice.
+//
+// What SIGTERM does (1.13.7, checked on an isolated instance): the app handles
+// the first one as a quit. It closes every window, keeping the vaults that were
+// open flagged open in its list, and its helper processes end; on macOS the main
+// process can then stay, with no window, as a macOS app does. Electron handles
+// only the first SIGTERM as a quit: a second one ends the process at once,
+// without its quit handlers. It is sent only after that same process has shown
+// no window and no helper (it is alone in the table, and reads the same) at
+// every reading for at least `lingerMs`, measured on a monotonic clock; a
+// reading that cannot be parsed does not count as alone. That is a margin, not
+// a proof that nothing is left to save. There is never a third signal, and
+// never another kind; an app that is still not gone is reported
+// (`app-did-not-quit`) and left to the person. `signals` counts the signals
+// that were delivered.
+//
+// Qualified on macOS only: on Linux a quit app is started again with a link,
+// which drops the other vaults' reopen flags (launch-plan.mjs), so the promise
+// that they reopen would not hold there.
+//
+// Nothing here reads the process table or sends a signal itself: every seam is
+// injected, with no default. Only the production seams module of the command
+// entry and the opt-in real-app suite, for its isolated app, construct one.
+
+export const RESTART_PLATFORMS = Object.freeze(['darwin'])
+const APP_PROCESS = /^obsidian(?: helper\b.*)?$/i
+const MAIN_EXECUTABLE = /^\/.+\.app\/Contents\/MacOS\/Obsidian$/i
+// `pid ppid uid comm`. macOS prints the uid of `nobody` as -2: a uid is signed.
+export const PROCESS_ROW = /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(.+?)\s*$/
+// `ppid uid start-time comm`, one process read again.
+const DESCRIBED = /^\s*(\d+)\s+(-?\d+)\s+(.+?)\s*$/
+
+const unproven = (detail) => ({ state: 'unproven', reason: 'app-main-process-unproven', detail })
+const rowsOf = (table) => table.split('\n').filter((line) => line.trim() !== '').map((line) => PROCESS_ROW.exec(line))
+
+// Pure. The app's main process in a process table (`ps -A -o pid=,ppid=,uid=,comm=`), for the account `uid`:
+// { state: 'proven', pid, ppid, executable } | { state: 'absent' } | { state: 'unproven', reason, detail }.
+export function provenMainProcess({ table, uid } = {}) {
+  if (typeof table !== 'string' || table.trim() === '') return unproven('the process table could not be read')
+  if (!Number.isSafeInteger(uid) || uid < 0) return unproven('the account is not known')
+  const matches = rowsOf(table)
+  if (matches.some((match) => match === null)) return unproven('the process table has a line that is not a process')
+  const rows = matches.map((match) => ({ pid: Number(match[1]), ppid: Number(match[2]), uid: Number(match[3]), executable: match[4] }))
+  const app = rows.filter((row) => APP_PROCESS.test(path.posix.basename(row.executable)))
+  if (app.length === 0) return { state: 'absent' }
+  if (app.some((row) => row.uid !== uid)) return unproven('an Obsidian process runs as another user')
+  const main = app.filter((row) => /^obsidian$/i.test(path.posix.basename(row.executable)))
+  if (main.length !== 1) return unproven(main.length === 0 ? 'no Obsidian main process is in the process table' : 'more than one Obsidian main process runs')
+  const [one] = main
+  if (!MAIN_EXECUTABLE.test(one.executable)) return unproven('the main process does not name the app bundle\'s executable')
+  if (app.some((row) => row !== one && row.ppid !== one.pid)) return unproven('an Obsidian helper process is not a child of the main process')
+  return { state: 'proven', pid: one.pid, ppid: one.ppid, executable: one.executable }
+}
+
+// `readTable()`      -> the process table as provenMainProcess reads it (throws or answers '' when it cannot)
+// `readProcess(pid)` -> that process read again as `ppid uid start-time comm`, or null
+// `signal(pid)`      -> sends SIGTERM to exactly that pid; throws when it was not delivered
+// `processProbe()`   -> 'running' | 'absent' | 'unknown', the probe the settings write uses
+//
+// quit({ beforeSignal }) answers { quit: true, pid, signalled, signals, settingsCopy? } once the probe says `absent`,
+// or { quit: false, reason, signalled, signals, pid?, detail?, settingsCopy? }: `restart-platform-unqualified`,
+// `app-main-process-unproven` and the refusal of `beforeSignal` before any signal, `app-did-not-quit` after one, when
+// the probe did not say `absent` within `waitMs`. `beforeSignal()`, when given, runs once the main process is proven
+// and read again, immediately before the first signal: { ok: true, backupPath? } lets it be sent, anything else
+// ({ ok: false, code }) sends nothing. `now` is a monotonic clock in milliseconds.
+export function createAppQuitter({ platform, uid, readTable, readProcess, signal, processProbe, sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) }), now = () => performance.now(), waitMs = 30_000, pollMs = 250, lingerMs = 5000 } = {}) {
+  for (const [name, seam] of Object.entries({ readTable, readProcess, signal, processProbe })) if (typeof seam !== 'function') throw new TypeError(`quitting Obsidian needs an injected ${name}`)
+  const probe = () => { try { return processProbe() } catch { return 'unknown' } }
+  const describe = (pid) => { try { const line = readProcess(pid); return typeof line === 'string' && line.trim() !== '' ? line.trim() : null } catch { return null } }
+  const table = () => { try { const text = readTable(); return typeof text === 'string' ? text : '' } catch { return '' } }
+  // The process read again is the one the table proved: this user's, under the parent the table showed, same name.
+  const isFound = (line, found) => {
+    const match = line === null ? null : DESCRIBED.exec(line)
+    return match !== null && Number(match[1]) === found.ppid && Number(match[2]) === uid && match[3].endsWith(found.executable)
+  }
+  // The proven main process alone in the table, still the process `seen` described: its windows closed, it did not quit.
+  const lingersAlone = (found, seen) => {
+    const matches = rowsOf(table())
+    if (matches.length === 0 || matches.some((match) => match === null)) return false
+    const rows = matches.filter((match) => APP_PROCESS.test(path.posix.basename(match[4])))
+    return rows.length === 1 && Number(rows[0][1]) === found.pid && describe(found.pid) === seen
+  }
+  return {
+    async quit({ beforeSignal = null } = {}) {
+      if (!RESTART_PLATFORMS.includes(platform)) return { quit: false, reason: 'restart-platform-unqualified', signalled: false, signals: 0 }
+      const found = provenMainProcess({ table: table(), uid })
+      if (found.state === 'absent') return probe() === 'absent' ? { quit: true, pid: null, signalled: false, signals: 0 } : { quit: false, reason: 'app-main-process-unproven', detail: 'the process table shows no Obsidian, and the process probe does not say it is gone', signalled: false, signals: 0 }
+      if (found.state !== 'proven') return { quit: false, reason: found.reason, detail: found.detail, signalled: false, signals: 0 }
+      const seen = describe(found.pid)
+      if (!isFound(seen, found)) return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process read again is not the one the table showed', signalled: false, signals: 0 }
+      // Immediately before the signal: still the same process.
+      if (describe(found.pid) !== seen) return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process changed while it was being proven', signalled: false, signals: 0 }
+      let copy = {}
+      if (typeof beforeSignal === 'function') {
+        let kept
+        try { kept = await beforeSignal() } catch { kept = null }
+        if (kept?.ok !== true) return { quit: false, reason: typeof kept?.code === 'string' ? kept.code : 'obsidian-settings-unwritable', signalled: false, signals: 0 }
+        if (typeof kept.backupPath === 'string') copy = { settingsCopy: kept.backupPath }
+      }
+      try { signal(found.pid) } catch { return { quit: false, reason: 'app-main-process-unproven', detail: 'the main process could not be signalled', signalled: false, signals: 0, ...copy } }
+      let signals = 1
+      let second = false
+      let aloneSince = null
+      const deadline = now() + waitMs
+      for (;;) {
+        if (probe() === 'absent') return { quit: true, pid: found.pid, signalled: true, signals, ...copy }
+        if (now() >= deadline) return { quit: false, reason: 'app-did-not-quit', pid: found.pid, signalled: true, signals, ...copy }
+        if (!second) {
+          if (!lingersAlone(found, seen)) aloneSince = null
+          else if (aloneSince === null) aloneSince = now()
+          else if (now() - aloneSince >= lingerMs) {
+            // Once, whether or not it is delivered.
+            second = true
+            try { signal(found.pid); signals = 2 } catch { /* not delivered: not counted */ }
+          }
+        }
+        await sleep(pollMs)
+      }
+    },
+  }
+}

package/src/runtime/obsidian/engine.mjs

@@ -2,11 +2,12 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, manifestLayoutVersion } from '../../projection/obsidian/contracts.mjs'
+import { PERSONAL_VALIDATION_PENDING, personalWorkspaceBindingOf, personalWorkspaceInputs, validatePersonalWorkspace } from '../../projection/obsidian/personal-workspace.mjs'
 import { PROTOCOL_ID } from '../../projection/obsidian/publication/bridge-script.mjs'
-import { PublicationRefusal } from '../../projection/obsidian/recovery/store.mjs'
+import { PublicationRefusal, allocatedFolderState, hasCommittedGeneration, readVaultAllocation } from '../../projection/obsidian/recovery/store.mjs'
 import { canonicalJson, compareText, isoTime } from './documents.mjs'
 import { readObsidianEnablement } from './enablement.mjs'
-import { ObsidianMaintenanceRefusal } from './errors.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { createMaintenanceExtensions } from './extension-points.mjs'
 import {
   assertOutsideRepositories, authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, protectedRoots, readLocalPointer,
@@ -14,10 +15,12 @@ import {
 } from './machine-settings.mjs'
 import { configKey, listConfigFiles, listSourceFiles, listVaultNotes, readFileFacts, reconcile, sha256Digest, sourceKey, vaultKey } from './observation.mjs'
 import { dispatchAutomaticApply, heldPaths, layoutHeldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
-import { DEFAULT_ELIGIBILITY, createProductionSeams } from './pipeline.mjs'
+import { createProductionSeams, eligibilityFor } from './pipeline.mjs'
+import { PLUGIN_FILES_WAIT_FOR_APP } from './plugin-presence.mjs'
 import { ENGINE_LOCK_DIRECTORY, acquirePrivateGenerationLock, createAbandonmentProof } from './private-lock.mjs'
 import { probeHealth } from './service-client.mjs'
 import { FRESHNESS_SCHEMA, LATE_WRITERS_SCHEMA, createMaintenanceStateStore } from './state-store.mjs'
+import { ensureVaultAllocation, projectDisplayName } from './vault-location.mjs'
 import { createNullWatcherFactory } from './watchers.mjs'
 
 // The maintenance engine. One explicit `tick()`; no timer, no process, no
@@ -126,7 +129,15 @@ export const ENGINE_PRIMITIVES = Object.freeze({
 })
 
 const isTypedRefusal = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal || error instanceof PublicationRefusal
+// The code a view is refused with when its own vault cannot be placed: a typed refusal's, or `vault-location-unusable`
+// for a file-system error there (a file in the way, no permission, a read-only volume). Null for anything else, which
+// is a fault of the engine and stops the tick.
+const viewRefusalCode = (error) => (isTypedRefusal(error) ? error.code : typeof error?.code === 'string' && /^E[A-Z]+$/.test(error.code) ? 'vault-location-unusable' : null)
 const digestOfJson = (value) => sha256Digest(Buffer.from(canonicalJson(value)))
+// The configuration a tick observes. A project bound to a personal workspace adds the person's authored manifest and
+// overlay and its generation's record: a change to any of them is a configuration change, so every view is prepared
+// again, asks the composition, and is refused at once when the generation no longer holds.
+const configFilesOf = (project) => [...listConfigFiles(project), ...personalWorkspaceInputs(project).map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))]
 
 // An editor adapter that `build` makes, synchronously or not, the first time the publisher calls it; a refusal of
 // `build` is thrown from that call, and `refusal()` answers it afterwards.
@@ -142,6 +153,11 @@ function builtOnFirstUse(build) {
     publish: async (payload) => (await built()).publish(payload),
   }
 }
+// The adapter a publication gets when the factory refused the app: it coordinates with nothing and never calls it.
+function uncoordinatedAdapter(refusal) {
+  const never = async () => { throw refusal }
+  return { probe: async () => ({ state: 'uncoordinated', reason: `${refusal.code}: the installed Obsidian does not qualify, and nothing is published through it` }), inspect: never, collect: never, publish: never }
+}
 // Views a tick may be asked to prepare again, at most, before it runs.
 const MAX_PREPARATION_REQUESTS = 64
 
@@ -166,9 +182,19 @@ function journalsToRecheck(store, { nowMs, full, windowMs }) {
 export function createMaintenanceEngineForOracleTests(options = {}, primitives = ENGINE_PRIMITIVES) {
   const {
     loadProject, dataRoot, adapterFactory, clock,
-    watcherFactory = createNullWatcherFactory(), extensions = createMaintenanceExtensions(), eligibility = DEFAULT_ELIGIBILITY,
+    // Which notes may enter a view: what the machine settings decide at each tick (eligibilityFor), unless a test fixes it.
+    watcherFactory = createNullWatcherFactory(), extensions = createMaintenanceExtensions(), eligibility: fixedEligibility = null,
     fullReconciliationIntervalMs = DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, lateWriterWindowMs = DEFAULT_LATE_WRITER_WINDOW_MS,
     publicationRetryMs = DEFAULT_PUBLICATION_RETRY_MS, observeApp = null,
+    // Reads the app's own vault list without asking the app (readAppVaultListForAllocation): { ok: true, vaults } with
+    // the map id -> { path }, or { ok: false, code }. A folder for a new vault is never allocated inside a vault it
+    // lists, nor under a name a vault it lists already has, nor while the list cannot be read.
+    readAppVaultList = null,
+    // Reads the app's own vault list from its file, without asking the app (unheld-evidence.mjs): { unlisted: true } only
+    // when no list names a view's vault, a folder above it or one inside it. A view never published into its allocated
+    // folder is then published even while an app runs that cannot be coordinated with, creating files only (the
+    // publisher's `direct-unheld` path). An engine given no reader never takes that path.
+    readUnheldEvidence = null,
     quietPeriodMs, lstat = fs.lstatSync, randomBytes, env = process.env, platform = process.platform,
     // A service names where it answers health, so a lock it leaves behind can be proven abandoned.
     lockOwner = null, lockProbe = probeHealth,
@@ -215,6 +241,14 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   const waitingForApp = new Map()
   const proveAbandoned = createAbandonmentProof({ probe: lockProbe })
 
+  // Whether a view kept from publication by an app that does not qualify may still be published on the publisher's
+  // `direct-unheld` path: never committed, its vault the folder allocated for it, and the app's list naming no folder
+  // on the way. The publisher checks every condition again, under its locks.
+  async function unheldMayApply(store, pointer) {
+    if (typeof readUnheldEvidence !== 'function' || pointer !== null || store.vaultOrigin !== 'allocated') return false
+    try { return (await readUnheldEvidence({ vaultRoot: store.vaultRoot }))?.unlisted === true } catch { return false }
+  }
+
   async function takeLock(workspaceRoot, workspaceId) {
     if (heldLock) return { acquired: true }
     const lock = await rules.acquireEngineLock({
@@ -249,9 +283,18 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   }
 
   function storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) {
-    const signature = JSON.stringify([workspaceRoot, workspaceId, repositoryRoots])
+    // A view's vault can be allocated, made again or moved while the engine runs: the store follows its record. A
+    // store is used again only while its allocated folder is still the one the record names; otherwise it is dropped,
+    // and the store made in its place refuses, typed (vault-allocation-replaced, say), so a folder replaced while the
+    // service runs, or a link put where it was, is never published into.
+    const signature = JSON.stringify([workspaceRoot, workspaceId, repositoryRoots, readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })])
     const cached = stores.get(scope.scopeId)
-    if (cached?.signature === signature) return cached.store
+    // A vault root that is gone (a folder under the data root the person removed, say) is looked for again too, so the
+    // store made in its place says why rather than failing on the folder that is not there.
+    if (cached?.signature === signature && fs.lstatSync(cached.store.vaultRoot, { throwIfNoEntry: false }) !== undefined) {
+      try { cached.store.checkAllocatedVault?.(); return cached.store } catch (error) { if (!isTypedRefusal(error)) throw error }
+    }
+    stores.delete(scope.scopeId)
     const store = seams.createRecoveryStore({ workspaceRoot, workspaceId, scopeId: scope.scopeId, repositoryRoots })
     stores.set(scope.scopeId, { signature, store })
     return store
@@ -318,15 +361,19 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
 
     // 1. Project and enablement. The digests are seeded before the project is
     // loaded for good, so the loaded project is never older than the index.
+    // A loader may answer a promise (one that composes a personal workspace off
+    // the event loop). A project bound to a personal workspace is loaded once:
+    // what a generation holds is fixed, and an input that changed after the load
+    // changes the validity key every build is checked against.
     if (project === null) {
-      project = loadProject()
-      reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full: true, lstat })
-      project = loadProject()
+      project = await loadProject()
+      reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full: true, lstat })
+      if (personalWorkspaceBindingOf(project) === null) project = await loadProject()
     } else {
-      const config = reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full, hinted, lstat })
+      const config = reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full, hinted, lstat })
       if (config.changes.length > 0) {
-        project = loadProject()
-        reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full: true, lstat })
+        project = await loadProject()
+        reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full: true, lstat })
       }
     }
     const enablement = readObsidianEnablement(project)
@@ -351,14 +398,63 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (!lock.acquired) return { state: 'busy', reason: 'engine-lock-held', lock: { reason: lock.reason, holder: lock.holder ?? null }, changes: [], scopes: [], pendingEdits: [], dispatched: [], lateWriters: [] }
     const machine = readMachineSettings({ workspaceRoot, workspaceId })
       ?? writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: defaultMachineSettings({ workspaceId, updatedAt: now }) })
+    const eligibility = fixedEligibility ?? eligibilityFor({ machine, project })
     const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
     known = { stateStore, maintenanceMode: machine.maintenanceMode }
-    const scopes = enablement.scopes.map((scope) => ({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }))
+    // Each view's vault: allocated now where this workspace decided its vaults live, when it has none and was never
+    // published under the data root (vault-location.mjs). A view whose folder cannot be allocated is not prepared on
+    // this tick, and its freshness says why; the other views go on.
+    const allocationRefusals = new Map()
+    if (machine.decisions.location !== null) {
+      // The app's list, read once per tick and only when a view is about to be allocated. An engine given no reader
+      // coordinates with no app, and knows no list. A list that cannot be read allocates nothing: the view says why,
+      // and its folder is allocated at a later tick, once the list reads.
+      let list = null
+      const appList = async () => {
+        if (typeof readAppVaultList !== 'function') return { ok: true, vaults: null }
+        if (list === null) {
+          let answer
+          try { answer = await readAppVaultList() } catch { answer = null }
+          list = answer?.ok === true ? { ok: true, vaults: answer.vaults ?? {} } : { ok: false, code: typeof answer?.code === 'string' ? answer.code : 'obsidian-settings-unreadable' }
+        }
+        return list
+      }
+      // The folders allocated to the views; a record that cannot be read refuses only its own view, below.
+      const allocatedPaths = enablement.scopes.map((scope) => { try { return readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })?.path } catch { return undefined } }).filter((item) => typeof item === 'string')
+      for (const scope of enablement.scopes) {
+        try {
+          let vaults = null
+          // The list is read where a folder is about to be made: a first allocation, or an allocated folder that has gone.
+          const record = readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })
+          if (record === null ? !hasCommittedGeneration({ workspaceRoot, scopeId: scope.scopeId }) : allocatedFolderState(record) === 'missing') {
+            const known = await appList()
+            if (!known.ok) refuse('app-vault-list-unreadable', 'Obsidian\'s vault list could not be read, so no folder is allocated for this view yet; it is tried again at the next tick', { cause: known.code })
+            vaults = known.vaults
+          }
+          ensureVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId, location: machine.decisions.location, projectName: projectDisplayName(project), repositoryRoots, vaults, allocatedPaths, now })
+        } catch (error) {
+          const code = viewRefusalCode(error)
+          if (code === null) throw error
+          allocationRefusals.set(scope.scopeId, code)
+        }
+      }
+    }
+    // Each view's store, on its own: one whose vault cannot be placed (a record naming a folder inside a repository,
+    // say) is refused alone, and the other views go on.
+    const scopes = []
+    for (const scope of enablement.scopes) {
+      if (allocationRefusals.has(scope.scopeId)) continue
+      try { scopes.push({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }) } catch (error) {
+        const code = viewRefusalCode(error)
+        if (code === null) throw error
+        allocationRefusals.set(scope.scopeId, code)
+      }
+    }
 
     watch([
       ...(project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => ({ id: `repo:${repo.name}`, path: repo.path, recursive: true, keyPrefix: sourceKey(repo.name, ''), keyOf: (relative) => sourceKey(repo.name, relative) })),
       ...scopes.map(({ scope, store }) => ({ id: `vault:${scope.scopeId}`, path: store.vaultRoot, recursive: true, keyPrefix: vaultKey(scope.scopeId, ''), keyOf: (relative) => vaultKey(scope.scopeId, relative) })),
-      ...[...new Set(listConfigFiles(project).map((file) => path.dirname(file.absolute)))].filter((directory) => fs.existsSync(directory))
+      ...[...new Set(configFilesOf(project).map((file) => path.dirname(file.absolute)))].filter((directory) => fs.existsSync(directory))
         .map((directory) => ({ id: `config:${directory}`, path: directory, recursive: false, keyPrefix: CONFIG_PREFIX, keyOf: (relative) => configKey(path.join(directory, relative)) })),
     ])
 
@@ -385,9 +481,12 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     // Observation. The registered proposal adapter is handed a copy of the pending edits and observes the open ones
     // the object store does not know yet, a bounded number per tick: each is classified from its preserved bytes
     // against the source as it is now and recorded as what it is, in manual and in automatic mode alike, and no
-    // source is written. What refused before anything was recorded is offered again on a full reconciliation only.
+    // source is written. What refused before anything was recorded is offered again on a full reconciliation only;
+    // for a personal workspace, also on the tick after one whose graph was pending, which offers every earlier
+    // refusal again.
     const proposalAdapter = extensions.get('proposal-adapter')
-    const adapterContext = () => ({ project, workspaceRoot, workspaceId, repositoryRoots, edits: structuredClone(edits), clock, env })
+    // A personal workspace is never composed on this event loop by the adapter: its builds defer, as the engine's do.
+    const adapterContext = () => ({ project, workspaceRoot, workspaceId, repositoryRoots, edits: structuredClone(edits), clock, env, deferPersonalValidation: true })
     let observed = null
     if (proposalAdapter !== null && rules.observeEdits(proposalAdapter)) {
       try { observed = await proposalAdapter.observe(adapterContext(), { retryRefused: full }) } catch { observed = { adapterId: proposalAdapter.id, failed: 'proposal-adapter-threw' } }
@@ -455,7 +554,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (full) { lastFullMs = nowMs; forceFull = false }
 
     // 7. Which views are invalid.
-    declaredScopes = new Set(scopes.map(({ scope }) => scope.scopeId))
+    declaredScopes = new Set(enablement.scopes.map((scope) => scope.scopeId))
     const previous = readPreviousFreshness(stateStore)
     const entries = new Map()
     const unseen = new Set()
@@ -479,9 +578,21 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       if (earlierLayout.has(scope.scopeId) && entry.state === 'current' && layoutHeldOf(scope.scopeId).length === 0) invalidate(scope.scopeId, null)
     }
     for (const change of changes) for (const { scope } of scopes) if (change.scopeId === undefined || change.scopeId === scope.scopeId) invalidate(scope.scopeId, change.changeClass)
+    // A bound personal workspace is composed again, off the event loop, at every full reconciliation, whatever else is
+    // being prepared: a cause outside its validity key can stop a generation holding without a file this engine
+    // observes. Its views are prepared again only when the composition refuses, or confirms another key.
+    let personalRefusal = null
+    if (full && personalWorkspaceBindingOf(project) !== null) {
+      const verdict = await validatePersonalWorkspace(project)
+      if (verdict.ok !== true) personalRefusal = verdict.code
+      if (verdict.ok !== true || verdict.changed) for (const { scope } of scopes) invalidate(scope.scopeId, null)
+    }
 
     // Invalidation is durable before any work: a view is not reported current while it is being rebuilt.
     for (const [scopeId, classes] of attempt) entries.set(scopeId, { ...demote(entries.get(scopeId), 'stale', 'invalidated', now), changeClasses: [...classes].sort() })
+    for (const [scopeId, code] of allocationRefusals) {
+      entries.set(scopeId, demote(previous?.scopes.find((entry) => entry.scopeId === scopeId && entry.state !== 'disabled') ?? blankEntry(scopeId, now), 'stale', code, now))
+    }
     for (const entry of previous?.scopes ?? []) if (!entries.has(entry.scopeId)) entries.set(entry.scopeId, demote(entry, 'disabled', 'scope-not-configured', now))
     const persist = () => stateStore.writeFreshness(freshnessDocument({ workspaceId, enablement: 'enabled', maintenanceMode: machine.maintenanceMode, now, entries }))
     persist()
@@ -490,7 +601,19 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (attempt.size > 0) {
       let built = null
       try {
-        const graph = seams.buildGraph({ project, eligibility, cache: graphCache, index })
+        if (personalRefusal !== null) refuse(personalRefusal, 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
+        // A personal workspace whose validity key is not confirmed yet is composed off the event loop, then built again.
+        const build = () => seams.buildGraph({ project, eligibility, cache: graphCache, index, deferPersonalValidation: true })
+        let graph
+        try { graph = build() } catch (error) {
+          if (error?.code !== PERSONAL_VALIDATION_PENDING) throw error
+          const verdict = await validatePersonalWorkspace(project)
+          if (verdict?.ok !== true) refuse(verdict?.code ?? 'personal-binding-unrecognized', 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
+          try { graph = build() } catch (again) {
+            if (again?.code !== PERSONAL_VALIDATION_PENDING) throw again
+            refuse('personal-graph-unconfirmed', 'the graph built for the personal workspace is not the one its composition built; nothing is prepared from it', { source: 'personal-workspace' })
+          }
+        }
         // The assets this graph lets a view copy are observed from now on, and hashed now so the snapshot pins
         // what observation saw. A withheld asset is not observed: its bytes can change no view.
         const formerAssetKeys = new Set(observedAssets.map((asset) => sourceKey(asset.repo, asset.path)))
@@ -508,6 +631,9 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
         if (!isTypedRefusal(error)) throw error
         for (const scopeId of attempt.keys()) entries.set(scopeId, demote(entries.get(scopeId), 'stale', error.code, now))
         if (REREAD_CODES.has(error.code)) forceFull = true
+        // The personal workspace refused the bound generation: the project is loaded again at the next tick, so a
+        // loader that now binds another generation is followed.
+        if (error.detail?.source === 'personal-workspace') project = null
       }
       for (const { scope, store } of built ? scopes.filter((item) => attempt.has(item.scope.scopeId)) : []) {
         const { scopeId } = scope
@@ -543,13 +669,29 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           // that cannot be qualified never makes a current view stale. Any other publication builds the adapter first,
           // and an app that does not qualify keeps the publisher from being reached at all.
           const lazy = trusted()?.generationId === preparedGenerationId ? builtOnFirstUse(() => adapterFactory({ store, scope })) : null
-          const adapter = lazy ?? await adapterFactory({ store, scope })
+          // A view never published into its allocated folder is not kept from its first publication by an app that
+          // does not qualify, while that app's list shows no entry for the folder: the publisher is reached with an
+          // adapter that coordinates with nothing, and may take its `direct-unheld` path. Any other outcome is the
+          // factory's refusal, as before.
+          let heldBackBy = null
+          let adapter = lazy
+          if (adapter === null) {
+            try { adapter = await adapterFactory({ store, scope }) } catch (error) {
+              if (!isTypedRefusal(error) || !(await unheldMayApply(store, trusted()))) throw error
+              heldBackBy = error
+              adapter = uncoordinatedAdapter(error)
+            }
+          }
           let result
           try {
             result = await seams.publishView({
               preparedView: prepared, protocolId: PROTOCOL_ID, expectedGeneration: trusted()?.generationId ?? null, recoveryStore: store, adapter, clock,
               ...(quietPeriodMs === undefined ? {} : { quietPeriodMs }),
+              ...(typeof readUnheldEvidence === 'function' ? { unheldEvidence: readUnheldEvidence, platform } : {}),
             })
+            // Stopped before its commit for want of an app that coordinates: the app's refusal is what the person has to
+            // act on, and `open` answers it before it would add the vault to the app.
+            if (heldBackBy !== null && (result.state === 'refused' || (result.state === 'updating' && result.notes.some((note) => note.blocking && note.outcome === 'editor-uncoordinated')))) throw heldBackBy
           } catch (error) {
             // The publisher asked for the app only to publish the committed generation again (a plugin file drifted),
             // and the app did not qualify: nothing was written, and the committed generation is read back as it is.
@@ -579,7 +721,8 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
             // Somebody wrote during the publication. The next tick preserves and queues it.
             else if (differing.length > 0 || editedUnderPublisher) settle('updating', 'read-back-differs', common)
             else if (common.generationId !== preparedGenerationId) settle('stale', 'committed-generation-differs', common)
-            else settle('current', result.alreadyCommitted ? 'verified-by-read-back' : 'published-and-verified', { ...common, heldNotes: [], verified: true })
+            // Kept current while a plugin file waits for the app: the reason says so, and status shows it on the plugin line.
+            else settle('current', result.waitsForApp === true ? PLUGIN_FILES_WAIT_FOR_APP : result.alreadyCommitted ? 'verified-by-read-back' : 'published-and-verified', { ...common, heldNotes: [], verified: true })
           }
         } catch (error) {
           if (!isTypedRefusal(error)) { settle('stale', 'publisher-error'); persist(); throw error }

package/src/runtime/obsidian/extension-points.mjs

@@ -65,7 +65,7 @@ export function normalizeApplyResult(value) {
 // an apply operation replaces it.
 const OPERATION_NAME = /^[a-z][a-z0-9-]{0,31}$/
 // The operations the command ships. The service composes the same registry, so both refuse the same contributions.
-export const BUILT_IN_OPERATIONS = Object.freeze(['status', 'scope', 'audience', 'mode', 'policy', 'service', 'open', 'plugin', 'apply', 'help'])
+export const BUILT_IN_OPERATIONS = Object.freeze(['status', 'settings', 'location', 'scope', 'view', 'audience', 'mode', 'policy', 'service', 'open', 'uninstall', 'plugin', 'apply', 'help'])
 export const REPLACEABLE_OPERATIONS = Object.freeze(['apply'])
 
 export function createCommandOperations({ reserved = [] } = {}) {

package/src/runtime/obsidian/index.mjs

@@ -6,8 +6,9 @@
 export { ObsidianMaintenanceRefusal } from './errors.mjs'
 export { DISABLED_REASONS, ENABLEMENT_STATES, readObsidianEnablement } from './enablement.mjs'
 export {
-  LOCAL_POINTER_SCHEMA, MACHINE_SETTINGS_SCHEMA, MAINTENANCE_MODES, authorizeAutomaticApply, defaultDataRoot, defaultMachineSettings, ensureWorkspaceIdentity,
-  installApplyPolicy, localPointerPath, protectedRoots, readInstalledApplyPolicy, readLocalPointer, readMachineSettings, resolveDataRoot, revokeApplyPolicy, workspaceStateRoot, writeLocalPointer, writeMachineSettings,
+  DECISIONS, DECISION_SOURCES, LOCAL_POINTER_SCHEMA, MACHINE_SETTINGS_SCHEMA, MACHINE_SETTINGS_SCHEMA_V1, MAINTENANCE_MODES, ONLY_YOU_AUDIENCES, authorizeAutomaticApply,
+  defaultDataRoot, defaultMachineSettings, ensureWorkspaceIdentity, installApplyPolicy, localPointerPath, protectedRoots, readInstalledApplyPolicy, readLocalPointer,
+  readMachineSettings, resolveDataRoot, revokeApplyPolicy, withDecision, workspaceStateRoot, writeLocalPointer, writeMachineSettings,
 } from './machine-settings.mjs'
 export { APPLY_RESULT_STATUSES, BUILT_IN_OPERATIONS, EXTENSION_KINDS, REPLACEABLE_OPERATIONS, UNAVAILABLE_APPLY_OPERATION, createCommandOperations, createMaintenanceExtensions, createObsidianRegistry } from './extension-points.mjs'
 export { CONTRIBUTIONS_DIRECTORY, loadContributions } from './contributions.mjs'
@@ -20,19 +21,21 @@ export {
 } from './state-store.mjs'
 export { listConfigFiles, listSourceFiles, listVaultNotes, reconcile } from './observation.mjs'
 export { createFsWatcherFactory, createNullWatcherFactory } from './watchers.mjs'
-export { DEFAULT_ELIGIBILITY, assetEligibilityFor, createProductionSeams } from './pipeline.mjs'
+export { DEFAULT_ELIGIBILITY, assetEligibilityFor, createProductionSeams, eligibilityFor, onlyYouEligibility } from './pipeline.mjs'
 export { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, DEFAULT_LATE_WRITER_WINDOW_MS, DEFAULT_PUBLICATION_RETRY_MS, DEFAULT_RETRY_INTERVAL_MS, createMaintenanceEngine } from './engine.mjs'
 export { ENGINE_LOCK_DIRECTORY, LOCK_TICKET_SCHEMA, acquirePrivateGenerationLock, createAbandonmentProof, inspectPrivateGenerationLock } from './private-lock.mjs'
 export { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
 export { HEALTH_SCHEMA, LOOPBACK_HOSTS, probeHealth, requestLoopback } from './service-client.mjs'
 export {
-  CONSENT_COVERAGES, SERVICE_ERROR_SCHEMA, SERVICE_SETTINGS_SCHEMA, executableIdentity, publicRecord, readLastServiceError, readServiceRecord, readServiceSettings,
-  removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
+  CONSENT_COVERAGES, LAST_STARTUP_SCHEMA, SERVICE_ERROR_SCHEMA, SERVICE_SETTINGS_SCHEMA, STARTUP_OUTCOMES, executableIdentity, publicRecord, readLastServiceError, readLastStartup,
+  readServiceRecord, readServiceSettings, removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
 } from './service-record.mjs'
 export { MAX_REQUEST_BYTES, SERVICE_OPERATIONS, createServiceServer } from './service-server.mjs'
 export { PLUGIN_BEARER_SCHEMA, PLUGIN_PRESENCE_SCHEMA, createPluginChannel, createPluginSessions, ensurePluginBearer, pluginBearerDirectory, pluginPresence, readPluginBearers } from './plugin-channel.mjs'
 export { PLUGIN_PRESENCE_REASONS, pluginPresenceOf, turnPluginOnNext, withPluginReportedVersion } from './plugin-presence.mjs'
 export { PLUGIN_CHOICE_SCHEMA, PLUGIN_CHOICE_STATES, confirmPluginEntry, confirmPluginSeen, currentPluginChoice, decidePluginChoice, pluginChoiceDirectory, readCommunityEntry, readPluginChoice, viewVaultRoot, writePluginChoice } from './plugin-choice.mjs'
-export { DEFAULT_SHUTDOWN_GRACE_MS, SERVICE_STATUS_SCHEMA, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
+export { DEFAULT_SHUTDOWN_GRACE_MS, RELEASE_CHANGED, SERVICE_STATUS_SCHEMA, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
 export { DEFAULT_START_TIMEOUT_MS, DEFAULT_STOP_TIMEOUT_MS, SERVICE_STATES, readServiceStatusDocument, requestServiceTick, serviceStatus, startService, stopService } from './lifecycle.mjs'
-export { STARTUP_PLATFORMS, buildStartupAdapter } from './startup-adapters.mjs'
+export { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from './startup-adapters.mjs'
+export { LOGIN_ITEM_SCHEMA, installLoginItem, loginItemStatus, removeLoginItem, resolveLoginItemEntry } from './login-item.mjs'
+export { SERVICE_MANAGER_KINDS, createLaunchdManager, createSystemdManager } from './service-managers.mjs'

package/src/runtime/obsidian/launch-plan.mjs

@@ -55,11 +55,14 @@ export const urlProcessed = (stdout) => typeof stdout === 'string' && /^processe
 //
 // A URL is never handed to the operating system for an app this launch
 // started: that would start or reach it while it starts, which is what drops
-// the other vaults' reopen flags. The vault was added flagged open, so a plainly
-// started app opens it anyway, and `open` waits for it.
-export async function runLaunchPlan(plan, { start, answered, handLink, osOpen, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), waitMs = 30_000, pollMs = 500, now = () => Date.now() }) {
+// the other vaults' reopen flags. A vault added flagged open is opened anyway by
+// a plainly started app, and `open` waits for it; one already listed but closed
+// is handed the link once more instead (opening.mjs). `startedEarlier` says
+// that an earlier launch of the same `open` started the app (a link handed to
+// it once more): the link then goes through the app's tool only, as well.
+export async function runLaunchPlan(plan, { start, answered, handLink, osOpen, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), waitMs = 30_000, pollMs = 500, now = () => Date.now(), startedEarlier = false }) {
   if (!plan?.ok) return { launched: false, reason: plan?.reason ?? 'launcher-refused' }
-  let started = false
+  let started = startedEarlier === true
   let reason = 'url-accepted'
   for (const { step, uri } of plan.steps) {
     if (step === 'plain-start') {