@indigoai-us/hq-cli 5.281.0 → 5.283.0

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

@@ -12,7 +12,8 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import type { ThrottleConfig } from "./types.js";
-export declare const CPU_SAMPLE_MS = 200;
+export declare const CPU_SAMPLE_MS = 5000;
+export declare const CPU_CUMULATIVE_MAX_AGE_MS: number;
 export declare const STARVATION_MAX_DEFERRALS = 10;
 export declare const STARVATION_MAX_MS: number;
 export declare const PROC_MEMINFO = "/proc/meminfo";
@@ -39,12 +40,34 @@ export interface ThrottleDeps {
     renameSync: typeof fs.renameSync;
     unlinkSync: typeof fs.unlinkSync;
 }
+export type CpuBusySource = "interval" | "window" | "override";
+export interface CpuCumulativeSnapshot {
+    idle: number;
+    total: number;
+    sampled_at: string;
+}
+export interface CpuBusyObservation {
+    busy: number | null;
+    source: CpuBusySource | undefined;
+    snapshot: CpuCumulativeSnapshot | undefined;
+}
 export declare function defaultThrottleDeps(env?: NodeJS.ProcessEnv): ThrottleDeps;
 export declare function cpuTimesSnapshot(cpus: os.CpuInfo[]): CpuTimes;
 export declare function busyFractionFromDeltas(before: CpuTimes, after: CpuTimes): number | null;
 export declare function sampleCpuBusyFraction(deps?: ThrottleDeps, sampleMs?: number): Promise<number | null>;
 export declare function isCpuCheckEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function resolveCpuBusyFraction(deps?: ThrottleDeps): Promise<number | null>;
+/**
+ * Measure CPU busy against the previous reconcile snapshot when it is fresh.
+ * A short stable window is used only to establish a baseline or recover from
+ * stale/backwards counters (for example, after a reboot).
+ */
+export declare function sampleCpuBusyObservation(deps: ThrottleDeps, previous: CpuCumulativeSnapshot | undefined, options?: {
+    measureBusy?: boolean;
+}): Promise<CpuBusyObservation>;
+export declare function recordCpuBusyObservation(state: ThrottleState, observation: CpuBusyObservation, options?: {
+    advanceSnapshot?: boolean;
+}): ThrottleState;
 /** Parse MemAvailable kB from /proc/meminfo. */
 export declare function parseMemAvailableKb(contents: string): number | null;
 /**
@@ -56,6 +79,10 @@ export interface ThrottleState {
     consecutiveDeferrals: number;
     lastAdmissionAt: string | null;
     cpuPaused: boolean;
+    cpu_snapshot?: CpuCumulativeSnapshot;
+    last_busy?: number | null;
+    busy_source?: CpuBusySource;
+    sampled_at?: string;
 }
 export type ThrottleAdmitReason = "ok" | "starvation_bound" | "unreadable" | "cpu_check_disabled";
 export type ThrottleDeferReason = "cpu" | "memory";
@@ -82,7 +109,7 @@ export declare function applyThrottleDecision(state: ThrottleState, decision: Th
 export declare function throttleStatePath(hqRoot: string): string;
 export declare function readThrottleState(filePath: string, deps?: ThrottleDeps): ThrottleState | "unreadable" | "missing";
 export declare function writeThrottleState(filePath: string, state: ThrottleState, deps?: ThrottleDeps): void;
-export declare function decideAdmission(hqRoot: string, throttle?: ThrottleConfig, deps?: ThrottleDeps): Promise<{
+export declare function decideAdmission(hqRoot: string, throttle?: ThrottleConfig, deps?: ThrottleDeps, cpuBusyFraction?: number | null, cpuObservation?: CpuBusyObservation): Promise<{
     decision: ThrottleDecision;
     state: ThrottleState;
 }>;

package/dist/lib/lanes/throttle.js

@@ -13,7 +13,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_MIN_AVAILABLE_MEM_MB, } from "./config.js";
-export const CPU_SAMPLE_MS = 200;
+// Reconcile normally measures the interval between cumulative CPU snapshots.
+// A five-second window establishes a baseline or recovers from stale counters.
+export const CPU_SAMPLE_MS = 5_000;
+export const CPU_CUMULATIVE_MAX_AGE_MS = 5 * 60 * 1000;
 export const STARVATION_MAX_DEFERRALS = 10;
 export const STARVATION_MAX_MS = 30 * 60 * 1000;
 export const PROC_MEMINFO = "/proc/meminfo";
@@ -83,6 +86,93 @@ export async function resolveCpuBusyFraction(deps = defaultThrottleDeps()) {
     }
     return sampleCpuBusyFraction(deps);
 }
+function snapshotFromDeps(deps) {
+    return {
+        ...cpuTimesSnapshot(deps.cpus()),
+        sampled_at: new Date(deps.now()).toISOString(),
+    };
+}
+/**
+ * Measure CPU busy against the previous reconcile snapshot when it is fresh.
+ * A short stable window is used only to establish a baseline or recover from
+ * stale/backwards counters (for example, after a reboot).
+ */
+export async function sampleCpuBusyObservation(deps, previous, options = {}) {
+    let start;
+    try {
+        start = snapshotFromDeps(deps);
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: CPU counters failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { busy: null, source: undefined, snapshot: previous };
+    }
+    if (options.measureBusy === false || !isCpuCheckEnabled(deps.env)) {
+        return { busy: null, source: undefined, snapshot: start };
+    }
+    const rawOverride = deps.env[LANES_CPU_BUSY_OVERRIDE];
+    if (rawOverride !== undefined && rawOverride !== "") {
+        const override = Number(rawOverride);
+        if (Number.isFinite(override)) {
+            return {
+                busy: Math.max(0, Math.min(1, override)),
+                source: "override",
+                snapshot: start,
+            };
+        }
+        process.stderr.write(`lanes throttle: ${LANES_CPU_BUSY_OVERRIDE} is not a finite number (${JSON.stringify(rawOverride)}); sampling instead\n`);
+    }
+    const nowMs = Date.parse(start.sampled_at);
+    const previousAtMs = previous ? Date.parse(previous.sampled_at) : Number.NaN;
+    if (previous !== undefined &&
+        Number.isFinite(previousAtMs) &&
+        nowMs >= previousAtMs &&
+        nowMs - previousAtMs <= CPU_CUMULATIVE_MAX_AGE_MS &&
+        start.idle >= previous.idle &&
+        start.total >= previous.total) {
+        return {
+            busy: busyFractionFromDeltas(previous, start),
+            source: "interval",
+            snapshot: start,
+        };
+    }
+    try {
+        await deps.sleep(CPU_SAMPLE_MS);
+        const end = snapshotFromDeps(deps);
+        return {
+            busy: busyFractionFromDeltas(start, end),
+            source: "window",
+            snapshot: end,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: CPU window sample failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { busy: null, source: "window", snapshot: start };
+    }
+}
+export function recordCpuBusyObservation(state, observation, options = {}) {
+    const observationAt = observation.snapshot === undefined
+        ? Number.NaN
+        : Date.parse(observation.snapshot.sampled_at);
+    const currentSnapshotAt = state.cpu_snapshot === undefined
+        ? Number.NaN
+        : Date.parse(state.cpu_snapshot.sampled_at);
+    const snapshotIsCurrent = options.advanceSnapshot !== false && observation.snapshot !== undefined && (!Number.isFinite(currentSnapshotAt) ||
+        observationAt > currentSnapshotAt ||
+        (observationAt === currentSnapshotAt && observation.snapshot.total >= (state.cpu_snapshot?.total ?? 0)));
+    const currentMetricAt = state.sampled_at === undefined ? Number.NaN : Date.parse(state.sampled_at);
+    const metricIsCurrent = observation.source !== undefined && Number.isFinite(observationAt) && (!Number.isFinite(currentMetricAt) || observationAt >= currentMetricAt);
+    return {
+        ...state,
+        ...(snapshotIsCurrent ? { cpu_snapshot: observation.snapshot } : {}),
+        ...(metricIsCurrent
+            ? {
+                last_busy: observation.busy,
+                busy_source: observation.source,
+                sampled_at: observation.snapshot.sampled_at,
+            }
+            : {}),
+    };
+}
 /** Parse MemAvailable kB from /proc/meminfo. */
 export function parseMemAvailableKb(contents) {
     for (const line of contents.split("\n")) {
@@ -184,12 +274,14 @@ export function evaluateThrottle(input) {
 export function applyThrottleDecision(state, decision, nowMs) {
     if (decision.admit) {
         return {
+            ...state,
             consecutiveDeferrals: 0,
             lastAdmissionAt: new Date(nowMs).toISOString(),
             cpuPaused: false,
         };
     }
     return {
+        ...state,
         consecutiveDeferrals: state.consecutiveDeferrals + 1,
         lastAdmissionAt: state.lastAdmissionAt,
         cpuPaused: decision.reason === "cpu" ? true : state.cpuPaused,
@@ -231,10 +323,47 @@ export function readThrottleState(filePath, deps = defaultThrottleDeps()) {
             process.stderr.write(`lanes throttle: state ${filePath} has invalid cpuPaused\n`);
             return "unreadable";
         }
+        const optionalTimestamp = (value) => typeof value === "string" && value.trim() !== "" && Number.isFinite(Date.parse(value));
+        let cpuSnapshot;
+        if (obj.cpu_snapshot !== undefined) {
+            const rawSnapshot = obj.cpu_snapshot;
+            if (rawSnapshot === null || typeof rawSnapshot !== "object" || Array.isArray(rawSnapshot)) {
+                process.stderr.write(`lanes throttle: state ${filePath} has invalid cpu_snapshot\n`);
+                return "unreadable";
+            }
+            const snapshot = rawSnapshot;
+            if (typeof snapshot.idle !== "number" || !Number.isFinite(snapshot.idle) || snapshot.idle < 0 ||
+                typeof snapshot.total !== "number" || !Number.isFinite(snapshot.total) || snapshot.total < 0 ||
+                !optionalTimestamp(snapshot.sampled_at)) {
+                process.stderr.write(`lanes throttle: state ${filePath} has invalid cpu_snapshot fields\n`);
+                return "unreadable";
+            }
+            cpuSnapshot = {
+                idle: snapshot.idle,
+                total: snapshot.total,
+                sampled_at: snapshot.sampled_at,
+            };
+        }
+        if (obj.last_busy !== undefined && obj.last_busy !== null && (typeof obj.last_busy !== "number" || !Number.isFinite(obj.last_busy) || obj.last_busy < 0 || obj.last_busy > 1)) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid last_busy\n`);
+            return "unreadable";
+        }
+        if (obj.busy_source !== undefined && !["interval", "window", "override"].includes(String(obj.busy_source))) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid busy_source\n`);
+            return "unreadable";
+        }
+        if (obj.sampled_at !== undefined && !optionalTimestamp(obj.sampled_at)) {
+            process.stderr.write(`lanes throttle: state ${filePath} has invalid sampled_at\n`);
+            return "unreadable";
+        }
         return {
             consecutiveDeferrals: obj.consecutiveDeferrals,
             lastAdmissionAt: obj.lastAdmissionAt,
             cpuPaused: obj.cpuPaused,
+            ...(cpuSnapshot !== undefined ? { cpu_snapshot: cpuSnapshot } : {}),
+            ...(obj.last_busy !== undefined ? { last_busy: obj.last_busy } : {}),
+            ...(obj.busy_source !== undefined ? { busy_source: obj.busy_source } : {}),
+            ...(obj.sampled_at !== undefined ? { sampled_at: obj.sampled_at } : {}),
         };
     }
     catch (err) {
@@ -269,7 +398,7 @@ export async function decideAdmission(hqRoot, throttle = {
     cpu_busy_pause: DEFAULT_CPU_BUSY_PAUSE,
     cpu_busy_resume: DEFAULT_CPU_BUSY_RESUME,
     min_available_mem_mb: DEFAULT_MIN_AVAILABLE_MEM_MB,
-}, deps = defaultThrottleDeps()) {
+}, deps = defaultThrottleDeps(), cpuBusyFraction, cpuObservation) {
     const filePath = throttleStatePath(hqRoot);
     const loaded = readThrottleState(filePath, deps);
     if (loaded === "unreadable") {
@@ -279,18 +408,29 @@ export async function decideAdmission(hqRoot, throttle = {
         };
     }
     const state = loaded === "missing" ? emptyThrottleState() : loaded;
-    const busy = await resolveCpuBusyFraction(deps);
+    const cpuCheckEnabled = isCpuCheckEnabled(deps.env);
+    const observation = cpuObservation ?? (cpuBusyFraction === undefined && cpuCheckEnabled
+        ? await sampleCpuBusyObservation(deps, state.cpu_snapshot)
+        : undefined);
+    const busy = cpuBusyFraction === undefined
+        ? observation?.busy ?? null
+        : cpuBusyFraction;
     const availableMemMb = readAvailableMemMb(deps);
     const nowMs = deps.now();
     const decision = evaluateThrottle({
         busy,
         availableMemMb,
-        cpuCheckEnabled: isCpuCheckEnabled(deps.env),
+        cpuCheckEnabled,
         state,
         throttle,
         nowMs,
     });
-    const next = applyThrottleDecision(state, decision, nowMs);
+    const observedState = observation
+        ? recordCpuBusyObservation(state, observation, {
+            advanceSnapshot: cpuObservation !== undefined,
+        })
+        : state;
+    const next = applyThrottleDecision(observedState, decision, nowMs);
     writeThrottleState(filePath, next, deps);
     return { decision, state: next };
 }

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

@@ -173,8 +173,14 @@ export declare const TERMINAL_LANE_STATES: readonly ["done", "failed", "interrup
 export type TerminalLaneState = (typeof TERMINAL_LANE_STATES)[number];
 export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
-export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry"];
+export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "worker_profile_changed"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
+export interface QueuedDetails {
+    reason: "worker_profile_changed";
+    expected_hash: string | null;
+    actual_hash: string;
+    recovery_command: string;
+}
 export declare function isQueuedReason(value: unknown): value is QueuedReason;
 export declare const HOST_KINDS: readonly ["local", "outpost"];
 export type HostKind = (typeof HOST_KINDS)[number];
@@ -442,6 +448,7 @@ export interface LaneRecord {
     senior_history: SeniorHistoryEntry[];
     state: LaneState;
     queued_reason?: QueuedReason;
+    queued_details?: QueuedDetails;
     /** Time the current queue turn began; old records fall back to created_at. */
     queued_at?: string;
     /** Short-lived slot reservation between create persistence and worker spawn. */

package/dist/lib/lanes/types.js

@@ -107,6 +107,7 @@ export const QUEUED_REASONS = [
     "throttle",
     "provider_binary_missing",
     "account_retry",
+    "worker_profile_changed",
 ];
 export function isQueuedReason(value) {
     return typeof value === "string" && QUEUED_REASONS.includes(value);
@@ -220,7 +221,7 @@ export const LANE_FIELD_WRITERS = {
     project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
     depth: ["command"], senior: ["command"], senior_history: ["command"],
     hire_grant: ["creator", "command"],
-    state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
+    state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_details: ["command", "reconcile", "spawn", "watcher"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],

package/dist/lib/lanes/watcher.js

@@ -380,6 +380,7 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
             ...runResultFields(hqRoot, current, at),
             state: effectiveClassification.state,
             queued_reason: undefined,
+            queued_details: undefined,
             stalled: undefined,
             stalled_at: undefined,
             stalled_reason: undefined,

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.281.0",
+  "version": "5.283.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {