crewly 1.20.158 → 1.20.159

package/dist/backend/backend/src/services/worktree/low-disk-guard.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Low-disk guard — pure helpers for the disk janitor's free-space check.
+ *
+ * The janitor checks free space on the volume holding CREWLY_HOME every
+ * 10 minutes. Below 15 GB it cleans up at once with shorter idle thresholds;
+ * if space is still short it tells the owner (at most once per 24 h, or once
+ * per 6 h and marked urgent below 5 GB) what it could not remove and why.
+ * This file holds the decisions and the wording; the service does the I/O.
+ *
+ * @module services/worktree/low-disk-guard
+ */
+/** Subset of `fs.StatFs` the guard needs (numbers or bigints). */
+export interface StatFsLike {
+    /** Free blocks available to unprivileged users */
+    bavail: number | bigint;
+    /** Block size in bytes */
+    bsize: number | bigint;
+}
+/** `fs.promises.statfs`-compatible probe. */
+export type StatFsFn = (p: string) => Promise<StatFsLike>;
+/** Disk level relative to the thresholds. */
+export type DiskLevel = 'ok' | 'low' | 'critical';
+/** When the owner was last told about low disk (persisted). */
+export interface LowDiskNoticeState {
+    /** Last notice of any kind (ms epoch) */
+    lastNoticeAt?: number;
+    /** Last urgent notice (ms epoch) */
+    lastUrgentAt?: number;
+}
+/** Something the janitor looked at and left on disk. */
+export interface KeptItem {
+    /** Absolute path */
+    path: string;
+    /** Size in bytes */
+    bytes: number;
+    /** Janitor reason code (`dirty`, `not-merged`, `unpushed`, …) */
+    reason: string;
+}
+/**
+ * Free bytes on the volume holding `p`.
+ *
+ * @param p - Any path on the volume
+ * @param statfs - Probe (default `fs.promises.statfs`)
+ * @returns Free bytes for unprivileged users, or null when the probe failed
+ */
+export declare function readFreeBytes(p: string, statfs?: StatFsFn): Promise<number | null>;
+/**
+ * Classify free space.
+ *
+ * @param freeBytes - Free bytes
+ * @returns `critical` below CRITICAL_DISK_BYTES, `low` below LOW_DISK_BYTES, else `ok`
+ */
+export declare function diskLevel(freeBytes: number): DiskLevel;
+/**
+ * Idle threshold to use, shortened in low-disk mode.
+ *
+ * @param normalMs - Threshold in normal mode
+ * @param lowDisk - Whether free space is below LOW_DISK_BYTES
+ * @returns `normalMs`, or `normalMs / LOW_DISK_IDLE_DIVISOR` floored at LOW_DISK_MIN_IDLE_FLOOR_MS
+ *
+ * @example
+ * ```typescript
+ * idleThreshold(24 * HOUR, true); // 12 h
+ * idleThreshold(2 * HOUR, true);  // 2 h (floor)
+ * ```
+ */
+export declare function idleThreshold(normalMs: number, lowDisk: boolean): number;
+/**
+ * Whether to tell the owner now, and how.
+ *
+ * @param level - Current disk level (after cleanup)
+ * @param state - When the owner was last told
+ * @param now - Current time (ms)
+ * @returns `urgent`, `normal`, or null (nothing to send)
+ */
+export declare function noticeToSend(level: DiskLevel, state: LowDiskNoticeState, now: number): 'urgent' | 'normal' | null;
+/**
+ * The state after a notice went out.
+ *
+ * @param state - Previous state
+ * @param kind - What was sent
+ * @param now - Send time (ms)
+ * @returns New state
+ */
+export declare function recordNotice(state: LowDiskNoticeState, kind: 'urgent' | 'normal', now: number): LowDiskNoticeState;
+/**
+ * Plain-English reason for a kept item.
+ *
+ * @param reason - Janitor reason code
+ * @returns Short phrase ("has changes that were never committed")
+ */
+export declare function describeReason(reason: string): string;
+/**
+ * Owner notice for low disk: free space, what was freed, and the biggest
+ * items left with the reason, short enough for a phone.
+ *
+ * @param input - Free bytes, urgency, bytes freed this pass, kept items
+ * @returns Title and message
+ */
+export declare function buildLowDiskNotice(input: {
+    freeBytes: number;
+    urgent: boolean;
+    freedBytes: number;
+    items: KeptItem[];
+}): {
+    title: string;
+    message: string;
+};
+//# sourceMappingURL=low-disk-guard.d.ts.map

package/dist/backend/backend/src/services/worktree/low-disk-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"low-disk-guard.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/worktree/low-disk-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,kEAAkE;AAClE,MAAM,WAAW,UAAU;IAC1B,kDAAkD;IAClD,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAE1D,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,KAAK,GAAG,UAAU,CAAC;AAElD,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACxB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,QAAwB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvG;AAMD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAItD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAIxE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAQjH;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAElH;AAqBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;CAClB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkBrC"}

package/dist/backend/backend/src/services/worktree/low-disk-guard.js

@@ -0,0 +1,148 @@
+/**
+ * Low-disk guard — pure helpers for the disk janitor's free-space check.
+ *
+ * The janitor checks free space on the volume holding CREWLY_HOME every
+ * 10 minutes. Below 15 GB it cleans up at once with shorter idle thresholds;
+ * if space is still short it tells the owner (at most once per 24 h, or once
+ * per 6 h and marked urgent below 5 GB) what it could not remove and why.
+ * This file holds the decisions and the wording; the service does the I/O.
+ *
+ * @module services/worktree/low-disk-guard
+ */
+import * as fs from 'fs';
+import { WORKTREE_JANITOR_CONSTANTS } from '../../constants.js';
+import { formatBytes } from './worktree-janitor.git.js';
+/**
+ * Free bytes on the volume holding `p`.
+ *
+ * @param p - Any path on the volume
+ * @param statfs - Probe (default `fs.promises.statfs`)
+ * @returns Free bytes for unprivileged users, or null when the probe failed
+ */
+export async function readFreeBytes(p, statfs = defaultStatFs) {
+    try {
+        const s = await statfs(p);
+        return Number(s.bavail) * Number(s.bsize);
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultStatFs(p) {
+    return fs.promises.statfs(p);
+}
+/**
+ * Classify free space.
+ *
+ * @param freeBytes - Free bytes
+ * @returns `critical` below CRITICAL_DISK_BYTES, `low` below LOW_DISK_BYTES, else `ok`
+ */
+export function diskLevel(freeBytes) {
+    if (freeBytes < WORKTREE_JANITOR_CONSTANTS.CRITICAL_DISK_BYTES)
+        return 'critical';
+    if (freeBytes < WORKTREE_JANITOR_CONSTANTS.LOW_DISK_BYTES)
+        return 'low';
+    return 'ok';
+}
+/**
+ * Idle threshold to use, shortened in low-disk mode.
+ *
+ * @param normalMs - Threshold in normal mode
+ * @param lowDisk - Whether free space is below LOW_DISK_BYTES
+ * @returns `normalMs`, or `normalMs / LOW_DISK_IDLE_DIVISOR` floored at LOW_DISK_MIN_IDLE_FLOOR_MS
+ *
+ * @example
+ * ```typescript
+ * idleThreshold(24 * HOUR, true); // 12 h
+ * idleThreshold(2 * HOUR, true);  // 2 h (floor)
+ * ```
+ */
+export function idleThreshold(normalMs, lowDisk) {
+    if (!lowDisk)
+        return normalMs;
+    const halved = normalMs / WORKTREE_JANITOR_CONSTANTS.LOW_DISK_IDLE_DIVISOR;
+    return Math.max(Math.min(normalMs, WORKTREE_JANITOR_CONSTANTS.LOW_DISK_MIN_IDLE_FLOOR_MS), halved);
+}
+/**
+ * Whether to tell the owner now, and how.
+ *
+ * @param level - Current disk level (after cleanup)
+ * @param state - When the owner was last told
+ * @param now - Current time (ms)
+ * @returns `urgent`, `normal`, or null (nothing to send)
+ */
+export function noticeToSend(level, state, now) {
+    if (level === 'ok')
+        return null;
+    if (level === 'critical') {
+        const last = state.lastUrgentAt;
+        return last === undefined || now - last >= WORKTREE_JANITOR_CONSTANTS.CRITICAL_DISK_NOTIFY_INTERVAL_MS ? 'urgent' : null;
+    }
+    const last = state.lastNoticeAt;
+    return last === undefined || now - last >= WORKTREE_JANITOR_CONSTANTS.LOW_DISK_NOTIFY_INTERVAL_MS ? 'normal' : null;
+}
+/**
+ * The state after a notice went out.
+ *
+ * @param state - Previous state
+ * @param kind - What was sent
+ * @param now - Send time (ms)
+ * @returns New state
+ */
+export function recordNotice(state, kind, now) {
+    return { ...state, lastNoticeAt: now, ...(kind === 'urgent' ? { lastUrgentAt: now } : {}) };
+}
+const REASON_TEXT = {
+    dirty: 'has changes that were never committed',
+    'not-merged': 'has work that is not merged yet',
+    unpushed: 'has commits that were never pushed',
+    stash: 'has stashed changes',
+    'no-remote': 'is a git repo with no remote, so its history may exist nowhere else',
+    'has-external-worktrees': 'has a worktree somewhere else that depends on it',
+    'contains-worktree': 'holds a worktree that is still in use or not finished',
+    recent: 'was used recently',
+    locked: 'is locked by a running tool',
+    'process-inside': 'a program is still open in it',
+    'agent-session-inside': 'an agent is working in it',
+    'cwd-probe-failed': 'could not check whether a program is using it',
+    'managed-by-workitem-worktrees': 'belongs to an open task',
+    'status-failed': 'git could not read it',
+    'git-failed': 'git could not read it',
+    'remove-failed': 'deleting it failed',
+};
+/**
+ * Plain-English reason for a kept item.
+ *
+ * @param reason - Janitor reason code
+ * @returns Short phrase ("has changes that were never committed")
+ */
+export function describeReason(reason) {
+    return REASON_TEXT[reason] ?? `kept (${reason})`;
+}
+/**
+ * Owner notice for low disk: free space, what was freed, and the biggest
+ * items left with the reason, short enough for a phone.
+ *
+ * @param input - Free bytes, urgency, bytes freed this pass, kept items
+ * @returns Title and message
+ */
+export function buildLowDiskNotice(input) {
+    const title = input.urgent ? 'URGENT: disk almost full' : 'Disk space is running low';
+    const lines = [];
+    lines.push(`Only ${formatBytes(input.freeBytes)} free on this machine.${input.urgent ? ' Crewly and the agents may stop working soon.' : ''}`);
+    lines.push(input.freedBytes > 0
+        ? `I cleaned up ${formatBytes(input.freedBytes)} of finished work, but it is not enough.`
+        : 'I found nothing more that is safe to delete on my own.');
+    const top = [...input.items].sort((a, b) => b.bytes - a.bytes).slice(0, WORKTREE_JANITOR_CONSTANTS.LOW_DISK_REPORT_ITEMS);
+    if (top.length > 0) {
+        lines.push('', 'Biggest things I left alone:');
+        for (const it of top)
+            lines.push(`• ${it.path} (${formatBytes(it.bytes)}) — ${describeReason(it.reason)}`);
+        lines.push('', 'Tell me which ones can go, or free up space another way.');
+    }
+    else {
+        lines.push('Please free up some space.');
+    }
+    return { title, message: lines.join('\n') };
+}
+//# sourceMappingURL=low-disk-guard.js.map

package/dist/backend/backend/src/services/worktree/low-disk-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"low-disk-guard.js","sourceRoot":"","sources":["../../../../../../backend/src/services/worktree/low-disk-guard.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/worktree/scratch-janitor.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Scratch janitor — removes stale Claude Code session scratch dirs.
+ *
+ * Claude Code gives every session a temp dir
+ * `<tmp>/claude-<uid>/<project-slug>/<session-uuid>/` (with `scratchpad/`
+ * inside). Agents clone whole repos and build test homes there — 0.5–1.8 GB
+ * each — and nothing ever deletes them; one Mac filled its disk with dozens
+ * of GB of week-old sessions. These are not worktrees, so the worktree rules
+ * never see them.
+ *
+ * ## Roots
+ * `<os.tmpdir()>/claude-<uid>`, `/private/tmp/claude-<uid>` and
+ * `/tmp/claude-<uid>`, de-duplicated by real path. Only the
+ * `<root>/<slug>/<uuid>/` pattern is a unit; anything else in the root
+ * (loose files, worktrees such as `<root>/visa-cm-wt`) is left alone here.
+ * Symlinks are never followed out of the root.
+ *
+ * ## A session dir is deleted only when ALL hold
+ * 1. Idle: the newest mtime of the dir and everything in its top two levels,
+ *    and of every git repo's HEAD / index / logs/HEAD inside it, is older
+ *    than 3 days (halved in low-disk mode, never below 2 h).
+ * 2. No process of this user (nor a Crewly agent session) has its cwd
+ *    inside. If the probe fails, everything is kept.
+ * 3. It holds no linked worktree of a repo outside it — those belong to the
+ *    worktree rules (`git worktree remove`), never `rm -rf`.
+ * 4. Every git repo inside (depth ≤ 3, `node_modules` skipped) is safe:
+ *    - `git status --porcelain --untracked-files=all` is empty (untracked
+ *      files count, ignored ones do not);
+ *    - it has a remote (no remote → kept: its commits may exist nowhere else);
+ *    - `git rev-list HEAD --branches --not --remotes` is empty (no local
+ *      commit missing from the remote-tracking refs) and there is no stash;
+ *    - it has no linked worktree outside the session dir (deleting the
+ *      clone would orphan it).
+ *    Any git error keeps the dir.
+ *
+ * @module services/worktree/scratch-janitor
+ */
+import { type CommandResult } from './worktree-janitor.git.js';
+/** Why a session dir is kept, or why it may go. */
+export type ScratchReason = 'recent' | 'process-inside' | 'agent-session-inside' | 'cwd-probe-failed' | 'contains-worktree' | 'dirty' | 'no-remote' | 'unpushed' | 'stash' | 'has-external-worktrees' | 'git-failed' | 'stale';
+/** Verdict and outcome for one session dir. */
+export interface ScratchVerdict {
+    /** Absolute session dir */
+    path: string;
+    /** What the janitor would do / did */
+    decision: 'remove' | 'keep';
+    /** The deciding rule */
+    reason: ScratchReason;
+    /** Repo (or path) that decided it, and what was found */
+    detail?: string;
+    /** Ms since last touched, when computed */
+    idleMs?: number;
+    /** Git repos found inside */
+    repos: string[];
+    /** True when the dir was deleted */
+    removed: boolean;
+    /** Bytes freed (measured before deletion), when removed */
+    freedBytes?: number;
+    /** Error text when deletion failed */
+    error?: string;
+}
+/** Result of one scratch sweep. */
+export interface ScratchSweepSummary {
+    /** Roots scanned (real paths) */
+    roots: string[];
+    /** Session dirs removed */
+    removed: number;
+    /** Dry run only: dirs a real sweep would remove */
+    wouldRemove: number;
+    /** Session dirs kept */
+    kept: number;
+    /** Bytes freed by removed dirs */
+    freedBytes: number;
+    /** Kept dirs by reason */
+    keptReasons: Record<string, number>;
+    /** Per-dir results */
+    sessions: ScratchVerdict[];
+}
+/** A place something is working in (same shape as the worktree janitor's). */
+export interface ScratchBusyCwd {
+    /** Absolute directory */
+    cwd: string;
+    /** `agent-session` for Crewly sessions, `process` for anything else */
+    source: 'agent-session' | 'process';
+}
+/** Inputs of one sweep. */
+export interface ScratchSweepInput {
+    /** Roots to scan (already resolved) */
+    roots: string[];
+    /** Busy cwds, or null when the probe failed */
+    busy: ScratchBusyCwd[] | null;
+    /** Current time (ms) */
+    now: number;
+    /** Minimum idle time */
+    minIdleMs: number;
+    /** When true, nothing is deleted */
+    dryRun: boolean;
+    /** git runner (`args` as for `git`) */
+    git: (args: string[]) => Promise<CommandResult>;
+    /** Size probe (default `du -sk`) */
+    sizeOf?: (p: string) => Promise<number | null>;
+}
+/**
+ * The per-user Claude Code temp roots that exist, de-duplicated by real path.
+ *
+ * @param uid - User id (default: process.getuid())
+ * @param tmpDir - System temp dir (default: os.tmpdir())
+ * @returns Existing root directories (real paths)
+ *
+ * @example
+ * ```typescript
+ * defaultScratchRoots(501); // ['/private/tmp/claude-501']
+ * ```
+ */
+export declare function defaultScratchRoots(uid?: number, tmpDir?: string): string[];
+/**
+ * Session dirs (`<root>/<slug>/<uuid>`) under a root. Symlinked slugs or
+ * session dirs are skipped, as is anything not matching the pattern. Async;
+ * yields to the event loop every few entries.
+ *
+ * @param root - A scratch root (real path)
+ * @returns Absolute session dirs
+ */
+export declare function listSessionDirs(root: string): Promise<string[]>;
+/**
+ * Evaluate one session dir. Read-only.
+ *
+ * @param dir - Session dir
+ * @param input - Sweep inputs
+ * @returns Verdict (not yet acted on)
+ */
+export declare function evaluateSessionDir(dir: string, input: ScratchSweepInput): Promise<ScratchVerdict>;
+/**
+ * One sweep over every session dir of every root. Never throws.
+ *
+ * @param input - Roots, busy cwds, clock, threshold, dry-run flag, git runner
+ * @returns Per-dir verdicts and totals
+ */
+export declare function sweepScratch(input: ScratchSweepInput): Promise<ScratchSweepSummary>;
+//# sourceMappingURL=scratch-janitor.d.ts.map

package/dist/backend/backend/src/services/worktree/scratch-janitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-janitor.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/worktree/scratch-janitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,OAAO,EAUN,KAAK,aAAa,EAElB,MAAM,2BAA2B,CAAC;AAEnC,mDAAmD;AACnD,MAAM,MAAM,aAAa,GACtB,QAAQ,GACR,gBAAgB,GAChB,sBAAsB,GACtB,kBAAkB,GAClB,mBAAmB,GACnB,OAAO,GACP,WAAW,GACX,UAAU,GACV,OAAO,GACP,wBAAwB,GACxB,YAAY,GACZ,OAAO,CAAC;AAEX,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC9B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,wBAAwB;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IACnC,iCAAiC;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,sBAAsB;IACtB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC9B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;CACpC;AAED,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB;IACjC,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,IAAI,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAC9B,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAChD,oCAAoC;IACpC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,GAAG,MAAM,EAAE,CAaxF;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBrE;AAOD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0DvG;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiCzF"}

package/dist/backend/backend/src/services/worktree/scratch-janitor.js

@@ -0,0 +1,249 @@
+/**
+ * Scratch janitor — removes stale Claude Code session scratch dirs.
+ *
+ * Claude Code gives every session a temp dir
+ * `<tmp>/claude-<uid>/<project-slug>/<session-uuid>/` (with `scratchpad/`
+ * inside). Agents clone whole repos and build test homes there — 0.5–1.8 GB
+ * each — and nothing ever deletes them; one Mac filled its disk with dozens
+ * of GB of week-old sessions. These are not worktrees, so the worktree rules
+ * never see them.
+ *
+ * ## Roots
+ * `<os.tmpdir()>/claude-<uid>`, `/private/tmp/claude-<uid>` and
+ * `/tmp/claude-<uid>`, de-duplicated by real path. Only the
+ * `<root>/<slug>/<uuid>/` pattern is a unit; anything else in the root
+ * (loose files, worktrees such as `<root>/visa-cm-wt`) is left alone here.
+ * Symlinks are never followed out of the root.
+ *
+ * ## A session dir is deleted only when ALL hold
+ * 1. Idle: the newest mtime of the dir and everything in its top two levels,
+ *    and of every git repo's HEAD / index / logs/HEAD inside it, is older
+ *    than 3 days (halved in low-disk mode, never below 2 h).
+ * 2. No process of this user (nor a Crewly agent session) has its cwd
+ *    inside. If the probe fails, everything is kept.
+ * 3. It holds no linked worktree of a repo outside it — those belong to the
+ *    worktree rules (`git worktree remove`), never `rm -rf`.
+ * 4. Every git repo inside (depth ≤ 3, `node_modules` skipped) is safe:
+ *    - `git status --porcelain --untracked-files=all` is empty (untracked
+ *      files count, ignored ones do not);
+ *    - it has a remote (no remote → kept: its commits may exist nowhere else);
+ *    - `git rev-list HEAD --branches --not --remotes` is empty (no local
+ *      commit missing from the remote-tracking refs) and there is no stash;
+ *    - it has no linked worktree outside the session dir (deleting the
+ *      clone would orphan it).
+ *    Any git error keeps the dir.
+ *
+ * @module services/worktree/scratch-janitor
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { WORKTREE_JANITOR_CONSTANTS } from '../../constants.js';
+import { canonicalPath, diskUsageBytes, EventLoopYielder, findGitCheckouts, isPathInside, latestTreeMtimeMs, latestWorktreeMtimeMs, parsePorcelainWorktrees, readGitFilePointer, } from './worktree-janitor.git.js';
+/**
+ * The per-user Claude Code temp roots that exist, de-duplicated by real path.
+ *
+ * @param uid - User id (default: process.getuid())
+ * @param tmpDir - System temp dir (default: os.tmpdir())
+ * @returns Existing root directories (real paths)
+ *
+ * @example
+ * ```typescript
+ * defaultScratchRoots(501); // ['/private/tmp/claude-501']
+ * ```
+ */
+export function defaultScratchRoots(uid, tmpDir = os.tmpdir()) {
+    const id = uid ?? (typeof process.getuid === 'function' ? process.getuid() : os.userInfo().uid);
+    const name = `${WORKTREE_JANITOR_CONSTANTS.SCRATCH_ROOT_PREFIX}${id}`;
+    const candidates = [tmpDir, ...WORKTREE_JANITOR_CONSTANTS.SCRATCH_TMP_DIRS].map((d) => path.join(d, name));
+    const out = new Set();
+    for (const c of candidates) {
+        try {
+            if (fs.lstatSync(c).isDirectory())
+                out.add(fs.realpathSync(c));
+        }
+        catch {
+            // missing
+        }
+    }
+    return [...out];
+}
+/**
+ * Session dirs (`<root>/<slug>/<uuid>`) under a root. Symlinked slugs or
+ * session dirs are skipped, as is anything not matching the pattern. Async;
+ * yields to the event loop every few entries.
+ *
+ * @param root - A scratch root (real path)
+ * @returns Absolute session dirs
+ */
+export async function listSessionDirs(root) {
+    const out = [];
+    const yielder = new EventLoopYielder();
+    let slugs;
+    try {
+        slugs = await fs.promises.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const slug of slugs) {
+        await yielder.tick();
+        if (!slug.isDirectory())
+            continue;
+        const slugDir = path.join(root, slug.name);
+        let sessions;
+        try {
+            sessions = await fs.promises.readdir(slugDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const s of sessions) {
+            if (!s.isDirectory() || !WORKTREE_JANITOR_CONSTANTS.SCRATCH_SESSION_DIR_PATTERN.test(s.name))
+                continue;
+            out.push(path.join(slugDir, s.name));
+        }
+    }
+    return out;
+}
+/** Git dir of a checkout (`.git` dir, or the one a `.git` file points to). */
+async function gitDirOf(repo) {
+    return repo.kind === 'dir' ? path.join(repo.path, '.git') : readGitFilePointer(repo.path);
+}
+/**
+ * Evaluate one session dir. Read-only.
+ *
+ * @param dir - Session dir
+ * @param input - Sweep inputs
+ * @returns Verdict (not yet acted on)
+ */
+export async function evaluateSessionDir(dir, input) {
+    const repos = await findGitCheckouts(dir, WORKTREE_JANITOR_CONSTANTS.SCRATCH_REPO_SEARCH_DEPTH);
+    const base = { path: dir, repos: repos.map((r) => r.path), removed: false };
+    const keep = (reason, detail, idleMs) => ({
+        ...base,
+        decision: 'keep',
+        reason,
+        ...(detail ? { detail } : {}),
+        ...(idleMs !== undefined ? { idleMs } : {}),
+    });
+    let newest = await latestTreeMtimeMs(dir, WORKTREE_JANITOR_CONSTANTS.SCRATCH_MTIME_DEPTH);
+    for (const r of repos) {
+        const gd = await gitDirOf(r);
+        const m = latestWorktreeMtimeMs(r.path, gd);
+        if (m !== null && (newest === null || m > newest))
+            newest = m;
+        if (gd) {
+            const logs = await latestTreeMtimeMs(path.join(gd, 'logs'), WORKTREE_JANITOR_CONSTANTS.SCRATCH_MTIME_DEPTH);
+            if (logs !== null && (newest === null || logs > newest))
+                newest = logs;
+        }
+    }
+    const idleMs = newest === null ? undefined : Math.max(0, input.now - newest);
+    if (idleMs === undefined || idleMs < input.minIdleMs)
+        return keep('recent', undefined, idleMs);
+    if (input.busy === null)
+        return keep('cwd-probe-failed', undefined, idleMs);
+    const hit = input.busy.find((b) => isPathInside(b.cwd, dir));
+    if (hit)
+        return keep(hit.source === 'agent-session' ? 'agent-session-inside' : 'process-inside', hit.cwd, idleMs);
+    for (const r of repos) {
+        if (r.kind === 'file') {
+            const common = await input.git(['-C', r.path, 'rev-parse', '--path-format=absolute', '--git-common-dir']);
+            if (common.code !== 0)
+                return keep('git-failed', `${r.path}: ${common.stderr.trim().slice(0, 200)}`, idleMs);
+            if (!isPathInside(common.stdout.trim(), dir))
+                return keep('contains-worktree', r.path, idleMs);
+        }
+        const status = await input.git(['-C', r.path, 'status', '--porcelain', '--untracked-files=all']);
+        if (status.code !== 0)
+            return keep('git-failed', `${r.path}: ${status.stderr.trim().slice(0, 200)}`, idleMs);
+        const dirty = status.stdout.split('\n').filter((l) => l.trim() !== '').length;
+        if (dirty > 0)
+            return keep('dirty', `${r.path}: ${dirty} changed/untracked path(s)`, idleMs);
+        const remotes = await input.git(['-C', r.path, 'remote']);
+        if (remotes.code !== 0)
+            return keep('git-failed', `${r.path}: ${remotes.stderr.trim().slice(0, 200)}`, idleMs);
+        if (remotes.stdout.trim() === '')
+            return keep('no-remote', r.path, idleMs);
+        const unpushed = await input.git(['-C', r.path, 'rev-list', '--max-count=1', 'HEAD', '--branches', '--not', '--remotes']);
+        if (unpushed.code !== 0)
+            return keep('git-failed', `${r.path}: ${unpushed.stderr.trim().slice(0, 200)}`, idleMs);
+        if (unpushed.stdout.trim() !== '')
+            return keep('unpushed', `${r.path}: commit ${unpushed.stdout.trim().slice(0, 12)} is on no remote`, idleMs);
+        const stash = await input.git(['-C', r.path, 'rev-parse', '--verify', '--quiet', 'refs/stash']);
+        if (stash.code === 0)
+            return keep('stash', r.path, idleMs);
+        const wts = await input.git(['-C', r.path, 'worktree', 'list', '--porcelain']);
+        if (wts.code !== 0)
+            return keep('git-failed', `${r.path}: ${wts.stderr.trim().slice(0, 200)}`, idleMs);
+        const external = parsePorcelainWorktrees(wts.stdout).find((w) => !w.isMain && !w.prunable && fs.existsSync(w.path) && !isPathInside(w.path, dir));
+        if (external)
+            return keep('has-external-worktrees', `${r.path} → ${external.path}`, idleMs);
+    }
+    return { ...base, decision: 'remove', reason: 'stale', idleMs };
+}
+/**
+ * One sweep over every session dir of every root. Never throws.
+ *
+ * @param input - Roots, busy cwds, clock, threshold, dry-run flag, git runner
+ * @returns Per-dir verdicts and totals
+ */
+export async function sweepScratch(input) {
+    const summary = {
+        roots: input.roots.map(canonicalPath),
+        removed: 0,
+        wouldRemove: 0,
+        kept: 0,
+        freedBytes: 0,
+        keptReasons: {},
+        sessions: [],
+    };
+    const sizeOf = input.sizeOf ?? diskUsageBytes;
+    for (const root of summary.roots) {
+        for (const dir of await listSessionDirs(root)) {
+            let v;
+            try {
+                v = await evaluateSessionDir(dir, input);
+            }
+            catch (err) {
+                v = { path: dir, decision: 'keep', reason: 'git-failed', detail: err instanceof Error ? err.message : String(err), repos: [], removed: false };
+            }
+            if (v.decision === 'remove' && !input.dryRun)
+                await removeSessionDir(root, v, sizeOf);
+            summary.sessions.push(v);
+            if (v.removed) {
+                summary.removed++;
+                summary.freedBytes += v.freedBytes ?? 0;
+            }
+            else if (input.dryRun && v.decision === 'remove')
+                summary.wouldRemove++;
+            else {
+                summary.kept++;
+                const key = v.error ? 'remove-failed' : v.reason;
+                summary.keptReasons[key] = (summary.keptReasons[key] ?? 0) + 1;
+            }
+        }
+    }
+    return summary;
+}
+/** Delete one session dir after re-checking it is a real dir inside its root. */
+async function removeSessionDir(root, v, sizeOf) {
+    try {
+        const st = await fs.promises.lstat(v.path);
+        if (!st.isDirectory() || st.isSymbolicLink() || !(await fs.promises.realpath(v.path)).startsWith(root + path.sep)) {
+            v.error = 'not a real directory inside the scratch root';
+            return;
+        }
+        const size = await sizeOf(v.path);
+        // fs.rm removes symlinks themselves, never their targets.
+        await fs.promises.rm(v.path, { recursive: true, force: true });
+        v.removed = true;
+        if (size !== null)
+            v.freedBytes = size;
+    }
+    catch (err) {
+        v.error = (err instanceof Error ? err.message : String(err)).slice(0, 300);
+    }
+}
+//# sourceMappingURL=scratch-janitor.js.map