run402 4.59.0 → 4.60.0

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.59.0",
+  "surface_version": "4.60.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/daemon-path.mjs

@@ -0,0 +1,99 @@
+/**
+ * Daemon identity + transport addressing (gitvault-persistent-helper D4/D5)
+ * — the ONE module the thin client's fast path may import beside node
+ * builtins (pinned by the import-graph gate test), so it must stay tiny.
+ *
+ * The socket lives INSIDE the client configuration directory — the same
+ * 0700 trust boundary that already holds the allowance private key and the
+ * gitvault keystore — and its path is keyed by CLI version, so a CLI
+ * upgrade resolves a NEW path: the new client never reaches the old daemon,
+ * which idles out on its own. Windows uses a named pipe whose name carries
+ * a hash of the config dir (pipes have no filesystem home) plus the same
+ * version key.
+ */
+import { readFileSync } from "node:fs";
+import { homedir, tmpdir, userInfo } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+
+/** Mirrors core config's base-dir resolution without importing its graph. */
+export function configBaseDir() {
+  return process.env.RUN402_CONFIG_DIR || join(homedir(), ".config", "run402");
+}
+
+let cachedVersion = null;
+export function cliVersion() {
+  if (cachedVersion) return cachedVersion;
+  const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+  cachedVersion = String(pkg.version);
+  return cachedVersion;
+}
+
+/** Bump when the client↔daemon frame protocol changes shape. */
+export const DAEMON_PROTOCOL_VERSION = 1;
+
+/**
+ * Unix domain sockets cap `sun_path` around 104 bytes (macOS) — a long
+ * RUN402_CONFIG_DIR (test tmpdirs, deep homes) makes the config-dir socket
+ * un-listenable, which the fallback would silently mask forever. So the
+ * home is the config dir when the path FITS, else an owner-only per-user
+ * directory under tmpdir whose socket NAME still keys on the config dir —
+ * the trust boundary (0700 dir the daemon creates and verifies) travels
+ * with it either way.
+ */
+const SUN_PATH_BUDGET = 100;
+
+function fallbackDir() {
+  let who;
+  try {
+    who = String(userInfo().uid ?? userInfo().username);
+  } catch {
+    who = "u";
+  }
+  return join(tmpdir(), `run402-gvd-${who}`);
+}
+
+/** The socket's full address — preferred home when it fits the budget, else the owner-only fallback with a config-keyed name. */
+function resolveSocket() {
+  const version = cliVersion().replace(/[^0-9A-Za-z.]/g, "_");
+  if (process.platform === "win32") {
+    const key = createHash("sha256").update(configBaseDir()).digest("hex").slice(0, 12);
+    return { dir: null, path: `\\\\.\\pipe\\run402-gvd-${key}-${version}` };
+  }
+  const preferredDir = join(configBaseDir(), "daemon");
+  const preferred = join(preferredDir, `gv-${version}.sock`);
+  if (Buffer.byteLength(preferred) <= SUN_PATH_BUDGET) return { dir: preferredDir, path: preferred };
+  const dir = fallbackDir();
+  const key = createHash("sha256").update(configBaseDir()).digest("hex").slice(0, 12);
+  return { dir, path: join(dir, `g${key}${version.replace(/\./g, "")}.sock`) };
+}
+
+/** Directory holding the socket (created 0700 by the daemon). */
+export function daemonDir() {
+  return resolveSocket().dir;
+}
+
+export function daemonSocketPath() {
+  return resolveSocket().path;
+}
+
+export function daemonRunnerPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), "gitvault-daemon-run.mjs");
+}
+
+/**
+ * The env allowlist a session forwards (D1): everything run402- or
+ * git-shaped, plus the locale pair git itself respects. Deliberately NOT
+ * the whole environment — the daemon runs with its own HOME/PATH (same
+ * user, same machine), and forwarding arbitrary env would make the daemon's
+ * behavior depend on whichever client spoke last in ways nothing re-reads.
+ */
+export function forwardableEnv(env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v === undefined) continue;
+    if (k.startsWith("RUN402_") || k.startsWith("GIT_") || k === "LC_ALL" || k === "LANG") out[k] = v;
+  }
+  return out;
+}

package/lib/doctor.mjs

@@ -602,6 +602,50 @@ export async function run(sub, args = []) {
   // all of that (the resolver's own top tier), same as every other gitvault
   // verb's `--project`.
   if (wanted("gitvault")) {
+    // gitvault-persistent-helper: a bounded LOCAL probe of the resident
+    // helper engine — {running:false} is a fine answer, never a finding
+    // (the daemon is an accelerator, not a dependency).
+    const daemonInfo = await (async () => {
+      try {
+        const { daemonSocketPath } = await import("./daemon-path.mjs");
+        const { connect: netConnect } = await import("node:net");
+        return await new Promise((resolve) => {
+          let settled = false;
+          const done = (v) => {
+            if (!settled) {
+              settled = true;
+              resolve(v);
+            }
+          };
+          const socket = netConnect(daemonSocketPath());
+          const timer = setTimeout(() => {
+            socket.destroy();
+            done({ running: false });
+          }, 500);
+          let data = "";
+          socket.on("data", (c) => {
+            data += c.toString("utf8");
+            const nl = data.indexOf("\n");
+            if (nl === -1) return;
+            clearTimeout(timer);
+            try {
+              const { t: _t, ...rest } = JSON.parse(data.slice(0, nl));
+              done({ running: true, ...rest });
+            } catch {
+              done({ running: false });
+            }
+            socket.end();
+          });
+          socket.once("error", () => {
+            clearTimeout(timer);
+            done({ running: false });
+          });
+          socket.once("connect", () => socket.write('{"t":"status"}\n'));
+        });
+      } catch {
+        return { running: false };
+      }
+    })();
     const target = await resolveGitvaultTarget({ repoDir: process.cwd(), explicitProjectId: projectOverride ?? undefined });
     const projectId = target.project_id ?? null;
     const repoId = target.repo_id ?? null;
@@ -633,6 +677,7 @@ export async function run(sub, args = []) {
           // already proved a second covering recipient, so the hint switches
           // to the durability sentence instead of the terminal-loss claim.
           covering_recipients: gv.covering_recipients ?? null,
+          daemon: daemonInfo,
         };
         const gaps = [];
         // The one that actually breaks the next deploy: the project demands a

package/lib/gitvault-daemon-run.mjs

@@ -0,0 +1,22 @@
+/**
+ * Daemon process entry (gitvault-persistent-helper) — spawned detached by
+ * the thin client's fallback path; never invoked by users directly. Enables
+ * the compile cache (the daemon compiles the heavy graph exactly once, so
+ * this mostly benefits the NEXT daemon after an upgrade), then runs the
+ * listener. A second copy losing the listen race exits quietly — the socket
+ * winner serves everyone.
+ */
+import * as nodeModule from "node:module";
+
+try {
+  nodeModule.enableCompileCache?.();
+} catch {
+  /* silent by contract */
+}
+
+const { runDaemon } = await import("./gitvault-daemon.mjs");
+try {
+  await runDaemon();
+} catch {
+  process.exit(0);
+}

package/lib/gitvault-daemon.mjs

@@ -0,0 +1,263 @@
+/**
+ * The resident helper engine (gitvault-persistent-helper D2–D6).
+ *
+ * Holds the WARM things — the loaded session module (whose top-level await
+ * pulls the whole SDK graph), the owned dispatcher's live h2 connection,
+ * signer precomputation, the paid stack — and re-reads the SMALL things
+ * (keystore, pins, wallet binding, allowance, env-derived config) fresh per
+ * forwarded session, so no cache-invalidation class exists (D2).
+ *
+ * SINGLE-SESSION BY DESIGN (D6 as applied): a session is {cwd, env}
+ * applied to THIS process (`process.chdir` + an env allowlist swap), and
+ * the SDK reads both at call time throughout — two concurrent sessions
+ * with different cwd/env would race process-global state. Concurrent git
+ * helpers are rare; a `busy` rejection makes the second client fall back
+ * in-process, which is exactly today's behavior. Correct and boring beats
+ * clever here.
+ *
+ * Lifecycle (D4): idle exit after 15 minutes; the socket path is keyed by
+ * CLI version so an upgraded client never reaches this daemon; a `hello`
+ * carrying a different version or protocol is rejected (the client falls
+ * back and spawns a fresh daemon at ITS path). Trust boundary (D5): the
+ * socket lives in the 0700 config dir, 0600 where the OS honors socket
+ * modes; no network listener exists or ever will in this module.
+ */
+import net from "node:net";
+import { mkdirSync, unlinkSync, chmodSync } from "node:fs";
+import { daemonDir, daemonSocketPath, DAEMON_PROTOCOL_VERSION, cliVersion, forwardableEnv } from "./daemon-path.mjs";
+import { PassThrough } from "node:stream";
+
+const IDLE_EXIT_MS = 15 * 60 * 1000;
+
+function frame(obj) {
+  return `${JSON.stringify(obj)}\n`;
+}
+
+/** Swap the allowlisted env to the session's view; returns a restore fn. */
+function applySessionEnv(sessionEnv) {
+  const mine = forwardableEnv(process.env);
+  const keys = new Set([...Object.keys(mine), ...Object.keys(sessionEnv)]);
+  for (const k of keys) {
+    if (k in sessionEnv) process.env[k] = sessionEnv[k];
+    else delete process.env[k];
+  }
+  return () => {
+    for (const k of new Set([...keys, ...Object.keys(forwardableEnv(process.env))])) {
+      if (k in mine) process.env[k] = mine[k];
+      else delete process.env[k];
+    }
+  };
+}
+
+export async function runDaemon() {
+  // Load the heavy module ONCE — this is the entire point of residency.
+  // Its top-level await pulls the SDK graph; the prewarm dials the API
+  // origin so the first forwarded session rides a warm h2 connection.
+  const { prewarmGitvaultConnection } = await import("../sdk/dist/node/gitvault-prewarm.js");
+  prewarmGitvaultConnection();
+  const { runHelperSession } = await import("./remote-helper-session.mjs");
+
+  const socketPath = daemonSocketPath();
+  if (process.platform !== "win32") {
+    mkdirSync(daemonDir(), { recursive: true, mode: 0o700 });
+  }
+
+  let busy = false;
+  let sessionsServed = 0;
+  const startedAt = Date.now();
+  let idleTimer = null;
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (busy) {
+        // Never exit under a live session — re-arm and check again later.
+        armIdle();
+        return;
+      }
+      try {
+        server.close();
+        if (process.platform !== "win32") unlinkSync(socketPath);
+      } catch {
+        /* exiting anyway */
+      }
+      process.exit(0);
+    }, IDLE_EXIT_MS);
+    idleTimer.unref?.();
+  };
+
+  const server = net.createServer((socket) => {
+    socket.setNoDelay(true);
+    armIdle();
+    let buf = "";
+    let session = null; // { stdin, restoreEnv, restoreCwd, restoreWrites }
+
+    const send = (obj) => {
+      try {
+        socket.write(frame(obj));
+      } catch {
+        /* client gone — session teardown happens on 'close' */
+      }
+    };
+
+    const teardown = () => {
+      if (!session) return;
+      const s = session;
+      session = null;
+      busy = false;
+      try {
+        s.stdin.end();
+      } catch {
+        /* already ended */
+      }
+      s.restoreWrites();
+      s.restoreEnv();
+      s.restoreCwd();
+      armIdle();
+    };
+    socket.on("close", teardown);
+    socket.on("error", () => socket.destroy());
+
+    socket.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+      for (;;) {
+        const nl = buf.indexOf("\n");
+        if (nl === -1) return;
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          socket.destroy();
+          return;
+        }
+        if (msg.t === "hello") {
+          if (msg.proto !== DAEMON_PROTOCOL_VERSION || msg.version !== cliVersion()) {
+            send({ t: "reject", reason: "version" });
+            socket.end();
+            return;
+          }
+          if (busy) {
+            // D6: one session at a time — the client falls back in-process,
+            // which is exactly the pre-daemon behavior.
+            send({ t: "reject", reason: "busy" });
+            socket.end();
+            return;
+          }
+          busy = true;
+          sessionsServed += 1;
+          const stdin = new PassThrough();
+          const restoreEnv = applySessionEnv(msg.env ?? {});
+          const prevCwd = process.cwd();
+          let restoreCwd = () => {};
+          try {
+            process.chdir(msg.cwd);
+            restoreCwd = () => {
+              try {
+                process.chdir(prevCwd);
+              } catch {
+                /* prev dir may be gone; daemon cwd is inert between sessions */
+              }
+            };
+          } catch {
+            restoreEnv();
+            busy = false;
+            send({ t: "reject", reason: "cwd" });
+            socket.end();
+            return;
+          }
+          // Redirect BOTH write streams for the session's duration: the
+          // session's own out()/note() and every SDK trace/warn line reach
+          // the CLIENT, exactly as they reach a standalone helper's pipes.
+          const realOut = process.stdout.write.bind(process.stdout);
+          const realErr = process.stderr.write.bind(process.stderr);
+          const toBuffer = (data, rest) => (typeof data === "string" ? Buffer.from(data, typeof rest[0] === "string" ? rest[0] : "utf8") : Buffer.from(data));
+          process.stdout.write = (data, ...rest) => {
+            send({ t: "out", d: toBuffer(data, rest).toString("base64") });
+            rest.find((a) => typeof a === "function")?.();
+            return true;
+          };
+          process.stderr.write = (data, ...rest) => {
+            send({ t: "err", d: toBuffer(data, rest).toString("base64") });
+            rest.find((a) => typeof a === "function")?.();
+            return true;
+          };
+          const restoreWrites = () => {
+            process.stdout.write = realOut;
+            process.stderr.write = realErr;
+          };
+          session = { stdin, restoreEnv, restoreCwd, restoreWrites };
+          send({ t: "ready" });
+          runHelperSession(Array.isArray(msg.argv) ? msg.argv : [], { stdin })
+            .then((code) => {
+              teardown();
+              send({ t: "exit", code });
+              socket.end();
+            })
+            .catch(() => {
+              teardown();
+              send({ t: "exit", code: 1 });
+              socket.end();
+            });
+        } else if (msg.t === "in") {
+          session?.stdin.write(Buffer.from(msg.d, "base64"));
+        } else if (msg.t === "in_end") {
+          session?.stdin.end();
+        } else if (msg.t === "status") {
+          send({ t: "status", version: cliVersion(), proto: DAEMON_PROTOCOL_VERSION, pid: process.pid, started_at: startedAt, sessions_served: sessionsServed, busy });
+          socket.end();
+        } else if (msg.t === "stop") {
+          send({ t: "stopping" });
+          socket.end();
+          try {
+            server.close();
+            if (process.platform !== "win32") unlinkSync(socketPath);
+          } catch {
+            /* exiting anyway */
+          }
+          process.exit(0);
+        }
+      }
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    const tryListen = (attempt) => {
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE" && attempt === 0 && process.platform !== "win32") {
+          // A live daemon OR a stale socket file from a crash. Probe it: a
+          // refused connection means stale — unlink and take the address.
+          const probe = net.connect(socketPath);
+          probe.once("connect", () => {
+            probe.destroy();
+            reject(new Error("daemon already running"));
+          });
+          probe.once("error", () => {
+            try {
+              unlinkSync(socketPath);
+            } catch {
+              /* raced */
+            }
+            tryListen(1);
+          });
+        } else {
+          reject(err);
+        }
+      });
+      server.listen(socketPath, () => {
+        if (process.platform !== "win32") {
+          try {
+            chmodSync(socketPath, 0o600);
+          } catch {
+            /* the 0700 parent dir is the real boundary */
+          }
+        }
+        resolve();
+      });
+    };
+    tryListen(0);
+  });
+
+  armIdle();
+  return server;
+}