harnery 0.29.0 → 0.31.0

package/src/core/workflow/spawn-claude.ts

@@ -19,12 +19,12 @@
  */
 
 import { exec } from "../../lib/exec.ts";
-import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
-import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { builtinAdapterProfile, validateAdapterEffort } from "../adapters/profiles.ts";
+import type { AdapterInvocation, AdapterRawResult } from "../adapters/types.ts";
+import { notFoundError } from "./adapters.ts";
 import { buildChildEnv } from "./child-env.ts";
-import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 interface ClaudeEnvelope {
@@ -37,13 +37,13 @@ interface ClaudeEnvelope {
   errors?: string[];
 }
 
-export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
-  validateHarnessEffort("claude-code", req.effort);
+export function buildClaudeInvocation(req: SpawnRequest): AdapterInvocation {
+  validateAdapterEffort("claude-code", req.effort);
   if (req.filesystemPolicy) {
     // Declared unrepresentable: refuse rather than drop it silently (ADR 0039).
     resolveSandboxProjection(
       "claude-code",
-      builtinHarnessProfile("claude-code")?.sandboxProjection,
+      builtinAdapterProfile("claude-code")?.sandboxProjection,
       req.filesystemPolicy,
     );
   }
@@ -61,7 +61,7 @@ export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
   return { argv };
 }
 
-export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
+export function normalizeClaudeResult(raw: AdapterRawResult): SpawnResult {
   if (raw.timedOut) {
     return {
       ok: false,
@@ -70,7 +70,20 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
       error: `claude timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("claude-code"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return {
       ok: false,
       text: "",
@@ -79,11 +92,13 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
     };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `claude exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `claude exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
 
@@ -100,13 +115,17 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
   }
 
   if (envelope.is_error) {
+    const envelopeError = `${envelope.subtype ?? ""} ${(envelope.errors ?? []).join("; ")} ${String(
+      envelope.result ?? "",
+    )}`;
     return {
       ok: false,
       text: String(envelope.result ?? ""),
       sessionId: envelope.session_id,
       costUsd: envelope.total_cost_usd,
       durationMs: raw.durationMs,
-      error: `harness error (${envelope.subtype ?? "unknown"}): ${(envelope.errors ?? []).join("; ") || "see envelope"}`,
+      error: `adapter error (${envelope.subtype ?? "unknown"}): ${(envelope.errors ?? []).join("; ") || "see envelope"}`,
+      ...(isUpstreamFailureText(envelopeError) ? { class: "upstream" as const } : {}),
     };
   }
 
@@ -121,7 +140,7 @@ export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
 
 export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
   const t0 = Date.now();
-  let invocation: HarnessInvocation;
+  let invocation: AdapterInvocation;
   try {
     invocation = buildClaudeInvocation(req);
   } catch (error) {
@@ -129,7 +148,10 @@ export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<Spa
   }
   const r = await exec(invocation.argv, {
     cwd: req.cwd,
-    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    env: buildChildEnv(req.runId, {
+      subscriptionOnly: req.subscriptionOnly,
+      agentId: req.agentId,
+    }),
     timeout: req.timeoutMs,
   });
   return normalizeClaudeResult({ ...r, durationMs: Date.now() - t0 });

package/src/core/workflow/spawn-codex.ts

@@ -3,7 +3,7 @@
  * subprocess.
  *
  * Contract notes (LIVE-VERIFIED 2026-07-16 against codex-cli 0.144.5: flags
- * present, schema-gated triage + text stages round-trip via `--harness codex`):
+ * present, schema-gated triage + text stages round-trip via `--adapter codex`):
  * - `codex exec "<prompt>"` is the non-interactive mode.
  * - The final assistant message is captured via `--output-last-message <file>`
  *   (a temp file), which is far more drift-tolerant than parsing the
@@ -20,22 +20,22 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { exec } from "../../lib/exec.ts";
-import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
-import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { builtinAdapterProfile, validateAdapterEffort } from "../adapters/profiles.ts";
+import type { AdapterInvocation, AdapterRawResult } from "../adapters/types.ts";
+import { notFoundError } from "./adapters.ts";
 import { buildChildEnv } from "./child-env.ts";
-import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
-export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): HarnessInvocation {
-  validateHarnessEffort("codex", req.effort);
+export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): AdapterInvocation {
+  validateAdapterEffort("codex", req.effort);
   if (!resultFile) throw new Error("codex adapter requires a final-message result file");
   // Default stays workspace-write so an unprojected request is unchanged.
   const projection = req.filesystemPolicy
     ? resolveSandboxProjection(
         "codex",
-        builtinHarnessProfile("codex")?.sandboxProjection,
+        builtinAdapterProfile("codex")?.sandboxProjection,
         req.filesystemPolicy,
       )
     : undefined;
@@ -60,7 +60,7 @@ export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): Ha
   return { argv, resultFile };
 }
 
-export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
+export function normalizeCodexResult(raw: AdapterRawResult): SpawnResult {
   if (raw.timedOut) {
     return {
       ok: false,
@@ -69,15 +69,30 @@ export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
       error: `codex timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("codex"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `codex exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `codex exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
   return {
@@ -95,7 +110,7 @@ export const codexSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnRes
   );
 
   try {
-    let invocation: HarnessInvocation;
+    let invocation: AdapterInvocation;
     try {
       invocation = buildCodexInvocation(req, outFile);
     } catch (error) {
@@ -103,7 +118,10 @@ export const codexSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnRes
     }
     const r = await exec(invocation.argv, {
       cwd: req.cwd,
-      env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+      env: buildChildEnv(req.runId, {
+        subscriptionOnly: req.subscriptionOnly,
+        agentId: req.agentId,
+      }),
       timeout: req.timeoutMs,
     });
     return normalizeCodexResult({

package/src/core/workflow/spawn-cursor.ts

@@ -4,7 +4,7 @@
  *
  * Contract notes (LIVE-VERIFIED 2026-07-17 against cursor-agent
  * 2026.07.16-899851b: schema-gated triage + text stages round-trip via
- * `--harness cursor`, session_id parses from the envelope):
+ * `--adapter cursor`, session_id parses from the envelope):
  * - `cursor-agent -p "<prompt>" --output-format json` prints a single result
  *   envelope modeled on Claude Code's (`{type: "result", is_error, result,
  *   session_id, …}`).
@@ -20,12 +20,12 @@
  */
 
 import { exec } from "../../lib/exec.ts";
-import { builtinHarnessProfile, validateHarnessEffort } from "../harnesses/profiles.ts";
-import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { builtinAdapterProfile, validateAdapterEffort } from "../adapters/profiles.ts";
+import type { AdapterInvocation, AdapterRawResult } from "../adapters/types.ts";
+import { notFoundError } from "./adapters.ts";
 import { buildChildEnv } from "./child-env.ts";
-import { notFoundError } from "./harnesses.ts";
 import { resolveSandboxProjection } from "./sandbox-projection.ts";
-import { vendorFailureText } from "./spawn-failure.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
 interface CursorEnvelope {
@@ -53,13 +53,13 @@ export function parseCursorOutput(stdout: string): {
   }
 }
 
-export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
-  validateHarnessEffort("cursor", req.effort);
+export function buildCursorInvocation(req: SpawnRequest): AdapterInvocation {
+  validateAdapterEffort("cursor", req.effort);
   if (req.filesystemPolicy) {
     // Declared unrepresentable: refuse rather than drop it silently (ADR 0039).
     resolveSandboxProjection(
       "cursor",
-      builtinHarnessProfile("cursor")?.sandboxProjection,
+      builtinAdapterProfile("cursor")?.sandboxProjection,
       req.filesystemPolicy,
     );
   }
@@ -73,7 +73,7 @@ export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
   return { argv };
 }
 
-export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
+export function normalizeCursorResult(raw: AdapterRawResult): SpawnResult {
   if (raw.timedOut) {
     return {
       ok: false,
@@ -82,15 +82,30 @@ export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
       error: `cursor timed out after ${raw.durationMs}ms and was killed`,
     };
   }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("cursor"),
+      class: "environment",
+    };
+  }
   if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
     return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
   }
   if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
     return {
       ok: false,
       text: "",
       durationMs: raw.durationMs,
-      error: `cursor-agent exited ${raw.exitCode}: ${vendorFailureText(raw)}`,
+      error: `cursor-agent exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
     };
   }
 
@@ -102,6 +117,7 @@ export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
       sessionId: parsed.sessionId,
       durationMs: raw.durationMs,
       error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
+      ...(isUpstreamFailureText(parsed.text) ? { class: "upstream" as const } : {}),
     };
   }
   return {
@@ -114,7 +130,7 @@ export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
 
 export const cursorSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
   const t0 = Date.now();
-  let invocation: HarnessInvocation;
+  let invocation: AdapterInvocation;
   try {
     invocation = buildCursorInvocation(req);
   } catch (error) {
@@ -123,7 +139,10 @@ export const cursorSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnRe
 
   const r = await exec(invocation.argv, {
     cwd: req.cwd,
-    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    env: buildChildEnv(req.runId, {
+      subscriptionOnly: req.subscriptionOnly,
+      agentId: req.agentId,
+    }),
     timeout: req.timeoutMs,
   });
   return normalizeCursorResult({ ...r, durationMs: Date.now() - t0 });

package/src/core/workflow/spawn-failure.ts

@@ -1,5 +1,5 @@
 /**
- * Shared failure-text extraction for the harness spawn adapters.
+ * Shared failure-text extraction for the adapter spawn adapters.
  *
  * A vendor CLI prints its banner, resolved config, and startup warnings first,
  * and the reason it actually failed last. Every adapter used to keep the FIRST
@@ -26,3 +26,43 @@ export function vendorFailureText(
   const combined = parts.join("\n");
   return combined.length > maxChars ? `…${combined.slice(-maxChars)}` : combined;
 }
+
+// A 429 or 5xx status, but only where it sits in HTTP-status CONTEXT — not any
+// digits that merely happen to fall in that range. A bare-number match treats a
+// line number ("at line 500"), an item count ("got 429 items"), or a duration
+// ("after 502 seconds") as an upstream refusal, which wrongly withholds a charge
+// for a failure that was entirely our code. Three recognized shapes:
+//   1. after an "HTTP" label:  "HTTP 429", "HTTP/1.1 503 Service Unavailable"
+//   2. after a "status" label: "status 500", "status: 429", "status code 502"
+//   3. a bare status line:     "503 Service Unavailable" (code at line start,
+//      then a reason phrase) — the classic "<code> <Reason-Phrase>" shape.
+// The trailing `(?![0-9])` and the label/line-start anchors also keep a status
+// embedded in a longer number ("4295"/"5031") out. All 5xx are server-side; 429
+// is the only 4xx that means "reached and refused, retry later".
+const STATUS = "(?:429|5[0-9]{2})";
+const UPSTREAM_STATUS = new RegExp(
+  `(?:\\bHTTP\\b[/0-9. ]*|\\bstatus(?:\\s*code)?\\b[\\s:=]*)${STATUS}(?![0-9])` +
+    `|(?:^|\\n)\\s*${STATUS}\\s+[A-Za-z]`,
+  "i",
+);
+// Explicit vendor wording for the same conditions when a numeric status is
+// absent. Deliberately short — see isUpstreamFailureText.
+const UPSTREAM_PHRASES =
+  /circuit[ _-]?open|service unavailable|too many requests|rate[ _-]?limit|overloaded|bad gateway|gateway time-?out|internal server error/i;
+
+/**
+ * Whether failure text names an UPSTREAM refusal — the vendor was reached and
+ * refused (a 5xx/429 status or circuit-open wording), as opposed to a work
+ * failure (the model ran and produced a wrong or incomplete result).
+ *
+ * There is no structural upstream signal the way ENOENT structurally marks a
+ * missing binary, so this is the one text match in the classifier. It is kept
+ * SHORT and documented on purpose: a per-vendor regex zoo would rot, and a
+ * false positive here wrongly withholds a charge, so both the phrase list and
+ * the numeric match stay tight — the number must sit in HTTP-status context, not
+ * merely fall in the 429/5xx range. Anything it does not match falls through to
+ * a charged work failure.
+ */
+export function isUpstreamFailureText(text: string): boolean {
+  return UPSTREAM_STATUS.test(text) || UPSTREAM_PHRASES.test(text);
+}

package/src/core/workflow/specialists.ts

@@ -29,7 +29,7 @@ export function normalizeWorkflowSpecialists(
         `workflow specialist ${id} instructions`,
         MAX_INSTRUCTIONS,
       ),
-      harness: optional(profile.harness, `workflow specialist ${id} harness`),
+      adapter: optional(profile.adapter, `workflow specialist ${id} adapter`),
       model: optional(profile.model, `workflow specialist ${id} model`),
       effort: optional(profile.effort, `workflow specialist ${id} effort`),
       maxAttempts: positiveOptional(
@@ -64,7 +64,7 @@ export function resolveSpecialistAssignment(
     prompt: `${profile.instructions}\n\nAssignment:\n${prompt}`,
     opts: {
       specialist: opts.specialist,
-      harness: opts.harness ?? profile.harness,
+      adapter: opts.adapter ?? profile.adapter,
       model: opts.model ?? profile.model,
       effort: opts.effort ?? profile.effort,
       maxAttempts: opts.maxAttempts ?? profile.maxAttempts,

package/src/core/workflow/{journal.ts → transcript.ts}

@@ -3,27 +3,27 @@ import { dirname, join, resolve } from "node:path";
 import { fsyncParentDirectory, stableDigest } from "./durable-record.ts";
 
 // Limit for the JSON record body. The trailing newline delimiter is outside the
-// record and is not counted by readers after splitting journal lines.
-export const WORKFLOW_JOURNAL_EVENT_BYTES = 16 * 1024;
+// record and is not counted by readers after splitting transcript lines.
+export const WORKFLOW_TRANSCRIPT_EVENT_BYTES = 16 * 1024;
 
 /** Key under which a shrunk record names the fields it had to drop. */
-export const WORKFLOW_JOURNAL_OMITTED = "omitted_fields";
+export const WORKFLOW_TRANSCRIPT_OMITTED = "omitted_fields";
 
 const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
-export interface WorkflowJournalOmission {
+export interface WorkflowTranscriptOmission {
   field: string;
   bytes: number;
   sha256: string;
 }
 
-export function workflowJournalPath(coordRoot: string, runId: string): string {
+export function workflowTranscriptPath(coordRoot: string, runId: string): string {
   if (!RUN_ID.test(runId)) throw new Error(`invalid workflow run id ${JSON.stringify(runId)}`);
-  return join(resolve(coordRoot), ".harnery", "workflows", runId, "journal.jsonl");
+  return join(resolve(coordRoot), ".harnery", "workflows", runId, "transcript.jsonl");
 }
 
 /**
- * Append one journal record, always.
+ * Append one transcript record, always.
  *
  * A record that would exceed what a reader accepts has its largest fields
  * replaced by a digest and a byte count until it fits, and it names what it
@@ -35,14 +35,14 @@ export function workflowJournalPath(coordRoot: string, runId: string): string {
  * this limit by construction. Losing detail from a record is recoverable.
  * Losing the run that was writing it is not.
  */
-export function appendWorkflowJournalEvent(
+export function appendWorkflowTranscriptEvent(
   coordRoot: string,
   runId: string,
   event: string,
   data: Record<string, unknown>,
 ): void {
-  const path = workflowJournalPath(coordRoot, runId);
-  const record = fitWorkflowJournalRecord(
+  const path = workflowTranscriptPath(coordRoot, runId);
+  const record = fitWorkflowTranscriptRecord(
     { schema_version: 1, run_id: runId, ts: new Date().toISOString(), event },
     data,
   );
@@ -64,16 +64,16 @@ export function appendWorkflowJournalEvent(
  * The envelope is never dropped, so a record keeps its run id, timestamp, and
  * event name however much detail it loses. Exported for tests.
  */
-export function fitWorkflowJournalRecord(
+export function fitWorkflowTranscriptRecord(
   envelope: Record<string, unknown>,
   data: Record<string, unknown>,
 ): Record<string, unknown> {
   const candidate = { ...envelope, ...data };
-  if (Buffer.byteLength(JSON.stringify(candidate)) <= WORKFLOW_JOURNAL_EVENT_BYTES) {
+  if (Buffer.byteLength(JSON.stringify(candidate)) <= WORKFLOW_TRANSCRIPT_EVENT_BYTES) {
     return candidate;
   }
   const kept: Record<string, unknown> = { ...data };
-  const omitted: WorkflowJournalOmission[] = [];
+  const omitted: WorkflowTranscriptOmission[] = [];
   const bySize = Object.keys(data)
     .map((field) => ({ field, bytes: Buffer.byteLength(JSON.stringify(data[field]) ?? "") }))
     .sort((a, b) => b.bytes - a.bytes);
@@ -81,10 +81,10 @@ export function fitWorkflowJournalRecord(
   for (const { field, bytes } of bySize) {
     omitted.push({ field, bytes, sha256: stableDigest(data[field]) });
     delete kept[field];
-    const next = { ...envelope, ...kept, [WORKFLOW_JOURNAL_OMITTED]: omitted };
-    if (Buffer.byteLength(JSON.stringify(next)) <= WORKFLOW_JOURNAL_EVENT_BYTES) return next;
+    const next = { ...envelope, ...kept, [WORKFLOW_TRANSCRIPT_OMITTED]: omitted };
+    if (Buffer.byteLength(JSON.stringify(next)) <= WORKFLOW_TRANSCRIPT_EVENT_BYTES) return next;
   }
   // Every field dropped and still over: the omission list is itself the excess.
   // Keep the envelope and a count so the record stays parseable and honest.
-  return { ...envelope, [WORKFLOW_JOURNAL_OMITTED]: omitted.length };
+  return { ...envelope, [WORKFLOW_TRANSCRIPT_OMITTED]: omitted.length };
 }