@venizia/vulcan 0.4.9-5 → 0.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,172 @@
1
+ import { existsSync, readdirSync, rmSync, statSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { EventConstants, EventSizeUnits } from './common/index.ts';
4
+ import type { IEventLimits, IEventSettings } from './common/index.ts';
5
+ import { EventLog } from './log.ts';
6
+
7
+ const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/;
8
+
9
+ export interface IRetentionFile {
10
+ name: string;
11
+ bytes: number;
12
+ /** Why it goes: `older than 30 days`, `more than 30 files`, `over the size limit`. */
13
+ reason: string;
14
+ }
15
+
16
+ export interface IRetentionPlan {
17
+ remove: IRetentionFile[];
18
+ /** Today's file is bigger than `maxSize` alone: nothing is truncated, `doctor` says so. */
19
+ todayOver: boolean;
20
+ todayBytes: number;
21
+ }
22
+
23
+ /** How much of the event log is kept: whole day files go, oldest first, and today's file never does. */
24
+ export class EventRetention {
25
+ /** `50MB`, `1.5 GB`, `200mb` as bytes; `undefined` when the text is not a number with KB, MB or GB. */
26
+ static parseSize(opts: { text: string }): number | undefined {
27
+ const found = EventSizeUnits.PATTERN.exec(opts.text.trim());
28
+
29
+ return found === null
30
+ ? undefined
31
+ : Math.floor(Number(found[1]) * (EventSizeUnits.BYTES[found[2].toUpperCase()] ?? 0));
32
+ }
33
+
34
+ /** The limits of a project: what the manifest sets, and the defaults for what it does not. */
35
+ static limitsOf(opts: { settings: IEventSettings }): IEventLimits {
36
+ const { settings } = opts;
37
+
38
+ return {
39
+ maxBytes:
40
+ EventRetention.parseSize({ text: settings.maxSize ?? EventConstants.DEFAULT_MAX_SIZE }) ??
41
+ 0,
42
+ maxFiles: settings.maxFiles ?? EventConstants.DEFAULT_MAX_FILES,
43
+ maxAgeDays: settings.maxAgeDays ?? EventConstants.DEFAULT_MAX_AGE_DAYS,
44
+ };
45
+ }
46
+
47
+ /** Whether the project keeps its log within limits: the log is on, or it set a limit itself. */
48
+ static isActive(opts: { settings: IEventSettings }): boolean {
49
+ const { settings } = opts;
50
+
51
+ return (
52
+ settings.log ||
53
+ settings.maxSize !== undefined ||
54
+ settings.maxFiles !== undefined ||
55
+ settings.maxAgeDays !== undefined
56
+ );
57
+ }
58
+
59
+ /**
60
+ * What goes from the folder `dir`. First every day file older than `maxAgeDays` days; then the oldest files, one by
61
+ * one, until the count is within `maxFiles` and the total within `maxBytes`. Today's file (of the local day of `now`)
62
+ * and a file of a later day are never in the list, even when today's alone is over the size, which `todayOver` then says.
63
+ */
64
+ static plan(opts: { dir: string; limits: IEventLimits; now: number }): IRetentionPlan {
65
+ const empty: IRetentionPlan = { remove: [], todayOver: false, todayBytes: 0 };
66
+
67
+ if (!existsSync(opts.dir)) {
68
+ return empty;
69
+ }
70
+
71
+ const today = EventLog.dayOf({ time: opts.now });
72
+ let names: string[];
73
+
74
+ try {
75
+ names = readdirSync(opts.dir);
76
+ } catch {
77
+ // Not a folder, or one that cannot be read: nothing to prune, and `doctor` says what is wrong with it.
78
+ return empty;
79
+ }
80
+
81
+ const files = names
82
+ .flatMap((name) => {
83
+ const day = DAY_FILE.exec(name)?.[1];
84
+
85
+ return day === undefined
86
+ ? []
87
+ : [{ name, day, bytes: EventRetention.sizeOf({ path: join(opts.dir, name) }) }];
88
+ })
89
+ .sort((left, right) => left.day.localeCompare(right.day));
90
+ const todayFile = files.find((file) => file.day === today);
91
+ const remove: IRetentionFile[] = [];
92
+ const todayStart = new Date(`${today}T00:00:00`).getTime();
93
+ const keep = files.filter((file) => {
94
+ const ageDays = Math.round(
95
+ (todayStart - new Date(`${file.day}T00:00:00`).getTime()) / EventConstants.DAY_MS,
96
+ );
97
+
98
+ if (file.day < today && ageDays > opts.limits.maxAgeDays) {
99
+ remove.push({
100
+ name: file.name,
101
+ bytes: file.bytes,
102
+ reason: `older than ${opts.limits.maxAgeDays} days`,
103
+ });
104
+
105
+ return false;
106
+ }
107
+
108
+ return true;
109
+ });
110
+ let total = keep.reduce((sum, file) => sum + file.bytes, 0);
111
+ let count = keep.length;
112
+
113
+ for (const file of keep) {
114
+ // Today's file and any later one (a clock that is ahead, a writer past midnight) are never removed.
115
+ if (file.day >= today) {
116
+ continue;
117
+ }
118
+
119
+ if (count <= opts.limits.maxFiles && total <= opts.limits.maxBytes) {
120
+ break;
121
+ }
122
+
123
+ remove.push({
124
+ name: file.name,
125
+ bytes: file.bytes,
126
+ reason:
127
+ count > opts.limits.maxFiles
128
+ ? `more than ${opts.limits.maxFiles} files`
129
+ : 'over the size limit',
130
+ });
131
+ total -= file.bytes;
132
+ count -= 1;
133
+ }
134
+
135
+ return {
136
+ remove,
137
+ todayOver: todayFile !== undefined && todayFile.bytes > opts.limits.maxBytes,
138
+ todayBytes: todayFile?.bytes ?? 0,
139
+ };
140
+ }
141
+
142
+ /** Whether `name` is a day file of the log: `yyyy-mm-dd.jsonl`. */
143
+ static isDayFile(opts: { name: string }): boolean {
144
+ return DAY_FILE.test(opts.name);
145
+ }
146
+
147
+ /** Removes the files of a plan; returns what went. A file that cannot be removed is left and not counted. */
148
+ static apply(opts: { dir: string; plan: IRetentionPlan }): { files: number; bytes: number } {
149
+ let files = 0;
150
+ let bytes = 0;
151
+
152
+ for (const file of opts.plan.remove) {
153
+ try {
154
+ rmSync(join(opts.dir, file.name), { force: true });
155
+ files += 1;
156
+ bytes += file.bytes;
157
+ } catch {
158
+ // Left in place; the next run tries again.
159
+ }
160
+ }
161
+
162
+ return { files, bytes };
163
+ }
164
+
165
+ private static sizeOf(opts: { path: string }): number {
166
+ try {
167
+ return statSync(opts.path).size;
168
+ } catch {
169
+ return 0;
170
+ }
171
+ }
172
+ }
@@ -3,6 +3,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
3
3
  import { RecordValue } from '../common/record.ts';
4
4
  import { EventConstants } from './common/index.ts';
5
5
  import type { IEventSettings } from './common/index.ts';
6
+ import { EventRetention } from './retention.ts';
6
7
 
7
8
  /** Where the log is and whether the Claude Code hooks write it: the `events` block of the manifest `vulcan sync` wrote. */
8
9
  export class EventSettings {
@@ -38,11 +39,22 @@ export class EventSettings {
38
39
 
39
40
  const { dir } = block;
40
41
 
42
+ const { maxSize, maxFiles, maxAgeDays } = block;
43
+
41
44
  return {
42
45
  log: block.log === true,
43
46
  ...(typeof dir === 'string' && EventSettings.dirError({ dir }) === undefined
44
47
  ? { dir }
45
48
  : {}),
49
+ ...(typeof maxSize === 'string' && EventRetention.parseSize({ text: maxSize }) !== undefined
50
+ ? { maxSize }
51
+ : {}),
52
+ ...(typeof maxFiles === 'number' && Number.isInteger(maxFiles) && maxFiles >= 1
53
+ ? { maxFiles }
54
+ : {}),
55
+ ...(typeof maxAgeDays === 'number' && Number.isInteger(maxAgeDays) && maxAgeDays >= 1
56
+ ? { maxAgeDays }
57
+ : {}),
46
58
  };
47
59
  } catch {
48
60
  return { log: false };
@@ -0,0 +1,99 @@
1
+ import { lstatSync, readdirSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { EventRetention } from '../events/retention.ts';
4
+ import { EventSettings } from '../events/settings.ts';
5
+ import { LocalAutoClean } from './auto-clean.ts';
6
+ import { LocalClean } from './clean.ts';
7
+ import { CleanScopes, LocalStates } from './constants.ts';
8
+ import { LocalScan } from './scan.ts';
9
+ import { EventLog } from '../events/log.ts';
10
+
11
+ /** The safe part of `.agents/local/`, removed by itself. A wrong guess here would cost nothing a build or a day cannot give back. */
12
+ export class AutoCleanRun {
13
+ /**
14
+ * Removes: `tmp/` entries past their days and browser leftovers an hour old (scope `tmp`, state stale), release
15
+ * candidates whose version is tagged (state shipped), and event day files past the limits of `events`. A worktree
16
+ * or a clone is never scanned, let alone removed: those stay with `vulcan clean --yes` and the warnings of `vulcan doctor`.
17
+ * Writes the stamp with what went, for the next session to say once.
18
+ */
19
+ static run(opts: { root: string; now?: number }): { files: number; bytes: number } {
20
+ const now = opts.now ?? Date.now();
21
+ const scanned = LocalScan.scan({
22
+ root: opts.root,
23
+ now,
24
+ only: [CleanScopes.TMP, CleanScopes.RELEASE_CANDIDATES],
25
+ });
26
+ // A folder that holds a repository (a clone, a worktree) is somebody's work: only `vulcan clean --yes` takes it, with its checks.
27
+ const remove = scanned.filter(
28
+ (entry) =>
29
+ entry.removable &&
30
+ (entry.state === LocalStates.STALE || entry.state === LocalStates.SHIPPED) &&
31
+ !AutoCleanRun.holdsRepository({ path: entry.path }),
32
+ );
33
+ const ran = LocalClean.run({ root: opts.root, plan: { remove, keep: [] } });
34
+ let files = ran.removed.length;
35
+ let bytes = ran.removed.reduce((sum, entry) => sum + entry.bytes, 0);
36
+ const settings = EventSettings.read({ root: opts.root });
37
+
38
+ if (EventRetention.isActive({ settings })) {
39
+ const dir = EventSettings.dirOf({ root: opts.root, settings });
40
+ const plan = EventRetention.plan({ dir, limits: EventRetention.limitsOf({ settings }), now });
41
+ const events = EventRetention.apply({ dir, plan });
42
+
43
+ files += events.files;
44
+ bytes += events.bytes;
45
+ }
46
+
47
+ const previous = LocalAutoClean.readStamp({ root: opts.root });
48
+
49
+ LocalAutoClean.writeStamp({
50
+ root: opts.root,
51
+ stamp: {
52
+ day: previous?.day ?? EventLog.dayOf({ time: now }),
53
+ startedAt: previous?.startedAt ?? new Date(now).toISOString(),
54
+ removedFiles: files,
55
+ removedBytes: bytes,
56
+ reported: false,
57
+ },
58
+ });
59
+
60
+ return { files, bytes };
61
+ }
62
+
63
+ /**
64
+ * Whether `path`, or anything under it, is a `.git` file or folder (a clone has the folder, a worktree the file). A
65
+ * link is not followed and `node_modules` is not entered. A tree too big to look through counts as holding one.
66
+ */
67
+ static holdsRepository(opts: { path: string; budget?: { left: number } }): boolean {
68
+ const budget = opts.budget ?? { left: AutoCleanRun.LOOK_LIMIT };
69
+
70
+ try {
71
+ if (!lstatSync(opts.path).isDirectory()) {
72
+ return false;
73
+ }
74
+
75
+ for (const name of readdirSync(opts.path)) {
76
+ budget.left -= 1;
77
+
78
+ if (budget.left < 0 || name === '.git') {
79
+ return true;
80
+ }
81
+
82
+ if (
83
+ name !== 'node_modules' &&
84
+ AutoCleanRun.holdsRepository({ path: join(opts.path, name), budget })
85
+ ) {
86
+ return true;
87
+ }
88
+ }
89
+
90
+ return false;
91
+ } catch {
92
+ // What cannot be read cannot be judged: it stays.
93
+ return true;
94
+ }
95
+ }
96
+
97
+ /** How many entries are looked at before a tree counts as holding a repository. */
98
+ static readonly LOOK_LIMIT = 20_000;
99
+ }
@@ -0,0 +1,147 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { BASE_DIRECTORY } from '../common/paths.ts';
5
+ import { RecordValue } from '../common/record.ts';
6
+ import { EventLog } from '../events/log.ts';
7
+ import { LocalFormat } from './format.ts';
8
+
9
+ export interface IAutoCleanStamp {
10
+ /** The local day of the last run, `2026-11-03`. */
11
+ day: string;
12
+ startedAt: string;
13
+ removedFiles: number;
14
+ removedBytes: number;
15
+ /** Whether a session has already printed what that run removed. */
16
+ reported: boolean;
17
+ }
18
+
19
+ /**
20
+ * The automatic clean of `.agents/local/`, as the session-start hook sees it: at most once a day it starts a detached
21
+ * process that removes the safe part (see `AutoCleanRun`) and leaves a stamp. Everything here is a stat and a read of two
22
+ * small files, so a session that finds nothing due does not wait.
23
+ */
24
+ export class LocalAutoClean {
25
+ static readonly STAMP = '.agents/local/auto-clean.json';
26
+ static readonly OFF_ENV = 'VULCAN_AUTO_CLEAN';
27
+ static readonly SCRIPT = join('hooks', 'auto-clean.ts');
28
+
29
+ /** On unless the project's manifest says `local.autoClean: false`, or the environment says `VULCAN_AUTO_CLEAN=off`. */
30
+ static isEnabled(opts: { root: string; env: Record<string, string | undefined> }): boolean {
31
+ if (opts.env[LocalAutoClean.OFF_ENV] === 'off') {
32
+ return false;
33
+ }
34
+
35
+ try {
36
+ const manifest: unknown = JSON.parse(
37
+ readFileSync(join(opts.root, '.agents/vulcan.manifest.json'), 'utf8'),
38
+ );
39
+ const local = RecordValue.isRecord(manifest) ? manifest.local : undefined;
40
+
41
+ return !(RecordValue.isRecord(local) && local.autoClean === false);
42
+ } catch {
43
+ return true;
44
+ }
45
+ }
46
+
47
+ static readStamp(opts: { root: string }): IAutoCleanStamp | undefined {
48
+ try {
49
+ const value: unknown = JSON.parse(
50
+ readFileSync(join(opts.root, LocalAutoClean.STAMP), 'utf8'),
51
+ );
52
+
53
+ if (
54
+ RecordValue.isRecord(value) &&
55
+ typeof value.day === 'string' &&
56
+ typeof value.startedAt === 'string' &&
57
+ typeof value.removedFiles === 'number' &&
58
+ typeof value.removedBytes === 'number' &&
59
+ typeof value.reported === 'boolean'
60
+ ) {
61
+ return {
62
+ day: value.day,
63
+ startedAt: value.startedAt,
64
+ removedFiles: value.removedFiles,
65
+ removedBytes: value.removedBytes,
66
+ reported: value.reported,
67
+ };
68
+ }
69
+ } catch {
70
+ // No stamp, or one that is not ours: the clean is due.
71
+ }
72
+
73
+ return undefined;
74
+ }
75
+
76
+ static writeStamp(opts: { root: string; stamp: IAutoCleanStamp }): void {
77
+ writeFileSync(join(opts.root, LocalAutoClean.STAMP), `${JSON.stringify(opts.stamp)}\n`);
78
+ }
79
+
80
+ /**
81
+ * Called at session start. Does nothing when the project has no `.agents/local/`, turned the clean off, or already ran
82
+ * today. Otherwise it writes today's stamp first (a second session that starts a moment later finds it) and starts the
83
+ * clean in a process of its own that outlives the hook. Returns the one line to print, or `undefined`: the line says what the
84
+ * last finished run removed, once, because the run itself ends after the hook did.
85
+ */
86
+ static tick(opts: {
87
+ root: string;
88
+ now?: number;
89
+ env?: Record<string, string | undefined>;
90
+ start?: (opts: { root: string }) => void;
91
+ }): string | undefined {
92
+ const now = opts.now ?? Date.now();
93
+
94
+ if (
95
+ !existsSync(join(opts.root, '.agents/local')) ||
96
+ !LocalAutoClean.isEnabled({ root: opts.root, env: opts.env ?? process.env })
97
+ ) {
98
+ return undefined;
99
+ }
100
+
101
+ const today = EventLog.dayOf({ time: now });
102
+ const stamp = LocalAutoClean.readStamp({ root: opts.root });
103
+ const pending =
104
+ stamp !== undefined && !stamp.reported && stamp.removedBytes > 0 ? stamp : undefined;
105
+ const line =
106
+ pending === undefined
107
+ ? undefined
108
+ : `vulcan: cleaned ${LocalFormat.formatBytes({ bytes: pending.removedBytes })} from .agents/local`;
109
+
110
+ if (stamp?.day === today) {
111
+ if (pending !== undefined) {
112
+ LocalAutoClean.writeStamp({ root: opts.root, stamp: { ...pending, reported: true } });
113
+ }
114
+
115
+ return line;
116
+ }
117
+
118
+ LocalAutoClean.writeStamp({
119
+ root: opts.root,
120
+ stamp: {
121
+ day: today,
122
+ startedAt: new Date(now).toISOString(),
123
+ removedFiles: 0,
124
+ removedBytes: 0,
125
+ reported: true,
126
+ },
127
+ });
128
+ (opts.start ?? LocalAutoClean.startDetached)({ root: opts.root });
129
+
130
+ return line;
131
+ }
132
+
133
+ /** Starts `base/hooks/auto-clean.ts` for `root` as a detached process: the hook does not wait for it and its end does not matter to the session. */
134
+ static startDetached(opts: { root: string }): void {
135
+ const child = spawn(
136
+ process.execPath,
137
+ [join(BASE_DIRECTORY, LocalAutoClean.SCRIPT), opts.root],
138
+ {
139
+ detached: true,
140
+ stdio: 'ignore',
141
+ },
142
+ );
143
+
144
+ child.on('error', () => {});
145
+ child.unref();
146
+ }
147
+ }
@@ -1,6 +1,9 @@
1
1
  import { spawnSync } from 'node:child_process';
2
2
  import { existsSync, lstatSync, rmSync, unlinkSync } from 'node:fs';
3
- import { LocalConstants } from './constants.ts';
3
+ import { basename, dirname } from 'node:path';
4
+ import { EventRetention } from '../events/retention.ts';
5
+ import { EventSettings } from '../events/settings.ts';
6
+ import { CleanScopes, LocalConstants } from './constants.ts';
4
7
  import { LocalScan } from './scan.ts';
5
8
  import type { ILocalEntry } from './scan.ts';
6
9
 
@@ -17,10 +20,39 @@ const git = (opts: { cwd: string; args: string[] }): boolean =>
17
20
  timeout: LocalConstants.GIT_TIMEOUT_MS,
18
21
  }).status === 0;
19
22
 
23
+ /**
24
+ * Removes one day file of an event log kept outside the project. Only a plain file named `yyyy-mm-dd.jsonl`, directly
25
+ * in the folder the project's settings name, is ever removed; anything else is refused.
26
+ */
27
+ const removeSharedEvent = (opts: { root: string; entry: ILocalEntry }): string | undefined => {
28
+ const { entry } = opts;
29
+
30
+ try {
31
+ if (
32
+ entry.scope !== CleanScopes.EVENTS ||
33
+ !EventRetention.isDayFile({ name: basename(entry.path) }) ||
34
+ dirname(entry.path) !== EventSettings.dirOf({ root: opts.root }) ||
35
+ !lstatSync(entry.path).isFile()
36
+ ) {
37
+ return 'refused: not a day file in the folder events.dir names';
38
+ }
39
+
40
+ unlinkSync(entry.path);
41
+
42
+ return undefined;
43
+ } catch (error) {
44
+ return error instanceof Error ? error.message : String(error);
45
+ }
46
+ };
47
+
20
48
  /** Removes one entry. Only a path inside `.agents/local/` is touched, and a symlink is unlinked, never followed. */
21
49
  const removeEntry = (opts: { root: string; entry: ILocalEntry }): string | undefined => {
22
50
  const { entry } = opts;
23
51
 
52
+ if (entry.outside === true) {
53
+ return removeSharedEvent({ root: opts.root, entry });
54
+ }
55
+
24
56
  if (!LocalScan.isInside({ root: opts.root, path: entry.path })) {
25
57
  return 'refused: the path is not inside .agents/local/';
26
58
  }
@@ -58,6 +58,7 @@ export class LocalConstants {
58
58
  'profile.json',
59
59
  'claude.launch.settings.json',
60
60
  'violations.jsonl',
61
+ 'auto-clean.json',
61
62
  '.gitkeep',
62
63
  ]);
63
64
  /**
@@ -2,3 +2,4 @@ export * from './constants.ts';
2
2
  export * from './scan.ts';
3
3
  export * from './clean.ts';
4
4
  export * from './format.ts';
5
+ export * from './auto-clean.ts';
package/src/local/scan.ts CHANGED
@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process';
2
2
  import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
3
3
  import { join, resolve, sep } from 'node:path';
4
4
  import { ProjectLayout } from '../common/index.ts';
5
+ import { EventRetention } from '../events/retention.ts';
6
+ import { EventSettings } from '../events/settings.ts';
5
7
  import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
6
8
 
7
9
  /** One thing under `.agents/local/`: a child of one of its directories, or the profile file. */
@@ -19,6 +21,8 @@ export interface ILocalEntry {
19
21
  isSymlink: boolean;
20
22
  /** A registered git worktree: removed with `git worktree remove`, then pruned. */
21
23
  registered: boolean;
24
+ /** A day file of an event log kept outside the project (`events.dir`): removed only after its folder is checked against the settings. */
25
+ outside?: boolean;
22
26
  note: string;
23
27
  }
24
28
 
@@ -416,7 +420,7 @@ export class LocalScan {
416
420
  }
417
421
 
418
422
  /** Every entry of `.agents/local/`, with size, age and what may be removed. Nothing is followed outside it. */
419
- static scan(opts: { root: string; now?: number }): ILocalEntry[] {
423
+ static scan(opts: { root: string; now?: number; only?: string[] }): ILocalEntry[] {
420
424
  const local = LocalScan.localRootOf({ root: opts.root });
421
425
  const now = opts.now ?? Date.now();
422
426
 
@@ -424,11 +428,31 @@ export class LocalScan {
424
428
  return [];
425
429
  }
426
430
 
427
- const registered = LocalScan.registeredWorktrees({ root: opts.root });
431
+ // `only` names the folders to look at: the automatic clean asks for two and never starts git for the worktrees.
432
+ const wants = (name: string): boolean => opts.only === undefined || opts.only.includes(name);
433
+ const registered = wants(CleanScopes.WORKTREES)
434
+ ? LocalScan.registeredWorktrees({ root: opts.root })
435
+ : undefined;
428
436
  const entries: ILocalEntry[] = [];
437
+ // The event log is where the project's settings put it (`events.dir`, else `.agents/local/events`), with its limits.
438
+ const eventSettings = EventSettings.read({ root: opts.root });
439
+ const eventsDir = EventSettings.dirOf({ root: opts.root, settings: eventSettings });
440
+ const eventPlan = wants(CleanScopes.EVENTS)
441
+ ? EventRetention.plan({
442
+ dir: eventsDir,
443
+ limits: EventRetention.limitsOf({ settings: eventSettings }),
444
+ now,
445
+ })
446
+ : undefined;
447
+ const isEventsOutside = !`${eventsDir}${sep}`.startsWith(`${local}${sep}`);
429
448
 
430
449
  for (const layout of ProjectLayout.LOCAL_LAYOUT) {
431
- const directory = join(local, layout.name);
450
+ if (!wants(layout.name)) {
451
+ continue;
452
+ }
453
+
454
+ const isEvents = layout.name === CleanScopes.EVENTS;
455
+ const directory = isEvents ? eventsDir : join(local, layout.name);
432
456
 
433
457
  if (!isRealDirectory({ path: directory })) {
434
458
  continue;
@@ -457,6 +481,17 @@ export class LocalScan {
457
481
  });
458
482
 
459
483
  ({ state, removable, registered: isRegistered, note } = verdict);
484
+ } else if (layout.name === CleanScopes.EVENTS) {
485
+ // Day files are removed by the limits of `events` (age, count, size), never all at once and never today's.
486
+ const goes = eventPlan?.remove.find((file) => file.name === name);
487
+
488
+ ({ removable, note } =
489
+ goes === undefined
490
+ ? {
491
+ removable: false,
492
+ note: 'within the limits of events (maxSize, maxFiles, maxAgeDays)',
493
+ }
494
+ : { removable: true, note: goes.reason });
460
495
  } else if (layout.name === CleanScopes.RELEASE_CANDIDATES) {
461
496
  // A candidate is named by its version: once that version is tagged the release has shipped.
462
497
  const isShipped =
@@ -483,7 +518,8 @@ export class LocalScan {
483
518
  entries.push({
484
519
  scope: layout.name,
485
520
  name,
486
- where: `${layout.name}/${name}`,
521
+ // An event log kept outside the project is named by its whole path.
522
+ where: isEvents && isEventsOutside ? path : `${layout.name}/${name}`,
487
523
  path,
488
524
  bytes: sizeOf({ path }),
489
525
  ageMs,
@@ -492,13 +528,14 @@ export class LocalScan {
492
528
  isSymlink: stat.isSymbolicLink(),
493
529
  registered: isRegistered,
494
530
  note,
531
+ ...(isEvents && isEventsOutside ? { outside: true } : {}),
495
532
  });
496
533
  }
497
534
  }
498
535
 
499
536
  const profile = join(local, 'profile.json');
500
537
 
501
- if (existsSync(profile)) {
538
+ if (wants(CleanScopes.PROFILE) && existsSync(profile)) {
502
539
  const stat = lstatSync(profile);
503
540
 
504
541
  entries.push({
@@ -516,7 +553,7 @@ export class LocalScan {
516
553
  });
517
554
  }
518
555
 
519
- return [...entries, ...LocalScan.strays({ local, now })];
556
+ return [...entries, ...(wants(CleanScopes.TMP) ? LocalScan.strays({ local, now }) : [])];
520
557
  }
521
558
 
522
559
  /**
@@ -79,9 +79,39 @@ const ciBlockOf = (opts: { config: TResolvedConfig }): { ci?: Record<string, unk
79
79
 
80
80
  /** The manifest's `events` block, which the hooks and `vulcan event` read: only when the log is on or has a folder. */
81
81
  const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<string, unknown> } => {
82
- const { log, dir } = opts.config.events;
82
+ const { log, dir, maxSize, maxFiles, maxAgeDays } = opts.config.events;
83
+ const limits = {
84
+ ...(maxSize === undefined ? {} : { maxSize }),
85
+ ...(maxFiles === undefined ? {} : { maxFiles }),
86
+ ...(maxAgeDays === undefined ? {} : { maxAgeDays }),
87
+ };
88
+
89
+ return log || dir !== undefined || Object.keys(limits).length > 0
90
+ ? { events: { log, ...(dir === undefined ? {} : { dir }), ...limits } }
91
+ : {};
92
+ };
83
93
 
84
- return log || dir !== undefined ? { events: { log, ...(dir === undefined ? {} : { dir }) } } : {};
94
+ /** The manifest's `local` block: only when the project turns the automatic clean off, which the hook reads. */
95
+ const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } =>
96
+ opts.config.local.autoClean ? {} : { local: { autoClean: false } };
97
+
98
+ /** The manifest's `board` block, which `vulcan board` reads: only what the project sets. */
99
+ const boardBlockOf = (opts: { config: TResolvedConfig }): { board?: Record<string, unknown> } => {
100
+ const { owner, title, logo, agents } = opts.config.board;
101
+
102
+ return owner === undefined &&
103
+ title === undefined &&
104
+ logo === undefined &&
105
+ Object.keys(agents).length === 0
106
+ ? {}
107
+ : {
108
+ board: {
109
+ ...(owner === undefined ? {} : { owner }),
110
+ ...(title === undefined ? {} : { title }),
111
+ ...(logo === undefined ? {} : { logo }),
112
+ ...(Object.keys(agents).length === 0 ? {} : { agents }),
113
+ },
114
+ };
85
115
  };
86
116
 
87
117
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
@@ -180,6 +210,10 @@ export class ProjectManifest {
180
210
  ...commitBlockOf({ config }),
181
211
  // The files the project adds to the ones that make every package affected; none added, nothing is written.
182
212
  ...ciBlockOf({ config }),
213
+ // The names and the logo `vulcan board` puts on its page; nothing set, nothing is written.
214
+ ...boardBlockOf({ config }),
215
+ // The automatic clean of .agents/local is on unless the project turns it off here.
216
+ ...localBlockOf({ config }),
183
217
  // Whether the Claude Code hooks write the agent event log, and the folder it goes to.
184
218
  ...eventsBlockOf({ config }),
185
219
  };