@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/eval/runners/external-command.ts

@@ -1,13 +1,5 @@
 import { spawn } from "node:child_process";
 import { performance } from "node:perf_hooks";
-import {
-	addChaosObservations,
-	chaosMetricEntries,
-	createChaosFold,
-	EMPTY_CHAOS_OBSERVATION,
-	type EvalChaosObservation,
-	parseChaosMarker,
-} from "../metrics/chaos-stream.js";
 import {
 	addFleetLoopObservations,
 	createFleetLoopFold,
@@ -53,8 +45,6 @@ export interface ShellCommandResult {
 	usage: EvalTokenStreamUsage;
 	/** Wire-stream structural invariants folded live, for the same reason. */
 	streamInvariants: EvalStreamInvariants;
-	/** Strict SIGINT harness marker folded live from stdout. */
-	chaos: EvalChaosObservation;
 	fleetLoops: EvalFleetLoopObservation;
 	stderr: string;
 	wallTimeMs: number;
@@ -84,7 +74,6 @@ export async function runExternalCommandRunner(
 	// is reported as unmeasured, never as zero cost.
 	let usage = UNMEASURED_TOKEN_USAGE;
 	let streamInvariants = EMPTY_STREAM_INVARIANTS;
-	let chaos = EMPTY_CHAOS_OBSERVATION;
 	let fleetLoops = EMPTY_FLEET_LOOP_OBSERVATION;
 	for (const command of commands) {
 		const result = await runShellCommand(command, cwd, runner.timeoutMs ?? timeoutMs, env);
@@ -93,7 +82,6 @@ export async function runExternalCommandRunner(
 		wallTimeMs += result.wallTimeMs;
 		usage = addTokenStreamUsage(usage, result.usage);
 		streamInvariants = addStreamInvariants(streamInvariants, result.streamInvariants);
-		chaos = addChaosObservations(chaos, result.chaos);
 		fleetLoops = addFleetLoopObservations(fleetLoops, result.fleetLoops);
 		if (result.exitCode !== 0) {
 			return {
@@ -107,11 +95,10 @@ export async function runExternalCommandRunner(
 					"latency.wallMs": wallTimeMs,
 					...tokenMetricEntries(usage),
 					...streamInvariantMetrics(streamInvariants),
-					...chaosMetricEntries(chaos),
 					...fleetLoopMetricEntries(fleetLoops),
 					"verifier.exitCode": result.exitCode,
 				},
-				artifacts: chaosArtifacts(chaos),
+				artifacts: {},
 			};
 		}
 	}
@@ -126,11 +113,10 @@ export async function runExternalCommandRunner(
 			"latency.wallMs": wallTimeMs,
 			...tokenMetricEntries(usage),
 			...streamInvariantMetrics(streamInvariants),
-			...chaosMetricEntries(chaos),
 			...fleetLoopMetricEntries(fleetLoops),
 			"verifier.exitCode": 0,
 		},
-		artifacts: chaosArtifacts(chaos),
+		artifacts: {},
 	};
 }
 
@@ -150,7 +136,6 @@ export function runShellCommand(
 		const metricCapture = createJsonlMetricCapture();
 		const usageFold = createTokenUsageFold();
 		const streamFold = createStreamInvariantFold();
-		const chaosFold = createChaosFold();
 		const fleetLoopFold = createFleetLoopFold();
 		let timedOut = false;
 		let settled = false;
@@ -169,7 +154,6 @@ export function runShellCommand(
 			metricCapture.push(chunk);
 			usageFold.push(chunk);
 			streamFold.push(chunk);
-			chaosFold.push(chunk);
 			fleetLoopFold.push(chunk);
 		});
 		child.stderr.on("data", (chunk: string) => {
@@ -191,7 +175,6 @@ export function runShellCommand(
 				metricJsonl: metricCapture.finish(),
 				usage: usageFold.usage(),
 				streamInvariants: streamFold.invariants(),
-				chaos: chaosFold.observation(),
 				fleetLoops: fleetLoopFold.observation(),
 				stderr,
 				wallTimeMs: Math.round(performance.now() - started),
@@ -290,10 +273,6 @@ export function createJsonlMetricCapture(): JsonlMetricCapture {
 
 function compactMetricEvent(event: Record<string, unknown>): Record<string, unknown> | null {
 	const type = event.type;
-	if (type === "clio_soak_chaos") {
-		const marker = parseChaosMarker(event);
-		return marker === null ? null : { type, ...marker };
-	}
 	if (type === "tool_execution_start") {
 		const toolName = stringField(event, "toolName");
 		if (toolName !== "dispatch" && toolName !== "code_nav" && toolName !== "read" && toolName !== "grep") {
@@ -334,12 +313,6 @@ function compactMetricEvent(event: Record<string, unknown>): Record<string, unkn
 	};
 }
 
-function chaosArtifacts(observation: EvalChaosObservation): Record<string, string> {
-	return observation.markerCount === 1 && observation.marker !== null
-		? { chaosSeed: String(observation.marker.seed) }
-		: {};
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/domains/eval/schema/suite.ts

@@ -43,13 +43,6 @@ export const CANONICAL_METRICS = [
 	"evidence.verification",
 	"evidence.firstPassSuccess",
 	"cost.usd",
-	// Behavioral checkpoints for the bounded reconnaissance live suite.
-	"dispatch.count",
-	"wiki.staleAcknowledged",
-	// SIGINT chaos-harness facts folded live from its one strict stdout marker.
-	"chaos.seed",
-	"chaos.faultInjected",
-	"chaos.exitCode",
 	// Invariant checks: what Clio promised about its own machinery, read from
 	// the journal the item's run left behind. These are true or false about
 	// Clio and say nothing about whether the model solved the task. A check

package/src/domains/eval/suites/run.ts

@@ -126,7 +126,7 @@ async function runMatrixItem(
 			CLIO_CODER_ENTRY: clioEntry,
 		});
 		const patch = collectPatchMetrics(workspace.dir);
-		const receiptExitCode = receiptProcessExitCode(runner);
+		const receiptExitCode = runner.exitCode;
 		// Read after the runner returned and before the journal is removed: what
 		// Clio sealed for this item, judged against its own ledger, and whether
 		// the workers it attested are still running.
@@ -193,12 +193,6 @@ async function runMatrixItem(
 	}
 }
 
-/** A SIGINT harness exits cleanly after checking the nested Clio process; reconcile its receipt to that nested exit. */
-export function receiptProcessExitCode(runner: Pick<EvalRunnerOutput, "exitCode" | "metrics">): number {
-	const chaosExitCode = runner.metrics["chaos.exitCode"];
-	return typeof chaosExitCode === "number" && Number.isInteger(chaosExitCode) ? chaosExitCode : runner.exitCode;
-}
-
 /** Journal-derived invariants for one finished item, read from its isolated state directory. */
 function invariantMetrics(stateDir: string, runnerExitCode: number): Record<string, number | boolean> {
 	const journal = readRunJournal(stateDir);

package/src/domains/evidence/trust-status.ts

@@ -418,6 +418,7 @@ export type PersistedRunReceiptTrustFacts = Pick<RunReceipt, "runId"> &
 			RunReceipt,
 			| "integrity"
 			| "verification"
+			| "hostVerification"
 			| "quality"
 			| "validationGrounding"
 			| "briefing"
@@ -536,6 +537,12 @@ export function adaptRunReceiptValidationStatus(
 ): ValidationGroundingStatus {
 	if (receipt === null || receipt === undefined) return absentTrustStatus("artifact_missing");
 	const artifacts = validationArtifacts(receipt);
+	if (receipt.hostVerification?.status === "rejected") {
+		return attributed("failed", receiptSource(receipt), { kind: "validator", id: "host-verification" }, artifacts);
+	}
+	if (receipt.hostVerification?.status === "verified") {
+		return attributed("validated", receiptSource(receipt), { kind: "validator", id: "host-verification" }, artifacts);
+	}
 	if (qualityHasFailure(receipt.quality)) {
 		return attributed("failed", receiptSource(receipt), { kind: "validator", id: "receipt-quality" }, artifacts);
 	}
@@ -549,7 +556,9 @@ export function adaptRunReceiptValidationStatus(
 	if (qualityHasValidation(receipt.quality)) {
 		return attributed("validated", receiptSource(receipt), { kind: "validator", id: "receipt-quality" }, artifacts);
 	}
-	if (receipt.verification !== undefined) return verificationStatus(receipt.verification, receipt, artifacts);
+	if (receipt.verification !== undefined) {
+		return verificationStatus(receipt.verification, receipt, artifacts);
+	}
 	return attributed("unknown", compatibilitySource(receipt, "verification"), COMPATIBILITY_AUTHORITY, artifacts);
 }
 

package/src/domains/memory/index.ts

@@ -6,6 +6,20 @@ export {
 	rejectMemoryRecord,
 	selectApprovedMemory,
 } from "./operations.js";
+export {
+	applyScopeIdentity,
+	MEMORY_PROMOTION_SCOPES,
+	type MemoryPromotionScope,
+	type MemoryPromotionSource,
+	type MemoryPromotionSourceRedaction,
+	type MemoryScopeSelection,
+	memoryAgentIdentity,
+	memoryRecordFromPromotion,
+	memoryRuntimeIdentity,
+	memoryScopeIdentityKey,
+	proposeMemoryPromotion,
+	validateMemoryScopeSelection,
+} from "./promotion.js";
 export {
 	buildMemoryPromptSection,
 	MEMORY_PROMPT_DEFAULT_MAX_ITEMS,
@@ -46,7 +60,9 @@ export {
 	type TaskMemorySnapshot,
 } from "./task-bank.js";
 export {
+	type LegacyTaskMemoryHandoffSnapshot,
 	parseTaskMemoryHandoffSnapshot,
+	type ReviewedTaskMemoryHandoffSnapshot,
 	readNewestTaskMemoryHandoff,
 	renderTaskMemoryHandoffSnapshot,
 	renderTaskMemoryHandoffSource,
@@ -57,9 +73,11 @@ export {
 	type TaskMemoryHandoffArtifact,
 	type TaskMemoryHandoffEntry,
 	type TaskMemoryHandoffOffer,
+	type TaskMemoryHandoffRedaction,
 	type TaskMemoryHandoffSeedOutcome,
 	type TaskMemoryHandoffSeedResult,
 	type TaskMemoryHandoffSnapshot,
+	type TaskMemoryHandoffSourceProvenance,
 	taskMemoryHandoffSeedOffer,
 	taskMemoryHandoffSnapshot,
 } from "./task-memory-handoff.js";
@@ -112,12 +130,16 @@ export {
 	taskMemoryTracePath,
 } from "./task-memory-trace.js";
 export type {
+	MemoryAgentIdentity,
+	MemoryPromotionRedaction,
 	MemoryProposalResult,
 	MemoryPruneResult,
 	MemoryRecord,
+	MemoryRecordProvenance,
 	MemoryRecordValidationResult,
 	MemoryRepositoryIdentity,
 	MemoryRetrievalOptions,
+	MemoryRuntimeIdentity,
 	MemoryScope,
 	MemoryStatus,
 	MemoryStoreFile,

package/src/domains/memory/operations.ts

@@ -2,7 +2,13 @@ import { isAbsolute } from "node:path";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { ceilChars } from "../session/context-accounting.js";
 import { pruneStaleMemoryRecords, sortMemoryRecords, updateMemoryRecord } from "./store.js";
-import type { MemoryRecord, MemoryRepositoryIdentity, MemoryRetrievalOptions } from "./types.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRetrievalOptions,
+	MemoryRuntimeIdentity,
+} from "./types.js";
 
 export async function approveMemoryRecord(
 	dataDir: string,
@@ -31,12 +37,16 @@ export function selectApprovedMemory(
 	if (options.tokenBudget <= 0) return [];
 	const allowedScopes = options.scopes === undefined ? null : new Set(options.scopes);
 	const activeRepository = canonicalActiveRepository(options.activeRepository);
+	const activeRuntime = validActiveNamedIdentity(options.activeRuntime, "runtime");
+	const activeAgent = validActiveNamedIdentity(options.activeAgent, "agent");
 	const candidates = sortMemoryRecords(records)
 		.filter((record) => record.approved)
 		.filter((record) => record.evidenceRefs.length > 0)
 		.filter((record) => record.regressions === undefined || record.regressions.length === 0)
 		.filter((record) => allowedScopes === null || allowedScopes.has(record.scope))
 		.filter((record) => repositoryApplies(record, activeRepository))
+		.filter((record) => runtimeApplies(record, activeRuntime))
+		.filter((record) => agentApplies(record, activeAgent))
 		.sort(compareRetrievalPriority);
 	const selected: MemoryRecord[] = [];
 	let spent = 0;
@@ -55,6 +65,8 @@ export function estimateMemoryTokens(record: MemoryRecord): number {
 		record.key,
 		record.lesson,
 		...(record.repository === undefined ? [] : [record.repository.kind, record.repository.key]),
+		...(record.runtime === undefined ? [] : [record.runtime.kind, record.runtime.key]),
+		...(record.agent === undefined ? [] : [record.agent.kind, record.agent.key]),
 		...record.evidenceRefs,
 		...record.appliesWhen,
 		...record.avoidWhen,
@@ -80,6 +92,21 @@ function cloneRecord(record: MemoryRecord): MemoryRecord {
 	if (record.regressions !== undefined) next.regressions = [...record.regressions];
 	if (record.rejectedAt !== undefined) next.rejectedAt = record.rejectedAt;
 	if (record.repository !== undefined) next.repository = { ...record.repository };
+	if (record.runtime !== undefined) next.runtime = { ...record.runtime };
+	if (record.agent !== undefined) next.agent = { ...record.agent };
+	if (record.provenance !== undefined) {
+		next.provenance = {
+			...record.provenance,
+			...(record.provenance.redaction === undefined
+				? {}
+				: {
+						redaction: {
+							...record.provenance.redaction,
+							sourceFields: [...record.provenance.redaction.sourceFields],
+						},
+					}),
+		};
+	}
 	return next;
 }
 
@@ -115,6 +142,36 @@ function repositoryApplies(record: MemoryRecord, activeRepository: MemoryReposit
 	return record.repository.kind === activeRepository.kind && record.repository.key === activeRepository.key;
 }
 
+function runtimeApplies(record: MemoryRecord, activeRuntime: MemoryRuntimeIdentity | null): boolean {
+	if (record.scope !== "runtime") return true;
+	if (activeRuntime === null || record.runtime === undefined) return false;
+	return record.runtime.kind === activeRuntime.kind && record.runtime.key === activeRuntime.key;
+}
+
+function agentApplies(record: MemoryRecord, activeAgent: MemoryAgentIdentity | null): boolean {
+	if (record.scope !== "agent") return true;
+	if (activeAgent === null || record.agent === undefined) return false;
+	return record.agent.kind === activeAgent.kind && record.agent.key === activeAgent.key;
+}
+
+function validActiveNamedIdentity<T extends "runtime" | "agent">(
+	identity: { kind: T; key: string } | null | undefined,
+	kind: T,
+): { kind: T; key: string } | null {
+	if (
+		identity === null ||
+		identity === undefined ||
+		identity.kind !== kind ||
+		identity.key.length === 0 ||
+		identity.key.length > 256 ||
+		identity.key.trim() !== identity.key ||
+		/[\0\r\n\t ]/u.test(identity.key)
+	) {
+		return null;
+	}
+	return { kind, key: identity.key };
+}
+
 function isUsableAbsoluteRepositoryPath(value: string): boolean {
 	return value.length > 0 && !/[\0\r\n]/u.test(value) && isAbsolute(value);
 }

package/src/domains/memory/promotion.ts

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import { createRedactionTally, redactSecretsText } from "../evidence/redact.js";
+import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import { loadMemoryRecords, upsertMemoryRecord } from "./store.js";
+import type { TaskMemoryEntry, TaskMemoryRenderableClass } from "./task-bank.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryProposalResult,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRuntimeIdentity,
+} from "./types.js";
+import { validateMemoryRecord } from "./validate.js";
+
+export const MEMORY_PROMOTION_SCOPES = ["repo", "global", "runtime", "agent"] as const;
+export type MemoryPromotionScope = (typeof MEMORY_PROMOTION_SCOPES)[number];
+
+export type MemoryScopeSelection =
+	| { scope: "repo"; repository: MemoryRepositoryIdentity }
+	| { scope: "global"; acknowledgeGlobal: true }
+	| { scope: "runtime"; runtime: MemoryRuntimeIdentity }
+	| { scope: "agent"; agent: MemoryAgentIdentity };
+
+export interface MemoryPromotionSourceRedaction {
+	replacementCount: number;
+	sourceFields: ReadonlyArray<string>;
+}
+
+export interface MemoryPromotionSource {
+	kind: "task-bank-entry" | "handoff-snapshot";
+	sessionId: string;
+	evidenceRefs: ReadonlyArray<string>;
+	entry: TaskMemoryEntry;
+	runtimeIds?: ReadonlyArray<string>;
+	agentIds?: ReadonlyArray<string>;
+	redaction?: MemoryPromotionSourceRedaction;
+}
+
+interface ScopeSourceIdentities {
+	runtimeIds?: ReadonlyArray<string>;
+	agentIds?: ReadonlyArray<string>;
+}
+
+/**
+ * Validate an operator-selected scope without inferring or widening it.
+ * Runtime and agent scopes must name identities carried by the source.
+ */
+export function validateMemoryScopeSelection(
+	selection: MemoryScopeSelection,
+	source: ScopeSourceIdentities,
+): MemoryScopeSelection {
+	switch (selection.scope) {
+		case "repo": {
+			const repository = canonicalMemoryRepositoryIdentity(selection.repository.key);
+			if (
+				selection.repository.kind !== "canonical-path" ||
+				repository === null ||
+				repository.key !== selection.repository.key
+			) {
+				throw new Error("repo scope requires an existing canonical absolute repository identity");
+			}
+			return { scope: "repo", repository };
+		}
+		case "global":
+			if (selection.acknowledgeGlobal !== true) {
+				throw new Error("global scope requires a separate operator acknowledgement");
+			}
+			return selection;
+		case "runtime": {
+			const runtime = normalizeNamedIdentity(selection.runtime, "runtime");
+			if (!(source.runtimeIds ?? []).includes(runtime.key)) {
+				throw new Error(`runtime identity '${runtime.key}' does not match the promotion source`);
+			}
+			return { scope: "runtime", runtime };
+		}
+		case "agent": {
+			const agent = normalizeNamedIdentity(selection.agent, "agent");
+			if (!(source.agentIds ?? []).includes(agent.key)) {
+				throw new Error(`agent identity '${agent.key}' does not match the promotion source`);
+			}
+			return { scope: "agent", agent };
+		}
+	}
+}
+
+export function memoryRuntimeIdentity(key: string): MemoryRuntimeIdentity {
+	return normalizeNamedIdentity({ kind: "runtime", key }, "runtime");
+}
+
+export function memoryAgentIdentity(key: string): MemoryAgentIdentity {
+	return normalizeNamedIdentity({ kind: "agent", key }, "agent");
+}
+
+/** Create one reviewable proposal from a selected non-private task-bank entry. */
+export async function proposeMemoryPromotion(
+	dataDir: string,
+	source: MemoryPromotionSource,
+	selection: MemoryScopeSelection,
+	now: Date = new Date(),
+): Promise<MemoryProposalResult> {
+	validatePromotionSource(source);
+	const validatedScope = validateMemoryScopeSelection(selection, {
+		runtimeIds: source.runtimeIds ?? [],
+		agentIds: source.agentIds ?? [],
+	});
+	const record = memoryRecordFromPromotion(source, validatedScope, now);
+	const existing = (await loadMemoryRecords(dataDir)).find((candidate) => candidate.id === record.id);
+	if (existing !== undefined) return { record: existing, created: false };
+	await upsertMemoryRecord(dataDir, record);
+	return { record, created: true };
+}
+
+export function memoryRecordFromPromotion(
+	source: MemoryPromotionSource,
+	selection: MemoryScopeSelection,
+	now: Date = new Date(),
+): MemoryRecord {
+	validatePromotionSource(source);
+	const entryKind = source.entry.kind;
+	if (entryKind === "status") throw new Error("private task-memory status cannot be promoted");
+	const validatedScope = validateMemoryScopeSelection(selection, {
+		runtimeIds: source.runtimeIds ?? [],
+		agentIds: source.agentIds ?? [],
+	});
+	const tally = createRedactionTally();
+	const lesson = redactPromotionText(source.entry.content, tally).replace(/\s+/gu, " ").trim();
+	const sourceFields = new Set(source.redaction?.sourceFields ?? []);
+	if (lesson !== source.entry.content) sourceFields.add("content");
+	const replacementCount = (source.redaction?.replacementCount ?? 0) + tally.count;
+	const scopeKey = memoryScopeIdentityKey(validatedScope);
+	const record: MemoryRecord = {
+		id: promotedMemoryId({
+			sourceKind: source.kind,
+			sessionId: source.sessionId,
+			entryId: source.entry.id,
+			entryKind,
+			evidenceRefs: uniqueStrings(source.evidenceRefs),
+			lesson,
+			scopeKey,
+		}),
+		scope: validatedScope.scope,
+		key: `promotion:${source.kind}:${source.sessionId}:${source.entry.id}`,
+		lesson,
+		evidenceRefs: uniqueStrings(source.evidenceRefs),
+		appliesWhen: scopeApplicability(validatedScope),
+		avoidWhen: [],
+		confidence: 0.6,
+		createdAt: now.toISOString(),
+		approved: false,
+		provenance: {
+			sourceKind: source.kind,
+			sourceSessionId: source.sessionId,
+			sourceEntryId: source.entry.id,
+			sourceEntryKind: entryKind,
+			sourceEntryCreatedAt: source.entry.createdAt,
+			sourceEntryLastTouchedAt: source.entry.lastTouchedAt,
+			redaction: {
+				appliedBeforePersistence: true,
+				replacementCount,
+				sourceFields: [...sourceFields].sort(compareStrings),
+			},
+		},
+	};
+	applyScopeIdentity(record, validatedScope);
+	const validated = validateMemoryRecord(record);
+	if (!validated.valid) {
+		throw new Error(
+			`promoted memory record invalid: ${validated.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+		);
+	}
+	return validated.record;
+}
+
+export function applyScopeIdentity(record: MemoryRecord, selection: MemoryScopeSelection): void {
+	if (selection.scope === "repo") record.repository = { ...selection.repository };
+	if (selection.scope === "runtime") record.runtime = { ...selection.runtime };
+	if (selection.scope === "agent") record.agent = { ...selection.agent };
+}
+
+export function memoryScopeIdentityKey(selection: MemoryScopeSelection): string {
+	switch (selection.scope) {
+		case "repo":
+			return `repo:${selection.repository.kind}:${selection.repository.key}`;
+		case "global":
+			return "global:acknowledged";
+		case "runtime":
+			return `runtime:${selection.runtime.key}`;
+		case "agent":
+			return `agent:${selection.agent.key}`;
+	}
+}
+
+function validatePromotionSource(source: MemoryPromotionSource): void {
+	if (!validSourceValue(source.sessionId)) throw new Error("promotion requires a valid source session id");
+	if (source.evidenceRefs.length === 0 || source.evidenceRefs.some((value) => !validSourceValue(value))) {
+		throw new Error("promotion requires at least one valid source evidence ref");
+	}
+	if (source.entry.kind === "status") throw new Error("private task-memory status cannot be promoted");
+	if (source.entry.kind !== "knowledge" && source.entry.kind !== "procedural") {
+		throw new Error("promotion requires a knowledge or procedural task-memory entry");
+	}
+	if (!validSourceValue(source.entry.id) || source.entry.content.trim().length === 0) {
+		throw new Error("promotion requires a valid task-memory entry");
+	}
+	for (const runtimeId of source.runtimeIds ?? []) memoryRuntimeIdentity(runtimeId);
+	for (const agentId of source.agentIds ?? []) memoryAgentIdentity(agentId);
+	if (source.redaction !== undefined) {
+		if (!Number.isInteger(source.redaction.replacementCount) || source.redaction.replacementCount < 0) {
+			throw new Error("promotion source redaction count must be a non-negative integer");
+		}
+		if (source.redaction.sourceFields.some((field) => !validSourceValue(field))) {
+			throw new Error("promotion source redaction fields must be valid non-empty strings");
+		}
+	}
+}
+
+function normalizeNamedIdentity<T extends "runtime" | "agent">(
+	identity: { kind: T; key: string },
+	kind: T,
+): { kind: T; key: string } {
+	if (identity.kind !== kind || !validNamedIdentityKey(identity.key)) {
+		throw new Error(`${kind} scope requires a valid ${kind} identity`);
+	}
+	return { kind, key: identity.key };
+}
+
+function validNamedIdentityKey(value: string): boolean {
+	return value.length > 0 && value.length <= 256 && value.trim() === value && !/[\0\r\n\t ]/u.test(value);
+}
+
+function validSourceValue(value: string): boolean {
+	return value.length > 0 && value.length <= 1_024 && value.trim() === value && !/[\0\r\n]/u.test(value);
+}
+
+function scopeApplicability(selection: MemoryScopeSelection): string[] {
+	switch (selection.scope) {
+		case "repo":
+			return [`repository:${selection.repository.kind}:${selection.repository.key}`];
+		case "global":
+			return [];
+		case "runtime":
+			return [`runtime:${selection.runtime.key}`];
+		case "agent":
+			return [`agent:${selection.agent.key}`];
+	}
+}
+
+function promotedMemoryId(value: {
+	sourceKind: MemoryPromotionSource["kind"];
+	sessionId: string;
+	entryId: string;
+	entryKind: TaskMemoryRenderableClass;
+	evidenceRefs: string[];
+	lesson: string;
+	scopeKey: string;
+}): string {
+	const digest = createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex").slice(0, 16);
+	return `mem-${digest}`;
+}
+
+function uniqueStrings(values: ReadonlyArray<string>): string[] {
+	return [...new Set(values)].sort(compareStrings);
+}
+
+function redactPromotionText(text: string, tally: ReturnType<typeof createRedactionTally>): string {
+	const markers: string[] = [];
+	const masked = text.replace(/\[redacted:[a-z-]+\]/gu, (marker) => {
+		const token = `\uE000${String.fromCharCode(0xe100 + markers.length)}`;
+		markers.push(marker);
+		return token;
+	});
+	let redacted = redactSecretsText(masked, tally);
+	for (let index = 0; index < markers.length; index += 1) {
+		redacted = redacted.replaceAll(`\uE000${String.fromCharCode(0xe100 + index)}`, markers[index] ?? "");
+	}
+	return redacted;
+}
+
+function compareStrings(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/domains/memory/prompt-section.ts

@@ -1,5 +1,11 @@
 import { estimateMemoryTokens, selectApprovedMemory } from "./operations.js";
-import type { MemoryRecord, MemoryRepositoryIdentity, MemoryScope } from "./types.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRuntimeIdentity,
+	MemoryScope,
+} from "./types.js";
 
 export const MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET = 400;
 export const MEMORY_PROMPT_DEFAULT_MAX_ITEMS = 5;
@@ -20,6 +26,10 @@ export interface MemoryPromptOptions {
 	maxItems?: number;
 	/** Missing or unknown identity leaves global memory eligible but excludes repo memory. */
 	activeRepository?: MemoryRepositoryIdentity | null;
+	/** Missing or unknown identity excludes runtime-scoped memory. */
+	activeRuntime?: MemoryRuntimeIdentity | null;
+	/** Missing or unknown identity excludes agent-scoped memory. */
+	activeAgent?: MemoryAgentIdentity | null;
 }
 
 /**
@@ -40,6 +50,8 @@ export function selectMemoryForPrompt(
 		scopes,
 		tokenBudget,
 		activeRepository: options.activeRepository ?? null,
+		activeRuntime: options.activeRuntime ?? null,
+		activeAgent: options.activeAgent ?? null,
 	});
 	return selected.slice(0, maxItems);
 }
@@ -67,11 +79,19 @@ export function renderMemoryPromptSection(records: ReadonlyArray<MemoryRecord>):
 }
 
 function renderApplicability(record: MemoryRecord): string {
-	if (record.scope !== "repo") return `scope=${record.scope}`;
-	if (record.repository !== undefined) {
-		return `scope=repo, repository=${JSON.stringify(`${record.repository.kind}:${record.repository.key}`)}`;
+	if (record.scope === "repo") {
+		if (record.repository !== undefined) {
+			return `scope=repo, repository=${JSON.stringify(`${record.repository.kind}:${record.repository.key}`)}`;
+		}
+		return "scope=repo, repository=unknown";
 	}
-	return "scope=repo, repository=unknown";
+	if (record.scope === "runtime") {
+		return `scope=runtime, runtime=${JSON.stringify(record.runtime?.key ?? "unknown")}`;
+	}
+	if (record.scope === "agent") {
+		return `scope=agent, agent=${JSON.stringify(record.agent?.key ?? "unknown")}`;
+	}
+	return `scope=${record.scope}`;
 }
 
 /** Convenience for callers that want a single end-to-end build step. */