@kici-dev/orchestrator 0.1.12 → 0.1.14

package/dist/cli/commands/agent-service/install.d.ts

@@ -3,6 +3,13 @@
  *
  * Registers the agent as a native system service on the current platform.
  * Accepts orchestrator URL and token for connecting to the orchestrator.
+ *
+ * Targeting is folder-anchored: the install writes an instance manifest
+ * into the deploy folder (`--instance-dir`, default: CWD) and appends a
+ * row to the host-wide instance index so every lifecycle command can
+ * reconstruct the ServiceConfig without re-deriving paths. A create-path
+ * guard refuses to clobber a same-named foreign instance unless `--force`
+ * is passed.
  */
 import type { Command } from 'commander';
 export declare function registerAgentInstall(agent: Command): void;

package/dist/cli/commands/agent-service/logs.d.ts

@@ -1,8 +1,13 @@
 /**
- * `kici-admin agent-service logs` command.
+ * `kici-admin agent logs` command.
  *
- * Tails and follows agent service logs with filtering.
- * Delegates to the platform-specific service manager.
+ * Tails and follows agent service logs with filtering by time, level,
+ * and output format. Delegates to the platform-specific service
+ * manager's logs() method.
+ *
+ * Target resolution goes through resolveInstance — the same priority chain
+ * every lifecycle command uses (--instance-dir > --name > CWD manifest >
+ * refusal with candidate list).
  */
 import type { Command } from 'commander';
 export declare function registerAgentLogsCommand(parent: Command): void;

package/dist/cli/commands/agent-service/restart.d.ts

@@ -1,7 +1,11 @@
 /**
  * `kici-admin agent restart` command.
  *
- * Restarts the agent service.
+ * Restarts the agent service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerAgentRestart(agent: Command): void;

package/dist/cli/commands/agent-service/start.d.ts

@@ -1,7 +1,11 @@
 /**
  * `kici-admin agent start` command.
  *
- * Starts the agent service.
+ * Starts the agent service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerAgentStart(agent: Command): void;

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

@@ -1,9 +1,13 @@
 /**
- * `kici-admin agent-service status` command.
+ * `kici-admin agent status` command.
  *
  * Shows OS-level service status (state, PID, uptime) and queries
  * the running agent's health API for agent-specific info (labels,
  * orchestrator connection, current job).
+ *
+ * Target resolution goes through resolveInstance — the same priority chain
+ * every lifecycle command uses (--instance-dir > --name > CWD manifest >
+ * refusal with candidate list).
  */
 import type { Command } from 'commander';
 export declare function registerAgentStatusCommand(parent: Command): void;

package/dist/cli/commands/agent-service/stop.d.ts

@@ -1,7 +1,11 @@
 /**
  * `kici-admin agent stop` command.
  *
- * Stops the agent service.
+ * Stops the agent service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerAgentStop(agent: Command): void;

package/dist/cli/commands/agent-service/uninstall.d.ts

@@ -1,8 +1,12 @@
 /**
  * `kici-admin agent uninstall` command.
  *
- * Removes the agent service registration.
- * Preserves config files and logs per user decision.
+ * Removes the agent service registration. Target resolution goes
+ * through resolveInstance — the same priority chain every lifecycle command
+ * uses (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * The manifest stays on disk so subsequent commands can still reference the
+ * deploy folder; the host-wide index entry is dropped unconditionally so a
+ * stale row never lingers after the unit is gone.
  */
 import type { Command } from 'commander';
 export declare function registerAgentUninstall(agent: Command): void;

package/dist/cli/commands/agent-service/upgrade.d.ts

@@ -1,10 +1,20 @@
 /**
- * `kici-admin agent-service upgrade` command.
+ * `kici-admin agent upgrade` command.
  *
  * Upgrades the agent using the versioned directory layout:
- * - Same pattern as orchestrator: versioned directories with symlink switching
- * - Extracts to agent-{version}/, symlink at agent/
+ * - Extracts new version alongside old versions
+ * - Updates symlink (Unix) or service registration (Windows) atomically
+ * - Preserves old versions for rollback
  * - No database migrations (agents are stateless)
+ *
+ * Targeting is folder-anchored: the resolution priority is
+ *   1. `--instance-dir <path>`
+ *   2. `--name <name>`
+ *   3. CWD manifest (`./.kici-agent.json`)
+ *   4. otherwise refuses with a candidate-list error.
+ *
+ * `--name` no longer has a default — every invocation must resolve via one
+ * of the above paths.
  */
 import type { Command } from 'commander';
 export declare function registerAgentUpgradeCommand(parent: Command): void;

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

@@ -4,6 +4,10 @@
  * Tails and follows service logs with filtering by time, level,
  * and output format. Delegates to the platform-specific service
  * manager's logs() method.
+ *
+ * Target resolution goes through resolveInstance — the same priority chain
+ * every lifecycle command uses (--instance-dir > --name > CWD manifest >
+ * refusal with candidate list).
  */
 import type { Command } from 'commander';
 export declare function registerLogsCommand(parent: Command): void;

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

@@ -1,7 +1,11 @@
 /**
  * `kici-admin orchestrator restart` command.
  *
- * Restarts the orchestrator service.
+ * Restarts the orchestrator service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerOrchestratorRestart(orchestrator: Command): void;

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

@@ -1,7 +1,11 @@
 /**
  * `kici-admin orchestrator start` command.
  *
- * Starts the orchestrator service.
+ * Starts the orchestrator service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerOrchestratorStart(orchestrator: Command): void;

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

@@ -4,6 +4,10 @@
  * 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).
+ *
+ * Target resolution goes through resolveInstance — the same priority chain
+ * every lifecycle command uses (--instance-dir > --name > CWD manifest >
+ * refusal with candidate list).
  */
 import type { Command } from 'commander';
 export declare function registerStatusCommand(parent: Command): void;

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

@@ -1,7 +1,11 @@
 /**
  * `kici-admin orchestrator stop` command.
  *
- * Stops the orchestrator service.
+ * Stops the orchestrator service. Target resolution goes through
+ * resolveInstance — the same priority chain every lifecycle command uses
+ * (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * `--name` has no default; every invocation must resolve via one of the
+ * above paths.
  */
 import type { Command } from 'commander';
 export declare function registerOrchestratorStop(orchestrator: Command): void;

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

@@ -1,8 +1,12 @@
 /**
  * `kici-admin orchestrator uninstall` command.
  *
- * Removes the orchestrator service registration.
- * Preserves config files, database, and logs per user decision.
+ * Removes the orchestrator service registration. Target resolution goes
+ * through resolveInstance — the same priority chain every lifecycle command
+ * uses (--instance-dir > --name > CWD manifest > refusal with candidate list).
+ * The manifest stays on disk so subsequent commands can still reference the
+ * deploy folder; the host-wide index entry is dropped unconditionally so a
+ * stale row never lingers after the unit is gone.
  */
 import type { Command } from 'commander';
 export declare function registerOrchestratorUninstall(orchestrator: Command): void;

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

@@ -6,6 +6,15 @@
  * - Updates symlink (Unix) or service registration (Windows) atomically
  * - Preserves old versions for rollback
  * - Supports --cleanup and --rollback flags
+ *
+ * Targeting is folder-anchored: the resolution priority is
+ *   1. `--instance-dir <path>`
+ *   2. `--name <name>`
+ *   3. CWD manifest (`./.kici-orchestrator.json`)
+ *   4. otherwise refuses with a candidate-list error.
+ *
+ * `--name` no longer has a default — every invocation must resolve via one
+ * of the above paths.
  */
 import type { Command } from 'commander';
 export declare function registerUpgradeCommand(parent: Command): void;

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

@@ -7,13 +7,20 @@
  * - Preserve old versions for rollback
  * - Optional cleanup of old versions
  */
-import { type ServicePlatform } from '../../service/index.js';
+import { type ResolvedInstance, type ServiceManager, type ServicePlatform } from '../../service/index.js';
+import type { ServiceConfig } from '../../service/types.js';
 /** Component types that can be upgraded. */
 type UpgradeComponent = 'orchestrator' | 'agent';
 /** Options for the versioned upgrade command. */
 interface VersionedUpgradeOptions {
     platform?: ServicePlatform;
-    name: string;
+    /**
+     * Service name. No default — targeting flows through {@link resolveInstance}
+     * which consumes `name`, `instanceDir`, or the CWD manifest in priority order.
+     */
+    name?: string;
+    /** Deploy folder of the instance to upgrade. */
+    instanceDir?: string;
     from?: string;
     url?: string;
     version?: string;
@@ -22,6 +29,51 @@ interface VersionedUpgradeOptions {
     rollback?: boolean;
     force?: boolean;
 }
+/**
+ * Resolved upgrade target: the manifest-backed ServiceConfig the upgrade
+ * flow operates on, the manifest's installBase (NOT re-derived from name),
+ * and the underlying resolved instance for downstream writes.
+ */
+export interface UpgradeTarget {
+    config: ServiceConfig;
+    installBase: string;
+    resolvedInstance: ResolvedInstance;
+}
+/**
+ * Resolve the upgrade target via the folder-anchored model and build the
+ * ServiceConfig + installBase the rest of the upgrade flow needs.
+ *
+ * Priority chain (delegated to {@link resolveInstance}):
+ *   1. `opts.instanceDir` — read manifest at that path.
+ *   2. `opts.name`        — match against listInstances() output.
+ *   3. CWD manifest       — read `./.kici-<component>.json`.
+ *   4. otherwise          — refuse with a candidate-list error.
+ *
+ * The returned `installBase` comes from the manifest, NEVER re-derived from
+ * the service name. Instances installed with a non-default base must
+ * continue to resolve to that base on upgrade.
+ */
+export declare function resolveUpgradeTarget(args: {
+    component: UpgradeComponent;
+    opts: {
+        instanceDir?: string;
+        name?: string;
+    };
+    manager: ServiceManager;
+    isUserLevel: boolean;
+    kiciRoot: string;
+}): Promise<UpgradeTarget>;
+/**
+ * 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:
+ *   - systemd / compose: /opt/kici/<name>/
+ *   - launchd:           /usr/local/kici/<name>/
+ *   - windows:           C:\Program Files\KiCI\<name>\
+ */
+export declare function getInstallBase(platform: ServicePlatform, name: string): string;
 /**
  * Perform a versioned directory upgrade for a KiCI component.
  *

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

@@ -6,10 +6,10 @@
  * a container-based service management backend that works on any
  * platform with Docker or Podman installed.
  */
-import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions } from './types.js';
+import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance } from './types.js';
 export declare class ComposeServiceManager implements ServiceManager {
     private runtime;
-    /** Get the runtime command, detecting it if not already done. */
+    /** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
     private getRuntime;
     /** Run a compose command for the given service config. */
     private runCompose;
@@ -21,5 +21,6 @@ export declare class ComposeServiceManager implements ServiceManager {
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
+    list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
 }
 //# sourceMappingURL=compose.d.ts.map

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

@@ -8,8 +8,14 @@
  */
 export type { ServiceManager, ServiceConfig, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
 export { DEFAULT_RESTART_POLICY } from './types.js';
-export { detectPlatform, isRoot, getConfigDir, getLogDir, getCacheDir } from './platform-detect.js';
+export { detectPlatform, isRoot, kiciConfigRoot, getConfigDir, getLogDir, getCacheDir, } from './platform-detect.js';
 export { resolveUserLevel, type PrivilegeOpts } from './privilege.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, } from './instance/manifest.js';
+export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
+export { listInstances, resolveInstance, formatRefusal } from './instance/resolve.js';
+export type { ListedInstance, ResolveArgs, ListInstancesArgs } from './instance/resolve.js';
 import type { ServiceManager, ServicePlatform } from './types.js';
 /**
  * Create a ServiceManager for the given platform.

package/dist/cli/service/instance/index-file.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Instance index — a reconciled CACHE of all installed instances on the host.
+ *
+ * Lives at <kiciRoot>/instances.json, where kiciRoot is the name-agnostic
+ * config root (~/.config/kici/ for user-level, /etc/kici/ for system). The
+ * index is convenience: discovery is authoritative against the init system
+ * (see resolve.ts#listInstances which reconciles this file against scans).
+ *
+ * Corrupt index → warn and treat as empty; the next install/uninstall
+ * rewrites it cleanly.
+ */
+import type { Component, IndexEntry } from './types.js';
+/** Resolve <kiciRoot>/instances.json. */
+export declare function indexPath(kiciRoot: string): string;
+/** Read the index. Missing or corrupt → []. */
+export declare function readIndex(kiciRoot: string): IndexEntry[];
+/** Overwrite the index. */
+export declare function writeIndex(kiciRoot: string, entries: IndexEntry[]): void;
+/**
+ * Append an entry. Idempotent for an exact (component,name,instanceDir) match.
+ * Throws on a (component,name) collision with a different instanceDir — the
+ * caller must use a different name or pass --force to overwrite.
+ */
+export declare function appendIndexEntry(kiciRoot: string, entry: IndexEntry): void;
+/** Remove the matching entry (no-op when absent). */
+export declare function removeIndexEntry(kiciRoot: string, key: {
+    component: Component;
+    name: string;
+}): void;
+//# sourceMappingURL=index-file.d.ts.map

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

@@ -0,0 +1,30 @@
+/**
+ * Instance manifest — the single source of truth for a folder-anchored
+ * service install. Written by `install` into the deploy folder, read by
+ * every lifecycle command to reconstruct the ServiceConfig.
+ */
+import type { Component, InstanceManifest } from './types.js';
+/** Per-component manifest filename. */
+export declare function manifestFilename(component: Component): string;
+/** Resolve the manifest path inside an instance directory. */
+export declare function manifestPath(instanceDir: string, component: Component): string;
+/**
+ * Read the manifest for `component` from `instanceDir`.
+ * Returns null when the file does not exist; throws on parse or schema errors.
+ */
+export declare function readManifest(instanceDir: string, component: Component): InstanceManifest | null;
+/**
+ * Write the manifest for `manifest.component` into `instanceDir`.
+ * Returns the full path written.
+ */
+export declare function writeManifest(instanceDir: string, manifest: InstanceManifest): string;
+/**
+ * Read the running kici-admin's version from the orchestrator package.json.
+ *
+ * `process.env.npm_package_version` is only populated under `npm run` and is
+ * undefined when kici-admin runs as a globally-installed binary, which is the
+ * actual install path. Reading from the package.json on disk is the only
+ * reliable source.
+ */
+export declare function readKiciVersion(): string;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * resolveInstance — the single entry point every lifecycle command uses to
+ * decide which installed service it's operating on.
+ *
+ * Priority:
+ *   1. --instance-dir <path>       → read manifest at <path>
+ *   2. --name <name>               → match against listInstances() result
+ *   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
+ * the index to self-heal stale entries.
+ */
+import type { DiscoveredInstance, ServiceManager } 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';
+}
+export interface ListInstancesArgs {
+    component: Component;
+    isUserLevel: boolean;
+    kiciRoot: string;
+    manager: ServiceManager;
+}
+/**
+ * Reconcile <kiciRoot>/instances.json with the driver's native scan, then
+ * rewrite the index dropping entries whose units no longer exist. Returns
+ * the merged list filtered to the requested component + isUserLevel.
+ */
+export declare function listInstances(args: ListInstancesArgs): Promise<ListedInstance[]>;
+export interface ResolveArgs {
+    component: Component;
+    opts: ResolveOptions;
+    cwd: string;
+    kiciRoot: string;
+    manager: 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.
+     */
+    isUserLevel: boolean;
+}
+/**
+ * Resolve the target instance for the current lifecycle invocation.
+ * Throws with a refusal/candidate-listing error 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;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+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.
+ */
+export interface InstanceManifest {
+    component: Component;
+    name: string;
+    platform: ServicePlatform;
+    isUserLevel: boolean;
+    envFilePath: string;
+    configDir: string;
+    logDir: string;
+    installBase: string;
+    createdAt: string;
+    kiciVersion: string;
+}
+/** A row in `<kiciRoot>/instances.json`. */
+export interface IndexEntry {
+    component: Component;
+    name: string;
+    platform: ServicePlatform;
+    isUserLevel: boolean;
+    instanceDir: string;
+}
+/** CLI options that influence target resolution. */
+export interface ResolveOptions {
+    instanceDir?: string;
+    name?: string;
+}
+/** Fully-resolved target — what `resolveInstance` returns. */
+export interface ResolvedInstance {
+    manifest: InstanceManifest;
+    manifestPath: string;
+    instanceDir: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -5,7 +5,7 @@
  * Supports both system-level (/Library/LaunchDaemons/) and
  * user-level (~/Library/LaunchAgents/) agents.
  */
-import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
+import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions, DiscoveredInstance } from './types.js';
 export declare class LaunchdServiceManager implements ServiceManager {
     /** Build the launchd label for a service. */
     private label;
@@ -42,6 +42,23 @@ export declare class LaunchdServiceManager implements ServiceManager {
     /** Is the service 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
+     * 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.
+     */
+    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. If a stale instance
+     * reappears between attempts, it is booted out before the next try.
+     */
+    private bootstrapWithRetry;
     uninstall(config: ServiceConfig): Promise<void>;
     start(config: ServiceConfig): Promise<void>;
     stop(config: ServiceConfig): Promise<void>;
@@ -49,5 +66,6 @@ export declare class LaunchdServiceManager implements ServiceManager {
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
+    list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
 }
 //# sourceMappingURL=launchd.d.ts.map

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

@@ -25,7 +25,8 @@ export declare function detectPlatform(override?: ServicePlatform): ServicePlatf
  */
 export declare function isRoot(): boolean;
 /**
- * Get the configuration directory for a KiCI service.
+ * 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/
@@ -33,18 +34,37 @@ export declare function isRoot(): boolean;
  * - 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}.
  */
-export declare function getConfigDir(_serviceName: string, isUserLevel: boolean): string;
+export declare function kiciConfigRoot(isUserLevel: boolean): string;
 /**
- * Get the log directory for a KiCI service.
+ * Get the configuration directory for a specific KiCI service instance.
  *
- * Paths follow platform conventions:
- * - System Linux/macOS: /var/log/kici/
- * - User Linux: ~/.local/share/kici/logs/
- * - User macOS: ~/Library/Logs/kici/
- * - Windows: C:\ProgramData\kici\logs\
+ * 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>\
+ */
+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\
  */
-export declare function getLogDir(_serviceName: string, isUserLevel: boolean): string;
+export declare function getLogDir(serviceName: string, isUserLevel: boolean): string;
 /**
  * Get the cache directory for lazy dependency downloads.
  *

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

@@ -5,7 +5,7 @@
  * journalctl, and loginctl commands. Supports both system-level
  * (/etc/systemd/system/) and user-level (~/.config/systemd/user/) services.
  */
-import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
+import type { DiscoveredInstance, ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
 /**
  * Check whether linger is already enabled for a user.
  *
@@ -37,5 +37,6 @@ export declare class SystemdServiceManager implements ServiceManager {
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
+    list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
 }
 //# sourceMappingURL=systemd.d.ts.map