pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/advisory-challenge.ts

@@ -0,0 +1,75 @@
+import { Type, type Static } from "typebox";
+import { collectAdvisoryStage, type AdvisoryStageCoverage } from "./advisory-evidence.ts";
+import { DEFAULT_ADVISORY_TOOLS, DEFAULT_ADVISORY_TOOL_HINTS, type AdvisoryVerified } from "./workflow-advisory-utils.ts";
+import type { WorkflowApi } from "./types.ts";
+
+const ChallengeSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("counterexample"), Type.Literal("alternative-explanation"), Type.Literal("supports-original"), Type.Literal("no-counterexample")]),
+  evidence: Type.Array(Type.String()),
+  experiment: Type.String({ description: "Smallest distinguishing experiment, with observed result if actually run." }),
+});
+const AdjudicationSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("upheld"), Type.Literal("refuted"), Type.Literal("unresolved")]),
+  evidence: Type.Array(Type.String()),
+  reason: Type.String(),
+});
+export type ChallengeRecord =
+  | { status: "complete"; challenge: Static<typeof ChallengeSchema>; adjudication: Static<typeof AdjudicationSchema> }
+  | { status: "failed"; challenge?: Static<typeof ChallengeSchema> };
+export interface AdvisoryChallengeOptions {
+  maxChallenges: number;
+  shouldChallenge?: (finding: AdvisoryVerified) => boolean;
+}
+
+/** Opt in with --challenge or --challenge=N (hard bound of 10). */
+export function parseChallengeArgs(args: string): { args: string; options: AdvisoryChallengeOptions } {
+  let maxChallenges = 0;
+  const remaining = args.replace(/(?:^|\s)--challenge(?:=([^\s]*))?(?=\s|$)/g, (_match, limit: string | undefined) => {
+    if (limit !== undefined && !/^\d+$/.test(limit)) {
+      throw new Error(`Invalid --challenge value "${limit}". Use --challenge or --challenge=N with a non-negative integer; zero disables challenges.`);
+    }
+    maxChallenges = Math.min(10, limit === undefined ? 3 : Number(limit));
+    return " ";
+  });
+  return { args: remaining.trim(), options: { maxChallenges } };
+}
+
+export function needsChallenge(finding: AdvisoryVerified): boolean {
+  return finding.verdict === "PLAUSIBLE" || finding.verdict === "NOT_SUBSTANTIATED" || finding.evidence.length === 0 ||
+    /\b(security|concurren\w*|race|persist\w*|cancel\w*|retr(?:y|ies)|data loss|corrupt\w*|high impact)\b/i.test(`${finding.category} ${finding.summary} ${finding.impact}`);
+}
+
+/** A bounded recipe using existing agent/parallel calls, not a new runtime primitive. */
+export async function challengeFindings<T extends AdvisoryVerified>(
+  api: Pick<WorkflowApi, "agent" | "parallel">,
+  findings: T[],
+  context: string,
+  options: AdvisoryChallengeOptions,
+  coverage: AdvisoryStageCoverage[],
+): Promise<T[]> {
+  const limit = Number.isFinite(options.maxChallenges) ? Math.max(0, Math.min(10, Math.trunc(options.maxChallenges))) : 0;
+  if (limit === 0) return findings;
+  const selected = findings.filter((finding) => finding.verdict !== "REFUTED" && (options.shouldChallenge ?? needsChallenge)(finding)).slice(0, limit);
+  const replacements = new Map<string, T>();
+  await collectAdvisoryStage(api, "Challenge", selected.map((finding) => ({ id: finding.candidateId, run: async () => {
+    // Preserve the candidate as unresolved if either independent stage fails.
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed" } });
+    const challenge = await api.agent(
+      `Assume this finding is a false positive. Try to DISPROVE it. Find the strongest concrete counterexample or alternative root cause. Inspect callers, invariants, tests and control flow. For a repair, seek an input, race or error path that still fails. State the smallest experiment distinguishing explanations. Do not edit files or claim tests you did not run. No counterexample found is not proof.\n\nExact review context:\n${context}\n\nCandidate and verifier evidence:\n${JSON.stringify(finding)}`,
+      { label: `challenge:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, schema: ChallengeSchema },
+    );
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed", challenge } });
+    const adjudication = await api.agent(
+      `Adjudicate the original finding, independent verifier evidence and falsification attempt below. Preserve unresolved conflict; do not force consensus. A missing counterexample alone cannot upgrade a plausible claim. Cite concrete evidence and observed test results; never invent experiments.\nContext:\n${context}\nOriginal and verifier:\n${JSON.stringify(finding)}\nChallenger:\n${JSON.stringify(challenge)}`,
+      { label: `adjudicate:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: [], skills: [], schema: AdjudicationSchema },
+    );
+    replacements.set(finding.candidateId, {
+      ...finding,
+      verdict: adjudication.outcome === "refuted" ? "REFUTED" : adjudication.outcome === "unresolved" ? "NOT_SUBSTANTIATED" : finding.verdict,
+      evidence: [...finding.evidence, ...challenge.evidence, ...(challenge.experiment ? [challenge.experiment] : []), ...adjudication.evidence, adjudication.reason],
+      challenge: { status: "complete", challenge, adjudication },
+    });
+    return finding.candidateId;
+  } })), coverage);
+  return findings.map((finding) => replacements.get(finding.candidateId) ?? finding);
+}

package/.pi/extensions/pi-workflow-engine/src/advisory-evidence.ts

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { Type, type Static } from "typebox";
+import { AdvisorySeveritySchema, type IdentifiedAdvisoryCandidate, type AdvisoryCandidate, type AdvisoryReport } from "./advisory-schema.ts";
+import type { WorkflowApi } from "./types.ts";
+
+export type AdvisoryStageCoverage = NonNullable<AdvisoryReport["coverage"]>[number];
+
+/** Settled results are required here: a missing branch is not a negative finding. */
+export async function collectAdvisoryStage<T>(
+  api: Pick<WorkflowApi, "parallel">,
+  stage: string,
+  branches: { id: string; candidate?: AdvisoryCandidate; run(): Promise<T> }[],
+  coverage: AdvisoryStageCoverage[],
+): Promise<T[]> {
+  const results = await api.parallel(branches.map((branch) => branch.run), { settled: true });
+  const failures = results.flatMap((result, index) => result.ok ? [] : [{ branch: branches[index]!.id, reason: result.error.message, ...(branches[index]!.candidate ? { candidate: branches[index]!.candidate } : {}) }]);
+  coverage.push({ stage, expected: branches.length, completed: results.length - failures.length, failed: failures.length, failures });
+  return results.flatMap((result) => result.ok ? [result.value] : []);
+}
+
+export function identifyCandidates(candidates: readonly AdvisoryCandidate[], lens: string): IdentifiedAdvisoryCandidate[] {
+  return candidates.map((candidate, index) => {
+    const candidateId = createHash("sha256").update(JSON.stringify([lens, index, candidate])).digest("hex").slice(0, 20);
+    // Identities are assigned by the workflow, never accepted from a finder.
+    return { ...candidate, candidateId, sourceCandidateIds: [candidateId] };
+  });
+}
+
+function normalizedSummary(summary: string): string {
+  return summary.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.!?]+$/, "");
+}
+
+/** Repo-relative readings of a reported path, most literal first: without a stray `./`, then also without a git `a/`/`b/` prefix. */
+export function repoPathCandidates(path: string): [literal: string, unprefixed: string] {
+  const literal = path.replace(/^\.\//, "");
+  return [literal, literal.replace(/^[ab]\//, "")];
+}
+
+function candidateDedupKey(candidate: AdvisoryCandidate): string {
+  const location = candidate.locations[0];
+  return JSON.stringify([candidate.category, location && repoPathCandidates(location.file)[1],
+    location?.symbol ?? location?.line ?? null, normalizedSummary(candidate.summary)]);
+}
+
+/** Collapse only equivalent claims at the same anchor; keep every discovery ID and location. */
+export function dedupeCandidates<T extends IdentifiedAdvisoryCandidate>(candidates: readonly T[]): T[] {
+  const seen = new Map<string, T>();
+  for (const candidate of candidates) {
+    const key = candidateDedupKey(candidate);
+    const previous = seen.get(key);
+    if (!previous) seen.set(key, { ...candidate });
+    else {
+      previous.sourceCandidateIds = [...new Set([...previous.sourceCandidateIds, ...candidate.sourceCandidateIds])];
+      previous.locations = uniqueLocations([...previous.locations, ...candidate.locations]);
+      previous.impact = [...new Set([previous.impact, candidate.impact])].join("\n");
+      previous.discoveryEvidence = [...new Set([...(previous.discoveryEvidence ?? []), ...(candidate.discoveryEvidence ?? [])])];
+    }
+  }
+  return [...seen.values()];
+}
+
+export function uniqueLocations(locations: AdvisoryCandidate["locations"]): AdvisoryCandidate["locations"] {
+  return [...new Map(locations.map((location) => [JSON.stringify(location), location])).values()];
+}
+
+// Synthesis selects evidence records. It has no fields with which to replace their evidence.
+export const AdvisorySynthesisSchema = Type.Object({
+  summary: Type.String(),
+  findings: Type.Array(Type.Object({
+    sourceCandidateIds: Type.Array(Type.String(), { minItems: 1 }),
+    severity: AdvisorySeveritySchema,
+    recommendation: Type.String(),
+  })),
+  nextSteps: Type.Array(Type.String()),
+});
+export type AdvisorySynthesis = Static<typeof AdvisorySynthesisSchema>;
+export const SYNTHESIS_ID_INSTRUCTIONS = "Select or merge findings only by sourceCandidateIds shown below. Return severity and an advisory recommendation per selection. Never select an ID absent from these verified records. ";
+
+export function withAdvisoryCoverage<T extends AdvisoryReport>(report: T, coverage: AdvisoryStageCoverage[]) {
+  const incomplete = coverage.some((stage) => stage.failed > 0);
+  const gaps = coverage.flatMap((stage) => stage.failures.map((failure) => `${stage.stage}/${failure.branch}: ${failure.reason}`));
+  return {
+    ...report,
+    status: incomplete ? "incomplete" as const : "complete" as const,
+    summary: incomplete ? `Incomplete review: ${gaps.length} branch(es) failed. ${report.findings.length} finding(s) available; no clean conclusion is possible.` : report.summary,
+    nextSteps: incomplete ? ["Inspect failed branches and rerun missing work.", ...(report.findings.length > 0 ? report.nextSteps : [])] : report.nextSteps,
+    coverage,
+    gaps,
+  };
+}

package/.pi/extensions/pi-workflow-engine/src/advisory-schema.ts

@@ -9,7 +9,7 @@ export const AdvisoryConfidenceSchema = Type.Union([Type.Literal("low"), Type.Li
   description: "Confidence that the finding is actionable.",
 });
 
-export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")], {
+export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED"), Type.Literal("NOT_SUBSTANTIATED")], {
   description: "Verifier judgment for a candidate finding.",
 });
 
@@ -20,6 +20,8 @@ export const AdvisoryLocationSchema = Type.Object({
 });
 
 export const AdvisoryCandidateSchema = Type.Object({
+  discoveryEvidence: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
   summary: Type.String({ description: "One-line candidate finding or hypothesis." }),
   category: Type.String({ description: "Workflow-specific category such as bug, duplication, root-cause, or io." }),
   locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
@@ -34,10 +36,12 @@ export const AdvisoryCandidatesSchema = Type.Object({
 export const AdvisoryVerdictSchema = Type.Object({
   verdict: AdvisoryVerifierVerdictSchema,
   evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
-  confidence: Type.Optional(AdvisoryConfidenceSchema),
 });
 
 export const AdvisoryFindingSchema = Type.Object({
+  verdict: Type.Optional(AdvisoryVerifierVerdictSchema),
+  sourceCandidateIds: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
   summary: Type.String({ description: "One-line final finding." }),
   category: Type.String({ description: "Workflow-specific category for grouping and display." }),
   severity: AdvisorySeveritySchema,
@@ -49,6 +53,12 @@ export const AdvisoryFindingSchema = Type.Object({
 });
 
 export const AdvisoryReportSchema = Type.Object({
+  status: Type.Optional(Type.Union([Type.Literal("complete"), Type.Literal("incomplete")])),
+  gaps: Type.Optional(Type.Array(Type.String())),
+  coverage: Type.Optional(Type.Array(Type.Object({
+    stage: Type.String(), expected: Type.Number(), completed: Type.Number(), failed: Type.Number(),
+    failures: Type.Array(Type.Object({ branch: Type.String(), reason: Type.String(), candidate: Type.Optional(AdvisoryCandidateSchema) })),
+  }))),
   summary: Type.String({ description: "Short overall advisory summary." }),
   findings: Type.Array(AdvisoryFindingSchema, { description: "Verified and ranked advisory findings." }),
   nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
@@ -61,6 +71,7 @@ export const AdvisoryReportWithStatsSchema = Type.Object({
 
 export type AdvisoryLocation = Static<typeof AdvisoryLocationSchema>;
 export type AdvisoryCandidate = Static<typeof AdvisoryCandidateSchema>;
+export type IdentifiedAdvisoryCandidate = AdvisoryCandidate & { candidateId: string; sourceCandidateIds: string[] };
 export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
 export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
 export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;
@@ -69,3 +80,10 @@ export type AdvisoryReportWithStats = Static<typeof AdvisoryReportWithStatsSchem
 export function isAdvisoryReport(value: unknown): value is AdvisoryReportWithStats {
   return Value.Check(AdvisoryReportWithStatsSchema, value);
 }
+
+/** `file:line (symbol)`, omitting whichever of line and symbol is unknown. */
+export function formatAdvisoryLocation(location: AdvisoryLocation): string {
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}

package/.pi/extensions/pi-workflow-engine/src/agent-attempt.ts

@@ -2,28 +2,23 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import { assertWorkflowBudgetAvailable } from "./budget.ts";
 import {
   type AgentExecutionOptions,
-  type AgentRunTags,
   type RunContext,
 } from "./agent-runner-types.ts";
 import {
   captureReplayIdentity,
   captureIsolatedRepositoryAfterSetup,
   captureSharedRepositoryBeforeSetup,
-  isReplayEnabled,
   lookupReplayResult,
-  validateReplayEvidence,
+  validateMutationGuard,
   validateReplayIdentity,
   type AgentAttemptResult,
-  type AgentReplayEvidence,
+  type AgentReplayContract,
   type AgentReplayPlan,
+  type ArmedReplayPlan,
 } from "./agent-replay.ts";
 import { openAgentSession, promptAgentSession, type AgentSessionHandle } from "./agent-session.ts";
-import {
-  createAgentWorkspace,
-  disposeAgentWorkspace,
-  type AgentWorkspace,
-} from "./agent-workspace.ts";
-import type { AgentResumeBaseContext, AgentResumeContext, RepositoryResumeContext } from "./resume-context.ts";
+import { createAgentWorkspace, type AgentWorkspace } from "./agent-workspace.ts";
+import type { AgentResumeBaseContext, RepositoryResumeContext } from "./resume-context.ts";
 import { captureRepositoryMutationGuard } from "./resume-context.ts";
 
 /** Execute one fully bracketed workspace/session attempt. Cleanup always precedes settlement. */
@@ -36,38 +31,33 @@ export async function executeAgentAttempt(input: {
   readonly replay: AgentReplayPlan;
   readonly label: string;
   readonly rowId: number;
-  readonly tags: AgentRunTags;
+  readonly phase: string;
   readonly admitLiveAgent: () => void;
 }): Promise<AgentAttemptResult> {
-  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, tags, admitLiveAgent } = input;
+  const { rc, prompt, opts, resumeBaseContext, model, replay, label, rowId, phase, admitLiveAgent } = input;
+  let armed: ArmedReplayPlan | undefined;
   let repositoryBefore: RepositoryResumeContext | undefined;
-  let evidence: AgentReplayEvidence | undefined;
-  if (isReplayEnabled(replay)) {
-    if (replay.kind === "isolated") {
-      const mutationGuard = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
-      if (mutationGuard.kind === "unverifiable") {
-        repositoryBefore = mutationGuard;
-      } else {
-        evidence = { kind: "isolated", mutationGuard: mutationGuard.fingerprint };
-      }
-    } else {
-      repositoryBefore = await captureSharedRepositoryBeforeSetup(rc, prompt, opts, replay);
-      evidence = { kind: "shared" };
-    }
+  if (replay.kind === "isolated") {
+    const mutationGuard = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
+    if (mutationGuard.kind === "verified") armed = { ...replay, mutationGuard: mutationGuard.fingerprint };
+    else rc.progress.log(`${label}: resume disabled for this call (${mutationGuard.reason})`);
+  } else if (replay.kind === "shared") {
+    armed = replay;
+    repositoryBefore = await captureSharedRepositoryBeforeSetup(rc, prompt, opts, replay);
   }
   let workspace: AgentWorkspace | undefined;
   let handle: AgentSessionHandle | undefined;
 
   try {
     workspace = await createAgentWorkspace(rc, opts, label);
-    if (replay.kind === "isolated" && evidence?.kind === "isolated") {
+    if (armed?.kind === "isolated") {
       if (workspace.kind !== "isolated") throw new Error("Isolated replay created a shared workspace.");
       repositoryBefore = await captureIsolatedRepositoryAfterSetup(rc, prompt, opts, workspace);
     }
-    handle = await openAgentSession({ rc, prompt, opts, cwd: workspace.cwd, model, label, tags });
+    handle = await openAgentSession({ rc, prompt, opts, cwd: workspace.cwd, model, label });
 
-    let identity: AgentResumeContext | undefined;
-    if (isReplayEnabled(replay) && repositoryBefore && evidence) {
+    let contract: AgentReplayContract | undefined;
+    if (armed && repositoryBefore) {
       const capture = await captureReplayIdentity({
         rc,
         base: resumeBaseContext,
@@ -79,23 +69,12 @@ export async function executeAgentAttempt(input: {
       if (capture.kind === "unverifiable") {
         rc.progress.log(`${label}: resume disabled for this call (${capture.reason})`);
       } else {
-        identity = capture.identity;
-        const cached = await lookupReplayResult({ rc, key: replay.key, identity, opts, workspace });
+        contract = { ...armed, identity: capture.identity };
+        const cached = await lookupReplayResult({ rc, key: contract.key, identity: contract.identity, opts, workspace });
         if (cached.hit) {
-          const contract = await validateReplayIdentity({
-            rc,
-            identity,
-            selectedSkills: handle.selectedSkills,
-            session: handle.session,
-            sessionCwd: workspace.cwd,
-            replay,
-            workspace,
-          });
-          const validation = contract.ok
-            ? await validateReplayEvidence(rc, evidence)
-            : contract;
+          const validation = await validateReplayContract(rc, contract, handle, workspace);
           if (validation.ok) {
-            return { kind: "cache-hit", result: cached.result, identity, evidence };
+            return { kind: "cache-hit", result: cached.result, contract };
           }
           rc.progress.log(`${label}: cached result invalidated (${validation.reason})`);
         } else if (cached.reason) {
@@ -113,35 +92,42 @@ export async function executeAgentAttempt(input: {
       opts,
       label,
       rowId,
-      tags,
+      phase,
     });
     const result = await workspace.wrapResult(rawResult);
-    if (!identity) return { kind: "live-unrecordable", result };
-    if (!isReplayEnabled(replay) || !evidence) throw new Error("Replay identity produced without complete replay evidence.");
+    if (!contract) return { kind: "live-unrecordable", result };
 
-    const contract = await validateReplayIdentity({
-      rc,
-      identity,
-      selectedSkills: handle.selectedSkills,
-      session: handle.session,
-      sessionCwd: workspace.cwd,
-      replay,
-      workspace,
-    });
-    const validation = contract.ok
-      ? await validateReplayEvidence(rc, evidence)
-      : contract;
+    const validation = await validateReplayContract(rc, contract, handle, workspace);
     if (validation.ok) {
-      return { kind: "live-recordable", result, identity, evidence };
+      return { kind: "live-recordable", result, contract };
     }
     rc.progress.log(`${label}: read-only resume contract was not recorded (${validation.reason})`);
     return { kind: "live-unrecordable", result };
   } finally {
     try {
       const session = handle?.session;
-      if (session) rc.perf.timeSync("agent.dispose_ms", () => session.dispose(), tags);
+      if (session) rc.perf.timeSync("agent.dispose_ms", () => session.dispose());
     } finally {
-      await disposeAgentWorkspace(rc, label, workspace);
+      await workspace?.dispose();
     }
   }
 }
+
+/** Re-check a captured replay identity and its repository evidence against the session and workspace as they are now. */
+async function validateReplayContract(
+  rc: RunContext,
+  contract: AgentReplayContract,
+  handle: AgentSessionHandle,
+  workspace: AgentWorkspace,
+): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  const identity = await validateReplayIdentity({
+    rc,
+    contract,
+    selectedSkills: handle.selectedSkills,
+    session: handle.session,
+    sessionCwd: workspace.cwd,
+    workspace,
+  });
+  if (!identity.ok || contract.kind === "shared") return identity;
+  return await validateMutationGuard(rc, contract.mutationGuard);
+}

package/.pi/extensions/pi-workflow-engine/src/agent-replay.ts

@@ -1,8 +1,9 @@
 import type { Skill } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { captureAgentSkillIdentities, extractSkillSelectorsFromText } from "./agent-skills.ts";
-import type { AgentExecutionOptions, AgentRunnerSession, AgentRunTags, RunContext } from "./agent-runner-types.ts";
+import type { AgentExecutionOptions, AgentRunnerSession, RunContext } from "./agent-runner-types.ts";
 import { captureEffectiveAgentSessionIdentity } from "./agent-session-identity.ts";
+import { isRecord } from "./guards.ts";
 import { FINAL_TOOL } from "./agent-session.ts";
 import type { AgentWorkspace, IsolatedAgentWorkspace } from "./agent-workspace.ts";
 import { captureAgentJournalKey } from "./journal.ts";
@@ -11,7 +12,7 @@ import {
   captureRepositoryMutationGuard,
   captureIsolatedRepositoryContext,
   captureRepositoryResumeContext,
-  createAgentResumeContext,
+  repositoryMismatchReason,
   resumeContextMismatchReason,
   type AgentResumeBaseContext,
   type AgentResumeContext,
@@ -26,13 +27,17 @@ export type AgentReplayPlan =
   | { readonly kind: "shared"; readonly key: string; readonly additionalInputs: readonly string[] }
   | { readonly kind: "isolated"; readonly key: string };
 
-export type AgentReplayEvidence =
-  | { readonly kind: "shared" }
-  | { readonly kind: "isolated"; readonly mutationGuard: string };
+/** An enabled replay plan with its main-workspace evidence: isolated replays carry the mutation guard taken before setup. */
+export type ArmedReplayPlan =
+  | Extract<AgentReplayPlan, { readonly kind: "shared" }>
+  | (Extract<AgentReplayPlan, { readonly kind: "isolated" }> & { readonly mutationGuard: string });
+
+/** An armed replay plan plus the resume identity captured for one attempt. */
+export type AgentReplayContract = ArmedReplayPlan & { readonly identity: AgentResumeContext };
 
 export type AgentAttemptResult =
-  | { readonly kind: "cache-hit"; readonly result: unknown; readonly identity: AgentResumeContext; readonly evidence: AgentReplayEvidence }
-  | { readonly kind: "live-recordable"; readonly result: unknown; readonly identity: AgentResumeContext; readonly evidence: AgentReplayEvidence }
+  | { readonly kind: "cache-hit"; readonly result: unknown; readonly contract: AgentReplayContract }
+  | { readonly kind: "live-recordable"; readonly result: unknown; readonly contract: AgentReplayContract }
   | { readonly kind: "live-unrecordable"; readonly result: unknown };
 
 export type AgentAttemptSettlement =
@@ -129,28 +134,28 @@ export async function lookupReplayResult(input: {
 
 export async function validateReplayIdentity(input: {
   readonly rc: RunContext;
-  readonly identity: AgentResumeContext;
+  readonly contract: AgentReplayContract;
   readonly selectedSkills: readonly Skill[];
   readonly session: AgentRunnerSession;
   readonly sessionCwd: string;
-  readonly replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>;
   readonly workspace: AgentWorkspace;
 }): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
-  const repository = input.identity.repository.state === "inaccessible"
+  const { identity } = input.contract;
+  const repository = identity.repository.state === "inaccessible"
     ? INACCESSIBLE_REPOSITORY_CONTEXT
-    : await captureCurrentRepository(input.rc, input.replay, input.workspace);
+    : await captureCurrentRepository(input.rc, input.contract, input.workspace);
   if (repository.kind === "unverifiable") return { ok: false, reason: repository.reason };
 
   const current = await captureVerifiedReplayIdentity({
     rc: input.rc,
     repository,
-    workflow: input.identity.workflow,
+    workflow: identity.workflow,
     selectedSkills: input.selectedSkills,
     session: input.session,
     sessionCwd: input.sessionCwd,
   });
   if (current.kind === "unverifiable") return { ok: false, reason: current.reason };
-  const mismatch = resumeContextMismatchReason(input.identity, current.identity, {
+  const mismatch = resumeContextMismatchReason(identity, current.identity, {
     allowWorkflowSourceMismatch: input.rc.resumeEditedWorkflow,
   });
   return mismatch ? { ok: false, reason: mismatch } : { ok: true };
@@ -159,23 +164,16 @@ export async function validateReplayIdentity(input: {
 export async function settleAgentAttempt(input: {
   readonly rc: RunContext;
   readonly label: string;
-  readonly tags: AgentRunTags;
-  readonly replay: AgentReplayPlan;
   readonly outcome: AgentAttemptResult;
 }): Promise<AgentAttemptSettlement> {
-  const { rc, label, replay, outcome } = input;
+  const { rc, label, outcome } = input;
   if (outcome.kind === "live-unrecordable") {
     recordAgentResultSource(rc, "live");
     return { kind: "done", result: outcome.result };
   }
-  if (!isReplayEnabled(replay)) throw new Error("Replayable agent outcome produced without an enabled replay plan.");
 
-  const repository = await validateRepositoryAfterCleanup(
-    rc,
-    outcome.identity,
-    replay,
-    outcome.evidence,
-  );
+  const { contract } = outcome;
+  const repository = await validateRepositoryAfterCleanup(rc, contract);
   if (!repository.ok) {
     if (outcome.kind === "cache-hit") {
       rc.progress.log(`${label}: cached result invalidated after cleanup (${repository.reason})`);
@@ -185,10 +183,10 @@ export async function settleAgentAttempt(input: {
     return { kind: "done", result: outcome.result };
   }
 
-  await recordJournalResult(rc, label, replay.key, outcome.result, outcome.identity);
+  await recordJournalResult(rc, label, contract.key, outcome.result, contract.identity);
   if (outcome.kind === "cache-hit") {
     rc.progress.log(`${label}: using cached result from workflow journal`);
-    rc.perf.counter("agent.cache_hit", 1, input.tags);
+    rc.perf.counter("agent.cache_hit");
     recordAgentResultSource(rc, "cached");
   } else {
     recordAgentResultSource(rc, "live");
@@ -236,12 +234,12 @@ async function captureVerifiedReplayIdentity(input: {
   }
   return {
     kind: "verified",
-    identity: createAgentResumeContext(
-      { workflow: input.workflow },
-      input.repository,
-      effectiveSession.identity,
-      skills.skills,
-    ),
+    identity: {
+      workflow: input.workflow,
+      repository: input.repository,
+      session: effectiveSession.identity,
+      skills: skills.skills,
+    },
   };
 }
 
@@ -259,7 +257,7 @@ async function validateCachedResult(
     if (!patch.ok) {
       return {
         ok: false,
-        reason: `cached isolated patch does not apply to the current baseline (${(patch.error ?? patch.stderr.trim()) || "unknown error"})`,
+        reason: `cached isolated patch does not apply to the current baseline (${patch.error})`,
       };
     }
     result = isolated.wrapper.result;
@@ -271,7 +269,6 @@ async function validateCachedResult(
       ? { ok: true }
       : { ok: false, reason: "cached text result is not a string" };
   }
-  if (result === null) return { ok: true };
   try {
     return Value.Check(opts.schema, result)
       ? { ok: true }
@@ -287,63 +284,45 @@ function isolatedCachedResult(value: unknown):
       readonly wrapper: { readonly result: unknown; readonly patch: string; readonly changed: boolean };
     }
   | { readonly ok: false; readonly reason: string } {
-  if (typeof value !== "object" || value === null) {
+  if (!isRecord(value)) {
     return { ok: false, reason: "cached isolated result is not an object" };
   }
-  const candidate = value as { readonly result?: unknown; readonly patch?: unknown; readonly changed?: unknown };
-  if (!("result" in candidate) || typeof candidate.patch !== "string" || typeof candidate.changed !== "boolean") {
+  if (!("result" in value) || typeof value.patch !== "string" || typeof value.changed !== "boolean") {
     return { ok: false, reason: "cached isolated result has an invalid wrapper" };
   }
-  const wrapper = { result: candidate.result, patch: candidate.patch, changed: candidate.changed };
+  const wrapper = { result: value.result, patch: value.patch, changed: value.changed };
   return { ok: true, wrapper };
 }
 
 async function validateRepositoryAfterCleanup(
   rc: RunContext,
-  identity: AgentResumeContext,
-  replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>,
-  evidence: AgentReplayEvidence,
+  contract: AgentReplayContract,
 ): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
-  if (replay.kind === "isolated") {
-    return evidence.kind === "isolated"
-      ? await validateReplayEvidence(rc, evidence)
-      : { ok: false, reason: "isolated replay omitted its main-workspace mutation guard" };
-  }
+  if (contract.kind === "isolated") return await validateMutationGuard(rc, contract.mutationGuard);
 
-  const repository = identity.repository.state === "inaccessible"
+  const repository = contract.identity.repository.state === "inaccessible"
     ? INACCESSIBLE_REPOSITORY_CONTEXT
-    : await captureRepositoryResumeContext(rc.cwd, replay.additionalInputs, rc.signal);
+    : await captureRepositoryResumeContext(rc.cwd, contract.additionalInputs, rc.signal);
   if (repository.kind === "unverifiable") return { ok: false, reason: repository.reason };
-  const mismatch = resumeContextMismatchReason(identity, { ...identity, repository });
-  if (mismatch) return { ok: false, reason: mismatch };
-  return evidence.kind === "shared"
-    ? { ok: true }
-    : { ok: false, reason: "shared replay carried isolated mutation evidence" };
-}
-
-export async function validateReplayEvidence(
-  rc: RunContext,
-  evidence: AgentReplayEvidence,
-): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
-  return evidence.kind === "shared"
-    ? { ok: true }
-    : await validateRepositoryMutationGuard(rc, evidence.mutationGuard);
+  const mismatch = repositoryMismatchReason(contract.identity.repository, repository);
+  return mismatch ? { ok: false, reason: mismatch } : { ok: true };
 }
 
-export async function validateRepositoryMutationGuard(
+/** Check that the main workspace is unchanged since an isolated replay took its mutation guard. */
+export async function validateMutationGuard(
   rc: RunContext,
-  expected: string,
+  mutationGuard: string,
 ): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
   const current = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
   if (current.kind === "unverifiable") return { ok: false, reason: current.reason };
-  return current.fingerprint === expected
+  return current.fingerprint === mutationGuard
     ? { ok: true }
     : { ok: false, reason: "main workspace changed outside the isolated worktree" };
 }
 
 async function captureCurrentRepository(
   rc: RunContext,
-  replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>,
+  replay: ArmedReplayPlan,
   workspace: AgentWorkspace,
 ): Promise<RepositoryResumeContext> {
   if (replay.kind === "shared") return await captureRepositoryResumeContext(rc.cwd, replay.additionalInputs, rc.signal);
@@ -375,8 +354,8 @@ function declaresNoWorkspaceCapability(prompt: string, opts: AgentExecutionOptio
     opts.tools !== undefined &&
     opts.tools.length === 0 &&
     (opts.toolHints?.length ?? 0) === 0 &&
-    (opts.skills?.length ?? 0) === 0 &&
-    extractSkillSelectorsFromText(prompt).length === 0
+    // Explicit skills suppress prompt inference, matching resolveAgentSkillRequest.
+    (opts.skills !== undefined ? opts.skills.length === 0 : extractSkillSelectorsFromText(prompt).length === 0)
   );
 }