akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/workflows/renderer.js

@@ -2,17 +2,17 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Show + indexing renderer for the unified workflow asset (workflow-format-
- * unification). One format now: reads the frontmatter+body document via
- * `parseWorkflow` and projects the validated `WorkflowDocument` down to the
- * public `ShowResponse` shape and into search hints for the indexer,
+ * Show + indexing renderer for peer workflow sources. `.md` and `.yml` both
+ * compile through `compileWorkflowSource` into source IR v1, which is projected
+ * down to the public `ShowResponse` shape and into search hints for the indexer,
  * including a compact per-step orchestration summary (engine/model or an exec
  * unit's argv, `map.over` reference, route table) when the step declares one.
  */
 import { displayRef } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
-import { parseWorkflow } from "./parser.js";
 import { projectExecCore } from "./program/schema.js";
+import { compileWorkflowSource } from "./source-ir/compile.js";
+import { sourceStepInstructions, workflowShellCommand } from "./source-ir/program.js";
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -26,11 +26,11 @@ function deriveName(ctx) {
     const ext = ctx.relPath.lastIndexOf(".");
     return ext > 0 ? ctx.relPath.slice(0, ext) : ctx.relPath;
 }
-function loadDocument(ctx) {
-    const result = parseWorkflow(ctx.content(), { path: ctx.relPath });
+function loadSourceIr(ctx) {
+    const result = compileWorkflowSource(ctx.content(), { path: ctx.relPath, workspaceRoot: ctx.stashRoot });
     if (result.ok)
-        return result.document;
-    const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
+        return result.ir;
+    const summary = result.errors.map((e) => `${e.path}:${e.line} — ${e.message}`).join("\n");
     throw new UsageError(`Workflow has errors:\n${summary}`);
 }
 /**
@@ -40,8 +40,9 @@ function loadDocument(ctx) {
  * a non-empty instructions string).
  */
 function stepInstructions(step) {
-    if (step.instructions)
-        return step.instructions.text;
+    const instructions = sourceStepInstructions(step);
+    if (instructions)
+        return instructions;
     if (step.route) {
         const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
         if (step.route.defaultStepId !== undefined)
@@ -51,10 +52,10 @@ function stepInstructions(step) {
     return "";
 }
 /** Project the `params` block into the flat `WorkflowParameter` list. */
-function projectParameters(document) {
-    if (!document.params)
+function projectParameters(sourceIr) {
+    if (!sourceIr.params)
         return undefined;
-    const parameters = Object.entries(document.params).map(([name, schema]) => {
+    const parameters = Object.entries(sourceIr.params).map(([name, schema]) => {
         const description = schema.description;
         return { name, ...(typeof description === "string" && description !== "" ? { description } : {}) };
     });
@@ -91,8 +92,15 @@ function projectParameters(document) {
  * `instructions` this same projection already carries whole.
  */
 function summarizeStepOrchestration(step, defaults) {
-    const unit = step.unit ?? step.map?.unit;
-    const exec = unit?.exec;
+    const unit = step.unit;
+    const exec = step.exec
+        ? step.exec
+        : step.run !== undefined
+            ? {
+                command: workflowShellCommand(step.shell ?? "sh", step.run),
+                ...(step.workingDirectory ? { cwd: step.workingDirectory } : {}),
+            }
+            : undefined;
     const engine = exec ? undefined : (unit?.engine ?? defaults?.engine);
     const model = exec ? undefined : (unit?.model ?? defaults?.model);
     const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
@@ -126,16 +134,21 @@ function summarizeStepOrchestration(step, defaults) {
     };
     return Object.keys(summary).length > 0 ? summary : undefined;
 }
-function projectStepDefinitions(document) {
-    return document.steps.map((step) => {
-        const orchestration = summarizeStepOrchestration(step, document.defaults);
+function projectStepDefinitions(sourceIr) {
+    const flattened = sourceIr.jobs.flatMap((job) => job.steps.map((step) => ({ jobId: job.id, step })));
+    const counts = new Map();
+    for (const { step } of flattened)
+        counts.set(step.id, (counts.get(step.id) ?? 0) + 1);
+    return flattened.map(({ jobId, step }, sequenceIndex) => {
+        const id = (counts.get(step.id) ?? 0) > 1 ? `${jobId}-${step.id}` : step.id;
+        const orchestration = summarizeStepOrchestration(step, sourceIr.defaults);
         return {
-            id: step.id,
-            // No titles anywhere in the unified format — a step IS its id.
+            id,
+            // No titles in the shared source IR — a step IS its id.
             title: step.id,
             instructions: stepInstructions(step),
-            ...(step.gateRubric?.text.trim() ? { completionCriteria: [step.gateRubric.text] } : {}),
-            sequenceIndex: step.sequenceIndex,
+            ...(step.gate?.rubric?.trim() ? { completionCriteria: [step.gate.rubric] } : {}),
+            sequenceIndex,
             ...(orchestration ? { orchestration } : {}),
         };
     });
@@ -144,26 +157,26 @@ export const workflowMdRenderer = {
     name: "workflow-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
-        const doc = loadDocument(ctx);
+        const sourceIr = loadSourceIr(ctx);
         // WI-8.5b (display flip): the `akm workflow run <ref>` action is DISPLAY
         // output — its spelling follows the D-R5 display rule (`displayRef`). A
         // primary/default-bundle workflow renders the SHORT conceptId
         // (`workflows/<name>`); a named source qualifies it as
         // (`<bundle>//workflows/<name>`).
         const ref = displayRef({ type: "workflow", name, bundleId: ctx.origin }, ctx.defaultBundle);
-        const parameters = projectParameters(doc);
+        const parameters = projectParameters(sourceIr);
         return {
             type: "workflow",
             name,
             path: ctx.absPath,
             action: buildWorkflowAction(ref),
-            ...(doc.preamble ? { content: doc.preamble } : {}),
-            description: doc.description,
-            // No authored title in the unified format — the asset's human name is
+            ...(sourceIr.preamble ? { content: sourceIr.preamble } : {}),
+            description: sourceIr.description,
+            // No authored title in the shared source IR — the asset's human name is
             // its `description`/H1 like any other asset; this is its canonical name.
             workflowTitle: name,
             ...(parameters ? { parameters: parameters.map((p) => p.name), workflowParameters: parameters } : {}),
-            steps: projectStepDefinitions(doc),
+            steps: projectStepDefinitions(sourceIr),
         };
     },
 };

package/dist/workflows/resource-limits.js

@@ -1,6 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { EXECUTION_MAX_TIMEOUT_MS } from "../execution/limits.js";
 export const WORKFLOW_MAX_PLAN_BYTES = 2 * 1024 * 1024;
 export const WORKFLOW_MAX_SOURCE_BYTES = 1024 * 1024;
 export const WORKFLOW_MAX_STEPS = 256;
@@ -33,7 +34,7 @@ export const WORKFLOW_MAX_GATE_LOOPS = 100;
 /** Max retry attempts per unit. */
 export const WORKFLOW_MAX_RETRIES = 100;
 /** Max timeout in milliseconds (setTimeout's 32-bit signed ceiling: 2^31-1, ~24.8 days). */
-export const WORKFLOW_MAX_TIMEOUT_MS = 2 ** 31 - 1;
+export const WORKFLOW_MAX_TIMEOUT_MS = EXECUTION_MAX_TIMEOUT_MS;
 /** Engine names: lowercase dash-separated runs of letters/digits, starting with a letter. */
 export const WORKFLOW_ENGINE_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 export const WORKFLOW_MAX_ENGINE_NAME_LENGTH = 63;
@@ -51,10 +52,8 @@ export const WORKFLOW_MAX_EXEC_CWD_LENGTH = 1024;
 /**
  * Max entries in an exec unit's `pass_env:` list.
  *
- * `pass_env` is the "one or two more toolchain variables" escape hatch, not a
- * second way to spell `inherit_env:` — a workflow reaching for more than this
- * many names wants full inheritance and should say so where a reviewer can see
- * it.
+ * `pass_env` is bounded; use explicit named `env:` bindings for a larger set.
+ * New v4 starts do not offer whole-process inheritance.
  */
 export const WORKFLOW_MAX_EXEC_PASS_ENV = 32;
 /**

package/dist/workflows/runtime/agent-identity.js

@@ -2,13 +2,13 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Resolve the agent harness + session identity for the current process.
+ * Resolve the invoking harness/session identity for the current process.
  *
- * This is the first concrete slice of #501 / #506: capturing *who* is driving a
- * workflow run so a future (separately-approved) monitor can correlate runs
- * with session activity. It deliberately does NOT start any background thread,
- * timer, or daemon — it only reads identity that the surrounding agent harness
- * already exposes via the environment.
+ * This is the first concrete slice of #501 / #506: capturing the invoking
+ * harness/session identity so a future (separately-approved) monitor can
+ * correlate runs with session activity. It deliberately does NOT start any
+ * background thread, timer, or daemon — it only reads identity that the
+ * surrounding agent harness already exposes via the environment.
  *
  * Resolution is best-effort and environment-driven:
  *   - harness:    AKM_AGENT_HARNESS, else inferred from a harness session-id
@@ -30,7 +30,7 @@
  *
  * @module workflows/agent-identity
  */
-import { denormalizeRuntimeIdentity, HARNESS_REGISTRY } from "../../integrations/harnesses/index.js";
+import { HARNESS_REGISTRY } from "../../integrations/harnesses/index.js";
 /**
  * Derive a marker table from one registry env-var field, ordered by canonical
  * id. The sort keeps the pre-derivation precedence byte-identical ('claude'
@@ -67,15 +67,13 @@ export function resolveAgentIdentity(env = process.env) {
     if (!harness) {
         // Infer the harness from a harness-specific *session* env var first
         // (registry `identityEnv` markers). A concrete session id is the
-        // strongest evidence of the immediate driver, so it outranks any
+        // strongest evidence of the invoking harness/session context, so it
+        // outranks any
         // presence flag — e.g. opencode launched inside a codex sandbox
         // (OPENCODE_SESSION_ID + CODEX_SANDBOX) attributes to opencode.
         for (const marker of SESSION_MARKERS) {
             if (firstNonEmpty(env, marker.envKeys)) {
-                // Report the harness's RUNTIME identity (e.g. canonical 'claude' →
-                // 'claude-code') via the registry's #562 bridge so the persisted
-                // runtime string can't drift.
-                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                harness = marker.harnessId;
                 break;
             }
         }
@@ -87,7 +85,7 @@ export function resolveAgentIdentity(env = process.env) {
         // but they carry no session id, so sessionId stays null below.
         for (const marker of PRESENCE_MARKERS) {
             if (firstNonEmpty(env, marker.envKeys)) {
-                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                harness = marker.harnessId;
                 break;
             }
         }

package/dist/workflows/runtime/plan-classifier.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { UsageError } from "../../core/errors.js";
 import { decodeCanonicalPlan } from "../ir/plan-hash.js";
-import { WORKFLOW_IR_VERSION } from "../ir/schema.js";
+import { WORKFLOW_IR_V4_VERSION } from "../ir/schema-v4.js";
 /** Validate that a live run carries exactly the current frozen-plan format. */
 export function classifyWorkflowRunPlan(row) {
     const runId = row.id ?? "(unknown)";
@@ -16,31 +16,31 @@ export function classifyWorkflowRunPlan(row) {
     }
     if (row.plan_ir_version !== null &&
         row.plan_ir_version !== undefined &&
-        row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+        row.plan_ir_version !== WORKFLOW_IR_V4_VERSION) {
         return {
             support: "unsupported-version",
             irVersion: row.plan_ir_version,
-            error: `Workflow run ${runId} uses unsupported workflow IR version ${row.plan_ir_version}; this runtime requires version ${WORKFLOW_IR_VERSION}.`,
+            error: `Workflow run ${runId} uses unsupported workflow IR version ${row.plan_ir_version}; this runtime supports only workflow IR version 4. Start a new run from the authored workflow.`,
         };
     }
-    if (row.plan_ir_version !== WORKFLOW_IR_VERSION) {
+    if (row.plan_ir_version !== WORKFLOW_IR_V4_VERSION) {
         return {
             support: "corrupt-plan",
             irVersion: null,
-            error: `Workflow run ${runId} does not declare workflow IR version ${WORKFLOW_IR_VERSION}.`,
+            error: `Workflow run ${runId} does not declare a supported workflow IR version.`,
         };
     }
     try {
         return {
             support: "supported",
-            irVersion: WORKFLOW_IR_VERSION,
-            plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash),
+            irVersion: row.plan_ir_version,
+            plan: decodeCanonicalPlan(runId, row.plan_json, row.plan_hash, row.plan_ir_version),
         };
     }
     catch (cause) {
         return {
             support: "corrupt-plan",
-            irVersion: WORKFLOW_IR_VERSION,
+            irVersion: row.plan_ir_version,
             error: cause instanceof Error ? cause.message : String(cause),
         };
     }

package/dist/workflows/runtime/runs.js

@@ -13,10 +13,9 @@ import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
 import { frozenSummaryJudge } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
 import { collectWorkflowWarnings } from "../ir/compile.js";
-import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
+import { compileResolveFreezeWorkflowV4 } from "../ir/freeze-v4.js";
 import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
-import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
 import { clip, utf8Bytes, WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS, WORKFLOW_MAX_EVIDENCE_JSON_BYTES, WORKFLOW_UNIT_DIAGNOSTIC_CLIP, } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
@@ -33,7 +32,7 @@ const IR_RUNTIME_KINDS = { llm: true, agent: true, sdk: true, exec: true };
 function runtimeKindOf(runner) {
     return runner !== null && Object.hasOwn(IR_RUNTIME_KINDS, runner) ? runner : null;
 }
-function toUnitDiagnostic(row, stale, plannedEngine) {
+function toUnitDiagnostic(row, stale) {
     let diagnostic = null;
     if (row.result_json !== null) {
         // `result_json` is a JSON-encoded value: a bare JSON string for a free-text
@@ -69,7 +68,7 @@ function toUnitDiagnostic(row, stale, plannedEngine) {
         claimExpiresAt: row.claim_expires_at,
         engine: row.engine ?? null,
         runtimeKind: runtimeKindOf(row.runner),
-        platform: plannedEngine?.kind === "agent" ? plannedEngine.platform : null,
+        platform: null,
     };
 }
 export async function startWorkflowRun(ref, params = {}, options) {
@@ -78,8 +77,8 @@ export async function startWorkflowRun(ref, params = {}, options) {
     // persist it on the run row in the same transaction as the insert. Every
     // later invocation executes this snapshot — the asset file is never re-read
     // for an in-flight run; re-planning is an explicit new run.
-    const frozen = compileResolveFreezeWorkflow(asset, loadConfig());
-    const plan = decodeWorkflowPlanV3(frozen.plan);
+    const frozen = await compileResolveFreezeWorkflowV4(asset, loadConfig());
+    const plan = frozen.plan;
     if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
         throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
     }
@@ -89,7 +88,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
     // Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
     // as `warn()` lines at start (stderr, consistent with the repo's other
     // author-facing warnings) without blocking the run.
-    for (const w of collectWorkflowWarnings(asset.document)) {
+    for (const w of collectWorkflowWarnings(asset.sourceIr)) {
         warn(`workflow run: ${asset.path}:${w.line} — ${w.message}`);
     }
     // Reviewer #12: validate supplied parameters against the frozen param
@@ -111,7 +110,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
         const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = plan.steps[0]?.stepId ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref, asset.adapterId);
-        // Capture the agent harness + session driving this run. Explicit options
+        // Capture the invoking harness/session identity for this run. Explicit options
         // win; otherwise fall back to best-effort environment detection. This is
         // identity-only — no background thread or timer is started here.
         const detected = resolveAgentIdentity();
@@ -127,15 +126,10 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // per the workflow-agent check-in ADR) so a stalled run can be
         // re-targeted with a `continue` directive. The agent harness + session id
         // are already resolved above (agentHarness/agentSessionId, from #501).
-        repo.immediateTransaction(() => {
-            if (!options?.force) {
-                const existing = repo.findActiveRunForScope(workflowRefs, scopeKey);
-                if (existing) {
-                    throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
-                        `Use 'akm workflow run ${asset.ref}' to resume it or 'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
-                }
-            }
-            repo.insertRun({
+        repo.publishWorkflowRunV4({
+            workflowRefs,
+            ...(options?.force ? { force: true } : {}),
+            run: {
                 id: runId,
                 workflowRef: asset.ref,
                 scopeKey,
@@ -148,17 +142,18 @@ export async function startWorkflowRun(ref, params = {}, options) {
                 agentHarness,
                 agentSessionId,
                 checkinArmedAt: now,
-            });
-            repo.insertSteps(frozenStepRows(plan).map((step) => ({
+            },
+            steps: frozenStepRows(plan).map((step) => ({
                 runId,
                 stepId: step.stepId,
                 stepTitle: step.stepTitle,
                 instructions: step.instructions,
                 completionJson: step.completionJson,
                 sequenceIndex: step.sequenceIndex,
-            })));
-            // Same transaction as the insert: a run row never exists without its frozen plan.
-            repo.setRunPlan(runId, planJson, planHash, WORKFLOW_IR_VERSION);
+            })),
+            planJson,
+            planHash,
+            revalidateSources: () => frozen.sourceCollector.revalidate(),
         });
         const result = await getWorkflowStatus(runId);
         // #13: params are declared non-secret (they are copied verbatim into every
@@ -174,16 +169,6 @@ export async function startWorkflowRun(ref, params = {}, options) {
         // re-announces a decision it did not make.
         if (frozen.engineAnnouncement)
             result.warnings = [...(result.warnings ?? []), frozen.engineAnnouncement];
-        // 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
-        // comes verbatim from the workflow asset's frontmatter and is therefore
-        // attacker-influenceable). Keeping raw titles out of the events stream
-        // shrinks the injectable footprint for any consumer that re-surfaces events
-        // into agent context.
-        appendEvent({
-            eventType: "workflow_started",
-            ref: asset.ref,
-            metadata: { runId: result.run.id, status: result.run.status },
-        });
         return result;
     });
 }
@@ -201,9 +186,7 @@ export async function getWorkflowStatus(runId, opts) {
             // injected for deterministic tests) so a unit left `running` by a process
             // that died surfaces as stale here, not just as raw `running`.
             const staleById = new Map(evaluateStaleUnits(rows, opts.now ?? Date.now()).map((u) => [u.unitId, u]));
-            const classified = classifyWorkflowRunPlan(run);
-            const engines = classified.support === "supported" ? classified.plan.execution?.engines : undefined;
-            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id), row.engine ? engines?.[row.engine] : undefined));
+            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id)));
         }
         return detail;
     });
@@ -296,9 +279,9 @@ function projectNextResult(run, steps) {
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
-        const plan = requireExecutableWorkflowPlan(run);
+        const storedPlan = requireExecutableWorkflowPlan(run);
         const steps = readWorkflowRunSteps(repo, run.id);
-        assertWorkflowSpineMatchesPlan(plan, run, steps);
+        assertWorkflowSpineMatchesPlan(storedPlan, run, steps);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
@@ -473,9 +456,9 @@ export async function completeWorkflowStep(input) {
     // the write transaction — a slow/hung LLM must never hold a db write lock.
     const preflight = await withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, input.runId);
-        const plan = requireExecutableWorkflowPlan(run);
+        const storedPlan = requireExecutableWorkflowPlan(run);
         const steps = readWorkflowRunSteps(repo, run.id);
-        assertWorkflowSpineMatchesPlan(plan, run, steps);
+        assertWorkflowSpineMatchesPlan(storedPlan, run, steps);
         if (run.status !== "active") {
             throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
         }
@@ -490,10 +473,10 @@ export async function completeWorkflowStep(input) {
         if (run.current_step_id !== existing.step_id) {
             throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
         }
-        const stepPlan = plan.steps.find((step) => step.stepId === input.stepId);
+        const stepPlan = storedPlan.steps.find((step) => step.stepId === input.stepId);
         if (!stepPlan)
             throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
-        return { existing, plan, stepPlan };
+        return { existing, plan: storedPlan, stepPlan };
     });
     const summary = input.summary?.trim();
     // #506: completing a step requires a summary of the work done.
@@ -510,7 +493,7 @@ export async function completeWorkflowStep(input) {
             ? // Manual completion journals no gate row, so there is no `<stepId>.gate:l<loop>`
                 // identity to agree with — but the dispatch still names the REAL run and
                 // step (frozen-judge falls back to the gate node id for the unit id).
-                frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal, undefined, {
+                frozenSummaryJudge(preflight.stepPlan.gate.frozenJudge, input.signal, undefined, {
                     runId: input.runId,
                     stepId: input.stepId,
                 })
@@ -750,7 +733,8 @@ function toWorkflowRunSummary(run) {
         planIrVersion: plan.irVersion,
         executionSupport: plan.support,
         // Surface the engine lease (holder id + expiry — never workflow-authored
-        // content) so `workflow run`/`status` show who is driving the run.
+        // content) so `workflow run`/`status` show which native execution
+        // invocation currently holds the run lease.
         ...(run.engine_lease_holder && run.engine_lease_until
             ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
             : {}),