@oisincoveney/pipeline 2.1.1 → 2.3.0

package/dist/runtime/opencode-adapter.js

@@ -1,11 +1,31 @@
 import { isRecord } from "../safe-json.js";
 import { jsonLineValues } from "../json-line-values.js";
 //#region src/runtime/opencode-adapter.ts
-const opencodeCliRuntimeAdapter = {
-	continuation() {
-		return Promise.reject(/* @__PURE__ */ new Error("OpenCode CLI runtime adapter does not expose native continuation yet"));
+/**
+* Output-parsing seam for opencode runner output. The SDK executor
+* (opencode-session-executor.ts) re-serializes assistant text parts into the
+* same `{ part: { type: "text", text } }` JSONL the legacy CLI emitted, so this
+* parser is transport-agnostic and the structured-output / repair passes work
+* unchanged on top of SDK responses.
+*
+* The session lifecycle, event-stream forwarding, and per-message agent/model
+* selection live in opencode-session-executor.ts + opencode-server.ts; this
+* adapter only normalizes output and reports capabilities.
+*/
+const opencodeSdkRuntimeAdapter = {
+	continuation(request) {
+		return Promise.resolve({ metadata: {
+			adapterId: "opencode-sdk",
+			continuationApi: "session-reuse",
+			nodeId: request.sessionId,
+			outputFormat: "text",
+			pluginEvents: "server-event-stream",
+			runnerId: "opencode",
+			sessionInspectionApi: "sdk",
+			worktreePath: ""
+		} });
 	},
-	id: "opencode-cli-subprocess",
+	id: "opencode-sdk",
 	launch(plan) {
 		assertOpenCodePlan(plan);
 		return {
@@ -37,13 +57,13 @@ const opencodeCliRuntimeAdapter = {
 		assertOpenCodePlan(plan);
 		return {
 			adapterId: this.id,
-			continuationApi: "unavailable",
+			continuationApi: "session-reuse",
 			nodeId: plan.nodeId,
 			outputFormat: plan.outputFormat,
-			pluginEvents: "project-local",
+			pluginEvents: "server-event-stream",
 			profileId: plan.profileId,
 			runnerId: plan.runnerId,
-			sessionInspectionApi: "unavailable",
+			sessionInspectionApi: "sdk",
 			worktreePath: plan.cwd
 		};
 	}
@@ -57,4 +77,4 @@ function opencodeTextPart(value) {
 	if (isRecord(part) && part.type === "text") return typeof part.text === "string" ? part.text : void 0;
 }
 //#endregion
-export { opencodeCliRuntimeAdapter };
+export { opencodeSdkRuntimeAdapter };

package/dist/runtime/opencode-agent-name.js

@@ -0,0 +1,18 @@
+//#region src/runtime/opencode-agent-name.ts
+const MOKA_PROFILE_PREFIX = "moka-";
+/**
+* Map a pipeline profile id to the opencode agent name a served instance
+* exposes (e.g. `moka-code-writer` -> `MoKa Code Writer`). Shared by the slash
+* command installer and the SDK runtime so per-message agent selection targets
+* the same `.opencode/agent/*` definition the host projects.
+*/
+function opencodeAgentName(profileId) {
+	if (!profileId.startsWith(MOKA_PROFILE_PREFIX)) return profileId;
+	return `MoKa ${profileId.slice(5).split("-").map(opencodeAgentNamePart).join(" ")}`;
+}
+function opencodeAgentNamePart(part) {
+	if (part === "opencode") return "OpenCode";
+	return `${part.charAt(0).toUpperCase()}${part.slice(1)}`;
+}
+//#endregion
+export { opencodeAgentName };

package/dist/runtime/opencode-runtime.js

@@ -0,0 +1,62 @@
+import { OpencodeServerStartupError, openOpencodeServer } from "./opencode-server.js";
+import { createOpencodeExecutor, createOpencodeSessionRegistry } from "./opencode-session-executor.js";
+//#region src/runtime/opencode-runtime.ts
+/**
+* True when the config declares any opencode runner, i.e. the SDK transport is
+* relevant for this run. Command-only configs never start a server.
+*/
+function configUsesOpencode(config) {
+	return Object.values(config.runners).some((runner) => runner.type === "opencode");
+}
+/**
+* Return an SDK-backed executor plus a release() that tears the server down.
+* The opencode server is started LAZILY on the first executor call, not at
+* lease time: a run whose ready nodes are all command/builtin (or that fails
+* before any agent node executes) never spawns opencode, so the binary is only
+* required when an agent node actually runs. release() is a no-op if the server
+* was never started. Caller owns the lifecycle:
+*
+*   const lease = await leaseOpencodeRuntime({ config, worktreePath });
+*   try { ...run with lease.executor... } finally { await lease.release(); }
+*/
+function leaseOpencodeRuntime(input) {
+	const registry = createOpencodeSessionRegistry();
+	const openHandle = input.openServer ?? startServer;
+	let handle;
+	let pending;
+	const ensureExecutor = () => {
+		pending ??= openHandle(input).then((started) => {
+			handle = started;
+			return createOpencodeExecutor({
+				client: started.client,
+				directory: input.worktreePath,
+				registry
+			});
+		});
+		return pending;
+	};
+	return Promise.resolve({
+		executor: async (plan, options) => {
+			return await (await ensureExecutor())(plan, options);
+		},
+		release: async () => {
+			if (handle) {
+				await handle.close();
+				handle = void 0;
+			}
+		}
+	});
+}
+async function startServer(input) {
+	try {
+		return await openOpencodeServer({
+			directory: input.worktreePath,
+			...input.signal ? { signal: input.signal } : {}
+		});
+	} catch (error) {
+		if (error instanceof OpencodeServerStartupError) throw new OpencodeServerStartupError(`${error.message}. Confirm the opencode binary is installed and recent enough to expose 'opencode serve', or set OPENCODE_SERVER_URL to an already-running server.`, { cause: error });
+		throw error;
+	}
+}
+//#endregion
+export { configUsesOpencode, leaseOpencodeRuntime };

package/dist/runtime/opencode-server.js

@@ -0,0 +1,67 @@
+import { createOpencode, createOpencodeClient } from "@opencode-ai/sdk";
+//#region src/runtime/opencode-server.ts
+const DEFAULT_STARTUP_TIMEOUT_MS = 3e4;
+var OpencodeServerStartupError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "OpencodeServerStartupError";
+	}
+};
+async function openOpencodeServer(options) {
+	const externalUrl = options.serverUrl ?? process.env.OPENCODE_SERVER_URL ?? "";
+	if (externalUrl.length > 0) return connectExternalServer(externalUrl, options.directory);
+	return await spawnOwnedServer(options);
+}
+function connectExternalServer(url, directory) {
+	return {
+		close: () => Promise.resolve(),
+		client: createOpencodeClient({
+			baseUrl: url,
+			directory
+		}),
+		owned: false,
+		url
+	};
+}
+async function spawnOwnedServer(options) {
+	const spawn = options.spawn ?? createOpencode;
+	try {
+		const { client, server } = await spawn(spawnArgs(options));
+		return ownedHandle(client, server, options.directory);
+	} catch (error) {
+		throw new OpencodeServerStartupError(`Failed to start opencode server: ${errorText(error)}`, { cause: error });
+	}
+}
+function spawnArgs(options) {
+	return {
+		port: 0,
+		...options.signal ? { signal: options.signal } : {},
+		timeout: options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS
+	};
+}
+function ownedHandle(client, server, directory) {
+	return {
+		close: () => {
+			server.close();
+			return Promise.resolve();
+		},
+		client: withDirectory(client, server.url, directory),
+		owned: true,
+		url: server.url
+	};
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function withDirectory(fallback, url, directory) {
+	try {
+		return createOpencodeClient({
+			baseUrl: url,
+			directory
+		});
+	} catch {
+		return fallback;
+	}
+}
+//#endregion
+export { OpencodeServerStartupError, openOpencodeServer };

package/dist/runtime/opencode-session-executor.js

@@ -0,0 +1,206 @@
+import { opencodeAgentName } from "./opencode-agent-name.js";
+//#region src/runtime/opencode-session-executor.ts
+function createOpencodeSessionRegistry() {
+	return { sessions: /* @__PURE__ */ new Map() };
+}
+/**
+* Distinguish infra failure (server/session error -> retry-eligible exit 70)
+* from a normal agent completion (the agent may still have produced a wrong
+* answer; gates decide that, exit 0). This mirrors the EXIT_STARTUP convention
+* in runner-command/run.ts and feeds retry.ts via the node's retry policy.
+*/
+const EXIT_OK = 0;
+const EXIT_AGENT_ERROR = 1;
+const EXIT_INFRA = 70;
+/**
+* SDK-backed replacement for the subprocess `runLaunchPlan`. Conforms to the
+* RuntimeContext.executor seam so agent-node never learns the transport.
+*/
+function createOpencodeExecutor(deps) {
+	return async function execute(plan, options = {}) {
+		if (plan.type !== "opencode") throw new Error(`opencode executor cannot drive runner type '${plan.type}'`);
+		try {
+			return successResult(plan, await driveSession(deps, plan, options));
+		} catch (error) {
+			return failureResult(plan, error);
+		}
+	};
+}
+async function driveSession(deps, plan, options) {
+	const sessionId = await resolveSessionId(deps, plan);
+	deps.onSession?.(plan.nodeId, sessionId);
+	const stream = await streamEventsToOutput(deps, sessionId, plan, options);
+	try {
+		const data = unwrap(await deps.client.session.prompt({
+			body: promptBody(plan),
+			path: { id: sessionId },
+			query: { directory: deps.directory }
+		}));
+		return {
+			...data.info ? { assistant: data.info } : {},
+			parts: data.parts ?? [],
+			sessionId
+		};
+	} finally {
+		await stream.stop();
+	}
+}
+async function resolveSessionId(deps, plan) {
+	const existing = deps.registry.sessions.get(plan.nodeId);
+	if (existing) return existing;
+	const session = unwrap(await deps.client.session.create({
+		body: { title: `moka:${plan.nodeId}` },
+		query: { directory: deps.directory }
+	}));
+	deps.registry.sessions.set(plan.nodeId, session.id);
+	return session.id;
+}
+function promptBody(plan) {
+	const prompt = promptText(plan);
+	const model = parseModel(plan.model);
+	const agent = plan.profileId ? opencodeAgentName(plan.profileId) : void 0;
+	return {
+		parts: [{
+			text: prompt,
+			type: "text"
+		}],
+		...agent ? { agent } : {},
+		...model ? { model } : {}
+	};
+}
+const FLAGS_TAKING_VALUE = new Set([
+	"--model",
+	"--dir",
+	"--file",
+	"--format"
+]);
+/**
+* The launch plan carries the prompt inside the CLI argv (`run <prompt>` or
+* `run <prompt> --file <ctx>`). Recover it as the trailing positional arg
+* (skipping flags and their values) so the adapter boundary is identical
+* regardless of transport.
+*/
+function promptText(plan) {
+	return plan.args.filter((arg, index) => index > 0 && !arg.startsWith("-") && !FLAGS_TAKING_VALUE.has(plan.args[index - 1] ?? "")).at(-1) ?? "";
+}
+function parseModel(model) {
+	if (!model) return;
+	const slash = model.indexOf("/");
+	if (slash === -1) return;
+	return {
+		modelID: model.slice(slash + 1),
+		providerID: model.slice(0, slash)
+	};
+}
+async function streamEventsToOutput(deps, sessionId, plan, options) {
+	if (!options.onOutput) return { stop: () => Promise.resolve() };
+	const iterator = (await deps.client.event.subscribe()).stream;
+	const pump = (async () => {
+		try {
+			for await (const event of iterator) forwardEvent(event, sessionId, plan, options);
+		} catch (error) {
+			options.onOutput?.({
+				chunk: `opencode event stream dropped: ${errorMessage(error)}\n`,
+				nodeId: plan.nodeId,
+				stream: "stderr"
+			});
+		}
+	})();
+	return { stop: async () => {
+		await iterator.return?.(void 0);
+		await pump;
+	} };
+}
+function forwardEvent(event, sessionId, plan, options) {
+	const forwarded = eventChunk(event, sessionId);
+	if (forwarded) options.onOutput?.({
+		chunk: forwarded.chunk,
+		nodeId: plan.nodeId,
+		stream: forwarded.stream
+	});
+}
+function eventChunk(event, sessionId) {
+	if (event.type === "message.part.updated") return partChunk(event.properties.part, sessionId);
+	if (event.type === "session.error" && belongsToSession(event, sessionId)) return {
+		chunk: `opencode session error: ${describeMessageError(event.properties.error)}\n`,
+		stream: "stderr"
+	};
+}
+function belongsToSession(event, sessionId) {
+	return event.properties.sessionID === void 0 || event.properties.sessionID === sessionId;
+}
+function partChunk(part, sessionId) {
+	if (part.sessionID !== sessionId) return;
+	if (part.type === "text") return {
+		chunk: `${JSON.stringify({ part: {
+			text: part.text,
+			type: "text"
+		} })}\n`,
+		stream: "stdout"
+	};
+	if (part.type === "tool") return {
+		chunk: `opencode tool ${part.tool} ${part.state.status}\n`,
+		stream: "stderr"
+	};
+}
+/**
+* Reconstruct the JSONL stdout the existing normalizeOutput/outputCandidates
+* parser already understands, so the structured-output and repair passes work
+* unchanged on top of SDK responses.
+*/
+function successResult(plan, drive) {
+	const stdout = drive.parts.filter((part) => part.type === "text").map((part) => JSON.stringify({ part: {
+		text: part.text,
+		type: "text"
+	} })).join("\n");
+	const assistantError = drive.assistant?.error;
+	if (assistantError) return {
+		argv: plan.args,
+		exitCode: infraErrorExitCode(assistantError),
+		sessionId: drive.sessionId,
+		stderr: describeMessageError(assistantError),
+		stdout
+	};
+	return {
+		argv: plan.args,
+		exitCode: EXIT_OK,
+		sessionId: drive.sessionId,
+		stdout
+	};
+}
+function failureResult(plan, error) {
+	return {
+		argv: plan.args,
+		exitCode: EXIT_INFRA,
+		stderr: `opencode session failed: ${errorMessage(error)}`,
+		stdout: ""
+	};
+}
+/**
+* Map opencode message errors to the runner's infra-vs-agent exit convention.
+* Output-length / aborted are agent-task outcomes (exit 1, gate territory);
+* provider-auth, API, and unknown are infra (exit 70, retry-eligible).
+*/
+function infraErrorExitCode(error) {
+	switch (error.name) {
+		case "MessageOutputLengthError":
+		case "MessageAbortedError": return EXIT_AGENT_ERROR;
+		default: return EXIT_INFRA;
+	}
+}
+function describeMessageError(error) {
+	if (!error) return "unknown opencode error";
+	const data = error.data;
+	const detail = data && typeof data.message === "string" ? `: ${data.message}` : "";
+	return `${error.name}${detail}`;
+}
+function unwrap(response) {
+	if (response.error) throw new Error(typeof response.error === "string" ? response.error : JSON.stringify(response.error));
+	if (response.data === void 0) throw new Error("opencode response contained no data");
+	return response.data;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { createOpencodeExecutor, createOpencodeSessionRegistry };

package/dist/schedule/passes/coverage.js

@@ -1,12 +1,12 @@
+import { uniqueGeneratedId } from "../../strings.js";
+import { dependentsByNeed, hasReachableDependent } from "../../planning/graph.js";
+import { isCoverageNode, isImplementationNode } from "../scheduling-roles.js";
 //#region src/schedule/passes/coverage.ts
 const DEFAULT_GENERATED_COVERAGE_PROFILE_PREFERENCE = [
 	"moka-verifier",
 	"moka-acceptance-reviewer",
 	"moka-thermo-nuclear-reviewer"
 ];
-const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
-const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
-const STARTS_WITH_ALPHA_RE = /^[a-z]/;
 function addGeneratedImplementationCoverage(config, artifact) {
 	const coverageProfileId = generatedCoverageProfileId(config);
 	if (!coverageProfileId) return artifact;
@@ -26,8 +26,8 @@ function addNodeScopeImplementationCoverage(config, nodes, coverageProfileId) {
 		...node,
 		nodes: addNodeScopeImplementationCoverage(config, node.nodes, coverageProfileId)
 	} : node);
-	const dependentsByNeed = workflowDependentsByNeed(scopedNodes);
-	const uncovered = scopedNodes.filter((node) => isImplementationNode(config, node)).filter((node) => !hasDownstreamCoverage(config, node.id, dependentsByNeed));
+	const index = dependentsByNeed(scopedNodes);
+	const uncovered = scopedNodes.filter((node) => isImplementationNode(config, node)).filter((node) => !hasDownstreamCoverage(config, node.id, index));
 	if (uncovered.length === 0) return scopedNodes;
 	const coverageNodeId = uniqueGeneratedId("generated-coverage", new Set(scopedNodes.map((node) => node.id)), "generated-coverage");
 	return [...scopedNodes, {
@@ -82,52 +82,8 @@ function generatedCoverageGates(nodeId) {
 		}
 	];
 }
-function workflowDependentsByNeed(nodes) {
-	const dependentsByNeed = /* @__PURE__ */ new Map();
-	for (const node of nodes) for (const need of node.needs ?? []) {
-		const dependents = dependentsByNeed.get(need) ?? [];
-		dependents.push(node);
-		dependentsByNeed.set(need, dependents);
-	}
-	return dependentsByNeed;
-}
-function isImplementationNode(config, node) {
-	return hasSchedulingRole(config, node, "implementation");
-}
-function hasDownstreamCoverage(config, nodeId, dependentsByNeed) {
-	return hasReachableDependent(nodeId, dependentsByNeed, (node) => hasSchedulingRole(config, node, "coverage"));
-}
-function hasSchedulingRole(config, node, role) {
-	if (node.kind !== "agent") return false;
-	return config.profiles[node.profile]?.scheduling_roles?.includes(role) ?? false;
-}
-function hasReachableDependent(nodeId, dependentsByNeed, matches) {
-	const visited = /* @__PURE__ */ new Set();
-	const queue = [...dependentsByNeed.get(nodeId) ?? []];
-	while (queue.length > 0) {
-		const node = queue.shift();
-		if (!node || visited.has(node.id)) continue;
-		visited.add(node.id);
-		if (matches(node)) return true;
-		queue.push(...dependentsByNeed.get(node.id) ?? []);
-	}
-	return false;
-}
-function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
-	const base = generatedId(value, fallbackPrefix);
-	let candidate = base;
-	let suffix = 2;
-	while (usedIds.has(candidate)) {
-		candidate = `${base}-${suffix}`;
-		suffix += 1;
-	}
-	usedIds.add(candidate);
-	return candidate;
-}
-function generatedId(value, fallbackPrefix) {
-	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
-	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
-	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
+function hasDownstreamCoverage(config, nodeId, index) {
+	return hasReachableDependent(nodeId, index, (node) => isCoverageNode(config, node));
 }
 //#endregion
 export { addGeneratedImplementationCoverage };

package/dist/schedule/passes/ids.js

@@ -1,7 +1,6 @@
+import { uniqueGeneratedId } from "../../strings.js";
+import { flattenNodes } from "../../planning/graph.js";
 //#region src/schedule/passes/ids.ts
-const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
-const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
-const STARTS_WITH_ALPHA_RE = /^[a-z]/;
 function canonicalizeGeneratedScheduleIds(artifact) {
 	return {
 		...artifact,
@@ -11,7 +10,7 @@ function canonicalizeGeneratedScheduleIds(artifact) {
 function canonicalizeWorkflowNodeIds(workflow) {
 	const nodeIdMap = /* @__PURE__ */ new Map();
 	const usedNodeIds = /* @__PURE__ */ new Set();
-	for (const node of workflow.nodes.flatMap(flattenWorkflowNode)) nodeIdMap.set(node.id, uniqueGeneratedId(node.id, usedNodeIds, "node"));
+	for (const node of flattenNodes(workflow.nodes, (node) => node.kind === "parallel" ? node.nodes : void 0)) nodeIdMap.set(node.id, uniqueGeneratedId(node.id, usedNodeIds, "node"));
 	return {
 		...workflow,
 		nodes: workflow.nodes.map((node) => rewriteGeneratedWorkflowNodeIds(node, nodeIdMap))
@@ -28,24 +27,5 @@ function rewriteGeneratedWorkflowNodeIds(node, nodeIdMap) {
 		nodes: rewritten.nodes.map((child) => rewriteGeneratedWorkflowNodeIds(child, nodeIdMap))
 	} : rewritten;
 }
-function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
-	const base = generatedId(value, fallbackPrefix);
-	let candidate = base;
-	let suffix = 2;
-	while (usedIds.has(candidate)) {
-		candidate = `${base}-${suffix}`;
-		suffix += 1;
-	}
-	usedIds.add(candidate);
-	return candidate;
-}
-function generatedId(value, fallbackPrefix) {
-	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
-	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
-	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
-}
-function flattenWorkflowNode(node) {
-	return node.kind === "parallel" ? [node, ...node.nodes.flatMap(flattenWorkflowNode)] : [node];
-}
 //#endregion
 export { canonicalizeGeneratedScheduleIds };

package/dist/schedule/scheduling-roles.js

@@ -0,0 +1,19 @@
+//#region src/schedule/scheduling-roles.ts
+/**
+* Whether an agent node's profile declares the given scheduling role. Non-agent
+* nodes never carry scheduling roles. This is the single source of truth for the
+* implementation/coverage role policy used by schedule generation and
+* validation.
+*/
+function hasSchedulingRole(config, node, role) {
+	if (node.kind !== "agent") return false;
+	return config.profiles[node.profile]?.scheduling_roles?.includes(role) ?? false;
+}
+function isImplementationNode(config, node) {
+	return hasSchedulingRole(config, node, "implementation");
+}
+function isCoverageNode(config, node) {
+	return hasSchedulingRole(config, node, "coverage");
+}
+//#endregion
+export { isCoverageNode, isImplementationNode };

package/dist/strings.js

@@ -4,5 +4,34 @@ function uniqueStrings(values, options = {}) {
 	const unique = [...new Set(input)];
 	return options.sort ? unique.sort() : unique;
 }
+const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
+const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
+const STARTS_WITH_ALPHA_RE = /^[a-z]/;
+/**
+* Slugify an arbitrary string into a workflow-safe id (lowercase, hyphenated).
+* When the slug does not begin with a letter it is prefixed with
+* `fallbackPrefix` so the result is always a valid node/workflow id.
+*/
+function generatedId(value, fallbackPrefix) {
+	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
+	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
+	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
+}
+/**
+* Slugify `value` to a generated id (see {@link generatedId}) and disambiguate
+* against `usedIds` by appending an incrementing numeric suffix. Mutates
+* `usedIds` to reserve the chosen id.
+*/
+function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
+	const base = generatedId(value, fallbackPrefix);
+	let candidate = base;
+	let suffix = 2;
+	while (usedIds.has(candidate)) {
+		candidate = `${base}-${suffix}`;
+		suffix += 1;
+	}
+	usedIds.add(candidate);
+	return candidate;
+}
 //#endregion
-export { uniqueStrings };
+export { uniqueGeneratedId, uniqueStrings };

package/docs/adr-opencode-first-goal-loop-runtime.md

@@ -1,6 +1,6 @@
 # ADR: OpenCode-First Goal Loop Runtime
 
-Status: Accepted
+Status: Accepted (Codex compatibility subsequently removed; OpenCode and Claude Code are the active command hosts)
 
 Date: 2026-06-08
 

package/docs/config-architecture.md

@@ -306,14 +306,51 @@ timeouts, output limits, sanitized env, and explicit trust flags.
 
 ## Host Support Matrix
 
-| Runner   | Native subagents | Rules | Skills | MCP | Outputs                   | Generated resources             |
-| -------- | ---------------- | ----- | ------ | --- | ------------------------- | ------------------------------- |
-| OpenCode | yes              | yes   | yes    | yes | text, JSON, JSONL, schema | commands, agents, skills, plugins, LSP |
-| command  | no               | no    | no     | no  | declared by runner        | subprocess argv                 |
+| Runner      | Native subagents | Rules | Skills | MCP | Outputs                   | Generated resources             |
+| ----------- | ---------------- | ----- | ------ | --- | ------------------------- | ------------------------------- |
+| OpenCode    | yes              | yes   | yes    | yes | text, JSON, JSONL, schema | commands, agents, skills, plugins, LSP |
+| Claude Code | via `opencode run` | yes (skill) | yes | yes | declared by runner | commands, wrapper agents, settings |
+| command     | no               | no    | no     | no  | declared by runner        | subprocess argv                 |
 
 Generated host resources follow a native runner rule. OpenCode runner nodes use
-OpenCode native agents. Unsupported runner or host mappings fail closed instead
-of doing instruction-only translation or generic worker substitution.
+OpenCode native agents. The Claude Code host does not run MoKa profiles natively:
+its generated `.claude/agents/moka-<role>.md` subagents each wrap a single
+`opencode run --agent "MoKa <role>"` subprocess, so the OpenCode runner remains
+the execution surface while Claude Code orchestrates. Unsupported runner or host
+mappings fail closed instead of doing instruction-only translation or generic
+worker substitution.
+
+## Planning: Compile And Generate
+
+Two distinct planning strategies turn config into an executable plan, and the
+module layout names the distinction (`src/planning/`):
+
+- `planning/compile.ts` — **deterministic DAG compilation**. `compileWorkflowPlan`
+  validates a workflow's nodes (duplicate ids, missing dependencies, group
+  references, cycles), normalizes group dependencies, and produces the
+  `WorkflowExecutionPlan` (graph, topological order, parallel batches). This is
+  the engine's mandatory front door: every execution path runs through it,
+  including AI-generated schedules. Exposed as the `./planner` package subpath.
+- `planning/generate.ts` — **optional AI decomposition**. `generateScheduleArtifact`
+  drives a planner profile to decompose a task into a schedule artifact, then
+  normalizes it through auditable passes (coverage → models → ids → references)
+  and finally feeds it back into `compileScheduleArtifact`, which merges the
+  generated workflows into config and calls `compileWorkflowPlan`. So generate
+  output is always an input to compile — never a substitute for it. Exposed as
+  the `./schedule` package subpath.
+
+Both layers share one policy-free traversal model, `planning/graph.ts`
+(`flattenNodes`, `dependentsByNeed`, `hasReachableDependent`, `findNode`,
+`findDependencyCycles`). Each caller supplies its own predicates and owns its
+error vocabulary, so config validation, deterministic compile, and AI-schedule
+validation reason over the same graph structure without sharing layer-specific
+policy. Schedule-specific support (artifact re-export barrel, baseline, prompts,
+the normalization passes, backlog context, scheduling-role policy) stays under
+`src/schedule/` and imports the artifact + generate API from `planning/generate`.
+
+The toposort uses `@dagrejs/graphlib` for the graph model but an iterative
+traversal for the topological sort, because graphlib's recursive topsort can
+overflow the call stack on deep generated workflow chains.
 
 ## Troubleshooting