@indigoai-us/hq-cli 5.144.0 → 5.146.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.146.0] — 2026-09-23
+
+### Fixed
+
+- The mesh daemon asks for presence in the device-default company and the companies with a session updated in the last day (at most five), and asks again within a minute when that set changes. `hq mesh doctor` says when a company was left out because presence is off or because one credential cannot cover every company.
+- `hq mesh project ensure` closes a genesis thread only when that same call created it and register returns a different server `proj-` thread. An already-open project thread stays open on a re-run. The register route does not accept a client thread id.
+- `hq mesh project ensure` on a new project closes the client genesis thread when register returns the server `proj-` thread, so the project has one open thread. The register route does not accept a client thread id.
+- A session that registers or creates a project is bound to it. `hq mesh project ensure` and `hq mesh project set --create` bind the calling session when it is the same company and still `needs_project` or unresolved, and they leave a session that is already on a different project alone. The next prompt re-checks `needs_project` against the current catalog. `hq mesh context prd-sync --session <sid> --file <prd.json>` emits `task_status` when a bound session's story `passes` or `status` changes (`passes: true` is done, `in_progress` is in progress) and does not call the network when nothing changed.
+- `hq report publish` now fills a report's missing company from its channel and keeps it across updates. Before, a report saved without a company was published under a personal access policy and the deploy refused it.
+
+## [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
@@ -50,6 +68,7 @@
 ### Fixed
 
 - `hq lanes monitor-check` now recognizes a live Claude Monitor task launched through the CLI's shell/node process wrapper, so active lanes are not reported as uncovered.
+
 - A session hint now binds to the best existing project. An exact Board is used as-is. An exact local PRD gets a Board through the same genesis-thread, view, then register path as `project ensure`, and is bound. A single clear match is bound with a recorded reason. When nothing matches, or two candidates are close, the session stays `needs_project` and the start hook lists the candidates. `hq mesh context bind-project` applies the answer. A flush HTTP 404 downgrades that session, holds its events, and logs one line instead of dead-lettering them. `hq mesh doctor` lists `needs_project` sessions.
 
 ## [5.139.0] — 2026-09-23

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]";
@@ -5882,6 +5882,24 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "prd-sync";
+            readonly description: "Emit task_status for PRD story passes/status changes on a bound session";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--session <sid>";
+                readonly description: "Canonical session id";
+            }, {
+                readonly flags: "--file <path>";
+                readonly description: "prd.json written by the bound session";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "organize";
             readonly description: "List or submit one-time project/task decisions (US-007B / US-005B)";

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]",
@@ -7593,6 +7593,29 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "prd-sync",
+                        "description": "Emit task_status for PRD story passes/status changes on a bound session",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--session <sid>",
+                                "description": "Canonical session id"
+                            },
+                            {
+                                "flags": "--file <path>",
+                                "description": "prd.json written by the bound session"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "organize",
                         "description": "List or submit one-time project/task decisions (US-007B / US-005B)",

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 {