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

package/src/attachments/types.ts

@@ -0,0 +1,123 @@
+import type { Database } from "bun:sqlite";
+
+export type AttachmentFormat = "html" | "md" | "txt" | "pdf";
+export type AttachmentReadMode = "text" | "native-document" | "pages" | "ocr";
+export type AttachmentState = "snapshotting" | "sealed" | "preparing" | "ready" | "bound" | "discarded" | "error" | "revoked";
+export type AttachmentEncoding = "utf-8" | "utf-16le" | "utf-16be" | "euc-kr" | "cp949";
+export interface AttachmentRecipient {
+	readonly kind: "main" | "agent";
+	readonly id: string;
+	readonly epoch: number;
+}
+export interface AttachmentScope {
+	readonly ownerPrincipal: string;
+	readonly draftId: string;
+	readonly convId: string;
+	readonly convEpoch: number;
+	readonly recipient: AttachmentRecipient;
+}
+export interface AttachmentManifest {
+	readonly attachmentId: string;
+	readonly expectedRevision: number;
+	readonly preparationRevision: number;
+	readonly originalSha256: string;
+	readonly representationSha256: string;
+}
+/** Frozen attachmentAdmission DTO; full existing message data is a separate argument. */
+export interface AttachmentAdmission extends AttachmentScope {
+	readonly submissionId: string;
+	readonly requestDigest: string;
+	readonly inspectedTextSha256: string;
+	readonly text: string;
+	readonly attachments: readonly AttachmentManifest[];
+}
+export interface AttachmentMetadata {
+	readonly id: string;
+	readonly grantId: string;
+	readonly name: string;
+	readonly format: AttachmentFormat;
+	readonly bytes: number;
+	readonly sha256: string;
+	readonly readMode: AttachmentReadMode;
+	readonly pageCount?: number;
+	/** Client frames only. Read from this grant's row when sent; never stored in the message. */
+	readonly grantRevoked?: boolean;
+}
+export interface AttachmentAccepted {
+	readonly convId: string;
+	readonly submissionId: string;
+	readonly messageSeq: number;
+	readonly pendingDispatchSeq: number;
+	readonly attachments: readonly AttachmentMetadata[];
+}
+export interface AttachmentCAS {
+	readonly expectedRevision: number;
+	readonly jobGeneration: string;
+}
+export interface AttachmentJob {
+	readonly attachmentId: string;
+	readonly state: AttachmentState;
+	readonly revision: number;
+	readonly jobGeneration: string;
+	readonly preparationRevision: number;
+}
+export interface AttachmentPreparation {
+	readonly originalSha256: string;
+	readonly preparationRevision: number;
+	readonly representationSha256: string;
+	readonly inspectedTextSha256: string;
+	readonly readMode: AttachmentReadMode;
+	readonly pageCount?: number;
+}
+export interface AttachmentSelection {
+	readonly scope: AttachmentScope;
+	readonly operationId: string;
+	readonly entryIdentity: Readonly<Record<string, unknown>>;
+	readonly sourceIdentity: Readonly<Record<string, unknown>>;
+	readonly name: string;
+	readonly format: AttachmentFormat;
+	readonly bytes: number;
+	readonly jobGeneration: string;
+}
+/** Structurally compatible with confirmed 292 AttachmentOrigin, not an authority token. */
+export interface SelectedAttachmentExport {
+	readonly attachmentId: string;
+	readonly sourceGrantId: string;
+	readonly sourceGrantRevision: number;
+	readonly originMessageSeq: number;
+	readonly sourceConvId: string;
+	readonly sourceRecipientId: string;
+	readonly sourceConvEpoch: number;
+	readonly sourceRecipientEpoch: number;
+	readonly originalSha256: string;
+	readonly bytes: number;
+	readonly format: string;
+	readonly name: string;
+}
+export interface AttachmentCurrent {
+	readonly convEpoch: number;
+	readonly recipient: AttachmentRecipient;
+	readonly ownerActive: boolean;
+	/** Omitted in standalone mode; supplied by the real 294 ledger in combined mode. */
+	readonly authority?: { readonly epoch: number; readonly accessState: "open" | "blocked"; readonly policyRevision: number };
+}
+/** Trusted internal adapters, never model/client DTOs. All calls are synchronous on the writer connection.
+ * current reads the existing lifecycle/identity ledger; no attachment-owned lifecycle counter exists.
+ * original checks the sealed descriptor bytes, not source_identity_json or the original host pathname.
+ * inspect enforces the existing text security guard against the exact admission + preparation digests.
+ */
+export interface AttachmentGate {
+	readonly current: (tx: Database, scope: AttachmentScope) => AttachmentCurrent;
+	readonly original: (tx: Database, attachmentId: string) => { readonly bytes: number; readonly sha256: string } | null;
+	readonly inspect: (tx: Database, admission: AttachmentAdmission, preparations: readonly AttachmentPreparation[]) => undefined;
+}
+export type AttachmentErrorCode =
+	| "invalid_attachment_input" | "attachment_not_found" | "attachment_scope_mismatch" | "attachment_owner_inactive"
+	| "attachment_cas_conflict" | "attachment_not_ready" | "attachment_already_bound" | "attachment_manifest_conflict"
+	| "attachment_original_unavailable" | "operation_conflict" | "submission_conflict" | "request_digest_mismatch"
+	| "staging_quota_exceeded" | "too_many_attachments" | "attachment_reference_unavailable" | "attachment_revoked"
+	| "attachment_busy" | "attachment_tombstoned" | "attachment_provider_invalid" | "attachment_transaction_required"
+	| "agent_access_blocked" | "authority_epoch_mismatch";
+export class AttachmentStoreError extends Error {
+	constructor(readonly code: AttachmentErrorCode, readonly status = 409) { super(code); this.name = "AttachmentStoreError"; }
+}

package/src/cli/doctor.ts

@@ -4,7 +4,7 @@ import { relative, resolve, sep } from "node:path";
 import { consentState, loadNotice, readConsent } from "../consent/consent.ts";
 import { OMO_REGISTRY_URL, engine } from "../engine/index.ts";
 import { bunInstallDir, checkSchema, globalEngineVersion, globalEngineWarning, readStoreSchema, SCHEMA_TOO_NEW, type SchemaCheck } from "../engine/schema-guard.ts";
-import { GC_PATH } from "../gc.ts";
+import { HOUSEKEEPING_PATH } from "../housekeeping/api.ts";
 import { agentDir } from "../model-accounts.ts";
 import { type InstallKind } from "../runtime/install-kind.ts";
 import { readVoiceSetting } from "../voice-setting.ts";
@@ -45,7 +45,10 @@ export interface DoctorDeps extends LaunchdDeps {
 	readonly schema: () => SchemaCheck;
 	readonly diskFree: (path: string) => number | null;
 	readonly consent: () => ConsentView;
+	/** Open candidates of the housekeeping gc role (회수); null when the gateway did not answer. */
 	readonly gcCandidates?: () => number | null | Promise<number | null>;
+	/** Open candidates of the housekeeping reconcile role (상태 정리); null when the gateway did not answer. */
+	readonly reconcileCandidates?: () => number | null | Promise<number | null>;
 	/** npm install only (Todo 26): the raw voice setting and whether <home>/voice/installed.json exists; null elsewhere. */
 	readonly voiceInstall?: () => { readonly on: boolean; readonly installed: boolean } | null;
 	/** GET /api/update/status of the running gateway; null when it did not answer. */
@@ -63,6 +66,7 @@ export interface DoctorReport {
 	readonly counts: DoctorCounts | null;
 	readonly rpcDaemons: readonly string[];
 	readonly gcCandidates: number | null;
+	readonly reconcileCandidates: number | null;
 	readonly fix?: { readonly targets: readonly Service[]; readonly failed: readonly Service[] };
 }
 
@@ -149,7 +153,9 @@ export async function collect(deps: DoctorDeps, ctx: LaunchdContext): Promise<Do
 		detail: free === null ? "확인 실패" : `${(free / 1024 ** 3).toFixed(1)}GB` });
 
 	const gc = deps.gcCandidates === undefined ? null : await deps.gcCandidates();
-	if (gc !== null) items.push({ id: "gc", label: "정리 후보", status: "info", detail: `${gc}개` });
+	if (gc !== null) items.push({ id: "gc", label: "정리 후보 (회수)", status: "info", detail: `${gc}개` });
+	const reconcile = deps.reconcileCandidates === undefined ? null : await deps.reconcileCandidates();
+	if (reconcile !== null) items.push({ id: "reconcile", label: "정리 후보 (상태 정리)", status: "info", detail: `${reconcile}개` });
 
 	if (deps.access !== undefined) items.push(await deps.access());
 
@@ -163,7 +169,7 @@ export async function collect(deps: DoctorDeps, ctx: LaunchdContext): Promise<Do
 			? `만료(동의한 버전 ${consent.version}, 지금 ${consent.noticeVersion}). \`zigmini consent\`를 실행하세요` : "없음. `zigmini consent`를 실행하세요" });
 
 	return { ok: !items.some((item) => item.status === "bad"), items, consent, omo: { status: health?.omo ?? null, pinned, global, latest },
-		counts, rpcDaemons: rpc ?? [], gcCandidates: gc };
+		counts, rpcDaemons: rpc ?? [], gcCandidates: gc, reconcileCandidates: reconcile };
 }
 
 /** Only the broken launchd agents; consent and a too-new schema are not fixed by a restart. */
@@ -254,12 +260,31 @@ export function gcTotal(body: unknown): number | null {
 	return typeof body === "object" && body !== null ? count((body as { total?: unknown }).total) : null;
 }
 
+/** Per-role open candidate counts of GET /api/housekeeping; null unless both are counts. */
+export function housekeepingCounts(body: unknown): { reconcile: number; gc: number } | null {
+	if (typeof body !== "object" || body === null) return null;
+	const roles = (body as { roles?: { reconcile?: { total?: unknown }; gc?: { total?: unknown } } }).roles;
+	const reconcile = count(roles?.reconcile?.total);
+	const gc = count(roles?.gc?.total);
+	return reconcile === null || gc === null ? null : { reconcile, gc };
+}
+
 export function engineFolder(omoRoot: string, target: string): string | null {
 	const version = relative(omoRoot, resolve(omoRoot, target));
 	return version === "" || version.startsWith("..") || version.includes(sep) ? null : version;
 }
 
 export function systemDoctorDeps(base: LaunchdDeps, ctx: LaunchdContext, kind: InstallKind): DoctorDeps {
+	// One doctor scan per run serves both role counts.
+	let scanned: Promise<{ reconcile: number; gc: number } | null> | null = null;
+	const housekeeping = () => scanned ??= (async () => {
+		try {
+			const url = `http://127.0.0.1:${ctx.paths.ports.web}${HOUSEKEEPING_PATH}?trigger=doctor`;
+			return housekeepingCounts(await (await fetch(url, { signal: AbortSignal.timeout(60_000) })).json());
+		} catch {
+			return null;
+		}
+	})();
 	return {
 		...base,
 		portOpen: canConnect,
@@ -284,13 +309,8 @@ export function systemDoctorDeps(base: LaunchdDeps, ctx: LaunchdContext, kind: I
 				return null;
 			}
 		},
-		gcCandidates: async () => {
-			try {
-				return gcTotal(await (await fetch(`http://127.0.0.1:${ctx.paths.ports.web}${GC_PATH}`, { signal: AbortSignal.timeout(30_000) })).json());
-			} catch {
-				return null;
-			}
-		},
+		gcCandidates: async () => (await housekeeping())?.gc ?? null,
+		reconcileCandidates: async () => (await housekeeping())?.reconcile ?? null,
 		pinnedEngine: () => {
 			try {
 				return engineFolder(ctx.paths.omo, readlinkSync(ctx.paths.omoCurrent));

package/src/decisions.ts

@@ -1,11 +1,13 @@
 import { isDeepStrictEqual } from "node:util";
 import { decisionContext } from "./decision-context.ts";
 import { SecurityCheckError, type MessageGuard } from "./security-check.ts";
-import { securityDecision, SecurityRuntimeError } from "./security-allow.ts";
+import { artifactReviewDecision, securityDecision, SecurityRuntimeError, type ArtifactSecurityHold } from "./security-allow.ts";
+import { collaborationStageDecision } from "./agent/collaboration-types.ts";
+import { AgentToolPermissionError, parseToolGrantAnswer, type OwnerPrincipal } from "./agent/tool-permissions.ts";
 import type { OmoEvent } from "./omo/client.ts";
 import { say, type Text } from "./server-text.ts";
-import type { ActionAnswerData, DecisionAnswerRequest, DecisionInfo, DecisionsPageData, DecisionUpdatedData } from "./protocol.ts";
-import { blockedMainQuestion, blockedQuestion, DecisionStoreError, RESUMABLE_CLOSED, Store, type Decision, type DecisionMethod, type DecisionSubmission, type StoredEvent } from "./store.ts";
+import type { ActionAnswerData, ArtifactReviewInfo, DecisionAnswerRequest, DecisionInfo, DecisionsPageData, DecisionUpdatedData } from "./protocol.ts";
+import { blockedMainQuestion, blockedQuestion, DecisionStoreError, INSTRUCTION_RELEASED, releasedWorkQuestion, RESUMABLE_CLOSED, Store, type Decision, type DecisionMethod, type DecisionSubmission, type StoredEvent } from "./store.ts";
 
 export interface DecisionOwner {
 	readonly conv: string;
@@ -30,6 +32,8 @@ export interface DecisionPorts {
 	sendLive(decision: Decision): boolean;
 	dispatchWork(workId: string): Promise<void>;
 	dispatchMain(input: StoredEvent): Promise<void>;
+	/** Wakes the shared collaboration dispatcher of a conversation whose request continuation now holds an owner answer. */
+	dispatchCollaboration?(conv: string): Promise<void>;
 	/** Reads existing owning-session evidence. Must not replay an uncertain command. */
 	reconcile(decision: Decision): Promise<void>;
 }
@@ -141,6 +145,7 @@ export class DecisionService {
 	private stopped = false;
 	private refreshing = false;
 	private readonly receiptMs: number;
+	private toolPrincipal: ((req: Request) => OwnerPrincipal | Response) | null = null;
 
 	constructor(
 		private readonly store: Store,
@@ -164,8 +169,64 @@ export class DecisionService {
 		return decision;
 	}
 
+	/** The caller helper (main.ts) that verifies the owner of a tool purpose answer. */
+	useToolPrincipal(resolver: (req: Request) => OwnerPrincipal | Response): void {
+		this.toolPrincipal = resolver;
+	}
+
+	/**
+	 * Tool purpose answers (294 C3): only the structured toolGrant or cancelled body with a verified owner. A plain
+	 * confirm, value or free text answer stays pending with tool_grant_response_required; no grant or execution is made.
+	 */
+	private answerToolGrant(id: string, input: unknown, principal: OwnerPrincipal | null): DecisionInfo {
+		const request = parseToolGrantAnswer(input);
+		if (!request) {
+			parseDecisionAnswer(input);
+			throw new DecisionStoreError("tool_grant_response_required", this.required(id));
+		}
+		if (!principal) throw new DecisionStoreError("tool_grant_principal_required", this.required(id));
+		let answered: ReturnType<Store["answerAgentToolDecision"]>;
+		try {
+			answered = this.store.answerAgentToolDecision(id, request, principal);
+		} finally {
+			this.refresh();
+		}
+		// Only a freshly committed allow carries an execution (deny/cancel have none); a replayed submission never runs again.
+		const invocationId = answered.fresh ? answered.result?.invocationId ?? null : null;
+		if (invocationId) {
+			try { this.toolGranted?.(invocationId); }
+			catch (error) { this.error(error); }
+		}
+		if (answered.fresh) {
+			try { this.toolAnswered?.(id); }
+			catch (error) { this.error(error); }
+		}
+		return this.info(this.required(id));
+	}
+
+	private toolGranted: ((invocationId: string) => void) | undefined;
+
+	/** 294 item 5: called once after an owner allow commits; main.ts starts the delivery of that execution. */
+	useToolGranted(listener: (invocationId: string) => void): void {
+		this.toolGranted = listener;
+	}
+
+	private toolAnswered: ((decisionId: string) => void) | undefined;
+
+	/** Q-07: called once after any owner answer of a tool card commits (allow, deny or cancel); Hub continues a collaboration card. */
+	useToolAnswered(listener: (decisionId: string) => void): void {
+		this.toolAnswered = listener;
+	}
+
 	info(decision: Decision): DecisionInfo {
+		if (collaborationStageDecision(decision)) return { ...decision, work: null, allowedActions: [] };
+		if (this.store.toolPermissions.isToolPurpose(decision.id)) {
+			return { ...decision, work: null, allowedActions: decision.status === "pending" && decision.submissionId === null ? ["answer"] : [] };
+		}
 		if (securityDecision(decision)) {
+			// A held artifact read is answered through the owner hold route; the generic answer stays refused (security_endpoint_required).
+			const hold = artifactReviewDecision(decision) ? this.store.artifactSecurityHold(decision.id) : null;
+			if (hold) return { ...decision, work: null, allowedActions: hold.state === "pending" ? ["answer"] : [], artifactReview: this.artifactReview(hold) };
 			const security = this.store.securityHold(decision.id)?.state;
 			return { ...decision, work: null, allowedActions: [], ...(security ? { security } : {}) };
 		}
@@ -194,6 +255,15 @@ export class DecisionService {
 		};
 	}
 
+	/** The owner's view of a held artifact read: the hold state, the reading agent, the file, the part asked for and the finding summary. */
+	private artifactReview(hold: ArtifactSecurityHold): ArtifactReviewInfo {
+		const artifact = this.store.agentArtifact(hold.resourceRef.artifactId);
+		return { holdId: hold.id, revision: hold.revision, state: hold.state, resumeState: hold.continuation.state,
+			agentId: this.store.getConversation(hold.readScope.granteeConv)?.agentId ?? null,
+			requestId: hold.resourceRef.requestId, artifactId: hold.resourceRef.artifactId, fileName: artifact?.originalName || hold.resourceRef.artifactId,
+			view: hold.representation.view, range: { start: hold.representation.range.start, end: hold.representation.range.end }, summary: hold.summary ?? null };
+	}
+
 	list(options: { limit?: number; cursor?: string } = {}): DecisionsPageData {
 		this.refresh();
 		const page = this.store.listDecisions(options);
@@ -208,6 +278,7 @@ export class DecisionService {
 	answer(id: string, input: unknown, checked = false): DecisionInfo {
 		const original = this.store.getDecision(id);
 		if (original && securityDecision(original)) throw new DecisionStoreError("security_endpoint_required");
+		if (original && this.store.toolPermissions.isToolPurpose(id)) return this.answerToolGrant(id, input, null);
 		const request = parseDecisionAnswer(input);
 		if (!checked) {
 			const owner = this.store.getDecision(id)?.ownerConv ?? "main";
@@ -248,6 +319,11 @@ export class DecisionService {
 			this.dispatch(id, () => this.ports.dispatchMain(inputEvent), checked);
 		} else if (operation?.data.commandId && decision.workId) {
 			this.dispatch(id, () => this.ports.dispatchWork(decision.workId!), checked);
+		} else if (operation?.data.commandId?.startsWith("collaboration:") && operation.data.commandId !== "collaboration:ended") {
+			const wake = this.ports.dispatchCollaboration;
+			// The answer also unblocks queued input elsewhere in the same request tree; those conversations get no other wake.
+			const convs = new Set([decision.ownerConv, ...this.store.agentDecisionDependents(id)]);
+			if (wake) this.dispatch(id, () => Promise.all([...convs].map(conv => wake(conv))).then(() => undefined), checked);
 		}
 		this.refresh();
 		return this.info(this.required(id));
@@ -311,7 +387,7 @@ export class DecisionService {
 			throw new DecisionStoreError("invalid_decision_answer", decision);
 		}
 		// A main question kept open without its native wait takes a chat-card answer as a resume.
-		const released = decision.bindingState === "closed" && decision.reason === "main_released";
+		const released = (decision.bindingState === "closed" && decision.reason === "main_released") || releasedWorkQuestion(decision);
 		if (!supplied && !released && (decision.bindingState !== "live" || !this.ports.liveBinding(decision))) return false;
 		const response: Record<string, unknown> = {};
 		if (data.cancel !== undefined) {
@@ -387,6 +463,20 @@ export class DecisionService {
 		return true;
 	}
 
+	/**
+	 * Bug 236 (operator decision 2026-11-05): a newer instruction was queued behind a work's turn that waits on this
+	 * required question. The work's native wait ends so the instruction runs; the question stays open in the inbox and its
+	 * answer reaches the work later as a follow-up command. True when the caller must now end the native wait.
+	 */
+	releaseWorkWait(id: string): boolean {
+		if (this.stopped) return false;
+		const decision = this.required(id);
+		if (decision.workId === null || !blockedQuestion(decision) || decision.status !== "pending" || decision.submissionId !== null) return false;
+		this.store.setDecisionBinding(decision.id, decision.revision, { state: "closed", reason: INSTRUCTION_RELEASED });
+		this.refresh();
+		return true;
+	}
+
 	/**
 	 * Improvement 77: a required question that a generation handoff parked comes back from the new generation with a new
 	 * request id (the frame id is a fresh routing id; the toolCallId stays). Exactly one unanswered decision of the same
@@ -535,7 +625,7 @@ export class DecisionService {
 			this.store.reconcileDecisionReceipts();
 			const now = Date.now();
 			for (let decision of this.store.allDecisions()) {
-				if (securityDecision(decision)) continue;
+				if (securityDecision(decision) || collaborationStageDecision(decision) || this.store.toolPermissions.isToolPurpose(decision.id)) continue;
 				if (!unresolved(decision)) continue;
 				const context = this.store.decisionContextReason(decision);
 				if (context === "work_failed" || context === "work_cancelled") {
@@ -563,7 +653,7 @@ export class DecisionService {
 				}
 			}
 			for (const decision of this.store.allDecisions()) {
-				if (securityDecision(decision)) continue;
+				if (securityDecision(decision) || collaborationStageDecision(decision)) continue;
 				if (decision.method === "question" && decision.status === "pending" && decision.bindingState === "live") {
 					this.store.reconcileReissuedQuestion(decision.id, this.ports.liveBinding(decision));
 				}
@@ -574,7 +664,7 @@ export class DecisionService {
 				const previous = this.known.get(decision.id);
 				this.known.set(decision.id, decision);
 				if (!previous || previous.revision < decision.revision) {
-					if (!securityDecision(decision) && previous && previous.status !== decision.status && !unresolved(decision)) {
+					if (!securityDecision(decision) && !collaborationStageDecision(decision) && previous && previous.status !== decision.status && !unresolved(decision)) {
 						const answer = record(decision.answer) ? decision.answer : {};
 						const kind = decision.method === "question" ? "question" : decision.method === "confirm" ? "confirm" : "value";
 						const dismissedText = decision.status === "closed" && Object.hasOwn(DISMISSED_REASONS, decision.reason ?? "") ? DISMISSED_REASONS[decision.reason ?? ""] : undefined;
@@ -596,7 +686,7 @@ export class DecisionService {
 				}
 				const times: number[] = [];
 				if (unresolved(decision) && decision.bindingState === "live" && decision.deadlineAt !== null) times.push(decision.deadlineAt);
-				if (!securityDecision(decision) && decision.status === "submitted") {
+				if (!securityDecision(decision) && !collaborationStageDecision(decision) && decision.status === "submitted") {
 					const operation = this.store.latestDecisionOperation(decision.id);
 					times.push(Date.parse(operation?.ts ?? decision.updatedAt) + this.receiptMs);
 				}
@@ -637,12 +727,17 @@ export class DecisionService {
 			if (route[2] === "/dismiss" && req.method === "POST") {
 				return Response.json(this.dismiss(id, await req.json().catch(() => null)));
 			}
+			if (route[2] === "/answer" && req.method === "POST" && this.store.toolPermissions.isToolPurpose(id)) {
+				const principal = this.toolPrincipal ? this.toolPrincipal(req) : null;
+				if (principal instanceof Response) return principal;
+				return Response.json(this.answerToolGrant(id, await req.json().catch(() => null), principal));
+			}
 			if (route[2] && req.method === "POST") {
 				return Response.json(this.answer(id, await req.json().catch(() => null)));
 			}
 			if (!route[2] && req.method === "GET") {
 				const decision = this.required(id);
-				if (!securityDecision(decision) && unresolved(decision)) {
+				if (!securityDecision(decision) && !collaborationStageDecision(decision) && unresolved(decision)) {
 					let timer: ReturnType<typeof setTimeout> | undefined;
 					try {
 						await Promise.race([
@@ -673,7 +768,11 @@ export class DecisionService {
 			if (error instanceof DecisionStoreError) {
 				return Response.json({
 					error: error.code, decision: error.decision ? this.info(error.decision) : null,
-				}, { status: error.code === "decision_not_found" ? 404 : error.code === "security_endpoint_required" || error.code.startsWith("invalid_") ? 400 : 409 });
+				}, { status: error.code === "decision_not_found" ? 404 : error.code === "tool_grant_principal_required" ? 403
+					: error.code === "security_endpoint_required" || error.code === "tool_grant_response_required" || error.code.startsWith("invalid_") ? 400 : 409 });
+			}
+			if (error instanceof AgentToolPermissionError) {
+				return Response.json({ error: error.code }, { status: error.status, headers: { "Cache-Control": "no-store" } });
 			}
 			if (error instanceof URIError) return Response.json({ error: "invalid_decision" }, { status: 400 });
 			this.error(error);

package/src/engine/apply-patch.ts

@@ -6,6 +6,12 @@ export function patchPath(value: string): string {
 	return value;
 }
 
+/**
+ * A file section whose blocks start with this line replaces text instead of lines: `-<old>` then `+<new>`, where <old>
+ * occurs exactly once in the file. For one-line minified files, so a patch never repeats the whole line.
+ */
+export const REPLACE_BLOCK = "@@ replace @@";
+
 export function applyPatch(patch: string, read: (path: string) => string): Map<string, string> {
 	const lines = patch.split("\n");
 	if (lines.pop() !== "") throw new Error("patch_missing_final_newline");
@@ -18,6 +24,21 @@ export function applyPatch(patch: string, read: (path: string) => string): Map<s
 		const path = patchPath(header.slice(6).split("\t")[0]!);
 		const next = lines[i++] ?? "";
 		if (!next.startsWith("+++ b/") || next.slice(6).split("\t")[0] !== path) throw new Error("patch_new_header_invalid");
+		if (lines[i] === REPLACE_BLOCK) {
+			let text = result.get(path) ?? read(path);
+			while (lines[i] === REPLACE_BLOCK) {
+				i++;
+				const from = lines[i++] ?? "";
+				const to = lines[i++] ?? "";
+				if (!from.startsWith("-") || from.length < 2 || !to.startsWith("+")) throw new Error(`patch_replace_invalid:${path}`);
+				const old = from.slice(1);
+				const at = text.indexOf(old);
+				if (at < 0 || text.includes(old, at + 1)) throw new Error(`patch_replace_match:${path}`);
+				text = text.slice(0, at) + to.slice(1) + text.slice(at + old.length);
+			}
+			result.set(path, text);
+			continue;
+		}
 		const source = (result.get(path) ?? read(path)).match(/[^\n]*\n|[^\n]+$/g) ?? [];
 		const output: string[] = [];
 		let cursor = 0;

package/src/engine/compat.json

@@ -2,5 +2,6 @@
   "omo": "5.1.51",
   "senpi": "2026.10.27-1",
   "threadSchema": 10,
-  "verifiedAt": "2026-11-03"
+  "capabilities": ["agent_tool_authority"],
+  "verifiedAt": "2026-11-11"
 }

package/src/engine/install.ts

@@ -196,8 +196,45 @@ async function bounded<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
 	} finally { clearTimeout(timer); }
 }
 
+export const ENGINE_CAPABILITY_MISSING = "engine_capability_missing";
+
+type EngineCommand = (type: string, params: Record<string, unknown>) => Promise<unknown>;
+
+/** One live proof per engine capability the gateway pin requires (compat.json `capabilities`). */
+const CAPABILITY_PROBES: Readonly<Record<string, (command: EngineCommand, sessionId: string, candidate: string) => Promise<boolean>>> = {
+	// 294: the host pushes a revisioned policy and the engine acknowledges exactly it. Governed eval needs QuickJS.
+	async agent_tool_authority(command, sessionId, candidate) {
+		if (!existsSync(join(candidate, "node_modules/quickjs-wasi/package.json"))) return false;
+		const ack = await command("zgw.agent_tool_policy", { sessionId, policy: { revision: 1, grants: [], missing: "deny" } }) as
+			{ readonly revision?: unknown; readonly grants?: unknown; readonly missing?: unknown } | null | undefined;
+		return ack?.revision === 1 && ack.grants === 0 && ack.missing === "deny";
+	},
+};
+
+/** Refuses the candidate unless every required capability passes its probe; a failed command is a missing capability. */
+export async function proveCapabilities(command: EngineCommand, sessionId: string, candidate: string, capabilities: readonly string[]): Promise<void> {
+	for (const capability of capabilities) {
+		const probe = Object.hasOwn(CAPABILITY_PROBES, capability) ? CAPABILITY_PROBES[capability] : undefined;
+		if (probe === undefined) throw new Error(`engine_capability_unknown:${capability}`);
+		let proven: boolean;
+		try {
+			proven = await probe(command, sessionId, candidate);
+		} catch (error) {
+			throw new Error(`${ENGINE_CAPABILITY_MISSING}:${capability}`, { cause: error });
+		}
+		if (!proven) throw new Error(`${ENGINE_CAPABILITY_MISSING}:${capability}`);
+	}
+}
+
+/** The capability list of the compatibility pin; anything but an array of names is an invalid pin. */
+export function pinCapabilities(pin: { readonly capabilities?: unknown }): readonly string[] {
+	if (pin.capabilities === undefined) return [];
+	if (!Array.isArray(pin.capabilities) || !pin.capabilities.every((name) => typeof name === "string")) throw new Error("engine_pin_invalid:capabilities");
+	return pin.capabilities;
+}
+
 /** A private socket host, relayed to OmoClient, exercises the real protocol without any model calls. */
-export async function smokeEngine(home: string, candidate: string, options: { readonly port?: number; readonly timeoutMs?: number } = {}): Promise<void> {
+export async function smokeEngine(home: string, candidate: string, options: { readonly port?: number; readonly timeoutMs?: number; readonly capabilities?: readonly string[] } = {}): Promise<void> {
 	const scratch = mkdtempSync(join(home, "omo/.smoke-"));
 	const socket = join(scratch, "rpc.sock");
 	const timeout = options.timeoutMs ?? 30_000;
@@ -282,6 +319,8 @@ export async function smokeEngine(home: string, candidate: string, options: { re
 		const opened = await bounded(client.command<{ sessionId: string }>("open_session", { cwd: scratch }), timeout);
 		const tools = await bounded(client.command<string[]>("extension_request", { sessionId: opened.sessionId, name: "zigmini.install.probe" }), timeout);
 		if (!tools.includes("zigmini_install_probe")) throw new Error("engine_smoke_extension_missing");
+		const live = client;
+		await bounded(proveCapabilities((type, params) => live.command(type, params), opened.sessionId, candidate, options.capabilities ?? []), timeout);
 		await bounded(client.command("close_session", { sessionId: opened.sessionId }), timeout);
 	} finally {
 		client?.stop();
@@ -321,10 +360,12 @@ export async function installEngine(options: {
 	readonly acceptLicense?: boolean;
 	readonly engineOnly?: boolean;
 	readonly confirmLicense?: (summary: string, path: string) => Promise<boolean>;
-	readonly smoke?: { readonly port?: number; readonly timeoutMs?: number };
+	readonly smoke?: { readonly port?: number; readonly timeoutMs?: number; readonly capabilities?: readonly string[] };
 }): Promise<string> {
-	const pin: { readonly omo: string; readonly threadSchema?: number } = JSON.parse(readFileSync(new URL("./compat.json", import.meta.url), "utf8"));
+	const pin: { readonly omo: string; readonly threadSchema?: number; readonly capabilities?: unknown } = JSON.parse(readFileSync(new URL("./compat.json", import.meta.url), "utf8"));
 	const version = options.version ?? pin.omo;
+	// The pinned build must prove the pin's capabilities before `current` moves; running engines are never stopped here.
+	const capabilities = options.smoke?.capabilities ?? (version === pin.omo ? pinCapabilities(pin) : []);
 	if (options.agentDir !== undefined && version === pin.omo) {
 		const found = storeIncompatibility(readStoreSchema(options.agentDir), pin.threadSchema ?? null);
 		if (found !== null) throw new Error(`${ENGINE_SCHEMA_INCOMPATIBLE}:store=${found.store},supported=${found.supported}`);
@@ -335,7 +376,7 @@ export async function installEngine(options: {
 	const candidate = join(omoDir, target);
 	if (options.agentDir !== undefined) assertStoreCompatible(options.agentDir, candidate);
 	await acceptEngineLicense(options.home, candidate, options);
-	await smokeEngine(options.home, candidate, options.smoke);
+	await smokeEngine(options.home, candidate, { ...options.smoke, capabilities });
 	candidateExecutable(candidate);
 	const current = join(omoDir, "current");
 	if (existsSync(current) && !lstatSync(current).isSymbolicLink()) throw new Error("engine_current_not_symlink");

package/src/engine/sandbox-cell.ts

@@ -0,0 +1,2 @@
+/** 294 item 6: the engine's sandbox cell module, relative to the pinned engine root (agent-execution runs it confined). */
+export const SANDBOX_CELL_MODULE = "node_modules/@code-yeongyu/senpi-codemode/src/kernels/sandbox/sandbox-cell.ts";