@indigoai-us/hq-cli 5.144.0 → 5.146.0

package/dist/commands/files.js

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

package/dist/commands/mesh.js

@@ -12,7 +12,7 @@ import chalk from "chalk";
 import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
-import { ensureProjectBoard } from "../lib/mesh/project-board.js";
+import { closeSupersededProjectThread, ensureProjectBoard } from "../lib/mesh/project-board.js";
 import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, } from "../lib/work-context/config.js";
@@ -39,6 +39,9 @@ import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
 import { readSessionState, updateSessionState } from "../lib/work-context/state.js";
 import { findLocalPrd, listNeedsProjectSessions } from "../lib/work-context/bind-best.js";
+import { bindCallingSession, formatSessionBoundLine } from "../lib/work-context/bind-calling-session.js";
+import { rebindNeedsProjectOnPrompt } from "../lib/work-context/prompt-rebind.js";
+import { planPrdSync } from "../lib/work-context/prd-sync.js";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "../lib/work-context/contract.js";
 import { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "../lib/work-context/reconcile.js";
 import { resolveCompany } from "../lib/work-context/company.js";
@@ -388,6 +391,9 @@ async function runProjectSet(projectId, opts) {
             throw err;
         }
     }
+    if (!current && opts.create) {
+        noteCallingSessionBound(view.projectId, company);
+    }
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "project.set", principalUid, ...view }, null, 2));
         return;
@@ -488,6 +494,13 @@ async function runProjectEnsure(projectId, opts) {
             }
         }
         registration = await registerMeshProject(token, company.companyUid, projectId);
+        await closeSupersededProjectThread({
+            token,
+            companyUid: company.companyUid,
+            openedThreadId: genesis.threadId,
+            canonicalThreadId: registration.threadId,
+            created: genesis.created,
+        });
         if (!registration.threadId || !registration.channelId) {
             fail("Work mesh registration did not return a threadId and channelId.");
         }
@@ -519,12 +532,91 @@ async function runProjectEnsure(projectId, opts) {
         version: verified.version,
         stories: verified.stories,
     };
+    noteCallingSessionBound(payload.projectId, company);
     if (opts.json) {
         console.log(JSON.stringify(payload));
         return;
     }
     console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
 }
+async function runPrdSync(opts) {
+    const sessionId = opts.session.trim();
+    const file = opts.file.trim();
+    if (!sessionId || !file)
+        fail("Usage: hq mesh context prd-sync --session <sid> --file <prd.json>");
+    const root = workContextHomeRoot();
+    const plan = planPrdSync({ sessionId, file, root });
+    if (!plan.changed) {
+        const payload = { ok: true, action: "context.prd-sync", changed: 0, ...(plan.skip ? { skip: plan.skip } : {}) };
+        if (opts.json)
+            console.log(JSON.stringify(payload));
+        else
+            console.log(plan.skip ? `Work mesh: prd-sync skipped (${plan.skip})` : "Work mesh: prd-sync unchanged");
+        return;
+    }
+    let token;
+    try {
+        token = await requireToken();
+    }
+    catch {
+        token = null;
+    }
+    if (!token) {
+        console.error("work-mesh: prd-sync has changes but no token; snapshot not advanced");
+        return;
+    }
+    const events = plan.events.map((event, index) => buildMeshEmitEvent({
+        eventId: generateUlid(Date.now() + index),
+        kind: "task_status",
+        sessionId,
+        harness: "hq-sessions",
+        adapterVersion: "1.0.0",
+        at: new Date().toISOString(),
+        seq: plan.seqStart + index + 1,
+        source: "hooks",
+        taskId: event.taskId,
+        status: event.status,
+        summary: event.status === "done" ? `${event.taskId} passes` : `${event.taskId} in progress`,
+    }));
+    const poster = createEmitPoster({ token, baseUrl: resolveVaultApiBase(process.env) });
+    await emitEvents({
+        workMeshRoot: workMeshHomeRoot(),
+        poster,
+        newEvents: events,
+    });
+    plan.commit();
+    if (plan.taskId) {
+        updateSessionState(sessionId, root, (current) => {
+            if (!current)
+                return null;
+            return {
+                ...current,
+                taskId: plan.taskId,
+                contextStatus: current.projectId ? "bound" : current.contextStatus,
+                updatedAt: new Date().toISOString(),
+            };
+        });
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "context.prd-sync", changed: plan.events.length, taskId: plan.taskId }));
+        return;
+    }
+    console.log(`Work mesh: prd-sync emitted ${plan.events.length} task_status`);
+}
+function noteCallingSessionBound(projectId, company) {
+    try {
+        const bound = bindCallingSession({
+            root: workContextHomeRoot(),
+            projectId,
+            company,
+        });
+        if (bound.bound)
+            console.error(formatSessionBoundLine(bound.sessionId, bound.projectId));
+    }
+    catch {
+        /* session bind is local and must not fail project ensure */
+    }
+}
 async function runDoctor(opts) {
     if (opts.apply) {
         fail("`hq mesh doctor --apply` (paced Board PUTs from local prd.json) is not in the CLI yet.\n" +
@@ -1327,6 +1419,21 @@ async function runSessionEnqueue(cliKind, opts) {
     const sessionId = resolveEnqueueSessionId(opts.sessionId, process.env);
     if (!sessionId)
         fail("sessionId required (--session-id or HQ_SESSION_ID)");
+    if (kind === "turn_start") {
+        try {
+            rebindNeedsProjectOnPrompt({
+                sessionId,
+                root: workContextHomeRoot(),
+                hqRoot: opts.hqRoot?.trim() || process.env.HQ_ROOT,
+                cwd: opts.cwd,
+                companySlug: opts.companySlug,
+                env: process.env,
+            });
+        }
+        catch {
+            /* prompt rebind is fail-soft */
+        }
+    }
     const evidence = buildEmitEvidence({
         sessionId: sessionId,
         hqRoot: opts.hqRoot,
@@ -1674,6 +1781,13 @@ export function registerMeshCommand(program) {
         .option("--company <slug|uid>", "Company override when creating a Board")
         .option("--json", "Print machine-readable JSON")
         .action((target, slug, opts) => wrap(() => runBindProject(target, { ...opts, slug }))());
+    context
+        .command("prd-sync")
+        .description("Emit task_status for PRD story passes/status changes on a bound session")
+        .requiredOption("--session <sid>", "Canonical session id")
+        .requiredOption("--file <path>", "prd.json written by the bound session")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runPrdSync(opts))());
     context
         .command("organize")
         .description("List or submit one-time project/task decisions (US-007B / US-005B)")

package/dist/commands/report.d.ts

@@ -1,6 +1,19 @@
 import { Command } from "commander";
 import { buildReportTarball, deployOrgContext, type ChannelReport, type DeployAccessPolicy, type ReportDeployment, type ReportPatch } from "../lib/report-publish.js";
+type ChannelRow = {
+    channelId?: string;
+    scope?: string;
+    companyUid?: string | null;
+};
 type ReportPatchInput = ReportPatch | ((current: ChannelReport) => ReportPatch);
+/** Any company-owned channel (company or project scope) can carry reports; personal channels cannot. */
+export declare function isCompanyReportChannel(channel: ChannelRow): boolean;
+/**
+ * Records created before hq-pro stamped companyUid carry null. The channel the
+ * caller can see knows its company, and publish needs it to pick the deploy
+ * org, so fill it from there rather than failing every publish.
+ */
+export declare function withChannelCompany(report: ChannelReport, channels: ChannelRow[]): ChannelReport;
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
 export declare function resolveReport(token: string, reportId: string, requestedChannelId?: string): Promise<ChannelReport>;
 export declare function patchReport(token: string, report: ChannelReport, patch: ReportPatchInput): Promise<ChannelReport>;

package/dist/commands/report.js

@@ -87,22 +87,26 @@ function print(value, json) {
         console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
 async function listReportChannels(token) {
-    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+    // scope=all: the default list is personal channels only, which hid every
+    // project and company channel a report can live on.
+    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels?scope=all" });
     if (!channels.ok)
-        throw new ReportPublishError("Could not resolve the report channel.");
+        throw new ReportPublishError("Could not resolve the report channel.", "source-invalid");
     const listed = await channels.json();
     return Array.isArray(listed.channels) ? listed.channels : [];
 }
-function isCompanyReportChannel(channel) {
-    return channel.scope === "company"
-        || (typeof channel.scope !== "string" && Boolean(channel.companyUid));
+/** Any company-owned channel (company or project scope) can carry reports; personal channels cannot. */
+export function isCompanyReportChannel(channel) {
+    if (channel.scope === "personal")
+        return false;
+    return channel.scope === "company" || channel.scope === "project" || Boolean(channel.companyUid);
 }
 function requireCompanyReportChannel(channels, channelId) {
     const channel = channels.find((row) => row.channelId === channelId);
     if (!channel)
-        throw new ReportPublishError("Report channel was not found in your channels.");
+        throw new ReportPublishError("Report channel was not found in your channels.", "source-invalid");
     if (!isCompanyReportChannel(channel))
-        throw new ReportPublishError("Channel reports require a company channel.");
+        throw new ReportPublishError("Channel reports require a company channel.", "source-invalid");
 }
 async function readReportInChannel(token, channelId, reportId) {
     const res = await vaultApiFetch({ token, path: reportPath(channelId, reportId) });
@@ -113,6 +117,17 @@ async function readReportInChannel(token, channelId, reportId) {
         throw new ReportPublishError("Report response was incomplete.");
     return body.report;
 }
+/**
+ * Records created before hq-pro stamped companyUid carry null. The channel the
+ * caller can see knows its company, and publish needs it to pick the deploy
+ * org, so fill it from there rather than failing every publish.
+ */
+export function withChannelCompany(report, channels) {
+    if (report.companyUid)
+        return report;
+    const companyUid = channels.find((row) => row.channelId === report.channelId)?.companyUid;
+    return companyUid ? { ...report, companyUid } : report;
+}
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
 export async function resolveReport(token, reportId, requestedChannelId) {
     const explicit = requestedChannelId ?? process.env.HQ_REPORT_CHANNEL_ID;
@@ -121,18 +136,18 @@ export async function resolveReport(token, reportId, requestedChannelId) {
         requireCompanyReportChannel(channels, explicit);
         const res = await vaultApiFetch({ token, path: reportPath(explicit, reportId) });
         if (!res.ok)
-            throw new ReportPublishError("Report was not found in the supplied channel context.");
+            throw new ReportPublishError("Report was not found in the supplied channel context.", "source-invalid");
         const body = await res.json();
         if (!body.report)
             throw new ReportPublishError("Report response was incomplete.");
-        return body.report;
+        return withChannelCompany(body.report, channels);
     }
     const recordedChannel = locallyRecordedChannel(reportId);
     if (recordedChannel) {
         requireCompanyReportChannel(channels, recordedChannel);
         const recorded = await readReportInChannel(token, recordedChannel, reportId);
         if (recorded)
-            return recorded;
+            return withChannelCompany(recorded, channels);
     }
     // The report API is intentionally channel-scoped. Discover only among the
     // caller's existing channels, using list endpoints so missing reports never
@@ -153,13 +168,13 @@ export async function resolveReport(token, reportId, requestedChannelId) {
         const reports = Array.isArray(body.reports) ? body.reports : [];
         const match = reports.find((report) => report.reportId === reportId);
         if (match)
-            return match;
+            return withChannelCompany(match, channels);
     }
     throw new ReportPublishError(notFoundMessage(scannedChannels));
 }
 export async function patchReport(token, report, patch) {
     if (!report.companyUid)
-        throw new ReportPublishError("Channel reports require a company channel.");
+        throw new ReportPublishError("Channel reports require a company channel.", "source-invalid");
     const patchOnce = (current) => vaultApiFetch({
         token,
         path: reportPath(current.channelId, current.reportId),
@@ -275,7 +290,14 @@ export async function deployReportStatic(token, input) {
 }
 async function publishWithOrg(token, report, directory, draft) {
     const published = await publishReport(report, directory, draft, {
-        patch: (current, patch) => patchReport(token, current, patch),
+        // The server echoes the stored record, whose companyUid may still be null
+        // on reports created before hq-pro stamped it. Keep the company resolved
+        // from the channel so the access policy and deploy org stay correct.
+        patch: async (current, patch) => {
+            const next = await patchReport(token, current, patch);
+            const companyUid = next.companyUid ?? current.companyUid ?? report.companyUid;
+            return companyUid ? { ...next, companyUid } : next;
+        },
         deploy: async (input) => {
             const org = await orgFor(token, report);
             return deployReportStatic(token, { ...input, org });

package/dist/commands/sync-narrow.js

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

package/dist/commands/workers.js

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

package/dist/lib/mesh/live/daemon/credentials.d.ts

@@ -18,6 +18,12 @@ export declare const REFUSED_RETRY_ENV = "HQ_MESH_DAEMON_REFUSED_RETRY_MS";
 export declare const MAX_TIMER_DELAY_MS = 2147483647;
 /** Cap any single retry so a bogus Retry-After cannot park the daemon. */
 export declare const MAX_RETRY_DELAY_MS: number;
+/** Contract-3 vend accepts at most this many preferred company uids. */
+export declare const PREFERRED_COMPANY_LIMIT = 5;
+/** Session files older than this do not count as companies in use. */
+export declare const PREFERRED_SESSION_WINDOW_MS: number;
+/** Preferred-set changes re-vend at most this often. */
+export declare const PREFERRED_REVEND_MIN_MS = 60000;
 export type CredentialVendFailureKind = "refused" | "transient";
 /**
  * Typed vend failure. `refused` = server will not vend right now
@@ -51,6 +57,8 @@ export interface PresenceCompany {
 }
 export interface DroppedPresenceCompany {
     companyUid: string;
+    /** Short name for doctor text when the server sent one. */
+    label?: string;
     /** Server-supplied cause when available; otherwise a deliberately neutral label. */
     reason: string;
 }
@@ -98,6 +106,30 @@ export declare function normalizeContract3Bundle(raw: unknown): Contract3Bundle;
  * No identity file → return the bundle unchanged (person laptop).
  */
 export declare function scopeBundleToAgentIdentity(bundle: Contract3Bundle, env?: NodeJS.ProcessEnv): Contract3Bundle;
+/**
+ * Device default first, then distinct company uids from session files updated
+ * in the last 24 hours, newest first, max 5. Any read error returns undefined
+ * so the vend body omits the field.
+ */
+export declare function readPreferredCompanyUids(input: {
+    workContextRoot: string;
+    nowMs?: number;
+}): string[] | undefined;
+export declare function preferredCompanyKey(uids: readonly string[] | undefined): string;
+/** True when a new preferred set should force a vend, at most once per minute. */
+export declare function shouldRevendPreferredCompanies(input: {
+    previous: readonly string[] | undefined;
+    next: readonly string[] | undefined;
+    lastVendMs: number;
+    nowMs: number;
+    minIntervalMs?: number;
+}): boolean;
+export declare function contract3VendBody(preferredCompanyUids: readonly string[] | undefined): {
+    contractVersion: 3;
+    preferredCompanyUids?: string[];
+};
+/** Plain doctor line for one company the vend left out. */
+export declare function formatDroppedPresenceCompany(company: DroppedPresenceCompany): string;
 export type CredentialVendPostResult = {
     status: number;
     body: unknown;
@@ -110,6 +142,8 @@ export declare function createContract3Fetcher(opts: {
     post?: (path: string, body: unknown) => Promise<CredentialVendPostResult>;
     /** Process env for identity-file scoping (tests). */
     env?: NodeJS.ProcessEnv;
+    /** Companies to ask for. Undefined (read error) omits the field. */
+    readPreferredCompanyUids?: () => string[] | undefined;
 }): CredentialsFetcher;
 export interface CredentialRenewalErrorInfo {
     /** Absolute ISO timestamp when the renewal retry is scheduled to fire. */
@@ -130,8 +164,11 @@ export declare class CredentialRenewalManager {
     private readonly random;
     private handle;
     private stopped;
+    private inflight;
     constructor(fetchCredentials: CredentialsFetcher, onRenewed: (bundle: Contract3Bundle) => void, onError?: (err: unknown, info?: CredentialRenewalErrorInfo) => void, timers?: TimerHost, retryDelayMs?: number, refusedRetryMs?: number, random?: () => number);
     schedule(bundle: Contract3Bundle): void;
+    /** Vend now (preferred companies changed). No-op while a vend is in flight. */
+    renewNow(): void;
     private renew;
     stop(): void;
     private clear;