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

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.2.0-alpha.11
+
+### Fixed
+
+- `status` now gives the same reason-specific next step as `open` for a
+  publication that stopped because an Obsidian that may hold the vault could
+  not be coordinated with (`publisher-conflict`, reason
+  `editor-uncoordinated`). The text no longer names one cause, since the
+  reason has several: another vault open, a command line that did not answer,
+  an unknown process table (on Linux, any app on a system Electron), or an app
+  started during an app-closed publication. The advice depends on whether the
+  view was ever published. Before a first publication: quit Obsidian (on
+  Linux, also any app that runs on a system Electron) so the view is
+  published, then `atelier obsidian open` starts Obsidian on it. After one:
+  the same, or open the view in the app as it is with `atelier obsidian open
+  --allow-stale`. A concurrent publisher keeps its advice.
+- The service's app qualification checks no version for an app that is not
+  running, and that answer is remembered for up to ten seconds. An editor
+  adapter built on it could coordinate with an Obsidian started inside that
+  window, whose version nobody had checked, and publish through it in-app.
+  The adapter now receives the qualification and does not coordinate, or ask
+  the app anything, unless a version was checked. An answer that checked no
+  version (the app was not running, or none was found) is no longer reused,
+  so the next publication after the app starts reads its version and
+  coordinates. A publication that stops this way is tried again on the next
+  change or at the next full reconciliation, every five minutes.
+- On macOS the app is found only at `/Applications/Obsidian.app`. An
+  Obsidian installed elsewhere is `app-missing`: nothing is published through
+  it, and publication waits while it runs. This is now documented.
+- On Linux an app started through a differently named link or launcher was
+  read as absent, because the process name is the name it was started
+  through. A process whose name is not recognised is now identified by the
+  executable `/proc/<pid>/exe` resolves to. A read failure other than a
+  process that exited or whose executable this user may not read, or a table
+  in which nothing resolves, is `unknown`.
+- The `ps` call of the process probe had no timeout, so a hung `ps` blocked
+  the service. It is killed after five seconds and the reading is `unknown`.
+- Documented that from 0.2.0-alpha.10 the app-free publication path runs in
+  production, with its re-probe window of up to two seconds plus one note
+  while Obsidian is not running (see "Known limits" in `docs/obsidian.md`).
+
 ## 0.2.0-alpha.10
 
 ### Fixed

package/README.md

@@ -54,7 +54,7 @@ governed projections
 You can see the complete loop in a disposable sample workspace:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
 npx mnstry-atelier init --fixture=sample-workspace --target ./sample
 npx mnstry-atelier graph --project ./sample/atelier.project.json
 npx mnstry-atelier project --project ./sample/atelier.project.json
@@ -378,7 +378,7 @@ Node.js `>=22.18.0 <23` is required. Pin the prerelease while the package
 remains in alpha:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
 ```
 
 Then choose the path that matches what you are building:
@@ -397,7 +397,7 @@ Then choose the path that matches what you are building:
 
 ## Status and command reference
 
-Current package: `@mnstry/atelier@0.2.0-alpha.10`.
+Current package: `@mnstry/atelier@0.2.0-alpha.11`.
 
 The alpha package is usable and contract-tested, but its library API may still
 change before a stable release. Pin the exact version in production toolchains.

package/docs/install.md

@@ -34,19 +34,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.11"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.11"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the

package/docs/obsidian-contract.md

@@ -2,8 +2,10 @@
 
 This document freezes what later work receives from the contract and
 feasibility track. It states what is proven, on what, and what is not. Nothing
-here enables a feature: a publisher exists under
-`src/projection/obsidian/publication/`, and no command or service calls it yet.
+here enables a feature. The publisher under
+`src/projection/obsidian/publication/` is called by the maintenance service
+(`atelier obsidian service start`) and so by `atelier obsidian open`; see
+[obsidian.md](obsidian.md).
 
 ## Registered shapes
 
@@ -292,9 +294,15 @@ in the newly started app is not: the app then takes its own
 external-modification merge, which can drop overlapping edits. The probe also
 cannot see an app on another machine that reaches the vault through a shared
 or synchronized folder, or an app packaged under another executable name. It
-recognises the app by the executable a process runs (`ps -A -o comm=`), never
+recognises the app by the executable a process runs (`ps -A -o comm=`, or
+`pid=,comm=` on Linux), never
 by its arguments; on Linux a system Electron process, which does not say which
-app it hosts, makes the reading unknown rather than absent.
+app it hosts, makes the reading unknown rather than absent, and a process whose
+name is not recognised is identified by the executable `/proc/<pid>/exe`
+resolves to. A `ps` that does not answer within five seconds is unknown.
+Before 0.2.0-alpha.10 no production reading was ever absent, because the probe
+found Atelier's own service; from that release this path, and this window, are
+live.
 
 ### Proven boundary
 

package/docs/obsidian.md

@@ -303,7 +303,11 @@ usage text; `atelier obsidian --help` prints it.
    --adapter=obsidian-cli` prints a startup unit and installs nothing.
 4. Open a view: `atelier obsidian open --scope ID --adapter=obsidian-cli`.
    The command starts or reconnects maintenance, verifies the vault by reading
-   it back, and asks the app (version 1.13.7 or later) to open it.
+   it back, and asks the app (version 1.13.7 or later) to open it. Quit
+   Obsidian before a view's first publication (on Linux, also any app that
+   runs on a system Electron): while a process that may be Obsidian runs, the
+   first publication stops, and `open` and `status` say so; see
+   [First publication while Obsidian is running](#first-publication-while-obsidian-is-running).
 
 `open` and `status` answer with a freshness state, not a promise. `current`
 means the vault is the present generation, verified by read-back, and the app
@@ -341,14 +345,31 @@ Publication is proven on macOS arm64 only and is refused on Windows; see
 ### First publication while Obsidian is running
 
 The publisher writes into a vault only when it can coordinate with every
-Obsidian that might have it open. An Obsidian that is running without this
-vault open cannot be coordinated with, so the first publication of a view is
-refused as `publisher-conflict` with reason `editor-uncoordinated`, and
-nothing is written. Quit Obsidian: the service then publishes the view
-directly, and `atelier obsidian open --scope ID --adapter=obsidian-cli` starts
-Obsidian on it. An Obsidian with no vault open at all answers its command line
-with "Vault not found." for every command, its version included; that is
-reported as reason `no-vault-open`, and the same remedy applies.
+Obsidian that may hold it, or when the process table shows, positively, that
+none runs. Otherwise it stops, and the view reports `publisher-conflict` with
+reason `editor-uncoordinated`. That reason has several causes, and the report
+does not say which: Obsidian runs without this vault open, or with it open but
+its command line did not answer; the process table could not be read, or on
+Linux shows an app that runs on a system Electron, which may be Obsidian; the
+app's version was not checked when the publication began (it started just
+then, or on macOS it is installed outside `/Applications`; see "Known
+limits"); or an app started while the view was being published with the app
+closed, which stops that publication partway. Before a first publication no
+app has the vault open, so only the first way on applies: quit Obsidian (on
+Linux, also any app that runs on a system Electron). The service then
+publishes the view directly, and
+`atelier obsidian open --scope ID --adapter=obsidian-cli` starts Obsidian on
+it. `status` and `open` give that as the next step. Once a view
+has been published, the last published vault stays in place and there is a
+second way on: open it in the running app as it is with
+`atelier obsidian open --allow-stale`, which waits, bounded, until the app
+answers for it. The publication is retried automatically either way.
+
+An Obsidian with no vault open at all answers its command line with "Vault not
+found." for every command, its version included. That is reported as outcome
+`app-version-unsupported` with reason `no-vault-open`, under `service.app` in
+`status` and by `open`. Opening any vault in Obsidian resolves it, because the
+version can then be read, and so does quitting Obsidian.
 
 ## Known limits
 
@@ -375,7 +396,20 @@ test reported as a pass.
   is admitted although the protocol depends on the view's undocumented
   `lastSavedData` field, and the protocol cases have not been re-run on any
   later release. See the "App capability floor" row of
-  [obsidian-contract.md](obsidian-contract.md).
+  [obsidian-contract.md](obsidian-contract.md). An app that was not running
+  when an adapter was qualified had no version to check, and neither had an
+  app that was not found. Such an answer is never reused, and the adapter
+  built on it does not coordinate with any app it then finds running, and
+  asks it nothing. That publication stops as `publisher-conflict` with reason
+  `editor-uncoordinated`, and the next publication asks again and reads the
+  version. A view that stopped is tried again on its next change, or at the
+  next full reconciliation, every five minutes.
+- Install location (macOS): the app is found only at
+  `/Applications/Obsidian.app`, and its command-line tool only inside it. An
+  Obsidian installed elsewhere, or a renamed bundle, is `app-missing`.
+  Nothing is published through it, publication waits while it runs (the
+  process probe still sees it), and `open` answers `app-missing` and cannot
+  start it. With it quit, the view is published on the path with no app.
 - No vault open: while Obsidian runs with no vault open, its command-line tool
   answers every command, `version` included, with `Vault not found.`. The
   version floor cannot be checked then, so the app does not qualify:
@@ -386,20 +420,47 @@ test reported as a pass.
   the version again on a later tick. `open` launches nothing while the app
   runs with no vault open, and after its own launch it waits, bounded, while
   the app is still opening the vault.
-- Detecting the app: the process table is read with `ps -A -o comm=`, and the
-  app is recognised by the executable a process runs, never by its arguments,
-  so a path argument that contains an `obsidian` directory (the maintenance
-  service itself, anything under the private data root) is not the app. On
-  macOS the executable `Obsidian` and the bundle's `Obsidian Helper`
-  processes count, in any directory. On Linux a process named `obsidian`
-  counts, which covers the .deb, snap, AppImage and Flatpak builds. A
-  distribution that runs the app under a system Electron shows only
-  `electron`: the table is then `unknown`, which is treated as a running app,
-  so publication through the app-free path waits until no such process runs.
-  The command-line tool (`obsidian-cli`) is a client of the app and is not
-  counted. A process renamed by its packager, an app on another machine and an
-  app that starts after a reading are not seen; see "The path with no app" in
-  [obsidian-contract.md](obsidian-contract.md).
+- Detecting the app: the process table is read with `ps -A -o comm=`
+  (`pid=,comm=` on Linux), and the app is recognised by the executable a
+  process runs, never by its arguments, so a path argument that contains an
+  `obsidian` directory (the maintenance service itself, anything under the
+  private data root) is not the app. A `ps` that has not answered within five
+  seconds is killed and the reading is `unknown`, which is treated as a
+  running app.
+  - macOS: the executable `Obsidian` and the bundle's `Obsidian Helper`
+    processes count, in any directory. An app started through a differently
+    named link shows that name for its main process; its `Obsidian Helper`
+    processes still count.
+  - Linux: a process named `obsidian` counts, which covers the .deb, snap,
+    AppImage and Flatpak builds. Linux names a process after the path it was
+    started through, so for a name that is not recognised the probe reads
+    the executable `/proc/<pid>/exe` resolves to: an app started through a
+    link or launcher named `obs`, or a child started through
+    `/proc/self/exe` whose executable is readable, still counts. A process
+    whose executable this user may not read (another user's, or one of this
+    user's that hides it from tracing, such as ssh-agent) or that exited
+    meanwhile is judged by its name alone. Any other read failure, or a
+    table in which no executable resolves at all, is `unknown`. A
+    distribution that runs the app under a system Electron shows only
+    `electron`: the table is then `unknown`, so publication through the
+    app-free path waits until no such process runs.
+  - The command-line tool (`obsidian-cli`) is a client of the app and is not
+    counted. An app packaged under another executable name, an app on
+    another machine and an app that starts after a reading are not seen; see
+    "The path with no app" in [obsidian-contract.md](obsidian-contract.md).
+- The app-free path is live: before 0.2.0-alpha.10 the probe always found
+  Atelier's own service, so publication never took the path with no app.
+  From 0.2.0-alpha.10 it does, whenever the process table shows, positively,
+  that no Obsidian runs. It applies only then. The table is read at path
+  selection, again immediately before the first note, and again whenever two
+  seconds have passed. An app that starts between two readings is not seen
+  for at most two seconds plus one note's publication, and in that window a
+  note is exchanged with no editor check. Bytes on disk stay protected by the
+  on-disk comparison and the exchange. An unsaved buffer in the newly started
+  app does not: the app applies its own external-modification merge, which
+  can drop overlapping edits. Once a reading shows an app, every remaining
+  note refuses. To avoid the window, do not start Obsidian while a view is
+  being published with the app closed.
 - CRLF sources: the editor normalizes line endings when it saves, so a body
   edit made in the vault to a note whose source uses CRLF is more than a body
   replacement to the edit lens. It is preserved and becomes a proposal; it is

package/docs/upgrade.md

@@ -9,6 +9,15 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.11
+
+This release tightens the Obsidian projection's app checks after independent
+review of 0.2.0-alpha.10: Atelier never coordinates with an Obsidian whose version it
+has not checked, the advice for a refused publication is true for every cause
+and appears in `status` as well as `open`, Linux resolves an app started
+through a differently named launcher, and the process check has a timeout.
+No project or machine setting needs to change.
+
 ## Upgrading to 0.2.0-alpha.10
 
 This release fixes the first activation of the Obsidian projection. In
@@ -176,7 +185,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -184,7 +193,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.11"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.11",
   "private": false,
   "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry or required hosted account; optional host-bound vault adapters.",
   "keywords": [

package/src/projection/obsidian/publication/transport.mjs

@@ -1,4 +1,5 @@
 import { execFile, execFileSync } from 'node:child_process'
+import { readlinkSync } from 'node:fs'
 import { POLICY_SETTINGS_PATH, buildEvalCode, createInProcessHost, runInProcess, validatePayload } from './bridge-script.mjs'
 
 // Editor coordination adapter.
@@ -26,9 +27,16 @@ export class TransportTimeout extends Error {
 
 const READ_RETRIES = 2
 
-export function createEditorAdapter({ call, processProbe, kind = 'custom' }) {
+// `qualification`, when given, is the app qualification this adapter was
+// constructed under (`qualifyApp`). An adapter qualified while no app ran was
+// never shown a version, so it never coordinates with an app found running
+// later, whose version nobody checked: it is `uncoordinated` until an adapter
+// qualified with a checked version replaces it. Without a qualification the
+// adapter coordinates as before.
+export function createEditorAdapter({ call, processProbe, kind = 'custom', qualification }) {
   if (typeof call !== 'function') throw new TypeError('createEditorAdapter needs a call function')
   if (typeof processProbe !== 'function') throw new TypeError('createEditorAdapter needs a processProbe function')
+  const versionUnchecked = qualification !== undefined && qualification?.versionChecked !== true
   const retries = []
   let tail = Promise.resolve()
   const serialized = (operation) => {
@@ -62,11 +70,13 @@ export function createEditorAdapter({ call, processProbe, kind = 'custom' }) {
     }),
     // Path selection. `absent` is returned only when the process probe says,
     // positively, that no Obsidian is running. A running or unknowable app
-    // that does not answer for this exact vault is `uncoordinated`.
+    // that does not answer for this exact vault is `uncoordinated`, and so is
+    // any app while this adapter's qualification checked no version.
     probe: ({ vaultRoot }) => serialized(async () => {
       let processes
       try { processes = await processProbe() } catch { processes = 'unknown' }
       if (processes === 'absent') return { state: 'absent', reason: 'no Obsidian process is running' }
+      if (versionUnchecked) return { state: 'uncoordinated', reason: 'app-version-unchecked: an Obsidian process may be running, and this adapter was qualified while none ran, so its version was never checked' }
       try {
         const reply = await readOnly({ op: 'inspect', vaultRoot, path: POLICY_SETTINGS_PATH })
         // `path-unsafe` for the probe path still proves the app answered for this vault; the settings unit reports the path.
@@ -127,13 +137,48 @@ export function createObsidianCliCall({ cliPath = defaultCliPath(), env = proces
 //          directory: a moved or renamed bundle still counts, and so does a
 //          process whose path ps cannot read and names by its short name.
 //   Linux  `obsidian`, the executable of the .deb, snap, AppImage and Flatpak
-//          builds. A distribution that runs the app under a system Electron
-//          shows only `electron`, and which app it hosts is not known.
+//          builds, by name or, for a name that is not recognised, by the
+//          executable it resolves to. A distribution that runs the app under
+//          a system Electron shows only `electron`, and which app it hosts is
+//          not known.
 //
 // The command-line tool is a client of the app, not the app: counting it would
 // make every call this package makes through it look like a running app.
 const APP_EXECUTABLE = Object.freeze({ darwin: /^obsidian(?: helper\b.*)?$/i, linux: /^obsidian$/i })
 const ELECTRON_HOST = /^\.?electron(?:\d+|-wrap.*)?$/i
+// A `ps` that has not answered by then is killed, and the reading is unknown.
+const PS_TIMEOUT_MS = 5000
+// A process that exited since the table was read, or whose executable this
+// user may not read: another user's process, or one of this user's that hides
+// it from tracing (ssh-agent, a sandboxed renderer). Such a process is judged
+// by its name alone.
+const EXECUTABLE_UNREADABLE = new Set(['ENOENT', 'ESRCH', 'EACCES', 'EPERM'])
+
+const baseName = (text) => text.slice(text.lastIndexOf('/') + 1)
+const readProcessExecutable = (pid) => readlinkSync(`/proc/${pid}/exe`)
+
+// Linux names a process after the path it was started through, so an app
+// started through a differently named link or launcher shows another name.
+// The executable `/proc/<pid>/exe` resolves to does not change with the name.
+// Any failure other than the expected ones is unknown, and so is a table in
+// which no executable could be resolved at all: without `/proc`, nothing
+// below the names can be established.
+function resolveLinuxExecutables(rows, readExe) {
+  let resolved = 0
+  let unknown = false
+  for (const { pid } of rows) {
+    let target
+    try { target = String(readExe(pid)) } catch (error) {
+      if (!EXECUTABLE_UNREADABLE.has(error?.code)) unknown = true
+      continue
+    }
+    resolved += 1
+    const name = baseName(target.replace(/ \(deleted\)$/, ''))
+    if (APP_EXECUTABLE.linux.test(name)) return 'running'
+    if (ELECTRON_HOST.test(name)) unknown = true
+  }
+  return unknown || resolved === 0 ? 'unknown' : 'absent'
+}
 
 // Default process probe: 'absent' only when the process table was read and
 // holds no Obsidian. Limits: it sees this machine's processes as this user
@@ -141,20 +186,27 @@ const ELECTRON_HOST = /^\.?electron(?:\d+|-wrap.*)?$/i
 // vault through a shared or synchronized folder, an app packaged under another
 // executable name, or an app that starts after the probe. Anything it cannot
 // establish is 'unknown', which the adapter treats as a running app: an empty
-// table, a failed read, and on Linux a system Electron process.
-export function defaultObsidianProcessProbe({ platform = process.platform, run = execFileSync } = {}) {
+// table, a failed or slow read, and on Linux a system Electron process or an
+// executable that cannot be resolved for an unexpected reason.
+export function defaultObsidianProcessProbe({ platform = process.platform, run = execFileSync, readExe = readProcessExecutable } = {}) {
   if (!Object.hasOwn(APP_EXECUTABLE, platform)) return 'unknown'
+  const linux = platform === 'linux'
   try {
-    const table = run('/bin/ps', ['-A', '-o', 'comm='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 })
+    const table = run('/bin/ps', ['-A', '-o', linux ? 'pid=,comm=' : 'comm='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024, timeout: PS_TIMEOUT_MS, killSignal: 'SIGKILL' })
     if (typeof table !== 'string' || table.trim() === '') return 'unknown'
-    const names = table.split('\n').map((line) => line.trim()).filter((line) => line !== '').map((line) => line.slice(line.lastIndexOf('/') + 1))
-    if (names.some((name) => APP_EXECUTABLE[platform].test(name))) return 'running'
-    return platform === 'linux' && names.some((name) => ELECTRON_HOST.test(name)) ? 'unknown' : 'absent'
+    const rows = table.split('\n').map((line) => line.trim()).filter((line) => line !== '').map((line) => {
+      const match = linux ? /^(\d+)\s+(.*)$/.exec(line) : null
+      return match ? { pid: Number(match[1]), comm: match[2] } : { pid: null, comm: line }
+    })
+    if (rows.some((row) => APP_EXECUTABLE[platform].test(baseName(row.comm)))) return 'running'
+    if (!linux) return 'absent'
+    if (rows.some((row) => row.pid === null || ELECTRON_HOST.test(baseName(row.comm)))) return 'unknown'
+    return resolveLinuxExecutables(rows, readExe)
   } catch {
     return 'unknown'
   }
 }
 
-export function createObsidianCliAdapter({ cliPath, env, timeoutMs, processProbe = () => defaultObsidianProcessProbe() } = {}) {
-  return createEditorAdapter({ call: createObsidianCliCall({ cliPath, env, timeoutMs }), processProbe, kind: 'obsidian-cli' })
+export function createObsidianCliAdapter({ cliPath, env, timeoutMs, processProbe = () => defaultObsidianProcessProbe(), qualification } = {}) {
+  return createEditorAdapter({ call: createObsidianCliCall({ cliPath, env, timeoutMs }), processProbe, kind: 'obsidian-cli', qualification })
 }

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

@@ -103,13 +103,22 @@ export async function inspectApp(appProbe) {
 // The adapter factory of a service that reaches a real app. The editor adapter
 // is constructed only after the app qualified; otherwise the factory refuses,
 // typed, and the engine records that reason and publishes nothing. The answer
-// is remembered briefly so a tick over many views asks once.
+// is remembered briefly so a tick over many views asks once, unless it let an
+// adapter through without a checked version. `createAdapter` receives the
+// qualification with its input: an app that was not running qualified without
+// a version, and an adapter built on that answer must not coordinate with an
+// app started since (see createEditorAdapter).
 export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor = MINIMUM_APP_VERSION, maxAgeMs = 10_000, now = () => Date.now() } = {}) {
   if (typeof appProbe?.inspectSync !== 'function') throw new TypeError('the qualified adapter factory needs an appProbe with inspectSync()')
   if (typeof createAdapter !== 'function') throw new TypeError('the qualified adapter factory needs createAdapter')
   let last = null
+  // An answer that lets an adapter through without a checked version (no app
+  // was running, or none was found) is never reused: an app started since is
+  // asked for its version by the next call, not refused on the old answer. An
+  // answer that checked a version, or that refuses, is reused for `maxAgeMs`.
+  const reusable = (result) => result.versionChecked === true || (result.outcome !== 'qualified' && result.outcome !== 'app-missing')
   const qualification = () => {
-    if (last === null || now() - last.at > maxAgeMs) {
+    if (last === null || !reusable(last.result) || now() - last.at > maxAgeMs) {
       let observation
       try { observation = appProbe.inspectSync() } catch { observation = null }
       last = { at: now(), result: qualifyApp(observation, { requireVersion: false, floor }) }
@@ -120,7 +129,7 @@ export function createQualifiedAdapterFactory({ appProbe, createAdapter, floor =
     const result = qualification()
     // No app at all is not an unqualified app: the publisher's own path needs none, and its adapter finds no process.
     if (result.outcome !== 'qualified' && result.outcome !== 'app-missing') refuse(result.outcome, 'the installed Obsidian does not qualify; nothing is published through it', { reason: result.reason, floor: result.floor, version: result.version })
-    return createAdapter(input)
+    return createAdapter({ ...input, qualification: result })
   }
   factory.qualification = qualification
   // What was last learned, without asking again: for a status answer.

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

@@ -11,8 +11,10 @@ import { readVersionAnswer } from './app-capability.mjs'
 // 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 imports it, and importing it leaves a trace
-// below that the test suite asserts is absent.
+// `production: true`). No test 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.
 //
 // Status: written against the documented command-line interface and NOT yet
 // exercised against a running app. The acceptance work qualifies it on an

package/src/runtime/obsidian/opening.mjs

@@ -58,18 +58,35 @@ export function describeOutcome(code) {
 // A reason whose next step is not its outcome's. With no vault open the app's
 // command line answers nothing, its version included, so the version floor
 // cannot be checked until a vault is open or the app is quit.
-// `editor-uncoordinated` is the publisher refusing to write while an Obsidian
-// runs that does not answer for this vault: nothing coordinates with the app,
-// so nothing is written. There is no other publisher to wait for. With the app
-// quit, the view is published directly, and `open` then starts the app on it.
+// `editor-uncoordinated` is the publisher stopping because an Obsidian that may
+// hold this vault could not be coordinated with. There is no other publisher to
+// wait for, and the cause is not known here: the app runs without this vault,
+// or with it but its command line did not answer, or the process table was
+// unknown (on Linux, any app that runs on a system Electron), or an app started
+// while the view was published with the app closed. Every cause clears once no
+// such process runs, and a view that was published before can instead be
+// opened in the app as it is, which then answers for it.
+const UNCOORDINATED = 'an Obsidian that may hold this vault could not be coordinated with, so publication stopped'
+const QUIT = 'quit Obsidian (on Linux, also any app that runs on a system Electron)'
 export const REASON_NEXT = Object.freeze({
   'no-vault-open': 'open any vault in Obsidian, or quit Obsidian, then open again',
-  'editor-uncoordinated': 'Obsidian is running without this vault open, so nothing is written into it: quit Obsidian, let the view publish, then open again',
+  'editor-uncoordinated': `${UNCOORDINATED}; ${QUIT}, or open this view in it with \`atelier obsidian open --allow-stale\`; it is retried automatically`,
 })
 
-// The next step for an outcome and its reason; null for a code that is not an opening outcome.
-export function nextStep(outcome, reason) {
-  if (typeof reason === 'string' && Object.hasOwn(REASON_NEXT, reason)) return REASON_NEXT[reason]
+// Before a first publication there is no vault to open in the app: the view is
+// published only while no such process runs.
+const FIRST_PUBLICATION_NEXT = Object.freeze({
+  'editor-uncoordinated': `${UNCOORDINATED}; ${QUIT} so the view is published, then \`atelier obsidian open\` starts Obsidian on it`,
+})
+
+// The next step for an outcome and its reason; null for a code that is not an
+// opening outcome. `published` says whether a published generation of the view
+// reads back.
+export function nextStep(outcome, reason, { published = true } = {}) {
+  if (typeof reason === 'string') {
+    if (!published && Object.hasOwn(FIRST_PUBLICATION_NEXT, reason)) return FIRST_PUBLICATION_NEXT[reason]
+    if (Object.hasOwn(REASON_NEXT, reason)) return REASON_NEXT[reason]
+  }
   return Object.hasOwn(OPENING_OUTCOMES, outcome) ? OPENING_OUTCOMES[outcome].next : null
 }
 
@@ -147,7 +164,7 @@ export function scopeReport({ workspace, scopeId, repositoryRoots, serviceState,
   } else if (serviceState !== 'healthy') { outcome = 'stale-readable'; reason = serviceState === 'busy' ? 'maintenance-busy-not-rechecked' : 'maintenance-not-running' }
   else { outcome = 'current'; reason = entry.reason }
   return {
-    scopeId, ...describeOutcome(outcome), reason,
+    scopeId, ...describeOutcome(outcome), next: nextStep(outcome, reason, { published: verification.readable }), reason,
     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),
@@ -184,7 +201,7 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   const project = loadProject()
   const enablement = readObsidianEnablement(project)
   const applyAvailable = extensions !== null && extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
-  const finish = (outcome, extra = {}) => ({ ok: outcome === 'current', ...describeOutcome(outcome), next: nextStep(outcome, extra.reason), launched: false, ...extra })
+  const finish = (outcome, extra = {}) => ({ ok: outcome === 'current', ...describeOutcome(outcome), next: nextStep(outcome, extra.reason, { published: extra.readBack?.readable !== false }), launched: false, ...extra })
   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 }) }

package/src/runtime/obsidian/service-main.mjs

@@ -23,12 +23,14 @@ import { runMaintenanceService } from './service.mjs'
 // selected them. The editor adapter is constructed only for an app that meets
 // the minimum version; below it, or when the version cannot be read, the
 // factory refuses, the engine records that reason and nothing is published.
+// An adapter qualified while no app ran carries that qualification and does
+// not coordinate with an app that starts before the next qualification.
 const ADAPTERS = Object.freeze({
   'obsidian-cli': async () => {
     const [{ createObsidianCliAdapter }, { createProductionAppProbe }, { createQualifiedAdapterFactory }] = await Promise.all([
       import('../../projection/obsidian/publication/transport.mjs'), import('./app-production-seams.mjs'), import('./app-capability.mjs'),
     ])
-    const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: () => createObsidianCliAdapter() })
+    const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: ({ qualification }) => createObsidianCliAdapter({ qualification }) })
     return { adapterFactory, appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } } }
   },
 })

package/templates/external-project-workspace/pack-lifecycle.json

@@ -6,7 +6,7 @@
       "version": "v1",
       "digest": "sha256:0eff795765e0bbd4c2510acda2e492201c23bc870df6c354eef623484643ab11",
       "compatibleRootVersions": [
-        "0.2.0-alpha.10"
+        "0.2.0-alpha.11"
       ],
       "status": "active"
     }