@kici-dev/orchestrator 0.1.16 → 0.1.18

package/dist/agent/dispatcher.d.ts

@@ -55,6 +55,13 @@ export declare class Dispatcher {
     private readonly agentJobs;
     /** Reverse map: jobId -> agentId, for cancel-run lookups. */
     private readonly jobToAgent;
+    /**
+     * jobId -> runId for currently-tracked jobs. Populated alongside
+     * `jobToAgent`/`agentJobs` at dispatch time and cleared with them, so the
+     * provenance token relay can resolve a job's runId from the dispatcher's own
+     * state (`resolveOwnedJob`) rather than trusting an agent-asserted value.
+     */
+    private readonly jobRunIds;
     /**
      * Grace window for recently completed jobs.
      * Allows late messages (log.chunk, step.status) to be accepted for a short
@@ -143,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.
@@ -296,7 +312,7 @@ export declare class Dispatcher {
      * reconnecting agent reporting the job in-flight means it had started,
      * so mark it started for disconnect triage.
      */
-    restoreJobForAgent(agentId: string, jobId: string): void;
+    restoreJobForAgent(agentId: string, jobId: string, runId?: string): void;
     /**
      * Start a recovery timer for a job found in 'dispatched' state on startup.
      * Called by server.ts/standalone.ts to create recovery timers for jobs
@@ -349,6 +365,16 @@ export declare class Dispatcher {
     /** Remove expired entries from the completedJobs grace window map. */
     private cleanupExpiredGraceEntries;
     private trackJobForAgent;
+    /**
+     * Verify `agentId` currently owns `jobId`; if so, return the job's runId from
+     * the dispatcher's own tracking. Used by the provenance token relay so the
+     * orchestrator binds a minted token to a job the agent actually owns — the
+     * agent never asserts a runId. Returns `undefined` when the agent does not
+     * own the job (or the runId is no longer tracked).
+     */
+    resolveOwnedJob(agentId: string, jobId: string): {
+        runId: string;
+    } | undefined;
     /**
      * Cancel a queued job (mark as failed in the dispatch queue).
      * Used by the coordinator to clean up local fallback entries when a peer

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/approvals/apply-decision.d.ts

@@ -40,15 +40,25 @@ export interface ApplyDecisionDeps {
     allowSelfApproval: boolean;
     /** Resolve the Keycloak sub of the user who triggered a run (for the self-approval gate). */
     resolveTriggererSub: (runId: string) => Promise<string | undefined>;
-    /** Called when a job/workflow hold is released — re-dispatch the element. */
+    /** Called when a job hold is released — re-dispatch the element. */
     onJobRelease: (signal: ReleaseSignal) => Promise<void>;
     /** Called when a step hold is released — notify the waiting agent (approved). */
     onStepRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Called when a workflow-scoped hold is released (install gate approved) —
+     * rebuild the dispatch context and resume the workflow from the install gate.
+     */
+    onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
     /**
      * Called when a step-scoped hold is rejected — notify the waiting agent so it
      * fails the step instead of blocking until expiry. Carries the holdId.
      */
     onStepReject?: (heldRunId: string, reason?: string) => Promise<void> | void;
+    /**
+     * Called when a workflow-scoped hold is rejected (install gate rejected) —
+     * cancel the run and drop the pending workflow context. Carries the runId.
+     */
+    onWorkflowReject?: (runId: string) => Promise<void>;
 }
 /** Apply a single approve/reject decision to a hold. */
 export declare function applyDecision(deps: ApplyDecisionDeps, args: {

package/dist/cache/pending-inits.d.ts

@@ -12,6 +12,11 @@ export interface InitResult {
     environmentName?: string;
     env?: Record<string, string>;
     concurrencyGroup?: string;
+    /**
+     * Resolved matrix combinations when the target job's matrix is a dynamic
+     * function. The dispatch path re-materializes these into N execution jobs.
+     */
+    matrixValues?: Array<Record<string, string | undefined>>;
 }
 export declare class PendingInitTracker extends PendingTracker<InitResult> {
     constructor();

package/dist/cli/api-client.d.ts

@@ -25,6 +25,14 @@ export interface FleetTopologyResponse {
  * avoid a cross-package import in the CLI wire type.
  */
 export type GenericSourceGitConfigPayload = Record<string, unknown>;
+/**
+ * Wire shape for a local filesystem source's config (`{ repoBasePath, cloneUrlBase? }`).
+ * Matches `LocalSourceConfigSchema` in `providers/local/local-source-config.ts`.
+ */
+export interface GenericSourceLocalConfigPayload {
+    repoBasePath: string;
+    cloneUrlBase?: string;
+}
 /**
  * Response shape for generic webhook sources from the admin API.
  */
@@ -134,6 +142,7 @@ export declare class AdminApiClient {
         rateLimitRpm?: number;
         providerType?: string;
         gitConfig?: GenericSourceGitConfigPayload;
+        localConfig?: GenericSourceLocalConfigPayload;
     }): Promise<{
         source: GenericSourceResponse;
     }>;
@@ -159,6 +168,8 @@ export declare class AdminApiClient {
         providerType?: string;
         /** `null` clears the config; omit to leave unchanged. */
         gitConfig?: GenericSourceGitConfigPayload | null;
+        /** `null` clears the config; omit to leave unchanged. */
+        localConfig?: GenericSourceLocalConfigPayload | null;
     }): Promise<{
         source: GenericSourceResponse;
     }>;

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/local-hook.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Render the post-receive hook script. For each pushed ref the hook calls
+ * `kici-admin source trigger-local <id> --ref <ref> --sha <new> --base-url <url>`,
+ * so a push to any branch dispatches a run for that ref.
+ */
+export declare function renderPostReceiveHook(opts: {
+    sourceId: string;
+    baseUrl: string;
+}): string;
+/**
+ * Write the rendered hook into the repo's `.git/hooks/post-receive` and make it
+ * executable. Throws when the path is not a git repo (no `.git/hooks` dir).
+ */
+export declare function installPostReceiveHook(repoPath: string, script: string): string;
+//# sourceMappingURL=local-hook.d.ts.map

package/dist/cli/commands/local-trigger.d.ts

@@ -0,0 +1,24 @@
+export interface LocalTriggerInput {
+    orgId: string;
+    sourceId: string;
+    repoFullName: string;
+    event: 'push' | 'pull_request';
+    ref: string;
+    sha: string;
+    defaultBranch: string;
+}
+export interface LocalTriggerRequest {
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+}
+/** Build the GitHub-shaped webhook request the local provider normalizer expects. */
+export declare function buildLocalTriggerRequest(input: LocalTriggerInput): LocalTriggerRequest;
+/** Read HEAD ref + sha from a local git repo (used when the operator omits --ref/--sha). */
+export declare function readRepoHead(repoPath: string): {
+    ref: string;
+    sha: string;
+};
+/** POST the trigger request to the orchestrator base URL. Returns the HTTP status. */
+export declare function sendLocalTrigger(baseUrl: string, req: LocalTriggerRequest): Promise<number>;
+//# sourceMappingURL=local-trigger.d.ts.map

package/dist/cli/commands/remote-source.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Remote-source inspection command for kici-admin.
+ *
+ * Subcommand namespace: `kici-admin remote-source show`.
+ *
+ * The remote-source anchor (`remote_sources` table) maps the deterministic
+ * routing key `remote:<orgId>` to the orchestrator's canonical org id so a
+ * Platform-relayed `kici run remote` resolves the real tenant. It is
+ * auto-provisioned on Platform auth; this command lets an operator inspect or
+ * confirm the row when debugging org-anchor issues on a hidden orchestrator.
+ *
+ * Reads the orchestrator DB directly (on-host operator inspection), so it stays
+ * usable even when Platform is unreachable.
+ */
+import type { Command } from 'commander';
+export declare function registerRemoteSourceCommands(program: Command): void;
+//# sourceMappingURL=remote-source.d.ts.map

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

@@ -85,6 +85,43 @@ export declare function getInstallBase(platform: ServicePlatform, name: string):
  * 5. Update symlink (Unix) or service registration (Windows)
  * 6. Start service
  */
+/**
+ * Resolve the target version for an npm-source upgrade (no --from/--url).
+ *
+ * The npm-source flow assumes the operator already ran
+ * `npm install -g @kici-dev/<pkg>@<version>`, which overwrites the global
+ * package in place. The running `kici-admin` binary is therefore the new
+ * version, and `running` is its self-reported version. We default the target
+ * to it, or validate an explicitly-passed --version matches — a mismatch means
+ * the npm install did not actually update the global binary.
+ */
+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/kici-admin.d.ts

@@ -19,4 +19,17 @@ import { Command } from 'commander';
 export declare function buildProgram(): Command;
 /** Build the program and parse argv — the bin-shim entry point. */
 export declare function runCli(argv?: string[]): void;
+/**
+ * Canonicalize a path through any symlinks, falling back to a plain `resolve`
+ * when the target does not exist on disk. The entry-point guard compares the
+ * invoked script path against this module's own path; both sides must be fully
+ * canonicalized or a symlinked invocation path silently fails the match. The
+ * canonical example is the light-package launcher running
+ * `node /tmp/.../kici-admin.cjs` on macOS, where `/tmp` is a symlink to
+ * `/private/tmp`: `process.argv[1]` keeps the `/tmp` form while the bundle's
+ * `import.meta.url` resolves to the real `/private/tmp` path, so an
+ * un-canonicalized comparison is always false and the CLI exits 0 without
+ * running any command.
+ */
+export declare function canonicalize(p: string): string;
 //# sourceMappingURL=kici-admin.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