@diff-review-system/drs 4.0.1 → 5.0.0-rc.1

package/dist/cli/workflow.js

@@ -16,15 +16,23 @@ import { resolveCursorFixLinkOptions } from '../lib/cursor-fix-link.js';
 import { extractHtmlDocument, parseArtifactOutputPointer, readArtifactOutputPointer, validateHtmlArtifact, } from '../lib/html-artifact.js';
 import { getCanonicalDiffCommand, resolveBaseBranch } from '../lib/repository-validator.js';
 import { formatCodeQualityReport, generateCodeQualityReport } from '../lib/code-quality-report.js';
+import { formatOkfValidationErrors, synchronizeOkfIndexes, validateOkfBundle, } from '../lib/okf-wiki.js';
+import { checkWikiClean, planWikiUpdate, recordWikiState, } from '../lib/wiki-delta.js';
+import { createWikiRunSummary, formatWikiRunSummaryHuman, formatWikiRunSummaryMarkdown, getWikiRunSummary, } from '../lib/wiki-run-summary.js';
 import { createGitHubClient } from '../github/client.js';
 import { GitHubPlatformAdapter } from '../github/platform-adapter.js';
 import { createGitLabClient } from '../gitlab/client.js';
 import { GitLabPlatformAdapter } from '../gitlab/platform-adapter.js';
 import { loadWorkflowArtifact, saveWorkflowArtifact, updateWorkflowArtifact, workflowArtifactExists, } from '../lib/workflow-artifacts.js';
-import { addReviewArtifactFinding, createReviewArtifactPayload, getReviewArtifactStatus, isReviewArtifactPayload, updateReviewArtifactFindings, } from '../lib/review-artifact.js';
+import { addReviewArtifactFinding, createReviewArtifactPayload, getReviewArtifactStatus, isReviewArtifactPayload, reviewArtifactToReviewResult, updateReviewArtifactFindings, } from '../lib/review-artifact.js';
+import { renderAgentPermissions, renderAgentValidation } from '../lib/agent-permissions.js';
 import { runAgent } from './run-agent.js';
 import { TraceCollector } from '../lib/trace-collector.js';
 import { renderTraceHtml } from '../lib/trace-html.js';
+import { buildWorkflowGraph, formatWorkflowGraphMermaid, } from '../lib/workflow/graph.js';
+import { computeActiveWorkflowNodes, createSkippedWorkflowNodeResult, findWorkflowSegmentIndex, getNodeKind, getNodeNeeds, getWorkflowExecutionOrder, getWorkflowExecutionWaves, getWorkflowNodeSkipReason, getWorkflowNodes, hasWorkflowControlNodes, isPotentialWorkspaceMutation, normalizeWorkflowBooleanLike, renderTemplate, runControlWorkflowNode, splitWorkflowSegments, } from '../lib/workflow/planning.js';
+import { getWorkflowInputConfigType } from '../lib/workflow/input.js';
+export { compileWorkflowPlan, } from '../lib/workflow/compiled-plan.js';
 function createWorkflowLock() {
     return { current: Promise.resolve() };
 }
@@ -80,425 +88,6 @@ function getWorkflowPlatformClient(executionContext, platform) {
     executionContext.platformClients[platform] = client;
     return client;
 }
-function getNodeNeeds(node) {
-    if (node.needs === undefined) {
-        return [];
-    }
-    if (!Array.isArray(node.needs)) {
-        throw new Error('Workflow node "needs" must be an array of node ids.');
-    }
-    return node.needs;
-}
-function getControlTargets(node) {
-    const targets = [];
-    if (node.target)
-        targets.push(node.target);
-    if (node.exit)
-        targets.push(node.exit);
-    if (node.default)
-        targets.push(node.default);
-    if (node.cases)
-        targets.push(...Object.values(node.cases));
-    return targets;
-}
-function validateWorkflowControlTargets(nodes) {
-    for (const [nodeId, node] of Object.entries(nodes)) {
-        for (const target of getControlTargets(node)) {
-            if (!nodes[target]) {
-                throw new Error(`Workflow node "${nodeId}" targets unknown node "${target}".`);
-            }
-        }
-    }
-}
-function validateWorkflowControlRouteDirection(nodes, executionOrder) {
-    const segments = splitWorkflowSegments(nodes, executionOrder);
-    for (let segmentIndex = 0; segmentIndex < segments.length; segmentIndex++) {
-        const segment = segments[segmentIndex];
-        if (segment.type !== 'control') {
-            continue;
-        }
-        const node = nodes[segment.nodeId];
-        if (!node || node.control === 'loop') {
-            continue;
-        }
-        for (const target of getControlTargets(node)) {
-            const targetIndex = findWorkflowSegmentIndex(segments, target);
-            if (targetIndex <= segmentIndex) {
-                throw new Error(`Workflow control node "${segment.nodeId}" cannot jump backward to "${target}". Use control: loop with maxIterations for repeated execution.`);
-            }
-        }
-    }
-}
-function validateWorkflowPassThroughShape(nodeId, node) {
-    if (node.control !== 'passThrough') {
-        return;
-    }
-    if (!node.target) {
-        throw new Error(`Workflow passThrough node "${nodeId}" must define "target".`);
-    }
-    const forbiddenKeys = [
-        'if',
-        'then',
-        'else',
-        'exit',
-        'cases',
-        'default',
-        'maxIterations',
-        'onMaxIterations',
-        'value',
-    ];
-    const extraFields = forbiddenKeys.filter((key) => key in node);
-    if (extraFields.length > 0) {
-        throw new Error(`Workflow passThrough node "${nodeId}" must not define extra control logic: ${extraFields.join(', ')}.`);
-    }
-}
-const WORKFLOW_NODE_FIELDS = new Set([
-    'agent',
-    'agentsFrom',
-    'control',
-    'action',
-    'with',
-    'needs',
-    'if',
-    'target',
-    'exit',
-    'maxIterations',
-    'onMaxIterations',
-    'value',
-    'cases',
-    'default',
-    'input',
-    'output',
-    'writes',
-    'json',
-]);
-const EXECUTABLE_NODE_FIELDS = new Set([
-    'agent',
-    'agentsFrom',
-    'action',
-    'with',
-    'needs',
-    'if',
-    'input',
-    'output',
-    'writes',
-    'json',
-]);
-const CONTROL_NODE_FIELDS = {
-    loop: new Set([
-        'control',
-        'needs',
-        'if',
-        'target',
-        'exit',
-        'maxIterations',
-        'onMaxIterations',
-        'output',
-    ]),
-    switch: new Set(['control', 'needs', 'value', 'cases', 'default', 'output']),
-    end: new Set(['control', 'needs', 'output']),
-    passThrough: new Set(['control', 'needs', 'target', 'output']),
-};
-const ACTION_OPTION_FIELDS = {
-    write: new Set(),
-    'git-diff': new Set(['staged']),
-    'git-add': new Set(['path', 'paths']),
-    'git-branch': new Set(['name', 'from', 'force']),
-    'git-commit': new Set(['message', 'path', 'paths']),
-    'git-push': new Set(['remote', 'branch', 'remoteBranch', 'setUpstream', 'force']),
-    'has-diff': new Set(['path', 'paths']),
-    'stack-guard': new Set(['source', 'allowStackedSource', 'reservedPrefixes']),
-    'review-threshold': new Set(['review', 'severity', 'minIssues']),
-    'save-artifact': new Set([
-        'kind',
-        'source',
-        'artifact',
-        'payload',
-        'platform',
-        'project',
-        'projectId',
-        'owner',
-        'repo',
-        'subject',
-        'changeKind',
-        'changeNumber',
-        'pr',
-        'mr',
-        'branch',
-    ]),
-    'load-artifact': new Set([
-        'kind',
-        'source',
-        'id',
-        'platform',
-        'project',
-        'projectId',
-        'owner',
-        'repo',
-        'subject',
-        'changeKind',
-        'changeNumber',
-        'pr',
-        'mr',
-        'branch',
-    ]),
-    'artifact-exists': new Set([
-        'kind',
-        'source',
-        'id',
-        'platform',
-        'project',
-        'projectId',
-        'owner',
-        'repo',
-        'subject',
-        'changeKind',
-        'changeNumber',
-        'pr',
-        'mr',
-        'branch',
-    ]),
-    'create-review-artifact': new Set(['source', 'review']),
-    'review-artifact-status': new Set(['artifact']),
-    'review-artifact-add-finding': new Set(['artifact', 'issue', 'source']),
-    'review-artifact-update-findings': new Set([
-        'artifact',
-        'state',
-        'disposition',
-        'ids',
-        'fingerprints',
-        'severity',
-    ]),
-    'review-artifact-promote-finding': new Set(['artifact', 'ids', 'fingerprints', 'severity']),
-    'review-artifact-resolve-finding': new Set(['artifact', 'ids', 'fingerprints', 'severity']),
-    'verify-fix': new Set(['artifact', 'review', 'fixChange', 'severity', 'minIssues']),
-    'create-change-request': new Set([
-        'platform',
-        'owner',
-        'repo',
-        'project',
-        'projectId',
-        'sourceBranch',
-        'head',
-        'targetBranch',
-        'base',
-        'title',
-        'body',
-        'draft',
-        'reuseExisting',
-    ]),
-    'create-pr': new Set([
-        'platform',
-        'owner',
-        'repo',
-        'project',
-        'projectId',
-        'sourceBranch',
-        'head',
-        'targetBranch',
-        'base',
-        'title',
-        'body',
-        'draft',
-        'reuseExisting',
-    ]),
-    'create-mr': new Set([
-        'platform',
-        'owner',
-        'repo',
-        'project',
-        'projectId',
-        'sourceBranch',
-        'head',
-        'targetBranch',
-        'base',
-        'title',
-        'body',
-        'draft',
-        'reuseExisting',
-    ]),
-    'change-source': new Set([
-        'type',
-        'staged',
-        'from',
-        'to',
-        'includePrereleaseFrom',
-        'owner',
-        'repo',
-        'pr',
-        'project',
-        'projectId',
-        'mr',
-        'mrIid',
-        'source',
-        'fixChange',
-    ]),
-    review: new Set(['source', 'reviewArtifact', 'severity', 'artifact']),
-    'review-context': new Set(['source', 'file', 'baseBranch']),
-    describe: new Set(['source', 'post', 'postDescription']),
-    'code-quality-report': new Set(['review', 'path']),
-    'post-comment': new Set([
-        'source',
-        'platform',
-        'owner',
-        'repo',
-        'project',
-        'projectId',
-        'pr',
-        'mr',
-        'prNumber',
-        'mrIid',
-        'body',
-        'marker',
-    ]),
-    'post-review-comments': new Set(['source', 'review', 'removeErrorComment']),
-    'post-fix-status': new Set([
-        'platform',
-        'owner',
-        'repo',
-        'project',
-        'projectId',
-        'pr',
-        'mr',
-        'source',
-        'reviewArtifact',
-        'fixReview',
-        'fixChange',
-        'severity',
-        'stackedPrUrl',
-        'marker',
-    ]),
-};
-function validateAllowedFields(nodeId, value, allowed, subject) {
-    const unknownFields = Object.keys(value).filter((key) => !allowed.has(key));
-    if (unknownFields.length > 0) {
-        throw new Error(`Workflow ${subject} "${nodeId}" has unsupported field(s): ${unknownFields.join(', ')}.`);
-    }
-}
-function validateWorkflowNodeShape(nodeId, node) {
-    validateAllowedFields(nodeId, node, WORKFLOW_NODE_FIELDS, 'node');
-    const kind = getNodeKind(node);
-    if (kind === 'control') {
-        const control = node.control;
-        if (!control || !CONTROL_NODE_FIELDS[control]) {
-            throw new Error(`Workflow control node "${nodeId}" has unsupported control "${String(control)}".`);
-        }
-        validateAllowedFields(nodeId, node, CONTROL_NODE_FIELDS[control], 'control node');
-        return;
-    }
-    validateAllowedFields(nodeId, node, EXECUTABLE_NODE_FIELDS, 'node');
-    if (node.action && node.with) {
-        const allowed = ACTION_OPTION_FIELDS[node.action];
-        if (!allowed) {
-            throw new Error(`Workflow action node "${nodeId}" has unsupported action "${node.action}".`);
-        }
-        validateAllowedFields(nodeId, node.with, allowed, `node "${nodeId}" with`);
-    }
-}
-function validateWorkflowNodeKinds(nodes) {
-    for (const [nodeId, node] of Object.entries(nodes)) {
-        validateWorkflowNodeShape(nodeId, node);
-        validateWorkflowPassThroughShape(nodeId, node);
-    }
-}
-function hasWorkflowControlNodes(nodes) {
-    return Object.values(nodes).some((node) => node.control !== undefined);
-}
-function getWorkflowExecutionOrder(nodes) {
-    const nodeIds = Object.keys(nodes);
-    const visiting = new Set();
-    const visited = new Set();
-    const order = [];
-    function visit(nodeId) {
-        if (visited.has(nodeId)) {
-            return;
-        }
-        if (visiting.has(nodeId)) {
-            throw new Error(`Workflow contains a dependency cycle at node "${nodeId}".`);
-        }
-        const node = nodes[nodeId];
-        if (!node) {
-            throw new Error(`Workflow references unknown node "${nodeId}".`);
-        }
-        visiting.add(nodeId);
-        for (const dependency of getNodeNeeds(node)) {
-            if (!nodes[dependency]) {
-                throw new Error(`Workflow node "${nodeId}" needs unknown node "${dependency}".`);
-            }
-            visit(dependency);
-        }
-        visiting.delete(nodeId);
-        visited.add(nodeId);
-        order.push(nodeId);
-    }
-    for (const nodeId of nodeIds) {
-        visit(nodeId);
-    }
-    validateWorkflowNodeKinds(nodes);
-    validateWorkflowControlTargets(nodes);
-    const standaloneEndNodes = order.filter((nodeId) => nodes[nodeId]?.control === 'end' && getNodeNeeds(nodes[nodeId] ?? {}).length === 0);
-    const nonStandaloneEndNodes = order.filter((nodeId) => !standaloneEndNodes.includes(nodeId));
-    const executionOrder = [...nonStandaloneEndNodes, ...standaloneEndNodes];
-    validateWorkflowControlRouteDirection(nodes, executionOrder);
-    return executionOrder;
-}
-function getWorkflowNodes(workflowName, workflow) {
-    const nodes = workflow.nodes;
-    if (typeof nodes !== 'object' ||
-        nodes === null ||
-        Array.isArray(nodes) ||
-        Object.keys(nodes).length === 0) {
-        throw new Error(`Workflow "${workflowName}" must define at least one node.`);
-    }
-    return nodes;
-}
-function getWorkflowExecutionWaves(nodes, executionOrder) {
-    const depthByNode = new Map();
-    const waves = [];
-    for (const nodeId of executionOrder) {
-        const node = nodes[nodeId];
-        if (!node) {
-            throw new Error(`Workflow references unknown node "${nodeId}".`);
-        }
-        const depth = getNodeNeeds(node).reduce((maxDepth, dependency) => {
-            return Math.max(maxDepth, (depthByNode.get(dependency) ?? 0) + 1);
-        }, 0);
-        depthByNode.set(nodeId, depth);
-        waves[depth] = waves[depth] ?? [];
-        waves[depth].push(nodeId);
-    }
-    return waves;
-}
-function getPathValue(root, path) {
-    return path.split('.').reduce((current, part) => {
-        if (current === undefined || current === null) {
-            return undefined;
-        }
-        if (typeof current !== 'object') {
-            return undefined;
-        }
-        return current[part];
-    }, root);
-}
-function stringifyTemplateValue(value) {
-    if (value === undefined) {
-        return '';
-    }
-    if (typeof value === 'string') {
-        return value;
-    }
-    return JSON.stringify(value, null, 2);
-}
-function renderTemplate(template, context) {
-    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, rawPath) => {
-        const path = rawPath.trim();
-        const value = getPathValue(context, path);
-        if (value === undefined) {
-            throw new Error(`Unknown workflow template value "{{${path}}}".`);
-        }
-        return stringifyTemplateValue(value);
-    });
-}
 async function flushWorkflowTrace(traceCollector, workflowName, inputs, startedAt, workingDir, options) {
     const workflowTrace = traceCollector.buildWorkflowTrace(workflowName, inputs, startedAt);
     const scope = {
@@ -540,9 +129,6 @@ async function resolveWorkflowInput(key, input, workingDir) {
     }
     return '';
 }
-function getWorkflowInputConfigType(input) {
-    return typeof input === 'string' ? 'string' : (input.type ?? 'string');
-}
 function validateResolvedWorkflowInput(key, input, value) {
     if (typeof input === 'string') {
         return;
@@ -600,24 +186,11 @@ function resolveAgentsFrom(config, agentsFrom) {
     }
     throw new Error(`Unsupported workflow agentsFrom "${agentsFrom}". ` + 'Currently supported: review.agents.');
 }
-function getNodeKind(node) {
-    const configuredKinds = [node.agent, node.agentsFrom, node.action, node.control].filter((value) => value !== undefined).length;
-    if (configuredKinds !== 1) {
-        throw new Error('Workflow node must define exactly one of agent, agentsFrom, action, or control.');
-    }
-    if (node.agent !== undefined)
-        return 'agent';
-    if (node.agentsFrom !== undefined)
-        return 'agents';
-    if (node.control !== undefined)
-        return 'control';
-    return 'action';
-}
 function hasConfiguredAgentPrompt(config, agentId) {
     const runConfig = resolveAgentRunConfig(config, agentId);
     return runConfig.prompt !== undefined || runConfig.promptFile !== undefined;
 }
-function createAgentOptions(prompt, options, workingDir) {
+function createAgentOptions(prompt, options, workingDir, node, context) {
     return {
         prompt,
         jsonOutput: false,
@@ -627,6 +200,16 @@ function createAgentOptions(prompt, options, workingDir) {
         quiet: true,
         allowImplicitStdin: false,
         ignoreConfiguredOutput: true,
+        ...(node.permissions
+            ? {
+                permissions: renderAgentPermissions(node.permissions, (value) => renderTemplate(value, context)),
+            }
+            : {}),
+        ...(node.validation
+            ? {
+                validation: renderAgentValidation(node.validation, (value) => renderTemplate(value, context)),
+            }
+            : {}),
     };
 }
 async function writeWorkflowFile(workingDir, relativeOutputPath, content) {
@@ -686,7 +269,7 @@ async function runAgentWorkflowNode(config, nodeId, node, options, workingDir, c
         throw new Error(`Workflow agent node "${nodeId}" must define input or configure ` +
             `agents.overrides.${agentId}.run.prompt/promptFile.`);
     }
-    const agentOptions = createAgentOptions(prompt, options, workingDir);
+    const agentOptions = createAgentOptions(prompt, options, workingDir, node, context);
     if (executionContext?.traceCollector && prompt) {
         agentOptions.traceCollector = executionContext.traceCollector;
         executionContext.traceCollector.setContext(nodeId, agentId, prompt);
@@ -704,6 +287,8 @@ async function runAgentWorkflowNode(config, nodeId, node, options, workingDir, c
         type: 'agent',
         agent: agentId,
         response: result.response,
+        usage: result.usage,
+        workspaceChanges: result.workspaceChanges,
         output,
         writes,
     };
@@ -722,7 +307,7 @@ async function runAgentsWorkflowNode(config, nodeId, node, options, workingDir,
                 `agents.overrides.${missingPromptAgent}.run.prompt/promptFile.`);
         }
     }
-    const responses = await Promise.all(agentIds.map((agentId) => runAgent(config, agentId, createAgentOptions(prompt, options, workingDir))));
+    const responses = await Promise.all(agentIds.map((agentId) => runAgent(config, agentId, createAgentOptions(prompt, options, workingDir, node, context))));
     const response = responses
         .map((result) => `## ${result.agent}\n\n${result.response.trim()}`.trim())
         .join('\n\n');
@@ -823,6 +408,27 @@ async function runActionWorkflowNode(config, nodeId, node, options, workingDir,
     if (node.action === 'code-quality-report') {
         return runCodeQualityReportWorkflowNode(nodeId, node, workingDir, context);
     }
+    if (node.action === 'plan-wiki-update') {
+        return runPlanWikiUpdateWorkflowNode(nodeId, node, workingDir, context);
+    }
+    if (node.action === 'sync-okf-indexes') {
+        return runSyncOkfIndexesWorkflowNode(nodeId, node, workingDir, context);
+    }
+    if (node.action === 'validate-okf-wiki') {
+        return runValidateOkfWikiWorkflowNode(nodeId, node, workingDir, context);
+    }
+    if (node.action === 'summarize-wiki-run') {
+        return runSummarizeWikiRunWorkflowNode(nodeId, node, context);
+    }
+    if (node.action === 'record-wiki-state') {
+        return runRecordWikiStateWorkflowNode(nodeId, node, workingDir, context);
+    }
+    if (node.action === 'check-wiki-state') {
+        return runCheckWikiStateWorkflowNode(nodeId, node, workingDir, context);
+    }
+    if (node.action === 'check-wiki-clean') {
+        return runCheckWikiCleanWorkflowNode(nodeId, node, workingDir, context);
+    }
     if (node.action === 'post-comment') {
         return runPostCommentWorkflowNode(nodeId, node, options, workingDir, context, executionContext);
     }
@@ -976,13 +582,45 @@ async function runGitBranchWorkflowNode(nodeId, node, workingDir, context, execu
 async function runGitCommitWorkflowNode(nodeId, node, workingDir, context, executionContext) {
     const git = await requireWorkflowGitRepo(nodeId, workingDir, executionContext);
     const message = requireStringActionOption(nodeId, node, 'message', context);
+    const useChangeRequestAuthor = getBooleanActionOption(node, 'useChangeRequestAuthor', context);
+    let commitGit = git;
+    if (useChangeRequestAuthor) {
+        const configuredSource = getStringActionOption(node, 'source', context)?.trim();
+        const sourceArtifact = configuredSource ?? 'change';
+        const source = context.artifacts[sourceArtifact];
+        const platform = isReviewSource(source) && typeof source.context.platform === 'string'
+            ? source.context.platform
+            : undefined;
+        const pullRequest = isReviewSource(source) && isPullRequest(source.context.pullRequest)
+            ? source.context.pullRequest
+            : undefined;
+        const name = pullRequest?.author.trim();
+        const email = pullRequest?.authorEmail?.trim();
+        if (!isWorkflowPlatform(platform) ||
+            !name ||
+            name === 'Unknown' ||
+            /[\0\r\n]/.test(name) ||
+            !email ||
+            /[\0\r\n]/.test(email) ||
+            !/^[^\s<>@]+@[^\s<>@]+$/.test(email)) {
+            throw new Error(`Workflow git-commit node "${nodeId}" with.useChangeRequestAuthor requires source artifact "${sourceArtifact}" to contain a GitHub PR or GitLab MR creator identity.`);
+        }
+        const environment = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+        commitGit = simpleGit({ baseDir: workingDir }).env({
+            ...environment,
+            GIT_AUTHOR_NAME: name,
+            GIT_AUTHOR_EMAIL: email,
+            GIT_COMMITTER_NAME: name,
+            GIT_COMMITTER_EMAIL: email,
+        });
+    }
     const paths = hasActionOption(node, 'paths') || hasActionOption(node, 'path')
         ? getPathActionOption(nodeId, node, context, workingDir)
         : undefined;
     if (paths) {
         await git.add(paths);
     }
-    const commit = paths ? await git.commit(message, paths) : await git.commit(message);
+    const commit = paths ? await commitGit.commit(message, paths) : await commitGit.commit(message);
     const output = {
         commit: commit.commit,
         message,
@@ -1555,16 +1193,59 @@ function createPlatformChangeSource(platform, name, projectId, pullRequest, chan
         workingDir,
     };
 }
+function getPatchChangeCounts(patch) {
+    let additions = 0;
+    let deletions = 0;
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('+'))
+            additions += 1;
+        if (line.startsWith('-'))
+            deletions += 1;
+    }
+    return { additions, deletions };
+}
 async function loadGitHubChangeSource(nodeId, node, workingDir, context, executionContext) {
     const owner = requireStringActionOption(nodeId, node, 'owner', context);
     const repo = requireStringActionOption(nodeId, node, 'repo', context);
     const prNumber = requireNumberActionOption(nodeId, node, 'pr', context);
     const projectId = `${owner}/${repo}`;
     const platformClient = getWorkflowPlatformClient(executionContext, 'github');
-    const [pullRequest, changedFiles] = await Promise.all([
-        platformClient.getPullRequest(projectId, prNumber),
-        platformClient.getChangedFiles(projectId, prNumber),
-    ]);
+    const requireCompleteDiff = getBooleanActionOption(node, 'requireCompleteDiff', context);
+    let pullRequest;
+    let changedFiles;
+    if (requireCompleteDiff) {
+        const before = await platformClient.getPullRequest(projectId, prNumber);
+        changedFiles = await platformClient.getChangedFiles(projectId, prNumber);
+        const after = await platformClient.getPullRequest(projectId, prNumber);
+        if (before.headSha !== after.headSha) {
+            throw new Error(`Workflow change-source node "${nodeId}" cannot review an unstable pull request head.`);
+        }
+        const platformData = after.platformData;
+        const expectedFileCount = platformData && typeof platformData === 'object' && 'changed_files' in platformData
+            ? platformData.changed_files
+            : undefined;
+        if (typeof expectedFileCount !== 'number' ||
+            !Number.isInteger(expectedFileCount) ||
+            expectedFileCount !== changedFiles.length) {
+            throw new Error(`Workflow change-source node "${nodeId}" did not receive the complete GitHub file list.`);
+        }
+        const incompleteFiles = changedFiles.filter((file) => {
+            if (!file.patch || file.patch.length === 0)
+                return true;
+            const counts = getPatchChangeCounts(file.patch);
+            return counts.additions !== file.additions || counts.deletions !== file.deletions;
+        });
+        if (incompleteFiles.length > 0) {
+            throw new Error(`Workflow change-source node "${nodeId}" did not receive complete patches for: ${incompleteFiles.map((file) => file.filename).join(', ')}`);
+        }
+        pullRequest = after;
+    }
+    else {
+        [pullRequest, changedFiles] = await Promise.all([
+            platformClient.getPullRequest(projectId, prNumber),
+            platformClient.getChangedFiles(projectId, prNumber),
+        ]);
+    }
     return createPlatformChangeSource('github', `GitHub PR ${projectId}#${prNumber}`, projectId, pullRequest, changedFiles, workingDir);
 }
 async function loadGitLabChangeSource(nodeId, node, workingDir, context, executionContext) {
@@ -1987,6 +1668,154 @@ async function runCodeQualityReportWorkflowNode(nodeId, node, workingDir, contex
         writes: reportPath,
     };
 }
+async function runSyncOkfIndexesWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const version = getStringActionOption(node, 'version', context)?.trim() ?? '0.1';
+    const result = await synchronizeOkfIndexes(workingDir, root, version);
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: `synchronized ${result.indexes} OKF indexes under ${result.root} (${result.updated} updated)`,
+        output: result,
+    };
+}
+function getWikiInstructionsActionOptions(node, context) {
+    const instructionsPath = getStringActionOption(node, 'instructionsPath', context)?.trim();
+    const instructions = getStringActionOption(node, 'instructions', context);
+    return {
+        ...(instructionsPath ? { instructionsPath } : {}),
+        ...(instructions !== undefined ? { instructions } : {}),
+    };
+}
+async function runPlanWikiUpdateWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const statePath = getStringActionOption(node, 'statePath', context)?.trim() ?? '.drs/wiki-state.json';
+    const result = await planWikiUpdate(workingDir, root, statePath, getWikiInstructionsActionOptions(node, context));
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: `${result.mode}: ${result.reason}`,
+        output: result,
+    };
+}
+async function runValidateOkfWikiWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const version = getStringActionOption(node, 'version', context)?.trim() ?? '0.1';
+    const result = await validateOkfBundle(workingDir, root, version);
+    if (!result.valid) {
+        throw new Error(`Workflow validate-okf-wiki node "${nodeId}" found ${result.errors.length} error(s):\n${formatOkfValidationErrors(result)}`);
+    }
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: `validated ${result.concepts} OKF concepts under ${result.root} with ` +
+            `${result.warnings.length} warning(s); graph: ${result.graph.nodeCount} nodes, ` +
+            `${result.graph.directedEdgeCount} directed edges, ` +
+            `${result.graph.orphanConceptCount} orphans, ` +
+            `${result.graph.weaklyConnectedConceptCount} weakly connected`,
+        output: result,
+    };
+}
+function runSummarizeWikiRunWorkflowNode(nodeId, node, context) {
+    const planName = getStringActionOption(node, 'plan', context)?.trim() ?? 'wikiDelta';
+    const validationName = getStringActionOption(node, 'validation', context)?.trim() ?? 'wikiValidation';
+    const agentNodeId = getStringActionOption(node, 'agentNode', context)?.trim() ?? 'maintain-wiki';
+    const plan = requireWikiUpdatePlan(context.artifacts[planName], nodeId, planName);
+    const validation = requireWikiValidation(context.artifacts[validationName], nodeId, validationName);
+    const agentNode = context.nodes[agentNodeId];
+    if (plan.shouldRun &&
+        (!agentNode || agentNode.status === 'skipped' || agentNode.type !== 'agent')) {
+        throw new Error(`Workflow summarize-wiki-run node "${nodeId}" expected completed agent node "${agentNodeId}".`);
+    }
+    const startedAt = context.startedAt ? Date.parse(context.startedAt) : Date.now();
+    const summary = createWikiRunSummary({
+        plan,
+        validation,
+        modelInvoked: plan.shouldRun,
+        usage: plan.shouldRun ? agentNode?.usage : undefined,
+        workspaceChanges: plan.shouldRun ? agentNode?.workspaceChanges : undefined,
+        elapsedMs: Date.now() - (Number.isFinite(startedAt) ? startedAt : Date.now()),
+    });
+    const response = formatWikiRunSummaryHuman(summary);
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response,
+        output: { ...validation, summary, summaryMarkdown: formatWikiRunSummaryMarkdown(summary) },
+    };
+}
+function requireWikiUpdatePlan(value, nodeId, artifactName) {
+    if (!isRecord(value) ||
+        !['generate', 'reconcile', 'update', 'noop'].includes(String(value.mode)) ||
+        typeof value.shouldRun !== 'boolean' ||
+        typeof value.changedPathCount !== 'number') {
+        throw new Error(`Workflow summarize-wiki-run node "${nodeId}" needs a wiki update plan artifact at "${artifactName}".`);
+    }
+    return value;
+}
+function requireWikiValidation(value, nodeId, artifactName) {
+    if (!isRecord(value) ||
+        typeof value.valid !== 'boolean' ||
+        typeof value.root !== 'string' ||
+        typeof value.concepts !== 'number' ||
+        !Array.isArray(value.errors) ||
+        !Array.isArray(value.warnings) ||
+        !isRecord(value.graph)) {
+        throw new Error(`Workflow summarize-wiki-run node "${nodeId}" needs an OKF validation artifact at "${artifactName}".`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+async function runRecordWikiStateWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const statePath = getStringActionOption(node, 'statePath', context)?.trim() ?? '.drs/wiki-state.json';
+    const result = await recordWikiState(workingDir, root, statePath, getWikiInstructionsActionOptions(node, context));
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: `recorded wiki state for ${result.root} at ${result.gitHead}`,
+        output: result,
+        writes: statePath,
+    };
+}
+async function runCheckWikiCleanWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const statePath = getStringActionOption(node, 'statePath', context)?.trim() ?? '.drs/wiki-state.json';
+    const result = await checkWikiClean(workingDir, root, statePath);
+    if (!result.clean) {
+        throw new Error(`Workflow check-wiki-clean node "${nodeId}" found stale wiki output:\n${result.changedPaths.map((filePath) => `- ${filePath}`).join('\n')}`);
+    }
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: `wiki bundle ${result.root} and state ${result.statePath} are current`,
+        output: result,
+    };
+}
+async function runCheckWikiStateWorkflowNode(nodeId, node, workingDir, context) {
+    const root = getStringActionOption(node, 'root', context)?.trim() ?? 'wiki';
+    const statePath = getStringActionOption(node, 'statePath', context)?.trim() ?? '.drs/wiki-state.json';
+    const result = await planWikiUpdate(workingDir, root, statePath, getWikiInstructionsActionOptions(node, context));
+    if (result.shouldRun) {
+        const paths = result.changedPaths.map((filePath) => `- ${filePath}`).join('\n');
+        throw new Error(`Workflow check-wiki-state node "${nodeId}" found a stale wiki (${result.mode}): ${result.reason}${paths ? `\n${paths}` : ''}`);
+    }
+    return {
+        id: nodeId,
+        type: 'action',
+        action: node.action,
+        response: result.reason,
+        output: result,
+    };
+}
 async function runDescribeWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext) {
     const sourceArtifact = getStringActionOption(node, 'source', context) ?? 'change';
     const source = context.artifacts[sourceArtifact];
@@ -2041,7 +1870,10 @@ async function runPostCommentWorkflowNode(nodeId, node, options, workingDir, con
     const rawBody = node.input === undefined
         ? requireStringActionOption(nodeId, node, 'body', context)
         : renderTemplate(node.input, context);
-    const marker = getStringActionOption(node, 'marker', context)?.trim();
+    const configuredMarker = getStringActionOption(node, 'marker', context)?.trim();
+    const marker = configuredMarker && configuredMarker.length > 0
+        ? configuredMarker
+        : options.idempotencyContext?.idempotencyKey;
     const body = formatMarkedComment(rawBody, marker);
     let operation = 'created';
     if (marker) {
@@ -2076,15 +1908,35 @@ async function runPostReviewCommentsWorkflowNode(config, nodeId, node, options,
     const sourceArtifact = getStringActionOption(node, 'source', context) ?? 'change';
     const reviewArtifact = getStringActionOption(node, 'review', context) ?? 'review';
     const source = context.artifacts[sourceArtifact];
-    const reviewResult = context.artifacts[reviewArtifact];
+    const reviewValue = context.artifacts[reviewArtifact];
     if (!isReviewSource(source)) {
         throw new Error(`Workflow post-review-comments node "${nodeId}" needs a ReviewSource artifact.`);
     }
-    if (!isReviewResult(reviewResult)) {
-        throw new Error(`Workflow post-review-comments node "${nodeId}" needs a ReviewResult artifact.`);
-    }
     const target = resolvePostTarget(nodeId, node, context, executionContext, source);
     const pullRequest = target.pullRequest;
+    const canonicalArtifactMode = hasActionOption(node, 'expectedHeadSha');
+    const expectedHeadSha = getStringActionOption(node, 'expectedHeadSha', context)?.trim();
+    let reviewResult;
+    if (canonicalArtifactMode) {
+        if (!expectedHeadSha || !pullRequest) {
+            throw new Error(`Workflow post-review-comments node "${nodeId}" needs pull request metadata and a non-empty expectedHeadSha to validate a canonical review artifact.`);
+        }
+        reviewResult = reviewArtifactToReviewResult(reviewValue, {
+            platform: target.platform,
+            projectId: target.projectId,
+            changeKind: target.platform === 'gitlab' ? 'mr' : 'pr',
+            changeNumber: target.prNumber,
+            expectedHeadSha,
+            currentHeadSha: pullRequest.headSha,
+            changedFiles: source.files,
+        });
+    }
+    else if (isReviewResult(reviewValue)) {
+        reviewResult = reviewValue;
+    }
+    else {
+        throw new Error(`Workflow post-review-comments node "${nodeId}" needs a ReviewResult artifact or a canonical review artifact with expectedHeadSha.`);
+    }
     const platformData = pullRequest?.platformData;
     const lineValidator = createWorkflowLineValidator(target.platform, source);
     const createInlinePosition = lineValidator
@@ -2092,10 +1944,15 @@ async function runPostReviewCommentsWorkflowNode(config, nodeId, node, options,
         : undefined;
     const shouldRemoveErrorComment = !hasActionOption(node, 'removeErrorComment') ||
         getBooleanActionOption(node, 'removeErrorComment', context);
-    await withWorkflowConsoleSuppressed(executionContext, options.jsonOutput === true, async () => {
-        if (shouldRemoveErrorComment) {
-            await removeErrorComment(target.platformClient, target.projectId, target.prNumber);
+    const assertCurrentHead = expectedHeadSha
+        ? async () => {
+            const latestPullRequest = await target.platformClient.getPullRequest(target.projectId, target.prNumber);
+            if (latestPullRequest.headSha !== expectedHeadSha) {
+                throw new Error('Pull request head changed before review comments could be posted.');
+            }
         }
+        : undefined;
+    await withWorkflowConsoleSuppressed(executionContext, options.jsonOutput === true, async () => {
         const cursorFixLinks = resolveCursorFixLinkOptions(config, target.projectId, workingDir);
         await postReviewComments(target.platformClient, target.projectId, target.prNumber, reviewResult.summary, reviewResult.issues, reviewResult.changeSummary, reviewResult.usage, platformData, lineValidator, createInlinePosition, cursorFixLinks, pullRequest
             ? {
@@ -2103,6 +1960,8 @@ async function runPostReviewCommentsWorkflowNode(config, nodeId, node, options,
                 sourceBranch: pullRequest.sourceBranch,
                 targetBranch: pullRequest.targetBranch,
             }
+            : undefined, assertCurrentHead, shouldRemoveErrorComment
+            ? () => removeErrorComment(target.platformClient, target.projectId, target.prNumber, assertCurrentHead)
             : undefined);
     });
     return {
@@ -2432,11 +2291,17 @@ async function runReviewWorkflowNode(config, nodeId, node, options, workingDir,
             console.warn = () => undefined;
         }
         try {
-            return await executeReview(config, {
+            const reviewSource = {
                 ...sourceForReview,
                 workingDir: sourceForReview.workingDir ?? workingDir,
                 debug: options.debug,
                 thinkingLevel: options.thinkingLevel,
+            };
+            if (!node.permissions) {
+                return await executeReview(config, reviewSource);
+            }
+            return await executeReview(config, reviewSource, {
+                permissions: renderAgentPermissions(node.permissions, (value) => renderTemplate(value, context)),
             });
         }
         finally {
@@ -2450,19 +2315,25 @@ async function runReviewWorkflowNode(config, nodeId, node, options, workingDir,
     if (writes) {
         await writeWorkflowFile(workingDir, writes, JSON.stringify(reviewResult, null, 2));
     }
-    const artifactOutput = getStringActionOption(node, 'artifact', context)?.trim();
+    const explicitArtifactOutput = getStringActionOption(node, 'artifact', context)?.trim();
+    let artifactOutput;
+    if (explicitArtifactOutput) {
+        artifactOutput = explicitArtifactOutput;
+    }
+    else if (!reviewArtifactName) {
+        artifactOutput = `${nodeId}Artifact`;
+    }
     const outputs = {};
-    let artifactResponse = '';
+    const reviewArtifactPayload = createReviewArtifactPayload(reviewResult, source);
+    const scope = await resolveArtifactScope(nodeId, node, workingDir, context, executionContext);
+    const saved = await saveWorkflowArtifact(workingDir, {
+        kind: 'review',
+        scope,
+        payload: reviewArtifactPayload,
+    });
+    const artifactResponse = `\nSaved review artifact ${saved.artifact.id}.`;
     if (artifactOutput) {
-        const reviewArtifact = createReviewArtifactPayload(reviewResult, source);
-        const scope = await resolveArtifactScope(nodeId, node, workingDir, context, executionContext);
-        const saved = await saveWorkflowArtifact(workingDir, {
-            kind: 'review',
-            scope,
-            payload: reviewArtifact,
-        });
         outputs[artifactOutput] = { ...saved.artifact, path: saved.path, latestPath: saved.latestPath };
-        artifactResponse = `\nSaved review artifact ${saved.artifact.id}.`;
     }
     return {
         id: nodeId,
@@ -2486,272 +2357,6 @@ function recordNodeArtifact(nodeId, node, result, artifacts) {
         }
     }
 }
-function parseWorkflowExpressionValue(value, context) {
-    const trimmed = value.trim();
-    if (!trimmed)
-        return '';
-    const templateReference = trimmed.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
-    if (templateReference && context) {
-        const path = templateReference[1]?.trim() ?? '';
-        const resolved = getPathValue(context, path);
-        if (resolved === undefined) {
-            throw new Error(`Unknown workflow template value "{{${path}}}".`);
-        }
-        return resolved;
-    }
-    if (trimmed === 'true')
-        return true;
-    if (trimmed === 'false')
-        return false;
-    if (trimmed === 'null')
-        return null;
-    if (/^-?\d+(\.\d+)?$/.test(trimmed))
-        return Number(trimmed);
-    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        const inner = trimmed.slice(1, -1);
-        return context ? renderTemplate(inner, context) : inner;
-    }
-    if (context && /^(inputs|nodes|artifacts|loop)\.[A-Za-z0-9_.-]+$/.test(trimmed)) {
-        const resolved = getPathValue(context, trimmed);
-        if (resolved === undefined) {
-            throw new Error(`Unknown workflow expression value "${trimmed}".`);
-        }
-        return resolved;
-    }
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        return trimmed;
-    }
-}
-function isWorkflowTruthy(value) {
-    if (value === undefined || value === null)
-        return false;
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number')
-        return value !== 0;
-    if (typeof value === 'string') {
-        const normalized = value.trim().toLowerCase();
-        return (normalized.length > 0 && normalized !== 'false' && normalized !== '0' && normalized !== 'no');
-    }
-    if (Array.isArray(value))
-        return value.length > 0;
-    if (typeof value === 'object')
-        return Object.keys(value).length > 0;
-    return true;
-}
-function normalizeWorkflowBooleanLike(value) {
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number') {
-        if (value === 1)
-            return true;
-        if (value === 0)
-            return false;
-    }
-    if (typeof value === 'string') {
-        const normalized = value.trim().toLowerCase();
-        if (normalized === 'true' || normalized === '1' || normalized === 'yes')
-            return true;
-        if (normalized === 'false' || normalized === '0' || normalized === 'no')
-            return false;
-    }
-    return undefined;
-}
-function compareWorkflowValues(left, operator, right) {
-    if (operator === '==' || operator === '!=') {
-        const leftBoolean = normalizeWorkflowBooleanLike(left);
-        const rightBoolean = normalizeWorkflowBooleanLike(right);
-        const matches = leftBoolean !== undefined || rightBoolean !== undefined
-            ? leftBoolean === rightBoolean
-            : String(left) === String(right);
-        return operator === '==' ? matches : !matches;
-    }
-    const leftNumber = Number(left);
-    const rightNumber = Number(right);
-    if (!Number.isFinite(leftNumber) || !Number.isFinite(rightNumber)) {
-        throw new Error(`Workflow expression operator "${operator}" requires numeric values.`);
-    }
-    if (operator === '>')
-        return leftNumber > rightNumber;
-    if (operator === '>=')
-        return leftNumber >= rightNumber;
-    if (operator === '<')
-        return leftNumber < rightNumber;
-    if (operator === '<=')
-        return leftNumber <= rightNumber;
-    throw new Error(`Unsupported workflow expression operator "${operator}".`);
-}
-function splitWorkflowExpressionOperator(expression, operator) {
-    const parts = [];
-    let current = '';
-    let quote;
-    let depth = 0;
-    for (let i = 0; i < expression.length; i++) {
-        const char = expression[i] ?? '';
-        if ((char === '"' || char === "'") && expression[i - 1] !== '\\') {
-            quote = quote === char ? undefined : (quote ?? char);
-            current += char;
-            continue;
-        }
-        if (!quote && char === '(') {
-            depth += 1;
-            current += char;
-            continue;
-        }
-        if (!quote && char === ')' && depth > 0) {
-            depth -= 1;
-            current += char;
-            continue;
-        }
-        if (!quote && depth === 0 && expression.slice(i, i + operator.length) === operator) {
-            parts.push(current.trim());
-            current = '';
-            i += operator.length - 1;
-            continue;
-        }
-        current += char;
-    }
-    parts.push(current.trim());
-    return parts;
-}
-function stripWorkflowExpressionParens(expression) {
-    const trimmed = expression.trim();
-    if (!trimmed.startsWith('(') || !trimmed.endsWith(')')) {
-        return trimmed;
-    }
-    let quote;
-    let depth = 0;
-    for (let i = 0; i < trimmed.length; i++) {
-        const char = trimmed[i] ?? '';
-        if ((char === '"' || char === "'") && trimmed[i - 1] !== '\\') {
-            quote = quote === char ? undefined : (quote ?? char);
-            continue;
-        }
-        if (quote)
-            continue;
-        if (char === '(')
-            depth += 1;
-        if (char === ')')
-            depth -= 1;
-        if (depth === 0 && i < trimmed.length - 1) {
-            return trimmed;
-        }
-    }
-    return trimmed.slice(1, -1).trim();
-}
-function evaluateWorkflowExpressionText(rendered, context) {
-    rendered = stripWorkflowExpressionParens(rendered);
-    const orParts = splitWorkflowExpressionOperator(rendered, '||');
-    if (orParts.length > 1) {
-        return orParts.some((part) => evaluateWorkflowExpressionText(part, context));
-    }
-    const andParts = splitWorkflowExpressionOperator(rendered, '&&');
-    if (andParts.length > 1) {
-        return andParts.every((part) => evaluateWorkflowExpressionText(part, context));
-    }
-    const match = rendered.match(/^(.+?)\s*(==|!=|>=|<=|>|<)\s*(.+)$/);
-    if (!match) {
-        return isWorkflowTruthy(parseWorkflowExpressionValue(rendered, context));
-    }
-    return compareWorkflowValues(parseWorkflowExpressionValue(match[1] ?? '', context), match[2] ?? '', parseWorkflowExpressionValue(match[3] ?? '', context));
-}
-function evaluateWorkflowExpression(expression, context) {
-    return evaluateWorkflowExpressionText(expression.trim(), context);
-}
-function splitWorkflowSegments(workflowNodes, executionOrder) {
-    const segments = [];
-    let currentDag = [];
-    for (const nodeId of executionOrder) {
-        const node = workflowNodes[nodeId];
-        if (!node) {
-            throw new Error(`Workflow references unknown node "${nodeId}".`);
-        }
-        if (node.control !== undefined) {
-            if (currentDag.length > 0) {
-                segments.push({ type: 'dag', nodeIds: currentDag });
-                currentDag = [];
-            }
-            segments.push({ type: 'control', nodeId });
-        }
-        else {
-            currentDag.push(nodeId);
-        }
-    }
-    if (currentDag.length > 0) {
-        segments.push({ type: 'dag', nodeIds: currentDag });
-    }
-    return segments;
-}
-function findWorkflowSegmentIndex(segments, targetNodeId) {
-    return segments.findIndex((segment) => segment.type === 'control'
-        ? segment.nodeId === targetNodeId
-        : segment.nodeIds.includes(targetNodeId));
-}
-function computeActiveWorkflowNodes(workflowNodes, nodeIds, rootNodeId, includeRootDependencies = true) {
-    const segmentNodeIds = new Set(nodeIds);
-    const downstream = new Set([rootNodeId]);
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const nodeId of nodeIds) {
-            if (downstream.has(nodeId))
-                continue;
-            const needs = getNodeNeeds(workflowNodes[nodeId] ?? {});
-            if (needs.some((dependency) => downstream.has(dependency))) {
-                downstream.add(nodeId);
-                changed = true;
-            }
-        }
-    }
-    const active = new Set(downstream);
-    const includeDependencies = (nodeId) => {
-        const node = workflowNodes[nodeId];
-        if (!node)
-            return;
-        for (const dependency of getNodeNeeds(node)) {
-            if (!segmentNodeIds.has(dependency) || active.has(dependency))
-                continue;
-            active.add(dependency);
-            includeDependencies(dependency);
-        }
-    };
-    if (includeRootDependencies) {
-        for (const nodeId of downstream) {
-            includeDependencies(nodeId);
-        }
-    }
-    return active;
-}
-function createSkippedWorkflowNodeResult(nodeId) {
-    return {
-        id: nodeId,
-        type: 'skipped',
-        status: 'skipped',
-        response: '',
-        output: undefined,
-    };
-}
-function getWorkflowNodeRunCondition(node) {
-    return node.if;
-}
-function getSkippedWorkflowDependencies(node, nodes) {
-    return getNodeNeeds(node).filter((dependency) => nodes[dependency]?.status === 'skipped');
-}
-function getWorkflowNodeSkipReason(node, context) {
-    const skippedDependencies = getSkippedWorkflowDependencies(node, context.nodes);
-    if (skippedDependencies.length > 0) {
-        return `dependency skipped: ${skippedDependencies.join(', ')}`;
-    }
-    const ifExpression = getWorkflowNodeRunCondition(node);
-    if (ifExpression !== undefined && !evaluateWorkflowExpression(ifExpression, context)) {
-        return `if false: ${ifExpression}`;
-    }
-    return undefined;
-}
 function logWorkflowNodeRunning(nodeId, options) {
     if (!options.jsonOutput) {
         console.log(chalk.gray(`Running node ${nodeId}...`));
@@ -2769,7 +2374,14 @@ function recordWorkflowNodeResult(nodeId, node, result, nodes, artifacts) {
         recordNodeArtifact(nodeId, node, result, artifacts);
     }
 }
-async function runWorkflowDagSegment(config, workflowNodes, nodeIds, activeNodeIds, options, workingDir, context, executionContext) {
+function completeWorkflowNodeResult(result, startedAt) {
+    const completedAt = new Date().toISOString();
+    result.startedAt ??= startedAt;
+    result.completedAt ??= completedAt;
+    result.durationMs ??= Math.max(0, new Date(completedAt).getTime() - new Date(startedAt).getTime());
+    return result;
+}
+async function runWorkflowDagSegment(workflowNodes, nodeIds, activeNodeIds, options, context, nodeExecutor) {
     const completed = new Set();
     const segmentNodeIds = new Set(nodeIds);
     if (activeNodeIds) {
@@ -2800,14 +2412,19 @@ async function runWorkflowDagSegment(config, workflowNodes, nodeIds, activeNodeI
             if (!node) {
                 throw new Error(`Workflow references unknown node "${nodeId}".`);
             }
+            const startedAt = new Date().toISOString();
             const skipReason = getWorkflowNodeSkipReason(node, context);
             if (skipReason) {
                 logWorkflowNodeSkipped(nodeId, skipReason, options);
-                return { nodeId, node, result: createSkippedWorkflowNodeResult(nodeId) };
+                return {
+                    nodeId,
+                    node,
+                    result: completeWorkflowNodeResult(createSkippedWorkflowNodeResult(nodeId), startedAt),
+                };
             }
             logWorkflowNodeRunning(nodeId, options);
-            const result = await runSingleWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
-            return { nodeId, node, result };
+            const result = await nodeExecutor.runNode(nodeId, node, context);
+            return { nodeId, node, result: completeWorkflowNodeResult(result, startedAt) };
         }));
         const firstRejection = settled.find((outcome) => outcome.status === 'rejected');
         if (firstRejection) {
@@ -2822,124 +2439,22 @@ async function runWorkflowDagSegment(config, workflowNodes, nodeIds, activeNodeI
         }
     }
 }
-function runControlWorkflowNode(nodeId, node, context) {
-    if (node.control === 'loop') {
-        const expression = node.if;
-        if (!expression) {
-            throw new Error(`Workflow loop node "${nodeId}" must define if.`);
-        }
-        if (!node.target || !node.exit) {
-            throw new Error(`Workflow loop node "${nodeId}" must define target and exit.`);
-        }
-        const rawMaxIterations = node.maxIterations;
-        const renderedMaxIterations = typeof rawMaxIterations === 'string'
-            ? renderTemplate(rawMaxIterations, context).trim()
-            : String(rawMaxIterations ?? '');
-        const configuredMaxIterations = Number.parseInt(renderedMaxIterations, 10);
-        if (renderedMaxIterations === '' ||
-            !Number.isInteger(configuredMaxIterations) ||
-            configuredMaxIterations <= 0) {
-            throw new Error(`Workflow loop node "${nodeId}" must define a positive maxIterations.`);
-        }
-        const maxIterations = configuredMaxIterations;
-        const shouldLoop = evaluateWorkflowExpression(expression, context);
-        const current = context.loop[nodeId] ?? { iteration: 1, maxIterations };
-        let nextNodeId = node.exit;
-        let decision = 'exit';
-        if (shouldLoop) {
-            if (current.iteration >= maxIterations) {
-                if (node.onMaxIterations === 'exit') {
-                    nextNodeId = node.exit;
-                }
-                else {
-                    throw new Error(`Workflow loop node "${nodeId}" reached maxIterations (${maxIterations}).`);
-                }
-            }
-            else {
-                decision = 'loop';
-                nextNodeId = node.target;
-                current.iteration += 1;
-            }
-        }
-        current.maxIterations = maxIterations;
-        current.lastDecision = decision;
-        context.loop[nodeId] = current;
-        return {
-            nextNodeId,
-            result: {
-                id: nodeId,
-                type: 'control',
-                status: 'success',
-                control: node.control,
-                decision,
-                target: nextNodeId,
-                response: decision,
-                output: {
-                    matched: shouldLoop,
-                    target: nextNodeId,
-                    iteration: current.iteration,
-                    maxIterations,
-                },
-            },
-        };
-    }
-    if (node.control === 'switch') {
-        if (!node.value || !node.cases) {
-            throw new Error(`Workflow switch node "${nodeId}" must define value and cases.`);
-        }
-        const value = renderTemplate(node.value, context).trim();
-        const nextNodeId = node.cases[value] ?? node.default;
-        if (!nextNodeId) {
-            throw new Error(`Workflow switch node "${nodeId}" has no case for "${value}" or default.`);
-        }
-        return {
-            nextNodeId,
-            result: {
-                id: nodeId,
-                type: 'control',
-                status: 'success',
-                control: node.control,
-                decision: value,
-                target: nextNodeId,
-                response: value,
-                output: { value, target: nextNodeId },
-            },
-        };
-    }
-    if (node.control === 'end') {
-        return {
-            ended: true,
-            result: {
-                id: nodeId,
-                type: 'control',
-                status: 'success',
-                control: node.control,
-                decision: 'end',
-                response: 'end',
-                output: { ended: true },
-            },
-        };
-    }
-    if (node.control === 'passThrough') {
-        const result = {
-            id: nodeId,
-            type: 'control',
-            control: 'passThrough',
-            target: node.target,
-            decision: 'pass',
-            response: `passed through to ${node.target}`,
-        };
-        return { result, nextNodeId: node.target };
-    }
-    throw new Error(`Unsupported workflow control "${node.control}" in node "${nodeId}".`);
+async function runControlWorkflow(workflowNodes, executionOrder, options, context, nodeExecutor) {
+    await runControlWorkflowFromSegments(workflowNodes, splitWorkflowSegments(workflowNodes, executionOrder), options, context, nodeExecutor);
 }
-async function runControlWorkflow(config, workflowNodes, executionOrder, options, workingDir, context, executionContext) {
-    const segments = splitWorkflowSegments(workflowNodes, executionOrder);
+async function runControlWorkflowFromSegments(workflowNodes, compiledSegments, options, context, nodeExecutor) {
+    const segments = compiledSegments.map((segment) => segment.type === 'control'
+        ? { type: 'control', nodeId: segment.nodeId }
+        : {
+            type: 'dag',
+            nodeIds: [...segment.nodeIds],
+            ...(segment.activeNodeIds ? { activeNodeIds: new Set(segment.activeNodeIds) } : {}),
+        });
     let segmentIndex = 0;
     while (segmentIndex < segments.length) {
         const segment = segments[segmentIndex];
         if (segment.type === 'dag') {
-            await runWorkflowDagSegment(config, workflowNodes, segment.nodeIds, segment.activeNodeIds, options, workingDir, context, executionContext);
+            await runWorkflowDagSegment(workflowNodes, segment.nodeIds, segment.activeNodeIds, options, context, nodeExecutor);
             segmentIndex += 1;
             continue;
         }
@@ -2954,9 +2469,14 @@ async function runControlWorkflow(config, workflowNodes, executionOrder, options
         else {
             logWorkflowNodeRunning(segment.nodeId, options);
         }
-        const { result, nextNodeId, ended } = skipReason
+        const startedAt = new Date().toISOString();
+        const controlResult = skipReason
             ? { result: createSkippedWorkflowNodeResult(segment.nodeId) }
             : runControlWorkflowNode(segment.nodeId, node, context);
+        const { result, nextNodeId, ended } = {
+            ...controlResult,
+            result: completeWorkflowNodeResult(controlResult.result, startedAt),
+        };
         recordWorkflowNodeResult(segment.nodeId, node, result, context.nodes, context.artifacts);
         if (ended) {
             return;
@@ -2987,16 +2507,57 @@ async function runSingleWorkflowNode(config, nodeId, node, options, workingDir,
     if (getWorkflowNodeSkipReason(node, context)) {
         return createSkippedWorkflowNodeResult(nodeId);
     }
-    if (kind === 'agent') {
-        return runAgentWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
-    }
-    if (kind === 'agents') {
-        return runAgentsWorkflowNode(config, nodeId, node, options, workingDir, context);
-    }
-    if (kind === 'control') {
-        throw new Error(`Workflow control node "${nodeId}" cannot run in the static DAG executor.`);
-    }
-    return runActionWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
+    const run = async () => {
+        if (kind === 'agent') {
+            return runAgentWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
+        }
+        if (kind === 'agents') {
+            return runAgentsWorkflowNode(config, nodeId, node, options, workingDir, context);
+        }
+        if (kind === 'control') {
+            throw new Error(`Workflow control node "${nodeId}" cannot run in the static DAG executor.`);
+        }
+        return runActionWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
+    };
+    return isPotentialWorkspaceMutation(node)
+        ? withWorkflowLock(executionContext.locks.workspace, run)
+        : run();
+}
+/**
+ * In-process {@link NodeExecutor} that dispatches a single non-control node
+ * to the existing side-effecting runner functions. Constructed once per
+ * workflow run so git/platform clients and locks are shared across nodes.
+ *
+ * The Temporal executor will provide its own NodeExecutor whose `runNode`
+ * schedules a Temporal activity instead of executing in-process.
+ */
+class LocalNodeExecutor {
+    config;
+    options;
+    workingDir;
+    executionContext;
+    constructor(config, options, workingDir, executionContext) {
+        this.config = config;
+        this.options = options;
+        this.workingDir = workingDir;
+        this.executionContext = executionContext;
+    }
+    async runNode(nodeId, node, context) {
+        return runSingleWorkflowNode(this.config, nodeId, node, this.options, this.workingDir, context, this.executionContext);
+    }
+}
+export async function runWorkflowNodeLocally(config, nodeId, node, options, workingDir, context) {
+    const executionContext = {
+        gitClients: new Map(),
+        platformClients: {},
+        traceCollector: options.trace ? new TraceCollector() : undefined,
+        locks: {
+            exit: createWorkflowLock(),
+            console: createWorkflowLock(),
+            workspace: createWorkflowLock(),
+        },
+    };
+    return runSingleWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
 }
 export async function runWorkflow(config, workflowName, options = {}) {
     const workflow = config.workflows?.[workflowName];
@@ -3004,12 +2565,40 @@ export async function runWorkflow(config, workflowName, options = {}) {
         throw new Error(`Unknown workflow "${workflowName}".`);
     }
     const workflowNodes = getWorkflowNodes(workflowName, workflow);
+    const executionOrder = getWorkflowExecutionOrder(workflowNodes);
+    const executionWaves = getWorkflowExecutionWaves(workflowNodes, executionOrder);
+    return executeWorkflowRun(config, workflowName, workflowNodes, executionOrder, executionWaves, workflow.output, hasWorkflowControlNodes(workflowNodes), options);
+}
+/**
+ * Run a workflow from a previously compiled {@link CompiledWorkflowPlan}.
+ *
+ * The plan supplies the scheduling data (nodes, execution order, waves,
+ * segments, output key) so the caller does not need to reload repo config to
+ * drive execution. `config` is still required because agent/action node
+ * execution needs agent and review configuration that lives outside the
+ * compiled plan.
+ */
+export async function runWorkflowFromCompiledPlan(config, plan, options = {}) {
+    const executionSegments = plan.hasControlNodes ? plan.segments : [];
+    if (plan.hasControlNodes) {
+        const workflowNodes = plan.nodes;
+        const order = plan.executionOrder;
+        return executeWorkflowRun(config, plan.workflowName, workflowNodes, order, plan.waves, plan.output, true, options, executionSegments);
+    }
+    return executeWorkflowRun(config, plan.workflowName, plan.nodes, plan.executionOrder, plan.waves, plan.output, false, options);
+}
+async function executeWorkflowRun(config, workflowName, workflowNodes, executionOrder, executionWaves, workflowOutput, hasControl, options, controlSegments) {
+    const startedAt = new Date().toISOString();
+    const workflow = config.workflows?.[workflowName];
+    if (!workflow) {
+        throw new Error(`Unknown workflow "${workflowName}".`);
+    }
     const workingDir = options.workingDir ?? process.cwd();
     const inputs = await resolveWorkflowInputs(workflow, options, workingDir);
     const nodes = {};
     const artifacts = {};
     const loop = {};
-    const context = { inputs, nodes, artifacts, loop };
+    const context = { startedAt, inputs, nodes, artifacts, loop };
     const executionContext = {
         gitClients: new Map(),
         platformClients: {},
@@ -3017,16 +2606,28 @@ export async function runWorkflow(config, workflowName, options = {}) {
         locks: {
             exit: createWorkflowLock(),
             console: createWorkflowLock(),
+            workspace: createWorkflowLock(),
         },
     };
-    const executionOrder = getWorkflowExecutionOrder(workflowNodes);
-    const executionWaves = getWorkflowExecutionWaves(workflowNodes, executionOrder);
+    const nodeExecutor = new LocalNodeExecutor(config, options, workingDir, executionContext);
     if (!options.jsonOutput) {
         console.log(chalk.gray(`Running workflow ${workflowName}...\n`));
     }
     try {
-        if (hasWorkflowControlNodes(workflowNodes)) {
-            await runControlWorkflow(config, workflowNodes, executionOrder, options, workingDir, context, executionContext);
+        if (hasControl) {
+            if (controlSegments) {
+                const internalSegments = controlSegments.map((segment) => segment.type === 'control'
+                    ? { type: 'control', nodeId: segment.nodeId }
+                    : {
+                        type: 'dag',
+                        nodeIds: segment.nodeIds,
+                        ...(segment.activeNodeIds ? { activeNodeIds: new Set(segment.activeNodeIds) } : {}),
+                    });
+                await runControlWorkflowFromSegments(workflowNodes, internalSegments, options, context, nodeExecutor);
+            }
+            else {
+                await runControlWorkflow(workflowNodes, executionOrder, options, context, nodeExecutor);
+            }
         }
         else {
             for (const wave of executionWaves) {
@@ -3035,14 +2636,19 @@ export async function runWorkflow(config, workflowName, options = {}) {
                     if (!node) {
                         throw new Error(`Workflow references unknown node "${nodeId}".`);
                     }
+                    const startedAt = new Date().toISOString();
                     const skipReason = getWorkflowNodeSkipReason(node, context);
                     if (skipReason) {
                         logWorkflowNodeSkipped(nodeId, skipReason, options);
-                        return { nodeId, node, result: createSkippedWorkflowNodeResult(nodeId) };
+                        return {
+                            nodeId,
+                            node,
+                            result: completeWorkflowNodeResult(createSkippedWorkflowNodeResult(nodeId), startedAt),
+                        };
                     }
                     logWorkflowNodeRunning(nodeId, options);
-                    const result = await runSingleWorkflowNode(config, nodeId, node, options, workingDir, context, executionContext);
-                    return { nodeId, node, result };
+                    const result = await nodeExecutor.runNode(nodeId, node, context);
+                    return { nodeId, node, result: completeWorkflowNodeResult(result, startedAt) };
                 }));
                 const firstRejection = settled.find((outcome) => outcome.status === 'rejected');
                 if (firstRejection) {
@@ -3070,7 +2676,7 @@ export async function runWorkflow(config, workflowName, options = {}) {
     }
     const lastNodeId = executionOrder[executionOrder.length - 1];
     const lastNode = workflowNodes[lastNodeId];
-    const outputKey = workflow.output ?? lastNode.output ?? lastNodeId;
+    const outputKey = workflowOutput ?? lastNode.output ?? lastNodeId;
     const result = {
         timestamp: new Date().toISOString(),
         workflow: workflowName,
@@ -3092,8 +2698,14 @@ export async function runWorkflow(config, workflowName, options = {}) {
     if (options.jsonOutput) {
         console.log(formatWorkflowJson(result));
     }
-    else if (typeof result.output === 'string' && result.output.trim()) {
-        console.log(`\n${result.output}`);
+    else {
+        const wikiSummary = getWikiRunSummary(result.output);
+        if (wikiSummary) {
+            console.log(`\n${formatWikiRunSummaryHuman(wikiSummary)}`);
+        }
+        else if (typeof result.output === 'string' && result.output.trim()) {
+            console.log(`\n${result.output}`);
+        }
     }
     return result;
 }
@@ -3119,6 +2731,7 @@ export function listWorkflows(config, options = {}) {
             source: info.source,
             overridden: info.overridesPackaged,
             description: workflow.description,
+            metadata: workflow.metadata,
         };
     })
         .sort((a, b) => a.name.localeCompare(b.name));
@@ -3171,11 +2784,13 @@ function buildWorkflowDetail(name, workflow, workingDir) {
     };
     const workflowNodes = getWorkflowNodes(name, workflow);
     getWorkflowExecutionOrder(workflowNodes);
+    const graph = buildWorkflowGraph(name, workflow);
     return {
         name,
         source: info.source,
         overridden: info.overridesPackaged,
         description: workflow.description,
+        metadata: workflow.metadata,
         inputs: workflow.inputs ?? {},
         output: workflow.output,
         nodes: Object.entries(workflowNodes).map(([nodeId, node]) => ({
@@ -3192,10 +2807,42 @@ function buildWorkflowDetail(name, workflow, workingDir) {
             output: node.output,
             writes: node.writes,
             json: node.json,
+            permissions: node.permissions,
+            validation: node.validation,
             routes: getWorkflowNodeRoutes(node),
         })),
+        graph,
     };
 }
+export function showWorkflowGraph(config, workflowName, options = {}) {
+    const workflow = config.workflows?.[workflowName];
+    if (!workflow) {
+        throw new Error(`Unknown workflow "${workflowName}".`);
+    }
+    const graph = buildWorkflowGraph(workflowName, workflow);
+    const format = options.format ?? 'text';
+    if (format === 'json') {
+        console.log(JSON.stringify(graph, null, 2));
+    }
+    else if (format === 'mermaid') {
+        console.log(formatWorkflowGraphMermaid(graph));
+    }
+    else {
+        console.log(chalk.bold(`\nWorkflow Graph: ${graph.workflow}\n`));
+        for (const node of graph.nodes) {
+            const outgoing = graph.edges.filter((edge) => edge.source === node.id);
+            const suffix = node.condition ? chalk.yellow(` if ${node.condition}`) : '';
+            console.log(`  ${chalk.white(node.id)} ${chalk.gray(`[${node.kind}]`)}${suffix}`);
+            for (const edge of outgoing) {
+                const edgeLabel = edge.label ? ` ${chalk.gray(`(${edge.label})`)}` : '';
+                const marker = edge.kind === 'control' ? chalk.cyan('~>') : chalk.gray('->');
+                console.log(`    ${marker} ${edge.target}${edgeLabel}`);
+            }
+        }
+        console.log('');
+    }
+    return graph;
+}
 export function showWorkflow(config, workflowName, options = {}) {
     const workflow = config.workflows?.[workflowName];
     if (!workflow) {
@@ -3216,6 +2863,9 @@ export function showWorkflow(config, workflowName, options = {}) {
     if (detail.output) {
         console.log(`  Output: ${detail.output}`);
     }
+    if (detail.metadata) {
+        console.log(`  Metadata: ${JSON.stringify(detail.metadata)}`);
+    }
     console.log(chalk.bold('\nInputs:'));
     const inputEntries = Object.entries(detail.inputs);
     if (inputEntries.length === 0) {
@@ -3246,6 +2896,10 @@ export function showWorkflow(config, workflowName, options = {}) {
             console.log(`    output: ${node.output}`);
         if (node.writes)
             console.log(`    writes: ${node.writes}`);
+        if (node.permissions)
+            console.log(`    permissions: ${JSON.stringify(node.permissions)}`);
+        if (node.validation)
+            console.log(`    validation: ${JSON.stringify(node.validation)}`);
         if (node.input)
             console.log(`    input: ${node.input.split('\n')[0]}`);
         if (node.with && Object.keys(node.with).length > 0) {
@@ -3306,4 +2960,15 @@ export function validateWorkflows(config, workflowName, options = {}) {
     console.log('');
     return results;
 }
+/**
+ * Default in-process {@link WorkflowExecutor}. Delegates to {@link runWorkflow}.
+ *
+ * The Temporal executor will implement the same interface so `drs workflow run`
+ * can dispatch through either backend once `--executor temporal` is added.
+ */
+export class LocalWorkflowExecutor {
+    async run(config, workflowName, options = {}) {
+        return runWorkflow(config, workflowName, options);
+    }
+}
 //# sourceMappingURL=workflow.js.map