@veda-hq/dvara 0.0.0-stage → 0.5.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veda Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# @veda-hq/dvara
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+द्वार, gate. Git hooks for repositories coding agents work in: cheap checks at
+commit, expensive ones once at push.
+
+This release holds the runner every hook goes through. Your hook stays a bash
+file in your repository; dvara runs it.
+
+## What it does
+
+- **One history row per run.** `dvara run <hook-file> [args…]` runs the hook
+  under bash in its own process group and appends a row to
+  `<historyDir>/history.jsonl`: kind, who started it (git, a person, a
+  background preflight, a benchmark), exit code and status, each stage's start,
+  duration and input, the base and tree it was judged against, the commits a
+  push updated, and the hook's peak memory.
+- **Signals reach the hook.** Ctrl-C, SIGTERM, SIGHUP and SIGQUIT are forwarded
+  to the whole group. A run that was signalled is reported as cancelled, with
+  the signal's exit code, even when the hook trapped it and exited 0, so an
+  interrupted gate never lets a push through.
+- **Quiet on success.** A hook listed in `quietHooks` (default `pre-commit`)
+  prints its warnings and one line when it passes, and everything when it
+  fails. The full output is kept in `<historyDir>/<hook>.log`.
+  `DVARA_VERBOSE=1` streams it.
+- **Keep-going mode.** For a preflight, a run of the push hook ahead of the
+  push: each stage's `exit 1` is recorded and the hook carries on, so one run
+  lists every failure.
+- **A watchdog, if you have one.** `watchdog` names a module the supervisor
+  attaches to each run; it may stop a hung hook and decide the verdict. Without
+  one, or when it fails to load, the hook runs exactly as it would anyway.
+
+Every one of these is fail-open: telemetry, quiet output and the watchdog never
+change a hook's verdict.
+
+## A hook under dvara
+
+```bash
+#!/usr/bin/env bash
+# .husky/pre-push, or wherever core.hooksPath points
+if [ "${DVARA_MEASURED_HOOK:-}" != "pre-push" ]; then
+  exec node node_modules/@veda-hq/dvara/dist/cli.js run "$0" "$@"
+fi
+source node_modules/@veda-hq/dvara/shell/stages.sh
+if [ "${DVARA_MODE:-}" = preflight ] && [ $# -eq 0 ]; then
+  source node_modules/@veda-hq/dvara/shell/keep-going.sh
+fi
+
+dvara_stage lint
+pnpm lint || exit 1
+dvara_passed && echo "✅ lint"
+
+dvara_stage test
+pnpm test || exit 1
+
+if [ "${DVARA_MODE:-}" = preflight ] && [ $# -eq 0 ]; then dvara_keep_going_report; fi
+```
+
+`stages.sh` gives the hook:
+
+| Helper                          | Does                                                                                                        |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `dvara_stage <name>`            | marks the start of a stage                                                                                  |
+| `dvara_record <type> <fields…>` | a fact for the row: `stage-input <stage> <kind> <digest>`, `proof <check> <outcome> <ms>`, `proof-reason …` |
+| `dvara_record_refs "$stdin"`    | the commits a push updates, from git's ref lines; never the ref names                                       |
+| `dvara_passed`                  | false once after keep-going mode carried on past a refusal, to guard a "✅" line                            |
+
+`keep-going.sh` adds `dvara_keep_going_held`, `dvara_keep_going_skipped` and
+`dvara_keep_going_report`. `DVARA_KEEP_GOING_NAME` and `DVARA_KEEP_GOING_TITLE`
+rename it in its messages (default "preflight" and "Preflight").
+
+## Configuration
+
+`.dvara.json` at the repository's root, or the file `DVARA_CONFIG` names. Every
+field is optional; an unknown field is an error.
+
+| Field        | Default                                          | Meaning                                                        |
+| ------------ | ------------------------------------------------ | -------------------------------------------------------------- |
+| `historyDir` | `.dvara`                                         | where the history, the quiet log and scratch files go          |
+| `quietHooks` | `["pre-commit"]`                                 | hooks whose passing output is one line                         |
+| `watchdog`   | `null`                                           | a watchdog module, relative to the root                        |
+| `baseRefs`   | `origin/main`, `origin/develop`, `origin/master` | the refs tried for the base a run is judged against            |
+| `stages`     | `{}`                                             | each hook's stages in order; `dvara stages <hook>` prints them |
+
+`records`, an object, holds the settings of `dvara records` and `dvara frozen`
+(below). Each field is optional; an unknown one is an error.
+
+| Field            | Default                        | Meaning                                                                                                                  |
+| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `baseline`       | `.dvara/records-baseline.json` | the per-file baseline, relative to the root; read from git, so it must be tracked (un-ignore it if `.dvara/` is ignored) |
+| `skip`           | `[]`                           | path prefixes no rule reads, such as a checker's own fixtures                                                            |
+| `frozen`         | `{"paths": [], "except": []}`  | `paths`: prefixes `dvara frozen` refuses changing and no rule reads; `except`: exact paths under them that stay editable |
+| `identityPaths`  | `[]`                           | regular expressions for the paths where a commit must be cited by its full id (`EVIDENCE-01`); none by default           |
+| `repository`     | `null`                         | `owner/name` on GitHub: its commit URLs are this repository's, every other repository's are not checked                  |
+| `allowPaths`     | `[]`                           | regular expressions for machine paths that are durable by agreement, matched from where the path starts: anchor with `^` |
+| `packageManager` | `null`                         | `pnpm`, `npm` or `yarn`: the other managers' install commands are refused; `null` checks none                            |
+
+The environment it reads: `DVARA_MODE=preflight` (a preflight's rows get kind
+`preflight`), `DVARA_BACKGROUND=1` (started detached), `DVARA_MEASUREMENT_CONTEXT=manual-benchmark`,
+`DVARA_BOOTSTRAP_SECONDS` (seconds the hook spent selecting its runtime before
+starting dvara, counted as a stage), `DVARA_VERBOSE=1`. It sets
+`DVARA_MEASURED_HOOK`, `DVARA_STAGE_FILE` and `DVARA_RECORD_FILE` for the hook.
+
+## A watchdog module
+
+```ts
+export function createWatchdog(options: {
+  rootPid;
+  stageFile;
+  hangsDir;
+  runId;
+  config;
+}): {
+  disarm(): void;
+  stop(): void;
+  summary(): { mode: string };
+  enforced(): boolean;
+};
+export function resolveWatchdogConfig(
+  env,
+  platform,
+  perfLevels: string[],
+): unknown;
+export function exitDisposition(
+  summary,
+): { code: number; status: string } | null;
+```
+
+## The record gate: `dvara records`
+
+Committed text should not cite what stops meaning anything once the session
+that wrote it ends. The gate reads every text file that is not source code, a
+binary, a lockfile (`*.lock`, `pnpm-lock.yaml`, `package-lock.json`), a
+symlink or a submodule, a skipped or frozen path, the baseline or the config,
+and refuses (rule `EVIDENCE-02`, one finding per line):
+
+- a `file://` URL, a `/Users/<name>` or `/home/<name>` home path, a sandbox temp
+  root (`/private/tmp/`, `/private/var/`, `/var/folders/`), a literal `.git/`
+  path, or an agent-process marker ("I am Agent 3");
+- another package manager's install command, when `packageManager` names one.
+  A clause that says not to ("never run `npm install`") is no finding.
+
+Where `identityPaths` match, it also refuses (rule `EVIDENCE-01`) a commit cited
+by less than its full 40-hex id, since git lengthens abbreviations as history
+grows and clones disagree on their length:
+
+- `abbreviated-id`: a 7–39 hex token the line makes a commit (after a commit
+  word, backticked on its own, in an `a..b` range, cut off with an ellipsis, or
+  in a short commit URL of `repository`), unless the line names it another kind
+  of hash (digest, sha256, checksum, …);
+- `abbreviating-command`: a git command that prints abbreviations
+  (`--oneline`, `%h`, `--abbrev-commit`, `rev-parse --short`);
+- `unresolved-id`: a full id the change adds that is not a commit in this
+  repository, compared with the ids the file cited at the merge base. No
+  baseline holds these: they are new by construction.
+
+In Markdown, a fence's captured output is not read for tokens; its command
+lines are (`$ ` lines of a transcript, every line of an `sh` fence). Fences are
+found by CommonMark's rules (mdast-util-from-markdown), so a fence in a quote or
+a list item counts.
+
+Files written before the gate existed are held by the baseline: each file's
+count per rule, which may only fall. A new finding in a legacy file, a fix that
+leaves its allowance in place, an entry for a file that is gone or not read,
+and a baseline edit that raises a count or adds a file are all refused; a
+rename git detects carries its entry forward.
+
+```sh
+dvara records --staged                 # pre-commit: the index, against the first baseRefs that resolves
+dvara records --base origin/main       # CI: the files the branch changed, at HEAD
+dvara records --all [--base REF]       # every tracked file at HEAD
+dvara records --all --write-baseline   # record today's counts
+dvara records --all --survey           # counts per rule and check
+```
+
+Exit 0: clean or within the baseline; 1: refused; 2: could not run. Inside the
+package the gate takes any list of rules, `(path, text, tree) => Finding[]`;
+the command runs the list `rulesFor` in `src/records/rules.ts` returns.
+
+## Frozen paths: `dvara frozen`
+
+A path under one of `records.frozen.paths` is history: no commit adds, changes
+or deletes a file there, except the exact `records.frozen.except` paths.
+
+```sh
+dvara frozen --staged                    # pre-commit, merge commits included
+dvara frozen --base origin/main [--head REF]   # CI: what the branch changes since its merge base
+```
+
+In a merge, a path staged exactly as a merged-in parent has it is that
+parent's change and passes; a hand resolution counts. With no frozen paths
+configured it passes without asking git. Exit 0, 1 or 2 as above.
+
+## Commands
+
+```sh
+dvara run <hook-file> [hook args…]   # run a git hook under the supervisor
+dvara stages <hook>                  # the stages .dvara.json lists for it
+dvara shell <stages|keep-going>      # the path of a shell helper
+dvara records <--staged | --all [--base REF] [--write-baseline | --survey] | --base REF>
+dvara frozen <--staged | --base REF [--head REF]>
+dvara --version
+```

package/dist/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// dvara: git hooks with cheap checks at commit and expensive ones once at push.
+import { readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { configName, loadConfig } from "./config.js";
+import { frozen, parseArgs as parseFrozenArgs, USAGE as FROZEN_USAGE, } from "./records/frozen.js";
+import { parseArgs as parseRecordsArgs, records, USAGE as RECORDS_USAGE, } from "./records/gate.js";
+import { runner } from "./records/git.js";
+import { supervise } from "./supervisor.js";
+export const USAGE = [
+    "usage: dvara run <hook-file> [hook args…]   run a git hook under the supervisor",
+    "       dvara stages <hook>                  the hook stages the config lists, one per line",
+    "       dvara shell <stages|keep-going>      the path of a shell helper to source",
+    "       dvara records <--staged | --all [--base REF] [--write-baseline | --survey] | --base REF>",
+    "                                            the record gate: no new non-durable paths, a baseline that only falls",
+    "       dvara frozen <--staged | --base REF [--head REF]>",
+    "                                            refuse changes to the frozen paths",
+    "       dvara --version",
+].join("\n");
+const SHELL_HELPERS = new Set(["stages", "keep-going"]);
+export const ownVersion = () => {
+    const pkg = join(import.meta.dirname, "..", "package.json");
+    return JSON.parse(readFileSync(pkg, "utf8")).version;
+};
+/** The path of a shell helper this package ships. */
+export const shellHelper = (name) => resolve(import.meta.dirname, "..", "shell", `${name}.sh`);
+/**
+ * `dvara records` or `dvara frozen` at the root `cwd`: 2 on bad arguments, a
+ * config it cannot read, or git failing.
+ */
+const checkCommand = (command, args, { io, cwd, env }) => {
+    const parsed = command === "records" ? parseRecordsArgs(args) : parseFrozenArgs(args);
+    if ("error" in parsed) {
+        io.err(`dvara ${command}: ${parsed.error}`);
+        io.err(command === "records" ? RECORDS_USAGE : FROZEN_USAGE);
+        return 2;
+    }
+    try {
+        const config = loadConfig(cwd, env);
+        const repo = { cwd, env };
+        if ("mode" in parsed)
+            return records(parsed, repo, io.out, {
+                records: config.records,
+                baseRefs: config.baseRefs,
+                own: [configName(env)],
+            });
+        const result = frozen(parsed, runner(repo), config.records.frozen, env);
+        for (const line of result.stdout)
+            io.out(line);
+        for (const line of result.stderr)
+            io.err(line);
+        return result.code;
+    }
+    catch (error) {
+        io.err(`dvara ${command}: ${error.message}`);
+        return 2;
+    }
+};
+/** Runs one command; resolves with the process's exit code. */
+export const run = async (argv, context) => {
+    const { io, cwd, env } = context;
+    const [command, ...rest] = argv;
+    if (command === "--version") {
+        io.out(ownVersion());
+        return 0;
+    }
+    if (command === "shell" &&
+        rest.length === 1 &&
+        SHELL_HELPERS.has(rest[0] ?? "")) {
+        io.out(shellHelper(rest[0] ?? ""));
+        return 0;
+    }
+    if (command === "records" || command === "frozen")
+        return checkCommand(command, rest, context);
+    if ((command === "run" && rest.length > 0) ||
+        (command === "stages" && rest.length === 1)) {
+        // Git runs every hook at the top of the working tree.
+        let config;
+        try {
+            config = loadConfig(cwd, env);
+        }
+        catch (error) {
+            io.err(error.message);
+            return 2;
+        }
+        if (command === "stages") {
+            for (const name of config.stages[rest[0] ?? ""] ?? [])
+                io.out(name);
+            return 0;
+        }
+        return (context.supervise ?? supervise)(rest, {
+            ...context.options,
+            root: cwd,
+            config,
+            env,
+        });
+    }
+    io.err(USAGE);
+    return 2;
+};
+/** Whether this module is the script node was asked to run, through any symlink. */
+export const isEntry = (entry, moduleUrl) => {
+    if (!entry)
+        return false;
+    try {
+        return (realpathSync(resolve(entry)) === realpathSync(fileURLToPath(moduleUrl)));
+    }
+    catch {
+        return false;
+    }
+};
+/** The process's own output, one line per call. */
+export const processIo = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+};
+if (isEntry(process.argv[1], import.meta.url)) {
+    process.exitCode = await run(process.argv.slice(2), {
+        io: processIo,
+        cwd: process.cwd(),
+        env: process.env,
+    });
+}

package/dist/config.js

@@ -0,0 +1,175 @@
+// A repository's dvara settings: `.dvara.json` at its root, or the file
+// DVARA_CONFIG names (relative to the root). Every field is optional.
+import { readFileSync } from "node:fs";
+import { isAbsolute, posix, resolve } from "node:path";
+export const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn"];
+export const DEFAULTS = {
+    historyDir: ".dvara",
+    quietHooks: ["pre-commit"],
+    watchdog: null,
+    baseRefs: ["origin/main", "origin/develop", "origin/master"],
+    stages: {},
+    records: {
+        baseline: ".dvara/records-baseline.json",
+        skip: [],
+        frozen: { paths: [], except: [] },
+        identityPaths: [],
+        repository: null,
+        allowPaths: [],
+        packageManager: null,
+    },
+};
+export const CONFIG_FILE = ".dvara.json";
+/** The config file's name relative to the root, as `loadConfig` reads it. */
+export const configName = (env) => posix.normalize(env.DVARA_CONFIG || CONFIG_FILE);
+const strings = (value, field) => {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
+        throw new Error(`${field} must be a list of strings`);
+    return value;
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const onlyKnown = (entries, known, field) => {
+    for (const key of Object.keys(entries))
+        if (!known.includes(key))
+            throw new Error(`unknown field ${field}${key}`);
+};
+/** Whether `path`, normalized, leaves the root: `..`, `../x`, `a/../../x`. */
+const escapes = (path) => {
+    const normal = posix.normalize(path);
+    return normal === ".." || normal.startsWith("../");
+};
+/**
+ * Repository-relative path prefixes or paths: none empty, none absolute, none
+ * leaving the root (git prints no path there, so it would match nothing).
+ */
+const repoPaths = (value, field) => {
+    const list = strings(value, field);
+    for (const path of list)
+        if (path === "" || isAbsolute(path) || escapes(path))
+            throw new Error(`${field} must hold repository-relative paths`);
+    return list;
+};
+const patterns = (value, field) => strings(value, field).map((source, i) => {
+    try {
+        return new RegExp(source);
+    }
+    catch (error) {
+        throw new Error(`${field}[${i}] is not a regular expression: ${error.message}`);
+    }
+});
+const parseRecordsConfig = (value) => {
+    if (!isObject(value))
+        throw new Error("records must be an object");
+    onlyKnown(value, Object.keys(DEFAULTS.records), "records.");
+    const records = { ...DEFAULTS.records };
+    if ("baseline" in value) {
+        const path = value.baseline;
+        // Compared with the paths git prints: `./a/../b.json` is `b.json`. A
+        // folder (`.`, `archive/`) names no tracked file, so it is no baseline.
+        const normal = typeof path === "string" ? posix.normalize(path) : "";
+        if (typeof path !== "string" ||
+            path === "" ||
+            isAbsolute(path) ||
+            escapes(path) ||
+            normal === "." ||
+            normal.endsWith("/"))
+            throw new Error("records.baseline must be a file path inside the repository");
+        records.baseline = normal;
+    }
+    if ("skip" in value)
+        records.skip = repoPaths(value.skip, "records.skip");
+    if ("frozen" in value) {
+        const frozen = value.frozen;
+        if (!isObject(frozen))
+            throw new Error("records.frozen must be an object");
+        onlyKnown(frozen, ["paths", "except"], "records.frozen.");
+        records.frozen = {
+            paths: "paths" in frozen
+                ? repoPaths(frozen.paths, "records.frozen.paths")
+                : [],
+            except: "except" in frozen
+                ? repoPaths(frozen.except, "records.frozen.except")
+                : [],
+        };
+    }
+    if ("identityPaths" in value)
+        records.identityPaths = patterns(value.identityPaths, "records.identityPaths");
+    if ("repository" in value) {
+        const repository = value.repository;
+        if (repository !== null &&
+            (typeof repository !== "string" || !/^[\w.-]+\/[\w.-]+$/.test(repository)))
+            throw new Error('records.repository must be "owner/name" or null');
+        records.repository = repository;
+    }
+    if ("allowPaths" in value)
+        records.allowPaths = patterns(value.allowPaths, "records.allowPaths");
+    if ("packageManager" in value) {
+        const manager = value.packageManager;
+        if (manager !== null &&
+            !PACKAGE_MANAGERS.includes(manager))
+            throw new Error(`records.packageManager must be one of ${PACKAGE_MANAGERS.join(", ")}, or null`);
+        records.packageManager = manager;
+    }
+    return records;
+};
+/** The settings in `text` over the defaults; a field of the wrong type is an error, an unknown one too. */
+export const parseConfig = (text) => {
+    const raw = JSON.parse(text);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("the config must be an object");
+    const entries = raw;
+    const known = new Set(Object.keys(DEFAULTS));
+    for (const key of Object.keys(entries))
+        if (!known.has(key))
+            throw new Error(`unknown field ${key}`);
+    const config = { ...DEFAULTS };
+    if ("historyDir" in entries) {
+        if (typeof entries.historyDir !== "string" || entries.historyDir === "")
+            throw new Error("historyDir must be a non-empty string");
+        config.historyDir = entries.historyDir;
+    }
+    if ("quietHooks" in entries)
+        config.quietHooks = strings(entries.quietHooks, "quietHooks");
+    if ("watchdog" in entries) {
+        if (entries.watchdog !== null && typeof entries.watchdog !== "string")
+            throw new Error("watchdog must be a path or null");
+        config.watchdog = entries.watchdog;
+    }
+    if ("baseRefs" in entries)
+        config.baseRefs = strings(entries.baseRefs, "baseRefs");
+    if ("stages" in entries) {
+        const stages = entries.stages;
+        if (typeof stages !== "object" || stages === null || Array.isArray(stages))
+            throw new Error("stages must map each hook to its stage names");
+        const out = {};
+        for (const [hook, names] of Object.entries(stages))
+            out[hook] = strings(names, `stages.${hook}`);
+        config.stages = out;
+    }
+    if ("records" in entries)
+        config.records = parseRecordsConfig(entries.records);
+    return config;
+};
+/**
+ * The settings for `root`. No file is the defaults. A file that cannot be
+ * parsed is an error: a hook that silently ran on the defaults would write its
+ * history somewhere nobody reads.
+ */
+export const loadConfig = (root, env) => {
+    const path = resolve(root, env.DVARA_CONFIG || CONFIG_FILE);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT" && !env.DVARA_CONFIG)
+            return DEFAULTS;
+        throw new Error(`dvara: cannot read ${path}: ${error.message}`);
+    }
+    try {
+        return parseConfig(text);
+    }
+    catch (error) {
+        throw new Error(`dvara: ${path}: ${error.message}`);
+    }
+};

package/dist/context.js

@@ -0,0 +1,67 @@
+// Who started a run and on what machine: facts for the history row only.
+import { execFileSync } from "node:child_process";
+const run = (file, args) => execFileSync(file, args, { encoding: "utf8", timeout: 5000 });
+/**
+ * A preflight runs the pre-push hook ahead of a push but is not one: its rows
+ * get their own kind, so a reader of push rows never counts it. Git always
+ * passes a real push its remote, so one that inherited the mode stays a push.
+ */
+export const hookKind = (hookName, args, env) => hookName === "pre-push" && env.DVARA_MODE === "preflight" && args.length === 0
+    ? "preflight"
+    : hookName;
+/** Parent of each pid in a `ps -axo pid=,ppid=,comm=` table. */
+export const processTable = (text) => {
+    const parents = new Map();
+    for (const line of text.trim().split("\n")) {
+        const match = /^(\d+)\s+(\d+)\s+(.+)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const parent = Number(match[2]);
+        // A digit run too long for a number is no process.
+        if (!Number.isFinite(pid) || !Number.isFinite(parent))
+            continue;
+        parents.set(pid, { parent, command: match[3] ?? "" });
+    }
+    return parents;
+};
+/**
+ * Who started this run: a benchmark, a background preflight, git, or a person
+ * (a parent chain that ends at init without passing git).
+ */
+export const invocationContext = (kind, env, ppid, exec = run) => {
+    if (env.DVARA_MEASUREMENT_CONTEXT === "manual-benchmark")
+        return "manual-benchmark";
+    // A detached background preflight's parent chain ends at init.
+    if (kind === "preflight" && env.DVARA_BACKGROUND === "1")
+        return "background";
+    try {
+        const parents = processTable(exec("ps", ["-axo", "pid=,ppid=,comm="]));
+        const seen = new Set();
+        let pid = ppid;
+        for (let entry = parents.get(pid); entry && !seen.has(pid); entry = parents.get(pid)) {
+            seen.add(pid);
+            if (/(?:^|\/)git$/.test(entry.command))
+                return "git-hook";
+            pid = entry.parent;
+        }
+        return pid <= 1 ? "manual" : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+};
+/** The CPU's performance-level names (macOS only), for a watchdog's mode. */
+export const perfLevelNames = (platform, exec = run) => {
+    if (platform !== "darwin")
+        return [];
+    try {
+        const levels = Number(exec("sysctl", ["-n", "hw.nperflevels"]));
+        if (!Number.isFinite(levels))
+            return [];
+        return Array.from({ length: levels }, (_, i) => exec("sysctl", ["-n", `hw.perflevel${i}.name`]).trim());
+    }
+    catch {
+        return [];
+    }
+};

package/dist/quiet.js

@@ -0,0 +1,31 @@
+// Quiet on success. A passing commit hook that prints thirty lines of progress
+// costs an agent session those lines on every later request, and says nothing
+// one line cannot. The supervisor holds a quiet hook's output: on failure it is
+// shown in full; on success it becomes the hook's warnings plus one summary
+// line, and the full output is kept in a log. DVARA_VERBOSE=1 streams it.
+/** Whether this run's output is held rather than streamed. */
+export const isQuiet = (kind, quietHooks, env) => quietHooks.includes(kind) && env.DVARA_VERBOSE !== "1";
+/**
+ * The warnings a passing run still shows: each line starting with ⚠ and the
+ * indented lines that continue it. A warning qualifies a pass; hiding it would
+ * turn the pass into an unqualified one.
+ */
+export const successNotices = (text) => {
+    const kept = [];
+    let inNotice = false;
+    for (const line of text.split("\n")) {
+        if (line.trimStart().startsWith("⚠")) {
+            inNotice = true;
+            kept.push(line);
+        }
+        else if (inNotice && /^\s+\S/.test(line)) {
+            kept.push(line);
+        }
+        else {
+            inNotice = false;
+        }
+    }
+    return kept;
+};
+/** The one line a passing quiet run prints. */
+export const successLine = (kind, durationMs, logPath) => `✅ ${kind} passed in ${(durationMs / 1000).toFixed(1)}s (full output: ${logPath})`;