zigmini 0.8.0-beta.7 → 0.9.0-beta.2

package/src/main.ts

@@ -4,7 +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, handleSecurityCheckSetting, MessageGuard, SECURITY_CHECK_PATH, SECURITY_HELD_PATH, SecurityCheckError, defaultChecker } from "./security-check.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";
@@ -150,9 +150,17 @@ 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,
@@ -321,6 +329,7 @@ const decisions = new DecisionService(store, {
 	v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(),
 	conv: data.decision.ownerConv, type: "decision.updated", data,
 }), { onHistory: (event) => hub.publishStored(event), guard: messageGuard });
+securityDecisionRefresh = () => decisions.refresh();
 hub.attachDecisions(decisions);
 const summarizer = new SpeechSummarizer(omo, {
 	sessionDir: config.omoSessionDir,
@@ -476,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;
@@ -652,9 +663,11 @@ 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, (id, outcome) => publish({
-			v: PROTOCOL_VERSION, id: crypto.randomUUID(), ts: new Date().toISOString(), conv: "*", type: "security-check.resolved", data: { id, outcome },
-		}));
+		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) {
@@ -878,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);
@@ -926,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

@@ -1,9 +1,20 @@
+import { FrameSocket } from "./frame-socket.ts";
 import { NativeLifecycleLog, type NativeLifecycleRecord } from "./lifecycle.ts";
 import { RecoveryReceiptLog } from "./recovery-receipt.ts";
 import type { RecoveryOpenContext, RecoveryReceiptRecord } from "./recovery-receipt-types.ts";
 
 export type OmoStatus = "connecting" | "ready" | "disconnected";
 
+interface OmoSocket {
+	readonly readyState: number;
+	onopen: (() => void) | null;
+	onmessage: ((event: { readonly data: string }) => void) | null;
+	onclose: ((event: { readonly code: number; readonly reason: string; readonly wasClean: boolean }) => void) | null;
+	onerror: ((event: { readonly message?: string }) => void) | null;
+	send(text: string): void;
+	close(): void;
+}
+
 export interface OmoEvent {
 	type: string;
 	sessionId?: string;
@@ -79,7 +90,7 @@ type Pending = {
 const STABLE_READY_MS = 10_000;
 
 export class OmoClient {
-	private ws: WebSocket | null = null;
+	private ws: OmoSocket | null = null;
 	private nextId = 1;
 	private readonly instanceId = crypto.randomUUID();
 	private readonly pending = new Map<string, Pending>();
@@ -157,10 +168,12 @@ export class OmoClient {
 		this.setStatus("connecting");
 		this.recovery?.connecting();
 		if (this.stopped) return;
-		const ws = new WebSocket(this.url, { headers: {
+		const headers: Record<string, string> = {
 			Authorization: `Bearer ${this.token}`,
 			...(this.connectionId ? { "x-zgw-connection-id": this.connectionId } : {}),
-		} } as unknown as string[]);
+		};
+		const ws: OmoSocket = this.url.startsWith("ws://") ? new FrameSocket(this.url, headers)
+			: new WebSocket(this.url, { headers } as unknown as string[]) as unknown as OmoSocket;
 		this.ws = ws;
 		ws.onopen = () => {
 			let continuityLoss: string | undefined;

package/src/omo/frame-socket.ts

@@ -0,0 +1,330 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { Socket } from "bun";
+
+// Bug 221: Bun's WebSocket client misreads valid bridge frames in long sessions (1002/1011 closes on a byte stream
+// that parses cleanly). This client speaks RFC 6455 over plain TCP for ws:// bridge URLs, so frame parsing is ours.
+export const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+const CLOSE_WAIT_MS = 1_000;
+export const HANDSHAKE_LIMIT = 16_384;
+
+export type FrameSocketState = 0 | 1 | 2 | 3;
+export interface FrameSocketClose { readonly code: number; readonly reason: string; readonly wasClean: boolean }
+
+export function acceptFor(key: string): string {
+	return createHash("sha1").update(`${key}${WS_GUID}`).digest("base64");
+}
+
+export function encodeFrame(opcode: number, payload: Uint8Array, mask: Uint8Array): Uint8Array {
+	if (mask.length !== 4) throw new Error("frame_mask_length");
+	const length = payload.length;
+	const extra = length < 126 ? 0 : length <= 0xffff ? 2 : 8;
+	const frame = new Uint8Array(2 + extra + 4 + length);
+	frame[0] = 0x80 | opcode;
+	if (extra === 0) frame[1] = 0x80 | length;
+	else if (extra === 2) {
+		frame[1] = 0x80 | 126;
+		frame[2] = length >>> 8;
+		frame[3] = length & 0xff;
+	} else {
+		frame[1] = 0x80 | 127;
+		new DataView(frame.buffer).setBigUint64(2, BigInt(length));
+	}
+	const at = 2 + extra;
+	frame.set(mask, at);
+	payload.forEach((byte, i) => { frame[at + 4 + i] = byte ^ mask[i & 3]!; });
+	return frame;
+}
+
+export type HandshakeHead =
+	| { readonly kind: "need" }
+	| { readonly kind: "too_large" }
+	| { readonly kind: "head"; readonly head: string; readonly rest: string };
+
+export function handshakeHead(text: string): HandshakeHead {
+	const end = text.indexOf("\r\n\r\n");
+	if (end === -1) return text.length > HANDSHAKE_LIMIT ? { kind: "too_large" } : { kind: "need" };
+	if (end > HANDSHAKE_LIMIT) return { kind: "too_large" };
+	return { kind: "head", head: text.slice(0, end), rest: text.slice(end + 4) };
+}
+
+export interface WriteSink { write(bytes: Uint8Array): number }
+
+export class WriteQueue {
+	private readonly pending: Uint8Array[] = [];
+
+	get size(): number {
+		return this.pending.length;
+	}
+
+	write(sink: WriteSink, bytes: Uint8Array): void {
+		if (this.pending.length > 0) {
+			this.pending.push(bytes);
+			return;
+		}
+		const written = sink.write(bytes);
+		if (written < bytes.length) this.pending.push(bytes.subarray(Math.max(0, written)));
+	}
+
+	flush(sink: WriteSink): void {
+		while (this.pending.length > 0) {
+			const head = this.pending[0]!;
+			const written = sink.write(head);
+			if (written < head.length) {
+				this.pending[0] = head.subarray(Math.max(0, written));
+				return;
+			}
+			this.pending.shift();
+		}
+	}
+}
+
+export interface ParsedFrame { readonly fin: boolean; readonly opcode: number; readonly payload: Uint8Array }
+export type ParseResult =
+	| { readonly kind: "frame"; readonly frame: ParsedFrame; readonly used: number }
+	| { readonly kind: "need"; readonly bytes: number }
+	| { readonly kind: "error"; readonly code: number; readonly reason: string };
+
+export function parseFrame(buffer: Uint8Array, maxBytes = MAX_MESSAGE_BYTES): ParseResult {
+	if (buffer.length < 2) return { kind: "need", bytes: 2 };
+	const first = buffer[0]!;
+	const second = buffer[1]!;
+	if ((first & 0x70) !== 0) return { kind: "error", code: 1002, reason: "reserved_bits_set" };
+	if ((second & 0x80) !== 0) return { kind: "error", code: 1002, reason: "masked_server_frame" };
+	const fin = (first & 0x80) !== 0;
+	const opcode = first & 0x0f;
+	if (![0, 1, 2, 8, 9, 10].includes(opcode)) return { kind: "error", code: 1002, reason: "unknown_opcode" };
+	const control = opcode >= 8;
+	let length = second & 0x7f;
+	let header = 2;
+	if (length === 126) {
+		if (buffer.length < 4) return { kind: "need", bytes: 4 };
+		length = (buffer[2]! << 8) | buffer[3]!;
+		header = 4;
+	} else if (length === 127) {
+		if (buffer.length < 10) return { kind: "need", bytes: 10 };
+		length = Number(new DataView(buffer.buffer, buffer.byteOffset + 2, 8).getBigUint64(0));
+		header = 10;
+	}
+	if (control && (!fin || length > 125)) return { kind: "error", code: 1002, reason: "invalid_control_frame" };
+	if (length > maxBytes) return { kind: "error", code: 1009, reason: "message_too_big" };
+	if (buffer.length < header + length) return { kind: "need", bytes: header + length };
+	return { kind: "frame", frame: { fin, opcode, payload: buffer.subarray(header, header + length) }, used: header + length };
+}
+
+export class FrameSocket {
+	static readonly OPEN = 1;
+	readyState: FrameSocketState = 0;
+	onopen: (() => void) | null = null;
+	onmessage: ((event: { readonly data: string }) => void) | null = null;
+	onclose: ((event: FrameSocketClose) => void) | null = null;
+	onerror: ((event: { readonly message?: string }) => void) | null = null;
+
+	private socket: Socket<undefined> | null = null;
+	private readonly key = randomBytes(16).toString("base64");
+	private handshake = "";
+	private input: Uint8Array[] = [];
+	private inputBytes = 0;
+	private inputNeeded = 2;
+	private readonly output = new WriteQueue();
+	private fragments: Uint8Array[] = [];
+	private fragmentBytes = 0;
+	private fragmentOpcode = 0;
+	private closeTimer: ReturnType<typeof setTimeout> | null = null;
+	private closed = false;
+	private readonly decoder = new TextDecoder();
+
+	constructor(url: string, private readonly headers: Readonly<Record<string, string>> = {}, private readonly maxBytes = MAX_MESSAGE_BYTES) {
+		const target = new URL(url);
+		if (target.protocol !== "ws:") throw new Error(`frame_socket_unsupported_url:${target.protocol}`);
+		for (const [name, value] of Object.entries(headers)) {
+			if (/[\r\n:]/.test(name) || /[\r\n]/.test(value)) throw new Error("frame_socket_invalid_header");
+		}
+		const port = Number(target.port || 80);
+		const path = `${target.pathname || "/"}${target.search}`;
+		const host = target.port ? `${target.hostname}:${target.port}` : target.hostname;
+		Bun.connect({
+			hostname: target.hostname.replace(/^\[|\]$/g, ""),
+			port,
+			socket: {
+				open: (socket) => {
+					this.socket = socket;
+					if (this.closed) {
+						socket.end();
+						return;
+					}
+					const lines = [`GET ${path} HTTP/1.1`, `Host: ${host}`, "Connection: Upgrade", "Upgrade: websocket",
+						"Sec-WebSocket-Version: 13", `Sec-WebSocket-Key: ${this.key}`,
+						...Object.entries(this.headers).map(([name, value]) => `${name}: ${value}`)];
+					this.write(new TextEncoder().encode(`${lines.join("\r\n")}\r\n\r\n`));
+				},
+				data: (_socket, chunk) => this.receive(chunk),
+				drain: () => this.flush(),
+				close: () => this.finish(1006, "", false),
+				error: (_socket, error) => this.fail(1006, error.message),
+				connectError: (_socket, error) => this.fail(1006, error.message),
+			},
+		}).catch((error: Error) => this.fail(1006, error.message));
+	}
+
+	send(text: string): void {
+		if (this.readyState !== FrameSocket.OPEN) throw new Error("frame_socket_not_open");
+		this.write(encodeFrame(1, new TextEncoder().encode(text), randomBytes(4)));
+	}
+
+	close(code = 1000, reason = ""): void {
+		if (this.readyState >= 2) return;
+		if (this.readyState === 0) {
+			this.finish(1006, reason, false);
+			return;
+		}
+		this.readyState = 2;
+		this.sendClose(code, reason);
+		this.closeTimer = setTimeout(() => this.finish(1006, reason, false), CLOSE_WAIT_MS);
+	}
+
+	private sendClose(code: number, reason: string): void {
+		const text = new TextEncoder().encode(reason);
+		const payload = new Uint8Array(2 + text.length);
+		payload[0] = code >>> 8;
+		payload[1] = code & 0xff;
+		payload.set(text, 2);
+		this.write(encodeFrame(8, payload, randomBytes(4)));
+	}
+
+	private write(bytes: Uint8Array): void {
+		if (this.socket) this.output.write(this.socket, bytes);
+	}
+
+	private flush(): void {
+		if (this.socket) this.output.flush(this.socket);
+	}
+
+	private receive(chunk: Uint8Array): void {
+		if (this.closed) return;
+		if (this.readyState === 0) {
+			this.handshake += Buffer.from(chunk).toString("latin1");
+			const parsed = handshakeHead(this.handshake);
+			if (parsed.kind === "need") return;
+			if (parsed.kind === "too_large") {
+				this.fail(1006, "handshake_too_large");
+				return;
+			}
+			this.handshake = "";
+			const rest = Buffer.from(parsed.rest, "latin1");
+			const [status, ...fields] = parsed.head.split("\r\n");
+			const accept = fields.find((line) => /^sec-websocket-accept:/i.test(line))?.split(":")[1]?.trim();
+			if (!/^HTTP\/1\.1 101 /.test(status ?? "")) {
+				this.fail(1006, `handshake_status:${status ?? ""}`);
+				return;
+			}
+			if (accept !== acceptFor(this.key)) {
+				this.fail(1006, "handshake_accept_mismatch");
+				return;
+			}
+			this.readyState = 1;
+			this.dispatch(() => this.onopen?.());
+			this.receive(rest);
+			return;
+		}
+		this.input.push(chunk.slice());
+		this.inputBytes += chunk.length;
+		if (this.inputBytes < this.inputNeeded) return;
+		const merged = new Uint8Array(this.inputBytes);
+		let at = 0;
+		for (const part of this.input) {
+			merged.set(part, at);
+			at += part.length;
+		}
+		let offset = 0;
+		while (!this.closed) {
+			const parsed = parseFrame(merged.subarray(offset), this.maxBytes);
+			if (parsed.kind === "need") {
+				this.inputNeeded = parsed.bytes;
+				break;
+			}
+			if (parsed.kind === "error") {
+				this.protocolError(parsed.code, parsed.reason);
+				return;
+			}
+			offset += parsed.used;
+			this.handle(parsed.frame);
+		}
+		const rest = merged.slice(offset);
+		this.input = [rest];
+		this.inputBytes = rest.length;
+	}
+
+	private handle(frame: ParsedFrame): void {
+		const { opcode, payload, fin } = frame;
+		if (opcode === 9) {
+			if (this.readyState === 1) this.write(encodeFrame(10, payload, randomBytes(4)));
+			return;
+		}
+		if (opcode === 10) return;
+		if (opcode === 8) {
+			const code = payload.length >= 2 ? (payload[0]! << 8) | payload[1]! : 1005;
+			const reason = this.decoder.decode(payload.subarray(2));
+			if (this.readyState === 1) this.sendClose(code === 1005 ? 1000 : code, "");
+			this.finish(code, reason, true);
+			return;
+		}
+		if (opcode === 0 ? this.fragmentOpcode === 0 : this.fragmentOpcode !== 0) {
+			this.protocolError(1002, "unexpected_continuation");
+			return;
+		}
+		if (opcode !== 0) this.fragmentOpcode = opcode;
+		this.fragmentBytes += payload.length;
+		if (this.fragmentBytes > this.maxBytes) {
+			this.protocolError(1009, "message_too_big");
+			return;
+		}
+		this.fragments.push(payload.slice());
+		if (!fin) return;
+		const whole = new Uint8Array(this.fragmentBytes);
+		let at = 0;
+		for (const part of this.fragments) {
+			whole.set(part, at);
+			at += part.length;
+		}
+		this.fragments = [];
+		this.fragmentBytes = 0;
+		this.fragmentOpcode = 0;
+		if (this.readyState === 1) {
+			const data = this.decoder.decode(whole);
+			this.dispatch(() => this.onmessage?.({ data }));
+		}
+	}
+
+	private protocolError(code: number, reason: string): void {
+		if (this.readyState === 1) this.sendClose(code, reason);
+		this.dispatch(() => this.onerror?.({ message: `frame_socket_protocol_error:${reason}` }));
+		this.finish(code, reason, false);
+	}
+
+	private dispatch(handler: () => void): void {
+		try {
+			handler();
+		} catch (error) {
+			queueMicrotask(() => {
+				throw error;
+			});
+		}
+	}
+
+	private fail(code: number, message: string): void {
+		if (this.closed) return;
+		this.dispatch(() => this.onerror?.({ message }));
+		this.finish(code, message, false);
+	}
+
+	private finish(code: number, reason: string, wasClean: boolean): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.readyState = 3;
+		if (this.closeTimer) clearTimeout(this.closeTimer);
+		this.flush();
+		this.socket?.end();
+		this.dispatch(() => this.onclose?.({ code, reason, wasClean }));
+	}
+}

package/src/protocol.ts

@@ -85,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;
@@ -151,7 +152,7 @@ export type ClientMessage =
 	| { 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 }

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);
+}