Class RuntimeBackgroundHandle

src/node/services/backgroundProcessExecutor.ts:216–337

* Unified handle to a background process. * Uses runtime.exec for all operations, working identically for local and SSH. * * Output files (output.log, exit_code) are on the runtime's filesystem. * This handle provides lifecycle management via execBuffered commands.

 * This handle provides lifecycle management via execBuffered commands.
 */
class RuntimeBackgroundHandle implements BackgroundHandle {
  private terminated = false;

  constructor(
    private readonly runtime: Runtime,
    private readonly pid: number,
    public readonly outputDir: string,
    private readonly quotePath: (p: string) => string
  ) {}

  /**
   * Get the exit code from the exit_code file.
   * Returns null if process is still running (file doesn't exist yet).
   */
  async getExitCode(): Promise<number | null> {
    try {
      const exitCodePath = this.quotePath(`${this.outputDir}/${EXIT_CODE_FILENAME}`);
      const result = await execBuffered(
        this.runtime,
        `cat ${exitCodePath} 2>/dev/null || echo ""`,
        { cwd: FALLBACK_CWD, timeout: 10 }
      );
      return parseExitCode(result.stdout);
    } catch (error) {
      log.debug(`RuntimeBackgroundHandle.getExitCode: Error: ${errorMsg(error)}`);
      return null;
    }
  }

  /**
   * Terminate the process group.
   * Sends SIGTERM to process group, waits briefly, then SIGKILL if still running.
   */
  async terminate(): Promise<void> {
    if (this.terminated) return;

    try {
      const exitCodePath = `${this.outputDir}/${EXIT_CODE_FILENAME}`;
      const terminateCmd = buildTerminateCommand(this.pid, exitCodePath, this.quotePath);
      await execBuffered(this.runtime, terminateCmd, {
        cwd: FALLBACK_CWD,
        timeout: 15,
      });
      log.debug(`RuntimeBackgroundHandle: Terminated process group ${this.pid}`);
    } catch (error) {
      // Process may already be dead - that's fine
      log.debug(`RuntimeBackgroundHandle.terminate: Error: ${errorMsg(error)}`);
    }

    this.terminated = true;
  }

  /**
   * Clean up resources.
   * No resources to clean - process runs independently via nohup.
   */
  async dispose(): Promise<void> {
    // No resources to clean up