@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/engine/worktree.ts

@@ -76,11 +76,14 @@ export async function worktreePreflight(root: string, exec: GitExec = defaultGit
 	return { ok: true };
 }
 
-/** Capture the complete post-run worktree state as a portable unified diff. Tracked edits use
- * `git diff HEAD`; files newly created by a coding leg are added with `git diff --no-index`.
+/** Capture the complete post-run worktree state as a portable unified diff from its pinned
+ * starting commit. Files newly created by a coding leg are added with `git diff --no-index`.
  * Exit code 1 is the normal "files differ" result for --no-index. */
-export async function captureWorktreeArtifact(root: string, exec: GitExec = defaultGitExec): Promise<WorktreeArtifact> {
-	const tracked = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", "HEAD", "--"]);
+export async function captureWorktreeArtifact(root: string, baseCommit: string, exec: GitExec = defaultGitExec): Promise<WorktreeArtifact> {
+	if (!baseCommit.trim()) {
+		return { ok: false, error: "could not export the isolated worktree diff: starting commit is missing" };
+	}
+	const tracked = await exec(["-C", root, "diff", "--no-ext-diff", "--binary", baseCommit, "--"]);
 	if (tracked.code !== 0) {
 		return { ok: false, error: `could not export the isolated worktree diff: ${tracked.stderr.trim() || `git exited ${tracked.code}`}` };
 	}
@@ -107,8 +110,9 @@ export async function captureWorktreeArtifact(root: string, exec: GitExec = defa
 	return { ok: true, diff: parts.join("\n") };
 }
 
-/** Create a detached worktree off `root`'s HEAD, run `body(worktreeDir)`, then force-remove it. */
-export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: string) => Promise<T>): Promise<T> {
+/** Create a detached worktree off `root`'s HEAD, pin its starting commit, run
+ * `body(worktreeDir, baseCommit)`, then force-remove it. */
+export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: string, baseCommit: string) => Promise<T>): Promise<T> {
 	const preflight = await worktreePreflight(root, exec);
 	if (!preflight.ok) throw new Error(preflight.error);
 	const dir = await mkdtemp(join(tmpdir(), "pi-persona-wt-"));
@@ -120,7 +124,13 @@ export async function withWorktree<T>(root: string, exec: GitExec, body: (dir: s
 		throw new Error(`could not create git worktree: ${add.stderr.trim() || `git exited ${add.code}`}`);
 	}
 	try {
-		return await body(dir);
+		const initial = await exec(["-C", dir, "rev-parse", "--verify", "HEAD^{commit}"]);
+		const baseCommit = initial.stdout.trim();
+		if (initial.code !== 0 || !baseCommit) {
+			const reason = initial.stderr.trim() || (initial.code !== 0 ? `git exited ${initial.code}` : "Git returned an empty commit id");
+			throw new Error(`could not resolve the initial worktree commit: ${reason}`);
+		}
+		return await body(dir, baseCommit);
 	} finally {
 		// Remove the worktree registration, then the dir (force: it may carry the agent's edits).
 		// Never throw: cleanup must not replace the body's result (or its error) — `defaultGitExec`

package/src/exocom/collaboration-delivery.ts

@@ -0,0 +1,29 @@
+/** Signed offer wakes project retained ledger data; the envelope is never its authority. */
+import { attributePeer } from "../core/fence.ts";
+import { collaborationOfferStatus } from "./collaboration.ts";
+import { frameSigningPayload, type ExocomOffer, type ExocomSemanticFrame } from "./envelope.ts";
+import type { LedgerState } from "./ledger.ts";
+
+export function collaborationWriteIntent(frame: ExocomSemanticFrame, state: LedgerState): boolean {
+	if (frame.kind === "claim" || frame.kind === "task_create") return frame.write_set.length > 0;
+	return frame.kind === "task_take" && (state.collaboration?.tasks.find((task) => task.created.work_key === frame.work_key)?.created.write_set.length ?? 0) > 0;
+}
+
+export function deliverCollaborationOffer(
+	frame: ExocomOffer, state: LedgerState, sessionId: string, label: string, now: number,
+): { accepted: true; notice?: string } | { accepted: false; reason: string } {
+	if (frame.to_session !== sessionId) return { accepted: false, reason: "offer addressed to another session" };
+	const stored = state.collaboration?.offers.find((offer) => offer.offer_id === frame.offer_id);
+	if (!stored || frameSigningPayload(stored) !== frameSigningPayload(frame)) {
+		return { accepted: false, reason: "offer is not durable with this sender and payload" };
+	}
+	const tasks = state.collaboration?.tasks ?? [];
+	if (collaborationOfferStatus(stored, tasks, now) !== "open") return { accepted: true };
+	const task = tasks.find((candidate) => candidate.created.work_key === stored.work_key && candidate.created.msg_id === stored.task_id);
+	if (!task) return { accepted: true };
+	return { accepted: true, notice: [
+		`[pi-persona] Optional peer invitation · task=${stored.work_key} · offer=${stored.offer_id} · expires ${stored.expires_at}`,
+		"This creates no response obligation or permission. Inspect the task and take it voluntarily only within your authorized scope; otherwise continue your work.",
+		attributePeer(frame.from_session === task.created.from_session ? label : task.created.from_session, task.created.description),
+	].join("\n") };
+}

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

@@ -13,6 +13,7 @@ import { canCallTool, canParticipateInExocom, EXOCOM_TOOL_NAMES } from "../core/
 import type { DelegationNudge } from "../core/nudge.ts";
 import { shortModel } from "../tools/delegate.ts";
 import { boundDisplayRows } from "../ui/presentation.ts";
+import { compactWidget } from "../ui/compact-widget.ts";
 import type { PersonaController } from "../persona/controller.ts";
 import { type InstanceDescriptor, type PeerDescriptor } from "../telemetry/contract.ts";
 import type { TelemetryProducer } from "../telemetry/producer.ts";
@@ -26,6 +27,7 @@ import {
 	sanitizePeerField,
 	sendPersonaFollowUp,
 	shouldReportHeartbeatFailure,
+	toastCause,
 	type ExocomQueuedToast,
 } from "../extension/shared.ts";
 import { SeenMessages, SenderBudget } from "./guards.ts";
@@ -53,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";
 
@@ -236,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),
 		};
@@ -327,7 +327,7 @@ export function installExocom(pi: ExtensionAPI, host: ExocomHost): ExocomInstall
 							return `${quiet ? "💤" : "📡"} ${name}${persona ? ` (${persona})` : ""} · ${shortModel(model) || "?"} · ctx ${contextPct}% · recv ${exocomPlane?.receivedFromPeer(p.session_id) ?? 0} · sent ${exocomPlane?.sentToPeer(p.session_id) ?? 0}${workspaceBit}`;
 						});
 			const lines = boundDisplayRows(local, peerRows, 7, "exocom_list for the full pool");
-			host.lastCtx.ui.setWidget("persona-exocom", lines, { placement: "aboveEditor" });
+			host.lastCtx.ui.setWidget("persona-exocom", compactWidget(lines), { placement: "aboveEditor" });
 		} catch {
 			/* cosmetic — the widget is best-effort */
 		}
@@ -411,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; },
@@ -422,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;
@@ -535,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") {
@@ -549,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.
@@ -561,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 {
@@ -656,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 });
 						}
 					}
@@ -691,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" };
@@ -739,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 {
@@ -774,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.
@@ -782,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 */
@@ -890,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();