@indigoai-us/hq-cli 5.345.169 → 5.345.171

package/dist/commands/feedback.js

@@ -9,6 +9,7 @@ import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectF
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
+import { decodeJwtPayload } from "../utils/person-token-cache.js";
 import { registerFeedbackShowCommand } from "./feedback-show.js";
 import { registerFeedbackTriageCommands } from "./feedback-triage.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
@@ -223,6 +224,7 @@ export async function submitFeedback(opts) {
 export const PUBLIC_TICKET_STATES = [
     "triaged",
     "in-progress",
+    "stalled",
     "shipped",
     "verified",
     "resolved",
@@ -277,6 +279,129 @@ export async function fetchFeedbackLink(opts) {
     }
     return url;
 }
+const PR_URL_RE = /^https:\/\/[^\s/]+\/[^\s]+$/;
+/** Max `--lane` length; matches hq-pro LANE_ID_MAX_CHARS. */
+const LANE_ID_MAX_CHARS = 200;
+/** Same rule as hq-pro normalizeLaneId: non-empty, at most 200 chars, no control characters. */
+function isValidLaneId(lane) {
+    if (lane.length === 0 || lane.length > LANE_ID_MAX_CHARS)
+        return false;
+    for (let i = 0; i < lane.length; i += 1) {
+        const code = lane.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+/** Accept `in_progress` as an alias of the public `in-progress` state. */
+export function normalizePublicState(raw) {
+    const value = raw.trim().toLowerCase();
+    return value === "in_progress" ? "in-progress" : value;
+}
+/** Validate --pr/--lane for a state; in-progress needs at least one, other states take none. */
+export function buildWorkLink(state, opts) {
+    const pr = opts.pr?.trim();
+    const lane = opts.lane?.trim();
+    if (state !== "in-progress") {
+        if (pr !== undefined || lane !== undefined) {
+            throw new Error("--pr and --lane only apply to --state in-progress.");
+        }
+        return null;
+    }
+    if (!pr && !lane) {
+        throw new Error("--state in-progress needs --pr <url> or --lane <id>: a ticket is in progress only while it has an open PR or a live lane. Claiming a ticket does not need a state; use hq feedback claim.");
+    }
+    const link = {};
+    if (pr) {
+        if (!PR_URL_RE.test(pr))
+            throw new Error(`Invalid --pr '${opts.pr}': expected an https:// pull request URL.`);
+        link.prUrl = pr;
+    }
+    if (lane) {
+        if (!isValidLaneId(lane)) {
+            throw new Error(`Invalid --lane '${opts.lane}': expected a lane id of at most ${LANE_ID_MAX_CHARS} characters with no control characters.`);
+        }
+        link.laneId = lane;
+    }
+    return link;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function storedLinkMatches(row, link) {
+    if (!row)
+        return false;
+    return ((link.prUrl === undefined || row.prUrl === link.prUrl) &&
+        (link.laneId === undefined || row.laneId === link.laneId));
+}
+/** Read a feedback row with the staff GET. Returns null when it cannot be read. */
+export async function fetchFeedbackRow(opts) {
+    try {
+        const res = await vaultApiFetch({ token: opts.token, path: `/v1/feedback/${opts.id}`, method: "GET" });
+        if (!res.ok)
+            return null;
+        const data = asRecord(await res.json().catch(() => null));
+        return asRecord(data?.item);
+    }
+    catch {
+        return null;
+    }
+}
+function describeRowState(row) {
+    return typeof row?.status === "string"
+        ? `The ticket's current state is '${row.status}'.`
+        : "The ticket's current state could not be read; check it with hq feedback list.";
+}
+/** Re-read the row and describe its actual state, for error messages. */
+async function currentStateNote(id, token) {
+    return describeRowState(await fetchFeedbackRow({ id, token }));
+}
+const OLD_SERVER_HINT = "The server may not support work links yet.";
+/** Delays between read-back attempts: 3 reads over about 1s. */
+export const LINK_READBACK_DELAYS_MS = [300, 700];
+/** Overridable in tests so retries do not wait on real timers. */
+export const linkReadbackTimer = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+function sleep(ms) {
+    return linkReadbackTimer.sleep(ms);
+}
+/**
+ * Store the PR or lane link before any state change, then confirm it was
+ * saved by reading the row back. The PATCH response does not echo prUrl or
+ * laneId, and an older server ignores unknown fields, so only the GET shows
+ * the link is stored. A link-only PATCH can itself change the row (hq-pro
+ * resumes a stalled row), so errors report the row's actual state.
+ */
+export async function storeFeedbackWorkLink(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { ...opts.link },
+    });
+    if (!res.ok) {
+        const message = await readFeedbackError(res);
+        throw new Error(`The server rejected the work link for ${opts.id}: ${message}. ${OLD_SERVER_HINT} ${await currentStateNote(opts.id, opts.token)}`);
+    }
+    // The GET resolves through an eventually consistent index, so a read right
+    // after the PATCH can return the old row. Retry briefly before deciding.
+    let row = null;
+    let readOk = false;
+    for (let attempt = 0; attempt < LINK_READBACK_DELAYS_MS.length + 1; attempt += 1) {
+        if (attempt > 0)
+            await sleep(LINK_READBACK_DELAYS_MS[attempt - 1]);
+        row = await fetchFeedbackRow({ id: opts.id, token: opts.token });
+        if (row)
+            readOk = true;
+        if (storedLinkMatches(row, opts.link))
+            return;
+    }
+    if (!readOk) {
+        throw new Error(`Could not read ${opts.id} back to confirm the work link; the link may have been saved. The state was not posted; rerun the same command to retry.`);
+    }
+    throw new Error(`The server did not store the work link for ${opts.id}. ${OLD_SERVER_HINT} ${describeRowState(row)}`);
+}
 /** Post a customer-visible update; the server also mirrors it into #hq-feedback. */
 export async function postFeedbackUpdate(opts) {
     const res = await vaultApiFetch({
@@ -286,7 +411,11 @@ export async function postFeedbackUpdate(opts) {
         body: { publicUpdate: { state: opts.state, note: opts.note } },
     });
     if (!res.ok) {
-        throw new Error(`Failed to update ${opts.id}: ${await readFeedbackError(res)}`);
+        const message = await readFeedbackError(res);
+        const hint = opts.state === "stalled" && (res.status === 400 || res.status === 422)
+            ? ` The server may not support the stalled state yet. ${await currentStateNote(opts.id, opts.token)}`
+            : "";
+        throw new Error(`Failed to update ${opts.id}: ${message}${hint}`);
     }
     const data = (await res.json());
     return {
@@ -367,6 +496,41 @@ function registerAssignSubcommand(feedbackCmd) {
         }
     });
 }
+function registerClaimSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("claim")
+        .description("Assign a ticket to yourself (sets the assignee only, never the status)")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .option("--json", "Print { id, assignee } as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const token = await resolveStaffToken();
+            const email = emailFromStaffToken(token);
+            if (!email) {
+                throw new Error("hq feedback claim needs a person login with an email (hq login). Use hq feedback assign <id> <person> instead.");
+            }
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            await assignFeedback({ id, token, assignee: email });
+            if (opts.json) {
+                console.log(JSON.stringify({ id, assignee: email }));
+            }
+            else {
+                console.log(`Claimed: ${id} -> ${email}`);
+                console.log("Set --state in-progress with --pr <url> or --lane <id> once work is linked.");
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+function emailFromStaffToken(token) {
+    const claims = decodeJwtPayload(token);
+    const email = claims?.email;
+    return typeof email === "string" && email.includes("@") ? email.toLowerCase() : null;
+}
 function registerLinkSubcommand(feedbackCmd) {
     feedbackCmd
         .command("link")
@@ -393,12 +557,16 @@ function registerUpdateSubcommand(feedbackCmd) {
         .argument("<id>", "Feedback id (feedback_<uuid>)")
         .requiredOption("--state <state>", `One of: ${PUBLIC_TICKET_STATES.join(", ")}`)
         .requiredOption("--note <text>", "What the customer should read (plain text, up to 2000 characters)")
+        .option("--pr <url>", "Open pull request for this ticket (required with --state in-progress unless --lane is given)")
+        .option("--lane <id>", "Live lane working this ticket (required with --state in-progress unless --pr is given)")
         .action(async (id, opts) => {
         try {
             assertFeedbackId(id);
-            if (!PUBLIC_TICKET_STATES.includes(opts.state)) {
+            const state = normalizePublicState(opts.state);
+            if (!PUBLIC_TICKET_STATES.includes(state)) {
                 throw new Error(`Invalid --state '${opts.state}': expected one of ${PUBLIC_TICKET_STATES.join(", ")}.`);
             }
+            const link = buildWorkLink(state, opts);
             const note = opts.note.trim();
             if (note.length === 0)
                 throw new Error("--note must not be empty.");
@@ -406,13 +574,24 @@ function registerUpdateSubcommand(feedbackCmd) {
                 throw new Error("--note must be at most 2000 characters.");
             const token = await resolveStaffToken();
             assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            if (link)
+                await storeFeedbackWorkLink({ id, token, link });
             const result = await postFeedbackUpdate({
                 id,
                 token,
-                state: opts.state,
+                state: state,
                 note,
+            }).catch((err) => {
+                if (!link)
+                    throw err;
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`${message} The work link was saved; rerun the same command to set the state.`);
             });
-            console.log(`Updated: ${id} -> ${opts.state}`);
+            console.log(`Updated: ${id} -> ${state}`);
+            if (link?.prUrl)
+                console.log(`PR: ${link.prUrl}`);
+            if (link?.laneId)
+                console.log(`Lane: ${link.laneId}`);
             if (result.publicUrl)
                 console.log(`Track: ${result.publicUrl}`);
             if (result.slack === "failed") {
@@ -530,6 +709,7 @@ export function registerFeedbackCommand(program) {
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
     registerAssignSubcommand(feedbackCmd);
+    registerClaimSubcommand(feedbackCmd);
     registerFeedbackTriageCommands(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

package/dist/commands/files.d.ts

@@ -66,6 +66,48 @@ export declare class ShareSessionHttpError extends Error {
  */
 export declare function formatShareSessionError(err: ShareSessionHttpError): string;
 export declare function registerFilesCommand(program: Command): Command;
+/**
+ * True for a prefix that might name a folder without saying so: no trailing
+ * `/` (private folder), no `/*` (shared folder glob), and not the `*`
+ * wildcard, and a last segment with no extension (a name with an extension is
+ * taken as the file it names). The vault ACL treats such a path as an exact
+ * object key, so
+ * `hq files share knowledge --with x` used to grant an object named
+ * "knowledge" and nothing under `knowledge/` (DEV-5173: members were blocked
+ * under a folder their admin had "shared"). The name alone does not decide
+ * whether it is a folder (`Makefile`, `bin/hq`); resolveBareSharePrefix asks
+ * the vault.
+ */
+export declare function looksLikeBareFolderPrefix(prefix: string): boolean;
+/**
+ * Refuse a bare prefix that would become a malformed grant if it were
+ * rewritten to a folder glob: a `*` inside a segment (`**`, `know*`) or an
+ * empty segment (`/knowledge`, `a//b`). Returns the error text, or null.
+ */
+export declare function malformedBareSharePrefix(prefix: string): string | null;
+export type BareSharePrefixResolution = {
+    kind: "unchanged";
+    prefix: string;
+} | {
+    kind: "folder";
+    prefix: string;
+    folderGlob: string;
+} | {
+    kind: "refused";
+    prefix: string;
+    message: string;
+};
+/**
+ * Decide what a bare prefix means by looking it up in the vault. Rewrite `X`
+ * to `X/*` only when `X/` has children and no object `X` exists. Keep `X` when
+ * only the object exists. Refuse when both exist, when neither does, or when
+ * the lookup fails; the caller exits non-zero and points to --exact or `X/*`.
+ */
+export declare function resolveBareSharePrefix(params: {
+    token: string;
+    companyUid: string;
+    prefix: string;
+}): Promise<BareSharePrefixResolution>;
 /** Server response shape for POST /v1/files/delete. */
 export interface FilesDeleteResponse {
     prefix: string;

package/dist/commands/files.js

@@ -196,6 +196,7 @@ export function registerFilesCommand(program) {
         .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, company Outpost id (out_...), or '@all' to share with every active company member")
         .option("--permission <level>", "Permission level (only with --with): read | write")
+        .option("--exact", "With --with: grant exactly the object named by <prefix>, even when it looks like a folder (by default a bare folder name such as 'knowledge' is granted as the folder glob 'knowledge/*').")
         .option("--full", "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.")
         .option("--expires <duration>", "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.")
         .option("--no-open", "Print the share-session URL but do not launch the browser")
@@ -208,6 +209,14 @@ export function registerFilesCommand(program) {
                 console.error(chalk.red("--mention requires --channel <name>."));
                 process.exit(1);
             }
+            if (opts.exact && opts.with === undefined && opts.channel === undefined) {
+                console.error(chalk.red("--exact applies only to a direct grant and requires --with <principal> (or --channel with --mention)."));
+                process.exit(1);
+            }
+            if (opts.exact && opts.full) {
+                console.error(chalk.red("--exact cannot be combined with --full."));
+                process.exit(1);
+            }
             const companySlug = files.opts().company;
             const channelTarget = opts.channel !== undefined
                 ? await resolveShareChannelTarget({
@@ -258,6 +267,7 @@ export function registerFilesCommand(program) {
                     principal: opts.with,
                     permission: opts.permission,
                     companySlug,
+                    ...(opts.exact ? { exact: true } : {}),
                     ...channelTarget,
                 });
                 return;
@@ -278,6 +288,7 @@ export function registerFilesCommand(program) {
                         principal: uid,
                         permission,
                         companySlug,
+                        ...(opts.exact ? { exact: true } : {}),
                         ...(index === 0
                             ? {
                                 channelId: channelTarget.channelId,
@@ -302,14 +313,22 @@ export function registerFilesCommand(program) {
     });
     files
         .command("unshare <prefix>")
-        .description("Remove a named file access grant, or remove an empty ACL row or grantee-less entries without --with.")
+        .description("Remove a named file access grant, or remove an empty ACL row or grantee-less entries without --with. " +
+        "With --with, a bare name such as 'knowledge' first removes the exact 'knowledge' grant (rows from older " +
+        "`hq files share` versions) and, when none matches, the folder-glob 'knowledge/*' grant. Without --with, " +
+        "the prefix is used exactly as typed: pass 'knowledge/*' (quoted) to clean up the folder-glob row.")
         .option("--with <principal>", "Person uid, agent uid, company Outpost id (out_...), email address, group id, or '@all' to remove the grant")
+        .option("--exact", "With --with: remove the grant on exactly the object named by <prefix>. By default a bare folder name such as 'knowledge' resolves to the folder glob 'knowledge/*', the same way `hq files share` resolves it.")
         .action(async (prefix, opts) => {
         try {
+            if (opts.exact && !opts.with) {
+                console.error(chalk.red("--exact requires --with <principal>."));
+                process.exit(1);
+            }
             // Unshare MUTATES access with no preview. Anchored content paths remain
             // refused; the exact company-root ACL row is the sole exception and
             // resolves its anchor against the selected company before revoking.
-            const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+            let canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
                 mutating: true,
                 allowCompanyRootAclRow: true,
                 ...(files.opts().company !== undefined
@@ -385,40 +404,66 @@ export function registerFilesCommand(program) {
                     : `${cleanupMessage || `Removed empty ACL pattern '${canonicalPrefix}'. `}It now follows its parent folder's access, so anyone who can see that parent can see this folder.`));
                 return;
             }
-            const res = await vaultApiFetch({
-                token,
-                path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
-                method: "POST",
-                body: { prefix: canonicalPrefix, granteeType, granteeId },
-            });
-            if (!res.ok) {
+            // A bare name may carry an exact-key row from older `hq files share`
+            // versions (DEV-5173) or the folder-glob row the current share
+            // creates. Try the exact row first, then `X/*` unless the vault says
+            // X is only a file. A revoke only reduces access, so the vault lookup
+            // never blocks it: a deleted path or a failed lookup still tries both.
+            const bare = !opts.exact &&
+                companyRootSlug === undefined &&
+                looksLikeBareFolderPrefix(canonicalPrefix) &&
+                malformedBareSharePrefix(canonicalPrefix) === null;
+            const candidates = [canonicalPrefix];
+            const tried = [];
+            let aclMissingEverywhere = true;
+            for (let index = 0; index < candidates.length; index++) {
+                const candidate = candidates[index];
+                tried.push(candidate);
+                const res = await vaultApiFetch({
+                    token,
+                    path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
+                    method: "POST",
+                    body: { prefix: candidate, granteeType, granteeId },
+                });
+                if (res.ok) {
+                    console.log(chalk.green(`Removed grant for ${principalLabel} on '${displayAclPattern(candidate)}'`));
+                    if (bare && candidate === canonicalPrefix) {
+                        console.log(chalk.dim(`This removed the exact '${candidate}' grant. A grant for ${principalLabel} on ` +
+                            `'${candidate}/*', if one exists, remains; remove it with ` +
+                            `hq files unshare '${candidate}/*' --with ${principal}.`));
+                    }
+                    return;
+                }
                 const body = await res.json().catch(() => ({}));
+                if (res.status === 404) {
+                    // A 404 means ZERO rows were removed — never report a green success
+                    // that implies a revoke happened. ACL_NOT_FOUND means the prefix
+                    // has no ACL at all; GRANT_NOT_FOUND (or an older server with no
+                    // code) means the ACL exists but no grant matched this principal.
+                    if (body.code !== "ACL_NOT_FOUND")
+                        aclMissingEverywhere = false;
+                    if (bare && candidate === canonicalPrefix) {
+                        const resolution = await resolveBareSharePrefix({
+                            token,
+                            companyUid,
+                            prefix: canonicalPrefix,
+                        });
+                        // Fall back to the folder glob unless the vault confirms X is a
+                        // file with nothing under it.
+                        if (resolution.kind !== "unchanged")
+                            candidates.push(`${canonicalPrefix}/*`);
+                    }
+                    continue;
+                }
                 if (res.status === 401) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
                 else if (res.status === 403) {
                     console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
-                    await offerAccessLadder(canonicalPrefix, {
+                    await offerAccessLadder(candidate, {
                         company: files.opts().company,
                     });
                 }
-                else if (res.status === 404) {
-                    // A 404 means ZERO rows were removed — never report a green success
-                    // that implies a revoke happened. Distinguish the two causes:
-                    //   ACL_NOT_FOUND  — the prefix has no ACL at all (nothing was ever
-                    //                    shared here): genuinely, benignly absent.
-                    //   GRANT_NOT_FOUND (or an older server with no code) — the ACL
-                    //                    exists but no grant matched this principal:
-                    //                    surface it as a warning so a typo'd/stale
-                    //                    principal isn't mistaken for a real removal.
-                    if (body.code === "ACL_NOT_FOUND") {
-                        console.log(chalk.dim(`Nothing to remove — '${canonicalPrefix}' has no sharing grants.`));
-                    }
-                    else {
-                        console.warn(chalk.yellow(`No matching grant for ${principalLabel} on '${canonicalPrefix}' — nothing was removed.`));
-                    }
-                    return;
-                }
                 else if (res.status >= 500) {
                     console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
                 }
@@ -427,7 +472,18 @@ export function registerFilesCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Removed grant for ${principalLabel} on '${displayAclPattern(canonicalPrefix)}'`));
+            if (tried.length === 1) {
+                if (aclMissingEverywhere) {
+                    console.log(chalk.dim(`Nothing to remove — '${canonicalPrefix}' has no sharing grants.`));
+                }
+                else {
+                    console.warn(chalk.yellow(`No matching grant for ${principalLabel} on '${canonicalPrefix}' — nothing was removed.`));
+                }
+                return;
+            }
+            console.warn(chalk.yellow(`No matching grant for ${principalLabel} on ${tried.map((row) => `'${displayAclPattern(row)}'`).join(" or ")} ` +
+                `— nothing was removed. Check the grant with hq files acl, then re-run with --exact for the exact ` +
+                `'${canonicalPrefix}' row or pass '${canonicalPrefix}/*' (quoted) for the folder glob.`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -811,14 +867,130 @@ async function resolveMentionPersonUid(mention, companySlug) {
     console.error(chalk.red(`Could not resolve --mention '${trimmed}' to a person.`));
     process.exit(1);
 }
+/**
+ * True for a prefix that might name a folder without saying so: no trailing
+ * `/` (private folder), no `/*` (shared folder glob), and not the `*`
+ * wildcard, and a last segment with no extension (a name with an extension is
+ * taken as the file it names). The vault ACL treats such a path as an exact
+ * object key, so
+ * `hq files share knowledge --with x` used to grant an object named
+ * "knowledge" and nothing under `knowledge/` (DEV-5173: members were blocked
+ * under a folder their admin had "shared"). The name alone does not decide
+ * whether it is a folder (`Makefile`, `bin/hq`); resolveBareSharePrefix asks
+ * the vault.
+ */
+export function looksLikeBareFolderPrefix(prefix) {
+    if (prefix === "*" || prefix.endsWith("/") || prefix.endsWith("/*"))
+        return false;
+    const last = prefix.slice(prefix.lastIndexOf("/") + 1);
+    return last.length > 0 && !last.includes(".");
+}
+/**
+ * Refuse a bare prefix that would become a malformed grant if it were
+ * rewritten to a folder glob: a `*` inside a segment (`**`, `know*`) or an
+ * empty segment (`/knowledge`, `a//b`). Returns the error text, or null.
+ */
+export function malformedBareSharePrefix(prefix) {
+    if (!looksLikeBareFolderPrefix(prefix))
+        return null;
+    if (prefix.includes("*")) {
+        return (`'${prefix}' has a '*' inside a path segment. Only a whole trailing '/*' segment ` +
+            `(for example 'knowledge/*') or '*' alone (--full) is a glob.`);
+    }
+    if (prefix.split("/").some((segment) => segment.length === 0)) {
+        return `'${prefix}' has an empty path segment. Pass a company-relative path such as 'knowledge'.`;
+    }
+    return null;
+}
+/**
+ * Decide what a bare prefix means by looking it up in the vault. Rewrite `X`
+ * to `X/*` only when `X/` has children and no object `X` exists. Keep `X` when
+ * only the object exists. Refuse when both exist, when neither does, or when
+ * the lookup fails; the caller exits non-zero and points to --exact or `X/*`.
+ */
+export async function resolveBareSharePrefix(params) {
+    const { prefix } = params;
+    if (!looksLikeBareFolderPrefix(prefix))
+        return { kind: "unchanged", prefix };
+    const malformed = malformedBareSharePrefix(prefix);
+    if (malformed)
+        return { kind: "refused", prefix, message: malformed };
+    const folderGlob = `${prefix}/*`;
+    const choose = `Re-run with --exact to use exactly the object '${prefix}', or pass '${folderGlob}' ` +
+        `(quoted) to cover everything under the folder.`;
+    const list = async (listPrefix) => {
+        const res = await vaultApiFetch({
+            token: params.token,
+            path: "/v1/files/list",
+            query: { company: params.companyUid, prefix: listPrefix },
+        });
+        if (!res.ok)
+            throw new Error(`files list failed (${res.status})`);
+        const body = (await res.json());
+        return Array.isArray(body.objects) ? body.objects : [];
+    };
+    let objectExists;
+    let folderHasChildren;
+    try {
+        // The object `X` sorts first among keys that start with `X`, so the first
+        // page holds it when it exists. Children are listed separately so sibling
+        // keys such as `X-old.md` cannot push them off the page.
+        objectExists = (await list(prefix)).some((object) => object.key === prefix);
+        folderHasChildren = (await list(`${prefix}/`)).length > 0;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            kind: "refused",
+            prefix,
+            message: `Could not check whether '${prefix}' is a file or a folder (${reason}). ${choose}`,
+        };
+    }
+    if (folderHasChildren && !objectExists)
+        return { kind: "folder", prefix, folderGlob };
+    if (objectExists && !folderHasChildren)
+        return { kind: "unchanged", prefix };
+    return {
+        kind: "refused",
+        prefix,
+        message: objectExists
+            ? `'${prefix}' is both a file and a folder in the vault. ${choose}`
+            : `Nothing exists at '${prefix}' or under '${prefix}/' in the vault, so it is unclear ` +
+                `whether it is a file or a folder. ${choose}`,
+    };
+}
+/** Resolve a bare prefix for a mutating command: print the note, or exit 1 on refusal. */
+async function resolveBareSharePrefixOrExit(params) {
+    if (params.exact)
+        return params.prefix;
+    const resolution = await resolveBareSharePrefix(params);
+    if (resolution.kind === "refused") {
+        console.error(chalk.red(resolution.message));
+        process.exit(1);
+    }
+    if (resolution.kind === "folder") {
+        console.error(chalk.yellow(`Note: '${resolution.prefix}' is a folder in the vault, so this uses the folder glob ` +
+            `'${resolution.folderGlob}' (everything under it). Pass --exact to use the exact ` +
+            `object key '${resolution.prefix}' instead.`));
+        return resolution.folderGlob;
+    }
+    return resolution.prefix;
+}
 async function runDirectGrant(params) {
-    const canonicalPrefix = normalizeCompanyFilePrefix(params.prefix, {
+    let canonicalPrefix = normalizeCompanyFilePrefix(params.prefix, {
         mutating: true,
         rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
         ...(params.companySlug !== undefined
             ? { companySlug: params.companySlug }
             : {}),
     });
+    if (!params.exact) {
+        const malformed = malformedBareSharePrefix(canonicalPrefix);
+        if (malformed) {
+            console.error(chalk.red(malformed));
+            process.exit(1);
+        }
+    }
     if (!params.permission) {
         console.error(chalk.red("--permission is required when --with is set (read | write)"));
         process.exit(1);
@@ -864,6 +1036,14 @@ async function runDirectGrant(params) {
     const principalLabel = isAll ? "everyone in the company" : granteeId;
     const token = (await resolveVaultCredential()).token;
     const companyUid = await getCompanyUid(token, params.companySlug);
+    if (!params.fullVault) {
+        canonicalPrefix = await resolveBareSharePrefixOrExit({
+            token,
+            companyUid,
+            prefix: canonicalPrefix,
+            exact: params.exact,
+        });
+    }
     let res = await vaultApiFetch({
         token,
         path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
@@ -966,13 +1146,20 @@ async function runDirectGrant(params) {
 async function runShareSession(params) {
     // Validate every path before minting a session; an anchored path must never
     // silently become a share of the corresponding company-relative objects.
-    const normalizedPaths = params.paths.map((prefix) => normalizeCompanyFilePrefix(prefix, {
+    const canonicalPaths = params.paths.map((prefix) => normalizeCompanyFilePrefix(prefix, {
         mutating: true,
         rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
         ...(params.companySlug !== undefined
             ? { companySlug: params.companySlug }
             : {}),
     }));
+    for (const prefix of canonicalPaths) {
+        const malformed = malformedBareSharePrefix(prefix);
+        if (malformed) {
+            console.error(chalk.red(malformed));
+            process.exit(1);
+        }
+    }
     let expiresInMs;
     if (params.expires !== undefined) {
         const parsed = parseDuration(params.expires);
@@ -988,6 +1175,12 @@ async function runShareSession(params) {
     }
     const token = (await resolveVaultCredential()).token;
     const companyUid = await getCompanyUid(token, params.companySlug);
+    // A bare folder name in a share session would create the same exact-key row
+    // that blocked members in DEV-5173, so resolve each path like a direct grant.
+    const normalizedPaths = [];
+    for (const prefix of canonicalPaths) {
+        normalizedPaths.push(await resolveBareSharePrefixOrExit({ token, companyUid, prefix }));
+    }
     let session;
     try {
         session = await mintShareSession({