@indigoai-us/hq-cli 5.104.0 → 5.105.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.105.0] — 2026-08-31
+
+### Changed
+
+- `hq reindex` now removes HQ-managed Git worktrees whose last Git-visible
+  activity is more than 12 hours old. It preserves the current worktree,
+  recently edited/deleted/renamed files, and the worktree's branch; ignored
+  dependency/build churn does not keep a worktree alive, and malformed or
+  uninspectable worktrees fail closed.
+
 ## [5.104.0] — 2026-08-31
 
 ### Added

package/dist/commands/reindex.d.ts

@@ -1,4 +1,10 @@
 import { Command } from 'commander';
+/**
+ * Remove inactive worktrees created by `hq worktree` without ever deleting
+ * directories directly. This runs on the hook path, so it uses a shallow
+ * layout scan and Git's status output rather than recursively walking trees.
+ */
+export declare function removeStaleHqWorktrees(hqRoot: string, now?: number, deadline?: number): void;
 /**
  * Check hook health without relying on lifecycle hooks. A fully disabled
  * configuration is repaired only after a successful reindex; partial and

package/dist/commands/reindex.js

@@ -33,6 +33,9 @@ import { findHqRoot } from '../utils/manifest.js';
 import { guardLargeFiles } from '../utils/large-file-guard.js';
 const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse'];
 const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh');
+const WORKTREE_STALE_AFTER_MS = 12 * 60 * 60 * 1_000;
+const WORKTREE_GIT_TIMEOUT_MS = 2_000;
+const WORKTREE_HOOK_SWEEP_BUDGET_MS = 5_000;
 /** Resolve the same root the repair/check commands must operate on. */
 function resolveHqRoot(repoRoot) {
     const root = repoRoot ?? findHqRoot();
@@ -43,6 +46,267 @@ function resolveHqRoot(repoRoot) {
         return path.resolve(root);
     }
 }
+function runGit(cwd, args, deadline = Number.POSITIVE_INFINITY, finishStartedCommand = false) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+        return undefined;
+    try {
+        const result = spawnSync('git', ['-C', cwd, ...args], {
+            encoding: 'utf8',
+            stdio: 'pipe',
+            ...(finishStartedCommand
+                ? {}
+                : { timeout: Math.max(1, Math.min(WORKTREE_GIT_TIMEOUT_MS, remainingMs)) }),
+            // `git status` may otherwise refresh its index while merely measuring
+            // activity, making this cleanup itself keep an old worktree alive.
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+        });
+        if (result.error)
+            return undefined;
+        return {
+            status: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function latestMtime(paths) {
+    let latest = 0;
+    for (const candidate of paths) {
+        try {
+            latest = Math.max(latest, fs.lstatSync(candidate).mtimeMs);
+        }
+        catch {
+            // A concurrently removed administrative file is not activity.
+        }
+    }
+    return latest;
+}
+function latestContentChange(paths) {
+    let latest = 0;
+    for (const candidate of paths) {
+        try {
+            const stat = fs.lstatSync(candidate);
+            latest = Math.max(latest, stat.mtimeMs, stat.ctimeMs);
+        }
+        catch {
+            // Deleted paths are represented by their surviving parent directory.
+        }
+    }
+    return latest;
+}
+function changedWorktreePaths(status) {
+    const entries = status.split('\0');
+    const paths = [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (!entry || entry.length < 4 || entry[2] !== ' ')
+            continue;
+        paths.push(entry.slice(3));
+        // With -z, rename/copy records carry the second path in the next NUL
+        // field. Check both because either end may have recent activity.
+        if ((entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C') && entries[index + 1]) {
+            paths.push(entries[index + 1]);
+            index += 1;
+        }
+    }
+    return paths;
+}
+function isDirectChild(parent, candidate) {
+    return path.dirname(candidate) === parent;
+}
+function currentProcessIsInside(worktree) {
+    let resolvedWorktree;
+    try {
+        resolvedWorktree = fs.realpathSync(worktree);
+    }
+    catch {
+        return true;
+    }
+    let currentCwd;
+    try {
+        currentCwd = process.cwd();
+    }
+    catch {
+        return true;
+    }
+    for (const processPath of [currentCwd, process.argv[1]]) {
+        if (!processPath)
+            continue;
+        try {
+            const resolvedProcessPath = fs.realpathSync(path.resolve(processPath));
+            if (resolvedProcessPath === resolvedWorktree ||
+                resolvedProcessPath.startsWith(`${resolvedWorktree}${path.sep}`)) {
+                return true;
+            }
+        }
+        catch {
+            // A missing argv path says nothing about whether this worktree is active.
+        }
+    }
+    return false;
+}
+function managedWorktreeCandidates(hqRoot) {
+    const worktreesRoot = path.join(hqRoot, 'workspace', 'worktrees');
+    let repositories;
+    try {
+        repositories = fs.readdirSync(worktreesRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const repository of repositories) {
+        if (!repository.isDirectory())
+            continue;
+        const repositoryRoot = path.join(worktreesRoot, repository.name);
+        let worktrees;
+        try {
+            worktrees = fs.readdirSync(repositoryRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const worktree of worktrees) {
+            if (!worktree.isDirectory())
+                continue;
+            const candidate = path.join(repositoryRoot, worktree.name);
+            // Keep the cleanup constrained to the layout that `hq worktree` owns.
+            if (isDirectChild(repositoryRoot, candidate))
+                candidates.push(candidate);
+        }
+    }
+    return candidates;
+}
+function linkedWorktreeGitDir(worktree, deadline = Number.POSITIVE_INFINITY) {
+    const gitFile = path.join(worktree, '.git');
+    try {
+        if (!fs.lstatSync(gitFile).isFile())
+            return undefined;
+        const match = /^gitdir:\s*(.+)\s*$/i.exec(fs.readFileSync(gitFile, 'utf8'));
+        if (!match)
+            return undefined;
+        const gitDir = path.resolve(worktree, match[1]);
+        if (!fs.statSync(gitDir).isDirectory())
+            return undefined;
+        // A submodule checkout also has a .git *file*. A linked worktree is
+        // distinguished by its per-worktree administrative commondir file.
+        if (!fs.lstatSync(path.join(gitDir, 'commondir')).isFile())
+            return undefined;
+        const topLevel = runGit(worktree, ['rev-parse', '--show-toplevel'], deadline);
+        if (topLevel?.status !== 0 || !topLevel.stdout.trim())
+            return undefined;
+        return fs.realpathSync(topLevel.stdout.trim()) === fs.realpathSync(worktree) ? gitDir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function nearestExistingAncestor(candidate, worktree) {
+    let current = candidate;
+    while (current !== worktree && current.startsWith(`${worktree}${path.sep}`)) {
+        if (fs.existsSync(current))
+            return current;
+        current = path.dirname(current);
+    }
+    return worktree;
+}
+function hasRecentWorktreeActivity(worktree, gitDir, cutoff, deadline = Number.POSITIVE_INFINITY) {
+    const gitFile = path.join(worktree, '.git');
+    const administrativeActivity = latestMtime([
+        worktree,
+        gitFile,
+        gitDir,
+        path.join(gitDir, 'HEAD'),
+        path.join(gitDir, 'index'),
+        path.join(gitDir, 'logs', 'HEAD'),
+    ]);
+    if (administrativeActivity >= cutoff)
+        return true;
+    // Ask Git for only changed paths. `all` is necessary to see an untracked
+    // file inside an untracked directory; ignored dependency/build trees remain
+    // excluded, and we stat only the paths Git reports instead of walking trees.
+    const status = runGit(worktree, [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--untracked-files=all',
+        '--ignored=no',
+    ], deadline);
+    // A repository we cannot inspect is safer to retain than force-remove.
+    if (status?.status !== 0)
+        return true;
+    // Node replaces invalid UTF-8 bytes while decoding stdout. The resulting
+    // path is no longer safe to stat, so retain the worktree fail-closed.
+    if (status.stdout.includes('\uFFFD'))
+        return true;
+    const changedPaths = changedWorktreePaths(status.stdout);
+    // Git produced a record we do not understand. Fail closed instead of
+    // treating an unparsed dirty worktree as clean.
+    if (status.stdout.length > 0 && changedPaths.length === 0)
+        return true;
+    for (const relativePath of changedPaths) {
+        const candidate = path.resolve(worktree, relativePath);
+        if (candidate !== worktree && !candidate.startsWith(`${worktree}${path.sep}`))
+            continue;
+        try {
+            // Parent Git reports submodules and embedded repositories as aggregate
+            // directory paths. Descendant edits do not touch that directory's own
+            // timestamps, so retain these dirty aggregates rather than recurse into
+            // an unbounded tree on every reindex hook.
+            if (fs.lstatSync(candidate).isDirectory())
+                return true;
+        }
+        catch {
+            // Missing paths are deletions and are handled through their ancestors.
+        }
+    }
+    const dirtyPaths = changedPaths.flatMap((relativePath) => {
+        const candidate = path.resolve(worktree, relativePath);
+        if (candidate !== worktree && !candidate.startsWith(`${worktree}${path.sep}`))
+            return [];
+        return [candidate, nearestExistingAncestor(path.dirname(candidate), worktree)];
+    });
+    return latestContentChange(dirtyPaths) >= cutoff;
+}
+/**
+ * Remove inactive worktrees created by `hq worktree` without ever deleting
+ * directories directly. This runs on the hook path, so it uses a shallow
+ * layout scan and Git's status output rather than recursively walking trees.
+ */
+export function removeStaleHqWorktrees(hqRoot, now = Date.now(), deadline = Number.POSITIVE_INFINITY) {
+    if (!isHqRoot(hqRoot))
+        return;
+    const cutoff = now - WORKTREE_STALE_AFTER_MS;
+    for (const worktree of managedWorktreeCandidates(hqRoot)) {
+        if (Date.now() >= deadline)
+            break;
+        if (currentProcessIsInside(worktree))
+            continue;
+        const gitDir = linkedWorktreeGitDir(worktree, deadline);
+        if (!gitDir || hasRecentWorktreeActivity(worktree, gitDir, cutoff, deadline))
+            continue;
+        // Narrow the destructive TOCTOU window: re-resolve the linked-worktree
+        // identity and re-measure activity immediately before asking Git to remove
+        // it. Git remains the only component that deletes the directory.
+        const confirmedGitDir = linkedWorktreeGitDir(worktree, deadline);
+        if (!confirmedGitDir || hasRecentWorktreeActivity(worktree, confirmedGitDir, cutoff, deadline))
+            continue;
+        // Recursive removal is not transactional. Only start it inside the sweep
+        // budget, then let Git finish so a timeout cannot leave a registered,
+        // partially deleted worktree behind.
+        const removal = runGit(worktree, ['worktree', 'remove', '--force', worktree], deadline, true);
+        if (removal?.status === 0) {
+            console.log(`reindex: removed stale worktree ${worktree} (branch preserved; stale uncommitted files are not recoverable)`);
+            continue;
+        }
+        const reason = removal?.stderr.trim() || removal?.stdout.trim() || 'Git could not remove it';
+        console.warn(`reindex: could not remove stale worktree ${worktree}: ${reason}`);
+    }
+}
 function isHqRoot(hqRoot) {
     return (fs.existsSync(path.join(hqRoot, 'companies')) &&
         (fs.existsSync(path.join(hqRoot, '.claude')) ||
@@ -254,8 +518,10 @@ export function registerReindexCommand(program) {
         if (lockTimeoutSec !== undefined && process.env.HQ_OP_LOCK_TIMEOUT === undefined) {
             process.env.HQ_OP_LOCK_TIMEOUT = String(lockTimeoutSec);
         }
-        const { status } = reindex({ repoRoot: opts.repoRoot });
         const hqRoot = resolveHqRoot(opts.repoRoot);
+        const sweepStartedAt = Date.now();
+        removeStaleHqWorktrees(hqRoot, sweepStartedAt, opts.fromHook ? sweepStartedAt + WORKTREE_HOOK_SWEEP_BUDGET_MS : Number.POSITIVE_INFINITY);
+        const { status } = reindex({ repoRoot: opts.repoRoot });
         repairExtremeHookDrift(hqRoot, status === 0);
         if (status === 0)
             await trustHqRuntimeHooks(hqRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.104.0",
+  "version": "5.105.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {