zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/host/omo-bridge/aside-tabs.ts

@@ -0,0 +1,41 @@
+import { asideBin } from "./agent-aside.ts";
+import { asideAccount } from "./agent-aside-tool.ts";
+
+// 294 D4: the bridge answers the gateway's `zgw_aside_tabs` with the tab list for the owner's picker. It runs the official
+// CLI for listing only (fixed script, argv, no shell); no agent session is involved and no tab is opened or changed.
+
+export const TABS_PREFIX = "ZGW_ASIDE_TABS ";
+const TABS_SCRIPT = `const tabs = await listBrowserTabs(); console.log(${JSON.stringify(TABS_PREFIX)} + JSON.stringify(tabs.map((t) => ({ targetId: String(t.targetId), url: String(t.url), title: String(t.title ?? "") }))));`;
+const LIST_TIMEOUT_MS = 60_000;
+
+export interface AsideTab { readonly targetId: string; readonly url: string; readonly title: string }
+export type TabsRunner = (bin: string, argv: readonly string[]) => Promise<{ code: number; stdout: string }>;
+
+const runTabs: TabsRunner = async (bin, argv) => {
+	const child = Bun.spawn([bin, ...argv], { stdin: "ignore", stdout: "pipe", stderr: "ignore", timeout: LIST_TIMEOUT_MS });
+	const [stdout, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+	return { code, stdout };
+};
+
+/** The last prefixed line of the listing; anything that is not a list of string-identified tabs is invalid. */
+export function parseAsideTabs(stdout: string): AsideTab[] | null {
+	const line = stdout.split("\n").map((entry) => entry.replace(/\u001b\[[0-9;]*m/g, "").trim()).reverse().find((entry) => entry.startsWith(TABS_PREFIX)) ?? "";
+	let value: unknown;
+	try { value = JSON.parse(line.slice(TABS_PREFIX.length)); } catch { return null; }
+	if (!Array.isArray(value)) return null;
+	return value.filter((tab): tab is AsideTab => typeof tab?.targetId === "string" && tab.targetId !== "" && typeof tab.url === "string")
+		.map((tab) => ({ targetId: tab.targetId, url: tab.url, title: typeof tab.title === "string" ? tab.title : "" }));
+}
+
+/** No confirmed account means no listing (the picker answers target_identity_unclear); a failed CLI run is an error. */
+export async function listAsideTabs(deps: { bin?: string; run?: TabsRunner; account?: (bin: string) => Promise<string | null> } = {}):
+	Promise<{ account: string | null; tabs: AsideTab[] }> {
+	const bin = deps.bin ?? asideBin();
+	const account = await (deps.account ?? asideAccount)(bin);
+	if (!account) return { account: null, tabs: [] };
+	const result = await (deps.run ?? runTabs)(bin, ["repl", "--account", account, TABS_SCRIPT]);
+	if (result.code !== 0) throw new Error("aside_failed");
+	const tabs = parseAsideTabs(result.stdout);
+	if (tabs === null) throw new Error("aside_output_invalid");
+	return { account, tabs };
+}

package/host/omo-bridge/attachment-read.ts

@@ -0,0 +1,100 @@
+import { createSecretKey, randomBytes, randomUUID, type KeyObject } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { parseManagedCallIdentity, type ManagedCallIdentity } from "../../src/agent/managed-call.ts";
+import { attachmentDocumentCall, attachmentReadCall } from "../../src/attachments/managed-binding.ts";
+import { runtimePaths } from "../../src/runtime/paths.ts";
+import { buildManagedCallProof, type ManagedNativeContext } from "./managed-call.ts";
+
+export const ATTACHMENT_READ_TOOL = "zgw_attachment_read";
+const ROUTE = "/internal/attachment-read";
+const DOCUMENT_ROUTE = "/internal/attachment-document";
+type NativeContext = ManagedNativeContext & { readonly cwd?: string };
+export interface AttachmentExtension {
+	readonly sessionKind: string;
+	readonly sessionContext: Readonly<Record<string, string>>;
+	readonly rpc: { handle(name: string, handler: (data: unknown) => unknown): void };
+	on(event: "session_start" | "session_shutdown", handler: (event: unknown, ctx: NativeContext) => unknown): void;
+	/** Present only on an engine that supports document input. */
+	setDocumentResolver?(resolve: (request: DocumentResolverRequest) => Promise<unknown>): void;
+	registerTool(tool: { name: string; label: string; description: string; parameters: unknown;
+		permissionParser(input: Record<string, unknown>): { permission: string; patterns: string[]; always: string[] }[];
+		execute(id: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: unknown, ctx: NativeContext): Promise<unknown> }): void;
+}
+interface DocumentResolverRequest { readonly reference: { readonly source: { readonly attachmentId: string; readonly grantId: string; readonly originalSha256: string } }; readonly mode: string; readonly sessionId: string; readonly signal?: AbortSignal }
+type BoundIdentity = Omit<ManagedCallIdentity, "inputId" | "toolCallId" | "logicalCallId">;
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Registers only for managed main and agent sessions. Work and CLI sessions get no tool and no handler. */
+export function installAttachmentRead(pi: AttachmentExtension): { bound(): boolean } {
+	const role = pi.sessionContext.zgw_role, conv = pi.sessionContext.zgw_conv;
+	if (pi.sessionKind !== "interactive" || !conv || (role !== "main" && role !== "agent")) return { bound: () => false };
+	let manager: ManagedNativeContext["sessionManager"] | undefined;
+	let binding: { identity: BoundIdentity; secret: KeyObject; inputId: string | null } | null = null;
+	pi.on("session_start", (_event, ctx) => { manager = ctx.sessionManager; binding = null; });
+	pi.on("session_shutdown", () => { manager = undefined; binding = null; });
+	pi.rpc.handle("zgw.attachment_bind", data => {
+		if (!record(data) || typeof data.secret !== "string" || !/^[a-f0-9]{64}$/.test(data.secret) || !record(data.identity) || !manager) throw new Error("attachment_bind_invalid");
+		const identity = parseManagedCallIdentity({ ...data.identity, inputId: "pending", toolCallId: "pending", logicalCallId: "pending" });
+		if (identity.convId !== conv || identity.role !== role || identity.agentId !== (pi.sessionContext.zgw_agent ?? null) ||
+			identity.durableSessionId !== manager.getSessionId() || identity.sessionPath !== manager.getSessionFile()) throw new Error("attachment_bind_mismatch");
+		binding = { identity, secret: createSecretKey(Buffer.from(data.secret, "hex")), inputId: typeof data.inputId === "string" ? data.inputId : null };
+		return { ok: true, documentResolver: resolverRegistered };
+	});
+	// Inline bytes are fetched here, per provider request, and never stored in the session. An unbound session gets the unavailable label.
+	const resolverRegistered = typeof pi.setDocumentResolver === "function";
+	pi.setDocumentResolver?.(async request => {
+		const current = binding, native = manager;
+		if (!current || !native || current.inputId === null || request.sessionId !== native.getSessionId()) return { status: "attachment_unavailable" };
+		const { attachmentId, grantId, originalSha256 } = request.reference.source;
+		const body = new TextEncoder().encode(JSON.stringify({ attachmentId, grantId, originalSha256, mode: request.mode }));
+		const toolCallId = `document-${randomUUID()}`;
+		const identity = parseManagedCallIdentity({ ...current.identity, inputId: current.inputId, toolCallId, logicalCallId: attachmentDocumentCall(toolCallId) });
+		const proof = buildManagedCallProof({ native: { sessionManager: native }, nativeInstance: native, identity, secret: current.secret,
+			currentIdentity: () => (binding === current && current.inputId === identity.inputId ? identity : null) },
+		{ method: "POST", route: DOCUMENT_ROUTE, operation: "attachment.document", body, nonce: randomBytes(32).toString("hex") });
+		try {
+			const base = process.env.ZGW_WORK_URL ?? `http://127.0.0.1:${process.env.ZGW_PORT ?? "8700"}`;
+			const response = await fetch(new URL(DOCUMENT_ROUTE, base), { method: "POST", redirect: "error", body,
+				headers: { authorization: `Bearer ${readFileSync(runtimePaths().omoTokenFile, "utf8").trim()}`, "content-type": "application/json",
+					"x-zigmini-managed-call": Buffer.from(JSON.stringify(proof)).toString("base64") },
+				signal: request.signal ? AbortSignal.any([request.signal, AbortSignal.timeout(120_000)]) : AbortSignal.timeout(120_000) });
+			return response.ok ? await response.json() : { status: "attachment_unavailable" };
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw error;
+			return { status: "attachment_unavailable" };
+		}
+	});
+	pi.rpc.handle("zgw.attachment_input", data => {
+		if (!binding || !record(data) || data.sessionIncarnation !== binding.identity.sessionIncarnation || typeof data.inputId !== "string") throw new Error("attachment_input_mismatch");
+		binding.inputId = data.inputId;
+		return { ok: true };
+	});
+	pi.registerTool({
+		name: ATTACHMENT_READ_TOOL, label: "Attachment read",
+		// Sending a file is already the owner's permission to read it, so a read preset must not ask again (C9-1).
+		permissionParser: input => [{ permission: "read", patterns: [`zgw-attachment:${String(input.attachmentId)}`], always: [] }],
+		description: "Read a document the user attached to this conversation. Identify it only by attachmentId from the message metadata. view text returns extracted text; view pages returns rendered pages of a PDF. Continue with nextCursor until it is absent.",
+		parameters: { type: "object", additionalProperties: false, required: ["attachmentId", "view"], properties: {
+			attachmentId: { type: "string" }, view: { type: "string", enum: ["text", "pages"] },
+			cursor: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 2000 } } },
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const current = binding, native = manager;
+			if (!current || !native || current.inputId === null) throw new Error("attachment_read_unbound");
+			const body = new TextEncoder().encode(JSON.stringify(params));
+			const identity = parseManagedCallIdentity({ ...current.identity, inputId: current.inputId, toolCallId, logicalCallId: attachmentReadCall(toolCallId) });
+			const proof = buildManagedCallProof({ native: ctx, nativeInstance: native, identity, secret: current.secret,
+				currentIdentity: () => (binding === current && current.inputId === identity.inputId ? identity : null) },
+			{ method: "POST", route: ROUTE, operation: "attachment.read", body, nonce: randomBytes(32).toString("hex") });
+			const base = process.env.ZGW_WORK_URL ?? `http://127.0.0.1:${process.env.ZGW_PORT ?? "8700"}`;
+			const response = await fetch(new URL(ROUTE, base), { method: "POST", redirect: "error", body,
+				headers: { authorization: `Bearer ${readFileSync(runtimePaths().omoTokenFile, "utf8").trim()}`, "content-type": "application/json",
+					"x-zigmini-managed-call": Buffer.from(JSON.stringify(proof)).toString("base64") },
+				signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(120_000)]) : AbortSignal.timeout(120_000) });
+			const result: unknown = await response.json();
+			if (!response.ok || !record(result) || !Array.isArray(result.content)) throw new Error(record(result) && typeof result.error === "string" ? result.error : `attachment_read_http_${response.status}`);
+			const { content, ...details } = result;
+			return { content: [{ type: "text", text: JSON.stringify(details) }, ...content], details };
+		},
+	});
+	return { bound: () => binding !== null };
+}

package/host/omo-bridge/bridge.ts

@@ -13,6 +13,7 @@ import { bunInstallDir, guardMode, guardStart } from "../../src/engine/schema-gu
 import { bridgeMayRun, readRegistry } from "../../src/runtime/slots.ts";
 import { BridgeMaintenance } from "./maintenance.ts";
 import { asciiJson } from "./ascii-json.ts";
+import { listAsideTabs } from "./aside-tabs.ts";
 
 const paths = runtimePaths();
 const home = paths.home;
@@ -506,6 +507,15 @@ const server = Bun.serve<Link>({
 					}));
 					return;
 				}
+				// 294 D4: the owner's Aside tab picker asks the bridge (token-authenticated link) for the tab list; the CLI lists
+				// only and no agent session is involved, so a link without a requester identity is answered too.
+				if (record(request) && request.type === "zgw_aside_tabs") {
+					const id = request.id;
+					const answer = (body: Record<string, unknown>) => deliver(link, JSON.stringify({ type: "response", id, command: "zgw_aside_tabs", ...body }));
+					void listAsideTabs().then((data) => answer({ success: true, data }),
+						(error: unknown) => answer({ success: false, error: error instanceof Error ? error.message : String(error) }));
+					return;
+				}
 				if (record(request) && link.identity) {
 					if (request.type === "zgw_transport_info" || request.type === "zgw_transport_resume") {
 						if (request.type === "zgw_transport_resume" && !link.ready) {

package/host/omo-bridge/managed-call.ts

@@ -0,0 +1,46 @@
+import type { KeyObject } from "node:crypto";
+import {
+	ManagedCallError, managedCallBodyDigest, managedCallSignature, parseManagedCallIdentity, sameManagedCallIdentity,
+	type ManagedCallIdentity, type ManagedCallProof, type ManagedCallRequest,
+} from "../../src/agent/managed-call.ts";
+
+/** Structural SDK port; getters on the real native context enforce runner retirement. */
+export interface ManagedNativeContext {
+	readonly sessionManager: {
+		getSessionId(): string;
+		getSessionFile(): string | undefined;
+	};
+	readonly signal?: AbortSignal;
+}
+
+/**
+ * Private adapter state, NEVER tool parameters, sessionContext metadata or log data.
+ * The trusted bind pins the native manager object and execution identity. Input/tool/
+ * logical-call IDs come from the host's actual invocation and operation ledger.
+ * Provisioning/Hub identity RPC and retirement wiring are owned by the consumer.
+ */
+export interface ManagedCallContext {
+	readonly native: ManagedNativeContext;
+	readonly nativeInstance: ManagedNativeContext["sessionManager"];
+	readonly identity: ManagedCallIdentity;
+	readonly secret: KeyObject;
+	/** Current trusted execution identity; null after retirement/cancel/settle. */
+	currentIdentity(): ManagedCallIdentity | null;
+}
+
+export function buildManagedCallProof(
+	context: ManagedCallContext,
+	request: ManagedCallRequest & { readonly nonce: string },
+): ManagedCallProof {
+	// Access the guarded native getter on EVERY call, including retries.
+	const manager = context.native.sessionManager;
+	const identity = parseManagedCallIdentity(context.identity);
+	if (manager !== context.nativeInstance || manager.getSessionId() !== identity.durableSessionId ||
+		manager.getSessionFile() !== identity.sessionPath || context.native.signal?.aborted)
+		throw new ManagedCallError("native_context_mismatch");
+	const current = context.currentIdentity();
+	if (current === null || !sameManagedCallIdentity(identity, current)) throw new ManagedCallError("binding_mismatch");
+	const content = { nonce: request.nonce, bodySha256: managedCallBodyDigest(request.body) };
+	const mac = managedCallSignature({ identity, secret: context.secret }, request, content);
+	return Object.freeze({ version: 1, identity, ...content, mac });
+}

package/host/omo-bridge/task-control.ts

@@ -1,13 +1,18 @@
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { registerAgentCollaboration, COLLABORATION_TOOLS, CollaborationExtensionError, type CollaborationControl } from "./agent-collaboration.ts";
+import { CollaborationSnapshots, type NativeFileSdk } from "./agent-collaboration-files.ts";
+import { loadEngineSdk } from "../../src/engine/index.ts";
 import { isDeepStrictEqual } from "node:util";
-import { runtimePaths } from "../../src/runtime/paths.ts";
+import { runtimeHome, runtimePaths } from "../../src/runtime/paths.ts";
 import { agentRules } from "../../src/agent-rules.ts";
 import { applyRequestRules, loadRequestRules, type ProviderRequestEvent } from "../../src/agent-request-rules.ts";
 import { nicknamePrompt, PROFILE_TIMEOUT_MS, readPromptProfile, type PromptProfile } from "../../src/profile-prompt.ts";
 
 // The pinned runtime supplies this SDK surface, just as it does for model-control.ts.
 type Entry = { id: string; type: string; customType?: string; data?: unknown; message?: { role: string; content: unknown; toolName?: string; details?: unknown; toolCallId?: string } };
-type Context = { sessionManager: { getSessionFile(): string | undefined; getEntries(): Entry[] } };
+type Context = { sessionManager: { getSessionFile(): string | undefined; getEntries(): Entry[] }; readonly cwd?: string; readonly model?: unknown; readonly thinkingLevel?: string };
 type Params = Record<string, unknown>;
 type Tool = {
 	name: string; label: string; description: string; parameters: unknown;
@@ -16,11 +21,14 @@ type Tool = {
 interface ExtensionApi {
 	readonly sessionKind: string;
 	readonly sessionContext: Readonly<Record<string, string>>;
-	readonly rpc: { handle(name: string, handler: () => unknown): void; emit(name: string, data: unknown): void };
+	readonly rpc: { handle(name: string, handler: (data: unknown) => unknown): void; emit(name: string, data: unknown): void };
 	readonly events: { on(name: string, handler: (data: unknown) => void): () => void };
 	on(event: "session_start", handler: (event: unknown, ctx: Context) => void): void;
 	on(event: "before_agent_start", handler: (event: { systemPrompt: string }) => unknown, options: { previewSafe: boolean }): void;
 	on(event: "before_provider_request", handler: (event: ProviderRequestEvent) => unknown): void;
+	on(event: "input", handler: (event: { inputId: string; text: string }) => unknown): void;
+	on(event: "session_abort" | "session_shutdown" | "agent_settled", handler: () => void): void;
+	on(event: "tool_call", handler: (event: { toolName: string }) => unknown): void;
 	registerTool(tool: Tool): void;
 	appendEntry(customType: string, data: unknown): void;
 }
@@ -127,19 +135,41 @@ async function postWork(operation: string, requestKey: string, sourceSessionPath
 	return result;
 }
 
-export default function taskControl(pi: ExtensionApi): void {
+// allow: SIZE_OK - existing main/work lifecycle and report protocol; the shared file adapter owns the new file logic.
+export default function taskControl(pi: ExtensionApi, loadSdk: () => Promise<NativeFileSdk> = () => loadEngineSdk<NativeFileSdk>()): void {
 	const role = pi.sessionContext.zgw_role;
 	const workId = pi.sessionContext.zgw_work;
 	const conv = pi.sessionContext.zgw_conv;
 	let runtime: Context | undefined;
-	pi.on("session_start", (_event, ctx) => { runtime = ctx; });
+	let collaboration: CollaborationControl | undefined;
+	pi.on("session_start", async (_event, ctx) => {
+		runtime = ctx; collaboration?.start(ctx);
+		collaboration?.applied({ definitionSha: mainSha, fingerprint: createHash("sha256").update(JSON.stringify({ mainSha, model: ctx.model, thinking: ctx.thinkingLevel })).digest("hex") });
+		if (collaboration) {
+			if (!ctx.cwd) throw new CollaborationExtensionError("native_cwd_missing");
+			const sdk = await loadSdk();
+			new CollaborationSnapshots({ root: join(runtimeHome(), "agents"), control: collaboration, queue: sdk.withFileMutationQueue,
+				assertKnowledgeLock() { throw new CollaborationExtensionError("read_only_continuation"); } }).install(pi, { sdk, cwd: ctx.cwd });
+		}
+	});
 	pi.rpc.handle("zgw.work_identity", () => ({ role, workId, conv, sessionPath: runtime?.sessionManager.getSessionFile() }));
 	const isMain = role === "main" && pi.sessionKind === "interactive" && Boolean(conv);
 	const isWork = role === "work" && pi.sessionKind === "worker" && Boolean(workId);
 	if (!isMain && !isWork) return; // No task tools in unrelated CLI or speech-summary workers.
+	collaboration = isMain ? registerAgentCollaboration(pi) : undefined;
+	if (collaboration) {
+		pi.on("input", event => { collaboration?.input(event); });
+		for (const event of ["session_abort", "session_shutdown", "agent_settled"] as const) pi.on(event, () => { collaboration?.revoke(); });
+		pi.on("tool_call", event => {
+			try { if (!COLLABORATION_TOOLS.includes(event.toolName)) collaboration?.assertGeneralTool(); }
+			catch (error) { if (error instanceof CollaborationExtensionError) return { block: true, reason: error.code }; throw error; }
+			if (collaboration?.isPeer() && ["bash", "eval", "task", "zgw_work_report"].includes(event.toolName)) return { block: true, reason: "collaboration_tool_forbidden" };
+		});
+	}
 	const rules = agentRules();
 	console.warn(rules.log);
 	const rulesText = rules.text === "" ? "" : `\n\n${rules.text}`;
+	const mainSha = createHash("sha256").update(rulesText).digest("hex");
 	const requestRules = loadRequestRules();
 	pi.on("before_provider_request", (event) => applyRequestRules(event, requestRules));
 
@@ -168,6 +198,7 @@ export default function taskControl(pi: ExtensionApi): void {
 			name: "zgw_precomment", label: "Precomment", description: PRECOMMENT_DESCRIPTION,
 			parameters: { type: "object", properties: { text: { type: "string", minLength: 1, maxLength: PRECOMMENT_MAX } }, required: ["text"], additionalProperties: false },
 			async execute(toolCallId, params, signal, _update, ctx) {
+				collaboration?.assertGeneralTool();
 				// A precomment is advisory: a recording failure is reported to the model and never blocks the turn.
 				try {
 					const text = precommentText(params.text);
@@ -189,6 +220,7 @@ export default function taskControl(pi: ExtensionApi): void {
 			description: "List the user's agents read-only: name, one-line description and the web link of each agent's conversation. Use it to answer which agents exist or to give the user the link to open one. Returns no agent knowledge.",
 			parameters: { type: "object", properties: {}, additionalProperties: false },
 			async execute(_toolCallId, _params, signal) {
+				collaboration?.assertGeneralTool();
 				const token = readFileSync(runtimePaths().omoTokenFile, "utf8").trim();
 				const response = await fetch(new URL("/internal/agent-list", gatewayBase()), {
 					headers: { authorization: `Bearer ${token}` },
@@ -212,11 +244,13 @@ export default function taskControl(pi: ExtensionApi): void {
 			name: `zgw_work_${operation}`, label: `Work ${operation}`, description: spec.description,
 			parameters: { type: "object", properties: spec.fields, required: spec.required, additionalProperties: false },
 			async execute(toolCallId, params, signal, _update, ctx) {
+				collaboration?.assertGeneralTool();
 				const sourceSessionPath = ctx.sessionManager.getSessionFile();
 				if (!sourceSessionPath) throw new Error("work_source_session_missing");
 				const requestKey = JSON.stringify([sourceSessionPath, toolCallId]);
 				let payload: Params = params;
 				if (operation === "report") {
+					if (isMain && collaboration?.isPeer()) throw new Error("collaboration_owner_answer_forbidden");
 					if (isMain && (params.kind !== "question" ||
 						Object.keys(params).some((key) => !["kind", "summary", "details"].includes(key)))) {
 						throw new Error("main_question_only");

package/host/omo-check/patches/attachments-293/README.md

@@ -0,0 +1,138 @@
+# Unreleased attachment 293 engine candidate
+
+This directory is a test candidate, not a release registration. The released
+manifest, existing patches, compatibility pins, installer and build-ID code are
+unchanged. Revision 4 is only the existing builder's nested directory label under
+a task-owned, manifest-hashed root. Never install this candidate over a published
+or installed engine.
+
+## Reproduction
+
+`test/fixtures/attachments/engine/candidate.ts` installs the stock
+`omo-ai@5.1.51` package with the existing `installStock` (npm registry, or
+`ZIGMINI_REGISTRY_URL`) as its input. It reads nothing from `.omo/evidence`
+(bug 304), so a fresh clone, CI and another Mac build the same tree. It stages this manifest, the
+unchanged baseline patches and the document patch, then calls the existing
+`buildPatched(version, omoDir, patchDir)` with both directories explicit. The
+builder checks fixed original and patched hashes. It never derives expected
+hashes from the candidate it is checking.
+
+The output is `<cache>/<manifest-sha>/omo/5.1.51-zgw.4`, where `<cache>` is
+`ATTACHMENT_ENGINE_CACHE` or `zgw-attachment-engine` in the OS temp folder.
+Importing `candidate-ready.ts` (or awaiting `buildCandidate()`) builds the
+candidate once; later runs verify the fixed patched hashes. Importing
+`candidate.ts` alone has no side effect. `ATTACHMENT_ENGINE_ROOT` uses an already built candidate instead.
+Without network access and without that variable, the engine tests fail; they
+are never skipped.
+The source snippets in `document-content.js` and `document-content.types.txt`
+are included in the frozen unified patch, not imported from this directory at
+runtime. Changing a snippet requires updating that patch and its fixed manifest
+hashes together.
+
+From the task worktree:
+
+```sh
+env -i HOME="$HOME" PATH="$PATH" USER="$USER" LOGNAME="$LOGNAME" \
+  SHELL="$SHELL" TMPDIR="${TMPDIR:-/tmp}" LANG=en_US.UTF-8 \
+  bun run heavy omo-check -- perl -e 'alarm shift; exec @ARGV' 600 \
+  bun test/fixtures/attachments/engine/run.ts \
+  bun test/fixtures/attachments/engine/candidate.ts
+```
+
+Use the same clean wrapper with the `test` slot for
+`bun test test/contract/attachment-engine.contract.test.ts` and
+`bun test test/unit/attachment-engine.test.ts`.
+Use the separate `mutation` slot for
+`bun test test/mutation/attachment-engine.test.ts`.
+`ATTACHMENT_MUTATION_SEED` can reproduce a recorded seed when set after slot
+acquisition. Normal mutation runs choose a new seed.
+`fingerprint.ts` hashes the complete candidate tree and rejects escaping links.
+
+## Engine boundary
+
+RPC advertises `document_content_v1`. `prompt`, `steer` and `follow_up` accept the
+approved PDF `DocumentContent`, owner metadata and client input identity.
+Ingress checks PDF magic, original digest, size and exact attachment/grant
+correlation. The persisted input is a `DocumentReference`; base64 is not stored
+in admission, queue or transcript records. Compaction checkpoints retain
+references and owner/input provenance even after the resident mirror is trimmed.
+`append_session_entry` also accepts validated owner-document history for native
+session replacement. Bare `append_user_message` cannot invent document
+provenance; it remains text/image-only.
+
+The gateway extension registers the resolver with
+`pi.setDocumentResolver(resolve)`, either while the extension loads or later.
+Only one extension owns it per session; another owner gets
+`document_resolver_already_registered`. An in-process host may call
+`AgentSession.setDocumentResolver(resolve)` directly.
+The resolver receives the current native session/input identity, the originating
+input ID, exact reference, selected model, mode and cancellation signal. It must
+use the verified managed binding and active grant ledger. A filename, attachment
+ID or callback registration is not authentication. No resolver means a typed
+unavailable label; there is no implicit filesystem reader.
+
+A ready resolver reply carries:
+
+- Original SHA, the reader's **unchanged** representation SHA and grant revision.
+- `payloadSha256`: SHA256 of UTF-8
+  `JSON.stringify({content, coverage, ...(nextCursor === undefined ? {} : {nextCursor})})`.
+  This delivery-envelope digest is separate from the native reader's complete
+  prepared-text digest. T4's digest and cursor contracts are not redefined.
+- The validated representation, coverage, optional opaque continuation and
+  a conservative input-token estimate from the preparing service.
+
+The native helper's internal scalar cursor is not this engine's opaque cursor.
+T6 must translate it through its grant-bound cursor service and recheck the
+reader's original/representation digest before constructing a delivery envelope.
+The engine does not issue grants, inspect text-security holds, or implement HMAC.
+
+`ready` is the resolver's complete-preparation prerequisite. `coverage` describes
+only the current bounded delivery, not all prepared pages. A partial initial
+delivery requires `nextCursor`, including OCR. The engine retains that opaque
+cursor with the exact source/grant, representation digest and grant revision;
+it does not fetch or concatenate subsequent chunks. Subsequent
+`zgw_attachment_read` replies remain bounded text/image tool results, with T6
+responsible for their cursor scope, range completion and release checks.
+Non-native delivered `rendered-image` pages require exactly one actual image
+block per declared page. Text coverage requires actual text that isn't only
+whitespace after trimming, and a truly empty page uses `verified-blank`. The
+aggregate text content is bounded to 48 KiB in UTF-8, not JavaScript characters.
+
+Public OpenAI Responses and Anthropic Messages use top-level native PDF blocks.
+Subscription requests use prepared text/images; text-only models use prepared
+OCR text. Requests reselect their representation, including after reopen,
+compaction and a provider change. Revoked/unavailable replies become typed
+labels. `attachment_text_held` stops the request without content.
+
+The engine bounds original bytes, base64, coverage, image count/bytes and
+serialized requests. Native size/page/context overflow selects pages before a
+provider dispatch where that representation fits. Provider errors carrying
+document input do not retry an uncertain request. Claude document requests use a
+fresh cold seed with all authorized document page images, rather than the old
+eight-image history elision.
+
+## Evidence boundaries
+
+The contracts execute the candidate's native CLI runtime, RPC handler, durable
+queue/transcript and compaction pipeline. Public and ChatGPT adapters use real
+loopback HTTP with scripted model replies. Claude's actual adapter is exercised
+at its SDK query/prompt boundary with scripted SDK replies; this is not proof of
+Claude SDK-internal HTTP framing or real-model comprehension.
+
+Prepared page/OCR inputs in these engine fixtures are synthetic representation
+inputs. They are not evidence of PDFKit rendering or Vision recognition. Those
+native operations remain T4's proof. Managed-call authentication and rotation
+remain 292 T4-owned. The fixture's reopen/compaction checks do not claim that
+unimplemented authentication integration ran. Gateway/T6 registration and final
+combined-channel tests remain separate.
+
+Primary provider documents read on 2026-11-06:
+
+- `https://developers.openai.com/api/docs/guides/file-inputs`
+- `https://platform.claude.com/docs/en/build-with-claude/pdf-support`
+
+The local OpenAI serialized ceiling is 50,000,000 bytes, stricter than the
+documented aggregate decoded-file limit after base64 expansion. The public
+Anthropic ceiling is 128,000,000 bytes. Subscription input uses a conservative
+24 MiB engine-request ceiling. These are payload checks, not live semantic
+verification or authorization to call configured providers.