@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/doctor.d.ts

@@ -55,6 +55,8 @@ export interface RunDoctorOptions {
     stderr?: (chunk: string) => void;
     /** Emit the machine-readable JSON document instead of text. Default: false. */
     json?: boolean;
+    /** Resolve hq-flags independently for each company represented in sync results. */
+    resolveClientHealthReasonCodesForCompany?: (companySlug: string | null) => Promise<boolean>;
     /** In text mode, also print every PASS result. Default: false. */
     verbose?: boolean;
     /** In text mode, emit ANSI colour. Default: false (no escape sequences). */
@@ -89,6 +91,16 @@ export interface RunDoctorOptions {
     company?: string;
     /** Internal test seam; production CLI always runs integrations checks. */
     integrations?: boolean;
+    /**
+     * Run only these check families (`--only`). Omitted or empty runs them all.
+     *
+     * This exists for callers that need one family's verdict and nothing else —
+     * `core/scripts/check-hq-hooks.sh` reads six hook check ids, and `hq reindex`
+     * runs that checker on every pass. Without scoping they pay for every other
+     * family too, which on a large tree is dominated by the per-company sync
+     * journal scan. An unknown id is an error, never a silent empty run.
+     */
+    only?: readonly string[];
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {

package/dist/commands/doctor.js

@@ -23,6 +23,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { Option } from "commander";
 import { createDefaultRegistry, } from "../lib/doctor/registry.js";
 import { computeExitCode, renderText, UNKNOWN_PLATFORM, } from "../lib/doctor/report.js";
 import { buildDoctorJson, renderJson } from "../lib/doctor/json-output.js";
@@ -30,6 +31,10 @@ import { detectPlatform } from "../lib/doctor/platform.js";
 import { DEEP_FAMILY_ID, DEEP_FAMILY_TITLE, runDeepGuardTests, } from "../lib/doctor/deep/executor.js";
 import { PARITY_FAMILY_ID, PARITY_FAMILY_TITLE, runParityReplay, } from "../lib/doctor/deep/parity.js";
 import { applyFixes } from "../lib/doctor/fix/apply.js";
+import { renderDoctorFixJson } from "../lib/doctor/fix/json-output.js";
+import { clientHealthReasonCodesEnabled as isActiveCompanyClientHealthReasonCodesEnabled, clientHealthReasonCodesEnabledForCompany, } from "../lib/doctor/client-health-reason-codes-flag.js";
+import { isCompanyJournalSlug } from "../lib/doctor/checks/sync-health.js";
+import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import * as readline from "node:readline";
 import { runSideEffectTests } from "../lib/doctor/deep/sandbox.js";
 /**
@@ -93,7 +98,25 @@ export async function runDoctor(options = {}) {
             `  Run hq doctor from inside your HQ root.\n`);
         return { exitCode: 1, hqRoot: null, families: [] };
     }
-    const registry = options.registry ?? createDefaultRegistry();
+    const fullRegistry = options.registry ?? createDefaultRegistry();
+    const requested = options.only && options.only.length > 0 ? [...options.only] : undefined;
+    let registry = fullRegistry;
+    let scope;
+    if (requested) {
+        const selection = fullRegistry.select(requested);
+        // The deep families are appended by `--deep-test` rather than registered,
+        // so they are addressable only when that flag is present — naming one
+        // without it is the same mistake as naming a family that does not exist.
+        const appendable = options.deepTest ? [DEEP_FAMILY_ID, PARITY_FAMILY_ID] : [];
+        const unknown = selection.unknown.filter((id) => !appendable.includes(id));
+        if (unknown.length > 0) {
+            writeErr(`hq doctor --only: unknown check ${unknown.length === 1 ? "family" : "families"}: ${unknown.join(", ")}\n` +
+                `  Available: ${[...fullRegistry.ids(), ...appendable].join(", ")}\n`);
+            return { exitCode: 1, hqRoot, families: [] };
+        }
+        registry = selection.registry;
+        scope = [...registry.ids(), ...appendable.filter((id) => requested.includes(id))];
+    }
     const platform = options.platform ?? UNKNOWN_PLATFORM;
     // The detected platform and the session id are exposed to every check so the
     // host-specific runtime probe (US-006) can decide UNKNOWN vs FAIL vs UNTESTED.
@@ -111,7 +134,11 @@ export async function runDoctor(options = {}) {
     // own family. Run only when asked — appending here, not in the default
     // registry, is what keeps `hq doctor` from ever spawning a hook without the
     // flag. Any FAIL/UNKNOWN it produces flows through computeExitCode below.
-    if (options.deepTest) {
+    // The deep families are appended here rather than registered, so the `--only`
+    // filter has to be applied to them explicitly — otherwise
+    // `--only hooks --deep-test` would still sandbox-fire every hook.
+    const inScope = (id) => !requested || requested.includes(id);
+    if (options.deepTest && inScope(DEEP_FAMILY_ID)) {
         const deepResults = await runDeepGuardTests(context);
         // US-009: side-effecting hooks (autocommit, checkpoint, journal, reindex, …)
         // cannot be verified by verdict, so they run in throwaway sandboxes and their
@@ -122,10 +149,12 @@ export async function runDoctor(options = {}) {
             family: { id: DEEP_FAMILY_ID, title: DEEP_FAMILY_TITLE },
             results: [...deepResults, ...effectResults],
         });
-        // Cross-platform parity replay (US-010): replay every pure-guard fixture
-        // case through the Claude, Codex, and Grok adapters and compare verdicts, so
-        // platform drift surfaces as a test result. Also gated behind --deep-test,
-        // and it too runs only in its own sandbox — never the live tree.
+    }
+    // Cross-platform parity replay (US-010): replay every pure-guard fixture
+    // case through the Claude, Codex, and Grok adapters and compare verdicts, so
+    // platform drift surfaces as a test result. Also gated behind --deep-test,
+    // and it too runs only in its own sandbox — never the live tree.
+    if (options.deepTest && inScope(PARITY_FAMILY_ID)) {
         const parityResults = await runParityReplay(context);
         families.push({
             family: { id: PARITY_FAMILY_ID, title: PARITY_FAMILY_TITLE },
@@ -133,7 +162,16 @@ export async function runDoctor(options = {}) {
         });
     }
     if (options.json) {
-        write(renderJson(buildDoctorJson({ hqRoot, families, platform })));
+        const clientHealthReasonCodesEnabledCheckIds = options.resolveClientHealthReasonCodesForCompany
+            ? await resolveClientHealthReasonCodesCheckIds(families, options.resolveClientHealthReasonCodesForCompany)
+            : undefined;
+        write(renderJson(buildDoctorJson({
+            hqRoot,
+            families,
+            platform,
+            scope,
+            clientHealthReasonCodesEnabledCheckIds,
+        })));
     }
     else {
         write(renderText({
@@ -148,6 +186,61 @@ export async function runDoctor(options = {}) {
     // UNTESTED, NA, and KNOWN-DEFECT are reported but never fail the command.
     return { exitCode: computeExitCode(families), hqRoot, families };
 }
+async function resolveClientHealthReasonCodesCheckIds(families, resolveForCompany) {
+    const checksByCompany = new Map();
+    for (const run of families) {
+        if (run.family.id !== "sync")
+            continue;
+        for (const result of run.results) {
+            if (result.reasonCode === undefined ||
+                (result.status !== "FAIL" && result.status !== "WARN")) {
+                continue;
+            }
+            const scoped = /^sync\.(?:journal|manifest)\.(.+)$/.exec(result.checkId);
+            const companySlug = scoped && isCompanyJournalSlug(scoped[1]) ? scoped[1] : null;
+            const checkIds = checksByCompany.get(companySlug) ?? [];
+            checkIds.push(result.checkId);
+            checksByCompany.set(companySlug, checkIds);
+        }
+    }
+    const enabledChecks = new Set();
+    const decisions = await Promise.all([...checksByCompany.entries()].map(async ([companySlug, checkIds]) => ({
+        checkIds,
+        enabled: await resolveForCompany(companySlug),
+    })));
+    for (const decision of decisions) {
+        if (decision.enabled) {
+            for (const checkId of decision.checkIds)
+                enabledChecks.add(checkId);
+        }
+    }
+    return enabledChecks;
+}
+function createClientHealthReasonCodeCompanyResolver(hqRoot) {
+    const companies = readCompaniesManifestMap(hqRoot);
+    return async (companySlug) => {
+        if (companySlug === null) {
+            return isActiveCompanyClientHealthReasonCodesEnabled();
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(companySlug)) {
+            return false;
+        }
+        const manifestUid = companies?.[companySlug]?.cloud_uid;
+        const activeSlug = process.env.HQ_COMPANY_SLUG?.trim() || "";
+        const activeUid = process.env.HQ_COMPANY_UID?.trim() || "";
+        const companyUid = typeof manifestUid === "string" && manifestUid.trim()
+            ? manifestUid.trim()
+            : companySlug === activeSlug
+                ? activeUid
+                : "";
+        if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid))
+            return false;
+        return clientHealthReasonCodesEnabledForCompany({
+            companyUid,
+            companySlug,
+        });
+    };
+}
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
 export function registerDoctorCommand(program) {
     program
@@ -160,18 +253,42 @@ export function registerDoctorCommand(program) {
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
         .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
         .option("--company <slug>", "Company slug for integrations checks (otherwise resolves your single active company).")
+        .option("--only <families>", "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
+        .addOption(new Option("--client-health-report", "Resolve the opt-in hq-flags gate used by the client-health report hook.").hideHelp())
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
         .action(async (opts) => {
+        // `--fix` repairs the whole tree from its own allowlist and has no
+        // notion of a check family, so a scope passed alongside it could only
+        // be ignored. Ignoring it silently is the dangerous reading: an
+        // operator who wrote `--only sync --fix` would believe they had scoped
+        // hook configuration out of a write, and `--only typo --fix` would slip
+        // past the unknown-family rejection. Refuse the combination instead.
+        if (opts.fix === true && parseOnly(opts.only) !== undefined) {
+            process.stderr.write(`hq doctor: --only cannot be combined with --fix.\n` +
+                `  --fix applies the allowlisted repairs across the whole tree; it has no family scope.\n` +
+                `  Inspect with \`hq doctor --only ${parseOnly(opts.only)?.join(",")}\`, then repair with \`hq doctor --fix\`.\n`);
+            process.exitCode = 1;
+            return;
+        }
         // `--fix` is the only write path. It resolves the tree, applies the
         // allowlisted repairs behind a backup + confirmation, and returns its own
         // exit code; the read-only report below never runs in this branch.
         if (opts.fix === true) {
             const hqRoot = resolveHqRoot();
             if (!hqRoot) {
-                process.stderr.write(`hq doctor --fix: not inside an HQ tree.\n` +
-                    `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n`);
+                if (opts.json === true) {
+                    process.stdout.write(renderDoctorFixJson({
+                        exitCode: 1,
+                        refused: "outside-hq-tree",
+                        applied: [],
+                    }));
+                }
+                else {
+                    process.stderr.write(`hq doctor --fix: not inside an HQ tree.\n` +
+                        `  Looking for a directory containing all of: ${HQ_ROOT_MARKERS.join(", ")}\n`);
+                }
                 process.exitCode = 1;
                 return;
             }
@@ -179,8 +296,14 @@ export function registerDoctorCommand(program) {
                 hqRoot,
                 yes: opts.yes === true,
                 force: opts.force === true,
-                confirm: promptYesNo,
+                confirm: () => promptYesNo(opts.json === true ? process.stderr : process.stdout),
+                ...(opts.json === true
+                    ? { stdout: () => { }, stderr: () => { } }
+                    : {}),
             });
+            if (opts.json === true) {
+                process.stdout.write(renderDoctorFixJson(fixResult));
+            }
             process.exitCode = fixResult.exitCode;
             return;
         }
@@ -199,6 +322,14 @@ export function registerDoctorCommand(program) {
             id: detection.platform,
             evidence: detection.evidence,
         };
+        const clientHealthReasonCodesResolver = json && opts.clientHealthReport === true
+            ? (() => {
+                const hqRoot = resolveHqRoot();
+                return hqRoot
+                    ? createClientHealthReasonCodeCompanyResolver(hqRoot)
+                    : undefined;
+            })()
+            : undefined;
         const result = await runDoctor({
             json,
             verbose: opts.verbose === true,
@@ -208,6 +339,8 @@ export function registerDoctorCommand(program) {
             deepTest: opts.deepTest === true,
             liveRuntimes: opts.liveRuntimes === true,
             company: opts.company,
+            only: parseOnly(opts.only),
+            resolveClientHealthReasonCodesForCompany: clientHealthReasonCodesResolver,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an
@@ -215,17 +348,30 @@ export function registerDoctorCommand(program) {
         process.exitCode = result.exitCode;
     });
 }
+/**
+ * Split `--only` into family ids. Blank entries are dropped so a trailing comma
+ * or a quoted empty string reads as "no scope" rather than as a family named "".
+ */
+function parseOnly(value) {
+    if (value === undefined)
+        return undefined;
+    const ids = value
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    return ids.length > 0 ? ids : undefined;
+}
 /**
  * Interactive y/N confirmation for `--fix`. Resolves false on a non-TTY stdin
  * (so a piped run without `--yes` writes nothing) and on anything other than an
  * explicit yes.
  */
-function promptYesNo() {
+function promptYesNo(output = process.stdout) {
     if (!process.stdin.isTTY)
         return Promise.resolve(false);
     const rl = readline.createInterface({
         input: process.stdin,
-        output: process.stdout,
+        output,
     });
     return new Promise((resolve) => {
         rl.question("Apply these repairs? [y/N] ", (answer) => {

package/dist/commands/feedback.d.ts

@@ -3,6 +3,8 @@ import { type DiagnosticsBlob } from "../utils/feedback-diagnostics.js";
 import { collectFeedbackLogs, feedbackLogsEnabled } from "../utils/feedback-logs.js";
 import { type LogBundleRef } from "../utils/feedback-log-bundle.js";
 export declare const BODY_MAX_BYTES: number;
+/** Validate fields that must be valid before feedback attachments are uploaded. */
+export declare function validateFeedbackContent(title: string, body: string): void;
 /**
  * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
  * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
@@ -36,6 +38,10 @@ export interface FeedbackSubmitOptions {
      * stays a summary and this carries the rest.
      */
     logBundle?: LogBundleRef;
+    /** Diagnostics collected before uploads by the command path. */
+    diagnostics?: DiagnosticsBlob;
+    /** Precomputed setting so environment lookup happens before attachments upload. */
+    logsEnabled?: boolean;
 }
 export declare function readBodyFile(bodyFile: string, stdin?: NodeJS.ReadableStream): Promise<string>;
 /**

package/dist/commands/feedback.js

@@ -1,12 +1,25 @@
 import * as fs from "node:fs";
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
+import { assertVaultApiRequestSupported, vaultApiFetch, } from "../utils/vault-api.js";
 import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
 import { MAX_SCREENSHOTS, uploadScreenshots } from "../utils/feedback-screenshots.js";
 import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectFeedbackLogs, feedbackLogsEnabled, } from "../utils/feedback-logs.js";
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 export const BODY_MAX_BYTES = 64 * 1024;
+/** Validate fields that must be valid before feedback attachments are uploaded. */
+export function validateFeedbackContent(title, body) {
+    if (title.trim().length === 0) {
+        throw new Error("title must not be empty. Provide a short, non-whitespace title via --title.");
+    }
+    if (body.trim().length === 0) {
+        throw new Error("body must not be empty. Provide at least one non-whitespace character.");
+    }
+    const bodyBytes = Buffer.byteLength(body, "utf8");
+    if (bodyBytes > BODY_MAX_BYTES) {
+        throw new Error(`Body exceeds 64 KiB limit (${bodyBytes} bytes). Reduce the body size before submitting.`);
+    }
+}
 /**
  * Mirror of the server's `MAX_BODY_BYTES` in hq-pro
  * `src/vault-service/handlers/feedback.ts`, which rejects the WHOLE request
@@ -16,12 +29,36 @@ export const BODY_MAX_BYTES = 64 * 1024;
  * logs are budgeted against whatever headroom is left between them.
  */
 export const REQUEST_MAX_BYTES = 64 * 1024;
+/** Reject JSON envelopes that hq-pro would refuse with HTTP 413. */
+function validateFeedbackRequestSize(requestBody) {
+    const requestBytes = Buffer.byteLength(JSON.stringify(requestBody), "utf8");
+    if (requestBytes > REQUEST_MAX_BYTES) {
+        throw new Error(`Request exceeds 64 KiB limit (${requestBytes} bytes). Reduce the feedback content before submitting.`);
+    }
+}
 /**
  * Headroom held back for the `"logs":{...}` JSON envelope itself — its keys,
  * braces, and the escaping of the tail text. The final size is re-measured
  * after attaching, so this reserve only needs to be roughly right.
  */
 const LOGS_ENVELOPE_RESERVE_BYTES = 1024;
+function buildFeedbackRequestBody(opts) {
+    const requestBody = {
+        type: opts.type,
+        title: opts.title,
+        body: opts.body,
+        diagnostics: opts.diagnostics,
+    };
+    if (opts.company) {
+        requestBody.company = opts.company;
+    }
+    if (opts.screenshots && opts.screenshots.length > 0) {
+        requestBody.screenshots = opts.screenshots;
+    }
+    if (opts.logBundle)
+        requestBody.logBundle = opts.logBundle;
+    return requestBody;
+}
 export async function readBodyFile(bodyFile, stdin) {
     if (bodyFile === "-") {
         const stream = stdin ?? process.stdin;
@@ -79,48 +116,32 @@ export function attachDebugLogs(requestBody, diagnostics, enabled, deps = {}) {
     }
 }
 export async function submitFeedback(opts) {
-    // Validate the title locally, symmetric with the body check below. Commander's
-    // `requiredOption("--title")` only requires the flag to be PRESENT — an empty
-    // or whitespace-only value (`--title ""`, or a title the /hq-bug skill derived
-    // to nothing) passes the flag check, then the server rejects it with a 400
-    // "title (non-empty string) is required" that floods Sentry as a context-free
-    // warning (HQ-AB). Catch it here so the caller gets a clear, actionable error
-    // and the bad request never reaches the server.
-    if (opts.title.trim().length === 0) {
-        throw new Error("title must not be empty. Provide a short, non-whitespace title via --title.");
-    }
-    if (opts.body.trim().length === 0) {
-        throw new Error("body must not be empty. Provide at least one non-whitespace character.");
-    }
-    const bodyBytes = Buffer.byteLength(opts.body, "utf8");
-    if (bodyBytes > BODY_MAX_BYTES) {
-        throw new Error(`Body exceeds 64 KiB limit (${bodyBytes} bytes). Reduce the body size before submitting.`);
-    }
-    const diagnostics = collectDiagnostics();
-    const requestBody = {
+    // Keep submitFeedback safe for direct callers as well as the command path,
+    // which invokes the same validator before uploading any attachments.
+    validateFeedbackContent(opts.title, opts.body);
+    const diagnostics = opts.diagnostics ?? collectDiagnostics();
+    const requestBody = buildFeedbackRequestBody({
         type: opts.type,
         title: opts.title,
         body: opts.body,
+        company: opts.company,
         diagnostics,
-    };
-    if (opts.company) {
-        requestBody.company = opts.company;
-    }
-    if (opts.screenshots && opts.screenshots.length > 0) {
-        requestBody.screenshots = opts.screenshots;
-    }
-    // The bundle reference is four small fields, so unlike the inline logs below
-    // it needs no budgeting — but it is added BEFORE attachDebugLogs so those
-    // bytes are counted against the inline budget rather than overrunning it.
-    if (opts.logBundle) {
-        requestBody.logBundle = opts.logBundle;
-    }
+        screenshots: opts.screenshots,
+        logBundle: opts.logBundle,
+    });
+    // Direct callers can supply attachment references; ensure the complete base
+    // envelope still fits before adding optional inline logs or making a request.
+    validateFeedbackRequestSize(requestBody);
     // Debug logs are attached LAST and sized against the headroom the rest of
     // the request left behind. The server 413s the whole body over 64 KiB, so a
     // fixed log budget would turn a previously-working large-body submission
     // into a hard failure. Measuring the real serialized envelope — the exact
     // bytes vaultApiFetch will send — is what makes that impossible.
-    attachDebugLogs(requestBody, diagnostics, opts.includeLogs !== false);
+    attachDebugLogs(requestBody, diagnostics, opts.includeLogs !== false, {
+        envEnabled: opts.logsEnabled === undefined
+            ? feedbackLogsEnabled
+            : () => opts.logsEnabled === true,
+    });
     const res = await vaultApiFetch({
         token: opts.token,
         path: "/v1/feedback",
@@ -155,8 +176,34 @@ function registerSubcommand(feedbackCmd, type) {
         try {
             const token = await ensureCognitoToken({ interactive: false });
             const body = await readBodyFile(opts.bodyFile);
-            // Validate + upload screenshots (direct-to-S3 via presigned PUT)
-            // before submitting, so the row references uploaded objects.
+            validateFeedbackContent(opts.title, body);
+            // Resolve every required local input before creating S3 objects. These
+            // diagnostics are passed through so submitFeedback does not collect
+            // them again after attachments have been uploaded.
+            const diagnostics = collectDiagnostics();
+            const logsEnabled = opts.logs !== false && feedbackLogsEnabled();
+            // Validate the serialized server request envelope before screenshots
+            // or the log bundle can create remote objects. Attachment references
+            // are added and checked again inside submitFeedback after upload.
+            validateFeedbackRequestSize(buildFeedbackRequestBody({
+                type,
+                title: opts.title,
+                body,
+                company: opts.company,
+                diagnostics,
+            }));
+            // vaultApiFetch can reject an hqk_ token or an invalid API base URL
+            // locally before fetch. Check the mandatory POST, and the screenshot
+            // presign when requested, before any upload can create an orphan.
+            assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
+            if ((opts.screenshot ?? []).length > 0) {
+                assertVaultApiRequestSupported({
+                    token,
+                    path: "/v1/feedback/screenshots/presign",
+                });
+            }
+            // Upload screenshots (direct-to-S3 via presigned PUT) before the
+            // submission, so the row references uploaded objects.
             const screenshots = await uploadScreenshots({
                 paths: opts.screenshot ?? [],
                 token,
@@ -167,7 +214,7 @@ function registerSubcommand(feedbackCmd, type) {
             // this resolves undefined and the report still carries inline logs.
             const logBundle = await uploadLogBundle({
                 token,
-                enabled: opts.logs !== false && feedbackLogsEnabled(),
+                enabled: logsEnabled,
             });
             const result = await submitFeedback({
                 type,
@@ -178,6 +225,8 @@ function registerSubcommand(feedbackCmd, type) {
                 screenshots,
                 includeLogs: opts.logs !== false,
                 logBundle,
+                diagnostics,
+                logsEnabled,
             });
             console.log(`Submitted: ${result.id}`);
         }

package/dist/commands/files-browse.d.ts

@@ -31,11 +31,14 @@
  * `toCompanyAnchored`.
  *
  * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
- * methods and `grantPathToPrefix` from hq-cloud.
+ * methods from hq-cloud.
  */
 import { Command } from "commander";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
 import { VaultClient, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type AclSource } from "../utils/files-browse-acl.js";
+export { ACL_SOURCE_DISPLAY_LABELS, displayAclSource } from "../utils/files-browse-acl.js";
+export type { AclSource } from "../utils/files-browse-acl.js";
 /** STS-vended credential set the browse/cat path consumes. */
 export interface BrowseCredentials {
     accessKeyId: string;
@@ -110,14 +113,17 @@ export type CompanyBrowseClientFactory = (input: {
 /**
  * ACL provenance for a single listed key.
  *   - `shared-with-you`: an explicit grant the caller holds covers the key.
+ *   - `creator`: a creator-only child grant (or its folder marker) covers the
+ *      key; this is explicit creator access, not an owner/admin role bypass.
  *   - `role-bypass`: the caller has no covering explicit grant, but
  *      owner/admin role widened the browse-vend policy to include it.
  *   - `personal-vault`: the key lives in the caller's own person-entity
  *      vault, where no grants graph applies — the caller is the only
  *      principal with access by construction. Emitted only when
  *      `runBrowse({ personalMode: true })`.
+ *   - `private-folder`: this is the private folder row itself. Its children
+ *      are creator-only, so it never covers a child key.
  */
-export type AclSource = "shared-with-you" | "role-bypass" | "personal-vault";
 export interface BrowseRow {
     key: string;
     size: number;
@@ -148,16 +154,23 @@ export declare function toBucketRelative(pathOrPrefix: string, slug: string): st
 export declare function toCompanyAnchored(bucketRelKey: string, slug: string): string;
 /**
  * Classify a single company-relative S3 key against the caller's
- * (already-normalized) explicit-grant prefixes. Any prefix that covers the
- * key contributes `shared-with-you`; otherwise the key is visible only via
- * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
- * prefix is a company-wide grant and matches everything.
+ * raw explicit-grant patterns. `foo/*` covers all keys below `foo/`, while
+ * `foo/` is the private folder itself and never covers a child key. Otherwise
+ * the key is visible only via the owner/admin role-bypass the `/sts/vend`
+ * policy applied. An empty-string prefix is a company-wide grant and matches
+ * everything.
  *
- * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
- * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
- * calling this — keeping this helper pure and trivially testable.
+ * The caller translates only the redundant company anchor before calling this;
+ * it must not coalesce a trailing slash into a glob, which would imply child
+ * access that the server did not grant.
  */
-export declare function classifyAclSource(bucketRelKey: string, grantPrefixes: string[]): AclSource;
+export declare function classifyAclSource(bucketRelKey: string, grantPatterns: Array<string | BrowseGrantPattern>): AclSource;
+export interface BrowseGrantPattern {
+    pattern: string;
+    source?: ExplicitGrant["source"];
+}
+/** Remove only the redundant company anchor; retain the ACL pattern itself. */
+export declare function toBrowseGrantPattern(grantPath: string, slug: string): string;
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -439,6 +452,12 @@ export declare function createCompanyPresignClient(input: {
      * (keys on these errors are bucket-relative and carry no slug).
      */
     companySlug?: string;
+    /**
+     * Control-plane origin for list/presign calls. Defaults to
+     * DEFAULT_VAULT_API_URL (via vaultApiFetch); an enrolled agent passes its
+     * own `apiBaseUrl` so its token only goes to the API it enrolled against.
+     */
+    baseUrl?: string;
 }): FilesBrowseS3Client;
 /**
  * Production company-mode client factory — closes over the caller's token and
@@ -485,6 +504,7 @@ export declare function resolveBrowseSession(): Promise<{
  * and registers `share`/`unshare`/`acl`; this function appends the two
  * new browse-vs-sync subcommands so they share the `--company` switch.
  */
-export declare function registerFilesBrowseCommands(filesCmd: Command): void;
-export {};
+export declare function registerFilesBrowseCommands(filesCmd: Command, deps?: {
+    personalS3Factory?: S3ClientFactory;
+}): void;
 //# sourceMappingURL=files-browse.d.ts.map