mcp-google-multi 6.0.0-beta.2 → 6.0.0-beta.4

package/dist/doctor.js

@@ -2,16 +2,19 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { getAccountSet } from './accounts.js';
-import { deriveAccountHealth } from './tools/accounts-tool.js';
+import { accountHealthDepsFor, deriveAccountHealth } from './tools/accounts-tool.js';
+import { isOwnerContext } from './identity.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
 import { configDir, loadConfigFile } from './config-file.js';
 import { envValueSource } from './env-load.js';
+import { reauthHint } from './reauth-hint.js';
 import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
-import { probeApiEnablement } from './api-probe.js';
+import { apiProbeDepsFor, probeApiEnablement } from './api-probe.js';
 import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
+import { hints } from './hint-provider.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -32,9 +35,8 @@ const DEFAULT_DEPS = {
     probeApi: (alias) => probeApiEnablement(alias),
     probeHttp: (cfg) => probeHttpEndpoints(cfg),
 };
-/** §7 live check: the advertised OAuth metadata must derive from MCP_PUBLIC_URL
- * exactly — one mismatch between PRM `resource` / AS `issuer` and what clients
- * compute from the public URL is the perpetual-401 interop bug (BR4). */
+// §7 live check: a mismatch between PRM/AS metadata and what clients compute
+// from the public URL is the perpetual-401 interop bug.
 async function probeHttpEndpoints(cfg) {
     try {
         const prmRes = await fetch(`${cfg.publicUrl}/.well-known/oauth-protected-resource`, {
@@ -63,14 +65,27 @@ async function probeHttpEndpoints(cfg) {
         return { ok: false, unreachable: true };
     }
 }
-/** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
+/** Console deep-link to enable one API (section-6 hint). */
 export function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
 const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
-function sectionRuntime(deps) {
+function sectionRuntime(deps, tenantScope = false) {
     const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
     if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {
+        if (tenantScope) {
+            // The host version is operator infrastructure, not the tenant's: no
+            // version string, and the fix is the operator's to apply.
+            const rendered = hints()?.render({ kind: 'operator_only', slug: 'E_NODE_TOO_OLD' });
+            return {
+                id: 1,
+                title: 'Runtime',
+                verdict: 'fail',
+                slug: 'E_NODE_TOO_OLD',
+                lines: ['Runtime below the supported version'],
+                hint: rendered?.hint ?? 'Tell the server operator the code E_NODE_TOO_OLD.',
+            };
+        }
         return {
             id: 1,
             title: 'Runtime',
@@ -80,23 +95,36 @@ function sectionRuntime(deps) {
             hint: `Upgrade to Node ${MIN_NODE_MAJOR} LTS or newer.`,
         };
     }
-    return { id: 1, title: 'Runtime', verdict: 'ok', lines: [`Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`] };
+    return {
+        id: 1,
+        title: 'Runtime',
+        verdict: 'ok',
+        lines: [tenantScope ? 'Runtime ok' : `Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`],
+    };
 }
-function sectionConfig(deps, set) {
+function sectionConfig(deps, set, tenantScope = false) {
     const lines = [];
     let verdict = 'ok';
     let hint;
     let slug;
     if (!set || set.aliases.length === 0) {
+        const tenantHint = tenantScope ? (hints()?.render({ kind: 'no_accounts' })?.hint ?? '') : undefined;
         return {
             id: 2,
             title: 'Config',
             verdict: 'fail',
             slug: 'E_NO_ACCOUNTS_CONFIGURED',
             lines: ['No accounts configured.'],
-            hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.',
+            ...(tenantScope
+                ? (tenantHint ? { hint: tenantHint } : {})
+                : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
         };
     }
+    // The config file, process env, working directory and metrics store below
+    // are the operator's host, not the context's: a tenant sees its own count.
+    if (tenantScope) {
+        return { id: 2, title: 'Config', verdict: 'ok', lines: [`${set.aliases.length} account(s) configured`] };
+    }
     const cfgPath = path.join(configDir(), 'config.json');
     lines.push(deps.fileExists(cfgPath) ? `config.json present (${set.aliases.length} account(s))` : `config.json absent — accounts sourced from env (${set.aliases.length})`);
     const legacyEnv = LEGACY_ENV_KEYS.filter((k) => deps.env[k]);
@@ -121,7 +149,7 @@ function sectionConfig(deps, set) {
     return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
 }
 /** One line, state AND source, so the people being measured can see both
- * here and in `diagnose` (metrics spec section 2). Read-only. */
+ * here and in `diagnose`. Read-only. */
 export function usageMetricsStatusLine(env) {
     const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
     let configValue;
@@ -181,7 +209,8 @@ function sectionsTokensAndScopes(deps, aliases) {
             if (scopeVerdict === 'ok')
                 scopeVerdict = 'warn';
             scopeLines.push(`${alias}: ${r.callable.length} callable, ${r.requestable.length} requested-not-granted`);
-            scopeHint = `Re-auth to grant missing scopes: \`npx mcp-google-multi auth --account ${alias}\`.`;
+            const rendered = hints()?.render({ kind: 'scopes_missing', account: alias });
+            scopeHint = rendered?.hint ?? `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
         }
         else {
             scopeLines.push(`${alias}: ${r.callable.length} callable, all profile scopes granted`);
@@ -192,7 +221,7 @@ function sectionsTokensAndScopes(deps, aliases) {
         { id: 5, title: 'Scopes', verdict: scopeVerdict, lines: scopeLines, ...(scopeHint ? { hint: scopeHint } : {}), ...(scopeVerdict === 'warn' ? { slug: 'E_SCOPE_NOT_GRANTED' } : {}) },
     ];
 }
-async function sectionApiEnablement(deps, aliases) {
+async function sectionApiEnablement(deps, aliases, tenantScope = false) {
     if (!deps.probeApi) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['Probe not run (no live account probe configured).'] };
     }
@@ -209,8 +238,14 @@ async function sectionApiEnablement(deps, aliases) {
         results = await deps.probeApi(healthy);
     }
     catch (e) {
-        // Network / transient: WARN with the target, never crash the report.
-        return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
+        // Network / transient: WARN with the target, never crash the report. The
+        // raw text can name an egress or proxy host: tenant scope drops it.
+        return {
+            id: 6,
+            title: 'API enablement',
+            verdict: 'warn',
+            lines: [tenantScope ? 'Probe could not complete.' : `Probe could not complete: ${e?.message ?? e}`],
+        };
     }
     if (results.length === 0) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: [`No probeable service scopes granted on "${healthy}".`] };
@@ -218,13 +253,14 @@ async function sectionApiEnablement(deps, aliases) {
     const disabled = results.filter((r) => r.notEnabled);
     const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
     if (disabled.length > 0) {
+        const rendered = hints()?.render({ kind: 'apis_disabled', services: disabled.map((r) => ({ service: r.service, api: r.api })) });
         return {
             id: 6,
             title: 'API enablement',
             verdict: 'fail',
             slug: 'E_API_NOT_ENABLED',
             lines,
-            hint: disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
+            hint: rendered?.hint ?? disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
         };
     }
     return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
@@ -299,21 +335,27 @@ export function overallVerdict(sections) {
     }
     return worst;
 }
-export async function runDiagnostics(deps = DEFAULT_DEPS) {
+export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
+    // Tenant scope omits the OPERATOR sections (§3 key provenance, §7 owner-gate
+    // emails) and trims §2 to the context's own account count.
+    const tenantScope = opts.scope === 'tenant';
     const sections = [];
-    sections.push(sectionRuntime(deps));
+    sections.push(sectionRuntime(deps, tenantScope));
     const set = deps.accountSet();
-    sections.push(sectionConfig(deps, set));
+    sections.push(sectionConfig(deps, set, tenantScope));
     const aliases = set?.aliases ?? [];
-    sections.push(sectionKeys(deps, aliases));
+    if (!tenantScope)
+        sections.push(sectionKeys(deps, aliases));
     if (aliases.length > 0) {
         const [tokens, scopes] = sectionsTokensAndScopes(deps, aliases);
         sections.push(tokens, scopes);
-        sections.push(await sectionApiEnablement(deps, aliases));
+        sections.push(await sectionApiEnablement(deps, aliases, tenantScope));
+    }
+    if (!tenantScope) {
+        const http = await sectionHttp(deps, aliases);
+        if (http)
+            sections.push(http);
     }
-    const http = await sectionHttp(deps, aliases);
-    if (http)
-        sections.push(http);
     return { verdict: overallVerdict(sections), sections };
 }
 // --- skins -----------------------------------------------------------------
@@ -333,11 +375,35 @@ export function renderDoctorText(report) {
     out.push(`Overall: ${report.verdict.toUpperCase()}`);
     return out.join('\n');
 }
-/** Mask the local-part of an email so a report never carries a full address (BR8). */
+const EMAIL_LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
+const EMAIL_DOMAIN_CHAR = /[A-Za-z0-9.-]/;
+// A linear scan, not a regex: `local*@domain` backtracks polynomially on long
+// local-charset runs without an @ (CodeQL js/polynomial-redos).
 function maskEmails(text) {
-    return text.replace(/([A-Za-z0-9._%+-])[A-Za-z0-9._%+-]*(@[A-Za-z0-9.-]+)/g, '$1***$2');
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] === '@') {
+            let j = i + 1;
+            while (j < text.length && EMAIL_DOMAIN_CHAR.test(text[j]))
+                j += 1;
+            let k = out.length;
+            while (k > 0 && EMAIL_LOCAL_CHAR.test(out[k - 1]))
+                k -= 1;
+            if (j > i + 1 && k < out.length) {
+                // keep the first local char, mask the rest ('*' is outside the local
+                // charset, so a masked run can never be re-masked by a later @)
+                out = `${out.slice(0, k + 1)}***${text.slice(i, j)}`;
+                i = j;
+                continue;
+            }
+        }
+        out += text[i];
+        i += 1;
+    }
+    return out;
 }
-/** Redacted, paste-ready bug report (BR8): verdicts + provenance labels + token
+/** Redacted, paste-ready bug report: verdicts + provenance labels + token
  * statuses + slugs; NO token values, secrets, keys, or full email addresses. */
 export function renderReport(report, version) {
     const out = [`mcp-google-multi doctor report (v${version})`, `overall: ${report.verdict}`, ''];
@@ -356,6 +422,26 @@ export function exitCodeFor(report, strict) {
         return 1;
     return 0;
 }
+/** The engine's account, token and probe reads bound to one context, so a
+ * report never shows (or probes with) another context's accounts. */
+function diagnosticsDepsFor(ctx) {
+    const health = accountHealthDepsFor(ctx.tokenStore, () => ctx.accounts);
+    const probe = apiProbeDepsFor(ctx.tokenStore.readToken, ctx.getClient);
+    return {
+        ...DEFAULT_DEPS,
+        accountSet: () => {
+            try {
+                return ctx.accounts;
+            }
+            catch {
+                return null;
+            }
+        },
+        accountHealth: (alias) => deriveAccountHealth(alias, health),
+        anyTokensExist: (aliases) => aliases.some((a) => ctx.tokenStore.hasToken(a)),
+        probeApi: (alias) => probeApiEnablement(alias, probe),
+    };
+}
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
  * engine. Registered as a META tool, like `account_list`: it introspects this
  * server rather than Google data, and as a normal tool it became a service of
@@ -363,14 +449,18 @@ export function exitCodeFor(report, strict) {
  * from already-registered services, and this runs after that), so it was
  * advertised only once something else expanded the surface. The README sends
  * people here when they are stuck, so it has to be findable. */
-export function registerDiagnoseTool(registry) {
+export function registerDiagnoseTool(registry, ctx) {
+    // A non-owner context gets the tenant-scoped report; only the owner context
+    // (or the context-free CLI surface) keeps the full operator report.
+    const scope = ctx && !isOwnerContext(ctx) ? 'tenant' : 'operator';
+    const deps = ctx ? diagnosticsDepsFor(ctx) : DEFAULT_DEPS;
     registry.registerMeta('diagnose', {
         annotations: { readOnlyHint: true, openWorldHint: true },
         description: 'Health report for this server: runtime, config, keys, per-account token status, scope grants, and API enablement. Read-only; returns copy-pasteable fixes for anything wrong. Call this to diagnose auth/config failures.',
         inputSchema: {},
     }, async () => {
         try {
-            const result = await runDiagnostics();
+            const result = await runDiagnostics(deps, { scope });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (e) {

package/dist/env-load.js

@@ -3,11 +3,8 @@ import path from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Precedence: real env > CWD .env > package-root .env > ~/.config .env.
-// process.loadEnvFile never overwrites keys already in process.env (pinned by
-// tests/env-load.test.ts T4), so highest-priority file loads FIRST and real
-// env wins by already being present; the boot snapshot re-assert is a second
-// line of defense should those semantics ever change.
+// Precedence: real env > CWD .env > package-root .env > ~/.config .env;
+// the boot snapshot re-assert below is a second line of defense.
 export function loadEnvFiles(paths = {}) {
     // loadEnvFile exists since 20.12, so a feature check alone would let 20.12-21.x through.
     const major = Number(process.versions.node.split('.', 1)[0]);

package/dist/executor.d.ts

@@ -1,4 +1,5 @@
 import { getClient } from './client.js';
+import { type ScopeSetDeps } from './scope-observability.js';
 export declare const MAX_RESPONSE_CHARS = 100000;
 export type QueryValue = string | number | boolean;
 export type QueryParams = Record<string, QueryValue | QueryValue[]>;
@@ -13,6 +14,8 @@ export interface ApiMethodRef {
 }
 export interface ExecuteDeps {
     getClientFn?: typeof getClient;
+    /** Token + profile view behind a 403 scope hint; absent = the single owner. */
+    scopeDeps?: ScopeSetDeps;
 }
 export interface ExecuteArgs {
     account: string;

package/dist/executor.js

@@ -4,6 +4,7 @@ import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
 import { checkOutboundForMethod } from './outbound-allowlist.js';
+import { hints } from './hint-provider.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -70,10 +71,11 @@ export async function executeApiMethod(method, args, deps = {}) {
         }, true);
     }
     if (!isGoogleApiUrl(url)) {
+        const rendered = hints()?.render({ kind: 'untrusted_host' });
         return jsonResult({
             error: 'untrusted_host',
             message: `Refusing to send credentials to a non-googleapis.com host for "${method.id}".`,
-            hint: 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
+            hint: rendered?.hint ?? 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
             retriable: false,
             account: args.account,
         }, true);
@@ -89,10 +91,8 @@ export async function executeApiMethod(method, args, deps = {}) {
         });
         const text = JSON.stringify(res.data ?? null);
         if (text.length > MAX_RESPONSE_CHARS) {
-            // Budget the ENCODED head: jsonResult re-stringifies it, so every quote
-            // and backslash inside doubles. Slicing raw characters made the emitted
-            // result exceed the cap this tool advertises, by up to 15 percent on a
-            // quote-dense listing.
+            // Budget the ENCODED head: jsonResult re-stringifies it, so slicing raw
+            // characters overshot the advertised cap on a quote-dense listing.
             return jsonResult({
                 truncated: true,
                 totalChars: text.length,
@@ -103,6 +103,6 @@ export async function executeApiMethod(method, args, deps = {}) {
         return { content: [{ type: 'text', text }] };
     }
     catch (error) {
-        return handleGoogleApiError(error, args.account, undefined, () => method.scopes?.length ? scopeHintForMethod(method.scopes, args.account) : null);
+        return handleGoogleApiError(error, args.account, undefined, () => method.scopes?.length ? scopeHintForMethod(method.scopes, args.account, deps.scopeDeps) : null);
     }
 }

package/dist/fanout.d.ts

@@ -1,6 +1,14 @@
 import { z } from 'zod';
 export declare const CSV_RE: RegExp;
-export declare function fanoutAccountField(description: string): z.ZodType;
+export declare function fanoutAccountField(description: string, aliases: () => readonly string[]): z.ZodType;
+/** '*' over an empty account set would fan out to nothing and report success. */
+export declare function noAccountsResult(): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
 export type AccountSelector = {
     ok: true;
     fanout: boolean;

package/dist/fanout.js

@@ -1,28 +1,47 @@
 import { z } from 'zod';
-import { ACCOUNTS, getAccountSet, unknownAliasMessage } from './accounts.js';
+import { getAccountSet, liveAccountCheck, unknownAliasMessage } from './accounts.js';
+import { echoName, echoNames, MAX_SUGGESTED_KEYS } from './arg-strict.js';
+import { hints } from './hint-provider.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
-export function fanoutAccountField(description) {
-    const csvExample = ACCOUNTS.length > 1 ? `; or a CSV subset like "${ACCOUNTS.slice(0, 2).join(',')}"` : '';
-    // The union's OWN error only fires when every branch aborts at the type
-    // check (a non-string). For a string, zod surfaces the single non-aborted
-    // branch verbatim, which is the CSV regex, so a mistyped alias used to read
-    // as "Invalid string: must match pattern /^[a-zA-Z0-9_-]+(,...)/" and never
-    // named an alias. Hence the same message on BOTH.
-    const bad = () => unknownAliasMessage(ACCOUNTS, true);
+// `aliases` is a getter read at parse time (not baked), so a registry only
+// ever sees ITS OWN account set, and a mid-session alias (account_add) is valid on tools registered before it existed.
+export function fanoutAccountField(description, aliases) {
+    const boot = aliases();
+    const csvExample = boot.length > 1 ? `; or a CSV subset like "${boot.slice(0, 2).join(',')}"` : '';
+    // Same message on both union branches: for a string, zod surfaces the
+    // single non-aborted branch (the CSV regex) verbatim, which never named the alias.
+    const bad = () => unknownAliasMessage(aliases(), true);
     return z
-        // '*' first so the tuple is statically non-empty even when ACCOUNTS is empty
-        // (a fresh install): z.enum requires [string, ...string[]].
-        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE, { error: bad })], { error: bad })
+        // The selector branch stays first: tools/list injects the live
+        // '*' + alias enum into it (registry withLiveAccountEnum).
+        .union([z.string().check(liveAccountCheck(aliases, true)), z.string().regex(CSV_RE, { error: bad })], { error: bad })
         .optional()
         .describe(`${description}; "*" = all accounts${csvExample}; omit for the default account`);
 }
+/** '*' over an empty account set would fan out to nothing and report success. */
+export function noAccountsResult() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'validation_error',
+                    message: 'No Google account is configured, so "*" selects nothing.',
+                    hint: unknownAliasMessage([]),
+                    retriable: false,
+                    account: '*',
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
 export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
-    // A single alias used to skip validation entirely and reach getClient, whose
-    // throw landed on the mapper's floor as an unclassified upstream_error. Same
-    // check and same envelope wherever the alias was typed.
+    // A single alias used to skip validation and reach getClient, whose throw
+    // landed on the mapper's floor as an unclassified upstream_error.
     if (!value.includes(',')) {
         return accounts.includes(value)
             ? { ok: true, fanout: false, aliases: [value] }
@@ -53,10 +72,11 @@ export function invalidAccountsResult(invalid, accounts = getAccountSet().aliase
                 type: 'text',
                 text: JSON.stringify({
                     error: 'validation_error',
-                    message: `Unknown account alias(es): ${invalid.join(', ')}.`,
+                    // The caller's CSV can hold any number of tokens: echo a prefix.
+                    message: `Unknown account alias(es): ${echoNames(invalid)}.`,
                     hint: unknownAliasMessage(accounts, true),
                     retriable: false,
-                    account: invalid.join(','),
+                    account: invalid.slice(0, MAX_SUGGESTED_KEYS).map(echoName).join(','),
                 }),
             },
         ],
@@ -87,10 +107,17 @@ export async function runFanout(handler, args, aliases) {
                 results[i] = res?.isError ? { account, ok: false, error: payload } : { account, ok: true, data: payload };
             }
             catch (err) {
+                const rendered = hints()?.render({ kind: 'internal', account });
                 results[i] = {
                     account,
                     ok: false,
-                    error: { error: 'internal', message: err.message, retriable: false, account },
+                    error: {
+                        error: 'internal',
+                        message: rendered?.message ?? err.message,
+                        hint: rendered?.hint,
+                        retriable: false,
+                        account,
+                    },
                 };
             }
         }
@@ -98,10 +125,8 @@ export async function runFanout(handler, args, aliases) {
     await Promise.all(Array.from({ length: Math.min(FANOUT_CONCURRENCY, aliases.length) }, () => worker()));
     const failed = results.filter((r) => !r.ok).length;
     if (failed === results.length && results.length > 0) {
-        // Every account failed, so this IS an error result, and used to carry
-        // `isError` with no top-level error, hint or retriable: the agent saw a
-        // successful-looking object flagged as an error, and metrics bucketed it
-        // as `other`. Hoist a real envelope, keeping the per-account detail.
+        // Every account failed, so this IS an error result: hoist a real
+        // top-level envelope (error/hint/retriable), keeping the per-account detail.
         const slugs = [...new Set(results.map((r) => r.error?.error ?? 'internal'))];
         const hints = [...new Set(results.map((r) => r.error?.hint).filter(Boolean))];
         const retriable = results.every((r) => r.error?.retriable === true);

package/dist/fs-atomic.d.ts

@@ -1,3 +1,11 @@
+interface LockIdentity {
+    ns: string;
+    start: string;
+    boot: string;
+}
+/** Test hook: act as a process with this identity (undefined restores the real one). */
+export declare function __setLockIdentityForTest(identity?: LockIdentity): void;
 export declare function withFileLock<T>(absPath: string, fn: () => T, label?: string): T;
 export declare function atomicWriteFileSync(absPath: string, contents: string, mode?: number): void;
 export declare function atomicWriteWithLock(absPath: string, contents: string, mode?: number): void;
+export {};