@vimhead.dev/norn-cli 0.1.0-tip.35359392805.1 → 0.1.0-tip.35436871363.1

package/assets/packages/cli/src/internal/run-state.ts

@@ -5,7 +5,7 @@ import { isNodeError } from "@vimhead.dev/norn-core/errors";
 import { readRunLaunchRequest, readOptionalRunResumeRequest, RESUME_START_GRACE_MS } from "./launch-request.ts";
 import { getRunLeaseHealth } from "./run-lease.ts";
 import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
-import { createRunFileCoordinator, type NornFileCoordinator } from "@vimhead.dev/norn/files";
+import { createRunFileCoordinator, type NornFileCoordinator } from "./file-coordinator.ts";
 import { runCurrentRoot } from "./run-store.ts";
 import { jsonValueSchema } from "@vimhead.dev/norn/schema";
 import { Value } from "typebox/value";
@@ -13,19 +13,19 @@ import { Value } from "typebox/value";
 export const RUN_STATE_FILE_NAME = "run-state.json";
 const LEGACY_RUN_STATE_FILE_NAME = "runtime-state.json";
 
-export function mergeInterruptedWorkflowParams(currentParams: unknown, params: unknown, fields: readonly string[] | undefined): unknown {
-	if (!isRecord(currentParams) || !isRecord(params)) return params;
+export function mergeInterruptedWorkflowArgs(currentArgs: unknown, args: unknown, fields: readonly string[] | undefined): unknown {
+	if (!isRecord(currentArgs) || !isRecord(args)) return args;
 	if (fields) {
-		const unsupportedFields = Object.keys(params).filter((field) => !fields.includes(field));
-		if (unsupportedFields.length > 0) throw new Error(`Interrupted workflow params cannot update non-gate fields: ${unsupportedFields.join(", ")}`);
+		const unsupportedFields = Object.keys(args).filter((field) => !fields.includes(field));
+		if (unsupportedFields.length > 0) throw new Error(`Interrupted workflow args cannot update non-gate fields: ${unsupportedFields.join(", ")}`);
 	}
-	return { ...currentParams, ...params };
+	return { ...currentArgs, ...args };
 }
-const RUN_STATE_VERSION = 1;
+const RUN_STATE_VERSION = 2;
 
 type NornRunWorkflowStep = {
 	readonly workflowId: string;
-	readonly params: unknown;
+	readonly args: unknown;
 	readonly cwd: string;
 	readonly env: Record<string, string>;
 	readonly interruption?: RuntimeInterruption;
@@ -58,7 +58,8 @@ type NornRunWorkflowOutcome = {
 };
 
 export type NornRunState = {
-	readonly version: typeof RUN_STATE_VERSION;
+	readonly version: 1 | typeof RUN_STATE_VERSION;
+	readonly projectRoot?: string;
 	readonly id: string;
 	readonly name: string;
 	readonly entrypointWorkflowId: string;
@@ -74,6 +75,7 @@ export type NornRunState = {
 };
 
 type CreateNornRunStateInput = {
+	readonly projectRoot: string;
 	readonly id: string;
 	readonly name: string;
 	readonly entrypointWorkflowId: string;
@@ -101,7 +103,8 @@ export class NornRunStateStore {
 			id: input.id,
 			name: input.name,
 			entrypointWorkflowId: input.entrypointWorkflowId,
-			workspace: input.workspace,
+			projectRoot: resolve(input.projectRoot),
+			workspace: resolve(input.workspace),
 			configOverride: input.configOverride,
 			status: "running",
 			current: input.current,
@@ -119,7 +122,7 @@ export class NornRunStateStore {
 	static async load(runRoot: string): Promise<NornRunStateStore> {
 		const currentRoot = runCurrentRoot(runRoot);
 		const files = createRunFileCoordinator(runRoot);
-		const state = await files.withExclusiveLock(join(currentRoot, RUN_STATE_FILE_NAME), async (path) => parseNornRunState(await readRunStateFile({ path, legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) })));
+		const state = await files.withExclusiveLock(join(currentRoot, RUN_STATE_FILE_NAME), async (path) => parseNornRunState(await readRunStateFile({ path, legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) }), "execute"));
 		return new NornRunStateStore({ path: join(currentRoot, RUN_STATE_FILE_NAME), state, files });
 	}
 
@@ -163,11 +166,11 @@ export class NornRunStateStore {
 		});
 	}
 
-	async interruptCurrent(params: unknown, interruption: { readonly description: string; readonly fields?: readonly string[] }): Promise<void> {
+	async interruptCurrent(args: unknown, interruption: { readonly description: string; readonly fields?: readonly string[] }): Promise<void> {
 		if (!this.state.current) throw new Error("Cannot interrupt run without current step");
 		await this.update({
 			status: "interrupted",
-			current: { ...this.state.current, params, interruption: { status: "pending", ...interruption } },
+			current: { ...this.state.current, args, interruption: { status: "pending", ...interruption } },
 			outcome: null,
 			failed: null,
 		});
@@ -185,11 +188,11 @@ export class NornRunStateStore {
 		await this.update({ status: "stopped", outcome: null, failed: null });
 	}
 
-	async replaceCurrentParams(params: unknown): Promise<void> {
+	async replaceCurrentArgs(args: unknown): Promise<void> {
 		if (!this.state.current) throw new Error("Cannot resume run without current step");
 		await this.update({
 			status: "running",
-			current: { ...this.state.current, params, interruption: { ...this.state.current.interruption, status: "satisfied" } },
+			current: { ...this.state.current, args, interruption: { ...this.state.current.interruption, status: "satisfied" } },
 			outcome: null,
 			failed: null,
 		});
@@ -208,16 +211,16 @@ export class NornRunStateStore {
 
 	private async update(patch: Partial<NornRunState>): Promise<void> {
 		await this.files.withExclusiveLock(this.path, async (path) => {
-			const current = parseNornRunState(await readRunStateFile({ path, legacyPath: join(dirname(this.path), LEGACY_RUN_STATE_FILE_NAME) }));
+			const current = parseNornRunState(await readRunStateFile({ path, legacyPath: join(dirname(this.path), LEGACY_RUN_STATE_FILE_NAME) }), "execute");
 			const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
-			if (next.current?.params !== undefined) Value.Assert(jsonValueSchema, next.current.params);
+			if (next.current?.args !== undefined) Value.Assert(jsonValueSchema, next.current.args);
 			await writeJsonAtomically(path, next);
 			this.state = next;
 		});
 	}
 
 	private async write(): Promise<void> {
-		if (this.state.current?.params !== undefined) Value.Assert(jsonValueSchema, this.state.current.params);
+		if (this.state.current?.args !== undefined) Value.Assert(jsonValueSchema, this.state.current.args);
 		await mkdir(dirname(this.path), { recursive: true });
 		await this.files.withExclusiveLock(this.path, (path) => writeJsonAtomically(path, this.state));
 	}
@@ -239,13 +242,20 @@ export async function listRuns(sessionCwd: string): Promise<NornRunInfo[]> {
 
 export async function getRunInfo(runRoot: string): Promise<NornRunInfo> {
 	try {
-		const resumeRequest = await readOptionalRunResumeRequest(runRoot);
-		const state = parseNornRunState(await readRunStateJson(runCurrentRoot(runRoot)));
+		// Read the request first so a completed handoff cannot revive an old interruption.
+		const pendingResume = await readOptionalRunResumeRequest(runRoot).then(
+			request => ({ status: "fulfilled" as const, request }),
+			(error: unknown) => ({ status: "rejected" as const, error }),
+		);
+		const state = parseNornRunState(await readRunStateJson(runCurrentRoot(runRoot)), "inspect");
+		if (state.version === RUN_STATE_VERSION && pendingResume.status === "rejected") throw pendingResume.error;
+		const resumeRequest = state.version === RUN_STATE_VERSION && pendingResume.status === "fulfilled" ? pendingResume.request : undefined;
 		return {
 			version: state.version,
 			id: state.id,
 			name: state.name,
 			path: runRoot,
+			paths: { project: state.projectRoot ?? resolve(runRoot, "../../.."), workspace: state.workspace },
 			entrypointWorkflowId: state.entrypointWorkflowId,
 			currentWorkflowId: state.current?.workflowId,
 			status: resumeRequest ? "running" : state.status,
@@ -311,6 +321,7 @@ async function getLaunchedRunInfo(runRoot: string): Promise<NornRunInfo> {
 		id: launchRequest.id,
 		name: launchRequest.name,
 		path: runRoot,
+		paths: { project: resolve(runRoot, "../../.."), workspace: join(runCurrentRoot(resolve(runRoot)), "workspace") },
 		entrypointWorkflowId: launchRequest.workflowId,
 		currentWorkflowId: launchRequest.workflowId,
 		status: "running",
@@ -337,10 +348,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-function parseNornRunState(value: unknown): NornRunState {
+export function assertRunVersion(version: unknown): void {
+	if (version !== RUN_STATE_VERSION) throw new Error(`Incompatible saved run state version ${String(version)}; this alpha requires version ${RUN_STATE_VERSION}. Use the original Norn version to resume this run, or start a new run. Saved files have not been migrated.`);
+}
+
+function parseNornRunState(value: unknown, mode: "execute" | "inspect"): NornRunState {
 	if (!value || typeof value !== "object") throw new Error("Invalid run state");
 	const state = value as Partial<NornRunState> & { rootWorkflowId?: unknown };
-	if (state.version !== RUN_STATE_VERSION) throw new Error(`Unsupported run state version: ${String(state.version)}`);
+	if (mode === "execute" || state.version !== 1) assertRunVersion(state.version);
 	if (typeof state.id !== "string" || state.id.length === 0) throw new Error("Invalid run state id");
 	const normalizedState = state as { name?: string; entrypointWorkflowId?: unknown; rootWorkflowId?: unknown };
 	if (typeof normalizedState.name !== "string" || normalizedState.name.length === 0) normalizedState.name = state.id;
@@ -369,7 +384,7 @@ function runInterruption(state: NornRunState): NornRunInterruption | undefined {
 	if (state.status !== "interrupted" || !state.current?.interruption) return undefined;
 	return {
 		workflowId: state.current.workflowId,
-		params: state.current.params,
+		args: state.version === 1 ? (state.current as { readonly params?: unknown }).params : state.current.args,
 		description: state.current.interruption.description ?? "",
 		fields: state.current.interruption.fields,
 	};

package/assets/packages/cli/src/internal/run.ts

@@ -1,63 +1,38 @@
-import { isAbsolute, relative, resolve, sep } from "node:path";
 import type { CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
-import type { NornAnyWorkflowDeclaration, NornProjectRun, NornRunOutcomeMetadata, NornWorkflowIsolationMode, NornRun } from "@vimhead.dev/norn";
+import type { NornRunOutcomeMetadata, NornRun } from "@vimhead.dev/norn";
 import { createWorkflowTransition } from "@vimhead.dev/norn-core/workflow-transition";
 import type { NornAgentResponseCollector } from "./agent-response-tool.ts";
-import type { NornArtifacts } from "./artifacts.ts";
 import { NornAgentRunner } from "./agents.ts";
 import { NornCommandRunner } from "./commands.ts";
 import type { NornRunLogs } from "./logs.ts";
 import type { NornRunLogger } from "./run-log.ts";
-import type { NornRunResources } from "../resources.ts";
 
 type DefaultNornRunInput = {
 	readonly id: string;
 	readonly runRoot: string;
-	readonly projectRoot: string;
-	readonly workspace: string;
-	readonly cwd: string;
-	readonly isolationMode: NornWorkflowIsolationMode;
 	readonly signal?: AbortSignal;
 	readonly model?: CreateAgentSessionOptions["model"];
 	readonly thinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
 	readonly agentDir?: string;
 	readonly responseCollector: NornAgentResponseCollector;
-	readonly resources: NornRunResources;
-	readonly state: NornRun["state"];
 	readonly logger: NornRunLogger;
-	readonly artifacts: NornArtifacts;
 	readonly logs: NornRunLogs;
 };
 
-export class NornRunContext implements NornProjectRun {
-	readonly resources: NornRunResources;
-	readonly state: NornRun["state"];
-	readonly artifacts: NornRun["artifacts"];
+export class NornRunContext implements NornRun {
 	readonly logs: NornRun["logs"];
 	readonly commands: NornRun["commands"];
 	readonly agents: NornRun["agents"];
 	readonly id: string;
-	readonly workspace: string;
-	readonly projectRoot: string;
-	readonly cwd: string;
 
 	constructor(private readonly input: DefaultNornRunInput) {
 		this.id = input.id;
-		this.workspace = input.workspace;
-		this.projectRoot = input.projectRoot;
-		this.cwd = input.cwd;
-		this.resources = input.resources;
-		this.state = input.state;
-		this.artifacts = input.artifacts;
 		this.logs = {
 			read: (log) => this.input.logs.read(log),
 		};
 		this.commands = {
 			run: (commandInput) =>
 				new NornCommandRunner({
-					boundaryRoot: this.boundaryRoot,
-					boundaryName: this.input.isolationMode,
-					cwd: this.cwd,
 					signal: this.input.signal,
 					logs: this.input.logs,
 					logger: this.input.logger,
@@ -69,26 +44,10 @@ export class NornRunContext implements NornProjectRun {
 		};
 	}
 
-	forWorkflow(workflow: NornAnyWorkflowDeclaration): NornRunContext {
-		const isolationMode = workflow.isolation.mode;
-		return new NornRunContext({
-			...this.input,
-			isolationMode,
-			cwd: isolationMode === "project" ? this.projectRoot : this.workspace,
-		});
-	}
-
-	private get boundaryRoot(): string {
-		return this.input.isolationMode === "project" ? this.projectRoot : this.workspace;
-	}
-
 	private createAgentRunner(): NornAgentRunner {
 		return new NornAgentRunner({
 			id: this.id,
 			runRoot: this.input.runRoot,
-			boundaryRoot: this.boundaryRoot,
-			boundaryName: this.input.isolationMode,
-			cwd: this.cwd,
 			signal: this.input.signal,
 			model: this.input.model,
 			thinkingLevel: this.input.thinkingLevel,
@@ -99,16 +58,8 @@ export class NornRunContext implements NornProjectRun {
 		});
 	}
 
-	path(relativePath: string): string {
-		return this.resolveFromRoot(this.cwd, this.boundaryRoot, relativePath);
-	}
-
-	projectPath(relativePath: string): string {
-		return this.resolveFromRoot(this.projectRoot, this.projectRoot, relativePath);
-	}
-
-	next(workflowId: string, params: unknown): ReturnType<NornRun["next"]> {
-		return createWorkflowTransition({ workflowId, params });
+	next(workflowId: string, args: unknown): ReturnType<NornRun["next"]> {
+		return createWorkflowTransition({ workflowId, args });
 	}
 
 	complete(metadata?: NornRunOutcomeMetadata): ReturnType<NornRun["complete"]> {
@@ -118,13 +69,4 @@ export class NornRunContext implements NornProjectRun {
 	fail(metadata: NornRunOutcomeMetadata & { readonly summary: string }): ReturnType<NornRun["fail"]> {
 		return { type: "fail", metadata };
 	}
-
-	private resolveFromRoot(root: string, boundaryRoot: string, path: string): string {
-		const resolvedPath = isAbsolute(path) ? path : resolve(root, path);
-		const pathFromBoundary = relative(boundaryRoot, resolvedPath);
-		if (pathFromBoundary === ".." || pathFromBoundary.startsWith(`..${sep}`) || isAbsolute(pathFromBoundary)) {
-			throw new Error(`Workflow path escapes ${this.input.isolationMode} isolation: ${path}`);
-		}
-		return resolvedPath;
-	}
 }

package/assets/packages/cli/src/internal/worker-directory.ts

@@ -0,0 +1,17 @@
+import { chmod, lstat, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+
+export async function prepareRunWorkerDirectory(runRoot: string): Promise<string> {
+	const directory = join(runRoot, "worker");
+	try {
+		await mkdir(directory, { mode: 0o555 });
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "EEXIST") throw error;
+	}
+	const metadata = await lstat(directory);
+	if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error(`Run worker cwd must be a directory, not a symlink: ${directory}`);
+	if ((await readdir(directory)).length !== 0) throw new Error(`Run worker cwd must be empty: ${directory}`);
+	await chmod(directory, 0o555);
+	return directory;
+}

package/assets/packages/cli/src/internal/workflow-registry.ts

@@ -1,24 +1,40 @@
-import { isWorkflowComplete, isWorkflowFail, isWorkflowNext, type NornAnyWorkflowDeclaration, type NornDispose, type NornInspectedWorkflowInfo, type NornRegisteredWorkflowInfo, type NornRunComplete, type NornRunFail, type NornRunFor, type NornRunNext, type NornWorkflowGateInfo, type NornWorkflowImplementation, type NornWorkflowParams, type NornWorkflowPluginInfo } from "@vimhead.dev/norn";
+import { isWorkflowComplete, isWorkflowDeclaration, isWorkflowFail, isWorkflowNext, type NornAnyWorkflowDeclaration, type NornDispose, type NornInspectedWorkflowInfo, type NornRegisteredWorkflowInfo, type NornRunComplete, type NornRunFail, type NornRun, type NornRunNext, type NornWorkflowPaths, type NornWorkflowContext, type NornWorkflowGateInfo, type NornWorkflowSource, type NornWorkflowScopeInfo, type NornProjectConfigurationInfo } from "@vimhead.dev/norn";
 import { assertWorkflowMetadata, inspectSchema, isPlainObject, schemaShape, schemaType, unwrapSchema } from "@vimhead.dev/norn/schema";
-import { type TSchema } from "typebox";
+import type { TSchema } from "typebox";
 import { Value } from "typebox/value";
 
+export type NornRegisteredConfiguration = { readonly key: string; readonly schema: TSchema | undefined; readonly input: unknown; readonly value: unknown };
 export type NornRegisteredWorkflow = {
-	workflow: NornAnyWorkflowDeclaration;
-	implementation: NornWorkflowImplementation<NornAnyWorkflowDeclaration, unknown>;
-	configuration?: NornRegisteredConfiguration;
-	plugin?: NornWorkflowPluginInfo;
+	readonly workflow: NornAnyWorkflowDeclaration;
+	readonly configuration: NornRegisteredConfiguration;
+	readonly scopeId: string | undefined;
+	readonly source: NornWorkflowSource | undefined;
 };
 
-export type NornRegisteredConfiguration = { readonly schema: TSchema; readonly input: unknown; readonly value: unknown };
+type NornRegisteredScope = { readonly definition: NornWorkflowScopeInfo; readonly configuration: NornRegisteredConfiguration };
 
-export function decodePluginConfiguration(input: { readonly pluginId: string; readonly schema: TSchema | undefined; readonly value: unknown }): NornRegisteredConfiguration | undefined {
+export function decodeConfiguration(input: { readonly key: string; readonly schema: TSchema | undefined; readonly value: unknown }): NornRegisteredConfiguration {
 	if (!input.schema) {
-		if (input.value !== undefined) throw new Error(`Norn config provided for plugin without config schema: ${input.pluginId}`);
-		return undefined;
+		if (input.value !== undefined) throw new Error(`Norn config provided without config schema: ${input.key}`);
+		return { key: input.key, schema: undefined, input: undefined, value: undefined };
+	}
+	const value = input.value === undefined && schemaType(unwrapSchema(input.schema)) === "object" ? {} : input.value;
+	return { key: input.key, schema: input.schema, input: value, value: Value.Decode(input.schema, value) };
+}
+
+export function assertCompatibleConfigurationOwners(workflows: readonly NornAnyWorkflowDeclaration[]): void {
+	const owners = new Map<string, { readonly kind: "workflow" | "scope"; readonly definition: object }>();
+	for (const workflow of workflows) {
+		for (const owner of [
+			{ key: workflow.id, kind: "workflow" as const, definition: workflow },
+			...(workflow.scope ? [{ key: workflow.scope.id, kind: "scope" as const, definition: workflow.scope }] : []),
+		]) {
+			const previous = owners.get(owner.key);
+			if (previous && previous.kind !== owner.kind) throw new Error(`Ambiguous configuration key: ${owner.key}`);
+			if (previous && owner.kind === "scope" && previous.definition !== owner.definition) throw new Error(`Duplicate workflow scope id: ${owner.key}; import one shared scope definition`);
+			owners.set(owner.key, owner);
+		}
 	}
-	const value = defaultConfigInput(input.schema, input.value);
-	return { schema: input.schema, input: value, value: Value.Decode(input.schema, value) };
 }
 
 export type NornWorkflowStepResult =
@@ -26,157 +42,156 @@ export type NornWorkflowStepResult =
 	| { readonly type: "complete"; readonly workflow: NornAnyWorkflowDeclaration; readonly metadata?: NornRunComplete["metadata"] }
 	| { readonly type: "fail"; readonly workflow: NornAnyWorkflowDeclaration; readonly metadata: NornRunFail["metadata"] };
 
+type NornExecutionContextInput = {
+	readonly run: NornRun;
+	readonly paths: NornWorkflowPaths;
+	readonly args: unknown;
+	readonly configOverride: unknown;
+};
+
+type NornWorkflowExecutionInput = NornExecutionContextInput & { readonly workflow: NornAnyWorkflowDeclaration };
+
 export class NornWorkflowRegistry {
 	private readonly entries = new Map<string, NornRegisteredWorkflow>();
+	private readonly scopes = new Map<string, NornRegisteredScope>();
 
-	register<TWorkflow extends NornAnyWorkflowDeclaration>(
-		workflow: TWorkflow,
-		implementation: NornWorkflowImplementation<TWorkflow, unknown>,
-		metadata: { readonly plugin?: NornWorkflowPluginInfo; readonly configuration?: NornRegisteredConfiguration } = {},
-	): NornDispose {
+	register(input: { readonly workflow: NornAnyWorkflowDeclaration; readonly config: Readonly<Record<string, unknown>>; readonly source: NornWorkflowSource | undefined }): NornDispose {
+		const { workflow, config, source } = input;
+		assertWorkflowDefinition(workflow);
 		if (this.entries.has(workflow.id)) throw new Error(`Workflow already registered: ${workflow.id}`);
-
+		assertCompatibleConfigurationOwners([...this.sortedEntries().map(entry => entry.workflow), workflow]);
 		const entry: NornRegisteredWorkflow = {
-			workflow,
-			implementation: implementation as NornWorkflowImplementation<NornAnyWorkflowDeclaration, unknown>,
-			configuration: metadata.configuration,
-			plugin: metadata.plugin,
+			workflow, source, scopeId: workflow.scope?.id,
+			configuration: decodeConfiguration({ key: workflow.id, schema: workflow.config, value: configurationInput(config, workflow.id) }),
 		};
-		assertWorkflowMetadata(workflow);
-		assertGateWorkflow(workflow);
+		if (workflow.scope && !this.scopes.has(workflow.scope.id)) {
+			this.scopes.set(workflow.scope.id, {
+				definition: workflow.scope,
+				configuration: decodeConfiguration({ key: workflow.scope.id, schema: workflow.scope.config, value: configurationInput(config, workflow.scope.id) }),
+			});
+		}
 		this.entries.set(workflow.id, entry);
-
 		return () => {
-			if (this.entries.get(workflow.id) === entry) this.entries.delete(workflow.id);
+			if (this.entries.get(workflow.id) !== entry) return;
+			this.entries.delete(workflow.id);
+			if (entry.scopeId && ![...this.entries.values()].some(other => other.scopeId === entry.scopeId)) this.scopes.delete(entry.scopeId);
 		};
 	}
 
 	list(options: { readonly entrypointsOnly?: boolean } = {}): NornRegisteredWorkflowInfo[] {
-		const entries = options.entrypointsOnly ? this.launchableEntries() : this.sortedEntries();
-		return entries.map((entry) => workflowInfo(entry));
+		return (options.entrypointsOnly ? this.launchableEntries() : this.sortedEntries()).map(workflowInfo);
 	}
 
 	inspect(workflowId: string): NornInspectedWorkflowInfo | undefined {
 		const entry = this.entries.get(workflowId);
-		return entry ? inspectedWorkflowInfo(entry) : undefined;
+		const scope = entry?.scopeId ? this.scopes.get(entry.scopeId) : undefined;
+		return entry ? {
+			...workflowInfo(entry),
+			argsSchema: inspectSchema(entry.workflow.args),
+			configSchema: entry.configuration.schema ? inspectSchema(entry.configuration.schema) : null,
+			scope: scope ? {
+				id: scope.definition.id,
+				configKey: scope.configuration.key,
+				configSchema: scope.configuration.schema ? inspectSchema(scope.configuration.schema) : null,
+			} : undefined,
+			gate: gateInfo(entry.workflow),
+		} : undefined;
 	}
 
-	launchableEntries(): NornRegisteredWorkflow[] {
-		return this.sortedEntries().filter(({ workflow }) => workflow.isEntrypoint);
+	configurationInfos(): NornProjectConfigurationInfo[] {
+		return [
+			...this.sortedEntries().map(entry => ({ configuration: entry.configuration, scopeId: null })),
+			...[...this.scopes.values()].map(scope => ({ configuration: scope.configuration, scopeId: scope.definition.id })),
+		].map(({ configuration, scopeId }) => ({ key: configuration.key, scopeId, configSchema: configuration.schema ? inspectSchema(configuration.schema) : null, config: configuration.value }));
 	}
 
-	workflowById(workflowId: string): NornAnyWorkflowDeclaration | undefined {
-		return this.entries.get(workflowId)?.workflow;
-	}
+	launchableEntries(): NornRegisteredWorkflow[] { return this.sortedEntries().filter(({ workflow }) => workflow.isEntrypoint); }
+	workflowById(workflowId: string): NornAnyWorkflowDeclaration | undefined { return this.entries.get(workflowId)?.workflow; }
 
-	async describeGate<TWorkflow extends NornAnyWorkflowDeclaration>(
-		workflow: TWorkflow,
-		run: NornRunFor<TWorkflow>,
-		params: unknown,
-		configOverride?: unknown,
-	): Promise<string> {
-		const entry = this.entries.get(workflow.id);
-		if (!entry) throw new Error(`Unknown workflow: ${workflow.id}`);
+	async describeGate(input: NornWorkflowExecutionInput): Promise<string> {
+		const { workflow } = input;
+		const entry = this.requireEntry(workflow.id);
 		if (!workflow.gate) throw new Error(`Workflow is not gated: ${workflow.id}`);
-		const parsedParams = Value.Decode(workflow.params, params) as NornWorkflowParams<TWorkflow>;
-		const parsedConfig = parseExecutionConfig(entry, configOverride);
-		const description = await (entry.implementation as NornWorkflowImplementation<TWorkflow, unknown>).gate?.describe(run, parsedParams, parsedConfig);
-		return validateGateDescription(description ?? workflow.id, workflow.id);
+		const context = this.createExecutionContext({ ...input, entry });
+		const description = await entry.workflow.gate?.describe?.(context) ?? workflow.id;
+		if (typeof description !== "string" || description.trim().length === 0) throw new Error(`Workflow gate description must not be empty: ${workflow.id}`);
+		return description.trim();
 	}
 
-	async execute<TWorkflow extends NornAnyWorkflowDeclaration>(
-		workflow: TWorkflow,
-		run: NornRunFor<TWorkflow>,
-		params: unknown,
-		configOverride?: unknown,
-	): Promise<NornWorkflowStepResult> {
-		const entry = this.entries.get(workflow.id);
-		if (!entry) throw new Error(`Unknown workflow: ${workflow.id}`);
-
-		const parsedParams = Value.Decode(workflow.params, params) as NornWorkflowParams<TWorkflow>;
-		const parsedConfig = parseExecutionConfig(entry, configOverride);
-		const result = await (entry.implementation as NornWorkflowImplementation<TWorkflow, unknown>).execute(run, parsedParams, parsedConfig);
+	async execute(input: NornWorkflowExecutionInput): Promise<NornWorkflowStepResult> {
+		const { workflow } = input;
+		const entry = this.requireEntry(workflow.id);
+		const result = await entry.workflow.execute(this.createExecutionContext({ ...input, entry }));
 		if (isWorkflowNext(result)) return result;
 		if (isWorkflowComplete(result)) return { type: "complete", workflow, metadata: result.metadata };
 		if (isWorkflowFail(result)) return { type: "fail", workflow, metadata: result.metadata };
 		throw new Error(`Workflow returned invalid control result: ${workflow.id}`);
 	}
 
-	private sortedEntries(): NornRegisteredWorkflow[] {
-		return Array.from(this.entries.values()).sort((left, right) => left.workflow.id.localeCompare(right.workflow.id));
+	private createExecutionContext(input: NornExecutionContextInput & { readonly entry: NornRegisteredWorkflow }): NornWorkflowContext {
+		const { entry, run, paths, configOverride } = input;
+		const scope = entry.scopeId ? this.scopes.get(entry.scopeId) : undefined;
+		return {
+			args: Value.Decode(entry.workflow.args, input.args),
+			config: parseExecutionConfig(entry.configuration, configOverride),
+			...(scope ? { scope: { id: scope.definition.id, config: parseExecutionConfig(scope.configuration, configOverride) } } : {}),
+			paths,
+			run,
+		};
 	}
-}
 
-function defaultConfigInput(configSchema: TSchema, config: unknown): unknown {
-	if (config !== undefined) return config;
-	return schemaType(unwrapSchema(configSchema)) === "object" ? {} : undefined;
+	private requireEntry(id: string): NornRegisteredWorkflow {
+		const entry = this.entries.get(id);
+		if (!entry) throw new Error(`Unknown workflow: ${id}`);
+		return entry;
+	}
+	private sortedEntries(): NornRegisteredWorkflow[] { return [...this.entries.values()].sort((left, right) => left.workflow.id.localeCompare(right.workflow.id)); }
 }
 
-function parseExecutionConfig(entry: NornRegisteredWorkflow, configOverride: unknown): unknown {
-	const pluginConfigOverride = pluginConfigOverrideInput(entry, configOverride);
-	if (!entry.configuration) {
-		if (pluginConfigOverride !== undefined) throw new Error(`Run config override provided for plugin without config schema: ${entry.plugin?.id ?? entry.workflow.id}`);
-		return undefined;
-	}
-	if (pluginConfigOverride === undefined) return entry.configuration.value;
-	const rawConfig = isPlainObject(entry.configuration.input) && isPlainObject(pluginConfigOverride)
-		? deepMerge(entry.configuration.input, pluginConfigOverride)
-		: pluginConfigOverride;
-	return Value.Decode(entry.configuration.schema, rawConfig);
+function configurationInput(config: Readonly<Record<string, unknown>>, key: string): unknown {
+	return Object.hasOwn(config, key) ? config[key] : undefined;
 }
 
-function pluginConfigOverrideInput(entry: NornRegisteredWorkflow, configOverride: unknown): unknown {
-	if (configOverride === undefined) return undefined;
-	if (!isPlainObject(configOverride)) throw new Error("Run config override must be an object keyed by plugin id");
-	const pluginId = entry.plugin?.id;
-	return pluginId ? configOverride[pluginId] : undefined;
+function parseExecutionConfig(configuration: NornRegisteredConfiguration, overrides: unknown): unknown {
+	if (overrides !== undefined && !isPlainObject(overrides)) throw new Error("Run config override must be an object keyed by workflow or scope id");
+	const override = overrides ? configurationInput(overrides, configuration.key) : undefined;
+	if (override === undefined) return configuration.value;
+	if (!configuration.schema) throw new Error(`Run config override provided without config schema: ${configuration.key}`);
+	const input = isPlainObject(configuration.input) && isPlainObject(override) ? deepMerge(configuration.input, override) : override;
+	return Value.Decode(configuration.schema, input);
 }
 
 function deepMerge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
-	const result: Record<string, unknown> = { ...base };
-	for (const [key, value] of Object.entries(override)) {
-		const baseValue = result[key];
-		result[key] = isPlainObject(baseValue) && isPlainObject(value) ? deepMerge(baseValue, value) : value;
-	}
+	const result = { ...base };
+	for (const [key, value] of Object.entries(override)) result[key] = isPlainObject(result[key]) && isPlainObject(value) ? deepMerge(result[key], value) : value;
 	return result;
 }
 
+export function assertWorkflowDefinition(workflow: NornAnyWorkflowDeclaration): void {
+	assertWorkflowMetadata(workflow);
+	if (!isWorkflowDeclaration(workflow)) throw new Error("Invalid workflow definition");
+	assertGateWorkflow(workflow);
+}
+
 function assertGateWorkflow(workflow: NornAnyWorkflowDeclaration): void {
 	if (!workflow.gate) return;
 	if (workflow.gate.enabled !== true) throw new Error(`Workflow gate must be enabled with true: ${workflow.id}`);
+	if (workflow.gate.describe !== undefined && typeof workflow.gate.describe !== "function") throw new Error(`Invalid gate description callback: ${workflow.id}`);
 	if (!workflow.gate.fields) return;
-	const paramsSchema = unwrapSchema(workflow.params);
-	if (schemaType(paramsSchema) !== "object") throw new Error(`Workflow gate fields require object params: ${workflow.id}`);
-	const paramsShape = schemaShape(paramsSchema);
-	for (const field of workflow.gate.fields) {
-		if (!Object.prototype.hasOwnProperty.call(paramsShape, field)) throw new Error(`Unknown workflow gate field ${field}: ${workflow.id}`);
-	}
-}
-
-function validateGateDescription(description: string, workflowId: string): string {
-	const trimmed = description.trim();
-	if (trimmed.length === 0) throw new Error(`Workflow gate description must not be empty: ${workflowId}`);
-	return trimmed;
-}
-
-function inspectedWorkflowInfo(entry: NornRegisteredWorkflow): NornInspectedWorkflowInfo {
-	return {
-		...workflowInfo(entry),
-		paramsSchema: inspectSchema(entry.workflow.params),
-		gate: gateInfo(entry.workflow),
-	};
+	const argsSchema = unwrapSchema(workflow.args);
+	if (schemaType(argsSchema) !== "object") throw new Error(`Workflow gate fields require object args: ${workflow.id}`);
+	const shape = schemaShape(argsSchema);
+	for (const field of workflow.gate.fields) if (!Object.hasOwn(shape, field)) throw new Error(`Unknown workflow gate field ${field}: ${workflow.id}`);
 }
 
 function workflowInfo(entry: NornRegisteredWorkflow): NornRegisteredWorkflowInfo {
 	return {
-		id: entry.workflow.id,
-		instructions: entry.workflow.instructions,
-		isEntrypoint: entry.workflow.isEntrypoint,
-		isolation: entry.workflow.isolation,
-		plugin: entry.plugin,
+		id: entry.workflow.id, instructions: entry.workflow.instructions, isEntrypoint: entry.workflow.isEntrypoint,
+		source: entry.source,
+		configKey: entry.workflow.id,
+		scope: entry.scopeId ? { id: entry.scopeId } : undefined,
 	};
 }
-
 function gateInfo(workflow: NornAnyWorkflowDeclaration): NornWorkflowGateInfo | null {
 	return workflow.gate ? { enabled: true, fields: workflow.gate.fields } : null;
 }

package/assets/packages/cli/src/internal/working-directory.ts

@@ -0,0 +1,6 @@
+import { isAbsolute, resolve } from "node:path";
+
+export function requireAbsoluteWorkingDirectory(cwd: string): string {
+	if (typeof cwd !== "string" || !isAbsolute(cwd)) throw new Error("Working directory (cwd) must be an absolute path");
+	return resolve(cwd);
+}