riftri 0.4.0 → 0.5.0

package/README.md

@@ -162,9 +162,11 @@ $ sudo riftri overlayfs install-helper
 ```
 
 **Riftri fails closed.** When a checkout cannot be reproduced exactly — custom
-filters, sparse checkout, submodules, external attributes, checkout hooks, or non-canonical
-[Git LFS](docs/git-lfs.md) setups — it stops before changing anything rather
-than silently falling back to a full copy. See
+filters, a repository's own sparse-checkout profile, submodules, external
+attributes, or non-canonical [Git LFS](docs/git-lfs.md) setups
+— it stops before changing anything rather than silently falling back to a full
+copy. Sparse worktrees are supported when you ask for them explicitly, with
+[`--sparse-dir` cone selection](docs/sparse-checkout.md). See
 [how Riftri stays safe](docs/safety.md).
 
 ## Common commands

package/bin/riftri.js

@@ -50,22 +50,18 @@ if (process.platform !== "win32") {
   }
 }
 
-function releaseSignals() {
-  for (const signal of ignoredSignals) {
-    process.removeListener(signal, ignoreSignal);
-  }
-  for (const signal of forwardedSignals) {
-    process.removeListener(signal, forwardSignal);
-  }
-}
+// The handlers deliberately stay installed until the process exits. Removing
+// the last listener for a signal restores its default disposition, so a SIGINT
+// still in flight — the common case, since the terminal sent it to the whole
+// foreground group — would kill the launcher in the window before
+// `process.exit`, losing the command's real status. `process.exit` does not
+// need them removed.
 
 child.on("error", (error) => {
-  releaseSignals();
   fail(`could not start the native executable at ${binary}: ${error.message}`);
 });
 
 child.on("exit", (code, signal) => {
-  releaseSignals();
   if (signal !== null) {
     const exitCode = signalExitCode(signal);
     if (exitCode === null) {

package/lib/client.d.ts

@@ -20,7 +20,15 @@ export interface FailureReceipt {
 }
 
 export class RiftriError extends Error {
+  /**
+   * Always a number. A process killed by a signal reports 128 plus the signal
+   * number, the convention native `riftri exec` uses for its own children.
+   */
   readonly exitCode: number;
+  /** The signal that killed the process, or null if it exited on its own. */
+  readonly signal: NodeJS.Signals | null;
+  /** The process was killed rather than exiting on its own. */
+  readonly wasSignalled: boolean;
   readonly receipt: FailureReceipt | null;
   /** Riftri declined before touching anything; falling back is safe. */
   readonly isPolicyRefusal: boolean;
@@ -136,7 +144,17 @@ export class Riftri {
   /** Inspect Git and storage. Creates nothing. */
   doctor(options?: { destination?: string }): Promise<DoctorReport>;
   backends(path?: string): Promise<unknown>;
-  /** Convenience: true when this destination can be optimized. */
+  /**
+   * True when this destination can be optimized.
+   *
+   * Resolves `false` only when Riftri answers the question: no active
+   * copy-on-write backend, a destination Riftri reports as `blocked`, or an
+   * outright refusal. A missing or non-executable binary, an unreadable
+   * repository, or output that is not JSON rejects instead.
+   *
+   * A `needs-activation` destination is optimizable: `worktree.add` works
+   * without `enable()`, which only gates Git interception.
+   */
   isOptimizable(destination?: string): Promise<boolean>;
 
   enable(): Promise<null>;

package/lib/client.js

@@ -9,6 +9,7 @@
 
 const { spawn } = require("node:child_process");
 const { resolveBinary } = require("./platform.js");
+const { signalExitCode } = require("./signals.js");
 
 /** Process exit codes. Documented in docs/cli.md. */
 const EXIT_SUCCESS = 0;
@@ -27,13 +28,25 @@ const REPORTING = new Set([
 ]);
 
 class RiftriError extends Error {
-  constructor(exitCode, receipt, stderr) {
-    super(receipt?.message || stderr.trim() || `riftri exited ${exitCode}`);
+  constructor(exitCode, receipt, stderr, signal = null) {
+    super(
+      receipt?.message ||
+        stderr.trim() ||
+        (signal ? `riftri terminated by ${signal}` : `riftri exited ${exitCode}`),
+    );
     this.name = "RiftriError";
+    // Always a number. A signalled process reports 128 + the signal number,
+    // the convention native `riftri exec` already uses for its own children.
     this.exitCode = exitCode;
+    this.signal = signal;
     this.receipt = receipt ?? null;
   }
 
+  /** The process was killed rather than exiting on its own. */
+  get wasSignalled() {
+    return this.signal !== null;
+  }
+
   /** Riftri declined before touching anything. Falling back is safe. */
   get isPolicyRefusal() {
     return this.exitCode === EXIT_POLICY;
@@ -55,6 +68,18 @@ class RiftriError extends Error {
   }
 }
 
+/**
+ * Place Riftri's own flags before any `--`. Appending them instead puts them
+ * inside the payload `riftri exec` hands to the child, which then fails on a
+ * flag meant for Riftri.
+ */
+function withRiftriFlags(args, flags) {
+  if (flags.length === 0) return [...args];
+  const boundary = args.indexOf("--");
+  if (boundary === -1) return [...args, ...flags];
+  return [...args.slice(0, boundary), ...flags, ...args.slice(boundary)];
+}
+
 function flagsFor(options) {
   const flags = [];
   for (const [key, value] of Object.entries(options)) {
@@ -104,7 +129,7 @@ class Riftri {
     return new Promise((resolve, reject) => {
       let child;
       try {
-        child = spawn(this.#executable(), [...args, ...flags], {
+        child = spawn(this.#executable(), withRiftriFlags(args, flags), {
           cwd,
           stdio: ["ignore", "pipe", "pipe"],
         });
@@ -117,9 +142,33 @@ class Riftri {
       child.stdout.on("data", (chunk) => (stdout += chunk));
       child.stderr.on("data", (chunk) => (stderr += chunk));
       child.on("error", reject);
-      child.on("close", (exitCode) => {
+      child.on("close", (exitCode, signal) => {
+        // A signalled child reports a null exit code. Translate it rather than
+        // letting `null` reach callers through a field typed as a number.
+        if (signal) {
+          const code = signalExitCode(signal) ?? EXIT_OPERATIONAL;
+          reject(new RiftriError(code, null, stderr, signal));
+          return;
+        }
         if (exitCode === EXIT_SUCCESS) {
-          resolve(json && stdout.trim() ? JSON.parse(stdout) : null);
+          if (!json || !stdout.trim()) {
+            resolve(null);
+            return;
+          }
+          try {
+            resolve(JSON.parse(stdout));
+          } catch (error) {
+            // Thrown from a close handler this would be uncatchable and would
+            // take the host process down, so it has to reject instead.
+            reject(
+              new RiftriError(
+                EXIT_OPERATIONAL,
+                null,
+                `riftri ${args.join(" ")} returned output that is not JSON: ` +
+                  `${error.message}\n${stdout.slice(0, 2000)}`,
+              ),
+            );
+          }
           return;
         }
         let receipt = null;
@@ -148,13 +197,28 @@ class Riftri {
     return this.run(["backends", ...target]);
   }
 
-  /** True when this destination can get an optimized worktree. */
+  /**
+   * True when this destination can get an optimized worktree.
+   *
+   * `false` is an answer from Riftri: either the report says no backend is
+   * active, or Riftri refused this destination outright. A broken
+   * installation, an unreadable repository, or any other unexpected failure
+   * rejects instead, so a caller can tell "not supported here" apart from
+   * "this client cannot run at all".
+   */
   async isOptimizable(destination) {
     try {
       const report = await this.doctor(destination ? { destination } : {});
-      return Boolean(report?.cow_backend_active);
+      if (!report?.cow_backend_active) return false;
+      // cow_backend_active is a fact about the volume, not about this
+      // destination. Outside a Git repository it is still true while
+      // `worktree add` cannot possibly succeed, so the readiness verdict
+      // decides. `needs-activation` stays optimizable: the explicit interface
+      // works without `enable`, which only gates Git interception.
+      const readiness = report.destination_readiness?.status;
+      return readiness === undefined || readiness !== "blocked";
     } catch (error) {
-      if (error.code === "ENOENT" || error instanceof RiftriError === false) return false;
+      if (error instanceof RiftriError && error.isPolicyRefusal) return false;
       throw error;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "riftri",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Experimental lightweight Git workspaces for parallel development",
   "license": "MIT",
   "author": "Assistant UI contributors",
@@ -18,14 +18,14 @@
     "node": ">=18.18"
   },
   "optionalDependencies": {
-    "riftri-darwin-arm64": "0.4.0",
-    "riftri-darwin-x64": "0.4.0",
-    "riftri-linux-arm64-gnu": "0.4.0",
-    "riftri-linux-arm64-musl": "0.4.0",
-    "riftri-linux-x64-gnu": "0.4.0",
-    "riftri-linux-x64-musl": "0.4.0",
-    "riftri-win32-arm64": "0.4.0",
-    "riftri-win32-x64": "0.4.0"
+    "riftri-darwin-arm64": "0.5.0",
+    "riftri-darwin-x64": "0.5.0",
+    "riftri-linux-arm64-gnu": "0.5.0",
+    "riftri-linux-arm64-musl": "0.5.0",
+    "riftri-linux-x64-gnu": "0.5.0",
+    "riftri-linux-x64-musl": "0.5.0",
+    "riftri-win32-arm64": "0.5.0",
+    "riftri-win32-x64": "0.5.0"
   },
   "repository": {
     "type": "git",