@indigoai-us/hq-cli 5.282.0 → 5.283.0

package/dist/lib/lanes/outpost-snapshot-cache.js

@@ -0,0 +1,215 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+export const OUTPOST_SNAPSHOT_CACHE_TTL_MS = 3_000;
+export const OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS = 45_000;
+const CACHE_RELATIVE_PATH = path.join("workspace", "lanes-runs", ".cache", "outpost-snapshots");
+const CACHE_SCHEMA_VERSION = "hq-lanes-outpost-snapshot-cache.v1";
+const LOCK_POLL_MS = 20;
+const LOCK_WAIT_MS = 60_000;
+/** Deduplicates identical remote snapshot queries within one command invocation. */
+export class OutpostSnapshotInvocationMemo {
+    requests = new Map();
+    getOrCreate(outpostId, query, fetch) {
+        const key = JSON.stringify([outpostId, query]);
+        const existing = this.requests.get(key);
+        if (existing)
+            return existing;
+        const request = fetch();
+        this.requests.set(key, request);
+        return request;
+    }
+}
+export function outpostLaneListSnapshotKey(outpostId, normalizedQuery) {
+    return JSON.stringify(["lane-list", outpostId, normalizedQuery]);
+}
+export function outpostSnapshotCachePath(hqRoot, key) {
+    const digest = createKeyDigest(key);
+    return path.join(hqRoot, CACHE_RELATIVE_PATH, `${digest}.json`);
+}
+export async function getOrFetchOutpostSnapshot(input) {
+    const policy = input.policy ?? {};
+    const now = policy.now ?? Date.now;
+    const ttlMs = policy.ttlMs ?? OUTPOST_SNAPSHOT_CACHE_TTL_MS;
+    const staleLockMs = policy.staleLockMs ?? OUTPOST_SNAPSHOT_CACHE_STALE_LOCK_MS;
+    const lockWaitMs = policy.lockWaitMs ?? LOCK_WAIT_MS;
+    const pollMs = policy.pollMs ?? LOCK_POLL_MS;
+    const sleep = policy.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const filePath = outpostSnapshotCachePath(input.hqRoot, input.key);
+    const cached = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+    if (cached !== undefined)
+        return cached;
+    const lockPath = `${filePath}.lock`;
+    const token = `${process.pid}:${randomBytes(12).toString("hex")}`;
+    const startedAt = now();
+    const acquireLock = policy.acquireLock ?? createCacheLock;
+    while (true) {
+        try {
+            acquireLock(lockPath, token, now());
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                process.stderr.write(`${JSON.stringify({
+                    event: "lanes.outpost_snapshot_cache_lock_unavailable",
+                    error: typeof code === "string" ? code : "UnknownError",
+                    fallback: "uncached",
+                })}\n`);
+                const value = await input.fetch();
+                if (!input.isValue(value)) {
+                    throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
+                }
+                return value;
+            }
+            if (recoverStaleLock(lockPath, staleLockMs, now()))
+                continue;
+            const afterWait = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+            if (afterWait !== undefined)
+                return afterWait;
+            if (now() - startedAt >= lockWaitMs) {
+                throw new LanesError("outpost_snapshot_cache_lock_timeout", "Timed out waiting for an Outpost snapshot refresh", { path: lockPath });
+            }
+            await sleep(pollMs);
+        }
+    }
+    try {
+        const afterLock = readFreshCache(filePath, input.key, now(), ttlMs, input.isValue);
+        if (afterLock !== undefined)
+            return afterLock;
+        const value = await input.fetch();
+        if (!input.isValue(value)) {
+            throw new LanesError("outpost_snapshot_cache_value_invalid", "Outpost snapshot fetch returned an invalid value", { key: input.key });
+        }
+        writeCache(filePath, input.key, value, now());
+        return value;
+    }
+    finally {
+        releaseLock(lockPath, token);
+    }
+}
+function createCacheLock(lockPath, token, nowMs) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const lockFd = fs.openSync(lockPath, "wx", 0o600);
+    try {
+        fs.writeSync(lockFd, `${token}\n${nowMs}\n`);
+    }
+    catch (err) {
+        try {
+            fs.closeSync(lockFd);
+        }
+        catch (closeErr) {
+            process.stderr.write(`lanes snapshot cache: lock close failed: ${errorText(closeErr)}\n`);
+        }
+        releaseLock(lockPath, token);
+        throw err;
+    }
+    fs.closeSync(lockFd);
+}
+function createKeyDigest(key) {
+    // A lane-list query can contain lane ids. Keep raw ids out of cache filenames.
+    return createHash("sha256").update(key).digest("hex");
+}
+function readFreshCache(filePath, key, nowMs, ttlMs, isValue) {
+    let contents;
+    try {
+        contents = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        process.stderr.write(`lanes snapshot cache: read failed: ${errorText(err)}\n`);
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch (err) {
+        process.stderr.write(`lanes snapshot cache: ignoring malformed cache: ${errorText(err)}\n`);
+        return undefined;
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const entry = raw;
+    if (Object.keys(entry).length !== 4 ||
+        entry.schema_version !== CACHE_SCHEMA_VERSION ||
+        entry.key !== key ||
+        !Number.isSafeInteger(entry.cached_at) ||
+        entry.cached_at > nowMs ||
+        nowMs - entry.cached_at >= ttlMs ||
+        !isValue(entry.value))
+        return undefined;
+    return entry.value;
+}
+function writeCache(filePath, key, value, nowMs) {
+    const temporaryPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        const fd = fs.openSync(temporaryPath, "wx", 0o600);
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify({
+                schema_version: CACHE_SCHEMA_VERSION,
+                key,
+                cached_at: nowMs,
+                value,
+            })}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporaryPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch (cleanupErr) {
+            if (cleanupErr.code !== "ENOENT") {
+                process.stderr.write(`lanes snapshot cache: temp cleanup failed: ${errorText(cleanupErr)}\n`);
+            }
+        }
+        // The cache is an optimization; a successful, validated remote result stays usable.
+        process.stderr.write(`lanes snapshot cache: write failed: ${errorText(err)}\n`);
+    }
+}
+function recoverStaleLock(lockPath, staleLockMs, nowMs) {
+    let stat;
+    try {
+        stat = fs.statSync(lockPath);
+    }
+    catch (err) {
+        return err.code === "ENOENT";
+    }
+    if (nowMs - stat.mtimeMs <= staleLockMs)
+        return false;
+    const stalePath = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
+    try {
+        fs.renameSync(lockPath, stalePath);
+        fs.unlinkSync(stalePath);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return true;
+        throw new LanesError("outpost_snapshot_cache_lock_recovery_failed", `Could not recover a stale Outpost snapshot lock: ${errorText(err)}`, { path: lockPath });
+    }
+}
+function releaseLock(lockPath, token) {
+    try {
+        const contents = fs.readFileSync(lockPath, "utf8");
+        if (contents.split("\n", 1)[0] === token)
+            fs.unlinkSync(lockPath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            process.stderr.write(`lanes snapshot cache: lock release failed: ${errorText(err)}\n`);
+        }
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=outpost-snapshot-cache.js.map

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

@@ -22,6 +22,8 @@ export interface StoreDeps {
     unlinkSync: typeof fs.unlinkSync;
     existsSync: typeof fs.existsSync;
     readdirSync: typeof fs.readdirSync;
+    /** Bulk readers may provide a pre-indexed conflict-sidecar lookup. */
+    conflictSidecarPathsFor?: (recordPath: string) => readonly string[];
     openSync: typeof fs.openSync;
     closeSync: typeof fs.closeSync;
     fsyncSync: typeof fs.fsyncSync;
@@ -50,6 +52,8 @@ export declare function mergeLaneRecords(live: LaneRecord, sidecars: readonly La
 export declare function mergeQuestionRecords(live: QuestionRecord, sidecars: readonly QuestionRecord[]): QuestionRecord;
 export declare function tryReadLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord | null;
 export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
+/** Reads every lane while scanning the lane directory for conflict sidecars once. */
+export declare function readAllLanes(hqRoot: string, deps?: StoreDeps): LaneRecord[];
 export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
 export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
 /** Semver precedence includes prerelease identifiers (for example, rc.2 > rc.1). */

package/dist/lib/lanes/store.js

@@ -954,6 +954,9 @@ export function isConflictSidecarName(recordBasename, name) {
     return name.startsWith(`${recordBasename}.conflict-`);
 }
 function sidecarPathsFor(recordPath, deps) {
+    if (deps.conflictSidecarPathsFor) {
+        return [...deps.conflictSidecarPathsFor(recordPath)];
+    }
     const dir = path.dirname(recordPath);
     const base = path.basename(recordPath);
     if (!deps.existsSync(dir))
@@ -1157,6 +1160,42 @@ export function readLane(hqRoot, laneId, deps = defaultStoreDeps()) {
         throw new LaneNotFoundError("lane", laneId);
     return record;
 }
+/** Reads every lane while scanning the lane directory for conflict sidecars once. */
+export function readAllLanes(hqRoot, deps = defaultStoreDeps()) {
+    const laneIds = listLaneIds(hqRoot, deps);
+    if (laneIds.length === 0)
+        return [];
+    const laneDir = path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR);
+    let names;
+    try {
+        names = deps.readdirSync(laneDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            names = [];
+        else
+            throw err;
+    }
+    const sidecarsByRecord = new Map();
+    for (const name of names) {
+        if (typeof name !== "string")
+            continue;
+        const marker = name.indexOf(".json.conflict-");
+        if (marker < 0 || name.startsWith("."))
+            continue;
+        const recordBasename = name.slice(0, marker + ".json".length);
+        if (!isConflictSidecarName(recordBasename, name))
+            continue;
+        const sidecars = sidecarsByRecord.get(recordBasename) ?? [];
+        sidecars.push(path.join(laneDir, name));
+        sidecarsByRecord.set(recordBasename, sidecars);
+    }
+    const indexedDeps = {
+        ...deps,
+        conflictSidecarPathsFor: (recordPath) => sidecarsByRecord.get(path.basename(recordPath)) ?? [],
+    };
+    return laneIds.map((laneId) => readLane(hqRoot, laneId, indexedDeps));
+}
 export function tryReadQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
     const filePath = questionRecordPath(hqRoot, questionId);
     return readMergedRecord(filePath, parseQuestionRecord, mergeQuestionRecords, deps);

package/dist/lib/policy-validator.d.ts

@@ -0,0 +1,2 @@
+export declare function policyValidatorDiagnostic(content: string, filePath: string, env: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=policy-validator.d.ts.map

package/dist/lib/policy-validator.js

@@ -0,0 +1,136 @@
+const VALIDATION_NOTE = '\n(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.\nAn agent must never set, export, or write it on its own initiative.)\n';
+function isPolicyPath(file) {
+    const low = file.toLowerCase().replaceAll('\\', '/');
+    const basename = low.slice(low.lastIndexOf('/') + 1);
+    return low.endsWith('.md')
+        && (low.includes('/policies/') || low.startsWith('policies/'))
+        && basename !== 'readme.md'
+        && !low.includes('/audit/');
+}
+function normalizeValidatorText(content) {
+    return content.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+function hasValidTriggerGrammar(expression) {
+    let input = expression.replace(/[A-Za-z0-9_./][A-Za-z0-9_./-]*/g, '0');
+    if (/[^01&|!() \t]/.test(input))
+        return false;
+    let position = 0;
+    let valid = true;
+    const skip = () => { while (input[position] === ' ' || input[position] === '\t')
+        position += 1; };
+    let parseOr;
+    let parseAnd;
+    let parseNot;
+    let parseAtom;
+    parseAtom = () => {
+        skip();
+        const current = input[position];
+        if (current === '(') {
+            position += 1;
+            const result = parseOr();
+            skip();
+            if (input[position] !== ')') {
+                valid = false;
+                return false;
+            }
+            position += 1;
+            return result;
+        }
+        if (current === '0' || current === '1') {
+            position += 1;
+            return current === '1';
+        }
+        valid = false;
+        return false;
+    };
+    parseNot = () => {
+        skip();
+        if (input[position] === '!') {
+            position += 1;
+            return !parseNot();
+        }
+        return parseAtom();
+    };
+    parseAnd = () => {
+        let result = parseNot();
+        skip();
+        while (valid && input.slice(position, position + 2) === '&&') {
+            position += 2;
+            const rhs = parseNot();
+            result = result && rhs;
+            skip();
+        }
+        return result;
+    };
+    parseOr = () => {
+        let result = parseAnd();
+        skip();
+        while (valid && input.slice(position, position + 2) === '||') {
+            position += 2;
+            const rhs = parseAnd();
+            result = result || rhs;
+            skip();
+        }
+        return result;
+    };
+    input = input.replace(/\r/g, '');
+    if (input.replace(/[ \t]/g, '') === '')
+        return false;
+    parseOr();
+    skip();
+    return valid && position === input.length;
+}
+export function policyValidatorDiagnostic(content, filePath, env) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    const normalized = normalizeValidatorText(content);
+    const match = /^\s*---[ \t]*\n([\s\S]*?)\n---[ \t]*(\n|$)/.exec(normalized);
+    if (!match)
+        return `BLOCKED: policy file is missing required trigger frontmatter (missing: no-frontmatter).\n\nEvery policy under */policies/ must declare BOTH:\n  when: <expression>   # e.g.  always  |  git && push  |  deploy || share\n  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart\nThese drive just-in-time policy injection. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\nAdd both fields to the frontmatter, then retry.\n${VALIDATION_NOTE}`;
+    const frontmatter = match[1];
+    const whenLines = [...frontmatter.matchAll(/^[ \t]*when:[ \t]*(.*)$/gm)].map((entry) => entry[1] ?? '');
+    const hasWhen = whenLines.some((line) => /\S/.test(line));
+    const onMatch = /^[ \t]*on:[ \t]*\S/m.test(frontmatter);
+    const missing = [];
+    if (!hasWhen)
+        missing.push('when');
+    if (!onMatch)
+        missing.push('on');
+    if (missing.length > 0)
+        return `BLOCKED: policy file is missing required trigger frontmatter (missing: ${missing.join(',')}).\n\nEvery policy under */policies/ must declare BOTH:\n  when: <expression>   # e.g.  always  |  git && push  |  deploy || share\n  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart\nThese drive just-in-time policy injection. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\nAdd both fields to the frontmatter, then retry.\n${VALIDATION_NOTE}`;
+    const enforcement = /^[ \t]*enforcement:[ \t]*["']?([A-Za-z]+)["']?/m.exec(frontmatter)?.[1]?.toLowerCase();
+    if (enforcement === 'hard') {
+        const tautological = whenLines.some((line) => !/[&!]/.test(line.toLowerCase()) && /(^|[^A-Za-z0-9_./-])always([^A-Za-z0-9_./-]|$)/i.test(line));
+        const onLine = /^[ \t]*on:[ \t]*(.*)$/m.exec(frontmatter)?.[1] ?? '';
+        const reactive = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'AssistantIntent'].filter((event) => onLine.includes(event));
+        if (tautological && reactive.length > 0) {
+            const events = reactive.join(', ');
+            return `BLOCKED: an enforcement: hard policy pairs an unconditional \`when:\` with a\nreactive event (${events}).\n\n\`when: always\` is TRUE for every command, prompt, and message. On a reactive\nevent the injector ranks that as an event-specific match, so it takes the\nsession cap slot of a policy that genuinely matched the thing you are doing —\nthe loose trigger crowds out the precise one.\n\nPick one:\n  when: always          + on: [SessionStart]        # ambient governance rule\n  when: <real signal>   + on: [PreToolUse, ...]     # e.g. deploy || publish\n\nName the word(s) that actually appear when the rule is relevant. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\n${VALIDATION_NOTE}`;
+        }
+        const after = normalized.slice(match.index + match[0].length);
+        const binding = [];
+        const stop = /^#+[ \t]*(rationale|rationale and context|background|change history|changelog|history|examples?|references?|related|see also|sources?|provenance|evidence)[ \t]*$/i;
+        for (const line of after.split('\n')) {
+            if (stop.test(line.trim().toLowerCase()))
+                break;
+            binding.push(line);
+        }
+        const byteCount = Buffer.byteLength(binding.join('\n').trim(), 'utf8');
+        const rawMax = env.HQ_POLICY_HARD_RULE_MAX_BYTES || '6144';
+        const max = Number.parseInt(rawMax, 10);
+        if (Number.isFinite(max) && max > 0 && byteCount > max) {
+            return `BLOCKED: enforcement: hard policy body is ${byteCount} bytes; the limit is ${rawMax}.\n\nA hard policy is injected VERBATIM into the session, so its length is a\nrecurring context cost for every session it fires in. Keep the binding rule\ntight and move the reasoning out of the injected span: everything from the\nfirst \`## Rationale\` / \`## Background\` / \`## Change history\` /\n\`## Examples\` / \`## References\` heading onward is NOT counted and NOT\ninjected, so long-form context belongs there.\n\nIf the rule genuinely needs more than that, either split it into separate\npolicies with distinct triggers, or raise HQ_POLICY_HARD_RULE_MAX_BYTES in\n.claude/settings.local.json "env".\n${VALIDATION_NOTE}`;
+        }
+    }
+    let malformedWhen;
+    for (const when of whenLines) {
+        if (!hasValidTriggerGrammar(when))
+            malformedWhen = when;
+    }
+    if (malformedWhen !== undefined) {
+        const when = malformedWhen;
+        return `BLOCKED: policy file has a malformed when: trigger expression:\n\n  when: ${when}\n\nThe canonical trigger evaluator rejected it. A space is NOT an AND, and quoted\nphrases are NOT tokens. Use explicit boolean operators instead:\n  "pull request"  -> (pull && request)\n  "force-push"    -> force-push\n\nUse only identifiers joined by the documented boolean grammar:\n  when: <identifier>                 # e.g.  always  |  git  |  /deep-plan\n  when: <expr> && <expr>             # AND\n  when: <expr> || <expr>             # OR\n  when: ! <expr>                     # NOT\n  when: ( <expr> )                   # grouping\nIdentifiers may contain letters, digits, _, ., /, and internal -. Quotes,\nYAML block scalars, adjacent identifiers without an operator, and other\npunctuation are not valid. See core/knowledge/public/hq-core/policies-spec.md\n("Trigger Expressions"). Fix the expression, then retry.\n${VALIDATION_NOTE}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=policy-validator.js.map

package/dist/native-fast-route.d.ts

@@ -1,3 +1,5 @@
 /** Default-off flag check for native entrypoint routes. */
 export declare function nativeFastRouteEnabled(argv: readonly string[], env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export declare function fastFlagEnabled(flagKey: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
 //# sourceMappingURL=native-fast-route.d.ts.map

package/dist/native-fast-route.js

@@ -5,7 +5,11 @@ export async function nativeFastRouteEnabled(argv, env = process.env) {
     const parsed = parseFastCore(argv);
     if (!parsed || parsed.entry.kind !== "native")
         return false;
-    const override = nativeRouteOverride(parsed.entry.flagKey, env);
+    return fastFlagEnabled(parsed.entry.flagKey, env);
+}
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export async function fastFlagEnabled(flagKey, env = process.env) {
+    const override = nativeRouteOverride(flagKey, env);
     if (override !== null)
         return override;
     try {
@@ -16,7 +20,7 @@ export async function nativeFastRouteEnabled(argv, env = process.env) {
         const { companyUid } = resolveProcessFlagCompanyContext(env);
         if (!companyUid)
             return false;
-        return readFlagSnapshotFile(companyUid, { env })?.flags[parsed.entry.flagKey] === true;
+        return readFlagSnapshotFile(companyUid, { env })?.flags[flagKey] === true;
     }
     catch {
         // The new path is a rollout optimization. Any unavailable local scope or

package/dist/utils/contribution-table.d.ts

@@ -99,5 +99,5 @@ export declare const CONTRIBUTION_KEYS: ContributionKey[];
  */
 export declare function payloadFor(key: ContributionKey, item: string): string;
 /** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
-export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "skills" | "knowledge" | "hooks" | "policies" | "scripts")[];
+export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "hooks" | "skills" | "policies" | "knowledge" | "scripts")[];
 //# sourceMappingURL=contribution-table.d.ts.map

package/package.json

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