@cleocode/adapters 2026.6.14 → 2026.6.17

package/src/providers/claude-code/spawn.ts

@@ -5,17 +5,26 @@
  * Migrated from src/core/spawn/adapters/claude-code-adapter.ts
  *
  * Uses the native `claude` CLI to spawn subagent processes with prompts
- * written to temporary files. Processes run detached and are tracked
- * by PID for listing and termination.
+ * written to temporary files. Processes run in per-session containment
+ * (systemd transient scope on Linux, or setsid process group as fallback)
+ * so that session end reaps the entire MCP suite tree.
  *
  * @task T5240
+ * @task T11998 — per-session scope/pgid suite containment
  */
 
 import { exec, spawn as nodeSpawn } from 'node:child_process';
 import { unlink, writeFile } from 'node:fs/promises';
 import { promisify } from 'node:util';
-import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import type {
+  AdapterSpawnProvider,
+  AgentSuiteOwnership,
+  SpawnContext,
+  SpawnResult,
+} from '@cleocode/contracts';
 import { getErrorMessage } from '@cleocode/contracts';
+import { buildAgentSpawnArgs } from '../shared/agent-spawn-wrapper.js';
+import { reapAgentSuite } from './suite-reaper.js';
 
 const execAsync = promisify(exec);
 
@@ -24,6 +33,8 @@ interface TrackedProcess {
   pid: number;
   taskId: string;
   startTime: string;
+  /** Suite containment handle — used by terminate() and session-end reap (T11998). */
+  ownership: AgentSuiteOwnership;
 }
 
 /**
@@ -98,15 +109,27 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
       // --print: non-interactive batch mode (process prompt, output response, exit)
       // --dangerously-skip-permissions: allow all tool calls without human approval
       // --output-format json: structured output for parsing
-      const args = [
+      const claudeArgs = [
         '--print',
         '--dangerously-skip-permissions',
         '--output-format',
         'json',
         tmpFile,
       ];
+
+      // T11998: Build the argv with per-session containment.
+      // On Linux with systemd, this wraps 'claude' inside a transient
+      // cleo.slice scope (systemd-run --user --scope ...).
+      // On non-Linux or without systemd, falls back to pgid (detached+setsid).
+      // The ownership handle records the scope unit name or pgid for reaping.
+      const spawnBuild = buildAgentSpawnArgs('claude', claudeArgs, instanceId);
+
+      // For the systemd path: the child of systemd-run is NOT detached (systemd
+      // manages the scope lifecycle).  For the pgid path: we use detached:true
+      // so Node creates a new session, giving us a fresh pgid to kill the group.
+      const isSystemd = spawnBuild.ownership.mode === 'systemd';
       const spawnOpts: Parameters<typeof nodeSpawn>[2] = {
-        detached: true,
+        detached: !isSystemd,
         stdio: ['ignore', 'pipe', 'pipe'],
       };
 
@@ -126,14 +149,28 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
         spawnOpts.env = { ...process.env, ...optionsEnv };
       }
 
-      const child = nodeSpawn('claude', args, spawnOpts);
+      const child = nodeSpawn(spawnBuild.command, spawnBuild.args, spawnOpts);
+      // unref() so the parent process can exit without waiting for the child.
+      // The containment scope/pgid ensures the child tree can still be reaped.
       child.unref();
 
+      // Resolve the ownership handle: for the pgid path the pgid is the same
+      // as the pid when detached:true (Node sets the child as the group leader).
+      const ownership: AgentSuiteOwnership = {
+        ...spawnBuild.ownership,
+        pid: child.pid,
+        pgid:
+          spawnBuild.ownership.mode === 'pgid' && child.pid !== undefined
+            ? child.pid
+            : spawnBuild.ownership.pgid,
+      };
+
       if (child.pid) {
         this.processMap.set(instanceId, {
           pid: child.pid,
           taskId: context.taskId,
           startTime,
+          ownership,
         });
       }
 
@@ -153,6 +190,9 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
         providerId: 'claude-code',
         status: 'running',
         startTime,
+        // T11998: surface the ownership handle in the result so callers can
+        // persist it or pass it to reapAgentSuite on session end.
+        ownership,
       };
     } catch (error) {
       // Log spawn failure for debugging
@@ -198,6 +238,8 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
           providerId: 'claude-code',
           status: 'running',
           startTime: tracked.startTime,
+          // T11998: propagate ownership handle so callers can reap the suite.
+          ownership: tracked.ownership,
         });
       } catch {
         this.processMap.delete(instanceId);
@@ -210,20 +252,45 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
   /**
    * Terminate a running spawn by instance ID.
    *
-   * Sends SIGTERM to the tracked process. If the process is not found
-   * or has already exited, this is a no-op.
+   * Uses the suite-reaper to kill the entire process tree (root claude CLI +
+   * all MCP grandchildren) via the containment handle recorded at spawn time.
+   * Falls back to a direct SIGTERM on the tracked PID for legacy entries
+   * that pre-date T11998 and lack an ownership handle.
+   *
+   * Idempotent: no-op if the instance is not found or has already exited.
    *
    * @param instanceId - ID of the spawn instance to terminate
+   * @task T11998
    */
   async terminate(instanceId: string): Promise<void> {
     const tracked = this.processMap.get(instanceId);
     if (!tracked) return;
 
+    this.processMap.delete(instanceId);
+
     try {
-      process.kill(tracked.pid, 'SIGTERM');
+      // T11998: reap the entire suite tree via the containment handle.
+      await reapAgentSuite(tracked.ownership);
     } catch {
-      // Process may have already exited
+      // Best-effort: fall back to direct SIGTERM on the root pid.
+      try {
+        process.kill(tracked.pid, 'SIGTERM');
+      } catch {
+        // Process may have already exited — no-op.
+      }
     }
-    this.processMap.delete(instanceId);
+  }
+
+  /**
+   * Terminate all tracked spawn instances on session end.
+   *
+   * Called by the session lifecycle when a CLEO session ends, ensuring
+   * no orphaned agent suites (root process + MCP children) remain.
+   *
+   * @task T11998
+   */
+  async terminateAll(): Promise<void> {
+    const instanceIds = [...this.processMap.keys()];
+    await Promise.allSettled(instanceIds.map((id) => this.terminate(id)));
   }
 }

package/src/providers/claude-code/suite-reaper.ts

@@ -0,0 +1,210 @@
+/**
+ * Agent suite reaper — session-end cleanup for the per-session containment epic (T11998).
+ *
+ * Provides a single {@link reapAgentSuite} function that kills an agent's
+ * entire process tree (including indirectly-spawned MCP grandchildren) using
+ * whatever containment handle was recorded at spawn time.
+ *
+ * ## Reap strategy
+ *
+ * | mode     | primary kill                          | fallback                  |
+ * |----------|---------------------------------------|---------------------------|
+ * | systemd  | `systemctl --user stop <unitName>`    | negative-pgid SIGKILL     |
+ * | pgid     | `kill(-pgid, SIGTERM)` → grace → KILL | none (best-effort)        |
+ * | none     | no-op (janitor T11995 is backstop)    | —                         |
+ *
+ * All operations are idempotent: ESRCH, no-such-unit, and already-stopped
+ * conditions are treated as success (no-op).
+ *
+ * @module suite-reaper
+ * @task T11998
+ * @epic T11992
+ */
+
+import { spawnSync } from 'node:child_process';
+import type { AgentSuiteOwnership } from '@cleocode/contracts';
+
+/**
+ * Grace period in milliseconds between SIGTERM and SIGKILL in the pgid path.
+ *
+ * 3 s is sufficient for graceful MCP server shutdown and avoids the risk
+ * of SIGKILL mid-write.
+ */
+const SIGTERM_GRACE_MS = 3_000;
+
+/**
+ * Reap an agent process suite.
+ *
+ * Stops the entire tree of processes associated with a spawned agent session:
+ * the root claude CLI process AND all MCP children that reparented under it.
+ *
+ * This function is called on:
+ *   - Normal session end (user runs `cleo session end`)
+ *   - `terminate(instanceId)` on the spawn provider
+ *   - Watchdog-declared death (future T11995 janitor call-back)
+ *
+ * @param ownership - The containment handle recorded at spawn time.
+ * @returns A promise that resolves when the reap attempt is complete.
+ *
+ * @task T11998
+ */
+export async function reapAgentSuite(ownership: AgentSuiteOwnership): Promise<void> {
+  switch (ownership.mode) {
+    case 'systemd':
+      await reapSystemdScope(ownership);
+      break;
+    case 'pgid':
+      await reapPgidGroup(ownership);
+      break;
+    case 'none':
+      // No containment recorded — the janitor (T11995) is the sole backstop.
+      // Log at debug level for observability but do not throw.
+      process.stderr.write(
+        '[cleo:suite-reaper] containment mode=none — no reap performed; ' +
+          'janitor (T11995) is the backstop\n',
+      );
+      break;
+    default: {
+      // Exhaustiveness guard — should never be reached.
+      const _exhaustive: never = ownership.mode;
+      void _exhaustive;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Systemd path
+// ---------------------------------------------------------------------------
+
+/**
+ * Stop a transient systemd scope and reset its failed-unit state.
+ *
+ * 1. `systemctl --user stop <unitName>` — graceful scope stop.
+ * 2. `systemctl --user reset-failed <unitName>` — clear the failed ledger
+ *    if the scope exited non-zero (idempotent, best-effort).
+ * 3. pgid fallback if systemctl is unavailable or the stop failed.
+ *
+ * @internal
+ */
+async function reapSystemdScope(ownership: AgentSuiteOwnership): Promise<void> {
+  const { unitName, pgid } = ownership;
+
+  if (unitName) {
+    const stopResult = spawnSync('systemctl', ['--user', 'stop', unitName], {
+      stdio: 'ignore',
+      timeout: 10_000,
+    });
+
+    if (stopResult.error) {
+      // systemctl not available — fall through to pgid.
+      process.stderr.write(
+        `[cleo:suite-reaper] systemctl stop failed (${stopResult.error.message}); ` +
+          'falling back to pgid kill\n',
+      );
+    } else if (stopResult.status !== 0) {
+      // Non-zero exit may mean "unit not found" (already gone) or "not started".
+      // Both are acceptable outcomes — unit is gone either way.
+      // Attempt reset-failed to clear the ledger, then check pgid.
+      spawnSync('systemctl', ['--user', 'reset-failed', unitName], {
+        stdio: 'ignore',
+        timeout: 5_000,
+      });
+      // If there is a pgid handle, kill any survivors the scope may have missed.
+      if (pgid !== undefined) {
+        await killPgidGracefully(pgid);
+      }
+      return;
+    } else {
+      // Successful stop — also try reset-failed to keep the ledger clean.
+      spawnSync('systemctl', ['--user', 'reset-failed', unitName], {
+        stdio: 'ignore',
+        timeout: 5_000,
+      });
+      // A successful scope stop reaps all cgroup members; pgid kill is not needed.
+      return;
+    }
+  }
+
+  // Fallback: pgid kill when unit name is absent or systemctl failed.
+  if (pgid !== undefined) {
+    await killPgidGracefully(pgid);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pgid path
+// ---------------------------------------------------------------------------
+
+/**
+ * Kill a POSIX process group: SIGTERM → grace period → SIGKILL.
+ *
+ * Sends SIGTERM to the whole group (negative PID = group leader + all
+ * members).  After {@link SIGTERM_GRACE_MS}, checks for survivors and
+ * sends SIGKILL if any remain.
+ *
+ * ESRCH errors (no such process / already gone) are treated as success.
+ *
+ * @internal
+ */
+async function reapPgidGroup(ownership: AgentSuiteOwnership): Promise<void> {
+  const { pgid } = ownership;
+  if (pgid === undefined) return;
+  await killPgidGracefully(pgid);
+}
+
+/**
+ * Send SIGTERM to a process group, wait for grace period, then SIGKILL survivors.
+ *
+ * @param pgid - Positive process-group ID.
+ * @internal
+ */
+async function killPgidGracefully(pgid: number): Promise<void> {
+  // Step 1: SIGTERM
+  try {
+    process.kill(-pgid, 'SIGTERM');
+  } catch (err) {
+    // ESRCH = group already gone — treat as success.
+    if (isEsrch(err)) return;
+    // Other errors: log and proceed to SIGKILL attempt.
+    process.stderr.write(`[cleo:suite-reaper] SIGTERM to pgid=${pgid} failed: ${String(err)}\n`);
+  }
+
+  // Step 2: Grace period — give MCP servers time to flush and exit.
+  await sleep(SIGTERM_GRACE_MS);
+
+  // Step 3: SIGKILL survivors.
+  try {
+    process.kill(-pgid, 'SIGKILL');
+  } catch (err) {
+    // ESRCH after grace = all processes exited cleanly — ideal outcome.
+    if (isEsrch(err)) return;
+    process.stderr.write(`[cleo:suite-reaper] SIGKILL to pgid=${pgid} failed: ${String(err)}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if an error is ESRCH (no such process).
+ *
+ * @internal
+ */
+function isEsrch(err: unknown): boolean {
+  if (typeof err === 'object' && err !== null) {
+    const code = (err as Record<string, unknown>)['code'];
+    return code === 'ESRCH';
+  }
+  return false;
+}
+
+/**
+ * Promise-based sleep.
+ *
+ * @param ms - Duration in milliseconds.
+ * @internal
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/providers/shared/agent-spawn-wrapper.ts

@@ -0,0 +1,222 @@
+/**
+ * Adapter-local spawn-args builder for per-session suite containment (T11998).
+ *
+ * This module provides a self-contained copy of the systemd-run argv builder
+ * for use inside `packages/adapters/`, which cannot import from
+ * `packages/core/` (that would create a circular dependency since core depends
+ * on adapters).
+ *
+ * ## Relationship to `packages/core/src/resources/spawn-wrapper.ts`
+ *
+ * The canonical SSoT for systemd-run argv construction is in core (T11993).
+ * This module is a DELIBERATE LOCAL COPY scoped to the adapter layer, kept
+ * in sync by the skill-drift gate.  It follows the same design decisions:
+ *   - `cleo.slice` placement
+ *   - `MemoryMax=32G` hard cap (P1 staged value)
+ *   - `MemorySwapMax=0`
+ *   - Selective `ManagedOOMPreference=avoid` (daemon/db only)
+ *   - Core suppression via `ulimit -c 0` (NOT LimitCORE=0 — invalid on scopes)
+ *   - `_forceSystemdRunAvailable()` test hook
+ *
+ * When the core SSoT changes, update this file in the same PR.
+ *
+ * ## Why a copy?
+ *
+ * The dependency direction is `core → adapters`.  Adding `core` to adapters'
+ * deps would create a cycle.  Extracting to a third package is a separate
+ * refactor task; for P1 the local copy is the right trade-off.
+ *
+ * @module agent-spawn-wrapper
+ * @task T11998
+ * @epic T11992
+ * @see packages/core/src/resources/spawn-wrapper.ts (canonical SSoT)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import type { AgentContainmentMode, AgentSuiteOwnership } from '@cleocode/contracts';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** The systemd user slice that all cleo agent scope sessions are placed under. */
+export const CLEO_SLICE = 'cleo.slice' as const;
+
+/** Default MemoryMax for agent scopes (P1 staged value). */
+const DEFAULT_MEMORY_MAX = '32G' as const;
+
+// ---------------------------------------------------------------------------
+// Availability probe
+// ---------------------------------------------------------------------------
+
+/** Cached result of the systemd-run probe. */
+let _systemdRunAvailable: boolean | undefined;
+
+/** Whether the pgid-demotion log line has been emitted for this process. */
+let _demotionLogged = false;
+
+/** Counter for unique scope discriminators within this process. */
+let _scopeCounter = 0;
+
+/**
+ * Check whether `systemd-run --user` is usable on this host.
+ *
+ * Returns `false` on non-Linux, when systemd-run is absent, or when
+ * DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR are absent.
+ */
+function hasSystemdRun(): boolean {
+  if (_systemdRunAvailable !== undefined) return _systemdRunAvailable;
+  if (process.platform !== 'linux') {
+    _systemdRunAvailable = false;
+    return false;
+  }
+  const probe = spawnSync('systemd-run', ['--version'], { stdio: 'ignore' });
+  _systemdRunAvailable = probe.status === 0;
+  return _systemdRunAvailable;
+}
+
+/**
+ * Force the cached systemd-run availability for tests.
+ *
+ * @param available - `true` = systemd path, `false` = pgid fallback.
+ */
+export function _forceSystemdRunAvailable(available: boolean): void {
+  _systemdRunAvailable = available;
+}
+
+// ---------------------------------------------------------------------------
+// Memory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read /proc/meminfo MemTotal in bytes.  Returns 32 GiB as a safe fallback.
+ */
+function readMemTotalBytes(): number {
+  if (process.platform !== 'linux') return 32 * 1024 * 1024 * 1024;
+  try {
+    const raw = readFileSync('/proc/meminfo', 'utf8');
+    const m = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
+    if (m?.[1]) return parseInt(m[1], 10) * 1024;
+  } catch {
+    // ignore
+  }
+  return 32 * 1024 * 1024 * 1024;
+}
+
+// ---------------------------------------------------------------------------
+// Build result
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of building the spawn argv for an agent session.
+ *
+ * Carries both the launch command/args AND the ownership handle that must
+ * be persisted in the tracking record for use by {@link reapAgentSuite}.
+ */
+export interface AgentSpawnArgs {
+  /** Command to execute (e.g. `'systemd-run'` or `'sh'` or the real binary). */
+  command: string;
+  /** Full argument list. */
+  args: string[];
+  /**
+   * Ownership handle to persist in the session tracking record.
+   *
+   * Pass this to {@link reapAgentSuite} on session end.
+   */
+  ownership: AgentSuiteOwnership;
+}
+
+// ---------------------------------------------------------------------------
+// Main API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the argv for spawning a claude agent session with containment.
+ *
+ * When systemd is available the agent is placed in a transient scope under
+ * `cleo.slice`.  Otherwise it falls back to a setsid process-group spawn
+ * (the caller is responsible for passing `{ detached: true }` to
+ * `child_process.spawn` so a new pgid is created).
+ *
+ * Core suppression is applied via `ulimit -c 0` (NOT `LimitCORE=0` — that is
+ * a service-unit EXEC property and is rejected by `systemd-run --scope`).
+ *
+ * @param command - The executable to run (e.g. `'claude'`).
+ * @param args - Arguments for the executable.
+ * @param scopeId - Optional discriminator appended to the unit name (e.g. a
+ *   task ID or instance ID) so concurrent sessions are addressable.
+ * @returns Build result with spawn command/args and the ownership handle.
+ */
+export function buildAgentSpawnArgs(
+  command: string,
+  args: readonly string[],
+  scopeId?: string,
+): AgentSpawnArgs {
+  if (!hasSystemdRun()) {
+    if (!_demotionLogged) {
+      _demotionLogged = true;
+      process.stderr.write(
+        '[cleo:agent-spawn-wrapper] systemd-run unavailable — ' +
+          'falling back to plain pgid (detached) spawn; no cgroup containment\n',
+      );
+    }
+
+    // pgid fallback: wrap with ulimit -c 0 for core suppression.
+    // The caller MUST pass { detached: true } to spawn() so that Node creates
+    // a new session+pgid for this child.
+    return {
+      command: 'sh',
+      args: ['-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args],
+      ownership: {
+        mode: 'pgid' as AgentContainmentMode,
+        // pgid is populated after spawn; the caller patches it via the
+        // returned child.pid (which is the pgid leader when detached: true).
+      },
+    };
+  }
+
+  // Systemd path: build a transient scope under cleo.slice.
+  const totalBytes = readMemTotalBytes();
+  const maxStr = DEFAULT_MEMORY_MAX; // P1: absolute string, no fraction logic needed
+
+  const counter = ++_scopeCounter;
+  const discriminator = scopeId
+    ? scopeId.replace(/[^a-zA-Z0-9-]/g, '-').slice(0, 40)
+    : String(counter);
+  const unitName = `cleo-agent-session-${discriminator}.scope`;
+
+  // Resolve MemoryMax fraction if needed (P1 uses absolute string, so passthrough).
+  void totalBytes; // suppress unused-var for future fraction support
+
+  const wrapArgs: string[] = [
+    '--user',
+    '--scope',
+    `--slice=${CLEO_SLICE}`,
+    `--unit=${unitName}`,
+    '-p',
+    `MemoryMax=${maxStr}`,
+    '-p',
+    'MemorySwapMax=0',
+    // NOTE: ManagedOOMPreference=avoid is NOT set for agent sessions —
+    // only daemon/db scope classes (write-txn holders) get 'avoid'.
+    // See spawn-wrapper.ts OOM_AVOID_CLASSES and the module TSDoc for rationale.
+    '--',
+    'sh',
+    '-c',
+    'ulimit -c 0; exec "$@"',
+    'sh',
+    command,
+    ...args,
+  ];
+
+  return {
+    command: 'systemd-run',
+    args: wrapArgs,
+    ownership: {
+      mode: 'systemd' as AgentContainmentMode,
+      unitName,
+      // pgid is populated after spawn; caller patches via child.pid.
+    },
+  };
+}