@mcrescenzo/opencode-workflows 0.1.0

package/workflow-kernel/notification-toast.js

@@ -0,0 +1,287 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
+import {
+  WORKFLOW_PROGRESS_TOAST_FORCE_MS,
+  WORKFLOW_PROGRESS_TOAST_INTERVAL_MS,
+  WORKFLOW_TOAST_DURATION_MS,
+} from "./constants.js";
+import { stableStringify, truncateText } from "./text-json.js";
+import { redactFreeTextSecrets } from "./free-text-redactor.js";
+import { addTokens, zeroTokens } from "./budget-accounting.js";
+import {
+  renderWorkflowApplyCard,
+  renderWorkflowHeartbeatCard,
+  renderWorkflowProblemCard,
+  renderWorkflowTerminalCard,
+  workflowToastCardSignature,
+  workflowToastCardSnapshot,
+} from "./notification-toast-cards.js";
+import {
+  createWorkflowToastPolicyState,
+  evaluateWorkflowToastEventPolicy,
+  evaluateWorkflowToastTickPolicy,
+} from "./notification-toast-policy.js";
+
+const WORKFLOW_TOAST_MESSAGE_MAX_CHARS = 1_000;
+
+const WORKFLOW_TOAST_MAX_LANES = 4;
+
+const WORKFLOW_TOAST_DELIVERY_TIMEOUT_MS = 1_000;
+
+const activeToastDeliveries = new WeakSet();
+
+function hasWorkflowToast(pluginContext) {
+  return typeof pluginContext.client?.tui?.showToast === "function" || typeof pluginContext.tui?.ui?.toast === "function";
+}
+
+async function showToast(pluginContext, variant, title, message) {
+  try {
+    const body = {
+      variant,
+      title: truncateText(redactFreeTextSecrets(title), 120),
+      message: truncateText(redactFreeTextSecrets(message), WORKFLOW_TOAST_MESSAGE_MAX_CHARS),
+      duration: WORKFLOW_TOAST_DURATION_MS,
+    };
+    const timeoutMs = Number.isFinite(pluginContext.__workflowToastTimeoutMs) ? pluginContext.__workflowToastTimeoutMs : WORKFLOW_TOAST_DELIVERY_TIMEOUT_MS;
+    if (typeof pluginContext.client?.tui?.showToast === "function") {
+      if (activeToastDeliveries.has(pluginContext)) return;
+      activeToastDeliveries.add(pluginContext);
+      const ac = new AbortController();
+      const delivery = Promise.resolve(pluginContext.client.tui.showToast({ body, signal: ac.signal })).catch(() => {}).finally(() => {
+        activeToastDeliveries.delete(pluginContext);
+        ac.abort();
+      });
+      await Promise.race([
+        delivery,
+        sleep(timeoutMs, undefined, { signal: ac.signal }).then(() => ac.abort()).catch(() => {}),
+      ]);
+      return;
+    }
+    pluginContext.tui?.ui?.toast?.(body);
+  } catch {
+    // Toasts are best effort; persisted state remains authoritative.
+  }
+}
+
+function workflowDisplayName(run) {
+  const name = typeof run.meta?.name === "string" ? run.meta.name.trim() : "";
+  return name || "unnamed";
+}
+
+function workflowQueuedAgents(run) {
+  return run.waitingAgents?.length ?? run.queuedAgents ?? 0;
+}
+
+function workflowTotalCost(run) {
+  const cost = Number(run.cost ?? 0) + Number(run.replayedCost ?? 0);
+  return Number.isFinite(cost) ? cost : 0;
+}
+
+function workflowCostLabel(run) {
+  return workflowTotalCost(run).toFixed(4).replace(/\.?0+$/, "") || "0";
+}
+
+function workflowTotalTokens(run) {
+  const total = addTokens(run.tokens ?? zeroTokens(), run.replayedTokens ?? zeroTokens());
+  return (total.input ?? 0) + (total.output ?? 0) + (total.reasoning ?? 0);
+}
+
+function compactDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "-";
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h${minutes % 60}m`;
+}
+
+function laneRecordsForRun(run) {
+  if (run.laneRecords instanceof Map) return [...run.laneRecords.values()];
+  if (Array.isArray(run.laneRecords)) return run.laneRecords;
+  return [];
+}
+
+function lanePriority(lane) {
+  if (lane.status === "running" || lane.status === "committed") return 0;
+  if (["failure", "timeout", "cancelled", "budget_stopped"].includes(lane.outcome) || ["failure", "timeout", "cancelled", "budget_stopped"].includes(lane.status)) return 1;
+  if (lane.status === "completed") return 2;
+  return 3;
+}
+
+function shortModel(model) {
+  const text = String(model || "model?");
+  return truncateText(text.split("/").pop() || text, 18);
+}
+
+function laneRuntimeLabel(lane, now) {
+  const start = Date.parse(lane.startedAt ?? "");
+  const end = Date.parse(lane.completedAt ?? "");
+  if (Number.isFinite(start) && Number.isFinite(end)) return compactDuration(end - start);
+  if (Number.isFinite(start)) return compactDuration(now - start);
+  return "-";
+}
+
+function workflowToastSnapshot(run, options = {}) {
+  return workflowToastCardSnapshot(run, options);
+}
+
+function workflowBudgetLabel(snapshot) {
+  if (Number.isFinite(snapshot.budgetPercent)) return ` budget=${snapshot.budgetPercent}%`;
+  const labels = [];
+  const maxCost = snapshot.budgetCeilings?.maxCost;
+  if (Number.isFinite(maxCost) && maxCost > 0) labels.push(`cost ${Math.round((Number(snapshot.cost) / maxCost) * 100)}%`);
+  const maxTokens = snapshot.budgetCeilings?.maxTokens;
+  if (Number.isFinite(maxTokens) && maxTokens > 0) labels.push(`tok ${Math.round((snapshot.tokens / maxTokens) * 100)}%`);
+  return labels.length ? ` budget=${labels.join(",")}` : "";
+}
+
+function workflowToastMessage(snapshot, options = {}) {
+  const maxChars = Number.isFinite(options.maxChars) ? options.maxChars : WORKFLOW_TOAST_MESSAGE_MAX_CHARS;
+  return truncateText(redactFreeTextSecrets(renderWorkflowHeartbeatCard(snapshot, options).message), maxChars);
+}
+
+function workflowPhaseLabel(run) {
+  const phase = run.currentPhase ? String(run.currentPhase) : "-";
+  const phases = Array.isArray(run.meta?.phases) ? run.meta.phases.map((item) => String(item)) : [];
+  if (phase === "-" || phases.length === 0) return phase;
+  const index = phases.indexOf(phase);
+  return index >= 0 ? `${phase}(${index + 1}/${phases.length})` : phase;
+}
+
+function workflowProgressToastMessage(run) {
+  return workflowToastMessage(workflowToastSnapshot(run));
+}
+
+function workflowHeartbeatToastCard(run, options = {}) {
+  return renderWorkflowHeartbeatCard(workflowToastSnapshot(run, options), options);
+}
+
+// Preserve exported aliases while keeping one canonical message formatter.
+const workflowStartToastMessage = workflowProgressToastMessage;
+
+function workflowTerminalToastMessage(run, options = {}) {
+  return renderWorkflowTerminalCard(workflowToastSnapshot(run, options), options).message;
+}
+
+function workflowTerminalToastCard(run, options = {}) {
+  return renderWorkflowTerminalCard(workflowToastSnapshot(run, options), options);
+}
+
+function workflowApplyToastCard(run, options = {}) {
+  return renderWorkflowApplyCard(workflowToastSnapshot(run, options), options);
+}
+
+function workflowProgressToastSignature(run) {
+  return workflowToastCardSignature(workflowToastSnapshot(run));
+}
+
+function workflowToastOptions(pluginContext) {
+  return { ascii: pluginContext?.__workflowToastAscii === true };
+}
+
+function workflowToastPolicyState(run) {
+  run.toastPolicyState ??= createWorkflowToastPolicyState();
+  return run.toastPolicyState;
+}
+
+function renderWorkflowToastDecision(decision, pluginContext) {
+  const options = workflowToastOptions(pluginContext);
+  if (decision.card === "heartbeat") return renderWorkflowHeartbeatCard(decision.snapshot, options);
+  if (decision.card === "problem") return renderWorkflowProblemCard(decision.snapshot, decision.problem, options);
+  return undefined;
+}
+
+async function deliverWorkflowToastDecisions(pluginContext, decisions) {
+  let delivered = false;
+  for (const decision of decisions) {
+    const card = renderWorkflowToastDecision(decision, pluginContext);
+    if (!card) continue;
+    await showToast(pluginContext, card.variant, card.title, card.message);
+    delivered = true;
+  }
+  return delivered;
+}
+
+function createWorkflowToastEventSink(pluginContext, run, options = {}) {
+  if (!hasWorkflowToast(pluginContext)) return undefined;
+  return async (event) => {
+    if (run.status !== "running") return;
+    const now = Number.isFinite(options.now) ? options.now : Date.now();
+    const snapshot = workflowToastSnapshot(run, { now });
+    const decisions = evaluateWorkflowToastEventPolicy(workflowToastPolicyState(run), event, snapshot, {
+      now,
+      forceMs: options.forceMs,
+      problemCooldownMs: options.problemCooldownMs,
+      signature: workflowToastCardSignature(snapshot),
+    });
+    await deliverWorkflowToastDecisions(pluginContext, decisions);
+  };
+}
+
+async function maybeShowWorkflowProgressToast(pluginContext, run, options = {}) {
+  if (run.status !== "running") return false;
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const forceMs = Number.isFinite(options.forceMs) && options.forceMs > 0 ? options.forceMs : WORKFLOW_PROGRESS_TOAST_FORCE_MS;
+  const snapshot = workflowToastSnapshot(run, { now });
+  const signature = workflowToastCardSignature(snapshot);
+  const decisions = evaluateWorkflowToastTickPolicy(workflowToastPolicyState(run), snapshot, {
+    now,
+    forceMs,
+    problemCooldownMs: options.problemCooldownMs,
+    signature,
+  });
+  if (decisions.length === 0) return false;
+  if (decisions.some((decision) => decision.card === "heartbeat")) {
+    run.lastProgressToastSignature = signature;
+    run.lastProgressToastAt = now;
+  }
+  return await deliverWorkflowToastDecisions(pluginContext, decisions);
+}
+
+function startWorkflowProgressToasts(pluginContext, run, options = {}) {
+  if (!hasWorkflowToast(pluginContext)) return () => {};
+  const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0 ? options.intervalMs : WORKFLOW_PROGRESS_TOAST_INTERVAL_MS;
+  const forceMs = Number.isFinite(options.forceMs) && options.forceMs > 0 ? options.forceMs : WORKFLOW_PROGRESS_TOAST_FORCE_MS;
+  const timer = setInterval(() => {
+    void maybeShowWorkflowProgressToast(pluginContext, run, { forceMs }).catch(() => {
+      // Progress toasts are best effort and must not affect workflow execution.
+    });
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+export {
+  WORKFLOW_TOAST_MESSAGE_MAX_CHARS,
+  WORKFLOW_TOAST_MAX_LANES,
+  WORKFLOW_TOAST_DELIVERY_TIMEOUT_MS,
+  hasWorkflowToast,
+  showToast,
+  workflowDisplayName,
+  workflowQueuedAgents,
+  workflowTotalCost,
+  workflowCostLabel,
+  workflowTotalTokens,
+  compactDuration,
+  laneRecordsForRun,
+  lanePriority,
+  shortModel,
+  laneRuntimeLabel,
+  workflowToastSnapshot,
+  workflowBudgetLabel,
+  workflowToastMessage,
+  workflowPhaseLabel,
+  workflowStartToastMessage,
+  workflowHeartbeatToastCard,
+  workflowProgressToastMessage,
+  workflowTerminalToastMessage,
+  workflowTerminalToastCard,
+  workflowApplyToastCard,
+  workflowProgressToastSignature,
+  createWorkflowToastEventSink,
+  renderWorkflowToastDecision,
+  deliverWorkflowToastDecisions,
+  maybeShowWorkflowProgressToast,
+  startWorkflowProgressToasts,
+};

package/workflow-kernel/path-policy.js

@@ -0,0 +1,219 @@
+import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+
+export const DEFAULT_SECRET_GLOBS = [
+  "**/.env",
+  "**/.env.*",
+  ".env",
+  ".env.*",
+  "**/.aws/credentials",
+  "**/.aws/config",
+  "**/.kube/config",
+  "**/.ssh/id_ecdsa",
+  "**/.ssh/id_dsa",
+  "**/.netrc",
+  "**/.pgpass",
+  "**/.config/gcloud/credentials.db",
+  "**/.docker/config.json",
+  "**/*.pem",
+  "**/*.key",
+  "**/*credentials*",
+  "**/*secret*",
+  "**/id_rsa",
+  "**/id_ed25519",
+];
+
+const CONTROL_PATH_SEGMENTS = new Set([".git", ".opencode"]);
+
+// O_NOFOLLOW guarantees only that the *final* path component is not a symlink.
+// O_DIRECTORY makes the open fail unless the component resolves to a directory.
+const NOFOLLOW_DIR_FLAGS = fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_DIRECTORY;
+// Create-or-truncate the final file, but refuse to follow a symlink at the final
+// component. A swapped-in symlink (e.g. target replaced by a link to /etc/passwd)
+// makes this open fail with ELOOP/ENOTDIR instead of redirecting the write.
+const NOFOLLOW_WRITE_FLAGS =
+  fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW;
+
+function escapeRegex(value) {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+export function normalizePolicyPath(filePath) {
+  return String(filePath ?? "").replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+
+function globToRegExp(glob) {
+  const pattern = normalizePolicyPath(glob);
+  let output = "^";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+    if (char === "*" && next === "*") {
+      const after = pattern[index + 2];
+      if (after === "/") {
+        output += "(?:.*/)?";
+        index += 2;
+      } else {
+        output += ".*";
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "*") {
+      output += "[^/]*";
+      continue;
+    }
+    if (char === "?") {
+      output += "[^/]";
+      continue;
+    }
+    output += escapeRegex(char);
+  }
+  return new RegExp(`${output}$`, "i");
+}
+
+export function matchesPolicyGlob(relativePath, glob) {
+  return globToRegExp(glob).test(normalizePolicyPath(relativePath));
+}
+
+export function protectedPathReason(relativePath, options = {}) {
+  const normalized = normalizePolicyPath(relativePath);
+  const segments = normalized.split("/");
+  if (segments.some((segment) => CONTROL_PATH_SEGMENTS.has(segment.toLowerCase()))) return "control-path";
+  const secretGlobs = Array.isArray(options.secretGlobs) ? options.secretGlobs : DEFAULT_SECRET_GLOBS;
+  if (secretGlobs.some((glob) => matchesPolicyGlob(normalized, glob))) return "secret-path";
+  return undefined;
+}
+
+export function assertWritableWorkflowPath(relativePath, options = {}) {
+  const reason = protectedPathReason(relativePath, options);
+  if (reason) throw new Error(`Patch target is protected (${reason}): ${relativePath}`);
+}
+
+export function pathContains(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+// Resolve the real path that an *already-open* file descriptor points at, so we can
+// re-confirm containment against the kernel's view of where the fd actually landed
+// (after all symlink/.. resolution) rather than re-resolving a path string that an
+// attacker could swap again. Linux exposes this via /proc/self/fd/<fd>.
+async function fdRealPath(handle) {
+  try {
+    return await fs.readlink(`/proc/self/fd/${handle.fd}`);
+  } catch {
+    return undefined;
+  }
+}
+
+async function requiredFdRealPath(handle, target) {
+  const real = await fdRealPath(handle);
+  if (real === undefined) {
+    throw new Error(`Patch write requires fd realpath support for TOCTOU-safe containment: ${target}`);
+  }
+  return real;
+}
+
+// TOCTOU-safe write for a workflow patch target.
+//
+// validatePatchTargets lstat-checks ancestors + target up front, but the write
+// happens later; a concurrent local actor with tree-write access can swap a
+// validated dir/file for a symlink to /etc between validation and write, landing
+// the write outside `root` (R18 / opencode-workflows-994). The per-run advisory
+// lock does not protect against external processes.
+//
+// Defense, immediately at write time (no exploitable window):
+//   1. Re-validate each ancestor directory with O_NOFOLLOW|O_DIRECTORY opens, and
+//      confirm each opened dir fd's real path still lies inside `root`. A swapped-in
+//      ancestor symlink makes its O_NOFOLLOW open fail (ELOOP/ENOTDIR); a redirected
+//      ancestor makes the fd realpath escape `root`.
+//   2. Open the final component with O_NOFOLLOW|O_CREAT|O_WRONLY|O_TRUNC so a
+//      symlinked final component is rejected at open (it is never followed).
+//   3. Open-then-validate-fd: re-confirm the opened *target* fd's real path is still
+//      inside `root` before writing a byte; bail (and close) on any escape.
+//   4. Write + fsync-free flush through that exact fd — never re-resolving the path.
+export async function safeWriteFileWithinRoot(root, target, content) {
+  const rootReal = await fs.realpath(root);
+  let rootHandle;
+  try {
+    rootHandle = await fs.open(rootReal, NOFOLLOW_DIR_FLAGS);
+    const real = await requiredFdRealPath(rootHandle, target);
+    if (!pathContains(rootReal, real)) throw new Error(`Patch root escapes primary root: ${target}`);
+  } finally {
+    await rootHandle?.close();
+  }
+  // Resolve the target against the *realpathed* root, not the raw `root`. Call sites
+  // derive root via path.resolve(context.worktree||directory), which normalizes ./..
+  // but does NOT resolve symlinks, so when the apply root has a symlinked ancestor
+  // (macOS /tmp->/private/tmp, symlinked $HOME/worktree parent — see
+  // tests/drain-runtime.test.mjs R15 and worktree-adapter realpath handling) the
+  // un-realpathed targetAbs would diverge from rootReal and the containment check
+  // below would reject every legitimate write (R18-followup / opencode-workflows-2gs).
+  // Resolving against rootReal keeps the .. / absolute-target escape check intact
+  // (path.resolve still collapses ../ and absolute targets) while letting legit
+  // nested writes through under a symlinked-ancestor root.
+  const targetAbs = path.resolve(rootReal, target);
+  if (!pathContains(rootReal, targetAbs)) {
+    throw new Error(`Patch target escapes primary root: ${target}`);
+  }
+
+  // Walk + create ancestors with O_NOFOLLOW dir opens so no ancestor component can be
+  // a freshly swapped-in symlink redirecting the write tree.
+  const relParts = path.relative(rootReal, targetAbs).split(path.sep).filter(Boolean);
+  if (relParts.length === 0) {
+    throw new Error(`Patch target must name a file: ${target}`);
+  }
+  const dirParts = relParts.slice(0, -1);
+  let currentReal = rootReal;
+  for (const part of dirParts) {
+    const childPath = path.join(currentReal, part);
+    let dirHandle;
+    try {
+      dirHandle = await fs.open(childPath, NOFOLLOW_DIR_FLAGS);
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        // Create the missing directory (mkdir refuses to follow/replace, and a racing
+        // symlink at this name makes the subsequent O_NOFOLLOW open below fail).
+        await fs.mkdir(childPath);
+        dirHandle = await fs.open(childPath, NOFOLLOW_DIR_FLAGS);
+      } else if (error && (error.code === "ELOOP" || error.code === "ENOTDIR")) {
+        throw new Error(`Patch ancestor is a symlink: ${target}`);
+      } else {
+        throw error;
+      }
+    }
+    try {
+      const real = await requiredFdRealPath(dirHandle, target);
+      if (!pathContains(rootReal, real)) {
+        throw new Error(`Patch ancestor escapes primary root: ${target}`);
+      }
+      currentReal = real;
+    } finally {
+      await dirHandle.close();
+    }
+  }
+
+  const finalPath = path.join(currentReal, relParts.at(-1));
+  let handle;
+  try {
+    handle = await fs.open(finalPath, NOFOLLOW_WRITE_FLAGS, 0o644);
+  } catch (error) {
+    if (error && (error.code === "ELOOP" || error.code === "ENOTDIR")) {
+      throw new Error(`Patch target is a symlink: ${target}`);
+    }
+    throw error;
+  }
+  try {
+    const real = await requiredFdRealPath(handle, target);
+    if (!pathContains(rootReal, real)) {
+      // An ancestor was redirected after our per-ancestor checks; the fd points
+      // outside root. Abort before writing a single byte.
+      throw new Error(`Patch target escapes primary root after open: ${target}`);
+    }
+    await handle.writeFile(content, "utf8");
+  } finally {
+    await handle.close();
+  }
+}

package/workflow-kernel/result-readback.js

@@ -0,0 +1,106 @@
+import {
+  MAX_INLINE_RESULT_BYTES,
+  MAX_RESULT_READBACK_BYTES,
+  MAX_RESULT_READ_FILE_BYTES,
+} from "./constants.js";
+import { redactValue } from "./text-json.js";
+
+const FULL_RESULT_REDACTION = {
+  maxDepth: Number.POSITIVE_INFINITY,
+  maxString: Number.POSITIVE_INFINITY,
+  maxArray: Number.POSITIVE_INFINITY,
+};
+
+const PARTIAL_READBACK_LIMITS = [
+  { maxDepth: Number.POSITIVE_INFINITY, maxString: 16 * 1024, maxArray: 500 },
+  { maxDepth: Number.POSITIVE_INFINITY, maxString: 8 * 1024, maxArray: 250 },
+  { maxDepth: 20, maxString: 4 * 1024, maxArray: 100 },
+  { maxDepth: 12, maxString: 2 * 1024, maxArray: 50 },
+  { maxDepth: 8, maxString: 1024, maxArray: 25 },
+  { maxDepth: 6, maxString: 600, maxArray: 10 },
+  { maxDepth: 4, maxString: 240, maxArray: 5 },
+];
+
+function normalizeJsonValue(value) {
+  return value === undefined ? null : value;
+}
+
+function jsonText(value, { pretty = false } = {}) {
+  return JSON.stringify(normalizeJsonValue(value), null, pretty ? 2 : 0);
+}
+
+function byteLength(text) {
+  return Buffer.byteLength(String(text ?? ""), "utf8");
+}
+
+function serializedBytes(value) {
+  return byteLength(jsonText(value));
+}
+
+function resultSummary(value) {
+  if (Array.isArray(value)) return { type: "array", length: value.length };
+  if (value && typeof value === "object") return { type: "object", keys: Object.keys(value).slice(0, 50) };
+  return { type: value === null ? "null" : typeof value };
+}
+
+export function redactResultValue(value, options = {}) {
+  return redactValue(value, { ...FULL_RESULT_REDACTION, ...options });
+}
+
+export function inlineResultProjection(value, { maxBytes = MAX_INLINE_RESULT_BYTES } = {}) {
+  const result = redactResultValue(value);
+  const text = jsonText(result, { pretty: true });
+  const bytes = byteLength(text);
+  if (bytes > maxBytes) return { inline: false, bytes, maxBytes };
+  return { inline: true, bytes, maxBytes, text, result };
+}
+
+export function resultReadbackProjection(value, { maxBytes = MAX_RESULT_READBACK_BYTES } = {}) {
+  const full = redactResultValue(value);
+  const fullBytes = serializedBytes(full);
+  if (fullBytes <= maxBytes) {
+    return {
+      result: full,
+      resultReadback: {
+        mode: "full",
+        truncated: false,
+        bytes: fullBytes,
+        maxBytes,
+      },
+    };
+  }
+
+  for (const limits of PARTIAL_READBACK_LIMITS) {
+    const candidate = redactResultValue(value, limits);
+    const bytes = serializedBytes(candidate);
+    if (bytes <= maxBytes) {
+      return {
+        result: candidate,
+        resultReadback: {
+          mode: "partial",
+          truncated: true,
+          bytes,
+          fullBytes,
+          maxBytes,
+          limits,
+        },
+      };
+    }
+  }
+
+  const summary = {
+    status: "truncated",
+    reason: `Result readback exceeds ${maxBytes} bytes after bounded projection`,
+    summary: resultSummary(full),
+  };
+  return {
+    result: summary,
+    resultReadback: {
+      mode: "summary",
+      truncated: true,
+      bytes: serializedBytes(summary),
+      fullBytes,
+      maxBytes,
+    },
+  };
+}