@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/src/engine/state-types.ts

@@ -1,13 +1,105 @@
 export const RUN_STATE_VERSION = 1 as const;
+export const MAX_RESUME_INPUT_CHARS = 16_000;
+export const MAX_STEP_TRACE_TASK_CHARS = 64_000;
+export const MAX_STEP_TRACE_ATTEMPTS = 16;
+export const MAX_STEP_TRACE_SUMMARY_CHARS = 8_000;
+export const MAX_STEP_TRACE_ARTIFACT_CHARS = 16_000;
+export const MAX_STEP_TRACE_LOG_EVENTS = 400;
+export const MAX_STEP_TRACE_LOG_EVENT_CHARS = 2_000;
+export const MAX_STEP_TRACE_LOG_CHARS = 120_000;
+export const MAX_WORKFLOW_TRACE_CHARS = 2_000_000;
 
 export type WorkflowRunStatus =
   'running' | 'paused' | 'awaiting-gate' | 'completed' | 'aborted';
 
+export type GateApproval = {
+  /** Stable identity of the gate request that produced this approval. */
+  readonly requestId: string;
+  readonly artifact: string;
+  readonly feedback: string;
+  /** Prompt-excluded step structure approved by this gate request. */
+  readonly stepStructuralDigest: string;
+};
+
+export type StepAttemptResult = {
+  readonly outcome: string;
+  readonly summary: string;
+  readonly summaryTruncated?: true | undefined;
+  readonly artifact?: string | undefined;
+  readonly artifactTruncated?: true | undefined;
+  readonly workspaceCwd?: string | undefined;
+};
+
+export type StepGateDecision = {
+  readonly provider: 'prompt' | 'plannotator';
+  readonly requestId: string;
+  readonly approved: boolean;
+  readonly feedback: string;
+  readonly feedbackTruncated?: true | undefined;
+  readonly resolvedAt: number;
+  readonly reviewId?: string | undefined;
+};
+
+export type SubagentTranscriptReference = {
+  /** Trusted parent-derived directory containing this child run. */
+  readonly trustedRoot: string;
+  /** Exact child session returned by the delegation protocol. */
+  readonly sessionFile: string;
+  /** Pi-subagents run identity used to confine the session path. */
+  readonly runId: string;
+  readonly childIndex: number;
+};
+
+export type StepExecutionAttempt =
+  | {
+      readonly kind: 'main';
+      readonly requestId: string;
+      /** One-based attempt position within this step visit. */
+      readonly ordinal?: number | undefined;
+      /** Exact workflow task sent to the main agent. */
+      readonly task: string;
+      readonly taskTruncated?: true | undefined;
+      readonly omittedTaskChars?: number | undefined;
+      /** Redacted assistant/tool events retained from the start of this attempt. */
+      readonly log?: ReadonlyArray<string> | undefined;
+      /** Whether later events were omitted from the bounded prefix. */
+      readonly logTruncated?: true | undefined;
+      readonly omittedLogEvents?: number | undefined;
+      readonly startedAt: number;
+      readonly result?: StepAttemptResult | undefined;
+      readonly gateDecision?: StepGateDecision | undefined;
+    }
+  | {
+      readonly kind: 'subagent';
+      readonly requestId: string;
+      /** One-based attempt position within this step visit. */
+      readonly ordinal?: number | undefined;
+      readonly agent: string;
+      /** Exact task body sent after the private child-policy envelope. */
+      readonly task: string;
+      readonly taskTruncated?: true | undefined;
+      readonly omittedTaskChars?: number | undefined;
+      readonly startedAt: number;
+      readonly transcript?: SubagentTranscriptReference | undefined;
+      readonly result?: StepAttemptResult | undefined;
+      readonly gateDecision?: StepGateDecision | undefined;
+    };
+
 export type StepHistoryEntry = {
   readonly stepId: string;
   readonly stepDigest: string;
   readonly outcome: string;
   readonly summary: string;
+  /** Canonical execution directory selected by this completed step. */
+  readonly workspaceCwd?: string | undefined;
+  /** Artifact projection paired exactly with `approval` on approved gates. */
+  readonly artifact?: string | undefined;
+  /** Complete approval provenance for a newly completed gate step. */
+  readonly approval?: GateApproval | undefined;
+  /** Durable execution evidence for every attempt of this completed step. */
+  readonly attempts?: ReadonlyArray<StepExecutionAttempt> | undefined;
+  /** Older attempts compacted to keep the checkpoint bounded. */
+  readonly omittedAttempts?: number | undefined;
   readonly completedAt: number;
 };
 
@@ -22,8 +114,8 @@ export type PendingGate = {
   readonly requestId: string;
   readonly stepId: string;
   readonly artifact: string;
-  /** Legacy v1 field. New runs use the reviewed artifact as the handoff. */
-  summary?: string | undefined;
+  /** Compact step handoff kept separate from the opaque review artifact. */
+  readonly summary?: string | undefined;
   readonly submittedOutcome: string;
   readonly requestedAt: number;
   readonly reviewId?: string | undefined;
@@ -42,15 +134,24 @@ export type WorkflowRun = {
   readonly baselineTools: ReadonlyArray<string>;
   readonly visits: Readonly<Record<string, number>>;
   readonly history: ReadonlyArray<StepHistoryEntry>;
+  /** Attempts for the current, not-yet-completed step. */
+  readonly currentStepAttempts?:
+    ReadonlyArray<StepExecutionAttempt> | undefined;
+  /** Older current-step attempts compacted from the checkpoint. */
+  readonly currentStepOmittedAttempts?: number | undefined;
   readonly startedAt: number;
   readonly updatedAt: number;
   /**
-   * Most recent human-approved gate artifact. This is the only provenance
-   * source from which reviewed Bash capabilities may be derived.
+   * Most recent human-approved gate artifact. The workflow prompt decides how
+   * to interpret this opaque value.
    */
   readonly reviewedArtifact?: string | undefined;
-  /** Final feedback paired with the immutable approved artifact. */
+  /** Final feedback paired with the approved artifact. */
   readonly reviewedFeedback?: string | undefined;
+  /** Immutable working directory captured when the workflow started. */
+  readonly startCwd?: string | undefined;
+  /** Current canonical execution directory for delegated workflow steps. */
+  readonly cwd?: string | undefined;
   /**
    * Input inherited from the previous completed step. Unlike `lastSummary`,
    * this survives a paused attempt of the current step.
@@ -58,6 +159,8 @@ export type WorkflowRun = {
   readonly stepHandoff?: string | undefined;
   readonly lastSummary: string;
   readonly gateFeedback: string;
+  /** User-authored guidance supplied for the current resume attempt. */
+  readonly resumeInput?: string | undefined;
   readonly pauseReason?: string | undefined;
   readonly pausedFrom?: 'running' | 'awaiting-gate' | undefined;
   /** Current step when execution failed and was paused for a resumable retry. */

package/src/engine/state.ts

@@ -1,10 +1,24 @@
 export { createRun } from './create-run.ts';
 export { isWorkflowRun } from './run-validation.ts';
-export { RUN_STATE_VERSION } from './state-types.ts';
+export {
+  MAX_RESUME_INPUT_CHARS,
+  MAX_STEP_TRACE_ATTEMPTS,
+  MAX_STEP_TRACE_LOG_CHARS,
+  MAX_STEP_TRACE_LOG_EVENT_CHARS,
+  MAX_STEP_TRACE_LOG_EVENTS,
+  MAX_STEP_TRACE_TASK_CHARS,
+  MAX_WORKFLOW_TRACE_CHARS,
+  RUN_STATE_VERSION,
+} from './state-types.ts';
 export type {
+  GateApproval,
   GateResolution,
   PendingGate,
+  StepAttemptResult,
+  StepExecutionAttempt,
+  StepGateDecision,
   StepHistoryEntry,
+  SubagentTranscriptReference,
   WorkflowRun,
   WorkflowRunStatus,
 } from './state-types.ts';

package/src/engine/step-trace.ts

@@ -0,0 +1,495 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import { redactStepLogText } from '../step-log.ts';
+import {
+  MAX_STEP_TRACE_ARTIFACT_CHARS,
+  MAX_STEP_TRACE_ATTEMPTS,
+  MAX_STEP_TRACE_LOG_CHARS,
+  MAX_STEP_TRACE_LOG_EVENTS,
+  MAX_STEP_TRACE_SUMMARY_CHARS,
+  MAX_STEP_TRACE_TASK_CHARS,
+  MAX_WORKFLOW_TRACE_CHARS,
+  type StepAttemptResult,
+  type StepExecutionAttempt,
+  type StepGateDecision,
+  type SubagentTranscriptReference,
+  type WorkflowRun,
+} from './state-types.ts';
+
+type CompactedTask = {
+  readonly task: string;
+  readonly taskTruncated?: true;
+  readonly omittedTaskChars?: number;
+};
+
+const COMPACTED_FIELD_CHARS = 512;
+const COMPACTED_LOG_CHARS = 4_096;
+
+type CompactedLog = {
+  readonly log?: ReadonlyArray<string>;
+  readonly logTruncated?: true;
+  readonly omittedLogEvents?: number;
+};
+
+function logChars(lines: ReadonlyArray<string> | undefined): number {
+  return lines?.reduce((total, line) => total + line.length, 0) ?? 0;
+}
+
+function attemptSize(attempt: StepExecutionAttempt): number {
+  return (
+    attempt.requestId.length +
+    attempt.task.length +
+    (attempt.kind === 'subagent' ? attempt.agent.length : 0) +
+    (attempt.kind === 'main' ? logChars(attempt.log) : 0) +
+    (attempt.result?.outcome.length ?? 0) +
+    (attempt.result?.summary.length ?? 0) +
+    (attempt.result?.artifact?.length ?? 0) +
+    (attempt.result?.workspaceCwd?.length ?? 0) +
+    (attempt.kind === 'subagent'
+      ? (attempt.transcript?.trustedRoot.length ?? 0) +
+        (attempt.transcript?.sessionFile.length ?? 0) +
+        (attempt.transcript?.runId.length ?? 0)
+      : 0) +
+    (attempt.gateDecision?.requestId.length ?? 0) +
+    (attempt.gateDecision?.feedback.length ?? 0) +
+    (attempt.gateDecision?.reviewId?.length ?? 0)
+  );
+}
+
+function compactMainLog(attempt: StepExecutionAttempt): CompactedLog {
+  if (attempt.kind !== 'main' || !attempt.log) return {};
+  const retained: Array<string> = [];
+  let chars = 0;
+  for (const line of attempt.log) {
+    if (chars + line.length > COMPACTED_LOG_CHARS) break;
+    retained.push(line);
+    chars += line.length;
+  }
+  const newlyOmitted = attempt.log.length - retained.length;
+  const omittedLogEvents = (attempt.omittedLogEvents ?? 0) + newlyOmitted;
+  return {
+    log: retained,
+    ...(attempt.logTruncated || omittedLogEvents > 0
+      ? { logTruncated: true, omittedLogEvents }
+      : {}),
+  };
+}
+
+function compactAttempt(attempt: StepExecutionAttempt): StepExecutionAttempt {
+  const task = attempt.task.slice(0, COMPACTED_FIELD_CHARS);
+  const removedTaskChars = attempt.task.length - task.length;
+  const result = attempt.result
+    ? {
+        ...attempt.result,
+        summary: attempt.result.summary.slice(0, COMPACTED_FIELD_CHARS),
+        ...(attempt.result.summary.length > COMPACTED_FIELD_CHARS
+          ? { summaryTruncated: true as const }
+          : {}),
+        ...(attempt.result.artifact !== undefined
+          ? {
+              artifact: attempt.result.artifact.slice(0, COMPACTED_FIELD_CHARS),
+              ...(attempt.result.artifact.length > COMPACTED_FIELD_CHARS
+                ? { artifactTruncated: true as const }
+                : {}),
+            }
+          : {}),
+      }
+    : undefined;
+  const gateDecision = attempt.gateDecision
+    ? {
+        ...attempt.gateDecision,
+        feedback: attempt.gateDecision.feedback.slice(0, COMPACTED_FIELD_CHARS),
+        ...(attempt.gateDecision.feedback.length > COMPACTED_FIELD_CHARS
+          ? { feedbackTruncated: true as const }
+          : {}),
+      }
+    : undefined;
+  const compactedLog = compactMainLog(attempt);
+  return {
+    ...attempt,
+    task,
+    ...(attempt.taskTruncated || removedTaskChars > 0
+      ? {
+          taskTruncated: true as const,
+          omittedTaskChars: (attempt.omittedTaskChars ?? 0) + removedTaskChars,
+        }
+      : {}),
+    ...(result ? { result } : {}),
+    ...(gateDecision ? { gateDecision } : {}),
+    ...(attempt.kind === 'main' && attempt.log ? compactedLog : {}),
+  };
+}
+
+/** Returns the bounded checkpoint payload attributable to step traces. */
+export function workflowTraceChars(run: WorkflowRun): number {
+  return [
+    ...run.history.flatMap((entry) => entry.attempts ?? []),
+    ...(run.currentStepAttempts ?? []),
+  ].reduce((total, attempt) => total + attemptSize(attempt), 0);
+}
+
+function compactRunTraceBudget(run: WorkflowRun): WorkflowRun {
+  let remaining = workflowTraceChars(run);
+  if (remaining <= MAX_WORKFLOW_TRACE_CHARS) return run;
+
+  const compactAttempts = (
+    values: ReadonlyArray<StepExecutionAttempt>,
+  ): Array<StepExecutionAttempt> => {
+    const attempts = [...values];
+    for (let index = 0; index < attempts.length; index += 1) {
+      if (remaining <= MAX_WORKFLOW_TRACE_CHARS) break;
+      const attempt = attempts[index];
+      if (!attempt) continue;
+      const compacted = compactAttempt(attempt);
+      remaining -= attemptSize(attempt) - attemptSize(compacted);
+      attempts[index] = compacted;
+    }
+    return attempts;
+  };
+  const history = run.history.map((entry) =>
+    entry.attempts
+      ? { ...entry, attempts: compactAttempts(entry.attempts) }
+      : entry,
+  );
+  const currentStepAttempts = [...(run.currentStepAttempts ?? [])];
+  const compactedCurrent = compactAttempts(currentStepAttempts);
+  for (let index = 0; index < history.length; index += 1) {
+    if (remaining <= MAX_WORKFLOW_TRACE_CHARS) break;
+    const entry = history[index];
+    if (!entry?.attempts || entry.attempts.length <= 1) continue;
+    const attempts = [...entry.attempts];
+    let omittedAttempts = entry.omittedAttempts ?? 0;
+    while (remaining > MAX_WORKFLOW_TRACE_CHARS && attempts.length > 2) {
+      const removed = attempts.splice(1, 1)[0];
+      if (removed) remaining -= attemptSize(removed);
+      omittedAttempts += 1;
+    }
+    history[index] = { ...entry, attempts, omittedAttempts };
+  }
+  let currentOmittedAttempts = run.currentStepOmittedAttempts ?? 0;
+  while (remaining > MAX_WORKFLOW_TRACE_CHARS && compactedCurrent.length > 2) {
+    const removed = compactedCurrent.splice(1, 1)[0];
+    if (removed) remaining -= attemptSize(removed);
+    currentOmittedAttempts += 1;
+  }
+  for (let index = 0; index < history.length; index += 1) {
+    if (remaining <= MAX_WORKFLOW_TRACE_CHARS) break;
+    const entry = history[index];
+    if (!entry?.attempts || entry.attempts.length === 0) continue;
+    const attempts = [...entry.attempts];
+    let omittedAttempts = entry.omittedAttempts ?? 0;
+    while (remaining > MAX_WORKFLOW_TRACE_CHARS && attempts.length > 0) {
+      const removed = attempts.shift();
+      if (removed) remaining -= attemptSize(removed);
+      omittedAttempts += 1;
+    }
+    history[index] = { ...entry, attempts, omittedAttempts };
+  }
+  while (remaining > MAX_WORKFLOW_TRACE_CHARS && compactedCurrent.length > 0) {
+    const removed = compactedCurrent.shift();
+    if (removed) remaining -= attemptSize(removed);
+    currentOmittedAttempts += 1;
+  }
+
+  return {
+    ...run,
+    history,
+    ...(run.currentStepAttempts
+      ? { currentStepAttempts: compactedCurrent }
+      : {}),
+    ...(currentOmittedAttempts > 0
+      ? { currentStepOmittedAttempts: currentOmittedAttempts }
+      : {}),
+  };
+}
+
+function compactTask(task: string): CompactedTask {
+  if (task.length <= MAX_STEP_TRACE_TASK_CHARS) return { task };
+  return {
+    task: task.slice(0, MAX_STEP_TRACE_TASK_CHARS),
+    taskTruncated: true,
+    omittedTaskChars: task.length - MAX_STEP_TRACE_TASK_CHARS,
+  };
+}
+
+function appendAttempt(
+  run: WorkflowRun,
+  attempt: StepExecutionAttempt,
+  now: number,
+): WorkflowRun {
+  if (
+    run.currentStepAttempts?.some(
+      (candidate) => candidate.requestId === attempt.requestId,
+    )
+  ) {
+    return run;
+  }
+  const existing = run.currentStepAttempts ?? [];
+  const isFull = existing.length >= MAX_STEP_TRACE_ATTEMPTS;
+  const retained = isFull
+    ? [existing[0], ...existing.slice(-(MAX_STEP_TRACE_ATTEMPTS - 2))].filter(
+        (candidate): candidate is StepExecutionAttempt =>
+          candidate !== undefined,
+      )
+    : existing;
+  const omittedAttempts =
+    (run.currentStepOmittedAttempts ?? 0) + (isFull ? 1 : 0);
+  return compactRunTraceBudget({
+    ...run,
+    currentStepAttempts: [...retained, attempt],
+    ...(omittedAttempts > 0
+      ? { currentStepOmittedAttempts: omittedAttempts }
+      : {}),
+    updatedAt: now,
+  });
+}
+
+function nextAttemptOrdinal(run: WorkflowRun): number {
+  const attempts = run.currentStepAttempts ?? [];
+  const largestRecordedOrdinal = attempts.reduce(
+    (largest, attempt) => Math.max(largest, attempt.ordinal ?? 0),
+    0,
+  );
+  const attemptedCount =
+    attempts.length + (run.currentStepOmittedAttempts ?? 0);
+  return Math.max(largestRecordedOrdinal, attemptedCount) + 1;
+}
+
+/** Records the exact task supplied for one main-agent attempt. */
+export function beginMainStepAttempt(
+  run: WorkflowRun,
+  requestId: string,
+  task: string,
+  now: number,
+): WorkflowRun {
+  if (!requestId || requestId.includes('\0') || !task.trim()) return run;
+  const compacted = compactTask(task);
+  return appendAttempt(
+    run,
+    {
+      kind: 'main',
+      requestId,
+      ordinal: nextAttemptOrdinal(run),
+      ...compacted,
+      startedAt: now,
+    },
+    now,
+  );
+}
+
+/** Records the exact task body supplied for one child attempt. */
+export function beginSubagentStepAttempt(
+  run: WorkflowRun,
+  requestId: string,
+  agent: string,
+  task: string,
+  now: number,
+): WorkflowRun {
+  if (!requestId || requestId.includes('\0') || !agent || !task.trim()) {
+    return run;
+  }
+  const compacted = compactTask(task);
+  return appendAttempt(
+    run,
+    {
+      kind: 'subagent',
+      requestId,
+      ordinal: nextAttemptOrdinal(run),
+      agent,
+      ...compacted,
+      startedAt: now,
+    },
+    now,
+  );
+}
+
+/** Appends a redacted, bounded prefix of main-agent events to one exact attempt. */
+export function appendMainStepLog(
+  run: WorkflowRun,
+  requestId: string,
+  lines: ReadonlyArray<string>,
+  now: number,
+): WorkflowRun {
+  if (!requestId || requestId.includes('\0') || lines.length === 0) return run;
+  const attempts = run.currentStepAttempts;
+  if (!attempts || attempts.length === 0) return run;
+  const index = attempts.length - 1;
+  const attempt = attempts[index];
+  if (!attempt || attempt.kind !== 'main' || attempt.requestId !== requestId) {
+    return run;
+  }
+
+  const safeLines = lines
+    .map(redactStepLogText)
+    .filter((line) => line.length > 0);
+  if (safeLines.length === 0) return run;
+
+  const existing = [...(attempt.log ?? [])];
+  let chars = logChars(existing);
+  let accepted = 0;
+  if (!attempt.logTruncated) {
+    for (const line of safeLines) {
+      if (
+        existing.length >= MAX_STEP_TRACE_LOG_EVENTS ||
+        chars + line.length > MAX_STEP_TRACE_LOG_CHARS
+      ) {
+        break;
+      }
+      existing.push(line);
+      chars += line.length;
+      accepted += 1;
+    }
+  }
+  const newlyOmitted = safeLines.length - accepted;
+  const omittedLogEvents = (attempt.omittedLogEvents ?? 0) + newlyOmitted;
+  const currentStepAttempts = [...attempts];
+  currentStepAttempts[index] = {
+    ...attempt,
+    log: existing,
+    ...(attempt.logTruncated || omittedLogEvents > 0
+      ? { logTruncated: true, omittedLogEvents }
+      : {}),
+  };
+  return compactRunTraceBudget({
+    ...run,
+    currentStepAttempts,
+    updatedAt: now,
+  });
+}
+
+function isSafeTranscriptReference(
+  reference: SubagentTranscriptReference,
+): boolean {
+  if (
+    !isAbsolute(reference.trustedRoot) ||
+    !isAbsolute(reference.sessionFile) ||
+    reference.trustedRoot.includes('\0') ||
+    reference.sessionFile.includes('\0') ||
+    !reference.runId ||
+    reference.runId.includes('\0') ||
+    reference.runId.includes('/') ||
+    reference.runId.includes('\\') ||
+    reference.runId === '.' ||
+    reference.runId === '..' ||
+    !Number.isSafeInteger(reference.childIndex) ||
+    reference.childIndex < 0
+  ) {
+    return false;
+  }
+  const expected = resolve(
+    reference.trustedRoot,
+    reference.runId,
+    `run-${reference.childIndex}`,
+    'session.jsonl',
+  );
+  const relativePath = relative(
+    resolve(reference.trustedRoot),
+    resolve(reference.sessionFile),
+  );
+  const isWithinTrustedRoot =
+    relativePath !== '' &&
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath);
+  return isWithinTrustedRoot && resolve(reference.sessionFile) === expected;
+}
+
+/**
+ * Attaches a lexically confined child transcript reference to its attempt.
+ *
+ * The status reader repeats this check and then verifies real paths, file type,
+ * no-follow opening, and a stable bounded read before displaying anything.
+ */
+export function attachSubagentTranscript(
+  run: WorkflowRun,
+  requestId: string,
+  reference: SubagentTranscriptReference,
+  now: number,
+): WorkflowRun {
+  if (!isSafeTranscriptReference(reference)) return run;
+  const attempts = run.currentStepAttempts;
+  const index = attempts?.findIndex(
+    (attempt) => attempt.requestId === requestId && attempt.kind === 'subagent',
+  );
+  if (index === undefined || index < 0 || !attempts) return run;
+  const currentStepAttempts = [...attempts];
+  const attempt = currentStepAttempts[index];
+  if (!attempt || attempt.kind !== 'subagent') return run;
+  currentStepAttempts[index] = { ...attempt, transcript: reference };
+  return compactRunTraceBudget({ ...run, currentStepAttempts, updatedAt: now });
+}
+
+function attemptResult(
+  result: WorkflowStepResult,
+  workspaceCwd?: string,
+): StepAttemptResult {
+  const summary = result.summary.slice(0, MAX_STEP_TRACE_SUMMARY_CHARS);
+  const artifact = result.artifact?.slice(0, MAX_STEP_TRACE_ARTIFACT_CHARS);
+  return {
+    outcome: result.outcome,
+    summary,
+    ...(summary.length < result.summary.length
+      ? { summaryTruncated: true as const }
+      : {}),
+    ...(artifact !== undefined ? { artifact } : {}),
+    ...(artifact !== undefined &&
+    artifact.length < (result.artifact?.length ?? 0)
+      ? { artifactTruncated: true as const }
+      : {}),
+    ...(workspaceCwd ? { workspaceCwd } : {}),
+  };
+}
+
+/** Stores the submitted result on the latest attempt before transition. */
+export function recordCurrentStepResult(
+  run: WorkflowRun,
+  result: WorkflowStepResult,
+  now: number,
+  workspaceCwd?: string,
+): WorkflowRun {
+  const attempts = run.currentStepAttempts;
+  if (!attempts || attempts.length === 0) return run;
+  const index = attempts.length - 1;
+  const latest = attempts[index];
+  if (!latest) return run;
+  const currentStepAttempts = [...attempts];
+  currentStepAttempts[index] = {
+    ...latest,
+    result: attemptResult(result, workspaceCwd),
+  };
+  return compactRunTraceBudget({
+    ...run,
+    currentStepAttempts,
+    updatedAt: now,
+  });
+}
+
+/** Durably pairs a human gate decision with the attempt it reviewed. */
+export function recordCurrentGateDecision(
+  run: WorkflowRun,
+  decision: StepGateDecision,
+  now: number,
+): WorkflowRun {
+  const attempts = run.currentStepAttempts;
+  if (!attempts || attempts.length === 0) return run;
+  const index = attempts.length - 1;
+  const latest = attempts[index];
+  if (!latest) return run;
+  const feedback = decision.feedback.slice(0, MAX_STEP_TRACE_SUMMARY_CHARS);
+  const currentStepAttempts = [...attempts];
+  currentStepAttempts[index] = {
+    ...latest,
+    gateDecision: {
+      ...decision,
+      feedback,
+      ...(feedback.length < decision.feedback.length
+        ? { feedbackTruncated: true }
+        : {}),
+    },
+  };
+  return compactRunTraceBudget({
+    ...run,
+    currentStepAttempts,
+    updatedAt: now,
+  });
+}

package/src/engine/transitions.ts

@@ -12,6 +12,7 @@ export {
   failRun,
   pauseRun,
   resumeRun,
+  setResumeInput,
 } from './run-lifecycle.ts';
 export { reconcileRun } from './run-reconciliation.ts';
 export type { ReconcileResult } from './transition-types.ts';