zcode-workbuddy-connect 0.0.0-stage → 1.0.0

package/skills/workbuddy-models/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: workbuddy-models
+description: Operate the WorkBuddy model provider — start/stop the local endpoint, check sign-in and remaining credit, list or refresh the model roster, and troubleshoot "model fails to respond" errors. Use when the user asks about WorkBuddy models in ZCode, the provider shows no models, a WorkBuddy model errors out, credit balance, or the login state of the WorkBuddy desktop app.
+when_to_use: The user mentions WorkBuddy, the WorkBuddy provider, a WorkBuddy model (GLM-5.3, DeepSeek-V4-Pro, Kimi-K3, MiniMax-M3, Hy3, GLM-5v-Turbo), or reports that a model from this provider fails.
+---
+
+# WorkBuddy models in ZCode
+
+This plugin exposes the models inside the **WorkBuddy desktop app** (CN) as a
+ZCode model provider. The desktop app's models are reachable only with the app's
+own login, and only through an internal API that rejects ordinary OpenAI
+clients, so a small local service translates between the two:
+
+```
+ZCode ──(OpenAI chat-completions)──▶ 127.0.0.1:39271 ──▶ copilot.tencent.com
+                                       local endpoint        (WorkBuddy)
+```
+
+The service reads the WorkBuddy desktop app's sign-in file (read-only), refreshes
+tokens into its own state directory, and runs the model roster as a provider.
+Everything lives outside the app: nothing here writes to WorkBuddy's files.
+
+## Where things are
+
+| Thing | Path |
+|---|---|
+| Service + CLI | `${ZCODE_PLUGIN_ROOT}` |
+| State (token copy, endpoint bearer, logs) | `%USERPROFILE%\.zcode-workbuddy-connect` |
+| Provider entry | `%USERPROFILE%\.zcode\v2\provider_config.json` |
+| WorkBuddy sign-in (read-only) | `%LOCALAPPDATA%\CodeBuddyExtension\Data\Public\auth\workbuddy-desktop.info` |
+
+All CLI commands below are run as `node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" <command>`.
+
+## The one thing that usually matters
+
+The provider only works while the local endpoint is running. A `SessionStart`
+hook starts it automatically, but a locked-down host can refuse a detached
+spawn, so the first check for any "model not responding" report is always:
+
+```sh
+node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" service-status
+```
+
+- **`endpoint … up (N models)`** — the service is fine; look elsewhere.
+- **`endpoint … NOT reachable`** — start it in a terminal:
+  `node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" serve`
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `serve` | Run the endpoint in the foreground (`--port` to change, default 39271) |
+| `service-status` | Is the endpoint reachable; is autostart registered |
+| `status` | Sign-in state, token expiry, remaining credit, the whole model roster |
+| `refresh` | Re-pull the model roster from the upstream |
+| `doctor` | Credentials, upstream reachability, catalog, credit — for diagnosis |
+| `setup` | Rewrite the ZCode provider entry from the live roster |
+| `install-service` / `uninstall-service` | Register/remove a logon autostart launcher |
+| `logout` | Drop the service's own token copy (the desktop app is untouched) |
+
+## Diagnosing a failure
+
+Work through these in order; each one is cheap and they are ordered by how often
+they are the cause.
+
+1. **Is the endpoint up?** `service-status`. If not reachable, start it.
+2. **Is WorkBuddy still signed in?** `doctor`. The desktop app's token expires;
+   when it does, the fix is to open the WorkBuddy app once. The plugin cannot
+   sign in on the user's behalf and must never be asked to.
+3. **Does the model still exist?** `refresh` then `status`. The upstream roster
+   changes often — models appear and disappear — so a model that worked last
+   month may simply be gone.
+4. **Is there credit left?** `status` prints the remaining credit and any
+   promotional badges. `402` from the endpoint means insufficient credit, and no
+   local fix exists.
+5. **Read the log.** `%USERPROFILE%\.zcode-workbuddy-connect\service.log` records hook
+   and startup decisions; the running service also prints to its console.
+
+## Boundaries — do not cross these
+
+- **Never write to the WorkBuddy desktop app's own files.** The sign-in file is
+  read-only input. Token refreshes go to
+  `%USERPROFILE%\.zcode-workbuddy-connect\.workbuddy-auth.json` and nowhere else; that
+  separation is what stops this plugin from breaking the desktop app's login.
+- **Never ask for or handle the user's WorkBuddy password.** The plugin reuses
+  the desktop app's existing session by design; there is no credential to type.
+- **Do not hand-edit the token** in `endpoint.json` while the service is running
+  — the service holds the bearer in memory from startup, so a hand-edited value
+  will not match and every request will 401. Change it with `--token` and
+  restart, or delete `endpoint.json` and let it regenerate.
+- **Do not "fix" a missing model by adding it to the provider config by hand.**
+  Run `setup`: it writes the roster the upstream actually reports, including the
+  per-model context window and vision flags.
+
+## Notes on behaviour worth knowing
+
+- **Reasoning models think for a long time before their first token.** The
+  endpoint emits SSE heartbeat comments during that silence so the connection
+  and the client's read timeout survive it. A long pause before the first word
+  is normal, not a hang.
+- **Tool calls are repaired in transit.** The upstream streams tool-call
+  fragments in an unusual shape (the id and function name ride on the first
+  fragment only, and the finish event repeats). The endpoint reassembles them,
+  so a client sees one clean `tool_calls` array.
+- **Prices are informational.** Rates come from the upstream roster and are
+  cached; a promotion that expires is dropped rather than left claiming a
+  discount. `rateUnknown` means the cached rate can no longer be trusted.

package/src/app-version.js

@@ -0,0 +1,119 @@
+/**
+ * Installed-App version resolution, used for the international catalog's
+ * App-shaped User-Agent. Only the CN variant is wired up in this service, so
+ * this module serves the shared validator and the fallback constant; the
+ * international probe is kept because the region gate still routes an
+ * international credential to it.
+ *
+ * @module zcode-workbuddy-connect/app-version
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { savedVersionPath } from './config.js'
+
+/** Compiled-in international fallback. */
+export const FALLBACK_APP_VERSION = '5.5.6'
+
+/**
+ * Compiled-in CN fallback for the `WorkBuddy/<v>` tokens.
+ *
+ * Observed on the CN desktop app; like the international fallback it is a
+ * shape requirement, not a currency claim — the gateway has not been observed
+ * to branch on it.
+ */
+export const FALLBACK_CN_APP_VERSION = '5.5.6'
+
+/** Basename of the international saved-version cache. */
+export const GLOBAL_APP_VERSION_FILENAME = '.workbuddy-ai-version.json'
+
+/**
+ * Whether a value is an App version that may reach a header. Tolerates a
+ * prerelease suffix and a four-part build number; anything with whitespace,
+ * CR or LF never passes — the value is interpolated into an HTTP header.
+ */
+export function validAppVersion(value) {
+  return typeof value === 'string' && /^\d{1,6}(?:\.\d{1,6}){1,3}(?:-[0-9A-Za-z.]+)?$/u.test(value)
+}
+
+/** The App-shaped User-Agent for the international catalog request. */
+export function appUserAgent(version) {
+  return `WorkBuddy AI/${version}`
+}
+
+/**
+ * Read a version out of an App manifest.
+ *
+ * Handles the three shapes actually seen in the wild: a JSON `package.json`
+ * with a `version` field, an XML `Info.plist` with `CFBundleShortVersionString`,
+ * and undefined for anything else.
+ */
+export async function readBundleVersion(path) {
+  let text
+  try {
+    text = await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+  if (text.trimStart().startsWith('{')) {
+    try {
+      const pkg = JSON.parse(text)
+      if (validAppVersion(pkg?.['version'])) return pkg['version']
+      const product = pkg?.['productVersion'] ?? pkg?.['buildVersion']
+      if (validAppVersion(product)) return product
+    } catch {
+      return undefined
+    }
+    return undefined
+  }
+  const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/u.exec(text)
+  return match !== null && validAppVersion(match[1]) ? match[1] : undefined
+}
+
+/**
+ * International App version: installed bundle → saved cache → compiled-in
+ * fallback. Never throws; a missing App or unreadable manifest degrades to
+ * the constant.
+ */
+export async function resolveAppVersion() {
+  const candidates = []
+  if (process.platform === 'darwin') {
+    candidates.push('/Applications/WorkBuddy AI.app')
+  } else if (process.platform === 'win32') {
+    const local = process.env['LOCALAPPDATA']
+    const programFiles = process.env['ProgramFiles'] ?? 'C:/Program Files'
+    if (local) candidates.push(join(local, 'Programs', 'WorkBuddy AI'))
+    candidates.push(join(programFiles, 'WorkBuddy AI'))
+  }
+  for (const root of candidates) {
+    for (const manifest of [
+      join(root, 'resources', 'app', 'package.json'),
+      join(root, 'Contents', 'Info.plist'),
+      join(root, 'package.json'),
+    ]) {
+      const version = await readBundleVersion(manifest)
+      if (version !== undefined) {
+        await rememberVersion(version)
+        return { version, root }
+      }
+    }
+  }
+  const savedPath = savedVersionPath()
+  try {
+    const saved = JSON.parse(await readFile(savedPath, 'utf8'))
+    if (validAppVersion(saved?.['version'])) return { version: saved['version'] }
+  } catch {
+    // absent or malformed cache
+  }
+  return { version: FALLBACK_APP_VERSION }
+}
+
+async function rememberVersion(version) {
+  try {
+    const savedPath = savedVersionPath()
+    await mkdir(dirname(savedPath), { recursive: true })
+    await writeFile(savedPath, `${JSON.stringify({ version, observedAt: Date.now() }, null, 2)}\n`, { mode: 0o600 })
+  } catch {
+    // Best-effort memory; not a failure.
+  }
+}

package/src/auth.js

@@ -0,0 +1,441 @@
+/**
+ * WorkBuddy credential resolution. The primary source is the WorkBuddy
+ * desktop app's own auth file, read-only; a plugin-owned copy under the
+ * service's state directory holds token refreshes so the desktop file is
+ * never written. The effective credential is whichever of the two belongs to
+ * the currently signed-in account and expires later.
+ *
+ * @module zcode-workbuddy-connect/auth
+ */
+
+import { readFile, rm, stat, writeFile, mkdir, rename } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { regionOf } from './upstream.js'
+import {
+  WorkBuddyAtRestKeyProvider,
+  WorkBuddyElectronPathError,
+  classifyDesktopAuthDocument,
+  keyIdsOf,
+  openAuthField,
+  reasonCodeOf,
+  unwrapDesktopAuthDocument,
+} from './desktop-credential-protection.js'
+
+/** Current on-disk format of the plugin-owned copy; readers reject others. */
+const OWN_FORMAT_VERSION = 1
+
+/** Basename of the desktop app's own auth file in the shared auth directory. */
+export const DESKTOP_AUTH_FILENAME = 'workbuddy-desktop.info'
+/** Basename of the international app's auth file (same directory, different app). */
+export const DESKTOP_AUTH_AI_FILENAME = 'workbuddy-desktop-ai.info'
+
+const DESKTOP_AUTH_RELATIVE_PATH = ['CodeBuddyExtension', 'Data', 'Public', 'auth', DESKTOP_AUTH_FILENAME]
+
+/** Env variable that overrides the desktop auth-file location. */
+export const WORKBUDDY_AUTH_FILE_ENV = 'WORKBUDDY_AUTH_FILE'
+/** Env variable overriding the international desktop auth-file location. */
+export const WORKBUDDY_AI_AUTH_FILE_ENV = 'WORKBUDDY_AI_AUTH_FILE'
+
+/** Normalize an expiry that may arrive in seconds or milliseconds. */
+function expiryToMs(value) {
+  if (typeof value !== 'number' || value <= 0) return 0
+  return value > 1e12 ? value : value * 1000
+}
+
+function optionalString(value) {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Platform-default candidates for one variant's auth file, in probe order.
+ * Windows probes both AppData roots: current builds write under
+ * `%LOCALAPPDATA%` (Local), older ones under `%APPDATA%` (Roaming). The two
+ * apps share the directory and differ only in basename.
+ *
+ * @param {string} desktopFilename which variant's file to look for
+ */
+export function defaultDesktopAuthCandidates(desktopFilename = DESKTOP_AUTH_FILENAME) {
+  const relative = ['CodeBuddyExtension', 'Data', 'Public', 'auth', desktopFilename]
+  const home = homedir()
+  if (process.platform === 'win32') {
+    const local = process.env['LOCALAPPDATA'] ?? join(home, 'AppData', 'Local')
+    const roaming = process.env['APPDATA'] ?? join(home, 'AppData', 'Roaming')
+    return [
+      join(local, ...relative),
+      join(roaming, ...relative),
+    ]
+  }
+  if (process.platform === 'darwin') {
+    return [join(home, 'Library', 'Application Support', ...relative)]
+  }
+  return [join(home, '.config', ...relative)]
+}
+
+/**
+ * Parse a WorkBuddy auth document in either on-disk shape: the plugin OAuth
+ * nested form `{"auth":{...},"account":{...}}` and the flat panel form.
+ * Returns undefined when the document carries no access token.
+ */
+export function parseWorkBuddyAuth(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (!isObject(parsed)) return undefined
+  let auth
+  let identity
+  if (isObject(parsed['auth'])) {
+    auth = parsed['auth']
+    identity = isObject(parsed['account']) ? parsed['account'] : {}
+  } else {
+    auth = parsed
+    identity = parsed
+  }
+  const accessToken = typeof auth['accessToken'] === 'string' ? auth['accessToken'] : ''
+  if (accessToken === '') return undefined
+  const refreshExpiresAtMs = typeof auth['refreshExpiresAt'] === 'number' ? expiryToMs(auth['refreshExpiresAt']) : undefined
+  const enterpriseId = optionalString(identity['enterpriseId'])
+  const nickname = optionalString(identity['nickname'])
+  return {
+    accessToken,
+    refreshToken: typeof auth['refreshToken'] === 'string' ? auth['refreshToken'] : '',
+    expiresAtMs: typeof auth['expiresAt'] === 'number' ? expiryToMs(auth['expiresAt']) : 0,
+    ...(refreshExpiresAtMs === undefined ? {} : { refreshExpiresAtMs }),
+    domain: optionalString(auth['domain']) ?? '',
+    uid: optionalString(identity['uid']) ?? '',
+    ...(enterpriseId === undefined ? {} : { enterpriseId }),
+    ...(nickname === undefined ? {} : { nickname }),
+    source: 'desktop',
+  }
+}
+
+/** Parse the plugin-owned copy; other versions and shapes are rejected. */
+function parseOwnDocument(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (!isObject(parsed)) return undefined
+  if (parsed['version'] !== OWN_FORMAT_VERSION) return undefined
+  if (!isObject(parsed['credential'])) return undefined
+  // The owned copy stores the normalized credential itself (camelCase
+  // `expiresAtMs`, identity fields at the top level), NOT the desktop document
+  // shape. Round-tripping through parseWorkBuddyAuth would read `expiresAt`
+  // and an `account` object, find neither, and drop uid/enterprise/nickname.
+  const stored = parsed['credential']
+  const accessToken = typeof stored['accessToken'] === 'string' ? stored['accessToken'] : ''
+  if (accessToken === '') return undefined
+  const refreshExpiresAtMs = typeof stored['refreshExpiresAtMs'] === 'number' ? stored['refreshExpiresAtMs'] : undefined
+  const enterpriseId = optionalString(stored['enterpriseId'])
+  const nickname = optionalString(stored['nickname'])
+  return {
+    accessToken,
+    refreshToken: typeof stored['refreshToken'] === 'string' ? stored['refreshToken'] : '',
+    expiresAtMs: typeof stored['expiresAtMs'] === 'number' ? stored['expiresAtMs'] : 0,
+    ...(refreshExpiresAtMs === undefined ? {} : { refreshExpiresAtMs }),
+    domain: optionalString(stored['domain']) ?? '',
+    uid: optionalString(stored['uid']) ?? '',
+    ...(enterpriseId === undefined ? {} : { enterpriseId }),
+    ...(nickname === undefined ? {} : { nickname }),
+    source: 'own',
+  }
+}
+
+function isENOENT(error) {
+  return (error?.code) === 'ENOENT'
+}
+
+/**
+ * Read-only credential store with demand-driven refresh.
+ *
+ * Refresh policy: refresh only when the access token is inside the margin (or
+ * already expired), keep the refreshed credential in the plugin-owned copy,
+ * and never write the desktop app's file. A failed refresh still returns a
+ * not-yet-expired token so an unreachable refresh endpoint does not take down
+ * a working session.
+ */
+export class WorkBuddyCredentialStore {
+  /**
+   * @param {object} options
+   * @param {(credential: object) => Promise<object>} options.refresh performs the upstream token refresh
+   * @param {string} options.ownPath plugin-owned credential copy path
+   * @param {string} [options.desktopPath] explicit desktop auth-file path
+   * @param {string} [options.desktopFilename] basename for the platform-default probe (variant selection)
+   * @param {string} [options.authFileEnv] env var overriding the desktop path (default WORKBUDDY_AUTH_FILE)
+   * @param {string} [options.appName] display name for diagnostics ('WorkBuddy' | 'WorkBuddy AI')
+   * @param {number} [options.refreshMarginMs] refresh this long before expiry
+   * @param {{ protectorKeyFor: (requested: readonly string[]) => Promise<Buffer>, helperPath: () => string | undefined }} [options.keyProvider]
+   *        opens WorkBuddy 5.6 at-rest envelopes by spawning the app's own
+   *        Electron; injected per variant by the composition root
+   */
+  constructor(options) {
+    this.refresh = options.refresh
+    this.refreshMarginMs = options.refreshMarginMs ?? 5 * 60 * 1000
+    this.ownPath = options.ownPath
+    this.desktopPathOverride = options.desktopPath
+    this.desktopFilename = options.desktopFilename ?? DESKTOP_AUTH_FILENAME
+    this.authFileEnv = options.authFileEnv ?? WORKBUDDY_AUTH_FILE_ENV
+    this.appName = options.appName ?? 'WorkBuddy'
+    // Injected per variant by the composition root: the provider knows nothing
+    // about which product it serves, only how it was configured. The no-arg
+    // default is deliberately the safe one — no default binary, no discovery —
+    // so a store built without a provider never reaches for another product's
+    // app; it reports that no binary is configured instead.
+    this.keyProvider = options.keyProvider ?? new WorkBuddyAtRestKeyProvider()
+    this.inflight = undefined
+  }
+
+  /**
+   * Configuration precedence for the desktop file: the configured path, then
+   * the environment variable, then the platform defaults.
+   */
+  resolveDesktopCandidates() {
+    const fromEnv = process.env[this.authFileEnv]
+    const explicit = this.desktopPathOverride
+      ?? (fromEnv !== undefined && fromEnv.trim() !== '' ? fromEnv : undefined)
+    if (explicit !== undefined) return [explicit]
+    return defaultDesktopAuthCandidates(this.desktopFilename)
+  }
+
+  /** The resolved desktop auth-file path, for diagnostics. */
+  desktopAuthPath() {
+    return this.resolveDesktopCandidates()[0]
+  }
+
+  /** The plugin-owned copy path, for diagnostics. */
+  ownAuthPath() {
+    return this.ownPath
+  }
+
+  /** Read the freshest stored credential without refreshing anything. */
+  async current() {
+    const [desktop, own] = await Promise.all([this.readDesktop(), this.readOwn()])
+    if (desktop === undefined) return own
+    if (own === undefined) return desktop
+    // Identity beats expiry. The own copy is written by this service's own
+    // refreshes, so after the user switches accounts in the desktop app the
+    // copy still belongs to the *previous* account — and may well expire
+    // later, because we refreshed it. Preferring it by expiry would send the
+    // old account's uid in `X-User-Id` and answer as the wrong user. The
+    // desktop file is the authority on who is signed in now.
+    if (desktop.uid !== own.uid || desktop.enterpriseId !== own.enterpriseId) return desktop
+    return own.expiresAtMs > desktop.expiresAtMs ? own : desktop
+  }
+
+  /**
+   * The credential to send upstream: {@link current}, refreshed on demand.
+   * Single-flight, so parallel requests share one refresh.
+   */
+  async resolve() {
+    const credential = await this.current()
+    if (credential === undefined) {
+      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 ${this.appName} account found; sign in once in the ${this.appName} desktop app`
+        + ` (expected ${desktop} or ${this.authFileEnv})`,
+ )
+    }
+    if (!this.needsRefresh(credential)) return credential
+    this.inflight ??= this.refreshNow(credential).finally(() => {
+      this.inflight = undefined
+    })
+    return this.inflight
+  }
+
+  /** Read-only sign-in summary; never refreshes and never throws. */
+  async status() {
+    try {
+      const credential = await this.current()
+      if (credential === undefined) return { state: 'signed-out' }
+      return {
+        state: 'signed-in',
+        expiresAtMs: credential.expiresAtMs,
+        ...(credential.refreshExpiresAtMs === undefined ? {} : { refreshExpiresAtMs: credential.refreshExpiresAtMs }),
+        ...(credential.nickname === undefined ? {} : { nickname: credential.nickname }),
+        ...(credential.domain === '' ? {} : { domain: credential.domain }),
+        ...(credential.enterpriseId === undefined ? {} : { enterpriseId: credential.enterpriseId }),
+        uid: credential.uid,
+        region: regionOf(credential.domain),
+        source: credential.source,
+      }
+    } catch (error) {
+      // A region mismatch, an unreadable desktop file, or a failed envelope
+      // open is a *diagnosable* signed-out state, not a silent one. The reason
+      // stays human-readable; the code is the machine-readable counterpart, so
+      // a caller never has to parse the prose.
+      const reason = error instanceof Error ? error.message : String(error)
+      const reasonCode = reasonCodeOf(error)
+      return {
+        state: 'signed-out',
+        reason,
+        ...(reasonCode === undefined ? {} : { reasonCode }),
+      }
+    }
+  }
+
+  /**
+   * Classify the first desktop candidate that exists and carries content;
+   * `absent` when none does. An empty first file is skipped so it cannot mask
+   * a real document on the next candidate. Diagnostics only — it never spawns
+   * the key helper and never decrypts, so doctor can describe the file without
+   * attempting the unlock.
+   */
+  async desktopAuthFormat() {
+    for (const desktopPath of this.resolveDesktopCandidates()) {
+      let text
+      try {
+        text = await readFile(desktopPath, 'utf8')
+      } catch (error) {
+        if (!isENOENT(error)) throw error
+        continue
+      }
+      const format = classifyDesktopAuthDocument(text).format
+      if (format !== 'absent') return format
+    }
+    return 'absent'
+  }
+
+  /** The Electron binary the key helper would use; diagnostics only. */
+  keyHelperPath() {
+    return this.keyProvider.helperPath()
+  }
+
+  /** Remove the plugin-owned copy; the desktop file is untouched. */
+  async logout() {
+    await rm(this.ownPath, { force: true })
+  }
+
+  needsRefresh(credential) {
+    if (credential.expiresAtMs <= 0) return true
+    return Date.now() + this.refreshMarginMs >= credential.expiresAtMs
+  }
+
+  async refreshNow(credential) {
+    if (credential.refreshToken === '') {
+      if (credential.expiresAtMs > Date.now() + 30_000) return credential
+      throw new Error('workbuddy: access token expired and no refresh token is stored; sign in again in the WorkBuddy desktop app')
+    }
+    try {
+      const outcome = await this.refresh(credential)
+      const refreshed = {
+        ...credential,
+        accessToken: outcome.accessToken,
+        ...(outcome.refreshToken === undefined ? {} : { refreshToken: outcome.refreshToken }),
+        expiresAtMs: outcome.expiresInSec !== undefined
+          ? Date.now() + outcome.expiresInSec * 1000
+          : credential.expiresAtMs,
+        ...(outcome.domain === undefined || outcome.domain === '' ? {} : { domain: outcome.domain }),
+        source: 'own',
+      }
+      await this.saveOwn(refreshed)
+      return refreshed
+    } catch (error) {
+      if (credential.expiresAtMs > Date.now() + 30_000) return credential
+      throw new Error(
+        `workbuddy: token refresh failed and the access token is expired (${String(error)});`
+        + ' open the WorkBuddy desktop app once to sign in again',
+      )
+    }
+  }
+
+  /** Atomic write of the plugin-owned copy (temp file + rename). */
+  async saveOwn(credential) {
+    const document = { version: OWN_FORMAT_VERSION, credential }
+    await mkdir(dirname(this.ownPath), { recursive: true })
+    const temp = `${this.ownPath}.${process.pid}.tmp`
+    await writeFile(temp, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 })
+    await rename(temp, this.ownPath)
+  }
+
+  /**
+   * Read the first desktop candidate that exists. Only an absent file (ENOENT)
+   * falls through to the next candidate; a file that is present but unreadable
+   * is authoritative for its slot, so a stale older-version file never
+   * silently wins over a broken newer one.
+   *
+   * Since WorkBuddy 5.6 the token fields may arrive in at-rest envelopes, so the
+   * text is classified before the regular parser sees it. An encrypted
+   * document must be *opened*, never skipped; an unrecognized one must fail
+   * loudly. The desktop file, as long as it exists, is the identity authority —
+   * a document this plugin cannot read must surface as a diagnosis rather than
+   * be papered over by the plugin-owned copy, which belongs to whatever account
+   * was signed in when it was last refreshed. Only an absent (or empty) file
+   * lets the probe continue.
+   */
+  async readDesktop() {
+    for (const desktopPath of this.resolveDesktopCandidates()) {
+      let text
+      try {
+        text = await readFile(desktopPath, 'utf8')
+      } catch (error) {
+        if (!isENOENT(error)) throw error
+        continue
+      }
+      const classification = classifyDesktopAuthDocument(text)
+      if (classification.format === 'plaintext') return parseWorkBuddyAuth(text)
+      if (classification.format === 'absent') continue
+      if (classification.format === 'unrecognized') {
+        throw new Error(
+          `the desktop auth file at ${desktopPath} exists but is unreadable`
+          + ' (neither a plaintext credential nor a decodable WorkBuddy 5.6 envelope);'
+          + ' fix or remove the file — it outranks the plugin-owned credential copy',
+        )
+      }
+      return await this.openEncryptedDesktop(classification)
+    }
+    return undefined
+  }
+
+  /**
+   * Open a 5.6 encrypted desktop document into the regular credential shape.
+   * The rebuilt plaintext goes through the same parser a plaintext document
+   * uses, so identity and expiry need no second code path.
+   */
+  async openEncryptedDesktop(classification) {
+    const wrapped = classification.wrapped
+    const key = await this.keyProvider.protectorKeyFor(keyIdsOf(wrapped.fields))
+    const text = unwrapDesktopAuthDocument(classification, field => {
+      const plaintext = openAuthField(key, field.envelope)
+      if (plaintext === undefined) {
+        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
+    })
+    return parseWorkBuddyAuth(text)
+  }
+
+  async readOwn() {
+    try {
+      return parseOwnDocument(await readFile(this.ownPath, 'utf8'))
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Whether any desktop-file candidate exists as a regular file; diagnostics only. */
+  async desktopFilePresent() {
+    for (const desktopPath of this.resolveDesktopCandidates()) {
+      try {
+        if ((await stat(desktopPath)).isFile()) return true
+      } catch {
+        // absent or not a regular file — try the next candidate
+      }
+    }
+    return false
+  }
+}