@indigoai-us/hq-cli 5.303.0 → 5.305.0

package/dist/lib/lanes/keep-alive.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { LanesError } from "./errors.js";
 import { dropboxInboxHasMessages } from "./dropbox.js";
 import { appendCappedHistory, listQuestionIds, readQuestion, retryUpdateLane } from "./store.js";
-import { isIsoDateTime } from "./types.js";
+import { isTerminalLaneState, isIsoDateTime, } from "./types.js";
 export const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
 export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 export const LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_FLAG = "lanes.keep-alive-next-check-at";
@@ -254,7 +254,10 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
     return lanes.find((candidate) => {
         if (candidate.lane_id === lane.lane_id || Date.parse(candidate.created_at) <= createdAt)
             return false;
-        if (candidate.state === "cancelled" || candidate.state === "killed" || candidate.state === "failed")
+        if (candidate.state === "cancelled" ||
+            candidate.state === "killed" ||
+            candidate.state === "failed" ||
+            (lane.state === "running" && isTerminalLaneState(candidate.state)))
             return false;
         const candidateCompany = companyOf(candidate) ?? null;
         const sameCompany = laneCompany === null
@@ -270,8 +273,16 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
         const sameLaneSenior = (lane.senior.kind === "lane" || lane.senior.kind === "session") &&
             candidate.senior.kind === lane.senior.kind &&
             candidate.senior.id === lane.senior.id;
+        const differentKnownSenior = lane.senior.kind === "lane" &&
+            candidate.senior.kind === "lane" &&
+            typeof lane.senior.id === "string" &&
+            lane.senior.id.trim().length > 0 &&
+            typeof candidate.senior.id === "string" &&
+            candidate.senior.id.trim().length > 0 &&
+            candidate.senior.id !== lane.senior.id;
         const sameProfile = lane.worker_profile !== undefined &&
             candidate.worker_profile === lane.worker_profile &&
+            !(lane.state === "running" && differentKnownSenior) &&
             !(lineageAware && sameLaneSenior);
         const projectLead = lane.project_id !== undefined &&
             candidate.project_id === lane.project_id &&

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

@@ -11,7 +11,7 @@ import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
 import { outboxQuarantineStatusEnabled } from "../../../work-context/outbox-quarantine-status-flag.js";
 import { formatDroppedPresenceCompany } from "./credentials.js";
-import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
+import { countDistinctHeldEvents, countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
 import { daemonDir, daemonPidPath } from "./paths.js";
 import { readEmitState } from "../emit.js";
@@ -178,7 +178,7 @@ export function collectDaemonDoctor(deps = {}) {
     const heldPath = workMeshHeldPath(meshRoot);
     const deadPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
-    const heldCount = countJsonlLines(heldPath);
+    const heldCount = countDistinctHeldEvents(heldPath);
     const trustedRoots = readDaemonConfig(dir).trustedHqRoots;
     const outboxOperations = listOutboxOperations(ctxRoot);
     const heldWithNoLocalEvidence = readHeldSessions(meshRoot).filter((ref) => {

package/dist/lib/mesh/live/flush.d.ts

@@ -14,7 +14,7 @@ import { type SessionEventsPoster } from "./session-events-client.js";
 export declare const HELD_TTL_MS: number;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export declare const HELD_RETRY_INTERVAL_MS: number;
-/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+/** Cap distinct held events; oldest overflow is dead-lettered with HELD_OVERFLOW. */
 export declare const HELD_MAX_LINES = 20000;
 /**
  * Re-check an unbound session against the project catalog at most this often.
@@ -46,7 +46,7 @@ export interface FlushDeps {
     lastHeldRetryAtMs?: number;
     /** Invoked when this flush claims held, so the daemon can advance its timestamp. */
     onHeldClaimed?: (atMs: number) => void;
-    /** Max lines retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
+    /** Max distinct eventIds retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
     heldMaxLines?: number;
     /** Optional logger (daemon wires this); used once per overflow trim. */
     log?: (message: string) => void;

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

@@ -22,7 +22,7 @@ import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.
 import { LOCAL_ONLY_FIELDS, stripLocalOnlyFields } from "./format-spool-line.js";
 import { enrichSessionEndEvent } from "./report-summary.js";
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
-import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, countJsonlLines, ensureSpoolFile, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
+import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLinesIfAbsent, appendSpoolLine, claimHeld, claimSpool, countDistinctHeldEvents, countJsonlLines, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
 import { workMeshHeldPath, workMeshRoot } from "./paths.js";
 /** Bound a replayed session backlog so one flush cannot burst hundreds of events. */
 const SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH = 25;
@@ -31,7 +31,7 @@ const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
 export const HELD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export const HELD_RETRY_INTERVAL_MS = 5 * 60 * 1000;
-/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+/** Cap distinct held events; oldest overflow is dead-lettered with HELD_OVERFLOW. */
 export const HELD_MAX_LINES = 20_000;
 /**
  * Re-check an unbound session against the project catalog at most this often.
@@ -279,11 +279,9 @@ export async function flushSessionEvents(deps) {
                 state = readSessionState(sessionId, deps.workContextRoot) ?? state;
                 if (!allowed) {
                     const heldAt = now().toISOString();
-                    for (const item of remainingItems) {
-                        appendHeldLine(heldEnvelope(item.event, "NEEDS_COMPANY", item.heldAt ?? heldAt), deps.workMeshRoot);
-                        summary.held += 1;
+                    summary.held += appendHeldLinesIfAbsent(remainingItems.map((item) => heldEnvelope(item.event, "NEEDS_COMPANY", item.heldAt ?? heldAt)), deps.workMeshRoot);
+                    for (const item of remainingItems)
                         markDisposed(item.event);
-                    }
                     continue;
                 }
             }
@@ -306,11 +304,9 @@ export async function flushSessionEvents(deps) {
             }
             if (decision.action === "hold") {
                 const heldAt = now().toISOString();
-                for (const item of remainingItems) {
-                    appendHeldLine(heldEnvelope(item.event, decision.heldReason, item.heldAt ?? heldAt), deps.workMeshRoot);
-                    summary.held += 1;
+                summary.held += appendHeldLinesIfAbsent(remainingItems.map((item) => heldEnvelope(item.event, decision.heldReason, item.heldAt ?? heldAt)), deps.workMeshRoot);
+                for (const item of remainingItems)
                     markDisposed(item.event);
-                }
                 continue;
             }
             // Post a bounded portion of this session's remaining backlog (after any
@@ -368,11 +364,9 @@ export async function flushSessionEvents(deps) {
                         deps.log?.(`work-mesh: session ${sessionId} project missing (HTTP 404); downgraded to needs_project and held events`);
                     }
                     const heldAt = now().toISOString();
-                    for (const item of originalChunk) {
-                        appendHeldLine(heldEnvelope(item.event, "NEEDS_PROJECT", item.heldAt ?? heldAt), deps.workMeshRoot);
-                        summary.held += 1;
+                    summary.held += appendHeldLinesIfAbsent(originalChunk.map((item) => heldEnvelope(item.event, "NEEDS_PROJECT", item.heldAt ?? heldAt)), deps.workMeshRoot);
+                    for (const item of originalChunk)
                         markDisposed(item.event);
-                    }
                     continue;
                 }
                 if (!result.retryable) {
@@ -429,15 +423,17 @@ export async function flushSessionEvents(deps) {
  *   flusher (`hq mesh flush` beside the daemon) may have appended to a fresh
  *   held.jsonl after our claim renamed the old one away.
  * - The overflow claim file is removed only after every dead letter and every
- *   retained line is on disk. If anything throws, the claim stays behind and
- *   recoverOrphanClaims re-reads it on the next flush (duplicates are possible,
- *   loss is not).
+ *   retained line is on disk. Retained rows are idempotent by eventId, so a
+ *   retry after an interrupted append is safe; the claim stays until recovery
+ *   can finish, preserving the append-before-remove ordering.
  */
 function trimHeldOverflow(meshRoot, maxLines, now, summary) {
     if (maxLines <= 0)
         return 0;
     const heldPath = workMeshHeldPath(meshRoot);
-    if (countJsonlLines(heldPath) <= maxLines)
+    const lineCount = countJsonlLines(heldPath);
+    const distinctCount = countDistinctHeldEvents(heldPath);
+    if (lineCount <= maxLines && lineCount === distinctCount)
         return 0;
     const claim = claimHeld(meshRoot, `${now().getTime()}.overflow`);
     if (!claim.claimPath)
@@ -447,15 +443,26 @@ function trimHeldOverflow(meshRoot, maxLines, now, summary) {
         return 0;
     }
     try {
-        if (claim.lines.length <= maxLines) {
-            appendHeldLines(meshRoot, claim.lines);
+        const alreadyHeldIds = readHeldEventIds(heldPath);
+        const seenClaimIds = new Set();
+        const uniqueLines = claim.lines.filter((line) => {
+            const eventId = heldEventIdOfLine(line);
+            if (!eventId)
+                return true;
+            if (alreadyHeldIds.has(eventId) || seenClaimIds.has(eventId))
+                return false;
+            seenClaimIds.add(eventId);
+            return true;
+        });
+        if (uniqueLines.length <= maxLines) {
+            appendHeldLinesOnce(meshRoot, uniqueLines);
             removeClaimFile(claim.claimPath);
             return 0;
         }
-        const overflow = claim.lines.length - maxLines;
+        const overflow = uniqueLines.length - maxLines;
         // Oldest by heldAt: retries regroup held by session, so file order is not
         // chronological. Unparseable lines sort first (dead-lettered first).
-        const ordered = claim.lines
+        const ordered = uniqueLines
             .map((line, idx) => ({ line, idx, atMs: heldAtMs(line) }))
             .sort((a, b) => a.atMs - b.atMs || a.idx - b.idx);
         const toDead = ordered.slice(0, overflow);
@@ -475,7 +482,7 @@ function trimHeldOverflow(meshRoot, maxLines, now, summary) {
             }
             summary.deadLettered += 1;
         }
-        appendHeldLines(meshRoot, toKeep);
+        appendHeldLinesOnce(meshRoot, toKeep);
         summary.heldOverflow = overflow;
         removeClaimFile(claim.claimPath);
         return overflow;
@@ -496,12 +503,25 @@ function heldAtMs(line) {
     const ms = Date.parse(heldAt);
     return Number.isFinite(ms) ? ms : 0;
 }
-function appendHeldLines(meshRoot, lines) {
-    if (lines.length === 0)
-        return;
-    const heldPath = workMeshHeldPath(meshRoot);
-    ensureSpoolFile(heldPath);
-    fs.appendFileSync(heldPath, `${lines.join("\n")}\n`, { mode: 0o600 });
+function appendHeldLinesOnce(meshRoot, lines) {
+    appendHeldLinesIfAbsent(lines, meshRoot);
+}
+function heldEventIdOfLine(line) {
+    const parsed = parseLine(line);
+    return parsed ? eventIdOf(unwrapHeld(parsed).event) : null;
+}
+function readHeldEventIds(filePath) {
+    if (!fs.existsSync(filePath))
+        return new Set();
+    const ids = new Set();
+    for (const line of fs.readFileSync(filePath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        const id = heldEventIdOfLine(line);
+        if (id)
+            ids.add(id);
+    }
+    return ids;
 }
 /**
  * Account a 2xx batch: dead-letter rejected eventIds with their codes;

package/dist/lib/mesh/live/spool.d.ts

@@ -19,6 +19,10 @@ export declare function ensureSpoolFile(filePath: string): void;
 export declare function appendJsonlLine(filePath: string, line: string): void;
 export declare function appendSpoolLine(line: string, root?: string): string;
 export declare function appendHeldLine(line: string, root?: string): string;
+/** Append a held envelope only when its eventId is not already held. */
+export declare function appendHeldLineIfAbsent(line: string, root?: string): boolean;
+/** Append a deduplicated held batch under one file lock and one write. */
+export declare function appendHeldLinesIfAbsent(lines: string[], root?: string): number;
 export declare function appendDeadLetterLine(line: string, root?: string): string;
 export declare function appendDroppedReceipt(receipt: Record<string, unknown>, root?: string): string;
 export interface ClaimResult {
@@ -49,6 +53,8 @@ export declare function recoverOrphanClaims(root: string): {
 export declare function removeClaimFile(claimPath: string | null): void;
 export declare function deadLetterNonEmpty(root?: string): boolean;
 export declare function countJsonlLines(filePath: string): number;
+/** Count held eventIds once; legacy rows without an eventId remain line-counted. */
+export declare function countDistinctHeldEvents(filePath: string): number;
 /** Local queues that still lack a usable company attribution. */
 export interface UnattributedEventCounts {
     spool: number;

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

@@ -5,6 +5,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { ensureOwnerDir } from "../../work-context/atomic.js";
 import { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "./paths.js";
 /** Linux PIPE_BUF is typically 4096; keep a conservative ceiling for one line. */
@@ -65,12 +66,160 @@ export function appendSpoolLine(line, root) {
 }
 export function appendHeldLine(line, root) {
     const held = workMeshHeldPath(root ?? workMeshRoot());
-    appendJsonlLine(held, line);
+    appendHeldLineIfAbsent(line, root);
     return held;
 }
+/** Append a held envelope only when its eventId is not already held. */
+export function appendHeldLineIfAbsent(line, root) {
+    return appendHeldLinesIfAbsent([line], root) === 1;
+}
+/** Append a deduplicated held batch under one file lock and one write. */
+export function appendHeldLinesIfAbsent(lines, root) {
+    const heldPath = workMeshHeldPath(root ?? workMeshRoot());
+    ensureSpoolFile(heldPath);
+    return withJsonlLock(heldPath, () => {
+        const seen = readEventIds(heldPath);
+        const append = [];
+        for (const line of lines) {
+            const eventId = heldEventId(line);
+            if (eventId) {
+                if (seen.has(eventId))
+                    continue;
+                seen.add(eventId);
+            }
+            append.push(line);
+        }
+        appendJsonlLines(heldPath, append);
+        return append.length;
+    });
+}
+function heldEventId(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        const event = record.event && typeof record.event === "object" && !Array.isArray(record.event)
+            ? record.event
+            : record;
+        return typeof event.eventId === "string" && event.eventId.trim() ? event.eventId.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readEventIds(filePath) {
+    const ids = new Set();
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return ids;
+        throw error;
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId)
+            ids.add(eventId);
+    }
+    return ids;
+}
+function appendJsonlLines(filePath, lines) {
+    if (lines.length === 0)
+        return;
+    ensureSpoolFile(filePath);
+    fs.appendFileSync(filePath, `${lines.join("\n")}\n`, { encoding: "utf8", mode: 0o600 });
+    chmodOwnerFile(filePath);
+}
+const JSONL_LOCK_STALE_MS = 5 * 60_000;
+const JSONL_LOCK_TIMEOUT_MS = 5_000;
+/** Serialize check-and-append with claims; stale locks expire after five minutes. */
+function withJsonlLock(filePath, fn) {
+    const lockPath = `${filePath}.lock`;
+    const token = randomBytes(12).toString("hex");
+    const deadline = Date.now() + JSONL_LOCK_TIMEOUT_MS;
+    const waitCell = new Int32Array(new SharedArrayBuffer(4));
+    while (true) {
+        try {
+            const fd = fs.openSync(lockPath, "wx", 0o600);
+            try {
+                fs.writeSync(fd, JSON.stringify({ pid: process.pid, token, at: Date.now() }));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            try {
+                const before = fs.statSync(lockPath);
+                stale = Date.now() - before.mtimeMs >= JSONL_LOCK_STALE_MS;
+                if (stale) {
+                    const after = fs.statSync(lockPath);
+                    if (before.dev === after.dev && before.ino === after.ino && after.mtimeMs === before.mtimeMs) {
+                        fs.unlinkSync(lockPath);
+                    }
+                    else {
+                        stale = false;
+                    }
+                }
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (stale)
+                continue;
+            if (Date.now() >= deadline)
+                throw new SpoolWriteError(`Timed out waiting for ${path.basename(filePath)} lock`);
+            Atomics.wait(waitCell, 0, 0, 10);
+        }
+    }
+    let result;
+    let operationError;
+    let operationFailed = false;
+    try {
+        result = fn();
+    }
+    catch (error) {
+        operationError = error;
+        operationFailed = true;
+    }
+    let cleanupError;
+    try {
+        const record = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (record.token === token)
+            fs.unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            cleanupError = error;
+    }
+    if (operationFailed && cleanupError !== undefined) {
+        throw new AggregateError([operationError, cleanupError], "JSONL write and lock cleanup failed");
+    }
+    if (operationFailed)
+        throw operationError;
+    if (cleanupError !== undefined)
+        throw cleanupError;
+    return result;
+}
 export function appendDeadLetterLine(line, root) {
     const dl = workMeshDeadLetterPath(root ?? workMeshRoot());
-    appendJsonlLine(dl, line);
+    withJsonlLock(dl, () => {
+        ensureSpoolFile(dl);
+        const ids = readEventIds(dl);
+        const eventId = heldEventId(line);
+        if (!eventId || !ids.has(eventId))
+            appendJsonlLine(dl, line);
+    });
     return dl;
 }
 export function appendDroppedReceipt(receipt, root) {
@@ -108,7 +257,8 @@ export function claimSpool(root, ts = `${Date.now()}`) {
 }
 export function claimHeld(root, ts = `${Date.now()}`) {
     ensureOwnerDir(root);
-    return claimJsonlByRename(workMeshHeldPath(root), workMeshClaimPath("held", ts, root));
+    const heldPath = workMeshHeldPath(root);
+    return withJsonlLock(heldPath, () => claimJsonlByRename(heldPath, workMeshClaimPath("held", ts, root)));
 }
 /** Match leftover claim files: spool.<ts>.claimed / held.<ts>.claimed (and held.<ts>.held.claimed). */
 const ORPHAN_CLAIM_RE = /^(spool|held)\..+\.claimed$/;
@@ -195,6 +345,31 @@ export function countJsonlLines(filePath) {
     }
     return n;
 }
+/** Count held eventIds once; legacy rows without an eventId remain line-counted. */
+export function countDistinctHeldEvents(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        // A concurrent claim can rename held.jsonl between existence and read checks.
+        return 0;
+    }
+    const seen = new Set();
+    let count = 0;
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId) {
+            if (seen.has(eventId))
+                continue;
+            seen.add(eventId);
+        }
+        count += 1;
+    }
+    return count;
+}
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -258,8 +433,32 @@ function countUnattributedJsonlLines(filePath) {
 export function countUnattributedEvents(root) {
     const meshRoot = root ?? workMeshRoot();
     const spool = countUnattributedJsonlLines(workMeshSpoolPath(meshRoot));
-    const held = countUnattributedJsonlLines(workMeshHeldPath(meshRoot));
+    const held = countUnattributedHeldEvents(workMeshHeldPath(meshRoot));
     const deadLetter = countUnattributedJsonlLines(workMeshDeadLetterPath(meshRoot));
     return { spool, held, deadLetter, total: spool + held + deadLetter };
 }
+function countUnattributedHeldEvents(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        // A concurrent held claim may rename this file between the read and open.
+        return 0;
+    }
+    const seen = new Set();
+    let count = 0;
+    for (const line of raw.split("\n")) {
+        if (!line.trim() || !isUnattributedLine(line))
+            continue;
+        const eventId = heldEventId(line);
+        if (eventId) {
+            if (seen.has(eventId))
+                continue;
+            seen.add(eventId);
+        }
+        count += 1;
+    }
+    return count;
+}
 //# sourceMappingURL=spool.js.map

package/dist/lib/work-context/bind-best.js

@@ -57,6 +57,17 @@ function readJson(filePath) {
         return null;
     }
 }
+function isInactiveProject(hqRoot, project) {
+    if (!hqRoot || !project.prdPath)
+        return false;
+    const state = readJson(path.join(hqRoot, "workspace", "orchestrator", project.projectId, "state.json"));
+    const status = typeof state?.status === "string" ? state.status.trim().toLowerCase() : "";
+    if (status !== "archived" && status !== "retired")
+        return false;
+    if (typeof state?.prd_path !== "string" || !state.prd_path.trim())
+        return false;
+    return path.resolve(hqRoot, state.prd_path) === path.resolve(project.prdPath);
+}
 function reposFromMetadata(metadata) {
     if (!metadata || typeof metadata !== "object")
         return [];
@@ -225,7 +236,8 @@ export function refineProjectBinding(input) {
     const hint = input.hint?.trim();
     if (!hint)
         return { action: "keep" };
-    const catalog = discoverProjectsCached(input, input.nowMs ?? Date.now());
+    const catalog = discoverProjectsCached(input, input.nowMs ?? Date.now())
+        .filter((project) => !isInactiveProject(input.hqRoot?.trim(), project));
     const exact = catalog.find((row) => row.projectId === hint);
     if (exact?.hasBoard) {
         return { action: "bind", projectId: hint, reason: "exact slug has a Board" };

package/dist/main.js

@@ -38,7 +38,7 @@ import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
-import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
+import { printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
@@ -161,7 +161,8 @@ const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version(CLI_VERSION);
+    .version(CLI_VERSION)
+    .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
 program.hook("preAction", async () => {
     // A host that pinned HQ_AGENT_DIR has declared that it IS that agent, so
     // every command — `hq dm`, `hq secrets`, not only `hq agent …` — must
@@ -206,6 +207,7 @@ export async function runCli() {
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
+    let versionNudgeHandled = false;
     try {
         runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
             category: "command",
@@ -248,6 +250,15 @@ export async function runCli() {
         });
         if (versionAction === "reexec")
             return;
+        // Commander exits immediately for its built-in --version action, before a
+        // nudge can be appended. Handle the global version-only form here so the
+        // installed semver stays the first stdout line and optional guidance follows.
+        if (process.argv.length === 3 &&
+            ["--version", "-V"].includes(process.argv[2] ?? "")) {
+            versionNudgeHandled = true;
+            await printVersionAndNudge();
+            return;
+        }
         // Register every contributor for the selected root only. Root help and
         // unknown-command recovery use generated metadata, so they keep the full
         // Commander surface without evaluating every command implementation.
@@ -298,7 +309,9 @@ export async function runCli() {
             const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
             const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
             await settleWithin([
-                refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+                ...(versionNudgeHandled
+                    ? []
+                    : [refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs })]),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
                 ...inviteTeammateExposureFlushes,

package/dist/utils/self-update.d.ts

@@ -137,6 +137,10 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
+    /** Permission preflight for an npm global prefix (tests inject a read-only result). */
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    /** Home directory used for the durable per-install permission notice marker. */
+    homeDir?: string;
     /** Same-filesystem install rename, injectable for rollback tests. */
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;