@socketsecurity/lib 6.0.7 → 6.0.8

package/dist/paths/socket.d.ts

@@ -1,12 +1,13 @@
 /**
- * @file Path utilities for Socket ecosystem directories. Provides
- *   platform-aware path resolution for Socket tools' shared directory
- *   structure. Directory Structure: ~/.socket/ ├── _cacache/ #
- *   Content-addressable cache for npm packages ├── _dlx/ # DLX installations
- *   (content-addressed by hash) │ ├── <hash>/ # npm package installs
- *   (dlx-package) │ └── <hash>/ # binary downloads (dlx-binary) ├── _socket/ #
- *   Socket CLI app directory ├── _registry/ # Socket Registry app directory └──
- *   _sfw/ # Socket Firewall app directory.
+ * @file Path utilities for Socket ecosystem directories. Platform-aware
+ *   resolution for the shared ~/.socket/ layout. The `_`-prefixed entries are
+ *   Socket-managed DIRS (not apps): `_cacache` content-addressable cache;
+ *   `_dlx/<hash>/` name+version binary store (node, jre, python, sfw, …);
+ *   `_state/<app>/` version-LESS persistent app state (daemon socket + lock +
+ *   OAuth refresh; mirrors pnpm `state-dir` / XDG_STATE_HOME), with
+ *   `_state/<app>/run/` for a daemon's socket/lock/pid; `_wheelhouse`
+ *   cross-fleet shared bin. Generic per-app dirs (`getSocketAppDir('<name>')`)
+ *   nest under the same `_`-prefix.
  */
 /**
  * Get the OS home directory. Can be overridden in tests using
@@ -37,67 +38,56 @@ export declare function getSocketAppCacheDir(appName: string): string;
  */
 export declare function getSocketAppCacheTtlDir(appName: string): string;
 /**
- * Get a Socket app directory (~/.socket/_<appName>).
+ * Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+ * here; pass the bare app name (e.g. 'socket', 'registry').
  */
 /**
- * Get a Socket app directory (~/.socket/_<appName>).
+ * Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+ * here; pass the bare app name (e.g. 'socket', 'registry').
  */
 export declare function getSocketAppDir(appName: string): string;
 /**
- * Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
- * SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
- * is cached via getPathValue for performance.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-cacache-dir', ...)
- * 2. SOCKET_CACACHE_DIR - Full override of cacache directory
- * 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+ * Get the Socket cacache directory (~/.socket/_cacache). Override precedence:
+ * setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+ * $SOCKET_HOME/_cacache → $HOME/.socket/_cacache.
  */
 /**
- * Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
- * SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
- * is cached via getPathValue for performance.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-cacache-dir', ...)
- * 2. SOCKET_CACACHE_DIR - Full override of cacache directory
- * 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+ * Get an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+ * daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+ * the socket path is stable across binary upgrades.
  */
-export declare function getSocketCacacheDir(): string;
+export declare function getSocketAppRuntimeDir(appName: string): string;
 /**
- * Get the Socket CLI directory (~/.socket/_socket).
+ * Get the Socket user directory (~/.socket). Override precedence:
+ * setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+ * /tmp/.socket (Unix) or %TEMP%.socket (Windows).
  */
 /**
- * Get the Socket CLI directory (~/.socket/_socket).
+ * Get an app's persistent state directory (~/.socket/_state/<app>/). The
+ * `<app>` is a real app (proteus, acorn) nesting its version-less state inside
+ * the `_state` infra dir.
  */
-export declare function getSocketCliDir(): string;
+export declare function getSocketAppStateDir(appName: string): string;
 /**
- * Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
- * SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
- * cached via getPathValue for performance.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-dlx-dir', ...)
- * 2. SOCKET_DLX_DIR - Full override of DLX cache directory
- * 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
- * 4. Default: $HOME/.socket/_dlx
- * 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
+ * Get an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+ * daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+ * the socket path is stable across binary upgrades.
  */
 /**
- * Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
- * SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
- * cached via getPathValue for performance.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-dlx-dir', ...)
- * 2. SOCKET_DLX_DIR - Full override of DLX cache directory
- * 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
- * 4. Default: $HOME/.socket/_dlx
- * 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
+ * Get the Socket cacache directory (~/.socket/_cacache). Override precedence:
+ * setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+ * $SOCKET_HOME/_cacache → $HOME/.socket/_cacache.
+ */
+export declare function getSocketCacacheDir(): string;
+/**
+ * Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+ * (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+ * …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
+ */
+/**
+ * Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+ * (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+ * …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
  */
 export declare function getSocketDlxDir(): string;
 /**
@@ -110,56 +100,40 @@ export declare function getSocketDlxDir(): string;
  */
 export declare function getSocketHomePath(): string;
 /**
- * Get the Socket Registry directory (~/.socket/_registry).
+ * Get the Socket state directory (~/.socket/_state) — version-LESS persistent
+ * app state (the home for daemon sockets, locks, OAuth refresh, durable caches
+ * that survive version bumps; mirrors pnpm `state-dir` / XDG_STATE_HOME).
+ * Override precedence: setPath('socket-state-dir', …) → SOCKET_STATE_DIR env →
+ * $SOCKET_HOME/_state → $HOME/.socket/_state.
  */
 /**
- * Get the Socket Registry directory (~/.socket/_registry).
+ * Get the Socket state directory (~/.socket/_state) — version-LESS persistent
+ * app state (the home for daemon sockets, locks, OAuth refresh, durable caches
+ * that survive version bumps; mirrors pnpm `state-dir` / XDG_STATE_HOME).
+ * Override precedence: setPath('socket-state-dir', …) → SOCKET_STATE_DIR env →
+ * $SOCKET_HOME/_state → $HOME/.socket/_state.
  */
-export declare function getSocketRegistryDir(): string;
+export declare function getSocketStateDir(): string;
 /**
- * Get the Socket Registry GitHub cache directory
- * (~/.socket/_registry/cache/ttl/github).
+ * Get an app's persistent state directory (~/.socket/_state/<app>/). The
+ * `<app>` is a real app (proteus, acorn) nesting its version-less state inside
+ * the `_state` infra dir.
  */
 /**
- * Get the Socket Registry GitHub cache directory
- * (~/.socket/_registry/cache/ttl/github).
+ * Get the Socket user directory (~/.socket). Override precedence:
+ * setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+ * /tmp/.socket (Unix) or %TEMP%.socket (Windows).
  */
-export declare function getSocketRegistryGithubCacheDir(): string;
+export declare function getSocketUserDir(): string;
 /**
  * Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
  * cross-fleet location for binaries that every fleet member can reach without
  * each one re-downloading and re-extracting per-repo. Tool installers (janus,
  * sfw, etc.) drop their resolved executables under
  * `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
- * appropriate `bin/` to PATH or invoke the binary by absolute path.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-wheelhouse-dir', ...)
- * 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
- *    getSocketUserDir)
- * 3. Default: $HOME/.socket/_wheelhouse
- */
-/**
- * Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
- * environment variable or via setPath() for testing. Result is cached via
- * getPathValue for performance.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-user-dir', ...)
- * 2. SOCKET_HOME - Base directory override
- * 3. Default: $HOME/.socket
- * 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
- */
-export declare function getSocketUserDir(): string;
-/**
- * Get the user's home directory. Uses environment variables directly to support
- * test mocking. Falls back to temporary directory if home is not available.
- *
- * Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
- * environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
- * getNodeOs().tmpdir() (rarely used, for restricted environments)
+ * appropriate `bin/` to PATH or invoke the binary by absolute path. Override
+ * precedence: setPath('socket-wheelhouse-dir', …) → $SOCKET_HOME/_wheelhouse →
+ * $HOME/.socket/_wheelhouse.
  */
 /**
  * Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
@@ -167,34 +141,23 @@ export declare function getSocketUserDir(): string;
  * each one re-downloading and re-extracting per-repo. Tool installers (janus,
  * sfw, etc.) drop their resolved executables under
  * `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
- * appropriate `bin/` to PATH or invoke the binary by absolute path.
- *
- * Priority order:
- *
- * 1. Test override via setPath('socket-wheelhouse-dir', ...)
- * 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
- *    getSocketUserDir)
- * 3. Default: $HOME/.socket/_wheelhouse
+ * appropriate `bin/` to PATH or invoke the binary by absolute path. Override
+ * precedence: setPath('socket-wheelhouse-dir', …) → $SOCKET_HOME/_wheelhouse →
+ * $HOME/.socket/_wheelhouse.
  */
 export declare function getSocketWheelhouseDir(): string;
 /**
- * Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
- * environment variable or via setPath() for testing. Result is cached via
- * getPathValue for performance.
- *
- * Priority order:
+ * Get the user's home directory. Uses environment variables directly to support
+ * test mocking. Falls back to temporary directory if home is not available.
  *
- * 1. Test override via setPath('socket-user-dir', ...)
- * 2. SOCKET_HOME - Base directory override
- * 3. Default: $HOME/.socket
- * 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
+ * Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+ * getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
  */
 /**
  * Get the user's home directory. Uses environment variables directly to support
  * test mocking. Falls back to temporary directory if home is not available.
  *
- * Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
- * environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
- * getNodeOs().tmpdir() (rarely used, for restricted environments)
+ * Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+ * getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
  */
 export declare function getUserHomeDir(): string;

package/dist/paths/socket.js

@@ -2,33 +2,34 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_node_os = require('../node/os.js');
+const require_env_home = require('../env/home.js');
 const require_paths_normalize = require('./normalize.js');
 const require_node_path = require('../node/path.js');
 const require_env_socket = require('../env/socket.js');
-const require_constants_github = require('../constants/github.js');
 const require_constants_socket = require('../constants/socket.js');
-const require_env_home = require('../env/home.js');
 const require_env_windows = require('../env/windows.js');
 const require_paths_dirnames = require('./dirnames.js');
 const require_paths_rewire = require('./rewire.js');
 
 //#region src/paths/socket.ts
 /**
-* @file Path utilities for Socket ecosystem directories. Provides
-*   platform-aware path resolution for Socket tools' shared directory
-*   structure. Directory Structure: ~/.socket/ ├── _cacache/ #
-*   Content-addressable cache for npm packages ├── _dlx/ # DLX installations
-*   (content-addressed by hash) │ ├── <hash>/ # npm package installs
-*   (dlx-package) │ └── <hash>/ # binary downloads (dlx-binary) ├── _socket/ #
-*   Socket CLI app directory ├── _registry/ # Socket Registry app directory └──
-*   _sfw/ # Socket Firewall app directory.
+* @file Path utilities for Socket ecosystem directories. Platform-aware
+*   resolution for the shared ~/.socket/ layout. The `_`-prefixed entries are
+*   Socket-managed DIRS (not apps): `_cacache` content-addressable cache;
+*   `_dlx/<hash>/` name+version binary store (node, jre, python, sfw, …);
+*   `_state/<app>/` version-LESS persistent app state (daemon socket + lock +
+*   OAuth refresh; mirrors pnpm `state-dir` / XDG_STATE_HOME), with
+*   `_state/<app>/run/` for a daemon's socket/lock/pid; `_wheelhouse`
+*   cross-fleet shared bin. Generic per-app dirs (`getSocketAppDir('<name>')`)
+*   nest under the same `_`-prefix.
 */
 /**
 * Get the OS home directory. Can be overridden in tests using
 * setPath('homedir', ...) from paths/rewire.
 */
 function getOsHomeDir() {
-	return require_paths_rewire.getPathValue("homedir", () => require_node_os.getNodeOs().homedir());
+	const os = require_node_os.getNodeOs();
+	return require_paths_rewire.getPathValue("homedir", () => os.homedir());
 }
 /**
 * Get the OS temporary directory. Can be overridden in tests using
@@ -39,7 +40,8 @@ function getOsHomeDir() {
 * setPath('tmpdir', ...) from paths/rewire.
 */
 function getOsTmpDir() {
-	return require_paths_rewire.getPathValue("tmpdir", () => require_node_os.getNodeOs().tmpdir());
+	const os = require_node_os.getNodeOs();
+	return require_paths_rewire.getPathValue("tmpdir", () => os.tmpdir());
 }
 /**
 * Get a Socket app cache directory (~/.socket/_<appName>/cache).
@@ -60,81 +62,72 @@ function getSocketAppCacheTtlDir(appName) {
 	return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketAppCacheDir(appName), "ttl"));
 }
 /**
-* Get a Socket app directory (~/.socket/_<appName>).
+* Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+* here; pass the bare app name (e.g. 'socket', 'registry').
 */
 /**
-* Get a Socket app directory (~/.socket/_<appName>).
+* Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+* here; pass the bare app name (e.g. 'socket', 'registry').
 */
 function getSocketAppDir(appName) {
 	return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), `${"_"}${appName}`));
 }
 /**
-* Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
-* SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
-* is cached via getPathValue for performance.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-cacache-dir', ...)
-* 2. SOCKET_CACACHE_DIR - Full override of cacache directory
-* 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+* Get the Socket cacache directory (~/.socket/_cacache). Override precedence:
+* setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+* $SOCKET_HOME/_cacache → $HOME/.socket/_cacache.
 */
 /**
-* Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
-* SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
-* is cached via getPathValue for performance.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-cacache-dir', ...)
-* 2. SOCKET_CACACHE_DIR - Full override of cacache directory
-* 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+* Get an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+* daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+* the socket path is stable across binary upgrades.
 */
-function getSocketCacacheDir() {
-	return require_paths_rewire.getPathValue("socket-cacache-dir", () => {
-		if (require_env_socket.getSocketCacacheDirEnv()) return require_paths_normalize.normalizePath(require_env_socket.getSocketCacacheDirEnv());
-		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), `${"_"}cacache`));
-	});
+function getSocketAppRuntimeDir(appName) {
+	return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketAppStateDir(appName), "run"));
 }
 /**
-* Get the Socket CLI directory (~/.socket/_socket).
+* Get the Socket user directory (~/.socket). Override precedence:
+* setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+* /tmp/.socket (Unix) or %TEMP%.socket (Windows).
 */
 /**
-* Get the Socket CLI directory (~/.socket/_socket).
+* Get an app's persistent state directory (~/.socket/_state/<app>/). The
+* `<app>` is a real app (proteus, acorn) nesting its version-less state inside
+* the `_state` infra dir.
 */
-function getSocketCliDir() {
-	return getSocketAppDir(require_constants_socket.SOCKET_CLI_APP_NAME);
+function getSocketAppStateDir(appName) {
+	return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketStateDir(), appName));
 }
 /**
-* Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
-* SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
-* cached via getPathValue for performance.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-dlx-dir', ...)
-* 2. SOCKET_DLX_DIR - Full override of DLX cache directory
-* 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
-* 4. Default: $HOME/.socket/_dlx
-* 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
+* Get an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+* daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+* the socket path is stable across binary upgrades.
 */
 /**
-* Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
-* SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
-* cached via getPathValue for performance.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-dlx-dir', ...)
-* 2. SOCKET_DLX_DIR - Full override of DLX cache directory
-* 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
-* 4. Default: $HOME/.socket/_dlx
-* 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
+* Get the Socket cacache directory (~/.socket/_cacache). Override precedence:
+* setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+* $SOCKET_HOME/_cacache → $HOME/.socket/_cacache.
+*/
+function getSocketCacacheDir() {
+	return require_paths_rewire.getPathValue("socket-cacache-dir", () => {
+		if (require_env_socket.getSocketCacacheDirEnv()) return require_paths_normalize.normalizePath(require_env_socket.getSocketCacacheDirEnv());
+		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), require_constants_socket.SOCKET_DIR.cacache));
+	});
+}
+/**
+* Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+* (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+* …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
+*/
+/**
+* Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+* (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+* …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
 */
 function getSocketDlxDir() {
 	return require_paths_rewire.getPathValue("socket-dlx-dir", () => {
 		if (require_env_socket.getSocketDlxDirEnv()) return require_paths_normalize.normalizePath(require_env_socket.getSocketDlxDirEnv());
-		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), `${"_"}${"dlx"}`));
+		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), require_constants_socket.SOCKET_DIR.dlx));
 	});
 }
 /**
@@ -149,51 +142,34 @@ function getSocketHomePath() {
 	return getSocketUserDir();
 }
 /**
-* Get the Socket Registry directory (~/.socket/_registry).
+* Get the Socket state directory (~/.socket/_state) — version-LESS persistent
+* app state (the home for daemon sockets, locks, OAuth refresh, durable caches
+* that survive version bumps; mirrors pnpm `state-dir` / XDG_STATE_HOME).
+* Override precedence: setPath('socket-state-dir', …) → SOCKET_STATE_DIR env →
+* $SOCKET_HOME/_state → $HOME/.socket/_state.
 */
 /**
-* Get the Socket Registry directory (~/.socket/_registry).
-*/
-function getSocketRegistryDir() {
-	return getSocketAppDir(require_constants_socket.SOCKET_REGISTRY_APP_NAME);
-}
-/**
-* Get the Socket Registry GitHub cache directory
-* (~/.socket/_registry/cache/ttl/github).
+* Get the Socket state directory (~/.socket/_state) — version-LESS persistent
+* app state (the home for daemon sockets, locks, OAuth refresh, durable caches
+* that survive version bumps; mirrors pnpm `state-dir` / XDG_STATE_HOME).
+* Override precedence: setPath('socket-state-dir', …) → SOCKET_STATE_DIR env →
+* $SOCKET_HOME/_state → $HOME/.socket/_state.
 */
-/**
-* Get the Socket Registry GitHub cache directory
-* (~/.socket/_registry/cache/ttl/github).
-*/
-function getSocketRegistryGithubCacheDir() {
-	return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketAppCacheTtlDir(require_constants_socket.SOCKET_REGISTRY_APP_NAME), require_constants_github.CACHE_GITHUB_DIR));
+function getSocketStateDir() {
+	return require_paths_rewire.getPathValue("socket-state-dir", () => {
+		if (require_env_socket.getSocketStateDirEnv()) return require_paths_normalize.normalizePath(require_env_socket.getSocketStateDirEnv());
+		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), require_constants_socket.SOCKET_DIR.state));
+	});
 }
 /**
-* Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
-* cross-fleet location for binaries that every fleet member can reach without
-* each one re-downloading and re-extracting per-repo. Tool installers (janus,
-* sfw, etc.) drop their resolved executables under
-* `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
-* appropriate `bin/` to PATH or invoke the binary by absolute path.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-wheelhouse-dir', ...)
-* 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
-*    getSocketUserDir)
-* 3. Default: $HOME/.socket/_wheelhouse
+* Get an app's persistent state directory (~/.socket/_state/<app>/). The
+* `<app>` is a real app (proteus, acorn) nesting its version-less state inside
+* the `_state` infra dir.
 */
 /**
-* Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
-* environment variable or via setPath() for testing. Result is cached via
-* getPathValue for performance.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-user-dir', ...)
-* 2. SOCKET_HOME - Base directory override
-* 3. Default: $HOME/.socket
-* 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
+* Get the Socket user directory (~/.socket). Override precedence:
+* setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+* /tmp/.socket (Unix) or %TEMP%.socket (Windows).
 */
 function getSocketUserDir() {
 	return require_paths_rewire.getPathValue("socket-user-dir", () => {
@@ -203,12 +179,14 @@ function getSocketUserDir() {
 	});
 }
 /**
-* Get the user's home directory. Uses environment variables directly to support
-* test mocking. Falls back to temporary directory if home is not available.
-*
-* Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
-* environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
-* getNodeOs().tmpdir() (rarely used, for restricted environments)
+* Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
+* cross-fleet location for binaries that every fleet member can reach without
+* each one re-downloading and re-extracting per-repo. Tool installers (janus,
+* sfw, etc.) drop their resolved executables under
+* `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
+* appropriate `bin/` to PATH or invoke the binary by absolute path. Override
+* precedence: setPath('socket-wheelhouse-dir', …) → $SOCKET_HOME/_wheelhouse →
+* $HOME/.socket/_wheelhouse.
 */
 /**
 * Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
@@ -216,39 +194,28 @@ function getSocketUserDir() {
 * each one re-downloading and re-extracting per-repo. Tool installers (janus,
 * sfw, etc.) drop their resolved executables under
 * `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
-* appropriate `bin/` to PATH or invoke the binary by absolute path.
-*
-* Priority order:
-*
-* 1. Test override via setPath('socket-wheelhouse-dir', ...)
-* 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
-*    getSocketUserDir)
-* 3. Default: $HOME/.socket/_wheelhouse
+* appropriate `bin/` to PATH or invoke the binary by absolute path. Override
+* precedence: setPath('socket-wheelhouse-dir', …) → $SOCKET_HOME/_wheelhouse →
+* $HOME/.socket/_wheelhouse.
 */
 function getSocketWheelhouseDir() {
 	return require_paths_rewire.getPathValue("socket-wheelhouse-dir", () => {
-		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), `${"_"}${require_constants_socket.SOCKET_WHEELHOUSE_APP_NAME}`));
+		return require_paths_normalize.normalizePath(require_node_path.getNodePath().join(getSocketUserDir(), require_constants_socket.SOCKET_DIR.wheelhouse));
 	});
 }
 /**
-* Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
-* environment variable or via setPath() for testing. Result is cached via
-* getPathValue for performance.
-*
-* Priority order:
+* Get the user's home directory. Uses environment variables directly to support
+* test mocking. Falls back to temporary directory if home is not available.
 *
-* 1. Test override via setPath('socket-user-dir', ...)
-* 2. SOCKET_HOME - Base directory override
-* 3. Default: $HOME/.socket
-* 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
+* Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+* getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
 */
 /**
 * Get the user's home directory. Uses environment variables directly to support
 * test mocking. Falls back to temporary directory if home is not available.
 *
-* Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
-* environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
-* getNodeOs().tmpdir() (rarely used, for restricted environments)
+* Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+* getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
 */
 function getUserHomeDir() {
 	const home = require_env_home.getHome();
@@ -270,12 +237,12 @@ exports.getOsTmpDir = getOsTmpDir;
 exports.getSocketAppCacheDir = getSocketAppCacheDir;
 exports.getSocketAppCacheTtlDir = getSocketAppCacheTtlDir;
 exports.getSocketAppDir = getSocketAppDir;
+exports.getSocketAppRuntimeDir = getSocketAppRuntimeDir;
+exports.getSocketAppStateDir = getSocketAppStateDir;
 exports.getSocketCacacheDir = getSocketCacacheDir;
-exports.getSocketCliDir = getSocketCliDir;
 exports.getSocketDlxDir = getSocketDlxDir;
 exports.getSocketHomePath = getSocketHomePath;
-exports.getSocketRegistryDir = getSocketRegistryDir;
-exports.getSocketRegistryGithubCacheDir = getSocketRegistryGithubCacheDir;
+exports.getSocketStateDir = getSocketStateDir;
 exports.getSocketUserDir = getSocketUserDir;
 exports.getSocketWheelhouseDir = getSocketWheelhouseDir;
 exports.getUserHomeDir = getUserHomeDir;