@first-tree-ai/context-tree 0.1.11 → 0.1.12

package/dist/cli/index.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import path, { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
+import path, { basename, delimiter, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
-import childProcess, { spawnSync } from "node:child_process";
-import fs, { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import childProcess, { spawn, spawnSync } from "node:child_process";
+import fs, { accessSync, chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region \0rolldown/runtime.js
@@ -7468,6 +7469,46 @@ object({
 	ok: literal(false),
 	schemaVersion: literal(1)
 }).strict();
+const cleanupAgentSchema = union([literal("codex"), literal("claude")]);
+const cleanupScheduleSchema = object({
+	id: string$2().regex(/^[a-f0-9]{64}$/u),
+	projectPath: string$2().refine(isAbsolute),
+	identity: string$2(),
+	agent: cleanupAgentSchema,
+	model: string$2().min(1),
+	everyMinutes: number().int().positive().max(525600),
+	nodePath: string$2().refine(isAbsolute),
+	cliPath: string$2().refine(isAbsolute),
+	agentPath: string$2().refine(isAbsolute),
+	searchPath: string$2(),
+	enabled: boolean()
+}).strict();
+const cleanupOutcomeSchema = object({
+	at: number(),
+	outcome: union([
+		literal("inactive"),
+		literal("unchanged"),
+		literal("noop"),
+		literal("published"),
+		literal("running"),
+		literal("failed"),
+		literal("cancelled"),
+		literal("publication-uncertain")
+	]),
+	worktreePath: string$2().optional(),
+	sha: string$2().optional(),
+	message: string$2().optional()
+}).strict();
+const cleanupResultSchema = object({
+	schemaVersion: literal(1),
+	schedule: cleanupScheduleSchema.nullable(),
+	registered: boolean(),
+	running: boolean(),
+	inactive: boolean(),
+	lastActivity: number().nullable(),
+	latest: cleanupOutcomeSchema.nullable()
+}).strict();
+const cleanupRunResultSchema = cleanupOutcomeSchema.extend({ schemaVersion: literal(1) }).strict();
 //#endregion
 //#region src/core/internal/errors.ts
 /**
@@ -25700,164 +25741,969 @@ function readPackageVersion() {
 	return manifest.version;
 }
 //#endregion
-//#region src/core/scaffold.ts
-function template(name, values) {
-	let result = readFileSync(resolvePackagedResource("templates", name), "utf8");
-	for (const [key, value] of Object.entries(values)) result = result.replaceAll(`{{${key}}}`, value);
-	return result;
-}
-/** Templated regular files, written before the CLAUDE.md -> AGENTS.md symlink. */
-const TEMPLATED_FILES = [
-	["NODE.md", "root-node.md"],
-	["AGENTS.md", "AGENTS.md"],
-	[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
-];
-const SCAFFOLD_FILES = [
-	"NODE.md",
-	"AGENTS.md",
-	"CLAUDE.md",
-	".github/workflows/validate-context-tree.yml"
-];
-function initializeGitRepository(root, runner) {
-	gitCommand([
-		"init",
-		"--quiet",
-		"--",
-		root
+//#region src/core/sync.ts
+/**
+* Local trees report their checked-out state without network access. GitHub
+* trees fast-forward the exact checked-out branch once, then revalidate.
+*/
+function syncProject(projectPath, runner) {
+	const connection = resolveConnectionRecord(projectPath, runner);
+	const root = connection.tree.path;
+	const branch = git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
 	], {
-		message: "Failed to initialize Git repository.",
+		message: "Failed to resolve the checked-out branch.",
 		runner
 	});
-	return git(root, [
+	if (connection.tree.kind === "github") {
+		git(root, [
+			"pull",
+			"--ff-only",
+			"origin",
+			branch
+		], {
+			message: "Fast-forwarding the Context Tree failed.",
+			runner
+		});
+		validateStoredTreeState(connection.tree, runner);
+	}
+	return {
+		branch,
+		schemaVersion: 1,
+		sha: git(root, ["rev-parse", "HEAD"], {
+			message: "Failed to resolve the Context Tree commit.",
+			runner
+		}),
+		tree: connection.tree
+	};
+}
+//#endregion
+//#region src/core/write.ts
+const TASK_BRANCH_PREFIX = "context-tree/write/";
+/** A prepared worktree left untouched for longer than this is treated as abandoned. */
+const ABANDONED_WRITE_AGE_MS = 1440 * 60 * 1e3;
+/** Synchronize first, then create an isolated task worktree at the exact HEAD. */
+function prepareContextWrite(projectPath, runner) {
+	const synchronized = syncProject(projectPath, runner);
+	const root = synchronized.tree.path;
+	reclaimAbandonedWrites(root, synchronized.branch, runner);
+	const destination = mkdtempSync(join(tmpdir(), "context-tree-write-"));
+	const taskBranch = `${TASK_BRANCH_PREFIX}${basename(destination)}`;
+	try {
+		git(root, [
+			"worktree",
+			"add",
+			"--quiet",
+			"-b",
+			taskBranch,
+			destination,
+			synchronized.sha
+		], {
+			message: "Creating the isolated write worktree failed.",
+			runner
+		});
+		return {
+			schemaVersion: 1,
+			worktreePath: realDirectoryWithoutSymlinks(destination, "Write worktree")
+		};
+	} catch (error) {
+		rmSync(destination, {
+			force: true,
+			recursive: true
+		});
+		throw error;
+	}
+}
+/** Commit every pending change, then fast-forward locally or push once. */
+function finishContextWrite(options, runner) {
+	const connection = resolveConnectionRecord(options.projectPath, runner);
+	const root = connection.tree.path;
+	const { taskBranch, worktreePath } = validatePreparedWorktree(root, options.worktreePath, runner);
+	const branch = git(root, [
 		"symbolic-ref",
 		"--short",
 		"HEAD"
 	], {
-		message: "Failed to resolve the initial Git branch during repository initialization.",
+		message: "Failed to resolve the connected checkout branch.",
 		runner
 	});
-}
-function commitScaffold(root, runner) {
-	for (const file of SCAFFOLD_FILES) git(root, [
-		"add",
-		"--",
-		file
+	if (git(worktreePath, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
 	], {
-		message: "Failed to stage the scaffold files.",
+		message: "Failed to inspect the prepared worktree.",
+		runner
+	}).length === 0) throw new Error("The prepared worktree has no pending changes.");
+	if (!verifyTree(worktreePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to commit an invalid Context Tree; run context-tree verify --tree-path ${worktreePath}.`);
+	git(worktreePath, ["add", "--all"], {
+		message: "Staging the Context Tree changes failed.",
 		runner
 	});
-	git(root, [
-		"-c",
-		"user.name=Context Tree",
-		"-c",
-		"user.email=context-tree@localhost",
+	git(worktreePath, [
 		"-c",
 		"commit.gpgsign=false",
 		"commit",
 		"--quiet",
 		"-m",
-		"Initialize Context Tree"
+		options.message
 	], {
-		message: "Failed to commit the scaffold.",
+		message: "Committing the Context Tree changes failed.",
 		runner
 	});
-	return git(root, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the scaffold commit.",
+	const sha = git(worktreePath, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the write commit.",
 		runner
 	});
-}
-function scaffoldTree(options) {
-	const name = treeNameSchema.parse(options.name);
-	const root = resolve(options.path);
-	const destination = lstatSync(root, { throwIfNoEntry: false });
-	if (destination !== void 0) {
-		if (destination.isSymbolicLink() || !destination.isDirectory()) throw new Error(`Refusing to scaffold into a symlink or non-directory destination: ${root}`);
-		if (readdirSync(root).length > 0) throw new Error(`Refusing to scaffold into a non-empty directory: ${root}`);
-	}
-	const initialBranch = initializeGitRepository(root, options.runner);
-	const values = {
-		branchJson: JSON.stringify(initialBranch),
-		packageVersion: readPackageVersion(),
-		title: name,
-		titleJson: JSON.stringify(name)
-	};
-	for (const [relativePath, source] of TEMPLATED_FILES) {
-		const path = join(root, relativePath);
-		mkdirSync(dirname(path), { recursive: true });
-		writeFileSync(path, template(source, values), {
-			encoding: "utf8",
-			flag: "wx",
-			mode: 420
+	try {
+		if (connection.tree.kind === "local") git(root, [
+			"merge",
+			"--ff-only",
+			taskBranch
+		], {
+			message: "Fast-forwarding the local Context Tree failed.",
+			runner
+		});
+		else git(worktreePath, [
+			"push",
+			"origin",
+			`HEAD:refs/heads/${branch}`
+		], {
+			message: "Publishing the Context Tree write failed.",
+			runner
 		});
+	} catch (error) {
+		if (isNonFastForward(error)) throw new ContextTreeError(CLI_ERROR_CODES.writeOutdated, `The Context Tree advanced; the prepared worktree is preserved at ${worktreePath}.`);
+		throw error;
 	}
-	symlinkSync("AGENTS.md", join(root, "CLAUDE.md"), "file");
-	if (!verifyTree(root).ok) throw new Error("Refusing to commit an invalid Context Tree scaffold.");
+	removeWorktree(root, worktreePath, taskBranch, runner);
 	return {
-		branch: initialBranch,
-		commit: commitScaffold(root, options.runner),
-		root
+		branch,
+		schemaVersion: 1,
+		sha
 	};
 }
-//#endregion
-//#region src/core/create.ts
-function projectName(canonicalRoot) {
-	const normalized = basename(canonicalRoot).toLowerCase().replace(/[^a-z\d._-]+/gu, "-").replace(/-{2,}/gu, "-").replace(/^[-.]+/u, "").replace(/[-.]+$/u, "").slice(0, 40);
-	return /^[a-z\d]/u.test(normalized) ? normalized : "project";
+function gitCommonDirectory(root, runner) {
+	const value = git(root, ["rev-parse", "--git-common-dir"], {
+		message: "Failed to resolve the Git common directory.",
+		runner
+	});
+	return realDirectoryWithoutSymlinks(isAbsolute(value) ? value : resolve(root, value), "Git common directory");
 }
-function existingCreateResult(canonical, destination, runner) {
-	const branch = git(destination, [
+function validatePreparedWorktree(root, suppliedPath, runner) {
+	const worktreePath = realDirectoryWithoutSymlinks(suppliedPath, "Prepared worktree");
+	if (gitCommonDirectory(worktreePath, runner) !== gitCommonDirectory(root, runner)) throw new Error("The prepared worktree does not belong to the connected Context Tree.");
+	const taskBranch = git(worktreePath, [
 		"symbolic-ref",
 		"--short",
 		"HEAD"
 	], {
-		message: "Failed to resolve the managed tree branch.",
-		runner
-	});
-	const commitSha = git(destination, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the managed tree commit.",
+		message: "Failed to resolve the worktree branch.",
 		runner
 	});
-	linkProjectInstructions(canonical);
+	if (!taskBranch.startsWith(TASK_BRANCH_PREFIX)) throw new Error("The prepared worktree is not on a reserved Context Tree write branch.");
 	return {
-		branch,
-		commitSha,
-		created: false,
-		schemaVersion: 1,
-		title: readRootNode(destination).frontmatter.title,
-		treePath: destination
+		taskBranch,
+		worktreePath
 	};
 }
-/** Create and connect the project's uniquely named managed local Context Tree. */
-function createProject(projectPath, runner) {
-	const canonical = canonicalProjectRoot(projectPath, runner);
-	const name = treeNameSchema.parse(`${projectName(canonical)}-context-tree`);
-	const destination = join(managedTreesRoot(), name);
-	const current = findConnectionRecord(canonical, runner);
-	if (current !== void 0 && current.tree.path !== destination) throw new Error(`This project is already connected to a Context Tree at ${current.tree.path}; run context-tree connect ${name} to switch.`);
-	if (existsSync(destination)) {
-		const entry = lstatSync(destination);
-		if (entry.isSymbolicLink() || !entry.isDirectory() || current === void 0) throw new Error(`Managed Context Tree name ${name} is occupied; run context-tree connect ${name}.`);
-		return existingCreateResult(canonical, destination, runner);
-	}
-	mkdirSync(destination, { mode: 448 });
-	try {
-		const scaffold = scaffoldTree({
-			name,
-			path: destination,
-			runner
-		});
-		upsertConnection({
-			projectPath: canonical,
-			tree: {
-				kind: "local",
-				path: scaffold.root
-			}
-		}, runner);
-		linkProjectInstructions(canonical);
-		return {
-			branch: scaffold.branch,
-			commitSha: scaffold.commit,
-			created: true,
+function isNonFastForward(error) {
+	return error instanceof CommandError && /non-fast-forward|fetch first|tip of your current branch is behind|not possible to fast-forward|diverg/i.test(error.stderr);
+}
+function removeWorktree(root, worktreePath, taskBranch, runner) {
+	git(root, [
+		"worktree",
+		"remove",
+		worktreePath
+	], {
+		message: "Removing the write worktree failed.",
+		runner
+	});
+	git(root, [
+		"branch",
+		"-D",
+		taskBranch
+	], {
+		message: "Deleting the write branch failed.",
+		runner
+	});
+}
+/** Map every reserved write branch that still has a registered worktree to its path. */
+function listWriteWorktrees(root, runner) {
+	const paths = /* @__PURE__ */ new Map();
+	const output = optionalGit(root, [
+		"worktree",
+		"list",
+		"--porcelain"
+	], runner);
+	if (output === void 0) return paths;
+	let path;
+	for (const record of output.split("\n")) {
+		if (record.startsWith("worktree ")) {
+			path = record.slice(9).trim();
+			continue;
+		}
+		if (!record.startsWith("branch refs/heads/")) continue;
+		const branch = record.slice(18).trim();
+		if (path !== void 0 && branch.startsWith(TASK_BRANCH_PREFIX)) paths.set(branch, path);
+	}
+	return paths;
+}
+function millisecondsSinceModification(path) {
+	try {
+		return Date.now() - statSync(path).mtimeMs;
+	} catch {
+		return;
+	}
+}
+/**
+* A preparation is abandoned only when it carries no commit the connected
+* checkout lacks, has no pending edits, and has gone untouched. Every unknown
+* answer preserves the worktree, so a `WRITE_OUTDATED` commit awaiting its
+* retry and a concurrent preparation both survive.
+*/
+function isAbandonedWrite(root, branch, checkoutBranch, path, runner) {
+	if (optionalGit(root, [
+		"rev-list",
+		"--count",
+		branch,
+		"--not",
+		checkoutBranch
+	], runner) !== "0") return false;
+	if (path === void 0) return true;
+	const age = millisecondsSinceModification(path);
+	if (age === void 0 || age < ABANDONED_WRITE_AGE_MS) return false;
+	return optionalGit(path, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	], runner) === "";
+}
+/** Reclaim earlier preparations that were never finished. Every step is best effort. */
+function reclaimAbandonedWrites(root, checkoutBranch, runner) {
+	optionalGit(root, ["worktree", "prune"], runner);
+	const paths = listWriteWorktrees(root, runner);
+	const branches = optionalGit(root, [
+		"for-each-ref",
+		"--format=%(refname:short)",
+		`refs/heads/${TASK_BRANCH_PREFIX}`
+	], runner);
+	if (branches === void 0) return;
+	for (const branch of branches.split("\n").filter((value) => value.length > 0)) {
+		const path = paths.get(branch);
+		if (!isAbandonedWrite(root, branch, checkoutBranch, path, runner)) continue;
+		if (path !== void 0) optionalGit(root, [
+			"worktree",
+			"remove",
+			path
+		], runner);
+		optionalGit(root, [
+			"branch",
+			"-D",
+			branch
+		], runner);
+	}
+}
+//#endregion
+//#region src/core/cleanup/agent.ts
+function agentArguments(config) {
+	return config.agent === "codex" ? [
+		"exec",
+		"--sandbox",
+		"workspace-write",
+		"-c",
+		"approval_policy=\"never\"",
+		"-c",
+		"model_reasoning_effort=\"low\"",
+		"--model",
+		config.model,
+		"--ephemeral",
+		"-"
+	] : [
+		"-p",
+		"--model",
+		config.model,
+		"--permission-mode",
+		"acceptEdits",
+		"--tools",
+		"Read,Edit,Write,Glob,Grep",
+		"--allowedTools",
+		"Read,Edit,Write,Glob,Grep",
+		"--no-session-persistence"
+	];
+}
+async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3) {
+	if (signal.aborted) throw new Error("Cleanup cancelled.");
+	await new Promise((resolve, reject) => {
+		const child = spawn(config.agentPath, agentArguments(config), {
+			cwd: worktree,
+			env: {
+				...process.env,
+				PATH: config.searchPath,
+				CONTEXT_TREE_CLEANUP: "1"
+			},
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore"
+			]
+		});
+		let failure;
+		let termination;
+		const stop = (reason) => {
+			if (termination !== void 0) return;
+			failure = reason;
+			clearTimeout(timer);
+			const descendants = child.pid === void 0 ? [] : childProcesses(child.pid);
+			termination = new Promise((finished) => {
+				setTimeout(() => {
+					for (const pid of descendants) kill(pid, "SIGKILL");
+					child.kill("SIGKILL");
+					finished();
+				}, 5e3);
+			});
+			for (const pid of descendants.reverse()) kill(pid, "SIGTERM");
+			child.kill("SIGTERM");
+		};
+		const abort = () => stop("Cleanup cancelled.");
+		const timer = setTimeout(() => stop("Cleanup agent exceeded its 15-minute timeout."), timeoutMs);
+		signal.addEventListener("abort", abort, { once: true });
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(prompt);
+		child.on("error", () => {
+			failure = "Unable to launch cleanup agent.";
+		});
+		child.on("close", async (code) => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", abort);
+			await termination;
+			if (failure || code !== 0) reject(new Error(failure ?? "Cleanup agent failed; check CLI authentication and model access."));
+			else resolve();
+		});
+	});
+}
+function kill(pid, signal) {
+	try {
+		process.kill(pid, signal);
+	} catch {}
+}
+function childProcesses(parent) {
+	const pairs = spawnSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8" }).stdout?.trim().split("\n").map((line) => line.trim().split(/\s+/u).map(Number)) ?? [];
+	const children = [];
+	const visit = (pid) => {
+		for (const [child, owner] of pairs) if (owner === pid && child !== void 0 && !children.includes(child)) {
+			children.push(child);
+			visit(child);
+		}
+	};
+	visit(parent);
+	return children;
+}
+//#endregion
+//#region src/core/cleanup/store.ts
+function privateDirectory(path) {
+	const parent = join(path, "..");
+	if (!lstatSync(path, { throwIfNoEntry: false })) {
+		privateDirectory(parent);
+		mkdirSync(path, { mode: 448 });
+	}
+	return realDirectoryWithoutSymlinks(path, "Cleanup directory");
+}
+function cleanupRoot() {
+	return privateDirectory(join(realpathSync(homedir()), ".context-tree", "cleanup"));
+}
+function statePath(id, name) {
+	if (!/^[a-f0-9]{64}$/u.test(id) || !/^[a-z-]+$/u.test(name)) throw new Error("Invalid cleanup state key.");
+	return join(cleanupRoot(), `${id}.${name}`);
+}
+function readState(path) {
+	if (!lstatSync(dirname(path), { throwIfNoEntry: false })) return void 0;
+	realDirectoryWithoutSymlinks(dirname(path), "Cleanup state parent");
+	const entry = lstatSync(path, { throwIfNoEntry: false });
+	if (!entry) return void 0;
+	if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Cleanup state must be a regular file.");
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+function atomicState(path, value) {
+	atomicFile(path, `${JSON.stringify(value)}\n`);
+}
+function atomicFile(path, value, mode = 384) {
+	const entry = lstatSync(path, { throwIfNoEntry: false });
+	if (entry && (!entry.isFile() || entry.isSymbolicLink())) throw new Error("Unsafe cleanup file.");
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	writeFileSync(temporary, value, {
+		mode,
+		flag: "wx"
+	});
+	try {
+		renameSync(temporary, path);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+function treeIdentity(tree) {
+	return tree.kind === "github" ? `github:${tree.repository.toLowerCase()}` : `local:${realpathSync(tree.path)}`;
+}
+function identityId(identity) {
+	return createHash("sha256").update(identity).digest("hex");
+}
+function schedules() {
+	return readdirSync(cleanupRoot()).filter((name) => name.endsWith(".config")).map((name) => loadSchedule(name.slice(0, -7)));
+}
+function loadSchedule(id) {
+	const config = cleanupScheduleSchema.parse(readState(statePath(id, "config")));
+	if (config.id !== id || identityId(config.identity) !== id) throw new Error("Cleanup identity is corrupt.");
+	return config;
+}
+function activity(id) {
+	const parsed = number().finite().safeParse(readState(statePath(id, "activity")));
+	return parsed.success ? parsed.data : null;
+}
+//#endregion
+//#region src/core/cleanup/scheduler.ts
+function xml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+function shellQuote(value) {
+	if (value.includes("\0")) throw new Error("Unsupported control character in scheduler argument.");
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function unitQuote(value) {
+	if (/[\n\r\0]/u.test(value)) throw new Error("Unsupported control character in scheduler argument.");
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("%", "%%").replaceAll("$", "$$")}"`;
+}
+function nativeScheduler(platform = process.platform, home = homedir(), runner = defaultRunner) {
+	if (platform !== "darwin" && platform !== "linux") throw new Error("Cleanup schedules require macOS LaunchAgents or Linux systemd user services.");
+	const label = (config) => `ai.context-tree.cleanup.${config.id}`;
+	const domain = `gui/${process.getuid?.() ?? 0}`;
+	const command = (args, allowMissing = false) => {
+		const result = runner(platform === "darwin" ? "launchctl" : "systemctl", platform === "darwin" ? args : ["--user", ...args]);
+		if (result.status !== 0 && !(allowMissing && /could not find service|not loaded|not found|does not exist/i.test(result.stderr + result.stdout))) throw new Error("Native cleanup scheduler operation failed; inspect your user scheduler.");
+		return result.status === 0 ? result.stdout : "";
+	};
+	const directory = () => privateDirectory(platform === "darwin" ? join(home, "Library", "LaunchAgents") : join(home, ".config", "systemd", "user"));
+	const launcherDirectory = (config) => {
+		if (!/^[a-f0-9]{64}$/u.test(config.id)) throw new Error("Invalid cleanup state key.");
+		return privateDirectory(join(home, ".context-tree", "cleanup", "launchers", config.id));
+	};
+	const status = (config) => {
+		if (platform === "darwin") {
+			const output = command(["print", `${domain}/${label(config)}`], true);
+			return {
+				registered: output.length > 0,
+				running: /state = running|pid = \d+/u.test(output)
+			};
+		}
+		const timer = command([
+			"show",
+			`${label(config)}.timer`,
+			"--property=LoadState,ActiveState"
+		], true);
+		const service = command([
+			"show",
+			`${label(config)}.service`,
+			"--property=ActiveState"
+		], true);
+		return {
+			registered: /ActiveState=active/u.test(timer),
+			running: /ActiveState=(active|activating|deactivating)/u.test(service)
+		};
+	};
+	return {
+		status,
+		install(config) {
+			const args = [
+				config.nodePath,
+				config.cliPath,
+				"cleanup",
+				"run",
+				"--schedule-id",
+				config.id,
+				"--project-path",
+				config.projectPath,
+				"--json"
+			];
+			const name = label(config);
+			if (platform === "darwin") {
+				const file = join(directory(), `${name}.plist`);
+				const launcher = join(launcherDirectory(config), "context-tree-cleanup");
+				atomicFile(launcher, `#!/bin/sh\nexec ${args.map(shellQuote).join(" ")}\n`, 448);
+				if (status(config).registered) command(["bootout", `${domain}/${name}`]);
+				atomicFile(file, `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>${name}</string><key>ProgramArguments</key><array><string>${xml(launcher)}</string></array><key>StartInterval</key><integer>${config.everyMinutes * 60}</integer><key>RunAtLoad</key><false/><key>AbandonProcessGroup</key><false/><key>WorkingDirectory</key><string>${xml(config.projectPath)}</string><key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(config.searchPath)}</string></dict></dict></plist>`);
+				command([
+					"bootstrap",
+					domain,
+					file
+				]);
+			} else {
+				atomicFile(join(directory(), `${name}.service`), `[Unit]\nDescription=Context Tree cleanup\n[Service]\nType=oneshot\nExecStart=${args.map(unitQuote).join(" ")}\nEnvironment=${unitQuote(`PATH=${config.searchPath}`)}\nKillMode=control-group\nTimeoutStopSec=10\nTimeoutStartSec=30min\n`);
+				atomicFile(join(directory(), `${name}.timer`), `[Unit]\nDescription=Context Tree cleanup timer\n[Timer]\nOnActiveSec=${config.everyMinutes}min\nOnUnitInactiveSec=${config.everyMinutes}min\nUnit=${name}.service\n[Install]\nWantedBy=timers.target\n`);
+				command(["daemon-reload"]);
+				command(["enable", `${name}.timer`]);
+				command(["restart", `${name}.timer`]);
+			}
+		},
+		remove(config) {
+			const name = label(config);
+			if (platform === "darwin") {
+				command(["bootout", `${domain}/${name}`], true);
+				const launcherDir = launcherDirectory(config);
+				const launcher = join(launcherDir, "context-tree-cleanup");
+				const entry = lstatSync(launcher, { throwIfNoEntry: false });
+				if (entry && (!entry.isFile() || entry.isSymbolicLink())) throw new Error("Unsafe cleanup file.");
+				rmSync(join(directory(), `${name}.plist`), { force: true });
+				rmSync(launcher, { force: true });
+				if (readdirSync(launcherDir).length === 0) rmdirSync(launcherDir);
+			} else {
+				command([
+					"disable",
+					"--now",
+					`${name}.timer`
+				], true);
+				command(["stop", `${name}.service`], true);
+				for (const suffix of ["timer", "service"]) rmSync(join(directory(), `${name}.${suffix}`), { force: true });
+				command(["daemon-reload"]);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/core/cleanup/index.ts
+function parseCleanupInterval(value = "1h") {
+	const match = /^(\d+)(m|h|d)$/u.exec(value);
+	const minutes = Number(match?.[1]) * (match?.[2] === "d" ? 1440 : match?.[2] === "h" ? 60 : 1);
+	if (!match || !Number.isSafeInteger(minutes) || minutes < 1 || minutes > 525600) throw new Error("Cleanup cadence must be a positive whole-minute duration (for example 30m, 1h, 1d), at most 365d.");
+	return minutes;
+}
+function executable(name) {
+	for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+		if (!directory) continue;
+		const path = resolve(directory, name);
+		try {
+			accessSync(path, constants.X_OK);
+			if (lstatSync(realpathSync(path)).isFile()) return realpathSync(path);
+		} catch {}
+	}
+	throw new Error(`Install ${name} on PATH before scheduling cleanup.`);
+}
+function findSchedule(project) {
+	const canonical = canonicalProjectRoot(project);
+	const owned = schedules().filter((config) => config.projectPath === canonical);
+	if (owned.length > 1) throw new Error("Multiple saved cleanup identities for this project; remove the old schedule first.");
+	if (owned[0]) return owned[0];
+	const connection = findConnectionRecord(canonical);
+	return connection ? schedules().find((config) => config.id === identityId(treeIdentity(connection.tree))) : void 0;
+}
+function cleanupStatus(project, scheduler = nativeScheduler()) {
+	const config = findSchedule(project);
+	if (!config) return {
+		schemaVersion: 1,
+		schedule: null,
+		registered: false,
+		running: false,
+		inactive: true,
+		lastActivity: null,
+		latest: null
+	};
+	const lastActivity = activity(config.id);
+	const latest = readState(statePath(config.id, "latest"));
+	return cleanupResultSchema.parse({
+		schemaVersion: 1,
+		schedule: config,
+		...scheduler.status(config),
+		inactive: lastActivity === null || Date.now() - lastActivity > 864e5,
+		lastActivity,
+		latest: latest === void 0 ? null : cleanupOutcomeSchema.parse(latest)
+	});
+}
+function manage(operation) {
+	const path = join(cleanupRoot(), ".management-lock");
+	try {
+		mkdirSync(path, { mode: 448 });
+	} catch {
+		throw new Error("Another cleanup management operation is in progress.");
+	}
+	try {
+		return operation();
+	} finally {
+		rmSync(path, { recursive: true });
+	}
+}
+function scheduleCleanup(options, scheduler = nativeScheduler()) {
+	return manage(() => scheduleCleanupUnlocked(options, scheduler));
+}
+function removeCleanup(project, scheduler = nativeScheduler()) {
+	return manage(() => removeCleanupUnlocked(project, scheduler));
+}
+function scheduleCleanupUnlocked(options, scheduler = nativeScheduler()) {
+	const agent = cleanupAgentSchema.parse(options.agent);
+	const connection = resolveConnectionRecord(options.projectPath);
+	const identity = treeIdentity(connection.tree);
+	const previous = findSchedule(connection.projectPath);
+	if (previous?.enabled && previous.identity !== identity) throw new Error("Remove the previous cleanup schedule before scheduling a changed connection.");
+	const id = identityId(identity);
+	const config = cleanupScheduleSchema.parse({
+		id,
+		projectPath: connection.projectPath,
+		identity,
+		agent,
+		model: options.model ?? (agent === "codex" ? "gpt-5.6-luna" : "claude-haiku-4-5"),
+		everyMinutes: parseCleanupInterval(options.every),
+		nodePath: realpathSync(process.execPath),
+		cliPath: resolvePackagedResource("dist", "cli", "index.mjs"),
+		agentPath: executable(agent),
+		searchPath: process.env.PATH ?? "",
+		enabled: true
+	});
+	if (scheduler.status(config).running || lstatSync(statePath(id, "lock"), { throwIfNoEntry: false })) throw new Error("Cleanup is running; remove it before changing the schedule.");
+	if (previous && previous.id !== id) rmSync(statePath(previous.id, "config"));
+	atomicState(statePath(id, "config"), config);
+	atomicState(statePath(id, "activity"), Date.now());
+	try {
+		scheduler.install(config);
+	} catch (error) {
+		atomicState(statePath(id, "config"), {
+			...config,
+			enabled: false
+		});
+		throw error;
+	}
+	return cleanupStatus(connection.projectPath, scheduler);
+}
+function removeCleanupUnlocked(project, scheduler = nativeScheduler()) {
+	const config = findSchedule(project);
+	if (!config) return cleanupStatus(project, scheduler);
+	atomicState(statePath(config.id, "config"), {
+		...config,
+		enabled: false
+	});
+	scheduler.remove(config);
+	const latest = cleanupOutcomeSchema.safeParse(readState(statePath(config.id, "latest")));
+	if (latest.success && latest.data.outcome === "running") atomicState(statePath(config.id, "latest"), {
+		...latest.data,
+		at: Date.now(),
+		outcome: latest.data.message === "publishing" ? "publication-uncertain" : "cancelled",
+		message: "Stopped. Unfinished worktrees are preserved; publication already underway may have completed. No rollback or retry was attempted."
+	});
+	const owner = number().int().positive().safeParse(readState(join(statePath(config.id, "lock"), "owner")));
+	if (owner.success && !alive(owner.data)) rmSync(statePath(config.id, "lock"), { recursive: true });
+	return cleanupStatus(project, scheduler);
+}
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+	}
+}
+/** CLI-only, best effort: the background process and all its child CLIs are excluded. */
+function recordCleanupActivity(options) {
+	if (process.env.CONTEXT_TREE_CLEANUP === "1") return;
+	try {
+		const tree = options.projectPath ? findConnectionRecord(options.projectPath)?.tree : void 0;
+		for (const config of schedules()) {
+			if (!config.enabled) continue;
+			let matches = tree !== void 0 && treeIdentity(tree) === config.identity;
+			if (options.treePath) {
+				const supplied = realpathSync(options.treePath);
+				const connection = findConnectionRecord(config.projectPath);
+				matches ||= connection !== void 0 && treeIdentity(connection.tree) === config.identity && realpathSync(connection.tree.path) === supplied;
+			}
+			if (matches) atomicState(statePath(config.id, "activity"), Date.now());
+		}
+	} catch {}
+}
+function snapshot(root) {
+	const result = /* @__PURE__ */ new Map();
+	const walk = (directory, prefix) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const name = prefix + entry.name;
+			const path = join(directory, entry.name);
+			if (entry.isDirectory()) walk(path, `${name}/`);
+			else if (entry.isFile()) result.set(name, `${lstatSync(path).mode}:${createHash("sha256").update(readFileSync(path)).digest("hex")}`);
+			else result.set(name, entry.isSymbolicLink() ? `symlink:${readlinkSync(path)}` : "unsupported");
+		}
+	};
+	walk(root, "");
+	return result;
+}
+function inspectEdits(root, before) {
+	const after = snapshot(root);
+	let changed = false;
+	for (const name of new Set([...before.keys(), ...after.keys()])) {
+		if (before.get(name) === after.get(name)) continue;
+		if (!name.endsWith(".md") || classifyContextContent(name) === "repo-infra" || before.get(name) === "unsupported" || after.get(name) === "unsupported" || before.get(name)?.startsWith("symlink:") || after.get(name)?.startsWith("symlink:")) throw new Error("Cleanup agent changed infrastructure, a symlink, or unsupported content.");
+		changed = true;
+	}
+	if (git(root, [
+		"diff",
+		"--cached",
+		"--name-only",
+		"-z"
+	]).length > 0) throw new Error("Cleanup agent staged changes; editorial workers must not stage.");
+	return changed;
+}
+async function runCleanup(project, savedId, dependencies = {}) {
+	const config = savedId ? loadSchedule(savedId) : findSchedule(project);
+	if (!config) throw new Error("No cleanup schedule exists for this project.");
+	const lock = statePath(config.id, "lock");
+	manage(() => {
+		const entry = lstatSync(lock, { throwIfNoEntry: false });
+		if (entry) {
+			if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error("Unsafe cleanup lock.");
+			if (alive(number().int().positive().parse(readState(join(lock, "owner"))))) throw new Error("Cleanup already running.");
+			rmSync(lock, { recursive: true });
+		}
+		mkdirSync(lock, { mode: 448 });
+		atomicState(join(lock, "owner"), process.pid);
+	});
+	const controller = new AbortController();
+	const cancel = () => controller.abort();
+	process.on("SIGTERM", cancel);
+	process.on("SIGINT", cancel);
+	let worktreePath;
+	let publishing = false;
+	const record = (outcome, extra = {}) => {
+		const value = cleanupOutcomeSchema.parse({
+			at: Date.now(),
+			outcome,
+			...worktreePath ? { worktreePath } : {},
+			...extra
+		});
+		atomicState(statePath(config.id, "latest"), value);
+		return value;
+	};
+	const check = () => {
+		const current = loadSchedule(config.id);
+		if (controller.signal.aborted || !current.enabled || JSON.stringify(current) !== JSON.stringify(config)) throw new Error("Cleanup cancelled or schedule changed.");
+	};
+	const identityCheck = () => {
+		check();
+		const tree = resolveConnectionRecord(config.projectPath).tree;
+		if (treeIdentity(tree) !== config.identity) throw new Error("Cleanup connection identity changed; reschedule explicitly.");
+		return tree;
+	};
+	try {
+		check();
+		const lastActivity = activity(config.id);
+		if (lastActivity === null || Date.now() - lastActivity > 864e5) return record("inactive");
+		identityCheck();
+		const synced = (dependencies.sync ?? syncProject)(config.projectPath);
+		check();
+		if (readState(statePath(config.id, "success")) === synced.sha) return record("unchanged", { sha: synced.sha });
+		worktreePath = (dependencies.prepare ?? prepareContextWrite)(config.projectPath).worktreePath;
+		check();
+		const head = git(worktreePath, ["rev-parse", "HEAD"]);
+		const before = snapshot(worktreePath);
+		record("running");
+		const editorial = readFileSync(resolvePackagedResource("skills", "context-tree-cleanup", "references", "editorial.md"), "utf8");
+		const monitor = setInterval(() => {
+			try {
+				check();
+			} catch {
+				controller.abort();
+			}
+		}, 250);
+		try {
+			await (dependencies.agent ?? runAgent)(config, worktreePath, `${editorial}\n\nYou are the editorial worker in an already prepared isolated worktree. Read all normal and member Markdown content directly using file tools. Edit and check references only. Do not invoke Context Tree lifecycle commands, stage, commit, change Git configuration, or publish. Do not follow other skills that request those operations. Report unresolved issues outside tree files.`, controller.signal);
+		} finally {
+			clearInterval(monitor);
+		}
+		check();
+		if (git(worktreePath, ["rev-parse", "HEAD"]) !== head) throw new Error("Cleanup agent committed changes.");
+		const changed = inspectEdits(worktreePath, before);
+		if (!verifyTree(worktreePath).ok) throw new Error("Cleanup agent produced an invalid tree.");
+		identityCheck();
+		if (!changed) {
+			atomicState(statePath(config.id, "success"), head);
+			return record("noop", { sha: head });
+		}
+		record("running", { message: "publishing" });
+		check();
+		publishing = true;
+		const finished = (dependencies.finish ?? finishContextWrite)({
+			projectPath: config.projectPath,
+			worktreePath,
+			message: "Clean up Context Tree content"
+		});
+		publishing = false;
+		atomicState(statePath(config.id, "success"), finished.sha);
+		return record("published", { sha: finished.sha });
+	} catch (error) {
+		const message = sanitizeCommandOutput(error instanceof Error ? error.message : "Cleanup failed.");
+		const outdated = error instanceof Error && "code" in error && error.code === "WRITE_OUTDATED";
+		return record(publishing && !outdated ? "publication-uncertain" : controller.signal.aborted || !loadSchedule(config.id).enabled ? "cancelled" : "failed", { message });
+	} finally {
+		process.removeListener("SIGTERM", cancel);
+		process.removeListener("SIGINT", cancel);
+		rmSync(lock, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/core/scaffold.ts
+function template(name, values) {
+	let result = readFileSync(resolvePackagedResource("templates", name), "utf8");
+	for (const [key, value] of Object.entries(values)) result = result.replaceAll(`{{${key}}}`, value);
+	return result;
+}
+/** Templated regular files, written before the CLAUDE.md -> AGENTS.md symlink. */
+const TEMPLATED_FILES = [
+	["NODE.md", "root-node.md"],
+	["AGENTS.md", "AGENTS.md"],
+	[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
+];
+const SCAFFOLD_FILES = [
+	"NODE.md",
+	"AGENTS.md",
+	"CLAUDE.md",
+	".github/workflows/validate-context-tree.yml"
+];
+function initializeGitRepository(root, runner) {
+	gitCommand([
+		"init",
+		"--quiet",
+		"--",
+		root
+	], {
+		message: "Failed to initialize Git repository.",
+		runner
+	});
+	return git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the initial Git branch during repository initialization.",
+		runner
+	});
+}
+function commitScaffold(root, runner) {
+	for (const file of SCAFFOLD_FILES) git(root, [
+		"add",
+		"--",
+		file
+	], {
+		message: "Failed to stage the scaffold files.",
+		runner
+	});
+	git(root, [
+		"-c",
+		"user.name=Context Tree",
+		"-c",
+		"user.email=context-tree@localhost",
+		"-c",
+		"commit.gpgsign=false",
+		"commit",
+		"--quiet",
+		"-m",
+		"Initialize Context Tree"
+	], {
+		message: "Failed to commit the scaffold.",
+		runner
+	});
+	return git(root, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the scaffold commit.",
+		runner
+	});
+}
+function scaffoldTree(options) {
+	const name = treeNameSchema.parse(options.name);
+	const root = resolve(options.path);
+	const destination = lstatSync(root, { throwIfNoEntry: false });
+	if (destination !== void 0) {
+		if (destination.isSymbolicLink() || !destination.isDirectory()) throw new Error(`Refusing to scaffold into a symlink or non-directory destination: ${root}`);
+		if (readdirSync(root).length > 0) throw new Error(`Refusing to scaffold into a non-empty directory: ${root}`);
+	}
+	const initialBranch = initializeGitRepository(root, options.runner);
+	const values = {
+		branchJson: JSON.stringify(initialBranch),
+		packageVersion: readPackageVersion(),
+		title: name,
+		titleJson: JSON.stringify(name)
+	};
+	for (const [relativePath, source] of TEMPLATED_FILES) {
+		const path = join(root, relativePath);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, template(source, values), {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 420
+		});
+	}
+	symlinkSync("AGENTS.md", join(root, "CLAUDE.md"), "file");
+	if (!verifyTree(root).ok) throw new Error("Refusing to commit an invalid Context Tree scaffold.");
+	return {
+		branch: initialBranch,
+		commit: commitScaffold(root, options.runner),
+		root
+	};
+}
+//#endregion
+//#region src/core/create.ts
+function projectName(canonicalRoot) {
+	const normalized = basename(canonicalRoot).toLowerCase().replace(/[^a-z\d._-]+/gu, "-").replace(/-{2,}/gu, "-").replace(/^[-.]+/u, "").replace(/[-.]+$/u, "").slice(0, 40);
+	return /^[a-z\d]/u.test(normalized) ? normalized : "project";
+}
+function existingCreateResult(canonical, destination, runner) {
+	const branch = git(destination, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the managed tree branch.",
+		runner
+	});
+	const commitSha = git(destination, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the managed tree commit.",
+		runner
+	});
+	linkProjectInstructions(canonical);
+	return {
+		branch,
+		commitSha,
+		created: false,
+		schemaVersion: 1,
+		title: readRootNode(destination).frontmatter.title,
+		treePath: destination
+	};
+}
+/** Create and connect the project's uniquely named managed local Context Tree. */
+function createProject(projectPath, runner) {
+	const canonical = canonicalProjectRoot(projectPath, runner);
+	const name = treeNameSchema.parse(`${projectName(canonical)}-context-tree`);
+	const destination = join(managedTreesRoot(), name);
+	const current = findConnectionRecord(canonical, runner);
+	if (current !== void 0 && current.tree.path !== destination) throw new Error(`This project is already connected to a Context Tree at ${current.tree.path}; run context-tree connect ${name} to switch.`);
+	if (existsSync(destination)) {
+		const entry = lstatSync(destination);
+		if (entry.isSymbolicLink() || !entry.isDirectory() || current === void 0) throw new Error(`Managed Context Tree name ${name} is occupied; run context-tree connect ${name}.`);
+		return existingCreateResult(canonical, destination, runner);
+	}
+	mkdirSync(destination, { mode: 448 });
+	try {
+		const scaffold = scaffoldTree({
+			name,
+			path: destination,
+			runner
+		});
+		upsertConnection({
+			projectPath: canonical,
+			tree: {
+				kind: "local",
+				path: scaffold.root
+			}
+		}, runner);
+		linkProjectInstructions(canonical);
+		return {
+			branch: scaffold.branch,
+			commitSha: scaffold.commit,
+			created: true,
 			schemaVersion: 1,
 			title: name,
 			treePath: scaffold.root
@@ -26063,407 +26909,141 @@ function classifyCreationFailure(stderr) {
 	if (/already exists/iu.test(stderr)) return new ContextTreeError(CLI_ERROR_CODES.repositoryExists, "A GitHub repository with this name already exists; choose an explicit OWNER/REPO override.");
 	return new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub repository creation has an uncertain or partial result; do not retry automatically.");
 }
-/**
-* Publish a clean, valid local tree as a private GitHub repository. The
-* default repository name derives from the authenticated account and managed
-* tree name; OWNER/REPO is accepted only as an explicit override. The initial
-* publication is one gh repo create operation, and the stored connection is
-* updated atomically to the published tree state.
-*/
-function publishProject(projectPath, options = {}, runner) {
-	const connection = resolveConnectionRecord(projectPath, runner);
-	const root = connection.tree.path;
-	if (connection.tree.kind === "github") throw new ContextTreeError(CLI_ERROR_CODES.failed, `The Context Tree is already published as ${connection.tree.repository}; writes publish new commits automatically.`);
-	if (optionalGit(root, [
-		"remote",
-		"get-url",
-		"origin"
-	], runner) !== void 0) throw new ContextTreeError(CLI_ERROR_CODES.failed, "A local Context Tree must not already have an origin before publication.");
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the checked-out branch.",
-		runner
-	});
-	const sha = git(root, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the Context Tree commit.",
-		runner
-	});
-	const repository = options.repository === void 0 ? `${authenticatedAccount(runner)}/${basename(root)}` : githubRepositoryIdentitySchema.parse(options.repository);
-	const url = canonicalGitHubRepositoryUrl(repository);
-	try {
-		gh([
-			"repo",
-			"create",
-			repository,
-			"--private",
-			"--source",
-			root,
-			"--remote",
-			"origin",
-			"--push"
-		], {
-			message: "GitHub repository creation failed.",
-			runner
-		});
-	} catch (error) {
-		if (error instanceof CommandError) throw classifyCreationFailure(error.stderr);
-		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub publication ended with an uncertain result.");
-	}
-	try {
-		updateConnectionTree(connection.projectPath, {
-			kind: "github",
-			path: root,
-			repository
-		}, runner);
-	} catch {
-		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "The private repository was created, but updating the local connection failed.");
-	}
-	return {
-		branch,
-		repository,
-		schemaVersion: 1,
-		sha,
-		url
-	};
-}
-//#endregion
-//#region src/core/read.ts
-function normalizeTreeTarget(value) {
-	if (!value || value === ".") return "";
-	const normalized = posix.normalize(toPosixPath(value).replace(/^\.\//u, ""));
-	if (normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) throw new Error(`Read target is outside the Context Tree: ${value}`);
-	return normalized.replace(/\/$/u, "");
-}
-function canonicalTarget(root, path) {
-	const requested = normalizeTreeTarget(path);
-	const semanticPath = requested === "NODE.md" ? "" : requested.endsWith("/NODE.md") ? dirname(requested) : requested;
-	if (classifyContextContent(semanticPath) === "repo-infra") throw new Error(`Read target is repository infrastructure: ${requested || "."}`);
-	const absolutePath = resolve(root, semanticPath);
-	if (!isPathInside(root, absolutePath)) throw new Error("Read target escapes the Context Tree root.");
-	const entry = lstatSync(absolutePath);
-	if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) throw new Error(`Read target must be a real file or directory: ${requested || "."}`);
-	if (realpathSync(absolutePath) !== absolutePath) throw new Error(`Read target must not traverse a symlink: ${requested || "."}`);
-	const relativePath = toPosixPath(relative(root, absolutePath));
-	if (entry.isFile() && !absolutePath.endsWith(".md")) throw new Error(`Read target must be a Markdown file or indexed directory: ${requested || "."}`);
-	return {
-		absolutePath,
-		kind: entry.isDirectory() ? "directory" : "file",
-		relativePath
-	};
-}
-function readNode(path, relativePath, kind) {
-	const documentPath = kind === "directory" ? join(path, "NODE.md") : path;
-	const entry = lstatSync(documentPath);
-	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error(`Context Tree document must be a regular file: ${relativePath || "NODE.md"}`);
-	const document = readNodeDocument(documentPath);
-	if (document === null) throw new Error(`Context Tree document has invalid or missing metadata: ${relativePath || "."}`);
-	return {
-		body: document.body,
-		contentClass: classifyContextContent(relativePath),
-		frontmatter: document.frontmatter,
-		kind,
-		path: relativePath || "."
-	};
-}
-function childSummary(root, parentPath, name) {
-	const absolutePath = join(parentPath, name);
-	const relativePath = toPosixPath(relative(root, absolutePath));
-	const contentClass = classifyContextContent(relativePath);
-	if (contentClass === "repo-infra") return null;
-	const entry = lstatSync(absolutePath);
-	if (entry.isSymbolicLink()) return null;
-	const kind = entry.isDirectory() ? "directory" : entry.isFile() && name.endsWith(".md") && name !== "NODE.md" ? "file" : null;
-	if (kind === null) return null;
-	const document = readNodeDocument(kind === "directory" ? join(absolutePath, "NODE.md") : absolutePath);
-	if (document === null) throw new Error(`Context Tree child has invalid or missing metadata: ${relativePath}`);
-	return {
-		contentClass,
-		...document.description === void 0 ? {} : { description: document.description },
-		kind,
-		path: relativePath,
-		title: document.title
-	};
-}
-function readTree(treePath, path) {
-	const root = resolveTreeRoot(treePath);
-	const target = canonicalTarget(root, path);
-	const node = readNode(target.absolutePath, target.relativePath, target.kind);
-	return {
-		children: target.kind === "file" ? [] : readdirSync(target.absolutePath).map((name) => childSummary(root, target.absolutePath, name)).filter((child) => child !== null).sort((left, right) => left.path.localeCompare(right.path)),
-		node,
-		root,
-		schemaVersion: 1,
-		target: target.relativePath || "."
-	};
-}
-//#endregion
-//#region src/core/sync.ts
-/**
-* Local trees report their checked-out state without network access. GitHub
-* trees fast-forward the exact checked-out branch once, then revalidate.
-*/
-function syncProject(projectPath, runner) {
-	const connection = resolveConnectionRecord(projectPath, runner);
-	const root = connection.tree.path;
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the checked-out branch.",
-		runner
-	});
-	if (connection.tree.kind === "github") {
-		git(root, [
-			"pull",
-			"--ff-only",
-			"origin",
-			branch
-		], {
-			message: "Fast-forwarding the Context Tree failed.",
-			runner
-		});
-		validateStoredTreeState(connection.tree, runner);
-	}
-	return {
-		branch,
-		schemaVersion: 1,
-		sha: git(root, ["rev-parse", "HEAD"], {
-			message: "Failed to resolve the Context Tree commit.",
-			runner
-		}),
-		tree: connection.tree
-	};
-}
-//#endregion
-//#region src/core/write.ts
-const TASK_BRANCH_PREFIX = "context-tree/write/";
-/** A prepared worktree left untouched for longer than this is treated as abandoned. */
-const ABANDONED_WRITE_AGE_MS = 1440 * 60 * 1e3;
-/** Synchronize first, then create an isolated task worktree at the exact HEAD. */
-function prepareContextWrite(projectPath, runner) {
-	const synchronized = syncProject(projectPath, runner);
-	const root = synchronized.tree.path;
-	reclaimAbandonedWrites(root, synchronized.branch, runner);
-	const destination = mkdtempSync(join(tmpdir(), "context-tree-write-"));
-	const taskBranch = `${TASK_BRANCH_PREFIX}${basename(destination)}`;
-	try {
-		git(root, [
-			"worktree",
-			"add",
-			"--quiet",
-			"-b",
-			taskBranch,
-			destination,
-			synchronized.sha
-		], {
-			message: "Creating the isolated write worktree failed.",
-			runner
-		});
-		return {
-			schemaVersion: 1,
-			worktreePath: realDirectoryWithoutSymlinks(destination, "Write worktree")
-		};
-	} catch (error) {
-		rmSync(destination, {
-			force: true,
-			recursive: true
-		});
-		throw error;
-	}
-}
-/** Commit every pending change, then fast-forward locally or push once. */
-function finishContextWrite(options, runner) {
-	const connection = resolveConnectionRecord(options.projectPath, runner);
-	const root = connection.tree.path;
-	const { taskBranch, worktreePath } = validatePreparedWorktree(root, options.worktreePath, runner);
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the connected checkout branch.",
-		runner
-	});
-	if (git(worktreePath, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	], {
-		message: "Failed to inspect the prepared worktree.",
-		runner
-	}).length === 0) throw new Error("The prepared worktree has no pending changes.");
-	if (!verifyTree(worktreePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to commit an invalid Context Tree; run context-tree verify --tree-path ${worktreePath}.`);
-	git(worktreePath, ["add", "--all"], {
-		message: "Staging the Context Tree changes failed.",
-		runner
-	});
-	git(worktreePath, [
-		"-c",
-		"commit.gpgsign=false",
-		"commit",
-		"--quiet",
-		"-m",
-		options.message
+/**
+* Publish a clean, valid local tree as a private GitHub repository. The
+* default repository name derives from the authenticated account and managed
+* tree name; OWNER/REPO is accepted only as an explicit override. The initial
+* publication is one gh repo create operation, and the stored connection is
+* updated atomically to the published tree state.
+*/
+function publishProject(projectPath, options = {}, runner) {
+	const connection = resolveConnectionRecord(projectPath, runner);
+	const root = connection.tree.path;
+	if (connection.tree.kind === "github") throw new ContextTreeError(CLI_ERROR_CODES.failed, `The Context Tree is already published as ${connection.tree.repository}; writes publish new commits automatically.`);
+	if (optionalGit(root, [
+		"remote",
+		"get-url",
+		"origin"
+	], runner) !== void 0) throw new ContextTreeError(CLI_ERROR_CODES.failed, "A local Context Tree must not already have an origin before publication.");
+	const branch = git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
 	], {
-		message: "Committing the Context Tree changes failed.",
+		message: "Failed to resolve the checked-out branch.",
 		runner
 	});
-	const sha = git(worktreePath, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the write commit.",
+	const sha = git(root, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the Context Tree commit.",
 		runner
 	});
+	const repository = options.repository === void 0 ? `${authenticatedAccount(runner)}/${basename(root)}` : githubRepositoryIdentitySchema.parse(options.repository);
+	const url = canonicalGitHubRepositoryUrl(repository);
 	try {
-		if (connection.tree.kind === "local") git(root, [
-			"merge",
-			"--ff-only",
-			taskBranch
-		], {
-			message: "Fast-forwarding the local Context Tree failed.",
-			runner
-		});
-		else git(worktreePath, [
-			"push",
+		gh([
+			"repo",
+			"create",
+			repository,
+			"--private",
+			"--source",
+			root,
+			"--remote",
 			"origin",
-			`HEAD:refs/heads/${branch}`
+			"--push"
 		], {
-			message: "Publishing the Context Tree write failed.",
+			message: "GitHub repository creation failed.",
 			runner
 		});
 	} catch (error) {
-		if (isNonFastForward(error)) throw new ContextTreeError(CLI_ERROR_CODES.writeOutdated, `The Context Tree advanced; the prepared worktree is preserved at ${worktreePath}.`);
-		throw error;
+		if (error instanceof CommandError) throw classifyCreationFailure(error.stderr);
+		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub publication ended with an uncertain result.");
+	}
+	try {
+		updateConnectionTree(connection.projectPath, {
+			kind: "github",
+			path: root,
+			repository
+		}, runner);
+	} catch {
+		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "The private repository was created, but updating the local connection failed.");
 	}
-	removeWorktree(root, worktreePath, taskBranch, runner);
 	return {
 		branch,
+		repository,
 		schemaVersion: 1,
-		sha
+		sha,
+		url
 	};
 }
-function gitCommonDirectory(root, runner) {
-	const value = git(root, ["rev-parse", "--git-common-dir"], {
-		message: "Failed to resolve the Git common directory.",
-		runner
-	});
-	return realDirectoryWithoutSymlinks(isAbsolute(value) ? value : resolve(root, value), "Git common directory");
+//#endregion
+//#region src/core/read.ts
+function normalizeTreeTarget(value) {
+	if (!value || value === ".") return "";
+	const normalized = posix.normalize(toPosixPath(value).replace(/^\.\//u, ""));
+	if (normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) throw new Error(`Read target is outside the Context Tree: ${value}`);
+	return normalized.replace(/\/$/u, "");
 }
-function validatePreparedWorktree(root, suppliedPath, runner) {
-	const worktreePath = realDirectoryWithoutSymlinks(suppliedPath, "Prepared worktree");
-	if (gitCommonDirectory(worktreePath, runner) !== gitCommonDirectory(root, runner)) throw new Error("The prepared worktree does not belong to the connected Context Tree.");
-	const taskBranch = git(worktreePath, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the worktree branch.",
-		runner
-	});
-	if (!taskBranch.startsWith(TASK_BRANCH_PREFIX)) throw new Error("The prepared worktree is not on a reserved Context Tree write branch.");
+function canonicalTarget(root, path) {
+	const requested = normalizeTreeTarget(path);
+	const semanticPath = requested === "NODE.md" ? "" : requested.endsWith("/NODE.md") ? dirname(requested) : requested;
+	if (classifyContextContent(semanticPath) === "repo-infra") throw new Error(`Read target is repository infrastructure: ${requested || "."}`);
+	const absolutePath = resolve(root, semanticPath);
+	if (!isPathInside(root, absolutePath)) throw new Error("Read target escapes the Context Tree root.");
+	const entry = lstatSync(absolutePath);
+	if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) throw new Error(`Read target must be a real file or directory: ${requested || "."}`);
+	if (realpathSync(absolutePath) !== absolutePath) throw new Error(`Read target must not traverse a symlink: ${requested || "."}`);
+	const relativePath = toPosixPath(relative(root, absolutePath));
+	if (entry.isFile() && !absolutePath.endsWith(".md")) throw new Error(`Read target must be a Markdown file or indexed directory: ${requested || "."}`);
 	return {
-		taskBranch,
-		worktreePath
+		absolutePath,
+		kind: entry.isDirectory() ? "directory" : "file",
+		relativePath
 	};
 }
-function isNonFastForward(error) {
-	return error instanceof CommandError && /non-fast-forward|fetch first|tip of your current branch is behind|not possible to fast-forward|diverg/i.test(error.stderr);
-}
-function removeWorktree(root, worktreePath, taskBranch, runner) {
-	git(root, [
-		"worktree",
-		"remove",
-		worktreePath
-	], {
-		message: "Removing the write worktree failed.",
-		runner
-	});
-	git(root, [
-		"branch",
-		"-D",
-		taskBranch
-	], {
-		message: "Deleting the write branch failed.",
-		runner
-	});
-}
-/** Map every reserved write branch that still has a registered worktree to its path. */
-function listWriteWorktrees(root, runner) {
-	const paths = /* @__PURE__ */ new Map();
-	const output = optionalGit(root, [
-		"worktree",
-		"list",
-		"--porcelain"
-	], runner);
-	if (output === void 0) return paths;
-	let path;
-	for (const record of output.split("\n")) {
-		if (record.startsWith("worktree ")) {
-			path = record.slice(9).trim();
-			continue;
-		}
-		if (!record.startsWith("branch refs/heads/")) continue;
-		const branch = record.slice(18).trim();
-		if (path !== void 0 && branch.startsWith(TASK_BRANCH_PREFIX)) paths.set(branch, path);
-	}
-	return paths;
-}
-function millisecondsSinceModification(path) {
-	try {
-		return Date.now() - statSync(path).mtimeMs;
-	} catch {
-		return;
-	}
+function readNode(path, relativePath, kind) {
+	const documentPath = kind === "directory" ? join(path, "NODE.md") : path;
+	const entry = lstatSync(documentPath);
+	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error(`Context Tree document must be a regular file: ${relativePath || "NODE.md"}`);
+	const document = readNodeDocument(documentPath);
+	if (document === null) throw new Error(`Context Tree document has invalid or missing metadata: ${relativePath || "."}`);
+	return {
+		body: document.body,
+		contentClass: classifyContextContent(relativePath),
+		frontmatter: document.frontmatter,
+		kind,
+		path: relativePath || "."
+	};
 }
-/**
-* A preparation is abandoned only when it carries no commit the connected
-* checkout lacks, has no pending edits, and has gone untouched. Every unknown
-* answer preserves the worktree, so a `WRITE_OUTDATED` commit awaiting its
-* retry and a concurrent preparation both survive.
-*/
-function isAbandonedWrite(root, branch, checkoutBranch, path, runner) {
-	if (optionalGit(root, [
-		"rev-list",
-		"--count",
-		branch,
-		"--not",
-		checkoutBranch
-	], runner) !== "0") return false;
-	if (path === void 0) return true;
-	const age = millisecondsSinceModification(path);
-	if (age === void 0 || age < ABANDONED_WRITE_AGE_MS) return false;
-	return optionalGit(path, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	], runner) === "";
+function childSummary(root, parentPath, name) {
+	const absolutePath = join(parentPath, name);
+	const relativePath = toPosixPath(relative(root, absolutePath));
+	const contentClass = classifyContextContent(relativePath);
+	if (contentClass === "repo-infra") return null;
+	const entry = lstatSync(absolutePath);
+	if (entry.isSymbolicLink()) return null;
+	const kind = entry.isDirectory() ? "directory" : entry.isFile() && name.endsWith(".md") && name !== "NODE.md" ? "file" : null;
+	if (kind === null) return null;
+	const document = readNodeDocument(kind === "directory" ? join(absolutePath, "NODE.md") : absolutePath);
+	if (document === null) throw new Error(`Context Tree child has invalid or missing metadata: ${relativePath}`);
+	return {
+		contentClass,
+		...document.description === void 0 ? {} : { description: document.description },
+		kind,
+		path: relativePath,
+		title: document.title
+	};
 }
-/** Reclaim earlier preparations that were never finished. Every step is best effort. */
-function reclaimAbandonedWrites(root, checkoutBranch, runner) {
-	optionalGit(root, ["worktree", "prune"], runner);
-	const paths = listWriteWorktrees(root, runner);
-	const branches = optionalGit(root, [
-		"for-each-ref",
-		"--format=%(refname:short)",
-		`refs/heads/${TASK_BRANCH_PREFIX}`
-	], runner);
-	if (branches === void 0) return;
-	for (const branch of branches.split("\n").filter((value) => value.length > 0)) {
-		const path = paths.get(branch);
-		if (!isAbandonedWrite(root, branch, checkoutBranch, path, runner)) continue;
-		if (path !== void 0) optionalGit(root, [
-			"worktree",
-			"remove",
-			path
-		], runner);
-		optionalGit(root, [
-			"branch",
-			"-D",
-			branch
-		], runner);
-	}
+function readTree(treePath, path) {
+	const root = resolveTreeRoot(treePath);
+	const target = canonicalTarget(root, path);
+	const node = readNode(target.absolutePath, target.relativePath, target.kind);
+	return {
+		children: target.kind === "file" ? [] : readdirSync(target.absolutePath).map((name) => childSummary(root, target.absolutePath, name)).filter((child) => child !== null).sort((left, right) => left.path.localeCompare(right.path)),
+		node,
+		root,
+		schemaVersion: 1,
+		target: target.relativePath || "."
+	};
 }
 //#endregion
 //#region src/cli/format.ts
@@ -26545,7 +27125,8 @@ const TEXT_DEFAULT_COMMANDS = new Set([
 	"resolve",
 	"publish",
 	"read",
-	"verify"
+	"verify",
+	"cleanup"
 ]);
 function line(io, value) {
 	io.stdout(`${value}\n`);
@@ -26628,6 +27209,66 @@ function createContextTreeCli(io = defaultIo) {
 		if (options.project !== void 0) request.projectPath = resolve(io.cwd(), options.project);
 		line(io, JSON.stringify(uninstallSkills(request)));
 	});
+	const cleanup = program.command("cleanup").description("Schedule and manage CLI-based Context Tree cleanup.");
+	for (const operation of [
+		"schedule",
+		"status",
+		"remove",
+		"run"
+	]) {
+		const command = cleanup.command(operation).option("--project-path <path>", "project directory", ".").option(...jsonOption);
+		if (operation === "schedule") command.requiredOption("--agent <agent>", "codex or claude").option("--model <model>", "explicit model override").option("--every <duration>", "positive whole-minute interval, e.g. 30m or 1h", "1h");
+		if (operation === "run") command.addOption(new Option("--schedule-id <id>").hideHelp());
+		command.action(async (options) => {
+			const projectPath = resolve(io.cwd(), options.projectPath);
+			if (operation === "run") {
+				const result = await runCleanup(projectPath, options.scheduleId);
+				const wireResult = cleanupRunResultSchema.parse({
+					schemaVersion: 1,
+					...result
+				});
+				emit(io, options.json, wireResult, (value) => `Cleanup: ${value.outcome}.${value.message ? ` ${value.message}` : ""}${value.worktreePath ? `\n  Worktree: ${value.worktreePath}` : ""}${value.sha ? `\n  Commit: ${value.sha}` : ""}`);
+				if ([
+					"failed",
+					"cancelled",
+					"publication-uncertain"
+				].includes(result.outcome)) process.exitCode = 1;
+				return;
+			}
+			const result = operation === "schedule" ? scheduleCleanup({
+				...options,
+				projectPath,
+				agent: options.agent ?? ""
+			}) : operation === "remove" ? removeCleanup(projectPath) : cleanupStatus(projectPath);
+			emit(io, options.json, result, (value) => {
+				const config = value.schedule;
+				if (!config) return "No cleanup schedule.";
+				return [
+					`Cleanup ${config.enabled ? "scheduled" : "removed"}.`,
+					`  Registered: ${value.registered}; running: ${value.running}`,
+					`  Project: ${config.projectPath}`,
+					`  Every: ${config.everyMinutes} minutes`,
+					`  Agent: ${config.agent}; model: ${config.model}`,
+					`  Last activity: ${value.lastActivity === null ? "missing" : new Date(value.lastActivity).toISOString()}`,
+					`  Inactivity: ${value.inactive ? "cleanup prevented (no activity within 24 hours)" : "cleanup permitted"}`,
+					`  Latest: ${value.latest?.outcome ?? "none"}${value.latest?.message ? ` — ${value.latest.message}` : ""}`,
+					...value.latest?.worktreePath ? [`  Worktree: ${value.latest.worktreePath}`] : []
+				].join("\n");
+			});
+		});
+	}
+	program.hook("postAction", (_command, action) => {
+		if (![
+			"create",
+			"connect",
+			"sync",
+			"read",
+			"prepare-write",
+			"finish-write"
+		].includes(action.name())) return;
+		const options = action.opts();
+		recordCleanupActivity(action.name() === "read" ? { treePath: resolve(io.cwd(), options.treePath ?? ".") } : { projectPath: resolve(io.cwd(), options.projectPath ?? ".") });
+	});
 	return program;
 }
 async function runContextTreeCli(argv = process.argv, io = defaultIo) {