@aeondave/pi-persona 1.17.3 → 1.17.4

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

package/src/exocom/plane.ts

@@ -33,6 +33,7 @@ import { createFrameReader, encodeFrame } from "../bus/broker/framing.ts";
 import { frameSigningPayload, isExocomFrame, isSemanticFrame, nextHops, parseExocomArtifactDescriptor, truncateForInject, type AgentCard, type ExocomAck, type ExocomArtifactDescriptor, type ExocomBye, type ExocomFrame, type ExocomMessage, type ExocomNack, type ExocomSemanticFrame } from "./envelope.ts";
 import { EXOCOM } from "./limits.ts";
 import { exocomRoot } from "./paths.ts";
+import { normalizeExocomProfile, type ExocomProfile } from "./profile.ts";
 import { isAlive, normalizePeerName, prune, readAll, removeEntryIfMatches, writeEntry, type RegistryEntry, type RegistryOwnership } from "./registry.ts";
 
 export interface ExocomIdentity {
@@ -398,6 +399,9 @@ export class ExocomPlane {
 	private server: net.Server | undefined;
 	private readonly unlinkEndpoint: () => void;
 	private endpointOwned = false;
+	private profile: ExocomProfile | undefined;
+	/** Last successfully published metadata, so editing a profile cannot restore startup labels. */
+	private presence: RegistryEntry | undefined;
 	/** Ownership of the registry entry successfully written by this plane.  A plane
 	 * may share a session_id with a replacement, so session_id alone is not enough
 	 * to clean up safely. */
@@ -443,6 +447,17 @@ export class ExocomPlane {
 		return normalizePeerName(this.deps.identity.name);
 	}
 
+	/** The plane owns this transient, optional self-report for its live session. */
+	getProfile(): ExocomProfile | undefined {
+		return this.profile ? { ...this.profile, capabilities: [...this.profile.capabilities] } : undefined;
+	}
+
+	/** Update the live registry immediately; `undefined` withdraws the entire self-report. */
+	setProfile(profile: ExocomProfile | undefined): void {
+		this.profile = profile === undefined ? undefined : normalizeExocomProfile(profile);
+		if (this.registeredOwnership) this.heartbeat({ ...(this.presence ?? this.buildEntry()), heartbeat_at: new Date(this.now()).toISOString() });
+	}
+
 	/** Messages this instance has successfully `send()`'d TO the given peer (ack settled), keyed by
 	 *  the peer's session_id — 0 for a peer never sent to. The plane is the SINGLE source of these
 	 *  counters — the widget reads them, it never keeps its own. */
@@ -480,6 +495,7 @@ export class ExocomPlane {
 			prune(agentDir, hash, { now: this.now(), staleMs: EXOCOM.STALE_AFTER_MS });
 			const entry = this.buildEntry();
 			writeEntry(agentDir, hash, entry);
+			this.presence = entry;
 			this.registeredOwnership = {
 				session_id: entry.session_id,
 				endpoint: entry.endpoint,
@@ -524,6 +540,7 @@ export class ExocomPlane {
 				workspace_code: identity.workspace.code,
 				workspace_label: identity.workspace.label,
 			} : {}),
+			...(this.profile ? { profile: this.getProfile()! } : {}),
 		};
 	}
 
@@ -535,8 +552,15 @@ export class ExocomPlane {
 	 *  key exists only in this process. `session_id` is ours by construction, never the caller's. */
 	heartbeat(entry: Omit<RegistryEntry, "public_key">): void {
 		const { agentDir, hash, identity } = this.deps;
-		const owned = { ...entry, session_id: identity.session_id, public_key: this.publicKey };
+		const { profile: _callerProfile, ...entryWithoutProfile } = entry;
+		const owned = {
+			...entryWithoutProfile,
+			session_id: identity.session_id,
+			public_key: this.publicKey,
+			...(this.profile ? { profile: this.getProfile()! } : {}),
+		};
 		writeEntry(agentDir, hash, owned);
+		this.presence = owned;
 		this.registeredOwnership = { session_id: owned.session_id, endpoint: owned.endpoint, public_key: owned.public_key };
 	}
 
@@ -864,6 +888,11 @@ export class ExocomPlane {
 					return;
 				}
 				case "claim":
+				case "task_create":
+				case "task_take":
+				case "task_finish":
+				case "offer":
+				case "publish":
 				case "ask":
 				case "answer":
 				case "progress":
@@ -1112,5 +1141,7 @@ export class ExocomPlane {
 		// spill. In a scope where Exocom is never enabled again, that is never: sweeping on the
 		// way out bounds the retention without touching anything still inside its TTL.
 		this.cleanupArtifacts();
+		this.profile = undefined;
+		this.presence = undefined;
 	}
 }

package/src/exocom/profile.ts

@@ -0,0 +1,40 @@
+/** Self-reported presence only; these fields carry no identity or authorization. */
+export interface ExocomProfile {
+	capabilities: readonly string[];
+	availability?: "available" | "busy" | "away";
+}
+
+const UNSAFE_PROFILE_TEXT = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200b-\u200f\u202a-\u202e\u2060-\u206f<>]/g;
+const AVAILABILITIES = new Set(["available", "busy", "away"]);
+
+function normalizeCapability(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const clean = Array.from(value.normalize("NFKC").replace(UNSAFE_PROFILE_TEXT, " ").replace(/\s+/g, " ").trim())
+		.slice(0, 48).join("");
+	return clean || undefined;
+}
+
+/** Normalize untrusted registry or tool data into the bounded, display-safe profile contract. */
+export function normalizeExocomProfile(value: unknown): ExocomProfile | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	const capabilities: string[] = [];
+	const seen = new Set<string>();
+	if (Array.isArray(input.capabilities)) {
+		for (const value of input.capabilities) {
+			const capability = normalizeCapability(value);
+			if (!capability || seen.has(capability.toLowerCase())) continue;
+			seen.add(capability.toLowerCase());
+			capabilities.push(capability);
+			if (capabilities.length === 8) break;
+		}
+	}
+	const availability = typeof input.availability === "string" && AVAILABILITIES.has(input.availability)
+		? input.availability as ExocomProfile["availability"]
+		: undefined;
+	if (capabilities.length === 0 && availability === undefined) return undefined;
+	return {
+		capabilities,
+		...(availability ? { availability } : {}),
+	};
+}

package/src/exocom/registry.ts

@@ -2,6 +2,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { agentsDir, registryPath } from "./paths.ts";
+import { normalizeExocomProfile, type ExocomProfile } from "./profile.ts";
 
 export interface RegistryEntry {
 	/** `name` is display-only — NOT unique, NOT a lookup key. The registry FILE is keyed by
@@ -16,6 +17,8 @@ export interface RegistryEntry {
 	workspace_id?: string;
 	workspace_code?: string;
 	workspace_label?: string;
+	/** Optional self-reported presence; it is descriptive and never grants capability. */
+	profile?: ExocomProfile;
 }
 
 /** The fields that prove which process owns a registry slot.  `session_id` is the
@@ -57,6 +60,7 @@ export function normalizeRegistryEntry(value: unknown): RegistryEntry | undefine
 	const contextPct = typeof e.context_pct === "number" && Number.isFinite(e.context_pct) ? Math.max(0, Math.min(100, e.context_pct)) : 0;
 	const inbox = typeof e.inbox === "number" && Number.isFinite(e.inbox) ? Math.max(0, Math.min(1_000_000, Math.floor(e.inbox))) : 0;
 	const publicKey = opaqueString(e.public_key, 256);
+	const profile = normalizeExocomProfile(e.profile);
 	const hasWorkspaceMetadata = e.workspace_id !== undefined || e.workspace_code !== undefined || e.workspace_label !== undefined;
 	let workspace: Pick<RegistryEntry, "workspace_id" | "workspace_code" | "workspace_label"> = {};
 	if (hasWorkspaceMetadata) {
@@ -83,6 +87,7 @@ export function normalizeRegistryEntry(value: unknown): RegistryEntry | undefine
 		inbox,
 		heartbeat_at: new Date(Date.parse(heartbeatAt)).toISOString(),
 		...(publicKey && /^[A-Za-z0-9+/]+={0,2}$/.test(publicKey) ? { public_key: publicKey } : {}),
+		...(profile ? { profile } : {}),
 		...workspace,
 	};
 }

package/src/exocom/status.ts

@@ -20,6 +20,7 @@ import type { LedgerAsk, LedgerClaim, LedgerState } from "./ledger.ts";
 import { formatDuration } from "../core/time.ts";
 import { fencePeer } from "../core/fence.ts";
 import { renderWriteSet, untrusted, UNTRUSTED_MAX } from "./untrusted.ts";
+import { collaborationOfferStatus, collaborationStatus } from "./collaboration.ts";
 
 /** No section may hand the model an unbounded ledger — a long-lived scope with many claims stays
  *  one bounded read, same discipline as the pending-ask block and the peer roster. */
@@ -72,8 +73,12 @@ export function formatLedgerStatus(
 	const peerClaims = state.claims.filter((claim) => claim.from_session !== self).sort(byTsAscending);
 	const asksForYou = state.asks.filter((ask) => ask.to_session === self).sort(byTsAscending);
 	const yourAsks = state.asks.filter((ask) => ask.from_session === self).sort(byTsAscending);
+	const collaboration = state.collaboration;
+	const tasks = collaboration?.tasks ?? [];
+	const offers = collaboration?.offers ?? [];
+	const evidence = collaboration?.evidence ?? [];
 
-	if (ownClaims.length === 0 && peerClaims.length === 0 && asksForYou.length === 0 && yourAsks.length === 0) {
+	if (ownClaims.length === 0 && peerClaims.length === 0 && asksForYou.length === 0 && yourAsks.length === 0 && tasks.length === 0 && offers.length === 0 && evidence.length === 0) {
 		return "nothing claimed or pending";
 	}
 
@@ -82,5 +87,10 @@ export function formatLedgerStatus(
 		section("peer claims", peerClaims.map((claim) => claimRow(claim, self, labelFor, now)), { fence: true }),
 		section("asks waiting for you", asksForYou.map((ask) => askRow(ask, ask.from_session, labelFor, now)), { fence: true }),
 		section("your open asks", yourAsks.map((ask) => askRow(ask, ask.to_session, labelFor, now))),
+		...(tasks.length ? [section("shared tasks (exocom_task list for detail)", tasks.map((task) =>
+			`${task.created.work_key} · ${collaborationStatus(task)} · ${resolveLabel(task.taken?.from_session ?? task.created.from_session, labelFor)}`), { fence: true })] : []),
+		...(offers.length ? [section("optional invitations", offers.map((offer) =>
+			`${offer.offer_id} · task ${offer.work_key} · ${collaborationOfferStatus(offer, tasks, now)} · ${offer.to_session ? resolveLabel(offer.to_session, labelFor) : "open invitation"}`), { fence: true })] : []),
+		...(evidence.length ? [`${evidence.length} retained evidence excerpt(s); discover with exocom_publish { action: "read", work_key: "<task>" }.`] : []),
 	].join("\n\n");
 }

package/src/exocom/write-guard.ts

@@ -64,6 +64,13 @@ export function writeWarningReason(path: string, claim: LedgerClaim, label: stri
 	return `exocom: ${path} is inside ${who}'s open claim — coordinate with exocom_ask or claim it; call the tool again to proceed (this warning shows once per path)\n${fencePeer(`${slice}: ${writeSet}`)}`;
 }
 
+/** The operator-TOAST variant of the same warning: its single authoritative line, sanitized and
+ *  bounded. The fenced peer-authored detail below the newline stays model-facing (the tool
+ *  result); a toast is one line and never carries the claim block. */
+export function writeWarningToastReason(path: string, claim: LedgerClaim, label: string): string {
+	return untrusted(writeWarningReason(path, claim, label).split("\n")[0] ?? "", 300);
+}
+
 /** Warn-once memory for the write guard. A bare unbounded set would grow for the life of the
  *  install on a long session with many distinct claim+path pairs; caps at `maxEntries` (like the
  *  sibling `SeenMessages` in guards.ts) and drops the oldest insertion first once exceeded. */