@indigoai-us/hq-cli 5.197.0 → 5.198.1

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -15,12 +15,14 @@ export type QmdReindexOptions = UtilityIo & {
         cwd: string;
     }) => unknown;
     sizeLimit?: (hqRoot: string) => unknown;
-    /** Test seams for the lock shared by every hq-cli embed entry point. */
+    /** Test seams for the lock shared by every hq-cli QMD writer. */
     embedLockDependencies?: EmbedLockDependencies;
     /** Test seams for the host load gate consulted while the embed lock is held. */
     loadGateDependencies?: LoadGateDependencies;
     /** Test seam for the hq-flags-gated warning on qmd native startup failures. */
     startupFailureWarningsEnabled?: () => boolean;
+    /** Test seam for the default-off shared lock around the full reindex pass. */
+    singleFlightEnabled?: () => boolean;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -7,7 +7,8 @@
  *
  * Contract preserved verbatim: a missing qmd or a non-HQ path is a silent
  * success (a sync must never fail because indexing could not run), the lexical
- * update always runs, and embeddings rebuild only on `--embed`.
+ * update normally runs, and embeddings rebuild only on `--embed`. An enabled
+ * single-flight canary may skip a pass while another QMD writer owns the lock.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -16,6 +17,7 @@ import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
 import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from "../search-index/load-gate.js";
 import { resolveProcessFlagGate } from "../flag-registry.js";
+import { qmdReindexSingleFlightEnabled } from "../search-index/reindex-single-flight-flag.js";
 import { isQmdNativeBindingError, QMD_NATIVE_BINDING_REMEDY, } from "../../utils/qmd-native-binding-error.js";
 import { ioFor, line } from "./common.js";
 export const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
@@ -58,52 +60,59 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         startupFailureWarningShown = true;
         line(stderr, `hq: search index was not updated after sync; ${QMD_NATIVE_BINDING_REMEDY}`);
     };
-    // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
-    try {
-        reconcile(hqRoot, { bin });
-    }
-    catch {
-        /* registration is advisory; an update still helps */
-    }
-    // The cap has to land before the update, not after: qmd decides what to read
-    // at glob time, so an ignore entry written afterwards saves nothing on this
-    // pass. This is the post-sync entry point, which reaches `qmd update` without
-    // going through `hq index sync` at all.
-    try {
-        sizeLimit(hqRoot);
-    }
-    catch {
-        /* an uncapped index is worse than none, but still better than a failed sync */
-    }
-    try {
-        run(["update"], { bin, cwd: hqRoot });
-    }
-    catch (error) {
-        warnOnNativeStartupFailure(error);
-        /* never fail a sync on index freshness */
-    }
-    if (embed) {
+    const updateIndex = () => {
+        // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
+        try {
+            reconcile(hqRoot, { bin });
+        }
+        catch {
+            /* registration is advisory; an update still helps */
+        }
+        // The cap has to land before the update: qmd decides what to read
+        // at glob time, so an ignore entry written afterwards saves nothing on this
+        // pass. This is the post-sync entry point, which reaches `qmd update` without
+        // going through `hq index sync` at all.
+        try {
+            sizeLimit(hqRoot);
+        }
+        catch {
+            /* an uncapped index is worse than none, but still better than a failed sync */
+        }
+        try {
+            run(["update"], { bin, cwd: hqRoot });
+        }
+        catch (error) {
+            warnOnNativeStartupFailure(error);
+            /* never fail a sync on index freshness */
+        }
+    };
+    const runEmbed = (home, lockDependencies) => {
+        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
+        const decision = checkEmbedLoad(home, loadGateDependencies);
+        if (decision.action === "skip") {
+            line(stderr, decision.notice.trimEnd());
+            return "skipped";
+        }
+        if (decision.forced)
+            line(stderr, decision.notice.trimEnd());
+        run(["embed"], { bin, cwd: hqRoot });
+        recordSuccessfulEmbed(home, loadGateDependencies);
+        return undefined;
+    };
+    if ((options.singleFlightEnabled ?? qmdReindexSingleFlightEnabled)()) {
         const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
         const home = resolveQmdHome(lockDependencies.env);
-        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
         try {
             const outcome = runWithEmbedLock(home, lockDependencies, () => {
-                const decision = checkEmbedLoad(home, loadGateDependencies);
-                if (decision.action === "skip") {
-                    line(stderr, decision.notice.trimEnd());
-                    return "skipped";
-                }
-                if (decision.forced)
-                    line(stderr, decision.notice.trimEnd());
-                run(["embed"], { bin, cwd: hqRoot });
-                recordSuccessfulEmbed(home, loadGateDependencies);
-                return undefined;
+                updateIndex();
+                return embed ? runEmbed(home, lockDependencies) : undefined;
             });
             if (outcome === "busy") {
-                line(stderr, "hq: qmd embed is already running; skipping this pass.");
+                line(stderr, "hq: qmd reindex is already running; skipping this post-sync pass.");
+            }
+            if (outcome === "unavailable") {
+                line(stderr, "hq: cannot access the qmd reindex lock; skipping this post-sync pass.");
             }
-            if (outcome === "unavailable")
-                line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
         }
         catch (error) {
             if (error instanceof LoadGateConfigurationError)
@@ -111,6 +120,26 @@ export function qmdReindexAfterSync(args = [], options = {}) {
             warnOnNativeStartupFailure(error);
             /* embeddings are deferred-cost and optional */
         }
+        return 0;
+    }
+    updateIndex();
+    if (!embed)
+        return 0;
+    const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const home = resolveQmdHome(lockDependencies.env);
+    try {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => runEmbed(home, lockDependencies));
+        if (outcome === "busy") {
+            line(stderr, "hq: qmd embed is already running; skipping this pass.");
+        }
+        if (outcome === "unavailable")
+            line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
+    }
+    catch (error) {
+        if (error instanceof LoadGateConfigurationError)
+            line(stderr, `hq: ${error.message}`);
+        warnOnNativeStartupFailure(error);
+        /* embeddings are deferred-cost and optional */
     }
     return 0;
 }

package/dist/lib/lanes/config.d.ts

@@ -37,6 +37,8 @@ export declare const DEFAULT_LIVE_WITHIN_MS: number;
 export declare const DEFAULT_TURN_START_LOST_MS: number;
 /** Spec §9: no event for 12 hours (and no session_end) → lost. */
 export declare const DEFAULT_SILENT_LOST_MS: number;
+/** Unanswered session questions move to the next audience after 10 minutes. */
+export declare const DEFAULT_SESSION_QUESTION_TIMEOUT_SECS: number;
 export declare const DEFAULT_LIVENESS_WINDOWS: LivenessWindows;
 export declare const DEFAULT_PROVIDER_MAX_RUNNING: Record<LaneProvider, number>;
 export declare const DEFAULT_ACCOUNT_HOMES: Record<LaneProvider, string>;

package/dist/lib/lanes/config.js

@@ -41,6 +41,8 @@ export const DEFAULT_LIVE_WITHIN_MS = 10 * 60 * 1000;
 export const DEFAULT_TURN_START_LOST_MS = 2 * 60 * 60 * 1000;
 /** Spec §9: no event for 12 hours (and no session_end) → lost. */
 export const DEFAULT_SILENT_LOST_MS = 12 * 60 * 60 * 1000;
+/** Unanswered session questions move to the next audience after 10 minutes. */
+export const DEFAULT_SESSION_QUESTION_TIMEOUT_SECS = 10 * 60;
 export const DEFAULT_LIVENESS_WINDOWS = {
     live_within_ms: DEFAULT_LIVE_WITHIN_MS,
     turn_start_lost_ms: DEFAULT_TURN_START_LOST_MS,
@@ -340,6 +342,7 @@ export function documentedDefaultConfig(deps = defaultDeps()) {
             min_available_mem_mb: DEFAULT_MIN_AVAILABLE_MEM_MB,
         },
         liveness: { ...DEFAULT_LIVENESS_WINDOWS },
+        session_question_timeout_secs: DEFAULT_SESSION_QUESTION_TIMEOUT_SECS,
     };
 }
 export function parseLanesConfig(raw, deps = defaultDeps()) {
@@ -380,6 +383,7 @@ export function parseLanesConfig(raw, deps = defaultDeps()) {
         providers,
         throttle: parseThrottle(raw.throttle),
         liveness: parseLiveness(raw.liveness),
+        session_question_timeout_secs: positiveInt(raw.session_question_timeout_secs, "session_question_timeout_secs", DEFAULT_SESSION_QUESTION_TIMEOUT_SECS),
     };
 }
 export function lanesConfigPath(hqRoot) {

package/dist/lib/lanes/liveness.d.ts

@@ -40,6 +40,10 @@ export interface LivenessDeps {
     existsSync: (file: string) => boolean;
     mkdirSync: typeof fs.mkdirSync;
     statSync: (file: string) => fs.Stats;
+    lstatSync: (file: string) => fs.Stats;
+    readdirSync: (dir: string, options: {
+        withFileTypes: true;
+    }) => fs.Dirent[];
 }
 export declare function defaultLivenessDeps(): LivenessDeps;
 export declare function defaultSpoolPath(deps?: LivenessDeps): string;
@@ -53,6 +57,14 @@ export declare function livenessIndexPath(hqRoot: string): string;
  * `session_end` as the last event is `ended` even when recent (fast path).
  */
 export declare function classifySessionLiveness(entry: SessionIndexEntry, nowMs: number, presenceConnected?: boolean, windows?: LivenessWindows): LivenessState;
+/**
+ * Use recent Claude transcript file activity when a session has no mesh event
+ * entry. This reads file metadata only; transcript contents are never opened.
+ * If a session transcript exists in more than one configured home, the newest
+ * mtime is the activity signal. A stale or absent transcript remains unknown
+ * and is not evidence of an end.
+ */
+export declare function unindexedClaudeSessionLiveness(sessionId: string, nowMs: number, windows: LivenessWindows, deps?: LivenessDeps, configuredHomes?: readonly string[]): LivenessState | null;
 export declare function ingestSpoolLine(line: string, sessions: Record<string, SessionIndexEntry>, lineNo: number): void;
 export declare function buildLivenessIndexFromSpool(spoolContents: string, meta: {
     spool_path: string;

package/dist/lib/lanes/liveness.js

@@ -37,6 +37,8 @@ export function defaultLivenessDeps() {
         existsSync: (file) => fs.existsSync(file),
         mkdirSync: fs.mkdirSync.bind(fs),
         statSync: (file) => fs.statSync(file),
+        lstatSync: (file) => fs.lstatSync(file),
+        readdirSync: fs.readdirSync.bind(fs),
     };
 }
 export function defaultSpoolPath(deps = defaultLivenessDeps()) {
@@ -81,6 +83,64 @@ export function classifySessionLiveness(entry, nowMs, presenceConnected = false,
         return "idle";
     return "idle";
 }
+/**
+ * Use recent Claude transcript file activity when a session has no mesh event
+ * entry. This reads file metadata only; transcript contents are never opened.
+ * If a session transcript exists in more than one configured home, the newest
+ * mtime is the activity signal. A stale or absent transcript remains unknown
+ * and is not evidence of an end.
+ */
+export function unindexedClaudeSessionLiveness(sessionId, nowMs, windows, deps = defaultLivenessDeps(), configuredHomes = []) {
+    if (sessionId.length === 0 ||
+        sessionId.trim() !== sessionId ||
+        sessionId === "." ||
+        sessionId === ".." ||
+        /[\\/\0]/.test(sessionId)) {
+        throw new LanesError("session_activity_invalid_id", "Cannot inspect Claude activity for an invalid session id", { session_id: sessionId });
+    }
+    const homes = [
+        deps.env.CLAUDE_CONFIG_DIR?.trim(),
+        path.join(deps.homedir(), ".claude"),
+        ...configuredHomes,
+    ].filter((home) => typeof home === "string" && home.trim() !== "");
+    const projectsDirs = [...new Set(homes.map((home) => path.resolve(home, "projects")))];
+    let activityAt = null;
+    for (const projectsDir of projectsDirs) {
+        let projects;
+        try {
+            projects = deps.readdirSync(projectsDir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw new LanesError("session_activity_unreadable", `Cannot inspect Claude project activity: ${err instanceof Error ? err.message : String(err)}`, { path: projectsDir });
+        }
+        for (const project of projects) {
+            if (!project.isDirectory() || project.isSymbolicLink())
+                continue;
+            const transcriptPath = path.join(projectsDir, project.name, `${sessionId}.jsonl`);
+            let transcript;
+            try {
+                transcript = deps.lstatSync(transcriptPath);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw new LanesError("session_activity_unreadable", `Cannot inspect Claude session activity: ${err instanceof Error ? err.message : String(err)}`, { path: transcriptPath });
+            }
+            if (!transcript.isFile() || transcript.isSymbolicLink())
+                continue;
+            if (!Number.isFinite(transcript.mtimeMs)) {
+                throw new LanesError("session_activity_unreadable", `Cannot inspect Claude session activity: invalid modification time`, { path: transcriptPath });
+            }
+            activityAt = Math.max(activityAt ?? Number.NEGATIVE_INFINITY, transcript.mtimeMs);
+        }
+    }
+    if (activityAt === null)
+        return null;
+    const ageMs = nowMs - activityAt;
+    return ageMs >= 0 && ageMs <= windows.live_within_ms ? "live" : null;
+}
 export function ingestSpoolLine(line, sessions, lineNo) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -310,9 +370,11 @@ export function sessionLiveness(hqRoot, sessionId, opts = {}) {
     const deps = opts.deps ?? defaultLivenessDeps();
     const index = loadLivenessIndex(hqRoot, opts.spoolPath, deps);
     const entry = index.sessions[sessionId];
-    if (!entry)
-        return null;
-    const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
+    const config = loadLanesConfig(hqRoot);
+    const windows = opts.windows ?? config.liveness;
+    if (!entry) {
+        return unindexedClaudeSessionLiveness(sessionId, opts.nowMs ?? deps.now(), windows, deps, Object.values(config.providers.claude.accounts).map((account) => account.home));
+    }
     const presenceConnected = opts.presenceConnected ?? readDaemonPresenceConnected(deps);
     return classifySessionLiveness(entry, opts.nowMs ?? deps.now(), presenceConnected, windows);
 }

package/dist/lib/lanes/reconcile.d.ts

@@ -86,7 +86,7 @@ export declare function timeoutPath(hqRoot: string, laneId: string): string;
 export declare function laneRunsHere(lane: LaneRecord, host: ReconcileHost): boolean;
 export declare function agedAdvanceCount(question: QuestionRecord): number;
 export declare function currentHopStartedAtMs(question: QuestionRecord): number;
-export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number): boolean;
+export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number, ageWindowMs?: number): boolean;
 export declare function shouldAdvanceAudienceEnded(audience: SeniorRef, liveness: LivenessState | null): boolean;
 export declare function readTimeoutDeadline(hqRoot: string, laneId: string): {
     deadline_at: string;

package/dist/lib/lanes/reconcile.js

@@ -14,7 +14,7 @@ import { loadLanesConfig, providerQuotaDefaultHoldMs } from "./config.js";
 import { MAX_LANE_DEPTH } from "./constants.js";
 import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./errors.js";
 import { loadWorkerProfile } from "./profile.js";
-import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, } from "./liveness.js";
+import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, unindexedClaudeSessionLiveness, } from "./liveness.js";
 import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
@@ -106,7 +106,7 @@ export function currentHopStartedAtMs(question) {
     const ms = Date.parse(raw);
     return Number.isFinite(ms) ? ms : Number.NEGATIVE_INFINITY;
 }
-export function shouldAgeQuestion(question, audience, nowMs) {
+export function shouldAgeQuestion(question, audience, nowMs, ageWindowMs = QUESTION_AGE_MS) {
     if (question.status !== "pending")
         return false;
     if (audience.kind === "user")
@@ -116,14 +116,14 @@ export function shouldAgeQuestion(question, audience, nowMs) {
     const started = currentHopStartedAtMs(question);
     if (started === Number.NEGATIVE_INFINITY)
         return false;
-    return nowMs - started >= QUESTION_AGE_MS;
+    return nowMs - started >= ageWindowMs;
 }
 export function shouldAdvanceAudienceEnded(audience, liveness) {
     if (audience.kind === "user")
         return false;
     if (audience.kind !== "session")
         return false;
-    return liveness === "ended" || liveness === "lost" || liveness === null;
+    return liveness === "ended";
 }
 export function readTimeoutDeadline(hqRoot, laneId) {
     const filePath = timeoutPath(hqRoot, laneId);
@@ -655,12 +655,25 @@ export async function runPassBody(hqRoot, deps) {
     };
     const readSessionSenior = deps.readSessionSenior ??
         ((sessionId) => defaultReadSessionSenior(hqRoot, sessionId));
+    const configuredClaudeHomes = Object.values(config.providers.claude.accounts).map((account) => account.home);
+    const sessionStateCache = new Map();
     const sessionState = (sessionId) => {
+        if (sessionStateCache.has(sessionId)) {
+            return sessionStateCache.get(sessionId) ?? null;
+        }
         const entry = livenessIndex.sessions[sessionId];
-        if (!entry)
-            return null;
-        return classifySessionLiveness(entry, nowMs, presenceConnected, config.liveness);
+        if (!entry) {
+            const state = unindexedClaudeSessionLiveness(sessionId, nowMs, config.liveness, livenessDeps, configuredClaudeHomes);
+            sessionStateCache.set(sessionId, state);
+            return state;
+        }
+        const state = classifySessionLiveness(entry, nowMs, presenceConnected, config.liveness);
+        sessionStateCache.set(sessionId, state);
+        return state;
     };
+    const questionAgeWindowMs = (audience) => audience.kind === "session"
+        ? config.session_question_timeout_secs * 1000
+        : QUESTION_AGE_MS;
     if (deps.afterLoad)
         await deps.afterLoad();
     markOverdueLanes(hqRoot, lanes, summary, deps, now);
@@ -680,12 +693,22 @@ export async function runPassBody(hqRoot, deps) {
             });
             continue;
         }
-        const liveness = audience.kind === "session" && audience.id
-            ? sessionState(audience.id)
-            : audience.kind === "user"
-                ? "live"
-                : null;
         try {
+            let liveness;
+            try {
+                liveness =
+                    audience.kind === "session" && audience.id
+                        ? sessionState(audience.id)
+                        : audience.kind === "user"
+                            ? "live"
+                            : null;
+            }
+            catch (err) {
+                // A failed metadata probe cannot prove that the session ended, but it
+                // must not suppress the independent unanswered-timeout rule below.
+                markError(summary, err);
+                liveness = null;
+            }
             if (shouldAdvanceAudienceEnded(audience, liveness)) {
                 const nextHop = question.hop + 1;
                 const nextAudience = resolveQuestionAudience({ ...question, hop: nextHop }, readLaneSenior, readSessionSenior);
@@ -712,12 +735,17 @@ export async function runPassBody(hqRoot, deps) {
                 }
                 continue;
             }
-            if (shouldAgeQuestion(question, audience, nowMs)) {
+            if (shouldAgeQuestion(question, audience, nowMs, questionAgeWindowMs(audience))) {
                 const nextHop = question.hop + 1;
                 const nextAudience = resolveQuestionAudience({ ...question, hop: nextHop }, readLaneSenior, readSessionSenior);
-                const result = casQuestionIf(hqRoot, question.question_id, (current) => current.status === "pending" &&
-                    agedAdvanceCount(current) < MAX_AGED_ADVANCES &&
-                    shouldAgeQuestion(current, resolveQuestionAudience(current, readLaneSenior, readSessionSenior), nowMs), (current) => {
+                const result = casQuestionIf(hqRoot, question.question_id, (current) => {
+                    if (current.status !== "pending" ||
+                        agedAdvanceCount(current) >= MAX_AGED_ADVANCES) {
+                        return false;
+                    }
+                    const currentAudience = resolveQuestionAudience(current, readLaneSenior, readSessionSenior);
+                    return shouldAgeQuestion(current, currentAudience, nowMs, questionAgeWindowMs(currentAudience));
+                }, (current) => {
                     const entry = {
                         hop: current.hop + 1,
                         audience: nextAudience,
@@ -748,7 +776,7 @@ export async function runPassBody(hqRoot, deps) {
             markDirty(summary, {
                 kind: "question",
                 id: question.question_id,
-                why: `advance failed: ${err instanceof Error ? err.message : String(err)}`,
+                why: `advance failed: ${err instanceof LanesError ? `${err.error}: ` : ""}${err instanceof Error ? err.message : String(err)}`,
             });
         }
     }

package/dist/lib/lanes/tracker-store.d.ts

@@ -0,0 +1,27 @@
+export type TrackerKind = "blocker" | "kpi" | "okr" | "directive";
+export interface TrackerRecord {
+    schema_version: "hq-lanes-tracker-record.v1";
+    kind: TrackerKind;
+    id: string;
+    company: string;
+    project_id: string;
+    version: number;
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+}
+export interface TrackerRecordInput {
+    kind: TrackerKind;
+    id?: string;
+    company: string;
+    project_id: string;
+    [key: string]: unknown;
+}
+export interface TrackerStore {
+    read(kind: TrackerKind, id: string): TrackerRecord | null;
+    list(kind: TrackerKind): TrackerRecord[];
+    create(record: TrackerRecordInput): TrackerRecord;
+    update(kind: TrackerKind, id: string, expectedVersion: number, change: (current: TrackerRecord) => TrackerRecord): TrackerRecord;
+}
+export declare function createLocalTrackerStore(projectDirectory: string, now?: () => Date): TrackerStore;
+//# sourceMappingURL=tracker-store.d.ts.map