@push.rocks/smartdaemon 2.18.0 → 2.19.1

package/readme.md

@@ -249,7 +249,10 @@ unit was started right after the release and stored descriptors again, which a c
 read as a failed clean. A refused clean, or one that could not be run, rejects with
 `command_failed`; so does a clean whose `systemctl` call exceeded `commandTimeoutMs`, whose outcome
 is unknown because the manager may have released the store before the client was killed. After
-`command_failed` a caller must `inspect()` the unit before treating the store as kept.
+`command_failed` a caller must `inspect()` the unit before treating the store as kept. Cleaning a
+store needs systemd 254 or later: the call reads the manager's version first and refuses an older
+manager with `SystemdUnitManagerTooOldError` (`manager_too_old`), an unreadable version with
+`version_unknown` and an unanswered read with `command_failed`, each without running the clean.
 
 `inspectConfiguration()` reports the selected `fragmentPath`, opaque `dropInPaths`
 list and `needsReload` flag. `reloadConfiguration()` explicitly reloads the manager's
@@ -269,10 +272,12 @@ extension a running start requested), `limitNoFile` and `limitNoFileSoft`
 (`0` without a store), `fileDescriptorStorePreserve` (`no`, `yes` or `restart`) and `environment`, the
 unit's own `Environment=` variables as a frozen name-to-value object (variables the manager gives
 every unit, `EnvironmentFile=` and `PassEnvironment=` are not included). A missing, repeated,
-foreign or malformed property rejects with `invalid_state`, so a manager too old to report one of
-them fails closed (systemd 253 and older know no `FileDescriptorStorePreserve`, so
-`inspectServiceSettings()` needs systemd 254 or later); this includes an `Environment=` value holding a control character, which
-`systemctl show` prints as a C escape. Every environment a `SystemdServiceDefinition` accepts
+foreign or malformed property rejects with `invalid_state`; this includes an `Environment=` value
+holding a control character, which `systemctl show` prints as a C escape. `inspectServiceSettings()`
+needs systemd 254 or later, the first to report `FileDescriptorStorePreserve`: it reads the manager's
+version first and refuses an older manager with `SystemdUnitManagerTooOldError` (`manager_too_old`)
+and an unreadable version with `version_unknown`, both before the unit is read (see *The manager's
+version* below). Every environment a `SystemdServiceDefinition` accepts
 reads back. Reload changed files first; the snapshot describes what the manager loaded.
 
 `execStart` lists every `ExecStart=` command of the loaded unit, drop-ins included, in the order
@@ -318,6 +323,43 @@ target and the actual network provider; inspect the provider's `requires` and
 `after` as well. Recheck the exact file digest, selected fragment, absence of
 drop-ins and `needsReload === false` before permitting dependent activation.
 
+#### The manager's version
+
+`inspectManagerVersion()` reads the running manager's version through the unit's scope — the
+system manager, or the calling user's manager for `scope: 'user'` — with `systemctl show
+--property=Version`, the same `systemctlPath`, environment and timeout as every other call. It
+resolves with a frozen `ISystemdManagerVersion`: `major` (`255`) and `version`, the manager's
+`Version` property verbatim (`255.4-1ubuntu8.17`). This is the running manager's version, which after
+a package upgrade differs from `systemctl --version` until the manager re-executes. A manager that
+does not answer rejects with `command_failed`; an answer that is not a single `Version=` line with a
+version starting with a major of one to four digits rejects with `version_unknown`.
+
+`requireManagerVersion(requiredMajor)` resolves with that version when its `major` is at least
+`requiredMajor` (an integer from 1 to 9999; anything else rejects with `invalid_options` before any
+command) and otherwise rejects with a `SystemdUnitManagerTooOldError`: a `SystemdUnitError` with code
+`manager_too_old` that carries the `managerVersion` it read and the `requiredMajor`. Calls that need a
+newer manager use it and fail closed: `inspectServiceSettings()`, `cleanFileDescriptorStore()` and
+installing a definition with a `requiredManagerMajor` (see `SystemdUnitFile.install()`), so none fails
+late with a generic code. `runInTransientScope()` refuses an older user manager the same way with its
+own `SystemdTransientScopeManagerTooOldError`.
+
+```typescript
+import { SystemdUnit, SystemdUnitManagerTooOldError } from '@push.rocks/smartdaemon';
+
+const unit = new SystemdUnit({ unitName: 'pallet-node.service' });
+console.log((await unit.inspectManagerVersion()).major); // 255
+try {
+  await unit.inspectServiceSettings();
+} catch (error) {
+  if (error instanceof SystemdUnitManagerTooOldError) {
+    // e.g. 'systemd 253 (253.5-1) running, 254 required'
+    console.error(`systemd ${error.managerVersion.major} (${error.managerVersion.version}) running, ` +
+      `${error.requiredMajor} required`);
+  }
+  throw error;
+}
+```
+
 ### Installing a direct systemd service definition
 
 `SystemdServiceDefinition` encodes a literal executable and argument list, with
@@ -584,8 +626,11 @@ loads an explicit `NotifyAccess=none` beside a store as `main`, so `'none'` is r
 (systemd's default) once it is neither active nor about to restart, and `'yes'` only when the
 unit leaves the manager's memory or `SystemdUnit.cleanFileDescriptorStore()` releases it. A reboot
 empties the store; a `systemctl soft-reboot` keeps the running kernel, so a preserved store and the
-descriptors in it pass on to the next userspace boot. Systemd reads `FileDescriptorStorePreserve=` from version 254;
-an older manager ignores the line. Sending `FDSTORE=1` needs an `AF_UNIX` socket, so a definition
+descriptors in it pass on to the next userspace boot. Systemd reads `FileDescriptorStorePreserve=` from version 254
+and an older manager would ignore the line, so a definition with `fileDescriptorStorePreserve` has
+`requiredManagerMajor` 254 and `SystemdUnitFile.install()` refuses it on an older manager with
+`SystemdUnitManagerTooOldError` (`manager_too_old`) before touching anything; every other definition
+has `requiredManagerMajor` null. Sending `FDSTORE=1` needs an `AF_UNIX` socket, so a definition
 with a store or a notify access other than `'none'` that restricts its socket families must allow
 `AF_UNIX`. Omitted, each option renders nothing.
 
@@ -820,7 +865,11 @@ directories and regular single-link mode-0644 files, retains changed definitions
 as `<unit>.previous-<sha256>`, flushes them before atomic replacement, reloads
 the manager and checks its selected fragment and final bytes. A reload failure
 leaves the new file and retained previous definition in place; recovery requires
-inspection, never an automatic rollback. Filesystem and definition errors use
+inspection, never an automatic rollback. A definition whose `requiredManagerMajor` is not null is
+admitted only on a manager at least that new, read with `SystemdUnit.requireManagerVersion()` before
+any directory, file or other `systemctl` effect; that read's refusal propagates unchanged as the
+unit's `SystemdUnitError`: `manager_too_old` (a `SystemdUnitManagerTooOldError`), `version_unknown`,
+or `command_failed` when the manager does not answer. Filesystem and definition errors use
 `SystemdUnitFileError` with a local code; every `unsafe_path` refusal is a
 `SystemdUnitFileUnsafePathError` naming the offending `path` and its `reason`, and
 every `unsafe_unit` refusal is a `SystemdUnitFileUnsafeUnitError` naming its `reason`
@@ -893,7 +942,8 @@ refused options), the `stderr` read so far and one of these codes:
 | --- | --- |
 | `invalid_options` | Malformed options, or a runtime directory that is not a private directory of the caller |
 | `unsupported_platform` | The process is not running on Linux |
-| `user_manager_unavailable` | No `XDG_RUNTIME_DIR` (or `runtimeDirectory`), a runtime directory that does not exist, or a manager that does not answer `systemctl --user` |
+| `user_manager_unavailable` | No `XDG_RUNTIME_DIR` (or `runtimeDirectory`), a runtime directory that does not exist, or a manager that does not answer `systemctl --user show --property=Version` with a version as `SystemdUnit.inspectManagerVersion()` reads it |
+| `manager_too_old` | The user manager is older than systemd 254; a `SystemdTransientScopeManagerTooOldError` naming its `managerVersion` and the `requiredMajor`. Nothing was started |
 | `scope_start_failed` | systemd-run exited without reporting the scope running; the program has not run |
 | `timed_out` | The manager probe or the program did not finish and close its output within `commandTimeoutMs` |
 | `output_limit` | The program's stdout or stderr exceeded 1 MiB |
@@ -905,8 +955,11 @@ its daemon's output); otherwise the call runs into its timeout. On `timed_out` a
 the scope. `commandTimeoutMs` (default 120000, maximum 600000) bounds the probe
 and the program each. Trusted owning code can set `runtimeDirectory` and the
 absolute `systemdRunPath` and `systemctlPath`. systemd-run reports the started
-scope as its first stderr line, which systemd 254 and later print; an older
-systemd-run, which lacks `--expand-environment`, fails with `scope_start_failed`.
+scope as its first stderr line, which systemd 254 and later print, and systemd-run
+before 254 lacks `--expand-environment`. The manager probe's version stands for the
+installation's: a user manager older than 254 is refused with `manager_too_old`
+before systemd-run starts. A systemd-run older than the manager it addresses still
+fails with `scope_start_failed`.
 If the program cannot be executed after the scope started, systemd-run reports
 that as the program's exit status 1.
 
@@ -1085,6 +1138,9 @@ console.log(template); // View generated systemd unit file
 ## 🏗️ System Requirements
 
 - **Operating System**: Linux with systemd (Ubuntu 16.04+, Debian 9+, CentOS 7+, RHEL 7+, Fedora, Arch, etc.)
+- **systemd 254 or later** for `SystemdUnit.inspectServiceSettings()`, `SystemdUnit.cleanFileDescriptorStore()`,
+  `runInTransientScope()` and for installing a definition with `fileDescriptorStorePreserve` (Debian 13,
+  Ubuntu 24.04, Fedora 39 and later ship it); an older manager is refused by name with `manager_too_old`
 - **Node.js**: Version 14.x or higher
 - **Permissions**: Either root access or properly configured sudo
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdaemon',
-  version: '2.18.0',
+  version: '2.19.1',
   description: 'Start scripts as long running daemons and manage them.'
 }

package/ts/classes.systemdservicedefinition.ts

@@ -2,6 +2,7 @@ import * as plugins from './smartdaemon.plugins.js';
 import { environmentByteLimit, environmentVariableLimit, isCleanText, renderServiceRelations, systemdAddressFamilies,
   systemdCapabilities, type TSystemdServiceStartup, type ISystemdServiceDependencies, type ISystemdServiceInstallTargets,
   type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily } from './systemd.definition.js';
+import { fileDescriptorStorePreserveMajor } from './systemd.managerversion.js';
 export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
   ISystemdServiceDependencies, ISystemdServiceInstallTargets, ISystemdServiceCredential, TSystemdCapability,
   TSystemdAddressFamily } from './systemd.definition.js';
@@ -65,7 +66,9 @@ interface ISystemdServiceDefinitionBaseOptions {
    * When the manager releases the store (`FileDescriptorStorePreserve=`, systemd 254 or later):
    * `'no'` when the service stops, `'restart'` (systemd's default) once it is neither active nor
    * about to restart, `'yes'` only when the unit leaves the manager's memory or is cleaned with
-   * `SystemdUnit.cleanFileDescriptorStore()`. Requires `fileDescriptorStoreMax`.
+   * `SystemdUnit.cleanFileDescriptorStore()`. Requires `fileDescriptorStoreMax`. Sets
+   * `requiredManagerMajor` to 254, so `SystemdUnitFile.install()` refuses an older manager, which
+   * would ignore the line.
    */
   fileDescriptorStorePreserve?: 'no' | 'yes' | 'restart';
   /**
@@ -172,6 +175,12 @@ export class SystemdServiceDefinition {
   public readonly scope: 'system' | 'user';
   public readonly content: string;
   public readonly sha256: string;
+  /**
+   * The oldest systemd major whose manager reads every directive this definition renders, when it
+   * renders one an older manager would ignore: 254 with `fileDescriptorStorePreserve`; otherwise
+   * null. `SystemdUnitFile.install()` refuses a definition on an older manager.
+   */
+  public readonly requiredManagerMajor: number | null;
 
   constructor(options: ISystemdServiceDefinitionOptions) {
     const fail = (option: TSystemdServiceDefinitionOption): never => {
@@ -508,6 +517,8 @@ export class SystemdServiceDefinition {
     ].join('\n');
     requireValue(Buffer.byteLength(this.content) <= 16384, 'options');
     this.sha256 = plugins.crypto.createHash('sha256').update(this.content).digest('hex');
+    this.requiredManagerMajor = options.fileDescriptorStorePreserve !== undefined
+      ? fileDescriptorStorePreserveMajor : null;
     Object.freeze(this);
   }
 }

package/ts/classes.systemdtransientscope.ts

@@ -1,6 +1,12 @@
 import * as plugins from './smartdaemon.plugins.js';
 import { isCleanText } from './systemd.definition.js';
 import { captureUserEnvironment, inspectRuntimeDirectory, isSafeDirectory } from './systemd.userenvironment.js';
+import {
+  type ISystemdManagerVersion,
+  managerVersionArguments,
+  parseManagerVersion,
+  transientScopeMajor,
+} from './systemd.managerversion.js';
 
 export interface ISystemdTransientScopeOptions {
   /** The calling user's manager; the only manager a transient scope is started in. */
@@ -51,8 +57,16 @@ export type TSystemdTransientScopeErrorCode =
   | 'invalid_options'
   /** The process is not running on Linux. */
   | 'unsupported_platform'
-  /** No runtime directory is set or it does not exist, or the manager does not answer systemctl. */
+  /**
+   * No runtime directory is set or it does not exist, or the manager does not answer systemctl
+   * with a version it reports as systemd does (`SystemdUnit.inspectManagerVersion()`).
+   */
   | 'user_manager_unavailable'
+  /**
+   * The user manager is older than systemd 254, whose systemd-run this call needs; always a
+   * `SystemdTransientScopeManagerTooOldError`. Nothing was started.
+   */
+  | 'manager_too_old'
   /** systemd-run exited without reporting the scope running; the program has not run. */
   | 'scope_start_failed'
   /** The manager probe or the program did not finish, and close its output, in time. */
@@ -74,6 +88,24 @@ export class SystemdTransientScopeError extends Error {
   }
 }
 
+/** Every `manager_too_old` refusal: names the user manager's version and the one required. */
+export class SystemdTransientScopeManagerTooOldError extends SystemdTransientScopeError {
+  declare public readonly code: 'manager_too_old';
+
+  constructor(
+    unitName: string,
+    /** The user manager's version the probe read. */
+    public readonly managerVersion: ISystemdManagerVersion,
+    /** The oldest systemd major the call needs. */
+    public readonly requiredMajor: number,
+  ) {
+    super('manager_too_old', unitName, '');
+    this.message = `Systemd transient scope failed: manager_too_old (${unitName}: systemd ` +
+      `${managerVersion.major} running, ${requiredMajor} required).`;
+    this.name = 'SystemdTransientScopeManagerTooOldError';
+  }
+}
+
 const outputLimit = 1048576;
 const reservedName = (name: string) =>
   name === 'XDG_RUNTIME_DIR' || name === 'INVOCATION_ID' || name.startsWith('SYSTEMD_') || name.startsWith('DBUS_');
@@ -227,7 +259,9 @@ const programStderr = (stderr: string, unitName: string): string | undefined =>
  * must not keep the program's stdout or stderr open, or the call runs into its timeout.
  *
  * On `timed_out` and `output_limit` the direct process is killed; processes it started stay in
- * the scope. A program that exits with a failure status is a result, not an error.
+ * the scope. A program that exits with a failure status is a result, not an error. A user manager
+ * older than systemd 254 is refused with `SystemdTransientScopeManagerTooOldError` before
+ * systemd-run is started.
  */
 export const runInTransientScope = async (
   options: ISystemdTransientScopeOptions,
@@ -247,13 +281,19 @@ export const runInTransientScope = async (
   if (admission !== 'private') fail('invalid_options');
 
   const probe = await runProcess(validated.systemctlPath,
-    ['--user', '--no-ask-password', '--no-pager', 'show', '--property=Version'],
+    ['--user', '--no-ask-password', '--no-pager', ...managerVersionArguments],
     { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C', XDG_RUNTIME_DIR: runtimeDirectory! }, validated.timeoutMs);
   if (probe.kind === 'timed_out') fail('timed_out', probe.stderr);
-  if (probe.kind !== 'exited' || probe.code !== 0 || !probe.stdout.startsWith('Version=')) {
-    fail('user_manager_unavailable', probe.kind === 'spawn_failed' ? '' : probe.stderr,
+  const managerVersion = probe.kind === 'exited' && probe.code === 0 ? parseManagerVersion(probe.stdout) : undefined;
+  if (managerVersion === undefined) {
+    return fail('user_manager_unavailable', probe.kind === 'spawn_failed' ? '' : probe.stderr,
       probe.kind === 'spawn_failed' ? probe.error : undefined);
   }
+  // systemd-run before 254 knows no --expand-environment; the running user manager's version is the
+  // one this call can read before starting anything, so it stands for the installation's.
+  if (managerVersion.major < transientScopeMajor) {
+    throw new SystemdTransientScopeManagerTooOldError(unitName, managerVersion, transientScopeMajor);
+  }
 
   // systemd-run registers its own process as the scope, then executes the program in place with
   // its environment, so that environment is the program's own plus INVOCATION_ID.

package/ts/classes.systemdunit.ts

@@ -8,6 +8,14 @@ import {
   isUserManagerEnvironment,
 } from './systemd.userenvironment.js';
 import { environmentByteLimit, environmentVariableLimit, isCleanText } from './systemd.definition.js';
+import {
+  type ISystemdManagerVersion,
+  fileDescriptorStoreCleanMajor,
+  fileDescriptorStorePreserveMajor,
+  managerVersionArguments,
+  parseManagerVersion,
+} from './systemd.managerversion.js';
+export type { ISystemdManagerVersion } from './systemd.managerversion.js';
 
 export interface ISystemdUnitOptions {
   unitName: string;
@@ -171,8 +179,17 @@ export class SystemdUnitError extends Error {
     /**
      * `released_uninspected`: only `cleanFileDescriptorStore()`. The manager released the store, and
      * the snapshot read afterwards failed; `cause` is that inspection's error.
+     * `version_unknown`: the manager answered, but its `Version` property is not one this package
+     * reads, so a call that needs a minimum manager version refuses.
+     * `manager_too_old`: always a `SystemdUnitManagerTooOldError`, naming both versions.
      */
-    public readonly code: 'invalid_options' | 'command_failed' | 'invalid_state' | 'released_uninspected',
+    public readonly code:
+      | 'invalid_options'
+      | 'command_failed'
+      | 'invalid_state'
+      | 'released_uninspected'
+      | 'version_unknown'
+      | 'manager_too_old',
     options?: ErrorOptions,
   ) {
     super(`Systemd unit operation failed: ${code}.`, options);
@@ -180,6 +197,23 @@ export class SystemdUnitError extends Error {
   }
 }
 
+/** Every `manager_too_old` refusal: the running manager is older than the call needs. */
+export class SystemdUnitManagerTooOldError extends SystemdUnitError {
+  declare public readonly code: 'manager_too_old';
+
+  constructor(
+    /** The running manager's version the refusal read. */
+    public readonly managerVersion: ISystemdManagerVersion,
+    /** The oldest systemd major the refused call needs. */
+    public readonly requiredMajor: number,
+  ) {
+    super('manager_too_old');
+    this.message = `Systemd unit operation failed: manager_too_old (systemd ${managerVersion.major} ` +
+      `running, ${requiredMajor} required).`;
+    this.name = 'SystemdUnitManagerTooOldError';
+  }
+}
+
 // systemd's format_timespan() units, largest first; a year and a month are 365.25 and 30.44 days.
 const timespanUnits = new Map<string, bigint>([
   ['y', 31557600000000n], ['month', 2629800000000n], ['w', 604800000000n], ['d', 86400000000n],
@@ -514,11 +548,42 @@ export class SystemdUnit {
     });
   }
 
+  /**
+   * Reads the running manager's version (`systemctl show --property=Version`) through the unit's
+   * scope: the system manager, or the calling user's manager for user scope. A manager that does
+   * not answer rejects with `command_failed`; an answer this package cannot read, with
+   * `version_unknown`.
+   */
+  public async inspectManagerVersion(): Promise<ISystemdManagerVersion> {
+    const version = parseManagerVersion(await this.command([...managerVersionArguments]));
+    if (version === undefined) throw new SystemdUnitError('version_unknown');
+    return version;
+  }
+
+  /**
+   * Resolves with the running manager's version when its major is at least `requiredMajor`, an
+   * integer from 1 to 9999; otherwise rejects with a `SystemdUnitManagerTooOldError`. Fails closed:
+   * an unreadable version rejects with `version_unknown`, an unanswered read with
+   * `command_failed`, and a malformed `requiredMajor` with `invalid_options` before any command.
+   */
+  public async requireManagerVersion(requiredMajor: number): Promise<ISystemdManagerVersion> {
+    if (!Number.isSafeInteger(requiredMajor) || requiredMajor < 1 || requiredMajor > 9999) {
+      throw new SystemdUnitError('invalid_options');
+    }
+    const version = await this.inspectManagerVersion();
+    if (version.major < requiredMajor) throw new SystemdUnitManagerTooOldError(version, requiredMajor);
+    return version;
+  }
+
   /**
    * Reports the loaded service settings that a definition renders, so an owner can verify an
    * installed unit carries them. Reads only; the manager must have reloaded changed files first.
+   * Needs systemd 254 or later, which first reports `FileDescriptorStorePreserve`: an older manager
+   * is refused with `SystemdUnitManagerTooOldError` before the unit is read, and so is a manager
+   * whose version is unreadable, with `version_unknown`.
    */
   public async inspectServiceSettings(): Promise<ISystemdServiceSettings> {
+    await this.requireManagerVersion(fileDescriptorStorePreserveMajor);
     const keys = ['Id', 'Type', 'NotifyAccess', 'Restart', 'RestartUSec', 'KillMode', 'TimeoutStopUSec',
       'TimeoutStartUSec', 'RestartPreventExitStatus', 'SuccessExitStatus', 'StartLimitIntervalUSec', 'StartLimitBurst',
       'Delegate', 'LimitNOFILE', 'LimitNOFILESoft', 'TasksMax', 'OOMScoreAdjust', 'FileDescriptorStoreMax',
@@ -530,7 +595,7 @@ export class SystemdUnit {
       if (separator < 1 || !keys.includes(key) || fields.has(key)) throw new SystemdUnitError('invalid_state');
       fields.set(key, line.slice(separator + 1));
     }
-    // An older manager omits a property it does not know; the count check refuses that snapshot.
+    // A manager that omits a requested property it should know fails this count check.
     if (fields.size !== keys.length || fields.get('Id') !== this.unitName) throw new SystemdUnitError('invalid_state');
     const mode = (key: string, empty = false): string => {
       const value = fields.get(key)!;
@@ -596,8 +661,13 @@ export class SystemdUnit {
    * or that could not be run rejects with `command_failed`; so does one whose `systemctl` call
    * exceeded `commandTimeoutMs`, whose outcome is then unknown, so after `command_failed` a caller
    * must `inspect()` the unit before treating the store as kept.
+   *
+   * Needs systemd 254 or later, the first that cleans a store: the manager's version is read first,
+   * and an older manager is refused with `SystemdUnitManagerTooOldError`, an unreadable version with
+   * `version_unknown` and an unanswered read with `command_failed`, each before any clean is run.
    */
   public async cleanFileDescriptorStore(): Promise<ISystemdUnitState> {
+    await this.requireManagerVersion(fileDescriptorStoreCleanMajor);
     await this.command(['clean', '--what=fdstore', this.unitName]);
     try {
       return await this.inspect();

package/ts/classes.systemdunitfile.ts

@@ -270,6 +270,11 @@ export class SystemdUnitFile {
   /**
    * Expected previous digest is mandatory; null admits an absent file. Exact desired bytes are idempotent.
    * Retains changed definitions beside the unit before replacement. A failed reload never rolls code back.
+   *
+   * A definition with a `requiredManagerMajor` is admitted only on a manager at least that new,
+   * read before any directory, file or other systemctl effect: an older manager rejects with
+   * the unit's `SystemdUnitManagerTooOldError` (`manager_too_old`), an unreadable version with
+   * `SystemdUnitError` `version_unknown` and a failed read with `SystemdUnitError` `command_failed`.
    */
   public async install(
     definition: SystemdServiceDefinition,
@@ -288,6 +293,10 @@ export class SystemdUnitFile {
     // instead of a wrapped write_failed.
     const maskDirectories = this.maskDirectories();
     if (maskDirectories === null) throw new SystemdUnitFileError('invalid_options');
+    // A manager older than the definition needs would load the unit without the newer directives.
+    if (definition.requiredManagerMajor !== null) {
+      await this.unit.requireManagerVersion(definition.requiredManagerMajor);
+    }
     requireValue(!this.busy, 'busy');
     this.busy = true;
     let temporary: string | undefined;

package/ts/smartdaemon.plugins.ts

@@ -14,7 +14,7 @@ export { path, childProcess, fs, fsConstants, crypto, util, os };
 import * as lik from '@push.rocks/lik';
 import * as smartfs from '@push.rocks/smartfs';
 import * as smartlog from '@push.rocks/smartlog';
-import * as smartlogDestinationLocal from '@push.rocks/smartlog-destination-local';
+import * as smartlogDestinationLocal from '@push.rocks/smartlog/destination-local';
 import * as smartmarkdown from '@push.rocks/smartmarkdown/iso';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartshell from '@push.rocks/smartshell';

package/ts/systemd.managerversion.ts

@@ -0,0 +1,38 @@
+/** The version of a running systemd manager, as the manager itself reports it. */
+export interface ISystemdManagerVersion {
+  /** systemd's major version: the leading number of `version`, `255` for `255.4-1ubuntu8.17`. */
+  readonly major: number;
+  /**
+   * The manager's `Version` property verbatim, as its build names it: `255.4-1ubuntu8.17`,
+   * `253.5-1`, `256~rc3` or `257.1-1.fc41`. It is the running manager's version, which differs
+   * from `systemctl --version` after an upgrade until the manager re-executes.
+   */
+  readonly version: string;
+}
+
+/** Internal: the systemd major that first reads `FileDescriptorStorePreserve=` and reports it. */
+export const fileDescriptorStorePreserveMajor = 254;
+
+/** Internal: the systemd major whose `systemctl clean` first releases a file descriptor store (`--what=fdstore`). */
+export const fileDescriptorStoreCleanMajor = 254;
+
+/**
+ * Internal: the systemd major whose `systemd-run` first takes `--expand-environment` and reports a
+ * started scope as `runInTransientScope()` reads it.
+ */
+export const transientScopeMajor = 254;
+
+/** Internal: the `systemctl` verb and argument that print the manager's `Version` property. */
+export const managerVersionArguments: readonly string[] = ['show', '--property=Version'];
+
+/**
+ * Internal: parses the output of `systemctl show --property=Version`, exactly one
+ * `Version=<version>` line. The version is a major of 1–4 digits without a leading zero,
+ * optionally followed by a separator (`.`, `~`, `-`, `+`, `^` or `_`) and printable ASCII, at
+ * most 256 characters in all. Anything else, `systemctl --version`'s `systemd 255 (255.4-1)`
+ * format included, is refused with undefined.
+ */
+export const parseManagerVersion = (stdout: string): ISystemdManagerVersion | undefined => {
+  const match = /^Version=(([1-9][0-9]{0,3})(?:[.~+^_-][\x21-\x7e]{0,251})?)\n$/.exec(stdout);
+  return match ? Object.freeze({ major: Number(match[2]), version: match[1] }) : undefined;
+};