@kici-dev/orchestrator 0.1.17 → 0.1.19

package/dist/agent/dispatcher.d.ts

@@ -150,6 +150,15 @@ export declare class Dispatcher {
      * 4. If queue full: return 'rejected'.
      */
     dispatch(job: QueuedJobInput): Promise<DispatchResult>;
+    /**
+     * Dispatch a host-fanout pinned child. The job targets exactly
+     * `job.pinnedAgentId`: if that agent is locally connected, satisfies the
+     * runsOn/exclude/mandatory gate, and has capacity, dispatch immediately;
+     * otherwise queue it WITH the pin so the pin-aware drain delivers it when the
+     * agent frees up or (re)connects. A pinned job never falls through to a
+     * different agent.
+     */
+    private dispatchPinned;
     /**
      * Eagerly dispatch a specific bound job to a freshly-registered
      * scaler-managed agent.

package/dist/agent/host-roster-reaper.d.ts

@@ -0,0 +1,42 @@
+import type { HostRosterStore } from './host-roster.js';
+export interface HostRosterReaperOptions {
+    store: Pick<HostRosterStore, 'reapEphemeralPastTtl' | 'countStaticUnreachable'>;
+    ttlMs: number;
+    /** Grace window for the connected-but-stale case in `countStaticUnreachable`. */
+    graceMs: number;
+    scanIntervalMs: number;
+    /** Setter for the `kici_orch_declared_hosts_unreachable` gauge. */
+    setUnreachableGauge: (value: number) => void;
+}
+/**
+ * Leader-only host-roster reaper.
+ *
+ * Modeled on `EventRetryScanner`: started/stopped via the Raft leadership
+ * callbacks, a single timer cleared on `stop()`. Each leader tick it:
+ *
+ * - DELETEs `ephemeral` host_roster rows whose `last_seen` is older than the ttl
+ *   (scaled-down autoscale agents — silent GC, no alarm); and
+ * - counts `static` (declared) hosts whose derived status is `unreachable` and
+ *   publishes that count to the `kici_orch_declared_hosts_unreachable` gauge, so
+ *   a Mimir ruler alert can page an operator when a declared box goes dark.
+ *
+ * `static` unreachability is read-derived by `deriveHostStatus` (no write here),
+ * so the reaper never deletes a static row. Followers never run the reaper, so
+ * the gauge series exists only on the leader (the alert uses `max by ()`).
+ */
+export declare class HostRosterReaper {
+    private readonly store;
+    private readonly ttlMs;
+    private readonly graceMs;
+    private readonly scanIntervalMs;
+    private readonly setUnreachableGauge;
+    private timer;
+    private isLeader;
+    constructor(opts: HostRosterReaperOptions);
+    onBecomeLeader(): void;
+    onLoseLeadership(): void;
+    stop(): void;
+    /** One reap pass. Public for tests. */
+    tick(): Promise<void>;
+}
+//# sourceMappingURL=host-roster-reaper.d.ts.map

package/dist/agent/host-roster.d.ts

@@ -0,0 +1,110 @@
+import { type Kysely } from 'kysely';
+import { type LabelMatcher } from '@kici-dev/engine';
+import type { Database, HostRosterRow } from '../db/types.js';
+/**
+ * Derived (read-time) status of a roster host. Never a stored mutable column:
+ * status is computed from the shared `last_seen` + `connected_instance_id` so
+ * every cluster instance agrees regardless of which one holds the live WS.
+ */
+export declare enum HostStatus {
+    /** Connected to some instance AND heartbeat fresh. */
+    ready = "ready",
+    /** Static host that is not currently live (declared, rebooting, or gone). */
+    unreachable = "unreachable",
+    /** Ephemeral host past ttl but not yet reaped (scaled down). */
+    stale = "stale"
+}
+/** The lifecycle class snapshot from the auth token's `agent_type`. */
+export type LifecycleClass = 'static' | 'ephemeral';
+/**
+ * A roster host that matched a `runsOnAll` predicate, with its derived status.
+ * The host-fanout resolver consumes this: `ready` hosts become pinned children;
+ * `unreachable` static hosts are subject to the `onUnreachable` policy; `stale`
+ * ephemeral hosts are skipped.
+ */
+export interface MatchedHost {
+    agentId: string;
+    /** Hostname (falls back to agentId). */
+    host: string;
+    labels: string[];
+    lifecycleClass: LifecycleClass;
+    /** Which orchestrator holds the live WS (null = disconnected). For the cross-cluster pin. */
+    connectedInstanceId: string | null;
+    status: HostStatus;
+    platform: string | null;
+    arch: string | null;
+}
+export interface UpsertHostInput {
+    agentId: string;
+    tokenId: string | null;
+    lifecycleClass: LifecycleClass;
+    labels: string[];
+    hostname: string | null;
+    platform: string;
+    arch: string;
+    instanceId: string;
+}
+/** Minimal row shape `deriveHostStatus` reads (the store row or the CLI row). */
+export interface HostStatusRow {
+    connected_instance_id: string | null;
+    lifecycle_class: string;
+    last_seen: Date | string;
+}
+/**
+ * The ONE status-derivation function — used by the store and the kici-admin
+ * host CLI. `ready` requires the host to be genuinely live (connected to some
+ * instance AND heartbeat fresh — the freshness check catches a crashed
+ * instance that never cleared `connected_instance_id`). It never returns
+ * `ready` for a not-currently-live host: a not-live `static` reads
+ * `unreachable` (the declared-but-absent alarm), a not-live `ephemeral` reads
+ * `stale` (scaled down, awaiting reap).
+ */
+export declare function deriveHostStatus(row: HostStatusRow, nowMs: number, graceMs: number): HostStatus;
+/**
+ * Durable, cluster-shared roster of every agent the cluster has ever enrolled.
+ *
+ * The in-memory `AgentRegistry` reconciles into this table on register
+ * (`upsert`) / unregister (`markDisconnected`), with a coarse heartbeat
+ * (`stampLastSeen`). All liveness writes are owner-guarded by `instanceId` so a
+ * stale disconnect from an old instance can never clobber a row a different
+ * instance now owns. The leader-only reaper deletes `ephemeral` rows past their
+ * ttl via `reapEphemeralPastTtl`; `static` rows persist and read `unreachable`.
+ */
+export declare class HostRosterStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /** Idempotent upsert on agent_id; stamps connected_instance_id + last_seen. */
+    upsert(input: UpsertHostInput): Promise<void>;
+    /** Clear liveness on disconnect — but only if THIS instance still owns it. */
+    markDisconnected(agentId: string, instanceId: string): Promise<void>;
+    /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
+    stampLastSeen(agentId: string, instanceId: string): Promise<void>;
+    /** Operator pre-declare of a static host before its agent dials in. */
+    declareStatic(input: {
+        agentId: string;
+        labels: string[];
+        hostname?: string;
+    }): Promise<void>;
+    get(agentId: string): Promise<HostRosterRow | null>;
+    listAll(): Promise<HostRosterRow[]>;
+    /**
+     * Resolve every roster host matching a `runsOnAll` predicate (OR-of-AND
+     * include groups, minus exclude labels), tagged with its derived status. This
+     * is the host-fanout resolver: it returns declared-but-absent static hosts
+     * (status `unreachable`) so the caller can apply `onUnreachable` — the live
+     * registry alone cannot name an expected-but-absent host.
+     */
+    findMatching(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
+    /**
+     * Count `static` (declared) hosts whose derived status is `unreachable` —
+     * the "declared-but-absent" alarm population. Reuses the single-source
+     * {@link deriveHostStatus} so the count never diverges from what
+     * `kici-admin host list` shows. A not-currently-connected static host reads
+     * `unreachable` regardless of grace (only the connected-but-stale case
+     * depends on `graceMs`).
+     */
+    countStaticUnreachable(graceMs: number): Promise<number>;
+    /** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
+    reapEphemeralPastTtl(ttlMs: number): Promise<number>;
+}
+//# sourceMappingURL=host-roster.d.ts.map

package/dist/agent/registry.d.ts

@@ -8,6 +8,7 @@
  *
  * No persistence needed -- agents re-register on reconnect.
  */
+import { type LabelMatcher } from '@kici-dev/engine';
 import type { WsLike } from '@kici-dev/engine';
 export type { WsLike } from '@kici-dev/engine';
 /**
@@ -76,6 +77,13 @@ export interface AgentEntry {
     memoryUsedMb: number | null;
     memoryAvailableMb: number | null;
     uptimeSeconds: number | null;
+    /**
+     * The auth token's `agent_type` (`'static'` | `'ephemeral'`) snapshot, or
+     * `null` when auth mode is `none`. Drives the host roster's
+     * `lifecycle_class` — `static` rows persist + alarm on absence, `ephemeral`
+     * rows are GC'd past their ttl.
+     */
+    tokenAgentType: 'static' | 'ephemeral' | null;
 }
 /** Optional static metadata from the agent.register message. */
 interface AgentMetadata {
@@ -106,6 +114,36 @@ interface AgentMetadata {
      * scaler registration metadata.
      */
     scalerManaged?: boolean;
+    /**
+     * The auth token's `agent_type` (`'static'` | `'ephemeral'`), threaded from
+     * `agent-handler.ts` so the host roster can snapshot it as the row's
+     * `lifecycle_class`. `null` / undefined when auth mode is `none`.
+     */
+    tokenAgentType?: 'static' | 'ephemeral' | null;
+}
+/**
+ * Subset of `HostRosterStore` the registry reconciles into. Optional — when no
+ * store is injected (e.g. workers, which have no DB), the reconcile hooks are
+ * a no-op and the in-memory registry behaves exactly as before.
+ */
+export interface RosterReconciler {
+    upsert(input: {
+        agentId: string;
+        tokenId: string | null;
+        lifecycleClass: 'static' | 'ephemeral';
+        labels: string[];
+        hostname: string | null;
+        platform: string;
+        arch: string;
+        instanceId: string;
+    }): Promise<void>;
+    markDisconnected(agentId: string, instanceId: string): Promise<void>;
+    stampLastSeen(agentId: string, instanceId: string): Promise<void>;
+}
+/** Optional dependencies that enable host-roster reconciliation. */
+export interface AgentRegistryDeps {
+    rosterStore?: RosterReconciler;
+    instanceId?: string;
 }
 export declare class AgentRegistry {
     /** Primary: agentId -> AgentEntry */
@@ -143,6 +181,24 @@ export declare class AgentRegistry {
      * propagation path to in-flight WS connections.
      */
     private readonly tokenExpiryTimers;
+    /**
+     * Per-agent last roster `last_seen` stamp time (epoch ms). Throttles the
+     * coarse heartbeat write so we don't issue a DB write per agent per
+     * heartbeat — `grace`/`ttl` are minute-scale, so a throttled stamp is
+     * sufficient. Cleaned up alongside the agent in `removeFromIndexes`.
+     */
+    private readonly lastRosterStampAt;
+    /** Minimum interval between coarse roster `last_seen` stamps per agent. */
+    private readonly ROSTER_STAMP_THROTTLE_MS;
+    /** Optional host-roster reconciler + this instance's id (see AgentRegistryDeps). */
+    private readonly rosterStore?;
+    private readonly instanceId?;
+    /**
+     * The roster reconcile seam is optional: when no store is injected (workers
+     * with no DB, unit tests), every reconcile hook is a no-op and the in-memory
+     * registry behaves exactly as before.
+     */
+    constructor(deps?: AgentRegistryDeps);
     /**
      * Register an agent. If the agentId already exists, updates the existing
      * entry (agent reconnection scenario).
@@ -209,7 +265,14 @@ export declare class AgentRegistry {
      * @param requiredLabels - All labels the agent must have (intersection semantics).
      * @returns Array of matching available AgentEntry objects.
      */
-    findAvailable(requiredLabels: string[], excludeLabels?: string[]): AgentEntry[];
+    findAvailable(requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[]): AgentEntry[];
+    /**
+     * Whether a specific agent satisfies the same label / exclude / mandatory
+     * gate `findAvailable` applies per-agent, ignoring capacity. Used by the
+     * host-fanout pin to verify the resolved agent still matches before pinning
+     * (guards against roster label drift between resolution and dispatch).
+     */
+    agentSatisfies(agent: AgentEntry, requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[]): boolean;
     /**
      * Check if ANY registered agent matches the required labels, regardless of capacity.
      * Used to decide whether to queue (agent exists but busy) vs reject (no agent at all).
@@ -221,7 +284,7 @@ export declare class AgentRegistry {
      * an off-gate gated agent as "matching but busy" and skip the peer
      * reroute path even though the local agent can never accept the job.
      */
-    hasMatchingAgent(requiredLabels: string[], excludeLabels?: string[]): boolean;
+    hasMatchingAgent(requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[]): boolean;
     /**
      * Internal helper: intersect the per-label candidate sets to find agentIds
      * that satisfy `requiredLabels`. Returns `null` when any required label

package/dist/app.d.ts

@@ -16,6 +16,7 @@ import type { Kysely } from 'kysely';
 import type pg from 'pg';
 import { type ColdStore } from '@kici-dev/shared';
 import type { AppConfig } from './config.js';
+import type { HostRosterStore } from './agent/host-roster.js';
 import type { Database } from './db/types.js';
 import type { AgentRegistry } from './agent/registry.js';
 import type { Dispatcher } from './agent/dispatcher.js';
@@ -81,6 +82,8 @@ export interface AppDependencies {
     db: Kysely<Database>;
     pool: pg.Pool;
     registry: AgentRegistry;
+    /** Host roster store for runsOnAll fan-out resolution. */
+    hostRosterStore?: HostRosterStore;
     dispatcher: Dispatcher;
     jobQueue: JobQueue;
     dedup: DedupCache;

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

@@ -0,0 +1,13 @@
+/**
+ * Host roster management commands for kici-admin (orchestrator data plane).
+ *
+ *   host list      List all roster hosts with derived status
+ *   host get       Show one roster host
+ *   host declare   Pre-declare a static host before its agent connects
+ *
+ * Reads/writes the orchestrator DB directly (via withDb), so this lives in
+ * kici-admin — never in the public `kici` or the Platform `kici-platform-admin`.
+ */
+import type { Command } from 'commander';
+export declare function registerHostCommands(program: Command): void;
+//# sourceMappingURL=host.d.ts.map

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

@@ -99,6 +99,29 @@ export declare function resolveNpmSourceVersion(opts: {
     requested: string | undefined;
     running: string;
 }): string;
+/** Verdict from {@link verifyNpmSourceLaunch}. */
+export type NpmSourceLaunchVerdict = {
+    ok: true;
+    version: string;
+    manifestVersion: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether an npm-source upgrade may proceed, given the version the
+ * invoking CLI is (`invoked`) and the version the installed unit will actually
+ * launch (`launched`, or null when unresolvable — e.g. an opaque --binary
+ * install). On success `manifestVersion` is the value to persist (null = leave
+ * the manifest's kiciVersion unchanged because we couldn't verify it).
+ */
+export declare function verifyNpmSourceLaunch(opts: {
+    component: UpgradeComponent;
+    invoked: string;
+    launched: string | null;
+    launchedPath: string | null;
+    force: boolean;
+}): NpmSourceLaunchVerdict;
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions): Promise<void>;
 export {};
 //# sourceMappingURL=versioned-upgrade.d.ts.map

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

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

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

@@ -6,13 +6,13 @@
  * specified) platform. Uses dynamic imports to avoid loading all
  * platform-specific code on every platform.
  */
-export type { ServiceManager, ServiceConfig, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
+export type { ServiceManager, ServiceConfig, LaunchSpec, ServiceStatus, ServiceState, ServicePlatform, RestartPolicy, LogOptions, } from './types.js';
 export { DEFAULT_RESTART_POLICY } from './types.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 { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, } 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';

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

@@ -4,6 +4,7 @@
  * every lifecycle command to reconstruct the ServiceConfig.
  */
 import type { Component, InstanceManifest } from './types.js';
+import type { LaunchSpec } from '../types.js';
 /** Per-component manifest filename. */
 export declare function manifestFilename(component: Component): string;
 /** Resolve the manifest path inside an instance directory. */
@@ -27,4 +28,15 @@ export declare function writeManifest(instanceDir: string, manifest: InstanceMan
  * reliable source.
  */
 export declare function readKiciVersion(): string;
+/**
+ * Resolve the `@kici-dev/<component>` package version that a {@link LaunchSpec}
+ * will actually execute, by locating the component's entry script among the
+ * spec's tokens and reading the version from the package.json that owns it.
+ *
+ * Returns null when no resolvable entry script is present (e.g. an opaque
+ * `--binary` install) or the owning package.json is missing / name-mismatched.
+ * This is what lets the npm-source upgrade refuse to report a version it can't
+ * stand behind.
+ */
+export declare function resolveVersionFromLaunchSpec(spec: LaunchSpec, component: Component): string | null;
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -27,8 +27,18 @@ export interface ListInstancesArgs {
 }
 /**
  * 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.
+ * 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
+ *     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.
+ *
+ * The init system is therefore the source of truth for the name→folder mapping
+ * (via the X-KiCI-InstanceDir / KiCIInstanceDir / dev.kici.instance-dir / [KiCI-DIR]
+ * markers), and the index is a pure cache. Returns the merged list filtered to
+ * the requested component + isUserLevel.
  */
 export declare function listInstances(args: ListInstancesArgs): Promise<ListedInstance[]>;
 export interface ResolveArgs {

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, DiscoveredInstance } from './types.js';
+import type { ServiceConfig, ServiceManager, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
 export declare class LaunchdServiceManager implements ServiceManager {
     /** Build the launchd label for a service. */
     private label;
@@ -17,6 +17,8 @@ export declare class LaunchdServiceManager implements ServiceManager {
     private parseEnvFile;
     /** Escape XML special characters. */
     private escapeXml;
+    /** Inverse of {@link escapeXml} — decode the entities back to literals. */
+    private unescapeXml;
     /**
      * Generate a launchd plist XML string from a service config.
      * Visible for testing.
@@ -67,5 +69,6 @@ export declare class LaunchdServiceManager implements ServiceManager {
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
+    readLaunchSpec(config: ServiceConfig): Promise<LaunchSpec | null>;
 }
 //# sourceMappingURL=launchd.d.ts.map

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

@@ -37,6 +37,11 @@ export declare function isRoot(): boolean;
  *
  * Used by the instance index (`<kiciRoot>/instances.json`) which lives
  * outside any per-instance subdir, and as the base for {@link getConfigDir}.
+ *
+ * `KICI_CONFIG_ROOT` overrides the platform default for both privilege scopes.
+ * It exists so a test harness (or a sandboxed run) can point the instance index
+ * at an isolated directory instead of sharing the host's `~/.config/kici/` —
+ * which otherwise lets concurrent installs clobber each other's index.
  */
 export declare function kiciConfigRoot(isUserLevel: boolean): string;
 /**

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 { DiscoveredInstance, ServiceConfig, ServiceManager, ServiceStatus, LogOptions } from './types.js';
+import type { DiscoveredInstance, ServiceConfig, ServiceManager, ServiceStatus, LogOptions, LaunchSpec } from './types.js';
 /**
  * Check whether linger is already enabled for a user.
  *
@@ -37,6 +37,7 @@ export declare class SystemdServiceManager implements ServiceManager {
     status(config: ServiceConfig): Promise<ServiceStatus>;
     logs(config: ServiceConfig, options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
+    readLaunchSpec(config: ServiceConfig): Promise<LaunchSpec | null>;
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
 }
 //# sourceMappingURL=systemd.d.ts.map

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

@@ -68,6 +68,28 @@ export interface ServiceConfig {
      * Optional during lifecycle ops that don't regenerate the unit; required on install.
      */
     component?: 'orchestrator' | 'agent';
+    /**
+     * The deploy folder that holds this instance's manifest. Embedded in the unit
+     * (X-KiCI-InstanceDir for systemd, KiCIInstanceDir for launchd,
+     * dev.kici.instance-dir for compose, a description suffix for Windows) so
+     * per-driver `list()` scans can recover the deploy folder straight from the
+     * init system — making the instance index a true rebuildable cache rather
+     * than the sole source of the name→folder mapping.
+     *
+     * Optional during lifecycle ops that don't regenerate the unit; set on install.
+     */
+    instanceDir?: string;
+}
+/**
+ * The launch command an installed init unit will actually execute, parsed
+ * back out of the unit/plist/service registration. `execPath` is the binary
+ * the init system runs (for a Node-launched server, the node binary); `args`
+ * are everything after it (for a Node-launched server, the resolved entry
+ * script path). Returned by {@link ServiceManager.readLaunchSpec}.
+ */
+export interface LaunchSpec {
+    execPath: string;
+    args: string[];
 }
 /** Current state of a service. */
 export type ServiceState = 'running' | 'stopped' | 'failed' | 'unknown';
@@ -101,6 +123,12 @@ export interface DiscoveredInstance {
     isUserLevel: boolean;
     /** The component this unit belongs to, decoded from the unit's KiCI marker. */
     component: 'orchestrator' | 'agent';
+    /**
+     * The deploy folder recovered from the unit's KiCI instance-dir marker, when
+     * the unit carries one. Undefined for units installed before the marker
+     * existed (the index cache remains the fallback for those).
+     */
+    instanceDir?: string;
 }
 /**
  * Interface that all platform-specific service managers must implement.
@@ -134,5 +162,14 @@ export interface ServiceManager {
      * (systemd, launchd); ignored on Windows/compose.
      */
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
+    /**
+     * Read the launch command the installed unit will actually execute, parsed
+     * back out of the init system's own record (systemd ExecStart, launchd
+     * ProgramArguments, windows service binPath). Returns null when the unit is
+     * not installed, its launch spec can't be parsed, or the platform has no
+     * node-launched entry to resolve (compose). Used by the npm-source upgrade to
+     * verify the version that will run before reporting success.
+     */
+    readLaunchSpec(config: ServiceConfig): Promise<LaunchSpec | null>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -6,7 +6,7 @@
  * dependency on first use. Service configuration (auto-start, recovery)
  * is handled via sc.exe.
  */
-import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance } from './types.js';
+import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
 export declare class WindowsServiceManager implements ServiceManager {
     install(config: ServiceConfig): Promise<void>;
     uninstall(config: ServiceConfig): Promise<void>;
@@ -17,5 +17,6 @@ export declare class WindowsServiceManager implements ServiceManager {
     logs(config: ServiceConfig, _options: LogOptions): Promise<void>;
     isInstalled(config: ServiceConfig): Promise<boolean>;
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
+    readLaunchSpec(config: ServiceConfig): Promise<LaunchSpec | null>;
 }
 //# sourceMappingURL=windows.d.ts.map