@indigoai-us/hq-cli 5.144.0 → 5.145.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.145.0] — 2026-09-23
+
+- `hq files` now preserves a trailing-slash private-folder pattern such as
+  `foo/` rather than rewriting it to `foo/*`, identifies private folders in
+  ACL and discovery output, and explains the conflict with an existing shared
+  glob. Quote a shared glob such as `'foo/*'` when invoking it from a shell.
+- `hq report` now finds reports on project channels. It listed only personal channels and treated only company-wide channels as valid, so every publish from a bot on a project channel failed with a generic deploy error. Channel lookup errors now say what went wrong.
+
 ## [5.144.0] — 2026-09-23
 
 - Worker-profile models now use the same provider catalog validation as

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

@@ -1642,7 +1642,7 @@ export declare const COMMAND_CATALOG: readonly [{
     }];
 }, {
     readonly name: "files";
-    readonly description: "Manage file access controls in HQ vault";
+    readonly description: "Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children.";
     readonly aliases: readonly [];
     readonly hidden: false;
     readonly usage: "[options] [command]";
@@ -1653,7 +1653,7 @@ export declare const COMMAND_CATALOG: readonly [{
     }];
     readonly subcommands: readonly [{
         readonly name: "share";
-        readonly description: "Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.";
+        readonly description: "Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] [paths...]";
@@ -1687,7 +1687,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "unshare";
-        readonly description: "Remove a file access grant";
+        readonly description: "Remove a file access grant. A trailing slash targets the private-folder row exactly.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] <prefix>";
@@ -1703,7 +1703,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "acl";
-        readonly description: "Show the ACL (access control list) for a file prefix";
+        readonly description: "Show the ACL (access control list) for a file prefix. foo/ is a private folder whose children are creator-only; the quoted glob 'foo/*' is shared.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] <prefix>";
@@ -1797,7 +1797,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "browse";
-        readonly description: "List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.";
+        readonly description: "List vault objects under [path] without syncing them locally. Private-folder rows (foo/) are labelled and do not imply child access; their children are creator-only. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options] [path]";
@@ -1844,7 +1844,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "shared-with-me";
-        readonly description: "List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).";
+        readonly description: "List the files/prefixes explicitly shared with you. Private folders (foo/) expose only the folder; children are creator-only. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options]";

package/dist/command-catalog.generated.js

@@ -2093,7 +2093,7 @@ export const COMMAND_CATALOG = [
     },
     {
         "name": "files",
-        "description": "Manage file access controls in HQ vault",
+        "description": "Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children.",
         "aliases": [],
         "hidden": false,
         "usage": "[options] [command]",
@@ -2107,7 +2107,7 @@ export const COMMAND_CATALOG = [
         "subcommands": [
             {
                 "name": "share",
-                "description": "Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.",
+                "description": "Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] [paths...]",
@@ -2152,7 +2152,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "unshare",
-                "description": "Remove a file access grant",
+                "description": "Remove a file access grant. A trailing slash targets the private-folder row exactly.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] <prefix>",
@@ -2173,7 +2173,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "acl",
-                "description": "Show the ACL (access control list) for a file prefix",
+                "description": "Show the ACL (access control list) for a file prefix. foo/ is a private folder whose children are creator-only; the quoted glob 'foo/*' is shared.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] <prefix>",
@@ -2296,7 +2296,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "browse",
-                "description": "List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.",
+                "description": "List vault objects under [path] without syncing them locally. Private-folder rows (foo/) are labelled and do not imply child access; their children are creator-only. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options] [path]",
@@ -2358,7 +2358,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "shared-with-me",
-                "description": "List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).",
+                "description": "List the files/prefixes explicitly shared with you. Private folders (foo/) expose only the folder; children are creator-only. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options]",

package/dist/commands/_patterns.d.ts

@@ -1,5 +1,21 @@
 export declare const SECRET_NAME_PATTERN: RegExp;
 export declare const GROUP_ID_PATTERN: RegExp;
 export declare const EMAIL_PATTERN: RegExp;
+/**
+ * Keep an ACL pattern exactly as the caller supplied it.
+ *
+ * `foo/` is a private folder row: it authorizes creating a direct child, but
+ * does not grant access to any child. `foo/*` is the distinct shared-folder
+ * glob. The server owns validation (including the conflict between them), so
+ * the CLI must never silently turn one into the other.
+ */
 export declare function normalizeFilePrefix(prefix: string): string;
+/**
+ * Make a recursive folder glob only where the caller intentionally asks for
+ * one. This is not an ACL-input normalizer: callers must opt in because a
+ * trailing slash has private-folder semantics on ACL routes.
+ */
+export declare function toSharedFolderGlob(prefix: string): string;
+/** A non-root trailing slash is the private-folder ACL pattern. */
+export declare function isPrivateFolderPattern(prefix: string): boolean;
 //# sourceMappingURL=_patterns.d.ts.map

package/dist/commands/_patterns.js

@@ -1,10 +1,27 @@
 export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]+)*$/;
 export const GROUP_ID_PATTERN = /^grp_[A-Za-z0-9_-]+$/;
 export const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+/**
+ * Keep an ACL pattern exactly as the caller supplied it.
+ *
+ * `foo/` is a private folder row: it authorizes creating a direct child, but
+ * does not grant access to any child. `foo/*` is the distinct shared-folder
+ * glob. The server owns validation (including the conflict between them), so
+ * the CLI must never silently turn one into the other.
+ */
 export function normalizeFilePrefix(prefix) {
-    if (prefix.endsWith("/")) {
-        return prefix + "*";
-    }
     return prefix;
 }
+/**
+ * Make a recursive folder glob only where the caller intentionally asks for
+ * one. This is not an ACL-input normalizer: callers must opt in because a
+ * trailing slash has private-folder semantics on ACL routes.
+ */
+export function toSharedFolderGlob(prefix) {
+    return prefix.endsWith("/") ? `${prefix}*` : prefix;
+}
+/** A non-root trailing slash is the private-folder ACL pattern. */
+export function isPrivateFolderPattern(prefix) {
+    return prefix.length > 1 && prefix.endsWith("/");
+}
 //# sourceMappingURL=_patterns.js.map

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

@@ -31,7 +31,7 @@
  * `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";
@@ -110,14 +110,18 @@ 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 type AclSource = "shared-with-you" | "creator" | "role-bypass" | "personal-vault" | "private-folder";
 export interface BrowseRow {
     key: string;
     size: number;
@@ -148,16 +152,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`

package/dist/commands/files-browse.js

@@ -31,7 +31,7 @@
  * `toCompanyAnchored`.
  *
  * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
- * methods and `grantPathToPrefix` from hq-cloud.
+ * methods from hq-cloud.
  */
 import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
@@ -40,7 +40,8 @@ import * as path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
-import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
+import { VaultClient, } from "@indigoai-us/hq-cloud";
+import { isPrivateFolderPattern } from "./_patterns.js";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, buildVaultConfig, } from "../utils/cognito-session.js";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, looksLikeCompanyUid, looksLikePersonVaultUid, vaultApiFetch, } from "../utils/vault-api.js";
@@ -70,9 +71,15 @@ export function parseCompanySlugFromPath(prefix) {
  */
 export function toBucketRelative(pathOrPrefix, slug) {
     const anchor = `companies/${slug}/`;
+    const slugAnchor = `${slug}/`;
     const normalized = pathOrPrefix.replace(/^\/+/, "");
-    return normalized.startsWith(anchor)
-        ? normalized.slice(anchor.length)
+    if (normalized.startsWith(anchor))
+        return normalized.slice(anchor.length);
+    // Explicit-grant responses can use either the full company anchor or the
+    // historical bare-slug anchor. Strip both before classification, while
+    // preserving the caller's trailing `/` versus `/*` semantics.
+    return normalized.startsWith(slugAnchor)
+        ? normalized.slice(slugAnchor.length)
         : normalized;
 }
 /**
@@ -85,22 +92,62 @@ export function toCompanyAnchored(bucketRelKey, slug) {
 }
 /**
  * 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 function classifyAclSource(bucketRelKey, grantPrefixes) {
-    for (const p of grantPrefixes) {
-        if (p === "" || bucketRelKey.startsWith(p))
+export function classifyAclSource(bucketRelKey, grantPatterns) {
+    const normalized = grantPatterns.map((entry) => typeof entry === "string"
+        ? { pattern: entry, source: undefined }
+        : entry);
+    for (const entry of normalized) {
+        const pattern = entry.pattern;
+        if (pattern === "" || pattern === "*")
             return "shared-with-you";
+        if (pattern.endsWith("/*")) {
+            if (bucketRelKey.startsWith(pattern.slice(0, -1))) {
+                return entry.source === "creator" ? "creator" : "shared-with-you";
+            }
+            continue;
+        }
+        if (isPrivateFolderPattern(pattern)) {
+            if (bucketRelKey === pattern)
+                return "private-folder";
+            continue;
+        }
+        if (bucketRelKey === pattern) {
+            return entry.source === "creator" ? "creator" : "shared-with-you";
+        }
+    }
+    // The server can expose a creator-owned child row without returning the
+    // creator's original `foo/` row. Keep the zero-byte `foo/` marker visible
+    // and label it as creator access when a creator grant is underneath it.
+    if (bucketRelKey.endsWith("/")) {
+        const creatorOwnsMarker = normalized.some((entry) => entry.source === "creator" &&
+            entry.pattern.startsWith(bucketRelKey));
+        if (creatorOwnsMarker)
+            return "creator";
     }
     return "role-bypass";
 }
+/** Remove only the redundant company anchor; retain the ACL pattern itself. */
+export function toBrowseGrantPattern(grantPath, slug) {
+    const companyRelative = toBucketRelative(grantPath, slug);
+    return companyRelative === "*" ? "" : companyRelative;
+}
+function displayAclSource(source) {
+    return source === "private-folder"
+        ? "private folder — children are creator-only"
+        : source === "creator"
+            ? "creator access — creator-only"
+            : source;
+}
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -132,7 +179,7 @@ export function formatBrowseTable(rows) {
         r.key,
         String(r.size),
         r.lastModified ? r.lastModified.toISOString() : "—",
-        r.aclSource,
+        displayAclSource(r.aclSource),
     ]);
     const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
     const renderRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
@@ -225,14 +272,17 @@ export async function runBrowse(input) {
     const listPrefix = personalMode || slug === undefined
         ? pathPrefix
         : toBucketRelative(pathPrefix, slug);
-    // Pull the caller's explicit-grant graph once so per-key classification
-    // is O(grants) without N round-trips. Grant `path`s are normalized to
-    // company-relative `startsWith` prefixes (matching the bucket key space)
-    // via `grantPathToPrefix`. Skipped in personal mode — the grants graph is a
-    // company concept; a person bucket marks every row `"personal-vault"`.
-    const grantPrefixes = personalMode || slug === undefined
+    // Pull the caller's explicit-grant graph once so per-key classification is
+    // O(grants) without N round-trips. Retain the raw pattern after stripping
+    // only the redundant company anchor: `foo/` and `foo/*` have different
+    // server semantics. Skipped in personal mode — the grants graph is a company
+    // concept; a person bucket marks every row `"personal-vault"`.
+    const grantPatterns = personalMode || slug === undefined
         ? []
-        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => grantPathToPrefix(g.path, slug));
+        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => ({
+            pattern: toBrowseGrantPattern(g.path, slug),
+            source: g.source,
+        }));
     const rows = [];
     let continuationToken;
     do {
@@ -244,8 +294,14 @@ export async function runBrowse(input) {
         for (const obj of resp.Contents ?? []) {
             if (!obj.Key)
                 continue;
-            // Skip S3 "directory marker" objects (0-byte, trailing slash).
-            if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
+            const aclSource = personalMode
+                ? "personal-vault"
+                : classifyAclSource(obj.Key, grantPatterns);
+            // Keep a private-folder marker visible so its ACL meaning can be shown.
+            // Other zero-byte directory markers remain list implementation details.
+            if (obj.Key.endsWith("/") &&
+                (obj.Size ?? 0) === 0 &&
+                aclSource !== "private-folder")
                 continue;
             // `obj.Key` is company-relative. Classify in that space, then re-anchor
             // for display so the CLI keeps speaking `companies/<slug>/...`.
@@ -255,9 +311,7 @@ export async function runBrowse(input) {
                     : toCompanyAnchored(obj.Key, slug),
                 size: obj.Size ?? 0,
                 lastModified: obj.LastModified,
-                aclSource: personalMode
-                    ? "personal-vault"
-                    : classifyAclSource(obj.Key, grantPrefixes),
+                aclSource,
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -434,14 +488,23 @@ export function formatSharedWithMeTable(rows) {
         return "Nothing is explicitly shared with you. (Owner/admin role-bypass access is not listed here — only explicit grants.)";
     }
     const cols = ["COMPANY", "PATH", "PERMISSION", "SOURCE"];
-    const data = rows.map((r) => [r.companySlug, r.path, r.permission, r.source]);
+    const data = rows.map((r) => [
+        r.companySlug,
+        isPrivateFolderPattern(r.path) ? `${r.path} (private folder)` : r.path,
+        r.permission,
+        r.source,
+    ]);
     const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
     const renderRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
-    return [
+    const lines = [
         chalk.bold(renderRow(cols)),
         chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
         ...data.map(renderRow),
-    ].join("\n");
+    ];
+    if (rows.some((row) => isPrivateFolderPattern(row.path))) {
+        lines.push("Private folders expose the folder only; children are creator-only.");
+    }
+    return lines.join("\n");
 }
 /**
  * `hq files search <query>` orchestrator. Lists the company (or personal)
@@ -863,7 +926,7 @@ export async function resolveBrowseSession() {
 export function registerFilesBrowseCommands(filesCmd) {
     filesCmd
         .command("browse [path]")
-        .description("List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.")
+        .description("List vault objects under [path] without syncing them locally. Private-folder rows (foo/) are labelled and do not imply child access; their children are creator-only. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.")
         .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>)")
         .option("--personal", "Browse the caller's canonical personal vault. [path] is treated as " +
         "bucket-relative (omit it to list the vault root). Mutually exclusive " +
@@ -1035,7 +1098,7 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
     filesCmd
         .command("shared-with-me")
-        .description("List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
+        .description("List the files/prefixes explicitly shared with you. Private folders (foo/) expose only the folder; children are creator-only. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
         .option("--company <slug>", "Scope to a single company (defaults to a cross-company roll-up).")
         .action(async (options, command) => {
         try {

package/dist/commands/files.js

@@ -4,7 +4,7 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
-import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, isPrivateFolderPattern, normalizeFilePrefix, toSharedFolderGlob, } from "./_patterns.js";
 import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
 import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
@@ -40,6 +40,27 @@ export function parseDuration(input) {
 }
 /** PRD upper bound on browser-launch share-session expiry. */
 export const MAX_SHARE_SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24h
+/** Render the ACL-specific meaning of a path without changing its wire value. */
+function displayAclPattern(prefix) {
+    return isPrivateFolderPattern(prefix)
+        ? `${prefix} (private folder)`
+        : prefix;
+}
+function privateFolderExplanation(prefix) {
+    return (`Private folder '${prefix}' — write can create only a new direct child. ` +
+        "Children are creator-only; this grant does not read, list, overwrite, or delete them.");
+}
+function formatAclPatternConflict(prefix, serverMessage) {
+    const privatePattern = prefix.endsWith("/*")
+        ? prefix.slice(0, -1)
+        : prefix.endsWith("/")
+            ? prefix
+            : `${prefix}/`;
+    const sharedPattern = `${privatePattern}*`;
+    const detail = serverMessage ? `${serverMessage}. ` : "";
+    return (`${detail}A private folder '${privatePattern}' and shared folder glob ` +
+        `'${sharedPattern}' cannot both exist. Remove the conflicting ACL pattern and retry.`);
+}
 /**
  * POST /files/{companyUid}/share-session — mint a browser-launch share
  * session token. Returns the parsed response. Throws ShareSessionHttpError
@@ -101,7 +122,7 @@ export function formatShareSessionError(err) {
 export function registerFilesCommand(program) {
     const files = program
         .command("files")
-        .description("Manage file access controls in HQ vault")
+        .description("Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children.")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     // An exported HQ_API_KEY must never fall back to the caller's Cognito session
     // (that would ignore the key's scope entirely), so every subcommand is gated.
@@ -130,7 +151,7 @@ export function registerFilesCommand(program) {
     });
     files
         .command("share [paths...]")
-        .description("Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
+        .description("Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
         .option("--with <principal>", "Email address, group id, or '@all' to share with every active company member")
         .option("--permission <level>", "Permission level (only with --with): read | write")
         .option("--full", "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.")
@@ -239,7 +260,7 @@ export function registerFilesCommand(program) {
     });
     files
         .command("unshare <prefix>")
-        .description("Remove a file access grant")
+        .description("Remove a file access grant. A trailing slash targets the private-folder row exactly.")
         .requiredOption("--with <principal>", "Email address, group id, or '@all' to remove the company-wide grant")
         .action(async (prefix, opts) => {
         try {
@@ -316,7 +337,7 @@ export function registerFilesCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Removed grant for ${principalLabel} on '${canonicalPrefix}'`));
+            console.log(chalk.green(`Removed grant for ${principalLabel} on '${displayAclPattern(canonicalPrefix)}'`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -325,7 +346,7 @@ export function registerFilesCommand(program) {
     });
     files
         .command("acl <prefix>")
-        .description("Show the ACL (access control list) for a file prefix")
+        .description("Show the ACL (access control list) for a file prefix. foo/ is a private folder whose children are creator-only; the quoted glob 'foo/*' is shared.")
         .option("--json", "Output structured ACL data, including explicit absence")
         .action(async (prefix, opts) => {
         try {
@@ -389,7 +410,10 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             const aclStatus = row?.open ? "open" : "restricted";
-            console.log(chalk.green(`ACL for ${tree.prefix} (${aclStatus})`));
+            console.log(chalk.green(`ACL for ${displayAclPattern(tree.prefix)} (${aclStatus})`));
+            if (isPrivateFolderPattern(tree.prefix)) {
+                console.log(chalk.gray(privateFolderExplanation(tree.prefix)));
+            }
             if (row) {
                 console.log(`Creator: ${row.creatorUid}`);
             }
@@ -413,7 +437,7 @@ export function registerFilesCommand(program) {
                 const PERM_W = Math.max(10, ...rows.map((e) => e.permission.length));
                 const BY_W = Math.max(10, ...rows.map((e) => e.grantedBy.length));
                 const SRC_W = showSource
-                    ? Math.max(6, ...rows.map((e) => (e.sourcePrefix ?? "").length))
+                    ? Math.max(6, ...rows.map((e) => displayAclPattern(e.sourcePrefix ?? "").length))
                     : 0;
                 const headerCols = [
                     "TYPE".padEnd(TYPE_W),
@@ -435,7 +459,7 @@ export function registerFilesCommand(program) {
                         grantedAt,
                     ];
                     if (showSource)
-                        cols.splice(4, 0, (e.sourcePrefix ?? "").padEnd(SRC_W));
+                        cols.splice(4, 0, displayAclPattern(e.sourcePrefix ?? "").padEnd(SRC_W));
                     console.log(cols.join("  "));
                 }
             }
@@ -713,6 +737,9 @@ async function runDirectGrant(params) {
         else if (res.status === 404) {
             console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
         }
+        else if (res.status === 409 && body.code === "ACL_PATTERN_CONFLICT") {
+            console.error(chalk.red(formatAclPatternConflict(canonicalPrefix, body.message)));
+        }
         else if (res.status === 409) {
             console.error(chalk.red("Concurrent modification — please retry"));
         }
@@ -731,7 +758,10 @@ async function runDirectGrant(params) {
         console.log(chalk.green(`${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`));
     }
     else {
-        console.log(chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`));
+        console.log(chalk.green(`${verb} ${params.permission} on ${displayAclPattern(printedPrefix)} to ${principalLabel}`));
+    }
+    if (isPrivateFolderPattern(printedPrefix)) {
+        console.log(chalk.gray(privateFolderExplanation(printedPrefix)));
     }
     if (typeof data.record?.error === "string" &&
         typeof data.record.status === "number" &&
@@ -1049,19 +1079,20 @@ export async function runFilesDelete(params, deps = {}) {
     const confirm = deps.confirm ?? realConfirm;
     // Strip the local company anchor before preview/confirmation (HQ-8F/HQ-CA).
     // Personal keys are already bucket-relative and must keep any such anchor.
-    // Normalize trailing `/` to `/*`, then reject the root/empty prefix before
+    // Deletion intentionally expands a folder spelling to a recursive glob, then
+    // rejects the root/empty prefix before
     // any network call, including when stripping a bare company anchor empties it.
     // The anchor names a company. Compare it with --company (refusing a
     // mismatch), and when --company was omitted ADOPT it rather than letting the
     // membership fallback pick a different company to delete from.
     const anchorSlug = companySlugFromAnchor(params.prefix, params.personal);
-    const normalized = normalizeCompanyFilePrefix(params.prefix, {
+    const normalized = toSharedFolderGlob(normalizeCompanyFilePrefix(params.prefix, {
         personal: params.personal,
         deferRootReject: true,
         ...(params.companySlug !== undefined
             ? { companySlug: params.companySlug }
             : {}),
-    });
+    }));
     if (normalized === "" || normalized === "*" || normalized === "/*") {
         console.error(chalk.red("Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key."));
         process.exit(1);

package/dist/commands/report.d.ts

@@ -1,6 +1,13 @@
 import { Command } from "commander";
 import { buildReportTarball, deployOrgContext, type ChannelReport, type DeployAccessPolicy, type ReportDeployment, type ReportPatch } from "../lib/report-publish.js";
+type ChannelRow = {
+    channelId?: string;
+    scope?: string;
+    companyUid?: string | null;
+};
 type ReportPatchInput = ReportPatch | ((current: ChannelReport) => ReportPatch);
+/** Any company-owned channel (company or project scope) can carry reports; personal channels cannot. */
+export declare function isCompanyReportChannel(channel: ChannelRow): boolean;
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
 export declare function resolveReport(token: string, reportId: string, requestedChannelId?: string): Promise<ChannelReport>;
 export declare function patchReport(token: string, report: ChannelReport, patch: ReportPatchInput): Promise<ChannelReport>;

package/dist/commands/report.js

@@ -87,22 +87,26 @@ function print(value, json) {
         console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
 async function listReportChannels(token) {
-    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+    // scope=all: the default list is personal channels only, which hid every
+    // project and company channel a report can live on.
+    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels?scope=all" });
     if (!channels.ok)
-        throw new ReportPublishError("Could not resolve the report channel.");
+        throw new ReportPublishError("Could not resolve the report channel.", "source-invalid");
     const listed = await channels.json();
     return Array.isArray(listed.channels) ? listed.channels : [];
 }
-function isCompanyReportChannel(channel) {
-    return channel.scope === "company"
-        || (typeof channel.scope !== "string" && Boolean(channel.companyUid));
+/** Any company-owned channel (company or project scope) can carry reports; personal channels cannot. */
+export function isCompanyReportChannel(channel) {
+    if (channel.scope === "personal")
+        return false;
+    return channel.scope === "company" || channel.scope === "project" || Boolean(channel.companyUid);
 }
 function requireCompanyReportChannel(channels, channelId) {
     const channel = channels.find((row) => row.channelId === channelId);
     if (!channel)
-        throw new ReportPublishError("Report channel was not found in your channels.");
+        throw new ReportPublishError("Report channel was not found in your channels.", "source-invalid");
     if (!isCompanyReportChannel(channel))
-        throw new ReportPublishError("Channel reports require a company channel.");
+        throw new ReportPublishError("Channel reports require a company channel.", "source-invalid");
 }
 async function readReportInChannel(token, channelId, reportId) {
     const res = await vaultApiFetch({ token, path: reportPath(channelId, reportId) });
@@ -121,7 +125,7 @@ export async function resolveReport(token, reportId, requestedChannelId) {
         requireCompanyReportChannel(channels, explicit);
         const res = await vaultApiFetch({ token, path: reportPath(explicit, reportId) });
         if (!res.ok)
-            throw new ReportPublishError("Report was not found in the supplied channel context.");
+            throw new ReportPublishError("Report was not found in the supplied channel context.", "source-invalid");
         const body = await res.json();
         if (!body.report)
             throw new ReportPublishError("Report response was incomplete.");

package/dist/commands/sync-narrow.js

@@ -103,6 +103,31 @@ export async function resolveNarrowTarget(input) {
         syncConfig,
     };
 }
+/**
+ * Normalize one ACL row for the local pull scope used by `sync narrow`.
+ *
+ * A trailing slash is a private-folder row, not a recursive read prefix. It
+ * lets its grantee create a new direct child, but existing children remain
+ * creator-only. Dropping that row from the prospective shared scope keeps the
+ * narrow plan from retaining private children merely because their parent
+ * happens to end in `/`. A creator's exact/child grant is still retained by
+ * the normal `grantPathToPrefix` path below.
+ */
+function narrowPrefixForGrant(grant, companySlug) {
+    let path = (grant.path ?? "").replace(/^\/+/, "");
+    const companyAnchor = `companies/${companySlug}/`;
+    const slugAnchor = `${companySlug}/`;
+    if (path.startsWith(companyAnchor)) {
+        path = path.slice(companyAnchor.length);
+    }
+    else if (path.startsWith(slugAnchor)) {
+        path = path.slice(slugAnchor.length);
+    }
+    if (path.length > 0 && path.endsWith("/") && !path.endsWith("/*")) {
+        return null;
+    }
+    return grantPathToPrefix(grant.path, companySlug);
+}
 /**
  * Compute the narrow plan for one company: fetch explicit grants, coalesce,
  * read the per-company journal, walk the local tree, classify.
@@ -118,11 +143,17 @@ export async function computeNarrowPlan(input) {
     // (grantPathToPrefix, hq-cloud ≥5.42.0): real grants are anchored
     // (`companies/<slug>/x/*`, `<slug>/x/*`) and glob-style (`x/*`, bare `*`),
     // none of which startsWith-match the company-relative local-tree keys
-    // buildNarrowPlan emits. A wildcard grant normalizes to "" (everything);
-    // coalescePrefixes drops empties, so guard it explicitly to `[""]` (which
-    // isCoveredByAny treats as covering everything → nothing orphaned) rather
-    // than letting it collapse to "nothing" and propose deleting the tree.
-    const normalizedPrefixes = grants.map((g) => grantPathToPrefix(g.path, companySlug));
+    // buildNarrowPlan emits. Private-folder rows (`x/`) are deliberately
+    // excluded: they do not grant read/list access to existing children, so
+    // treating them as recursive prefixes would leave private files on disk
+    // after an all → shared migration. A wildcard grant normalizes to ""
+    // (everything); coalescePrefixes drops empties, so guard it explicitly to
+    // `[""]` (which isCoveredByAny treats as covering everything → nothing
+    // orphaned) rather than letting it collapse to "nothing" and propose
+    // deleting the tree.
+    const normalizedPrefixes = grants
+        .map((g) => narrowPrefixForGrant(g, companySlug))
+        .filter((p) => p !== null);
     const prospectivePrefixSet = normalizedPrefixes.some((p) => p === "")
         ? [""]
         : coalescePrefixes(normalizedPrefixes);

package/dist/commands/workers.js

@@ -5,7 +5,7 @@ import * as yaml from "js-yaml";
 import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
-import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, toSharedFolderGlob } from "./_patterns.js";
 import { findHqRoot } from "../utils/manifest.js";
 export { readWorkerRegistry } from "../lib/workers-registry/read.js";
 import { readWorkerRegistry } from "../lib/workers-registry/read.js";
@@ -56,7 +56,10 @@ export function workerVaultPrefix(w) {
     const rel = w.path.startsWith(companyRoot)
         ? w.path.slice(companyRoot.length)
         : w.path;
-    return normalizeFilePrefix(rel);
+    // Worker sharing intentionally covers every child in the generated worker
+    // directory. Keep that conversion explicit: a user-supplied trailing slash
+    // on an ACL command instead means a private folder.
+    return toSharedFolderGlob(rel);
 }
 /** Classify a share principal (@all | email | grp_*) — null when invalid. */
 export function classifyPrincipal(principal) {

package/package.json

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