@indigoai-us/hq-cli 5.119.12 → 5.119.15

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.119.15] — 2026-09-18
+
+### Fixed
+
+- `hq people resolve <name>` now reports ambiguity when the name matches more
+  than one person instead of selecting the first match.
+
+## [5.119.13] — 2026-09-18
+
+### Added
+
+- `hq version` (and `hq --version`) print the installed HQ version, the CLI
+  version labelled as CLI, and the latest hq-core release. If a newer HQ is
+  out it says to run `/update-hq`; if the lookup cannot reach the network it
+  says so instead of going quiet. `hq version --json` prints the same payload.
+
+### Fixed
+
+- `hq core rebuild-index company-knowledge` no longer silently replaces a
+  hand-written company knowledge INDEX. If the file is not the last generated
+  output, the command refuses, prints a short diff, and asks for `--accept`.
+  `<!-- hq:keep -->` opts the whole file out; `<!-- hq:keep -->` … `<!-- /hq:keep -->`
+  fences are kept while the table regenerates. Subdirectory README headings
+  are projected into the description column so the generated index is usable
+  without hand edits.
+
 ## [5.119.12] — 2026-09-18
 
 ### Fixed

package/assets/scaffold/core/scripts/rebuild-company-knowledge-index.sh

@@ -8,7 +8,7 @@
 #   - .md files → first `#` heading (stripped)
 #   - .yaml files → `description:` field if present
 #   - .json files → `description` field if present
-#   - directories → "{N} item(s)"
+#   - directories → README.md `#` heading plus "{N} item(s)", or "{N} item(s)"
 #
 # Most company knowledge dirs are embedded git repos (160000 gitlinks). The
 # generated INDEX.md lives inside the inner repo; HQ git won't track its
@@ -42,7 +42,15 @@ describe_item() {
   if [[ -d "$path" ]]; then
     local n
     n=$(find "$path" -mindepth 1 -maxdepth 1 ! -name '.*' 2>/dev/null | wc -l | tr -d ' ')
-    echo "${n} item(s)"
+    local h=""
+    if [[ -f "$path/README.md" ]]; then
+      h=$(awk '/^# / { sub(/^# +/, ""); print; exit }' "$path/README.md" 2>/dev/null || true)
+    fi
+    if [[ -n "$h" ]]; then
+      echo "${h} (${n} item(s))"
+    else
+      echo "${n} item(s)"
+    fi
     return
   fi
   case "$name" in
@@ -70,6 +78,26 @@ describe_item() {
   esac
 }
 
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+stamp_generated() {
+  local tmp="$1"
+  local out="$2"
+  local norm
+  norm=$(mktemp)
+  sed 's/^> Auto-generated. Updated: [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$/> Auto-generated. Updated: <date>/' "$tmp" > "$norm"
+  local hash
+  hash=$(sha256_file "$norm")
+  rm -f "$norm"
+  awk -v h="$hash" '{print} /^> Auto-generated. Updated: / {print "<!-- hq-generated-sha256: " h " -->"}' "$tmp" > "$out"
+}
+
 write_knowledge_index() {
   local co="$1"
   local kdir="companies/${co}/knowledge"
@@ -77,6 +105,8 @@ write_knowledge_index() {
   local out="${kdir}/INDEX.md"
   local title
   title="$(titleize "$co") Knowledge"
+  local tmp
+  tmp=$(mktemp)
 
   {
     echo "# ${title}"
@@ -108,7 +138,10 @@ write_knowledge_index() {
         find -L "$kdir" -mindepth 1 -maxdepth 1 -type f 2>/dev/null | sort
       }
     )
-  } > "$out"
+  } > "$tmp"
+
+  stamp_generated "$tmp" "$out"
+  rm -f "$tmp"
 
   echo "rebuild-company-knowledge-index: wrote ${out}" >&2
 }

package/dist/command-catalog.generated.d.ts

@@ -805,6 +805,18 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly description: "Also report this company's workspace plan state (Starter lock)";
     }];
     readonly subcommands: readonly [];
+}, {
+    readonly name: "version";
+    readonly description: "Show HQ, CLI, and latest hq-core versions";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly usage: "[options]";
+    readonly arguments: readonly [];
+    readonly options: readonly [{
+        readonly flags: "--json";
+        readonly description: "Output the same payload as JSON";
+    }];
+    readonly subcommands: readonly [];
 }, {
     readonly name: "auth";
     readonly description: "Manage the local HQ Cognito session";

package/dist/command-catalog.generated.js

@@ -1029,6 +1029,21 @@ export const COMMAND_CATALOG = [
         ],
         "subcommands": []
     },
+    {
+        "name": "version",
+        "description": "Show HQ, CLI, and latest hq-core versions",
+        "aliases": [],
+        "hidden": false,
+        "usage": "[options]",
+        "arguments": [],
+        "options": [
+            {
+                "flags": "--json",
+                "description": "Output the same payload as JSON"
+            }
+        ],
+        "subcommands": []
+    },
     {
         "name": "auth",
         "description": "Manage the local HQ Cognito session",

package/dist/command-registration-plan.d.ts

@@ -171,6 +171,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/whoami.js";
     readonly exportName: "registerWhoamiCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "version";
+    readonly parent: "program";
+    readonly module: "./commands/version.js";
+    readonly exportName: "registerVersionCommand";
 }, {
     readonly type: "registrar";
     readonly root: "auth";

package/dist/command-registration-plan.js

@@ -31,6 +31,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "login", parent: "program", module: "./commands/login.js", exportName: "registerLoginCommand" },
     { type: "registrar", root: "logout", parent: "program", module: "./commands/logout.js", exportName: "registerLogoutCommand" },
     { type: "registrar", root: "whoami", parent: "program", module: "./commands/whoami.js", exportName: "registerWhoamiCommand" },
+    { type: "registrar", root: "version", parent: "program", module: "./commands/version.js", exportName: "registerVersionCommand" },
     { type: "registrar", root: "auth", parent: "program", module: "./commands/auth.js", exportName: "registerAuthCommands" },
     { type: "registrar", root: "secrets", parent: "program", module: "./commands/secrets.js", exportName: "registerSecretsCommand" },
     { type: "registrar", root: "db", parent: "program", module: "./commands/db.js", exportName: "registerDbCommand" },

package/dist/commands/core.js

@@ -408,7 +408,19 @@ export function registerCoreCommands(program) {
         const scope = core.opts();
         const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
         const operands = cmd.args.length > 0 ? cmd.args : args;
-        renderIndexTarget(entry.renderer, { root: hqRoot, log: (message) => process.stderr.write(`${message}\n`) }, operands.slice(1));
+        const passthrough = operands.slice(1);
+        const force = passthrough.includes("--accept");
+        const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
+        const refused = [];
+        renderIndexTarget(entry.renderer, {
+            root: hqRoot,
+            log: (message) => process.stderr.write(`${message}\n`),
+            force,
+            refused,
+        }, rendererArgs);
+        if (refused.length > 0) {
+            throw expectedUserError(`rebuild-index: refused to overwrite ${refused.length} hand-edited INDEX.md file(s). Re-run with --accept to overwrite.`);
+        }
     });
     for (const entry of SCAFFOLD_COMMANDS) {
         core

package/dist/commands/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * hq version — labelled HQ vs CLI vs latest hq-core.
+ *
+ * `hq --version` is intercepted on the fast path in index.ts and prints the
+ * same report. This registrar exists so `hq --help` lists the command and so
+ * `hq version --json` still works if the fast path is skipped.
+ */
+import { Command } from "commander";
+export declare function registerVersionCommand(program: Command): void;
+//# sourceMappingURL=version.d.ts.map

package/dist/commands/version.js

@@ -0,0 +1,11 @@
+import { runVersionCommand } from "../utils/version-report.js";
+export function registerVersionCommand(program) {
+    program
+        .command("version")
+        .description("Show HQ, CLI, and latest hq-core versions")
+        .option("--json", "Output the same payload as JSON")
+        .action(async () => {
+        await runVersionCommand(process.argv);
+    });
+}
+//# sourceMappingURL=version.js.map

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./commands/scaffold-fast.js";
-declare function isVersionRequest(argv: readonly string[]): boolean;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
 };
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,17 +3,13 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
-import { CLI_VERSION } from "./cli-version.js";
+import { isVersionRequest } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
 import { isFastCoreRequest } from "./commands/scaffold-fast.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
-function isVersionRequest(argv) {
-    const args = argv.slice(2);
-    return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
-}
 // Install BEFORE any dispatch so a floated rejection on ANY path (the command
 // graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
 // onUnhandledRejection integration defaults to 'warn' — it captures but does
@@ -22,7 +18,9 @@ function isVersionRequest(argv) {
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
 if (isVersionRequest(process.argv)) {
-    process.stdout.write(`${CLI_VERSION}\n`);
+    // Same report as `hq version`: HQ, CLI, latest hq-core. Lazy so --version
+    // still skips the command graph.
+    void import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
 }
 else if (isFastCoreRequest(process.argv)) {
     // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)

package/dist/lib/index-render/company-knowledge.js

@@ -1,11 +1,13 @@
-import { basename, date, immediateEntries, isHidden, log, readJson, readText, sanitize, titleize, truncate, write } from "./shared.js";
+import * as fs from "fs";
+import { at, basename, date, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, heading, immediateEntries, isHidden, log, looksAutoGenerated, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
 function describe(item) {
     const name = basename(item);
-    // `find -L` follows a symlink only for its direct target. fs.statSync mirrors that.
     try {
-        if ((awaitStat(item)).isDirectory()) {
-            const fs = requireFs();
-            return `${fs.readdirSync(item).filter((entry) => !entry.startsWith(".")).length} item(s)`;
+        if (fs.statSync(item).isDirectory()) {
+            const entries = fs.readdirSync(item).filter((entry) => !entry.startsWith("."));
+            const n = entries.length;
+            const summary = heading(`${item}/README.md`);
+            return summary ? `${summary} (${n} item(s))` : `${n} item(s)`;
         }
     }
     catch {
@@ -23,13 +25,55 @@ function describe(item) {
     }
     return name;
 }
-// Avoid a heavier tree abstraction here: the source script's `find -L` is
-// specifically about knowledge gitlinks, so stat is intentionally local.
-function requireFs() { return fsModule; }
-import * as fsModule from "fs";
-function awaitStat(file) { return fsModule.statSync(file); }
+function briefDiff(existing, next) {
+    const oldLines = existing.split("\n");
+    const newLines = next.split("\n");
+    const lines = ["--- existing", "+++ generated"];
+    const limit = Math.max(oldLines.length, newLines.length);
+    let shown = 0;
+    for (let i = 0; i < limit && shown < 20; i += 1) {
+        const a = oldLines[i];
+        const b = newLines[i];
+        if (a === b)
+            continue;
+        if (a !== undefined)
+            lines.push(`- ${a}`);
+        if (b !== undefined)
+            lines.push(`+ ${b}`);
+        shown += 1;
+    }
+    if (shown === 20)
+        lines.push("…");
+    return lines.join("\n");
+}
+function composeIndex(raw, existing) {
+    const stamped = stampGenerated(raw);
+    const fences = existing ? extractKeepFences(existing) : "";
+    if (!fences)
+        return stamped;
+    return `${stamped.replace(/\n+$/, "\n")}\n${fences}\n`;
+}
+function shouldOverwrite(context, existing, next) {
+    if (!existing)
+        return "write";
+    if (context.force)
+        return "write";
+    if (hasUnclosedKeepMarker(existing))
+        return "skip";
+    const stored = generatedStamp(existing);
+    if (stored && stored === generatedFingerprint(existing))
+        return "write";
+    if (stored)
+        return "refuse";
+    if (looksAutoGenerated(existing))
+        return "write";
+    if (generatedFingerprint(existing) === generatedFingerprint(next))
+        return "write";
+    return "refuse";
+}
 export function renderCompanyKnowledge(context) {
     const written = [];
+    let refused = 0;
     for (const companyDir of immediateEntries(context.root, "companies", "dir")) {
         const company = basename(companyDir);
         if (company.startsWith("_") || isHidden(company))
@@ -37,24 +81,24 @@ export function renderCompanyKnowledge(context) {
         const relative = `companies/${company}/knowledge`;
         const knowledge = `${companyDir}/knowledge`;
         try {
-            if (!fsModule.statSync(knowledge).isDirectory())
+            if (!fs.statSync(knowledge).isDirectory())
                 continue;
         }
         catch {
             continue;
         }
-        const entries = fsModule.readdirSync(knowledge).flatMap((name) => {
+        const entries = fs.readdirSync(knowledge).flatMap((name) => {
             const item = `${knowledge}/${name}`;
             try {
-                return fsModule.statSync(item).isDirectory() ? [item] : [];
+                return fs.statSync(item).isDirectory() ? [item] : [];
             }
             catch {
                 return [];
             }
-        }).sort().concat(fsModule.readdirSync(knowledge).flatMap((name) => {
+        }).sort().concat(fs.readdirSync(knowledge).flatMap((name) => {
             const item = `${knowledge}/${name}`;
             try {
-                return fsModule.statSync(item).isFile() ? [item] : [];
+                return fs.statSync(item).isFile() ? [item] : [];
             }
             catch {
                 return [];
@@ -68,18 +112,37 @@ export function renderCompanyKnowledge(context) {
             const value = truncate(sanitize(describe(item)), 100) || "—";
             let directory = false;
             try {
-                directory = fsModule.statSync(item).isDirectory();
+                directory = fs.statSync(item).isDirectory();
             }
             catch { /* omitted */ }
             lines.push(`| \`${name}${directory ? "/" : ""}\` | ${value} |`);
         }
         lines.push("");
         const output = `${relative}/INDEX.md`;
-        write(context, output, lines.join("\n"));
+        const raw = lines.join("\n");
+        const existing = readText(at(context.root, output));
+        const next = composeIndex(raw, existing);
+        const decision = shouldOverwrite(context, existing, next);
+        if (decision === "skip") {
+            log(context, `rebuild-company-knowledge-index: skipped ${output} (<!-- hq:keep -->)`);
+            continue;
+        }
+        if (decision === "refuse") {
+            refused += 1;
+            context.refused?.push(output);
+            log(context, `rebuild-company-knowledge-index: refused ${output} (hand-written or edited; differs from last generated output)`);
+            log(context, briefDiff(existing ?? "", next));
+            log(context, "Re-run with --accept to overwrite, or add <!-- hq:keep --> to opt out.");
+            continue;
+        }
+        write(context, output, next);
         written.push(output);
         log(context, `rebuild-company-knowledge-index: wrote ${output}`);
     }
     log(context, `rebuild-company-knowledge-index: regenerated ${written.length} knowledge INDEX.md file(s)`);
+    if (refused > 0) {
+        log(context, `rebuild-company-knowledge-index: refused to overwrite ${refused} hand-edited INDEX.md file(s)`);
+    }
     return { written };
 }
 //# sourceMappingURL=company-knowledge.js.map

package/dist/lib/index-render/shared.d.ts

@@ -3,6 +3,10 @@ export type RenderContext = {
     now?: Date;
     log?: (message: string) => void;
     output?: (message: string) => void;
+    /** Overwrite hand-edited INDEX.md files (`rebuild-index … --accept`). */
+    force?: boolean;
+    /** Relative paths that were not overwritten because they differ from last generated output. */
+    refused?: string[];
 };
 export type RenderResult = {
     written: string[];
@@ -26,6 +30,14 @@ export declare function timestamp(now?: Date): string;
 /** Write via a same-directory temporary file, then atomically replace the destination. */
 export declare function atomicWrite(file: string, content: string): void;
 export declare function write(context: RenderContext, relative: string, content: string): string;
+/** Drop keep fences, the generated stamp, and the rolling date so two generated bodies can be compared. */
+export declare function generatedFingerprint(content: string): string;
+/** Insert a content stamp after the Auto-generated line. Idempotent. */
+export declare function stampGenerated(content: string): string;
+export declare function extractKeepFences(content: string): string;
+export declare function hasUnclosedKeepMarker(content: string): boolean;
+export declare function looksAutoGenerated(content: string): boolean;
+export declare function generatedStamp(content: string): string | undefined;
 export declare function log(context: RenderContext, message: string): void;
 export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string): string;
 export declare function basename(file: string): string;

package/dist/lib/index-render/shared.js

@@ -1,3 +1,4 @@
+import { createHash } from "crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -96,6 +97,42 @@ export function write(context, relative, content) {
     atomicWrite(at(context.root, relative), content);
     return relative;
 }
+const GENERATED_DATE_LINE = /^> Auto-generated\. Updated: \d{4}-\d{2}-\d{2}$/m;
+const GENERATED_STAMP_LINE = /^<!-- hq-generated-sha256: [a-f0-9]{64} -->\n?/m;
+function keepFencePattern() {
+    return /<!-- hq:keep -->\r?\n?[\s\S]*?<!-- \/hq:keep -->/g;
+}
+/** Drop keep fences, the generated stamp, and the rolling date so two generated bodies can be compared. */
+export function generatedFingerprint(content) {
+    const normalized = content
+        .replace(keepFencePattern(), "")
+        .replace(GENERATED_STAMP_LINE, "")
+        .replace(GENERATED_DATE_LINE, "> Auto-generated. Updated: <date>")
+        .replace(/\n+$/, "\n");
+    return createHash("sha256").update(normalized, "utf8").digest("hex");
+}
+/** Insert a content stamp after the Auto-generated line. Idempotent. */
+export function stampGenerated(content) {
+    const unstamped = content.replace(GENERATED_STAMP_LINE, "");
+    const hash = generatedFingerprint(unstamped);
+    return unstamped.replace(GENERATED_DATE_LINE, (line) => `${line}\n<!-- hq-generated-sha256: ${hash} -->`);
+}
+export function extractKeepFences(content) {
+    return (content.match(keepFencePattern()) ?? []).join("\n\n");
+}
+export function hasUnclosedKeepMarker(content) {
+    const opens = content.match(/<!-- hq:keep -->/g)?.length ?? 0;
+    if (opens === 0)
+        return false;
+    const closes = content.match(/<!-- \/hq:keep -->/g)?.length ?? 0;
+    return opens > closes;
+}
+export function looksAutoGenerated(content) {
+    return GENERATED_DATE_LINE.test(content);
+}
+export function generatedStamp(content) {
+    return content.match(/^<!-- hq-generated-sha256: ([a-f0-9]{64}) -->/m)?.[1];
+}
 export function log(context, message) { context.log?.(message); }
 export function projectStatus(root, project, prdPath, fallback) {
     const state = readJson(at(root, `workspace/orchestrator/${project}/state.json`));

package/dist/utils/people.d.ts

@@ -86,17 +86,10 @@ export type ResolveResult = {
 /**
  * Resolve a person NAME to their email, built on top of {@link searchPeople}.
  *
- * Match precedence (narrowest first) so a precise query isn't drowned out by
- * looser substring hits:
- *   1. exact name match (case-insensitive, trimmed)
- *   2. exact folder-slug match
- *   3. substring search over name/email/slug
- *
- * The first tier that yields any match decides the result:
- *   - exactly one match with an email  → `found`
- *   - exactly one match, no email      → `no_email`
- *   - more than one match              → `ambiguous` (caller disambiguates)
- *   - no match in any tier             → `not_found`
+ * Resolution is deliberately stricter than a convenience ranking. Every
+ * case-insensitive name, email, or slug substring match is a candidate; an
+ * exact name never silently selects one person when the query also names
+ * other people. The caller must disambiguate any multi-person result.
  */
 export declare function resolveNameToEmail(people: PersonRecord[], name: string): ResolveResult;
 //# sourceMappingURL=people.d.ts.map

package/dist/utils/people.js

@@ -122,31 +122,16 @@ export function searchPeople(people, keyword) {
 /**
  * Resolve a person NAME to their email, built on top of {@link searchPeople}.
  *
- * Match precedence (narrowest first) so a precise query isn't drowned out by
- * looser substring hits:
- *   1. exact name match (case-insensitive, trimmed)
- *   2. exact folder-slug match
- *   3. substring search over name/email/slug
- *
- * The first tier that yields any match decides the result:
- *   - exactly one match with an email  → `found`
- *   - exactly one match, no email      → `no_email`
- *   - more than one match              → `ambiguous` (caller disambiguates)
- *   - no match in any tier             → `not_found`
+ * Resolution is deliberately stricter than a convenience ranking. Every
+ * case-insensitive name, email, or slug substring match is a candidate; an
+ * exact name never silently selects one person when the query also names
+ * other people. The caller must disambiguate any multi-person result.
  */
 export function resolveNameToEmail(people, name) {
     const query = name.trim();
     if (!query)
         return { status: "not_found" };
-    const lowered = query.toLowerCase();
-    const exactName = people.filter((p) => p.name.toLowerCase() === lowered);
-    const exactSlug = people.filter((p) => p.slug.toLowerCase() === lowered);
-    const substring = searchPeople(people, query);
-    const matches = exactName.length > 0
-        ? exactName
-        : exactSlug.length > 0
-            ? exactSlug
-            : substring;
+    const matches = searchPeople(people, query);
     if (matches.length === 0)
         return { status: "not_found" };
     if (matches.length > 1)

package/dist/utils/version-gate.d.ts

@@ -347,6 +347,14 @@ declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?
  * see what the USER's next invocation resolves.
  */
 export declare function resolveHqOnPath(): string | null;
+/**
+ * Pull the CLI version out of `hq --version` output.
+ *
+ * Older builds printed a bare semver. Current builds print a labelled report
+ * (`HQ …` / `CLI 5.119.12` / …). Convergence must accept both, otherwise a
+ * successful install looks like a PATH shadow.
+ */
+export declare function parseReportedCliVersion(stdout: string): string | null;
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export declare function probeCliVersion(bin: string): string | null;
 /**

package/dist/utils/version-gate.js

@@ -810,6 +810,28 @@ export function resolveHqOnPath() {
         return null;
     }
 }
+/**
+ * Pull the CLI version out of `hq --version` output.
+ *
+ * Older builds printed a bare semver. Current builds print a labelled report
+ * (`HQ …` / `CLI 5.119.12` / …). Convergence must accept both, otherwise a
+ * successful install looks like a PATH shadow.
+ */
+export function parseReportedCliVersion(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    const labelled = /^CLI\s+(\S+)/m.exec(text);
+    if (labelled)
+        return labelled[1];
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 1)
+        return lines[0];
+    return null;
+}
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export function probeCliVersion(bin) {
     try {
@@ -819,8 +841,7 @@ export function probeCliVersion(bin) {
         });
         if (result.error || result.status !== 0)
             return null;
-        const out = (result.stdout ?? "").trim();
-        return out || null;
+        return parseReportedCliVersion(result.stdout ?? "");
     }
     catch {
         return null;
@@ -1140,7 +1161,12 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
  * force-upgraded.
  */
 export function shouldSkipGate(argv) {
-    return argv.some((a) => a === "--version" || a === "-V" || a === "-v" || a === "--help" || a === "-h");
+    return argv.some((a) => a === "--version" ||
+        a === "-V" ||
+        a === "-v" ||
+        a === "--help" ||
+        a === "-h" ||
+        a === "version");
 }
 export const __test__ = {
     CLIENT_ID,

package/dist/utils/version-report.d.ts

@@ -0,0 +1,27 @@
+export declare const HQ_CORE_LATEST_URL = "https://api.github.com/repos/indigoai-us/hq-core/releases/latest";
+export declare const LATEST_FETCH_TIMEOUT_MS = 3000;
+export type LatestLookup = "ok" | "network-error";
+export interface VersionReport {
+    hq: string | null;
+    cli: string;
+    latestHqCore: string | null;
+    updateAvailable: boolean;
+    latestLookup: LatestLookup;
+}
+export interface VersionReportDeps {
+    cliVersion?: string;
+    hqRoot?: string;
+    readHq?: (hqRoot: string) => string | null;
+    fetchLatest?: () => Promise<string | null>;
+}
+export declare function normalizeHqCoreTag(tag: string): string | null;
+export declare function fetchLatestHqCoreRelease(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+export declare function collectVersionReport(deps?: VersionReportDeps): Promise<VersionReport>;
+export declare function formatVersionReport(report: VersionReport): string;
+export declare function versionReportJson(report: VersionReport): string;
+export { isVersionRequest } from "../version-request.js";
+export declare function wantsJson(argv: readonly string[]): boolean;
+export declare function runVersionCommand(argv?: readonly string[], deps?: VersionReportDeps, stdout?: {
+    write(chunk: string): unknown;
+}): Promise<void>;
+//# sourceMappingURL=version-report.d.ts.map

package/dist/utils/version-report.js

@@ -0,0 +1,97 @@
+/**
+ * The payload behind `hq version` / labelled `hq --version`.
+ *
+ * Prints the installed HQ scaffold version, the CLI version (labelled so it
+ * cannot be confused with HQ), and the latest hq-core GitHub release. A
+ * network failure is an explicit line, never a silent omission.
+ */
+import semver from "semver";
+import { CLI_VERSION } from "../cli-version.js";
+import { findHqRoot } from "./manifest.js";
+import { readHqVersion } from "./pack-contributions.js";
+export const HQ_CORE_LATEST_URL = "https://api.github.com/repos/indigoai-us/hq-core/releases/latest";
+export const LATEST_FETCH_TIMEOUT_MS = 3_000;
+export function normalizeHqCoreTag(tag) {
+    const version = tag.trim().replace(/^v/i, "");
+    return semver.valid(version) ? version : null;
+}
+export async function fetchLatestHqCoreRelease(fetchImpl = fetch, timeoutMs = LATEST_FETCH_TIMEOUT_MS) {
+    try {
+        const res = await fetchImpl(HQ_CORE_LATEST_URL, {
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "hq-cli-version",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (typeof body.tag_name !== "string")
+            return null;
+        return normalizeHqCoreTag(body.tag_name);
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectVersionReport(deps = {}) {
+    const cli = deps.cliVersion ?? CLI_VERSION;
+    let hq;
+    try {
+        const hqRoot = deps.hqRoot ?? findHqRoot();
+        hq = (deps.readHq ?? readHqVersion)(hqRoot);
+    }
+    catch {
+        hq = null;
+    }
+    const latestHqCore = deps.fetchLatest
+        ? await deps.fetchLatest()
+        : await fetchLatestHqCoreRelease();
+    const latestLookup = latestHqCore ? "ok" : "network-error";
+    const hqValid = hq ? semver.valid(hq) : null;
+    const latestValid = latestHqCore ? semver.valid(latestHqCore) : null;
+    const updateAvailable = Boolean(hqValid && latestValid && semver.gt(latestValid, hqValid));
+    return { hq, cli, latestHqCore, updateAvailable, latestLookup };
+}
+export function formatVersionReport(report) {
+    const lines = [
+        `HQ ${report.hq ?? "unknown"}`,
+        `CLI ${report.cli}`,
+    ];
+    if (report.latestLookup === "network-error") {
+        lines.push("Latest hq-core unknown");
+        lines.push("could not reach the network to check for a newer HQ");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`Latest hq-core ${report.latestHqCore}`);
+    if (!report.hq) {
+        lines.push("installed HQ version unknown, cannot tell if an update is available");
+    }
+    else if (report.updateAvailable) {
+        lines.push("update available, run /update-hq");
+    }
+    else {
+        lines.push("up to date");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function versionReportJson(report) {
+    return `${JSON.stringify({
+        hq: report.hq,
+        cli: report.cli,
+        latestHqCore: report.latestHqCore,
+        updateAvailable: report.updateAvailable,
+        latestLookup: report.latestLookup,
+    }, null, 2)}\n`;
+}
+export { isVersionRequest } from "../version-request.js";
+export function wantsJson(argv) {
+    return argv.includes("--json");
+}
+export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout) {
+    const report = await collectVersionReport(deps);
+    stdout.write(wantsJson(argv) ? versionReportJson(report) : formatVersionReport(report));
+}
+//# sourceMappingURL=version-report.js.map

package/dist/version-request.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Argv predicate for the version fast path. Keep this file dependency-free so
+ * every `hq` invocation can classify `--version` / `version` without loading
+ * yaml, semver, or the command graph.
+ */
+export declare function isVersionRequest(argv: readonly string[]): boolean;
+//# sourceMappingURL=version-request.d.ts.map

package/dist/version-request.js

@@ -0,0 +1,22 @@
+/**
+ * Argv predicate for the version fast path. Keep this file dependency-free so
+ * every `hq` invocation can classify `--version` / `version` without loading
+ * yaml, semver, or the command graph.
+ */
+export function isVersionRequest(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return false;
+    if (args.includes("--help") || args.includes("-h"))
+        return false;
+    const positionals = args.filter((a) => !a.startsWith("-"));
+    const flags = args.filter((a) => a.startsWith("-"));
+    const allowedFlags = new Set(["--version", "-V", "-v", "--json"]);
+    if (!flags.every((f) => allowedFlags.has(f)))
+        return false;
+    if (positionals.length === 0) {
+        return flags.some((f) => f === "--version" || f === "-V" || f === "-v");
+    }
+    return positionals.length === 1 && positionals[0] === "version";
+}
+//# sourceMappingURL=version-request.js.map

package/package.json

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