feat(cli): cleanup watch capability — stale file housekeeping (#791) by tamirdresher · Pull Request #794 · bradygaster/squad

tamirdresher · 2026-04-03T18:46:13Z

What

New cleanup watch capability in the housekeeping phase that removes stale temp files, archives old logs, and warns about stale inbox files.

Why

Squad state directories accumulate files over time — old session logs, orchestration entries, scratch files. No automated cleanup exists. Closes #791

How

Clears .squad/.scratch/ (all ephemeral temp files)
Deletes orchestration-log and session-log entries older than N days (default: 30)
Warns about stale decision inbox files (>7 days)
Runs every N rounds (default: 10, configurable via everyNRounds)
Registered in capability barrel (index.ts)

Testing

npm run build passes
npm test passes (12 new tests — metadata, preflight, scratch clearing, log archival, inbox warnings, round skipping, custom config)

Docs

Changeset entry (cleanup-ceremony.md)
Feature doc page (will be added in follow-up commit)

Exports

N/A (CLI internal capability)

Breaking Changes

None

Waivers

None

…791) - New cleanup capability in housekeeping phase - Clears .squad/.scratch/ temp files - Archives old orchestration-log and session-log entries (>30d) - Warns about stale decision inbox files (>7d) - Configurable: everyNRounds, maxAgeDays - 12 new tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-03T18:46:24Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit ed6c014

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	2 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	15 check(s) still running

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

Copilot

Pull request overview

Adds a new cleanup watch capability in the housekeeping phase to proactively remove stale .squad/ artifacts (scratch + old logs) and surface stale decision inbox items.

Changes:

Introduces CleanupCapability and registers it in the default watch capability registry.
Implements scratch clearing, age-based log/orchestration cleanup, and stale inbox warnings with configurable cadence/retention.
Adds a dedicated Vitest suite covering capability behavior and configuration.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
`packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts`	New cleanup capability implementation (scratch/log cleanup + inbox staleness warning).
`packages/squad-cli/src/cli/commands/watch/capabilities/index.ts`	Registers `CleanupCapability` in the built-in capability registry.
`test/watch-cleanup.test.ts`	Adds unit tests for cleanup metadata, preflight, execution behavior, and config handling.
`.changeset/cleanup-ceremony.md`	Release note for the new watch capability.

Copilot · 2026-04-03T18:50:38Z

packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts

+export class CleanupCapability implements WatchCapability {
+  readonly name = 'cleanup';
+  readonly description = 'Remove stale scratch files, archive old logs, warn about stale inbox';
+  readonly configShape = 'object' as const;


The capability claims it “archives” old log/orchestration entries (and reports them as archived), but the implementation only unlinks the files (deleteSync). Either implement a real archive/move, or rename the user-facing strings/variable names to “deleted/removed” to avoid misleading housekeeping output.

Copilot · 2026-04-03T18:50:38Z

packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts

+    // 1. Clear .squad/.scratch/ — everything in here is ephemeral
+    const scratchDir = path.join(squadDir, '.scratch');
+    const scratchFiles = safeList(scratchDir);
+    let scratchDeleted = 0;
+    for (const f of scratchFiles) {
+      if (safeDelete(path.join(scratchDir, f))) scratchDeleted++;
+    }
+    if (scratchDeleted > 0) {
+      actions.push(`scratch: ${scratchDeleted} files cleared`);
+    }


Scratch cleanup iterates entries and calls deleteSync (unlink). If .squad/.scratch/ contains subdirectories (or nested trees), unlink will fail and the cleanup run may incorrectly report “nothing to do” or undercount deletions. Consider detecting directories and using deleteDirSync (recursive) or a recursive traversal to truly “delete everything” in scratch.

Copilot · 2026-04-03T18:50:38Z

packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts

+function parseConfig(raw: Record<string, unknown>): CleanupConfig {
+  return {
+    everyNRounds: typeof raw.everyNRounds === 'number' ? raw.everyNRounds : DEFAULT_EVERY_N_ROUNDS,
+    maxAgeDays: typeof raw.maxAgeDays === 'number' ? raw.maxAgeDays : DEFAULT_MAX_AGE_DAYS,


parseConfig accepts any number values for everyNRounds / maxAgeDays (including 0, negatives, NaN, Infinity). everyNRounds <= 0 (or NaN) causes the modulo check to behave unexpectedly (often skipping forever except round 1), and negative ages invert retention. Clamp/validate to finite integers (e.g., everyNRounds >= 1, maxAgeDays >= 0) and fall back to defaults on invalid input.

Suggested change

function parseConfig(raw: Record<string, unknown>): CleanupConfig {

return {

everyNRounds: typeof raw.everyNRounds === 'number' ? raw.everyNRounds : DEFAULT_EVERY_N_ROUNDS,

maxAgeDays: typeof raw.maxAgeDays === 'number' ? raw.maxAgeDays : DEFAULT_MAX_AGE_DAYS,

function parseIntegerConfig(value: unknown, minimum: number, fallback: number): number {

if (typeof value !== 'number' || !Number.isFinite(value)) {

return fallback;

}

const normalized = Math.floor(value);

return normalized >= minimum ? normalized : fallback;

}

function parseConfig(raw: Record<string, unknown>): CleanupConfig {

return {

everyNRounds: parseIntegerConfig(raw.everyNRounds, 1, DEFAULT_EVERY_N_ROUNDS),

maxAgeDays: parseIntegerConfig(raw.maxAgeDays, 0, DEFAULT_MAX_AGE_DAYS),

Copilot · 2026-04-03T18:50:38Z

packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts

+  const fileDate = new Date(match[1]!);
+  if (isNaN(fileDate.getTime())) return false;
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+  return fileDate < cutoff;


Date parsing mixes UTC (new Date('YYYY-MM-DD') is parsed as UTC midnight) with a local-time cutoff (new Date(); cutoff.setDate(...)). This can produce off-by-one behavior around day boundaries/timezones. Consider computing the cutoff in UTC (setUTCDate / Date.UTC) or comparing by date-only strings consistently.

Suggested change

const fileDate = new Date(match[1]!);

if (isNaN(fileDate.getTime())) return false;

const cutoff = new Date();

cutoff.setDate(cutoff.getDate() - days);

return fileDate < cutoff;

const fileDateString = match[1]!;

const fileDate = new Date(`${fileDateString}T00:00:00.000Z`);

if (isNaN(fileDate.getTime())) return false;

if (fileDate.toISOString().slice(0, 10) !== fileDateString) return false;

const cutoff = new Date();

cutoff.setUTCDate(cutoff.getUTCDate() - days);

const cutoffDateString = cutoff.toISOString().slice(0, 10);

return fileDateString < cutoffDateString;

Copilot · 2026-04-03T18:50:39Z

.changeset/cleanup-ceremony.md

+- Warns about stale decision inbox files (>7 days)
+- Configurable: `everyNRounds` (default: 10), `maxAgeDays` (default: 30)
+- 11 new tests


The changeset claims “11 new tests”, but test/watch-cleanup.test.ts adds 12 it(...) cases. Update the count (or adjust the tests) so the release note matches the actual PR contents.

- Rename 'archive' to 'prune' in all log messages and comments - Use rmSync with recursive to handle subdirectories in .scratch/ - Add Number.isFinite and >0 guards to parseConfig validation - Use Date.now() consistently for UTC cutoff calculation - Fix changeset: correct test count from 11 to 12 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher · 2026-04-04T19:27:07Z

Superseded by #830 — combined into a single watch next-gen PR for easier review.

tamirdresher · 2026-04-04T20:11:22Z

Closing — superseded by #830 (watch-next-gen combined PR)

tamirdresher requested review from Copilot and diberry April 3, 2026 18:46

Copilot started reviewing on behalf of tamirdresher April 3, 2026 18:46 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

tamirdresher and others added 2 commits April 4, 2026 18:29

Merge branch 'dev' into squad/791-cleanup-ceremony

bc60dee

tamirdresher mentioned this pull request Apr 4, 2026

feat(watch): next-gen watch with execute redesign, robustness, and PS1 parity #830

Merged

tamirdresher closed this Apr 4, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): cleanup watch capability — stale file housekeeping (#791)#794

feat(cli): cleanup watch capability — stale file housekeeping (#791)#794
tamirdresher wants to merge 3 commits intodevfrom
squad/791-cleanup-ceremony

tamirdresher commented Apr 3, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-function parseConfig(raw: Record<string, unknown>): CleanupConfig {
-  return {
-    everyNRounds: typeof raw.everyNRounds === 'number' ? raw.everyNRounds : DEFAULT_EVERY_N_ROUNDS,
-    maxAgeDays: typeof raw.maxAgeDays === 'number' ? raw.maxAgeDays : DEFAULT_MAX_AGE_DAYS,
+function parseIntegerConfig(value: unknown, minimum: number, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.floor(value);
+  return normalized >= minimum ? normalized : fallback;
+}
+function parseConfig(raw: Record<string, unknown>): CleanupConfig {
+  return {
+    everyNRounds: parseIntegerConfig(raw.everyNRounds, 1, DEFAULT_EVERY_N_ROUNDS),
+    maxAgeDays: parseIntegerConfig(raw.maxAgeDays, 0, DEFAULT_MAX_AGE_DAYS),

Conversation

tamirdresher commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Testing

Docs

Exports

Breaking Changes

Waivers

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 4 item(s) to address before review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tamirdresher commented Apr 3, 2026 •

edited

Loading

github-actions bot commented Apr 3, 2026 •

edited

Loading