@indigoai-us/hq-cli 5.145.0 → 5.146.0

package/CHANGELOG.md

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

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

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

package/dist/command-catalog.generated.js

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

package/dist/commands/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

@@ -8,6 +8,12 @@ type ChannelRow = {
 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

@@ -117,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;
@@ -129,14 +140,14 @@ export async function resolveReport(token, reportId, requestedChannelId) {
         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
@@ -157,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),
@@ -279,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/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;

package/dist/lib/mesh/live/daemon/credentials.js

@@ -2,9 +2,13 @@
  * Contract-3 realtime credential vend + 80%-of-lifetime renewal.
  * Never logs or persists credential material.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { DEFAULT_VAULT_API_URL } from "../../../../utils/cognito-session.js";
 import { vaultApiFetch } from "../../../../utils/vault-api.js";
 import { readAgentIdentityCompanyUid } from "../../../work-context/company.js";
+import { readDeviceConfig } from "../../../work-context/config.js";
+import { workContextSessionsDir } from "../../../work-context/paths.js";
 export const REALTIME_CREDENTIALS_PATH = "/v1/realtime/credentials";
 export const MQTT_KEEPALIVE_SECONDS = 15;
 /** Renew at 80% of credential lifetime. */
@@ -20,6 +24,12 @@ export const REFUSED_RETRY_ENV = "HQ_MESH_DAEMON_REFUSED_RETRY_MS";
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Cap any single retry so a bogus Retry-After cannot park the daemon. */
 export const MAX_RETRY_DELAY_MS = 24 * 60 * 60 * 1000;
+/** Contract-3 vend accepts at most this many preferred company uids. */
+export const PREFERRED_COMPANY_LIMIT = 5;
+/** Session files older than this do not count as companies in use. */
+export const PREFERRED_SESSION_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Preferred-set changes re-vend at most this often. */
+export const PREFERRED_REVEND_MIN_MS = 60_000;
 /**
  * Typed vend failure. `refused` = server will not vend right now
  * (FEATURE_DISABLED / REALTIME_CONTRACT_UNSUPPORTED / 403); daemon should
@@ -241,8 +251,14 @@ export function normalizeContract3Bundle(raw) {
         const companyUid = typeof row.companyUid === "string" ? row.companyUid.trim() : "";
         if (!companyUid)
             continue;
+        const slug = typeof row.companySlug === "string"
+            ? row.companySlug.trim()
+            : typeof row.slug === "string"
+                ? row.slug.trim()
+                : "";
         droppedCompanies.push({
             companyUid,
+            ...(slug ? { label: slug } : {}),
             reason: typeof row.reason === "string" && row.reason.trim()
                 ? row.reason.trim()
                 : "not included",
@@ -282,6 +298,101 @@ export function scopeBundleToAgentIdentity(bundle, env = process.env) {
     }
     return { ...bundle, companies: matched };
 }
+function pushDistinct(out, seen, uid) {
+    const trimmed = uid?.trim();
+    if (!trimmed || seen.has(trimmed) || out.length >= PREFERRED_COMPANY_LIMIT)
+        return;
+    seen.add(trimmed);
+    out.push(trimmed);
+}
+/**
+ * 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 function readPreferredCompanyUids(input) {
+    try {
+        const nowMs = input.nowMs ?? Date.now();
+        const config = readDeviceConfig({ root: input.workContextRoot });
+        const out = [];
+        const seen = new Set();
+        if (config.defaultCompany?.enabled && config.defaultCompany.uid) {
+            pushDistinct(out, seen, config.defaultCompany.uid);
+        }
+        const dir = workContextSessionsDir(input.workContextRoot);
+        let names = [];
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+        }
+        const recent = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const full = path.join(dir, name);
+            const stat = fs.statSync(full);
+            if (!stat.isFile())
+                continue;
+            const raw = JSON.parse(fs.readFileSync(full, "utf8"));
+            const parsedAt = typeof raw.updatedAt === "string" ? Date.parse(raw.updatedAt) : Number.NaN;
+            const at = Number.isFinite(parsedAt) ? parsedAt : stat.mtimeMs;
+            if (!Number.isFinite(at) || nowMs - at > PREFERRED_SESSION_WINDOW_MS)
+                continue;
+            if (nowMs < at)
+                continue;
+            if (typeof raw.companyUid !== "string")
+                continue;
+            recent.push({ uid: raw.companyUid, at });
+        }
+        recent.sort((a, b) => b.at - a.at || a.uid.localeCompare(b.uid));
+        for (const row of recent)
+            pushDistinct(out, seen, row.uid);
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function preferredCompanyKey(uids) {
+    return (uids ?? []).join("\n");
+}
+/** True when a new preferred set should force a vend, at most once per minute. */
+export function shouldRevendPreferredCompanies(input) {
+    if (!input.next)
+        return false;
+    if (preferredCompanyKey(input.previous) === preferredCompanyKey(input.next)) {
+        return false;
+    }
+    const min = input.minIntervalMs ?? PREFERRED_REVEND_MIN_MS;
+    return input.nowMs - input.lastVendMs >= min;
+}
+export function contract3VendBody(preferredCompanyUids) {
+    const body = {
+        contractVersion: 3,
+    };
+    if (preferredCompanyUids && preferredCompanyUids.length > 0) {
+        body.preferredCompanyUids = preferredCompanyUids.slice(0, PREFERRED_COMPANY_LIMIT);
+    }
+    return body;
+}
+/** Plain doctor line for one company the vend left out. */
+export function formatDroppedPresenceCompany(company) {
+    const name = company.label?.trim() || company.companyUid;
+    if (company.reason === "gate_disabled") {
+        return `${name}: not included (presence is turned off for this company)`;
+    }
+    if (company.reason === "policy_budget") {
+        return `${name}: not included (too many companies for one credential)`;
+    }
+    if (!company.reason || company.reason === "unknown" || company.reason === "not included") {
+        return `${name}: not included`;
+    }
+    return `${name}: not included (${company.reason})`;
+}
 function headerGet(headers, name) {
     if (!headers)
         return null;
@@ -294,11 +405,19 @@ function headerGet(headers, name) {
 }
 export function createContract3Fetcher(opts) {
     return async () => {
+        let preferred;
+        if (opts.readPreferredCompanyUids) {
+            try {
+                preferred = opts.readPreferredCompanyUids();
+            }
+            catch {
+                preferred = undefined;
+            }
+        }
+        const body = contract3VendBody(preferred);
         let bundle;
         if (opts.post) {
-            const res = await opts.post(REALTIME_CREDENTIALS_PATH, {
-                contractVersion: 3,
-            });
+            const res = await opts.post(REALTIME_CREDENTIALS_PATH, body);
             if (res.status < 200 || res.status >= 300) {
                 throw classifyCredentialVendFailure(res.status, res.body, headerGet(res.headers, "Retry-After"));
             }
@@ -309,23 +428,23 @@ export function createContract3Fetcher(opts) {
                 token: opts.token,
                 path: REALTIME_CREDENTIALS_PATH,
                 method: "POST",
-                body: { contractVersion: 3 },
+                body,
                 baseUrl: opts.baseUrl ?? DEFAULT_VAULT_API_URL,
             });
             const text = await res.text();
-            let body = {};
+            let parsed = {};
             if (text) {
                 try {
-                    body = JSON.parse(text);
+                    parsed = JSON.parse(text);
                 }
                 catch {
-                    body = { raw: text.slice(0, 200) };
+                    parsed = { raw: text.slice(0, 200) };
                 }
             }
             if (!res.ok) {
-                throw classifyCredentialVendFailure(res.status, body, res.headers.get("Retry-After"));
+                throw classifyCredentialVendFailure(res.status, parsed, res.headers.get("Retry-After"));
             }
-            bundle = normalizeContract3Bundle(body);
+            bundle = normalizeContract3Bundle(parsed);
         }
         return scopeBundleToAgentIdentity(bundle, opts.env ?? process.env);
     };
@@ -344,6 +463,7 @@ export class CredentialRenewalManager {
     random;
     handle = null;
     stopped = false;
+    inflight = false;
     constructor(fetchCredentials, onRenewed, onError = () => { }, timers = realTimerHost, retryDelayMs = 30_000, refusedRetryMs = DEFAULT_REFUSED_RETRY_MS, random = Math.random) {
         this.fetchCredentials = fetchCredentials;
         this.onRenewed = onRenewed;
@@ -360,9 +480,17 @@ export class CredentialRenewalManager {
         const delay = renewalDelayMs(this.timers.now(), bundle.expiresAt);
         this.handle = scheduleBoundedTimeout(this.timers, () => void this.renew(), delay);
     }
+    /** Vend now (preferred companies changed). No-op while a vend is in flight. */
+    renewNow() {
+        if (this.stopped || this.inflight)
+            return;
+        this.clear();
+        void this.renew();
+    }
     async renew() {
-        if (this.stopped)
+        if (this.stopped || this.inflight)
             return;
+        this.inflight = true;
         try {
             const bundle = await this.fetchCredentials();
             if (this.stopped)
@@ -389,6 +517,9 @@ export class CredentialRenewalManager {
                 return;
             this.handle = scheduleBoundedTimeout(this.timers, () => void this.renew(), delay);
         }
+        finally {
+            this.inflight = false;
+        }
     }
     stop() {
         this.stopped = true;

package/dist/lib/mesh/live/daemon/doctor.js

@@ -9,6 +9,7 @@ import { describeCognitoTokenSource, formatCognitoSubject, loadMachineCachedToke
 import { listOutboxOperations, outboxStats, } from "../../../work-context/outbox.js";
 import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
+import { formatDroppedPresenceCompany } from "./credentials.js";
 import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
 import { daemonDir, daemonPidPath } from "./paths.js";
@@ -239,9 +240,9 @@ export function formatDaemonDoctor(report) {
     if (report.presenceDroppedCompanies.length > 0) {
         lines.push(`presence not published for ${report.presenceDroppedCompanies.length} companies: ` +
             report.presenceDroppedCompanies
-                .map((company) => `${company.companyUid} (${company.reason})`)
-                .join(", ") +
-            `; presence credential holds ${report.companiesOnline.length} companies; these were not included`);
+                .map((company) => formatDroppedPresenceCompany(company))
+                .join("; ") +
+            `; presence credential holds ${report.companiesOnline.length} companies`);
     }
     if (report.unhealthy) {
         lines.push(`health: UNHEALTHY`);