@shanepadgett/tau-agent 0.8.0 → 0.9.1

package/extensions/context/README.md

@@ -2,7 +2,22 @@
 
 Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
 
-Use `/context` to select entries and inject their files through Tau autoread. Use `/context-sync` to reconcile affected scopes from the current Git changes. Sync is automatic, constrained to the changed scope, and may report `no-change` when existing mappings already fit.
+Use `/context` to select entries and inject their files through Tau autoread. Use `/context-sync` to reconcile affected scopes from the current Git changes. Tau validates context membership after agent turns and asks the agent to sync uncovered changed files or stale references automatically.
+
+Validation is enabled by default. Configure it globally or per project in Tau settings:
+
+```json
+{
+  "extensions": {
+    "context": {
+      "validation": {
+        "enabled": true,
+        "ignoreGlobs": ["generated/**"]
+      }
+    }
+  }
+}
+```
 
 ```toml
 name = "Player"

package/extensions/context/definitions.ts

@@ -2,6 +2,7 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { parse } from "smol-toml";
+import { matchGlob } from "../../shared/glob.ts";
 
 export interface ContextEntry {
 	id: string;
@@ -36,10 +37,11 @@ const CONTEXT_IGNORED_FILENAMES = new Set([
 	"yarn.lock",
 ]);
 
-export function isContextEligiblePath(path: string): boolean {
+export function isContextEligiblePath(path: string, ignoreGlobs: readonly string[] = []): boolean {
 	return (
 		path !== "LICENSE" &&
 		!CONTEXT_IGNORED_FILENAMES.has(basename(path)) &&
+		!ignoreGlobs.some((glob) => matchGlob(glob, path)) &&
 		path !== ".pi/tau/ideas.jsonl" &&
 		path !== ".working" &&
 		!path.startsWith(".working/") &&

package/extensions/context/index.ts

@@ -4,11 +4,14 @@ import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { emitTauEvent } from "../../shared/events.ts";
+import { createGitRunner, loadRepoStatus } from "../../shared/git.ts";
 import { createInjectedContext } from "../../shared/injected-context.ts";
-import { registerTauSystemPromptContribution } from "../../shared/system-prompt-contributions.ts";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { ContextPanel } from "./panel.ts";
 import { findProjectRoot, loadContextEntries, type ContextEntry } from "./definitions.ts";
+import contextSettings from "./settings.ts";
 import { runContextSync, type ContextSyncDetails } from "./sync.ts";
+import { formatContextValidationFailure, validateContextCatalog } from "./validation.ts";
 
 const contextSyncParams = Type.Object({}, { additionalProperties: false });
 
@@ -16,22 +19,16 @@ function compactResult(details: ContextSyncDetails) {
 	const value = {
 		outcome: details.outcome,
 		summary: details.summary,
+		reason: details.reason,
 		changedContextFiles: details.changedContextFiles,
 	};
 	return { content: [{ type: "text" as const, text: JSON.stringify(value) }], details };
 }
 
 export default function contextExtension(pi: ExtensionAPI): void {
-	let active: ContextEntry[] = [];
+	let validationSettings = contextSettings.defaults.validation;
+	let lastValidationFailure: string | undefined;
 	const activeToolExecutions = new Map<string, { toolName: string; done: Promise<void>; complete: () => void }>();
-	const unregisterPrompt = registerTauSystemPromptContribution({
-		id: "context.selected-authority",
-		order: 100,
-		render: () =>
-			active.length
-				? "Treat the autoread files as the authoritative project context and current snapshots. Do not reread them or search for coverage around them. Start work from them immediately. Explore outside them only when the user's request or concrete evidence in those files requires missing code or information."
-				: undefined,
-	});
 
 	pi.registerCommand("context", {
 		description: "Select repository context entries and inject their files",
@@ -55,8 +52,6 @@ export default function contextExtension(pi: ExtensionAPI): void {
 				},
 			);
 			if (!selected?.length) return;
-			active = selected;
-			pi.appendEntry("tau.context-selection", { ids: selected.map((entry) => entry.id) });
 			const files = [...new Set(selected.flatMap((entry) => entry.files))].sort();
 			pi.sendMessage(
 				createInjectedContext(
@@ -102,7 +97,8 @@ export default function contextExtension(pi: ExtensionAPI): void {
 		defineTool<typeof contextSyncParams, ContextSyncDetails | undefined>({
 			name: "context_sync",
 			label: "context_sync",
-			description: "Synchronize repository context from current Git changes.",
+			description:
+				"Synchronize repository context membership after context validation reports changed, stale, or unassigned files.",
 			parameters: contextSyncParams,
 			async execute(id, _params, _signal, onUpdate, ctx) {
 				await Promise.all(
@@ -161,22 +157,51 @@ export default function contextExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
-		const root = await findProjectRoot(ctx.cwd);
-		const entries = await loadContextEntries(root);
-		let selectionData: unknown;
-		for (const entry of ctx.sessionManager.getBranch())
-			if (entry.type === "custom" && entry.customType === "tau.context-selection") selectionData = entry.data;
-		const ids =
-			typeof selectionData === "object" &&
-			selectionData !== null &&
-			"ids" in selectionData &&
-			Array.isArray(selectionData.ids)
-				? selectionData.ids.filter((id: unknown): id is string => typeof id === "string")
-				: [];
-		active = entries.filter((entry) => ids.includes(entry.id));
+		validationSettings = (await loadTauExtensionSettings(ctx, contextSettings)).validation;
+	});
+	pi.on("agent_start", async (_event, ctx) => {
+		validationSettings = (await loadTauExtensionSettings(ctx, contextSettings)).validation;
+	});
+	pi.on("agent_end", async (event, ctx) => {
+		if (
+			event.messages.some(
+				(message) =>
+					typeof message === "object" &&
+					message !== null &&
+					"role" in message &&
+					message.role === "assistant" &&
+					"stopReason" in message &&
+					message.stopReason === "aborted",
+			)
+		)
+			return;
+		if (!validationSettings.enabled || !ctx.isProjectTrusted()) {
+			lastValidationFailure = undefined;
+			return;
+		}
+		try {
+			const root = await findProjectRoot(ctx.cwd);
+			const git = createGitRunner(pi, ctx);
+			if (!(await loadRepoStatus(git))) return;
+			const failure = formatContextValidationFailure(
+				await validateContextCatalog(git, root, validationSettings.ignoreGlobs),
+			);
+			if (!failure) {
+				lastValidationFailure = undefined;
+				return;
+			}
+			if (failure === lastValidationFailure) return;
+			lastValidationFailure = failure;
+			ctx.ui.notify("Context catalog validation failed", "error");
+			pi.sendMessage(
+				{ customType: "tau.context-validation", content: failure, display: false },
+				{ triggerTurn: true },
+			);
+		} catch (error) {
+			ctx.ui.notify(`Context validation failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+		}
 	});
 	pi.on("session_shutdown", () => {
-		unregisterPrompt();
 		for (const execution of activeToolExecutions.values()) execution.complete();
 		activeToolExecutions.clear();
 	});

package/extensions/context/settings.ts

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+export default defineTauExtensionSettings({
+	key: "context",
+	defaults: {
+		validation: {
+			enabled: true as boolean,
+			ignoreGlobs: [] as string[],
+		},
+	},
+	schema: Type.Object(
+		{
+			validation: Type.Optional(
+				Type.Object(
+					{
+						enabled: Type.Optional(
+							Type.Boolean({ default: true, description: "Validate context membership after agent turns." }),
+						),
+						ignoreGlobs: Type.Optional(
+							Type.Array(Type.String(), {
+								default: [],
+								description: "Project-relative files excluded from context membership validation and sync.",
+							}),
+						),
+					},
+					{ additionalProperties: false },
+				),
+			),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/context/sync.ts

@@ -6,6 +6,7 @@ import { withFileMutationQueue, type ExtensionAPI, type ExtensionContext } from
 import { parse, stringify } from "smol-toml";
 import { createGitRunner, loadRepoStatus, type GitRunner } from "../../shared/git.ts";
 import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { truncAt } from "../../shared/text.ts";
 import { XAI_CHAT_MODEL, XAI_PROVIDER } from "../xai/constants.ts";
 import {
@@ -18,6 +19,7 @@ import {
 	validSlug,
 	type ContextEntry,
 } from "./definitions.ts";
+import contextSettings from "./settings.ts";
 
 const MAX_DIRTY_EVIDENCE = 4_000;
 const MAX_STRUCTURAL_PREVIEW = 1_500;
@@ -146,9 +148,10 @@ async function runContextSyncLocked(
 	const git = createGitRunner(pi, ctx);
 	const status = await loadRepoStatus(git);
 	if (!status) throw new Error("No Git repository found");
-	if (status.fileCount === 0) return noChange("Existing context mappings already fit the changed scope.");
-	const evidence = await collectSyncEvidence(git, status.root);
-	if (evidence.files.length === 0) return noChange("Changed files are outside context catalog scope.");
+	const settings = await loadTauExtensionSettings(ctx, contextSettings);
+	const evidence = await collectSyncEvidence(git, status.root, settings.validation.ignoreGlobs);
+	if (evidence.files.length === 0 && evidence.missingPaths.size === 0)
+		return noChange("Changed files are outside context catalog scope.");
 	const prompt = buildContextSyncPrompt(evidence);
 	const plan = await generateToolValidated(
 		ctx,
@@ -163,7 +166,7 @@ async function runContextSyncLocked(
 	await onStatus?.("Applying context catalog changes");
 	return applyContextSyncPlan(evidence.root, plan, evidence.entries, async () => {
 		const currentEntries = await loadContextEntries(evidence.root);
-		const currentFiles = await collectDirtyFiles(git, evidence.root, currentEntries);
+		const currentFiles = await collectDirtyFiles(git, evidence.root, currentEntries, settings.validation.ignoreGlobs);
 		if ((await computeWorktreeSignature(git, evidence.root, currentFiles)) !== evidence.worktreeSignature)
 			throw new Error("Repository changed during context sync. Rerun context sync.");
 		if ((await computeCatalogSignature(evidence.root)) !== evidence.catalogSignature)
@@ -196,9 +199,13 @@ async function withSyncLock<T>(task: () => Promise<T>): Promise<T> {
 	}
 }
 
-async function collectSyncEvidence(git: GitRunner, root: string): Promise<SyncEvidence> {
+async function collectSyncEvidence(
+	git: GitRunner,
+	root: string,
+	ignoreGlobs: readonly string[],
+): Promise<SyncEvidence> {
 	const entries = await loadContextEntries(root);
-	const files = await collectDirtyFiles(git, root, entries);
+	const files = await collectDirtyFiles(git, root, entries, ignoreGlobs);
 	const dirtyExisting = new Set<string>();
 	for (const file of files)
 		if (file.kind !== "deleted" && (await isFile(join(root, file.path)))) dirtyExisting.add(file.path);
@@ -206,10 +213,15 @@ async function collectSyncEvidence(git: GitRunner, root: string): Promise<SyncEv
 		root,
 		files.filter((file) => dirtyExisting.has(file.path)),
 	);
-	for (const path of dependencies) if (!isContextEligiblePath(path)) dependencies.delete(path);
+	for (const path of dependencies) if (!isContextEligiblePath(path, ignoreGlobs)) dependencies.delete(path);
+	const missingPaths = new Set<string>();
+	for (const entry of entries)
+		for (const path of entry.files)
+			if (isContextEligiblePath(path, ignoreGlobs) && !(await isFile(join(root, path)))) missingPaths.add(path);
 	const affectedIds = new Set<string>();
 	for (const entry of entries) {
 		if (
+			entry.files.some((path) => missingPaths.has(path)) ||
 			entry.files.some(
 				(path) => files.some((file) => file.path === path || file.oldPath === path) || dependencies.has(path),
 			)
@@ -218,12 +230,9 @@ async function collectSyncEvidence(git: GitRunner, root: string): Promise<SyncEv
 	}
 	const affectedConcepts = new Set([...affectedIds].map((id) => id.split("/").slice(0, 2).join("/")));
 	const siblingEntries = entries.filter((entry) => affectedConcepts.has(`${entry.tab}/${entry.concept}`));
-	const missingPaths = new Set<string>();
-	for (const entry of entries)
-		for (const path of entry.files) if (!(await isFile(join(root, path)))) missingPaths.add(path);
 	const siblingFiles = siblingEntries
 		.flatMap((entry) => entry.files)
-		.filter((path) => !missingPaths.has(path) && isContextEligiblePath(path));
+		.filter((path) => !missingPaths.has(path) && isContextEligiblePath(path, ignoreGlobs));
 	const eligibleFiles = new Set([...dirtyExisting, ...dependencies, ...siblingFiles]);
 	const structuralPreviews = new Map<string, string>();
 	for (const path of [...new Set(siblingFiles)].sort()) {
@@ -259,6 +268,7 @@ async function collectDirtyFiles(
 	git: GitRunner,
 	root: string,
 	entries: readonly ContextEntry[],
+	ignoreGlobs: readonly string[],
 ): Promise<SyncDirtyFile[]> {
 	const raw = await git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root });
 	const parts = raw.split("\0").filter(Boolean);
@@ -306,7 +316,8 @@ async function collectDirtyFiles(
 	const sorted = parsed
 		.filter(
 			(file) =>
-				isContextEligiblePath(file.path) || (file.oldPath !== undefined && isContextEligiblePath(file.oldPath)),
+				isContextEligiblePath(file.path, ignoreGlobs) ||
+				(file.oldPath !== undefined && isContextEligiblePath(file.oldPath, ignoreGlobs)),
 		)
 		.sort((a, b) => a.path.localeCompare(b.path));
 	const result: SyncDirtyFile[] = [];
@@ -420,13 +431,7 @@ async function isFile(path: string): Promise<boolean> {
 
 function buildContextSyncPrompt(evidence: SyncEvidence): string {
 	const stale = evidence.entries.flatMap((entry) =>
-		entry.files
-			.filter(
-				(path) =>
-					evidence.missingPaths.has(path) &&
-					!evidence.files.some((file) => file.path === path || file.oldPath === path),
-			)
-			.map((path) => `${entry.id}: ${path}`),
+		entry.files.filter((path) => evidence.missingPaths.has(path)).map((path) => `${entry.id}: ${path}`),
 	);
 	const affected = evidence.entries.filter((entry) => evidence.affectedIds.has(entry.id));
 	const previews = [...evidence.structuralPreviews].map(([path, preview]) => `${path}\n${preview}`);
@@ -434,11 +439,11 @@ function buildContextSyncPrompt(evidence: SyncEvidence): string {
 		[
 			"Synchronize reusable repository context scopes from the supplied Git and catalog evidence.",
 			"Call submit_context_sync exactly once and produce no prose response.",
-			"Return no-change when existing mappings already support likely future work.",
+			"Return no-change only when every eligible changed file has context membership and no stale catalog paths remain.",
 			"Context entries are reusable work scopes, not inventories of every touched file. Prefer updating an existing entry over creating a near-duplicate. Do not create one entry per file.",
 			"Follow direct local dependency candidates only when needed. Do not add package dependencies, generated files, incidental imports, or recursive dependencies.",
 			"Reconsider granularity only inside affected concepts. Preserve broad entries when splitting would duplicate files without improving future work.",
-			"New or unmapped changed files may remain unmapped. Do not clean unrelated stale paths. Use only supplied candidate paths.",
+			"Every eligible changed file must belong to at least one entry. Remove every stale catalog path. Use only supplied candidate paths.",
 			"Example: replace gameplay/player/all with gameplay/player/movement and gameplay/player/input only when every still-useful file from all remains in the final entries.",
 			"Changed-file catalog and current memberships:",
 			...evidence.files.map(
@@ -458,7 +463,7 @@ function buildContextSyncPrompt(evidence: SyncEvidence): string {
 			),
 			"Changed files with no membership:",
 			evidence.files
-				.filter((file) => file.memberships.length === 0 && file.oldMemberships.length === 0)
+				.filter((file) => file.kind !== "deleted" && file.memberships.length === 0)
 				.map((file) => file.path)
 				.join("\n") || "(none)",
 			"Affected entries:",
@@ -467,7 +472,7 @@ function buildContextSyncPrompt(evidence: SyncEvidence): string {
 			[...evidence.affectedConcepts].sort().join("\n") || "(none)",
 			"Resolved direct dependency candidates:",
 			[...evidence.dependencies].sort().join("\n") || "(none)",
-			"Unrelated stale catalog paths (evidence only; do not modify):",
+			"Stale catalog paths that must be removed:",
 			stale.join("\n") || "(none)",
 			"Dirty files:",
 			...evidence.files.map(
@@ -488,6 +493,9 @@ export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence)
 	if (!reason) throw new Error("Context sync reason is required.");
 	if (input.outcome === "no-change") {
 		if ("changes" in input) throw new Error("no-change must not include changes.");
+		const uncovered = evidence.files.filter((file) => file.kind !== "deleted" && file.memberships.length === 0);
+		if (uncovered.length > 0 || evidence.missingPaths.size > 0)
+			throw new Error("no-change cannot leave uncovered changed files or stale catalog paths.");
 		return { outcome: "no-change", reason };
 	}
 	if (!Array.isArray(input.changes) || input.changes.length === 0)
@@ -567,6 +575,12 @@ export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence)
 			if (evidence.eligibleFiles.has(path) && ![...final.values()].some((files) => files.includes(path)))
 				throw new Error(`Deleting entry would orphan surviving file: ${path}`);
 	}
+	for (const path of evidence.dirtyExisting)
+		if (![...final.values()].some((files) => files.includes(path)))
+			throw new Error(`Context sync would leave changed file uncovered: ${path}`);
+	for (const files of final.values())
+		for (const path of files)
+			if (evidence.missingPaths.has(path)) throw new Error(`Context sync would leave stale path: ${path}`);
 	return { outcome: "apply", reason, changes };
 }
 

package/extensions/context/validation.ts

@@ -0,0 +1,73 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { GitRunner } from "../../shared/git.ts";
+import { isContextEligiblePath, isSensitiveContextPath, loadContextEntries } from "./definitions.ts";
+
+export interface ContextValidationResult {
+	stale: Array<{ path: string; ids: string[] }>;
+	uncovered: string[];
+}
+
+export async function validateContextCatalog(
+	git: GitRunner,
+	root: string,
+	ignoreGlobs: readonly string[],
+): Promise<ContextValidationResult> {
+	const entries = await loadContextEntries(root);
+	const memberships = new Map<string, string[]>();
+	for (const entry of entries)
+		for (const file of entry.files) memberships.set(file, [...(memberships.get(file) ?? []), entry.id]);
+
+	const stale: Array<{ path: string; ids: string[] }> = [];
+	for (const [path, ids] of memberships) {
+		if (!isContextEligiblePath(path, ignoreGlobs)) continue;
+		try {
+			if (!(await stat(join(root, path))).isFile()) stale.push({ path, ids });
+		} catch {
+			stale.push({ path, ids });
+		}
+	}
+
+	const status = await git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root });
+	const records = status.split("\0");
+	const dirty = new Set<string>();
+	for (let index = 0; index < records.length; index++) {
+		const record = records[index];
+		if (!record) continue;
+		if (record.startsWith("? ")) {
+			dirty.add(record.slice(2).replaceAll("\\", "/"));
+			continue;
+		}
+		const fields = record.split(" ");
+		const state = fields[1] ?? "..";
+		if (record.startsWith("1 ") && !state.includes("D")) {
+			dirty.add(fields.slice(8).join(" ").replaceAll("\\", "/"));
+		} else if (record.startsWith("2 ")) {
+			if (!state.includes("D")) dirty.add(fields.slice(9).join(" ").replaceAll("\\", "/"));
+			index += 1;
+		} else if (record.startsWith("u ")) {
+			dirty.add(fields.slice(10).join(" ").replaceAll("\\", "/"));
+		}
+	}
+	const uncovered = [...dirty]
+		.filter(
+			(path) => !isSensitiveContextPath(path) && isContextEligiblePath(path, ignoreGlobs) && !memberships.has(path),
+		)
+		.sort((left, right) => left.localeCompare(right));
+	return { stale: stale.sort((left, right) => left.path.localeCompare(right.path)), uncovered };
+}
+
+export function formatContextValidationFailure(result: ContextValidationResult): string | undefined {
+	if (result.stale.length === 0 && result.uncovered.length === 0) return undefined;
+	const output = ["Context catalog validation failed."];
+	if (result.stale.length)
+		output.push(
+			"",
+			"Stale context file references:",
+			...result.stale.map((item) => `- ${item.path} (${item.ids.sort().join(", ")})`),
+		);
+	if (result.uncovered.length)
+		output.push("", "Changed files with no context membership:", ...result.uncovered.map((path) => `- ${path}`));
+	output.push("", "Run context_sync to reconcile the context catalog.");
+	return output.join("\n");
+}

package/extensions/publish/README.md

@@ -8,4 +8,4 @@ Create a tagged Tau release and monitor its GitHub Actions npm publish run.
 /publish
 ```
 
-`/publish` requires a clean Git working tree and authenticated GitHub CLI. It recommends a semantic version bump from commits since the previous release tag, asks for confirmation, then pushes a release tag. GitHub Actions publishes the TUI package before the agent package through npm trusted publishing.
+`/publish` requires a clean Git working tree, authenticated GitHub CLI, and public approved npm package sources. It recommends a semantic version bump from commits since the previous release tag, asks for confirmation, then pushes a release tag. GitHub Actions publishes the TUI package before the agent package through npm trusted publishing.

package/extensions/publish/index.ts

@@ -55,6 +55,7 @@ async function publish(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<
 	if (repo.fileCount > 0)
 		throw new Error("Working tree is not clean. Commit or stash every change before publishing.");
 	await run(pi, ctx, "gh", ["auth", "status"], repo.root);
+	await run(pi, ctx, "npm", ["run", "check:package-sources"], repo.root);
 
 	const manifests = await loadManifests(repo.root);
 	const currentVersion = sharedVersion(manifests);

package/extensions/runtime-context/README.md

@@ -0,0 +1,5 @@
+# Runtime Context
+
+Supplies Tau with the current local date and an initial root directory snapshot as hidden session context. The snapshot remains fixed until the extension runtime restarts, while the date updates when the local day changes.
+
+After changing this extension, run `/reload` before testing the new behavior.

package/extensions/runtime-context/context.ts

@@ -0,0 +1,138 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { type Dirent, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const ROOT_SNAPSHOT_MAX_PATHS = 300;
+
+interface SnapshotEntry {
+	dirent: Dirent;
+	path: string;
+}
+
+export interface RuntimeContext {
+	cwd: string;
+	rootSnapshot: readonly string[];
+}
+
+export function freezeRuntimeContext(cwd: string): RuntimeContext {
+	return { cwd: cwd.replace(/\\/g, "/"), rootSnapshot: listRootSnapshot(cwd) };
+}
+
+export function formatLocalDateKey(date: Date): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+export function formatLocalDisplayDate(date: Date): string {
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December",
+	];
+	return `${date.getDate()} ${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+
+export function fingerprintRuntimeSnapshot(context: RuntimeContext): string {
+	return createHash("sha256")
+		.update(JSON.stringify({ version: 1, cwd: context.cwd, paths: context.rootSnapshot }))
+		.digest("hex");
+}
+
+export function formatRuntimeContextMessage(displayDate: string, rootSnapshot: readonly string[] | undefined): string {
+	const blocks = [`Current local date: ${displayDate}`];
+	if (rootSnapshot?.length) {
+		blocks.push(`Root directory snapshot (depth 2):\n${rootSnapshot.map((path) => `- ${path}`).join("\n")}`);
+	}
+	return blocks.join("\n");
+}
+
+function listRootSnapshot(cwd: string): string[] {
+	const root = resolve(cwd);
+	const rootEntries = listSnapshotEntries(root, ".");
+	const ignoredRootPaths = gitIgnoredPaths(
+		root,
+		rootEntries.map((entry) => entry.path),
+	);
+	const visibleRootEntries = rootEntries.filter(
+		(entry) => !isAlwaysHiddenFromSnapshot(entry.dirent.name) && !ignoredRootPaths.has(entry.path),
+	);
+	const childEntriesByParent = new Map<string, SnapshotEntry[]>();
+	const childPaths: string[] = [];
+
+	for (const entry of visibleRootEntries) {
+		if (!entry.dirent.isDirectory()) continue;
+		const childEntries = listSnapshotEntries(root, entry.path).filter(
+			(childEntry) => !isAlwaysHiddenFromSnapshot(childEntry.dirent.name),
+		);
+		childEntriesByParent.set(entry.path, childEntries);
+		childPaths.push(...childEntries.map((childEntry) => childEntry.path));
+	}
+
+	const ignoredChildPaths = gitIgnoredPaths(root, childPaths);
+	const paths: string[] = [];
+
+	for (const entry of visibleRootEntries) {
+		pushSnapshotPath(paths, entry);
+		if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) break;
+
+		for (const childEntry of childEntriesByParent.get(entry.path) ?? []) {
+			if (ignoredChildPaths.has(childEntry.path)) continue;
+			pushSnapshotPath(paths, childEntry);
+			if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) break;
+		}
+	}
+
+	return paths.length === ROOT_SNAPSHOT_MAX_PATHS ? [...paths, "..."] : paths;
+}
+
+function listSnapshotEntries(root: string, relativePath: string): SnapshotEntry[] {
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(join(root, relativePath), { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	return entries
+		.sort((left, right) => left.name.localeCompare(right.name))
+		.map((dirent) => ({
+			dirent,
+			path: relativePath === "." ? dirent.name : `${relativePath}/${dirent.name}`,
+		}));
+}
+
+function gitIgnoredPaths(root: string, paths: readonly string[]): Set<string> {
+	if (paths.length === 0) return new Set();
+
+	const result = spawnSync("git", ["check-ignore", "-z", "--stdin"], {
+		cwd: root,
+		encoding: "utf8",
+		input: `${paths.join("\0")}\0`,
+	});
+
+	if (result.status === 0 || result.status === 1) {
+		return new Set(result.stdout.split("\0").filter(Boolean));
+	}
+	return new Set(paths.filter((path) => path.split("/").includes("node_modules")));
+}
+
+function isAlwaysHiddenFromSnapshot(name: string): boolean {
+	return name === ".git";
+}
+
+function pushSnapshotPath(paths: string[], entry: SnapshotEntry): void {
+	if (paths.length >= ROOT_SNAPSHOT_MAX_PATHS) return;
+	paths.push(entry.dirent.isDirectory() ? `${entry.path}/` : entry.path);
+}