@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/commands/access.js

@@ -1,5 +1,5 @@
 /**
- * `hq access <path-or-query>` — existence + ACL probe with a self-healing
+ * `hq access <path-or-query...>` — existence + ACL probe with a self-healing
  * ladder: resolve, list, probe ACL, then (with --fix) download / pin / repair
  * sync or request access from the grantor.
  *
@@ -85,6 +85,10 @@ function normalizeTarget(raw, slug) {
     const anchor = `companies/${slug}/`;
     if (t.startsWith(anchor))
         t = t.slice(anchor.length);
+    // `folder`, `folder/` and `folder/*` name the same folder for the ACL
+    // resolver (policy hq-authorization-path-canonicalization); use one form for
+    // listing and ACL lookups.
+    t = t.replace(/\/\*$/, "").replace(/\/+$/, "");
     return t;
 }
 function fileGrantCoversPath(grantPath, targetPath) {
@@ -123,41 +127,6 @@ function httpStatusOf(err) {
     }
     return undefined;
 }
-/**
- * List under `prefix`. A 403 from the list route (`/v1/files/list`) means the
- * caller cannot enumerate the prefix — surfaced as `{ denied: true }` so the
- * caller maps it to outcome `no-access` (exit 3) instead of a bare error.
- */
-async function listKeys(s3, bucket, prefix) {
-    try {
-        return { keys: await listKeysOrThrow(s3, bucket, prefix), denied: false };
-    }
-    catch (err) {
-        if (httpStatusOf(err) === 403)
-            return { keys: [], denied: true };
-        throw err;
-    }
-}
-async function listKeysOrThrow(s3, bucket, prefix) {
-    const keys = [];
-    let continuationToken;
-    do {
-        const resp = (await s3.send(new ListObjectsV2Command({
-            Bucket: bucket,
-            Prefix: prefix,
-            ContinuationToken: continuationToken,
-        })));
-        for (const obj of resp.Contents ?? []) {
-            if (!obj.Key)
-                continue;
-            if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
-                continue;
-            keys.push(obj.Key);
-        }
-        continuationToken = resp.NextContinuationToken ?? undefined;
-    } while (continuationToken);
-    return keys;
-}
 function treeIsEmpty(tree) {
     const noDirect = tree.directRow == null;
     const noInherited = !tree.inherited || tree.inherited.length === 0;
@@ -233,19 +202,15 @@ function grantorLabel(g) {
     const name = g.name ? `${g.name} ` : "";
     return `${name}${g.email}`.trim();
 }
-export async function runAccess(input) {
-    const { deps, json } = input;
-    const log = deps.log ?? ((line) => console.log(line));
-    const stderr = deps.stderr ?? ((line) => console.error(line));
-    const slug = deps.companySlug;
-    const steps = [];
-    const relative = normalizeTarget(input.target, slug);
-    const anchored = (key) => `companies/${slug}/${key}`;
-    const finishCtx = { hqRoot: deps.hqRoot, now: deps.now, stderr };
-    let vendDenied = false;
+/**
+ * One STS vend for the company. A 403 is a company-boundary denial, a 422
+ * write-scope truncation still allows presigned reads, a 404 is reported and
+ * tolerated; anything else is thrown.
+ */
+async function vendForAccess(deps) {
     try {
         await deps.vaultClient.sts.vend({ companyUid: deps.companyUid });
-        steps.push("vend: ok");
+        return { denied: false, step: "vend: ok" };
     }
     catch (err) {
         const status = httpStatusOf(err);
@@ -253,29 +218,98 @@ export async function runAccess(input) {
             ? err
             : undefined;
         if (status === 403) {
-            vendDenied = true;
-            steps.push("vend: 403 (no-access)");
+            return { denied: true, step: "vend: 403 (no-access)" };
         }
-        else if ((status === 422 || vendError?.statusCode === 422) &&
+        if ((status === 422 || vendError?.statusCode === 422) &&
             vendError?.code === "POLICY_WRITE_SCOPE_TRUNCATED") {
             // This failure means the company-wide STS write policy could not fit.
             // Company reads use the separate ACL-filtered presign API, which remains
             // the authority for listing and materializing this particular object.
-            steps.push("vend: write policy truncated; using presigned read");
-        }
-        else if (status === 404) {
-            steps.push("vend: 404");
+            return { denied: false, step: "vend: write policy truncated; using presigned read" };
         }
-        else {
-            throw err;
+        if (status === 404) {
+            return { denied: false, step: "vend: 404" };
         }
+        throw err;
     }
-    const entity = await deps.vaultClient.entity.findInMyNamespace("company", slug);
-    const bucket = entity?.bucketName ?? `hq-vault-cmp-${slug}`;
-    const s3 = deps.companyClient({ companyUid: deps.companyUid });
+}
+/**
+ * Mark a promise that runs ahead of its use. A rejection is not reported as
+ * unhandled; it still surfaces at the point the promise is awaited.
+ */
+function startEarly(promise) {
+    promise.catch(() => undefined);
+    return promise;
+}
+function verdictDenied(verdict) {
+    return verdict.kind === "tree" ? aclDenied(verdict.tree) : false;
+}
+/** Bucket name for the company: the entity's bucket, else the conventional name. */
+function bucketFor(entity, slug) {
+    return entity?.bucketName ?? `hq-vault-cmp-${slug}`;
+}
+/**
+ * One list request under `prefix`, never followed by a continuation. A 403
+ * from the list route (`/v1/files/list`) means the caller cannot enumerate
+ * the prefix, surfaced as `{ denied: true }` so the caller maps it to outcome
+ * `no-access` (exit 3) instead of a bare error.
+ */
+async function listPage(s3, bucket, prefix) {
+    let resp;
+    try {
+        resp = (await s3.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix })));
+    }
+    catch (err) {
+        if (httpStatusOf(err) === 403)
+            return { keys: [], truncated: false, denied: true };
+        throw err;
+    }
+    const keys = [];
+    for (const obj of resp.Contents ?? []) {
+        if (!obj.Key)
+            continue;
+        if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
+            continue;
+        keys.push(obj.Key);
+    }
+    return {
+        keys,
+        truncated: Boolean(resp.IsTruncated || resp.NextContinuationToken),
+        denied: false,
+    };
+}
+/**
+ * Fuzzy-match pool for a miss: one page under the closest parent folder that
+ * has keys, walking up from the deepest. A bare query with no folder part has
+ * only the bucket root as its parent, so it gets one root page. A denied
+ * parent stops the walk and is reported as denied.
+ */
+async function listClosestParent(s3, bucket, relative) {
+    const segments = relative.split("/");
+    if (segments.length === 1)
+        return listPage(s3, bucket, "");
+    for (let depth = segments.length - 1; depth >= 1; depth -= 1) {
+        const parent = `${segments.slice(0, depth).join("/")}/`;
+        const page = await listPage(s3, bucket, parent);
+        if (page.denied || page.keys.length > 0)
+            return page;
+    }
+    return { keys: [], truncated: false, denied: false };
+}
+/**
+ * Existence + ACL for one target: exact key first, then a folder check, then a
+ * bounded fuzzy match. Every list call is a single page.
+ */
+async function locateTarget(target, deps, ctx) {
+    const slug = deps.companySlug;
+    const steps = [ctx.vend.step];
+    const relative = normalizeTarget(target, slug);
+    const anchored = (key) => `companies/${slug}/${key}`;
+    const { s3, bucket } = ctx;
     let listDenied = false;
+    let directory = false;
     let key;
-    if (vendDenied) {
+    if (ctx.vend.denied) {
         // The caller is denied at the company boundary. Do not use list results to
         // resolve or disclose matching keys, even if a separate listing succeeds.
         listDenied = true;
@@ -283,8 +317,24 @@ export async function runAccess(input) {
         steps.push("list: skipped after vend 403 (no-access)");
     }
     else {
-        const prefixList = await listKeys(s3, bucket, relative);
-        const exact = prefixList.keys.find((k) => k === relative);
+        const prefixList = await listPage(s3, bucket, relative);
+        // An exact key sorts first among the keys that start with it, so the
+        // first page always holds it when it exists.
+        const exact = prefixList.keys.includes(relative);
+        const folderPrefix = `${relative}/`;
+        let isFolder = !exact &&
+            relative !== "" &&
+            prefixList.keys.some((k) => k.startsWith(folderPrefix));
+        if (!prefixList.denied &&
+            !exact &&
+            !isFolder &&
+            relative !== "" &&
+            prefixList.truncated) {
+            // Siblings such as `name-other/` sort before `name/` and can fill the
+            // first page; ask for the folder itself.
+            const folderList = await listPage(s3, bucket, folderPrefix);
+            isFolder = !folderList.denied && folderList.keys.length > 0;
+        }
         if (prefixList.denied) {
             // The server refused to enumerate — the caller has no read on this
             // prefix. Keep the target as the key so the request rung can still name
@@ -294,45 +344,58 @@ export async function runAccess(input) {
             steps.push("list: 403 (no-access)");
         }
         else if (exact) {
-            key = exact;
+            key = relative;
             steps.push("resolve: exact key");
             steps.push("list: 1 hit");
         }
+        else if (isFolder) {
+            key = relative;
+            directory = true;
+            steps.push("resolve: folder");
+            steps.push("list: 1 hit");
+        }
         else {
-            const allList = await listKeys(s3, bucket, "");
             const q = relative.toLowerCase();
-            // A root-list 403 only says the caller cannot enumerate the WHOLE bucket.
-            // The prefix list above succeeded, so fuzzy-match within it first; the
-            // root denial is the verdict only when the readable prefix has no match.
-            const pool = allList.denied ? prefixList.keys : allList.keys;
+            // Keys under the target prefix already contain the query. Only when
+            // there are none, look one page under the closest existing parent.
+            const parentList = prefixList.keys.length > 0
+                ? { keys: [], truncated: false, denied: false }
+                : await listClosestParent(s3, bucket, relative);
+            const pool = [
+                ...new Set([...prefixList.keys, ...parentList.keys]),
+            ].sort();
             const fuzzy = pool.filter((k) => k.toLowerCase().includes(q));
-            if (allList.denied && fuzzy.length === 0) {
+            if (parentList.denied && fuzzy.length === 0) {
                 listDenied = true;
                 key = relative;
                 steps.push("list: 403 (no-access)");
             }
             else if (fuzzy.length === 0) {
                 steps.push("list: 0 hits");
-                const tree = await deps.fetchAclTree(relative);
-                if (aclDenied(tree)) {
+                const verdict = await ctx.aclFor(relative);
+                if (verdictDenied(verdict)) {
                     steps.push("acl: deny");
-                    const result = finish("no-access", {
-                        path: anchored(relative) || input.target,
+                    return {
+                        kind: "terminal",
+                        outcome: "no-access",
+                        fields: {
+                            path: anchored(relative) || target,
+                            company: slug,
+                            exists: true,
+                            steps,
+                        },
+                    };
+                }
+                return {
+                    kind: "terminal",
+                    outcome: "never-existed",
+                    fields: {
+                        path: anchored(relative) || target,
                         company: slug,
-                        exists: true,
+                        exists: false,
                         steps,
-                    }, finishCtx);
-                    emit(input, result, log);
-                    return result;
-                }
-                const result = finish("never-existed", {
-                    path: anchored(relative) || input.target,
-                    company: slug,
-                    exists: false,
-                    steps,
-                }, finishCtx);
-                emit(input, result, log);
-                return result;
+                    },
+                };
             }
             else if (fuzzy.length === 1) {
                 key = fuzzy[0];
@@ -343,42 +406,70 @@ export async function runAccess(input) {
                 const candidates = fuzzy.map(anchored);
                 steps.push(`list: ${fuzzy.length} hits`);
                 let picked = null;
-                if (deps.pick) {
+                if (ctx.allowPick && deps.pick) {
                     picked = await deps.pick(candidates);
                 }
                 if (!picked) {
-                    const result = finish("ambiguous", {
-                        path: input.target,
-                        company: slug,
-                        exists: false,
-                        candidates,
-                        steps,
-                    }, finishCtx);
-                    emit(input, result, log);
-                    return result;
+                    return {
+                        kind: "terminal",
+                        outcome: "ambiguous",
+                        fields: {
+                            path: target,
+                            company: slug,
+                            exists: false,
+                            candidates,
+                            steps,
+                        },
+                    };
                 }
-                const stripped = normalizeTarget(picked, slug);
-                key = stripped;
+                key = normalizeTarget(picked, slug);
                 steps.push("resolve: pick");
             }
         }
     }
     const resolvedKey = key;
-    const resolvedPath = anchored(resolvedKey);
-    const tree = await deps.fetchAclTree(resolvedKey);
+    const verdict = await ctx.aclFor(resolvedKey);
+    return {
+        kind: "found",
+        resolvedKey,
+        directory,
+        vendDenied: ctx.vend.denied,
+        listDenied,
+        verdict,
+        steps,
+    };
+}
+async function resolveRequester(requester) {
+    return typeof requester === "function" ? requester() : requester;
+}
+/**
+ * Disk check, self-heal and request rung for one located target, then the
+ * single telemetry record via `finish`.
+ */
+async function completeTarget(input, deps, located) {
+    const { json } = input;
+    const log = deps.log ?? ((line) => console.log(line));
+    const stderr = deps.stderr ?? ((line) => console.error(line));
+    const slug = deps.companySlug;
+    const finishCtx = { hqRoot: deps.hqRoot, now: deps.now, stderr };
+    if (located.kind === "terminal") {
+        return finish(located.outcome, located.fields, finishCtx);
+    }
+    const { resolvedKey, directory, vendDenied, listDenied, verdict, steps } = located;
+    const resolvedPath = `companies/${slug}/${resolvedKey}`;
     let noAccess = vendDenied || listDenied;
-    if (tree == null || treeIsEmpty(tree)) {
+    if (verdict.kind === "resolved") {
+        steps.push(`acl: ${verdict.permission}`);
+    }
+    else if (verdict.tree == null || treeIsEmpty(verdict.tree)) {
         steps.push("acl: no record (membership-distributed)");
     }
-    else if (aclDenied(tree)) {
+    else if (aclDenied(verdict.tree)) {
         noAccess = true;
         steps.push("acl: deny");
     }
     else {
-        steps.push(`acl: ${tree.effectivePermission ?? "ok"}`);
-    }
-    if (vendDenied || listDenied) {
-        noAccess = true;
+        steps.push(`acl: ${verdict.tree.effectivePermission ?? "ok"}`);
     }
     const onDisk = fs.existsSync(path.join(deps.hqRoot, "companies", slug, resolvedKey));
     steps.push(onDisk ? "disk: present" : "disk: missing");
@@ -394,7 +485,11 @@ export async function runAccess(input) {
     }
     let fixed;
     let localPath;
-    if (outcome === "not-synced" && input.fix === true && !noAccess) {
+    if (outcome === "not-synced" && input.fix === true && directory) {
+        // `get` fetches one object; a folder is pulled by sync.
+        steps.push("get: skipped (folder; run hq sync)");
+    }
+    else if (outcome === "not-synced" && input.fix === true && !noAccess) {
         const absLocal = path.join(deps.hqRoot, "companies", slug, resolvedKey);
         const getFn = deps.get ??
             ((anchoredPath) => runGet({
@@ -492,8 +587,9 @@ export async function runAccess(input) {
             steps.push("request: no dm transport");
         }
         else {
+            const grantorTree = verdict.kind === "tree" ? verdict.tree : await deps.fetchAclTree(resolvedKey);
             const members = await deps.listMembers();
-            const resolved = resolveGrantor(tree, members);
+            const resolved = resolveGrantor(grantorTree, members);
             if (!resolved) {
                 steps.push("request: no grantor found");
                 requestNote = "No grantor found. Contact a company owner.";
@@ -508,8 +604,9 @@ export async function runAccess(input) {
                 else
                     log(grantorLine);
                 const nowMs = (deps.now ?? Date.now)();
+                const requester = await resolveRequester(deps.requester);
                 const recent = findRecentAccessRequest(deps.hqRoot, {
-                    requester: deps.requester.email,
+                    requester: requester.email,
                     prefix: resolvedKey,
                     company: slug,
                     grantor: resolved.email,
@@ -546,8 +643,8 @@ export async function runAccess(input) {
                         }
                     }
                     if (approved && outcome === "no-access") {
-                        const message = `${deps.requester.email} is asking for read access to ${resolvedKey} in ${slug}.`;
-                        const prompt = `hq files share ${resolvedKey} --with ${deps.requester.email} --permission read --company ${slug}`;
+                        const message = `${requester.email} is asking for read access to ${resolvedKey} in ${slug}.`;
+                        const prompt = `hq files share ${resolvedKey} --with ${requester.email} --permission read --company ${slug}`;
                         const sent = await deps.dm.send({
                             recipient: resolved.email,
                             message,
@@ -557,7 +654,7 @@ export async function runAccess(input) {
                         requestSentAt = sentAt;
                         try {
                             recordAccessRequest(deps.hqRoot, {
-                                requester: deps.requester.email,
+                                requester: requester.email,
                                 prefix: resolvedKey,
                                 company: slug,
                                 grantor: resolved.email,
@@ -591,31 +688,157 @@ export async function runAccess(input) {
         ...(alreadyAskedAt ? { alreadyAskedAt } : {}),
         ...(requestNote ? { requestNote } : {}),
     }, finishCtx);
+    return result;
+}
+export async function runAccess(input) {
+    const { deps } = input;
+    const log = deps.log ?? ((line) => console.log(line));
+    const slug = deps.companySlug;
+    const relative = normalizeTarget(input.target, slug);
+    // Vend, the bucket lookup, and the ACL record for the target as typed do not
+    // depend on each other; start them together.
+    const vendP = startEarly(vendForAccess(deps));
+    const entityP = startEarly(deps.vaultClient.entity.findInMyNamespace("company", slug));
+    // acl/resolve answers a granted permission in a fraction of the time
+    // acl/tree takes. The tree is only needed when resolve has no permission
+    // (deny or no record), so without resolve it starts early as before, and
+    // with resolve it is fetched on demand.
+    // A failed resolve call falls back to the tree rather than failing the check.
+    const resolvedP = deps.resolveAcl
+        ? deps.resolveAcl([relative]).catch(() => new Map())
+        : null;
+    const trees = new Map();
+    const treeFor = (key) => {
+        let p = trees.get(key);
+        if (!p) {
+            p = deps.fetchAclTree(key);
+            trees.set(key, p);
+        }
+        return p;
+    };
+    if (!resolvedP)
+        startEarly(treeFor(relative));
+    const vend = await vendP;
+    const entity = await entityP;
+    const ctx = {
+        vend,
+        bucket: bucketFor(entity, slug),
+        s3: deps.companyClient({ companyUid: deps.companyUid }),
+        aclFor: async (key) => {
+            if (resolvedP && key === relative) {
+                const permission = (await resolvedP).get(key);
+                if (permission)
+                    return { kind: "resolved", permission };
+            }
+            return { kind: "tree", tree: await treeFor(key) };
+        },
+        allowPick: true,
+    };
+    const located = await locateTarget(input.target, deps, ctx);
+    const result = await completeTarget(input, deps, located);
     emit(input, result, log);
     return result;
 }
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next;
+            next += 1;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return out;
+}
+/**
+ * Several targets in one company: one vend, one bucket lookup, and one
+ * acl/resolve call for all of them, then bounded-concurrency existence
+ * checks. Requests (DM rung) run one at a time in input order so prompts and
+ * grantor lines never interleave. Several fuzzy hits are reported as
+ * ambiguous; the interactive picker is single-path only.
+ */
+export async function runAccessBatch(input) {
+    const { deps } = input;
+    const log = deps.log ?? ((line) => console.log(line));
+    const slug = deps.companySlug;
+    const relatives = input.targets.map((t) => normalizeTarget(t, slug));
+    const unique = [...new Set(relatives)];
+    const vendP = startEarly(vendForAccess(deps));
+    const entityP = startEarly(deps.vaultClient.entity.findInMyNamespace("company", slug));
+    const resolvedP = startEarly(deps.resolveAcl
+        ? deps.resolveAcl(unique).catch(() => new Map())
+        : Promise.resolve(new Map()));
+    const vend = await vendP;
+    const entity = await entityP;
+    const permissions = await resolvedP;
+    const trees = new Map();
+    const treeFor = (key) => {
+        let p = trees.get(key);
+        if (!p) {
+            p = deps.fetchAclTree(key);
+            trees.set(key, p);
+        }
+        return p;
+    };
+    const ctx = {
+        vend,
+        bucket: bucketFor(entity, slug),
+        s3: deps.companyClient({ companyUid: deps.companyUid }),
+        aclFor: async (key) => {
+            const permission = permissions.get(key);
+            // A null permission can mean an explicit deny or no ACL record at all;
+            // only the tree tells those apart, so it decides as it does for a
+            // single path.
+            if (permission)
+                return { kind: "resolved", permission };
+            return { kind: "tree", tree: await treeFor(key) };
+        },
+        allowPick: false,
+    };
+    const located = await mapLimit(input.targets, input.concurrency ?? 4, (target) => locateTarget(target, deps, ctx));
+    const results = [];
+    for (let i = 0; i < input.targets.length; i += 1) {
+        const target = input.targets[i];
+        if (!input.json)
+            log(`==> ${target} <==`);
+        const result = await completeTarget(input, deps, located[i]);
+        if (!input.json)
+            log(formatAccessOutcome(result));
+        results.push({ target, result });
+    }
+    if (input.json) {
+        log(JSON.stringify(results.map(({ target, result }) => ({ target, ...jsonPayload(result) })), null, 2));
+    }
+    const exitCode = results.reduce((max, { result }) => (result.exitCode > max ? result.exitCode : max), 0);
+    return { results, exitCode };
+}
+function jsonPayload(result) {
+    const payload = {
+        outcome: result.outcome,
+        path: result.path,
+        company: result.company,
+        ...(result.exists !== undefined ? { exists: result.exists } : {}),
+        steps: result.steps,
+    };
+    if (result.grantor)
+        payload.grantor = result.grantor;
+    if (result.candidates)
+        payload.candidates = result.candidates;
+    if (result.fixed)
+        payload.fixed = result.fixed;
+    if (result.localPath)
+        payload.localPath = result.localPath;
+    if (result.requestSentAt)
+        payload.requestSentAt = result.requestSentAt;
+    if (result.alreadyAskedAt)
+        payload.alreadyAskedAt = result.alreadyAskedAt;
+    return payload;
+}
 function emit(input, result, log) {
     if (input.json) {
-        const payload = {
-            outcome: result.outcome,
-            path: result.path,
-            company: result.company,
-            ...(result.exists !== undefined ? { exists: result.exists } : {}),
-            steps: result.steps,
-        };
-        if (result.grantor)
-            payload.grantor = result.grantor;
-        if (result.candidates)
-            payload.candidates = result.candidates;
-        if (result.fixed)
-            payload.fixed = result.fixed;
-        if (result.localPath)
-            payload.localPath = result.localPath;
-        if (result.requestSentAt)
-            payload.requestSentAt = result.requestSentAt;
-        if (result.alreadyAskedAt)
-            payload.alreadyAskedAt = result.alreadyAskedAt;
-        log(JSON.stringify(payload, null, 2));
+        log(JSON.stringify(jsonPayload(result), null, 2));
     }
     else {
         log(formatAccessOutcome(result));
@@ -674,11 +897,12 @@ function treeFromBody(body) {
 }
 export function registerAccessCommand(program) {
     program
-        .command("access <path-or-query>")
-        .description("Tell whether a vault file exists and whether you can read it. Never a bare not-found. Exit codes: 0 local/not-synced, 2 never-existed, 3 no-access, 4 ambiguous.")
+        .command("access [vault-path...]")
+        .description("Tell whether a vault file exists and whether you can read it. Never a bare not-found. Takes one or more paths or queries. Exit codes: 0 local/not-synced, 2 never-existed, 3 no-access, 4 ambiguous.")
         .option("--company <slug>", "Company slug")
         .option("--as <person>", "Check a person's access (email, prs_, or agt_ uid; self or owner/admin)")
-        .option("--json", "Print a single JSON object")
+        .option("--json", "Print a single JSON object (an array for several paths)")
+        .option("--stdin", "Read more paths from stdin, one per line")
         .option("--no-fix", "Diagnose only: do not fetch, pin, or repair sync")
         .option("--yes", "Answer the one send-confirmation yes (hosts must pass this explicitly)")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
@@ -688,17 +912,34 @@ Exit codes:
   2  never-existed (the path was never created)
   3  no-access (the file exists but you cannot read it)
   4  ambiguous (several keys matched; pick one)
+
+With several paths, each gets its own result block and the exit code is the
+highest one across the paths.
 `)
-        .action(async (target, opts) => {
+        .action(async (paths, opts) => {
         try {
+            const targets = [...paths];
+            if (opts.stdin)
+                targets.push(...parseTargetLines(await readStdin()));
+            if (targets.length === 0) {
+                throw new Error("Pass at least one path, or --stdin with one path per line.");
+            }
             if (opts.as) {
-                const result = await runAccessForPerson(target, opts.as, opts);
+                if (targets.length !== 1) {
+                    throw new Error("--as checks one path at a time.");
+                }
+                const result = await runAccessForPerson(targets[0], opts.as, opts);
                 console.log(opts.json ? JSON.stringify(result) : formatAccessForPerson(result));
                 process.exitCode = result.exitCode;
                 return;
             }
-            const result = await runAccessForPath(target, opts);
-            process.exitCode = result.exitCode;
+            if (targets.length === 1 && !opts.stdin) {
+                const result = await runAccessForPath(targets[0], opts);
+                process.exitCode = result.exitCode;
+                return;
+            }
+            const batch = await runAccessForPaths(targets, opts);
+            process.exitCode = batch.exitCode;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -707,6 +948,20 @@ Exit codes:
         }
     });
 }
+/** One target per non-blank line; surrounding whitespace is ignored. */
+export function parseTargetLines(text) {
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
 /**
  * Resolve the company `hq access` runs against: explicit `company` (the
  * ladder forwards the slug stamped on a 403), else the slug anchored in the
@@ -798,15 +1053,14 @@ export async function runAccessForPerson(rawPath, personUid, opts) {
 export function formatAccessForPerson(result) {
     return `${result.personUid} has ${result.permission ?? "no access"} access to ${result.path}.`;
 }
-export async function runAccessForPath(path, opts) {
-    const target = path;
-    const hqRoot = opts?.hqRoot ?? DEFAULT_HQ_ROOT;
-    const slug = resolveAccessCompany(target, opts);
-    if (!slug) {
-        throw new Error("Pass --company <slug>, an anchored companies/<slug>/... path, or set activeCompany in .hq/config.json.");
-    }
+/** Live deps for one company: vault session, ACL routes, lazy caller lookup. */
+async function buildLiveAccessDeps(slug, hqRoot) {
     const { token, client } = await resolveBrowseSession();
     const companyUid = await getCompanyUid(token, slug);
+    const aclError = async (res, route) => {
+        const body = (await res.json().catch(() => ({})));
+        return new Error(body.message ?? body.error ?? `${route} failed (${res.status})`);
+    };
     const fetchAclTree = async (prefix) => {
         const res = await vaultApiFetch({
             token,
@@ -815,41 +1069,67 @@ export async function runAccessForPath(path, opts) {
         });
         if (res.status === 404)
             return null;
-        if (!res.ok) {
-            const body = (await res.json().catch(() => ({})));
-            throw new Error(body.message ?? body.error ?? `acl/tree failed (${res.status})`);
-        }
+        if (!res.ok)
+            throw await aclError(res, "acl/tree");
         const tree = (await res.json());
         return treeFromBody(tree);
     };
-    const listMembers = async () => {
-        const rows = await listActiveMembers(token, companyUid);
-        return rows
+    const resolveAcl = async (targets) => {
+        const res = await vaultApiFetch({
+            token,
+            path: `/files/${encodeURIComponent(companyUid)}/acl/resolve`,
+            method: "POST",
+            body: { targets },
+        });
+        if (!res.ok)
+            throw await aclError(res, "acl/resolve");
+        const data = (await res.json());
+        const out = new Map();
+        for (const row of data.results ?? []) {
+            if (typeof row.target !== "string")
+                continue;
+            out.set(row.target, typeof row.permission === "string" ? row.permission : null);
+        }
+        return out;
+    };
+    // Members and the caller are needed only to send an access request, so
+    // they load on first use and at most once.
+    let membersP;
+    const listMembers = () => {
+        membersP ??= listActiveMembers(token, companyUid).then((rows) => rows
             .filter((m) => ["owner", "admin", "member", "guest"].includes(m.role))
             .map((m) => ({
             personUid: m.personUid,
             personEmail: m.personEmail ?? "",
             personName: m.personName,
             role: m.role,
-        }));
+        })));
+        return membersP;
+    };
+    let requesterP;
+    const requester = () => {
+        requesterP ??= (async () => {
+            const members = await listMembers();
+            const caller = await resolveCallerUid(token);
+            const me = members.find((m) => m.personUid === caller.uid);
+            // An agent has no mailbox and no person entity. `hq files share --with`
+            // accepts its agt_* uid, so the access request names the agent by uid.
+            let requesterEmail = caller.kind === "agent" ? caller.uid : me?.personEmail;
+            const requesterName = me?.personName;
+            if (!requesterEmail) {
+                const claims = peekIdToken(token);
+                const emailClaim = claims.email;
+                if (typeof emailClaim === "string" && emailClaim.length > 0) {
+                    requesterEmail = emailClaim;
+                }
+            }
+            if (!requesterEmail) {
+                throw new Error("Could not resolve your email; pass --company and ensure you are an active member");
+            }
+            return { email: requesterEmail, name: requesterName };
+        })();
+        return requesterP;
     };
-    const members = await listMembers();
-    const caller = await resolveCallerUid(token);
-    const me = members.find((m) => m.personUid === caller.uid);
-    // An agent has no mailbox and no person entity. `hq files share --with`
-    // accepts its agt_* uid, so the access request names the agent by uid.
-    let requesterEmail = caller.kind === "agent" ? caller.uid : me?.personEmail;
-    const requesterName = me?.personName;
-    if (!requesterEmail) {
-        const claims = peekIdToken(token);
-        const emailClaim = claims.email;
-        if (typeof emailClaim === "string" && emailClaim.length > 0) {
-            requesterEmail = emailClaim;
-        }
-    }
-    if (!requesterEmail) {
-        throw new Error("Could not resolve your email; pass --company and ensure you are an active member");
-    }
     const dm = {
         async send(msg) {
             const body = buildDmBody({
@@ -889,65 +1169,99 @@ export async function runAccessForPath(path, opts) {
             return t === "y" || t === "yes";
         }
         : undefined;
-    const result = await runAccess({
-        target,
-        fix: opts?.fix !== false,
-        json: Boolean(opts?.json),
-        yes: Boolean(opts?.yes),
-        deps: {
+    return {
+        hqRoot,
+        companySlug: slug,
+        companyUid,
+        vaultClient: client,
+        companyClient: makeCompanyPresignFactory(token, slug),
+        region: "us-east-1",
+        fetchAclTree,
+        listMembers,
+        requester,
+        resolveAcl,
+        dm,
+        confirm,
+        now: Date.now,
+        get: (anchoredPath) => runGet({
+            path: anchoredPath,
             hqRoot,
             companySlug: slug,
-            companyUid,
             vaultClient: client,
             companyClient: makeCompanyPresignFactory(token, slug),
             region: "us-east-1",
-            fetchAclTree,
-            listMembers,
-            requester: { email: requesterEmail, name: requesterName },
-            dm,
-            confirm,
-            now: Date.now,
-            pick: promptPick,
-            get: (anchoredPath) => runGet({
-                path: anchoredPath,
+        }),
+        syncStatus: async () => {
+            const journals = listJournals();
+            if (journals.length === 0)
+                return "no sync journal yet";
+            let files = 0;
+            for (const j of journals) {
+                const entries = Object.entries(j.journal.files ?? {});
+                files += entries.filter(([, e]) => !e.removedAt).length;
+            }
+            return `${journals.length} journals, ${files} files tracked`;
+        },
+        syncDoctor: async (apply) => {
+            const doctorResult = await syncDoctor({
+                entity: "local",
+                vaultConfig: {},
                 hqRoot,
-                companySlug: slug,
-                vaultClient: client,
-                companyClient: makeCompanyPresignFactory(token, slug),
-                region: "us-east-1",
-            }),
-            syncStatus: async () => {
-                const journals = listJournals();
-                if (journals.length === 0)
-                    return "no sync journal yet";
-                let files = 0;
-                for (const j of journals) {
-                    const entries = Object.entries(j.journal.files ?? {});
-                    files += entries.filter(([, e]) => !e.removedAt).length;
-                }
-                return `${journals.length} journals, ${files} files tracked`;
-            },
-            syncDoctor: async (apply) => {
-                const doctorResult = await syncDoctor({
-                    entity: "local",
-                    vaultConfig: {},
-                    hqRoot,
-                    yes: apply,
-                    reconcileConflicts: true,
-                });
-                const twins = doctorResult.conflictTwins?.plan?.length ?? 0;
-                const bulkRefused = Boolean(doctorResult.plan?.bulkRefused);
-                return {
-                    twins,
-                    summary: `${twins} conflict twins`,
-                    bulkRefused,
-                    breakerMessage: bulkRefused
-                        ? "bulk-asymmetry circuit-breaker tripped — refusing the delete leg"
-                        : undefined,
-                };
-            },
+                yes: apply,
+                reconcileConflicts: true,
+            });
+            const twins = doctorResult.conflictTwins?.plan?.length ?? 0;
+            const bulkRefused = Boolean(doctorResult.plan?.bulkRefused);
+            return {
+                twins,
+                summary: `${twins} conflict twins`,
+                bulkRefused,
+                breakerMessage: bulkRefused
+                    ? "bulk-asymmetry circuit-breaker tripped — refusing the delete leg"
+                    : undefined,
+            };
         },
+    };
+}
+/**
+ * Company for a set of targets. Every target must resolve to the same company:
+ * one vend and one ACL call cover the whole batch.
+ */
+function resolveBatchCompany(targets, opts) {
+    const slugs = new Set(targets.map((t) => resolveAccessCompany(t, opts)));
+    if (slugs.has(undefined)) {
+        throw new Error("Pass --company <slug>, an anchored companies/<slug>/... path, or set activeCompany in .hq/config.json.");
+    }
+    if (slugs.size > 1) {
+        throw new Error(`Paths span several companies (${[...slugs].join(", ")}); run hq access once per company or pass --company <slug>.`);
+    }
+    return [...slugs][0];
+}
+export async function runAccessForPath(path, opts) {
+    const hqRoot = opts?.hqRoot ?? DEFAULT_HQ_ROOT;
+    const slug = resolveAccessCompany(path, opts);
+    if (!slug) {
+        throw new Error("Pass --company <slug>, an anchored companies/<slug>/... path, or set activeCompany in .hq/config.json.");
+    }
+    const deps = await buildLiveAccessDeps(slug, hqRoot);
+    return runAccess({
+        target: path,
+        fix: opts?.fix !== false,
+        json: Boolean(opts?.json),
+        yes: Boolean(opts?.yes),
+        deps: { ...deps, pick: promptPick },
+    });
+}
+export async function runAccessForPaths(paths, opts) {
+    const hqRoot = opts?.hqRoot ?? DEFAULT_HQ_ROOT;
+    const slug = resolveBatchCompany(paths, opts);
+    const deps = await buildLiveAccessDeps(slug, hqRoot);
+    return runAccessBatch({
+        targets: paths,
+        fix: opts?.fix !== false,
+        json: Boolean(opts?.json),
+        yes: Boolean(opts?.yes),
+        deps,
     });
-    return result;
 }
 //# sourceMappingURL=access.js.map