harnery 0.36.0 → 0.38.0

package/src/core/agents/mailbox.ts

@@ -0,0 +1,373 @@
+/**
+ * Name-addressed durable mailbox.
+ *
+ * Peer messaging used to require a live recipient: the sender resolved a name
+ * to a running instance and wrote into that instance's journal. Two failures
+ * followed from that. A message to a name whose session had ended was refused
+ * outright, so the sender spent a long sequence of discovery calls looking for
+ * somewhere else to put it. A message to a live peer was accepted but never
+ * shown to them, because nothing surfaces another session's journal.
+ *
+ * This module addresses the durable persona name instead of the instance, so a
+ * message can be queued before its recipient exists. Delivery happens on the
+ * recipient's side: their next SessionStart or prompt drains the queue, shows
+ * the messages, and records them in their journal.
+ *
+ * Storage: `.harnery/mailbox/<slug>.jsonl`, one JSON record per line, appended
+ * by senders and removed by an atomic claim on the recipient's side. Delivered
+ * records are appended to `.harnery/mailbox/delivered/<slug>.jsonl` for audit.
+ *
+ * Related but distinct: `core/inbox` is an instance-keyed transport with a
+ * storage-framework service behind it. This mailbox is name-keyed, file-only,
+ * and follows the same shape as council manifests and journals.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+import { lookupByName } from "../../lib/identities/index.ts";
+import { resolveBinName } from "../config.ts";
+import { readLiveCoordinationRows } from "./state/live-coordination-view.ts";
+import { COORD_NAMES } from "./state/names.ts";
+
+export const MAILBOX_MESSAGE_SCHEMA = "harnery.mailbox-message/v1" as const;
+
+/** Per-message body ceiling. Larger payloads belong in a managed artifact, with
+ * the path sent as the message. */
+export const MAX_BODY_BYTES = 4000;
+/** Pending messages held for one name before senders are refused. */
+export const MAX_PENDING = 25;
+/** Delivered-archive ceiling; the file is truncated from the head past this. */
+const MAX_DELIVERED_BYTES = 256 * 1024;
+
+export interface MailboxMessageV1 {
+  schema: typeof MAILBOX_MESSAGE_SCHEMA;
+  message_id: string;
+  /** Bare display name the sender addressed (registry casing when known). */
+  to_name: string;
+  from_name: string;
+  from_instance_id: string;
+  created_at: string;
+  body: string;
+  /** True when the sender already appended this to a live recipient's journal,
+   * so the drain surfaces it without writing a duplicate entry. */
+  journaled: boolean;
+}
+
+export type MailboxCapacityReason = "body_limit" | "pending_limit";
+
+export class MailboxCapacityError extends Error {
+  constructor(
+    readonly reason_code: MailboxCapacityReason,
+    readonly current: number,
+    readonly limit: number,
+  ) {
+    super(
+      `mailbox capacity ${reason_code}: ${current}/${limit}; write the payload to a managed artifact and send its path instead`,
+    );
+    this.name = "MailboxCapacityError";
+  }
+}
+
+/** Strip an `agent-` prefix and normalize to the registry's bare form. */
+export function bareAgentName(raw: string): string {
+  const trimmed = raw.trim();
+  return trimmed.toLowerCase().startsWith("agent-") ? trimmed.slice("agent-".length) : trimmed;
+}
+
+/** Filesystem-safe slug for a name. Rejects anything that could escape the
+ * mailbox directory rather than sanitizing it into a different agent's file. */
+function slugFor(name: string): string {
+  const bare = bareAgentName(name).toLowerCase();
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(bare)) {
+    throw new Error(`invalid agent name for mailbox addressing: ${JSON.stringify(name)}`);
+  }
+  return bare;
+}
+
+export function mailboxDir(coordRoot: string): string {
+  return resolve(coordRoot, ".harnery", "mailbox");
+}
+
+export function mailboxPath(coordRoot: string, name: string): string {
+  return join(mailboxDir(coordRoot), `${slugFor(name)}.jsonl`);
+}
+
+function deliveredPath(coordRoot: string, name: string): string {
+  return join(mailboxDir(coordRoot), "delivered", `${slugFor(name)}.jsonl`);
+}
+
+function parseLines(content: string): MailboxMessageV1[] {
+  const out: MailboxMessageV1[] = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as MailboxMessageV1;
+      if (parsed?.schema === MAILBOX_MESSAGE_SCHEMA) out.push(parsed);
+    } catch {
+      /* skip a torn line rather than losing the whole mailbox */
+    }
+  }
+  return out;
+}
+
+/** Every name a message may be addressed to: live sessions, the durable
+ * identity registry, and the built-in name pool. A name outside all three is a
+ * typo, and queueing it would silently swallow the message. */
+export function isAddressableName(coordRoot: string, name: string): boolean {
+  const bare = bareAgentName(name).toLowerCase();
+  if (!bare) return false;
+  if (COORD_NAMES.some((n) => n.toLowerCase() === bare)) return true;
+  if (lookupByName(bare, coordRoot)) return true;
+  try {
+    return readLiveCoordinationRows(coordRoot).some((r) => (r.name ?? "").toLowerCase() === bare);
+  } catch {
+    return false;
+  }
+}
+
+/** Names close enough to a miss to be worth suggesting (prefix or one edit). */
+export function suggestNames(coordRoot: string, name: string, limit = 5): string[] {
+  const bare = bareAgentName(name).toLowerCase();
+  const known = new Set<string>(COORD_NAMES);
+  try {
+    for (const row of readLiveCoordinationRows(coordRoot)) if (row.name) known.add(row.name);
+  } catch {
+    /* live rows are advisory here */
+  }
+  const scored: Array<{ name: string; distance: number }> = [];
+  for (const candidate of known) {
+    const lower = candidate.toLowerCase();
+    if (lower.startsWith(bare.slice(0, 2)) || editDistance(lower, bare) <= 2) {
+      scored.push({ name: candidate, distance: editDistance(lower, bare) });
+    }
+  }
+  scored.sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return scored.slice(0, limit).map((s) => s.name);
+}
+
+function editDistance(a: string, b: string): number {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let prev = Array.from({ length: cols }, (_, i) => i);
+  for (let i = 1; i < rows; i++) {
+    const curr = [i, ...Array.from({ length: cols - 1 }, () => 0)];
+    for (let j = 1; j < cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1]! + 1, prev[j]! + 1, prev[j - 1]! + cost);
+    }
+    prev = curr;
+  }
+  return prev[cols - 1]!;
+}
+
+export interface QueueInput {
+  coordRoot: string;
+  toName: string;
+  fromName: string;
+  fromInstanceId: string;
+  body: string;
+  journaled?: boolean;
+}
+
+export interface QueueResult {
+  message: MailboxMessageV1;
+  path: string;
+  pending: number;
+}
+
+/**
+ * Append one message to a name's mailbox. Throws `MailboxCapacityError` when
+ * the body or the pending queue is over its ceiling; the caller turns that into
+ * an actionable CLI error.
+ */
+export function queueMailboxMessage(input: QueueInput): QueueResult {
+  const body = input.body.trim();
+  const bodyBytes = Buffer.byteLength(body, "utf8");
+  if (bodyBytes > MAX_BODY_BYTES) {
+    throw new MailboxCapacityError("body_limit", bodyBytes, MAX_BODY_BYTES);
+  }
+
+  const path = mailboxPath(input.coordRoot, input.toName);
+  mkdirSync(mailboxDir(input.coordRoot), { recursive: true });
+  const existing = existsSync(path) ? parseLines(readFileSync(path, "utf8")) : [];
+  if (existing.length >= MAX_PENDING) {
+    throw new MailboxCapacityError("pending_limit", existing.length, MAX_PENDING);
+  }
+
+  // Preserve registry casing when the persona is known, so the recipient sees
+  // their own name spelled the way it is everywhere else.
+  const identity = lookupByName(input.toName, input.coordRoot);
+  const message: MailboxMessageV1 = {
+    schema: MAILBOX_MESSAGE_SCHEMA,
+    message_id: randomUUID(),
+    to_name: identity?.name ?? bareAgentName(input.toName),
+    from_name: input.fromName,
+    from_instance_id: input.fromInstanceId,
+    created_at: new Date().toISOString(),
+    body,
+    journaled: input.journaled ?? false,
+  };
+  appendFileSync(path, `${JSON.stringify(message)}\n`, "utf8");
+  return { message, path, pending: existing.length + 1 };
+}
+
+/** Pending messages for a name, without claiming them. */
+export function peekMailbox(coordRoot: string, name: string): MailboxMessageV1[] {
+  let path: string;
+  try {
+    path = mailboxPath(coordRoot, name);
+  } catch {
+    return [];
+  }
+  if (!existsSync(path)) return [];
+  try {
+    return parseLines(readFileSync(path, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Claim and return every pending message for a name.
+ *
+ * The claim is an atomic rename, so two sessions sharing a name cannot deliver
+ * the same message twice: whichever rename wins owns the batch. Claimed records
+ * are appended to the delivered archive before the claim file is removed, so a
+ * crash between the two leaves an auditable copy rather than a silent loss.
+ */
+export function drainMailbox(coordRoot: string, name: string): MailboxMessageV1[] {
+  let path: string;
+  try {
+    path = mailboxPath(coordRoot, name);
+  } catch {
+    return [];
+  }
+  // Heal first: a claim file left by a crashed reader may hold the only copy of
+  // a message for this very name, and sweeping after the existence check would
+  // skip it whenever the live queue is empty.
+  sweepStaleClaims(coordRoot);
+  if (!existsSync(path)) return [];
+
+  const claim = `${path}.claim-${process.pid}-${Date.now()}`;
+  try {
+    renameSync(path, claim);
+  } catch {
+    // Another reader claimed it first, or the file vanished. Either way there
+    // is nothing for this caller to deliver.
+    return [];
+  }
+
+  let messages: MailboxMessageV1[] = [];
+  try {
+    messages = parseLines(readFileSync(claim, "utf8"));
+  } catch {
+    messages = [];
+  }
+
+  if (messages.length > 0) {
+    try {
+      const archive = deliveredPath(coordRoot, name);
+      mkdirSync(join(mailboxDir(coordRoot), "delivered"), { recursive: true });
+      const deliveredAt = new Date().toISOString();
+      appendFileSync(
+        archive,
+        `${messages.map((m) => JSON.stringify({ ...m, delivered_at: deliveredAt })).join("\n")}\n`,
+        "utf8",
+      );
+      trimArchive(archive);
+    } catch {
+      /* audit copy is best-effort; never block delivery on it */
+    }
+  }
+
+  try {
+    unlinkSync(claim);
+  } catch {
+    /* a leftover claim is re-queued by the next drain's sweep */
+  }
+  return messages;
+}
+
+/** Re-queue any claim file left behind by a crashed reader (older than 5 min),
+ * so a killed session cannot strand a message. Runs at the head of every drain. */
+function sweepStaleClaims(coordRoot: string): void {
+  const dir = mailboxDir(coordRoot);
+  if (!existsSync(dir)) return;
+  const cutoff = Date.now() - 5 * 60_000;
+  try {
+    for (const file of readdirSync(dir)) {
+      const marker = file.indexOf(".jsonl.claim-");
+      if (marker === -1) continue;
+      const full = join(dir, file);
+      let mtime: number;
+      try {
+        mtime = statSync(full).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (mtime > cutoff) continue;
+      const owner = join(dir, `${file.slice(0, marker)}.jsonl`);
+      try {
+        const content = readFileSync(full, "utf8");
+        if (content.trim())
+          appendFileSync(owner, content.endsWith("\n") ? content : `${content}\n`);
+        unlinkSync(full);
+      } catch {
+        /* skip; next sweep retries */
+      }
+    }
+  } catch {
+    /* directory read is best-effort */
+  }
+}
+
+function trimArchive(path: string): void {
+  try {
+    if (statSync(path).size <= MAX_DELIVERED_BYTES) return;
+    const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+    const keep = lines.slice(Math.floor(lines.length / 2));
+    writeFileSync(path, `${keep.join("\n")}\n`, "utf8");
+  } catch {
+    /* trimming is housekeeping, never load-bearing */
+  }
+}
+
+/** Render a drained batch as the context block a recipient reads. */
+export function formatMailboxDelivery(
+  coordRoot: string,
+  messages: readonly MailboxMessageV1[],
+): string {
+  if (messages.length === 0) return "";
+  const bin = resolveBinName(coordRoot);
+  const header =
+    messages.length === 1
+      ? `Message from a peer agent (delivered now, recorded in your journal):`
+      : `${messages.length} messages from peer agents (delivered now, recorded in your journal):`;
+  const body = messages
+    .map((m) => {
+      const when = m.created_at.replace("T", " ").replace(/\.\d+Z$/, "Z");
+      return `  from agent-${m.from_name} (${when}):\n${indent(m.body)}`;
+    })
+    .join("\n\n");
+  return `${header}\n\n${body}\n\nReply with \`${bin} agents ping ${messages[0]!.from_name} "<your reply>"\`; it reaches them whether or not their session is still running.`;
+}
+
+function indent(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+}

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;
+  }
+}