@sayknow-cli/natives 0.4.6 → 0.5.0

package/native/index.d.ts

@@ -1,5 +1,12 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * macOS computer-use controller.
+ *
+ * This declaration and the named JS export are available on every platform so
+ * consumers can import them portably; the native controller itself is built
+ * only on macOS.
+ */
 export declare class ComputerController {
   constructor()
   screenshot(): ComputerScreenshot
@@ -120,7 +127,7 @@ export declare class NotificationServer {
    * Create a server for `session_id` authenticated by `token`.
    *
    * `state_root` (when given) is where the endpoint discovery file is written
-   * (e.g. `<repo>/.gjc/state`). `resolver_available` defaults to `true`.
+   * (e.g. `<repo>/.skc/state`). `resolver_available` defaults to `true`.
    */
   constructor(sessionId: string, token: string, stateRoot?: string | undefined | null, resolverAvailable?: boolean | undefined | null)
   /** Register the reply callback. Must be called before [`Self::start`]. */
@@ -201,6 +208,11 @@ export declare class NotificationServer {
    * Fails if not started or `frame_json` is not a valid `ServerMessage`.
    */
   pushFrame(frameJson: string): void
+  /**
+   * Deliver a frame through every authenticated connection and wait for each
+   * socket writer to settle within `timeout_ms`.
+   */
+  pushFrameAndWait(frameJson: string, timeoutMs: number): Promise<boolean>
   /**
    * Broadcast a TypeScript-constructed turn frame without re-parsing JSON.
    * External frames must continue through [`Self::push_frame`] for serde
@@ -300,6 +312,15 @@ export declare class Process {
   get ppid(): number | null
   /** Launch arguments for this process. */
   args(): Array<string>
+  /**
+   * Send `signal` only to this pinned process reference.
+   *
+   * On Linux this uses the owned pidfd; on Windows it uses the owned process
+   * handle. It deliberately never discovers descendants or signals a process
+   * group. Returns `false` when the pinned process has already exited or the
+   * operating system rejects delivery.
+   */
+  signalRoot(signal: number): boolean
   /**
    * Send `signal` to this process and its descendants, children first.
    *
@@ -377,7 +398,7 @@ export declare class RecoveryFsRoot {
    */
   appendManaged(relativePath: string, data: Uint8Array, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
   /** Remove one exact managed regular file through retained authority. */
-  removeManaged(relativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  removeManaged(relativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsRetainedCleanupResult
   /**
    * Create each absent directory component beneath the retained root with
    * owner-only security. Existing components are re-opened no-follow.
@@ -388,22 +409,22 @@ export declare class RecoveryFsRoot {
    * retained root. The source identity is rechecked after the no-replace
    * rename, and the move is rolled back on a mismatch.
    */
-  renameManagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  renameManagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsPublishResult
   /** Snapshot a managed directory tree entirely through the retained root. */
   snapshotManagedTree(relativePath: string): NativeDirectoryTreeResult
   /**
    * Move an exact managed directory tree to an absent name through retained
    * authority.
    */
-  renameManagedTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  renameManagedTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsPublishResult
   /** Remove an exact managed directory tree through retained authority. */
-  removeManagedTree(relativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  removeManagedTree(relativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsRetainedCleanupResult
   /**
    * Atomically install an already-created regular file at an absent name.
    * Both names remain relative to this retained root and are never resolved
    * through a pathname after their parent descriptors are acquired.
    */
-  install(sourceRelativePath: string, destinationRelativePath: string): RecoveryFsResult
+  install(sourceRelativePath: string, destinationRelativePath: string): RecoveryFsPublishResult
   /**
    * Synchronize the retained root directory, making a preceding create or
    * install durable when the filesystem supports directory fsync.
@@ -443,6 +464,15 @@ export declare class Shell {
   abort(): Promise<void>
 }
 
+/**
+ * Publish-result wire-contract sentinel.
+ *
+ * The loader requires this in addition to the release sentinel, so a
+ * same-version modern artifact built before the retained-publish contract
+ * cannot be selected over a compatible baseline.
+ */
+export declare function __piNativesPublishOutcomeV1(): void
+
 /**
  * Version sentinel — exists solely so the JS loader can prove at load time
  * that the `.node` file on disk is from the same package release as the
@@ -461,7 +491,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_4_6(): void
+export declare function __piNativesV0_5_0(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -1711,6 +1741,18 @@ export interface NativeExactUnlinkResult {
   retainedUnknownPath?: string
 }
 
+/** Dedicated result for an atomic no-replace namespace publication. */
+export interface NativeNoReplaceResult {
+  ok: boolean
+  code?: string
+  mutationState: string
+  durabilityState: string
+  reason: string
+  primitive: string
+  phase: string
+  diagnostic: NativePublishDiagnostic
+}
+
 /** Result of applying or checking owner-only path security. */
 export type NativeOwnerOnlySecurityResult =
 	| {
@@ -1856,6 +1898,8 @@ export interface PresentationLease {
   registrationEpoch: number
 }
 
+export declare function probeWindowsJobMemory(): WindowsJobMemoryProbeResult
+
 /** Current state of a process reference. */
 export declare enum ProcessStatus {
   /** The referenced process is still running. */
@@ -1941,6 +1985,38 @@ export interface RecoveryFsIdentity {
   sha256?: string
 }
 
+/** Bounded, path-free diagnostic evidence for one retained publication. */
+export interface RecoveryFsPublishDiagnostic {
+  schemaVersion: number
+  collectionState: string
+  osCode?: number
+  syncFailures?: Array<RecoveryFsPublishSyncFailure>
+}
+
+/**
+ * Explicit mutation and durability outcome for retained no-replace
+ * publication.
+ */
+export interface RecoveryFsPublishResult {
+  ok: boolean
+  code?: string
+  identity?: RecoveryFsIdentity
+  mutationState: string
+  durabilityState: string
+  reason: string
+  primitive: string
+  phase: string
+  diagnostic: RecoveryFsPublishDiagnostic
+}
+
+/** Bounded, path-free diagnostic evidence for one retained publication. */
+export interface RecoveryFsPublishSyncFailure {
+  phase: string
+  parentRole: string
+  osCode?: number
+  kind: string
+}
+
 export interface RecoveryFsResult {
   ok: boolean
   code?: string
@@ -1948,7 +2024,28 @@ export interface RecoveryFsResult {
   data?: Uint8Array
 }
 
-export declare function renameNoReplacePath(sourcePath: string, destinationPath: string): NativeExactUnlinkResult
+/**
+ * Fail-closed outcome for a removal whose detached object remains retained.
+ * `recovery_path` identifies evidence only; it grants no authority to replay
+ * or delete the retained object.
+ */
+export interface RecoveryFsRetainedCleanupResult {
+  ok: boolean
+  code?: string
+  recoveryPath?: string
+  identity?: RecoveryFsIdentity
+  treeSnapshot?: NativeDirectoryTreeSnapshot
+}
+
+export declare function renameNoReplacePath(sourcePath: string, destinationPath: string): NativeNoReplaceResult
+
+/**
+ * Repair an owner-only ACL on a retained expected path.
+ *
+ * Its no-follow handle must still identify the expected object before repair
+ * and again after final ACL verification.
+ */
+export declare function repairOwnerOnlyPathSecurityExpected(path: string, kind: "directory" | "file", expectedDev: bigint, expectedIno: bigint): NativeOwnerOnlySecurityResult
 
 /** A client reply forwarded to the TypeScript host for gate resolution. */
 export interface ReplyEvent {
@@ -2178,6 +2275,12 @@ export declare function verifyOwnerOnlyFdSecurity(path: string, kind: "directory
 
 export declare function verifyOwnerOnlyPathSecurity(path: string, kind: "directory" | "file"): NativeOwnerOnlySecurityResult
 
+/**
+ * Verify owner-only ACL security without mutation only when the retained
+ * no-follow handle identifies the expected object before and after inspection.
+ */
+export declare function verifyOwnerOnlyPathSecurityExpected(path: string, kind: "directory" | "file", expectedDev: bigint, expectedIno: bigint): NativeOwnerOnlySecurityResult
+
 /**
  * Calculate visible width of text, excluding ANSI escape sequences.
  *
@@ -2188,6 +2291,21 @@ export declare function visibleWidth(text: string, tabWidth: number): number
 /** Calculate visible widths of many strings, excluding ANSI escape sequences. */
 export declare function visibleWidths(lines: Array<string>, tabWidth: number): Array<number>
 
+export interface WindowsJobMemoryProbeResult {
+  kind: string
+  platform: string
+  isInJob?: boolean
+  jobMemoryLimitBytes?: string
+  jobMemoryUsedBytes?: string
+  peakJobMemoryUsedBytes?: string
+  processMemoryLimitBytes?: string
+  processPrivateUsageBytes?: string
+  processWorkingSetBytes?: string
+  peakProcessWorkingSetBytes?: string
+  call?: string
+  code?: string
+}
+
 /** Profiling results returned to JavaScript. */
 export interface WorkProfile {
   /** Folded stack format for flamegraph tools. */
@@ -2209,3 +2327,19 @@ export interface WorkProfile {
  * Returns UTF-16 lines with active SGR codes carried across line boundaries.
  */
 export declare function wrapTextWithAnsi(text: string, width: number, tabWidth: number): Array<string>
+
+/** Bounded, path-free evidence for a parent-directory durability failure. */
+export interface NativePublishSyncFailure {
+  phase: string
+  parentRole: string
+  osCode: number
+  kind: string
+}
+
+/** Bounded, path-free evidence for one atomic publication. */
+export interface NativePublishDiagnostic {
+  schemaVersion: number
+  collectionState: string
+  osCode?: number
+  syncFailures?: Array<NativePublishSyncFailure>
+}

package/native/index.js

@@ -29,7 +29,8 @@ export const RecoveryFsRoot = nativeBindings.RecoveryFsRoot;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV0_4_6 = nativeBindings.__piNativesV0_4_6;
+export const __piNativesPublishOutcomeV1 = nativeBindings.__piNativesPublishOutcomeV1;
+export const __piNativesV0_5_0 = nativeBindings.__piNativesV0_5_0;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const applyOwnerOnlyFdSecurity = nativeBindings.applyOwnerOnlyFdSecurity;
 export const applyOwnerOnlyPathSecurity = nativeBindings.applyOwnerOnlyPathSecurity;
@@ -74,9 +75,11 @@ export const nativeBuildInfo = nativeBindings.nativeBuildInfo;
 export const openRecoveryFsRoot = nativeBindings.openRecoveryFsRoot;
 export const parseKey = nativeBindings.parseKey;
 export const parseKittySequence = nativeBindings.parseKittySequence;
+export const probeWindowsJobMemory = nativeBindings.probeWindowsJobMemory;
 export const ptyTimeoutCount = nativeBindings.ptyTimeoutCount;
 export const readImageFromClipboard = nativeBindings.readImageFromClipboard;
 export const renameNoReplacePath = nativeBindings.renameNoReplacePath;
+export const repairOwnerOnlyPathSecurityExpected = nativeBindings.repairOwnerOnlyPathSecurityExpected;
 export const retainBrokerPublication = nativeBindings.retainBrokerPublication;
 export const search = nativeBindings.search;
 export const sliceWithWidth = nativeBindings.sliceWithWidth;
@@ -87,6 +90,7 @@ export const truncateLinesToWidth = nativeBindings.truncateLinesToWidth;
 export const truncateToWidth = nativeBindings.truncateToWidth;
 export const verifyOwnerOnlyFdSecurity = nativeBindings.verifyOwnerOnlyFdSecurity;
 export const verifyOwnerOnlyPathSecurity = nativeBindings.verifyOwnerOnlyPathSecurity;
+export const verifyOwnerOnlyPathSecurityExpected = nativeBindings.verifyOwnerOnlyPathSecurityExpected;
 export const visibleWidth = nativeBindings.visibleWidth;
 export const visibleWidths = nativeBindings.visibleWidths;
 export const wrapTextWithAnsi = nativeBindings.wrapTextWithAnsi;

package/native/loader-state.d.ts

@@ -26,6 +26,15 @@ export interface GetAddonFilenamesInput {
 
 export function getAddonFilenames(input: GetAddonFilenamesInput): string[];
 
+export function getOptionalPackageNames(platformTag: string): string[];
+
+export interface ResolveOptionalPackageNativeDirsInput {
+	packageNames: string[];
+	requireResolve: (id: string) => string;
+}
+
+export function resolveOptionalPackageNativeDirs(input: ResolveOptionalPackageNativeDirsInput): string[];
+
 export interface ShouldStageNodeModulesAddonInput {
 	platform: NodeJS.Platform | string;
 	isCompiledBinary: boolean;
@@ -38,8 +47,9 @@ export interface ResolveLoaderCandidatesInput {
 	addonFilenames: string[];
 	isCompiledBinary: boolean;
 	stageFromNodeModules?: boolean;
+	isWorkspaceLoad?: boolean;
+	optionalPackageNativeDirs?: string[];
 	nativeDir: string;
-	platformNativeDir?: string | null;
 	execDir: string;
 	versionedDir: string;
 	userDataDir: string;
@@ -47,4 +57,56 @@ export interface ResolveLoaderCandidatesInput {
 
 export function resolveLoaderCandidates(input: ResolveLoaderCandidatesInput): string[];
 
-export function loadNative(): Record<string, unknown>;
+export interface LoadFromCandidatesInput<T> {
+	candidates: string[];
+	requireCandidate: (candidate: string) => T;
+	validateCandidate: (bindings: T, candidate: string) => void;
+	describeCandidate: (candidate: string) => string;
+}
+
+export interface LoadFromCandidatesResult<T> {
+	bindings: T | null;
+	errors: string[];
+}
+
+export function loadFromCandidates<T>(input: LoadFromCandidatesInput<T>): LoadFromCandidatesResult<T>;
+
+export interface CachedEmbeddedExtractionIsFreshInput {
+	targetPath: string;
+	embeddedPath: string;
+	sizeOf: (path: string) => number | null;
+}
+
+export function cachedEmbeddedExtractionIsFresh(input: CachedEmbeddedExtractionIsFreshInput): boolean;
+
+export function validateLoadedBindings(
+	ctx: { versionSentinelExport: string; packageVersion: string },
+	bindings: Record<string, unknown>,
+	candidate: string,
+): void;
+
+export interface LoaderContext {
+	isCompiledBinary: boolean;
+	platformTag: string;
+	packageVersion?: string;
+	addonLabel?: string;
+	addonFilenames?: string[];
+	versionedDir?: string;
+	candidates?: string[];
+	selectedVariant?: "modern" | "baseline" | null;
+}
+
+export function embeddedAddonIsAuthoritative(
+	ctx: LoaderContext,
+	addon?: EmbeddedAddon | null,
+): boolean;
+
+export interface LoadNativeOptions {
+	context?: LoaderContext;
+	extractEmbeddedAddons?: (ctx: LoaderContext) => string[];
+	stageNodeModulesAddon?: () => string | null;
+	requireCandidate?: (candidate: string) => Record<string, unknown>;
+	validateCandidate?: (bindings: Record<string, unknown>) => void;
+}
+
+export function loadNative(options?: LoadNativeOptions): Record<string, unknown>;

package/native/loader-state.js

@@ -31,6 +31,14 @@ import { embeddedAddon } from "./embedded-addon.js";
  */
 
 const SUPPORTED_PLATFORMS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"];
+const OPTIONAL_PACKAGE_BY_PLATFORM_TAG = {
+	"darwin-arm64": "@sayknow-cli/natives-darwin-arm64",
+	"darwin-x64": "@sayknow-cli/natives-darwin-x64",
+	"linux-arm64": "@sayknow-cli/natives-linux-arm64",
+	"linux-x64": "@sayknow-cli/natives-linux-x64",
+	"win32-x64": "@sayknow-cli/natives-win32-x64",
+};
+
 
 function getNativesDir() {
 	const xdgDataHome = process.env.XDG_DATA_HOME;
@@ -78,6 +86,32 @@ export function getAddonFilenames({ tag, arch, variant }) {
 	return [baselineFilename, defaultFilename];
 }
 
+/**
+ * @param {string} platformTag
+ * @returns {string[]}
+ */
+export function getOptionalPackageNames(platformTag) {
+	const packageName = OPTIONAL_PACKAGE_BY_PLATFORM_TAG[platformTag];
+	return packageName ? [packageName] : [];
+}
+
+/**
+ * @param {{ packageNames: string[]; requireResolve: (id: string) => string }} input
+ * @returns {string[]}
+ */
+export function resolveOptionalPackageNativeDirs({ packageNames, requireResolve }) {
+	const dirs = [];
+	for (const packageName of packageNames) {
+		try {
+			const manifestPath = requireResolve(`${packageName}/package.json`);
+			dirs.push(path.join(path.dirname(manifestPath), "native"));
+		} catch {
+			// Optional dependency is absent on non-matching platforms or older installs.
+		}
+	}
+	return dirs;
+}
+
 /**
  * Decide whether the loader should mirror the package's `native/<filename>.node`
  * into the per-version cache directory (`~/.skc/natives/<version>/`) before loading.
@@ -112,8 +146,9 @@ export function shouldStageNodeModulesAddon({ platform, isCompiledBinary, native
  *   addonFilenames: string[];
  *   isCompiledBinary: boolean;
  *   stageFromNodeModules?: boolean;
+ *   isWorkspaceLoad?: boolean;
+ *   optionalPackageNativeDirs?: string[];
  *   nativeDir: string;
- *   platformNativeDir?: string | null;
  *   execDir: string;
  *   versionedDir: string;
  *   userDataDir: string;
@@ -124,18 +159,25 @@ export function resolveLoaderCandidates({
 	addonFilenames,
 	isCompiledBinary,
 	stageFromNodeModules = false,
+	isWorkspaceLoad = false,
+	optionalPackageNativeDirs = [],
 	nativeDir,
-	platformNativeDir,
 	execDir,
 	versionedDir,
 	userDataDir,
 }) {
-	const nestedPlatformNativeDir = path.join(nativeDir, "..", "node_modules", "@sayknow-cli", `natives-${process.platform}-${process.arch}`, "native");
-	const sourceNativeDirs = [nativeDir, platformNativeDir, nestedPlatformNativeDir].filter(dir => typeof dir === "string" && dir.length > 0);
-	const baseReleaseCandidates = addonFilenames.flatMap(filename => [
-		...sourceNativeDirs.map(dir => path.join(dir, filename)),
+	const workspaceCandidates = addonFilenames.map(filename => path.join(nativeDir, filename));
+	const optionalPackageCandidates = optionalPackageNativeDirs.flatMap(optionalNativeDir =>
+		addonFilenames.map(filename => path.join(optionalNativeDir, filename)),
+	);
+	const legacyReleaseCandidates = addonFilenames.flatMap(filename => [
+		path.join(nativeDir, filename),
 		path.join(execDir, filename),
 	]);
+	const legacyExecCandidates = addonFilenames.map(filename => path.join(execDir, filename));
+	const baseReleaseCandidates = isWorkspaceLoad
+		? [...workspaceCandidates, ...optionalPackageCandidates, ...legacyExecCandidates]
+		: [...optionalPackageCandidates, ...legacyReleaseCandidates];
 	const compiledCandidates = addonFilenames.flatMap(filename => [
 		path.join(versionedDir, filename),
 		path.join(userDataDir, filename),
@@ -152,6 +194,52 @@ export function resolveLoaderCandidates({
 	return [...new Set(releaseCandidates)];
 }
 
+/**
+ * Deterministically try candidate paths in order using injected operations.
+ * This leaves file loading and compatibility policy at the call site while
+ * making fallback behavior testable without a native addon on disk.
+ *
+ * @template T
+ * @param {{
+ *   candidates: string[];
+ *   requireCandidate: (candidate: string) => T;
+ *   validateCandidate: (bindings: T, candidate: string) => void;
+ *   describeCandidate: (candidate: string) => string;
+ * }} input
+ * @returns {{ bindings: T | null; errors: string[] }}
+ */
+export function loadFromCandidates({ candidates, requireCandidate, validateCandidate, describeCandidate }) {
+	const errors = [];
+	for (const candidate of candidates) {
+		try {
+			const bindings = requireCandidate(candidate);
+			validateCandidate(bindings, candidate);
+			return { bindings, errors };
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			errors.push(`${describeCandidate(candidate)}: ${message}`);
+		}
+	}
+	return { bindings: null, errors };
+}
+
+/**
+ * Decide whether a previously extracted embedded addon may be reused. A cached
+ * extraction from an earlier build of the same version carries the same version
+ * sentinel yet can expose a different native surface, so it is fresh only when
+ * its byte size matches the embedded payload. `sizeOf` returns the byte size of
+ * a path, or `null` when it cannot be inspected.
+ * @param {{ targetPath: string; embeddedPath: string; sizeOf: (path: string) => number | null }} input
+ * @returns {boolean}
+ */
+export function cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath, sizeOf }) {
+	const cachedSize = sizeOf(targetPath);
+	if (cachedSize === null) return false;
+	const embeddedSize = sizeOf(embeddedPath);
+	if (embeddedSize === null) return false;
+	return cachedSize === embeddedSize;
+}
+
 // =========================================================================
 // Side-effectful loader. Everything below runs only when `loadNative()` is
 // called from `native/index.js` — tests that only import the pure helpers
@@ -218,70 +306,79 @@ function resolveCpuVariant(override) {
 	return detectAvx2Support() ? "modern" : "baseline";
 }
 
-function selectEmbeddedAddonFile(selectedVariant) {
-	if (!embeddedAddon) return null;
-	const defaultFile = embeddedAddon.files.find(file => file.variant === "default") || null;
-	if (process.arch !== "x64") return defaultFile || embeddedAddon.files[0] || null;
-	if (selectedVariant === "modern") {
-		return (
-			embeddedAddon.files.find(file => file.variant === "modern") ||
-			embeddedAddon.files.find(file => file.variant === "baseline") ||
-			null
-		);
-	}
-	return embeddedAddon.files.find(file => file.variant === "baseline") || null;
+function embeddedAddonCandidates(selectedVariant) {
+	if (!embeddedAddon) return [];
+	const files = embeddedAddon.files;
+	const candidates = process.arch !== "x64"
+		? [files.find(file => file.variant === "default"), ...files]
+		: selectedVariant === "modern"
+			? [files.find(file => file.variant === "modern"), files.find(file => file.variant === "baseline")]
+			: [files.find(file => file.variant === "baseline")];
+	return [...new Set(candidates.filter(Boolean))];
 }
 
-function maybeExtractEmbeddedAddon(ctx, errors) {
-	if (!ctx.isCompiledBinary || !embeddedAddon) return null;
-	if (embeddedAddon.platformTag !== ctx.platformTag || embeddedAddon.version !== ctx.packageVersion) return null;
-
-	const selectedEmbeddedFile = selectEmbeddedAddonFile(ctx.selectedVariant);
-	if (!selectedEmbeddedFile) return null;
-	const targetPath = path.join(ctx.versionedDir, selectedEmbeddedFile.filename);
-	if (fs.existsSync(targetPath)) return targetPath;
+function maybeExtractEmbeddedAddons(ctx, errors) {
+	if (!ctx.isCompiledBinary || !embeddedAddon) return [];
+	if (embeddedAddon.platformTag !== ctx.platformTag || embeddedAddon.version !== ctx.packageVersion) return [];
 
-	try {
-		fs.mkdirSync(ctx.versionedDir, { recursive: true });
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		errors.push(`embedded addon dir: ${message}`);
-		return null;
-	}
+	const extracted = [];
+	for (const embeddedFile of embeddedAddonCandidates(ctx.selectedVariant)) {
+		const targetPath = path.join(ctx.versionedDir, embeddedFile.filename);
+		if (fs.existsSync(targetPath)) {
+			// Guard against intra-version drift: a cached extraction written by an earlier
+			// build of the same version carries the same version sentinel but can expose a
+			// different native surface (e.g. a symbol added mid-cycle). The embedded addon
+			// is the source of truth, so reuse the cached file only when it matches the
+			// embedded payload size and re-extract otherwise.
+			const sizeOf = candidate => {
+				try {
+					return fs.statSync(candidate).size;
+				} catch {
+					return null;
+				}
+			};
+			if (cachedEmbeddedExtractionIsFresh({ targetPath, embeddedPath: embeddedFile.filePath, sizeOf })) {
+				extracted.push(targetPath);
+				continue;
+			}
+		}
 
-	try {
-		const buffer = fs.readFileSync(selectedEmbeddedFile.filePath);
-		const tempPath = `${targetPath}.tmp.${process.pid}`;
-		fs.writeFileSync(tempPath, buffer);
-		fs.renameSync(tempPath, targetPath);
-		return targetPath;
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		errors.push(`embedded addon write (${selectedEmbeddedFile.filename}): ${message}`);
-		return null;
+		try {
+			fs.mkdirSync(ctx.versionedDir, { recursive: true });
+			const buffer = fs.readFileSync(embeddedFile.filePath);
+			const tempPath = `${targetPath}.tmp.${process.pid}`;
+			fs.writeFileSync(tempPath, buffer);
+			fs.renameSync(tempPath, targetPath);
+			extracted.push(targetPath);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			errors.push(`embedded addon write (${embeddedFile.filename}): ${message}`);
+		}
 	}
+	return extracted;
 }
 
 /**
- * Mirror `nativeDir/<filename>.node` to `versionedDir/<filename>.node` on Windows
- * installs so the running process keeps its OS-level handle on a versioned
- * cache path, never on the `node_modules` copy that bun must overwrite on
- * update. No-op on non-Windows, in workspace dev, and for compiled binaries —
- * see `shouldStageNodeModulesAddon` for the gating rules.
+ * Mirror the optional-package or legacy bundled `native/<filename>.node` into
+ * `versionedDir/<filename>.node` on Windows installs so the running process
+ * keeps its OS-level handle on a versioned cache path, never on the
+ * `node_modules` copy that bun must overwrite on update. No-op on non-Windows,
+ * in workspace dev, and for compiled binaries — see `shouldStageNodeModulesAddon`.
  */
 function maybeStageNodeModulesAddon(ctx, errors) {
 	if (!ctx.stageFromNodeModules) return null;
 
 	let stagedPath = null;
+	const sourceDirs = [...ctx.optionalPackageNativeDirs, ctx.nativeDir];
 	for (const filename of ctx.addonFilenames) {
-		const sourcePath = path.join(ctx.nativeDir, filename);
 		const targetPath = path.join(ctx.versionedDir, filename);
 
 		if (fs.existsSync(targetPath)) {
 			stagedPath = stagedPath || targetPath;
 			continue;
 		}
-		if (!fs.existsSync(sourcePath)) continue;
+		const sourcePath = sourceDirs.map(sourceDir => path.join(sourceDir, filename)).find(candidate => fs.existsSync(candidate));
+		if (!sourcePath) continue;
 
 		try {
 			fs.mkdirSync(ctx.versionedDir, { recursive: true });
@@ -304,19 +401,26 @@ function maybeStageNodeModulesAddon(ctx, errors) {
 	return stagedPath;
 }
 
-function validateLoadedBindings(ctx, bindings, candidate) {
-	// In workspace dev (running out of `packages/natives/native/` rather than a
-	// `node_modules` install or a compiled bundle) the local `.node` only gains
-	// the renamed sentinel after `bun --cwd=packages/natives run build`. Skip
-	// validation there so a stale post-pull dev tree boots while the rebuild
-	// completes; install and compiled-binary paths still validate.
-	if (ctx.isWorkspaceLoad) return;
-	if (typeof bindings[ctx.versionSentinelExport] === "function") return;
-	throw new Error(
-		`Loaded ${candidate} but it does not expose the @sayknow-cli/natives@${ctx.packageVersion} ` +
-			`version sentinel \`${ctx.versionSentinelExport}\`. The .node file on disk is from a different ` +
-			"release than this loader — reinstall to re-sync.",
-	);
+export function validateLoadedBindings(ctx, bindings, candidate) {
+	if (typeof bindings[ctx.versionSentinelExport] !== "function") {
+		throw new Error(
+			`Loaded ${candidate} but it does not expose the @sayknow-cli/natives@${ctx.packageVersion} ` +
+				`version sentinel \`${ctx.versionSentinelExport}\`. The .node file on disk is from a different ` +
+				"release than this loader — reinstall to re-sync.",
+		);
+	}
+	if (typeof bindings.__piNativesPublishOutcomeV1 !== "function") {
+		throw new Error(
+			`Loaded ${candidate} but it lacks retained-publish capability sentinel ` +
+			"`__piNativesPublishOutcomeV1`; trying the next compatible artifact.",
+		);
+	}
+	if (typeof bindings.renameNoReplacePath !== "function") {
+		throw new Error(`Loaded ${candidate} but it lacks required atomic publish capability \`renameNoReplacePath\`.`);
+	}
+	if (typeof bindings.probeWindowsJobMemory !== "function") {
+		throw new Error(`Loaded ${candidate} but it lacks required memory probe capability \`probeWindowsJobMemory\`.`);
+	}
 }
 
 function buildHelpMessage(ctx) {
@@ -347,11 +451,10 @@ function buildHelpMessage(ctx) {
  * Called from `loadNative()` rather than at module scope so importing pure
  * helpers from this file doesn't trigger AVX2 detection or filesystem probes.
  */
-function initLoaderContext() {
+function initLoaderContext(require_) {
 	const platformTag = `${process.platform}-${process.arch}`;
 	const packageVersion = packageJson.version;
 	const nativeDir = path.join(import.meta.dir, "..", "native");
-	const platformNativeDir = path.join(nativeDir, "..", "..", `natives-${platformTag}`, "native");
 	const execDir = path.dirname(process.execPath);
 	const versionedDir = path.join(getNativesDir(), packageVersion);
 	const userDataDir =
@@ -369,17 +472,25 @@ function initLoaderContext() {
 		isCompiledBinary,
 		nativeDir,
 	});
+	const isWorkspaceLoad =
+		!isCompiledBinary && !nativeDir.includes("\\node_modules\\") && !nativeDir.includes("/node_modules/");
 
 	const selectedVariant = resolveCpuVariant(getVariantOverride());
 	const addonFilenames = getAddonFilenames({ tag: platformTag, arch: process.arch, variant: selectedVariant });
 	const addonLabel = selectedVariant ? `${platformTag} (${selectedVariant})` : platformTag;
+	const optionalPackageNativeDirs = resolveOptionalPackageNativeDirs({
+		packageNames: getOptionalPackageNames(platformTag),
+		requireResolve: id => require_.resolve(id),
+	});
+
 
 	const candidates = resolveLoaderCandidates({
 		addonFilenames,
 		isCompiledBinary,
 		stageFromNodeModules,
+		isWorkspaceLoad,
+		optionalPackageNativeDirs,
 		nativeDir,
-		platformNativeDir,
 		execDir,
 		versionedDir,
 		userDataDir,
@@ -393,8 +504,6 @@ function initLoaderContext() {
 	// turns the silent `<sym> is not a function` crash from a Windows
 	// locked-file update into an actionable load-time error.
 	const versionSentinelExport = `__piNativesV${packageVersion.replace(/[^A-Za-z0-9]/g, "_")}`;
-	const isWorkspaceLoad =
-		!isCompiledBinary && !nativeDir.includes("\\node_modules\\") && !nativeDir.includes("/node_modules/");
 
 	return {
 		platformTag,
@@ -405,33 +514,41 @@ function initLoaderContext() {
 		stageFromNodeModules,
 		selectedVariant,
 		addonFilenames,
+		optionalPackageNativeDirs,
 		addonLabel,
 		candidates,
 		versionSentinelExport,
-		isWorkspaceLoad,
 	};
 }
 
-export function loadNative() {
-	const ctx = initLoaderContext();
-	const require_ = createRequire(import.meta.url);
+/** Embedded standalone payloads are the complete trust boundary for their matching build. */
+export function embeddedAddonIsAuthoritative(ctx, addon = embeddedAddon) {
+	return (
+		ctx.isCompiledBinary && addon?.platformTag === ctx.platformTag && addon.version === ctx.packageVersion
+	);
+}
 
-	const errors = [];
-	const embeddedCandidate = maybeExtractEmbeddedAddon(ctx, errors);
-	const stagedCandidate = embeddedCandidate ? null : maybeStageNodeModulesAddon(ctx, errors);
-	const prepended = [embeddedCandidate, stagedCandidate].filter(c => typeof c === "string");
-	const runtimeCandidates = prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
+export function loadNative(options = {}) {
+	const require_ = options.requireCandidate ? null : createRequire(import.meta.url);
+	const ctx = options.context ?? initLoaderContext(require_);
 
-	for (const candidate of runtimeCandidates) {
-		try {
-			const bindings = require_(candidate);
-			validateLoadedBindings(ctx, bindings, candidate);
-			return bindings;
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			errors.push(`${candidate}: ${message}`);
-		}
-	}
+	const errors = [];
+	const embeddedCandidates = (options.extractEmbeddedAddons ?? maybeExtractEmbeddedAddons)(ctx, errors);
+	const embeddedIsAuthoritative = embeddedAddonIsAuthoritative(ctx);
+	const stagedCandidate =
+		embeddedCandidates.length > 0 || embeddedIsAuthoritative
+			? null
+			: (options.stageNodeModulesAddon ?? maybeStageNodeModulesAddon)(ctx, errors);
+	const prepended = [...embeddedCandidates, stagedCandidate].filter(c => typeof c === "string");
+	const runtimeCandidates = embeddedIsAuthoritative ? prepended : prepended.length > 0 ? [...prepended, ...ctx.candidates] : ctx.candidates;
+	const loaded = loadFromCandidates({
+		candidates: runtimeCandidates,
+		requireCandidate: options.requireCandidate ?? (candidate => require_(candidate)),
+		validateCandidate: options.validateCandidate ?? ((bindings, candidate) => validateLoadedBindings(ctx, bindings, candidate)),
+		describeCandidate: candidate => candidate,
+	});
+	if (loaded.bindings) return loaded.bindings;
+	errors.push(...loaded.errors);
 
 	if (!SUPPORTED_PLATFORMS.includes(ctx.platformTag)) {
 		throw new Error(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sayknow-cli/natives",
-	"version": "0.4.6",
+	"version": "0.5.0",
 	"description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://sayknow-cli.com",
@@ -61,11 +61,11 @@
 		"README.md"
 	],
 	"optionalDependencies": {
-		"@sayknow-cli/natives-darwin-arm64": "0.4.6",
-		"@sayknow-cli/natives-darwin-x64": "0.4.6",
-		"@sayknow-cli/natives-linux-arm64": "0.4.6",
-		"@sayknow-cli/natives-linux-x64": "0.4.6",
-		"@sayknow-cli/natives-win32-x64": "0.4.6"
+		"@sayknow-cli/natives-darwin-arm64": "0.5.0",
+		"@sayknow-cli/natives-darwin-x64": "0.5.0",
+		"@sayknow-cli/natives-linux-arm64": "0.5.0",
+		"@sayknow-cli/natives-linux-x64": "0.5.0",
+		"@sayknow-cli/natives-win32-x64": "0.5.0"
 	},
 	"exports": {
 		".": {