@indigoai-us/hq-cli 5.118.2 → 5.119.1

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [5.119.1] — 2026-09-17
+
+### Fixed
+
+- A kit.json written before `syncFiles` existed now reads as NOT syncing, the
+  same as a fresh install. 5.119.0 read it as `true` to preserve the behaviour
+  it recorded, which was wrong twice over: the bots with such a file are
+  exactly the ones the mirror is failing on, and because a bare reinstall keeps
+  recorded settings, the documented fix — reinstall the kit — left the sync
+  loop running and `hq agent probe` still pulling the whole vault. A reinstall
+  now removes that loop. A bot that genuinely wants the local mirror passes
+  `--sync-files` once.
+
+## [5.119.0] — 2026-09-17
+
+### Changed
+
+- External agents no longer copy the company vault onto their own machine.
+  `hq agent kit install` used to install a sync loop that mirrored the whole
+  vault to disk; a bot reads and writes vault files on demand through the `hq`
+  MCP server and the `hq files` commands, so the copy bought nothing for the
+  common case and cost a full download of the company's assets. On a team with
+  a large brand library that is hundreds of megabytes, and on a sandboxed bot
+  host whose egress truncates large responses it could never finish at all —
+  every file retried three times and failed with `ERR_HQ_TRUNCATED_RESPONSE`,
+  which left the probe stuck and the agent reporting a sync error while it was
+  otherwise a healthy team member.
+
+  Pass `--sync-files` if the bot genuinely needs files on disk for shell-based
+  work; a reinstall without it removes a sync loop an earlier install left
+  behind. An existing install is unchanged until it is reinstalled.
+
+- `hq agent probe` reports a `files` check in place of `team-sync`. Without a
+  local copy it proves the read path the bot actually uses — a vault listing
+  answers — instead of downloading the vault to prove a folder exists. With
+  `--sync-files` it checks the pull exactly as before.
+
+- The heartbeat reports only the components the kit runs. A component that was
+  never installed is omitted rather than reported as an error, so a bot with no
+  sync loop no longer looks broken.
+
+- `hq_search` no longer runs a local index search on an agent that has no local
+  copy, where it could only ever return nothing. It runs the server-side vault
+  search instead, and says plainly that content and semantic search need a kit
+  installed with `--sync-files`.
+
 ## [5.118.2] — 2026-09-17
 
 ### Changed

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

@@ -4181,7 +4181,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly options: readonly [];
         readonly subcommands: readonly [{
             readonly name: "install";
-            readonly description: "Install sync, work-mesh, inbox and heartbeat services plus the skills directory";
+            readonly description: "Install the work-mesh, inbox and heartbeat services plus the skills directory";
             readonly aliases: readonly [];
             readonly hidden: false;
             readonly usage: "[options]";
@@ -4189,6 +4189,12 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly options: readonly [{
                 readonly flags: "--hq-root <path>";
                 readonly description: "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)";
+            }, {
+                readonly flags: "--sync-files";
+                readonly description: "Also mirror the company vault to disk. Off by default: files are read on demand through the hq MCP server";
+            }, {
+                readonly flags: "--no-sync-files";
+                readonly description: "Do not mirror the vault to disk (default; removes the loop if an earlier install added it)";
             }, {
                 readonly flags: "--inbox-ack";
                 readonly description: "Ack mirrored inbox items on the server (default: leave acking to the bot)";

package/dist/command-catalog.generated.js

@@ -5410,7 +5410,7 @@ export const COMMAND_CATALOG = [
                 "subcommands": [
                     {
                         "name": "install",
-                        "description": "Install sync, work-mesh, inbox and heartbeat services plus the skills directory",
+                        "description": "Install the work-mesh, inbox and heartbeat services plus the skills directory",
                         "aliases": [],
                         "hidden": false,
                         "usage": "[options]",
@@ -5420,6 +5420,14 @@ export const COMMAND_CATALOG = [
                                 "flags": "--hq-root <path>",
                                 "description": "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)"
                             },
+                            {
+                                "flags": "--sync-files",
+                                "description": "Also mirror the company vault to disk. Off by default: files are read on demand through the hq MCP server"
+                            },
+                            {
+                                "flags": "--no-sync-files",
+                                "description": "Do not mirror the vault to disk (default; removes the loop if an earlier install added it)"
+                            },
                             {
                                 "flags": "--inbox-ack",
                                 "description": "Ack mirrored inbox items on the server (default: leave acking to the bot)"

package/dist/commands/agent-kit.d.ts

@@ -35,6 +35,13 @@ export interface KitInstallOptions {
     hqRoot?: string;
     inboxAck?: boolean;
     activate?: boolean;
+    /**
+     * Mirror the company vault onto local disk. Off unless asked for: a bot
+     * reads and writes vault files on demand through the `hq` MCP server, so the
+     * sync loop is not installed at all rather than installed and left failing
+     * on a host that cannot finish a full-copy download.
+     */
+    syncFiles?: boolean;
 }
 export interface KitFallbackInfo {
     mode: "fallback";

package/dist/commands/agent-kit.js

@@ -22,10 +22,10 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { readExternalMachineCreds, } from "../lib/agent-kit/creds.js";
-import { defaultKitConfig, readKitConfig, writeKitConfig, } from "../lib/agent-kit/kit-config.js";
+import { defaultKitConfig, enabledKitComponents, readKitConfig, writeKitConfig, } from "../lib/agent-kit/kit-config.js";
 import { createKitLogger } from "../lib/agent-kit/log.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
-import { isKitService, KIT_SERVICES, kitServiceSpecs, } from "../lib/agent-kit/services.js";
+import { isKitService, KIT_SERVICES, enabledKitServices, kitServiceSpec, kitServiceSpecs, } from "../lib/agent-kit/services.js";
 import { writeKitSkills } from "../lib/agent-kit/skills.js";
 import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
 import { pollInboxOnce, runInboxLoop } from "../lib/agent-kit/run/inbox.js";
@@ -76,13 +76,24 @@ export function installKit(paths, opts, host, deps = {}, fallbackDeps = {}) {
         ...existing,
         ...(opts.hqRoot ? { hqRoot: opts.hqRoot } : {}),
         ...(opts.inboxAck !== undefined ? { inboxAck: opts.inboxAck } : {}),
+        ...(opts.syncFiles !== undefined ? { syncFiles: opts.syncFiles } : {}),
         cliVersion: CLI_VERSION,
     };
     fs.mkdirSync(config.hqRoot, { recursive: true, mode: 0o700 });
     writeKitConfig(paths, config);
     const skills = writeKitSkills(paths);
     const activate = opts.activate ?? deps.activate ?? true;
-    const services = installServices(kitServiceSpecs(paths), host, {
+    // A reinstall that turns file sync off must also remove the unit an earlier
+    // install left behind, or the loop keeps running and keeps failing.
+    if (!config.syncFiles) {
+        try {
+            uninstallServices([kitServiceSpec("sync", paths)], host, deps);
+        }
+        catch {
+            /* best effort: an absent unit is the desired end state either way */
+        }
+    }
+    const services = installServices(kitServiceSpecs(paths, { syncFiles: config.syncFiles }), host, {
         ...deps,
         activate,
     });
@@ -149,6 +160,7 @@ export async function runKitService(service, rt) {
                 intervalMs: rt.config.heartbeatIntervalMs,
                 getToken: rt.getToken,
                 log: rt.log,
+                components: enabledKitComponents(rt.config),
             });
             return;
         case "inbox":
@@ -210,9 +222,10 @@ export async function runKitService(service, rt) {
 }
 /** `kit run all`: supervise the four services as child processes with restart backoff. */
 export async function runAllKitServices(rt, host) {
-    rt.log("info", `supervisor starting ${KIT_SERVICES.join(",")} agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
+    const services = enabledKitServices({ syncFiles: rt.config.syncFiles });
+    rt.log("info", `supervisor starting ${services.join(",")} agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
     const handle = superviseKitServices({
-        services: KIT_SERVICES,
+        services,
         log: rt.log,
         spawnService: (service) => {
             const fd = fs.openSync(serviceLogPath(rt.paths, service), "a", 0o600);
@@ -265,21 +278,30 @@ export function registerAgentKitCommand(agent) {
         .description("Install, inspect, or run the external-agent background services");
     kit
         .command("install")
-        .description("Install sync, work-mesh, inbox and heartbeat services plus the skills directory")
+        .description("Install the work-mesh, inbox and heartbeat services plus the skills directory")
         .option("--hq-root <path>", "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)")
+        .option("--sync-files", "Also mirror the company vault to disk. Off by default: files are read on demand through the hq MCP server")
+        .option("--no-sync-files", "Do not mirror the vault to disk (default; removes the loop if an earlier install added it)")
         .option("--inbox-ack", "Ack mirrored inbox items on the server (default: leave acking to the bot)")
         .option("--no-activate", "Write unit files but do not load them")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => {
         try {
             const paths = agentKitPaths(os.homedir(), process.env);
-            const result = installKit(paths, { hqRoot: opts.hqRoot, inboxAck: opts.inboxAck, activate: opts.activate }, resolveServiceHost(paths));
+            const result = installKit(paths, {
+                hqRoot: opts.hqRoot,
+                inboxAck: opts.inboxAck,
+                syncFiles: opts.syncFiles,
+                activate: opts.activate,
+            }, resolveServiceHost(paths));
             if (opts.json) {
                 console.log(JSON.stringify({ ok: true, ...result }, null, 2));
                 return;
             }
             console.log(chalk.green("HQ agent kit installed."));
-            console.log(`  hq root:   ${result.config.hqRoot}`);
+            console.log(result.config.syncFiles
+                ? `  files:     mirrored to ${result.config.hqRoot}`
+                : "  files:     read on demand through the hq MCP server (no local copy)");
             console.log(`  logs:      ${paths.logsDir}`);
             console.log(`  skills:    ${paths.skillsDir} (${result.skills.length} skills)`);
             if (result.fallback) {
@@ -310,7 +332,7 @@ export function registerAgentKitCommand(agent) {
         try {
             const paths = agentKitPaths(os.homedir(), process.env);
             const fallback = fallbackStatus(paths);
-            const result = servicesStatus(kitServiceSpecs(paths), resolveServiceHost(paths));
+            const result = servicesStatus(kitServiceSpecs(paths, { syncFiles: true }), resolveServiceHost(paths));
             if (opts.json) {
                 console.log(JSON.stringify({ ok: true, ...result, ...(fallback ? { fallback } : {}) }, null, 2));
                 return;
@@ -335,7 +357,7 @@ export function registerAgentKitCommand(agent) {
         try {
             const paths = agentKitPaths(os.homedir(), process.env);
             const fallback = stopFallback(paths);
-            const result = uninstallServices(kitServiceSpecs(paths), resolveServiceHost(paths));
+            const result = uninstallServices(kitServiceSpecs(paths, { syncFiles: true }), resolveServiceHost(paths));
             if (opts.json) {
                 console.log(JSON.stringify({ ok: true, ...result, fallback }, null, 2));
                 return;

package/dist/commands/agent-mcp.js

@@ -15,6 +15,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
+import { readKitConfig } from "../lib/agent-kit/kit-config.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { requireExternalCreds } from "./agent-kit.js";
 export const AGENT_MCP_SERVER_NAME = "hq-agent";
@@ -56,6 +57,7 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
     return {
         creds,
         paths,
+        syncFiles: readKitConfig(agentKitPaths(os.homedir(), process.env), CLI_VERSION).syncFiles,
         runHq: defaultRunHq(process.execPath, process.argv[1], env),
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         apiJson: async (token, path, init) => {

package/dist/commands/agent-probe.d.ts

@@ -3,7 +3,8 @@
  * team member, one line per check, non-zero exit on any failure:
  *
  *   whoami       mint as the machine identity; token names this agent
- *   team-sync    `hq sync pull --all` succeeds and the company folder exists
+ *   files        a vault listing answers on demand (or, with --sync-files, a
+ *                pull succeeds and the company folder exists)
  *   work-mesh    the personal (contract-2) realtime vend names this agent, the
  *                agent-authorized inbox route answers 200, and this host's own
  *                presence is live: a fresh last-heartbeat.json plus an ok
@@ -46,7 +47,10 @@ export interface ProbeDeps {
     hqRoot: string;
     getToken: () => Promise<string>;
     resolveCompanyUid: (token: string, slug: string) => Promise<string>;
-    runPull: (args: string[]) => Promise<number>;
+    /** Runs the `hq` CLI with these args as a child; resolves with its exit code. */
+    runHq: (args: string[]) => Promise<number>;
+    /** Mirror the vault to disk. Off by default: files are read through the API. */
+    syncFiles?: boolean;
     vendRealtime: (token: string) => Promise<{
         actorUid: string;
     }>;

package/dist/commands/agent-probe.js

@@ -3,7 +3,8 @@
  * team member, one line per check, non-zero exit on any failure:
  *
  *   whoami       mint as the machine identity; token names this agent
- *   team-sync    `hq sync pull --all` succeeds and the company folder exists
+ *   files        a vault listing answers on demand (or, with --sync-files, a
+ *                pull succeeds and the company folder exists)
  *   work-mesh    the personal (contract-2) realtime vend names this agent, the
  *                agent-authorized inbox route answers 200, and this host's own
  *                presence is live: a fresh last-heartbeat.json plus an ok
@@ -91,29 +92,55 @@ export async function runProbe(deps) {
             checks.push({ name: "company", ok: false, detail: `cannot resolve ${deps.creds.companySlug}: ${errText(err)}` });
         }
     }
-    // 2. team-sync
+    // 2. files
+    //
+    // Two shapes, because the kit has two. With file sync off (the default) the
+    // bot reads and writes vault files on demand, so what has to be proven is
+    // that a vault listing answers — not that a full local copy exists. Pulling
+    // the whole vault here would also make the probe fail for a reason that does
+    // not affect the bot: a team with a large asset library is hundreds of
+    // megabytes, and a sandboxed bot host whose egress truncates large responses
+    // can never finish it.
     if (token) {
-        try {
-            const code = await deps.runPull(syncPullArgs(deps.hqRoot));
-            const companyDir = path.join(deps.hqRoot, "companies", deps.creds.companySlug);
-            const present = fs.existsSync(companyDir);
-            const ok = code === 0 && present;
-            checks.push({
-                name: "team-sync",
-                ok,
-                detail: ok
-                    ? `synced into ${companyDir}`
-                    : code !== 0
-                        ? `hq sync pull exited ${code}`
-                        : `sync exited 0 but ${companyDir} is missing`,
-            });
+        if (deps.syncFiles) {
+            try {
+                const code = await deps.runHq(syncPullArgs(deps.hqRoot));
+                const companyDir = path.join(deps.hqRoot, "companies", deps.creds.companySlug);
+                const present = fs.existsSync(companyDir);
+                const ok = code === 0 && present;
+                checks.push({
+                    name: "files",
+                    ok,
+                    detail: ok
+                        ? `synced into ${companyDir}`
+                        : code !== 0
+                            ? `hq sync pull exited ${code}`
+                            : `sync exited 0 but ${companyDir} is missing`,
+                });
+            }
+            catch (err) {
+                checks.push({ name: "files", ok: false, detail: errText(err) });
+            }
         }
-        catch (err) {
-            checks.push({ name: "team-sync", ok: false, detail: errText(err) });
+        else {
+            const target = `companies/${deps.creds.companySlug}`;
+            try {
+                const code = await deps.runHq(["files", "browse", target]);
+                checks.push({
+                    name: "files",
+                    ok: code === 0,
+                    detail: code === 0
+                        ? `${target} is readable on demand (no local copy)`
+                        : `hq files browse ${target} exited ${code}`,
+                });
+            }
+            catch (err) {
+                checks.push({ name: "files", ok: false, detail: errText(err) });
+            }
         }
     }
     else {
-        checks.push({ name: "team-sync", ok: false, detail: "skipped: no token" });
+        checks.push({ name: "files", ok: false, detail: "skipped: no token" });
     }
     // 3. work-mesh: vend + agent-authorized reachability + self presence
     if (token && companyUid) {
@@ -258,9 +285,10 @@ export function defaultProbeDeps(paths, creds) {
         paths,
         creds,
         hqRoot: config.hqRoot,
+        syncFiles: config.syncFiles,
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
-        runPull: defaultRunPull(process.execPath, process.argv[1], process.env),
+        runHq: defaultRunPull(process.execPath, process.argv[1], process.env),
         vendRealtime: async (token) => {
             const bundle = await createPersonalRealtimeFetcher({ token, baseUrl: base })();
             return { actorUid: bundle.actorUid };

package/dist/lib/agent-kit/kit-config.d.ts

@@ -4,7 +4,7 @@
  * sync and how often. Kept separate from machine-creds.json, which is the
  * contract-shaped credential file and nothing else.
  */
-import type { AgentKitPaths } from "./paths.js";
+import { type AgentKitPaths, type KitComponent } from "./paths.js";
 export declare const DEFAULT_SYNC_INTERVAL_MS: number;
 export declare const DEFAULT_INBOX_POLL_MS = 15000;
 export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
@@ -18,9 +18,41 @@ export interface KitConfig {
     meshRefreshMs: number;
     /** Ack mirrored inbox items on the server after writing them locally. */
     inboxAck: boolean;
+    /**
+     * Mirror the company vault onto local disk.
+     *
+     * Off by default. An external bot reads and writes vault files on demand
+     * through the `hq` MCP server (hq_files_read / hq_files_list /
+     * hq_files_write) and the `hq files` CLI, so a local mirror buys nothing
+     * for the common case and costs a full copy of the company's assets — on a
+     * team with a large brand library that is hundreds of megabytes, and on a
+     * sandboxed bot host whose egress proxy truncates large responses it can
+     * never finish at all (every file retried three times, all failing with
+     * ERR_HQ_TRUNCATED_RESPONSE, leaving the probe stuck and component-sync in
+     * error while the bot was otherwise a healthy team member).
+     *
+     * Turn it on with `hq agent kit install --sync-files` when the bot genuinely
+     * needs files on disk for shell-based work (grep, build tools, a local
+     * index).
+     *
+     * A kit.json written before this field existed reads as `false`, the same as
+     * a fresh install. Reading it as `true` (its behaviour at the time) was the
+     * safer-looking choice and was wrong: the bots with such a file are exactly
+     * the ones the mirror is failing on, and because a bare reinstall preserves
+     * recorded settings, the documented fix — reinstall the kit — left the sync
+     * loop running and the probe still pulling. A bot that genuinely wants the
+     * mirror passes `--sync-files` once.
+     */
+    syncFiles: boolean;
     installedAt: string;
     cliVersion: string;
 }
+/**
+ * Kit components whose health this install actually reports. `sync` drops out
+ * when the vault is not mirrored to disk — there is no loop to be healthy or
+ * unhealthy, so reporting it either way would be a lie.
+ */
+export declare function enabledKitComponents(config: Pick<KitConfig, "syncFiles">): readonly KitComponent[];
 export declare function defaultHqRoot(paths: Pick<AgentKitPaths, "agentDir">): string;
 export declare function defaultKitConfig(paths: Pick<AgentKitPaths, "agentDir">, cliVersion: string, now?: () => Date): KitConfig;
 export declare function writeKitConfig(paths: Pick<AgentKitPaths, "kitConfigPath">, config: KitConfig): void;

package/dist/lib/agent-kit/kit-config.js

@@ -6,10 +6,19 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { KIT_COMPONENTS } from "./paths.js";
 export const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 export const DEFAULT_INBOX_POLL_MS = 15_000;
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
 export const DEFAULT_MESH_REFRESH_MS = 5 * 60_000;
+/**
+ * Kit components whose health this install actually reports. `sync` drops out
+ * when the vault is not mirrored to disk — there is no loop to be healthy or
+ * unhealthy, so reporting it either way would be a lie.
+ */
+export function enabledKitComponents(config) {
+    return KIT_COMPONENTS.filter((c) => c !== "sync" || config.syncFiles);
+}
 export function defaultHqRoot(paths) {
     return path.join(paths.agentDir, "hq");
 }
@@ -21,6 +30,7 @@ export function defaultKitConfig(paths, cliVersion, now = () => new Date()) {
         heartbeatIntervalMs: DEFAULT_HEARTBEAT_INTERVAL_MS,
         meshRefreshMs: DEFAULT_MESH_REFRESH_MS,
         inboxAck: false,
+        syncFiles: false,
         installedAt: now().toISOString(),
         cliVersion,
     };
@@ -47,6 +57,7 @@ export function readKitConfig(paths, cliVersion) {
         heartbeatIntervalMs: num("heartbeatIntervalMs"),
         meshRefreshMs: num("meshRefreshMs"),
         inboxAck: raw.inboxAck === true,
+        syncFiles: raw.syncFiles === true,
         installedAt: typeof raw.installedAt === "string" ? raw.installedAt : base.installedAt,
         cliVersion: typeof raw.cliVersion === "string" ? raw.cliVersion : base.cliVersion,
     };

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -30,6 +30,13 @@ export interface McpToolClients {
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
     getToken: () => Promise<string>;
+    /**
+     * Whether this kit mirrors the vault to disk. Off by default, and it decides
+     * what `hq_search` can honestly do: the local qmd index only exists when
+     * there is a local copy to index, so without one the search is a server-side
+     * match on file names and paths, not on contents.
+     */
+    syncFiles?: boolean;
     /** Authenticated JSON call against the control plane. */
     apiJson: (token: string, path: string, init?: {
         method?: string;

package/dist/lib/agent-kit/mcp/tools.js

@@ -99,7 +99,9 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_search",
-            description: "Search the synced company vault (local qmd index). Modes: keyword (default), semantic, hybrid.",
+            description: clients.syncFiles
+                ? "Search the synced company vault (local qmd index). Modes: keyword (default), semantic, hybrid."
+                : "Search the company vault by file name and path, server-side (no local copy is kept). Content and semantic search need a kit installed with --sync-files.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -117,6 +119,14 @@ export function buildAgentMcpTools(clients) {
                     throw new McpToolInputError('"mode" must be keyword, semantic or hybrid');
                 }
                 const count = int(args, "count", { min: 1, max: 50, fallback: 10 });
+                if (!clients.syncFiles) {
+                    // No local copy means no local index. Say so plainly instead of
+                    // running a local search that can only ever return nothing.
+                    if (mode && mode !== "keyword") {
+                        throw new McpToolInputError(`"${mode}" search needs a local copy of the vault; this agent reads files on demand. Use keyword, or reinstall the kit with \`hq agent kit install --sync-files\`.`);
+                    }
+                    return fromRun(await clients.runHq(["files", "search", query, "--company", company]), "hq files search");
+                }
                 const hqArgs = ["search", query, "--mode", mode ?? "keyword", "-n", String(count), "--json"];
                 return fromRun(await clients.runHq(hqArgs), "hq search");
             },

package/dist/lib/agent-kit/run/heartbeat.d.ts

@@ -17,7 +17,15 @@ import { type AgentKitPaths, type KitComponent } from "../paths.js";
 /** A component stamp older than this reads as error. */
 export declare const COMPONENT_STALE_AFTER_MS: Record<KitComponent, number>;
 export interface HeartbeatBody {
-    components: Record<KitComponent, ComponentStatus>;
+    /**
+     * Only the components this kit actually runs. A component that was never
+     * installed is OMITTED rather than reported `error`: with file sync off (the
+     * default — the bot reads vault files on demand through the MCP server)
+     * there is no sync loop to be unhealthy, and stamping it `error` would make
+     * every healthy bot look broken. hq-pro records the components it is sent
+     * and ignores absent names.
+     */
+    components: Partial<Record<KitComponent, ComponentStatus>>;
     cliVersion: string;
     hostInfo: {
         os: string;
@@ -26,10 +34,10 @@ export interface HeartbeatBody {
         cliVersion: string;
     };
 }
-export declare function buildHeartbeatBody(paths: Pick<AgentKitPaths, "stateDir">, now?: () => Date, hostInfo?: HeartbeatBody["hostInfo"]): HeartbeatBody;
+export declare function buildHeartbeatBody(paths: Pick<AgentKitPaths, "stateDir">, now?: () => Date, hostInfo?: HeartbeatBody["hostInfo"], components_?: readonly KitComponent[]): HeartbeatBody;
 export interface LastHeartbeat {
     at: string;
-    components: Record<KitComponent, ComponentStatus>;
+    components: Partial<Record<KitComponent, ComponentStatus>>;
     status: number;
 }
 export declare function writeLastHeartbeat(paths: Pick<AgentKitPaths, "stateDir" | "lastHeartbeatPath">, record: LastHeartbeat): void;
@@ -41,6 +49,8 @@ export interface HeartbeatDeps {
     intervalMs: number;
     getToken: () => Promise<string>;
     log: KitLogger;
+    /** Components this kit runs; defaults to all of them. */
+    components?: readonly KitComponent[];
     post?: (token: string, body: HeartbeatBody) => Promise<number>;
     now?: () => Date;
     sleep?: (ms: number) => Promise<void>;

package/dist/lib/agent-kit/run/heartbeat.js

@@ -23,9 +23,9 @@ export const COMPONENT_STALE_AFTER_MS = {
     mesh: 3 * 60_000,
     inbox: 3 * 60_000,
 };
-export function buildHeartbeatBody(paths, now = () => new Date(), hostInfo) {
+export function buildHeartbeatBody(paths, now = () => new Date(), hostInfo, components_ = KIT_COMPONENTS) {
     const components = {};
-    for (const c of KIT_COMPONENTS) {
+    for (const c of components_) {
         components[c] = readComponentStatus(paths, c, COMPONENT_STALE_AFTER_MS[c], now).status;
     }
     return {
@@ -67,7 +67,7 @@ export function defaultHeartbeatPost(agentUid, apiBaseUrl) {
 export async function beatOnce(deps) {
     const now = deps.now ?? (() => new Date());
     const post = deps.post ?? defaultHeartbeatPost(deps.agentUid, deps.apiBaseUrl);
-    const body = buildHeartbeatBody(deps.paths, now);
+    const body = buildHeartbeatBody(deps.paths, now, undefined, deps.components ?? KIT_COMPONENTS);
     try {
         const token = await deps.getToken();
         const status = await post(token, body);
@@ -75,7 +75,9 @@ export async function beatOnce(deps) {
         if (ok) {
             writeLastHeartbeat(deps.paths, { at: now().toISOString(), components: body.components, status });
         }
-        deps.log(ok ? "info" : "warn", `heartbeat ${status} sync=${body.components.sync} mesh=${body.components.mesh} inbox=${body.components.inbox}`);
+        deps.log(ok ? "info" : "warn", `heartbeat ${status} ${Object.entries(body.components)
+            .map(([name, health]) => `${name}=${health}`)
+            .join(" ")}`);
         return ok;
     }
     catch (err) {

package/dist/lib/agent-kit/services.d.ts

@@ -17,5 +17,16 @@ export declare function isKitService(value: string): value is KitService;
  */
 export declare function kitServiceEnv(paths: AgentKitPaths): Record<string, string>;
 export declare function kitServiceSpec(service: KitService, paths: AgentKitPaths): ServiceSpec;
-export declare function kitServiceSpecs(paths: AgentKitPaths): ServiceSpec[];
+/**
+ * Services to install. `sync` is included only when the kit is configured to
+ * mirror the vault to disk; by default a bot reads files on demand through the
+ * `hq` MCP server, so the loop (and its full-copy download) is not installed at
+ * all rather than installed and left failing.
+ */
+export declare function kitServiceSpecs(paths: AgentKitPaths, options?: {
+    syncFiles?: boolean;
+}): ServiceSpec[];
+export declare function enabledKitServices(options?: {
+    syncFiles?: boolean;
+}): readonly KitService[];
 //# sourceMappingURL=services.d.ts.map

package/dist/lib/agent-kit/services.js

@@ -40,7 +40,17 @@ export function kitServiceSpec(service, paths) {
         restartSec: 10,
     };
 }
-export function kitServiceSpecs(paths) {
-    return KIT_SERVICES.map((s) => kitServiceSpec(s, paths));
+/**
+ * Services to install. `sync` is included only when the kit is configured to
+ * mirror the vault to disk; by default a bot reads files on demand through the
+ * `hq` MCP server, so the loop (and its full-copy download) is not installed at
+ * all rather than installed and left failing.
+ */
+export function kitServiceSpecs(paths, options = {}) {
+    return enabledKitServices(options).map((s) => kitServiceSpec(s, paths));
+}
+export function enabledKitServices(options = {}) {
+    const syncFiles = options.syncFiles === true;
+    return KIT_SERVICES.filter((s) => s !== "sync" || syncFiles);
 }
 //# sourceMappingURL=services.js.map

package/dist/lib/agent-kit/skills.js

@@ -50,21 +50,29 @@ mark each item done.
     },
     {
         name: "search",
-        description: "Search the company vault (documents, knowledge, meeting notes) with the hq CLI's local index.",
+        description: "Find things in the company vault (documents, knowledge, meeting notes) with the hq CLI.",
         body: `# HQ search
 
-The company vault is synced to the kit's HQ root (see \`~/.hq-agent/kit.json\`,
-\`hqRoot\`). Search it with:
+By default this agent keeps no local copy of the vault, so search runs
+server-side and matches file NAMES and paths, not file contents:
 
 \`\`\`bash
-hq search "<query>"                        # ranked results across the synced vault
-hq search "<query>" --mode hybrid          # keyword + semantic
-hq search "<query>" --json                 # machine-readable
-hq files search "<query>" --company <slug> # server-side vault search (no local index needed)
+hq files search "<query>" --company <slug>   # find files by name/path
+hq files browse companies/<slug>/<folder>    # list a folder
+hq files cat companies/<slug>/<file>         # read one file
 \`\`\`
 
-If results look stale, the sync loop may not have run yet:
-\`hq sync pull --all --on-conflict keep --hq-root <hqRoot>\` pulls now.
+A good pattern for a question you cannot answer from names alone: search or
+browse to narrow to a few likely files, then read them with \`hq files cat\`.
+
+Content and semantic search need a local copy and its index, which only exists
+if the kit was installed with \`--sync-files\`. In that case (check
+\`~/.hq-agent/kit.json\` → \`syncFiles\`) you also have:
+
+\`\`\`bash
+hq search "<query>"                 # ranked full-text over the local copy
+hq search "<query>" --mode hybrid   # keyword + semantic
+\`\`\`
 
 Cite the file path of anything you quote so a teammate can open it.
 `,
@@ -82,11 +90,19 @@ hq files share companies/<slug>/<path>      # share a path with a teammate
 hq files versions companies/<slug>/<file>   # version history
 \`\`\`
 
-Paths are vault-relative and start with \`companies/<slug>/\`. The synced copy
-lives under the kit's HQ root (\`~/.hq-agent/kit.json\` → \`hqRoot\`); edit files
-there and run \`hq sync push --hq-root <hqRoot>\` to publish. Writes are
-audited under this agent's identity — only write where you were asked to,
-and prefer creating a new file over overwriting one you did not author.
+Paths are vault-relative and start with \`companies/<slug>/\`. Read them on
+demand with the commands above — this agent keeps no local copy of the vault
+unless the kit was installed with \`--sync-files\` (check \`~/.hq-agent/kit.json\`
+→ \`syncFiles\`), so never assume a file is already on disk.
+
+To publish a change you need that local copy: with \`syncFiles\` on, edit under
+the kit's HQ root (\`kit.json\` → \`hqRoot\`) and run
+\`hq sync push --hq-root <hqRoot>\`. Without it, \`hq files get\` a file, and if
+you need to write one back, say so and ask — do not improvise an upload.
+
+Writes are audited under this agent's identity — only write where you were
+asked to, and prefer creating a new file over overwriting one you did not
+author.
 `,
     },
     {

package/package.json

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