@kici-dev/orchestrator 0.6.1 → 0.7.0

package/dist/cli/commands/trust-policy.d.ts

@@ -69,6 +69,21 @@ export interface TrustPolicyView {
  * route returned, so the values remain reachable for anyone who needs them.
  */
 export declare function formatPolicy(policy: TrustPolicyView, format: string): string;
+/**
+ * Warn that the fork switch in force silently drops pull requests.
+ *
+ * `ignore` is the one verdict that leaves nothing behind: no run row, no check
+ * status, and nothing on the pull request itself. A maintainer who does not
+ * already know the switch exists has no way to connect a fork PR that CI never
+ * touched to a policy they never set, so the reader of `trust-policy show`
+ * is told outright — with where to look for each individual drop.
+ *
+ * `reject` is deprecated and resolves through the same arm, so it warns too.
+ *
+ * Returns the lines rather than printing them so the check is unit-testable,
+ * matching `policyDeprecationWarnings` above.
+ */
+export declare function forkDropWarnings(policy: TrustPolicyView): string[];
 /**
  * Render the enforced hold window.
  *
@@ -135,9 +150,47 @@ export interface TrustDirectoryView {
 interface DirectoryResponse {
     directory: TrustDirectoryView | null;
     platformManaged: boolean;
+    /**
+     * Whether the orchestrator's Platform connection is up right now.
+     *
+     * Absent whenever there is no connection state to report, which never means
+     * "down": an independent orchestrator, the `PATCH` and `DELETE` responses,
+     * and an orchestrator that predates the field. {@link directoryStalenessNote}
+     * escalates only on an explicit `false`.
+     */
+    platformConnected?: boolean;
     /** Present on `directory-remove`: false when the member held nothing. */
     removed?: boolean;
 }
+/**
+ * Say how long ago the directory was written, beside the timestamp itself.
+ *
+ * The absolute time is what the orchestrator stored and stays first, because it
+ * is what correlates with a Platform-side change. The age is what an operator
+ * would otherwise compute in their head at the exact moment they are least able
+ * to — mid-incident, reading a refused approval.
+ *
+ * A timestamp this cannot parse renders alone rather than as `NaN`, and one in
+ * the future renders as `0s` — the two clocks are different machines'.
+ */
+export declare function formatDirectoryAge(updatedAt: string, now: number): string;
+/**
+ * Explain what an old directory costs, and escalate when it cannot refresh.
+ *
+ * Only a Platform-attached orchestrator has an upstream to lag behind. An
+ * independent one's directory is written by the operator reading this, so there
+ * is nothing to be stale against and nothing to say.
+ *
+ * The connected wording is a `Note:` and the disconnected one a `Warning:`,
+ * because the two ask for different things: one states a property of the design
+ * the reader should know, the other names a condition they should act on. The
+ * `Warning:` producers above — `forkDropWarnings`, `policyExpiryWarnings` and
+ * `policyDeprecationWarnings` — are all of the second kind.
+ *
+ * Returns the lines rather than printing them so the check is unit-testable,
+ * matching `forkDropWarnings` above.
+ */
+export declare function directoryStalenessNote(res: DirectoryResponse): string[];
 /**
  * Render the stored approval directory, or say why there is nothing to render.
  *
@@ -146,8 +199,11 @@ interface DirectoryResponse {
  * decides whether the approval counts, and a `{team}` clause is matched against
  * the team memberships. So the listing is per-entry rather than a set of counts
  * — "who can approve right now" is the question this command exists to answer.
+ *
+ * `now` is a parameter so the rendered age is deterministic under test; every
+ * caller takes the default.
  */
-export declare function formatDirectory(res: DirectoryResponse, format: string): string;
+export declare function formatDirectory(res: DirectoryResponse, format: string, now?: number): string;
 export declare function registerTrustPolicyCommands(program: Command, getClient: () => AdminApiClient): void;
 export {};
 //# sourceMappingURL=trust-policy.d.ts.map

package/dist/cli/join.d.ts

@@ -3,7 +3,7 @@
  *
  * Bootstraps a new orchestrator by connecting to an existing cluster via
  * Platform relay or direct peer, receiving an encrypted config bundle, and
- * writing the local YAML config.
+ * writing an env file the orchestrator boots from.
  *
  * Usage:
  *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://api.kici.dev/ws --api-key KEY

package/dist/cli/service/backup-timer.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Scheduled orchestrator database backups.
+ *
+ * Renders and registers a `kici-<instance>-db-backup` service + timer pair that
+ * runs `kici-admin db backup --output-dir <dir> --keep <n>` on a calendar
+ * schedule. systemd gets a `.service` plus a `.timer`; launchd gets one plist
+ * with a `StartCalendarInterval`.
+ *
+ * Windows and Compose are refused: `sc.exe` has no timer concept, and a
+ * Compose orchestrator runs in a container whose host scheduler KiCI does not
+ * own. Both refusals name the platform-native equivalent.
+ */
+import type { ServicePlatform } from './types.js';
+/** Default retention: keep the last week of daily dumps. */
+export declare const BACKUP_TIMER_DEFAULT_KEEP = 7;
+/** Default calendar spec — midnight every day, on both platforms. */
+export declare const BACKUP_TIMER_DEFAULT_SCHEDULE = "daily";
+export interface BackupTimerConfig {
+    /** Orchestrator instance name the timer backs up (e.g. `kici-orchestrator`). */
+    serviceName: string;
+    /** Calendar spec: a systemd `OnCalendar=` value, or `daily` / `HH:MM`. */
+    schedule: string;
+    /** Directory the timestamped dumps are written to. */
+    outputDir: string;
+    /** How many dumps to retain after each run. */
+    keep: number;
+    /** Node binary the scheduled unit runs. */
+    nodeBinPath: string;
+    /** `kici-admin` entry script the scheduled unit runs. */
+    cliScriptPath: string;
+    /** Env file carrying `KICI_DATABASE_URL` for the scheduled run. */
+    envFilePath: string;
+    /** User-level (`systemctl --user`, LaunchAgent) vs system-level. */
+    isUserLevel: boolean;
+    /** Account a system-level unit runs as. */
+    user?: string;
+}
+/**
+ * `kici-orchestrator` -> `kici-orchestrator-db-backup`. A name that already
+ * carries the `kici-` prefix keeps exactly one, so the unit is always
+ * `kici-<instance>-db-backup`.
+ */
+export declare function backupTimerName(serviceName: string): string;
+/** The argv the scheduled unit executes, after the node binary. */
+export declare function backupCommandArgs(config: BackupTimerConfig): string[];
+/**
+ * Explain why a platform cannot carry a KiCI-managed backup timer, and what to
+ * use instead. Returns null when the platform is supported.
+ */
+export declare function unsupportedPlatformMessage(platform: ServicePlatform, outputDir: string, keep: number): string | null;
+/** Throw the {@link unsupportedPlatformMessage} refusal, if there is one. */
+export declare function assertTimerPlatformSupported(platform: ServicePlatform, outputDir: string, keep: number): void;
+/** Render the systemd `.service` unit the timer triggers. */
+export declare function renderSystemdBackupService(config: BackupTimerConfig): string;
+/** Render the systemd `.timer` unit that schedules the backup service. */
+export declare function renderSystemdBackupTimer(config: BackupTimerConfig): string;
+/**
+ * Translate a calendar spec into the launchd `StartCalendarInterval` fields.
+ * launchd has no calendar-expression parser, so only the two forms that map
+ * cleanly are accepted; anything else is refused by name.
+ */
+export declare function parseLaunchdSchedule(schedule: string): {
+    hour: number;
+    minute: number;
+};
+/**
+ * Read one key out of a `KEY=value` env file. Returns undefined when the file
+ * or the key is absent — the caller decides whether that is fatal.
+ *
+ * The value is trimmed and stripped of surrounding quotes, because these files
+ * are hand-edited as often as they are generated: a path written as
+ * `"/etc/kici/scalers.yaml"` or left with a trailing space names the same file
+ * and must read back the same way. Only the outer quote characters go — an
+ * embedded `=` stays, so `B=two=three` still reads as `two=three`.
+ *
+ * A duplicated key takes its **last** occurrence, because that is the value the
+ * running process holds: systemd's `EnvironmentFile=` applies each assignment in
+ * order, so the last one wins. Reporting an earlier one would name a path or a
+ * database the service never used, which is the opposite of what these readers
+ * are for. Every other env-file reader in the repo takes the last occurrence too.
+ */
+export declare function readEnvValue(content: string, key: string): string | undefined;
+/** Render the launchd plist that schedules the backup run. */
+export declare function renderLaunchdBackupPlist(config: BackupTimerConfig, env: Record<string, string>): string;
+/** Filesystem + process seams, so install/uninstall are unit-testable. */
+export interface TimerIo {
+    mkdirp: (dir: string) => void;
+    writeFile: (file: string, content: string) => void;
+    readFile: (file: string) => string;
+    removeFile: (file: string) => void;
+    run: (bin: string, args: string[]) => void;
+}
+export declare const defaultTimerIo: TimerIo;
+/** Directory holding the generated systemd units for this privilege level. */
+export declare function systemdUnitDir(isUserLevel: boolean): string;
+/** Path of the generated launchd plist for this privilege level. */
+export declare function launchdPlistPath(name: string, isUserLevel: boolean): string;
+/** Install the backup timer for the detected platform. Returns the files written. */
+export declare function installBackupTimer(platform: ServicePlatform, config: BackupTimerConfig, io?: TimerIo): {
+    unitName: string;
+    files: string[];
+};
+/** Remove the backup timer for the detected platform. Returns the files removed. */
+export declare function uninstallBackupTimer(platform: ServicePlatform, config: Pick<BackupTimerConfig, 'serviceName' | 'isUserLevel' | 'outputDir' | 'keep'>, io?: TimerIo): {
+    unitName: string;
+    files: string[];
+};
+//# sourceMappingURL=backup-timer.d.ts.map

package/dist/cli/service/compose-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Where the generated compose file for a service lives: beside its env file,
+ * named for the service.
+ *
+ * This sits in its own module because two callers need it and they cannot
+ * share `compose.ts` — that module also detects a container runtime, which the
+ * env-file writer has no business pulling in. One definition means the naming
+ * convention is written down once rather than re-derived at each site.
+ */
+export declare function composeFilePath(envFilePath: string, serviceName: string): string;
+//# sourceMappingURL=compose-path.d.ts.map

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

@@ -20,7 +20,29 @@ type Runtime = 'podman' | 'docker';
  */
 export declare function detectRuntime(): Runtime;
 export declare class ComposeServiceManager implements ServiceManager {
+    readonly platform: 'compose';
     private runtime;
+    /**
+     * True when the container runtime's own registry answers. A host with
+     * neither podman nor docker cannot hold a running compose install, and a
+     * host whose runtime is momentarily down still holds its installs — so
+     * discovery reads a `false` here as "do not touch this platform's index
+     * rows" rather than as an empty scan.
+     *
+     * Both halves are needed, and the second is the one that costs something.
+     * `<runtime> compose version` is answered by the compose client alone: with
+     * dockerd stopped it still exits 0 (measured), so a client-only probe reports
+     * available, `list()` then gets an error it cannot distinguish from an empty
+     * registry, and the reconcile prunes live rows. The `RUNTIME_PROBE_TIMEOUT_MS`
+     * bound does not cover this — the client answers instantly whether or not the
+     * daemon is there, so there is nothing for a timeout to catch.
+     *
+     * `ps -q` is the cheapest question only the registry can answer (0.02s
+     * docker / 0.07s podman on a healthy host), and it fails the same two ways
+     * the scan itself would: non-zero for a daemon that is down, and a timeout
+     * kill for one that is hung.
+     */
+    available(): Promise<boolean>;
     /** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
     private getRuntime;
     /** Run a compose command for the given service config. */

package/dist/cli/service/deploy-env.d.ts

@@ -1,12 +1,3 @@
-/**
- * Deployment-identity env injection for the orchestrator installer.
- *
- * The orchestrator reports its own deployment shape (systemd / launchd /
- * windows / compose) in `source.register` so the dashboard can build the
- * correct `kici-admin` invocation. The shape is only knowable at install time
- * (a running container can't learn its own container name), so the installer
- * injects it into the orchestrator's env file via these `KICI_DEPLOY_*` vars.
- */
 import type { ServicePlatform } from './types.js';
 /** Inputs the installer already has when it writes the env file. */
 export interface DeployEnvInput {
@@ -15,11 +6,19 @@ export interface DeployEnvInput {
     serviceName: string;
     /** Container runtime, only meaningful for the `compose` platform. */
     containerRuntime?: 'podman' | 'docker';
+    /**
+     * Absolute path of the env file the installer is writing. Stamped into the
+     * file itself because the running process cannot derive it: systemd's
+     * `EnvironmentFile=` delivers the variables and not the filename, and a
+     * compose container never sees the host path at all.
+     */
+    envFilePath: string;
 }
 /**
  * Build the `KICI_DEPLOY_*` env lines for a given deployment shape. The mode
- * line is always emitted; container name + runtime are emitted only for the
- * `compose` platform (the only shape with a container to `exec` into).
+ * and config-file lines are always emitted; the container name, runtime, and
+ * compose file are emitted only for the `compose` platform (the only shape
+ * with a container to `exec` into and a generated compose file to read).
  */
 export declare function buildDeployEnvLines(input: DeployEnvInput): string[];
 /**

package/dist/cli/service/env-assignment.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Single-variable upsert for service env-file content.
+ *
+ * The sibling {@link ./deploy-env.js} upserts a whole `KICI_DEPLOY_*` block by
+ * stripping the prefix and re-appending it. A variable an operator may also
+ * have set by hand needs the narrower shape: replace the assignment where it
+ * already sits, so the comment above it still describes the value below it.
+ */
+/**
+ * Whether `content` carries an uncommented assignment of `name`.
+ *
+ * A `#`-prefixed mention does not count: it is documentation, and the readers
+ * that matter (systemd's `EnvironmentFile=`, `selectServerEntry`) skip it.
+ */
+export declare function hasEnvAssignment(content: string, name: string): boolean;
+/**
+ * Return `content` with `name` assigned `value`.
+ *
+ * Every uncommented assignment of `name` is rewritten in place; a file that
+ * declares it nowhere gains the assignment on its last line. Commented lines
+ * are left alone, so a stub's explanatory `# KICI_MODE=...` survives.
+ */
+export declare function upsertEnvAssignment(content: string, name: string, value: string): string;
+//# sourceMappingURL=env-assignment.d.ts.map

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

@@ -14,8 +14,8 @@ export type { Component, InstanceManifest, IndexEntry, ResolveOptions, ResolvedI
 export { COMPONENTS, isComponent } from './instance/types.js';
 export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
 export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
-export { listInstances, resolveInstance, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
-export type { ListedInstance, ResolveArgs, ListInstancesArgs } from './instance/resolve.js';
+export { candidatePlatforms, listInstances, resolveInstance, resolveInstanceTarget, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
+export type { ListedInstance, ResolveArgs, ListInstancesArgs, ResolveTargetArgs, ResolvedTarget, } from './instance/resolve.js';
 import type { ServiceManager, ServicePlatform } from './types.js';
 /**
  * Create a ServiceManager for the given platform.

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

@@ -8,30 +8,49 @@
  *   3. CWD manifest                → read ./.kici-<component>.json
  *   4. otherwise                   → refuse with a candidate list (throws)
  *
- * listInstances reconciles the on-disk index (cache) with the driver's
- * native scan (source of truth). The reconciled result is rewritten back to
+ * 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.
  */
-import type { DiscoveredInstance, ServiceManager } from '../types.js';
+import type { DiscoveredInstance, ServiceManager, ServicePlatform } from '../types.js';
 import type { Component, ResolveOptions, ResolvedInstance } from './types.js';
 /** A reconciled view of a discovered instance: driver scan + (maybe) index entry. */
 export interface ListedInstance extends DiscoveredInstance {
     instanceDir?: string;
     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.
+ */
+export declare function candidatePlatforms(override?: ServicePlatform): ServicePlatform[];
 export interface ListInstancesArgs {
     component: Component;
     isUserLevel: boolean;
     kiciRoot: string;
-    manager: ServiceManager;
+    /**
+     * 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.
+     */
+    managers?: ServiceManager[];
 }
 /**
- * Reconcile <kiciRoot>/instances.json with the driver's native scan, then
+ * 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:
  *
  *   - backward: drop index entries whose unit no longer exists.
- *   - forward: adopt an instanceDir the driver recovered from the unit marker
+ *   - 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.
  *
@@ -39,6 +58,11 @@ export interface ListInstancesArgs {
  * (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 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.
  */
 export declare function listInstances(args: ListInstancesArgs): Promise<ListedInstance[]>;
 /**
@@ -57,7 +81,11 @@ export interface ResolveArgs {
     opts: ResolveOptions;
     cwd: string;
     kiciRoot: string;
-    manager: ServiceManager;
+    /**
+     * Every driver discovery should scan. 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
@@ -77,4 +105,40 @@ export declare function resolveInstance(args: ResolveArgs): Promise<ResolvedInst
  * 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.
+     */
+    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.
+     */
+    platformOverride?: ServicePlatform;
+    /** Driver factory. Defaults to the service barrel's createServiceManager. */
+    createManager?: (platform: ServicePlatform) => Promise<ServiceManager>;
+}
+/** The instance a lifecycle command operates on, and the driver that can do it. */
+export interface ResolvedTarget {
+    resolved: ResolvedInstance;
+    manager: ServiceManager;
+    /** The install's own platform — `platformOverride ?? manifest.platform`. */
+    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.
+ */
+export declare function resolveInstanceTarget(args: ResolveTargetArgs): Promise<ResolvedTarget>;
 //# sourceMappingURL=resolve.d.ts.map

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

@@ -32,6 +32,21 @@ export interface InstanceManifest {
     installBase: string;
     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.
+     */
+    migrationHeads?: Record<string, string>;
 }
 /** A row in `<kiciRoot>/instances.json`. */
 export interface IndexEntry {

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

@@ -6,7 +6,14 @@
  * user-level (~/Library/LaunchAgents/) agents.
  */
 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.
+ */
+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. */

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

@@ -18,6 +18,7 @@ import type { DiscoveredInstance, ServiceConfig, ServiceManager, ServiceStatus,
  */
 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.

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

@@ -136,6 +136,36 @@ export interface DiscoveredInstance {
  * Each method operates on a service identified by the ServiceConfig.
  */
 export interface ServiceManager {
+    /**
+     * The platform this driver manages. Discovery scans several drivers at once
+     * (a host can hold both a systemd install and a compose install), and each
+     * driver's scan is authoritative only over its own platform's index rows —
+     * including when that scan comes back empty. An empty scan carries no row to
+     * read a platform off, so the driver states it here.
+     */
+    readonly platform: ServicePlatform;
+    /**
+     * Whether this driver can inspect its registry right now. A driver that
+     * answers `false` is excluded from discovery, and the index rows for its
+     * platform are left untouched — an empty scan from a driver whose registry is
+     * unreachable is not evidence that the instances are gone.
+     *
+     * Absent means always available: an init system a driver targets is either
+     * present or the driver is not a candidate for the host at all — which is
+     * why the two filesystem-backed drivers (systemd, launchd) omit it and let
+     * an unreadable unit directory throw out of `list()` instead. Compose and
+     * Windows implement it because their registry is a service that can be down
+     * or hung while the host and the client binary are fine.
+     *
+     * A driver that implements it MUST probe the registry itself, not the client
+     * that talks to it: `<runtime> compose version` and `where powershell` both
+     * answer on a host whose registry is down, which is the shape that reported
+     * available, scanned empty, and pruned live rows.
+     *
+     * Discovery calls this INSIDE its own error handling, so a probe that
+     * rejects drops only this driver.
+     */
+    available?(): Promise<boolean>;
     /** Install and register the service with the init system. */
     install(config: ServiceConfig): Promise<void>;
     /** Remove the service registration (preserves config/data). */
@@ -160,6 +190,12 @@ export interface ServiceManager {
      *
      * `isUserLevel` selects user vs system scope on platforms where that matters
      * (systemd, launchd); ignored on Windows/compose.
+     *
+     * An empty array means the registry answered and holds no KiCI services —
+     * the reconcile prunes this platform's index rows on that basis. A driver
+     * that could not read its registry must therefore throw rather than return
+     * `[]`; discovery drops a throwing driver exactly as it drops one whose
+     * `available()` said false.
      */
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
     /**

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

@@ -8,6 +8,22 @@
  */
 import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
 export declare class WindowsServiceManager implements ServiceManager {
+    readonly platform: 'windows';
+    /**
+     * True when the service registry this driver reads actually answers.
+     *
+     * Probes the same subsystem `list()` reads — CIM's `Win32_Service` — with a
+     * filter that cannot match, so a healthy host answers with an empty result
+     * set and exits 0. It deliberately does NOT probe for the presence of
+     * `powershell` or `sc.exe`: a client-only probe is exactly the defect this
+     * driver's compose sibling had, where the client answered on a host whose
+     * registry was down and the empty scan then pruned live rows.
+     *
+     * A name filter rather than a well-known service name: no service is assumed
+     * to exist, and no display string is parsed, so the probe carries no locale
+     * or Windows-edition assumption.
+     */
+    available(): Promise<boolean>;
     /**
      * Check whether a Windows service is currently registered.
      * `sc.exe query` exits non-zero (execSync throws) when the service does

package/dist/cli/wizard/orchestrator-wizard.d.ts

@@ -14,6 +14,15 @@ export interface OrchestratorSourceHint {
     privateKeyPath: string;
     webhookSecret?: string;
 }
+/** Inputs the install command threads into the wizard. */
+export interface OrchestratorWizardOptions {
+    /**
+     * Preselect the operating-mode prompt (from `orchestrator install --mode`).
+     * Defaults to `hybrid`, the recommended shape: the Platform relay plus this
+     * orchestrator's own direct webhook ingress.
+     */
+    defaultMode?: OrchestratorMode;
+}
 /** Config produced by the orchestrator wizard. */
 interface OrchestratorInstallConfig {
     mode: OrchestratorMode;
@@ -54,15 +63,15 @@ export declare const DEFAULT_PLATFORM_RELAY_URL = "wss://api.kici.dev/ws";
  * Run the interactive orchestrator setup wizard.
  *
  * Asks only essential questions per the user decision:
- * 1. Mode (platform/hybrid/observed/independent)
+ * 1. Mode (hybrid/platform/observed/independent)
  * 2. Database URL
  * 3. Port
  * 4. Secrets encryption key
  * 5. Bootstrap admin token (for kici-admin authentication)
  * 6. Platform URL + token (if platform/hybrid/observed mode), plus the public
- *    webhook base URL when observed
+ *    webhook base URL -- required in observed mode, optional in hybrid
  * 7. Webhook secret (if hybrid/independent mode)
  */
-export declare function runOrchestratorWizard(): Promise<OrchestratorInstallConfig>;
+export declare function runOrchestratorWizard(opts?: OrchestratorWizardOptions): Promise<OrchestratorInstallConfig>;
 export {};
 //# sourceMappingURL=orchestrator-wizard.d.ts.map

package/dist/cli/wizard/prompts.d.ts

@@ -12,6 +12,13 @@ export declare function promptPort(defaultPort: number): Promise<number>;
 export declare function promptConfirm(message: string, defaultValue?: boolean): Promise<boolean>;
 /** Prompt for a URL with http(s):// validation. */
 export declare function promptUrl(message: string, defaultValue?: string): Promise<string>;
+/**
+ * Prompt for an optional URL: an empty answer returns undefined, any other
+ * answer must carry an http(s)/ws(s) scheme. Used where a URL genuinely may be
+ * left unset (the hybrid public ingress base), which `promptUrl` cannot express
+ * because its validator rejects a blank answer.
+ */
+export declare function promptOptionalUrl(message: string): Promise<string | undefined>;
 /** Prompt for a secret/password (masked input). */
 export declare function promptSecret(message: string): Promise<string>;
 /** Prompt for a selection from a list of options. */