dsh-deeppilot 0.6.0 → 0.6.1

package/lib/index.js

@@ -3,18 +3,253 @@ import { createHash, createPrivateKey, createPublicKey, randomBytes, randomUUID,
 import { access, chmod, mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { WebSocketServer } from "ws";
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir, networkInterfaces } from "node:os";
 import * as Cordis from "@deepseek-ai/cordis";
 import { Context } from "@deepseek-ai/cordis";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { connect } from "node:http2";
 import { spawn } from "node:child_process";
-import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { request } from "node:https";
 import z from "@deepseek-ai/schemastery";
 import { isIP } from "node:net";
 import { createServer } from "node:http";
+function validSendId(id) {
+	return typeof id === "string" && /^\d{13}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+}
+/** Durable at-most-once dispatch. Unknown outcomes are never automatically retried. */
+var PromptDeliveryJournal = class {
+	path;
+	capacity;
+	entries = Object.create(null);
+	inFlight = /* @__PURE__ */ new Map();
+	healthy = true;
+	constructor(path, capacity = 1e4) {
+		this.path = path;
+		this.capacity = capacity;
+		if (!path || !existsSync(path)) return;
+		try {
+			if (statSync(path).size > 8388608) throw new Error("oversized journal");
+			const parsed = JSON.parse(readFileSync(path, "utf8"));
+			if (parsed.version !== 1 || !Array.isArray(parsed.entries) || parsed.entries.length > capacity) throw new Error("invalid journal");
+			for (const [key, value] of parsed.entries) {
+				if (typeof key !== "string" || !/^[a-f0-9]{64}$/.test(key) || !value || typeof value.sessionId !== "string" || !Number.isFinite(value.createdAt) || typeof value.fingerprint !== "string" || !validSendId(value.receipt?.clientSendId) || ![
+					"accepted",
+					"rejected",
+					"unknown"
+				].includes(value.receipt.status)) throw new Error("invalid entry");
+				if (!/^[a-f0-9]{64}$/.test(value.fingerprint) || value.createdAt !== Number(value.receipt.clientSendId.slice(0, 13)) || value.receipt.status === "accepted" && !Number.isSafeInteger(value.receipt.userSeq) || value.receipt.status === "rejected" && ![
+					"E_BUSY",
+					"E_NOT_FOUND",
+					"E_PROTOCOL",
+					"E_UNSUPPORTED"
+				].includes(value.receipt.code)) throw new Error("invalid receipt");
+				this.entries[key] = value;
+			}
+		} catch {
+			this.healthy = false;
+		}
+	}
+	key(deviceId, id) {
+		return createHash("sha256").update(JSON.stringify([deviceId, id])).digest("hex");
+	}
+	expired(id, now = Date.now()) {
+		const age = now - Number(id.slice(0, 13));
+		return age > 6048e5 || age < -3e5;
+	}
+	save() {
+		if (!this.path) return;
+		mkdirSync(dirname(this.path), {
+			recursive: true,
+			mode: 448
+		});
+		const temp = this.path + "." + randomUUID() + ".tmp";
+		const fd = openSync(temp, "wx", 384);
+		try {
+			writeFileSync(fd, JSON.stringify({
+				version: 1,
+				entries: Object.entries(this.entries)
+			}));
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(temp, this.path);
+		const dir = openSync(dirname(this.path), "r");
+		try {
+			fsyncSync(dir);
+		} finally {
+			closeSync(dir);
+		}
+	}
+	lookup(deviceId, sessionId, id) {
+		if (!this.healthy) return {
+			clientSendId: id,
+			status: "unknown"
+		};
+		const entry = this.entries[this.key(deviceId, id)];
+		if (entry && entry.sessionId === sessionId) return entry.receipt;
+		return {
+			clientSendId: id,
+			status: this.expired(id) ? "expired" : "notFound"
+		};
+	}
+	async dispatch(deviceId, sessionId, id, content, operation) {
+		const key = this.key(deviceId, id);
+		const fingerprint = createHash("sha256").update(JSON.stringify([sessionId, content])).digest("hex");
+		const existing = this.entries[key];
+		if (existing) {
+			if (existing.fingerprint !== fingerprint) return {
+				clientSendId: id,
+				status: "rejected",
+				code: "E_PROTOCOL"
+			};
+			return this.inFlight.get(key) ?? existing.receipt;
+		}
+		if (!this.healthy) return {
+			clientSendId: id,
+			status: "unknown"
+		};
+		if (this.expired(id)) return {
+			clientSendId: id,
+			status: "expired"
+		};
+		for (const [key, value] of Object.entries(this.entries)) if (Date.now() - value.createdAt > 6051e5 && !this.inFlight.has(key)) delete this.entries[key];
+		if (Object.keys(this.entries).length >= this.capacity) return {
+			clientSendId: id,
+			status: "rejected",
+			code: "E_BUSY"
+		};
+		const entry = {
+			fingerprint,
+			sessionId,
+			createdAt: Number(id.slice(0, 13)),
+			receipt: {
+				clientSendId: id,
+				status: "unknown"
+			}
+		};
+		this.entries[key] = entry;
+		try {
+			this.save();
+		} catch {
+			this.healthy = false;
+			return entry.receipt;
+		}
+		const run = (async () => {
+			try {
+				const result = await operation();
+				if (result.ok) entry.receipt = {
+					clientSendId: id,
+					status: "accepted",
+					userSeq: result.value
+				};
+				else if ([
+					"busy",
+					"not-found",
+					"invalid",
+					"unsupported"
+				].includes(result.kind)) {
+					const code = {
+						busy: "E_BUSY",
+						"not-found": "E_NOT_FOUND",
+						invalid: "E_PROTOCOL",
+						unsupported: "E_UNSUPPORTED"
+					}[result.kind];
+					entry.receipt = {
+						clientSendId: id,
+						status: "rejected",
+						code
+					};
+				}
+			} catch {}
+			try {
+				this.save();
+			} catch {
+				this.healthy = false;
+			}
+			return entry.receipt;
+		})();
+		this.inFlight.set(key, run);
+		try {
+			return await run;
+		} finally {
+			this.inFlight.delete(key);
+		}
+	}
+};
+const journals = /* @__PURE__ */ new Map();
+function openDeliveryJournal(path) {
+	if (!path) return new PromptDeliveryJournal();
+	let journal = journals.get(path);
+	if (!journal) {
+		journal = new PromptDeliveryJournal(path);
+		journals.set(path, journal);
+	}
+	return journal;
+}
+//#endregion
+//#region src/request-validation.ts
+/** Shape and resource limits for authenticated client requests. Unknown fields
+* remain accepted for additive protocol-v2 compatibility. Business validation
+* (supported models, pending choices, permissions) stays with its owner. */
+function validateRequest(type, value) {
+	const empty = /* @__PURE__ */ new Set([
+		"c2s.ping",
+		"c2s.sessions.list",
+		"c2s.pending.list",
+		"c2s.workspaces.list",
+		"c2s.directory.pick"
+	]);
+	if (value === void 0 && (type === "c2s.session.create" || type === "c2s.directory.list")) value = {};
+	if (value == null && empty.has(type)) return;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return "payload must be an object";
+	const p = value;
+	const text = (v, max = 4096, nonempty = true) => typeof v === "string" && v.length <= max && (!nonempty || v.trim().length > 0);
+	const optional = (key, check) => p[key] === void 0 || check(p[key]);
+	const integer = (v, min, max) => typeof v === "number" && Number.isSafeInteger(v) && v >= min && v <= max;
+	if (type.startsWith("c2s.session.") && type !== "c2s.session.create" && !text(p.sessionId)) return "invalid sessionId";
+	if (type === "c2s.session.create" && (!optional("workspaceId", (v) => text(v)) || !optional("cwd", (v) => text(v, 32768)) || p.workspaceId !== void 0 && p.cwd !== void 0)) return "invalid workspace selection";
+	if (type === "c2s.directory.list" && !optional("path", (v) => text(v, 32768, false))) return "invalid path";
+	if (type === "c2s.workspace.create" && !text(p.path, 32768)) return "invalid path";
+	if (type === "c2s.session.open" && !optional("tailCount", (v) => integer(v, 1, 1e4))) return "invalid tailCount";
+	if (type === "c2s.session.history" && (!integer(p.beforeSeq, 0, Number.MAX_SAFE_INTEGER) || !optional("limit", (v) => integer(v, 1, 500)))) return "invalid history range";
+	if (type === "c2s.session.rename" && !text(p.title, 4096)) return "invalid title";
+	if (type === "c2s.session.attachment" && !text(p.attachmentId)) return "invalid attachmentId";
+	if (type === "c2s.session.selectModel" && (!text(p.provider, 256) || !text(p.model, 1024) || !optional("reasoningEffort", (v) => text(v, 128, false)))) return "invalid model selection";
+	if (type === "c2s.session.delivery" && !validSendId(p.clientSendId)) return "invalid clientSendId";
+	if (type === "c2s.session.sendPrompt") {
+		if (p.clientSendId !== void 0 && !validSendId(p.clientSendId)) return "invalid clientSendId";
+		if (!optional("text", (v) => text(v, 262144, false)) || !optional("images", Array.isArray) || !optional("documents", Array.isArray)) return "invalid prompt fields";
+		for (const key of ["images", "documents"]) {
+			const items = p[key];
+			if (items && items.some((v) => v === null || typeof v !== "object" || Array.isArray(v))) return "invalid attachment";
+			for (const item of items ?? []) {
+				if (item.name !== void 0 && !text(item.name, 4096, false)) return "invalid attachment name";
+				if (item.truncated !== void 0 && typeof item.truncated !== "boolean") return "invalid truncated flag";
+			}
+		}
+	}
+	if (type === "c2s.approval.respond" || type === "c2s.question.respond") {
+		if (!text(p.requestId)) return "invalid requestId";
+	}
+	if (type === "c2s.approval.respond" && (!["allow", "deny"].includes(p.decision) || !optional("reason", (v) => text(v, 65536, false)))) return "invalid approval response";
+	if (type === "c2s.question.respond") {
+		if (!Array.isArray(p.answers) || p.answers.length > 100) return "invalid answers";
+		const ids = /* @__PURE__ */ new Set();
+		for (const answer of p.answers) {
+			if (!answer || typeof answer !== "object" || Array.isArray(answer) || !text(answer.id) || ids.has(answer.id) || !Array.isArray(answer.selected) || answer.selected.length > 100 || !answer.selected.every((v) => text(v, 4096)) || answer.custom !== void 0 && !text(answer.custom, 65536)) return "invalid answer";
+			ids.add(answer.id);
+		}
+	}
+	if (type === "c2s.push.register" || type === "c2s.widget.push.register") {
+		if (p.environment !== void 0 && p.environment !== "production" && p.environment !== "development") return "invalid APNs environment";
+		if (!optional("enrollKey", (v) => text(v, 128))) return "invalid enrollKey";
+		if (p.categories !== void 0 && (!p.categories || typeof p.categories !== "object" || Array.isArray(p.categories) || Object.values(p.categories).some((v) => typeof v !== "boolean"))) return "invalid categories";
+	}
+}
+//#endregion
 //#region src/device-auth.ts
 function getPairingCodeTtlMs() {
 	return Number(process.env.DEEPPILOT_PAIRING_TTL_MS) || 3e5;
@@ -226,7 +461,8 @@ var DeviceStore = class DeviceStore {
 			scopes: normalizeDeviceScopes(record.scopes),
 			firstSeenTs: existing?.firstSeenTs ?? now,
 			lastSeenTs: now,
-			...existing?.apns ? { apns: existing.apns } : {}
+			...existing?.apns ? { apns: existing.apns } : {},
+			...existing?.widgetApns ? { widgetApns: existing.widgetApns } : {}
 		};
 		this.devices.set(deviceId, next);
 		this.flush();
@@ -251,6 +487,7 @@ var DeviceStore = class DeviceStore {
 		if (!record || record.revokedAt !== void 0) return false;
 		record.revokedAt = now;
 		delete record.apns;
+		delete record.widgetApns;
 		this.flush();
 		return true;
 	}
@@ -296,6 +533,25 @@ var DeviceStore = class DeviceStore {
 		delete record.apns;
 		this.flush();
 	}
+	setWidgetPushToken(deviceId, token, environment, now) {
+		const record = this.authorized(deviceId);
+		if (!record || !isValidApnsToken(token)) return;
+		const previous = record.widgetApns;
+		if (previous?.token === token && previous.environment === environment && now - previous.updatedAt < 36e5) return;
+		record.widgetApns = {
+			token,
+			environment,
+			updatedAt: now
+		};
+		this.flush();
+	}
+	/** Compare-and-clear protects a rotated token from a delayed APNs rejection. */
+	clearWidgetPushToken(deviceId, token) {
+		const record = this.devices.get(deviceId);
+		if (record?.widgetApns?.token !== token) return;
+		delete record.widgetApns;
+		this.flush();
+	}
 	/** Serialized so concurrent touches can never interleave half-written JSON. */
 	flush() {
 		const next = this.flushTail.then(() => this.writeFile());
@@ -332,14 +588,54 @@ const IMAGE_MEDIA_TYPES = /* @__PURE__ */ new Set([
 function sanitizeDeviceField(value, maxChars) {
 	return (typeof value === "string" ? value : String(value ?? "")).replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, maxChars);
 }
+/**
+* Runtime shape guard for a frame after JSON.parse. The old `as Envelope`
+* cast alone let JSON `null` reach `env.v` and let a missing or mistyped
+* `type` reach `requiredScope()`'s string operations — one anonymous frame
+* could crash the host process. Reject anything that is not a plain object
+* with a numeric version and a non-empty string type, so field access below
+* is always safe. The payload is intentionally opaque here; each handler
+* validates its own payload shape.
+*/
+function isEnvelope(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const frame = value;
+	if (typeof frame.v !== "number") return false;
+	if (typeof frame.type !== "string" || frame.type.length === 0) return false;
+	if (frame.id !== void 0 && typeof frame.id !== "string") return false;
+	if (frame.ts !== void 0 && typeof frame.ts !== "number") return false;
+	if (frame.seq !== void 0 && typeof frame.seq !== "number") return false;
+	return true;
+}
 function requiredScope(type) {
+	if (typeof type !== "string") return void 0;
 	if (type === "c2s.ping" || type === "c2s.resume") return void 0;
-	if (type === "c2s.session.sendPrompt") return "prompt.send";
+	if (type === "c2s.session.sendPrompt" || type === "c2s.session.delivery") return "prompt.send";
+	if (type === "c2s.pending.list") return "interactions.respond";
 	if (type === "c2s.approval.respond" || type === "c2s.question.respond") return "interactions.respond";
-	if (type === "c2s.push.register") return "notifications.register";
+	if (type === "c2s.push.register" || type === "c2s.widget.push.register") return "notifications.register";
 	if (type === "c2s.workspace.create" || type === "c2s.session.create" || type === "c2s.session.rename" || type === "c2s.session.archive" || type === "c2s.session.cancel" || type === "c2s.session.selectModel") return "sessions.manage";
 	if (type.startsWith("c2s.")) return "sessions.read";
 }
+/** Broadcast and replay authorization. Unknown frame types fail closed. */
+const PUSH_SCOPE_BY_TYPE = {
+	"s2c.session.event": "sessions.read",
+	"s2c.sessions.delta": "sessions.read",
+	"s2c.session.tail": "sessions.read",
+	"s2c.history.page": "sessions.read",
+	"s2c.pending.approval": "interactions.respond",
+	"s2c.pending.question": "interactions.respond",
+	"s2c.pending.cleared": "interactions.respond"
+};
+function pushScopeFor(type, payload) {
+	const fixed = PUSH_SCOPE_BY_TYPE[type];
+	if (fixed !== void 0) return fixed;
+	if (type === "s2c.notify") {
+		const category = payload?.category;
+		if (category === "approval.required" || category === "question.asked") return "interactions.respond";
+		if (category === "turn.completed" || category === "session.error") return "sessions.read";
+	}
+}
 function sanitizeImageName(value) {
 	return value.replace(/[\u0000-\u001F\u007F]/g, "").trim().slice(0, 120);
 }
@@ -396,13 +692,18 @@ var BridgeConnection = class {
 	/** Sanitized device identity from hello; needed for push registration. */
 	deviceId;
 	scopes = /* @__PURE__ */ new Set();
+	widgetClient = false;
 	authChallenge;
 	constructor(ws, deps) {
 		this.ws = ws;
 		this.deps = deps;
 		this.authChallenge = createAuthChallenge(deps.audience);
 		ws.on("message", (data) => {
-			this.onMessage(String(data));
+			this.onMessage(String(data)).catch((error) => {
+				if (this.deps.debug === true) this.deps.log("frame handler failed: " + String(error));
+				if (this.closed) return;
+				this.terminate();
+			});
 		});
 		ws.on("close", () => {
 			this.onClose();
@@ -439,7 +740,19 @@ var BridgeConnection = class {
 	get connectedDeviceId() {
 		return this.authenticated ? this.deviceId : void 0;
 	}
+	get suppressesAlertPush() {
+		return !this.widgetClient;
+	}
+	/** S→C permission gate consulted by the bridge for every broadcast/replay
+	*  frame: a device only receives what its scopes grant (R1/P2). */
+	canReceive(scope) {
+		return this.scopes.has(scope);
+	}
 	push(type, payload, seq) {
+		if (type === "s2c.notify") payload = {
+			...payload,
+			hostAudience: this.deps.audience
+		};
 		if (type === "s2c.session.event") {
 			const sessionId = payload?.sessionId;
 			if (typeof sessionId === "string") {
@@ -528,7 +841,12 @@ var BridgeConnection = class {
 		}
 		let env;
 		try {
-			env = JSON.parse(raw);
+			const parsed = JSON.parse(raw);
+			if (!isEnvelope(parsed)) {
+				this.fail(void 0, "E_PROTOCOL", "malformed frame");
+				return;
+			}
+			env = parsed;
 		} catch {
 			this.fail(void 0, "E_PROTOCOL", "frame is not valid JSON");
 			return;
@@ -550,11 +868,19 @@ var BridgeConnection = class {
 			this.fail(env.id, "E_PROTOCOL", "authenticate first");
 			return;
 		}
+		if (this.widgetClient && ![
+			"c2s.ping",
+			"c2s.sessions.list",
+			"c2s.pending.list",
+			"c2s.widget.push.register"
+		].includes(env.type)) return this.fail(env.id, "E_FORBIDDEN", "widget connection is read-only");
 		const required = requiredScope(env.type);
 		if (required !== void 0 && !this.scopes.has(required)) {
 			this.fail(env.id, "E_FORBIDDEN", `scope ${required} required`);
 			return;
 		}
+		const invalid = validateRequest(env.type, env.payload);
+		if (invalid) return this.fail(env.id, "E_PROTOCOL", invalid);
 		switch (env.type) {
 			case "c2s.ping":
 				this.send("s2c.pong", { serverTime: Date.now() }, env.id);
@@ -727,6 +1053,11 @@ var BridgeConnection = class {
 				}, env.id);
 				return;
 			}
+			case "c2s.session.delivery": {
+				const p = env.payload;
+				this.send("s2c.ack", this.deps.bridge.promptDeliveries.lookup(this.deviceId, p.sessionId, p.clientSendId), env.id);
+				return;
+			}
 			case "c2s.session.sendPrompt": {
 				const p = env.payload;
 				const text = typeof p?.text === "string" ? p.text : "";
@@ -758,6 +1089,15 @@ var BridgeConnection = class {
 						...document.truncated === true ? { truncated: true } : {}
 					});
 				}
+				if (p.clientSendId) {
+					const receipt = await this.deps.bridge.promptDeliveries.dispatch(this.deviceId, p.sessionId, p.clientSendId, {
+						text,
+						images,
+						documents
+					}, () => this.deps.bridge.sendPrompt(p.sessionId, text, images, documents));
+					this.send("s2c.ack", receipt, env.id);
+					return;
+				}
 				const userSeq = await this.deps.bridge.sendPrompt(p.sessionId, text, images, documents);
 				if (!userSeq.ok) return this.fail(env.id, managementErrorCode(userSeq.kind), userSeq.message);
 				this.send("s2c.ack", { userSeq: userSeq.value }, env.id);
@@ -779,7 +1119,9 @@ var BridgeConnection = class {
 				this.send("s2c.ack", {}, env.id);
 				return;
 			}
+			case "c2s.widget.push.register":
 			case "c2s.push.register": {
+				const widget = env.type === "c2s.widget.push.register";
 				const p = env.payload;
 				const token = typeof p?.deviceToken === "string" ? p.deviceToken.trim() : "";
 				if (!isValidApnsToken(token)) return this.fail(env.id, "E_PROTOCOL", "hex deviceToken (32-512 chars) required");
@@ -790,7 +1132,12 @@ var BridgeConnection = class {
 					const enrollKey = p.enrollKey.trim().replace(/[^\x20-\x7e]/g, "").slice(0, 128);
 					if (enrollKey.length >= 8 && enrollKey.length <= 128) await this.deps.onPushEnrollKey?.(enrollKey);
 				}
-				this.deps.devices.setPushToken(this.deviceId, token, environment, categories, Date.now());
+				const record = this.deps.devices.authorized(this.deviceId);
+				if (this.closed || !record?.scopes?.includes("notifications.register")) return this.fail(env.id, "E_FORBIDDEN", "device authorization changed");
+				if (widget) {
+					if (!record.scopes.includes("sessions.read") || !record.scopes.includes("interactions.respond")) return this.fail(env.id, "E_FORBIDDEN", "widget overview permissions required");
+					this.deps.devices.setWidgetPushToken(this.deviceId, token, environment, Date.now());
+				} else this.deps.devices.setPushToken(this.deviceId, token, environment, categories, Date.now());
 				if (!this.deps.bridge.capabilities.push) {
 					if (this.deps.debug === true) this.deps.log("push register held: bridge not ready");
 					return this.fail(env.id, "E_UNSUPPORTED", "push is not configured on this bridge");
@@ -836,11 +1183,12 @@ var BridgeConnection = class {
 		this.settleAuthentication(true, "success");
 		this.authenticated = true;
 		this.deviceId = deviceId;
+		this.widgetClient = p.clientRole === "widget";
 		this.scopes = new Set(record.scopes ?? []);
 		if (this.helloTimer !== void 0) clearTimeout(this.helloTimer);
-		this.deps.devices.markAuthenticated(deviceId, deviceName, appVersion, Date.now());
+		if (!this.widgetClient) this.deps.devices.markAuthenticated(deviceId, deviceName, appVersion, Date.now());
 		this.deps.onDeviceAuthenticated?.(deviceId);
-		const cursor = resumeCursor;
+		const cursor = this.widgetClient ? void 0 : resumeCursor;
 		const canResume = cursor !== void 0 && this.deps.bridge.canResumeFrom(cursor);
 		this.send("s2c.welcome", {
 			protocolVersion: 2,
@@ -851,7 +1199,7 @@ var BridgeConnection = class {
 			cursor: this.deps.bridge.currentCursor(),
 			resumed: canResume
 		}, env.id);
-		this.deps.bridge.addSink(this);
+		if (!this.widgetClient) this.deps.bridge.addSink(this);
 		if (cursor !== void 0) {
 			if (canResume) this.deps.bridge.resumeFrom(cursor, this);
 			else this.resync();
@@ -1401,11 +1749,14 @@ var HostBridge = class {
 	abort = new AbortController();
 	started = false;
 	disposed = false;
-	constructor(apiProxy, historyBufferMax = MAX_RING_DEFAULT) {
+	promptDeliveries;
+	constructor(apiProxy, historyBufferMax = MAX_RING_DEFAULT, deliveryJournalPath) {
 		this.apiProxy = apiProxy;
 		this.historyBufferMax = historyBufferMax;
+		this.promptDeliveries = openDeliveryJournal(deliveryJournalPath);
 	}
 	pushOutlet;
+	widgetFingerprint = "";
 	/**
 	* Wire the offline-push fan-out. Present ⇒ welcome advertises the `push`
 	* capability and notify-worthy events are mirrored to APNs.
@@ -1420,11 +1771,13 @@ var HostBridge = class {
 			approvals: true,
 			questions: true,
 			pendingSnapshot: true,
+			promptDelivery: true,
 			notifyAllCategories: true,
 			models: typeof this.apiProxy.sessions.models === "function" && typeof this.apiProxy.sessions.selectModel === "function",
 			sessionManagement: typeof this.apiProxy.sessions.rename === "function" && typeof this.apiProxy.workspace?.archiveSession === "function",
 			projectSelection: typeof this.apiProxy.workspace?.list === "function" && typeof this.apiProxy.workspace?.create === "function",
-			push: this.pushOutlet?.isAvailable() === true
+			push: this.pushOutlet?.isAvailable() === true,
+			widgetPush: true
 		};
 	}
 	diagnostic(message) {
@@ -1521,17 +1874,45 @@ var HostBridge = class {
 	* Replay buffered pushes after the given cursor; false when the gap is
 	* unrecoverable. Frames go to `target` only — replaying into every sink
 	* duplicated the whole window onto devices that never asked for it.
+	* Each frame is filtered by the S→C permission policy per sink, so a
+	* reader without interactions.respond never gets the missed approval
+	* frames back (R1/P2).
 	*/
 	resumeFrom(cursor, target) {
 		const oldest = this.ring.length > 0 ? this.ring[0].seq : this.cursor + 1;
 		if (cursor + 1 < oldest) return false;
 		const receivers = target !== void 0 ? [target] : [...this.sinks];
-		for (const entry of this.ring) if (entry.seq > cursor) for (const sink of receivers) sink.replay([entry]);
+		for (const entry of this.ring) if (entry.seq > cursor) for (const sink of receivers) {
+			const need = pushScopeFor(entry.type, entry.payload);
+			if (need === void 0 || !sink.canReceive(need)) continue;
+			sink.replay([entry]);
+		}
 		for (const sink of receivers) sink.replayDone();
 		return true;
 	}
 	record(type, payload, except) {
 		if (this.disposed) return;
+		if (type === "s2c.sessions.delta" || type.startsWith("s2c.pending.")) {
+			const fingerprint = JSON.stringify([
+				this.listSessions().map(({ id, title, status, lastActivityTs, todos, pendingApproval, pendingQuestion }) => ({
+					id,
+					title,
+					status,
+					lastActivityTs,
+					todos,
+					pendingApproval,
+					pendingQuestion
+				})),
+				this.approvals.size,
+				this.questions.size
+			]);
+			if (fingerprint !== this.widgetFingerprint) {
+				this.widgetFingerprint = fingerprint;
+				try {
+					this.pushOutlet?.widgetChanged?.();
+				} catch {}
+			}
+		}
 		this.cursor += 1;
 		const entry = {
 			seq: this.cursor,
@@ -1540,7 +1921,9 @@ var HostBridge = class {
 		};
 		this.ring.push(entry);
 		if (this.ring.length > this.historyBufferMax) this.ring.splice(0, this.ring.length - this.historyBufferMax);
+		const need = pushScopeFor(type, payload);
 		for (const sink of this.sinks) {
+			if (need === void 0 || !sink.canReceive(need)) continue;
 			if (except && except(sink)) continue;
 			sink.push(type, payload, entry.seq);
 		}
@@ -1782,6 +2165,14 @@ var HostBridge = class {
 		} else if (key === "sessionListMetadata") {
 			const meta = value;
 			if (meta?.lastPromptAt) row.lastActivityTs = Math.max(row.lastActivityTs, meta.lastPromptAt);
+		} else if (key === "sessionStats" || key === "tokenUsage") {
+			const patch = sanitizeUsageStatsPatch(key, value);
+			if (!patch) return;
+			row.stats = {
+				...emptyUsageStats,
+				...row.stats ?? {},
+				...patch
+			};
 		} else return;
 		this.pushSummary(row);
 	}
@@ -2415,6 +2806,65 @@ function sanitizeTodoItems(items) {
 		status: i.status
 	}));
 }
+/** Zero-value stats snapshot used as the merge base for partial patches. */
+const emptyUsageStats = {
+	turns: 0,
+	steps: 0,
+	llmMs: 0,
+	toolMs: 0,
+	ttftMs: 0,
+	ttftSteps: 0,
+	decodeMs: 0,
+	decodeTokens: 0,
+	inputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0
+};
+/** Coerce one host counter to a non-negative integer; junk becomes 0. */
+function usageCounter(value) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n) || n < 0) return 0;
+	return Math.floor(n);
+}
+const SESSION_STATS_COUNTERS = [
+	"turns",
+	"steps",
+	"llmMs",
+	"toolMs",
+	"ttftMs",
+	"ttftSteps",
+	"decodeMs",
+	"decodeTokens"
+];
+const TOKEN_USAGE_COUNTERS = [
+	"outputTokens",
+	"cacheReadTokens",
+	"cacheWriteTokens"
+];
+/** Sanitize one `sessionStats` / `tokenUsage` projection value into the wire
+* stats fields; undefined when the payload carries nothing readable. Host
+* field names differ between the two projections (tokenUsage reports
+* `uncachedInputTokens`, the wire mirrors it as `inputTokens`). */
+function sanitizeUsageStatsPatch(key, value) {
+	if (!value || typeof value !== "object") return void 0;
+	const raw = value;
+	const patch = {};
+	if (key === "sessionStats") {
+		for (const field of SESSION_STATS_COUNTERS) if (field in raw) patch[field] = usageCounter(raw[field]);
+	} else {
+		if ("uncachedInputTokens" in raw) patch.inputTokens = usageCounter(raw.uncachedInputTokens);
+		for (const field of TOKEN_USAGE_COUNTERS) if (field in raw) patch[field] = usageCounter(raw[field]);
+	}
+	return Object.keys(patch).length > 0 ? patch : void 0;
+}
+/** Combine one session's `sessionStats` + `tokenUsage` projection values into
+* a complete wire stats object; undefined when neither carries anything. */
+function usageStatsOf(sessionStats, tokenUsage) {
+	const patches = [sanitizeUsageStatsPatch("sessionStats", sessionStats), sanitizeUsageStatsPatch("tokenUsage", tokenUsage)].filter((patch) => patch !== void 0);
+	if (patches.length === 0) return void 0;
+	return Object.assign({}, emptyUsageStats, ...patches);
+}
 function toSummary(row, approvals, questions, workspace) {
 	const values = row.projections?.values ?? {};
 	const todos = Array.isArray(values.todos) ? values.todos : null;
@@ -2425,6 +2875,7 @@ function toSummary(row, approvals, questions, workspace) {
 	const cwd = typeof row.cwd === "string" ? row.cwd : "";
 	const label = workspace?.title ?? (cwd ? cwd.split("/").filter(Boolean).pop() : void 0);
 	const todoItems = sanitizeTodoItems(todos);
+	const stats = usageStatsOf(values.sessionStats, values.tokenUsage);
 	return {
 		id: row.sessionId,
 		title: typeof values.title === "string" ? values.title : "",
@@ -2437,6 +2888,7 @@ function toSummary(row, approvals, questions, workspace) {
 		todoItems: todoItems.length > 0 ? todoItems : null,
 		pendingApproval,
 		pendingQuestion,
+		...stats ? { stats } : {},
 		workspaceLabel: label ?? null,
 		workspaceId: workspace?.workspaceId ?? null,
 		workspacePath: workspace?.path ?? (cwd || null)
@@ -3642,6 +4094,10 @@ function p8ToDer(pem) {
 }
 /** Pure payload builder so tests can assert the wire format without sockets. */
 function apnsPayload(notification) {
+	if ("kind" in notification && notification.kind === "widget") return { aps: { "content-changed": true } };
+	return alertPayload(notification);
+}
+function alertPayload(notification) {
 	const timeSensitive = notification.category === "approval.required" || notification.category === "question.asked";
 	return {
 		aps: {
@@ -3651,17 +4107,32 @@ function apnsPayload(notification) {
 			},
 			sound: "default",
 			category: notification.category,
-			"thread-id": notification.sessionId.slice(0, 64),
+			"thread-id": notification.hostAudience ? createHash("sha256").update(`${notification.hostAudience}:${notification.sessionId}`).digest("hex") : notification.sessionId.slice(0, 64),
 			...timeSensitive ? { "interruption-level": "time-sensitive" } : {}
 		},
+		...notification.hostAudience ? { hostAudience: notification.hostAudience } : {},
 		sessionId: notification.sessionId,
 		notificationId: notification.notificationId,
 		kind: notification.category
 	};
 }
+function pushHeaders(bundleId, notification) {
+	if ("kind" in notification && notification.kind === "widget") return {
+		"apns-topic": bundleId + ".push-type.widgets",
+		"apns-push-type": "widgets",
+		"apns-priority": "5",
+		"apns-collapse-id": "widget-overview"
+	};
+	return {
+		"apns-topic": bundleId,
+		"apns-push-type": "alert",
+		"apns-priority": "10",
+		"apns-collapse-id": collapseIdFor(notification)
+	};
+}
 /** collapse-id accepts ≤64 bytes of ASCII; keep it stable per session+event. */
 function collapseIdFor(notification) {
-	const raw = `${notification.category}:${notification.sessionId}`;
+	const raw = `${notification.hostAudience ? notification.hostAudience + ":" : ""}${notification.category}:${notification.sessionId}`;
 	const readable = raw.replace(/[^a-zA-Z0-9.:-]/g, "");
 	const digest = createHash("sha256").update(raw, "utf8").digest("hex").slice(0, 12);
 	return `${readable.slice(0, 51)}:${digest}`;
@@ -3738,11 +4209,8 @@ var ApnsClient = class {
 					[":method"]: "POST",
 					[":path"]: "/3/device/" + deviceToken,
 					authorization: "bearer " + token,
-					"apns-topic": this.opts.bundleId,
-					"apns-push-type": "alert",
-					"apns-priority": "10",
+					...pushHeaders(this.opts.bundleId, notification),
 					"apns-expiration": String(Math.floor(Date.now() / 1e3) + 3600),
-					"apns-collapse-id": collapseIdFor(notification),
 					"content-type": "application/json",
 					"content-length": String(Buffer.byteLength(body))
 				});
@@ -4608,6 +5076,7 @@ const Config = z.object({
 			"apns",
 			"relay"
 		]).default("none"),
+		contentMode: z.union(["preview", "generic"]).default("preview"),
 		teamId: z.string().default(""),
 		keyId: z.string().default(""),
 		keyPath: z.string().default(join(bridgeDataDir(), "apns", "AuthKey.p8")),
@@ -4616,6 +5085,7 @@ const Config = z.object({
 		relayToken: z.string().default("")
 	}).default({
 		provider: "none",
+		contentMode: "preview",
 		teamId: "",
 		keyId: "",
 		keyPath: join(bridgeDataDir(), "apns", "AuthKey.p8"),
@@ -4793,6 +5263,11 @@ var AuthRateLimiter = class {
 function shouldPrunePushToken(outcome, reason) {
 	return outcome === "invalid-token" && (reason === "Unregistered" || reason === "ExpiredToken");
 }
+/** APNs requires both registration and the same content permission as WS. */
+function mayReceivePush(device, notification) {
+	const scope = pushScopeFor("s2c.notify", notification);
+	return scope !== void 0 && device.scopes?.includes("notifications.register") === true && device.scopes.includes(scope);
+}
 /**
 * Zero-touch relay self-heal: HTTP 401 means the relay no longer honors the
 * cached credential. Only auto-enrolled cells with a still-current token may
@@ -4802,6 +5277,59 @@ function shouldPrunePushToken(outcome, reason) {
 function shouldReEnrollRelayToken(transport, outcome, reason, opts) {
 	return transport === "relay" && outcome === "failed" && reason === "HTTP 401" && opts.hasEnrollKey && opts.usedCellToken && opts.tokenStillCurrent;
 }
+/** Apply before either transport receives the payload, including the Relay. */
+function pushContent(notification, mode) {
+	if (mode !== "generic") return notification;
+	const bodies = {
+		"turn.completed": "A task has completed.",
+		"approval.required": "An approval needs your attention.",
+		"question.asked": "A question needs your answer.",
+		"session.error": "A task needs your attention."
+	};
+	return {
+		...notification,
+		title: "DeepPilot",
+		body: bodies[notification.category] ?? "Open DeepPilot for an update."
+	};
+}
+//#endregion
+//#region src/widget-push.ts
+/** Coalesce bursts and bound continuous updates, without starving the trailing
+* state. One scheduler per host, not per token or per streaming text frame. */
+var WidgetPushScheduler = class {
+	send;
+	intervalMs;
+	timer;
+	lastSent = 0;
+	disposed = false;
+	sending = false;
+	dirty = false;
+	constructor(send, intervalMs = 3e4) {
+		this.send = send;
+		this.intervalMs = intervalMs;
+	}
+	changed() {
+		if (this.disposed) return;
+		this.dirty = true;
+		if (this.timer || this.sending) return;
+		this.timer = setTimeout(() => {
+			this.timer = void 0;
+			this.dirty = false;
+			this.sending = true;
+			this.lastSent = Date.now();
+			this.send().catch(() => {}).finally(() => {
+				this.sending = false;
+				if (this.dirty) this.changed();
+			});
+		}, Math.max(Math.min(1e3, this.intervalMs), this.intervalMs - (Date.now() - this.lastSent)));
+		this.timer.unref();
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = void 0;
+	}
+};
 //#endregion
 //#region src/phone-server.ts
 /**
@@ -5250,20 +5778,59 @@ function apply(ctx, options) {
 	* token. Rules:
 	*  - devices with a live WebSocket are skipped (they already got the WS
 	*    frame and will raise the local notification themselves);
+	*  - only devices granted `notifications.register` are candidates — a
+	*    device whose scope was revoked must not receive offline pushes
+	*    (R1/P2 S→C permission policy);
 	*  - each device is delivered on ITS registered environment (the build
 	*    kind it self-reported), so sandbox and production devices coexist;
 	*  - the device's per-category switches suppress muted categories;
 	*  - only APNs' terminal Unregistered/ExpiredToken verdicts prune storage;
 	*    BadDeviceToken may be an environment mismatch and stays diagnosable.
 	*/
+	const widgetPush = new WidgetPushScheduler(async () => {
+		if (!enabledNow()) return;
+		const resolved = resolvePushConfig(currentConfig());
+		if (!resolved.ok) return;
+		const devices = auth.devices;
+		const send = await senderFor(resolved.value);
+		if (!devices || !send) return;
+		const sent = /* @__PURE__ */ new Set();
+		for (const device of devices.list()) {
+			const registration = device.widgetApns;
+			if (!registration || device.revokedAt !== void 0 || ![
+				"notifications.register",
+				"sessions.read",
+				"interactions.respond"
+			].every((scope) => device.scopes?.includes(scope)) || Date.now() - registration.updatedAt > 6048e5) continue;
+			const key = registration.environment + ":" + registration.token;
+			if (sent.has(key)) continue;
+			sent.add(key);
+			const { outcome, reason } = await send({
+				deviceToken: registration.token,
+				environment: registration.environment,
+				notification: { kind: "widget" }
+			});
+			if (shouldPrunePushToken(outcome, reason)) devices.clearWidgetPushToken(device.deviceId, registration.token);
+			if (resolved.value.kind === "relay" && reason === "HTTP 401" && enrollmentCell.token === resolved.value.token && enrollmentCell.enrollKey) {
+				enrollmentCell.token = void 0;
+				persistEnrollment();
+				await ensureRelayEnrolled(resolved.value.url);
+			}
+		}
+	});
 	const makePushOutlet = () => ({
+		widgetChanged: () => widgetPush.changed(),
 		isAvailable: () => {
 			const resolved = resolvePushConfig(currentConfig());
 			if (!resolved.ok) return false;
 			if (resolved.value.kind === "relay" && !resolved.value.token) return false;
 			return true;
 		},
-		fanOut: (notification) => {
+		fanOut: (sourceNotification) => {
+			const notification = pushContent({
+				...sourceNotification,
+				hostAudience: auth.audience ?? void 0
+			}, currentConfig().push?.contentMode);
 			(async () => {
 				let resolved = resolvePushConfig(currentConfig());
 				if (!resolved.ok && resolved.reason === "relay token not enrolled yet") {
@@ -5280,12 +5847,16 @@ function apply(ctx, options) {
 				const connectedIds = /* @__PURE__ */ new Set();
 				for (const connection of connections) {
 					const id = connection.connectedDeviceId;
-					if (id) connectedIds.add(id);
+					if (id && connection.suppressesAlertPush) connectedIds.add(id);
 				}
 				const candidates = devices.list().filter((device) => {
 					const registration = device.apns;
 					if (!registration) return false;
 					if (connectedIds.has(device.deviceId)) return false;
+					if (!mayReceivePush(device, notification)) {
+						if (currentConfig().debug === true) log(`push skip "${device.deviceName}": notification permission not granted`);
+						return false;
+					}
 					if (registration.categories?.[notification.category] === false) {
 						if (currentConfig().debug === true) log(`push skip "${device.deviceName}": category ${notification.category} muted`);
 						return false;
@@ -5840,7 +6411,7 @@ function apply(ctx, options) {
 			log("dsh 0.1.2 session bridge unavailable: " + String(error));
 			return;
 		}
-		const bridge = new HostBridge(proxy, cfg.historyBufferMax);
+		const bridge = new HostBridge(proxy, cfg.historyBufferMax, join(dataDir, "prompt-deliveries-v1.json"));
 		bridge.setPushOutlet(makePushOutlet());
 		state.bridge = bridge;
 		bridge.start();
@@ -5883,6 +6454,7 @@ function apply(ctx, options) {
 		const sender = cachedSender;
 		cachedSender = void 0;
 		updateChecker.dispose();
+		widgetPush.dispose();
 		const wssClosed = new Promise((resolve) => wss.close(() => resolve()));
 		await Promise.allSettled([
 			enrollmentWriteTail,
@@ -5892,6 +6464,6 @@ function apply(ctx, options) {
 	}, "deeppilot: process resources");
 }
 //#endregion
-export { Config, HostBridge, apply, inject, name, shouldPrunePushToken, shouldReEnrollRelayToken };
+export { Config, HostBridge, apply, inject, mayReceivePush, name, shouldPrunePushToken, shouldReEnrollRelayToken };
 
 //# sourceMappingURL=index.js.map