@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/cli/service/instance/resolve.d.ts

@@ -1,6 +1,5 @@
 /**
- * resolveInstance — the single entry point every lifecycle command uses to
- * decide which installed service it's operating on.
+ * resolveInstance picks the installed service every lifecycle command acts on.
  *
  * Priority:
  *   1. --instance-dir <path>       → read manifest at <path>
@@ -8,14 +7,9 @@
  *   3. CWD manifest                → read ./.kici-<component>.json
  *   4. otherwise                   → refuse with a candidate list (throws)
  *
- * listInstances reconciles the on-disk index (cache) with the drivers'
- * native scans (source of truth). The reconciled result is rewritten back to
- * the index to self-heal stale entries.
- *
- * Discovery is platform-plural and operation is platform-singular. A host can
- * hold both a systemd install and a compose install, so finding an instance
- * scans every candidate driver; acting on the one that was found uses the
- * single driver its manifest names.
+ * Discovery is platform-plural and operation is platform-singular: a host can
+ * hold both a systemd and a compose install, so finding an instance scans every
+ * candidate driver, and acting on it uses the single driver its manifest names.
  */
 import type { DiscoveredInstance, ServiceManager, ServicePlatform } from '../types.js';
 import type { Component, ResolveOptions, ResolvedInstance } from './types.js';
@@ -25,13 +19,10 @@ export interface ListedInstance extends DiscoveredInstance {
     source: 'index' | 'scan' | 'index+scan';
 }
 /**
- * The drivers that can plausibly hold an install on this host.
- *
- * `--platform` forces one driver, so an operator keeps an escape hatch to
- * today's exact single-driver behaviour on every path. Otherwise the host's own
- * init system is joined by compose, which runs on any host with a container
- * runtime — a compose install on a systemd box is the case the single-driver
- * scan could not see.
+ * The drivers that can plausibly hold an install on this host. `--platform`
+ * forces one driver, the operator's single-driver escape hatch. Otherwise the
+ * host's init system is joined by compose, which runs on any host with a
+ * container runtime, so a compose install on a systemd box is found.
  */
 export declare function candidatePlatforms(override?: ServicePlatform): ServicePlatform[];
 export interface ListInstancesArgs {
@@ -39,37 +30,34 @@ export interface ListInstancesArgs {
     isUserLevel: boolean;
     kiciRoot: string;
     /**
-     * The drivers to scan. Omit to scan every candidate driver for this host.
-     * Each driver is authoritative only over its own platform's index rows.
+     * Omit to scan every candidate driver for this host. Each driver is
+     * authoritative only over its own platform's index rows.
      */
     managers?: ServiceManager[];
 }
 /**
  * Reconcile <kiciRoot>/instances.json with the drivers' native scans, then
- * rewrite the index so it mirrors the scanned instances that have a known
- * instanceDir. Two self-heal directions happen here:
+ * rewrite the index to mirror the scanned instances with a known instanceDir:
  *
  *   - backward: drop index entries whose unit no longer exists.
  *   - forward: adopt an instanceDir a driver recovered from the unit marker
- *     when the index entry is missing or carries no dir — so a lost or emptied
- *     index rebuilds itself from the init system on the next read.
+ *     when the index entry is missing or has no dir, so a lost or emptied
+ *     index rebuilds itself on the next read.
  *
- * The init system is therefore the source of truth for the name→folder mapping
- * (via the X-KiCI-InstanceDir / KiCIInstanceDir / dev.kici.instance-dir / [KiCI-DIR]
- * markers), and the index is a pure cache. Returns the merged list filtered to
- * the requested component + isUserLevel.
+ * The init system is the source of truth for the name→folder mapping (via the
+ * X-KiCI-InstanceDir / KiCIInstanceDir / dev.kici.instance-dir / [KiCI-DIR]
+ * markers); the index is a pure cache. Returns the list filtered to the
+ * requested component + isUserLevel.
  *
- * The rewrite is scoped to the platforms that were actually scanned. A driver
- * speaks for its own platform's rows and for no others, so a systemd scan
- * cannot delete a compose install's row, and a driver that could not reach its
- * registry deletes nothing at all.
+ * The rewrite is scoped to the scanned platforms: a systemd scan cannot delete
+ * a compose install's row, and a driver that could not reach its registry
+ * deletes nothing.
  */
 export declare function listInstances(args: ListInstancesArgs): Promise<ListedInstance[]>;
 /**
- * Thrown by resolveInstance when `--name <n>` is given but no installed
- * instance matches. Lifecycle commands catch this to treat stop/uninstall of
- * a never-installed instance as an idempotent no-op. Distinct from the
- * ambiguous-refusal and missing-manifest errors, which stay hard failures.
+ * Thrown when `--name <n>` matches no installed instance. Lifecycle commands
+ * catch it so stop/uninstall of a never-installed instance is an idempotent
+ * no-op; the ambiguous-refusal and missing-manifest errors stay hard failures.
  */
 export declare class InstanceNotFoundError extends Error {
     readonly component: Component;
@@ -81,45 +69,25 @@ export interface ResolveArgs {
     opts: ResolveOptions;
     cwd: string;
     kiciRoot: string;
-    /**
-     * Every driver discovery should scan. Omit to scan every candidate driver
-     * for this host.
-     */
+    /** Omit to scan every candidate driver for this host. */
     managers?: ServiceManager[];
     /**
-     * Privilege scope to resolve against. Must match the caller's resolved
-     * --system / --user-level decision so candidate lists and name lookups see
-     * the correct set of installed instances.
+     * Must match the caller's resolved --system / --user-level decision so
+     * candidate lists and name lookups see the right installed instances.
      */
     isUserLevel: boolean;
 }
-/**
- * Resolve the target instance for the current lifecycle invocation.
- * Throws with a refusal/candidate-listing error when ambiguous.
- */
+/** Throws a refusal listing the candidates when ambiguous. */
 export declare function resolveInstance(args: ResolveArgs): Promise<ResolvedInstance>;
-/**
- * Format the refusal message and candidate table.
- *
- * When candidates is empty, returns the "no instances installed" guidance.
- * When candidates exist, lists them with their instanceDir (or "(no manifest)").
- */
 export declare function formatRefusal(component: Component, candidates: ListedInstance[]): string;
-/** What {@link resolveInstanceTarget} is asked. */
 export interface ResolveTargetArgs {
     component: Component;
     opts: ResolveOptions;
     cwd: string;
     kiciRoot: string;
-    /**
-     * Privilege scope to resolve against. Must match the caller's resolved
-     * --system / --user-level decision.
-     */
+    /** Must match the caller's resolved --system / --user-level decision. */
     isUserLevel: boolean;
-    /**
-     * The `--platform` flag. When set it forces the driver for both discovery and
-     * operation, which is the operator's escape hatch to a single-driver run.
-     */
+    /** `--platform`: forces the driver for both discovery and operation. */
     platformOverride?: ServicePlatform;
     /** Driver factory. Defaults to the service barrel's createServiceManager. */
     createManager?: (platform: ServicePlatform) => Promise<ServiceManager>;
@@ -132,13 +100,9 @@ export interface ResolvedTarget {
     platform: ServicePlatform;
 }
 /**
- * Resolve the target instance and the driver that manages it.
- *
- * The question a lifecycle command asks is about the install, not the host: a
- * compose install stays a compose install on a systemd box. So discovery scans
- * every candidate driver, and the manifest that discovery produced then names
- * the single driver the command operates through. The two need not be the same
- * object, and only the second has to be right.
+ * Resolve the target instance and its driver. A compose install stays a compose
+ * install on a systemd box, so discovery scans every candidate driver and the
+ * found manifest names the single driver the command operates through.
  */
 export declare function resolveInstanceTarget(args: ResolveTargetArgs): Promise<ResolvedTarget>;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/cli/service/instance/types.d.ts

@@ -1,25 +1,16 @@
 /**
- * Instance types — the shared shape of a folder-anchored service instance,
- * its on-disk manifest, the reconciled cache index, and the per-driver
- * discovery result.
- *
- * A KiCI service instance is identified by (component, name, instanceDir).
- * The deploy folder holds the manifest; the index at <kiciRoot>/instances.json
- * is a reconciled cache of all installed instances on the host.
+ * A service instance is identified by (component, name, instanceDir). The
+ * deploy folder holds the manifest; `<kiciRoot>/instances.json` is a
+ * reconciled cache of the host's installed instances.
  */
 import type { ServicePlatform } from '../types.js';
-/** The two KiCI components managed by `kici-admin` service commands. */
 export type Component = 'orchestrator' | 'agent';
-/** Enumerable list — used for iteration and discovery. */
 export declare const COMPONENTS: readonly Component[];
-/** Narrow an arbitrary string to a Component. */
 export declare function isComponent(value: string): value is Component;
 /**
- * The manifest written by `install` into the deploy folder
- * (`./.kici-orchestrator.json` or `./.kici-agent.json`).
- *
- * Holds everything `resolveInstance` needs to reconstruct a ServiceConfig
- * without re-deriving paths.
+ * The `./.kici-<component>.json` that `install` writes into the deploy folder:
+ * everything `resolveInstance` needs to rebuild a ServiceConfig without
+ * re-deriving paths.
  */
 export interface InstanceManifest {
     component: Component;
@@ -33,18 +24,11 @@ export interface InstanceManifest {
     createdAt: string;
     kiciVersion: string;
     /**
-     * Installed version → the last applied migration at the moment that version
-     * was running.
-     *
-     * A rollback flips a symlink, and the previous release's static migration
-     * provider does not carry the newer migrations' names — so Kysely refuses to
-     * start against a ledger that records them, and the documented recovery
-     * produces a second outage. This map is what lets the switch check whether
-     * the database is ahead of the version it is about to activate.
-     *
-     * Merged, never replaced, at every version change. Absent on every instance
-     * installed before this field existed, which the guard treats as "unknown"
-     * and warns about rather than refusing.
+     * Installed version → the last migration applied while it ran. A version
+     * switch checks it to refuse activating a version the database is ahead of
+     * (see `schemaGuardVerdict`). Merged, never replaced, at every version
+     * change; absent on older installs, which the guard warns about rather than
+     * refuses.
      */
     migrationHeads?: Record<string, string>;
 }
@@ -56,12 +40,11 @@ export interface IndexEntry {
     isUserLevel: boolean;
     instanceDir: string;
 }
-/** CLI options that influence target resolution. */
 export interface ResolveOptions {
     instanceDir?: string;
     name?: string;
 }
-/** Fully-resolved target — what `resolveInstance` returns. */
+/** What `resolveInstance` returns. */
 export interface ResolvedInstance {
     manifest: InstanceManifest;
     manifestPath: string;

package/dist/cli/service/launchd.d.ts

@@ -1,101 +1,70 @@
 /**
- * launchd service manager implementation.
- *
- * Generates plist files and manages service lifecycle via launchctl.
- * Supports both system-level (/Library/LaunchDaemons/) and
- * user-level (~/Library/LaunchAgents/) agents.
+ * launchd service manager: writes plists and drives launchctl, for system-level
+ * (/Library/LaunchDaemons/) and user-level (~/Library/LaunchAgents/) jobs.
  */
 import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
 /**
- * `dev.kici.my-orch` -> `my-orch`. Returns the input unchanged when it carries
- * no known prefix, so a hand-written plist is still discoverable under
- * whatever label it uses.
+ * `dev.kici.my-orch` -> `my-orch`. A label with no known prefix returns
+ * unchanged, so a hand-written plist stays discoverable.
  */
 export declare function stripLabelPrefix(label: string): string;
 export declare class LaunchdServiceManager implements ServiceManager {
     readonly platform: 'launchd';
-    /** Build the launchd label for a service. */
     private label;
-    /** Resolve the log directory based on service level. */
     private logDir;
     /** The directory launchd loads this service level's plists from. */
     private plistDir;
     /** The job `install` writes: `dev.kici.<name>`. */
     private installJob;
     /**
-     * An installed job for this name under another label: a `com.kici.<name>`
-     * plist, or a plist named after the service itself — each one `list()`
-     * reports as this instance. Only a plist that carries the KiCI component
-     * marker counts, and the job is addressed by the Label the plist declares.
+     * A job for this name under another label (`com.kici.<name>`, or a plist named
+     * after the service), which `list()` reports as this instance. Only a plist
+     * with the KiCI component marker counts; the job is addressed by its declared Label.
      */
     private otherLabelJob;
     /**
-     * The job a lifecycle command acts on: the `dev.kici.<name>` plist when it
-     * is installed, otherwise a job this name was installed under with another
-     * label, so every instance `list()` reports can be stopped, started and
-     * removed. With neither installed, the `dev.kici.<name>` job.
+     * The job a lifecycle command acts on: the installed `dev.kici.<name>` plist,
+     * else an other-label job, so every instance `list()` reports stays
+     * manageable. With neither installed, the `dev.kici.<name>` job.
      */
     private resolveJob;
-    /** Parse a .env file into key-value pairs. */
     private parseEnvFile;
-    /** Escape XML special characters. */
     private escapeXml;
-    /** Inverse of {@link escapeXml} — decode the entities back to literals. */
+    /** Inverse of {@link escapeXml}. */
     private unescapeXml;
-    /**
-     * Generate a launchd plist XML string from a service config.
-     * Visible for testing.
-     */
+    /** Visible for testing. */
     generatePlist(config: ServiceConfig): string;
     /**
-     * Resolve the launchctl domain string for a service config.
-     *
-     *   - User-level (LaunchAgent at `~/Library/LaunchAgents/…`) → `gui/<uid>`
-     *   - System-level (LaunchDaemon at `/Library/LaunchDaemons/…`) → `system`
-     *
-     * The legacy `launchctl load` / `unload` verbs implicitly inferred the
-     * domain from the plist's filesystem location, but they fail silently on
-     * headless macOS hosts where no GUI session exists (the `gui/<uid>` domain
-     * is not available without a console login). The modern `bootstrap` /
-     * `bootout` / `kickstart` / `print` verbs take the domain explicitly, so a
-     * system-level LaunchDaemon loads regardless of whether anyone is logged
-     * in at the console — exactly what we need for headless deploy targets.
+     * `gui/<uid>` for a user-level LaunchAgent, `system` for a LaunchDaemon. The
+     * legacy `load`/`unload` verbs infer the domain from the plist location and
+     * fail silently on a headless host (no `gui/<uid>` domain without a console
+     * login); the `bootstrap`/`bootout`/`kickstart`/`print` verbs take it
+     * explicitly, so a system daemon loads with nobody logged in.
      */
     private domain;
     /** `<domain>/<label>` — the target string for bootout/kickstart/print. */
     private domainTarget;
     /**
-     * `launchctl print <domain>/<label>`: the job's description while it is
-     * loaded, or null when launchd reports it not loaded. Unlike `launchctl
-     * list`, which lists only the caller's own domain, this reads a system
-     * daemon without root. Any other failure throws, so a job that could not be
-     * inspected is never mistaken for a stopped one.
+     * `launchctl print`: the job description, or null when not loaded. Unlike
+     * `launchctl list` (own domain only), it reads a system daemon without root.
+     * Any other failure throws, so an uninspectable job never reads as stopped.
      */
     private printJob;
-    /** Is the job currently loaded in its target domain? */
     private isLoaded;
     install(config: ServiceConfig): Promise<void>;
     /**
-     * Poll until the job is no longer loaded in its target domain, or the
-     * deadline elapses. Resolves true once the job has left the domain,
-     * false on timeout. `launchctl bootout` is asynchronous — it returns before
-     * launchd has finished releasing the job — so a bootstrap issued
-     * immediately afterward races the teardown and fails with EIO. Waiting for
-     * the unload to complete closes that race for the common case; the residual
-     * window is covered by bootstrapWithRetry.
+     * True once the job has left its domain, false on timeout. `bootout` returns
+     * before launchd releases the job, so an immediate bootstrap fails with EIO;
+     * this closes the common case and bootstrapWithRetry the residual window.
      */
     private waitUntilUnloaded;
     /**
-     * Bootstrap into the target domain, retrying on the transient EIO
-     * ("5: Input/output error") launchd returns when a just-removed service has
-     * not finished tearing down. A genuine, non-transient failure (bad plist,
-     * permission denied) is re-thrown on the first attempt.
-     *
-     * launchd answers a bootstrap of a job that is already loaded with the same
-     * EIO. With `replaceLoaded` (install, which just wrote a new plist) such a
-     * job is booted out before the next try. Without it (start), a job that
-     * another caller loaded meanwhile is the outcome start wanted: RunAtLoad has
-     * started it, so the call succeeds and leaves it running.
+     * Bootstrap, retrying on the transient EIO launchd returns while a
+     * just-removed service tears down; a non-transient failure (bad plist,
+     * permission denied) throws at once. An already-loaded job gets the same
+     * EIO: with `replaceLoaded` (install) it is booted out before the next try;
+     * without it (start), a job another caller loaded meanwhile is the wanted
+     * outcome (RunAtLoad started it), so the call succeeds.
      */
     private bootstrapWithRetry;
     uninstall(config: ServiceConfig): Promise<void>;

package/dist/cli/service/platform-detect.d.ts

@@ -1,84 +1,29 @@
-/**
- * Platform detection and directory resolution for KiCI service management.
- *
- * Detects the init system (systemd, launchd, Windows Services, or Compose fallback)
- * and resolves platform-appropriate directories for config, logs, and cache.
- */
+/** Init-system detection and the per-platform config, log and cache directories. */
 import type { ServicePlatform } from './types.js';
 /**
- * Detect the service management platform.
+ * Linux without systemd falls back to Docker/Podman Compose.
  *
- * Auto-detection order:
- * - win32 -> 'windows'
- * - darwin -> 'launchd'
- * - linux with /run/systemd/system or /sys/fs/cgroup/systemd -> 'systemd'
- * - linux without systemd -> 'compose' (Docker/Podman Compose fallback)
- *
- * @param override - Force a specific platform (e.g., from --platform flag)
+ * @param override - Forces a platform (the --platform flag).
  */
 export declare function detectPlatform(override?: ServicePlatform): ServicePlatform;
-/**
- * Check if the current process has root/admin privileges.
- *
- * - Unix: UID === 0
- * - Windows: attempts `net session` (succeeds only as admin)
- */
+/** Root on Unix (UID 0) or admin on Windows. */
 export declare function isRoot(): boolean;
 /**
- * Name-agnostic KiCI config root — the directory that contains every
- * per-instance config subdir for this privilege level.
- *
- * Paths follow platform conventions:
- * - System Linux/macOS: /etc/kici/
- * - User Linux: ~/.config/kici/
- * - User macOS: ~/Library/Application Support/kici/
- * - System Windows: C:\ProgramData\kici\
- * - User Windows: %LOCALAPPDATA%\kici\
- *
- * Used by the instance index (`<kiciRoot>/instances.json`) which lives
- * outside any per-instance subdir, and as the base for {@link getConfigDir}.
+ * The config root holding every per-instance subdir for this privilege level,
+ * plus the instance index (`<kiciRoot>/instances.json`).
  *
- * `KICI_CONFIG_ROOT` overrides the platform default for both privilege scopes.
- * It exists so a test harness (or a sandboxed run) can point the instance index
- * at an isolated directory instead of sharing the host's `~/.config/kici/` —
- * which otherwise lets concurrent installs clobber each other's index.
+ * `KICI_CONFIG_ROOT` overrides it for both scopes, so a test harness or
+ * sandboxed run gets an isolated index; a shared `~/.config/kici/` lets
+ * concurrent installs clobber each other's index.
  */
 export declare function kiciConfigRoot(isUserLevel: boolean): string;
 /**
- * Get the configuration directory for a specific KiCI service instance.
- *
- * Returns `<kiciConfigRoot>/<serviceName>/`. The name-scoped subdir is the
- * folder-anchored home for everything belonging to one installed instance
- * (env file, generated unit references, future per-instance state).
- *
- * Examples:
- * - System Linux: /etc/kici/<name>/
- * - User Linux: ~/.config/kici/<name>/
- * - User macOS: ~/Library/Application Support/kici/<name>/
- * - System Windows: C:\ProgramData\kici\<name>\
- * - User Windows: %LOCALAPPDATA%\kici\<name>\
+ * `<kiciConfigRoot>/<serviceName>/`: the home of everything one instance owns
+ * (env file, unit references).
  */
 export declare function getConfigDir(serviceName: string, isUserLevel: boolean): string;
-/**
- * Get the log directory for a specific KiCI service instance.
- *
- * The per-platform layout matches the existing matrix; the service name is
- * injected as the per-instance segment so each instance has its own log dir:
- * - System Linux/macOS: /var/log/kici/<name>/
- * - User Linux: ~/.local/share/kici/<name>/logs/
- * - User macOS: ~/Library/Logs/kici/<name>/
- * - Windows: C:\ProgramData\kici\<name>\logs\
- */
+/** One log directory per instance, named by `serviceName`. */
 export declare function getLogDir(serviceName: string, isUserLevel: boolean): string;
-/**
- * Get the cache directory for lazy dependency downloads.
- *
- * Resolution order:
- * 1. $XDG_CACHE_HOME/kici/deps/ (if set)
- * 2. Platform default:
- *    - Linux: ~/.cache/kici/deps/
- *    - macOS: ~/Library/Caches/kici/deps/
- *    - Windows: %LOCALAPPDATA%\kici\deps\
- */
+/** The lazy-dependency download cache; `$XDG_CACHE_HOME` wins on every platform. */
 export declare function getCacheDir(): string;
 //# sourceMappingURL=platform-detect.d.ts.map

package/dist/cli/service/privilege.d.ts

@@ -1,41 +1,28 @@
 /**
- * Resolve the system-vs-user privilege level for a service lifecycle command.
+ * Resolve system- vs user-level for the service lifecycle verbs and `db`, so
+ * they agree on the target (`systemctl --user` / LaunchAgents vs `systemctl` /
+ * LaunchDaemons). No flag auto-detects by UID: non-root is user-level.
  *
- * The service lifecycle verbs (install, start, stop, restart, uninstall,
- * status, logs) and `db` need to agree on whether they're operating against
- * the user-level service (~/Library/LaunchAgents, `systemctl --user`) or the
- * system-level one (/Library/LaunchDaemons, `systemctl`). Default behavior
- * (no flag) is to auto-detect based on UID — non-root → user-level, root →
- * system-level.
- *
- * Explicit `--system` / `--user-level` flags override the auto-detect.
- * They're mutually exclusive: passing both throws. Passing `--system`
- * without root throws with a `sudo` command the operator can paste: it names
- * the node binary and CLI script the refused process was actually running,
- * because `sudo` resets PATH to its `secure_path` and cannot find a node that
- * a version manager (nvm, mise, fnm, volta) put on the operator's PATH.
+ * `--system` and `--user-level` are mutually exclusive. `--system` without
+ * root throws with a pasteable `sudo` command naming the running node binary
+ * and CLI script, because `sudo` resets PATH to `secure_path` and loses a
+ * version manager's node (nvm, mise, fnm, volta).
  */
 export interface PrivilegeOpts {
-    /** Force system-level install/lifecycle. Requires root. */
+    /** Requires root. */
     system?: boolean;
-    /** Force user-level install/lifecycle. */
     userLevel?: boolean;
 }
-/** The slice of `process` the re-run hint is built from, injectable for tests. */
+/** The slice of `process` the re-run hint uses, injectable for tests. */
 export interface RerunContext {
-    /** `process.execPath` — the node binary actually running. */
     execPath: string;
-    /** `process.argv` — `[node, script, ...args]`. */
+    /** `[node, script, ...args]`. */
     argv: readonly string[];
-    /** `process.platform`. */
     platform: NodeJS.Platform;
 }
 /**
- * The lines appended to the `--system` refusal: a command that re-runs the
- * refused invocation as root, built from the running process rather than from
- * a literal `kici-admin`, which `sudo` cannot find when node comes from a
- * version manager. On Windows there is no `sudo`; the hint names an elevated
- * shell instead.
+ * A root re-run command built from the running process, not a literal
+ * `kici-admin`; on Windows, an elevated shell instead.
  */
 export declare function systemRerunHint(ctx: RerunContext): string;
 export declare function resolveUserLevel(opts: PrivilegeOpts): boolean;

package/dist/cli/service/shutdown-grace.d.ts

@@ -1,35 +1,26 @@
-/**
- * How long an init system waits for a KiCI service to shut down.
- */
 import type { ServiceConfig } from './types.js';
 /**
  * Seconds an init system must wait after SIGTERM before it SIGKILLs the service.
  *
- * The runtime defaults are shorter than either component's own graceful-shutdown
- * budget: Compose waits 10s, launchd's default ExitTimeOut is 5s, and shawl's
- * default `--stop-timeout` on Windows is 3s. A teardown that
- * takes longer is killed partway through: the orchestrator never broadcasts
- * `peer.leaving` and never closes its agent sockets, and the agent never
- * finishes draining. That window is reached exactly when it matters most — the
- * orchestrator's scaler stops each managed agent with its own grace, so an
- * orchestrator with agents in flight routinely needs more than 10s.
+ * Runtime defaults (Compose 10s, launchd ExitTimeOut 5s, shawl `--stop-timeout`
+ * 3s) are shorter than either component's graceful shutdown, so the orchestrator
+ * would never broadcast `peer.leaving` or close its agent sockets, and the agent
+ * would never finish draining. An orchestrator stopping its scaler's agents, each
+ * with its own grace, routinely needs more than 10s.
  *
- * Each value is its component's force-exit budget plus headroom, so the
- * process always reaches its own timer first and the runtime's kill stays the
- * last resort it is meant to be:
+ * Each value is the component's force-exit budget plus headroom, so its own
+ * timer always fires before the runtime's kill:
  * - orchestrator: 30s (`setupGracefulShutdown` default) plus up to 2s of log
  *   file flush -> 45s
  * - agent: 10s plus a ~1s abort delay in its `onForceExit` -> 20s
  *
- * An unrecognised component gets the larger value: over-waiting costs a few
- * seconds on shutdown, under-waiting corrupts it.
+ * An unrecognised component gets the larger value: over-waiting costs seconds,
+ * under-waiting corrupts the shutdown.
  */
 export declare function shutdownGraceSeconds(config: ServiceConfig): number;
 /**
- * Seconds a `stop` waits for the init system to report the service stopped.
- *
- * The init system kills the process once its grace elapses, so a service still
- * running after the grace plus this margin is hung, not slow.
+ * Seconds a `stop` waits for the service to report stopped. The init system
+ * kills it once its grace elapses, so one still running after this is hung.
  */
 export declare function stopWaitSeconds(config: ServiceConfig): number;
 //# sourceMappingURL=shutdown-grace.d.ts.map

package/dist/cli/service/systemd.d.ts

@@ -1,34 +1,21 @@
 /**
- * systemd service manager implementation.
- *
- * Generates unit files and manages service lifecycle via systemctl,
- * journalctl, and loginctl commands. Supports both system-level
- * (/etc/systemd/system/) and user-level (~/.config/systemd/user/) services.
+ * systemd service manager: system-level (/etc/systemd/system/) and user-level
+ * (~/.config/systemd/user/) units, driven through systemctl, journalctl and
+ * loginctl.
  */
 import type { DiscoveredInstance, ServiceConfig, ServiceManager, ServiceStatus, LogOptions, LaunchSpec } from './types.js';
 /**
- * Check whether linger is already enabled for a user.
- *
- * Uses `loginctl show-user <user>` which is readable by any user. Returns
- * true if the user's `Linger` property reads `yes`. Returns false on any
- * parse failure, missing binary, or unknown user — the caller is expected
- * to attempt `enable-linger` in that case.
- *
- * Exported (package-private) for testing.
+ * Whether linger is enabled, via `loginctl show-user` (readable by any user).
+ * False on any failure (parse, missing binary, unknown user), in which case
+ * the caller attempts `enable-linger`. Exported for testing.
  */
 export declare function isLingerEnabled(user: string): boolean;
 export declare class SystemdServiceManager implements ServiceManager {
     readonly platform: 'systemd';
-    /**
-     * Generate a systemd unit file from a service config.
-     * Visible for testing.
-     */
+    /** Visible for testing. */
     generateUnitFile(config: ServiceConfig): string;
-    /** Resolve the unit file path based on service level. */
     private unitFilePath;
-    /** Build systemctl command args, inserting --user for user-level services. */
     private systemctlArgs;
-    /** Run a systemctl command. */
     private systemctl;
     install(config: ServiceConfig): Promise<void>;
     uninstall(config: ServiceConfig): Promise<void>;