@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/src/workflows/human-decision.ts

@@ -24,6 +24,8 @@ import type {
   HumanDecisionSettlementRecord,
   HumanDecisionSubmission,
   HumanDecisionTextInput,
+  HumanDecisionTimeout,
+  ResolvedHumanDecision,
   WorkflowNodeCommon,
   WorkflowNodeContext,
 } from "./types.js";
@@ -43,6 +45,14 @@ export type HumanDecisionDefinition<TChoices extends HumanDecisionChoiceMap> =
     audience: HumanDecisionAudience;
     choices: TChoices;
     request: (context: WorkflowNodeContext) => HumanDecisionPrompt | Promise<HumanDecisionPrompt>;
+    onTimeout?:
+      | { afterMs: number; response: HumanDecisionResponseFor<TChoices> }
+      | ((
+          context: WorkflowNodeContext,
+        ) =>
+          | { afterMs: number; response: HumanDecisionResponseFor<TChoices> }
+          | undefined
+          | Promise<{ afterMs: number; response: HumanDecisionResponseFor<TChoices> } | undefined>);
   };
 
 export type HumanDecisionResponseFor<TChoices extends HumanDecisionChoiceMap> = {
@@ -98,11 +108,25 @@ export function humanDecision<const TChoices extends HumanDecisionChoiceMap>(
   if (typeof definition.request !== "function") {
     throw new Error("Human decision request must be a function");
   }
-  const { choices, request, ...common } = definition;
+  const { choices, request, onTimeout, ...common } = definition;
+  if (
+    onTimeout !== undefined &&
+    typeof onTimeout !== "function" &&
+    (typeof onTimeout.afterMs !== "number" ||
+      !Number.isFinite(onTimeout.afterMs) ||
+      onTimeout.afterMs <= 0)
+  ) {
+    throw new Error("Human decision onTimeout afterMs must be a finite positive number");
+  }
   return checkpoint({
     ...common,
     summary: typeof audience === "string" ? `human decision for ${audience}` : "human decision",
-    humanDecision: { audience, choices, request },
+    humanDecision: {
+      audience,
+      choices,
+      request,
+      ...(onTimeout !== undefined ? { onTimeout } : {}),
+    },
   }) as CheckpointNodeDefinition & { readonly __humanChoices?: TChoices };
 }
 
@@ -136,11 +160,31 @@ export function createHumanDecisionRequest(input: {
   attemptId: string;
   contract: { audience: string; choices: HumanDecisionChoiceMap };
   prompt: HumanDecisionPrompt;
+  timeout?: HumanDecisionTimeout;
   createdAt?: string;
 }): HumanDecisionRequest {
   validateChoices(input.contract.choices);
+  const createdAt = input.createdAt ?? new Date().toISOString();
   const title = requireString(input.prompt.title, "Human decision title");
-  const expiresAt = validateExpiry(input.prompt.expiresAt, input.createdAt);
+  if (input.timeout !== undefined && input.prompt.expiresAt !== undefined) {
+    throw new Error("Human decision request cannot combine expiresAt with onTimeout");
+  }
+  if (
+    input.timeout !== undefined &&
+    (typeof input.timeout.afterMs !== "number" ||
+      !Number.isFinite(input.timeout.afterMs) ||
+      input.timeout.afterMs <= 0)
+  ) {
+    throw new Error("Human decision onTimeout afterMs must be a finite positive number");
+  }
+  const defaultResponse =
+    input.timeout === undefined
+      ? undefined
+      : validateResponseForChoices(input.contract.choices, input.timeout.response);
+  const expiresAt =
+    input.timeout === undefined
+      ? validateExpiry(input.prompt.expiresAt, createdAt)
+      : new Date(Date.parse(createdAt) + input.timeout.afterMs).toISOString();
   const common = {
     runId: input.runId,
     workflowName: input.workflowName,
@@ -150,58 +194,35 @@ export function createHumanDecisionRequest(input: {
     title,
     choices: input.contract.choices,
     ...(expiresAt !== undefined ? { expiresAt } : {}),
+    ...(defaultResponse !== undefined ? { defaultResponse } : {}),
   } as const;
-  const presented =
-    Object.hasOwn(input.prompt, "subject") || Object.hasOwn(input.prompt, "presentation");
-  if (presented) {
-    validatePresentedText(title, "Human decision title");
-    validatePresentedChoices(input.contract.choices);
-    if (Object.hasOwn(input.prompt, "body")) {
-      throw new Error("Presented human decision requests must not contain a legacy body");
-    }
-    if (!Object.hasOwn(input.prompt, "subject") || !Object.hasOwn(input.prompt, "presentation")) {
-      throw new Error("Presented human decision requests require subject and presentation");
-    }
-    const prompt = input.prompt as Extract<HumanDecisionPrompt, { subject: unknown }>;
-    assertJsonValue(prompt.subject, "Human decision subject");
-    const presentation = normalizeDecisionPresentation(prompt.presentation);
-    const revision = prompt.revision ?? 1;
-    if (!Number.isInteger(revision) || revision < 1) {
-      throw new Error("Human decision revision must be a positive integer");
-    }
-    const basis = {
-      schema: "pi-workflows.human-decision-request.v2" as const,
-      ...common,
-      subject: prompt.subject,
-      presentation,
-      revision,
-    };
-    const subjectDigest = digestCanonical(prompt.subject);
-    const presentationDigest = digestCanonical(presentation);
-    const requestDigest = digestCanonical(basis);
-    const decisionId = decisionIdFor(input, requestDigest);
-    return {
-      ...basis,
-      decisionId,
-      requestDigest,
-      subjectDigest,
-      presentationDigest,
-      createdAt: input.createdAt ?? new Date().toISOString(),
-    };
+  validatePresentedText(title, "Human decision title");
+  validatePresentedChoices(input.contract.choices);
+  const prompt = input.prompt;
+  assertJsonValue(prompt.subject, "Human decision subject");
+  const presentation = normalizeDecisionPresentation(prompt.presentation);
+  const revision = prompt.revision ?? 1;
+  if (!Number.isInteger(revision) || revision < 1) {
+    throw new Error("Human decision revision must be a positive integer");
   }
-  const prompt = input.prompt as Extract<HumanDecisionPrompt, { body: unknown }>;
-  assertJsonValue(prompt.body, "Human decision body");
   const basis = {
     schema: "pi-workflows.human-decision-request.v1" as const,
     ...common,
-    body: prompt.body,
+    subject: prompt.subject,
+    presentation,
+    revision,
   };
-  const requestDigest = digest(basis);
+  const subjectDigest = digestCanonical(prompt.subject);
+  const presentationDigest = digestCanonical(presentation);
+  const requestDigest = digestCanonical(basis);
+  const decisionId = decisionIdFor(input, requestDigest);
   return {
     ...basis,
-    decisionId: decisionIdFor(input, requestDigest),
+    decisionId,
     requestDigest,
-    createdAt: input.createdAt ?? new Date().toISOString(),
+    subjectDigest,
+    presentationDigest,
+    createdAt,
   };
 }
 
@@ -220,13 +241,20 @@ function decisionIdFor(
 export function validateHumanDecisionResponse(
   request: HumanDecisionRequest,
   value: unknown,
+): HumanDecisionResponse {
+  return validateResponseForChoices(request.choices, value);
+}
+
+function validateResponseForChoices(
+  choices: HumanDecisionChoiceMap,
+  value: unknown,
 ): HumanDecisionResponse {
   const response = requireRecord(value, "Human decision response");
   const selected = response.choice;
-  if (typeof selected !== "string" || !Object.hasOwn(request.choices, selected)) {
+  if (typeof selected !== "string" || !Object.hasOwn(choices, selected)) {
     throw new Error(`Human decision choice ${JSON.stringify(selected)} is not available`);
   }
-  const selectedChoice = request.choices[selected];
+  const selectedChoice = choices[selected];
   if (!selectedChoice) throw new Error("Human decision choice contract is missing");
   if (selectedChoice.input === undefined) {
     if (response.input !== undefined) {
@@ -288,34 +316,65 @@ export function humanDecisionStateRoot(runsRoot: string): string {
 }
 
 export type HumanDecisionAcceptance =
-  | { status: "accepted" | "adopted"; decision: AcceptedHumanDecision }
-  | { status: "conflict"; decision: AcceptedHumanDecision };
+  | { status: "accepted" | "adopted"; decision: ResolvedHumanDecision }
+  | { status: "conflict"; decision: ResolvedHumanDecision };
 
 type HumanDecisionResolution =
   | {
       schema: "pi-workflows.human-decision-resolution.v1";
       outcome: "accepted";
-      decision: Extract<
-        AcceptedHumanDecision,
-        { schema: "pi-workflows.human-decision-accepted.v1" }
-      >;
+      decision: ResolvedHumanDecision;
     }
   | {
-      schema: "pi-workflows.human-decision-resolution.v2";
-      outcome: "accepted";
-      decision: Extract<
-        AcceptedHumanDecision,
-        { schema: "pi-workflows.human-decision-accepted.v2" }
-      >;
-    }
-  | {
-      schema:
-        | "pi-workflows.human-decision-resolution.v1"
-        | "pi-workflows.human-decision-resolution.v2";
+      schema: "pi-workflows.human-decision-resolution.v1";
       outcome: "cancelled";
       cancellation: HumanDecisionCancellationRecord;
     };
 
+const INCOMPATIBLE_HUMAN_DECISION_STATE =
+  "Human decision state uses an incompatible alpha contract; reset the affected workflow run and decision state.";
+
+function requireCurrentDecision(value: unknown): ResolvedHumanDecision {
+  const decision = requireRecord(value, "Resolved human decision");
+  if (
+    decision.schema !== "pi-workflows.human-decision-accepted.v1" ||
+    !Object.hasOwn(decision, "subjectDigest") ||
+    !Object.hasOwn(decision, "presentationDigest") ||
+    !Object.hasOwn(decision, "revision")
+  ) {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  return value as ResolvedHumanDecision;
+}
+
+function requireCurrentResolution(value: unknown): HumanDecisionResolution | null {
+  if (value === null) return null;
+  const resolution = requireRecord(value, "Human decision resolution");
+  if (resolution.schema !== "pi-workflows.human-decision-resolution.v1") {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  if (resolution.outcome === "accepted") {
+    return {
+      ...resolution,
+      decision: requireCurrentDecision(resolution.decision),
+    } as HumanDecisionResolution;
+  }
+  if (resolution.outcome === "cancelled") return value as HumanDecisionResolution;
+  throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+}
+
+function requireCurrentDelivery(value: unknown): HumanDecisionDeliveryRecord {
+  const delivery = requireRecord(value, "Human decision delivery");
+  if (
+    delivery.schema !== "pi-workflows.human-decision-delivery.v1" ||
+    !Object.hasOwn(delivery, "presentationDigest") ||
+    !Object.hasOwn(delivery, "phase")
+  ) {
+    throw new Error(INCOMPATIBLE_HUMAN_DECISION_STATE);
+  }
+  return value as HumanDecisionDeliveryRecord;
+}
+
 export class HumanDecisionStore {
   readonly root: string;
 
@@ -412,36 +471,35 @@ export class HumanDecisionStore {
       decisionId: request.decisionId,
       requestDigest: request.requestDigest,
       response,
+      provenance: "human" as const,
       source: normalized.source,
       idempotencyKey: normalized.idempotencyKey,
       acceptedAt: attemptedAt,
       answerDigest: digest({ response, source: normalized.source }),
     };
-    const decision: AcceptedHumanDecision =
-      request.schema === "pi-workflows.human-decision-request.v2"
-        ? {
-            schema: "pi-workflows.human-decision-accepted.v2",
-            ...commonDecision,
-            subjectDigest: request.subjectDigest,
-            presentationDigest: request.presentationDigest,
-            revision: request.revision,
-          }
-        : { schema: "pi-workflows.human-decision-accepted.v1", ...commonDecision };
+    const decision: AcceptedHumanDecision = {
+      schema: "pi-workflows.human-decision-accepted.v1",
+      ...commonDecision,
+      subjectDigest: request.subjectDigest,
+      presentationDigest: request.presentationDigest,
+      revision: request.revision,
+    };
     const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
-    const resolution = {
-      schema:
-        decision.schema === "pi-workflows.human-decision-accepted.v2"
-          ? ("pi-workflows.human-decision-resolution.v2" as const)
-          : ("pi-workflows.human-decision-resolution.v1" as const),
-      outcome: "accepted" as const,
+    const resolution: HumanDecisionResolution = {
+      schema: "pi-workflows.human-decision-resolution.v1",
+      outcome: "accepted",
       decision,
-    } as HumanDecisionResolution;
+    };
     const result = await writeImmutableJson(resolutionPath, resolution, false);
     const winner =
       result === "created"
         ? resolution
         : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
     if (winner === null) throw new Error("Human decision resolution became unreadable");
+    const winningCancellation = await this.readCancellation(request.decisionId);
+    if (winningCancellation !== null) {
+      throw new Error(`Human decision request was ${winningCancellation.reason}`);
+    }
     if (winner.outcome === "cancelled") {
       throw new Error(`Human decision request was ${winner.cancellation.reason}`);
     }
@@ -455,6 +513,7 @@ export class HumanDecisionStore {
       return { status: "adopted", decision: existing };
     }
     if (
+      existing.provenance === "human" &&
       existing.idempotencyKey === decision.idempotencyKey &&
       canonicalJson(existing.response) === canonicalJson(decision.response) &&
       canonicalJson(existing.source) === canonicalJson(decision.source)
@@ -464,13 +523,74 @@ export class HumanDecisionStore {
     return { status: "conflict", decision: existing };
   }
 
+  async resolveTimeout(
+    request: HumanDecisionRequest,
+    now = new Date(),
+  ): Promise<HumanDecisionAcceptance> {
+    validateHumanDecisionRequestIntegrity(request);
+    if (request.expiresAt === undefined || request.defaultResponse === undefined) {
+      throw new Error("Human decision request has no timeout default");
+    }
+    if (Date.parse(request.expiresAt) > now.getTime()) {
+      throw new Error("Human decision timeout default is not eligible yet");
+    }
+    const response = validateHumanDecisionResponse(request, request.defaultResponse);
+    const commonDecision = {
+      decisionId: request.decisionId,
+      requestDigest: request.requestDigest,
+      response,
+      provenance: "timeout" as const,
+      acceptedAt: now.toISOString(),
+      answerDigest: digest({
+        provenance: "timeout",
+        requestDigest: request.requestDigest,
+        response,
+      }),
+    };
+    const decision: ResolvedHumanDecision = {
+      schema: "pi-workflows.human-decision-accepted.v1",
+      ...commonDecision,
+      subjectDigest: request.subjectDigest,
+      presentationDigest: request.presentationDigest,
+      revision: request.revision,
+    };
+    const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
+    const resolution: HumanDecisionResolution = {
+      schema: "pi-workflows.human-decision-resolution.v1",
+      outcome: "accepted",
+      decision,
+    };
+    const result = await writeImmutableJson(resolutionPath, resolution, false);
+    const winner =
+      result === "created"
+        ? resolution
+        : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
+    if (winner === null) throw new Error("Human decision resolution became unreadable");
+    const winningCancellation = await this.readCancellation(request.decisionId);
+    if (winningCancellation !== null) {
+      throw new Error(`Human decision request was ${winningCancellation.reason}`);
+    }
+    if (winner.outcome === "cancelled") {
+      throw new Error(`Human decision request was ${winner.cancellation.reason}`);
+    }
+    const existing = winner.decision;
+    await writeImmutableJson(
+      path.join(this.decisionDir(request.decisionId), "accepted.json"),
+      existing,
+    );
+    if (result === "created") return { status: "accepted", decision: existing };
+    return canonicalJson(existing) === canonicalJson(decision)
+      ? { status: "adopted", decision: existing }
+      : { status: "conflict", decision: existing };
+  }
+
   async listDeliveries(
     decisionId: string,
     channel: string,
   ): Promise<HumanDecisionDeliveryRecord[]> {
     const safeChannel = requireSimpleId(channel, "Human decision channel");
     const directory = path.join(this.decisionDir(decisionId), "deliveries", safeChannel);
-    return (await readJsonDirectory(directory)) as HumanDecisionDeliveryRecord[];
+    return (await readJsonDirectory(directory)).map(requireCurrentDelivery);
   }
 
   async recordSettlement(
@@ -505,8 +625,8 @@ export class HumanDecisionStore {
     reason: HumanDecisionCancellationRecord["reason"],
   ): Promise<"created" | "adopted"> {
     validateHumanDecisionRequestIntegrity(request);
-    if ((await this.readAccepted(request.decisionId)) !== null) {
-      throw new Error("Accepted human decision cannot be cancelled");
+    if ((await this.readResolved(request.decisionId)) !== null) {
+      throw new Error("Resolved human decision cannot be cancelled");
     }
     const filePath = path.join(this.decisionDir(request.decisionId), "cancelled.json");
     const record: HumanDecisionCancellationRecord = {
@@ -518,10 +638,7 @@ export class HumanDecisionStore {
     };
     const resolutionPath = path.join(this.decisionDir(request.decisionId), "resolution.json");
     const resolution: HumanDecisionResolution = {
-      schema:
-        request.schema === "pi-workflows.human-decision-request.v2"
-          ? "pi-workflows.human-decision-resolution.v2"
-          : "pi-workflows.human-decision-resolution.v1",
+      schema: "pi-workflows.human-decision-resolution.v1",
       outcome: "cancelled",
       cancellation: record,
     };
@@ -532,7 +649,7 @@ export class HumanDecisionStore {
         : ((await readJson(resolutionPath)) as HumanDecisionResolution | null);
     if (winner === null) throw new Error("Human decision resolution became unreadable");
     if (winner.outcome === "accepted") {
-      throw new Error("Accepted human decision cannot be cancelled");
+      throw new Error("Resolved human decision cannot be cancelled");
     }
     const existing = winner.cancellation;
     if (
@@ -551,9 +668,9 @@ export class HumanDecisionStore {
       path.join(this.decisionDir(decisionId), "cancelled.json"),
     )) as HumanDecisionCancellationRecord | null;
     if (stored !== null) return stored;
-    const resolution = (await readJson(
-      path.join(this.decisionDir(decisionId), "resolution.json"),
-    )) as HumanDecisionResolution | null;
+    const resolution = requireCurrentResolution(
+      await readJson(path.join(this.decisionDir(decisionId), "resolution.json")),
+    );
     if (resolution?.outcome !== "cancelled") return null;
     await writeImmutableJson(
       path.join(this.decisionDir(decisionId), "cancelled.json"),
@@ -562,14 +679,14 @@ export class HumanDecisionStore {
     return resolution.cancellation;
   }
 
-  async readAccepted(decisionId: string): Promise<AcceptedHumanDecision | null> {
-    const stored = (await readJson(
-      path.join(this.decisionDir(decisionId), "accepted.json"),
-    )) as AcceptedHumanDecision | null;
-    if (stored !== null) return stored;
-    const resolution = (await readJson(
-      path.join(this.decisionDir(decisionId), "resolution.json"),
-    )) as HumanDecisionResolution | null;
+  async readResolved(decisionId: string): Promise<ResolvedHumanDecision | null> {
+    const cancellation = await readJson(path.join(this.decisionDir(decisionId), "cancelled.json"));
+    if (cancellation !== null) return null;
+    const stored = await readJson(path.join(this.decisionDir(decisionId), "accepted.json"));
+    if (stored !== null) return requireCurrentDecision(stored);
+    const resolution = requireCurrentResolution(
+      await readJson(path.join(this.decisionDir(decisionId), "resolution.json")),
+    );
     if (resolution?.outcome !== "accepted") return null;
     await writeImmutableJson(
       path.join(this.decisionDir(decisionId), "accepted.json"),

package/src/workflows/index.ts

@@ -23,8 +23,8 @@ export {
   decisionPresentationFingerprint,
   digestCanonical,
   humanDecisionChannelRequest,
-  legacyDecisionPresentation,
   normalizeDecisionPresentation,
+  valueDecisionPresentation,
   validateHumanDecisionRequestIntegrity,
   type DecisionDocumentSegment,
 } from "./decision-presentation.js";
@@ -74,6 +74,21 @@ export {
   type WorkflowSearchPaths,
 } from "./loader.js";
 export { renderShellCommand, runShellAction } from "./shell.js";
+export {
+  COMMAND_BATCH_RESULT_SCHEMA,
+  MAX_COMMAND_BATCH_CONCURRENCY,
+  MAX_COMMAND_BATCH_ITEMS,
+  MAX_COMMAND_BATCH_OUTPUT_CHARS,
+  MAX_COMMAND_BATCH_TIMEOUT_MS,
+  runCommandBatch,
+  validateCommandBatchRequest,
+  type CommandBatchItem,
+  type CommandBatchItemOutcome,
+  type CommandBatchItemResult,
+  type CommandBatchRequest,
+  type CommandBatchResult,
+  type RunCommandBatchOptions,
+} from "./command-batch.js";
 export {
   estimateProgress,
   formatProgressLine,
@@ -122,8 +137,8 @@ export {
 } from "./store.js";
 export type {
   AcceptedHumanDecision,
-  AcceptedHumanDecisionV1,
-  AcceptedHumanDecisionV2,
+  DefaultedHumanDecision,
+  ResolvedHumanDecision,
   AgentNodeDefinition,
   AgentStepContract,
   AgentStepExecutor,
@@ -152,24 +167,18 @@ export type {
   HumanDecisionChoiceMap,
   HumanDecisionContinuationRecord,
   HumanDecisionDeliveryRecord,
-  HumanDecisionDeliveryRecordV1,
-  HumanDecisionDeliveryRecordV2,
   HumanDecisionNodeContract,
   HumanDecisionPrompt,
   HumanDecisionReceipt,
-  HumanDecisionReceiptV1,
-  HumanDecisionReceiptV2,
   HumanDecisionRequest,
-  HumanDecisionRequestV1,
-  HumanDecisionRequestV2,
   HumanDecisionResponse,
   HumanDecisionSettlementRecord,
   HumanDecisionSubmission,
   HumanDecisionTextInput,
-  LegacyHumanDecisionPrompt,
+  HumanDecisionTimeout,
+  HumanDecisionTimeoutPolicy,
   MaybePromise,
   NotifyNodeDefinition,
-  PresentedHumanDecisionPrompt,
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,

package/src/workflows/progress.ts

@@ -18,6 +18,7 @@ export type ProgressEstimate = {
   confidence?: ProgressConfidence;
   sourceEstimatedFinishAt?: string;
   unavailableReason?: string;
+  elapsedMs?: number;
 };
 
 export type ProgressSample = {
@@ -42,7 +43,16 @@ export function estimateProgress(
   for (const sample of samples) validateProgressData(sample.data as Record<string, unknown>);
   const latest = samples.at(-1) as ProgressSample;
   const data = latest.data;
-  const base: ProgressEstimate = { key, data, sampleCount: 1 };
+  const firstAt = Date.parse(samples[0]!.at);
+  const endAt = TERMINAL.has(data.status) ? Date.parse(latest.at) : now.getTime();
+  const elapsedMs =
+    Number.isFinite(firstAt) && Number.isFinite(endAt) ? Math.max(0, endAt - firstAt) : undefined;
+  const base: ProgressEstimate = {
+    key,
+    data,
+    sampleCount: 1,
+    ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+  };
   if (TERMINAL.has(data.status)) return base;
   const sourceFinish = validSourceFinish(latest, now);
   if (sourceFinish !== undefined) base.sourceEstimatedFinishAt = sourceFinish;
@@ -212,10 +222,15 @@ export function formatProgressLine(estimate: ProgressEstimate, now = new Date())
         ? `${formatRemaining(estimate.remainingLowMs)}–${formatRemaining(estimate.remainingHighMs)}`
         : formatRemaining(estimate.remainingMedianMs);
     eta = `ETA ${range}`;
-  } else if (!TERMINAL.has(data.status)) {
+  } else if (!TERMINAL.has(data.status) && data.phase === undefined) {
     eta = `ETA unavailable${estimate.unavailableReason ? ` (${estimate.unavailableReason})` : ""}`;
   }
-  return [label, count, eta].filter(Boolean).join("  ");
+  const phase = data.phase === undefined ? "" : sanitizeText(data.phase);
+  const elapsed =
+    data.phase === undefined || estimate.elapsedMs === undefined
+      ? ""
+      : `elapsed ${formatRemaining(estimate.elapsedMs)}`;
+  return [label, count, phase, elapsed, eta].filter(Boolean).join("  ");
 }
 
 export function formatProgressReport(

package/src/workflows/schema.ts

@@ -35,10 +35,11 @@ function assertOptionalFunction(value: unknown, description: string): void {
 function assertCommonNodeFields(node: WorkflowNodeDefinition, nodeId: string): void {
   if (
     node.timeoutMs !== undefined &&
+    node.timeoutMs !== null &&
     typeof node.timeoutMs !== "function" &&
     (typeof node.timeoutMs !== "number" || !Number.isFinite(node.timeoutMs) || node.timeoutMs <= 0)
   ) {
-    fail(`node ${nodeId} timeoutMs must be a finite positive number or function`);
+    fail(`node ${nodeId} timeoutMs must be null, a finite positive number, or a function`);
   }
   if (node.statusDetail !== undefined && typeof node.statusDetail !== "string") {
     fail(`node ${nodeId} statusDetail must be a string`);
@@ -150,6 +151,23 @@ export function assertValidCheckpointNode(
     if (typeof node.humanDecision.request !== "function") {
       fail(`node ${nodeId} humanDecision request must be a function`);
     }
+    if (
+      node.humanDecision.onTimeout !== undefined &&
+      typeof node.humanDecision.onTimeout !== "function"
+    ) {
+      assertRecord(node.humanDecision.onTimeout, `node ${nodeId} humanDecision onTimeout`);
+      if (
+        typeof node.humanDecision.onTimeout.afterMs !== "number" ||
+        !Number.isFinite(node.humanDecision.onTimeout.afterMs) ||
+        node.humanDecision.onTimeout.afterMs <= 0
+      ) {
+        fail(`node ${nodeId} humanDecision onTimeout afterMs must be a finite positive number`);
+      }
+      assertRecord(
+        node.humanDecision.onTimeout.response,
+        `node ${nodeId} humanDecision onTimeout response`,
+      );
+    }
   }
   assertCommonNodeFields(node, nodeId);
 }

package/src/workflows/shell.ts

@@ -26,6 +26,16 @@ export function renderShellCommand(command: string, args: string[]): string {
   return renderedArgs.length > 0 ? `${command} ${renderedArgs}` : command;
 }
 
+export function shellOutputTruncation(result: ShellActionResult): {
+  stdout: boolean;
+  stderr: boolean;
+} {
+  return {
+    stdout: result.stdout.endsWith(TRUNCATION_MARKER),
+    stderr: result.stderr.endsWith(TRUNCATION_MARKER),
+  };
+}
+
 function shellFailure(
   spec: ShellActionExecution,
   args: string[],

package/src/workflows/store.ts

@@ -1417,7 +1417,9 @@ function snapshotNode(
       : exit !== undefined
         ? { includeTransition: "exit" as const }
         : {}),
-    ...(typeof node.timeoutMs === "number" ? { timeoutMs: node.timeoutMs } : {}),
+    ...(typeof node.timeoutMs === "number" || node.timeoutMs === null
+      ? { timeoutMs: node.timeoutMs }
+      : {}),
     ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
   };
   if (node.nodeType === "agent" && node.expectedOutput !== undefined) {
@@ -1435,6 +1437,11 @@ function snapshotNode(
         typeof node.humanDecision.audience === "string" ? node.humanDecision.audience : "<dynamic>",
       ...(typeof node.humanDecision.audience === "function" ? { dynamicAudience: true } : {}),
       choices: structuredClone(node.humanDecision.choices),
+      ...(node.humanDecision.onTimeout !== undefined &&
+      typeof node.humanDecision.onTimeout !== "function"
+        ? { onTimeout: structuredClone(node.humanDecision.onTimeout) }
+        : {}),
+      ...(typeof node.humanDecision.onTimeout === "function" ? { dynamicTimeout: true } : {}),
     };
   }
   if (node.nodeType === "action") {