memhtml 0.5.1 → 0.7.0

package/dist/memhtml.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { $ as STATE_DB_PATH, A as IndexRecorder, B as IndexGit, C as ModelClient, D as EmbeddingsLive, E as Embeddings, F as makeRetrieval, G as MIGRATIONS_DIR, H as sanitizeFtsQuery, I as reinforce, J as Store, K as STATE_MIGRATIONS_DIR, L as Indexer, M as persistScanned, N as readWatermark, O as EMBED_DIM, P as Retrieval, R as makeIndexer, S as runDiscrimination, T as wrapAsData, U as DatabaseService, V as makeGitPort, W as makeDatabase, X as makeStore, Y as expandRoot, Z as INDEX_DB_PATH, _ as meta, a as parseSidecar, at as makeGit, b as isSleepPhase, c as generateArtifacts, ct as setMeta, d as allPaths, dt as fenceOpeningOf, et as STATE_SIDECAR_PATH, f as danglingEdges, ft as REINFORCE_SIGNALS, g as link, h as hrefFor, i as makeSleep, it as Git, j as makeIndexRecorder, k as EMBED_WATERMARK, l as DETECTION_PREFIX, lt as isValidDatetime, m as applyHeadEdits, n as scanTraceRoot, nt as initRepo, o as renderSidecar, ot as commitSubject, p as publishRows, pt as frameKeyOf, q as STATE_SCHEMA, r as Sleep, rt as readFileOrNull, s as archivedFormOf, st as checkMemory, t as mergeTailExtract, tt as attemptIo, u as accessRows, ut as closesFence, v as unlink, w as ModelClientLive, x as discriminationGate, y as SLEEP_PHASES, z as readIndexState } from "./dist-DgKlozi6.mjs";
-import { $ as TASK_RELS, Dt as isTaskStatus, Et as WRITABLE_MEMORY_TYPES, G as InvalidMemory, Q as MEMORY_RELS, R as hasConsolidatorCredentials, Y as StorageFailure, a as makeConsolidator, et as isEdgeRel, lt as TASKS_SUBDIR, mt as normalizePath, ot as INBOX_DIR, q as ModelUnavailable, tt as relClassFor, wt as TASK_STATUSES } from "./dist-BCsav-EP.mjs";
+import { $ as expandRoot, A as EMBED_DIM, B as reinforce, C as discriminationGate, D as wrapAsData, E as ModelClientLive, F as readWatermark, G as makeGitPort, H as makeIndexer, I as Retrieval, J as makeDatabase, K as sanitizeFtsQuery, L as makeRetrieval, M as IndexRecorder, N as makeIndexRecorder, O as Embeddings, P as persistScanned, Q as Store, R as facetConditions, S as DiscriminationFailed, T as ModelClient, U as readIndexState, V as Indexer, W as IndexGit, X as STATE_MIGRATIONS_DIR, Y as MIGRATIONS_DIR, Z as STATE_SCHEMA, _ as link, _t as REINFORCE_SIGNALS, a as parseSidecar, at as attemptIo, b as SLEEP_PHASES, c as archivedFormOf, ct as Git, d as accessRows, dt as checkMemory, et as makeStore, f as allPaths, g as hrefFor, gt as fenceOpeningOf, h as applyHeadEdits, ht as closesFence, i as makeSleep, it as STATE_SIDECAR_PATH, j as EMBED_WATERMARK, k as EmbeddingsLive, l as generateArtifacts, lt as makeGit, m as publishRows, mt as isValidDatetime, n as scanTraceRoot, o as renderSidecar, ot as initRepo, p as danglingEdges, pt as setMeta, q as DatabaseService, r as Sleep, rt as STATE_DB_PATH, st as readFileOrNull, t as mergeTailExtract, tt as INDEX_DB_PATH, u as DETECTION_PREFIX, ut as commitSubject, v as meta, vt as frameKeyOf, w as runDiscrimination, x as isSleepPhase, y as unlink, z as parseFacetFilters } from "./dist-D1wH0oJ0.mjs";
+import { It as WRITABLE_MEMORY_TYPES, Lt as isTaskStatus, Pt as TASK_STATUSES, W as hasConsolidatorCredentials, ct as TASK_RELS, et as InvalidMemory, ht as INBOX_DIR, i as makeConsolidator, it as StorageFailure, lt as isEdgeRel, nt as ModelUnavailable, st as MEMORY_RELS, ut as relClassFor, vt as TASKS_SUBDIR, wt as normalizePath } from "./dist-DHFdTnlp.mjs";
 import { createRequire } from "node:module";
 import { Config, Context, Effect, Layer, Logger } from "effect";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
@@ -9,6 +9,170 @@ import { dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+//#region apps/cli/src/extraction.ts
+/**
+* GPT-5.6 Luna, the fast high-volume model on the mantle endpoint. A constant rather than config
+* because the schema below is tested against this model's strict-mode behavior. Changing the model
+* is a code change with a test run, not an env var.
+*/
+const EXTRACTION_MODEL_ID = "openai.gpt-5.6-luna";
+/**
+* The strict output schema. `additionalProperties: false` and `required` on every level because
+* the Responses API's `strict: true` demands both, and a lax schema invites the model to answer
+* with prose keys the parser would then be guessing at.
+*/
+const RESPONSE_SCHEMA = {
+	type: "object",
+	properties: { items: {
+		type: "array",
+		items: {
+			type: "object",
+			properties: {
+				index: { type: "integer" },
+				entities: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							type: {
+								type: "string",
+								enum: [...[
+									"person",
+									"org",
+									"service",
+									"place",
+									"work",
+									"concept",
+									"event"
+								]]
+							},
+							name: { type: "string" }
+						},
+						required: ["type", "name"],
+						additionalProperties: false
+					}
+				}
+			},
+			required: ["index", "entities"],
+			additionalProperties: false
+		}
+	} },
+	required: ["items"],
+	additionalProperties: false
+};
+const INSTRUCTIONS = "Extract the named entities each memory mentions. An entity is a specific nameable thing a later search would look up: a person, an organization, a service or system, a place, a titled work, a defined concept, or a named event. Skip generic nouns, dates, and quantities. Use the memory's own spelling for the name. Return one result per input index, with an empty entities array when a memory names nothing.";
+/** The request body for one batch. Exported for the wire test, where the schema is the contract. */
+const requestBodyOf = (modelId, items) => JSON.stringify({
+	model: modelId,
+	instructions: INSTRUCTIONS,
+	input: wrapAsData("memories", JSON.stringify(items.map((item, index) => ({
+		index,
+		title: item.title,
+		text: item.text
+	})))),
+	text: { format: {
+		type: "json_schema",
+		name: "entities",
+		strict: true,
+		schema: RESPONSE_SCHEMA
+	} }
+});
+/**
+* Decode one Responses-API payload into index-aligned `type:name` arrays.
+*
+* Total over unknown input: every malformed shape returns `undefined` and the caller maps that to
+* `ModelUnavailable`. A payload this code cannot read carries no answer, and treating it as
+* "no entities" would record a model failure as a fact about the corpus.
+*/
+const entitiesOf = (payload, expected) => {
+	const text = outputTextOf(payload);
+	if (text === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return;
+	}
+	const items = parsed.items;
+	if (!Array.isArray(items)) return void 0;
+	const results = Array.from({ length: expected }, () => []);
+	for (const item of items) {
+		const index = item.index;
+		const entities = item.entities;
+		if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= expected) continue;
+		if (!Array.isArray(entities)) continue;
+		results[index] = entities.flatMap((entity) => {
+			const type = entity.type;
+			const name = entity.name;
+			if (typeof type !== "string" || typeof name !== "string") return [];
+			const trimmedName = name.trim();
+			return trimmedName === "" ? [] : [`${type}:${trimmedName}`];
+		});
+	}
+	return results;
+};
+/** The assistant message text out of a Responses payload, or `undefined` off-shape. */
+const outputTextOf = (payload) => {
+	const output = payload.output;
+	if (!Array.isArray(output)) return void 0;
+	for (const entry of output) {
+		if (entry.type !== "message") continue;
+		const content = entry.content;
+		if (!Array.isArray(content)) continue;
+		for (const part of content) {
+			const text = part.text;
+			if (part.type === "output_text" && typeof text === "string") return text;
+		}
+	}
+};
+/**
+* Per-call ceiling. Generous against the probed ~1s because a batch of 256 ops is a bigger
+* prompt than the probe's one sentence, and a late abort costs only this batch's entities. The
+* write itself is unaffected.
+*/
+const EXTRACT_TIMEOUT_MS = 6e4;
+/** The extractor over a transport. The transport owns the endpoint; this owns prompt and parse. */
+const makeEntityExtractor = (transport, modelId) => ({ extract: (items) => items.length === 0 ? Effect.succeed([]) : Effect.gen(function* () {
+	const payload = yield* Effect.tryPromise({
+		try: (signal) => {
+			const timeout = AbortSignal.timeout(EXTRACT_TIMEOUT_MS);
+			return transport.post(requestBodyOf(modelId, items), AbortSignal.any([signal, timeout]));
+		},
+		catch: (cause) => ModelUnavailable.make({
+			modelId,
+			reason: cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)
+		})
+	});
+	const entities = entitiesOf(payload, items.length);
+	if (entities === void 0) return yield* Effect.fail(ModelUnavailable.make({
+		modelId,
+		reason: "unreadable extraction payload"
+	}));
+	return entities;
+}) });
+/**
+* The production transport: bearer-token fetch against the mantle endpoint.
+*
+* A non-2xx status is a rejection carrying the status and the body's first line, because mantle
+* reports quota and auth failures as structured JSON the operator needs verbatim. Folding it into
+* a generic message was the mistake the embeddings lane made first.
+*/
+const fetchMantleTransport = (region, token) => ({ post: async (body, signal) => {
+	const response = await fetch(`https://bedrock-mantle.${region}.api.aws/openai/v1/responses`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json"
+		},
+		body,
+		signal
+	});
+	const text = await response.text();
+	if (!response.ok) throw new Error(`mantle ${response.status}: ${text.slice(0, 200)}`);
+	return JSON.parse(text);
+} });
+
+//#endregion
 //#region apps/cli/src/serve.ts
 /** An explicit path to the server, for a deployment that does not keep the two apps side by side. */
 const MCP_BIN_VAR = "MEMHTML_MCP_BIN";
@@ -102,7 +266,14 @@ const CONFIG_VARS = [
 	},
 	{
 		name: "MEMHTML_EXTRACT_ENTITIES",
-		description: "`on` adds one GPT-5.6 Luna call per write batch that extracts `memhtml-entity` metas the ops did not declare. Opt-in, unlike MEMHTML_EMBED, because it changes what a write STORES: extracted entities land in the files as if authored, and the write itself never waits on or fails with the model. A failed extraction is a logged warning and an unextracted batch.",
+		/**
+		* The model id is interpolated from `extraction.ts`, never spelled here. That constant is the
+		* one the transport calls and the one the strict output schema beside it is tested against, so a
+		* second spelling in this row is a manifest that can name a model the code does not call. The
+		* lane is also not `@memhtml/llm`'s: the extractor speaks the Bedrock mantle Responses API, which
+		* is why this id is absent from `ModelKey`.
+		*/
+		description: `\`on\` adds one \`${EXTRACTION_MODEL_ID}\` call per write batch that extracts \`memhtml-entity\` metas the ops did not declare. Opt-in, unlike MEMHTML_EMBED, because it changes what a write STORES: extracted entities land in the files as if authored, and the write itself never waits on or fails with the model. A failed extraction is a logged warning and an unextracted batch.`,
 		fallback: "off"
 	},
 	{
@@ -147,6 +318,7 @@ const ERROR_CODES = [
 	"ERR_UNKNOWN_COMMAND",
 	"ERR_MISSING_ARGUMENT",
 	"ERR_INVALID_FLAG",
+	"ERR_UNEXPECTED_ARGUMENT",
 	"ERR_PATH_NOT_FOUND",
 	"ERR_INVALID_MEMORY",
 	"ERR_DUPLICATE_CONTENT",
@@ -204,170 +376,6 @@ const stripNulls = (value) => {
 };
 const render = (payload, dense) => dense ? JSON.stringify(stripNulls(payload)) : JSON.stringify(payload, null, 2);
 
-//#endregion
-//#region apps/cli/src/extraction.ts
-/**
-* GPT-5.6 Luna, the fast high-volume model on the mantle endpoint. A constant rather than config
-* because the schema below is tested against this model's strict-mode behavior. Changing the model
-* is a code change with a test run, not an env var.
-*/
-const EXTRACTION_MODEL_ID = "openai.gpt-5.6-luna";
-/**
-* The strict output schema. `additionalProperties: false` and `required` on every level because
-* the Responses API's `strict: true` demands both, and a lax schema invites the model to answer
-* with prose keys the parser would then be guessing at.
-*/
-const RESPONSE_SCHEMA = {
-	type: "object",
-	properties: { items: {
-		type: "array",
-		items: {
-			type: "object",
-			properties: {
-				index: { type: "integer" },
-				entities: {
-					type: "array",
-					items: {
-						type: "object",
-						properties: {
-							type: {
-								type: "string",
-								enum: [...[
-									"person",
-									"org",
-									"service",
-									"place",
-									"work",
-									"concept",
-									"event"
-								]]
-							},
-							name: { type: "string" }
-						},
-						required: ["type", "name"],
-						additionalProperties: false
-					}
-				}
-			},
-			required: ["index", "entities"],
-			additionalProperties: false
-		}
-	} },
-	required: ["items"],
-	additionalProperties: false
-};
-const INSTRUCTIONS = "Extract the named entities each memory mentions. An entity is a specific nameable thing a later search would look up: a person, an organization, a service or system, a place, a titled work, a defined concept, or a named event. Skip generic nouns, dates, and quantities. Use the memory's own spelling for the name. Return one result per input index, with an empty entities array when a memory names nothing.";
-/** The request body for one batch. Exported for the wire test, where the schema is the contract. */
-const requestBodyOf = (modelId, items) => JSON.stringify({
-	model: modelId,
-	instructions: INSTRUCTIONS,
-	input: wrapAsData("memories", JSON.stringify(items.map((item, index) => ({
-		index,
-		title: item.title,
-		text: item.text
-	})))),
-	text: { format: {
-		type: "json_schema",
-		name: "entities",
-		strict: true,
-		schema: RESPONSE_SCHEMA
-	} }
-});
-/**
-* Decode one Responses-API payload into index-aligned `type:name` arrays.
-*
-* Total over unknown input: every malformed shape returns `undefined` and the caller maps that to
-* `ModelUnavailable`. A payload this code cannot read carries no answer, and treating it as
-* "no entities" would record a model failure as a fact about the corpus.
-*/
-const entitiesOf = (payload, expected) => {
-	const text = outputTextOf(payload);
-	if (text === void 0) return void 0;
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch {
-		return;
-	}
-	const items = parsed.items;
-	if (!Array.isArray(items)) return void 0;
-	const results = Array.from({ length: expected }, () => []);
-	for (const item of items) {
-		const index = item.index;
-		const entities = item.entities;
-		if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= expected) continue;
-		if (!Array.isArray(entities)) continue;
-		results[index] = entities.flatMap((entity) => {
-			const type = entity.type;
-			const name = entity.name;
-			if (typeof type !== "string" || typeof name !== "string") return [];
-			const trimmedName = name.trim();
-			return trimmedName === "" ? [] : [`${type}:${trimmedName}`];
-		});
-	}
-	return results;
-};
-/** The assistant message text out of a Responses payload, or `undefined` off-shape. */
-const outputTextOf = (payload) => {
-	const output = payload.output;
-	if (!Array.isArray(output)) return void 0;
-	for (const entry of output) {
-		if (entry.type !== "message") continue;
-		const content = entry.content;
-		if (!Array.isArray(content)) continue;
-		for (const part of content) {
-			const text = part.text;
-			if (part.type === "output_text" && typeof text === "string") return text;
-		}
-	}
-};
-/**
-* Per-call ceiling. Generous against the probed ~1s because a batch of 256 ops is a bigger
-* prompt than the probe's one sentence, and a late abort costs only this batch's entities. The
-* write itself is unaffected.
-*/
-const EXTRACT_TIMEOUT_MS = 6e4;
-/** The extractor over a transport. The transport owns the endpoint; this owns prompt and parse. */
-const makeEntityExtractor = (transport, modelId) => ({ extract: (items) => items.length === 0 ? Effect.succeed([]) : Effect.gen(function* () {
-	const payload = yield* Effect.tryPromise({
-		try: (signal) => {
-			const timeout = AbortSignal.timeout(EXTRACT_TIMEOUT_MS);
-			return transport.post(requestBodyOf(modelId, items), AbortSignal.any([signal, timeout]));
-		},
-		catch: (cause) => ModelUnavailable.make({
-			modelId,
-			reason: cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)
-		})
-	});
-	const entities = entitiesOf(payload, items.length);
-	if (entities === void 0) return yield* Effect.fail(ModelUnavailable.make({
-		modelId,
-		reason: "unreadable extraction payload"
-	}));
-	return entities;
-}) });
-/**
-* The production transport: bearer-token fetch against the mantle endpoint.
-*
-* A non-2xx status is a rejection carrying the status and the body's first line, because mantle
-* reports quota and auth failures as structured JSON the operator needs verbatim. Folding it into
-* a generic message was the mistake the embeddings lane made first.
-*/
-const fetchMantleTransport = (region, token) => ({ post: async (body, signal) => {
-	const response = await fetch(`https://bedrock-mantle.${region}.api.aws/openai/v1/responses`, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${token}`,
-			"Content-Type": "application/json"
-		},
-		body,
-		signal
-	});
-	const text = await response.text();
-	if (!response.ok) throw new Error(`mantle ${response.status}: ${text.slice(0, 200)}`);
-	return JSON.parse(text);
-} });
-
 //#endregion
 //#region apps/cli/src/api-layer.ts
 const Roots = Context.Service("memhtml/Roots");
@@ -519,22 +527,21 @@ const ConsolidatorPortService = Context.Service("memhtml/ConsolidatorPort");
 *
 * The check cannot be skipped in favor of the client's own, because the provider is lazy.
 * `createAmazonBedrock` and `provider(modelId)` both succeed with zero credentials and nothing fails
-* until the first request (verified in T-EVE-1's probe, recorded at
-* `apps/consolidator/src/contract.ts:301-319`).
+* until the first request (the contract suite in `apps/consolidator/src/contract.ts` pins this).
 *
 * **`env` is a parameter, and it has to be.** `Config` reads its values through a `ConfigProvider`,
 * which a test substitutes, while `hasConsolidatorCredentials` reads `process.env` directly, and
-* effect's default provider snapshots `process.env` at module load (probed 2026-08-08: mutating
-* `process.env.MEMHTML_LLM` after importing `effect` changes nothing `Config.string` returns). A test
+* effect's default provider snapshots `process.env` at module load, so mutating
+* `process.env.MEMHTML_LLM` after importing `effect` changes nothing `Config.string` returns. A test
 * that set both by mutation would read a stale snapshot for one gate and a live object for the other,
 * and the two gates would disagree about which environment they are in. Threading the credential
 * environment through as an argument makes both injectable from one call. See
 * `apps/cli/tests/consolidator-wiring.test.ts`, where that disagreement produced a false defect
 * before this parameter existed.
 *
-* **It now requires `RootsShape`, for `traceRoot`.** That is how transcripts reach the agent. The
+* **It requires `RootsShape`, for `traceRoot`.** That is how transcripts reach the agent. The
 * consolidator mounts the trace root read-only rather than sending transcripts as a model message
-* (`apps/consolidator/src/client.ts`, `manifestFor`, records what the superseded path actually did).
+* (`apps/consolidator/src/client.ts`, `manifestFor`).
 * The root is `MEMHTML_TRACE_ROOT` and this file is where config becomes services, so it is read from the
 * same `Roots` service `memhtml trace index` scans with. One resolution of one variable is what
 * keeps the mounted tree and the indexed `traces` rows describing the same directory. A second
@@ -642,6 +649,7 @@ const codeFor = (error) => {
 		case "DuplicateContent": return "ERR_DUPLICATE_CONTENT";
 		case "ModelUnavailable": return "ERR_MODEL_UNAVAILABLE";
 		case "EmbedModelMismatch": return "ERR_EMBED_MODEL_MISMATCH";
+		case "IndexStale": return "ERR_INDEX_STALE";
 		case "DiscriminationFailed": return "ERR_DISCRIMINATION_FAILED";
 		default: return "ERR_UNKNOWN";
 	}
@@ -667,6 +675,7 @@ const messageFor = (error) => {
 		case "DuplicateContent": return `this content already lives at ${text(error.existingPath) ?? "another path"}`;
 		case "ModelUnavailable": return `bedrock refused ${text(error.modelId) ?? "the model"}: ${text(error.reason) ?? "no reason given"}`;
 		case "EmbedModelMismatch": return `the index was built in vector space ${text(error.stored) ?? "?"}, configured is ${text(error.configured) ?? "?"}`;
+		case "IndexStale": return `the index is stale: ${text(error.reason) ?? "it does not describe the current commit"}`;
 		case "LlmContractViolation": return `the model broke its structured-output contract: ${text(error.reason) ?? "no reason given"}`;
 		case "DiscriminationFailed": return text(error.reason) ?? "the discrimination gate refused";
 		default: return `unexpected failure: ${error._tag}`;
@@ -676,12 +685,14 @@ const messageFor = (error) => {
 * What to do about a failure, as commands the caller can run.
 *
 * A suggestion is part of the contract. An agent that receives `ERR_INDEX_STALE` and a
-* `memhtml index update` suggestion can recover in one step without a round trip to a human. Absent
-* suggestions are an empty array rather than a null, so a parser never branches on presence.
+* `memhtml index rebuild` suggestion can recover in one step without a round trip to a human, which
+* also means a suggestion has to be a call that MOVES the failure: naming the command that raised the
+* tag would loop. Absent suggestions are an empty array rather than a null, so a parser never
+* branches on presence.
 *
 * A record rather than a `switch`, which is what closes the drift class. Every `memhtml …` string
-* below names a command from the table in `commands.ts`, and a rename there used to leave a stale
-* suggestion here that nothing failed on. A record's keys and arms are both walkable, so the suite
+* below names a command from the table in `commands.ts`, and a rename there would otherwise leave a
+* stale suggestion here that nothing fails on. A record's keys and arms are both walkable, so the suite
 * can enumerate every tag, run every suggestion through the real `parseArgv`, and fail on a name the
 * table does not hold. A `switch` cannot expose any of that to a test.
 *
@@ -690,11 +701,29 @@ const messageFor = (error) => {
 * `AUTHORABLE_RELS` undefined in `commands.ts`'s module body under an operations-first import order.
 */
 const SUGGESTIONS = {
-	PathNotFound: () => ["memhtml search <what you were looking for>", "memhtml list"],
-	WriteConflict: (error) => [`memhtml read ${text(error.path) ?? "<path>"}`, "re-apply the change to current content"],
+	PathNotFound: () => [
+		"memhtml resolve <the path you cited> — a correction or an eviction may have moved it",
+		"memhtml search <what you were looking for>",
+		"memhtml list"
+	],
+	/**
+	* Two branches produce this tag and they recover differently, so both are offered.
+	*
+	* An occupied EXPLICIT `--path` is refused rather than overwritten — nothing in this corpus is
+	* deleted — and the recovery is `memhtml correct <path>`, which writes the superseding memory and
+	* archives what it replaces in one commit. A merge conflict on a sleep branch carries two blob
+	* shas instead, and there the recovery is to read the current content and re-apply. The read is
+	* first because it is the step both branches start with.
+	*/
+	WriteConflict: (error) => [
+		`memhtml read ${text(error.path) ?? "<path>"}`,
+		`memhtml correct ${text(error.path) ?? "<path>"} --title <title> --claim <sentence>`,
+		"re-apply the change to current content"
+	],
 	DirtyTree: () => ["git -C $MEMHTML_ROOT status", "commit or stash the changes, then retry"],
 	DuplicateContent: (error) => [`memhtml read ${text(error.existingPath) ?? "<path>"}`],
 	EmbedModelMismatch: () => ["memhtml index rebuild --embed"],
+	IndexStale: () => ["memhtml index rebuild"],
 	ModelUnavailable: () => ["retry: search still works on the lexical floor", "memhtml status"],
 	InvalidMemory: () => ["memhtml manifest"],
 	DiscriminationFailed: () => [
@@ -796,20 +825,20 @@ const recordLink = (path, linkKind, provenance, at) => Effect.gen(function* () {
 /**
 * Bring the index up to the commit a write just made.
 *
-* `indexer.update()` rather than `indexPaths([…])`, and the difference changes behavior twice:
+* The whole COMMIT, never a list of paths the caller happens to know about, and two properties of the
+* index rest on that:
 *
-* 1. **`indexPaths` cannot express a rename.** Every correction and every archive is a `git mv`, and
-*    an index that handled one as "index the destination" leaves the source row live. The archived
-*    memory stays in `memhtml list`, `files` gains a row the tree does not have, and the chunk rows the
-*    move exists to preserve are duplicated under two paths. `update()` reads `diff --name-status -M`,
-*    sees the `R`, and re-points the row, which keeps the embedding and drops nothing.
-* 2. **`indexPaths` never records the watermark.** `index_state.head_sha` is what makes
-*    "the index describes the current commit" answerable at all, so a write path that skipped it
-*    would leave `memhtml status` reporting `index_fresh: false` forever and `index update` re-deriving
-*    from a stale base.
+* 1. **A rename is only expressible as a diff.** Every correction and every archive is a `git mv`.
+*    `update()` reads `diff --name-status -M`, sees the `R`, and re-points the row, which keeps the
+*    embedding. Indexing the destination alone leaves the source row live: the archived memory stays
+*    in `memhtml list`, `files` carries a row the tree does not have, and the chunk rows the move
+*    exists to preserve end up duplicated under two paths.
+* 2. **The watermark is what makes freshness answerable.** `update()` records
+*    `index_state.head_sha`, and without it `memhtml status` reports `index_fresh: false` forever
+*    while `index update` re-derives from a stale base.
 *
 * The cost is one `git diff` over one commit, which is what the watermark exists to bound. On the
-* very first write the watermark is absent and `update()` falls through to a full rebuild. That is
+* very first write there is no watermark row and `update()` falls through to a full rebuild. That is
 * correct, and cheap on a corpus that has one file in it.
 */
 const reindex = () => Effect.gen(function* () {
@@ -820,8 +849,8 @@ const reindex = () => Effect.gen(function* () {
 *
 * Shared by {@link writeMemory} and {@link batchWrite}, and the sharing matters. A batch that
 * re-derived this would be a second decode of the same vocabulary, and the two would agree today
-* and drift the first time a field is added. This is `symspec`'s lesson stated as code: the batch
-* folds the singular's own decode rather than a parallel one.
+* and drift the first time a field is added. The batch folds the singular's own decode rather
+* than a parallel one.
 *
 * The two task metas are decoded here, before any file is rendered, and only for a task.
 * `@memhtml/html`'s parser refuses `memhtml-task-status` on a non-task and refuses a `memhtml-due` that is not
@@ -842,6 +871,7 @@ const toWriteInput = (params, at) => Effect.gen(function* () {
 			body: params.body,
 			articleHtml: params.articleHtml,
 			path: params.path,
+			strictPath: params.strictPath,
 			workspace: params.workspace,
 			tags: params.tags,
 			entities: params.entities,
@@ -1431,13 +1461,116 @@ const reinforceMemories = (paths, signal) => Effect.gen(function* () {
 	};
 });
 /**
+* The ceiling on nodes per neighborhood, and the default when a caller names none.
+*
+* A caller-supplied `limit` is clamped into `1..NEIGHBORS_LIMIT`, which is the shape both sibling
+* reads have (`memory_list` `Math.min(500, …)`, `trace_search` `Math.min(200, …)`). A clamp with no
+* flag behind it is a ceiling a caller can neither ask for nor lower.
+*/
+const NEIGHBORS_LIMIT = 200;
+/**
+* Edge rows the statement may RETURN before it stops.
+*
+* **This bounds the answer, not the join.** Measured 2026-08-25 on node 24.19.0 against the shipped
+* schema: `EXPLAIN QUERY PLAN` on {@link neighborsQuery}'s depth-2 statement yields `MERGE
+* (UNION ALL)` with `USE TEMP B-TREE FOR ORDER BY` on every arm, so SQLite enumerates the union and
+* sorts the whole row set in a temp b-tree BEFORE the `LIMIT` takes its prefix. A hub of degree
+* 150/300/450 generates 22.5k/90k/202k rows either way, and the limited statement runs in
+* 47/92/155 ms against 66/253/591 ms unlimited — so the cap buys real time and memory downstream of
+* the sort while the join's work and the temp b-tree still grow with the center's degree squared.
+*
+* What the cap does bound: the rows that cross into JS, the fold below, and the size of one answer.
+* A neighborhood that reaches it is truncated rather than exhaustive, and `scanSaturated` says so
+* instead of leaving the caller to infer it — raising a caller's `limit` cannot recover an edge the
+* walk never returned.
+*
+* Bounding each arm before the union WOULD bound the join, and is not done: an arm-level `LIMIT`
+* takes an arbitrary prefix of one direction's edges, so the hop-1 nodes that survive decide which
+* hop-2 nodes exist at all, and the answer would change with the planner's row order rather than
+* only shrink.
+*/
+const NEIGHBORS_SCAN_LIMIT = 1e4;
+/**
+* The neighborhood walk as one statement plus its bind list.
+*
+* Exported so a cost assertion can `EXPLAIN QUERY PLAN` the string this function actually issues.
+* A plan asserted against a copy pasted into a test explains the copy, and the two drift the first
+* time an arm moves.
+*
+* Hop 1 is the center's own edges, either direction. Hop 2 walks one further from each hop-1 node and
+* excludes the center, so a two-cycle does not report the center as its own neighbor at distance 2.
+* Each arm carries the edge's own endpoints (`a`, `b`) so an edge can be counted as an edge, not
+* inferred from a node count.
+*
+* The join onto `files` is an inner join, so an edge pointing at a path the tree does not hold
+* contributes nothing. A dangling href is `memhtml doctor`'s finding rather than a titleless node.
+*
+* The rel list binds once per occurrence of the filter, in textual order: hop 1 uses it twice, hop 2
+* uses it four more times. Getting this count wrong is a bind mismatch rather than a wrong answer, so
+* it fails loudly.
+*/
+const neighborsQuery = (input) => {
+	const { center, depth, rels } = input;
+	const relFilter = rels.length > 0 ? ` AND e.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	const relFilter2 = rels.length > 0 ? ` AND e2.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	const hopOne = `
+      SELECT e.dst_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop,
+             e.src_path AS a, e.dst_path AS b
+      FROM edges e
+      WHERE e.src_path = ?1 AND e.edge_class = 'memory'${relFilter}
+      UNION ALL
+      SELECT e.src_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop,
+             e.src_path AS a, e.dst_path AS b
+      FROM edges e
+      WHERE e.dst_path = ?1 AND e.edge_class = 'memory'${relFilter}`;
+	const hopTwo = `
+      SELECT e2.dst_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop,
+             e2.src_path AS a, e2.dst_path AS b
+      FROM edges e
+      JOIN edges e2 ON e2.src_path = e.dst_path
+      WHERE e.src_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
+        AND e2.dst_path <> ?1${relFilter}${relFilter2}
+      UNION ALL
+      SELECT e2.src_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop,
+             e2.src_path AS a, e2.dst_path AS b
+      FROM edges e
+      JOIN edges e2 ON e2.dst_path = e.src_path
+      WHERE e.dst_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
+        AND e2.src_path <> ?1${relFilter}${relFilter2}`;
+	return {
+		sql: `SELECT w.path AS path, f.title AS title, w.rel AS rel, w.derived AS derived,
+              w.hop AS hop, w.a AS a, w.b AS b
+       FROM (${depth === 1 ? hopOne : `${hopOne}\n      UNION ALL${hopTwo}`}) w
+       JOIN files f ON f.path = w.path
+       ORDER BY w.hop ASC, w.path ASC
+       LIMIT ${NEIGHBORS_SCAN_LIMIT}`,
+		params: [center, ...depth === 1 ? [...rels, ...rels] : [
+			...rels,
+			...rels,
+			...rels,
+			...rels,
+			...rels,
+			...rels
+		]]
+	};
+};
+/**
 * The memory graph around one path, to a fixed depth of at most two hops.
 *
 * **Two fixed-depth joins in a `UNION ALL`, deliberately not a recursive CTE.** The depth is
 * bounded at 2 by the tool's contract, so recursion buys nothing and costs the one thing a graph
 * query must not have here: an unbounded worst case on a corpus whose `relates_to` edges are
-* mined by the sleep cycle and can be dense. A fixed join is also index-covered by `edges_src`
-* and `edges_dst`, which a recursive walk is not.
+* mined by the sleep cycle and can be dense.
+*
+* **Every arm is index-probed, in both directions, through `edges_src` and `edges_dst`.** Measured
+* 2026-08-26 on node 24.19.0 with no `ANALYZE`, and locked by the plan assertion in
+* `apps/cli/tests/e2e.test.ts`: each arm is a `SEARCH` binding two columns,
+* `(src_path=? AND edge_class=?)` or `(dst_path=? AND edge_class=?)`. Neither index carries a
+* predicate (`0011_edge_indexes.sql`), which is what makes them reachable from here at all — this walk
+* selects `e.derived` and filters only on `edge_class`, so a `WHERE derived = 0` index could not be a
+* candidate, and the reverse arms would fall back to a full scan of `edges` per arm. The row set is
+* still degree², which is what `NEIGHBORS_SCAN_LIMIT` bounds; what the indexes bound is the work spent
+* finding it.
 *
 * **Both directions, and `derived = 0 ∪ derived = 1`.** An edge is an assertion about a pair, and
 * which file happens to hold the `<link>` is authorship rather than direction of meaning. A
@@ -1446,66 +1579,228 @@ const reinforceMemories = (paths, signal) => Effect.gen(function* () {
 * is what they are for. `derived` is still reported per node so a caller can tell a
 * sleep-mined suspicion from an authored assertion.
 *
-* `edge_class = 'memory'` on every join. A person edge entering here would put
-* `resources/people/*` into a memory neighborhood, and the class column exists to make that
-* structurally impossible.
+* `edge_class = 'memory'` on every join. A person edge entering here would put
+* `resources/people/*` into a memory neighborhood, and the class column exists to make that
+* structurally impossible.
+*/
+const neighborsOf = (params) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const center = normalizePath(params.path);
+	const depth = Math.min(2, Math.max(1, Math.trunc(params.depth ?? 1)));
+	const limit = Math.min(200, Math.max(1, Math.trunc(params.limit ?? 200)));
+	const rels = (params.rels ?? []).filter((rel) => isEdgeRel(rel) && relClassFor(rel) === "memory");
+	/**
+	* Edge rows, hop-1 first, folded per path below rather than `GROUP BY` in SQL. A `GROUP BY`
+	* with `min(hop)` and `min(rel)` aggregates the two columns independently, so a node reachable
+	* as `supersedes` at hop 1 and `contradicts` at hop 2 would report `(hop 1, contradicts)`, a
+	* pairing no edge holds. The fold keeps the rel of an edge AT the minimal hop.
+	*/
+	const statement = neighborsQuery({
+		center,
+		depth,
+		rels
+	});
+	const rows = yield* db.all(statement.sql, statement.params);
+	/**
+	* One node per path at its minimal hop: a node reachable both directly and via a detour is a
+	* 1-hop neighbor, and reporting it twice would let one memory occupy two slots in a bounded
+	* answer. The rows arrive hop-first, so a path's first row IS an edge at its minimal hop and
+	* its rel is kept verbatim. `derived` is the max over every edge reaching the node, so one
+	* sleep-mined route marks the node as carrying a mined suspicion even when an authored edge
+	* also reaches it. `edges` counts distinct edges the walk enumerated, which is what the MCP
+	* schema's `edges` field claims to be.
+	*
+	* A path the clamp turns away is still counted, in `nodesDropped`, and its edges still count
+	* toward `edges`: the two numbers live in different coordinate spaces on purpose, and an `edges`
+	* total that quietly excluded a dropped path's edges would agree with `nodes` while describing
+	* a walk that never happened.
+	*/
+	const byPath = /* @__PURE__ */ new Map();
+	const edgeKeys = /* @__PURE__ */ new Set();
+	const dropped = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		edgeKeys.add(JSON.stringify([
+			row.a,
+			row.rel,
+			row.b
+		]));
+		const existing = byPath.get(row.path);
+		if (existing === void 0) {
+			if (byPath.size < limit) byPath.set(row.path, {
+				title: row.title,
+				hop: row.hop,
+				rel: row.rel,
+				derived: row.derived === 1
+			});
+			else dropped.add(row.path);
+		} else if (row.derived === 1) byPath.set(row.path, {
+			...existing,
+			derived: true
+		});
+	}
+	return {
+		center,
+		depth,
+		/** The node ceiling this answer was built under, after clamping the caller's ask. */
+		limit,
+		nodes: [...byPath.entries()].map(([path, node]) => ({
+			path,
+			title: node.title,
+			hop: node.hop,
+			rel: node.rel,
+			derived: node.derived
+		})),
+		edges: edgeKeys.size,
+		/**
+		* Distinct paths the walk reached and `limit` turned away. `0` means `nodes` holds every path
+		* the walk found, so a caller can tell a saturated neighborhood from a complete one. Raising
+		* `limit` toward {@link NEIGHBORS_LIMIT} returns them.
+		*/
+		nodesDropped: dropped.size,
+		/**
+		* True when the walk returned {@link NEIGHBORS_SCAN_LIMIT} rows, so edges past the cap were
+		* never enumerated and no `limit` recovers them. Distinct from `nodesDropped`, which a bigger
+		* `limit` fixes.
+		*/
+		scanSaturated: rows.length >= NEIGHBORS_SCAN_LIMIT
+	};
+});
+/**
+* Steps the forward walk takes before it stops and says which bound stopped it.
+*
+* A chain this long is a corpus that has corrected one fact sixteen times, which the walk answers
+* with `hop_limit` rather than by paying an unbounded number of statements for a read a caller
+* expects to be cheap. It is not the cycle guard: {@link resolveMemory} carries a visited set, so a
+* loop is reported as a loop at the hop that closes it, however short.
 */
-const neighborsOf = (params) => Effect.gen(function* () {
+const RESOLVE_MAX_HOPS = 16;
+/**
+* The three statements the walk issues, as literals a plan assertion can EXPLAIN.
+*
+* Exported for {@link neighborsQuery}'s reason: a cost contract can only be asserted at the planner,
+* and a test that EXPLAINed a pasted copy would explain the copy. Each one binds exactly one
+* parameter, so a test can run them as written.
+*
+* `successor` names `edge_class` even though `rel = 'supersedes'` implies it under `edges`' CHECK
+* constraints. That is a planner constraint, not a filter: measured 2026-08-26 on node 24's
+* `node:sqlite` with no `ANALYZE`, `dst_path = ? AND rel = ? AND derived = 0` alone plans as `SEARCH
+* edges USING INDEX edges_derived (derived=? AND rel=?)` — every authored correction in the corpus,
+* per hop — while naming the class binds two columns of `edges_dst` and the same statement probes.
+* The rel and `derived = 0` are still the CORRECTNESS half: `derived = 0` is the same authored-only
+* rule `SearchHit.supersededBy` reads, so `search` and this walk cannot disagree about who superseded
+* what, and a sleep-mined suspicion can never redirect a citation.
+*
+* `archived` is the archive mapping read backwards, served by `files_origin`
+* (`0012_origin_path.sql`). `ORDER BY archived_at DESC` decides the case a UNIQUE index would have
+* had to refuse: one path evicted, rewritten, and evicted again carries two archive rows, and the
+* NEWEST is the occupant a citation of that path most recently named. A row with no `memhtml-archived`
+* stamp sorts last, since SQLite puts NULLs last under DESC.
+*/
+const resolveQueries = {
+	successor: `SELECT e.src_path AS path FROM edges e
+     WHERE e.dst_path = ? AND e.edge_class = 'memory' AND e.rel = 'supersedes' AND e.derived = 0
+     ORDER BY e.created_at DESC, e.src_path ASC LIMIT 1`,
+	archived: `SELECT f.path AS path FROM files f
+     WHERE f.origin_path = ? ORDER BY f.archived_at DESC, f.path DESC LIMIT 1`,
+	file: "SELECT f.archived AS archived, f.title AS title FROM files f WHERE f.path = ?"
+};
+/**
+* The live path a possibly-moved path names now, by walking `supersedes` forward.
+*
+* **A path IS the id of a memory** (`packages/contracts/src/types.ts`, `MemoryPath`), and it is
+* derived from the title through `slugify`, so a re-consolidation that rewords a title lands the
+* corrected fact at a DIFFERENT path while `correctMemory` `git mv`s the original into
+* `archive/<YYYY>/`. An external receipt holding the old path therefore dead-ends at a path the tree
+* no longer holds — through no fault of the receipt. This read is how such a receipt is repaired
+* without a second identifier: the corpus already records both mechanisms that move a memory, and
+* nothing here is minted.
+*
+* **Two mechanisms, and a path absent from `files` is looked up by the archive mapping ALONE.** A
+* correction stamps its `supersedes` link toward the target's ARCHIVE path
+* (`packages/store/src/store.ts`, `correctMemory`), so the pre-archive path has no inbound edge at
+* all and only `origin_path` knows where its bytes went. An inbound `supersedes` edge over a path the
+* tree does not hold is a DANGLING edge — `memhtml doctor`'s finding — and following one would
+* resolve a citation through an assertion about a file nothing can read. Conversely a path that IS in
+* `files` is never redirected by the archive mapping, even when an older eviction of the same path
+* left a row behind: the live file at that path is the answer, and the redirect would replace it with
+* a historical one.
+*
+* **Every node in the chain is named by the path that holds it NOW.** A `supersedes` link is an
+* element inside a file, so archiving that file carries the link with it: after a second correction the
+* edge points from the archived middle memory, not from the path the middle was live at. A three-step
+* chain over two corrections therefore reads `cited → archive(cited) → archive(middle) → live`, and the
+* middle's own live-at-the-time path appears nowhere in it. The tree is the system of record, and this
+* walk reports where each memory is rather than where it was.
+*
+* **`hops: 0` with `stopReason: "live"` does not mean the bytes are unchanged.** A correction whose
+* title is unchanged lands at the SAME path, so the path is live and its content is a different fact.
+* That grain is what the pinned citation URI is for; this read answers where to look, not what was
+* there.
+*
+* Statement count is `1..2` per hop and the walk is bounded twice — by a visited set and by
+* {@link RESOLVE_MAX_HOPS} — so a corpus defect costs a bounded read and is reported rather than
+* hung. A recursive CTE would do it in one statement and could not report WHICH mechanism took each
+* hop, which is the half a receipt is audited on.
+*/
+const resolveMemory = (path) => Effect.gen(function* () {
 	const db = yield* DatabaseService;
-	const center = normalizePath(params.path);
-	const depth = Math.min(2, Math.max(1, Math.trunc(params.depth ?? 1)));
-	const rels = (params.rels ?? []).filter((rel) => isEdgeRel(rel) && relClassFor(rel) === "memory");
-	const relFilter = rels.length > 0 ? ` AND e.rel IN (${rels.map(() => "?").join(", ")})` : "";
-	const relFilter2 = rels.length > 0 ? ` AND e2.rel IN (${rels.map(() => "?").join(", ")})` : "";
-	/**
-	* Hop 1 is the center's own edges, either direction. Hop 2 walks one further from each hop-1
-	* node and excludes the center, so a two-cycle does not report the center as its own neighbor
-	* at distance 2.
-	*/
-	const hopOne = `
-      SELECT e.dst_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop
-      FROM edges e
-      WHERE e.src_path = ?1 AND e.edge_class = 'memory'${relFilter}
-      UNION ALL
-      SELECT e.src_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop
-      FROM edges e
-      WHERE e.dst_path = ?1 AND e.edge_class = 'memory'${relFilter}`;
-	const hopTwo = `
-      SELECT e2.dst_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop
-      FROM edges e
-      JOIN edges e2 ON e2.src_path = e.dst_path
-      WHERE e.src_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
-        AND e2.dst_path <> ?1${relFilter}${relFilter2}
-      UNION ALL
-      SELECT e2.src_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop
-      FROM edges e
-      JOIN edges e2 ON e2.dst_path = e.src_path
-      WHERE e.dst_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
-        AND e2.src_path <> ?1${relFilter}${relFilter2}`;
-	const walk = depth === 1 ? hopOne : `${hopOne}\n      UNION ALL${hopTwo}`;
-	const nodes = (yield* db.all(`SELECT w.path AS path, f.title AS title, min(w.hop) AS hop,
-              min(w.rel) AS rel, max(w.derived) AS derived
-       FROM (${walk}) w
-       JOIN files f ON f.path = w.path
-       GROUP BY w.path
-       ORDER BY hop ASC, w.path ASC`, [center, ...depth === 1 ? [...rels, ...rels] : [
-		...rels,
-		...rels,
-		...rels,
-		...rels,
-		...rels,
-		...rels
-	]])).map((row) => ({
-		path: row.path,
-		title: row.title,
-		hop: row.hop,
-		rel: row.rel
-	}));
+	const requested = normalizePath(path);
+	const state = yield* readIndexState(db);
+	const steps = [];
+	const visited = /* @__PURE__ */ new Set([requested]);
+	/** Titles of every indexed path the walk touched, so the answer carries one without a re-read. */
+	const titles = /* @__PURE__ */ new Map();
+	let at = requested;
+	let stopReason = "unindexed";
+	for (;;) {
+		const row = yield* db.get(resolveQueries.file, [at]);
+		if (row !== void 0) titles.set(at, row.title);
+		const hop = row === void 0 ? {
+			found: yield* db.get(resolveQueries.archived, [at]),
+			via: "archive_move"
+		} : {
+			found: yield* db.get(resolveQueries.successor, [at]),
+			via: "supersedes"
+		};
+		if (hop.found === void 0) {
+			if (row === void 0) stopReason = "unindexed";
+			else stopReason = row.archived === 1 ? "archived" : "live";
+			break;
+		}
+		/**
+		* The bound is checked BEFORE the step is taken, so `steps.length` is exactly
+		* {@link RESOLVE_MAX_HOPS} when it fires and `path` is a real path the walk stood on. Taking the
+		* step first would report a hop past a bound the answer claims to respect.
+		*/
+		if (steps.length >= 16) {
+			stopReason = "hop_limit";
+			break;
+		}
+		steps.push({
+			from: at,
+			to: hop.found.path,
+			via: hop.via
+		});
+		at = hop.found.path;
+		/**
+		* The repeat IS recorded as a step before the walk stops, so `steps` shows the loop closing and
+		* a reader can name both ends of it. A cycle detected and then hidden would leave the caller
+		* with a `path` it cannot account for.
+		*/
+		if (visited.has(at)) {
+			stopReason = "cycle";
+			break;
+		}
+		visited.add(at);
+	}
 	return {
-		center,
-		depth,
-		nodes,
-		edges: nodes.length
+		requested,
+		path: at,
+		hops: steps.length,
+		steps,
+		stopReason,
+		title: titles.get(at) ?? null,
+		indexedCommit: state?.head_sha ?? null
 	};
 });
 /**
@@ -1539,9 +1834,20 @@ const listMemories = (params) => Effect.gen(function* () {
 		values.push(params.tag);
 	}
 	if (params.entity !== void 0 && params.entity !== "") {
-		conditions.push("EXISTS (SELECT 1 FROM file_entities e WHERE e.path = f.path AND e.entity_type || ':' || e.entity_name = ?)");
-		values.push(params.entity);
+		conditions.push("EXISTS (SELECT 1 FROM file_entities e WHERE e.path = f.path AND lower(e.entity_type || ':' || e.entity_name) = lower(?))");
+		values.push(params.entity.trim());
 	}
+	/**
+	* The facet axis, from `@memhtml/index`'s builder rather than a second copy of the grouping.
+	*
+	* The listing binds anonymous `?` in textual order, so the placeholder callback pushes onto
+	* `values` and returns the marker. That is the same contract the numbered form has: whatever the
+	* builder emits, the values it pushed are in the order the statement reads them.
+	*/
+	for (const condition of facetConditions(params.facets ?? [], "f", (value) => {
+		values.push(value);
+		return "?";
+	})) conditions.push(condition);
 	if (params.cursor !== void 0 && params.cursor !== "") {
 		conditions.push("f.path > ?");
 		values.push(normalizePath(params.cursor));
@@ -1568,6 +1874,116 @@ const listMemories = (params) => Effect.gen(function* () {
 		nextCursor
 	};
 });
+/** The most rows one call returns. A caller asking for more is clamped into it. */
+const ENTITY_ACTIVITY_MAX = 500;
+/**
+* {@link entityActivity}'s statement, as a pure function of its parameters.
+*
+* Exported for `neighborsQuery`'s reason: a cost contract can only be asserted at the planner, and a
+* test that EXPLAINed a pasted copy of the SQL would be explaining its own string. This repo has
+* already written that test the other way and watched it keep passing while the clause it guarded was
+* deleted from the source. Handing the caller the statement the code issues is what makes the plan
+* assertion about the code.
+*
+* `count(*) OVER ()` counts the GROUPED rows, so it is the number of distinct entities in scope rather
+* than the number of `file_entities` rows. A window function is evaluated after grouping, which is what
+* makes one statement answer both the page and its total; a second `COUNT` over the same predicate
+* could disagree with this one under a concurrent write.
+*
+* `GROUP BY (entity_type, entity_name)` is exactly `file_entities_name`'s column SET, so the grouping
+* is served by an index scan rather than by a sort of the whole join. The SET is what matters and the
+* order within it does not: probed 2026-08-26 on node 24's `node:sqlite`, naming the two columns either
+* way plans identically as `SCAN e USING INDEX file_entities_name`, because SQLite reorders group keys
+* to match an index it can use. Grouping on a set the index does NOT cover — `entity_name` alone, or
+* `(path, entity_name)` — adds `USE TEMP B-TREE FOR GROUP BY`, a full sort of the join per call. The
+* ORDER BY is over an aggregate and no index can serve it, which is the one sort this statement pays
+* for knowingly.
+*/
+const entityActivityQuery = (params = {}) => {
+	const limit = Math.min(500, Math.max(1, Math.trunc(params.limit ?? 50)));
+	const conditions = [];
+	const values = [];
+	if (params.includeArchived !== true) conditions.push("f.archived = 0");
+	if (params.entityType !== void 0 && params.entityType !== "") {
+		conditions.push("lower(e.entity_type) = lower(?)");
+		values.push(params.entityType.trim());
+	}
+	return {
+		sql: `SELECT e.entity_type AS entity_type, e.entity_name AS entity_name,
+              count(*) AS file_count,
+              max(coalesce(f.event_at, f.updated_at)) AS last_activity_at,
+              max(f.event_at) AS last_event_at,
+              max(f.updated_at) AS last_written_at,
+              count(*) OVER () AS entity_total
+       FROM file_entities e JOIN files f ON f.path = e.path
+       ${conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`}
+       GROUP BY e.entity_type, e.entity_name
+       ORDER BY max(coalesce(f.event_at, f.updated_at)) DESC,
+                e.entity_type ASC, e.entity_name ASC
+       LIMIT ?`,
+		params: [...values, limit],
+		limit
+	};
+};
+/**
+* Every entity in the corpus with its file count and its last activity, newest first.
+*
+* **REPORT-ONLY, and that is a design constraint rather than a description of today's callers.** This
+* value must never become a decay term, a retention input, or a ranking signal. The salience arm
+* already refuses to rank two kinds of row for reasons that apply here word for word
+* (`SALIENCE_EXCLUDED_PREFIX` and `SALIENCE_EXCLUDED_TYPE`, `packages/index/src/retrieval-sql.ts`):
+* decay is wrong for identity, because a colleague unmentioned for six months is not less themselves,
+* and decay over working state would reward STALENESS, so the stuck task re-read at every triage would
+* outrank the fresh urgent one. An "entity last active" number wired into ranking reintroduces both at
+* once, on the axis where a consumer models its own domain. It answers a question an operator asks;
+* it decides nothing.
+*
+* **WRITE-side activity, deliberately, so the read stays inside one database.** Reads live in
+* `state.access`, which is path-keyed with NO foreign key onto `files`
+* (`packages/index/state-migrations/S0001_access.sql`) and which is ATTACHed as a separate plane —
+* `index.db` is a disposable projection of git and `state.db` is not. Joining it here would make one
+* report span both lifetimes, so a rebuilt index and a preserved state plane could disagree about a
+* row. The salience arm already owns read-time signals and is the only statement that crosses that
+* boundary.
+*
+* Every memory type counts, tasks included, matching {@link listMemories} rather than
+* `activeEntities` in `@memhtml/sleep`. That function excludes tasks because it FEEDS a phase that
+* mints person files from what it finds, and a person mentioned only by a to-do item would get a
+* durable identity surface out of it. Nothing here mints anything, and a report that hid an entity's
+* task activity would be answering a narrower question than the one asked.
+*
+* `entityCount` is the total matching the scope, independent of `limit`, so a clamped answer is
+* visible rather than silent — a caller can tell "these are all of them" from "these are the newest
+* of more".
+*
+* **A row is one STORED reference, not one folded identity.** The grouping is on `(entity_type,
+* entity_name)` as `file_entities` holds them, so a corpus that authored both `Service:Checkout-API`
+* and `service:checkout-api` reports two rows while `--entity` at either retrieval door folds them and
+* returns one entity's memories. That is the honest report of an unresolved corpus — `entity-resolution`
+* is the phase that folds spellings, and a report that folded them first would hide the work it has to
+* do — but it means `fileCount` is per stored spelling and a caller summing rows to a per-name total
+* has to fold them itself.
+*/
+const entityActivity = (params = {}) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const statement = entityActivityQuery(params);
+	const rows = yield* db.all(statement.sql, statement.params);
+	return {
+		entities: rows.map((row) => ({
+			entity: `${row.entity_type}:${row.entity_name}`,
+			entityType: row.entity_type,
+			entityName: row.entity_name,
+			fileCount: row.file_count,
+			lastActivityAt: row.last_activity_at,
+			lastEventAt: row.last_event_at,
+			lastWrittenAt: row.last_written_at
+		})),
+		/** Distinct entities matching the scope, before `limit`. `0` when the scope matched nothing. */
+		entityCount: rows[0]?.entity_total ?? 0,
+		/** The bound this answer was built under, so a clamped ask is legible rather than silent. */
+		limit: statement.limit
+	};
+});
 /**
 * Move a task to a new status.
 *
@@ -1582,9 +1998,9 @@ const listMemories = (params) => Effect.gen(function* () {
 * fifth value every archive, correction, and publish path would have to learn. The stamp is written
 * before the move so both land in one commit and `git log --follow` reads through it.
 *
-* `indexer.update()` afterwards rather than `indexPaths`, because the `done` transition is a rename and
-* `indexPaths` cannot express one. It would leave the pre-archive row live, duplicate the chunks
-* under two paths, and skip the watermark (finding from T9, stated at {@link reindex}).
+* Reindexed through {@link reindex}, which diffs the whole commit. The `done` transition is a rename,
+* and only a diff expresses one: indexing the destination path alone leaves the pre-archive row live,
+* duplicates the chunks under two paths, and records no watermark.
 */
 const setTaskStatus = (params) => Effect.gen(function* () {
 	const status = yield* decodeTaskStatus(params.status);
@@ -1684,7 +2100,7 @@ const DETECTED_TASK_GLOB = `*/${DETECTION_PREFIX}${"[0-9a-f]".repeat(12)}-*.html
 * memory-graph query filters on, and a reader who saw this one query trust the rel alone would learn
 * the wrong rule about how the firewall is enforced.
 *
-* `group_concat` over an ordered subselect, probed 2026-08-12 on node 24.19.0. The inner `ORDER BY`
+* `group_concat` over an ordered subselect, probed 2026-08-12 on node 24.19.0: the inner `ORDER BY`
 * is preserved, and `char(10)` is the separator because a path cannot contain a newline while it can
 * contain a comma.
 *
@@ -1810,7 +2226,18 @@ const indexTraces = () => Effect.gen(function* () {
 	let merged = 0;
 	for (const scanned of report.files) {
 		const outcome = yield* persistScanned(db, scanned, tailMerger, at);
-		if (outcome.action !== "skip") sessionsWritten += 1;
+		/**
+		* `sessionsWritten` counts files for which a `traces` ROW was written, which is exactly the
+		* files `persistScanned` returns a session id for. It writes a row only for a non-skip
+		* carrying an extract and a session id, so the three files it declines — a skip, a failed
+		* read (a null extract), and a `file-history-*`-only file with no session to be about — are
+		* each not a session written.
+		*
+		* The action alone cannot answer this. A failed read keeps the action the PLAN named, `tail`
+		* or `rescan`, because the watermark logic needs to know what was attempted; a report that
+		* read the action as the write would claim a session for a transcript that errored.
+		*/
+		if (outcome.sessionId !== null) sessionsWritten += 1;
 		if (outcome.merged) merged += 1;
 		promptsWritten += outcome.promptsWritten;
 	}
@@ -1820,6 +2247,7 @@ const indexTraces = () => Effect.gen(function* () {
 		skipped: report.skipped,
 		tailed: report.tailed,
 		rescanned: report.rescanned,
+		filesFailed: report.failed,
 		bytesRead: report.bytesRead,
 		sessionsWritten,
 		promptsWritten,
@@ -1879,6 +2307,12 @@ const searchTraces = (params) => Effect.gen(function* () {
 	};
 });
 /**
+* Rows one `trace links` answer may carry. Every sibling read clamps (`memory_list` 500,
+* `trace_search` 200), and a long-lived session accretes links without bound, so an unclamped
+* answer grows forever. Newest first, so the truncation costs the oldest links.
+*/
+const TRACE_LINKS_LIMIT = 500;
+/**
 * The memory-session links, from either side.
 *
 * Both parameters absent is a refusal rather than an unbounded scan of every link ever recorded. A
@@ -1902,7 +2336,8 @@ const traceLinks = (params) => Effect.gen(function* () {
 	return { links: (yield* db.all(`SELECT l.path, l.session_id, l.prompt_id, l.turn_uuid, l.link_kind, l.at
        FROM memory_session_links l
        WHERE ${conditions.join(" AND ")}
-       ORDER BY l.at DESC, l.path ASC`, values)).map((row) => ({
+       ORDER BY l.at DESC, l.path ASC
+       LIMIT ${TRACE_LINKS_LIMIT}`, values)).map((row) => ({
 		path: row.path,
 		sessionId: row.session_id,
 		promptId: row.prompt_id,
@@ -1967,27 +2402,46 @@ const countRows = (db, sql) => db.all(sql).pipe(Effect.map((rows) => Object.from
 
 //#endregion
 //#region apps/cli/src/commands.ts
-/** Flags every command accepts. Listed once so the manifest cannot drift from behavior. */
-const GLOBAL_FLAGS = [
-	{
-		name: "json",
-		type: "boolean",
-		description: "Emit the typed JSON envelope on stdout (default; logs go to stderr).",
-		default: true
-	},
-	{
-		name: "dense",
-		type: "boolean",
-		description: "Minify JSON and drop null fields, for pasting into a context window.",
-		default: false
-	},
-	{
-		name: "repo",
-		type: "string",
-		description: "Path to the memory repo. Defaults to $MEMHTML_ROOT.",
-		default: ""
-	}
-];
+/**
+* Flags every command accepts. Listed once so the manifest cannot drift from behavior.
+*
+* There is no `--json` flag: the typed JSON envelope is the only output the binary has, on every
+* command, so a flag for it would be parsed, advertised, and read by nothing. Logs go to stderr.
+*/
+const GLOBAL_FLAGS = [{
+	name: "dense",
+	type: "boolean",
+	description: "Minify JSON and drop null fields, for pasting into a context window.",
+	default: false
+}, {
+	name: "repo",
+	type: "string",
+	description: "Path to the memory repo. Defaults to $MEMHTML_ROOT.",
+	default: ""
+}];
+/**
+* The `--strict-path` help.
+*
+* It states the DEFAULT as well as the opt-in, because the default is the surprising half: a caller
+* reaching for this flag is a caller who just discovered that a malformed `--path` was re-derived, and
+* the help has to confirm that reading rather than leave it inferred. The refusal's code is named too,
+* since a caller branches on `code` and never on the prose.
+*/
+const STRICT_PATH_FLAG = "Refuse an unusable --path instead of letting the placement rule decide. By default a --path that is not a usable memory path is re-derived, so the memory lands somewhere you did not name and the response reports that other path as a success. With this flag the write is REFUSED with ERR_INVALID_MEMORY naming the clause the path broke, and nothing is written, staged, or committed. It governs the path you NAMED: with no --path there is nothing to be strict about and the flag changes nothing, while an EMPTY or blank --path is named rather than absent and is refused — that is what your own path template renders when it produced nothing. An OCCUPIED path is refused with ERR_WRITE_CONFLICT with or without it.";
+/**
+* The `--facet` help, shared by every command that scopes on one.
+*
+* The composition rule is IN the help because it is a semantic contract rather than a convenience: a
+* caller who read `--facet a=1 --facet b=2` as "either" would act on a superset, and one who read
+* `--facet a=1 --facet a=2` as "both" would act on an empty result. Neither mistake is visible in
+* the rows that come back.
+*
+* The unitless clause is there for the same reason. `file_facets.numeric_value` exists, and offering
+* a numeric comparison over it would be offering an inequality on an unlabelled number — the unit
+* lives in the human phrasing beside the value, so the caller owns it, and it owns it by matching the
+* text the corpus holds.
+*/
+const FACET_FLAG = "Restrict to memories carrying a `<dl>` facet, as name=value; the value may contain `=`, the name may not. Repeatable, and the composition is fixed: values under the SAME name broaden (--facet doc-type=runbook --facet doc-type=guide is either), DIFFERENT names narrow (--facet doc-type=runbook --facet tier=1 is both). This is the extension axis: memhtml's element and meta vocabularies are closed, so a consumer's own document kinds, states, and tiers live in `<dt>`/`<dd>` pairs and are queried here. The match is on the facet's TEXT with no case folding, so write the halves you mean to query. The stored form is the element's text content, which the parser collapses whitespace runs in and trims — so `<dd>runbook  rollback</dd>` is stored and queried single-spaced. There is no numeric comparison: a `<data value>` is indexed UNITLESS because the unit lives in the prose beside it, so the caller owns the unit and matches the text it wrote.";
 /** Flags every retrieval command shares, so `search` and `recall` cannot scope differently. */
 const SCOPE_FLAGS = [
 	{
@@ -2013,6 +2467,12 @@ const SCOPE_FLAGS = [
 		type: "string",
 		description: "Restrict to memories carrying one `type:name` entity reference, e.g. service:checkout-api, the form a hit's `entities` publishes, so a hop is a copy. A scope matching nothing returns no hits and says so; it never widens."
 	},
+	{
+		name: "facet",
+		type: "string",
+		description: FACET_FLAG,
+		repeatable: true
+	},
 	{
 		name: "include-archived",
 		type: "boolean",
@@ -2087,7 +2547,13 @@ const COMMANDS = [
 			{
 				name: "path",
 				type: "string",
-				description: "An explicit path override. Ignored when it is not a valid memory path."
+				description: "An explicit path override. One that is not a usable memory path (rooted in a PARA bucket, ending in .html, no `.` or `..` segment) is IGNORED and the placement rule decides instead, so a malformed override lands the memory somewhere you did not name — pass --strict-path to have it refused instead. One a file ALREADY occupies is REFUSED with ERR_WRITE_CONFLICT and nothing is written or committed: this corpus overwrites nothing, and an explicit path gets no `-2` suffix because you named one path. To replace what a memory says, use `memhtml correct <path>`."
+			},
+			{
+				name: "strict-path",
+				type: "boolean",
+				description: STRICT_PATH_FLAG,
+				default: false
 			},
 			{
 				name: "workspace",
@@ -2141,7 +2607,7 @@ const COMMANDS = [
 			{
 				name: "file",
 				type: "string",
-				description: "The JSONL file to read. One complete JSON object per line. Omit it (or pass `-`) to read the stream from stdin."
+				description: "The JSONL file to read. One complete JSON object per line. Omit it, pass `--file -`, or pass a positional `-` to read the stream from stdin; stdin beside a real --file is refused."
 			},
 			{
 				name: "continue-on-error",
@@ -2187,11 +2653,31 @@ const COMMANDS = [
 			description: "Repo-root-relative path to the memory.",
 			required: true
 		}],
-		flags: [{
-			name: "session-id",
-			type: "string",
-			description: "Records a `read` session link, so provenance is queryable both ways."
-		}],
+		/**
+		* The whole provenance triple, because the `read` arm stamps the whole triple.
+		* `memory_session_links` carries `prompt_id` and `turn_uuid` beside `session_id`, so a command
+		* that declared only the session would record a coarser link for a read than the write path
+		* records for the same turn, and one triple could not be threaded through a write-then-read
+		* flow. MCP's `memory_read` narrows to `session_id`; this surface is the one an agent threads a
+		* triple through.
+		*/
+		flags: [
+			{
+				name: "session-id",
+				type: "string",
+				description: "Records a `read` session link, so provenance is queryable both ways."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
+			}
+		],
 		responseTypes: ["memory.detail"]
 	},
 	{
@@ -2272,6 +2758,16 @@ const COMMANDS = [
 				name: "session-id",
 				type: "string",
 				description: "Records a `corrected` session link."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
 			}
 		],
 		responseTypes: ["memory.corrected"]
@@ -2307,20 +2803,40 @@ const COMMANDS = [
 			description: "The center of the neighborhood.",
 			required: true
 		}],
-		flags: [{
-			name: "depth",
-			type: "int",
-			description: "1 or 2. Never more.",
-			default: 1
-		}, {
-			name: "rel",
-			type: "string",
-			description: "Restrict to these rels. Repeatable.",
-			values: MEMORY_RELS,
-			repeatable: true
-		}],
+		flags: [
+			{
+				name: "depth",
+				type: "int",
+				description: "1 or 2. Never more.",
+				default: 1
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Distinct nodes to return, clamped to 200. `nodesDropped` counts the paths the walk reached and this limit turned away, and `scanSaturated` says the walk stopped at its own 10000-row cap, which no limit recovers.",
+				default: 200
+			},
+			{
+				name: "rel",
+				type: "string",
+				description: "Restrict to these rels. Repeatable.",
+				values: MEMORY_RELS,
+				repeatable: true
+			}
+		],
 		responseTypes: ["memory.neighbors"]
 	},
+	{
+		name: "resolve",
+		summary: "Follow a possibly-moved path forward to the memory that carries the fact now.",
+		args: [{
+			name: "path",
+			description: "The path a receipt, citation, or older answer recorded.",
+			required: true
+		}],
+		flags: [],
+		responseTypes: ["memory.resolved"]
+	},
 	{
 		name: "archive",
 		summary: "Soft-evict: `git mv` into archive/<YYYY>/ with the archive stamps. Never a delete.",
@@ -2343,7 +2859,8 @@ const COMMANDS = [
 		args: [{
 			name: "path",
 			description: "A memory path. Repeat the argument for more.",
-			required: true
+			required: true,
+			repeatable: true
 		}],
 		flags: [{
 			name: "signal",
@@ -2356,7 +2873,7 @@ const COMMANDS = [
 	},
 	{
 		name: "list",
-		summary: "Page through the corpus by type, workspace, tag, entity, or PARA bucket.",
+		summary: "Page through the corpus by type, workspace, tag, entity, facet, or PARA bucket.",
 		args: [],
 		flags: [
 			{
@@ -2380,6 +2897,12 @@ const COMMANDS = [
 				type: "string",
 				description: "One `type:name` entity reference."
 			},
+			{
+				name: "facet",
+				type: "string",
+				description: FACET_FLAG,
+				repeatable: true
+			},
 			{
 				name: "para",
 				type: "string",
@@ -2411,6 +2934,31 @@ const COMMANDS = [
 		],
 		responseTypes: ["memory.list"]
 	},
+	{
+		name: "entity activity",
+		summary: "Every entity with its file count and its last activity, newest first. Report only.",
+		args: [],
+		flags: [
+			{
+				name: "type",
+				type: "string",
+				description: "Restrict to one entity type, e.g. `service`. The half before the colon in a `type:name` reference."
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Rows to return, 1 to 500. An ask outside that is clamped into it rather than refused, and `limit` echoes the bound the answer was built under. `entityCount` is the total matching the scope, so a clamped answer is visible.",
+				default: 50
+			},
+			{
+				name: "include-archived",
+				type: "boolean",
+				description: "Aggregate archived memories too. Excluded by default: eviction is a `git mv`, so an archived memory still exists and would otherwise keep an entity looking active.",
+				default: false
+			}
+		],
+		responseTypes: ["entity.activity"]
+	},
 	(
 	/**
 	* The task family: CRUDL over the 10th memory type, without retrieval.
@@ -2640,12 +3188,13 @@ const COMMANDS = [
 	{
 		name: "sleep run",
 		/**
-		* The count is DERIVED from `SLEEP_PHASES`, not typed. Both strings used to spell `15` by hand,
-		* and adding a sixteenth phase left `AGENTS.md` and `memhtml manifest` asserting a number the list
-		* beside them contradicted — visible only because the doc drift gate compares generated bytes, and
-		* only for the one of the two that also prints the names.
+		* Both counts are `SLEEP_PHASES.length`, never typed. A phase added to that list moves this
+		* summary and the `--phases` description below together, so neither can assert a number the list
+		* printed beside it contradicts. A hand-typed count is not symmetrically caught: the doc drift
+		* gate compares generated bytes, so it fails only on the string that also prints the names, and a
+		* stale number in the other one ships.
 		*/
-		summary: `The nightly curation cycle: ${SLEEP_PHASES.length} phases, each an isolated commit on a review branch.`,
+		summary: `The curation cycle: ${SLEEP_PHASES.length} phases, each an isolated commit on a review branch.`,
 		args: [],
 		flags: [
 			{
@@ -2663,6 +3212,17 @@ const COMMANDS = [
 				type: "boolean",
 				description: "Report per-phase counts and commit nothing.",
 				default: false
+			},
+			{
+				name: "deep",
+				type: "boolean",
+				description: "The deep-sleep cycle: mine a lower grouping band, group by shared entity, re-file inbox singletons, and iterate compress until a pass folds nothing. Reaches the inbox tail the default community gate cannot; costs more model calls. Same branch, review, and merge gate as a run without this flag.",
+				default: false
+			},
+			{
+				name: "max-llm-calls",
+				type: "int",
+				description: "Cap on model calls the deep mechanisms may spend, shared across all deep phases. Exhaustion skips remaining batches with reason `budget` and the run stays green. Read only with --deep; absent means uncapped."
 			}
 		],
 		responseTypes: ["sleep.report"]
@@ -2717,6 +3277,13 @@ const COMMANDS = [
 		flags: [],
 		responseTypes: ["sleep.report"]
 	},
+	{
+		name: "sleep plan",
+		summary: "Would a run change anything? Read the signals from index counts, running no phase.",
+		args: [],
+		flags: [],
+		responseTypes: ["sleep.plan"]
+	},
 	{
 		name: "status",
 		summary: "Corpus health: HEAD, dirty state, counts by type, edges, index freshness.",
@@ -2760,6 +3327,11 @@ const COMMANDS = [
 				type: "int",
 				description: "The fixture corpus seed. A failing run is reproducible from this number."
 			},
+			{
+				name: "now",
+				type: "int",
+				description: "The run instant the fixture corpus anchors its stamps behind, UTC milliseconds since the epoch. The other half of reproducing a failing run: the corpus is a function of (seed, now), and the recency arm ranks on those stamps. Defaults to the clock, and rides back in the report."
+			},
 			{
 				name: "size",
 				type: "int",
@@ -2820,7 +3392,7 @@ const COMMANDS = [
 			{
 				name: "file",
 				type: "string",
-				description: "The script to run, as a path on the HOST. Omit it (or pass `-`) to read the script from stdin. Mutually exclusive with `--script`."
+				description: "The script to run, as a path on the HOST. Omit it, pass `--file -`, or pass a positional `-` to read the script from stdin. Mutually exclusive with `--script`."
 			},
 			{
 				name: "script",
@@ -2873,7 +3445,7 @@ const COMMANDS = [
 	},
 	{
 		name: "serve mcp",
-		summary: "Run the `memhtml-mcp` stdio server: 14 tools and 2 resources over this same repo.",
+		summary: "Run the `memhtml-mcp` stdio server: 15 tools and 3 resources over this same repo.",
 		args: [],
 		flags: [],
 		responseTypes: ["serve.exit"]
@@ -2908,12 +3480,12 @@ const GUIDE = [
 	},
 	{
 		topic: "write-surfaces",
-		body: "There are three ways to put a memory into the corpus, and they are all legitimate. First, this CLI: `memhtml write` for one memory, `memhtml apply` for many. Second, the MCP server: `memhtml serve mcp` speaks stdio with 14 tools and 2 resources over this same repo, and it is the door to use when you are already an MCP client. Third, editing files under $MEMHTML_ROOT directly with your normal file tools: the git tree IS the system of record and `.memhtml/index.db` is only a projection of it, so a hand-written or hand-edited memory file is as real as one this CLI wrote. `memhtml index update` projects uncommitted working-tree changes as well as committed ones, so a dirty edit is searchable before you commit it. What you take on by editing directly is everything the write path would have done for you: the file must satisfy the format (run `memhtml doctor`, and `memhtml read <path>` reports per-file format warnings), you own choosing a path that does not collide, you own noticing that the content already exists somewhere else, and you own the commit. The nightly `memhtml sleep run` refuses to start on a dirty tree, so an uncommitted edit blocks curation until it is committed or stashed. A CLI command and a running `memhtml serve mcp` may share one store: the index is WAL SQLite, which admits one writer at a time and any number of concurrent readers, so a second writer waits its turn rather than failing. The one thing to keep clear of is `memhtml sleep run`, and for a git reason rather than a database one: a run holds a checked-out `sleep/<date>` branch, so a write landing during it commits onto that branch and is merged as if it were curation or lost when the branch is dropped."
+		body: "There are three ways to put a memory into the corpus, and they are all legitimate. First, this CLI: `memhtml write` for one memory, `memhtml apply` for many. Second, the MCP server: `memhtml serve mcp` speaks stdio with the same tools and resources over this same repo, and it is the door to use when you are already an MCP client. Third, editing files under $MEMHTML_ROOT directly with your normal file tools: the git tree IS the system of record and `.memhtml/index.db` is only a projection of it, so a hand-written or hand-edited memory file is as real as one this CLI wrote. `memhtml index update` projects uncommitted working-tree changes as well as committed ones, so a dirty edit is searchable before you commit it. What you take on by editing directly is everything the write path would have done for you: the file must satisfy the format (run `memhtml doctor`, and `memhtml read <path>` reports per-file format warnings), you own choosing a path that does not collide, you own noticing that the content already exists somewhere else, and you own the commit. `memhtml sleep run` refuses to start on a dirty tree, so an uncommitted edit blocks curation until it is committed or stashed. A CLI command and a running `memhtml serve mcp` may share one store: the index is WAL SQLite, which admits one writer at a time and any number of concurrent readers, so a second writer waits its turn rather than failing. The one thing to keep clear of is `memhtml sleep run`, and for a git reason rather than a database one: a run holds a checked-out `sleep/<date>` branch, so a write landing during it commits onto that branch and is merged as if it were curation or lost when the branch is dropped."
 	},
 	{
 		topic: "when-to-batch",
 		body: `Writing more than about three memories in one task? Call \`memhtml apply\` once with a JSONL op stream instead of running \`memhtml write\` N times. A batch stages every file, makes ONE commit, and reindexes ONCE, where N separate writes make N commits and pay N index passes over N diffs. Pass the stream as \`memhtml apply --file ops.jsonl\`, or pipe it: \`memhtml apply -\` and a bare \`memhtml apply\` both read stdin. One complete JSON object per line, no wrapping array, no pretty-printing. A line looks like this:
-${GUIDE_OP_EXAMPLE}\n\`op\` is \`write\` (the only verb in the vocabulary today), \`title\` and \`type\` are required, and each op carries the same optional fields \`memhtml write\` takes, in snake_case: \`path\`, \`workspace\`, \`tag\`, \`entity\`, \`importance\`, \`confidence\`, \`session_id\`, \`prompt_id\`, \`turn_uuid\`. The whole file is validated for shape before ANY op executes, so a malformed line 7 is exit 2 naming line 7 with nothing written. A failed apply costs you nothing but the call. You get one result per op in INPUT ORDER, each naming its own \`index\`, so you can match results back to the lines you sent. A batch is ATOMIC by default: the first refused op aborts the whole batch, no file is written, no commit is made, and the surviving ops report \`skipped: true\`. Pass \`--continue-on-error\` for best-effort instead, and a refused op comes back as one failed result carrying its own \`code\` and \`error\` while every op that succeeded lands in the one commit. A duplicate is never an error: an op whose exact content is already stored comes back \`ok: true\` with \`deduped: true\` and the existing path, so re-applying a file you already applied is safe and writes nothing. \`commit_sha\` is null exactly when nothing was committed: a batch that only deduped, or one that aborted.`
+${GUIDE_OP_EXAMPLE}\n\`op\` is \`write\` (the only verb in the vocabulary today), \`title\` and \`type\` are required, and each op carries the same optional fields \`memhtml write\` takes, in snake_case: \`path\`, \`strict_path\`, \`workspace\`, \`tag\`, \`entity\`, \`importance\`, \`confidence\`, \`status\`, \`due\`, \`session_id\`, \`prompt_id\`, \`turn_uuid\`. The whole file is validated for shape before ANY op executes, so a malformed line 7 is exit 2 naming line 7 with nothing written. A failed apply costs you nothing but the call. You get one result per op in INPUT ORDER, each naming its own \`index\`, so you can match results back to the lines you sent. A batch is ATOMIC by default: the first refused op aborts the whole batch, no file is written, no commit is made, and the surviving ops report \`skipped: true\`. Pass \`--continue-on-error\` for best-effort instead, and a refused op comes back as one failed result carrying its own \`code\` and \`error\` while every op that succeeded lands in the one commit. A duplicate is never an error: an op whose exact content is already stored comes back \`ok: true\` with \`deduped: true\` and the existing path, so re-applying a file you already applied is safe and writes nothing. \`commit_sha\` is null exactly when nothing was committed: a batch that only deduped, or one that aborted.`
 	},
 	{
 		topic: "conflicts",
@@ -2925,7 +3497,7 @@ ${GUIDE_OP_EXAMPLE}\n\`op\` is \`write\` (the only verb in the vocabulary today)
 	},
 	{
 		topic: "code-mode",
-		body: "Answering a question that takes MORE THAN ONE HOP through the corpus? Write it as a script and run `memhtml exec` once, instead of spending a tool call per hop. Supersedence ancestry, live contradiction pairs, orphan census, entity co-occurrence, 'which of these 40 paths has no backlink': each of those is one traversal in code and N round trips through `memhtml read` and `memhtml neighbors`. Measured on a 305-file corpus: a full census in 598ms, and 410 edges resolved into 201 chains, longest 8 hops, in one execution at 430ms. The script runs under QuickJS in a sandbox with the corpus mounted READ-ONLY at `/mnt/memhtml`, and a helper is already seeded for you at `/workspace/lib/corpus.mjs`. Import it: `import { corpus, backlinks, chain, edges } from \"/workspace/lib/corpus.mjs\"`. `corpus()` returns a Map keyed by root-absolute path (the SAME string an edge's href holds, so `memories.get(link.href)` resolves with no path juggling) and each value carries `claim`, `memoryType`, `status`, `tags`, `entities`, `links`, `facets`, `citations`, `eventAt`, and a `document` escape hatch for any selector the fields do not cover. Print your answer as JSON on stdout with `console.log`; it comes back verbatim in `data.stdout`, so keep it small and structured rather than dumping the corpus. THREE THINGS IT CANNOT DO, by design. It cannot write: the corpus is read-only and a write answers EROFS, so every write still goes through `memhtml write` / `memhtml apply`, which own commits, dedup, and conflict detection. It cannot rank: no cosine, no RRF, no salience, and no index database. For ranked retrieval shell out to `memhtml search --json` and parse its envelope, which the one-envelope-per-command contract already makes a code-mode API. And it cannot reach the network: there is no curl and the guest's `fetch` refuses on call. The intended opening move is ranked retrieval FIRST, code-mode second: `memhtml search` or `memhtml recall` to get the handful of paths the ranking stack says matter, then `memhtml exec` to walk, join, count, and filter from there. Starting in code-mode means starting with a full-corpus scan and no relevance signal. A non-zero `exitCode` in the response is YOUR script failing, not the command failing. Read `data.stderr` for the diagnostic and the exit code is still 0. A script that runs past `--timeout-ms` (default 30000) comes back `exitCode: 124` with `timedOut: true`. The tree you get is a pinned commit, HEAD by default, named in `data.sha`, so an answer is reproducible with `--sha`, and an uncommitted edit is NOT visible to the script."
+		body: "Answering a question that takes MORE THAN ONE HOP through the corpus? Write it as a script and run `memhtml exec` once, instead of spending a tool call per hop. Supersedence ancestry, live contradiction pairs, orphan census, entity co-occurrence, 'which of these 40 paths has no backlink': each of those is one traversal in code and N round trips through `memhtml read` and `memhtml neighbors`. Measured on a 305-file corpus: a full census in 598ms, and 410 edges resolved into 201 chains, longest 8 hops, in one execution at 430ms. The script runs under QuickJS in a sandbox with the corpus mounted READ-ONLY at `/mnt/memhtml`, and a helper is already seeded for you at `/workspace/lib/corpus.mjs`. Import it: `import { corpus, backlinks, chain, edges } from \"/workspace/lib/corpus.mjs\"`. `corpus()` returns a Map keyed by root-absolute path (the SAME string an edge's href holds, so `memories.get(link.href)` resolves with no path juggling) and each value carries `claim`, `memoryType`, `status`, `tags`, `entities`, `links`, `facets`, `citations`, `eventAt`, and a `document` escape hatch for any selector the fields do not cover. Print your answer as JSON on stdout with `console.log`; it comes back verbatim in `data.stdout`, so keep it small and structured rather than dumping the corpus. THREE THINGS IT CANNOT DO, by design. It cannot write: the corpus is read-only and a write answers EROFS, so every write still goes through `memhtml write` / `memhtml apply`, which own commits, dedup, and conflict detection. It cannot rank: no cosine, no RRF, no salience, and no index database. For ranked retrieval shell out to `memhtml search` and parse its envelope, which the one-envelope-per-command contract already makes a code-mode API. And it cannot reach the network: there is no curl and the guest's `fetch` refuses on call. The intended opening move is ranked retrieval FIRST, code-mode second: `memhtml search` or `memhtml recall` to get the handful of paths the ranking stack says matter, then `memhtml exec` to walk, join, count, and filter from there. Starting in code-mode means starting with a full-corpus scan and no relevance signal. A non-zero `exitCode` in the response is YOUR script failing, not the command failing. Read `data.stderr` for the diagnostic and the exit code is still 0. A script that runs past `--timeout-ms` (default 30000) comes back `exitCode: 124` with `timedOut: true`. The tree you get is a pinned commit, HEAD by default, named in `data.sha`, so an answer is reproducible with `--sha`, and an uncommitted edit is NOT visible to the script."
 	}
 ];
 const GUIDE_TOPICS = GUIDE.map((block) => block.topic);
@@ -2936,13 +3508,14 @@ const GUIDE_TOPICS = GUIDE.map((block) => block.topic);
 */
 const buildManifest = () => ({
 	name: "memhtml",
-	version: "0.5.1",
+	version: "0.7.0",
 	summary: "Read, write, and curate the git-backed memory repo.",
 	apiVersion: "1",
 	/**
 	* The prose an agent needs before the command table means anything, so it is listed before it.
-	* A manifest that opened with 33 command specifications makes an agent infer the workflow from a
-	* surface, while `guide` states it.
+	* A manifest that opens with the command specifications makes an agent infer the workflow from a
+	* surface, while `guide` states it. No count appears here: `commands` is `COMMANDS` walked, so the
+	* only honest quantity is its `length`.
 	*/
 	guide: GUIDE,
 	globalFlags: GLOBAL_FLAGS,
@@ -3142,22 +3715,22 @@ const runAgentsDoc = (options) => Effect.gen(function* () {
 * Prose → claim derivation: the single implementation both write doors use.
 *
 * The tools take `{title, body}` because that is what a model produces, and the format needs a
-* `<mark>` claim plus one `<p>` per paragraph. Turning the first into the second is a text heuristic,
-* and it lives here for two reasons. It was duplicated once, as `claimOf`/`restOf` in `apps/mcp` and
-* `claimFromProse`/`proseTail` in `apps/cli`, the same regex in two packages. A sentence-splitting
-* rule that drifts between the doors also makes `memhtml apply` and `memory_write_batch` derive different
-* claims from the same body, so the gist of a memory would depend on which door wrote it.
+* `<mark>` claim plus one `<p>` per paragraph. Turning the first into the second is a text
+* heuristic, and it must have exactly one copy: `apps/mcp` and `apps/cli` both import this module,
+* because a sentence-splitting rule maintained per door lets `memhtml apply` and
+* `memory_write_batch` derive different claims from the same body, making the gist of a memory
+* depend on which door wrote it.
 *
 * It does not live in `@memhtml/html`, which owns markup and the format's own rules. "Where does a
 * sentence end" is a guess about natural-language prose, and the format states no such constraint. It
 * is not in `operations.ts` either, because that module holds the use cases both doors call, and this
 * is a text helper they apply before calling one.
 *
-* The derivation is defense in depth now; it was once the only guard. `@memhtml/html` constraint 1 now
-* rejects an empty `<mark>` outright, so a door that skipped this would be stopped by the store's
-* render gate instead of landing a file with an empty `files.gist`. What is left here is the
-* authoring convenience the doors exist to provide: a JSONL line and an MCP call carry no `claim`
-* field, so the door derives one instead of asking an author to restate the body's first sentence.
+* The derivation is defense in depth: `@memhtml/html` constraint 1 rejects an empty `<mark>`
+* outright, so a door that skipped this would be stopped by the store's render gate rather than
+* landing a file with an empty `files.gist`. What this module carries is the authoring convenience
+* the doors exist to provide: a JSONL line and an MCP call carry no `claim` field, so the door
+* derives one instead of asking an author to restate the body's first sentence.
 */
 /**
 * Split prose into paragraphs on blank lines, dropping the empties. Inside a fenced code block a
@@ -3260,11 +3833,20 @@ const LIST_FIELDS = {
 	entity: "entities",
 	entities: "entities"
 };
+/**
+* Fields that must be a JSON boolean.
+*
+* Its own table because {@link SCALAR_FIELDS}' decode refuses anything that is not a string, and a
+* boolean spelled `"true"` is a different value from `true` on this wire. A caller that sent the
+* string would otherwise get a strict-path ask that reads as satisfied and behaves as absent.
+*/
+const BOOLEAN_FIELDS = { strict_path: "strictPath" };
 /** `op` is the discriminator rather than a `WriteParams` field, so it is legal and never mapped. */
 const KNOWN_FIELDS = /* @__PURE__ */ new Set([
 	"op",
 	...Object.keys(SCALAR_FIELDS),
-	...Object.keys(LIST_FIELDS)
+	...Object.keys(LIST_FIELDS),
+	...Object.keys(BOOLEAN_FIELDS)
 ]);
 /** A usage failure naming the offending line, 1-based as a text editor counts. */
 const lineError = (code, line, reason, suggestions = []) => fail(code, `${APPLY_DOC}: line ${line}: ${reason}`, suggestions);
@@ -3350,6 +3932,12 @@ const opAt = (record, line) => {
 		if (isFailure(parsed)) return parsed;
 		params[target] = [...params[target] ?? [], ...parsed];
 	}
+	for (const [field, target] of Object.entries(BOOLEAN_FIELDS)) {
+		const value = record[field];
+		if (value === void 0 || value === null) continue;
+		if (typeof value !== "boolean") return lineError("ERR_INVALID_FLAG", line, `\`${field}\` must be a boolean, got ${typeof value}. JSON \`true\`, not the string "true"`);
+		params[target] = value;
+	}
 	/**
 	* `body` prose becomes claim + tail; `article_html` is used verbatim and leaves `claim` empty.
 	*
@@ -3358,10 +3946,10 @@ const opAt = (record, line) => {
 	* has no `claim` field, so a prose line's claim is derived rather than restated by its author (see
 	* {@link claimFromProse}, the one copy both doors share).
 	*
-	* Skipping this no longer lands a bad file. `@memhtml/html` constraint 1 rejects an empty `<mark>`, so
-	* the render gate would stop the op instead of committing a file with an empty `files.gist`. The
-	* derivation is what makes a prose line valid in the first place. It is no longer the only thing
-	* standing between a missing claim and a silent write.
+	* Skipping this cannot land a bad file. `@memhtml/html` constraint 1 rejects an empty `<mark>`,
+	* so the render gate would stop the op instead of committing a file with an empty `files.gist`.
+	* The derivation is what makes a prose line valid in the first place; the render gate is the
+	* guard between a missing claim and a silent write.
 	*/
 	const prose = typeof params.body === "string" ? params.body : void 0;
 	if (prose !== void 0 && prose.trim() !== "") {
@@ -3494,7 +4082,7 @@ const applyPayload = (result) => ({
 * `memhtml doctor`: the corpus's own health check, and `--fix` for the two findings a repair can settle
 * without a judgement call.
 *
-* Eight checks, and each one is a claim the design makes about the corpus rather than a lint:
+* Nine checks, and each one is a claim the design makes about the corpus rather than a lint:
 *
 * 1. **Dangling `<link>` hrefs**: an authored edge pointing at a path the tree does not hold. Design
 *    §2.3 has no foreign key on `edges` deliberately (a `<link>` may name a file the indexer has not
@@ -3518,8 +4106,12 @@ const applyPayload = (result) => ({
 *    is a task waiting on something that will never move.
 * 8. **Task inbox depth**: a task in `areas/inbox/tasks/` is work with no project, and a task inbox
 *    is meant to be drained rather than accumulated.
+* 9. **Untyped entity references**: a `memhtml-entity` meta written as a bare name indexes under the
+*    `unknown` type, which is supported, and is therefore unreachable by the typed reference the
+*    `entity` scope requires. The query returns an empty set rather than an error, so a producer
+*    emitting bare names makes its memories unfindable with nothing anywhere reporting it.
 *
-* **`--fix` repairs exactly two of the eight, and the repair logic is imported from the sleep
+* **`--fix` repairs exactly two of the nine, and the repair logic is imported from the sleep
 * integrity phase rather than re-ported.** `archivedFormOf` decides whether a dangling target moved
 * to the archive or is genuinely gone, and `applyHeadEdits`/`link`/`unlink`/`meta` are the byte-splice
 * editors that change one head line without touching the article. A parse→serialize round trip drops
@@ -3527,11 +4119,12 @@ const applyPayload = (result) => ({
 * every file it touched. A second implementation of either would be the consumer-side reimplementation
 * of producer semantics the fleet has paid for repeatedly.
 *
-* The other six report and do not repair. An inbox memory or task needs a human or an agent to decide
+* The other seven report and do not repair. An inbox memory or task needs a human or an agent to decide
 * where it belongs, a vocabulary warning needs the author's intent, and a stale index needs
 * `memhtml index update`, which doctor names in its own suggestions rather than running behind the
 * operator's back. An overdue task needs the work done or the deadline moved, and a stale blocker
-* needs someone to decide whether the blocked task is actually ready.
+* needs someone to decide whether the blocked task is actually ready. An untyped entity needs the
+* producer that wrote it to name a type, which is a vocabulary decision no repair can make.
 */
 /** How deep the inbox may get before doctor calls it a finding. */
 const INBOX_WARN_DEPTH = 20;
@@ -3543,6 +4136,14 @@ const INBOX_WARN_DEPTH = 20;
 * is the state a to-do list rots in, and a task inbox is meant to be drained rather than accumulated.
 */
 const INBOX_TASK_WARN_DEPTH = 10;
+/**
+* How many distinct untyped entity names a report lists before truncating.
+*
+* A bound rather than the whole set, because the count is a signal about a PRODUCER and twenty examples
+* name it as well as two thousand would. `untypedEntityTotal` carries the real cardinality beside the
+* sample, so a truncated list can never be mistaken for the whole one.
+*/
+const UNTYPED_ENTITY_SAMPLE = 20;
 /** Every `state.access` path the index has no `files` row for. */
 const orphanAccess = (db) => db.hasState ? db.all(`SELECT a.path AS path FROM ${STATE_SCHEMA}.access a
            LEFT JOIN files f ON f.path = a.path
@@ -3569,8 +4170,8 @@ const inboxTaskDepth = (db) => db.get(`SELECT count(*) AS n FROM files
 * "overdue" meaning the same thing in the two places an operator reads it.
 *
 * **`archived = 0` and `task_status <> 'done'` both change the result** (mutation-verified
-* 2026-08-02). A finished task's deadline is history, and reporting it would make the finding grow
-* forever and never reach zero.
+* 2026-08-02: dropping either predicate makes the count include finished tasks). A finished task's
+* deadline is history, and reporting it would make the finding grow forever and never reach zero.
 */
 const overdueTasks = (db, today) => db.all(`SELECT path, task_status, due_at FROM files
        WHERE memory_type = 'task' AND archived = 0 AND due_at IS NOT NULL
@@ -3618,6 +4219,35 @@ const staleBlockers = (db) => db.all(`SELECT t.path AS path, e.src_path AS block
 	blockerState: row.blocker_state === "missing" ? "missing" : "archived"
 }))), Effect.orElseSucceed(() => []));
 /**
+* Untyped entity references: `memhtml-entity` metas written as a bare name, which the projection files
+* under the `unknown` type rather than dropping (`@memhtml/index`'s `entityRowsFor`).
+*
+* Report-only, and excluded from `healthy` on the same reasoning as `overdueTasks`. `unknown` is a
+* SUPPORTED fallback — a hand-authored file's only entity is still a real handle — so a bare name is not
+* a defect in the corpus. What it is is invisible to the caller who would look for it: the `entity`
+* scope requires the type half, so a memory stored under `unknown:checkout-api` cannot be found by
+* `service:checkout-api`, and the query returns an empty set rather than an error. A PRODUCER that emits
+* bare names therefore makes every memory it writes unreachable by the reference an agent would guess,
+* and nothing in a green suite says so. This count is where that shows up.
+*
+* Truncated to {@link UNTYPED_ENTITY_SAMPLE} with the distinct total reported beside it, so the sample
+* can never be read as the whole set.
+*/
+const untypedEntities = (db) => db.all(`SELECT e.entity_name AS entity_name, count(*) AS files
+       FROM file_entities e JOIN files f ON f.path = e.path
+       WHERE e.entity_type = 'unknown' AND f.archived = 0
+       GROUP BY e.entity_name
+       ORDER BY files DESC, e.entity_name ASC`).pipe(Effect.map((rows) => ({
+	sample: rows.slice(0, 20).map((row) => ({
+		entityName: row.entity_name,
+		files: row.files
+	})),
+	total: rows.length
+})), Effect.orElseSucceed(() => ({
+	sample: [],
+	total: 0
+})));
+/**
 * Re-read every active file and collect its format warnings.
 *
 * Re-read rather than taken from the index, because a warning is not a stored column. The indexer
@@ -3671,6 +4301,7 @@ const repair = (root, findings, orphans) => Effect.gen(function* () {
 	let rewritten = 0;
 	let dropped = 0;
 	const touched = [];
+	const failedWrites = [];
 	for (const finding of findings) {
 		if (!isEdgeRel(finding.rel)) continue;
 		const rel = finding.rel;
@@ -3685,10 +4316,13 @@ const repair = (root, findings, orphans) => Effect.gen(function* () {
 		const edited = applyHeadEdits(html, edits);
 		if (edited === html) continue;
 		if (finding.rewriteTo === null) yield* Effect.logWarning(`doctor dropped a dangling ${rel} from ${finding.srcPath}: target has no file`);
-		yield* attemptIo(`doctor.write:${finding.srcPath}`, async () => {
+		if (!(yield* attemptIo(`doctor.write:${finding.srcPath}`, async () => {
 			await mkdir(dirname(absolute), { recursive: true });
 			await writeFile(absolute, edited, "utf8");
-		}).pipe(Effect.orElseSucceed(() => void 0));
+		}).pipe(Effect.as(true), Effect.orElseSucceed(() => false)))) {
+			failedWrites.push(finding.srcPath);
+			continue;
+		}
 		touched.push(finding.srcPath);
 		if (finding.rewriteTo === null) dropped += 1;
 		else rewritten += 1;
@@ -3709,6 +4343,7 @@ const repair = (root, findings, orphans) => Effect.gen(function* () {
 	return {
 		rewritten,
 		dropped,
+		failedWrites,
 		prunedAccessRows,
 		commitSha
 	};
@@ -3743,6 +4378,7 @@ const doctor = (options) => Effect.gen(function* () {
 	const taskDepth = yield* inboxTaskDepth(db);
 	const overdue = yield* overdueTasks(db, yield* todayDate);
 	const stale = yield* staleBlockers(db);
+	const untyped = yield* untypedEntities(db);
 	const active = yield* db.all("SELECT path FROM files WHERE archived = 0 ORDER BY path ASC").pipe(Effect.orElseSucceed(() => []));
 	const { warnings, unparseable } = yield* collectWarnings(git.root, active.map((row) => row.path));
 	const repaired = options.fix ? yield* repair(git.root, dangling, orphanAccessRows) : void 0;
@@ -3764,6 +4400,8 @@ const doctor = (options) => Effect.gen(function* () {
 		inboxTasksCrowded: taskDepth > 10,
 		overdueTasks: overdue,
 		staleBlockers: stale,
+		untypedEntities: untyped.sample,
+		untypedEntityTotal: untyped.total,
 		warnings,
 		unparseable,
 		indexFresh,
@@ -3784,8 +4422,7 @@ const doctor = (options) => Effect.gen(function* () {
 *
 * ROADMAP item 7 is the requirement. A multi-hop traversal written as code answers in one execution
 * what the tool path answers in one round trip per hop, and the closed vocabulary is what makes the
-* tree queryable without a new surface per question. Measured in the 2026-08 spike and
-* re-probed here on 2026-08-09: a 305-file
+* tree queryable without a new surface per question. Measured here: a 305-file
 * census in 598ms, and an edge walk resolving 410/410 edges into 201 chains, the longest 8 hops, in one
 * execution at 430ms.
 *
@@ -3818,7 +4455,7 @@ const DEFAULT_TIMEOUT_MS = 3e4;
 *
 * `maxJsTimeoutMs` is the only thing standing between a runaway guest loop and a `memhtml exec` that
 * never returns. The guest is a QuickJS worker with no host-side reaper of its own, and an unbounded
-* script would hold the CLI process open indefinitely. Probed 2026-08-09 with `maxJsTimeoutMs: 700`
+* script would hold the CLI process open indefinitely. Measured with `maxJsTimeoutMs: 700`
 * against `for(;;){n++}`: exit 124 at 724ms, "js-exec: Execution timeout: exceeded 700ms limit".
 */
 const MAX_TIMEOUT_MS = 6e5;
@@ -3835,7 +4472,7 @@ const SHELL_TIMEOUT_GRACE_MS = 2e3;
 *
 * QuickJS ships no base64 builtins and `node-html-parser` decodes a base64 entity table at load time,
 * so without this the parser throws "'atob' is not defined" at import and every script fails before
-* its first selector. Probed all three placements 2026-08-09: `bootstrap` works, prepending the shim
+* its first selector. Of the three possible placements, `bootstrap` works, prepending the shim
 * to the parser's own bytes works, and omitting it fails at `decodeBase64`. `bootstrap` is chosen
 * because it leaves the vendored parser byte-identical to the published artifact. A shim spliced into
 * the bundle would make the seeded file something no `pnpm` install reproduces.
@@ -3904,14 +4541,14 @@ const parserSourcePath = () => createRequire(import.meta.url).resolve("node-html
 * through the command and therefore a claim rather than a guard. As a function it is testable against
 * both strings just-bash actually produces.
 *
-* Both wordings, measured 2026-08-09 on `for(;;)` at a 400ms bound:
+* Both wordings, measured on `for(;;)` at a 400ms bound:
 *
 * - `maxJsTimeoutMs` fires: `js-exec: Execution timeout: exceeded 400ms limit`
 * - `maxExecutionTimeMs` fires: `bash: js-exec exceeded its execution deadline`, with no "timeout" in it
 *
 * A pattern matching only `/timeout/` therefore reports `timedOut: false` on a script that was cut off,
 * which is what the first version of this did. `aborted` covers `bash: execution aborted`, which is what
-* an `AbortSignal` produces (probed). This module takes no such path today, and classifying it correctly
+* an `AbortSignal` produces. This module takes no such path today, and classifying it correctly
 * now is cheap if it ever does.
 *
 * The exit code is required as well as the wording. 124 alone is reachable from a script that exits 124
@@ -3933,8 +4570,8 @@ const cutOffByTheRuntime = (exitCode, stderr) => exitCode === 124 && /timeout|de
 *
 * Neither is a fact about the corpus or the script. Both reach `stderr` as a thrown guest error, which
 * without this check is reported as the SCRIPT's non-zero exit — telling an agent its selector is wrong
-* when the sandbox merely failed to hand back a `stat`. Observed once on a 4-vCPU CI runner (2026-08-14,
-* `memhtml/memhtml` run 31830358200) on a walk of ~900 entries: `at isDirectory
+* when the sandbox merely failed to hand back a `stat`. Observed once on a 4-vCPU CI runner
+* on a walk of ~900 entries: `at isDirectory
 * (/workspace/lib/corpus.mjs:45:28): Error code: 0`, on a commit whose tree was byte-identical to one
 * that had passed minutes earlier. The bridge kept working afterwards — the guest's own `stderr` write
 * and exit both landed — so the fault is one operation, not a torn-down sandbox, which is what makes
@@ -3963,8 +4600,8 @@ const BRIDGE_ATTEMPTS = 3;
 * Run one attempt at a time until a report is the script's own answer, or fail as the runtime.
 *
 * Exported and parameterized by `attempt` because that is the only shape this loop can be tested in: a
-* bridge fault is a rare race — 72 executions under 3x CPU oversubscription did not produce one
-* (measured 2026-08-14) — so a test driving the real sandbox could not distinguish a working retry from
+* bridge fault is a rare race — 72 executions under 3x CPU oversubscription did not produce one —
+* so a test driving the real sandbox could not distinguish a working retry from
 * a fault that never fired. The injected attempt makes the loop's three claims falsifiable: a faulting
 * attempt is re-run, a script's own failure is NOT, and exhaustion is a typed failure.
 *
@@ -4004,7 +4641,7 @@ const withBridgeRetry = (attempt, attempts = 3) => Effect.gen(function* () {
 *
 * `new Bash()` is constructed with no `network` and no `fetch` option, so just-bash never registers its
 * network commands at all. Per `Bash.d.ts:80`: "Network commands (curl, wget) are registered when either
-* `fetch` or `network` is provided." Probed 2026-08-09 (`scripts/probe-sandbox-egress.mjs`): `curl` is
+* `fetch` or `network` is provided." `scripts/probe-sandbox-egress.mjs` demonstrates it: `curl` is
 * exit 127 "command not found", and the guest's `fetch` refuses on call with "Network access not
 * configured." `fetch` is a function there, so a `typeof` check on the global proves nothing. Eve
 * passes `dangerouslyAllowFullInternetAccess`, so the consolidator's sandbox does reach the network.
@@ -4035,7 +4672,7 @@ const runExec = (input) => Effect.gen(function* () {
 		catch: (cause) => StorageFailure.make({ operation: `exec.sandbox-load: ${String(cause)}` })
 	});
 	const { mountReadOnlyRoots } = yield* Effect.tryPromise({
-		try: () => import("./dist-DuzGralO.mjs"),
+		try: () => import("./dist-CBhYV3up.mjs"),
 		catch: (cause) => StorageFailure.make({ operation: `exec.mount-load: ${String(cause)}` })
 	});
 	const helperSource = yield* Effect.tryPromise({
@@ -4075,7 +4712,7 @@ const runExec = (input) => Effect.gen(function* () {
 		*
 		* `maxJsTimeoutMs` bounds the `js-exec` call and `maxExecutionTimeMs` bounds the whole shell
 		* invocation, so both are needed. A script cannot outlive its budget by spending the time
-		* outside the JS worker. Which one fires first changes the diagnostic, probed 2026-08-09 on a
+		* outside the JS worker. Which one fires first changes the diagnostic, measured on a
 		* `for(;;)` loop at a 400ms bound:
 		*
 		* | limits | exit | stderr |
@@ -4146,8 +4783,8 @@ const readScript = async (file) => {
 *
 * ## Why a pinned worktree and not `$MEMHTML_ROOT` itself
 *
-* A live `$MEMHTML_ROOT` contains `.memhtml/index.db`, and the guest ships `sqlite3`. Probed 2026-08-09
-* against a read-only `OverlayFs` over a directory holding a real database: `sqlite3
+* A live `$MEMHTML_ROOT` contains `.memhtml/index.db`, and the guest ships `sqlite3`. Against a
+* read-only `OverlayFs` over a directory holding a real database: `sqlite3
 * /mnt/memhtml/.memhtml/index.db 'select count(*) …'` returned the row, exit 0. Read-only is therefore no
 * barrier to a reader, and mounting the live root would hand every script the ranked planes this command
 * is scoped to exclude, through a door no `memhtml exec` flag opens.
@@ -4180,7 +4817,7 @@ const execCommand = (input) => Effect.gen(function* () {
 	* would not cover.
 	*/
 	const { pinCorpusSnapshot } = yield* Effect.tryPromise({
-		try: () => import("./dist-DuzGralO.mjs"),
+		try: () => import("./dist-CBhYV3up.mjs"),
 		catch: (cause) => StorageFailure.make({ operation: `exec.mount-load: ${String(cause)}` })
 	});
 	const snapshot = yield* Effect.acquireRelease(Effect.tryPromise({
@@ -4382,7 +5019,7 @@ const indexReport = () => Effect.gen(function* () {
 });
 const count = (db, sql) => db.get(sql).pipe(Effect.map((row) => row?.n ?? 0), Effect.orElseSucceed(() => 0));
 /**
-* A `--phases` value as a validated phase list, or `undefined` for "all sixteen".
+* A `--phases` value as a validated phase list, or `undefined` for every phase in `SLEEP_PHASES`.
 *
 * An unknown phase is rejected instead of dropped silently. A run asked for `--phases dedup,compress`
 * with a typo in the first name would otherwise execute only the second. `dedup-merge` is a hard
@@ -4421,6 +5058,41 @@ const sleepRunReport = (report) => ({
 //#region apps/cli/src/run.ts
 const KNOWN_FLAGS = /* @__PURE__ */ new Set([...GLOBAL_FLAGS.map((flag) => flag.name), ...COMMANDS.flatMap((command) => command.flags.map((flag) => flag.name))]);
 /**
+* Every flag name the spec table declares, mapped to the type it declares.
+*
+* **Only a `string` or `int` flag consumes the next argv token as its value**, and the two kinds it
+* excludes are excluded for different reasons:
+*
+* - A `boolean` flag takes `--flag`, `--flag=value`, or `--no-flag`, so the token after it stays
+*   positional and can be the command: `memhtml --dense list` is the `list` command, not an empty
+*   command carrying `dense: "list"`.
+* - A flag the table does not declare has no type to consult, and eating the token would swallow the
+*   command name — `memhtml --nope list` would answer the manifest at exit 0 instead of refusing an
+*   unknown flag. Leaving the token positional lets the command reach {@link validate}, which is
+*   where an unknown flag becomes exit 2.
+*
+* The map is name-keyed across every command even though validation is per-command, because the
+* parser runs before the command is known. That is sound only while one name carries ONE type
+* everywhere, which is a property of the table `cli.test.ts` enforces rather than a hope.
+*/
+const FLAG_TYPES = new Map([...GLOBAL_FLAGS, ...COMMANDS.flatMap((command) => command.flags)].map((flag) => [flag.name, flag.type]));
+/**
+* The tokens {@link bool} would have read as a boolean value.
+*
+* A boolean flag followed by one of these is a caller spelling `--flag <value>`, which parses as the
+* opposite value. Any other token after a boolean flag is a positional the caller meant — the
+* command name, a path, a query — so the set is exactly the vocabulary `bool` interprets and not
+* "any following token".
+*/
+const BOOLEAN_VALUE_TOKENS = /* @__PURE__ */ new Set([
+	"true",
+	"false",
+	"yes",
+	"no",
+	"0",
+	"1"
+]);
+/**
 * The two-word command names, longest first.
 *
 * A subcommand is matched greedily so `index status` beats `index`, and the leftover tokens become
@@ -4430,16 +5102,22 @@ const KNOWN_FLAGS = /* @__PURE__ */ new Set([...GLOBAL_FLAGS.map((flag) => flag.
 */
 const COMPOUND_NAMES = COMMAND_NAMES.filter((name) => name.includes(" ")).sort((left, right) => right.length - left.length);
 /**
-* `--flag value`, `--flag=value`, `--no-flag`, and bare `--flag`.
+* `--flag value`, `--flag=value`, `--no-flag`, and bare `--flag`, parsed against the spec table.
 *
 * Every flag's value is an array, because several flags are repeatable (`--tag`, `--entity`,
 * `--body`) and a map of scalars would silently keep only the last occurrence, so a write with three
 * entities would store one. Non-repeatable flags read `.at(-1)`, so a duplicate is last-wins rather
 * than an error, which is what a shell user retyping a flag expects.
+*
+* Only a flag the table types `string` or `int` consumes the next token as its value; a boolean flag
+* and an undeclared flag both leave it positional, for the two reasons {@link FLAG_TYPES} states.
+* A boolean flag followed by a value-shaped token is recorded as a stray so {@link validate} can
+* refuse it rather than silently inverting the caller's ask.
 */
 const parseArgv = (argv) => {
 	const positional = [];
 	const flags = /* @__PURE__ */ new Map();
+	const strayBooleanValues = [];
 	const push = (name, value) => {
 		const existing = flags.get(name);
 		if (existing === void 0) flags.set(name, [value]);
@@ -4462,11 +5140,13 @@ const parseArgv = (argv) => {
 				continue;
 			}
 			const next = argv[index + 1];
-			if (next !== void 0 && !next.startsWith("--")) {
+			const type = FLAG_TYPES.get(body);
+			if ((type === "string" || type === "int") && next !== void 0 && !next.startsWith("--")) {
 				push(body, next);
 				index += 2;
 				continue;
 			}
+			if (type === "boolean" && next !== void 0 && BOOLEAN_VALUE_TOKENS.has(next.toLowerCase())) strayBooleanValues.push([body, next]);
 			push(body, true);
 			index += 1;
 			continue;
@@ -4481,13 +5161,15 @@ const parseArgv = (argv) => {
 		return {
 			command: compound,
 			positional: positional.slice(consumed),
-			flags
+			flags,
+			strayBooleanValues
 		};
 	}
 	return {
 		command: positional[0] ?? "",
 		positional: positional.slice(1),
-		flags
+		flags,
+		strayBooleanValues
 	};
 };
 /** A flag's last value as a string, or `undefined` when it was not given. */
@@ -4524,6 +5206,7 @@ const scopeOf = (parsed) => ({
 	workspace: str(parsed, "workspace"),
 	tags: list(parsed, "tag"),
 	entity: str(parsed, "entity"),
+	facets: parseFacetFilters(list(parsed, "facet")),
 	includeArchived: bool(parsed, "include-archived", false),
 	asOf: str(parsed, "as-of")
 });
@@ -4534,6 +5217,25 @@ const provenanceOf = (parsed) => ({
 	turnUuid: str(parsed, "turn-uuid")
 });
 /**
+* Exit 1 when a sleep run has a failed phase.
+*
+* **A partially-failed run and a fully-aborted run exit the same**, and that is a decision rather
+* than an omission. A caller reading the exit code is asking one question — did the curation this
+* invocation was for happen — and both answers are no. The difference between them is already stated
+* in the payload, precisely: an abort is every selected phase `failed` with `headSha === baseSha` and
+* no commits, while a partial run names the phases that landed. A second exit code would be a
+* second, weaker copy of that, and a caller would have to learn it to recover a fact the envelope
+* already carries.
+*
+* Exit 1 rather than 2: the call was well-formed, so this is a runtime failure an operator fixes by
+* changing the repo or the environment ({@link EXIT_USAGE} is reserved for fixing the call).
+*
+* `sleep status` and `sleep review` are deliberately not routed through here. They REPORT a run they
+* did not perform, and a read that exited non-zero because the thing it describes failed would make
+* "tell me what happened" indistinguishable from "I could not tell you".
+*/
+const sleepExit = (report) => report.failedPhases.length > 0 ? 1 : 0;
+/**
 * Dispatch one parsed invocation against the provided services.
 *
 * Every arm is decode → call → name the response type. No arm builds an envelope, catches an error,
@@ -4560,6 +5262,7 @@ const dispatch = (parsed, applyOps = []) => {
 				articleHtml: str(parsed, "article-html"),
 				memoryType: str(parsed, "type") ?? "",
 				path: str(parsed, "path"),
+				strictPath: bool(parsed, "strict-path", false),
 				workspace: str(parsed, "workspace"),
 				tags: list(parsed, "tag"),
 				entities: list(parsed, "entity"),
@@ -4633,9 +5336,13 @@ const dispatch = (parsed, applyOps = []) => {
 			return ["memory.neighbors", yield* neighborsOf({
 				path: parsed.positional[0] ?? "",
 				depth: int(parsed, "depth"),
+				limit: int(parsed, "limit"),
 				rels: list(parsed, "rel")
 			})];
 		});
+		case "resolve": return Effect.gen(function* () {
+			return ["memory.resolved", yield* resolveMemory(parsed.positional[0] ?? "")];
+		});
 		case "archive": return Effect.gen(function* () {
 			return ["memory.archived", yield* archiveMemory(parsed.positional[0] ?? "", str(parsed, "reason") ?? "")];
 		});
@@ -4648,12 +5355,20 @@ const dispatch = (parsed, applyOps = []) => {
 				workspace: str(parsed, "workspace"),
 				tag: str(parsed, "tag"),
 				entity: str(parsed, "entity"),
+				facets: parseFacetFilters(list(parsed, "facet")),
 				para: str(parsed, "para"),
 				limit: int(parsed, "limit"),
 				cursor: str(parsed, "cursor"),
 				includeArchived: bool(parsed, "include-archived", false)
 			})];
 		});
+		case "entity activity": return Effect.gen(function* () {
+			return ["entity.activity", yield* entityActivity({
+				entityType: str(parsed, "type"),
+				limit: int(parsed, "limit"),
+				includeArchived: bool(parsed, "include-archived", false)
+			})];
+		});
 		case "task add": return Effect.gen(function* () {
 			const title = str(parsed, "title") ?? "";
 			const result = yield* writeMemory({
@@ -4735,16 +5450,29 @@ const dispatch = (parsed, applyOps = []) => {
 		case "sleep run": return Effect.gen(function* () {
 			const sleep = yield* Sleep;
 			const phases = yield* sleepPhases(str(parsed, "phases"));
+			const maxLlmCalls = int(parsed, "max-llm-calls");
 			const report = yield* sleep.run({
 				date: str(parsed, "date") ?? (yield* today),
 				...phases === void 0 ? {} : { phases },
-				dryRun: bool(parsed, "dry-run", false)
+				dryRun: bool(parsed, "dry-run", false),
+				deep: bool(parsed, "deep", false),
+				...maxLlmCalls === void 0 ? {} : { maxLlmCalls }
 			});
-			return ["sleep.report", sleepRunReport(report)];
+			const payload = sleepRunReport(report);
+			return [
+				"sleep.report",
+				payload,
+				sleepExit(payload)
+			];
 		});
 		case "sleep resume": return Effect.gen(function* () {
 			const report = yield* (yield* Sleep).resume(parsed.positional[0] ?? "");
-			return ["sleep.report", sleepRunReport(report)];
+			const payload = sleepRunReport(report);
+			return [
+				"sleep.report",
+				payload,
+				sleepExit(payload)
+			];
 		});
 		case "sleep review": return Effect.gen(function* () {
 			const report = yield* (yield* Sleep).review(parsed.positional[0]);
@@ -4773,6 +5501,17 @@ const dispatch = (parsed, applyOps = []) => {
 		case "state import": return Effect.gen(function* () {
 			return ["state.import", yield* stateImport()];
 		});
+		case "sleep plan": return Effect.gen(function* () {
+			const sleep = yield* Sleep;
+			/**
+			* The instant is read HERE and passed in, which keeps the one clock reading anywhere near sleep
+			* on the caller's side. The settled-transcript cutoff is derived from it, and a plan that read a
+			* clock inside the package would be the first thing in sleep that consults one to decide
+			* something.
+			*/
+			const millis = yield* Effect.clockWith((clock) => clock.currentTimeMillis);
+			return ["sleep.plan", yield* sleep.plan(millis)];
+		});
 		case "sleep status": return Effect.gen(function* () {
 			const report = yield* (yield* Sleep).review();
 			return ["sleep.report", {
@@ -4827,10 +5566,13 @@ const EITHER_CLAIM_OR_ARTICLE = /* @__PURE__ */ new Set(["write", "correct"]);
 *
 * Here for the reason `claimOrArticle` is: `validate`'s return becomes exit 2 and a failure raised in
 * `dispatch` becomes exit 1, so "you passed the wrong flags" must be decided before any service is
-* built. `.erpaval/solutions/api-patterns/xor-params-and-mcp-error-masking.md` records the rule.
+* built. Mutually exclusive parameters are refused at this edge, before dispatch, because a refusal
+* raised any later is masked as a runtime error
+* (`.erpaval/solutions/api-patterns/xor-params-and-mcp-error-masking.md`).
 *
 * At most one rather than exactly one, because zero doors is legal and means stdin, the same shape
-* `memhtml apply` has, where a bare invocation drains the pipe. A missing script is not a usage error
+* `memhtml apply` has, where a bare invocation drains the pipe. `--file -` is the flag spelling of
+* stdin and counts as no door at all. A missing script is not a usage error
 * here. An empty one is, and that check sits beside the read in {@link run} because reading is async.
 *
 * `--timeout-ms` is checked for a positive integer within the cap. Zero and negatives are refused
@@ -4839,19 +5581,33 @@ const EITHER_CLAIM_OR_ARTICLE = /* @__PURE__ */ new Set(["write", "correct"]);
 */
 const execFlags = (parsed) => {
 	if (parsed.command !== "exec") return void 0;
-	const doors = [str(parsed, "file") === void 0 ? void 0 : "--file", str(parsed, "script") === void 0 ? void 0 : "--script"].filter((door) => door !== void 0);
+	const file = str(parsed, "file");
+	const doors = [file === void 0 || file === "-" ? void 0 : "--file", str(parsed, "script") === void 0 ? void 0 : "--script"].filter((door) => door !== void 0);
 	if (doors.length > 1) return fail("ERR_INVALID_FLAG", "exec takes at most one of --file or --script, not both: two scripts cannot both be the one that runs", [
 		"memhtml exec --file traverse.mjs",
 		"memhtml exec --script 'console.log(1)'",
 		"cat s.mjs | memhtml exec"
 	]);
-	if (doors.length === 1 && parsed.positional[0] === "-") return fail("ERR_INVALID_FLAG", `exec cannot read stdin and ${doors[0]} in the same call: \`-\` names stdin as the script source`, ["cat s.mjs | memhtml exec", `memhtml exec ${doors[0]} …`]);
+	if (doors.length === 1 && (parsed.positional[0] === "-" || file === "-")) return fail("ERR_INVALID_FLAG", `exec cannot read stdin and ${doors[0]} in the same call: \`-\` names stdin as the script source`, ["cat s.mjs | memhtml exec", `memhtml exec ${doors[0]} …`]);
 	if (str(parsed, "timeout-ms") !== void 0) {
 		const timeout = int(parsed, "timeout-ms");
 		if (timeout === void 0 || timeout <= 0 || timeout > 6e5) return fail("ERR_INVALID_FLAG", `--timeout-ms must be a positive integer of at most ${MAX_TIMEOUT_MS}: a non-positive bound is no bound at all, which is the one thing a sandbox may not be`, [`memhtml exec --timeout-ms ${DEFAULT_TIMEOUT_MS}`]);
 	}
 };
 /**
+* `memhtml apply` takes at most one op-stream source.
+*
+* The same rule `execFlags` holds for a script, on the same two spellings: `-` (positional or as
+* `--file -`) names stdin, and stdin beside a real `--file` is two streams claiming to be the one
+* that applies. Refused here so the answer is exit 2, matching exec, rather than one of the
+* sources being silently ignored.
+*/
+const applyFlags = (parsed) => {
+	if (parsed.command !== "apply") return void 0;
+	const file = str(parsed, "file");
+	if (file !== void 0 && file !== "-" && parsed.positional[0] === "-") return fail("ERR_INVALID_FLAG", "apply cannot read stdin and --file in the same call: `-` names stdin as the op stream", ["cat ops.jsonl | memhtml apply", "memhtml apply --file ops.jsonl"]);
+};
+/**
 * Exactly one of `--claim` / `--article-html`.
 *
 * Checked here rather than in the dispatch arm, because the exit code is the contract. `validate`'s
@@ -4871,6 +5627,76 @@ const claimOrArticle = (parsed) => {
 	if (!hasClaim && !hasArticle) return fail("ERR_MISSING_ARGUMENT", `${parsed.command} requires exactly one of --claim or --article-html`, [`memhtml ${parsed.command} --claim <sentence>`, `memhtml ${parsed.command} --article-html '<p>…</p>'`]);
 };
 /**
+* `--as-of` must be a value the point-in-time comparison can order.
+*
+* The flag binds twice into `coalesce(valid_from, event_at, created_at) <= ? AND (valid_until IS
+* NULL OR valid_until > ?)` (`packages/index/src/scope.ts`), where SQLite compares TEXT to TEXT.
+* Nothing there parses the value, so an unsortable one does not error — it silently answers a
+* DIFFERENT question. `--as-of "2026-08-24 13:00"` sorts after every `T`-form instant on that day
+* and before none of them, so the window it selects is not the window the caller asked for, and the
+* result set looks like a plausible point-in-time view. A usage error is the only visible answer.
+*
+* The same {@link isValidDatetime} the format enforces on `<time datetime>` and on every datetime
+* meta, so the values a caller may ASK ABOUT are exactly the values a file may STATE. Two grammars
+* here would let a caller name an instant no memory can carry.
+*
+* `ERR_INVALID_FLAG`, this function's existing code for a flag present but unusable as given, and
+* exit 2 rather than a runtime error, because `validate`'s return is the usage path. A bare
+* `--as-of` with no value is refused for the same reason a bad one is: it reads as a scoped query
+* and would return an unscoped answer.
+*/
+const asOfFlag = (parsed) => {
+	if (parsed.flags.get("as-of") === void 0) return void 0;
+	const value = str(parsed, "as-of");
+	if (value !== void 0 && isValidDatetime(value)) return void 0;
+	return fail("ERR_INVALID_FLAG", `--as-of must be an ISO date or datetime (YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ)${value === void 0 ? "" : `, not "${value}"`}: the point-in-time window compares it as a string, so a value outside that grammar selects a different window rather than failing`, [`memhtml ${parsed.command} --as-of 2026-08-24`, `memhtml ${parsed.command} --as-of 2026-08-24T13:00:00Z`]);
+};
+/**
+* A boolean flag spelled with a space-separated value.
+*
+* `--embed false` parses as `embed: true` plus a positional `"false"`, so a caller asking to SKIP
+* embedding would get embedding on and a stray token nothing reads. That is a silent wrong answer,
+* which is the one outcome this surface may not produce, so the pair is exit 2 and the message names
+* both spellings that work.
+*
+* `ERR_INVALID_FLAG`, the code for a flag present but unusable as given, and the same code the
+* closed-vocabulary and `--as-of` checks return.
+*/
+const strayBooleanFlags = (parsed) => {
+	const stray = parsed.strayBooleanValues[0];
+	if (stray === void 0) return void 0;
+	const [name, token] = stray;
+	return fail("ERR_INVALID_FLAG", `--${name} is a boolean flag and takes no separate value, so \`--${name} ${token}\` reads as --${name} with a stray "${token}" argument`, [`memhtml ${parsed.command} --${name}=${token}`, `memhtml ${parsed.command} --no-${name}`]);
+};
+/**
+* The commands where a bare `-` positional names stdin rather than an argument.
+*
+* Both declare no positional argument and both document `-` as the spelling that reads the stream
+* from a pipe, so the dash is the caller doing what the flag description says rather than a surplus
+* token. Their own mutual-exclusion checks (`execFlags`, `applyFlags`) refuse a dash beside a real
+* `--file`.
+*/
+const STDIN_MARKER_COMMANDS = /* @__PURE__ */ new Set(["apply", "exec"]);
+/**
+* Positionals past what the command declares.
+*
+* The counterpart to the missing-argument check below: "absent" and "surplus" are both wrong calls
+* and both answer. Without this one a surplus positional is silently dropped — `memhtml read
+* a.html b.html` reads ONE memory and reports nothing about the second, and every mis-spelled
+* boolean value (`--embed false`) leaves one behind.
+*
+* A `repeatable` last argument turns the check off, because a variadic tail is what
+* `memhtml reinforce a.html b.html` is. That is declared in the table rather than listed here, so
+* the manifest states it and a future variadic command needs no edit to this function.
+*/
+const surplusArgs = (parsed, spec) => {
+	if (spec.args.at(-1)?.repeatable === true) return void 0;
+	const extra = parsed.positional.slice(spec.args.length).filter((token) => !(token === "-" && STDIN_MARKER_COMMANDS.has(spec.name)));
+	if (extra.length === 0) return void 0;
+	const shape = spec.args.length === 0 ? `${spec.name} takes no arguments` : `${spec.name} takes ${spec.args.length}: ${spec.args.map((arg) => arg.name).join(", ")}`;
+	return fail("ERR_UNEXPECTED_ARGUMENT", `unexpected argument: ${extra.map((token) => `"${token}"`).join(", ")}. ${shape}`, [`memhtml ${spec.name}${spec.args.map((arg) => ` <${arg.name}>`).join("")}`, "memhtml manifest"]);
+};
+/**
 * Validate a parsed invocation against its spec. Usage errors only; nothing here touches a service.
 *
 * Returning the failure rather than throwing keeps the exit code decision in one place. A usage
@@ -4878,9 +5704,21 @@ const claimOrArticle = (parsed) => {
 * have to know that too.
 */
 const validate = (parsed) => {
-	for (const name of parsed.flags.keys()) if (!KNOWN_FLAGS.has(name)) return fail("ERR_INVALID_FLAG", `unknown flag: --${name}`, nearest(name, [...KNOWN_FLAGS]));
 	const spec = COMMANDS.find((command) => command.name === parsed.command);
 	if (spec === void 0) return unknownCommand(parsed);
+	/**
+	* Flags are validated against THIS command's spec plus the true globals, not the union of every
+	* command's flags. A flag that is valid somewhere else is still a usage error here: an agent that
+	* typed `memhtml list --status todo` meant `task list`, and silently ignoring the flag would
+	* return an unfiltered answer that looks filtered. The suggestions are drawn from the whole known
+	* set, so a flag that belongs to another command still points somewhere.
+	*/
+	const allowed = /* @__PURE__ */ new Set([...GLOBAL_FLAGS.map((flag) => flag.name), ...spec.flags.map((flag) => flag.name)]);
+	for (const name of parsed.flags.keys()) if (!allowed.has(name)) return KNOWN_FLAGS.has(name) ? fail("ERR_INVALID_FLAG", `--${name} is not a flag of ${spec.name}`, COMMANDS.filter((command) => command.flags.some((flag) => flag.name === name)).slice(0, 3).map((command) => `memhtml ${command.name} --${name}`)) : fail("ERR_INVALID_FLAG", `unknown flag: --${name}`, nearest(name, [...allowed]));
+	const strayBoolean = strayBooleanFlags(parsed);
+	if (strayBoolean !== void 0) return strayBoolean;
+	const surplus = surplusArgs(parsed, spec);
+	if (surplus !== void 0) return surplus;
 	const missingArgs = spec.args.filter((arg, position) => arg.required && parsed.positional[position] === void 0);
 	if (missingArgs.length > 0) return fail("ERR_MISSING_ARGUMENT", `${spec.name} requires: ${missingArgs.map((arg) => arg.name).join(", ")}`, [`memhtml ${spec.name} <${missingArgs[0]?.name}>`]);
 	const missingFlags = spec.flags.filter((flag) => flag.required === true && parsed.flags.get(flag.name) === void 0);
@@ -4889,6 +5727,10 @@ const validate = (parsed) => {
 	if (eitherOr !== void 0) return eitherOr;
 	const exec = execFlags(parsed);
 	if (exec !== void 0) return exec;
+	const apply = applyFlags(parsed);
+	if (apply !== void 0) return apply;
+	const asOf = asOfFlag(parsed);
+	if (asOf !== void 0) return asOf;
 	/**
 	* A closed-vocabulary flag is checked here rather than at the service, so a typo answers with the
 	* whole vocabulary and never touches the database. Every value of a repeatable flag is checked, not
@@ -4969,22 +5811,23 @@ const run = async (argv, layer, stdin = readStdin) => {
 	* would open and migrate a store this command never queries, and an operator checking the gate is
 	* typically doing it while `memhtml-mcp` serves that store.
 	*
-	* **Exit 1 on a failed gate**, with `ERR_DISCRIMINATION_FAILED`. A gate that exited 0 and
-	* left the verdict inside the payload would be a gate every shell caller forgets to read. The
-	* exit code is what stops a pipeline.
+	* **Exit 1 on a failed gate**, with the `ERR_DISCRIMINATION_FAILED` FAILURE envelope. A gate
+	* that exited 0 and left the verdict inside the payload would be a gate every shell caller
+	* forgets to read, and a gate that exited 1 inside a success envelope would be one an agent
+	* branching on `code` never sees fail. The failure travels through `failureFor` like every other
+	* typed failure, so the code, the one-line reason, and the recovery suggestions are the
+	* documented ones.
 	*/
 	if (parsed.command === "eval discriminate") {
 		const requested = str(parsed, "mode") ?? "fake";
 		return Effect.runPromise(runDiscrimination({
 			mode: requested,
 			...int(parsed, "seed") === void 0 ? {} : { seed: int(parsed, "seed") },
+			...int(parsed, "now") === void 0 ? {} : { now: int(parsed, "now") },
 			...int(parsed, "size") === void 0 ? {} : { size: int(parsed, "size") },
 			...int(parsed, "probes") === void 0 ? {} : { probes: int(parsed, "probes") },
 			...num(parsed, "mrr-floor") === void 0 ? {} : { mrrFloor: num(parsed, "mrr-floor") }
-		}).pipe(Effect.map((outcome) => outcome.passed ? emit(succeed("eval.discrimination", outcome), 0) : {
-			stdout: render(succeed("eval.discrimination", outcome), dense),
-			exitCode: 1
-		}), Effect.catchCause((cause) => Effect.succeed(emit(fail("ERR_UNKNOWN", `unexpected failure: ${String(cause)}`, []), 1))), Effect.provideService(Logger.LogToStderr, true)));
+		}).pipe(Effect.map((outcome) => outcome.passed ? emit(succeed("eval.discrimination", outcome), 0) : emit(failureFor(new DiscriminationFailed(outcome)), 1)), Effect.catchCause((cause) => Effect.succeed(emit(fail("ERR_UNKNOWN", `unexpected failure: ${String(cause)}`, []), 1))), Effect.provideService(Logger.LogToStderr, true)));
 	}
 	/**
 	* `memhtml exec` does not build the app layer either, for the reason two commands over.
@@ -5006,7 +5849,8 @@ const run = async (argv, layer, stdin = readStdin) => {
 	*/
 	if (parsed.command === "exec") {
 		const inline = str(parsed, "script");
-		const file = parsed.positional[0] === "-" ? void 0 : str(parsed, "file");
+		const flagFile = str(parsed, "file");
+		const file = parsed.positional[0] === "-" || flagFile === "-" ? void 0 : flagFile;
 		const script = inline !== void 0 ? inline : file === void 0 ? await stdin() : await readScript(file);
 		if (typeof script !== "string") return emit(script, 2);
 		if (script.trim() === "") return emit(fail("ERR_MISSING_ARGUMENT", "exec needs a script: a blank one would report an empty answer rather than an error", [
@@ -5040,14 +5884,15 @@ const run = async (argv, layer, stdin = readStdin) => {
 	*/
 	let applyOps = [];
 	if (parsed.command === "apply") {
-		const file = parsed.positional[0] === "-" ? void 0 : str(parsed, "file");
+		const flagFile = str(parsed, "file");
+		const file = parsed.positional[0] === "-" || flagFile === "-" ? void 0 : flagFile;
 		const text = await applyText(file, stdin);
 		if (typeof text !== "string") return emit(text, 2);
 		const decoded = decodeApply(text);
 		if (!decoded.ok) return emit(decoded.failure, 2);
 		applyOps = decoded.ops;
 	}
-	const program = dispatch(parsed, applyOps).pipe(Effect.map(([type, data]) => emit(succeed(type, data), 0)), Effect.catch((error) => Effect.succeed(emit(failureFor(error), 1))), Effect.catchCause((cause) => Effect.succeed(emit(fail("ERR_UNKNOWN", `unexpected failure: ${String(cause)}`, []), 1))), Effect.provide(layer ?? layerApp(str(parsed, "repo"))), Effect.provideService(Logger.LogToStderr, true), Effect.scoped);
+	const program = dispatch(parsed, applyOps).pipe(Effect.map(([type, data, exitCode]) => emit(succeed(type, data), exitCode ?? 0)), Effect.catch((error) => Effect.succeed(emit(failureFor(error), 1))), Effect.catchCause((cause) => Effect.succeed(emit(fail("ERR_UNKNOWN", `unexpected failure: ${String(cause)}`, []), 1))), Effect.provide(layer ?? layerApp(str(parsed, "repo"))), Effect.provideService(Logger.LogToStderr, true), Effect.scoped);
 	return Effect.runPromise(program);
 };