@indigoai-us/hq-cli 5.103.34 → 5.105.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [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
+
+- `hq agents terminal <agent>` — open an interactive terminal (real TTY over
+  SSM Session Manager) on a fleet agent's box using HQ identity alone: no SSH,
+  no local AWS credentials. Owner/admin only; auto-starts a dormant box and
+  waits for it to come online. `--forward <port>` (with optional
+  `--local-port`) tunnels a port on the box to your machine instead of opening
+  a shell. Requires the AWS `session-manager-plugin` installed locally.
+- `hq outposts terminal` — the same interactive terminal for personal
+  Outposts (via `@indigoai-us/hq-cloud`).
+
 ## [5.103.34] — 2026-08-30
 
 ## [5.103.33] — 2026-08-30

package/dist/commands/agents.d.ts

@@ -25,6 +25,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 import { Command } from "commander";
+import { type TerminalSessionPayload } from "@indigoai-us/hq-cloud/outposts/node";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export declare const VALID_EFFORTS: Set<string>;
@@ -201,6 +202,19 @@ export declare function startStopAgent(token: string, agentUid: string, action:
     uid: string;
     runtime?: Record<string, unknown>;
 }>;
+/** `POST /v1/agents/{uid}/terminal` wire shape: vended session or 202 starting. */
+export type AgentTerminalResponse = ({
+    ok: true;
+    uid: string;
+    mode: "shell" | "port-forward";
+} & TerminalSessionPayload) | {
+    ok: false;
+    step: "starting";
+    state: "starting-instance" | "awaiting-ssm";
+    retryAfterSeconds?: number;
+    uid: string;
+};
+export declare function openAgentTerminal(token: string, agentUid: string, body: Record<string, unknown>): Promise<AgentTerminalResponse>;
 export declare function retryAgent(token: string, agentUid: string): Promise<Record<string, unknown>>;
 export declare function deprovisionAgent(token: string, agentUid: string): Promise<{
     uid: string;

package/dist/commands/agents.js

@@ -30,6 +30,7 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
@@ -299,6 +300,14 @@ export async function startStopAgent(token, agentUid, action) {
         method: "POST",
     });
 }
+export async function openAgentTerminal(token, agentUid, body) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/terminal`,
+        method: "POST",
+        body,
+    });
+}
 export async function retryAgent(token, agentUid) {
     return agentsRequest({
         token,
@@ -540,6 +549,17 @@ function sleep(ms) {
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
+/** Parse an optional port flag: integer 1..65535 or exit(1) with the flag name. */
+function parsePortOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65_535) {
+        console.error(chalk.red(`${flag} must be an integer between 1 and 65535.`));
+        process.exit(1);
+    }
+    return n;
+}
 function fail(err) {
     // Let the CLI boundary render and offer the one shared Team checkout flow.
     // Local exits would otherwise prevent interactive plan-limit remediation.
@@ -578,6 +598,9 @@ export function registerAgentsCommand(program) {
         bySubcommand: {
             message: { capability: "agents:use", routeAvailable: false },
             thread: { capability: "agents:use", routeAvailable: false },
+            // Interactive terminals are for humans: hq-pro serves no keyed
+            // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
+            terminal: { capability: "agents:use", routeAvailable: false },
         },
     });
     // `--company` may live on the group or the subcommand; the subcommand value
@@ -667,6 +690,74 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("terminal <agent>")
+        .description("Open an interactive terminal on an agent's box — a real TTY over SSM Session Manager (no SSH, no local AWS credentials). " +
+        "Owner/admin only; requires the AWS session-manager-plugin installed locally. With --forward, tunnels a port on the box instead.")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .option("--forward <port>", "Forward this port on the box to your machine instead of opening a shell")
+        .option("--local-port <port>", "Local port for --forward (defaults to the forwarded port)")
+        .action(async function (agent, opts) {
+        try {
+            const forwardPort = parsePortOption(opts.forward, "--forward");
+            const localPort = parsePortOption(opts.localPort, "--local-port");
+            if (localPort !== undefined && forwardPort === undefined) {
+                console.error(chalk.red("--local-port requires --forward <port>."));
+                process.exit(1);
+            }
+            // A shell needs a real TTY on both ends; a port-forward does not.
+            if (forwardPort === undefined && !process.stdin.isTTY) {
+                console.error(chalk.red("hq agents terminal needs an interactive terminal (stdin is not a TTY)."));
+                process.exit(1);
+            }
+            const token = (await resolveVaultCredential()).token;
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+            const body = forwardPort !== undefined
+                ? {
+                    mode: "port-forward",
+                    portNumber: forwardPort,
+                    ...(localPort !== undefined ? { localPortNumber: localPort } : {}),
+                }
+                : { mode: "shell" };
+            // 202-retry loop: a dormant box is auto-started server-side; SSM
+            // registration after a cold start takes ~30-90s. Status lines go to
+            // stderr (once per state) so stdout stays the session's.
+            let lastState;
+            const session = await waitForTerminalSession(async () => {
+                const result = await openAgentTerminal(token, agentUid, body);
+                if (result.ok)
+                    return { kind: "ready", session: result };
+                return {
+                    kind: "starting",
+                    state: result.state,
+                    ...(result.retryAfterSeconds !== undefined
+                        ? { retryAfterSeconds: result.retryAfterSeconds }
+                        : {}),
+                };
+            }, {
+                onStatus: (state) => {
+                    if (state === lastState)
+                        return;
+                    lastState = state;
+                    console.error(chalk.dim(state === "starting-instance"
+                        ? `${agent}'s box is starting — waiting for it to come online (Ctrl-C to cancel)…`
+                        : `${agent}'s box is up — waiting for its agent to register (Ctrl-C to cancel)…`));
+                },
+            });
+            console.error(chalk.dim(forwardPort !== undefined
+                ? `Forwarding box port ${forwardPort} to localhost:${localPort ?? forwardPort} — Ctrl-C to end.`
+                : `Connected to ${agent}'s box — type 'exit' or Ctrl-D to leave.`));
+            process.exitCode = await launchSessionManagerPlugin(session);
+        }
+        catch (err) {
+            if (err instanceof SessionManagerPluginLaunchError ||
+                err instanceof TerminalSessionTimeoutError) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            fail(err);
+        }
+    });
     agents
         .command("provision <name>")
         .alias("new")

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.103.34",
+  "version": "5.105.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.95",
+    "@indigoai-us/hq-cloud": "~6.16.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",