@cleocode/core 2026.6.15 → 2026.6.18

package/dist/gc/janitor.d.ts

@@ -0,0 +1,149 @@
+/**
+ * CLEO Janitor — orphan process reaper + stale scope/lock/debris sweep.
+ *
+ * Composable engine that the GC subsystem and the `cleo janitor run` CLI verb
+ * call.  Every action is:
+ *   - Silent: no console output; one JSONL line per action appended to
+ *     `.cleo/audit/janitor.jsonl`, plus counts in the returned result.
+ *   - Idempotent: a fully-converged state produces zero actions on re-run.
+ *   - Dry-run capable: `dryRun: true` reports planned actions without mutating
+ *     anything.
+ *
+ * ## Categories
+ *
+ * | # | Category                 | Description                                          |
+ * |---|--------------------------|------------------------------------------------------|
+ * | 1 | `reaped`                 | Leaked MCP/agent helpers (registration-primary)      |
+ * | 2 | `scopesStopped`          | Cleo-owned systemd transient scopes that exited      |
+ * | 3 | `locksReclaimed`         | Sentient/GC lock files held by dead PIDs             |
+ * | 4 | `semaphoreSlotsCleared`  | Tool-semaphore slot dirs held past staleMs           |
+ * | 5 | `worktreesPruned`        | Orphan worktree directories                          |
+ * | 6 | `worktreesQuarantined`   | Dirty/unpushed worktrees quarantined                 |
+ * | 7 | `tmpRemoved`             | Stale CLEO temp directories                          |
+ * | 8 | `attachmentsRepaired`    | Attachment rows/files repaired                       |
+ * | 9 | `configsRepaired`        | Corrupt config files restored                        |
+ *
+ * ## Amendment compliance
+ *
+ * - **Amendment 1 (registration-primary)**: orphan detection uses cleo-owned
+ *   scope/pgid as PRIMARY discriminator; signature+age only for UNREGISTERED
+ *   processes when all stdio pipe peers are dead.
+ * - **Amendment 2 (regression)**: reparented double-fork of a LIVE session is
+ *   preserved; same of a DEAD session is reaped.
+ * - **Amendment 3 (scope reaping)**: restricted to units starting with
+ *   `cleo-` prefix inside `cleo.slice`.  Never touches `run-*.scope`.
+ * - **Amendment 4 (idempotency)**: TERM→KILL escalation spanning runs is
+ *   legitimate; a fully-converged state produces zero actions on second run.
+ * - **Amendment 5 (liveness probe)**: stale locks reclaimed only after
+ *   verifying the holder PID is dead — never on mtime alone.
+ * - **Amendment 6 (silence)**: every action → `.cleo/audit/janitor.jsonl`;
+ *   zero desktop notifications; zero console noise in non-verbose mode.
+ * - **Amendment 7 (tmp debris)**: reuses `gc/cleanup.ts` patterns directly.
+ *
+ * @module @cleocode/core/gc/janitor
+ * @task T11995
+ * @epic T11992
+ */
+/**
+ * Default minimum age (ms) of an unregistered process before reap eligibility.
+ * 10 minutes gives a freshly-spawned MCP server time to register.
+ */
+export declare const DEFAULT_GRACE_MS: number;
+/**
+ * Default SIGTERM→SIGKILL grace period (ms).
+ * Matches suite-reaper.ts value for consistency.
+ */
+export declare const SIGTERM_GRACE_MS = 3000;
+/**
+ * Default stale-ms for tool-semaphore slot lock directories.
+ * Matches tool-semaphore.ts default.
+ */
+export declare const DEFAULT_SEMAPHORE_STALE_MS = 600000;
+/** Per-category result counts returned by {@link runJanitor}. */
+export interface JanitorResult {
+    /** Orphan agent/MCP processes sent SIGTERM or SIGKILL. */
+    readonly reaped: number;
+    /** Cleo-owned transient scopes stopped + reset-failed. */
+    readonly scopesStopped: number;
+    /** Stale PID lock files reclaimed (sentient, gc). */
+    readonly locksReclaimed: number;
+    /** Stale tool-semaphore slot directories cleared. */
+    readonly semaphoreSlotsCleared: number;
+    /** Orphan worktree directories removed. */
+    readonly worktreesPruned: number;
+    /** Dirty/unpushed worktrees quarantined (not deleted). */
+    readonly worktreesQuarantined: number;
+    /** Stale CLEO tmp dirs removed. */
+    readonly tmpRemoved: number;
+    /** Attachment orphans marked or deleted. */
+    readonly attachmentsRepaired: number;
+    /** Corrupt config files restored from backup. */
+    readonly configsRepaired: number;
+    /** Total non-fatal errors encountered. */
+    readonly errors: number;
+    /** True when `dryRun: true` was set — no mutations were performed. */
+    readonly dryRun: boolean;
+}
+/** Options for {@link runJanitor}. */
+export interface JanitorOptions {
+    /**
+     * When true, report planned actions without performing any mutations.
+     * @default false
+     */
+    dryRun?: boolean;
+    /**
+     * Minimum age (ms) of an unregistered process before reap eligibility.
+     * @default DEFAULT_GRACE_MS (10 min)
+     */
+    gracePeriodMs?: number;
+    /**
+     * Absolute path to the project-level `.cleo/` directory.
+     * Defaults to `resolveCleoDir()` using the current working directory.
+     */
+    cleoDir?: string;
+    /**
+     * Root of the CLEO worktrees hierarchy.
+     * Defaults to `~/.local/share/cleo/worktrees/`.
+     */
+    worktreesRoot?: string;
+    /**
+     * Set of active (non-terminal) task IDs for the worktree prune guard.
+     * When `undefined`, worktree pruning is skipped entirely.
+     */
+    activeTaskIds?: Set<string>;
+    /**
+     * Selectively skip categories.  Omit or set `false` to run all.
+     */
+    skip?: {
+        processes?: boolean;
+        scopes?: boolean;
+        locks?: boolean;
+        semaphores?: boolean;
+        worktrees?: boolean;
+        tmp?: boolean;
+        attachments?: boolean;
+        config?: boolean;
+    };
+}
+/**
+ * Check whether a PID is alive via `kill(pid, 0)`.
+ * Returns `false` for ESRCH or any other error.
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Run the CLEO janitor sweep.
+ *
+ * Runs all enabled categories and returns a structured result with per-category
+ * counts.  Designed to be called from:
+ *   - `cleo janitor run [--dry-run]` (manual verb)
+ *   - GC subsystem sentient tick (daemon mode)
+ *   - Session start/end (daemon-off lazy mode)
+ *
+ * @param opts - Janitor options.
+ * @returns Structured result.
+ *
+ * @task T11995
+ * @epic T11992
+ */
+export declare function runJanitor(opts?: JanitorOptions): Promise<JanitorResult>;
+//# sourceMappingURL=janitor.d.ts.map

package/dist/gc/janitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"janitor.d.ts","sourceRoot":"","sources":["../../src/gc/janitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAwBH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAsClD,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE5B;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAoCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAgeD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CA4NlF"}