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

package/src/runtime/obsidian/service-manager-production.mjs

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { refuse } from './errors.mjs'
+import { createLaunchdManager, createSystemdManager, homeIsAccountHome } from './service-managers.mjs'
+
+// The production service manager of a login item: the only code that runs
+// launchctl or systemctl, or writes into ~/Library/LaunchAgents or the user's
+// systemd folder.
+//
+// It is imported in exactly one place, dynamically: the command entry
+// (src/commands/obsidian.mjs), only when it runs as the real command-line
+// entry. Importing it leaves a trace below that the test suite asserts is
+// absent. It refuses, before anything is looked up or run:
+//
+//   - under the Node test runner (`real-login-item-under-test`), whatever
+//     environment it is handed: a test hands in its own manager;
+//   - when HOME is not the account's own home directory
+//     (`login-item-home-mismatch`): launchd and systemd register a unit in
+//     the account's real session whatever HOME says, so a private HOME must
+//     never install one;
+//   - on Windows (`startup-platform-unqualified`) and on any platform but
+//     macOS and Linux (`startup-platform-unsupported`).
+globalThis[Symbol.for('mnstry.atelier.obsidian.production-service-manager-loaded')] = true
+
+const RUN_TIMEOUT_MS = 15 * 1000
+const SYSTEMCTL = ['/usr/bin/systemctl', '/bin/systemctl']
+
+// No shell, in the root directory, bounded.
+function runner(env) {
+  return (program, args) => new Promise((resolve) => {
+    execFile(program, args, { env, cwd: '/', timeout: RUN_TIMEOUT_MS, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ status: error ? (typeof error.code === 'number' ? error.code : null) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+    })
+  })
+}
+
+export function createProductionServiceManager({ platform = process.platform, env = process.env } = {}) {
+  if (process.env.NODE_TEST_CONTEXT !== undefined || env.NODE_TEST_CONTEXT !== undefined) refuse('real-login-item-under-test', 'the production login-item manager is never used under the test runner; a test hands in its own')
+  if (platform === 'win32') refuse('startup-platform-unqualified', 'operating-system startup on Windows has not been qualified', { platform })
+  if (platform !== 'darwin' && platform !== 'linux') refuse('startup-platform-unsupported', 'no login item is known for this platform', { platform: String(platform) })
+  const account = os.userInfo()
+  if (!homeIsAccountHome({ env, accountHome: account.homedir })) refuse('login-item-home-mismatch', 'HOME is not this account\'s home directory; a login item is registered in the account\'s real session whatever HOME says, so none is installed from here')
+  const run = runner(env)
+  if (platform === 'darwin') return createLaunchdManager({ run, uid: account.uid, directory: path.join(account.homedir, 'Library', 'LaunchAgents') })
+  const configHome = typeof env.XDG_CONFIG_HOME === 'string' && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(account.homedir, '.config')
+  const systemctl = SYSTEMCTL.find((candidate) => { try { return fs.statSync(candidate).isFile() } catch { return false } })
+  if (systemctl === undefined) return unavailableManager({ directory: path.join(configHome, 'systemd', 'user') })
+  return createSystemdManager({ run, systemctl, directory: path.join(configHome, 'systemd', 'user') })
+}
+
+// Linux without systemctl: every change answers `login-item-unavailable`, and nothing is written.
+function unavailableManager({ directory }) {
+  const unavailable = async () => ({ ok: false, code: 'login-item-unavailable', status: null, message: 'systemctl was not found' })
+  return {
+    kind: 'systemd-user-unit', platform: 'linux', directory, fileFor: (fileName) => path.join(directory, fileName),
+    readUnit: () => null, install: unavailable, start: unavailable, remove: async () => ({ ok: true, removed: false }),
+    inspect: async ({ fileName }) => ({ ok: true, file: path.join(directory, fileName), present: false, loaded: null, running: null, pid: null, lastExit: null, disabled: null }),
+  }
+}

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

@@ -0,0 +1,275 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, readRegularTextNoFollow } from '../../project/private-state.mjs'
+
+// The operating system's service managers, as a login item uses them: a
+// launchd user agent on macOS and a systemd user unit on Linux.
+//
+// Each is built from the directory its unit files live in and `run`, the only
+// way it starts a program: `run(program, args)` resolves { status, stdout,
+// stderr }, with a null status when the program could not be run at all.
+// Neither has a default here. The production ones are made only by the real
+// command-line entry, through the production manager module, never under the
+// test runner and never for a HOME that is not the account's own; tests hand
+// in a `run` that records what it was asked and a temporary directory.
+//
+// What each does, in order:
+//
+//   launchd  install  write the property list (mode 0644, atomically); boot
+//                     the job out if it is loaded, because a loaded job keeps
+//                     the definition it was loaded with, and wait until
+//                     launchd has let it go; bootstrap it (RunAtLoad starts it);
+//                     a file written where none was is removed again when
+//                     launchd did not take it
+//            start    kickstart -p: starts the job when it is not running and
+//                     prints its PID either way
+//            remove   bootout; delete the file
+//            inspect  print (loaded, state, PID, last exit code) and
+//                     print-disabled (switched off in System Settings)
+//   systemd  install  write the unit (mode 0644, atomically); daemon-reload;
+//                     enable
+//            start    start
+//            remove   disable --now; delete the file; daemon-reload
+//            inspect  show LoadState, ActiveState, SubState, UnitFileState,
+//                     MainPID, ExecMainStatus
+//
+// Every answer is { ok: true, ... } or { ok: false, code, status, message }
+// with one of these codes:
+//
+//   login-item-unavailable     no manager to install into (no systemd user
+//                              instance: WSL, a container, no session bus)
+//   login-item-install-failed  the manager refused the unit
+//   login-item-not-loaded      a start of a job the manager does not have
+//                              loaded (booted out, or not allowed to run)
+//   login-item-start-failed    the manager did not start it for another reason
+//   login-item-remove-failed   the manager did not let the job go
+//   login-item-file-unsafe     the unit's file is a link or not a regular file
+//
+// The exit statuses and texts of launchctl and systemctl read here are the
+// documented ones; they are exercised against recorded texts, never against
+// this machine's own session.
+
+export const SERVICE_MANAGER_KINDS = Object.freeze(['launchd-user-agent', 'systemd-user-unit'])
+export const LAUNCHCTL = '/bin/launchctl'
+const UNIT_FILE_MODE = 0o644
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+// launchctl: the service is not in the domain (print, kickstart), and the job was not loaded (bootout).
+const LAUNCHD_NOT_FOUND = [113, 3]
+const BOOTOUT_WAIT_MS = 10 * 1000
+const BOOTOUT_POLL_MS = 100
+
+// Whether HOME names the account's own home directory (`accountHome`, as the system records it). A login item is
+// registered in the account's real session whatever HOME says, so only then is one installed.
+export function homeIsAccountHome({ env, accountHome }) {
+  const home = env?.HOME
+  if (typeof home !== 'string' || !path.isAbsolute(home) || typeof accountHome !== 'string' || !path.isAbsolute(accountHome)) return false
+  if (path.resolve(home) === path.resolve(accountHome)) return true
+  try { return fs.realpathSync(home) === fs.realpathSync(accountHome) } catch { return false }
+}
+
+const failed = (code, answer, message) => ({ ok: false, code, status: answer?.status ?? null, message: message ?? firstLine(answer) })
+// The first line of what a manager printed, bounded: never a whole output, which can carry an environment.
+function firstLine(answer) {
+  const text = `${answer?.stderr ?? ''}\n${answer?.stdout ?? ''}`.split('\n').map((line) => line.trim()).find((line) => line !== '')
+  return text === undefined ? null : text.slice(0, 200)
+}
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) })
+
+function checkUnit({ label, fileName }) {
+  if (typeof label !== 'string' || !LABEL.test(label)) throw new TypeError('a login item has a plain label')
+  if (typeof fileName !== 'string' || fileName !== path.basename(fileName) || !fileName.startsWith(label)) throw new TypeError('a unit file name is the label and its suffix')
+}
+
+// The unit's file, owned by this module: written atomically with the mode a manager accepts (neither launchd nor
+// systemd reads a unit anyone else can write), never through a link.
+function unitFiles(directory) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw new TypeError('a service manager needs the absolute directory of its unit files')
+  const fileFor = (fileName) => path.join(directory, fileName)
+  return {
+    directory,
+    fileFor,
+    read(fileName) {
+      try { return readRegularTextNoFollow(fileFor(fileName)) } catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+        return undefined
+      }
+    },
+    write(fileName, text) {
+      try {
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+        atomicReplacePrivateText(fileFor(fileName), text, UNIT_FILE_MODE)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, code: error?.code === undefined || /regular file|redirected/.test(String(error.message)) ? 'login-item-file-unsafe' : 'login-item-install-failed', status: null, message: String(error.code ?? 'not-written') }
+      }
+    },
+    remove(fileName) {
+      let before
+      try { before = fs.lstatSync(fileFor(fileName)) } catch (error) { if (error.code === 'ENOENT') return { ok: true, removed: false }; return { ok: false, code: 'login-item-remove-failed', status: null, message: String(error.code) } }
+      if (!before.isFile()) return { ok: false, code: 'login-item-file-unsafe', status: null, message: 'not a regular file' }
+      try { fs.unlinkSync(fileFor(fileName)); return { ok: true, removed: true } } catch (error) {
+        return error.code === 'ENOENT' ? { ok: true, removed: false } : { ok: false, code: 'login-item-remove-failed', status: null, message: String(error.code) }
+      }
+    },
+    present(fileName) { try { return fs.lstatSync(fileFor(fileName)).isFile() } catch { return false } },
+  }
+}
+
+// Pure. What `launchctl print <domain>/<label>` says about one job.
+export function readLaunchdPrint(text) {
+  const value = (name) => { const match = new RegExp(`^\\s*${name} = (.+)$`, 'm').exec(String(text ?? '')); return match === null ? null : match[1].trim() }
+  const pid = Number(value('pid'))
+  const exit = Number(value('last exit code'))
+  return { state: value('state'), pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null, lastExit: Number.isInteger(exit) ? exit : null }
+}
+
+// Pure. Whether `launchctl print-disabled <domain>` lists this label as disabled: true, false, or null when it is not
+// listed. Releases of macOS print `=> disabled` / `=> enabled`, earlier ones `=> true` / `=> false`.
+export function readLaunchdDisabled(text, label) {
+  for (const line of String(text ?? '').split('\n')) {
+    const match = /^\s*"([^"]+)"\s*=>\s*(\S+)\s*$/.exec(line)
+    if (match === null || match[1] !== label) continue
+    if (match[2] === 'disabled' || match[2] === 'true') return true
+    if (match[2] === 'enabled' || match[2] === 'false') return false
+  }
+  return null
+}
+
+export function createLaunchdManager({ run, uid, directory, waitMs = BOOTOUT_WAIT_MS, pollMs = BOOTOUT_POLL_MS } = {}) {
+  if (typeof run !== 'function') throw new TypeError('a service manager needs run')
+  if (!Number.isSafeInteger(uid) || uid < 0) throw new TypeError('a launchd manager needs the user id of its session')
+  const files = unitFiles(directory)
+  const domain = `gui/${uid}`
+  const target = (label) => `${domain}/${label}`
+  const launchctl = (...args) => run(LAUNCHCTL, args)
+  const loaded = async (label) => {
+    const answer = await launchctl('print', target(label))
+    return answer.status === 0 ? { loaded: true, answer } : { loaded: LAUNCHD_NOT_FOUND.includes(answer.status) ? false : null, answer }
+  }
+  // Boots the job out when launchd has it, and waits, bounded, until it is gone: bootstrap refuses a label still loaded.
+  async function bootout(label) {
+    const answer = await launchctl('bootout', target(label))
+    if (answer.status !== 0 && !LAUNCHD_NOT_FOUND.includes(answer.status)) return failed('login-item-remove-failed', answer)
+    const until = Date.now() + waitMs
+    for (;;) {
+      const now = await loaded(label)
+      if (now.loaded === false) return { ok: true, wasLoaded: answer.status === 0 }
+      if (Date.now() >= until) return failed('login-item-remove-failed', now.answer, 'launchd kept the job loaded')
+      await sleep(pollMs)
+    }
+  }
+  return {
+    kind: 'launchd-user-agent', platform: 'darwin', directory: files.directory, fileFor: files.fileFor,
+    readUnit({ label, fileName }) { checkUnit({ label, fileName }); return files.read(fileName) },
+    async install({ label, fileName, text }) {
+      checkUnit({ label, fileName })
+      // launchd loads every property list in LaunchAgents at login: one this installation wrote where none was is
+      // removed again when launchd did not take it.
+      const existed = files.present(fileName)
+      const written = files.write(fileName, text)
+      if (!written.ok) return written
+      const out = await bootout(label)
+      if (!out.ok) { if (!existed) files.remove(fileName); return out }
+      const answer = await launchctl('bootstrap', domain, files.fileFor(fileName))
+      if (answer.status !== 0) {
+        if (!existed) files.remove(fileName)
+        return failed(answer.status === null ? 'login-item-unavailable' : 'login-item-install-failed', answer)
+      }
+      return { ok: true, file: files.fileFor(fileName) }
+    },
+    async start({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const answer = await launchctl('kickstart', '-p', target(label))
+      if (answer.status === 0) { const pid = Number(String(answer.stdout ?? '').trim()); return { ok: true, pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null } }
+      return failed(LAUNCHD_NOT_FOUND.includes(answer.status) ? 'login-item-not-loaded' : 'login-item-start-failed', answer)
+    },
+    async remove({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const out = await bootout(label)
+      if (!out.ok) return out
+      const removed = files.remove(fileName)
+      return removed.ok ? { ok: true, removed: removed.removed || out.wasLoaded } : removed
+    },
+    async inspect({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const present = files.present(fileName)
+      const printed = await loaded(label)
+      const disabled = await launchctl('print-disabled', domain)
+      const job = printed.loaded === true ? readLaunchdPrint(printed.answer.stdout) : { state: null, pid: null, lastExit: null }
+      return {
+        ok: true, file: files.fileFor(fileName), present, loaded: printed.loaded, running: printed.loaded === true ? job.state === 'running' : printed.loaded === false ? false : null,
+        pid: job.pid, lastExit: job.lastExit, disabled: disabled.status === 0 ? readLaunchdDisabled(disabled.stdout, label) === true : null,
+      }
+    },
+  }
+}
+
+// Pure. The `KEY=value` lines of `systemctl show`.
+export function readSystemdShow(text) {
+  const values = {}
+  for (const line of String(text ?? '').split('\n')) {
+    const at = line.indexOf('=')
+    if (at > 0) values[line.slice(0, at).trim()] = line.slice(at + 1).trim()
+  }
+  const pid = Number(values.MainPID)
+  const exit = Number(values.ExecMainStatus)
+  return {
+    loadState: values.LoadState ?? null, activeState: values.ActiveState ?? null, subState: values.SubState ?? null, unitFileState: values.UnitFileState ?? null,
+    pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null, lastExit: values.ExecMainStatus === undefined || !Number.isInteger(exit) ? null : exit,
+  }
+}
+
+export function createSystemdManager({ run, systemctl, directory } = {}) {
+  if (typeof run !== 'function') throw new TypeError('a service manager needs run')
+  if (typeof systemctl !== 'string' || !path.isAbsolute(systemctl)) throw new TypeError('a systemd manager needs the absolute path of systemctl')
+  const files = unitFiles(directory)
+  const user = (...args) => run(systemctl, ['--user', ...args])
+  // A user instance that cannot be reached (no session bus: WSL, a container, a session without systemd) makes the
+  // first call fail; nothing is left behind by an installation it stopped.
+  const unreachable = (answer) => answer.status === null || /Failed to connect to bus|No medium found|not been booted with systemd|System has not been booted/i.test(`${answer.stderr ?? ''}`)
+  return {
+    kind: 'systemd-user-unit', platform: 'linux', directory: files.directory, fileFor: files.fileFor,
+    readUnit({ label, fileName }) { checkUnit({ label, fileName }); return files.read(fileName) },
+    async install({ label, fileName, text }) {
+      checkUnit({ label, fileName })
+      const existed = files.present(fileName)
+      const written = files.write(fileName, text)
+      if (!written.ok) return written
+      const reloaded = await user('daemon-reload')
+      if (reloaded.status !== 0) {
+        if (!existed) files.remove(fileName)
+        return failed(unreachable(reloaded) ? 'login-item-unavailable' : 'login-item-install-failed', reloaded)
+      }
+      const enabled = await user('enable', fileName)
+      if (enabled.status !== 0) return failed(unreachable(enabled) ? 'login-item-unavailable' : 'login-item-install-failed', enabled)
+      return { ok: true, file: files.fileFor(fileName) }
+    },
+    async start({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const answer = await user('start', fileName)
+      if (answer.status === 0) return { ok: true, pid: null }
+      return failed(unreachable(answer) ? 'login-item-unavailable' : /not found|not loaded|does not exist/i.test(`${answer.stderr ?? ''}`) ? 'login-item-not-loaded' : 'login-item-start-failed', answer)
+    },
+    async remove({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const disabled = await user('disable', '--now', fileName)
+      const missing = disabled.status !== 0 && /not found|not loaded|does not exist/i.test(`${disabled.stderr ?? ''}`)
+      if (disabled.status !== 0 && !missing) return failed(unreachable(disabled) ? 'login-item-unavailable' : 'login-item-remove-failed', disabled)
+      const removed = files.remove(fileName)
+      if (!removed.ok) return removed
+      await user('daemon-reload')
+      return { ok: true, removed: removed.removed || disabled.status === 0 }
+    },
+    async inspect({ label, fileName }) {
+      checkUnit({ label, fileName })
+      const present = files.present(fileName)
+      const answer = await user('show', '-p', 'LoadState,ActiveState,SubState,UnitFileState,MainPID,ExecMainStatus', fileName)
+      if (answer.status !== 0) return { ok: true, file: files.fileFor(fileName), present, loaded: null, running: null, pid: null, lastExit: null, disabled: null }
+      const unit = readSystemdShow(answer.stdout)
+      return {
+        ok: true, file: files.fileFor(fileName), present, loaded: unit.loadState === 'loaded', running: unit.activeState === 'active' || unit.activeState === 'activating',
+        pid: unit.pid, lastExit: unit.lastExit, disabled: unit.unitFileState === null ? null : !['enabled', 'enabled-runtime', 'linked', 'linked-runtime'].includes(unit.unitFileState),
+      }
+    },
+  }
+}

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

@@ -11,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
@@ -24,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$/
@@ -41,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'),
   }
 }
 
@@ -73,29 +79,60 @@ const releases = new Map()
 // 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. 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)) {
-    const hash = createHash('sha256')
-    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()) hash.update(`${child}\0${createHash('sha256').update(fs.readFileSync(path.join(root, child))).digest('hex')}\n`)
-      }
+// 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 })
-    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 }
-    releases.set(root, Object.freeze({ version, digest: `sha256:${hash.digest('hex')}` }))
   }
+  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
 // ---------------------------------------------------------------------------
@@ -195,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.mjs

@@ -1,5 +1,6 @@
 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'
@@ -48,9 +49,16 @@ import { createFsWatcherFactory } from './watchers.mjs'
 //
 // `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 }) {
@@ -85,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')
@@ -107,6 +120,7 @@ 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')
@@ -126,7 +140,7 @@ export async function runMaintenanceService(options = {}) {
   // view without the plugin for this tick; the view itself is prepared as ever.
   const pluginFor = (scopeId) => {
     try {
-      const vaultRoot = viewVaultRoot(workspaceRoot, scopeId)
+      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 })
@@ -193,6 +207,18 @@ export async function runMaintenanceService(options = {}) {
       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,
@@ -200,7 +226,14 @@ export async function runMaintenanceService(options = {}) {
       // 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' } }
       askForDriftedViews()
-      return engine.tick()
+      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) }
+      }
     },
   })
 
@@ -296,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, release: releaseIdentity() } }, 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 },
       },
     })