dsh-mobile 0.8.4 → 0.8.6

package/lib/index.mjs

@@ -4,7 +4,7 @@ import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve,
 import { fileURLToPath, pathToFileURL } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { connect, createServer, isIP } from "node:net";
-import { chmod, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { access, chmod, copyFile, link, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
 import { performance as performance$1 } from "node:perf_hooks";
 import { execFile, spawn } from "node:child_process";
 import { createSocket } from "node:dgram";
@@ -25,7 +25,7 @@ import { connect as connect$1 } from "node:tls";
 import { generate } from "selfsigned";
 import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm/message";
 import { lookup } from "node:dns/promises";
-import { constants } from "node:fs";
+import { constants, readFileSync } from "node:fs";
 import { z as z$1 } from "zod";
 import webPush from "web-push";
 // src/access.ts
@@ -1036,10 +1036,17 @@ const Config = z.object({
 	maxBodyBytes: z.natural(),
 	upstreamTimeoutMs: z.natural(),
 	upstreamApiTimeoutMs: z.natural(),
+	catalogCache: z.boolean(),
 	rateLimitWindowMs: z.natural(),
 	maxPairingAttempts: z.natural(),
 	maxRateLimitKeys: z.natural()
 });
+/** Resolve one optional boolean with an explicit default; reject other types. */
+function booleanValue(value, name, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
+	return value;
+}
 function integer(value, name, fallback, minimum, maximum) {
 	const resolved = value ?? fallback;
 	if (typeof resolved !== "number" || !Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) throw new Error(`${name} must be an integer from ${String(minimum)} through ${String(maximum)}`);
@@ -1196,12 +1203,46 @@ function parseGatewayConfig(raw) {
 		maxBodyBytes: integer(value.maxBodyBytes, "maxBodyBytes", 167772160, 1024, 268435456),
 		upstreamTimeoutMs: integer(value.upstreamTimeoutMs, "upstreamTimeoutMs", 3e4, 1e3, 3e5),
 		upstreamApiTimeoutMs: integer(value.upstreamApiTimeoutMs, "upstreamApiTimeoutMs", 0, 0, 2147483647),
+		catalogCache: booleanValue(value.catalogCache, "catalogCache", true),
 		rateLimitWindowMs: integer(value.rateLimitWindowMs, "rateLimitWindowMs", 6e4, 1e3, 36e5),
 		maxPairingAttempts: integer(value.maxPairingAttempts, "maxPairingAttempts", 8, 1, 100),
 		maxRateLimitKeys: integer(value.maxRateLimitKeys, "maxRateLimitKeys", 256, 1, 4096)
 	});
 }
 // src/exec-file.ts
+/**
+* Longest stream text attached to a failed subprocess result.
+*
+* The text exists for diagnostics only: a caller decides which part is safe to
+* show. It is bounded here so a chatty child cannot turn one failure into an
+* unbounded buffer in every future consumer of that rejection.
+*/
+const MAX_SUBPROCESS_ERROR_STREAM_CHARS = 8192;
+function boundedStream(value) {
+	if (typeof value !== "string" || value === "") return void 0;
+	return value.length <= 8192 ? value : value.slice(0, MAX_SUBPROCESS_ERROR_STREAM_CHARS);
+}
+/**
+* Attach the captured streams to a subprocess failure, best effort.
+*
+* `execFile` reports a non-zero exit as an Error whose only text is the command
+* line with stderr merged into `message`; the raw stream strings are handed to
+* the callback and otherwise discarded, so a caller cannot read them from the
+* rejection. They are copied onto it when it accepts properties. A frozen,
+* exotic or primitive rejection value must keep `message` as its diagnostic
+* rather than turn one failure into a different error, so every write is
+* guarded and an existing property is never overwritten.
+*/
+function attachCapturedStreams(error, stdout, stderr) {
+	if (typeof error !== "object" || error === null) return;
+	const target = error;
+	try {
+		const capturedStderr = boundedStream(stderr);
+		const capturedStdout = boundedStream(stdout);
+		if (target.stderr === void 0 && capturedStderr !== void 0) target.stderr = capturedStderr;
+		if (target.stdout === void 0 && capturedStdout !== void 0) target.stdout = capturedStdout;
+	} catch {}
+}
 /** Capture both output streams even when a desktop host wraps execFile without Node's promisify metadata. */
 function execFileText(file, args, options = {}) {
 	return new Promise((resolve, reject) => {
@@ -1211,6 +1252,7 @@ function execFileText(file, args, options = {}) {
 			encoding: "utf8"
 		}, (error, stdout, stderr) => {
 			if (error !== null) {
+				attachCapturedStreams(error, stdout, stderr);
 				reject(error);
 				return;
 			}
@@ -2469,6 +2511,305 @@ var ApiLatencyRecorder = class {
 		}
 	}
 };
+// src/catalog-cache.ts
+/** Host RPCs whose successful completion can change catalog results. */
+const CATALOG_MUTATION_METHODS = /* @__PURE__ */ new Set([
+	"account/signOut",
+	"account/startSignIn",
+	"credentials/set",
+	"credentials/unset",
+	"pluginManager/installBundle",
+	"pluginManager/removeBundle",
+	"pluginManager/setBundleEnabled",
+	"pluginManager/setPluginEnabled",
+	"pluginManager/setVersionExemption",
+	"pluginManager/updateBundle",
+	"session/initializeDefaultModel",
+	"session/selectModel",
+	"settings/mutate",
+	"settings/replace",
+	"settings/update"
+]);
+const CATALOG_CACHE_METHODS = /* @__PURE__ */ new Set(["llm/listProviders", "session/modelCatalog"]);
+const DEFAULT_CATALOG_CACHE_LIMITS = Object.freeze({
+	freshMs: 5e3,
+	staleMs: 6e4,
+	maxEntries: 4,
+	maxEntryBytes: 2097152,
+	maxTotalBytes: 8388608,
+	maxInFlightFills: 2
+});
+const REQUEST_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"rpcId",
+	"method",
+	"payload"
+]);
+const RESPONSE_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"rpcId",
+	"result"
+]);
+const encoder = new TextEncoder();
+const isObject$1 = (value) => typeof value === "object" && value !== null;
+const hasExactKeys = (value, keys) => {
+	const present = Object.keys(value);
+	if (present.length !== keys.size) return false;
+	for (const key of present) if (!keys.has(key)) return false;
+	return true;
+};
+/**
+* Validate one catalog request against the captured wire contract.
+* @param routeMethod - The `/api/<method>` route segment.
+* @param bodyJson - The exact buffered request body.
+* @returns The eligible method and its live rpcId, or undefined for anything else.
+*/
+function checkCatalogRequest(routeMethod, bodyJson) {
+	if (!CATALOG_CACHE_METHODS.has(routeMethod)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(bodyJson);
+	} catch {
+		return;
+	}
+	if (!isObject$1(parsed) || !hasExactKeys(parsed, REQUEST_KEYS)) return void 0;
+	if (parsed.type !== "client-request") return void 0;
+	if (parsed.method !== routeMethod) return void 0;
+	if (typeof parsed.rpcId !== "string" || parsed.rpcId.length === 0 || parsed.rpcId.length > 512) return void 0;
+	const payload = parsed.payload;
+	if (!isObject$1(payload) || !hasExactKeys(payload, /* @__PURE__ */ new Set(["args"]))) return void 0;
+	const args = payload.args;
+	if (!isObject$1(args) || Array.isArray(args) || Object.keys(args).length !== 0) return void 0;
+	return {
+		method: routeMethod,
+		rpcId: parsed.rpcId
+	};
+}
+/**
+* Validate a fill response against the captured success schema.
+* @param envelopeJson - The buffered upstream response body.
+* @param expectedRpcId - The gateway-generated rpcId the fill sent.
+* @returns Whether the envelope is the shareable success variant for that id.
+*/
+function validateCatalogEnvelope(envelopeJson, expectedRpcId) {
+	let parsed;
+	try {
+		parsed = JSON.parse(envelopeJson);
+	} catch {
+		return false;
+	}
+	if (!isObject$1(parsed) || !hasExactKeys(parsed, RESPONSE_KEYS)) return false;
+	if (parsed.type !== "server-response") return false;
+	if (parsed.rpcId !== expectedRpcId) return false;
+	const result = parsed.result;
+	if (!isObject$1(result)) return false;
+	return result.ok === true && "value" in result;
+}
+/**
+* Re-stamp a validated envelope for one caller.
+* @param envelopeJson - The cached upstream envelope.
+* @param expectedRpcId - The fill rpcId the envelope must carry.
+* @param liveRpcId - The caller's rpcId to serialize into the response.
+* @returns The per-caller JSON body, or undefined when validation fails.
+*/
+function restampEnvelope(envelopeJson, expectedRpcId, liveRpcId) {
+	let parsed;
+	try {
+		parsed = JSON.parse(envelopeJson);
+	} catch {
+		return;
+	}
+	if (!validateCatalogEnvelope(envelopeJson, expectedRpcId)) return void 0;
+	const body = parsed;
+	body.rpcId = liveRpcId;
+	return JSON.stringify(body);
+}
+/**
+* Generation-aware SWR cache over the injected fill transport.
+* @typeParam TUpstreamSnapshot - Opaque immutable upstream identity snapshot the gateway captures per request.
+*/
+var CatalogCache = class {
+	#limits;
+	#clock;
+	#fetchFill;
+	#entries = /* @__PURE__ */ new Map();
+	#flights = /* @__PURE__ */ new Map();
+	#identityDigest;
+	#epoch = 0;
+	#disposed = false;
+	constructor(deps) {
+		this.#fetchFill = deps.fetchFill;
+		this.#clock = deps.clock;
+		this.#limits = {
+			...DEFAULT_CATALOG_CACHE_LIMITS,
+			...deps.limits
+		};
+	}
+	get entryCount() {
+		return this.#entries.size;
+	}
+	get residentBytes() {
+		let total = 0;
+		for (const entry of this.#entries.values()) total += entry.bytes;
+		return total;
+	}
+	get inFlightFills() {
+		let active = 0;
+		for (const flight of this.#flights.values()) if (!flight.settled) active += 1;
+		return active;
+	}
+	/**
+	* Serve one eligible request from the current generation.
+	* @param input - Method, caller rpcId, current identity digest and its snapshot.
+	* @returns A per-caller replay, or passthrough when the ordinary path must run.
+	*/
+	async serve(input) {
+		if (this.#disposed) return { kind: "passthrough" };
+		if (!CATALOG_CACHE_METHODS.has(input.method)) return { kind: "passthrough" };
+		const method = input.method;
+		this.#syncIdentity(input.identityDigest);
+		const generation = this.#currentGeneration();
+		const key = `${input.identityDigest}\u0000${method}`;
+		const entry = this.#entries.get(key);
+		if (entry !== void 0) {
+			const age = this.#clock() - entry.completedAt;
+			if (age < this.#limits.freshMs) {
+				entry.lastServedAt = this.#clock();
+				const body = restampEnvelope(entry.envelopeJson, entry.upstreamRpcId, input.rpcId);
+				if (body !== void 0) return {
+					kind: "hit",
+					body,
+					generation,
+					validUntil: entry.validUntil
+				};
+			} else if (age < this.#limits.staleMs) {
+				entry.lastServedAt = this.#clock();
+				const body = restampEnvelope(entry.envelopeJson, entry.upstreamRpcId, input.rpcId);
+				if (body !== void 0) {
+					this.#startBackgroundFill(method, input.identityDigest, input.upstream);
+					return {
+						kind: "stale",
+						body,
+						generation,
+						validUntil: entry.validUntil
+					};
+				}
+			}
+		}
+		const flightKey = `${input.identityDigest}|${generation.epoch}|${method}`;
+		const existing = this.#flights.get(flightKey);
+		if (existing === void 0 && this.inFlightFills >= this.#limits.maxInFlightFills) return { kind: "passthrough" };
+		const outcome = await (existing ?? this.#createFlight(method, generation, input.upstream)).promise;
+		if (!outcome.shareable) return { kind: "passthrough" };
+		if (!this.#isCurrent(generation)) return { kind: "passthrough" };
+		if (!validateCatalogEnvelope(outcome.envelopeJson, outcome.upstreamRpcId)) return { kind: "passthrough" };
+		const body = restampEnvelope(outcome.envelopeJson, outcome.upstreamRpcId, input.rpcId);
+		if (body === void 0) return { kind: "passthrough" };
+		return {
+			kind: "replay",
+			body,
+			generation,
+			validUntil: this.#clock() + this.#limits.staleMs
+		};
+	}
+	/** Record the current upstream identity; a change clears entries and bumps the epoch. */
+	noteIdentity(identityDigest) {
+		this.#syncIdentity(identityDigest);
+	}
+	/** Invalidate every entry after a catalog-affecting mutation. */
+	noteCatalogMutation() {
+		this.#epoch += 1;
+		this.#entries.clear();
+	}
+	/** Whether a generation is still the current one. */
+	isCurrent(generation) {
+		return this.#isCurrent(generation);
+	}
+	/** Final pre-commit check for a replay result: generation, disposal and age. */
+	canCommit(result) {
+		if (this.#disposed) return false;
+		if (!this.#isCurrent(result.generation)) return false;
+		return this.#clock() < result.validUntil;
+	}
+	/** Invalidate everything and refuse new fills or publication. */
+	dispose() {
+		this.#disposed = true;
+		this.#entries.clear();
+	}
+	#isCurrent(generation) {
+		if (this.#disposed) return false;
+		return generation.identityDigest === this.#identityDigest && generation.epoch === this.#epoch;
+	}
+	#currentGeneration() {
+		return {
+			identityDigest: this.#identityDigest,
+			epoch: this.#epoch
+		};
+	}
+	#syncIdentity(identityDigest) {
+		if (identityDigest === this.#identityDigest) return;
+		this.#identityDigest = identityDigest;
+		this.#epoch += 1;
+		this.#entries.clear();
+	}
+	#createFlight(method, generation, upstream) {
+		const flightKey = `${generation.identityDigest}|${generation.epoch}|${method}`;
+		const invoke = async () => this.#fetchFill({
+			method,
+			generation,
+			upstream
+		});
+		const flight = {
+			generation,
+			method,
+			settled: false,
+			promise: invoke().catch(() => ({ shareable: false })).then((outcome) => {
+				flight.settled = true;
+				if (this.#flights.get(flightKey) === flight) this.#flights.delete(flightKey);
+				if (outcome.shareable && this.#isCurrent(generation)) this.#retain(method, generation, outcome);
+				return outcome;
+			})
+		};
+		this.#flights.set(flightKey, flight);
+		return flight;
+	}
+	#startBackgroundFill(method, identityDigest, upstream) {
+		if (this.#disposed) return;
+		const generation = this.#currentGeneration();
+		const flightKey = `${identityDigest}|${generation.epoch}|${method}`;
+		if (this.#flights.has(flightKey)) return;
+		if (this.inFlightFills >= this.#limits.maxInFlightFills) return;
+		this.#createFlight(method, generation, upstream).promise.catch(() => void 0);
+	}
+	#retain(method, generation, outcome) {
+		if (!validateCatalogEnvelope(outcome.envelopeJson, outcome.upstreamRpcId)) return;
+		const bytes = encoder.encode(outcome.envelopeJson).length;
+		if (bytes > this.#limits.maxEntryBytes) return;
+		const key = `${generation.identityDigest}\u0000${method}`;
+		const now = this.#clock();
+		if (this.#entries.has(key)) this.#entries.delete(key);
+		const evict = () => {
+			const candidates = [...this.#entries.entries()].sort(([, a], [, b]) => a.lastServedAt - b.lastServedAt);
+			for (const [candidateKey] of candidates) {
+				if (this.#entries.size < this.#limits.maxEntries && this.residentBytes + bytes <= this.#limits.maxTotalBytes) break;
+				this.#entries.delete(candidateKey);
+			}
+		};
+		evict();
+		if (this.#entries.size >= this.#limits.maxEntries) return;
+		if (this.residentBytes + bytes > this.#limits.maxTotalBytes) return;
+		this.#entries.set(key, {
+			identityDigest: generation.identityDigest,
+			method,
+			envelopeJson: outcome.envelopeJson,
+			upstreamRpcId: outcome.upstreamRpcId,
+			completedAt: now,
+			validUntil: now + this.#limits.staleMs,
+			bytes,
+			lastServedAt: now
+		});
+	}
+};
 // src/upstream-auth-log.ts
 const LOG_INTERVAL_MS = 3e4;
 /** Two fixed sampling slots keep a first failure visible even after a successful exchange. */
@@ -5387,12 +5728,16 @@ const MOBILE_LAYOUT_MODULE = "@deepseek-ai/dsh-client-ui-layout";
 const MOBILE_LAYOUT_PATH = `${AUTH_PREFIX}/mobile-layout.js`;
 const MOBILE_BOOT_BATCH_PREFIX = `${AUTH_PREFIX}/mobile-boot/`;
 const MOBILE_DOCUMENT_VIEW_HEADER = "x-dsh-mobile-view";
+const CATALOG_CACHE_MARKER = "x-dsh-mobile-catalog";
+/** Eligible catalog envelopes are small fixed-shape JSON; larger declared bodies keep the streaming path. */
+const CATALOG_CANDIDATE_BODY_LIMIT = 65536;
 const MOBILE_PUSH_CONFIG_PATH = `${AUTH_PREFIX}/push/config`;
 const MOBILE_PUSH_SUBSCRIPTION_PATH = `${AUTH_PREFIX}/push/subscription`;
 const MOBILE_PUSH_PREFERENCES_PATH = `${AUTH_PREFIX}/push/preferences`;
 const MOBILE_PUSH_DISABLE_PATH = `${AUTH_PREFIX}/push/disable`;
 const MOBILE_PUSH_TEST_PATH = `${AUTH_PREFIX}/push/test`;
 const MOBILE_PUSH_RESOLVE_PATH = `${AUTH_PREFIX}/push/resolve`;
+const BACKGROUND_EVENT_PATH = `${AUTH_PREFIX}/background-events`;
 const MOBILE_PUSH_PREFERENCE_KEYS = [
 	"question",
 	"plan",
@@ -5869,7 +6214,7 @@ function splitMobileBootBatch(entries, sizes, passThrough) {
 	};
 	for (const entry of entries) {
 		const size = sizes.get(entry.url);
-		if ((passThrough.has(entry.url) || size !== void 0 && size >= MAX_MOBILE_BOOT_ENTRY_BYTES) && entry.id !== MOBILE_LAYOUT_MODULE) {
+		if ((passThrough.has(entry.url) || size !== void 0 && (size <= 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES)) && entry.id !== MOBILE_LAYOUT_MODULE) {
 			rows.push({
 				phase: "application",
 				url: entry.url,
@@ -5878,7 +6223,7 @@ function splitMobileBootBatch(entries, sizes, passThrough) {
 			});
 			continue;
 		}
-		const bytes = (size ?? 0) + MOBILE_BOOT_SEPARATOR_BYTES;
+		const bytes = (size !== void 0 && size > 0 ? size : 0) + MOBILE_BOOT_SEPARATOR_BYTES;
 		if (chunk !== void 0 && chunk.entries.length > 0 && chunk.bytes + bytes > MOBILE_BOOT_CHUNK_BYTES) flush();
 		chunk ??= {
 			ids: [],
@@ -6138,6 +6483,12 @@ function sanitizeRequestHeaders(request, upstream) {
 		const value = request.headers[name];
 		if (value !== void 0) headers[name] = value;
 	}
+	for (const name of Object.keys(request.headers)) {
+		const lower = name.toLowerCase();
+		if (!lower.startsWith("x-dsh-") || lower.startsWith("x-dsh-mobile-") || lower === "x-dsh-auth-token") continue;
+		const value = request.headers[name];
+		if (value !== void 0) headers[name] = Array.isArray(value) ? value[0] : value;
+	}
 	return headers;
 }
 const BLOCKED_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
@@ -6482,6 +6833,18 @@ var MobileAccessGateway = class {
 	upstreamCookie;
 	upstreamCookieExpiresAt = 0;
 	upstreamCookieTask;
+	#catalogCache;
+	#upstreamIdentityRevision = 0;
+	#catalogFills = /* @__PURE__ */ new Set();
+	/** The catalog SWR cache, or undefined when `catalogCache` is disabled. */
+	get catalogCache() {
+		if (!this.config.catalogCache) return void 0;
+		this.#catalogCache ??= new CatalogCache({
+			fetchFill: (input) => this.catalogFill(input),
+			clock: () => performance.now()
+		});
+		return this.#catalogCache;
+	}
 	upstreamAuthRequest;
 	nextOperationId = 1;
 	closing = false;
@@ -7279,6 +7642,7 @@ var MobileAccessGateway = class {
 		const computerImage = request.method === "GET" && target.decodedPathname === `/mobile-access/computer-image`;
 		const workspaceDirectories = (request.method === "GET" || request.method === "POST") && target.decodedPathname === `/mobile-access/workspace-directories`;
 		const clientModules = target.decodedPathname === `${AUTH_PREFIX}/client-modules`;
+		const backgroundEvents = target.decodedPathname === BACKGROUND_EVENT_PATH;
 		const mobilePushRoute = [
 			MOBILE_PUSH_CONFIG_PATH,
 			MOBILE_PUSH_SUBSCRIPTION_PATH,
@@ -7312,7 +7676,7 @@ var MobileAccessGateway = class {
 			fallback: void 0,
 			digest: requestedCompatRevision
 		} : void 0;
-		if (customAsset === void 0 && requestedMobileBootBatch === void 0 && !computerImages && !computerImage && !workspaceDirectories && !clientModules && !mobilePushRoute && extensionTarget(target.decodedPathname) === void 0 && (target.decodedPathname === "/mobile-access" || target.decodedPathname.startsWith(`/mobile-access/`))) throw new HttpError(404, "not_found");
+		if (customAsset === void 0 && requestedMobileBootBatch === void 0 && !computerImages && !computerImage && !workspaceDirectories && !clientModules && !backgroundEvents && !mobilePushRoute && extensionTarget(target.decodedPathname) === void 0 && (target.decodedPathname === "/mobile-access" || target.decodedPathname.startsWith(`/mobile-access/`))) throw new HttpError(404, "not_found");
 		if (![
 			"GET",
 			"HEAD",
@@ -7353,6 +7717,11 @@ var MobileAccessGateway = class {
 			await this.handleMobilePushRequest(target, request, response, authorization);
 			return;
 		}
+		if (backgroundEvents) {
+			if (request.method !== "GET" || target.search !== "") throw new HttpError(request.method === "GET" ? 400 : 405, request.method === "GET" ? "bad_request" : "method_not_allowed");
+			this.openBackgroundEventStream(request, response, authorization);
+			return;
+		}
 		if (clientModules) {
 			if (target.search !== "") throw new HttpError(400, "bad_request");
 			if (request.method !== "GET" && request.method !== "POST") throw new HttpError(405, "method_not_allowed");
@@ -7529,6 +7898,21 @@ var MobileAccessGateway = class {
 			return;
 		}
 		if (stockFrontend && target.decodedPathname === "/") request.url = "/";
+		const candidateContentType = String(request.headers["content-type"] ?? "").split(";", 1)[0]?.trim().toLowerCase();
+		const candidateDeclaredLength = request.headers["content-length"] === void 0 ? void 0 : Number(request.headers["content-length"]);
+		const catalogRouteMethod = this.config.catalogCache && documentView === void 0 && request.method === "POST" && target.search === "" && candidateContentType === "application/json" && candidateDeclaredLength !== void 0 && Number.isFinite(candidateDeclaredLength) && candidateDeclaredLength > 0 && candidateDeclaredLength <= CATALOG_CANDIDATE_BODY_LIMIT && (target.decodedPathname === "/api/llm/listProviders" || target.decodedPathname === "/api/session/modelCatalog") ? target.decodedPathname.slice(5) : void 0;
+		if (catalogRouteMethod !== void 0) {
+			const candidateBody = await this.readRequestBody(request, Math.min(CATALOG_CANDIDATE_BODY_LIMIT, this.config.maxBodyBytes));
+			const eligible = checkCatalogRequest(catalogRouteMethod, candidateBody.toString("utf8"));
+			if (eligible !== void 0 && this.catalogCache !== void 0) {
+				if (await this.serveCatalogCache(eligible, request, response, authorization)) return;
+				response.setHeader(CATALOG_CACHE_MARKER, "miss-passthrough");
+				await this.proxyHttp(request, response, authorization, documentView, candidateBody);
+				return;
+			}
+			await this.proxyHttp(request, response, authorization, documentView, candidateBody);
+			return;
+		}
 		await this.proxyHttp(request, response, authorization, documentView);
 	}
 	async handleExtensionRequest(targetInfo, target, request, response, authorization) {
@@ -7823,6 +8207,8 @@ var MobileAccessGateway = class {
 			if (pair === void 0 || pair.length > 4096 || !UPSTREAM_COOKIE_PAIR.test(pair) || !Number.isSafeInteger(expiresAt) || maxAgeSeconds <= 0) throw new HttpError(502, "upstream_unavailable");
 			this.upstreamCookie = pair;
 			this.upstreamCookieExpiresAt = expiresAt;
+			this.#upstreamIdentityRevision += 1;
+			this.catalogCache?.noteIdentity(createHash("sha256").update(pair).digest("hex"));
 			this.upstreamAuthDiagnostics.record(attempt, {
 				outcome: "accepted",
 				stage,
@@ -8346,7 +8732,7 @@ var MobileAccessGateway = class {
 				const index = cursor++;
 				const source = candidates[index].url;
 				const size = await this.upstreamBundleSize(source, signal);
-				if (size === void 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES) passThrough.add(source);
+				if (size === void 0 || size <= 0 || size >= MAX_MOBILE_BOOT_ENTRY_BYTES) passThrough.add(source);
 				else sizes.set(source, size);
 			}
 		};
@@ -8650,13 +9036,181 @@ var MobileAccessGateway = class {
 			}
 		};
 	}
+	/** Read one bounded request body verbatim; the caller owns replaying it upstream. */
+	readRequestBody(request, limitBytes) {
+		const declared = request.headers["content-length"];
+		if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > limitBytes)) throw new HttpError(413, "payload_too_large");
+		return new Promise((resolve, reject) => {
+			const chunks = [];
+			let received = 0;
+			let failed = false;
+			request.on("data", (chunk) => {
+				if (failed) return;
+				received += chunk.length;
+				if (received > limitBytes) {
+					failed = true;
+					reject(new HttpError(413, "payload_too_large"));
+					request.resume();
+					return;
+				}
+				chunks.push(chunk);
+			});
+			request.once("end", () => {
+				if (!failed) resolve(Buffer.concat(chunks));
+			});
+			request.once("error", (error) => {
+				if (!failed) reject(error);
+			});
+		});
+	}
+	/** One gateway-owned catalog fill: its own socket, rpcId, deadline and byte cap. */
+	async catalogFill(input) {
+		const rpcId = `dsh-mobile-catalog-${randomUUID()}`;
+		const body = JSON.stringify({
+			type: "client-request",
+			rpcId,
+			method: input.method,
+			payload: { args: {} }
+		});
+		return await new Promise((resolve) => {
+			let settled = false;
+			let upstreamRequest;
+			const finish = (outcome) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(absoluteDeadline);
+				this.#catalogFills.delete(upstreamRequest);
+				resolve(outcome);
+			};
+			upstreamRequest = request({
+				protocol: "http:",
+				hostname: stripIpv6Brackets(this.config.upstreamOrigin.hostname),
+				port: Number(this.config.upstreamOrigin.port),
+				method: "POST",
+				path: `/api/${input.method}`,
+				headers: {
+					host: this.config.upstreamOrigin.host,
+					"content-type": "application/json",
+					accept: "application/json",
+					"accept-encoding": "identity",
+					"content-length": String(Buffer.byteLength(body)),
+					...input.upstream.cookieHeader === void 0 ? {} : { cookie: input.upstream.cookieHeader }
+				},
+				agent: false
+			}, (response) => {
+				const status = response.statusCode ?? 0;
+				const rawContentType = String(response.headers["content-type"] ?? "");
+				const mediaType = rawContentType.split(";", 1)[0]?.trim().toLowerCase();
+				const charset = /charset\s*=\s*([^;]+)/iu.exec(rawContentType)?.[1]?.trim().toLowerCase();
+				if (status !== 200 || mediaType !== "application/json" || charset !== void 0 && charset !== "utf-8" && charset !== "utf8" || response.headers["set-cookie"] !== void 0 || response.headers["content-encoding"] !== void 0 && response.headers["content-encoding"] !== "identity") {
+					response.destroy();
+					finish({ shareable: false });
+					return;
+				}
+				const chunks = [];
+				let received = 0;
+				let overflowed = false;
+				response.on("data", (chunk) => {
+					if (overflowed) return;
+					received += chunk.length;
+					if (received > DEFAULT_CATALOG_CACHE_LIMITS.maxEntryBytes) {
+						overflowed = true;
+						response.destroy();
+						return;
+					}
+					chunks.push(chunk);
+				});
+				response.once("end", () => {
+					if (overflowed) {
+						finish({ shareable: false });
+						return;
+					}
+					try {
+						const envelopeJson = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+						JSON.parse(envelopeJson);
+						finish({
+							shareable: true,
+							envelopeJson,
+							upstreamRpcId: rpcId
+						});
+					} catch {
+						finish({ shareable: false });
+					}
+				});
+				response.once("error", () => finish({ shareable: false }));
+				response.once("close", () => finish({ shareable: false }));
+			});
+			const absoluteDeadline = setTimeout(() => {
+				upstreamRequest.destroy(/* @__PURE__ */ new Error("catalog fill deadline"));
+			}, this.config.upstreamTimeoutMs);
+			upstreamRequest.setTimeout(this.config.upstreamTimeoutMs, () => {
+				upstreamRequest.destroy(/* @__PURE__ */ new Error("catalog fill idle timeout"));
+			});
+			upstreamRequest.once("error", () => finish({ shareable: false }));
+			this.#catalogFills.add(upstreamRequest);
+			upstreamRequest.end(body);
+		});
+	}
+	/**
+	* Serve one eligible catalog request from the SWR cache.
+	* @returns true when the response was committed here; false for the ordinary path.
+	*/
+	async serveCatalogCache(eligible, request, response, authorization) {
+		const cache = this.catalogCache;
+		if (cache === void 0) return false;
+		const operation = this.allocateRequest(authorization, response, {});
+		const onClose = () => {
+			operation.abort();
+			operation.release();
+		};
+		response.once("close", onClose);
+		try {
+			const snapshotRevision = this.#upstreamIdentityRevision;
+			const hadIdentityBefore = this.upstreamCookie !== void 0;
+			const cookieHeader = await waitForRequestTask(this.upstreamCookieHeader(), operation.signal);
+			operation.signal.throwIfAborted();
+			const superseded = hadIdentityBefore && snapshotRevision !== this.#upstreamIdentityRevision;
+			if (response.destroyed || superseded) return false;
+			const identityDigest = createHash("sha256").update(cookieHeader ?? "none").digest("hex");
+			cache.noteIdentity(identityDigest);
+			const result = await cache.serve({
+				method: eligible.method,
+				rpcId: eligible.rpcId,
+				identityDigest,
+				upstream: { cookieHeader }
+			});
+			operation.signal.throwIfAborted();
+			if (result.kind === "passthrough" || !cache.canCommit(result) || response.destroyed) return false;
+			const payload = Buffer.from(result.body, "utf8");
+			const headers = {
+				"content-type": "application/json",
+				"cache-control": "no-store",
+				[CATALOG_CACHE_MARKER]: result.kind
+			};
+			let body = payload;
+			if (acceptsGzip(request.headers["accept-encoding"]) && payload.length >= MIN_COMPRESSIBLE_BYTES) {
+				body = await gzipBuffer(payload);
+				headers["content-encoding"] = "gzip";
+				addVaryAcceptEncoding(headers);
+			}
+			if (!cache.canCommit(result) || response.destroyed) return false;
+			headers["content-length"] = body.length;
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
+			response.writeHead(200, headers);
+			response.end(body);
+			return true;
+		} finally {
+			response.removeListener("close", onClose);
+			operation.release();
+		}
+	}
 	/**
 	* Proxy one request, retrying transient failures for plugin and asset GETs.
 	* Only bodyless GETs can be replayed, before response headers reach the client.
 	* One request slot and cancellation signal cover attempts and backoff together.
 	* API requests and requests with bodies are forwarded once.
 	*/
-	async proxyHttp(request, response, authorization, documentView) {
+	async proxyHttp(request, response, authorization, documentView, bodyOverride) {
 		const declared = request.headers["content-length"];
 		if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > this.config.maxBodyBytes)) throw new HttpError(413, "payload_too_large");
 		const replayable = request.method === "GET" && request.headers["transfer-encoding"] === void 0 && (declared === void 0 || Number(declared) === 0) && (request.url?.split("?", 1)[0]?.startsWith("/plugins/") === true || request.url?.split("?", 1)[0]?.startsWith("/assets/") === true);
@@ -8684,7 +9238,7 @@ var MobileAccessGateway = class {
 			for (let attempt = 1; attempt <= attempts; attempt++) {
 				operation.signal.throwIfAborted();
 				try {
-					await this.proxyHttpOnce(request, response, holder, operation.signal, replayable, documentView);
+					await this.proxyHttpOnce(request, response, holder, operation.signal, replayable, documentView, bodyOverride);
 					return;
 				} catch (error) {
 					if (operation.signal.aborted || response.destroyed) return;
@@ -8705,7 +9259,7 @@ var MobileAccessGateway = class {
 			operation.release();
 		}
 	}
-	async proxyHttpOnce(request$2, response, holder, signal, replayable, documentView) {
+	async proxyHttpOnce(request$2, response, holder, signal, replayable, documentView, bodyOverride) {
 		let bodyDone;
 		const projections = /* @__PURE__ */ new Set();
 		try {
@@ -8736,7 +9290,8 @@ var MobileAccessGateway = class {
 				});
 				upstreamRequest.once("response", resolve);
 				upstreamRequest.once("error", reject);
-				if (replayable) upstreamRequest.end();
+				if (bodyOverride !== void 0) upstreamRequest.end(bodyOverride);
+				else if (replayable) upstreamRequest.end();
 				else {
 					bodyDone = pipeline(request$2, new ByteLimitTransform(this.config.maxBodyBytes), upstreamRequest);
 					bodyDone.catch(reject);
@@ -8760,6 +9315,7 @@ var MobileAccessGateway = class {
 				delete headers["accept-ranges"];
 			}
 			const statusCode = proxied.statusCode ?? 502;
+			if (statusCode >= 200 && statusCode < 300 && this.catalogCache !== void 0 && pathname.startsWith("/api/") && CATALOG_MUTATION_METHODS.has(pathname.slice(5))) this.catalogCache.noteCatalogMutation();
 			this.httpFailures.recordUpstream(request$2.method, request$2.url?.split("?", 1)[0] ?? "", statusCode);
 			const cacheControl = graphEvents ? void 0 : revisionedStaticCacheControl(request$2, statusCode);
 			if (cacheControl !== void 0) headers["cache-control"] = cacheControl;
@@ -8906,6 +9462,54 @@ var MobileAccessGateway = class {
 		request.once("aborted", close);
 		response.once("close", close);
 	}
+	/**
+	* Native background notifications need only Host task and revocation events.
+	* They use the paired session cookie but no mobile document view, because the
+	* App has no live WebView while this stream is serving a suspended page.
+	*/
+	openBackgroundEventStream(request, response, authorization) {
+		const operation = this.allocateRequest(authorization, response, {});
+		let closed = false;
+		let heartbeat;
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			if (heartbeat !== void 0) clearInterval(heartbeat);
+			this.taskEventListeners.delete(sendTask);
+			const deviceListeners = this.deviceEventListeners.get(authorization.deviceId);
+			deviceListeners?.delete(sendDevice);
+			if (deviceListeners?.size === 0) this.deviceEventListeners.delete(authorization.deviceId);
+			request.removeListener("aborted", close);
+			response.removeListener("close", close);
+			operation.release();
+		};
+		const sendTask = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: task-notify\ndata: ${payload}\n\n`);
+		};
+		const sendDevice = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: device-revoked\ndata: ${payload}\n\n`);
+		};
+		setSecurityHeaders(response, this.tlsEnabled);
+		response.writeHead(200, {
+			"Content-Type": "text/event-stream; charset=utf-8",
+			"Cache-Control": "no-store",
+			Connection: "keep-alive",
+			"X-Accel-Buffering": "no"
+		});
+		response.write("retry: 2000\n: ready\n\n");
+		this.taskEventListeners.add(sendTask);
+		const deviceListeners = this.deviceEventListeners.get(authorization.deviceId) ?? /* @__PURE__ */ new Set();
+		deviceListeners.add(sendDevice);
+		this.deviceEventListeners.set(authorization.deviceId, deviceListeners);
+		heartbeat = setInterval(() => {
+			if (!closed && !response.destroyed && !response.writableEnded) response.write(": heartbeat\n\n");
+		}, EXTENSION_EVENT_HEARTBEAT_MS);
+		heartbeat.unref();
+		request.once("aborted", close);
+		response.once("close", close);
+	}
 	async readUpgradeResponse(upstream, expectedAccept) {
 		return new Promise((resolve, reject) => {
 			let buffer = Buffer.alloc(0);
@@ -9186,6 +9790,9 @@ var MobileAccessGateway = class {
 	}
 	async performClose() {
 		this.closing = true;
+		this.#catalogCache?.dispose();
+		for (const fill of this.#catalogFills) fill.destroy(/* @__PURE__ */ new Error("gateway closing"));
+		this.#catalogFills.clear();
 		const detachPushOrigin = this.detachPushOrigin;
 		this.detachPushOrigin = void 0;
 		detachPushOrigin?.();
@@ -9391,6 +9998,26 @@ var MemoryDeviceStore = class {
 		return structuredClone(this.snapshot);
 	}
 };
+// src/mobile-push/service.ts
+/**
+* Small Cordis service exposed to trusted Host plugins. The provider owns the
+* runtime lifetime and all recipient, category, session, and expiry checks.
+*/
+var MobilePushService = class extends Service {
+	send;
+	constructor(ctx, send) {
+		super(ctx, "mobilePush");
+		this.send = send;
+	}
+	/**
+	* Queue a notification for enabled web-push recipients.
+	* @param input - Session, text, optional category and optional expiry.
+	* @returns The number of newly queued recipient deliveries and the applied expiry.
+	*/
+	async notify(input) {
+		return await this.send(input);
+	}
+};
 // src/managed-files.ts
 /** Refuse link-shaped ancestors inside an owned state root before accessing a child. */
 async function assertManagedParents(root, target, prefix) {
@@ -11907,7 +12534,7 @@ async function saveManagedSetup(setupFile, setup) {
 }
 function privateIpv4(value) {
 	const parts = value.split(".").map(Number);
-	return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) && (parts[0] === 10 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168);
+	return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) && (parts[0] === 10 || parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168);
 }
 function networkCidr(address, cidr) {
 	const prefix = Number(cidr.slice(cidr.lastIndexOf("/") + 1));
@@ -15429,14 +16056,99 @@ const PAIRING_DESCRIPTOR_LOCAL_PORT = DEFAULT_IROH_LOCAL_PORT;
 const READY_TIMEOUT_MS = 45e3;
 const IDENTITY_TIMEOUT_MS = 15e3;
 const IDENTITY_METADATA_MAX_BYTES = 8192;
+const IDENTITY_DIAGNOSTIC_MAX_BYTES = 4096;
 const PAIRING_TIMEOUT_MS = 15e3;
 const MAX_LINE_BYTES = 16384;
 /** Gateway pairing windows default to five minutes; the descriptor caps at ten. */
 const MAX_PAIRING_WINDOW_MS = 3e5;
 const MIN_PAIRING_WINDOW_MS = 1e4;
+/** Safe classified failure from the short-lived endpoint identity probe. */
+var IrohIdentityProbeError = class extends Error {
+	code;
+	diagnostic;
+	constructor(code, diagnostic) {
+		super(code);
+		this.code = code;
+		this.diagnostic = diagnostic;
+		this.name = "IrohIdentityProbeError";
+	}
+};
 function publicStatus$2(status) {
 	return Object.freeze({ ...status });
 }
+function diagnosticText(value, dataDir) {
+	const text = value.toString("utf8").replaceAll(dataDir, "<data-dir>").trim().replace(/\s+/gu, " ");
+	return text === "" ? void 0 : text.slice(0, IDENTITY_DIAGNOSTIC_MAX_BYTES);
+}
+/** The wrapper `tls-prepare` prints when it discards the underlying native cause. */
+const HOST_TLS_PREPARATION_FAILURE = "Error: host TLS preparation failed";
+/**
+* Whether the wrapper is the only explanation stderr carries.
+*
+* Compare lines, never the whole buffer: the probe collapses whitespace for
+* reporting, and a preceding warning or a CRLF terminator must not hide the
+* fact that no cause chain was printed. A `Caused by:` section means the
+* native explanation already reached us, so the extra host run cannot add
+* anything the caller does not already have.
+*/
+function isBareHostTlsPreparationFailure(value, dataDir) {
+	const lines = value.toString("utf8").replaceAll(dataDir, "<data-dir>").split(/\r?\n/gu).map((line) => line.trim()).filter((line) => line !== "");
+	return lines.includes(HOST_TLS_PREPARATION_FAILURE) && !lines.some((line) => /^Caused by:/u.test(line));
+}
+/**
+* Ask the host entry point for the cause chain when `tls-prepare` reports only
+* its top-level wrapper. The command is local-only and bounded; it never
+* downloads a component or enables relay/discovery.
+*/
+async function hostIdentityDiagnostic(executable, dataDir, launch, onSpawn) {
+	const args = [
+		"--lang",
+		"en",
+		"host",
+		"--data-dir",
+		dataDir,
+		"--local-only"
+	];
+	const child = launch === void 0 ? spawn(executable, args, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true
+	}) : launch(executable, args);
+	onSpawn?.(child);
+	let stderrOutput = Buffer.alloc(0);
+	let settled = false;
+	let deadline;
+	return await new Promise((resolve) => {
+		const finish = (value) => {
+			if (settled) return;
+			settled = true;
+			if (deadline !== void 0) clearTimeout(deadline);
+			resolve(value);
+		};
+		deadline = setTimeout(() => {
+			terminateRemoteProcess(child).then(() => {
+				finish(diagnosticText(stderrOutput, dataDir));
+			}, () => {
+				finish(diagnosticText(stderrOutput, dataDir));
+			});
+		}, 5e3);
+		deadline.unref?.();
+		child.stderr?.on("data", (chunk) => {
+			const remaining = IDENTITY_DIAGNOSTIC_MAX_BYTES - stderrOutput.length;
+			if (remaining > 0) stderrOutput = Buffer.concat([stderrOutput, chunk.subarray(0, remaining)]);
+		});
+		child.once("error", () => {
+			finish(diagnosticText(stderrOutput, dataDir));
+		});
+		child.once("close", () => {
+			finish(diagnosticText(stderrOutput, dataDir));
+		});
+		child.stdin?.end();
+	});
+}
 /**
 * Prepare the sidecar's private identity/TLS state and resolve its endpoint.
 *
@@ -15465,16 +16177,21 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 	}) : options.launch(executable, args);
 	options.onSpawn?.(child);
 	let output = Buffer.alloc(0);
+	let stderrOutput = Buffer.alloc(0);
 	let settled = false;
+	const diagnostic = () => {
+		const text = stderrOutput.toString("utf8").replaceAll(dataDir, "<data-dir>").trim().replace(/\s+/gu, " ");
+		return text === "" ? void 0 : text.slice(0, IDENTITY_DIAGNOSTIC_MAX_BYTES);
+	};
 	return await new Promise((resolve, reject) => {
 		const fail = (code) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(deadline);
 			terminateRemoteProcess(child).then(() => {
-				reject(new Error(code));
+				reject(new IrohIdentityProbeError(code, diagnostic()));
 			}, () => {
-				reject(new AggregateError([new Error(code), /* @__PURE__ */ new Error("iroh_probe_stop_failed")], "iroh_identity_cleanup_failed"));
+				reject(new AggregateError([new IrohIdentityProbeError(code, diagnostic()), /* @__PURE__ */ new Error("iroh_probe_stop_failed")], "iroh_identity_cleanup_failed"));
 			});
 		};
 		const deadline = setTimeout(() => {
@@ -15489,7 +16206,10 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 			}
 			output = Buffer.concat([output, chunk]);
 		});
-		child.stderr?.resume();
+		child.stderr?.on("data", (chunk) => {
+			const remaining = IDENTITY_DIAGNOSTIC_MAX_BYTES - stderrOutput.length;
+			if (remaining > 0) stderrOutput = Buffer.concat([stderrOutput, chunk.subarray(0, remaining)]);
+		});
 		child.once("error", () => {
 			fail("iroh_identity_failed");
 		});
@@ -15497,14 +16217,28 @@ async function defaultResolveIdentity(executable, dataDir, options = {}) {
 			clearTimeout(deadline);
 			if (settled) return;
 			settled = true;
+			const probeDiagnostic = diagnostic();
+			if (code !== 0 && probeDiagnostic !== void 0 && isBareHostTlsPreparationFailure(stderrOutput, dataDir)) {
+				hostIdentityDiagnostic(executable, dataDir, options.launch, options.onSpawn).then((detail) => {
+					const resolvedDiagnostic = detail ?? probeDiagnostic;
+					reject(new IrohIdentityProbeError(/private (?:Windows )?data directory is not secure|private path ACL grants/iu.test(resolvedDiagnostic) ? "iroh_data_directory_insecure" : "iroh_identity_invalid", resolvedDiagnostic));
+				}, () => {
+					reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
+				});
+				return;
+			}
+			if (code !== 0 && probeDiagnostic !== void 0 && /private (?:Windows )?data directory is not secure|private path ACL grants/iu.test(probeDiagnostic)) {
+				reject(new IrohIdentityProbeError("iroh_data_directory_insecure", probeDiagnostic));
+				return;
+			}
 			let metadata;
 			try {
 				metadata = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(output));
 			} catch {
-				reject(/* @__PURE__ */ new Error("iroh_identity_invalid"));
+				reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
 				return;
 			}
-			if (code !== 0 || typeof metadata !== "object" || metadata === null || !("version" in metadata) || metadata.version !== 1 || !("endpointId" in metadata) || typeof metadata.endpointId !== "string" || !/^[0-9a-f]{64}$/u.test(metadata.endpointId)) reject(/* @__PURE__ */ new Error("iroh_identity_invalid"));
+			if (code !== 0 || typeof metadata !== "object" || metadata === null || !("version" in metadata) || metadata.version !== 1 || !("endpointId" in metadata) || typeof metadata.endpointId !== "string" || !/^[0-9a-f]{64}$/u.test(metadata.endpointId)) reject(new IrohIdentityProbeError("iroh_identity_invalid", probeDiagnostic));
 			else resolve(metadata.endpointId);
 		});
 	});
@@ -15691,9 +16425,15 @@ var IrohController = class {
 			this.options.onStatus?.(this.status());
 		} catch {}
 	}
-	async failGeneration(generation, errorCode, origin) {
+	async failGeneration(generation, errorCode, origin, diagnostic) {
 		if (generation !== this.generation) return;
 		this.generation += 1;
+		try {
+			this.options.onFailure?.({
+				errorCode,
+				...diagnostic === void 0 ? {} : { diagnostic }
+			});
+		} catch {}
 		this.publish({
 			enabled: this.enabled,
 			state: "error",
@@ -15778,7 +16518,9 @@ var IrohController = class {
 				});
 			} }) : await this.options.resolveIdentity(executable, this.options.dataDirectory);
 		} catch (error) {
-			await this.failGeneration(generation, error instanceof AggregateError ? "iroh_identity_cleanup_failed" : "iroh_identity_failed");
+			const code = error instanceof AggregateError ? "iroh_identity_cleanup_failed" : error instanceof IrohIdentityProbeError ? error.code : "iroh_identity_failed";
+			const diagnostic = error instanceof IrohIdentityProbeError ? error.diagnostic : error instanceof AggregateError && error.errors[0] instanceof IrohIdentityProbeError ? error.errors[0].diagnostic : void 0;
+			await this.failGeneration(generation, code, void 0, diagnostic);
 			return;
 		}
 		if (generation !== this.generation || !this.enabled) return;
@@ -16394,23 +17136,36 @@ function remoteSuffix(origin) {
 		return "地址格式无效";
 	}
 }
+/**
+* Read-only PowerShell that reports whether both managed LAN rules are usable.
+*
+* The verdict mirrors `windowsFirewallSetupScript`'s post-condition: enabled,
+* inbound, allow, and `Profile` exactly `Any`. A Domain/Private-scoped rule is
+* active only on those networks, so reporting it as ready would tell a user on
+* a Public network that nothing needs fixing. The script only reads: it never
+* enables, creates or deletes a rule, and the caller keeps its 3s budget.
+* @param port - managed LAN listener port the rules must cover.
+*/
+function windowsFirewallProbeScript(port) {
+	return [
+		"$specs = @(@{ Name = 'DSH Mobile HTTPS'; Protocol = 'TCP' }, @{ Name = 'DSH Mobile Discovery'; Protocol = 'UDP' })",
+		"$ready = $true",
+		"$specs | ForEach-Object {",
+		"  $spec = $_",
+		"  $rule = Get-NetFirewallRule -DisplayName $spec.Name -ErrorAction SilentlyContinue | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' -and $_.Profile -eq 'Any' } | Select-Object -First 1",
+		"  if ($null -eq $rule) { $ready = $false; return }",
+		"  $filters = @($rule | Get-NetFirewallPortFilter -ErrorAction SilentlyContinue)",
+		`  $matching = @($filters | Where-Object { $_.Protocol -eq $spec.Protocol -and ($_.LocalPort -eq 'Any' -or $_.LocalPort -eq '${String(port)}') })`,
+		"  if ($matching.Count -eq 0) { $ready = $false }",
+		"}",
+		"if ($ready) { 'ready' } else { 'missing' }"
+	].join("; ");
+}
 function defaultFirewallProbe(platform = process.platform) {
 	return async (port) => {
 		if (platform !== "win32") return { state: "not-applicable" };
 		if (port === void 0) return { state: "unknown" };
-		const script = [
-			"$specs = @(@{ Name = 'DSH Mobile HTTPS'; Protocol = 'TCP' }, @{ Name = 'DSH Mobile Discovery'; Protocol = 'UDP' })",
-			"$ready = $true",
-			"$specs | ForEach-Object {",
-			"  $spec = $_",
-			"  $rule = Get-NetFirewallRule -DisplayName $spec.Name -ErrorAction SilentlyContinue | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' } | Select-Object -First 1",
-			"  if ($null -eq $rule) { $ready = $false; return }",
-			"  $filters = @($rule | Get-NetFirewallPortFilter -ErrorAction SilentlyContinue)",
-			`  $matching = @($filters | Where-Object { $_.Protocol -eq $spec.Protocol -and ($_.LocalPort -eq 'Any' -or $_.LocalPort -eq '${String(port)}') })`,
-			"  if ($matching.Count -eq 0) { $ready = $false }",
-			"}",
-			"if ($ready) { 'ready' } else { 'missing' }"
-		].join("; ");
+		const script = windowsFirewallProbeScript(port);
 		try {
 			return { state: (await execFileText("powershell.exe", [
 				"-NoProfile",
@@ -16787,6 +17542,116 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 		})
 	});
 }
+// src/macos-file-access.ts
+/**
+* Reports whether this process already holds the macOS Full Disk Access grant.
+*
+* macOS shows a folder authorization dialog the first time a process reads a
+* protected location (Desktop, Documents, Downloads, external or network
+* volumes). While that dialog waits for a click, the calling thread stays
+* blocked, so an unattended machine can stall every request that needs the
+* file system. Granting Full Disk Access removes that class of dialog.
+*
+* The probe reads the per-user TCC database. That file is itself protected by
+* TCC, so opening it succeeds only for a process macOS already trusts with
+* Full Disk Access; a denied read fails immediately with EACCES/EPERM because
+* the grant can only be made in System Settings and can never be requested
+* through a dialog. The probe therefore never blocks on user input, unlike
+* reading one of the protected folders themselves.
+*/
+/** A final `ok` is sticky; only a non-ok result is retried, at most this often. */
+const DEFAULT_RETRY_MS = 2e3;
+/** A probe that never settles is treated as missing rather than awaited forever. */
+const DEFAULT_TIMEOUT_MS = 2e3;
+/**
+* Caches the Full Disk Access state so a status response can read it
+* synchronously while the file system check stays asynchronous.
+*/
+var MacFileAccessProbe = class {
+	platform;
+	home;
+	readAccess;
+	now;
+	retryMs;
+	timeoutMs;
+	statusValue = "missing";
+	checkedAt = Number.NEGATIVE_INFINITY;
+	activeProbe;
+	constructor(options = {}) {
+		this.platform = options.platform ?? process.platform;
+		this.home = options.home ?? homedir();
+		this.readAccess = options.readAccess ?? ((path) => access(path, constants.R_OK));
+		this.now = options.now ?? Date.now;
+		this.retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+	/** Whether the probe applies to this platform at all. */
+	get applicable() {
+		return this.platform === "darwin";
+	}
+	/** Latest cached result. Never performs I/O. */
+	status() {
+		return this.applicable ? this.statusValue : "ok";
+	}
+	/**
+	* Refresh the cached result when it is not final yet.
+	* @returns The result after this call.
+	*/
+	async refresh() {
+		if (!this.applicable) return "ok";
+		if (this.statusValue === "ok") return "ok";
+		if (this.activeProbe !== void 0) return this.activeProbe;
+		const at = this.now();
+		if (at - this.checkedAt < this.retryMs) return this.statusValue;
+		this.checkedAt = at;
+		const pending = this.probe();
+		this.activeProbe = pending;
+		try {
+			this.statusValue = await pending;
+			return this.statusValue;
+		} finally {
+			if (this.activeProbe === pending) this.activeProbe = void 0;
+		}
+	}
+	/** Run one bounded access check and collapse every failure into `missing`. */
+	async probe() {
+		const database = join(this.home, "Library", "Application Support", "com.apple.TCC", "TCC.db");
+		let timer;
+		try {
+			await Promise.race([this.readAccess(database), new Promise((_resolve, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("macos_file_access_probe_timeout")), this.timeoutMs);
+				timer.unref?.();
+			})]);
+			return "ok";
+		} catch {
+			return "missing";
+		} finally {
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	}
+};
+/** System Settings deep link for the Full Disk Access pane. */
+const MAC_FULL_DISK_ACCESS_PANE = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+/** Absolute path so a GUI-launched process does not depend on PATH. */
+const OPEN_COMMAND = "/usr/bin/open";
+function runCommand(file, args) {
+	return new Promise((resolve, reject) => {
+		execFile(file, [...args], (error) => {
+			if (error === null) resolve();
+			else reject(error);
+		});
+	});
+}
+/**
+* Open the Full Disk Access pane from the host process.
+*
+* The desktop app's renderer refuses to navigate to a custom scheme, so the
+* button cannot use `window.open`; `open` runs on the Mac that owns the app.
+* @param run - Command runner, injectable for tests.
+*/
+async function openMacFullDiskAccessSettings(run = runCommand) {
+	await run(OPEN_COMMAND, [MAC_FULL_DISK_ACCESS_PANE]);
+}
 // src/mobile-guide.ts
 /** Compose the guide with the current customization state injected. */
 function buildMobileGuide(state) {
@@ -19926,11 +20791,33 @@ function launchedProfileName(argv) {
 	}
 	return "web";
 }
+function profileInstallingModule(dshHome, moduleUrl) {
+	let directory;
+	try {
+		directory = dirname(fileURLToPath(moduleUrl));
+	} catch {
+		return;
+	}
+	const profilesRoot = resolve(dshHome, "profiles");
+	for (let depth = 0; depth < 16; depth += 1) {
+		const candidate = resolve(directory);
+		const fromProfiles = relative(profilesRoot, candidate);
+		if (fromProfiles !== "" && !fromProfiles.startsWith("..") && !isAbsolute(fromProfiles)) try {
+			const manifest = JSON.parse(readFileSync(join(candidate, "package.json"), "utf8"));
+			if (typeof manifest.dependencies?.[PACKAGE_NAME] === "string" && typeof manifest.dsh?.profile === "object" && manifest.dsh.profile !== null) return candidate;
+		} catch {}
+		const parent = dirname(candidate);
+		if (parent === candidate) break;
+		directory = parent;
+	}
+}
 /** Resolve the launcher-owned Desktop profile, or the CLI profile outside Desktop. */
-function releaseProfileDirectory(ctx, dshHome, argv) {
+function releaseProfileDirectory(ctx, dshHome, argv, moduleUrl = import.meta.url) {
 	const desktopProfiles = ctx.get("desktopProfiles");
 	const desktopDirectory = desktopProfiles?.current?.dir;
 	if (typeof desktopDirectory === "string" && isAbsolute(desktopDirectory)) return desktopDirectory;
+	const installedProfile = profileInstallingModule(dshHome, moduleUrl);
+	if (installedProfile !== void 0) return installedProfile;
 	if (desktopProfiles !== void 0 || ctx.get("desktopRuntime") !== void 0) return void 0;
 	return join(dshHome, "profiles", launchedProfileName(argv));
 }
@@ -21432,7 +22319,8 @@ function validSource(value) {
 		"lifetime",
 		"turn",
 		"callId",
-		"goal"
+		"goal",
+		"custom"
 	])) return false;
 	return [
 		value.sourceId,
@@ -21449,7 +22337,7 @@ function validSource(value) {
 		"live",
 		"projected",
 		"committed"
-	].includes(String(value.lifetime)) && (value.turn === void 0 || Number.isSafeInteger(value.turn)) && (value.callId === void 0 || typeof value.callId === "string") && (value.goal === void 0 || object(value.goal) && only(value.goal, ["id", "revision"]) && typeof value.goal.id === "string" && Number.isSafeInteger(value.goal.revision));
+	].includes(String(value.lifetime)) && (value.turn === void 0 || Number.isSafeInteger(value.turn)) && (value.callId === void 0 || typeof value.callId === "string") && (value.goal === void 0 || object(value.goal) && only(value.goal, ["id", "revision"]) && typeof value.goal.id === "string" && Number.isSafeInteger(value.goal.revision)) && (value.custom === void 0 || object(value.custom) && only(value.custom, ["title", "body"]) && typeof value.custom.title === "string" && value.custom.title.length > 0 && value.custom.title.length <= 80 && !/[\u0000-\u001f\u007f]/u.test(value.custom.title) && typeof value.custom.body === "string" && value.custom.body.length > 0 && value.custom.body.length <= 200 && !/[\u0000-\u001f\u007f]/u.test(value.custom.body));
 }
 function scopedCounts(rows, scope, maximum = 1024) {
 	const counts = /* @__PURE__ */ new Map();
@@ -22065,10 +22953,11 @@ function validateNavigate(navigate, category) {
 	if (typeof navigate !== "string" || !/^\/\?mobile-push=[A-Za-z0-9_-]{1,256}$/u.test(navigate)) throw new TypeError("push_navigation_invalid");
 }
 /** Build Apple's declarative Web Push schema with generic, locale-owned text. */
-function buildDeclarativePayload(category, locale, navigate, tag) {
+function buildDeclarativePayload(category, locale, navigate, tag, custom) {
 	validateNavigate(navigate, category);
 	if (!(locale in messages) || !(category in messages[locale]) || typeof tag !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/u.test(tag)) throw new TypeError("push_payload_invalid");
-	const [title, body] = messages[locale][category];
+	if (custom !== void 0 && (typeof custom.title !== "string" || custom.title.length === 0 || custom.title.length > 80 || typeof custom.body !== "string" || custom.body.length === 0 || custom.body.length > 200)) throw new TypeError("push_payload_invalid");
+	const [title, body] = custom === void 0 ? messages[locale][category] : [custom.title, custom.body];
 	const payload = JSON.stringify({
 		web_push: 8030,
 		notification: {
@@ -22408,6 +23297,12 @@ function sameKey(a, b) {
 function isPreferenceEnabled(preferences, category) {
 	return preferences[category] === true;
 }
+function notificationText(value, maximum, label) {
+	if (typeof value !== "string") throw new TypeError(`push_${label}_invalid`);
+	const text = value.trim().replace(/[\u0000-\u001f\u007f]+/gu, " ");
+	if (text.length === 0 || text.length > maximum) throw new TypeError(`push_${label}_invalid`);
+	return text;
+}
 function pendingHas(snapshot, intent) {
 	return snapshot.pending.some((item) => item.id === intent.id && sameKey(item.key, intent.key));
 }
@@ -22521,6 +23416,51 @@ var PushDelivery = class {
 			this.#kick();
 		});
 	}
+	/**
+	* Queue trusted Host-plugin text for every enabled web-push recipient that
+	* opted into the selected notification category. The source keeps its own
+	* short expiry; a restart may still retry it only inside that window.
+	*/
+	async notifyCustom(input) {
+		if (!this.#started || this.#closed || !this.#admitting) throw new Error("push_unavailable");
+		const sessionId = typeof input.sessionId === "string" ? input.sessionId.trim() : "";
+		if (sessionId === "" || sessionId.length > 4096) throw new TypeError("push_session_id_invalid");
+		const title = notificationText(input.title, 80, "title");
+		const body = notificationText(input.body, 200, "body");
+		const category = input.category ?? "response";
+		if (![
+			"question",
+			"plan",
+			"approval",
+			"response",
+			"goal",
+			"failure"
+		].includes(category)) throw new TypeError("push_category_invalid");
+		const now = this.#now();
+		const maximumExpiry = now + OUTCOME_TTL_MS;
+		if (input.expiresAt !== void 0 && (!Number.isSafeInteger(input.expiresAt) || input.expiresAt <= now)) throw new TypeError("push_expiry_invalid");
+		const expiresAt = Math.min(input.expiresAt ?? maximumExpiry, maximumExpiry);
+		if (!await this.#host.sessionExists(sessionId)) throw new Error("push_session_unavailable");
+		const source = {
+			sourceId: `custom:${randomUUID()}`,
+			sessionId,
+			targetSessionId: sessionId,
+			category,
+			createdAt: now,
+			expiresAt,
+			lifetime: "committed",
+			custom: {
+				title,
+				body
+			}
+		};
+		const queued = await this.#admit(source);
+		this.#kick();
+		return {
+			queued,
+			expiresAt
+		};
+	}
 	async resolve(owner, reference) {
 		if (this.#closed || !reference) return void 0;
 		let snapshot;
@@ -22560,14 +23500,15 @@ var PushDelivery = class {
 		this.#origins.clear();
 	}
 	async #admit(source) {
-		if (!this.#admitting || source.expiresAt <= this.#now()) return;
+		if (!this.#admitting || source.expiresAt <= this.#now()) return 0;
 		let eligible = false;
 		try {
-			eligible = this.#host.available && await this.#host.eligible(source);
+			eligible = source.custom === void 0 ? this.#host.available && await this.#host.eligible(source) : this.#host.available && await this.#host.sessionExists(source.sessionId);
 		} catch {
 			eligible = false;
 		}
-		if (!eligible || source.expiresAt <= this.#now()) return;
+		if (!eligible || source.expiresAt <= this.#now()) return 0;
+		let queued = 0;
 		for (const origin of this.#origins.values()) {
 			if (!origin.active || this.#closed) continue;
 			const devices = await this.#readAuthorized(origin);
@@ -22576,7 +23517,7 @@ var PushDelivery = class {
 			try {
 				snapshot = this.#registry.snapshot();
 			} catch {
-				return;
+				return queued;
 			}
 			const registrations = snapshot.registrations.filter((reg) => reg.scopeId === origin.scopeId && reg.origin === origin.origin && devices.has(reg.deviceId) && reg.enabled && reg.health === "ready" && isPreferenceEnabled(reg.preferences, source.category) && snapshot.keys?.fingerprint === reg.keyFingerprint);
 			if (registrations.length === 0) continue;
@@ -22605,6 +23546,7 @@ var PushDelivery = class {
 						attempts: 0,
 						nextAttemptAt: this.#now()
 					});
+					queued += 1;
 				}
 				return {
 					...clean,
@@ -22613,6 +23555,7 @@ var PushDelivery = class {
 			});
 		}
 		this.#kick();
+		return queued;
 	}
 	async #reconcileKnownScopes() {
 		let snapshot;
@@ -22797,7 +23740,7 @@ var PushDelivery = class {
 			await this.#removeIntent(intent);
 			return;
 		}
-		const payload = buildDeclarativePayload(intent.source.category, registration.locale, `/?mobile-push=${reference}`, intent.source.sourceId.replace(/[^A-Za-z0-9._:-]/gu, "_").slice(0, 128) || "push");
+		const payload = buildDeclarativePayload(intent.source.category, registration.locale, `/?mobile-push=${reference}`, intent.source.sourceId.replace(/[^A-Za-z0-9._:-]/gu, "_").slice(0, 128) || "push", intent.source.custom);
 		let result;
 		try {
 			result = await this.#sender.send({
@@ -22907,6 +23850,11 @@ var PushDelivery = class {
 	/** Maps the Host tri-state for durable-work decisions; boolean eligible() would collapse transient uncertainty into denial. */
 	async #sourceGuard(source) {
 		if (!this.#host.available) return "unverifiable";
+		if (source.custom !== void 0) try {
+			return await this.#host.sessionExists(source.sessionId) ? "allowed" : "denied";
+		} catch {
+			return "unverifiable";
+		}
 		let result;
 		try {
 			result = await this.#host.reconcile(source);
@@ -23260,6 +24208,10 @@ var PushGatewayCoordinator = class {
 			installationId
 		});
 	}
+	async notifyCustom(input) {
+		if (!this.host.available) throw new Error("push_unavailable");
+		return await this.delivery.notifyCustom(input);
+	}
 	async resolve(owner, reference) {
 		if (!this.host.available || !await this.authorize(owner, true)) return void 0;
 		return this.delivery.resolve(owner, reference);
@@ -23377,34 +24329,132 @@ function withInstallationIdentity(config, installationId, explicitIdentity) {
 // src/lan-setup.ts
 const FIREWALL_TCP_RULE = "DSH Mobile HTTPS";
 const FIREWALL_UDP_RULE = "DSH Mobile Discovery";
+const MIN_MANAGED_PORT = 1024;
+const MAX_MANAGED_PORT = 65535;
+function assertManagedPort(port, name) {
+	if (!Number.isSafeInteger(port) || port < MIN_MANAGED_PORT || port > MAX_MANAGED_PORT) throw new Error(`${name} must be from ${String(MIN_MANAGED_PORT)} through ${String(MAX_MANAGED_PORT)}`);
+}
+/** Longest failure detail carried in the thrown message. */
+const MAX_FAILURE_DETAIL_CHARS = 512;
+/**
+* Strip the elevated invocation and filesystem locations from PowerShell text.
+*
+* The launcher's stderr quotes the command it ran, including the base64
+* `-EncodedCommand` payload, and the elevated script quotes its own scratch
+* path. Neither helps an operator, and both can push the one useful line past
+* the length bound, so they are replaced before the detail is bounded.
+*/
+function redactPowerShellDetail(value) {
+	return value.replace(/EncodedCommand\s+\S+/giu, "EncodedCommand <redacted>").replace(/\b[A-Za-z0-9+/]{64,}={0,2}\b/gu, "<redacted>").replace(/(?<![A-Za-z])[A-Za-z]:[\\/][^\s'"]*/gu, "<path>");
+}
+/** Bounded, redacted detail for a failed elevated Windows operation. */
+function powerShellFailureDetail(error, innerError = "") {
+	if (!(error instanceof Error)) return "unknown failure";
+	const code = "code" in error && (typeof error.code === "string" || typeof error.code === "number") ? ` (${String(error.code)})` : "";
+	const detail = redactPowerShellDetail(innerError.trim() === "" && "stderr" in error && typeof error.stderr === "string" ? error.stderr : innerError).trim().replace(/\s+/gu, " ").slice(0, MAX_FAILURE_DETAIL_CHARS);
+	return `${code}${detail === "" ? "" : `: ${detail}`}`;
+}
+/** Default sink for a scratch directory that could not be removed. */
+function warnFirewallCleanupFailure(detail) {
+	process.emitWarning(`Windows firewall temporary cleanup failed (${detail})`, { code: "DSH_MOBILE_FIREWALL_CLEANUP_FAILED" });
+}
+/**
+* Remove the elevated helper's scratch directory without touching the run's outcome.
+*
+* The directory is created before elevation and removed in a `finally`, so a
+* cleanup failure must not replace the firewall error that explains the
+* failure, and must not fail a run that already succeeded. It stays observable
+* instead: the removal error's code is reported to the warning sink, whose own
+* failure is ignored for the same reason.
+* @param directory - scratch path created for this run.
+* @param options - injectable removal and warning sink for tests.
+*/
+async function discardFirewallScratch(directory, options = {}) {
+	const remove = options.remove ?? ((path) => rm(path, {
+		recursive: true,
+		force: true
+	}));
+	try {
+		await remove(directory);
+	} catch (error) {
+		const code = error !== null && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : "unknown";
+		const warn = options.warn ?? warnFirewallCleanupFailure;
+		try {
+			warn(code);
+		} catch {}
+	}
+}
 async function runElevatedPowerShell(script) {
-	await execFileText("powershell.exe", [
-		"-NoProfile",
-		"-NonInteractive",
-		"-Command",
-		[
-			"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
-			`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(script, "utf16le").toString("base64")}')`,
-			"; exit $process.ExitCode"
-		].join(" ")
-	], { windowsHide: true });
-}
-/** Install the two Windows inbound rules used by the managed LAN listener. */
+	const temporary = await mkdtemp(join(tmpdir(), "dsh-mobile-firewall-"));
+	const errorFile = join(temporary, "error.log");
+	const wrapped = [
+		`$__dshMobileErrorFile = '${errorFile.replaceAll("'", "''")}'`,
+		"try {",
+		script,
+		"} catch {",
+		"  try { [IO.File]::WriteAllText($__dshMobileErrorFile, ($_ | Out-String)) } catch {}",
+		"  throw",
+		"}"
+	].join("\n");
+	const launch = [
+		"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
+		`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(wrapped, "utf16le").toString("base64")}')`,
+		"; exit $process.ExitCode"
+	].join(" ");
+	try {
+		await execFileText("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			launch
+		], { windowsHide: true });
+	} catch (error) {
+		let innerError = "";
+		try {
+			innerError = (await readFile(errorFile, "utf8")).replace(/^\uFEFF/u, "");
+		} catch {}
+		throw new Error(`Windows firewall operation failed${powerShellFailureDetail(error, innerError)}`, { cause: error });
+	} finally {
+		await discardFirewallScratch(temporary);
+	}
+}
+function firewallRuleScript(name, protocol, port) {
+	return [
+		`$rules = @(Get-NetFirewallRule -DisplayName '${name}' -ErrorAction SilentlyContinue)`,
+		"if ($rules.Count -eq 0) {",
+		`  New-NetFirewallRule -DisplayName '${name}' -Direction Inbound -Action Allow -Protocol ${protocol} -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`,
+		"} else {",
+		"  foreach ($rule in $rules) {",
+		"    $rule | Set-NetFirewallRule -Enabled True -Direction Inbound -Action Allow -Profile Any",
+		`    $rule | Get-NetFirewallPortFilter | Set-NetFirewallPortFilter -Protocol ${protocol} -LocalPort ${String(port)}`,
+		"    $rule | Get-NetFirewallAddressFilter | Set-NetFirewallAddressFilter -RemoteAddress LocalSubnet",
+		"  }",
+		"}",
+		`$verified = @(Get-NetFirewallRule -DisplayName '${name}' -ErrorAction Stop | Where-Object { $_.Enabled -eq 'True' -and $_.Direction -eq 'Inbound' -and $_.Action -eq 'Allow' -and $_.Profile -eq 'Any' })`,
+		`$matchingPort = @($verified | Get-NetFirewallPortFilter | Where-Object { $_.Protocol -eq '${protocol}' -and $_.LocalPort -contains '${String(port)}' })`,
+		`$matchingAddress = @($verified | Get-NetFirewallAddressFilter | Where-Object { $_.RemoteAddress -contains 'LocalSubnet' })`,
+		`if ($verified.Count -eq 0 -or $matchingPort.Count -eq 0 -or $matchingAddress.Count -eq 0) { throw "DSH Mobile firewall rule '${name}' is not active with the expected scope" }`
+	];
+}
+/** Build the elevated Windows firewall script without removing a working rule first. */
+function windowsFirewallSetupScript(port) {
+	assertManagedPort(port, "Windows firewall port");
+	return [
+		"$ErrorActionPreference = 'Stop'",
+		...firewallRuleScript(FIREWALL_TCP_RULE, "TCP", port),
+		...firewallRuleScript(FIREWALL_UDP_RULE, "UDP", port)
+	].join("\n");
+}
+/** Install or update the two Windows inbound rules used by the managed LAN listener. */
 async function configureWindowsFirewall(port) {
 	if (process.platform !== "win32") return;
-	await runElevatedPowerShell([
-		"$ErrorActionPreference = 'Stop'",
-		`Get-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
-		`Get-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
-		`New-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -Direction Inbound -Action Allow -Protocol TCP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`,
-		`New-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -Direction Inbound -Action Allow -Protocol UDP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`
-	].join("; "));
+	await runElevatedPowerShell(windowsFirewallSetupScript(port));
 }
 /** Generate private TLS material and persist a managed setup selected by the user. */
 async function prepareManagedLanSetup(options) {
 	if (!isAbsolute(options.setupFile) || !isAbsolute(options.controlFile)) throw new Error("managed LAN setup paths must be absolute");
-	if (!Number.isSafeInteger(options.listenPort) || options.listenPort < 1024 || options.listenPort > 65535) throw new Error("managed LAN listenPort must be from 1024 through 65535");
-	if (!Number.isSafeInteger(options.dshPort) || options.dshPort < 1024 || options.dshPort > 65535) throw new Error("managed LAN dshPort must be from 1024 through 65535");
+	assertManagedPort(options.listenPort, "managed LAN listenPort");
+	assertManagedPort(options.dshPort, "managed LAN dshPort");
 	const directory = dirname(options.setupFile);
 	const tlsDirectory = join(directory, "tls");
 	await mkdir(tlsDirectory, {
@@ -23876,6 +24926,7 @@ async function apply(ctx, config) {
 		if (service === void 0) throw new Error("push_unavailable");
 		return service;
 	};
+	new MobilePushService(ctx, async (input) => (await requiredPushGatewayService()).notifyCustom(input));
 	const queueDeviceInvalidations = (scopeId, deviceIds) => {
 		let queued = pendingDeviceInvalidations.get(scopeId);
 		if (queued === void 0) pendingDeviceInvalidations.set(scopeId, queued = /* @__PURE__ */ new Set());
@@ -23950,6 +25001,11 @@ async function apply(ctx, config) {
 		async test(owner, installationId) {
 			await (await requiredPushGatewayService()).test(owner, installationId);
 		},
+		async notifyCustom(input) {
+			const service = await requiredPushGatewayService();
+			if (service.notifyCustom === void 0) throw new Error("push_unavailable");
+			return await service.notifyCustom(input);
+		},
 		async resolve(owner, reference) {
 			return (await requiredPushGatewayService()).resolve(owner, reference);
 		}
@@ -24042,6 +25098,7 @@ async function apply(ctx, config) {
 	const cloudflaredComponent = new CloudflaredComponentManager({ stateDirectory });
 	await cloudflaredComponent.initialize();
 	const frpComponent = new FrpComponentManager({ stateDirectory });
+	const macFileAccess = new MacFileAccessProbe();
 	await frpComponent.initialize();
 	const irohComponent = new IrohComponentManager({
 		stateDirectory,
@@ -24301,6 +25358,9 @@ async function apply(ctx, config) {
 		component: irohComponent,
 		dataDirectory: join(remoteDirectory, "iroh", "sidecar"),
 		createGateway: (endpointId) => createIrohGateway(endpointId),
+		onFailure: ({ errorCode, diagnostic }) => {
+			logger.warn("iroh startup failed: %s%s", errorCode, diagnostic === void 0 ? "" : `; ${diagnostic}`);
+		},
 		/**
 		* Read the pairing CA the live gateway advertises. The fingerprint must
 		* match the gateway instance id, otherwise a rotated CA would mint QR
@@ -24389,7 +25449,10 @@ async function apply(ctx, config) {
 		originMode: originController.mode(),
 		caddyConfiguration: caddyConfig.status(),
 		caddyState: caddyController.status(),
-		...process.platform === "darwin" ? { macosHost: true } : {}
+		...macFileAccess.applicable ? {
+			macosHost: true,
+			macFileAccess: macFileAccess.status()
+		} : {}
 	});
 	const lanPayload = () => ({
 		...loaded.kind === "unconfigured" ? {
@@ -24713,9 +25776,16 @@ async function apply(ctx, config) {
 					return;
 				}
 				if (request.method === "GET" && target.decodedPathname === `/api/mobile-access/remote/control`) {
+					await macFileAccess.refresh();
 					sendJson(response, 200, remotePayload(), false);
 					return;
 				}
+				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/macos-file-access/open-settings`) {
+					if (!macFileAccess.applicable) throw new HttpError(404, "not_found");
+					await openMacFullDiskAccessSettings();
+					sendJson(response, 200, { opened: true }, false);
+					return;
+				}
 				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/provider`) {
 					const body = await readJsonObject(request, 4096);
 					if (body.provider !== "tailscale" && body.provider !== "cpolar" && body.provider !== "cloudflared" && body.provider !== "frp" && body.provider !== "origin" && body.provider !== "iroh") throw new HttpError(400, "bad_request");
@@ -25271,6 +26341,6 @@ async function apply(ctx, config) {
 		};
 	}, "dsh-mobile: independent LAN and selectable remote providers with /mobile command");
 }
-export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CLOUDFLARED_COMPONENT_RELEASES, CPOLAR_COMPONENT_RELEASE, CPOLAR_COMPONENT_RELEASES, CSRF_COOKIE, CSRF_HEADER, ClientModuleConflictError, ClientModulePreferenceStore, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, CpolarComponentManager, DEFAULT_IROH_LOCAL_PORT, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, IROH_COMPONENT_RELEASES, IROH_LEAF_RENEW_BEFORE_DAYS, IROH_LEAF_VALIDITY_DAYS, IROH_VERSION, IrohComponentManager, IrohController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_PAIRING_DESCRIPTOR_BYTES, MAX_PAIRING_LIFETIME_MS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, OriginConfigStore, OriginController, PAIRING_DESCRIPTOR_LOCAL_PORT, PAIRING_DESCRIPTOR_TYPE, PAIRING_DESCRIPTOR_VERSION, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, decodePairingDescriptor, encodePairingDescriptor, ensureFrpIngressCertificate, ensureIrohTls, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, irohGatewayConfig, irohHostname, irohOrigin, irohTlsPaths, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, resolveHostExecution, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateIrohOrigin, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validatePairingDescriptor, validateWebSocketPath, watchTaskCompletions };
+export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CLOUDFLARED_COMPONENT_RELEASES, CPOLAR_COMPONENT_RELEASE, CPOLAR_COMPONENT_RELEASES, CSRF_COOKIE, CSRF_HEADER, ClientModuleConflictError, ClientModulePreferenceStore, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, CpolarComponentManager, DEFAULT_IROH_LOCAL_PORT, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, IROH_COMPONENT_RELEASES, IROH_LEAF_RENEW_BEFORE_DAYS, IROH_LEAF_VALIDITY_DAYS, IROH_VERSION, IrohComponentManager, IrohController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_PAIRING_DESCRIPTOR_BYTES, MAX_PAIRING_LIFETIME_MS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, MobilePushService, OriginConfigStore, OriginController, PAIRING_DESCRIPTOR_LOCAL_PORT, PAIRING_DESCRIPTOR_TYPE, PAIRING_DESCRIPTOR_VERSION, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, decodePairingDescriptor, encodePairingDescriptor, ensureFrpIngressCertificate, ensureIrohTls, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, irohGatewayConfig, irohHostname, irohOrigin, irohTlsPaths, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, resolveHostExecution, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateIrohOrigin, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validatePairingDescriptor, validateWebSocketPath, watchTaskCompletions };
 
 //# sourceMappingURL=index.mjs.map