Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

16.5 KB
Raw Blame
/*
 * subprocess.h — spawn a child process, supervise it, and classify how it ended.
 *
 * Generalized from the crash-isolating index spawn in src/ui/http_server.c so the
 * crash/hang supervisor (Track C) can reuse one primitive across platforms.
 *
 * Beyond a plain spawn+wait it adds the two things a supervisor needs and the
 * ad-hoc harness lacked:
 *   1. Exit CLASSIFICATION — {clean, exit-nonzero, crash, hang, killed} — from
 *      POSIX WIFSIGNALED/WTERMSIG and the Windows NTSTATUS exception exit codes
 *      (0xC0000005 access-violation, 0xC00000FD stack-overflow, …).
 *   2. A quiet-timeout — kill + report HANG when the child makes no progress
 *      (emits no new log line) for a configurable window. This catches external
 *      tree-sitter scanners that infinite-loop (a hang, not a crash).
 *
 * The reap loop is EINTR-safe. Line tailing keeps a partial final line buffered
 * while the child tree can still write, then delivers that final fragment once
 * the tree is quiescent.
 */
#ifndef CBM_SUBPROCESS_H
#define CBM_SUBPROCESS_H

#include <stdbool.h>
#include <stddef.h> /* size_t (cbm_build_win_cmdline) */
#include <stdint.h>

/* How a supervised child ended. */
typedef enum {
    CBM_PROC_CLEAN = 0,    /* exited with code 0 */
    CBM_PROC_EXIT_NONZERO, /* exited with a nonzero code (a graceful failure) */
    CBM_PROC_CRASH,        /* died from a fault: POSIX SIGSEGV/BUS/ILL/FPE/ABRT/SYS,
                            * or a Windows NTSTATUS exception exit code (>= 0xC0000000) */
    CBM_PROC_HANG,         /* made no progress within the quiet-timeout; we killed it */
    CBM_PROC_KILLED,       /* terminated by a non-fault signal we did not initiate */
    CBM_PROC_SPAWN_FAILED  /* fork/exec/CreateProcess failed — no child ever ran */
} cbm_proc_outcome_t;

typedef struct {
    cbm_proc_outcome_t outcome;
    int exit_code;               /* WEXITSTATUS / GetExitCodeProcess; -1 for a POSIX signal */
    int term_signal;             /* WTERMSIG on POSIX; 0 otherwise */
    bool cancellation_requested; /* an explicit cancel request was accepted before terminal */
    bool forced; /* force was needed after grace expiry or to reap descendants after root exit */
    bool tree_quiesced;      /* the owned process tree has no surviving processes */
    bool supervision_failed; /* the bounded containment deadline expired; tree_quiesced is false */
    size_t job_memory_limit_bytes; /* Windows Job Object commit cap; zero on POSIX or uncapped */
    size_t peak_job_memory_bytes;  /* Windows peak commit, not RSS or proof of a limit hit */
    bool job_memory_available;     /* terminal Job Object memory query succeeded */
} cbm_proc_result_t;

/* Called synchronously for each newly-completed log chunk while the child runs.
 * Newline-terminated lines are delivered without their newline; oversized lines
 * may be split into 1023-byte chunks, and the final unterminated remainder is
 * delivered after the tree is quiescent. Each delivered chunk resets the quiet
 * timeout. Poll bounds callback work by chunk/byte count, not elapsed time, so
 * callbacks must return promptly. */
typedef void (*cbm_proc_log_cb)(const char *line, void *ud);

typedef struct {
    const char *bin;                  /* executable path or literal PATH name;
                                       * also argv[0] when argv is NULL */
    const char *const *argv;          /* NULL-terminated argv; NULL => { bin, NULL } */
    const char *const *env_overrides; /* NULL-terminated NAME=value entries, merged with the
                                       * inherited environment for this child only. NAME= keeps
                                       * an empty value; the last duplicate wins. Names must be
                                       * nonempty (case-insensitive on Windows). NULL or an empty
                                       * list preserves normal inheritance. Executable lookup
                                       * continues to use the caller's PATH. strip_git_repo_env
                                       * also removes repository-local entries and GIT_DIFF_OPTS
                                       * from overrides. */
    const char *windows_cmd_payload;  /* Windows-only cmd.exe command text. When set, bin must
                                       * be an absolute path ending in cmd.exe and argv must be
                                       * NULL. The fixed /D /S /V:OFF /C prefix is added while
                                       * this payload is copied verbatim for cmd.exe to parse. */
    const char *log_file;             /* stderr and, when stdout_file is NULL, stdout are
                                       * redirected here and tailed; NULL => discard those
                                       * streams, no tailing */
    cbm_proc_log_cb on_log_line;      /* optional per-line callback */
    void *log_ud;                     /* user data for on_log_line */
    int quiet_timeout_ms;             /* <= 0 => no timeout; else kill+HANG after this many
                                       * ms with no new completed log line */
    int cancel_grace_ms;              /* graceful tree-termination window; <= 0 uses the finite
                                       * CBM_SUBPROCESS_DEFAULT_CANCEL_GRACE_MS */
    size_t memory_limit_bytes;        /* Windows-only hard commit limit for the entire Job Object;
                                       * 0 => no OS-enforced memory limit */
    bool delete_log_on_exit;          /* unlink log_file after reaping */
    bool strip_git_repo_env;          /* child env omits git's repository-local variables
                                       * (foundation/git_env.h) — set for every git spawn so
                                       * an inherited GIT_DIR never overrides `git -C` */
    const char *stdout_file;          /* optional separate stdout capture; NULL preserves
                                       * merged log_file behavior. Must be nonempty and
                                       * distinct from log_file; caller supplies private,
                                       * non-aliasing paths and owns capture-file cleanup.
                                       * Not tailed; quiet_timeout_ms observes log_file only.
                                       * delete_log_on_exit never deletes this file. */
    const char *stdin_file;           /* optional private, immutable regular binary input;
                                       * NULL => null device, never inherited stdin.
                                       * Must be nonempty and non-aliasing with log_file and
                                       * stdout_file; exact equal strings are rejected.
                                       * Caller closes its writer before spawn and retains
                                       * the file until the child tree is quiescent.
                                       * The child chooses its CRT binary mode on Windows.
                                       * Never modified or deleted by this API. */
} cbm_proc_opts_t;

#define CBM_SUBPROCESS_DEFAULT_CANCEL_GRACE_MS 1000
#define CBM_SUBPROCESS_MAX_CANCEL_GRACE_MS 1000
#define CBM_SUBPROCESS_FORCE_SETTLE_MS 1000

/* Opaque, owned supervisor for one child and its contained descendant tree.
 * POSIX implementations contain the child in its own process group; Windows
 * implementations use a Job Object. The containment is what makes a terminal
 * result stronger than merely observing that the direct child exited. */
typedef struct cbm_subprocess cbm_subprocess_t;

typedef enum {
    CBM_PROC_POLL_ERROR = -1, /* invalid handle/arguments */
    CBM_PROC_POLL_RUNNING = 0,
    CBM_PROC_POLL_TERMINAL = 1
} cbm_proc_poll_t;

typedef enum {
    CBM_PROC_TREE_RSS_ERROR = -1,
    CBM_PROC_TREE_RSS_EMPTY = 0,
    CBM_PROC_TREE_RSS_OK = 1,
} cbm_proc_tree_rss_status_t;

/* Spawn opts->bin and return immediately with a supervisor handle. On success,
 * *out owns the process until a terminal poll followed by destroy. Spawn copies
 * the option strings/argv it needs after return; log_ud remains caller-owned until
 * terminal. Returns 0 on success or -1 on validation/spawn failure (*out == NULL).
 *
 * A quiet timeout begins at successful spawn and is reset by each completed log
 * line. Expiry starts the same graceful->forced tree shutdown as explicit cancel,
 * but the terminal outcome remains CBM_PROC_HANG. */
int cbm_subprocess_spawn(const cbm_proc_opts_t *opts, cbm_subprocess_t **out);

/* Advance supervision without sleeping or waiting for the child. RUNNING means
 * the caller must poll again. TERMINAL is returned only after the direct child is
 * reaped AND the entire owned process tree is quiescent; *out is then filled with
 * the cached immutable result. Every later poll returns TERMINAL with that same
 * result. If an OS containment operation remains failed through the bounded
 * force-settle deadline, TERMINAL is still returned but supervision_failed is
 * true and tree_quiesced is false; callers must log this as a critical teardown
 * failure. *out is optional and is not modified for RUNNING or ERROR.
 *
 * Each poll delivers at most 64 log chunks / 64 KiB. On the normal callback
 * delivery path, RUNNING may continue after the process tree is quiescent while
 * remaining log batches drain, and TERMINAL follows successful catch-up. A
 * final-drain I/O error instead terminates without changing process-tree
 * classification and does not attempt to delete the log.
 *
 * Poll performs the graceful->force state transition: after explicit cancel (or
 * quiet-timeout), it requests graceful termination once, then force-terminates the
 * tree when cancel_grace_ms elapses. Callers must keep polling to make progress. */
cbm_proc_poll_t cbm_subprocess_poll(cbm_subprocess_t *process, cbm_proc_result_t *out);

/* Read the current charged memory of the complete contained process tree.
 * On macOS this is phys_footprint (what the OS holds against the process);
 * elsewhere it is RSS. OK returns an overflow-safe byte total, EMPTY means
 * the owned tree currently has no observable members, and ERROR means no
 * trustworthy measurement could be obtained. A member that exits between the
 * listing and its measurement is ignored (the platform reports it gone); any
 * other member that cannot be measured is ERROR, never a smaller total. */
cbm_proc_tree_rss_status_t cbm_subprocess_tree_rss_bytes(cbm_subprocess_t *process,
                                                         uint64_t *rss_bytes);
bool cbm_subprocess_root_running(const cbm_subprocess_t *process);
bool cbm_subprocess_termination_pending(const cbm_subprocess_t *process);
bool cbm_subprocess_supervision_active(const cbm_subprocess_t *process);

/* Record an explicit cancellation request without waiting. Safe to repeat and
 * safe to call from a cancellation thread while one owner thread polls. The
 * owner must stop cancellation producers before destroying the handle. true
 * means the process tree is live and cancellation is now/already pending; false
 * means process is NULL, draining terminal logs, or already terminal. Poll
 * performs signal delivery/escalation. */
bool cbm_subprocess_request_cancel(cbm_subprocess_t *process);

/* Release a terminal handle. This never waits or implicitly cancels; passing a
 * still-running handle violates the API contract. NULL is a no-op. */
void cbm_subprocess_destroy(cbm_subprocess_t *process);

/* Spawn opts->bin, supervise (tail + optional quiet-timeout), block until it ends,
 * and classify the result into *out. Compatibility wrapper around spawn + repeated
 * poll + bounded sleeps. Returns 0 if a child was spawned and its tree reached
 * terminal (out filled), or -1 if spawning/supervision failed
 * (out->outcome == CBM_PROC_SPAWN_FAILED). */
int cbm_subprocess_run(const cbm_proc_opts_t *opts, cbm_proc_result_t *out);

/* Pure outcome classifier — exposed so the platform-specific exit-code mapping
 * (notably the Windows NTSTATUS crash codes) is unit-testable on every platform.
 *   exited_normally: the child returned an exit code (POSIX WIFEXITED; always true
 *                    on Windows, which has no signals — crashes surface as codes).
 *   exit_code:       the exit / exception code (meaningful when exited_normally).
 *   term_signal:     POSIX terminating signal (meaningful when !exited_normally).
 *   timed_out:       we killed the child for exceeding the quiet-timeout. */
cbm_proc_outcome_t cbm_proc_classify(bool exited_normally, int exit_code, int term_signal,
                                     bool timed_out);

/* Stable lowercase name for an outcome (for structured logs / skip reasons). */
const char *cbm_proc_outcome_str(cbm_proc_outcome_t o);

/* Build a Windows CreateProcess command line from a NULL-terminated argv, applying
 * the Microsoft C runtime quoting rules (quote-wrap + escape embedded quotes and
 * their preceding backslashes) so the spawned child re-parses byte-identical argv.
 * Returns true on success, false on overflow (on overflow buf is set to an empty
 * string, never left unterminated).
 *
 * CreateProcess re-parses a SINGLE command string into argv, so a naive `"%s"` wrap
 * silently corrupts any element containing a double-quote — e.g. the index worker's
 * JSON arg {"repo_path":"…"} arrives as {repo_path:…}, the Windows index-worker bug.
 * Exposed (and compiled on every platform — it is pure string logic) so the quoting
 * is unit-tested on Linux/macOS CI, and so both spawn sites (cbm_subprocess_run and
 * the UI http_server index spawn) escape through one shared, tested implementation. */
bool cbm_build_win_cmdline(char *buf, size_t cap, const char *const *argv);

/* Build the special CreateProcess command line needed to invoke cmd.exe with a
 * command-language payload. Unlike cbm_build_win_cmdline(), payload is not a C
 * runtime argv element: cmd.exe must receive its embedded quotes and backslashes
 * unchanged. cmd_executable must be an absolute Windows path whose basename is
 * cmd.exe. The result is:
 *
 *   "<absolute-cmd.exe>" /D /S /V:OFF /C <payload-verbatim>
 *
 * Returns false for invalid input or overflow and leaves a valid empty string
 * whenever buf/cap permit one. Pure string logic, available on every platform
 * so the Windows serialization contract is unit-testable everywhere. */
bool cbm_build_win_cmd_payload(char *buf, size_t cap, const char *cmd_executable,
                               const char *payload);

#ifdef CBM_ENABLE_TEST_SEAMS
/* Force the next N spawn attempts to behave as if the kernel returned EAGAIN
 * ("try again"), so the retry path can be exercised deterministically instead
 * of hoping a loaded machine reproduces it. Test builds only. */
void cbm_subprocess_force_spawn_eagain_for_testing(int attempts);
int cbm_subprocess_pending_spawn_eagain_for_testing(void);
/* Hold the parent of the next N POSIX spawns until the child has exited (left
 * unreaped) before it checks the child's process group: the order a loaded
 * machine produces when a short command finishes before the parent runs
 * again. Test builds only. */
void cbm_subprocess_hold_parent_until_child_exits_for_testing(int spawns);
/* For the next N POSIX spawns, the parent's group check observes what macOS
 * shows for a child that is EXITING: setpgid and getpgid answer ESRCH while
 * waitid does not report it yet. Test builds only. */
void cbm_subprocess_observe_exiting_child_for_testing(int spawns);
uint64_t cbm_subprocess_rss_sum_for_testing(const uint64_t *values, size_t count);
/* Make the tree probe's measurement of every NON-root member fail with
 * platform_error (errno on POSIX, GetLastError() on Windows), as a live or an
 * exiting member would; 0 restores the real calls. Test builds only. */
void cbm_subprocess_tree_rss_fault_members_for_testing(int platform_error);
#endif

/* How the POSIX fork+exec child closed its inherited descriptors (#1484). */
typedef enum {
    CBM_FD_CLOSE_RANGE = 1, /* Linux close_range(2): one syscall */
    CBM_FD_CLOSEFROM,       /* BSD closefrom(3): one call */
    CBM_FD_CLOSE_LOOP       /* close() per descriptor up to _SC_OPEN_MAX: O(RLIMIT_NOFILE) */
} cbm_fd_close_strategy_t;

#if defined(CBM_ENABLE_TEST_SEAMS) && !defined(_WIN32)
/* Run the child's close-inherited-descriptors step in the CALLING process for
 * descriptors >= lowfd (callers pick a lowfd above everything they need) and
 * report which strategy did the work. Test builds only. */
cbm_fd_close_strategy_t cbm_subprocess_close_fds_from_for_testing(int lowfd, long max_fd);
/* Make the close_range fast path behave as if the kernel lacked it (ENOSYS),
 * so the fallback loop is exercised deterministically. Test builds only. */
void cbm_subprocess_force_close_range_enosys_for_testing(bool force);
#endif

#endif /* CBM_SUBPROCESS_H */