@indigoai-us/hq-cli 5.115.5 → 5.116.0

package/dist/lib/agent-kit/run/mesh-listener.js

@@ -0,0 +1,193 @@
+/**
+ * Kit service: work-mesh doorbell listener.
+ *
+ * Policy hq-work-mesh-source-of-truth: the work mesh (REST) is the source of
+ * truth; MQTT carries IDS-ONLY doorbells on the agent's personal topics
+ * `hq/{agt_*}/{dm,work,sessions,notifications}`. This listener is the cache
+ * writer: on any doorbell it refetches through the REST API into
+ * ~/.hq/work-mesh/cache (warmMeshConversationCache) — message bodies are
+ * never taken from MQTT. A periodic refresh covers missed doorbells.
+ *
+ * Credentials come from the same contract-3 vend the mesh daemon uses
+ * (POST /v1/realtime/credentials); the WSS URL is SigV4-presigned. The
+ * connection is rebuilt before the vended credentials expire. `component-mesh`
+ * is stamped ok while subscribed and refreshing, error otherwise.
+ */
+import mqtt from "mqtt";
+import { warmMeshConversationCache } from "../../mesh/api.js";
+import { createContract3Fetcher, MQTT_KEEPALIVE_SECONDS, renewalDelayMs, } from "../../mesh/live/daemon/credentials.js";
+import { presignIotWssUrl } from "../../mesh/live/daemon/presign.js";
+import { writeComponentStatus } from "../creds.js";
+export const DOORBELL_KINDS = ["dm", "work", "sessions", "notifications"];
+export const DOORBELL_DEBOUNCE_MS = 2_000;
+export const RECONNECT_BASE_MS = 1_000;
+export const RECONNECT_MAX_MS = 60_000;
+export function doorbellTopics(actorUid) {
+    return DOORBELL_KINDS.map((k) => `hq/${actorUid}/${k}`);
+}
+function backoff(attempt, random) {
+    const cap = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+    return Math.max(RECONNECT_BASE_MS, Math.floor(random() * cap));
+}
+export async function startMeshListener(deps) {
+    const now = deps.now ?? (() => new Date());
+    const random = deps.random ?? Math.random;
+    const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearT = deps.clearTimeout ?? ((h) => clearTimeout(h));
+    const connect = deps.connect ?? ((url, opts) => mqtt.connect(url, opts));
+    const refetch = deps.refetch ?? ((token, uid) => warmMeshConversationCache(token, uid));
+    const fetchCredentials = deps.fetchCredentials ??
+        (async () => {
+            const token = await deps.getToken();
+            return createContract3Fetcher({ token, baseUrl: deps.apiBaseUrl })();
+        });
+    let state = "idle";
+    let client = null;
+    let stopped = false;
+    let attempt = 0;
+    let debounce = null;
+    let renewal = null;
+    let periodic = null;
+    let refetching = null;
+    let pendingReason = null;
+    const doRefetch = async (reason) => {
+        if (refetching) {
+            pendingReason = reason;
+            return refetching;
+        }
+        refetching = (async () => {
+            try {
+                const token = await deps.getToken();
+                await refetch(token, deps.agentUid);
+                writeComponentStatus(deps.paths, "mesh", state === "subscribed" ? "ok" : "error");
+                deps.log("info", `cache refetched (${reason})`);
+            }
+            catch (err) {
+                writeComponentStatus(deps.paths, "mesh", "error");
+                deps.log("error", `refetch failed (${reason}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                refetching = null;
+            }
+            if (pendingReason) {
+                const next = pendingReason;
+                pendingReason = null;
+                await doRefetch(next);
+            }
+        })();
+        return refetching;
+    };
+    const ring = (topic) => {
+        if (debounce)
+            clearT(debounce);
+        debounce = setT(() => {
+            debounce = null;
+            void doRefetch(`doorbell ${topic}`);
+        }, DOORBELL_DEBOUNCE_MS);
+    };
+    const schedulePeriodic = () => {
+        if (periodic)
+            clearT(periodic);
+        periodic = setT(() => {
+            periodic = null;
+            void doRefetch("periodic").then(schedulePeriodic);
+        }, deps.refreshMs);
+    };
+    const scheduleReconnect = () => {
+        if (stopped)
+            return;
+        const delay = backoff(attempt, random);
+        attempt += 1;
+        deps.log("warn", `mqtt reconnect in ${delay}ms (attempt ${attempt})`);
+        setT(() => void connectOnce(), delay);
+    };
+    const connectOnce = async () => {
+        if (stopped)
+            return;
+        state = "connecting";
+        let bundle;
+        try {
+            bundle = await fetchCredentials();
+            if (bundle.actorUid !== deps.agentUid) {
+                throw new Error(`realtime vend is for ${bundle.actorUid}, expected ${deps.agentUid}`);
+            }
+        }
+        catch (err) {
+            writeComponentStatus(deps.paths, "mesh", "error");
+            deps.log("error", `credential vend failed: ${err instanceof Error ? err.message : String(err)}`);
+            scheduleReconnect();
+            return;
+        }
+        const url = presignIotWssUrl(bundle.credentials, bundle.iotEndpoint, bundle.region, now());
+        const c = connect(url, {
+            clientId: bundle.clientId,
+            keepalive: MQTT_KEEPALIVE_SECONDS,
+            clean: true,
+            reconnectPeriod: 0,
+            protocolVersion: 4,
+        });
+        client = c;
+        let settled = false;
+        c.on("connect", () => {
+            c.subscribe(doorbellTopics(bundle.actorUid), { qos: 1 }, (err) => {
+                if (err) {
+                    deps.log("error", `subscribe failed: ${err.message}`);
+                    c.end(true);
+                    return;
+                }
+                settled = true;
+                attempt = 0;
+                state = "subscribed";
+                writeComponentStatus(deps.paths, "mesh", "ok");
+                deps.log("info", `subscribed to ${doorbellTopics(bundle.actorUid).length} doorbell topics`);
+                void doRefetch("connect");
+                if (renewal)
+                    clearT(renewal);
+                renewal = setT(() => {
+                    deps.log("info", "renewing realtime credentials");
+                    c.end(true);
+                }, renewalDelayMs(now().getTime(), bundle.expiresAt));
+            });
+        });
+        c.on("message", (topic) => {
+            // Ids-only doorbell: the payload is never parsed for content.
+            ring(topic);
+        });
+        c.on("error", (err) => {
+            deps.log("warn", `mqtt error: ${err.message}`);
+        });
+        c.on("close", () => {
+            if (client !== c)
+                return;
+            client = null;
+            const wasSubscribed = state === "subscribed";
+            state = stopped ? "closed" : "idle";
+            writeComponentStatus(deps.paths, "mesh", "error");
+            if (!settled || !wasSubscribed)
+                deps.log("warn", "mqtt closed before subscribe settled");
+            scheduleReconnect();
+        });
+    };
+    schedulePeriodic();
+    await connectOnce();
+    return {
+        stop: async () => {
+            stopped = true;
+            state = "closed";
+            if (debounce)
+                clearT(debounce);
+            if (renewal)
+                clearT(renewal);
+            if (periodic)
+                clearT(periodic);
+            const c = client;
+            client = null;
+            if (c)
+                await new Promise((r) => c.end(true, undefined, () => r()));
+        },
+        refetchNow: doRefetch,
+        ring,
+        state: () => state,
+    };
+}
+//# sourceMappingURL=mesh-listener.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Kit service: company vault sync loop.
+ *
+ * Mirrors the hosted box's hq-agent-sync.service, which runs hq-cloud's
+ * `hq-sync-runner --companies --direction both --on-conflict keep` on a
+ * loop and writes `component-sync`. Here the equivalent is the CLI's own
+ * `hq sync pull --all --on-conflict keep --hq-root <kit hqRoot>`, run as a
+ * child of the same node + hq binary this service was launched with, so the
+ * machine identity, creds path and version are exactly the service's own.
+ *
+ * Honest health: exit 0 = ok, anything else = error (the heartbeat turns a
+ * stale stamp into error on its own).
+ */
+import type { KitLogger } from "../log.js";
+import type { AgentKitPaths } from "../paths.js";
+export interface SyncRunDeps {
+    paths: AgentKitPaths;
+    hqRoot: string;
+    intervalMs: number;
+    log: KitLogger;
+    nodeBinary?: string;
+    hqBinary?: string;
+    /** Injected child runner (tests). Resolves with the exit code. */
+    runPull?: (args: string[]) => Promise<number>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Stop after this many passes (tests); default runs forever. */
+    maxPasses?: number;
+}
+export declare function syncPullArgs(hqRoot: string): string[];
+export declare function defaultRunPull(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<number>;
+export declare function runSyncOnce(deps: SyncRunDeps): Promise<boolean>;
+export declare function runSyncLoop(deps: SyncRunDeps): Promise<void>;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1,58 @@
+/**
+ * Kit service: company vault sync loop.
+ *
+ * Mirrors the hosted box's hq-agent-sync.service, which runs hq-cloud's
+ * `hq-sync-runner --companies --direction both --on-conflict keep` on a
+ * loop and writes `component-sync`. Here the equivalent is the CLI's own
+ * `hq sync pull --all --on-conflict keep --hq-root <kit hqRoot>`, run as a
+ * child of the same node + hq binary this service was launched with, so the
+ * machine identity, creds path and version are exactly the service's own.
+ *
+ * Honest health: exit 0 = ok, anything else = error (the heartbeat turns a
+ * stale stamp into error on its own).
+ */
+import { spawn } from "node:child_process";
+import { writeComponentStatus } from "../creds.js";
+export function syncPullArgs(hqRoot) {
+    return ["sync", "pull", "--all", "--on-conflict", "keep", "--hq-root", hqRoot];
+}
+export function defaultRunPull(nodeBinary, hqBinary, env) {
+    return (args) => new Promise((resolve) => {
+        const child = spawn(nodeBinary, [hqBinary, ...args], {
+            env,
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        child.on("error", () => resolve(127));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+export async function runSyncOnce(deps) {
+    const runPull = deps.runPull ??
+        defaultRunPull(deps.nodeBinary ?? process.execPath, deps.hqBinary ?? process.argv[1], process.env);
+    const args = syncPullArgs(deps.hqRoot);
+    deps.log("info", `sync start hq-root=${deps.hqRoot}`);
+    let code;
+    try {
+        code = await runPull(args);
+    }
+    catch (err) {
+        deps.log("error", `sync spawn failed: ${err instanceof Error ? err.message : String(err)}`);
+        code = 1;
+    }
+    const ok = code === 0;
+    writeComponentStatus(deps.paths, "sync", ok ? "ok" : "error");
+    deps.log(ok ? "info" : "error", `sync ${ok ? "ok" : `failed exit=${code}`}`);
+    return ok;
+}
+export async function runSyncLoop(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let passes = 0;
+    for (;;) {
+        await runSyncOnce(deps);
+        passes += 1;
+        if (deps.maxPasses !== undefined && passes >= deps.maxPasses)
+            return;
+        await sleep(deps.intervalMs);
+    }
+}
+//# sourceMappingURL=sync.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * The four kit services and how each is launched. Every unit runs
+ * `node hq agent kit run <service>`; the service reads kit.json and the
+ * machine-creds file itself, so the units carry paths and nothing else.
+ */
+import type { ServiceSpec } from "../service-manager/types.js";
+import type { AgentKitPaths } from "./paths.js";
+export type KitService = "sync" | "mesh" | "inbox" | "heartbeat";
+export declare const KIT_SERVICES: readonly KitService[];
+export declare const KIT_LABEL_PREFIX = "ai.getindigo.hq-agent";
+export declare function isKitService(value: string): value is KitService;
+/**
+ * Environment every service inherits. HQ_MACHINE_CREDS_FILE pins hq-cloud's
+ * mint to the kit's creds file; HQ_REQUIRE_MACHINE_IDENTITY makes a missing
+ * file a loud error instead of a browser-login hang; HQ_AGENT_DIR keeps a
+ * relocated kit consistent across restarts.
+ */
+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[];
+//# sourceMappingURL=services.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * The four kit services and how each is launched. Every unit runs
+ * `node hq agent kit run <service>`; the service reads kit.json and the
+ * machine-creds file itself, so the units carry paths and nothing else.
+ */
+import { serviceLogPath } from "./paths.js";
+export const KIT_SERVICES = ["sync", "mesh", "inbox", "heartbeat"];
+export const KIT_LABEL_PREFIX = "ai.getindigo.hq-agent";
+export function isKitService(value) {
+    return KIT_SERVICES.includes(value);
+}
+const DESCRIPTIONS = {
+    sync: "HQ agent kit: company vault sync loop",
+    mesh: "HQ agent kit: work-mesh doorbell listener",
+    inbox: "HQ agent kit: inbox poller",
+    heartbeat: "HQ agent kit: heartbeat reporter",
+};
+/**
+ * Environment every service inherits. HQ_MACHINE_CREDS_FILE pins hq-cloud's
+ * mint to the kit's creds file; HQ_REQUIRE_MACHINE_IDENTITY makes a missing
+ * file a loud error instead of a browser-login hang; HQ_AGENT_DIR keeps a
+ * relocated kit consistent across restarts.
+ */
+export function kitServiceEnv(paths) {
+    return {
+        HQ_AGENT_DIR: paths.agentDir,
+        HQ_MACHINE_CREDS_FILE: paths.machineCredsPath,
+        HQ_REQUIRE_MACHINE_IDENTITY: "1",
+    };
+}
+export function kitServiceSpec(service, paths) {
+    return {
+        name: service,
+        label: `${KIT_LABEL_PREFIX}.${service}`,
+        description: DESCRIPTIONS[service],
+        args: ["agent", "kit", "run", service],
+        logPath: serviceLogPath(paths, service),
+        workingDir: paths.agentDir,
+        env: kitServiceEnv(paths),
+        restartSec: 10,
+    };
+}
+export function kitServiceSpecs(paths) {
+    return KIT_SERVICES.map((s) => kitServiceSpec(s, paths));
+}
+//# sourceMappingURL=services.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * The skills directory the kit ships to ~/.hq-agent/skills/<name>/SKILL.md.
+ *
+ * agentskills.io format: YAML frontmatter with `name` and `description`, then
+ * markdown the bot's framework loads as an instruction. Each skill drives
+ * the `hq` CLI, which authenticates as the machine identity on its own, so
+ * no skill ever embeds or asks for a token or secret value.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export interface KitSkill {
+    name: string;
+    description: string;
+    body: string;
+}
+export declare const KIT_SKILLS: readonly KitSkill[];
+export declare function renderSkillMarkdown(skill: KitSkill): string;
+export declare function writeKitSkills(paths: Pick<AgentKitPaths, "skillsDir">): string[];
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,149 @@
+/**
+ * The skills directory the kit ships to ~/.hq-agent/skills/<name>/SKILL.md.
+ *
+ * agentskills.io format: YAML frontmatter with `name` and `description`, then
+ * markdown the bot's framework loads as an instruction. Each skill drives
+ * the `hq` CLI, which authenticates as the machine identity on its own, so
+ * no skill ever embeds or asks for a token or secret value.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const KIT_SKILLS = [
+    {
+        name: "dm",
+        description: "Send and read HQ direct messages and channel messages as this agent using the hq CLI.",
+        body: `# HQ direct messages
+
+Use the \`hq dm\` command to talk to teammates (people and other agents) in HQ.
+The CLI authenticates as this agent automatically — never ask for a token.
+
+## Send
+
+\`\`\`bash
+hq dm <email-or-uid> "message text"        # 1:1 to a person (prs_…) or agent (agt_…)
+hq dm <uid1>,<uid2> "message text"         # group DM
+hq dm '#channel-name' "message text"       # channel
+\`\`\`
+
+## Read
+
+\`\`\`bash
+hq dm inbox --unread            # unread DMs addressed to you
+hq dm thread <email-or-uid>     # the 1:1 conversation
+hq dm inbox --mark-read         # mark what you have read
+hq dm channel <name>            # read a channel
+\`\`\`
+
+New inbound messages are also mirrored by the kit's inbox poller to
+\`~/.hq-agent/inbox/<id>.json\` (and \`inbox.jsonl\`) — check there when
+you are asked whether anyone has messaged you.
+
+## Rules
+
+- Reply in the same thread you were messaged in.
+- Keep messages short; link to files in the vault instead of pasting them.
+- Never include secrets or credentials in a message.
+`,
+    },
+    {
+        name: "search",
+        description: "Search the company vault (documents, knowledge, meeting notes) with the hq CLI's local index.",
+        body: `# HQ search
+
+The company vault is synced to the kit's HQ root (see \`~/.hq-agent/kit.json\`,
+\`hqRoot\`). Search it with:
+
+\`\`\`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)
+\`\`\`
+
+If results look stale, the sync loop may not have run yet:
+\`hq sync pull --all --on-conflict keep --hq-root <hqRoot>\` pulls now.
+
+Cite the file path of anything you quote so a teammate can open it.
+`,
+    },
+    {
+        name: "files",
+        description: "Read, list and write files in the company vault through the hq CLI (hq files).",
+        body: `# HQ vault files
+
+\`\`\`bash
+hq files browse companies/<slug>/<folder>   # list a vault folder without syncing it
+hq files cat companies/<slug>/<file>        # print one file
+hq files get companies/<slug>/<file>        # fetch one file into the local HQ tree
+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.
+`,
+    },
+    {
+        name: "secrets-exec",
+        description: "Run a command with company secrets injected as environment variables, without ever printing them.",
+        body: `# Run with HQ secrets
+
+Secrets never appear in chat, logs or files. Inject them into a child
+process instead:
+
+\`\`\`bash
+hq secrets list                                   # names only, never values
+hq secrets exec --only <NAME>[,<NAME>] -- <cmd>   # run <cmd> with those vars set
+hq run <script>                                   # run a vault script with its declared secrets
+\`\`\`
+
+Rules:
+
+- Never \`echo\`, \`printenv\` or otherwise print a secret, even to "check" it.
+- Request the narrowest \`--only\` set the command needs.
+- If a secret is missing, say which NAME is missing and ask a human admin to
+  add it with \`hq secrets set\` — do not ask for the value in chat.
+`,
+    },
+    {
+        name: "work-mesh-status",
+        description: "Report and update this agent's live work status and read the team's work mesh via the hq CLI.",
+        body: `# Work mesh status
+
+The work mesh is HQ's live board of who is working on what. It is the source
+of truth for project stories and active sessions; the kit's listener keeps a
+local cache under \`~/.hq/work-mesh/cache/\`.
+
+\`\`\`bash
+hq mesh session status --company <slug>          # who is working on what right now
+hq mesh start --company <slug> --project <slug> --summary "<what you are starting>"
+hq mesh progress --company <slug> --project <slug> --summary "<what changed>"
+hq mesh blocked --company <slug> --project <slug> --summary "<what blocks you>"
+hq mesh done --company <slug> --project <slug> --summary "<what you finished>"
+hq mesh note --company <slug> --project <slug> --summary "<short note>"
+\`\`\`
+
+Post \`start\` when you pick up a piece of work and \`done\` when you finish it.
+Keep entries to one line. Presence (online / stale / offline) is derived
+from the kit heartbeat automatically — you do not need to report it.
+`,
+    },
+];
+export function renderSkillMarkdown(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(skill.description)}\n---\n\n${skill.body}`;
+}
+export function writeKitSkills(paths) {
+    const written = [];
+    for (const skill of KIT_SKILLS) {
+        const dir = path.join(paths.skillsDir, skill.name);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+        const dest = path.join(dir, "SKILL.md");
+        fs.writeFileSync(dest, renderSkillMarkdown(skill), { mode: 0o644 });
+        written.push(dest);
+    }
+    return written;
+}
+//# sourceMappingURL=skills.js.map

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -91,7 +91,26 @@ export interface SyncHealthDeps {
      * scope that is fine.
      */
     unresolvedScopes?: (journals: readonly SyncJournalSummary[]) => readonly string[];
+    /**
+     * Whether a company slug has a local `companies/<slug>` directory in the HQ
+     * tree. Leftover journal shards for companies this machine does not keep
+     * locally are NA, not WARN — a journal without a tree is not a corroborated
+     * unhealthy-sync signal, and `hq doctor --fix` has nothing local to refresh.
+     */
+    localCompanyExists?: (slug: string) => boolean;
 }
+/**
+ * True when `slug` is a filesystem-safe company folder name. Rejects empty
+ * values, path separators, and `..` so a journal slug cannot be used to probe
+ * outside `companies/`.
+ */
+export declare function isSafeCompanySlug(slug: string): boolean;
+/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
+export declare function defaultLocalCompanyExists(hqRoot: string, slug: string): boolean;
+/** True when this journal slug names a company rather than the personal tree. */
+export declare function isCompanyJournalSlug(slug: string): boolean;
+/** Company slug from a `sync.journal.<slug>` check id, or null if not one. */
+export declare function journalSlugFromCheckId(checkId: string): string | null;
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export declare const syncHealthFamily: CheckFamily;
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */

package/dist/lib/doctor/checks/sync-health.js

@@ -47,14 +47,35 @@ export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 /** The offline update cache written by the check-hq-update SessionStart hook. */
 export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
 /** Fill in the optional dependencies so call sites never branch on undefined. */
-function withDefaults(deps) {
+function withDefaults(deps, hqRoot) {
     return {
         ...deps,
         manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
         manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
         unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
+        localCompanyExists: deps.localCompanyExists ??
+            ((slug) => defaultLocalCompanyExists(hqRoot, slug)),
     };
 }
+/**
+ * True when `slug` is a filesystem-safe company folder name. Rejects empty
+ * values, path separators, and `..` so a journal slug cannot be used to probe
+ * outside `companies/`.
+ */
+export function isSafeCompanySlug(slug) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug);
+}
+/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
+export function defaultLocalCompanyExists(hqRoot, slug) {
+    if (!isSafeCompanySlug(slug))
+        return false;
+    try {
+        return fs.statSync(path.join(hqRoot, "companies", slug)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Company journal shards are unresolvable by the default collector: the
  * snapshot store keys company scopes by `companyUid`, which `listJournals()`
@@ -146,6 +167,15 @@ const NON_COMPANY_JOURNAL_SLUGS = new Set([
     PERSONAL_SCOPE_SLUG,
     PERSONAL_VAULT_SCOPE_SLUG,
 ]);
+/** True when this journal slug names a company rather than the personal tree. */
+export function isCompanyJournalSlug(slug) {
+    return !NON_COMPANY_JOURNAL_SLUGS.has(slug);
+}
+/** Company slug from a `sync.journal.<slug>` check id, or null if not one. */
+export function journalSlugFromCheckId(checkId) {
+    const match = /^sync\.journal\.(.+)$/.exec(checkId);
+    return match ? match[1] : null;
+}
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export const syncHealthFamily = {
     id: SYNC_FAMILY_ID,
@@ -154,7 +184,7 @@ export const syncHealthFamily = {
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
 export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
-    const deps = withDefaults(rawDeps);
+    const deps = withDefaults(rawDeps, context.hqRoot);
     try {
         return [
             ...versionResults(context, deps),
@@ -325,6 +355,29 @@ function journalResults(deps, journals) {
     return journals.map((entry) => {
         const lastSync = entry.journal?.lastSync;
         const checkId = `sync.journal.${entry.slug}`;
+        // A company journal without a local tree is leftover membership state,
+        // not a live sync target. WARN would make `hq doctor --fix` look like it
+        // failed to repair something it was never going to touch (US-015 health
+        // hook files remaining FAIL/WARN after the safe repair pass).
+        if (isCompanyJournalSlug(entry.slug)) {
+            let local;
+            try {
+                local = deps.localCompanyExists(entry.slug);
+            }
+            catch {
+                // Existence probe failed: fall through to the staleness check rather
+                // than hiding a possibly-live company behind NA.
+                local = true;
+            }
+            if (!local) {
+                return {
+                    status: "NA",
+                    checkId,
+                    target: entry.path,
+                    message: `Sync journal '${entry.slug}' is unused on this machine — there is no companies/${entry.slug} directory, so this journal is not a live sync target.`,
+                };
+            }
+        }
         if (typeof lastSync !== "string" || lastSync.length === 0) {
             return {
                 status: "WARN",