@push.rocks/smartdaemon 2.7.1 → 2.8.0

package/ts/classes.systemdservicedefinition.ts

@@ -1,7 +1,8 @@
 import * as plugins from './smartdaemon.plugins.js';
-import { renderServiceRelations, type ISystemdServiceStartup, type ISystemdServiceDependencies,
+import { renderServiceRelations, type TSystemdServiceStartup, type ISystemdServiceDependencies,
   type ISystemdServiceInstallTargets } from './systemd.definition.js';
-export type { ISystemdServiceStartup, ISystemdServiceDependencies, ISystemdServiceInstallTargets } from './systemd.definition.js';
+export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
+  ISystemdServiceDependencies, ISystemdServiceInstallTargets } from './systemd.definition.js';
 
 interface ISystemdServiceDefinitionBaseOptions {
   unitName: string;
@@ -10,11 +11,21 @@ interface ISystemdServiceDefinitionBaseOptions {
   args: readonly string[];
   workingDirectory: string;
   restart: 'no' | 'on-failure' | 'always';
-  killMode: 'mixed' | 'control-group';
+  killMode: 'mixed' | 'control-group' | 'process';
   timeoutStopSeconds: number;
-  startup?: ISystemdServiceStartup;
+  startup?: TSystemdServiceStartup;
   dependencies?: ISystemdServiceDependencies;
   install?: ISystemdServiceInstallTargets;
+  /** Integer seconds from 1 to 600 before a restart (`RestartSec=`). Refused with `restart: 'no'`. */
+  restartSeconds?: number;
+  /** Leaves the cgroups of the processes this service starts to them (`Delegate=`). */
+  delegate?: boolean;
+  /** Soft and hard open-file limit (`LimitNOFILE=`): a positive integer or `'infinity'`. */
+  limitNoFile?: number | 'infinity';
+  /** Task limit of the unit's cgroup (`TasksMax=`): a positive integer or `'infinity'`. */
+  tasksMax?: number | 'infinity';
+  /** Integer from -1000 to 1000 (`OOMScoreAdjust=`). */
+  oomScoreAdjust?: number;
 }
 
 export type ISystemdServiceDefinitionOptions = ISystemdServiceDefinitionBaseOptions & (
@@ -67,8 +78,10 @@ export class SystemdServiceDefinition {
       'timeoutStopSeconds',
       ...(scope === 'system' ? ['user', 'group'] : []),
     ];
+    const optionalKeys = ['scope', 'startup', 'dependencies', 'install', 'restartSeconds', 'delegate',
+      'limitNoFile', 'tasksMax', 'oomScoreAdjust'];
     requireValue(
-      Reflect.ownKeys(options).every(key => typeof key === 'string' && [...keys, 'scope', 'startup', 'dependencies', 'install'].includes(key)
+      Reflect.ownKeys(options).every(key => typeof key === 'string' && [...keys, ...optionalKeys].includes(key)
           && Object.getOwnPropertyDescriptor(options, key)?.enumerable && 'value' in Object.getOwnPropertyDescriptor(options, key)!) && keys.every((key) => {
           const descriptor = Object.getOwnPropertyDescriptor(options, key);
           return descriptor && 'value' in descriptor;
@@ -108,10 +121,35 @@ export class SystemdServiceDefinition {
     }
     requireValue(
       ['no', 'on-failure', 'always'].includes(options.restart) &&
-        ['mixed', 'control-group'].includes(options.killMode) &&
+        ['mixed', 'control-group', 'process'].includes(options.killMode) &&
         Number.isSafeInteger(options.timeoutStopSeconds) &&
         options.timeoutStopSeconds >= 1 && options.timeoutStopSeconds <= 600,
     );
+    const integer = (value: unknown, minimum: number, maximum: number): value is number =>
+      Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum;
+    const limit = (value: unknown): value is number | 'infinity' =>
+      value === 'infinity' || integer(value, 1, Number.MAX_SAFE_INTEGER);
+    // Each optional directive is absent unless supplied, so existing definitions keep their bytes.
+    const service: string[] = [];
+    if (options.restartSeconds !== undefined) {
+      requireValue(integer(options.restartSeconds, 1, 600) && options.restart !== 'no');
+    }
+    if (options.delegate !== undefined) {
+      requireValue(typeof options.delegate === 'boolean');
+      service.push(`Delegate=${options.delegate ? 'yes' : 'no'}`);
+    }
+    if (options.limitNoFile !== undefined) {
+      requireValue(limit(options.limitNoFile));
+      service.push(`LimitNOFILE=${options.limitNoFile}`);
+    }
+    if (options.tasksMax !== undefined) {
+      requireValue(limit(options.tasksMax));
+      service.push(`TasksMax=${options.tasksMax}`);
+    }
+    if (options.oomScoreAdjust !== undefined) {
+      requireValue(integer(options.oomScoreAdjust, -1000, 1000));
+      service.push(`OOMScoreAdjust=${options.oomScoreAdjust}`);
+    }
     // Quoting and percent/dollar escaping follow systemd.syntax and systemd.service.
     const quote = (value: string, command = false) =>
       '"' + value
@@ -135,12 +173,14 @@ export class SystemdServiceDefinition {
       // WorkingDirectory is a raw path value, not an ExecStart word list.
       `WorkingDirectory=${options.workingDirectory.replaceAll('%', '%%')}`,
       `Restart=${options.restart}`,
+      ...(options.restartSeconds !== undefined ? [`RestartSec=${options.restartSeconds}s`] : []),
       `KillMode=${options.killMode}`,
       'KillSignal=SIGTERM',
       'FinalKillSignal=SIGKILL',
       'SendSIGKILL=yes',
       'SendSIGHUP=no',
       `TimeoutStopSec=${options.timeoutStopSeconds}s`,
+      ...service,
       'StandardInput=null',
       'StandardOutput=journal',
       'StandardError=journal',

package/ts/classes.systemdunit.ts

@@ -1,12 +1,20 @@
 import * as plugins from './smartdaemon.plugins.js';
+import {
+  type ISystemdUserEnvironment,
+  type TSystemdUserManagerEnvironment,
+  captureUserEnvironment,
+  isSafeDirectory,
+  isUserManagerEnvironment,
+} from './systemd.userenvironment.js';
 
 export interface ISystemdUnitOptions {
   unitName: string;
   /** Defaults to the system manager. User scope addresses the calling user's manager only. */
   scope?: 'system' | 'user';
   /**
-   * User-manager socket directory. Defaults to a non-empty XDG_RUNTIME_DIR. May be absent at
-   * construction; every call that contacts the user manager then refuses with `invalid_options`.
+   * User-manager socket directory. Defaults to a non-empty XDG_RUNTIME_DIR. A supplied option must
+   * be well formed at construction. The process default may be absent or malformed there; every
+   * call that contacts the user manager then refuses with `invalid_options`.
    */
   runtimeDirectory?: string;
   /** Absolute executable path supplied by trusted owning code. */
@@ -48,6 +56,29 @@ export interface ISystemdUnitRelationships {
   readonly wantedBy: readonly string[];
 }
 
+/**
+ * Service settings as the manager loaded them, drop-ins included. Timespans are exact integer
+ * microseconds; a limit systemd reports as unbounded is `'infinity'`. Mode strings are systemd's
+ * own vocabulary, so a value this package does not render is still reported; `type` is empty for
+ * a unit systemd could not load.
+ */
+export interface ISystemdServiceSettings {
+  readonly unitName: string;
+  readonly type: string;
+  readonly notifyAccess: string;
+  readonly restart: string;
+  readonly restartMicroseconds: number | 'infinity';
+  readonly killMode: string;
+  readonly timeoutStopMicroseconds: number | 'infinity';
+  readonly delegate: boolean;
+  /** Hard open-file limit (`LimitNOFILE`). */
+  readonly limitNoFile: number | 'infinity';
+  /** Soft open-file limit (`LimitNOFILESoft`). */
+  readonly limitNoFileSoft: number | 'infinity';
+  readonly tasksMax: number | 'infinity';
+  readonly oomScoreAdjust: number;
+}
+
 export class SystemdUnitError extends Error {
   constructor(public readonly code: 'invalid_options' | 'command_failed' | 'invalid_state') {
     super(`Systemd unit operation failed: ${code}.`);
@@ -55,6 +86,37 @@ export class SystemdUnitError extends Error {
   }
 }
 
+// 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],
+  ['h', 3600000000n], ['min', 60000000n], ['s', 1000000n], ['ms', 1000n], ['us', 1n],
+]);
+
+/** Parses `systemctl show` timespans such as `0`, `100ms`, `1min 30s`, `1.500000s` or `infinity`. */
+const parseTimespan = (text: string): number | 'infinity' | undefined => {
+  if (text === 'infinity') return 'infinity';
+  if (text === '0') return 0;
+  const names = [...timespanUnits.keys()];
+  let total = 0n;
+  let previous = -1;
+  for (const part of text.split(' ')) {
+    const match = /^(0|[1-9]\d{0,19})(?:\.(\d{1,6}))?([a-z]+)$/.exec(part);
+    const index = match ? names.indexOf(match[3]) : -1;
+    if (!match || index <= previous) return undefined;
+    previous = index;
+    const scale = timespanUnits.get(match[3])!;
+    const fraction = match[2] === undefined ? 0n : BigInt(match[2].padEnd(6, '0')) * scale;
+    if (fraction % 1000000n !== 0n) return undefined;
+    total += BigInt(match[1]) * scale + fraction / 1000000n;
+  }
+  return total > 0n && total <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(total) : undefined;
+};
+
+/** `infinity` or a decimal unsigned integer within the safe integer range. */
+const parseLimit = (text: string): number | 'infinity' | undefined =>
+  text === 'infinity' ? 'infinity'
+    : /^(0|[1-9]\d*)$/.test(text) && Number.isSafeInteger(Number(text)) ? Number(text) : undefined;
+
 const properties = [
   'Id',
   'LoadState',
@@ -74,30 +136,21 @@ export class SystemdUnit {
   private readonly executable: string;
   private readonly timeout: number;
   private readonly scope: 'system' | 'user';
-  private readonly runtimeDirectory?: string;
-  private readonly homeDirectory?: string;
-  private readonly configDirectory?: string;
-  private readonly dataDirectory?: string;
+  /** Present exactly for user scope. */
+  private readonly userEnvironment?: ISystemdUserEnvironment;
 
   constructor(optionsArg: ISystemdUnitOptions) {
     this.unitName = optionsArg?.unitName;
     this.executable = optionsArg?.systemctlPath ?? '/usr/bin/systemctl';
     this.timeout = optionsArg?.commandTimeoutMs ?? 120000;
     this.scope = optionsArg?.scope ?? 'system';
-    // An empty XDG_RUNTIME_DIR counts as unset, like the sibling XDG variables below. An explicit
-    // option is never reinterpreted, so an empty or relative option stays malformed.
-    this.runtimeDirectory = this.scope === 'user'
-      ? optionsArg?.runtimeDirectory ?? (process.env.XDG_RUNTIME_DIR || undefined) : undefined;
-    this.homeDirectory = this.scope === 'user' ? plugins.os.userInfo().homedir : undefined;
-    this.configDirectory = this.scope === 'user' ? process.env.XDG_CONFIG_HOME || undefined : undefined;
-    this.dataDirectory = this.scope === 'user' ? process.env.XDG_DATA_HOME || undefined : undefined;
-    const safeDirectory = (value: unknown): value is string =>
-      typeof value === 'string' && value !== '/' && plugins.path.isAbsolute(value) &&
-      plugins.path.normalize(value) === value && !value.endsWith('/') &&
-      value.length <= 4000 && !/[\x00-\x1f\x7f]/.test(value);
-    // Only a supplied runtime directory is validated here. Its absence matters solely to calls that
-    // reach the user manager, and those refuse it in validateUserRuntime(). Admitting absence lets
-    // owners read protected unit files from contexts without a login session (cron, plain ssh).
+    this.userEnvironment = this.scope === 'user'
+      ? captureUserEnvironment(optionsArg?.runtimeDirectory) : undefined;
+    // Construction validates only the options it is given. The process-derived user environment
+    // (home, XDG config/data/runtime roots) is validated by userManagerEnvironment() before every
+    // systemctl call, because only those calls read it. SystemdUnitFile builds its unit at
+    // construction, so refusing that environment here would also refuse SystemdUnitFile.inspect(),
+    // which never contacts the manager.
     if (
       typeof this.unitName !== 'string' ||
       !/^[a-zA-Z0-9][a-zA-Z0-9_.:@-]{0,230}\.service$/.test(this.unitName) ||
@@ -106,11 +159,8 @@ export class SystemdUnit {
       this.timeout < 1 || this.timeout > 600000 ||
       !['system', 'user'].includes(this.scope) ||
       (this.scope === 'system' && optionsArg?.runtimeDirectory !== undefined) ||
-      (this.scope === 'user' &&
-        (this.runtimeDirectory !== undefined && !safeDirectory(this.runtimeDirectory) ||
-          !safeDirectory(this.homeDirectory) ||
-          this.configDirectory !== undefined && !safeDirectory(this.configDirectory) ||
-          this.dataDirectory !== undefined && !safeDirectory(this.dataDirectory)))
+      (this.scope === 'user' && optionsArg?.runtimeDirectory !== undefined &&
+        !isSafeDirectory(optionsArg.runtimeDirectory))
     ) throw new SystemdUnitError('invalid_options');
   }
 
@@ -221,17 +271,65 @@ export class SystemdUnit {
     });
   }
 
+  /**
+   * 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.
+   */
+  public async inspectServiceSettings(): Promise<ISystemdServiceSettings> {
+    const keys = ['Id', 'Type', 'NotifyAccess', 'Restart', 'RestartUSec', 'KillMode', 'TimeoutStopUSec',
+      'Delegate', 'LimitNOFILE', 'LimitNOFILESoft', 'TasksMax', 'OOMScoreAdjust'];
+    const stdout = await this.command(['show', this.unitName, `--property=${keys.join(',')}`, '--all']);
+    const fields = new Map<string, string>();
+    for (const line of (stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout).split('\n')) {
+      const separator = line.indexOf('='), key = line.slice(0, separator);
+      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.
+    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)!;
+      if (!(empty && value === '') && !/^[a-z][a-z-]{0,31}$/.test(value)) throw new SystemdUnitError('invalid_state');
+      return value;
+    };
+    const parsed = <T>(key: string, parse: (text: string) => T | undefined): T => {
+      const value = parse(fields.get(key)!);
+      if (value === undefined) throw new SystemdUnitError('invalid_state');
+      return value;
+    };
+    const oomScoreAdjust = parsed('OOMScoreAdjust', (text) =>
+      /^(0|-?[1-9]\d{0,3})$/.test(text) && Math.abs(Number(text)) <= 1000 ? Number(text) : undefined);
+    return Object.freeze({
+      unitName: this.unitName,
+      type: mode('Type', true),
+      notifyAccess: mode('NotifyAccess'),
+      restart: mode('Restart'),
+      restartMicroseconds: parsed('RestartUSec', parseTimespan),
+      killMode: mode('KillMode'),
+      timeoutStopMicroseconds: parsed('TimeoutStopUSec', parseTimespan),
+      delegate: parsed('Delegate', (text) => text === 'yes' ? true : text === 'no' ? false : undefined),
+      limitNoFile: parsed('LimitNOFILE', parseLimit),
+      limitNoFileSoft: parsed('LimitNOFILESoft', parseLimit),
+      tasksMax: parsed('TasksMax', parseLimit),
+      oomScoreAdjust,
+    });
+  }
+
   /** Reloads unit definitions globally; does not enable, unmask, start or stop a unit. */
   public async reloadConfiguration(): Promise<ISystemdUnitConfigurationState> {
     await this.command(['daemon-reload']);
     return this.inspectConfiguration();
   }
 
-  private async validateUserRuntime(): Promise<void> {
-    if (this.scope !== 'user') return;
-    // Runs before every systemctl invocation, so a missing directory refuses without side effects.
-    const runtimeDirectory = this.runtimeDirectory;
-    if (runtimeDirectory === undefined) throw new SystemdUnitError('invalid_options');
+  /**
+   * Runs before every systemctl invocation, so an absent or malformed user environment and a
+   * missing or unsafe runtime directory refuse without side effects. Undefined for system scope.
+   */
+  private async userManagerEnvironment(): Promise<TSystemdUserManagerEnvironment | undefined> {
+    const environment = this.userEnvironment;
+    if (environment === undefined) return undefined;
+    if (!isUserManagerEnvironment(environment)) throw new SystemdUnitError('invalid_options');
+    const runtimeDirectory = environment.runtimeDirectory;
     try {
       const uid = process.getuid?.();
       if (process.platform !== 'linux' || uid === undefined || process.geteuid?.() !== uid ||
@@ -244,10 +342,11 @@ export class SystemdUnit {
     } catch {
       throw new SystemdUnitError('invalid_options');
     }
+    return environment;
   }
 
   private async command(argsArg: string[]): Promise<string> {
-    await this.validateUserRuntime();
+    const userEnvironment = await this.userManagerEnvironment();
     return new Promise((resolve, reject) => {
       plugins.childProcess.execFile(
         this.executable,
@@ -258,11 +357,13 @@ export class SystemdUnit {
           killSignal: 'SIGKILL',
           maxBuffer: 16384,
           windowsHide: true,
-          env: this.scope === 'user'
+          env: userEnvironment
             ? { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C',
-              HOME: this.homeDirectory!, XDG_RUNTIME_DIR: this.runtimeDirectory!,
-              ...(this.configDirectory ? { XDG_CONFIG_HOME: this.configDirectory } : {}),
-              ...(this.dataDirectory ? { XDG_DATA_HOME: this.dataDirectory } : {}) }
+              HOME: userEnvironment.homeDirectory, XDG_RUNTIME_DIR: userEnvironment.runtimeDirectory,
+              ...(userEnvironment.configDirectory
+                ? { XDG_CONFIG_HOME: userEnvironment.configDirectory } : {}),
+              ...(userEnvironment.dataDirectory
+                ? { XDG_DATA_HOME: userEnvironment.dataDirectory } : {}) }
             : { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C' },
         },
         (error, stdout) => {

package/ts/classes.systemdunitfile.ts

@@ -6,6 +6,12 @@ import {
   type ISystemdUnitState,
   SystemdUnit,
 } from './classes.systemdunit.js';
+import {
+  type ISystemdUserEnvironment,
+  captureUserEnvironment,
+  isSafeDirectory,
+  isUserManagerEnvironment,
+} from './systemd.userenvironment.js';
 
 export interface ISystemdUnitFileOptions extends ISystemdUnitOptions {
   /** Local vendor definitions can be installed without removing an administrator's mask. */
@@ -13,6 +19,10 @@ export interface ISystemdUnitFileOptions extends ISystemdUnitOptions {
   /** Trusted owning-code qualification only. Defaults to root for system, current uid for user. */
   expectedUid?: number;
 }
+interface IMaskDirectories {
+  readonly persistent: readonly string[];
+  readonly runtime: readonly string[];
+}
 export interface ISystemdUnitFileRecord {
   readonly path: string;
   readonly sha256: string;
@@ -57,42 +67,65 @@ export class SystemdUnitFile {
   private readonly directory: string;
   private readonly uid: number;
   private readonly scope: 'system' | 'user';
-  private readonly configDirectory?: string;
-  private readonly runtimeDirectory?: string;
+  /** Present exactly for user scope; read only by the default path and by install(). */
+  private readonly userEnvironment?: ISystemdUserEnvironment;
   private readonly unit: SystemdUnit;
   private readonly name: string;
   private busy = false;
 
   constructor(options: ISystemdUnitFileOptions) {
+    // Validates the unit's explicit options, including a supplied runtime directory. Like this
+    // class, it captures but does not validate the process-derived user environment.
     this.unit = new SystemdUnit(options);
     this.name = options.unitName;
     this.scope = options.scope ?? 'system';
-    const home = this.scope === 'user' ? plugins.os.userInfo().homedir : undefined;
-    const dataDirectory = this.scope === 'user'
-      ? process.env.XDG_DATA_HOME || plugins.path.join(home!, '.local/share') : undefined;
-    this.configDirectory = this.scope === 'user'
-      ? process.env.XDG_CONFIG_HOME || plugins.path.join(home!, '.config') : undefined;
-    // Resolved exactly as SystemdUnit resolves it, so both agree on presence.
-    this.runtimeDirectory = this.scope === 'user'
-      ? options.runtimeDirectory ?? (process.env.XDG_RUNTIME_DIR || undefined) : undefined;
-    this.directory = options.unitDirectory ?? (this.scope === 'user'
-      ? plugins.path.join(dataDirectory!, 'systemd/user') : '/usr/local/lib/systemd/system');
+    // Captured in the same synchronous step as the unit's own snapshot, so both read equal values.
+    this.userEnvironment = this.scope === 'user'
+      ? captureUserEnvironment(options.runtimeDirectory) : undefined;
+    const directory = options.unitDirectory ?? this.defaultDirectory();
     this.uid = options.expectedUid ?? (this.scope === 'user' ? process.getuid?.() ?? -1 : 0);
-    const validDirectory = (directory: unknown): directory is string =>
-      typeof directory === 'string' && directory !== '/' &&
-        plugins.path.isAbsolute(directory) && plugins.path.normalize(directory) === directory &&
-        !directory.endsWith('/') && !/[\x00-\x1f\x7f]/.test(directory) &&
-        directory.length <= 4000;
-    requireValue(
-      validDirectory(this.directory) && Number.isSafeInteger(this.uid) && this.uid >= 0 &&
-        (this.scope === 'system' ||
-          this.uid === process.getuid?.() && validDirectory(this.configDirectory) &&
-          // inspect() reads only the unit directory, so an absent runtime directory is refused
-          // later, by install(); a supplied one must still be well formed.
-          (this.runtimeDirectory === undefined || validDirectory(this.runtimeDirectory))),
-      'invalid_options',
-    );
-    this.path = plugins.path.join(this.directory, this.name);
+    // inspect() reads the unit directory as this uid and nothing else. The config and runtime
+    // roots and the manager environment are refused later, by install(), before any effect.
+    if (
+      !isSafeDirectory(directory) || !Number.isSafeInteger(this.uid) || this.uid < 0 ||
+      this.scope === 'user' && this.uid !== process.getuid?.()
+    ) throw new SystemdUnitFileError('invalid_options');
+    this.directory = directory;
+    this.path = plugins.path.join(directory, this.name);
+  }
+
+  /**
+   * Only the default location reads XDG_DATA_HOME, or the home directory when that is unset. The
+   * public path exists from construction, so a malformed source refuses there: joining would
+   * otherwise normalize a value such as `/data/../elsewhere` into a plausible directory.
+   */
+  private defaultDirectory(): string | undefined {
+    const environment = this.userEnvironment;
+    if (environment === undefined) return '/usr/local/lib/systemd/system';
+    const dataDirectory = environment.dataDirectory ?? (isSafeDirectory(environment.homeDirectory)
+      ? plugins.path.join(environment.homeDirectory, '.local/share') : undefined);
+    return isSafeDirectory(dataDirectory) ? plugins.path.join(dataDirectory, 'systemd/user') : undefined;
+  }
+
+  /**
+   * Directories whose entry for this unit is a mask the manager may report. Only install() reads
+   * them. Null when the user environment cannot drive the manager or name the config root.
+   */
+  private maskDirectories(): IMaskDirectories | null {
+    const environment = this.userEnvironment;
+    if (environment === undefined) {
+      return { persistent: ['/etc/systemd/system'], runtime: ['/run/systemd/system'] };
+    }
+    const configDirectory = environment.configDirectory ??
+      (isSafeDirectory(environment.homeDirectory)
+        ? plugins.path.join(environment.homeDirectory, '.config') : undefined);
+    if (!isUserManagerEnvironment(environment) || !isSafeDirectory(configDirectory)) return null;
+    const userDirectories = (roots: readonly string[]) =>
+      roots.map(root => plugins.path.join(root, 'systemd/user'));
+    return {
+      persistent: userDirectories([configDirectory, '/etc']),
+      runtime: userDirectories([environment.runtimeDirectory, '/run']),
+    };
   }
 
   /**
@@ -117,20 +150,22 @@ export class SystemdUnitFile {
       definition instanceof SystemdServiceDefinition && definition.unitName === this.name &&
         definition.scope === this.scope &&
         (expectedSha256 === null ||
-          typeof expectedSha256 === 'string' && /^[a-f0-9]{64}$/.test(expectedSha256)) &&
-        // Installation admits, reloads and verifies through the user manager and recognizes its
-        // runtime mask path. Refusing here, before the busy latch and any directory or systemctl
-        // effect, keeps the local error code instead of a wrapped write_failed.
-        (this.scope === 'system' || this.runtimeDirectory !== undefined),
+          typeof expectedSha256 === 'string' && /^[a-f0-9]{64}$/.test(expectedSha256)),
       'invalid_options',
     );
+    // Installation admits, reloads and verifies through the user manager and recognizes its
+    // persistent and runtime mask paths, so it needs the whole user environment. Refusing here,
+    // before the busy latch and any directory or systemctl effect, keeps the local error code
+    // instead of a wrapped write_failed.
+    const maskDirectories = this.maskDirectories();
+    if (maskDirectories === null) throw new SystemdUnitFileError('invalid_options');
     requireValue(!this.busy, 'busy');
     this.busy = true;
     let temporary: string | undefined;
     let temporaryInfo: plugins.Stats | undefined;
     try {
       const before = await this.unit.inspect();
-      const beforeConfiguration = await this.admit(before);
+      const beforeConfiguration = await this.admit(before, maskDirectories);
       await this.directories(true);
       const parent = await plugins.fs.lstat(this.directory);
       const previous = await this.read(this.path);
@@ -163,7 +198,7 @@ export class SystemdUnitFile {
         requireValue(sameFile(parent, await plugins.fs.lstat(this.directory)), 'unsafe_path');
         const rechecked = await this.unit.inspect();
         requireValue(JSON.stringify(rechecked) === JSON.stringify(before), 'changed');
-        const recheckedConfiguration = await this.admit(rechecked);
+        const recheckedConfiguration = await this.admit(rechecked, maskDirectories);
         requireValue(
           recheckedConfiguration.fragmentPath === beforeConfiguration.fragmentPath,
           'changed',
@@ -214,7 +249,10 @@ export class SystemdUnitFile {
     }
   }
 
-  private async admit(state: ISystemdUnitState): Promise<ISystemdUnitConfigurationState> {
+  private async admit(
+    state: ISystemdUnitState,
+    maskDirectories: IMaskDirectories,
+  ): Promise<ISystemdUnitConfigurationState> {
     requireValue(
       quiet(state) && (masked(state) ||
         state.loadState === 'loaded' &&
@@ -223,14 +261,9 @@ export class SystemdUnitFile {
       'unsafe_unit',
     );
     const configuration = await this.unit.inspectConfiguration();
-    const maskPaths = this.scope === 'system'
-      ? [plugins.path.join(
-        state.unitFileState === 'masked-runtime' ? '/run/systemd/system' : '/etc/systemd/system',
-        this.name,
-      )]
-      : (state.unitFileState === 'masked-runtime'
-        ? [this.runtimeDirectory!, '/run'].map(root => plugins.path.join(root, 'systemd/user', this.name))
-        : [this.configDirectory!, '/etc'].map(root => plugins.path.join(root, 'systemd/user', this.name)));
+    const maskPaths = (state.unitFileState === 'masked-runtime'
+      ? maskDirectories.runtime : maskDirectories.persistent)
+      .map(directory => plugins.path.join(directory, this.name));
     requireValue(
       !configuration.needsReload && configuration.dropInPaths === '' &&
         (masked(state)

package/ts/systemd.definition.ts

@@ -6,6 +6,18 @@ export interface ISystemdServiceStartup {
   timeoutStartSeconds: number;
 }
 
+/**
+ * Ready when a process admitted by `notifyAccess` sends `READY=1`. `NotifyAccess=none` is not
+ * offered: systemd would discard every notification and the start could only time out.
+ */
+export interface ISystemdServiceNotifyStartup {
+  type: 'notify';
+  notifyAccess: 'main' | 'exec' | 'all';
+  timeoutStartSeconds: number;
+}
+
+export type TSystemdServiceStartup = ISystemdServiceStartup | ISystemdServiceNotifyStartup;
+
 /** Complete literal relations. System services always retain After=local-fs.target. */
 export interface ISystemdServiceDependencies {
   defaultDependencies: boolean;
@@ -24,16 +36,17 @@ export interface ISystemdServiceInstallTargets {
 
 /** Internal validated renderer; no systemd/process/filesystem effects. */
 export const renderServiceRelations = (options: {
-  startup?: ISystemdServiceStartup;
+  startup?: TSystemdServiceStartup;
   dependencies?: ISystemdServiceDependencies;
   install?: ISystemdServiceInstallTargets;
 }, unitName: string, restart: string, scope: 'system' | 'user', fail: () => never): {
   unit: string[]; service: string[]; install: string[];
 } => {
   const requireValue = (value: unknown): void => { if (!value) fail(); };
+  const plain = (value: unknown): void => requireValue(value !== null && typeof value === 'object'
+    && !plugins.util.types.isProxy(value) && Object.getPrototypeOf(value) === Object.prototype);
   const record = (value: unknown, keys: readonly string[]): void => {
-    requireValue(value !== null && typeof value === 'object' && !plugins.util.types.isProxy(value)
-      && Object.getPrototypeOf(value) === Object.prototype);
+    plain(value);
     const actual = Reflect.ownKeys(value as object);
     requireValue(actual.length === keys.length && actual.every(key => typeof key === 'string' && keys.includes(key)
       && Object.getOwnPropertyDescriptor(value, key)?.enumerable && 'value' in Object.getOwnPropertyDescriptor(value, key)!));
@@ -62,10 +75,19 @@ export const renderServiceRelations = (options: {
   };
   if (options.startup !== undefined) {
     const value = options.startup;
-    record(value, ['type', 'remainAfterExit', 'timeoutStartSeconds']);
-    requireValue(value.type === 'oneshot' && typeof value.remainAfterExit === 'boolean' && restart !== 'always'
-      && Number.isSafeInteger(value.timeoutStartSeconds) && value.timeoutStartSeconds >= 1 && value.timeoutStartSeconds <= 600);
-    result.service = ['Type=oneshot', `RemainAfterExit=${value.remainAfterExit ? 'yes' : 'no'}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    plain(value);
+    // Select the shape from the data descriptor so no accessor runs before record() refuses it.
+    const kind = Object.getOwnPropertyDescriptor(value, 'type');
+    record(value, kind !== undefined && 'value' in kind && kind.value === 'notify'
+      ? ['type', 'notifyAccess', 'timeoutStartSeconds'] : ['type', 'remainAfterExit', 'timeoutStartSeconds']);
+    requireValue(Number.isSafeInteger(value.timeoutStartSeconds) && value.timeoutStartSeconds >= 1 && value.timeoutStartSeconds <= 600);
+    if (value.type === 'notify') {
+      requireValue(['main', 'exec', 'all'].includes(value.notifyAccess));
+      result.service = ['Type=notify', `NotifyAccess=${value.notifyAccess}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    } else {
+      requireValue(value.type === 'oneshot' && typeof value.remainAfterExit === 'boolean' && restart !== 'always');
+      result.service = ['Type=oneshot', `RemainAfterExit=${value.remainAfterExit ? 'yes' : 'no'}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    }
   }
   if (options.dependencies !== undefined) {
     const value = options.dependencies;