@danypops/papyrus 0.11.4 → 0.13.0

package/src/skill-execution.ts

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
-import { SKILL_MAX_RENDERED_BYTES, SKILL_RUN_ID_MAX_LENGTH, TASK_EXECUTION_MAX_EDGES } from "./constants.ts";
+import { SKILL_MAX_RENDERED_BYTES, SKILL_RUN_ID_MAX_LENGTH, SKILL_WORKFLOW_MAX_NESTING_DEPTH, TASK_EXECUTION_MAX_EDGES } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
 import { validateChecklist } from "./domain/checklist.ts";
 import {
 	resolveSkillArguments,
 	validateSkillDefinition,
 	type SkillArgumentValue,
+	type SkillCallBlueprint,
 	type SkillDefinition,
 } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
@@ -35,8 +36,12 @@ export interface SkillWorkflowRunResult {
 		docs: string[];
 		rules: string[];
 		tasks: string[];
+		/** Nested workflow Skill runs this pipeline triggered as pipeline steps, in execution order. */
+		skillRuns: string[];
 	};
+	/** Real starting points: for a nested skill-call root step, that nested run's own root tasks (recursively), not just "all its tasks". */
 	rootTaskIds: string[];
+	/** Scoped to this definition's own directly-created tasks only -- nested runs' tasks are real, graph-linked, and visible via /tasks graph, but not folded into this projection. */
 	execution: TaskExecutionPlan;
 }
 
@@ -115,12 +120,48 @@ function executionGraph(tasks: Artifact[], definition: SkillDefinition, ids: Map
 	return { nodes, rootIds: nodes.filter((node) => node.parentIds.length === 0).map((node) => node.task.id) };
 }
 
+type SkillWorkflowHistory = { events: TaskEventStore; scopes: TaskScopeStore; projectRoot: string; context?: TaskEventContext };
+
+/**
+ * Public entry point: wraps one complete pipeline run (including every nested sub-pipeline
+ * it triggers) in exactly one atomic transaction. The recursive core (runWorkflowSteps) never
+ * opens its own atomic wrapper -- SQLite savepoint nesting (inTransaction in db.ts) would
+ * tolerate it, but wrapping once here keeps the atomicity story unambiguous: one skills.run
+ * call is one all-or-nothing graph mutation, however many nested skills it triggers.
+ */
 export function instantiateSkillWorkflow(
 	artifacts: ArtifactStore,
 	skillId: string,
 	input: InstantiateSkillWorkflowInput = {},
-	history?: { events: TaskEventStore; scopes: TaskScopeStore; projectRoot: string; context?: TaskEventContext },
+	history?: SkillWorkflowHistory,
 ): SkillWorkflowRunResult {
+	const run = () => runWorkflowSteps(artifacts, skillId, input, history, new Set(), 0);
+	if (history) return history.events.atomic(run);
+	return requireAtomicArtifactStore(artifacts).atomic(run);
+}
+
+/**
+ * The recursive pipeline core. A workflow Skill's `skills` blueprint entries are pipeline
+ * steps that trigger another workflow Skill's own run -- the Jenkins "downstream job" /
+ * Ansible "include_tasks" primitive. Nested runs execute BEFORE this level's dependsOn/parent
+ * edges are wired, since a step depending on a skill-call ref needs to know every task id
+ * that nested run actually produced (not knowable ahead of time -- it depends on the nested
+ * skill's own definition). `ancestorSkillIds` tracks the current call CHAIN (not a global
+ * ever-visited set): sibling skill-calls under the same parent are independent and may
+ * legitimately share a called skill; only a real cycle back to an ancestor is rejected.
+ */
+function runWorkflowSteps(
+	artifacts: ArtifactStore,
+	skillId: string,
+	input: InstantiateSkillWorkflowInput,
+	history: SkillWorkflowHistory | undefined,
+	ancestorSkillIds: ReadonlySet<string>,
+	depth: number,
+): SkillWorkflowRunResult {
+	if (ancestorSkillIds.has(skillId)) throw new Error(`skill workflow nesting cycle includes "${skillId}"`);
+	if (depth > SKILL_WORKFLOW_MAX_NESTING_DEPTH) throw new Error(`skill workflow nesting exceeds ${SKILL_WORKFLOW_MAX_NESTING_DEPTH} levels`);
+	const nextAncestors = new Set([...ancestorSkillIds, skillId]);
+
 	const { definition } = requireWorkflowSkill(artifacts, skillId);
 	const projectRoot = history ? normalizeProjectRoot(history.projectRoot) : undefined;
 	const arguments_ = resolveSkillArguments(definition, input.arguments);
@@ -130,97 +171,150 @@ export function instantiateSkillWorkflow(
 		...rendered.blueprints.docs.map(({ ref }) => ref),
 		...rendered.blueprints.rules.map(({ ref }) => ref),
 		...rendered.blueprints.tasks.map(({ ref }) => ref),
+		...rendered.blueprints.skills.map(({ ref }) => ref),
 	];
 	const ids = new Map(refs.map((ref) => [ref, `${runId}-${ref}`]));
 	const taskIds = rendered.blueprints.tasks.map(({ ref }) => ids.get(ref)!);
-	const rootTaskIds = rendered.blueprints.tasks
-		.filter((task) => (task.dependsOn?.length ?? 0) === 0)
-		.map((task) => ids.get(task.ref)!);
+	// A bound at THIS level's own blueprint size; nested runs are independently bounded the same
+	// way at their own level, and nesting depth is separately capped -- so total blast radius
+	// across a whole pipeline stays bounded on both dimensions even though a step's dependency
+	// on a skill-call ref can fan out to more edges than this per-level count captures exactly.
 	const relationshipCount = rendered.links.length
 		+ rendered.blueprints.tasks.reduce((count, task) => count + (task.dependsOn?.length ?? 0) + (task.parent ? 2 : 0), 0)
-		+ rootTaskIds.length;
+		+ rendered.blueprints.skills.reduce((count, call) => count + (call.dependsOn?.length ?? 0) + (call.parent ? 2 : 0), 0)
+		+ rendered.blueprints.tasks.filter((task) => (task.dependsOn?.length ?? 0) === 0).length
+		+ rendered.blueprints.skills.filter((call) => (call.dependsOn?.length ?? 0) === 0).length;
 	if (relationshipCount > TASK_EXECUTION_MAX_EDGES) {
 		throw new Error(`skill workflow run exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
 	}
 
-	const atomic = requireAtomicArtifactStore(artifacts);
-	const persist = () => atomic.atomic(() => {
-		const docs = rendered.blueprints.docs.map((blueprint) => artifacts.create({
+	const docs = rendered.blueprints.docs.map((blueprint) => artifacts.create({
+		id: ids.get(blueprint.ref),
+		kind: "doc",
+		title: blueprint.title,
+		body: blueprint.body,
+		subtype: blueprint.subtype,
+		labels: withRunLabel(blueprint.labels, runId),
+		extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
+	}));
+	const rules = rendered.blueprints.rules.map((blueprint) => artifacts.create({
+		id: ids.get(blueprint.ref),
+		kind: "rule",
+		title: blueprint.title,
+		body: blueprint.body,
+		labels: withRunLabel(blueprint.labels, runId),
+		extra: {
+			...(blueprint.extra ?? {}),
+			...(blueprint.condition ? { condition: blueprint.condition } : {}),
+			...(blueprint.action ? { action: blueprint.action } : {}),
+			...(blueprint.severity ? { severity: blueprint.severity } : {}),
+			skillRun: { id: runId, skillId, ref: blueprint.ref },
+			scope: { type: "skill-run", runId, taskIds },
+		},
+	}));
+	const tasks = rendered.blueprints.tasks.map((blueprint) => {
+		const task = artifacts.create({
 			id: ids.get(blueprint.ref),
-			kind: "doc",
+			kind: "task",
 			title: blueprint.title,
 			body: blueprint.body,
-			subtype: blueprint.subtype,
 			labels: withRunLabel(blueprint.labels, runId),
 			extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
-		}));
-		const rules = rendered.blueprints.rules.map((blueprint) => artifacts.create({
-			id: ids.get(blueprint.ref),
-			kind: "rule",
-			title: blueprint.title,
-			body: blueprint.body,
-			labels: withRunLabel(blueprint.labels, runId),
-			extra: {
-				...(blueprint.extra ?? {}),
-				...(blueprint.condition ? { condition: blueprint.condition } : {}),
-				...(blueprint.action ? { action: blueprint.action } : {}),
-				...(blueprint.severity ? { severity: blueprint.severity } : {}),
-				skillRun: { id: runId, skillId, ref: blueprint.ref },
-				scope: { type: "skill-run", runId, taskIds },
-			},
-		}));
-		const tasks = rendered.blueprints.tasks.map((blueprint) => {
-			const task = artifacts.create({
-				id: ids.get(blueprint.ref),
-				kind: "task",
-				title: blueprint.title,
-				body: blueprint.body,
-				labels: withRunLabel(blueprint.labels, runId),
-				extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
-			});
-			if (history) {
-				history.scopes.assign(task.id, projectRoot, "cwd");
-				history.events.append({
-					taskId: task.id,
-					type: "created",
-					actor: history.context?.actor ?? "system",
-					source: history.context?.source ?? "skill-run",
-					toStatus: task.status as TaskStatus,
-					...(history.context?.sessionId === undefined ? {} : { sessionId: history.context.sessionId }),
-					...(history.context?.reason === undefined ? {} : { reason: history.context.reason }),
-				});
-			}
-			return task;
 		});
+		if (history) {
+			history.scopes.assign(task.id, projectRoot, "cwd");
+			history.events.append({
+				taskId: task.id,
+				type: "created",
+				actor: history.context?.actor ?? "system",
+				source: history.context?.source ?? "skill-run",
+				toStatus: task.status as TaskStatus,
+				...(history.context?.sessionId === undefined ? {} : { sessionId: history.context.sessionId }),
+				...(history.context?.reason === undefined ? {} : { reason: history.context.reason }),
+			});
+		}
+		return task;
+	});
 
-		for (const blueprint of rendered.blueprints.tasks) {
-			const id = ids.get(blueprint.ref)!;
-			for (const dependency of blueprint.dependsOn ?? []) {
-				artifacts.link({ from: id, relation: "depends_on", to: ids.get(dependency)! });
-			}
-			if (blueprint.parent) {
-				const parentId = ids.get(blueprint.parent)!;
-				artifacts.link({ from: parentId, relation: "contains", to: id });
-				artifacts.link({ from: id, relation: "part_of", to: parentId });
+	// Nested pipeline steps run before edge-wiring: dependents need to know what tasks each
+	// nested run actually produced. stepTaskIds/stepRootTaskIds map EVERY step ref (task or
+	// skill-call) to the task id(s) it resolves to, so dependsOn/parent wiring below treats
+	// both kinds of step uniformly.
+	const nestedRuns: SkillWorkflowRunResult[] = [];
+	const stepTaskIds = new Map<string, string[]>(tasks.map((task, index) => [rendered.blueprints.tasks[index]!.ref, [task.id]]));
+	const stepRootTaskIds = new Map<string, string[]>(
+		tasks.map((task, index) => [rendered.blueprints.tasks[index]!.ref, (rendered.blueprints.tasks[index]!.dependsOn?.length ?? 0) === 0 ? [task.id] : []]),
+	);
+	for (const call of rendered.blueprints.skills as SkillCallBlueprint[]) {
+		const nested = runWorkflowSteps(
+			artifacts,
+			call.skillId,
+			{ runId: `${runId}-${call.ref}`, arguments: call.arguments },
+			history,
+			nextAncestors,
+			depth + 1,
+		);
+		nestedRuns.push(nested);
+		stepTaskIds.set(call.ref, nested.created.tasks);
+		stepRootTaskIds.set(call.ref, nested.rootTaskIds);
+	}
+
+	for (const blueprint of rendered.blueprints.tasks) {
+		const id = ids.get(blueprint.ref)!;
+		for (const dependency of blueprint.dependsOn ?? []) {
+			for (const dependencyId of stepTaskIds.get(dependency) ?? []) artifacts.link({ from: id, relation: "depends_on", to: dependencyId });
+		}
+		if (blueprint.parent) {
+			const parentId = ids.get(blueprint.parent)!;
+			artifacts.link({ from: parentId, relation: "contains", to: id });
+			artifacts.link({ from: id, relation: "part_of", to: parentId });
+		}
+	}
+	for (const call of rendered.blueprints.skills as SkillCallBlueprint[]) {
+		const stepTaskIdsForCall = stepTaskIds.get(call.ref) ?? [];
+		for (const dependency of call.dependsOn ?? []) {
+			for (const dependencyId of stepTaskIds.get(dependency) ?? []) {
+				for (const taskId of stepTaskIdsForCall) artifacts.link({ from: taskId, relation: "depends_on", to: dependencyId });
 			}
 		}
-		for (const link of rendered.links) {
-			artifacts.link({ from: ids.get(link.from)!, relation: link.relation, to: ids.get(link.to)! });
+		if (call.parent) {
+			const parentId = ids.get(call.parent)!;
+			for (const rootTaskId of stepRootTaskIds.get(call.ref) ?? []) {
+				artifacts.link({ from: parentId, relation: "contains", to: rootTaskId });
+				artifacts.link({ from: rootTaskId, relation: "part_of", to: parentId });
+			}
 		}
-		for (const rootTaskId of rootTaskIds) artifacts.link({ from: skillId, relation: "triggers", to: rootTaskId });
+	}
+	for (const link of rendered.links) {
+		const fromIds = stepTaskIds.get(link.from) ?? [ids.get(link.from)!];
+		const toIds = stepTaskIds.get(link.to) ?? [ids.get(link.to)!];
+		for (const from of fromIds) for (const to of toIds) artifacts.link({ from, relation: link.relation, to });
+	}
 
-		return {
-			skillId,
-			runId,
-			arguments: arguments_,
-			created: {
-				docs: docs.map(({ id }) => id),
-				rules: rules.map(({ id }) => id),
-				tasks: tasks.map(({ id }) => id),
-			},
-			rootTaskIds,
-			execution: projectTaskExecution(executionGraph(tasks, rendered, ids)),
-		};
-	});
-	return history ? history.events.atomic(persist) : persist();
+	const rootTaskIds = [
+		...rendered.blueprints.tasks.filter((task) => (task.dependsOn?.length ?? 0) === 0).map((task) => ids.get(task.ref)!),
+		...(rendered.blueprints.skills as SkillCallBlueprint[])
+			.filter((call) => (call.dependsOn?.length ?? 0) === 0)
+			.flatMap((call) => stepRootTaskIds.get(call.ref) ?? []),
+	];
+	for (const task of rendered.blueprints.tasks) {
+		if ((task.dependsOn?.length ?? 0) === 0) artifacts.link({ from: skillId, relation: "triggers", to: ids.get(task.ref)! });
+	}
+	for (const call of rendered.blueprints.skills as SkillCallBlueprint[]) {
+		if ((call.dependsOn?.length ?? 0) === 0) artifacts.link({ from: skillId, relation: "triggers", to: call.skillId });
+	}
+
+	return {
+		skillId,
+		runId,
+		arguments: arguments_,
+		created: {
+			docs: [...docs.map(({ id }) => id), ...nestedRuns.flatMap((run) => run.created.docs)],
+			rules: [...rules.map(({ id }) => id), ...nestedRuns.flatMap((run) => run.created.rules)],
+			tasks: [...tasks.map(({ id }) => id), ...nestedRuns.flatMap((run) => run.created.tasks)],
+			skillRuns: [...nestedRuns.map((run) => run.runId), ...nestedRuns.flatMap((run) => run.created.skillRuns)],
+		},
+		rootTaskIds,
+		execution: projectTaskExecution(executionGraph(tasks, rendered, ids)),
+	};
 }

package/src/task-service.ts

@@ -34,6 +34,8 @@ export interface TaskFilter {
 	projectRoot?: string;
 	scope?: TaskViewMode;
 	rootTaskId?: string;
+	/** Requesting agent session id — scopes Task Focus reads so concurrent agents see only their own Focus. Defaults to a shared "global" scope when omitted. */
+	sessionId?: string;
 }
 
 export type TaskStatus = TaskLifecycleStatus;
@@ -280,7 +282,7 @@ export class Tasks {
 			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
 		}
 		const byId = new Map(tasks.map((task) => [task.id, task]));
-		const focus = this.focusStore.get();
+		const focus = this.focusStore.get(filter.sessionId);
 		const focusedId = focus?.taskId;
 		const nodes = new Map(tasks.map((task) => [task.id, {
 			task,
@@ -326,11 +328,11 @@ export class Tasks {
 	}
 
 	focused(filter?: TaskFilter): TaskFocus | null {
-		const focus = this.focusStore.get();
+		const focus = this.focusStore.get(filter?.sessionId);
 		if (!focus) return null;
 		const task = this.artifacts.get(focus.taskId);
 		if (!task || task.kind !== "task" || task.status === "done" || task.status === "canceled") {
-			this.focusStore.clear(focus.taskId);
+			this.focusStore.clear(focus.taskId, filter?.sessionId);
 			return null;
 		}
 		if (filter?.projectRoot && !this.list(filter).some((candidate) => candidate.id === task.id)) return null;
@@ -346,7 +348,7 @@ export class Tasks {
 		return this.events.atomic(() => {
 			const task = this.require(id);
 			if (task.status === "done" || task.status === "canceled") throw new Error(`cannot focus task from ${task.status}`);
-			this.focusStore.set(id);
+			this.focusStore.set(id, context.sessionId);
 			this.appendEvent({ taskId: id, type: "focus_set" }, context);
 			return task;
 		});
@@ -354,9 +356,9 @@ export class Tasks {
 
 	pauseFocus(context: TaskEventContext = {}): TaskFocus {
 		return this.events.atomic(() => {
-			const focus = this.focused();
+			const focus = this.focused({ sessionId: context.sessionId });
 			if (!focus) throw new Error("no focused task");
-			const state = this.focusStore.pause(focus.artifact.id, context.reason);
+			const state = this.focusStore.pause(focus.artifact.id, context.reason, context.sessionId);
 			this.appendEvent({ taskId: focus.artifact.id, type: "focus_paused" }, context);
 			return { artifact: focus.artifact, status: state.status, updatedAt: state.updatedAt, ...(state.pauseReason ? { pauseReason: state.pauseReason } : {}) };
 		});
@@ -364,9 +366,9 @@ export class Tasks {
 
 	unpauseFocus(context: TaskEventContext = {}): TaskFocus {
 		return this.events.atomic(() => {
-			const focus = this.focused();
+			const focus = this.focused({ sessionId: context.sessionId });
 			if (!focus) throw new Error("no focused task");
-			const state = this.focusStore.unpause(focus.artifact.id);
+			const state = this.focusStore.unpause(focus.artifact.id, context.sessionId);
 			this.appendEvent({ taskId: focus.artifact.id, type: "focus_unpaused" }, context);
 			return { artifact: focus.artifact, status: state.status, updatedAt: state.updatedAt };
 		});
@@ -374,9 +376,9 @@ export class Tasks {
 
 	clearFocus(context: TaskEventContext = {}): { cleared: boolean } {
 		return this.events.atomic(() => {
-			const focus = this.focusStore.get();
+			const focus = this.focusStore.get(context.sessionId);
 			if (focus) this.appendEvent({ taskId: focus.taskId, type: "focus_cleared" }, context);
-			this.focusStore.clear();
+			this.focusStore.clear(undefined, context.sessionId);
 			return { cleared: focus !== undefined };
 		});
 	}
@@ -389,14 +391,14 @@ export class Tasks {
 			if (action === "start") {
 				const blocking = this.dependencyIds(id).filter((dependencyId) => this.require(dependencyId).status !== "done");
 				if (blocking.length > 0) throw new Error(`task "${id}" is blocked by dependencies: ${blocking.join(", ")}`);
-				this.focusStore.set(id);
+				this.focusStore.set(id, context.sessionId);
 			}
 			const updated = this.artifacts.setStatus(id, transition.to)!;
 			const eventType = { start: "started", submit: "submitted", reject: "review_rejected", retry: "retried", cancel: "canceled" }[action] as AppendTaskEvent["type"];
 			this.appendEvent({ taskId: id, type: eventType, fromStatus: task.status as TaskStatus, toStatus: transition.to }, context);
 			if (action === "start" || action === "retry") this.propagateProgressToAncestors(id, context);
-			if (action === "retry") this.focusStore.set(id);
-			if (action === "cancel") this.focusStore.clear(id);
+			if (action === "retry") this.focusStore.set(id, context.sessionId);
+			if (action === "cancel") this.focusStore.clearEverywhere(id);
 			return updated;
 		});
 	}
@@ -437,30 +439,60 @@ export class Tasks {
 		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
 	}
 
-	depend(id: string, dependencyId: string): Artifact {
-		this.require(id);
-		this.require(dependencyId);
-		const graph = this.graph();
-		assertDependencyEdgeAllowed(graph, id, dependencyId);
-		const node = graph.nodes.find((entry) => entry.task.id === id)!;
-		if (node.dependencyIds.includes(dependencyId)) return this.show(id);
-		if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
-			throw new Error(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
-		}
-		const successorCount = graph.nodes.filter((entry) => entry.dependencyIds.includes(dependencyId)).length;
-		if (successorCount >= TASK_EXECUTION_MAX_DEGREE) {
-			throw new Error(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
-		}
-		this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId });
-		return this.show(id);
+	depend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.require(id);
+			this.require(dependencyId);
+			const graph = this.graph();
+			assertDependencyEdgeAllowed(graph, id, dependencyId);
+			const node = graph.nodes.find((entry) => entry.task.id === id)!;
+			if (node.dependencyIds.includes(dependencyId)) return this.show(id);
+			if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
+				throw new Error(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+			}
+			const successorCount = graph.nodes.filter((entry) => entry.dependencyIds.includes(dependencyId)).length;
+			if (successorCount >= TASK_EXECUTION_MAX_DEGREE) {
+				throw new Error(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
+			}
+			this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId }, context);
+			this.appendEvent({ taskId: id, type: "dependency_added", reason: context.reason }, context);
+			return this.show(id);
+		});
 	}
 
-	contain(parentId: string, childId: string): Artifact {
-		this.require(parentId);
-		this.require(childId);
-		this.artifacts.link({ from: parentId, relation: "contains", to: childId });
-		this.artifacts.link({ from: childId, relation: "part_of", to: parentId });
-		return this.show(parentId);
+	/** Idempotent: undepending an already-absent dependency is a no-op. Never starts, completes, or focuses work — only removes the edge. */
+	undepend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.require(id);
+			this.require(dependencyId);
+			const removed = this.artifacts.unlink({ from: id, relation: "depends_on", to: dependencyId }, context);
+			if (removed) this.appendEvent({ taskId: id, type: "dependency_removed", reason: context.reason }, context);
+			return this.show(id);
+		});
+	}
+
+	contain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.require(parentId);
+			this.require(childId);
+			const alreadyContained = this.relationships(parentId).some((edge) => edge.relation === "contains" && edge.from === parentId && edge.to === childId);
+			this.artifacts.link({ from: parentId, relation: "contains", to: childId }, context);
+			this.artifacts.link({ from: childId, relation: "part_of", to: parentId }, context);
+			if (!alreadyContained) this.appendEvent({ taskId: parentId, type: "containment_added", reason: context.reason }, context);
+			return this.show(parentId);
+		});
+	}
+
+	/** Idempotent: removing an already-absent containment is a no-op. Both contains/part_of edges are removed atomically. */
+	uncontain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.require(parentId);
+			this.require(childId);
+			const removedContains = this.artifacts.unlink({ from: parentId, relation: "contains", to: childId }, context);
+			this.artifacts.unlink({ from: childId, relation: "part_of", to: parentId }, context);
+			if (removedContains) this.appendEvent({ taskId: parentId, type: "containment_removed", reason: context.reason }, context);
+			return this.show(parentId);
+		});
 	}
 
 	private descendantIds(rootTaskId: string, projectTaskIds: string[]): Set<string> {
@@ -575,7 +607,7 @@ export class Tasks {
 					attemptId,
 					evidence: { gates, checklist, result: "rejected" },
 				}, context);
-				return { artifact, gates, checklist, completed: false, focused: this.active(), blocked: [] };
+				return { artifact, gates, checklist, completed: false, focused: this.active({ sessionId: context.sessionId }), blocked: [] };
 			});
 		}
 		return this.events.atomic(() => this.finish(id, attemptId, gates, checklist, context, options));
@@ -597,7 +629,7 @@ export class Tasks {
 			attemptId,
 			evidence: { gates, checklist, result: "completed" },
 		}, context);
-		this.focusStore.clear(id);
+		this.focusStore.clearEverywhere(id);
 		const blocked: TaskBlockage[] = [];
 		let focused: Artifact | null = null;
 		for (const successorId of [...successorIds].sort()) {
@@ -610,7 +642,7 @@ export class Tasks {
 				continue;
 			}
 			if (options.focusSuccessor !== false && !focused) {
-				this.focusStore.set(successor.id);
+				this.focusStore.set(successor.id, context.sessionId);
 				focused = successor;
 			}
 		}