@indigoai-us/hq-cli 5.297.0 → 5.299.0

package/dist/lib/daemon/run.js

@@ -22,7 +22,7 @@ import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
-import { adoptLegacyUnits } from "./migrate.js";
+import { retireLegacyMeshUnits } from "./migrate.js";
 import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { daemonRootRefusal } from "./install.js";
@@ -72,6 +72,17 @@ export function probeLegacyUnits(platform, home) {
         home,
         existsSync: fs.existsSync,
         listDir: (dir) => fs.readdirSync(dir),
+        launchdJobLoaded: (label) => {
+            if (platform !== "darwin")
+                return false;
+            const uid = process.getuid?.() ?? 0;
+            const result = spawnSync("launchctl", ["print", `gui/${uid}/${label}`], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 15_000,
+            });
+            return result.status === 0;
+        },
         windowsTaskExists,
     });
 }
@@ -344,7 +355,12 @@ export async function runDaemon(opts) {
     if (legacyMesh.length > 0) {
         try {
             const uid = process.getuid?.() ?? 0;
-            const result = adoptLegacyUnits(legacyMesh, {
+            retireLegacyMeshUnits(legacyMesh, {
+                platform,
+                managed: opts.managed === true,
+                hosted: opts.host !== undefined,
+                meshEnabled: enabledServices(machineType, initial).includes("mesh"),
+            }, {
                 run: (command, args) => {
                     const r = spawnSync(command, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
                     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
@@ -356,11 +372,7 @@ export async function runDaemon(opts) {
                 systemAdoptedDir: "/var/lib/hq/daemon/adopted",
                 systemRecordPath: "/var/lib/hq/daemon/adopted.json",
                 systemUnitDir: "/etc/systemd/system",
-            });
-            for (const unit of result.adopted)
-                log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
-            for (const failure of result.failed)
-                log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+            }, (level, message) => log(level, message));
         }
         catch (err) {
             log("error", `could not retire legacy mesh units: ${err.message}`);

package/dist/lib/daemon/supervisor.js

@@ -28,6 +28,7 @@ export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
+const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
@@ -297,11 +298,18 @@ export function createSupervisor(deps) {
             }
             const meshOwnerReason = slot.plan.service === "mesh" ? deps.meshOwnerReason?.() : undefined;
             if (meshOwnerReason) {
+                let lastLoggedReason;
+                let lastLoggedAt = Number.NEGATIVE_INFINITY;
                 const waitForOwner = (reason) => {
                     slot.state.status = "waiting";
                     slot.state.reason = reason;
                     slot.state.nextRunAt = now() + MESH_OWNER_RECHECK_MS;
-                    deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                    const at = now();
+                    if (reason !== lastLoggedReason || at - lastLoggedAt >= MESH_OWNER_LOG_INTERVAL_MS) {
+                        deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                        lastLoggedReason = reason;
+                        lastLoggedAt = at;
+                    }
                     slot.timer = setT(() => {
                         slot.timer = undefined;
                         const current = deps.meshOwnerReason?.();

package/dist/lib/lanes/profile.js

@@ -10,6 +10,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { parseUserYaml } from "../../utils/user-yaml-error.js";
+import { policyLoadDiagnostic } from "../policy-validator.js";
 import { WorkerResolutionError } from "./errors.js";
 import { PROVIDER_EFFORT_LEVELS } from "./effort.js";
 import { LANE_PROVIDERS, isLaneProvider, } from "./types.js";
@@ -261,6 +262,10 @@ function validatePolicyFrontmatter(id, profileDir, relative) {
         frontmatter.on.some((value) => typeof value !== "string" || value.trim().length === 0)) {
         throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} frontmatter must include a non-empty on string array`, { worker: id, file: filePath, field: "on" });
     }
+    const diagnostic = policyLoadDiagnostic(content, filePath);
+    if (diagnostic) {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} failed policy validation: ${diagnostic.split("\n", 1)[0]}`, { worker: id, file: filePath, field: "frontmatter", diagnostic });
+    }
 }
 function readSettings(id, dir) {
     const filePath = path.join(dir, PROFILE_SETTINGS);

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

@@ -89,6 +89,25 @@ export declare function quotaSignalFromFields(fields: {
 }, model: string | undefined, now: Date): QuotaSignal | null;
 export declare function readQuotaSignal(runDir: string, model: string | undefined, now: Date, workerOutOffset?: number): QuotaSignal | null;
 export declare function recordAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, signal: QuotaSignal): QuotaState;
+export interface ClearedModelQuotaReset {
+    model: string;
+    quota_reset_at: string;
+}
+export interface AccountQuotaClearResult {
+    all_models_quota_reset_at: string | null;
+    model_quota_resets: ClearedModelQuotaReset[];
+}
+export interface ClearAccountQuotaOptions {
+    /** Clear only this model's reset instead of every per-model reset. */
+    model?: string;
+    /** Clear only marks whose reset time is still ahead of now. */
+    futureOnly?: boolean;
+    now?: Date;
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export declare function clearAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, options?: ClearAccountQuotaOptions): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurn(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): void;
 export interface QuotaBlock {
     blocked: boolean;
     reason?: "account_quota_exhausted" | "account_model_unavailable";

package/dist/lib/lanes/quota.js

@@ -19,6 +19,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { withLaneRecordFileLock } from "./store.js";
 export const QUOTA_STATE_REL = path.join("personal", "lanes", "quota.json");
 export const QUOTA_SCHEMA_VERSION = "hq-lanes-quota.v1";
 /**
@@ -278,40 +279,116 @@ export function readQuotaSignal(runDir, model, now, workerOutOffset = 0) {
     return quotaSignalFromFields(fields, model, now);
 }
 export function recordAccountQuota(hqRoot, provider, accountId, signal) {
-    const state = loadQuotaState(hqRoot);
-    const accounts = state.providers[provider] ?? {};
-    const current = accounts[accountId] ?? { models: {} };
-    const models = { ...current.models };
-    if (signal.model) {
-        const prior = models[signal.model] ?? {};
-        const next = { ...prior };
-        if (signal.needs_credits) {
-            next.needs_credits = true;
-            next.marker = signal.marker ?? `needs credits for ${signal.model}`;
-            delete next.quota_reset_at;
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const state = loadQuotaState(hqRoot);
+        const accounts = state.providers[provider] ?? {};
+        const current = accounts[accountId] ?? { models: {} };
+        const models = { ...current.models };
+        if (signal.model) {
+            const prior = models[signal.model] ?? {};
+            const next = { ...prior };
+            if (signal.needs_credits) {
+                next.needs_credits = true;
+                next.marker = signal.marker ?? `needs credits for ${signal.model}`;
+                delete next.quota_reset_at;
+            }
+            if (signal.quota_reset_at &&
+                !signal.needs_credits &&
+                shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
+                next.quota_reset_at = signal.quota_reset_at;
+            }
+            models[signal.model] = next;
         }
-        if (signal.quota_reset_at &&
-            !signal.needs_credits &&
-            shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
-            next.quota_reset_at = signal.quota_reset_at;
+        const account = { ...current, models };
+        if (signal.account_wide && signal.quota_reset_at) {
+            if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
+                account.all_models_quota_reset_at = signal.quota_reset_at;
+                account.reset_source = signal.reset_source ?? "provider";
+            }
+            else if (current.all_models_quota_reset_at) {
+                account.all_models_quota_reset_at = current.all_models_quota_reset_at;
+                account.reset_source = current.reset_source ?? "provider";
+            }
         }
-        models[signal.model] = next;
-    }
-    const account = { ...current, models };
-    if (signal.account_wide && signal.quota_reset_at) {
-        if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
-            account.all_models_quota_reset_at = signal.quota_reset_at;
-            account.reset_source = signal.reset_source ?? "provider";
+        accounts[accountId] = account;
+        state.providers[provider] = accounts;
+        writeQuotaState(hqRoot, state);
+        return state;
+    });
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export function clearAccountQuota(hqRoot, provider, accountId, options = {}) {
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const cleared = {
+            all_models_quota_reset_at: null,
+            model_quota_resets: [],
+        };
+        const state = loadQuotaState(hqRoot);
+        const account = state.providers[provider]?.[accountId];
+        if (!account)
+            return cleared;
+        const now = options.now ?? new Date();
+        const shouldClear = (reset) => reset !== undefined &&
+            (!options.futureOnly || resetStillAhead(reset, now));
+        let changed = false;
+        const accountWideReset = account.all_models_quota_reset_at;
+        if (shouldClear(accountWideReset)) {
+            cleared.all_models_quota_reset_at = accountWideReset;
+            delete account.all_models_quota_reset_at;
+            delete account.reset_source;
+            changed = true;
+        }
+        const modelNames = options.model === undefined
+            ? Object.keys(account.models).sort()
+            : [options.model];
+        for (const model of modelNames) {
+            const entry = account.models[model];
+            const modelReset = entry?.quota_reset_at;
+            if (!entry || !shouldClear(modelReset))
+                continue;
+            cleared.model_quota_resets.push({
+                model,
+                quota_reset_at: modelReset,
+            });
+            delete entry.quota_reset_at;
+            if (Object.keys(entry).length === 0)
+                delete account.models[model];
+            changed = true;
         }
-        else if (current.all_models_quota_reset_at) {
-            account.all_models_quota_reset_at = current.all_models_quota_reset_at;
-            account.reset_source = current.reset_source ?? "provider";
+        if (!changed)
+            return cleared;
+        if (account.all_models_quota_reset_at === undefined) {
+            delete account.reset_source;
         }
+        const accounts = state.providers[provider];
+        if (account.all_models_quota_reset_at === undefined &&
+            Object.keys(account.models).length === 0) {
+            delete accounts[accountId];
+            if (Object.keys(accounts).length === 0)
+                delete state.providers[provider];
+        }
+        else {
+            accounts[accountId] = account;
+        }
+        writeQuotaState(hqRoot, state);
+        return cleared;
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now) {
+    return clearAccountQuota(hqRoot, provider, accountId, {
+        model,
+        futureOnly: true,
+        now,
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, provider, accountId, model, now) {
+    try {
+        clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`hq lanes: quota cleanup after successful turn failed for provider=${provider} account=${accountId} model=${model}: ${detail}\n`);
     }
-    accounts[accountId] = account;
-    state.providers[provider] = accounts;
-    writeQuotaState(hqRoot, state);
-    return state;
 }
 function shouldReplaceReset(current, incoming) {
     if (!current)

package/dist/lib/lanes/reconcile.js

@@ -27,7 +27,7 @@ import { appendDropboxMessage } from "./dropbox.js";
 import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
-import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
@@ -1299,6 +1299,17 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     return next;
                 }, deps.dryRun);
+                if (!deps.dryRun &&
+                    result.changed &&
+                    result.record.state === "done" &&
+                    terminalClassification.state === "done" &&
+                    terminalEnvelope?.decision === "done" &&
+                    !quota &&
+                    !providerRejection &&
+                    result.record.account &&
+                    result.record.model) {
+                    clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, result.record.provider, result.record.account, result.record.model, new Date(nowIso));
+                }
                 if (result.changed) {
                     summary.dead_host.push({
                         id: lane.lane_id,

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

@@ -43,6 +43,8 @@ export declare function sanitizeHostComponent(hostname: string): string;
 export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname"> & Partial<Pick<StoreDeps, "generateLaneUlid">>): string;
 export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
 export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export declare function withLaneRecordFileLock<T>(recordPath: string, fn: () => T): T;
 export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
 export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
 /**

package/dist/lib/lanes/store.js

@@ -222,6 +222,10 @@ function withRecordLock(recordPath, deps, fn) {
         }
     }
 }
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export function withLaneRecordFileLock(recordPath, fn) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+}
 function readJsonFile(filePath, deps) {
     let text;
     try {

package/dist/lib/lanes/watcher.js

@@ -40,7 +40,7 @@ import { laneStories, terminalEnvelopeStoryStatus } from "./stories.js";
 import { appendCappedHistory, listQuestionIds, readLane, readQuestion, retryUpdateLane, withLaneHireLocks } from "./store.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
 import { readWorkerRunResult } from "./delivery.js";
-import { applyDefaultQuotaHold, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, quotaSignalFromFields, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { PROVIDER_REJECTED_REASON, QUOTA_STATUS, isProviderLoginFailure, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
 import { appendDropboxMessageAtPath, dropboxInboxHasMessages, readToolActivity, toolActivityPath } from "./dropbox.js";
 import { loadLanesConfig, providerProgressEventMinIntervalMs, providerQuotaDefaultHoldMs } from "./config.js";
@@ -445,6 +445,15 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
         }
         return next;
     });
+    if (updated.state === "done" &&
+        effectiveClassification.state === "done" &&
+        effectiveEnvelope?.decision === "done" &&
+        opts.quota == null &&
+        opts.providerRejection == null &&
+        updated.account &&
+        updated.model) {
+        clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, updated.provider, updated.account, updated.model, new Date(at));
+    }
     notifySlotFreed({
         hqRoot,
         provider: updated.provider,

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -307,6 +307,9 @@ export declare function uninstallDaemonService(opts: {
     unlinkSync?: typeof fs.unlinkSync;
     existsSync?: typeof fs.existsSync;
     deactivate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Service-manager runner for uninstall deactivation (tests inject; never the real binary). */
+    run?: RunCommand;
+    uid?: number;
     /** Windows: schtasks.exe runner (tests inject; never the real binary). */
     schtasks?: SchtasksRunner;
     /** Windows: terminate the recorded daemon pid after `schtasks /End` (tests inject). */

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

@@ -22,7 +22,7 @@ import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqR
 import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
 import { retireLegacyListen } from "./legacy-listen.js";
 import { readDaemonState } from "./state.js";
-import { activateLaunchd, launchdIsLoaded, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
+import { activateLaunchd, defaultRunCommand, launchdIsLoaded, launchdServiceTarget, launchdPlistProgramArguments, launchdProgramArgumentsDiffer, parseLaunchctlPrintArguments, } from "../../../service-manager/launchd.js";
 import { activateSystemd, systemdIsActive } from "../../../service-manager/systemd.js";
 import { nodeBinaryProblem, preferStableNodeBinary } from "../../../node-binary.js";
 /**
@@ -955,7 +955,18 @@ export function uninstallDaemonService(opts) {
     }
     if (platform === "darwin") {
         if (existsSync(paths.plistPath)) {
-            opts.deactivate?.(platform, paths.plistPath);
+            if (opts.deactivate) {
+                opts.deactivate(platform, paths.plistPath);
+            }
+            else {
+                const run = opts.run ?? defaultRunCommand;
+                const target = launchdServiceTarget(paths.plistPath, opts.uid);
+                const bootout = run("launchctl", ["bootout", target]);
+                if (bootout.status !== 0 && run("launchctl", ["print", target]).status === 0) {
+                    const detail = (bootout.stderr || bootout.stdout).trim();
+                    throw new Error(`launchctl bootout failed for ${target}${detail ? `: ${detail}` : ` (exit ${bootout.status})`}`);
+                }
+            }
             unlinkSync(paths.plistPath);
         }
         return {

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

@@ -1,2 +1,7 @@
+/**
+ * Load-time validation: reject policy files that cannot participate in the
+ * trigger system. Authoring-only hard-policy constraints remain in the hook.
+ */
+export declare function policyLoadDiagnostic(content: string, filePath: string): string | undefined;
 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

@@ -80,13 +80,21 @@ function hasValidTriggerGrammar(expression) {
     skip();
     return valid && position === input.length;
 }
-export function policyValidatorDiagnostic(content, filePath, env) {
-    if (!isPolicyPath(filePath))
-        return undefined;
+const MISSING_TRIGGER_HELP = `Every policy under */policies/ must declare BOTH:
+  when: <expression>   # e.g.  always  |  git && push  |  deploy || share
+  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart
+These drive just-in-time policy injection. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+Add both fields to the frontmatter, then retry.
+${VALIDATION_NOTE}`;
+function inspectPolicyTriggerFrontmatter(content) {
     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}`;
+    if (!match) {
+        return {
+            diagnostic: `BLOCKED: policy file is missing required trigger frontmatter (missing: no-frontmatter).\n\n${MISSING_TRIGGER_HELP}`,
+        };
+    }
     const frontmatter = match[1];
     const whenLines = [...frontmatter.matchAll(/^[ \t]*when:[ \t]*(.*)$/gm)].map((entry) => entry[1] ?? '');
     const hasWhen = whenLines.some((line) => /\S/.test(line));
@@ -96,8 +104,46 @@ export function policyValidatorDiagnostic(content, filePath, env) {
         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}`;
+    if (missing.length > 0) {
+        return {
+            diagnostic: `BLOCKED: policy file is missing required trigger frontmatter (missing: ${missing.join(',')}).\n\n${MISSING_TRIGGER_HELP}`,
+            whenLines,
+        };
+    }
+    return { parsed: { normalized, match, frontmatter, whenLines }, whenLines };
+}
+function malformedTriggerDiagnostic(whenLines) {
+    let malformedWhen;
+    for (const when of whenLines) {
+        if (!hasValidTriggerGrammar(when))
+            malformedWhen = when;
+    }
+    if (malformedWhen === undefined)
+        return 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}`;
+}
+/**
+ * Load-time validation: reject policy files that cannot participate in the
+ * trigger system. Authoring-only hard-policy constraints remain in the hook.
+ */
+export function policyLoadDiagnostic(content, filePath) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    // Partial frontmatter (for example `when:` without `on:`) still has its
+    // `when:` grammar checked, so a malformed expression is never loaded.
+    const { whenLines } = inspectPolicyTriggerFrontmatter(content);
+    if (!whenLines)
+        return undefined;
+    return malformedTriggerDiagnostic(whenLines);
+}
+export function policyValidatorDiagnostic(content, filePath, env) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    const inspected = inspectPolicyTriggerFrontmatter(content);
+    if (inspected.diagnostic)
+        return inspected.diagnostic;
+    const { normalized, match, frontmatter, whenLines } = inspected.parsed;
     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));
@@ -105,7 +151,21 @@ export function policyValidatorDiagnostic(content, filePath, env) {
         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}`;
+            return `BLOCKED: an enforcement: hard policy pairs an unconditional \`when:\` with a
+reactive event (${events}).
+
+\`when: always\` is TRUE for every command, prompt, and message. On a reactive
+event the injector ranks that as an event-specific match, so it takes the
+session cap slot of a policy that genuinely matched the thing you are doing —
+the loose trigger crowds out the precise one.
+
+Pick one:
+  when: always          + on: [SessionStart]        # ambient governance rule
+  when: <real signal>   + on: [PreToolUse, ...]     # e.g. deploy || publish
+
+Name the word(s) that actually appear when the rule is relevant. See
+core/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").
+${VALIDATION_NOTE}`;
         }
         const after = normalized.slice(match.index + match[0].length);
         const binding = [];
@@ -122,15 +182,6 @@ export function policyValidatorDiagnostic(content, filePath, env) {
             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;
+    return malformedTriggerDiagnostic(whenLines);
 }
 //# sourceMappingURL=policy-validator.js.map