dsh-connect-workbuddy 2.0.10 → 2.0.12

package/lib/{host-heartbeat-DPbL9oi2.js → host-heartbeat-ChtMu37E.js}

@@ -5,14 +5,13 @@ import { dirname, join } from "node:path";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { execFile, execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 //#region src/at-rest.ts
 /**
 * WorkBuddy desktop "at-rest" credential decryption.
 *
-* The WorkBuddy desktop app (2.x, Windows builds first) no longer stores
-* `auth.accessToken` / `auth.refreshToken` as plain strings. It now writes a
-* field wrapper:
+* From 5.6.0 the WorkBuddy desktop app no longer stores `auth.accessToken` /
+* `auth.refreshToken` as plain strings. It writes a field wrapper:
 *
 *   { "$wbEncrypted": 1, "envelope": "<base64 of a JSON envelope>" }
 *
@@ -33,6 +32,16 @@ import { existsSync } from "node:fs";
 * payload, and caches it in memory for the process lifetime. Nothing is ever
 * written to disk, and the payload is never logged.
 *
+* 改动：**「macOS 也加密」这一事实**（issue #15 真机取证）。本模块原先假设该
+*   policy 是 Windows 先行、macOS 只是「将来可能」，于是 macOS 的可执行文件
+*   路径用 App 名拼成 `<bundle>/Contents/MacOS/WorkBuddy`——而两个真实 bundle
+*   的 `CFBundleExecutable` 都是 `Electron`，该路径并不存在。结果是 macOS 上
+*   加密凭据**永远**取不到密钥，用户却被报成「未登录」。现在二进制名向 bundle
+*   自己问（`macosBundleExecutable()`），候选含国际版 `WorkBuddy AI.app`，
+*   并允许 App 被归入 applications 目录的子目录——扫到的候选必须先用
+*   `CFBundleIdentifier` 确认身份才 `execFile`，因为**每个 Electron 应用的
+*   二进制都叫 `Electron`**，只按名字匹配就可能启动另一个产品。
+*
 * @module dsh-connect-workbuddy/at-rest
 */
 /** Envelope framing names, mapped to the single-byte AAD framing code. */
@@ -57,8 +66,19 @@ const SYMMETRIC_SCHEME = "sym-v1";
 const WORKBUDDY_APP_EXECUTABLE_ENV = "WORKBUDDY_APP_EXECUTABLE";
 /** How long the app is given to answer with its key payload. */
 const KEY_FETCH_TIMEOUT_MS = 1e4;
-/** File name of the WorkBuddy desktop executable, per platform. */
+/** File name of the WorkBuddy desktop executable on Windows. */
 const APP_EXECUTABLE_NAME = "WorkBuddy.exe";
+/**
+* macOS bundles the desktop app may be installed as, in probe order.
+*
+* `WorkBuddy.app` is the domestic build; `WorkBuddy AI.app` is the
+* international one, and a machine may carry either or both. The user-level
+* `~/Applications` location is included because macOS lets an app live there,
+* and installs have been observed under a subdirectory of /Applications too —
+* hence {@link findWorkbuddyAppExecutable}'s parent scan, which covers those
+* without guessing any particular folder name.
+*/
+const MACOS_APP_BUNDLE_NAMES = ["WorkBuddy.app", "WorkBuddy AI.app"];
 function encodeUint32(value) {
 	const bytes = Buffer.allocUnsafe(4);
 	bytes.writeUInt32BE(value);
@@ -156,24 +176,127 @@ function openEncryptedField(field, key) {
 	return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64")), decipher.final()]).toString("utf8");
 }
 /**
+* The executable inside a macOS app bundle, read from the bundle's own
+* `Info.plist`.
+*
+* The binary is NOT reliably named after the app: the WorkBuddy bundles ship
+* with `CFBundleExecutable` set to `Electron`, so a path assembled as
+* `<bundle>/Contents/MacOS/WorkBuddy` does not exist and the app looks absent
+* even when it is installed in the default location. Because the bundle
+* documents the real name, asking it is both correct and robust to a future
+* build that renames the binary.
+*
+* Returns undefined when the plist is absent, unreadable, or carries no usable
+* name — never a guessed path, so a caller can keep probing.
+*/
+function macosBundleExecutable(bundle) {
+	let plist;
+	try {
+		plist = readFileSync(join(bundle, "Contents", "Info.plist"), "utf8");
+	} catch {
+		return;
+	}
+	const name = /<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]*)<\/string>/u.exec(plist)?.[1]?.trim();
+	if (name === void 0 || name === "" || name.includes("/") || name.includes("\\") || name === "." || name === "..") return;
+	return join(bundle, "Contents", "MacOS", name);
+}
+/**
 * Candidate paths of the WorkBuddy desktop executable, in probe order.
 *
 * The Windows build is the one that encrypts credentials, so Windows leads;
-* the macOS bundle is listed because the same native module ships there and a
-* future build may enable the policy, and `undefined` entries (an unset env
-* variable) are dropped.
+* the macOS bundles are listed because the same native module ships there and
+* the encryption policy is enabled on macOS builds too (observed from 5.6.x),
+* and `undefined` entries (an unset env variable) are dropped.
+*
+* On macOS the executable name comes from each bundle (see
+* {@link macosBundleExecutable}) rather than being assembled from the app name.
+*
+* `readBundleExecutable` is injectable, in the same spirit as `platform`/`home`/
+* `env`: the macOS branch consults the real filesystem, so without a seam the
+* expected candidates would depend on whether the host machine happens to have
+* the app installed — and the test would pass on a developer's Mac while
+* failing in CI.
 */
-function workbuddyAppExecutableCandidates(platform = process.platform, home = homedir(), env = process.env) {
+function workbuddyAppExecutableCandidates(platform = process.platform, home = homedir(), env = process.env, readBundleExecutable = macosBundleExecutable) {
 	const candidates = [env[WORKBUDDY_APP_EXECUTABLE_ENV]?.trim()];
 	if (platform === "win32") {
 		const local = env["LOCALAPPDATA"]?.trim();
 		const programFiles = env["ProgramFiles"]?.trim();
 		const programFilesX86 = env["ProgramFiles(x86)"]?.trim();
-		candidates.push(local === void 0 || local === "" ? void 0 : join(local, "Programs", "WorkBuddy", APP_EXECUTABLE_NAME), programFiles === void 0 || programFiles === "" ? void 0 : join(programFiles, "WorkBuddy", APP_EXECUTABLE_NAME), programFilesX86 === void 0 || programFilesX86 === "" ? void 0 : join(programFilesX86, "WorkBuddy", APP_EXECUTABLE_NAME));
-	} else if (platform === "darwin") candidates.push("/Applications/WorkBuddy.app/Contents/MacOS/WorkBuddy", join(home, "Applications", "WorkBuddy.app", "Contents", "MacOS", "WorkBuddy"));
+		candidates.push(local === void 0 || local === "" ? void 0 : join(local, "Programs", "WorkBuddy", APP_EXECUTABLE_NAME), local === void 0 || local === "" ? void 0 : join(local, "WorkBuddy", APP_EXECUTABLE_NAME), programFiles === void 0 || programFiles === "" ? void 0 : join(programFiles, "WorkBuddy", APP_EXECUTABLE_NAME), programFilesX86 === void 0 || programFilesX86 === "" ? void 0 : join(programFilesX86, "WorkBuddy", APP_EXECUTABLE_NAME));
+	} else if (platform === "darwin") for (const name of MACOS_APP_BUNDLE_NAMES) candidates.push(readBundleExecutable(join("/Applications", name)), readBundleExecutable(join(home, "Applications", name)));
 	return candidates.filter((candidate) => candidate !== void 0 && candidate !== "");
 }
 /**
+* Bundle identifier PREFIXES the desktop app is signed with — `com.tencent.
+* workbuddy` (domestic, observed as `…workbuddy.mac`) and `com.workbuddy`
+* (international, observed as `com.workbuddy.workbuddy-ai`).
+*
+* Used to CONFIRM that a discovered bundle really is WorkBuddy before it is
+* launched. This matters because the discovery below scans directories and then
+* execs what it finds: every Electron app is built around a binary called
+* `Electron`, so a name-only match could pick a different product's bundle and
+* run it. The identifier is the app's own claim about itself, so it is the
+* check that makes the scan safe.
+*/
+const APP_BUNDLE_IDENTIFIER_PREFIXES = ["com.tencent.workbuddy", "com.workbuddy"];
+/**
+* Whether a bundle identifies itself as the WorkBuddy desktop app.
+*
+* The match is on dot boundaries, so a hypothetical `com.workbuddyish` cannot
+* pass as `com.workbuddy`.
+*
+* An unreadable or identifier-less plist is treated as NOT WorkBuddy: refusing
+* a candidate only costs a fallback to another path, whereas accepting the
+* wrong one would execute an unrelated application.
+*/
+function isWorkbuddyBundle(bundle) {
+	let plist;
+	try {
+		plist = readFileSync(join(bundle, "Contents", "Info.plist"), "utf8");
+	} catch {
+		return false;
+	}
+	const identifier = /<key>\s*CFBundleIdentifier\s*<\/key>\s*<string>([^<]*)<\/string>/u.exec(plist)?.[1]?.trim().toLowerCase();
+	if (identifier === void 0 || identifier === "") return false;
+	return APP_BUNDLE_IDENTIFIER_PREFIXES.some((prefix) => identifier === prefix || identifier.startsWith(`${prefix}.`));
+}
+/**
+* Bundles of the desktop app found one level BELOW a macOS applications
+* directory.
+*
+* Users do file apps into subfolders (`/Applications/IDE/WorkBuddy.app`), and
+* a hardcoded `/Applications/<name>` then reports the app as missing while it
+* is installed and signed in. The scan is deliberately ONE level deep and
+* matches the known bundle names only, so it stays predictable and cheap; each
+* candidate is then confirmed by {@link isWorkbuddyBundle} before use.
+*
+* Returns [] when the parent is absent or unreadable — a missing directory is
+* the normal case, not an error.
+*/
+function macosNestedAppBundles(parent) {
+	let entries;
+	try {
+		entries = readdirSync(parent);
+	} catch {
+		return [];
+	}
+	const bundles = [];
+	for (const entry of entries) {
+		const nested = join(parent, entry);
+		for (const name of MACOS_APP_BUNDLE_NAMES) {
+			const bundle = join(nested, name);
+			try {
+				if (!statSync(bundle).isDirectory()) continue;
+			} catch {
+				continue;
+			}
+			if (isWorkbuddyBundle(bundle)) bundles.push(bundle);
+		}
+	}
+	return bundles;
+}
+/**
 * The first candidate that exists as a file, or undefined when the desktop app
 * is not installed where this platform expects it.
 */
@@ -181,6 +304,13 @@ function findWorkbuddyAppExecutable(platform = process.platform, home = homedir(
 	for (const candidate of workbuddyAppExecutableCandidates(platform, home, env)) try {
 		if (existsSync(candidate)) return candidate;
 	} catch {}
+	if (platform === "darwin") for (const parent of ["/Applications", join(home, "Applications")]) for (const bundle of macosNestedAppBundles(parent)) {
+		const executable = macosBundleExecutable(bundle);
+		if (executable === void 0) continue;
+		try {
+			if (existsSync(executable)) return executable;
+		} catch {}
+	}
 }
 /**
 * Ask the installed desktop app for its key payload by running its own binary
@@ -905,9 +1035,52 @@ var WorkBuddyUpstreamClient = class {
 *   一个 store，账号、刷新、选择完全隔离；插件自有刷新副本也按区域分
 *   文件（`.workbuddy-auth.<region>.json`），双账号同时在线互不覆盖，
 *   旧的单文件 `.workbuddy-auth.json` 作为迁移源保留读取。
+*   另（issue #15）：`resolve()` 不再把「没登录」与「有登录但凭据读不出来」
+*   合并成同一句话。后者（加密字段 + 取不到密钥）改为抛
+*   `WorkBuddyEncryptedCredentialError`，给出「装 App / 用
+*   WORKBUDDY_APP_EXECUTABLE 指定」这条**可执行**的建议——对已登录的用户说
+*   「请重新登录一次」指向的是唯一无效的动作。判定只在失败路径上跑一次
+*   `diagnose()`，健康路径不付任何代价。
 *
 * @module dsh-connect-workbuddy/auth
 */
+/**
+* Marker for a credential that EXISTS but could not be decrypted.
+*
+* Identified by {@link ENCRYPTED_CREDENTIAL_CODE} rather than `instanceof`, so
+* the check keeps working when the thrower and the caller end up in different
+* module instances (bundled host half vs. a test's source import) — the same
+* convention `WorkBuddyCredentialRejectedError` uses.
+*/
+const ENCRYPTED_CREDENTIAL_CODE = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+/**
+* The user IS signed in, but the credential file cannot be read.
+*
+* This exists because "signed out" and "signed in with an unreadable credential"
+* resolve to the same observable state — zero accounts — and were therefore
+* reported with the same message. That message told a correctly signed-in user
+* to sign in again, which cannot possibly help: from WorkBuddy 5.6.x the desktop
+* app encrypts its token fields, and reading them requires asking the installed
+* app for its key. If that app cannot be located, the fix is to point the plugin
+* at it (`WORKBUDDY_APP_EXECUTABLE`), never to sign in again.
+*
+* No token material is carried: only the paths and the environment variable.
+*/
+var WorkBuddyEncryptedCredentialError = class extends Error {
+	code = ENCRYPTED_CREDENTIAL_CODE;
+	/** Files that hold an encrypted credential, for the user to recognize. */
+	paths;
+	constructor(paths) {
+		const where = paths.length > 0 ? paths.join(", ") : "the credential file";
+		super(`workbuddy: your WorkBuddy sign-in is present but encrypted, so it cannot be read (${where}). The WorkBuddy desktop app must be present to hand over its key; install it, or set ${WORKBUDDY_APP_EXECUTABLE_ENV} to its executable if it lives elsewhere. Signing in again will not change this.`);
+		this.name = "WorkBuddyEncryptedCredentialError";
+		this.paths = paths;
+	}
+};
+/** Whether an error reports an unreadable (encrypted) credential. */
+function isEncryptedCredentialError(value) {
+	return typeof value === "object" && value !== null && value.code === "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+}
 /** Legacy single-copy basename (pre-dual-provider); kept as migration source. */
 const WORKBUDDY_AUTH_FILENAME = ".workbuddy-auth.json";
 /** Env variable that overrides the desktop auth-file location. */
@@ -1510,17 +1683,38 @@ var WorkBuddyCredentialStore = class {
 	/** The credential to send upstream: {@link current}, refreshed on demand. */
 	async resolve() {
 		const credential = await this.current();
-		if (credential === void 0) {
-			const candidates = this.resolveDesktopCandidates();
-			const desktop = candidates.length > 0 ? candidates.join(" or ") : "(no desktop path on this platform)";
-			throw new Error(`workbuddy: no signed-in WorkBuddy account found; sign in once in the WorkBuddy desktop app (expected ${desktop} or ${WORKBUDDY_AUTH_FILE_ENV}), or refresh an existing session`);
-		}
+		if (credential === void 0) throw await this.describeMissingCredential();
 		if (!this.needsRefresh(credential)) return credential;
 		this.inflight ??= this.refreshNow(credential).finally(() => {
 			this.inflight = void 0;
 		});
 		return this.inflight;
 	}
+	/**
+	* WHY no credential resolved, as the error to throw.
+	*
+	* `resolve()` seeing zero accounts has two very different causes, and the
+	* generic "sign in once" message is only correct for one of them. When a
+	* probe finds a credential file whose fields are encrypted and the key could
+	* not be obtained, the user is signed in and re-authenticating cannot help —
+	* so that case gets {@link WorkBuddyEncryptedCredentialError} instead, naming
+	* the file and the environment variable that actually fixes it.
+	*
+	* The probe is only run on the failure path, so the healthy case pays nothing.
+	* A probe that itself throws must not replace the real error, hence the
+	* fallback to the generic message.
+	*/
+	async describeMissingCredential() {
+		let failures = [];
+		try {
+			failures = (await this.diagnose()).failures;
+		} catch {}
+		const encrypted = failures.filter((failure) => failure.reason === "encrypted").map((failure) => failure.path);
+		if (encrypted.length > 0) return new WorkBuddyEncryptedCredentialError(encrypted);
+		const candidates = this.resolveDesktopCandidates();
+		const desktop = candidates.length > 0 ? candidates.join(" or ") : "(no desktop path on this platform)";
+		return /* @__PURE__ */ new Error(`workbuddy: no signed-in WorkBuddy account found; sign in once in the WorkBuddy desktop app (expected ${desktop} or ${WORKBUDDY_AUTH_FILE_ENV}), or refresh an existing session`);
+	}
 	/** Read-only sign-in summary; never refreshes and never throws. */
 	async status() {
 		try {
@@ -2014,7 +2208,7 @@ var WorkBuddyCatalog = class {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "2.0.10";
+const WORKBUDDY_CONNECT_VERSION = "2.0.12";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -2120,4 +2314,4 @@ async function clearHostHeartbeat() {
 	await rm(workbuddyHostHeartbeatPath(), { force: true });
 }
 //#endregion
-export { isCredentialRejectedError as A, fetchAtRestKeyPayload as B, parseWorkBuddyAuth as C, WorkBuddyCredentialRejectedError as D, CREDENTIAL_REJECTED_CODE as E, regionOf as F, workbuddyAppExecutableCandidates as G, isEncryptedFieldWrapper as H, WORKBUDDY_APP_EXECUTABLE_ENV as I, clearAtRestKeyCache as L, parseReasoning as M, parseUpstreamModel as N, WorkBuddyUpstreamClient as O, prepareChatBody as P, deriveAtRestKey as R, legacyWorkbuddyOwnAuthPath as S, workbuddyOwnAuthPath as T, openEncryptedField as U, findWorkbuddyAppExecutable as V, readAtRestKey as W, authFileName as _, readHostHeartbeat as a, defaultDesktopAuthPath as b, WORKBUDDY_CONNECT_VERSION as c, WorkBuddyCatalog as d, deriveCatalog as f, WorkBuddyCredentialStore as g, WORKBUDDY_AUTH_FILE_ENV as h, processStartTimeMs as i, parseCreditMultiplier as j, classifyUpstreamError as k, FALLBACK_WORKBUDDY_MODELS as l, WORKBUDDY_AUTH_FILENAME as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, fallbackModelsFor as p, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS_GLOBAL as u, defaultDesktopAuthCandidates as v, workbuddyAccountId as w, hasEncryptedCredentialFields as x, defaultDesktopAuthDirs as y, deriveAtRestKeyId as z };
+export { WorkBuddyCredentialRejectedError as A, clearAtRestKeyCache as B, hasEncryptedCredentialFields as C, workbuddyAccountId as D, parseWorkBuddyAuth as E, parseReasoning as F, isEncryptedFieldWrapper as G, deriveAtRestKeyId as H, parseUpstreamModel as I, macosNestedAppBundles as J, isWorkbuddyBundle as K, prepareChatBody as L, classifyUpstreamError as M, isCredentialRejectedError as N, workbuddyOwnAuthPath as O, parseCreditMultiplier as P, regionOf as R, defaultDesktopAuthPath as S, legacyWorkbuddyOwnAuthPath as T, fetchAtRestKeyPayload as U, deriveAtRestKey as V, findWorkbuddyAppExecutable as W, readAtRestKey as X, openEncryptedField as Y, workbuddyAppExecutableCandidates as Z, WorkBuddyCredentialStore as _, readHostHeartbeat as a, defaultDesktopAuthCandidates as b, WORKBUDDY_CONNECT_VERSION as c, WorkBuddyCatalog as d, deriveCatalog as f, WORKBUDDY_AUTH_FILE_ENV as g, WORKBUDDY_AUTH_FILENAME as h, processStartTimeMs as i, WorkBuddyUpstreamClient as j, CREDENTIAL_REJECTED_CODE as k, FALLBACK_WORKBUDDY_MODELS as l, ENCRYPTED_CREDENTIAL_CODE as m, clearHostHeartbeat as n, workbuddyHostHeartbeatPath as o, fallbackModelsFor as p, macosBundleExecutable as q, isHeartbeatProcessAlive as r, writeHostHeartbeat as s, WORKBUDDY_HOST_HEARTBEAT_FILENAME as t, FALLBACK_WORKBUDDY_MODELS_GLOBAL as u, WorkBuddyEncryptedCredentialError as v, isEncryptedCredentialError as w, defaultDesktopAuthDirs as x, authFileName as y, WORKBUDDY_APP_EXECUTABLE_ENV as z };

package/lib/index.d.ts

@@ -65,6 +65,36 @@ interface WorkBuddyAuthStatus {
   domain?: string;
   source?: 'desktop' | 'dsh';
 }
+/**
+ * Marker for a credential that EXISTS but could not be decrypted.
+ *
+ * Identified by {@link ENCRYPTED_CREDENTIAL_CODE} rather than `instanceof`, so
+ * the check keeps working when the thrower and the caller end up in different
+ * module instances (bundled host half vs. a test's source import) — the same
+ * convention `WorkBuddyCredentialRejectedError` uses.
+ */
+declare const ENCRYPTED_CREDENTIAL_CODE = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+/**
+ * The user IS signed in, but the credential file cannot be read.
+ *
+ * This exists because "signed out" and "signed in with an unreadable credential"
+ * resolve to the same observable state — zero accounts — and were therefore
+ * reported with the same message. That message told a correctly signed-in user
+ * to sign in again, which cannot possibly help: from WorkBuddy 5.6.x the desktop
+ * app encrypts its token fields, and reading them requires asking the installed
+ * app for its key. If that app cannot be located, the fix is to point the plugin
+ * at it (`WORKBUDDY_APP_EXECUTABLE`), never to sign in again.
+ *
+ * No token material is carried: only the paths and the environment variable.
+ */
+declare class WorkBuddyEncryptedCredentialError extends Error {
+  readonly code = "WORKBUDDY_ENCRYPTED_CREDENTIAL";
+  /** Files that hold an encrypted credential, for the user to recognize. */
+  readonly paths: readonly string[];
+  constructor(paths: readonly string[]);
+}
+/** Whether an error reports an unreadable (encrypted) credential. */
+declare function isEncryptedCredentialError(value: unknown): value is WorkBuddyEncryptedCredentialError;
 /** Constructor options; only {@link refresh} is required. */
 interface WorkBuddyStoreOptions {
   /** Explicit desktop auth-file path, overriding env and platform defaults. */
@@ -328,6 +358,21 @@ declare class WorkBuddyCredentialStore {
   credentialFor(accountId: string): Promise<WorkBuddyCredential | undefined>;
   /** The credential to send upstream: {@link current}, refreshed on demand. */
   resolve(): Promise<WorkBuddyCredential>;
+  /**
+   * WHY no credential resolved, as the error to throw.
+   *
+   * `resolve()` seeing zero accounts has two very different causes, and the
+   * generic "sign in once" message is only correct for one of them. When a
+   * probe finds a credential file whose fields are encrypted and the key could
+   * not be obtained, the user is signed in and re-authenticating cannot help —
+   * so that case gets {@link WorkBuddyEncryptedCredentialError} instead, naming
+   * the file and the environment variable that actually fixes it.
+   *
+   * The probe is only run on the failure path, so the healthy case pays nothing.
+   * A probe that itself throws must not replace the real error, hence the
+   * fallback to the generic message.
+   */
+  private describeMissingCredential;
   /** Read-only sign-in summary; never refreshes and never throws. */
   status(): Promise<WorkBuddyAuthStatus>;
   /**
@@ -753,9 +798,8 @@ declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkB
 /**
  * WorkBuddy desktop "at-rest" credential decryption.
  *
- * The WorkBuddy desktop app (2.x, Windows builds first) no longer stores
- * `auth.accessToken` / `auth.refreshToken` as plain strings. It now writes a
- * field wrapper:
+ * From 5.6.0 the WorkBuddy desktop app no longer stores `auth.accessToken` /
+ * `auth.refreshToken` as plain strings. It writes a field wrapper:
  *
  *   { "$wbEncrypted": 1, "envelope": "<base64 of a JSON envelope>" }
  *
@@ -776,6 +820,16 @@ declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkB
  * payload, and caches it in memory for the process lifetime. Nothing is ever
  * written to disk, and the payload is never logged.
  *
+ * 改动：**「macOS 也加密」这一事实**（issue #15 真机取证）。本模块原先假设该
+ *   policy 是 Windows 先行、macOS 只是「将来可能」，于是 macOS 的可执行文件
+ *   路径用 App 名拼成 `<bundle>/Contents/MacOS/WorkBuddy`——而两个真实 bundle
+ *   的 `CFBundleExecutable` 都是 `Electron`，该路径并不存在。结果是 macOS 上
+ *   加密凭据**永远**取不到密钥，用户却被报成「未登录」。现在二进制名向 bundle
+ *   自己问（`macosBundleExecutable()`），候选含国际版 `WorkBuddy AI.app`，
+ *   并允许 App 被归入 applications 目录的子目录——扫到的候选必须先用
+ *   `CFBundleIdentifier` 确认身份才 `execFile`，因为**每个 Electron 应用的
+ *   二进制都叫 `Electron`**，只按名字匹配就可能启动另一个产品。
+ *
  * @module dsh-connect-workbuddy/at-rest
  */
 /** A `{$wbEncrypted:1,envelope}` field wrapper, the only shape this module opens. */
@@ -809,15 +863,64 @@ declare function deriveAtRestKey(payloadJson: string): Buffer;
  * key is wrong, and it must never degrade into a truncated token.
  */
 declare function openEncryptedField(field: WorkBuddyEncryptedField, key: Buffer): string;
+/**
+ * The executable inside a macOS app bundle, read from the bundle's own
+ * `Info.plist`.
+ *
+ * The binary is NOT reliably named after the app: the WorkBuddy bundles ship
+ * with `CFBundleExecutable` set to `Electron`, so a path assembled as
+ * `<bundle>/Contents/MacOS/WorkBuddy` does not exist and the app looks absent
+ * even when it is installed in the default location. Because the bundle
+ * documents the real name, asking it is both correct and robust to a future
+ * build that renames the binary.
+ *
+ * Returns undefined when the plist is absent, unreadable, or carries no usable
+ * name — never a guessed path, so a caller can keep probing.
+ */
+declare function macosBundleExecutable(bundle: string): string | undefined;
 /**
  * Candidate paths of the WorkBuddy desktop executable, in probe order.
  *
  * The Windows build is the one that encrypts credentials, so Windows leads;
- * the macOS bundle is listed because the same native module ships there and a
- * future build may enable the policy, and `undefined` entries (an unset env
- * variable) are dropped.
+ * the macOS bundles are listed because the same native module ships there and
+ * the encryption policy is enabled on macOS builds too (observed from 5.6.x),
+ * and `undefined` entries (an unset env variable) are dropped.
+ *
+ * On macOS the executable name comes from each bundle (see
+ * {@link macosBundleExecutable}) rather than being assembled from the app name.
+ *
+ * `readBundleExecutable` is injectable, in the same spirit as `platform`/`home`/
+ * `env`: the macOS branch consults the real filesystem, so without a seam the
+ * expected candidates would depend on whether the host machine happens to have
+ * the app installed — and the test would pass on a developer's Mac while
+ * failing in CI.
  */
-declare function workbuddyAppExecutableCandidates(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string[];
+declare function workbuddyAppExecutableCandidates(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv, readBundleExecutable?: (bundle: string) => string | undefined): string[];
+/**
+ * Whether a bundle identifies itself as the WorkBuddy desktop app.
+ *
+ * The match is on dot boundaries, so a hypothetical `com.workbuddyish` cannot
+ * pass as `com.workbuddy`.
+ *
+ * An unreadable or identifier-less plist is treated as NOT WorkBuddy: refusing
+ * a candidate only costs a fallback to another path, whereas accepting the
+ * wrong one would execute an unrelated application.
+ */
+declare function isWorkbuddyBundle(bundle: string): boolean;
+/**
+ * Bundles of the desktop app found one level BELOW a macOS applications
+ * directory.
+ *
+ * Users do file apps into subfolders (`/Applications/IDE/WorkBuddy.app`), and
+ * a hardcoded `/Applications/<name>` then reports the app as missing while it
+ * is installed and signed in. The scan is deliberately ONE level deep and
+ * matches the known bundle names only, so it stays predictable and cheap; each
+ * candidate is then confirmed by {@link isWorkbuddyBundle} before use.
+ *
+ * Returns [] when the parent is absent or unreadable — a missing directory is
+ * the normal case, not an error.
+ */
+declare function macosNestedAppBundles(parent: string): string[];
 /**
  * The first candidate that exists as a file, or undefined when the desktop app
  * is not installed where this platform expects it.
@@ -1242,6 +1345,23 @@ type WorkBuddyWebUsage =
   credentialRejected?: boolean;
   /** Present only alongside {@link credentialRejected}. */
   recovery?: WorkBuddyWebRecovery;
+  /**
+   * Diagnostic only: whether this Host build's Config carries the volatile
+   * markers dsh-settings requires before it will persist any field. Exposed
+   * so a save refusal can be attributed to the settings gate rather than
+   * guessed at.
+   */
+  diagVolatile?: {
+    regions: boolean;
+    accounts: boolean;
+    authFile: boolean;
+  };
+  /**
+   * The persisted per-region context budgets as the Host reads them. The
+   * browser settings mirror can lag a write made through the Host save
+   * endpoint, so the card renders these rather than a possibly-stale snapshot.
+   */
+  contextBudgets?: Record<string, number>;
 } | {
   status: 'error';
   message: string;
@@ -1372,6 +1492,43 @@ interface Config {
   /** @deprecated See {@link Config.lastCatalog}. */
   contextBudgets?: Record<string, WorkBuddyContextBudget>;
 }
+/**
+ * Mark a schema's field as volatile on the DSH lines that support it.
+ *
+ * `volatile()` exists from schemastery 3.18.3 (the DSH 0.1.7 line, which is the
+ * only line whose settings write gate reads the marker). Older pinning (3.18.2,
+ * the 0.1.5 line) has no such method, and the schema must stay byte-identical to
+ * the unmarked original there: hand-writing `meta.volatile = true` would bypass
+ * schemastery's own validateVolatileSchema checks and produce a schema no 0.1.5
+ * consumer understands — so on that line this degrades to an identity no-op.
+ *
+ * Exported so BOTH arms are testable on any machine. The capability is decided
+ * by whichever schemastery the dependency tree resolves, so without a seam the
+ * no-op arm would silently stop being exercised the moment the pinned version
+ * moved up — which is exactly how the volatile-path defect below went unseen.
+ */
+declare function asVolatile<T>(schema: z<T>): z<T>;
+/**
+ * Deep copy of a config value with every `{get(): T}` live reference replaced
+ * by the value it resolves to.
+ *
+ * {@link unwrapVolatile} only peels the ONE level a caller reads, which is all
+ * the ordinary read paths need. Handing a config object to a settings service
+ * is different: the service validates and `structuredClone`s the WHOLE object,
+ * so a reference surviving anywhere inside it fails schema validation with a
+ * message that names the field but not the cause —
+ * `$.authFile expected string but got [object Object]`.
+ *
+ * That is exactly what happened on the 0.1.5 line once volatile marking became
+ * active: `installSection` received the raw config, whose volatile fields were
+ * live references, and every field it validated threw. The namespace never
+ * registered, so the card's settings silently disappeared.
+ *
+ * Non-reference values are recursed into so a nested volatile field is caught
+ * too — arrays are rebuilt rather than mutated, so the caller's config object is
+ * never touched.
+ */
+declare function unwrapVolatileDeep<T>(value: T): T;
 declare const Config: z<Config>;
 /**
  * One region's saved model state. A config written before the region split has
@@ -1442,4 +1599,4 @@ declare function legacyAttributionRegion(value: Config, accountsFor: (region: Wo
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { CREDENTIAL_REJECTED_CODE, Config, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebRegion, type WorkBuddyWebSearchPath, type WorkBuddyWebUsage, apply, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, inject, isCredentialRejectedError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, name, nextRegionEnabled, nextRegionSlots, openEncryptedField, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, toPersistedWorkBuddyModel, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };
+export { CREDENTIAL_REJECTED_CODE, Config, ENCRYPTED_CREDENTIAL_CODE, FALLBACK_WORKBUDDY_MODELS, FALLBACK_WORKBUDDY_MODELS_GLOBAL, type UpstreamErrorKind, WORKBUDDY_ACCOUNTS_REFRESH_PATH, WORKBUDDY_APP_EXECUTABLE_ENV, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_CHECKIN_PATH, WORKBUDDY_CONNECT_VERSION, WORKBUDDY_GLOBAL_PROVIDER, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_MODELS_REFRESH_PATH, WORKBUDDY_PROVIDER, WORKBUDDY_PROVIDERS, WORKBUDDY_PROVIDER_DISPLAY_NAMES, WORKBUDDY_REGIONS, WORKBUDDY_REGION_PARAM, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WORKBUDDY_USAGE_PATH, type WorkBuddyAccountChoice, type WorkBuddyAdapter, type WorkBuddyAuthStatus, type WorkBuddyCandidateFailure, WorkBuddyCatalog, type WorkBuddyChatResult, type WorkBuddyCredential, type WorkBuddyCredentialRecovery, WorkBuddyCredentialRejectedError, WorkBuddyCredentialStore, type WorkBuddyCreditPackage, type WorkBuddyCredits, WorkBuddyEncryptedCredentialError, type WorkBuddyEncryptedField, type WorkBuddyHostHeartbeat, type WorkBuddyModelInfo, type WorkBuddyProbeStore, type WorkBuddyReasoning, type WorkBuddyRecoveryCandidate, type WorkBuddyRefreshOutcome, WorkBuddyRegionState, type WorkBuddyShim, type WorkBuddyStatusRouteOptions, type WorkBuddyStoreOptions, WorkBuddyUpstreamClient, type WorkBuddyUpstreamModel, type WorkBuddyUsabilityProbeOptions, type WorkBuddyWebAccount, type WorkBuddyWebCheckin, type WorkBuddyWebCredits, type WorkBuddyWebModel, type WorkBuddyWebPackage, type WorkBuddyWebRegion, type WorkBuddyWebSearchPath, type WorkBuddyWebUsage, apply, asVolatile, authFileName, classifyUpstreamError, clearAtRestKeyCache, clearHostHeartbeat, createAccountUsabilityProbe, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthDirs, defaultDesktopAuthPath, deriveAtRestKey, deriveAtRestKeyId, deriveCatalog, fallbackModelsFor, fetchAtRestKeyPayload, findWorkbuddyAppExecutable, hasEncryptedCredentialFields, inject, isCredentialRejectedError, isEncryptedCredentialError, isEncryptedFieldWrapper, isHeartbeatProcessAlive, isWorkbuddyBundle, legacyAttributionRegion, legacyWorkbuddyOwnAuthPath, macosBundleExecutable, macosNestedAppBundles, name, nextRegionEnabled, nextRegionSlots, openEncryptedField, parseCreditMultiplier, parseReasoning, parseUpstreamModel, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readAtRestKey, readHostHeartbeat, regionCleared, regionEnabled, regionEnabledOf, regionOf, regionOfProvider, regionOfStatusUrl, regionStateOf, registerWorkBuddyStatusRoute, resolveCredentialRecovery, selectAccountFor, toPersistedWorkBuddyModel, unwrapVolatileDeep, withWorkBuddyRegion, workBuddyDisplayName, workBuddyModelInput, workBuddyThinkingLevelMap, workBuddyWebStatus, workbuddyAccountId, workbuddyAppExecutableCandidates, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, writeHostHeartbeat };