@indigoai-us/hq-cli 5.290.0 → 5.292.0

package/dist/commands/mesh.js

@@ -11,7 +11,7 @@ import { readFileSync } from "node:fs";
 import { findHqRoot } from "../utils/manifest.js";
 import { CLI_VERSION } from "../cli-version.js";
 import chalk from "chalk";
-import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
+import { ensureCognitoToken, isExpiring, isMachineIdentity, loadCachedTokens, } 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 { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, } from "../lib/mesh/project-board.js";
@@ -26,7 +26,9 @@ import { CLI_KIND_TO_SCHEMA, resolveEnqueueSessionId, } from "../lib/mesh/live/i
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
 import { backfillHeldSessions } from "../lib/mesh/live/backfill-held.js";
 import { createSessionEventsPoster, resolveVaultApiBase, } from "../lib/mesh/live/session-events-client.js";
-const MEMBERSHIP_VALIDATION_TIMEOUT_MS = 5_000;
+const ONLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS = 5_000;
+// Leave 500 ms of headroom inside SessionStart's 2 s process-group limit.
+const OFFLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS = 1_500;
 import { buildEmitEvidence, machineEmitDisposition } from "../lib/mesh/live/emit-evidence.js";
 import { appendHeldLine } from "../lib/mesh/live/spool.js";
 import { createEmitPoster, buildMeshEmitEvent } from "../lib/mesh/live/emit-client.js";
@@ -860,29 +862,45 @@ async function runContextReconcile(opts) {
     let offline = Boolean(opts.offline);
     let token;
     try {
-        // Offline is outbox-only delivery. It still refreshes a device default's
-        // token-backed membership so a revoked default cannot be preflighted.
-        token = await requireToken();
-        const sessionToken = token;
-        validateMembership = async (candidate) => {
-            const membership = await new Promise((resolve, reject) => {
-                const timer = setTimeout(() => reject(new Error("membership validation timed out")), MEMBERSHIP_VALIDATION_TIMEOUT_MS);
-                void resolveActiveMembershipCompany(sessionToken, candidate).then((value) => {
-                    clearTimeout(timer);
-                    resolve(value);
-                }, (error) => {
-                    clearTimeout(timer);
-                    reject(error);
+        if (offline) {
+            if (isMachineIdentity()) {
+                token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            }
+            else {
+                const cached = loadCachedTokens();
+                if (cached && !isExpiring(cached, 120)) {
+                    token = cached.accessToken;
+                }
+            }
+        }
+        else {
+            token = await requireToken();
+        }
+        if (token) {
+            const sessionToken = token;
+            const membershipValidationTimeoutMs = offline
+                ? OFFLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS
+                : ONLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS;
+            validateMembership = async (candidate) => {
+                const membership = await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error("membership validation timed out")), membershipValidationTimeoutMs);
+                    void resolveActiveMembershipCompany(sessionToken, candidate).then((value) => {
+                        clearTimeout(timer);
+                        resolve(value);
+                    }, (error) => {
+                        clearTimeout(timer);
+                        reject(error);
+                    });
                 });
-            });
-            if (!membership || typeof membership.companyUid !== "string" || !membership.companyUid) {
-                return false;
+                if (!membership || typeof membership.companyUid !== "string" || !membership.companyUid) {
+                    return false;
+                }
+                return { uid: membership.companyUid };
+            };
+            if (!offline) {
+                deliver = createWorkSessionDeliverer({ token: sessionToken });
+                fetchCandidates = createCandidatesFetcher({ token: sessionToken });
             }
-            return { uid: membership.companyUid };
-        };
-        if (!offline) {
-            deliver = createWorkSessionDeliverer({ token: sessionToken });
-            fetchCandidates = createCandidatesFetcher({ token: sessionToken });
         }
     }
     catch {
@@ -900,7 +918,10 @@ async function runContextReconcile(opts) {
             log: (message) => console.error(chalk.dim(message)),
         });
         if (activation.status === "needs_choice") {
-            const interactive = !opts.machine && Boolean(process.stdin.isTTY && process.stdout.isTTY) && !isMachineIdentity();
+            const interactive = !offline &&
+                !opts.machine &&
+                Boolean(process.stdin.isTTY && process.stdout.isTTY) &&
+                !isMachineIdentity();
             if (interactive) {
                 const choices = activation.memberships
                     .map((membership, index) => `${index + 1}. ${membership.slug}`)
@@ -920,7 +941,7 @@ async function runContextReconcile(opts) {
                     rl.close();
                 }
             }
-            else if (!opts.machine) {
+            else if (!offline && !opts.machine) {
                 console.error(chalk.yellow("Multiple active memberships. Run `hq mesh context default set <slug>` to choose this device's default company."));
             }
         }

package/dist/commands/personal-targeted-push-flag.d.ts

@@ -0,0 +1,4 @@
+export declare const CLI_PERSONAL_TARGETED_PUSH_PATHS_FLAG = "cli.personal-targeted-push-paths";
+/** The established full-scope behavior remains in force until an explicit hq-flags enablement. */
+export declare function personalTargetedPushPathsEnabled(): boolean;
+//# sourceMappingURL=personal-targeted-push-flag.d.ts.map

package/dist/commands/personal-targeted-push-flag.js

@@ -0,0 +1,7 @@
+import { resolveProcessFlagGate } from "../lib/flag-registry.js";
+export const CLI_PERSONAL_TARGETED_PUSH_PATHS_FLAG = "cli.personal-targeted-push-paths";
+/** The established full-scope behavior remains in force until an explicit hq-flags enablement. */
+export function personalTargetedPushPathsEnabled() {
+    return resolveProcessFlagGate(CLI_PERSONAL_TARGETED_PUSH_PATHS_FLAG, { fallback: false }, () => false);
+}
+//# sourceMappingURL=personal-targeted-push-flag.js.map

package/dist/commands/personal-targeted-push-paths.d.ts

@@ -0,0 +1,3 @@
+/** Resolve explicit --personal paths against the same roots as a full personal push. */
+export declare function resolveExplicitPersonalPushPaths(hqRoot: string, requestedPaths: readonly string[], cwd?: string): string[];
+//# sourceMappingURL=personal-targeted-push-paths.d.ts.map

package/dist/commands/personal-targeted-push-paths.js

@@ -0,0 +1,67 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { computePersonalVaultPaths, matchPersonalVaultExclusion, } from "@indigoai-us/hq-cloud";
+function isWithin(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+function rejectPath(input, reason) {
+    throw new Error(`--personal cannot push path "${input}": ${reason}`);
+}
+/** Resolve explicit --personal paths against the same roots as a full personal push. */
+export function resolveExplicitPersonalPushPaths(hqRoot, requestedPaths, cwd = process.cwd()) {
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync.native(hqRoot);
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? String(error.code) : "unavailable";
+        throw new Error(`--personal cannot resolve HQ root "${hqRoot}" (${code})`);
+    }
+    const allowedRoots = computePersonalVaultPaths(realRoot)
+        .map((allowedPath) => {
+        try {
+            return fs.realpathSync.native(allowedPath);
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "unavailable";
+            throw new Error(`--personal personal-vault scope changed at "${allowedPath}" (${code})`);
+        }
+    })
+        .filter((allowedPath) => isWithin(realRoot, allowedPath));
+    const resolved = [];
+    for (const input of requestedPaths) {
+        const normalizedInput = path.resolve(cwd, input);
+        let realPath;
+        try {
+            realPath = fs.realpathSync.native(normalizedInput);
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "unavailable";
+            rejectPath(input, `path cannot be resolved (${code})`);
+        }
+        if (!isWithin(realRoot, realPath)) {
+            rejectPath(input, "resolved path escapes the HQ root");
+        }
+        let isDirectory;
+        try {
+            isDirectory = fs.statSync(realPath).isDirectory();
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "unavailable";
+            rejectPath(input, `path cannot be inspected (${code})`);
+        }
+        const relativePath = path.relative(realRoot, realPath).split(path.sep).join("/");
+        const exclusion = matchPersonalVaultExclusion(relativePath, isDirectory);
+        if (exclusion) {
+            rejectPath(input, `excluded by personal-vault rule ${exclusion.id}`);
+        }
+        if (!allowedRoots.some((allowedRoot) => isWithin(allowedRoot, realPath))) {
+            rejectPath(input, "resolved path is outside the personal-vault paths");
+        }
+        resolved.push(realPath);
+    }
+    return resolved;
+}
+//# sourceMappingURL=personal-targeted-push-paths.js.map

package/dist/commands/secrets.js

@@ -5,6 +5,7 @@ import { cognitoCachePrincipalUid, ensureCognitoToken } from "../utils/cognito-s
 import { isAuthError } from "../utils/auth-error.js";
 import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
+import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
@@ -988,6 +989,11 @@ export function registerSecretsCommand(program) {
             }
         }
         catch (err) {
+            // A plan-limit refusal goes to main.ts's shared renderer, which prints
+            // the reason, usage, fix options and upgrade link, offers the upgrade
+            // interactively, and exits non-zero.
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
@@ -1650,6 +1656,9 @@ export function registerSecretsCommand(program) {
             console.log(chalk.dim("  One-time use — link is invalidated after first submission."));
         }
         catch (err) {
+            // Same shared plan-limit renderer as `secrets set` (see main.ts).
+            if (isPlanGateError(err))
+                throw err;
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }

package/dist/commands/skill.d.ts

@@ -18,6 +18,7 @@ import { Command } from "commander";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
+import { type PlanLimitRefusalSummary } from "../lib/billing/plan-limit-refusals.js";
 export declare const SKILL_UID_PATTERN: RegExp;
 export declare const SKILL_SLUG_PATTERN: RegExp;
 interface SkillSyncInput {
@@ -30,6 +31,8 @@ interface SkillSyncResult {
     filesUploaded: number;
     filesSkipped: number;
     aborted: boolean;
+    /** Set when a plan limit refused the upload; absent or null otherwise. */
+    planLimit?: PlanLimitRefusalSummary | null;
 }
 export declare function parseSkillUid(markdown: string): string | undefined;
 export declare function readActiveCompanySlug(hqRoot: string): string | undefined;

package/dist/commands/skill.js

@@ -27,25 +27,47 @@ import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
 import { AuthError } from "../utils/auth-error.js";
 import { redactErrorText } from "../utils/redact-error-text.js";
 import { stampVaultAccessDenied, vaultAccessDeniedDiagnostics, } from "../utils/vault-access-denied-error.js";
+import { PlanGateError } from "../utils/plan-gate-error.js";
+import { createPlanLimitRefusalTracker, trackingProgressRecorder, } from "../lib/billing/plan-limit-refusals.js";
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
 export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
 async function defaultSyncFile(input) {
+    // The runner reports a plan-limit refusal as an event, not a throw, and still
+    // returns normally. Track it so the command cannot claim "Sync: complete".
+    const tracker = createPlanLimitRefusalTracker({ companySlug: input.companySlug });
     const result = await share({
         paths: [input.filePath],
         company: input.companySlug,
         hqRoot: input.hqRoot,
         vaultConfig: buildVaultConfig(input.token),
         onConflict: "abort",
+        progressRecorder: trackingProgressRecorder(tracker, input.companySlug),
     });
     return {
         filesUploaded: result.filesUploaded,
         filesSkipped: result.filesSkipped,
         aborted: result.aborted,
+        planLimit: tracker.summary(),
     };
 }
+/**
+ * The upload of a stamped skill file was refused by a plan limit. Registration
+ * and the local stamp already succeeded, so say that on stderr, then return a
+ * typed plan gate for main.ts to render (reason and upgrade link) and exit
+ * non-zero. Never "Skill ready … Sync: complete".
+ */
+function skillUploadRefused(skillUid, filePath, companySlug, refused) {
+    console.warn(chalk.yellow(`⚠ Skill ${skillUid} is stamped locally at '${filePath}', but the upload was refused by your plan limit.`));
+    return new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+        reason: `${refused.message ?? "New files are paused by your plan limit."} ` +
+            "The skill file was not uploaded. Once the limit is sorted, upload it with: " +
+            `hq sync push --company ${companySlug} '${filePath}'`,
+        ...(refused.upgradeUrl ? { upgradeUrl: refused.upgradeUrl } : {}),
+    });
+}
 export function parseSkillUid(markdown) {
     const match = markdown.match(FRONTMATTER_RE);
     if (!match)
@@ -575,6 +597,9 @@ export function registerSkillCommand(program, deps = {}) {
                 // Sentry rather than filing a crash on its first occurrence.
                 throw localSkillError(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
             }
+            if (syncResult.planLimit) {
+                throw skillUploadRefused(registered.skillUid, filePath, companySlug, syncResult.planLimit);
+            }
         }
         console.log(chalk.green(`Skill ready: ${registered.skillUid}`));
         console.log(`  File:     ${filePath}`);
@@ -739,6 +764,9 @@ export function registerSkillCommand(program, deps = {}) {
             if (syncResult.aborted) {
                 throw localSkillError(`Skill ${skillUid} is stamped locally at '${canonicalPath}', but sync aborted because the remote file conflicts.`);
             }
+            if (syncResult.planLimit) {
+                throw skillUploadRefused(skillUid, canonicalPath, companySlug, syncResult.planLimit);
+            }
         }
         console.log(chalk.green(`Skill promoted: ${skillUid}`));
         console.log(`  File:     ${canonicalPath}`);

package/dist/fast-core.js

@@ -54,6 +54,7 @@ export async function runFastCore(argv) {
         args: parsed.args,
         cwd: process.cwd(),
         hqRoot,
+        env: parsed.entry.name === "hq-session" ? { HQ_HQ_SESSION_NO_CLI: "1" } : undefined,
     });
     // Propagate verbatim: these scripts use their exit code as their interface.
     process.exit(code);

package/dist/lib/billing/free-month.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The free-month offer hq-pro attaches to Starter plan-limit payloads (the
+ * usage-limits nag and the hard-stop 402 body). Kept in a leaf module with no
+ * imports so the plan-gate error decoder can reuse the one parser without
+ * pulling in the HTTP layer that itself imports the decoder.
+ */
+export interface PlanLimitFreeMonth {
+    eligible: boolean;
+    trialDays?: number;
+    url?: string;
+}
+/**
+ * Parse `freeMonth` off a server payload. Anything but an explicit
+ * `eligible: true` is "no offer": an absent or malformed field never invents
+ * one.
+ */
+export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
+//# sourceMappingURL=free-month.d.ts.map

package/dist/lib/billing/free-month.js

@@ -0,0 +1,31 @@
+/**
+ * The free-month offer hq-pro attaches to Starter plan-limit payloads (the
+ * usage-limits nag and the hard-stop 402 body). Kept in a leaf module with no
+ * imports so the plan-gate error decoder can reuse the one parser without
+ * pulling in the HTTP layer that itself imports the decoder.
+ */
+/**
+ * Parse `freeMonth` off a server payload. Anything but an explicit
+ * `eligible: true` is "no offer": an absent or malformed field never invents
+ * one.
+ */
+export function parseFreeMonth(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const rec = value;
+    if (rec.eligible !== true)
+        return undefined;
+    const url = typeof rec.url === "string" && rec.url.trim().length > 0
+        ? rec.url.trim()
+        : undefined;
+    const trialDays = typeof rec.trialDays === "number" && Number.isFinite(rec.trialDays)
+        ? rec.trialDays
+        : undefined;
+    return {
+        eligible: true,
+        ...(trialDays !== undefined ? { trialDays } : {}),
+        ...(url ? { url } : {}),
+    };
+}
+//# sourceMappingURL=free-month.js.map

package/dist/lib/billing/plan-limit-refusals.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Collect the files a sync push was refused by a plan limit, from the surfaces
+ * the pinned `@indigoai-us/hq-cloud` runner already has, so `hq sync push`,
+ * `hq sync now` and `hq skill create` never print a success line over a
+ * refusal.
+ *
+ * The runner reports a refusal two ways today:
+ *
+ *   1. A `{ type: "plan-limit", upgradeUrl }` event, emitted once per push pass
+ *      when a presign row carried a code it recognises. It names no path.
+ *   2. A per-file `{ type: "error", path, message }` event for a 402 it does not
+ *      recognise (hq-pro's hard-stop body). The message is hq-cloud's
+ *      `describeError` string, which carries `http=402` and, when the server
+ *      sent one, `code=…`.
+ *
+ * `@indigoai-us/hq-cloud` 6.18.17 (US-012) recognises the hard-stop body,
+ * names each refused path on the `plan-limit` event (`paths`, `count`) and
+ * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
+ * that event; the `error`-message parsing stays for runners older than
+ * 6.18.17.
+ */
+import { type SyncProgressEvent } from "@indigoai-us/hq-cloud";
+/** What one push leg was refused. `null` from the tracker means nothing was. */
+export interface PlanLimitRefusalSummary {
+    /**
+     * Refused files the runner reported. A `plan-limit` event with no path or
+     * count still means at least one file, so this is never 0.
+     */
+    count: number;
+    /** Vault-relative paths the runner named, de-duplicated, in report order. */
+    paths: string[];
+    /** Server sentence from a refused file's error, when one was carried. */
+    message?: string;
+    /** Server-selected (or company billing fallback) upgrade link. */
+    upgradeUrl?: string;
+}
+export interface PlanLimitRefusalTracker {
+    observe(event: SyncProgressEvent): void;
+    summary(): PlanLimitRefusalSummary | null;
+}
+/** True when a runner `error` message is a plan-limit (402) refusal. */
+export declare function isPlanLimitErrorMessage(message: unknown): boolean;
+/**
+ * @param opts.companySlug the push target's slug, used for the company billing
+ *   link when the runner did not carry one. Omit for a personal-vault leg.
+ */
+export declare function createPlanLimitRefusalTracker(opts?: {
+    companySlug?: string;
+}): PlanLimitRefusalTracker;
+/**
+ * The `progressRecorder` for a share() call: feeds the tracker and still writes
+ * the shared progress snapshot, exactly as share()'s default recorder does.
+ * Passing the recorder rather than `onEvent` keeps share()'s own console output
+ * unchanged. `company` is the snapshot label: the target slug, or null for the
+ * personal vault.
+ */
+export declare function trackingProgressRecorder(tracker: PlanLimitRefusalTracker, company: string | null): (event: SyncProgressEvent) => void;
+/** Add a later leg's refusals to an earlier total. */
+export declare function mergePlanLimitRefusals(a: PlanLimitRefusalSummary | null | undefined, b: PlanLimitRefusalSummary | null | undefined): PlanLimitRefusalSummary | null;
+/**
+ * Plain lines describing a refusal: what was not uploaded, why, and the
+ * upgrade link. Colour and the leading status line are the caller's.
+ */
+export declare function renderPlanLimitRefusalLines(summary: PlanLimitRefusalSummary, indent?: string): string[];
+/** "1 new file" / "3 new files", or "new files" when only a notice said so. */
+export declare function describeRefusedCount(summary: PlanLimitRefusalSummary): string;
+/** {@link describeRefusedCount} with its verb: "1 new file was", "new files were". */
+export declare function describeRefusedFiles(summary: PlanLimitRefusalSummary): string;
+//# sourceMappingURL=plan-limit-refusals.d.ts.map

package/dist/lib/billing/plan-limit-refusals.js

@@ -0,0 +1,187 @@
+/**
+ * Collect the files a sync push was refused by a plan limit, from the surfaces
+ * the pinned `@indigoai-us/hq-cloud` runner already has, so `hq sync push`,
+ * `hq sync now` and `hq skill create` never print a success line over a
+ * refusal.
+ *
+ * The runner reports a refusal two ways today:
+ *
+ *   1. A `{ type: "plan-limit", upgradeUrl }` event, emitted once per push pass
+ *      when a presign row carried a code it recognises. It names no path.
+ *   2. A per-file `{ type: "error", path, message }` event for a 402 it does not
+ *      recognise (hq-pro's hard-stop body). The message is hq-cloud's
+ *      `describeError` string, which carries `http=402` and, when the server
+ *      sent one, `code=…`.
+ *
+ * `@indigoai-us/hq-cloud` 6.18.17 (US-012) recognises the hard-stop body,
+ * names each refused path on the `plan-limit` event (`paths`, `count`) and
+ * stops re-sending paused keys. The `path`/`paths`/`count` reads below consume
+ * that event; the `error`-message parsing stays for runners older than
+ * 6.18.17.
+ */
+import { createSyncProgressRecorder, } from "@indigoai-us/hq-cloud";
+import { planLimitUpgradeFallbackUrl } from "./plan-limit-upgrade-url.js";
+/** Upgrade destination when neither the event nor the error named one. */
+const FALLBACK_UPGRADE_URL = "https://hq.computer/billing";
+const PLAN_LIMIT_CODE_TOKEN = /\bcode=(?:PLAN_LIMIT_EXCEEDED|PLAN_LIMIT_REACHED|plan_limit_reached)\b/;
+const HTTP_402_TOKEN = /\bhttp=402\b/;
+const DIAGNOSTIC_TOKEN = /^(?:[A-Za-z]+Error|code=\S+|path=\S+|http=\d+|syscall=\S+|cause=\S+|causeHttp=\d+|host=\S+)$/;
+/** True when a runner `error` message is a plan-limit (402) refusal. */
+export function isPlanLimitErrorMessage(message) {
+    return (typeof message === "string" &&
+        (PLAN_LIMIT_CODE_TOKEN.test(message) || HTTP_402_TOKEN.test(message)));
+}
+/**
+ * The human sentence at the end of a `describeError` string, after its
+ * `Name code=… path=… http=…` diagnostic prefix. Everything up to the `http=`
+ * token is dropped first, because a `path=` value may itself contain spaces.
+ * Undefined when nothing but diagnostics (or a machine token) is left.
+ */
+function serverSentence(message) {
+    const http = /\bhttp=\d+\s+/.exec(message);
+    const rest = http ? message.slice(http.index + http[0].length) : message;
+    const words = rest.trim().split(/\s+/);
+    let index = 0;
+    while (index < words.length && DIAGNOSTIC_TOKEN.test(words[index]))
+        index++;
+    const sentence = words.slice(index).join(" ").trim();
+    if (!sentence || sentence === "plan_limit_reached")
+        return undefined;
+    return sentence;
+}
+function safeHttpsUrl(value) {
+    if (typeof value !== "string" || value.trim() !== value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && !url.username && !url.password
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * @param opts.companySlug the push target's slug, used for the company billing
+ *   link when the runner did not carry one. Omit for a personal-vault leg.
+ */
+export function createPlanLimitRefusalTracker(opts = {}) {
+    const paths = [];
+    let noticeSeen = false;
+    let reportedCount = 0;
+    let message;
+    let upgradeUrl;
+    const addPath = (value) => {
+        if (typeof value === "string" && value && !paths.includes(value)) {
+            paths.push(value);
+        }
+    };
+    return {
+        observe(event) {
+            const record = event;
+            if (event.type === "plan-limit") {
+                noticeSeen = true;
+                upgradeUrl ??= safeHttpsUrl(record.upgradeUrl);
+                addPath(record.path);
+                if (Array.isArray(record.paths))
+                    record.paths.forEach(addPath);
+                if (typeof record.count === "number" && Number.isFinite(record.count)) {
+                    reportedCount += Math.max(0, Math.trunc(record.count));
+                }
+                return;
+            }
+            if (event.type === "error" &&
+                record.diagnostic !== true &&
+                isPlanLimitErrorMessage(record.message)) {
+                noticeSeen = true;
+                addPath(record.path);
+                message ??= serverSentence(record.message);
+            }
+        },
+        summary() {
+            if (!noticeSeen)
+                return null;
+            const fallbackUrl = opts.companySlug
+                ? planLimitUpgradeFallbackUrl(opts.companySlug, FALLBACK_UPGRADE_URL)
+                : undefined;
+            const url = upgradeUrl ?? fallbackUrl;
+            return {
+                count: Math.max(1, paths.length, reportedCount),
+                paths: [...paths],
+                ...(message ? { message } : {}),
+                ...(url ? { upgradeUrl: url } : {}),
+            };
+        },
+    };
+}
+/**
+ * The `progressRecorder` for a share() call: feeds the tracker and still writes
+ * the shared progress snapshot, exactly as share()'s default recorder does.
+ * Passing the recorder rather than `onEvent` keeps share()'s own console output
+ * unchanged. `company` is the snapshot label: the target slug, or null for the
+ * personal vault.
+ */
+export function trackingProgressRecorder(tracker, company) {
+    const record = createSyncProgressRecorder({ company, phase: "push" });
+    return (event) => {
+        tracker.observe(event);
+        record(event);
+    };
+}
+/** Add a later leg's refusals to an earlier total. */
+export function mergePlanLimitRefusals(a, b) {
+    if (!a)
+        return b ?? null;
+    if (!b)
+        return a;
+    const paths = [...a.paths];
+    for (const p of b.paths)
+        if (!paths.includes(p))
+            paths.push(p);
+    const message = a.message ?? b.message;
+    const upgradeUrl = a.upgradeUrl ?? b.upgradeUrl;
+    return {
+        count: a.count + b.count,
+        paths,
+        ...(message ? { message } : {}),
+        ...(upgradeUrl ? { upgradeUrl } : {}),
+    };
+}
+/** How many named paths to print before summarising the rest. */
+const MAX_LISTED_PATHS = 20;
+/**
+ * Plain lines describing a refusal: what was not uploaded, why, and the
+ * upgrade link. Colour and the leading status line are the caller's.
+ */
+export function renderPlanLimitRefusalLines(summary, indent = "  ") {
+    const lines = [];
+    lines.push(`${indent}${summary.message ?? "New files are paused by your plan limit."}`);
+    if (summary.paths.length > 0) {
+        lines.push(`${indent}Not uploaded:`);
+        for (const p of summary.paths.slice(0, MAX_LISTED_PATHS)) {
+            lines.push(`${indent}  - ${p}`);
+        }
+        const unnamed = summary.count - Math.min(summary.paths.length, MAX_LISTED_PATHS);
+        if (unnamed > 0)
+            lines.push(`${indent}  … and ${unnamed} more`);
+    }
+    else {
+        lines.push(`${indent}New files stay on this machine and were not uploaded.`);
+    }
+    if (summary.upgradeUrl)
+        lines.push(`${indent}Upgrade: ${summary.upgradeUrl}`);
+    return lines;
+}
+/** "1 new file" / "3 new files", or "new files" when only a notice said so. */
+export function describeRefusedCount(summary) {
+    if (summary.paths.length === 0 && summary.count <= 1)
+        return "new files";
+    return `${summary.count} new file${summary.count === 1 ? "" : "s"}`;
+}
+/** {@link describeRefusedCount} with its verb: "1 new file was", "new files were". */
+export function describeRefusedFiles(summary) {
+    const subject = describeRefusedCount(summary);
+    return `${subject} ${subject === "1 new file" ? "was" : "were"}`;
+}
+//# sourceMappingURL=plan-limit-refusals.js.map

package/dist/lib/billing/plan-lock.d.ts

@@ -20,6 +20,8 @@
  * An absent field is UNKNOWN, so nothing here ever infers over-limit from
  * missing data (hq-absent-field-never-means-constraining-value).
  */
+import { parseFreeMonth, type PlanLimitFreeMonth } from "./free-month.js";
+export { parseFreeMonth, type PlanLimitFreeMonth };
 /**
  * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
  * fixes the nagging set at these four: `deployments` and `storageBytes` are
@@ -38,11 +40,6 @@ export interface PlanLimitMembers {
 }
 /** @deprecated US-040 — alias of {@link PlanLimitMembers}. */
 export type PlanLockMembers = PlanLimitMembers;
-export interface PlanLimitFreeMonth {
-    eligible: boolean;
-    trialDays?: number;
-    url?: string;
-}
 export interface PlanLimitStatus {
     companySlug: string;
     companyUid?: string;
@@ -78,7 +75,6 @@ export declare const STARTER_AGENT_TARGET = 0;
 export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
 /** The paid plan the nag sends owners to. Copy lives in ONE place. */
 export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
-export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
  * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.