@indigoai-us/hq-cli 5.86.0 → 5.88.0

package/dist/lib/index-render/social-drafts.js

@@ -0,0 +1,53 @@
+import * as fs from "fs";
+import { basename, countImmediate, date, exists, heading, immediateEntries, isHidden, log, mtime, sanitize, truncate, write } from "./shared.js";
+function directoryDescription(context, name) {
+    const base = `workspace/social-drafts/${name}`;
+    const files = countImmediate(context.root, base, (child, file) => !isHidden(child) && fs.statSync(file).isFile());
+    const dirs = countImmediate(context.root, base, (child, file) => !isHidden(child) && fs.statSync(file).isDirectory());
+    if (name === "x")
+        return `X/Twitter post drafts (${files} files)`;
+    if (name === "linkedin")
+        return `LinkedIn post drafts (${files} files)`;
+    if (name === "blog")
+        return `Blog post drafts (${files} files)`;
+    if (name === "tiktok")
+        return `TikTok scripts/drafts (${files} files)`;
+    if (name === "images")
+        return `Infographics and post images (${dirs} dirs)`;
+    return dirs > 0 ? `${dirs} subdir(s), ${files} file(s)` : `${files} file(s)`;
+}
+function fileDescription(file) { const name = basename(file); if (name.endsWith(".md"))
+    return heading(file) || name.slice(0, -3); if (name.endsWith(".json"))
+    return `${name.slice(0, -5)} data`; if (/\.(py|sh)$/.test(name))
+    return `Script: ${name}`; return name; }
+export function renderSocialDrafts(context) {
+    const base = "workspace/social-drafts";
+    if (!exists(context.root, base)) {
+        log(context, "rebuild-social-drafts-index: workspace/social-drafts/ missing, skipping");
+        return { written: [] };
+    }
+    const recent = ["x", "linkedin", "blog", "tiktok"].flatMap((channel) => immediateEntries(context.root, `${base}/${channel}`, "file").filter((file) => file.endsWith(".md"))).sort((a, b) => mtime(b) - mtime(a)).slice(0, 20);
+    const lines = ["# Social Drafts", "", `> Auto-generated. Updated: ${date(context.now)}`, "", "## Recent Drafts", ""];
+    for (const file of recent) {
+        const relative = file.slice(`${context.root}/workspace/social-drafts/`.length);
+        lines.push(`- \`${relative}\` - ${truncate(sanitize(heading(file) || basename(file).slice(0, -3)), 100)}`);
+    }
+    lines.push("", "## Directories", "", "| Name | Description |", "|------|-------------|");
+    for (const directory of immediateEntries(context.root, base, "dir")) {
+        const name = basename(directory);
+        if (!isHidden(name))
+            lines.push(`| \`${name}/\` | ${truncate(sanitize(directoryDescription(context, name)), 100)} |`);
+    }
+    for (const file of immediateEntries(context.root, base, "file")) {
+        const name = basename(file);
+        if (name !== "INDEX.md" && !isHidden(name))
+            lines.push(`| \`${name}\` | ${truncate(sanitize(fileDescription(file)), 100)} |`);
+    }
+    lines.push("");
+    const output = `${base}/INDEX.md`;
+    write(context, output, lines.join("\n"));
+    const draftCount = ["x", "linkedin", "blog", "tiktok"].reduce((sum, channel) => sum + immediateEntries(context.root, `${base}/${channel}`, "file").filter((file) => file.endsWith(".md")).length, 0);
+    log(context, `rebuild-social-drafts-index: wrote ${output} (${draftCount} draft file(s))`);
+    return { written: [output] };
+}
+//# sourceMappingURL=social-drafts.js.map

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

@@ -0,0 +1,3 @@
+import { RenderContext, RenderResult } from "./shared.js";
+export declare function renderThreads(context: RenderContext, args?: string[]): RenderResult;
+//# sourceMappingURL=threads.d.ts.map

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

@@ -0,0 +1,42 @@
+import * as fs from "fs";
+import { at, log, readJson, sanitize, timestamp, write } from "./shared.js";
+export function renderThreads(context, args = []) {
+    const mode = args[0] ?? "--index";
+    const directory = at(context.root, "workspace/threads");
+    fs.mkdirSync(directory, { recursive: true });
+    // Match `ls -t`: newest filesystem modification time first. `updated_at` is
+    // rendered metadata only, and must not influence the order.
+    const files = fs.readdirSync(directory)
+        .filter((name) => /^T-.*\.json$/.test(name) && !name.endsWith(".changeset.json"))
+        .map((name) => `${directory}/${name}`)
+        .sort((a, b) => {
+        const aTime = fs.statSync(a, { bigint: true }).mtimeNs;
+        const bTime = fs.statSync(b, { bigint: true }).mtimeNs;
+        return bTime > aTime ? 1 : bTime < aTime ? -1 : 0;
+    });
+    const rows = files.flatMap((file) => {
+        const data = readJson(file);
+        if (!data)
+            return [];
+        const metadata = data.metadata && typeof data.metadata === "object" ? data.metadata : {};
+        return [`| ${typeof data.thread_id === "string" ? data.thread_id : "-"} | ${typeof data.type === "string" ? data.type : "-"} | ${typeof data.updated_at === "string" ? data.updated_at : "-"} | ${sanitize(typeof metadata.title === "string" ? metadata.title.replace(/\|/g, "/") : "-")} |`];
+    });
+    const written = [];
+    const table = (title, limited) => [
+        `# ${title}`, "", `Generated: ${timestamp(context.now)}`, `Active threads: ${files.length} (archive/ excluded)`, "", "| Thread | Type | Updated | Title |", "|--------|------|---------|-------|", ...(limited ? rows.slice(0, limited) : rows), "",
+    ].join("\n");
+    if (mode === "--index" || mode === "--both") {
+        const output = "workspace/threads/INDEX.md";
+        write(context, output, table("Threads INDEX", 0));
+        written.push(output);
+        log(context, `rebuild-threads-index: wrote ${output} (${files.length} threads)`);
+    }
+    if (mode === "--recent" || mode === "--both") {
+        const output = "workspace/threads/recent.md";
+        write(context, output, table("Recent Threads", 15));
+        written.push(output);
+        log(context, `rebuild-threads-index: wrote ${output} (last 15)`);
+    }
+    return { written };
+}
+//# sourceMappingURL=threads.js.map

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

@@ -0,0 +1,3 @@
+import { RenderContext, RenderResult } from "./shared.js";
+export declare function renderWorkers(context: RenderContext): RenderResult;
+//# sourceMappingURL=workers.d.ts.map

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

@@ -0,0 +1,49 @@
+import * as yaml from "js-yaml";
+import { basename, date, exists, immediateEntries, isHidden, log, readText, sanitize, truncate, write } from "./shared.js";
+function workerDescription(file) {
+    const text = readText(file);
+    if (!text)
+        return "";
+    try {
+        const parsed = yaml.load(text);
+        const value = parsed?.worker?.description ?? parsed?.worker?.bio?.role;
+        return typeof value === "string" ? value : "";
+    }
+    catch {
+        return text.match(/^\s+description:\s*(.*)$/m)?.[1]?.replace(/^["']|["']$/g, "") ?? "";
+    }
+}
+function subindex(context, directory, label) {
+    if (!exists(context.root, directory))
+        return undefined;
+    const lines = [`# ${label}`, "", `> Auto-generated. Updated: ${date(context.now)}`, "", "| Name | Description |", "|------|-------------|"];
+    for (const entry of immediateEntries(context.root, directory, "dir")) {
+        const name = basename(entry);
+        if (!isHidden(name))
+            lines.push(`| \`${name}/\` | ${truncate(sanitize(workerDescription(`${entry}/worker.yaml`)), 100) || "—"} |`);
+    }
+    lines.push("");
+    const output = `${directory}/INDEX.md`;
+    write(context, output, lines.join("\n"));
+    log(context, `rebuild-workers-index: wrote ${output}`);
+    return output;
+}
+function rootIndex(context) {
+    const directory = "core/workers";
+    if (!exists(context.root, directory))
+        return undefined;
+    const lines = ["# Workers", "", `> Auto-generated. Updated: ${date(context.now)}`, "", "Shared workers live under `public/`. Private/local workers live under `personal/workers/`. `registry.yaml` is the auto-generated index (regenerated by core/scripts/generate-workers-registry.sh).", "", "| Name | Description |", "|------|-------------|"];
+    for (const entry of immediateEntries(context.root, directory, "dir")) {
+        const name = basename(entry);
+        if (isHidden(name))
+            continue;
+        lines.push(name === "public" ? "| `public/` | Shared public workers (see public/INDEX.md) |" : `| \`${name}/\` | ${truncate(sanitize(workerDescription(`${entry}/worker.yaml`)), 100) || "—"} |`);
+    }
+    lines.push("");
+    const output = `${directory}/INDEX.md`;
+    write(context, output, lines.join("\n"));
+    log(context, `rebuild-workers-index: wrote ${output}`);
+    return output;
+}
+export function renderWorkers(context) { const written = [subindex(context, "core/workers/public", "Public Workers"), subindex(context, "personal/workers", "Personal Workers"), rootIndex(context)].filter((value) => Boolean(value)); log(context, "rebuild-workers-index: done"); return { written }; }
+//# sourceMappingURL=workers.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

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.88.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {