zigmini 0.8.0-beta.6 → 0.9.0-beta.1

package/src/main.ts

@@ -4,6 +4,7 @@ import { join, normalize } from "node:path";
 import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
 import { createSttProvider } from "./adapters/voice/stt.ts";
 import { createTtsProvider, speakableText, splitForTts } from "./adapters/voice/tts.ts";
+import { handleHeld, handleSecurityAllowedValues, handleSecurityCheckSetting, MessageGuard, SECURITY_CHECK_PATH, SECURITY_HELD_PATH, SECURITY_ALLOWED_PATH, SecurityCheckError, defaultChecker } from "./security-check.ts";
 import { handleVoiceInstall, handleVoiceSetting, routeVoiceApi, VOICE_INSTALL_PATH, VOICE_SETTING_PATH, voiceGate, voiceUpdated } from "./voice-api.ts";
 import { readVoiceSetting, VoiceSetting } from "./voice-setting.ts";
 import { applyVoiceAgents } from "./voice/agents.ts";
@@ -46,6 +47,7 @@ import { RECOVERY_RECEIPT_PREFIX } from "./omo/recovery-receipt.ts";
 import { fileScheduleSource, notionRoutineSource, ReminderLoop } from "./schedule/reminders.ts";
 import { type ClientMessage, type Envelope, PROTOCOL_VERSION, ROTATION_HELD_MESSAGE, type Source } from "./protocol.ts";
 import { QuestionNotifications } from "./question-notifications.ts";
+import { NotificationSettingsApi, ReplyNotifications } from "./reply-notifications.ts";
 import { DecisionStoreError, Store } from "./store.ts";
 import { TranscriptLog } from "./transcript.ts";
 import { WorkRouter } from "./work.ts";
@@ -145,11 +147,26 @@ const updateApi: UpdateApiDeps = {
 };
 
 let publish: (envelope: Envelope) => void = () => {};
+const replyNotifications = new ReplyNotifications<ServerWebSocket<Conn>>(store, (ws, notification) => {
+	if (ws.data.deviceId && store.getDevice(ws.data.deviceId)?.status === "approved") ws.send(envelope("reply.notification", notification, notification.conv));
+});
+let securityDecisionRefresh = () => {};
+const securityEvent = (type: string, data: unknown) => publish({
+	v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(), conv: "*", type, data,
+});
+const messageGuard = new MessageGuard(defaultChecker(), runtimePaths().securityCheckFile, (held) => publish({
+	v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(), conv: held.conv, type: "security-check.held", data: held,
+}), { store, state: (state) => {
+	securityEvent("security-check.state", state);
+	if (state.status === "sent" || state.status === "cancelled") securityEvent("security-check.resolved", { id: state.id, outcome: state.status === "sent" ? "sent" : "dropped" });
+}, allowedUpdated: (revision) => securityEvent("security-check.allowed-values.updated", { revision }),
+	decisionUpdated: () => securityDecisionRefresh() });
 const hub = new Hub(
 	store,
 	dialogs,
 	stt,
 	{
+		replies: replyNotifications,
 		cwd: config.omoCwd,
 		sessionDir: config.omoSessionDir,
 		permissionPreset: config.omoPermissionPreset,
@@ -164,6 +181,7 @@ const hub = new Hub(
 			build: process.env.ZGW_BUILD_SHA,
 		}),
 		usageReport: createUsageReport({ dir: agentDir(), inContainer: existsSync("/.dockerenv") }),
+		guard: messageGuard,
 	},
 	(e) => publish(e),
 );
@@ -205,7 +223,7 @@ const omo = new GenerationRouter(startup.endpoints, startup.active, {
 	onEvent: (e) => {
 		if (work.onEvent(e)) return;
 		summarizer.onEvent(e, hub.ownsSession(e.sessionId));
-		hub.onEvent(e);
+		void Promise.resolve(hub.onEvent(e)).catch((error) => console.error("native event:", error));
 	},
 	onStatus: (s, d) => {
 		const generation = ++connectionGeneration;
@@ -249,10 +267,12 @@ function releaseRecovery(): void {
 	})().finally(() => { releaseRunning = null; });
 }
 const work = new WorkRouter(store, omo, {
+	replies: replyNotifications,
 	sessionDir: config.omoSessionDir,
 	permissionPreset: config.omoPermissionPreset,
 	onPublished(event) {
 		hub.publishStored(event);
+		replyNotifications.deliver();
 		// A published work report raises that work's `reported` in the work status.
 		workStatus.schedule();
 	},
@@ -285,6 +305,12 @@ const work = new WorkRouter(store, omo, {
 		else hub.handleScopedUiRequest(owner, event);
 	},
 });
+const notificationSettingsApi = new NotificationSettingsApi(replyNotifications, async () => {
+	await hub.notificationBaseline();
+	await work.notificationBaseline();
+}, (data) => publish({
+	v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(), conv: "*", type: "notifications.updated", data,
+}));
 hub.attachOmo(omo);
 const omoCheck = new OmoCheckScheduler(store, {
 	cwd: process.env.ZGW_OMO_CHECK_CWD ?? "",
@@ -302,7 +328,8 @@ const decisions = new DecisionService(store, {
 }, (data) => publish({
 	v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(),
 	conv: data.decision.ownerConv, type: "decision.updated", data,
-}), { onHistory: (event) => hub.publishStored(event) });
+}), { onHistory: (event) => hub.publishStored(event), guard: messageGuard });
+securityDecisionRefresh = () => decisions.refresh();
 hub.attachDecisions(decisions);
 const summarizer = new SpeechSummarizer(omo, {
 	sessionDir: config.omoSessionDir,
@@ -373,6 +400,7 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 		ws.data.notifyOnly &&
 		msg.type !== "hello" &&
 		msg.type !== "reminder.ack" &&
+		msg.type !== "reply.notification.ack" &&
 		msg.type !== "question.notification.ack"
 	) return;
 	if (
@@ -403,6 +431,7 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 			if (state.omo === "ready") questionNotifications.sync(snapshot.approvals);
 			if (ws.data.notifyOnly) {
 				if (ws.data.deviceId) questionNotifications.connectDevice(ws, ws.data.deviceId);
+				if (ws.data.deviceId) replyNotifications.connectDevice(ws, ws.data.deviceId);
 				for (const r of reminders.pending(Date.now())) ws.send(envelope("reminder", r));
 				return;
 			}
@@ -423,6 +452,10 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 		case "reminder.ack":
 			if (typeof msg.data?.id === "string") reminders.ack(msg.data.id, Date.now());
 			return;
+		case "reply.notification.ack":
+			if (ws.data.notifyOnly && ws.data.deviceId && typeof msg.data?.id === "string" &&
+				store.getDevice(ws.data.deviceId)?.status === "approved") replyNotifications.ack(ws, msg.data.id);
+			return;
 		case "question.notification.ack": {
 			const id = ws.data.deviceId;
 			if (
@@ -452,6 +485,8 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 					"owner",
 					Array.isArray(msg.data.images) ? msg.data.images.filter((n): n is string => typeof n === "string") : [],
 					msg.data.references,
+					false,
+					msg.data.submissionId,
 				),
 			);
 			return;
@@ -461,6 +496,9 @@ async function handleClient(ws: ServerWebSocket<Conn>, raw: string): Promise<voi
 					ws.send(envelope("error", { message: "approval_not_pending", actionId: msg.data.actionId }, msg.conv));
 				}
 			} catch (error) {
+				if (error instanceof SecurityCheckError) {
+					return;
+				}
 				if (!(error instanceof DecisionStoreError)) throw error;
 				ws.send(envelope("error", {
 					message: error.code, actionId: msg.data.actionId,
@@ -610,6 +648,7 @@ async function handle(req: Request, srv: Server<Conn>, trusted: boolean): Promis
 		return srv.upgrade(req, { data: { trusted, deviceId, notifyOnly, webClient: false } }) ? undefined : new Response("upgrade failed", { status: 400 });
 	}
 	// Voice off answers 503 before native admission and before any body is read.
+	if (url.pathname === "/api/settings/notifications") return notificationSettingsApi.handle(req);
 	const voiceDisabled = voiceGate(req, url, voiceSetting);
 	if (voiceDisabled) return voiceDisabled;
 	if (url.pathname === VOICE_INSTALL_PATH) {
@@ -623,6 +662,20 @@ async function handle(req: Request, srv: Server<Conn>, trusted: boolean): Promis
 		});
 		if (response) return response;
 	}
+	if (url.pathname === SECURITY_HELD_PATH || url.pathname.startsWith(`${SECURITY_HELD_PATH}/`)) {
+		const response = await handleHeld(req, url, messageGuard, () => {}, { client: trusted ? "web" : "android", deviceId });
+		if (response) return response;
+	}
+	if (url.pathname === SECURITY_ALLOWED_PATH || url.pathname.startsWith(`${SECURITY_ALLOWED_PATH}/`)) {
+		const response = await handleSecurityAllowedValues(req, url, store, (revision) => securityEvent("security-check.allowed-values.updated", { revision }));
+		if (response) return response;
+	}
+	if (url.pathname === SECURITY_CHECK_PATH) {
+		const response = await handleSecurityCheckSetting(req, trusted, messageGuard, (enabled) => publish({
+			v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(), conv: "*", type: "security-check.updated", data: { enabled },
+		}));
+		if (response) return response;
+	}
 	if (url.pathname === PROFILE_ICON_PATH) {
 		const response = await handleProfileIcon(req, url, trusted, { icon: profileIcon, profile: () => readProfile(store), publish: (e) => publish(e) });
 		if (response) return response;
@@ -827,6 +880,7 @@ const websocket: WebSocketHandler<Conn> = {
 	close(ws) {
 		if (ws.data.deviceId) deviceSockets.get(ws.data.deviceId)?.delete(ws);
 		questionNotifications.disconnectDevice(ws);
+		replyNotifications.disconnectDevice(ws);
 		questionNotifications.disconnectWeb(ws);
 	},
 };
@@ -837,8 +891,9 @@ const lanServer = config.lanPort
 	: null;
 
 publish = (e) => {
-	if (!omoCheckNotifications.allow(e)) return;
-	questionNotifications.onEnvelope(e);
+	const sensitiveHeld = e.type === "security-check.held";
+	if (!sensitiveHeld && !omoCheckNotifications.allow(e)) return;
+	if (!sensitiveHeld) questionNotifications.onEnvelope(e);
 	const text = JSON.stringify(e);
 	const topic = topicOf(e.type);
 	trustedServer.publish(topic, text);
@@ -885,6 +940,7 @@ function shutdown(): void {
 	updateChecker.stop();
 	clearInterval(updateTick);
 	decisions.stop();
+	messageGuard.stop();
 	watcher.stop();
 	work.stop();
 	omo.stop();

package/src/notification-history.ts

@@ -0,0 +1,56 @@
+import { open, stat } from "node:fs/promises";
+import { nativeReplyEntry, type NativeReplyEntry } from "./reply-notifications.ts";
+
+/**
+ * Read only the owned native JSONL, never the disposable resident blobs or an opened native session.
+ * The byte snapshot is finite; memory is bounded by a chunk plus the largest JSONL record, not the history.
+ */
+export async function notificationHistory(
+	path: string,
+	visit: (entry: NativeReplyEntry) => void,
+	baseline = false,
+): Promise<void> {
+	let file;
+	try { file = await open(path, "r"); }
+	catch (error) {
+		// Native buffers setup-only sessions until the first user/assistant message.
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+	try {
+		const snapshot = await file.stat();
+		const chunk = Buffer.alloc(64 * 1024);
+		const decoder = new TextDecoder("utf-8", { fatal: true });
+		let offset = 0;
+		let tail = "";
+		let header = false;
+		while (offset < snapshot.size) {
+			const { bytesRead } = await file.read(chunk, 0, Math.min(chunk.length, snapshot.size - offset), offset);
+			if (bytesRead === 0) throw new Error("reply_history_truncated");
+			offset += bytesRead;
+			tail += decoder.decode(chunk.subarray(0, bytesRead), { stream: true });
+			let newline: number;
+			while ((newline = tail.indexOf("\n")) !== -1) {
+				const line = tail.slice(0, newline);
+				tail = tail.slice(newline + 1);
+				const value: unknown = JSON.parse(line);
+				const entry = nativeReplyEntry(value);
+				if (!entry) throw new Error("reply_history_invalid_entry");
+				if (!header) {
+					if (entry.type !== "session") throw new Error("reply_history_invalid_header");
+					header = true;
+				} else {
+					if (entry.type === "session") throw new Error("reply_history_duplicate_header");
+					visit(baseline ? { id: entry.id, type: entry.type } : entry);
+				}
+			}
+		}
+		tail += decoder.decode();
+		if (!header || tail.length !== 0) throw new Error("reply_history_incomplete");
+		const current = await stat(path);
+		if (current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.size < snapshot.size ||
+			(current.size === snapshot.size && current.mtimeMs !== snapshot.mtimeMs)) throw new Error("reply_history_replaced");
+	} finally {
+		await file.close();
+	}
+}

package/src/omo/client.ts

@@ -10,6 +10,34 @@ export interface OmoEvent {
 	[key: string]: unknown;
 }
 
+/** Public S3 terminal categories. Native diagnostics never cross the UI boundary. */
+export const COMPACTION_FAILURE_KINDS = [
+	"invalid_model", "auth_missing", "auth_expired", "quota", "org_denied", "model_unavailable",
+	"refused", "timeout", "incomplete", "empty", "context_budget", "stale", "provider",
+] as const;
+export type CompactionFailureKind = typeof COMPACTION_FAILURE_KINDS[number];
+export type CompactionOutcome =
+	| { readonly status: "failed"; readonly failureKind: CompactionFailureKind }
+	| { readonly status: "cancelled" | "completed" };
+
+export function blockingCompaction(event: OmoEvent): boolean {
+	return event.blocking !== false && event.reason !== "speculative" && event.reason !== "idle";
+}
+
+/** Old engines have no structured failure; do not classify their raw error strings. */
+export function compactionOutcome(event: OmoEvent): CompactionOutcome {
+	const failure = event.failure;
+	const structured = typeof failure === "object" && failure !== null;
+	if (event.aborted === true && !structured && event.rejectionCause !== "cancelled-by-extension") return { status: "cancelled" };
+	const result = typeof event.result === "object" && event.result !== null && !Array.isArray(event.result);
+	const failed = structured || typeof event.errorMessage === "string" || event.accepted === false ||
+		(event.accepted !== true && !result);
+	if (!failed) return { status: "completed" };
+	const kind = structured && "kind" in failure ? failure.kind : undefined;
+	for (const known of COMPACTION_FAILURE_KINDS) if (kind === known) return { status: "failed", failureKind: known };
+	return { status: "failed", failureKind: "provider" };
+}
+
 export interface OmoResponse {
 	type: "response";
 	id: string;

package/src/protocol.ts

@@ -19,6 +19,22 @@ export interface MessageReference {
 	readonly images?: readonly string[];
 }
 
+/** Measured across one native response turn, including its model calls around tools. */
+export interface TurnStats {
+	readonly tokensPerSecond?: number;
+	/** Sum of assistant/model processing intervals, not tool or total wall time. */
+	readonly modelDurationMs?: number;
+	/** Missing cache usage is unknown, not zero. */
+	readonly cacheHitPercent?: number;
+}
+
+export interface MessageStatsData {
+	readonly itemId: string;
+	readonly messageSeq: number;
+	readonly turnId: string;
+	readonly stats: TurnStats;
+}
+
 export interface Envelope<T extends string = string, D = unknown> {
 	v: typeof PROTOCOL_VERSION;
 	id: string;
@@ -69,6 +85,7 @@ export type DecisionAnswerRequest = { readonly expectedRevision: number; readonl
 
 /** HTTP/event DTOs are separate from storage records; payload retains the existing action-card structure. */
 export interface DecisionInfo {
+	readonly security?: import("./security-allow.ts").HeldState;
 	readonly id: string;
 	readonly revision: number;
 	readonly ownerConv: string;
@@ -118,14 +135,27 @@ export interface DecisionUpdatedData {
 	readonly counters: DecisionCountersInfo;
 }
 
+export type NotificationMode = "inbox-only" | "all-replies";
+export interface NotificationSettings {
+	readonly mode: NotificationMode;
+}
+export interface ReplyNotification {
+	readonly id: string;
+	readonly conv: string;
+	readonly title: string;
+	readonly text: string;
+	readonly workId?: string;
+}
+
 export type ClientMessage =
 	| { type: "hello"; data: { client: string; version: string } }
 	| { type: "client.presence"; data: { visible: boolean } }
 	| { type: "history.get"; conv: string; before?: number; after?: number; limit?: number }
 	| { type: "conversation.create"; data: { title: string } }
-	| { type: "input.text"; conv: string; data: { text: string; images?: string[]; references?: number[] } }
+	| { type: "input.text"; conv: string; data: { text: string; images?: string[]; references?: number[]; submissionId?: string } }
 	| { type: "input.action"; conv: string; data: ActionAnswerData }
 	| { type: "input.interrupt"; conv: string; data: Record<string, never> }
 	| { type: "conversation.rotate"; conv: string }
 	| { type: "reminder.ack"; data: { id: string } }
-	| { type: "question.notification.ack"; data: { id: string } };
+	| { type: "question.notification.ack"; data: { id: string } }
+	| { type: "reply.notification.ack"; data: { id: string } };

package/src/reply-notifications.ts

@@ -0,0 +1,144 @@
+import type { NotificationSettings, ReplyNotification } from "./protocol.ts";
+import type { Store } from "./store.ts";
+
+export interface NativeReplySource {
+	readonly sessionPath: string;
+	readonly conv: string;
+	readonly workId?: string;
+	readonly title: string;
+}
+
+export interface NativeReplyEntry {
+	readonly id?: string;
+	readonly type?: string;
+	readonly message?: {
+		readonly role?: string;
+		readonly content?: unknown;
+		readonly stopReason?: string;
+		readonly errorMessage?: string;
+	};
+}
+
+/** entry_appended carries a persisted entry, unlike message_end's identity-free message object. */
+export function nativeReplyEntry(value: unknown): NativeReplyEntry | null {
+	if (typeof value !== "object" || value === null || !("id" in value) || typeof value.id !== "string" || !value.id ||
+		!("type" in value) || typeof value.type !== "string") return null;
+	const message = "message" in value ? value.message : undefined;
+	if (typeof message !== "object" || message === null) return { id: value.id, type: value.type };
+	return {
+		id: value.id, type: value.type,
+		message: {
+			role: "role" in message && typeof message.role === "string" ? message.role : undefined,
+			stopReason: "stopReason" in message && typeof message.stopReason === "string" ? message.stopReason : undefined,
+			errorMessage: "errorMessage" in message && typeof message.errorMessage === "string" ? message.errorMessage : undefined,
+			content: "content" in message ? message.content : undefined,
+		},
+	};
+}
+
+function replyText(entry: NativeReplyEntry): string | null {
+	const message = entry.type === "message" ? entry.message : undefined;
+	// Only native completed assistant messages qualify, including intermediate tool-use messages.
+	if (message?.role !== "assistant" || !["stop", "toolUse", "length"].includes(message.stopReason ?? "") || message.errorMessage) return null;
+	const content = message.content;
+	const text = typeof content === "string" ? content : Array.isArray(content)
+		? content.flatMap((part: unknown) => typeof part === "object" && part !== null &&
+			"type" in part && part.type === "text" && "text" in part && typeof part.text === "string" ? [part.text] : []).join("")
+		: "";
+	return text.trim() ? text : null;
+}
+
+export class ReplyNotifications<Connection extends object> {
+	private readonly devices = new Map<Connection, { deviceId: string; sent: Set<string> }>();
+
+	constructor(private readonly store: Store, private readonly send: (connection: Connection, notification: ReplyNotification) => void) {}
+
+	settings(): NotificationSettings {
+		return { mode: this.store.getSetting("notifications.mode") === "all-replies" ? "all-replies" : "inbox-only" };
+	}
+
+	revision(): string {
+		return this.store.getSetting("notifications.revision") ?? "0";
+	}
+
+	/** The read's revision is captured before RPC, so a toggle cannot admit an older in-flight read. */
+	observe(source: NativeReplySource, entries: readonly NativeReplyEntry[], revision: string): void {
+		if (revision !== this.revision()) return;
+		for (const entry of entries) {
+			if (typeof entry.id !== "string" || !entry.id) throw new Error("reply_history_entry_without_id");
+			const text = replyText(entry);
+			const notification = this.settings().mode === "all-replies" && text !== null ? {
+				id: crypto.randomUUID(), conv: source.conv, title: source.title, text,
+				...(source.workId ? { workId: source.workId } : {}),
+			} : null;
+			this.store.recordReplyNotification(source.sessionPath, entry.id, notification);
+		}
+		this.deliver();
+	}
+
+	setMode(mode: NotificationSettings["mode"]): void {
+		if (mode === this.settings().mode) return;
+		this.store.setNotificationMode(mode);
+	}
+
+	connectDevice(connection: Connection, deviceId: string): void {
+		if (this.devices.get(connection)?.deviceId === deviceId) return;
+		this.devices.set(connection, { deviceId, sent: new Set() });
+		this.deliver();
+	}
+
+	disconnectDevice(connection: Connection): void {
+		this.devices.delete(connection);
+		this.deliver();
+	}
+
+	ack(connection: Connection, id: string): boolean {
+		const device = this.devices.get(connection);
+		if (!device?.sent.has(id)) return false;
+		this.store.ackReplyNotification(id, device.deviceId);
+		return true;
+	}
+
+	/** Flushes committed occurrences, including explicitly published work replies. */
+	deliver(): void {
+		if (this.settings().mode !== "all-replies") return;
+		for (const [connection, device] of this.devices) {
+			for (const notification of this.store.pendingReplyNotifications(device.deviceId)) {
+				if ([...this.devices.values()].some((other) => other.deviceId === device.deviceId && other.sent.has(notification.id))) continue;
+				device.sent.add(notification.id);
+				this.send(connection, notification);
+			}
+		}
+	}
+}
+
+/** Native owners use this narrow seam; notification transport never observes synthetic chat publication. */
+export type NativeReplyObserver = Pick<ReplyNotifications<object>, "observe" | "revision" | "settings">;
+
+/** Writes serialize across awaited activation snapshots; rejected requests never reach the queue. */
+export class NotificationSettingsApi {
+	private writes: Promise<unknown> = Promise.resolve();
+
+	constructor(private readonly notifications: Pick<ReplyNotifications<object>, "settings" | "setMode">,
+		private readonly baseline: () => Promise<void>, private readonly publish: (settings: NotificationSettings) => void) {}
+
+	async handle(req: Request): Promise<Response> {
+		if (req.method === "GET") return Response.json(this.notifications.settings());
+		if (req.method !== "PUT") return Response.json({ error: "method_not_allowed" }, { status: 405 });
+		const body: unknown = await req.json().catch(() => null);
+		if (typeof body !== "object" || body === null || Array.isArray(body) || Object.keys(body).length !== 1 ||
+			!("mode" in body) || (body.mode !== "inbox-only" && body.mode !== "all-replies")) {
+			return Response.json({ error: "invalid_notification_settings" }, { status: 400 });
+		}
+		const mode = body.mode;
+		const write = this.writes.then(async () => {
+			if (mode === "all-replies" && this.notifications.settings().mode !== mode) await this.baseline();
+			this.notifications.setMode(mode);
+			const settings = this.notifications.settings();
+			this.publish(settings);
+			return Response.json(settings);
+		});
+		this.writes = write.catch(() => undefined);
+		return write;
+	}
+}

package/src/runtime/paths.ts

@@ -41,6 +41,7 @@ export interface RuntimePaths {
 	readonly backups: string;
 	readonly scheduleFile: string;
 	readonly voiceSettingFile: string;
+	readonly securityCheckFile: string;
 	readonly logs: string;
 	readonly secrets: string;
 	readonly omoTokenFile: string;
@@ -108,6 +109,7 @@ export function runtimePaths(env: Env = process.env, exists: (path: string) => b
 		backups: join(data, "backups"),
 		scheduleFile: value(env, "ZGW_SCHEDULE_FILE") ?? join(data, "schedule.json"),
 		voiceSettingFile: value(env, "ZGW_VOICE_SETTING_FILE") ?? join(data, "voice-setting"),
+		securityCheckFile: value(env, "ZGW_SECURITY_CHECK_FILE") ?? join(data, "security-check"),
 		logs: join(home, "logs"),
 		secrets,
 		omoTokenFile: value(env, "ZGW_OMO_TOKEN_FILE") ?? join(secrets, "omo-ws-token"),

package/src/security-allow.ts

@@ -0,0 +1,126 @@
+/** Runtime-only contract. Repository and release scanners never import this module. */
+export type HeldStatus = "pending" | "processing" | "sent" | "cancelled" | "failed" | "unconfirmed";
+export type SecurityErrorCode = "allowlist_persist_failed" | "state_persist_failed" | "payload_lost" | "dispatch_failed" | "dispatch_unknown" | "original_decision_conflict";
+export interface HeldState {
+	readonly id: string;
+	readonly decisionId: string;
+	readonly revision: number;
+	readonly conv: string;
+	readonly source: "message" | "answer";
+	readonly createdAt: string;
+	readonly originalDecisionId: string | null;
+	readonly status: HeldStatus;
+	readonly submissionId: string | null;
+	readonly remembered: boolean;
+	readonly allowlistRevision: number;
+	readonly errorCode: SecurityErrorCode | null;
+}
+export interface SecurityApprover {
+	readonly client: "web" | "android";
+	readonly deviceId: string | null;
+}
+export interface AllowedValue {
+	readonly id: string;
+	readonly value: string;
+	readonly kind: string;
+	readonly label: string;
+	readonly approvedAt: string;
+	readonly approvedBy: SecurityApprover;
+	readonly heldId: string;
+}
+export interface SecurityIntent {
+	readonly send: boolean;
+	readonly remember: boolean;
+	readonly expectedRevision: number | null;
+	readonly submissionId: string | null;
+}
+export type SecurityReceipt =
+	| { readonly kind: "message"; readonly conv: string; readonly messageSeq: number }
+	| { readonly kind: "answer"; readonly decisionId: string; readonly submissionId: string };
+export interface SecurityHoldRecord {
+	readonly state: HeldState;
+	readonly key: string | null;
+	readonly intent: SecurityIntent | null;
+	readonly dispatchReserved: boolean;
+	readonly receipt: SecurityReceipt | null;
+}
+export class SecurityRuntimeError extends Error {
+	constructor(
+		readonly code: "held_conflict" | "allowlist_conflict" | SecurityErrorCode,
+		readonly held?: HeldState,
+		readonly revision?: number,
+	) { super(code); }
+}
+export const securityDecision = (decision: { readonly payload: unknown }): boolean =>
+	typeof decision.payload === "object" && decision.payload !== null &&
+	"kind" in decision.payload && decision.payload.kind === "security-check";
+
+/** A delimiter is meaningful only if its matching quote can be proved. No decoding or normalization. */
+function quotedEnd(text: string, start: number, quote: string): number | null {
+	for (let i = start; i < text.length; i++) {
+		if (text[i] === "\\") { i++; continue; }
+		if (text[i] === quote) return i;
+	}
+	return null;
+}
+
+/** Expand an existing detector hit; this function never decides whether a hit exists. */
+export function canonicalSecurityValue(text: string, rule: string, start: number, end: number): string {
+	const lineStart = text.lastIndexOf("\n", start - 1) + 1;
+	const nextLine = text.indexOf("\n", end);
+	const lineEnd = nextLine < 0 ? text.length : nextLine;
+	// A PEM or SSH record owns every nested hit, including an address in its comment.
+	for (const match of text.matchAll(/-----BEGIN ([A-Z0-9 ]*PRIVATE KEY)-----/g)) {
+		const begin = match.index;
+		const closing = `-----END ${match[1]}-----`;
+		const at = text.indexOf(closing, begin + match[0].length);
+		const finish = at < 0 ? text.length : at + closing.length;
+		if (start >= begin && start < finish) return text.slice(begin, finish);
+	}
+	const line = text.slice(lineStart, lineEnd).replace(/\r$/, "");
+	if (/(?:ssh-(?:rsa|ed25519|dss)|ecdsa-sha2-[A-Za-z0-9-]+|sk-(?:ssh-ed25519|ecdsa-sha2-nistp256)@openssh\.com)[ \t]+[A-Za-z0-9+/]{20,}/.test(line)) return line;
+	// Locate quoted units and keep their original escape bytes.
+	let enclosing: { start: number; end: number | null } | undefined;
+	for (let i = lineStart; i < start; i++) {
+		const ch = text[i];
+		if (ch !== "'" && ch !== '"' && ch !== "`") continue;
+		const finish = quotedEnd(text, i + 1, ch);
+		if (finish === null || finish >= end) { enclosing = { start: i + 1, end: finish }; break; }
+		i = finish;
+	}
+	if (enclosing?.end === null) return text.slice(enclosing.start);
+	const header = /\b(?:authorization["']?\s*[:=]\s*["']?(?:Bearer|Basic)\s+|(?:set-cookie|cookie)["']?\s*[:=]\s*["']?)/i.exec(line);
+	if (header) {
+		const valueStart = lineStart + header.index + header[0].length;
+		if (start >= valueStart) return text.slice(valueStart, enclosing?.end ?? lineEnd).replace(/\r$/, "");
+	}
+	if (enclosing && enclosing.end !== null && /[:=]\s*$/.test(text.slice(lineStart, enclosing.start - 1))) {
+		return text.slice(enclosing.start, enclosing.end);
+	}
+	// URLs take precedence over addresses, token fragments and assignment captures inside them.
+	for (const match of text.matchAll(/[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s"'`<>]+/g)) {
+		if (start >= match.index && start < match.index + match[0].length) {
+			if (enclosing && enclosing.end !== null) return text.slice(match.index, enclosing.end);
+			return match[0];
+		}
+	}
+	// A path owns nested host/token captures. Quoted paths may contain spaces.
+	for (const match of text.matchAll(/\/(?:Users|home)\/[^\s"'`<>]*/g)) {
+		const finish = enclosing && enclosing.end !== null && match.index >= enclosing.start ?
+			enclosing.end : match.index + match[0].length;
+		if (start >= match.index && start < finish) return text.slice(match.index, finish);
+	}
+	if (["high-entropy-assignment", "credential-assignment", "device-serial", "authorization", "cookie-header"].includes(rule)) {
+		if (enclosing && enclosing.end !== null) return text.slice(start, enclosing.end);
+		if (rule === "authorization" || rule === "cookie-header") return text.slice(start, lineEnd).replace(/\r$/, "");
+		let finish = end;
+		while (finish < text.length && !/[\s,;}]/.test(text[finish] ?? "")) finish++;
+		return text.slice(start, finish);
+	}
+	if (["github-token", "npm-token", "anthropic-key", "openai-key", "notion-token", "slack-token", "aws-access-key", "gcp-api-key", "tailscale-key", "jwt"].includes(rule)) {
+		let finish = end;
+		while (finish < text.length && /[A-Za-z0-9_+/.=-]/.test(text[finish] ?? "")) finish++;
+		return text.slice(start, finish);
+	}
+	return text.slice(start, end);
+}