@agent-native/core 0.112.0 → 0.113.0

package/corpus/README.md

@@ -7,6 +7,7 @@ inside installed apps at `node_modules/@agent-native/core/corpus`.
 ## Contents
 
 - `core/` -- source and package files for `@agent-native/core`.
+- `toolkit/` -- source and package files for `@agent-native/toolkit`.
 - `templates/` -- source-only copies of first-party Agent Native templates.
 
 Runtime data, local env files, dependency folders, caches, tests, and build
@@ -27,5 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1477
-- template files: 6026
+- core files: 1497
+- toolkit files: 136
+- template files: 6048

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @agent-native/core
 
+## 0.113.0
+
+### Minor Changes
+
+- e53a34e: Extract reusable Postgres search and embedding primitives into Core while preserving Creative Context imports.
+  The pgvector setup error now consistently says "Vector search" instead of the narrower "Visual search" wording.
+- e53a34e: Add reusable Google and Slack OAuth compatibility helpers, including Slack's Basic-auth token exchange, Gong lookup utilities, and SSRF-safe JSON webhook delivery with shared Slack escaping.
+- e53a34e: Add reusable provider API and staged dataset action factories, including opt-in custom provider registration and sanitized provider request audit summaries that narrow recorded audit metadata to safe request context.
+
+### Patch Changes
+
+- e53a34e: Add a subscription-only Claude Code participant runtime with enforced read-only and driver permissions.
+- e53a34e: Add a ChatGPT-subscription Codex CLI participant runtime with enforced read-only and driver sandboxes.
+- e53a34e: Add durable, fenced local state for compound multi-frontier runs.
+- e53a34e: Move the reusable ChatHistoryList and its stylesheet to the Toolkit chat-history entrypoint while preserving Core compatibility imports. Adopt it across first-party full-page chat sidebars, ship readable Toolkit source, and add generated-app guidance for selective app-owned UI customization.
+- e53a34e: Keep interrupted local Codex runs paused and resumable across every runner command.
+- e53a34e: Harden local Code run persistence and cancellation for the packaged desktop runner.
+- e53a34e: Harden local Code run and transcript persistence with atomic replacements and idempotent events.
+- e53a34e: Persist bounded, redacted Desktop multi-frontier orchestration state for safe recovery.
+- Updated dependencies [e53a34e]
+  - @agent-native/toolkit@0.7.0
+
 ## 0.112.0
 
 ### Minor Changes

package/corpus/core/docs/AGENTS.md

@@ -25,6 +25,7 @@ pnpm action docs-search --slug actions
 pnpm action source-search --list
 pnpm action source-search --query "defineAction useActionQuery"
 pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
 ```
 
 The built-in app agent also has read-only `docs-search` and `source-search`
@@ -42,6 +43,12 @@ For source examples, read matching files under
 `node_modules/@agent-native/core/corpus/core/` or
 `node_modules/@agent-native/core/corpus/templates/`.
 
+Readable Toolkit TypeScript is available under
+`node_modules/@agent-native/toolkit/src/`. Before adapting it, read the
+generated app's `customizing-agent-native` skill. Treat installed source as a
+read-only reference, copy only the smallest UI piece into app-owned source, and
+preserve public action, state, auth, and agent-chat runtime contracts.
+
 ## What To Read First
 
 | Task                                  | Start with                                                                                               |

package/corpus/core/docs/content/integrations.mdx

@@ -409,8 +409,69 @@ these built-in providers:
 These entries are available to actions through the shared
 `provider-api-catalog`, `provider-api-docs`, and `provider-api-request` pattern.
 They do not imply that the provider also appears in the remote MCP picker.
-Custom provider registrations can extend this action catalog without changing
-the built-in list above.
+
+### Reuse the Core action factories {#provider-api-factories}
+
+Provider API actions are reusable Core primitives, not an implementation to
+copy between apps. App builders should keep a thin action file for each stable
+app-facing action id, then delegate its behavior to the shared factory. That
+keeps app-specific provider enums, descriptions, HTTP exposure, and
+`toolCallable` choices intact while Core owns request safety, auditing,
+credential injection, and staging.
+
+```ts
+import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
+
+import { MY_APP_ID, getMyProviderApiRuntime } from "../server/provider-api";
+
+export default createProviderApiRequestAction(getMyProviderApiRuntime(), {
+  appId: MY_APP_ID,
+  schema: myProviderRequestSchema,
+  description: "Call a configured provider API for this app.",
+  http: { method: "POST" },
+  toolCallable: false,
+});
+```
+
+Use `createProviderApiCatalogAction` and `createProviderApiDocsAction` for the
+other two actions. Their runtime is the app's provider runtime; the wrapper is
+where an app deliberately narrows provider ids or preserves its own public
+action contract. Do not reimplement the request, catalog, or docs behavior in
+each template.
+
+For data too large to keep in a response, pass `stageAs` to the request action
+and expose thin wrappers around `createQueryStagedDatasetAction`,
+`createListStagedDatasetsAction`, and `createDeleteStagedDatasetAction` (or the
+combined `createStagedDatasetActions`). Set the same `appId` on request and
+staged-dataset factories. Core scopes staged data to that app and the current
+credential owner, so one user's scratch data cannot be queried or deleted by a
+different user or app.
+
+### Credentials and custom providers {#provider-api-authority}
+
+The provider runtime is the credential authority. It resolves a scoped
+workspace connection, OAuth account, or secret and injects authentication into
+an allowed provider request. Action arguments, provider registrations, and
+docs may name credential keys or connection ids, but must never accept, store,
+or log credential values. Use the app's secrets and onboarding surfaces to
+collect credentials; use workspace grants when an account should be shared
+across apps.
+
+Apps can add their own provider integrations. Start with a thin wrapper over a
+runtime that recognizes the provider, then use the catalog and docs actions to
+make its safe capabilities discoverable. Custom-provider registration is
+deliberately opt-in:
+
+```ts
+createProviderApiActions(runtime, { customProviderRegistration: true });
+```
+
+This exposes the registration action only when the app chooses to support it.
+Registration stores endpoint and credential-key
+metadata, never secret values, and organization-scoped mutations require the
+runtime's authorization checks. A custom provider registration is not a remote
+MCP preset or a webhook adapter; add those separate integrations only when the
+product needs them.
 
 ## Keep the directory honest {#keep-current}
 

package/corpus/core/docs/design/provider-integration-authority.md

@@ -0,0 +1,117 @@
+# ADR: Defer `defineIntegration` Until Authority Boundaries Converge
+
+Status: Accepted
+
+Date: 2026-07-19
+
+## Context
+
+Several framework surfaces describe a provider or integration: shared workspace
+connections, Dispatch Vault secrets, custom provider APIs, and managed messaging
+adapters. They are related, but they do not have one interchangeable authority
+model. A generic `defineIntegration(...)` API would imply a shared lifecycle for
+credentials, grants, OAuth installation, request dispatch, and user-visible
+setup before that lifecycle exists.
+
+The immediate cost would be an attractive abstraction that either bypasses an
+existing access check or becomes a thin facade over incompatible stores. The
+more serious cost is migration risk: live OAuth and Slack installations cannot
+be lost, silently disconnected, or made invisible while an API is normalized.
+
+## Decision
+
+Do not add `defineIntegration` yet. Keep each existing authority in its current
+owner and use narrow bridges only where the implementation is demonstrably
+shared. A future integration definition must compose existing authority
+contracts; it must not replace them with a new credential or access model.
+
+## Authority Boundary Map
+
+| Surface                          | Current authority          | What it owns                                                                                                                  | Boundary for a future abstraction                                                                                                                                       |
+| -------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Workspace connections and grants | Core workspace-connections | Shared provider connection metadata, app grants, scoped credential resolution, and readiness                                  | An integration may request a connection only through its app grant. It cannot treat a provider label as access to every workspace credential.                           |
+| Dispatch Vault                   | Dispatch                   | Workspace secret lifecycle, requests, approvals, grants, audit, and sync into app credential scopes                           | Vault is a credential-distribution authority, not a provider transport or OAuth-install store. A generic integration API must not bypass Vault approval or audit paths. |
+| Custom provider registry         | Core provider-api          | Scoped provider metadata, allowed hosts, auth descriptor, docs links, SSRF validation, and request-time credential resolution | Registry rows describe an allowed outbound API. They do not grant messaging installation, workspace connection, or Vault access by themselves.                          |
+| Messaging adapters               | Core integrations          | Signed inbound webhooks, platform identity, managed installations, token health, scopes, queues, and outbound delivery        | A messaging adapter is a runtime channel with its own installation and webhook contract, not just another HTTP provider.                                                |
+
+These boundaries deliberately permit one product to use more than one surface:
+for example, a workspace-granted connection can supply provider credentials,
+while Dispatch governs a separately shared secret, and a messaging adapter owns
+an inbound channel installation. No generic record may collapse those distinct
+authorities into one unscoped token reference.
+
+## Consequences
+
+- Core remains the authority for runtime request context, credential resolution,
+  SSRF protection, OAuth tokens, workspace-connection grants, and managed
+  messaging installations.
+- Dispatch remains the authority for Vault policy, approval, audit, and
+  distribution. Provider code must consume its scoped credential result rather
+  than read Vault records directly.
+- Toolkit remains presentation-only. It can render readiness and setup supplied
+  by Core adapters, but must not import Core runtime contracts or own provider
+  credentials.
+- Reusable low-level helpers are still encouraged when they preserve the owner
+  of the data and access decision. Examples include OAuth exchange helpers,
+  provider response normalization, and a hardened outbound-delivery primitive.
+
+## Deferred Work And Required Follow-ups
+
+### Provider API registration reads
+
+`provider-api-register` has mutation-side authorization for custom-provider
+scope. Before making registration a general integration primitive, add and test
+equivalent request-context scoping for its list and get operations. The
+operations must resolve the caller's user/org context and return only providers
+visible in that scope; callers must not be able to select an arbitrary
+`scopeId` to enumerate or read another tenant's registry entries.
+
+### Clips Slack migration
+
+Clips currently has a product-specific Slack unfurl installation: its own
+`slack_installations` metadata, app-secret token references, `link_shared`
+webhook routing, and unfurl-only scopes. Core managed messaging installs use a
+different table and encrypted token-bundle format. Do not replace the Clips
+path until all of the following are true:
+
+1. The target store preserves the Clips team/app lookup, owner/org access, and
+   unfurl-only scopes.
+2. Webhook handling can dual-read the new managed installation and the legacy
+   Clips row, with the existing row as a fallback until migration completion.
+3. Existing app-secret references are imported or safely resolved without
+   exposing tokens to route responses.
+4. List, status, disconnect, and signed `link_shared` delivery have migration
+   coverage using an existing installation.
+5. Production telemetry proves that the new read path handles live events
+   before legacy rows or secret references are removed.
+
+### Zoom
+
+Zoom is not currently a Core provider-api, workspace-connection, or managed
+messaging catalog entry. It is a real OAuth capability in the Calendar template
+backed by the Scheduling package's video-provider API and Core OAuth-token
+storage. Treat Zoom as a later provider-catalog candidate, not evidence that a
+generic integration API already has a common model. Revisit catalog inclusion
+only when there is a defined owner for connection grants, credential setup,
+token refresh, and the Calendar/Scheduling compatibility contract.
+
+## Revisit Criteria
+
+Reconsider `defineIntegration` only when all of these are satisfied:
+
+1. At least two production consumers share the same lifecycle, not merely a
+   provider name or an OAuth exchange endpoint.
+2. The API has explicit ports for request context, authorization, credential
+   resolution, token storage, outbound-host policy, and audit ownership.
+3. Workspace-connection grants, Dispatch Vault policy, custom-provider scope,
+   and messaging-install access are represented as distinct inputs or are
+   explicitly inapplicable; none is inferred from a provider id.
+4. Each migrated surface has a documented compatibility path, dual-read or
+   backfill plan where durable data exists, rollback behavior, and focused
+   tests for existing installations/connections.
+5. The public API can state what it does not own: domain-specific routes,
+   provider-specific payloads, app data models, and presentation UI remain with
+   the appropriate app or Toolkit adapter.
+
+Until then, prefer focused Core exports and app adapters over a universal
+registration API.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -245,6 +245,7 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./provider-api": "./dist/provider-api/index.js",
+    "./provider-api/gong": "./dist/provider-api/gong.js",
     "./provider-api/corpus-jobs": "./dist/provider-api/corpus-jobs.js",
     "./provider-api/corpus-jobs-store": "./dist/provider-api/corpus-jobs-store.js",
     "./provider-api/staging": "./dist/provider-api/staging.js",
@@ -253,7 +254,11 @@
     "./provider-api/actions/query-staged-dataset": "./dist/provider-api/actions/query-staged-dataset.js",
     "./provider-api/actions/list-staged-datasets": "./dist/provider-api/actions/list-staged-datasets.js",
     "./provider-api/actions/delete-staged-dataset": "./dist/provider-api/actions/delete-staged-dataset.js",
+    "./provider-api/actions/staged-datasets": "./dist/provider-api/actions/staged-datasets.js",
     "./provider-api/actions/github-repo-files": "./dist/provider-api/actions/github-repo-files.js",
+    "./provider-api/actions/provider-api": "./dist/provider-api/actions/provider-api.js",
+    "./provider-api/actions/provider-api-audit": "./dist/provider-api/actions/provider-api-audit.js",
+    "./provider-api/actions/custom-provider-registration": "./dist/provider-api/actions/custom-provider-registration.js",
     "./data-programs": {
       "types": "./dist/data-programs/index.d.ts",
       "default": "./dist/data-programs/index.js"

package/corpus/core/scripts/materialize-source-corpus.mjs

@@ -281,6 +281,7 @@ function writeCorpusReadme(stats, baseDir) {
     "## Contents",
     "",
     "- `core/` -- source and package files for `@agent-native/core`.",
+    "- `toolkit/` -- source and package files for `@agent-native/toolkit`.",
     "- `templates/` -- source-only copies of first-party Agent Native templates.",
     "",
     "Runtime data, local env files, dependency folders, caches, tests, and build",
@@ -302,6 +303,7 @@ function writeCorpusReadme(stats, baseDir) {
     "## Generated Counts",
     "",
     `- core files: ${stats.coreFiles}`,
+    `- toolkit files: ${stats.toolkitFiles}`,
     `- template files: ${stats.templateFiles}`,
     "",
   ];
@@ -372,10 +374,15 @@ export function materializeSourceCorpus() {
   mkdirSync(tempDir, { recursive: true });
 
   const coreStats = copySourceFiles("packages/core", "core", tempDir);
+  const toolkitStats = copySourceFiles("packages/toolkit", "toolkit", tempDir);
   const templateStats = copySourceFiles("templates", "templates", tempDir);
 
   writeCorpusReadme(
-    { coreFiles: coreStats.files, templateFiles: templateStats.files },
+    {
+      coreFiles: coreStats.files,
+      toolkitFiles: toolkitStats.files,
+      templateFiles: templateStats.files,
+    },
     tempDir,
   );
 
@@ -386,7 +393,7 @@ export function materializeSourceCorpus() {
     ? ""
     : " (accepted a concurrent run's equivalent corpus)";
   console.log(
-    `[agent-native] Materialized source corpus at ${size} (${coreStats.files} core files, ${templateStats.files} template files).${note}`,
+    `[agent-native] Materialized source corpus at ${size} (${coreStats.files} core files, ${toolkitStats.files} toolkit files, ${templateStats.files} template files).${note}`,
   );
 }
 

package/corpus/core/src/cli/atomic-json-file.ts

@@ -0,0 +1,324 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const LOCK_WAIT_MS = 10_000;
+const STALE_LOCK_MS = 30_000;
+const lockWaiter = new Int32Array(new SharedArrayBuffer(4));
+
+export interface FileLockOptions {
+  lockWaitMs?: number;
+  staleLockMs?: number;
+  /**
+   * Durable writers wait long enough to reclaim a fresh dead owner. Hot paths
+   * may opt out and handle a short best-effort timeout themselves.
+   */
+  reclaimFreshDeadOwner?: boolean;
+}
+
+export interface AtomicJsonLineOptions {
+  mode?: number;
+  lock?: FileLockOptions;
+}
+
+interface FileLockMetadata {
+  pid: number;
+  createdAt: number;
+  token: string;
+}
+
+export function withFileLockSync<T>(
+  filePath: string,
+  action: () => T,
+  options: FileLockOptions = {},
+): T {
+  const lockPath = `${filePath}.lock`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const owner = acquireFileLockSync(lockPath, options);
+  try {
+    return action();
+  } finally {
+    releaseFileLockSync(lockPath, owner);
+  }
+}
+
+export function writeJsonFileAtomically(
+  filePath: string,
+  value: unknown,
+  options?: { mode?: number },
+): void {
+  writeTextFileAtomically(
+    filePath,
+    `${JSON.stringify(value, null, 2)}\n`,
+    options,
+  );
+}
+
+export function writeTextFileAtomically(
+  filePath: string,
+  content: string,
+  options?: { mode?: number },
+): void {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true });
+  const temporaryPath = path.join(
+    directory,
+    `.${path.basename(filePath)}.tmp-${process.pid}-${crypto.randomUUID()}`,
+  );
+  let mode = options?.mode;
+  if (mode === undefined) {
+    try {
+      mode = fs.statSync(filePath).mode & 0o777;
+    } catch {
+      // New files use the process umask.
+    }
+  }
+
+  try {
+    fs.writeFileSync(temporaryPath, content, {
+      encoding: "utf-8",
+      flag: "wx",
+      ...(mode === undefined ? {} : { mode }),
+    });
+    fs.renameSync(temporaryPath, filePath);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+export function updateJsonFileAtomically<T>(
+  filePath: string,
+  parse: (value: unknown) => T | null,
+  update: (current: T | null) => T | null,
+  options?: { lock?: FileLockOptions },
+): T | null {
+  return withFileLockSync(
+    filePath,
+    () => {
+      const current = readJsonFile(filePath, parse);
+      const next = update(current);
+      if (next !== null) writeJsonFileAtomically(filePath, next);
+      return next;
+    },
+    options?.lock,
+  );
+}
+
+export function appendUniqueJsonLineAtomically<T extends { id: string }>(
+  filePath: string,
+  value: T,
+  parse: (value: unknown) => T | null,
+  options?: AtomicJsonLineOptions,
+): { value: T; appended: boolean } {
+  return withFileLockSync(
+    filePath,
+    () => {
+      if (fs.existsSync(filePath)) {
+        for (const line of fs.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
+          if (!line) continue;
+          try {
+            const existing = parse(JSON.parse(line) as unknown);
+            if (existing?.id === value.id) {
+              return { value: existing, appended: false };
+            }
+          } catch {
+            // Ignore malformed legacy lines; valid events remain append-only.
+          }
+        }
+      }
+      fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`, {
+        encoding: "utf-8",
+        ...(options?.mode === undefined ? {} : { mode: options.mode }),
+      });
+      return { value, appended: true };
+    },
+    options?.lock,
+  );
+}
+
+function readJsonFile<T>(
+  filePath: string,
+  parse: (value: unknown) => T | null,
+): T | null {
+  try {
+    return parse(JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown);
+  } catch {
+    return null;
+  }
+}
+
+function acquireFileLockSync(
+  lockPath: string,
+  options: FileLockOptions,
+): FileLockMetadata {
+  const startedAt = Date.now();
+  while (true) {
+    if (hasActiveReaper(lockPath, options)) {
+      waitForFileLock(lockPath, startedAt, options);
+      continue;
+    }
+    const metadata: FileLockMetadata = {
+      pid: process.pid,
+      createdAt: Date.now(),
+      token: crypto.randomUUID(),
+    };
+    let fd: number | undefined;
+    try {
+      fd = fs.openSync(lockPath, "wx", 0o600);
+      fs.writeFileSync(fd, JSON.stringify(metadata), "utf-8");
+      return metadata;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      recoverStaleFileLock(lockPath, options);
+      if (!fs.existsSync(lockPath)) continue;
+      waitForFileLock(lockPath, startedAt, options);
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  }
+}
+
+function recoverStaleFileLock(
+  lockPath: string,
+  options: FileLockOptions,
+): void {
+  const reaperPath = `${lockPath}.reaper`;
+  const reaper = tryAcquireFileLock(reaperPath);
+  if (!reaper) return;
+  try {
+    const stale = readFileLockMetadata(lockPath);
+    if (!isStaleDeadOwner(stale, options)) return;
+    const confirmed = readFileLockMetadata(lockPath);
+    if (!sameFileLock(stale, confirmed)) return;
+    releaseFileLockSync(lockPath, stale);
+  } finally {
+    releaseFileLockSync(reaperPath, reaper);
+  }
+}
+
+function hasActiveReaper(lockPath: string, options: FileLockOptions): boolean {
+  const reaperPath = `${lockPath}.reaper`;
+  const reaper = readFileLockMetadata(reaperPath);
+  if (!reaper) return false;
+  if (!isStaleDeadOwner(reaper, options)) return true;
+  releaseFileLockSync(reaperPath, reaper);
+  return false;
+}
+
+function tryAcquireFileLock(lockPath: string): FileLockMetadata | null {
+  const metadata: FileLockMetadata = {
+    pid: process.pid,
+    createdAt: Date.now(),
+    token: crypto.randomUUID(),
+  };
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(lockPath, "wx", 0o600);
+    fs.writeFileSync(fd, JSON.stringify(metadata), "utf-8");
+    return metadata;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return null;
+    throw error;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function releaseFileLockSync(lockPath: string, owner: FileLockMetadata): void {
+  if (!sameFileLock(owner, readFileLockMetadata(lockPath))) return;
+  try {
+    fs.rmSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+function readFileLockMetadata(lockPath: string): FileLockMetadata | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, "utf-8")) as unknown;
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      typeof (parsed as FileLockMetadata).pid === "number" &&
+      typeof (parsed as FileLockMetadata).createdAt === "number" &&
+      typeof (parsed as FileLockMetadata).token === "string"
+    ) {
+      return parsed as FileLockMetadata;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function sameFileLock(
+  left: FileLockMetadata | null,
+  right: FileLockMetadata | null,
+): boolean {
+  return Boolean(
+    left &&
+    right &&
+    left.pid === right.pid &&
+    left.createdAt === right.createdAt &&
+    left.token === right.token,
+  );
+}
+
+function isStaleDeadOwner(
+  metadata: FileLockMetadata | null,
+  options: FileLockOptions,
+): metadata is FileLockMetadata {
+  return (
+    metadata !== null &&
+    Date.now() - metadata.createdAt >= staleLockMs(options) &&
+    !isProcessAlive(metadata.pid)
+  );
+}
+
+function waitForFileLock(
+  lockPath: string,
+  startedAt: number,
+  options: FileLockOptions,
+): void {
+  if (
+    Date.now() - startedAt >=
+    lockWaitBudgetMs(lockPath, startedAt, options)
+  ) {
+    throw new Error(`Timed out waiting for local store lock: ${lockPath}`);
+  }
+  Atomics.wait(lockWaiter, 0, 0, 8 + Math.floor(Math.random() * 8));
+}
+
+function lockWaitBudgetMs(
+  lockPath: string,
+  startedAt: number,
+  options: FileLockOptions,
+): number {
+  const configured = options.lockWaitMs ?? LOCK_WAIT_MS;
+  if (options.reclaimFreshDeadOwner === false) return configured;
+  const owner = readFileLockMetadata(lockPath);
+  if (!owner || isProcessAlive(owner.pid)) return configured;
+  const remainingUntilStale = Math.max(
+    0,
+    staleLockMs(options) - (Date.now() - owner.createdAt),
+  );
+  return Math.max(
+    configured,
+    Date.now() - startedAt + remainingUntilStale + 32,
+  );
+}
+
+function staleLockMs(options: FileLockOptions): number {
+  return options.staleLockMs ?? STALE_LOCK_MS;
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}