mcp-google-multi 6.0.0-beta.3 → 6.0.0-beta.5

package/dist/config-file.js

@@ -13,9 +13,8 @@ export function configFilePath(env = process.env) {
 export function tenantsDir(env = process.env) {
     return path.join(configDir(env), 'tenants');
 }
-// A tenant id becomes a filesystem path segment exactly like an account
-// alias, so it rides the same traversal guard. 'owner' is the single-owner
-// context's subject and client lane, so no tenant may take it.
+// A tenant id becomes a filesystem path segment like an account alias (same
+// traversal guard); 'owner' is the single-owner subject, so no tenant may take it.
 function assertTenantId(tenantId) {
     if (!ALIAS_RE.test(tenantId) || isReservedAlias(tenantId) || tenantId === 'owner') {
         throw new Error(`E_TENANT_ID_INVALID: invalid tenant id "${tenantId}".`);
@@ -52,9 +51,7 @@ const accountEntrySchema = z.strictObject({
     admin: z.boolean().optional(),
 });
 // .strict() everywhere: any unknown or secret-shaped key (clientSecret,
-// masterKey, jwtKey, clientId) fails validation, structurally enforcing
-// secrets-env-only. scopeProfiles/defaultAccount/discovery/toolsets are part
-// of the frozen envelope; their consumers land in later slices.
+// masterKey, jwtKey, clientId) fails validation, structurally enforcing secrets-env-only.
 export const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
 export function isReservedAlias(name) {
     return RESERVED_ALIASES.includes(name);
@@ -72,9 +69,8 @@ const configSchema = z.strictObject({
     defaultAccount: z.string().optional(),
     discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
     toolsets: z.string().optional(),
-    // Local usage metrics (metrics-feature-spec): absent = off. Downgrade rule:
-    // a pre-6.0 build reading a config carrying this key fails E_CONFIG_INVALID
-    // (strictObject); remove the key first.
+    // Absent = off. A pre-6.0 build reading a config carrying this key fails
+    // E_CONFIG_INVALID (strictObject); remove the key first to downgrade.
     usageMetrics: z.boolean().optional(),
 });
 export function failStartup(slug, message) {
@@ -125,9 +121,8 @@ export function loadConfigFile(filePath = configFilePath(), onInvalid = 'exit')
         const issue = result.error.issues[0];
         fail('E_CONFIG_INVALID', `${filePath}: ${issue.path.join('.') || '(root)'}: ${issue.message}. Secrets never belong in config.json.`);
     }
-    // Post-schema because zod's key regex passes these; a __proto__ record key
-    // is a prototype-pollution foothold, and Object.prototype member names break
-    // plain-object lookups downstream.
+    // Post-schema: zod's key regex passes these, but a __proto__ record key is
+    // a prototype-pollution foothold downstream.
     const data = result.data;
     for (const [section, keys] of [
         ['accounts', Object.keys(data.accounts ?? {})],

package/dist/discover.js

@@ -1,9 +1,8 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
 import { hints } from './hint-provider.js';
-// The description budget is the whole point of lazy mode: a full op list per
-// service put lazy tools/list at ~11.5k tokens (RQ2), so descriptions carry a
-// CAPPED vocabulary and the complete catalog stays in this tool's RESULT.
+// The description budget is the whole point of lazy mode: descriptions carry
+// a CAPPED vocabulary, and the complete catalog stays in this tool's RESULT.
 const CURATED_OPS_CAP = 10;
 const GENERATED_GROUPS_CAP = 6;
 function opVocabulary(registry, service) {
@@ -15,8 +14,7 @@ function opVocabulary(registry, service) {
         parts.push(`${shown.join(', ')}${more > 0 ? ` +${more} more` : ''}`);
     }
     if (generated.length > 0) {
-        // The generated long tail compresses to its resource groups: denser and
-        // more selective than any truncated name list.
+        // Compresses to resource groups: denser than any truncated name list.
         const counts = new Map();
         for (const op of generated) {
             const group = op.split('_')[0];
@@ -31,10 +29,7 @@ function opVocabulary(registry, service) {
 }
 export function registerDiscoverTools(registry, policy) {
     const registerMeta = registry.registerMeta;
-    // Agent-controllable runtime expansion (D3 refinement): reveal the whole
-    // curated quality layer for heavy Google work, collapse to reclaim the
-    // name/schema context budget after. stdio-only semantics — over stateless
-    // HTTP the mode is forced curated and these are no-ops.
+    // stdio-only semantics: over stateless HTTP the mode is forced curated and these are no-ops.
     registerMeta('discover_all', {
         description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). Use when ' +
             'starting substantial Google work; prefer these over google_api_call. Pair with discover_reset.',
@@ -101,9 +96,8 @@ export function registerDiscoverTools(registry, policy) {
                             service,
                             operations,
                             writeControl: rendered?.hint ?? describePolicy(policy),
-                            next: operations.length > 0
-                                ? 'Call the chosen tool by name; it is now listed and callable.'
-                                : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,
+                            // catalog() falls back to a full one-line listing when nothing matches, so this is never empty.
+                            next: 'Call the chosen tool by its exact name. A client that loads tools on demand may need its own tool-search or load step before the call succeeds.',
                         }),
                     },
                 ],

package/dist/discovery-client.js

@@ -35,10 +35,8 @@ export const SUPPORTED_APIS = {
     vault: { id: 'vault', version: 'v1' },
     workspaceevents: { id: 'workspaceevents', version: 'v1' },
 };
-// Names agents actually type for an API, mapped to real SUPPORTED_APIS keys.
-// Motivated by observed escape-hatch misses ("analytics" is two Discovery
-// APIs, the Admin SDK is three); keep entries plural-target only when the
-// split is real.
+// Names agents actually type for an API, mapped to real SUPPORTED_APIS keys;
+// plural-target entries only where the split ("analytics" is two APIs) is real.
 export const API_ALIASES = {
     analytics: ['analyticsadmin', 'analyticsdata'],
     ga4: ['analyticsadmin', 'analyticsdata'],
@@ -74,9 +72,8 @@ export function discoveryCacheDir(env = process.env) {
     return (env.DISCOVERY_CACHE_PATH ??
         path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'mcp-google-multi', 'discovery'));
 }
-// Default cache path only (an operator's DISCOVERY_CACHE_PATH may be shared,
-// even /tmp, and keeps its mode), only when this process owns it, and best
-// effort. Clears group/other bits and keeps setuid/setgid/sticky.
+// Default cache path only (an operator's DISCOVERY_CACHE_PATH may be shared
+// and keeps its mode), only when this process owns it; clears group/other bits.
 function tightenOwnDir(dir) {
     if (process.platform === 'win32')
         return;
@@ -110,9 +107,8 @@ export function buildMethodIndex(doc, api) {
             if (!method.id || !method.httpMethod || !method.path)
                 continue;
             const params = method.parameters ?? {};
-            // Google serves parameters{} with unstable key order between fetches;
-            // parameterOrder is the canonical sequence, so sort by it (alphabetical
-            // tie-break) to keep gen-tools output deterministic.
+            // parameters{} has unstable key order between fetches; sort by the
+            // canonical parameterOrder (alphabetical tie-break) for deterministic output.
             const order = method.parameterOrder ?? [];
             const pos = (n) => {
                 const i = order.indexOf(n);
@@ -174,9 +170,8 @@ export async function loadMethodIndex(api, deps = {}) {
     if (cacheFresh())
         doc = readCache();
     if (!doc) {
-        // Newer APIs (analyticsadmin/analyticsdata) are absent from the central
-        // discovery directory (404); each service's own $discovery endpoint is
-        // authoritative, so try both — same fallback as scripts/fetch-discovery.
+        // Newer APIs are absent from the central discovery directory (404); try
+        // each service's own $discovery endpoint too, as scripts/fetch-discovery does.
         const urls = [
             `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`,
             `https://${spec.id}.googleapis.com/$discovery/rest?version=${spec.version}`,
@@ -217,20 +212,11 @@ export function clearDiscoveryMemoryCache() {
 // GA4-style report execution (runReport, batchRunPivotReports, runAccessReport)
 // and check* predicates are POSTs purely for the request-body size — reads.
 const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect|check|suggest|(batch)?run\w*report)/i;
-// `cancelWipe` must be matched here, BEFORE `cancel` reaches the delete list:
-// it calls off a pending wipe, which is the opposite of one. Update is tested
-// before delete for exactly that reason.
-// State transitions on something that already exists: reversible, and none of
-// them creates anything, so `create` was both wrong and the most permissive
-// class available. `(batch)?` mirrors the delete list, without which every
-// `batchUpdate*` POST fell through to `create`.
+// Update, tested before delete, so cancelWipe (calling off a wipe) doesn't
+// reach the delete list via its "cancel" suffix. See docs/internals.md.
 const POST_UPDATE_VERB = /^(cancelWipe|(batch)?(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format|change|close|reopen|enable|disable|hide|unhide|accept|approve|decline|reassign|reactivate|renew|mark|turn|suspend|activate|make|return|reclaim|complete))/i;
-// archive sits with the deletes: in GA4 archiving a custom dimension/metric is
-// permanent, so the most restrictive write class is the safe classification.
-// So do the teardown verbs: `stop` and `cancel` tear down a push channel or a
-// long-running operation, `wipe`/`invalidate`/`signOut` destroy device data,
-// codes and sessions, `reset` discards a configuration, and `end` terminates a
-// live conference. Each removes something that existed.
+// archive/wipe/reset/stop/cancel/end etc. all remove or permanently discard
+// something that existed, so the most restrictive class is the safe one. See docs/internals.md.
 const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive|wipe|invalidate|signOut|stop|cancel|unregister|unreserve|reset|end)/i;
 export function cudFromMethod(method) {
     switch (method.httpMethod) {
@@ -262,13 +248,8 @@ export function expandPath(template, pathParams) {
         if (value === undefined) {
             throw new Error(`Missing required path parameter "${name}"`);
         }
-        // A blank segment collapses the path and Google routes the resulting
-        // trailing-slash URL to the COLLECTION: `sites.get` with siteUrl:"" came
-        // back as the whole site LIST, reported as success. Dot segments resolve
-        // at URL-parse time, so `../v1/contactGroups` retargets the call at a
-        // different endpoint and returns ITS response as success. Both are
-        // silent-wrong, so refuse locally rather than send a different request.
-        // `{+param}` keeps its slashes, so every segment has to be checked.
+        // Both a blank segment and a "." / ".." segment silently retarget the
+        // request to a different, successfully-answered endpoint. See docs/internals.md.
         const segments = plus ? String(value).split('/') : [String(value)];
         for (const segment of segments) {
             if (segment.trim() === '') {

package/dist/doctor.d.ts

@@ -52,10 +52,10 @@ export interface HttpProbeResult {
     unreachable?: boolean;
     problem?: string;
 }
-/** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
+/** Console deep-link to enable one API (section-6 hint). */
 export declare function apiEnableLink(api: string): string;
 /** 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 declare function usageMetricsStatusLine(env: Record<string, string | undefined>): string;
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
 export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
@@ -64,7 +64,7 @@ export declare function runDiagnostics(deps?: DiagnosticsDeps, opts?: {
 }): Promise<DiagnosticsReport>;
 /** doctor CLI (brew-doctor style): glyph-coded human report. */
 export declare function renderDoctorText(report: DiagnosticsReport): string;
-/** 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 declare function renderReport(report: DiagnosticsReport, version: string): string;
 /** Exit non-zero when any section FAILs; with strict, WARN counts too. */

package/dist/doctor.js

@@ -35,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`, {
@@ -66,7 +65,7 @@ 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`;
 }
@@ -75,8 +74,8 @@ 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 (E7
-            // residue): no version string, and the fix is the operator's to apply.
+            // 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,
@@ -150,7 +149,7 @@ function sectionConfig(deps, set, tenantScope = false) {
     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;
@@ -240,8 +239,7 @@ async function sectionApiEnablement(deps, aliases, tenantScope = false) {
     }
     catch (e) {
         // Network / transient: WARN with the target, never crash the report. The
-        // raw text can name an egress or proxy host (E7 residue): tenant scope
-        // drops it.
+        // raw text can name an egress or proxy host: tenant scope drops it.
         return {
             id: 6,
             title: 'API enablement',
@@ -338,10 +336,8 @@ export function overallVerdict(sections) {
     return worst;
 }
 export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
-    // Tenant scope omits the OPERATOR sections: §3 (key provenance = box
-    // infrastructure) and §7 (its owner-gate lines print MCP_OWNER_EMAILS
-    // values — other people's addresses from a tenant's seat), and trims §2 to
-    // the context's own account count.
+    // 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, tenantScope));
@@ -381,10 +377,8 @@ export function renderDoctorText(report) {
 }
 const EMAIL_LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
 const EMAIL_DOMAIN_CHAR = /[A-Za-z0-9.-]/;
-/** Mask the local-part of an email so a report never carries a full address
- * (BR8). A linear scan, not a regex: the `local* @domain` pattern backtracks
- * polynomially on long local-charset runs without an @ (CodeQL
- * js/polynomial-redos), and report text can embed arbitrary error strings. */
+// A linear scan, not a regex: `local*@domain` backtracks polynomially on long
+// local-charset runs without an @ (CodeQL js/polynomial-redos).
 function maskEmails(text) {
     let out = '';
     let i = 0;
@@ -409,7 +403,7 @@ function maskEmails(text) {
     }
     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}`, ''];

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.js

@@ -91,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,

package/dist/fanout.js

@@ -4,19 +4,13 @@ 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;
-// `aliases` is required (no global default): the field is baked into a
-// registry's inputSchema, so it must read THAT registry's account set or a
-// '*' would advertise and accept another registry's aliases. It is a getter:
-// the set is read at parse time, so an alias added mid-session (account_add,
-// a tenant link) is valid on tools registered before it existed.
+// `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(',')}"` : '';
-    // 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.
+    // 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
         // The selector branch stays first: tools/list injects the live
@@ -46,9 +40,8 @@ export function noAccountsResult() {
 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] }
@@ -132,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,6 +1,3 @@
-/** Which process instance holds a lock: PID namespace id, start time in
- * clock ticks since boot, and a boot id prefix. A part this process cannot
- * read is `host` or `0` (all three without /proc). */
 interface LockIdentity {
     ns: string;
     start: string;

package/dist/fs-atomic.js

@@ -10,6 +10,9 @@ const RENAME_RETRY_MS = 20;
 const LOCK_LEASE_MS = 60_000;
 // Breaking a lock takes microseconds, so an older breaker file was left by a crash.
 const BREAKER_STALE_MS = 2_000;
+// The no-hard-link fallback writes the lock in two syscalls (create, then the
+// pid); a reader can catch it empty in between. See docs/internals.md.
+const LOCK_WRITE_GRACE_MS = 2_000;
 const PROCESS_START_MS = performance.timeOrigin;
 const OWNER_NAME = /^(\d+)\.(\d+|host)\.(\d+)\.([0-9a-f]{8}|0)\.[0-9a-f]{12}\.owner$/;
 function startOf(pid) {
@@ -63,11 +66,19 @@ function sameFile(a, b) {
 function isEnoent(error) {
     return error.code === 'ENOENT';
 }
+function bindingRecord(id) {
+    return `${id.dev}:${id.ino}:${id.mtimeNs}`;
+}
+function matchesBinding(content, id) {
+    const m = /^(\d+):(\d+):(\d+)$/.exec(content);
+    return m !== null && BigInt(m[1]) === id.dev && BigInt(m[2]) === id.ino && BigInt(m[3]) === id.mtimeNs;
+}
 // Undefined when the lock changed hands while it was being read.
 function readHolder(lock) {
     const before = fs.lstatSync(lock, { bigint: true });
     const body = before.isFile() ? fs.readFileSync(lock, 'utf8') : '';
     let owner;
+    let ownerPending = false;
     if (before.isFile()) {
         const dir = path.dirname(lock);
         const prefix = `${path.basename(lock)}.`;
@@ -79,10 +90,12 @@ function readHolder(lock) {
                 continue;
             const ownerPath = path.join(dir, name);
             try {
-                if (sameFile(fs.lstatSync(ownerPath, { bigint: true }), before)) {
+                const ownerStat = fs.lstatSync(ownerPath, { bigint: true });
+                if (sameFile(ownerStat, before) || matchesBinding(fs.readFileSync(ownerPath, 'utf8'), before)) {
                     owner = { path: ownerPath, ns: m[2], start: m[3], boot: m[4] };
                     break;
                 }
+                ownerPending = true;
             }
             catch (error) {
                 if (!isEnoent(error))
@@ -93,7 +106,7 @@ function readHolder(lock) {
     const after = fs.lstatSync(lock, { bigint: true });
     if (!sameFile(before, after))
         return undefined;
-    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner };
+    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner, ownerPending };
 }
 // The owner file's random name tells two holders apart even when the second
 // lock reuses the first one's freed inode.
@@ -115,10 +128,21 @@ function probeDead(pid) {
         return false;
     }
 }
+// Symmetric: a clock step back must not make a write-in-progress lock look
+// permanently fresh (see docs/internals.md).
+function withinWriteGrace(now, mtimeMs) {
+    return Math.abs(now - mtimeMs) < LOCK_WRITE_GRACE_MS;
+}
 function holderDead(holder, now) {
+    if (holder.body === '' && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const pid = Number(holder.body);
     if (!(Number.isSafeInteger(pid) && pid > 0))
         return true;
+    // A same-pid owner file exists but is not yet bound (the fallback lock's two
+    // writes race a reader); give it the same grace as an empty lock.
+    if (!holder.owner && holder.ownerPending && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const leaseOver = now - holder.mtimeMs >= LOCK_LEASE_MS;
     const owner = holder.owner;
     // No owner file: an older writer, whose namespace is unknown.
@@ -129,9 +153,8 @@ function holderDead(holder, now) {
     // Two unreadable parts compare equal without naming the same namespace or
     // boot, so only a fully known identity is looked up by start time.
     if (SELF.ns !== 'host' && SELF.boot !== '0' && SELF.start !== '0' && owner.start !== '0') {
-        // A live namespace id is never shared, so the recorded pid is ours to
-        // look up: a restarted container reuses both the id and the pid, but not
-        // the start time.
+        // A live namespace id is never shared, so the recorded pid is ours to look
+        // up: a restarted container reuses both the id and the pid, but not the start time.
         const start = startOf(pid);
         if (start !== undefined)
             return start !== owner.start;
@@ -141,9 +164,8 @@ function holderDead(holder, now) {
         return holder.mtimeMs < PROCESS_START_MS;
     return probeDead(pid) || leaseOver;
 }
-// One waiter at a time breaks a dead lock: two breakers could otherwise both
-// see the dead holder, and the second would unlink the first one's new lock.
-// False when another waiter is breaking it.
+// One waiter at a time breaks a dead lock, or the second could unlink the
+// first one's new lock; false when another waiter is already breaking it.
 function breakLock(lock, holder) {
     const breaker = `${lock}.break`;
     // A token, not the inode: a breaker created after ours was removed can
@@ -198,10 +220,55 @@ function releaseBreaker(breaker, token) {
             throw error;
     }
 }
-// Hardlink-based advisory lock, generalized path-keyed from the token store's
-// alias-keyed original. The lock body is the bare pid, as older readers expect;
-// the owner file stays linked while held and names the holder's process
-// instance. See docs/internals.md.
+// No hard links here (Android/Termux denies link() in private storage, some
+// filesystems lack it entirely): the lock is created directly with O_EXCL,
+// carrying the bare pid a linked owner file would carry, and the owner file
+// is bound to it by a recorded identity instead of a hard link. See docs/internals.md.
+function takeFallbackLock(lock, ownerFile) {
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    let acquired;
+    try {
+        fs.writeSync(fd, String(process.pid));
+        const stat = fs.fstatSync(fd, { bigint: true });
+        acquired = { dev: stat.dev, ino: stat.ino, mtimeNs: stat.mtimeNs };
+    }
+    catch (error) {
+        // The lock is left empty; remove it only if it is still the one we just
+        // created, then rethrow so the caller never retries a write failure.
+        const stat = fs.fstatSync(fd, { bigint: true });
+        fs.closeSync(fd);
+        try {
+            if (sameFile(fs.lstatSync(lock, { bigint: true }), stat))
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    fs.closeSync(fd);
+    try {
+        fs.writeFileSync(ownerFile, bindingRecord(acquired));
+    }
+    catch (error) {
+        // The lock already exists holding our live pid; without this cleanup
+        // every other writer sees an ownerless holder and waits out the full lease.
+        try {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs)
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return acquired;
+}
+// Hardlink-based advisory lock; the lock body is the bare pid, as older
+// readers expect. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     const dir = path.dirname(absPath);
     const lock = path.join(dir, `.${path.basename(absPath)}.lock`);
@@ -210,17 +277,31 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
     let linked = false;
+    let acquired;
     try {
         while (true) {
             try {
                 fs.linkSync(ownerFile, lock);
                 linked = true;
+                acquired = fs.lstatSync(lock, { bigint: true });
                 break;
             }
             catch (error) {
                 const err = error;
-                if (err.code !== 'EEXIST')
+                if (err.code === 'EACCES' || err.code === 'EPERM') {
+                    try {
+                        acquired = takeFallbackLock(lock, ownerFile);
+                        linked = true;
+                        break;
+                    }
+                    catch (fbError) {
+                        if (fbError.code !== 'EEXIST')
+                            throw fbError;
+                    }
+                }
+                else if (err.code !== 'EEXIST') {
                     throw error;
+                }
                 try {
                     const holder = readHolder(lock);
                     if (holder && holderDead(holder, Date.now()) && breakLock(lock, holder))
@@ -242,23 +323,24 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
         if (!linked)
             fs.rmSync(ownerFile, { force: true });
     }
-    let bound = false;
     try {
-        // Some network and FUSE filesystems give each name of one file its own
-        // inode number; there the owner file cannot vouch for the lock.
-        bound = sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true }));
         return fn();
     }
     finally {
-        releaseLock(lock, ownerFile, bound);
+        releaseLock(lock, ownerFile, acquired);
     }
 }
 // A holder whose lock was broken (its owner file removed with it) must not
-// remove its successor's lock.
-function releaseLock(lock, ownerFile, bound) {
+// remove its successor's lock: only drop the lock if it is still the exact
+// file this call created, and our own owner file is still there to vouch for it.
+function releaseLock(lock, ownerFile, acquired) {
     try {
-        if (!bound || sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true })))
-            fs.rmSync(lock, { force: true });
+        if (acquired) {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs && fs.existsSync(ownerFile)) {
+                fs.rmSync(lock, { force: true });
+            }
+        }
     }
     catch (error) {
         if (!isEnoent(error))

package/dist/hint-provider.d.ts

@@ -58,7 +58,10 @@ export type HintCase = {
     entries: string[];
 } | {
     kind: 'no_default_account';
-    aliases: string[];
+    accounts: {
+        alias: string;
+        email: string;
+    }[];
 } | {
     kind: 'no_accounts';
 } | {