harnery 0.37.0 → 0.38.0

package/src/core/agents/qa-signal.ts

@@ -0,0 +1,261 @@
+/**
+ * Per-session page-QA signal: the pointer that lets `agents status` report a
+ * verdict with the runner's own clock instead of leaving an operator to read
+ * session age as if it were QA time.
+ *
+ * The problem this closes: a status box showing `session 58m` invites the
+ * reading "page QA took 58 minutes". Session age measures the agent, not the
+ * run. So the runner's wall time is recorded here and rendered beside the
+ * verdict, and admission-queue wait is carried as a separate number because
+ * `wall_time_ms.total` is runner stages only and never includes the queue
+ * (see QaRunResult.wall_time_ms in the toolkit contracts).
+ *
+ * Layering: the qa-run matrix runner is toolkit tier (`src/lib/browser/**`)
+ * and must not import `src/core`, so the runner cannot write this pointer
+ * itself. The command layer owns the write and calls `recordQaSignal()` after
+ * a run finishes. Core importing toolkit *types* is the permitted direction.
+ *
+ * Storage: `<coordRoot>/.harnery/qa/<instance-id>.json`, one file per session
+ * generation, atomic temp+rename so a concurrent status read never sees a
+ * torn write. Last run wins; each run directory remains the authoritative
+ * record of the run itself.
+ *
+ * Every function here is best-effort by contract. A missing, unreadable,
+ * malformed, or partial pointer yields null rather than throwing: the status
+ * box must render even when QA state is broken.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type {
+  QaRunEvidenceSource,
+  QaRunResult,
+  QaRunVerdict,
+} from "../../lib/browser/qa-run-contracts.ts";
+import { resolveCoordRoot, resolveOwner } from "./coord-client.ts";
+
+export const QA_SIGNAL_SCHEMA_VERSION = 1 as const;
+
+/** Pointers older than this render as `stale (<age>)` and nothing else: an
+ * age-of-day-old verdict says nothing about the page as it stands now, and
+ * showing its timings beside a current session invites the same conflation
+ * this signal exists to prevent. */
+export const QA_SIGNAL_STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/** Timings split the way the result contract splits them: `total` is runner
+ * stages only, `queue` is admission wait before any browser work and is never
+ * part of `total`. */
+export interface QaSignalWallTime {
+  total: number;
+  queue?: number;
+}
+
+export interface QaSignalPointer {
+  schema_version: typeof QA_SIGNAL_SCHEMA_VERSION;
+  run_id: string;
+  verdict: QaRunVerdict;
+  evidence_source: QaRunEvidenceSource;
+  /** ISO-8601 UTC instant the run completed. */
+  completed_at: string;
+  /** Absolute run directory holding the authoritative result document. */
+  out_dir: string;
+  wall_time_ms: QaSignalWallTime;
+  target: string;
+}
+
+const INSTANCE_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const VERDICTS: readonly QaRunVerdict[] = ["passed", "failed", "incomplete"];
+const EVIDENCE_SOURCES: readonly QaRunEvidenceSource[] = ["runner", "manual"];
+
+/**
+ * Absolute path of one session's QA pointer. Throws on an instance id that
+ * could escape the directory; callers in this module treat that as "no
+ * pointer" rather than propagating it.
+ */
+export function qaSignalPath(coordRoot: string, instanceId: string): string {
+  if (!INSTANCE_ID_PATTERN.test(instanceId)) {
+    throw new Error("instance_id must be 1-128 ASCII letters, digits, hyphens, or underscores");
+  }
+  const directory = resolve(coordRoot, ".harnery", "qa");
+  const candidate = resolve(directory, `${instanceId}.json`);
+  if (!candidate.startsWith(`${directory}/`)) {
+    throw new Error("resolved qa signal path escapes the qa directory");
+  }
+  return candidate;
+}
+
+export interface QaSignalTarget {
+  /** Defaults to the resolved coordination root. */
+  coordRoot?: string | null;
+  /** Defaults to the current session's instance id. */
+  instanceId?: string | null;
+}
+
+function resolveTarget(target: QaSignalTarget): { coordRoot: string; instanceId: string } | null {
+  const coordRoot = target.coordRoot ?? resolveCoordRoot();
+  const instanceId = target.instanceId ?? resolveOwner();
+  if (!coordRoot || !instanceId) return null;
+  return { coordRoot, instanceId };
+}
+
+/**
+ * Write the pointer for one completed run. Returns what was written, or null
+ * when the session/root could not be resolved or the write failed — a QA run
+ * must never fail because its status breadcrumb could not be recorded.
+ */
+export function recordQaSignal(
+  result: QaRunResult,
+  target: QaSignalTarget = {},
+): QaSignalPointer | null {
+  try {
+    const resolved = resolveTarget(target);
+    if (!resolved) return null;
+    const pointer: QaSignalPointer = {
+      schema_version: QA_SIGNAL_SCHEMA_VERSION,
+      run_id: result.run.run_id,
+      verdict: result.verdict,
+      evidence_source: result.evidence_source,
+      completed_at: result.run.completed_at,
+      out_dir: result.run.out_dir,
+      wall_time_ms: {
+        total: result.wall_time_ms.total,
+        ...(typeof result.wall_time_ms.queue === "number"
+          ? { queue: result.wall_time_ms.queue }
+          : {}),
+      },
+      target: result.target,
+    };
+    const path = qaSignalPath(resolved.coordRoot, resolved.instanceId);
+    mkdirSync(resolve(path, ".."), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(pointer, null, 2)}\n`, "utf8");
+    renameSync(tmp, path);
+    return pointer;
+  } catch {
+    return null;
+  }
+}
+
+/** Read one session's pointer. Null when absent, unreadable, or malformed. */
+export function readQaSignal(target: QaSignalTarget = {}): QaSignalPointer | null {
+  try {
+    const resolved = resolveTarget(target);
+    if (!resolved) return null;
+    const path = qaSignalPath(resolved.coordRoot, resolved.instanceId);
+    if (!existsSync(path)) return null;
+    return parseQaSignal(JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an untrusted pointer document. Fail-closed: a partial document —
+ * the shape a torn write or a schema change produces — is not a pointer, and
+ * renders no row at all rather than a half-true one.
+ */
+export function parseQaSignal(document: unknown): QaSignalPointer | null {
+  if (!document || typeof document !== "object" || Array.isArray(document)) return null;
+  const value = document as Record<string, unknown>;
+  if (value.schema_version !== QA_SIGNAL_SCHEMA_VERSION) return null;
+  if (typeof value.run_id !== "string" || value.run_id.length === 0) return null;
+  if (!VERDICTS.includes(value.verdict as QaRunVerdict)) return null;
+  if (!EVIDENCE_SOURCES.includes(value.evidence_source as QaRunEvidenceSource)) return null;
+  if (typeof value.completed_at !== "string" || Number.isNaN(Date.parse(value.completed_at))) {
+    return null;
+  }
+  if (typeof value.out_dir !== "string" || value.out_dir.length === 0) return null;
+  if (typeof value.target !== "string" || value.target.length === 0) return null;
+  const wall = value.wall_time_ms;
+  if (!wall || typeof wall !== "object" || Array.isArray(wall)) return null;
+  const { total, queue } = wall as Record<string, unknown>;
+  if (typeof total !== "number" || !Number.isFinite(total) || total < 0) return null;
+  if (queue !== undefined && (typeof queue !== "number" || !Number.isFinite(queue) || queue < 0)) {
+    return null;
+  }
+  return {
+    schema_version: QA_SIGNAL_SCHEMA_VERSION,
+    run_id: value.run_id,
+    verdict: value.verdict as QaRunVerdict,
+    evidence_source: value.evidence_source as QaRunEvidenceSource,
+    completed_at: value.completed_at,
+    out_dir: value.out_dir,
+    wall_time_ms: { total, ...(typeof queue === "number" ? { queue } : {}) },
+    target: value.target,
+  };
+}
+
+/**
+ * Coarse single-unit age, matching the status box's existing age vocabulary
+ * (`4m`, `3h`, `2d`). Deliberately coarser than the duration formatter: an
+ * operator reads age to judge relevance, not to compare timings.
+ */
+export function formatQaSignalAge(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.floor(seconds / 86400)}d`;
+}
+
+/**
+ * Duration in the units an operator compares runs by. Seconds stay seconds up
+ * to two minutes so a 90-second run reads `90s` rather than being rounded into
+ * a minute bucket that hides the difference between fast runs.
+ */
+export function formatQaSignalDuration(ms: number): string {
+  const value = Math.max(0, ms);
+  if (value < 120_000) return `${Math.round(value / 1000)}s`;
+  if (value < 3_600_000) return `${Math.round(value / 60_000)}m`;
+  const hours = Math.floor(value / 3_600_000);
+  const minutes = Math.round((value % 3_600_000) / 60_000);
+  return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+}
+
+/**
+ * Render the status-box `qa` value, or null when there is nothing honest to
+ * say. Three shapes:
+ *   - fresh runner evidence: `passed 4m ago · 90s runner (2m queued)`
+ *   - fresh manual evidence: `manual 12m ago · not a pass`
+ *   - anything over the staleness horizon: `stale (2d)`
+ *
+ * Manual evidence never reports a verdict or a runner clock: nothing
+ * re-executable ran, so the contract caps it below a pass and there is no
+ * runner time to attribute.
+ */
+export function formatQaSignalRow(
+  pointer: QaSignalPointer | null,
+  now: number = Date.now(),
+): string | null {
+  if (!pointer) return null;
+  const completedAt = Date.parse(pointer.completed_at);
+  if (Number.isNaN(completedAt)) return null;
+  const ageMs = Math.max(0, now - completedAt);
+  const age = formatQaSignalAge(ageMs);
+  if (ageMs > QA_SIGNAL_STALE_AFTER_MS) return `stale (${age})`;
+  if (pointer.evidence_source === "manual") return `manual ${age} ago · not a pass`;
+  const runner = `${formatQaSignalDuration(pointer.wall_time_ms.total)} runner`;
+  const queued =
+    typeof pointer.wall_time_ms.queue === "number" && pointer.wall_time_ms.queue > 0
+      ? ` (${formatQaSignalDuration(pointer.wall_time_ms.queue)} queued)`
+      : "";
+  return `${pointer.verdict} ${age} ago · ${runner}${queued}`;
+}
+
+/**
+ * The whole status-box contribution in one best-effort call: read this
+ * session's pointer and render its row. Null means render no `qa` row.
+ */
+export function qaSignalStatusRow(
+  target: QaSignalTarget = {},
+  now: number = Date.now(),
+): { value: string; pointer: QaSignalPointer } | null {
+  try {
+    const pointer = readQaSignal(target);
+    const value = formatQaSignalRow(pointer, now);
+    if (!pointer || !value) return null;
+    return { value, pointer };
+  } catch {
+    return null;
+  }
+}

package/src/core/agents/session-name-display.ts

@@ -8,6 +8,7 @@
 export interface SessionNameDisplayState {
   suggested_session_name?: string;
   session_name_seen_for?: string;
+  session_name_display_requested_for?: string;
 }
 
 export const SESSION_NAME_DISPLAY_NOTE =
@@ -21,6 +22,45 @@ export function sessionNameDisplayPending(
   return name;
 }
 
+/**
+ * Every title whose exact display satisfies the current latch.
+ *
+ * The pending title always counts. The title the agent was last instructed to
+ * display also counts, because the harness — not the agent — is what changed
+ * the target after asking. Accepting it costs nothing the operator can see: a
+ * clean one-line block did open that reply. Refusing it left Cursor sessions
+ * permanently latched, since no Cursor surface can re-open a missed window.
+ */
+export function sessionNameDisplayAcceptedNames(
+  row: SessionNameDisplayState | null | undefined,
+): string[] {
+  const pending = sessionNameDisplayPending(row);
+  if (!pending) return [];
+  const requested = row?.session_name_display_requested_for;
+  return requested && requested !== pending ? [pending, requested] : [pending];
+}
+
+/**
+ * Match assistant text against any accepted title and report which one closed
+ * the latch, so a drifted display can be stamped against the pending title and
+ * logged as drift rather than silently discarded.
+ */
+export function matchSessionNameDisplay(
+  row: SessionNameDisplayState | null | undefined,
+  text: string | undefined,
+  startsWithBlock: (
+    text: string,
+    expectedName: string,
+  ) => boolean = assistantTextStartsWithSessionNameBlock,
+): { pending: string; displayed: string } | null {
+  if (!text) return null;
+  const accepted = sessionNameDisplayAcceptedNames(row);
+  const pending = accepted[0];
+  if (!pending) return null;
+  const displayed = accepted.find((candidate) => startsWithBlock(text, candidate));
+  return displayed ? { pending, displayed } : null;
+}
+
 export function sessionNameDisplayBlock(name: string): string {
   return `\`\`\`\n${name}\n\`\`\``;
 }
@@ -80,10 +120,16 @@ function responseContainsSessionNameMint(
           return true;
         }
       } catch {
-        // Wrapper prose and partial JSON are not authoritative mint evidence.
+        // Fall through to the textual check below.
       }
     }
-    return false;
+    // The mint command's stdout often reaches the transcript mangled: cut
+    // short by `cut`/`head -c`, or with a tail-truncated first line. Whole-JSON
+    // parsing then fails even though the name and the mint flag are both
+    // legible, and a session that did mint can never latch. Accept the text
+    // when the exact quoted name sits under its key AND a mint flag is true;
+    // ordinary status output carries the name without any flag.
+    return textCarriesSessionNameMint(value, name);
   }
 
   if (typeof value !== "object") return false;
@@ -107,16 +153,41 @@ function responseContainsSessionNameMint(
   );
 }
 
+const MINT_FLAG_PATTERN = /"(?:first_of_session|name_reminted|session_name_retry)"\s*:\s*true\b/;
+
+function textCarriesSessionNameMint(text: string, name: string): boolean {
+  const quotedName = JSON.stringify(name);
+  const keyIndex = text.indexOf('"suggested_session_name"');
+  if (keyIndex < 0) return false;
+  const afterKey = text.slice(keyIndex + '"suggested_session_name"'.length);
+  const valueMatch = /^\s*:\s*("(?:[^"\\]|\\.)*")/.exec(afterKey);
+  if (!valueMatch || valueMatch[1] !== quotedName) return false;
+  return MINT_FLAG_PATTERN.test(text);
+}
+
 /**
- * Accept the exact unlabelled block Harnery requests. `text` and `plaintext`
- * are tolerated for older prompts, but the code block may contain only the
- * suggested name and must be the first non-whitespace user-facing content.
+ * A leading fenced block whose only line is the suggested name.
+ *
+ * What the contract protects is what the operator sees: the reply opens with a
+ * code block containing exactly the title, so it renders as one clean
+ * copy-pasteable line. The fence's info string changes none of that, so any
+ * single-word language tag passes. Restricting it to `text`/`plaintext` meant a
+ * model that wrote ```txt or ```markdown produced a display the operator could
+ * read perfectly while the latch refused to close — and since nothing else can
+ * close a Cursor latch, that mismatch stranded the whole session.
+ *
+ * Still exact in every load-bearing way: the block is the first user-facing
+ * content, holds one line, and that line equals the name. The backreference
+ * requires the closing fence to match the opening run, so a longer fence cannot
+ * be closed by a shorter one.
  */
+const LEADING_SESSION_NAME_BLOCK =
+  /^(`{3,})[ \t]*[A-Za-z0-9_.+#-]*[ \t]*\n([^\n]*)\n\1[ \t]*(?:\n|$)/;
+
 export function assistantTextStartsWithSessionNameBlock(text: string, name: string): boolean {
   if (!text || !name) return false;
   const normalized = text.replace(/\r\n?/g, "\n").trimStart();
-  const match = /^```(?:text|plaintext)?[ \t]*\n([^\n]*)\n```(?:[ \t]*(?:\n|$))/.exec(normalized);
-  return match?.[1] === name;
+  return LEADING_SESSION_NAME_BLOCK.exec(normalized)?.[2] === name;
 }
 
 /**

package/src/core/agents/state/heartbeat-reader.ts

@@ -33,6 +33,13 @@ export interface Heartbeat {
   session_name_seen_at?: string;
   /** The specific suggested name proven present by the sighting stamp. */
   session_name_seen_for?: string;
+  /**
+   * The suggested name the agent was last actually instructed to display.
+   * Usually identical to `suggested_session_name`; it differs only when the
+   * title changed after the instruction went out, and a display of it still
+   * counts so that drift cannot strand the latch.
+   */
+  session_name_display_requested_for?: string;
   last_status_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;

package/src/core/agents/state/heartbeat-writer.ts

@@ -180,6 +180,29 @@ export function stampSessionNameSeen(
   }));
 }
 
+/**
+ * Remember which title the agent was actually asked to display.
+ *
+ * The gate can only ask for a display through the PostToolUse instruction, and
+ * the title it names can change afterwards (an assigned-name rewrite of an
+ * `Agent unknown - ...` suggestion, a lifecycle re-mint, a rebuilt cache that
+ * re-minted from the current task). Without this record the agent's correct
+ * display of the title it was handed matches nothing, the latch never closes,
+ * and on Cursor no later surface can repair it.
+ */
+export function stampSessionNameRequested(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
+): Heartbeat | null {
+  if (!name) return null;
+  return mutate(coordRoot, instanceId, (hb) =>
+    hb.session_name_display_requested_for === name
+      ? hb
+      : { ...hb, session_name_display_requested_for: name },
+  );
+}
+
 export function releaseClaim(
   coordRoot: string,
   instanceId: string,

package/src/core/agents/state/live-coordination-view.ts

@@ -197,6 +197,7 @@ export function projectHeartbeatV3(
     suggested_session_name: cache?.suggested_session_name,
     session_name_seen_at: cache?.session_name_seen_at,
     session_name_seen_for: cache?.session_name_seen_for,
+    session_name_display_requested_for: cache?.session_name_display_requested_for,
     workflow_run_id: generation.run_id,
     workflow_agent_id: generation.workflow_agent_id,
     parent_instance_id: parent ? nativeInstanceIdV3(parent.instance_id) : undefined,

package/src/core/agents/state/live-coordination-writer.ts

@@ -107,6 +107,11 @@ function materializeLiveCoordinationHeartbeat(
           ...(current.session_name_seen_at
             ? { session_name_seen_at: current.session_name_seen_at }
             : {}),
+          ...(current.session_name_display_requested_for
+            ? {
+                session_name_display_requested_for: current.session_name_display_requested_for,
+              }
+            : {}),
         }
       : {};
   const materialized: V3HeartbeatMaterialization = {

package/src/core/artifacts/constants.ts

@@ -1,4 +1,4 @@
 /** Read-only artifact layout constants safe for browser-side server modules. */
 export const ARTIFACTS_DIR = ".harnery/artifacts";
 export const ARTIFACT_MANIFEST = ".harnery-artifact.json";
-export const ARTIFACT_SCHEMA_VERSION = 1 as const;
+export const ARTIFACT_SCHEMA_VERSION = 2 as const;