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

package/README.md

@@ -1,306 +1,126 @@
 # Context Tree
 
-`@first-tree-ai/context-tree` provides durable, structured project context for
-coding agents. It ships a portable core, CLI, templates, and seven
-framework-neutral skills.
-
-A Context Tree records current decisions, constraints, relationships, and their
-rationale. Source repositories still own implementation detail, task history,
-and credentials.
-
-## Requirements
-
-- Node.js 22.13 or newer
-- Git
-- GitHub CLI (`gh`) only for connecting a GitHub tree or publishing
-
-Git and GitHub authentication remain owned by the host tools. Repository inputs
-are credential-free `OWNER/REPO` identities, never URLs containing credentials.
+Context Tree gives coding agents lasting project memory: decisions, constraints,
+and the reasons behind them. Use it to avoid repeating context in new sessions,
+keep different agents aligned, or share knowledge across related repositories.
+Context lives in a separate Git repository. Keep it local or share it through
+private GitHub storage.
 
 ## Install
 
+Requires **Node.js 22.13+** and **Git**. For GitHub sharing, also install and
+sign in to the GitHub CLI (`gh auth login`).
+
 ```bash
 npm install --global @first-tree-ai/context-tree
 ```
 
-That installs the `context-tree` command and copies the eight skills into the
-skill directory of every agent you already have:
+This installs the CLI and skills for installed **Codex, Claude Code, and Pi**
+agents. Restart your agent to discover the skills.
 
-```text
-✓ claude  → ~/.claude/skills/   (8 skills)
-✓ codex   → ~/.codex/skills/    (8 skills)
-```
-
-Restart your agent so it discovers them, then try asking:
+## Get started
 
-> Set up a Context Tree for this project, then read the relevant context.
+Open your project in your agent and ask:
 
-> Write this architectural decision to the Context Tree.
+> Set up a local Context Tree for this project, then read the relevant context.
 
-Skill installation is a normal command, so you can re-run it after installing a
-new agent, or scope it to one project:
+You can also ask to connect an existing tree or create a private GitHub tree.
+To create a local tree yourself, run this from your project directory:
 
 ```bash
-context-tree install                       # every agent you have
-context-tree install --host codex          # one agent
-context-tree install --project .           # ./.claude/skills and ./.codex/skills
-context-tree uninstall                     # remove context-tree-* skills
+context-tree create
 ```
 
-Install and uninstall own exactly the `context-tree-*` skill directories.
-Install never touches skills it does not own or creates a configuration directory
-for an agent that is not present; uninstall removes every owned-prefix directory
-and nothing else. Adding support for another agent is one entry in the host table
-in `src/core/install.ts`.
-
-`create` and `connect` leave project instructions unchanged. When a project has
-a regular `AGENTS.md` and no `CLAUDE.md` entry, they best-effort create a
-`CLAUDE.md` symlink to `AGENTS.md`. Connections are stored separately.
-
-## Seven skills
+The tree is saved under `~/.context-tree/trees` and connected to your project.
 
-### Setup
+## Read and save context
 
-Read and write try their operation first. On `NO_CONNECTION`, they invoke
-`context-tree-setup` once, which offers an existing tree, a new local tree, a new
-private GitHub tree, or skipping Context Tree for this session. Existing targets
-can be managed names, GitHub `OWNER/REPO`, or exact checkout paths. Choices
-already supplied are reused without asking again. New private GitHub trees are
-created locally and then published; local-only creation needs no GitHub prompt.
+Ask your agent to use the tree as you work:
 
-After successful setup, the pending read/write resumes once for the original
-project. Skipping continues the user's task without Context Tree and suppresses
-further read/write and setup attempts for that project during the session,
-unless the user reopens them. The preference stays in the conversation, not
-project configuration. Failure or an unanswered setup question defers the
-Context Tree operation without silently choosing a fallback or claiming success.
-An installed skill does not require the user to adopt Context Tree.
+> Read the Context Tree before planning this change.
 
-### Create
+> Save our decision to use a single writer, including why we rejected multiple writers.
 
-```bash
-context-tree create --project-path ./service
-```
+The read skill retrieves relevant context; the write skill updates it and commits
+changes, pushing them when the tree is shared on GitHub. Save decisions and
+constraints that future work should respect, with their rationale.
 
-`create` derives `<normalized-project-directory>-context-tree`, scaffolds and
-commits it under `~/.context-tree/trees`, then connects it atomically. It is
-idempotent only while the project remains connected to that managed tree.
+To invoke a skill explicitly, use `$context-tree-read` in Codex,
+`/context-tree-read` in Claude Code, or `/skill:context-tree-read` in Pi.
+Replace `read` with `write`, `setup`, `create`, `connect`, `publish`, `cleanup`,
+or `schedule-cleanup` for the other workflows.
 
-### Connect
+## Share or connect an existing tree
 
-Connect to an existing managed tree by exact name:
+Publish your local tree as a **new private GitHub repository**:
 
 ```bash
-context-tree connect shared-context-tree --project-path ./service
+context-tree publish OWNER/REPO
 ```
 
-Or reuse or clone a GitHub tree by repository identity:
+From another project or machine, connect to it:
 
 ```bash
-context-tree connect OWNER/REPO --project-path ./service
+context-tree connect OWNER/REPO
 ```
 
-Or connect an existing checkout in place by exact disk path:
-
-```bash
-context-tree connect --tree-path /path/to/a/tree --project-path ./service
-```
-
-`connect --tree-path` requires an exact, clean, fully valid Git root with no
-symlink components. Trees without an origin connect as local state;
-credential-free GitHub origins connect as GitHub state. External disk trees
-are never copied, moved, or deleted.
-
-An identical connection is idempotent. An explicit connect automatically
-switches the project. GitHub checkouts use the repository's lowercase name in
-the same flat managed namespace as created trees.
-
-`context-tree list` reports valid, clean managed trees; `context-tree list --json`
-returns them as `{ schemaVersion: 1, trees: [{ name, tree }] }`, and a missing
-managed directory is an empty list.
-
-### Read
+You can also reuse a local tree by name or connect a checkout on disk:
 
 ```bash
-context-tree sync --project-path ./service
-context-tree read product/runtime.md --tree-path /path/from/sync
+context-tree list
+context-tree connect my-project-context-tree
+context-tree connect --tree-path /absolute/path/to/tree
 ```
 
-Local trees report their checked-out branch and exact `HEAD` without network
-access. GitHub trees perform one fast-forward-only pull of the checked-out
-branch. Reads navigate from indexes to narrow, task-relevant children.
+Connecting switches the current project's tree. Run these commands from the
+project directory, or add `--project-path /path/to/project`.
 
-### Write
+## Cleanup and scheduling
 
-```bash
-context-tree prepare-write --project-path ./service
-# Edit only the returned worktreePath.
-context-tree finish-write --project-path ./service \
-  --worktree-path /path/from/prepare \
-  --message "Record runtime constraint"
-```
-
-Preparation synchronizes first and creates a random isolated worktree at that
-exact commit. Finishing validates the worktree, stages every pending change,
-creates one unsigned commit using the host identity, and attempts one
-fast-forward merge for local trees or one non-force push for GitHub trees.
+Ask your agent to remove outdated clutter and consolidate duplicate context:
 
-If the destination advanced, `finish-write` returns `WRITE_OUTDATED` and
-preserves the worktree. Prepare again, reread affected nodes and their current
-placement, and adapt the intended semantic change once to any moved or
-consolidated content; there is no automatic rebase, retry loop, or pull-request fallback.
+> Run the context-tree-cleanup skill for this project and publish the changes.
 
-A preserved or abandoned write leaves its temporary worktree on disk and a
-`context-tree/write/<name>` branch in the tree. The next `prepare-write` reclaims
-one of these only when it holds no commit your checkout lacks, has no pending
-change, and has gone untouched for twenty-four hours, so a worktree you are still
-editing and a `WRITE_OUTDATED` worktree awaiting its retry are both left alone.
-Those keep their pending edits until you clear them with
-`git worktree remove <path>` and `git branch -D <branch>` in the connected tree.
-
-### Publish
+For recurring cleanup, use the schedule-cleanup skill or run:
 
 ```bash
-context-tree publish --project-path ./service
-# or: context-tree publish OWNER/REPO --project-path ./service
+context-tree cleanup schedule --agent codex --every 2h
+context-tree cleanup status
+context-tree cleanup logs
+context-tree cleanup remove
 ```
 
-Publishing requires a clean, valid local tree with no `origin`. It creates one
-new private GitHub repository, pushes the checkout, and then changes the stored
-connection to GitHub state. Those external and local changes are not atomic;
-uncertain or partial outcomes are reported as `PUBLISH_INCOMPLETE` and are not
-automatically inspected or repaired.
-
-### Cleanup and scheduling
-
-`context-tree-cleanup` removes noise, consolidates duplicates, and improves
-placement across shared content and all member directories, then publishes one
-commit if anything changed. It preserves useful context and protected decisions.
-
-> Run `$context-tree-cleanup` for the project at `<absolute-project-path>`.
-> Clean the entire tree and publish the changes. If another writer advances it,
-> defer until the next run.
-
-Use `context-tree-schedule-cleanup` to create or update a persistent local
-cleanup task:
-
-```text
-# Codex
-$context-tree-schedule-cleanup every 2 hours
+Choose `codex`, `claude`, or `pi`; the agent CLI must be installed and authenticated.
+Schedules run locally on macOS or Linux while the machine is awake, and skip trees
+unused for 24 hours. Use one designated cleaner per shared tree.
+`context-tree cleanup run` runs the configured cleanup now; `cleanup logs --list`
+lists previous runs.
 
-# Claude Code
-/context-tree-schedule-cleanup every 2 hours
-```
-
-The CLI manages one schedule per tree on this machine:
+## Useful commands
 
 ```bash
-context-tree cleanup schedule --project-path /absolute/project --agent codex
-context-tree cleanup schedule --project-path /absolute/project --agent claude --every 2h
-context-tree cleanup status --project-path /absolute/project
-context-tree cleanup run --project-path /absolute/project
-context-tree cleanup remove --project-path /absolute/project
+context-tree resolve                              # show this project's tree
+context-tree read --tree-path /path/to/tree        # browse its root index
+context-tree verify --tree-path /path/to/tree      # check its structure
+context-tree install                              # add skills for a new agent
+context-tree install --project .                  # install skills for this project
+context-tree uninstall                            # remove Context Tree skills
+context-tree --help
 ```
 
-All four operations accept `--json`. Scheduling starts no immediate cleanup.
-Cadence defaults to one hour and accepts positive whole-minute durations (`30m`,
-`2h`, `1d`, up to `365d`). Repeating schedule updates the same tree's entry.
-Remove an active schedule before changing it. Local identity is the resolved
-path; GitHub identity is the repository, case-insensitively. Connection changes
-require explicit removal and rescheduling.
-
-macOS uses user LaunchAgents, each invoking an executable named
-`context-tree-cleanup` at `~/.context-tree/cleanup/launchers/<schedule-id>/`.
-This private launcher executes the configured Node cleanup command and is removed
-with the schedule. Linux uses systemd user timers and services. The
-machine must be awake and the user scheduler available. No desktop app, root
-installation, daemon, or Linux lingering is needed. Cancel any previously created
-Codex desktop task or Claude Desktop routine before replacing it: the CLI cannot
-inspect or remove those tasks. Keep one designated cleaner per tree across machines.
-
-Agents use existing CLI authentication. Defaults are `gpt-5.6-luna` with low
-reasoning effort and `claude-haiku-4-5`; `--model` selects an explicit override.
-Codex uses workspace-write sandboxing and Claude uses file-editing permissions
-with a restricted tool list. Permission and authentication failures stop the run;
-models are never silently substituted. See [Codex noninteractive mode](https://learn.chatgpt.com/docs/non-interactive-mode)
-and the [Claude CLI reference](https://code.claude.com/docs/en/cli-reference).
-
-Scheduling opens a 24-hour activity window. Successful ordinary `create`,
-`connect`, `sync`, `read`, `prepare-write`, and `finish-write` use refreshes it.
-Cleanup and status never do. Missing or older activity skips before network or
-model work; successfully inspected unchanged commits skip the model. Each run
-uses a fresh isolated worktree, one agent with a 15-minute timeout, shared
-editorial instructions, verification, and at most one publication attempt.
-
-Private atomic state in `~/.context-tree/cleanup` holds configuration, activity,
-the last successful commit, and only the latest outcome. `status` reports native
-registration/running state and whether inactivity prevents cleanup. `remove`
-disables future runs and stops the native scheduled process and its children,
-preserving unfinished worktrees. Publication already underway may have completed;
-uncertain outcomes are reported without rollback or retries. Failures and
-`WRITE_OUTDATED` never advance the successful-inspection checkpoint.
-
-## Project identity
-
-Git project paths resolve to the exact root of that checkout. A clone or Git
-worktree is independent even if it shares an origin or Git common directory.
-Non-Git projects match only the exact connected directory; nested directories
-do not inherit the connection.
-
-Connection data is written atomically with mode `0600` at
-`~/.context-tree/connections.json`. Duplicate project records are corruption.
-Stored local/GitHub state is not reclassified from mutable remotes.
-
-Every command that touches a connected tree reports why it refused:
-`NO_CONNECTION` (nothing connected), `DIRTY_TREE` (your uncommitted edits —
-commit or discard them), `INVALID_TREE` (structure fails `verify`),
-`STALE_CONNECTION` (the stored path is gone; connect again), and
-`CORRUPT_CONNECTION` (unreadable or duplicated records).
-
-## CLI plumbing
-
-The public command inventory is:
-
-```text
-install  uninstall  create  connect  list  resolve  sync  prepare-write
-finish-write  publish  read  verify
-```
-
-Setup, create, connect, read, write, publish, cleanup, and schedule-cleanup ship as
-eight skills; setup
-orchestrates the five concrete workflows. `install` is the distribution
-entry point, run for you by `npm install`; `uninstall` is its supported reverse.
-`resolve`, `sync`, `prepare-write`,
-`finish-write`, and `verify` are plumbing or diagnostic commands rather than
-separate user intentions; `list` backs setup's connect-target discovery.
-
-### Output
-
-`create`, `connect`, `list`, `resolve`, `publish`, `read`, and `verify` print
-human-readable text by default and accept `--json` to emit their strict schema
-version `1` payload for scripts and agents; in text mode a failure prints a
-sanitized message to stderr with a non-zero exit code. The eight skills always
-pass `--json`. `sync`, `prepare-write`, `finish-write`, `install`, and `uninstall` are
-low-level plumbing and always emit that JSON (with the error envelope on stdout).
-`--help` and `--version` are always plain text.
-
-```bash
-context-tree verify                 # human-readable report
-context-tree verify --json          # { "ok": true, "schemaVersion": 1, ... }
-```
+For scripts and custom integrations, see the [CLI specification](docs/specification.md),
+including synchronization, prepared writes, and JSON output.
 
-`verify` is intended for CI and diagnostics. Normal skills invoke it only after
-an operation reports invalid tree content.
+## Working with OpenTag
 
-## Development
+Create or publish a tree as above, then choose it on each OpenTag Computer:
 
 ```bash
-pnpm install
-pnpm check
-pnpm typecheck
-pnpm test
-pnpm check:package
+opentag context-tree connect OWNER/REPO
+# Or use a local tree:
+opentag context-tree connect my-project-context-tree
 ```
 
-See [docs/specification.md](docs/specification.md) for contracts and safety
-invariants.
+OpenTag connects each agent workspace to that tree when a session starts.
+Use the same read, write, and cleanup prompts in those sessions. For a GitHub tree,
+GitHub authentication must work on each Computer.

package/dist/cli/index.mjs

@@ -3,12 +3,13 @@ import { createRequire } from "node:module";
 import path, { basename, delimiter, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
 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 fs, { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync, writeSync } 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";
+import { StringDecoder } from "node:string_decoder";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
@@ -7352,7 +7353,11 @@ const contextContentClassCountsSchema = object({
 	member: number().int().nonnegative(),
 	"repo-infra": number().int().nonnegative()
 }).strict();
-const SKILL_HOSTS = ["claude", "codex"];
+const SKILL_HOSTS = [
+	"claude",
+	"codex",
+	"pi"
+];
 const skillHostSchema = _enum(SKILL_HOSTS);
 const skillInstallationSchema = object({
 	host: skillHostSchema,
@@ -7469,13 +7474,17 @@ object({
 	ok: literal(false),
 	schemaVersion: literal(1)
 }).strict();
-const cleanupAgentSchema = union([literal("codex"), literal("claude")]);
+const cleanupAgentSchema = union([
+	literal("codex"),
+	literal("claude"),
+	literal("pi")
+]);
 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),
+	model: string$2().min(1).optional(),
 	everyMinutes: number().int().positive().max(525600),
 	nodePath: string$2().refine(isAbsolute),
 	cliPath: string$2().refine(isAbsolute),
@@ -7485,6 +7494,7 @@ const cleanupScheduleSchema = object({
 }).strict();
 const cleanupOutcomeSchema = object({
 	at: number(),
+	runId: string$2().uuid().optional(),
 	outcome: union([
 		literal("inactive"),
 		literal("unchanged"),
@@ -7509,6 +7519,29 @@ const cleanupResultSchema = object({
 	latest: cleanupOutcomeSchema.nullable()
 }).strict();
 const cleanupRunResultSchema = cleanupOutcomeSchema.extend({ schemaVersion: literal(1) }).strict();
+const cleanupLogEventSchema = object({
+	at: number().finite(),
+	source: union([
+		literal("runner"),
+		literal("stdout"),
+		literal("stderr")
+	]),
+	text: string$2()
+}).strict();
+const cleanupRunMetadataSchema = object({
+	runId: string$2().uuid(),
+	startedAt: number().finite(),
+	agent: cleanupAgentSchema,
+	model: string$2().optional(),
+	truncated: boolean(),
+	terminal: cleanupOutcomeSchema.optional()
+}).strict();
+const cleanupLogsResultSchema = object({
+	schemaVersion: literal(1),
+	runs: array(cleanupRunMetadataSchema),
+	selectedRunId: string$2().uuid().nullable(),
+	events: array(cleanupLogEventSchema)
+}).strict();
 //#endregion
 //#region src/core/internal/errors.ts
 /**
@@ -7525,18 +7558,27 @@ var ContextTreeError = class extends Error {
 };
 //#endregion
 //#region src/core/internal/git.ts
-function defaultRunner(command, args) {
+function defaultRunner(command, args, timeoutMs = 12e4) {
 	const result = spawnSync(command, args, {
 		encoding: "utf8",
 		stdio: [
 			"ignore",
 			"pipe",
 			"pipe"
-		]
+		],
+		timeout: timeoutMs,
+		killSignal: "SIGKILL",
+		detached: process.platform !== "win32"
 	});
+	const timedOut = result.error !== void 0 && "code" in result.error && result.error.code === "ETIMEDOUT";
+	if (timedOut && process.platform !== "win32" && result.pid) try {
+		process.kill(-result.pid, "SIGKILL");
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) throw error;
+	}
 	return {
 		status: result.status,
-		stderr: typeof result.stderr === "string" ? result.stderr : "",
+		stderr: timedOut ? `Command timed out after ${timeoutMs} ms.` : result.error ? "Unable to start command." : typeof result.stderr === "string" ? result.stderr : "",
 		stdout: typeof result.stdout === "string" ? result.stdout : ""
 	};
 }
@@ -26008,23 +26050,36 @@ function reclaimAbandonedWrites(root, checkoutBranch, runner) {
 }
 //#endregion
 //#region src/core/cleanup/agent.ts
+/** Pi built-in tools mirroring the Claude editing allowlist; Bash stays disabled. */
+const PI_CLEANUP_TOOLS = "read,edit,write,grep,find,ls";
 function agentArguments(config) {
-	return config.agent === "codex" ? [
-		"exec",
-		"--sandbox",
-		"workspace-write",
-		"-c",
-		"approval_policy=\"never\"",
-		"-c",
-		"model_reasoning_effort=\"low\"",
-		"--model",
-		config.model,
-		"--ephemeral",
-		"-"
-	] : [
+	if (config.agent === "codex") {
+		const args = [
+			"exec",
+			"--sandbox",
+			"workspace-write",
+			"-c",
+			"approval_policy=\"never\"",
+			"-c",
+			"model_reasoning_effort=\"low\""
+		];
+		if (config.model !== void 0) args.push("--model", config.model);
+		args.push("--ephemeral", "-");
+		return args;
+	}
+	if (config.agent === "pi") {
+		const args = [
+			"-p",
+			"--tools",
+			PI_CLEANUP_TOOLS,
+			"--no-session",
+			"--no-extensions"
+		];
+		if (config.model !== void 0) args.push("--model", config.model);
+		return args;
+	}
+	const args = [
 		"-p",
-		"--model",
-		config.model,
 		"--permission-mode",
 		"acceptEdits",
 		"--tools",
@@ -26033,8 +26088,10 @@ function agentArguments(config) {
 		"Read,Edit,Write,Glob,Grep",
 		"--no-session-persistence"
 	];
+	if (config.model !== void 0) args.push("--model", config.model);
+	return args;
 }
-async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3) {
+async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3, output) {
 	if (signal.aborted) throw new Error("Cleanup cancelled.");
 	await new Promise((resolve, reject) => {
 		const child = spawn(config.agentPath, agentArguments(config), {
@@ -26046,8 +26103,8 @@ async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3)
 			},
 			stdio: [
 				"pipe",
-				"ignore",
-				"ignore"
+				"pipe",
+				"pipe"
 			]
 		});
 		let failure;
@@ -26067,6 +26124,39 @@ async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3)
 			for (const pid of descendants.reverse()) kill(pid, "SIGTERM");
 			child.kill("SIGTERM");
 		};
+		const promptLines = new Set(prompt.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean));
+		const flushers = [];
+		for (const source of ["stdout", "stderr"]) {
+			const decoder = new StringDecoder("utf8");
+			let pending = "";
+			let oversized = false;
+			const emit = (text) => {
+				try {
+					output?.(source, promptLines.has(text.trim()) ? "[Prompt line suppressed]" : text);
+				} catch {
+					stop("Unable to store cleanup logs; worktree preserved.");
+				}
+			};
+			const consume = (text) => {
+				for (const part of text.split(/(?<=\n)/u)) {
+					if (!oversized) pending += part;
+					if (pending.length > 16384) {
+						pending = "";
+						oversized = true;
+					}
+					if (part.endsWith("\n")) {
+						emit(oversized ? "[Oversized output line suppressed]" : pending.slice(0, -1));
+						pending = "";
+						oversized = false;
+					}
+				}
+			};
+			child[source].on("data", (chunk) => consume(decoder.write(chunk)));
+			flushers.push(() => {
+				consume(decoder.end());
+				if (oversized || pending) emit(oversized ? "[Oversized output line suppressed]" : pending);
+			});
+		}
 		const abort = () => stop("Cleanup cancelled.");
 		const timer = setTimeout(() => stop("Cleanup agent exceeded its 15-minute timeout."), timeoutMs);
 		signal.addEventListener("abort", abort, { once: true });
@@ -26076,6 +26166,7 @@ async function runAgent(config, worktree, prompt, signal, timeoutMs = 900 * 1e3)
 			failure = "Unable to launch cleanup agent.";
 		});
 		child.on("close", async (code) => {
+			for (const flush of flushers) flush();
 			clearTimeout(timer);
 			signal.removeEventListener("abort", abort);
 			await termination;
@@ -26161,6 +26252,128 @@ function activity(id) {
 	const parsed = number().finite().safeParse(readState(statePath(id, "activity")));
 	return parsed.success ? parsed.data : null;
 }
+function directory(treeId) {
+	if (!/^[a-f0-9]{64}$/u.test(treeId)) throw new Error("Invalid cleanup tree ID.");
+	return privateDirectory(join(cleanupRoot(), "logs", treeId));
+}
+function runDirectory(root, runId) {
+	string$2().uuid().parse(runId);
+	const path = join(root, runId);
+	if (!lstatSync(path, { throwIfNoEntry: false })) throw new Error("Unknown cleanup run ID.");
+	return privateDirectory(path);
+}
+function summaries(root) {
+	return readdirSync(root).flatMap((id) => {
+		const state = readState(join(runDirectory(root, id), "metadata"));
+		if (state === void 0) return [];
+		const metadata = cleanupRunMetadataSchema.parse(state);
+		if (metadata.runId !== id) throw new Error("Cleanup log identity is corrupt.");
+		return metadata;
+	}).sort((a, b) => b.startedAt - a.startedAt || b.runId.localeCompare(a.runId));
+}
+function readEvents(path) {
+	const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > 5242880) throw new Error("Unsafe cleanup events file.");
+		const lines = readFileSync(fd, "utf8").split("\n");
+		lines.pop();
+		return lines.map((line) => cleanupLogEventSchema.parse(JSON.parse(line)));
+	} finally {
+		closeSync(fd);
+	}
+}
+function readCleanupHistory(treeId, options = {}) {
+	if (options.list && options.run !== void 0) throw new Error("--list and --run are mutually exclusive.");
+	if (options.run !== void 0) string$2().uuid().parse(options.run);
+	const root = directory(treeId);
+	const runs = summaries(root);
+	const selected = options.list ? void 0 : options.run ?? runs[0]?.runId;
+	if (options.run && !runs.some((run) => run.runId === options.run)) throw new Error("Unknown cleanup run ID.");
+	return cleanupLogsResultSchema.parse({
+		schemaVersion: 1,
+		runs,
+		selectedRunId: selected ?? null,
+		events: selected ? readEvents(join(runDirectory(root, selected), "events.jsonl")) : []
+	});
+}
+function sanitizeLogText(text) {
+	return sanitizeCommandOutput(stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "")).replace(/\b(?:https?|ssh):\/\/[^\s]+/giu, "<redacted URL>").replace(/\b[A-Z_][A-Z0-9_]*=[^\s]+/gu, "<redacted assignment>");
+}
+var CleanupHistory = class {
+	runId;
+	path;
+	metadata;
+	bytes = 0;
+	failed = false;
+	constructor(config) {
+		const root = directory(config.id);
+		const previous = summaries(root);
+		let count = previous.length;
+		for (const run of [...previous].reverse()) {
+			if (count < 50) break;
+			if (!run.terminal) continue;
+			rmSync(runDirectory(root, run.runId), { recursive: true });
+			count--;
+		}
+		this.runId = randomUUID();
+		this.path = privateDirectory(join(root, this.runId));
+		this.metadata = {
+			runId: this.runId,
+			startedAt: Date.now(),
+			agent: config.agent,
+			...config.model === void 0 ? {} : { model: sanitizeLogText(config.model) },
+			truncated: false
+		};
+		closeSync(openSync(join(this.path, "events.jsonl"), constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 384));
+		atomicState(join(this.path, "metadata"), this.metadata);
+	}
+	event(source, text) {
+		this.assertHealthy();
+		try {
+			if (this.metadata.truncated) return;
+			const line = `${JSON.stringify(cleanupLogEventSchema.parse({
+				at: Date.now(),
+				source,
+				text: sanitizeLogText(text)
+			}))}\n`;
+			const size = Buffer.byteLength(line);
+			if (this.bytes + size > 5242880) {
+				this.metadata.truncated = true;
+				this.save();
+				return;
+			}
+			privateDirectory(this.path);
+			const fd = openSync(join(this.path, "events.jsonl"), constants.O_APPEND | constants.O_WRONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+			try {
+				if (!fstatSync(fd).isFile()) throw new Error("Unsafe cleanup events file.");
+				const buffer = Buffer.from(line);
+				let written = 0;
+				while (written < buffer.length) written += writeSync(fd, buffer, written, buffer.length - written);
+			} finally {
+				closeSync(fd);
+			}
+			this.bytes += size;
+		} catch {
+			this.failed = true;
+			throw new Error("Unable to store cleanup logs; worktree preserved.");
+		}
+	}
+	assertHealthy() {
+		if (this.failed) throw new Error("Unable to store cleanup logs; worktree preserved.");
+	}
+	finish(outcome) {
+		this.metadata.terminal = {
+			...outcome,
+			...outcome.message === void 0 ? {} : { message: sanitizeLogText(outcome.message) }
+		};
+		this.save();
+	}
+	save() {
+		privateDirectory(this.path);
+		atomicState(join(this.path, "metadata"), this.metadata);
+	}
+};
 //#endregion
 //#region src/core/cleanup/scheduler.ts
 function xml(value) {
@@ -26248,7 +26461,11 @@ function nativeScheduler(platform = process.platform, home = homedir(), runner =
 		remove(config) {
 			const name = label(config);
 			if (platform === "darwin") {
-				command(["bootout", `${domain}/${name}`], true);
+				try {
+					command(["bootout", `${domain}/${name}`], true);
+				} catch (error) {
+					if (status(config).registered) throw error;
+				}
 				const launcherDir = launcherDirectory(config);
 				const launcher = join(launcherDir, "context-tree-cleanup");
 				const entry = lstatSync(launcher, { throwIfNoEntry: false });
@@ -26271,6 +26488,11 @@ function nativeScheduler(platform = process.platform, home = homedir(), runner =
 }
 //#endregion
 //#region src/core/cleanup/index.ts
+/** Low-cost editorial default for agents that need an explicit model; `--model` overrides it. */
+const DEFAULT_CLEANUP_MODEL = {
+	claude: "claude-haiku-4-5",
+	codex: "gpt-5.6-luna"
+};
 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);
@@ -26296,6 +26518,12 @@ function findSchedule(project) {
 	const connection = findConnectionRecord(canonical);
 	return connection ? schedules().find((config) => config.id === identityId(treeIdentity(connection.tree))) : void 0;
 }
+function cleanupLogs(project, options = {}) {
+	const connection = findConnectionRecord(canonicalProjectRoot(project));
+	const id = connection ? identityId(treeIdentity(connection.tree)) : findSchedule(project)?.id;
+	if (!id) throw new Error("No Context Tree connection or cleanup schedule exists for this project.");
+	return readCleanupHistory(id, options);
+}
 function cleanupStatus(project, scheduler = nativeScheduler()) {
 	const config = findSchedule(project);
 	if (!config) return {
@@ -26349,7 +26577,7 @@ function scheduleCleanupUnlocked(options, scheduler = nativeScheduler()) {
 		projectPath: connection.projectPath,
 		identity,
 		agent,
-		model: options.model ?? (agent === "codex" ? "gpt-5.6-luna" : "claude-haiku-4-5"),
+		model: options.model ?? DEFAULT_CLEANUP_MODEL[agent],
 		everyMinutes: parseCleanupInterval(options.every),
 		nodePath: realpathSync(process.execPath),
 		cliPath: resolvePackagedResource("dist", "cli", "index.mjs"),
@@ -26466,14 +26694,30 @@ async function runCleanup(project, savedId, dependencies = {}) {
 	process.on("SIGINT", cancel);
 	let worktreePath;
 	let publishing = false;
+	let history;
 	const record = (outcome, extra = {}) => {
 		const value = cleanupOutcomeSchema.parse({
 			at: Date.now(),
+			runId: history?.runId,
 			outcome,
 			...worktreePath ? { worktreePath } : {},
 			...extra
 		});
 		atomicState(statePath(config.id, "latest"), value);
+		if (outcome !== "running") try {
+			try {
+				history?.event("runner", `${outcome}${value.message ? `: ${value.message}` : ""}`);
+			} finally {
+				history?.finish(value);
+			}
+		} catch {
+			if (![
+				"failed",
+				"cancelled",
+				"publication-uncertain"
+			].includes(outcome)) throw new Error("Unable to store cleanup logs; worktree preserved.");
+		}
+		else history?.event("runner", value.message ?? "Agent execution started.");
 		return value;
 	};
 	const check = () => {
@@ -26487,13 +26731,17 @@ async function runCleanup(project, savedId, dependencies = {}) {
 		return tree;
 	};
 	try {
+		history = new CleanupHistory(config);
+		history.event("runner", "Preparing cleanup.");
 		check();
 		const lastActivity = activity(config.id);
 		if (lastActivity === null || Date.now() - lastActivity > 864e5) return record("inactive");
 		identityCheck();
+		record("running", { message: "Synchronizing Context Tree." });
 		const synced = (dependencies.sync ?? syncProject)(config.projectPath);
 		check();
 		if (readState(statePath(config.id, "success")) === synced.sha) return record("unchanged", { sha: synced.sha });
+		record("running", { message: "Preparing cleanup worktree." });
 		worktreePath = (dependencies.prepare ?? prepareContextWrite)(config.projectPath).worktreePath;
 		check();
 		const head = git(worktreePath, ["rev-parse", "HEAD"]);
@@ -26508,10 +26756,12 @@ async function runCleanup(project, savedId, dependencies = {}) {
 			}
 		}, 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);
+			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, void 0, (source, text) => history?.event(source, text));
 		} finally {
 			clearInterval(monitor);
 		}
+		history.assertHealthy();
+		history.event("runner", "Verifying cleanup edits.");
 		check();
 		if (git(worktreePath, ["rev-parse", "HEAD"]) !== head) throw new Error("Cleanup agent committed changes.");
 		const changed = inspectEdits(worktreePath, before);
@@ -26529,7 +26779,6 @@ async function runCleanup(project, savedId, dependencies = {}) {
 			worktreePath,
 			message: "Clean up Context Tree content"
 		});
-		publishing = false;
 		atomicState(statePath(config.id, "success"), finished.sha);
 		return record("published", { sha: finished.sha });
 	} catch (error) {
@@ -26718,12 +26967,22 @@ function createProject(projectPath, runner) {
 }
 //#endregion
 //#region src/core/install.ts
-/** Per-host configuration directory, relative to the home directory or to a project root. */
-const HOST_CONFIG_DIRECTORY = {
-	claude: ".claude",
-	codex: ".codex"
+/** Home configuration paths detect hosts independently of their skills destinations. */
+const HOST_DIRECTORIES = {
+	claude: {
+		config: [".claude"],
+		skills: ".claude"
+	},
+	codex: {
+		config: [".codex"],
+		skills: ".agents"
+	},
+	pi: {
+		config: [".pi", "agent"],
+		skills: ".agents"
+	}
 };
-/** Every supported host keeps user skills in the same subdirectory of its configuration directory. */
+/** Subdirectory below each skills destination. */
 const SKILLS_DIRECTORY = "skills";
 /** Only directories carrying this prefix are ever replaced or removed. */
 const OWNED_SKILL_PREFIX = "context-tree-";
@@ -26770,18 +27029,21 @@ function packagedSkillNames(skillsRoot) {
 }
 /** Resolve one host's destination, or the reason it was skipped. */
 function hostDestination(host, root, isProjectInstall) {
-	const configDirectory = HOST_CONFIG_DIRECTORY[host];
+	const directories = HOST_DIRECTORIES[host];
 	if (!isProjectInstall) {
-		const hostRoot = join(root, configDirectory);
-		const entry = lstatSync(hostRoot, { throwIfNoEntry: false });
-		if (entry === void 0) return { reason: `${hostRoot} does not exist; install ${host} first, then run context-tree install.` };
-		if (entry.isSymbolicLink() || !entry.isDirectory()) return { reason: `${hostRoot} is not a real directory.` };
+		let hostRoot = root;
+		for (const segment of directories.config) {
+			hostRoot = join(hostRoot, segment);
+			const entry = lstatSync(hostRoot, { throwIfNoEntry: false });
+			if (entry === void 0) return { reason: `${hostRoot} does not exist; install ${host} first, then run context-tree install.` };
+			if (entry.isSymbolicLink() || !entry.isDirectory()) return { reason: `${hostRoot} is not a real directory.` };
+		}
 	}
-	return { destination: ensureRealDirectory(root, [configDirectory, SKILLS_DIRECTORY]) };
+	return { destination: ensureRealDirectory(root, [directories.skills, SKILLS_DIRECTORY]) };
 }
 /** Resolve one host's existing skills root without creating or following anything. */
 function hostSkillsRoot(host, root) {
-	const hostRoot = join(root, HOST_CONFIG_DIRECTORY[host]);
+	const hostRoot = join(root, HOST_DIRECTORIES[host].skills);
 	const hostEntry = lstatSync(hostRoot, { throwIfNoEntry: false });
 	if (hostEntry === void 0) return { reason: `${hostRoot} does not exist; nothing to remove.` };
 	if (hostEntry.isSymbolicLink() || !hostEntry.isDirectory()) return { reason: `${hostRoot} is not a real directory.` };
@@ -26807,6 +27069,7 @@ function installSkills(options = {}) {
 	const root = projectRoot ?? realHome();
 	const installed = [];
 	const skipped = [];
+	const written = /* @__PURE__ */ new Set();
 	for (const host of hosts) {
 		const resolved = hostDestination(host, root, projectRoot !== void 0);
 		if ("reason" in resolved) {
@@ -26816,13 +27079,16 @@ function installSkills(options = {}) {
 			});
 			continue;
 		}
-		for (const skill of skills) {
-			const target = join(resolved.destination, skill);
-			if (lstatSync(target, { throwIfNoEntry: false }) !== void 0) rmSync(target, {
-				force: true,
-				recursive: true
-			});
-			copyRealTree(join(skillsRoot, skill), target);
+		if (!written.has(resolved.destination)) {
+			for (const skill of skills) {
+				const target = join(resolved.destination, skill);
+				if (lstatSync(target, { throwIfNoEntry: false }) !== void 0) rmSync(target, {
+					force: true,
+					recursive: true
+				});
+				copyRealTree(join(skillsRoot, skill), target);
+			}
+			written.add(resolved.destination);
 		}
 		installed.push({
 			host,
@@ -26843,6 +27109,7 @@ function uninstallSkills(options = {}) {
 	const root = options.projectPath === void 0 ? realHome() : resolve(options.projectPath);
 	const removed = [];
 	const skipped = [];
+	const removedByDestination = /* @__PURE__ */ new Map();
 	for (const host of hosts) {
 		const resolved = hostSkillsRoot(host, root);
 		if ("reason" in resolved) {
@@ -26852,29 +27119,34 @@ function uninstallSkills(options = {}) {
 			});
 			continue;
 		}
-		const skills = [];
-		for (const entry of readdirSync(resolved.destination, { withFileTypes: true })) {
-			if (!entry.name.startsWith(OWNED_SKILL_PREFIX)) continue;
-			const target = join(resolved.destination, entry.name);
-			const targetEntry = lstatSync(target, { throwIfNoEntry: false });
-			if (targetEntry === void 0) continue;
-			if (targetEntry.isSymbolicLink() || !targetEntry.isDirectory()) {
-				skipped.push({
-					host,
-					reason: `${target} is not a real directory.`
+		let skills = removedByDestination.get(resolved.destination);
+		if (skills === void 0) {
+			skills = [];
+			for (const entry of readdirSync(resolved.destination, { withFileTypes: true })) {
+				if (!entry.name.startsWith(OWNED_SKILL_PREFIX)) continue;
+				const target = join(resolved.destination, entry.name);
+				const targetEntry = lstatSync(target, { throwIfNoEntry: false });
+				if (targetEntry === void 0) continue;
+				if (targetEntry.isSymbolicLink() || !targetEntry.isDirectory()) {
+					skipped.push({
+						host,
+						reason: `${target} is not a real directory.`
+					});
+					continue;
+				}
+				rmSync(target, {
+					force: true,
+					recursive: true
 				});
-				continue;
+				skills.push(entry.name);
 			}
-			rmSync(target, {
-				force: true,
-				recursive: true
-			});
-			skills.push(entry.name);
+			skills.sort();
+			removedByDestination.set(resolved.destination, skills);
 		}
 		removed.push({
 			host,
 			path: resolved.destination,
-			skills: skills.sort()
+			skills
 		});
 	}
 	return {
@@ -27197,13 +27469,13 @@ function createContextTreeCli(io = defaultIo) {
 		emit(io, options.json, result, formatVerify);
 		if (!result.ok) process.exitCode = 1;
 	});
-	program.command("install").description("Install the packaged Context Tree skills into each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, or all", "all").option("--project <path>", "install below this project root instead of the home directory").action((options) => {
+	program.command("install").description("Install the packaged Context Tree skills into each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, pi, or all", "all").option("--project <path>", "install below this project root instead of the home directory").action((options) => {
 		const request = {};
 		if (options.host !== "all") request.hosts = [skillHostSchema.parse(options.host)];
 		if (options.project !== void 0) request.projectPath = resolve(io.cwd(), options.project);
 		line(io, JSON.stringify(installSkills(request)));
 	});
-	program.command("uninstall").description("Remove packaged Context Tree skills from each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, or all", "all").option("--project <path>", "remove below this project root instead of the home directory").action((options) => {
+	program.command("uninstall").description("Remove packaged Context Tree skills from each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, pi, or all", "all").option("--project <path>", "remove below this project root instead of the home directory").action((options) => {
 		const request = {};
 		if (options.host !== "all") request.hosts = [skillHostSchema.parse(options.host)];
 		if (options.project !== void 0) request.projectPath = resolve(io.cwd(), options.project);
@@ -27214,13 +27486,24 @@ function createContextTreeCli(io = defaultIo) {
 		"schedule",
 		"status",
 		"remove",
-		"run"
+		"run",
+		"logs"
 	]) {
 		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 === "schedule") command.requiredOption("--agent <agent>", "codex, claude, or pi").option("--model <model>", "explicit model override").option("--every <duration>", "positive whole-minute interval, e.g. 30m or 1h", "1h");
+		if (operation === "logs") command.option("--list", "list recorded runs").option("--run <run-id>", "select a recorded run");
 		if (operation === "run") command.addOption(new Option("--schedule-id <id>").hideHelp());
 		command.action(async (options) => {
 			const projectPath = resolve(io.cwd(), options.projectPath);
+			if (operation === "logs") {
+				const result = cleanupLogs(projectPath, options);
+				emit(io, options.json, result, (value) => {
+					if (!value.runs.length) return `No cleanup logs recorded for project ${projectPath}.\nUse --project-path <path> to query another project's Context Tree.`;
+					if (options.list) return value.runs.map((run) => `${run.runId}  ${new Date(run.startedAt).toISOString()}  ${run.agent}/${run.model ?? "agent default"}  ${run.terminal?.outcome ?? "incomplete"}${run.truncated ? "  truncated" : ""}`).join("\n");
+					return value.events.map((event) => `[${new Date(event.at).toISOString()}] [${event.source}] ${event.text}`).join("\n");
+				});
+				return;
+			}
 			if (operation === "run") {
 				const result = await runCleanup(projectPath, options.scheduleId);
 				const wireResult = cleanupRunResultSchema.parse({
@@ -27248,7 +27531,7 @@ function createContextTreeCli(io = defaultIo) {
 					`  Registered: ${value.registered}; running: ${value.running}`,
 					`  Project: ${config.projectPath}`,
 					`  Every: ${config.everyMinutes} minutes`,
-					`  Agent: ${config.agent}; model: ${config.model}`,
+					`  Agent: ${config.agent}; model: ${config.model ?? "agent default"}`,
 					`  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}` : ""}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@first-tree-ai/context-tree",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Durable, structured project context for coding agents: a CLI plus framework-neutral skills.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/postinstall.mjs

@@ -50,7 +50,7 @@ const skipped = Array.isArray(payload?.skipped) ? payload.skipped : [];
 
 if (installed.length === 0) {
   process.stdout.write(
-    "Context Tree: no agent directory found. Install Claude Code or Codex, then run `context-tree install`.\n",
+    "Context Tree: no agent directory found. Install Claude Code, Codex, or Pi, then run `context-tree install`.\n",
   );
   process.exit(0);
 }

package/skills/context-tree-schedule-cleanup/SKILL.md

@@ -19,11 +19,11 @@ runs cleanup immediately. Use the installed CLI on PATH; if missing, report
    desktop task using its existing controls before creating the CLI schedule.
    The CLI cannot discover or cancel old desktop tasks. Do not create a duplicate
    while cancellation is unconfirmed.
-2. Select the requested installed agent, or the current host's CLI: `codex` or
-   `claude`. Use the requested model if supplied; otherwise keep CLI defaults.
-   Use a positive whole-minute cadence such as `30m`, `1h`, or `1d`; default to
-   every hour. Do not silently approximate unsupported schedules.
-3. Run `context-tree cleanup schedule --project-path "<absolute-project-path>" --agent <codex-or-claude> --every <duration> --json`.
+2. Select the requested installed agent, or the current host's CLI: `codex`,
+   `claude`, or `pi`. Use the requested model if supplied; otherwise keep CLI
+   defaults. Use a positive whole-minute cadence such as `30m`, `1h`, or `1d`;
+   default to every hour. Do not silently approximate unsupported schedules.
+3. Run `context-tree cleanup schedule --project-path "<absolute-project-path>" --agent <codex-claude-or-pi> --every <duration> --json`.
    Add `--model <model>` only for an explicit override. Quote real arguments
    safely. Connection or scheduler errors stop without setup or repair.
 4. Read back `context-tree cleanup status --project-path "<absolute-project-path>" --json`.
@@ -43,8 +43,10 @@ activity, unchanged commits, and overlap. Do not run it merely when scheduling.
 macOS uses user LaunchAgents; Linux uses systemd user timers/services. No desktop
 app, daemon, root installation, or Linux lingering is required. The machine must
 be awake and the user scheduler available; timing follows the native scheduler.
-Defaults are `gpt-5.6-luna` with low reasoning effort or `claude-haiku-4-5`, using
-existing CLI authentication. Do not change credentials, bypass permissions,
+Defaults are `gpt-5.6-luna` with low reasoning effort for Codex and
+`claude-haiku-4-5` for Claude, using existing CLI authentication. Pi uses its
+configured default model. Pi runs ephemeral with extensions disabled; `--model`
+may also name a `provider/model`. Do not change credentials, bypass permissions,
 silently switch models, or retry publication.
 
 Initial scheduling starts a 24-hour activity window. Successful ordinary create,
@@ -54,3 +56,19 @@ activity skips before network or model work; unchanged successfully cleaned
 commits skip the model. Failures preserve worktrees and success checkpoints.
 The runner owns preparation, verification, and publication; the fresh agent
 only edits using the cleanup skill's shared required editorial resource.
+
+Inspect runner history with `context-tree cleanup logs --project-path <project> --json`.
+Use `--list` for newest-first summaries or `--run <run-id>` for a particular run;
+these selectors are mutually exclusive. The versioned result includes summaries
+and the selected run's labeled runner/stdout/stderr events. Reads are snapshots,
+do not refresh activity, and do not query the scheduler. Agent output varies by
+CLI. Missing terminal outcomes mean incomplete runs. Outcomes include `runId`
+when history was recorded.
+
+History is local, shared across connected projects, and survives schedule removal.
+Retention is 50 runs (oldest completed runs are pruned; incomplete entries are
+protected), with 5 MiB of serialized output per run and an explicit truncation
+flag. Final outcome metadata survives output truncation. Credentials and terminal
+controls are sanitized; oversized lines are suppressed. Only runner attempts are
+recorded, including inactivity and unchanged skips. Old transcripts and cleanup
+performed directly through a host skill are unavailable.