harnery 0.27.0 → 0.29.0

package/src/core/work/runner.ts

@@ -18,6 +18,7 @@ import {
   assertWorkflowUnchanged,
   boundedActor,
   newWorkflowRunId,
+  openOperatorFindings,
   readWorkItemIgnoringLease,
   type WorkAttempt,
 } from "./state.ts";
@@ -81,11 +82,18 @@ export async function runWorkItem(input: RunWorkItemInput): Promise<RunReport> {
       }
       prior = priorContext(coordRoot, latest);
     }
+    const open = openOperatorFindings(coordRoot, input.workId);
+    const findings = open.findings.map((finding) => ({
+      id: finding.id,
+      actor: open.actor,
+      statement: finding.statement,
+    }));
     const attemptContext: WorkflowAttemptContext = {
       schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
       number: attempt,
       trigger,
       ...(prior ? { prior } : {}),
+      ...(findings.length === 0 ? {} : { findings }),
     };
     const runId = newWorkflowRunId();
     appendWorkEvent(coordRoot, input.workId, {

package/src/core/work/state.ts

@@ -16,6 +16,7 @@ import { hostname } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { readWorkflowApproval } from "../workflow/approvals.ts";
 import { stableDigest } from "../workflow/durable-record.ts";
+import { WORKFLOW_JOURNAL_EVENT_BYTES, workflowJournalPath } from "../workflow/journal.ts";
 import { readWorkflowProof } from "../workflow/proof.ts";
 import { readWorkflowRunManifest, workflowScriptDigest } from "../workflow/run-state.ts";
 import { isWorkspaceBoundExecutionEvidence } from "../workflow/workspaces/validate.ts";
@@ -98,18 +99,35 @@ export interface WorkEvent {
   proof_sha256?: string;
   terminal_attestation_sha256?: string;
   accepted_unknowns?: string[];
+  /** Operator corrections raised with a reopen. Authored by a human against a
+   * prior attempt, carried into the next attempt, and open until disposed. */
+  findings?: WorkOperatorFinding[];
+  /** How an operator disposed of each open finding at acceptance. */
+  dispositions?: WorkFindingDisposition[];
   state?: WorkState;
   next_action?: WorkNextAction;
 }
 
+export interface WorkOperatorFinding {
+  id: string;
+  statement: string;
+}
+
+export interface WorkFindingDisposition {
+  id: string;
+  outcome: "fixed" | "deferred";
+  reason?: string;
+}
+
 export interface WorkAttempt {
   number: number;
   run_id: string;
   started_at: string;
   trigger?: WorkAttemptTrigger;
-  status: "running" | "parked" | "succeeded" | "failed" | "lost";
+  status: "running" | "parked" | "succeeded" | "failed" | "lost" | "journal_unreadable";
   approval_id?: string;
   proof_path?: string;
+  journal_error?: string;
 }
 
 export interface WorkProjection {
@@ -270,7 +288,12 @@ export function reconcileAllWorkItems(coordRoot: string, actor?: string): WorkRe
 export function acceptWorkItem(
   coordRoot: string,
   workId: string,
-  input: { actor?: string; reason?: string; acceptedUnknowns?: readonly string[] } = {},
+  input: {
+    actor?: string;
+    reason?: string;
+    acceptedUnknowns?: readonly string[];
+    dispositions?: readonly WorkFindingDisposition[];
+  } = {},
 ): WorkRecord {
   return appendGovernanceEvent(coordRoot, workId, "work.accepted", ["in_review"], input);
 }
@@ -292,7 +315,7 @@ export function cancelWorkItem(
 export function reopenWorkItem(
   coordRoot: string,
   workId: string,
-  input: { actor?: string; reason?: string } = {},
+  input: { actor?: string; reason?: string; findings?: readonly string[] } = {},
 ): WorkRecord {
   return appendGovernanceEvent(
     coordRoot,
@@ -303,6 +326,28 @@ export function reopenWorkItem(
   );
 }
 
+/** Findings raised by the most recent reopen that no later acceptance disposed
+ * of. Empty when the work was never reopened with findings. */
+export function openOperatorFindings(
+  coordRoot: string,
+  workId: string,
+): { actor: string; findings: WorkOperatorFinding[] } {
+  const events = readWorkEvents(coordRoot, workId);
+  let actor = "operator";
+  let open: WorkOperatorFinding[] = [];
+  for (const event of events) {
+    if (event.event === "work.reopened" && event.findings?.length) {
+      actor = event.actor;
+      open = event.findings.map((finding) => ({ ...finding }));
+    }
+    if (event.event === "work.accepted" && event.dispositions?.length) {
+      const disposed = new Set(event.dispositions.map((entry) => entry.id));
+      open = open.filter((finding) => !disposed.has(finding.id));
+    }
+  }
+  return { actor, findings: open };
+}
+
 export function assertWorkId(workId: string): void {
   if (!WORK_ID.test(workId)) throw new Error(`invalid work id ${JSON.stringify(workId)}`);
 }
@@ -418,6 +463,16 @@ function deriveWorkProjection(
     };
   }
   const attemptsRemaining = intent.max_attempts - attempts.length;
+  if (latest.status === "journal_unreadable") {
+    return {
+      ...base,
+      state: "blocked",
+      reason: `workflow attempt ${latest.number} journal is unreadable: ${
+        latest.journal_error ?? "unknown journal read error"
+      }`,
+      next_action: attemptsRemaining > 0 ? "retry" : "none",
+    };
+  }
   return {
     ...base,
     state: "blocked",
@@ -494,21 +549,36 @@ function inspectAttempt(
         : "failed";
     return attempt;
   }
-  const journalPath = join(coordRoot, ".harnery", "workflows", runId, "journal.jsonl");
+  const journalPath = workflowJournalPath(coordRoot, runId);
   if (existsSync(journalPath)) {
     let parked: string | undefined;
     let resumed = false;
-    for (const line of readBoundedLines(journalPath, MAX_EVENTS_BYTES, "workflow journal")) {
-      const value = parseObject(line, `workflow run ${runId} journal`);
-      if (value.event === "run.parked" && typeof value.approval_id === "string") {
-        parked = value.approval_id;
-        resumed = false;
+    try {
+      for (const line of readBoundedLines(
+        journalPath,
+        MAX_EVENTS_BYTES,
+        WORKFLOW_JOURNAL_EVENT_BYTES,
+        "workflow journal",
+      )) {
+        const value = parseObject(line, `workflow run ${runId} journal`);
+        if (value.event === "run.parked" && typeof value.approval_id === "string") {
+          parked = value.approval_id;
+          resumed = false;
+        }
+        if (value.event === "run.resume") resumed = true;
+      }
+      if (parked && !resumed) {
+        attempt.status = "parked";
+        attempt.approval_id = parked;
+        return attempt;
+      }
+    } catch (error) {
+      if (workflowResumeLeaseIsLive(coordRoot, runId)) {
+        attempt.status = "running";
+      } else {
+        attempt.status = "journal_unreadable";
+        attempt.journal_error = boundedJournalError((error as Error).message);
       }
-      if (value.event === "run.resume") resumed = true;
-    }
-    if (parked && !resumed) {
-      attempt.status = "parked";
-      attempt.approval_id = parked;
       return attempt;
     }
   }
@@ -537,7 +607,13 @@ function appendGovernanceEvent(
   workId: string,
   event: "work.accepted" | "work.cancelled" | "work.reopened",
   allowed: WorkState[],
-  input: { actor?: string; reason?: string; acceptedUnknowns?: readonly string[] },
+  input: {
+    actor?: string;
+    reason?: string;
+    acceptedUnknowns?: readonly string[];
+    findings?: readonly string[];
+    dispositions?: readonly WorkFindingDisposition[];
+  },
 ): WorkRecord {
   const releaseWork = event === "work.cancelled" ? undefined : acquireWorkLease(coordRoot, workId);
   const releaseEvent = acquireWorkEventLease(coordRoot, workId);
@@ -554,11 +630,19 @@ function appendGovernanceEvent(
       event === "work.accepted"
         ? acceptanceAuthority(coordRoot, current, input.acceptedUnknowns ?? [])
         : undefined;
+    const dispositions =
+      event === "work.accepted"
+        ? findingAuthority(coordRoot, workId, input.dispositions ?? [])
+        : undefined;
+    const findings =
+      event === "work.reopened" ? normalizeRaisedFindings(input.findings) : undefined;
     appendWorkEventUnderLease(coordRoot, workId, {
       event,
       actor: boundedActor(input.actor),
       reason: boundedOptional(input.reason, "work reason", MAX_REASON),
       ...acceptance,
+      ...(findings ? { findings } : {}),
+      ...(dispositions ? { dispositions } : {}),
     });
   } finally {
     releaseEvent();
@@ -567,6 +651,59 @@ function appendGovernanceEvent(
   return reconcileWorkItem(coordRoot, workId, input.actor);
 }
 
+/** Acceptance fails closed while an operator finding is open. The operator who
+ * raised it decides whether it was addressed; the team cannot mark its own. */
+function findingAuthority(
+  coordRoot: string,
+  workId: string,
+  dispositions: readonly WorkFindingDisposition[],
+): WorkFindingDisposition[] {
+  const open = openOperatorFindings(coordRoot, workId).findings;
+  if (open.length === 0) {
+    if (dispositions.length > 0) {
+      throw new Error(`work item ${workId} has no open operator finding to dispose`);
+    }
+    return [];
+  }
+  const byId = new Map(dispositions.map((entry) => [entry.id, entry]));
+  const undisposed = open.filter((finding) => !byId.has(finding.id));
+  if (undisposed.length > 0) {
+    throw new Error(
+      `work item ${workId} cannot be accepted while operator findings are undisposed: ${undisposed
+        .map((finding) => finding.id)
+        .join(", ")}`,
+    );
+  }
+  const known = new Set(open.map((finding) => finding.id));
+  return dispositions.map((entry) => {
+    if (!known.has(entry.id)) {
+      throw new Error(`work item ${workId} has no open operator finding ${entry.id}`);
+    }
+    if (entry.outcome !== "fixed" && entry.outcome !== "deferred") {
+      throw new Error(`operator finding ${entry.id} disposition must be fixed or deferred`);
+    }
+    if (entry.outcome === "deferred" && !entry.reason?.trim()) {
+      throw new Error(`deferring operator finding ${entry.id} requires a reason`);
+    }
+    return {
+      id: entry.id,
+      outcome: entry.outcome,
+      ...(entry.reason ? { reason: boundedString(entry.reason, "disposition reason", 500) } : {}),
+    };
+  });
+}
+
+function normalizeRaisedFindings(
+  statements: readonly string[] | undefined,
+): WorkOperatorFinding[] | undefined {
+  if (!statements || statements.length === 0) return undefined;
+  if (statements.length > 20) throw new Error("a reopen may raise at most 20 findings");
+  return statements.map((statement, index) => ({
+    id: `f${index + 1}`,
+    statement: boundedString(statement, `finding[${index}] statement`, 1_000),
+  }));
+}
+
 function acceptanceAuthority(
   coordRoot: string,
   current: WorkRecord,
@@ -712,16 +849,19 @@ function readWorkEvents(coordRoot: string, workId: string): WorkEvent[] {
   assertWorkId(workId);
   const path = join(workDir(coordRoot, workId), "events.jsonl");
   if (!existsSync(path)) return [];
-  const events = readBoundedLines(path, MAX_EVENTS_BYTES, `work item ${workId} events`).map(
-    (line, index) => {
-      const event = parseObject(
-        line,
-        `work item ${workId} event ${index + 1}`,
-      ) as unknown as WorkEvent;
-      validateWorkEvent(event, workId, index + 1);
-      return event;
-    },
-  );
+  const events = readBoundedLines(
+    path,
+    MAX_EVENTS_BYTES,
+    MAX_EVENT_BYTES,
+    `work item ${workId} events`,
+  ).map((line, index) => {
+    const event = parseObject(
+      line,
+      `work item ${workId} event ${index + 1}`,
+    ) as unknown as WorkEvent;
+    validateWorkEvent(event, workId, index + 1);
+    return event;
+  });
   validateWorkHistory(events, workId);
   return events;
 }
@@ -1026,7 +1166,12 @@ function writePrivateJson(path: string, value: unknown, maxBytes: number): void
   chmodSync(path, 0o600);
 }
 
-function readBoundedLines(path: string, maxBytes: number, field: string): string[] {
+function readBoundedLines(
+  path: string,
+  maxBytes: number,
+  maxRecordBytes: number,
+  field: string,
+): string[] {
   const size = statSync(path).size;
   if (size > maxBytes) throw new Error(`${field} exceeds ${maxBytes} bytes`);
   const body = readFileSync(path, "utf8");
@@ -1035,12 +1180,17 @@ function readBoundedLines(path: string, maxBytes: number, field: string): string
   const lines = body.split("\n").filter(Boolean);
   if (lines.length > MAX_EVENTS) throw new Error(`${field} exceeds ${MAX_EVENTS} records`);
   for (const line of lines) {
-    if (Buffer.byteLength(line) > MAX_EVENT_BYTES)
+    if (Buffer.byteLength(line) > maxRecordBytes)
       throw new Error(`${field} contains an oversized record`);
   }
   return lines;
 }
 
+function boundedJournalError(message: string): string {
+  const normalized = message.trim() || "unknown journal read error";
+  return normalized.length > MAX_REASON ? normalized.slice(0, MAX_REASON) : normalized;
+}
+
 function parseObject(input: string, field: string): Record<string, unknown> {
   try {
     const value = JSON.parse(input) as unknown;

package/src/core/workflow/approvals.ts

@@ -12,6 +12,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import type { PolicyEvaluation, PolicyRequestSummary, PolicyVerdict } from "../policy/index.ts";
+import { appendWorkflowJournalEvent } from "./journal.ts";
 
 export const WORKFLOW_APPROVAL_SCHEMA_VERSION = 1 as const;
 
@@ -222,19 +223,15 @@ function appendResolutionJournal(coordRoot: string, approval: WorkflowApproval):
     "journal.jsonl",
   );
   if (!existsSync(journalPath) || !approval.decision) return;
-  const event = {
-    schema_version: 1,
-    run_id: approval.request.run_id,
+  appendWorkflowJournalEvent(coordRoot, approval.request.run_id, "approval.resolved", {
     ts: approval.decision.decided_at,
-    event: "approval.resolved",
     stage: "",
     approval_id: approval.request.id,
     decision_id: approval.request.decision_id,
     verdict: approval.decision.verdict,
     actor: approval.decision.actor,
     reason: approval.decision.reason ?? null,
-  };
-  writeFileSync(journalPath, `${JSON.stringify(event)}\n`, { encoding: "utf8", flag: "a" });
+  });
 }
 
 function approvalRequestDigest(

package/src/core/workflow/attempt-context.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowAttemptFailureCause,
   WorkflowAttemptPriorContext,
   WorkflowAttemptUnresolvedCriterion,
+  WorkflowOperatorFinding,
 } from "./types.ts";
 import { WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION } from "./types.ts";
 
@@ -13,7 +14,12 @@ const MAX_ATTEMPTS = 100;
 const MAX_ERROR = 2_000;
 const MAX_CRITERIA = 50;
 const MAX_STATEMENT = 500;
-const CONTEXT_FIELDS = new Set(["schema_version", "number", "trigger", "prior"]);
+const MAX_FINDINGS = 20;
+const MAX_FINDING_STATEMENT = 1_000;
+const MAX_FINDING_ACTOR = 100;
+const FINDING_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const CONTEXT_FIELDS = new Set(["schema_version", "number", "trigger", "prior", "findings"]);
+const FINDING_FIELDS = new Set(["id", "actor", "statement"]);
 const PRIOR_FIELDS = new Set(["run_id", "causes", "error", "acceptance", "unresolved"]);
 const SUMMARY_FIELDS = new Set(["satisfied", "unsatisfied", "unknown", "total"]);
 const CRITERION_FIELDS = new Set(["id", "statement", "status"]);
@@ -34,6 +40,7 @@ export function normalizeWorkflowAttemptContext(value: unknown): WorkflowAttempt
   if (input.trigger !== "initial" && input.trigger !== "retry") {
     throw new Error('workflow attempt context trigger must be "initial" or "retry"');
   }
+  const findings = normalizeFindings(input.findings);
   if (input.trigger === "initial") {
     if (input.prior !== undefined) {
       throw new Error("initial workflow attempt context cannot contain prior evidence");
@@ -42,6 +49,7 @@ export function normalizeWorkflowAttemptContext(value: unknown): WorkflowAttempt
       schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
       number,
       trigger: "initial",
+      ...(findings.length === 0 ? {} : { findings }),
     };
   }
   if (number < 2) throw new Error("retry workflow attempt context number must be at least 2");
@@ -53,9 +61,43 @@ export function normalizeWorkflowAttemptContext(value: unknown): WorkflowAttempt
     number,
     trigger: "retry",
     prior: normalizePrior(input.prior),
+    ...(findings.length === 0 ? {} : { findings }),
   };
 }
 
+function normalizeFindings(value: unknown): WorkflowOperatorFinding[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_FINDINGS) {
+    throw new Error(
+      `workflow attempt findings must contain 1 to ${MAX_FINDINGS} entries when present`,
+    );
+  }
+  const ids = new Set<string>();
+  return value.map((candidate, index) => {
+    const input = objectValue(candidate, `workflow attempt finding[${index}]`);
+    rejectExtraFields(input, FINDING_FIELDS, `workflow attempt finding[${index}]`);
+    const id = requiredString(input.id, `workflow attempt finding[${index}].id`, 64);
+    if (!FINDING_ID.test(id)) {
+      throw new Error(`invalid workflow attempt finding id ${JSON.stringify(id)}`);
+    }
+    if (ids.has(id)) throw new Error(`duplicate workflow attempt finding id ${JSON.stringify(id)}`);
+    ids.add(id);
+    return {
+      id,
+      actor: requiredString(
+        input.actor,
+        `workflow attempt finding[${index}].actor`,
+        MAX_FINDING_ACTOR,
+      ),
+      statement: requiredString(
+        input.statement,
+        `workflow attempt finding[${index}].statement`,
+        MAX_FINDING_STATEMENT,
+      ),
+    };
+  });
+}
+
 export function freezeWorkflowAttemptContext(value: unknown): Readonly<WorkflowAttemptContext> {
   const normalized = normalizeWorkflowAttemptContext(value);
   if (normalized.prior) {
@@ -65,6 +107,10 @@ export function freezeWorkflowAttemptContext(value: unknown): Readonly<WorkflowA
     Object.freeze(normalized.prior.unresolved);
     Object.freeze(normalized.prior);
   }
+  if (normalized.findings) {
+    for (const finding of normalized.findings) Object.freeze(finding);
+    Object.freeze(normalized.findings);
+  }
   return Object.freeze(normalized);
 }
 

package/src/core/workflow/engine.ts

@@ -18,7 +18,7 @@
  */
 
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { snapshotRepo } from "../context/index.ts";
@@ -39,6 +39,7 @@ import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.ts";
 import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import { stableDigest } from "./durable-record.ts";
+import { appendWorkflowJournalEvent } from "./journal.ts";
 import {
   buildWorkflowProof,
   createEvidenceRecord,
@@ -73,7 +74,6 @@ import type {
   WorkflowSandboxProjectionEvidence,
   WorkflowWorkContext,
 } from "./types.ts";
-import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
 import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
 import { freezeWorkflowWorkContext } from "./work-context.ts";
 import {
@@ -81,7 +81,6 @@ import {
   attestWorkspaceFailure,
   resolveWorkspaceBinding,
 } from "./workspaces/execution.ts";
-import { appendWorkflowJournalEvent } from "./workspaces/state.ts";
 import type {
   WorkspaceAttestation,
   WorkspaceBinding,
@@ -526,15 +525,22 @@ async function executeWorkflow(
   const acceptanceIds = new Set(meta.acceptance.map((criterion) => criterion.id));
 
   const journal = (event: string, data: Record<string, unknown>): void => {
-    const line = JSON.stringify({
-      schema_version: WORKFLOW_PROOF_SCHEMA_VERSION,
-      run_id: runId,
-      ts: new Date().toISOString(),
-      event,
-      stage: currentStage,
+    appendWorkflowJournalEvent(opts.coordRoot, runId, event, { stage: currentStage, ...data });
+  };
+  const journalAgentEnd = (
+    data: Record<string, unknown>,
+    resultKind: "text" | "json",
+    result: unknown,
+  ): void => {
+    // The writer shrinks an oversized record itself and names what it dropped,
+    // so no per-call fallback is needed here. A digest rides along regardless so
+    // a shrunk record can still be tied back to the exact result.
+    journal("agent.end", {
       ...data,
+      result_kind: resultKind,
+      result_digest: digestResult(result, resultKind),
+      result,
     });
-    appendFileSync(journalPath, `${line}\n`, "utf8");
   };
 
   // Bounded concurrency gate shared by every spawn in the run — direct
@@ -913,17 +919,19 @@ async function executeWorkflow(
             agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
           agentProof.session_id = last.sessionId;
           agentProof.result = digestResult(last.text, "text");
-          journal("agent.end", {
-            id,
-            key,
-            attempts: attempt,
-            cost_usd: last.costUsd,
-            total_cost_usd: agentCostUsd,
-            duration_ms: last.durationMs,
-            session_id: last.sessionId,
-            result_kind: "text",
-            result: last.text,
-          });
+          journalAgentEnd(
+            {
+              id,
+              key,
+              attempts: attempt,
+              cost_usd: last.costUsd,
+              total_cost_usd: agentCostUsd,
+              duration_ms: last.durationMs,
+              session_id: last.sessionId,
+            },
+            "text",
+            last.text,
+          );
           return last.text;
         }
 
@@ -938,17 +946,19 @@ async function executeWorkflow(
             agentCostUsd > 0 || last.costUsd !== undefined ? agentCostUsd : undefined;
           agentProof.session_id = last.sessionId;
           agentProof.result = digestResult(parsed.value, "json");
-          journal("agent.end", {
-            id,
-            key,
-            attempts: attempt,
-            cost_usd: last.costUsd,
-            total_cost_usd: agentCostUsd,
-            duration_ms: last.durationMs,
-            session_id: last.sessionId,
-            result_kind: "json",
-            result: parsed.value,
-          });
+          journalAgentEnd(
+            {
+              id,
+              key,
+              attempts: attempt,
+              cost_usd: last.costUsd,
+              total_cost_usd: agentCostUsd,
+              duration_ms: last.durationMs,
+              session_id: last.sessionId,
+            },
+            "json",
+            parsed.value,
+          );
           return parsed.value;
         }
 
@@ -1296,7 +1306,12 @@ function loadResumeCache(
         result_kind?: "json" | "text";
         result?: unknown;
       };
-      if (e.event === "agent.end" && e.key && e.result_kind !== undefined) {
+      if (
+        e.event === "agent.end" &&
+        e.key &&
+        (e.result_kind === "json" || e.result_kind === "text") &&
+        "result" in e
+      ) {
         cache.set(e.key, { kind: e.result_kind, value: e.result });
       }
     } catch {