@indigoai-us/hq-cli 5.345.155 → 5.345.159

package/dist/commands/core-pipeline-driver-native.js

@@ -4,7 +4,15 @@ import * as path from "node:path";
 import { inflateRawSync } from "node:zlib";
 import { isPipelineDriverProcess } from "./core-pipeline-driver-process.js";
 /* eslint-disable @typescript-eslint/no-explicit-any */
-export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync) {
+// Longest time a routed phase may wait in its lane's queue before the driver
+// gives up on it (PC_QUEUE_MAX_MIN minutes, default 240: twice the default
+// PC_DEADLINE_MIN). Queue time does not count toward the deadline or the stall
+// window, so this ceiling is what ends a run whose lane is never admitted.
+export function queueMaxSeconds(env = process.env) {
+    const minutes = Number.parseInt(String(env.PC_QUEUE_MAX_MIN ?? ''), 10);
+    return (Number.isFinite(minutes) && minutes > 0 ? minutes : 240) * 60;
+}
+export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync, queueMax = queueMaxSeconds()) {
     const S = stateDir, MAX = maxFails, HQ = hqBin;
     const TERMINAL = ['passed', 'failed', 'blocked'];
     const EARLY = 'engine_exited_early';
@@ -78,6 +86,59 @@ export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync) {
             return { reason: 'loop_stalled', phase: ph, story_id: sid };
         return state === 'failed' ? { reason: state, phase: ph, story_id: sid } : null;
     }
+    // The deadline bounds work time, not queue time (ported from hq-core-staging
+    // #1357). An envelope still waiting in its loop lane's queue (the lane is queued
+    // for admission behind the host throttle, or busy on another envelope) is not
+    // past its deadline yet. With no lane row or no loop status the deadline applies.
+    // An admitted lane counts as holding the envelope only while its queue is not
+    // empty: a lane with queue_depth 0 that is not working on this envelope has lost
+    // or dropped it, and the deadline applies.
+    // Known limit: while the lane is busy on an envelope from another run, this phase
+    // waits on that envelope's own watchdog; PC_QUEUE_MAX_MIN still bounds the wait.
+    function waitingInQueue(worker, envId) {
+        if (typeof envId !== 'string' || !envId)
+            return false;
+        const row = laneRow(worker);
+        if (isObj(row) && get(row, 'state', null) === 'queued')
+            return true;
+        const loop = get(row, 'loop', null);
+        if (!isObj(loop) || !Object.prototype.hasOwnProperty.call(loop, 'active_envelope_id'))
+            return false;
+        if (get(loop, 'active_envelope_id', null) === envId)
+            return false;
+        const depth = get(loop, 'queue_depth', 0);
+        return isNum(depth) && depth > 0;
+    }
+    const queuedMark = (sid, ph) => path.join(S, 'driver', `queued-${sid}-${ph}`);
+    function clearQueuedMark(sid, ph) {
+        try {
+            fs.rmSync(queuedMark(sid, ph), { force: true });
+        }
+        catch (e) { /* best effort */ }
+    }
+    // The deadline to enforce, or null while the envelope still waits. The envelope
+    // deadline is stamped at routing, so the time the envelope was last seen waiting
+    // is added back: a phase gets its full budget once the lane picks it up.
+    // driver/queued-<sid>-<phase> holds that time (epoch seconds).
+    function workDeadline(sid, ph, dl, since, waiting) {
+        const mark = queuedMark(sid, ph);
+        if (waiting) {
+            try {
+                fs.writeFileSync(mark, String(Math.trunc(now())) + '\n');
+            }
+            catch (e) { /* best effort */ }
+            return null;
+        }
+        let seen = NaN;
+        try {
+            seen = parseInt(fs.readFileSync(mark, 'utf8'), 10);
+        }
+        catch (e) { /* never queued */ }
+        const base = epoch(dl);
+        if (!isNum(since) || !Number.isFinite(seen) || seen <= since || base === null)
+            return dl;
+        return new Date((base + (seen - Math.trunc(since))) * 1000).toISOString().slice(0, 19) + 'Z';
+    }
     function mtime(p) {
         try {
             return fs.statSync(p).mtimeMs / 1000;
@@ -146,6 +207,7 @@ export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync) {
             const hstat = mine ? get(hd, 'status', null) : null;
             let ev = null;
             if (mine && TERMINAL.includes(hstat) && get(hd, 'exit_reason', null) !== EARLY) {
+                clearQueuedMark(sid, ph);
                 out.push(['ACCEPT', sid, ph, h]);
             }
             else if (mine && get(hd, 'exit_reason', null) === EARLY) {
@@ -153,6 +215,7 @@ export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync) {
                 if (!isNum(secs))
                     secs = since !== null ? Math.trunc(now() - since) : 0;
                 const why = collapse(str(truthy(hd.notes) ? hd.notes : truthy(hd.summary) ? hd.summary : 'no reason given'));
+                clearQueuedMark(sid, ph);
                 out.push(['EARLY', sid, ph, String(Math.trunc(secs)), why]);
             }
             else if ((!mine || !TERMINAL.includes(hstat)) && (ev = phaseExit(worker, sid, ph, since)) !== null) {
@@ -171,8 +234,15 @@ export function scanDriverState(stateDir, maxFails, hqBin, run = spawnSync) {
             else {
                 const env = load(path.join(S, 'envelopes', `${sid}-${ph}.json`));
                 const dl = get(env, 'deadline', null);
-                if (typeof dl === 'string' && isoNow() > dl)
-                    out.push(['DEADLINE', sid, ph, dl]);
+                const waiting = waitingInQueue(worker, get(env, 'id', null));
+                if (waiting && isNum(since) && now() - since >= queueMax) {
+                    out.push(['QUEUED_TOO_LONG', sid, ph, String(Math.trunc(now() - since)), String(get(laneRow(worker), 'lane_id', worker))]);
+                }
+                else if (typeof dl === 'string') {
+                    const due = workDeadline(sid, ph, dl, since, waiting);
+                    if (due !== null && isoNow() > due)
+                        out.push(['DEADLINE', sid, ph, due]);
+                }
                 if (since !== null)
                     out.push(['INFLIGHT', sid, ph, String(Math.max(0, Math.trunc(now() - since)))]);
             }
@@ -293,7 +363,8 @@ export function checkDriverStall(stateDir, stallWindow, hqBin, run = spawnSync)
                     byWorker.set(worker, r);
         for (const [sid, worker, s] of inflight) {
             const r = byWorker.get(worker);
-            if (r && get(r.loop, 'queue_depth', 0) > 0 && !truthy(get(r.loop, 'active_envelope_id', null))) {
+            // a lane queued for admission (host throttle, queue position) is waiting, not stalled
+            if (r && get(r, 'state', null) !== 'queued' && get(r.loop, 'queue_depth', 0) > 0 && !truthy(get(r.loop, 'active_envelope_id', null))) {
                 cond = true;
                 stories.push(sid);
                 lanes.push(get(r, 'lane_id', worker));
@@ -480,6 +551,45 @@ export async function sleep(ms, signal) {
         signal?.addEventListener("abort", finish, { once: true });
     });
 }
+/**
+ * Move a handoff that failed validation to a numbered sibling
+ * (handoffs/<story>-<phase>.invalid.<n>.json) so the worker's evidence is never
+ * lost, and write a failed handoff in its place that names the validation
+ * error and the kept file. Returns both paths.
+ */
+export function quarantineInvalidHandoff(state, storyId, phase, handoffPath, reason) {
+    const dir = path.dirname(handoffPath);
+    let n = 1;
+    let keptPath = path.join(dir, `${storyId}-${phase}.invalid.${n}.json`);
+    while (fs.existsSync(keptPath)) {
+        n += 1;
+        keptPath = path.join(dir, `${storyId}-${phase}.invalid.${n}.json`);
+    }
+    fs.renameSync(handoffPath, keptPath);
+    const story = readJson(path.join(state, "stories", `${storyId}.json`));
+    const storyRecord = story && typeof story === "object" ? story : {};
+    const current = Number.isInteger(storyRecord.current) ? storyRecord.current : 0;
+    const worker = storyRecord.phases?.[current]?.worker ?? "None";
+    const loaded = readJson(keptPath);
+    const workerId = loaded && typeof loaded === "object" && typeof loaded.worker_id === "string" && loaded.worker_id ? loaded.worker_id : String(worker);
+    const record = {
+        schema: "hq-phase-handoff/v1",
+        story_id: storyId,
+        phase,
+        worker_id: workerId,
+        status: "failed",
+        exit_reason: "invalid_handoff",
+        summary: `invalid handoff: ${reason}`,
+        files_changed: [],
+        commits: [],
+        back_pressure: { tests: "skip", lint: "skip", typecheck: "skip", build: "skip" },
+        context_for_next: `The worker handoff failed validation (${reason}). It is kept unchanged at ${keptPath}.`,
+        invalid_handoff_path: keptPath,
+        notes: reason,
+    };
+    fs.writeFileSync(handoffPath, `${JSON.stringify(record)}\n`);
+    return { keptPath, handoffPath };
+}
 function writeEarlyHandoff(state, storyId, phase, seconds, reason) {
     const story = readJson(path.join(state, "stories", `${storyId}.json`));
     const storyRecord = story && typeof story === "object" ? story : {};
@@ -697,7 +807,21 @@ export async function runPipelineDriverNative(args, hqRoot = "") {
                         writeDriverLog(logFile, `ACCEPTING ${a} ${b} ${c}`);
                         const result = runPc(["accept", "--state", state, "--story", a, "--handoff", c]);
                         writeDriverLog(logFile, `ACCEPT ${a} ${b} rc=${result.code}: ${result.stdout.trim()}`);
-                        if (!((result.code === 0 && (/^(NEXT|RECHECK)/.test(result.stdout))) || (result.code === 1 && /^PHASE_/.test(result.stdout)) || (result.code === 10 && /^PHASE_BLOCKED/.test(result.stdout)))) {
+                        const invalid = /invalid handoff: (.*)/.exec(result.stderr);
+                        if (result.code !== 0 && invalid) {
+                            // A worker wrote a handoff that fails validation. Keep it on disk
+                            // beside the handoff, record the phase as failed with the reason,
+                            // and keep driving: the fail cap bounds the retries.
+                            const reason = invalid[1].trim();
+                            const kept = quarantineInvalidHandoff(state, a, b, c, reason);
+                            writeDriverLog(logFile, `INVALID_HANDOFF ${a} ${b}: ${reason}; worker handoff kept at ${kept.keptPath}`);
+                            const failed = runPc(["accept", "--state", state, "--story", a, "--handoff", kept.handoffPath]);
+                            writeDriverLog(logFile, `ACCEPT ${a} ${b} rc=${failed.code}: ${failed.stdout.trim()}`);
+                            if (!(failed.code === 1 && failed.stdout.startsWith("PHASE_FAILED"))) {
+                                return finish(23, `accept invalid handoff ${a} ${b}: unexpected (rc=${failed.code}): ${failed.stdout} ${failed.stderr}`);
+                            }
+                        }
+                        else if (!((result.code === 0 && (/^(NEXT|RECHECK)/.test(result.stdout))) || (result.code === 1 && /^PHASE_/.test(result.stdout)) || (result.code === 10 && /^PHASE_BLOCKED/.test(result.stdout)))) {
                             return finish(23, `accept ${a} ${b}: unexpected (rc=${result.code}): ${result.stdout} ${result.stderr}`);
                         }
                         acted = 1;
@@ -717,6 +841,8 @@ export async function runPipelineDriverNative(args, hqRoot = "") {
                     }
                     else if (action === "DEADLINE")
                         return finish(22, `phase ${a}/${b} passed its deadline ${c} with no handoff`);
+                    else if (action === "QUEUED_TOO_LONG")
+                        return finish(22, `phase ${a}/${b} waited ${c}s in the queue of lane ${d} without being picked up (limit PC_QUEUE_MAX_MIN=${queueMaxSeconds() / 60} min); check lane admission (hq lanes list), then restart the driver`);
                     else if (action === "HELD")
                         held = `${a} ${b}`;
                     else if (action === "BLOCKED")

package/dist/commands/core.js

@@ -652,6 +652,12 @@ export function registerCoreCommands(program) {
         .allowExcessArguments()
         .helpOption(false)
         .action((target, args = [], _opts, cmd) => {
+        // Help must never write. `--help`/`-h` in the target slot prints the
+        // command usage instead of being treated as an unknown target.
+        if (target === "--help" || target === "-h") {
+            process.stdout.write(`Usage: hq core rebuild-index <target> [args...]\n\nRegenerate one index. Targets: ${validTargets.join(", ")}.\nRun \`hq core rebuild-index <target> --help\` for target options. Help performs no writes.\n`);
+            return;
+        }
         const entry = REBUILD_INDEX_TARGETS.find((candidate) => candidate.target === target);
         if (!entry) {
             throw expectedUserError(`Unknown rebuild-index target "${target}". Valid targets: ${validTargets.join(", ")}.`);
@@ -663,10 +669,16 @@ export function registerCoreCommands(program) {
         const rendererArgs = passthrough.filter((arg) => arg !== "--accept");
         const isCompaniesTarget = entry.renderer === "companies";
         const wantsHelp = rendererArgs.some((arg) => arg === "--help" || arg === "-h");
-        if (isCompaniesTarget && wantsHelp) {
+        if (wantsHelp && ["companies", "company-knowledge", "projects"].includes(entry.renderer)) {
             renderIndexTarget(entry.renderer, { root: "", output: (message) => process.stdout.write(message) }, rendererArgs);
             return;
         }
+        if (wantsHelp) {
+            // Every other renderer has no option grammar of its own; print usage
+            // and exit before resolving a root or rendering anything.
+            process.stdout.write(`Usage: hq core rebuild-index ${entry.target} [--accept]\n\n${entry.summary}. Help performs no writes.\n`);
+            return;
+        }
         const requestsCompanyScope = isCompaniesTarget && rendererArgs.some((arg) => arg === "--company" || arg.startsWith("--company="));
         if (requestsCompanyScope && !coreCompanyIndexScopeEnabled()) {
             throw expectedUserError("rebuild-index companies --company is disabled; enable cli.rebuild-index-company-scope for a canary.");

package/dist/commands/crm.js

@@ -2,6 +2,23 @@ import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getEntityUid } from "../utils/vault-api.js";
+import { readSessionCompanyLock } from "../lib/session-company-lock.js";
+import { sessionIdFromEnv } from "../lib/core-utils/session-id.js";
+import { MULTI_COMPANY_SESSION_LOCK_FLAG } from "../lib/cli-flag-keys.js";
+import { fastFlagEnabledDefaultOn } from "../native-fast-route.js";
+async function resolveCrmCompany(requestedCompany) {
+    const lock = sessionIdFromEnv(process.env)
+        && await fastFlagEnabledDefaultOn(MULTI_COMPANY_SESSION_LOCK_FLAG)
+        ? readSessionCompanyLock(process.env)
+        : undefined;
+    const company = requestedCompany ?? lock?.companies[0];
+    if (lock && company && !lock.companies.includes(company)) {
+        throw new Error(`Company '${company}' is outside this session's locked company set.`);
+    }
+    if (!company)
+        throw new Error("--company <slug> is required.");
+    return company;
+}
 /**
  * `hq crm entity upsert` — agent-facing controlled entity upsert
  * (hq-native-crm US-002). Wraps `POST /crm/entities`, which fronts the ontology
@@ -19,6 +36,17 @@ const CRM_ENTITY_TYPES = [
     "invoice",
     "company",
 ];
+/** Entity types the read route accepts as a `list --type` filter. */
+const CRM_READ_ENTITY_TYPES = [
+    "person",
+    "project",
+    "company",
+    "concept",
+    "contact",
+    "deal",
+    "contract",
+    "invoice",
+];
 const CRM_SETTINGS_PRECHECK_TIMEOUT_MS = 3_000;
 const CRM_DISABLED_HINT_PREFIX = "CRM is not enabled for this company. Enable it first: ";
 function printCrmDisabledHint(companySlug) {
@@ -129,11 +157,64 @@ function buildEntityFromFlags(opts) {
 export function registerCrmCommand(program) {
     const crm = program
         .command("crm")
-        .description("Native CRM — upsert canonical entities into a company vault")
+        .description("Read and upsert canonical CRM entities in a company vault")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     const entity = crm
         .command("entity")
         .description("CRM entity operations");
+    async function readEntities(path, query) {
+        try {
+            const companySlug = await resolveCrmCompany(crm.opts().company);
+            const token = await ensureCognitoToken();
+            const companyUid = await getEntityUid(token, { companySlug });
+            const res = await vaultApiFetch({ token, path, query: { ...query, companyUid }, signal: AbortSignal.timeout(25_000) });
+            const text = await res.text();
+            let result;
+            try {
+                result = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                if (res.ok)
+                    throw new Error(`CRM read returned a non-JSON response (HTTP ${res.status})`);
+                result = undefined;
+            }
+            if (!res.ok) {
+                if (res.status === 403 && isRecord(result) && result.code === "CRM_DISABLED")
+                    printCrmDisabledHint(companySlug);
+                throw new Error(isRecord(result) && typeof result.error === "string" ? result.error : `CRM read failed (HTTP ${res.status})`);
+            }
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exit(1);
+        }
+    }
+    entity.command("list")
+        .description("List one CRM entity page as JSON; continue with nextCursor until null")
+        .option("--type <type>", `Filter by entity type: ${CRM_READ_ENTITY_TYPES.join(" | ")}`)
+        .option("--stage <stage>", "Exact pipeline stage")
+        .option("--name <text>", "Case-insensitive canonical name filter")
+        .option("--limit <number>", "Object keys examined per page (1–100)", "50")
+        .option("--cursor <cursor>", "Continue a prior page with the same company and filters")
+        .action(async (opts) => {
+        if (!/^\d+$/.test(opts.limit) || Number(opts.limit) < 1 || Number(opts.limit) > 100) {
+            console.error(chalk.red("Error: --limit must be an integer from 1 to 100."));
+            process.exit(1);
+        }
+        if (opts.type !== undefined && !CRM_READ_ENTITY_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Error: --type must be one of ${CRM_READ_ENTITY_TYPES.join(", ")}.`));
+            process.exit(1);
+        }
+        const query = Object.fromEntries(Object.entries(opts).filter((entry) => typeof entry[1] === "string"));
+        await readEntities("/crm/entities", query);
+    });
+    entity.command("get <id>")
+        .description("Read a canonical CRM entity as JSON")
+        .option("--key <path>", "Source key returned by list, for direct lookup in large vaults")
+        .action(async (id, opts) => {
+        await readEntities(`/crm/entities/${encodeURIComponent(id)}`, opts.key ? { key: opts.key } : {});
+    });
     entity
         .command("upsert")
         .description("Create or update a canonical CRM entity (POST /crm/entities). " +
@@ -148,11 +229,7 @@ export function registerCrmCommand(program) {
         .option("--json <file|->", "Path to a JSON file (or '-' for stdin) with a full entity object or array")
         .action(async (opts) => {
         try {
-            const companySlug = crm.opts().company;
-            if (!companySlug) {
-                console.error(chalk.red("Error: --company <slug> is required."));
-                process.exit(1);
-            }
+            const companySlug = await resolveCrmCompany(crm.opts().company);
             // Resolve the entity payload: --json is the alternative to flags.
             let entities;
             if (opts.json) {

package/dist/commands/deploy-access.d.ts

@@ -0,0 +1,33 @@
+import { Command } from "commander";
+/**
+ * `hq deploy access` reads and changes a deploy app's access policy through
+ * hq-deploy's GET/PUT /api/apps/:id/access-policy (the same API the HQ console
+ * access modal uses). Feedback bcd64202-071a-4d01-9005-3329a13ca4ae.
+ */
+export declare const DEPLOY_ACCESS_MODES: readonly ["company", "selected", "public"];
+export type DeployAccessMode = (typeof DEPLOY_ACCESS_MODES)[number];
+interface Grantee {
+    id: string;
+}
+export interface AccessPolicyView {
+    appId: string | null;
+    mode: string | null;
+    companyUid: string | null;
+    users: Grantee[];
+    groups: Grantee[];
+    policyVersion: number | null;
+    updatedAt: string | null;
+}
+/**
+ * Terminal hooks for the approval prompt. Tests replace these; production reads
+ * the real TTY state and asks on stdin.
+ */
+export declare const deployAccessPrompt: {
+    isInteractive: () => boolean;
+    ask: (question: string) => Promise<string>;
+};
+export declare function parseMode(raw: string): DeployAccessMode;
+export declare function toView(body: Record<string, unknown>): AccessPolicyView;
+export declare function registerDeployAccessCommand(deploy: Command): void;
+export {};
+//# sourceMappingURL=deploy-access.d.ts.map