@cleocode/core 2026.9.8 → 2026.9.9

package/dist/resources/spawn-wrapper.d.ts

@@ -65,6 +65,8 @@
  * @task T11993
  */
 import { type ChildProcess, spawn } from 'node:child_process';
+import type { ParserExecutionPort } from '@cleocode/contracts';
+import type { ProcessCaptureOptions, ProcessCaptureResult, ProcessLaunchExecution, SystemdControlContext } from '@cleocode/contracts/resource-governor';
 /**
  * Scope classes understood by the wrapper.
  *
@@ -97,11 +99,24 @@ export interface SliceResourceConfig {
      * Default: `'32G'`.  P2 target: 85 % of MemTotal (`0.85`).
      */
     memoryMax?: number | string;
+    /** Optional hard kernel task limit (processes and threads); omitted preserves manager defaults. */
+    tasksMax?: number;
 }
 /**
  * Options for {@link buildSpawnArgs}.
  */
 export interface BuildSpawnArgsOptions {
+    /** Original caller deadline/cancellation, shared through probes and launch.
+     * @defaultValue No additional execution deadline; legacy probe ceilings still apply.
+     */
+    execution?: ProcessLaunchExecution;
+    /**
+     * Explicit local manager connection, separate from the child's isolated environment.
+     * Only the launcher receives these path/address overrides; original child values
+     * are restored before executing the requested command. No global environment changes.
+     * @defaultValue Ambient manager discovery.
+     */
+    systemdControl?: SystemdControlContext;
     /**
      * Scope class — controls `ManagedOOMPreference` and the transient unit name
      * prefix.
@@ -194,24 +209,31 @@ export declare const CLEO_SLICE: "cleo.slice";
  * P1: MemoryHigh disabled, MemoryMax=32G.
  * P2 target (after T11994 stall-escalator lands): memoryHigh=0.60, memoryMax=0.85.
  */
-export declare const DEFAULT_SCOPE_RESOURCES: Required<SliceResourceConfig>;
+export declare const DEFAULT_SCOPE_RESOURCES: Required<Omit<SliceResourceConfig, 'tasksMax'>>;
 /**
- * Check whether `systemd-run --user` is usable on this host.
- *
- * Returns `false` on non-Linux, when systemd-run is not on PATH, or when
- * DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR are absent (CI containers,
- * ssh sessions without a user bus).
+ * Check whether the selected local user manager can launch transient scopes.
+ * @param context - Explicit manager context; omitted callers retain ambient discovery.
+ * @param execution - Original deadline/cancellation; each synchronous probe uses its remaining budget.
+ * @returns Whether systemd binaries and the selected user bus answered the bounded probes.
+ * @remarks Availability does not prove that a later scope or resource bound was established.
+ * Probe results are keyed by platform, executable search path and manager connection,
+ * so an unavailable ambient context cannot poison a later explicit context.
+ * @example
+ * ```typescript
+ * const available = hasSystemdRun({ runtimeDirectory: '/run/user/1000' });
+ * ```
  */
-export declare function hasSystemdRun(): boolean;
+export declare function hasSystemdRun(context?: SystemdControlContext, execution?: ProcessLaunchExecution): boolean;
 /**
- * Force-override the cached systemd-run availability.
- *
- * Exposed for unit tests that need to exercise the pgid-fallback or
- * systemd paths without the real binary.
- *
- * @param available - `true` = force systemd path, `false` = force pgid path.
+ * Override availability for deterministic tests, or clear the override and cached probes.
+ * @param available - Forced availability; undefined restores real context-specific probing.
+ * @remarks Test overrides do not establish actual manager availability or containment.
+ * @example
+ * ```typescript
+ * _forceSystemdRunAvailable(undefined);
+ * ```
  */
-export declare function _forceSystemdRunAvailable(available: boolean): void;
+export declare function _forceSystemdRunAvailable(available: boolean | undefined): void;
 /**
  * Build the argv for a cleo child spawn.
  *
@@ -242,6 +264,11 @@ export declare function _forceSystemdRunAvailable(available: boolean): void;
  * @param args - Arguments to pass to the executable.
  * @param opts - Wrapper options (scope class, resources, etc.).
  * @returns Build result with final command, args, mode, and unit name.
+ * @remarks This only constructs launch arguments; it does not establish or inspect a scope.
+ * @example
+ * ```typescript
+ * const launch = buildSpawnArgs('node', ['--version']);
+ * ```
  */
 export declare function buildSpawnArgs(command: string, args: readonly string[], opts?: BuildSpawnArgsOptions): SpawnArgsBuildResult;
 /**
@@ -260,6 +287,47 @@ export declare function buildSpawnArgs(command: string, args: readonly string[],
  * @param spawnOpts - Options forwarded to `child_process.spawn`.
  * @param wrapOpts - Wrapper options (scope class, resources, etc.).
  * @returns Wrapped spawn result.
+ * @remarks An explicit manager context applies only to the launcher. Child manager variables
+ * are restored before execution, while all other child environment values remain in env.
+ * Scope membership, limits and cleanup require independent observation.
+ * @example
+ * ```typescript
+ * const launched = spawnWrapped('node', ['--version'], { env: process.env });
+ * ```
  */
 export declare function spawnWrapped(command: string, args: readonly string[], spawnOpts?: Parameters<typeof spawn>[2], wrapOpts?: BuildSpawnArgsOptions): SpawnWrappedResult;
+/**
+ * Capture an owned process with a shared deadline, cancellation and bounded output.
+ * @param command - Exact executable; never interpreted as a shell expression.
+ * @param args - Exact target arguments; no environment values are added to argv.
+ * @param options - Explicit captured routing, environment and original execution budget.
+ * @returns Target events and independent transport, stop and cleanup diagnostics.
+ * @throws When admission inputs are invalid, the original context has ended, or the platform cannot provide process-group cleanup.
+ * @remarks A fixed Node transport distinguishes the requested process from systemd/sh
+ * launchers. Cleanup has a bounded additional manager timeout and can exceed the
+ * execution deadline. POSIX process groups cannot contain deliberately escaped
+ * descendants; Windows capture is refused. Requested hard memory/task limits require
+ * observation inside the exact owned cgroup before the target is launched. Calls without
+ * requests retain unverified memory limits. This is a transport, not a job scheduler.
+ * @example
+ * ```typescript
+ * const result = await captureWrapped('node', ['check.mjs'], {
+ *   cwd: projectRoot, env: {}, execution: { deadlineAt: Date.now() + 2000 },
+ * });
+ * if (result.started && !result.stopped && result.exitCode === 0) inspect(result);
+ * ```
+ */
+export declare function captureWrapped(command: string, args: readonly string[], options: ProcessCaptureOptions): Promise<ProcessCaptureResult>;
+/**
+ * Create the parser's process-execution port using the canonical spawn service.
+ * @returns A launcher with per-process V8 limits and teardown cancellation.
+ * @remarks Explicit Node argv overrides inherited NODE_OPTIONS heap flags while
+ * preserving loader guards. Configured cgroup memory is not claimed as observed
+ * native-memory containment. The parser verifies its actual V8 limit at startup.
+ * @example
+ * ```ts
+ * const parserExecution = createParserExecutionPort();
+ * ```
+ */
+export declare function createParserExecutionPort(): ParserExecutionPort;
 //# sourceMappingURL=spawn-wrapper.d.ts.map

package/dist/resources/spawn-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-wrapper.d.ts","sourceRoot":"","sources":["../../src/resources/spawn-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAQzE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,EAAE,YAAY,CAAC;IACpB,yEAAyE;IACzE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAG,YAAqB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,mBAAmB,CAGjE,CAAC;AAoBF;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAUvC;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAElE;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CA6EtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,GAAE,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAM,EAC3C,QAAQ,GAAE,qBAA0B,GACnC,kBAAkB,CASpB"}
+{"version":3,"file":"spawn-wrapper.d.ts","sourceRoot":"","sources":["../../src/resources/spawn-wrapper.ts"],"names":[],"mappings":"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"}