memhtml 0.5.1 → 0.7.0

package/src/contract.ts

@@ -67,6 +67,38 @@ export type CommitmentActor = (typeof COMMITMENT_ACTORS)[number]
 /** Ceiling on a commitment's statement. One sentence, the same bound a claim carries. */
 export const MAX_STATEMENT_CHARS = 300
 
+/**
+ * Ceilings on the LIST fields, so one answer is finite by contract rather than by good behavior.
+ *
+ * Every scalar field above is bounded and the lists were not, so a single turn could return an answer
+ * whose size only the model chose: each candidate is up to ~21 KB of prose plus its evidence, and each
+ * evidence quote costs a containment walk over the cited transcript in `fabricatedQuoteReason`. The
+ * bounds are generous against the instructions — `agent/instructions.md` calls six candidates plenty
+ * and asks for a handful of commitments — so a decode that trips one is an off-contract answer, not a
+ * thorough one.
+ */
+export const MAX_CANDIDATES_PER_RESULT = 200
+export const MAX_COMMITMENTS_PER_RESULT = 200
+/** Per candidate. Two is the floor (the TRACE-2 bar); this is the matching ceiling. */
+export const MAX_EVIDENCE_PER_CANDIDATE = 32
+/** Per candidate. Concrete names, not an inventory of every file a session touched. */
+export const MAX_ENTITIES_PER_CANDIDATE = 64
+
+/**
+ * Ceiling on transcripts per run.
+ *
+ * Not a bound on resident bytes — the mount does not copy — but on how many files one agent session
+ * is asked to hold in attention, and the guard against a caller handing over five thousand sessions,
+ * which is well within what one sleep cycle could find unconsolidated. The sleep phase's own
+ * `TRACE_SESSIONS_PER_RUN` is lower and binds first; this is the client's independent backstop
+ * against a different caller.
+ *
+ * Declared with the other ceilings rather than beside the mount notes below, because
+ * {@link ConsolidationPayload} bounds its read receipt by it and a class body evaluates where it is
+ * written — a `const` declared further down would be in its temporal dead zone.
+ */
+export const MAX_TRANSCRIPTS_PER_RUN = 32
+
 /**
  * One transcript line the candidate rests on, tied to the session it came from.
  *
@@ -89,6 +121,41 @@ export class CandidateEvidence extends Schema.Class<CandidateEvidence>("Candidat
   quote: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_QUOTE_CHARS))
 }) {}
 
+/**
+ * One entity a candidate names, as a TYPE and a NAME rather than as one bare string.
+ *
+ * ## Why the type half is structural
+ *
+ * The corpus keys an entity on `(entity_type, entity_name)`, and the `entity` retrieval scope compares
+ * a whole `type:name` reference (`packages/index/src/scope.ts`). A reference carrying no separator is
+ * filed under the type `unknown` (`packages/index/src/project.ts`), which keeps the name as a handle
+ * and costs reachability: a memory stored under `unknown:checkout-api` answers
+ * `service:checkout-api` — the reference a caller would ask for — with an empty set, which is the same
+ * answer an absent memory gives. So a producer emitting bare names writes memories nothing can reach
+ * by entity.
+ *
+ * ## A required OBJECT FIELD, never a `pattern` on a string
+ *
+ * The other entity producer in this repo already ships this shape: `apps/cli/src/extraction.ts` sends
+ * `{type, name}` with `required: ["type", "name"]` and `additionalProperties: false` under the
+ * Responses API's `strict: true`, and joins the pair as `type:name`. A JSON-Schema `pattern` is not
+ * reliably enforced by a provider's strict-mode structured output, while a required object field is,
+ * so the type half arrives because the shape has nowhere else to put it.
+ *
+ * ## The type vocabulary is OPEN
+ *
+ * `type` is any non-empty term, not a literal union. memhtml does not dictate a consumer's entity
+ * taxonomy: the types `agent/instructions.md` offers are a prompt-level suggestion, `unknown` remains
+ * a valid store type, and a consumer modelling its own domain adds its own terms without a change
+ * here. What this schema requires is that the type is STATED, never which one it is.
+ */
+export class CandidateEntity extends Schema.Class<CandidateEntity>("CandidateEntity")({
+  /** What kind of thing it is — `service`, `person`, `file`, or any other term. See the class note. */
+  type: Schema.String.check(Schema.isMinLength(1)),
+  /** Its concrete name, as the transcript spells it. */
+  name: Schema.String.check(Schema.isMinLength(1))
+}) {}
+
 /**
  * One distilled candidate. Not yet a memory: the next task decides what reaches the corpus.
  *
@@ -105,8 +172,11 @@ export class CandidateMemory extends Schema.Class<CandidateMemory>("CandidateMem
   /** The supporting detail: what recurs, where, and what it implies. */
   gist: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_GIST_CHARS)),
   /** Tools, files, commands, packages, people the claim is about. May be empty. */
-  entities: Schema.Array(Schema.String.check(Schema.isMinLength(1))),
-  evidence: Schema.Array(CandidateEvidence).check(Schema.isMinLength(2))
+  entities: Schema.Array(CandidateEntity).check(Schema.isMaxLength(MAX_ENTITIES_PER_CANDIDATE)),
+  evidence: Schema.Array(CandidateEvidence).check(
+    Schema.isMinLength(2),
+    Schema.isMaxLength(MAX_EVIDENCE_PER_CANDIDATE)
+  )
 }) {}
 
 /**
@@ -165,7 +235,7 @@ export class CandidateCommitment extends Schema.Class<CandidateCommitment>("Cand
 }) {}
 
 /**
- * What one run produced, what it cost in model calls, and WHICH SESSIONS IT ACTUALLY REACHED.
+ * What one run produced, what it cost in model calls, and WHICH SESSIONS IT ACTUALLY READ.
  *
  * `analyzedSessionIds` is the value a caller watermarks from rather than a reporting field. It exists
  * because the alternative, watermarking the batch that was ASKED about, records a transcript that
@@ -173,16 +243,19 @@ export class CandidateCommitment extends Schema.Class<CandidateCommitment>("Cand
  * rotated away, or sits behind a symlink the sandbox will not follow, is not ten sessions read.
  *
  * The field is REQUIRED rather than optional, and that is what makes the rule structural instead of
- * advisory: nothing can produce a `ConsolidationResult` without stating what it reached, so a caller
- * has the honest set at hand and never has to fall back on the batch. `markSessionsConsolidated`'s
- * only correct input is this set, intersected with the batch. See
+ * advisory: nothing can produce a `ConsolidationResult` without stating what it read, so a caller has
+ * the honest set at hand and never has to fall back on the batch. `markSessionsConsolidated`'s only
+ * correct input is this set, intersected with the batch. See
  * `packages/sleep/src/phases/trace-consolidation.ts`.
  *
- * It is the set of transcripts whose files RESOLVE AT THEIR GUEST PATH inside the sandbox's
- * read-only mount, not the set the model chose to open. Those are different claims and only the
- * first is checkable: nothing outside the model can prove a file was read, while a file that does
- * not resolve was categorically not read. The pre-existing semantics of a watermark, "the agent saw
- * this session and correctly found nothing above the bar", needs exactly the first.
+ * It is the intersection of two sets, gated on the answer carrying at least one finding: the
+ * transcripts whose files RESOLVE AT THEIR GUEST PATH inside the sandbox's read-only mount, and the
+ * sessions the agent's own read receipt names. Resolution is checkable where "the model opened it" is
+ * not, and it is measured before the model runs — so it bounds the claim rather than proving it, while
+ * the receipt narrows it to what the agent says it opened. Never the batch that was asked about, and
+ * never merely the ids the answer CITES: a barren-but-read session must advance, or every quiet
+ * transcript is re-read at full model cost every night. {@link watermarkableSessionIds} holds the whole
+ * rule, and the client logs the empty arm loudly.
  */
 export class ConsolidationResult extends Schema.Class<ConsolidationResult>("ConsolidationResult")({
   candidates: Schema.Array(CandidateMemory),
@@ -282,6 +355,151 @@ const ungroundedReason = (
   `${label} ${String(offset)} cites session ${sessionId}, which this run did ` +
   `not make readable (${String(readableCount)} transcript(s) resolved in the sandbox)`
 
+/**
+ * Which of the reachable sessions a caller may WATERMARK from this answer.
+ *
+ * TWO conditions, and both are necessary because each covers what the other cannot.
+ *
+ * ## One: the answer must carry a finding, which is the only VERIFIED receipt
+ *
+ * Reachability is decided by this process before the model runs, so it proves the files could be read
+ * and never that anything read them. Quotes are the only receipt an answer carries that something
+ * outside the model checks: `fabricatedQuoteReason` (`client.ts`) re-reads each cited transcript and
+ * refuses the turn unless the quoted text is really in it. So an answer with NO candidates and NO
+ * commitments proves nothing and advances nothing, whatever its {@link ConsolidationPayload.readSessionIds}
+ * claims — a misrouted listener answering with empty lists and a full read receipt would otherwise
+ * watermark a batch nothing opened. The batch stays unwatermarked and the next night asks again.
+ *
+ * ## Two: the advance covers what the agent SAYS it read, intersected with what was reachable
+ *
+ * The receipt behind the quote gate is per-RUN: it proves SOME file in the batch was opened, and says
+ * nothing about the others. Advancing every reachable session on that receipt loses transcripts
+ * permanently — a turn that opens 1 of 32 and returns one candidate with two real quotes advances all
+ * 32, and `trace_consolidations` is an anti-join, so the other 31 are never selected again. That is the
+ * shape a step-budget-truncated turn takes.
+ *
+ * `readSessionIds` closes it: the agent names the sessions it opened or grepped, and only those
+ * advance. A barren-but-READ session still advances, which is what keeps the cost bounded — "the agent
+ * read it and found nothing above the bar" is the watermark's meaning, and gating each session on its
+ * own CITATION would re-read every quiet transcript at full model cost every night forever.
+ *
+ * The intersection is what bounds the claim. A session id the run did not make reachable cannot be
+ * watermarked however the answer names it, so the receipt can only ever NARROW the reachable set. That
+ * is the same authority `analyzedFrom` gives the client's answer against the phase's batch.
+ *
+ * ## What is still unverified, stated as the residual it is
+ *
+ * `readSessionIds` is a model CLAIM. An agent that opens one transcript and names thirty-two advances
+ * thirty-two, and nothing here can tell that from a thorough run — the quote gate proves reading
+ * happened, not how much. {@link underCitedWatermarkWarning} is what makes that shape
+ * visible: it compares the sessions the answer QUOTES against the sessions it claims to have read, so a
+ * wide claim behind a narrow set of quotes is logged rather than silent.
+ *
+ * Ids are trimmed before comparison, so a receipt whose entries carry stray whitespace still matches
+ * the reachable ids the manifest handed over.
+ *
+ * In the contract rather than inline in `client.ts`, matching {@link ungroundedEvidenceReason}: the
+ * rule is pure over the answer and the reachable ids, and the test tier exercises it with no server.
+ */
+export const watermarkableSessionIds = (
+  answer: {
+    readonly candidates: ReadonlyArray<unknown>
+    readonly commitments: ReadonlyArray<unknown>
+    readonly readSessionIds: ReadonlyArray<string>
+  },
+  readableSessionIds: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  if (answer.candidates.length === 0 && answer.commitments.length === 0) return []
+  const read = new Set(answer.readSessionIds.map((id) => id.trim()))
+  return readableSessionIds.filter((id) => read.has(id))
+}
+
+/**
+ * The share of an ADVANCING set that must be CITED for the advance to pass without a warning.
+ *
+ * A quarter. The instructions call six candidates plenty for a batch of up to
+ * {@link MAX_TRANSCRIPTS_PER_RUN} transcripts, and each candidate cites at least two quotes, so an
+ * honest thorough turn claiming 32 sessions read cites somewhere around 4 to 12 of them and sits near
+ * this line; the shape this exists to surface — one candidate quoting one session while the receipt
+ * claims 32 — is at 3%. Set to fire rather than to stay quiet, because the log line is the only place
+ * the claim's breadth is measured against a verified receipt, and a warning costs a line while the
+ * shape it describes costs transcripts.
+ */
+const WATERMARK_CITED_SHARE_FLOOR = 0.25
+
+/**
+ * Advances smaller than this never warn.
+ *
+ * Below eight sessions the ratio carries no signal: a two-session advance with one citation is at the
+ * floor and is also the ordinary shape of a night with two transcripts, so warning there would train an
+ * operator to ignore the line by the time a claim of 32 advancing on one citation arrives. It is also
+ * what keeps an HONEST narrow turn quiet — a run that opens one transcript and names one advances one.
+ */
+const WATERMARK_WARN_MIN_READABLE = 8
+
+/**
+ * The warning for a watermark that advances many sessions on the citations of a small fraction of them,
+ * or `null` when the advance is unremarkable.
+ *
+ * This is OBSERVABILITY over the one thing {@link watermarkableSessionIds} cannot check, not a second
+ * gate. It changes no semantics: the advance happens either way.
+ *
+ * What it measures is the gap between two receipts of different strength. `readSessionIds` is the
+ * agent's own CLAIM about what it opened, and the advance is derived from it; the quotes are the
+ * VERIFIED half, re-read against the real transcripts by `fabricatedQuoteReason`. So an answer claiming
+ * thirty-two sessions read while quoting one is the shape a truncated or lazy turn takes, and it is
+ * indistinguishable here from a thorough run whose thirty-one quiet sessions genuinely held nothing.
+ * The log line is the only place that gap is visible.
+ *
+ * An HONEST narrow turn does not warn, and that follows from the advance being the claim: a turn that
+ * opens one transcript and names one advances one, which is below {@link WATERMARK_WARN_MIN_READABLE}.
+ * The line fires for a WIDE claim behind a NARROW set of quotes, which is exactly the case worth an
+ * operator's attention.
+ *
+ * The count is of DISTINCT cited session ids INSIDE the advancing set, because both numbers in the line
+ * have to name one space. A citation of a session that is not advancing — one outside the receipt, or
+ * one the run never made reachable — is evidence about a different set, and counting it both understates
+ * the uncited remainder and suppresses the line in the case it exists for: eight sessions advancing on
+ * the receipt alone, with two quotes naming sessions none of them, reads as a quarter cited when zero
+ * of the advance is. Distinct rather than per-quote, because a candidate citing one session twice is one
+ * session's receipt and a per-quote count would read as breadth. Pure over the answer and the readable
+ * ids, in the contract for the reason {@link ungroundedEvidenceReason} records: the test tier drives it
+ * with no server.
+ */
+export const underCitedWatermarkWarning = (
+  answer: {
+    readonly candidates: ReadonlyArray<{
+      readonly evidence: ReadonlyArray<{ readonly sessionId: string }>
+    }>
+    readonly commitments: ReadonlyArray<{ readonly evidence: { readonly sessionId: string } }>
+    readonly readSessionIds: ReadonlyArray<string>
+  },
+  readableSessionIds: ReadonlyArray<string>
+): string | null => {
+  const advance = watermarkableSessionIds(answer, readableSessionIds)
+  const advancing = advance.length
+  if (advancing < WATERMARK_WARN_MIN_READABLE) return null
+
+  const advancingIds = new Set(advance)
+  const cited = new Set<string>()
+  const cite = (sessionId: string): void => {
+    const id = sessionId.trim()
+    if (advancingIds.has(id)) cited.add(id)
+  }
+  for (const candidate of answer.candidates) {
+    for (const quote of candidate.evidence) cite(quote.sessionId)
+  }
+  for (const commitment of answer.commitments) cite(commitment.evidence.sessionId)
+  if (cited.size >= advancing * WATERMARK_CITED_SHARE_FLOOR) return null
+
+  return (
+    `consolidation is watermarking ${String(advancing)} session(s) the agent reports having read, on ` +
+    `quotes from only ${String(cited.size)} of them; the other ${String(advancing - cited.size)} ` +
+    "advance on the reported receipt alone, and a watermarked session is never selected again. " +
+    "Check the turn's step budget if it should have read more."
+  )
+}
+
 /**
  * Whether a quote appears in a text, compared after collapsing whitespace runs on BOTH sides.
  *
@@ -295,11 +513,48 @@ const ungroundedReason = (
  * strings — see {@link decodedTranscriptStrings} for why either alone fails honest quotes.
  */
 export const quoteAppearsIn = (quote: string, text: string): boolean => {
-  const flatten = (value: string): string => value.replace(/\s+/g, " ").trim()
-  const needle = flatten(quote)
+  const needle = flattenWhitespace(quote)
   /** An empty needle is `includes`-true against anything, which would gate nothing. */
   if (needle === "") return false
-  return flatten(text).includes(needle)
+  return flattenWhitespace(text).includes(needle)
+}
+
+/** The one normalization both sides get. See {@link quoteAppearsIn} for why nothing else is. */
+const flattenWhitespace = (value: string): string => value.replace(/\s+/g, " ").trim()
+
+/**
+ * Containment checks for many quotes against ONE transcript, paying its normalization once.
+ *
+ * {@link quoteAppearsIn} flattens BOTH sides per call, so checking a transcript's quotes through it
+ * directly re-flattens the whole file once per quote — against the corpus's measured p99 of 4.68 MB
+ * and a 37.2 MB maximum, that is megabytes of regex work multiplied by however many quotes the model
+ * cited from one session. This closure flattens the raw bytes at construction and the decoded strings
+ * on the first quote that needs them, so the per-quote cost is one `includes` (plus one more per
+ * decoded string when the raw arm misses).
+ *
+ * Same two arms, same semantics as the caller composing {@link quoteAppearsIn} with
+ * {@link decodedTranscriptStrings}: raw bytes first because most quotes are verbatim in the source,
+ * decoded strings each tested SEPARATELY so a quote stitched across two messages still refuses.
+ * `fabricatedQuoteReason` (`client.ts`) builds one of these per cited session; a run that cites
+ * nothing builds none.
+ */
+export interface TranscriptQuoteChecker {
+  readonly contains: (quote: string) => boolean
+}
+
+export const transcriptQuoteChecker = (transcript: string): TranscriptQuoteChecker => {
+  const flatRaw = flattenWhitespace(transcript)
+  /** Decoded lazily: a session whose every quote is verbatim in the bytes never pays for a parse. */
+  let flatDecoded: ReadonlyArray<string> | null = null
+  return {
+    contains: (quote) => {
+      const needle = flattenWhitespace(quote)
+      if (needle === "") return false
+      if (flatRaw.includes(needle)) return true
+      flatDecoded ??= decodedTranscriptStrings(transcript).map(flattenWhitespace)
+      return flatDecoded.some((text) => text.includes(needle))
+    }
+  }
 }
 
 /**
@@ -319,7 +574,7 @@ export const quoteAppearsIn = (quote: string, text: string): boolean => {
  *
  * The cost of that mismatch is not one lost commitment. `fabricatedQuoteReason` (`client.ts`) refuses
  * the WHOLE turn, so the batch produces nothing, so `markSessionsConsolidated` never runs, so the
- * next night selects the same batch and fails identically — an honest answer livelocking a nightly
+ * next run selects the same batch and fails identically — an honest answer livelocking an unattended
  * job. PR #47's review gauntlet found exactly this against real JSONL bytes.
  *
  * ## Values only, and each value SEPARATELY
@@ -383,32 +638,19 @@ export const decodedTranscriptStrings = (transcript: string): ReadonlyArray<stri
 }
 
 /**
- * ── The origin validation that used to live here is DELETED, with the parse it defended ──────────
- *
- * `loopbackOriginFrom`, `nonLoopbackOrigin`, `isLoopbackHostname`, `ANSI_ESCAPE`, and
- * `URL_CANDIDATE` existed for one caller: `startServer` spawned `eve start --port 0` and read the
- * bound port back off the child's stdout, so the address this process posted transcripts to was a
- * string a child wrote, and validating it as loopback was the only thing standing between "eve
- * printed a URL" and "the batch was posted to it".
- *
- * `client.ts` now chooses the port itself (`reserveLoopbackPort`) and passes it to
- * `eve start --port <n>`, so the origin is composed from a constant and an integer this process got
- * from the kernel. There is no untrusted string in the path any more, and nothing left to validate:
- * a "defense" over a value we constructed asserts that we typed our own constant correctly.
- *
- * Kept as belt-and-braces it would have been WORSE than deleted, because it would have kept
- * asserting a threat model that no longer holds. The deletion also costs nothing in practice:
- * the readiness poll now refuses any listener that does not answer `/eve/v1/health` as eve, which
- * covers the reachable case (something else on the port) more directly than a hostname check on a
- * self-composed URL ever did.
- *
- * One measured correction to leave behind, since the old comment asserted the opposite. It claimed
- * eve's piped stdout carries zero ANSI escape bytes. It does not: probed 2026-08-09 with stdout
- * redirected to a file and no TTY, a failing `eve start` emitted
- * `ESC[90mStopping server gracefully (5s)... Press ESC[1mCtrl+CESC[22m again…ESC[39m`. So an escape
- * on that stream is real rather than theoretical. It is simply no longer on any path that decides an
- * address. If anything ever parses that stream again it needs the strip, and it needs the ESC byte
- * built via `String.fromCharCode` because biome's `noControlCharactersInRegex` refuses a control
+ * ── This module holds NO origin validation, and nothing may parse a child's stdout for one ───────
+ *
+ * The server's origin is composed in `client.ts` from `LOOPBACK_HOST` and a port this process
+ * obtained from the kernel (`reserveLoopbackPort`), then passed to `eve start --port <n>`. No string
+ * a child process writes is ever on the path that decides where a transcript or a run token is sent,
+ * so there is no untrusted origin to validate here. The readiness poll covers the reachable hazard
+ * (something else on the port) by refusing any listener that does not answer `/eve/v1/health` with
+ * eve's own body.
+ *
+ * A constraint on anything that ever parses eve's stdout again: the stream carries ANSI escapes even
+ * when piped with no TTY (measured 2026-08-09, eve 0.33.0: a failing `eve start` emitted
+ * `ESC[90m…ESC[39m` into a redirected file). Such a parser needs an escape strip, with the ESC byte
+ * built via `String.fromCharCode`, because biome's `noControlCharactersInRegex` refuses a control
  * character in regex source however it is spelled.
  */
 
@@ -427,8 +669,28 @@ export const decodedTranscriptStrings = (transcript: string): ReadonlyArray<stri
 export class ConsolidationPayload extends Schema.Class<ConsolidationPayload>(
   "ConsolidationPayload"
 )({
-  candidates: Schema.Array(CandidateMemory),
-  commitments: Schema.Array(CandidateCommitment)
+  candidates: Schema.Array(CandidateMemory).check(Schema.isMaxLength(MAX_CANDIDATES_PER_RESULT)),
+  commitments: Schema.Array(CandidateCommitment).check(
+    Schema.isMaxLength(MAX_COMMITMENTS_PER_RESULT)
+  ),
+  /**
+   * The `sessionId` of every session the agent opened or grepped: the PER-SESSION READ RECEIPT the
+   * watermark advances over.
+   *
+   * REQUIRED, and that is what makes it a receipt rather than a hint. An optional field would let an
+   * agent that reported nothing be indistinguishable from one that read nothing, and the fallback for
+   * an absent receipt is the whole reachable set — which is exactly the advance this field exists to
+   * narrow. Nothing downstream defaults it.
+   *
+   * Bounded by {@link MAX_TRANSCRIPTS_PER_RUN}, because a run mounts at most that many transcripts, so
+   * a longer list names sessions no run was handed.
+   *
+   * {@link watermarkableSessionIds} intersects it with the reachable set, so an id outside that set is
+   * INERT. The whole turn is not refused for one, unlike a fabricated EVIDENCE id
+   * ({@link ungroundedEvidenceReason}): that one rides into a commit message as provenance a reviewer
+   * trusts, while this one changes nothing a caller can act on.
+   */
+  readSessionIds: Schema.Array(Schema.String).check(Schema.isMaxLength(MAX_TRANSCRIPTS_PER_RUN))
 }) {}
 
 /**
@@ -507,39 +769,20 @@ export const toJsonSchema = (schema: Schema.Top): JsonObject => {
 export const CONSOLIDATION_OUTPUT_JSON_SCHEMA = toJsonSchema(ConsolidationPayload)
 
 /**
- * ── `DEFAULT_TAIL_BYTES` is DELETED, and so is the reason it existed ──────────────────────────────
- *
- * It was a 256 KiB per-file cap on how much of each transcript reached the sandbox, and the cap
- * bounded a mechanism that is gone: the client SEEDED transcripts, so every seeded byte was
- * resident in the server process for the session's lifetime (just-bash is a pure-JS VFS holding file
- * content in memory), and 256 KiB x 32 files was what bounded that at 8 MiB.
- *
- * Transcripts now arrive on a read-only `OverlayFs` mount that reads THROUGH to the host on demand
- * (`src/mount.ts`), so nothing is resident because nothing is copied. A 37.2 MB transcript, the
- * measured maximum over the live corpus, now costs whatever the model actually reads of it, and eve
- * bounds each `read_file` at 2000 lines or 50 KB
- * (node_modules/eve/dist/src/execution/sandbox/truncate-output.js). The budget moved from the seeding
- * path to the reader, where the model spends it deliberately.
- *
- * Keeping the constant would have been worse than deleting it: a 256 KiB number labelled "how many
- * bytes reach the sandbox" is now FALSE, and a future reader would have taken it as a live limit.
- * The distribution it was measured against is still recorded (11,360 transcripts, 6.59 GB, p50
- * 332 KB, p90 915 KB, p99 4.68 MB, max 37.2 MB, 2026-08-08) because
- * `packages/traces/src/parse.ts:16-21` reasons about the same shape.
+ * ── There is deliberately NO per-file byte cap on what a transcript exposes to the sandbox ───────
+ *
+ * Transcripts arrive on a read-only `OverlayFs` mount that reads THROUGH to the host on demand
+ * (`src/mount.ts`), so nothing is resident in the server process and there is no seeded byte count
+ * to bound. A large transcript costs whatever the model actually reads of it, and eve bounds each
+ * `read_file` at 2000 lines or 50 KB
+ * (node_modules/eve/dist/src/execution/sandbox/truncate-output.js), so the budget sits with the
+ * reader, spent deliberately per call.
+ *
+ * The corpus distribution this holds against, measured 2026-08-08: 11,360 transcripts, 6.59 GB, p50
+ * 332 KB, p90 915 KB, p99 4.68 MB, max 37.2 MB. `packages/traces/src/parse.ts:16-21` reasons about
+ * the same shape.
  */
 
-/**
- * Ceiling on transcripts per run.
- *
- * This one SURVIVES the seeding path's removal, and its justification changes rather than
- * disappearing. It no longer bounds resident bytes, since the mount does not copy, but it bounds
- * how many files one agent session is asked to hold in attention, and it is the guard against a
- * caller handing over five thousand sessions, which is well within what one sleep cycle could find
- * unconsolidated. The sleep phase's own `TRACE_SESSIONS_PER_RUN` is lower and binds first; this is
- * the client's independent backstop against a different caller.
- */
-export const MAX_TRANSCRIPTS_PER_RUN = 32
-
 /** One transcript the caller wants read, named by the session it belongs to. */
 export interface TranscriptRef {
   readonly sessionId: string

package/src/mount.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process"
 import { mkdtempSync, statSync } from "node:fs"
+import { rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join, normalize } from "node:path"
 import { promisify } from "node:util"
@@ -12,13 +13,16 @@ import { InMemoryFs, MountableFs, OverlayFs } from "just-bash"
  * Two consumers need the SAME shape and it is built once here: this app's consolidator, which
  * mounts the transcript root so the agent reads transcripts off a filesystem, and `memhtml exec`, which
  * mounts the memory corpus so a sandboxed script can traverse it. The module lives in
- * `apps/consolidator` because that is where `just-bash` is a real dependency, pinned to 3.2.0,
- * the version eve 0.33.0 loads through its own optional-package path
- * (node_modules/eve/dist/src/execution/sandbox/bindings/just-bash-runtime.js). `memhtml exec` imports it
- * from `@memhtml/consolidator`.
+ * `apps/consolidator` because that is where `just-bash` is a real dependency (pinned in
+ * `package.json`, inside the `^3.0.0` range eve loads through its own optional-package path,
+ * node_modules/eve/dist/src/execution/sandbox/bindings/just-bash-runtime.js). `memhtml exec` imports
+ * it from `@memhtml/consolidator`.
  *
- * Every fact below was measured against just-bash 3.2.0 on 2026-08-09, re-probing the 2026-08
- * spike's findings rather than citing them.
+ * The facts below were first measured against just-bash 3.2.0 (2026-08-09). The load-bearing ones —
+ * EROFS on write, symlinks not followed, the mountPoint spellings, nesting/trailing-slash refusals,
+ * the base surviving — are re-proven against the INSTALLED just-bash on every run of
+ * `tests/mount.test.ts`, so a behavior change in an upgrade fails there rather than aging in this
+ * comment.
  */
 
 /**
@@ -231,6 +235,17 @@ export const decodeSandboxMounts = (
   return roots
 }
 
+/**
+ * The temp directory prefix a pinned snapshot lives under, named once so the `mkdtemp` and the sweep
+ * that reclaims an orphan cannot drift.
+ *
+ * Exported because the sweep is `client.ts`'s — one startup sweep covers every temp prefix this app
+ * creates, and it matches literal prefixes rather than a glob, so each prefix has to be a value it can
+ * import. {@link pinCorpusSnapshot} is reached on the `memhtml exec` path, where a SIGKILL leaves the
+ * mkdtemp parent behind with no finalizer able to reach it.
+ */
+export const CORPUS_SNAPSHOT_TMPDIR_PREFIX = "memhtml-corpus-snapshot-"
+
 /** A materialized commit, and how to remove it. */
 export interface CorpusSnapshot {
   /** The detached worktree's directory, suitable as a {@link ReadOnlyRoot} `hostPath`. */
@@ -259,7 +274,7 @@ export const pinCorpusSnapshot = async (input: {
   readonly repoRoot: string
   readonly sha: string
 }): Promise<CorpusSnapshot> => {
-  const parent = mkdtempSync(join(tmpdir(), "memhtml-corpus-snapshot-"))
+  const parent = mkdtempSync(join(tmpdir(), CORPUS_SNAPSHOT_TMPDIR_PREFIX))
   const hostPath = join(parent, "tree")
   await run("git", ["-C", input.repoRoot, "worktree", "add", "--detach", hostPath, input.sha])
 
@@ -274,6 +289,15 @@ export const pinCorpusSnapshot = async (input: {
       await run("git", ["-C", input.repoRoot, "worktree", "remove", "--force", hostPath]).catch(
         () => {}
       )
+      /**
+       * The mkdtemp PARENT is this function's to remove, and it is a second step because `git worktree
+       * remove` deletes only the tree it was handed. Releasing without it leaves one empty
+       * `${CORPUS_SNAPSHOT_TMPDIR_PREFIX}*` directory per `memhtml exec` on the CLEAN path, where
+       * nothing failed and nothing looks wrong. Unconditional on the git call's outcome: a worktree
+       * that could not be removed is a stale administrative entry `git worktree prune` reclaims, and
+       * keeping the directory around does not fix it.
+       */
+      await rm(parent, { recursive: true, force: true }).catch(() => {})
     }
   }
 }

package/src/run-auth.ts

@@ -3,19 +3,19 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto"
 /**
  * The per-run credential the agent server demands and the client presents.
  *
- * ## What this replaces, and why the composition was worse than either half
+ * ## Why loopback alone is not the boundary
  *
- * `agent/channels/eve.ts` used to authenticate every caller anonymously with `none()`, and the only
- * thing keeping the agent off the network was the bind address. Loopback is not an authorization
- * boundary on a shared host: any local UID could drive the session endpoint for a run's duration,
- * which is free Opus tokens plus a bash sandbox. That alone was rated MEDIUM (CWE-306).
+ * An anonymous channel — `none()` in `agent/channels/eve.ts` — leaves the bind address as the only
+ * thing keeping the agent off the network, and loopback is not an authorization boundary on a shared
+ * host: any local UID can drive the session endpoint for a run's duration, which is free Opus tokens
+ * plus a bash sandbox. That alone rates MEDIUM (CWE-306).
  *
  * The sandbox half is what makes it more than that. The sandbox has FULL network egress and this app
  * cannot turn it off: `network:{dangerouslyAllowFullInternetAccess:!0}` is a hardcoded literal in
  * node_modules/eve/dist/src/execution/sandbox/bindings/just-bash-runtime.js, and
  * `justBashSetNetworkPolicyUnsupported()` throws by design. Measured 2026-08-09
  * (`node scripts/probe-sandbox-egress.mjs`): `curl` reaches example.com, an IMDSv2 token PUT returns
- * 56 bytes, and the instance-role name comes back. So the unauthenticated endpoint was a handle on a
+ * 56 bytes, and the instance-role name comes back. So an unauthenticated endpoint is a handle on a
  * sandbox that reaches IMDS. `agent/sandbox/sandbox.ts` records that egress cannot be closed here;
  * this module closes the handle.
  *
@@ -32,11 +32,12 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto"
  * eve out of `src/`'s import graph so the test tier stays server-free. TypeScript is structural, so
  * the value {@link runVerifierConfig} returns is assignable to `jwtHmac`'s parameter with no cast.
  *
- * Every claim and bound below was verified against the installed eve 0.33.0 by driving
- * `verifyJwtHmac` directly (2026-08-14): a token from {@link signRunToken} verifies as
- * `principalType: "service"`, and `null`, a non-JWT string, a token signed with a different secret,
- * an expired token, one with no `sub`, one with a foreign `sub`, and one with a foreign `aud` each
- * return `{ ok: false }`. `tests/run-auth.test.ts` is that probe kept as a test.
+ * Every claim and bound below is re-proven against the INSTALLED eve on every run of
+ * `tests/run-auth.test.ts`, which drives eve's own `verifyJwtHmac` directly: a token from
+ * {@link signRunToken} verifies as `principalType: "service"`, and `null`, a non-JWT string, a token
+ * signed with a different secret, an expired token, one with no `sub`, one with a foreign `sub`, and
+ * one with a foreign `aud` each return `{ ok: false }`. An eve upgrade that changes any of it fails
+ * there rather than aging in this comment.
  */
 
 /**
@@ -193,10 +194,12 @@ const segment = (value: unknown): string =>
  * Sign one short-lived bearer token for the run.
  *
  * Hand-rolled over `node:crypto` because eve exports NO signer: `jwtHmac`, `verifyJwtHmac`, and the
- * jose bundle behind them are verify-only on the public surface (checked across every subpath export
- * of eve 0.33.0, 46 of them), so the alternative to these six lines is a new dependency for one HMAC. The claims
- * are the ones {@link runVerifierConfig} matches, which is the whole correctness condition and the
- * reason both live in this module.
+ * jose bundle behind them are verify-only on the public surface (measured on eve 0.33.0 across all
+ * 46 subpath exports; not re-checked per upgrade — if a later eve ships a signer this stays merely
+ * redundant, not wrong, and `tests/run-auth.test.ts` keeps proving the verifier accepts these
+ * tokens). The alternative to these six lines is a new dependency for one HMAC. The claims are the
+ * ones {@link runVerifierConfig} matches, which is the whole correctness condition and the reason
+ * both live in this module.
  *
  * `exp` is derived from the call, not from the spawn, so each call produces a token valid
  * {@link TOKEN_TTL_SECONDS} from now, which is what makes the per-request function form work.