@indigoai-us/hq-cli 5.86.0 → 5.87.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [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

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

@@ -1,5 +1,6 @@
 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[];
@@ -7,6 +8,9 @@ export type SearchIndexDependencies = {
     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;

package/dist/commands/index-cmd.js

@@ -1,4 +1,6 @@
+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,
@@ -7,6 +9,9 @@ const defaults = {
     resolveQmdBin,
     resolveQmdVersion,
     runQmd,
+    runBackgroundLauncher,
+    runBackgroundWorker,
+    backgroundStatus,
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
@@ -18,6 +23,14 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
 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}`);
@@ -54,6 +67,25 @@ export function registerIndexCommand(program, dependencies = defaults) {
         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')
@@ -65,8 +97,10 @@ export function registerIndexCommand(program, dependencies = defaults) {
         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)

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

package/dist/lib/search-index/background.js

@@ -0,0 +1,382 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
+const LOCK_NAME = 'qmd-reindex-bg.lock';
+const COMPLETE_NAME = 'qmd-reindex-bg.completed';
+function defaultSpawnWorker({ logPath }) {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const log = fs.openSync(logPath, 'a');
+    const entry = process.argv[1];
+    if (!entry)
+        throw new Error('Cannot determine hq CLI entrypoint for background worker');
+    const child = spawn(process.execPath, [entry, 'index', 'background', '--worker', '--log', logPath], {
+        detached: true,
+        stdio: ['ignore', log, log],
+    });
+    fs.closeSync(log);
+    child.unref();
+    if (!child.pid)
+        throw new Error('Unable to start qmd background worker');
+    return child.pid;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Defaults used by the CLI; tests supply every nondeterministic dependency. */
+export function defaultBackgroundDependencies(hqRoot) {
+    return {
+        env: process.env,
+        hqRoot,
+        now: () => Math.floor(Date.now() / 1_000),
+        pid: process.pid,
+        random: () => Math.random().toString(36).slice(2),
+        isProcessAlive: alive,
+        resolveQmdBin: defaultResolveQmdBin,
+        reconcileCollections: defaultReconcileCollections,
+        runQmd: defaultRunQmd,
+        spawnWorker: defaultSpawnWorker,
+    };
+}
+/** Match the shell forwarder's hosted-agent markers before looking up qmd. */
+export function isHostedAgent(env = process.env) {
+    if (env.HQ_QMD_REINDEX_MODE === 'skip-agent' || env.HQ_QMD_REINDEX_MODE === 'skip')
+        return true;
+    if (env.HQ_AGENT_BOX && env.HQ_AGENT_BOX !== '0')
+        return true;
+    try {
+        fs.accessSync('/usr/local/bin/hq-agent-qmd-index', fs.constants.X_OK);
+        return true;
+    }
+    catch { /* probe next marker */ }
+    try {
+        fs.accessSync('/usr/local/lib/hq-agent/qmd-index-user', fs.constants.X_OK);
+        return true;
+    }
+    catch { /* probe next marker */ }
+    return fs.existsSync('/etc/systemd/system/hq-agent-qmd-index.timer')
+        || fs.existsSync('/etc/systemd/system/hq-agent-qmd-index.service')
+        || fs.existsSync('/var/lib/hq-agent');
+}
+function lockRoot(home) {
+    return path.join(home, '.hq', 'locks');
+}
+function lockPath(home) {
+    return path.join(lockRoot(home), LOCK_NAME);
+}
+function completionPath(home) {
+    return path.join(lockRoot(home), COMPLETE_NAME);
+}
+function parseFields(file) {
+    try {
+        return Object.fromEntries(fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
+            const index = line.indexOf('=');
+            return index === -1 ? [] : [[line.slice(0, index), line.slice(index + 1)]];
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readOwner(directory) {
+    const fields = parseFields(path.join(directory, 'owner'));
+    if (!fields || !/^\d+$/.test(fields.pid ?? '') || !/^\d+$/.test(fields.ts ?? '') || !/^[A-Za-z0-9._-]+$/.test(fields.nonce ?? ''))
+        return undefined;
+    return { pid: Number(fields.pid), ts: Number(fields.ts), nonce: fields.nonce };
+}
+function graceSeconds(dependencies) {
+    const value = dependencies.env.QMD_HANDOFF_LOCK_GRACE_SEC;
+    return value && /^\d+$/.test(value) ? Number(value) : 5;
+}
+function dedupeSeconds(dependencies) {
+    const value = dependencies.env.QMD_HANDOFF_DEDUPE_SEC;
+    return value && /^\d+$/.test(value) ? Number(value) : 90;
+}
+function isRecentCompletion(home, dependencies) {
+    const dedupe = dedupeSeconds(dependencies);
+    if (dedupe === 0)
+        return false;
+    const fields = parseFields(completionPath(home));
+    if (!fields || !/^\d+$/.test(fields.ts ?? ''))
+        return false;
+    const age = dependencies.now() - Number(fields.ts);
+    return age >= 0 && age < dedupe;
+}
+function writeCompletion(home, dependencies) {
+    try {
+        fs.writeFileSync(completionPath(home), `ts=${dependencies.now()}\npid=${dependencies.pid}\nmode=raw\n`);
+    }
+    catch {
+        // Completion is a best-effort dedupe hint, never a worker failure.
+    }
+}
+function isOwnerlessLockWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < graceSeconds(dependencies);
+    }
+    catch {
+        return true;
+    }
+}
+function lockState(directory, dependencies) {
+    if (!fs.existsSync(directory))
+        return 'free';
+    const owner = readOwner(directory);
+    if (owner)
+        return dependencies.isProcessAlive(owner.pid) ? 'held' : 'stale';
+    return isOwnerlessLockWithinGrace(directory, dependencies) ? 'held' : 'stale';
+}
+function generation(directory) {
+    const owner = readOwner(directory);
+    if (owner)
+        return owner.nonce;
+    if (!fs.existsSync(directory))
+        return undefined;
+    return 'empty';
+}
+function removeDirectoryIfEmpty(directory) {
+    try {
+        fs.rmdirSync(directory);
+    }
+    catch { /* another claimant owns it, or it is already gone */ }
+}
+function claimWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < Math.max(5, graceSeconds(dependencies));
+    }
+    catch {
+        return true;
+    }
+}
+function acquireClaim(home, observedGeneration, dependencies) {
+    const claim = path.join(lockRoot(home), `qmd-reindex-bg.claim.${observedGeneration}`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.mkdirSync(claim);
+        }
+        catch {
+            if (attempt === 1 || !recoverAbandonedClaim(claim, dependencies))
+                return undefined;
+            continue;
+        }
+        const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
+        try {
+            fs.mkdirSync(claimant);
+            fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
+            return { claim, claimant };
+        }
+        catch {
+            fs.rmSync(claimant, { recursive: true, force: true });
+            removeDirectoryIfEmpty(claim);
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reclaim only exact dead claimant names, then remove the claim directory if
+ * empty. This mirrors the shell's no-fixed-path-reclaim rule: a peer that has
+ * recreated claim.G with a new marker makes rmdir fail and wins the race.
+ */
+function recoverAbandonedClaim(claim, dependencies) {
+    let entries;
+    try {
+        entries = fs.readdirSync(claim, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries.filter((entry) => entry.name.startsWith('c.'))) {
+        const marker = path.join(claim, entry.name);
+        const fields = parseFields(path.join(marker, 'owner'));
+        const pid = fields && /^\d+$/.test(fields.pid ?? '') ? Number(fields.pid) : undefined;
+        if (pid !== undefined && dependencies.isProcessAlive(pid))
+            return false;
+        if (pid === undefined && claimWithinGrace(claim, dependencies))
+            return false;
+        const abandoned = `${claim}.stale-claim.${dependencies.pid}.${dependencies.random()}`;
+        try {
+            fs.renameSync(marker, abandoned);
+            fs.rmSync(abandoned, { recursive: true, force: true });
+        }
+        catch {
+            return false;
+        }
+    }
+    if (entries.length === 0 && claimWithinGrace(claim, dependencies))
+        return false;
+    removeDirectoryIfEmpty(claim);
+    return !fs.existsSync(claim);
+}
+function createAndPublishLock(home, dependencies) {
+    const directory = lockPath(home);
+    try {
+        fs.mkdirSync(directory);
+    }
+    catch {
+        return false;
+    }
+    const marker = path.join(directory, `acq.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        fs.mkdirSync(marker);
+    }
+    catch {
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+    const nonce = `${dependencies.pid}.${dependencies.random()}`;
+    const ownerFile = path.join(directory, 'owner');
+    const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
+        fs.renameSync(temporary, ownerFile);
+        dependencies.afterOwnerPublish?.(ownerFile);
+        const verified = readOwner(directory);
+        if (!verified || verified.pid !== dependencies.pid || verified.nonce !== nonce)
+            throw new Error('owner publish verification failed');
+        fs.rmSync(marker, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        // The marker identifies only the directory this process created.  Do not
+        // recursively remove the fixed lock path after a failed publication.
+        fs.rmSync(marker, { recursive: true, force: true });
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+}
+function claimAndReclaim(home, dependencies) {
+    const directory = lockPath(home);
+    const observedGeneration = generation(directory);
+    if (!observedGeneration || lockState(directory, dependencies) !== 'stale')
+        return false;
+    const acquired = acquireClaim(home, observedGeneration, dependencies);
+    if (!acquired)
+        return false;
+    try {
+        // Generation fencing: only move exactly the stale generation we observed.
+        if (generation(directory) !== observedGeneration || lockState(directory, dependencies) !== 'stale')
+            return false;
+        const abandoned = `${directory}.stale.${dependencies.pid}.${dependencies.random()}`;
+        fs.renameSync(directory, abandoned);
+        fs.rmSync(abandoned, { recursive: true, force: true });
+        return createAndPublishLock(home, dependencies);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.rmSync(acquired.claimant, { recursive: true, force: true });
+        removeDirectoryIfEmpty(acquired.claim);
+    }
+}
+function acquireLock(home, dependencies) {
+    fs.mkdirSync(lockRoot(home), { recursive: true });
+    return createAndPublishLock(home, dependencies) || claimAndReclaim(home, dependencies);
+}
+function releaseLock(home, dependencies) {
+    const directory = lockPath(home);
+    if (readOwner(directory)?.pid === dependencies.pid)
+        fs.rmSync(directory, { recursive: true, force: true });
+}
+export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
+    processEvents.once('exit', cleanup);
+    // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
+    // catchable cleanup. SIGINT/SIGTERM are registered here and the CLI's normal
+    // process exit then runs the same idempotent owner release. Exiting prevents
+    // a synchronous pipeline from continuing after it has released ownership.
+    processEvents.once('SIGINT', () => { cleanup(); exit(0); });
+    processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
+}
+/** Start a detached worker; this public entry never owns the qmd pipeline. */
+export function runBackgroundLauncher(dependencies) {
+    if (isHostedAgent(dependencies.env))
+        return { state: 'skipped-agent' };
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { state: 'quiet' };
+    try {
+        dependencies.resolveQmdBin();
+    }
+    catch {
+        return { state: 'skipped' };
+    }
+    const logPath = dependencies.env.QMD_REINDEX_LOG
+        ?? dependencies.env.QMD_HANDOFF_LOG
+        ?? path.join(dependencies.env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
+    return { state: 'launched', pid: dependencies.spawnWorker({ logPath }) };
+}
+/** Run the single-flight cleanup → update → embed pipeline in a worker only. */
+export function runBackgroundWorker(dependencies) {
+    if (isHostedAgent(dependencies.env))
+        return { state: 'skipped-agent' };
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { state: 'quiet' };
+    try {
+        dependencies.resolveQmdBin();
+    }
+    catch {
+        return { state: 'skipped' };
+    }
+    if (isRecentCompletion(home, dependencies) || !acquireLock(home, dependencies))
+        return { state: 'busy' };
+    let released = false;
+    const cleanup = () => {
+        if (released)
+            return;
+        released = true;
+        releaseLock(home, dependencies);
+    };
+    installWorkerCleanup(cleanup, process, (code) => process.exit(code));
+    try {
+        if (isRecentCompletion(home, dependencies))
+            return { state: 'busy' };
+        // Collection reconciliation is the existing #306 seam; cleanup/update/embed
+        // retain their shell-script ordering after that policy setup.
+        try {
+            dependencies.reconcileCollections(dependencies.hqRoot);
+        }
+        catch {
+            // The shell worker has no collection-registration step. Keep this #306
+            // integration best-effort so it cannot suppress a later index update.
+        }
+        try {
+            dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot });
+        }
+        catch { /* cleanup is intentionally best-effort */ }
+        try {
+            dependencies.runQmd(['update'], { cwd: dependencies.hqRoot });
+        }
+        catch {
+            return { state: 'update-failed' };
+        }
+        try {
+            dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot });
+        }
+        catch { /* a completed embed attempt still permits the completion stamp */ }
+        writeCompletion(home, dependencies);
+        return { state: 'completed' };
+    }
+    finally {
+        cleanup();
+    }
+}
+/** Report the background lock and latest successful completion for `hq index status`. */
+export function backgroundStatus(dependencies) {
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { lock: 'free' };
+    const fields = parseFields(completionPath(home));
+    const completedAt = fields && /^\d+$/.test(fields.ts ?? '') ? Number(fields.ts) : undefined;
+    return { lock: lockState(lockPath(home), dependencies), ...(completedAt === undefined ? {} : { completedAt }) };
+}
+//# sourceMappingURL=background.js.map

package/package.json

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