@solaqua/gji 0.14.0 → 0.16.0

package/dist/infrastructure/filesystem/locked-file.d.ts

@@ -0,0 +1,4 @@
+/** Serializes read-modify-write cycles on `path` across gji processes. */
+export declare function withFileLock<T>(path: string, operation: () => Promise<T>): Promise<T>;
+/** Replaces `path` in one step so concurrent readers never see a partial file. */
+export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;

package/dist/infrastructure/filesystem/locked-file.js

@@ -0,0 +1,53 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
+import { dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { isAlreadyExistsError } from "./fs-utils.js";
+const LOCK_STALE_AFTER_MS = 10_000;
+const LOCK_RETRY_DELAY_MS = 5;
+const LOCK_WAIT_TIMEOUT_MS = LOCK_STALE_AFTER_MS + LOCK_RETRY_DELAY_MS;
+/** Serializes read-modify-write cycles on `path` across gji processes. */
+export async function withFileLock(path, operation) {
+    await mkdir(dirname(path), { recursive: true });
+    const release = await acquireFileLock(path);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+/** Replaces `path` in one step so concurrent readers never see a partial file. */
+export async function writeJsonAtomic(path, value) {
+    const temporaryPath = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        await rename(temporaryPath, path);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function acquireFileLock(path) {
+    const lockPath = `${path}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            const handle = await open(lockPath, "wx");
+            return async () => {
+                await handle.close();
+                await unlink(lockPath).catch(() => undefined);
+            };
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error))
+                throw error;
+            const lockStat = await stat(lockPath).catch(() => null);
+            if (lockStat && Date.now() - lockStat.mtimeMs > LOCK_STALE_AFTER_MS)
+                await unlink(lockPath).catch(() => undefined);
+            await delay(LOCK_RETRY_DELAY_MS);
+        }
+    }
+    throw new Error(`timed out waiting for the lock on ${path}`);
+}

package/dist/infrastructure/git/runner.d.ts

@@ -1,2 +1,9 @@
+export declare const GIT_ENV: {
+    LC_ALL: string;
+};
 export declare function runGit(cwd: string, args: string[]): Promise<string>;
 export declare function runGitRaw(cwd: string, args: string[]): Promise<string>;
+/** Runs a Git command that can lose a race with another Git process. */
+export declare function runGitRetryingContention(cwd: string, args: string[]): Promise<string>;
+/** Retries `operation`, with jittered backoff, while Git reports contention with another process. */
+export declare function retryGitContention<T>(operation: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/infrastructure/git/runner.js

@@ -1,12 +1,39 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+const CONTENTION_RETRY_TIMEOUT_MS = 10_000;
+const CONTENTION_RETRY_MAX_DELAY_MS = 1_000;
+// Force English output so error message string matching is locale-independent.
+export const GIT_ENV = { ...process.env, LC_ALL: "C" };
 export async function runGit(cwd, args) {
     return (await runGitRaw(cwd, args)).trim();
 }
 export async function runGitRaw(cwd, args) {
+    return execGit(cwd, args);
+}
+/** Runs a Git command that can lose a race with another Git process. */
+export async function runGitRetryingContention(cwd, args) {
+    return (await retryGitContention(() => execGit(cwd, args, GIT_ENV))).trim();
+}
+/** Retries `operation`, with jittered backoff, while Git reports contention with another process. */
+export async function retryGitContention(operation, timeoutMs = CONTENTION_RETRY_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (let delayMs = 25;; delayMs *= 2) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isTransientGitError(error) || Date.now() >= deadline)
+                throw error;
+        }
+        const jitteredDelayMs = Math.min(delayMs, CONTENTION_RETRY_MAX_DELAY_MS) *
+            (0.5 + Math.random() / 2);
+        await new Promise((resolve) => setTimeout(resolve, jitteredDelayMs));
+    }
+}
+async function execGit(cwd, args, env) {
     try {
-        const { stdout } = await execFileAsync("git", args, { cwd });
+        const { stdout } = await execFileAsync("git", args, { cwd, env });
         return stdout;
     }
     catch (error) {
@@ -14,3 +41,10 @@ export async function runGitRaw(cwd, args) {
         throw new Error(`Git command failed in '${cwd}': ${message}`);
     }
 }
+// Only errors that another process can clear: a held lock, or a linked worktree
+// entry that another process is still creating or removing. Git uses the
+// same "cannot lock" wording for permanent failures such as a conflicting branch name.
+function isTransientGitError(error) {
+    return (error instanceof Error &&
+        /(could not lock config file .*|Unable to create '.*\.lock'): File exists|cannot lock ref .*: is at .* but expected |failed to read .*\/commondir|Invalid path '.*\/worktrees\//.test(error.message));
+}

package/dist/infrastructure/persistence/history.js

@@ -1,6 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { withFileLock, writeJsonAtomic } from "../filesystem/locked-file.js";
 import { GLOBAL_CONFIG_DIRECTORY } from "./config.js";
 export const HISTORY_FILE_NAME = "history.json";
 const MAX_HISTORY_ENTRIES = 50;
@@ -26,14 +27,15 @@ export async function loadHistory(home = homedir()) {
 }
 export async function appendHistory(path, branch, home = homedir()) {
     const historyPath = HISTORY_FILE_PATH(home);
-    const existing = await loadHistory(home);
-    const entry = { branch, path, timestamp: Date.now() };
-    const next = [
-        entry,
-        ...existing.filter((existingEntry) => existingEntry.path !== path),
-    ].slice(0, MAX_HISTORY_ENTRIES);
-    await mkdir(dirname(historyPath), { recursive: true });
-    await writeFile(historyPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    await withFileLock(historyPath, async () => {
+        const existing = await loadHistory(home);
+        const entry = { branch, path, timestamp: Date.now() };
+        const next = [
+            entry,
+            ...existing.filter((existingEntry) => existingEntry.path !== path),
+        ].slice(0, MAX_HISTORY_ENTRIES);
+        await writeJsonAtomic(historyPath, next);
+    });
 }
 export async function recordWorktreeUsage(path, branch, home = homedir()) {
     try {

package/dist/infrastructure/persistence/slots.js

@@ -1,6 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { withFileLock, writeJsonAtomic } from "../filesystem/locked-file.js";
 import { GLOBAL_CONFIG_DIRECTORY } from "./config.js";
 export function SLOTS_FILE_PATH(home = homedir()) {
     const configDir = process.env.GJI_CONFIG_DIR;
@@ -20,33 +21,35 @@ export async function loadSlots(home = homedir()) {
     }
 }
 export async function assignWorktreeSlot(repoRoot, worktreePath, home = homedir()) {
-    const slots = await loadSlots(home);
-    const existing = slots[worktreePath];
-    if (existing !== undefined)
-        return existing;
-    if (worktreePath !== repoRoot && slots[repoRoot] === undefined)
-        slots[repoRoot] = 0;
-    const used = new Set(Object.values(slots));
-    const slot = worktreePath === repoRoot ? 0 : nextAvailableSlot(used);
-    slots[worktreePath] = slot;
-    await saveSlots(slots, home);
-    return slot;
+    return withFileLock(SLOTS_FILE_PATH(home), async () => {
+        const slots = await loadSlots(home);
+        const existing = slots[worktreePath];
+        if (existing !== undefined)
+            return existing;
+        if (worktreePath !== repoRoot && slots[repoRoot] === undefined)
+            slots[repoRoot] = 0;
+        const used = new Set(Object.values(slots));
+        const slot = worktreePath === repoRoot ? 0 : nextAvailableSlot(used);
+        slots[worktreePath] = slot;
+        await saveSlots(slots, home);
+        return slot;
+    });
 }
 export async function getWorktreeSlot(worktreePath, home = homedir()) {
     const slot = (await loadSlots(home))[worktreePath];
     return slot === undefined ? null : slot;
 }
 export async function releaseWorktreeSlot(worktreePath, home = homedir()) {
-    const slots = await loadSlots(home);
-    if (!(worktreePath in slots))
-        return;
-    delete slots[worktreePath];
-    await saveSlots(slots, home);
+    await withFileLock(SLOTS_FILE_PATH(home), async () => {
+        const slots = await loadSlots(home);
+        if (!(worktreePath in slots))
+            return;
+        delete slots[worktreePath];
+        await saveSlots(slots, home);
+    });
 }
 async function saveSlots(slots, home) {
-    const path = SLOTS_FILE_PATH(home);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(slots, null, 2)}\n`, "utf8");
+    await writeJsonAtomic(SLOTS_FILE_PATH(home), slots);
 }
 function nextAvailableSlot(used) {
     let slot = 1;

package/dist/infrastructure/process/hooks.js

@@ -96,8 +96,10 @@ export function extractHooks(config) {
     }
     const hooks = raw;
     return {
+        "after-branch-create": parseHookCommand(hooks["after-branch-create"] ?? hooks.afterBranchCreate),
         "after-create": parseHookCommand(hooks["after-create"] ?? hooks.afterCreate),
         "after-enter": parseHookCommand(hooks["after-enter"] ?? hooks.afterEnter),
+        "after-switch": parseHookCommand(hooks["after-switch"] ?? hooks.afterSwitch),
         "before-remove": parseHookCommand(hooks["before-remove"] ?? hooks.beforeRemove),
     };
 }

package/dist/infrastructure/repository/registry.js

@@ -1,12 +1,11 @@
-import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { access, mkdir, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { access, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
+import { withFileLock, writeJsonAtomic } from "../filesystem/locked-file.js";
 import { GLOBAL_CONFIG_DIRECTORY } from "../persistence/config.js";
 const REGISTRY_FILE_NAME = "repos.json";
 const MAX_REGISTRY_ENTRIES = 100;
-const registryLocks = new Map();
 export function REGISTRY_FILE_PATH(home = homedir()) {
     const configDir = process.env.GJI_CONFIG_DIR;
     if (configDir) {
@@ -37,10 +36,12 @@ async function canonicalizeRepoPath(repoPath) {
 }
 export async function registerRepo(repoPath, home = homedir()) {
     const registryPath = REGISTRY_FILE_PATH(home);
-    await withRegistryLock(registryPath, async () => {
+    const canonicalRepoPath = await canonicalizeRepoPath(repoPath);
+    // Skip the lock and the write if this repo is already the most-recently-used entry (common case).
+    if ((await loadRegistry(home))[0]?.path === canonicalRepoPath)
+        return;
+    await withFileLock(registryPath, async () => {
         const existing = await normalizeRegistryForWrite(await loadRegistry(home));
-        const canonicalRepoPath = await canonicalizeRepoPath(repoPath);
-        // Skip write if this repo is already the most-recently-used entry (common case).
         if (existing.length > 0 && existing[0].path === canonicalRepoPath)
             return;
         const entry = {
@@ -50,14 +51,14 @@ export async function registerRepo(repoPath, home = homedir()) {
         };
         const filtered = existing.filter((e) => e.path !== canonicalRepoPath);
         const next = [entry, ...filtered].slice(0, MAX_REGISTRY_ENTRIES);
-        await writeRegistry(next, registryPath);
+        await writeJsonAtomic(registryPath, next);
     });
 }
 export async function removeMissingRegistryEntries(paths, home = homedir()) {
     if (paths.size === 0)
         return { removedPaths: [], skippedPaths: [] };
     const registryPath = REGISTRY_FILE_PATH(home);
-    return withRegistryLock(registryPath, async () => {
+    return withFileLock(registryPath, async () => {
         const entries = await loadRegistry(home);
         const candidates = entries.filter((entry) => paths.has(entry.path));
         const status = await Promise.all(candidates.map(async (entry) => ({
@@ -71,30 +72,11 @@ export async function removeMissingRegistryEntries(paths, home = homedir()) {
             .filter(({ missing }) => !missing)
             .map(({ entry }) => entry.path);
         if (removedPaths.length > 0) {
-            await writeRegistry(entries.filter((entry) => !removedPaths.includes(entry.path)), registryPath);
+            await writeJsonAtomic(registryPath, entries.filter((entry) => !removedPaths.includes(entry.path)));
         }
         return { removedPaths, skippedPaths };
     });
 }
-async function withRegistryLock(registryPath, operation) {
-    const previous = registryLocks.get(registryPath);
-    let release;
-    const current = new Promise((resolve) => {
-        release = resolve;
-    });
-    registryLocks.set(registryPath, current);
-    if (previous)
-        await previous;
-    try {
-        return await operation();
-    }
-    finally {
-        release();
-        if (registryLocks.get(registryPath) === current) {
-            registryLocks.delete(registryPath);
-        }
-    }
-}
 async function isMissingPath(path) {
     try {
         await access(path, constants.F_OK);
@@ -110,18 +92,6 @@ function isMissingPathError(error) {
     const code = error.code;
     return code === "ENOENT" || code === "ENOTDIR";
 }
-async function writeRegistry(entries, registryPath) {
-    await mkdir(dirname(registryPath), { recursive: true });
-    const temporaryPath = `${registryPath}.tmp-${process.pid}-${randomUUID()}`;
-    try {
-        await writeFile(temporaryPath, `${JSON.stringify(entries, null, 2)}\n`, "utf8");
-        await rename(temporaryPath, registryPath);
-    }
-    catch (error) {
-        await rm(temporaryPath, { force: true }).catch(() => undefined);
-        throw error;
-    }
-}
 async function normalizeRegistryForWrite(entries) {
     const normalized = [];
     const seenPaths = new Set();

package/dist/infrastructure/worktree/lifecycle.d.ts

@@ -1,3 +1,28 @@
+export interface NewBranchOptions {
+    startPoint?: string;
+    track?: boolean;
+}
+export type WorktreeTarget = {
+    branch: string;
+} | {
+    branch: string;
+    create: NewBranchOptions;
+} | {
+    detachedAt: string | undefined;
+};
+/**
+ * Adds a worktree on a path no other process has claimed, leaving nothing it
+ * created behind on failure.
+ *
+ * A new branch is created first because that is the only part of `git worktree add -b`
+ * that writes the shared .git/config. Retrying it stays cheap and lets checkouts run in parallel.
+ */
+export declare function addWorktree(repoRoot: string, worktreePath: string, target: WorktreeTarget): Promise<void>;
+/** Best-effort rollback of a worktree, and of the branch if this run created it. */
+export declare function removeCreatedWorktree(repoRoot: string, worktreePath: string, createdBranch?: string): Promise<void>;
+export declare function createBranch(repoRoot: string, branch: string, options?: NewBranchOptions): Promise<void>;
+/** Best-effort rollback. Git refuses to delete a branch another worktree has checked out. */
+export declare function deleteCreatedBranch(repoRoot: string, branch: string): Promise<void>;
 export declare function removeWorktree(repoRoot: string, worktreePath: string): Promise<void>;
 export declare function forceRemoveWorktree(repoRoot: string, worktreePath: string): Promise<void>;
 export declare function deleteBranch(repoRoot: string, branch: string): Promise<void>;

package/dist/infrastructure/worktree/lifecycle.js

@@ -1,15 +1,113 @@
 import { execFile } from "node:child_process";
-import { rm } from "node:fs/promises";
+import { mkdir, rm, rmdir } from "node:fs/promises";
 import { promisify } from "node:util";
+import { isAlreadyExistsError } from "../filesystem/fs-utils.js";
+import { GIT_ENV, retryGitContention } from "../git/runner.js";
 import { listWorktrees } from "../repository/worktrees.js";
 const execFileAsync = promisify(execFile);
-// Force English output so error message string matching is locale-independent.
-const GIT_ENV = { ...process.env, LC_ALL: "C" };
+const BRANCH_CONFIG_CLEANUP_TIMEOUT_MS = 1_000;
+/**
+ * Adds a worktree on a path no other process has claimed, leaving nothing it
+ * created behind on failure.
+ *
+ * A new branch is created first because that is the only part of `git worktree add -b`
+ * that writes the shared .git/config. Retrying it stays cheap and lets checkouts run in parallel.
+ */
+export async function addWorktree(repoRoot, worktreePath, target) {
+    await claimWorktreePath(worktreePath);
+    if ("create" in target) {
+        try {
+            await createBranch(repoRoot, target.branch, target.create);
+        }
+        catch (error) {
+            await rmdir(worktreePath).catch(() => undefined);
+            throw error;
+        }
+    }
+    const args = "branch" in target
+        ? [target.branch]
+        : ["--detach", ...(target.detachedAt ? [target.detachedAt] : [])];
+    try {
+        // No forced locale: this runs the user's hooks. Contention errors in another
+        // language are not retried, and fall through to the rollback below.
+        await retryGitContention(() => execFileAsync("git", ["worktree", "add", worktreePath, ...args], {
+            cwd: repoRoot,
+        }));
+    }
+    catch (error) {
+        // Git can fail after registering the worktree, for example in a post-checkout hook.
+        await removeCreatedWorktree(repoRoot, worktreePath, "create" in target ? target.branch : undefined);
+        throw error;
+    }
+}
+/** Best-effort rollback of a worktree, and of the branch if this run created it. */
+export async function removeCreatedWorktree(repoRoot, worktreePath, createdBranch) {
+    await runLifecycleGit(repoRoot, [
+        "worktree",
+        "remove",
+        "--force",
+        worktreePath,
+    ]).catch(() => undefined);
+    await rmdir(worktreePath).catch(() => undefined);
+    if (createdBranch)
+        await deleteCreatedBranch(repoRoot, createdBranch);
+}
+// Git accepts an empty target directory but does not claim it atomically, so
+// without this, racing processes can both succeed on one path.
+async function claimWorktreePath(worktreePath) {
+    try {
+        await mkdir(worktreePath);
+    }
+    catch (error) {
+        if (!isAlreadyExistsError(error))
+            throw error;
+        throw new Error(`target worktree path already exists: ${worktreePath}`);
+    }
+}
+export async function createBranch(repoRoot, branch, options = {}) {
+    const args = [
+        "branch",
+        ...(options.track ? ["--track"] : []),
+        branch,
+        ...(options.startPoint ? [options.startPoint] : []),
+    ];
+    try {
+        await retryGitContention(async () => {
+            try {
+                await execFileAsync("git", args, { cwd: repoRoot, env: GIT_ENV });
+            }
+            catch (error) {
+                // Git creates the ref before writing tracking config, so this failure
+                // leaves a branch that only this call can have created.
+                if (isGitConfigLockError(error))
+                    await forceDeleteBranch(repoRoot, branch);
+                throw error;
+            }
+        });
+    }
+    catch (error) {
+        if (isGitConfigLockError(error))
+            await removeBranchConfig(repoRoot, branch).catch(() => undefined);
+        throw error;
+    }
+}
+/** Best-effort rollback. Git refuses to delete a branch another worktree has checked out. */
+export async function deleteCreatedBranch(repoRoot, branch) {
+    try {
+        await forceDeleteBranch(repoRoot, branch);
+        await removeBranchConfig(repoRoot, branch);
+    }
+    catch {
+        /* rollback best effort */
+    }
+}
+// `git branch -D` only warns when it cannot update the config, and tracking
+// config can be left partly written when `git branch` loses the lock midway.
+async function removeBranchConfig(repoRoot, branch) {
+    await runLifecycleGit(repoRoot, ["config", "--remove-section", `branch.${branch}`], BRANCH_CONFIG_CLEANUP_TIMEOUT_MS);
+}
 export async function removeWorktree(repoRoot, worktreePath) {
-    await execFileAsync("git", ["worktree", "remove", worktreePath], {
-        cwd: repoRoot,
-        env: GIT_ENV,
-    });
+    await runLifecycleGit(repoRoot, ["worktree", "remove", worktreePath]);
 }
 export async function forceRemoveWorktree(repoRoot, worktreePath) {
     try {
@@ -29,10 +127,12 @@ export async function forceRemoveWorktree(repoRoot, worktreePath) {
     }
 }
 async function removeWorktreeWithForce(repoRoot, worktreePath) {
-    await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
-        cwd: repoRoot,
-        env: GIT_ENV,
-    });
+    await runLifecycleGit(repoRoot, [
+        "worktree",
+        "remove",
+        "--force",
+        worktreePath,
+    ]);
 }
 async function deinitializeSubmodules(worktreePath) {
     await execFileAsync("git", ["submodule", "deinit", "--force", "--all"], {
@@ -41,16 +141,10 @@ async function deinitializeSubmodules(worktreePath) {
     });
 }
 export async function deleteBranch(repoRoot, branch) {
-    await execFileAsync("git", ["branch", "-d", branch], {
-        cwd: repoRoot,
-        env: GIT_ENV,
-    });
+    await runLifecycleGit(repoRoot, ["branch", "-d", branch]);
 }
 export async function forceDeleteBranch(repoRoot, branch) {
-    await execFileAsync("git", ["branch", "-D", branch], {
-        cwd: repoRoot,
-        env: GIT_ENV,
-    });
+    await runLifecycleGit(repoRoot, ["branch", "-D", branch]);
 }
 export function isWorktreeForceRemovalError(error) {
     if (!hasStderr(error)) {
@@ -75,3 +169,10 @@ function hasStderr(error) {
         "stderr" in error &&
         typeof error.stderr === "string");
 }
+async function runLifecycleGit(repoRoot, args, timeoutMs) {
+    await retryGitContention(() => execFileAsync("git", args, { cwd: repoRoot, env: GIT_ENV }), timeoutMs);
+}
+function isGitConfigLockError(error) {
+    return (error instanceof Error &&
+        error.message.includes("could not lock config file"));
+}

package/dist/ports/git.d.ts

@@ -5,4 +5,5 @@ export interface RemoteBase {
 export interface GitCommandPort {
     runGit(cwd: string, args: string[]): Promise<string>;
     runGitRaw(cwd: string, args: string[]): Promise<string>;
+    runGitRetryingContention(cwd: string, args: string[]): Promise<string>;
 }

package/dist/ports/hooks.d.ts

@@ -1,7 +1,14 @@
 export type GjiHookCommand = string | string[];
 export interface GjiHooks {
+    /** A new branch was created by `gji new`, in a new worktree or in place. */
+    "after-branch-create"?: GjiHookCommand;
+    /** A linked worktree was created and bootstrapped. */
     "after-create"?: GjiHookCommand;
+    /** An existing worktree was entered. */
     "after-enter"?: GjiHookCommand;
+    /** The current worktree switched to another branch in place. */
+    "after-switch"?: GjiHookCommand;
+    /** A linked worktree is about to be removed. */
     "before-remove"?: GjiHookCommand;
 }
 export interface HookContext {

package/dist/presentation/shell/completion.js

@@ -37,23 +37,20 @@ const TOP_LEVEL_COMMANDS = [
     },
     { name: "ls", description: "list active worktrees" },
     { name: "clean", description: "interactively prune linked worktrees" },
-    {
-        name: "remove",
-        description: "deprecated: use done for one worktree or clean for bulk cleanup",
-    },
-    { name: "rm", description: "deprecated alias of remove" },
     {
         name: "run-hook",
         description: "run a named hook in the current worktree",
     },
-    {
-        name: "warp",
-        description: "deprecated: use go (press Tab for all known repos)",
-    },
     { name: "config", description: "manage global config defaults" },
 ];
 const SHELL_NAMES = ["bash", "fish", "zsh"];
-const HOOK_NAMES = ["after-create", "after-enter", "before-remove"];
+const HOOK_NAMES = [
+    "after-branch-create",
+    "after-create",
+    "after-enter",
+    "after-switch",
+    "before-remove",
+];
 const CONFIG_KEYS = Array.from(KNOWN_GLOBAL_CONFIG_KEYS);
 export function renderShellCompletion(shell) {
     switch (shell) {
@@ -221,17 +218,15 @@ _gji_completion() {
       COMPREPLY=( $(compgen -W "--compact --json --help" -- "$cur") )
       ;;
     clean)
-      COMPREPLY=( $(compgen -W "-f --force --stale --dry-run --json --help" -- "$cur") )
-      ;;
-    remove|rm)
-      COMPREPLY=( $(compgen -W "$(__gji_worktree_branches) -f --force --dry-run --json --help" -- "$cur") )
+      if [ "\${COMP_WORDS[COMP_CWORD-1]}" = "--path" ]; then
+        COMPREPLY=( $(compgen -d -- "$cur") )
+      else
+        COMPREPLY=( $(compgen -W "-f --force --stale --path --dry-run --json --help" -- "$cur") )
+      fi
       ;;
     run-hook)
       COMPREPLY=( $(compgen -W "${hooks} --help" -- "$cur") )
       ;;
-    warp)
-      COMPREPLY=( $(compgen -W "--print --json --help" -- "$cur") )
-      ;;
     config)
       if [ "$COMP_CWORD" -eq 2 ]; then
         COMPREPLY=( $(compgen -W "get set unset" -- "$cur") )
@@ -454,21 +449,14 @@ complete -c gji -n '__fish_seen_subcommand_from ls' -l json -d 'print active wor
 
 complete -c gji -n '__fish_seen_subcommand_from clean' -s f -l force -d 'bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches'
 complete -c gji -n '__fish_seen_subcommand_from clean' -l stale -d 'only target clean worktrees whose upstream is gone and branch is merged into the default branch'
+complete -c gji -n '__fish_seen_subcommand_from clean' -l path -r -F -d 'only target worktrees under a directory or matching a path glob (repeatable)'
 complete -c gji -n '__fish_seen_subcommand_from clean' -l dry-run -d 'show what would be deleted without removing anything'
 complete -c gji -n '__fish_seen_subcommand_from clean' -l json -d 'emit JSON on success or error instead of human-readable output'
 
-complete -c gji -n '__fish_seen_subcommand_from remove rm' -s f -l force -d 'bypass prompts, force-remove a dirty worktree, and force-delete an unmerged branch'
-complete -c gji -n '__fish_seen_subcommand_from remove rm' -l dry-run -d 'show what would be deleted without removing anything'
-complete -c gji -n '__fish_seen_subcommand_from remove rm' -l json -d 'emit JSON on success or error instead of human-readable output'
-complete -c gji -n '__fish_seen_subcommand_from remove rm' -a '(__gji_worktree_branches)' -d 'worktree branch'
-
 ${hookLines}
 
 complete -c gji -n '__fish_use_subcommand' -l json -d 'emit the repository hub as JSON'
 
-complete -c gji -n '__fish_seen_subcommand_from warp' -l print -d 'print the resolved worktree path without changing directory'
-complete -c gji -n '__fish_seen_subcommand_from warp' -l json -d 'emit JSON on success or error instead of human-readable output'
-
 complete -c gji -n '__fish_seen_subcommand_from config; and __gji_should_complete_config_action' -a 'get set unset' -d 'config action'
 ${configKeyLines}`;
 }
@@ -612,17 +600,11 @@ case "\${words[2]}" in
     _arguments '--compact[show only branch and path columns]' '--json[print active worktrees as JSON]'
     ;;
   clean)
-    _arguments '(-f --force)'{-f,--force}'[bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches]' '--stale[only target clean worktrees whose upstream is gone and branch is merged into the default branch]' '--dry-run[show what would be deleted without removing anything]' '--json[emit JSON on success or error instead of human-readable output]'
-    ;;
-  remove|rm)
-    _arguments '(-f --force)'{-f,--force}'[bypass prompts, force-remove a dirty worktree, and force-delete an unmerged branch]' '--dry-run[show what would be deleted without removing anything]' '--json[emit JSON on success or error instead of human-readable output]' '2:branch:->worktrees'
+    _arguments '(-f --force)'{-f,--force}'[bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches]' '--stale[only target clean worktrees whose upstream is gone and branch is merged into the default branch]' '*--path[only target worktrees under a directory or matching a path glob]:pattern:_files' '--dry-run[show what would be deleted without removing anything]' '--json[emit JSON on success or error instead of human-readable output]'
     ;;
   run-hook)
     _arguments "2:hook:(${hooks})"
     ;;
-  warp)
-    _arguments '--print[print the resolved worktree path without changing directory]' '--json[emit JSON on success or error instead of human-readable output]' '2:branch: '
-    ;;
   config)
     if (( CURRENT == 3 )); then
       _values 'config action' get set unset

package/dist/presentation/terminal/context-card.js

@@ -12,5 +12,5 @@ function formatState(info) {
     return `${info.status}${info.upstream.kind === "tracked" ? ` · ↑${info.upstream.ahead} ↓${info.upstream.behind}` : ""}`;
 }
 function formatLastCommit(info) {
-    return new Date(info.lastCommitTimestamp).toISOString();
+    return new Date(info.lastCommitTimestamp * 1000).toISOString();
 }