A local-first multi-agent app development platform, built on PenguinHarness
/**
* The data root's storage ledger — what is on disk, what it is for, and what migh be
* removable.
*
* This module is the **single definition point of the cleanup vocabulary** and it is
* deliberately pure: it walks a data root and reports, and it never moves or deletes
* anything. Every destructive action lives in the server's storage service, so the
* ledger can be produced by the CLI on a machine whose server is not running, and both
* callers can never disagree about what a class means.
*
* Two ideas carry the whole design:
*
* - **A class is a rule about provenance, not a directory name.** `protected` is user
* data (Agent State, Project config, a Workspace the user chose, user vaults, plugins,
* benchmarks, snapshots); everything else is derived — a temporary Workspace, a
* Session's drafts, a Trace shard, an environment the model built for itself. Nothing
* in the first group is ever reported as a candidate.
* - **A candidate is a claim, never an action.** An entry carries the rules it matched
* (`empty`, `unreferenced`, `orphan`, `idle`, `budget`) and whether it is still
* referenced; the caller reviews that list and decides. `referenced` is recomputed
* from live state by the caller at execution time, so a stale ledger can never be
* used to delete something that came alive in between.
*
* Liveness is an **input**, not something this module can discover: which Sessions still
* exist is a database question, and the database is the server's. `StorageLiveSet` is
* what the caller must supply, and an empty one means "nothing is referenced", which is
* why `emptyLiveSet()` is separate and named rather than a default argument.
*
* Cost: one walk of the root, `lstat` per file, no file contents read — except the
* `agent_state` text scan that the shared-environment text guard needs, which runs only
* when a policy enables the idle rule for that class and only for the one Agent whose
* environment is being judged.
*
* The numbers are **apparent sizes** (`st_size`), not allocated blocks, so a tree of many
* small files weighs less here than `du` reports for it — on the install this was written
* against, 5.4G of apparent size against `du`'s 6.0G, the difference being filesystem
* block rounding across ~100k files. A report is a map of what is there and what it is
* for; it is not a substitute for `df`, which is why the volume's own numbers ride along.
*/
import fs from "node:fs/promises";
import type { Dirent } from "node:fs";
import { createHash } from "node:crypto";
import path from "node:path";
/** The classes the ledger accounts for. Every byte under the root lands in exactly one. */
export const STORAGE_CLASSES = [
"protected",
"tmp_workspaces",
"session_drafts",
"traces",
"shared_env",
"trash",
"database",
"other",
] as const;
export type StorageClass = (typeof STORAGE_CLASSES)[number];
/**
* What a candidate matched. `empty` and `unreferenced` belong to temporary Workspaces,
* `orphan` to a Session's drafts, `idle` to anything judged by silence, and `budget` to
* anything evicted by a size cap (oldest first).
*/
export type CandidateRule = "empty" | "unreferenced" | "orphan" | "idle" | "budget";
/**
* Thresholds. **Every one of them defaults to off** (`null`) except the temporary
* Workspace idle rule, whose candidate list is the least ambiguous thing the ledger can
* produce — and even that only lists.
*
* The defaults are off on purpose and for a measured reason: on the install this was
* designed against, the data root was ten days old, so an age-based rule reported zero
* bytes of anything older than thirty days while the root had grown to 6.0G. Age is a
* slow lever; the ledger's value is that it names the fast ones (references, budgets,
* duplicate environments) instead of pretending timestamps will save the disk.
*/
export interface StoragePolicy {
/** A temporary Workspace no Session references and untouched for this long. */
tmpIdleDays: number | null;
/** A draft directory whose Session has been silent for this long. */
draftIdleDays: number | null;
/** Per-Agent draft budget; exceeding it evicts the oldest drafts down to 70%. */
draftBudgetBytes: number | null;
/** A Trace date directory older than this. */
traceIdleDays: number | null;
/** Per-Agent Trace budget; exceeding it evicts the oldest date directories down to 70%. */
traceBudgetBytes: number | null;
/** A shared environment untouched for this long **and** unmentioned in Agent State. */
sharedEnvIdleDays: number | null;
/** Candidates kept per class in the returned list (the per-class totals stay exact). */
maxCandidatesPerClass: number;
}
export const DEFAULT_STORAGE_POLICY: StoragePolicy = {
tmpIdleDays: 30,
draftIdleDays: null,
draftBudgetBytes: null,
traceIdleDays: null,
traceBudgetBytes: null,
sharedEnvIdleDays: null,
maxCandidatesPerClass: 200,
};
/** Bytes a budget rule evicts down to, so a single run does not empty the class. */
const BUDGET_EVICTION_TARGET = 0.7;
/** What the caller must know about live state for the ledger to be meaningful. */
export interface StorageLiveSet {
/** Session ids that still exist (the draft-directory test). */
sessionIds: ReadonlySet<string>;
/** Real paths of the Workspaces live Sessions still point at (the temporary-Workspace test). */
workspacePaths: ReadonlySet<string>;
/** Session id -> last activity, epoch ms (the draft idle test). */
sessionLastActiveMs: ReadonlyMap<string, number>;
}
/** A live set that claims nothing is referenced — named, so passing it is always a decision. */
export function emptyLiveSet(): StorageLiveSet {
return { sessionIds: new Set(), workspacePaths: new Set(), sessionLastActiveMs: new Map() };
}
/** One accounted thing: a temporary Workspace, a Session's drafts, a Trace day, an environment. */
export interface StorageEntry {
/** Path relative to the data root, `/`-separated (what a plan and a pin record). */
path: string;
class: StorageClass;
bytes: number;
files: number;
/** Newest modification inside the entry, epoch ms; 0 when nothing could be stat'd. */
newestMtimeMs: number;
/** Whether live state still points at this entry (a Workspace a Session uses, a Session's drafts). */
referenced: boolean;
/** Rules this entry matched; empty means it is not a candidate. */
rules: CandidateRule[];
/** For `shared_env`: the environment's own marker was found (see `.adelie-env.json`). */
marked?: boolean;
/** Subdirectories unreadable while measuring; the entry is still reported with what was read. */
unreadable: number;
}
export interface StorageClassReport {
class: StorageClass;
bytes: number;
files: number;
entries: number;
candidateEntries: number;
candidateBytes: number;
}
/**
* Environments that look like the same toolchain installed more than once. Report only:
* the remedy is a merge a person triggers, never a deletion, because two environments
* that look alike may be at different versions and only one of them may work.
*/
export interface SharedEnvGroup {
kind: "name" | "structure";
/** The normalized name or the structure signature the members share. */
key: string;
/** Relative paths, largest first. */
members: string[];
bytes: number;
}
export interface StorageLedger {
root: string;
scannedAtMs: number;
/** Sum of every entry, i.e. what the classification accounts for. */
totalBytes: number;
classes: StorageClassReport[];
/** Candidates, largest first, capped per class; the class totals above stay exact. */
candidates: StorageEntry[];
/** Duplicate-looking environments; never candidates. */
sharedEnvGroups: SharedEnvGroup[];
/** Disk facts beside the ledger, so a report can say how close the volume is. */
disk: { freeBytes: number; totalBytes: number } | null;
/** Paths that could not be read (capped); a report says so rather than guessing. */
unreadable: string[];
}
interface Measured {
bytes: number;
files: number;
newestMtimeMs: number;
/** Immediate subdirectory names (for the environment structure signature). */
topLevel: string[];
unreadable: number;
}
const UNREADABLE_REPORT_CAP = 20;
const STATE_TEXT_READ_CAP_BYTES = 8 * 1024 * 1024;
/** `realpath` with a fallback that still yields a stable absolute path for a vanished entry. */
async function realPathOrResolve(p: string): Promise<string> {
try {
return await fs.realpath(p);
} catch {
return path.resolve(p);
}
}
/** Measures one file or directory tree. Symlinks are counted as entries and never followed. */
async function measure(target: string, unreadable: string[]): Promise<Measured> {
let bytes = 0;
let files = 0;
let newest = 0;
let bad = 0;
const topLevel: string[] = [];
const note = (p: string): void => {
if (unreadable.length < UNREADABLE_REPORT_CAP) unreadable.push(p);
};
const visit = async (dir: string, depth: number): Promise<void> => {
let children;
try {
children = await fs.readdir(dir, { withFileTypes: true });
} catch {
bad += 1;
note(dir);
return;
}
if (depth === 0) for (const c of children) topLevel.push(c.name);
for (const child of children) {
const full = path.join(dir, child.name);
let st;
try {
st = await fs.lstat(full);
} catch {
bad += 1;
note(full);
continue;
}
if (st.mtimeMs > newest) newest = st.mtimeMs;
if (st.isSymbolicLink()) continue;
if (st.isDirectory()) await visit(full, depth + 1);
else if (st.isFile()) {
bytes += st.size;
files += 1;
}
}
};
let st;
try {
st = await fs.lstat(target);
} catch {
return { bytes: 0, files: 0, newestMtimeMs: 0, topLevel, unreadable: bad };
}
if (st.isDirectory()) {
const dirSt = st;
if (dirSt.mtimeMs > newest) newest = dirSt.mtimeMs;
await visit(target, 0);
} else if (st.isFile()) {
bytes = st.size;
files = 1;
if (st.mtimeMs > newest) newest = st.mtimeMs;
}
return { bytes, files, newestMtimeMs: newest, topLevel, unreadable: bad };
}
/** The relative, `/`-separated form of a path under the root — what a plan records. */
function relativeTo(root: string, target: string): string {
return path.relative(root, target).split(path.sep).join("/");
}
function ageDays(newestMtimeMs: number, nowMs: number): number {
if (newestMtimeMs <= 0) return 0;
return (nowMs - newestMtimeMs) / 86_400_000;
}
/** A name with case, separators and punctuation removed: `csu-mail` and `csumail` collide. */
function normalizedEnvName(name: string): string {
return name.toLowerCase().replace(/[^a-z0-9]+/g, "");
}
/** A structure signature: what the environment holds at its top level, and how many files. */
function envStructureKey(measured: Measured): string {
const names = [...measured.topLevel].sort().join(",");
const bucket = measured.files < 100 ? "s" : measured.files < 10_000 ? "m" : "l";
return `${names}|${bucket}`;
}
/** Collector for one scan; holds the aggregates the report is built from and nothing else. */
class Ledger {
readonly entries: StorageEntry[] = [];
readonly unreadable: string[] = [];
constructor(private readonly root: string) {}
entry(
target: string,
classKey: StorageClass,
measured: Measured,
options: { referenced?: boolean; rules?: CandidateRule[]; marked?: boolean } = {},
): StorageEntry {
const entry: StorageEntry = {
path: relativeTo(this.root, target),
class: classKey,
bytes: measured.bytes,
files: measured.files,
newestMtimeMs: measured.newestMtimeMs,
referenced: options.referenced ?? false,
rules: options.rules ?? [],
unreadable: measured.unreadable,
...(options.marked !== undefined ? { marked: options.marked } : {}),
};
this.entries.push(entry);
return entry;
}
async readdir(dir: string): Promise<Dirent[]> {
try {
return await fs.readdir(dir, { withFileTypes: true });
} catch {
if (this.unreadable.length < UNREADABLE_REPORT_CAP) this.unreadable.push(dir);
return [];
}
}
async fileExists(p: string): Promise<boolean> {
try {
await fs.access(p);
return true;
} catch {
return false;
}
}
}
/** All text under an Agent's `agent_state`, so the environment name guard is one pass per Agent. */
async function readAgentStateText(agentState: string): Promise<string | null> {
const parts: string[] = [];
let budget = STATE_TEXT_READ_CAP_BYTES;
const visit = async (dir: string): Promise<void> => {
let children;
try {
children = await fs.readdir(dir, { withFileTypes: true });
} catch {
return;
}
for (const child of children) {
if (budget <= 0) return;
const full = path.join(dir, child.name);
if (child.isDirectory()) {
await visit(full);
continue;
}
if (!child.isFile()) continue;
let st;
try {
st = await fs.lstat(full);
} catch {
continue;
}
if (st.size > budget) continue;
try {
parts.push(await fs.readFile(full, "utf8"));
budget -= st.size;
} catch {
// A file that vanished between readdir and read is simply not part of the text.
}
}
};
try {
await visit(agentState);
} catch {
return null;
}
return parts.join("\n");
}
/**
* Walks `root` and reports what it found. Pure with respect to the data root: reads only,
* and an entry that cannot be read is counted as unknown rather than assumed empty.
*/
export async function scanStorage(
root: string,
live: StorageLiveSet,
policy: StoragePolicy = DEFAULT_STORAGE_POLICY,
nowMs: number = Date.now(),
): Promise<StorageLedger> {
const realRoot = await realPathOrResolve(root);
const ledger = new Ledger(realRoot);
const stateTextCache = new Map<string, string | null>();
const sharedEnvGroups: SharedEnvGroup[] = [];
const measured = (target: string): Promise<Measured> => measure(target, ledger.unreadable);
/** One Agent's shared environments: judged by silence only when the policy asks for it. */
const scanSharedEnv = async (envRoot: string, agentState: string): Promise<void> => {
const children = await ledger.readdir(envRoot);
const byName = new Map<string, StorageEntry[]>();
const byStructure = new Map<string, StorageEntry[]>();
for (const child of children) {
if (!child.isDirectory()) continue;
const full = path.join(envRoot, child.name);
const m = await measured(full);
const marked = await ledger.fileExists(path.join(full, ".adelie-env.json"));
const rules: CandidateRule[] = [];
if (
policy.sharedEnvIdleDays !== null &&
ageDays(m.newestMtimeMs, nowMs) > policy.sharedEnvIdleDays
) {
if (!stateTextCache.has(agentState)) {
stateTextCache.set(agentState, await readAgentStateText(agentState));
}
const text = stateTextCache.get(agentState) ?? "";
const mentionedInState = text.includes(child.name);
const mentionedInWorkspaces = [...live.workspacePaths].some((w) => w.includes(child.name));
if (!mentionedInState && !mentionedInWorkspaces) rules.push("idle");
}
const entry = ledger.entry(full, "shared_env", m, { rules, marked });
const nameKey = normalizedEnvName(child.name);
const nameBucket = byName.get(nameKey);
if (nameBucket === undefined) byName.set(nameKey, [entry]);
else nameBucket.push(entry);
const structureKey = envStructureKey(m);
const structureBucket = byStructure.get(structureKey);
if (structureBucket === undefined) byStructure.set(structureKey, [entry]);
else structureBucket.push(entry);
}
for (const [key, members] of byName) {
if (members.length < 2) continue;
sharedEnvGroups.push({
kind: "name",
key,
members: members.map((m) => m.path).sort(),
bytes: members.reduce((sum, m) => sum + m.bytes, 0),
});
}
for (const [key, members] of byStructure) {
if (members.length < 2) continue;
sharedEnvGroups.push({
kind: "structure",
key,
members: members.map((m) => m.path).sort(),
bytes: members.reduce((sum, m) => sum + m.bytes, 0),
});
}
};
/** One Agent's drafts, with the orphan and idle rules and the optional budget eviction. */
const scanDrafts = async (draftRoot: string): Promise<StorageEntry[]> => {
const entries: StorageEntry[] = [];
for (const child of await ledger.readdir(draftRoot)) {
if (!child.isDirectory()) continue;
const full = path.join(draftRoot, child.name);
const m = await measured(full);
const referenced = live.sessionIds.has(child.name);
const rules: CandidateRule[] = [];
if (!referenced) rules.push("orphan");
else if (policy.draftIdleDays !== null) {
const last = live.sessionLastActiveMs.get(child.name);
if (last !== undefined && ageDays(last, nowMs) > policy.draftIdleDays) rules.push("idle");
}
entries.push(ledger.entry(full, "session_drafts", m, { referenced, rules }));
}
if (policy.draftBudgetBytes !== null) {
const total = entries.reduce((sum, e) => sum + e.bytes, 0);
if (total > policy.draftBudgetBytes) {
const target = policy.draftBudgetBytes * BUDGET_EVICTION_TARGET;
let running = total;
for (const entry of [...entries].sort((a, b) => a.newestMtimeMs - b.newestMtimeMs)) {
if (running <= target) break;
if (entry.rules.includes("orphan")) continue;
entry.rules.push("budget");
running -= entry.bytes;
}
}
}
return entries;
};
/** One Agent's Trace days, with the idle rule and the optional budget eviction. */
const scanTraces = async (traceRoot: string): Promise<StorageEntry[]> => {
const entries: StorageEntry[] = [];
for (const child of await ledger.readdir(traceRoot)) {
if (!child.isDirectory()) continue;
const full = path.join(traceRoot, child.name);
const m = await measured(full);
const rules: CandidateRule[] = [];
if (policy.traceIdleDays !== null && ageDays(m.newestMtimeMs, nowMs) > policy.traceIdleDays) {
rules.push("idle");
}
entries.push(ledger.entry(full, "traces", m, { rules }));
}
if (policy.traceBudgetBytes !== null) {
const total = entries.reduce((sum, e) => sum + e.bytes, 0);
if (total > policy.traceBudgetBytes) {
const target = policy.traceBudgetBytes * BUDGET_EVICTION_TARGET;
let running = total;
for (const entry of [...entries].sort((a, b) => a.newestMtimeMs - b.newestMtimeMs)) {
if (running <= target) break;
if (!entry.rules.includes("idle")) entry.rules.push("budget");
running -= entry.bytes;
}
}
}
return entries;
};
for (const top of await ledger.readdir(realRoot)) {
const full = path.join(realRoot, top.name);
if (!top.isDirectory()) {
// Root-level files: the database and its sidecars are accounted for as such, and
// anything else (the API token, the install id, the server lock) is `other` — small,
// but named, so the classification stays complete rather than nearly so.
const classKey: StorageClass =
top.name === "web.db" || top.name.startsWith("web.db-") ? "database" : "other";
ledger.entry(full, classKey, await measured(full));
continue;
}
if (top.name === ".trash") {
for (const child of await ledger.readdir(full)) {
ledger.entry(
path.join(full, child.name),
"trash",
await measured(path.join(full, child.name)),
);
}
continue;
}
if (top.name === "users" || top.name === "plugins") {
ledger.entry(full, "protected", await measured(full));
continue;
}
const agents = path.join(full, "agents");
if (!(await ledger.fileExists(agents))) {
ledger.entry(full, "other", await measured(full));
continue;
}
// A Project directory: `agents/` is walked Agent by Agent, and everything beside it
// (`benchmarks/`, the Project config) is user data.
for (const child of await ledger.readdir(full)) {
if (child.name === "agents") continue;
ledger.entry(
path.join(full, child.name),
"protected",
await measured(path.join(full, child.name)),
);
}
for (const agent of await ledger.readdir(agents)) {
if (!agent.isDirectory()) continue;
const agentRoot = path.join(agents, agent.name);
const agentState = path.join(agentRoot, "agent_state");
for (const child of await ledger.readdir(agentRoot)) {
const childPath = path.join(agentRoot, child.name);
if (!child.isDirectory()) {
ledger.entry(childPath, "other", await measured(childPath));
continue;
}
switch (child.name) {
case "agent_state":
case "snapshots":
ledger.entry(childPath, "protected", await measured(childPath));
break;
case "scratchpad":
await scanDrafts(childPath);
break;
case "traces":
await scanTraces(childPath);
break;
case "shared_env":
await scanSharedEnv(childPath, agentState);
break;
case "workspaces": {
for (const ws of await ledger.readdir(childPath)) {
const wsPath = path.join(childPath, ws.name);
const m = await measured(wsPath);
const isTemp = ws.name.startsWith("tmp-");
if (!isTemp) {
ledger.entry(wsPath, "protected", m, { referenced: true });
continue;
}
const referenced = live.workspacePaths.has(await realPathOrResolve(wsPath));
const rules: CandidateRule[] = [];
if (!referenced && m.files === 0) rules.push("empty");
if (!referenced) {
rules.push("unreferenced");
if (
policy.tmpIdleDays !== null &&
ageDays(m.newestMtimeMs, nowMs) > policy.tmpIdleDays
) {
rules.push("idle");
}
}
ledger.entry(wsPath, "tmp_workspaces", m, { referenced, rules });
}
break;
}
default:
ledger.entry(childPath, "other", await measured(childPath));
}
}
}
}
// Aggregate. Every entry is in exactly one class, so the totals sum to the root's own size.
const classes: StorageClassReport[] = STORAGE_CLASSES.map((classKey) => {
const own = ledger.entries.filter((e) => e.class === classKey);
const candidates = own.filter((e) => e.rules.length > 0);
return {
class: classKey,
bytes: own.reduce((sum, e) => sum + e.bytes, 0),
files: own.reduce((sum, e) => sum + e.files, 0),
entries: own.length,
candidateEntries: candidates.length,
candidateBytes: candidates.reduce((sum, e) => sum + e.bytes, 0),
};
});
const candidates: StorageEntry[] = [];
for (const classKey of STORAGE_CLASSES) {
const own = ledger.entries
.filter((e) => e.class === classKey && e.rules.length > 0)
.sort((a, b) => b.bytes - a.bytes)
.slice(0, policy.maxCandidatesPerClass);
candidates.push(...own);
}
return {
root: realRoot,
scannedAtMs: nowMs,
totalBytes: ledger.entries.reduce((sum, e) => sum + e.bytes, 0),
classes,
candidates,
sharedEnvGroups: sharedEnvGroups.sort((a, b) => b.bytes - a.bytes),
disk: await diskFacts(realRoot),
unreadable: ledger.unreadable,
};
}
/** Whether `target` is `root` itself or something below it. Lexical: both sides are absolute. */
export function isInsideRoot(root: string, target: string): boolean {
const resolved = path.resolve(target);
const base = path.resolve(root);
return resolved === base || resolved.startsWith(base + path.sep);
}
/**
* Where a planned entry actually is, or null when it may not be touched. Four refusals, in
* the order the design's guardrails ask for them: a path with `..` or an absolute form is
* refused lexically before any filesystem call; the target must be a real directory rather
* than a symlink; it must resolve inside the root; and its realpath must be the path itself,
* so no directory above it is a link either.
*
* The last one is stricter than containment needs and is the version that is easy to state:
* a tree is moved only from exactly where the bill recorded it. A link anywhere in the chain
* means the recorded path and the real one disagree, and a person reading the bill was looking
* at the wrong sentence — a case worth refusing rather than interpreting. A root reached
* through a symlinked parent (a home on macOS reaches its data through `/var`) is unaffected:
* both sides of the comparison are under the root's own realpath.
*
* Resolution is per call and never cached: what it answers is exactly the thing that can have
* changed since the scan, and a stale answer here is a move of the wrong thing.
*/
export async function resolveStorageEntry(
root: string,
relativePath: string,
): Promise<string | null> {
if (relativePath === "" || relativePath.startsWith("/") || relativePath.includes("\\")) {
return null;
}
if (relativePath.split("/").some((segment) => segment === "" || segment === "..")) return null;
const realRoot = await realPathOrResolve(root);
const target = path.join(realRoot, ...relativePath.split("/"));
if (!isInsideRoot(realRoot, target)) return null;
let st;
try {
st = await fs.lstat(target);
} catch {
return null;
}
if (st.isSymbolicLink() || !st.isDirectory()) return null;
if ((await realPathOrResolve(target)) !== target) return null;
return target;
}
/**
* Measures one entry again, the same way the scan measured it, so an approval can be checked
* against the disk as it is now rather than as the scan found it. Null when the entry is
* gone — which is drift too, not a silently empty tree.
*/
export async function measureStorageEntry(
target: string,
): Promise<{ bytes: number; files: number; newestMtimeMs: number } | null> {
try {
await fs.lstat(target);
} catch {
return null;
}
const measured = await measure(target, []);
return { bytes: measured.bytes, files: measured.files, newestMtimeMs: measured.newestMtimeMs };
}
// ---------------------------------------------------------------------------
// From candidate to executed: the plan a person approves
// ---------------------------------------------------------------------------
/**
* The classes a cleanup may actually move in this version. One class at a time, on purpose:
* a temporary Workspace is the entry whose whole premise is that nobody points at it, so a
* move can be undone by a rename and nothing in a running Session notices. Drafts, Traces and
* environments each carry a consequence a person must weigh (an image URL in an old message
* stops resolving, a replay loses its shard, a toolchain has to be installed again), and every
* one of them deserves its own review rather than riding along with the first switch that
* happens to exist. Classes outside this list are reported and planned, never applied.
*/
export const EXECUTABLE_STORAGE_CLASSES: readonly StorageClass[] = ["tmp_workspaces"];
export function isExecutableStorageClass(classKey: StorageClass): boolean {
return EXECUTABLE_STORAGE_CLASSES.includes(classKey);
}
/** Short hex digest, for the fingerprints a plan records. Not a security boundary. */
function hash(input: string): string {
return createHash("sha256").update(input).digest("hex");
}
/**
* A temporary Workspace's recorded path: `<project>/agents/<agent>/workspaces/tmp-<suffix>`.
* Anchored, one path segment per level, so a plan file edited by hand (or written by an older
* version) cannot name `../..`, a nested path inside a Workspace, or a Workspace that is not
* temporary.
*/
const TEMP_WORKSPACE_PATH = /^[^/]+\/agents\/[^/]+\/workspaces\/tmp-[^/]+$/;
/**
* Whether a recorded path is one this class may act on at all — the prefix whitelist of the
* design's safety rules, applied to the `/`-separated relative paths a plan records. Purely
* lexical: whether the path escapes the root through a symlink is a filesystem question the
* server answers with `realpath`, and it asks this first so a plan that was tampered with is
* refused before anything is stat'd.
*/
export function isPlannablePath(relativePath: string, classKey: StorageClass): boolean {
if (relativePath === "" || relativePath.startsWith("/") || relativePath.includes("\\")) {
return false;
}
if (relativePath.split("/").some((segment) => segment === "" || segment === "..")) return false;
switch (classKey) {
case "tmp_workspaces":
return TEMP_WORKSPACE_PATH.test(relativePath);
default:
// Nothing else is executable yet, so nothing else has a prefix to be checked against —
// and answering `true` here would be a whitelist that whitelists everything.
return false;
}
}
/**
* How long an approved-but-unexecuted plan stays valid. A day is long enough to review a bill
* over lunch and short enough that a plan stopped describing the disk a week ago by the time
* somebody presses the button; the design asks for exactly this bound, after which the answer
* is a fresh scan rather than a guess.
*/
export const STORAGE_PLAN_TTL_MS = 24 * 60 * 60 * 1000;
/** One line of a bill: a candidate, and everything needed to prove it has not changed since. */
export interface StoragePlanEntry {
/** Path relative to the root, `/`-separated — what was measured and what a move would name. */
path: string;
class: StorageClass;
bytes: number;
files: number;
/** Newest modification inside the entry at scan time, epoch ms (0 = nothing could be stat'd). */
newestMtimeMs: number;
rules: CandidateRule[];
/**
* The entry as it was measured, as one short hash. Re-measured before a move: a mismatch
* means the tree grew, shrank or was touched after the person read the bill, and the answer
* is a new scan — never a partial cleanup of something nobody reviewed.
*/
fingerprint: string;
}
/**
* A scan's output, as a file a person reviews: what could go, why, and how big it is. Written
* by the server, read by the page and the CLI, and **used once** — `appliedAtMs` is the whole
* one-shot rule, so an approval cannot be replayed against a disk that has moved on.
*/
export interface StoragePlan {
id: string;
/** The real path of the root the scan walked. */
root: string;
createdAtMs: number;
expiresAtMs: number;
/** Hash over the entries, in order — what an approval quotes back to prove it read this one. */
fingerprint: string;
/** Sum of `entries`, i.e. what this bill accounts for (not the root's size). */
totalBytes: number;
entries: StoragePlanEntry[];
/** Paths a pin kept out of the bill — why a candidate the report shows is missing from it. */
excluded: string[];
/** When an apply ran; a plan is valid until then. */
appliedAtMs?: number;
/** The paths that apply actually moved. */
appliedPaths?: string[];
}
/** The local-time parts of an instant, for the names a person reads in a directory listing. */
function localStamp(nowMs: number): {
date: string;
time: string;
compact: string;
} {
const at = new Date(nowMs);
const pad = (n: number): string => String(n).padStart(2, "0");
const date = `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`;
const time = `${pad(at.getHours())}-${pad(at.getMinutes())}-${pad(at.getSeconds())}`;
return { date, time, compact: `${date.replace(/-/g, "")}-${time.replace(/-/g, "")}` };
}
/**
* A plan id: `2026-10-10-13-05-22-4f2a` — the moment of the scan plus a suffix that keeps two
* apart, in the machine's own local time because this name is read by a person looking at the
* directory (or at a bill's header) rather than parsed. Ids of the same shape sort by time as
* strings, which is all the plan list needs.
*/
export function storagePlanId(nowMs: number, suffix: string): string {
const stamp = localStamp(nowMs);
return `${stamp.date}-${stamp.time}-${suffix}`;
}
/**
* A trash entry's id: `20261010-130522`, the moment of the run. Folders, not files, so the
* compact form reads better in a listing; a collision (two runs inside one second, which the
* single-writer rule should prevent anyway) is resolved by the caller appending a counter.
*/
export function storageTrashId(nowMs: number): string {
return localStamp(nowMs).compact;
}
/**
* One entry's fingerprint: what the bill said about this tree, in one short hash. Size and
* newest mtime rather than a walk of every file — a plan names hundreds of trees and hashing
* their contents would cost more than the cleanup saves — and both change when a tree is
* written to, which is the drift an approval has to notice.
*/
export function planEntryFingerprint(entry: {
path: string;
bytes: number;
newestMtimeMs: number;
}): string {
return hash(`${entry.path}\n${entry.bytes}\n${Math.round(entry.newestMtimeMs)}`).slice(0, 32);
}
/** The whole bill's fingerprint, over its entries in order. */
export function planFingerprint(entries: readonly StoragePlanEntry[]): string {
return hash(entries.map((entry) => entry.fingerprint).join("\n")).slice(0, 32);
}
/** The plan's entries this version may act on — what "全选本类" means, said once, in core. */
export function planDefaultSelection(plan: StoragePlan): string[] {
return plan.entries.filter((entry) => isExecutableStorageClass(entry.class)).map((e) => e.path);
}
/**
* Turns a ledger's candidates into a bill. Pure: the pins are an argument, the id is an
* argument, and the clock is an argument — the file it becomes is the server's business.
*
* Pinned paths are left out entirely (the design's "pin 过的东西不再出现在任何账单里"), which is
* why the pin list is applied here rather than filtered out again at each call site: one place
* decides what a person may be asked about.
*/
export function buildStoragePlan(
ledger: StorageLedger,
options: { id: string; nowMs: number; pins?: ReadonlySet<string>; ttlMs?: number },
): StoragePlan {
const pins = options.pins ?? new Set<string>();
const excluded: string[] = [];
const entries: StoragePlanEntry[] = [];
for (const candidate of ledger.candidates) {
if (candidate.rules.length === 0) continue;
if (pins.has(candidate.path)) {
excluded.push(candidate.path);
continue;
}
entries.push({
path: candidate.path,
class: candidate.class,
bytes: candidate.bytes,
files: candidate.files,
newestMtimeMs: candidate.newestMtimeMs,
rules: [...candidate.rules],
fingerprint: planEntryFingerprint(candidate),
});
}
return {
id: options.id,
root: ledger.root,
createdAtMs: options.nowMs,
expiresAtMs: options.nowMs + (options.ttlMs ?? STORAGE_PLAN_TTL_MS),
fingerprint: planFingerprint(entries),
totalBytes: entries.reduce((sum, entry) => sum + entry.bytes, 0),
entries,
excluded,
};
}
/** The volume's free/total bytes, or null where the platform cannot answer. */
async function diskFacts(
target: string,
): Promise<{ freeBytes: number; totalBytes: number } | null> {
try {
const st = await fs.statfs(target);
return { freeBytes: st.bavail * st.bsize, totalBytes: st.blocks * st.bsize };
} catch {
return null;
}
}