@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/runtime/product/efficiency-metrics.ts

@@ -0,0 +1,130 @@
+import crypto from "node:crypto";
+
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { readSolverShadowEvents } from "../solver/solver-shadow.ts";
+import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
+import type { TrajectoryPhase } from "../trajectory/trajectory-types.ts";
+
+export const TASK_EFFICIENCY_METRICS_VERSION = "task-efficiency-v1" as const;
+
+type ExactUsage = {
+  tokens: number | null;
+  cost: number | null;
+  currency: string | null;
+  source: "provider" | "pi-runtime";
+};
+
+function hash(value: string): string {
+  return crypto.createHash("sha256").update(value || "unknown-session").digest("hex");
+}
+
+function duration(start: string, end: string): number | null {
+  const value = Date.parse(end) - Date.parse(start);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function phaseDurations(task: TaskContract, trajectory: ReturnType<typeof readTrajectoryStore>): Array<{ phase: TrajectoryPhase; durationMs: number }> {
+  if (trajectory.status !== "ok" || !trajectory.state) return [];
+  if (trajectory.state.sequence > 0 && trajectory.events.length !== trajectory.state.sequence) return [];
+  const totals = new Map<TrajectoryPhase, number>();
+  let phase: TrajectoryPhase = "intake";
+  let startedAt = trajectory.state.createdAt;
+  for (const event of trajectory.events) {
+    const elapsed = duration(startedAt, event.observedAt);
+    if (elapsed !== null) totals.set(phase, (totals.get(phase) ?? 0) + elapsed);
+    phase = event.to;
+    startedAt = event.observedAt;
+  }
+  const elapsed = duration(startedAt, task.updatedAt);
+  if (elapsed !== null) totals.set(phase, (totals.get(phase) ?? 0) + elapsed);
+  return [...totals.entries()].map(([name, durationMs]) => ({ phase: name, durationMs }));
+}
+
+export function buildTaskEfficiencyMetrics(
+  cwd: string,
+  task: TaskContract,
+  input: { activeToolGroups?: string[]; exactUsage?: ExactUsage } = {}
+) {
+  const sessionHash = hash(task.sessionId);
+  const solverStore = readSolverShadowEvents(cwd);
+  const solverEvent = [...solverStore.records].reverse().find((event) => event.sessionHash === sessionHash);
+  const trajectory = readTrajectoryStore(cwd, task.taskRunId);
+  const decision = solverEvent?.decision;
+  const helperUsage = task.acceptanceReceipt?.helperUsage;
+  const provenance = task.acceptanceReceipt?.provenance;
+  const relevantEvent = trajectory.events.find((event) => event.cause === "context-observed");
+  const relevantFileMs = relevantEvent && task.contextManifest.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
+  const recommendedTools = decision?.toolGroups ?? [];
+  const activeTools = [...new Set(input.activeToolGroups ?? [])].sort();
+  const exactUsage = input.exactUsage && (input.exactUsage.tokens !== null || input.exactUsage.cost !== null)
+    ? input.exactUsage
+    : { tokens: null, cost: null, currency: null, source: "unavailable" as const };
+
+  return {
+    schemaVersion: 1,
+    version: TASK_EFFICIENCY_METRICS_VERSION,
+    identity: { taskId: task.taskId, taskRunId: task.taskRunId, sessionHash },
+    compatibility: {
+      solver: solverStore.corruptions.length > 0 ? "corrupt" : solverEvent ? "ok" : "unavailable",
+      trajectory: trajectory.status,
+      oldSessionReadable: true
+    },
+    solver: decision ? {
+      mode: decision.mode,
+      route: decision.route,
+      override: decision.override,
+      routeRegret: decision.override.observed ? "route-overridden" : "unreviewed"
+    } : { mode: "unknown", route: "unknown", override: null, routeRegret: "unavailable" },
+    trajectory: {
+      currentPhase: trajectory.state?.currentPhase ?? null,
+      phaseDurations: phaseDurations(task, trajectory),
+      recoveredEvents: trajectory.recoveredEvents,
+      warnings: trajectory.warnings.slice(0, 4)
+    },
+    context: {
+      requiredFiles: task.requiredContext.length,
+      manifestedFiles: task.contextManifest.length,
+      memoryCitations: task.memoryCitations.length,
+      recommendedBudget: decision?.context.budgetBand ?? "unknown",
+      timeToRelevantFileMs: relevantFileMs,
+      timeToRelevantFileSource: relevantFileMs === null ? "unavailable" : "persisted-context-transition"
+    },
+    tools: {
+      recommendedGroups: recommendedTools,
+      activeGroups: activeTools,
+      activeRecommendedGroups: activeTools.filter((group) => recommendedTools.includes(group)),
+      actualInvocationCounts: null
+    },
+    timing: {
+      taskDurationMs: duration(task.createdAt, task.updatedAt),
+      timeToFirstCorrectEditMs: null,
+      timeToFirstCorrectEditReason: "no persisted edit-to-verifier causal marker"
+    },
+    verification: {
+      attempts: task.verifyEvidence.length,
+      passed: task.verifyEvidence.filter((item) => item.exitCode === 0).length,
+      failed: task.verifyEvidence.filter((item) => item.exitCode !== 0).length,
+      repairCount: provenance?.repairCount ?? 0,
+      retryCount: provenance?.retryCount ?? 0
+    },
+    helpers: {
+      mode: helperUsage?.mode ?? "unknown",
+      used: helperUsage?.used ?? false,
+      entries: (helperUsage?.helpers ?? []).map((item) => ({
+        role: item.role,
+        model: null,
+        calls: item.calls,
+        tokens: item.tokens,
+        disposition: item.disposition,
+        requestRef: item.requestRef,
+        outputDigest: item.outputDigest
+      }))
+    },
+    outcome: {
+      task: task.trace.outcome,
+      acceptance: task.acceptanceReceipt?.criteria.map((item) => ({ id: item.id, status: item.status })) ?? [],
+      recoveryDisposition: provenance?.finalRecoveryDisposition ?? "unknown"
+    },
+    exactUsage
+  };
+}

package/packages/piagent-core/runtime/product/operator-projections.ts

@@ -0,0 +1,111 @@
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { replayTaskCheckpoints } from "../../extensions/task-journal.js";
+import { taskContractValidationErrors, taskDigestMigrationArchiveStatus } from "../../extensions/task-state.js";
+import { latestObservedVerificationEvidence, verificationEvidenceProvesStableTree } from "../../extensions/verification-intelligence.js";
+import {
+  isCurrentWorkingTreeDigest,
+  WORKING_TREE_DIGEST_ALGORITHM,
+  workingTreeEvidenceDigest
+} from "../../extensions/working-tree-digest.js";
+import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
+import type { ModelRouteDecision } from "../model/model-route-types.ts";
+import type { RetrievalRoutePlan } from "../context/retrieval-route-policy.ts";
+import { inspectTaskResumeState } from "../recovery/resume-state.ts";
+import type { SolverShadowEvaluation } from "../solver/solver-shadow.ts";
+import type { TrajectoryStatus } from "../trajectory/trajectory-runtime.ts";
+import { buildTaskEfficiencyMetrics } from "./efficiency-metrics.ts";
+
+export const PRODUCT_PREFLIGHT_VERSION = "product-preflight-v1" as const;
+export const LIVE_TASK_STATUS_VERSION = "live-task-status-v1" as const;
+export const COMPLETION_RECEIPT_VIEW_VERSION = "completion-receipt-view-v1" as const;
+
+export type CompletionGateProjection = {
+  decision: "pass" | "fail";
+  missing: string[];
+  warnings?: string[];
+  currentWorkingTreeDigest?: string;
+};
+
+function digestMigration(task: TaskContract) {
+  return {
+    algorithm: task.workingTreeDigestAlgorithm,
+    migration: task.workingTreeDigestMigration
+      ? {
+          status: task.workingTreeDigestMigration.status,
+          reasonCode: task.workingTreeDigestMigration.reasonCode,
+          requiredAction: task.workingTreeDigestMigration.requiredAction
+        }
+      : null
+  };
+}
+
+function sameSortedStrings(left: string[], right: string[]): boolean {
+  return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+}
+
+function taskTreeEvidenceIsCurrent(cwd: string | undefined, task: TaskContract, baselineDigest: string, currentDigest: string): boolean {
+  const migrationCurrent = !task.workingTreeDigestMigration || Boolean(cwd
+    && task.workingTreeDigestMigration.status === "refreshed"
+    && taskDigestMigrationArchiveStatus(cwd, task).valid
+    && replayTaskCheckpoints(cwd, task.taskRunId, task).corruptions.length === 0);
+  return taskContractValidationErrors(task).length === 0
+    && task.workingTreeDigestAlgorithm === WORKING_TREE_DIGEST_ALGORITHM
+    && task.workingTreeDigestMigration?.status !== "verification-refresh-required"
+    && migrationCurrent
+    && isCurrentWorkingTreeDigest(baselineDigest)
+    && isCurrentWorkingTreeDigest(currentDigest)
+    && sameSortedStrings(task.baselineChangedFiles, Object.keys(task.baselineFileDigests))
+    && sameSortedStrings(task.finalWorkingTreeFiles, Object.keys(task.finalFileDigests));
+}
+
+export function buildProductPreflight(evaluation: SolverShadowEvaluation, input: { runtime?: RuntimeModelSnapshot; modelRoute?: ModelRouteDecision | null; retrievalRoute?: RetrievalRoutePlan | null; scope?: string[]; protectedPaths?: string[]; activeToolGroups?: string[]; helperMode?: string; helperBudget?: string; executionBackend?: string; executionBoundary?: string; approvals?: string[]; blockers?: string[]; controlMode?: "shadow" | "assist" | "enforce" } = {}) {
+  if (evaluation.status !== "ok") return { schemaVersion: 1, version: PRODUCT_PREFLIGHT_VERSION, status: evaluation.status, controlMode: evaluation.status === "off" ? "off" : "unknown", intent: { workflow: "unknown", changeMode: "unknown" }, risk: { lane: "unknown", signals: [] }, scope: { requested: input.scope ?? [], protectedPaths: input.protectedPaths ?? [] }, runtime: null, solver: null, modelRouting: input.modelRoute ?? null, retrieval: input.retrievalRoute ?? null, phases: [], contextBudget: "unknown", tools: { active: input.activeToolGroups ?? [], recommended: [] }, helper: { mode: input.helperMode ?? "unknown", recommendation: null, ownedBudget: input.helperBudget ?? "unknown" }, execution: { backend: input.executionBackend ?? "host", boundary: input.executionBoundary ?? "host execution is not a sandbox", implementationAuthorized: false }, readiness: { git: null, verifier: null }, approvals: input.approvals ?? [], blockers: input.blockers ?? [] };
+  const { features, decision } = evaluation;
+  const implementationAuthorized = features.changeMode === "source-change" && !features.protectedTarget && !features.externalAction && !features.destructiveAction && !features.permissionExpansion && features.gitReady === true && features.verifierReady === true;
+  return { schemaVersion: 1, version: PRODUCT_PREFLIGHT_VERSION, status: "ok", controlMode: input.controlMode ?? (decision.mode === "shadow" ? "shadow" : decision.mode === "recommend" ? "assist" : "off"), intent: { workflow: features.workflowIntent, changeMode: features.changeMode }, risk: { lane: features.riskLane, signals: features.riskSignals }, scope: { requested: input.scope ?? [], protectedPaths: input.protectedPaths ?? [] }, runtime: { provider: input.runtime?.provider ?? features.userPinnedProvider, modelId: input.runtime?.modelId ?? features.userPinnedModel, effort: input.runtime?.effectiveThinkingLevel ?? features.userPinnedEffort, contextWindow: input.runtime?.contextWindow ?? null, provenance: input.runtime?.source ?? "unknown", unknown: !input.runtime }, solver: { mode: decision.mode, route: decision.route, confidence: decision.confidence, reasonCodes: decision.reasonCodes }, modelRouting: input.modelRoute ?? null, retrieval: input.retrievalRoute ?? null, phases: decision.plannedPhases, contextBudget: decision.context.budgetBand, tools: { active: input.activeToolGroups ?? [], recommended: decision.toolGroups }, helper: { mode: input.helperMode ?? "unknown", recommendation: decision.helper, ownedBudget: input.helperBudget ?? "unknown" }, execution: { backend: input.executionBackend ?? "host", boundary: input.executionBoundary ?? "host execution is not a sandbox", implementationAuthorized }, readiness: { git: features.gitReady, verifier: features.verifierReady }, approvals: input.approvals ?? [], blockers: input.blockers ?? [] };
+}
+
+export function formatProductPreflight(view: ReturnType<typeof buildProductPreflight>): string {
+  const solver = view.solver as any, runtime = view.runtime as any;
+  const modelRoute = view.modelRouting as ModelRouteDecision | null;
+  const retrieval = view.retrieval as RetrievalRoutePlan | null;
+  const control = view.controlMode === "shadow" ? "shadow: no behavior changed" : view.controlMode === "assist" ? "assist: recommendations visible" : view.controlMode === "enforce" ? "enforce: policy active" : `control: ${view.controlMode}`;
+  return [`preflight: ${view.controlMode.toUpperCase()} (${view.status})`, `intent: ${view.intent.workflow}/${view.intent.changeMode}; risk=${view.risk.lane}`, `scope: ${view.scope.requested.join(", ") || "unknown"}; protected=${view.scope.protectedPaths.join(", ") || "none"}`, `runtime: ${runtime ? `${runtime.provider ?? "unknown"}/${runtime.modelId ?? "unknown"}; effort=${runtime.effort ?? "unknown"}; provenance=${runtime.provenance}` : "unknown"}`, `route: ${solver ? `${solver.route}; solverMode=${solver.mode}; confidence=${solver.confidence}; reasons=${solver.reasonCodes.join(",")}` : "unknown"}`, `modelRoute: ${modelRoute ? `${modelRoute.disposition}; band=${modelRoute.capabilityBand}; floor=${modelRoute.safetyFloor}; target=${modelRoute.provider ?? "none"}/${modelRoute.modelId ?? "none"}:${modelRoute.effort ?? "none"}; source=${modelRoute.selectionSource}; enforced=${modelRoute.enforced}` : "off/unavailable"}`, `retrieval: ${retrieval ? `${retrieval.activation}; parallel=${retrieval.maxParallel}; rounds=${retrieval.maxRounds}; specialist=${retrieval.specialistRole ?? "none"}; auto=${retrieval.automaticDispatch}` : "local-default"}`, control, `phases: ${view.phases.join(" → ") || "none"}; context=${view.contextBudget}`, `tools: active=${view.tools.active.join(",") || "unknown"}; recommended=${view.tools.recommended.join(",") || "none"}`, `helper: mode=${view.helper.mode}; recommendation=${JSON.stringify(view.helper.recommendation)}; budget=${view.helper.ownedBudget}`, `execution: ${view.execution.backend}; ${view.execution.boundary}; implementation=${view.execution.implementationAuthorized ? "authorized" : "not-authorized"}`, `readiness: git=${view.readiness.git ?? "unknown"}; verifier=${view.readiness.verifier ?? "unknown"}`, `approvals/blockers: ${[...view.approvals, ...view.blockers].join("; ") || "none"}`].join("\n");
+}
+
+export function buildLiveTaskStatus(cwd: string, task: TaskContract | undefined, sessionId: string, input: { trajectory?: TrajectoryStatus; runtime?: RuntimeModelSnapshot; modelRoute?: ModelRouteDecision | null; activeToolGroups?: string[]; helpers?: unknown[]; completionGate?: CompletionGateProjection } = {}) {
+  if (!task) return { schemaVersion: 1, version: LIVE_TASK_STATUS_VERSION, state: "idle", task: null, tree: null, runtime: input.runtime ?? null, modelRouting: input.modelRoute ?? null, activeToolGroups: input.activeToolGroups ?? [], helpers: input.helpers ?? [], blockers: [], nextSafeAction: "start-or-resume-task", receipt: null, efficiency: null };
+  const replay = replayTaskCheckpoints(cwd, task.taskRunId, task); const resume = inspectTaskResumeState(cwd, task, sessionId); const latest = replay.checkpoints.at(-1); const latestFailure = [...replay.checkpoints].reverse().find((item) => item.status === "failed"); const evidence = latestFailure?.evidence && typeof latestFailure.evidence === "object" ? latestFailure.evidence as Record<string, any> : {};
+  const currentTreeDigest = isCurrentWorkingTreeDigest(resume.currentTreeDigest) ? resume.currentTreeDigest : null;
+  const migrationRefresh = task.workingTreeDigestMigration?.status === "verification-refresh-required";
+  const latestVerifiers = latestObservedVerificationEvidence(task.verifyEvidence);
+  return { schemaVersion: 1, version: LIVE_TASK_STATUS_VERSION, state: task.trace.outcome === "pending" ? resume.enforcementSafe ? "active" : "corrupt" : "terminal", task: { taskId: task.taskId, taskRunId: task.taskRunId, sessionHash: resume.sessionId === task.sessionId ? "matched" : "conflict", attempt: task.attempt, maxAttempts: task.maxAttempts, phase: input.trajectory?.phase ?? resume.phase, outcome: task.trace.outcome, pendingVerifiers: task.verifyCommands.filter((command) => !currentTreeDigest || !verificationEvidenceProvesStableTree(latestVerifiers.get(command.trim()), currentTreeDigest)), pendingReview: task.workPlan.some((step) => step.id === "review" && step.status !== "done") }, tree: { ...digestMigration(task), currentDigest: currentTreeDigest }, runtime: input.runtime ?? null, modelRouting: input.modelRoute ?? null, activeToolGroups: input.activeToolGroups ?? [], recovery: { classification: evidence.failureClassification?.category ?? null, action: evidence.recovery?.action ?? null }, helpers: input.helpers ?? task.acceptanceReceipt?.helperUsage?.helpers ?? [], checkpoint: latest ? { id: latest.checkpointId, phase: latest.phase, status: latest.status, sequence: latest.sequence } : null, resume: { decision: resume.decision, safe: resume.enforcementSafe, staleVerifier: resume.staleVerifierEvidence, authorityPolicy: resume.authorityPolicy }, blockers: resume.warnings, nextSafeAction: task.trace.outcome !== "pending" ? "none-terminal" : migrationRefresh ? "rerun-exact-verifier" : resume.enforcementSafe ? resume.staleVerifierEvidence ? "rerun-exact-verifier" : "continue-current-phase" : "inspect-handoff-and-recover", receipt: task.trace.outcome === "pending" ? null : buildCompletionReceiptView(task, { cwd, gate: input.completionGate, modelRoute: input.modelRoute }), efficiency: buildTaskEfficiencyMetrics(cwd, task, { activeToolGroups: input.activeToolGroups }) };
+}
+
+export function formatLiveTaskStatus(view: ReturnType<typeof buildLiveTaskStatus>): string { if (!view.task) return `task: none\nmodelRoute: ${view.modelRouting ? `${view.modelRouting.disposition}/${view.modelRouting.capabilityBand}` : "none"}\nnext: start-or-resume-task`; const task = view.task; return [`task: ${task.taskId} (${task.taskRunId}); attempt=${task.attempt}/${task.maxAttempts}`, `state: ${view.state}; phase=${task.phase ?? "unknown"}; outcome=${task.outcome}`, `modelRoute: ${view.modelRouting ? `${view.modelRouting.disposition}; band=${view.modelRouting.capabilityBand}; target=${view.modelRouting.modelId ?? "none"}:${view.modelRouting.effort ?? "none"}; enforced=${view.modelRouting.enforced}` : "none"}`, `pending: verify=${task.pendingVerifiers.join(",") || "none"}; review=${task.pendingReview}`, `recovery: ${view.recovery.classification ?? "none"}/${view.recovery.action ?? "none"}`, `helpers: ${view.helpers.length}; checkpoint=${view.checkpoint?.id ?? "none"}`, `resume: ${view.resume.decision}; safe=${view.resume.safe}; staleVerifier=${view.resume.staleVerifier}; authority=${view.resume.authorityPolicy.disposition}/${view.resume.authorityPolicy.reason}`, `blockers: ${view.blockers.join("; ") || "none"}`, `next: ${view.nextSafeAction}`].join("\n"); }
+
+export function buildCompletionReceiptView(task: TaskContract, input: { cwd?: string; gate?: CompletionGateProjection; modelRoute?: ModelRouteDecision | null } = {}) {
+  const gate = input.gate;
+  const current = task.finalFileDigests ?? {};
+  const baselineDigest = workingTreeEvidenceDigest(task.baselineFileDigests ?? {});
+  const currentDigest = workingTreeEvidenceDigest(current);
+  const recovery = task.acceptanceReceipt?.provenance;
+  const helpers = task.acceptanceReceipt?.helperUsage;
+  const latestVerifiers = latestObservedVerificationEvidence(task.verifyEvidence);
+  const acceptanceSatisfied = task.acceptanceReceipt?.criteria.every((item) => item.status === "satisfied") === true;
+  const treeEvidenceCurrent = taskTreeEvidenceIsCurrent(input.cwd, task, baselineDigest, currentDigest);
+  const gateTreeCurrent = isCurrentWorkingTreeDigest(gate?.currentWorkingTreeDigest)
+    && gate?.currentWorkingTreeDigest === currentDigest;
+  const completionApproved = gate?.decision === "pass" && task.trace.outcome === "completed" && acceptanceSatisfied && treeEvidenceCurrent && gateTreeCurrent;
+  const remainingRisk = [
+    ...(task.trace.outcome === "completed" ? [] : [task.failureReason ?? task.trace.friction ?? "task-not-completed"]),
+    ...(gate ? gate.missing : ["completion-gate-unavailable"]),
+    ...(acceptanceSatisfied ? [] : ["acceptance-criteria-pending"]),
+    ...(task.workingTreeDigestAlgorithm === WORKING_TREE_DIGEST_ALGORITHM ? [] : ["working-tree-digest-legacy-untrusted"]),
+    ...(task.workingTreeDigestMigration?.status === "verification-refresh-required" ? ["working-tree-verification-refresh-required"] : []),
+    ...(treeEvidenceCurrent ? [] : ["task-contract-or-tree-evidence-invalid"]),
+    ...(gate?.decision === "pass" && !gateTreeCurrent ? ["completion-gate-tree-digest-untrusted-or-mismatched"] : []),
+    ...(gate?.decision === "pass" && !treeEvidenceCurrent ? ["working-tree-evidence-not-current"] : [])
+  ].filter((value, index, values) => values.indexOf(value) === index);
+  return { schemaVersion: 1, version: COMPLETION_RECEIPT_VIEW_VERSION, outcome: task.trace.outcome, completionApproved, modelRouting: input.modelRoute ?? null, gate: { decision: gate?.decision ?? "unavailable", missing: gate?.missing ?? ["completion-gate-unavailable"], warnings: gate?.warnings ?? [], currentWorkingTreeDigest: isCurrentWorkingTreeDigest(gate?.currentWorkingTreeDigest) ? gate?.currentWorkingTreeDigest : null }, acceptance: task.acceptanceReceipt?.criteria.map((item) => ({ id: item.id, obligation: item.obligation, status: item.status, evidence: item.evidence.map((entry) => entry.kind) })) ?? [], changedFiles: task.changedFiles, tree: { ...digestMigration(task), baselineDigest: isCurrentWorkingTreeDigest(baselineDigest) ? baselineDigest : null, currentDigest: isCurrentWorkingTreeDigest(currentDigest) ? currentDigest : null, evidenceCurrent: treeEvidenceCurrent }, verification: { exactCommands: task.verifyCommands, results: task.verifyCommands.map((command) => latestVerifiers.get(command.trim())).filter(Boolean).map((item) => ({ command: item.command, exitCode: item.exitCode, workingTreeDigest: isCurrentWorkingTreeDigest(item.workingTreeDigest) ? item.workingTreeDigest : null })) }, review: { lenses: task.reviewLenses, completed: task.workPlan.filter((item) => item.id === "review").every((item) => item.status === "done"), oracleDisposition: helpers?.helpers.find((item) => item.role === "oracle")?.disposition ?? "not-used" }, helpers: helpers ?? { mode: "off", used: false, reasonCodes: [], helpers: [] }, recovery: recovery ?? null, policyBlocks: task.trace.outcome === "blocked" ? [task.failureReason ?? task.trace.friction ?? "blocked"] : [], remainingRisk, handoff: recovery?.handoffRef ?? `.pi/piagent-state/handoffs/${task.taskRunId}.json`, assurance: completionApproved ? "same-runtime-operational-evidence" : "historical-or-untrusted-working-tree-evidence" };
+}

package/packages/piagent-core/runtime/quality/exact-output-contract.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+
+const MAX_EVIDENCE_BYTES = 256 * 1024;
+const EXACT_OUTPUT_TEMPLATE = /\b([A-Z][A-Z0-9_]{2,63})\s*=\s*<([a-z][a-z0-9_-]{1,31})>/g;
+
+export type ExactOutputContractEvaluation = {
+  applicable: boolean;
+  passed: boolean;
+  key?: string;
+  expectedLines: string[];
+  evidencePaths: string[];
+};
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function exactOutputDirective(text: string): { key: string; placeholder: string } | undefined {
+  const value = String(text ?? "");
+  for (const match of value.matchAll(EXACT_OUTPUT_TEMPLATE)) {
+    const nearby = value.slice(Math.max(0, match.index! - 180), Math.min(value.length, match.index! + match[0].length + 180));
+    if (/\b(?:finish|end|last)\b[\s\S]{0,180}\b(?:response|answer|output|with|line)\b/i.test(nearby)) {
+      return { key: match[1], placeholder: match[2] };
+    }
+  }
+  return undefined;
+}
+
+function safeObservedFile(cwd: string, candidate: string): { path: string; text: string } | undefined {
+  try {
+    const absolute = path.resolve(cwd, candidate);
+    const relative = path.relative(cwd, absolute);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return undefined;
+    const stat = fs.lstatSync(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_EVIDENCE_BYTES) return undefined;
+    return { path: relative.split(path.sep).join("/"), text: fs.readFileSync(absolute, "utf8") };
+  } catch {
+    return undefined;
+  }
+}
+
+function valuesForKey(key: string, text: string): string[] {
+  const keyPattern = key.split(/_+/).filter(Boolean).map(escapeRegex).join("[\\s_-]*");
+  if (!keyPattern) return [];
+  const assignment = new RegExp(String.raw`\b${keyPattern}\b\s*[:=]\s*["']?([a-z0-9][a-z0-9_.:/-]{0,255})`, "gi");
+  return [...text.matchAll(assignment)].map((match) => match[1]);
+}
+
+export function exactFinalOutputGuidance(taskText: string): string[] {
+  const directive = exactOutputDirective(taskText);
+  if (!directive) return [];
+  return [
+    `Exact final-output contract: make ${directive.key}=<${directive.placeholder}> the last non-empty response line. Copy the complete value verbatim from observed in-scope evidence and self-check every character before handoff.`
+  ];
+}
+
+export function evaluateExactFinalOutputContract(
+  task: Pick<TaskContract, "summary" | "expectedOutput" | "acceptanceCriteria" | "contextManifest">,
+  responseText: string,
+  cwd: string
+): ExactOutputContractEvaluation {
+  const directive = exactOutputDirective([
+    task.summary,
+    task.expectedOutput,
+    ...(task.acceptanceCriteria ?? [])
+  ].filter(Boolean).join("\n"));
+  if (!directive) return { applicable: false, passed: true, expectedLines: [], evidencePaths: [] };
+
+  const evidencePaths: string[] = [];
+  const observedValues = new Set<string>();
+  for (const entry of task.contextManifest ?? []) {
+    const observed = safeObservedFile(cwd, entry.path);
+    if (!observed) continue;
+    const values = valuesForKey(directive.key, observed.text);
+    if (values.length === 0) continue;
+    evidencePaths.push(observed.path);
+    for (const value of values) observedValues.add(value);
+  }
+  if (observedValues.size === 0) {
+    return { applicable: false, passed: true, key: directive.key, expectedLines: [], evidencePaths: [] };
+  }
+
+  const expectedLines = [...observedValues].sort().map((value) => `${directive.key}=${value}`);
+  const finalLine = String(responseText ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) ?? "";
+  return {
+    applicable: true,
+    passed: expectedLines.includes(finalLine),
+    key: directive.key,
+    expectedLines,
+    evidencePaths: [...new Set(evidencePaths)].sort()
+  };
+}

package/packages/piagent-core/runtime/quality/model-mutation-proof.ts

@@ -0,0 +1,185 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX_PROOF_FILE_BYTES = 4 * 1024 * 1024;
+
+export type ModelMutationProof = {
+  expectedContentDigests: Record<string, string[]>;
+  preContentDigests: Record<string, string>;
+  fullContentPaths: string[];
+  replacePaths: string[];
+};
+
+function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
+  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
+  const absolute = path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(cwd, candidate);
+  const relative = path.relative(cwd, absolute).split(path.sep).join("/");
+  return relative && relative !== ".." && !relative.startsWith("../") ? relative : undefined;
+}
+
+function contentDigest(content: string | Buffer): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function stableFile(cwd: string, file: string): { content: string; digest: string } | undefined {
+  const absolute = path.resolve(cwd, file);
+  const relative = path.relative(cwd, absolute);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return undefined;
+  try {
+    const descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const before = fs.fstatSync(descriptor);
+      if (!before.isFile() || before.size > MAX_PROOF_FILE_BYTES) return undefined;
+      const buffer = Buffer.alloc(before.size);
+      let position = 0;
+      while (position < before.size) {
+        const bytes = fs.readSync(descriptor, buffer, position, before.size - position, position);
+        if (bytes <= 0) return undefined;
+        position += bytes;
+      }
+      const after = fs.fstatSync(descriptor);
+      if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return undefined;
+      return { content: buffer.toString("utf8"), digest: contentDigest(buffer) };
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+function inputEdits(input: Record<string, unknown>): Array<{ oldText: string; newText: string }> | undefined {
+  const values = Array.isArray(input.edits)
+    ? input.edits
+    : typeof input.oldText === "string" && typeof input.newText === "string"
+      ? [{ oldText: input.oldText, newText: input.newText }]
+      : [];
+  if (values.length === 0 || values.length > 100) return undefined;
+  const edits: Array<{ oldText: string; newText: string }> = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const edit = value as Record<string, unknown>;
+    if (typeof edit.oldText !== "string" || typeof edit.newText !== "string" || !edit.oldText || edit.oldText === edit.newText) return undefined;
+    edits.push({ oldText: edit.oldText, newText: edit.newText });
+  }
+  return edits;
+}
+
+function applyUniqueReplacements(content: string, edits: Array<{ oldText: string; newText: string }>): string | undefined {
+  let projected = content;
+  for (const edit of edits) {
+    const index = projected.indexOf(edit.oldText);
+    if (index < 0 || projected.indexOf(edit.oldText, index + edit.oldText.length) >= 0) return undefined;
+    projected = `${projected.slice(0, index)}${edit.newText}${projected.slice(index + edit.oldText.length)}`;
+  }
+  return projected === content ? undefined : projected;
+}
+
+function applyPatchHunks(content: string, lines: string[]): string | undefined {
+  let projected = content.split("\n");
+  let sawHunk = false;
+  for (let index = 0; index < lines.length;) {
+    if (!lines[index].startsWith("@@")) return undefined;
+    sawHunk = true;
+    index += 1;
+    const oldLines: string[] = [], newLines: string[] = [];
+    while (index < lines.length && !lines[index].startsWith("@@")) {
+      const line = lines[index++];
+      if (!line || line.startsWith("\\ No newline") || ![" ", "+", "-"].includes(line[0])) return undefined;
+      if (line[0] !== "+") oldLines.push(line.slice(1));
+      if (line[0] !== "-") newLines.push(line.slice(1));
+    }
+    if (oldLines.length === 0 || (oldLines.length === newLines.length && oldLines.every((line, item) => line === newLines[item]))) return undefined;
+    const matches: number[] = [];
+    for (let at = 0; at + oldLines.length <= projected.length; at += 1) {
+      if (oldLines.every((line, offset) => projected[at + offset] === line)) matches.push(at);
+    }
+    if (matches.length !== 1) return undefined;
+    projected.splice(matches[0], oldLines.length, ...newLines);
+  }
+  const result = sawHunk ? projected.join("\n") : undefined;
+  return result === content ? undefined : result;
+}
+
+function patchStrings(input: Record<string, unknown>): string[] {
+  return Object.values(input).filter((value): value is string => typeof value === "string" && value.includes("*** "));
+}
+
+function patchProof(cwd: string, input: Record<string, unknown>, targets: string[], proof: ModelMutationProof): void {
+  for (const patch of patchStrings(input)) {
+    const lines = patch.replace(/\r\n/g, "\n").split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+      const marker = lines[index].match(/^\*\*\* (Add|Update) File:\s*(.+?)\s*$/);
+      if (!marker) continue;
+      const file = normalizeRelative(cwd, marker[2]);
+      if (!file || !targets.includes(file)) continue;
+      const section: string[] = [];
+      for (index += 1; index < lines.length && !lines[index].startsWith("*** "); index += 1) section.push(lines[index]);
+      index -= 1;
+      if (marker[1] === "Add") {
+        proof.fullContentPaths.push(file);
+        const valid = section.every((line) => line.startsWith("+"));
+        if (valid) {
+          const content = section.map((line) => line.slice(1)).join("\n");
+          proof.expectedContentDigests[file] = [...new Set([contentDigest(content), contentDigest(`${content}\n`)])];
+        }
+        continue;
+      }
+      proof.replacePaths.push(file);
+      const before = stableFile(cwd, file);
+      if (!before) continue;
+      proof.preContentDigests[file] = before.digest;
+      const projected = applyPatchHunks(before.content, section);
+      if (projected !== undefined) proof.expectedContentDigests[file] = [contentDigest(projected)];
+    }
+  }
+}
+
+export function expectedModelMutationProof(
+  cwd: string,
+  toolName: string,
+  input: Record<string, unknown>,
+  targetPaths: string[]
+): ModelMutationProof {
+  const targets = [...new Set(targetPaths)];
+  const proof: ModelMutationProof = { expectedContentDigests: {}, preContentDigests: {}, fullContentPaths: [], replacePaths: [] };
+  const rememberFullContent = (file: string, contents: string[]) => {
+    if (!targets.includes(file) || contents.length === 0) return;
+    proof.fullContentPaths.push(file);
+    proof.expectedContentDigests[file] = [...new Set(contents.map(contentDigest))];
+  };
+  if (toolName === "write" && targets.length === 1 && typeof input.content === "string") {
+    rememberFullContent(targets[0], [input.content]);
+  } else if (toolName === "edit" && targets.length === 1) {
+    proof.replacePaths.push(targets[0]);
+    const before = stableFile(cwd, targets[0]);
+    const edits = inputEdits(input);
+    if (before) proof.preContentDigests[targets[0]] = before.digest;
+    const projected = before && edits ? applyUniqueReplacements(before.content, edits) : undefined;
+    if (projected !== undefined) proof.expectedContentDigests[targets[0]] = [contentDigest(projected)];
+  } else if (toolName === "apply_patch") {
+    patchProof(cwd, input, targets, proof);
+  }
+  proof.fullContentPaths = [...new Set(proof.fullContentPaths)].sort();
+  proof.replacePaths = [...new Set(proof.replacePaths)].sort();
+  return proof;
+}
+
+export function expectedModelMutationContentDigests(
+  cwd: string,
+  toolName: string,
+  input: Record<string, unknown>,
+  targetPaths: string[]
+): Record<string, string[]> {
+  return expectedModelMutationProof(cwd, toolName, input, targetPaths).expectedContentDigests;
+}
+
+export function currentFileContentDigests(cwd: string, paths: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const file of [...new Set(paths)]) {
+    const current = stableFile(cwd, file);
+    if (current) result[file] = current.digest;
+  }
+  return result;
+}