@veda-hq/dvara 0.0.0-stage → 0.5.0

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,122 @@
-# 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 |
+
+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;
+```
+
+## 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 --version
+```

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/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 { loadConfig } from "./config.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 --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`);
+/** 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 === "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,76 @@
+// 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 { resolve } from "node:path";
+export const DEFAULTS = {
+    historyDir: ".dvara",
+    quietHooks: ["pre-commit"],
+    watchdog: null,
+    baseRefs: ["origin/main", "origin/develop", "origin/master"],
+    stages: {},
+};
+export const CONFIG_FILE = ".dvara.json";
+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;
+};
+/** 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;
+    }
+    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})`;

package/dist/records.js

@@ -0,0 +1,96 @@
+// What a supervised hook tells its supervisor while it runs: stage markers
+// (`dvara_stage`) and records (`dvara_record`), one line each in files the
+// supervisor names. Parsed here into the history row's fields.
+/**
+ * A duration field. Empty is unmeasured, not zero; text that is not a finite
+ * number is null too, as JSON would have written NaN and Infinity.
+ */
+export const recordedMs = (text) => {
+    if (!text)
+        return null;
+    const ms = Number(text);
+    return Number.isFinite(ms) ? ms : null;
+};
+/**
+ * Records, one tab-separated line each: `refs-source <stdin|none>`,
+ * `ref <local> <remote>`, `stage-input <stage> <kind> <digest>`,
+ * `proof <check> <outcome> <ms>`, and
+ * `proof-reason <check> <reason> <waitMs> <executionMs> <previousExecutionMs>`.
+ * Anything else is ignored.
+ */
+export const parseRecords = (text) => {
+    const declared = new Map();
+    const proof = [];
+    const proofDiagnostics = [];
+    if (text === null)
+        return { pushed: null, declared, proof, proofDiagnostics };
+    const pushed = { source: "none", refs: [] };
+    for (const line of text.split("\n").filter(Boolean)) {
+        const [type, ...f] = line.split("\t");
+        if (type === "refs-source")
+            pushed.source = f[0] ?? "";
+        else if (type === "ref")
+            pushed.refs.push({ local: f[0] ?? "", remote: f[1] ?? "" });
+        else if (type === "stage-input")
+            declared.set(f[0] ?? "", { kind: f[1] ?? "", digest: f[2] ?? "" });
+        else if (type === "proof") {
+            const ms = Number(f[2]);
+            proof.push({
+                check: f[0] ?? "",
+                outcome: f[1] ?? "",
+                ms: Number.isFinite(ms) ? ms : null,
+            });
+        }
+        else if (type === "proof-reason")
+            proofDiagnostics.push({
+                check: f[0] ?? "",
+                reason: f[1] ?? "",
+                waitMs: recordedMs(f[2]),
+                executionMs: recordedMs(f[3]),
+                previousExecutionMs: recordedMs(f[4]),
+            });
+    }
+    return { pushed, declared, proof, proofDiagnostics };
+};
+/**
+ * Stage markers, `<seconds>\t<name>` per line (bash's `$SECONDS`), offset by
+ * the time the hook spent choosing its runtime before the supervisor started,
+ * which becomes a stage of its own. A marker whose time is not a number stays
+ * NaN: JSON writes it as null, which voids its neighbours' durations rather
+ * than inventing them.
+ */
+export const parseStages = (text, bootstrapMs) => {
+    const stages = (text ?? "")
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [seconds, name = ""] = line.split("\t");
+        const at = Number(seconds);
+        return {
+            name,
+            startMs: Number.isFinite(at) ? bootstrapMs + at * 1000 : Number.NaN,
+        };
+    });
+    if (bootstrapMs)
+        stages.unshift({ name: "runtime-selection", startMs: 0 });
+    return stages;
+};
+/** Resident memory (KiB) and process count of `rootPid`'s tree, from a `ps -axo pid=,ppid=,rss=` table. */
+export const treeUsage = (table, rootPid) => {
+    const rows = table
+        .trim()
+        .split("\n")
+        .map((row) => row.trim().split(/\s+/).map(Number));
+    const ids = new Set([rootPid]);
+    // A Set visits what is added while iterating it: a breadth-first walk.
+    for (const id of ids)
+        for (const [pid, ppid] of rows)
+            if (ppid === id && pid !== undefined)
+                ids.add(pid);
+    let rssKiB = 0;
+    for (const [pid, , rss] of rows)
+        if (pid !== undefined && ids.has(pid))
+            rssKiB += rss ?? 0;
+    return { rssKiB, processes: ids.size };
+};

package/dist/supervisor.js

@@ -0,0 +1,371 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// The hook supervisor: runs a git hook under bash, forwards the terminal's
+// signals to it, and writes one history row per run. It never changes the
+// hook's verdict except to report a signalled run as cancelled; every failure
+// of its own (telemetry, watchdog, quiet output) is fail-open.
+import { execFileSync, spawn, spawnSync, } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { cpus, totalmem } from "node:os";
+import { relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { hookKind, invocationContext, perfLevelNames } from "./context.js";
+import { isQuiet, successLine, successNotices } from "./quiet.js";
+import { parseRecords, parseStages, treeUsage } from "./records.js";
+/** Exit code per signal, shared by the pre-launch path and the exit handler. */
+export const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+    SIGHUP: 129,
+    SIGQUIT: 131,
+};
+const FORWARDED = Object.keys(SIGNAL_EXIT_CODES);
+// A hung `ps` must not hang the supervisor that exists to report hangs.
+const psTable = () => execFileSync("ps", ["-axo", "pid=,ppid=,rss="], {
+    encoding: "utf8",
+    timeout: 10_000,
+});
+const readOrNull = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+const importWatchdog = async (path) => (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+/** What a run is judged against, read once before the hook starts. */
+export const judgedAgainst = (root, env, baseRefs) => {
+    const git = (args) => {
+        try {
+            // A fact git cannot give is null; its complaint is not the hook's output.
+            return execFileSync("git", args, {
+                cwd: root,
+                env,
+                stdio: "pipe",
+            }).toString();
+        }
+        catch {
+            return null;
+        }
+    };
+    const revision = git(["rev-parse", "HEAD"]);
+    // A detached HEAD abbreviates to the literal "HEAD", which is no branch.
+    const branchName = git(["rev-parse", "--abbrev-ref", "HEAD"])?.trim();
+    const branch = !branchName || branchName === "HEAD" ? null : branchName;
+    const diff = revision === null ? null : git(["diff", "--binary", "HEAD"]);
+    // Diagnostic identity only: it never authorizes reusing a result.
+    const fingerprint = revision === null || diff === null
+        ? null
+        : createHash("sha256").update(revision).update(diff).digest("hex");
+    // The merge-base is taken with the captured commit, not the ref, so a peer's
+    // fetch between the two calls cannot pair two versions of the base. Exit 1
+    // is "no common ancestor", a real state; any other failure is unknown.
+    const mergeBaseOf = (commit) => {
+        const result = spawnSync("git", ["merge-base", commit, "HEAD"], {
+            cwd: root,
+            env,
+            encoding: "utf8",
+        });
+        if (result.status === 0)
+            return result.stdout.trim() || null;
+        return result.status === 1 ? "none" : null;
+    };
+    let base = null;
+    for (const ref of baseRefs) {
+        const commit = git([
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `${ref}^{commit}`,
+        ])?.trim();
+        if (commit) {
+            base = { ref, commit, mergeBase: mergeBaseOf(commit) };
+            break;
+        }
+    }
+    const tree = git(["rev-parse", "HEAD^{tree}"])?.trim() || null;
+    const untracked = git(["ls-files", "--others", "--exclude-standard"]);
+    const clean = diff === null || untracked === null
+        ? null
+        : diff === "" && untracked === "";
+    return { branch, fingerprint, base, tree, clean };
+};
+/**
+ * Run `hook` under supervision and resolve with the exit code git must see.
+ * One row per run goes to `<root>/<historyDir>/history.jsonl`.
+ */
+export const supervise = async ([hook, ...args], options) => {
+    if (hook === undefined)
+        throw new Error("supervise: no hook given");
+    const { root, config, env = process.env, signals = process, exit = (code) => process.exit(code), platform = process.platform, sampleIntervalMs = 5000, drainLimitMs = 2000, ppid = process.ppid, loadWatchdog = importWatchdog, stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), processTable = psTable, } = options;
+    const dir = resolve(root, config.historyDir);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* telemetry cannot block the hook */
+    }
+    const id = randomUUID();
+    const events = resolve(dir, `${id}.stages`);
+    const records = resolve(dir, `${id}.records`);
+    // The seconds the hook spent selecting its runtime before it started this
+    // supervisor; unset, junk and negative count as none.
+    const bootstrapSeconds = Number(env.DVARA_BOOTSTRAP_SECONDS);
+    const bootstrapMs = Math.max(0, Number.isFinite(bootstrapSeconds) ? bootstrapSeconds : 0) *
+        1000;
+    const started = Date.now() - bootstrapMs;
+    const hookName = hook.split("/").at(-1) ?? hook;
+    const kind = hookKind(hookName, args, env);
+    const invocation = invocationContext(kind, env, ppid);
+    // The handlers go in BEFORE the hook is spawned and before the first await.
+    // The child is detached, in its own process group, so it does not receive
+    // the terminal's signals: forwarding them is the only thing that stops it.
+    // Registered after the spawn, a signal in between kills this supervisor by
+    // default instead, writing no row and orphaning the hook. Under load that
+    // window opens wide.
+    let child;
+    let watchdog;
+    let signal = null;
+    const listeners = [];
+    for (const name of FORWARDED) {
+        const listener = () => {
+            signal = name;
+            // A person cancelled the run: the watchdog must neither act on nor relabel it.
+            watchdog?.disarm();
+            if (child?.pid === undefined) {
+                // Nothing has run, so there is no group to signal and no row to write.
+                exit(SIGNAL_EXIT_CODES[name] ?? 1);
+                return;
+            }
+            try {
+                process.kill(-child.pid, name);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH") {
+                    stderr(`Process-group signal forwarding failed: ${error.code}; forwarding to the hook directly.\n`);
+                    child.kill(name);
+                }
+            }
+        };
+        listeners.push([name, listener]);
+        signals.on(name, listener);
+    }
+    // A settled run answers no more signals: each run removes only its own.
+    const release = () => {
+        for (const [name, listener] of listeners)
+            signals.off(name, listener);
+    };
+    const { branch, fingerprint, base, tree, clean } = judgedAgainst(root, env, config.baseRefs);
+    let watchdogModule = null;
+    if (config.watchdog) {
+        try {
+            watchdogModule = await loadWatchdog(resolve(root, config.watchdog));
+        }
+        catch {
+            /* the watchdog is a safety net, never a prerequisite for running the hook */
+        }
+    }
+    // Signalled while the watchdog loaded: `exit` has ended the CLI already.
+    if (signal) {
+        release();
+        return SIGNAL_EXIT_CODES[signal] ?? 1;
+    }
+    const quiet = isQuiet(kind, config.quietHooks, env);
+    const held = [];
+    const spawned = spawn("bash", [hook, ...args], {
+        cwd: root,
+        // stdin stays inherited: pre-push reads its refs from it.
+        stdio: quiet ? ["inherit", "pipe", "pipe"] : "inherit",
+        detached: true,
+        env: {
+            ...env,
+            DVARA_MEASURED_HOOK: hookName,
+            DVARA_STAGE_FILE: events,
+            DVARA_RECORD_FILE: records,
+        },
+    });
+    child = spawned;
+    if (quiet)
+        for (const stream of [spawned.stdout, spawned.stderr])
+            stream?.on("data", (chunk) => held.push(chunk));
+    if (watchdogModule && spawned.pid !== undefined) {
+        try {
+            watchdog = watchdogModule.createWatchdog({
+                rootPid: spawned.pid,
+                stageFile: events,
+                hangsDir: resolve(dir, "hangs"),
+                runId: id,
+                config: watchdogModule.resolveWatchdogConfig(env, platform, perfLevelNames(platform)),
+            });
+        }
+        catch {
+            watchdog = undefined;
+        }
+    }
+    let peakTreeRssKiB = 0;
+    let peakProcesses = 0;
+    let resourceSamples = 0;
+    const sample = () => {
+        try {
+            const table = processTable();
+            const usage = treeUsage(table, spawned.pid ?? -1);
+            peakTreeRssKiB = Math.max(peakTreeRssKiB, usage.rssKiB);
+            peakProcesses = Math.max(peakProcesses, usage.processes);
+            resourceSamples++;
+        }
+        catch {
+            /* an unavailable measurement is not a verdict */
+        }
+    };
+    const timer = setInterval(sample, sampleIntervalMs);
+    /** A quiet hook's held output: all of it when the run did not pass, else its warnings and one line. */
+    const report = (code, durationMs) => {
+        const output = Buffer.concat(held);
+        const log = resolve(dir, `${kind}.log`);
+        try {
+            writeFileSync(log, output);
+        }
+        catch {
+            /* the log is a convenience; the verdict is printed regardless */
+        }
+        if (code !== 0) {
+            stderr(output);
+            return;
+        }
+        const lines = [
+            ...successNotices(output.toString("utf8")),
+            successLine(kind, durationMs, relative(root, log)),
+        ];
+        stdout(`${lines.join("\n")}\n`);
+    };
+    /**
+     * Wait for a quiet hook's pipes to empty after it exits. A process the hook
+     * left running can hold them open forever, so the wait is bounded and the
+     * pipes are then closed.
+     */
+    const drained = async () => {
+        if (!quiet)
+            return;
+        const streams = [spawned.stdout, spawned.stderr].filter((s) => s !== null);
+        const closed = Promise.all(streams.map((stream) => stream.closed
+            ? null
+            : new Promise((done) => stream.once("close", done))));
+        const limit = new Promise((done) => setTimeout(() => done("limit"), drainLimitMs).unref());
+        const outcome = await Promise.race([closed, limit]);
+        if (outcome === "limit")
+            held.push(Buffer.from(`[output truncated: a process the hook started still held its output open ${drainLimitMs / 1000} s after it exited]\n`));
+        for (const stream of streams)
+            stream.destroy();
+    };
+    const finish = (exitCode, error) => {
+        let code = exitCode;
+        clearInterval(timer);
+        watchdog?.stop();
+        const watchdogSummary = watchdog?.summary() ?? {
+            mode: "unavailable",
+        };
+        // An enforced stop decides the outcome: the hook exited because the
+        // watchdog stopped it, so its own status is not the story.
+        const imposed = watchdogModule?.exitDisposition(watchdogSummary) ?? null;
+        if (imposed)
+            code = imposed.code;
+        const ended = Date.now();
+        if (quiet)
+            report(code, ended - started);
+        const marks = parseStages(readOrNull(events), bootstrapMs);
+        const { pushed, declared, proof, proofDiagnostics } = parseRecords(readOrNull(records));
+        const verdict = (last) => imposed
+            ? imposed.status
+            : signal
+                ? "cancelled"
+                : code === 0
+                    ? "success"
+                    : last
+                        ? "failed"
+                        : "failure";
+        // A stage's input is what it declared, else the whole tree when that tree
+        // is exactly a commit: coarse, but recomputable.
+        const treeInput = clean && tree ? { kind: "tree", digest: tree } : null;
+        const stages = marks.map((stage, index) => ({
+            ...stage,
+            input: declared.get(stage.name) ?? treeInput,
+            durationMs: Math.max(0, (marks[index + 1]?.startMs ?? ended - started) - stage.startMs),
+            status: index === marks.length - 1 ? verdict(true) : "completed",
+        }));
+        try {
+            appendFileSync(resolve(dir, "history.jsonl"), `${JSON.stringify({
+                schema: 1,
+                id,
+                kind,
+                invocation,
+                startedAt: new Date(started).toISOString(),
+                durationMs: ended - started,
+                exitCode: code,
+                signal,
+                error,
+                status: verdict(false),
+                branch,
+                fingerprint,
+                fingerprintPurpose: "diagnostic-head-and-tracked-diff-only",
+                base,
+                tree,
+                clean,
+                pushed,
+                stages,
+                proof,
+                proofDiagnostics,
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                cpus: cpus().length,
+                totalMemoryBytes: totalmem(),
+                sampledPeakTreeRssKiB: peakTreeRssKiB || null,
+                peakProcesses: peakProcesses || null,
+                resourceSamples,
+                sampleIntervalMs,
+                watchdog: watchdogSummary,
+            })}\n`);
+            rmSync(events, { force: true });
+            rmSync(records, { force: true });
+        }
+        catch (failure) {
+            stderr(`History unavailable: ${failure.message}\n`);
+        }
+        return code;
+    };
+    // One row per run, whichever of `error` and `exit` arrives first.
+    let outcome;
+    return new Promise((done, fail) => {
+        const settle = (code, error) => {
+            try {
+                outcome ??= finish(code, error);
+                done(outcome);
+            }
+            catch (failure) {
+                fail(failure);
+            }
+            finally {
+                release();
+            }
+        };
+        spawned.on("error", (error) => settle(127, error.message));
+        spawned.on("exit", (code, childSignal) => {
+            // The watchdog's own stop is not a cancellation; `finish` reports its verdict instead.
+            if (!watchdog?.enforced())
+                signal ??= childSignal;
+            // A signal outranks the code the hook chose: a hook that traps its
+            // signal and exits 0 was still cancelled, and reporting 0 would let a
+            // push through a gate its operator had just interrupted.
+            const verdict = (signal ? SIGNAL_EXIT_CODES[signal] : undefined) ?? code ?? 1;
+            void drained().then(() => settle(verdict));
+        });
+    });
+};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@veda-hq/dvara",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "Git hooks for repositories coding agents work in: runs each hook under a supervisor that times its stages, forwards signals and keeps one history row per run, with quiet output on success and a keep-going mode for preflights.",
+  "keywords": [
+    "git hooks",
+    "pre-push",
+    "pre-commit",
+    "coding agents",
+    "telemetry"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veda-hq/veda.git",
+    "directory": "packages/dvara"
+  },
+  "homepage": "https://github.com/veda-hq/veda/tree/main/packages/dvara#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "dvara": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/supervisor.js",
+    "./config": "./dist/config.js",
+    "./shell/stages.sh": "./shell/stages.sh",
+    "./shell/keep-going.sh": "./shell/keep-going.sh",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "shell/*.sh"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts --test-coverage-include=src/**/*.ts src/**/*.test.ts",
+    "smoke": "node dist/cli.js --version && node dist/cli.js shell stages",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
+  }
 }

package/shell/keep-going.sh

@@ -0,0 +1,86 @@
+# shellcheck shell=bash
+# Keep-going mode, for a preflight: the push hook itself, run ahead of the
+# push, so the preflight and the push cannot drift apart. Only what a refusal
+# does differs. In a push, a stage's `exit 1` ends the hook at its first
+# failure. Here the same `exit 1` is recorded against the stage that raised it
+# (DVARA_CURRENT_STAGE, stages.sh) and the hook carries on, so one run lists
+# every failure. dvara_keep_going_report ends the run.
+#
+# Source it only in keep-going mode, after the runtimes the hook needs are in
+# place, so a missing runtime still ends the run at once.
+#
+# How: a function named `exit` runs in place of the builtin. It takes over one
+# case only, status 1 in the hook's own shell. In a subshell or a command
+# substitution (BASH_SUBSHELL > 0) `exit` must still end that subshell, and
+# every other status (0, a trap's 130 or 143, a probe's 124) is a real end, so
+# those go to the builtin. Whatever `set -e` aborts on never calls `exit` and
+# still ends the run. A stage written as a function keeps this behaviour: the
+# function runs in the hook's shell, and execution continues after the `exit`.
+#
+# Plain strings, not arrays: macOS runs hooks under /bin/bash 3.2, where an
+# empty array is an unbound variable under `set -u`.
+
+DVARA_KEEP_GOING_FAILED=""
+DVARA_KEEP_GOING_HELD=""
+DVARA_KEEP_GOING_SKIPPED=""
+
+# shellcheck disable=SC2034 # DVARA_UNREPORTED_REFUSAL is read by stages.sh
+exit() {
+  local status="${1:-$?}"
+  if [ "$status" = 1 ] && [ "${BASH_SUBSHELL:-0}" -eq 0 ]; then
+    local stage="${DVARA_CURRENT_STAGE:-unknown}"
+    DVARA_KEEP_GOING_FAILED="${DVARA_KEEP_GOING_FAILED}${stage}"$'\n'
+    DVARA_UNREPORTED_REFUSAL=1
+    echo "✗ ${DVARA_KEEP_GOING_NAME:-preflight}: ${stage} failed; carrying on to the next check"
+    return 0
+  fi
+  builtin exit "$status"
+}
+
+# A check not run because an earlier result makes its verdict meaningless.
+dvara_keep_going_held() {
+  DVARA_KEEP_GOING_HELD="${DVARA_KEEP_GOING_HELD}$1: not run: $2"$'\n'
+  echo "→ $1: not run: $2"
+}
+
+# A check this run was asked not to run: not a failure, and not a pass.
+dvara_keep_going_skipped() {
+  DVARA_KEEP_GOING_SKIPPED="${DVARA_KEEP_GOING_SKIPPED}$1: skipped: $2"$'\n'
+  echo "⏭  $1: skipped: $2"
+}
+
+# The end of the run: every check skipped, held and failed, and the verdict.
+# Fails when any check failed or was held; passes, saying so, when the only
+# gaps are skips.
+dvara_keep_going_report() {
+  local line failed=0
+  echo ""
+  echo "━━━ ${DVARA_KEEP_GOING_TITLE:-Preflight} summary ━━━"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then echo "  ⏭  ${line}"; fi
+  done <<< "$DVARA_KEEP_GOING_SKIPPED"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then echo "  ⏸  ${line}"; fi
+  done <<< "$DVARA_KEEP_GOING_HELD"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then
+      echo "  ❌ ${line}"
+      failed=$((failed + 1))
+    fi
+  done <<< "$DVARA_KEEP_GOING_FAILED"
+  if [ "$failed" -gt 0 ]; then
+    echo "  ${failed} check(s) failed. Fix them all, commit, and run the preflight again."
+    echo "  Nothing was pushed."
+    builtin exit 1
+  fi
+  if [ -n "$DVARA_KEEP_GOING_HELD" ]; then
+    echo "  No check failed, but the checks above did not run. Nothing was pushed."
+    builtin exit 1
+  fi
+  if [ -n "$DVARA_KEEP_GOING_SKIPPED" ]; then
+    echo "  ✅ Every check that ran passed; the push runs the skipped ones. Nothing was pushed."
+    builtin exit 0
+  fi
+  echo "  ✅ Every check passed. Nothing was pushed and no pull request was opened."
+  builtin exit 0
+}

package/shell/stages.sh

@@ -0,0 +1,52 @@
+# shellcheck shell=bash
+# dvara's hook helpers, sourced by a hook that runs under `dvara run`.
+# Builtins only: one-second resolution, no subprocesses, and a failed write
+# never fails the hook. Outside the supervisor the files are unset and every
+# helper is a no-op, so the hook runs the same either way.
+
+# Mark the start of a stage. DVARA_CURRENT_STAGE is the stage a refusal is
+# recorded against in keep-going mode (keep-going.sh).
+# shellcheck disable=SC2034 # read by keep-going.sh
+dvara_stage() {
+  DVARA_CURRENT_STAGE="$1"
+  if [ -n "${DVARA_STAGE_FILE:-}" ]; then
+    printf '%s\t%s\n' "$SECONDS" "$1" >> "$DVARA_STAGE_FILE" || true
+  fi
+}
+
+# A fact for the run's history row that only the hook knows: its fields,
+# tab-separated, one record per call (records.ts lists the kinds).
+dvara_record() {
+  if [ -n "${DVARA_RECORD_FILE:-}" ]; then
+    local IFS=$'\t'
+    printf '%s\n' "$*" >> "$DVARA_RECORD_FILE" || true
+  fi
+}
+
+# Record the commits a push updates, from the ref lines git passes pre-push
+# on stdin ("<local_ref> <local_sha> <remote_ref> <remote_sha>"): each line's
+# two commit ids, never its ref names. An empty argument means a manual run.
+dvara_record_refs() {
+  local _local_ref local_sha _remote_ref remote_sha
+  if [ -z "${1:-}" ]; then
+    dvara_record refs-source none
+    return 0
+  fi
+  dvara_record refs-source stdin
+  while read -r _local_ref local_sha _remote_ref remote_sha; do
+    dvara_record ref "$local_sha" "$remote_sha"
+  done <<< "$1"
+}
+
+# Guards a "✅" line: false once after keep-going mode carried on past a
+# refusal, so a failed check is never reported as passed. A run that stops at
+# its first failure never carries on, so there it is always true.
+dvara_passed() {
+  if [ "${DVARA_UNREPORTED_REFUSAL:-0}" = 1 ]; then
+    DVARA_UNREPORTED_REFUSAL=0
+    return 1
+  fi
+  return 0
+}
+
+dvara_stage startup