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

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

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../project/private-state.mjs'
 import { ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
 import { canonicalJson, closedObject } from './documents.mjs'
@@ -10,11 +11,14 @@ import { LOOPBACK_HOSTS } from './service-client.mjs'
 // Private documents of the maintenance service of one workspace, under
 //
 //   <data>/obsidian/<workspace-id>/state/service/
-//     runtime.json     the adapter record of the running service (service-state v1)
-//     settings.json    what this machine chose: loopback host, port, startup consent
-//     last-error.json  the last tick that failed for a reason nobody typed
-//     service.log      the operational log of the service process
-//     start-lock/      serializes `start` for this workspace
+//     runtime.json       the adapter record of the running service (service-state v1)
+//     settings.json      what this machine chose: loopback host, port, startup consent
+//     last-error.json    the last tick that failed for a reason nobody typed
+//     last-startup.json  how the last start by the login item ended: started, or the refusal's code
+//     login-item.json    the installed login item (login-item.mjs)
+//     service.log        the operational log of the service process
+//     login-item.log     what a login item's service printed before it could open service.log
+//     start-lock/        serializes `start` for this workspace
 //
 // Owner-only, replaced atomically, outside every repository and every vault.
 // Every document is validated on every read. One that does not validate, or
@@ -23,7 +27,9 @@ import { LOOPBACK_HOSTS } from './service-client.mjs'
 
 export const SERVICE_SETTINGS_SCHEMA = 'atelier-obsidian-service-settings/v1'
 export const SERVICE_ERROR_SCHEMA = 'atelier-obsidian-service-last-error/v1'
+export const LAST_STARTUP_SCHEMA = 'atelier-obsidian-last-startup/v1'
 export const CONSENT_COVERAGES = Object.freeze(['service', 'service-and-startup'])
+export const STARTUP_OUTCOMES = Object.freeze(['started', 'refused'])
 
 const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
@@ -40,6 +46,7 @@ export function servicePaths(workspaceRoot) {
   return {
     stateLocation: path.join(workspaceRoot, 'state'), directory, record: path.join(directory, 'runtime.json'), settings: path.join(directory, 'settings.json'),
     lastError: path.join(directory, 'last-error.json'), log: path.join(directory, 'service.log'), startLock: path.join(directory, 'start-lock'),
+    lastStartup: path.join(directory, 'last-startup.json'), loginItem: path.join(directory, 'login-item.json'), loginItemLog: path.join(directory, 'login-item.log'),
   }
 }
 
@@ -60,6 +67,72 @@ export function executableIdentity(entryPath) {
   return { path: resolved, digest: `sha256:${createHash('sha256').update(fs.readFileSync(resolved)).digest('hex')}` }
 }
 
+// The package this module ships in.
+const PACKAGE_ROOT = fileURLToPath(new URL('../../../', import.meta.url))
+const byName = (left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+const releases = new Map()
+
+// The release that runs, beyond its entry module: the version of the package
+// and a digest of the runtime it ships, by relative path and content. That is
+// what the service loads: every module under `src/`, the `contracts/` it
+// reads, and the plugin under `plugins/` it publishes into every vault it
+// maintains; outside those it reads nothing else of the package but the
+// version in `package.json`. A release that changes any of it, and not only
+// the entry, differs. A package without `plugins/` reads as one with an empty
+// one.
+
+// Every regular file a release identity covers, in a fixed order: `visit(relative, absolute)`. A missing `src/` or
+// `contracts/` throws (the package cannot be read); a missing `plugins/` is empty.
+export function walkRelease(root, visit) {
+  const walk = (relative, { optional = false } = {}) => {
+    let entries
+    try { entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true }) } catch (error) { if (optional && error.code === 'ENOENT') return; throw error }
+    for (const entry of entries.sort(byName)) {
+      const child = `${relative}/${entry.name}`
+      if (entry.isDirectory()) walk(child)
+      else if (entry.isFile()) visit(child, path.join(root, child))
+    }
+  }
+  for (const part of ['src', 'contracts']) walk(part)
+  walk('plugins', { optional: true })
+}
+
+// The release identity of the package at `root`, read now and never cached: { version, digest }.
+export function readReleaseIdentity({ root }) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) throw new TypeError('a release identity is read from the absolute root of a package')
+  const hash = createHash('sha256')
+  walkRelease(root, (relative, absolute) => { hash.update(`${relative}\0${createHash('sha256').update(fs.readFileSync(absolute)).digest('hex')}\n`) })
+  let version = null
+  try { const read = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version; version = typeof read === 'string' ? read : null } catch { version = null }
+  return Object.freeze({ version, digest: `sha256:${hash.digest('hex')}` })
+}
+
+// readReleaseIdentity, computed once per process and package root, so a service keeps the identity of the code it
+// loaded.
+export function releaseIdentity({ root = PACKAGE_ROOT } = {}) {
+  if (!releases.has(root)) releases.set(root, readReleaseIdentity({ root }))
+  return releases.get(root)
+}
+
+const ENTRY_IN_PACKAGE = Object.freeze(['src', 'runtime', 'obsidian', 'service-main.mjs'])
+
+// The root of the package whose service entry is `entryPath` (`<root>/src/runtime/obsidian/service-main.mjs`), as that
+// path names it, without resolving links; null for any other entry.
+export function packageRootOfEntry(entryPath) {
+  if (typeof entryPath !== 'string' || !path.isAbsolute(entryPath)) return null
+  const parts = path.resolve(entryPath).split(path.sep)
+  if (parts.length <= ENTRY_IN_PACKAGE.length || ENTRY_IN_PACKAGE.some((part, index) => parts[parts.length - ENTRY_IN_PACKAGE.length + index] !== part)) return null
+  return parts.slice(0, parts.length - ENTRY_IN_PACKAGE.length).join(path.sep) || path.sep
+}
+
+// The release that starting `entryPath` would run, read now from the package that path names (so a link pointed
+// elsewhere, or a `file:` install, is the package it leads to now); for an entry that is not a package's service entry,
+// this package's own, as it was loaded.
+export function releaseOfEntry(entryPath) {
+  const root = packageRootOfEntry(entryPath)
+  return root === null ? releaseIdentity() : readReleaseIdentity({ root })
+}
+
 // ---------------------------------------------------------------------------
 // The adapter record
 // ---------------------------------------------------------------------------
@@ -159,6 +232,33 @@ export function writeLastServiceError({ workspaceRoot, workspaceId, document })
   return document
 }
 
+// ---------------------------------------------------------------------------
+// How the last start by a login item ended
+// ---------------------------------------------------------------------------
+
+// { schema, workspaceId, at, outcome: 'started' | 'refused', code }: the code of the refusal, null for a start. Written by
+// the service when it runs with `--startup`, so a login item that exits cleanly on a refusal (and is therefore not
+// started again in a loop) still says why.
+function validateLastStartup(document, workspaceId) {
+  const code = 'invalid-service-last-startup'
+  closedObject(document, { required: ['schema', 'workspaceId', 'at', 'outcome', 'code'] }, code, 'the last startup')
+  const ok = document.schema === LAST_STARTUP_SCHEMA && document.workspaceId === workspaceId && TIMESTAMP.test(document.at) && STARTUP_OUTCOMES.includes(document.outcome)
+    && (document.outcome === 'started' ? document.code === null : typeof document.code === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(document.code))
+  if (!ok) refuse(code, 'the last startup is malformed')
+  return document
+}
+
+export function readLastStartup({ workspaceRoot, workspaceId }) {
+  const document = readJson(servicePaths(workspaceRoot).lastStartup, 'invalid-service-last-startup', 'the last startup')
+  return document === null ? null : validateLastStartup(document, workspaceId)
+}
+
+export function writeLastStartup({ workspaceRoot, workspaceId, document }) {
+  validateLastStartup(document, workspaceId)
+  atomicReplacePrivateText(path.join(serviceDirectory(workspaceRoot), 'last-startup.json'), canonicalJson(document))
+  return document
+}
+
 // The log is bounded: past the ceiling it becomes the one previous log, and a new one begins.
 export const SERVICE_LOG_MAX_BYTES = 1024 * 1024
 

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

@@ -1,31 +1,50 @@
 import { createHash, timingSafeEqual } from 'node:crypto'
 import http from 'node:http'
+import { isContractIdentifier } from '../../projection/obsidian/contracts.mjs'
+import { PLUGIN_MAX_REQUEST_BYTES, pluginCommandOf, validatePluginRequest } from '../../projection/obsidian/plugin-bridge/channel.mjs'
 import { requestHeader, sameOrigin } from '../../server/security.mjs'
 import { isPlainObject } from './documents.mjs'
 import { HEALTH_SCHEMA, LOOPBACK_HOSTS, authorityOf } from './service-client.mjs'
 
-// The listener of the maintenance service: four fixed operations and nothing
-// else. There is no file serving, no command, no evaluation and no route that
-// takes a path, a name or code from a request.
+// The listener of the maintenance service: four fixed operations, the five
+// fixed commands of Atelier's plugin, and nothing else. There is no file
+// serving, no command, no evaluation and no route that takes a path, a name or
+// code from a request.
 //
 //   GET  /health   who answers here; open, and says nothing else
 //   GET  /status   service and per-view freshness summary; bearer required
 //   POST /tick     run one tick now; bearer required
 //   POST /stop     finish the tick in flight and exit; bearer required
 //
+//   POST /plugin/challenge | /plugin/hello | /plugin/lease | /plugin/release |
+//        /plugin/status
+//                  Atelier's plugin inside one vault, authenticated by a
+//                  handshake over that vault's key (plugin-bridge/channel.mjs)
+//
 // Every request, before its operation is even looked up:
 //
 //   - `Host` is exactly the literal loopback authority this listener is bound
 //     to, so a name that resolves to loopback (DNS rebinding) is refused;
 //   - a `Sec-Fetch-Site` other than `none` or `same-origin`, or an `Origin`
 //     that is not this listener itself, is refused: no web page drives this;
-//   - the path is one of the four, exactly, with no query; the method is the
+//   - the path is one of the nine, exactly, with no query; the method is the
 //     one that path has.
 //
-// Everything but health needs the per-runtime random bearer that exists only
-// in the owner-only record. A POST body is JSON of at most 1 KiB naming the
-// runtime it is meant for, so a request aimed at an earlier runtime on the
-// same port does nothing.
+// Everything but health and the plugin's commands needs the per-runtime
+// random bearer that exists only in the owner-only record. A POST body is JSON
+// of at most 1 KiB naming the runtime it is meant for, so a request aimed at an
+// earlier runtime on the same port does nothing (409). A tick may also name one
+// view (`scopeId`, a contract identifier), which is then prepared and published
+// once more on that tick; any other member is refused (400,
+// `request-member-unknown`).
+//
+// A plugin command carries no bearer: the plugin never sends its vault's key.
+// Its body, JSON of at most 1 KiB with exactly the fields of its command, is
+// judged by the plugin channel (plugin-channel.mjs): a challenge the service
+// answers only for a key it holds, a hello that proves the same key, and
+// session commands under the key the handshake derived. What it grants is
+// these commands for that one vault. The runtime bearer is not accepted there,
+// and nothing a plugin holds reaches status, tick or stop.
 
 export const MAX_REQUEST_BYTES = 1024
 export const SERVICE_OPERATIONS = Object.freeze({ '/health': 'GET', '/status': 'GET', '/tick': 'POST', '/stop': 'POST' })
@@ -35,6 +54,7 @@ const digestOf = (value) => createHash('sha256').update(String(value)).digest()
 // The decisions the request oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
 export const SERVER_PRIMITIVES = Object.freeze({
   bearerMatches: (presented, expected) => typeof presented === 'string' && presented !== '' && timingSafeEqual(digestOf(presented), digestOf(expected)),
+  maxPluginRequestBytes: PLUGIN_MAX_REQUEST_BYTES,
   hostMatches: (header, authority) => header === authority,
   originAllowed(headers, authority) {
     const site = requestHeader(headers, 'sec-fetch-site').toLowerCase()
@@ -73,7 +93,9 @@ function readBoundedJson(request, limit) {
 }
 
 // identity: { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt }
-// operations: { healthStatus(), status(), tick(), stop() }
+// operations: { healthStatus(), status(), tick(), stop() }, and, where the
+// service holds the plugin channel, { plugin(command, { body, authority }) ->
+// { statusCode, body } }
 export function createServiceServerForOracleTests({ identity, bearer, operations }, primitives = SERVER_PRIMITIVES) {
   if (!LOOPBACK_HOSTS.includes(identity?.host)) throw new TypeError('the service listens on a literal loopback address only')
   if (typeof bearer !== 'string' || bearer.length < 32) throw new TypeError('the service needs its random bearer')
@@ -83,6 +105,19 @@ export function createServiceServerForOracleTests({ identity, bearer, operations
     const authority = authorityOf(identity.host, identity.port)
     if (!rules.hostMatches(requestHeader(request.headers, 'host'), authority)) return send(response, 403, { error: 'host-not-this-loopback-listener' })
     if (!rules.originAllowed(request.headers, authority)) return send(response, 403, { error: 'cross-site-request' })
+    const presented = /^Bearer ([A-Za-z0-9_-]+)$/.exec(requestHeader(request.headers, 'authorization'))?.[1] ?? null
+    const command = typeof operations.plugin === 'function' ? pluginCommandOf(request.url) : null
+    if (command !== null) {
+      if (request.method !== 'POST') return send(response, 405, { error: 'method-not-allowed' })
+      // No credential travels in a header here: a request that sends one was not made by the plugin.
+      if (requestHeader(request.headers, 'authorization') !== '') return send(response, 400, { error: 'plugin-command-takes-no-bearer' })
+      const payload = await readBoundedJson(request, rules.maxPluginRequestBytes)
+      if (!payload.ok) return send(response, payload.statusCode, { error: payload.code })
+      const checked = validatePluginRequest(command, payload.body)
+      if (!checked.ok) return send(response, checked.code === 'protocol-unsupported' ? 409 : 400, { error: checked.code })
+      const answer = await operations.plugin(command, { body: checked.body, authority })
+      return send(response, answer.statusCode, answer.body)
+    }
     const method = Object.hasOwn(SERVICE_OPERATIONS, request.url) ? SERVICE_OPERATIONS[request.url] : null
     if (method === null) return send(response, 404, { error: 'unknown-operation' })
     if (request.method !== method) return send(response, 405, { error: 'method-not-allowed' })
@@ -90,13 +125,16 @@ export function createServiceServerForOracleTests({ identity, bearer, operations
       const { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt } = identity
       return send(response, 200, { schema: HEALTH_SCHEMA, serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt, status: operations.healthStatus() })
     }
-    const presented = /^Bearer ([A-Za-z0-9_-]+)$/.exec(requestHeader(request.headers, 'authorization'))?.[1] ?? null
     if (!rules.bearerMatches(presented, bearer)) return send(response, 401, { error: 'bearer-required' })
     if (request.url === '/status') return send(response, 200, await operations.status())
     const payload = await readBoundedJson(request, rules.maxRequestBytes)
     if (!payload.ok) return send(response, payload.statusCode, { error: payload.code })
-    if (Object.keys(payload.body).length !== 1 || payload.body.runtimeId !== identity.runtimeId) return send(response, 409, { error: 'request-names-another-runtime' })
-    if (request.url === '/tick') return send(response, 200, await operations.tick())
+    const { runtimeId, scopeId, ...unknown } = payload.body
+    if (runtimeId !== identity.runtimeId) return send(response, 409, { error: 'request-names-another-runtime' })
+    // A member the operation does not take: a view on a stop, or anything else.
+    if (Object.keys(unknown).length > 0 || (scopeId !== undefined && request.url !== '/tick')) return send(response, 400, { error: 'request-member-unknown' })
+    if (scopeId !== undefined && !isContractIdentifier(scopeId)) return send(response, 400, { error: 'request-invalid' })
+    if (request.url === '/tick') return send(response, 200, await operations.tick(scopeId === undefined ? {} : { scopeId }))
     // The answer leaves first; the service then finishes its tick and exits.
     response.once('finish', () => { void operations.stop() })
     return send(response, 202, { stopping: true, runtimeId: identity.runtimeId, pid: identity.pid })

package/src/runtime/obsidian/service.mjs

@@ -1,19 +1,26 @@
 import { randomBytes as cryptoRandomBytes } from 'node:crypto'
 import fs from 'node:fs'
+import path from 'node:path'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
 import { ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { prepareView as productionPrepareView } from '../../projection/obsidian/materialize/index.mjs'
+import { preparePluginFiles } from '../../projection/obsidian/plugin-bridge/bundle.mjs'
+import { publishView as productionPublishView } from '../../projection/obsidian/publication/publisher.mjs'
 import { isoTime } from './documents.mjs'
 import { createMaintenanceEngine } from './engine.mjs'
 import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { assertOutsideRepositories, protectedRoots, readLocalPointer, resolveDataRoot, workspaceStateRoot } from './machine-settings.mjs'
+import { createPluginChannel, createPluginSessions, ensurePluginBearer, pluginPresence } from './plugin-channel.mjs'
+import { confirmPluginEntry, confirmPluginSeen, currentPluginChoice, decidePluginChoice, vaultFilePresent, viewVaultRoot } from './plugin-choice.mjs'
+import { createPluginDriftObserver } from './plugin-drift.mjs'
 import { isProcessAlive } from './private-lock.mjs'
 import { probeHealth } from './service-client.mjs'
 import {
-  SERVICE_ERROR_SCHEMA, executableIdentity, readLastServiceError, readServiceRecord, readServiceSettings, removeServiceRecord, serviceNameFor, servicePaths,
+  SERVICE_ERROR_SCHEMA, executableIdentity, readLastServiceError, readServiceRecord, readServiceSettings, releaseIdentity, removeServiceRecord, serviceNameFor, servicePaths,
   writeLastServiceError, writeServiceRecord,
 } from './service-record.mjs'
 import { createServiceServer } from './service-server.mjs'
-import { createMaintenanceStateStore } from './state-store.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs'
 import { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
 import { createFsWatcherFactory } from './watchers.mjs'
 
@@ -33,11 +40,25 @@ import { createFsWatcherFactory } from './watchers.mjs'
 // publication that was cut short is settled by the publisher's own restart
 // recovery on a later tick, never by deleting what it left behind.
 //
+// It also holds the plugin channel (plugin-channel.mjs). Every view it
+// prepares carries Atelier's plugin, whose data file names this listener and
+// the view's bearer, unless the person turned the plugin off in that vault
+// (plugin-choice.mjs): then the entry is left alone and only the plugin files
+// that are still there are kept current. A plugin that holds a view open is
+// reported by status and tells the adapter factory the app version it runs in.
+//
 // `adapterFactory` has no default here either: whoever starts the service
 // decides whether it may reach a running app.
+//
+// Started by a login item (`startup`), the service also asks `releaseWatch`
+// after every tick whether the package it runs from changed on disk; when it
+// did, it finishes that tick and shuts down with the reason RELEASE_CHANGED,
+// which its process turns into an exit code the service manager restarts, on
+// the new release (release-watch.mjs, service-main.mjs).
 
 export const SERVICE_STATUS_SCHEMA = 'atelier-obsidian-service-status/v1'
 export const DEFAULT_SHUTDOWN_GRACE_MS = 30 * 1000
+export const RELEASE_CHANGED = 'release-changed'
 
 // Where a workspace keeps its private state, without creating an identity.
 export function resolveServiceWorkspace({ project, dataRoot, env = process.env, platform = process.platform, create = false }) {
@@ -72,6 +93,11 @@ export async function runMaintenanceService(options = {}) {
     engineOptions = {}, createEngine = createMaintenanceEngine,
     // What the adapter factory last learned about the installed app, when it qualifies one. Codes and versions only.
     appStatus = null,
+    // Under `startup`: { changed() } (createReleaseWatch), asked after every tick.
+    releaseWatch = null,
+    // The entry as this process was started by it (`process.argv[1]`), when that is not its real path: a login item
+    // names the installed entry by its path. It is recorded, so the process table can still prove this process ours.
+    invokedAs = null,
   } = options
   if (typeof loadProject !== 'function') throw new TypeError('the service needs loadProject')
   if (typeof adapterFactory !== 'function') throw new TypeError('the service needs an adapterFactory')
@@ -94,10 +120,13 @@ export async function runMaintenanceService(options = {}) {
   }
 
   const executable = executableIdentity(entryPath)
+  const alias = typeof invokedAs === 'string' && path.isAbsolute(invokedAs) && path.resolve(invokedAs) !== executable.path ? path.resolve(invokedAs) : null
   const startedAt = isoTime(clock)
   const identity = { serviceName: serviceNameFor(workspaceId), workspaceId, runtimeId, pid, host, port, executableDigest: executable.digest, startedAt }
   const bearer = randomBytes(32).toString('base64url')
   const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
+  // Session identities live in memory only and are always random, whatever `randomBytes` the service was given.
+  const pluginSessions = createPluginSessions()
 
   let stopping = false
   let consecutiveFailures = 0
@@ -105,7 +134,49 @@ export async function runMaintenanceService(options = {}) {
   let settleDone
   const done = new Promise((resolve) => { settleDone = resolve })
 
-  const engine = createEngine({ watcherFactory: createFsWatcherFactory(), ...engineOptions, loadProject, dataRoot, adapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId } })
+  // Every prepared view carries the plugin with this listener's address and the view's bearer, as the person's choice
+  // for that vault allows: the choice is read, and recorded when the vault shows it changed, from the community plugin
+  // list as it is now, and those very bytes travel with the view. A bearer or a choice that cannot be kept leaves that
+  // view without the plugin for this tick; the view itself is prepared as ever.
+  const pluginFor = (scopeId) => {
+    try {
+      const vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId)
+      const { choice, community } = decidePluginChoice({ workspaceRoot, workspaceId, scopeId, vaultRoot, clock })
+      const off = choice.state === 'off'
+      const bearer = ensurePluginBearer({ workspaceRoot, workspaceId, scopeId, randomBytes, clock })
+      if (pluginChannel.bearers().get(scopeId) !== bearer) pluginChannel.bearersChanged()
+      const plugin = preparePluginFiles({ channel: { host, port }, scopeId, bearer, onlyIfPresent: off })
+      // Turned off: the files still there are kept current; a folder the person removed is not made again.
+      const files = off ? plugin.files.filter((file) => vaultFilePresent(vaultRoot, file.path)) : plugin.files
+      const kept = new Set(files.map((file) => file.path))
+      const unreadable = community.file.state === 'unreadable'
+      return {
+        files, ownership: { ...plugin.ownership, files: plugin.ownership.files.filter((entry) => kept.has(entry.path)) },
+        community: off || unreadable ? { entry: 'withheld', reason: off ? 'turned-off-in-this-vault' : 'list-unreadable' } : { entry: 'owned', existing: community.file.bytes },
+      }
+    } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-not-prepared', code: errorCode(error), name: errorName(error) })
+      return null
+    }
+  }
+  const prepareWithPlugin = (input) => (engineOptions.seams?.prepareView ?? productionPrepareView)({ ...input, plugin: pluginFor(input.scope.scopeId) })
+  // An entry offered to a vault and now in place is confirmed: from then on, a list without it is the person's decision.
+  const publishAndConfirm = async (input) => {
+    const result = await (engineOptions.seams?.publishView ?? productionPublishView)(input)
+    try { confirmPluginEntry({ workspaceRoot, workspaceId, scopeId: input.recoveryStore.scopeId, result, clock }) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-entry-not-confirmed', code: errorCode(error), name: errorName(error) })
+    }
+    return result
+  }
+  // The app version a live plugin reports counts as checked for the view it holds open, while one launch of the plugin
+  // alone holds it: with two apps holding the vault, which one the command-line tool reaches is unknown.
+  const pluginReportOf = (scopeId) => { const report = pluginSessions.report(scopeId); return report?.instances === 1 ? report : null }
+  // The engine also asks the factory itself (`forget`, on a tick somebody asked for): the wrapper keeps its methods.
+  const pluginAwareAdapterFactory = Object.assign((input) => adapterFactory({ ...input, pluginReport: typeof input?.scope?.scopeId === 'string' ? pluginReportOf(input.scope.scopeId) : null }), adapterFactory)
+  const engine = createEngine({
+    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, publishView: publishAndConfirm },
+    loadProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
+  })
 
   const recordIsOurs = () => {
     try { const record = readServiceRecord({ workspaceRoot, workspaceId }); return record !== null && record.runtimeId === runtimeId && record.pid === pid } catch { return false }
@@ -128,12 +199,41 @@ export async function runMaintenanceService(options = {}) {
     writeLastServiceError({ workspaceRoot, workspaceId, document: { schema: SERVICE_ERROR_SCHEMA, workspaceId, runtimeId, code: errorCode(outcome.error), name: errorName(outcome.error), at, consecutiveFailures, totalFailures: (previous?.totalFailures ?? 0) + 1, resolvedAt: null } })
   }
 
+  // A plugin file a view's committed generation pins that is not on disk as pinned has the view prepared again, so the
+  // publisher writes it again; a drift is asked about once, not at every tick.
+  const pluginDrift = createPluginDriftObserver({ workspaceRoot, workspaceId })
+  const askForDriftedViews = () => {
+    try { for (const scopeId of pluginDrift.observe([...pluginChannel.bearers().keys()])) engine.requestPreparation(scopeId) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-drift-not-read', code: errorCode(error), name: errorName(error) })
+    }
+  }
+  // What a publication of this tick could not change is no drift to ask about again (plugin-drift.mjs).
+  const settleDriftLooks = () => {
+    try { pluginDrift.settle([...pluginChannel.bearers().keys()]) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-drift-not-read', code: errorCode(error), name: errorName(error) })
+    }
+  }
+
+  // A package that changed on disk: another release, loaded module by module into this process from then on.
+  const releaseChanged = () => {
+    if (!startup || releaseWatch === null) return false
+    try { return releaseWatch.changed() === true } catch { return false }
+  }
+
   const loop = createTickLoop({
     intervalMs, maxBackoffMs, onOutcome: recordOutcome,
     async tick() {
       // The service runs only while its record names it: a replaced or removed record ends it, cleanly.
       if (!recordIsOurs()) { void shutdown('record-no-longer-names-this-runtime'); return { state: 'stopping', reason: 'record-no-longer-names-this-runtime' } }
-      return engine.tick()
+      askForDriftedViews()
+      try {
+        const report = await engine.tick()
+        if (report?.state === 'ticked') settleDriftLooks()
+        return report
+      } finally {
+        // After the tick, whether it succeeded or not: the next one runs in a process of the release now on disk.
+        if (!stopping && releaseChanged()) { log({ at: isoTime(clock), event: RELEASE_CHANGED }); void shutdown(RELEASE_CHANGED) }
+      }
     },
   })
 
@@ -150,6 +250,26 @@ export async function runMaintenanceService(options = {}) {
   }
 
   const healthStatus = () => (stopping ? 'stopped' : consecutiveFailures > 0 ? 'degraded' : 'healthy')
+
+  // One view as the plugin is told about it: its freshness entry with held notes counted, and its open pending edits.
+  function pluginStatusOf(scopeId) {
+    let entry = null
+    try { entry = stateStore.readFreshness()?.scopes.find((item) => item.scopeId === scopeId) ?? null } catch (error) { if (!isTyped(error)) throw error; return { view: null, pendingEdits: null } }
+    let open = null
+    try { open = stateStore.readPendingEdits().edits.filter((edit) => edit.scopeId === scopeId && OPEN_EDIT_STATES.includes(edit.state)).length } catch (error) { if (!isTyped(error)) throw error }
+    const view = 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,
+    }
+    return { view, pendingEdits: open === null ? null : { open } }
+  }
+  // A plugin that holds a view open shows that its app has the view's entry: an entry only offered so far is confirmed.
+  const pluginSeen = (scopeId) => {
+    try { confirmPluginSeen({ workspaceRoot, workspaceId, scopeId, clock }) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-entry-not-confirmed', code: errorCode(error), name: errorName(error) })
+    }
+  }
+  const pluginChannel = createPluginChannel({ workspaceRoot, workspaceId, runtimeId, sessions: pluginSessions, statusOf: pluginStatusOf, serviceStatus: healthStatus, onSessionOpened: pluginSeen })
   const server = createServiceServer({
     identity, bearer,
     operations: {
@@ -158,14 +278,21 @@ export async function runMaintenanceService(options = {}) {
         let lastError = null
         try { lastError = readLastServiceError({ workspaceRoot, workspaceId }) } catch (error) { if (!isTyped(error)) throw error; lastError = { unreadable: error.code } }
         if (lastError?.schema) { const { schema: _schema, workspaceId: _workspace, ...shown } = lastError; lastError = shown }
-        return { schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(), ...(typeof appStatus === 'function' ? { app: appStatus() } : {}) }
+        return {
+          schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(),
+          plugins: pluginPresence({ sessions: pluginSessions, scopeIds: [...pluginChannel.bearers().keys()], entryOf: (scopeId) => currentPluginChoice({ workspaceRoot, workspaceId, scopeId }).state }),
+          ...(typeof appStatus === 'function' ? { app: appStatus() } : {}),
+        }
       },
-      async tick() {
+      // A tick asked for one view (`open` asks for its own) prepares and publishes that view once more.
+      async tick({ scopeId } = {}) {
+        if (scopeId !== undefined) engine.requestPreparation?.(scopeId)
         const outcome = await loop.tickNow()
         if (outcome.stopped) return { ok: false, stopped: true }
         return outcome.ok ? { ok: true, ...summary(outcome.report) } : { ok: false, error: { code: errorCode(outcome.error), name: errorName(outcome.error) } }
       },
       stop: () => shutdown('stop-requested'),
+      plugin: (command, request) => pluginChannel.handle(command, request),
     },
   })
 
@@ -202,7 +329,7 @@ export async function runMaintenanceService(options = {}) {
       workspaceRoot, workspaceId,
       record: {
         schema: 'atelier-obsidian-service-state/v1', contractVersion: '1.0.0', workspaceId, serviceName: identity.serviceName, host, port, runtimeId, pid,
-        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
+        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath, release: releaseIdentity(), ...(alias === null ? {} : { invokedAs: alias }) } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
         health: { status: 'healthy', checkedAt: startedAt }, consent: settings.consent, ext: { bearer },
       },
     })