@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/lifecycle/migrations/2026-08-18-lmstudio-runtime-id.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+
+import { readSettings, settingsPath, updateSettings } from "../../../core/config.js";
+import { authStoragePath } from "../../providers/auth/backend-file.js";
+import { openAuthStorage } from "../../providers/auth/index.js";
+import type { Migration } from "./index.js";
+
+function normalizeLmStudioUrl(url: string | undefined): string | undefined {
+	if (!url) return url;
+	if (url.startsWith("ws://")) return `http://${url.slice("ws://".length)}`;
+	if (url.startsWith("wss://")) return `https://${url.slice("wss://".length)}`;
+	return url;
+}
+
+const migration: Migration = {
+	id: "2026-08-18-lmstudio-runtime-id",
+	async up(): Promise<void> {
+		let keepLegacyCredential = false;
+		if (existsSync(settingsPath())) {
+			const current = readSettings();
+			keepLegacyCredential = current.targets.some((target) => target.auth?.apiKeyRef === "lmstudio-native");
+			const needsSettingsRewrite = current.targets.some(
+				(target) =>
+					target.runtime === "lmstudio-native" ||
+					((target.runtime === "lmstudio" || target.runtime === "lmstudio-native") &&
+						normalizeLmStudioUrl(target.url) !== target.url),
+			);
+			if (needsSettingsRewrite) {
+				updateSettings((settings) => {
+					for (const target of settings.targets) {
+						if (target.runtime !== "lmstudio-native" && target.runtime !== "lmstudio") continue;
+						target.runtime = "lmstudio";
+						const url = normalizeLmStudioUrl(target.url);
+						if (url !== undefined) target.url = url;
+					}
+				});
+			}
+		}
+		if (!existsSync(authStoragePath())) return;
+		// Only reach for the rename when a legacy credential is actually stored.
+		// Most homes this migration runs on never held one, and asking the store
+		// to rename nothing is work that can only fail: it takes the credentials
+		// lock and, before this guard existed, refused outright on a file the
+		// parser could not fully read, which failed every later `clio-coder
+		// upgrade` on that machine.
+		const storage = openAuthStorage();
+		if (!storage.hasStored("lmstudio-native")) return;
+		storage.renameProvider("lmstudio-native", "lmstudio", { keepSource: keepLegacyCredential });
+	},
+};
+
+export default migration;

package/src/domains/lifecycle/migrations/index.ts

@@ -0,0 +1,114 @@
+/**
+ * Clio Coder state migration runner.
+ *
+ * A migration is a versioned state-shape change keyed by a stable id of the
+ * form `YYYY-MM-DD-<slug>`. The registry is a static, ordered list compiled
+ * into the bundle so the runtime never scans the filesystem for migration
+ * files. To add a migration, author `YYYY-MM-DD-<slug>.ts` with a default
+ * export matching the `Migration` contract and register it below.
+ *
+ * Applied migration ids are persisted to `<stateDir>/migrations.json`. A
+ * migration whose id already appears in that manifest is skipped. `up()` is
+ * invoked at most once per Clio Coder state tree for a given id.
+ *
+ * The registry ships empty pre-launch. Requirements for future migrations:
+ *
+ * 1. A migration that writes settings.yaml must hold the settings
+ *    single-writer lock (`withSettingsLock` in core/config.ts) around its
+ *    read-rewrite-write so it can never race `updateSettings`, and should
+ *    land the write through the atomic rename writer
+ *    (core/safe-resource-write.ts) so readers never see a partial file.
+ * 2. Migrations are authored against the shapes the code has on the day they
+ *    are needed, never against stale pre-release shapes.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import lmStudioRuntimeId from "./2026-08-18-lmstudio-runtime-id.js";
+
+export interface Migration {
+	id: string;
+	up(stateDir: string): Promise<void>;
+}
+
+export interface MigrationManifest {
+	applied: string[];
+}
+
+export interface MigrationRunResult {
+	/** ids newly applied on this invocation (in order). */
+	applied: string[];
+	/** every id recorded in the manifest after this invocation. */
+	allApplied: string[];
+	/** full migration inventory ordered by id. */
+	available: string[];
+}
+
+const REGISTRY: ReadonlyArray<Migration> = Object.freeze([lmStudioRuntimeId]);
+
+export function listMigrations(): ReadonlyArray<Migration> {
+	return REGISTRY;
+}
+
+function manifestPath(stateDir: string): string {
+	return join(stateDir, "migrations.json");
+}
+
+function readManifest(path: string): MigrationManifest {
+	if (!existsSync(path)) return { applied: [] };
+	try {
+		const raw = readFileSync(path, "utf8");
+		const parsed = JSON.parse(raw) as unknown;
+		if (parsed && typeof parsed === "object" && Array.isArray((parsed as { applied?: unknown }).applied)) {
+			const ids = (parsed as { applied: unknown[] }).applied.filter((v): v is string => typeof v === "string");
+			return { applied: ids };
+		}
+	} catch {
+		// fall through; treat unreadable manifest as empty
+	}
+	return { applied: [] };
+}
+
+function writeManifest(path: string, manifest: MigrationManifest): void {
+	writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", mode: 0o644 });
+}
+
+/**
+ * Apply every registered migration this state tree has not recorded yet.
+ *
+ * `migrations` defaults to the compiled registry and exists so the ordering
+ * guarantee below can be exercised against a failing migration; production
+ * callers pass one argument.
+ */
+export async function runPending(
+	stateDir: string,
+	migrations: ReadonlyArray<Migration> = REGISTRY,
+): Promise<MigrationRunResult> {
+	mkdirSync(stateDir, { recursive: true });
+	const path = manifestPath(stateDir);
+	const manifest = readManifest(path);
+	const applied = new Set(manifest.applied);
+	const newlyApplied: string[] = [];
+	// The manifest is written after each `up()` rather than once at the end. A
+	// throw from a later migration used to discard the record of the earlier ones
+	// that had already succeeded, so they re-ran on the next upgrade against a
+	// tree they had already changed. That breaks the at-most-once guarantee this
+	// module's contract states.
+	for (const m of migrations) {
+		if (applied.has(m.id)) continue;
+		await m.up(stateDir);
+		applied.add(m.id);
+		newlyApplied.push(m.id);
+		writeManifest(path, { applied: [...applied] });
+	}
+	const allApplied = [...applied];
+	// Nothing pending still rewrites the manifest, so a home whose file was
+	// missing or unparseable gains a well-formed one.
+	writeManifest(path, { applied: allApplied });
+	return {
+		applied: newlyApplied,
+		allApplied,
+		available: migrations.map((m) => m.id),
+	};
+}

package/src/domains/lifecycle/state.ts

@@ -0,0 +1,93 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { initializeClioHome } from "../../core/init.js";
+import { clioStatePath } from "../../core/xdg.js";
+
+export interface StateInfo {
+	version: string;
+	/** Absent when this record was rebuilt over a state root whose install time was gone. */
+	installedAt?: string;
+	upgradedAt?: string;
+	/** When the record itself was rebuilt. Never the same claim as an install. */
+	repairedAt?: string;
+	/** The version on record before the most recent version change. */
+	upgradedFrom?: string;
+	/** The version whose upgrade notice has already been shown once. */
+	noticedVersion?: string;
+	platform: string;
+	nodeVersion: string;
+}
+
+export interface UpgradeTransition {
+	from: string;
+	to: string;
+}
+
+export interface StateInfoRead {
+	info: StateInfo | null;
+	/**
+	 * Why the metadata could not be read, or null when it is absent or fine.
+	 * Absent and unreadable are different problems with different remedies, and
+	 * collapsing both to null had `clio-coder doctor` report "state metadata missing"
+	 * for an install.json that was present and merely mode 000, then send the
+	 * user to a `--fix` that dies on EACCES.
+	 */
+	problem: string | null;
+}
+
+export function readStateInfoResult(): StateInfoRead {
+	const path = join(clioStatePath(), "install.json");
+	try {
+		return { info: JSON.parse(readFileSync(path, "utf8")) as StateInfo, problem: null };
+	} catch (error) {
+		// `existsSync` cannot carry this distinction: it answers false for a
+		// genuinely absent file and for one sitting behind a directory the process
+		// may not traverse. Only ENOENT means the metadata was never written.
+		const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+		if (code === "ENOENT") return { info: null, problem: null };
+		const message = error instanceof Error ? error.message : String(error);
+		return { info: null, problem: `${path} could not be read: ${message}` };
+	}
+}
+
+export function readStateInfo(): StateInfo | null {
+	return readStateInfoResult().info;
+}
+
+export function ensureClioState(): StateInfo {
+	initializeClioHome();
+	const info = readStateInfo();
+	if (!info) throw new Error("state metadata was not written by initializeClioHome()");
+	return info;
+}
+
+/**
+ * The version transition the operator has not been told about yet, or null.
+ * `initializeClioHome` refreshes `install.json` silently on every boot, so by
+ * the time anything can speak the record already says the current version;
+ * `upgradedFrom` is what remembers where it came from. Claiming the notice
+ * stamps `noticedVersion`, so it is shown once per version and never again.
+ * A record without an `upgradedFrom`, or one already noticed, yields null and
+ * writes nothing.
+ */
+export function takeUpgradeNotice(): UpgradeTransition | null {
+	const path = join(clioStatePath(), "install.json");
+	let raw: Record<string, unknown>;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		raw = parsed as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+	const { version, upgradedFrom, noticedVersion } = raw;
+	if (typeof version !== "string" || typeof upgradedFrom !== "string") return null;
+	if (upgradedFrom === version || noticedVersion === version) return null;
+	try {
+		writeFileSync(path, `${JSON.stringify({ ...raw, noticedVersion: version }, null, 2)}\n`, "utf8");
+	} catch {
+		// A record that cannot be rewritten still gets its notice; it will repeat
+		// on the next boot, which is the lesser wrong against staying silent.
+	}
+	return { from: upgradedFrom, to: version };
+}

package/src/domains/lifecycle/upgrade-notice.ts

@@ -0,0 +1,35 @@
+/**
+ * The one line the first interactive launch after an upgrade says.
+ *
+ * `install.json` is refreshed silently on every boot, so without this the
+ * operator who installed 0.3.0 and ran `npm install -g` again would never be
+ * told the version moved or that anything at the keyboard changed. This is one
+ * sentence per release, for changes an interactive operator meets by typing
+ * (a command that now opens elsewhere, a skill that no longer answers), and a
+ * pointer to the shipped CHANGELOG for the rest. It is not a release-notes
+ * system: a release without a keyboard-facing change gets no entry and the
+ * generic line.
+ */
+
+import type { UpgradeTransition } from "./state.js";
+
+const KEYBOARD_FACING_CHANGES: Readonly<Record<string, string>> = Object.freeze({
+	"0.3.1":
+		"/targets, /fleet, and /scoped-models now open inside /settings; " +
+		"the commit-crafting, create-pr, investigate-issue, and review-changes skills are retired in favour of file-ticket, fix-issue, and ship; " +
+		"artifact defaults write under .clio-coder/artifacts/.",
+});
+
+/**
+ * Word choice is load-bearing: the footer classifies a plain string by its
+ * text, and "changed" is what makes this a sticky, dismissable notice rather
+ * than one that fades in twelve seconds while the operator is still reading.
+ */
+export function describeUpgradeNotice(transition: UpgradeTransition): string {
+	const changes = KEYBOARD_FACING_CHANGES[transition.to];
+	const head = `clio: upgraded ${transition.from} → ${transition.to}.`;
+	const tail = `Full notes: CHANGELOG.md, section ${transition.to}.`;
+	return changes === undefined
+		? `${head} What changed is in CHANGELOG.md, section ${transition.to}.`
+		: `${head} What changed at the keyboard: ${changes} ${tail}`;
+}

package/src/domains/lifecycle/version.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { PI_MONO_PACKAGES } from "../../engine/pi-mono-names.js";
+
+interface PackageJsonShape {
+	version?: string;
+	dependencies?: Record<string, string>;
+}
+
+let cached: VersionInfo | null = null;
+
+export interface VersionInfo {
+	clio: string;
+	node: string;
+	platform: string;
+	piAgentCore: string | null;
+	piAi: string | null;
+	piTui: string | null;
+}
+
+export function getVersionInfo(): VersionInfo {
+	if (cached) return cached;
+	const root = resolvePackageRoot();
+	const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as PackageJsonShape;
+	cached = {
+		clio: pkg.version ?? "0.0.0",
+		node: process.version,
+		platform: `${process.platform}-${process.arch}`,
+		piAgentCore: pkg.dependencies?.[PI_MONO_PACKAGES.agentCore] ?? null,
+		piAi: pkg.dependencies?.[PI_MONO_PACKAGES.ai] ?? null,
+		piTui: pkg.dependencies?.[PI_MONO_PACKAGES.tui] ?? null,
+	};
+	return cached;
+}

package/src/domains/memory/index.ts

@@ -0,0 +1,128 @@
+export {
+	approveMemoryRecord,
+	canonicalMemoryRepositoryIdentity,
+	estimateMemoryTokens,
+	pruneStaleMemory,
+	rejectMemoryRecord,
+	selectApprovedMemory,
+} from "./operations.js";
+export {
+	buildMemoryPromptSection,
+	MEMORY_PROMPT_DEFAULT_MAX_ITEMS,
+	MEMORY_PROMPT_DEFAULT_SCOPES,
+	MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET,
+	type MemoryPromptOptions,
+	renderMemoryPromptSection,
+	selectMemoryForPrompt,
+} from "./prompt-section.js";
+export {
+	memoryIdFromEvidence,
+	memoryRecordFromEvidence,
+	proposeMemoryFromEvidence,
+} from "./proposal.js";
+export {
+	loadMemoryRecords,
+	loadMemoryRecordsSync,
+	MEMORY_STALE_APPROVED_DAYS,
+	MEMORY_STALE_UNAPPROVED_DAYS,
+	MEMORY_STORE_MAX_RECORDS,
+	memoryRoot,
+	memoryStatus,
+	memoryStorePath,
+	sortMemoryRecords,
+	writeMemoryRecords,
+} from "./store.js";
+export {
+	type SaveTaskMemoryOptions,
+	TASK_MEMORY_CONTENT_MAX_CHARS,
+	TASK_MEMORY_DEFAULT_KNOWLEDGE_CAP,
+	TASK_MEMORY_DEFAULT_PROCEDURAL_CAP,
+	TASK_MEMORY_VERSION,
+	TaskMemoryBank,
+	type TaskMemoryBankOptions,
+	type TaskMemoryClass,
+	type TaskMemoryEntry,
+	type TaskMemoryRenderableClass,
+	type TaskMemorySnapshot,
+} from "./task-bank.js";
+export {
+	parseTaskMemoryHandoffSnapshot,
+	readNewestTaskMemoryHandoff,
+	renderTaskMemoryHandoffSnapshot,
+	renderTaskMemoryHandoffSource,
+	seedTaskMemoryBank,
+	seedTaskMemoryFromNewestHandoff,
+	TASK_MEMORY_HANDOFF_LANGUAGE,
+	TASK_MEMORY_HANDOFF_VERSION,
+	type TaskMemoryHandoffArtifact,
+	type TaskMemoryHandoffEntry,
+	type TaskMemoryHandoffOffer,
+	type TaskMemoryHandoffSeedOutcome,
+	type TaskMemoryHandoffSeedResult,
+	type TaskMemoryHandoffSnapshot,
+	taskMemoryHandoffSeedOffer,
+	taskMemoryHandoffSnapshot,
+} from "./task-memory-handoff.js";
+export {
+	parseTaskMemoryPolicyResponse,
+	runTaskMemoryPolicy,
+	TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS,
+	TASK_MEMORY_POLICY_MAX_OPERATIONS,
+	TASK_MEMORY_POLICY_MODEL_MAX_OUTPUT_TOKENS,
+	type TaskMemoryEnvelope,
+	type TaskMemoryModelClient,
+	type TaskMemoryModelRequest,
+	type TaskMemoryModelResponse,
+	type TaskMemoryPolicyDecision,
+	type TaskMemoryPolicyInput,
+	type TaskMemoryPolicyReason,
+	type TaskMemoryPolicyResult,
+	type TaskMemoryTrajectoryStep,
+} from "./task-memory-policy.js";
+export {
+	describeTaskMemoryActivity,
+	type TaskMemoryActivityEvent,
+	type TaskMemoryOperatorStatus,
+	type TaskMemoryTier,
+	taskMemoryBankSize,
+} from "./task-memory-status.js";
+export {
+	type CreateTaskMemoryTelemetrySinkOptions,
+	createTaskMemoryTelemetrySink,
+	parseTaskMemoryTelemetryRecord,
+	TASK_MEMORY_TELEMETRY_FILE,
+	TASK_MEMORY_TELEMETRY_MAX_BYTES,
+	TASK_MEMORY_TELEMETRY_VERSION,
+	type TaskMemoryBankDelta,
+	type TaskMemoryClassDelta,
+	type TaskMemoryTelemetryDecision,
+	type TaskMemoryTelemetryRecord,
+	type TaskMemoryTelemetrySink,
+	type TaskMemoryTelemetryStep,
+	type TaskMemoryTelemetryTier,
+	type TaskMemoryTelemetryTrigger,
+	type TaskMemoryTokenCost,
+	taskMemoryBankDelta,
+	taskMemoryTelemetryRecord,
+} from "./task-memory-telemetry.js";
+export {
+	createTaskMemoryTrace,
+	type TaskMemoryTrace,
+	type TaskMemoryTraceRow,
+	taskMemoryTracePath,
+} from "./task-memory-trace.js";
+export type {
+	MemoryProposalResult,
+	MemoryPruneResult,
+	MemoryRecord,
+	MemoryRecordValidationResult,
+	MemoryRepositoryIdentity,
+	MemoryRetrievalOptions,
+	MemoryScope,
+	MemoryStatus,
+	MemoryStoreFile,
+	MemoryStoreValidationResult,
+	MemoryValidationIssue,
+} from "./types.js";
+export { MEMORY_SCOPES, MEMORY_VERSION } from "./types.js";
+export { validateMemoryRecord, validateMemoryStore } from "./validate.js";

package/src/domains/memory/operations.ts

@@ -0,0 +1,143 @@
+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";
+
+export async function approveMemoryRecord(
+	dataDir: string,
+	memoryId: string,
+	now: Date = new Date(),
+): Promise<MemoryRecord> {
+	return updateMemoryRecord(dataDir, memoryId, (record) => approveRecord(record, now));
+}
+
+export async function rejectMemoryRecord(
+	dataDir: string,
+	memoryId: string,
+	now: Date = new Date(),
+): Promise<MemoryRecord> {
+	return updateMemoryRecord(dataDir, memoryId, (record) => rejectRecord(record, now));
+}
+
+export async function pruneStaleMemory(dataDir: string, now: Date = new Date()): Promise<MemoryRecord[]> {
+	return pruneStaleMemoryRecords(dataDir, now);
+}
+
+export function selectApprovedMemory(
+	records: ReadonlyArray<MemoryRecord>,
+	options: MemoryRetrievalOptions,
+): MemoryRecord[] {
+	if (options.tokenBudget <= 0) return [];
+	const allowedScopes = options.scopes === undefined ? null : new Set(options.scopes);
+	const activeRepository = canonicalActiveRepository(options.activeRepository);
+	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))
+		.sort(compareRetrievalPriority);
+	const selected: MemoryRecord[] = [];
+	let spent = 0;
+	for (const record of candidates) {
+		const cost = estimateMemoryTokens(record);
+		if (spent + cost > options.tokenBudget) continue;
+		selected.push(record);
+		spent += cost;
+	}
+	return selected;
+}
+
+export function estimateMemoryTokens(record: MemoryRecord): number {
+	const text = [
+		record.scope,
+		record.key,
+		record.lesson,
+		...(record.repository === undefined ? [] : [record.repository.kind, record.repository.key]),
+		...record.evidenceRefs,
+		...record.appliesWhen,
+		...record.avoidWhen,
+		...(record.regressions ?? []),
+	].join("\n");
+	return Math.max(1, ceilChars(text.length));
+}
+
+function cloneRecord(record: MemoryRecord): MemoryRecord {
+	const next: MemoryRecord = {
+		id: record.id,
+		scope: record.scope,
+		key: record.key,
+		lesson: record.lesson,
+		evidenceRefs: [...record.evidenceRefs],
+		appliesWhen: [...record.appliesWhen],
+		avoidWhen: [...record.avoidWhen],
+		confidence: record.confidence,
+		createdAt: record.createdAt,
+		approved: record.approved,
+	};
+	if (record.lastVerifiedAt !== undefined) next.lastVerifiedAt = record.lastVerifiedAt;
+	if (record.regressions !== undefined) next.regressions = [...record.regressions];
+	if (record.rejectedAt !== undefined) next.rejectedAt = record.rejectedAt;
+	if (record.repository !== undefined) next.repository = { ...record.repository };
+	return next;
+}
+
+/**
+ * Build the path identity expected by memory selection. The input must be an
+ * absolute active repository root. Existing symlinks are resolved; non-Git
+ * directories are valid identities too. Missing/moved paths stay distinct
+ * from their former location and therefore fail closed against old records.
+ */
+export function canonicalMemoryRepositoryIdentity(repositoryPath: string): MemoryRepositoryIdentity | null {
+	if (!isUsableAbsoluteRepositoryPath(repositoryPath)) return null;
+	const key = canonicalizeExistingPath(repositoryPath);
+	if (!isUsableAbsoluteRepositoryPath(key)) return null;
+	return { kind: "canonical-path", key };
+}
+
+function canonicalActiveRepository(
+	identity: MemoryRepositoryIdentity | null | undefined,
+): MemoryRepositoryIdentity | null {
+	if (identity === null || identity === undefined || identity.kind !== "canonical-path") return null;
+	const canonical = canonicalMemoryRepositoryIdentity(identity.key);
+	if (canonical === null || canonical.key !== identity.key) return null;
+	return canonical;
+}
+
+function repositoryApplies(record: MemoryRecord, activeRepository: MemoryRepositoryIdentity | null): boolean {
+	if (record.scope !== "repo") return true;
+	if (activeRepository === null) return false;
+
+	// The structured field is the only applicability mechanism: a repo-scoped
+	// record without it never enters any repository prompt.
+	if (record.repository === undefined) return false;
+	return record.repository.kind === activeRepository.kind && record.repository.key === activeRepository.key;
+}
+
+function isUsableAbsoluteRepositoryPath(value: string): boolean {
+	return value.length > 0 && !/[\0\r\n]/u.test(value) && isAbsolute(value);
+}
+
+function approveRecord(record: MemoryRecord, now: Date): MemoryRecord {
+	const next = cloneRecord(record);
+	next.approved = true;
+	next.lastVerifiedAt = now.toISOString();
+	Reflect.deleteProperty(next, "rejectedAt");
+	return next;
+}
+
+function rejectRecord(record: MemoryRecord, now: Date): MemoryRecord {
+	const next = cloneRecord(record);
+	next.approved = false;
+	next.rejectedAt = now.toISOString();
+	return next;
+}
+
+function compareRetrievalPriority(left: MemoryRecord, right: MemoryRecord): number {
+	const leftVerified = left.lastVerifiedAt ?? left.createdAt;
+	const rightVerified = right.lastVerifiedAt ?? right.createdAt;
+	const byVerified = rightVerified.localeCompare(leftVerified);
+	if (byVerified !== 0) return byVerified;
+	return left.id.localeCompare(right.id);
+}

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

@@ -0,0 +1,86 @@
+import { estimateMemoryTokens, selectApprovedMemory } from "./operations.js";
+import type { MemoryRecord, MemoryRepositoryIdentity, MemoryScope } from "./types.js";
+
+export const MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET = 400;
+export const MEMORY_PROMPT_DEFAULT_MAX_ITEMS = 5;
+
+/**
+ * Default scopes considered for chat-loop memory injection. We deliberately
+ * keep this conservative: `global` records are generally relevant and `repo`
+ * records are considered only when they exactly match the active repository
+ * identity. `language`, `runtime`, `agent`, `task-family`, and `hpc-domain`
+ * need richer context that the chat-loop does not have at submit-time. Future
+ * slices can broaden this list per call site.
+ */
+export const MEMORY_PROMPT_DEFAULT_SCOPES: ReadonlyArray<MemoryScope> = ["global", "repo"];
+
+export interface MemoryPromptOptions {
+	scopes?: ReadonlyArray<MemoryScope>;
+	tokenBudget?: number;
+	maxItems?: number;
+	/** Missing or unknown identity leaves global memory eligible but excludes repo memory. */
+	activeRepository?: MemoryRepositoryIdentity | null;
+}
+
+/**
+ * Filter approved, non-regressed, evidence-linked memory and cap by scope,
+ * deterministic token budget, repository identity, and item count. Stable
+ * ordering is guaranteed by `selectApprovedMemory`'s inner sort and the fixed
+ * scope list. Repository identities match on exact canonical keys only.
+ */
+export function selectMemoryForPrompt(
+	records: ReadonlyArray<MemoryRecord>,
+	options: MemoryPromptOptions = {},
+): MemoryRecord[] {
+	const scopes = options.scopes ?? MEMORY_PROMPT_DEFAULT_SCOPES;
+	const tokenBudget = options.tokenBudget ?? MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET;
+	const maxItems = options.maxItems ?? MEMORY_PROMPT_DEFAULT_MAX_ITEMS;
+	if (tokenBudget <= 0 || maxItems <= 0) return [];
+	const selected = selectApprovedMemory(records, {
+		scopes,
+		tokenBudget,
+		activeRepository: options.activeRepository ?? null,
+	});
+	return selected.slice(0, maxItems);
+}
+
+/**
+ * Render a compact, deterministic memory section for prompt injection. Every
+ * line cites evidence ids so the model can reason about provenance. Returns
+ * the empty string when no records apply, so callers can treat the section as
+ * absent.
+ */
+export function renderMemoryPromptSection(records: ReadonlyArray<MemoryRecord>): string {
+	if (records.length === 0) return "";
+	const lines: string[] = [
+		"# Memory",
+		"",
+		"Approved long-term memory records that may apply. Each lesson is gated by human approval and cited evidence; do not extrapolate beyond the cited findings.",
+		"",
+	];
+	for (const record of records) {
+		const lesson = record.lesson.replace(/\s+/g, " ").trim();
+		const evidence = record.evidenceRefs.join(", ");
+		lines.push(`- [${record.id}] (${renderApplicability(record)}) ${lesson} Evidence: ${evidence}.`);
+	}
+	return lines.join("\n");
+}
+
+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}`)}`;
+	}
+	return "scope=repo, repository=unknown";
+}
+
+/** Convenience for callers that want a single end-to-end build step. */
+export function buildMemoryPromptSection(
+	records: ReadonlyArray<MemoryRecord>,
+	options: MemoryPromptOptions = {},
+): { section: string; records: MemoryRecord[]; tokens: number } {
+	const selected = selectMemoryForPrompt(records, options);
+	const section = renderMemoryPromptSection(selected);
+	const tokens = selected.reduce((acc, record) => acc + estimateMemoryTokens(record), 0);
+	return { section, records: selected, tokens };
+}