@electric-ax/agents-server 0.4.17 → 0.4.19

package/dist/entrypoint.js

@@ -2235,7 +2235,10 @@ async function authorizeDurableStreamAccess(request, ctx) {
 	}
 	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;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) {
+			if (ownerEntityUrl) await ctx.entityManager.registry.replaceSharedStateLink(ownerEntityUrl, `shared-state:${sharedStateId}`, sharedStateId);
+			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`);
@@ -3973,9 +3976,10 @@ var EntityManager = class {
 		const workLocks = new Set();
 		const writeEntityLocks = new Set();
 		const writeStreamLocks = new Set();
+		const usePointerPath = opts.forkPointer !== void 0 || opts.anchor !== void 0;
 		try {
 			let sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				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);
@@ -3984,10 +3988,13 @@ var EntityManager = class {
 			const sourceRoot = sourceTree[0];
 			if (sourceRoot.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
 			let preFilteredRoot;
-			if (opts.forkPointer) {
+			let effectiveForkPointer = opts.forkPointer;
+			if (usePointerPath) {
 				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);
+				if (!effectiveForkPointer && opts.anchor === `latest_completed_run`) effectiveForkPointer = this.resolveLatestCompletedRunPointer(flat, sourceRoot.streams.main);
+				if (!effectiveForkPointer) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Internal: pointer-path fork with no resolved pointer`, 500);
+				const target = this.resolveForkPointerTarget(flat, effectiveForkPointer, sourceRoot.streams.main);
 				const filteredEvents = flat.slice(0, target);
 				const rootManifests = this.reduceStateRows(filteredEvents, `manifest`);
 				const sharedStateIds = new Set();
@@ -4000,7 +4007,7 @@ var EntityManager = class {
 				};
 			}
 			const effectiveSubtree = preFilteredRoot ? this.computeEffectiveSubtree(sourceTree, sourceRoot.url, preFilteredRoot.manifests) : sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				const descendants = effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url);
 				if (descendants.length > 0) await this.waitForGivenEntitiesIdle(descendants, opts, workLocks);
 			}
@@ -4025,6 +4032,14 @@ var EntityManager = class {
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
 			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap, opts.createdBy);
+			const rootPlanForOverrides = entityPlans.find((plan) => plan.source.url === rootUrl);
+			if (rootPlanForOverrides) {
+				if (opts.parent !== void 0) rootPlanForOverrides.fork.parent = opts.parent;
+				if (opts.tags !== void 0) rootPlanForOverrides.fork.tags = {
+					...rootPlanForOverrides.fork.tags ?? {},
+					...opts.tags
+				};
+			}
 			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => getSharedStateStreamPath(id)), writeStreamLocks);
 			const createdStreams = [];
@@ -4033,7 +4048,7 @@ var EntityManager = class {
 			try {
 				for (const plan of entityPlans) {
 					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);
+					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && effectiveForkPointer ? { forkPointer: effectiveForkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
 				}
 				for (const [sourceId, forkId] of sharedStateIdMap) {
@@ -4060,6 +4075,20 @@ var EntityManager = class {
 					await this.registry.createEntity(plan.fork);
 					createdEntities.push(plan.fork.url);
 				}
+				if (opts.wake !== void 0) {
+					const rootPlan = entityPlans.find((plan) => plan.source.url === rootUrl);
+					if (rootPlan) await this.wakeRegistry.register({
+						tenantId: this.tenantId,
+						subscriberUrl: opts.wake.subscriberUrl,
+						sourceUrl: rootPlan.fork.url,
+						condition: opts.wake.condition,
+						debounceMs: opts.wake.debounceMs,
+						timeoutMs: opts.wake.timeoutMs,
+						oneShot: false,
+						includeResponse: opts.wake.includeResponse,
+						manifestKey: opts.wake.manifestKey
+					});
+				}
 				for (const plan of entityPlans) {
 					const manifests = activeManifestsByEntity.get(plan.fork.url) ?? new Map();
 					await this.materializeForkManifestSideEffects(plan.fork.url, manifests);
@@ -4220,6 +4249,45 @@ var EntityManager = class {
 		return positionAtAnchor + pointer.subOffset;
 	}
 	/**
+	* Find an `EventPointer` that addresses the most recent `runs` row on
+	* the source's `main` stream with `status === 'completed'`. Mirrors the
+	* eligibility rule the per-row "Fork from here" UI applies — only
+	* completed runs are valid fork anchors; `started`/`failed` rows are
+	* skipped.
+	*
+	* The pointer is computed in the same coordinate system the runtime
+	* mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+	* R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+	* `P` is the END offset of the log entry preceding E (or `null` for
+	* stream start) and `K` is R's 1-indexed position within E.
+	*/
+	resolveLatestCompletedRunPointer(events, streamPath) {
+		let priorEntryOffset = null;
+		let currentEntryOffset = null;
+		let positionInEntry = 0;
+		let latest = null;
+		for (const event of events) {
+			const headers = isRecord(event.headers) ? event.headers : void 0;
+			const eventOffset = typeof headers?.offset === `string` ? headers.offset : null;
+			if (eventOffset !== currentEntryOffset) {
+				priorEntryOffset = currentEntryOffset;
+				currentEntryOffset = eventOffset;
+				positionInEntry = 0;
+			}
+			positionInEntry++;
+			if (event.type !== `run`) continue;
+			if (headers?.operation === `delete`) continue;
+			if (!isRecord(event.value)) continue;
+			if (event.value.status !== `completed`) continue;
+			latest = {
+				offset: priorEntryOffset,
+				subOffset: positionInEntry
+			};
+		}
+		if (!latest) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Source ${streamPath} has no completed run to fork from`, 400);
+		return latest;
+	}
+	/**
 	* 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
@@ -5726,6 +5794,14 @@ function agentUrlPath(value) {
 		return value;
 	}
 }
+async function hasValidAgentWriteToken(request, ctx, fromAgent) {
+	const agentUrl = agentUrlPath(fromAgent);
+	const token = writeTokenFromRequest(request);
+	if (!token) return false;
+	const agentEntity = await ctx.entityManager.registry.getEntity(agentUrl);
+	if (!agentEntity) return false;
+	return ctx.entityManager.isValidWriteToken(agentEntity, token);
+}
 const inboxMessageBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	position: Type.Optional(Type.String()),
@@ -5747,7 +5823,19 @@ const forkBodySchema = Type.Object({
 	fork_pointer: Type.Optional(Type.Object({
 		offset: Type.Union([Type.String(), Type.Null()]),
 		sub_offset: Type.Number()
-	}))
+	})),
+	anchor: Type.Optional(Type.Literal(`latest_completed_run`)),
+	parent: Type.Optional(Type.String()),
+	wake: Type.Optional(Type.Object({
+		subscriberUrl: Type.String(),
+		condition: wakeConditionSchema,
+		debounceMs: Type.Optional(Type.Number()),
+		timeoutMs: Type.Optional(Type.Number()),
+		includeResponse: Type.Optional(Type.Boolean()),
+		manifestKey: Type.Optional(Type.String())
+	})),
+	initialMessage: Type.Optional(Type.Unknown()),
+	tags: Type.Optional(stringRecordSchema$1)
 });
 const setTagBodySchema = Type.Object({ value: Type.String() });
 const entitySignalSchema = Type.Union([
@@ -6134,8 +6222,18 @@ async function forkEntity(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `forked`);
 	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
+	if (parsed.fork_pointer && parsed.anchor) return apiError(400, ErrCodeInvalidRequest, `fork_pointer and anchor are mutually exclusive`);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
+	if (parsed.parent !== 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 apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn children from ${parent.url}`);
+	}
+	if (parsed.wake !== void 0) {
+		if (parsed.parent === void 0) return apiError(400, ErrCodeInvalidRequest, `wake requires parent (the fork's wake fires to its parent)`);
+		if (parsed.wake.subscriberUrl !== parsed.parent) return apiError(401, ErrCodeUnauthorized, `wake.subscriberUrl must match parent`);
+	}
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
 		waitTimeoutMs: parsed.waitTimeoutMs,
@@ -6143,9 +6241,17 @@ async function forkEntity(request, ctx) {
 		...parsed.fork_pointer && { forkPointer: {
 			offset: parsed.fork_pointer.offset,
 			subOffset: parsed.fork_pointer.sub_offset
-		} }
+		} },
+		...parsed.anchor && { anchor: parsed.anchor },
+		...parsed.parent !== void 0 && { parent: parsed.parent },
+		...parsed.wake !== void 0 && { wake: parsed.wake },
+		...parsed.tags !== void 0 && { tags: parsed.tags }
 	});
 	for (const forkedEntity of result.entities) await linkEntityDispatchSubscription(ctx, forkedEntity);
+	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(result.root.url, {
+		from: parsed.parent ?? ctx.principal.url,
+		payload: parsed.initialMessage
+	});
 	return json({
 		root: toPublicEntity(result.root),
 		entities: result.entities.map((entity$1) => toPublicEntity(entity$1))
@@ -6158,7 +6264,10 @@ async function sendEntity(request, ctx) {
 	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`);
+		const fromAgentUrl = agentUrlPath(parsed.from_agent);
+		const matchesPrincipalAgent = fromAgentUrl === principalAgentUrl;
+		const hasAgentWriteToken = await hasValidAgentWriteToken(request, ctx, parsed.from_agent);
+		if (!matchesPrincipalAgent && !hasAgentWriteToken) return apiError(400, ErrCodeInvalidRequest, `Request from_agent must match authenticated agent principal`);
 	}
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);

package/dist/index.cjs

@@ -3664,9 +3664,10 @@ var EntityManager = class {
 		const workLocks = new Set();
 		const writeEntityLocks = new Set();
 		const writeStreamLocks = new Set();
+		const usePointerPath = opts.forkPointer !== void 0 || opts.anchor !== void 0;
 		try {
 			let sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				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);
@@ -3675,10 +3676,13 @@ var EntityManager = class {
 			const sourceRoot = sourceTree[0];
 			if (sourceRoot.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
 			let preFilteredRoot;
-			if (opts.forkPointer) {
+			let effectiveForkPointer = opts.forkPointer;
+			if (usePointerPath) {
 				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);
+				if (!effectiveForkPointer && opts.anchor === `latest_completed_run`) effectiveForkPointer = this.resolveLatestCompletedRunPointer(flat, sourceRoot.streams.main);
+				if (!effectiveForkPointer) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Internal: pointer-path fork with no resolved pointer`, 500);
+				const target = this.resolveForkPointerTarget(flat, effectiveForkPointer, sourceRoot.streams.main);
 				const filteredEvents = flat.slice(0, target);
 				const rootManifests = this.reduceStateRows(filteredEvents, `manifest`);
 				const sharedStateIds = new Set();
@@ -3691,7 +3695,7 @@ var EntityManager = class {
 				};
 			}
 			const effectiveSubtree = preFilteredRoot ? this.computeEffectiveSubtree(sourceTree, sourceRoot.url, preFilteredRoot.manifests) : sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				const descendants = effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url);
 				if (descendants.length > 0) await this.waitForGivenEntitiesIdle(descendants, opts, workLocks);
 			}
@@ -3716,6 +3720,14 @@ var EntityManager = class {
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
 			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap, opts.createdBy);
+			const rootPlanForOverrides = entityPlans.find((plan) => plan.source.url === rootUrl);
+			if (rootPlanForOverrides) {
+				if (opts.parent !== void 0) rootPlanForOverrides.fork.parent = opts.parent;
+				if (opts.tags !== void 0) rootPlanForOverrides.fork.tags = {
+					...rootPlanForOverrides.fork.tags ?? {},
+					...opts.tags
+				};
+			}
 			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => (0, __electric_ax_agents_runtime.getSharedStateStreamPath)(id)), writeStreamLocks);
 			const createdStreams = [];
@@ -3724,7 +3736,7 @@ var EntityManager = class {
 			try {
 				for (const plan of entityPlans) {
 					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);
+					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && effectiveForkPointer ? { forkPointer: effectiveForkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
 				}
 				for (const [sourceId, forkId] of sharedStateIdMap) {
@@ -3751,6 +3763,20 @@ var EntityManager = class {
 					await this.registry.createEntity(plan.fork);
 					createdEntities.push(plan.fork.url);
 				}
+				if (opts.wake !== void 0) {
+					const rootPlan = entityPlans.find((plan) => plan.source.url === rootUrl);
+					if (rootPlan) await this.wakeRegistry.register({
+						tenantId: this.tenantId,
+						subscriberUrl: opts.wake.subscriberUrl,
+						sourceUrl: rootPlan.fork.url,
+						condition: opts.wake.condition,
+						debounceMs: opts.wake.debounceMs,
+						timeoutMs: opts.wake.timeoutMs,
+						oneShot: false,
+						includeResponse: opts.wake.includeResponse,
+						manifestKey: opts.wake.manifestKey
+					});
+				}
 				for (const plan of entityPlans) {
 					const manifests = activeManifestsByEntity.get(plan.fork.url) ?? new Map();
 					await this.materializeForkManifestSideEffects(plan.fork.url, manifests);
@@ -3911,6 +3937,45 @@ var EntityManager = class {
 		return positionAtAnchor + pointer.subOffset;
 	}
 	/**
+	* Find an `EventPointer` that addresses the most recent `runs` row on
+	* the source's `main` stream with `status === 'completed'`. Mirrors the
+	* eligibility rule the per-row "Fork from here" UI applies — only
+	* completed runs are valid fork anchors; `started`/`failed` rows are
+	* skipped.
+	*
+	* The pointer is computed in the same coordinate system the runtime
+	* mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+	* R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+	* `P` is the END offset of the log entry preceding E (or `null` for
+	* stream start) and `K` is R's 1-indexed position within E.
+	*/
+	resolveLatestCompletedRunPointer(events, streamPath) {
+		let priorEntryOffset = null;
+		let currentEntryOffset = null;
+		let positionInEntry = 0;
+		let latest = null;
+		for (const event of events) {
+			const headers = isRecord(event.headers) ? event.headers : void 0;
+			const eventOffset = typeof headers?.offset === `string` ? headers.offset : null;
+			if (eventOffset !== currentEntryOffset) {
+				priorEntryOffset = currentEntryOffset;
+				currentEntryOffset = eventOffset;
+				positionInEntry = 0;
+			}
+			positionInEntry++;
+			if (event.type !== `run`) continue;
+			if (headers?.operation === `delete`) continue;
+			if (!isRecord(event.value)) continue;
+			if (event.value.status !== `completed`) continue;
+			latest = {
+				offset: priorEntryOffset,
+				subOffset: positionInEntry
+			};
+		}
+		if (!latest) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Source ${streamPath} has no completed run to fork from`, 400);
+		return latest;
+	}
+	/**
 	* 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
@@ -7857,7 +7922,10 @@ async function authorizeDurableStreamAccess(request, ctx) {
 	}
 	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;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) {
+			if (ownerEntityUrl) await ctx.entityManager.registry.replaceSharedStateLink(ownerEntityUrl, `shared-state:${sharedStateId}`, sharedStateId);
+			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`);
@@ -8017,6 +8085,14 @@ function agentUrlPath(value) {
 		return value;
 	}
 }
+async function hasValidAgentWriteToken(request, ctx, fromAgent) {
+	const agentUrl = agentUrlPath(fromAgent);
+	const token = writeTokenFromRequest(request);
+	if (!token) return false;
+	const agentEntity = await ctx.entityManager.registry.getEntity(agentUrl);
+	if (!agentEntity) return false;
+	return ctx.entityManager.isValidWriteToken(agentEntity, token);
+}
 const inboxMessageBodySchema = __sinclair_typebox.Type.Object({
 	payload: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Unknown()),
 	position: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
@@ -8038,7 +8114,19 @@ const forkBodySchema = __sinclair_typebox.Type.Object({
 	fork_pointer: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Object({
 		offset: __sinclair_typebox.Type.Union([__sinclair_typebox.Type.String(), __sinclair_typebox.Type.Null()]),
 		sub_offset: __sinclair_typebox.Type.Number()
-	}))
+	})),
+	anchor: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Literal(`latest_completed_run`)),
+	parent: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String()),
+	wake: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Object({
+		subscriberUrl: __sinclair_typebox.Type.String(),
+		condition: wakeConditionSchema,
+		debounceMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
+		timeoutMs: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Number()),
+		includeResponse: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Boolean()),
+		manifestKey: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.String())
+	})),
+	initialMessage: __sinclair_typebox.Type.Optional(__sinclair_typebox.Type.Unknown()),
+	tags: __sinclair_typebox.Type.Optional(stringRecordSchema$1)
 });
 const setTagBodySchema = __sinclair_typebox.Type.Object({ value: __sinclair_typebox.Type.String() });
 const entitySignalSchema = __sinclair_typebox.Type.Union([
@@ -8425,8 +8513,18 @@ async function forkEntity(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `forked`);
 	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
+	if (parsed.fork_pointer && parsed.anchor) return apiError(400, ErrCodeInvalidRequest, `fork_pointer and anchor are mutually exclusive`);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
+	if (parsed.parent !== 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 apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn children from ${parent.url}`);
+	}
+	if (parsed.wake !== void 0) {
+		if (parsed.parent === void 0) return apiError(400, ErrCodeInvalidRequest, `wake requires parent (the fork's wake fires to its parent)`);
+		if (parsed.wake.subscriberUrl !== parsed.parent) return apiError(401, ErrCodeUnauthorized, `wake.subscriberUrl must match parent`);
+	}
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
 		waitTimeoutMs: parsed.waitTimeoutMs,
@@ -8434,9 +8532,17 @@ async function forkEntity(request, ctx) {
 		...parsed.fork_pointer && { forkPointer: {
 			offset: parsed.fork_pointer.offset,
 			subOffset: parsed.fork_pointer.sub_offset
-		} }
+		} },
+		...parsed.anchor && { anchor: parsed.anchor },
+		...parsed.parent !== void 0 && { parent: parsed.parent },
+		...parsed.wake !== void 0 && { wake: parsed.wake },
+		...parsed.tags !== void 0 && { tags: parsed.tags }
 	});
 	for (const forkedEntity of result.entities) await linkEntityDispatchSubscription(ctx, forkedEntity);
+	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(result.root.url, {
+		from: parsed.parent ?? ctx.principal.url,
+		payload: parsed.initialMessage
+	});
 	return (0, itty_router.json)({
 		root: toPublicEntity(result.root),
 		entities: result.entities.map((entity$1) => toPublicEntity(entity$1))
@@ -8449,7 +8555,10 @@ async function sendEntity(request, ctx) {
 	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`);
+		const fromAgentUrl = agentUrlPath(parsed.from_agent);
+		const matchesPrincipalAgent = fromAgentUrl === principalAgentUrl;
+		const hasAgentWriteToken = await hasValidAgentWriteToken(request, ctx, parsed.from_agent);
+		if (!matchesPrincipalAgent && !hasAgentWriteToken) return apiError(400, ErrCodeInvalidRequest, `Request from_agent must match authenticated agent principal`);
 	}
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);

package/dist/index.d.cts

@@ -5245,6 +5245,38 @@ type ForkSubtreeOptions = {
    * `main` stream; shared-state streams clone at HEAD regardless.
    */
   forkPointer?: EventPointer;
+  /**
+   * Named server-resolved anchor. Resolves to a concrete `forkPointer`
+   * by reading the source root's `main` history. Mutually exclusive with
+   * `forkPointer`. Use this when the caller doesn't have access to the
+   * source's per-row pointer side-table (e.g. an agent forking a session
+   * via a tool).
+   *
+   * - `latest_completed_run` — the most recent `runs` row on the source
+   *   with `status === 'completed'`. Errors if no such row exists. This
+   *   is the eligibility rule the per-row "Fork from here" UI uses.
+   */
+  anchor?: `latest_completed_run`;
+  /**
+   * Optional parent URL for the new root fork entity. When set, the
+   * new fork is a CHILD of this URL — its `parent` field is overridden
+   * (rather than inherited from the source, which is `null` for the
+   * only allowed source: a top-level entity). Pairs with `wake` to give
+   * the parent reply-delivery the same way spawn does.
+   */
+  parent?: string;
+  /**
+   * Optional wake subscription registered on the new root fork at fork
+   * time. Same shape and semantics as `spawn`'s `wake` (see
+   * `TypedSpawnRequest.wake`). Typically set by the agent `fork` tool
+   * to wire reply delivery via the parent's manifest-anchored wake.
+   */
+  wake?: TypedSpawnRequest[`wake`];
+  /**
+   * Optional tags stamped onto the new root fork entity in addition
+   * to those copied from the source. Mirrors `spawn`'s `tags`.
+   */
+  tags?: Record<string, string>;
 };
 type ForkResult = {
   root: ElectricAgentsEntity;
@@ -5333,6 +5365,20 @@ declare class EntityManager {
    *   - `pointer.subOffset` is in `[1, total events past the anchor]`.
    */
   private resolveForkPointerTarget;
+  /**
+   * Find an `EventPointer` that addresses the most recent `runs` row on
+   * the source's `main` stream with `status === 'completed'`. Mirrors the
+   * eligibility rule the per-row "Fork from here" UI applies — only
+   * completed runs are valid fork anchors; `started`/`failed` rows are
+   * skipped.
+   *
+   * The pointer is computed in the same coordinate system the runtime
+   * mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+   * R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+   * `P` is the END offset of the log entry preceding E (or `null` for
+   * stream start) and `K` is R's 1-indexed position within E.
+   */
+  private resolveLatestCompletedRunPointer;
   /**
    * Compute the subset of `sourceTree` that survives the manifest filter
    * applied at the root. After filtering the root's manifest at the fork

package/dist/index.d.ts

@@ -5246,6 +5246,38 @@ type ForkSubtreeOptions = {
    * `main` stream; shared-state streams clone at HEAD regardless.
    */
   forkPointer?: EventPointer;
+  /**
+   * Named server-resolved anchor. Resolves to a concrete `forkPointer`
+   * by reading the source root's `main` history. Mutually exclusive with
+   * `forkPointer`. Use this when the caller doesn't have access to the
+   * source's per-row pointer side-table (e.g. an agent forking a session
+   * via a tool).
+   *
+   * - `latest_completed_run` — the most recent `runs` row on the source
+   *   with `status === 'completed'`. Errors if no such row exists. This
+   *   is the eligibility rule the per-row "Fork from here" UI uses.
+   */
+  anchor?: `latest_completed_run`;
+  /**
+   * Optional parent URL for the new root fork entity. When set, the
+   * new fork is a CHILD of this URL — its `parent` field is overridden
+   * (rather than inherited from the source, which is `null` for the
+   * only allowed source: a top-level entity). Pairs with `wake` to give
+   * the parent reply-delivery the same way spawn does.
+   */
+  parent?: string;
+  /**
+   * Optional wake subscription registered on the new root fork at fork
+   * time. Same shape and semantics as `spawn`'s `wake` (see
+   * `TypedSpawnRequest.wake`). Typically set by the agent `fork` tool
+   * to wire reply delivery via the parent's manifest-anchored wake.
+   */
+  wake?: TypedSpawnRequest[`wake`];
+  /**
+   * Optional tags stamped onto the new root fork entity in addition
+   * to those copied from the source. Mirrors `spawn`'s `tags`.
+   */
+  tags?: Record<string, string>;
 };
 type ForkResult = {
   root: ElectricAgentsEntity;
@@ -5334,6 +5366,20 @@ declare class EntityManager {
    *   - `pointer.subOffset` is in `[1, total events past the anchor]`.
    */
   private resolveForkPointerTarget;
+  /**
+   * Find an `EventPointer` that addresses the most recent `runs` row on
+   * the source's `main` stream with `status === 'completed'`. Mirrors the
+   * eligibility rule the per-row "Fork from here" UI applies — only
+   * completed runs are valid fork anchors; `started`/`failed` rows are
+   * skipped.
+   *
+   * The pointer is computed in the same coordinate system the runtime
+   * mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+   * R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+   * `P` is the END offset of the log entry preceding E (or `null` for
+   * stream start) and `K` is R's 1-indexed position within E.
+   */
+  private resolveLatestCompletedRunPointer;
   /**
    * Compute the subset of `sourceTree` that survives the manifest filter
    * applied at the root. After filtering the root's manifest at the fork

package/dist/index.js

@@ -3635,9 +3635,10 @@ var EntityManager = class {
 		const workLocks = new Set();
 		const writeEntityLocks = new Set();
 		const writeStreamLocks = new Set();
+		const usePointerPath = opts.forkPointer !== void 0 || opts.anchor !== void 0;
 		try {
 			let sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				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);
@@ -3646,10 +3647,13 @@ var EntityManager = class {
 			const sourceRoot = sourceTree[0];
 			if (sourceRoot.parent) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Only top-level entities can be forked`, 400);
 			let preFilteredRoot;
-			if (opts.forkPointer) {
+			let effectiveForkPointer = opts.forkPointer;
+			if (usePointerPath) {
 				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);
+				if (!effectiveForkPointer && opts.anchor === `latest_completed_run`) effectiveForkPointer = this.resolveLatestCompletedRunPointer(flat, sourceRoot.streams.main);
+				if (!effectiveForkPointer) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Internal: pointer-path fork with no resolved pointer`, 500);
+				const target = this.resolveForkPointerTarget(flat, effectiveForkPointer, sourceRoot.streams.main);
 				const filteredEvents = flat.slice(0, target);
 				const rootManifests = this.reduceStateRows(filteredEvents, `manifest`);
 				const sharedStateIds = new Set();
@@ -3662,7 +3666,7 @@ var EntityManager = class {
 				};
 			}
 			const effectiveSubtree = preFilteredRoot ? this.computeEffectiveSubtree(sourceTree, sourceRoot.url, preFilteredRoot.manifests) : sourceTree;
-			if (opts.forkPointer) {
+			if (usePointerPath) {
 				const descendants = effectiveSubtree.filter((entity) => entity.url !== sourceRoot.url);
 				if (descendants.length > 0) await this.waitForGivenEntitiesIdle(descendants, opts, workLocks);
 			}
@@ -3687,6 +3691,14 @@ var EntityManager = class {
 			const sharedStateIdMap = await this.buildForkSharedStateIdMap(snapshot.sharedStateIds, suffix);
 			const stringMap = this.buildForkStringMap(entityUrlMap, sharedStateIdMap);
 			const entityPlans = this.buildForkEntityPlans(effectiveSubtree, entityUrlMap, stringMap, opts.createdBy);
+			const rootPlanForOverrides = entityPlans.find((plan) => plan.source.url === rootUrl);
+			if (rootPlanForOverrides) {
+				if (opts.parent !== void 0) rootPlanForOverrides.fork.parent = opts.parent;
+				if (opts.tags !== void 0) rootPlanForOverrides.fork.tags = {
+					...rootPlanForOverrides.fork.tags ?? {},
+					...opts.tags
+				};
+			}
 			this.addForkLocks(this.forkWriteLockedEntities, effectiveSubtree.map((entity) => entity.url), writeEntityLocks);
 			this.addForkLocks(this.forkWriteLockedStreams, [...snapshot.sharedStateIds].map((id) => getSharedStateStreamPath(id)), writeStreamLocks);
 			const createdStreams = [];
@@ -3695,7 +3707,7 @@ var EntityManager = class {
 			try {
 				for (const plan of entityPlans) {
 					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);
+					await this.streamClient.fork(plan.fork.streams.main, plan.source.streams.main, isRoot && effectiveForkPointer ? { forkPointer: effectiveForkPointer } : void 0);
 					createdStreams.push(plan.fork.streams.main);
 				}
 				for (const [sourceId, forkId] of sharedStateIdMap) {
@@ -3722,6 +3734,20 @@ var EntityManager = class {
 					await this.registry.createEntity(plan.fork);
 					createdEntities.push(plan.fork.url);
 				}
+				if (opts.wake !== void 0) {
+					const rootPlan = entityPlans.find((plan) => plan.source.url === rootUrl);
+					if (rootPlan) await this.wakeRegistry.register({
+						tenantId: this.tenantId,
+						subscriberUrl: opts.wake.subscriberUrl,
+						sourceUrl: rootPlan.fork.url,
+						condition: opts.wake.condition,
+						debounceMs: opts.wake.debounceMs,
+						timeoutMs: opts.wake.timeoutMs,
+						oneShot: false,
+						includeResponse: opts.wake.includeResponse,
+						manifestKey: opts.wake.manifestKey
+					});
+				}
 				for (const plan of entityPlans) {
 					const manifests = activeManifestsByEntity.get(plan.fork.url) ?? new Map();
 					await this.materializeForkManifestSideEffects(plan.fork.url, manifests);
@@ -3882,6 +3908,45 @@ var EntityManager = class {
 		return positionAtAnchor + pointer.subOffset;
 	}
 	/**
+	* Find an `EventPointer` that addresses the most recent `runs` row on
+	* the source's `main` stream with `status === 'completed'`. Mirrors the
+	* eligibility rule the per-row "Fork from here" UI applies — only
+	* completed runs are valid fork anchors; `started`/`failed` rows are
+	* skipped.
+	*
+	* The pointer is computed in the same coordinate system the runtime
+	* mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+	* R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+	* `P` is the END offset of the log entry preceding E (or `null` for
+	* stream start) and `K` is R's 1-indexed position within E.
+	*/
+	resolveLatestCompletedRunPointer(events, streamPath) {
+		let priorEntryOffset = null;
+		let currentEntryOffset = null;
+		let positionInEntry = 0;
+		let latest = null;
+		for (const event of events) {
+			const headers = isRecord(event.headers) ? event.headers : void 0;
+			const eventOffset = typeof headers?.offset === `string` ? headers.offset : null;
+			if (eventOffset !== currentEntryOffset) {
+				priorEntryOffset = currentEntryOffset;
+				currentEntryOffset = eventOffset;
+				positionInEntry = 0;
+			}
+			positionInEntry++;
+			if (event.type !== `run`) continue;
+			if (headers?.operation === `delete`) continue;
+			if (!isRecord(event.value)) continue;
+			if (event.value.status !== `completed`) continue;
+			latest = {
+				offset: priorEntryOffset,
+				subOffset: positionInEntry
+			};
+		}
+		if (!latest) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Source ${streamPath} has no completed run to fork from`, 400);
+		return latest;
+	}
+	/**
 	* 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
@@ -7828,7 +7893,10 @@ async function authorizeDurableStreamAccess(request, ctx) {
 	}
 	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;
+		if (await canAccessSharedState(ctx, sharedStateId, `write`, request, ownerEntityUrl)) {
+			if (ownerEntityUrl) await ctx.entityManager.registry.replaceSharedStateLink(ownerEntityUrl, `shared-state:${sharedStateId}`, sharedStateId);
+			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`);
@@ -7988,6 +8056,14 @@ function agentUrlPath(value) {
 		return value;
 	}
 }
+async function hasValidAgentWriteToken(request, ctx, fromAgent) {
+	const agentUrl = agentUrlPath(fromAgent);
+	const token = writeTokenFromRequest(request);
+	if (!token) return false;
+	const agentEntity = await ctx.entityManager.registry.getEntity(agentUrl);
+	if (!agentEntity) return false;
+	return ctx.entityManager.isValidWriteToken(agentEntity, token);
+}
 const inboxMessageBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	position: Type.Optional(Type.String()),
@@ -8009,7 +8085,19 @@ const forkBodySchema = Type.Object({
 	fork_pointer: Type.Optional(Type.Object({
 		offset: Type.Union([Type.String(), Type.Null()]),
 		sub_offset: Type.Number()
-	}))
+	})),
+	anchor: Type.Optional(Type.Literal(`latest_completed_run`)),
+	parent: Type.Optional(Type.String()),
+	wake: Type.Optional(Type.Object({
+		subscriberUrl: Type.String(),
+		condition: wakeConditionSchema,
+		debounceMs: Type.Optional(Type.Number()),
+		timeoutMs: Type.Optional(Type.Number()),
+		includeResponse: Type.Optional(Type.Boolean()),
+		manifestKey: Type.Optional(Type.String())
+	})),
+	initialMessage: Type.Optional(Type.Unknown()),
+	tags: Type.Optional(stringRecordSchema$1)
 });
 const setTagBodySchema = Type.Object({ value: Type.String() });
 const entitySignalSchema = Type.Union([
@@ -8396,8 +8484,18 @@ async function forkEntity(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `forked`);
 	if (principalMutationError) return principalMutationError;
 	const parsed = routeBody(request);
+	if (parsed.fork_pointer && parsed.anchor) return apiError(400, ErrCodeInvalidRequest, `fork_pointer and anchor are mutually exclusive`);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);
 	await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy);
+	if (parsed.parent !== 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 apiError(401, ErrCodeUnauthorized, `Principal is not allowed to spawn children from ${parent.url}`);
+	}
+	if (parsed.wake !== void 0) {
+		if (parsed.parent === void 0) return apiError(400, ErrCodeInvalidRequest, `wake requires parent (the fork's wake fires to its parent)`);
+		if (parsed.wake.subscriberUrl !== parsed.parent) return apiError(401, ErrCodeUnauthorized, `wake.subscriberUrl must match parent`);
+	}
 	const result = await ctx.entityManager.forkSubtree(entityUrl, {
 		rootInstanceId: parsed.instance_id,
 		waitTimeoutMs: parsed.waitTimeoutMs,
@@ -8405,9 +8503,17 @@ async function forkEntity(request, ctx) {
 		...parsed.fork_pointer && { forkPointer: {
 			offset: parsed.fork_pointer.offset,
 			subOffset: parsed.fork_pointer.sub_offset
-		} }
+		} },
+		...parsed.anchor && { anchor: parsed.anchor },
+		...parsed.parent !== void 0 && { parent: parsed.parent },
+		...parsed.wake !== void 0 && { wake: parsed.wake },
+		...parsed.tags !== void 0 && { tags: parsed.tags }
 	});
 	for (const forkedEntity of result.entities) await linkEntityDispatchSubscription(ctx, forkedEntity);
+	if (parsed.initialMessage !== void 0) await ctx.entityManager.send(result.root.url, {
+		from: parsed.parent ?? ctx.principal.url,
+		payload: parsed.initialMessage
+	});
 	return json({
 		root: toPublicEntity(result.root),
 		entities: result.entities.map((entity$1) => toPublicEntity(entity$1))
@@ -8420,7 +8526,10 @@ async function sendEntity(request, ctx) {
 	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`);
+		const fromAgentUrl = agentUrlPath(parsed.from_agent);
+		const matchesPrincipalAgent = fromAgentUrl === principalAgentUrl;
+		const hasAgentWriteToken = await hasValidAgentWriteToken(request, ctx, parsed.from_agent);
+		if (!matchesPrincipalAgent && !hasAgentWriteToken) return apiError(400, ErrCodeInvalidRequest, `Request from_agent must match authenticated agent principal`);
 	}
 	await ctx.entityManager.ensurePrincipal(principal);
 	const { entityUrl, entity } = requireExistingEntityRoute(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@electric-ax/agents-server",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Electric Agents entity runtime server",
   "author": "Durable Stream contributors",
   "bin": {
@@ -54,7 +54,7 @@
     "pino-pretty": "^13.0.0",
     "postgres": "^3.4.0",
     "undici": "^7.24.7",
-    "@electric-ax/agents-runtime": "0.3.10"
+    "@electric-ax/agents-runtime": "0.3.12"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
@@ -65,9 +65,9 @@
     "tsx": "^4.19.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
-    "@electric-ax/agents": "0.4.14",
-    "@electric-ax/agents-server-ui": "0.4.17",
-    "@electric-ax/agents-server-conformance-tests": "0.1.11"
+    "@electric-ax/agents": "0.4.16",
+    "@electric-ax/agents-server-conformance-tests": "0.1.11",
+    "@electric-ax/agents-server-ui": "0.4.19"
   },
   "files": [
     "dist",

package/src/entity-manager.ts

@@ -175,6 +175,38 @@ type ForkSubtreeOptions = {
    * `main` stream; shared-state streams clone at HEAD regardless.
    */
   forkPointer?: EventPointer
+  /**
+   * Named server-resolved anchor. Resolves to a concrete `forkPointer`
+   * by reading the source root's `main` history. Mutually exclusive with
+   * `forkPointer`. Use this when the caller doesn't have access to the
+   * source's per-row pointer side-table (e.g. an agent forking a session
+   * via a tool).
+   *
+   * - `latest_completed_run` — the most recent `runs` row on the source
+   *   with `status === 'completed'`. Errors if no such row exists. This
+   *   is the eligibility rule the per-row "Fork from here" UI uses.
+   */
+  anchor?: `latest_completed_run`
+  /**
+   * Optional parent URL for the new root fork entity. When set, the
+   * new fork is a CHILD of this URL — its `parent` field is overridden
+   * (rather than inherited from the source, which is `null` for the
+   * only allowed source: a top-level entity). Pairs with `wake` to give
+   * the parent reply-delivery the same way spawn does.
+   */
+  parent?: string
+  /**
+   * Optional wake subscription registered on the new root fork at fork
+   * time. Same shape and semantics as `spawn`'s `wake` (see
+   * `TypedSpawnRequest.wake`). Typically set by the agent `fork` tool
+   * to wire reply delivery via the parent's manifest-anchored wake.
+   */
+  wake?: TypedSpawnRequest[`wake`]
+  /**
+   * Optional tags stamped onto the new root fork entity in addition
+   * to those copied from the source. Mirrors `spawn`'s `tags`.
+   */
+  tags?: Record<string, string>
 }
 
 type ForkEntityPlan = {
@@ -909,6 +941,13 @@ export class EntityManager {
     const writeEntityLocks = new Set<string>()
     const writeStreamLocks = new Set<string>()
 
+    // Anchor-forks resolve to a concrete pointer server-side by reading the
+    // source's `main` history. Below this point the resolved pointer (or
+    // an explicit one from `opts.forkPointer`) drives the same code path —
+    // anchor handling collapses entirely into the pointer-fork flow.
+    const usePointerPath =
+      opts.forkPointer !== undefined || opts.anchor !== undefined
+
     try {
       // For pointer-forks we read the source root HISTORICALLY at a
       // frozen offset, so concurrent activity on the root past the
@@ -920,7 +959,7 @@ export class EntityManager {
       // those are HEAD-cloned and need a stable snapshot. For HEAD-forks
       // the old all-idle requirement still applies.
       let sourceTree: Array<ElectricAgentsEntity>
-      if (opts.forkPointer) {
+      if (usePointerPath) {
         const rootEntity = await this.registry.getEntity(rootUrl)
         if (!rootEntity) {
           throw new ElectricAgentsError(
@@ -949,11 +988,11 @@ export class EntityManager {
         )
       }
 
-      // When forking at a pointer, pre-read the root's main, validate the
-      // pointer against the source's true history, and materialise the
-      // root-at-pointer snapshot fragments. The pointer only applies to
-      // the root's `main` stream. Descendants kept by the manifest filter
-      // are forked at HEAD.
+      // When forking at a pointer (or anchor), pre-read the root's main,
+      // validate the pointer against the source's true history, and
+      // materialise the root-at-pointer snapshot fragments. The pointer
+      // only applies to the root's `main` stream. Descendants kept by
+      // the manifest filter are forked at HEAD.
       //
       // Pointer→position translation: the runtime mints pointers as
       // `{ offset: previousBatchOffset, subOffset: itemIndex+1 }`, where
@@ -972,16 +1011,32 @@ export class EntityManager {
             sharedStateIds: Set<string>
           }
         | undefined
-      if (opts.forkPointer) {
+      let effectiveForkPointer: EventPointer | undefined = opts.forkPointer
+      if (usePointerPath) {
         const sourceEvents = await this.streamClient.readJson<
           Record<string, unknown>
         >(sourceRoot.streams.main)
         const flat = sourceEvents.flatMap((item) =>
           Array.isArray(item) ? item : [item]
         ) as Array<Record<string, unknown>>
+        if (!effectiveForkPointer && opts.anchor === `latest_completed_run`) {
+          effectiveForkPointer = this.resolveLatestCompletedRunPointer(
+            flat,
+            sourceRoot.streams.main
+          )
+        }
+        if (!effectiveForkPointer) {
+          // Defensive — would only fire on a future anchor variant we
+          // forget to handle above.
+          throw new ElectricAgentsError(
+            ErrCodeInvalidRequest,
+            `Internal: pointer-path fork with no resolved pointer`,
+            500
+          )
+        }
         const target = this.resolveForkPointerTarget(
           flat,
-          opts.forkPointer,
+          effectiveForkPointer,
           sourceRoot.streams.main
         )
         const filteredEvents = flat.slice(0, target)
@@ -1013,7 +1068,7 @@ export class EntityManager {
       // subtree except the root) are HEAD-cloned, so they must be idle
       // before we read their snapshots. Wait+lock only those — the root
       // was skipped above.
-      if (opts.forkPointer) {
+      if (usePointerPath) {
         const descendants = effectiveSubtree.filter(
           (entity) => entity.url !== sourceRoot.url
         )
@@ -1066,6 +1121,28 @@ export class EntityManager {
         opts.createdBy
       )
 
+      // Override fields on the new root fork's plan from caller opts.
+      // Plumbed through from `forkBodySchema` — descendants in
+      // `effectiveSubtree` keep what `buildForkEntityPlans` copied.
+      //
+      // - `parent`: child-fork relationship (vs the default inheritance
+      //   from the source, which is `null` for a top-level source).
+      // - `tags`: merged on top of source tags (caller-supplied wins).
+      const rootPlanForOverrides = entityPlans.find(
+        (plan) => plan.source.url === rootUrl
+      )
+      if (rootPlanForOverrides) {
+        if (opts.parent !== undefined) {
+          rootPlanForOverrides.fork.parent = opts.parent
+        }
+        if (opts.tags !== undefined) {
+          rootPlanForOverrides.fork.tags = {
+            ...(rootPlanForOverrides.fork.tags ?? {}),
+            ...opts.tags,
+          }
+        }
+      }
+
       this.addForkLocks(
         this.forkWriteLockedEntities,
         effectiveSubtree.map((entity) => entity.url),
@@ -1090,8 +1167,8 @@ export class EntityManager {
           await this.streamClient.fork(
             plan.fork.streams.main,
             plan.source.streams.main,
-            isRoot && opts.forkPointer
-              ? { forkPointer: opts.forkPointer }
+            isRoot && effectiveForkPointer
+              ? { forkPointer: effectiveForkPointer }
               : undefined
           )
           createdStreams.push(plan.fork.streams.main)
@@ -1146,6 +1223,30 @@ export class EntityManager {
           createdEntities.push(plan.fork.url)
         }
 
+        // Register a wake subscription on the new root fork when the
+        // caller asked for one. Mirrors the spawn flow's wake handling
+        // (entity-manager.spawnInner). Rollback below already calls
+        // `wakeRegistry.unregisterBySource(forkUrl)` for every created
+        // entity, so this cleans up automatically on failure.
+        if (opts.wake !== undefined) {
+          const rootPlan = entityPlans.find(
+            (plan) => plan.source.url === rootUrl
+          )
+          if (rootPlan) {
+            await this.wakeRegistry.register({
+              tenantId: this.tenantId,
+              subscriberUrl: opts.wake.subscriberUrl,
+              sourceUrl: rootPlan.fork.url,
+              condition: opts.wake.condition,
+              debounceMs: opts.wake.debounceMs,
+              timeoutMs: opts.wake.timeoutMs,
+              oneShot: false,
+              includeResponse: opts.wake.includeResponse,
+              manifestKey: opts.wake.manifestKey,
+            })
+          }
+        }
+
         for (const plan of entityPlans) {
           const manifests =
             activeManifestsByEntity.get(plan.fork.url) ?? new Map()
@@ -1461,6 +1562,58 @@ export class EntityManager {
     return positionAtAnchor + pointer.subOffset
   }
 
+  /**
+   * Find an `EventPointer` that addresses the most recent `runs` row on
+   * the source's `main` stream with `status === 'completed'`. Mirrors the
+   * eligibility rule the per-row "Fork from here" UI applies — only
+   * completed runs are valid fork anchors; `started`/`failed` rows are
+   * skipped.
+   *
+   * The pointer is computed in the same coordinate system the runtime
+   * mints pointers in (see entity-stream-db's onBeforeBatch): for a row
+   * R in log entry E, the pointer is `{ offset: P, subOffset: K }` where
+   * `P` is the END offset of the log entry preceding E (or `null` for
+   * stream start) and `K` is R's 1-indexed position within E.
+   */
+  private resolveLatestCompletedRunPointer(
+    events: ReadonlyArray<Record<string, unknown>>,
+    streamPath: string
+  ): EventPointer {
+    let priorEntryOffset: string | null = null
+    let currentEntryOffset: string | null = null
+    let positionInEntry = 0
+    let latest: EventPointer | null = null
+
+    for (const event of events) {
+      const headers = isRecord(event.headers) ? event.headers : undefined
+      const eventOffset =
+        typeof headers?.offset === `string` ? headers.offset : null
+
+      if (eventOffset !== currentEntryOffset) {
+        priorEntryOffset = currentEntryOffset
+        currentEntryOffset = eventOffset
+        positionInEntry = 0
+      }
+      positionInEntry++
+
+      if (event.type !== `run`) continue
+      if (headers?.operation === `delete`) continue
+      if (!isRecord(event.value)) continue
+      if (event.value.status !== `completed`) continue
+
+      latest = { offset: priorEntryOffset, subOffset: positionInEntry }
+    }
+
+    if (!latest) {
+      throw new ElectricAgentsError(
+        ErrCodeInvalidRequest,
+        `Source ${streamPath} has no completed run to fork from`,
+        400
+      )
+    }
+    return latest
+  }
+
   /**
    * Compute the subset of `sourceTree` that survives the manifest filter
    * applied at the root. After filtering the root's manifest at the fork

package/src/routing/durable-streams-router.ts

@@ -717,6 +717,19 @@ async function authorizeDurableStreamAccess(
         ownerEntityUrl
       )
     ) {
+      // Bootstrap the link synchronously so subsequent reads on this stream
+      // (e.g. the runtime's preload right after `mkdb`) can resolve the owner
+      // without waiting for the entity's manifest stream event to be
+      // processed eventually-consistently. Without this, a brand-new
+      // shared-state always 401s on the first preload because the link row
+      // is only created later via `applyManifestEntitySource`.
+      if (ownerEntityUrl) {
+        await ctx.entityManager.registry.replaceSharedStateLink(
+          ownerEntityUrl,
+          `shared-state:${sharedStateId}`,
+          sharedStateId
+        )
+      }
       return undefined
     }
     return apiError(

package/src/routing/entities-router.ts

@@ -187,6 +187,19 @@ function agentUrlPath(value: string): string {
   }
 }
 
+async function hasValidAgentWriteToken(
+  request: AgentsRouteRequest,
+  ctx: TenantContext,
+  fromAgent: string
+): Promise<boolean> {
+  const agentUrl = agentUrlPath(fromAgent)
+  const token = writeTokenFromRequest(request)
+  if (!token) return false
+  const agentEntity = await ctx.entityManager.registry.getEntity(agentUrl)
+  if (!agentEntity) return false
+  return ctx.entityManager.isValidWriteToken(agentEntity, token)
+}
+
 const inboxMessageBodySchema = Type.Object({
   payload: Type.Optional(Type.Unknown()),
   position: Type.Optional(Type.String()),
@@ -219,6 +232,41 @@ const forkBodySchema = Type.Object({
       sub_offset: Type.Number(),
     })
   ),
+  // Named server-resolved anchor. Resolves to a concrete fork pointer on
+  // the source root's `main` server-side, so callers don't need access
+  // to the source's per-row pointer side-table. Mutually exclusive with
+  // `fork_pointer`.
+  anchor: Type.Optional(Type.Literal(`latest_completed_run`)),
+  // Optional parent URL. When set, the new root fork is a CHILD of this
+  // URL (rather than inheriting the source's parent, which is `null`
+  // for the only allowed source — a top-level entity). Used by the
+  // agent `fork` tool to make a forking entity own its forks the same
+  // way a spawning entity owns its workers.
+  parent: Type.Optional(Type.String()),
+  // Optional wake subscription registered on the new root fork at fork
+  // time. Mirrors the `wake` field on spawn — the subscriber URL gets
+  // woken when the fork meets the named condition, with the response
+  // optionally inlined. Used to wire fork-as-child reply delivery
+  // through the same manifest-anchored mechanism spawn uses.
+  wake: Type.Optional(
+    Type.Object({
+      subscriberUrl: Type.String(),
+      condition: wakeConditionSchema,
+      debounceMs: Type.Optional(Type.Number()),
+      timeoutMs: Type.Optional(Type.Number()),
+      includeResponse: Type.Optional(Type.Boolean()),
+      manifestKey: Type.Optional(Type.String()),
+    })
+  ),
+  // Optional initial inbox message for the new root fork. Folds
+  // fork+send into one round-trip for the caller. Not atomic with
+  // fork creation: the server sends it after the fork is created
+  // and dispatch-linked (see the `entityManager.send` call below),
+  // so a failed send can leave an idle dispatched fork.
+  initialMessage: Type.Optional(Type.Unknown()),
+  // Optional tags stamped on the new root fork entity in addition to
+  // those copied from the source. Mirrors spawn's `tags`.
+  tags: Type.Optional(stringRecordSchema),
 })
 
 const setTagBodySchema = Type.Object({
@@ -1088,8 +1136,57 @@ async function forkEntity(
   if (principalMutationError) return principalMutationError
 
   const parsed = routeBody<ForkBody>(request)
+  if (parsed.fork_pointer && parsed.anchor) {
+    return apiError(
+      400,
+      ErrCodeInvalidRequest,
+      `fork_pointer and anchor are mutually exclusive`
+    )
+  }
   const { entityUrl, entity } = requireExistingEntityRoute(request)
   await assertDispatchPolicyAllowed(ctx, entity.dispatch_policy)
+
+  // Validate `parent` and `wake.subscriberUrl` before forking — mirrors
+  // the spawn route's parent-validation flow. Without these checks, a
+  // direct HTTP caller could attach a fork under an arbitrary parent or
+  // register a wake firing to an arbitrary subscriber.
+  if (parsed.parent !== undefined) {
+    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 as Request))) {
+      return apiError(
+        401,
+        ErrCodeUnauthorized,
+        `Principal is not allowed to spawn children from ${parent.url}`
+      )
+    }
+  }
+  if (parsed.wake !== undefined) {
+    // The only sensible target for a fork's wake is the new fork's
+    // parent (so the parent gets woken when the fork's run finishes
+    // — same model as spawn). Require parent + matching subscriber to
+    // prevent a caller from registering a wake firing to an entity
+    // they don't own. If subscriber-flexibility ever becomes a real
+    // use case, replace this with a proper canAccessEntity check on
+    // the subscriber.
+    if (parsed.parent === undefined) {
+      return apiError(
+        400,
+        ErrCodeInvalidRequest,
+        `wake requires parent (the fork's wake fires to its parent)`
+      )
+    }
+    if (parsed.wake.subscriberUrl !== parsed.parent) {
+      return apiError(
+        401,
+        ErrCodeUnauthorized,
+        `wake.subscriberUrl must match parent`
+      )
+    }
+  }
+
   const result = await ctx.entityManager.forkSubtree(entityUrl, {
     rootInstanceId: parsed.instance_id,
     waitTimeoutMs: parsed.waitTimeoutMs,
@@ -1100,10 +1197,24 @@ async function forkEntity(
         subOffset: parsed.fork_pointer.sub_offset,
       },
     }),
+    ...(parsed.anchor && { anchor: parsed.anchor }),
+    ...(parsed.parent !== undefined && { parent: parsed.parent }),
+    ...(parsed.wake !== undefined && { wake: parsed.wake }),
+    ...(parsed.tags !== undefined && { tags: parsed.tags }),
   })
   for (const forkedEntity of result.entities) {
     await linkEntityDispatchSubscription(ctx, forkedEntity)
   }
+  // Deliver the initial message via entityManager.send AFTER the
+  // dispatch subscription is linked — same ordering spawn uses. Sending
+  // before linking would land the inbox row on the stream before the
+  // dispatcher is subscribed, and the dispatcher would never pick it up.
+  if (parsed.initialMessage !== undefined) {
+    await ctx.entityManager.send(result.root.url, {
+      from: parsed.parent ?? ctx.principal.url,
+      payload: parsed.initialMessage,
+    })
+  }
   return json(
     {
       root: toPublicEntity(result.root),
@@ -1138,7 +1249,14 @@ async function sendEntity(
   }
   if (parsed.from_agent !== undefined) {
     const principalAgentUrl = agentUrlForPrincipal(principal)
-    if (agentUrlPath(parsed.from_agent) !== principalAgentUrl) {
+    const fromAgentUrl = agentUrlPath(parsed.from_agent)
+    const matchesPrincipalAgent = fromAgentUrl === principalAgentUrl
+    const hasAgentWriteToken = await hasValidAgentWriteToken(
+      request,
+      ctx,
+      parsed.from_agent
+    )
+    if (!matchesPrincipalAgent && !hasAgentWriteToken) {
       return apiError(
         400,
         ErrCodeInvalidRequest,