dsh-workbuddy-connect 0.6.0 → 0.6.2

package/lib/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { D as WorkBuddyUpstreamClient, Y as resolveAppVersion, b as WorkBuddyCredentialStore, f as WORKBUDDY_CONNECT_VERSION, g as FALLBACK_WORKBUDDY_MODELS, h as FALLBACK_WORKBUDDY_AI_MODELS, i as variantFor, l as readHostHeartbeat, n as CN_VARIANT, r as WORKBUDDY_VARIANTS, s as isHeartbeatProcessAlive, u as workbuddyHostHeartbeatPath } from "./variants-CnrmSn0Q.js";
+import { D as WorkBuddyUpstreamClient, E as WorkBuddyAtRestKeyProvider, Y as resolveAppVersion, b as WorkBuddyCredentialStore, f as WORKBUDDY_CONNECT_VERSION, g as FALLBACK_WORKBUDDY_MODELS, h as FALLBACK_WORKBUDDY_AI_MODELS, i as variantFor, l as readHostHeartbeat, n as CN_VARIANT, r as WORKBUDDY_VARIANTS, s as isHeartbeatProcessAlive, u as workbuddyHostHeartbeatPath } from "./variants-B3Pa4EBr.js";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/bin.ts
@@ -26,12 +26,21 @@ function printHelp() {
 function printJson(value) {
 	process.stdout.write(`${JSON.stringify(value)}\n`);
 }
-/** One variant's store plus the client that performs its refreshes. */
+/**
+* One variant's store plus the client that performs its refreshes.
+*
+* The key provider is injected explicitly, and per variant, for the same
+* reason the plugin host does it: discovery is CN/macOS-only, so the provider
+* must not be left to its no-arg default — that default is deliberately
+* `discovery: 'none'`, and relying on it here would quietly strip the CN CLI
+* of the decryption it has always had.
+*/
 function makeStore(variant) {
 	const client = new WorkBuddyUpstreamClient();
 	return new WorkBuddyCredentialStore({
 		variant,
-		refresh: (credential) => client.refreshToken(credential)
+		refresh: (credential) => client.refreshToken(credential),
+		keyProvider: new WorkBuddyAtRestKeyProvider({ discovery: variant.id === CN_VARIANT.id ? "macos-workbuddy" : "none" })
 	});
 }
 /** The plugin-owned credential copy for one variant, for display. */

package/lib/client.js

@@ -30,6 +30,21 @@ window.__ModuleLoader__.load({
 		*/
 		const WORKBUDDY_AI_STATUS_PATH = "/plugins/dsh-workbuddy-connect/ai/status";
 		const WORKBUDDY_AI_PROBE_PATH = "/plugins/dsh-workbuddy-connect/ai/probe";
+		/** Every reason code, for validation without trusting a wire value. */
+		const SIGNED_OUT_REASON_CODES = [
+			"no-credential",
+			"credential-region-mismatch",
+			"encrypted-credential-unreadable",
+			"electron-binary-not-found",
+			"electron-binary-ambiguous",
+			"electron-binary-unavailable",
+			"electron-path-invalid",
+			"electron-discovery-incomplete"
+		];
+		/** Whether a value is one of the closed set of signed-out reason codes. */
+		function isWorkBuddySignedOutReasonCode(value) {
+			return typeof value === "string" && SIGNED_OUT_REASON_CODES.includes(value);
+		}
 		//#endregion
 		//#region src/client/status-document.ts
 		/**
@@ -43,6 +58,11 @@ window.__ModuleLoader__.load({
 		* The check is deliberately limited to the discriminator (plus `error`'s
 		* `message`, which the error paragraph renders): validating optional fields
 		* here would reject documents the host legitimately omits fields from.
+		*
+		* `reasonCode` is therefore *not* rejected here — a card renders `reason`
+		* either way — but every reader must narrow it with
+		* `isWorkBuddySignedOutReasonCode` before branching on it, since the wire
+		* value is not guaranteed to be inside the enum.
 		*/
 		function isWorkBuddyWebStatus(value) {
 			if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
@@ -67,7 +87,9 @@ window.__ModuleLoader__.load({
 			introKey: "intro",
 			signedOutKey: "signedOutHint",
 			statusPath: WORKBUDDY_STATUS_PATH,
-			probePath: WORKBUDDY_PROBE_PATH
+			probePath: WORKBUDDY_PROBE_PATH,
+			appName: "WorkBuddy",
+			unavailableKey: "assistUnavailableCN"
 		};
 		/** International WorkBuddy AI. */
 		const AI_CARD_VARIANT = {
@@ -76,11 +98,119 @@ window.__ModuleLoader__.load({
 			introKey: "introAI",
 			signedOutKey: "signedOutHintAI",
 			statusPath: WORKBUDDY_AI_STATUS_PATH,
-			probePath: WORKBUDDY_AI_PROBE_PATH
+			probePath: WORKBUDDY_AI_PROBE_PATH,
+			appName: "WorkBuddy AI",
+			unavailableKey: "assistUnavailableAI"
 		};
 		/** Both cards, in display order. */
 		const CARD_VARIANTS = [CN_CARD_VARIANT, AI_CARD_VARIANT];
 		const POLL_INTERVAL_MS = 6e4;
+		/**
+		* The reason codes whose failures the Agent assist block covers: the plugin
+		* cannot reach a decryption program, for any of the five reasons in §5.5.
+		*
+		* This is the *only* place the card decides whether the block applies. It
+		* branches on the code, never on `reason` text: the prose is written for a
+		* human and is expected to change, so matching it would silently stop
+		* matching after any wording edit.
+		*
+		* `encrypted-credential-unreadable` is deliberately absent — the app was found
+		* and ran, so "look for the app" is not the fix for it.
+		*/
+		const ASSIST_REASON_CODES = [
+			"electron-binary-not-found",
+			"electron-binary-ambiguous",
+			"electron-binary-unavailable",
+			"electron-path-invalid",
+			"electron-discovery-incomplete"
+		];
+		/** Locale key for one failure's summary inside the Agent prompt. */
+		function assistSummaryKey(code, variant) {
+			switch (code) {
+				case "electron-binary-not-found": return "assistNotFound";
+				case "electron-binary-ambiguous": return "assistAmbiguous";
+				case "electron-discovery-incomplete": return "assistIncomplete";
+				case "electron-path-invalid": return "assistPathInvalid";
+				default: return variant.unavailableKey;
+			}
+		}
+		/** Copy text to the clipboard, reporting whether it worked. */
+		async function copyPrompt(text) {
+			try {
+				if (navigator.clipboard?.writeText === void 0) return false;
+				await navigator.clipboard.writeText(text);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+		/**
+		* The Agent assist block for a path failure: what is wrong, one copyable
+		* request, and a re-check. Rendered only for the codes above.
+		*/
+		function AssistBlock({ t, variant, code, busy, onRecheck }) {
+			const [copied, setCopied] = (0, react.useState)(false);
+			const [copyFailed, setCopyFailed] = (0, react.useState)(false);
+			const prompt = t("assistantPrompt", {
+				appName: variant.appName,
+				failureSummary: t(assistSummaryKey(code, variant))
+			});
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: assistStyle,
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h4", {
+						style: assistHeadingStyle,
+						children: t("assistantHeading")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						style: bodyStyle,
+						children: t("assistantIntro")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: assistPromptRowStyle,
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							style: assistPromptStyle,
+							children: prompt
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							style: buttonStyle$1,
+							onClick: () => {
+								(async () => {
+									const ok = await copyPrompt(prompt);
+									setCopied(ok);
+									setCopyFailed(!ok);
+								})();
+							},
+							children: t("assistantCopy")
+						})]
+					}),
+					copied ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						style: assistFeedbackStyle,
+						role: "status",
+						children: t("assistantCopied")
+					}) : null,
+					copyFailed ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						style: assistFeedbackStyle,
+						role: "status",
+						children: t("assistantCopyFailed")
+					}) : null,
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						style: bodyStyle,
+						children: t("assistantAfter")
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						style: rowStyle,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							style: buttonStyle$1,
+							disabled: busy,
+							onClick: onRecheck,
+							children: busy ? t("assistantRechecking") : t("assistantRecheck")
+						})
+					})
+				]
+			});
+		}
 		const cardStyle = {
 			overflow: "hidden",
 			border: "1px solid var(--dsw-alias-border-l2)",
@@ -225,6 +355,53 @@ window.__ModuleLoader__.load({
 			gap: 2
 		};
 		/**
+		* The Agent assist block. Sits beside the existing error line rather than
+		* replacing it: the short diagnosis stays the headline, this adds the way out.
+		*/
+		const assistStyle = {
+			display: "flex",
+			flexDirection: "column",
+			gap: 10,
+			padding: "12px 14px",
+			marginTop: 12,
+			border: "1px solid var(--dsw-alias-border-l2)",
+			borderRadius: 10,
+			background: "var(--dsw-alias-bg-layer-2, rgba(0, 0, 0, 0.04))"
+		};
+		const assistHeadingStyle = {
+			margin: 0,
+			fontSize: 14,
+			lineHeight: "20px",
+			fontWeight: 600,
+			color: "var(--dsw-alias-label-primary)"
+		};
+		const assistPromptRowStyle = {
+			display: "flex",
+			flexWrap: "wrap",
+			alignItems: "flex-start",
+			gap: 8,
+			padding: "8px 9px 8px 11px",
+			borderRadius: 7,
+			background: "var(--dsw-alias-bg-layer-1)"
+		};
+		const assistPromptStyle = {
+			flex: "1 1 220px",
+			minWidth: 0,
+			margin: 0,
+			color: "var(--dsw-alias-label-primary)",
+			fontSize: 12,
+			lineHeight: "19px",
+			whiteSpace: "pre-wrap",
+			overflowWrap: "anywhere",
+			userSelect: "text"
+		};
+		const assistFeedbackStyle = {
+			margin: 0,
+			fontSize: 12,
+			lineHeight: "19px",
+			color: "var(--dsw-alias-label-secondary)"
+		};
+		/**
 		* Left half of one merged context/visibility row: the visibility checkbox (when
 		* the account has one) beside the model's name and rate. Kept as a flex span so
 		* the capacity column stays flush right no matter how long the name runs.
@@ -987,6 +1164,13 @@ window.__ModuleLoader__.load({
 				});
 			}, [control]);
 			const title = t(variant.titleKey);
+			/**
+			* The failure the assist block covers, when this document has one. Computed
+			* once so the block and the header's refresh button agree on whether the
+			* block owns the re-check action — showing both would put two buttons with
+			* the same effect side by side.
+			*/
+			const assistCode = status?.status === "signed-out" && isWorkBuddySignedOutReasonCode(status.reasonCode) && ASSIST_REASON_CODES.includes(status.reasonCode) ? status.reasonCode : void 0;
 			const label = status === void 0 ? t("loading") : status.status === "signed-in" ? status.nickname === void 0 ? t("signedInAs", { nickname: "" }).trimEnd().replace(/[:：]$/, "") : t("signedInAs", { nickname: status.nickname }) : status.status === "error" ? t("requestFailed") : t("signedOut");
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
 				style: cardStyle,
@@ -1032,7 +1216,7 @@ window.__ModuleLoader__.load({
 									"aria-hidden": "true",
 									style: dotStyle(status === void 0 ? "loading" : status.status)
 								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: label })]
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							}), assistCode === void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
 								style: buttonStyle$1,
 								disabled: busy,
@@ -1040,7 +1224,7 @@ window.__ModuleLoader__.load({
 									manualRefresh();
 								},
 								children: busy ? t("refreshing") : t("refresh")
-							})]
+							}) : null]
 						}),
 						readFailure === void 0 || signedIn === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 							style: errorStyle,
@@ -1178,10 +1362,18 @@ window.__ModuleLoader__.load({
 								})]
 							})
 						] }) : null,
-						status?.status === "signed-out" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						status?.status === "signed-out" ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 							style: status.reason === void 0 ? bodyStyle : errorStyle,
 							children: status.reason ?? t(variant.signedOutKey)
-						}) : null,
+						}), assistCode === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AssistBlock, {
+							t,
+							variant,
+							code: assistCode,
+							busy,
+							onRecheck: () => {
+								manualRefresh();
+							}
+						})] }) : null,
 						status?.status === "error" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 							style: errorStyle,
 							children: status.message
@@ -1745,7 +1937,22 @@ window.__ModuleLoader__.load({
 			probeResultUnknown: "Detection did not complete",
 			probeResultAt: "Detected {time}",
 			probeResultEmpty: "No detectable models right now.",
-			probeFailed: "Detection failed: {message}"
+			probeFailed: "Detection failed: {message}",
+			assistantHeading: "Let an Agent sort this out",
+			assistantIntro: "Send the request below to your Agent; it will check the app location and the launch configuration for you.",
+			assistantCopy: "Copy for Agent",
+			assistantCopied: "Copied",
+			assistantCopyFailed: "Copy failed — select the text above and copy it manually",
+			assistantAfter: "When your Agent is done, come back and check again. If the DSH launch environment was changed, restart DSH first as instructed.",
+			assistantRecheck: "Done — check again",
+			assistantRechecking: "Checking…",
+			assistantPrompt: "DSH's dsh-workbuddy-connect cannot use my {appName}: {failureSummary}. Please check the actual installation location and any existing path configuration, help the plugin use it correctly, and verify recovery. If the DSH launch environment must be changed or DSH restarted, give me clear steps; do not only set an environment variable temporarily in the current shell.",
+			assistNotFound: "no usable decryption program was found",
+			assistAmbiguous: "more than one WorkBuddy copy was found and none could be chosen safely",
+			assistIncomplete: "the automatic search could not be completed",
+			assistPathInvalid: "the configured program path is not usable",
+			assistUnavailableCN: "no decryption program is configured for this platform",
+			assistUnavailableAI: "no decryption program is configured for WorkBuddy AI"
 		};
 		const zh = {
 			title: "DSH WorkBuddy Connect",
@@ -1831,7 +2038,22 @@ window.__ModuleLoader__.load({
 			probeResultUnknown: "检测未完成",
 			probeResultAt: "检测于 {time}",
 			probeResultEmpty: "当前没有可检测的模型。",
-			probeFailed: "检测失败：{message}"
+			probeFailed: "检测失败：{message}",
+			assistantHeading: "让 Agent 帮你处理",
+			assistantIntro: "把下面这段请求发给你的 Agent，它会协助检查应用位置和启动配置。",
+			assistantCopy: "复制给 Agent",
+			assistantCopied: "已复制",
+			assistantCopyFailed: "复制失败，请手动选择上方文字复制",
+			assistantAfter: "Agent 处理完成后，回到这里重新检查；如果修改了 DSH 的启动环境，请先按指引重启 DSH。",
+			assistantRecheck: "已处理，重新检查",
+			assistantRechecking: "正在检查…",
+			assistantPrompt: "DSH 的 dsh-workbuddy-connect 无法使用我的 {appName}：{failureSummary}。请帮我检查实际安装位置和已有路径配置，让插件能正确使用它，并验证恢复结果；如果需要修改 DSH 的启动环境或重启，请给我明确的操作步骤，不要只在当前 shell 临时设置环境变量。",
+			assistNotFound: "没有找到可用的解密程序",
+			assistAmbiguous: "找到了多个 WorkBuddy 副本，无法安全自动选择",
+			assistIncomplete: "自动定位未能完成",
+			assistPathInvalid: "指定的程序路径不可用",
+			assistUnavailableCN: "当前平台尚未配置解密程序",
+			assistUnavailableAI: "尚未配置 WorkBuddy AI 的解密程序"
 		};
 		//#endregion
 		//#region src/client/index.tsx

package/lib/index.d.ts

@@ -1,39 +1,65 @@
 import z from "@deepseek-ai/schemastery";
 import "@earendil-works/pi-ai";
-import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import { PiAiAdapter, PiAiAdapterOptions } from "@deepseek-ai/dsh-llm-pi-ai";
 import { Context } from "@deepseek-ai/cordis";
 import { SettingsNamespace } from "@deepseek-ai/dsh-settings";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
-//#region src/desktop-credential-protection.d.ts
+//#region src/status-paths.d.ts
 /**
- * WorkBuddy 5.6.x at-rest credential protection: classification, key
- * resolution, and field decryption for the desktop app's encrypted auth file.
- *
- * Since WorkBuddy 5.6 the desktop app encrypts `auth.accessToken` and
- * `auth.refreshToken` at rest (`buildPolicy: "fields"`, on by default), so the
- * plugin reads `{$wbEncrypted:1, envelope}` wrappers instead of token strings
- * (issues #39/#40). Everything needed to open them lives on the same machine:
- *
- * - the sealed payload (`{version:1, atRestSecretKey}`) comes from the
- *   WorkBuddy-modified Electron's private `workbuddyStorage` binding, reached
- *   by running *its own* binary once with `ELECTRON_RUN_AS_NODE=1`;
- * - `protectorKey = sha256(atRestSecretKey, utf8)` opens the envelopes with
- *   AES-256-GCM; the AAD builder below is transcribed from the app's own
- *   `buildAuthenticatedContextAad` (verified live against 5.6.2, see
- *   `docs/r3-final.js` in the working copy — not committed).
+ * Why no credential is usable, as a closed enum the browser half switches on.
  *
- * The plugin process itself can never call `_linkedBinding` (it runs in DSH's
- * Node, not the forked Electron), so the helper is spawned. The key is cached
- * in memory only, single-flight, and re-resolved when an envelope names a
- * different key id. Neither the payload, the key, nor any token is ever
- * logged; error messages carry sizes, ids, and exit codes only.
- *
- * @module dsh-workbuddy-connect/desktop-credential-protection
+ * Deliberately separate from `reason`: `reason` is free text meant for a human
+ * to read, so matching on it would break the moment the wording changes. This
+ * is the machine-readable half, and the card uses it — never a substring of
+ * `reason` — to decide whether the Agent assist block applies.
  */
+type WorkBuddySignedOutReasonCode =
+/** Nobody is signed in; nothing diagnosable beyond that. */
+'no-credential' |
+/** A credential for the *other* product was found in this variant's file. */
+'credential-region-mismatch' |
+/** An encrypted credential exists but could not be opened (wrong key, GCM failure, helper crash). */
+'encrypted-credential-unreadable' |
+/** CN/macOS: discovery ran to completion and produced no usable candidate. */
+'electron-binary-not-found' |
+/** CN/macOS: discovery found more than one distinct usable app. */
+'electron-binary-ambiguous' |
+/** No auto-discovery for this product/platform and no explicit path configured. */
+'electron-binary-unavailable' |
+/** An explicit path (option or env) is set but missing or not executable. */
+'electron-path-invalid' |
+/** Discovery could not finish: tool missing, timeout, output overflow, unreadable plist. */
+'electron-discovery-incomplete';
+//#endregion
+//#region src/desktop-credential-protection.d.ts
 /** The four states a desktop auth document can be read as. */
 type DesktopAuthFormat = 'absent' | 'plaintext' | 'encrypted' | 'unrecognized';
 /** The spawned helper. Separated from the provider so tests can stand it in. */
 type WorkBuddyKeyPayloadSource = () => Promise<string>;
+/**
+ * Which automatic discovery, if any, this provider may run when no explicit
+ * binary is configured.
+ *
+ * `none` is the safe default: a provider that has not been told which product
+ * it serves must not reach for another product's app. `macos-workbuddy` is the
+ * CN line — the only one whose at-rest credentials and app layout have been
+ * verified live — and resolves the platform default and then Spotlight.
+ */
+type WorkBuddyElectronDiscovery = 'none' | 'macos-workbuddy';
+/** Seams the discovery flow runs through, so tests never spawn a process. */
+interface WorkBuddyDiscoveryTools {
+  /** Candidate `.app` bundles for the CN bundle id, or a throw for an unusable tool. */
+  findApps: (signal: AbortSignal) => Promise<readonly string[]>;
+  /**
+   * `CFBundleIdentifier` of a bundle, or `undefined` when the tool could not
+   * read it — which is "we could not check this candidate", never "it does not
+   * match". A successful read of a *different* id returns that id, and the
+   * caller excludes the candidate.
+   */
+  bundleIdentifier: (bundlePath: string, signal: AbortSignal) => Promise<string | undefined>;
+  /** Display version, best effort; `undefined` when unavailable. */
+  bundleVersion: (bundlePath: string, signal: AbortSignal) => Promise<string | undefined>;
+}
 /** Provider options. */
 interface WorkBuddyAtRestKeyProviderOptions {
   /** Explicit Electron binary; overrides the platform default and env. */
@@ -43,23 +69,76 @@ interface WorkBuddyAtRestKeyProviderOptions {
   /**
    * Where the payload comes from. Defaults to spawning WorkBuddy's own
    * Electron with `ELECTRON_RUN_AS_NODE=1`; tests supply a stand-in so no
-   * test ever touches the real binary or a real key.
+   * test ever touches the real binary or a real key. Supplying this replaces
+   * path *resolution* too, so tests about resolution use
+   * {@link spawnHelper} instead.
    */
   source?: WorkBuddyKeyPayloadSource;
+  /**
+   * Runs the helper at the resolved path. Distinct from {@link source}, which
+   * replaces the whole payload path: this seam keeps resolution — explicit
+   * config, platform default, discovery — real, so tests can exercise it
+   * without spawning anything.
+   */
+  spawnHelper?: (electronPath: string) => Promise<string>;
+  /**
+   * Automatic discovery budget; defaults to `'none'` (see
+   * {@link WorkBuddyElectronDiscovery}). Passed explicitly per variant at the
+   * composition root, never inferred from the environment.
+   */
+  discovery?: WorkBuddyElectronDiscovery;
+  /**
+   * Platform default binary, consulted only when `discovery` is enabled and no
+   * explicit path is configured. Injectable so tests can force the fallback
+   * branch without moving the real app; `null` means "no default here".
+   */
+  defaultElectronPath?: string | undefined;
+  /** Discovery subprocesses; injectable so tests never spawn. */
+  tools?: WorkBuddyDiscoveryTools;
+  /**
+   * Total budget for one discovery run, covering the search and every
+   * candidate check. Injectable so tests can exercise exhaustion without
+   * waiting out the production 10s.
+   */
+  discoveryBudgetMs?: number;
 }
 /**
  * In-memory protector-key resolver: one spawn per key id, single-flight, never
  * persisted. The cache is keyed by the id envelopes ask for, so an envelope
  * sealed under a rotated key triggers exactly one fresh resolution.
- */
-declare class WorkBuddyAtRestKeyProvider {
-  private readonly electronPath;
+ */ declare class WorkBuddyAtRestKeyProvider {
+  /**
+   * The explicit binary, when one was configured. `undefined` here means "the
+   * caller did not name one", which is what lets discovery run — an explicit
+   * path that turns out to be unusable is an error, never a reason to look for
+   * a different app.
+   */
+  private readonly explicitPath;
+  private readonly defaultPath;
+  private readonly discovery;
+  private readonly tools;
+  private readonly discoveryBudgetMs;
   private readonly timeoutMs;
   private readonly source;
+  private readonly spawnHelper;
+  /**
+   * The path discovery settled on, cached only on success. A failure leaves
+   * this unset so the next attempt tries again — the user may install or move
+   * the app without restarting DSH.
+   */
+  private discoveredPath;
   private cache;
   private inflight;
   constructor(options?: WorkBuddyAtRestKeyProviderOptions);
-  /** The binary the default helper would use, for diagnostics. */
+  /**
+   * The binary the default helper would use, for diagnostics.
+   *
+   * Reports a *discovery result* once one exists, so diagnostics describe what
+   * would actually run rather than the default that was bypassed. Discovery
+   * itself stays in {@link resolveElectronPath}: this accessor never triggers a
+   * search (the constructor must remain I/O-free, and callers may ask before
+   * any resolution has happened).
+   */
   helperPath(): string | undefined;
   /**
    * A protector key matching one of the requested envelope key ids. The first
@@ -70,7 +149,25 @@ declare class WorkBuddyAtRestKeyProvider {
    */
   protectorKeyFor(requested: readonly string[]): Promise<Buffer>;
   private ingest;
+  /**
+   * The binary to spawn, or a diagnosable error saying why there is none.
+   *
+   * Order is the contract: an explicit path is used as-is and never falls back;
+   * discovery runs only for a provider that was configured for it, and only
+   * after the platform default has been tried and found unusable.
+   */
+  private resolveElectronPath;
+  /**
+   * Resolve the CN app through Spotlight, then prove each candidate's identity
+   * before it can be executed.
+   *
+   * The whole flow shares one budget: a hang in one candidate must not extend
+   * the wait for the others, and running out of budget is reported as an
+   * unfinished check rather than an absent app.
+   */
+  private discoverMacosApp;
   private spawnPayload;
+  private spawnAt;
 }
 //#endregion
 //#region src/app-version.d.ts
@@ -726,6 +823,11 @@ interface WorkBuddyAuthStatus {
    * Present only on `signed-out`, and never a substitute for fixing the file.
    */
   reason?: string;
+  /**
+   * Machine-readable companion to {@link reason}, for callers that must branch
+   * on the cause. Never derived by matching `reason` text.
+   */
+  reasonCode?: WorkBuddySignedOutReasonCode;
 }
 /** Constructor options; only {@link refresh} is required. */
 interface WorkBuddyStoreOptions {
@@ -1104,6 +1206,8 @@ interface WorkBuddyAdapterOptions {
   catalog: WorkBuddyCatalog;
   /** Resolve the durable attachment service at request time, when present. */
   resolveAttachments?: () => AttachmentStore | undefined;
+  /** Resolve one image's path in the current model-tool execution world. */
+  resolveImageAccess?: NonNullable<PiAiAdapterOptions['resolveImageAccess']>;
   /**
    * Look up a local probe observation for a model. Consulted only for rows the
    * upstream left undeclared; absent means declared-set-only behavior.
@@ -1362,8 +1466,9 @@ declare function readHostHeartbeat(): Promise<WorkBuddyHostHeartbeat | undefined
  * - macOS / Linux: `ps -o lstart=` prints a local-time "EEE MMM DD HH:MM:SS YYYY";
  *   `Date.parse` resolves it against the local clock, which matches how
  *   `registeredAt` (a `Date.now()` absolute value) is expressed.
- * - Windows: WMI `CreationDate` is UTC (`YYYYMMDDHHMMSS.mmm+zzzz`); parsed with
- *   `Date.UTC`, again comparable to `registeredAt`.
+ * - Windows: `wmic` prints a CIM_DATETIME `CreationDate` — local fields plus a
+ *   signed minute offset (see {@link parseWmiCreationDate}); the epoch it
+ *   yields is comparable to `registeredAt`.
  *
  * Failures return `undefined` so callers can fall back to plain PID liveness
  * rather than mis-report a running host as dead.

package/lib/index.js

@@ -1,12 +1,12 @@
-import { A as normalizeCredits, B as chatUserAgent, C as desktopAuthCandidatesFor, D as WorkBuddyUpstreamClient, E as WorkBuddyAtRestKeyProvider, F as PROBE_EFFORT_CANDIDATES, G as WORKBUDDY_APP_VERSION_FILENAME, H as readCliVersion, I as probeModel, J as readBundleVersion, K as appUserAgent, L as randomSentinel, M as prepareChatBody, N as prepareInternationalChatBody, O as classifyUpstreamError, P as regionOf, R as CN_APP_VERSION_FILENAME, S as defaultDesktopAuthPath, T as workbuddyOwnAuthPath, U as resolveChatIdentity, V as fallbackChatIdentity, W as validCliVersion, X as validAppVersion, Y as resolveAppVersion, _ as WorkBuddyCatalog, a as WORKBUDDY_HOST_HEARTBEAT_FILENAME, b as WorkBuddyCredentialStore, c as processStartTimeMs, d as writeHostHeartbeat, f as WORKBUDDY_CONNECT_VERSION, g as FALLBACK_WORKBUDDY_MODELS, h as FALLBACK_WORKBUDDY_AI_MODELS, i as variantFor, j as parseModelCatalog, k as modelWithCurrentPromotion, l as readHostHeartbeat, n as CN_VARIANT, o as clearHostHeartbeat, q as installedAppVersion, r as WORKBUDDY_VARIANTS, s as isHeartbeatProcessAlive, t as AI_VARIANT, u as workbuddyHostHeartbeatPath, v as WORKBUDDY_AUTH_FILENAME, w as parseWorkBuddyAuth, x as defaultDesktopAuthCandidates, y as WORKBUDDY_AUTH_FILE_ENV, z as FALLBACK_CN_APP_VERSION } from "./variants-CnrmSn0Q.js";
+import { A as normalizeCredits, B as chatUserAgent, C as desktopAuthCandidatesFor, D as WorkBuddyUpstreamClient, E as WorkBuddyAtRestKeyProvider, F as PROBE_EFFORT_CANDIDATES, G as WORKBUDDY_APP_VERSION_FILENAME, H as readCliVersion, I as probeModel, J as readBundleVersion, K as appUserAgent, L as randomSentinel, M as prepareChatBody, N as prepareInternationalChatBody, O as classifyUpstreamError, P as regionOf, R as CN_APP_VERSION_FILENAME, S as defaultDesktopAuthPath, T as workbuddyOwnAuthPath, U as resolveChatIdentity, V as fallbackChatIdentity, W as validCliVersion, X as validAppVersion, Y as resolveAppVersion, _ as WorkBuddyCatalog, a as WORKBUDDY_HOST_HEARTBEAT_FILENAME, b as WorkBuddyCredentialStore, c as processStartTimeMs, d as writeHostHeartbeat, f as WORKBUDDY_CONNECT_VERSION, g as FALLBACK_WORKBUDDY_MODELS, h as FALLBACK_WORKBUDDY_AI_MODELS, i as variantFor, j as parseModelCatalog, k as modelWithCurrentPromotion, l as readHostHeartbeat, n as CN_VARIANT, o as clearHostHeartbeat, q as installedAppVersion, r as WORKBUDDY_VARIANTS, s as isHeartbeatProcessAlive, t as AI_VARIANT, u as workbuddyHostHeartbeatPath, v as WORKBUDDY_AUTH_FILENAME, w as parseWorkBuddyAuth, x as defaultDesktopAuthCandidates, y as WORKBUDDY_AUTH_FILE_ENV, z as FALLBACK_CN_APP_VERSION } from "./variants-B3Pa4EBr.js";
 import z from "@deepseek-ai/schemastery";
+import { resolveImageAttachmentAccess, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { dirname, join, resolve } from "node:path";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { createProvider } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
-import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
@@ -328,6 +328,7 @@ const NO_COST = {
 */
 function withLegacyImageBudget(store) {
 	return new Proxy(store, { get(target, property, receiver) {
+		if (property === "imageHostPath") return target.imageHostPath.bind(target);
 		if (property !== "readImageRequest") return Reflect.get(target, property, receiver);
 		return (...args) => {
 			const [ref, policy, signal] = args;
@@ -458,7 +459,7 @@ function toPiModel(info, baseUrl, observed, providerId = WORKBUDDY_PROVIDER) {
 * `modelErrors` since 0.1.5-alpha.2 (#12).
 */
 function createWorkBuddyAdapter(options) {
-	const { shim, store, catalog, resolveAttachments, observe, hidden } = options;
+	const { shim, store, catalog, resolveAttachments, resolveImageAccess, observe, hidden } = options;
 	const providerId = options.providerId ?? "workbuddy";
 	const displayName = options.displayName ?? "WorkBuddy";
 	const buildModels = () => {
@@ -503,7 +504,8 @@ function createWorkBuddyAdapter(options) {
 			...resolveAttachments === void 0 ? {} : { resolveAttachments: () => {
 				const store = resolveAttachments();
 				return store === void 0 ? void 0 : withLegacyImageBudget(store);
-			} }
+			} },
+			...resolveImageAccess === void 0 ? {} : { resolveImageAccess }
 		}),
 		invalidate: () => {
 			profiles = /* @__PURE__ */ new Map([[providerId, profile]]);
@@ -1170,7 +1172,8 @@ async function workBuddyWebStatus(deps) {
 	const authStatus = await deps.store.status();
 	if (authStatus.state !== "signed-in") return {
 		status: "signed-out",
-		...authStatus.reason === void 0 ? {} : { reason: authStatus.reason }
+		...authStatus.reason === void 0 ? {} : { reason: authStatus.reason },
+		...authStatus.reasonCode === void 0 ? {} : { reasonCode: authStatus.reasonCode }
 	};
 	const status = {
 		status: "signed-in",
@@ -1706,6 +1709,7 @@ async function startVariant(ctx, runtime) {
 			store,
 			catalog,
 			resolveAttachments: () => ctx.get("attachments"),
+			resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, (hostPath) => ctx.get("fs")?.processPathFromHostPath(hostPath), ref),
 			observe: (modelId) => probeService.recordFor(modelId),
 			hidden: () => {
 				const account = runtime.account();
@@ -1762,8 +1766,8 @@ function apply(ctx, config) {
 	* case that must not fall back to a shared preference bucket.
 	*/
 	const lastAccounts = /* @__PURE__ */ new Map();
-	const atRestKeys = new WorkBuddyAtRestKeyProvider();
-	const runtimes = WORKBUDDY_VARIANTS.map((variant) => createVariantRuntime(config, variant, () => current(), (id) => lastIdentities.get(id), (id) => lastAccounts.get(id), atRestKeys));
+	const atRestKeysFor = (variant) => new WorkBuddyAtRestKeyProvider({ discovery: variant.id === CN_VARIANT.id ? "macos-workbuddy" : "none" });
+	const runtimes = WORKBUDDY_VARIANTS.map((variant) => createVariantRuntime(config, variant, () => current(), (id) => lastIdentities.get(id), (id) => lastAccounts.get(id), atRestKeysFor(variant)));
 	const probeKey = createProbeKey();
 	let setMaximumContextWindow;
 	/**

package/lib/{variants-CnrmSn0Q.js → variants-B3Pa4EBr.js}

@@ -5,7 +5,7 @@ import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { execFile, execFileSync } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
 //#region src/app-version.ts
 /**
 * The international desktop app's version, used as the `/v3/config` UA.
@@ -1389,10 +1389,11 @@ function prepareInternationalChatBody(source) {
 		return prepared;
 	}
 	if (!isObject(body)) return prepared;
+	dropUnsupportedEffort(body);
 	const messages = body["messages"];
-	if (!Array.isArray(messages)) return prepared;
+	if (!Array.isArray(messages)) return JSON.stringify(body);
 	const first = messages[0];
-	if (isObject(first) && first["role"] === "system") return prepared;
+	if (isObject(first) && first["role"] === "system") return JSON.stringify(body);
 	messages.unshift({
 		role: "system",
 		content: INTERNATIONAL_SYSTEM_PROMPT
@@ -1400,6 +1401,30 @@ function prepareInternationalChatBody(source) {
 	return JSON.stringify(body);
 }
 /**
+* Remove the adapter's own `off` effort spelling from the **international** wire.
+*
+* `thinkingLevelMap.off` is pinned to the literal `'off'` for models that
+* declare `canDisableThinking`, so that the level stays selectable. pi-ai
+* sends that value for any request carrying no explicit level, and the
+* international endpoint rejects it on the GPT family with HTTP 400 `11133` /
+* `extError.param === 'reasoning.effort'` (issue #49). Omission is the only
+* form measured good on every such model; a literal `'none'` is *not* a safe
+* substitute — accepted by the GPT-5.6 family and GLM, rejected by
+* `gpt-6-astra`.
+*
+* Consequences, stated honestly: the international picker still offers Off,
+* but selecting it now means "the field is omitted" — the model's actual
+* behaviour is decided upstream and is *not* guaranteed to disable thinking
+* or to match the catalog's `defaultEffort`. Declared spellings
+* (`low`/`medium`/`high`/`xhigh`/`max`) and an explicit `none` pass through
+* untouched. The CN variant is deliberately unaffected: its endpoint has
+* accepted this spelling in every measurement so far, and keeping its wire
+* unchanged is a scope decision, not a claim about that endpoint's future.
+*/
+function dropUnsupportedEffort(obj) {
+	if (obj["reasoning_effort"] === "off") delete obj["reasoning_effort"];
+}
+/**
 * The system prompt injected when the international endpoint receives a body
 * with none.
 *
@@ -1636,26 +1661,145 @@ function parseAtRestPayload(text) {
 function deriveProtectorKey(secret) {
 	return createHash("sha256").update(secret, "utf8").digest();
 }
+/** The CN app's bundle id; the only one this round resolves by discovery. */
+const WORKBUDDY_CN_BUNDLE_ID = "com.tencent.workbuddy.mac";
+/** Absolute tool paths: never resolved through PATH, which a user can change. */
+const MDFIND_BIN = "/usr/bin/mdfind";
+const PLUTIL_BIN = "/usr/bin/plutil";
+/** One discovery subprocess's own limits; see {@link WorkBuddyAtRestKeyProviderOptions}. */
+const WORKBUDDY_DISCOVERY_STEP_TIMEOUT_MS = 3e3;
+const MDFIND_MAX_OUTPUT_BYTES = 1048576;
+const PLUTIL_MAX_OUTPUT_BYTES = 65536;
+/**
+* Why a discovery step could not produce an answer. Every one of these means
+* "we do not know", explicitly *not* "the candidate does not exist" — the
+* distinction is what keeps a half-finished check from being mistaken for a
+* unique candidate.
+*/
+var DiscoveryIncompleteError = class extends Error {};
+/**
+* The default discovery tools: Spotlight for the bundle, `/usr/bin/plutil` for
+* identity. Every failure that means "we could not tell" — a missing tool, a
+* timeout, an oversized answer — is raised as {@link DiscoveryIncompleteError}
+* so it can never be silently read as "no such app".
+*/
+function workBuddyDiscoveryTools() {
+	const runTool = (bin, args, maxBytes, signal) => new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(new DiscoveryIncompleteError(`${bin} was not started: the discovery budget was already spent`));
+			return;
+		}
+		let settled = false;
+		const child = execFile(bin, [...args], {
+			maxBuffer: maxBytes,
+			timeout: WORKBUDDY_DISCOVERY_STEP_TIMEOUT_MS
+		}, (error, stdout) => {
+			if (settled) return;
+			settled = true;
+			if (error !== null && error !== void 0) {
+				reject(new DiscoveryIncompleteError(`${bin} could not complete (${error.killed === true ? "timed out" : String(error.code ?? "unavailable")})`));
+				return;
+			}
+			resolve(stdout);
+		});
+		const abort = () => {
+			if (settled) return;
+			settled = true;
+			child.kill();
+			reject(new DiscoveryIncompleteError(`${bin} was abandoned: the discovery budget was spent`));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		child.on("close", () => {
+			signal.removeEventListener("abort", abort);
+		});
+	});
+	return {
+		findApps: async (signal) => {
+			return (await runTool(MDFIND_BIN, [`kMDItemCFBundleIdentifier == '${WORKBUDDY_CN_BUNDLE_ID}'`], MDFIND_MAX_OUTPUT_BYTES, signal)).split("\n").map((line) => line.trim()).filter((line) => line.endsWith(".app"));
+		},
+		bundleIdentifier: async (bundlePath, signal) => {
+			try {
+				return (await runTool(PLUTIL_BIN, [
+					"-extract",
+					"CFBundleIdentifier",
+					"raw",
+					"-o",
+					"-",
+					join(bundlePath, "Contents", "Info.plist")
+				], PLUTIL_MAX_OUTPUT_BYTES, signal)).trim();
+			} catch {
+				return;
+			}
+		},
+		bundleVersion: async (bundlePath, signal) => {
+			try {
+				const version = (await runTool(PLUTIL_BIN, [
+					"-extract",
+					"CFBundleShortVersionString",
+					"raw",
+					"-o",
+					"-",
+					join(bundlePath, "Contents", "Info.plist")
+				], PLUTIL_MAX_OUTPUT_BYTES, signal)).trim();
+				return version === "" ? void 0 : version;
+			} catch {
+				return;
+			}
+		}
+	};
+}
 /**
 * In-memory protector-key resolver: one spawn per key id, single-flight, never
 * persisted. The cache is keyed by the id envelopes ask for, so an envelope
 * sealed under a rotated key triggers exactly one fresh resolution.
-*/
-var WorkBuddyAtRestKeyProvider = class {
-	electronPath;
+*/ var WorkBuddyAtRestKeyProvider = class {
+	/**
+	* The explicit binary, when one was configured. `undefined` here means "the
+	* caller did not name one", which is what lets discovery run — an explicit
+	* path that turns out to be unusable is an error, never a reason to look for
+	* a different app.
+	*/
+	explicitPath;
+	defaultPath;
+	discovery;
+	tools;
+	discoveryBudgetMs;
 	timeoutMs;
 	source;
+	spawnHelper;
+	/**
+	* The path discovery settled on, cached only on success. A failure leaves
+	* this unset so the next attempt tries again — the user may install or move
+	* the app without restarting DSH.
+	*/
+	discoveredPath;
 	cache;
 	inflight;
 	constructor(options = {}) {
 		const fromEnv = process.env[WORKBUDDY_ELECTRON_BIN_ENV]?.trim();
-		this.electronPath = options.electronPath ?? (fromEnv !== void 0 && fromEnv !== "" ? fromEnv : void 0) ?? defaultWorkBuddyElectronPath();
+		const envPath = fromEnv === void 0 || fromEnv === "" ? void 0 : fromEnv;
+		this.explicitPath = options.electronPath ?? envPath;
+		this.discovery = options.discovery ?? "none";
+		this.defaultPath = options.defaultElectronPath === void 0 ? defaultWorkBuddyElectronPath() : options.defaultElectronPath ?? void 0;
+		this.tools = options.tools ?? workBuddyDiscoveryTools();
+		this.discoveryBudgetMs = options.discoveryBudgetMs ?? 1e4;
 		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.spawnHelper = options.spawnHelper ?? ((path) => this.spawnAt(path));
 		this.source = options.source ?? (() => this.spawnPayload());
 	}
-	/** The binary the default helper would use, for diagnostics. */
+	/**
+	* The binary the default helper would use, for diagnostics.
+	*
+	* Reports a *discovery result* once one exists, so diagnostics describe what
+	* would actually run rather than the default that was bypassed. Discovery
+	* itself stays in {@link resolveElectronPath}: this accessor never triggers a
+	* search (the constructor must remain I/O-free, and callers may ask before
+	* any resolution has happened).
+	*/
 	helperPath() {
-		return this.electronPath;
+		if (this.explicitPath !== void 0) return this.explicitPath;
+		if (this.discovery === "none") return void 0;
+		return this.discoveredPath ?? this.defaultPath;
 	}
 	/**
 	* A protector key matching one of the requested envelope key ids. The first
@@ -1665,19 +1809,19 @@ var WorkBuddyAtRestKeyProvider = class {
 	* reach will open them.
 	*/
 	async protectorKeyFor(requested) {
-		if (requested.length === 0) throw new Error("encrypted desktop credential carries no key ids");
+		if (requested.length === 0) throw new WorkBuddyElectronPathError("encrypted-credential-unreadable", "encrypted desktop credential carries no key ids");
 		const cached = this.cache;
 		if (cached !== void 0 && requested.includes(cached.keyId)) return cached.key;
 		this.inflight ??= this.source().then((text) => this.ingest(text)).finally(() => {
 			this.inflight = void 0;
 		});
 		const resolved = await this.inflight;
-		if (!requested.includes(resolved.keyId)) throw new Error(`WorkBuddy's current at-rest key (id ${resolved.keyId}) does not match the credential's envelope (id ${requested.join(" or ")}); the desktop credential was sealed by a different WorkBuddy installation`);
+		if (!requested.includes(resolved.keyId)) throw new WorkBuddyElectronPathError("encrypted-credential-unreadable", `WorkBuddy's current at-rest key (id ${resolved.keyId}) does not match the credential's envelope (id ${requested.join(" or ")}); the desktop credential was sealed by a different WorkBuddy installation`);
 		return resolved.key;
 	}
 	ingest(text) {
 		const payload = parseAtRestPayload(text);
-		if (payload === void 0) throw new Error("WorkBuddy key helper returned an unusable at-rest payload (expected {version:1, atRestSecretKey})");
+		if (payload === void 0) throw new WorkBuddyElectronPathError("encrypted-credential-unreadable", "WorkBuddy key helper returned an unusable at-rest payload (expected {version:1, atRestSecretKey})");
 		const key = deriveProtectorKey(payload.atRestSecretKey);
 		const resolved = {
 			key,
@@ -1686,14 +1830,103 @@ var WorkBuddyAtRestKeyProvider = class {
 		this.cache = resolved;
 		return resolved;
 	}
-	async spawnPayload() {
-		const electronPath = this.electronPath;
-		if (electronPath === void 0) throw new Error(`no WorkBuddy Electron binary is known for ${process.platform}; set ${WORKBUDDY_ELECTRON_BIN_ENV} to the app's Electron binary`);
+	/**
+	* The binary to spawn, or a diagnosable error saying why there is none.
+	*
+	* Order is the contract: an explicit path is used as-is and never falls back;
+	* discovery runs only for a provider that was configured for it, and only
+	* after the platform default has been tried and found unusable.
+	*/
+	async resolveElectronPath() {
+		if (this.explicitPath !== void 0) {
+			if (!isExecutable(this.explicitPath)) throw new WorkBuddyElectronPathError("electron-path-invalid", `the configured WorkBuddy Electron binary is not available at ${this.explicitPath}; check ${WORKBUDDY_ELECTRON_BIN_ENV} or unset it to let the plugin look for the app itself`);
+			return this.explicitPath;
+		}
+		if (this.discovery === "none") throw new WorkBuddyElectronPathError("electron-binary-unavailable", `no WorkBuddy Electron binary is configured for this platform; set ${WORKBUDDY_ELECTRON_BIN_ENV} to the app's Electron binary`);
+		if (this.defaultPath !== void 0 && isExecutable(this.defaultPath)) return this.defaultPath;
+		if (this.discoveredPath !== void 0) {
+			if (isExecutable(this.discoveredPath)) return this.discoveredPath;
+			this.discoveredPath = void 0;
+		}
+		const found = await this.discoverMacosApp();
+		this.discoveredPath = found;
+		return found;
+	}
+	/**
+	* Resolve the CN app through Spotlight, then prove each candidate's identity
+	* before it can be executed.
+	*
+	* The whole flow shares one budget: a hang in one candidate must not extend
+	* the wait for the others, and running out of budget is reported as an
+	* unfinished check rather than an absent app.
+	*/
+	async discoverMacosApp() {
+		if (process.platform !== "darwin") throw new WorkBuddyElectronPathError("electron-binary-unavailable", `no WorkBuddy Electron binary is configured for this platform; set ${WORKBUDDY_ELECTRON_BIN_ENV} to the app's Electron binary`);
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.discoveryBudgetMs);
 		try {
-			accessSync(electronPath, constants.X_OK);
-		} catch {
-			throw new Error(`the WorkBuddy Electron binary is not available at ${electronPath}; set ${WORKBUDDY_ELECTRON_BIN_ENV} if it lives elsewhere`);
+			let candidates;
+			try {
+				candidates = await this.tools.findApps(controller.signal);
+			} catch {
+				throw discoveryIncomplete("the app search did not complete");
+			}
+			const seen = /* @__PURE__ */ new Map();
+			let unresolved = false;
+			for (const candidate of candidates) {
+				try {
+					statSync(candidate);
+				} catch (error) {
+					if (isENOENT$1(error)) continue;
+					unresolved = true;
+					continue;
+				}
+				let bundleIdentifier;
+				try {
+					bundleIdentifier = await this.tools.bundleIdentifier(candidate, controller.signal);
+				} catch {
+					unresolved = true;
+					continue;
+				}
+				if (bundleIdentifier === void 0) {
+					unresolved = true;
+					continue;
+				}
+				if (bundleIdentifier !== "com.tencent.workbuddy.mac") continue;
+				const electronPath = join(candidate, "Contents", "MacOS", "Electron");
+				if (!isExecutable(electronPath)) continue;
+				let identity;
+				try {
+					identity = realpathSync(candidate);
+				} catch {
+					identity = candidate;
+				}
+				if (seen.has(identity)) continue;
+				let version;
+				try {
+					version = await this.tools.bundleVersion(candidate, controller.signal);
+				} catch {
+					version = void 0;
+				}
+				seen.set(identity, {
+					bundlePath: candidate,
+					electronPath,
+					...version === void 0 ? {} : { version }
+				});
+			}
+			if (seen.size > 1) throw new WorkBuddyElectronPathError("electron-binary-ambiguous", `more than one WorkBuddy application was found, so none was chosen:\n${[...seen.values()].map((app) => `  - ${app.bundlePath}${app.version === void 0 ? "" : ` (${app.version})`}`).join("\n")}\n set ${WORKBUDDY_ELECTRON_BIN_ENV} to the one to use`);
+			if (unresolved) throw discoveryIncomplete("some candidates could not be checked");
+			if (seen.size === 0) throw new WorkBuddyElectronPathError("electron-binary-not-found", "no WorkBuddy application was found in the default location or the system index; if WorkBuddy is installed elsewhere, it may not be indexed yet");
+			return [...seen.values()][0].electronPath;
+		} finally {
+			clearTimeout(timer);
+			controller.abort();
 		}
+	}
+	async spawnPayload() {
+		return await this.spawnHelper(await this.resolveElectronPath());
+	}
+	async spawnAt(electronPath) {
 		return await new Promise((resolve, reject) => {
 			execFile(electronPath, [HELPER_SCRIPT_ARGUMENT_FLAG, HELPER_SCRIPT], {
 				timeout: this.timeoutMs,
@@ -1705,13 +1938,12 @@ var WorkBuddyAtRestKeyProvider = class {
 				}
 			}, (error, stdout) => {
 				if (error !== null && error !== void 0) {
-					const reason = error.killed === true ? `timed out or was killed after ${String(this.timeoutMs)}ms` : error.code !== void 0 ? `exited with code ${String(error.code)}` : "could not be started";
-					reject(/* @__PURE__ */ new Error(`the WorkBuddy key helper (${electronPath}) ${reason}`));
+					reject(new WorkBuddyElectronPathError("encrypted-credential-unreadable", `the WorkBuddy key helper (${electronPath}) ${error.killed === true ? `timed out or was killed after ${String(this.timeoutMs)}ms` : error.code !== void 0 ? `exited with code ${String(error.code)}` : "could not be started"}`));
 					return;
 				}
 				const output = stdout.trim();
 				if (output === "") {
-					reject(/* @__PURE__ */ new Error(`the WorkBuddy key helper (${electronPath}) produced no payload`));
+					reject(new WorkBuddyElectronPathError("encrypted-credential-unreadable", `the WorkBuddy key helper (${electronPath}) produced no payload`));
 					return;
 				}
 				resolve(output);
@@ -1719,6 +1951,39 @@ var WorkBuddyAtRestKeyProvider = class {
 		});
 	}
 };
+/** Whether a path exists and is executable; never throws. */
+function isExecutable(path) {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* A failure the card must be able to classify. The code travels with the error
+* so the store can promote it to `reasonCode` without re-deriving the cause
+* from prose.
+*/
+var WorkBuddyElectronPathError = class extends Error {
+	reasonCode;
+	constructor(reasonCode, message) {
+		super(message);
+		this.name = "WorkBuddyElectronPathError";
+		this.reasonCode = reasonCode;
+	}
+};
+/** Read the reason code off an arbitrary thrown value, when it carries one. */
+function reasonCodeOf(error) {
+	return error instanceof WorkBuddyElectronPathError ? error.reasonCode : void 0;
+}
+/** Whether a filesystem error reports an absent path (`existsSync` cannot tell). */
+function isENOENT$1(error) {
+	return error?.code === "ENOENT";
+}
+function discoveryIncomplete(detail) {
+	return new WorkBuddyElectronPathError("electron-discovery-incomplete", `the WorkBuddy application search did not finish (${detail}); this is not proof that the app is missing`);
+}
 /**
 * The helper: run inside WorkBuddy's Electron as plain Node, where the
 * private `workbuddyStorage` binding exists, and print only the payload. It
@@ -1971,7 +2236,7 @@ var WorkBuddyCredentialStore = class {
 		if (this.variant !== void 0) for (const [label, credential] of [["desktop file", desktop], ["plugin copy", own]]) {
 			if (credential === void 0) continue;
 			const region = regionOf(credential.domain);
-			if (region !== this.variant.region) throw new Error(`${this.variant.displayName} received a ${region === "cn" ? "WorkBuddy (CN)" : "WorkBuddy AI"} credential in its ${label} (domain ${JSON.stringify(credential.domain)}); point ${this.variant.env} at the ${this.variant.appName} sign-in, or remove the mismatched file`);
+			if (region !== this.variant.region) throw new WorkBuddyElectronPathError("credential-region-mismatch", `${this.variant.displayName} received a ${region === "cn" ? "WorkBuddy (CN)" : "WorkBuddy AI"} credential in its ${label} (domain ${JSON.stringify(credential.domain)}); point ${this.variant.env} at the ${this.variant.appName} sign-in, or remove the mismatched file`);
 		}
 		if (desktop === void 0) return own;
 		if (own === void 0) return desktop;
@@ -2000,7 +2265,10 @@ var WorkBuddyCredentialStore = class {
 	async status() {
 		try {
 			const credential = await this.current();
-			if (credential === void 0) return { state: "signed-out" };
+			if (credential === void 0) return {
+				state: "signed-out",
+				reasonCode: "no-credential"
+			};
 			return {
 				state: "signed-in",
 				expiresAtMs: credential.expiresAtMs,
@@ -2012,7 +2280,8 @@ var WorkBuddyCredentialStore = class {
 		} catch (error) {
 			return {
 				state: "signed-out",
-				reason: error instanceof Error ? error.message : String(error)
+				reason: error instanceof Error ? error.message : String(error),
+				...reasonCodeOf(error) === void 0 ? {} : { reasonCode: reasonCodeOf(error) }
 			};
 		}
 	}
@@ -2092,7 +2361,7 @@ var WorkBuddyCredentialStore = class {
 		const key = await this.keyProvider.protectorKeyFor(keyIdsOf(wrapped.fields));
 		return parseWorkBuddyAuth(unwrapDesktopAuthDocument(classification, (field) => {
 			const plaintext = openAuthField(key, field.envelope);
-			if (plaintext === void 0) throw new Error(`the encrypted desktop credential's ${field.field} could not be decrypted (envelope key id ${field.envelope.keyId}); the WorkBuddy app may hold a different at-rest key — open it once to reseal the sign-in`);
+			if (plaintext === void 0) throw new WorkBuddyElectronPathError("encrypted-credential-unreadable", `the encrypted desktop credential's ${field.field} could not be decrypted (envelope key id ${field.envelope.keyId}); the WorkBuddy app may hold a different at-rest key — open it once to reseal the sign-in`);
 			return plaintext;
 		}));
 	}
@@ -2960,7 +3229,7 @@ const WORKBUDDY_AI_STATUS_PATH = "/plugins/dsh-workbuddy-connect/ai/status";
 const WORKBUDDY_AI_PROBE_PATH = "/plugins/dsh-workbuddy-connect/ai/probe";
 //#endregion
 //#region src/version.ts
-const WORKBUDDY_CONNECT_VERSION = "0.6.0";
+const WORKBUDDY_CONNECT_VERSION = "0.6.2";
 //#endregion
 //#region src/host-heartbeat.ts
 /**
@@ -3026,14 +3295,44 @@ async function readHostHeartbeat() {
 	} catch {}
 }
 /**
+* Parse a WMI `CreationDate` (CIM_DATETIME) into epoch milliseconds; returns
+* `undefined` for anything that does not match the format, never throws.
+*
+* The CIM_DATETIME layout is `yyyymmddHHMMSS.mmmmmmsUUU`: local wall-clock
+* fields, a 6-digit microsecond fraction, and a **3-digit signed UTC offset
+* in minutes** (`+000`, `+480` for UTC+8, `-300` for UTC−5). The fields are
+* therefore *not* UTC — the offset must be subtracted to obtain the epoch:
+* `+480` means local time runs 480 minutes ahead of UTC, so
+* `20260923104314.239907+480` is `2026-09-23T02:43:14.000Z`. A 4-digit offset
+* is not part of the format and is rejected rather than partially matched.
+*/
+function parseWmiCreationDate(value) {
+	const m = value.trim().match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d+)([+-]\d{3})$/);
+	if (m === null) return void 0;
+	const [, y, mo, d, h, mi, s, , offset] = m;
+	const [year, month, day, hour, minute, second] = [
+		y,
+		mo,
+		d,
+		h,
+		mi,
+		s
+	].map(Number);
+	if (month < 1 || month > 12 || day < 1 || day > 31) return void 0;
+	if (hour > 23 || minute > 59 || second > 59) return void 0;
+	const epoch = Date.UTC(year, month - 1, day, hour, minute, second) - Number(offset) * 6e4;
+	return Number.isFinite(epoch) ? epoch : void 0;
+}
+/**
 * Absolute start time (epoch ms) of the process holding `pid`, or `undefined`
 * when it cannot be determined (no such PID, platform lacks a readable source).
 *
 * - macOS / Linux: `ps -o lstart=` prints a local-time "EEE MMM DD HH:MM:SS YYYY";
 *   `Date.parse` resolves it against the local clock, which matches how
 *   `registeredAt` (a `Date.now()` absolute value) is expressed.
-* - Windows: WMI `CreationDate` is UTC (`YYYYMMDDHHMMSS.mmm+zzzz`); parsed with
-*   `Date.UTC`, again comparable to `registeredAt`.
+* - Windows: `wmic` prints a CIM_DATETIME `CreationDate` — local fields plus a
+*   signed minute offset (see {@link parseWmiCreationDate}); the epoch it
+*   yields is comparable to `registeredAt`.
 *
 * Failures return `undefined` so callers can fall back to plain PID liveness
 * rather than mis-report a running host as dead.
@@ -3041,7 +3340,7 @@ async function readHostHeartbeat() {
 function processStartTimeMs(pid) {
 	try {
 		if (process.platform === "win32") {
-			const m = execFileSync("wmic", [
+			const token = execFileSync("wmic", [
 				"process",
 				"where",
 				`processid=${pid}`,
@@ -3050,11 +3349,9 @@ function processStartTimeMs(pid) {
 			], {
 				encoding: "utf8",
 				windowsHide: true
-			}).match(/(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.\d+([+-]\d{4})/);
-			if (m === null) return void 0;
-			const [, y, mo, d, h, mi, s] = m;
-			const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
-			return Number.isFinite(ms) ? ms : void 0;
+			}).match(/(\d{14})\.(\d+)([+-]\d{3})(?=\s|$)/)?.[0];
+			if (token === void 0) return void 0;
+			return parseWmiCreationDate(token);
 		}
 		const out = execFileSync("ps", [
 			"-o",

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-workbuddy-connect",
   "displayName": "DSH WorkBuddy Connect",
   "description": "将 WorkBuddy 桌面 App 包含的模型自动接入 DeepSeek Harness — bring WorkBuddy desktop app models into DeepSeek Harness with zero configuration.",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "author": "corrinehu",
   "keywords": [
     "dsh-plugin",