pi-roundtable-sandbox 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.9.0
+
+- The sandbox claim answers only an author the host's `access` rules serve: it reads the router's `message.speaker` and ignores a message without one, as it ignores a bot's. A guest who was answered in 0.8 without any tier is now ignored until `access` gives them one, for example `access.members.roles` naming their guild role. The message is still never routed to a host agent.
+- `SandboxRuntime.runTurn` takes the author's `principalId` with their `id` and `name` (`SandboxSpeaker`, a new export) and refuses a turn without one. Host tools read it as `context.speaker.principalId`, and the credential hook as `scope.speaker.principalId`, so a host can pick a key per principal. The worker still reads only the author's `id` and `name`; its memory namespaces are unchanged. A `PiSandboxRuntime` turn's scope carries no principal.
+- `precheckScriptRunner` grants a script what `context.tier`, the tier of its run (pi-roundtable 0.9's `PrecheckContext.tier`, its schedule's capped at what its creator holds now), reaches, instead of the tier the schedule was set at, so a script 0.8 stored at the owner tier no longer reaches the owner's tools for a member.
+- `ScopedSandboxDelegator.start` takes the author's `principalId` and the tier `member`, as pi-roundtable 0.9's `DelegationJob.author` requires them, and refuses any other tier, as it refused a tier before: a guest's report runs as the principal the host bound them to, at the member tier or theirs, whichever is lower. The worker's `run` still hears only the author's `id` and `name`.
+
 ## 0.8.0
 
 - `apiKey` and `oauthToken` receive `{ channel, speaker }` (`SandboxCredentialScope`, a new export) before every model call, so a host can pick a key or a subscription per channel or speaker, such as `apiKey: ({ channel }) => keys.get(channel)`. A zero-argument function keeps working. A turn keeps the scope it started with while its requests are in flight, and a getter that returns `undefined` or an empty string fails the call: no other credential is used. The worker still sees only the placeholder key.

package/README.md

@@ -59,7 +59,8 @@ export const guestPlugins = [sandbox({
 Choose a model available to your endpoint and sign the host into its provider.
 By default, `context.apiKey(provider)` is read on every request, allowing login refresh without copying credentials into the worker.
 Alternatively supply `apiKey: () => process.env.MODEL_API_KEY` when the endpoint uses a separate key.
-`apiKey` receives `{ channel, speaker }` (`SandboxCredentialScope`) before every model call, so a host can pick a different key per channel or speaker, for example `apiKey: ({ channel }) => keys.get(channel)`; a zero-argument function keeps working.
+`apiKey` receives `{ channel, speaker }` (`SandboxCredentialScope`) before every model call, so a host can pick a different key per channel, speaker or principal, for example `apiKey: ({ channel }) => keys.get(channel)` or `apiKey: ({ speaker }) => keys.get(speaker.principalId)`; a zero-argument function keeps working.
+`speaker.principalId` is the principal the host's identity service resolved the author to; it never reaches the worker.
 When the hook has no key it should return `undefined` (the call fails closed) rather than fall back to the host's own login.
 Keep secrets in the service's protected environment, not configuration source or the worker image.
 All directories must be dedicated to this package and owned by the service account.
@@ -74,7 +75,8 @@ Only one host process may own these directories.
 Restart the bot, then run `/roundtable sandbox on` in a guild channel as the owner.
 The command root follows your `discord.rootCommand` setting.
 The claim outranks the core agent-server claim (priority 200 versus 100), including when the owner speaks there.
-It answers non-bot, non-integration guild messages that mention the bot or reply to it.
+It answers non-bot, non-integration guild messages that mention the bot or reply to it, from an author the host's `access` rules serve.
+Give guests a tier there, for example `access.members.roles` naming their guild role; the sandbox ignores an author the rules serve no one by, as it ignores a message whose author could not be resolved.
 Other messages are dropped, never routed to a host agent.
 `/roundtable sandbox status` shows the mode; `/roundtable sandbox off` retains memory and restores normal routing after queued work completes.
 These commands are guarded by the published owner-command helper and serialized through the shared channel queue.
@@ -105,7 +107,7 @@ const tools: HostTool[] = [{
 Pass `tools` to `sandbox()`.
 Host tool and MCP server/tool names must match `[a-z][a-z0-9_]{0,47}`.
 The worker exposes them as `host_clock`, while the broker accepts only `POST /tools/clock`.
-The host binds `context.channel` and `context.speaker` to the current admitted turn.
+The host binds `context.channel` and `context.speaker` to the current admitted turn; `context.speaker.principalId` is the principal the author was admitted as.
 The callback signal combines the request's deadline/closure and the turn's cancellation, and aborts when either scope ends.
 Body fields cannot change that identity, even if a guest replaces the worker or forges a broker call.
 Callbacks must validate every input field, enforce their own authorization and rate limits, obey cancellation, and avoid returning secrets.
@@ -219,7 +221,7 @@ Other model transports are not implicitly proxied by this broker.
 | `partyDir`, `image` | Dedicated private, host-owned directory and operator-built Pi image. |
 | `profiles` | Host allow-list mapping profile names to fixed Anthropic `model` and optional MCP server names. |
 | `oauthToken({ channel, speaker })` | Host-only credential getter called before each model request with the bound turn's channel and speaker, so a host can use a different subscription per channel or speaker; supports refresh without container credentials. A zero-argument getter still works. Returning `undefined` or an empty string fails the call; no other credential is used. |
-| `memory.promptBlock(channel, id, name)` | Current admitted speaker's context, at most 100,000 characters; database implementations remain host adapters. |
+| `memory.promptBlock(channel, id, name)`, `memory.visibility` | Context at most 100,000 characters; private to the admitted reader by default. Explicit `"shared"` declares party-wide facts public and avoids tainting reader records. Database implementations remain host adapters. |
 | `effort.judge(text, { level })` | Host-selected `low`, `medium`, `high`, or `xhigh`; the previous channel choice is retained for the next judgment. |
 | `tools.names`, `tools.call` | Explicit host tool allow-list and callback receiving fixed channel/profile/speaker plus cancellation signal. |
 | `mcp.servers`, `mcp.token()` | Fixed server URLs and tool-name allow-lists; host credential getter. |
@@ -241,6 +243,64 @@ Callbacks must still validate input and enforce per-person quotas, memory author
 Optional person/notes/moments tools can use an existing PostgreSQL store without copying the connection, schema, migration ledger or owner memory into the image.
 Schedules can be host tools with a declared channel-local background target and host-bound author; no scheduler is enabled automatically.
 
+### Principal migration in 0.9
+
+Follow [Migrating to 0.9](../../docs/migration-0.9.md) for the core upgrade.
+The sandbox claim ignores an author with no resolved tier; guests need core `access` admission, not an implicit owner fallback.
+`SandboxRuntime.runTurn` requires a host-bound speaker with `principalId`, and credential/host-tool hooks receive that id; the sealed worker protocol still receives only the actor id and name.
+For the separate `PiSandboxRuntime`, pass `author: { id, name, principalId }` from the admitted speaker: `id` remains the actor id and `principalId` is the reader used for private-history projection.
+It is optional for compatibility, falling back to `id` only for integrations whose actor id already is the principal id.
+Never take it from guest tool arguments.
+This does not isolate a shared channel's workspace by principal: guests in that channel still share its raw files and stored history.
+The sealed default's channel-shared memory contract is unchanged.
+Per-person model credentials remain the host integration's responsibility, not a guarantee of the core release.
+
+### Private tool exchanges in Pi mode
+
+The container creates its own Pi session, not the core's `SessionFactory`; the worker now explicitly applies core `memoryProjection` to requests and `privateCompaction` before summaries.
+Host tool callbacks may return `PiToolResponse` with `privateTo?: string`, a principal id:
+
+```ts
+const principalId = context.speaker.principalId;
+if (!principalId) throw new Error("Private tools require a bound principal");
+return { ok: true, text: "private facts", privateTo: principalId };
+```
+
+The broker validates and preserves the field; the worker persists it as `details.privateTo` on the Pi tool result, including tagged error results (`ok: false`).
+`PiSandboxRuntimeOptions.memory.visibility` declares whether `promptBlock` is `"private"` (default) or `"shared"`.
+A private nonempty prompt block taints that turn's reader record even without a tool call; an explicitly shared block does not.
+A host with party-wide facts must set `memory.visibility: "shared"`, including when upgrading a 0.8 integration, or another participant's later claude-bridge turn is refused.
+Shared visibility applies only to that prompt block; a tool returning `privateTo` still creates a private exchange.
+For another reader, the call's arguments and result become placeholders while their call id/name pairing stays valid.
+The principal itself still sees the original exchange.
+This applies to any custom tool name, not just core memory tools; `remember_person`, `recall_person`, and `forget_person` must be tagged by the host when their results are private.
+Untagged custom exchanges are public.
+Both Pi's summary and the host compactor receive no tagged private exchanges, including the kept tail sent to the host, and no earlier prompt memory or reasoning.
+Calls/results split across compaction boundaries are paired for redaction.
+The bridge provider bypasses request projection by replaying its own history: before calling a provider, the worker refuses a bridge turn when its raw persisted branch records private memory carried for another reader, or holds an explicit private exchange hidden from that reader, even after Pi compacted it.
+Reader records cover private prompt blocks and their retained reasoning without requiring a tool call; memory exchanges, including malformed/truncated/unanswered built-in calls, belong to their turn's reader.
+A turn carrying no private memory never blocks another participant merely for speaking, so explicitly shared party-wide prompt blocks with public tools remain usable across A → B → A turns.
+Unlike the core host guard, sandbox has no primary-owner compatibility exception for untagged old built-in memory exchanges.
+Existing summaries are not retroactively scrubbed.
+Start fresh before allowing new readers into histories previously summarized without this protection, and rebuild the worker image with the upgraded core and sandbox together.
+This is exchange isolation, not general secret-flow prevention or a hostile-container boundary: public replies, untagged tools, raw workspace files, and attachments/reply files remain shared.
+Do not put confidential data in the guest workspace.
+
+### Worker capability handshake
+
+The trusted Pi worker sends `POST /worker/ready` with `{ capabilities: { privateTo: true, readerRecords: true }, privateHistory: <boolean> }`.
+`privateTo` declares tagged call/result request projection and private compaction support; `readerRecords` declares persisted per-turn readers, prompt privacy, and raw-branch bridge refusal.
+`privateHistory` reports retained private history, including compacted turns, when a worker reconnects to a restarted host.
+A missing or empty ready body means an older worker, not implicit support; malformed capability declarations are refused.
+The host requires both capabilities only when a turn carries a nonempty private prompt block, the worker reports retained private history, or a host tool actually returns `privateTo`.
+Merely configuring tools does not require capabilities, and old images can still serve empty or explicitly shared prompt blocks with only public tools.
+If a host tool first returns `privateTo` to an incompatible image, its payload is not sent to the worker: the host fails the whole turn and blocks subsequent model calls, even if the old worker catches tool errors.
+The error names the exact configured image to rebuild with the installed core and sandbox packages; keeping the same local image tag is not proof that it has been rebuilt.
+A worker reconnecting without capabilities also invalidates an already queued private turn.
+For direct `PiSandboxBroker` integrations, supply `workerImage` so errors name that image; `PiSandboxRuntime` supplies its `image` automatically.
+This handshake detects mixed trusted versions, not a compromised worker that lies about its capabilities.
+It does not sanitize historical data written by an old worker; start fresh before sharing previously unsafe private history.
+
 ### Compaction
 
 Worker sessions compact with the core's tiers, as the host's own sessions do: a model whose window leaves more than 300,000 tokens compacts at 300,000 through the host compactor, and past 500,000 through Pi's own summary, whose model calls go through the broker like any other.
@@ -394,7 +454,7 @@ export const precheckScripts = definePlugin({
 });
 ```
 
-`grant({ channel, target, tier })` returns the `PrecheckMcpServer`s a script for that schedule may call: `{ name, url, tools, token? }`.
+`grant({ channel, target, tier })` returns the `PrecheckMcpServer`s a script for that schedule may call: `{ name, url, tools, token? }`. `tier` is the tier the run is for, its schedule's capped at what its creator holds now (or the asker's, when `schedule_list` describes what a script may call), so grant lower tiers less.
 Each run reaches only the granted tools that were approved with the script: the core reads a script's calls when it is saved, and saving one that calls a tool the host's hold rules hold waits for the owner's approval. `toolName(server, tool)` gives the name those rules know a tool by, the name the host's own agent calls it by; the default is the tool's own name, so pass it when your agent sees MCP tools under another name, such as `${server}_${tool}`.
 The script calls a server by `name`, only the listed `tools`, and only with single `tools/call` requests; every other server, tool, method, query, and extra credential is refused, and refused calls count against the run's budget (`maxCalls`, default 16).
 `url` is a fixed HTTPS Streamable HTTP endpoint answering with JSON or one SSE event; `token` is read on the host for each call and inserted by the broker. An answer that carries it, plainly, inside JSON text, or base64-encoded, is refused; this catches an echo, not an upstream set on leaking it, so grant only upstreams you trust.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -36,7 +36,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
-		"pi-roundtable": ">=0.8.0 <0.9.0",
+		"pi-roundtable": ">=0.9.0 <0.10.0",
 		"typebox": ">=1.3.34 <2"
 	},
 	"peerDependenciesMeta": {
@@ -52,7 +52,7 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.8.0",
+		"pi-roundtable": "0.9.0",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/broker.ts

@@ -16,15 +16,29 @@ export interface BrokerListener {
 	stop(force?: boolean): Promise<void>;
 }
 
+/**
+ * Whom a turn is for, as the host admitted them: the author's `id` and `name` as their surface
+ * knows them, which the worker also reads, and the `principalId` the host's identity service
+ * resolved them to, which stays on the host.
+ */
+export interface SandboxSpeaker {
+	id: string;
+	name: string;
+	principalId: string;
+}
 export interface HostToolContext {
 	channel: ChannelKey;
-	speaker: { id: string; name: string };
+	speaker: SandboxSpeaker;
 	signal: AbortSignal;
 }
-/** Who a model call is made for; a credential hook can pick a token per channel or speaker. */
+/**
+ * Who a model call is made for; a credential hook can pick a token per channel, speaker or
+ * principal. A `sandbox` plugin turn always carries the principal; a `PiSandboxRuntime` turn
+ * carries none, as its author names none.
+ */
 export interface SandboxCredentialScope {
 	channel: ChannelKey;
-	speaker: { id: string; name: string };
+	speaker: { id: string; name: string; principalId?: string };
 }
 export interface HostTool extends ToolSpec {
 	run(
@@ -230,7 +244,11 @@ export class SandboxBroker {
 			const { channel, speaker } = this.#options.context;
 			const key = await this.#options.apiKey({
 				channel,
-				speaker: { id: speaker.id, name: speaker.name },
+				speaker: {
+					id: speaker.id,
+					name: speaker.name,
+					principalId: speaker.principalId,
+				},
 			});
 			if (!key) throw new Error("model credential unavailable");
 			return await this.#forward(

package/src/claim.ts

@@ -34,6 +34,10 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 		admit: (message) => {
 			if (!options.channels.has(message.channel) || !isSandboxAddress(message))
 				return undefined;
+			// The router resolved the author; one the host's access rules serve no one by goes
+			// unanswered, as does a message whose author it could not resolve.
+			const { speaker } = message;
+			if (!speaker) return undefined;
 			return {
 				kind: "turn",
 				failure: "sandbox turn failed",
@@ -45,7 +49,11 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 						const text = `${message.reference?.text ? `Quoted message (untrusted): ${message.reference.text}\n\n` : ""}${message.text}${message.attachments.length ? "\n[Attachments are not supported in this sandbox.]" : ""}`;
 						const reply = await options.runtime.runTurn(
 							message.channel,
-							{ id: message.authorId, name: message.authorName },
+							{
+								id: message.authorId,
+								name: message.authorName,
+								principalId: speaker.principalId,
+							},
 							text,
 						);
 						await options.surfaces.sendReply(message.channel, {

package/src/index.ts

@@ -20,6 +20,7 @@ export {
 	type McpServer,
 	SandboxBroker,
 	type SandboxCredentialScope,
+	type SandboxSpeaker,
 } from "./broker.ts";
 export { SandboxChannelStore } from "./channel-store.ts";
 export {

package/src/pi-broker.ts

@@ -17,6 +17,7 @@ import {
 	type PiTurnRequest,
 	type PiTurnResponse,
 	type PiWorkerConfig,
+	type PiWorkerReady,
 	validateCompactionReport,
 	validateCompactRequest,
 	validateImages,
@@ -27,7 +28,7 @@ import { boundedText, isRecord } from "./protocol.ts";
 export interface PiHostContext {
 	channel: ChannelKey;
 	profile: string;
-	speaker: { id: string; name: string };
+	speaker: { id: string; name: string; principalId?: string };
 	/** The host-judged level for this turn; the worker can request less but never more. */
 	thinking: PiThinkingLevel;
 	signal: AbortSignal;
@@ -66,6 +67,8 @@ export interface PiCompactor {
 }
 export interface PiBrokerOptions {
 	model: string;
+	/** Actual configured image, named in capability failures so the operator can rebuild it. */
+	workerImage?: string;
 	/** Host-only, read before each model call for its channel and speaker; a zero-argument function still works. Return `undefined` or an empty string when the scope has no token: the call fails rather than using another credential. Never sent to the worker. */
 	oauthToken: (
 		scope: SandboxCredentialScope,
@@ -282,6 +285,16 @@ function abortableCompact<T>(
 export class PiSandboxBroker {
 	readonly #options: PiBrokerOptions;
 	#ready = false;
+	#capabilities: NonNullable<PiWorkerReady["capabilities"]> = {};
+	#requiresPrivacy = false;
+	#capabilityProblem(): string | undefined {
+		const missing = (["privateTo", "readerRecords"] as const).filter(
+			(name) => this.#capabilities[name] !== true,
+		);
+		return missing.length === 0
+			? undefined
+			: `Sandbox worker image ${this.#options.workerImage ?? "(configured image)"} lacks ${missing.join(", ")}; rebuild this image with the installed core and sandbox packages`;
+	}
 	#receivingResult = false;
 	#next: ((turn: PiTurnRequest) => void) | undefined;
 	#pending:
@@ -301,6 +314,13 @@ export class PiSandboxBroker {
 		signal: AbortSignal,
 	): Promise<PiTurnResponse> {
 		if (this.#pending) return Promise.reject(new Error("Worker is busy"));
+		const privatePrompt =
+			request.memory.length > 0 && request.memoryVisibility !== "shared";
+		if (this.#requiresPrivacy || privatePrompt) {
+			const problem = this.#capabilityProblem();
+			if (problem) return Promise.reject(new Error(problem));
+			this.#requiresPrivacy = true;
+		}
 		return new Promise((resolve, reject) => {
 			const abort = () => {
 				this.#pending = undefined;
@@ -320,13 +340,52 @@ export class PiSandboxBroker {
 					this.#pending = undefined;
 					resolve(result);
 				},
-				reject,
+				reject: (error) => {
+					signal.removeEventListener("abort", abort);
+					this.#pending = undefined;
+					reject(error);
+				},
 			};
 			this.#next?.(request);
 		});
 	}
 	async #worker(request: Request, path: string): Promise<Response> {
 		if (path === "/worker/ready" && request.method === "POST") {
+			try {
+				const text = await boundedText(request.body, 16_384, request.signal);
+				const value: unknown = text.trim() ? JSON.parse(text) : {};
+				if (
+					!isRecord(value) ||
+					(value.privateHistory !== undefined &&
+						typeof value.privateHistory !== "boolean")
+				)
+					throw new Error("Invalid ready handshake");
+				const caps = value.capabilities;
+				if (
+					caps !== undefined &&
+					(!isRecord(caps) ||
+						[caps.privateTo, caps.readerRecords].some(
+							(flag) => flag !== undefined && typeof flag !== "boolean",
+						))
+				)
+					throw new Error("Invalid capabilities");
+				this.#capabilities = isRecord(caps)
+					? {
+							privateTo: caps.privateTo === true,
+							readerRecords: caps.readerRecords === true,
+						}
+					: {};
+				if (value.privateHistory === true) this.#requiresPrivacy = true;
+				if (this.#requiresPrivacy && this.#pending) {
+					const problem = this.#capabilityProblem();
+					if (problem) {
+						if (this.#turn) this.#turn.failed = true;
+						this.#pending.reject(new Error(problem));
+					}
+				}
+			} catch {
+				return new Response("Invalid ready handshake", { status: 400 });
+			}
 			this.#ready = true;
 			this.#rearmStartup();
 			return new Response("Ready");
@@ -416,7 +475,12 @@ export class PiSandboxBroker {
 		return new Response("Not found", { status: 404 });
 	}
 	#turn:
-		| { context: PiHostContext; remaining: number; active: number }
+		| {
+				context: PiHostContext;
+				remaining: number;
+				active: number;
+				failed?: boolean;
+		  }
 		| undefined;
 	/**
 	 * A restarted worker connects its MCP servers before any turn, so it needs the metadata-only
@@ -535,8 +599,20 @@ export class PiSandboxBroker {
 			return this.#compaction(request, url.pathname);
 		const startup = !this.#turn;
 		const turn = this.#turn ?? this.#startup;
-		if (!turn || turn.context.signal.aborted)
+		if (
+			!turn ||
+			turn.context.signal.aborted ||
+			("failed" in turn && turn.failed)
+		)
 			return new Response("Turn ended", { status: 410 });
+		if (this.#requiresPrivacy) {
+			const problem = this.#capabilityProblem();
+			if (problem) {
+				if (this.#turn) this.#turn.failed = true;
+				this.#pending?.reject(new Error(problem));
+				return new Response(problem, { status: 410 });
+			}
+		}
 		const toolName = url.pathname.startsWith("/tools/")
 			? url.pathname.slice(7)
 			: "";
@@ -581,9 +657,25 @@ export class PiSandboxBroker {
 					!result ||
 					typeof result.ok !== "boolean" ||
 					(result.text?.length ?? 0) > 1_000_000 ||
-					(result.error?.length ?? 0) > 10_000
+					(result.error?.length ?? 0) > 10_000 ||
+					(result.privateTo !== undefined &&
+						(typeof result.privateTo !== "string" ||
+							result.privateTo.length === 0 ||
+							result.privateTo.length > 256))
 				)
 					throw new Error("Invalid tool output");
+				if (result.privateTo !== undefined) {
+					this.#requiresPrivacy = true;
+					const problem = this.#capabilityProblem();
+					if (problem) {
+						// Do not release private bytes to an old worker, even when it catches tool errors.
+						if (this.#turn === turn) {
+							this.#turn.failed = true;
+							this.#pending?.reject(new Error(problem));
+						}
+						return new Response(problem, { status: 409 });
+					}
+				}
 				if (result.image) validateImages([result.image]);
 				signal.throwIfAborted();
 				return Response.json(result);

package/src/pi-protocol.ts

@@ -23,9 +23,11 @@ export interface PiImage {
 }
 export interface PiTurnRequest {
 	turnId: string;
-	author: { id: string; name: string };
+	author: { id: string; name: string; principalId?: string };
 	text: string;
 	memory: string;
+	/** Defaults to private for older callers; shared prompt blocks do not taint a reader record. */
+	memoryVisibility?: "shared" | "private";
 	images: PiImage[];
 	thinking: PiThinkingLevel;
 }
@@ -68,16 +70,28 @@ export interface PiToolResponse {
 	text?: string;
 	error?: string;
 	image?: PiImage;
+	/** The principal who may read this tool exchange, including its arguments. */
+	privateTo?: string;
 }
 export interface PiTurnContext {
 	authorId: string;
 	authorName: string;
+	/** Falls back to authorId for legacy workers whose actor id is already their principal. */
+	authorPrincipalId?: string;
 	outbox: string;
 	memory: string;
+	memoryVisibility?: "shared" | "private";
 }
 export interface PiMcpDiscovery {
 	servers: { name: string; tools: string[] }[];
 }
+/** Protocol guarantees declared by the trusted image; missing fields mean an older worker. */
+export interface PiWorkerReady {
+	capabilities?: { privateTo?: boolean; readerRecords?: boolean };
+	/** Raw retained branch has private memory, even if the current turn's prompt is public. */
+	privateHistory?: boolean;
+}
+
 /** What the worker learns from the host at startup; `compaction` is absent when the host has no compactor. */
 export interface PiWorkerConfig {
 	compaction?: { engine: string };
@@ -248,10 +262,17 @@ export function validatePiTurn(value: unknown): asserts value is PiTurnRequest {
 		typeof value.author.name !== "string" ||
 		value.author.id.length > 256 ||
 		value.author.name.length > 256 ||
+		(value.author.principalId !== undefined &&
+			(typeof value.author.principalId !== "string" ||
+				value.author.principalId.length === 0 ||
+				value.author.principalId.length > 256)) ||
 		typeof value.text !== "string" ||
 		value.text.length > 100_000 ||
 		typeof value.memory !== "string" ||
 		value.memory.length > 100_000 ||
+		(value.memoryVisibility !== undefined &&
+			value.memoryVisibility !== "shared" &&
+			value.memoryVisibility !== "private") ||
 		!isPiThinkingLevel(value.thinking)
 	)
 		throw new Error("Invalid turn");

package/src/pi-runtime.ts

@@ -79,6 +79,8 @@ export interface PiSandboxRuntimeOptions
 	driver?: PiContainerDriver;
 	mcp?: PiBrokerOptions["mcp"];
 	memory: {
+		/** Private by default; a party-wide block must explicitly declare shared visibility. */
+		visibility?: "shared" | "private";
 		promptBlock(channel: ChannelKey, id: string, name: string): Promise<string>;
 	};
 	effort: {
@@ -99,7 +101,7 @@ export interface PiSandboxTurn {
 	channel: ChannelKey;
 	profile: string;
 	turnId: string;
-	author: { id: string; name: string };
+	author: { id: string; name: string; principalId?: string };
 	text: string;
 	images: PiImage[];
 	signal?: AbortSignal;
@@ -276,6 +278,7 @@ export class PiSandboxRuntime {
 			const broker = new PiSandboxBroker({
 				...this.#options,
 				model: selected.model,
+				workerImage: this.#options.image,
 				mcp: this.#options.mcp ? { ...this.#options.mcp, servers } : undefined,
 			});
 			const socket = join(paths.run, PI_BROKER_SOCKET);
@@ -370,7 +373,11 @@ export class PiSandboxRuntime {
 				!safeFileName(turn.turnId) ||
 				turn.text.length > 100_000 ||
 				turn.author.id.length > 256 ||
-				turn.author.name.length > 256
+				turn.author.name.length > 256 ||
+				(turn.author.principalId !== undefined &&
+					(typeof turn.author.principalId !== "string" ||
+						turn.author.principalId.length === 0 ||
+						turn.author.principalId.length > 256))
 			)
 				throw new Error("Invalid turn input");
 			validateImages(turn.images);
@@ -399,6 +406,7 @@ export class PiSandboxRuntime {
 				author: { ...turn.author },
 				text: turn.text,
 				memory,
+				memoryVisibility: this.#options.memory.visibility ?? "private",
 				images: turn.images,
 				thinking,
 			};

package/src/precheck-runner.ts

@@ -339,7 +339,7 @@ export function precheckScriptRunner(
 			await grant({
 				channel: schedule.channel,
 				target: schedule.target,
-				tier: schedule.createdTier,
+				tier: context.tier,
 			})
 		).flatMap((server) => {
 			const tools = server.tools.filter((tool) =>

package/src/runtime-options.ts

@@ -114,7 +114,7 @@ export function resolveSandboxRuntimeOptions(
 		...options,
 		context: {
 			channel: "sandbox:preflight",
-			speaker: { id: "", name: "" },
+			speaker: { id: "", name: "", principalId: "" },
 			signal: new AbortController().signal,
 		},
 	});

package/src/runtime.ts

@@ -1,4 +1,5 @@
 import type { ChannelKey } from "pi-roundtable";
+import type { SandboxSpeaker } from "./broker.ts";
 import type { SandboxReply } from "./protocol.ts";
 import {
 	type ResolvedSandboxRuntimeOptions,
@@ -23,17 +24,26 @@ export class SandboxRuntime {
 		this.#options = resolveSandboxRuntimeOptions(options);
 	}
 
+	/**
+	 * Runs one turn for `speaker`, the author the host admitted, with the principal they resolved
+	 * to; host tools and the credential hook read it, and a turn without one is refused.
+	 */
 	async runTurn(
 		channel: ChannelKey,
-		speaker: { id: string; name: string },
+		speaker: SandboxSpeaker,
 		text: string,
 	): Promise<SandboxReply> {
 		if (this.#closed || this.#active.has(channel))
 			throw new Error("sandbox is stopped or channel is busy");
+		if (typeof speaker.principalId !== "string" || !speaker.principalId)
+			throw new Error(
+				"a sandbox turn needs the principal its speaker was admitted as",
+			);
 		if (
 			text.length > 32_000 ||
 			speaker.id.length > 256 ||
-			speaker.name.length > 256
+			speaker.name.length > 256 ||
+			speaker.principalId.length > 256
 		)
 			throw new Error("sandbox message too large");
 		const controller = new AbortController();
@@ -48,7 +58,11 @@ export class SandboxRuntime {
 			this.#options,
 			{
 				channel,
-				speaker: { ...speaker },
+				speaker: {
+					id: speaker.id,
+					name: speaker.name,
+					principalId: speaker.principalId,
+				},
 				text,
 				reset: resetGeneration > 0,
 				signal: controller.signal,

package/src/sandbox-turn.ts

@@ -2,13 +2,17 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import type { ChannelKey } from "pi-roundtable";
-import { type BrokerListener, SandboxBroker } from "./broker.ts";
+import {
+	type BrokerListener,
+	SandboxBroker,
+	type SandboxSpeaker,
+} from "./broker.ts";
 import type { SandboxReply, SandboxTurn } from "./protocol.ts";
 import type { ResolvedSandboxRuntimeOptions } from "./runtime-options.ts";
 
 interface SandboxTurnRequest {
 	channel: ChannelKey;
-	speaker: { id: string; name: string };
+	speaker: SandboxSpeaker;
 	text: string;
 	reset: boolean;
 	signal: AbortSignal;
@@ -42,7 +46,8 @@ export async function runSandboxTurn(
 		}).listen(socket);
 		const turn: SandboxTurn = {
 			text,
-			speaker,
+			// The worker reads who speaks; whose principal they are stays with the host.
+			speaker: { id: speaker.id, name: speaker.name },
 			model: options.model,
 			prompt:
 				options.prompt ??

package/src/scoped-delegator.ts

@@ -74,11 +74,13 @@ export class ScopedSandboxDelegator {
 	start(
 		request: Omit<DelegationJob, "id" | "startedAt" | "thread">,
 	): DelegationJob {
+		// A guest's report runs at the member tier, as the principal the host bound them to.
 		if (
 			this.#closed ||
 			request.target !== this.#options.target ||
 			request.origin ||
-			request.author.tier
+			request.author.tier !== "member" ||
+			!request.author.principalId
 		)
 			throw new DelegationError("Delegation scope refused");
 		const task = request.task.trim();
@@ -104,7 +106,12 @@ export class ScopedSandboxDelegator {
 			id: this.#next++,
 			channel: request.channel,
 			target: this.#options.target,
-			author: { id: request.author.id, name: request.author.name },
+			author: {
+				principalId: request.author.principalId,
+				id: request.author.id,
+				name: request.author.name,
+				tier: "member",
+			},
 			title: request.title.trim(),
 			task,
 			startedAt: new Date(),
@@ -119,7 +126,7 @@ export class ScopedSandboxDelegator {
 			try {
 				const report = await this.#options.run(job.task, {
 					channel: job.channel,
-					author: job.author,
+					author: { id: job.author.id, name: job.author.name },
 					signal,
 				});
 				signal.throwIfAborted();

package/worker/pi-compaction.ts

@@ -13,6 +13,8 @@ import {
 	type CompactionHistory,
 	CompactionTiers,
 	compactionEngine,
+	privateCompaction,
+	summaryProjection,
 } from "pi-roundtable/kit";
 import type {
 	PiCompactionReport,
@@ -52,6 +54,12 @@ export function compactRequest(
 					.flatMap((entry) =>
 						entry.type === "message" ? [entry.message] : [],
 					);
+	privateCompaction(preparation, keptMessages);
+	const projectedKept = summaryProjection(keptMessages, [
+		...preparation.messagesToSummarize,
+		...preparation.turnPrefixMessages,
+		...keptMessages,
+	]);
 	const { read, written, edited } = preparation.fileOps;
 	const modified = new Set([...written, ...edited]);
 	return {
@@ -61,7 +69,7 @@ export function compactRequest(
 		isSplitTurn: preparation.isSplitTurn,
 		messagesToSummarize: preparation.messagesToSummarize as PiCompactMessage[],
 		turnPrefixMessages: preparation.turnPrefixMessages as PiCompactMessage[],
-		keptMessages: keptMessages as PiCompactMessage[],
+		keptMessages: projectedKept as PiCompactMessage[],
 		...(preparation.previousSummary === undefined
 			? {}
 			: { previousSummary: preparation.previousSummary }),
@@ -105,10 +113,20 @@ export class WorkerCompaction {
 		return [
 			{
 				name: "host-compaction",
-				factory: this.#tiers.wrapCompactor(handler, (bypass) => {
-					this.#options.log("compaction skips the host compactor", bypass);
-					void this.#report({ type: "bypass", ...bypass });
-				}),
+				factory: this.#tiers.wrapCompactor(
+					handler,
+					(bypass) => {
+						this.#options.log("compaction skips the host compactor", bypass);
+						void this.#report({ type: "bypass", ...bypass });
+					},
+					(event) =>
+						privateCompaction(
+							event.preparation,
+							event.branchEntries.flatMap((entry) =>
+								entry.type === "message" ? [entry.message] : [],
+							),
+						),
+				),
 			},
 		];
 	}

package/worker/pi-main.ts

@@ -12,6 +12,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
 	activeToolsExtension,
+	bridgeHistoryHidesMemory,
+	carriesMemory,
 	lastAssistant,
 	mcpAdapterExtension,
 	packageDir,
@@ -38,7 +40,11 @@ import {
 import { boundedText } from "../src/protocol.ts";
 import { WorkerCompaction } from "./pi-compaction.ts";
 import type { PiWorkerContent } from "./pi-content.ts";
-import { speakerMemoryExtension } from "./pi-memory.ts";
+import {
+	recordSandboxMemoryTurn,
+	sandboxBridgeRefusal,
+	speakerMemoryExtension,
+} from "./pi-memory.ts";
 import {
 	loadSkillIndex,
 	skillsExtension,
@@ -312,13 +318,23 @@ async function runTurn(
 	mkdirSync(outbox, { recursive: true });
 	turnContext.authorId = turn.author.id;
 	turnContext.authorName = turn.author.name;
+	turnContext.authorPrincipalId = turn.author.principalId;
+	const refusal = sandboxBridgeRefusal(session, turnContext);
+	if (refusal) return { ok: false, error: refusal };
 	turnContext.outbox = outbox;
 	turnContext.memory = turn.memory;
+	turnContext.memoryVisibility = turn.memoryVisibility;
+	const markPrivateMemory = recordSandboxMemoryTurn(
+		session.sessionManager,
+		turnContext,
+	);
 	session.setActiveToolsByName([...activeTools]);
 	session.setThinkingLevel(turn.thinking);
 	const timer = setTimeout(() => void session.abort(), TURN_TIMEOUT_MS);
 	const toolCalls: string[] = [];
 	const unsubscribe = session.subscribe((event) => {
+		if (event.type === "message_end" && carriesMemory(event.message))
+			markPrivateMemory();
 		if (event.type === "tool_execution_start") toolCalls.push(event.toolName);
 		else if (event.type === "tool_execution_end" && event.isError)
 			log("tool failed", {
@@ -414,6 +430,14 @@ async function main(): Promise<void> {
 			const ready = await fetch("http://broker/worker/ready", {
 				unix: brokerSocket,
 				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					capabilities: { privateTo: true, readerRecords: true },
+					privateHistory: bridgeHistoryHidesMemory(
+						session.sessionManager.getBranch(),
+						undefined,
+					),
+				}),
 				signal: AbortSignal.timeout(5000),
 			});
 			await ready.body?.cancel();

package/worker/pi-memory.ts

@@ -1,6 +1,46 @@
-import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionFactory,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+	bridgeHistoryHidesMemory,
+	memoryProjection,
+	privateCompaction,
+	recordMemoryTurn,
+} from "pi-roundtable/kit";
 import type { PiTurnContext } from "../src/pi-protocol.ts";
 
+/** Bridge's retained transcript bypasses projection, including exchanges Pi already compacted. */
+export function sandboxBridgeRefusal(
+	session: {
+		model: { provider: string } | undefined;
+		sessionManager: Pick<SessionManager, "getBranch">;
+	},
+	turn: PiTurnContext,
+): string | undefined {
+	if (session.model?.provider !== "claude-bridge") return undefined;
+	if (
+		!bridgeHistoryHidesMemory(
+			session.sessionManager.getBranch(),
+			turn.authorPrincipalId ?? turn.authorId,
+		)
+	)
+		return undefined;
+	return "claude-bridge cannot replay another reader's private-memory turns or private exchanges hidden from this sandbox reader; use another provider or a fresh conversation";
+}
+
+/** Record the declared privacy of the host's prompt block before any worker provider call. */
+export function recordSandboxMemoryTurn(
+	manager: Pick<SessionManager, "appendCustomEntry">,
+	turn: PiTurnContext,
+): () => void {
+	return recordMemoryTurn(
+		manager,
+		turn.authorPrincipalId ?? turn.authorId,
+		turn.memoryVisibility !== "shared" && turn.memory.length > 0,
+	);
+}
+
 /**
  * Adds what the channel keeps about the current speaker to this run's system prompt. The
  * prompt is rebuilt every run, so the session history never piles up stale copies.
@@ -9,6 +49,24 @@ export function speakerMemoryExtension(
 	turn: () => PiTurnContext,
 ): ExtensionFactory {
 	return (pi) => {
+		// Sandbox sessions bypass the core SessionFactory; apply its shared-history projection here.
+		pi.on("context_with_system", (event) => {
+			const current = turn();
+			const messages = memoryProjection(event.messages, {
+				shared: true,
+				reader: current.authorPrincipalId ?? current.authorId,
+			});
+			return messages ? { messages } : undefined;
+		});
+		// Registered before custom compactors, also protecting Pi's built-in fallback.
+		pi.on("session_before_compact", (event) =>
+			privateCompaction(
+				event.preparation,
+				event.branchEntries.flatMap((entry) =>
+					entry.type === "message" ? [entry.message] : [],
+				),
+			),
+		);
 		pi.on("before_agent_start", (event) => {
 			const { memory } = turn();
 			if (!memory) return;

package/worker/pi-tools.ts

@@ -133,7 +133,13 @@ export function brokerToolsExtension(
 					const body = JSON.parse(
 						await boundedText(response.body, 32 * 1024 * 1024),
 					) as PiToolResponse;
-					if (!body.ok) throw new Error(body.error ?? "Host tool failed");
+					if (
+						body.privateTo !== undefined &&
+						(typeof body.privateTo !== "string" ||
+							body.privateTo.length === 0 ||
+							body.privateTo.length > 256)
+					)
+						throw new Error("Invalid private tool owner");
 					if (body.image) {
 						validateImages([body.image]);
 						saveToOutbox(
@@ -142,7 +148,16 @@ export function brokerToolsExtension(
 							Buffer.from(body.image.data, "base64"),
 						);
 					}
-					return toolText(body.text ?? "");
+					return {
+						...toolText(
+							body.ok ? (body.text ?? "") : (body.error ?? "Host tool failed"),
+						),
+						isError: !body.ok,
+						details:
+							body.privateTo === undefined
+								? undefined
+								: { privateTo: body.privateTo },
+					};
 				},
 			});
 	};