@prismatic-io/lux 0.0.1 → 0.0.2-preview.10

package/src/cli/render/reporter.ts

@@ -4,6 +4,7 @@ import {
   createToolOutcomeAccumulator,
   emptyRunUsage,
   type GradingAssertionEntry,
+  type GradingReport,
   harnessUsage,
   isUsageEmpty,
   type LifecycleStage,
@@ -77,6 +78,7 @@ type CaseView = {
   assertionTotal: number;
   currentAssertion: string | null;
   assertions: GradingAssertionEntry[];
+  skippedAssertions: NonNullable<GradingReport["skippedAssertions"]>;
   usage: RunUsage;
   /** Per-API-call agent usage, in order — the split behind `usage.agent`. */
   agentTurns: TurnUsage[];
@@ -117,7 +119,10 @@ const statusMark = (status: CaseStatus, theme: Theme): string => {
 
 const assertionTally = (view: CaseView): string => {
   const passed = view.assertions.filter((a) => a.passed).length;
-  return view.assertions.length === 0 ? "—" : `${passed}/${view.assertions.length}`;
+  const evaluated = view.assertions.length === 0 ? "—" : `${passed}/${view.assertions.length}`;
+  return view.skippedAssertions.length > 0
+    ? `${evaluated} · ${view.skippedAssertions.length} skipped`
+    : evaluated;
 };
 
 /**
@@ -233,6 +238,7 @@ export class ConsoleReporter implements SuiteObserver {
       assertionTotal: 0,
       currentAssertion: null,
       assertions: [],
+      skippedAssertions: [],
       usage: emptyRunUsage(),
       agentTurns: [],
       phaseDurationMs: null,
@@ -299,6 +305,7 @@ export class ConsoleReporter implements SuiteObserver {
     if (result.errorMessage) view.errorMessage = result.errorMessage;
     if (result.result) {
       view.assertions = result.result.grading.assertions;
+      view.skippedAssertions = result.result.grading.skippedAssertions ?? [];
       view.usage = result.result.metadata.usage;
       view.phaseDurationMs = result.result.metadata.phaseDurationMs ?? null;
       const tools = result.result.metadata.toolOutcomes;
@@ -315,6 +322,7 @@ export class ConsoleReporter implements SuiteObserver {
       // Assertions reported before the run failed to persist are not results
       // and must not inflate the closing tally of a case that errored.
       view.assertions = [];
+      view.skippedAssertions = [];
     }
 
     this.region.staticLine(this.finishedLine(view));
@@ -452,6 +460,11 @@ export class ConsoleReporter implements SuiteObserver {
         body: !entry.passed && entry.comment ? [this.theme.dim(entry.comment)] : [],
       });
     }
+    for (const skipped of view.skippedAssertions) {
+      nodes.push({
+        head: `${this.theme.dim("⊘")} ${skipped.name}  ${this.theme.dim("skipped: judge disabled")}`,
+      });
+    }
 
     if (view.toolCalls > 0 || view.toolUnmatchedResults > 0 || view.toolMalformed > 0) {
       const parts = [
@@ -550,15 +563,17 @@ export class ConsoleReporter implements SuiteObserver {
     }
 
     const assertions = this.cases.flatMap((c) => c.assertions);
-    if (assertions.length > 0) {
+    const skippedAssertions = this.cases.flatMap((c) => c.skippedAssertions);
+    if (assertions.length > 0 || skippedAssertions.length > 0) {
       const ok = assertions.filter((a) => a.passed).length;
       const bad = assertions.length - ok;
       const tally = formatTally(
         [
           [ok, this.theme.green("passed")],
           [bad, this.theme.red("failed")],
+          [skippedAssertions.length, this.theme.dim("skipped")],
         ],
-        assertions.length,
+        assertions.length + skippedAssertions.length,
       );
       lines.push(` ${label("Assertions")}${tally}`);
     }

package/src/cli/run-options.ts

@@ -8,6 +8,7 @@ export type RunOptions = {
   listTags?: boolean;
   interactive?: boolean;
   claudeAnswerer?: boolean;
+  skipJudge?: boolean;
   runsRoot?: string;
   profile?: string;
   subjectRoot?: string;

package/src/cli/view.ts

@@ -0,0 +1,168 @@
+import { resolve } from "node:path";
+import { InvalidArgumentError } from "commander";
+import {
+  formatExperimentRun,
+  formatExperimentRunsTable,
+  formatRunDetail,
+  formatRunsTable,
+  formatSuiteRunDetail,
+  formatSuiteRunsTable,
+  isExperimentRun,
+  listExperimentRuns,
+  listRuns,
+  listSuiteRuns,
+  loadExperimentRun,
+  loadLuxConfig,
+  loadRunDetail,
+  loadSuiteRun,
+} from "../orchestrator/index.js";
+import { openPreviewUrl, startPreviewServer } from "../previewer/server.js";
+import { abortOnInterrupt, ensureDirectory, failWith } from "./command-runtime.js";
+
+const SIGINT_EXIT_CODE = 130;
+
+export type ViewOptions = {
+  runsRoot?: string;
+  case?: string;
+  suites?: boolean;
+  experiments?: boolean;
+  web?: boolean;
+  port?: number;
+  open?: boolean;
+  json?: boolean;
+};
+
+const previewKind = async (
+  initialPath: string | undefined,
+  options: ViewOptions,
+): Promise<"run" | "suite" | "experiment" | undefined> => {
+  if (initialPath) {
+    if (isExperimentRun(initialPath)) return "experiment";
+    if (await loadSuiteRun(initialPath)) return "suite";
+    return "run";
+  }
+  if (options.experiments) return "experiment";
+  if (options.suites) return "suite";
+  return undefined;
+};
+
+const webViewCommand = async (
+  runDirArg: string | undefined,
+  options: ViewOptions,
+): Promise<void> => {
+  if (options.json) {
+    throw new InvalidArgumentError("--web and --json are mutually exclusive");
+  }
+  const config = await loadLuxConfig(process.cwd());
+  const runsRoot = options.runsRoot ? resolve(options.runsRoot) : config.runsRoot;
+  const initialPath = runDirArg ? resolve(runDirArg) : undefined;
+  if (initialPath && !(await ensureDirectory("view", initialPath))) return;
+  const initialKind = await previewKind(initialPath, options);
+  const controller = abortOnInterrupt();
+  const preview = await startPreviewServer({
+    runsRoot,
+    ...(options.port !== undefined ? { port: options.port } : {}),
+    ...(initialPath ? { initialPath } : {}),
+    ...(initialKind ? { initialKind } : {}),
+    ...(options.case ? { caseFilter: options.case } : {}),
+    signal: controller.signal,
+  });
+  process.stdout.write(`Lux Review: ${preview.url}\n`);
+  process.stdout.write(`Reading evidence from ${runsRoot}\n`);
+  if (options.open !== false) {
+    try {
+      await openPreviewUrl(preview.url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`lux view: could not open a browser (${message})\n`);
+    }
+  }
+  await preview.closed;
+  if (controller.signal.aborted) failWith(SIGINT_EXIT_CODE);
+};
+
+export const viewCommand = async (
+  runDirArg: string | undefined,
+  options: ViewOptions,
+): Promise<void> => {
+  if (options.web) {
+    await webViewCommand(runDirArg, options);
+    return;
+  }
+  if (options.port !== undefined || options.open === false) {
+    throw new InvalidArgumentError("--port and --no-open require --web");
+  }
+  if (runDirArg) {
+    const path = resolve(runDirArg);
+    if (!(await ensureDirectory("view", path))) return;
+    if (isExperimentRun(path)) {
+      const experiment = await loadExperimentRun(path);
+      if (!experiment) {
+        process.stderr.write(`lux view: invalid experiment at ${path}\n`);
+        failWith(1);
+        return;
+      }
+      process.stdout.write(
+        options.json
+          ? `${JSON.stringify({ experimentDir: path, ...experiment }, null, 2)}\n`
+          : `${formatExperimentRun(path, experiment)}\n`,
+      );
+      return;
+    }
+    const suite = await loadSuiteRun(path);
+    if (suite) {
+      process.stdout.write(
+        options.json
+          ? `${JSON.stringify({ suiteDir: path, ...suite }, null, 2)}\n`
+          : `${formatSuiteRunDetail(path, suite)}\n`,
+      );
+      return;
+    }
+    const detail = await loadRunDetail(path);
+    process.stdout.write(
+      options.json ? `${JSON.stringify(detail, null, 2)}\n` : `${formatRunDetail(detail)}\n`,
+    );
+    return;
+  }
+
+  const config = await loadLuxConfig(process.cwd());
+  const runsRoot = options.runsRoot ? resolve(options.runsRoot) : config.runsRoot;
+  if (options.experiments) {
+    const experiments = await listExperimentRuns(runsRoot);
+    process.stdout.write(
+      options.json
+        ? `${JSON.stringify(experiments, null, 2)}\n`
+        : `experiments at ${runsRoot}:\n${formatExperimentRunsTable(experiments)}\n`,
+    );
+    return;
+  }
+  if (options.suites) {
+    const suites = await listSuiteRuns(runsRoot);
+    process.stdout.write(
+      options.json
+        ? `${JSON.stringify(suites, null, 2)}\n`
+        : `suite runs at ${runsRoot}:\n${formatSuiteRunsTable(suites)}\n`,
+    );
+    return;
+  }
+  const all = await listRuns(runsRoot);
+  const runs = options.case ? all.filter((run) => run.caseSlug === options.case) : all;
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(runs, null, 2)}\n`);
+    return;
+  }
+  if (!options.case) {
+    process.stdout.write(`suite runs at ${runsRoot}:\n`);
+    process.stdout.write(`${formatSuiteRunsTable(await listSuiteRuns(runsRoot))}\n\n`);
+  }
+  process.stdout.write(`runs at ${runsRoot}:\n`);
+  process.stdout.write(`${formatRunsTable(runs)}\n`);
+};
+
+export const parsePreviewPort = (value: string): number => {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new InvalidArgumentError("port must be an integer from 0 to 65535");
+  }
+  return port;
+};

package/src/core/action-events.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { RunEvent } from "./events.js";
+
+export const ActionCategorySchema = z.enum([
+  "query",
+  "mutation",
+  "durable-mutation",
+  "execution",
+  "interaction",
+]);
+export type ActionCategory = z.infer<typeof ActionCategorySchema>;
+
+export const ActionProgressPayloadSchema = z
+  .object({
+    name: z.string(),
+    category: ActionCategorySchema,
+  })
+  .strict();
+export type ActionProgressPayload = z.infer<typeof ActionProgressPayloadSchema>;
+
+export const ActionTimingSchema = z.object({
+  timeToFirstActionMs: z.exactOptional(z.number().nonnegative()),
+  timeToFirstMutationMs: z.exactOptional(z.number().nonnegative()),
+  timeToFirstDurableMutationMs: z.exactOptional(z.number().nonnegative()),
+});
+export type ActionTiming = z.infer<typeof ActionTimingSchema>;
+
+export const actionTiming = (events: readonly RunEvent[]): ActionTiming => {
+  const startEvent = events.find(
+    (event) => event.type === "lifecycle" && event.stage === "start-driver",
+  );
+  const startedAt = startEvent?.type === "lifecycle" ? startEvent.ts : undefined;
+  if (startedAt === undefined) return {};
+
+  const actions = events.flatMap((event) => {
+    if (event.type !== "progress" || event.kind !== "action") return [];
+    const payload = ActionProgressPayloadSchema.safeParse(event.payload).data;
+    return payload ? [{ ...payload, ts: event.ts }] : [];
+  });
+  const elapsed = (category: "any" | "mutation" | "durable-mutation") => {
+    const timestamps = actions.flatMap(({ category: candidate, ts }) => {
+      if (category === "any") return [ts];
+      if (category === "mutation") {
+        return candidate === "mutation" || candidate === "durable-mutation" ? [ts] : [];
+      }
+      return candidate === category ? [ts] : [];
+    });
+    return timestamps.length > 0 ? Math.max(0, Math.min(...timestamps) - startedAt) : undefined;
+  };
+
+  const timeToFirstActionMs = elapsed("any");
+  const timeToFirstMutationMs = elapsed("mutation");
+  const timeToFirstDurableMutationMs = elapsed("durable-mutation");
+  return {
+    ...(timeToFirstActionMs === undefined ? {} : { timeToFirstActionMs }),
+    ...(timeToFirstMutationMs === undefined ? {} : { timeToFirstMutationMs }),
+    ...(timeToFirstDurableMutationMs === undefined ? {} : { timeToFirstDurableMutationMs }),
+  };
+};

package/src/core/agent-activity.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { ActionProgressPayloadSchema } from "./action-events.js";
+import { AgentCompletedPayloadSchema, AgentSpawnPayloadSchema } from "./agent-events.js";
+import type { AgentAttribution, ReadyState, RunEvent } from "./events.js";
+import { ToolCallPayloadSchema, ToolResultPayloadSchema } from "./tool-events.js";
+import { TokenUsageSchema } from "./usage.js";
+
+export const AgentActivitySchema = z.object({
+  agent: z.object({
+    id: z.string(),
+    role: z.enum(["main", "subagent"]),
+    parentId: z.exactOptional(z.string()),
+    spawnToolUseId: z.exactOptional(z.string()),
+    name: z.exactOptional(z.string()),
+    model: z.exactOptional(z.string()),
+  }),
+  startedAt: z.number(),
+  endedAt: z.number(),
+  durationMs: z.number().nonnegative(),
+  status: z.enum(["completed", "failed", "cancelled", "unknown"]),
+  eventCount: z.number().int().nonnegative(),
+  usage: TokenUsageSchema.extend({ total: z.number().int().nonnegative() }),
+  toolCalls: z.object({
+    total: z.number().int().nonnegative(),
+    succeeded: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+  }),
+  actions: z.object({
+    total: z.number().int().nonnegative(),
+    mutations: z.number().int().nonnegative(),
+    durableMutations: z.number().int().nonnegative(),
+    timeToFirstActionMs: z.exactOptional(z.number().nonnegative()),
+    timeToFirstMutationMs: z.exactOptional(z.number().nonnegative()),
+    timeToFirstDurableMutationMs: z.exactOptional(z.number().nonnegative()),
+  }),
+});
+export type AgentActivity = z.infer<typeof AgentActivitySchema>;
+
+const legacyAttribution = (
+  event: Extract<RunEvent, { type: "progress" }>,
+  ready: ReadyState,
+): AgentAttribution => {
+  const payload = event.payload;
+  const parentToolUseId =
+    typeof payload === "object" && payload !== null && "parentToolUseId" in payload
+      ? payload.parentToolUseId
+      : undefined;
+  const spawnToolUseId =
+    typeof parentToolUseId === "string" && parentToolUseId.length > 0 ? parentToolUseId : undefined;
+  return spawnToolUseId
+    ? {
+        id: `subagent:${spawnToolUseId}`,
+        role: "subagent" as const,
+        parentId: ready.agentId,
+        spawnToolUseId,
+      }
+    : { id: ready.agentId, role: "main" as const, ...(ready.model ? { model: ready.model } : {}) };
+};
+
+type MutableActivity = AgentActivity & { calls: Map<string, "pending" | "succeeded" | "failed"> };
+type ProgressEvent = Extract<RunEvent, { type: "progress" }>;
+type SpawnInfo = { ts: number; name?: string; model?: string };
+
+const initialActivity = (agent: AgentAttribution, startedAt: number): MutableActivity => ({
+  agent,
+  startedAt,
+  endedAt: startedAt,
+  durationMs: 0,
+  status: "unknown",
+  eventCount: 0,
+  usage: { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, total: 0 },
+  toolCalls: { total: 0, succeeded: 0, failed: 0, unresolved: 0 },
+  actions: { total: 0, mutations: 0, durableMutations: 0 },
+  calls: new Map(),
+});
+
+const collectSpawnInfo = (events: RunEvent[]): Map<string, SpawnInfo> => {
+  const spawns = new Map<string, SpawnInfo>();
+  for (const event of events) {
+    if (event.type !== "progress" || event.kind !== "tool-call") continue;
+    const call = ToolCallPayloadSchema.safeParse(event.payload).data;
+    if (!call) continue;
+    const input = z
+      .object({
+        name: z.string().min(1).optional(),
+        subagent_type: z.string().min(1).optional(),
+        agent: z.string().min(1).optional(),
+        role: z.string().min(1).optional(),
+        model: z.string().min(1).optional(),
+      })
+      .loose()
+      .safeParse(call.input).data;
+    const name = input?.name ?? input?.subagent_type ?? input?.agent ?? input?.role;
+    spawns.set(call.toolUseId, {
+      ts: event.ts,
+      ...(name ? { name } : {}),
+      ...(input?.model ? { model: input.model } : {}),
+    });
+  }
+  return spawns;
+};
+
+const applyLifecycle = (
+  event: ProgressEvent,
+  activities: Map<string, MutableActivity>,
+): boolean => {
+  if (event.kind === "agent-spawn") {
+    const spawn = AgentSpawnPayloadSchema.safeParse(event.payload).data;
+    if (spawn && !activities.has(spawn.agent.id)) {
+      activities.set(spawn.agent.id, initialActivity(spawn.agent, event.ts));
+    }
+    return true;
+  }
+  if (event.kind !== "agent-completed") return false;
+  const completed = AgentCompletedPayloadSchema.safeParse(event.payload).data;
+  const activity = completed ? activities.get(completed.agentId) : undefined;
+  if (activity && completed) {
+    activity.endedAt = Math.max(activity.endedAt, event.ts);
+    activity.durationMs = Math.max(0, activity.endedAt - activity.startedAt);
+    activity.status = completed.status;
+  }
+  return true;
+};
+
+const activityFor = (
+  event: ProgressEvent,
+  ready: ReadyState,
+  driverStartedAt: number,
+  spawns: Map<string, SpawnInfo>,
+  activities: Map<string, MutableActivity>,
+): MutableActivity => {
+  const agent = event.agent ?? legacyAttribution(event, ready);
+  const existing = activities.get(agent.id);
+  if (existing) return existing;
+  const spawn = agent.spawnToolUseId ? spawns.get(agent.spawnToolUseId) : undefined;
+  const name = agent.name ?? spawn?.name;
+  const model = agent.model ?? spawn?.model;
+  const attributedAgent = {
+    ...agent,
+    ...(name ? { name } : {}),
+    ...(model ? { model } : {}),
+  };
+  const startedAt =
+    agent.role === "subagent" && agent.spawnToolUseId
+      ? (spawn?.ts ?? event.ts)
+      : driverStartedAt || event.ts;
+  return activities.get(agent.id) ?? initialActivity(attributedAgent, startedAt);
+};
+
+const addAction = (event: ProgressEvent, activity: MutableActivity): void => {
+  const action = ActionProgressPayloadSchema.safeParse(event.payload).data;
+  if (!action) return;
+  const elapsed = Math.max(0, event.ts - activity.startedAt);
+  activity.actions.total++;
+  activity.actions.timeToFirstActionMs ??= elapsed;
+  if (action.category === "mutation" || action.category === "durable-mutation") {
+    activity.actions.mutations++;
+    activity.actions.timeToFirstMutationMs ??= elapsed;
+  }
+  if (action.category === "durable-mutation") {
+    activity.actions.durableMutations++;
+    activity.actions.timeToFirstDurableMutationMs ??= elapsed;
+  }
+};
+
+const addUsage = (event: ProgressEvent, activity: MutableActivity): void => {
+  const usage = TokenUsageSchema.safeParse(event.payload).data;
+  if (!usage) return;
+  activity.usage.input += usage.input;
+  activity.usage.output += usage.output;
+  activity.usage.cacheRead += usage.cacheRead;
+  activity.usage.cacheCreation += usage.cacheCreation;
+  activity.usage.total += usage.input + usage.output + usage.cacheRead + usage.cacheCreation;
+};
+
+const addWork = (event: ProgressEvent, activity: MutableActivity): void => {
+  activity.eventCount++;
+  activity.endedAt = Math.max(activity.endedAt, event.ts);
+  activity.durationMs = Math.max(0, activity.endedAt - activity.startedAt);
+  if (event.kind === "tool-call") {
+    const call = ToolCallPayloadSchema.safeParse(event.payload).data;
+    if (call && !activity.calls.has(call.toolUseId)) {
+      activity.calls.set(call.toolUseId, "pending");
+      activity.toolCalls.total++;
+    }
+    return;
+  }
+  if (event.kind === "tool-result") {
+    const result = ToolResultPayloadSchema.safeParse(event.payload).data;
+    if (result && activity.calls.has(result.toolUseId)) {
+      activity.calls.set(result.toolUseId, result.isError ? "failed" : "succeeded");
+    }
+    return;
+  }
+  if (event.kind === "action") addAction(event, activity);
+  if (event.kind === "usage") addUsage(event, activity);
+};
+
+export const summarizeAgentActivity = (events: RunEvent[], ready: ReadyState): AgentActivity[] => {
+  const driverStart = events.find(
+    (event): event is Extract<RunEvent, { type: "lifecycle" }> =>
+      event.type === "lifecycle" && event.stage === "start-driver",
+  );
+  const driverStartedAt = driverStart?.ts ?? 0;
+  const spawns = collectSpawnInfo(events);
+  const activities = new Map<string, MutableActivity>();
+  for (const event of events) {
+    if (event.type !== "progress") continue;
+    if (applyLifecycle(event, activities)) continue;
+    const activity = activityFor(event, ready, driverStartedAt, spawns, activities);
+    addWork(event, activity);
+    activities.set(activity.agent.id, activity);
+  }
+
+  if (!activities.has(ready.agentId)) {
+    activities.set(
+      ready.agentId,
+      initialActivity(
+        {
+          id: ready.agentId,
+          role: "main",
+          ...(ready.model ? { model: ready.model } : {}),
+        },
+        driverStartedAt,
+      ),
+    );
+  }
+  return [...activities.values()]
+    .map(({ calls, ...activity }) => {
+      for (const outcome of calls.values())
+        activity.toolCalls[outcome === "pending" ? "unresolved" : outcome]++;
+      return AgentActivitySchema.parse(activity);
+    })
+    .sort((a, b) => a.startedAt - b.startedAt || a.agent.id.localeCompare(b.agent.id));
+};

package/src/core/agent-events.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { AgentAttributionSchema } from "./events.js";
+
+export const AGENT_SPAWN_KIND = "agent-spawn" as const;
+export const AGENT_COMPLETED_KIND = "agent-completed" as const;
+
+export const AgentSpawnPayloadSchema = z.object({
+  agent: AgentAttributionSchema.extend({ role: z.literal("subagent") }),
+  prompt: z.exactOptional(z.string()),
+});
+export type AgentSpawnPayload = z.infer<typeof AgentSpawnPayloadSchema>;
+
+export const AgentCompletedPayloadSchema = z.object({
+  agentId: z.string().min(1),
+  status: z.enum(["completed", "failed", "cancelled", "unknown"]),
+});
+export type AgentCompletedPayload = z.infer<typeof AgentCompletedPayloadSchema>;

package/src/core/artifact-evidence.ts

@@ -7,12 +7,15 @@ import type { Run } from "./run.js";
 const DEFAULT_ARTIFACT_READ_BYTES = 5 * 1024 * 1024;
 const MAX_ARTIFACT_READ_BYTES = 10 * 1024 * 1024;
 
+export type RunArtifactIssueReason = "absent" | "unreadable";
+
 export type RunArtifactInspection = {
   target: string;
   root: string;
   artifact?: Artifact;
   stats?: Stats;
   issue?: string;
+  reason?: RunArtifactIssueReason;
 };
 
 type RunArtifactEvidence = {
@@ -82,6 +85,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: runArtifactsRoot(run),
       issue: `${authoredPath} contains a null byte`,
+      reason: "unreadable",
     };
   }
   const matching = run.artifacts.filter((candidate) => candidate.path === authoredPath);
@@ -91,6 +95,7 @@ export const inspectRunArtifact = async (
       target: resolve(root, authoredPath),
       root,
       issue: `${authoredPath} was not captured in the frozen artifact index`,
+      reason: "absent",
     };
   }
   if (matching.some((candidate) => candidate.root !== undefined && !isAbsolute(candidate.root))) {
@@ -98,6 +103,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: defaultArtifactsRoot(run),
       issue: `${authoredPath} declares a non-absolute artifact root`,
+      reason: "unreadable",
     };
   }
   const artifact = matching[0];
@@ -108,6 +114,7 @@ export const inspectRunArtifact = async (
       target: authoredPath,
       root: defaultArtifactsRoot(run),
       issue: `${authoredPath} is ambiguous across multiple artifact roots`,
+      reason: "unreadable",
     };
   }
   // A non-default root is trusted only for an exact artifact-index entry.
@@ -116,7 +123,12 @@ export const inspectRunArtifact = async (
   const root = matchingRoots[0] ?? defaultArtifactsRoot(run);
   const target = resolve(root, authoredPath);
   if (pathEscapesRoot(root, target)) {
-    return { target, root, issue: `${authoredPath} escapes the captured artifact root` };
+    return {
+      target,
+      root,
+      issue: `${authoredPath} escapes the captured artifact root`,
+      reason: "unreadable",
+    };
   }
 
   const path = relative(root, target);
@@ -134,7 +146,13 @@ export const inspectRunArtifact = async (
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code;
       if (code === "ENOENT" || code === "ENOTDIR") {
-        return { target, root, ...identified, issue: `${authoredPath} not found` };
+        return {
+          target,
+          root,
+          ...identified,
+          issue: `${authoredPath} not found`,
+          reason: "absent",
+        };
       }
       throw error;
     }
@@ -144,16 +162,17 @@ export const inspectRunArtifact = async (
         root,
         ...identified,
         issue: `${authoredPath} resolves through a symlink`,
+        reason: "unreadable",
       };
     }
     if (index < components.length - 1 && !stats.isDirectory()) {
-      return { target, root, ...identified, issue: `${authoredPath} not found` };
+      return { target, root, ...identified, issue: `${authoredPath} not found`, reason: "absent" };
     }
     if (index === components.length - 1) {
       return { target, root, ...identified, stats };
     }
   }
-  return { target, root, ...identified, issue: `${authoredPath} not found` };
+  return { target, root, ...identified, issue: `${authoredPath} not found`, reason: "absent" };
 };
 
 export type ReadRunArtifactTextOptions = {
@@ -247,3 +266,27 @@ export const readRunArtifactText = async (
 ): Promise<string> => {
   return (await readRunArtifactBytes(run, authoredPath, options)).toString("utf8");
 };
+
+/**
+ * Read optional artifact evidence. Returns null when the artifact was never
+ * captured, and still throws when one exists but is unsafe to consume, so a
+ * traversal or symlink violation is never mistaken for missing evidence.
+ */
+export const readRunArtifactTextIfPresent = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  options: ReadRunArtifactTextOptions = {},
+): Promise<string | null> => {
+  const inspected = await inspectRunArtifact(run, authoredPath);
+  if (inspected.reason === "absent") return null;
+  if (!inspected.stats?.isFile()) {
+    throw new Error(
+      inspected.issue ??
+        (inspected.stats ? `${authoredPath} is not a file` : `${authoredPath} not found`),
+    );
+  }
+  const maxBytes = options.maxBytes ?? DEFAULT_ARTIFACT_READ_BYTES;
+  return (
+    await readInspectedFileBytes(inspected.target, inspected.stats, maxBytes, authoredPath)
+  ).toString("utf8");
+};