faberun 0.12.0 → 0.13.0

package/src/harnesses/dsh/runner.mjs

@@ -13,7 +13,9 @@
  *
  * Transcript, the only thing this process writes to stdout:
  *   {"type":"dsh.started","sessionId":string}
- *   {"type":"dsh.message","text":string}          one per non-empty assistant message
+ *   {"type":"dsh.tool","name":string,"target":string|null}   one per tool call
+ *   {"type":"dsh.message","text":string,"usage"?:Usage}      one per non-empty assistant message,
+ *                                                  with that message's own usage when the harness sent it
  *   {"type":"dsh.completed","sessionId":string,"result":string,"usage":Usage}
  *   {"type":"dsh.failed","sessionId":string,"kind":string,"error":{...},"usage":Usage}
  * where Usage is `{inputTokens, outputTokens, cacheReadInputTokens}` with
@@ -99,6 +101,27 @@ function addUsage(totals, usage) {
   return observed;
 }
 
+/**
+ * The file, path, command or pattern a tool call names, bounded: the
+ * controller's live meter counts the call and the run page shows the target.
+ *
+ * @param {unknown} rawArguments the harness's JSON-encoded tool arguments
+ * @returns {string|null}
+ */
+function toolTarget(rawArguments) {
+  if (typeof rawArguments !== "string" || !rawArguments) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(rawArguments);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const record = /** @type {Record<string, unknown>} */ (parsed);
+  const value = record.file_path ?? record.path ?? record.command ?? record.pattern ?? null;
+  return typeof value === "string" ? value.slice(0, 200) : null;
+}
+
 /** @param {unknown} reason @returns {{kind: string, error: {code: string, message: string, retryAfterMs?: number} | null}} */
 function describeReason(reason) {
   const record = reason && typeof reason === "object" ? /** @type {Record<string, unknown>} */ (reason) : {};
@@ -149,9 +172,21 @@ function fail(kind, error, exitCode = 1) {
 
 /** @param {Record<string, any>} event */
 function fold(event) {
+  if (event.type === "tool/call") {
+    // Forwarded, not folded away: a tool call is the liveness evidence the
+    // controller's stall detector counts, and the step the run page renders.
+    const data = event.data && typeof event.data === "object" ? /** @type {Record<string, unknown>} */ (event.data) : {};
+    emit({ type: "dsh.tool", name: typeof data.name === "string" ? data.name : "tool", target: toolTarget(data.arguments) });
+    return;
+  }
   if (event.type === "assistant/message") {
     const data = event.data && typeof event.data === "object" ? /** @type {Record<string, unknown>} */ (event.data) : {};
-    sawUsage = addUsage(usage, data.usage) || sawUsage;
+    const messageUsage = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+    const observed = addUsage(messageUsage, data.usage);
+    if (observed) {
+      addUsage(usage, data.usage);
+      sawUsage = true;
+    }
     const message = data.message && typeof data.message === "object" ? /** @type {Record<string, unknown>} */ (data.message) : {};
     const blocks = Array.isArray(message.content) ? message.content : [];
     const text = blocks.map((block) => (block && typeof block === "object" && typeof block.text === "string" ? block.text : "")).join("");
@@ -159,7 +194,7 @@ function fold(event) {
       texts.push(text);
       // Every message, not only the last: a judge that returns two verdicts
       // must be visible as two, and the adapter counts them here.
-      emit({ type: "dsh.message", text });
+      emit({ type: "dsh.message", text, ...(observed ? { usage: messageUsage } : {}) });
     }
     return;
   }

package/src/harnesses/exec-jsonl/index.mjs

@@ -22,8 +22,6 @@
 
 import {
   canonicalUsage,
-  eventItem,
-  extractJson,
   failed,
   parseJsonLines,
   parseVersion,
@@ -259,503 +257,6 @@ function validateError(value, label) {
   if (typeof record.message !== "string" || !record.message.trim()) throw new TypeError(`${label}.message must be a non-empty string`);
 }
 
-/**
- * Best-effort input-token meter over a still-growing transcript. The
- * controller never owns the provider stream (the gate writes stdout straight
- * to the log fd), so budget enforcement polls this instead. Lenient by
- * design: unparsable or partial lines count as zero, and providers that only
- * report usage at completion (agy, exec-jsonl, replay) meter as 0 mid-run.
- *
- * @param {string} harness
- * @param {string} stdout bounded transcript tail
- * @returns {{inputTokens: number|null, cacheReadInputTokens: number|null}}
- */
-export function liveUsage(harness, stdout) {
-  if (harness === "exec-jsonl" || harness === "replay") {
-    // Completion-only harnesses: usage arrives in the terminal envelope, which
-    // the close path normalizes, never in a mid-run live observation.
-    return { inputTokens: null, cacheReadInputTokens: null };
-  }
-  const events = parsedEvents(stdout);
-  if (harness === "codex") {
-    // turn.completed usage is cumulative for the session; the last one wins.
-    // Codex counts input_tokens with their cached portion included, so the
-    // uncached total is what the ledger calls `inputTokens`.
-    const records = events
-      .filter((event) => event?.type === "turn.completed" && event.usage && typeof event.usage === "object")
-      .map((event) => {
-        const rawInput = finite(event.usage.input_tokens ?? event.usage.inputTokens);
-        if (rawInput === null) return null;
-        const cacheReadInputTokens = finite(
-          event.usage.cached_input_tokens ?? event.usage.cacheReadInputTokens ?? event.usage.cache_read_tokens,
-        ) ?? 0;
-        return { inputTokens: Math.max(0, rawInput - cacheReadInputTokens), cacheReadInputTokens };
-      })
-      .filter((record) => record !== null);
-    if (!records.length) return { inputTokens: null, cacheReadInputTokens: null };
-    return records.reduce((best, record) => (
-      record.inputTokens + record.cacheReadInputTokens > best.inputTokens + best.cacheReadInputTokens ? record : best
-    ));
-  }
-  if (harness === "claude") {
-    // The terminal result event carries the session total; before it lands,
-    // sum per-request assistant usage (each request re-reads full context).
-    // Claude's input_tokens already exclude cache reads.
-    const resultEvent = events.findLast((event) => event?.type === "result");
-    const resultUsage = resultEvent?.usage && typeof resultEvent.usage === "object"
-      ? finite(resultEvent.usage.input_tokens ?? resultEvent.usage.inputTokens)
-      : null;
-    if (resultUsage !== null) {
-      return {
-        inputTokens: resultUsage,
-        cacheReadInputTokens: finite(resultEvent.usage.cache_read_input_tokens ?? resultEvent.usage.cacheReadInputTokens) ?? null,
-      };
-    }
-    return {
-      inputTokens: events.reduce((sum, event) => {
-        if (event?.type !== "assistant") return sum;
-        const usage = event.message?.usage;
-        const value = usage && typeof usage === "object" ? finite(usage.input_tokens ?? usage.inputTokens) : null;
-        return sum + (value ?? 0);
-      }, 0) || null,
-      cacheReadInputTokens: null,
-    };
-  }
-  return { inputTokens: null, cacheReadInputTokens: null };
-}
-
-/**
- * Budgeted live meter: one number, with cache reads weighted by the campaign
- * policy so it is comparable with the persisted ledger. A provider that only
- * reports usage at completion (agy, exec-jsonl, replay) meters as 0 mid-run.
- *
- * @param {string} harness
- * @param {string} stdout bounded transcript tail
- * @param {number} [cacheReadWeight] cached-to-uncached rate ratio, default 1
- * @returns {number}
- */
-export function liveInputTokens(harness, stdout, cacheReadWeight = 1) {
-  const usage = liveUsage(harness, stdout);
-  if (usage.inputTokens === null) return 0;
-  const weighted = usage.inputTokens + (usage.cacheReadInputTokens ?? 0) * cacheReadWeight;
-  return Math.round(weighted * 1000) / 1000;
-}
-
-/**
- * Parse each JSONL line independently. A bounded transcript tail can start or
- * end mid-line, so unparsable lines are skipped rather than failing the live
- * observation.
- *
- * @param {string} stdout
- */
-function parsedEvents(stdout) {
-  return String(stdout).split(/\r?\n/u).flatMap((line) => {
-    try {
-      return [JSON.parse(line)];
-    } catch {
-      return [];
-    }
-  });
-}
-
-/** Codex item types whose completion proves one tool invocation. */
-const CODEX_TOOL_ITEM_TYPES = new Set(["tool_call", "command_execution", "mcp_tool_call", "web_search", "file_change"]);
-
-/**
- * Session evidence from a bounded live transcript: completed turns, cache-read
- * input, tool invocations, and whether the harness's terminal record has been
- * folded. Each harness exposes only what its own events prove, and anything
- * unparsable or unsupported meters as zero — a live observation never throws.
- *
- * @param {string} harness
- * @param {string} stdout bounded transcript tail
- * @returns {{turns: number, cacheReadInputTokens: number, toolCalls: number, completed: boolean}}
- */
-export function liveSessionMetrics(harness, stdout) {
-  const parser = new SessionMetricsParser(harness);
-  parser.push(String(stdout));
-  parser.flush();
-  return parser.metrics();
-}
-
-/** Retention bound for one streamed record: records at or below it parse whole. */
-const SESSION_RECORD_MAX_BYTES = 64 * 1024;
-
-/** Fragment evidence kept for a record that outgrew the retention bound. */
-const SESSION_FRAGMENT_BYTES = SESSION_RECORD_MAX_BYTES / 2;
-
-/** Claude-family content-block needle proving one tool invocation. */
-const TOOL_USE_NEEDLE = Buffer.from('"type":"tool_use"', "utf8");
-
-/** Cache-read evidence spellings across harness streams. */
-const CACHE_READ_PATTERN = /"(?:cache_read_input_tokens|cached_input_tokens|cacheReadInputTokens)":(\d+)/gu;
-
-/**
- * Bounded incremental session-metrics parser: fold fixed-size chunks into
- * running rotation totals without ever holding a buffer that scales with the
- * unread transcript. Records within `SESSION_RECORD_MAX_BYTES` parse whole;
- * a larger record keeps head and tail fragments plus streamed needle counts,
- * so its turn and usage evidence still lands in the totals instead of being
- * silently skipped.
- */
-export class SessionMetricsParser {
-  /**
-   * @param {string} harness
-   * @param {{turns?: number, cacheReadInputTokens?: number, toolCalls?: number, completed?: boolean}} [previous]
-   */
-  constructor(harness, previous = {}) {
-    this.harness = harness;
-    this.totals = {
-      turns: previous.turns ?? 0,
-      cacheReadInputTokens: previous.cacheReadInputTokens ?? 0,
-      toolCalls: previous.toolCalls ?? 0,
-      completed: previous.completed === true,
-    };
-    /** @type {string|null} */
-    this.continuationId = null;
-    /** @type {string|null} Most recent folded item-completed type, for the codex completion rule. */
-    this.lastItemType = null;
-    /** @type {string|null} Text of the most recent folded agent message, for the codex completion rule. */
-    this.lastAgentText = null;
-    /** @type {Buffer} */
-    this.pending = Buffer.alloc(0);
-    /** @type {{head: Buffer, tail: Buffer, streamedToolUse: number, carry: Buffer}|null} */
-    this.oversized = null;
-  }
-
-  /**
-   * Fold every newline-terminated record in one chunk. A trailing partial
-   * record stays buffered (bounded) for the next chunk.
-   *
-   * @param {string|Buffer} chunk
-   */
-  push(chunk) {
-    let data = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
-    while (data.length > 0) {
-      const newline = data.indexOf(10);
-      if (newline < 0) {
-        this.absorb(data);
-        return;
-      }
-      this.absorb(data.subarray(0, newline));
-      this.completeRecord();
-      data = data.subarray(newline + 1);
-    }
-  }
-
-  /** Fold the buffered partial record as if a newline had ended it. */
-  flush() {
-    if (this.pending.length > 0 || this.oversized) this.completeRecord();
-  }
-
-  /** @returns {{turns: number, cacheReadInputTokens: number, toolCalls: number, completed: boolean}} */
-  metrics() {
-    return {
-      turns: this.totals.turns,
-      cacheReadInputTokens: this.totals.cacheReadInputTokens,
-      toolCalls: this.totals.toolCalls,
-      completed: this.totals.completed === true,
-    };
-  }
-
-  /**
-   * Retain one piece of a record still under assembly. Once the record
-   * outgrows the retention bound, only its head and a rolling tail are kept;
-   * the bytes leaving the tail are scanned for tool_use evidence instead of
-   * being buffered.
-   *
-   * @param {Buffer} piece
-   */
-  absorb(piece) {
-    if (this.oversized) {
-      const window = Buffer.concat([this.oversized.tail, piece]);
-      const keep = window.subarray(Math.max(0, window.length - SESSION_FRAGMENT_BYTES));
-      const dropped = window.subarray(0, window.length - keep.length);
-      if (this.harness === "claude") {
-        const counted = countWithCarry(dropped, this.oversized.carry, TOOL_USE_NEEDLE);
-        this.oversized.streamedToolUse += counted.hits;
-        this.oversized.carry = counted.carry;
-      }
-      this.oversized.tail = keep;
-      return;
-    }
-    if (this.pending.length + piece.length <= SESSION_RECORD_MAX_BYTES) {
-      // Copy: `piece` may be a view of a scratch buffer the caller reuses for
-      // the next read, which would corrupt a record buffered mid-chunk.
-      this.pending = this.pending.length > 0 ? Buffer.concat([this.pending, piece]) : Buffer.from(piece);
-      return;
-    }
-    const whole = Buffer.concat([this.pending, piece]);
-    this.pending = Buffer.alloc(0);
-    const head = whole.subarray(0, Math.min(SESSION_FRAGMENT_BYTES, whole.length));
-    const tail = whole.subarray(Math.max(0, whole.length - SESSION_FRAGMENT_BYTES));
-    /** @type {{head: Buffer, tail: Buffer, streamedToolUse: number, carry: Buffer}} */
-    const oversized = { head, tail, streamedToolUse: 0, carry: Buffer.alloc(0) };
-    if (this.harness === "claude") {
-      // Count from the record start up to where the rolling tail takes over,
-      // so a needle straddling any region boundary is counted exactly once.
-      const counted = countWithCarry(whole.subarray(0, Math.max(0, whole.length - tail.length)), oversized.carry, TOOL_USE_NEEDLE);
-      oversized.streamedToolUse = counted.hits;
-      oversized.carry = counted.carry;
-    }
-    this.oversized = oversized;
-  }
-
-  /** Fold the assembled record into the running totals. */
-  completeRecord() {
-    const oversized = this.oversized;
-    if (oversized) {
-      this.oversized = null;
-      /** @type {{head: string, tail: string, toolUse: number}} */
-      let fragments;
-      if (this.harness === "claude") {
-        const counted = countWithCarry(oversized.tail, oversized.carry, TOOL_USE_NEEDLE);
-        fragments = {
-          head: decodeFragment(oversized.head),
-          tail: decodeFragment(oversized.tail),
-          toolUse: oversized.streamedToolUse + counted.hits,
-        };
-      } else {
-        fragments = { head: decodeFragment(oversized.head), tail: decodeFragment(oversized.tail), toolUse: 0 };
-      }
-      foldFragmentRecord(this.harness, this.totals, fragments);
-      this.continuationId ??= fragmentContinuationId(this.harness, fragments);
-      return;
-    }
-    const line = this.pending.toString("utf8");
-    this.pending = Buffer.alloc(0);
-    let event;
-    try {
-      event = JSON.parse(line);
-    } catch {
-      return;
-    }
-    if (!event || typeof event !== "object" || Array.isArray(event)) return;
-    const record = /** @type {Record<string, unknown>} */ (event);
-    foldRecord(this.harness, this.totals, record);
-    this.continuationId ??= recordContinuationId(this.harness, record);
-    this.foldCompletionEvidence(record);
-  }
-
-  /**
-   * Fold the completion evidence one parsed record proves into the sticky
-   * totals. A harness is completed when its terminal record was folded; for
-   * codex that means a turn.completed that ends the turn with the
-   * result-carrying final agent message, so a live observation never treats a
-   * still-working or already-answered session ambiguously.
-   *
-   * @param {Record<string, unknown>} record
-   */
-  foldCompletionEvidence(record) {
-    const totals = this.totals;
-    if (this.harness === "codex") {
-      if (record.type === "turn.completed" && this.lastItemType === "agent_message"
-        && extractJson(this.lastAgentText) !== null) {
-        totals.completed = true;
-      }
-    } else if (this.harness === "claude" && record.type === "result") {
-      totals.completed = true;
-    } else if (this.harness === "exec-jsonl" && record.type === "run.completed") {
-      totals.completed = true;
-    } else if (this.harness === "replay" && typeof record.status === "string") {
-      // The replay envelope is the terminal record: the bin emits exactly one
-      // envelope line per invocation, so folding one proves completion.
-      totals.completed = true;
-    }
-    const item = eventItem(record);
-    if (record.type === "item.completed" && item) {
-      this.lastItemType = String(item.type ?? "");
-      this.lastAgentText = this.lastItemType === "agent_message" && typeof item.text === "string"
-        ? item.text
-        : null;
-    } else {
-      this.lastItemType = null;
-      this.lastAgentText = null;
-    }
-  }
-}
-
-/**
- * Fold one parsed record into the running totals. Turn and tool counts are
- * additive; cache-read is a running max for Codex (each turn.completed
- * counter is already cumulative) and additive for claude-style streams until
- * a terminal result event carries the authoritative session total.
- *
- * @param {string} harness
- * @param {{turns: number, cacheReadInputTokens: number, toolCalls: number, completed: boolean}} totals
- * @param {Record<string, unknown>} record
- */
-function foldRecord(harness, totals, record) {
-  if (harness === "codex") {
-    if (record.type === "turn.completed") {
-      totals.turns += 1;
-      totals.cacheReadInputTokens = Math.max(totals.cacheReadInputTokens, canonicalUsage(record.usage).cacheReadInputTokens ?? 0);
-    } else if (record.type === "item.completed" && CODEX_TOOL_ITEM_TYPES.has(String(eventItem(record)?.type))) {
-      totals.toolCalls += 1;
-    }
-    return;
-  }
-  if (harness === "claude") {
-    if (record.type === "assistant") {
-      const message = /** @type {Record<string, unknown>} */ (record.message ?? {});
-      totals.turns += 1;
-      totals.cacheReadInputTokens += canonicalUsage(message.usage).cacheReadInputTokens ?? 0;
-      totals.toolCalls += Array.isArray(message.content)
-        ? message.content.filter((/** @type {{type?: unknown}} */ block) => block?.type === "tool_use").length
-        : 0;
-    } else if (record.type === "result") {
-      const sessionTotal = canonicalUsage(record.usage).cacheReadInputTokens;
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
-    }
-    return;
-  }
-  if (harness === "exec-jsonl" && record.type === "run.completed") {
-    // The protocol carries no tool events; only a completed run proves a turn.
-    totals.turns += 1;
-    totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
-  }
-  if (harness === "replay" && typeof record.status === "string") {
-    // A replayed envelope is the whole invocation: one completed turn, no
-    // tool events, usage only in the terminal record.
-    totals.turns += 1;
-    totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
-  }
-}
-
-/**
- * Fold the head-plus-tail fragments of one record that outgrew the retention
- * bound: the same evidence foldRecord extracts, read as fragments so an
- * oversized record is never silently skipped.
- *
- * @param {string} harness
- * @param {{turns: number, cacheReadInputTokens: number, toolCalls: number, completed: boolean}} totals
- * @param {{head: string, tail: string, toolUse: number}} fragments
- */
-function foldFragmentRecord(harness, totals, fragments) {
-  const text = `${fragments.head}\n${fragments.tail}`;
-  if (harness === "claude") {
-    if (text.includes('"type":"assistant"')) {
-      totals.turns += 1;
-      totals.toolCalls += fragments.toolUse;
-      const cacheRead = lastCacheRead(text);
-      if (cacheRead !== null) totals.cacheReadInputTokens += cacheRead;
-    } else if (text.includes('"type":"result"')) {
-      const sessionTotal = lastCacheRead(text);
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
-      totals.completed = true;
-    }
-    return;
-  }
-  if (harness === "codex") {
-    if (text.includes('"type":"turn.completed"')) {
-      totals.turns += 1;
-      const cacheRead = lastCacheRead(text);
-      totals.cacheReadInputTokens = Math.max(totals.cacheReadInputTokens, cacheRead ?? 0);
-      // Fragment approximation of the parsed-record completion rule: the
-      // turn ends with the final agent message when that message appears
-      // before the completed marker in the retained head and tail.
-      const agentAt = text.indexOf('"type":"agent_message"');
-      if (agentAt >= 0 && agentAt < text.indexOf('"type":"turn.completed"')) totals.completed = true;
-    } else if (text.includes('"type":"item.completed"') && [...CODEX_TOOL_ITEM_TYPES].some((type) => text.includes(`"type":"${type}"`))) {
-      totals.toolCalls += 1;
-    }
-    return;
-  }
-  if (harness === "exec-jsonl" && text.includes('"type":"run.completed"')) {
-    totals.turns += 1;
-    const cacheRead = lastCacheRead(text);
-    if (cacheRead !== null) totals.cacheReadInputTokens += cacheRead;
-    totals.completed = true;
-  }
-}
-
-/**
- * The provider session identity one record proves.
- *
- * @param {string} harness
- * @param {Record<string, unknown>} record
- * @returns {string|null}
- */
-function recordContinuationId(harness, record) {
-  if (harness === "codex") {
-    return record.type === "thread.started" && typeof record.thread_id === "string" ? record.thread_id : null;
-  }
-  if (harness === "claude") {
-    return record.type === "result" && typeof record.session_id === "string" ? record.session_id : null;
-  }
-  if (harness === "exec-jsonl" && (record.type === "run.started" || record.type === "run.completed")) {
-    return typeof record.continuationId === "string" ? record.continuationId : null;
-  }
-  return null;
-}
-
-/**
- * The provider session identity one record's fragments prove.
- *
- * @param {string} harness
- * @param {{head: string, tail: string}} fragments
- * @returns {string|null}
- */
-function fragmentContinuationId(harness, fragments) {
-  const text = `${fragments.head}\n${fragments.tail}`;
-  const pattern = harness === "codex"
-    ? /"thread_id":"([^"]+)"/u
-    : harness === "claude"
-      ? /"session_id":"([^"]+)"/u
-      : /"continuationId":"([^"]+)"/u;
-  const match = pattern.exec(text);
-  return match ? match[1] : null;
-}
-
-/**
- * Count needle occurrences in one region, keeping the trailing bytes that
- * could complete a needle in the next region so a straddling needle is
- * counted exactly once.
- *
- * @param {Buffer} region
- * @param {Buffer} carry
- * @param {Buffer} needle
- * @returns {{hits: number, carry: Buffer}}
- */
-function countWithCarry(region, carry, needle) {
-  const stream = carry.length > 0 ? Buffer.concat([carry, region]) : region;
-  return { hits: countNeedle(stream, needle), carry: stream.subarray(Math.max(0, stream.length - (needle.length - 1))) };
-}
-
-/**
- * @param {Buffer} haystack
- * @param {Buffer} needle
- * @returns {number}
- */
-function countNeedle(haystack, needle) {
-  let hits = 0;
-  for (let at = haystack.indexOf(needle); at >= 0; at = haystack.indexOf(needle, at + needle.length)) hits += 1;
-  return hits;
-}
-
-/**
- * Decode a retained fragment without splitting a UTF-8 sequence.
- *
- * @param {Buffer} fragment
- * @returns {string}
- */
-function decodeFragment(fragment) {
-  let start = 0;
-  while (start < fragment.length && (fragment[start] & 0xc0) === 0x80) start += 1;
-  return fragment.toString("utf8", start);
-}
-
-/**
- * The last cache-read number in a fragment text, or null.
- *
- * @param {string} text
- * @returns {number|null}
- */
-function lastCacheRead(text) {
-  const matches = [...text.matchAll(CACHE_READ_PATTERN)];
-  return matches.length > 0 ? Number(matches.at(-1)?.[1]) : null;
-}
-
 /**
  * Bound one tool result to at most `maxBytes` UTF-8 bytes, keeping the head
  * and the tail around an omission marker. This is the reference head+tail