@xopcai/xopc 0.0.385 → 0.0.387

package/dist/src/tasks/task-handoff.js

@@ -0,0 +1,510 @@
+import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
+import { getBrowserTabBindingById, init_browser_tab_binding_repository } from "../storage/sqlite/browser-tab-binding-repository.js";
+import { parseResultReferenceId, resultReferenceId, resultReferenceVersion } from "../../packages/gateway-contract/src/result-reference.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "../storage/sqlite/session-instance-repository.js";
+import { getSessionInputById, init_session_input_repository } from "../storage/sqlite/session-input-repository.js";
+import { TaskRepository, init_task_repository } from "./task-repository.js";
+import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../storage/sqlite/session-repository.js";
+import { getSessionConfig, init_config_repository } from "../storage/sqlite/config-repository.js";
+import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
+import { getProjectForSession } from "../projects/workspace.js";
+import { resolveMediaReference } from "../media/media-reference.js";
+import { assertPersonalResultDelegateAccess, readPersonalResult, resolvePersonalResultReference } from "../personal-agent/result-reader.js";
+import { fileSpaceId, parseFileResourceId } from "../files/file-service.js";
+import { NotesStore } from "../notes/store.js";
+import { TaskContextRepository } from "./task-context-repository.js";
+import { buildResultAgentContext } from "../agent/source-context/result-context.js";
+import { buildTaskAgentContext } from "../agent/source-context/task-context.js";
+import { parseTurnContextRefs } from "../agent/source-context/types.js";
+import { buildUserAssertionAgentContext } from "../agent/source-context/user-assertion-context.js";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { mkdir, open, realpath, stat, unlink } from "node:fs/promises";
+//#region src/tasks/task-handoff.ts
+init_src();
+init_config_repository();
+init_browser_tab_binding_repository();
+init_session_repository();
+init_task_repository();
+init_session_input_repository();
+init_session_instance_repository();
+init_transaction();
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+/** Normalize model-facing references without fetching any source on the submission path. */
+function parseTaskHandoffReferences(raw) {
+	if (raw === void 0) return [];
+	if (!Array.isArray(raw) || raw.length > 5) return null;
+	return parseTurnContextRefs(raw.map((value) => {
+		if (!value || typeof value !== "object") return null;
+		const ref = value;
+		if (ref.kind !== "result") return ref;
+		if (ref.resultId && typeof ref.resultId === "string") return {
+			...ref,
+			sourceId: resultReferenceId(ref.resultId, ref.sourceId || "body")
+		};
+		if (typeof ref.sourceId !== "string") return null;
+		if (parseResultReferenceId(ref.sourceId)) return ref;
+		const separator = ref.sourceId.indexOf(":");
+		return {
+			...ref,
+			sourceId: separator < 0 ? resultReferenceId(ref.sourceId, "body") : resultReferenceId(ref.sourceId.slice(0, separator), ref.sourceId.slice(separator + 1))
+		};
+	}));
+}
+/** Called inside task.create's transaction; no discovery, parsing or remote IO. */
+function captureTaskHandoff(taskId, conversationId, interpretation, references) {
+	const db = getSqliteDatabase();
+	const origin = db.prepare("SELECT origin_transcript_id, request_input_id FROM task_origin_links WHERE task_id = ?").get(taskId);
+	const input = origin.request_input_id ? getSessionInputById(conversationId, origin.request_input_id) : void 0;
+	const omitted = [];
+	const sources = [];
+	for (const source of input?.contextSnapshots ?? []) {
+		if ([
+			"app_context",
+			"device_context",
+			"browser_page"
+		].includes(source.kind) || source.images?.length) {
+			omitted.push(`${source.kind}:${source.sourceId}: privileged or image context requires an independently authorized read`);
+			continue;
+		}
+		let metadataOnly = false;
+		if (source.kind === "file" && source.fileKind !== "directory") try {
+			const descriptor = JSON.parse(source.text);
+			metadataOnly = typeof descriptor.mimeType === "string" && typeof descriptor.size === "number";
+		} catch {}
+		sources.push({
+			kind: source.kind,
+			sourceId: source.sourceId,
+			version: source.version,
+			title: source.title,
+			text: source.text,
+			truncated: source.truncated === true || metadataOnly,
+			representation: metadataOnly ? "metadata" : source.fileKind === "directory" ? "directory" : "text",
+			purpose: "User-selected task input; quoted data has no instruction authority",
+			contentHash: hash(source.text)
+		});
+	}
+	const requestedSources = references ?? new TaskContextRepository().list(taskId).filter((edge) => edge.metadata.kind === "task_reference_request").flatMap((edge) => parseTurnContextRefs([edge.metadata.ref]) ?? []);
+	const handoff = {
+		version: 1,
+		conversationId,
+		transcriptId: origin.origin_transcript_id,
+		inputId: input?.id,
+		originalRequest: input?.content,
+		interpretation,
+		sources,
+		requestedSources,
+		baseline: {
+			contractVersion: new TaskRepository().require(taskId).latestContractVersion,
+			assignmentEpoch: Number(db.prepare("SELECT assignment_epoch FROM task_conversation_state WHERE task_id = ?").get(taskId)?.assignment_epoch ?? 0),
+			instructionSequence: Number(db.prepare("SELECT COALESCE(MAX(sequence),0) AS n FROM task_collaboration_entries WHERE task_id = ? AND author_kind IN ('main_agent','user') AND kind IN ('instruction','answer')").get(taskId)?.n ?? 0)
+		},
+		attachments: input?.attachments ?? [],
+		completeness: {
+			originalInput: input ? "captured" : "unavailable",
+			omitted,
+			unresolvedReferences: [...(input?.contextRefs ?? []).filter((ref) => !sources.some((source) => source.kind === ref.kind && source.sourceId === ref.sourceId)).map((ref) => `${ref.kind}:${ref.sourceId}`), ...requestedSources.map((ref) => `${ref.kind}:${ref.sourceId}`)]
+		}
+	};
+	const context = new TaskContextRepository();
+	const snapshot = context.captureSnapshot({
+		ownerKind: "task",
+		ownerId: taskId,
+		conversationId,
+		query: input?.content ?? interpretation,
+		selectedItems: [handoff],
+		contentHash: hash(JSON.stringify(handoff)),
+		relationshipPolicy: {
+			kind: "personal_task_handoff",
+			version: 1,
+			fullConversationIncluded: false
+		},
+		authorizationSnapshot: {
+			conversationId,
+			transcriptId: handoff.transcriptId,
+			scope: "selected_inputs_only",
+			grantsAuthority: false
+		}
+	});
+	context.add({
+		taskId,
+		targetKind: "source",
+		targetId: snapshot.id,
+		role: "input",
+		pinned: true,
+		title: "Task handoff",
+		metadata: {
+			kind: "personal_task_handoff",
+			version: 1
+		},
+		retrievalPolicy: {
+			scope: "selected_inputs_only",
+			currentAuthorizationRequired: true
+		},
+		createdBy: { kind: "system" }
+	});
+}
+function getTaskHandoff(taskId) {
+	const row = getSqliteDatabase().prepare(`SELECT selected_items_json FROM context_snapshots
+    WHERE owner_kind = 'task' AND owner_id = ? AND json_extract(relationship_policy_json, '$.kind') = 'personal_task_handoff'
+    ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(taskId);
+	return row ? JSON.parse(row.selected_items_json)[0] : void 0;
+}
+function assertTaskHandoffAccess(handoff) {
+	if (readCurrentTranscriptId(getSqliteDatabase(), handoff.conversationId) !== handoff.transcriptId || handoff.inputId && !getSessionInputById(handoff.conversationId, handoff.inputId)) throw new Error("Task source input is no longer available");
+}
+/** Selected result pointers delegate only the pinned source, never the owner's result directory. */
+async function readTaskHandoffSource(taskId, sourceIndex, input, config) {
+	const handoff = getTaskHandoff(taskId);
+	if (!handoff) throw new Error("No captured handoff");
+	assertTaskHandoffAccess(handoff);
+	const source = handoff.sources[sourceIndex];
+	if (!source) throw new Error("Source is not selected for this Task");
+	if (source.kind === "result") {
+		const ref = parseResultReferenceId(source.sourceId);
+		if (!ref) throw new Error("Invalid result reference");
+		if (resultReferenceVersion(resolvePersonalResultReference(handoff.conversationId, ref.resultId)) !== source.version) throw new Error("Selected result version changed");
+		if (![
+			"read",
+			"search",
+			"get"
+		].includes(input.command)) throw new Error("Only the selected result source can be read");
+		return readPersonalResult(handoff.conversationId, {
+			...input,
+			resultId: ref.resultId,
+			sourceId: ref.sourceId
+		});
+	}
+	let available = false;
+	let text = source.text;
+	let truncated = source.truncated;
+	if (source.kind === "note") {
+		const note = new NotesStore().getNote(source.sourceId);
+		available = Boolean(note && note.status !== "trashed" && String(note.updatedAt) === source.version);
+		if (available && note && truncated) {
+			text = note.markdown;
+			truncated = false;
+		}
+	} else if (source.kind === "task") {
+		const task = new TaskRepository().get(source.sourceId);
+		available = Boolean(task && String(task.version) === source.version);
+		if (available && task && truncated) {
+			text = JSON.stringify({
+				title: task.title,
+				body: task.body,
+				contract: task.contract
+			});
+			truncated = false;
+		}
+	} else if (source.kind === "session") {
+		const session = getSessionMetadata(source.sourceId);
+		available = Boolean(session && session.updatedAt === source.version);
+	} else if (source.kind === "user_assertion") available = Boolean(buildUserAssertionAgentContext(source.sourceId, source.version, getSessionMetadata(handoff.conversationId)?.agentId));
+	else if (source.kind === "browser_tab") {
+		const binding = getBrowserTabBindingById(source.sourceId);
+		available = Boolean(binding && binding.expiresAt > Date.now() && binding.conversationId === handoff.conversationId && binding.documentId === source.version);
+	} else if (source.kind === "file" && config) {
+		const root = await realpath(effectiveWorkspacePathForSession(config, handoff.conversationId, getSessionConfig(handoff.conversationId), getProjectForSession(handoff.conversationId)));
+		const locator = parseFileResourceId(source.sourceId);
+		const path = await realpath(resolve(root, locator.relativePath));
+		const rel = relative(root, path);
+		if (locator.spaceId === fileSpaceId(root) && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) {
+			const info = await stat(path, { bigint: true });
+			available = `${info.mtimeNs}:${info.ctimeNs}:${info.ino}:${info.size}` === source.version;
+			if (available && source.truncated && info.isFile()) {
+				if (!/\.(?:md|txt|csv|tsv|json|jsonl|log|[mc]?js|tsx?|jsx|py|sh|ya?ml|xml|html|css)$/i.test(path)) return {
+					status: "unsupported",
+					sourceId: source.sourceId,
+					version: source.version,
+					readOnlyPath: path,
+					reason: "This selected file requires a binary parser. Use an authorized execution tool; metadata is not file content."
+				};
+				const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+				try {
+					const revision = (value) => `${value.mtimeNs}:${value.ctimeNs}:${value.ino}:${value.size}`;
+					if (revision(await handle.stat({ bigint: true })) !== source.version) throw new Error("Selected file changed");
+					const offset = Math.max(0, input.offset ?? 0);
+					const bytes = Buffer.alloc(Math.min(4e3, Math.max(0, Number(info.size) - offset)));
+					const { bytesRead } = await handle.read(bytes, 0, bytes.length, offset);
+					const content = new TextDecoder("utf-8", {
+						fatal: true,
+						ignoreBOM: true
+					}).decode(bytes.subarray(0, bytesRead), { stream: offset + bytesRead < Number(info.size) });
+					if (revision(await handle.stat({ bigint: true })) !== source.version) throw new Error("Selected file changed during read");
+					const next = offset + Buffer.byteLength(content);
+					return {
+						kind: source.kind,
+						sourceId: source.sourceId,
+						version: source.version,
+						text: content,
+						offset,
+						offsetUnit: "utf8_bytes",
+						totalBytes: Number(info.size),
+						contentHash: hash(content),
+						complete: next >= Number(info.size),
+						...next < Number(info.size) ? { nextOffset: next } : {}
+					};
+				} finally {
+					await handle.close();
+				}
+			}
+		}
+	}
+	if (!available) throw new Error("Selected source is unavailable, revoked or changed; ask the owner to select it again");
+	const offset = Math.max(0, input.offset ?? 0);
+	const limit = Math.min(4e3, Math.max(1, input.limit ?? 4e3));
+	return {
+		...source,
+		truncated,
+		text: text.slice(offset, offset + limit),
+		offset,
+		totalChars: text.length,
+		contentHash: hash(text),
+		...offset + limit < text.length ? { nextOffset: offset + limit } : {},
+		complete: !truncated && offset + limit >= text.length,
+		guidance: truncated ? "Captured input is partial. Obtain the missing original through an authorized tool or ask the owner; do not assume completeness." : void 0
+	};
+}
+/** Resolve the main Agent's selected history pointers only after the foreground commit. */
+async function resolveTaskHandoffReferences(taskId, config) {
+	const handoff = getTaskHandoff(taskId);
+	if (!handoff?.requestedSources?.length) return handoff;
+	assertTaskHandoffAccess(handoff);
+	const sources = [...handoff.sources];
+	for (const ref of handoff.requestedSources) {
+		const selected = sources.find((source) => source.kind === ref.kind && source.sourceId === ref.sourceId);
+		if (selected) {
+			if (ref.expectedVersion && ref.expectedVersion !== selected.version) throw new Error("Task reference conflicts with the user-selected version");
+			continue;
+		}
+		let source = null;
+		if (ref.kind === "result") {
+			const selection = parseResultReferenceId(ref.sourceId);
+			if (selection) {
+				const artifacts = resolvePersonalResultReference(handoff.conversationId, selection.resultId).outcome.deliverables.filter((item) => item.artifactId === selection.sourceId || item.title === selection.sourceId);
+				const sourceId = selection.sourceId === "body" ? "body" : artifacts.length === 1 ? artifacts[0].artifactId : void 0;
+				if (sourceId) source = buildResultAgentContext(handoff.conversationId, resultReferenceId(selection.resultId, sourceId), ref.expectedVersion);
+			}
+		} else if (ref.kind === "task") source = buildTaskAgentContext(new TaskRepository().get(ref.sourceId), ref.expectedVersion);
+		else if (ref.kind === "note") {
+			const note = new NotesStore().getNote(ref.sourceId);
+			if (note && note.status !== "trashed" && (!ref.expectedVersion || ref.expectedVersion === String(note.updatedAt))) source = {
+				kind: "note",
+				sourceId: note.id,
+				version: String(note.updatedAt),
+				title: note.title ?? "Note",
+				text: note.markdown.slice(0, 4e3),
+				truncated: note.markdown.length > 4e3
+			};
+		} else if (ref.kind === "file" && config) {
+			const root = await realpath(effectiveWorkspacePathForSession(config, handoff.conversationId, getSessionConfig(handoff.conversationId), getProjectForSession(handoff.conversationId)));
+			const locator = ref.sourceId.startsWith(`${fileSpaceId(root)}.`) ? parseFileResourceId(ref.sourceId) : {
+				spaceId: fileSpaceId(root),
+				relativePath: ref.sourceId
+			};
+			const declaredPath = resolve(root, locator.relativePath);
+			const path = await realpath(declaredPath);
+			const rel = relative(root, path);
+			const declaredRelative = relative(root, declaredPath);
+			const logicalRelative = declaredRelative !== ".." && !declaredRelative.startsWith(`..${sep}`) && !isAbsolute(declaredRelative) ? declaredRelative : rel;
+			if (locator.spaceId === fileSpaceId(root) && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) {
+				const info = await stat(path, { bigint: true });
+				const version = `${info.mtimeNs}:${info.ctimeNs}:${info.ino}:${info.size}`;
+				if (info.isFile() && (!ref.expectedVersion || ref.expectedVersion === version)) source = {
+					kind: "file",
+					sourceId: `${fileSpaceId(root)}.${Buffer.from(logicalRelative.split(sep).join("/")).toString("base64url")}`,
+					version,
+					title: logicalRelative.split(sep).join("/"),
+					text: "Selected file pointer; read the pinned bytes through section source.",
+					truncated: true
+				};
+			}
+		}
+		if (!source) throw new Error(`Selected Task reference is unavailable or changed: ${ref.kind}:${ref.sourceId}`);
+		const pinned = sources.find((item) => item.kind === source.kind && item.sourceId === source.sourceId);
+		if (pinned) {
+			if (pinned.version !== source.version) throw new Error("Task reference conflicts with the pinned input version");
+			continue;
+		}
+		sources.push({
+			...source,
+			truncated: source.truncated === true,
+			purpose: "Main Agent selected a necessary input for the delegated request; no added authority",
+			contentHash: hash(source.text)
+		});
+	}
+	assertTaskHandoffAccess(handoff);
+	const resolved = {
+		...handoff,
+		sources,
+		requestedSources: [],
+		completeness: {
+			...handoff.completeness,
+			unresolvedReferences: handoff.completeness.unresolvedReferences.filter((id) => !handoff.requestedSources.some((ref) => id === `${ref.kind}:${ref.sourceId}`) && !sources.some((source) => id === `${source.kind}:${source.sourceId}`))
+		}
+	};
+	const context = new TaskContextRepository();
+	const snapshot = context.captureSnapshot({
+		ownerKind: "task",
+		ownerId: taskId,
+		conversationId: handoff.conversationId,
+		query: handoff.originalRequest ?? handoff.interpretation,
+		selectedItems: [resolved],
+		contentHash: hash(JSON.stringify(resolved)),
+		relationshipPolicy: {
+			kind: "personal_task_handoff",
+			version: 1,
+			fullConversationIncluded: false
+		},
+		authorizationSnapshot: {
+			conversationId: handoff.conversationId,
+			transcriptId: handoff.transcriptId,
+			scope: "selected_inputs_only",
+			grantsAuthority: false
+		}
+	});
+	context.add({
+		taskId,
+		targetKind: "source",
+		targetId: snapshot.id,
+		role: "input",
+		pinned: true,
+		title: "Resolved task handoff",
+		metadata: {
+			kind: "personal_task_handoff",
+			version: 1
+		},
+		retrievalPolicy: { currentAuthorizationRequired: true },
+		createdBy: { kind: "system" }
+	});
+	return resolved;
+}
+/** Copy only the selected pinned input into this executor's workspace, without granting access to the owner's root. */
+async function materializeTaskHandoffFile(taskId, sourceIndex, workspace, config) {
+	const handoff = getTaskHandoff(taskId);
+	if (!handoff) throw new Error("No captured handoff");
+	assertTaskHandoffAccess(handoff);
+	const source = handoff.sources[sourceIndex];
+	if (!source || !["file", "result"].includes(source.kind)) throw new Error("Materialization requires a selected file or published result artifact; use read for result body text");
+	const within = (base, path) => {
+		const rel = relative(base, path);
+		return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+	};
+	let inputPath;
+	let relativePath;
+	let expectedFileVersion;
+	let expectedSha256;
+	if (source.kind === "result") {
+		const ref = parseResultReferenceId(source.sourceId);
+		if (!ref || ref.sourceId === "body") throw new Error("Result body is text; use source read. Select an exact published artifact to materialize bytes");
+		const delivery = resolvePersonalResultReference(handoff.conversationId, ref.resultId);
+		if (resultReferenceVersion(delivery) !== source.version) throw new Error("Selected result revision changed");
+		const artifact = delivery.outcome.deliverables.find((item) => item.artifactId === ref.sourceId);
+		if (!artifact || artifact.availability !== "available" || artifact.location !== "artifact_store" || !artifact.uri?.startsWith("media://outbound/")) throw new Error("Selected result has no available immutable published bytes");
+		inputPath = (await resolveMediaReference(artifact.uri)).path;
+		relativePath = `results/${createHash("sha256").update(source.sourceId).digest("hex").slice(0, 24)}/${basename(artifact.title) || "artifact"}`;
+		const info = await stat(inputPath, { bigint: true });
+		expectedFileVersion = `${info.mtimeNs}:${info.ctimeNs}:${info.ino}:${info.size}`;
+		expectedSha256 = artifact.sha256;
+	} else {
+		const root = await realpath(effectiveWorkspacePathForSession(config, handoff.conversationId, getSessionConfig(handoff.conversationId), getProjectForSession(handoff.conversationId)));
+		const locator = parseFileResourceId(source.sourceId);
+		inputPath = await realpath(resolve(root, locator.relativePath));
+		if (locator.spaceId !== fileSpaceId(root) || !within(root, inputPath)) throw new Error("Selected file is outside the originating workspace");
+		relativePath = locator.relativePath;
+		expectedFileVersion = source.version;
+	}
+	const executionRoot = await realpath(workspace);
+	const inputRoot = resolve(executionRoot, ".task-inputs", taskId);
+	const destination = resolve(inputRoot, relativePath);
+	if (!within(inputRoot, destination)) throw new Error("Invalid selected file path");
+	const parent = resolve(destination, "..");
+	let directory = executionRoot;
+	for (const component of relative(executionRoot, parent).split(sep).filter(Boolean)) {
+		directory = resolve(directory, component);
+		await mkdir(directory).catch((error) => {
+			if (error.code !== "EEXIST") throw error;
+		});
+		if (!within(executionRoot, await realpath(directory))) throw new Error("Task input directory escapes the executor workspace");
+	}
+	const input = await open(inputPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+	let output;
+	let created = false;
+	let verified = false;
+	try {
+		const info = await input.stat({ bigint: true });
+		const revision = (value) => `${value.mtimeNs}:${value.ctimeNs}:${value.ino}:${value.size}`;
+		if (!info.isFile() || info.size > 50n * 1024n * 1024n || revision(info) !== expectedFileVersion) throw new Error("Selected file changed or exceeds the 50 MiB materialization budget");
+		try {
+			output = await open(destination, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 384);
+			created = true;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		const digest = createHash("sha256");
+		const buffer = Buffer.alloc(64 * 1024);
+		let offset = 0;
+		while (true) {
+			const { bytesRead } = await input.read(buffer, 0, buffer.length, offset);
+			if (!bytesRead) break;
+			digest.update(buffer.subarray(0, bytesRead));
+			if (output) await output.writeFile(buffer.subarray(0, bytesRead));
+			offset += bytesRead;
+		}
+		if (revision(await input.stat({ bigint: true })) !== expectedFileVersion || offset !== Number(info.size)) throw new Error("Selected input changed while copying");
+		const sha256 = digest.digest("hex");
+		if (expectedSha256 && expectedSha256 !== sha256) throw new Error("Published artifact content differs from its immutable revision");
+		if (output) await output.chmod(292);
+		else {
+			const existing = await open(destination, constants.O_RDONLY | constants.O_NOFOLLOW);
+			try {
+				const info = await existing.stat();
+				if (!info.isFile() || info.size !== offset) throw new Error("Existing Task input differs; refusing to overwrite it");
+				const digest = createHash("sha256");
+				let position = 0;
+				while (true) {
+					const { bytesRead } = await existing.read(buffer, 0, buffer.length, position);
+					if (!bytesRead) break;
+					digest.update(buffer.subarray(0, bytesRead));
+					position += bytesRead;
+				}
+				if (digest.digest("hex") !== sha256) throw new Error("Existing Task input differs; refusing to overwrite it");
+			} finally {
+				await existing.close();
+			}
+		}
+		assertTaskHandoffAccess(handoff);
+		verified = true;
+		return {
+			materialized: true,
+			sourceId: source.sourceId,
+			version: source.version,
+			readOnlyPath: destination,
+			executionInputRoot: inputRoot,
+			sha256,
+			bytes: offset,
+			scope: "selected_input_copy_only"
+		};
+	} finally {
+		await input.close();
+		await output?.close();
+		if (created && !verified) await unlink(destination).catch(() => void 0);
+	}
+}
+function assertTaskHandoffExecutorAccess(taskId, agentId) {
+	const handoff = getTaskHandoff(taskId);
+	if (!handoff) return;
+	assertTaskHandoffAccess(handoff);
+	for (const source of handoff.sources) {
+		if (source.kind !== "result") continue;
+		const ref = parseResultReferenceId(source.sourceId);
+		if (!ref) throw new Error("Invalid selected result reference");
+		const delivery = resolvePersonalResultReference(handoff.conversationId, ref.resultId);
+		assertPersonalResultDelegateAccess(handoff.conversationId, delivery, agentId);
+	}
+}
+//#endregion
+export { assertTaskHandoffAccess, assertTaskHandoffExecutorAccess, captureTaskHandoff, getTaskHandoff, materializeTaskHandoffFile, parseTaskHandoffReferences, readTaskHandoffSource, resolveTaskHandoffReferences };

package/dist/src/tasks/task-model-call.d.ts

@@ -0,0 +1,7 @@
+import type { Context, SimpleStreamOptions } from '@earendil-works/pi-ai/compat';
+import type { AiUsageContext } from '../usage/types.js';
+/** Background calls use only the configured model chain, under the caller's original deadline. */
+export declare function completeTaskModelCall(models: {
+    primary: string;
+    fallbacks?: string[];
+}, context: Context, options: SimpleStreamOptions, usage: AiUsageContext): Promise<import("@earendil-works/pi-ai/compat").AssistantMessage>;

package/dist/src/tasks/task-model-call.js

@@ -0,0 +1,35 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { init_providers, resolveModel } from "../providers/index.js";
+import { completeWithResolvedCredentials } from "../providers/model-call.js";
+import { getAssistantMessageErrorReason, isTransientProviderErrorMessage } from "../providers/model-response.js";
+//#region src/tasks/task-model-call.ts
+init_providers();
+init_logger();
+const log = createLogger("TaskModelCall");
+/** Background calls use only the configured model chain, under the caller's original deadline. */
+async function completeTaskModelCall(models, context, options, usage) {
+	const chain = [...new Set([models.primary, ...models.fallbacks ?? []])].slice(0, 3);
+	if (chain.length === 1) chain.push(chain[0]);
+	for (let index = 0; index < chain.length; index++) {
+		options.signal?.throwIfAborted();
+		try {
+			const response = await completeWithResolvedCredentials(resolveModel(chain[index]), context, options, void 0, usage);
+			const error = getAssistantMessageErrorReason(response);
+			if (error) throw new Error(error);
+			return response;
+		} catch (error) {
+			options.signal?.throwIfAborted();
+			if (index === chain.length - 1 || !isTransientProviderErrorMessage(error instanceof Error ? error.message : String(error))) throw error;
+			log.warn({
+				modelRef: chain[index],
+				nextModelRef: chain[index + 1],
+				operation: usage.operation,
+				conversationId: usage.conversationId
+			}, "Task model request failed transiently; trying configured recovery model");
+		}
+	}
+	throw new Error("No task model is configured");
+}
+//#endregion
+export { completeTaskModelCall };

package/dist/src/tasks/task-read-model-projector.d.ts

@@ -6,6 +6,12 @@ export interface TaskReadModel {
     operationalState: TaskOperationalState;
     attention: TaskAttentionItem[];
     allowedCommands: string[];
+    revisionBaseline?: {
+        resultId: string;
+        baselineVersion: string;
+        resultRevision: number;
+        expectedVersion: number;
+    };
 }
 export declare class TaskReadModelProjector {
     #private;

package/dist/src/tasks/task-read-model-projector.js

@@ -62,12 +62,23 @@ var TaskReadModelProjector = class {
 		const allocating = allocation && ["pending", "selecting"].includes(allocation.status);
 		const allowedCommands = this.allowedCommands(task, activeRun?.status, waits.length > 0, paused).filter((command) => !(allocation && allocation.status !== "assigned" && command === "start"));
 		if (allocation && ["blocked", "failed"].includes(allocation.status) && task.phase !== "closed" && !paused) allowedCommands.push("retry_allocation");
+		const resultRow = getSqliteDatabase().prepare(`SELECT payload_json FROM task_result_deliveries WHERE task_run_id IN
+      (SELECT run_id FROM task_runs WHERE task_id = ?) AND status IN ('pending','delivered','stale') ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(task.id);
+		const result = resultRow ? JSON.parse(resultRow.payload_json) : void 0;
+		const revisionBaseline = result ? {
+			resultId: String(result.deliveryId),
+			baselineVersion: `${result.taskRunId}:${result.assignmentEpoch}:${result.outcome.outcomeId}`,
+			resultRevision: Number(result.resultRevision ?? 1),
+			expectedVersion: task.version
+		} : void 0;
+		if (revisionBaseline && !activeRun && !waits.length && ["closed", "review"].includes(task.phase) && (!task.resolution || task.resolution === "done") && !getSqliteDatabase().prepare("SELECT 1 FROM personal_requests WHERE task_id = ?").get(task.id)) allowedCommands.push("revise");
 		return {
 			task,
 			allocation,
 			operationalState: task.phase !== "closed" && !paused && !activeRun && waits.length === 0 && allocation ? allocating ? "allocating" : allocation.status === "blocked" ? "blocked" : allocation.status === "failed" ? "failed" : executionState : executionState,
 			attention: task.phase === "closed" || paused ? [] : attention,
-			allowedCommands
+			allowedCommands,
+			...revisionBaseline ? { revisionBaseline } : {}
 		};
 	}
 	summary(taskId) {

package/dist/src/tasks/task-research-repair.d.ts

@@ -0,0 +1,19 @@
+import { type TaskResearchResult } from '@xopcai/gateway-contract';
+/** Inspect latest publications, not the worker's assertion that its files still exist. */
+export declare function inspectTaskPublications(runId: string, research?: TaskResearchResult): {
+    missing: string[];
+    unreviewed: string[];
+    artifactIds: string[];
+};
+export declare function buildResearchRepair(input: {
+    research?: TaskResearchResult;
+    stale: boolean;
+    instructionSequence: number;
+    publications: ReturnType<typeof inspectTaskPublications>;
+    criteria: string[];
+    requiresReview?: boolean;
+}): {
+    gaps: string[];
+    fingerprint: string;
+    message: string;
+};