@kici-dev/orchestrator 0.11.0 → 0.13.0

package/dist/cli/commands/orchestrator-service/status.d.ts

@@ -1,9 +1,9 @@
 /**
  * `kici-admin orchestrator status` command.
  *
- * Shows OS-level service status (state, PID, uptime) and queries
- * the running orchestrator's health API for KiCI-specific info
- * (mode, DB connectivity, agents, jobs, scaler).
+ * Shows OS-level service status (state, PID, uptime) and queries the
+ * running orchestrator's `/health` and `/ready` endpoints for its version,
+ * build fingerprint, uptime and readiness (database reachable, boot finished).
  *
  * Target resolution goes through resolveInstanceTarget — the same priority chain
  * every lifecycle command uses (--instance-dir > --name > CWD manifest >
@@ -11,6 +11,13 @@
  */
 import type { Command } from 'commander';
 import { type ServicePlatform } from '../../service/index.js';
+/**
+ * How long to wait for `/ready`. Its database check waits up to the pool's
+ * acquire timeout before it reports `database: false`, so the wait covers that
+ * timeout plus a margin. An acquire timeout of 0 lets the pool wait without
+ * limit; the default then bounds the wait.
+ */
+export declare function readinessTimeoutMs(envContent: string): number;
 /**
  * The config files this install owns, for an operator who wants to inspect
  * them. Derived from the instance manifest and the env file on disk, not from

package/dist/cli/commands/queue.d.ts

@@ -7,8 +7,7 @@
  * READ-ONLY — mutations live in `maintenance.ts` (queue clear) instead.
  * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
  *
- * supersedes the original `cache list|show` framing — the E2E call
- * sites were actually querying dispatch_queue, not a dedup cache.
+ * The rows come from dispatch_queue, not a dedup cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/runs.d.ts

@@ -2,9 +2,8 @@
  * Execution run commands for kici-admin.
  *
  * Provides operator-facing read access to execution runs and their
- * sub-resources via the orchestrator's admin HTTP API. This is the
- * dogfooded replacement for hand-rolled curl commands when inspecting
- * run state.
+ * sub-resources via the orchestrator's admin HTTP API. Use it instead of
+ * hand-rolled curl commands when inspecting run state.
  *
  *   runs list                          List execution runs (table or JSON)
  *   runs show <runId>                  Show run detail with jobs and steps

package/dist/cli/commands/service-health.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reads a locally installed KiCI service's health endpoints and formats what
+ * they report. `kici-admin orchestrator status` and `kici-admin agent status`
+ * both render through here, so the two sections agree on layout and on how a
+ * missing field is handled.
+ */
+import { type BuildFingerprint, type LivenessBase } from '@kici-dev/shared';
+/** A label and its value: one line of a status section. */
+export type StatusRow = readonly [label: string, value: string];
+/**
+ * Read the env file, or empty content when it is missing or unreadable. A file
+ * this account may not read is reported: the port and address the caller then
+ * falls back to may not be the ones the service uses. On Windows only
+ * LocalSystem and Administrators can read a service's env file.
+ */
+export declare function readEnvContent(envFilePath: string, warn?: (line: string) => void): string;
+/** Where a service installed on this host answers HTTP. */
+export interface LocalEndpoint {
+    host: string;
+    port: number;
+    /** The prefix the service's routes are mounted under; empty when they sit at `/`. */
+    pathPrefix: string;
+}
+/**
+ * Where the service answers, read from its env file: `KICI_PORT` (or
+ * `defaultPort`), `KICI_HOST` and `KICI_BASE_PATH`. A service bound to every
+ * interface is reached on `localhost`; one bound to a single address is reached
+ * there. The agent reads none of the last two, so its env file never sets them.
+ */
+export declare function readLocalEndpoint(envContent: string, defaultPort: number): LocalEndpoint;
+/** The URL of `pathname` on `endpoint`, with an IPv6 host bracketed. */
+export declare function localUrl(endpoint: LocalEndpoint, pathname: string): string;
+/**
+ * GET a JSON body from a service on this host. `acceptStatuses` names the
+ * non-2xx codes whose body is still an answer: `/ready` returns its checks
+ * with a 503 when one fails. Returns null when nothing answers in time.
+ */
+export declare function fetchLocalJson<T>(endpoint: LocalEndpoint, pathname: string, opts?: {
+    acceptStatuses?: readonly number[];
+    timeoutMs?: number;
+}): Promise<T | null>;
+/**
+ * A `/health` body with its deprecated `buildCommit` replaced by its version.
+ * A service older than this CLI reports a commit ID from KiCI's private
+ * repository there, which a reader cannot resolve; `--json` keeps the key, a
+ * string as before, and carries the release version in it. A body that reports
+ * no `buildCommit` comes back unchanged.
+ */
+export declare function hideBuildCommit<T extends {
+    version?: string;
+    buildCommit?: string;
+}>(health: T): T;
+/**
+ * Rows for the build fingerprint and process uptime of a `/health` body. A
+ * field the body lacks is skipped, so a service older than this CLI renders
+ * the fields it does report. The version line never shows `buildCommit`
+ * (see {@link hideBuildCommit}).
+ */
+export declare function buildInfoRows(health: Partial<LivenessBase & BuildFingerprint & {
+    buildDate: string;
+}>): StatusRow[];
+/**
+ * A status section: a blank separator line, the heading, then one line per
+ * row with each value starting at `valueColumn`. A body with no field this CLI
+ * recognises still gets a line saying so, so the heading never stands alone.
+ */
+export declare function formatHealthSection(heading: string, rows: readonly StatusRow[], valueColumn: number): string[];
+//# sourceMappingURL=service-health.d.ts.map

package/dist/cli/commands/shared/env-file-mode.d.ts

@@ -9,8 +9,9 @@
  * `cluster/peer-credentials.ts`.
  *
  * The guarantee is POSIX-only. Node maps a mode onto Windows by toggling the
- * read-only attribute and changes no ACL, so a Windows install must restrict
- * the file itself.
+ * read-only attribute and changes no ACL, so a Windows install restricts the
+ * folder that holds the file instead (`restrictEnvFileAccess`,
+ * `cli/service/windows-acl.ts`).
  */
 export declare const ENV_FILE_MODE = 384;
 //# sourceMappingURL=env-file-mode.d.ts.map

package/dist/cli/commands/shared/upgrade-safety.d.ts

@@ -19,6 +19,11 @@ export declare function waitForQuiesce(poll: () => Promise<DrainSnapshot>, opts:
     quiesced: boolean;
     jobsRunning: number;
 }>;
+/**
+ * What a version switch prints when it cannot read the live migration ledger,
+ * so it could not compare the schema to the recorded head.
+ */
+export declare const SCHEMA_NOT_CHECKED = "The running service could not be reached, so the schema was not checked.";
 /** One entry of `GET /api/v1/admin/db/migrate/status`. */
 export interface MigrationStatusRow {
     name: string;
@@ -47,11 +52,12 @@ export type SchemaGuardVerdict = {
  * Decide whether the version pointer may move.
  *
  * Three outcomes, and the middle one is the compatibility shim: an instance
- * installed before `migrationHeads` existed has no recorded head, and refusing
- * there would break the documented `--rollback` on exactly the installs that
- * predate the guard. So an unknown head warns loudly and falls through to the
- * existing confirmation prompt; the map is populated at the next version
- * change, arming the guard one upgrade later.
+ * installed before `migrationHeads` existed, or one whose upgrade away from the
+ * target ran without admin access, has no recorded head, and refusing there
+ * would break the documented `--rollback` on exactly those installs. So an
+ * unknown head warns loudly and falls through to the existing confirmation
+ * prompt; the map is populated at the next version change with admin access,
+ * arming the guard one upgrade later.
  */
 export declare function schemaGuardVerdict(input: {
     targetVersion: string;

package/dist/cli/commands/shared/versioned-upgrade.d.ts

@@ -11,9 +11,9 @@ import { type NpmInstallTarget, type ResolvedInstance, type ServiceManager, type
 import type { LaunchSpec, ServiceConfig } from '../../service/types.js';
 import { type MigrationStatusRow } from './upgrade-safety.js';
 /** Component types that can be upgraded. */
-type UpgradeComponent = 'orchestrator' | 'agent';
+export type UpgradeComponent = 'orchestrator' | 'agent';
 /** Options for the versioned upgrade command. */
-interface VersionedUpgradeOptions {
+export interface VersionedUpgradeOptions {
     platform?: ServicePlatform;
     /**
      * Service name. No default — targeting flows through {@link resolveInstanceTarget}
@@ -130,8 +130,8 @@ export declare function resolveUpgradeTarget(args: {
  * Install base for a KiCI component instance.
  *
  * Name-scoped so that two instances of the same component (e.g. an org's
- * dogfood orchestrator and an E2E test orchestrator) own independent
- * versioned trees and symlinks. Per-platform bases:
+ * production orchestrator and a test orchestrator on the same host) own
+ * independent versioned trees and symlinks. Per-platform bases:
  *   - systemd / compose: /opt/kici/<name>/
  *   - launchd:           /usr/local/kici/<name>/
  *   - windows:           C:\Program Files\KiCI\<name>\
@@ -171,6 +171,55 @@ export declare function checkPickFlagConflicts(opts: {
     rollback?: boolean;
     cleanup?: boolean;
 }): string | null;
+/**
+ * Stop the service, register it again on Windows, then start it: the restart
+ * every npm-source upgrade ends with.
+ *
+ * `npm install -g` replaces the package in place, so the launch command the
+ * service runs (`spec`, read back from its registration) stays valid. On
+ * Windows the registration around that command (the service wrapper's
+ * arguments, the description, the recovery settings) is whatever the CLI that
+ * installed it wrote, so `install` writes the current one, as the archive
+ * upgrade does. A launch command that names a file that does not exist was
+ * read back wrong, so it is not registered: the service restarts as it was,
+ * with a warning. systemd and launchd keep their unit as it is.
+ */
+export declare function restartOntoInstalledPackage(args: {
+    manager: ServiceManager;
+    config: ServiceConfig;
+    platform: ServicePlatform;
+    spec: LaunchSpec | null;
+}): Promise<void>;
+/**
+ * Extract a release archive into `tmpDir` and return the release folder in it.
+ * On Windows a release from before KICI_ENV_FILE is refused here, before
+ * anything is copied into the install base or the service is stopped.
+ */
+export declare function extractRelease(args: {
+    archivePath: string;
+    tmpDir: string;
+    component: UpgradeComponent;
+    platform: ServicePlatform;
+    version: string;
+    config: ServiceConfig;
+}): string;
+/**
+ * Put the release in `archivePath` at `versionedDirPath`. The release is
+ * extracted and checked first ({@link extractRelease}); only then is a folder
+ * already at `versionedDirPath` removed, which the caller allows with
+ * `--force`, and the release copied in. A refused release leaves the install
+ * base as it was.
+ */
+export declare function installRelease(args: {
+    archivePath: string;
+    tmpDir: string;
+    installBase: string;
+    versionedDirPath: string;
+    component: UpgradeComponent;
+    platform: ServicePlatform;
+    version: string;
+    config: ServiceConfig;
+}): void;
 /**
  * Perform a versioned directory upgrade for a KiCI component.
  *
@@ -252,13 +301,36 @@ export declare function planNpmSourceUpgrade(opts: {
     force: boolean;
     windows: boolean;
 }): NpmSourceUpgradeAction;
-/** Injected process runner seam for {@link installGlobalPackage}. */
-type SpawnRunner = (cmd: string, args: string[], opts?: {
+/** Injected process runner seam for the npm calls of an npm-source upgrade. */
+export type SpawnRunner = (cmd: string, args: string[], opts?: {
     env?: NodeJS.ProcessEnv;
 }) => {
     status: number | null;
+    stdout: string;
     stderr: string;
 };
+/**
+ * The cmd.exe command line for npm on Windows. npm is a batch file there, which
+ * Node.js starts only through a shell, and Node.js joins the parts of a shell
+ * command with spaces and quotes none of them. The standard Node.js install is
+ * under `C:\Program Files`, so the npm path is quoted here. An argument with a
+ * character outside those of a package name, a version or a flag is refused
+ * rather than handed to cmd.exe.
+ */
+export declare function windowsShellCommand(cmd: string, args: string[]): string;
+/**
+ * Whether `version` of the KiCI packages reads KICI_ENV_FILE, asked of the
+ * registry the unit's npm installs from. A release that reads it publishes the
+ * env-file loader in `@kici-dev/shared`, which every KiCI package of the same
+ * version depends on.
+ */
+export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
+    ok: true;
+    reads: boolean;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Install `<owningPackage>@<version>` globally under the unit's own pinned node,
  * so it lands in exactly the global prefix the unit's ExecStart resolves from.
@@ -278,6 +350,47 @@ export declare function installGlobalPackage(target: NpmInstallTarget, version:
     stderr: string;
 };
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions, hooks?: UpgradeHooks): Promise<void>;
+/** The inputs of {@link restartOnlyUpgrade}. */
+export interface RestartOnlyArgs {
+    component: UpgradeComponent;
+    config: ServiceConfig;
+    resolvedInstance: ResolvedInstance;
+    manager: ServiceManager;
+    verdict: NpmSourceLaunchVerdict;
+    opts: VersionedUpgradeOptions;
+    platform: ServicePlatform;
+    /** The launch command read from the registration before the upgrade. */
+    spec: LaunchSpec | null;
+}
+/** The inputs of {@link performSelfDrivingInstall}. */
+export interface SelfDriveArgs extends Omit<RestartOnlyArgs, 'verdict'> {
+    action: {
+        target: NpmInstallTarget;
+        version: string;
+    };
+    /** Runs npm; tests inject it. */
+    run?: SpawnRunner;
+}
+/**
+ * Restart-only path: the operator pre-installed `@kici-dev/<pkg>@<version>` (or
+ * kici-admin) themselves. Verify the unit will launch the invoking CLI's version,
+ * restart onto it, and persist the manifest version.
+ */
+export declare function restartOnlyUpgrade(args: RestartOnlyArgs): Promise<void>;
+/**
+ * Self-driving path: install the resolved global package under the unit's own
+ * pinned node/npm, restart, and verify the unit now launches the requested
+ * version.
+ */
+export declare function performSelfDrivingInstall(args: SelfDriveArgs): Promise<void>;
+/**
+ * Stop the service, switch the active version pointer to an already-installed
+ * versioned directory (atomic symlink on Unix; re-registration + version file
+ * on Windows), restart, and persist the new `kiciVersion` into the manifest.
+ *
+ * Shared by `--rollback` (switch to the previous version) and `--pick` (switch
+ * to any chosen installed version).
+ */
 export declare function switchToInstalledVersion(args: {
     component: UpgradeComponent;
     platform: ServicePlatform;
@@ -293,5 +406,4 @@ export declare function switchToInstalledVersion(args: {
     /** Skip the confirmation the unknown-head warning falls through to. */
     yes?: boolean;
 }): Promise<void>;
-export {};
 //# sourceMappingURL=versioned-upgrade.d.ts.map

package/dist/cli/commands/workflow.d.ts

@@ -2,10 +2,9 @@
  * Workflow registration commands for kici-admin.
  *
  * Provides operator-facing read access to the workflow_registrations table
- * via the orchestrator's admin HTTP API. This is the dogfooded replacement
- * for "let me just psql the registration table" — every CLI subcommand here
- * goes through AdminApiClient and the existing /api/v1/admin/registrations
- * route.
+ * via the orchestrator's admin HTTP API. Use it instead of querying the
+ * registration table with psql: every CLI subcommand here goes through
+ * AdminApiClient and the existing /api/v1/admin/registrations route.
  *
  *   workflow list                List registered workflows (table or JSON)
  *

package/dist/cli/open-browser.d.ts

@@ -5,7 +5,7 @@
  * blocked launcher) just falls back to copy-paste.
  *
  * `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
- * (E2E / headless capture), any other value is run with `{url}` substituted —
+ * (automated tests / headless capture), any other value is run with `{url}` substituted —
  * mirroring the `kici login` convention.
  */
 export declare function openBrowserBestEffort(url: string): void;

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

@@ -33,4 +33,22 @@ export declare function resolveServiceExecutable(opts: {
     nodePath: string;
     entryScript?: string;
 }): ServiceExecutable;
+/**
+ * The path of a server entry script installed beside this CLI, for a service
+ * that runs `node <script>`. `resolve` is the calling module's
+ * `import.meta.resolve`, or undefined where the CLI has none: a kici-admin from a
+ * standalone package is a single CommonJS bundle that carries no orchestrator
+ * or agent server. Either way the error names `--binary`, the launcher the
+ * service runs instead.
+ */
+export declare function resolveServerScript(specifier: string, component: ServerComponent, resolve: ModuleResolver | undefined): string;
+/**
+ * Refuse an install without `--binary` on a kici-admin that cannot resolve
+ * installed packages, before the wizard runs or any file is written.
+ */
+export declare function assertServerResolvable(component: ServerComponent, binary: string | undefined, resolve: ModuleResolver | undefined): void;
+type ServerComponent = 'orchestrator' | 'agent';
+/** A module's `import.meta.resolve`. */
+export type ModuleResolver = (specifier: string) => string;
+export {};
 //# sourceMappingURL=entrypoint.d.ts.map

package/dist/cli/service/image-digests.d.ts

@@ -11,6 +11,16 @@
  * layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
  * the package root) and the single-file bundle (`dist/cli.js` → one dir up).
  */
+import type { Component } from './instance/types.js';
+/** The published image a component runs, whatever the service is named. */
+export declare function installerImageName(component: Component): string;
+/**
+ * The release {@link resolveImageRef} pins `name` at, or null when it falls
+ * back to the moving `:latest` tag.
+ */
+export declare function pinnedImageVersion(name: string, opts?: {
+    filePath?: string;
+}): string | null;
 /**
  * Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
  * image. Falls back to `:latest` (with a warning) when no recorded digest exists.

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

@@ -7,12 +7,14 @@
  * platform-specific code on every platform.
  */
 export type { ServiceManager, ServiceConfig, LaunchSpec, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
-export { DEFAULT_RESTART_POLICY } from './types.js';
+export { DEFAULT_RESTART_POLICY, SERVICE_TEXT } from './types.js';
 export { detectPlatform, isRoot, kiciConfigRoot, getConfigDir, getLogDir, getCacheDir, } from './platform-detect.js';
 export { resolveUserLevel, type PrivilegeOpts } from './privilege.js';
+export { restrictEnvFileAccess } from './windows-acl.js';
+export { ENV_FILE_LOADER_EXPORT, envFileRefusal, launchReadsEnvFile, launchedRelease, } from './windows-env-file.js';
 export type { Component, InstanceManifest, IndexEntry, ResolveOptions, ResolvedInstance, } from './instance/types.js';
 export { COMPONENTS, isComponent } from './instance/types.js';
-export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
+export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveLauncherVersion, writeInstallManifest, type InstallManifestWrite, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
 export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
 export { candidatePlatforms, listInstances, resolveInstance, resolveInstanceTarget, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
 export type { ListedInstance, ResolveArgs, ListInstancesArgs, ResolveTargetArgs, ResolvedTarget, } from './instance/resolve.js';

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

@@ -39,6 +39,45 @@ export declare function readKiciVersion(): string;
  * stand behind.
  */
 export declare function resolveVersionFromLaunchSpec(spec: LaunchSpec, component: Component): string | null;
+/**
+ * The version of the launcher a service definition starts, or null when the
+ * launch command does not show one.
+ *
+ * An npm-installed entry script names its version in its package.json
+ * ({@link resolveVersionFromLaunchSpec}). A launcher under the instance's
+ * install base resolves into the `<component>-<version>` folder an archive
+ * upgrade extracted: through the `<component>` symlink on Linux and macOS, or
+ * directly where Windows registers it. A `--binary` anywhere else shows none.
+ */
+export declare function resolveLauncherVersion(spec: LaunchSpec, component: Component, installBase: string): string | null;
+/** What {@link writeInstallManifest} wrote. */
+export interface InstallManifestWrite {
+    file: string;
+    manifest: InstanceManifest;
+    /** Set when the folder held a manifest the install replaced instead of updating. */
+    warning?: string;
+}
+/**
+ * Write the manifest `install` built into `instanceDir`.
+ *
+ * A first install writes `fresh` as it is. A re-install of the same instance
+ * (the folder holds a readable manifest of this component and name) updates
+ * that manifest: it keeps what the instance recorded over time — `createdAt`,
+ * the `migrationHeads` the rollback schema guard reads, and any field a newer
+ * CLI wrote — and takes every other field from `fresh`. Its `kiciVersion` is
+ * the version of the launcher `launch` starts; when the launcher shows none,
+ * the recorded version stands, because the CLI that ran `install` need not
+ * be the version the service runs. A compose service runs the image its
+ * compose file pins, whatever `launch` names, so a compose re-install records
+ * the release of that image (`opts.digestRecordPath` overrides the digest
+ * record it reads, for tests).
+ *
+ * A manifest that cannot be read, or that names another instance, is
+ * replaced, and the result carries a warning.
+ */
+export declare function writeInstallManifest(instanceDir: string, fresh: InstanceManifest, launch: LaunchSpec, opts?: {
+    digestRecordPath?: string;
+}): InstallManifestWrite;
 /**
  * The global npm package + node runtime an npm-source upgrade must install
  * into, derived from a unit's launch spec. `owningPackage` is the top-level

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

@@ -18,8 +18,24 @@ export declare class LaunchdServiceManager implements ServiceManager {
     private label;
     /** Resolve the log directory based on service level. */
     private logDir;
-    /** Resolve the plist file path based on service level. */
-    private plistPath;
+    /** 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.
+     */
+    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.
+     */
+    private resolveJob;
     /** Parse a .env file into key-value pairs. */
     private parseEnvFile;
     /** Escape XML special characters. */
@@ -41,20 +57,29 @@ export declare class LaunchdServiceManager implements ServiceManager {
      * 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` / `kill` verbs take the domain explicitly, so a
+     * `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.
      */
     private domain;
-    /** `<domain>/<label>` — the target string for kickstart/kill/print/enable. */
+    /** `<domain>/<label>` — the target string for bootout/kickstart/print. */
     private domainTarget;
-    /** Is the service currently loaded in its target domain? */
+    /**
+     * `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.
+     */
+    private printJob;
+    /** Is the job currently loaded in its target domain? */
     private isLoaded;
     install(config: ServiceConfig): Promise<void>;
     /**
-     * Poll until the service is no longer loaded in its target domain, or a
-     * short deadline elapses. `launchctl bootout` is asynchronous — it returns
-     * before launchd has finished releasing the service — so a bootstrap issued
+     * 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.
@@ -64,13 +89,23 @@ export declare class LaunchdServiceManager implements ServiceManager {
      * 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. If a stale instance
-     * reappears between attempts, it is booted out before the next try.
+     * 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.
      */
     private bootstrapWithRetry;
     uninstall(config: ServiceConfig): Promise<void>;
     start(config: ServiceConfig): Promise<void>;
     stop(config: ServiceConfig): Promise<void>;
+    /**
+     * Boot the job out of its domain and wait until launchd has finished the
+     * teardown. Does nothing when no job is loaded.
+     */
+    private unload;
     restart(config: ServiceConfig): Promise<void>;
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * 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:
+ * - 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.
+ */
+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.
+ */
+export declare function stopWaitSeconds(config: ServiceConfig): number;
+//# sourceMappingURL=shutdown-grace.d.ts.map

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

@@ -20,6 +20,15 @@ export interface RestartPolicy {
 }
 /** Default restart policy: backoff 1s, 5s, 15s, 30s; max 5 failures in 5 minutes. */
 export declare const DEFAULT_RESTART_POLICY: RestartPolicy;
+/**
+ * The display name and description a component's service is registered with.
+ * `install` and every upgrade that registers a service again use it, so an
+ * upgraded registration carries the same text as a fresh one.
+ */
+export declare const SERVICE_TEXT: Record<'orchestrator' | 'agent', {
+    displayName: string;
+    description: string;
+}>;
 /** Configuration for installing a service. */
 export interface ServiceConfig {
     /** Service identifier (e.g., "kici-orchestrator"). */

package/dist/cli/service/windows-acl.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Restricting a Windows service's env file to the service account and to
+ * Administrators.
+ *
+ * Node maps a file mode onto Windows by toggling the read-only attribute and
+ * changes no ACL, so ENV_FILE_MODE protects nothing there. The instance folder
+ * under C:\ProgramData\kici\ inherits read access for BUILTIN\Users from
+ * C:\ProgramData. Its ACL is replaced with full control for LocalSystem (the
+ * account the shawl service runs as) and Administrators, inherited by
+ * everything created in it: the env file, the temporary file a secure write
+ * stages it through, and the service logs are unreadable to other accounts
+ * from the moment they exist.
+ *
+ * Every call passes `/L` and none recurses, so icacls acts on the folder and on
+ * the env file themselves and never on what a link there points at. A
+ * recursive `/reset` or `/setowner` descends into the target of a junction or
+ * of a symbolic link, even with `/L`, and rewrites the ACL of the files there.
+ * The new folder ACL still reaches every entry that inherits from the folder.
+ */
+/** NT AUTHORITY\SYSTEM, the account a shawl service runs as. */
+export declare const LOCAL_SYSTEM_SID = "S-1-5-18";
+/** BUILTIN\Administrators. */
+export declare const ADMINISTRATORS_SID = "S-1-5-32-544";
+/** Runs `icacls` with the given arguments; throws when it fails. */
+export type IcaclsRunner = (args: string[]) => void;
+/**
+ * The icacls arguments that remove every inherited ACE from `dir` and grant
+ * full control, inherited by files and folders, to LocalSystem and
+ * Administrators. SIDs rather than names, so a localized Windows resolves them.
+ */
+export declare function restrictDirArgs(dir: string): string[];
+/** The icacls arguments that reset `file` to inherit only from its folder. */
+export declare function resetFileArgs(file: string): string[];
+/**
+ * Restrict the folder that holds `envFilePath`, then reset an existing env
+ * file to inherit only from it, which also drops any explicit ACE on the file.
+ * Run it before the first secret is written into the folder.
+ */
+export declare function restrictEnvFileAccess(envFilePath: string, run?: IcaclsRunner, exists?: (filePath: string) => boolean): void;
+//# sourceMappingURL=windows-acl.d.ts.map