feat(core): add named cgroup unit attach and managed child-run superv…

…isor
wenshao · Oct 6, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026
commit 0c1425926eff15fdba8e67ac1274957dcd4b233f
@@ -9,7 +9,10 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { HookCommandCgroup } from './hook-command-cgroup.js';
+import {
+  HookCommandCgroup,
+  HookCommandIsolationUnavailableError,
+} from './hook-command-cgroup.js';
 
 let directory: string;
 beforeEach(async () => {
@@ -19,6 +22,23 @@ afterEach(async () => {
   await rm(directory, { recursive: true, force: true });
 });
 
+describe('unit creation and attachment', () => {
+  it('refuses to create or attach without a delegated Linux root', () => {
+    expect(() => HookCommandCgroup.create(undefined)).toThrow(
+      HookCommandIsolationUnavailableError,
+    );
+    expect(() =>
+      HookCommandCgroup.create(join(directory, 'not-a-cgroup')),
+    ).toThrow(HookCommandIsolationUnavailableError);
+    expect(() =>
+      HookCommandCgroup.create(join(directory, 'not-a-cgroup'), 'qwen-bg-1'),
+    ).toThrow(HookCommandIsolationUnavailableError);
+    expect(() =>
+      HookCommandCgroup.attach(join(directory, 'not-a-cgroup'), 'qwen-bg-1'),
+    ).toThrow(HookCommandIsolationUnavailableError);
+  });
+});
+
 describe('managed command launcher environment', () => {
   it('keeps environment values out of argv and applies them only after membership', async () => {
     const preload = join(directory, 'preload.cjs');

@@ -48,20 +48,28 @@ child.on('exit', (code) => process.exit(code ?? 1));
 export class HookCommandCgroup {
   private constructor(readonly directory: string) {}
 
-  static create(root: string | undefined): HookCommandCgroup {
+  private static resolveRoot(root: string | undefined): string {
+    if (process.platform !== 'linux' || !root || !isAbsolute(root))
+      throw new HookCommandIsolationUnavailableError();
+    const resolved = realpathSync(root);
+    if (statfsSync(resolved).type !== 0x63677270)
+      throw new HookCommandIsolationUnavailableError();
+    if (readFileSync(join(resolved, 'cgroup.type'), 'utf8').trim() !== 'domain')
+      throw new HookCommandIsolationUnavailableError();
+    return resolved;
+  }
+
+  static create(
+    root: string | undefined,
+    unitName?: string,
+  ): HookCommandCgroup {
     let directory: string | undefined;
+    let created = false;
     try {
-      if (process.platform !== 'linux' || !root || !isAbsolute(root))
-        throw new HookCommandIsolationUnavailableError();
-      const resolved = realpathSync(root);
-      if (statfsSync(resolved).type !== 0x63677270)
-        throw new HookCommandIsolationUnavailableError();
-      if (
-        readFileSync(join(resolved, 'cgroup.type'), 'utf8').trim() !== 'domain'
-      )
-        throw new HookCommandIsolationUnavailableError();
-      directory = join(resolved, `qwen-hook-${randomUUID()}`);
+      const resolved = HookCommandCgroup.resolveRoot(root);
+      directory = join(resolved, unitName ?? `qwen-hook-${randomUUID()}`);
       mkdirSync(directory, { mode: 0o700 });
+      created = true;
       const unit = new HookCommandCgroup(directory);
       if (!unit.empty()) throw new HookCommandIsolationUnavailableError();
       for (const file of ['cgroup.procs', 'cgroup.kill']) {
@@ -70,7 +78,9 @@ export class HookCommandCgroup {
       }
       return unit;
     } catch {
-      if (directory) {
+      // Only a unit this call created may be removed: a named unit that
+      // already exists belongs to whoever made it, never to us.
+      if (created && directory) {
         try {
           rmdirSync(directory);
         } catch {
@@ -81,6 +91,29 @@ export class HookCommandCgroup {
     }
   }
 
+  /**
+   * Opens a unit somebody else created, for a worker that (re)attaches a
+   * supervised process after a replacement. A missing unit answers
+   * `undefined`; an unusable root answers the isolation error, never a guess.
+   */
+  static attach(
+    root: string | undefined,
+    unitName: string,
+  ): HookCommandCgroup | undefined {
+    const resolved = HookCommandCgroup.resolveRoot(root);
+    if (unitName.includes('/') || unitName.includes('')) return undefined;
+    let directory: string;
+    try {
+      directory = realpathSync(join(resolved, unitName));
+      if (!directory.startsWith(resolved + '/')) return undefined;
+      if (statfsSync(directory).type !== 0x63677270) return undefined;
+      readFileSync(join(directory, 'cgroup.events'), 'utf8');
+    } catch {
+      return undefined;
+    }
+    return Reflect.construct(HookCommandCgroup, [directory]);
+  }
+
   launch(executable: string, args: string[], env: NodeJS.ProcessEnv) {
     return {
       executable: process.execPath,

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HookCommandCgroup } from '../hooks/hook-command-cgroup.js';
+import {
+  HookCommandIsolationUnavailableError,
+  ManagedChildRunSupervisor,
+} from './managed-child-run-supervisor.js';
+
+let directory: string;
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'child-supervisor-'));
+});
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(directory, { recursive: true, force: true });
+});
+
+async function fakeUnit(name: string) {
+  const dir = join(directory, name);
+  await mkdir(dir);
+  const unit = Reflect.construct(HookCommandCgroup, [dir]);
+  const removed = { value: false };
+  vi.spyOn(unit, 'remove').mockImplementation(() => {
+    removed.value = true;
+  });
+  return { unit, removed };
+}
+
+describe('ManagedChildRunSupervisor', () => {
+  it('refuses creation without a delegated root', () => {
+    expect(() =>
+      ManagedChildRunSupervisor.create({ cgroupRoot: undefined }),
+    ).toThrow(HookCommandIsolationUnavailableError);
+  });
+
+  it('starts a process whose output and exit evidence are captured', async () => {
+    const { unit, removed } = await fakeUnit('qwen-bg-shell-1');
+    const create = vi.spyOn(HookCommandCgroup, 'create').mockReturnValue(unit);
+    const supervisor = ManagedChildRunSupervisor.create({
+      cgroupRoot: '/root',
+    });
+    const chunks: string[] = [];
+    const proc = supervisor.start({
+      unitName: 'qwen-bg-shell-1',
+      executable: '/bin/sh',
+      args: ['-c', 'printf hello'],
+      env: { PATH: '/bin:/usr/bin' },
+      cwd: directory,
+      onOutput: (_stream, chunk) => chunks.push(chunk.toString()),
+    });
+    expect(create).toHaveBeenCalledWith('/root', 'qwen-bg-shell-1');
+    expect(supervisor.size).toBe(1);
+    await new Promise((resolve) => proc.child.once('exit', resolve));
+    await writeFile(
+      join(directory, 'qwen-bg-shell-1', 'cgroup.events'),
+      'populated 0\n',
+    );
+    expect(chunks.join('')).toBe('hello');
+    expect(proc.evidence).toEqual({ exitCode: 0, exitSignal: null });
+    await expect(proc.terminate(1_000)).resolves.toEqual({
+      exitCode: 0,
+      exitSignal: null,
+    });
+    expect(removed.value).toBe(true);
+  });
+
+  it('settles a terminated process only after the unit is empty', async () => {
+    const { unit, removed } = await fakeUnit('qwen-bg-shell-2');
+    vi.spyOn(HookCommandCgroup, 'create').mockReturnValue(unit);
+    const supervisor = ManagedChildRunSupervisor.create({
+      cgroupRoot: '/root',
+    });
+    const proc = supervisor.start({
+      unitName: 'qwen-bg-shell-2',
+      executable: '/bin/sh',
+      args: ['-c', 'sleep 30'],
+      env: { PATH: '/bin:/usr/bin' },
+      cwd: directory,
+      onOutput: () => undefined,
+    });
+    await writeFile(
+      join(directory, 'qwen-bg-shell-2', 'cgroup.procs'),
+      `${proc.child.pid}\n`,
+    );
+    const markEmpty = proc.child.once('exit', () =>
+      writeFile(
+        join(directory, 'qwen-bg-shell-2', 'cgroup.events'),
+        'populated 0\n',
+      ),
+    );
+    const [evidence] = await Promise.all([proc.terminate(5_000), markEmpty]);
+    expect(evidence).toEqual({ exitCode: null, exitSignal: 'SIGTERM' });
+    expect(removed.value).toBe(true);
+  });
+
+  it('keeps the process when emptiness cannot be proven', async () => {
+    const { unit, removed } = await fakeUnit('qwen-bg-shell-3');
+    const empty = vi.spyOn(unit, 'empty').mockReturnValue(false);
+    vi.spyOn(unit, 'terminate').mockResolvedValue(undefined);
+    vi.spyOn(HookCommandCgroup, 'create').mockReturnValue(unit);
+    const supervisor = ManagedChildRunSupervisor.create({
+      cgroupRoot: '/root',
+    });
+    const proc = supervisor.start({
+      unitName: 'qwen-bg-shell-3',
+      executable: '/bin/sh',
+      args: ['-c', 'sleep 30'],
+      env: { PATH: '/bin:/usr/bin' },
+      cwd: directory,
+      onOutput: () => undefined,
+    });
+    await expect(proc.terminate(100)).resolves.toBeNull();
+    expect(empty).toHaveBeenCalled();
+    expect(removed.value).toBe(false);
+    expect(supervisor.process('qwen-bg-shell-3')).toBe(proc);
+    proc.child.kill('SIGKILL');
+    await supervisor.process('qwen-bg-shell-3')?.child.once('exit', () => {});
+  });
+
+  it('forwards attachment with its root only', () => {
+    const attached = { present: true };
+    const attach = vi
+      .spyOn(HookCommandCgroup, 'attach')
+      .mockReturnValue(attached as unknown as HookCommandCgroup);
+    const supervisor = ManagedChildRunSupervisor.create({
+      cgroupRoot: '/root',
+    });
+    expect(supervisor.attach('qwen-bg-x')).toBe(attached);
+    expect(attach).toHaveBeenCalledWith('/root', 'qwen-bg-x');
+  });
+});
@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+  HookCommandCgroup,
+  HookCommandIsolationUnavailableError,
+} from '../hooks/hook-command-cgroup.js';
+
+// H3 of #12827: the per-process supervisor for a managed background Shell.
+// Each process lives in its own delegated cgroup v2 unit whose name derives
+// from the execution identity, so a replacement worker re-attaches by name
+// across its own restarts. Exit is claimed only with evidence; a unit that
+// cannot be proven empty keeps the hold instead. See
+// docs/design/2026-10-03-managed-shell-monitor-runtime.md.
+
+export { HookCommandIsolationUnavailableError };
+
+export interface ChildRunExitEvidence {
+  readonly exitCode: number | null;
+  readonly exitSignal: string | null;
+}
+
+export interface ChildRunSpawnSpec {
+  /** The unit's stable name, derived from the execution identity. */
+  readonly unitName: string;
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly env: NodeJS.ProcessEnv;
+  readonly cwd: string;
+  /** The caller's bounded capture sink, one call per pipe chunk. */
+  readonly onOutput: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
+}
+
+export class ManagedChildRunProcess {
+  private exitEvidence: ChildRunExitEvidence | null = null;
+  private settled = false;
+
+  constructor(
+    readonly unitName: string,
+    private readonly unit: HookCommandCgroup,
+    readonly child: ChildProcess,
+  ) {
+    child.on('error', () => undefined);
+    child.on('exit', (code, signal) => {
+      this.exitEvidence = {
+        exitCode: code,
+        exitSignal: typeof signal === 'string' ? signal : null,
+      };
+    });
+  }
+
+  get exited(): boolean {
+    return this.exitEvidence !== null;
+  }
+
+  get evidence(): ChildRunExitEvidence | null {
+    return this.exitEvidence;
+  }
+
+  /**
+   * Drains output, then TERM, then `cgroup.kill` after the grace window, and
+   * settles only once the unit is proven empty via `cgroup.events` — never on
+   * the root process's exit alone. Answers the exit evidence on success and
+   * `null` while nothing is proven, in which case the caller keeps the hold.
+   */
+  async terminate(graceMs: number): Promise<ChildRunExitEvidence | null> {
+    if (this.settled) return this.exitEvidence;
+    if (this.exited && this.unit.empty()) {
+      this.unit.remove();
+      this.settled = true;
+      return this.exitEvidence;
+    }
+    await this.unit.terminate(graceMs);
+    if (!this.unit.empty()) return null;
+    this.unit.remove();
+    this.settled = true;
+    return this.exitEvidence;
+  }
+}
+
+export class ManagedChildRunSupervisor {
+  private readonly processes = new Map<string, ManagedChildRunProcess>();
+
+  private constructor(private readonly cgroupRoot: string) {}
+
+  static create(options: { cgroupRoot: string | undefined }) {
+    if (options.cgroupRoot === undefined)
+      throw new HookCommandIsolationUnavailableError();
+    return new ManagedChildRunSupervisor(options.cgroupRoot);
+  }
+
+  get size(): number {
+    return this.processes.size;
+  }
+
+  process(unitName: string): ManagedChildRunProcess | undefined {
+    return this.processes.get(unitName);
+  }
+
+  /** Starts a new process under a fresh unit named after the execution. */
+  start(spec: ChildRunSpawnSpec): ManagedChildRunProcess {
+    const unit = HookCommandCgroup.create(this.cgroupRoot, spec.unitName);
+    // The launcher joins the unit before the command exists, so no
+    // deployment-provided executable or environment is read outside it.
+    const launch = unit.launch(spec.executable, [...spec.args], spec.env);
+    const child = spawn(launch.executable, launch.args, {
+      cwd: spec.cwd,
+      env: launch.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    child.stdout?.on('data', (chunk: Buffer) => spec.onOutput('stdout', chunk));
+    child.stderr?.on('data', (chunk: Buffer) => spec.onOutput('stderr', chunk));
+    const process_ = new ManagedChildRunProcess(spec.unitName, unit, child);
+    this.processes.set(spec.unitName, process_);
+    return process_;
+  }
+
+  /**
+   * Re-attaches a unit that a previous incarnation of this worker started:
+   * nothing spawns, and the caller verifies the membership evidence itself.
+   */
+  attach(unitName: string): HookCommandCgroup | undefined {
+    return HookCommandCgroup.attach(this.cgroupRoot, unitName);
+  }
+
+  forget(unitName: string): void {
+    this.processes.delete(unitName);
+  }
+}