@iowarp/clio-coder 0.4.3 → 0.4.4

package/src/domains/safety/validation-contract.ts

@@ -0,0 +1,388 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { resolveSafeCwd } from "../../core/safe-exec.js";
+import { byteLength } from "../../tools/truncate-utf8.js";
+import { compareCodepoints } from "../evidence/ordering.js";
+
+/**
+ * The one strict loader for the version-1 scientific validation contract.
+ * Rigor resolution, verifier authoring, doctor, and the startup hint all read
+ * the contract through this module, so a file either parses under one schema
+ * or is diagnosed under one vocabulary. Nothing here executes anything: a
+ * parsed contract is a requirement statement, and its `validators` stay prose
+ * until the project declares matching `.clio-coder/verifiers.yaml` entries.
+ */
+
+export const VALIDATION_CONTRACT_VERSION = 1;
+
+/** YAML contract paths in resolution order; the first that exists is the contract. */
+export const VALIDATION_CONTRACT_YAML_PATHS: ReadonlyArray<string> = [
+	".clio-coder/validation.yaml",
+	".clio-coder/validation.yml",
+	"validation.yaml",
+	"validation.yml",
+];
+
+/** Markdown is recognized as present but never parsed and never raises rigor. */
+export const VALIDATION_CONTRACT_MARKDOWN_PATH = "VALIDATION.md";
+
+/** Public schema limits. Diagnostics cite these values instead of hiding policy. */
+export const VALIDATION_CONTRACT_CAPS = Object.freeze({
+	fileBytes: 256 * 1024,
+	textBytes: 4096,
+	notesBytes: 16 * 1024,
+	artifacts: 256,
+	validators: 128,
+	modules: 64,
+	mapEntries: 256,
+	mapKeyBytes: 256,
+});
+
+export type ValidationRuntimeKind = "local" | "slurm" | "mpi" | "other";
+
+const RUNTIME_KINDS: ReadonlyArray<ValidationRuntimeKind> = ["local", "slurm", "mpi", "other"];
+
+export interface ValidationContractRuntime {
+	kind: ValidationRuntimeKind;
+	nodes?: number;
+	ranks?: number;
+	walltime?: string;
+	modules?: string[];
+}
+
+export interface ValidationNumericalTolerances {
+	relative?: number;
+	absolute?: number;
+	ulp?: number;
+}
+
+export interface ValidationContractArtifact {
+	path: string;
+	format?: string;
+	expected_dimensions?: Record<string, number>;
+	expected_attributes?: Record<string, string>;
+	numerical_tolerances?: ValidationNumericalTolerances;
+	preserve?: boolean;
+}
+
+export interface ValidationContract {
+	version: typeof VALIDATION_CONTRACT_VERSION;
+	task?: string;
+	runtime?: ValidationContractRuntime;
+	artifacts?: ValidationContractArtifact[];
+	/** Advisory command prose. Never executed from here. */
+	validators?: string[];
+	notes?: string;
+}
+
+export type ValidationContractLoadResult =
+	/** A YAML contract parsed under the version-1 schema. */
+	| { ok: true; contract: ValidationContract; path: string }
+	/** No contract file at the workspace root. */
+	| { ok: true; contract: null }
+	/** Only `VALIDATION.md` exists: present, unparsed, advisory. */
+	| { ok: true; contract: null; path: string; advisory: true }
+	/** A YAML contract exists but does not parse; `reason` names the fault and cites the cap it crossed. */
+	| { ok: false; path: string; reason: string };
+
+const ROOT_FIELDS = new Set(["version", "task", "runtime", "artifacts", "validators", "notes"]);
+const RUNTIME_FIELDS = new Set(["kind", "nodes", "ranks", "walltime", "modules"]);
+const ARTIFACT_FIELDS = new Set([
+	"path",
+	"format",
+	"expected_dimensions",
+	"expected_attributes",
+	"numerical_tolerances",
+	"preserve",
+]);
+const TOLERANCE_FIELDS = new Set(["relative", "absolute", "ulp"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function unknownFields(record: Record<string, unknown>, allowed: ReadonlySet<string>): string[] {
+	return Object.keys(record)
+		.filter((key) => !allowed.has(key))
+		.sort(compareCodepoints);
+}
+
+function boundedText(value: unknown, location: string, cap: number): string | Error {
+	if (typeof value !== "string" || value.length === 0) return new Error(`${location} must be a non-empty string`);
+	if (value.includes("\0")) return new Error(`${location} must not contain a NUL byte`);
+	if (byteLength(value) > cap) return new Error(`${location} exceeds the ${cap}-byte cap`);
+	return value;
+}
+
+function positiveInteger(value: unknown, location: string): number | Error {
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+		return new Error(`${location} must be a positive integer`);
+	}
+	return value;
+}
+
+function nonNegativeNumber(value: unknown, location: string): number | Error {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		return new Error(`${location} must be a finite non-negative number`);
+	}
+	return value;
+}
+
+function boundedStringList(value: unknown, location: string, cap: number): string[] | Error {
+	if (!Array.isArray(value)) return new Error(`${location} must be an array of strings`);
+	if (value.length > cap) return new Error(`${location} exceeds the ${cap}-entry cap`);
+	const items: string[] = [];
+	for (const [index, entry] of value.entries()) {
+		const text = boundedText(entry, `${location}[${index}]`, VALIDATION_CONTRACT_CAPS.textBytes);
+		if (text instanceof Error) return text;
+		items.push(text);
+	}
+	return items;
+}
+
+function boundedMap<T>(
+	value: unknown,
+	location: string,
+	validateEntry: (entry: unknown, entryLocation: string) => T | Error,
+): Record<string, T> | Error {
+	if (!isRecord(value)) return new Error(`${location} must be a map`);
+	const keys = Object.keys(value);
+	if (keys.length > VALIDATION_CONTRACT_CAPS.mapEntries) {
+		return new Error(`${location} exceeds the ${VALIDATION_CONTRACT_CAPS.mapEntries}-entry cap`);
+	}
+	const out: Record<string, T> = {};
+	for (const key of keys.sort(compareCodepoints)) {
+		const entryLocation = `${location}.${key}`;
+		if (key.length === 0) return new Error(`${location} has an empty key`);
+		if (byteLength(key) > VALIDATION_CONTRACT_CAPS.mapKeyBytes) {
+			return new Error(`${entryLocation} key exceeds the ${VALIDATION_CONTRACT_CAPS.mapKeyBytes}-byte cap`);
+		}
+		const entry = validateEntry(value[key], entryLocation);
+		if (entry instanceof Error) return entry;
+		out[key] = entry;
+	}
+	return out;
+}
+
+function validateRuntime(value: unknown, location: string): ValidationContractRuntime | Error {
+	if (!isRecord(value)) return new Error(`${location} must be an object with a kind field`);
+	const unknown = unknownFields(value, RUNTIME_FIELDS);
+	if (unknown.length > 0) return new Error(`${location} has unknown field(s): ${unknown.join(", ")}`);
+	if (!Object.hasOwn(value, "kind")) return new Error(`${location}.kind is required`);
+	const kind = value.kind;
+	if (typeof kind !== "string" || !(RUNTIME_KINDS as ReadonlyArray<string>).includes(kind)) {
+		return new Error(`${location}.kind must be one of ${RUNTIME_KINDS.join(", ")}`);
+	}
+	const runtime: ValidationContractRuntime = { kind: kind as ValidationRuntimeKind };
+	if (Object.hasOwn(value, "nodes")) {
+		const nodes = positiveInteger(value.nodes, `${location}.nodes`);
+		if (nodes instanceof Error) return nodes;
+		runtime.nodes = nodes;
+	}
+	if (Object.hasOwn(value, "ranks")) {
+		const ranks = positiveInteger(value.ranks, `${location}.ranks`);
+		if (ranks instanceof Error) return ranks;
+		runtime.ranks = ranks;
+	}
+	if (Object.hasOwn(value, "walltime")) {
+		const walltime = boundedText(value.walltime, `${location}.walltime`, VALIDATION_CONTRACT_CAPS.textBytes);
+		if (walltime instanceof Error) return walltime;
+		runtime.walltime = walltime;
+	}
+	if (Object.hasOwn(value, "modules")) {
+		const modules = boundedStringList(value.modules, `${location}.modules`, VALIDATION_CONTRACT_CAPS.modules);
+		if (modules instanceof Error) return modules;
+		runtime.modules = modules;
+	}
+	return runtime;
+}
+
+function validateTolerances(value: unknown, location: string): ValidationNumericalTolerances | Error {
+	if (!isRecord(value)) return new Error(`${location} must be an object`);
+	const unknown = unknownFields(value, TOLERANCE_FIELDS);
+	if (unknown.length > 0) return new Error(`${location} has unknown field(s): ${unknown.join(", ")}`);
+	const tolerances: ValidationNumericalTolerances = {};
+	if (Object.hasOwn(value, "relative")) {
+		const relative = nonNegativeNumber(value.relative, `${location}.relative`);
+		if (relative instanceof Error) return relative;
+		tolerances.relative = relative;
+	}
+	if (Object.hasOwn(value, "absolute")) {
+		const absolute = nonNegativeNumber(value.absolute, `${location}.absolute`);
+		if (absolute instanceof Error) return absolute;
+		tolerances.absolute = absolute;
+	}
+	if (Object.hasOwn(value, "ulp")) {
+		const ulp = value.ulp;
+		if (typeof ulp !== "number" || !Number.isInteger(ulp) || ulp < 0) {
+			return new Error(`${location}.ulp must be a non-negative integer`);
+		}
+		tolerances.ulp = ulp;
+	}
+	return tolerances;
+}
+
+function validateArtifact(value: unknown, location: string): ValidationContractArtifact | Error {
+	if (!isRecord(value)) return new Error(`${location} must be an object with a path field`);
+	const unknown = unknownFields(value, ARTIFACT_FIELDS);
+	if (unknown.length > 0) return new Error(`${location} has unknown field(s): ${unknown.join(", ")}`);
+	if (!Object.hasOwn(value, "path")) return new Error(`${location}.path is required`);
+	const artifactPath = boundedText(value.path, `${location}.path`, VALIDATION_CONTRACT_CAPS.textBytes);
+	if (artifactPath instanceof Error) return artifactPath;
+	const artifact: ValidationContractArtifact = { path: artifactPath };
+	if (Object.hasOwn(value, "format")) {
+		const format = boundedText(value.format, `${location}.format`, VALIDATION_CONTRACT_CAPS.textBytes);
+		if (format instanceof Error) return format;
+		artifact.format = format;
+	}
+	if (Object.hasOwn(value, "expected_dimensions")) {
+		const dimensions = boundedMap(value.expected_dimensions, `${location}.expected_dimensions`, (entry, entryLocation) =>
+			typeof entry === "number" && Number.isInteger(entry) && entry >= 0
+				? entry
+				: new Error(`${entryLocation} must be a non-negative integer`),
+		);
+		if (dimensions instanceof Error) return dimensions;
+		artifact.expected_dimensions = dimensions;
+	}
+	if (Object.hasOwn(value, "expected_attributes")) {
+		const attributes = boundedMap(value.expected_attributes, `${location}.expected_attributes`, (entry, entryLocation) =>
+			typeof entry === "string"
+				? boundedText(entry, entryLocation, VALIDATION_CONTRACT_CAPS.textBytes)
+				: new Error(`${entryLocation} must be a string`),
+		);
+		if (attributes instanceof Error) return attributes;
+		artifact.expected_attributes = attributes;
+	}
+	if (Object.hasOwn(value, "numerical_tolerances")) {
+		const tolerances = validateTolerances(value.numerical_tolerances, `${location}.numerical_tolerances`);
+		if (tolerances instanceof Error) return tolerances;
+		artifact.numerical_tolerances = tolerances;
+	}
+	if (Object.hasOwn(value, "preserve")) {
+		if (typeof value.preserve !== "boolean") return new Error(`${location}.preserve must be a boolean`);
+		artifact.preserve = value.preserve;
+	}
+	return artifact;
+}
+
+/** Parse contract text under the version-1 schema; `contractPath` only labels the result. */
+export function parseValidationContractText(text: string, contractPath: string): ValidationContractLoadResult {
+	const invalid = (reason: string): ValidationContractLoadResult => ({ ok: false, path: contractPath, reason });
+	const document = parseDocument(text, { prettyErrors: false, strict: true, uniqueKeys: true });
+	if (document.errors.length > 0) {
+		return invalid(`invalid YAML: ${document.errors.map((error) => error.message).join("; ")}`);
+	}
+	let parsed: unknown;
+	try {
+		parsed = document.toJS({ maxAliasCount: 0 }) as unknown;
+	} catch (error) {
+		return invalid(`invalid YAML: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!isRecord(parsed)) return invalid("root must be an object with a version field");
+	const rootUnknown = unknownFields(parsed, ROOT_FIELDS);
+	if (rootUnknown.length > 0) return invalid(`root has unknown field(s): ${rootUnknown.join(", ")}`);
+	if (!Object.hasOwn(parsed, "version")) return invalid("root.version is required");
+	if (parsed.version !== VALIDATION_CONTRACT_VERSION) {
+		return invalid(
+			`unsupported version ${JSON.stringify(parsed.version)}; supported version is ${VALIDATION_CONTRACT_VERSION}`,
+		);
+	}
+	const contract: ValidationContract = { version: VALIDATION_CONTRACT_VERSION };
+	if (Object.hasOwn(parsed, "task")) {
+		const task = boundedText(parsed.task, "root.task", VALIDATION_CONTRACT_CAPS.textBytes);
+		if (task instanceof Error) return invalid(task.message);
+		contract.task = task;
+	}
+	if (Object.hasOwn(parsed, "runtime")) {
+		const runtime = validateRuntime(parsed.runtime, "root.runtime");
+		if (runtime instanceof Error) return invalid(runtime.message);
+		contract.runtime = runtime;
+	}
+	if (Object.hasOwn(parsed, "artifacts")) {
+		if (!Array.isArray(parsed.artifacts)) return invalid("root.artifacts must be an array");
+		if (parsed.artifacts.length > VALIDATION_CONTRACT_CAPS.artifacts) {
+			return invalid(`root.artifacts exceeds the ${VALIDATION_CONTRACT_CAPS.artifacts}-entry cap`);
+		}
+		const artifacts: ValidationContractArtifact[] = [];
+		for (const [index, value] of parsed.artifacts.entries()) {
+			const artifact = validateArtifact(value, `artifacts[${index}]`);
+			if (artifact instanceof Error) return invalid(artifact.message);
+			artifacts.push(artifact);
+		}
+		contract.artifacts = artifacts;
+	}
+	if (Object.hasOwn(parsed, "validators")) {
+		const validators = boundedStringList(parsed.validators, "root.validators", VALIDATION_CONTRACT_CAPS.validators);
+		if (validators instanceof Error) return invalid(validators.message);
+		contract.validators = validators;
+	}
+	if (Object.hasOwn(parsed, "notes")) {
+		const notes = boundedText(parsed.notes, "root.notes", VALIDATION_CONTRACT_CAPS.notesBytes);
+		if (notes instanceof Error) return invalid(notes.message);
+		contract.notes = notes;
+	}
+	return { ok: true, contract, path: contractPath };
+}
+
+function readContractText(absolutePath: string, workspaceRoot: string): string | Error {
+	let realPath: string;
+	try {
+		const realRoot = realpathSync(workspaceRoot);
+		realPath = realpathSync(absolutePath);
+		resolveSafeCwd(realPath, realRoot);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return new Error(`contract file must resolve inside the workspace root (${message})`);
+	}
+	try {
+		const stats = statSync(realPath);
+		if (!stats.isFile()) return new Error("contract path must be a regular file");
+		if (stats.size > VALIDATION_CONTRACT_CAPS.fileBytes) {
+			return new Error(`file exceeds the ${VALIDATION_CONTRACT_CAPS.fileBytes}-byte cap`);
+		}
+		return readFileSync(realPath, "utf8");
+	} catch (error) {
+		return new Error(`cannot read contract (${error instanceof Error ? error.message : String(error)})`);
+	}
+}
+
+/**
+ * Load the workspace's validation contract. The first YAML path in
+ * {@link VALIDATION_CONTRACT_YAML_PATHS} that exists is the contract; a
+ * `VALIDATION.md` without any YAML is reported present and advisory. Every
+ * failure is a value, never a throw, so rigor resolution stays total.
+ */
+export function loadValidationContract(workspaceRoot: string): ValidationContractLoadResult {
+	let contractPath: string | null = null;
+	try {
+		contractPath =
+			VALIDATION_CONTRACT_YAML_PATHS.find((relative) => existsSync(path.join(workspaceRoot, relative))) ?? null;
+		if (contractPath === null) {
+			if (existsSync(path.join(workspaceRoot, VALIDATION_CONTRACT_MARKDOWN_PATH))) {
+				return { ok: true, contract: null, path: VALIDATION_CONTRACT_MARKDOWN_PATH, advisory: true };
+			}
+			return { ok: true, contract: null };
+		}
+	} catch (error) {
+		return {
+			ok: false,
+			path: contractPath ?? VALIDATION_CONTRACT_YAML_PATHS[0] ?? "validation.yaml",
+			reason: `cannot inspect workspace root (${error instanceof Error ? error.message : String(error)})`,
+		};
+	}
+	const text = readContractText(path.join(workspaceRoot, contractPath), workspaceRoot);
+	if (text instanceof Error) return { ok: false, path: contractPath, reason: text.message };
+	return parseValidationContractText(text, contractPath);
+}
+
+/** One line a diagnostic surface can print for a load result, or null when there is nothing to say. */
+export function describeValidationContract(result: ValidationContractLoadResult): string | null {
+	if (!result.ok) return `${result.path}: ${result.reason}`;
+	if (result.contract === null) {
+		return "advisory" in result
+			? `${result.path} is advisory prose and does not raise rigor; add a version-1 validation.yaml to raise the default to high`
+			: null;
+	}
+	return null;
+}

package/src/domains/session/archive-readers.ts

@@ -30,6 +30,8 @@ export interface AuditReadResult {
 }
 
 export interface SessionReadResult {
+	/** Persisted /tree selection, when the session has not appended past it. */
+	leafTurnId?: string;
 	entries: SessionEntry[];
 	missing: boolean;
 	errors: string[];
@@ -142,7 +144,14 @@ export async function readSessionEntriesForId(stateDir: string, sessionId: strin
 				return { entries: [], missing: false, errors: [`${currentPath}: ${err.message ?? String(err)}`] };
 			}
 		}
-		return parseSessionEntries(raw, source);
+		const result = parseSessionEntries(raw, source);
+		try {
+			const meta: unknown = JSON.parse(await readFile(join(root, cwdHash, sessionId, "meta.json"), "utf8"));
+			if (isRecord(meta) && typeof meta.pinnedLeafTurnId === "string") result.leafTurnId = meta.pinnedLeafTurnId;
+		} catch {
+			// Legacy archives without metadata fall back to the newest message branch.
+		}
+		return result;
 	}
 	return { entries: [], missing: true, errors: [] };
 }

package/src/domains/session/decision-board.ts

@@ -1,10 +1,12 @@
+import { randomUUID } from "node:crypto";
 import type { AskUserToolPolicy } from "../../tools/registry.js";
 import type { AutonomyExposure } from "../safety/autonomy.js";
-import type { DecisionLedgerEntry, DecisionRecord } from "./entries.js";
+import { type DecisionLedgerEntry, type DecisionRecord, decisionRef } from "./entries.js";
 
 export interface DecisionLedgerEntryFields {
 	kind: "decisionLedger";
 	parentTurnId: string;
+	origin?: "interview" | "agent";
 	interviewId: string;
 	interviewStatus: "complete" | "cancelled";
 	startedAt: string;
@@ -28,11 +30,35 @@ export interface DecisionBoardStoreDeps {
 	now?: () => Date;
 }
 
+/** One design choice the model records itself through the `decide` tool. */
+export interface AgentDecisionInput {
+	key: string;
+	value: string;
+	alternatives: ReadonlyArray<string>;
+	rationale: string;
+	label?: string;
+}
+
+export interface AgentDecisionOutcome {
+	/** The appended agent decision set; `decisionRef(entry.interviewId, key)` cites it. */
+	entry: DecisionLedgerEntryFields;
+	/** The earlier active record with the same key that this decision superseded, when there was one. */
+	superseded: { interviewId: string; key: string } | null;
+}
+
 export interface DecisionBoardStore {
 	/** Latest snapshot per interview, newest interview first. */
 	snapshot(): ReadonlyArray<DecisionLedgerEntry>;
 	/** Persist the one host-finalized snapshot for a settled interview. */
 	recordFinalizedInterview(policy: AskUserToolPolicy): boolean;
+	/**
+	 * Append one agent-recorded decision as its own complete set
+	 * (`origin: "agent"`, `interviewId: "agent:<uuid>"`, `roundCount: 0`). An
+	 * earlier active agent decision with the same key is superseded first with
+	 * the new rationale as its correction. An active operator decision with the
+	 * same key is never overwritten by the model; that throws.
+	 */
+	recordAgentDecision(input: AgentDecisionInput): AgentDecisionOutcome;
 	/** Append an operator revision snapshot anchored to the active branch leaf. */
 	supersede(interviewId: string, key: string, correction?: string): DecisionLedgerEntryFields;
 	/** Force the next read to refold, including after a same-session tree switch. */
@@ -90,6 +116,24 @@ function finalizedInterviewEntryFields(policy: AskUserToolPolicy): DecisionLedge
 	};
 }
 
+/** Most decision refs one dispatch request, envelope, or receipt carries. */
+export const DECISION_REFS_CAP = 32;
+
+/**
+ * Refs of every active decision on a board snapshot, sorted and capped at
+ * {@link DECISION_REFS_CAP}. Dispatch seals this onto each request it builds;
+ * an empty board yields an empty list, which callers leave off the request.
+ */
+export function activeDecisionRefs(board: ReadonlyArray<DecisionLedgerEntry>): string[] {
+	const refs = new Set<string>();
+	for (const entry of board) {
+		for (const decision of entry.decisions) {
+			if (decision.status === "active") refs.add(decisionRef(entry.interviewId, decision.key));
+		}
+	}
+	return [...refs].sort().slice(0, DECISION_REFS_CAP);
+}
+
 function isDecisionLedgerEntry(value: unknown): value is DecisionLedgerEntry {
 	return !!value && typeof value === "object" && (value as { kind?: unknown }).kind === "decisionLedger";
 }
@@ -143,7 +187,7 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 		dirty = true;
 	};
 
-	return {
+	const store: DecisionBoardStore = {
 		snapshot(): ReadonlyArray<DecisionLedgerEntry> {
 			syncToSession();
 			return interviews;
@@ -154,6 +198,51 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 			append(entry);
 			return true;
 		},
+		recordAgentDecision(input: AgentDecisionInput): AgentDecisionOutcome {
+			syncToSession();
+			let superseded: AgentDecisionOutcome["superseded"] = null;
+			for (const interview of interviews) {
+				const prior = interview.decisions.find((decision) => decision.key === input.key && decision.status === "active");
+				if (prior === undefined) continue;
+				if (interview.origin !== "agent" || prior.source !== "agent") {
+					throw new Error(
+						`decision board: '${input.key}' is an operator decision (${interview.interviewId}); it can only be revised through ask_user`,
+					);
+				}
+				superseded = { interviewId: interview.interviewId, key: prior.key };
+				break;
+			}
+			if (superseded !== null) store.supersede(superseded.interviewId, superseded.key, input.rationale);
+			const now = (deps.now?.() ?? new Date()).toISOString();
+			const entries = deps.readEntries?.() ?? [];
+			const parentTurnId = deps.getActiveLeafTurnId?.() ?? activeLeafFromEntries(entries);
+			if (!parentTurnId) throw new Error("decision board: no active branch leaf is available for the decision");
+			const entry: DecisionLedgerEntryFields = {
+				kind: "decisionLedger",
+				parentTurnId,
+				origin: "agent",
+				interviewId: `agent:${randomUUID()}`,
+				interviewStatus: "complete",
+				startedAt: now,
+				endedAt: now,
+				roundCount: 0,
+				exposure: "local",
+				decisions: [
+					{
+						key: input.key,
+						value: input.value,
+						...(input.label ? { label: input.label } : {}),
+						status: "active",
+						decidedAt: now,
+						source: "agent",
+						alternatives: [...input.alternatives],
+						rationale: input.rationale,
+					},
+				],
+			};
+			append(entry);
+			return { entry, superseded };
+		},
 		supersede(interviewId: string, key: string, correction?: string): DecisionLedgerEntryFields {
 			syncToSession();
 			const interview = interviews.find((candidate) => candidate.interviewId === interviewId);
@@ -191,4 +280,14 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 			dirty = true;
 		},
 	};
+	return store;
+}
+
+/** Preserve the recorded argument wherever a decision is carried into another prompt. */
+export function decisionRationale(decision: DecisionRecord): string | undefined {
+	const parts: string[] = [];
+	if (decision.alternatives?.length) parts.push(`Alternatives: ${decision.alternatives.join("; ")}`);
+	if (decision.rationale) parts.push(`Rationale: ${decision.rationale}`);
+	if (parts.length > 0) return parts.join(". ");
+	return decision.source_question ?? decision.correction;
 }

package/src/domains/session/entries.ts

@@ -5,10 +5,13 @@
  * carries its `kind` discriminant, a `turnId` (uuid v7 where possible so
  * entries sort by creation), a parent pointer, and an ISO timestamp.
  *
- * Later slices extend this union:
- *   - compactionSummary is produced by compaction/compact.ts (slice 12c).
- *   - branchSummary is produced by the fork path (slice 12b).
- *   - bashExecution / fileEntry become the wire shape for Phase 14 extensions.
+ * Non-message kinds and where they come from:
+ *   - compactionSummary is produced by compaction/compact.ts.
+ *   - branchSummary is produced by the fork path.
+ *   - bashExecution is produced by the editor bash path
+ *     (interactive/editor-bash.ts).
+ *   - fileEntry is consumed by the renderer, compaction, handoff, and
+ *     evidence builders but has no in-tree producer.
  */
 
 import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
@@ -213,6 +216,14 @@ export interface TaskLedgerEntry extends BaseSessionEntry {
 
 export type DecisionStatus = "active" | "superseded";
 
+/**
+ * Who settled a decision. `operator` is an answer the operator gave in an
+ * `ask_user` interview. `agent` is a design choice the model recorded itself
+ * through the `decide` tool, with the alternatives it rejected and why. Absent
+ * on entries written before agent decisions existed, which were all operator.
+ */
+export type DecisionSource = "operator" | "agent";
+
 export interface DecisionRecord {
 	key: string;
 	value: string;
@@ -222,11 +233,33 @@ export interface DecisionRecord {
 	decidedAt: string;
 	revisedAt?: string;
 	correction?: string;
+	source?: DecisionSource;
+	/** Options considered and not taken. Only agent decisions carry these. */
+	alternatives?: string[];
+	/** Why `value` won over `alternatives`. Only agent decisions carry this. */
+	rationale?: string;
+}
+
+/**
+ * Stable reference to one decision: `<interviewId>/<key>`. Both halves are
+ * already unique on the active path, so the pair needs no third id. Run
+ * envelopes, receipts, and commit trailers cite decisions by this string.
+ */
+export type DecisionRef = string;
+
+export function decisionRef(interviewId: string, key: string): DecisionRef {
+	return `${interviewId}/${key}`;
 }
 
-/** One complete, branch-anchored snapshot of a settled operator interview. */
+/**
+ * One complete, branch-anchored snapshot of a settled decision set. An
+ * `interview` origin is an operator `ask_user` round; an `agent` origin is a
+ * set the model recorded with the `decide` tool, where `interviewId` is the
+ * agent decision set id and `roundCount` is 0. Absent origin means interview.
+ */
 export interface DecisionLedgerEntry extends BaseSessionEntry {
 	kind: "decisionLedger";
+	origin?: "interview" | "agent";
 	interviewId: string;
 	interviewStatus: "complete" | "cancelled";
 	startedAt: string;
@@ -503,11 +536,14 @@ function isTaskLedgerEvidence(value: unknown): value is TaskLedgerValidationEvid
 	);
 }
 
-function isDecisionRecord(value: unknown): value is DecisionRecord {
+export function isDecisionRecord(value: unknown): value is DecisionRecord {
 	if (!isRecord(value)) return false;
-	if (!isString(value.key) || !/^[a-z0-9]+(?:_[a-z0-9]+)*$/.test(value.key)) return false;
+	if (!isString(value.key) || !/^[a-z0-9]+(?:[_-][a-z0-9]+)*$/.test(value.key)) return false;
 	if (!isString(value.value) || !isOneOf(value.status, DECISION_STATUSES) || !isString(value.decidedAt)) return false;
 	if (!isOptionalString(value.label) || !isOptionalString(value.source_question)) return false;
+	if (value.source !== undefined && !isOneOf(value.source, ["operator", "agent"])) return false;
+	if (value.alternatives !== undefined && !isStringArray(value.alternatives)) return false;
+	if (!isOptionalString(value.rationale)) return false;
 	if (!isOptionalString(value.revisedAt) || !isOptionalString(value.correction)) return false;
 	return value.status === "superseded"
 		? isString(value.revisedAt)
@@ -642,6 +678,7 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 			);
 		case "decisionLedger":
 			return (
+				(v.origin === undefined || isOneOf(v.origin, ["interview", "agent"])) &&
 				isString(v.interviewId) &&
 				isOneOf(v.interviewStatus, DECISION_INTERVIEW_STATUSES) &&
 				isString(v.startedAt) &&

package/src/domains/session/extension.ts

@@ -282,10 +282,10 @@ export function createSessionBundle(context: DomainContext): DomainBundle<Sessio
 			return snapshotFor(id);
 		},
 		switchBranch(sessionId) {
-			// /tree-driven branch switch currently delegates to resume. Kept as a
-			// distinct contract method so later slices can layer telemetry or
-			// chat-loop rewiring without changing resume's semantics. Same
-			// open-before-close ordering as resume() above and for the same reason.
+			// /tree-driven branch switch delegates to resume. Kept as a distinct
+			// contract method so telemetry or chat-loop rewiring can be layered on
+			// without changing resume's semantics. Same open-before-close ordering
+			// as resume() above and for the same reason.
 			if (state?.meta.id === sessionId) return state.meta;
 			const resumed = resumeSessionState(sessionId);
 			if (state) {