@makaio/client-codex 1.0.0-dev-1781368534585 → 1.0.0-dev-1783940945655

package/dist/definition.d.ts

@@ -40,7 +40,37 @@ export declare const clientDefinition: {
         description?: string | undefined;
         glob?: string | undefined;
     }[] | undefined;
-    defaultProviderId?: string | undefined;
+    authMethods: ({
+        id: string;
+        mode: "explicit";
+        label: string;
+        description?: string | undefined;
+        fields: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+            required: boolean;
+            secret: boolean;
+            sourceHints: {
+                kind: "environment";
+                variable: string;
+            }[];
+        }[];
+    } | {
+        id: string;
+        mode: "inferred";
+        label: string;
+        description?: string | undefined;
+    } | {
+        id: string;
+        mode: "none";
+        label: string;
+        description?: string | undefined;
+    })[];
+    defaultAuth?: {
+        providerDefinitionId: string;
+        methodId: string;
+    } | undefined;
     runtimeCapabilities: {
         supportsHooks: boolean;
         supportsStatusline: boolean;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as CodexNativeHooksFileSchema, a as CodexWiringSchemas, b as clientDefinition, c as CodexConfigHooksAddResponseSchema, d as CodexConfigHooksRemoveRequestSchema, f as CodexConfigHooksRemoveResponseSchema, g as CodexNativeHookMatcherGroupSchema, h as CodexNativeCommandHookSchema, l as CodexConfigHooksListRequestSchema, m as CodexHookEntrySchema, o as AbsolutePathSchema, p as CodexConfigSchemas, r as CodexClientSubjects, s as CodexConfigHooksAddRequestSchema, t as CodexClientSessionService, u as CodexConfigHooksListResponseSchema, v as CodexScopeHookRecordSchema, y as CodexScopeSchema } from "./codex-client-session-service-C2F6rQDS.mjs";
-import { t as codexPackage } from "./src-CUFX-QsP.mjs";
+import { C as clientDefinition, S as CodexScopeSchema, _ as CodexHookEntrySchema, b as CodexNativeHooksFileSchema, c as CodexWiringSchemas, d as CodexConfigHooksAddResponseSchema, f as CodexConfigHooksListRequestSchema, g as CodexConfigSchemas, h as CodexConfigHooksRemoveResponseSchema, l as AbsolutePathSchema, m as CodexConfigHooksRemoveRequestSchema, o as CodexClientSubjects, p as CodexConfigHooksListResponseSchema, t as CodexClientSessionService, u as CodexConfigHooksAddRequestSchema, v as CodexNativeCommandHookSchema, x as CodexScopeHookRecordSchema, y as CodexNativeHookMatcherGroupSchema } from "./codex-client-session-service-ddd3K0rw.mjs";
+import { t as codexPackage } from "./src-B_UWVcLO.mjs";
 
 export { AbsolutePathSchema, CodexClientSessionService, CodexClientSubjects, CodexConfigHooksAddRequestSchema, CodexConfigHooksAddResponseSchema, CodexConfigHooksListRequestSchema, CodexConfigHooksListResponseSchema, CodexConfigHooksRemoveRequestSchema, CodexConfigHooksRemoveResponseSchema, CodexConfigSchemas, CodexHookEntrySchema, CodexNativeCommandHookSchema, CodexNativeHookMatcherGroupSchema, CodexNativeHooksFileSchema, CodexScopeHookRecordSchema, CodexScopeSchema, CodexWiringSchemas, clientDefinition, codexPackage };

package/dist/runtime/codex-client-session-service.d.ts

@@ -11,8 +11,8 @@
  * Codex config root, falling back to native `~/.codex` paths when no resolver
  * or global binary is available. Wiring requests use the same settings path
  * resolution. The service also handles the blocking `client:codex.config.prime`
- * lifecycle hook and the `client:codex.sessionConfig.setup` delegation subject
- * for per-session config directory initialization.
+ * lifecycle hook and the `client:codex.sessionConfig.setup` / `.destroy`
+ * delegation subjects for refresh-safe per-session config isolation.
  *
  * Unknown or not-yet-modeled event names are silently dropped — they stay
  * raw-only inside the `client:codex.*` namespace and are never forwarded to
@@ -41,6 +41,7 @@
 import type { IMakaioBus } from '@makaio/framework/bus';
 import { BaseService } from '@makaio/framework/service-base';
 import { CodexClientSettings } from './client-settings.js';
+import { CodexSessionConfigHandler } from './session-config-handler.js';
 /**
  * Maximum number of adapter-managed session IDs retained in
  * {@link CodexClientSessionService.managedAdapterSessionIds}.
@@ -61,7 +62,7 @@ export declare const MANAGED_SESSION_CAP = 10000;
  *    `client.runtime.started` for the adapter-managed session gate, and
  *    registers request handlers for `config.hooks.list`, `config.hooks.add`,
  *    `config.hooks.remove`, `config.prime`, `wiring.list`, `wiring.apply`,
- *    `wiring.remove`, and `sessionConfig.setup`.
+ *    `wiring.remove`, `sessionConfig.setup`, and `sessionConfig.destroy`.
  * 2. On each incoming raw event, calls {@link normalizeCodexHook}.
  * 3. Emits the normalized subject when the event is recognized; silently
  *    ignores unknown events.  Normalized `client.session.*` events are
@@ -74,6 +75,15 @@ export declare class CodexClientSessionService extends BaseService {
     private readonly settingsOverride;
     /** Cached active config-dir resolution; reset when the active Codex version changes. */
     private cachedConfigDir;
+    /**
+     * Stable runtime identity of the machine that owns the client sessions
+     * observed by this service.  Stamped onto `client.session.started` payloads
+     * so downstream storage receives the owning machine's identity without
+     * deriving it from the writer process.
+     */
+    private readonly machineId;
+    /** Client-owned native auth materialization and refresh reconciliation. */
+    private readonly sessionConfigHandler;
     /**
      * Set of `adapterSessionId` values known to be owned by an adapter-managed
      * Codex runtime.  Populated by {@link handleRuntimeStarted} when a
@@ -93,12 +103,16 @@ export declare class CodexClientSessionService extends BaseService {
      * @param settings - Optional {@link CodexClientSettings} instance for tests
      *   that need exact filesystem paths. Production callers should omit it so
      *   the service can resolve the active managed config dir via the bus.
+     * @param machineId - Stable runtime identity of the observing machine,
+     *   caller-supplied from the extension context. Omit in tests or when the
+     *   identity is unavailable.
+     * @param sessionConfigHandler - Optional native auth lease handler override.
      */
-    constructor(bus?: IMakaioBus, settings?: CodexClientSettings);
+    constructor(bus?: IMakaioBus, settings?: CodexClientSettings, machineId?: string, sessionConfigHandler?: CodexSessionConfigHandler);
     /**
      * Register the raw hook ingress handler, config management request handlers,
      * wiring management request handlers, the config-prime lifecycle handler,
-     * and the session config setup handler on the bus.
+     * and the session config setup/teardown handlers on the bus.
      *
      * Also subscribes to `client.runtime.started` to track adapter-managed
      * sessions for the {@link handleHookReceived} suppression gate.

package/dist/runtime/hook-normalizer.d.ts

@@ -72,7 +72,11 @@ export type CodexNormalizedEvent = {
  * Returns `null` for unknown or not-yet-modeled event names so the caller
  * skips global emission and keeps the event raw-only in `client:codex.*`.
  * @param raw - Raw hook payload delivered on `client:codex.hook.received`
+ * @param machineId - Stable runtime identity of the observing machine,
+ *   caller-supplied by the owning client runtime. Stamped onto
+ *   `client.session.started` so downstream storage receives the owning
+ *   machine's identity without deriving it from the writer process.
  * @returns Normalized event with subject and typed payload, or `null` when
  *   the event name is unknown
  */
-export declare function normalizeCodexHook(raw: RawClientHookPayload): CodexNormalizedEvent | null;
+export declare function normalizeCodexHook(raw: RawClientHookPayload, machineId?: string): CodexNormalizedEvent | null;

package/dist/runtime/namespace.d.ts

@@ -15,6 +15,7 @@
  * - `wiring.apply` — install wiring entries into the target scope
  * - `wiring.remove` — uninstall wiring entries from the target scope
  * - `sessionConfig.setup` — seed an isolated session config directory
+ * - `sessionConfig.destroy` — reconcile and clear isolated native auth
  *
  * **Subject conventions:**
  * - Raw Codex-native events flow in the `client:codex.*` namespace only.
@@ -37,6 +38,7 @@
  * - `CodexClientSubjects.wiring.apply` → `client:codex.wiring.apply`
  * - `CodexClientSubjects.wiring.remove` → `client:codex.wiring.remove`
  * - `CodexClientSubjects.sessionConfig.setup` → `client:codex.sessionConfig.setup`
+ * - `CodexClientSubjects.sessionConfig.destroy` → `client:codex.sessionConfig.destroy`
  */
 export declare const CodexClientSubjects: import("@makaio/framework/core").BusSubjects<import("@makaio/framework/core").FlatSubjectDefinitions<`client:${string}`, {
     'hook.received': import("zod").ZodObject<{
@@ -194,6 +196,20 @@ export declare const CodexClientSubjects: import("@makaio/framework/core").BusSu
         }, import("zod/v4/core").$strip>;
         response: import("zod").ZodObject<{
             env: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+            authMaterialized: import("zod").ZodBoolean;
+        }, import("zod/v4/core").$strip>;
+    };
+    'sessionConfig.destroy': {
+        request: import("zod").ZodObject<{
+            sessionDir: import("zod").ZodString;
+            platform: import("zod").ZodEnum<{
+                darwin: "darwin";
+                linux: "linux";
+                win32: "win32";
+            }>;
+        }, import("zod/v4/core").$strip>;
+        response: import("zod").ZodObject<{
+            success: import("zod").ZodBoolean;
         }, import("zod/v4/core").$strip>;
     };
 }>, `client:${string}`>;

package/dist/runtime/native-auth-errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Secret-safe error helpers for Codex native authentication storage.
+ * @packageDocumentation
+ */
+/**
+ * Build an error that preserves a safe discriminator but never the secret-bearing message.
+ * @param operation - Safe operation label.
+ * @param error - Original failure, whose message is deliberately discarded.
+ * @returns Sanitized error safe for bus propagation and logs.
+ */
+export declare function sanitizedNativeAuthError(operation: string, error: unknown): Error;
+/**
+ * Preserve both sanitized failures when cleanup follows an earlier error.
+ * @param existing - Earlier failure, when present.
+ * @param next - Newly observed sanitized failure.
+ * @param message - Safe aggregate description.
+ * @returns The new failure or an aggregate retaining both failures.
+ */
+export declare function mergeNativeAuthErrors(existing: unknown, next: Error, message: string): unknown;

package/dist/runtime/native-auth-source-lock.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Canonical Codex native-auth identity and source-lock primitives.
+ * @packageDocumentation
+ */
+/** Secret-free cross-process lock-directory suffix beside canonical CODEX_HOME. */
+export declare const CODEX_AUTH_CAS_LOCK_FILE = ".makaio-codex-auth-cas.lock";
+/** Lock finalization failed after the guarded native-auth operation committed. */
+export declare class CodexNativeAuthSourceLockFinalizationError extends Error {
+    constructor();
+}
+/** Result retaining a committed operation across lock-finalization failure. */
+export interface CodexNativeAuthSourceLockExecution<T> {
+    /** Guarded operation result. */
+    readonly value: T;
+    /** Whether the source lock released without compromise or cleanup failure. */
+    readonly coordination: 'released' | 'uncertain';
+}
+/** Canonical CODEX_HOME identity used by both file and keyring stores. */
+export interface CodexAuthHomeIdentity {
+    /** Canonical absolute CODEX_HOME path. */
+    readonly canonicalPath: string;
+    /** Codex keyring account derived from {@link canonicalPath}. */
+    readonly keyringAccount: string;
+}
+/** Result of inspecting a lease target without following an unsafe final symlink. */
+export type CodexLeaseTargetInspection = {
+    readonly status: 'safe';
+    readonly identity: CodexAuthHomeIdentity;
+} | {
+    readonly status: 'missing' | 'unsafe';
+    readonly fallbackIdentity: CodexAuthHomeIdentity;
+};
+/**
+ * Build Codex 0.130's keyring account for a CODEX_HOME.
+ * @param codexHome - CODEX_HOME path; canonicalized when it exists.
+ * @returns `cli|` followed by the first 16 hex characters of the path digest.
+ */
+export declare function buildCodexAuthKeyringAccount(codexHome: string): Promise<string>;
+/**
+ * Resolve the canonical identity shared by Codex file and keyring auth stores.
+ * @param codexHome - CODEX_HOME path.
+ * @returns Canonical path plus Codex's derived keyring account.
+ */
+export declare function identifyCodexAuthHome(codexHome: string): Promise<CodexAuthHomeIdentity>;
+/**
+ * Derive a cleanup-only identity from the normalized input path.
+ *
+ * This deliberately performs no `realpath` lookup. A lease directory may have
+ * disappeared or been replaced by a symlink before restart cleanup; following
+ * that new target could delete an unrelated canonical keyring credential.
+ * @param codexHome - Original lease CODEX_HOME path.
+ * @returns Lexically normalized identity safe for conservative keyring cleanup.
+ */
+export declare function identifyCodexAuthHomeLexically(codexHome: string): CodexAuthHomeIdentity;
+/**
+ * Inspect a lease target while rejecting a symlink or non-directory final path.
+ * @param codexHome - Isolated lease CODEX_HOME path.
+ * @returns Stable canonical identity, or a cleanup-only lexical fallback.
+ */
+export declare function inspectCodexLeaseTarget(codexHome: string): Promise<CodexLeaseTargetInspection>;
+/**
+ * Serialize one canonical Codex native-auth mutation by CODEX_HOME.
+ *
+ * Account integrations and session-lease compare-and-swap operations must use
+ * this same lock so a lease cannot overwrite a concurrently selected account.
+ * @param codexHome - Canonical Codex config home whose auth source is mutated.
+ * @param operation - Source operation that must retain exclusive ownership.
+ * @returns Operation result after the source lock is released.
+ */
+export declare function withCodexNativeAuthSourceLock<T>(codexHome: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Execute against one CODEX_HOME while preserving committed operation results
+ * when lock finalization becomes uncertain.
+ * @param codexHome - Canonical Codex config home.
+ * @param operation - Native-auth operation guarded by the source lock.
+ * @returns Operation value plus released/uncertain coordination state.
+ */
+export declare function executeCodexNativeAuthSourceLock<T>(codexHome: string, operation: () => Promise<T>): Promise<CodexNativeAuthSourceLockExecution<T>>;
+/**
+ * Serialize one operation against an already-pinned Codex auth identity.
+ * @param identity - Canonical source CODEX_HOME identity.
+ * @param operation - Source operation that must retain exclusive ownership.
+ * @returns Operation result after the source lock is released.
+ */
+export declare function withIdentifiedCodexNativeAuthSourceLock<T>(identity: CodexAuthHomeIdentity, operation: () => Promise<T>): Promise<T>;
+/**
+ * Execute against an already-pinned identity and retain post-commit lock state.
+ * @param identity - Canonical source CODEX_HOME identity.
+ * @param operation - Native-auth operation guarded by the source lock.
+ * @returns Operation value plus released/uncertain coordination state.
+ */
+export declare function executeIdentifiedCodexNativeAuthSourceLock<T>(identity: CodexAuthHomeIdentity, operation: () => Promise<T>): Promise<CodexNativeAuthSourceLockExecution<T>>;
+/**
+ * Build a sibling lock anchor that survives CODEX_HOME rename/replacement.
+ * @param canonicalPath - Canonical CODEX_HOME path.
+ * @returns Secret-free sibling lock directory path.
+ */
+export declare function buildCodexNativeAuthSourceLockPath(canonicalPath: string): string;

package/dist/runtime/native-auth-store.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Codex native authentication storage primitives.
+ *
+ * Mirrors Codex App Server 0.130's `file`, `keyring`, and `auto` credential
+ * store semantics without interpreting credential payloads. Credential values
+ * remain inside this client-owned runtime boundary; the only persisted lease
+ * state contains store identities and SHA-256 digests.
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import { type CodexKeyringCredentialStore } from './native-keyring-credential-store.js';
+import { type CodexAuthHomeIdentity } from './native-auth-source-lock.js';
+export { CODEX_AUTH_CAS_LOCK_FILE, buildCodexAuthKeyringAccount, buildCodexNativeAuthSourceLockPath, executeCodexNativeAuthSourceLock, identifyCodexAuthHome, identifyCodexAuthHomeLexically, inspectCodexLeaseTarget, withCodexNativeAuthSourceLock, } from './native-auth-source-lock.js';
+export type { CodexAuthHomeIdentity, CodexLeaseTargetInspection } from './native-auth-source-lock.js';
+/** Codex 0.130's native CLI credential store configuration values. */
+export type CodexAuthStoreMode = 'file' | 'keyring' | 'auto';
+/** Concrete store that contained a credential at one point in the lease. */
+export type CodexAuthStoreBackend = 'file' | 'keyring';
+/** Codex's fixed keyring service name for CLI authentication. */
+export declare const CODEX_AUTH_KEYRING_SERVICE = "Codex Auth";
+/** Non-secret lease metadata file stored inside the isolated CODEX_HOME. */
+export declare const CODEX_AUTH_LEASE_METADATA_FILE = ".makaio-codex-auth-lease.json";
+/** Result of resolving Codex's effective credential store. */
+export interface CodexEffectiveCredentialRead {
+    /** Credential and concrete backend, or `null` when no native auth exists. */
+    readonly credential: {
+        readonly backend: CodexAuthStoreBackend;
+        readonly value: string;
+    } | null;
+    /** Whether an `auto` read fell back because the keyring was unavailable. */
+    readonly keyringUnavailable: boolean;
+}
+/** Strict schema for the secret-free native auth lease generation. */
+export declare const CodexAuthLeaseMetadataSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    backend: z.ZodObject<{
+        configured: z.ZodEnum<{
+            auto: "auto";
+            file: "file";
+            keyring: "keyring";
+            none: "none";
+        }>;
+        effective: z.ZodEnum<{
+            file: "file";
+            keyring: "keyring";
+            none: "none";
+        }>;
+    }, z.core.$strict>;
+    canonicalIdentity: z.ZodNullable<z.ZodObject<{
+        canonicalPath: z.ZodString;
+        keyringAccount: z.ZodString;
+    }, z.core.$strict>>;
+    targetIdentity: z.ZodObject<{
+        canonicalPath: z.ZodString;
+        keyringAccount: z.ZodString;
+    }, z.core.$strict>;
+    sourceGenerationDigest: z.ZodNullable<z.ZodString>;
+    initialTargetDigest: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** Secret-free native auth lease state. */
+export type CodexAuthLeaseMetadata = z.infer<typeof CodexAuthLeaseMetadataSchema>;
+/** Parsed metadata outcome used to distinguish safe absence from corruption. */
+export type CodexAuthLeaseMetadataRead = {
+    readonly status: 'found';
+    readonly metadata: CodexAuthLeaseMetadata;
+} | {
+    readonly status: 'missing';
+} | {
+    readonly status: 'invalid';
+};
+/**
+ * Compute a stable SHA-256 digest without interpreting the credential value.
+ * @param value - Opaque credential payload.
+ * @returns Lowercase hexadecimal SHA-256 digest.
+ */
+export declare function digestCodexCredential(value: string): string;
+/**
+ * Local native auth store used by the session config handler.
+ */
+export declare class CodexNativeAuthStore {
+    private readonly keyring;
+    /**
+     * @param keyring - Cross-platform keyring implementation.
+     */
+    constructor(keyring?: CodexKeyringCredentialStore);
+    /**
+     * Resolve `cli_auth_credentials_store` from the canonical config.
+     * Codex 0.130 defaults this setting to `file`.
+     * @param identity - Canonical CODEX_HOME identity.
+     * @returns Configured credential store mode.
+     */
+    resolveMode(identity: CodexAuthHomeIdentity): Promise<CodexAuthStoreMode>;
+    /**
+     * Load a credential using Codex 0.130's configured store order.
+     * @param identity - Canonical CODEX_HOME identity.
+     * @param mode - Configured store mode.
+     * @returns Effective credential plus keyring-fallback status.
+     */
+    readEffective(identity: CodexAuthHomeIdentity, mode: CodexAuthStoreMode): Promise<CodexEffectiveCredentialRead>;
+    /**
+     * Read the credential generation that should be considered for lease refresh.
+     *
+     * `auto` normally prefers keyring. During a running process, however, a
+     * transient keyring save failure can put a fresher generation in `auth.json`
+     * while the unchanged keyring entry remains. Detect that exact fallback by
+     * comparing both stores to the lease's initial generation.
+     * @param identity - Isolated target CODEX_HOME identity.
+     * @param mode - Configured store mode.
+     * @param initialDigest - Digest materialized when the lease was created.
+     * @returns Refresh candidate plus keyring availability status.
+     */
+    readRefreshCandidate(identity: CodexAuthHomeIdentity, mode: CodexAuthStoreMode, initialDigest: string): Promise<CodexEffectiveCredentialRead>;
+    /**
+     * Read one concrete backend without fallback.
+     * @param identity - Canonical CODEX_HOME identity.
+     * @param backend - Concrete store to read.
+     * @returns Credential value, or `null` when absent.
+     */
+    readBackend(identity: CodexAuthHomeIdentity, backend: CodexAuthStoreBackend): Promise<string | null>;
+    /**
+     * Clone an opaque value into one concrete target backend.
+     * @param identity - Target CODEX_HOME identity.
+     * @param backend - Concrete target store.
+     * @param value - Opaque credential payload.
+     */
+    writeBackend(identity: CodexAuthHomeIdentity, backend: CodexAuthStoreBackend, value: string): Promise<void>;
+    /**
+     * Persist a refreshed credential using Codex 0.130's save semantics.
+     * @param identity - Canonical CODEX_HOME identity.
+     * @param mode - Configured store mode.
+     * @param value - Refreshed opaque credential payload.
+     */
+    saveConfigured(identity: CodexAuthHomeIdentity, mode: CodexAuthStoreMode, value: string): Promise<void>;
+    /**
+     * Run a generation check and conditional write under one cross-process lock.
+     * @param identity - Canonical source CODEX_HOME identity.
+     * @param operation - CAS operation to execute while the lock is held.
+     * @returns Operation result.
+     */
+    withSourceLock<T>(identity: CodexAuthHomeIdentity, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Remove a target keyring credential.
+     * @param identity - Target CODEX_HOME identity.
+     */
+    deleteKeyring(identity: CodexAuthHomeIdentity): Promise<void>;
+    /**
+     * Remove the file credential from a target CODEX_HOME.
+     * @param identity - Target CODEX_HOME identity.
+     */
+    deleteFile(identity: CodexAuthHomeIdentity): Promise<void>;
+    /**
+     * Atomically persist strict secret-free lease metadata with mode `0600`.
+     * @param sessionDir - Isolated CODEX_HOME.
+     * @param metadata - Validated metadata generation.
+     */
+    writeLeaseMetadata(sessionDir: string, metadata: CodexAuthLeaseMetadata): Promise<void>;
+    /**
+     * Read and strictly parse secret-free lease metadata.
+     * @param sessionDir - Isolated CODEX_HOME.
+     * @returns Found, missing, or invalid outcome without echoing file contents.
+     */
+    readLeaseMetadata(sessionDir: string): Promise<CodexAuthLeaseMetadataRead>;
+    private readFileCredential;
+    private readKeyringCredential;
+    private writeKeyring;
+}

package/dist/runtime/native-keyring-credential-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lazy native-keyring bridge for Codex authentication storage.
+ * @packageDocumentation
+ */
+/** Keyring operations used by the Codex native auth store. */
+export interface CodexKeyringCredentialStore {
+    /**
+     * Read one credential.
+     * @param service - Keyring service name.
+     * @param account - Keyring account name.
+     * @returns Stored value, or `null` when absent.
+     */
+    read(service: string, account: string): Promise<string | null>;
+    /**
+     * Write one credential.
+     * @param service - Keyring service name.
+     * @param account - Keyring account name.
+     * @param value - Opaque credential payload.
+     */
+    write(service: string, account: string, value: string): Promise<void>;
+    /**
+     * Delete one credential, treating absence as success.
+     * @param service - Keyring service name.
+     * @param account - Keyring account name.
+     */
+    delete(service: string, account: string): Promise<void>;
+}
+/** Native cross-platform keyring implementation matching Codex's keyring-rs store. */
+export declare const nativeKeyringCredentialStore: CodexKeyringCredentialStore;

package/dist/runtime/package.d.ts

@@ -11,6 +11,8 @@ export { CodexClientSubjects, CODEX_CLIENT_NAMESPACE } from './namespace.js';
 export { CodexClientSessionService } from './codex-client-session-service.js';
 export { normalizeCodexHook } from './hook-normalizer.js';
 export type { CodexNormalizedEvent, CodexNormalizedSubject } from './hook-normalizer.js';
+export { buildCodexNativeAuthSourceLockPath, executeCodexNativeAuthSourceLock, withCodexNativeAuthSourceLock, } from './native-auth-source-lock.js';
+export type { CodexNativeAuthSourceLockExecution } from './native-auth-source-lock.js';
 /**
  * MakaioExtension manifest for the Codex client session normalization service.
  *

package/dist/runtime/package.mjs

@@ -1,4 +1,4 @@
-import { i as normalizeCodexHook, n as CODEX_CLIENT_NAMESPACE, r as CodexClientSubjects, t as CodexClientSessionService } from "../codex-client-session-service-C2F6rQDS.mjs";
+import { a as CODEX_CLIENT_NAMESPACE, i as withCodexNativeAuthSourceLock, n as buildCodexNativeAuthSourceLockPath, o as CodexClientSubjects, r as executeCodexNativeAuthSourceLock, s as normalizeCodexHook, t as CodexClientSessionService } from "../codex-client-session-service-ddd3K0rw.mjs";
 import { dep } from "@makaio/framework/contracts";
 
 //#region src/runtime/package.ts
@@ -26,8 +26,8 @@ const codexClientRuntimePackage = {
 	* @param ctx - Runtime package context
 	* @returns Uninitialized Codex client session service
 	*/
-	create: (ctx) => new CodexClientSessionService(ctx.bus)
+	create: (ctx) => new CodexClientSessionService(ctx.bus, void 0, ctx.machineId)
 };
 
 //#endregion
-export { CODEX_CLIENT_NAMESPACE, CodexClientSessionService, CodexClientSubjects, codexClientRuntimePackage, normalizeCodexHook };
+export { CODEX_CLIENT_NAMESPACE, CodexClientSessionService, CodexClientSubjects, buildCodexNativeAuthSourceLockPath, codexClientRuntimePackage, executeCodexNativeAuthSourceLock, normalizeCodexHook, withCodexNativeAuthSourceLock };

package/dist/runtime/session-config-handler.d.ts

@@ -1,39 +1,51 @@
 /**
- * Codex session config setup handler.
+ * Codex session config lease handler.
  *
- * Implements the `client:codex.sessionConfig.setup` delegation request by
- * materializing the Codex config files needed for an isolated session
- * directory.
- *
- * The handler copies `config.toml` and `auth.json` from the base config
- * directory (when present) into the session-scoped directory, then primes the
- * session directory to ensure `check_for_update_on_startup = false` is set.
- *
- * When `sessionDir` and `baseConfigDir` resolve to the same path (the
- * framework passes `sessionDir` as `baseConfigDir` when no profile is
- * configured) the copy step is skipped and only the prime step runs.
- *
- * Returns `{ env: { CODEX_HOME: sessionDir } }` so the spawned Codex process
- * inherits the isolated session directory as its configuration root.
+ * Materializes file/keyring native auth into an isolated CODEX_HOME and
+ * reconciles refreshes on teardown with a generation-checked write-back.
+ * `empty` inheritance never reads or clones canonical native credentials.
  * @packageDocumentation
  */
-import type { SessionConfigSetupRequest, SessionConfigSetupResponse } from '@makaio/framework/contracts/client';
+import type { SessionConfigSetupRequest, SessionConfigSetupResponse, SessionConfigTeardownRequest, SessionConfigTeardownResponse } from '@makaio/framework/contracts/client';
+import { CodexNativeAuthStore } from './native-auth-store.js';
 /**
- * Handle `client:codex.sessionConfig.setup` by seeding the session-scoped
- * directory with the appropriate Codex config files.
- *
- * Steps:
- * 1. Create `sessionDir` (recursive, no-op when it already exists).
- * 2. When `sessionDir` and `baseConfigDir` are distinct paths, copy
- * `config.toml` and `auth.json` from `baseConfigDir` into `sessionDir`
- * (each copy is skipped when the source file does not exist).
- * 3. Prime `sessionDir` via {@link handleCodexConfigPrime} to ensure
- * `check_for_update_on_startup = false` is set.
- * @param payload - Session config setup delegation payload. Only `sessionDir`,
- *   `baseConfigDir`, and `projectDir` are used; `platform` and
- *   `configInheritance` are accepted for interface compatibility but are not
- *   required for Codex's simpler config model.
- * @returns Environment variables for the spawned Codex process: `CODEX_HOME`
- *   pointing to `sessionDir`.
+ * Codex-owned setup and teardown component for isolated config leases.
  */
-export declare function handleCodexSessionConfigSetup(payload: SessionConfigSetupRequest): Promise<SessionConfigSetupResponse>;
+export declare class CodexSessionConfigHandler {
+    private readonly authStore;
+    private readonly nativeConfigDir;
+    /** Runtime copy of metadata used when a lease directory disappeared early. */
+    private readonly activeMetadata;
+    /**
+     * @param authStore - Native file/keyring storage implementation.
+     * @param nativeConfigDir - Native CODEX_HOME used when no profile source exists.
+     */
+    constructor(authStore?: CodexNativeAuthStore, nativeConfigDir?: string);
+    /**
+     * Seed an isolated CODEX_HOME according to the requested inheritance policy.
+     * @param payload - Validated setup delegation payload.
+     * @returns Process environment and truthful native-auth materialization status.
+     */
+    setup(payload: SessionConfigSetupRequest): Promise<SessionConfigSetupResponse>;
+    /**
+     * Compare-and-swap refreshed native auth back to its canonical store, then
+     * remove the session-specific keyring entry.
+     * @param payload - Validated teardown delegation payload.
+     * @returns Successful client-owned teardown result.
+     */
+    teardown(payload: SessionConfigTeardownRequest): Promise<SessionConfigTeardownResponse>;
+    private inspectLeaseForTeardown;
+    private reconcileInspectedLease;
+    /**
+     * Resolve profile source or the native CODEX_HOME fallback.
+     * @param payload - Setup payload carrying source and target paths.
+     * @returns Canonical source candidate selected for this lease.
+     */
+    private resolveSourceConfigDir;
+    private materializeGeneralConfig;
+    private materializeNativeAuthLocked;
+    private recordMetadata;
+    private rollbackFailedSetup;
+    private collectTargetCleanupErrors;
+    private reconcileRefresh;
+}

package/dist/server.mjs

@@ -1,4 +1,4 @@
-import { t as codexPackage } from "./src-CUFX-QsP.mjs";
+import { t as codexPackage } from "./src-B_UWVcLO.mjs";
 import { codexClientRuntimePackage } from "./runtime/package.mjs";
 
 //#region src/server.ts

package/dist/{src-CUFX-QsP.mjs → src-B_UWVcLO.mjs}

@@ -1,4 +1,4 @@
-import { b as clientDefinition } from "./codex-client-session-service-C2F6rQDS.mjs";
+import { C as clientDefinition } from "./codex-client-session-service-ddd3K0rw.mjs";
 
 //#region src/package.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makaio/client-codex",
-  "version": "1.0.0-dev-1781368534585",
+  "version": "1.0.0-dev-1783940945655",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -25,15 +25,19 @@
     "@makaio/framework": ">=1.0.0-0 <2.0.0"
   },
   "dependencies": {
-    "zod": "^4.1.13"
+    "@napi-rs/keyring": "^1.2.0",
+    "proper-lockfile": "^4.1.2",
+    "smol-toml": "^1.3.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@makaio/build-tooling": "1.0.0",
     "@makaio/bus-core": "1.0.0",
-    "@makaio/contracts": "1.0.0-dev-1781368534585",
+    "@makaio/contracts": "1.0.0",
     "@makaio/core": "1.0.0",
     "@makaio/service-base": "1.0.0",
     "@makaio/subsystem-client": "1.0.0",
+    "@types/proper-lockfile": "^4.1.4",
     "tsdown": "0.22.0",
     "typescript": "^6.0.3"
   },