@indigoai-us/hq-cli 5.85.3 → 5.87.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.87.0]
+
+### Added
+
+- Added the hidden `hq core worker` subgroup for worker-scoped skill
+  maintenance: `hq core worker lint` fails when a skill shared by multiple
+  workers is duplicated by copy instead of single-sourced (or a shared-skill
+  symlink dangles), and `hq core worker share` migrates duplicated copies onto
+  one canonical file plus relative symlinks (dry-run by default; refuses
+  cross-scope paths and never silently clobbers a drifted copy). (#309)
+- Added single-flight background reindex. (#308)
+
+## [5.86.0]
+
+### Added
+
+- Added `hq search` and `hq index` commands for keyword, semantic, and hybrid
+  search across reconciled QMD collections, with explicit opt-in embedding and
+  package-local QMD resolution. Registered unmanaged collections remain
+  untouched and are reported as `registered (unmanaged)`. (#306)
+
 ## [5.85.3]
 
 ### Changed

package/assets/scaffold/core/scripts/lint-shared-worker-skills.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# lint-shared-worker-skills.sh — fail if a worker-scoped skill is duplicated by
+# copy instead of being single-sourced through the shared-skills convention.
+#
+# THE DRIFT PROBLEM this guards against: a skill used by several workers used to
+# be physically COPIED into each worker's skills/ directory. Editing one copy
+# left the others stale, so the copies drifted apart over time (e.g. a shared
+# e2e-testing skill splitting into two divergent versions). The fix is to keep
+# ONE canonical file under a scope-appropriate `_shared-skills/` store and point
+# each sharing worker's skill entry at it with a relative symlink — see
+# core/knowledge/public/hq-core/shared-worker-skills.md.
+#
+# This linter makes that convention enforceable. It flags two failure shapes:
+#
+#   DUPLICATE  — two or more NON-symlink skill files, in any worker under the
+#                scanned roots, whose byte content is identical. Identical bytes
+#                across two real files is exactly an un-single-sourced copy: the
+#                moment someone edits one, they drift. (Symlinks that resolve to
+#                a shared canonical are single-sourced and are NOT flagged, even
+#                though their resolved content matches the canonical.)
+#   BROKEN     — a skill entry that is a symlink whose target does not resolve.
+#
+# It deliberately does NOT flag two same-NAMED skills whose content differs
+# (e.g. an API-level vs a browser-level e2e skill): distinct content means they
+# are distinct skills that merely share a filename, not a drifted share.
+#
+# Usage: lint-shared-worker-skills.sh [root ...]
+#   Default roots: core/workers core/packages  (the SHIPPED hq-core scope —
+#   company `_shared-skills/` stores live under companies/<co>/ and are linted
+#   per-tenant, not here).
+#
+# Exit 0 + "OK:" line when clean; exit 1 + a report naming every offending group
+# when not. Matches the loud-and-specific style of lint-skill-script-refs.sh.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+roots=("$@")
+if [[ ${#roots[@]} -eq 0 ]]; then
+  roots=(core/workers core/packages)
+fi
+
+# Content hash of a file, portable across Linux and macOS (neither guaranteed to
+# ship the other's tool): md5sum (GNU) → md5 (BSD/macOS) → shasum (Perl, both).
+content_hash() {
+  if command -v md5sum >/dev/null 2>&1; then
+    md5sum "$1" | cut -d' ' -f1
+  elif command -v md5 >/dev/null 2>&1; then
+    md5 -q "$1"
+  else
+    shasum "$1" | cut -d' ' -f1
+  fi
+}
+
+# Collect skill entries: regular files AND symlinks named *.md under any
+# .../skills/... path. -type l must be matched explicitly — a symlink is not a
+# -type f, so a skills symlink would otherwise be invisible to the scan.
+mapfile -t entries < <(
+  find "${roots[@]}" \( -type f -o -type l \) -path '*/skills/*.md' 2>/dev/null | sort
+)
+
+# Empty is clean — and guards `"${entries[@]}"` under `set -u` on bash 3.2
+# (macOS), which errors on an empty array expansion.
+if [[ ${#entries[@]} -eq 0 ]]; then
+  echo "OK: worker-scoped skills are single-sourced (0 skill entries under: ${roots[*]})"
+  exit 0
+fi
+
+broken=()
+# Parallel arrays keyed by content hash: hash_keys[i] is a hash, and
+# hash_regfiles[i] is a newline-joined list of the NON-symlink files with that
+# hash. Bash 3.2 (macOS) has no associative arrays in a portable-guaranteed way,
+# so a linear scan over parallel arrays keeps this runnable everywhere HQ runs.
+hash_keys=()
+hash_regfiles=()
+
+hash_index() { # echo the index of $1 in hash_keys, or -1
+  local want="$1" i
+  for i in "${!hash_keys[@]}"; do
+    if [[ "${hash_keys[$i]}" == "$want" ]]; then
+      echo "$i"; return 0
+    fi
+  done
+  echo "-1"
+}
+
+for entry in "${entries[@]}"; do
+  if [[ -L "$entry" ]]; then
+    # Symlink: single-sourced by design. Only a DANGLING one is a problem.
+    if [[ ! -e "$entry" ]]; then
+      broken+=("$entry")
+    fi
+    continue
+  fi
+  # Regular file: hash its bytes and bucket it. Two regular files sharing a
+  # bucket are two copies of the same skill — the drift hazard.
+  h="$(content_hash "$entry")"
+  idx="$(hash_index "$h")"
+  if [[ "$idx" == "-1" ]]; then
+    hash_keys+=("$h")
+    hash_regfiles+=("$entry")
+  else
+    hash_regfiles[$idx]="${hash_regfiles[$idx]}"$'\n'"$entry"
+  fi
+done
+
+findings=0
+
+for i in "${!hash_keys[@]}"; do
+  group="${hash_regfiles[$i]}"
+  count="$(printf '%s\n' "$group" | grep -c .)"
+  if [[ "$count" -ge 2 ]]; then
+    if [[ $findings -eq 0 ]]; then
+      echo "lint-shared-worker-skills: FAIL — duplicated worker skills (single-source these via _shared-skills/ + relative symlinks):" >&2
+    fi
+    findings=$((findings + 1))
+    echo "  DUPLICATE (identical content, ${count} copies — pick one canonical and symlink the rest):" >&2
+    printf '    %s\n' "$group" >&2
+  fi
+done
+
+if [[ ${#broken[@]} -gt 0 ]]; then
+  if [[ $findings -eq 0 ]]; then
+    echo "lint-shared-worker-skills: FAIL — broken shared-skill symlink(s):" >&2
+  fi
+  findings=$((findings + ${#broken[@]}))
+  echo "  BROKEN (symlink target does not resolve):" >&2
+  printf '    %s\n' "${broken[@]}" >&2
+fi
+
+if [[ $findings -gt 0 ]]; then
+  echo "" >&2
+  echo "  Fix: keep ONE canonical file in the narrowest-scope _shared-skills/ store" >&2
+  echo "  (core/workers/_shared-skills, core/packages/<pack>/workers/_shared-skills," >&2
+  echo "  or companies/<co>/workers/_shared-skills) and replace each duplicate with a" >&2
+  echo "  relative symlink. Helper: hq core worker share" >&2
+  echo "  Doc: core/knowledge/public/hq-core/shared-worker-skills.md" >&2
+  exit 1
+fi
+
+echo "OK: worker-scoped skills are single-sourced (${#entries[@]} skill entries scanned under: ${roots[*]})"

package/assets/scaffold/core/scripts/share-worker-skill.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# share-worker-skill.sh — convert duplicated worker-scoped skill copies into a
+# single canonical file plus relative symlinks, the migration step for the
+# shared-worker-skills convention (core/knowledge/public/hq-core/shared-worker-skills.md).
+#
+# This performs the ONLY mechanical move the design needs: it never edits any
+# worker.yaml (the skill name still resolves to the same path — only the file
+# type changes from regular file to symlink), and it never touches a skill
+# resolver. `/run` reads {worker}/skills/{skill}.md and follows the symlink
+# transparently, so the change is purely file-layout.
+#
+# Usage:
+#   share-worker-skill.sh <scope-dir> <skill-name> <worker-skill-path> [<worker-skill-path> ...]
+#
+#   <scope-dir>          The narrowest scope that contains EVERY sharing worker,
+#                        e.g. core/workers, core/packages/<pack>/workers, or
+#                        companies/<co>/workers. The canonical file is created at
+#                        <scope-dir>/_shared-skills/<skill-name>.md.
+#   <skill-name>         Bare skill name (no .md), e.g. e2e-testing.
+#   <worker-skill-path>  Each worker's current copy, e.g.
+#                        core/workers/foo/skills/e2e-testing.md
+#
+# Safety rails:
+#   * Every worker path MUST live under <scope-dir> (no cross-scope symlinks,
+#     which would break on pack install / hq-sync). Refuses otherwise.
+#   * If no canonical exists yet, the FIRST worker path is promoted to canonical.
+#   * A worker copy whose content DIFFERS from the canonical is a DRIFTED copy:
+#     the script refuses and tells you to reconcile by hand first (the human
+#     decision the design reserves — never a silent overwrite). Re-run after
+#     reconciling, or pass --force to accept the canonical for that copy.
+#   * Idempotent: a path already symlinked to the canonical is left alone.
+#   * DRY-RUN BY DEFAULT. Pass --apply to make changes.
+
+set -euo pipefail
+
+APPLY=0
+FORCE=0
+args=()
+for a in "$@"; do
+  case "$a" in
+    --apply) APPLY=1 ;;
+    --force) FORCE=1 ;;
+    -*) echo "unknown flag: $a" >&2; exit 2 ;;
+    *) args+=("$a") ;;
+  esac
+done
+
+if [[ ${#args[@]} -lt 3 ]]; then
+  echo "usage: $0 [--apply] [--force] <scope-dir> <skill-name> <worker-skill-path>..." >&2
+  exit 2
+fi
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+scope_dir="${args[0]%/}"
+skill_name="${args[1]}"
+worker_paths=("${args[@]:2}")
+
+if [[ ! "$skill_name" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+  echo "error: skill-name '$skill_name' is not a bare skill name (no slashes, no .md)" >&2
+  exit 2
+fi
+if [[ ! -d "$scope_dir" ]]; then
+  echo "error: scope dir does not exist: $scope_dir" >&2
+  exit 2
+fi
+
+canonical="$scope_dir/_shared-skills/$skill_name.md"
+
+note() { printf '%s\n' "$*"; }
+would() { if [[ $APPLY -eq 1 ]]; then note "  did:   $*"; else note "  would: $*"; fi; }
+
+# Normalize a path to repo-relative without requiring GNU realpath (macOS-safe).
+rel_under() { # rel_under <path> <dir> → 0 if <path> is inside <dir>
+  local p="${1#./}" d="${2#./}"
+  [[ "$p" == "$d/"* ]]
+}
+
+# rel_path <from-dir> <to-file> → relative path from <from-dir> to <to-file>,
+# computed purely from the two repo-relative strings (both already normalized,
+# no `..` segments, no symlinks in the literal path). Portable: no python3, no
+# GNU realpath --relative-to (macOS ships neither).
+rel_path() {
+  local from="${1#./}" to="${2#./}"
+  local -a fa ta
+  IFS='/' read -r -a fa <<< "$from"
+  IFS='/' read -r -a ta <<< "$to"
+  local i=0
+  while [[ $i -lt ${#fa[@]} && $i -lt ${#ta[@]} && "${fa[$i]}" == "${ta[$i]}" ]]; do
+    i=$((i + 1))
+  done
+  local up="" j
+  for (( j=i; j<${#fa[@]}; j++ )); do up="../$up"; done
+  local down="" k
+  for (( k=i; k<${#ta[@]}; k++ )); do down="$down${ta[$k]}/"; done
+  down="${down%/}"
+  printf '%s%s' "$up" "$down"
+}
+
+# Every worker path must be inside the scope dir.
+for wp in "${worker_paths[@]}"; do
+  wp="${wp#./}"
+  if ! rel_under "$wp" "$scope_dir"; then
+    echo "error: worker path '$wp' is not under scope dir '$scope_dir'" >&2
+    echo "       canonical must live in the narrowest scope covering all sharers;" >&2
+    echo "       cross-scope symlinks are disallowed. Aborting (no changes made)." >&2
+    exit 2
+  fi
+done
+
+note "Canonical: $canonical"
+note "Scope:     $scope_dir"
+[[ $APPLY -eq 1 ]] || note "(dry run — pass --apply to make changes)"
+
+# 1) Establish the canonical file.
+if [[ -e "$canonical" && ! -L "$canonical" ]]; then
+  note "canonical already exists (regular file) — reusing it"
+else
+  # Promote the first worker path that is a real (non-symlink) file.
+  seed=""
+  for wp in "${worker_paths[@]}"; do
+    if [[ -f "$wp" && ! -L "$wp" ]]; then seed="$wp"; break; fi
+  done
+  if [[ -z "$seed" ]]; then
+    echo "error: no canonical exists and no worker path is a regular file to seed it from" >&2
+    exit 2
+  fi
+  would "mkdir -p $scope_dir/_shared-skills"
+  would "git mv $seed $canonical  (promote first copy to canonical)"
+  if [[ $APPLY -eq 1 ]]; then
+    mkdir -p "$scope_dir/_shared-skills"
+    git mv "$seed" "$canonical" 2>/dev/null || mv "$seed" "$canonical"
+  fi
+fi
+
+# 2) Point each worker path at the canonical via a relative symlink.
+for wp in "${worker_paths[@]}"; do
+  wp="${wp#./}"
+  # Already the canonical file itself (post-promotion) → link it too so every
+  # worker slot is a symlink and the canonical lives only under _shared-skills.
+  target_dir="$(dirname "$wp")"
+  # Relative path from the worker's skills dir to the canonical (portable).
+  rel="$(rel_path "$target_dir" "$canonical")"
+
+  if [[ -L "$wp" ]]; then
+    cur="$(readlink "$wp")"
+    if [[ "$cur" == "$rel" ]]; then
+      note "ok: $wp already links to canonical"
+      continue
+    fi
+    would "relink $wp -> $rel (was: $cur)"
+    if [[ $APPLY -eq 1 ]]; then ln -sfn "$rel" "$wp"; fi
+    continue
+  fi
+
+  if [[ -e "$wp" ]]; then
+    # Regular file present — must match canonical or be reconciled first.
+    if cmp -s "$wp" "$canonical"; then
+      would "replace identical copy $wp with symlink -> $rel"
+      if [[ $APPLY -eq 1 ]]; then rm -f "$wp"; ln -s "$rel" "$wp"; fi
+    else
+      if [[ $FORCE -eq 1 ]]; then
+        would "FORCE replace DRIFTED copy $wp with symlink -> $rel (content discarded)"
+        if [[ $APPLY -eq 1 ]]; then rm -f "$wp"; ln -s "$rel" "$wp"; fi
+      else
+        echo "  DRIFT: $wp differs from canonical — reconcile by hand, then re-run" >&2
+        echo "         (diff $wp $canonical), or pass --force to accept canonical." >&2
+        exit 3
+      fi
+    fi
+  else
+    would "create symlink $wp -> $rel"
+    if [[ $APPLY -eq 1 ]]; then mkdir -p "$target_dir"; ln -s "$rel" "$wp"; fi
+  fi
+done
+
+note "done."

package/dist/commands/core.d.ts

@@ -68,6 +68,21 @@ export type RebuildIndexTarget = ScaffoldAsset & {
     /** Rebuild target — `hq core rebuild-index <target>`. */
     target: string;
 };
+export type WorkerSubcommand = ScaffoldAsset & {
+    /** Subcommand name under the `worker` group — `hq core worker <name>`. */
+    name: string;
+};
+/**
+ * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
+ *
+ * Both are cold, explicitly-invoked operations (a linter and a one-shot
+ * migration), which the scaffold-vs-cli-code-ownership policy permits in the
+ * CLI. They are `root: "cwd"` because each derives its root from the caller
+ * (`git rev-parse --show-toplevel || pwd`): the CLI must inject nothing, or it
+ * would retarget the lint at the CLI's own checkout instead of the HQ tree the
+ * operator is standing in. See core/knowledge/public/hq-core/shared-worker-skills.md.
+ */
+export declare const WORKER_SUBCOMMANDS: WorkerSubcommand[];
 /**
  * The ten index rebuild targets. The command registration below intentionally
  * loops over this table for lookup, so adding a target never requires another

package/dist/commands/core.js

@@ -32,6 +32,30 @@ import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
+/**
+ * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
+ *
+ * Both are cold, explicitly-invoked operations (a linter and a one-shot
+ * migration), which the scaffold-vs-cli-code-ownership policy permits in the
+ * CLI. They are `root: "cwd"` because each derives its root from the caller
+ * (`git rev-parse --show-toplevel || pwd`): the CLI must inject nothing, or it
+ * would retarget the lint at the CLI's own checkout instead of the HQ tree the
+ * operator is standing in. See core/knowledge/public/hq-core/shared-worker-skills.md.
+ */
+export const WORKER_SUBCOMMANDS = [
+    {
+        name: "lint",
+        asset: "core/scripts/lint-shared-worker-skills.sh",
+        root: "cwd",
+        summary: "Fail on worker-scoped skills duplicated by copy instead of single-sourced",
+    },
+    {
+        name: "share",
+        asset: "core/scripts/share-worker-skill.sh",
+        root: "cwd",
+        summary: "Migrate duplicated worker skills onto one canonical file + relative symlinks",
+    },
+];
 /**
  * The ten index rebuild targets. The command registration below intentionally
  * loops over this table for lookup, so adding a target never requires another
@@ -181,6 +205,7 @@ export const SCAFFOLD_COMMANDS = [
 export const SCAFFOLD_ASSETS = [
     ...REBUILD_INDEX_TARGETS,
     ...SCAFFOLD_COMMANDS,
+    ...WORKER_SUBCOMMANDS,
 ];
 /**
  * Resolve the tree an entry runs against, and the cwd to run it in.
@@ -237,6 +262,27 @@ export function registerCoreCommands(program) {
     // This group primarily hosts manifest-driven bundled assets, but it also
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
+    // `hq core worker <name>` — a nested subgroup for worker-scoped skill
+    // maintenance. Nested (rather than flat `hq core worker-<name>`) so the two
+    // related operations read as one family.
+    const worker = core
+        .command("worker")
+        .description("Worker-scoped skill maintenance (lint, share)");
+    for (const entry of WORKER_SUBCOMMANDS) {
+        worker
+            .command(entry.name)
+            .description(entry.summary)
+            // Pure passthrough: the wrapped script owns its own argument grammar.
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments passed through to the script")
+            .action((args = [], _opts, cmd) => {
+            const scope = core.opts();
+            const operands = cmd.args.length > 0 ? cmd.args : args;
+            runEntry(entry, scope, operands);
+        });
+    }
     const runCommand = (entry, args = [], cmd, target) => {
         const scope = core.opts();
         // `cmd.args` is the authoritative operand list: with

package/dist/commands/index-cmd.d.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
+import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
+export type SearchIndexDependencies = {
+    reconcileCollections: (hqRoot: string) => unknown;
+    deriveCollections: (hqRoot: string) => SearchCollection[];
+    listRegisteredCollections: (hqRoot: string, options?: RunQmdOptions) => Set<string>;
+    resolveQmdBin: () => string;
+    resolveQmdVersion: () => string | undefined;
+    runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
+    runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
+};
+/** Incrementally update qmd, embedding only when an operator explicitly asks. */
+export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;
+export declare function collectionStatusLines(expected: SearchCollection[], registered: ReadonlySet<string>): string[];
+export declare function collectionSummary(expected: SearchCollection[], registered: ReadonlySet<string>): string;
+export declare function registerIndexCommand(program: Command, dependencies?: SearchIndexDependencies): void;
+//# sourceMappingURL=index-cmd.d.ts.map

package/dist/commands/index-cmd.js

@@ -0,0 +1,110 @@
+import { Option } from 'commander';
+import { deriveCollections, listRegisteredCollections, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
+import { findHqRoot } from '../utils/manifest.js';
+const defaults = {
+    reconcileCollections,
+    deriveCollections,
+    listRegisteredCollections,
+    resolveQmdBin,
+    resolveQmdVersion,
+    runQmd,
+    runBackgroundLauncher,
+    runBackgroundWorker,
+    backgroundStatus,
+};
+/** Incrementally update qmd, embedding only when an operator explicitly asks. */
+export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
+    dependencies.reconcileCollections(hqRoot);
+    dependencies.runQmd(['update'], { cwd: hqRoot });
+    if (embed)
+        dependencies.runQmd(['embed'], { cwd: hqRoot });
+}
+function resolveRoot(hqRoot) {
+    return hqRoot ?? findHqRoot();
+}
+function makeBackgroundDependencies(hqRoot, dependencies) {
+    return {
+        ...defaultBackgroundDependencies(hqRoot),
+        resolveQmdBin: dependencies.resolveQmdBin,
+        reconcileCollections: dependencies.reconcileCollections,
+        runQmd: dependencies.runQmd,
+    };
+}
+export function collectionStatusLines(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const managed = expected.map((collection) => `${registered.has(collection.name) ? 'registered' : 'missing'}  ${collection.name}  ${collection.path}`);
+    const unmanaged = [...registered]
+        .filter((name) => !expectedNames.has(name))
+        .sort((left, right) => left.localeCompare(right))
+        .map((name) => `registered (unmanaged)  ${name}`);
+    return [...managed, ...unmanaged];
+}
+export function collectionSummary(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const unmanaged = [...registered].filter((name) => !expectedNames.has(name)).length;
+    return `collections: ${registered.size} registered; ${expected.length} expected; ${unmanaged} unmanaged`;
+}
+export function registerIndexCommand(program, dependencies = defaults) {
+    const index = program.command('index').description('Manage the local HQ search index');
+    index
+        .command('sync')
+        .description('Reconcile collections and incrementally update the qmd index')
+        .option('--embed', 'Also rebuild expensive semantic embeddings')
+        .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        syncSearchIndex(hqRoot, options.embed === true);
+        console.log(`Updated search index for ${hqRoot}${options.embed ? ' (including embeddings)' : ''}.`);
+    });
+    index
+        .command('collections')
+        .description('Show expected and registered qmd collections')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const registered = dependencies.listRegisteredCollections(hqRoot);
+        for (const line of collectionStatusLines(dependencies.deriveCollections(hqRoot), registered))
+            console.log(line);
+    });
+    index
+        .command('background')
+        .description('Run a detached, single-flight qmd cleanup and reindex')
+        .option('--log <path>', 'Write worker output to this log file')
+        .addOption(new Option('--worker').hideHelp())
+        .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const background = makeBackgroundDependencies(hqRoot, dependencies);
+        if (options.log)
+            background.env = { ...background.env, QMD_REINDEX_LOG: options.log };
+        const result = options.worker
+            ? (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
+            : (dependencies.runBackgroundLauncher ?? runBackgroundLauncher)(background);
+        if (!options.worker && result.state === 'launched')
+            console.log(result.pid);
+        else if (!options.worker && (result.state === 'skipped-agent' || result.state === 'skipped'))
+            console.log(result.state);
+    });
+    index
+        .command('status')
+        .description('Show qmd binary, collection, and index status')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const bin = dependencies.resolveQmdBin();
+        const registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
+        const expected = dependencies.deriveCollections(hqRoot);
+        const qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
+        const qmdVersion = dependencies.resolveQmdVersion();
+        const background = (dependencies.backgroundStatus ?? backgroundStatus)(makeBackgroundDependencies(hqRoot, dependencies));
+        console.log(`qmd: ${bin}${qmdVersion ? ` (version ${qmdVersion})` : ''}`);
+        console.log(collectionSummary(expected, registered));
+        console.log(`background: lock ${background.lock}; last completed ${background.completedAt ?? 'never'}`);
+        if (qmdStatus.stdout)
+            process.stdout.write(qmdStatus.stdout);
+        if (qmdStatus.stderr)
+            process.stderr.write(qmdStatus.stderr);
+    });
+}
+//# sourceMappingURL=index-cmd.js.map

package/dist/commands/search.d.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+export type SearchMode = 'keyword' | 'semantic' | 'hybrid';
+export type SearchOptions = {
+    mode?: SearchMode;
+    collection?: string;
+    count?: number;
+    json?: boolean;
+};
+export declare function buildSearchArgs(query: string, options?: SearchOptions): string[];
+export declare function buildGetArgs(document: string, options?: Pick<SearchOptions, 'collection'>): string[];
+export declare function registerSearchCommand(program: Command): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/commands/search.js

@@ -0,0 +1,48 @@
+import { runQmd } from '../lib/search-index/index.js';
+export function buildSearchArgs(query, options = {}) {
+    const command = { keyword: 'search', semantic: 'vsearch', hybrid: 'query' }[options.mode ?? 'keyword'];
+    const args = [command, query];
+    if (options.collection)
+        args.push('-c', options.collection);
+    if (options.count !== undefined)
+        args.push('-n', String(options.count));
+    if (options.json)
+        args.push('--json');
+    return args;
+}
+export function buildGetArgs(document, options = {}) {
+    const args = ['get', document];
+    if (options.collection)
+        args.push('-c', options.collection);
+    return args;
+}
+function relay(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+}
+export function registerSearchCommand(program) {
+    const search = program.command('search').description('Search the local HQ qmd index');
+    search
+        .command('get <document>')
+        .description('Retrieve a qmd document by path or document id')
+        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
+        .action((document, options) => {
+        relay(runQmd(buildGetArgs(document, options)));
+    });
+    search
+        .command('<query>')
+        .description('Search the local HQ qmd index')
+        .option('--mode <mode>', 'Search mode: keyword, semantic, or hybrid', 'keyword')
+        .option('-c, --collection <collection>', 'Restrict search to a collection')
+        .option('-n, --count <count>', 'Maximum result count', (value) => Number(value))
+        .option('--json', 'Request machine-readable qmd output')
+        .action((query, options) => {
+        if (!['keyword', 'semantic', 'hybrid'].includes(options.mode ?? 'keyword')) {
+            throw new Error(`Unknown search mode '${options.mode}'. Expected keyword, semantic, or hybrid.`);
+        }
+        relay(runQmd(buildSearchArgs(query, options)));
+    });
+}
+//# sourceMappingURL=search.js.map

package/dist/lib/search-index/background.d.ts

@@ -0,0 +1,39 @@
+import { type QmdProcessResult, type RunQmdOptions } from './index.js';
+export type BackgroundResult = {
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed';
+} | {
+    state: 'launched';
+    pid: number;
+};
+export type BackgroundDependencies = {
+    env: NodeJS.ProcessEnv;
+    hqRoot: string;
+    now: () => number;
+    pid: number;
+    random: () => string;
+    isProcessAlive: (pid: number) => boolean;
+    resolveQmdBin: () => string;
+    reconcileCollections: (hqRoot: string) => unknown;
+    runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
+    spawnWorker: (options: {
+        logPath: string;
+    }) => number;
+    /** Test seam for simulating a competing owner replacing the atomic record. */
+    afterOwnerPublish?: (ownerFile: string) => void;
+};
+export type BackgroundStatus = {
+    lock: 'held' | 'stale' | 'free';
+    completedAt?: number;
+};
+/** Defaults used by the CLI; tests supply every nondeterministic dependency. */
+export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
+/** Match the shell forwarder's hosted-agent markers before looking up qmd. */
+export declare function isHostedAgent(env?: NodeJS.ProcessEnv): boolean;
+export declare function installWorkerCleanup(cleanup: () => void, processEvents?: Pick<NodeJS.Process, 'once'>, exit?: (code: number) => void): void;
+/** Start a detached worker; this public entry never owns the qmd pipeline. */
+export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;
+/** Run the single-flight cleanup → update → embed pipeline in a worker only. */
+export declare function runBackgroundWorker(dependencies: BackgroundDependencies): BackgroundResult;
+/** Report the background lock and latest successful completion for `hq index status`. */
+export declare function backgroundStatus(dependencies: BackgroundDependencies): BackgroundStatus;
+//# sourceMappingURL=background.d.ts.map