memhtml 0.5.1 → 0.7.0

package/migrations/0007_watermark.sql

@@ -9,8 +9,10 @@ CREATE TABLE index_state (
   head_sha      TEXT,
   -- The vector space, as `<model-id>@<dim>` (@memhtml/llm's EMBED_WATERMARK). A mismatch against
   -- configuration is a hard refusal, never a silent reindex: a half-migrated vector space degrades
-  -- every cosine and is invisible in tests. Only `rebuild --embed-model` rewrites it, and it
-  -- truncates `embeddings` first.
+  -- every cosine and is invisible in tests. `rebuild --embed` is the one path past that refusal: it
+  -- truncates `embeddings` with the other memory tables and records the configured space before any
+  -- vector is written, so it migrates the whole space rather than mixing two. `--no-embed` refuses
+  -- before the truncate, so a store that refuses keeps the vectors it has.
   embed_model   TEXT NOT NULL,
   embed_dim     INTEGER NOT NULL CHECK (embed_dim > 0),
   rebuilt_at    TEXT NOT NULL,

package/migrations/0011_edge_indexes.sql

@@ -0,0 +1,78 @@
+-- `edges_src` and `edges_dst` carry NO predicate: `(src_path, edge_class)` and `(dst_path, edge_class)`
+-- over every row, authored and derived alike. That is what the memory-graph walk needs, and a partial
+-- index on `derived = 0` cannot serve it at all.
+--
+-- ── Why a predicate makes the index unreachable ───────────────────────────────────────────────────
+--
+-- SQLite may use a partial index only when the query's WHERE clause IMPLIES the index's WHERE clause.
+-- The neighbors walk (`neighborsQuery`, `apps/cli/src/operations.ts`) filters
+-- `src_path = ?1 AND edge_class = 'memory'` and SELECTS `e.derived`, because it wants BOTH kinds of
+-- edge: sleep-mined edges are what lateral retrieval is for, and each node reports which kind reached
+-- it. `edge_class = 'memory'` does not imply `derived = 0`, so an index declared `WHERE derived = 0` is
+-- simply not a candidate.
+--
+-- Measured 2026-08-26 on node 24.19.0's `node:sqlite` with these migrations applied and no `ANALYZE`,
+-- over the walk's own statement at depth 2. With the predicate:
+--
+--   * the two `src_path = ?1` arms probe `sqlite_autoindex_edges_1`, because `src_path` leads
+--     `PRIMARY KEY (src_path, rel, dst_path)`, which binds ONE column;
+--   * the `dst_path = ?1` hop-1 arm is `SCAN e`, a full pass over `edges`;
+--   * the `dst_path`-driven hop-2 arm is `SCAN e2 USING INDEX sqlite_autoindex_edges_1`, a full index
+--     scan of the table per outer row.
+--
+-- Without it, all four arms are `SEARCH … (src_path=? AND edge_class=?)` or
+-- `(dst_path=? AND edge_class=?)`: two bound columns instead of one, in every direction.
+--
+-- ── A REPLACEMENT, and the per-statement census behind that ──────────────────────────────────────
+--
+-- Measured the same way over every statement in the tree that reads `edges` — the walk, both
+-- authored-only anti-joins in `@memhtml/sleep` (`sharedEntityPairs`, `minedPairs`), `retentionEdgeCounts`,
+-- `memoryEdges`, `deepGroupingEdges`, `inboundAuthoredEdges`, `danglingEdges`, retrieval's
+-- `superseded_by` subquery, `doctor`'s stale-blocker join, `task list`'s blockers column, the indexer's
+-- delete-by-source, and `movePath`'s `UPDATE edges SET src_path`. FIVE change plan, and every one of the
+-- five gets a probe it did not have or binds a column more:
+--
+--   * both `dst_path` walk arms, `SCAN e` -> `edges_dst (dst_path=? AND edge_class=?)`;
+--   * both `src_path` walk arms, `sqlite_autoindex_edges_1 (src_path=?)` -> `edges_src (src_path=? AND
+--     edge_class=?)`;
+--   * `retentionEdgeCounts`, `SCAN e` plus a temp b-tree -> `SCAN e USING COVERING INDEX edges_dst`, so
+--     it stops building an `AUTOMATIC PARTIAL COVERING INDEX` per call;
+--   * `task list`'s blockers subquery, `edges_rel (rel, edge_class)` -> `edges_dst (dst_path,
+--     edge_class)`, binding a path rather than the rel `'blocks'`;
+--   * the indexer's delete-by-source and `movePath`'s update, `sqlite_autoindex_edges_1 (src_path=?)` ->
+--     `edges_src (src_path=?)`.
+--
+-- The rest are byte-identical, including retrieval's `superseded_by` subquery, which probes
+-- `edges_dst (dst_path=? AND edge_class=?)` under BOTH shapes — it names the class, so it never depended
+-- on the predicate. The `derived = 0` readers that do not name a path reach for `edges_derived (derived,
+-- rel)`, which binds two columns where either directional pair binds one.
+--
+-- The predicate is not free to keep, and the cost is not the index COUNT: `edges` carries four either
+-- way. It is that a partial index holds only the authored rows. Dropping the predicate puts every mined
+-- edge in both b-trees, and mining writes thousands per run — measured 2026-08-26, 20,000 derived-edge
+-- inserts in one transaction cost 158-162 ms with the predicate and 184-188 ms without it, three
+-- repetitions, so roughly 14-19% more per mined edge. That is the price of the walk's two probes, paid
+-- knowingly: a walk arm was a full pass over `edges` per hop.
+--
+-- ── ADDITIVE, in 0009's sense ────────────────────────────────────────────────────────────────────
+--
+-- `DROP INDEX` plus `CREATE INDEX`, and deliberately NOT 0008's recreate-and-copy. That pattern was
+-- forced by a CHECK-constraint edit, which SQLite cannot `ALTER`, and it carried real risk:
+-- `DROP TABLE edges` would cascade nothing here, but `DROP TABLE files` cascades to `embeddings` and
+-- 0008 had to snapshot six tables to avoid re-paying Bedrock for the whole corpus. An index is derived
+-- data with no rows of its own — dropping one loses nothing and recreating one costs a single scan of
+-- `edges` — so none of that machinery applies.
+--
+-- The NAMES are reused because the name states which column the index leads with, which is what a
+-- reader of a query plan needs from it, and that has not changed.
+--
+-- `IF EXISTS` on the drops, so this file converges from any starting state a real store can be in —
+-- including one where an operator dropped an index by hand in `sqlite3`. A bare `DROP` there would fail
+-- the migration inside its transaction and leave that store unable to open at all. The `CREATE`s carry
+-- no such guard on purpose: if either name is still taken when they run, that is a fact worth failing on.
+
+DROP INDEX IF EXISTS edges_src;
+DROP INDEX IF EXISTS edges_dst;
+
+CREATE INDEX edges_src ON edges (src_path, edge_class);
+CREATE INDEX edges_dst ON edges (dst_path, edge_class);

package/migrations/0012_origin_path.sql

@@ -0,0 +1,21 @@
+-- The archive mapping, read backwards. `origin_path` holds the pre-archive path of a file under
+-- `archive/<YYYY>/`, derived from the path itself by the projection, and NULL for an active file.
+--
+-- Without an index, answering "what became of the memory that lived at areas/oncall/x.html" is a
+-- `SCAN files` — the one question an external citation asks, since a correction with a reworded title
+-- moves the memory to a new path and leaves the cited one holding nothing. Measured 2026-08-26 on
+-- node 24's `node:sqlite` with no ANALYZE: `SCAN files` becomes `SEARCH files USING INDEX
+-- files_origin (origin_path=?)`.
+--
+-- PARTIAL on purpose, and the predicate IS reachable from the query: SQLite proves `origin_path = ?`
+-- implies `origin_path IS NOT NULL`, so the probe above is what a partial index yields (probed the
+-- same day, both forms). Most of a corpus is active, so the partial form keeps every live file out of
+-- an index that only archived files can answer from. Contrast `0011_edge_indexes.sql`, where the
+-- predicate had to GO: there the readers filter on a column the predicate does not mention, and an
+-- implication SQLite cannot prove makes the index no candidate at all.
+--
+-- No UNIQUE. One path can be archived more than once — written, evicted, written again at the same
+-- path, evicted again — and each eviction lands in its own `archive/<YYYY>/` partition, so two rows
+-- may legitimately carry one `origin_path`. The reader orders by `archived_at` and takes the newest.
+
+CREATE INDEX files_origin ON files (origin_path) WHERE origin_path IS NOT NULL;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memhtml",
-  "version": "0.5.1",
-  "description": "An agent's long-term memory: one fact per semantic HTML file in git, four-arm retrieval, and a nightly sleep cycle.",
+  "version": "0.7.0",
+  "description": "An agent's long-term memory: one fact per semantic HTML file in git, four-arm retrieval, and a curation sleep cycle.",
   "keywords": [
     "memory",
     "agent",
@@ -40,16 +40,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.57",
-    "@aws-sdk/client-bedrock-runtime": "3.1111.0",
+    "@ai-sdk/amazon-bedrock": "5.0.61",
+    "@aws-sdk/client-bedrock-runtime": "3.1116.0",
     "@aws/bedrock-token-generator": "1.1.0",
-    "@effect/platform-node": "4.0.0-rc.109",
-    "@effect/platform-node-shared": "4.0.0-rc.109",
-    "ai": "7.0.66",
-    "effect": "4.0.0-rc.109",
-    "eve": "0.38.3",
+    "@effect/platform-node": "4.0.0-rc.111",
+    "@effect/platform-node-shared": "4.0.0-rc.111",
+    "ai": "7.0.77",
+    "effect": "4.0.0-rc.111",
+    "eve": "0.44.1",
     "highlight.js": "11.11.2",
-    "just-bash": "3.3.0",
+    "just-bash": "3.4.2",
     "node-html-parser": "9.0.1",
     "parse5": "8.0.1",
     "zod": "4.4.3"

package/src/agent-build.ts

@@ -1,11 +1,22 @@
 import { spawn } from "node:child_process"
 import { existsSync } from "node:fs"
-import { cp, mkdir, readdir, readFile, symlink, writeFile } from "node:fs/promises"
+import {
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  symlink,
+  writeFile
+} from "node:fs/promises"
 import { createRequire } from "node:module"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { Effect } from "effect"
 
+import { appendStderrTail, stderrMessageTail } from "./child-stderr.js"
 import { ConsolidatorUnavailable } from "./contract.js"
 
 /**
@@ -30,6 +41,33 @@ import { ConsolidatorUnavailable } from "./contract.js"
  * (`server/node_modules/node-liblzma/build/Release/node_lzma.node`) and eve says so itself — "Ensure
  * your production environment matches the builder OS and architecture (linux-x64)". A published
  * artifact cannot carry one platform's binaries.
+ *
+ * ## A finished build belongs to the directory it was built in
+ *
+ * `eve build` writes the ABSOLUTE path of its build directory into its own output: `appRoot` and
+ * `agentRoot` in the `manifest` literal inside `.output/server/index.mjs`, taken from the process cwd
+ * (eve offers no root flag — `dist/src/cli/application-root.js` derives the root from
+ * `process.cwd()`). And `eve start` does not merely carry those strings: it RE-BUNDLES the authored
+ * TypeScript found at `<agentRoot>/agent.ts` on first load
+ * (`dist/src/internal/authored-module-loader.js`) and writes the resulting bundle into a cache
+ * directory it creates under that same root. Three constraints follow, and the third is the one a
+ * reader is likeliest to break:
+ *
+ * 1. The directory `eve build` ran in is the only directory `eve start` can serve. A finished build
+ *    that is moved or renamed makes eve's `resolveAuthoredPackageRoot` walk the vanished path looking
+ *    for a `package.json`, reach `/`, and exit 1 on `Failed to resolve the authored package root for
+ *    "…/agent/agent.ts"`.
+ * 2. That directory must still hold the agent SOURCE, not just `.output/`. A tree published with
+ *    `.output/` alone fails identically, because the source is what gets re-bundled.
+ * 3. That directory must stay WRITABLE for the server's whole life, since the bundle cache is written
+ *    on first load rather than at build time.
+ *
+ * Probed live 2026-08-25 against eve 0.38.3: a build that answered `/eve/v1/health` where it was built
+ * exited 1 with that message after nothing but a `rename` of its directory, its baked `appRoot` still
+ * naming the old path.
+ *
+ * So the build runs AT the cache root and is never built elsewhere and moved in. What makes an
+ * unfinished build detectable without a move is {@link BUILD_COMPLETE_MARKER}, written last.
  */
 
 /**
@@ -41,8 +79,9 @@ import { ConsolidatorUnavailable } from "./contract.js"
  *
  * Resolution goes through the MANIFEST, not the bin. `resolve("eve/bin/eve.js")` raises
  * `ERR_PACKAGE_PATH_NOT_EXPORTED`: eve's `exports` map declares no `./bin/*` subpath, so node refuses
- * the deep path even though the file is there (probed against eve 0.33.0). `./package.json` IS
- * exported, and the `bin` field beside it names the entry point.
+ * the deep path even though the file is there. `tests/start-port.test.ts` re-proves both halves
+ * against the INSTALLED eve on every run — the deep path refused, `./package.json` exported with a
+ * real `bin` beside it — so an eve release that changes either fails there.
  */
 export const eveBinPath = (): string | null => {
   const require = createRequire(import.meta.url)
@@ -61,6 +100,57 @@ export const eveBinPath = (): string | null => {
 const cacheRootFor = (version: string): string =>
   join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "memhtml", "eve", version)
 
+/**
+ * The file whose PRESENCE says the cache directory holds a COMPLETED build.
+ *
+ * `.output/` existing cannot say that: a process killed while the tree was being staged or built
+ * leaves a partial directory that an existence check reads as complete — forever, because nothing
+ * would ever rebuild it, and `eve start` over a partial tree is a server that fails in whatever way
+ * the missing half implies. This marker is written LAST, only after `eve build` exits 0 with its
+ * {@link BUILT_SERVER_ENTRY} verified on disk, and it is the ONLY thing {@link cacheBuildComplete}
+ * trusts. A cache directory without it, whatever else it holds, is a partial to discard and rebuild.
+ *
+ * Writing it last is what a publishing `rename` would otherwise buy, and it is the shape that is
+ * compatible with an output which cannot be relocated (see the note at the top of this file). It is
+ * also the finalizer's discriminator: a markerless cache root is this build's own wreckage and gets
+ * removed, a marked one is a finished build and never does.
+ */
+const BUILD_COMPLETE_MARKER = ".memhtml-build-complete"
+
+/** Where a completed build's marker sits. Exported logic's one source of the path. */
+const buildMarkerPath = (cacheRoot: string): string => join(cacheRoot, BUILD_COMPLETE_MARKER)
+
+/**
+ * The file `eve start` serves, relative to a built root.
+ *
+ * A build is verified against THIS PATH rather than against `.output/`, because `eve build` exiting 0
+ * is not the same claim as `eve build` having emitted a server. An empty-but-present `.output/` earns
+ * the completion marker under a directory check, and the marker is permanent — so the box would serve
+ * an app with no entry point for that version's whole life. It is the "a scanner can exit 0 having
+ * produced nothing" hazard in build form, and the entry file is the artifact whose absence a boot
+ * would discover.
+ */
+const BUILT_SERVER_ENTRY = join(".output", "server", "index.mjs")
+
+/**
+ * How old a build lock may be before another process takes it over.
+ *
+ * The lock (a `mkdir`-ed sibling directory) is held for one stage-plus-build, measured in tens of
+ * seconds for the ~17 MB output. Ten minutes says its holder is dead — killed between `mkdir` and
+ * the `finally` that removes it — rather than slow, and a dead holder's lock would otherwise block
+ * every future run on this box for this version.
+ */
+const BUILD_LOCK_STALE_MS = 10 * 60_000
+
+/** How often a waiting process re-checks the marker and the lock. */
+const BUILD_LOCK_POLL_MS = 500
+
+/**
+ * How long a process waits on another's build before giving up. Stale takeover happens well before
+ * this; the budget only binds when a LIVE holder builds for longer than the stale age plus a poll.
+ */
+const BUILD_WAIT_BUDGET_MS = BUILD_LOCK_STALE_MS + 60_000
+
 /** A bare specifier's package name: two segments when scoped, one otherwise. */
 const packageOf = (specifier: string): string => {
   const parts = specifier.split("/")
@@ -201,10 +291,12 @@ const runEveBuild = (input: {
       cwd: input.cwd,
       stdio: ["ignore", "ignore", "pipe"]
     })
+    // Only a bounded TAIL is retained, and the failure message below renders the END of it. Both
+    // rules are `child-stderr.ts`'s, shared with the `eve start` child in `client.ts`.
     let stderr = ""
     child.stderr.setEncoding("utf8")
     child.stderr.on("data", (chunk: string) => {
-      stderr += chunk
+      stderr = appendStderrTail(stderr, chunk)
     })
     child.once("error", (cause) => {
       resume(
@@ -219,7 +311,7 @@ const runEveBuild = (input: {
           ? Effect.void
           : Effect.fail(
               ConsolidatorUnavailable.make({
-                reason: `eve build exited with code ${String(code)} in ${input.cwd}. ${stderr.slice(-400)}`
+                reason: `eve build exited with code ${String(code)} in ${input.cwd}. ${stderrMessageTail(stderr)}`
               })
             )
       )
@@ -229,6 +321,118 @@ const runEveBuild = (input: {
     })
   })
 
+/**
+ * Whether a cache directory holds a COMPLETED build. The marker is the answer; `.output/` alone is
+ * not, because a killed `eve build` leaves a partial `.output/` behind. See
+ * {@link BUILD_COMPLETE_MARKER}, which is written only beside a verified {@link BUILT_SERVER_ENTRY}.
+ */
+export const cacheBuildComplete = (cacheRoot: string): boolean =>
+  existsSync(buildMarkerPath(cacheRoot)) && existsSync(join(cacheRoot, ".output"))
+
+/** A held build lock: the directory to remove when done. */
+interface BuildLock {
+  readonly release: () => Promise<void>
+}
+
+/**
+ * Move a lock believed stale out of the way, and refuse to move any other lock.
+ *
+ * ## `rename` is the arbitration; an `rm` is not
+ *
+ * Two waiters can measure the same stale lock and both decide to take it over. An unconditional
+ * `rm(lockDir)` there is not an arbitration at all — it says nothing about WHICH directory it removed,
+ * so the ordering `stat(A), stat(B), rm(A), mkdir(A), rm(B), mkdir(B)` leaves A and B both holding: B's
+ * `rm` deleted the fresh lock A had just created, and B's `mkdir` then succeeded. `rename` narrows
+ * that: for one directory instance exactly one racer's rename can succeed, so the loser gets ENOENT and
+ * returns to the `mkdir`, where the winner's fresh lock excludes it.
+ *
+ * ## The inode is what binds the rename to the lock that was MEASURED
+ *
+ * `rename` alone still moves whatever sits at the path. A waiter's staleness reading is taken before
+ * its rename, and in between the takeover winner can have released and a third process can have created
+ * a fresh lock at the same path — renaming THAT aside would delete a live holder's lock and hand this
+ * waiter a second, concurrent hold, which is the same defect one step later. So a claim whose renamed
+ * directory is not the inode the staleness was read from is put straight back and this waiter acquires
+ * nothing; only the measured directory is ever discarded.
+ *
+ * The residual is the moment between such a mistaken rename and its restore, during which the path is
+ * empty and a waiter arriving at the top of the loop can `mkdir` it. That window is microseconds of
+ * filesystem calls and it costs at most what the previous shape cost always.
+ *
+ * Exported for `tests/agent-build.test.ts`, which drives both arms directly: the interleaving above
+ * cannot be forced through {@link acquireBuildLock} from one process.
+ */
+export const claimStaleLock = async (lockDir: string, staleIno: number): Promise<void> => {
+  const aside = `${lockDir}.stale-${String(process.pid)}`
+  await rm(aside, { recursive: true, force: true }).catch(() => {})
+  const claimed = await rename(lockDir, aside).then(
+    () => true,
+    () => false
+  )
+  if (!claimed) return
+  const moved = await stat(aside).then(
+    (stats) => stats.ino,
+    () => null
+  )
+  if (moved !== staleIno) {
+    await rename(aside, lockDir).catch(() => {})
+    return
+  }
+  await rm(aside, { recursive: true, force: true }).catch(() => {})
+}
+
+/**
+ * Take the per-version build lock, waiting out or taking over another holder.
+ *
+ * `mkdir` without `recursive` is the primitive: it either creates the directory (the lock is ours)
+ * or throws `EEXIST` (someone holds it), atomically, on every filesystem node runs on. Two runs on
+ * one box CAN race here — the sleep cycle and a hand-driven `memhtml` both resolving the same
+ * unbuilt version — and without the lock both would build into the shared cache root at once,
+ * interleaving two `eve build`s' output.
+ *
+ * A holder that died between its `mkdir` and its `release` (SIGKILL leaves no `finally`) is detected
+ * by the lock directory's AGE: past {@link BUILD_LOCK_STALE_MS} it cannot be a live build, so the
+ * waiter claims it through {@link claimStaleLock} and retries the `mkdir`. The claim is a `rename`
+ * bound to the inode the staleness was measured on, and that binding is what keeps two waiters from
+ * both ending up holding: see that function for the interleaving an unconditional `rm` admits.
+ *
+ * Exported for `tests/agent-build.test.ts`, which proves the lock excludes and the stale takeover
+ * fires; no production caller outside {@link resolveAgentAppRoot} reaches it.
+ */
+export const acquireBuildLock = async (cacheRoot: string): Promise<BuildLock> => {
+  const lockDir = `${cacheRoot}.lock`
+  // The lock is taken before anything else touches the cache tree, so its parent may not exist yet.
+  // Created separately from the lock itself: `recursive: true` on the lock mkdir would report
+  // success on an ALREADY-EXISTING directory, which is exactly the case the lock must refuse.
+  await mkdir(dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + BUILD_WAIT_BUDGET_MS
+  for (;;) {
+    try {
+      await mkdir(lockDir)
+      return { release: () => rm(lockDir, { recursive: true, force: true }).catch(() => {}) }
+    } catch (cause) {
+      if ((cause as { readonly code?: string }).code !== "EEXIST") throw cause
+    }
+    // The inode travels with the age, because the claim below acts on the directory this reading
+    // describes and not merely on the path it sits at.
+    const held = await stat(lockDir).then(
+      (stats) => ({ age: Date.now() - stats.mtimeMs, ino: stats.ino }),
+      () => null
+    )
+    if (held !== null && held.age > BUILD_LOCK_STALE_MS) {
+      await claimStaleLock(lockDir, held.ino)
+      continue
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `another process has held the build lock ${lockDir} past the wait budget; ` +
+          "remove it if no eve build is running"
+      )
+    }
+    await new Promise((done) => setTimeout(done, BUILD_LOCK_POLL_MS))
+  }
+}
+
 /**
  * The directory `eve start` will be run in, building the agent first when nothing has.
  *
@@ -236,6 +440,27 @@ const runEveBuild = (input: {
  * package that already holds `.output/` is a checkout where `build:agent` has run, and reusing it keeps
  * development behavior byte-identical. Only the remaining case — an installed package with no output —
  * materializes the cache directory, and it costs one ~17 MB build per version rather than one per run.
+ *
+ * ## Completion is the MARKER, written last
+ *
+ * The build runs AT the cache root, because that is the only directory its output works from — a
+ * finished build cannot be relocated, and the note at the top of this file is the measurement. So a
+ * cache root holding no marker is discarded whole before staging rather than built over, and the
+ * marker is written after `eve build` exits 0 and its {@link BUILT_SERVER_ENTRY} is on disk: the file
+ * a boot needs, rather than the directory it sits in. Since {@link cacheBuildComplete} consults the
+ * marker and nothing else, a process killed anywhere in the middle leaves a markerless root that the
+ * next run removes and redoes — which is the property a publishing `rename` would have bought, at a
+ * price the artifact cannot pay.
+ *
+ * A caller might still reach for a temp directory to get atomicity, and `eve build` already provides
+ * it where it counts: it compiles in an invocation-owned directory under `.eve/builds/`, publishes the
+ * completed output from there, and leaves the last successful `.output/` untouched when it fails (eve
+ * 0.38.3, `docs/reference/cli.md`). What eve cannot cover is THIS module's staging copy, which happens
+ * before eve is spawned — and that is what the lock and the marker are for.
+ *
+ * The build runs under a `mkdir`-based lock with stale-age takeover ({@link acquireBuildLock}),
+ * because two processes staging into the same version's cache concurrently would interleave their
+ * trees; eve's own `.eve/locks` starts too late to cover that copy.
  */
 export const resolveAgentAppRoot = (input: {
   readonly packageRoot: string
@@ -255,25 +480,72 @@ export const resolveAgentAppRoot = (input: {
         })
     })
     const cacheRoot = cacheRootFor(version)
-    if (existsSync(join(cacheRoot, ".output"))) return cacheRoot
+    if (cacheBuildComplete(cacheRoot)) return cacheRoot
 
-    yield* Effect.logInfo(`building the consolidator agent into ${cacheRoot} (once per version)`)
-    yield* Effect.tryPromise({
-      try: () => stageAgentTree({ packageRoot, cacheRoot, version }),
-      catch: (cause) =>
-        ConsolidatorUnavailable.make({
-          reason: `could not stage the consolidator agent in ${cacheRoot}: ${String(cause)}`
-        })
-    })
+    return yield* Effect.acquireUseRelease(
+      Effect.tryPromise({
+        try: () => acquireBuildLock(cacheRoot),
+        catch: (cause) =>
+          ConsolidatorUnavailable.make({
+            reason: `could not lock the consolidator agent build: ${String(cause)}`
+          })
+      }),
+      () =>
+        Effect.gen(function* () {
+          // Another process may have completed the build while this one waited on the lock.
+          if (cacheBuildComplete(cacheRoot)) return cacheRoot
+
+          yield* Effect.logInfo(
+            `building the consolidator agent into ${cacheRoot} (once per version)`
+          )
+          yield* Effect.tryPromise({
+            try: async () => {
+              // Reaching here means the root carries no marker, so whatever it holds is an
+              // unfinished build. Discarded whole rather than staged over: a half-copied tree plus a
+              // fresh copy is a tree with no single version's shape.
+              await rm(cacheRoot, { recursive: true, force: true })
+              await stageAgentTree({ packageRoot, cacheRoot, version })
+            },
+            catch: (cause) =>
+              ConsolidatorUnavailable.make({
+                reason: `could not stage the consolidator agent in ${cacheRoot}: ${String(cause)}`
+              })
+          })
 
-    yield* runEveBuild({ eveBin, cwd: cacheRoot })
+          yield* runEveBuild({ eveBin, cwd: cacheRoot })
 
-    if (!existsSync(join(cacheRoot, ".output"))) {
-      return yield* Effect.fail(
-        ConsolidatorUnavailable.make({ reason: `eve build wrote no .output/ in ${cacheRoot}` })
-      )
-    }
-    return cacheRoot
+          if (!existsSync(join(cacheRoot, BUILT_SERVER_ENTRY))) {
+            return yield* Effect.fail(
+              ConsolidatorUnavailable.make({
+                reason: `eve build wrote no ${BUILT_SERVER_ENTRY} in ${cacheRoot}`
+              })
+            )
+          }
+
+          yield* Effect.tryPromise({
+            try: () =>
+              writeFile(buildMarkerPath(cacheRoot), `${new Date().toISOString()}\n`, "utf8"),
+            catch: (cause) =>
+              ConsolidatorUnavailable.make({
+                reason: `could not mark the built agent complete in ${cacheRoot}: ${String(cause)}`
+              })
+          })
+          return cacheRoot
+        }).pipe(
+          // The build's own wreckage, reclaimed while the lock still excludes a concurrent stager: an
+          // unfinished build is ~17 MB nothing will ever consult, and the next run would discard it
+          // anyway. The MARKER is what makes this safe to run on every exit path, success included —
+          // it is written only beside a verified build, so a marked root is a finished one and is
+          // never a candidate, while every path that ends without it left a partial.
+          Effect.ensuring(
+            Effect.promise(async () => {
+              if (cacheBuildComplete(cacheRoot)) return
+              await rm(cacheRoot, { recursive: true, force: true }).catch(() => {})
+            })
+          )
+        ),
+      (lock) => Effect.promise(lock.release)
+    )
   })
 
 /** Exported for the tests that assert the location, which is the part a reader can get wrong. */

package/src/child-stderr.ts

@@ -0,0 +1,36 @@
+/**
+ * The bounded stderr every child spawned from this package keeps, and the slice a failure message
+ * renders from it.
+ *
+ * Two children are spawned here — `eve build` (`agent-build.ts`) and `eve start` (`client.ts`) — and
+ * each reads its child's stderr for exactly one purpose: to carry the last thing the child said into a
+ * typed failure. Both halves of that are load-bearing, and they are only correct together, which is why
+ * they live in one module rather than as a constant per call site:
+ *
+ * - **Retention is a TAIL.** An unbounded accumulator grows for the child's whole life, and the start
+ *   child's handle lives for a full turn — ten minutes — so a chatty server would hold every byte it
+ *   ever logged in this process's heap.
+ * - **The message renders that same TAIL.** A message sliced from the HEAD of a capped buffer shows
+ *   the bytes from just before the cap first bit, which for any child that wrote past the cap is a
+ *   window ending {@link STDERR_TAIL_CHARS} before the fatal line: a cap that works and a diagnostic
+ *   that defeats it. What a dying child wrote last is at the END.
+ */
+
+/**
+ * How much of a child's stderr is retained.
+ *
+ * The stream is read only so a failure can carry the child's last words, and
+ * {@link stderrMessageTail} takes 400 characters off it — so retention past that is context, not data.
+ * 64 KiB keeps the recent context and bounds the hold regardless of how long the child runs.
+ */
+export const STDERR_TAIL_CHARS = 64 * 1024
+
+/** How much of the retained tail rides into a failure message: enough for a stack, not for a log. */
+export const STDERR_MESSAGE_CHARS = 400
+
+/** Append a chunk to a retained tail, keeping the LAST {@link STDERR_TAIL_CHARS} characters. */
+export const appendStderrTail = (retained: string, chunk: string): string =>
+  (retained + chunk).slice(-STDERR_TAIL_CHARS)
+
+/** The END of a retained tail, which is where a dying child's fatal line is. */
+export const stderrMessageTail = (retained: string): string => retained.slice(-STDERR_MESSAGE_CHARS)