@indigoai-us/hq-cli 5.158.0 → 5.160.0

package/dist/lib/core-utils/sentry-report.js

@@ -45,11 +45,26 @@ const HOOK_TIMEOUT_WARNING_METRIC = "hq.hook_timeout_warning";
 const HOOK_TIMEOUT_EXCEEDED_METRIC = "hq.hook_timeout_exceeded";
 const HOOK_TIMEOUT_EXCEEDED_FINGERPRINT = "hook-timeout-exceeded";
 const HOOK_TIMEOUT_WARNING_FINGERPRINT = "hook-timeout";
+const HOOK_TIMEOUT_MACHINE_WIDE_FINGERPRINT = "hq-hook-slow";
 const MAX_HOOK_SEQUENCE_ENTRIES = 20;
 const HOOK_TIMEOUT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1_000;
 const RATE_LIMIT_LOCK_WAIT_MS = 500;
 const RATE_LIMIT_LOCK_POLL_MS = 5;
 const RATE_LIMIT_LOCK_STALE_MS = 5_000;
+const KNOWN_HOOK_SCRIPTS = new Set([
+    "master-hook.sh",
+    "hook-gate.sh",
+    "hook-timeout-watchdog.sh",
+    "check-hq-update.sh",
+    "block-core-writes-bash.sh",
+    "block-core-writes.sh",
+    "block-hq-worktree-session.sh",
+    "inject-policy-on-trigger.sh",
+    "inject-local-context.sh",
+    "session-title.sh",
+    "45-lanes-senior-monitor.sh",
+    "lanes-senior-monitor-stop-gate.sh",
+]);
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -71,6 +86,9 @@ export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
     "hq_version",
     "platform",
     "load_average",
+    "spawn_ms",
+    "slow_child",
+    "slow_child_ms",
     "exit_code",
     "final_elapsed_ms",
     "bash_env_set",
@@ -223,6 +241,9 @@ export function parseSentryReportEvent(stdin) {
                 ? boundedHookSequence(rawMetadata[key])
                 : rawMetadata[key];
     }
+    if (typeof metadata.slow_child === "string") {
+        metadata.slow_child = safeSlowChild(metadata);
+    }
     return {
         code: 0,
         event: {
@@ -311,6 +332,63 @@ function loadBucket(loadAverage) {
         return "10-20";
     return ">=20";
 }
+function parsedLoadAverage(metadata) {
+    const value = metadata.load_average;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    if (value === "unavailable")
+        return "unavailable";
+    const match = /^\s*\{?\s*([0-9]+(?:\.[0-9]+)?)/.exec(value);
+    if (!match)
+        return undefined;
+    const parsed = Number(match[1]);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function operatingSystemName(metadata) {
+    const platform = stringMetadata(metadata, "platform", "").toLowerCase();
+    if (/windows|win32|mingw|msys|cygwin/.test(platform))
+        return "windows";
+    if (/darwin|macos|mac os/.test(platform))
+        return "macos";
+    if (/linux/.test(platform))
+        return "linux";
+    return "other";
+}
+function spawnMsBucket(metadata) {
+    const value = metadata.spawn_ms;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return "unavailable";
+    if (value < 100)
+        return "<100ms";
+    if (value < 500)
+        return "100-499ms";
+    if (value < 1_000)
+        return "500-999ms";
+    return ">=1000ms";
+}
+function safeSlowChild(metadata) {
+    const value = metadata.slow_child;
+    if (typeof value !== "string" || value.length === 0)
+        return "other";
+    const script = basenameFromPath(value);
+    return KNOWN_HOOK_SCRIPTS.has(script) ? script : "other";
+}
+function isMachineWideHookSlowness(metadata) {
+    const spawnMs = metadata.spawn_ms;
+    if (typeof spawnMs === "number" && Number.isFinite(spawnMs) && spawnMs >= 500)
+        return true;
+    if (!Array.isArray(metadata.hook_sequence))
+        return false;
+    const slowScripts = new Set();
+    for (const entry of metadata.hook_sequence) {
+        if (entry.ms < 20_000 || !SAFE_HOOK_SCRIPT.test(entry.script))
+            continue;
+        slowScripts.add(entry.script);
+    }
+    return slowScripts.size >= 3;
+}
 function bashEnvTag(metadata) {
     const value = metadata.bash_env_set;
     if (value === true || value === "set")
@@ -330,7 +408,8 @@ function hookTimeoutTags(event) {
         : undefined;
     const shell = stringMetadata(metadata, "shell");
     const nproc = metadata.nproc;
-    const loadAverage = metadata.load_average;
+    const loadAverage = parsedLoadAverage(metadata);
+    const slowChildMs = metadata.slow_child_ms;
     return {
         hook_event: hookEvent(metadata),
         hook_script: hookScript(metadata),
@@ -346,7 +425,14 @@ function hookTimeoutTags(event) {
         shell: safeTagValue(shell),
         bash_env: bashEnvTag(metadata),
         cwd_kind: safeMetadataTag(metadata, "cwd_kind"),
-        load_bucket: typeof loadAverage === "number" ? loadBucket(loadAverage) : "unknown",
+        os_name: operatingSystemName(metadata),
+        load_bucket: loadAverage === "unavailable" ? "unavailable" : loadBucket(loadAverage),
+        spawn_ms_bucket: spawnMsBucket(metadata),
+        slow_child: safeSlowChild(metadata),
+        slow_child_ms_bucket: typeof slowChildMs === "number" && Number.isFinite(slowChildMs)
+            ? elapsedBucket(slowChildMs)
+            : "unknown",
+        machine_wide: isMachineWideHookSlowness(metadata) ? "true" : "false",
         nproc: typeof nproc === "number" || typeof nproc === "string"
             ? safeTagValue(String(nproc), SAFE_NPROC)
             : "unknown",
@@ -393,7 +479,20 @@ function hookTimeoutExceededOverrides(event) {
     const eventName = hookEvent(event.metadata);
     if (!isHookTimeoutEvent(event))
         return undefined;
-    if (hookTimeoutKind(event) === "warning") {
+    const kind = hookTimeoutKind(event);
+    if (isMachineWideHookSlowness(event.metadata)) {
+        return {
+            level: "warning",
+            fingerprint: [
+                HOOK_TIMEOUT_MACHINE_WIDE_FINGERPRINT,
+                "machine-wide",
+                operatingSystemName(event.metadata),
+                eventName,
+                kind,
+            ],
+        };
+    }
+    if (kind === "warning") {
         return {
             level: "warning",
             fingerprint: [HOOK_TIMEOUT_WARNING_FINGERPRINT, eventName, hookScript(event.metadata)],
@@ -536,7 +635,11 @@ function pruneExpiredRateLimitState(directory, now, protectedStatePath) {
 }
 function timeoutRateLimitLease(event, kind, options, dependencies) {
     const sessionId = stringMetadata(event.metadata, "session_id");
-    const key = `${sessionId}\0${hookEvent(event.metadata)}\0${hookScript(event.metadata)}\0${kind}`;
+    const machineWide = isMachineWideHookSlowness(event.metadata);
+    const classification = machineWide
+        ? `machine-wide\0${operatingSystemName(event.metadata)}`
+        : `per-script\0${hookScript(event.metadata)}`;
+    const key = `${sessionId}\0${hookEvent(event.metadata)}\0${kind}\0${classification}`;
     const directory = rateLimitDirectory(options, dependencies);
     const statePath = rateLimitStatePath(directory, key);
     const releaseLock = acquireRateLimitLock(directory);

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

@@ -34,6 +34,6 @@ export declare class AccountResolutionError extends LanesError {
     constructor(error: "unknown_account" | "account_disabled" | "no_enabled_account" | "account_model_unavailable" | "account_quota_exhausted", message: string, details?: Record<string, unknown>);
 }
 export declare class WorkerResolutionError extends LanesError {
-    constructor(error: "worker_not_found" | "worker_tenancy_unresolved" | "worker_not_available" | "worker_not_active" | "worker_id_conflict" | "worker_profile_invalid" | "worker_profile_ambiguous" | "package_workers_unmounted" | "worker_registry_unreadable", message: string, details?: Record<string, unknown>);
+    constructor(error: "worker_not_found" | "worker_tenancy_unresolved" | "worker_not_available" | "worker_not_active" | "worker_id_conflict" | "worker_profile_invalid" | "worker_policy_invalid" | "worker_profile_ambiguous" | "package_workers_unmounted" | "worker_registry_unreadable", message: string, details?: Record<string, unknown>);
 }
 //# sourceMappingURL=errors.d.ts.map

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

@@ -10,10 +10,10 @@ import { type LaneProvider } from "./types.js";
 export interface WorkerProfileMeta {
     version?: string;
     provider: LaneProvider;
-    model: string;
-    account: string;
-    effort: string;
-    fast_mode: boolean;
+    model?: string;
+    account?: string;
+    effort?: string;
+    fast_mode?: boolean;
     max_concurrent?: number;
     source?: string;
     accounts?: string[];
@@ -36,7 +36,7 @@ export declare function personalWorkerProfileDir(hqRoot: string, id: string): st
 /** A meta.yaml file is the explicit marker for a personal worker profile. */
 export declare function workerProfileMarker(hqRoot: string, id: string): "absent" | "present";
 export declare function loadWorkerProfile(hqRoot: string, id: string): WorkerProfile;
-export declare function workerProfilePrompt(profile: WorkerProfile): string;
+export declare function workerProfilePrompt(profile: WorkerProfile, delivery?: "hook" | "prompt"): string;
 export declare function ignoredWorkerProfileFields(provider: LaneProvider): string[];
 /**
  * Materialize provider settings and hook files in the lane run directory.

package/dist/lib/lanes/profile.js

@@ -135,20 +135,22 @@ function parseMeta(id, dir, raw) {
         });
     }
     const providerValue = provider.trim();
-    const requiredString = (field) => {
+    const optionalString = (field) => {
         const value = raw[field];
+        if (value === undefined)
+            return undefined;
         if (typeof value !== "string" || value.trim().length === 0) {
-            throw profileError(id, dir, `meta.yaml ${field} must be a non-empty string`, {
+            throw profileError(id, dir, `meta.yaml ${field} must be a non-empty string when present`, {
                 field,
                 value,
             });
         }
         return value.trim();
     };
-    const model = requiredString("model");
-    const account = requiredString("account");
-    const effort = requiredString("effort");
-    if (!PROVIDER_EFFORT_LEVELS[providerValue].includes(effort)) {
+    const model = optionalString("model");
+    const account = optionalString("account");
+    const effort = optionalString("effort");
+    if (effort !== undefined && !PROVIDER_EFFORT_LEVELS[providerValue].includes(effort)) {
         throw profileError(id, dir, `meta.yaml effort ${JSON.stringify(effort)} is invalid for ${providerValue}`, {
             field: "effort",
             provider: providerValue,
@@ -156,8 +158,8 @@ function parseMeta(id, dir, raw) {
             accepted: [...PROVIDER_EFFORT_LEVELS[providerValue]],
         });
     }
-    if (typeof raw.fast_mode !== "boolean") {
-        throw profileError(id, dir, "meta.yaml fast_mode must be a boolean", {
+    if (raw.fast_mode !== undefined && typeof raw.fast_mode !== "boolean") {
+        throw profileError(id, dir, "meta.yaml fast_mode must be a boolean when present", {
             field: "fast_mode",
             value: raw.fast_mode,
         });
@@ -205,15 +207,45 @@ function parseMeta(id, dir, raw) {
     return {
         ...(version !== undefined ? { version } : {}),
         provider: providerValue,
-        model,
-        account,
-        effort,
-        fast_mode: raw.fast_mode,
+        ...(model !== undefined ? { model } : {}),
+        ...(account !== undefined ? { account } : {}),
+        ...(effort !== undefined ? { effort } : {}),
+        ...(raw.fast_mode !== undefined ? { fast_mode: raw.fast_mode } : {}),
         ...(maxConcurrent !== undefined ? { max_concurrent: maxConcurrent } : {}),
         ...(source !== undefined ? { source } : {}),
         ...(accounts !== undefined ? { accounts } : {}),
     };
 }
+function validatePolicyFrontmatter(id, profileDir, relative) {
+    const filePath = path.join(profileDir, relative);
+    const content = readRequiredText(id, profileDir, filePath, relative);
+    const lines = content.split(/\r?\n/);
+    if (lines[0] !== "---") {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} must start with YAML frontmatter`, { worker: id, file: filePath, field: "frontmatter" });
+    }
+    const closing = lines.findIndex((line, index) => index > 0 && line === "---");
+    if (closing < 0 || closing === 1) {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} must contain a non-empty YAML frontmatter block`, { worker: id, file: filePath, field: "frontmatter" });
+    }
+    let frontmatter;
+    try {
+        frontmatter = parseUserYaml(lines.slice(1, closing).join("\n"), filePath);
+    }
+    catch (err) {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} has invalid YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`, { worker: id, file: filePath, field: "frontmatter" });
+    }
+    if (!isPlainObject(frontmatter)) {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} frontmatter must contain a YAML object`, { worker: id, file: filePath, field: "frontmatter" });
+    }
+    if (typeof frontmatter.when !== "string" || frontmatter.when.trim().length === 0) {
+        throw new WorkerResolutionError("worker_policy_invalid", `Worker policy ${filePath} frontmatter must include a non-empty when field`, { worker: id, file: filePath, field: "when" });
+    }
+    if (!Array.isArray(frontmatter.on) ||
+        frontmatter.on.length === 0 ||
+        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" });
+    }
+}
 function readSettings(id, dir) {
     const filePath = path.join(dir, PROFILE_SETTINGS);
     const stat = lstatOrAbsent(filePath);
@@ -308,6 +340,9 @@ export function loadWorkerProfile(hqRoot, id) {
     }
     const settingsResult = readSettings(id, dir);
     const policyFiles = collectFiles(id, dir, PROFILE_POLICIES);
+    for (const relative of policyFiles.filter((file) => file.toLowerCase().endsWith(".md"))) {
+        validatePolicyFrontmatter(id, dir, relative);
+    }
     const hookFiles = collectFiles(id, dir, PROFILE_HOOKS);
     const hashFiles = [
         PROFILE_META,
@@ -327,8 +362,10 @@ export function loadWorkerProfile(hqRoot, id) {
         contentHash: hashProfileFiles(dir, hashFiles),
     };
 }
-export function workerProfilePrompt(profile) {
+export function workerProfilePrompt(profile, delivery = "prompt") {
     const parts = [profile.systemPrompt.trimEnd()];
+    if (delivery === "hook")
+        return parts.join("\n");
     for (const relative of profile.policyFiles) {
         const content = readRequiredText(profile.id, profile.dir, path.join(profile.dir, relative), relative);
         parts.push(`\n## Profile policy: ${relative}\n${content.trimEnd()}`);

package/dist/lib/lanes/reconcile.js

@@ -15,12 +15,12 @@ import { MAX_LANE_DEPTH } from "./constants.js";
 import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./errors.js";
 import { loadWorkerProfile } from "./profile.js";
 import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, } from "./liveness.js";
-import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
+import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
 import { answeredQuestionEntries, raiseEnvelopeQuestions } from "./questions.js";
-import { SILENCE_MS, classifyLaneExit, isPidAlive, readLatestEnvelope, readLatestEnvelopeFile, readLatestEnvelopeRecord, } from "./watcher.js";
+import { SILENCE_MS, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { decideEnvelopeRepair, envelopeQuestionIds, routeProviderFailure } from "./watcher.js";
@@ -570,9 +570,11 @@ async function withReconcileLock(hqRoot, fn) {
     }
 }
 function classifyDeadLocalLane(hqRoot, laneId) {
-    const latest = readLatestEnvelopeRecord(hqRoot, laneId);
-    const envelope = latest?.envelope ?? readLatestEnvelope(hqRoot, laneId);
     const runDir = laneRunDir(hqRoot, laneId);
+    const manifest = readSpawnManifest(runDir);
+    const minEnvelopeName = manifest.envelope_path ? path.basename(manifest.envelope_path) : undefined;
+    const latest = readLatestEnvelopeRecord(hqRoot, laneId, minEnvelopeName);
+    const envelope = latest?.envelope ?? null;
     const hasPartialOutput = [
         path.join(runDir, "logs", "worker.out"),
         path.join(runDir, "logs", "worker.err"),
@@ -896,22 +898,31 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                 // Match the watcher's one-repair decision before classifying an
                 // unparseable envelope after both processes have died. As in the
                 // watcher, a provider rejection or a quota signal skips the repair.
-                const rawLatest = readLatestEnvelopeFile(hqRoot, lane.lane_id);
+                const runDir = laneRunDir(hqRoot, lane.lane_id);
+                const manifest = readSpawnManifest(runDir);
+                const minEnvelopeName = manifest.envelope_path ? path.basename(manifest.envelope_path) : undefined;
+                const rawLatest = readLatestEnvelopeFile(hqRoot, lane.lane_id, minEnvelopeName);
+                const missingExpected = rawLatest === null
+                    ? missingExpectedEnvelopeFile(hqRoot, lane.lane_id, manifest.envelope_path)
+                    : null;
+                const repairCandidate = rawLatest ?? missingExpected;
                 let invalidEnvelope = null;
                 if (!deps.dryRun &&
                     !providerRejection &&
                     !quota &&
-                    rawLatest &&
-                    rawLatest.envelope === null) {
+                    repairCandidate &&
+                    repairCandidate.envelope === null &&
+                    (!repairCandidate.missing || envelopeRepairMode(classified.provider) === "resume")) {
                     const spawnRepair = deps.spawnRepair ??
                         ((root, repairLane, input) => spawnEnvelopeRepair(root, repairLane, input, deps.spawnLaneDeps));
-                    const repair = decideEnvelopeRepair(hqRoot, lane.lane_id, rawLatest, nowMs, spawnRepair, () => undefined);
+                    const repair = decideEnvelopeRepair(hqRoot, lane.lane_id, repairCandidate, nowMs, spawnRepair, () => undefined);
                     if (repair.action === "spawned") {
                         armLaneWatcher(hqRoot, lane.lane_id, deps.spawnLaneDeps);
                         summary.heartbeats.push(`${lane.lane_id}:envelope-repair`);
                         continue;
                     }
-                    invalidEnvelope = { errors: repair.errors };
+                    if (!repairCandidate.missing)
+                        invalidEnvelope = { errors: repair.errors };
                 }
                 const repairedClassification = invalidEnvelope
                     ? classifyLaneExit({ envelope: null, hasPartialOutput: false, invalidEnvelope })

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

@@ -198,6 +198,7 @@ export declare function envelopeRepairPrompt(input: {
     envelopePath: string;
     error: string;
     rawText: string;
+    missing?: boolean;
 }): string;
 export interface ProviderResumeInput {
     session_id: string;
@@ -228,7 +229,10 @@ export declare function buildProviderCommand(provider: LaneProvider, input: {
 export declare function workerEnv(base: NodeJS.ProcessEnv, resolved: {
     envVar: string;
     home: string;
-}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef): NodeJS.ProcessEnv;
+}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string): NodeJS.ProcessEnv;
+export declare const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
+/** Grok does not run HQ hooks; Claude and Codex use the installed capability marker. */
+export declare function workerPolicyDeliveryMode(hqRoot: string, provider: LaneProvider): "hook" | "prompt";
 export declare function markSpawnFailure(hqRoot: string, laneId: string, reasonRaw: string, details: Record<string, unknown>): LaneRecord;
 /**
  * Spec §5.2 executing-side check. Compares this machine's identity to
@@ -251,6 +255,11 @@ export interface SpawnManifestFile {
     worker_profile_hash?: string;
     worker_profile_ignored?: string[];
     worker_profile_settings?: string;
+    worker_policy_delivery?: "hook" | "prompt";
+    worker_policy_dir?: string;
+    worker_policy_env?: {
+        HQ_POLICY_WORKER_DIR: string;
+    };
 }
 /** Read the per-run manifest. Missing file or field reads as absent. */
 export declare function readSpawnManifest(runDir: string): SpawnManifestFile;
@@ -282,6 +291,8 @@ export interface EnvelopeRepairSpawnInput {
     envelopePath: string;
     error: string;
     rawText: string;
+    /** True when this run never wrote its expected envelope file. */
+    missing?: boolean;
 }
 /** How the spec §4 repair turn reaches the provider (recorded as `envelope_repair.mode`). */
 export type EnvelopeRepairMode = "resume" | "fresh_turn";

package/dist/lib/lanes/spawn.js

@@ -1013,6 +1013,17 @@ export function envelopeRepairPrompt(input) {
     const rawText = input.rawText.length <= maxRawTextChars
         ? input.rawText
         : `${input.rawText.slice(0, 12_000)}\n\n[... raw envelope truncated; inspect ${input.envelopePath} for the complete file ...]\n\n${input.rawText.slice(-12_000)}`;
+    if (input.missing) {
+        return [
+            `Missing expected envelope file: ${input.envelopePath}`,
+            "The previous envelope is stale and must not be reused or copied into this run's result.",
+            "Printing an envelope in the conversation or writing it to last-message.txt is not enough; write the JSON object directly to the expected file.",
+            "Schema:",
+            JSON.stringify(LANE_ENVELOPE_JSON_SCHEMA, null, 2),
+            `Write the corrected JSON object to ${input.envelopePath}, overwriting it. ` +
+                `Output only that JSON. Do not add keys the schema does not name, and do not resume the task.`,
+        ].join("\n\n");
+    }
     return [
         `The file you wrote at ${input.envelopePath} is not a valid hq-lane-envelope.v1. ` +
             `This is the single repair turn: rewrite that file so it validates, and do nothing else.`,
@@ -1119,7 +1130,7 @@ export function buildProviderCommand(provider, input) {
         args: appendFastModeFlags(parsed, appendEffortFlag(parsed, appendModelFlag(parsed, appendProviderProfileFlags(parsed, args, input.profile), input.model), input.effort), input.fastMode),
     };
 }
-export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany) {
+export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, meshCompany, workerPolicyDir) {
     const accepted = Object.values(PROVIDER_HOME_ENV);
     if (!accepted.includes(resolved.envVar)) {
         throw new LanesError("unknown_provider_home_env", `Unknown provider home variable ${JSON.stringify(resolved.envVar)}. Accepted: ${accepted.join(", ")}`, { accepted, value: resolved.envVar });
@@ -1127,6 +1138,7 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     const env = { ...base };
     delete env.HQ_PROJECT_ID;
     delete env.HQ_STORY_ID;
+    delete env.HQ_POLICY_WORKER_DIR;
     env[resolved.envVar] = resolved.home;
     delete env[CLAUDE_AUTO_COMPACT_ENV];
     if (resolved.envVar === PROVIDER_HOME_ENV.claude && autoCompactTokens !== undefined) {
@@ -1134,6 +1146,10 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     }
     env.HQ_LANE_ID = laneId;
     env.HQ_ROOT = hqRoot;
+    if (workerPolicyDir !== undefined &&
+        (resolved.envVar === PROVIDER_HOME_ENV.claude || resolved.envVar === PROVIDER_HOME_ENV.codex)) {
+        env.HQ_POLICY_WORKER_DIR = workerPolicyDir;
+    }
     if (meshCompany) {
         env.HQ_SPAWN_COMPANY = meshCompany.slug || meshCompany.uid;
     }
@@ -1142,6 +1158,28 @@ export function workerEnv(base, resolved, laneId, hqRoot, autoCompactTokens, mes
     }
     return env;
 }
+export const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
+function installedWorkerPolicyHookSupportsDirectory(hqRoot) {
+    const hookPath = path.join(hqRoot, ".claude", "hooks", "inject-policy-on-trigger.sh");
+    try {
+        return fs.readFileSync(hookPath, "utf8")
+            .split(/\r?\n/)
+            .some((line) => line === WORKER_POLICY_HOOK_CAPABILITY);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        process.stderr.write(`hq lanes: cannot inspect worker-policy hook capability at ${hookPath}: ${err instanceof Error ? err.message : String(err)}; keeping policy prompt delivery\n`);
+        return false;
+    }
+}
+/** Grok does not run HQ hooks; Claude and Codex use the installed capability marker. */
+export function workerPolicyDeliveryMode(hqRoot, provider) {
+    return provider !== "grok" && installedWorkerPolicyHookSupportsDirectory(hqRoot)
+        ? "hook"
+        : "prompt";
+}
 function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
 }
@@ -1331,6 +1369,13 @@ function writeSpawnManifest(runDir, input) {
                 worker_profile: input.profile.id,
                 worker_profile_hash: input.profile.hash,
                 worker_profile_ignored: [...input.profile.ignoredFields],
+                worker_policy_delivery: input.profile.policyDelivery,
+                ...(input.profile.policyDir !== undefined
+                    ? {
+                        worker_policy_dir: input.profile.policyDir,
+                        worker_policy_env: { HQ_POLICY_WORKER_DIR: input.profile.policyDir },
+                    }
+                    : {}),
                 ...(input.profile.settingsPath
                     ? { worker_profile_settings: input.profile.settingsPath }
                     : {}),
@@ -1513,12 +1558,18 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const ignoredProfileFields = profile
         ? ignoredWorkerProfileFields(existing.provider)
         : [];
+    const policyDelivery = profile
+        ? workerPolicyDeliveryMode(hqRoot, existing.provider)
+        : undefined;
+    const workerPolicyDir = profile !== undefined && existing.provider !== "grok"
+        ? path.relative(hqRoot, profile.dir).split(path.sep).join("/")
+        : undefined;
     const profileRuntime = profile
         ? materializeWorkerProfile(profile, runDir)
         : undefined;
     const profileLaunch = profile
         ? {
-            systemPrompt: workerProfilePrompt(profile),
+            systemPrompt: workerProfilePrompt(profile, policyDelivery ?? "prompt"),
             ...(profileRuntime?.settingsPath !== undefined
                 ? { settingsPath: profileRuntime.settingsPath }
                 : {}),
@@ -1637,7 +1688,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir);
     const model = resolveLaneModel({
         cliModel: pinnedModel,
         profileModel,
@@ -1652,10 +1703,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         model,
     });
     const fastMode = lane.provider === "codex"
-        ? profileDefaultsApply
-            ? profile?.meta.fast_mode === true
-            : model !== undefined &&
-                (config.providers.codex.fast_mode_models ?? []).includes(model)
+        ? (profileDefaultsApply ? profile?.meta.fast_mode : undefined) ??
+            (model !== undefined && (config.providers.codex.fast_mode_models ?? []).includes(model))
         : false;
     const resume = plan.mode === "resume"
         ? {
@@ -1786,7 +1835,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ? {
                     model_source: pinnedModel !== undefined
                         ? "cli"
-                        : profileDefaultsApply
+                        : profileModel !== undefined
                             ? "profile"
                             : accountCfg?.model !== undefined
                                 ? "account"
@@ -1801,8 +1850,9 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ? {
                     worker_profile_hash: profile.contentHash,
                     worker_profile_ignored: [...ignoredProfileFields],
+                    worker_policy_delivery: policyDelivery,
                 }
-                : {}),
+                : { worker_policy_delivery: undefined }),
         };
         if (resume !== undefined) {
             next.provider_session_id = resume.session_id;
@@ -1901,6 +1951,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                         id: profile.id,
                         hash: profile.contentHash,
                         ignoredFields: ignoredProfileFields,
+                        policyDelivery: policyDelivery ?? "prompt",
+                        ...(workerPolicyDir !== undefined ? { policyDir: workerPolicyDir } : {}),
                         ...(profileRuntime?.settingsPath !== undefined
                             ? { settingsPath: profileRuntime.settingsPath }
                             : {}),
@@ -1985,12 +2037,18 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const ignoredProfileFields = profile
         ? ignoredWorkerProfileFields(lane.provider)
         : [];
+    const policyDelivery = profile
+        ? workerPolicyDeliveryMode(hqRoot, lane.provider)
+        : undefined;
+    const workerPolicyDir = profile !== undefined && lane.provider !== "grok"
+        ? path.relative(hqRoot, profile.dir).split(path.sep).join("/")
+        : undefined;
     const profileRuntime = profile
         ? materializeWorkerProfile(profile, runDir)
         : undefined;
     const profileLaunch = profile
         ? {
-            systemPrompt: workerProfilePrompt(profile),
+            systemPrompt: workerProfilePrompt(profile, policyDelivery ?? "prompt"),
             ...(profileRuntime?.settingsPath !== undefined
                 ? { settingsPath: profileRuntime.settingsPath }
                 : {}),
@@ -2014,7 +2072,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const autoCompactTokens = lane.provider === "claude"
         ? providerAutoCompactTokens(config.providers.claude)
         : undefined;
-    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined);
+    const childEnv = workerEnv(env, { envVar: resolved.envVar, home: resolved.home }, lane.lane_id, hqRoot, autoCompactTokens, lane.mesh_company ?? lane.company ?? undefined, workerPolicyDir);
     const accountCfg = config.providers[lane.provider].accounts[resolved.id];
     const model = resolveLaneModel({
         cliModel: pinnedModel,
@@ -2030,15 +2088,14 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
         model,
     });
     const fastMode = lane.provider === "codex"
-        ? profileDefaultsApply
-            ? profile?.meta.fast_mode === true
-            : model !== undefined &&
-                (config.providers.codex.fast_mode_models ?? []).includes(model)
+        ? (profileDefaultsApply ? profile?.meta.fast_mode : undefined) ??
+            (model !== undefined && (config.providers.codex.fast_mode_models ?? []).includes(model))
         : false;
     const repairPrompt = envelopeRepairPrompt({
         envelopePath: input.envelopePath,
         error: input.error,
         rawText: input.rawText,
+        missing: input.missing,
     });
     const command = buildProviderCommand(lane.provider, {
         hqRoot,
@@ -2081,6 +2138,8 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
                         id: profile.id,
                         hash: profile.contentHash,
                         ignoredFields: ignoredProfileFields,
+                        policyDelivery: policyDelivery ?? "prompt",
+                        ...(workerPolicyDir !== undefined ? { policyDir: workerPolicyDir } : {}),
                         ...(profileRuntime?.settingsPath !== undefined
                             ? { settingsPath: profileRuntime.settingsPath }
                             : {}),
@@ -2102,11 +2161,12 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
             if (profile !== undefined) {
                 next.worker_profile_hash = profile.contentHash;
                 next.worker_profile_ignored = [...ignoredProfileFields];
+                next.worker_policy_delivery = policyDelivery;
                 if (model !== undefined) {
                     next.model = model;
                     next.model_source = pinnedModel !== undefined
                         ? "cli"
-                        : profileDefaultsApply
+                        : profileModel !== undefined
                             ? "profile"
                             : accountCfg?.model !== undefined
                                 ? "account"
@@ -2124,6 +2184,9 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
                 else
                     delete next.effort;
             }
+            else {
+                next.worker_policy_delivery = undefined;
+            }
             if (fastMode)
                 next.fast_mode = true;
             else