@cleocode/contracts 2026.6.14 → 2026.6.17

package/src/branch-lock.ts

@@ -102,6 +102,10 @@ export interface WorktreeCleanupResult {
   removed: number;
   /** Paths that were removed. */
   removedPaths: string[];
+  /** Number of worktrees quarantined (dirty/unpushed — preserved, not deleted). */
+  quarantined: number;
+  /** Paths that were quarantined. */
+  quarantinedPaths: string[];
   /** Paths that failed to remove (with reasons). */
   errors: Array<{ path: string; reason: string }>;
 }

package/src/config.ts

@@ -751,6 +751,98 @@ export interface LeadRollupConfig {
   mode?: LeadRollupMode;
 }
 
+/**
+ * Daemon lifecycle configuration.
+ *
+ * Controls whether the postinstall hook is allowed to auto-enable and start
+ * the cleo-daemon service. When `autoStart` is `false`, postinstall NEVER
+ * enables or starts the service — even on a fresh install. This flag persists
+ * across upgrades so the operator's intent survives `npm install -g`.
+ *
+ * Configure via `~/.local/share/cleo/config.json` (global config):
+ * ```json
+ * { "daemon": { "autoStart": false } }
+ * ```
+ * Or via env var override: `CLEO_DAEMON_DISABLE=1` (per-session, non-persistent).
+ *
+ * @task T11984
+ */
+export interface DaemonConfig {
+  /**
+   * Whether the postinstall hook may auto-enable and start the cleo-daemon.
+   *
+   * - `true` (default): first install enables+starts; upgrade respects the
+   *   current systemd/launchd enabled state.
+   * - `false`: postinstall NEVER enables or starts the daemon. The unit file
+   *   is still written so the operator can activate later via
+   *   `cleo daemon enable`.
+   *
+   * @defaultValue true
+   */
+  autoStart: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Resources config (T11994 · PSI + MemAvailable sensing)
+// ---------------------------------------------------------------------------
+
+/**
+ * PSI pressure thresholds for the ResourceMonitor.
+ *
+ * Values are percentage points (0–100) for `avg10` exponential moving averages.
+ * Defaults sit far below systemd-oomd's Fedora kill line (80%/20s on
+ * user@1000.service).
+ *
+ * @task T11994
+ */
+export interface ResourcesPsiConfig {
+  /**
+   * Enter `hold` state when `some avg10` exceeds this value.
+   * @defaultValue 10
+   */
+  holdSomeAvg10?: number;
+  /**
+   * Enter `backoff` state when `some avg10` exceeds this value.
+   * @defaultValue 20
+   */
+  backoffSomeAvg10?: number;
+  /**
+   * Enter `hold` state when `full avg10` exceeds this value.
+   * @defaultValue 5
+   */
+  holdFullAvg10?: number;
+  /**
+   * Enter `backoff` state when `full avg10` exceeds this value.
+   * @defaultValue 10
+   */
+  backoffFullAvg10?: number;
+}
+
+/**
+ * Resource monitor configuration.
+ *
+ * Optional block — all fields have safe defaults. Maps to the
+ * `resources.*` config namespace (Amendment 5 · T11994).
+ *
+ * @task T11994
+ */
+export interface ResourcesConfig {
+  /**
+   * PSI pressure thresholds (percentage points).
+   *
+   * @defaultValue undefined (monitor uses built-in defaults)
+   */
+  psi?: ResourcesPsiConfig;
+  /**
+   * Minimum free memory headroom in MiB.
+   *
+   * Used in degraded mode (PSI absent) as the sole availability signal.
+   *
+   * @defaultValue 256
+   */
+  headroomMb?: number;
+}
+
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
   /** Configuration schema version string. */
@@ -838,6 +930,28 @@ export interface CleoConfig {
    * @saga T10377
    */
   leadRollup?: LeadRollupConfig;
+  /**
+   * Daemon lifecycle settings.
+   *
+   * When absent, defaults to `{ autoStart: true }` — matching the legacy
+   * install behaviour. Set `autoStart: false` to prevent postinstall from
+   * ever enabling or starting the cleo-daemon (persistent opt-out).
+   *
+   * @defaultValue undefined (treated as { autoStart: true })
+   * @task T11984
+   */
+  daemon?: DaemonConfig;
+  /**
+   * Resource monitor configuration — PSI pressure thresholds and memory
+   * headroom for the daemon-off governor and continuous supervisor mode.
+   *
+   * When absent, the ResourceMonitor uses built-in defaults which sit well
+   * below systemd-oomd's Fedora kill line (80%/20s on user@1000.service).
+   *
+   * @defaultValue undefined (ResourceMonitor uses built-in defaults)
+   * @task T11994
+   */
+  resources?: ResourcesConfig;
 }
 
 /**

package/src/dispatch/operations-registry.ts

@@ -9216,6 +9216,24 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
   },
 
+  // ── selfimprove query: probe (T11988 — seeded-code-regression scenario) ────────
+  // Pure read-only op that returns `{ probe: 'ok', version: probeVersion() }`.
+  // The `probe-helper.ts` intentionally ships with `probeVersion()` returning `2`
+  // (should be `1`) so the seeded-code-regression scenario replay diverges from its
+  // golden (`version: 1`) and gives the fix-gen LLM stage a real, patchable bug.
+  {
+    gateway: 'query',
+    domain: 'selfimprove',
+    operation: 'probe',
+    description:
+      'selfimprove.probe (query) — returns { probe: "ok", version: 1 } (health/version probe). Used by the seeded-code-regression scenario to validate the fix-gen pipeline (T11988).',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [] satisfies ParamDef[],
+  },
+
   // ── selfimprove mutate: run (T11889 / T11889-D — the self-dogfooding loop) ──
   // Boots ONE sandbox → replays the named canned scenario → diffs result
   // envelopes vs the golden → on a regression emits ONE leased `selfimprove_dhq`
@@ -9863,4 +9881,31 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  // T11995 — Janitor MVP: orphan process reaper + stale scope/lock/debris sweep
+  {
+    gateway: 'mutate',
+    domain: 'admin',
+    operation: 'janitor.run',
+    description:
+      'admin.janitor.run (mutate) — run the janitor sweep: reap orphan processes, stop dead cleo-owned scopes, reclaim stale locks, prune tmp debris',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Report planned actions without mutating anything.',
+      },
+      {
+        name: 'gracePeriodMs',
+        type: 'number',
+        required: false,
+        description:
+          'Minimum age (ms) of an unregistered process before reap eligibility (default: 600000).',
+      },
+    ] satisfies ParamDef[],
+  },
 ];

package/src/index.ts

@@ -261,6 +261,7 @@ export type {
   ClaudeSpawnMode,
   CleoConfig,
   ConfigSource,
+  DaemonConfig,
   DateFormat,
   DecisionsConfig,
   DepsRequiredAt,
@@ -285,6 +286,8 @@ export type {
   OutputFormat,
   ProviderConfig,
   ResolvedValue,
+  ResourcesConfig,
+  ResourcesPsiConfig,
   RoleName,
   SessionConfig,
   SessionSummaryInput,
@@ -2146,7 +2149,13 @@ export type {
   StatsSkillLifecycleState,
   StatsSkillSourceType,
 } from './skills/stats.js';
-export type { AdapterSpawnProvider, SpawnContext, SpawnResult } from './spawn.js';
+export type {
+  AdapterSpawnProvider,
+  AgentContainmentMode,
+  AgentSuiteOwnership,
+  SpawnContext,
+  SpawnResult,
+} from './spawn.js';
 // === CLEO Spawn Types (distinct from adapter spawn) ===
 export type {
   CAAMPSpawnOptions,

package/src/operations/llm.ts

@@ -255,6 +255,7 @@ export type ResolutionSource =
   | 'default'
   | 'default-profile'
   | 'registered-default'
+  | 'cross-provider'
   | 'implicit-fallback';
 
 /**

package/src/operations/worktree.ts

@@ -381,10 +381,20 @@ export interface PruneWorktreesResult {
   removed: number;
   /** Absolute paths that were removed. */
   removedPaths: string[];
+  /** Number of worktrees quarantined (dirty/unpushed — preserved, not deleted). */
+  quarantined: number;
+  /** Absolute paths of quarantined worktrees. */
+  quarantinedPaths: string[];
   /** Entries that failed to remove (with reasons). */
   errors: Array<{ path: string; reason: string }>;
   /** Whether `git worktree prune` was run. */
   gitPruneRan: boolean;
+  /**
+   * True when pruning was skipped entirely because the preserve set was empty
+   * or the task store was unreadable while worktrees exist (fail-closed guard,
+   * T11996). A structured audit warning is written to the lifecycle log.
+   */
+  skippedFailClosed?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -576,6 +586,7 @@ export type WorktreeLifecycleAction =
   | 'adopt'
   | 'prune'
   | 'prune-skip'
+  | 'quarantine'
   | 'force-unlock'
   | 'complete'
   | 'complete-skip'

package/src/spawn.ts

@@ -4,8 +4,79 @@
  * @task T5240
  * @task T9214 — orchestrator-defer waiver field (W4 UX hardening)
  * @task T9215 — DelegateTaskEnvelope discriminated-union type (W1 wiring)
+ * @task T11998 — per-session suite containment (AgentSuiteOwnership)
  */
 
+// =============================================================================
+// Agent suite ownership handle (T11998 — suite containment)
+// =============================================================================
+
+/**
+ * Containment mode used when spawning an agent process tree.
+ *
+ * - `'systemd'` — the agent and its MCP children run inside a transient
+ *   `systemd --user` scope unit.  The scope is the kill handle.
+ * - `'pgid'` — the agent runs in its own POSIX process group.  Negative-PID
+ *   kill (`kill(-pgid, SIGTERM)`) reaps the whole group.
+ * - `'none'` — no containment (detached+unref legacy path).  The janitor
+ *   (T11995) is the only backstop.
+ */
+export type AgentContainmentMode = 'systemd' | 'pgid' | 'none';
+
+/**
+ * Ownership/cleanup handle recorded per spawned agent session.
+ *
+ * This record is stored alongside the {@link SpawnResult} so that
+ * `terminate()` and session-end flows can reap the entire process tree
+ * (including indirectly-spawned MCP grandchildren) via a single kill.
+ *
+ * ## Systemd path
+ * `systemctl --user stop <unitName>` stops the scope and all processes
+ * inside it.  If the scope has already exited, use `reset-failed` to clear
+ * the failed-unit ledger; ESRCH / no-such-unit errors are no-ops.
+ *
+ * ## Pgid path
+ * `process.kill(-pgid, 'SIGTERM')` sends SIGTERM to every process in the
+ * group.  After a grace period, `process.kill(-pgid, 'SIGKILL')` cleans
+ * up survivors.  ESRCH is a no-op (group already gone).
+ *
+ * @task T11998
+ */
+export interface AgentSuiteOwnership {
+  /**
+   * Containment mode in effect for this agent spawn.
+   *
+   * Determines which reap primitive to use on session end.
+   */
+  readonly mode: AgentContainmentMode;
+
+  /**
+   * Systemd transient scope unit name (e.g. `cleo-agent-session-T1234.scope`).
+   *
+   * Present only when `mode === 'systemd'`.  Use as the argument to
+   * `systemctl --user stop <unitName>`.
+   */
+  readonly unitName?: string;
+
+  /**
+   * POSIX process-group ID of the spawned agent root process.
+   *
+   * Present only when `mode === 'pgid'`.  Use as negative-PID with kill:
+   * `process.kill(-pgid, 'SIGTERM')`.
+   *
+   * When `mode === 'systemd'` the pgid is also populated as a fallback
+   * handle (e.g. if the scope unit is unavailable at reap time).
+   */
+  readonly pgid?: number;
+
+  /**
+   * PID of the direct child process spawned by cleo.
+   *
+   * Informational — prefer `unitName` or `pgid` for reaping.
+   */
+  readonly pid?: number;
+}
+
 export interface AdapterSpawnProvider {
   canSpawn(): Promise<boolean>;
   spawn(context: SpawnContext): Promise<SpawnResult>;
@@ -48,6 +119,14 @@ export interface SpawnResult {
   endTime?: string;
   /** Error message when status is 'failed'. Contains details about what went wrong. */
   error?: string;
+  /**
+   * Suite containment ownership handle (T11998).
+   *
+   * Present when the spawn provider recorded containment info.
+   * Use this to reap the entire MCP suite tree on session end or terminate().
+   * Absent for legacy spawns that used detached+unref without containment.
+   */
+  ownership?: AgentSuiteOwnership;
 }
 
 // =============================================================================