memhtml 0.1.0

package/src/mount.ts

@@ -0,0 +1,279 @@
+import { execFile } from "node:child_process"
+import { mkdtempSync, statSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, normalize } from "node:path"
+import { promisify } from "node:util"
+import type { IFileSystem } from "just-bash"
+import { InMemoryFs, MountableFs, OverlayFs } from "just-bash"
+
+/**
+ * The one composition that puts host directories inside a just-bash sandbox read-only.
+ *
+ * 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`.
+ *
+ * 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.
+ */
+
+/**
+ * One host directory and where it appears in the guest.
+ *
+ * There is deliberately NO way to set the overlay's own `mountPoint` from here. See
+ * {@link mountReadOnlyRoots} for the measurement that makes that a footgun rather than an option.
+ */
+export interface ReadOnlyRoot {
+  /** Absolute guest path, e.g. `/mnt/memhtml`. Never `/`, never nested inside another root's path. */
+  readonly mountPath: string
+  /** An existing directory on the host. Mounted read-only; nothing under it is ever written. */
+  readonly hostPath: string
+}
+
+/** The composed filesystem, plus the roots that reached it in mount order. */
+export interface MountedFilesystem {
+  /** Hand this to `just-bash`'s `Bash`/`Sandbox`, or return it from eve's `filesystem` factory. */
+  readonly filesystem: IFileSystem
+  readonly roots: ReadonlyArray<ReadOnlyRoot>
+}
+
+/** A root declaration this composition cannot honour. Carries the reason, never a file's content. */
+export class SandboxMountInvalid extends Error {
+  override readonly name = "SandboxMountInvalid"
+}
+
+/**
+ * Why a set of roots cannot be mounted, or `null`.
+ *
+ * Pure except for `statSync` on each host path, and separate from {@link mountReadOnlyRoots} for one
+ * reason: **eve does NOT invoke the `filesystem` factory during template prewarming**
+ * (node_modules/eve/dist/src/public/sandbox/just-bash-sandbox.d.ts, `filesystem`), so a bad root
+ * would otherwise surface on the first live session, inside a spawned server, wrapped by eve as
+ * "Failed to create the custom just-bash filesystem", after a sleep run already committed earlier
+ * phases. A caller that can name its roots before spawning calls this first and fails there.
+ *
+ * The rules, in the order a caller trips them:
+ *
+ * - `mountPath` must be absolute, already normalized, and free of a trailing slash.
+ *   `MountableFs.mount` rejects `.`/`..` segments itself, but it silently normalizes a relative path,
+ *   a doubled separator, and a trailing slash. The declared path and the effective mount would then
+ *   differ, so a typo would mount somewhere other than where it reads. Note `/mnt/memhtml/`
+ *   survives `path.normalize` unchanged (probed), so the trailing slash needs its own check.
+ * - `mountPath` may not be `/` and may not nest inside another root's path. `MountableFs` throws on
+ *   both ("Cannot mount at root '/'", "Cannot mount at 'X': inside existing mount 'Y'", probed),
+ *   which this restates as one typed reason naming both paths.
+ * - `hostPath` must be an existing DIRECTORY. `OverlayFs`'s constructor does check this eagerly
+ *   ("OverlayFs root does not exist" / "is not a directory", probed), which is the one gotcha that
+ *   was already handled upstream; it is repeated here so one call answers for every root instead of
+ *   throwing on the first bad one with no mention of the mount it belongs to.
+ */
+export const readOnlyRootsProblem = (roots: ReadonlyArray<ReadOnlyRoot>): string | null => {
+  const claimed: string[] = []
+  for (const root of roots) {
+    const { mountPath, hostPath } = root
+    if (mountPath === "/") {
+      return 'mount path "/" is not mountable: the base filesystem owns the root'
+    }
+    if (
+      !mountPath.startsWith("/") ||
+      mountPath.endsWith("/") ||
+      normalize(mountPath) !== mountPath
+    ) {
+      return `mount path ${JSON.stringify(mountPath)} must be an absolute, normalized guest path`
+    }
+    for (const taken of claimed) {
+      if (taken === mountPath) return `mount path ${mountPath} is declared twice`
+      if (mountPath.startsWith(`${taken}/`) || taken.startsWith(`${mountPath}/`)) {
+        return `mount paths ${taken} and ${mountPath} nest, which MountableFs refuses`
+      }
+    }
+    claimed.push(mountPath)
+
+    let stats: ReturnType<typeof statSync>
+    try {
+      stats = statSync(hostPath)
+    } catch (cause) {
+      return `host path ${hostPath} for mount ${mountPath} is unreadable: ${String(cause)}`
+    }
+    if (!stats.isDirectory()) {
+      return `host path ${hostPath} for mount ${mountPath} is not a directory`
+    }
+  }
+  return null
+}
+
+/**
+ * Compose a filesystem with each host root mounted read-only at its guest path.
+ *
+ * ## `mountPoint: "/"` on the nested overlay decides which paths resolve, and a file count cannot say
+ *
+ * `MountableFs` routes a path to a mount by stripping the mount prefix and handing the REMAINDER to
+ * the mounted filesystem (`routePath` in just-bash's bundle), while `OverlayFs` applies its own
+ * `mountPoint`, default `/home/user/project`, to whatever it is handed. So the two prefixes
+ * compose, and all three spellings resolve a real file at a DIFFERENT path. Re-probed 2026-08-09
+ * against a two-file fixture, mounting at `/mnt/memhtml`:
+ *
+ * | overlay `mountPoint` | path that reads the file |
+ * | --- | --- |
+ * | `"/"` | `/mnt/memhtml/sub/a.txt` (intended) |
+ * | omitted | `/mnt/memhtml/home/user/project/sub/a.txt` |
+ * | `"/mnt/memhtml"` | `/mnt/memhtml/mnt/memhtml/sub/a.txt` |
+ *
+ * **Every variant reports the same file count**, so a census assertion cannot tell them apart; only
+ * reading a path does. That is why `mountPoint` is not on {@link ReadOnlyRoot} at all. The option
+ * has exactly one correct value under a `MountableFs`, and offering it would be offering two ways to
+ * get a filesystem that looks populated and answers no path a caller would write.
+ *
+ * ## What read-only means here, measured rather than assumed
+ *
+ * `readOnly: true` is enforced rather than advisory: a write through the composed filesystem throws
+ * `EROFS: read-only file system`, and through `Bash` the command throws the same. `..` traversal out
+ * of a mount and an absolute `/etc/hostname` both fail, because the overlay resolves a guest path
+ * against its own root and returns nothing outside it. And `allowSymlinks` defaults to FALSE, so a
+ * symlink under a mounted root is not followed: any real path traversing one is rejected. That is the
+ * safe direction, and it costs reachability. `~/.claude/skills/*` holds symlinks to directories
+ * outside the trace root, and those read as absent inside the sandbox.
+ *
+ * ## The base filesystem stays writable
+ *
+ * `base` is whatever the caller already owns; every unmounted path routes to it. For eve that is
+ * `defaultFilesystem` from the `filesystem` factory, which owns `/workspace`, `/tmp`, and the home
+ * directory. eve's contract requires those to survive
+ * (node_modules/eve/dist/src/public/sandbox/just-bash-sandbox.d.ts) and mounting only under `/mnt/*`
+ * is what preserves them. The default is an `InMemoryFs`, which is what a standalone caller wants
+ * and what `MountableFs` would have defaulted to anyway.
+ *
+ * @throws {SandboxMountInvalid} when {@link readOnlyRootsProblem} rejects the roots.
+ */
+export const mountReadOnlyRoots = (input: {
+  readonly roots: ReadonlyArray<ReadOnlyRoot>
+  readonly base?: IFileSystem | undefined
+}): MountedFilesystem => {
+  const problem = readOnlyRootsProblem(input.roots)
+  if (problem !== null) throw new SandboxMountInvalid(problem)
+
+  const filesystem = new MountableFs({ base: input.base ?? new InMemoryFs() })
+  for (const root of input.roots) {
+    filesystem.mount(
+      root.mountPath,
+      new OverlayFs({ root: root.hostPath, mountPoint: "/", readOnly: true })
+    )
+  }
+  return { filesystem, roots: [...input.roots] }
+}
+
+/**
+ * The variable a spawning process uses to tell a sandbox process what to mount.
+ *
+ * The `filesystem` factory runs inside the eve SERVER, and the roots are decided by the CLIENT that
+ * spawned it. Those are two processes, so the roots have to cross a process boundary, and the spawn
+ * environment is the only channel eve's CLI leaves open. One variable rather than one per root, so
+ * the order and the pairing survive: a `MEMHTML_SANDBOX_TRACE_ROOT`-style set of variables cannot express
+ * "these three, in this order" and would need a new variable per consumer.
+ */
+export const SANDBOX_MOUNTS_ENV = "MEMHTML_SANDBOX_MOUNTS"
+
+/** Render roots for {@link SANDBOX_MOUNTS_ENV}. Validated first, so a spawn cannot carry a bad root. */
+export const encodeSandboxMounts = (roots: ReadonlyArray<ReadOnlyRoot>): string => {
+  const problem = readOnlyRootsProblem(roots)
+  if (problem !== null) throw new SandboxMountInvalid(problem)
+  return JSON.stringify(
+    roots.map((root) => ({ mountPath: root.mountPath, hostPath: root.hostPath }))
+  )
+}
+
+/**
+ * Read roots back out of an environment. An absent or empty variable means no mounts, not an error.
+ *
+ * A MALFORMED variable throws, and the two cases are split for a reason: absent is the normal case
+ * for a sandbox with nothing to mount, while a variable that is present and unparseable means the
+ * spawner meant to mount something and this process would silently run without it. A sandbox that
+ * quietly lost its corpus answers questions about an empty corpus, which reads as a finding.
+ *
+ * @throws {SandboxMountInvalid} when the value is present and not a valid root array.
+ */
+export const decodeSandboxMounts = (
+  env: Record<string, string | undefined>
+): ReadonlyArray<ReadOnlyRoot> => {
+  const raw = env[SANDBOX_MOUNTS_ENV]
+  if (raw === undefined || raw.trim() === "") return []
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (cause) {
+    throw new SandboxMountInvalid(`${SANDBOX_MOUNTS_ENV} is not valid JSON: ${String(cause)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new SandboxMountInvalid(`${SANDBOX_MOUNTS_ENV} must hold an array of roots`)
+  }
+
+  const roots: ReadOnlyRoot[] = []
+  for (const entry of parsed) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new SandboxMountInvalid(`${SANDBOX_MOUNTS_ENV} holds a non-object entry`)
+    }
+    const { mountPath, hostPath } = entry as Record<string, unknown>
+    if (typeof mountPath !== "string" || typeof hostPath !== "string") {
+      throw new SandboxMountInvalid(
+        `${SANDBOX_MOUNTS_ENV} entries need string mountPath and hostPath`
+      )
+    }
+    roots.push({ mountPath, hostPath })
+  }
+
+  const problem = readOnlyRootsProblem(roots)
+  if (problem !== null) throw new SandboxMountInvalid(`${SANDBOX_MOUNTS_ENV}: ${problem}`)
+  return roots
+}
+
+/** A materialized commit, and how to remove it. */
+export interface CorpusSnapshot {
+  /** The detached worktree's directory, suitable as a {@link ReadOnlyRoot} `hostPath`. */
+  readonly hostPath: string
+  /** Removes the worktree and its administrative entry. Safe to call twice. */
+  readonly release: () => Promise<void>
+}
+
+const run = promisify(execFile)
+
+/**
+ * Materialize one commit of a repository as a directory, for mounting.
+ *
+ * **A sleep run's live working tree is not a snapshot of anything.** `packages/sleep/src/run.ts:96`
+ * checks out the run's own branch before any phase executes, and earlier phases commit onto it, so
+ * the directory a later phase would mount mutates underneath it. A consolidation that read the
+ * corpus "as it is" would be reading a corpus its own siblings edited seconds earlier, and would
+ * report a state no reviewer can reproduce. `git worktree add --detach` at the run's `baseSha` is
+ * the tree the reviewer diffs against, which makes "what the agent saw" and "what the review shows"
+ * the same tree by construction rather than by timing.
+ *
+ * `--detach` and not a branch: a named branch would be a second ref on a sha the run already tracks,
+ * and `git worktree remove` of a branch-carrying worktree leaves the branch behind.
+ */
+export const pinCorpusSnapshot = async (input: {
+  readonly repoRoot: string
+  readonly sha: string
+}): Promise<CorpusSnapshot> => {
+  const parent = mkdtempSync(join(tmpdir(), "memhtml-corpus-snapshot-"))
+  const hostPath = join(parent, "tree")
+  await run("git", ["-C", input.repoRoot, "worktree", "add", "--detach", hostPath, input.sha])
+
+  let released = false
+  return {
+    hostPath,
+    release: async () => {
+      if (released) return
+      released = true
+      // `--force` because the mount is read-only but the worktree is a real directory a reader may
+      // have left something in; a refusal here would leak a worktree entry into the repo's config.
+      await run("git", ["-C", input.repoRoot, "worktree", "remove", "--force", hostPath]).catch(
+        () => {}
+      )
+    }
+  }
+}

package/src/run-auth.ts

@@ -0,0 +1,231 @@
+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
+ *
+ * `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).
+ *
+ * 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
+ * sandbox that reaches IMDS. `agent/sandbox/sandbox.ts` records that egress cannot be closed here;
+ * this module closes the handle.
+ *
+ * ## The mechanism
+ *
+ * One HS256 bearer JWT over a secret this process mints per spawn from `randomBytes`, verified by
+ * eve's own `jwtHmac` strategy (node_modules/eve/dist/src/public/channels/auth.d.ts:451, config shape
+ * at :41-60). The secret crosses to the server on the SPAWN ENVIRONMENT, which is the same channel
+ * `mount.ts` uses for mount roots and for the same reason: the auth policy is evaluated in the eve
+ * SERVER process while the value is decided by the CLIENT that spawns it.
+ *
+ * **No eve import here.** `VerifyJwtHmacConfig` is a plain interface, so {@link RunVerifierConfig}
+ * restates it structurally, the same move `contract.ts` makes for `JsonObject`. That keeps
+ * 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.
+ */
+
+/**
+ * The variable a spawning client uses to hand the server the run's secret.
+ *
+ * Named for its LIFETIME rather than its content, because the lifetime is the security property: one
+ * spawn, one secret. A value that survived a run, such as a fixed default, a config key, or anything
+ * a caller could supply, would reopen the window this closes, since the window is exactly "how long
+ * is a credential that reaches this endpoint good for".
+ */
+export const RUN_SECRET_ENV = "MEMHTML_CONSOLIDATOR_RUN_SECRET"
+
+/**
+ * How many random bytes a run secret carries. 32 = 256 bits, matching HS256's hash output.
+ *
+ * RFC 7518 §3.2 requires an HMAC key at least the size of the hash output, and eve keys the verifier
+ * with `createSecretKey(Buffer.from(secret, "utf8"))`
+ * (node_modules/eve/dist/src/runtime/governance/auth/jwt-hmac.js), so the KEY MATERIAL is the
+ * base64url text, 43 bytes, carrying these 32 bytes of entropy. Both the byte count and the encoded
+ * length clear the floor.
+ *
+ * The floor is not enforced anywhere else. Probed against the installed eve: a three-character secret
+ * verifies its own token happily, because jose does not check HS key width on verify. So
+ * {@link runSecretFrom} enforces it, or a hand-set variable would be a password.
+ */
+const SECRET_BYTES = 32
+
+/**
+ * The minimum length a secret read from the environment may have, in characters.
+ *
+ * `base64url(32 bytes)` is exactly 43 unpadded characters, so this is the length {@link mintRunSecret}
+ * produces rather than a number picked to be round. A shorter value is REFUSED rather than accepted
+ * with a warning: an under-width HMAC key is the one failure mode eve's verifier will not catch.
+ */
+const MIN_SECRET_CHARS = 43
+
+/** The signature algorithm, on both sides, as one constant so they cannot drift apart. */
+const ALGORITHM = "HS256" as const
+
+/** The `node:crypto` hash name `HS256` denotes. Paired with {@link ALGORITHM} and never separately. */
+const HMAC_HASH = "sha256"
+
+/**
+ * `iss`, `aud`, and `sub`, all three matched by the verifier.
+ *
+ * Redundant with the signature and deliberately so: a secret that leaked into some other eve app's
+ * environment still mints nothing this channel accepts, because `subjects` and `audiences` are
+ * checked after the signature (`areTokenClaimMatchersSatisfied` in
+ * node_modules/eve/dist/src/runtime/governance/auth/token-claims.js). They cost one string compare
+ * each and they make a misconfiguration fail closed instead of cross-authenticating.
+ *
+ * `sub` is REQUIRED by eve independently of `subjects`: the strategy rejects a token whose `sub` is
+ * absent or empty before it looks at any matcher (jwt-hmac.js, verified live).
+ */
+const ISSUER = "memhtml-consolidator"
+const AUDIENCE = "memhtml-consolidator/eve"
+const SUBJECT = "memhtml-consolidator-client"
+
+/**
+ * How long one token is good for. Seconds.
+ *
+ * Short because it does not have to cover the run: the client passes the FUNCTION form of eve's
+ * `TokenValue`, which resolves before every HTTP call
+ * (node_modules/eve/dist/src/client/types.d.ts:49-69), so a 10-minute turn presents a fresh token on
+ * every request rather than one token held open for the turn. That decouples the credential's
+ * lifetime from `TURN_TIMEOUT_MS` entirely: a stream reconnect ten minutes in signs a new token.
+ *
+ * 120s rather than something tighter because the bound that matters is the SERVER's lifetime (one
+ * run), and a token has to survive being minted before a request that then queues behind a model
+ * call's connection setup.
+ */
+const TOKEN_TTL_SECONDS = 120
+
+/**
+ * Clock skew the verifier tolerates, in seconds. eve defaults to 30.
+ *
+ * 5 because there is no skew to tolerate: the signer and the verifier are two processes on ONE host
+ * reading one clock, so the 30s default is budget for a distributed issuer this deployment does not
+ * have. It is the difference between a token being good for 125s and 150s.
+ */
+const CLOCK_SKEW_SECONDS = 5
+
+/**
+ * eve's `VerifyJwtHmacConfig`, restated structurally.
+ *
+ * Field for field with node_modules/eve/dist/src/public/channels/auth.d.ts:41-60, minus the two
+ * optional matchers this app does not use. Declared rather than imported to keep `src/` free of eve.
+ * See the note at the top of this module.
+ */
+export interface RunVerifierConfig {
+  readonly algorithm: "HS256" | "HS384" | "HS512"
+  readonly audiences: readonly string[]
+  readonly issuer: string
+  readonly secret: string
+  readonly clockSkewSeconds: number
+  readonly subjects: readonly string[]
+}
+
+/**
+ * A fresh secret for one spawn.
+ *
+ * `randomBytes` and not `randomUUID`: a UUIDv4 carries 122 bits in a fixed 36-character shape, which
+ * is under the HS256 key floor {@link SECRET_BYTES} exists to clear. base64url so the value is safe
+ * in an environment variable with no quoting question, since `+`, `/`, and `=` are all avoided.
+ */
+export const mintRunSecret = (): string => randomBytes(SECRET_BYTES).toString("base64url")
+
+/**
+ * The run's secret as read from an environment, or `null` when there is no usable one.
+ *
+ * `null` is the FAIL-CLOSED signal and the callers on both sides treat it that way: the channel turns
+ * it into a 401 by handing `routeAuth` a walk with nothing that can accept. Absent, blank, and
+ * under-width all collapse to `null` on purpose, since the caller's move is the same for each
+ * (refuse), and distinguishing them in a return value would invite a caller to accept one of them.
+ *
+ * The value is the credential, so it is not logged and not returned in a message.
+ */
+export const runSecretFrom = (env: Record<string, string | undefined>): string | null => {
+  const raw = env[RUN_SECRET_ENV]
+  if (raw === undefined) return null
+  const secret = raw.trim()
+  if (secret.length < MIN_SECRET_CHARS) return null
+  return secret
+}
+
+/**
+ * The verifier configuration for an environment, or `null` when it holds no usable secret.
+ *
+ * Both sides of the boundary read their claims from the constants above through this one function and
+ * {@link signRunToken}, so a mismatch between what is signed and what is accepted is not expressible.
+ * That matters because every claim mismatch fails the same silent way, as `{ ok: false }` with no
+ * detail (eve returns no reason so routes cannot leak which check failed, auth.d.ts:9-19).
+ */
+export const runVerifierConfig = (
+  env: Record<string, string | undefined>
+): RunVerifierConfig | null => {
+  const secret = runSecretFrom(env)
+  if (secret === null) return null
+  return {
+    algorithm: ALGORITHM,
+    audiences: [AUDIENCE],
+    issuer: ISSUER,
+    secret,
+    clockSkewSeconds: CLOCK_SKEW_SECONDS,
+    subjects: [SUBJECT]
+  }
+}
+
+/** base64url of a JSON value, which is the encoding both JWT segments use. */
+const segment = (value: unknown): string =>
+  Buffer.from(JSON.stringify(value), "utf8").toString("base64url")
+
+/**
+ * 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.
+ *
+ * `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.
+ */
+export const signRunToken = (input: { readonly secret: string }): string => {
+  const now = Math.floor(Date.now() / 1_000)
+  const head = segment({ alg: ALGORITHM, typ: "JWT" })
+  const body = segment({
+    iss: ISSUER,
+    aud: AUDIENCE,
+    sub: SUBJECT,
+    iat: now,
+    exp: now + TOKEN_TTL_SECONDS
+  })
+  const signature = createHmac(HMAC_HASH, Buffer.from(input.secret, "utf8"))
+    .update(`${head}.${body}`)
+    .digest("base64url")
+  return `${head}.${body}.${signature}`
+}
+
+/**
+ * Whether two secrets are the same value, compared in constant time.
+ *
+ * For a test that has to assert the secret the client minted is the secret the spawn carried without
+ * ever reading either one. `timingSafeEqual` throws on a length mismatch, so that case is answered
+ * before the compare rather than by catching.
+ */
+export const sameRunSecret = (left: string, right: string): boolean => {
+  const a = Buffer.from(left, "utf8")
+  const b = Buffer.from(right, "utf8")
+  return a.length === b.length && timingSafeEqual(a, b)
+}

package/state-migrations/S0001_access.sql

@@ -0,0 +1,48 @@
+-- The state plane, applied to the ATTACHed `state` database.
+--
+-- These are the only facts git cannot reproduce, and they are high-churn: bumping an access count
+-- on every retrieval would produce a commit per query. So `state.db` is gitignored and its
+-- durability story is the committed append-only sidecar `.memhtml/state/access.jsonl`, refreshed once
+-- per night by the sleep cycle's state-export phase. A fresh clone plus `memhtml state import` plus
+-- `memhtml index rebuild` therefore reproduces the whole system, access history included.
+--
+-- Rejected alternative: keeping these counters in the memory HTML files. It makes every retrieval a
+-- git write, makes retrieval order a source of merge conflicts, and breaks the content-hash
+-- invariance that lets a correction land on one entry alone.
+
+CREATE TABLE state.access (
+  -- No FK to main.files: cross-database foreign keys do not exist. The store's move() issues the
+  -- matching `UPDATE state.access SET path = ?` in the same batch as an archive, and `memhtml doctor`
+  -- reports orphaned rows.
+  path                TEXT PRIMARY KEY,
+  -- Times this memory was retrieved, gated by the 900-second cooldown. A count, monotonically
+  -- non-decreasing. The cooldown exists because this feeds the salience RRF arm: without it,
+  -- replaying one query ten times would inflate that memory's salience tenfold.
+  access_count        INTEGER NOT NULL DEFAULT 0 CHECK (access_count >= 0),
+  reinforcement_count INTEGER NOT NULL DEFAULT 0 CHECK (reinforcement_count >= 0),
+  -- An EWMA over reinforcement signals, unitless in [-1, 1]. The salience arm clamps the negative
+  -- half to 0. A memory that led somewhere bad is not boosted, and it is not buried either.
+  outcome_score       REAL    NOT NULL DEFAULT 0.0 CHECK (outcome_score BETWEEN -1 AND 1),
+  last_accessed_at    TEXT,
+  last_reinforced_at  TEXT,
+  updated_at          TEXT NOT NULL
+);
+-- The schema name goes on the INDEX, not on the table: `CREATE INDEX x ON state.access (...)` is a
+-- syntax error on this driver (probed 2026-08-02), while `CREATE INDEX state.x ON access (...)` is
+-- accepted and lands the index in the attached schema. Unqualified `access` resolves within it.
+CREATE INDEX state.access_last ON access (last_accessed_at);
+
+-- The corroboration counter on a machine-detected `contradicts`. The one derived fact that gates a
+-- retention penalty, so it lives in the durable plane; once `detections >= 2` the sleep conflict
+-- phase promotes the edge into both files as <link rel="memhtml-contradicts"> and commits it, after
+-- which this row is decoration and the fact is file-borne.
+CREATE TABLE state.edge_corroboration (
+  src_path   TEXT NOT NULL,
+  rel        TEXT NOT NULL,
+  dst_path   TEXT NOT NULL,
+  detections INTEGER NOT NULL DEFAULT 1 CHECK (detections >= 1),
+  confirmed  INTEGER NOT NULL DEFAULT 0 CHECK (confirmed IN (0,1)),
+  promoted   INTEGER NOT NULL DEFAULT 0 CHECK (promoted IN (0,1)),
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (src_path, rel, dst_path)
+);