@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/clients/index.d.mts

@@ -0,0 +1,2639 @@
+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, 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, ManagedInstallDescriptor, ManagedInstallStrategy, PostInstallDescriptor } from "@makaio/framework/contracts/client";
+import * as _$zod_v4_core0 from "zod/v4/core";
+
+//#region subsystems/client/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 subsystems/client/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 subsystems/client/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 subsystems/client/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. `cwd` sets the working
+   *   directory; `env` is merged on top of the parent environment when present
+   *   (when absent the parent environment is inherited unchanged).
+   * @returns Trimmed stdout string.
+   */
+  exec(command: string, args: string[], options?: {
+    cwd?: string;
+    env?: Record<string, 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 subsystems/client/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}/`.
+ */
+interface ClientBinaryJobRunnerConfig {
+  /**
+   * Absolute base directory under which all managed binary versions are
+   * installed (e.g. `~/.makaio/binaries/`).
+   */
+  basePath: 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>;
+}
+/**
+ * Configuration for the managed binary manager.
+ */
+interface ClientBinaryManagerConfig extends ClientBinaryJobRunnerConfig {
+  /**
+   * 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;
+}
+/**
+ * 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 subsystems/client/src/client-binary-manager.d.ts
+/**
+ * In-memory manager for the global `client.*` binary-management contracts.
+ *
+ * **Responsibilities:**
+ * - 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.
+ *
+ * **Pin-only installs:** version resolution is always derived from the
+ * descriptor pin. No upstream feed fetches are performed at runtime; the
+ * version is determined statically from the client package.
+ */
+declare class ClientBinaryManager extends BaseService {
+  private readonly config;
+  private readonly definitionLookup;
+  private readonly versionResolver;
+  private readonly jobRunner;
+  private readonly strategyDeps;
+  private readonly resolvedBasePath;
+  private readonly resolvedConfigBasePath;
+  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);
+  /**
+   * 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.
+   * @returns Assembled list of client binary entries
+   */
+  private handleList;
+  /**
+   * Enqueue a background install job for a managed client binary.
+   *
+   * Resolves the target version from the descriptor pin (or validates the
+   * explicit version against it) 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 (must match the
+   *   descriptor pin), or `undefined` to use the pin directly
+   * @returns Job acknowledgement with resolved version
+   */
+  private handleInstall;
+  /**
+   * Install the descriptor pin and activate it.
+   *
+   * Resolves the version from the descriptor pin and enqueues a job with
+   * `makeActive: true`. No upstream feed fetch is performed.
+   * @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.
+   * @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;
+  /**
+   * 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.
+   *
+   * Primes the managed config directory for the installed client, then persists
+   * the installed version to storage and optionally sets it as active, then
+   * emits `client.version.changed` with the originating operation reason.
+   *
+   * **Order of operations:**
+   * 1. Prime the managed config directory (blocking, no-op if no handler).
+   * 2. Record the installed version and optional activation atomically.
+   * 3. Emit `client.version.changed` on activation (best-effort).
+   *
+   * **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;
+  /**
+   * Resolve the managed config directory for a client.
+   *
+   * The managed config directory follows the convention established by
+   * {@link ClientBinaryManagerConfig.configBasePath}:
+   * `{configBasePath}/{clientId}/config/`.
+   * @param clientId - Stable client identifier.
+   * @returns Absolute path to the client's managed config directory.
+   */
+  private resolveManagedConfigDir;
+}
+//#endregion
+//#region subsystems/client/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 - Job-runner configuration
+   */
+  constructor(strategyDeps: StrategyDependencies, config: ClientBinaryJobRunnerConfig);
+  /**
+   * 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;
+  /**
+   * Execute the install strategy and clean the target directory if the strategy
+   * fails after staging files.
+   * @param job - Running job descriptor.
+   * @param strategy - Concrete install strategy.
+   * @param targetDir - Versioned install directory.
+   * @param onProgress - Progress notification callback.
+   * @returns Normalized install artifact from the strategy.
+   */
+  private executeStrategy;
+  /**
+   * 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 subsystems/client/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 subsystems/client/src/client-binary-version-resolver.d.ts
+/**
+ * Resolution result returned by {@link ClientBinaryVersionResolver.resolveInstallVersion}.
+ */
+interface ResolvedInstallVersion {
+  /**
+   * Concrete version string to install.
+   *
+   * Always equals the pinned version from the descriptor. When an explicit
+   * version was supplied by the caller it has been validated to match the pin.
+   */
+  readonly version: string;
+  /**
+   * `true` when the version was supplied explicitly by the caller and matches
+   * the descriptor pin; `false` when the pin was used directly.
+   */
+  readonly explicit: boolean;
+}
+/**
+ * Synchronous, stateless version resolver for managed client binaries.
+ *
+ * The resolver enforces the pin-only install contract:
+ * - When no explicit version is supplied, it returns the descriptor pin.
+ * - When an explicit version is supplied, it is accepted only when it equals
+ *   the descriptor pin; any mismatch throws immediately so the caller can
+ *   reject the request with a clear message.
+ *
+ * No network calls, no cache, no async I/O. The concrete version is always
+ * known at construction time from the descriptor.
+ */
+declare class ClientBinaryVersionResolver {
+  /**
+   * Resolve the version to install for a `client.install` request.
+   *
+   * When `explicitVersion` is `undefined`, the descriptor pin is returned
+   * directly. When `explicitVersion` is provided, it must exactly match the
+   * pin or an error is thrown. Whitespace-only explicit versions are also
+   * rejected.
+   * @param clientId - Stable client identifier (e.g. `'claude-code'`)
+   * @param descriptor - Managed install descriptor carrying the pinned version
+   * @param explicitVersion - Version string supplied by the caller, or
+   *   `undefined` to use the descriptor pin
+   * @returns Resolved version and whether it was explicitly requested
+   * @throws When `explicitVersion` is an empty/whitespace-only string
+   * @throws When `explicitVersion` does not match the descriptor pin
+   */
+  resolveInstallVersion(clientId: string, descriptor: ManagedInstallDescriptor, explicitVersion?: string): ResolvedInstallVersion;
+}
+//#endregion
+//#region subsystems/client/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 subsystems/client/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 subsystems/client/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 subsystems/client/src/client-config-prime-service.d.ts
+/**
+ * Handles the generic `client.config.prime` request subject.
+ */
+declare class ClientConfigPrimeService extends BaseService {
+  /**
+   * @param bus - Bus instance used for handler registration and delegation.
+   */
+  constructor(bus?: IMakaioBus);
+  /**
+   * Register the generic config-prime handler.
+   */
+  protected onInit(): void;
+}
+//#endregion
+//#region subsystems/client/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 subsystems/client/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 subsystems/client/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;
+/**
+ * Default timeout in milliseconds for hook handle requests.
+ *
+ * Shared between the CLI schema default (client-hooks extension) and the
+ * wiring descriptor trailing flags (claude-code client) so both always agree
+ * on the configured wait budget without independent magic numbers.
+ */
+declare const DEFAULT_HOOK_HANDLE_TIMEOUT_MS = 5000;
+/**
+ * Schema for the response payload returned by a `makaio hook handle` command.
+ *
+ * The client binary reads this from the command's stdout after the process
+ * exits.  All fields default to safe zero-values so partial responses are
+ * still valid.
+ *
+ * Fields:
+ * - `exitCode` — process exit code the binary should use (0–255). Defaults to `0`.
+ * - `stdout`   — text written to stdout, forwarded verbatim to the client.
+ *   Defaults to `''`.
+ * - `stderr`   — text written to stderr, forwarded verbatim to the client.
+ *   Defaults to `''`.
+ */
+declare const ClientHookHandleResponseSchema: z.ZodObject<{
+  exitCode: z.ZodDefault<z.ZodNumber>;
+  stdout: z.ZodDefault<z.ZodString>;
+  stderr: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type ClientHookHandleResponse = z.infer<typeof ClientHookHandleResponseSchema>;
+type RawClientHookHandleSubjectRecord = SubjectRecord<'hook.handle', RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>>;
+/**
+ * Subject definition for the raw hook handle request/response subject in a
+ * concrete `client:<id>` namespace.
+ *
+ * Carries `RequestMessagePayload<RawClientHookPayload, ClientHookHandleResponse>`
+ * as a phantom type so `bus.requestOptional` infers the correct generics without
+ * additional type annotations at the call site.
+ */
+type RawClientHookHandleSubject = SubjectDefinition<RawClientHookHandleSubjectRecord, 'hook.handle', `client:${string}`>;
+/**
+ * Build a non-owning subject definition for `client:<id>.hook.handle`.
+ *
+ * The returned definition uses `isRequest: true` so the bus dispatches it
+ * through the request/response pipeline.  Concrete client packages own their
+ * full `client:<id>` namespace via {@link createClientNamespace}; this helper
+ * is intentionally non-owning for the same reasons as
+ * {@link createRawClientHookReceivedSubject} — see that function's doc for
+ * the full rationale.
+ * @param rawClientId - Stable client identifier, optionally prefixed with `client:`
+ * @returns Non-owning subject definition for the client's raw hook handle ingress
+ */
+declare function createRawClientHookHandleSubject(rawClientId: string): RawClientHookHandleSubject;
+/**
+ * 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 subsystems/client/src/create-client-namespace.d.ts
+/**
+ * Result returned by {@link createClientNamespace}.
+ * @typeParam AdditionalSchemas - Extra subject schemas registered alongside the
+ *   shared hook subjects.  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 raw hook ingress and `hook.handle` for
+   * hook request handling.
+   * 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 the shared
+ *   hook subjects.
+ * @returns Namespace subjects with shared hook subjects 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>;
+  'hook.handle': {
+    request: _$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>;
+    response: _$zod.ZodObject<{
+      exitCode: _$zod.ZodDefault<_$zod.ZodNumber>;
+      stdout: _$zod.ZodDefault<_$zod.ZodString>;
+      stderr: _$zod.ZodDefault<_$zod.ZodString>;
+    }, _$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` and `hook.handle`
+ * subjects so client bridges have consistent hook ingress and request handling
+ * points:
+ *
+ * ```ts
+ * // In @makaio/client-codex
+ * export const { subjects: CodexClientSubjects } = createClientNamespace('codex');
+ * // CodexClientSubjects.hook.received → 'client:codex.hook.received'
+ * // CodexClientSubjects.hook.handle → 'client:codex.hook.handle'
+ * ```
+ *
+ * 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 subjects.  Must not include `hook.received` or `hook.handle`.
+ * @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 subsystems/client/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 subsystems/client/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 subsystems/client/src/package.d.ts
+/**
+ * Composite service that initialises and destroys the
+ * {@link ClientRuntimeService}, the {@link ClientBinaryManager}, the
+ * {@link ClientConfigPrimeService}, 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 five 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 configPrimeService;
+  private readonly profileService;
+  private readonly sessionConfigService;
+  /**
+   * @param runtimeService - Handles `client.*` runtime observation subjects
+   * @param binaryManager - Handles `client.*` binary-management subjects
+   * @param configPrimeService - Handles generic `client.config.prime` delegation
+   * @param profileService - Handles `client.profile.*` CRUD subjects
+   * @param sessionConfigService - Handles `client.sessionConfig.*` isolation subjects
+   */
+  constructor(runtimeService: ClientRuntimeService, binaryManager: ClientBinaryManager, configPrimeService: ClientConfigPrimeService, profileService: ClientProfileService, sessionConfigService: ClientSessionConfigService);
+  /**
+   * Initialize all five 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 five 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 subsystems/client/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>;
+  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>;
+        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. */
+  upsertState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set the active version, creating a 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>;
+        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>;
+        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>;
+        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>;
+  };
+  /**
+   * 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>;
+        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. */
+  upsertState: {
+    request: z.ZodObject<{
+      clientId: z.ZodString;
+      activeVersion: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set the active version, creating a 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>;
+        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>;
+        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>;
+        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>;
+  };
+  /**
+   * 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 subsystems/client/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 subsystems/client/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 subsystems/client/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 subsystems/client/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;
+  /**
+   * Hook interaction mode for this event.
+   *
+   * - `'event'` — fire-and-forget: install `makaio hook received ...`
+   * - `'request'` — request/response: install `makaio hook handle ...`
+   */
+  readonly mode: 'event' | 'request';
+}
+/**
+ * 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.
+ * @param rootFlags - Optional root-level CLI flags inserted between the
+ *   executable and the sentinel (e.g. `['--debounce-failure']`).
+ * @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[], rootFlags?: 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, mode }` 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, ClientBinaryJobRunner, ClientBinaryManager, type ClientBinaryManagerConfig, type ClientBinaryStateRecord, ClientBinaryStateRecordSchema, ClientBinaryStorageNamespace, ClientBinaryStorageSubjects, type ClientBinaryVersionRecord, ClientBinaryVersionRecordSchema, ClientBinaryVersionResolver, ClientConfigPrimeService, type ClientDefinitionLookup, ClientDefinitionRegistry, type ClientHookHandleResponse, ClientHookHandleResponseSchema, 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, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, type InstallJob, type JobCompletedCallback, type JobCompletionCallback, type JobCompletionResult, type JobProgressCallback, type PostInstallContext, type PostInstallHandler, type RawClientHookHandleSubject, type RawClientHookPayload, RawClientHookPayloadSchema, type RawClientHookReceivedSubject, type ResolvedInstallVersion, RuntimeRecordSchema, type RuntimeUpsertResult, type SessionEventDescriptor, type StrategyDependencies, assertAbsoluteProjectDir, atomicModifyFile, buildClientCommand, buildClientSessionBase, buildHookCommand, canonicalizeClientId, createClientNamespace, createClientWiringListSubjectDef, createClientWiringSubjectDef, createClientsCorePackage, createRawClientHookHandleSubject, createRawClientHookReceivedSubject, deriveSessionEventDescriptors, emitBestEffort, isPathWithinBase, pickNonEmptyString, pickNonEmptyStringValue, registerStorageHandlersWithRollback, resolveAndValidateBasePath, resolveClientBinary };