@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/exocom/collaboration.ts

@@ -0,0 +1,148 @@
+/** Voluntary peer work. Pure domain rules; claims and persistence stay in the ledger transaction. */
+import { writeSetPathError } from "../core/ownership.ts";
+import { isSemanticFrame, type ExocomSemanticFrame, type ExocomCollaborationFrame, type ExocomOffer, type ExocomProgress, type ExocomPublish, type ExocomTaskCreate, type ExocomTaskFinish, type ExocomTaskTake } from "./envelope.ts";
+
+export interface CollaborationTask {
+	created: ExocomTaskCreate;
+	taken?: ExocomTaskTake;
+	progress?: ExocomProgress;
+	finished?: ExocomTaskFinish;
+	/** Loss of the owning registry lease is visible and never permits automatic pickup. */
+	stale?: true;
+	/** Receiver clock at the first lease-loss reconciliation, or release timestamp. */
+	staleAt?: number;
+}
+export interface CollaborationState { tasks: CollaborationTask[]; offers: ExocomOffer[]; evidence: ExocomPublish[]; }
+export const COLLABORATION_LIMITS = { tasks: 64, offers: 64, evidence: 64, maxBytes: 131_072 } as const;
+export function emptyCollaboration(): CollaborationState { return { tasks: [], offers: [], evidence: [] }; }
+export function collaborationStatus(task: CollaborationTask): "open" | "taken" | "done" | "abandoned" | "stale" {
+	return task.finished?.outcome ?? (task.stale ? "stale" : task.taken ? "taken" : "open");
+}
+export function offerStatus(offer: ExocomOffer, now: number): "open" | "expired" {
+	return Date.parse(offer.expires_at) <= now ? "expired" : "open";
+}
+/** Time expiry is authoritative even after the exact task generation becomes unavailable. */
+export function collaborationOfferStatus(offer: ExocomOffer, tasks: readonly CollaborationTask[], now: number): "open" | "expired" | "stale" {
+	if (offerStatus(offer, now) === "expired") return "expired";
+	const task = tasks.find((candidate) => candidate.created.work_key === offer.work_key && candidate.created.msg_id === offer.task_id);
+	return task && collaborationStatus(task) === "open" ? "open" : "stale";
+}
+function bounded(state: CollaborationState, reserveLifecycle = true): boolean {
+	// Local ledger lifecycle events are unsigned. Reserve their largest identity metadata and a
+	// minimal terminal note, as well as lease loss, before admitting optional prose. A full note
+	// can hit quota; taking work, finishing with a short note and release must remain available.
+	const reserved = { ...state, tasks: state.tasks.map((task) => {
+		if (task.finished) return task;
+		const future = { work_key: task.created.work_key, task_id: task.created.msg_id, from_session: "x".repeat(128),
+			from_name: "界".repeat(256), msg_id: "x".repeat(128), ts: "9999-12-31T23:59:59.999Z" };
+		return { ...task, stale: true, staleAt: -Number.MAX_VALUE,
+			taken: task.taken ?? { ...future, kind: "task_take" }, finished: { ...future, kind: "task_finish", outcome: "abandoned", note: "x" } };
+	}) };
+	return state.tasks.length <= COLLABORATION_LIMITS.tasks && state.offers.length <= COLLABORATION_LIMITS.offers
+		&& state.evidence.length <= COLLABORATION_LIMITS.evidence && Buffer.byteLength(JSON.stringify(reserveLifecycle ? reserved : state), "utf8") <= COLLABORATION_LIMITS.maxBytes;
+}
+/** Retained facts outlive the rolling transport-id window; they must never acquire duplicate identities. */
+export function retainedCollaborationEvent(state: CollaborationState, msgId: string): ExocomSemanticFrame | undefined {
+	for (const task of state.tasks) {
+		for (const event of [task.created, task.taken, task.progress, task.finished]) if (event?.msg_id === msgId) return event;
+	}
+	return state.offers.find((event) => event.msg_id === msgId) ?? state.evidence.find((event) => event.msg_id === msgId);
+}
+type Transition = { ok: true; state: CollaborationState } | { ok: false; error: string };
+function transition(state: CollaborationState, event: ExocomCollaborationFrame | ExocomProgress, reserveLifecycle: boolean): Transition {
+	if (event.kind === "progress" && event.task_id === undefined) return { ok: true, state };
+	const task = state.tasks.find((value) => value.created.work_key === event.work_key);
+	let next = state;
+	if (event.kind === "task_create") {
+		if (task) return { ok: false, error: "task work_key already exists" };
+		for (const path of event.write_set) {
+			const error = writeSetPathError(path);
+			if (error) return { ok: false, error: `task write_set path is ${error}` };
+		}
+		next = { ...state, tasks: [...state.tasks, { created: event }] };
+	} else {
+		if (!task) return { ok: false, error: "unknown collaboration task" };
+		if (event.task_id !== task.created.msg_id) return { ok: false, error: "task_id does not match this work key's retained generation" };
+		if (event.kind === "publish") next = { ...state, evidence: [...state.evidence, event] };
+		else if (event.kind === "offer") {
+			if (state.offers.some((offer) => offer.offer_id === event.offer_id)) return { ok: false, error: "offer_id already exists" };
+			if (event.to_session === event.from_session) return { ok: false, error: "offer cannot target self" };
+			if (collaborationStatus(task) !== "open") return { ok: false, error: "offers require an open task" };
+			next = { ...state, offers: [...state.offers, event] };
+		} else {
+			const status = collaborationStatus(task);
+			if (event.kind === "task_take") {
+				if (status !== "open") return { ok: false, error: `task is ${status}; pickup refused` };
+				next = { ...state, tasks: state.tasks.map((value) => value === task ? { ...task, taken: event } : value) };
+			} else {
+				if (status !== "taken" || task.taken?.from_session !== event.from_session) return { ok: false, error: "only the active task taker may report progress or finish" };
+				if (event.kind === "progress" && Date.parse(event.ts) < Date.parse(task.progress?.ts ?? task.taken.ts)) return { ok: false, error: "task progress predates its latest observation" };
+				const updated = event.kind === "progress" ? { ...task, progress: event } : { ...task, finished: event };
+				next = { ...state, tasks: state.tasks.map((value) => value === task ? updated : value) };
+			}
+		}
+	}
+	return bounded(next, reserveLifecycle) ? { ok: true, state: next } : { ok: false, error: "collaboration retention budget reached; shorten optional report text" };
+}
+export function applyCollaborationEvent(state: CollaborationState, event: ExocomCollaborationFrame | ExocomProgress): Transition {
+	return transition(state, event, true);
+}
+
+export function staleCollaboration(state: CollaborationState, isLive: (session: string) => boolean, now: number): CollaborationState {
+	return { ...state, tasks: state.tasks.map((task) => task.finished || task.stale || isLive(task.taken?.from_session ?? task.created.from_session)
+		? task : { ...task, stale: true, staleAt: now }) };
+}
+export function releaseCollaboration(state: CollaborationState, session: string, workKey: string, now: number): CollaborationState {
+	return { ...state, tasks: state.tasks.map((task) => task.created.work_key === workKey && !task.finished && !task.stale
+		&& (task.taken?.from_session ?? task.created.from_session) === session ? { ...task, stale: true, staleAt: now } : task) };
+}
+export function pruneCollaboration(state: CollaborationState, now: number, ttlMs: number, isLive: (session: string) => boolean): CollaborationState {
+	const reconciled = staleCollaboration(state, isLive, now);
+	const tasks = reconciled.tasks.filter((task) => {
+		const terminalAt = task.finished ? Date.parse(task.finished.ts) : task.staleAt;
+		return terminalAt === undefined || now - terminalAt <= ttlMs;
+	});
+	const retained = new Set(tasks.map((task) => task.created.work_key));
+	return {
+		tasks,
+		offers: state.offers.filter((offer) => retained.has(offer.work_key) && now - Date.parse(offer.expires_at) <= ttlMs),
+		evidence: state.evidence.filter((item) => retained.has(item.work_key) && now - Date.parse(item.ts) <= ttlMs),
+	};
+}
+
+/** Reconstruct snapshots through the same rules. No malformed ownership record is silently skipped. */
+export function parseCollaboration(raw: unknown): CollaborationState | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const value = raw as CollaborationState;
+	if (!Array.isArray(value.tasks) || !Array.isArray(value.offers) || !Array.isArray(value.evidence) || !bounded(value)) return undefined;
+	let state = emptyCollaboration();
+	const seen = new Set<string>();
+	function replay(event: unknown, kind: string): boolean {
+		if (!isSemanticFrame(event) || event.kind !== kind || seen.has(event.msg_id)) return false;
+		if (!(event.kind === "task_create" || event.kind === "task_take" || event.kind === "task_finish" || event.kind === "progress" || event.kind === "offer" || event.kind === "publish")) return false;
+		// Definitions must precede historical offers. Replay checks physical bounds; reserve
+		// future lifecycle only on the final state, once completed tasks are terminal again.
+		const applied = transition(state, event, false);
+		if (!applied.ok) return false;
+		seen.add(event.msg_id);
+		state = applied.state;
+		return true;
+	}
+	// All definitions precede offers/evidence; a finished task's historical offer is valid.
+	for (const task of value.tasks) {
+		if (!task || typeof task !== "object" || !replay(task.created, "task_create")) return undefined;
+	}
+	for (const offer of value.offers) if (!replay(offer, "offer")) return undefined;
+	for (const task of value.tasks) {
+		for (const [event, kind] of [[task.taken, "task_take"], [task.progress, "progress"], [task.finished, "task_finish"]] as const) {
+			if (event !== undefined && (event.work_key !== task.created.work_key || !replay(event, kind))) return undefined;
+		}
+		if (task.stale !== undefined && task.stale !== true) return undefined;
+		if (task.stale) {
+			if (task.finished || typeof task.staleAt !== "number" || !Number.isFinite(task.staleAt)) return undefined;
+			state = releaseCollaboration(state, task.taken?.from_session ?? task.created.from_session, task.created.work_key, task.staleAt);
+		} else if (task.staleAt !== undefined) return undefined;
+	}
+	for (const evidence of value.evidence) if (!replay(evidence, "publish")) return undefined;
+	return bounded(state) ? state : undefined;
+}

package/src/exocom/envelope.ts

@@ -31,13 +31,20 @@ export interface ExocomAnswer {
 }
 export interface ExocomProgress {
 	kind: "progress"; work_key: string; from_session: string; from_name: string;
-	note: string; msg_id: string; ts: string; signature?: string;
+	note: string; msg_id: string; ts: string; signature?: string; task_id?: string;
 }
 export interface ExocomRelease {
 	kind: "release"; work_key: string; from_session: string; from_name: string;
 	msg_id: string; ts: string; signature?: string;
 }
-export type ExocomSemanticFrame = ExocomClaim | ExocomAsk | ExocomAnswer | ExocomProgress | ExocomRelease;
+interface CollaborationFrame { work_key: string; from_session: string; from_name: string; msg_id: string; ts: string; signature?: string; }
+export interface ExocomTaskCreate extends CollaborationFrame { kind: "task_create"; description: string; write_set: string[]; }
+export interface ExocomTaskTake extends CollaborationFrame { kind: "task_take"; task_id: string; }
+export interface ExocomTaskFinish extends CollaborationFrame { kind: "task_finish"; task_id: string; outcome: "done" | "abandoned"; note: string; }
+export interface ExocomOffer extends CollaborationFrame { kind: "offer"; task_id: string; offer_id: string; to_session?: string; expires_at: string; }
+export interface ExocomPublish extends CollaborationFrame { kind: "publish"; task_id: string; title: string; excerpt: string; }
+export type ExocomCollaborationFrame = ExocomTaskCreate | ExocomTaskTake | ExocomTaskFinish | ExocomOffer | ExocomPublish;
+export type ExocomSemanticFrame = ExocomClaim | ExocomAsk | ExocomAnswer | ExocomProgress | ExocomRelease | ExocomCollaborationFrame;
 export type ExocomFrame = ExocomMessage | ExocomBye | ExocomAck | ExocomNack | ExocomSemanticFrame;
 
 const str = (v: unknown): v is string => typeof v === "string";
@@ -73,10 +80,27 @@ export function isSemanticFrame(v: unknown): v is ExocomSemanticFrame {
 		case "progress":
 			return token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
 				&& bounded(o.note, 4_096) && token(o.msg_id) && timestamp(o.ts)
-				&& optionalBounded(o.signature, 512);
+				&& optionalBounded(o.signature, 512) && (o.task_id === undefined || token(o.task_id));
 		case "release":
 			return token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
 				&& token(o.msg_id) && timestamp(o.ts) && optionalBounded(o.signature, 512);
+		case "task_create":
+		case "task_take":
+		case "task_finish":
+		case "offer":
+		case "publish": {
+			if (!token(o.work_key) || !token(o.from_session) || !metadata(o.from_name, 256)
+				|| !token(o.msg_id) || !timestamp(o.ts) || !optionalBounded(o.signature, 512)) return false;
+			if (o.kind === "task_create") return bounded(o.description, 2_048) && Array.isArray(o.write_set)
+				&& (o.write_set.length === 0 || writeSet(o.write_set));
+			if (!token(o.task_id)) return false;
+			if (o.kind === "task_finish") return (o.outcome === "done" || o.outcome === "abandoned") && bounded(o.note, 4_096);
+			if (o.kind === "offer") return token(o.offer_id) && (o.to_session === undefined || token(o.to_session))
+				&& timestamp(o.expires_at) && Date.parse(o.expires_at) > Date.parse(o.ts)
+				&& Date.parse(o.expires_at) - Date.parse(o.ts) <= 86_400_000;
+			if (o.kind === "publish") return bounded(o.title, 160) && bounded(o.excerpt, 4_096) && Buffer.byteLength(o.excerpt, "utf8") <= 8_192;
+			return true;
+		}
 		default:
 			return false;
 	}
@@ -102,6 +126,11 @@ export function isExocomFrame(v: unknown): v is ExocomFrame {
 		case "answer":
 		case "progress":
 		case "release":
+		case "task_create":
+		case "task_take":
+		case "task_finish":
+		case "offer":
+		case "publish":
 			return isSemanticFrame(v);
 		default: return false;
 	}
@@ -127,9 +156,19 @@ export function frameSigningPayload(frame: ExocomFrame): string {
 				frame.ok, frame.evidence, frame.ts]);
 		case "progress":
 			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name,
-				frame.note, frame.ts]);
+				frame.note, frame.ts, frame.task_id ?? null]);
 		case "release":
 			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name, frame.ts]);
+		case "task_create":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name, frame.description, frame.write_set, frame.ts]);
+		case "task_take":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.task_id, frame.from_session, frame.from_name, frame.ts]);
+		case "task_finish":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.task_id, frame.from_session, frame.from_name, frame.outcome, frame.note, frame.ts]);
+		case "offer":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.offer_id, frame.work_key, frame.task_id, frame.from_session, frame.from_name, frame.to_session ?? null, frame.expires_at, frame.ts]);
+		case "publish":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.task_id, frame.from_session, frame.from_name, frame.title, frame.excerpt, frame.ts]);
 	}
 }
 

package/src/exocom/gate.ts

@@ -1,6 +1,11 @@
 /** Identity metadata does not claim work or settle asks. Persona denials still apply first. */
 const ALLOWED = new Set(["exocom_name", "exocom_answer", "exocom_decline", "exocom_status", "read", "grep", "find", "ls"]);
 
-export function constrainedTurnAllows(toolName: string): boolean {
-	return ALLOWED.has(toolName);
+export function constrainedTurnAllows(toolName: string, input?: unknown): boolean {
+	if (ALLOWED.has(toolName)) return true;
+	if (!input || typeof input !== "object") return false;
+	const action = (input as { action?: unknown }).action;
+	return (toolName === "exocom_task" && (action === "list" || action === "get"))
+		|| (toolName === "exocom_publish" && action === "read")
+		|| (toolName === "exocom_profile" && action === "get");
 }

package/src/exocom/install.ts

@@ -27,6 +27,7 @@ import {
 	sanitizePeerField,
 	sendPersonaFollowUp,
 	shouldReportHeartbeatFailure,
+	toastCause,
 	type ExocomQueuedToast,
 } from "../extension/shared.ts";
 import { SeenMessages, SenderBudget } from "./guards.ts";
@@ -54,6 +55,9 @@ import type { ExocomSemanticFrame } from "./envelope.ts";
 import { prune as pruneExocom, type RegistryEntry } from "./registry.ts";
 import { registerExocomTools } from "../tools/exocom.ts";
 import { registerExocomWorkTools } from "../tools/exocom-work.ts";
+import { registerExocomCollaborationTools } from "../tools/exocom-collaboration.ts";
+import { registerExocomProfileTool } from "../tools/exocom-profile.ts";
+import { collaborationWriteIntent, deliverCollaborationOffer } from "./collaboration-delivery.ts";
 import type { SessionIdentity } from "../extension/identity.ts";
 import { WriteWarnings } from "./write-guard.ts";
 
@@ -237,28 +241,23 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 	}
 
 	function telemetrySessionId(ctx: ExtensionContext): string {
-		return (ctx as ExtensionContext & { sessionManager?: { getSessionId?: () => string } }).sessionManager?.getSessionId?.() ?? `legacy-${process.pid}`;
+		return ctx.sessionManager.getSessionId();
 	}
 
 	function currentTelemetryInstance(ctx: ExtensionContext): InstanceDescriptor {
-		const runtimeCtx = ctx as ExtensionContext & {
-			sessionManager?: { getSessionId?: () => string };
-			isIdle?: () => boolean;
-			getContextUsage?: () => { percent?: number } | undefined;
-		};
 		const personaName = host.controller.activePersona?.name ?? "";
 		const displayName = exocomSelfStatusLabel(host.identity.chosen, host.identity.name, personaName);
 		return {
 			displayName,
 			persona: host.controller.activePersona?.name ?? "",
 			model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "",
-			status: runtimeCtx.isIdle?.() === true ? "idle" : "active",
+			status: ctx.isIdle() ? "idle" : "active",
 			pid: process.pid,
 			// Clamped HERE, not merely in the producer's `sanitizeInstance`: that one runs only for
 			// `instance.started`, so an out-of-range reading would ride `instance.updated` and
 			// `instance.heartbeat` out to consumers, where the contract rejects the WHOLE event over
 			// the one bad field.
-			contextPercent: Math.max(0, Math.min(100, Math.round(runtimeCtx.getContextUsage?.()?.percent ?? 0))),
+			contextPercent: Math.max(0, Math.min(100, Math.round(ctx.getContextUsage()?.percent ?? 0))),
 			exocomEnabled: exocomPlane !== undefined,
 			color: exocomColorFor(displayName),
 		};
@@ -412,7 +411,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 			exocomSeen = new SeenMessages({ ttlMs: EXOCOM.SEEN_TTL_MS });
 			exocomLedgerFile = ledgerPath(agentDir, hash);
 			exocomWaitNotifier = new IdleCoalescingNotifier<string>({
-				isIdle: () => canDeliverPersonaNotification(host.orchestrating, host.processingDeferredOrchestration, host.lastCtx?.isIdle?.() === true),
+				isIdle: () => canDeliverPersonaNotification(host.orchestrating, host.processingDeferredOrchestration, host.lastCtx?.isIdle() === true),
 				deliver: (message) => sendPersonaFollowUp(pi, message, "pi-persona"),
 				render: (items) => items.join("\n\n"),
 				setTimer: (fn, ms) => { const h = setTimeout(fn, ms); h.unref?.(); return h; },
@@ -423,7 +422,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 			// pi.sendMessage (a distinct, labellable custom message) rather than pi.sendUserMessage
 			// (mirrors the bridge's own `sendFollowUp` for inbound cross-process text).
 			exocomNotifier = new IdleCoalescingNotifier<string>({
-				isIdle: () => canDeliverPersonaNotification(host.orchestrating, host.processingDeferredOrchestration, host.lastCtx?.isIdle?.() === true),
+				isIdle: () => canDeliverPersonaNotification(host.orchestrating, host.processingDeferredOrchestration, host.lastCtx?.isIdle() === true),
 				deliver: (message) => sendPersonaFollowUp(pi, message, "exocom_received"),
 				// A burst of independent peers must not turn one idle wake into an unbounded model
 				// payload. Each item is already attributed and peer-fenced by buildInboundDelivery;
@@ -536,7 +535,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 				if (!plane) throw new Error("exocom is not active for this persona");
 				if (!exocomLedgerFile) throw new Error("exocom ledger is not available");
 				let target: DisplayPeer | undefined;
-				if (frame.kind === "ask") {
+				if (frame.kind === "ask" || (frame.kind === "offer" && frame.to_session !== undefined)) {
 					target = plane.listPeers().find((peer) => peer.session_id === frame.to_session);
 					if (!target) throw new Error(`exocom: unknown peer session "${frame.to_session}"`);
 				} else if (frame.kind === "answer") {
@@ -550,7 +549,14 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 					}
 				}
 				const prune = currentLedgerPruneOptions();
-				const applied = commitLedgerEvent(exocomLedgerFile, frame, prune ? { prune } : {});
+				if (collaborationWriteIntent(frame, currentLedgerState())
+					&& (exocomScope?.joined === true || (host.controller.capabilities && !canCallTool(host.controller.capabilities, "exocom_claim")))) {
+					throw new Error("exocom: this session cannot claim write paths in the selected scope");
+				}
+				const applied = commitLedgerEvent(exocomLedgerFile, frame, {
+					...(prune ? { prune } : {}),
+					canClaim: exocomScope?.joined !== true && (!host.controller.capabilities || canCallTool(host.controller.capabilities, "exocom_claim")),
+				});
 				if (!applied.ok) throw new Error(`exocom: ${applied.error}`);
 				if (applied.duplicate === true) return { msg_id: frame.msg_id };
 				// Claims/progress/releases are authoritative in the shared ledger and need no postcard.
@@ -562,7 +568,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 					} catch { /* the durable result is still recoverable from the ledger */ }
 					return { msg_id: frame.msg_id, peerWakeDeferred: true };
 				}
-				if (target && (frame.kind === "ask" || frame.kind === "answer")) {
+				if (target && (frame.kind === "ask" || frame.kind === "answer" || frame.kind === "offer")) {
 					try {
 						await plane.sendSemantic(target.target, frame);
 					} catch {
@@ -657,7 +663,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 						exocomNotifier?.notify(decision.deliver);
 						// Never inject peer text into a live model turn. A compact human-only toast makes
 						// receipt visible while a long tool loop keeps the follow-up idle-gated.
-						if (host.lastCtx?.isIdle?.() !== true) {
+						if (host.lastCtx?.isIdle() !== true) {
 							exocomToastNotifier?.notify({ label, inReplyTo: msg.in_reply_to });
 						}
 					}
@@ -692,7 +698,15 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 						return { accepted: false, reason: error instanceof Error ? error.message : "ledger unavailable" };
 					}
 					const label = exocomPlane?.humanDisplayLabelFor(fromEntry) ?? fromEntry.session_id;
-					if (frame.kind === "ask") {
+					if (fromEntry.workspace_id !== undefined && fromEntry.workspace_id !== scope.scopeWorkspaceId && collaborationWriteIntent(frame, state)) {
+						exocomSeen?.forget(frame.from_session, frame.msg_id);
+						return { accepted: false, reason: "external-workspace peers cannot take write tasks in the selected scope" };
+					}
+					if (frame.kind === "offer") {
+						const delivery = deliverCollaborationOffer(frame, state, sessionId, label, Date.now());
+						if (!delivery.accepted) { exocomSeen?.forget(frame.from_session, frame.msg_id); return delivery; }
+						if (delivery.notice) exocomNotifier?.notify(delivery.notice);
+					} else if (frame.kind === "ask") {
 						if (frame.to_session !== sessionId) {
 							exocomSeen?.forget(frame.from_session, frame.msg_id);
 							return { accepted: false, reason: "ask addressed to another session" };
@@ -740,7 +754,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 					if (shouldReportHeartbeatFailure(exocomHeartbeatFailures)) {
 						try {
 							host.lastCtx?.ui.notify(
-								`exocom: heartbeat failed ${exocomHeartbeatFailures}× in a row (${message}) — peers drop this instance from the pool until it recovers.`,
+								`exocom: heartbeat failed ${exocomHeartbeatFailures}× in a row (${toastCause(message)}) — peers drop this instance from the pool until it recovers.`,
 								"warning",
 							);
 						} catch {
@@ -775,6 +789,19 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 				ledger: () => currentLedgerState(),
 				labelFor: peerLabelFor,
 			});
+			registerExocomCollaborationTools(pi, {
+				getPlane: () => exocomPlane,
+				sessionId: () => sessionId, name: () => host.identity.name, now: () => Date.now(),
+				canClaim: () => exocomScope?.joined !== true,
+				canCallTool: (name) => !host.controller.capabilities || canCallTool(host.controller.capabilities, name),
+				resolveTarget: (target) => {
+					if (!exocomPlane) throw new Error("exocom is not active for this persona");
+					return exocomPlane.resolvePeer(target).session_id;
+				},
+				dispatch: dispatchSemantic, ledger: currentLedgerState, labelFor: peerLabelFor,
+				targetForSession: (id) => exocomPlane?.listPeers().find((peer) => peer.session_id === id)?.target,
+			});
+			registerExocomProfileTool(pi, () => exocomPlane);
 		} catch (err) {
 			// `plane.start()` may have bound its server before a later registry write failed.
 			// Teardown while the reference is still owned; this also cancels notifier/timers.
@@ -783,7 +810,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 			let surfacedInUi = false;
 			if (ctx.hasUI) {
 				try {
-					ctx.ui.notify(`exocom failed to start: ${message}`, "error");
+					ctx.ui.notify(`exocom failed to start: ${toastCause(message)}`, "error");
 					surfacedInUi = true;
 				} catch {
 					/* the session may already be tearing down; stderr remains available */
@@ -891,6 +918,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 				const workKeys = new Set([
 					...state.claims.filter((claim) => claim.from_session === exocomSessionId).map((claim) => claim.work_key),
 					...state.asks.filter((ask) => ask.from_session === exocomSessionId).map((ask) => ask.work_key),
+					...(state.collaboration?.tasks.filter((task) => !task.finished && (task.taken?.from_session ?? task.created.from_session) === exocomSessionId).map((task) => task.created.work_key) ?? []),
 				]);
 				for (const work_key of workKeys) {
 					const prune = currentLedgerPruneOptions();

package/src/exocom/ledger.ts

@@ -8,7 +8,8 @@ import { dirname } from "node:path";
 
 import { attributePeer } from "../core/fence.ts";
 import { findWriteSetOverlaps, writeSetPathError } from "../core/ownership.ts";
-import { isSemanticFrame, truncateForInject, type ExocomAsk, type ExocomClaim, type ExocomSemanticFrame } from "./envelope.ts";
+import { frameSigningPayload, isSemanticFrame, truncateForInject, type ExocomAsk, type ExocomClaim, type ExocomSemanticFrame } from "./envelope.ts";
+import { applyCollaborationEvent, collaborationStatus, emptyCollaboration, parseCollaboration, pruneCollaboration, releaseCollaboration, retainedCollaborationEvent, type CollaborationState } from "./collaboration.ts";
 
 export type LedgerEvent = ExocomSemanticFrame;
 
@@ -33,6 +34,8 @@ export interface LedgerState {
 	/** Accepted ask ids, including completed asks, so ids cannot be recycled in this retained ledger window. */
 	askIds: string[];
 	seen: string[];
+	/** Optional only for older in-memory callers; current snapshots retain the bounded peer-work state. */
+	collaboration?: CollaborationState;
 }
 
 export type ApplyResult =
@@ -56,7 +59,7 @@ export const LEDGER_LIMITS = {
 } as const;
 
 export function emptyLedger(): LedgerState {
-	return { claims: [], asks: [], answers: [], askIds: [], seen: [] };
+	return { claims: [], asks: [], answers: [], askIds: [], seen: [], collaboration: emptyCollaboration() };
 }
 
 function remember(state: LedgerState, msgId: string): LedgerState {
@@ -99,8 +102,31 @@ export function applyLedgerEvent(state: LedgerState, event: LedgerEvent): ApplyR
 		}
 		return { ok: false, error: "malformed ledger event" };
 	}
+	const retained = retainedCollaborationEvent(state.collaboration ?? emptyCollaboration(), event.msg_id);
+	if (retained) return frameSigningPayload(retained) === frameSigningPayload(event)
+		? { ok: true, state, duplicate: true } : { ok: false, error: "msg_id conflicts with a retained collaboration fact" };
 	if (state.seen.includes(event.msg_id)) return { ok: true, state, duplicate: true };
 	switch (event.kind) {
+		case "task_create":
+		case "task_take":
+		case "task_finish":
+		case "offer":
+		case "publish": {
+			const collaboration = state.collaboration ?? emptyCollaboration();
+			const applied = applyCollaborationEvent(collaboration, event);
+			if (!applied.ok) return applied;
+			let claims = state.claims;
+			const task = collaboration.tasks.find((candidate) => candidate.created.work_key === event.work_key);
+			if (event.kind === "task_take" && task?.created.write_set.length) {
+				if (claims.some((claim) => claim.work_key === event.work_key && claim.from_session === event.from_session)) return { ok: false, error: "task pickup conflicts with an existing owned claim on this work_key" };
+				const claimed = applyLedgerEvent(state, { kind: "claim", work_key: event.work_key, from_session: event.from_session, from_name: event.from_name,
+					write_set: [...task.created.write_set], slice: task.created.description.slice(0, 256), msg_id: event.msg_id, ts: event.ts });
+				if (!claimed.ok) return claimed;
+				claims = claimed.state.claims;
+			}
+			if (event.kind === "task_finish" && task?.taken) claims = claims.filter((claim) => claim.msg_id !== task.taken!.msg_id);
+			return { ok: true, state: remember({ ...state, claims, collaboration: applied.state }, event.msg_id) };
+		}
 		case "claim": {
 			if (state.claims.length >= LEDGER_LIMITS.maxClaims) return { ok: false, error: "ledger claim limit reached" };
 			for (const path of event.write_set) {
@@ -138,12 +164,18 @@ export function applyLedgerEvent(state: LedgerState, event: LedgerEvent): ApplyR
 		case "release": {
 			const owned = state.claims.filter((claim) => claim.work_key === event.work_key && claim.from_session === event.from_session);
 			const outbound = state.asks.filter((ask) => ask.work_key === event.work_key && ask.from_session === event.from_session);
-			if (owned.length === 0 && outbound.length === 0) return { ok: false, error: "release: no owned claim or outbound ask on that work_key" };
+			const collaboration = state.collaboration ?? emptyCollaboration();
+			const ownsTask = collaboration.tasks.some((task) => task.created.work_key === event.work_key && !task.finished && !task.stale
+				&& (task.taken?.from_session ?? task.created.from_session) === event.from_session);
+			if (owned.length === 0 && outbound.length === 0 && !ownsTask) return { ok: false, error: "release: no owned claim or outbound ask on that work_key" };
 			const claims = state.claims.filter((claim) => !(claim.work_key === event.work_key && claim.from_session === event.from_session));
 			const asks = state.asks.filter((ask) => !(ask.work_key === event.work_key && ask.from_session === event.from_session));
-			return { ok: true, state: remember({ ...state, claims, asks }, event.msg_id) };
+			return { ok: true, state: remember({ ...state, claims, asks, collaboration: releaseCollaboration(collaboration, event.from_session, event.work_key, Date.parse(event.ts)) }, event.msg_id) };
+		}
+		case "progress": {
+			const applied = applyCollaborationEvent(state.collaboration ?? emptyCollaboration(), event);
+			return applied.ok ? { ok: true, state: remember({ ...state, collaboration: applied.state }, event.msg_id) } : applied;
 		}
-		case "progress": return { ok: true, state: remember(state, event.msg_id) };
 	}
 }
 
@@ -154,6 +186,7 @@ interface LedgerSnapshot {
 	answers: LedgerAnswer[];
 	ask_ids: string[];
 	seen: string[];
+	collaboration?: CollaborationState;
 }
 
 function token(value: unknown): value is string {
@@ -216,7 +249,15 @@ function parseSnapshot(raw: unknown): LedgerState | undefined {
 	}
 	const requiredAskIds = new Set(state.askIds);
 	if (![...requiredAskIds].every((askId) => snapshot.ask_ids!.includes(askId))) return undefined;
-	return { ...state, askIds: [...snapshot.ask_ids], seen: [...snapshot.seen] };
+	const collaboration = snapshot.collaboration === undefined ? emptyCollaboration() : parseCollaboration(snapshot.collaboration);
+	if (!collaboration) return undefined;
+	for (const task of collaboration.tasks) {
+		if (collaborationStatus(task) !== "taken" || !task.created.write_set.length) continue;
+		const claim = state.claims.find((candidate) => candidate.msg_id === task.taken?.msg_id);
+		if (!claim || claim.from_session !== task.taken?.from_session || claim.work_key !== task.created.work_key
+			|| JSON.stringify(claim.write_set) !== JSON.stringify(task.created.write_set)) return undefined;
+	}
+	return { ...state, collaboration, askIds: [...snapshot.ask_ids], seen: [...snapshot.seen] };
 }
 
 function snapshotOf(state: LedgerState): LedgerSnapshot {
@@ -227,6 +268,7 @@ function snapshotOf(state: LedgerState): LedgerSnapshot {
 		answers: state.answers,
 		ask_ids: state.askIds,
 		seen: state.seen,
+		collaboration: state.collaboration ?? emptyCollaboration(),
 	};
 }
 
@@ -246,6 +288,8 @@ export function parseLedger(text: string): LedgerState {
 			state = restored;
 			continue;
 		}
+		if (raw && typeof raw === "object" && typeof (raw as { kind?: unknown }).kind === "string"
+			&& (raw as { kind: string }).kind.startsWith("ledger_snapshot_")) throw new Error("unsupported ledger snapshot version");
 		if (!isSemanticFrame(raw)) continue;
 		const result = applyLedgerEvent(state, raw);
 		if (result.ok) state = result.state;
@@ -276,7 +320,7 @@ export function pruneLedger(state: LedgerState, options: LedgerPruneOptions): Le
 	const asks = state.asks.filter((ask) => options.liveSessions.has(ask.from_session) && options.liveSessions.has(ask.to_session));
 	const answers = state.answers.filter((answer) => isFresh(answer.ts, now, ttlMs)).slice(-LEDGER_LIMITS.maxResults);
 	const askIds = [...new Set([...asks.map((ask) => ask.ask_id), ...answers.map((answer) => answer.ask_id)])];
-	return { ...state, claims, asks, answers, askIds };
+	return { ...state, claims, asks, answers, askIds, collaboration: pruneCollaboration(state.collaboration ?? emptyCollaboration(), now, ttlMs, (session) => options.liveSessions.has(session)) };
 }
 
 /** The pending asks a prune dropped (a party left the pool) — the ids a waiter must be woken for. */
@@ -565,6 +609,8 @@ export function appendLedgerEvent(path: string, event: LedgerEvent): void {
 export interface LedgerCommitOptions {
 	/** Applied under the same transaction lock before validating the new event. */
 	prune?: LedgerPruneOptions;
+	/** Authoritative write admission, evaluated against the locked task definition (not a preflight read). */
+	canClaim?: boolean;
 	/** Test/operations override; defaults to half the maximum journal size. */
 	compactAtBytes?: number;
 	/** Fault-injection seam for short-write and Windows replacement regression tests. */
@@ -578,7 +624,8 @@ export interface LedgerFileIO {
 
 function pruningChanged(before: LedgerState, after: LedgerState): boolean {
 	return before.claims.length !== after.claims.length || before.asks.length !== after.asks.length
-		|| before.answers.length !== after.answers.length || before.askIds.length !== after.askIds.length;
+		|| before.answers.length !== after.answers.length || before.askIds.length !== after.askIds.length
+		|| JSON.stringify(before.collaboration) !== JSON.stringify(after.collaboration);
 }
 
 export function commitLedgerEvent(path: string, event: LedgerEvent, options: LedgerCommitOptions = {}): ApplyResult {
@@ -588,6 +635,9 @@ export function commitLedgerEvent(path: string, event: LedgerEvent, options: Led
 		const sizeBeforeRecovery = recoverIncompleteTrailingRecordLocked(path);
 		const loaded = loadLedger(path);
 		const pruned = options.prune ? pruneLedger(loaded, options.prune) : loaded;
+		const writes = event.kind === "claim" || event.kind === "task_create" ? event.write_set.length > 0
+			: event.kind === "task_take" && (pruned.collaboration?.tasks.find((task) => task.created.work_key === event.work_key)?.created.write_set.length ?? 0) > 0;
+		if (options.canClaim === false && writes) return { ok: false, error: "this session cannot claim write paths in the selected scope" };
 		const result = applyLedgerEvent(pruned, event);
 		const compactAt = Number.isFinite(options.compactAtBytes) && options.compactAtBytes !== undefined
 			? Math.max(1, Math.floor(options.compactAtBytes)) : Math.floor(LEDGER_LIMITS.maxBytes / 2);