@makaio/framework 1.0.0-dev-1779046984397

package/dist/clients/index.d.mts

@@ -0,0 +1,2786 @@
+import * as _$zod from "zod";
+import { z } from "zod";
+import * as _$_makaio_core0 from "@makaio/framework/core";
+import { EventMessagePayload, RequestMessagePayload, SchemaRecord, SubjectDefinition, SubjectRecord } from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import { ClientDefinition, ExtensionServiceLifecycle, LatestVersionSourceStatus, MakaioNodeExtension } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { ClientAccountIdentifier, ClientDefinition as ClientDefinition$1, ClientExecutionContext, ClientInstallCompleted, ClientInstallProgress, ClientRuntimeObserveRequest, ClientSessionObservedBase, ClientSubjects, ClientUsageSnapshot, ClientWiringEntry, ClientWiringEntrySchema, LatestVersionSourceStatus as LatestVersionSourceStatus$1, ManagedInstallDescriptor, ManagedInstallStrategy, PostInstallDescriptor } from "@makaio/framework/contracts/client";
+import * as _$zod_v4_core0 from "zod/v4/core";
+
+//#region packages/clients-core/src/atomic-modify-file.d.ts
+/**
+ * Atomic file read-modify-write utility with per-path mutex serialization.
+ *
+ * Provides a generic helper for safely updating JSON config files: reads the
+ * current JSON, validates it through a caller-supplied parser, applies a
+ * modifier, and writes the result atomically (write-to-UUID-tmp then rename).
+ * Concurrent calls to the same path are serialized via the caller-owned mutex
+ * map.
+ * @packageDocumentation
+ */
+/**
+ * Descriptor returned by an {@link AtomicModifier}.
+ * @typeParam TContent - The JSON-serializable type of the file's content.
+ * @typeParam TResult - An arbitrary caller-defined result value.
+ */
+interface AtomicModifyOutcome<TContent, TResult> {
+  /**
+   * The (potentially updated) content to persist.  Ignored when
+   * `changed` is `false`.
+   */
+  readonly content: TContent;
+  /**
+   * Whether the file should be written.  When `false`, no I/O is performed
+   * and the resolved promise carries `result` without touching the disk.
+   */
+  readonly changed: boolean;
+  /** Caller-defined value forwarded as the resolved value of {@link atomicModifyFile}. */
+  readonly result: TResult;
+}
+/**
+ * Modifier function supplied by the caller.
+ *
+ * Receives the current file content (or the default value when the file is
+ * absent) and returns an {@link AtomicModifyOutcome} describing the desired
+ * new content and whether a write is needed.
+ *
+ * The modifier **must be synchronous or return a resolved-in-the-same-tick
+ * promise** — it runs inside the mutex chain so async work inside the modifier
+ * is safe, but long-running modifiers will delay subsequent serialized writes.
+ * @typeParam TContent - The JSON-serializable type of the file's content.
+ * @typeParam TResult - An arbitrary caller-defined result value.
+ */
+type AtomicModifier<TContent, TResult> = (current: TContent) => AtomicModifyOutcome<TContent, TResult> | Promise<AtomicModifyOutcome<TContent, TResult>>;
+/**
+ * Parser function supplied by the caller.
+ *
+ * The helper reads disk JSON as `unknown`; client-specific settings modules
+ * own the schema that turns unknown JSON into a trusted content type.
+ * @typeParam TContent - The validated content type consumed by the modifier.
+ */
+type AtomicContentParser<TContent> = (raw: unknown) => TContent;
+/**
+ * Read the current file content, validate it with `parseContent`, apply
+ * `modifier`, and atomically persist the result when `changed` is `true`.
+ *
+ * **Atomicity:** the updated content is written to a UUID-suffixed sibling file
+ * in the same directory, then renamed into place.  Readers never observe a
+ * partial write.  The temp file is unlinked on write failure.
+ *
+ * **Serialization:** the caller owns the `mutex` map and passes the same
+ * instance for all calls sharing the same logical file namespace.  The helper
+ * chains on the existing in-flight promise for `filePath` so concurrent calls
+ * are queued rather than racing.  The entry is pruned from the map once no
+ * further work is queued.
+ *
+ * **Parent directory:** created automatically when absent (`mkdir -p`).
+ * @typeParam TContent - The JSON-serializable type of the file's content.
+ * @typeParam TResult - An arbitrary caller-defined result value.
+ * @param filePath - Absolute path to the target file.
+ * @param defaultContent - Raw value parsed when the file does not exist.
+ * @param mutex - Module-scoped per-path mutex map owned by the caller.
+ * @param parseContent - Parser that validates unknown disk JSON before mutation.
+ * @param modifier - Pure function that transforms the current content.
+ * @returns The `result` value produced by `modifier`.
+ */
+declare function atomicModifyFile<TContent, TResult>(filePath: string, defaultContent: unknown, mutex: Map<string, Promise<void>>, parseContent: AtomicContentParser<TContent>, modifier: AtomicModifier<TContent, TResult>): Promise<TResult>;
+//#endregion
+//#region packages/clients-core/src/client-binary-errors.d.ts
+/**
+ * Typed error classes for the client binary management subsystem.
+ * @packageDocumentation
+ */
+/**
+ * Thrown by `client.resolveBinary` when no managed version is active and the
+ * global PATH scan finds no matching binary for the client.
+ *
+ * Callers that need to distinguish "binary absent" from other resolution
+ * failures (e.g. corrupted managed state, storage errors) should check for
+ * this class rather than matching the error message string.
+ */
+declare class BinaryNotFoundError extends Error {
+  /** Discriminant code for structured error detection without string matching. */
+  readonly code: "BINARY_NOT_FOUND";
+  /**
+   * @param clientId - Stable client identifier for which no binary was found
+   */
+  constructor(clientId: string);
+}
+//#endregion
+//#region packages/clients-core/src/client-account-registry.d.ts
+/**
+ * Result returned when account identifiers are observed or ingested.
+ */
+interface ClientAccountUpsertResult {
+  /** Stable in-memory account ID selected or created for the identifier set. */
+  readonly clientAccountId: string;
+  /** Latest non-empty display label retained for the account, if any. */
+  readonly displayLabel?: string;
+  /** Any prior account IDs folded into the canonical account during upsert. */
+  readonly mergedAccountIds: ReadonlyArray<string>;
+}
+/**
+ * In-memory registry that canonicalizes client accounts across identifiers.
+ *
+ * Identifiers are scoped by `clientId`, `scheme`, and `value`, so the same raw
+ * identifier value used by different clients does not collide.
+ */
+declare class ClientAccountRegistry {
+  private nextAccountSequence;
+  private readonly accountIdsByIdentifier;
+  private readonly accounts;
+  /**
+   * Upsert an account record for the provided identifiers.
+   *
+   * Reuses an existing account ID when any identifier is already known, and
+   * folds all supplied identifiers onto the canonical account mapping.
+   * @param options - Client/account identity inputs to observe
+   * @returns Canonical account ID plus any merged prior IDs
+   */
+  upsertAccount(options: {
+    clientId: string;
+    identifiers: ReadonlyArray<ClientAccountIdentifier>;
+    displayLabel?: string;
+  }): ClientAccountUpsertResult;
+  /**
+   * Remove all in-memory state.
+   */
+  clear(): void;
+  private createAccount;
+  private mergeInto;
+}
+//#endregion
+//#region packages/clients-core/src/client-binary-feed-cache.d.ts
+/**
+ * In-memory cache of latest-available-version metadata per managed client.
+ *
+ * **Lifecycle:**
+ * 1. Call {@link ClientBinaryFeedCache.hydrate} at boot to populate the cache
+ *    from persisted state rows.
+ * 2. Call {@link ClientBinaryFeedCache.update} after every feed refresh to
+ *    update the in-memory entry and persist the new metadata to the database.
+ *
+ * The cache is write-only from the outside: the manager reads feed metadata
+ * exclusively via {@link ClientBinaryVersionResolver.getLatestVersionMeta}.
+ * The in-memory `cache` Map is retained internally so that
+ * {@link ClientBinaryFeedCache.update} can preserve the last-successful
+ * `lastCheckedAt` timestamp on error without an extra storage round-trip.
+ */
+declare class ClientBinaryFeedCache {
+  private readonly cache;
+  private readonly bus;
+  /**
+   * @param bus - Bus instance used to persist feed-cache updates to storage
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Hydrates the in-memory cache from all persisted state rows.
+   *
+   * Must be called once at boot, before any calls to {@link update}. Rows that
+   * have `latestVersionLastCheckedAt` set are
+   * classified as `'cached'`; rows without it are classified as `'error'`
+   * (the feed has never been successfully checked).
+   *
+   * Returns the raw state rows so the caller can reuse them (e.g. to seed
+   * the version resolver) without a second `loadAllState` bus round-trip.
+   * @returns All persisted state rows fetched during hydration
+   */
+  hydrate(): Promise<ReadonlyArray<{
+    clientId: string;
+    latestAvailableVersion: string | null;
+    latestVersionLastCheckedAt: number | null;
+    latestVersionSourceStatus: LatestVersionSourceStatus;
+  }>>;
+  /**
+   * Persist the feed-cache entry for a client to storage and then update the
+   * in-memory cache.
+   *
+   * Storage is written first so that a bus failure leaves the in-memory cache
+   * unchanged, keeping the resolver and storage in sync. The in-memory entry is
+   * only updated after the bus request succeeds.
+   *
+   * Call this after every feed refresh attempt, including failures (using
+   * `'error'` as the `sourceStatus`). On error the caller should pass the
+   * last-known version from the version resolver — not `null` — so that the
+   * cached value remains useful for subsequent list operations.
+   * @param clientId - Stable client identifier to update
+   * @param latestAvailableVersion - Latest version from the upstream feed,
+   *   or the previously cached version when the refresh failed
+   * @param sourceStatus - Freshness classification for this update
+   */
+  update(clientId: string, latestAvailableVersion: string | null, sourceStatus: LatestVersionSourceStatus): Promise<void>;
+}
+//#endregion
+//#region packages/clients-core/src/binary-strategies/types.d.ts
+/**
+ * Injected I/O dependencies for install strategy implementations.
+ *
+ * Abstracting these operations behind an interface makes every strategy
+ * testable without touching the network or file system.
+ */
+interface StrategyDependencies {
+  /**
+   * Fetch `url` and return the full response body as a string.
+   * @param url - The URL to fetch.
+   * @returns The raw response body text.
+   */
+  fetchText(url: string): Promise<string>;
+  /**
+   * Fetch `url`, parse the response body as JSON, and return it.
+   * @param url - The URL to fetch.
+   * @returns The parsed JSON value.
+   */
+  fetchJson(url: string): Promise<unknown>;
+  /**
+   * Download `url` to `destPath` on disk, optionally reporting byte progress.
+   * @param url - The URL to download.
+   * @param destPath - Absolute destination file path.
+   * @param onProgress - Optional callback; `total` is `null` when the server
+   *   does not advertise a `Content-Length`.
+   * @returns The resolved absolute destination path.
+   */
+  downloadFile(url: string, destPath: string, onProgress?: (downloaded: number, total: number | null) => void): Promise<string>;
+  /**
+   * Execute a shell command and return its stdout.
+   * @param command - The executable to run (no shell expansion).
+   * @param args - Positional arguments passed to the executable.
+   * @param options - Optional execution options.
+   * @returns Trimmed stdout string.
+   */
+  exec(command: string, args: string[], options?: {
+    cwd?: string;
+  }): Promise<string>;
+  /**
+   * Extract an archive file into `destDir`.
+   * @param archivePath - Absolute path to the archive file.
+   * @param destDir - Absolute directory to extract into.
+   * @param format - Archive type (`'tar.gz'` or `'zip'`).
+   */
+  extractArchive(archivePath: string, destDir: string, format: 'tar.gz' | 'zip'): Promise<void>;
+  /**
+   * Delete a single file from disk.
+   *
+   * Implementations must be idempotent — if `filePath` does not exist the call
+   * should resolve without error.
+   * @param filePath - Absolute path to the file to remove.
+   */
+  deleteFile(filePath: string): Promise<void>;
+  /**
+   * Compute the checksum of a file at `filePath`.
+   * @param filePath - Absolute path to the file to hash.
+   * @param algorithm - Hash algorithm name (defaults to `'sha256'`).
+   * @returns Lowercase hex-encoded digest string.
+   */
+  computeChecksum(filePath: string, algorithm?: string): Promise<string>;
+  /**
+   * Recursively remove a directory and all of its contents.
+   *
+   * Implementations must be idempotent — if `dirPath` does not exist the
+   * call should resolve without error. This mirrors the `force` flag of
+   * `fs.rm` from `node:fs/promises`.
+   * @param dirPath - Absolute path to the directory to remove.
+   */
+  removeDirectory(dirPath: string): Promise<void>;
+}
+//#endregion
+//#region packages/clients-core/src/client-binary-manager-types.d.ts
+/**
+ * Configuration for the managed binary base directory.
+ *
+ * The manager derives per-client, per-version install directories from
+ * `basePath` using the pattern `{basePath}/{clientId}/{version}/`.
+ *
+ * TODO: ClientBinaryJobRunner only consumes basePath — introduce a narrowed
+ * runner-specific config (e.g. `Pick<ClientBinaryManagerConfig, 'basePath'>`) to
+ * decouple the runner from manager-only config such as configBasePath.
+ */
+interface ClientBinaryManagerConfig {
+  /**
+   * Absolute base directory under which all managed binary versions are
+   * installed (e.g. `~/.makaio/binaries/`).
+   */
+  basePath: string;
+  /**
+   * Base directory for per-client config isolation directories.
+   *
+   * Managed binaries get `{configBasePath}/{clientId}/config/` as their
+   * isolated config dir (e.g. `~/.makaio/clients/claude-code/config/`).
+   *
+   * Used by `client.resolveBinary` to construct the managed config path when
+   * the definition declares `configIsolation`.
+   */
+  configBasePath: string;
+  /**
+   * Framework-owned handlers for declarative post-install descriptors.
+   *
+   * Client packages declare `postInstall.kind`; the host supplies the handler
+   * implementation here. Missing handlers fail the install job rather than
+   * silently skipping a declared lifecycle step.
+   */
+  postInstallHandlers?: ReadonlyMap<string, PostInstallHandler>;
+}
+/**
+ * Context passed to a framework-owned post-install handler.
+ */
+interface PostInstallContext {
+  /** Stable client identifier being installed. */
+  clientId: string;
+  /** Concrete version that was installed. */
+  version: string;
+  /** Absolute directory where the strategy installed the binary. */
+  installPath: string;
+  /** Declarative descriptor from the client definition. */
+  descriptor: PostInstallDescriptor;
+}
+/**
+ * Framework-owned handler for a declarative post-install action.
+ *
+ * Returning metadata is optional; when present it is forwarded on install
+ * progress and completion events.
+ */
+type PostInstallHandler = (context: PostInstallContext) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * An in-flight or completed install/update job.
+ *
+ * Jobs are created synchronously by `client.install` and `client.update`
+ * handlers and executed asynchronously by the {@link ClientBinaryJobRunner}.
+ */
+interface InstallJob {
+  /** Opaque stable identifier for this job (UUID v4). */
+  jobId: string;
+  /** Stable client identifier this job is installing. */
+  clientId: string;
+  /**
+   * Concrete version to install. Set immediately after version resolution;
+   * remains the resolved version string throughout execution.
+   */
+  version: string;
+  /**
+   * Install strategy discriminant corresponding to the managed install
+   * descriptor that was used to create the job.
+   */
+  strategy: ManagedInstallStrategy;
+  /** Current lifecycle state of the job. */
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /**
+   * When `true`, the job runner sets this version as active on successful
+   * completion.
+   */
+  makeActive: boolean;
+  /**
+   * The originating bus subject that created this job.
+   *
+   * Used to set the correct `reason` on `client.version.changed` events:
+   * `'install'` for `client.install` requests, `'update'` for `client.update`
+   * requests.
+   */
+  reason: 'install' | 'update';
+}
+/**
+ * Read-only interface used by the manager to retrieve client definitions.
+ *
+ * On the production boot path the manager receives a
+ * {@link ClientDefinitionRegistry} fully seeded before `init()` is called.
+ * The manager depends only on the read side of the registry contract;
+ * mutation is available on the concrete {@link ClientDefinitionRegistry} class
+ * for tests and administrative tooling.
+ */
+interface ClientDefinitionLookup {
+  /**
+   * Return the static definition for the given client identifier, or
+   * `undefined` when no definition is registered.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @returns The registered {@link ClientDefinition}, or `undefined`
+   */
+  getDefinition(clientId: string): ClientDefinition$1 | undefined;
+  /**
+   * Return all registered definitions known to this lookup.
+   *
+   * `client.list` uses this to include managed clients that have no installed
+   * versions or state rows yet.
+   * @returns Registered client definitions
+   */
+  listDefinitions(): readonly ClientDefinition$1[];
+}
+/**
+ * Result passed to the completion callback after a successful install.
+ *
+ * Bundles the job identity and artifact information into a single object
+ * so the callback signature stays stable as new fields are added.
+ */
+interface JobCompletionResult {
+  /** Job identifier that completed. */
+  jobId: string;
+  /** Stable client identifier. */
+  clientId: string;
+  /** Installed version string. */
+  version: string;
+  /** Absolute path to the installed binary directory. */
+  installPath: string;
+  /** Whether to activate this version. */
+  makeActive: boolean;
+  /** Originating operation reason forwarded to `client.version.changed`. */
+  reason: 'install' | 'update';
+}
+/**
+ * Callback invoked by the job runner when a job completes successfully and
+ * the binary has been written to disk but before activation.
+ *
+ * The manager uses this to persist the installed version to storage and
+ * optionally set it as active.
+ * @param result - Completion result with job and artifact details
+ */
+type JobCompletionCallback = (result: JobCompletionResult) => Promise<void>;
+/**
+ * Callback invoked by the job runner at each install pipeline stage transition.
+ *
+ * The manager provides this callback and emits the typed
+ * `client.installJob.progress` bus event.
+ * @param payload - Progress event payload to emit
+ */
+type JobProgressCallback = (payload: ClientInstallProgress) => void;
+/**
+ * Callback invoked by the job runner when the install pipeline terminates
+ * (success or failure).
+ *
+ * The manager provides this callback and emits the typed
+ * `client.installJob.completed` bus event.
+ * @param payload - Completed event payload to emit
+ */
+type JobCompletedCallback = (payload: ClientInstallCompleted) => Promise<void>;
+/**
+ * Return `true` when `candidate` resolves within `base`.
+ *
+ * Used by the manager and job runner to guard against path-traversal
+ * in persisted install paths and user-supplied version strings.
+ *
+ * Both arguments must be absolute paths. Relative inputs are rejected before
+ * `path.resolve()` runs so the process working directory cannot turn a
+ * relative candidate into an apparently managed path.
+ * @param base - Absolute base path
+ * @param candidate - Absolute path to validate
+ * @returns `true` when the candidate is safely within `base`
+ */
+declare function isPathWithinBase(base: string, candidate: string): boolean;
+/**
+ * Resolve and validate `basePath`, returning the resolved absolute path.
+ *
+ * Both {@link ClientBinaryManager} and {@link ClientBinaryJobRunner} call this
+ * at construction time so the resolved base is computed once and reused.
+ * @param basePath - Raw base path from configuration
+ * @param caller - Class name for error messages
+ * @returns Resolved absolute base path
+ * @throws When `basePath` is empty or not absolute
+ */
+declare function resolveAndValidateBasePath(basePath: string, caller: string): string;
+//#endregion
+//#region packages/clients-core/src/client-binary-manager.d.ts
+/**
+ * In-memory manager for the global `client.*` binary-management contracts.
+ *
+ * **Responsibilities:**
+ * - Hydrate the feed cache and version resolver from storage on boot.
+ * - Handle `client.list`, `client.install`, `client.update`,
+ *   `client.setActive`, and `client.uninstall` bus subjects.
+ * - Delegate async install/update execution to {@link ClientBinaryJobRunner}.
+ * - Persist installation state via `client-binary:storage.*` subjects.
+ * - Emit `client.version.changed` whenever the active version pointer changes.
+ * - Provide typed progress and completed callbacks to the job runner so that
+ *   bus emissions remain in the manager layer with correct type inference.
+ *
+ * **One job per client invariant:** only one install or update job is allowed
+ * to run for a given client at a time. Concurrent requests are rejected with
+ * an error until the in-flight job completes.
+ */
+declare class ClientBinaryManager extends BaseService {
+  private readonly config;
+  private readonly definitionLookup;
+  private readonly feedCache;
+  private readonly versionResolver;
+  private readonly jobRunner;
+  private readonly strategyDeps;
+  private readonly resolvedBasePath;
+  private readonly resolver;
+  /**
+   * Set of client IDs with an operation (install, update, or uninstall) in
+   * progress.
+   *
+   * Acquired synchronously before any async work to serialize concurrent
+   * requests per client and prevent the TOCTOU window between a guard check
+   * and the eventual {@link ClientBinaryJobRunner.startJob} call.
+   *
+   * Released by the `makeCompletedCallback` `.finally()` on job termination,
+   * by the `handleUninstall` `finally` block on uninstall completion, or by
+   * {@link onDestroy} on manager teardown.
+   */
+  private readonly pendingClients;
+  /**
+   * Creates a new binary manager.
+   * @param bus - Bus instance for handler registration and event emission
+   * @param config - Manager configuration; `basePath` and `configBasePath` must be non-empty absolute paths
+   * @param definitionLookup - Client definition registry
+   * @param strategyDeps - I/O dependency implementations for strategies
+   * @throws When `config.basePath` or `config.configBasePath` is empty or relative
+   */
+  constructor(bus: IMakaioBus | undefined, config: ClientBinaryManagerConfig, definitionLookup?: ClientDefinitionLookup, strategyDeps?: StrategyDependencies);
+  /**
+   * Hydrate state from storage and register bus handlers.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Cancel all running jobs and clear in-memory state.
+   */
+  protected onDestroy(): void;
+  /**
+   * Assemble the installation inventory for all managed clients.
+   *
+   * Delegates to {@link assembleBinaryList} for the read-model assembly logic.
+   * @param forceRefresh - When `true`, force a live upstream feed refresh
+   * @returns Assembled list of client binary entries
+   */
+  private handleList;
+  /**
+   * Enqueue a background install job for a managed client binary.
+   *
+   * Resolves the target version (explicit or latest-from-feed) and returns
+   * a `jobId` immediately. The job runs asynchronously; callers track progress
+   * via `client.installJob.progress` and `client.installJob.completed` events.
+   * @param clientId - Stable client identifier to install
+   * @param requestedVersion - Explicit version to install, or `undefined` for latest
+   * @returns Job acknowledgement with resolved version
+   */
+  private handleInstall;
+  /**
+   * Refresh the feed, resolve the latest version, and enqueue an update job
+   * that installs and activates the result.
+   * @param clientId - Stable client identifier to update
+   * @returns Job acknowledgement with resolved version
+   */
+  private handleUpdate;
+  /**
+   * Switch the active binary pointer to an already-installed version.
+   *
+   * The requested version must be present in the installed versions list;
+   * requests for uninstalled versions are rejected with an error.
+   * @param clientId - Stable client identifier
+   * @param version - Exact installed version string to activate
+   * @returns Updated client and active version
+   */
+  private handleSetActive;
+  /**
+   * Remove a specific installed version of a managed client binary.
+   *
+   * The version row and active-version pointer are cleared atomically in a
+   * single storage transaction via `removeVersionAndClearActive`. Filesystem
+   * cleanup and event emission occur in the manager layer after the transaction
+   * commits, keeping I/O out of the storage handler.
+   *
+   * If the removed version was active, `client.version.changed` is emitted.
+   * No automatic replacement is made — callers must explicitly call
+   * `client.setActive` to promote another version.
+   * @param clientId - Stable client identifier
+   * @param version - Exact version string to remove
+   * @returns Removal result with the updated active version
+   */
+  private handleUninstall;
+  /**
+   * Update the active version pointer and optionally emit
+   * `client.version.changed`.
+   *
+   * Centralizes the storage-side active-version mutation used by
+   * `handleSetActive` and the job completion callback. Feed-cache fields are
+   * preserved by `client-binary:storage.setActiveVersion`.
+   * @param clientId - Stable client identifier
+   * @param newActiveVersion - Version to set active, or `null` to clear
+   * @param reason - Operation that triggered the change
+   * @returns The previous active version before the mutation
+   */
+  private patchActiveVersion;
+  /**
+   * Hydrate feed cache and version resolver from persisted storage.
+   *
+   * Called once during `onInit()`. Populates the in-memory caches so that
+   * `client.list` and `client.install` requests do not need a live feed fetch
+   * on the first call after a process restart. Both caches are seeded from
+   * a single `loadAllState` bus round-trip.
+   */
+  private hydrateFromStorage;
+  /**
+   * Look up and validate a managed client definition.
+   *
+   * Throws when no definition is registered for `clientId` or when the
+   * definition lacks a `managedInstall` descriptor.
+   * @param clientId - Stable client identifier
+   * @param subject - Bus subject name used in error messages
+   * @returns The full definition and its managed install descriptor
+   */
+  private requireManagedDefinition;
+  /**
+   * Acquire the per-client operation lock, run `fn`, and release the lock on
+   * pre-job errors via the catch path.
+   *
+   * On successful job start the lock transfers to the
+   * `makeCompletedCallback`, which releases it on job termination.
+   * @param clientId - Stable client identifier to lock
+   * @param fn - Async work to run while the lock is held
+   * @returns The result of `fn`
+   */
+  private withClientLock;
+  /**
+   * Build an {@link InstallJob} and hand it to the job runner.
+   * @param clientId - Stable client identifier
+   * @param resolvedVersion - Concrete version to install
+   * @param descriptor - Managed install descriptor
+   * @param definition - Full client definition (for post-install and version command)
+   * @param makeActive - Whether to activate the version after install
+   * @param reason - Originating operation
+   * @returns The generated `jobId`
+   */
+  private startInstallJob;
+  /**
+   * Create the completion callback passed to the job runner.
+   *
+   * Persists the installed version to storage and optionally sets it as active,
+   * then emits `client.version.changed` with the originating operation reason.
+   *
+   * **Consistency guarantee:** version persistence and optional activation
+   * are committed through one storage transaction, so a failed activation
+   * cannot leave a version row pointing at a directory the runner will remove.
+   * @returns Bound completion callback for the job runner
+   */
+  private makeCompletionCallback;
+}
+//#endregion
+//#region packages/clients-core/src/client-binary-job-runner.d.ts
+/**
+ * Executes install jobs asynchronously and delivers progress and completed
+ * notifications via caller-provided typed callbacks.
+ *
+ * **Lifecycle:**
+ * 1. The {@link ClientBinaryManager} creates an {@link InstallJob} and calls
+ *    {@link startJob}.
+ * 2. The runner starts the job in the background (fire-and-forget `void`).
+ * 3. As the strategy moves through pipeline stages, the runner invokes the
+ *    `onProgress` callback with typed progress payloads.
+ * 4. On success the runner invokes {@link JobCompletionCallback} (for
+ *    persistence and activation) and then `onCompleted` with
+ *    `status: 'success'`.
+ * 5. On failure the runner invokes `onCompleted` with `status: 'error'` and
+ *    skips the persistence callback.
+ * 6. {@link cancelAll} sets a cancellation flag and clears the job map so
+ *    that any in-flight async work skips callbacks after shutdown. The
+ *    underlying I/O (network, disk) is not interrupted.
+ */
+declare class ClientBinaryJobRunner {
+  #private;
+  private readonly strategyDeps;
+  private readonly config;
+  /** Active jobs keyed by `jobId`. */
+  private readonly jobs;
+  private readonly resolvedBasePath;
+  /**
+   * @param strategyDeps - I/O dependency implementations forwarded to each strategy
+   * @param config - Manager configuration (provides `basePath`)
+   */
+  constructor(strategyDeps: StrategyDependencies, config: ClientBinaryManagerConfig);
+  /**
+   * Start a background install job and return immediately.
+   *
+   * The job is registered in the internal job map and executed asynchronously.
+   * Callers must not await the returned value — the job reports its outcome
+   * through the provided callbacks.
+   *
+   * Pipeline order:
+   * 1. Strategy execute (download → checksum → extract → install)
+   * 2. Post-install hook (if declared)
+   * 3. Version verification (if `versionCommand` is provided)
+   * 4. `onComplete` persistence callback
+   * 5. `onCompleted` bus-event callback
+   * @param job - Job descriptor created by the manager
+   * @param descriptor - Managed install descriptor for the client
+   * @param onProgress - Callback invoked at each pipeline stage transition
+   * @param onComplete - Callback invoked by the runner on successful completion (persistence)
+   * @param onCompleted - Callback invoked after completion (bus event emission)
+   * @param postInstall - Optional post-install descriptor from the client definition
+   * @param versionCommand - Optional version command used to verify the installed binary
+   * @returns The `jobId` of the started job (same as `job.jobId`)
+   */
+  startJob(job: InstallJob, descriptor: ManagedInstallDescriptor, onProgress: JobProgressCallback, onComplete: JobCompletionCallback, onCompleted: JobCompletedCallback, postInstall?: PostInstallDescriptor, versionCommand?: readonly [string, ...string[]]): string;
+  /**
+   * Signal cancellation and clear all tracked jobs.
+   *
+   * Called by the manager during shutdown. Sets the cancellation flag so that
+   * any in-flight async work skips its callbacks after this point. Clears the
+   * internal job map to avoid memory leaks across test resets.
+   */
+  cancelAll(): void;
+  /**
+   * Invoke the progress callback without propagating exceptions.
+   *
+   * Progress emission is best-effort: if the manager's progress publisher
+   * throws (e.g. a bus error or a subscriber that throws), the error is
+   * swallowed so that the install pipeline can continue unaffected.
+   * @param onProgress - Progress notification callback provided by the manager
+   * @param payload - Progress event payload to emit
+   */
+  private safeOnProgress;
+  /**
+   * Emit progress only while the runner is active.
+   *
+   * Helper methods use this instead of open-coding `#cancelled` checks so a
+   * shutdown that arrives between the caller's outer guard and the helper body
+   * cannot leak progress events from a destroyed manager.
+   * @param onProgress - Progress notification callback provided by the manager
+   * @param payload - Progress event payload to emit
+   * @returns `true` when the event was emitted; `false` when cancelled
+   */
+  private emitProgressIfActive;
+  /**
+   * Execute a single install job to completion.
+   *
+   * This method drives the strategy pipeline, invokes the progress callback
+   * at each stage, calls the persistence callback on success, and always
+   * invokes the completed callback at the end regardless of outcome.
+   *
+   * All callbacks are guarded by the `#cancelled` flag: if {@link cancelAll}
+   * is called while the job is in flight (e.g. during shutdown), no further
+   * callbacks will fire after that point.
+   * @param job - The running job descriptor
+   * @param descriptor - Managed install descriptor for the client
+   * @param onProgress - Progress notification callback
+   * @param onComplete - Persistence callback invoked on successful completion
+   * @param onCompleted - Bus event emission callback invoked after all work
+   * @param postInstall - Optional declarative post-install descriptor
+   * @param versionCommand - Optional version command used to verify the installed binary
+   */
+  private runJob;
+  /**
+   * Drive the success-path finalization: emit the `activating` stage when
+   * applicable, persist the artifact via `onComplete`, then emit the
+   * `client.installJob.completed` event via `onCompleted`.
+   *
+   * Extracted from {@link runJob} to keep that method within the line-count
+   * lint budget while retaining readable control flow.
+   * @param job - Running job descriptor
+   * @param artifact - Normalized install artifact returned by the strategy
+   * @param metadata - Optional post-install handler metadata
+   * @param onProgress - Progress callback (best-effort via {@link safeOnProgress})
+   * @param onComplete - Persistence callback invoked before event emission
+   * @param onCompleted - Bus event emission callback
+   */
+  private finalizeSuccess;
+  /**
+   * Best-effort cleanup for an artifact that passed strategy execution but failed
+   * before it could be persisted as an installed version.
+   * @param installPath - Absolute staged install directory to remove
+   */
+  private cleanupStagedArtifact;
+  /**
+   * Run the optional declarative post-install hook through a framework-owned
+   * handler registered on the manager config.
+   * @param job - Running job descriptor
+   * @param installPath - Absolute installed binary directory
+   * @param postInstall - Declarative post-install descriptor, if any
+   * @param onProgress - Progress callback used to emit `post-install`
+   * @returns Optional handler metadata
+   */
+  private runPostInstall;
+  /**
+   * Emit a `verifying` progress event and invoke {@link verifyInstalledVersion}.
+   *
+   * Emits a `verifying` progress event with `metadata.kind: 'version-command'`
+   * before executing the command so that callers can display real-time feedback.
+   * The verification runs synchronously after the event is emitted.
+   * @param job - Running job descriptor
+   * @param installPath - Absolute installed binary directory
+   * @param versionCommand - Command and args declared on the client definition
+   * @param onProgress - Progress callback for the verifying stage
+   * @throws When path validation fails or the binary reports an unexpected version
+   */
+  private runVersionVerification;
+  /**
+   * Resolve a post-install handler by descriptor kind.
+   * @param postInstall - Declarative post-install descriptor
+   * @returns Registered handler for the descriptor kind
+   * @throws When no handler is registered for the descriptor kind
+   */
+  private resolvePostInstallHandler;
+  /**
+   * Build a progress payload for runner-owned stages.
+   * @param job - Running job descriptor
+   * @param stage - Install stage to report
+   * @param progress - Stage progress value
+   * @param installPath - Absolute installed binary directory
+   * @param metadata - Optional event metadata
+   * @returns Install progress payload
+   */
+  private buildProgressPayload;
+  /**
+   * Resolve the absolute install directory for a specific client version.
+   *
+   * The convention is `{basePath}/{clientId}/{version}/`. Both `clientId` and
+   * `version` are resolved against the base path and validated to prevent path
+   * traversal sequences (e.g. `..`) from escaping the install root.
+   * @param clientId - Stable client identifier
+   * @param version - Resolved version string
+   * @returns Absolute target directory path
+   * @throws When the resolved path would escape `basePath`
+   */
+  private resolveTargetDir;
+}
+//#endregion
+//#region packages/clients-core/src/client-definition-registry.d.ts
+/**
+ * Concrete {@link ClientDefinitionLookup} implementation seeded with a fixed
+ * set of definitions at construction time.
+ *
+ * Definitions are indexed by {@link ClientDefinition.id} for O(1) lookup.
+ * The constructor validates that all supplied definitions have unique IDs,
+ * throwing immediately on a duplicate to surface misconfiguration at boot
+ * rather than silently overwriting an existing entry.
+ * @example
+ * ```ts
+ * const registry = new ClientDefinitionRegistry([claudeCodeDefinition]);
+ * const manager = new ClientBinaryManager(bus, config, registry, strategyDeps);
+ * await manager.init();
+ * ```
+ */
+declare class ClientDefinitionRegistry implements ClientDefinitionLookup {
+  private readonly definitions;
+  /**
+   * Create a registry pre-seeded with the supplied definitions.
+   *
+   * Throws when any two definitions share the same `id` — duplicate IDs
+   * indicate a misconfigured boot path that should fail loudly rather than
+   * silently drop or overwrite an entry.
+   * @param initialDefinitions - Ordered list of client definitions to register at construction time
+   * @throws When two definitions in `initialDefinitions` share the same `id`
+   */
+  constructor(initialDefinitions?: readonly ClientDefinition$1[]);
+  /**
+   * Return the static definition for the given client identifier, or
+   * `undefined` when no definition is registered.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @returns The registered {@link ClientDefinition}, or `undefined`
+   */
+  getDefinition(clientId: string): ClientDefinition$1 | undefined;
+  /**
+   * Return all registered definitions in insertion order.
+   *
+   * `client.list` uses this to include managed clients that have no installed
+   * versions or state rows yet.
+   * @returns All registered client definitions
+   */
+  listDefinitions(): readonly ClientDefinition$1[];
+  /**
+   * Register a client definition, replacing any existing entry for the same
+   * `definition.id`.
+   *
+   * **Test and admin path only.** This method is intentionally excluded from
+   * the normal application boot sequence. On the production path, all
+   * definitions are supplied to the constructor so the registry is immutable
+   * from the manager's perspective. Call `register` only from tests or
+   * administrative tooling that needs to inject or replace a definition after
+   * construction.
+   * @param definition - Client definition to register; its `id` is used as the registry key
+   */
+  register(definition: ClientDefinition$1): void;
+  /**
+   * Internal helper that registers a definition and throws on a duplicate ID.
+   *
+   * Used exclusively by the constructor to enforce uniqueness during seeding.
+   * @param definition - Client definition to register
+   * @throws When a definition with the same `id` is already registered
+   */
+  private registerUnique;
+}
+//#endregion
+//#region packages/clients-core/src/client-binary-version-resolver.d.ts
+/**
+ * Upstream feed fetcher abstraction.
+ *
+ * Implementors are responsible for the strategy-specific network calls needed
+ * to discover the latest published version of a managed client binary. The
+ * resolver treats this as a pure dependency so callers can substitute a mock
+ * in tests.
+ */
+interface FeedFetcher {
+  /**
+   * Fetch the latest available version string for the given install descriptor.
+   *
+   * The returned string must be a non-empty version identifier (semver or
+   * opaque tag). The implementor should throw on any network or parse error so
+   * the resolver can apply its fallback logic.
+   * @param descriptor - Managed install descriptor for the client
+   * @returns Resolved latest version string
+   */
+  fetchLatestVersion(descriptor: ManagedInstallDescriptor): Promise<string>;
+}
+/**
+ * Resolution result returned by {@link ClientBinaryVersionResolver.resolveInstallVersion}.
+ */
+interface ResolvedInstallVersion {
+  /** Concrete version string to install. */
+  version: string;
+  /**
+   * `true` when the version was supplied explicitly by the caller;
+   * `false` when the resolver fell back to the cached latest.
+   */
+  explicit: boolean;
+}
+/**
+ * Latest-version metadata for a single client, suitable for inclusion in a
+ * `client.list` response.
+ */
+interface LatestVersionMeta {
+  /** Latest version string known to the resolver, or `null` when unknown. */
+  latestAvailableVersion: string | null;
+  /** Epoch timestamp when the latest-version index was last checked, or `null`. */
+  latestVersionLastCheckedAt: number | null;
+  /** Freshness classification of the cache entry. */
+  latestVersionSourceStatus: LatestVersionSourceStatus$1;
+}
+/**
+ * In-memory version resolver for managed client binaries.
+ *
+ * Responsibilities:
+ * - Resolving a concrete version for `client.install` requests, falling back
+ *   to the last known latest when no explicit version is given.
+ * - Refreshing the latest-version cache on demand (for `client.list` with
+ *   `forceRefresh: true`), with a graceful fallback to the cached value on
+ *   network failure.
+ * - Exposing the cache state for `client.list` response assembly.
+ *
+ * This class is intentionally bus-free. The `ClientBinaryManager` owns bus
+ * registration and calls into this resolver.
+ */
+declare class ClientBinaryVersionResolver {
+  #private;
+  private readonly feedFetcher;
+  private readonly cache;
+  /**
+   * Creates a new resolver instance.
+   * @param feedFetcher - Strategy-agnostic upstream feed fetcher
+   */
+  constructor(feedFetcher: FeedFetcher);
+  /**
+   * Resolve the version to install for a `client.install` request.
+   *
+   * When `explicitVersion` is supplied it is returned unchanged. When it is
+   * absent the resolver returns the last cached latest version. If no cache
+   * entry exists for the client, the resolver attempts a live feed refresh; if
+   * that also fails, an error is thrown so the caller can reject the request
+   * with a clear message rather than installing a phantom version.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @param descriptor - Managed install descriptor for the client
+   * @param explicitVersion - Version string supplied by the caller, or `undefined`
+   * @returns Resolved version and whether it was explicitly requested
+   */
+  resolveInstallVersion(clientId: string, descriptor: ManagedInstallDescriptor, explicitVersion: string | undefined): Promise<ResolvedInstallVersion>;
+  /**
+   * Attempt a live feed refresh and update the in-memory cache.
+   *
+   * On success the cache entry is updated to `'fresh'`. On failure the
+   * existing entry (if any) is retained but its status is set to `'error'` so
+   * that callers can surface degraded-mode metadata without losing the last
+   * known version.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @param descriptor - Managed install descriptor for the client
+   * @returns `true` when the refresh succeeded, `false` when it failed
+   */
+  refresh(clientId: string, descriptor: ManagedInstallDescriptor): Promise<boolean>;
+  /**
+   * Return the current latest-version metadata for a client, suitable for
+   * embedding in a `client.list` response.
+   *
+   * When no cache entry exists, the returned object has `null` fields and
+   * status `'error'` — the absence of a cached value is itself an error state
+   * from the perspective of the list consumer.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @returns Latest-version metadata object
+   */
+  getLatestVersionMeta(clientId: string): LatestVersionMeta;
+  /**
+   * Seed the cache with a previously persisted latest-version entry.
+   *
+   * This is called by the `ClientBinaryManager` at startup to restore the
+   * feed-cache state from durable storage so that `resolveInstallVersion` does
+   * not need a live fetch on the first call after a restart.
+   *
+   * The seeded entry defaults to `'cached'` because it survived a process
+   * restart and has not been confirmed live in this session. Callers may pass
+   * `'error'` when the persisted row records a failed refresh attempt that
+   * should remain visible after hydration.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @param version - Version string from storage
+   * @param checkedAt - Epoch timestamp when the version was last fetched
+   * @param status - Persisted source status to seed
+   */
+  seedFromStorage(clientId: string, version: string, checkedAt: number, status?: LatestVersionSourceStatus$1): void;
+  /**
+   * Clear all in-memory cache entries.
+   *
+   * Intended for use in tests and on service destroy.
+   */
+  clear(): void;
+}
+//#endregion
+//#region packages/clients-core/src/client-runtime-registry-types.d.ts
+/**
+ * Shared types for the client runtime registry.
+ *
+ * Defines the in-memory record shape and upsert result
+ * consumed by {@link ClientRuntimeRegistry} and its storage layer.
+ * @packageDocumentation
+ */
+/**
+ * All valid lifecycle status values for a client runtime record.
+ *
+ * - `'observed'` — weaker evidence only (pid without supervisorSessionId); the
+ *   runtime has been detected but not yet confirmed as fully started.
+ * - `'started'` — strong evidence present (supervisorSessionId, or an adapter
+ *   confirmed the process); the runtime is confirmed started.
+ */
+declare const CLIENT_RUNTIME_STATUSES: readonly ["observed", "started"];
+/** Lifecycle status of a client runtime record. */
+type ClientRuntimeStatus = (typeof CLIENT_RUNTIME_STATUSES)[number];
+/**
+ * In-memory record for a single client runtime instance.
+ *
+ * All fields except `clientRuntimeId`, `clientId`, `status`, `observedAt`,
+ * `createdAt`, and `updatedAt` are optional because evidence accumulates
+ * incrementally across multiple observations.
+ */
+interface ClientRuntimeRecord {
+  /** Stable runtime identifier assigned by the registry (UUID v4). */
+  readonly clientRuntimeId: string;
+  /** Stable client identifier (e.g. `'claude-code'`). */
+  readonly clientId: string;
+  /** Current lifecycle status of the runtime. */
+  status: ClientRuntimeStatus;
+  /** Supervisor-assigned session ID, if observed. */
+  supervisorSessionId?: string;
+  /** OS process ID of the client binary, if observed. */
+  pid?: number;
+  /** OS process ID of the parent process, if observed. */
+  parentPid?: number;
+  /** Raw session identifier from the client runtime, if observed. */
+  adapterSessionId?: string;
+  /** Framework session ID, if already resolved. */
+  sessionId?: string;
+  /** Working directory of the client process, if observed. */
+  cwd?: string;
+  /** Full argv of the client process, if observed. */
+  argv?: string[];
+  /** Arbitrary pass-through metadata from the most recent observation. */
+  metadata?: Record<string, unknown>;
+  /** Unix epoch timestamp in milliseconds of the latest captured observation while the record was observed. */
+  observedAt: number;
+  /** Unix epoch timestamp in milliseconds when this record was created. */
+  readonly createdAt: number;
+  /** Unix epoch timestamp in milliseconds of the last mutation. */
+  updatedAt: number;
+}
+/**
+ * Result returned by {@link ClientRuntimeRegistry.upsertRuntime}.
+ */
+interface RuntimeUpsertResult {
+  /** Stable runtime record ID assigned or retrieved by the registry. */
+  readonly clientRuntimeId: string;
+  /** `true` when this observation created a new runtime record. */
+  readonly created: boolean;
+  /**
+   * `true` when this observation promoted an existing record from `'observed'`
+   * to `'started'` status.
+   */
+  readonly promoted: boolean;
+  /** The upserted runtime record (post-enrichment). */
+  readonly record: ClientRuntimeRecord;
+}
+//#endregion
+//#region packages/clients-core/src/client-runtime-registry.d.ts
+/**
+ * In-memory registry that canonicalizes client runtime instances across
+ * evidence fields and optionally persists them via a bus-backed handler.
+ *
+ * Construct the registry with an optional bus instance. When a bus is
+ * provided, every upsert is mirrored to the Drizzle handler via the
+ * `client-runtime:storage.upsert` subject. Call {@link loadFromStorage}
+ * once at boot to hydrate the in-memory map from persisted records.
+ */
+declare class ClientRuntimeRegistry {
+  private readonly runtimeMap;
+  private readonly bus;
+  /**
+   * Creates a new runtime registry.
+   * @param bus - Optional bus instance used to persist runtime records. When
+   *   absent, the registry operates purely in memory without persistence.
+   */
+  constructor(bus?: IMakaioBus);
+  /**
+   * Hydrate the in-memory map from all records persisted in storage.
+   *
+   * Must be called once at service boot before accepting observations. When
+   * no bus is wired in, this is a no-op.
+   */
+  loadFromStorage(): Promise<void>;
+  /**
+   * Upsert a runtime record for the provided observation evidence.
+   *
+   * Matching priority:
+   * 1. `supervisorSessionId` — globally unique; matches across clients.
+   * 2. `pid + clientId` — strong OS-level identity.
+   * 3. `adapterSessionId + clientId` — weaker adapter-level identity.
+   *
+   * When no existing record matches, a new runtime is created. When a match
+   * is found, the record is enriched with any new evidence fields and promoted
+   * to `'started'` when the incoming evidence warrants it.
+   * @param input - Runtime observation evidence
+   * @returns Upsert result with the stable `clientRuntimeId` and change flags
+   */
+  upsertRuntime(input: ClientRuntimeObserveRequest): Promise<RuntimeUpsertResult>;
+  /**
+   * Retrieve a runtime record by its stable ID.
+   *
+   * Returns a detached snapshot so caller mutations cannot affect registry
+   * records or secondary indexes.
+   * @param clientRuntimeId - Stable runtime identifier
+   * @returns The record, or `undefined` when not found
+   */
+  getRuntime(clientRuntimeId: string): ClientRuntimeRecord | undefined;
+  /**
+   * Remove all in-memory state.
+   *
+   * Does not touch persisted records — the storage layer is authoritative
+   * across restarts. Call {@link loadFromStorage} to re-hydrate.
+   */
+  clear(): void;
+  /**
+   * Return the number of runtime records currently held in memory.
+   * @returns Number of runtime records in the in-memory map
+   */
+  get size(): number;
+  private persistRecord;
+}
+//#endregion
+//#region packages/clients-core/src/client-runtime-service.d.ts
+/**
+ * In-memory runtime service for the global `client.*` contracts.
+ *
+ * The service owns six concerns:
+ * - account identity canonicalization via {@link ClientAccountRegistry}
+ * - latest usage snapshot retention and `client.usage.snapshot` emission
+ * - active account identity tracking (`account.activate` / `account.getActive`)
+ * - CLI-backed client discovery via storage + CLI detection orchestration
+ * - client runtime instance lifecycle via {@link ClientRuntimeRegistry}
+ * - global wiring aggregation via `client.wiring.list` fan-out to enabled clients
+ */
+declare class ClientRuntimeService extends BaseService {
+  private readonly accountRegistry;
+  private readonly runtimeRegistry;
+  private readonly latestSnapshots;
+  /**
+   * Most recently activated account identity per client, keyed by `clientId`.
+   *
+   * Populated by the `account.activate` handler and queried by `account.getActive`.
+   * This allows services (e.g. the Claude Code client) to resolve an active
+   * account identity without requiring a persisted session.
+   */
+  private readonly activeIdentities;
+  /**
+   * Creates a new client runtime service.
+   * @param bus - Bus instance used for client request/event handling
+   * @param accountRegistry - In-memory account registry implementation
+   * @param runtimeRegistry - Registry for client runtime instance lifecycle
+   */
+  constructor(bus?: IMakaioBus, accountRegistry?: ClientAccountRegistry, runtimeRegistry?: ClientRuntimeRegistry);
+  /**
+   * Register client runtime handlers on the bus.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Clear all in-memory state on destroy.
+   */
+  protected onDestroy(): void;
+  /**
+   * Return the latest snapshot retained for an account, if one exists.
+   * @param clientAccountId - Canonical account ID
+   * @returns Latest snapshot or undefined
+   */
+  getLatestSnapshot(clientAccountId: string): ClientUsageSnapshot | undefined;
+  private handleAccountObserve;
+  private handleUsageIngest;
+  private handleRuntimeObserve;
+  private scanClients;
+  private listScannableStoredClients;
+  /**
+   * Fan out a `wiring.list` request to each enabled client and aggregate the
+   * results.
+   *
+   * Only enabled clients respond; clients whose per-client `wiring.list`
+   * handler is not registered are skipped via `requestOptional`, and clients
+   * whose handler throws (I/O error, timeout, etc.) are omitted with a
+   * warning so that one failing client does not break status for the rest.
+   *
+   * The `payload` object accepts three optional filter fields:
+   * - `clientId` — when present, only the matching client is queried.
+   * - `projectDir` — forwarded verbatim to each per-client handler.
+   * - `makaioCommand` — forwarded verbatim to each per-client handler.
+   * @param payload - Filtering options forwarded to each per-client handler.
+   * @returns Aggregated wiring results for all responding enabled clients.
+   */
+  private listWirings;
+  private consolidateMergedSnapshots;
+}
+//#endregion
+//#region packages/clients-core/src/client-profile-service.d.ts
+/**
+ * Handles the `client.profile.*` bus subjects, providing full CRUD for named
+ * client configuration profiles plus filesystem directory management.
+ *
+ * Filesystem layout managed by this service:
+ * ```
+ * {clientsBasePath}/{clientId}/profiles/{name}/
+ * ```
+ */
+declare class ClientProfileService extends BaseService {
+  private readonly clientsBasePath;
+  /**
+   * @param bus - Bus instance used for handler registration and storage requests
+   * @param clientsBasePath - Absolute path to the top-level clients directory
+   *   (e.g. `~/.makaio/clients/`)
+   */
+  constructor(bus: IMakaioBus, clientsBasePath: string);
+  /**
+   * Register all `client.profile.*` handlers.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Register the `client.profile.create` handler.
+   */
+  private registerCreateHandler;
+  /**
+   * Register the `client.profile.list` handler.
+   */
+  private registerListHandler;
+  /**
+   * Register the `client.profile.get` handler.
+   */
+  private registerGetHandler;
+  /**
+   * Register the `client.profile.update` handler.
+   */
+  private registerUpdateHandler;
+  /**
+   * Register the `client.profile.delete` handler.
+   */
+  private registerDeleteHandler;
+  /**
+   * Register the `client.profile.setDefault` handler.
+   */
+  private registerSetDefaultHandler;
+}
+//#endregion
+//#region packages/clients-core/src/client-session-config-service.d.ts
+/**
+ * Handles `client.sessionConfig.*` bus subjects, providing per-session config
+ * directory isolation for client processes.
+ */
+declare class ClientSessionConfigService extends BaseService {
+  private readonly clientsBasePath;
+  private readonly getNow;
+  /**
+   * @param bus - Bus instance used for handler registration and storage requests
+   * @param clientsBasePath - Absolute path to the top-level clients directory
+   *   (e.g. `~/.makaio/clients/`)
+   * @param getNow - Returns the current Unix epoch in milliseconds; injectable
+   *   for deterministic testing (defaults to `Date.now`)
+   */
+  constructor(bus: IMakaioBus, clientsBasePath: string, getNow?: () => number);
+  /**
+   * Register all `client.sessionConfig.*` handlers and run boot-time cleanup.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Resolve the base configuration directory for a session.
+   *
+   * Resolution order:
+   * 1. Explicit `baseConfigDir` from the request payload.
+   * 2. Named profile's `configDir` looked up via storage.
+   * 3. Default profile's `configDir` when no explicit name was provided.
+   * 4. `sessionDir` — the client-owned setup handler decides the actual source
+   *    (e.g. `~/.claude` for Claude Code) when no profile is configured.
+   * @param clientId - Canonicalized stable client identifier
+   * @param sessionDir - Absolute path to the already-created session directory
+   * @param profileName - Optional profile name to look up
+   * @param explicitBaseConfigDir - Caller-supplied override, if any
+   * @returns Resolved absolute path for the base config directory
+   */
+  private resolveBaseConfigDir;
+  /**
+   * Scan session directories and remove those older than {@link SESSION_MAX_AGE_MS}.
+   *
+   * When `clientId` is supplied only that client's sessions are scanned.
+   * Omit it to clean across all clients.
+   * @param clientId - Optional client ID to scope cleanup
+   * @returns Absolute paths of all directories that were removed
+   */
+  private cleanupOrphanedDirs;
+  /**
+   * Remove every per-client config directory for a closed framework session.
+   * @param sessionId - Framework session ID from `session.closed`.
+   */
+  private destroySessionDirsForSessionId;
+  /**
+   * Run client-owned session config teardown before removing the directory.
+   * @param clientId - Canonical client identifier.
+   * @param sessionDir - Absolute session config directory to destroy.
+   */
+  private destroyClientSessionDir;
+  /**
+   * Check whether a stale-looking directory belongs to a still-active session.
+   * @param sessionId - Session directory name.
+   * @returns `true` when the session registry still marks the session active.
+   */
+  private isActiveSession;
+  /**
+   * Resolve a session directory for a canonical client ID.
+   * @param clientId - Canonical client identifier.
+   * @param sessionId - Framework session ID.
+   * @param operation - Operation name used in error messages.
+   * @returns Absolute session directory path.
+   */
+  private resolveClientSessionDir;
+  /**
+   * List all client IDs that currently have a directory under `clientsBasePath`.
+   * @returns Array of directory names (one per client)
+   */
+  private listClientIds;
+}
+//#endregion
+//#region packages/clients-core/src/client-session-observed-semantics.d.ts
+/**
+ * Canonical schema for the raw catch-all hook payload delivered on
+ * `client:<id>.hook.received`.
+ *
+ * Client ingress CLIs are dumb bridges: they accept any native hook event and
+ * publish it verbatim on this subject.  Downstream normalizers are responsible
+ * for interpreting `eventName` and mapping the `payload` to structured
+ * `client.session.*` observations.
+ *
+ * Fields:
+ * - `eventName`   — the hook event name as reported by the client CLI
+ *   (e.g. `'PreToolUse'`, `'Stop'`).
+ * - `receivedAt`  — Unix epoch timestamp in milliseconds when the bridge
+ *   received the hook call.
+ * - `payload`     — raw JSON object forwarded verbatim from the client CLI.
+ * - `metadata`    — optional pass-through metadata added by the bridge (e.g.
+ *   process PID, invocation arguments).
+ */
+declare const RawClientHookPayloadSchema: z.ZodObject<{
+  eventName: z.ZodString;
+  receivedAt: z.ZodNumber;
+  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type RawClientHookPayload = z.infer<typeof RawClientHookPayloadSchema>;
+/**
+ * Normalize user-provided client identifiers to the stable suffix used in
+ * `client:<id>` namespaces.
+ * @param clientId - Raw client identifier, optionally prefixed with `client:`
+ * @param caller - Optional function name used in thrown error messages
+ * @returns Canonical lowercase client identifier without the `client:` prefix
+ */
+declare function canonicalizeClientId(clientId: string, caller?: string): string;
+type RawClientHookSubjectRecord = SubjectRecord<'hook.received', EventMessagePayload<RawClientHookPayload>>;
+/**
+ * Subject definition for the raw catch-all hook event in a concrete
+ * `client:<id>` namespace.
+ */
+type RawClientHookReceivedSubject = SubjectDefinition<RawClientHookSubjectRecord, 'hook.received', `client:${string}`>;
+/**
+ * Build a non-owning subject definition for `client:<id>.hook.received`.
+ *
+ * This is intentionally not a namespace registration. Concrete client packages
+ * own their full `client:<id>` namespace via {@link createClientNamespace}; the
+ * generic CLI bridge only needs to emit the shared hook subject and must not
+ * accidentally register a narrower namespace before the concrete owner loads.
+ * When the concrete owner is loaded, normal bus schema validation applies. When
+ * it is not loaded, the ad-hoc subject still allows the raw event to traverse
+ * transports to a process that owns the namespace.
+ * @param clientId - Stable client identifier, optionally prefixed with `client:`
+ * @returns Non-owning subject definition for the client's raw hook ingress
+ */
+declare function createRawClientHookReceivedSubject(clientId: string): RawClientHookReceivedSubject;
+/**
+ * Trim and return a string value when non-empty, otherwise `undefined`.
+ *
+ * Primitive building block for normalizers that accept `unknown` values from
+ * raw JSON payloads.  Returns `undefined` when the input is not a string, or
+ * is a string that is empty or whitespace-only after trimming.
+ * @param value - Unknown value to inspect.
+ * @returns Trimmed non-empty string, or `undefined`.
+ */
+declare function pickNonEmptyStringValue(value: unknown): string | undefined;
+/**
+ * Extract a non-empty string value from an unknown-typed hook payload object.
+ *
+ * Convenience helper used by client hook normalizers to pick a single key from
+ * a raw JSON payload.  Returns `undefined` when the key is absent, not a
+ * string, or an empty string — so callers can use the `?? undefined` pattern
+ * or spread conditionally without additional checks.
+ * @param payload - Raw hook payload object forwarded by the ingress bridge.
+ * @param key - Property key to read.
+ * @returns Non-empty string value, or `undefined` when absent or empty.
+ */
+declare function pickNonEmptyString(payload: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Options for constructing a {@link ClientSessionObservedBase} payload.
+ */
+interface BuildClientSessionBaseOpts {
+  /** Stable client identifier (e.g. `'codex'`, `'claude-code'`). */
+  clientId: string;
+  /** Framework session ID, if already resolved at emission time. */
+  sessionId?: string;
+  /** Raw session identifier from the client runtime, if available. */
+  adapterSessionId?: string;
+}
+/**
+ * Build a {@link ClientSessionObservedBase} payload for a `client.session.*`
+ * observed-semantics event.
+ *
+ * Always stamps `source: 'adapter-derived'` and `observedAt: Date.now()`.
+ * The optional `sessionId` and `adapterSessionId` fields are omitted when
+ * undefined so Zod validation does not receive explicit `undefined` values.
+ * @param opts - Client and session identifiers for the observation
+ * @returns Base payload ready for emission or spread-extension
+ */
+declare function buildClientSessionBase(opts: BuildClientSessionBaseOpts): ClientSessionObservedBase;
+/**
+ * Execute an async emission thunk best-effort, swallowing any rejection.
+ *
+ * Adapters use this to emit `client.session.*` observed-semantics events
+ * without risking disruption of the core adapter operation when no handler
+ * is registered for the observed-semantics surface.
+ * @param fn - Async emission thunk to execute fire-and-forget
+ */
+declare function emitBestEffort(fn: () => Promise<void>): void;
+//#endregion
+//#region packages/clients-core/src/create-client-namespace.d.ts
+/**
+ * Result returned by {@link createClientNamespace}.
+ * @typeParam AdditionalSchemas - Extra subject schemas registered alongside the
+ *   shared `hook.received` subject.  Defaults to an empty record (no extras).
+ */
+interface ClientNamespaceResult<AdditionalSchemas extends SchemaRecord = Record<never, never>> {
+  /**
+   * The fully-qualified bus namespace domain string (e.g. `'client:codex'`).
+   */
+  readonly namespaceDomain: string;
+  /**
+   * Typed bus subjects for the per-client namespace.
+   *
+   * Always includes `hook.received` for the raw catch-all hook ingress.
+   * When `additionalSchemas` were provided at construction time the extra
+   * subjects are also present here, fully typed.
+   */
+  readonly subjects: ReturnType<typeof buildClientSubjects<AdditionalSchemas>>;
+}
+/**
+ * Build the subjects object for a per-client namespace.
+ *
+ * Extracted to a named generic function so the inferred return type is stable
+ * and can be referenced by {@link ClientNamespaceResult} via instantiation
+ * expressions.
+ * @param clientId - Stable client identifier (e.g. `'codex'`)
+ * @param additionalSchemas - Extra subjects to register alongside `hook.received`
+ * @returns Namespace subjects with `hook.received` plus any additional subjects
+ */
+declare function buildClientSubjects<AdditionalSchemas extends SchemaRecord>(clientId: string, additionalSchemas: AdditionalSchemas): _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<`client:${string}`, {
+  'hook.received': _$zod.ZodObject<{
+    eventName: _$zod.ZodString;
+    receivedAt: _$zod.ZodNumber;
+    payload: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>;
+    metadata: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>>;
+  }, _$zod_v4_core0.$strip>;
+} & AdditionalSchemas>, `client:${string}`>;
+/**
+ * Create (or retrieve) the per-client bus namespace for `client:<clientId>`.
+ *
+ * The namespace is registered idempotently — calling this function multiple
+ * times with the same `clientId` returns equivalent subjects.
+ *
+ * The resulting namespace pre-registers the `hook.received` subject so client
+ * ingress bridges have a consistent raw-event ingress point:
+ *
+ * ```ts
+ * // In @makaio/client-codex
+ * export const { subjects: CodexClientSubjects } = createClientNamespace('codex');
+ * // CodexClientSubjects.hook.received → 'client:codex.hook.received'
+ * ```
+ *
+ * Clients that need extra subjects pass them as the second argument:
+ *
+ * ```ts
+ * // In @makaio/client-claude-code
+ * export const { subjects } = createClientNamespace('claude-code', {
+ *   'statusline.received': ClaudeCodeStatuslinePayloadSchema,
+ * });
+ * // subjects.statusline.received → 'client:claude-code.statusline.received'
+ * ```
+ * @param clientId - Stable client identifier (e.g. `'codex'`,
+ *   `'claude-code'`), optionally prefixed with `client:`.  Canonicalized to
+ *   lowercase and restricted to letters, numbers, and hyphens.
+ * @param additionalSchemas - Optional extra subject schemas to register alongside
+ *   the shared `hook.received` subject.
+ * @returns Namespace domain string and typed bus subjects.
+ */
+declare function createClientNamespace<AdditionalSchemas extends SchemaRecord = Record<never, never>>(clientId: string, additionalSchemas?: AdditionalSchemas): ClientNamespaceResult<AdditionalSchemas>;
+//#endregion
+//#region packages/clients-core/src/wiring-schemas.d.ts
+/**
+ * Non-empty absolute filesystem path.
+ *
+ * Used for `projectDir` across all config and wiring subjects to ensure paths
+ * are not resolved relative to the service process cwd.
+ */
+declare const AbsolutePathSchema: z.ZodString;
+/**
+ * Shared response schema for per-client `wiring.list`.
+ *
+ * Returns all known wiring entries for the requested scope, indicating which
+ * are currently installed.
+ */
+declare const ClientWiringListResponseSchema: z.ZodObject<{
+  entries: z.ZodArray<z.ZodObject<{
+    group: z.ZodString;
+    name: z.ZodString;
+    installed: z.ZodBoolean;
+    command: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Inferred type for {@link ClientWiringListResponseSchema}. */
+type ClientWiringListResponse = z.infer<typeof ClientWiringListResponseSchema>;
+/**
+ * Shared response schema for per-client `wiring.apply`.
+ *
+ * Reports how many entries were written and how many were already in place.
+ */
+declare const ClientWiringApplyResponseSchema: z.ZodObject<{
+  applied: z.ZodNumber;
+  skipped: z.ZodNumber;
+}, z.core.$strip>;
+/** Inferred type for {@link ClientWiringApplyResponseSchema}. */
+type ClientWiringApplyResponse = z.infer<typeof ClientWiringApplyResponseSchema>;
+/**
+ * Shared response schema for per-client `wiring.remove`.
+ *
+ * Reports how many entries were removed from the config file.
+ */
+declare const ClientWiringRemoveResponseSchema: z.ZodObject<{
+  removed: z.ZodNumber;
+}, z.core.$strip>;
+/** Inferred type for {@link ClientWiringRemoveResponseSchema}. */
+type ClientWiringRemoveResponse = z.infer<typeof ClientWiringRemoveResponseSchema>;
+/**
+ * A single client's wiring result in the global aggregation response.
+ *
+ * Returned by `client.wiring.list` for each enabled client that responded
+ * to the per-client `wiring.list` bus request.
+ */
+declare const ClientWiringAggregatedResultSchema: z.ZodObject<{
+  clientId: z.ZodString;
+  entries: z.ZodArray<z.ZodObject<{
+    group: z.ZodString;
+    name: z.ZodString;
+    installed: z.ZodBoolean;
+    command: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Inferred type for {@link ClientWiringAggregatedResultSchema}. */
+type ClientWiringAggregatedResult = z.infer<typeof ClientWiringAggregatedResultSchema>;
+/**
+ * Assert that `projectDir`, when provided, is an absolute path.
+ *
+ * Prevents relative paths from being resolved against the service process cwd
+ * and causing writes to unintended filesystem locations. Used by per-client
+ * wiring handlers as a runtime guard when bus-layer Zod validation may be
+ * skipped in production.
+ * @param projectDir - Path value from the request payload, or `undefined`.
+ * @throws Error When `projectDir` is defined but not an absolute path.
+ */
+declare function assertAbsoluteProjectDir(projectDir: string | undefined): void;
+//#endregion
+//#region packages/clients-core/src/create-client-wiring-list-subject.d.ts
+/** Untyped wiring subject definition returned by {@link createClientWiringSubjectDef}. */
+interface ClientWiringSubjectDefBase {
+  /** Subject key within the client namespace (e.g. `'wiring.list'`). */
+  subject: string;
+  /** Standard `$meta` applied to all per-client wiring subjects. */
+  $meta: {
+    /** Resolved `client:<id>` namespace for this subject. */namespace: string; /** Always `true` — wiring subjects are request/response pairs. */
+    isRequest: true; /** Always `false` — wiring subjects are not local-only. */
+    local: false; /** Always `false` — wiring subjects are not channels. */
+    channel: false;
+  };
+}
+/**
+ * Build a non-owning typed subject definition for any per-client wiring
+ * subject.
+ *
+ * Encapsulates the standard `$meta` structure shared by all
+ * `client:<id>.wiring.*` subjects: `isRequest: true`, `local: false`,
+ * `channel: false`.  The `clientId` is canonicalized via
+ * {@link canonicalizeClientId} so callers need not normalize the input.
+ *
+ * This helper returns a plain object — callers cast it to their concrete
+ * {@link SubjectDefinition} type exactly as `createRawClientHookReceivedSubject`
+ * does.
+ * @param clientId - Stable client identifier, optionally prefixed with `client:`.
+ * @param subjectSuffix - Subject key within the namespace (e.g. `'wiring.list'`).
+ * @returns Plain subject definition object ready to be cast to the concrete type.
+ */
+declare function createClientWiringSubjectDef(clientId: string, subjectSuffix: string): ClientWiringSubjectDefBase;
+/**
+ * Typed payload for the per-client `wiring.list` request/response pair.
+ *
+ * The request accepts an optional `projectDir` and `makaioCommand` — the
+ * same optional filtering fields supported by all known client wiring
+ * implementations.  The response carries an `entries` array.
+ */
+type ClientWiringListPayload = RequestMessagePayload<{
+  projectDir?: string;
+  makaioCommand: string;
+}, {
+  entries: ClientWiringEntry[];
+}>;
+type ClientWiringListSubjectRecord = SubjectRecord<'wiring.list', ClientWiringListPayload>;
+/**
+ * Non-owning typed {@link SubjectDefinition} for `client:<id>.wiring.list`.
+ */
+type ClientWiringListSubjectDef = SubjectDefinition<ClientWiringListSubjectRecord, 'wiring.list', `client:${string}`>;
+/**
+ * Build a non-owning typed {@link SubjectDefinition} for
+ * `client:<clientId>.wiring.list`.
+ *
+ * This is intentionally **not** a namespace registration.  Concrete client
+ * packages own their full `client:<id>` namespace; the aggregator only needs
+ * to dispatch the list request without registering a conflicting namespace.
+ * When the concrete owner is loaded, normal bus schema validation applies;
+ * when it is not, the ad-hoc subject still dispatches locally.
+ * @param clientId - Stable client identifier (e.g. `'claude-code'`,
+ *   `'codex'`), optionally prefixed with `client:`.
+ * @returns Non-owning typed subject definition for the per-client wiring list.
+ */
+declare function createClientWiringListSubjectDef(clientId: string): ClientWiringListSubjectDef;
+//#endregion
+//#region packages/clients-core/src/package.d.ts
+/**
+ * Composite service that initialises and destroys the
+ * {@link ClientRuntimeService}, the {@link ClientBinaryManager}, the
+ * {@link ClientProfileService}, and the {@link ClientSessionConfigService}
+ * under a single {@link ExtensionServiceLifecycle} handle.
+ *
+ * The host coordinator calls `init()` once and `destroy()` once; this class
+ * ensures all four services participate in the same lifecycle without any
+ * requiring knowledge of the others.
+ */
+declare class ClientsCoreService implements ExtensionServiceLifecycle {
+  private readonly runtimeService;
+  private readonly binaryManager;
+  private readonly profileService;
+  private readonly sessionConfigService;
+  /**
+   * @param runtimeService - Handles `client.*` runtime observation subjects
+   * @param binaryManager - Handles `client.*` binary-management subjects
+   * @param profileService - Handles `client.profile.*` CRUD subjects
+   * @param sessionConfigService - Handles `client.sessionConfig.*` isolation subjects
+   */
+  constructor(runtimeService: ClientRuntimeService, binaryManager: ClientBinaryManager, profileService: ClientProfileService, sessionConfigService: ClientSessionConfigService);
+  /**
+   * Initialize all four sub-services in parallel.
+   *
+   * Uses {@link Promise.allSettled} so every service always attempts
+   * initialisation — matching the resilience pattern used by {@link destroy}.
+   * If any service fails, the first rejection is re-thrown after all attempts
+   * have settled.  Secondary failures are logged for observability.
+   */
+  init(): Promise<void>;
+  /**
+   * Destroy all four sub-services in parallel.
+   *
+   * Uses {@link Promise.allSettled} to guarantee every cleanup runs even when
+   * one rejects. Any rejections are logged for observability — matching the
+   * secondary-failure logging pattern used by {@link init}.
+   */
+  destroy(): Promise<void>;
+}
+/** Typed package token for retrieving the clients-core service. */
+declare const ClientsCoreToken: _$_makaio_contracts0.ExtensionToken<ClientsCoreService>;
+/**
+ * Options accepted by {@link createClientsCorePackage}.
+ *
+ * Definitions supplied here are seeded into a {@link ClientDefinitionRegistry}
+ * at construction time, before the coordinator calls `init()` on the returned
+ * service. All definitions must be available before `init()` runs — there is
+ * no post-start mutation path on the service surface.
+ */
+interface ClientsCorePackageOptions {
+  /**
+   * Client definitions to register before service initialisation.
+   *
+   * Typically populated by the boot composition root from discovered client
+   * packages via `loadMakaioExtensions` before calling `coordinator.load`.
+   */
+  readonly definitions?: readonly ClientDefinition[];
+  /**
+   * I/O dependency implementations for the binary install strategies.
+   *
+   * When omitted the manager uses a no-op implementation that throws on every
+   * call — correct for framework-only test callers that do not exercise binary
+   * management, but must be replaced before binary installation is functional.
+   *
+   * Host composition roots pass their concrete strategy dependency
+   * implementation here on real boot paths.
+   */
+  readonly strategyDependencies?: StrategyDependencies;
+  /**
+   * Framework-owned handlers for declarative post-install descriptors.
+   *
+   * Client packages declare `postInstall.kind`; the host supplies the handler
+   * implementation here. Missing handlers fail the install job rather than
+   * silently skipping a declared lifecycle step.
+   *
+   * When omitted no post-install handlers are registered.
+   */
+  readonly postInstallHandlers?: ReadonlyMap<string, PostInstallHandler>;
+}
+/**
+ * Run storage handler registrations and return one cleanup that unwinds every
+ * successful registration in reverse order.
+ *
+ * If any registration throws, previously registered handlers are immediately
+ * rolled back so package startup remains retry-safe.
+ * @param registrations - Ordered storage registration callbacks
+ * @returns Cleanup function for all successful registrations
+ */
+declare function registerStorageHandlersWithRollback(registrations: ReadonlyArray<() => () => void>): () => void;
+/**
+ * Create the MakaioExtension manifest for the in-memory client runtime service
+ * and the client binary manager.
+ *
+ * `@makaio/runtime-node` calls this factory after loading client packages and passes
+ * the resulting manifest to the extension coordinator. Definitions supplied
+ * via {@link ClientsCorePackageOptions.definitions} are seeded into a
+ * {@link ClientDefinitionRegistry} before `init()` runs, so
+ * `client.list` returns managed clients immediately after service startup.
+ * @example
+ * ```ts
+ * const clientPackages = await loadMakaioExtensions(discoveredClients, { importModule });
+ * const pkg = createClientsCorePackage({
+ *   definitions: clientPackages.flatMap((p) => p.clients ?? []),
+ * });
+ * coordinator.load([pkg, ...otherPackages], configDefaults);
+ * await coordinator.startAll();
+ * ```
+ * @param options - Package options including pre-seeded client definitions,
+ *   strategy I/O dependencies, and post-install handlers
+ * @returns Configured MakaioExtension manifest
+ */
+declare function createClientsCorePackage(options?: ClientsCorePackageOptions): MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region packages/clients-core/src/storage/client-binary-storage-namespace.d.ts
+/**
+ * Zod schema for a persisted installed-version record transported over the bus.
+ */
+declare const ClientBinaryVersionRecordSchema: z.ZodObject<{
+  id: z.ZodString;
+  clientId: z.ZodString;
+  version: z.ZodString;
+  installPath: z.ZodString;
+  installedAt: z.ZodNumber;
+  createdAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Zod schema for the per-client binary state record transported over the bus.
+ */
+declare const ClientBinaryStateRecordSchema: z.ZodObject<{
+  clientId: z.ZodString;
+  activeVersion: z.ZodNullable<z.ZodString>;
+  latestAvailableVersion: z.ZodNullable<z.ZodString>;
+  latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+  latestVersionSourceStatus: z.ZodEnum<{
+    error: "error";
+    fresh: "fresh";
+    cached: "cached";
+  }>;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Internal bus namespace for client binary storage operations.
+ *
+ * Subjects registered here are consumed exclusively by the Drizzle handler
+ * and the binary manager — they are not part of the public `client.*` namespace.
+ */
+declare const ClientBinaryStorageNamespace: _$_makaio_core0.BusNamespaceDefinition<"client-binary:storage", {
+  /** Insert a new installed-version row. */insertVersion: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+      clientId: z.ZodString;
+      version: z.ZodString;
+      installPath: z.ZodString;
+      installedAt: z.ZodNumber;
+      createdAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically record an installed version and optionally mark it active.
+   *
+   * Used by successful install/update jobs so storage never commits a version
+   * row without the requested active pointer update.
+   */
+  recordInstalledVersion: {
+    request: z.ZodObject<{
+      versionRecord: z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>;
+      makeActive: z.ZodBoolean;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  }; /** Return all installed-version rows for a given client. */
+  listVersions: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Return a single-client state + installed-version snapshot from one storage
+   * read boundary.
+   */
+  getSnapshot: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      state: z.ZodNullable<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all installed-version rows across every client (used for boot hydration). */
+  loadAllVersions: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Upsert the per-client binary state row (active version + feed cache). */
+  upsertState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      latestAvailableVersion: z.ZodNullable<z.ZodString>;
+      latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+      latestVersionSourceStatus: z.ZodEnum<{
+        error: "error";
+        fresh: "fresh";
+        cached: "cached";
+      }>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set the active version without touching feed-cache fields.
+   *
+   * Creates a minimal state row when one does not exist yet.
+   */
+  setActiveVersion: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  }; /** Return the per-client binary state row, or `null` when it does not exist. */
+  getState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      state: z.ZodNullable<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return the state rows for all clients (used for boot hydration). */
+  loadAllState: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      states: z.ZodArray<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all state and installed-version rows from one storage read boundary. */
+  loadSnapshot: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      states: z.ZodArray<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Persist an updated feed-cache entry for a client.
+   *
+   * This is a subset of `upsertState` — the handler merges the feed fields
+   * into the existing row (or creates a minimal row) without touching
+   * `activeVersion`.
+   */
+  updateFeedCache: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      latestAvailableVersion: z.ZodNullable<z.ZodString>;
+      latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+      latestVersionSourceStatus: z.ZodEnum<{
+        error: "error";
+        fresh: "fresh";
+        cached: "cached";
+      }>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically remove an installed-version row and clear the active-version
+   * pointer when it currently points to the deleted version.
+   *
+   * Both operations are executed inside a single SQLite transaction so that
+   * concurrent reads never observe a state where the version row is absent but
+   * the active pointer still references it.
+   */
+  removeVersionAndClearActive: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      version: z.ZodString;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      removedVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  };
+}>;
+/** Typed bus subjects for client binary storage. */
+declare const ClientBinaryStorageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"client-binary:storage", {
+  /** Insert a new installed-version row. */insertVersion: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+      clientId: z.ZodString;
+      version: z.ZodString;
+      installPath: z.ZodString;
+      installedAt: z.ZodNumber;
+      createdAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically record an installed version and optionally mark it active.
+   *
+   * Used by successful install/update jobs so storage never commits a version
+   * row without the requested active pointer update.
+   */
+  recordInstalledVersion: {
+    request: z.ZodObject<{
+      versionRecord: z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>;
+      makeActive: z.ZodBoolean;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  }; /** Return all installed-version rows for a given client. */
+  listVersions: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Return a single-client state + installed-version snapshot from one storage
+   * read boundary.
+   */
+  getSnapshot: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      state: z.ZodNullable<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all installed-version rows across every client (used for boot hydration). */
+  loadAllVersions: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Upsert the per-client binary state row (active version + feed cache). */
+  upsertState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      latestAvailableVersion: z.ZodNullable<z.ZodString>;
+      latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+      latestVersionSourceStatus: z.ZodEnum<{
+        error: "error";
+        fresh: "fresh";
+        cached: "cached";
+      }>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set the active version without touching feed-cache fields.
+   *
+   * Creates a minimal state row when one does not exist yet.
+   */
+  setActiveVersion: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  }; /** Return the per-client binary state row, or `null` when it does not exist. */
+  getState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      state: z.ZodNullable<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return the state rows for all clients (used for boot hydration). */
+  loadAllState: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      states: z.ZodArray<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all state and installed-version rows from one storage read boundary. */
+  loadSnapshot: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      states: z.ZodArray<z.ZodObject<{
+        clientId: z.ZodString;
+        activeVersion: z.ZodNullable<z.ZodString>;
+        latestAvailableVersion: z.ZodNullable<z.ZodString>;
+        latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+        latestVersionSourceStatus: z.ZodEnum<{
+          error: "error";
+          fresh: "fresh";
+          cached: "cached";
+        }>;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+      versions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        version: z.ZodString;
+        installPath: z.ZodString;
+        installedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Persist an updated feed-cache entry for a client.
+   *
+   * This is a subset of `upsertState` — the handler merges the feed fields
+   * into the existing row (or creates a minimal row) without touching
+   * `activeVersion`.
+   */
+  updateFeedCache: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      latestAvailableVersion: z.ZodNullable<z.ZodString>;
+      latestVersionLastCheckedAt: z.ZodNullable<z.ZodNumber>;
+      latestVersionSourceStatus: z.ZodEnum<{
+        error: "error";
+        fresh: "fresh";
+        cached: "cached";
+      }>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically remove an installed-version row and clear the active-version
+   * pointer when it currently points to the deleted version.
+   *
+   * Both operations are executed inside a single SQLite transaction so that
+   * concurrent reads never observe a state where the version row is absent but
+   * the active pointer still references it.
+   */
+  removeVersionAndClearActive: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      version: z.ZodString;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      previousActiveVersion: z.ZodNullable<z.ZodString>;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      removedVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+  };
+}>, "client-binary:storage">;
+/** Persisted installed-version record as exchanged over the bus. */
+type ClientBinaryVersionRecord = z.infer<typeof ClientBinaryVersionRecordSchema>;
+/** Per-client binary state record as exchanged over the bus. */
+type ClientBinaryStateRecord = z.infer<typeof ClientBinaryStateRecordSchema>;
+//#endregion
+//#region packages/clients-core/src/storage/runtime-storage-namespace.d.ts
+/**
+ * Zod schema for a fully-populated runtime record transported over the bus.
+ *
+ * Mirrors {@link ClientRuntimeRecord} with explicit Zod types so the bus can
+ * validate payloads at runtime.
+ */
+declare const RuntimeRecordSchema: z.ZodObject<{
+  clientRuntimeId: z.ZodString;
+  clientId: z.ZodString;
+  status: z.ZodEnum<{
+    started: "started";
+    observed: "observed";
+  }>;
+  supervisorSessionId: z.ZodOptional<z.ZodString>;
+  pid: z.ZodOptional<z.ZodNumber>;
+  parentPid: z.ZodOptional<z.ZodNumber>;
+  adapterSessionId: z.ZodOptional<z.ZodString>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  cwd: z.ZodOptional<z.ZodString>;
+  argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  observedAt: z.ZodNumber;
+  createdAt: z.ZodNumber;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Internal bus namespace for client runtime storage operations.
+ *
+ * Subjects registered here are consumed exclusively by the Drizzle handler
+ * and the registry — they are not part of the public `client.*` namespace.
+ */
+declare const ClientRuntimeStorageNamespace: _$_makaio_core0.BusNamespaceDefinition<"client-runtime:storage", {
+  upsert: {
+    request: z.ZodObject<{
+      clientRuntimeId: z.ZodString;
+      clientId: z.ZodString;
+      status: z.ZodEnum<{
+        started: "started";
+        observed: "observed";
+      }>;
+      supervisorSessionId: z.ZodOptional<z.ZodString>;
+      pid: z.ZodOptional<z.ZodNumber>;
+      parentPid: z.ZodOptional<z.ZodNumber>;
+      adapterSessionId: z.ZodOptional<z.ZodString>;
+      sessionId: z.ZodOptional<z.ZodString>;
+      cwd: z.ZodOptional<z.ZodString>;
+      argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      observedAt: z.ZodNumber;
+      createdAt: z.ZodNumber;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  loadAll: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      records: z.ZodArray<z.ZodObject<{
+        clientRuntimeId: z.ZodString;
+        clientId: z.ZodString;
+        status: z.ZodEnum<{
+          started: "started";
+          observed: "observed";
+        }>;
+        supervisorSessionId: z.ZodOptional<z.ZodString>;
+        pid: z.ZodOptional<z.ZodNumber>;
+        parentPid: z.ZodOptional<z.ZodNumber>;
+        adapterSessionId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        observedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+}>;
+/** Typed bus subjects for client runtime storage. */
+declare const ClientRuntimeStorageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"client-runtime:storage", {
+  upsert: {
+    request: z.ZodObject<{
+      clientRuntimeId: z.ZodString;
+      clientId: z.ZodString;
+      status: z.ZodEnum<{
+        started: "started";
+        observed: "observed";
+      }>;
+      supervisorSessionId: z.ZodOptional<z.ZodString>;
+      pid: z.ZodOptional<z.ZodNumber>;
+      parentPid: z.ZodOptional<z.ZodNumber>;
+      adapterSessionId: z.ZodOptional<z.ZodString>;
+      sessionId: z.ZodOptional<z.ZodString>;
+      cwd: z.ZodOptional<z.ZodString>;
+      argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      observedAt: z.ZodNumber;
+      createdAt: z.ZodNumber;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  loadAll: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      records: z.ZodArray<z.ZodObject<{
+        clientRuntimeId: z.ZodString;
+        clientId: z.ZodString;
+        status: z.ZodEnum<{
+          started: "started";
+          observed: "observed";
+        }>;
+        supervisorSessionId: z.ZodOptional<z.ZodString>;
+        pid: z.ZodOptional<z.ZodNumber>;
+        parentPid: z.ZodOptional<z.ZodNumber>;
+        adapterSessionId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        argv: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        observedAt: z.ZodNumber;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+}>, "client-runtime:storage">;
+//#endregion
+//#region packages/clients-core/src/storage/profile-storage-namespace.d.ts
+/**
+ * Zod schema for a persisted client profile record transported over the bus.
+ *
+ * Reuses {@link ClientProfileSchema} from contracts so the storage namespace
+ * and the public client contract share a single source of truth.
+ */
+declare const ClientProfileRecordSchema: z.ZodObject<{
+  id: z.ZodString;
+  clientId: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodNullable<z.ZodString>;
+  configDir: z.ZodString;
+  isDefault: z.ZodBoolean;
+  createdAt: z.ZodNumber;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Internal bus namespace for client profile storage operations.
+ *
+ * Subjects registered here are consumed exclusively by the Drizzle handler
+ * and the profile manager — they are not part of the public `client.*` namespace.
+ */
+declare const ClientProfileStorageNamespace: _$_makaio_core0.BusNamespaceDefinition<"client-profile:storage", {
+  /** Return a single profile record identified by `(clientId, name)`, or `null` when not found. */get: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return a single profile record by its stable row ID, or `null` when not found. */
+  getById: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all profile records for a given client. */
+  list: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      records: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Insert or update a profile record identified by its stable row ID.
+   *
+   * On conflict, all mutable fields (`name`, `description`, `configDir`,
+   * `isDefault`, `updatedAt`) are overwritten. `createdAt` is preserved on
+   * subsequent upserts.
+   */
+  set: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+      clientId: z.ZodString;
+      name: z.ZodString;
+      description: z.ZodNullable<z.ZodString>;
+      configDir: z.ZodString;
+      isDefault: z.ZodBoolean;
+      createdAt: z.ZodNumber;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Delete the profile record identified by `(clientId, name)`.
+   *
+   * Returns `{ success: true }` when a row was deleted and
+   * `{ success: false }` when no matching row was found.
+   */
+  delete: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Clear the `isDefault` flag on all profiles for a given client.
+   *
+   * Low-level maintenance operation. Normal default promotion must use
+   * `setDefault` so clearing and promotion share one storage transaction.
+   */
+  clearDefault: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically promote one profile to default and clear the previous default.
+   */
+  setDefault: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+}>;
+/** Typed bus subjects for client profile storage. */
+declare const ClientProfileStorageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"client-profile:storage", {
+  /** Return a single profile record identified by `(clientId, name)`, or `null` when not found. */get: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return a single profile record by its stable row ID, or `null` when not found. */
+  getById: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Return all profile records for a given client. */
+  list: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      records: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Insert or update a profile record identified by its stable row ID.
+   *
+   * On conflict, all mutable fields (`name`, `description`, `configDir`,
+   * `isDefault`, `updatedAt`) are overwritten. `createdAt` is preserved on
+   * subsequent upserts.
+   */
+  set: {
+    request: z.ZodObject<{
+      id: z.ZodString;
+      clientId: z.ZodString;
+      name: z.ZodString;
+      description: z.ZodNullable<z.ZodString>;
+      configDir: z.ZodString;
+      isDefault: z.ZodBoolean;
+      createdAt: z.ZodNumber;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Delete the profile record identified by `(clientId, name)`.
+   *
+   * Returns `{ success: true }` when a row was deleted and
+   * `{ success: false }` when no matching row was found.
+   */
+  delete: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Clear the `isDefault` flag on all profiles for a given client.
+   *
+   * Low-level maintenance operation. Normal default promotion must use
+   * `setDefault` so clearing and promotion share one storage transaction.
+   */
+  clearDefault: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Atomically promote one profile to default and clear the previous default.
+   */
+  setDefault: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      name: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      record: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        clientId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        configDir: z.ZodString;
+        isDefault: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+}>, "client-profile:storage">;
+/** Persisted client profile record as exchanged over the bus. */
+type ClientProfileRecord = z.infer<typeof ClientProfileRecordSchema>;
+//#endregion
+//#region packages/clients-core/src/resolve-client-binary.d.ts
+/**
+ * Resolve the execution context for a client binary via the bus.
+ *
+ * Uses `requestOptional` so the adapter continues to function in
+ * framework-only boot where no `client.resolveBinary` handler is registered.
+ * In that case `undefined` is returned and callers fall back to PATH lookup.
+ * @param clientId - Stable client identifier to resolve (e.g. `'claude-code'`)
+ * @returns Resolved execution context (source `'managed'` or `'global'`), or
+ *   `undefined` when no `client.resolveBinary` handler is registered
+ *   (framework-only boot)
+ */
+declare function resolveClientBinary(clientId: string): Promise<ClientExecutionContext | undefined>;
+//#endregion
+//#region packages/clients-core/src/wiring-helpers.d.ts
+/**
+ * Minimal descriptor for a single session-event wiring entry.
+ *
+ * Produced by {@link deriveSessionEventDescriptors} and consumed by the
+ * per-client `buildWiringList`, `applyWiring`, and `removeWiring` functions to
+ * iterate over the events that need hook installation.
+ */
+interface SessionEventDescriptor {
+  /** Native event name as declared in the client definition (e.g. `'SessionStart'`). */
+  readonly eventName: string;
+}
+/**
+ * Build a shell-safe client command string from an executable and argv tokens.
+ *
+ * Native client settings store command strings rather than argv arrays, so the
+ * executable and arguments must be rendered with shell quoting before they are
+ * persisted.
+ *
+ * When `envPairs` is provided, each `KEY=value` string is prepended before the
+ * executable as inline environment variable assignments — the standard POSIX
+ * shell pattern for per-command env overrides.
+ * @param makaioCommand - Makaio CLI binary name or absolute path.
+ * @param args - Argument tokens appended after the Makaio command.
+ * @param envPairs - Optional `KEY=value` pairs prepended before the executable.
+ * @returns Shell-safe command string.
+ */
+declare function buildClientCommand(makaioCommand: string, args: readonly string[], envPairs?: readonly string[]): string;
+/**
+ * Build the full hook command string for a single session-event wiring entry.
+ *
+ * The resulting command takes the form:
+ * `[envPairs...] <makaioCommand> <sentinel> <eventName>`
+ *
+ * For example, given `'makaio'`, `'hook received claude-code'`, `'SessionStart'`
+ * the function returns `'makaio hook received claude-code SessionStart'`.
+ * @param makaioCommand - Makaio CLI binary name or path (e.g. `'makaio'`).
+ * @param sentinel - Client-specific sentinel string embedded in every Makaio
+ *   hook command (e.g. `'hook received claude-code'`).
+ * @param eventName - Native hook event name (e.g. `'SessionStart'`).
+ * @param envPairs - Optional `KEY=value` pairs prepended before the executable.
+ * @returns Full hook command string to write into the client's native config.
+ */
+declare function buildHookCommand(makaioCommand: string, sentinel: string, eventName: string, envPairs?: readonly string[]): string;
+/**
+ * Derive the ordered list of session-event wiring descriptors from a client
+ * definition.
+ *
+ * Only hook events that carry a `frameworkSubject` are included — events
+ * without one are client-internal and do not need framework wiring.
+ * @param clientDefinition - The parsed static client definition whose
+ *   `runtimeCapabilities.hookEvents` array is the source of truth.
+ * @returns Read-only array of `{ eventName }` descriptors in declaration order.
+ */
+declare function deriveSessionEventDescriptors(clientDefinition: ClientDefinition$1): ReadonlyArray<SessionEventDescriptor>;
+//#endregion
+export { AbsolutePathSchema, type AtomicContentParser, type AtomicModifier, type AtomicModifyOutcome, BinaryNotFoundError, type BuildClientSessionBaseOpts, CLIENT_RUNTIME_STATUSES, ClientAccountRegistry, type ClientAccountUpsertResult, ClientBinaryFeedCache, ClientBinaryJobRunner, ClientBinaryManager, type ClientBinaryManagerConfig, type ClientBinaryStateRecord, ClientBinaryStateRecordSchema, ClientBinaryStorageNamespace, ClientBinaryStorageSubjects, type ClientBinaryVersionRecord, ClientBinaryVersionRecordSchema, ClientBinaryVersionResolver, type ClientDefinitionLookup, ClientDefinitionRegistry, type ClientNamespaceResult, type ClientProfileRecord, ClientProfileRecordSchema, ClientProfileService, ClientProfileStorageNamespace, ClientProfileStorageSubjects, type ClientRuntimeRecord, ClientRuntimeRegistry, ClientRuntimeService, type ClientRuntimeStatus, ClientRuntimeStorageNamespace, ClientRuntimeStorageSubjects, ClientSessionConfigService, ClientSubjects, type ClientWiringAggregatedResult, ClientWiringAggregatedResultSchema, type ClientWiringApplyResponse, ClientWiringApplyResponseSchema, type ClientWiringEntry, ClientWiringEntrySchema, type ClientWiringListResponse, ClientWiringListResponseSchema, type ClientWiringListSubjectDef, type ClientWiringRemoveResponse, ClientWiringRemoveResponseSchema, type ClientWiringSubjectDefBase, type ClientsCorePackageOptions, ClientsCoreService, ClientsCoreToken, type FeedFetcher, type InstallJob, type JobCompletedCallback, type JobCompletionCallback, type JobCompletionResult, type JobProgressCallback, type LatestVersionMeta, type PostInstallContext, type PostInstallHandler, type RawClientHookPayload, RawClientHookPayloadSchema, type RawClientHookReceivedSubject, type ResolvedInstallVersion, RuntimeRecordSchema, type RuntimeUpsertResult, type SessionEventDescriptor, type StrategyDependencies, assertAbsoluteProjectDir, atomicModifyFile, buildClientCommand, buildClientSessionBase, buildHookCommand, canonicalizeClientId, createClientNamespace, createClientWiringListSubjectDef, createClientWiringSubjectDef, createClientsCorePackage, createRawClientHookReceivedSubject, deriveSessionEventDescriptors, emitBestEffort, isPathWithinBase, pickNonEmptyString, pickNonEmptyStringValue, registerStorageHandlersWithRollback, resolveAndValidateBasePath, resolveClientBinary };