@indigoai-us/hq-cli 5.108.25 → 5.109.0

package/dist/lib/mesh/live/emit.js

@@ -0,0 +1,153 @@
+/**
+ * Direct-emit orchestration (owner decision 2026-09-08). One invocation:
+ *   1. drains the local retry file (prior failures),
+ *   2. appends the new event(s),
+ *   3. POSTs /v1/mesh/events in batches with a short bounded retry,
+ *   4. keeps only network/5xx/429-failed or unaccounted events for next time,
+ *   5. records lastPostAt + per-event status counts for `hq mesh doctor`.
+ *
+ * accepted / unassigned / rejected are all terminal (rejected is dropped with a
+ * count — never re-posted). No long-lived process, spool, or held queue.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MESH_EVENTS_BATCH_MAX, parseEmitResults, } from "./emit-client.js";
+import { EMIT_RETRY_MAX, readEmitRetry, writeEmitRetry, } from "./emit-retry.js";
+import { defaultSleep, fullJitterDelayMs, } from "./backoff.js";
+export function emitStatePath(workMeshRoot) {
+    return path.join(workMeshRoot, "emit-state.json");
+}
+export function readEmitState(workMeshRoot) {
+    try {
+        const raw = fs.readFileSync(emitStatePath(workMeshRoot), "utf8");
+        const v = JSON.parse(raw);
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return v;
+    }
+    catch {
+        /* absent / malformed */
+    }
+    return null;
+}
+function writeEmitState(workMeshRoot, state) {
+    const p = emitStatePath(workMeshRoot);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+        const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, p);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function eventIdOf(e) {
+    return typeof e.eventId === "string" && e.eventId.trim() ? e.eventId.trim() : null;
+}
+/** Drain the retry file, post pending + new events, persist failures. */
+export async function emitEvents(deps) {
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const maxAttempts = deps.maxAttempts ?? 3;
+    const retryMax = deps.retryMax ?? EMIT_RETRY_MAX;
+    // Combine pending retry + new events, deduped by eventId (first wins).
+    const pending = readEmitRetry(deps.workMeshRoot);
+    const combined = [];
+    const seen = new Set();
+    for (const e of [...pending, ...(deps.newEvents ?? [])]) {
+        const id = eventIdOf(e);
+        if (id) {
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+        }
+        combined.push(e);
+    }
+    const summary = {
+        attempted: combined.length,
+        accepted: 0,
+        unassigned: 0,
+        rejected: 0,
+        retained: 0,
+        droppedOverflow: 0,
+        retryDepth: 0,
+        batches: 0,
+        statuses: { accepted: 0, unassigned: 0, rejected: 0 },
+    };
+    const keep = [];
+    let anyPosted = false;
+    for (let i = 0; i < combined.length; i += MESH_EVENTS_BATCH_MAX) {
+        const chunk = combined.slice(i, i + MESH_EVENTS_BATCH_MAX);
+        summary.batches += 1;
+        let result = await deps.poster(chunk);
+        for (let attempt = 1; attempt < maxAttempts && !result.ok && result.retryable; attempt += 1) {
+            await sleep(fullJitterDelayMs(attempt - 1, { random }));
+            result = await deps.poster(chunk);
+        }
+        if (!result.ok) {
+            if (result.retryable) {
+                // Network/5xx/429 after retries → keep the whole chunk for next time.
+                keep.push(...chunk);
+                deps.log?.(`emit batch retained (${chunk.length}) status=${result.status}`);
+            }
+            else {
+                // Non-retryable 4xx (e.g. 401/400) → drop with a log (never user data).
+                summary.rejected += chunk.length;
+                summary.statuses.rejected += chunk.length;
+                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status}`);
+            }
+            continue;
+        }
+        anyPosted = true;
+        const results = parseEmitResults(result.body);
+        if (!results) {
+            // Unparseable 2xx → retain rather than pretend posted.
+            keep.push(...chunk);
+            deps.log?.(`emit batch retained (${chunk.length}) unparseable 2xx`);
+            continue;
+        }
+        const byId = new Map(results.map((r) => [r.eventId, r]));
+        for (const e of chunk) {
+            const id = eventIdOf(e);
+            const r = id ? byId.get(id) : undefined;
+            if (!r) {
+                // Unaccounted event in a 2xx → retain (don't lose it).
+                keep.push(e);
+                continue;
+            }
+            summary.statuses[r.status] += 1;
+            if (r.status === "accepted")
+                summary.accepted += 1;
+            else if (r.status === "unassigned")
+                summary.unassigned += 1;
+            else
+                summary.rejected += 1;
+        }
+    }
+    const written = writeEmitRetry(deps.workMeshRoot, keep, retryMax);
+    summary.retained = written.written;
+    summary.droppedOverflow = written.dropped;
+    summary.retryDepth = written.written;
+    const nowIso = now().toISOString();
+    const prior = readEmitState(deps.workMeshRoot) ?? {};
+    const nextState = {
+        ...prior,
+        lastAttemptAt: nowIso,
+        lastAccepted: summary.accepted,
+        lastUnassigned: summary.unassigned,
+        lastRejected: summary.rejected,
+        lastRetryDepth: summary.retryDepth,
+    };
+    if (anyPosted) {
+        nextState.lastPostAt = nowIso;
+        summary.lastPostAt = nowIso;
+        delete nextState.lastError;
+    }
+    else if (combined.length > 0) {
+        nextState.lastError = "emit failed (network/server); retained for retry";
+    }
+    writeEmitState(deps.workMeshRoot, nextState);
+    return summary;
+}
+//# sourceMappingURL=emit.js.map

package/dist/lib/narrow-hint-banner.d.ts

@@ -22,7 +22,6 @@
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
- *   - the synced flag registry disables `sync.narrow-hint`,
  *   - or the same `{companyUid, level}` pair has already been shown this
  *     process (module-singleton dedupe; the runner imports the same module
  *     once per `hq` invocation so a single invocation prints at most one
@@ -47,7 +46,6 @@
  * `syncNarrowHintMinBytes` — see `resolveNarrowHintMinBytes`.
  */
 import * as fs from "node:fs";
-import { type FlagReader } from "./flag-registry.js";
 export type BannerLevel = "hint" | "warning" | "strict";
 /**
  * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
@@ -87,8 +85,6 @@ export interface ShouldShowBannerOpts {
     readFile?: (p: string) => string;
     /** Test seam: override `fs.existsSync`. */
     existsFile?: (p: string) => boolean;
-    /** Test seam: held registry snapshot reader. */
-    flagReader?: FlagReader;
 }
 /**
  * Decides whether a banner should be printed AT ALL — independent of
@@ -154,12 +150,12 @@ export declare function companyFolderExceedsThreshold(companyDir: string, thresh
  * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
  * folder is under the threshold is never refused.
  */
-export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel, flagReader?: FlagReader): boolean;
+export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel): boolean;
 /**
  * Keep the rendered banner honest about the decision that this invocation
  * actually made. Hint and warning remain local presentation choices. `strict`
- * is reserved for a real refusal, so a registry opt-out of an old strict level
- * degrades to the local warning presentation instead of claiming a block.
+ * is reserved for a real refusal, so a strict level that did NOT produce a
+ * refusal degrades to the local warning presentation instead of claiming a block.
  */
 export declare function resolveNarrowHintPresentationLevel(level: BannerLevel, strictRefusal: boolean): BannerLevel;
 /**

package/dist/lib/narrow-hint-banner.js

@@ -22,7 +22,6 @@
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
- *   - the synced flag registry disables `sync.narrow-hint`,
  *   - or the same `{companyUid, level}` pair has already been shown this
  *     process (module-singleton dedupe; the runner imports the same module
  *     once per `hq` invocation so a single invocation prints at most one
@@ -49,7 +48,6 @@
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveFlagGate, resolveProcessFlagGate, } from "./flag-registry.js";
 /**
  * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
  * smaller than this is cheap to keep in full, so all-mode is left alone and no
@@ -101,21 +99,11 @@ export function shouldShowBanner(opts = {}) {
             }
         }
     }
-    const lookup = {
-        globalEnvVar: "HQ_SYNC_NARROW_HINT",
-        globalValueSemantics: {
-            onValues: [],
-            offValues: ["off"],
-            unrecognizedValue: true,
-            unsetValue: true,
-            // Deliberately no `trim`: the legacy parser only case-folds.
-            caseInsensitive: true,
-        },
-        fallback: true,
-    };
-    return opts.flagReader
-        ? resolveFlagGate(opts.flagReader, "sync.narrow-hint", lookup, () => true)
-        : resolveProcessFlagGate("sync.narrow-hint", lookup, () => true);
+    // The env var (`HQ_SYNC_NARROW_HINT=off`, evaluated above) and the
+    // `.hq/config.json` off-switch are the ONLY ways to suppress the banner. This
+    // is a personal preference, not a rollout flag, so nothing else gates it:
+    // reaching here means neither off-switch fired, so the banner shows.
+    return true;
 }
 /**
  * Resolve the banner level from environment overrides. Defaults to
@@ -246,29 +234,20 @@ export function companyFolderExceedsThreshold(companyDir, thresholdBytes, deps =
  * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
  * folder is under the threshold is never refused.
  */
-export function isStrictRefusal(syncMode, level, flagReader) {
+export function isStrictRefusal(syncMode, level) {
     if (syncMode !== "all")
         return false;
-    const lookup = {
-        globalEnvVar: "HQ_SYNC_NARROW_HINT_LEVEL",
-        globalValueSemantics: {
-            onValues: ["strict"],
-            offValues: ["hint", "warning"],
-            unrecognizedValue: false,
-            unsetValue: false,
-            caseInsensitive: true,
-        },
-        fallback: level === "strict",
-    };
-    return flagReader
-        ? resolveFlagGate(flagReader, "sync.narrow-hint-strict", lookup, () => level === "strict")
-        : resolveProcessFlagGate("sync.narrow-hint-strict", lookup, () => level === "strict");
+    // The refusal is driven purely by the caller's `level`, which is itself
+    // resolved from the operator's own `HQ_SYNC_NARROW_HINT_LEVEL` (see
+    // `resolveBannerLevel`). This is a personal escalation choice, not a rollout
+    // flag, so no registry can independently force or clear the strict refusal.
+    return level === "strict";
 }
 /**
  * Keep the rendered banner honest about the decision that this invocation
  * actually made. Hint and warning remain local presentation choices. `strict`
- * is reserved for a real refusal, so a registry opt-out of an old strict level
- * degrades to the local warning presentation instead of claiming a block.
+ * is reserved for a real refusal, so a strict level that did NOT produce a
+ * refusal degrades to the local warning presentation instead of claiming a block.
  */
 export function resolveNarrowHintPresentationLevel(level, strictRefusal) {
     if (strictRefusal)

package/dist/lib/plan-limit-nag.d.ts

@@ -15,7 +15,6 @@
  * Additive only — never throws, never touches `process.exitCode`, never
  * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
  */
-import { type FlagReader } from "./flag-registry.js";
 export declare const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
 export interface PlanLimitEntry {
     used: number;
@@ -40,8 +39,6 @@ export declare function emitPlanLimitNag(opts?: {
     write?: (s: string) => void;
     now?: () => Date;
     statePath?: string;
-    /** Test seam: held registry snapshot reader. */
-    flagReader?: FlagReader;
 }): void;
 /** Test-only helper — clears last-seen status and session dedupe flags. */
 export declare function _resetForTests(): void;

package/dist/lib/plan-limit-nag.js

@@ -19,7 +19,6 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { resolveFlagGate, resolveProcessFlagGate, } from "./flag-registry.js";
 export const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** Module-level last-seen cell — overwritten by each successful parse. */
@@ -31,24 +30,15 @@ let overShownThisSession = false;
 function defaultStatePath() {
     return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
 }
-function isOptedOut() {
-    return process.env.HQ_NO_PLAN_LIMIT_NAG === "1";
-}
-function isPlanLimitNagEnabled(flagReader) {
-    const lookup = {
-        globalEnvVar: "HQ_NO_PLAN_LIMIT_NAG",
-        globalValueSemantics: {
-            onValues: [],
-            offValues: ["1"],
-            unrecognizedValue: true,
-            unsetValue: true,
-        },
-        fallback: true,
-    };
-    const legacyFallback = () => !isOptedOut();
-    return flagReader
-        ? resolveFlagGate(flagReader, "cli.plan-limit-nag", lookup, legacyFallback)
-        : resolveProcessFlagGate("cli.plan-limit-nag", lookup, legacyFallback);
+function isPlanLimitNagEnabled() {
+    // Personal opt-out only: `HQ_NO_PLAN_LIMIT_NAG=1` silences the nag on THIS
+    // machine. This is a user preference, not a rollout flag, so it is read
+    // straight from the environment — no registry lookup, so no future
+    // registration can revoke the opt-out. The value match is asymmetric on
+    // purpose: ONLY the exact value "1" turns the nag off; unset and every other
+    // value (including "0" and "false") keep it on. Do not "tidy" this into a
+    // boolean parse — that would silently silence anyone who wrote "false".
+    return process.env.HQ_NO_PLAN_LIMIT_NAG !== "1";
 }
 /**
  * Defensively parse a single planLimits entry. Returns null if the shape is
@@ -181,7 +171,7 @@ function buildOverBox(overEntries) {
  */
 export function emitPlanLimitNag(opts = {}) {
     try {
-        if (!isPlanLimitNagEnabled(opts.flagReader))
+        if (!isPlanLimitNagEnabled())
             return;
         if (lastSeen === null)
             return;

package/dist/register-all.js

@@ -57,6 +57,7 @@ import { registerWorkersCommand } from "./commands/workers.js";
 import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
+import { registerAccessCommand } from "./commands/access.js";
 import { registerSkillCommand } from "./commands/skill.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerPeopleCommand } from "./commands/people.js";
@@ -157,6 +158,8 @@ export function registerAllCommands(program) {
     // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
     const filesCmd = registerFilesCommand(program);
     registerFilesBrowseCommands(filesCmd);
+    // Top-level `hq access` — vault existence + ACL probe (self-healing ladder).
+    registerAccessCommand(program);
     // Comment-only skill improvement loop. Structured suggestion/review commands are
     // intentionally absent; live content changes remain governed by FILE_ACL sync.
     registerSkillCommand(program);

package/dist/utils/access-denied-hint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared 403 / access-denied formatter for `hq files` and `hq sync`.
+ *
+ * `src/commands/sync.ts` is the legacy modules-sync command and has no 403
+ * path — leave it untouched; this util is the only 403 hint surface.
+ */
+export declare const ACCESS_HINT_PREFIX = "Run: hq access";
+export declare function accessDeniedHint(path?: string): string;
+export declare function formatAccessDenied(message: string, path?: string): string;
+export declare function isAccessDeniedError(err: unknown): boolean;
+export declare function accessDeniedKeyOf(err: unknown): string | undefined;
+/**
+ * Company slug the denied operation was running against, when the thrower
+ * attached one (`createCompanyPresignClient` does). Keys on 403 errors are
+ * bucket-relative, so without this the ladder would fall back to the ACTIVE
+ * company and could probe/DM the wrong tenant.
+ */
+export declare function accessDeniedCompanyOf(err: unknown): string | undefined;
+/** Tenant anchor forwarded to `hq access` so it never guesses the company. */
+export interface AccessLadderContext {
+    company?: string;
+    hqRoot?: string;
+}
+export interface OfferAccessLadderOptions extends AccessLadderContext {
+    isTTY?: boolean;
+    ask?: (question: string) => Promise<boolean>;
+    run?: (path: string, ctx?: AccessLadderContext) => Promise<unknown>;
+    stderr?: (line: string) => void;
+}
+export declare function offerAccessLadder(path: string | undefined, opts?: OfferAccessLadderOptions): Promise<boolean>;
+export declare function reportAccessDenied(message: string, path: string | undefined, opts?: OfferAccessLadderOptions): Promise<void>;
+//# sourceMappingURL=access-denied-hint.d.ts.map

package/dist/utils/access-denied-hint.js

@@ -0,0 +1,139 @@
+/**
+ * Shared 403 / access-denied formatter for `hq files` and `hq sync`.
+ *
+ * `src/commands/sync.ts` is the legacy modules-sync command and has no 403
+ * path — leave it untouched; this util is the only 403 hint surface.
+ */
+import * as readline from "node:readline";
+export const ACCESS_HINT_PREFIX = "Run: hq access";
+export function accessDeniedHint(path) {
+    const target = path && path.length > 0 ? path : "<path>";
+    return `${ACCESS_HINT_PREFIX} ${target}`;
+}
+export function formatAccessDenied(message, path) {
+    return `${message}\n${accessDeniedHint(path)}`;
+}
+function errRecord(err) {
+    if (typeof err === "object" && err !== null)
+        return err;
+    return undefined;
+}
+function errMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    const rec = errRecord(err);
+    if (rec && typeof rec.message === "string")
+        return rec.message;
+    return "";
+}
+export function isAccessDeniedError(err) {
+    const rec = errRecord(err);
+    if (rec) {
+        if (rec.status === 403)
+            return true;
+        const meta = rec.$metadata;
+        if (typeof meta === "object" &&
+            meta !== null &&
+            meta.httpStatusCode === 403) {
+            return true;
+        }
+        if (rec.code === "FILES_PRESIGN_FORBIDDEN")
+            return true;
+    }
+    return /\b403\b|forbidden|not authorized|access denied/i.test(errMessage(err));
+}
+export function accessDeniedKeyOf(err) {
+    const rec = errRecord(err);
+    if (!rec)
+        return undefined;
+    if (typeof rec.key === "string" && rec.key.length > 0)
+        return rec.key;
+    if (typeof rec.path === "string" && rec.path.length > 0)
+        return rec.path;
+    return undefined;
+}
+/**
+ * Company slug the denied operation was running against, when the thrower
+ * attached one (`createCompanyPresignClient` does). Keys on 403 errors are
+ * bucket-relative, so without this the ladder would fall back to the ACTIVE
+ * company and could probe/DM the wrong tenant.
+ */
+export function accessDeniedCompanyOf(err) {
+    const rec = errRecord(err);
+    if (!rec)
+        return undefined;
+    if (typeof rec.company === "string" && rec.company.length > 0)
+        return rec.company;
+    return undefined;
+}
+function defaultIsTTY() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function defaultAsk(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} `, (line) => {
+            rl.close();
+            resolve(line);
+        });
+    });
+    const t = answer.trim().toLowerCase();
+    return t === "y" || t === "yes";
+}
+async function defaultRun(path, ctx) {
+    const m = await import("../commands/access.js");
+    return m.runAccessForPath(path, ctx);
+}
+function ladderContext(opts) {
+    if (!opts)
+        return undefined;
+    const ctx = {};
+    if (opts.company)
+        ctx.company = opts.company;
+    if (opts.hqRoot)
+        ctx.hqRoot = opts.hqRoot;
+    return Object.keys(ctx).length > 0 ? ctx : undefined;
+}
+export async function offerAccessLadder(path, opts) {
+    const stderr = opts?.stderr ?? ((line) => console.error(line));
+    stderr(accessDeniedHint(path));
+    const isTTY = opts?.isTTY ?? defaultIsTTY();
+    if (!isTTY || !path)
+        return false;
+    const ask = opts?.ask ?? defaultAsk;
+    const question = "Run it now? [y/N]";
+    let yes;
+    try {
+        yes = await ask(question);
+    }
+    catch {
+        return false;
+    }
+    if (!yes)
+        return false;
+    const run = opts?.run ?? defaultRun;
+    const ctx = ladderContext(opts);
+    try {
+        if (ctx)
+            await run(path, ctx);
+        else
+            await run(path);
+        return true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderr(`Error: ${message}`);
+        return false;
+    }
+}
+export async function reportAccessDenied(message, path, opts) {
+    const stderr = opts?.stderr ?? ((line) => console.error(line));
+    stderr(message);
+    await offerAccessLadder(path, opts);
+}
+//# sourceMappingURL=access-denied-hint.js.map

package/dist/utils/access-requests.d.ts

@@ -0,0 +1,28 @@
+export declare const ACCESS_REQUEST_DEDUPE_MS: number;
+export interface AccessRequestRecord {
+    requester: string;
+    prefix: string;
+    company: string;
+    grantor: string;
+    sentAt: string;
+    eventId?: string;
+}
+export declare function accessRequestsPath(hqRoot: string): string;
+/**
+ * Read the ledger. A missing file is the empty ledger; any other failure
+ * (unreadable, corrupt JSON, non-array shape) is rethrown with the ledger path
+ * so a corrupt file is never silently replaced by the next write.
+ */
+export declare function readAccessRequests(hqRoot: string): AccessRequestRecord[];
+export declare function recordAccessRequest(hqRoot: string, rec: AccessRequestRecord): void;
+export declare function findRecentAccessRequest(hqRoot: string, args: {
+    requester: string;
+    prefix: string;
+    /** Company slug — `prefix` is company-relative, so it is only unique per company. */
+    company: string;
+    grantor: string;
+    now: number;
+    windowMs?: number;
+}): AccessRequestRecord | null;
+export declare function formatTimeAgo(iso: string, nowMs: number): string;
+//# sourceMappingURL=access-requests.d.ts.map

package/dist/utils/access-requests.js

@@ -0,0 +1,98 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const ACCESS_REQUEST_DEDUPE_MS = 24 * 60 * 60 * 1000;
+export function accessRequestsPath(hqRoot) {
+    return path.join(hqRoot, ".hq", "access-requests.json");
+}
+/**
+ * Read the ledger. A missing file is the empty ledger; any other failure
+ * (unreadable, corrupt JSON, non-array shape) is rethrown with the ledger path
+ * so a corrupt file is never silently replaced by the next write.
+ */
+export function readAccessRequests(hqRoot) {
+    const file = accessRequestsPath(hqRoot);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot read access-request ledger at ${file}: ${message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Corrupt access-request ledger at ${file}: ${message}. Repair or remove the file; it was not overwritten.`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`Corrupt access-request ledger at ${file}: expected a JSON array. Repair or remove the file; it was not overwritten.`);
+    }
+    return parsed;
+}
+export function recordAccessRequest(hqRoot, rec) {
+    // Read first: a corrupt ledger throws here, before anything is written.
+    const existing = readAccessRequests(hqRoot);
+    existing.push(rec);
+    const file = accessRequestsPath(hqRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // Atomic replace: write a sibling tmp file, then rename over the ledger so a
+    // crash mid-write can never leave a truncated file behind.
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(existing, null, 2), "utf-8");
+        fs.renameSync(tmp, file);
+    }
+    finally {
+        // A failed rename must not strand the tmp file next to the ledger.
+        if (fs.existsSync(tmp))
+            fs.unlinkSync(tmp);
+    }
+}
+export function findRecentAccessRequest(hqRoot, args) {
+    const windowMs = args.windowMs ?? ACCESS_REQUEST_DEDUPE_MS;
+    const rows = readAccessRequests(hqRoot);
+    let latest = null;
+    for (const row of rows) {
+        if (row.requester !== args.requester ||
+            row.prefix !== args.prefix ||
+            row.company !== args.company ||
+            row.grantor !== args.grantor) {
+            continue;
+        }
+        const t = Date.parse(row.sentAt);
+        if (!Number.isFinite(t))
+            continue;
+        if (args.now - t > windowMs)
+            continue;
+        if (!latest || Date.parse(latest.sentAt) < t)
+            latest = row;
+    }
+    return latest;
+}
+export function formatTimeAgo(iso, nowMs) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return "just now";
+    const delta = Math.max(0, nowMs - t);
+    const minute = 60 * 1000;
+    const hour = 60 * minute;
+    const day = 24 * hour;
+    if (delta < minute)
+        return "just now";
+    if (delta < hour) {
+        const n = Math.floor(delta / minute);
+        return `${n} minute${n === 1 ? "" : "s"} ago`;
+    }
+    if (delta < day) {
+        const n = Math.floor(delta / hour);
+        return `${n} hour${n === 1 ? "" : "s"} ago`;
+    }
+    const n = Math.floor(delta / day);
+    return `${n} day${n === 1 ? "" : "s"} ago`;
+}
+//# sourceMappingURL=access-requests.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.108.25",
+  "version": "5.109.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {