@electric-ax/agents-server 0.4.14 → 0.4.16

package/dist/index.js

@@ -5,15 +5,15 @@ import { fileURLToPath } from "node:url";
 import { drizzle } from "drizzle-orm/postgres-js";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
-import { and, desc, eq, lt, ne, sql } from "drizzle-orm";
+import { and, desc, eq, inArray, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from "node:crypto";
-import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForTags, verifyWebhookSignature } from "@electric-ax/agents-runtime";
 import { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
-import fastq from "fastq";
 import { Type } from "@sinclair/typebox";
+import fastq from "fastq";
 import Ajv from "ajv";
 import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
 import { AutoRouter, Router, json, status, withParams } from "itty-router";
@@ -26,11 +26,16 @@ __export(schema_exports, {
 	entities: () => entities,
 	entityBridges: () => entityBridges,
 	entityDispatchState: () => entityDispatchState,
+	entityEffectivePermissions: () => entityEffectivePermissions,
+	entityLineage: () => entityLineage,
 	entityManifestSources: () => entityManifestSources,
+	entityPermissionGrants: () => entityPermissionGrants,
+	entityTypePermissionGrants: () => entityTypePermissionGrants,
 	entityTypes: () => entityTypes,
 	runnerRuntimeDiagnostics: () => runnerRuntimeDiagnostics,
 	runners: () => runners,
 	scheduledTasks: () => scheduledTasks,
+	sharedStateLinks: () => sharedStateLinks,
 	subscriptionWebhooks: () => subscriptionWebhooks,
 	tagStreamOutbox: () => tagStreamOutbox,
 	users: () => users,
@@ -61,6 +66,7 @@ const entities = pgTable(`entities`, {
 	tags: jsonb(`tags`).notNull().default({}),
 	tagsIndex: text(`tags_index`).array().notNull().default(sql`'{}'::text[]`),
 	spawnArgs: jsonb(`spawn_args`).default({}),
+	sandbox: jsonb(`sandbox`),
 	parent: text(`parent`),
 	createdBy: text(`created_by`),
 	typeRevision: integer(`type_revision`),
@@ -77,6 +83,94 @@ const entities = pgTable(`entities`, {
 	index(`entities_tags_index_gin`).using(`gin`, table.tagsIndex),
 	check(`chk_entities_status`, sql`${table.status} IN ('spawning', 'running', 'idle', 'paused', 'stopping', 'stopped', 'killed')`)
 ]);
+const entityTypePermissionGrants = pgTable(`entity_type_permission_grants`, {
+	id: bigserial(`id`, { mode: `number` }).primaryKey(),
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	entityType: text(`entity_type`).notNull(),
+	permission: text(`permission`).notNull(),
+	subjectKind: text(`subject_kind`).notNull(),
+	subjectValue: text(`subject_value`).notNull(),
+	createdBy: text(`created_by`),
+	expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	index(`idx_type_permission_grants_lookup`).on(table.tenantId, table.entityType, table.permission, table.subjectKind, table.subjectValue),
+	index(`idx_type_permission_grants_expiry`).on(table.tenantId, table.expiresAt),
+	check(`chk_type_permission_grants_permission`, sql`${table.permission} IN ('spawn', 'manage')`),
+	check(`chk_type_permission_grants_subject_kind`, sql`${table.subjectKind} IN ('principal', 'principal_kind')`)
+]);
+const entityLineage = pgTable(`entity_lineage`, {
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	ancestorUrl: text(`ancestor_url`).notNull(),
+	descendantUrl: text(`descendant_url`).notNull(),
+	depth: integer(`depth`).notNull(),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	primaryKey({ columns: [
+		table.tenantId,
+		table.ancestorUrl,
+		table.descendantUrl
+	] }),
+	index(`idx_entity_lineage_descendant`).on(table.tenantId, table.descendantUrl),
+	check(`chk_entity_lineage_depth`, sql`${table.depth} >= 0`)
+]);
+const entityPermissionGrants = pgTable(`entity_permission_grants`, {
+	id: bigserial(`id`, { mode: `number` }).primaryKey(),
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	entityUrl: text(`entity_url`).notNull(),
+	permission: text(`permission`).notNull(),
+	subjectKind: text(`subject_kind`).notNull(),
+	subjectValue: text(`subject_value`).notNull(),
+	propagation: text(`propagation`).notNull().default(`self`),
+	copyToChildren: boolean(`copy_to_children`).notNull().default(false),
+	createdBy: text(`created_by`),
+	expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	index(`idx_entity_permission_grants_entity`).on(table.tenantId, table.entityUrl),
+	index(`idx_entity_permission_grants_subject`).on(table.tenantId, table.permission, table.subjectKind, table.subjectValue),
+	index(`idx_entity_permission_grants_expiry`).on(table.tenantId, table.expiresAt),
+	check(`chk_entity_permission_grants_permission`, sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`),
+	check(`chk_entity_permission_grants_subject_kind`, sql`${table.subjectKind} IN ('principal', 'principal_kind')`),
+	check(`chk_entity_permission_grants_propagation`, sql`${table.propagation} IN ('self', 'descendants')`)
+]);
+const entityEffectivePermissions = pgTable(`entity_effective_permissions`, {
+	id: bigserial(`id`, { mode: `number` }).primaryKey(),
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	entityUrl: text(`entity_url`).notNull(),
+	sourceEntityUrl: text(`source_entity_url`).notNull(),
+	sourceGrantId: bigint(`source_grant_id`, { mode: `number` }).notNull(),
+	permission: text(`permission`).notNull(),
+	subjectKind: text(`subject_kind`).notNull(),
+	subjectValue: text(`subject_value`).notNull(),
+	expiresAt: timestamp(`expires_at`, { withTimezone: true }),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	unique(`uq_entity_effective_permission`).on(table.tenantId, table.entityUrl, table.sourceGrantId),
+	index(`idx_entity_effective_permissions_lookup`).on(table.tenantId, table.permission, table.subjectKind, table.subjectValue, table.entityUrl),
+	index(`idx_entity_effective_permissions_entity`).on(table.tenantId, table.entityUrl),
+	index(`idx_entity_effective_permissions_expiry`).on(table.tenantId, table.expiresAt),
+	check(`chk_entity_effective_permissions_permission`, sql`${table.permission} IN ('read', 'write', 'delete', 'signal', 'fork', 'schedule', 'spawn', 'manage')`),
+	check(`chk_entity_effective_permissions_subject_kind`, sql`${table.subjectKind} IN ('principal', 'principal_kind')`)
+]);
+const sharedStateLinks = pgTable(`shared_state_links`, {
+	tenantId: text(`tenant_id`).notNull().default(`default`),
+	sharedStateId: text(`shared_state_id`).notNull(),
+	ownerEntityUrl: text(`owner_entity_url`).notNull(),
+	manifestKey: text(`manifest_key`).notNull(),
+	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	primaryKey({ columns: [
+		table.tenantId,
+		table.ownerEntityUrl,
+		table.manifestKey
+	] }),
+	index(`idx_shared_state_links_shared_state`).on(table.tenantId, table.sharedStateId),
+	index(`idx_shared_state_links_owner`).on(table.tenantId, table.ownerEntityUrl)
+]);
 const users = pgTable(`users`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	id: text(`id`).notNull(),
@@ -102,6 +196,7 @@ const runners = pgTable(`runners`, {
 	kind: text(`kind`).notNull().default(`local`),
 	adminStatus: text(`admin_status`).notNull().default(`enabled`),
 	wakeStream: text(`wake_stream`).notNull(),
+	sandboxProfiles: jsonb(`sandbox_profiles`).notNull().default([]),
 	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
@@ -262,12 +357,18 @@ const entityBridges = pgTable(`entity_bridges`, {
 	sourceRef: text(`source_ref`).notNull(),
 	tags: jsonb(`tags`).notNull(),
 	streamUrl: text(`stream_url`).notNull(),
+	principalUrl: text(`principal_url`),
+	principalKind: text(`principal_kind`),
 	shapeHandle: text(`shape_handle`),
 	shapeOffset: text(`shape_offset`),
 	lastObserverActivityAt: timestamp(`last_observer_activity_at`, { withTimezone: true }).notNull().defaultNow(),
 	createdAt: timestamp(`created_at`, { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp(`updated_at`, { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.tenantId, table.sourceRef] }), unique(`uq_entity_bridges_stream_url`).on(table.tenantId, table.streamUrl)]);
+}, (table) => [
+	primaryKey({ columns: [table.tenantId, table.sourceRef] }),
+	unique(`uq_entity_bridges_stream_url`).on(table.tenantId, table.streamUrl),
+	index(`idx_entity_bridges_principal`).on(table.tenantId, table.principalKind, table.principalUrl)
+]);
 const entityManifestSources = pgTable(`entity_manifest_sources`, {
 	tenantId: text(`tenant_id`).notNull().default(`default`),
 	ownerEntityUrl: text(`owner_entity_url`).notNull(),
@@ -399,6 +500,7 @@ function toPublicEntity(entity) {
 		dispatch_policy: entity.dispatch_policy,
 		tags: entity.tags,
 		spawn_args: entity.spawn_args,
+		sandbox: entity.sandbox,
 		parent: entity.parent,
 		created_by: entity.created_by,
 		created_at: entity.created_at,
@@ -454,19 +556,35 @@ function isDuplicateUrlError(err) {
 	return e.code === `23505`;
 }
 const DEFAULT_RUNNER_LEASE_MS = 3e4;
+const PERMISSION_PRUNE_INTERVAL_MS = 3e4;
 function runnerWakeStream(runnerId) {
 	return `/runners/${runnerId}/wake`;
 }
 var PostgresRegistry = class {
+	lastPermissionPruneStartedAt = 0;
+	permissionPrunePromise = null;
 	constructor(db, tenantId = DEFAULT_TENANT_ID) {
 		this.db = db;
 		this.tenantId = tenantId;
 	}
 	async initialize() {}
 	close() {}
+	async ensureUserForPrincipal(principal) {
+		if (principal.kind !== `user`) return;
+		await this.db.insert(users).values({
+			tenantId: this.tenantId,
+			id: principal.id
+		}).onConflictDoNothing();
+	}
 	async createRunner(input) {
 		const now = new Date();
 		const wakeStream = input.wakeStream ?? runnerWakeStream(input.id);
+		const sandboxProfilesValue = input.sandboxProfiles ? input.sandboxProfiles.map((p) => ({
+			name: p.name,
+			label: p.label,
+			...p.description !== void 0 && { description: p.description },
+			...p.remote !== void 0 && { remote: p.remote }
+		})) : void 0;
 		await this.db.insert(runners).values({
 			tenantId: this.tenantId,
 			id: input.id,
@@ -475,6 +593,7 @@ var PostgresRegistry = class {
 			kind: input.kind ?? `local`,
 			adminStatus: input.adminStatus ?? `enabled`,
 			wakeStream,
+			...sandboxProfilesValue !== void 0 && { sandboxProfiles: sandboxProfilesValue },
 			updatedAt: now
 		}).onConflictDoUpdate({
 			target: [runners.tenantId, runners.id],
@@ -484,6 +603,7 @@ var PostgresRegistry = class {
 				kind: input.kind ?? `local`,
 				adminStatus: input.adminStatus ?? `enabled`,
 				wakeStream,
+				...sandboxProfilesValue !== void 0 && { sandboxProfiles: sandboxProfilesValue },
 				updatedAt: now
 			}
 		});
@@ -491,6 +611,30 @@ var PostgresRegistry = class {
 		if (!runner) throw new Error(`Failed to read back runner "${input.id}"`);
 		return runner;
 	}
+	/**
+	* Every sandbox profile advertised by a runner in this tenant (one entry
+	* per runner that advertises it — names may repeat across runners). Used by
+	* spawn validation for unpinned dispatch to learn whether a chosen profile
+	* is remote (so a shared sandbox can skip the single-runner guard).
+	*/
+	async listSandboxProfiles() {
+		const rows = await this.db.select({ sandboxProfiles: runners.sandboxProfiles }).from(runners).where(eq(runners.tenantId, this.tenantId));
+		const profiles = [];
+		for (const row of rows) {
+			const list = row.sandboxProfiles;
+			if (!Array.isArray(list)) continue;
+			for (const entry of list) {
+				if (!entry || typeof entry.name !== `string`) continue;
+				profiles.push({
+					name: entry.name,
+					label: typeof entry.label === `string` ? entry.label : entry.name,
+					...typeof entry.description === `string` && { description: entry.description },
+					...typeof entry.remote === `boolean` && { remote: entry.remote }
+				});
+			}
+		}
+		return profiles;
+	}
 	async getRunner(id) {
 		const rows = await this.db.select().from(runners).where(and(eq(runners.tenantId, this.tenantId), eq(runners.id, id))).limit(1);
 		return rows[0] ? this.rowToRunner(rows[0]) : null;
@@ -751,6 +895,7 @@ var PostgresRegistry = class {
 					tags: normalizeTags(entity.tags),
 					tagsIndex: buildTagsIndex(entity.tags),
 					spawnArgs: entity.spawn_args ?? {},
+					sandbox: entity.sandbox ?? null,
 					parent: entity.parent ?? null,
 					createdBy: entity.created_by ?? null,
 					typeRevision: entity.type_revision ?? null,
@@ -765,6 +910,59 @@ var PostgresRegistry = class {
 					pendingSourceStreams: [],
 					updatedAt: new Date()
 				}).onConflictDoNothing();
+				await tx.insert(entityLineage).values({
+					tenantId: this.tenantId,
+					ancestorUrl: entity.url,
+					descendantUrl: entity.url,
+					depth: 0
+				}).onConflictDoNothing();
+				if (entity.parent) await tx.execute(sql`
+            INSERT INTO ${entityLineage} (
+              tenant_id,
+              ancestor_url,
+              descendant_url,
+              depth
+            )
+            SELECT
+              ${this.tenantId},
+              ancestor_url,
+              ${entity.url},
+              depth + 1
+            FROM ${entityLineage}
+            WHERE tenant_id = ${this.tenantId}
+              AND descendant_url = ${entity.parent}
+            ON CONFLICT DO NOTHING
+          `);
+				await tx.execute(sql`
+          INSERT INTO ${entityEffectivePermissions} (
+            tenant_id,
+            entity_url,
+            source_entity_url,
+            source_grant_id,
+            permission,
+            subject_kind,
+            subject_value,
+            expires_at
+          )
+          SELECT
+            ${this.tenantId},
+            ${entity.url},
+            grants.entity_url,
+            grants.id,
+            grants.permission,
+            grants.subject_kind,
+            grants.subject_value,
+            grants.expires_at
+          FROM ${entityPermissionGrants} grants
+          JOIN ${entityLineage} lineage
+            ON lineage.tenant_id = grants.tenant_id
+           AND lineage.ancestor_url = grants.entity_url
+           AND lineage.descendant_url = ${entity.url}
+          WHERE grants.tenant_id = ${this.tenantId}
+            AND grants.propagation = 'descendants'
+            AND (grants.expires_at IS NULL OR grants.expires_at > now())
+          ON CONFLICT DO NOTHING
+        `);
 				return parseInt(result[0].txid);
 			});
 		} catch (err) {
@@ -786,10 +984,8 @@ var PostgresRegistry = class {
 	}
 	async getEntityByStream(streamPath) {
 		const mainSuffix = `/main`;
-		const errorSuffix = `/error`;
 		let entityUrl = null;
 		if (streamPath.endsWith(mainSuffix)) entityUrl = streamPath.slice(0, -mainSuffix.length);
-		else if (streamPath.endsWith(errorSuffix)) entityUrl = streamPath.slice(0, -errorSuffix.length);
 		if (!entityUrl) return null;
 		return this.getEntity(entityUrl);
 	}
@@ -799,6 +995,23 @@ var PostgresRegistry = class {
 		if (filter?.status) conditions.push(eq(entities.status, filter.status));
 		if (filter?.parent) conditions.push(eq(entities.parent, filter.parent));
 		if (filter?.created_by) conditions.push(eq(entities.createdBy, filter.created_by));
+		if (filter?.readableBy && !filter.readableBy.bypass) conditions.push(sql`(
+        ${entities.createdBy} = ${filter.readableBy.principalUrl}
+        OR ${entities.url} IN (
+          SELECT ${entityEffectivePermissions.entityUrl}
+          FROM ${entityEffectivePermissions}
+          WHERE ${entityEffectivePermissions.tenantId} = ${this.tenantId}
+            AND ${entityEffectivePermissions.permission} IN ('read', 'manage')
+            AND (${entityEffectivePermissions.expiresAt} IS NULL OR ${entityEffectivePermissions.expiresAt} > now())
+            AND (
+              (${entityEffectivePermissions.subjectKind} = 'principal'
+                AND ${entityEffectivePermissions.subjectValue} = ${filter.readableBy.principalUrl})
+              OR
+              (${entityEffectivePermissions.subjectKind} = 'principal_kind'
+                AND ${entityEffectivePermissions.subjectValue} = ${filter.readableBy.principalKind})
+            )
+        )
+      )`);
 		const whereClause = and(...conditions);
 		const countResult = await this.db.select({ count: sql`count(*)` }).from(entities).where(whereClause);
 		const total = Number(countResult[0].count);
@@ -811,6 +1024,189 @@ var PostgresRegistry = class {
 			total
 		};
 	}
+	async createEntityTypePermissionGrant(input) {
+		const [row] = await this.db.insert(entityTypePermissionGrants).values({
+			tenantId: this.tenantId,
+			entityType: input.entityType,
+			permission: input.permission,
+			subjectKind: input.subjectKind,
+			subjectValue: input.subjectValue,
+			createdBy: input.createdBy ?? null,
+			expiresAt: input.expiresAt ?? null
+		}).returning();
+		return this.rowToEntityTypePermissionGrant(row);
+	}
+	async ensureEntityTypePermissionGrant(input) {
+		const [existing] = await this.db.select().from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, input.entityType), eq(entityTypePermissionGrants.permission, input.permission), eq(entityTypePermissionGrants.subjectKind, input.subjectKind), eq(entityTypePermissionGrants.subjectValue, input.subjectValue), input.expiresAt ? eq(entityTypePermissionGrants.expiresAt, input.expiresAt) : sql`${entityTypePermissionGrants.expiresAt} IS NULL`)).limit(1);
+		if (existing) return this.rowToEntityTypePermissionGrant(existing);
+		return await this.createEntityTypePermissionGrant(input);
+	}
+	async listEntityTypePermissionGrants(entityType) {
+		const rows = await this.db.select().from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType))).orderBy(entityTypePermissionGrants.id);
+		return rows.map((row) => this.rowToEntityTypePermissionGrant(row));
+	}
+	async deleteEntityTypePermissionGrant(entityType, grantId) {
+		const rows = await this.db.delete(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType), eq(entityTypePermissionGrants.id, grantId))).returning({ id: entityTypePermissionGrants.id });
+		return rows.length > 0;
+	}
+	async hasEntityTypePermission(entityType, permission, subject) {
+		const permissions = [permission, `manage`];
+		const rows = await this.db.select({ id: entityTypePermissionGrants.id }).from(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), eq(entityTypePermissionGrants.entityType, entityType), inArray(entityTypePermissionGrants.permission, [...permissions]), sql`(${entityTypePermissionGrants.expiresAt} IS NULL OR ${entityTypePermissionGrants.expiresAt} > now())`, sql`(
+            (${entityTypePermissionGrants.subjectKind} = 'principal'
+              AND ${entityTypePermissionGrants.subjectValue} = ${subject.principalUrl})
+            OR
+            (${entityTypePermissionGrants.subjectKind} = 'principal_kind'
+              AND ${entityTypePermissionGrants.subjectValue} = ${subject.principalKind})
+          )`)).limit(1);
+		return rows.length > 0;
+	}
+	async createEntityPermissionGrant(input) {
+		return await this.db.transaction(async (tx) => {
+			const [row] = await tx.insert(entityPermissionGrants).values({
+				tenantId: this.tenantId,
+				entityUrl: input.entityUrl,
+				permission: input.permission,
+				subjectKind: input.subjectKind,
+				subjectValue: input.subjectValue,
+				propagation: input.propagation ?? `self`,
+				copyToChildren: input.copyToChildren ?? false,
+				createdBy: input.createdBy ?? null,
+				expiresAt: input.expiresAt ?? null
+			}).returning();
+			await this.materializeEntityPermissionGrant(tx, row);
+			return this.rowToEntityPermissionGrant(row);
+		});
+	}
+	async listEntityPermissionGrants(entityUrl) {
+		const rows = await this.db.select().from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, entityUrl))).orderBy(entityPermissionGrants.id);
+		return rows.map((row) => this.rowToEntityPermissionGrant(row));
+	}
+	async deleteEntityPermissionGrant(entityUrl, grantId) {
+		return await this.db.transaction(async (tx) => {
+			await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.sourceGrantId, grantId)));
+			const rows = await tx.delete(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, entityUrl), eq(entityPermissionGrants.id, grantId))).returning({ id: entityPermissionGrants.id });
+			return rows.length > 0;
+		});
+	}
+	async copyEntityPermissionGrantsForSpawn(parentEntityUrl, childEntityUrl, createdBy) {
+		const parentGrants = await this.db.select().from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), eq(entityPermissionGrants.entityUrl, parentEntityUrl), eq(entityPermissionGrants.copyToChildren, true), sql`(${entityPermissionGrants.expiresAt} IS NULL OR ${entityPermissionGrants.expiresAt} > now())`));
+		const copied = [];
+		for (const grant of parentGrants) copied.push(await this.createEntityPermissionGrant({
+			entityUrl: childEntityUrl,
+			permission: grant.permission,
+			subjectKind: grant.subjectKind,
+			subjectValue: grant.subjectValue,
+			propagation: `self`,
+			copyToChildren: grant.copyToChildren,
+			createdBy,
+			expiresAt: grant.expiresAt ?? void 0
+		}));
+		return copied;
+	}
+	async hasEntityPermission(entityUrl, permission, subject) {
+		const permissions = [permission, `manage`];
+		const rows = await this.db.select({ id: entityEffectivePermissions.id }).from(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.entityUrl, entityUrl), inArray(entityEffectivePermissions.permission, [...permissions]), sql`(${entityEffectivePermissions.expiresAt} IS NULL OR ${entityEffectivePermissions.expiresAt} > now())`, sql`(
+            (${entityEffectivePermissions.subjectKind} = 'principal'
+              AND ${entityEffectivePermissions.subjectValue} = ${subject.principalUrl})
+            OR
+            (${entityEffectivePermissions.subjectKind} = 'principal_kind'
+              AND ${entityEffectivePermissions.subjectValue} = ${subject.principalKind})
+          )`)).limit(1);
+		return rows.length > 0;
+	}
+	async replaceSharedStateLink(ownerEntityUrl, manifestKey, sharedStateId) {
+		await this.db.delete(sharedStateLinks).where(and(eq(sharedStateLinks.tenantId, this.tenantId), eq(sharedStateLinks.ownerEntityUrl, ownerEntityUrl), eq(sharedStateLinks.manifestKey, manifestKey)));
+		if (!sharedStateId) return;
+		await this.db.insert(sharedStateLinks).values({
+			tenantId: this.tenantId,
+			ownerEntityUrl,
+			manifestKey,
+			sharedStateId
+		}).onConflictDoUpdate({
+			target: [
+				sharedStateLinks.tenantId,
+				sharedStateLinks.ownerEntityUrl,
+				sharedStateLinks.manifestKey
+			],
+			set: {
+				sharedStateId,
+				updatedAt: new Date()
+			}
+		});
+	}
+	async listSharedStateLinkedEntityUrls(sharedStateId) {
+		const rows = await this.db.selectDistinct({ ownerEntityUrl: sharedStateLinks.ownerEntityUrl }).from(sharedStateLinks).where(and(eq(sharedStateLinks.tenantId, this.tenantId), eq(sharedStateLinks.sharedStateId, sharedStateId)));
+		return rows.map((row) => row.ownerEntityUrl);
+	}
+	async pruneExpiredPermissionGrants(now = new Date(), options = {}) {
+		if (this.permissionPrunePromise) return await this.permissionPrunePromise;
+		const startedAt = Date.now();
+		if (!options.force && startedAt - this.lastPermissionPruneStartedAt < PERMISSION_PRUNE_INTERVAL_MS) return;
+		this.lastPermissionPruneStartedAt = startedAt;
+		const promise = this.pruneExpiredPermissionGrantsNow(now);
+		this.permissionPrunePromise = promise;
+		try {
+			await promise;
+		} catch (error) {
+			this.lastPermissionPruneStartedAt = 0;
+			throw error;
+		} finally {
+			if (this.permissionPrunePromise === promise) this.permissionPrunePromise = null;
+		}
+	}
+	async pruneExpiredPermissionGrantsNow(now) {
+		await this.db.transaction(async (tx) => {
+			const expiredEntityGrantIds = await tx.select({ id: entityPermissionGrants.id }).from(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), sql`${entityPermissionGrants.expiresAt} IS NOT NULL`, lt(entityPermissionGrants.expiresAt, now)));
+			const ids = expiredEntityGrantIds.map((row) => row.id);
+			if (ids.length > 0) {
+				await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), inArray(entityEffectivePermissions.sourceGrantId, ids)));
+				await tx.delete(entityPermissionGrants).where(and(eq(entityPermissionGrants.tenantId, this.tenantId), inArray(entityPermissionGrants.id, ids)));
+			}
+			await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), sql`${entityEffectivePermissions.expiresAt} IS NOT NULL`, lt(entityEffectivePermissions.expiresAt, now)));
+			await tx.delete(entityTypePermissionGrants).where(and(eq(entityTypePermissionGrants.tenantId, this.tenantId), sql`${entityTypePermissionGrants.expiresAt} IS NOT NULL`, lt(entityTypePermissionGrants.expiresAt, now)));
+		});
+	}
+	async materializeEntityPermissionGrant(tx, grant) {
+		await tx.delete(entityEffectivePermissions).where(and(eq(entityEffectivePermissions.tenantId, this.tenantId), eq(entityEffectivePermissions.sourceGrantId, grant.id)));
+		if (grant.propagation === `descendants`) {
+			await tx.execute(sql`
+        INSERT INTO ${entityEffectivePermissions} (
+          tenant_id,
+          entity_url,
+          source_entity_url,
+          source_grant_id,
+          permission,
+          subject_kind,
+          subject_value,
+          expires_at
+        )
+        SELECT
+          ${this.tenantId},
+          descendant_url,
+          ${grant.entityUrl},
+          ${grant.id},
+          ${grant.permission},
+          ${grant.subjectKind},
+          ${grant.subjectValue},
+          ${grant.expiresAt}
+        FROM ${entityLineage}
+        WHERE tenant_id = ${this.tenantId}
+          AND ancestor_url = ${grant.entityUrl}
+        ON CONFLICT DO NOTHING
+      `);
+			return;
+		}
+		await tx.insert(entityEffectivePermissions).values({
+			tenantId: this.tenantId,
+			entityUrl: grant.entityUrl,
+			sourceEntityUrl: grant.entityUrl,
+			sourceGrantId: grant.id,
+			permission: grant.permission,
+			subjectKind: grant.subjectKind,
+			subjectValue: grant.subjectValue,
+			expiresAt: grant.expiresAt
+		}).onConflictDoNothing();
+	}
 	async updateStatus(entityUrl, status$1) {
 		const whereClause = isTerminalEntityStatus(status$1) ? this.entityWhere(entityUrl) : and(this.entityWhere(entityUrl), ne(entities.status, `stopped`), ne(entities.status, `killed`));
 		await this.db.update(entities).set({
@@ -912,7 +1308,9 @@ var PostgresRegistry = class {
 			tenantId: this.tenantId,
 			sourceRef: row.sourceRef,
 			tags: normalizeTags(row.tags),
-			streamUrl: row.streamUrl
+			streamUrl: row.streamUrl,
+			principalUrl: row.principalUrl,
+			principalKind: row.principalKind
 		}).onConflictDoNothing();
 		const existing = await this.getEntityBridge(row.sourceRef);
 		if (!existing) throw new Error(`Failed to load entity bridge ${row.sourceRef}`);
@@ -1074,20 +1472,46 @@ var PostgresRegistry = class {
 			updated_at: row.updatedAt
 		};
 	}
+	rowToEntityTypePermissionGrant(row) {
+		return {
+			id: row.id,
+			entity_type: row.entityType,
+			permission: row.permission,
+			subject_kind: row.subjectKind,
+			subject_value: row.subjectValue,
+			created_by: row.createdBy ?? void 0,
+			expires_at: row.expiresAt?.toISOString(),
+			created_at: row.createdAt.toISOString(),
+			updated_at: row.updatedAt.toISOString()
+		};
+	}
+	rowToEntityPermissionGrant(row) {
+		return {
+			id: row.id,
+			entity_url: row.entityUrl,
+			permission: row.permission,
+			subject_kind: row.subjectKind,
+			subject_value: row.subjectValue,
+			propagation: row.propagation,
+			copy_to_children: row.copyToChildren,
+			created_by: row.createdBy ?? void 0,
+			expires_at: row.expiresAt?.toISOString(),
+			created_at: row.createdAt.toISOString(),
+			updated_at: row.updatedAt.toISOString()
+		};
+	}
 	rowToEntity(row) {
 		return {
 			url: row.url,
 			type: row.type,
 			status: assertEntityStatus(row.status),
-			streams: {
-				main: `${row.url}/main`,
-				error: `${row.url}/error`
-			},
+			streams: { main: `${row.url}/main` },
 			subscription_id: row.subscriptionId,
 			dispatch_policy: row.dispatchPolicy ?? void 0,
 			write_token: row.writeToken,
 			tags: row.tags ?? {},
 			spawn_args: row.spawnArgs,
+			sandbox: row.sandbox ?? void 0,
 			parent: row.parent ?? void 0,
 			created_by: row.createdBy ?? void 0,
 			type_revision: row.typeRevision ?? void 0,
@@ -1103,6 +1527,8 @@ var PostgresRegistry = class {
 			sourceRef: row.sourceRef,
 			tags: row.tags ?? {},
 			streamUrl: row.streamUrl,
+			principalUrl: row.principalUrl ?? void 0,
+			principalKind: row.principalKind ?? void 0,
 			shapeHandle: row.shapeHandle ?? void 0,
 			shapeOffset: row.shapeOffset ?? void 0,
 			lastObserverActivityAt: row.lastObserverActivityAt,
@@ -1135,6 +1561,7 @@ var PostgresRegistry = class {
 			kind: assertRunnerKind(row.kind),
 			admin_status: assertRunnerAdminStatus(row.adminStatus),
 			wake_stream: row.wakeStream,
+			sandbox_profiles: row.sandboxProfiles ?? [],
 			created_at: row.createdAt.toISOString(),
 			updated_at: row.updatedAt.toISOString()
 		};
@@ -1256,6 +1683,93 @@ const serverLog = {
 	}
 };
 
+//#endregion
+//#region src/principal.ts
+const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
+const PRINCIPAL_KINDS = new Set([
+	`user`,
+	`agent`,
+	`service`,
+	`system`
+]);
+function parsePrincipalKey(input) {
+	const colon = input.indexOf(`:`);
+	if (colon <= 0) throw new Error(`Invalid principal identifier`);
+	const kind = input.slice(0, colon);
+	const id = input.slice(colon + 1);
+	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
+	if (!id || id.includes(`/`)) throw new Error(`Invalid principal id`);
+	const key = `${kind}:${id}`;
+	return {
+		kind,
+		id,
+		key,
+		url: `/principal/${encodeURIComponent(key)}`
+	};
+}
+function principalUrl(key) {
+	return parsePrincipalKey(key).url;
+}
+function parsePrincipalUrl(url) {
+	if (!url.startsWith(`/principal/`)) return null;
+	const segment = url.slice(`/principal/`.length);
+	if (!segment || segment.includes(`/`)) return null;
+	try {
+		return parsePrincipalKey(decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+}
+const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
+	`framework`,
+	`auth-sync`,
+	`dev-local`
+]);
+function isBuiltInSystemPrincipalUrl(url) {
+	if (!url?.startsWith(`/principal/`)) return false;
+	try {
+		const principal = parsePrincipalUrl(url);
+		if (!principal) return false;
+		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
+	} catch {
+		return false;
+	}
+}
+function principalFromCreatedBy(createdBy) {
+	if (!createdBy) return void 0;
+	const principal = parsePrincipalUrl(createdBy);
+	if (!principal) return {
+		url: createdBy,
+		key: null
+	};
+	return {
+		url: principal.url,
+		key: principal.key,
+		kind: principal.kind,
+		id: principal.id
+	};
+}
+const principalIdentityStateSchema = Type.Object({
+	kind: Type.Union([
+		Type.Literal(`user`),
+		Type.Literal(`agent`),
+		Type.Literal(`service`),
+		Type.Literal(`system`)
+	]),
+	id: Type.String(),
+	key: Type.String(),
+	url: Type.String(),
+	updated_at: Type.String(),
+	display_name: Type.Optional(Type.String()),
+	email: Type.Optional(Type.String()),
+	avatar_url: Type.Optional(Type.String()),
+	auth_provider: Type.Optional(Type.String()),
+	auth_subject: Type.Optional(Type.String()),
+	claims: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	created_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
+const principalUpdateIdentityMessageSchema = Type.Object({ identity: principalIdentityStateSchema }, { additionalProperties: false });
+
 //#endregion
 //#region src/entity-projector.ts
 const ENTITY_SHAPE_COLUMNS = [
@@ -1264,7 +1778,9 @@ const ENTITY_SHAPE_COLUMNS = [
 	`type`,
 	`status`,
 	`tags`,
+	`created_by`,
 	`spawn_args`,
+	`sandbox`,
 	`parent`,
 	`type_revision`,
 	`inbox_schemas`,
@@ -1282,6 +1798,12 @@ function sourceRefFromStreamPath(streamPath) {
 	const match = streamPath.match(/^\/_entities\/([^/]+)$/);
 	return match?.[1] ?? null;
 }
+function principalScopedSourceRef(tagSourceRef, principalUrl$1, principalKind) {
+	return `${tagSourceRef}-${hashString(JSON.stringify({
+		principalKind,
+		principalUrl: principalUrl$1
+	}))}`;
+}
 function sameMember(left, right) {
 	return JSON.stringify(left) === JSON.stringify(right);
 }
@@ -1298,6 +1820,7 @@ function toMemberRow(entity) {
 		status: entity.status,
 		tags: entity.tags,
 		spawn_args: entity.spawn_args ?? {},
+		sandbox: entity.sandbox ?? null,
 		parent: entity.parent ?? null,
 		type_revision: entity.type_revision ?? null,
 		inbox_schemas: entity.inbox_schemas ?? null,
@@ -1311,15 +1834,22 @@ var ProjectedEntityBridge = class {
 	sourceRef;
 	tags;
 	streamUrl;
+	principalUrl;
+	principalKind;
+	permissionBypass;
 	currentMembers = new Map();
 	producer = null;
 	stopped = false;
-	constructor(row, streamClient) {
+	constructor(row, registry, streamClient) {
+		this.registry = registry;
 		this.streamClient = streamClient;
 		this.tenantId = row.tenantId;
 		this.sourceRef = row.sourceRef;
 		this.tags = normalizeTags(row.tags);
 		this.streamUrl = row.streamUrl;
+		this.principalUrl = row.principalUrl;
+		this.principalKind = row.principalKind;
+		this.permissionBypass = isBuiltInSystemPrincipalUrl(row.principalUrl);
 	}
 	async start(initialEntities) {
 		await this.ensureStream();
@@ -1333,7 +1863,7 @@ var ProjectedEntityBridge = class {
 			}
 		});
 		await this.loadCurrentMembers();
-		this.reconcile(initialEntities);
+		await this.reconcile(initialEntities);
 	}
 	async stop() {
 		this.stopped = true;
@@ -1345,12 +1875,13 @@ var ProjectedEntityBridge = class {
 			this.producer = null;
 		}
 	}
-	reconcile(entities$1) {
+	async reconcile(entities$1) {
 		if (this.stopped) return;
 		const staleMembers = new Map(this.currentMembers);
 		for (const entity of entities$1) {
 			if (entity.tenant_id !== this.tenantId) continue;
 			if (!entityMatchesTags(entity, this.tags)) continue;
+			if (!await this.canReadEntity(entity)) continue;
 			staleMembers.delete(entity.url);
 			this.upsertEntity(entity);
 		}
@@ -1359,10 +1890,10 @@ var ProjectedEntityBridge = class {
 			this.currentMembers.delete(url);
 		}
 	}
-	applyEntity(entity) {
+	async applyEntity(entity) {
 		if (this.stopped) return;
 		if (entity.tenant_id !== this.tenantId) return;
-		if (!entityMatchesTags(entity, this.tags)) {
+		if (!entityMatchesTags(entity, this.tags) || !await this.canReadEntity(entity)) {
 			const existing = this.currentMembers.get(entity.url);
 			if (!existing) return;
 			this.append(`delete`, existing);
@@ -1391,6 +1922,15 @@ var ProjectedEntityBridge = class {
 			this.currentMembers.set(entity.url, next);
 		}
 	}
+	async canReadEntity(entity) {
+		if (this.permissionBypass) return true;
+		if (!this.principalUrl || !this.principalKind) return false;
+		if (entity.created_by === this.principalUrl) return true;
+		return await this.registry.hasEntityPermission(entity.url, `read`, {
+			principalUrl: this.principalUrl,
+			principalKind: this.principalKind
+		});
+	}
 	async ensureStream() {
 		if (!await this.streamClient.exists(this.streamUrl)) await this.streamClient.create(this.streamUrl, { contentType: `application/json` });
 	}
@@ -1495,17 +2035,19 @@ var EntityProjector = class {
 		this.activeReaders.clear();
 		await Promise.all(projections.map((projection) => projection.stop()));
 	}
-	async register(tenantId, registry, tagsInput) {
+	async register(tenantId, registry, tagsInput, principalUrl$1, principalKind) {
 		if (!this.electricUrl) throw new Error(`[entity-projector] Electric URL is required for entities()`);
 		await this.start();
 		this.registries.set(tenantId, registry);
 		const tags = normalizeTags(assertTags(tagsInput));
-		const sourceRef = sourceRefForTags(tags);
+		const sourceRef = principalScopedSourceRef(sourceRefForTags(tags), principalUrl$1, principalKind);
 		const streamUrl = getEntitiesStreamPath(sourceRef);
 		const row = await registry.upsertEntityBridge({
 			sourceRef,
 			tags,
-			streamUrl
+			streamUrl,
+			principalUrl: principalUrl$1,
+			principalKind
 		});
 		await registry.touchEntityBridge(sourceRef);
 		await this.ensureProjection(row);
@@ -1534,7 +2076,11 @@ var EntityProjector = class {
 			await this.touchSourceRef(tenantId, registry, sourceRef, `read-close`);
 		};
 	}
-	async onEntityChanged(_tenantId, _entityUrl) {}
+	async onEntityChanged(tenantId, entityUrl) {
+		const entity = this.entities.get(entityKey(tenantId, entityUrl));
+		if (!entity) return;
+		for (const projection of this.projectionsForTenant(tenantId)) await projection.applyEntity(entity);
+	}
 	async loadTenantBridges(tenantId, registry = this.registryForTenant(tenantId)) {
 		if (!this.started || !this.electricUrl) return;
 		await this.loadPersistedBridgesForTenant(tenantId, registry);
@@ -1595,16 +2141,16 @@ var EntityProjector = class {
 				}
 				if (message.headers.control === `up-to-date`) {
 					this.upToDate = true;
-					this.reconcileAll();
+					await this.reconcileAll();
 					this.readyResolve?.();
 				}
 				continue;
 			}
 			if (!isChangeMessage(message)) continue;
-			this.applyChangeMessage(message);
+			await this.applyChangeMessage(message);
 		}
 	}
-	applyChangeMessage(message) {
+	async applyChangeMessage(message) {
 		const entity = message.value;
 		const key = entityKey(entity.tenant_id, entity.url);
 		if (message.headers.operation === `delete`) {
@@ -1613,7 +2159,7 @@ var EntityProjector = class {
 			return;
 		}
 		this.entities.set(key, entity);
-		if (this.upToDate) for (const projection of this.projectionsForTenant(entity.tenant_id)) projection.applyEntity(entity);
+		if (this.upToDate) for (const projection of this.projectionsForTenant(entity.tenant_id)) await projection.applyEntity(entity);
 	}
 	async loadPersistedBridges() {
 		const registry = new PostgresRegistry(this.db);
@@ -1676,7 +2222,7 @@ var EntityProjector = class {
 				}
 				throw error;
 			}
-			const projection = new ProjectedEntityBridge(row, streamClient);
+			const projection = new ProjectedEntityBridge(row, this.registryForTenant(row.tenantId), streamClient);
 			await projection.start(this.entitiesForTenant(row.tenantId));
 			this.projections.set(key, projection);
 		})().finally(() => {
@@ -1691,8 +2237,8 @@ var EntityProjector = class {
 	projectionsForTenant(tenantId) {
 		return [...this.projections.values()].filter((projection) => projection.tenantId === tenantId);
 	}
-	reconcileAll() {
-		for (const projection of this.projections.values()) projection.reconcile(this.entitiesForTenant(projection.tenantId));
+	async reconcileAll() {
+		for (const projection of this.projections.values()) await projection.reconcile(this.entitiesForTenant(projection.tenantId));
 	}
 	async touchSourceRef(tenantId, registry, sourceRef, reason) {
 		try {
@@ -1734,8 +2280,8 @@ var EntityProjectorTenantFacade = class {
 		await this.projector.start();
 	}
 	async stop() {}
-	async register(tagsInput) {
-		return await this.projector.register(this.tenantId, this.registry, tagsInput);
+	async register(tagsInput, principalUrl$1, principalKind) {
+		return await this.projector.register(this.tenantId, this.registry, tagsInput, principalUrl$1, principalKind);
 	}
 	async onEntityChanged(entityUrl) {
 		await this.projector.onEntityChanged(this.tenantId, entityUrl);
@@ -1978,7 +2524,7 @@ var StreamClient = class {
 			});
 		});
 	}
-	async fork(path$1, sourcePath) {
+	async fork(path$1, sourcePath, opts) {
 		return await withSpan(`stream.fork`, async (span) => {
 			span.setAttributes({
 				[ATTR.STREAM_PATH]: path$1,
@@ -1988,6 +2534,11 @@ var StreamClient = class {
 				"content-type": `application/json`,
 				"Stream-Forked-From": new URL(this.streamUrl(sourcePath)).pathname
 			};
+			if (opts?.forkPointer) {
+				const ZERO_OFFSET = `0000000000000000_0000000000000000`;
+				headers[`Stream-Fork-Offset`] = opts.forkPointer.offset ?? ZERO_OFFSET;
+				if (opts.forkPointer.subOffset > 0) headers[`Stream-Fork-Sub-Offset`] = String(opts.forkPointer.subOffset);
+			}
 			injectTraceHeaders(headers);
 			const response = await fetch(this.streamUrl(path$1), {
 				method: `PUT`,
@@ -2516,91 +3067,101 @@ async function linkStreamToTargetSubscription(ctx, target, entity, subscriptionI
 }
 
 //#endregion
-//#region src/principal.ts
-const ELECTRIC_PRINCIPAL_HEADER = `electric-principal`;
-const PRINCIPAL_KINDS = new Set([
-	`user`,
-	`agent`,
-	`service`,
-	`system`
-]);
-function parsePrincipalKey(input) {
-	const colon = input.indexOf(`:`);
-	if (colon <= 0) throw new Error(`Invalid principal identifier`);
-	const kind = input.slice(0, colon);
-	const id = input.slice(colon + 1);
-	if (!PRINCIPAL_KINDS.has(kind)) throw new Error(`Invalid principal kind`);
-	if (!id || id.includes(`/`)) throw new Error(`Invalid principal id`);
-	const key = `${kind}:${id}`;
+//#region src/routing/sandbox.ts
+/**
+* Resolve and validate a spawn's sandbox CHOICE into the {@link
+* EntitySandboxSelection} persisted on the entity. Sibling of
+* `dispatch-policy.ts`'s `resolveEffectiveDispatchPolicyForSpawn`: kept off the
+* EntityManager so the spawn path reads as composed resolution steps.
+*
+* Profiles are a per-runner concern: each runner advertises what it supports.
+* When the spawn pins a runner via dispatch_policy, the chosen profile must be
+* in that runner's advertised set; otherwise we'd persist an unserviceable
+* choice that fails late at first wake. For unpinned dispatch (webhook /
+* parent-inherited) we can't pick a target ahead of time, so we fall back to a
+* tenant-wide "some runner offers this" check — better than nothing.
+*/
+async function resolveSandboxForSpawn(registry, dispatchPolicy, requested, parentEntity) {
+	if (!requested) return void 0;
+	const choice = applyInheritedSandbox(requested, parentEntity);
+	if (!choice) return void 0;
+	const chosenName = choice.profile;
+	if (!chosenName) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox requires a "profile" (or "inherit": true with a parent that has a shared sandbox).`, 400);
+	const chosenIsRemote = await resolveChosenProfileRemote(registry, chosenName, dispatchPolicy);
+	assertSharedSandboxColocated(choice.key, chosenIsRemote, dispatchPolicy);
+	const selection = { profile: chosenName };
+	if (choice.key !== void 0) selection.key = choice.key;
+	else if (choice.scope !== void 0) selection.scope = choice.scope;
+	if (choice.persistent !== void 0) selection.persistent = choice.persistent;
+	if (choice.owner === false) selection.owner = false;
+	return selection;
+}
+/**
+* Resolve `inherit` against the parent's *stored* sandbox. `inherit` reuses the
+* parent's keyed sandbox as a non-owner (attach-only). It's graceful: if the
+* parent has no shareable (keyed) sandbox the child simply gets none (returns
+* `undefined`), so `spawn_worker` can always request inheritance without
+* breaking unkeyed parents. (A running parent wake resolves inherit to its live
+* explicit key in the runtime instead — this server-side path covers direct API
+* callers, where only the parent's *stored* explicit key is available.)
+*
+* For a non-inherit choice the request passes through unchanged.
+*
+* NOTE: `inherit: true` takes the parent's identity AND durability wholesale —
+* any sibling field on the request (e.g. a caller-supplied `persistent: false`)
+* is intentionally ignored, because a child attaches to the parent's existing
+* sandbox and cannot change how that sandbox is torn down. `sandboxChoiceSchema`
+* permits the `{ inherit: true, persistent: ... }` combination, so the
+* precedence is resolved here rather than rejected at the schema level.
+*/
+function applyInheritedSandbox(requested, parentEntity) {
+	if (!requested.inherit) return requested;
+	const parentKey = parentEntity?.sandbox?.key;
+	if (!parentKey) return void 0;
 	return {
-		kind,
-		id,
-		key,
-		url: `/principal/${encodeURIComponent(key)}`
+		profile: parentEntity.sandbox.profile,
+		key: parentKey,
+		persistent: parentEntity.sandbox.persistent,
+		owner: false
 	};
 }
-function principalUrl(key) {
-	return parsePrincipalKey(key).url;
-}
-function parsePrincipalUrl(url) {
-	if (!url.startsWith(`/principal/`)) return null;
-	const segment = url.slice(`/principal/`.length);
-	if (!segment || segment.includes(`/`)) return null;
-	try {
-		return parsePrincipalKey(decodeURIComponent(segment));
-	} catch {
-		return null;
-	}
-}
-const BUILT_IN_SYSTEM_PRINCIPAL_IDS = new Set([
-	`framework`,
-	`auth-sync`,
-	`dev-local`
-]);
-function isBuiltInSystemPrincipalUrl(url) {
-	if (!url?.startsWith(`/principal/`)) return false;
-	try {
-		const principal = parsePrincipalUrl(url);
-		if (!principal) return false;
-		return principal.kind === `system` && BUILT_IN_SYSTEM_PRINCIPAL_IDS.has(principal.id);
-	} catch {
-		return false;
-	}
+/**
+* Validate the chosen profile is advertised by the relevant runner(s) and
+* determine whether it is a remote (off-host) sandbox, reachable from any
+* runner. Defaults to host-local (co-location required) unless every relevant
+* advertisement marks it remote. Throws if the profile is unserviceable.
+*/
+async function resolveChosenProfileRemote(registry, chosenName, dispatchPolicy) {
+	const runnerIds = [];
+	for (const target of dispatchPolicy?.targets ?? []) if (target.type === `runner`) runnerIds.push(target.runnerId);
+	if (runnerIds.length > 0) {
+		let allRemote = true;
+		for (const runnerId of runnerIds) {
+			const runner = await registry.getRunner(runnerId);
+			const advertised = runner?.sandbox_profiles ?? [];
+			const match = advertised.find((p) => p.name === chosenName);
+			if (!match) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox profile "${chosenName}" is not advertised by runner "${runnerId}" (advertised: ${advertised.map((p) => p.name).join(`, `) || `(none)`}).`, 400);
+			if (match.remote !== true) allRemote = false;
+		}
+		return allRemote;
+	}
+	const available = await registry.listSandboxProfiles();
+	const matches = available.filter((p) => p.name === chosenName);
+	if (matches.length === 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `sandbox profile "${chosenName}" is not offered by any registered runner (available: ${[...new Set(available.map((p) => p.name))].join(`, `) || `(none)`}).`, 400);
+	return matches.every((p) => p.remote === true);
 }
-function principalFromCreatedBy(createdBy) {
-	if (!createdBy) return void 0;
-	const principal = parsePrincipalUrl(createdBy);
-	if (!principal) return {
-		url: createdBy,
-		key: null
-	};
-	return {
-		url: principal.url,
-		key: principal.key,
-		kind: principal.kind,
-		id: principal.id
-	};
+/**
+* Co-location: a shared *local* sandbox lives on one host, so every
+* collaborator must be pinned to the same single runner. Subagents inherit the
+* parent's dispatch policy, so this holds once the root is pinned. A shared
+* *remote* sandbox is reachable from any runner, so the guard does not apply.
+*/
+function assertSharedSandboxColocated(key, chosenIsRemote, dispatchPolicy) {
+	if (key === void 0 || chosenIsRemote) return;
+	const targets = dispatchPolicy?.targets ?? [];
+	const pinnedToSingleRunner = targets.length === 1 && targets[0]?.type === `runner`;
+	if (!pinnedToSingleRunner) throw new ElectricAgentsError(ErrCodeInvalidRequest, `a shared sandbox (sandbox.key / sandbox.inherit) requires the entity to be pinned to a single runner via dispatch_policy, so all collaborators share one host.`, 400);
 }
-const principalIdentityStateSchema = Type.Object({
-	kind: Type.Union([
-		Type.Literal(`user`),
-		Type.Literal(`agent`),
-		Type.Literal(`service`),
-		Type.Literal(`system`)
-	]),
-	id: Type.String(),
-	key: Type.String(),
-	url: Type.String(),
-	updated_at: Type.String(),
-	display_name: Type.Optional(Type.String()),
-	email: Type.Optional(Type.String()),
-	avatar_url: Type.Optional(Type.String()),
-	auth_provider: Type.Optional(Type.String()),
-	auth_subject: Type.Optional(Type.String()),
-	claims: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-	created_at: Type.Optional(Type.String())
-}, { additionalProperties: false });
-const principalUpdateIdentityMessageSchema = Type.Object({ identity: principalIdentityStateSchema }, { additionalProperties: false });
 
 //#endregion
 //#region src/manifest-side-effects.ts
@@ -2837,7 +3398,10 @@ var EntityManager = class {
 	}
 	async ensurePrincipal(principal) {
 		const existing = await this.registry.getEntity(principal.url);
-		if (existing) return existing;
+		if (existing) {
+			await this.ensureUserPrincipal(principal);
+			return existing;
+		}
 		await this.ensurePrincipalEntityType();
 		try {
 			const entity = await this.spawn(`principal`, {
@@ -2866,15 +3430,22 @@ var EntityManager = class {
 					updated_at: now
 				}
 			}));
+			await this.ensureUserPrincipal(principal);
 			return entity;
 		} catch (error) {
 			if (error instanceof ElectricAgentsError && error.code === ErrCodeDuplicateURL) {
 				const raced = await this.registry.getEntity(principal.url);
-				if (raced) return raced;
+				if (raced) {
+					await this.ensureUserPrincipal(principal);
+					return raced;
+				}
 			}
 			throw error;
 		}
 	}
+	async ensureUserPrincipal(principal) {
+		if (principal.kind === `user`) await this.registry.ensureUserForPrincipal(principal);
+	}
 	/**
 	* Spawn a new entity of the given type with durable streams.
 	*/
@@ -2904,7 +3475,6 @@ var EntityManager = class {
 		const writeToken = randomUUID();
 		const entityURL = typeName === `principal` ? principalUrl(instanceId) : `/${typeName}/${instanceId}`;
 		const mainPath = `${entityURL}/main`;
-		const errorPath = `${entityURL}/error`;
 		const subscriptionId = `${typeName}-handler`;
 		const spawnT0 = performance.now();
 		const existingByURL = await this.registry.getEntity(entityURL);
@@ -2915,20 +3485,19 @@ var EntityManager = class {
 			if (!parentEntity) throw new ElectricAgentsError(ErrCodeNotFound, `Parent entity "${req.parent}" not found`, 404);
 		}
 		const dispatchPolicy = req.dispatch_policy ? this.validateDispatchPolicy(req.dispatch_policy, { label: `dispatch_policy` }) : parentEntity?.dispatch_policy ? applyTypeDefaultSubscriptionScope(parentEntity.dispatch_policy, entityType.default_dispatch_policy) : entityType.default_dispatch_policy;
+		const sandbox = await resolveSandboxForSpawn(this.registry, dispatchPolicy, req.sandbox, parentEntity);
 		const now = Date.now();
 		const entityData = {
 			type: typeName,
 			status: `idle`,
 			url: entityURL,
-			streams: {
-				main: mainPath,
-				error: errorPath
-			},
+			streams: { main: mainPath },
 			subscription_id: subscriptionId,
 			dispatch_policy: dispatchPolicy,
 			write_token: writeToken,
 			tags: initialTags,
 			spawn_args: req.args,
+			sandbox,
 			type_revision: entityType.revision,
 			inbox_schemas: entityType.inbox_schemas,
 			state_schemas: entityType.state_schemas,
@@ -2975,55 +3544,43 @@ var EntityManager = class {
 		const queueEnterT0 = performance.now();
 		const queueWaiting = this.spawnPersistQueue.length();
 		const queueRunning = this.spawnPersistQueue.running();
-		const [mainStreamResult, errorStreamResult, entityResult] = await this.spawnPersistQueue.push(async () => {
+		const [mainStreamResult, entityResult] = await this.spawnPersistQueue.push(async () => {
 			let entityTxid;
 			try {
 				entityTxid = await withSpan(`db.createEntity`, () => this.registry.createEntity(entityData));
 			} catch (err) {
-				return [
-					{
-						status: `fulfilled`,
-						value: void 0
-					},
-					{
-						status: `fulfilled`,
-						value: void 0
-					},
-					{
-						status: `rejected`,
-						reason: err
-					}
-				];
+				return [{
+					status: `fulfilled`,
+					value: void 0
+				}, {
+					status: `rejected`,
+					reason: err
+				}];
 			}
-			const [mainStreamResult$1, errorStreamResult$1] = await Promise.allSettled([this.streamClient.create(mainPath, {
+			const [mainStreamResult$1] = await Promise.allSettled([this.streamClient.create(mainPath, {
 				contentType,
 				body: initialBody
-			}), this.streamClient.create(errorPath, { contentType })]);
-			return [
-				mainStreamResult$1,
-				errorStreamResult$1,
-				{
-					status: `fulfilled`,
-					value: entityTxid
-				}
-			];
+			})]);
+			return [mainStreamResult$1, {
+				status: `fulfilled`,
+				value: entityTxid
+			}];
 		});
 		const parallelMs = +(performance.now() - queueEnterT0).toFixed(2);
-		if (mainStreamResult.status === `rejected` || errorStreamResult.status === `rejected` || entityResult.status === `rejected`) {
+		if (mainStreamResult.status === `rejected` || entityResult.status === `rejected`) {
 			const entityReason = entityResult.status === `rejected` ? entityResult.reason : null;
-			const streamReason = mainStreamResult.status === `rejected` ? mainStreamResult.reason : errorStreamResult.status === `rejected` ? errorStreamResult.reason : null;
+			const streamReason = mainStreamResult.status === `rejected` ? mainStreamResult.reason : null;
 			const isDuplicate = entityReason instanceof EntityAlreadyExistsError;
 			const isStreamConflict = !!streamReason && typeof streamReason === `object` && (`status` in streamReason && streamReason.status === 409 || `code` in streamReason && streamReason.code === `CONFLICT_SEQ`);
 			const rollbacks = [];
 			if (!isDuplicate && !isStreamConflict) {
 				if (mainStreamResult.status === `fulfilled`) rollbacks.push(this.streamClient.delete(mainPath));
-				if (errorStreamResult.status === `fulfilled`) rollbacks.push(this.streamClient.delete(errorPath));
 				if (entityResult.status === `fulfilled`) rollbacks.push(this.registry.deleteEntity(entityURL));
 				if (req.wake) rollbacks.push(this.wakeRegistry.unregisterBySubscriberAndSource(req.wake.subscriberUrl, entityURL, this.tenantId));
 				await Promise.allSettled(rollbacks);
 			}
 			if (isDuplicate || isStreamConflict) throw new ElectricAgentsError(ErrCodeDuplicateURL, `Entity already exists at URL "${entityURL}"`, 409);
-			const failure = mainStreamResult.status === `rejected` ? mainStreamResult.reason : errorStreamResult.status === `rejected` ? errorStreamResult.reason : entityResult.reason;
+			const failure = mainStreamResult.status === `rejected` ? mainStreamResult.reason : entityResult.reason;
 			if (failure instanceof Error) throw failure;
 			throw new ElectricAgentsError(`SPAWN_FAILED`, `Spawn failed: ${String(failure)}`, 500);
 		}
@@ -3058,30 +3615,67 @@ var EntityManager = class {
 		const writeEntityLocks = new Set();
 		const writeStreamLocks = new Set();
 		try {
-			const sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks);
+			let sourceTree;
+			if (opts.forkPointer) {
+				const rootEntity = await this.registry.getEntity(rootUrl);
+				if (!rootEntity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+				if (isTerminalEntityStatus(rootEntity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork terminal entity "${rootEntity.url}"`, 409);
+				sourceTree = await this.listEntitySubtree(rootEntity);
+			} else sourceTree = await this.waitForIdleSubtree(rootUrl, opts, workLocks);
 			const sourceRoot = sourceTree[0];
 			if (sourceRoot.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
-			const snapshot = await this.readForkStateSnapshot(sourceTree);
+			let preFilteredRoot;
+			if (opts.forkPointer) {
+				const sourceEvents = await this.streamClient.readJson(sourceRoot.streams.main);
+				const flat = sourceEvents.flatMap((item) => Array.isArray(item) ? item : [item]);
+				const target = this.resolveForkPointerTarget(flat, opts.forkPointer, sourceRoot.streams.main);
+				const filteredEvents = flat.slice(0, target);
+				const rootManifests = this.reduceStateRows(filteredEvents, `manifest`);
+				const sharedStateIds = new Set();
+				for (const manifest of rootManifests.values()) this.collectSharedStateIds(manifest, sharedStateIds);
+				preFilteredRoot = {
+					manifests: rootManifests,
+					childStatuses: this.reduceStateRows(filteredEvents, `child_status`),
+					replayWatermarks: this.reduceStateRows(filteredEvents, `replay_watermark`),
+					sharedStateIds
+				};
+			}
+			const effectiveSubtree = preFilteredRoot ? this.computeEffectiveSubtree(sourceTree, sourceRoot.url, preFilteredRoot.manifests) : sourceTree;
+			if (opts.forkPointer) {
+				const descendants = effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url);
+				if (descendants.length > 0) await this.waitForGivenEntitiesIdle(descendants, opts, workLocks);
+			}
+			const snapshot = await this.readForkStateSnapshot(
+				// Skip the root when we've already pre-filtered it — avoid both a
+				// wasted HEAD read of main and a re-population that would clobber
+				// the filtered entries.
+				preFilteredRoot ? effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url) : effectiveSubtree
+);
+			if (preFilteredRoot) {
+				snapshot.manifestsByEntity.set(sourceRoot.url, preFilteredRoot.manifests);
+				snapshot.childStatusesByEntity.set(sourceRoot.url, preFilteredRoot.childStatuses);
+				snapshot.replayWatermarksByEntity.set(sourceRoot.url, preFilteredRoot.replayWatermarks);
+				for (const id of preFilteredRoot.sharedStateIds) snapshot.sharedStateIds.add(id);
+			}
 			const suffix = randomUUID().slice(0, 8);
-			const entityUrlMap = await this.buildForkEntityUrlMap(sourceTree, {
+			const entityUrlMap = await this.buildForkEntityUrlMap(effectiveSubtree, {
 				suffix,
 				rootUrl,
 				rootInstanceId: opts.rootInstanceId
 			});
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
-			const entityPlans = this.buildForkEntityPlans(sourceTree, entityUrlMap, stringMap);
-			this.addForkLocks(this.forkWriteLockedEntities, sourceTree.map((entity) => entity.url), writeEntityLocks);
+			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap, opts.createdBy);
+			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => getSharedStateStreamPath(id)), writeStreamLocks);
 			const createdStreams = [];
 			const createdEntities = [];
 			const activeManifestsByEntity = new Map();
 			try {
 				for (const plan of entityPlans) {
-					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main);
+					const isRoot = plan.source.url === rootUrl;
+					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && opts.forkPointer ? { forkPointer: opts.forkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
-					await this.streamClient.fork(plan.fork.streams.error, plan.source.streams.error);
-					createdStreams.push(plan.fork.streams.error);
 				}
 				for (const [sourceId, forkId] of sharedStateIdMap) {
 					const sourcePath = getSharedStateStreamPath(sourceId);
@@ -3171,6 +3765,38 @@ var EntityManager = class {
 		}
 		held.clear();
 	}
+	/**
+	* Variant of {@link waitForIdleSubtree} that takes an explicit entity
+	* list instead of walking the registry from `rootUrl`. Used by the
+	* pointer-fork path to wait+lock only the kept descendants, since
+	* the root is being forked from history and doesn't need to be idle.
+	*/
+	async waitForGivenEntitiesIdle(entities$1, opts, workLocks) {
+		if (entities$1.length === 0) return;
+		const timeoutMs = opts.waitTimeoutMs ?? DEFAULT_FORK_WAIT_TIMEOUT_MS;
+		const pollMs = opts.waitPollMs ?? DEFAULT_FORK_WAIT_POLL_MS;
+		const refresh = async () => {
+			const refreshed = await Promise.all(entities$1.map((entity) => this.registry.getEntity(entity.url)));
+			return refreshed.filter((entity) => !!entity);
+		};
+		const deadline = Date.now() + timeoutMs;
+		while (true) {
+			const present = await refresh();
+			const stopped = present.find((entity) => isTerminalEntityStatus(entity.status));
+			if (stopped) throw new ElectricAgentsError(ErrCodeNotRunning, `Cannot fork terminal entity "${stopped.url}"`, 409);
+			let active = present.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
+			if (active.length === 0) {
+				this.addForkLocks(this.forkWorkLockedEntities, present.map((entity) => entity.url), workLocks);
+				const reChecked = await refresh();
+				const reActive = reChecked.filter((entity) => entity.status !== `idle` && entity.status !== `paused`);
+				if (reActive.length === 0) return;
+				this.releaseForkLocks(this.forkWorkLockedEntities, workLocks);
+				active = reActive;
+			}
+			if (Date.now() >= deadline) throw new ElectricAgentsError(ErrCodeForkWaitTimeout, `Timed out waiting for descendants to become idle`, 409, { active: active.map((entity) => entity.url) });
+			await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+		}
+	}
 	async waitForIdleSubtree(rootUrl, opts, workLocks) {
 		const timeoutMs = opts.waitTimeoutMs ?? DEFAULT_FORK_WAIT_TIMEOUT_MS;
 		const pollMs = opts.waitPollMs ?? DEFAULT_FORK_WAIT_POLL_MS;
@@ -3200,6 +3826,73 @@ var EntityManager = class {
 			await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
 		}
 	}
+	/**
+	* Translate `forkPointer` into a 1-indexed CUMULATIVE position in the
+	* source's flattened history. Throws a 400 if the pointer doesn't
+	* address a real event.
+	*
+	* Semantics (mirroring the durable-streams server interpretation):
+	* `{ offset: X, subOffset: N }` means "from anchor X, take N flattened
+	* messages forward." Concretely, the target event is the N-th event
+	* after the last event whose `headers.offset` is ≤ X. (When `X` is
+	* `null`, the anchor is the stream start and the target is the N-th
+	* event from the very beginning.) The returned position is the count
+	* of events to KEEP — events 1..position survive the filter.
+	*
+	* A pointer is valid when:
+	*   - `pointer.offset` is `null` (stream start) OR matches some
+	*     event's `headers.offset` value, AND
+	*   - `pointer.subOffset` is in `[1, total events past the anchor]`.
+	*/
+	resolveForkPointerTarget(events, pointer, streamPath) {
+		let positionAtAnchor = 0;
+		let anchorSeen = pointer.offset === null;
+		for (const event of events) {
+			const headers = isRecord(event.headers) ? event.headers : void 0;
+			const eventOffset = typeof headers?.offset === `string` ? headers.offset : void 0;
+			if (eventOffset === void 0) continue;
+			if (pointer.offset === null) continue;
+			if (eventOffset === pointer.offset) anchorSeen = true;
+			if (eventOffset <= pointer.offset) positionAtAnchor++;
+		}
+		if (!anchorSeen) throw new ElectricAgentsError(ErrCodeInvalidRequest, `fork_pointer.offset (${pointer.offset ?? `<stream-start>`}) does not match any event's Stream-Next-Offset on ${streamPath}`, 400);
+		const eventsPastAnchor = events.length - positionAtAnchor;
+		if (pointer.subOffset < 1 || pointer.subOffset > eventsPastAnchor) throw new ElectricAgentsError(ErrCodeInvalidRequest, `fork_pointer.sub_offset ${pointer.subOffset} out of range past anchor on ${streamPath} (valid: 1..${eventsPastAnchor})`, 400);
+		return positionAtAnchor + pointer.subOffset;
+	}
+	/**
+	* Compute the subset of `sourceTree` that survives the manifest filter
+	* applied at the root. After filtering the root's manifest at the fork
+	* pointer, only children whose manifest entries landed at or before the
+	* pointer remain; those kept children carry their CURRENT (HEAD) subtree
+	* along with them. Children dropped from the root's manifest, and any
+	* of their descendants, are excluded.
+	*/
+	computeEffectiveSubtree(sourceTree, rootUrl, filteredRootManifests) {
+		const keptChildUrls = new Set();
+		for (const value of filteredRootManifests.values()) if (value.kind === `child` && typeof value.entity_url === `string`) keptChildUrls.add(value.entity_url);
+		const childrenByParent = new Map();
+		for (const entity of sourceTree) {
+			if (!entity.parent) continue;
+			const list = childrenByParent.get(entity.parent) ?? [];
+			list.push(entity);
+			childrenByParent.set(entity.parent, list);
+		}
+		const rootEntity = sourceTree.find((e) => e.url === rootUrl);
+		if (!rootEntity) return [];
+		const result = [rootEntity];
+		const queue = [];
+		for (const child of childrenByParent.get(rootUrl) ?? []) if (keptChildUrls.has(child.url)) queue.push(child);
+		const seen = new Set([rootUrl]);
+		while (queue.length > 0) {
+			const entity = queue.shift();
+			if (seen.has(entity.url)) continue;
+			seen.add(entity.url);
+			result.push(entity);
+			for (const grandchild of childrenByParent.get(entity.url) ?? []) if (!seen.has(grandchild.url)) queue.push(grandchild);
+		}
+		return result;
+	}
 	async listEntitySubtree(root) {
 		const result = [];
 		const queue = [root];
@@ -3316,7 +4009,6 @@ var EntityManager = class {
 		for (const [sourceUrl, forkUrl] of entityUrlMap) {
 			stringMap.set(sourceUrl, forkUrl);
 			stringMap.set(`${sourceUrl}/main`, `${forkUrl}/main`);
-			stringMap.set(`${sourceUrl}/error`, `${forkUrl}/error`);
 		}
 		for (const [sourceId, forkId] of sharedStateIdMap) {
 			stringMap.set(sourceId, forkId);
@@ -3324,7 +4016,7 @@ var EntityManager = class {
 		}
 		return stringMap;
 	}
-	buildForkEntityPlans(entitiesToFork, entityUrlMap, stringMap) {
+	buildForkEntityPlans(entitiesToFork, entityUrlMap, stringMap, createdBy) {
 		const now = Date.now();
 		return entitiesToFork.map((source) => {
 			const forkUrl = entityUrlMap.get(source.url);
@@ -3337,14 +4029,12 @@ var EntityManager = class {
 				url: forkUrl,
 				type,
 				status: `idle`,
-				streams: {
-					main: `${forkUrl}/main`,
-					error: `${forkUrl}/error`
-				},
+				streams: { main: `${forkUrl}/main` },
 				subscription_id: `${type}-handler`,
 				write_token: randomUUID(),
 				spawn_args: spawnArgs,
 				parent,
+				created_by: createdBy ?? source.created_by,
 				created_at: now,
 				updated_at: now
 			};
@@ -3578,7 +4268,7 @@ var EntityManager = class {
 	}
 	async materializeForkManifestSideEffects(entityUrl, manifests) {
 		for (const [manifestKey, manifest] of manifests) {
-			await this.syncEntitiesManifestSource(entityUrl, manifestKey, `upsert`, manifest);
+			await this.syncManifestLinks(entityUrl, manifestKey, `upsert`, manifest);
 			const wake = buildManifestWakeRegistration(entityUrl, manifest, manifestKey);
 			if (wake) await this.wakeRegistry.register({
 				...wake,
@@ -3608,6 +4298,7 @@ var EntityManager = class {
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
 			from: senderUrl,
+			from_agent: senderUrl,
 			payload: manifest.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof manifest.messageType === `string` ? manifest.messageType : void 0,
@@ -3647,12 +4338,14 @@ var EntityManager = class {
 		const now = new Date().toISOString();
 		const key = req.key ?? `msg-in-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		const value = {
-			from: req.from,
+			from: req.from_principal ?? req.from,
 			payload: req.payload,
 			timestamp: now,
 			mode: req.mode ?? `immediate`,
 			status: req.mode === `queued` || req.mode === `paused` ? `pending` : `processed`
 		};
+		if (req.from_principal) value.from_principal = req.from_principal;
+		if (req.from_agent) value.from_agent = req.from_agent;
 		if (req.type) value.message_type = req.type;
 		if (req.position) value.position = req.position;
 		else if (value.mode === `queued` || value.mode === `paused`) value.position = createInitialQueuePosition(new Date(now));
@@ -3824,9 +4517,9 @@ var EntityManager = class {
 		if (result.changed && this.entityBridgeManager) await this.entityBridgeManager.onEntityChanged(entityUrl);
 		return updated;
 	}
-	async ensureEntitiesMembershipStream(tags) {
+	async ensureEntitiesMembershipStream(tags, principal) {
 		if (!this.entityBridgeManager) throw new Error(`Entity bridge manager not configured`);
-		return this.entityBridgeManager.register(this.validateTags(tags));
+		return this.entityBridgeManager.register(this.validateTags(tags), principal.url, principal.kind);
 	}
 	async writeManifestEntry(entityUrl, key, operation, value, opts) {
 		const entity = await this.registry.getEntity(entityUrl);
@@ -3844,11 +4537,11 @@ var EntityManager = class {
 		const encoded = this.encodeChangeEvent(event);
 		if (opts?.producerId) {
 			await this.streamClient.appendIdempotent(entity.streams.main, encoded, { producerId: opts.producerId });
-			await this.syncEntitiesManifestSource(entityUrl, key, operation, value);
+			await this.syncManifestLinks(entityUrl, key, operation, value);
 			return;
 		}
 		await this.streamClient.append(entity.streams.main, encoded);
-		await this.syncEntitiesManifestSource(entityUrl, key, operation, value);
+		await this.syncManifestLinks(entityUrl, key, operation, value);
 	}
 	async upsertCronSchedule(entityUrl, req) {
 		if (req.payload === void 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Missing required field: payload`, 400);
@@ -3997,6 +4690,8 @@ var EntityManager = class {
 		await this.scheduler.enqueueDelayedSend({
 			entityUrl,
 			from: req.from,
+			from_principal: req.from_principal,
+			from_agent: req.from_agent,
 			payload: req.payload,
 			key: req.key,
 			type: req.type,
@@ -4039,14 +4734,23 @@ var EntityManager = class {
 			await this.streamClient.appendIdempotent(subscriber.streams.main, this.encodeChangeEvent(wakeEvent), { producerId: `wake-reg-${result.registrationDbId}-${result.sourceEventKey}` });
 		});
 	}
-	async syncEntitiesManifestSource(entityUrl, manifestKey, operation, value) {
+	async syncManifestLinks(entityUrl, manifestKey, operation, value) {
 		const sourceRef = operation === `delete` ? void 0 : this.extractEntitiesSourceRef(value);
 		await this.registry.replaceEntityManifestSource(entityUrl, manifestKey, sourceRef);
+		const sharedStateId = operation === `delete` ? void 0 : this.extractSharedStateId(value);
+		await this.registry.replaceSharedStateLink(entityUrl, manifestKey, sharedStateId);
 	}
 	extractEntitiesSourceRef(manifest) {
 		if (manifest?.kind === `source` && manifest.sourceType === `entities` && typeof manifest.sourceRef === `string`) return manifest.sourceRef;
 		return void 0;
 	}
+	extractSharedStateId(manifest) {
+		if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) return manifest.id;
+		if (manifest?.kind !== `source` || manifest.sourceType !== `db`) return void 0;
+		if (typeof manifest.sourceRef === `string`) return manifest.sourceRef;
+		const config = isRecord(manifest.config) ? manifest.config : void 0;
+		return typeof config?.id === `string` ? config.id : void 0;
+	}
 	/**
 	* Read a child entity's stream and extract concatenated text deltas
 	* for a specific run, plus any error messages for that run.
@@ -4210,14 +4914,7 @@ var EntityManager = class {
 			await this.streamClient.append(entity.streams.main, signalData);
 			return;
 		}
-		const errorCloseEvent = {
-			type: `signal`,
-			key: signalEvent.key,
-			value: signalEvent.value,
-			headers: signalEvent.headers
-		};
-		const errorSignalData = this.encodeChangeEvent(errorCloseEvent);
-		for (const [streamPath, data] of [[entity.streams.main, signalData], [entity.streams.error, errorSignalData]]) try {
+		for (const [streamPath, data] of [[entity.streams.main, signalData]]) try {
 			await this.streamClient.append(streamPath, data, { close: true });
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -4307,6 +5004,7 @@ var EntityManager = class {
 				streams: entity.streams,
 				tags: entity.tags,
 				spawnArgs: entity.spawn_args,
+				sandbox: entity.sandbox,
 				createdBy: entity.created_by
 			},
 			principal: principalFromCreatedBy(entity.created_by),
@@ -5199,6 +5897,8 @@ var ElectricAgentsTenantRuntime = class {
 		try {
 			await this.manager.send(payload.entityUrl, {
 				from: payload.from,
+				from_principal: payload.from_principal,
+				from_agent: payload.from_agent,
 				payload: payload.payload,
 				key: payload.key ?? `scheduled-task-${taskId}`,
 				type: payload.type
@@ -5271,6 +5971,7 @@ var ElectricAgentsTenantRuntime = class {
 		await this.scheduler.syncManifestDelayedSend(ownerEntityUrl, manifestKey, {
 			entityUrl: targetUrl,
 			from: senderUrl,
+			from_agent: senderUrl,
 			payload: value.payload,
 			key: `scheduled-${producerId}`,
 			type: typeof value.messageType === `string` ? value.messageType : void 0,
@@ -5295,11 +5996,20 @@ var ElectricAgentsTenantRuntime = class {
 	async applyManifestEntitySource(ownerEntityUrl, manifestKey, operation, value) {
 		const sourceRef = operation === `delete` ? void 0 : this.extractEntitiesSourceRef(value);
 		await this.manager.registry.replaceEntityManifestSource(ownerEntityUrl, manifestKey, sourceRef);
+		const sharedStateId = operation === `delete` ? void 0 : this.extractSharedStateId(value);
+		await this.manager.registry.replaceSharedStateLink(ownerEntityUrl, manifestKey, sharedStateId);
 	}
 	extractEntitiesSourceRef(manifest) {
 		if (manifest?.kind === `source` && manifest.sourceType === `entities` && typeof manifest.sourceRef === `string`) return manifest.sourceRef;
 		return void 0;
 	}
+	extractSharedStateId(manifest) {
+		if (manifest?.kind === `shared-state` && typeof manifest.id === `string`) return manifest.id;
+		if (manifest?.kind !== `source` || manifest.sourceType !== `db`) return void 0;
+		if (typeof manifest.sourceRef === `string`) return manifest.sourceRef;
+		const config = typeof manifest.config === `object` && manifest.config !== null && !Array.isArray(manifest.config) ? manifest.config : void 0;
+		return typeof config?.id === `string` ? config.id : void 0;
+	}
 	async maybeMarkEntityIdleAfterRunFinished(entityUrl) {
 		const primaryStream = `${entityUrl}/main`;
 		const callbacks = await this.db.select().from(consumerCallbacks).where(and(eq(consumerCallbacks.tenantId, this.serviceId), eq(consumerCallbacks.primaryStream, primaryStream))).limit(1);
@@ -5972,11 +6682,21 @@ var WakeRegistry = class {
 		}
 		const kind = operation === `delete` ? `delete` : operation === `update` ? `update` : `insert`;
 		if (condition.ops && condition.ops.length > 0 && !condition.ops.includes(kind)) return null;
-		return { change: {
+		const change = {
 			collection: eventType,
 			kind,
 			key: event.key || ``
-		} };
+		};
+		if (eventType === `inbox`) {
+			const value = event.value;
+			if (typeof value?.from === `string`) change.from = value.from;
+			if (typeof value?.from_principal === `string`) change.from_principal = value.from_principal;
+			if (typeof value?.from_agent === `string`) change.from_agent = value.from_agent;
+			if (`payload` in (value ?? {})) change.payload = value?.payload;
+			if (typeof value?.timestamp === `string`) change.timestamp = value.timestamp;
+			if (typeof value?.message_type === `string`) change.message_type = value.message_type;
+		}
+		return { change };
 	}
 };
 
@@ -6383,29 +7103,136 @@ function buildElectricProxyTarget(options) {
 	if (options.electricSecret) target.searchParams.set(`secret`, options.electricSecret);
 	const table = options.incomingUrl.searchParams.get(`table`);
 	if (table === `entities`) {
-		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		target.searchParams.set(`columns`, `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","created_by","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`);
+		applyShapeWhere(target, buildReadableEntitiesWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	} else if (table === `entity_types`) {
 		target.searchParams.set(`columns`, `"tenant_id","name","description","creation_schema","inbox_schemas","state_schemas","serve_endpoint","default_dispatch_policy","revision","created_at","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		applyShapeWhere(target, buildSpawnableEntityTypesWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	} else if (table === `runners`) {
-		target.searchParams.set(`columns`, `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","created_at","updated_at"`);
+		target.searchParams.set(`columns`, `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","sandbox_profiles","created_at","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral(options.principalUrl ?? ``)}`]);
+	} else if (table === `users`) {
+		target.searchParams.set(`columns`, `"tenant_id","id","display_name","email","avatar_url","created_at","updated_at"`);
+		applyTenantShapeWhere(target, options.tenantId);
+	} else if (table === `entity_effective_permissions`) {
+		target.searchParams.set(`columns`, `"tenant_id","id","entity_url","source_entity_url","source_grant_id","permission","subject_kind","subject_value","expires_at","created_at"`);
+		applyShapeWhere(target, buildCurrentPrincipalEntityEffectivePermissionsWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	} else if (table === `runner_runtime_diagnostics`) {
 		target.searchParams.set(`columns`, `"tenant_id","runner_id","owner_principal","wake_stream_offset","last_seen_at","liveness_lease_expires_at","diagnostics","updated_at"`);
 		applyTenantShapeWhere(target, options.tenantId, [`owner_principal = ${sqlStringLiteral(options.principalUrl ?? ``)}`]);
 	} else if (table === `entity_dispatch_state`) {
 		target.searchParams.set(`columns`, `"tenant_id","entity_url","pending_source_streams","pending_reason","pending_since","outstanding_wake_id","outstanding_wake_target","outstanding_wake_created_at","active_consumer_id","active_runner_id","active_epoch","active_claimed_at","active_lease_expires_at","last_wake_id","last_claimed_at","last_released_at","last_completed_at","last_error","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		applyShapeWhere(target, buildReadableEntityUrlWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	} else if (table === `wake_notifications`) {
 		target.searchParams.set(`columns`, `"tenant_id","wake_id","entity_url","target_type","target_runner_id","target_webhook_url","target_worker_pool_id","runner_wake_stream","runner_wake_stream_offset","notification_public","delivery_status","claim_status","created_at","delivered_at","claimed_at","resolved_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		applyShapeWhere(target, buildReadableEntityUrlWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	} else if (table === `consumer_claims`) {
 		target.searchParams.set(`columns`, `"tenant_id","consumer_id","epoch","wake_id","entity_url","stream_path","runner_id","status","claimed_at","last_heartbeat_at","lease_expires_at","released_at","acked_streams","updated_at"`);
-		applyTenantShapeWhere(target, options.tenantId);
+		applyShapeWhere(target, buildReadableEntityUrlWhere({
+			tenantId: options.tenantId,
+			principalUrl: options.principalUrl ?? ``,
+			principalKind: options.principalKind ?? ``,
+			permissionBypass: options.permissionBypass
+		}));
 	}
 	return target;
 }
+function buildReadableEntitiesWhere(options) {
+	const tenant = sqlStringLiteral(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral(options.principalUrl);
+	const principalKind = sqlStringLiteral(options.principalKind);
+	return [
+		`tenant_id = ${tenant}`,
+		`AND (`,
+		`  created_by = ${principalUrl$1}`,
+		`  OR url IN (`,
+		`    SELECT entity_url`,
+		`    FROM entity_effective_permissions`,
+		`    WHERE tenant_id = ${tenant}`,
+		`      AND permission IN ('read', 'manage')`,
+		`      AND (`,
+		`        (subject_kind = 'principal' AND subject_value = ${principalUrl$1})`,
+		`        OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`      )`,
+		`  )`,
+		`)`
+	].join(`\n`);
+}
+function buildReadableEntityUrlWhere(options) {
+	const tenant = sqlStringLiteral(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	return [
+		`tenant_id = ${tenant}`,
+		`AND entity_url IN (`,
+		`  SELECT url`,
+		`  FROM entities`,
+		`  WHERE ${indentWhere(buildReadableEntitiesWhere(options), `    `).trimStart()}`,
+		`)`
+	].join(`\n`);
+}
+function buildCurrentPrincipalEntityEffectivePermissionsWhere(options) {
+	const tenant = sqlStringLiteral(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral(options.principalUrl);
+	const principalKind = sqlStringLiteral(options.principalKind);
+	return [
+		`tenant_id = ${tenant}`,
+		`AND (`,
+		`  (subject_kind = 'principal' AND subject_value = ${principalUrl$1})`,
+		`  OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`)`,
+		`AND entity_url IN (`,
+		`  SELECT url`,
+		`  FROM entities`,
+		`  WHERE ${buildReadableEntitiesWhere(options)}`,
+		`)`
+	].join(`\n`);
+}
+function buildSpawnableEntityTypesWhere(options) {
+	const tenant = sqlStringLiteral(options.tenantId);
+	if (options.permissionBypass) return `tenant_id = ${tenant}`;
+	const principalUrl$1 = sqlStringLiteral(options.principalUrl);
+	const principalKind = sqlStringLiteral(options.principalKind);
+	return [
+		`tenant_id = ${tenant}`,
+		`AND name IN (`,
+		`  SELECT entity_type`,
+		`  FROM entity_type_permission_grants`,
+		`  WHERE tenant_id = ${tenant}`,
+		`    AND permission IN ('spawn', 'manage')`,
+		`    AND (`,
+		`      (subject_kind = 'principal' AND subject_value = ${principalUrl$1})`,
+		`      OR (subject_kind = 'principal_kind' AND subject_value = ${principalKind})`,
+		`    )`,
+		`)`
+	].join(`\n`);
+}
 async function forwardFetchRequest(options) {
 	const routingAdapter = resolveDurableStreamsRoutingAdapter(options.durableStreamsRouting, options.durableStreamsUrl);
 	const routingInput = {
@@ -6440,13 +7267,170 @@ function decodeJsonObject(body) {
 	return null;
 }
 function applyTenantShapeWhere(target, tenantId, extraConditions = []) {
-	const tenantWhere = [`tenant_id = ${sqlStringLiteral(tenantId)}`, ...extraConditions].join(` AND `);
+	applyShapeWhere(target, [`tenant_id = ${sqlStringLiteral(tenantId)}`, ...extraConditions].join(` AND `));
+}
+function applyShapeWhere(target, enforcedWhere) {
 	const existingWhere = target.searchParams.get(`where`);
-	target.searchParams.set(`where`, existingWhere ? `${tenantWhere} AND (${existingWhere})` : tenantWhere);
+	target.searchParams.set(`where`, existingWhere ? `${enforcedWhere} AND (${existingWhere})` : enforcedWhere);
 }
 function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, `''`)}'`;
 }
+function indentWhere(where, prefix) {
+	return where.split(`\n`).map((line) => `${prefix}${line}`).join(`\n`);
+}
+
+//#endregion
+//#region src/permissions.ts
+const authzDecisionCache = new WeakMap();
+function principalSubject(principal) {
+	return {
+		principalUrl: principal.url,
+		principalKind: principal.kind
+	};
+}
+function isPermissionBypassPrincipal(ctx) {
+	return isBuiltInSystemPrincipalUrl(ctx.principal.url);
+}
+async function canAccessEntity(ctx, entity, permission, request) {
+	if (isPermissionBypassPrincipal(ctx)) return true;
+	await ctx.entityManager.registry.pruneExpiredPermissionGrants?.();
+	const builtInAllowed = entity.created_by === ctx.principal.url || await ctx.entityManager.registry.hasEntityPermission(entity.url, permission, principalSubject(ctx.principal));
+	return await applyAuthorizationHook(ctx, {
+		verb: permission,
+		resourceKey: `entity:${entity.url}`,
+		resource: {
+			kind: `entity`,
+			entity
+		},
+		builtInAllowed,
+		request
+	});
+}
+async function canAccessEntityType(ctx, entityType, permission, request) {
+	if (isPermissionBypassPrincipal(ctx)) return true;
+	await ctx.entityManager.registry.pruneExpiredPermissionGrants?.();
+	const builtInAllowed = await ctx.entityManager.registry.hasEntityTypePermission(entityType.name, permission, principalSubject(ctx.principal));
+	return await applyAuthorizationHook(ctx, {
+		verb: permission,
+		resourceKey: `entity_type:${entityType.name}`,
+		resource: {
+			kind: `entity_type`,
+			entityType
+		},
+		builtInAllowed,
+		request
+	});
+}
+async function canRegisterEntityType(ctx, input, request) {
+	if (isPermissionBypassPrincipal(ctx)) return true;
+	return await applyAuthorizationHook(ctx, {
+		verb: `manage`,
+		resourceKey: `entity_type_registration:${input.name}`,
+		resource: {
+			kind: `entity_type_registration`,
+			entityTypeName: input.name
+		},
+		builtInAllowed: true,
+		request
+	});
+}
+async function canAccessSharedState(ctx, sharedStateId, permission, request, ownerEntityUrl) {
+	if (isPermissionBypassPrincipal(ctx)) return true;
+	await ctx.entityManager.registry.pruneExpiredPermissionGrants?.();
+	const storedLinkedEntityUrls = await ctx.entityManager.registry.listSharedStateLinkedEntityUrls(sharedStateId);
+	const bootstrapEntityUrls = storedLinkedEntityUrls.length === 0 && ownerEntityUrl ? [ownerEntityUrl] : [];
+	const linkedEntityUrls = [...new Set([...storedLinkedEntityUrls, ...bootstrapEntityUrls])];
+	for (const entityUrl of linkedEntityUrls) {
+		const entity = await ctx.entityManager.registry.getEntity(entityUrl);
+		if (!entity) continue;
+		if (entity.created_by === ctx.principal.url || await ctx.entityManager.registry.hasEntityPermission(entity.url, permission, principalSubject(ctx.principal))) return await applyAuthorizationHook(ctx, {
+			verb: permission,
+			resourceKey: `shared_state:${sharedStateId}`,
+			resource: {
+				kind: `shared_state`,
+				sharedStateId,
+				linkedEntityUrls
+			},
+			builtInAllowed: true,
+			request
+		});
+	}
+	return await applyAuthorizationHook(ctx, {
+		verb: permission,
+		resourceKey: `shared_state:${sharedStateId}`,
+		resource: {
+			kind: `shared_state`,
+			sharedStateId,
+			linkedEntityUrls
+		},
+		builtInAllowed: false,
+		request
+	});
+}
+async function applyAuthorizationHook(ctx, input) {
+	const hook = ctx.authorizeRequest;
+	if (!hook) return input.builtInAllowed;
+	const cacheKey = [
+		ctx.service,
+		ctx.principal.url,
+		input.verb,
+		input.resourceKey
+	].join(`|`);
+	const cached = getCachedDecision(hook, cacheKey);
+	if (cached) return cached.decision === `allow`;
+	let decision;
+	try {
+		decision = await hook({
+			tenant: ctx.service,
+			principal: ctx.principal,
+			verb: input.verb,
+			resource: input.resource,
+			request: input.request ? requestMetadata(input.request) : void 0,
+			builtInAllowed: input.builtInAllowed
+		});
+	} catch (error) {
+		serverLog.warn(`[agent-server] authorization hook failed:`, error);
+		return false;
+	}
+	cacheDecision(hook, cacheKey, decision);
+	return decision.decision === `allow`;
+}
+function getCachedDecision(hook, cacheKey) {
+	const cache = authzDecisionCache.get(hook);
+	const entry = cache?.get(cacheKey);
+	if (!entry) return null;
+	if (entry.expiresAt <= Date.now()) {
+		cache?.delete(cacheKey);
+		return null;
+	}
+	return { decision: entry.decision };
+}
+function cacheDecision(hook, cacheKey, decision) {
+	if (!decision.expires_at) return;
+	const expiresAt = Date.parse(decision.expires_at);
+	if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return;
+	let cache = authzDecisionCache.get(hook);
+	if (!cache) {
+		cache = new Map();
+		authzDecisionCache.set(hook, cache);
+	}
+	cache.set(cacheKey, {
+		decision: decision.decision,
+		expiresAt
+	});
+}
+function requestMetadata(request) {
+	const headers = {};
+	request.headers.forEach((value, key) => {
+		headers[key] = value;
+	});
+	return {
+		method: request.method,
+		url: request.url,
+		headers
+	};
+}
 
 //#endregion
 //#region src/webhook-signing.ts
@@ -6538,6 +7522,7 @@ const subscriptionControlActions = [
 	`ack`,
 	`release`
 ];
+const SHARED_STATE_OWNER_ENTITY_HEADER = `electric-owner-entity`;
 const durableStreamsRouter = Router();
 durableStreamsRouter.put(`/__ds/subscriptions/:subscriptionId`, putSubscriptionBase);
 durableStreamsRouter.get(`/__ds/subscriptions/:subscriptionId`, getSubscriptionBase);
@@ -6755,6 +7740,8 @@ async function webhookJwks(_request, ctx) {
 	});
 }
 async function streamAppend(request, ctx) {
+	const auth = await authorizeDurableStreamAccess(request, ctx);
+	if (auth) return auth;
 	return await electricAgentsStreamAppendRouter.fetch(createStreamAppendRouteRequest(request), ctx.runtime, (req, body) => forwardFetchRequest({
 		request: {
 			method: req.method,
@@ -6771,8 +7758,9 @@ async function streamAppend(request, ctx) {
 	}));
 }
 async function proxyPassThrough(request, ctx) {
+	const auth = await authorizeDurableStreamAccess(request, ctx);
+	if (auth) return auth;
 	const streamPath = new URL(request.url).pathname;
-	if (ctx.entityManager?.isAttachmentStreamPath(streamPath)) return new Response(null, { status: 404 });
 	const upstream = await forwardToDurableStreams(ctx, request);
 	const method = request.method.toUpperCase();
 	const endTrackedRead = method === `GET` ? await ctx.entityBridgeManager.beginClientRead(streamPath) : null;
@@ -6783,6 +7771,51 @@ async function proxyPassThrough(request, ctx) {
 		await endTrackedRead?.();
 	}
 }
+async function authorizeDurableStreamAccess(request, ctx) {
+	const method = request.method.toUpperCase();
+	const streamPath = new URL(request.url).pathname;
+	if (method === `GET` || method === `HEAD`) {
+		const registry = ctx.entityManager?.registry;
+		const entity = registry?.getEntityByStream ? await registry.getEntityByStream(streamPath) : null;
+		if (entity) {
+			if (await canAccessEntity(ctx, entity, `read`, request)) return void 0;
+			return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to read ${entity.url}`);
+		}
+		const attachmentEntityUrl = entityUrlFromAttachmentStreamPath(streamPath);
+		if (attachmentEntityUrl) {
+			const attachmentEntity = registry?.getEntity ? await registry.getEntity(attachmentEntityUrl) : null;
+			if (!attachmentEntity) return apiError(404, ErrCodeNotFound, `Entity not found`);
+			if (await canAccessEntity(ctx, attachmentEntity, `read`, request)) return void 0;
+			return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to read ${attachmentEntity.url}`);
+		}
+	}
+	const sharedStateId = sharedStateIdFromPath(streamPath);
+	if (!sharedStateId) return void 0;
+	if (method === `GET` || method === `HEAD`) {
+		if (await canAccessSharedState(ctx, sharedStateId, `read`, request)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to read shared state`);
+	}
+	if (method === `PUT` || method === `POST`) {
+		const ownerEntityUrl = request.headers.get(SHARED_STATE_OWNER_ENTITY_HEADER)?.trim() || void 0;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to write shared state`);
+	}
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to access shared state`);
+}
+function entityUrlFromAttachmentStreamPath(path$1) {
+	const match = path$1.match(/^\/([^/]+)\/([^/]+)\/attachments\/[^/]+$/);
+	if (!match) return null;
+	return `/${match[1]}/${match[2]}`;
+}
+function sharedStateIdFromPath(path$1) {
+	const match = path$1.match(/^\/_electric\/shared-state\/([^/]+)$/);
+	if (!match) return null;
+	try {
+		return decodeURIComponent(match[1]);
+	} catch {
+		return match[1];
+	}
+}
 
 //#endregion
 //#region src/routing/electric-proxy-router.ts
@@ -6790,12 +7823,15 @@ const electricProxyRouter = Router({ base: `/_electric/electric` });
 electricProxyRouter.get(`/*`, proxyElectric);
 async function proxyElectric(request, ctx) {
 	if (!ctx.electricUrl) return apiError(500, `ELECTRIC_PROXY_FAILED`, `Electric URL not configured`);
+	await ctx.entityManager.registry.pruneExpiredPermissionGrants?.();
 	const target = buildElectricProxyTarget({
 		incomingUrl: new URL(request.url),
 		electricUrl: ctx.electricUrl,
 		electricSecret: ctx.electricSecret,
 		tenantId: ctx.service,
-		principalUrl: ctx.principal.url
+		principalUrl: ctx.principal.url,
+		principalKind: ctx.principal.kind,
+		permissionBypass: isPermissionBypassPrincipal(ctx)
 	});
 	const headers = new Headers(request.headers);
 	headers.delete(`host`);
@@ -6815,6 +7851,28 @@ async function proxyElectric(request, ctx) {
 	});
 }
 
+//#endregion
+//#region src/sandbox-choice-schema.ts
+/**
+* Wire schema for a spawn-time sandbox CHOICE (the request input), as opposed to
+* the resolved {@link import('./electric-agents-types.js').EntitySandboxSelection}
+* persisted on the entity. The matching `SandboxChoice` type is hand-maintained
+* in `electric-agents-types.ts` — mirrors how `dispatchPolicySchema` pairs with
+* the `DispatchPolicy` type in `dispatch-policy-schema.ts`.
+*
+* Validation happens once, at the router boundary (this schema is embedded in
+* the spawn body schema); the spawn resolver consumes already-validated input,
+* so there is intentionally no separate `parse` helper here.
+*/
+const sandboxChoiceSchema = Type.Object({
+	profile: Type.Optional(Type.String()),
+	key: Type.Optional(Type.String()),
+	scope: Type.Optional(Type.Union([Type.Literal(`entity`), Type.Literal(`wake`)])),
+	persistent: Type.Optional(Type.Boolean()),
+	owner: Type.Optional(Type.Boolean()),
+	inherit: Type.Optional(Type.Boolean())
+});
+
 //#endregion
 //#region src/routing/entities-router.ts
 const stringRecordSchema$1 = Type.Record(Type.String(), Type.String());
@@ -6832,12 +7890,35 @@ const wakeConditionSchema = Type.Union([Type.Literal(`runFinished`), Type.Object
 		Type.Literal(`delete`)
 	])))
 })]);
+const permissionSubjectSchema = Type.Object({
+	subject_kind: Type.Union([Type.Literal(`principal`), Type.Literal(`principal_kind`)]),
+	subject_value: Type.String()
+}, { additionalProperties: false });
+const entityPermissionSchema = Type.Union([
+	Type.Literal(`read`),
+	Type.Literal(`write`),
+	Type.Literal(`delete`),
+	Type.Literal(`signal`),
+	Type.Literal(`fork`),
+	Type.Literal(`schedule`),
+	Type.Literal(`spawn`),
+	Type.Literal(`manage`)
+]);
+const entityPermissionGrantInputSchema = Type.Object({
+	...permissionSubjectSchema.properties,
+	permission: entityPermissionSchema,
+	propagation: Type.Optional(Type.Union([Type.Literal(`self`), Type.Literal(`descendants`)])),
+	copy_to_children: Type.Optional(Type.Boolean()),
+	expires_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
 const spawnBodySchema = Type.Object({
 	args: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	tags: Type.Optional(stringRecordSchema$1),
 	parent: Type.Optional(Type.String()),
 	dispatch_policy: Type.Optional(dispatchPolicySchema),
+	sandbox: Type.Optional(sandboxChoiceSchema),
 	initialMessage: Type.Optional(Type.Unknown()),
+	grants: Type.Optional(Type.Array(entityPermissionGrantInputSchema)),
 	wake: Type.Optional(Type.Object({
 		subscriberUrl: Type.String(),
 		condition: wakeConditionSchema,
@@ -6859,8 +7940,22 @@ const sendBodySchema = Type.Object({
 	])),
 	position: Type.Optional(Type.String()),
 	afterMs: Type.Optional(Type.Number()),
-	from: Type.Optional(Type.String())
+	from: Type.Optional(Type.String()),
+	from_principal: Type.Optional(Type.String()),
+	from_agent: Type.Optional(Type.String())
 });
+function agentUrlForPrincipal(principal) {
+	if (principal.kind === `agent`) return `/${principal.id}`;
+	if (principal.key.startsWith(`entity:`)) return `/${principal.key.slice(`entity:`.length)}`;
+	return null;
+}
+function agentUrlPath(value) {
+	try {
+		return new URL(value).pathname;
+	} catch {
+		return value;
+	}
+}
 const inboxMessageBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	position: Type.Optional(Type.String()),
@@ -6878,7 +7973,11 @@ const inboxMessageBodySchema = Type.Object({
 });
 const forkBodySchema = Type.Object({
 	instance_id: Type.Optional(Type.String()),
-	waitTimeoutMs: Type.Optional(Type.Number())
+	waitTimeoutMs: Type.Optional(Type.Number()),
+	fork_pointer: Type.Optional(Type.Object({
+		offset: Type.Union([Type.String(), Type.Null()]),
+		sub_offset: Type.Number()
+	}))
 });
 const setTagBodySchema = Type.Object({ value: Type.String() });
 const entitySignalSchema = Type.Union([
@@ -6935,24 +8034,27 @@ const attachmentSubjectTypes = new Set([
 ]);
 const entitiesRouter = Router({ base: `/_electric/entities` });
 entitiesRouter.get(`/`, listEntities);
-entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), spawnEntity);
-entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, getEntity);
-entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, headEntity);
-entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, killEntity);
-entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), signalEntity);
-entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), sendEntity);
-entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, createAttachment);
-entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, readAttachment);
-entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, deleteAttachment);
-entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), updateInboxMessage);
-entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, deleteInboxMessage);
-entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), forkEntity);
-entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withSchema(setTagBodySchema), setTag);
-entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, deleteTag);
-entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), upsertSchedule);
-entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, deleteSchedule);
-entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), upsertEventSourceSubscription);
-entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, deleteEventSourceSubscription);
+entitiesRouter.put(`/:type/:instanceId`, withSpawnableEntityType, withSchema(spawnBodySchema), withSpawnPermission, spawnEntity);
+entitiesRouter.get(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`read`), getEntity);
+entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`read`), headEntity);
+entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`delete`), killEntity);
+entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), withEntityPermission(`signal`), signalEntity);
+entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), withEntityPermission(`write`), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, withEntityPermission(`write`), createAttachment);
+entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`read`), readAttachment);
+entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`write`), deleteAttachment);
+entitiesRouter.patch(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withSchema(inboxMessageBodySchema), withEntityPermission(`write`), updateInboxMessage);
+entitiesRouter.delete(`/:type/:instanceId/inbox/:messageKey`, withExistingEntity, withEntityPermission(`write`), deleteInboxMessage);
+entitiesRouter.post(`/:type/:instanceId/fork`, withExistingEntity, withSchema(forkBodySchema), withEntityPermission(`fork`), forkEntity);
+entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withSchema(setTagBodySchema), withEntityPermission(`write`), setTag);
+entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withEntityPermission(`write`), deleteTag);
+entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), withEntityPermission(`schedule`), upsertSchedule);
+entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withEntityPermission(`schedule`), deleteSchedule);
+entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertEventSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteEventSourceSubscription);
+entitiesRouter.get(`/:type/:instanceId/grants`, withExistingEntity, withEntityPermission(`manage`), listEntityPermissionGrants);
+entitiesRouter.post(`/:type/:instanceId/grants`, withExistingEntity, withSchema(entityPermissionGrantInputSchema), withEntityPermission(`manage`), createEntityPermissionGrant);
+entitiesRouter.delete(`/:type/:instanceId/grants/:grantId`, withExistingEntity, withEntityPermission(`manage`), deleteEntityPermissionGrant);
 function entityUrlFromSegments(type, instanceId) {
 	if (!type || !instanceId) return null;
 	if (type.startsWith(`_`) || type.includes(`*`) || instanceId.includes(`*`)) return null;
@@ -7051,6 +8153,17 @@ function rejectPrincipalEntityMutation(request, action) {
 	if (entity.type !== `principal`) return void 0;
 	return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be ${action}`);
 }
+function parseExpiresAt$1(value) {
+	if (value === void 0) return void 0;
+	const expiresAt = new Date(value);
+	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
+	return expiresAt;
+}
+function parseGrantId$1(request) {
+	const grantId = Number.parseInt(String(request.params.grantId), 10);
+	if (!Number.isSafeInteger(grantId) || grantId <= 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid grant id`, 400);
+	return grantId;
+}
 async function withExistingEntity(request, ctx) {
 	const entityUrl = entityUrlFromSegments(request.params.type, request.params.instanceId);
 	if (!entityUrl) return void 0;
@@ -7081,17 +8194,76 @@ async function withSpawnableEntityType(request, ctx) {
 	if (request.params.type === `principal`) return apiError(400, ErrCodeInvalidRequest, `Principal entities are built in and cannot be spawned directly`);
 	const entityType = await ctx.entityManager.registry.getEntityType(request.params.type);
 	if (!entityType) return apiError(404, ErrCodeUnknownEntityType, `Entity type "${request.params.type}" not found`);
+	request.spawnRoute = { entityType };
 	return void 0;
 }
+function withEntityPermission(permission) {
+	return async (request, ctx) => {
+		const { entity } = requireExistingEntityRoute(request);
+		if (await canAccessEntity(ctx, entity, permission, request)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to ${permission} ${entity.url}`);
+	};
+}
+async function withSpawnPermission(request, ctx) {
+	const parsed = routeBody(request);
+	const entityType = request.spawnRoute?.entityType;
+	if (!entityType) throw new Error(`spawnable entity type middleware did not run`);
+	if (!await canAccessEntityType(ctx, entityType, `spawn`, request)) return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn ${entityType.name}`);
+	if (!parsed.parent) return void 0;
+	const parent = await ctx.entityManager.registry.getEntity(parsed.parent);
+	if (!parent) return apiError(404, ErrCodeNotFound, `Parent entity not found`);
+	if (await canAccessEntity(ctx, parent, `spawn`, request)) return await validateParentedSpawnGrants(request, ctx, parent, parsed);
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn children from ${parent.url}`);
+}
+async function validateParentedSpawnGrants(request, ctx, parent, parsed) {
+	const needsParentManage = (parsed.grants ?? []).some(requiresParentManageForInitialGrant);
+	if (!needsParentManage) return void 0;
+	if (await canAccessEntity(ctx, parent, `manage`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to delegate broad grants from ${parent.url}`);
+}
+function requiresParentManageForInitialGrant(grant) {
+	return grant.permission === `manage` || grant.subject_kind === `principal_kind` || grant.propagation === `descendants` || grant.copy_to_children === true;
+}
 async function listEntities({ query }, ctx) {
 	const { entities: entities$1 } = await ctx.entityManager.registry.listEntities({
 		type: firstQueryValue$1(query.type),
 		status: firstQueryValue$1(query.status),
 		parent: firstQueryValue$1(query.parent),
-		created_by: firstQueryValue$1(query.created_by)
+		created_by: firstQueryValue$1(query.created_by),
+		readableBy: {
+			...principalSubject(ctx.principal),
+			bypass: isPermissionBypassPrincipal(ctx)
+		}
 	});
 	return json(entities$1.map((entity) => toPublicEntity(entity)));
 }
+async function listEntityPermissionGrants(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const grants = await ctx.entityManager.registry.listEntityPermissionGrants(entityUrl);
+	return json({ grants });
+}
+async function createEntityPermissionGrant(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const parsed = routeBody(request);
+	const grant = await ctx.entityManager.registry.createEntityPermissionGrant({
+		entityUrl,
+		permission: parsed.permission,
+		subjectKind: parsed.subject_kind,
+		subjectValue: parsed.subject_value,
+		propagation: parsed.propagation,
+		copyToChildren: parsed.copy_to_children,
+		expiresAt: parseExpiresAt$1(parsed.expires_at),
+		createdBy: ctx.principal.url
+	});
+	await ctx.entityBridgeManager.onEntityChanged(entityUrl);
+	return json(grant, { status: 201 });
+}
+async function deleteEntityPermissionGrant(request, ctx) {
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const deleted = await ctx.entityManager.registry.deleteEntityPermissionGrant(entityUrl, parseGrantId$1(request));
+	if (deleted) await ctx.entityBridgeManager.onEntityChanged(entityUrl);
+	return deleted ? status(204) : apiError(404, ErrCodeNotFound, `Grant not found`);
+}
 async function upsertSchedule(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `scheduled`);
 	if (principalMutationError) return principalMutationError;
@@ -7196,7 +8368,12 @@ async function forkEntity(request, ctx) {
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
-		waitTimeoutMs: parsed.waitTimeoutMs
+		waitTimeoutMs: parsed.waitTimeoutMs,
+		createdBy: ctx.principal.url,
+		...parsed.fork_pointer && { forkPointer: {
+			offset: parsed.fork_pointer.offset,
+			subOffset: parsed.fork_pointer.sub_offset
+		} }
 	});
 	for (const forkedEntity of result.entities) await linkEntityDispatchSubscription(ctx, forkedEntity);
 	return json({
@@ -7208,26 +8385,27 @@ async function sendEntity(request, ctx) {
 	const parsed = routeBody(request);
 	const principal = ctx.principal;
 	if (parsed.from !== void 0 && parsed.from !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from must match Electric-Principal`);
+	if (parsed.from_principal !== void 0 && parsed.from_principal !== principal.url) return apiError(400, ErrCodeInvalidRequest, `Request from_principal must match Electric-Principal`);
+	if (parsed.from_agent !== void 0) {
+		const principalAgentUrl = agentUrlForPrincipal(principal);
+		if (agentUrlPath(parsed.from_agent) !== principalAgentUrl) return apiError(400, ErrCodeInvalidRequest, `Request from_agent must match authenticated agent principal`);
+	}
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	const dispatchEntity = entity.dispatch_policy ? entity : await backfillEntityDispatchPolicy(ctx, entity);
 	await linkEntityDispatchSubscription(ctx, dispatchEntity);
-	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, {
-		from: principal.url,
-		payload: parsed.payload,
-		key: parsed.key,
-		type: parsed.type,
-		mode: parsed.mode,
-		position: parsed.position
-	}, new Date(Date.now() + parsed.afterMs));
-	else await ctx.entityManager.send(entityUrl, {
+	const sendReq = {
 		from: principal.url,
+		from_principal: principal.url,
+		from_agent: parsed.from_agent,
 		payload: parsed.payload,
 		key: parsed.key,
 		type: parsed.type,
 		mode: parsed.mode,
 		position: parsed.position
-	});
+	};
+	if (parsed.afterMs && parsed.afterMs > 0) await ctx.entityManager.enqueueDelayedSend(entityUrl, sendReq, new Date(Date.now() + parsed.afterMs));
+	else await ctx.entityManager.send(entityUrl, sendReq);
 	return status(204);
 }
 async function createAttachment(request, ctx) {
@@ -7294,10 +8472,22 @@ async function spawnEntity(request, ctx) {
 		tags: parsed.tags,
 		parent: parsed.parent,
 		dispatch_policy: dispatchPolicy,
+		sandbox: parsed.sandbox,
 		initialMessage: void 0,
 		wake: parsed.wake,
 		created_by: principal.url
 	});
+	if (parsed.parent) await ctx.entityManager.registry.copyEntityPermissionGrantsForSpawn(parsed.parent, entity.url, principal.url);
+	for (const grant of parsed.grants ?? []) await ctx.entityManager.registry.createEntityPermissionGrant({
+		entityUrl: entity.url,
+		permission: grant.permission,
+		subjectKind: grant.subject_kind,
+		subjectValue: grant.subject_value,
+		propagation: grant.propagation,
+		copyToChildren: grant.copy_to_children,
+		expiresAt: parseExpiresAt$1(grant.expires_at),
+		createdBy: principal.url
+	});
 	const linkBeforeInitialMessage = parsed.initialMessage !== void 0 && shouldLinkDispatchBeforeInitialMessage(dispatchPolicy);
 	if (linkBeforeInitialMessage) await linkEntityDispatchSubscription(ctx, entity);
 	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(entity.url, {
@@ -7349,6 +8539,12 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown());
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema);
+const typePermissionGrantInputSchema = Type.Object({
+	subject_kind: Type.Union([Type.Literal(`principal`), Type.Literal(`principal_kind`)]),
+	subject_value: Type.String(),
+	permission: Type.Union([Type.Literal(`spawn`), Type.Literal(`manage`)]),
+	expires_at: Type.Optional(Type.String())
+}, { additionalProperties: false });
 const registerEntityTypeBodySchema = Type.Object({
 	name: Type.Optional(Type.String()),
 	description: Type.Optional(Type.String()),
@@ -7356,7 +8552,8 @@ const registerEntityTypeBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
 	state_schemas: Type.Optional(schemaMapSchema),
 	serve_endpoint: Type.Optional(Type.String()),
-	default_dispatch_policy: Type.Optional(dispatchPolicySchema)
+	default_dispatch_policy: Type.Optional(dispatchPolicySchema),
+	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema))
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
@@ -7364,20 +8561,56 @@ const amendEntityTypeSchemasBodySchema = Type.Object({
 }, { additionalProperties: false });
 const entityTypesRouter = Router({ base: `/_electric/entity-types` });
 entityTypesRouter.get(`/`, listEntityTypes);
-entityTypesRouter.post(`/`, withSchema(registerEntityTypeBodySchema), registerEntityType);
-entityTypesRouter.patch(`/:name/schemas`, withSchema(amendEntityTypeSchemasBodySchema), amendSchemas);
-entityTypesRouter.get(`/:name`, getEntityType);
-entityTypesRouter.delete(`/:name`, deleteEntityType);
+entityTypesRouter.post(`/`, withSchema(registerEntityTypeBodySchema), withEntityTypeRegistrationPermission, registerEntityType);
+entityTypesRouter.patch(`/:name/schemas`, withExistingEntityType, withEntityTypeManagePermission, withSchema(amendEntityTypeSchemasBodySchema), amendSchemas);
+entityTypesRouter.get(`/:name`, withExistingEntityType, withEntityTypeSpawnPermission, getEntityType);
+entityTypesRouter.delete(`/:name`, withExistingEntityType, withEntityTypeManagePermission, deleteEntityType);
+entityTypesRouter.get(`/:name/grants`, withExistingEntityType, withEntityTypeManagePermission, listTypePermissionGrants);
+entityTypesRouter.post(`/:name/grants`, withExistingEntityType, withSchema(typePermissionGrantInputSchema), withEntityTypeManagePermission, createTypePermissionGrant);
+entityTypesRouter.delete(`/:name/grants/:grantId`, withExistingEntityType, withEntityTypeManagePermission, deleteTypePermissionGrant);
 async function registerEntityType(request, ctx) {
 	const parsed = routeBody(request);
 	const normalized = normalizeEntityTypeRequest(parsed);
 	if (normalized.serve_endpoint && !normalized.description && !normalized.creation_schema) return await discoverServeEndpoint(ctx, normalized);
 	const entityType = await ctx.entityManager.registerEntityType(normalized);
+	await applyRegistrationPermissionGrants(ctx, entityType.name, normalized);
 	return json(toPublicEntityType(entityType), { status: 201 });
 }
 async function listEntityTypes(_request, ctx) {
 	const entityTypes$1 = await ctx.entityManager.registry.listEntityTypes();
-	return json(entityTypes$1.map((entityType) => toPublicEntityType(entityType)));
+	const visible = [];
+	for (const entityType of entityTypes$1) if (await canAccessEntityType(ctx, entityType, `spawn`)) visible.push(entityType);
+	return json(visible.map((entityType) => toPublicEntityType(entityType)));
+}
+async function withExistingEntityType(request, ctx) {
+	const entityType = await ctx.entityManager.registry.getEntityType(request.params.name);
+	if (!entityType) return apiError(404, ErrCodeNotFound, `Entity type not found`);
+	request.entityTypeRoute = { entityType };
+	return void 0;
+}
+async function withEntityTypeManagePermission(request, ctx) {
+	const entityType = request.entityTypeRoute?.entityType;
+	if (!entityType) throw new Error(`entity type middleware did not run`);
+	if (await canAccessEntityType(ctx, entityType, `manage`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to manage ${entityType.name}`);
+}
+async function withEntityTypeSpawnPermission(request, ctx) {
+	const entityType = request.entityTypeRoute?.entityType;
+	if (!entityType) throw new Error(`entity type middleware did not run`);
+	if (await canAccessEntityType(ctx, entityType, `spawn`, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn ${entityType.name}`);
+}
+async function withEntityTypeRegistrationPermission(request, ctx) {
+	const parsed = normalizeEntityTypeRequest(routeBody(request));
+	if (!parsed.name) return void 0;
+	const existing = await ctx.entityManager.registry.getEntityType(parsed.name);
+	if (existing) {
+		request.entityTypeRoute = { entityType: existing };
+		if (await canAccessEntityType(ctx, existing, `manage`, request)) return void 0;
+		return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to manage ${existing.name}`);
+	}
+	if (await canRegisterEntityType(ctx, parsed, request)) return void 0;
+	return apiError(401, ErrCodeUnauthorized, `Principal is not allowed to register entity types`);
 }
 async function discoverServeEndpoint(ctx, parsed) {
 	try {
@@ -7386,17 +8619,17 @@ async function discoverServeEndpoint(ctx, parsed) {
 		const manifest = await response.json();
 		if (manifest.name !== parsed.name) return apiError(400, ErrCodeServeEndpointNameMismatch, `Serve endpoint returned name "${manifest.name}" but expected "${parsed.name}"`);
 		manifest.serve_endpoint = parsed.serve_endpoint;
+		manifest.permission_grants = parsed.permission_grants;
 		const entityType = await ctx.entityManager.registerEntityType(normalizeEntityTypeRequest(manifest));
+		await applyRegistrationPermissionGrants(ctx, entityType.name, manifest);
 		return json(toPublicEntityType(entityType), { status: 201 });
 	} catch (err) {
 		if (err instanceof ElectricAgentsError) throw err;
 		return apiError(502, ErrCodeServeEndpointUnreachable, `Failed to reach serve endpoint: ${err instanceof Error ? err.message : String(err)}`);
 	}
 }
-async function getEntityType(request, ctx) {
-	const entityType = await ctx.entityManager.registry.getEntityType(request.params.name);
-	if (!entityType) return apiError(404, ErrCodeNotFound, `Entity type not found`);
-	return json(toPublicEntityType(entityType));
+async function getEntityType(request) {
+	return json(toPublicEntityType(request.entityTypeRoute.entityType));
 }
 async function amendSchemas(request, ctx) {
 	const parsed = routeBody(request);
@@ -7410,6 +8643,47 @@ async function deleteEntityType(request, ctx) {
 	await ctx.entityManager.deleteEntityType(request.params.name);
 	return status(204);
 }
+async function listTypePermissionGrants(request, ctx) {
+	const grants = await ctx.entityManager.registry.listEntityTypePermissionGrants(request.entityTypeRoute.entityType.name);
+	return json({ grants });
+}
+async function createTypePermissionGrant(request, ctx) {
+	const parsed = routeBody(request);
+	const grant = await ctx.entityManager.registry.createEntityTypePermissionGrant({
+		entityType: request.entityTypeRoute.entityType.name,
+		permission: parsed.permission,
+		subjectKind: parsed.subject_kind,
+		subjectValue: parsed.subject_value,
+		expiresAt: parseExpiresAt(parsed.expires_at),
+		createdBy: ctx.principal.url
+	});
+	return json(grant, { status: 201 });
+}
+async function deleteTypePermissionGrant(request, ctx) {
+	const deleted = await ctx.entityManager.registry.deleteEntityTypePermissionGrant(request.entityTypeRoute.entityType.name, parseGrantId(request));
+	return deleted ? status(204) : apiError(404, ErrCodeNotFound, `Grant not found`);
+}
+async function applyRegistrationPermissionGrants(ctx, entityType, request) {
+	for (const grant of request.permission_grants ?? []) await ctx.entityManager.registry.ensureEntityTypePermissionGrant({
+		entityType,
+		permission: grant.permission,
+		subjectKind: grant.subject_kind,
+		subjectValue: grant.subject_value,
+		expiresAt: parseExpiresAt(grant.expires_at),
+		createdBy: ctx.principal.url
+	});
+}
+function parseGrantId(request) {
+	const grantId = Number.parseInt(String(request.params.grantId), 10);
+	if (!Number.isSafeInteger(grantId) || grantId <= 0) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid grant id`, 400);
+	return grantId;
+}
+function parseExpiresAt(value) {
+	if (value === void 0) return void 0;
+	const expiresAt = new Date(value);
+	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
+	return expiresAt;
+}
 function normalizeEntityTypeRequest(parsed) {
 	const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint);
 	return {
@@ -7422,7 +8696,8 @@ function normalizeEntityTypeRequest(parsed) {
 		default_dispatch_policy: parsed.default_dispatch_policy ?? (serveEndpoint ? { targets: [{
 			type: `webhook`,
 			url: serveEndpoint
-		}] } : void 0)
+		}] } : void 0),
+		permission_grants: parsed.permission_grants
 	};
 }
 function toPublicEntityType(entityType) {
@@ -7481,6 +8756,7 @@ function applyCors(response) {
 		`content-type`,
 		`authorization`,
 		`electric-claim-token`,
+		`electric-owner-entity`,
 		ELECTRIC_PRINCIPAL_HEADER,
 		`ngrok-skip-browser-warning`
 	].join(`, `));
@@ -7531,7 +8807,7 @@ observationsRouter.post(`/entities/ensure-stream`, withSchema(ensureEntitiesMemb
 observationsRouter.post(`/cron/ensure-stream`, withSchema(ensureCronStreamBodySchema), ensureCronStream);
 async function ensureEntitiesMembershipStream(request, ctx) {
 	const parsed = routeBody(request);
-	const result = await ctx.entityManager.ensureEntitiesMembershipStream(parsed.tags ?? {});
+	const result = await ctx.entityManager.ensureEntitiesMembershipStream(parsed.tags ?? {}, ctx.principal);
 	return json(result);
 }
 async function ensureCronStream(request, ctx) {
@@ -7548,6 +8824,12 @@ function withLeadingSlash(path$1) {
 
 //#endregion
 //#region src/routing/runners-router.ts
+const sandboxProfileBodySchema = Type.Object({
+	name: Type.String(),
+	label: Type.String(),
+	description: Type.Optional(Type.String()),
+	remote: Type.Optional(Type.Boolean())
+});
 const registerRunnerBodySchema = Type.Object({
 	id: Type.String(),
 	owner_principal: Type.Optional(Type.String()),
@@ -7560,7 +8842,8 @@ const registerRunnerBodySchema = Type.Object({
 		Type.Literal(`server`)
 	])),
 	admin_status: Type.Optional(Type.Union([Type.Literal(`enabled`), Type.Literal(`disabled`)])),
-	wake_stream: Type.Optional(Type.String())
+	wake_stream: Type.Optional(Type.String()),
+	sandbox_profiles: Type.Optional(Type.Array(sandboxProfileBodySchema))
 });
 const heartbeatBodySchema = Type.Object({
 	lease_ms: Type.Optional(Type.Number()),
@@ -7658,7 +8941,8 @@ async function registerRunner(request, ctx) {
 		label: parsed.label,
 		kind: parsed.kind,
 		adminStatus: parsed.admin_status,
-		wakeStream: parsed.wake_stream
+		wakeStream: parsed.wake_stream,
+		sandboxProfiles: parsed.sandbox_profiles
 	});
 	await ctx.streamClient.ensure(runner.wake_stream, { contentType: `application/json` });
 	return json(runner, { status: 201 });
@@ -7888,6 +9172,7 @@ async function notificationFromClaim(ctx, input) {
 			streams: entity.streams,
 			tags: entity.tags,
 			spawnArgs: entity.spawn_args,
+			sandbox: entity.sandbox,
 			createdBy: entity.created_by
 		},
 		principal: principalFromCreatedBy(entity.created_by)