pi-subagents 0.58.0 → 0.59.0

package/src/workflows/scripted-workflow.ts

@@ -2,6 +2,10 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
 import { Worker } from "node:worker_threads";
+import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../runs/shared/parallel-utils.ts";
+import { HOST_STEP_MAX_COUNT } from "../runs/shared/host-step-status.ts";
+import type { HostStepNodeV1, SingleResult } from "../shared/types.ts";
+import { normalizeWorkflowHostCommandParams, type WorkflowHostCommandParams, type WorkflowHostCommandResult } from "./host-command.ts";
 
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const requireFromPackage = createRequire(import.meta.url);
@@ -252,11 +256,11 @@ function hostCall(method, args, observation) {
     : promise;
 }
 
-function runHostCall(key, params, collectFailure, batch) {
+function runHostCall(key, params, collectFailure, batch, generatedLaneKey) {
   const callId = ++nextCallId;
   const promise = new Promise((resolve, reject) => {
     pending.set(callId, { resolve, reject });
-    parentPort.postMessage({ type: "call", callId, method: "run", args: { key, params, ...(collectFailure ? { collectFailure: true } : {}), ...(batch ? { batch } : {}) } });
+    parentPort.postMessage({ type: "call", callId, method: "run", args: { key, params, ...(collectFailure ? { collectFailure: true } : {}), ...(batch ? { batch } : {}), ...(generatedLaneKey ? { generatedLaneKey } : {}) } });
   });
   return { key, callId, promise };
 }
@@ -269,6 +273,15 @@ function isArrayIndexProperty(prop) {
 
 const runsAllResultTargets = new WeakMap();
 
+const MAX_LANES = 32;
+const MAX_LANE_STAGES = 16;
+const MAX_LANE_STAGE_COUNT = 64;
+const MAX_LANE_SPEC_BYTES = 64 * 1024;
+const MAX_LANE_TASK_BYTES = 1024 * 1024;
+const MAX_LANE_PATH_BYTES = 32 * 1024;
+const MAX_LANE_BOARD_TEXT_BYTES = 256;
+const LANE_PATH_FIELDS = new Set(["cwd", "output", "sessionDir"]);
+
 function runsAllKeyAccessError(prop) {
   return new Error("Cannot read runs.all result property '" + prop + "'. runs.all resolves to an ordered array, not a key map. Use results[0], array destructuring, or results.map((result) => result.output), not results." + prop + ".");
 }
@@ -288,6 +301,224 @@ function wrapRunsAllResults(results, keys) {
   return proxy;
 }
 
+function laneByteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function laneBoardText(value) {
+  if (typeof value !== "string" || !value) return undefined;
+  if (laneByteLength(value) <= MAX_LANE_BOARD_TEXT_BYTES) return value;
+  const bytes = new TextEncoder().encode(value).subarray(0, MAX_LANE_BOARD_TEXT_BYTES - 3);
+  return new TextDecoder().decode(bytes) + "...";
+}
+
+function laneBoardPath(value) {
+  if (typeof value !== "string" || !value || laneByteLength(value) > MAX_LANE_BOARD_TEXT_BYTES) return undefined;
+  return value;
+}
+
+function validateLaneStageBounds(params, label) {
+  if (typeof params.task === "string" && laneByteLength(params.task) > MAX_LANE_TASK_BYTES) throw new Error(label + " task exceeds 1 MiB when UTF-8 encoded.");
+  for (const field of LANE_PATH_FIELDS) if (typeof params[field] === "string" && laneByteLength(params[field]) > MAX_LANE_PATH_BYTES) throw new Error(label + " " + field + " exceeds 32 KiB when UTF-8 encoded.");
+}
+
+function validateLaneKey(value, owner) {
+  if (typeof value !== "string" || !runKeyPattern.test(value)) throw new Error(owner + " key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+  return value;
+}
+
+function laneStageParams(stage, previous) {
+  const resume = stage.resume;
+  const params = { ...stage.params };
+  if (resume !== "previous") return params;
+  if (!previous || typeof previous.runId !== "string" || !previous.runId.trim()) return undefined;
+  return { ...params, resume: previous.runId.trim() };
+}
+
+function laneStageVerdict(result) {
+  const structured = result && typeof result === "object" && !Array.isArray(result) ? result.structuredOutput : undefined;
+  const verdict = structured && typeof structured === "object" && !Array.isArray(structured) ? structured.verdict : undefined;
+  return typeof verdict === "string" && verdict.trim() ? laneBoardText(verdict.trim()) : undefined;
+}
+
+function laneStageIsBlocked(result) {
+  const structured = result && typeof result === "object" && !Array.isArray(result) ? result.structuredOutput : undefined;
+  return structured && typeof structured === "object" && !Array.isArray(structured) && structured.verdict === "blocked";
+}
+
+function laneStageRecord(stageKey, child, forcedState) {
+  const result = child && typeof child === "object" && !Array.isArray(child) ? child : undefined;
+  const ok = result?.ok === true;
+  const verdict = laneStageVerdict(result);
+  const blocked = laneStageIsBlocked(result);
+  const state = forcedState ?? (result?.stopped ? "stopped" : result?.detached ? "detached" : ok ? blocked ? "blocked" : "completed" : "failed");
+  const error = state !== "completed"
+    ? state === "blocked" && blocked
+      ? "Stage returned a blocked verdict."
+      : typeof result?.error === "string"
+        ? result.error
+        : typeof result?.output === "string"
+          ? result.output
+          : "Stage did not complete successfully."
+    : undefined;
+  return {
+    key: stageKey,
+    ...(typeof result?.runId === "string" && result.runId.trim() ? { runId: laneBoardText(result.runId.trim()) } : {}),
+    ...(result ? { ok } : {}),
+    state,
+    ...(typeof result?.outputReference === "string" ? (laneBoardPath(result.outputReference) ? { outputReference: laneBoardPath(result.outputReference) } : {}) : {}),
+    ...(verdict ? { verdict } : {}),
+    ...(error ? { error: laneBoardText(error) } : {}),
+  };
+}
+
+function laneFailure(stageKey, error) {
+  const text = error instanceof Error ? error.message : String(error);
+  return { key: stageKey, ok: false, output: text, error: text, artifactPaths: [] };
+}
+
+function runCollected(key, params, observe, generatedLaneKey) {
+  validateRunCall(key, params, "runs.lanes stage", runFingerprints);
+  const launched = runHostCall(key, params, true, undefined, generatedLaneKey);
+  observe([{ key, operation: "run", callId: launched.callId }]);
+  return launched.promise.then(decorateWorkflowChildResult);
+}
+
+function validateLaneSpecs(laneSpecs) {
+  if (!Array.isArray(laneSpecs)) throw new Error("runs.lanes(lanes) requires an array.");
+  if (laneSpecs.length === 0) throw new Error("runs.lanes(lanes) requires at least one lane.");
+  if (laneSpecs.length > MAX_LANES) throw new Error("runs.lanes supports at most " + MAX_LANES + " lanes.");
+  assertJsonValue(laneSpecs, "runs.lanes lanes");
+  if (laneByteLength(stableRunJson(laneSpecs)) > MAX_LANE_SPEC_BYTES) throw new Error("runs.lanes canonical JSON exceeds 64 KiB.");
+  const generatedKeys = new Set();
+  const validationFingerprints = new Map();
+  let stageCount = 0;
+  const normalized = [];
+  for (let laneIndex = 0; laneIndex < laneSpecs.length; laneIndex++) {
+    const lane = laneSpecs[laneIndex];
+    const laneLabel = "runs.lanes lane " + laneIndex;
+    if (!lane || typeof lane !== "object" || Array.isArray(lane)) throw new Error(laneLabel + " must be an object.");
+    const laneFields = Object.keys(lane);
+    if (laneFields.some((field) => field !== "key" && field !== "stages")) throw new Error(laneLabel + " contains unsupported fields.");
+    const laneKey = validateLaneKey(lane.key, laneLabel);
+    if (!Array.isArray(lane.stages) || lane.stages.length === 0) throw new Error(laneLabel + " stages must contain at least one stage.");
+    if (lane.stages.length > MAX_LANE_STAGES) throw new Error(laneLabel + " supports at most " + MAX_LANE_STAGES + " stages.");
+    const stageKeys = new Set();
+    const stages = [];
+    for (let stageIndex = 0; stageIndex < lane.stages.length; stageIndex++) {
+      stageCount++;
+      if (stageCount > MAX_LANE_STAGE_COUNT) throw new Error("runs.lanes supports at most " + MAX_LANE_STAGE_COUNT + " total stages.");
+      const stage = lane.stages[stageIndex];
+      const stageLabel = laneLabel + " stage " + stageIndex;
+      if (!stage || typeof stage !== "object" || Array.isArray(stage)) throw new Error(stageLabel + " must be an object.");
+      const stageKey = validateLaneKey(stage.key, stageLabel);
+      if (stageKeys.has(stageKey)) throw new Error(laneLabel + " contains duplicate stage key '" + stageKey + "'.");
+      stageKeys.add(stageKey);
+      const generatedKey = laneKey + "." + stageKey;
+      validateLaneKey(generatedKey, stageLabel + " generated");
+      if (generatedKeys.has(generatedKey)) throw new Error("runs.lanes generated child key '" + generatedKey + "' is duplicated.");
+      generatedKeys.add(generatedKey);
+      const resume = stage.resume;
+      if (resume !== undefined && resume !== "previous") {
+        if (stageIndex === 0 && typeof resume === "string") {
+          throw new Error(stageLabel + " cannot resume a retained run id in runs.lanes; use runs.run(key, { resume: id }) outside lanes, or start the lane with an agent stage and use resume: \"previous\" later.");
+        }
+        throw new Error(stageLabel + " resume must be 'previous'.");
+      }
+      if (stageIndex === 0 && resume === "previous") throw new Error(stageLabel + " cannot resume previous without a predecessor stage.");
+      const { key: _stageKey, resume: _resume, ...params } = stage;
+      const validationParams = resume === "previous" ? { ...params, resume: "retained-run-placeholder" } : params;
+      validateLaneStageBounds(validationParams, stageLabel);
+      validateRunCall(generatedKey, validationParams, stageLabel, validationFingerprints);
+      const existingFingerprint = runFingerprints.get(generatedKey);
+      if (existingFingerprint !== undefined && (resume === "previous" || existingFingerprint !== stableRunJson(params))) {
+        throw new Error("runs.lanes generated child key '" + generatedKey + "' is already used with incompatible launch params.");
+      }
+      stages.push({ key: stageKey, generatedKey, resume, params });
+    }
+    normalized.push({ key: laneKey, stages });
+  }
+  return normalized;
+}
+
+function runLane(lane, firstResult, observe) {
+  const records = [];
+  const appendSkipped = (start) => {
+    for (let index = start; index < lane.stages.length; index++) records.push({ key: lane.stages[index].key, state: "skipped" });
+  };
+  const finish = (state, failedStage) => ({ key: lane.key, state, ...(failedStage ? { failedStage } : {}), stages: records });
+  const visit = (index, previous) => {
+    if (index >= lane.stages.length) return Promise.resolve(finish("complete"));
+    const stage = lane.stages[index];
+    if (index === 0) {
+      const record = laneStageRecord(stage.key, previous);
+      records.push(record);
+      if (record.state !== "completed") {
+        appendSkipped(index + 1);
+        return Promise.resolve(finish("blocked", stage.key));
+      }
+      return visit(index + 1, previous);
+    }
+    if (stage.resume === "previous" && (!previous || typeof previous.runId !== "string" || !previous.runId.trim())) {
+      records.push({ key: stage.key, state: "blocked", error: "Previous stage did not return a retained run id." });
+      appendSkipped(index + 1);
+      return Promise.resolve(finish("blocked", stage.key));
+    }
+    if (!previous || previous.ok !== true || laneStageIsBlocked(previous)) {
+      records.push({ key: stage.key, state: "blocked", error: "Previous stage did not complete successfully." });
+      appendSkipped(index + 1);
+      return Promise.resolve(finish("blocked", stage.key));
+    }
+    const params = laneStageParams(stage, previous);
+    if (!params) {
+      records.push({ key: stage.key, state: "blocked", error: "Previous stage did not return a retained run id." });
+      appendSkipped(index + 1);
+      return Promise.resolve(finish("blocked", stage.key));
+    }
+    let launched;
+    try {
+      launched = runCollected(stage.generatedKey, params, observe, lane.key);
+    } catch (error) {
+      const failed = laneFailure(stage.generatedKey, error);
+      records.push(laneStageRecord(stage.key, failed));
+      appendSkipped(index + 1);
+      return Promise.resolve(finish("blocked", stage.key));
+    }
+    return launched.then((result) => {
+      const record = laneStageRecord(stage.key, result);
+      records.push(record);
+      if (record.state === "completed") return visit(index + 1, result);
+      appendSkipped(index + 1);
+      return finish("blocked", stage.key);
+    }, (error) => {
+      const failed = laneFailure(stage.generatedKey, error);
+      records.push(laneStageRecord(stage.key, failed));
+      appendSkipped(index + 1);
+      return finish("blocked", stage.key);
+    });
+  };
+  return visit(0, firstResult);
+}
+
+function runLanes(laneSpecs) {
+  const lanes = validateLaneSpecs(laneSpecs);
+  const firstItems = lanes.map((lane) => {
+    const first = lane.stages[0];
+    return { key: first.generatedKey, ...first.params };
+  });
+  // Share the runs.all batch launcher while allowing each lane to advance independently.
+  const firstBatch = launchRunsAll(firstItems, lanes.map((lane) => lane.key));
+  const firstResults = firstBatch.launched.map(({ promise }) => promise.then(decorateWorkflowChildResult));
+  let trackedAggregate;
+  const observe = (observations) => trackRunObservation(observations, trackedAggregate);
+  const laneAggregate = Promise.all(lanes.map((lane, index) => firstResults[index].then(
+    (result) => runLane(lane, result, observe),
+    (error) => runLane(lane, laneFailure(lane.stages[0].generatedKey, error), observe),
+  )));
+  trackedAggregate = trackRunObservation(firstBatch.launched.map(({ key, callId }) => ({ key, operation: "run", callId })), laneAggregate);
+  return trackedAggregate;
+}
+
 function formatRef(result) {
   if (!result || typeof result !== "object") throw new Error("runs.ref(result) requires a run result object.");
   const parts = ["run " + (result.key || "unknown")];
@@ -332,8 +563,28 @@ function validateExtensionBindings(value, label) {
   if (new TextEncoder().encode(stableRunJson(value)).byteLength > 16384) throw new Error(label + " extensionBindings canonical JSON exceeds 16384 bytes.");
 }
 
+function validateLaneMetadata(value, label, workflowKey) {
+  if (value === undefined) return;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(label + " must be a plain JSON object.");
+  const fields = Object.keys(value);
+  const allowed = ["version", "key", "mode", "sourceRef", "claims", "outputPaths"];
+  const unknown = fields.filter((field) => !allowed.includes(field));
+  if (unknown.length > 0) throw new Error(label + " has unsupported fields: " + unknown.join(", ") + ".");
+  if (value.version !== 1) throw new Error(label + ".version must be 1.");
+  if (typeof value.key !== "string" || !value.key.trim() || !runKeyPattern.test(value.key.trim())) throw new Error(label + ".key is invalid.");
+  if (workflowKey !== undefined && value.key.trim() !== workflowKey) throw new Error(label + ".key must match workflow key '" + workflowKey + "'.");
+  if (value.mode !== undefined && !["mutation", "review", "scout", "gate"].includes(value.mode)) throw new Error(label + ".mode is invalid.");
+  const bounded = (entry, maxBytes) => typeof entry === "string" && entry.trim() && new TextEncoder().encode(entry.trim()).byteLength <= maxBytes && !/[\r\n\u0000]/.test(entry);
+  if (value.sourceRef !== undefined && !bounded(value.sourceRef, 128)) throw new Error(label + ".sourceRef is invalid.");
+  for (const [name, maxItems, maxLength] of [["claims", 20, 160], ["outputPaths", 10, 256]]) {
+    if (value[name] === undefined) continue;
+    if (!Array.isArray(value[name]) || value[name].length > maxItems || value[name].some((entry) => !bounded(entry, maxLength))) throw new Error(label + "." + name + " is invalid.");
+  }
+}
+
 function validateRunCall(key, params, label, fingerprints) {
   if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error(label + " has an invalid key.");
+  if (hostKeys.has(key)) throw new Error("Workflow key '" + key + "' is already used by runs.host.");
   if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
   if (Object.prototype.hasOwnProperty.call(params, "action") || Object.prototype.hasOwnProperty.call(params, "workflowScript") || Object.prototype.hasOwnProperty.call(params, "tasks") || Object.prototype.hasOwnProperty.call(params, "chain") || Object.prototype.hasOwnProperty.call(params, "parallel") || Object.prototype.hasOwnProperty.call(params, "concurrency") || Object.prototype.hasOwnProperty.call(params, "chainDir")) {
     const hint = label === "runs.run" ? "; use runs.all(...) and JavaScript control flow for orchestration." : ".";
@@ -341,6 +592,7 @@ function validateRunCall(key, params, label, fingerprints) {
   }
   if (Object.prototype.hasOwnProperty.call(params, "clarify")) throw new Error(label + " does not support clarify UI.");
   if (params.worktree !== undefined && typeof params.worktree !== "boolean") throw new Error(label + " worktree must be true or false.");
+  validateLaneMetadata(params.lane, label + " lane", key);
   if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) throw new Error(label + " gate must be a non-empty command string.");
   if (params.gate !== undefined && params.acceptance !== undefined) throw new Error(label + " gate cannot be combined with acceptance; use one gate command or acceptance.verify.");
   if (params.gate !== undefined && params.resume !== undefined) throw new Error(label + " gate is not supported with retained resume.");
@@ -365,6 +617,44 @@ function validateRunCall(key, params, label, fingerprints) {
   fingerprints.set(key, fingerprint);
 }
 
+const hostKeys = new Set();
+
+function validateHostCommand(key, params) {
+  validateLaneKey(key, "runs.host");
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error("runs.host('" + key + "') params must be an object.");
+  const allowed = new Set(["kind", "command", "timeoutMs", "output", "role", "provider"]);
+  const unknown = Object.keys(params).filter((field) => !allowed.has(field));
+  if (unknown.length) throw new Error("runs.host('" + key + "') params have unsupported fields: " + unknown.join(", ") + ".");
+  if (params.kind !== "command") throw new Error("runs.host('" + key + "') kind must be 'command'.");
+  if (typeof params.command !== "string" || !params.command.trim() || params.command.includes("\u0000") || new TextEncoder().encode(params.command.trim()).byteLength > 16384) throw new Error("runs.host('" + key + "') command must be a non-empty string of at most 16384 bytes without NUL.");
+  if (!Number.isInteger(params.timeoutMs) || params.timeoutMs < 1 || params.timeoutMs > 86400000) throw new Error("runs.host('" + key + "') timeoutMs must be an integer from 1 to 86400000.");
+  if (params.output !== undefined && (typeof params.output !== "string" || !params.output.trim() || /^[/\\]|(?:^|[/\\])\.\.(?:[/\\]|$)/.test(params.output) || /[\u0000-\u001f\u007f]/.test(params.output) || new TextEncoder().encode(params.output.trim()).byteLength > 240)) throw new Error("runs.host('" + key + "') output must be a bounded relative path without traversal or control characters.");
+  if (params.role !== undefined && params.role !== "ci" && params.role !== "gate") throw new Error("runs.host('" + key + "') role must be 'ci' or 'gate'.");
+  if (params.provider !== undefined && (typeof params.provider !== "string" || !params.provider.trim() || /[\r\n\u0000]/.test(params.provider) || new TextEncoder().encode(params.provider.trim()).byteLength > 64)) throw new Error("runs.host('" + key + "') provider must be a non-empty single-line string of at most 64 bytes.");
+  assertJsonValue(params, "runs.host('" + key + "') params");
+  if (hostKeys.has(key) || runFingerprints.has(key)) throw new Error("Workflow key '" + key + "' is already in use.");
+  if (hostKeys.size >= 32) throw new Error("workflowScript supports at most 32 runs.host calls.");
+  hostKeys.add(key);
+}
+
+function launchRunsAll(items, generatedLaneKeys) {
+  if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
+  const fingerprints = new Map(runFingerprints);
+  const calls = [];
+  for (let index = 0; index < items.length; index++) {
+    if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("runs.all items must not contain sparse entries.");
+    const item = items[index];
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("runs.all item " + index + " must be an object.");
+    const { key, ...params } = item;
+    validateRunCall(key, params, "runs.all item " + index, fingerprints);
+    calls.push({ key, params });
+  }
+  runFingerprints = fingerprints;
+  const batch = { id: "batch-" + (++nextCallId), calls };
+  const launched = calls.map(({ key, params }, index) => runHostCall(key, params, true, batch, generatedLaneKeys?.[index]));
+  return { calls, launched };
+}
+
 const runs = Object.freeze({
   run(key, params) {
     validateRunCall(key, params, "runs.run", runFingerprints);
@@ -372,22 +662,16 @@ const runs = Object.freeze({
     return trackRunObservation([{ key, operation: "run", callId: launched.callId }], launched.promise.then(decorateWorkflowChildResult));
   },
   all(items) {
-    if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
-    const fingerprints = new Map(runFingerprints);
-    const calls = [];
-    for (let index = 0; index < items.length; index++) {
-      if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("runs.all items must not contain sparse entries.");
-      const item = items[index];
-      if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("runs.all item " + index + " must be an object.");
-      const { key, ...params } = item;
-      validateRunCall(key, params, "runs.all item " + index, fingerprints);
-      calls.push({ key, params });
-    }
-    runFingerprints = fingerprints;
-    const batch = { id: "batch-" + (++nextCallId), calls };
-    const launched = calls.map(({ key, params }) => runHostCall(key, params, true, batch));
+    const { calls, launched } = launchRunsAll(items);
     return trackRunObservation(launched.map(({ key, callId }) => ({ key, operation: "run", callId })), Promise.all(launched.map(({ promise }) => promise)).then((results) => wrapRunsAllResults(results.map(decorateWorkflowChildResult), calls.map(({ key }) => key))));
   },
+  lanes(laneSpecs) {
+    return runLanes(laneSpecs);
+  },
+  host(key, params) {
+    validateHostCommand(key, params);
+    return hostCall("host", { key, params }, { key, operation: "host" });
+  },
   steer(key, message, options = {}) {
     if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error("runs.steer has an invalid key.");
     if (typeof message !== "string" || !message.trim()) throw new Error("runs.steer message must be a non-empty string.");
@@ -654,6 +938,7 @@ parentPort.on("message", async (message) => {
 export interface WorkflowScriptChildResult {
 	key: string;
 	ok: boolean;
+	lane?: import("../shared/types.ts").WorkflowLaneMetadata;
 	terminalOutcome?: import("../shared/types.ts").WorkflowTerminalOutcome;
 	stopped?: boolean;
 	/** Canonical child agent name when launch resolution produced one. */
@@ -672,11 +957,11 @@ export interface WorkflowScriptChildResult {
 	resumability?: { state: "resumable" } | { state: "not-resumable"; reason: string };
 	continuation?: { runIds: string[] };
 	artifactPaths: string[];
-	results?: unknown[];
+	results?: SingleResult[];
 }
 
 export interface WorkflowScriptTraceEntry {
-	operation: "run" | "status" | "steer";
+	operation: "run" | "status" | "steer" | "host";
 	key: string;
 	state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
 	/** Canonical child agent name when resolved launch or result data is available. */
@@ -686,6 +971,10 @@ export interface WorkflowScriptTraceEntry {
 	phase?: string;
 	label?: string;
 	error?: string;
+	/** Internal provenance for a generated runs.lanes child key. */
+	generatedLaneKey?: string;
+	lane?: import("../shared/types.ts").WorkflowLaneMetadata;
+	warning?: string;
 }
 
 export interface WorkflowSteerOptions {
@@ -740,11 +1029,15 @@ export interface RunWorkflowScriptOptions {
 	oneUsePermit?: { claim: (key: string) => string | undefined };
 	timeoutMs?: number;
 	signal?: AbortSignal;
+	/** Maximum children executing concurrently within this workflow. Defaults to 20. */
+	globalConcurrencyLimit?: number;
 	admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
 	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean; batch: boolean }) => Promise<WorkflowScriptChildResult>;
 	resolveResume?: (reference: WorkflowReceiptResumeReference, signal: AbortSignal) => string | WorkflowResolvedResumeReference | Promise<string | WorkflowResolvedResumeReference>;
 	status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
 	steer?: (key: string, message: string, options: WorkflowSteerOptions, signal: AbortSignal) => Promise<WorkflowSteerResult>;
+	host?: (key: string, params: WorkflowHostCommandParams, signal: AbortSignal) => Promise<WorkflowHostCommandResult>;
+	onHostStep?: (hostStep: HostStepNodeV1) => void;
 	state?: {
 		get: (key: string) => unknown | Promise<unknown>;
 		set: (key: string, value: unknown) => void | Promise<void>;
@@ -916,12 +1209,47 @@ function literalString(node: unknown): string | undefined {
 	return undefined;
 }
 
-function directRunsCall(node: unknown, method: "run" | "all"): node is AstNode {
+function directRunsCall(node: unknown, method: "run" | "all" | "host"): node is AstNode {
 	if (!astNode(node) || node.type !== "CallExpression" || !astNode(node.callee) || node.callee.type !== "MemberExpression") return false;
 	const property = node.callee.computed === true ? literalString(node.callee.property) : astNode(node.callee.property) && node.callee.property.type === "Identifier" ? node.callee.property.name : undefined;
 	return property === method && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "runs";
 }
 
+function validateStaticHostCall(call: AstNode): WorkflowScriptValidationError[] {
+	const args = Array.isArray(call.arguments) ? call.arguments : [];
+	const keyNode = astNode(args[0]) ? args[0] : undefined;
+	const params = astNode(args[1]) ? args[1] : undefined;
+	const errors: WorkflowScriptValidationError[] = [];
+	const key = literalString(keyNode);
+	if (keyNode && key !== undefined && !KEY_PATTERN.test(key)) errors.push({ message: "runs.host key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.", ...nodeLocation(keyNode) });
+	if (!params || params.type !== "ObjectExpression" || !Array.isArray(params.properties) || params.properties.some((property) => !astNode(property) || property.type !== "Property")) return errors;
+	const allowed = new Set(["kind", "command", "timeoutMs", "output", "role", "provider"]);
+	for (const property of params.properties) {
+		if (!astNode(property)) continue;
+		const name = staticPropertyKey(property);
+		if (name !== undefined && !allowed.has(name)) errors.push({ message: `runs.host params contain unsupported field '${name}'.`, ...nodeLocation(property) });
+	}
+	const kindNode = directObjectPropertyValue(params, "kind");
+	const commandNode = directObjectPropertyValue(params, "command");
+	const timeoutNode = directObjectPropertyValue(params, "timeoutMs");
+	const kind = literalString(kindNode);
+	const command = literalString(commandNode);
+	const timeout = astNode(timeoutNode) && timeoutNode.type === "Literal" ? timeoutNode.value : undefined;
+	if (!kindNode) errors.push({ message: "runs.host params require kind: 'command'.", ...nodeLocation(params) });
+	else if (kind !== undefined && kind !== "command") errors.push({ message: "runs.host params kind must be 'command'.", ...nodeLocation(kindNode) });
+	if (!commandNode) errors.push({ message: "runs.host params require command.", ...nodeLocation(params) });
+	else if (command !== undefined && !command.trim()) errors.push({ message: "runs.host params command must be non-empty.", ...nodeLocation(commandNode) });
+	if (!timeoutNode) errors.push({ message: "runs.host params require timeoutMs.", ...nodeLocation(params) });
+	else if (typeof timeout === "number" && (!Number.isInteger(timeout) || timeout < 1)) errors.push({ message: "runs.host params timeoutMs must be a positive integer.", ...nodeLocation(timeoutNode) });
+	const outputNode = directObjectPropertyValue(params, "output");
+	const output = literalString(outputNode);
+	if (outputNode && output !== undefined && (!output.trim() || /^[/\\]|(?:^|[/\\])\.\.(?:[/\\]|$)/.test(output))) errors.push({ message: "runs.host params output must be a non-empty relative path without traversal.", ...nodeLocation(outputNode) });
+	const roleNode = directObjectPropertyValue(params, "role");
+	const role = literalString(roleNode);
+	if (roleNode && role !== undefined && role !== "ci" && role !== "gate") errors.push({ message: "runs.host params role must be 'ci' or 'gate'.", ...nodeLocation(roleNode) });
+	return errors;
+}
+
 function nodeLocation(node: AstNode): Pick<WorkflowScriptValidationError, "line" | "column"> {
 	return node.loc ? { line: Math.max(1, node.loc.start.line - 1), column: node.loc.start.column + 1 } : {};
 }
@@ -1042,6 +1370,7 @@ export function validateWorkflowScript(script: string): WorkflowScriptValidation
 				}
 			}
 		}
+		if (directRunsCall(node, "host")) errors.push(...validateStaticHostCall(node));
 		const boundaryValue = node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "Identifier" && node.callee.name === "emit" && Array.isArray(node.arguments) && astNode(node.arguments[0])
 			? node.arguments[0]
 			: node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "MemberExpression" && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "state" && astNode(node.callee.property) && node.callee.property.type === "Identifier" && node.callee.property.name === "set" && Array.isArray(node.arguments) && astNode(node.arguments[1])
@@ -1111,7 +1440,7 @@ function resolveWorkflowParserEntry(): string {
 	}
 }
 
-const AUTO_RESUME_PARAM_KEYS = ["acceptance", "agentContract", "index", "intercomBridge", "label", "maxRuntimeMs", "output", "outputMode", "outputSchema", "phase", "skill", "skills", "task", "timeoutMs", "toolBudget", "turnBudget", "worktree"] as const;
+const AUTO_RESUME_PARAM_KEYS = ["acceptance", "agentContract", "index", "intercomBridge", "label", "lane", "maxRuntimeMs", "output", "outputMode", "outputSchema", "phase", "skill", "skills", "task", "timeoutMs", "toolBudget", "worktree"] as const;
 
 function isZeroUsage(usage: unknown): boolean {
 	if (!isRecord(usage)) return false;
@@ -1149,6 +1478,10 @@ function setupAbortResumeParams(params: Record<string, unknown>, result: Workflo
 export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
 	if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
 	if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new Error("workflow script timeout must be a positive integer.");
+	if (options.globalConcurrencyLimit !== undefined && (!Number.isInteger(options.globalConcurrencyLimit) || options.globalConcurrencyLimit < 1)) {
+		throw new Error("workflow script global concurrency limit must be a positive integer.");
+	}
+	const launchSemaphore = new Semaphore(options.globalConcurrencyLimit ?? DEFAULT_GLOBAL_CONCURRENCY_LIMIT);
 
 	let acornPath: string;
 	try {
@@ -1162,13 +1495,15 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 	const trace: WorkflowScriptTraceEntry[] = [];
 	const children = new Map<string, WorkflowScriptChildResult>();
 	const childOrder: string[] = [];
-	const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult>; observed: boolean }>();
+	const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult>; observed: boolean; generatedLaneKey?: string }>();
 	const steers = new Map<number, { key: string; promise: Promise<WorkflowSteerResult>; observed: boolean }>();
+	const hostCalls = new Map<number, { key: string; promise: Promise<WorkflowHostCommandResult>; observed: boolean }>();
 	const stoppedLaunches = new Set<string>();
 	const childStopControllers = new Map<string, AbortController>();
 	const batchAdmissions = new Map<string, Promise<void>>();
 	const observedRunCalls = new Set<number>();
 	const observedSteerCalls = new Set<number>();
+	const observedHostCalls = new Set<number>();
 	const childController = new AbortController();
 	let settled = false;
 	let finishing = false;
@@ -1189,7 +1524,18 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			console.error("Workflow onTrace callback failed:", error);
 		}
 	};
+	const hostStepChanged = (hostStep: HostStepNodeV1) => {
+		try {
+			options.onHostStep?.(hostStep);
+		} catch (error) {
+			console.error("Workflow onHostStep callback failed:", error);
+		}
+	};
 	const stoppedChildResult = (key: string, message: string): WorkflowScriptChildResult => ({ key, ok: false, stopped: true, output: message, error: message, artifactPaths: [] });
+	const responseBoundaryFailure = (key: string, error: unknown): WorkflowScriptChildResult => {
+		const text = error instanceof Error ? error.message : String(error);
+		return { key, ok: false, output: text, error: text, artifactPaths: [] };
+	};
 	const stopChild = (key: string, message = `Workflow child '${key}' stopped by user.`): boolean => {
 		if (!launches.has(key) || children.has(key)) return false;
 		stoppedLaunches.add(key);
@@ -1203,6 +1549,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			...(started?.agent ? { agent: started.agent } : {}),
 			...(started?.phase ? { phase: started.phase } : {}),
 			...(started?.label ? { label: started.label } : {}),
+			...(started?.generatedLaneKey ? { generatedLaneKey: started.generatedLaneKey } : {}),
 			error: message,
 		});
 		traceChanged();
@@ -1215,7 +1562,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (settled || finishing) return;
 			finishing = true;
 			childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed."));
-			void Promise.allSettled([...steers.values()].map(({ promise }) => promise)).then(() => {
+			void Promise.allSettled([...steers.values(), ...hostCalls.values()].map(({ promise }) => promise)).then(() => {
 				if (settled) return;
 				settled = true;
 				options.registerStopChild?.(undefined);
@@ -1228,7 +1575,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					: "value" in outcome
 						? (() => {
 							const unobservedSteers = [...steers.values()].filter((steer) => !steer.observed).map((steer) => steer.key);
-							return unobservedSteers.length > 0 ? new Error(`workflowScript completed with unawaited runs.steer call(s): ${unobservedSteers.map((key) => `'${key}'`).join(", ")}. Await or return each call.`) : undefined;
+							if (unobservedSteers.length > 0) return new Error(`workflowScript completed with unawaited runs.steer call(s): ${unobservedSteers.map((key) => `'${key}'`).join(", ")}. Await or return each call.`);
+							const unobservedHosts = [...hostCalls.values()].filter((host) => !host.observed).map((host) => host.key);
+							return unobservedHosts.length > 0 ? new Error(`workflowScript completed with unawaited runs.host call(s): ${unobservedHosts.map((key) => `'${key}'`).join(", ")}. Await or return each call.`) : undefined;
 						})()
 						: undefined;
 				if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), outcome.error.workflowErrorKind === "detached-child" || outcome.error.workflowErrorKind === "timeout" ? outcome.error.workflowErrorKind : undefined));
@@ -1254,6 +1603,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					...(started?.agent ? { agent: started.agent } : {}),
 					...(started?.phase ? { phase: started.phase } : {}),
 					...(started?.label ? { label: started.label } : {}),
+					...(started?.generatedLaneKey ? { generatedLaneKey: started.generatedLaneKey } : {}),
 					error: error.message,
 				});
 			}
@@ -1322,12 +1672,16 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					const steer = steers.get(message.callId);
 					if (steer) steer.observed = true;
 					else observedSteerCalls.add(message.callId);
+				} else if (message.operation === "host") {
+					const host = hostCalls.get(message.callId);
+					if (host) host.observed = true;
+					else observedHostCalls.add(message.callId);
 				}
 				return;
 			}
 			if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
 
-			const respond = (promise: Promise<unknown>, responsePath?: string) => {
+			const respond = (promise: Promise<unknown>, responsePath?: string, onBoundaryError?: (error: unknown) => void) => {
 				void promise.then(
 					(value) => {
 						if (settled) return;
@@ -1340,6 +1694,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 							assertWorkflowJsonValue(normalized, responsePath);
 							worker.postMessage({ type: "response", callId: message.callId, ok: true, value: normalized });
 						} catch (error) {
+							onBoundaryError?.(error);
 							worker.postMessage({ type: "response", callId: message.callId, ok: false, error: `${responsePath} must contain only JSON data before it can be returned from workflowScript. Return a plain projection such as { runId, ok, output }. ${error instanceof Error ? error.message : String(error)}` });
 						}
 					},
@@ -1414,6 +1769,52 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				respond(promise);
 				return;
 			}
+			if (message.method === "host") {
+				let key: string;
+				let params: WorkflowHostCommandParams;
+				try {
+					key = validateKey(message.args.key, "runs.host");
+					params = normalizeWorkflowHostCommandParams(message.args.params, `runs.host('${key}') params`);
+				} catch (error) {
+					return respond(Promise.reject(error));
+				}
+				if (!options.host) return respond(Promise.reject(new Error("runs.host is unavailable in this host context.")));
+				if (hostCalls.size >= HOST_STEP_MAX_COUNT) return respond(Promise.reject(new Error(`workflowScript supports at most ${HOST_STEP_MAX_COUNT} runs.host calls.`)));
+				const startedAt = Date.now();
+				const startedStep: HostStepNodeV1 = {
+					version: 1,
+					kind: "host-step",
+					monitorKind: "command",
+					id: key,
+					label: key,
+					...(params.role ? { role: params.role } : {}),
+					...(params.provider ? { provider: params.provider } : {}),
+					state: "running",
+					updatedAt: startedAt,
+					deadlineAt: startedAt + params.timeoutMs,
+				};
+				hostStepChanged(startedStep);
+				trace.push({ operation: "host", key, state: "started" });
+				traceChanged();
+				const promise = Promise.resolve().then(() => options.host!(key, params, childController.signal)).then((result) => {
+					const state = result.state === "stopped" ? "cancelled" : result.ok ? "done" : "error";
+					const detail = [result.error, result.stderr.trim() || result.stdout.trim()].filter(Boolean).join(" ").replace(/\s+/g, " ").trim().slice(0, 200);
+					hostStepChanged({ ...startedStep, state, ...(state === "done" ? { verdict: "pass" as const } : {}), ...(!result.ok ? { reasonCode: result.state === "timed-out" ? "timed_out" : result.state === "stopped" ? "aborted" : "command_failed" } : {}), ...(detail ? { detail } : {}), reportPath: params.output ?? result.outputPath.split(/[\\/]/).at(-1), exitCode: result.exitCode, updatedAt: Date.now() });
+					trace.push({ operation: "host", key, state: result.ok ? "completed" : result.state === "stopped" ? "stopped" : "failed", durationMs: result.durationMs, ...(!result.ok ? { error: result.error ?? "Host command failed." } : {}) });
+					traceChanged();
+					if (!result.ok) throw new Error(`Host command '${key}' failed: ${detail || result.error || `exit code ${result.exitCode ?? "unknown"}`}`);
+					return result;
+				}, (error: unknown) => {
+					const text = error instanceof Error ? error.message : String(error);
+					hostStepChanged({ ...startedStep, state: "error", reasonCode: "execution_failed", detail: text.replace(/\s+/g, " ").slice(0, 200), updatedAt: Date.now() });
+					trace.push({ operation: "host", key, state: "failed", durationMs: Date.now() - startedAt, error: text });
+					traceChanged();
+					throw error;
+				});
+				hostCalls.set(message.callId, { key, promise, observed: observedHostCalls.delete(message.callId) });
+				respond(promise, `runs.host('${key}') result`);
+				return;
+			}
 			if (message.method !== "run") return respond(Promise.reject(new Error(`Unknown runs API method '${message.method}'.`)));
 
 			let key: string;
@@ -1424,6 +1825,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			}
 			const params = message.args.params;
 			if (!isRecord(params)) return respond(Promise.reject(new Error(`runs.run('${key}', params) requires a params object.`)));
+			const generatedLaneKey = typeof message.args.generatedLaneKey === "string" && KEY_PATTERN.test(message.args.generatedLaneKey) && key.startsWith(`${message.args.generatedLaneKey}.`)
+				? message.args.generatedLaneKey
+				: undefined;
 			const collectFailure = message.args.collectFailure === true;
 			const callObserved = observedRunCalls.delete(message.callId);
 			const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
@@ -1441,9 +1845,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (existing) {
 				if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
 				if (callObserved) existing.observed = true;
-				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
+				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params), ...(existing.generatedLaneKey ? { generatedLaneKey: existing.generatedLaneKey } : {}) });
 				traceChanged();
-				return respond(deliver(existing.promise), `runs.run('${key}') result`);
+				return respond(deliver(existing.promise), `runs.run('${key}') result`, (error) => children.set(key, responseBoundaryFailure(key, error)));
 			}
 			const permitError = options.oneUsePermit?.claim(key);
 			if (permitError) return respond(Promise.reject(new Error(permitError)));
@@ -1528,13 +1932,23 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					if (resolvedResumeLineage.at(-1) !== resolvedResumeId) resolvedResumeLineage.push(resolvedResumeId!);
 				}
 				const launchParams = resolvedResumeId ? { ...params, resume: resolvedResumeId } : params;
-				const result = await options.launch(key, launchParams, childSignal, { admitted: true, batch: batch !== undefined });
-				const autoResumeParams = setupAbortResumeParams(params, result, childSignal);
-				if (!autoResumeParams) return result;
-				resolvedResumeLineage = [...new Set([...(resolvedResumeLineage ?? []), result.runId!])];
-				trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(autoResumeParams), phase: "auto-resume", runId: result.runId });
-				traceChanged();
-				return options.launch(key, autoResumeParams, childSignal, { admitted: true, batch: batch !== undefined });
+				await launchSemaphore.acquire();
+				try {
+					if (settled || finishing || stoppedLaunches.has(key) || childSignal.aborted) {
+						const reason = childSignal.reason;
+						const text = children.get(key)?.error ?? (reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.");
+						return stoppedChildResult(key, text);
+					}
+					const result = await options.launch(key, launchParams, childSignal, { admitted: true, batch: batch !== undefined });
+					const autoResumeParams = setupAbortResumeParams(params, result, childSignal);
+					if (!autoResumeParams) return result;
+					resolvedResumeLineage = [...new Set([...(resolvedResumeLineage ?? []), result.runId!])];
+					trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(autoResumeParams), ...(generatedLaneKey ? { generatedLaneKey } : {}), phase: "auto-resume", runId: result.runId });
+					traceChanged();
+					return options.launch(key, autoResumeParams, childSignal, { admitted: true, batch: batch !== undefined });
+				} finally {
+					launchSemaphore.release();
+				}
 			}).then((result) => {
 				let normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
 				if (resolvedResumeLineage?.length && normalized.runId) {
@@ -1544,7 +1958,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				if (stoppedLaunches.has(key)) return children.get(key) ?? normalized;
 				children.set(key, normalized);
 				const state = normalized.ok ? "completed" : normalized.stopped ? "stopped" : normalized.detached ? "detached" : "failed";
-				trace.push({ operation: "run", key, state, durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
+				trace.push({ operation: "run", key, state, durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}), ...(normalized.agent ? { agent: normalized.agent } : {}), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
 				traceChanged();
 				return normalized;
 			}, (error: unknown) => {
@@ -1553,15 +1967,15 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				childStopControllers.delete(key);
 				if (stoppedLaunches.has(key)) return children.get(key) ?? { ...failure, stopped: true };
 				children.set(key, failure);
-				trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
+				trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}), error: text });
 				traceChanged();
 				return failure;
 			});
-			launches.set(key, { fingerprint, promise, observed: callObserved });
+			launches.set(key, { fingerprint, promise, observed: callObserved, ...(generatedLaneKey ? { generatedLaneKey } : {}) });
 			childOrder.push(key);
-			trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
+			trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params), ...(generatedLaneKey ? { generatedLaneKey } : {}) });
 			traceChanged();
-			respond(deliver(promise), `runs.run('${key}') result`);
+			respond(deliver(promise), `runs.run('${key}') result`, (error) => children.set(key, responseBoundaryFailure(key, error)));
 		});
 
 		worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });