@cortexkit/claustrum-client 0.13.0 → 0.15.0

package/README.md

@@ -13,8 +13,8 @@ credential caching, refresh, account scheduling, and retry policy.
   expiry-skew refresh can take seconds. Request paths should peek cached state,
   not call `get` speculatively.
 • `permanent` with `not_found` means the handle is unknown OR revoked — uniform refusal
-  by design (the vault cannot enumerate which). Treat it as gone either way: re-run
-  `ck auth migrate-opencode` to mint a fresh handle; the prior record, if any, is kept.
+  by design (the vault cannot enumerate which). Treat it as gone either way; the
+  prior record, if any, is kept.
 • `auth_required` means the record is latched and needs reauthentication.
 • `statusCredential` on an unknown or revoked handle RESOLVES, it does not throw: it
   returns `ready: false, lastErrorCode: 'not_found'` with `recordVersion`, `credentialId`
@@ -23,6 +23,9 @@ credential caching, refresh, account scheduling, and retry policy.
   as a version older than every real one.
 • Unknown server error classes are bounded to `transient`; callers must retry them
   rather than treating a forward-compatible class as permanent.
+• Account pools use the refresh adapter from `list_scoped` plus opaque `accountId`.
+  Use `recordVersion` to invalidate cached material, never as part of a pool key:
+  a token refresh must not split one account into a new pool.
 • **Changed in 0.13.0:** a transport `Error` frame whose answer no retry or reconnect
   can change is reported as `permanent` with action `gone`, and the client no longer
   reconnects for it: `unknown_method`, `invalid_params`, `invalid_request`,
@@ -52,9 +55,20 @@ credential caching, refresh, account scheduling, and retry policy.
   before categories existed). Both are `undefined` against a vault too old to send
   them; treat that as unknown, not as zero. A present but malformed value refuses the
   reply like any other malformed field.
+• Since 0.14.0, `reportUsageScoped({ credentialId, reading, enrollmentToken? })`
+  sends fire-and-forget quota readings. `accepted` means queued, never that the
+  usage-processing module insula applied the reading. Coalesce per credential and
+  never await it on a request path.
+  The client leaves reading validation to the vault, which refuses top-level
+  `credentialId` and `vouched` keys and compact JSON readings over 15,360 bytes with
+  `invalid_params`.
 
 The client sends `consumerIdentity: null` for every managed request so inherited
-`SUBC_MODULE_ID` and `SUBC_LAUNCH_NONCE` cannot impersonate a supervising host.
+launch identity cannot impersonate a supervising host. Nonce possession, not process
+ancestry, is the authority boundary: environment variables and an inheritable nonce
+descriptor can reach helpers unless scrubbed or closed. Helpers using other clients
+must explicitly omit route identity (for subc-client, `consumerIdentity: null`) when
+they should be anonymous; process ancestry alone does not enforce isolation.
 
 **Changed in 0.11.0:** the client depends on `@cortexkit/subc-client` ^0.22.0 (was
 ^0.16.0). A host that also uses subc-client must move to the 0.22 line, so both share one
@@ -62,6 +76,21 @@ copy. One behaviour reaches callers: while the vault is restarting or refusing r
 opens as retryable, a call now keeps retrying for up to 90 s (paced, with jitter) instead
 of 30 s. Give every vault call on a latency-sensitive path its own timeout.
 
+## Reading credential material
+
+The wire payload is opaque bytes. `getCredential(handle, minTtlMs?)` and
+`getScoped({ credentialId, enrollmentToken?, minTtlMs? })` keep their text results
+(`ServedCredential.material: string`) and require valid UTF-8. They refuse a
+non-UTF-8 payload with `invalid_response`; this does not mean the stored credential
+is corrupt.
+
+Use `getCredentialBytes(handle, minTtlMs?)` or
+`getScopedBytes({ credentialId, enrollmentToken?, minTtlMs? })` for binary cookies
+or any material that may not be UTF-8. Both return `ServedCredentialBytes`, with
+`material: Uint8Array` preserving every payload byte and the same metadata, grant
+checks, and TTL semantics as their text counterparts. Neither byte method performs
+text decoding.
+
 ## Watching for changes
 
 Since 0.12.0, `client.watchScoped(onNotice, { enrollmentToken? })` holds an
@@ -132,20 +161,10 @@ for (;;) {
 }
 ```
 
-## OpenCode handle-file exports
-
-`defaultHandleFilePath`, `readHandleFile`, `handleFileRevision`, and `parseHandleFile`
-are exported for tenant plugins consuming the OpenCode handle manifest. The shared
-`HANDLE_FILE_CONTRACT` is pinned to `maxBytes: 262144`, `mode: 0o600`,
-`labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/`, and `handleRe: /^ckh_[A-Za-z0-9_-]{43}$/`.
-
-### Private files and Windows support
+## Private files and Windows support
 
-Enrollment tokens support Windows as well as Unix. Reading a handle manifest works on
-Windows; writing one does not: the manifest lock's stale-lock eviction renames a lock
-another process may hold open, which Windows refuses, so `withManifestLock` and
-`writeHandleFileLocked` reject on Windows with code `unsupported_platform` rather than
-risk two writers overlapping. The client uses `@cortexkit/store` 0.2.1 or newer: exclusive private creation
+Enrollment tokens support Windows as well as Unix. The client uses
+`@cortexkit/store` 0.2.1 or newer: exclusive private creation
 protects files before any secret bytes are written, and atomic replacement keeps
 that protection. Unix files use mode 0600 and new directories use 0700. On Windows,
 the store's `@cortexkit/private-files` native module creates owner-only ACLs and the
@@ -167,7 +186,7 @@ preserved: an owned, non-sticky group-writable directory (including a 0775
 
 ## Testing a consumer of this client
 
-Three things on a developer box silently satisfy what a consumer's test is trying to
+Two things on a developer box silently satisfy what a consumer's test is trying to
 prove. Each was found by a consumer shipping green and failing elsewhere.
 
 • **A connection file at the default path is a host fact, not a fixture.** If the vault
@@ -175,9 +194,6 @@ prove. Each was found by a consumer shipping green and failing elsewhere.
   up, so a suite can pass on the daemon's real socket and fail anywhere without one.
   Force it absent (`CLAUSTRUM_SUBC_CONNECTION=/nonexistent/x.json`, and clear
   `XDG_RUNTIME_DIR`) and prove the suite still passes.
-• **Tests default into the operator's live config.** A suite that resolves
-  `~/.config/opencode` without an override writes lock files and manifests beside real
-  credentials — passing locally, and mutating state no CI runner has.
 • **A bare `bun` run is not an oracle for module resolution.** The Bun CLI auto-installs
   a public dependency it cannot resolve; a compiled binary does not. All readings below
   are bun 1.3.14, same module, no `node_modules` — a toolchain behaviour with no version
@@ -208,5 +224,5 @@ prove. Each was found by a consumer shipping green and failing elsewhere.
   result: a freshly linked unsigned binary is SIGKILLed, and `rc=137` with empty stderr
   reads as a resolution failure while being a signature one.
 
-The shape is the same in all three: the producing machine supplies the thing under test.
+The shape is the same in both: the producing machine supplies the thing under test.
 A passing check on it is evidence only when the ambient supply is removed first.

package/dist/enrollment.d.ts

@@ -1,12 +1,7 @@
+import { checkPrivatePath } from './private-path.js';
 export type EnrollmentTokenFile = {
     token: string;
     token_generation: number;
 };
-/**
- * Atomically replace a consumer's enrollment credential.
- *
- * Creation uses owner-only Unix permissions or native Windows ACLs before writing
- * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
- * users, and on Windows also verifies the completed parent's owner-only ACL.
- */
-export declare function writeEnrollmentTokenFile(path: string, value: EnrollmentTokenFile): Promise<void>;
+export declare function createEnrollmentWriter(checkPath?: typeof checkPrivatePath): (path: string, value: EnrollmentTokenFile) => Promise<void>;
+export declare const writeEnrollmentTokenFile: (path: string, value: EnrollmentTokenFile) => Promise<void>;

package/dist/enrollment.js

@@ -11,53 +11,57 @@ function validateTokenFile(value) {
         throw new Error('enrollment token generation must be a positive safe integer');
     }
 }
-async function refuseWritableAncestor(parent) {
-    const result = await checkPrivatePath(parent);
-    if (!result.ok)
-        throw new Error(notPrivate('enrollment token folder', result));
-}
-/**
- * Atomically replace a consumer's enrollment credential.
- *
- * Creation uses owner-only Unix permissions or native Windows ACLs before writing
- * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
- * users, and on Windows also verifies the completed parent's owner-only ACL.
- */
-export async function writeEnrollmentTokenFile(path, value) {
-    validateTokenFile(value);
-    path = resolve(path);
-    const parent = dirname(path);
-    // Native Windows creation rejects ancestors that other users can replace. A missing
-    // private parent can be created under a safe but non-private folder; afterwards the
-    // async check also requires the completed parent's protected owner-only ACL.
-    if (process.platform !== 'win32')
+export function createEnrollmentWriter(checkPath = checkPrivatePath) {
+    async function refuseWritableAncestor(parent) {
+        const result = await checkPath(parent);
+        if (!result.ok)
+            throw new Error(notPrivate('enrollment token folder', result));
+    }
+    /**
+     * Atomically replace a consumer's enrollment credential.
+     *
+     * Creation uses owner-only Unix permissions or native Windows ACLs before writing
+     * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
+     * users, and on Windows also verifies the completed parent's owner-only ACL.
+     */
+    async function writeEnrollmentTokenFile(path, value) {
+        validateTokenFile(value);
+        path = resolve(path);
+        const parent = dirname(path);
+        // Native Windows creation rejects ancestors that other users can replace. A missing
+        // private parent can be created under a safe but non-private folder; afterwards the
+        // async check also requires the completed parent's protected owner-only ACL.
+        if (process.platform !== 'win32')
+            await refuseWritableAncestor(parent);
+        await createPrivateParents(parent);
         await refuseWritableAncestor(parent);
-    await createPrivateParents(parent);
-    await refuseWritableAncestor(parent);
-    const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
-    let created = false;
-    try {
-        created = true;
-        try {
-            await createPrivateFile(temporary, `${JSON.stringify(value)}\n`);
-        }
-        catch (error) {
-            if (privateCreationCode(error) === 'EEXIST')
-                created = false;
-            throw error;
-        }
-        const descriptor = await open(temporary, 'r+');
+        const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
+        let created = false;
         try {
-            await descriptor.sync();
+            created = true;
+            try {
+                await createPrivateFile(temporary, `${JSON.stringify(value)}\n`);
+            }
+            catch (error) {
+                if (privateCreationCode(error) === 'EEXIST')
+                    created = false;
+                throw error;
+            }
+            const descriptor = await open(temporary, 'r+');
+            try {
+                await descriptor.sync();
+            }
+            finally {
+                await descriptor.close();
+            }
+            await rename(temporary, path);
+            created = false;
         }
         finally {
-            await descriptor.close();
+            if (created)
+                await unlink(temporary).catch(() => undefined);
         }
-        await rename(temporary, path);
-        created = false;
-    }
-    finally {
-        if (created)
-            await unlink(temporary).catch(() => undefined);
     }
+    return writeEnrollmentTokenFile;
 }
+export const writeEnrollmentTokenFile = createEnrollmentWriter();

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, type ClaustrumDetection, type ClaustrumEndpoint, } from './detect.js';
 export { storeIdentity, storageFingerprint } from './identity.js';
 export { writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollment.js';
-export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, type ManifestHandleAccount, type ManifestHandleFile, type ManifestHandleProvider, type ManifestLockError, type ManifestLockErrorCode, } from './manifest-lock.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, type ClaustrumCredentialErrorAction, type ClaustrumCredentialErrorClass, } from './errors.js';
-export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, type ServedCredentialBytes, } from './wire.js';
 export { ScopedWatchError, type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions, type ScopedWatchOutcome, } from './watch.js';
-export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';

package/dist/index.js

@@ -1,8 +1,6 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, } from './detect.js';
 export { storeIdentity, storageFingerprint } from './identity.js';
 export { writeEnrollmentTokenFile, } from './enrollment.js';
-export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, } from './manifest-lock.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, } from './errors.js';
 export { ClaustrumClient, } from './wire.js';
 export { ScopedWatchError, } from './watch.js';
-export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, } from './handles.js';

package/dist/private-path.d.ts

@@ -1,6 +1,4 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { type OwnerOnlyPathAsyncOptions, type OwnerOnlyPathResult } from '@cortexkit/store';
-export declare const privatePathContext: AsyncLocalStorage<OwnerOnlyPathAsyncOptions>;
 export declare const checkPrivatePath: (path: string, options?: OwnerOnlyPathAsyncOptions) => Promise<OwnerOnlyPathResult>;
 /**
  * The refusal text for a path the store judged not private. It names the folder and the

package/dist/private-path.js

@@ -1,12 +1,7 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { stat } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { checkOwnerOnlyPathAsync, createPrivateDirectory } from '@cortexkit/store';
-// Tests run the ownership check against fixture uids and account files through this
-// context, isolated per concurrent test. It is internal: the package `exports` map
-// exposes only the index, so consumers cannot reach it.
-export const privatePathContext = new AsyncLocalStorage();
-export const checkPrivatePath = (path, options) => checkOwnerOnlyPathAsync(resolve(path), privatePathContext.getStore() ?? options);
+export const checkPrivatePath = (path, options) => checkOwnerOnlyPathAsync(resolve(path), options);
 /**
  * The refusal text for a path the store judged not private. It names the folder and the
  * store's own reason (foreign owner, world-writable, a sticky folder without an

package/dist/wire.d.ts

@@ -26,19 +26,22 @@ export type ClaustrumClientOptions = {
  * an outage caused that way is visible only to the consumer that caused it.
  */
 export type ServedCredential = {
+    /** UTF-8 text; use `ServedCredentialBytes` for opaque, potentially non-UTF-8 material. */
     material: string;
     recordVersion: number;
     expiresAtMs: number | null;
     /**
      * Operator-chosen record label for verifying a caller-held binding. It is not a routing key:
-     * account-scoped routing joins `accountId` with `recordVersion`.
+     * Account-scoped routing joins `accountId` with `refreshAdapter` from the inventory,
+     * never `recordVersion`, which only invalidates cached material.
      */
     credentialId?: string;
     /** Non-secret Code Assist project identity, present only for antigravity credentials. */
     projectId?: string;
     /**
-     * Provider account identity the served token executes under. Account-scoped routing joins this
-     * value with `recordVersion`; it is neither the operator's credential label nor the bearer handle.
+     * Provider account identity the served token executes under. Account pools join this value with
+     * the inventory's `refreshAdapter`, not the material's `recordVersion`, so refreshes do not split
+     * one account into new pools. It is neither the operator's credential label nor the bearer handle.
      *
      * BEST-EFFORT, NEVER GUARANTEED, including for JWT providers. The vault parses the claim live
      * from the served access token and falls back to stored login-time identity; both legs can be
@@ -52,6 +55,10 @@ export type ServedCredential = {
     /** Non-secret organization or workspace display metadata captured at login. */
     orgName?: string;
 };
+/** The same credential metadata with opaque payload bytes, without text conversion. */
+export type ServedCredentialBytes = Omit<ServedCredential, 'material'> & {
+    material: Uint8Array;
+};
 /**
  * Non-secret health for one handle, read without minting anything.
  *
@@ -93,7 +100,10 @@ export declare class ClaustrumClient {
     #private;
     private constructor();
     static connect(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
+    /** Fetch UTF-8 text; use `getCredentialBytes` if the payload may contain arbitrary bytes. */
     getCredential(handle: string, minTtlMs?: number): Promise<ServedCredential>;
+    /** Fetch opaque payload bytes by bearer handle without UTF-8 decoding. */
+    getCredentialBytes(handle: string, minTtlMs?: number): Promise<ServedCredentialBytes>;
     statusCredential(handle: string): Promise<CredentialStatus>;
     reportAuthFailure(input: {
         handle: string;
@@ -111,7 +121,8 @@ export declare class ClaustrumClient {
     /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
     watchScoped(onNotice: (notice: ScopedWatchNotice) => void, options?: ScopedWatchOptions): ScopedWatch;
     /**
-     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     * Fetch UTF-8 text by credential id, authorized by a grant rather than a bearer handle.
+     * Use `getScopedBytes` if the payload may contain arbitrary bytes.
      *
      * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
      * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
@@ -123,6 +134,12 @@ export declare class ClaustrumClient {
         enrollmentToken?: string;
         minTtlMs?: number;
     }): Promise<ServedCredential>;
+    /** Fetch opaque bytes by credential id, with the same grant and TTL rules as `getScoped`. */
+    getScopedBytes(input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        minTtlMs?: number;
+    }): Promise<ServedCredentialBytes>;
     /**
      * Report a served credential dead, addressed by id rather than by handle.
      *
@@ -138,6 +155,19 @@ export declare class ClaustrumClient {
         recordVersion: number;
         reporterSource: ClaustrumReporterSource;
     }): Promise<void>;
+    /**
+     * Fire-and-forget quota reporting: `accepted` means queued, never that the
+     * usage-processing module insula applied the reading.
+     * Callers should coalesce per credential and never await this on a request path.
+     *
+     * Reading contents are not validated here. The vault rejects top-level `credentialId`
+     * and `vouched` keys and compact JSON readings over 15,360 bytes with `invalid_params`.
+     */
+    reportUsageScoped(input: {
+        credentialId: string;
+        reading: Record<string, unknown>;
+        enrollmentToken?: string;
+    }): Promise<void>;
     /**
      * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
      * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.

package/dist/wire.js

@@ -52,6 +52,17 @@ function isOptionalString(value) {
  * widen the published surface.
  */
 export function decodeCredential(response, logUnknownClass) {
+    const credential = decodeCredentialBytes(response, logUnknownClass);
+    let material;
+    try {
+        material = new TextDecoder('utf-8', { fatal: true }).decode(credential.material);
+    }
+    catch {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    return { ...credential, material };
+}
+function decodeCredentialBytes(response, logUnknownClass) {
     if (hasCredentialError(response))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
@@ -86,15 +97,8 @@ export function decodeCredential(response, logUnknownClass) {
         !isOptionalString(orgName)) {
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     }
-    let material;
-    try {
-        material = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(payload));
-    }
-    catch {
-        throw asCredentialError(response, 'invalid_response', logUnknownClass);
-    }
     return {
-        material,
+        material: Uint8Array.from(payload),
         recordVersion,
         expiresAtMs,
         credentialId,
@@ -160,6 +164,7 @@ export class ClaustrumClient {
         });
         return new ClaustrumClient(client, connector, connectionFile, options.handshakeTimeoutMs, identity, options.logger ?? ((errorClass) => console.warn(errorClass)));
     }
+    /** Fetch UTF-8 text; use `getCredentialBytes` if the payload may contain arbitrary bytes. */
     async getCredential(handle, minTtlMs) {
         const response = await this.#call('credential.get', {
             handle,
@@ -168,6 +173,15 @@ export class ClaustrumClient {
         });
         return decodeCredential(response, this.#logger);
     }
+    /** Fetch opaque payload bytes by bearer handle without UTF-8 decoding. */
+    async getCredentialBytes(handle, minTtlMs) {
+        const response = await this.#call('credential.get', {
+            handle,
+            min_ttl_ms: minTtlMs,
+            force_refresh: false,
+        });
+        return decodeCredentialBytes(response, this.#logger);
+    }
     async statusCredential(handle) {
         const response = await this.#call('credential.status', { handle });
         return decodeStatus(response, this.#logger);
@@ -204,7 +218,8 @@ export class ClaustrumClient {
         });
     }
     /**
-     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     * Fetch UTF-8 text by credential id, authorized by a grant rather than a bearer handle.
+     * Use `getScopedBytes` if the payload may contain arbitrary bytes.
      *
      * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
      * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
@@ -219,6 +234,15 @@ export class ClaustrumClient {
         });
         return decodeCredential(response, this.#logger);
     }
+    /** Fetch opaque bytes by credential id, with the same grant and TTL rules as `getScoped`. */
+    async getScopedBytes(input) {
+        const response = await this.#call('credential.get_scoped', {
+            credential_id: input.credentialId,
+            enrollment_token: input.enrollmentToken,
+            min_ttl_ms: input.minTtlMs,
+        });
+        return decodeCredentialBytes(response, this.#logger);
+    }
     /**
      * Report a served credential dead, addressed by id rather than by handle.
      *
@@ -241,6 +265,26 @@ export class ClaustrumClient {
         if (result?.accepted !== true)
             throw asCredentialError(response, 'invalid_response', this.#logger);
     }
+    /**
+     * Fire-and-forget quota reporting: `accepted` means queued, never that the
+     * usage-processing module insula applied the reading.
+     * Callers should coalesce per credential and never await this on a request path.
+     *
+     * Reading contents are not validated here. The vault rejects top-level `credentialId`
+     * and `vouched` keys and compact JSON readings over 15,360 bytes with `invalid_params`.
+     */
+    async reportUsageScoped(input) {
+        const response = await this.#call('usage.report_scoped', {
+            credential_id: input.credentialId,
+            reading: input.reading,
+            enrollment_token: input.enrollmentToken,
+        });
+        if (hasCredentialError(response))
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+        if (result?.accepted !== true)
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+    }
     /**
      * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
      * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/dist/handles.d.ts

@@ -1,62 +0,0 @@
-export declare const HANDLE_FILE_CONTRACT: {
-    readonly maxBytes: number;
-    readonly mode: 384;
-    readonly labelRe: RegExp;
-    readonly handleRe: RegExp;
-};
-export declare class HandleFileValidationError extends Error {
-    name: string;
-}
-export type HandleAccount = {
-    label: string;
-    handle: string;
-    credential_id: string;
-    superseded?: string[];
-    minTtlMs?: number;
-};
-export type HandleProvider = {
-    provider: string;
-    shape: 'api' | 'oauth';
-    serve: string;
-    accounts: HandleAccount[];
-};
-export type OpenCodeHandleFileV1 = {
-    version: 1;
-    providers: HandleProvider[];
-};
-export declare function identifierIsValid(value: unknown): value is string;
-export declare function credentialIdMatchesProvider(value: unknown, provider: string): value is string;
-export declare function parseHandleFile(value: unknown): OpenCodeHandleFileV1;
-type HandleFileStat = {
-    isFile(): boolean;
-    isDirectory?(): boolean;
-    isSymbolicLink?(): boolean;
-    mode: number;
-    size?: number;
-    gid?: number;
-    uid?: number;
-    mtimeMs?: number;
-};
-type HandleFileDescriptor = {
-    read?(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
-        bytesRead: number;
-    }> | {
-        bytesRead: number;
-    };
-    stat(): Promise<HandleFileStat>;
-    readFile(options: {
-        encoding: 'utf8';
-    }): Promise<string>;
-    close(): Promise<void>;
-};
-export type HandleFileIo = {
-    stat?: (path: string) => Promise<HandleFileStat>;
-    lstat?: (path: string) => Promise<HandleFileStat>;
-    readFile?: (path: string, encoding: 'utf8') => Promise<string>;
-    open?: (path: string) => Promise<HandleFileDescriptor>;
-    currentUid?: () => number | undefined;
-};
-export declare function defaultHandleFilePath(env?: NodeJS.ProcessEnv): string;
-export declare function readHandleFile(path?: string, io?: HandleFileIo): Promise<OpenCodeHandleFileV1>;
-export declare function handleFileRevision(path?: string, io?: HandleFileIo): Promise<string>;
-export {};

package/dist/handles.js

@@ -1,255 +0,0 @@
-import { createHash } from 'node:crypto';
-import { constants } from 'node:fs';
-import { lstat as nodeLstat, open as nodeOpen, readFile, stat as nodeStat } from 'node:fs/promises';
-import { userInfo } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { checkPrivatePath, notPrivate } from './private-path.js';
-export const HANDLE_FILE_CONTRACT = {
-    maxBytes: 256 * 1024,
-    mode: 0o600,
-    // Shape only: identifier validity also rejects FORBIDDEN_IDENTIFIERS; use
-    // identifierIsValid for validation so callers do not accept parser-rejected labels.
-    labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/,
-    handleRe: /^ckh_[A-Za-z0-9_-]{43}$/,
-};
-const FORBIDDEN_IDENTIFIERS = new Set(['__proto__', 'constructor', 'prototype']);
-export class HandleFileValidationError extends Error {
-    name = 'HandleFileValidationError';
-}
-function isAccount(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const account = value;
-    return typeof account.label === 'string' && typeof account.handle === 'string' &&
-        typeof account.credential_id === 'string' &&
-        (account.superseded === undefined ||
-            (Array.isArray(account.superseded) && account.superseded.every((handle) => typeof handle === 'string')));
-}
-function handleIsValid(handle) {
-    return typeof handle === 'string' && HANDLE_FILE_CONTRACT.handleRe.test(handle);
-}
-export function identifierIsValid(value) {
-    return typeof value === 'string' && HANDLE_FILE_CONTRACT.labelRe.test(value) && !FORBIDDEN_IDENTIFIERS.has(value);
-}
-export function credentialIdMatchesProvider(value, provider) {
-    if (typeof value !== 'string')
-        return false;
-    const segments = value.split(':');
-    return value.length > 0 && segments[1] === provider && segments.every((segment) => segment.length > 0);
-}
-function invalid(message) {
-    throw new HandleFileValidationError(message);
-}
-export function parseHandleFile(value) {
-    if (!value || typeof value !== 'object')
-        invalid('handle file must be an object');
-    const file = value;
-    if (file.version !== 1 || !Array.isArray(file.providers)) {
-        invalid('handle file must have version 1 and providers');
-    }
-    const providerIds = new Set();
-    const providers = file.providers.map((provider, index) => {
-        if (!provider || typeof provider !== 'object')
-            invalid(`provider ${index} must be an object`);
-        const item = provider;
-        if (!identifierIsValid(item.provider))
-            invalid(`provider ${index} has invalid provider`);
-        if (providerIds.has(item.provider))
-            invalid(`provider ${index} duplicates provider ${item.provider}`);
-        providerIds.add(item.provider);
-        if (item.shape !== 'api' && item.shape !== 'oauth')
-            invalid(`provider ${index} has invalid shape`);
-        if (typeof item.serve !== 'string' || !item.serve)
-            invalid(`provider ${index} requires serve`);
-        if (!Array.isArray(item.accounts) || item.accounts.length === 0 || !item.accounts.every(isAccount)) {
-            invalid(`provider ${index} has invalid accounts`);
-        }
-        const labels = new Set();
-        for (const account of item.accounts) {
-            if (!identifierIsValid(account.label))
-                invalid(`provider ${index} has an invalid account label`);
-            if (labels.has(account.label))
-                invalid(`provider ${index} duplicates account label ${account.label}`);
-            labels.add(account.label);
-            if (!handleIsValid(account.handle))
-                invalid(`provider ${index} account ${account.label} has invalid handle`);
-            if (account.minTtlMs !== undefined && !(Number.isSafeInteger(account.minTtlMs) && account.minTtlMs >= 0)) {
-                invalid(`provider ${index} account ${account.label} has invalid minTtlMs`);
-            }
-            // Segment 2 of the credential id must BE the provider block it sits in. Without
-            // this the check was non-empty-string only, so an `oauth:openai` binding parsed
-            // cleanly inside an `anthropic` block -- a cross-provider smuggle that every
-            // tenant reading this manifest would have honoured. Two peer tenants found the
-            // same hole in their own parsers independently.
-            //
-            // SCOPED TO SEGMENT 2 ONLY, deliberately. Segment 1 (the kind) is an OPEN SET --
-            // `oauth:`, `chatgpt:`, `antigravity:`, `apikey:` are all live in this vault today
-            // -- so a kind allowlist would refuse real ids. Segment 3+ (the label) is
-            // operator-chosen and may be absent: main is the 2-segment `oauth:anthropic`,
-            // fallbacks are 3-segment. Constraining either would reject the deployment this
-            // contract describes.
-            //
-            // NO SEGMENT MAY BE EMPTY. Segment 2 alone is what fences the provider, but a
-            // position-1 check ignores the rest of the string, and that left two ids passing
-            // that name credentials which cannot exist: `:anthropic:x` (empty kind) and
-            // `oauth:anthropic:` (empty label) both satisfy "segment 2 is the provider"
-            // literally. Neither is a smuggle; both defer a GUARANTEED resolve-time failure
-            // past the door, and under custody a resolve-time failure on a tombstoned account
-            // is a dark route rather than a refused row.
-            //
-            // It also removes an asymmetry nobody designed and everyone would read as a bug:
-            // `oauth::anthropic` rejected while `:anthropic:x` passed, purely because the
-            // check indexed position 1 and ignored positions 0 and 2. Agreed with the peer
-            // tenant and mirrored on their side, so this is chosen rather than defaulted --
-            // the previous behaviour was two independent defaults that happened to differ.
-            //
-            // The emptiness guard is ALSO explicit rather than a consequence: `''.split(':')`
-            // yields `['']`, whose `[1]` is `undefined` and cannot equal a provider string,
-            // so an empty id would reject anyway -- but that is a coincidence doing
-            // load-bearing work, and the check this replaced (`!account.credential_id`) was
-            // the emptiness guard. NO TEST DISTINGUISHES THAT ONE (empty rejects with or
-            // without it, verified by removal), so it is kept for a future reader who loosens
-            // the comparison, not for an arm it could never redden. The non-empty-SEGMENT
-            // rule in credentialIdMatchesProvider is different: it reddens, and is pinned.
-            if (!credentialIdMatchesProvider(account.credential_id, item.provider)) {
-                invalid(`provider ${index} account ${account.label} has invalid credential id`);
-            }
-            if (account.superseded?.some((handle) => !handleIsValid(handle))) {
-                invalid(`provider ${index} account ${account.label} has invalid superseded handle`);
-            }
-        }
-        return {
-            provider: item.provider,
-            shape: item.shape,
-            serve: item.serve,
-            accounts: item.accounts.map((account) => ({
-                ...account,
-                ...(account.superseded === undefined ? {} : { superseded: account.superseded }),
-            })),
-        };
-    });
-    return { version: 1, providers };
-}
-export function defaultHandleFilePath(env = process.env) {
-    if (env.CLAUSTRUM_OPENCODE_HANDLES)
-        return env.CLAUSTRUM_OPENCODE_HANDLES;
-    const configHome = env.XDG_CONFIG_HOME || (env.HOME ? join(env.HOME, '.config') : '.config');
-    return join(configHome, 'cortexkit', 'opencode-handles.json');
-}
-function currentUid() {
-    return process.platform === 'win32' ? undefined : process.getuid?.() ?? userInfo().uid;
-}
-async function readBounded(descriptor, cap) {
-    if (!descriptor.read)
-        throw new Error('readBounded requires a descriptor exposing read()');
-    const buffer = Buffer.alloc(cap + 1);
-    let total = 0;
-    while (total < cap + 1) {
-        const chunk = await descriptor.read(buffer, total, buffer.length - total, total);
-        if (chunk.bytesRead === 0)
-            break;
-        total += chunk.bytesRead;
-    }
-    return { buffer, bytes: total > cap ? -1 : total };
-}
-async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
-    path = resolve(path);
-    const stat = io.stat ?? nodeStat;
-    const lstat = io.lstat ?? nodeLstat;
-    const read = io.readFile ?? readFile;
-    const openFd = io.open ?? ((candidate) => nodeOpen(candidate, constants.O_RDONLY | constants.O_NOFOLLOW));
-    let descriptor;
-    try {
-        let metadata;
-        try {
-            if (io.lstat || io.readFile) {
-                metadata = await lstat(path);
-            }
-            else {
-                descriptor = await openFd(path);
-                metadata = await descriptor.stat();
-            }
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return { file: { version: 1, providers: [] } };
-            if (error.code === 'ELOOP')
-                invalid('handle file must not be a symlink');
-            invalid(`cannot stat handle file: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        if (metadata.isSymbolicLink?.())
-            invalid('handle file must not be a symlink');
-        if (!metadata.isFile())
-            invalid('handle file must be a regular file');
-        if ((metadata.size ?? 0) > HANDLE_FILE_CONTRACT.maxBytes)
-            invalid('handle file exceeds 256 KiB');
-        if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-            invalid('handle file mode must be exactly 0600');
-        const uid = io.currentUid ?? currentUid;
-        const expectedUid = uid();
-        if (expectedUid !== undefined && metadata.uid !== undefined && metadata.uid !== expectedUid) {
-            invalid('handle file is not owned by the current uid');
-        }
-        let parent;
-        try {
-            parent = await stat(dirname(path));
-        }
-        catch (error) {
-            invalid(`cannot stat handle file parent: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        if (!parent.isDirectory?.())
-            invalid('handle file parent must be a directory');
-        if (expectedUid !== undefined && parent.uid !== undefined && parent.uid !== expectedUid) {
-            invalid('handle file parent is not owned by the current uid');
-        }
-        // HandleFileIo's injected stat supplies ancestor metadata as well as the immediate
-        // parent. Pass that metadata to @cortexkit/store's Unix path check.
-        const fixtureStat = io.stat && (async (candidate) => {
-            const value = await io.stat(candidate);
-            return { ...value, isDirectory: () => value.isDirectory?.() ?? false };
-        });
-        const protection = await checkPrivatePath(process.platform === 'win32' ? path : dirname(path), fixtureStat ? {
-            euid: expectedUid,
-            fs: { stat: fixtureStat, lstat: fixtureStat },
-        } : undefined);
-        if (!protection.ok)
-            invalid(notPrivate('handle file folder', protection));
-        let source;
-        try {
-            if (descriptor) {
-                const { buffer, bytes } = await readBounded(descriptor, HANDLE_FILE_CONTRACT.maxBytes);
-                if (bytes === -1)
-                    invalid('handle file exceeds 256 KiB');
-                source = buffer.subarray(0, bytes).toString('utf8');
-            }
-            else {
-                source = await read(path, 'utf8');
-            }
-        }
-        catch (error) {
-            if (error instanceof HandleFileValidationError)
-                throw error;
-            invalid(`cannot read handle file: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        let value;
-        try {
-            value = JSON.parse(source);
-        }
-        catch {
-            invalid('handle file contains invalid JSON');
-        }
-        return { file: parseHandleFile(value), source, mtimeMs: metadata.mtimeMs };
-    }
-    finally {
-        await descriptor?.close();
-    }
-}
-export async function readHandleFile(path = defaultHandleFilePath(), io = {}) {
-    return (await readHandleSnapshot(path, io)).file;
-}
-export async function handleFileRevision(path = defaultHandleFilePath(), io = {}) {
-    const snapshot = await readHandleSnapshot(path, io);
-    if (snapshot.source === undefined)
-        invalid('cannot revise absent handle file');
-    return `${snapshot.mtimeMs ?? 0}:${createHash('sha256').update(snapshot.source).digest('hex')}`;
-}

package/dist/manifest-lock.d.ts

@@ -1,32 +0,0 @@
-import { type OpenCodeHandleFileV1 } from './handles.js';
-export declare const MANIFEST_LOCK: {
-    ttlMs: number;
-    renewEveryMs: number;
-    ownerKeys: readonly ['tenant', 'pid', 'claimed_at_ms', 'nonce'];
-    staleTargetRe: RegExp;
-    errorCodes: readonly ['lock_busy', 'owner_invalid', 'renewal_failed', 'unsupported_platform'];
-};
-/** Thrown by the lock. Branch on `code`; the message is diagnostic and may be reworded. */
-export type ManifestLockErrorCode = (typeof MANIFEST_LOCK.errorCodes)[number];
-export type ManifestLockError = Error & {
-    code: ManifestLockErrorCode;
-};
-export type ManifestHandleAccount = OpenCodeHandleFileV1['providers'][number]['accounts'][number];
-export type ManifestHandleProvider = OpenCodeHandleFileV1['providers'][number];
-export type ManifestHandleFile = OpenCodeHandleFileV1;
-type TestOptions = {
-    ttlMs?: number;
-    renewEveryMs?: number;
-    retryMinMs?: number;
-    retryMaxMs?: number;
-    afterClaim?: () => Promise<void> | void;
-    beforeEvict?: () => Promise<void>;
-    afterEvictRenameAttempt?: () => Promise<void>;
-    afterEvict?: () => void;
-    beforeManifestRename?: (path: string) => Promise<void>;
-};
-export declare function __setManifestLockTestOptions(options?: TestOptions): void;
-export declare function manifestLockQuarantinePrefix(path: string, basename?: (p: string) => string): string | undefined;
-export declare function withManifestLock<T>(path: string, tenant: string, fn: () => Promise<T> | T): Promise<T>;
-export declare function writeHandleFileLocked(path: string, tenant: string, mutate: (file: ManifestHandleFile) => void | ManifestHandleFile | Promise<void | ManifestHandleFile>): Promise<void>;
-export {};

package/dist/manifest-lock.js

@@ -1,333 +0,0 @@
-import { createPrivateDirectory, createPrivateFile } from '@cortexkit/store';
-import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.js';
-import { lstat, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
-import { randomBytes, randomInt } from 'node:crypto';
-import { basename as pathBasename, dirname, join, resolve } from 'node:path';
-import { HANDLE_FILE_CONTRACT, parseHandleFile } from './handles.js';
-export const MANIFEST_LOCK = { ttlMs: 30_000, renewEveryMs: 10_000, ownerKeys: ['tenant', 'pid', 'claimed_at_ms', 'nonce'], staleTargetRe: /^\.lock\.stale-\d+-(?!\.{1,2}$)(?!.*[. ]$)[^/\\\x00-\x1f:*?"<>|]{1,128}$/, errorCodes: ['lock_busy', 'owner_invalid', 'renewal_failed', 'unsupported_platform'] };
-// The claim deadline bounds when the last stale-lock rename is issued, not when it lands:
-// a rename issued at deadline-1ms can complete afterwards, by tens to hundreds of ms on a
-// loaded host. The retry deadline and staleness window both read `ttl` today; if they split,
-// this bound must keep their max so reclamation still covers the longer role.
-const MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS = 5_000;
-let testOptions;
-export function __setManifestLockTestOptions(options) { testOptions = options; }
-// 16 CSPRNG bytes: a collision needs both the same millisecond and the same nonce. Do not
-// simplify this to a counter, pid+timestamp, or a short token.
-const token = () => randomBytes(16).toString('base64url');
-const code = privateCreationCode;
-const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-// A tenant classifying a failure must not string-match our prose: a copy-edit would
-// silently reclassify a retryable busy-lock as an unknown error, with nothing failing
-// loudly. The code is the contract; the message is free to change.
-const lockError = (code, message) => Object.assign(new Error(message), { code });
-const unsupportedOnWindows = () => lockError('unsupported_platform', 'handle-file manifest locking is not supported on Windows');
-function parseOwner(source) {
-    let value;
-    try {
-        value = JSON.parse(source);
-    }
-    catch {
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    }
-    if (!value || typeof value !== 'object')
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    const owner = value;
-    // Widen the nonce alphabet only after every tenant has this path-safe reader; an older
-    // allowlist reader can otherwise wedge forever on the first owner using the new alphabet.
-    const staleTarget = `.lock.stale-${owner.claimed_at_ms}-${owner.nonce}`;
-    if (MANIFEST_LOCK.ownerKeys.some((key) => !Object.hasOwn(owner, key)) || typeof owner.claimed_at_ms !== 'number' || !Number.isInteger(owner.claimed_at_ms) || owner.claimed_at_ms < 0 || typeof owner.nonce !== 'string' || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    return owner;
-}
-const readOwner = async (path) => parseOwner(await readFile(path, 'utf8'));
-async function writeOwner(lock, owner) {
-    const target = join(lock, 'owner');
-    const temporary = join(lock, `owner.${process.pid}.${token()}.tmp`);
-    let file;
-    try {
-        await createPrivateFile(temporary, `${JSON.stringify(owner)}\n`);
-        file = await open(temporary, 'r+');
-        await file.sync();
-        await file.close();
-        file = undefined;
-        await rename(temporary, target);
-    }
-    finally {
-        await file?.close().catch(() => { });
-        await unlink(temporary).catch(() => { });
-    }
-}
-// Split out from the sweep so the platform claim is testable from a POSIX runner: this takes
-// the basename FUNCTION, so a test can drive it with path.win32.basename without pretending
-// a Linux host is Windows. A filesystem test cannot do that -- on Linux a '/' split and
-// basename agree, so the defect below survives every filesystem test written against it.
-//
-// pathBasename, not a split on '/': on Windows the manifest path is backslash-separated, so a
-// '/' split yields the whole path, nothing matches the prefix, and the sweep becomes a silent
-// no-op on the one platform the quarantine bound is hardest to observe. Fails closed -- it
-// cannot reap the wrong directory -- but the feature is inert, which is worse than loud.
-export function manifestLockQuarantinePrefix(path, basename = pathBasename) {
-    const name = basename(path);
-    return name ? name : undefined;
-}
-async function reclaimStaleManifestLockQuarantines(path, ttlMs, claimDeadlineMs) {
-    const reclaimAgeMs = Math.max(ttlMs, claimDeadlineMs) + MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS;
-    let names;
-    try {
-        names = await readdir(dirname(path));
-    }
-    catch {
-        return;
-    }
-    const basename = manifestLockQuarantinePrefix(path);
-    if (!basename)
-        return;
-    await Promise.all(names.map(async (name) => {
-        const staleTarget = name.startsWith(basename) ? name.slice(basename.length) : undefined;
-        if (!staleTarget || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
-            return;
-        const target = join(dirname(path), name);
-        let metadata;
-        try {
-            metadata = await lstat(target);
-        }
-        catch {
-            return;
-        }
-        if (!metadata.isDirectory() || Date.now() - metadata.mtimeMs < reclaimAgeMs)
-            return;
-        await rm(target, { recursive: true, force: true }).catch(() => { });
-    }));
-}
-export async function withManifestLock(path, tenant, fn) {
-    return withLockCommit(path, tenant, async () => fn());
-}
-async function withLockCommit(path, tenant, fn) {
-    // Stale-lock eviction renames the lock directory while another process may hold it
-    // open. That is safe under POSIX rename; on Windows CI two evictors both won and a
-    // rename of an open lock failed with EPERM. Until the protocol is proven there,
-    // refuse rather than risk two writers overlapping on the shared handle file.
-    if (process.platform === 'win32')
-        throw unsupportedOnWindows();
-    path = resolve(path);
-    const lock = `${path}.lock`, ownerPath = join(lock, 'owner'), ttl = testOptions?.ttlMs ?? MANIFEST_LOCK.ttlMs, renewEvery = testOptions?.renewEveryMs ?? MANIFEST_LOCK.renewEveryMs, retryMin = testOptions?.retryMinMs ?? 25, retryMax = testOptions?.retryMaxMs ?? 75;
-    const nonce = token(), started = Date.now(), deadline = started + ttl;
-    while (true) {
-        try {
-            await createPrivateDirectory(lock);
-            await writeOwner(lock, { tenant, pid: process.pid, claimed_at_ms: Date.now(), nonce });
-            await testOptions?.afterClaim?.();
-            break;
-        }
-        catch (error) {
-            if (code(error) !== 'EEXIST') {
-                if (code(error) !== 'ENOENT')
-                    await rm(lock, { recursive: true, force: true }).catch(() => { });
-                throw error;
-            }
-        }
-        let observed, ownerReadError;
-        try {
-            observed = await readOwner(ownerPath);
-        }
-        catch (error) {
-            ownerReadError = error;
-            if (code(error) !== 'ENOENT' && Date.now() >= deadline)
-                throw code(error) === 'owner_invalid' ? error : lockError('lock_busy', 'manifest lock busy');
-        }
-        if (!observed && code(ownerReadError) === 'ENOENT') {
-            const metadata = await lstat(lock).catch(() => undefined);
-            if (metadata?.isDirectory() && Date.now() - metadata.mtimeMs >= ttl) {
-                await testOptions?.beforeEvict?.();
-                const stale = `${lock}.stale-${Math.floor(metadata.mtimeMs)}-${token()}`;
-                try {
-                    await rename(lock, stale);
-                    // A claimant may have published its owner while the eviction was pending.
-                    const moved = await lstat(stale);
-                    const ownerExists = await lstat(join(stale, 'owner')).then(() => true, (error) => code(error) !== 'ENOENT');
-                    if (!ownerExists && moved.mtimeMs === metadata.mtimeMs) {
-                        testOptions?.afterEvict?.();
-                        continue;
-                    }
-                    await rename(stale, lock).catch(() => { });
-                }
-                catch (error) {
-                    if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(error) ?? ''))
-                        throw error;
-                }
-            }
-        }
-        if (observed && Date.now() - observed.claimed_at_ms >= ttl) {
-            await testOptions?.beforeEvict?.();
-            // The owner record remains because the quarantine is the ABA guard, not an audit log;
-            // bounded reclamation below is what makes that retention finite.
-            const stale = `${lock}.stale-${observed.claimed_at_ms}-${observed.nonce}`;
-            let renameError;
-            try {
-                await rename(lock, stale);
-            }
-            catch (error) {
-                renameError = error;
-            }
-            await testOptions?.afterEvictRenameAttempt?.();
-            if (renameError === undefined) {
-                const moved = await readOwner(join(stale, 'owner')).catch(() => undefined);
-                if (moved?.nonce === observed.nonce && moved.claimed_at_ms === observed.claimed_at_ms) {
-                    testOptions?.afterEvict?.();
-                    continue;
-                }
-                await rename(stale, lock).catch(() => { });
-            }
-            else if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(renameError) ?? ''))
-                throw renameError;
-        }
-        if (Date.now() >= deadline)
-            throw code(ownerReadError) === 'owner_invalid' ? ownerReadError : lockError('lock_busy', 'manifest lock busy');
-        await sleep(Math.min(randomInt(retryMin, retryMax + 1), Math.max(1, deadline - Date.now())));
-    }
-    await reclaimStaleManifestLockQuarantines(path, ttl, deadline - started);
-    let renewal = Promise.resolve(), failed = false, stopped = false;
-    const timer = setInterval(() => { renewal = renewal.then(async () => { if (failed)
-        return; try {
-        const current = await readOwner(ownerPath);
-        if (current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-            throw new Error('lease lost');
-        await writeOwner(lock, { ...current, claimed_at_ms: Date.now() });
-    }
-    catch {
-        failed = true;
-    } }); }, renewEvery);
-    timer.unref?.();
-    const commit = async () => { if (!stopped) {
-        stopped = true;
-        clearInterval(timer);
-        await renewal;
-    } ; const current = await readOwner(ownerPath).catch(() => undefined); if (failed || !current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-        throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted'); };
-    try {
-        const result = await fn(commit);
-        if (failed)
-            throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted');
-        return result;
-    }
-    finally {
-        if (!stopped)
-            clearInterval(timer);
-        await renewal;
-        const current = await readOwner(ownerPath).catch(() => undefined);
-        if (!current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-            console.warn('manifest lock lease lost, not releasing', { path, tenant });
-        else {
-            const release = `${lock}.release-${nonce}`;
-            try {
-                await rename(lock, release);
-                const moved = await readOwner(join(release, 'owner')).catch(() => undefined);
-                if (!moved || moved.nonce !== nonce || Date.now() - moved.claimed_at_ms >= ttl) {
-                    await rename(release, lock).catch(() => { });
-                    console.warn('manifest lock lease lost, not releasing', { path, tenant });
-                }
-                else
-                    await rm(release, { recursive: true, force: true });
-            }
-            catch {
-                console.warn('manifest lock lease lost, not releasing', { path, tenant });
-            }
-        }
-    }
-}
-async function readManifest(path) {
-    let metadata;
-    try {
-        metadata = await lstat(path);
-    }
-    catch (error) {
-        if (code(error) === 'ENOENT')
-            return { version: 1, providers: [] };
-        throw error;
-    }
-    if (metadata.isSymbolicLink() || !metadata.isFile())
-        throw new Error('handle file must be a regular file');
-    if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-        throw new Error('handle file mode must be exactly 0600');
-    const protection = await checkPrivatePath(path);
-    if (!protection.ok)
-        throw new Error(notPrivate('handle file folder', protection));
-    const source = await readFile(path);
-    if (source.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
-        throw new Error('handle file exceeds 256 KiB');
-    return parseHandleFile(JSON.parse(source.toString('utf8')));
-}
-const foreign = (file, tenant) => file.providers.filter((provider) => provider.serve !== tenant).map((provider) => JSON.stringify(provider));
-async function refuseWritableAncestors(parent) {
-    const protection = await checkPrivatePath(parent);
-    if (!protection.ok)
-        throw new Error(notPrivate('handle file folder', protection));
-}
-async function prepareParent(path) {
-    const parent = dirname(path);
-    // Check existing ancestors before creating directories under a replaceable tree.
-    if (process.platform !== 'win32')
-        await refuseWritableAncestors(parent);
-    const existing = await stat(parent).catch((error) => { if (code(error) !== 'ENOENT')
-        throw error; return undefined; });
-    if (existing && typeof process.getuid === 'function' && existing.uid !== process.getuid())
-        throw new Error('handle file parent is not owned by the current uid');
-    await createPrivateParents(parent);
-    const metadata = await stat(parent);
-    if (!metadata.isDirectory())
-        throw new Error('handle file parent must be a directory');
-    if (typeof process.getuid === 'function' && metadata.uid !== process.getuid())
-        throw new Error('handle file parent is not owned by the current uid');
-    await refuseWritableAncestors(parent);
-}
-async function writeAtomic(path, file, commit) {
-    const bytes = Buffer.from(JSON.stringify(file));
-    if (bytes.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
-        throw new Error('handle file exceeds 256 KiB');
-    // pathBasename for the same reason the quarantine sweep uses it, but this one fails LOUD
-    // rather than inert: a '/' split over a backslash path yields the whole path, so the temp
-    // name embeds separators and a drive-letter colon, join() nests it under its own directory,
-    // and O_CREAT|O_EXCL throws on a name Windows will not accept -- taking the manifest WRITE
-    // down, not just the reclaim. Covered by the dual-basename test, which a POSIX filesystem
-    // test cannot reach.
-    const temporary = join(dirname(path), `.${pathBasename(path)}.${process.pid}.${token()}.tmp`);
-    let handle;
-    try {
-        await createPrivateFile(temporary, bytes);
-        handle = await open(temporary, 'r+');
-        await handle.sync();
-        await handle.close();
-        handle = undefined;
-        await testOptions?.beforeManifestRename?.(`${path}.lock`);
-        await commit();
-        await rename(temporary, path);
-    }
-    finally {
-        await handle?.close().catch(() => { });
-        await unlink(temporary).catch(() => { });
-    }
-}
-export async function writeHandleFileLocked(path, tenant, mutate) {
-    // Refuse before any path check, so a Windows caller gets the platform reason rather
-    // than a private-path refusal from the parent check that runs next.
-    if (process.platform === 'win32')
-        throw unsupportedOnWindows();
-    path = resolve(path);
-    await prepareParent(path);
-    await withLockCommit(path, tenant, async (commit) => {
-        const before = await readManifest(path), working = structuredClone(before), result = await mutate(working), next = parseHandleFile(result ?? working), beforeForeign = foreign(before, tenant);
-        if (JSON.stringify(foreign(next, tenant)) !== JSON.stringify(beforeForeign))
-            throw new Error('manifest mutation changed another tenant block');
-        await writeAtomic(path, next, commit);
-        if (process.platform !== 'win32' && ((await lstat(path)).mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-            throw new Error('manifest readback mode is not 0600');
-        if (!(await checkPrivatePath(path)).ok)
-            throw new Error('manifest readback mode is not 0600');
-        const readback = await readManifest(path);
-        if (JSON.stringify(readback) !== JSON.stringify(next))
-            throw new Error('manifest readback differs');
-        if (JSON.stringify(foreign(readback, tenant)) !== JSON.stringify(beforeForeign))
-            throw new Error('manifest readback changed another tenant block');
-    });
-}