@indigoai-us/hq-cli 5.345.44 → 5.345.46

package/dist/lib/doctor/checks/sync-runtime.js

@@ -11,6 +11,8 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { currentSyncLogFamily, SYNC_LOG_GENERATIONS, syncLogBasePaths, syncLogGenerationPath, } from "../../../utils/sync-log-sources.js";
 export const SYNC_RUNTIME_WINDOW_MS = 60 * 60_000;
+/** Ignore timing and restart signals until a newly started receiver has settled. */
+export const SYNC_RUNTIME_RESTART_WARMUP_MS = 20 * 60_000;
 const LAG_SECONDS = 15 * 60;
 const LAG_MIN_RECEIPTS = 3;
 const RESTART_MIN_STARTS = 4;
@@ -62,7 +64,9 @@ function lineTimestamp(line) {
 /** Classify the last hour of sync log lines into privacy-safe results. */
 export function analyzeSyncRuntimeLog(lines, options) {
     const since = options.now - SYNC_RUNTIME_WINDOW_MS;
-    let slowReceipts = 0;
+    const contextSince = since - SYNC_RUNTIME_RESTART_WARMUP_MS;
+    const slowReceiptTimes = [];
+    const receiverStartTimes = [];
     let denied = 0;
     let starts = 0;
     let deviceLimited = 0;
@@ -70,35 +74,45 @@ export function analyzeSyncRuntimeLog(lines, options) {
         const time = lineTimestamp(line);
         if (time === null)
             continue;
-        if (!Number.isFinite(time) || time < since || time > options.now)
+        if (!Number.isFinite(time) || time < contextSince || time > options.now)
             continue;
         const stamp = TIMESTAMP.exec(line);
         const rest = stamp ? line.slice(stamp[0].length) : line;
-        if (DEVICE_LIMIT.test(rest))
+        if (time >= since && DEVICE_LIMIT.test(rest))
             deviceLimited += 1;
         const record = parseRecord(rest);
         if (!record)
             continue;
         const event = record.event;
-        if (event === "fanout.receive") {
+        if (event === "receiver.start") {
+            receiverStartTimes.push(time);
+            const settledAt = time + SYNC_RUNTIME_RESTART_WARMUP_MS;
+            // The lower bound preserves a full hour of settled restarts; the upper
+            // bound applies the 20-minute settle rule and excludes only the tail.
+            if (settledAt >= since && settledAt <= options.now)
+                starts += 1;
+        }
+        else if (event === "fanout.receive" && time >= since) {
             const latency = record.latencySeconds;
             if (typeof latency === "number" && latency > LAG_SECONDS)
-                slowReceipts += 1;
-        }
-        else if (event === "receiver.start") {
-            starts += 1;
+                slowReceiptTimes.push(time);
         }
-        if ((record.type === "receiver" || record.type === "error" ||
-            (typeof event === "string" && event.startsWith("receiver."))) &&
+        if (time >= since &&
+            (record.type === "receiver" || record.type === "error" ||
+                (typeof event === "string" && event.startsWith("receiver."))) &&
             PERMISSION.test(JSON.stringify(record.err ?? record.message ?? ""))) {
             denied += 1;
         }
     }
+    // Startup can temporarily expose queued receive latency and restart events
+    // while the receiver is warming its backlog. Only judge receipts outside the
+    // warm-up interval following the most recent preceding start.
+    const slowReceipts = slowReceiptTimes.filter((time) => !receiverStartTimes.some((start) => start <= time && time - start < SYNC_RUNTIME_RESTART_WARMUP_MS)).length;
     const conflicts = options.conflictCount ?? 0;
     const checks = [
         { id: "realtime-lag", reasonCode: "realtime-lag-stuck", failing: slowReceipts >= LAG_MIN_RECEIPTS, count: slowReceipts, label: "incoming changes delayed over 15 minutes" },
         { id: "receiver-permission", reasonCode: "receiver-permission-denied", failing: denied > 0, count: denied, label: "cloud permission refusals" },
-        { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "sync runner starts" },
+        { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "settled sync runner starts" },
         { id: "device-limit", reasonCode: "device-limit-backoff", failing: deviceLimited > 0, count: deviceLimited, label: "device-limit backoffs" },
         { id: "conflicts", reasonCode: "repeated-conflicts", failing: conflicts >= CONFLICT_MIN_COUNT, count: conflicts, label: "unresolved conflicts" },
     ];
@@ -197,7 +211,7 @@ export function defaultSyncRuntimeResults(now, hqHome = path.join(os.homedir(),
     const logFile = family === null ? paths.desktop : paths[family];
     let lines;
     try {
-        lines = readWindowLines(logFile, options.now - SYNC_RUNTIME_WINDOW_MS, family === "daemon");
+        lines = readWindowLines(logFile, options.now - SYNC_RUNTIME_WINDOW_MS - SYNC_RUNTIME_RESTART_WARMUP_MS, family === "daemon");
     }
     catch {
         return [

package/dist/lib/flag-snapshot-file.js

@@ -78,29 +78,38 @@ function isPermissionFailure(error) {
     const code = error?.code;
     return code === "EACCES" || code === "EPERM";
 }
-function fallbackSnapshotPath(companyUid, create) {
-    if (typeof process.getuid !== "function")
+function fallbackSnapshotPath(companyUid, create, env = process.env) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    const root = uid === undefined
+        ? env.LOCALAPPDATA?.trim()
+        : path.join(os.tmpdir(), `hq-cli-flag-snapshots-${uid}`);
+    if (!root)
         return undefined;
-    const uid = process.getuid();
-    const root = path.join(os.tmpdir(), `hq-cli-flag-snapshots-${uid}`);
-    const directories = [root, path.join(root, "hq"), path.join(root, "hq", "flags")];
+    const fallbackRoot = uid === undefined ? path.join(root, "hq-cli", "flag-snapshots") : root;
+    const directories = uid === undefined
+        ? [path.join(root, "hq-cli"), fallbackRoot]
+        : [fallbackRoot, path.join(fallbackRoot, "hq"), path.join(fallbackRoot, "hq", "flags")];
     for (const directory of directories) {
         try {
             if (create)
                 fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
             const stat = fs.lstatSync(directory);
-            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== uid)
-                return undefined;
-            if (create)
-                fs.chmodSync(directory, 0o700);
-            else if ((stat.mode & 0o077) !== 0)
+            if (!stat.isDirectory() || stat.isSymbolicLink())
                 return undefined;
+            if (uid !== undefined) {
+                if (stat.uid !== uid)
+                    return undefined;
+                if (create)
+                    fs.chmodSync(directory, 0o700);
+                else if ((stat.mode & 0o077) !== 0)
+                    return undefined;
+            }
         }
         catch {
             return undefined;
         }
     }
-    return path.join(directories[2], `snapshot-${companyUid}.json`);
+    return path.join(directories[directories.length - 1], `snapshot-${companyUid}.json`);
 }
 function fallbackPersonSnapshotPath(create) {
     if (typeof process.getuid !== "function")
@@ -275,7 +284,7 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
     }
     const cacheRootKind = env.XDG_CACHE_HOME?.trim() ? "xdg" : "home";
     const writeFallback = (originalError) => {
-        const fallbackFile = fallbackSnapshotPath(companyUid, true);
+        const fallbackFile = fallbackSnapshotPath(companyUid, true, env);
         if (!fallbackFile) {
             if (originalError) {
                 markFallbackFailed(originalError);
@@ -347,21 +356,20 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
     const file = flagSnapshotPath(companyUid, options.env);
     if (!file)
         return null;
-    if (fallbackCacheUsed) {
-        const fallback = fallbackSnapshotPath(companyUid, false);
-        const snapshot = fallback ? parseSnapshotFile(companyUid, fallback, options) : null;
-        if (snapshot)
-            return snapshot;
-    }
     const primary = parseSnapshotFile(companyUid, file, options);
-    if (primary)
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (primary && !fallbackCacheUsed && uid !== undefined)
         return primary;
-    const fallback = fallbackSnapshotPath(companyUid, false);
-    if (!fallback)
-        return null;
-    const snapshot = parseSnapshotFile(companyUid, fallback, options);
-    if (snapshot)
+    const fallback = fallbackSnapshotPath(companyUid, false, options.env);
+    const fallbackSnapshot = fallback ? parseSnapshotFile(companyUid, fallback, options) : null;
+    // A process can restart after a denied Windows rename wrote a newer snapshot
+    // to LOCALAPPDATA. Compare both valid stores so an older primary does not
+    // mask that successful fallback write. Equal timestamps keep the primary.
+    if (fallbackSnapshot
+        && (!primary || Date.parse(fallbackSnapshot.fetched_at) > Date.parse(primary.fetched_at))) {
         fallbackCacheUsed = true;
-    return snapshot;
+        return fallbackSnapshot;
+    }
+    return primary;
 }
 //# sourceMappingURL=flag-snapshot-file.js.map

package/dist/lib/install/claude-targets.js

@@ -50,9 +50,14 @@ export function hqSkillsSource(hqRoot) {
 /** The exact hook command registered for one event (absolute path, quoted). */
 export function hookCommand(hqRoot, event, target = 'master') {
     const skipInsideRoot = `if [ -d "\${CLAUDE_PROJECT_DIR:-}" ] && [ "\${CLAUDE_PROJECT_DIR}" -ef ${shellQuote(hqRoot)} ]; then exit 0; fi; cwd=$(pwd -P 2>/dev/null || pwd); while [ -n "$cwd" ]; do if [ -f "$cwd/core/core.yaml" ] && [ -f "$cwd/companies/manifest.yaml" ]; then exit 0; fi; [ "$cwd" = / ] && break; cwd=\${cwd%/*}; [ -n "$cwd" ] || cwd=/; done; `;
+    // Many HQ hooks take their root from CLAUDE_PROJECT_DIR (some before HQ_ROOT). In a
+    // foreign project that is the user's folder, so they load no policies and write
+    // workspace/ state there. Point both at HQ; the payload's cwd still names the
+    // folder the session is working in.
+    const rootEnv = `HQ_ROOT=${shellQuote(hqRoot)} CLAUDE_PROJECT_DIR=${shellQuote(hqRoot)} `;
     if (target === 'shim')
-        return `${skipInsideRoot}exec /bin/sh ${shellQuote(shimPath(hqRoot))} ${shellQuote(event)} --runtime claude`;
-    return `${skipInsideRoot}BASH_ENV=/dev/null exec bash ${shellQuote(masterHookPath(hqRoot))} ${shellQuote(event)}`;
+        return `${skipInsideRoot}${rootEnv}exec /bin/sh ${shellQuote(shimPath(hqRoot))} ${shellQuote(event)} --runtime claude`;
+    return `${skipInsideRoot}${rootEnv}BASH_ENV=/dev/null exec bash ${shellQuote(masterHookPath(hqRoot))} ${shellQuote(event)}`;
 }
 /** Quote one argument for the POSIX shell used by Claude Code command hooks. */
 function shellQuote(value) {

package/dist/lib/install/codex-targets.d.ts

@@ -30,6 +30,12 @@ type Doc = Record<string, unknown>;
 export declare function addCodexHooks(doc: Doc, hqRoot: string, target?: HookTarget): Doc;
 /** Remove only HQ adapter entries; drop containers this left empty. */
 export declare function removeCodexHooks(doc: Doc, hqRoot: string): Doc;
+/**
+ * Codex trust keys (`<hooks.json>:<snake_event>:<group>:<hook>`) for the HQ
+ * entries in a hooks.json document. Foreign entries are left out so install
+ * never trusts a hook the user added themselves.
+ */
+export declare function codexHookTrustKeys(doc: Doc, hooksJsonPath: string, hqRoot: string): string[];
 export declare function hasAllCodexHooks(doc: Doc, hqRoot: string, target?: HookTarget): boolean;
 export type LegacySkillsMirror = {
     kind: 'absent';

package/dist/lib/install/codex-targets.js

@@ -155,6 +155,31 @@ export function removeCodexHooks(doc, hqRoot) {
         next.hooks = hooks;
     return next;
 }
+/**
+ * Codex trust keys (`<hooks.json>:<snake_event>:<group>:<hook>`) for the HQ
+ * entries in a hooks.json document. Foreign entries are left out so install
+ * never trusts a hook the user added themselves.
+ */
+export function codexHookTrustKeys(doc, hooksJsonPath, hqRoot) {
+    const hooks = doc.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const keys = [];
+    for (const [event, value] of Object.entries(hooks)) {
+        if (!Array.isArray(value))
+            continue;
+        const snake = event.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+        value.forEach((group, g) => {
+            if (!group || !Array.isArray(group.hooks))
+                return;
+            group.hooks.forEach((entry, h) => {
+                if (isAdapterEntry(entry, hqRoot))
+                    keys.push(`${hooksJsonPath}:${snake}:${g}:${h}`);
+            });
+        });
+    }
+    return keys;
+}
 export function hasAllCodexHooks(doc, hqRoot, target = 'master') {
     return addCodexHooks(doc, hqRoot, target) === doc;
 }

package/dist/lib/lanes/flag-keys.d.ts

@@ -1,4 +1,5 @@
 /** hq-flags keys used by lane command behavior. */
+export declare const LANE_FOCUS_GUARD_FLAG = "lanes-focus-guard";
 export declare const LANE_FOCUS_DASHBOARD_FLAG = "lanes-focus-dashboard";
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 /** Enables same-provider automatic lane recovery after provider quota exhaustion. */

package/dist/lib/lanes/flag-keys.js

@@ -1,4 +1,5 @@
 /** hq-flags keys used by lane command behavior. */
+export const LANE_FOCUS_GUARD_FLAG = "lanes-focus-guard";
 export const LANE_FOCUS_DASHBOARD_FLAG = "lanes-focus-dashboard";
 export const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 /** Enables same-provider automatic lane recovery after provider quota exhaustion. */

package/dist/lib/lanes/focus-guard.d.ts

@@ -0,0 +1,65 @@
+import { LanesError } from "./errors.js";
+export declare const FOCUS_GUARD_MAX_PR_AGE_MS: number;
+export interface FocusGuardStory {
+    id: string;
+    focus_id?: unknown;
+    kpi?: unknown;
+    state?: unknown;
+    status?: unknown;
+    lane?: unknown;
+    lanes?: unknown;
+}
+export interface FocusGuardPullRequest {
+    number: number;
+    created_at: string;
+    repository?: string;
+}
+export interface FocusGuardLane {
+    lane_id: string;
+    state: string;
+}
+export type FocusGuardReason = {
+    code: "story_missing_focus";
+    story_id: string;
+} | {
+    code: "open_pr_over_48h";
+    number: number;
+    age_hours: number;
+    repository?: string;
+} | {
+    code: "stale_story";
+    story_id: string;
+    lane_id: string | null;
+} | {
+    code: "pr_lookup_failed";
+};
+export interface FocusGuardOverride {
+    reason: string;
+    by_lane: string;
+    at: string;
+    story: string;
+}
+export declare function appendLaneFocusOverride<T extends {
+    focus_overrides?: FocusGuardOverride[];
+}>(lane: T, override: FocusGuardOverride): T & {
+    focus_overrides: FocusGuardOverride[];
+};
+export declare function evaluateFocusGuard(input: {
+    storyIds: readonly string[];
+    stories: readonly FocusGuardStory[];
+    lanes: readonly FocusGuardLane[];
+    pullRequests?: readonly FocusGuardPullRequest[];
+    pullRequestLookupFailed?: boolean;
+    now: Date;
+    checkTeamBlockers: boolean;
+}): FocusGuardReason[];
+export declare function evaluateFocusGuardIfEnabled(enabled: boolean, input: Parameters<typeof evaluateFocusGuard>[0]): FocusGuardReason[];
+export declare function assertFocusGuardAllows(enabled: boolean, input: Parameters<typeof evaluateFocusGuard>[0], overrideReason?: string): FocusGuardReason[];
+export declare function focusGuardRefusal(reasons: readonly FocusGuardReason[]): LanesError;
+export declare function makeFocusOverride(input: {
+    reason?: string;
+    laneId: string;
+    at: string;
+    storyId: string;
+}): FocusGuardOverride | undefined;
+//# sourceMappingURL=focus-guard.d.ts.map

package/dist/lib/lanes/focus-guard.js

@@ -0,0 +1,91 @@
+import { LanesError } from "./errors.js";
+import { isTerminalLaneState } from "./types.js";
+export const FOCUS_GUARD_MAX_PR_AGE_MS = 48 * 60 * 60 * 1000;
+export function appendLaneFocusOverride(lane, override) {
+    return { ...lane, focus_overrides: [...(lane.focus_overrides ?? []), override].slice(-100) };
+}
+function nonempty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function storyLaneIds(story) {
+    const candidates = [story.lane, ...(Array.isArray(story.lanes) ? story.lanes : [])];
+    return [...new Set(candidates.flatMap((item) => {
+            if (typeof item === "string" && item.trim())
+                return [item.trim()];
+            if (item !== null && typeof item === "object" && typeof item.lane === "string") {
+                const lane = item.lane.trim();
+                return lane ? [lane] : [];
+            }
+            if (item !== null && typeof item === "object" && typeof item.lane_id === "string") {
+                const laneId = item.lane_id.trim();
+                return laneId ? [laneId] : [];
+            }
+            return [];
+        }))];
+}
+export function evaluateFocusGuard(input) {
+    const reasons = [];
+    const storyById = new Map(input.stories.map((story) => [story.id.trim(), story]));
+    for (const id of input.storyIds) {
+        const story = storyById.get(id);
+        if (!story || (!nonempty(story.focus_id) && !nonempty(story.kpi))) {
+            reasons.push({ code: "story_missing_focus", story_id: id });
+        }
+    }
+    if (!input.checkTeamBlockers)
+        return reasons;
+    if (input.pullRequestLookupFailed) {
+        reasons.push({ code: "pr_lookup_failed" });
+    }
+    else {
+        for (const pr of input.pullRequests ?? []) {
+            const ageMs = input.now.getTime() - Date.parse(pr.created_at);
+            if (Number.isFinite(ageMs) && ageMs > FOCUS_GUARD_MAX_PR_AGE_MS) {
+                reasons.push({
+                    code: "open_pr_over_48h",
+                    number: pr.number,
+                    age_hours: Math.floor(ageMs / (60 * 60 * 1000)),
+                    ...(pr.repository === undefined ? {} : { repository: pr.repository }),
+                });
+            }
+        }
+    }
+    const liveLaneIds = new Set(input.lanes
+        .filter((lane) => !isTerminalLaneState(lane.state))
+        .map((lane) => lane.lane_id));
+    for (const story of input.stories) {
+        const storyStatus = typeof story.state === "string" ? story.state : story.status;
+        if (storyStatus !== "in_progress")
+            continue;
+        const assigned = storyLaneIds(story);
+        if (assigned.length === 0 || assigned.every((laneId) => !liveLaneIds.has(laneId))) {
+            reasons.push({ code: "stale_story", story_id: story.id, lane_id: assigned[0] ?? null });
+        }
+    }
+    return reasons;
+}
+export function evaluateFocusGuardIfEnabled(enabled, input) {
+    return enabled ? evaluateFocusGuard(input) : [];
+}
+export function assertFocusGuardAllows(enabled, input, overrideReason) {
+    const reasons = evaluateFocusGuardIfEnabled(enabled, input);
+    if (enabled && reasons.length > 0 && overrideReason === undefined)
+        throw focusGuardRefusal(reasons);
+    return reasons;
+}
+export function focusGuardRefusal(reasons) {
+    return new LanesError("focus_guard_refused", `Lane launch refused by focus guard: ${reasons.map((reason) => reason.code).join(", ")}`, { reasons });
+}
+export function makeFocusOverride(input) {
+    if (input.reason === undefined)
+        return undefined;
+    const reason = input.reason.trim();
+    if (!reason) {
+        throw new LanesError("focus_override_reason_required", "--focus-override requires a non-empty reason", {
+            lane_id: input.laneId,
+            story_id: input.storyId,
+        });
+    }
+    return { reason, by_lane: input.laneId, at: input.at, story: input.storyId };
+}
+//# sourceMappingURL=focus-guard.js.map

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -33,6 +33,7 @@ export interface OutpostLaneCommand {
     text?: string;
     project?: string;
     story?: string;
+    focusOverride?: string;
     account?: string;
     model?: string;
     effort?: string;

package/dist/lib/lanes/outpost-dispatch.js

@@ -199,6 +199,7 @@ export function buildOutpostLaneCommand(input) {
         ["--text", input.text],
         ["--project", input.project],
         ["--story", input.story],
+        ["--focus-override", input.focusOverride],
         ["--account", input.account],
         ["--model", input.model],
         ["--effort", input.effort],

package/dist/lib/lanes/store.js

@@ -392,6 +392,10 @@ export function parseLaneRecord(raw, filePath) {
             path: filePath,
         });
     }
+    // Company attribution was added after lane records already existed on disk.
+    // Treat its historical absence as the same unbound state as an explicit null.
+    if (raw.company === undefined)
+        raw.company = null;
     for (const field of REQUIRED_LANE_RECORD_FIELDS) {
         if (!(field in raw)) {
             throw new LaneSchemaError(`Missing required lane record field ${field}`, { path: filePath, field });
@@ -423,6 +427,31 @@ export function parseLaneRecord(raw, filePath) {
     requireInt(raw.version, "version");
     requireInt(raw.depth, "depth");
     requireInt(raw.priority, "priority");
+    if (raw.focus_overrides !== undefined) {
+        if (!Array.isArray(raw.focus_overrides) || raw.focus_overrides.length > 100) {
+            throw new LaneSchemaError("focus_overrides must be an array with at most 100 entries", {
+                path: filePath,
+                field: "focus_overrides",
+            });
+        }
+        for (const [index, entry] of raw.focus_overrides.entries()) {
+            if (!isPlainObject(entry)) {
+                throw new LaneSchemaError("focus_overrides entries must be objects", {
+                    path: filePath,
+                    field: `focus_overrides[${index}]`,
+                });
+            }
+            for (const field of ["reason", "by_lane", "story"]) {
+                if (typeof entry[field] !== "string" || !entry[field].trim()) {
+                    throw new LaneSchemaError(`focus_overrides[${index}].${field} must be non-empty`, {
+                        path: filePath,
+                        field: `focus_overrides[${index}].${field}`,
+                    });
+                }
+            }
+            requireTimestamp(entry.at, `focus_overrides[${index}].at`, filePath);
+        }
+    }
     if (raw.ended_at !== undefined) {
         requireTimestamp(raw.ended_at, "ended_at", filePath);
     }

package/dist/lib/lanes/story-ledger.d.ts

@@ -24,6 +24,20 @@ export interface StoryLedgerQuestionRef {
     project_id: string;
     story_id: string;
 }
+export interface ProjectFocusOverride {
+    reason: string;
+    by_lane: string;
+    at: string;
+    story: string;
+}
+export declare function readProjectStoryFocusData(hqRoot: string, projectId: string, companySlug?: string): {
+    path: string;
+    metadata: Record<string, unknown>;
+    userStories: Array<Record<string, unknown>>;
+    focusOverrides: ProjectFocusOverride[];
+};
+export declare function appendProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
+export declare function removeProjectFocusOverride(hqRoot: string, projectId: string, companySlug: string | undefined, override: ProjectFocusOverride): void;
 export interface LaneStatusSnapshot {
     schema_version: "hq-lanes-status.v1";
     project_id: string;

package/dist/lib/lanes/story-ledger.js

@@ -11,6 +11,52 @@ const LOCK_RETRY_MS = 10;
 const STORY_STATES = ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
 const MANAGER_OWNED_STATES = new Set(["review", "done", "dropped"]);
 const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
+function projectFocusOverrides(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 100) {
+        throw new LanesError("project_focus_overrides_invalid", "Project focus_overrides must be an array with at most 100 entries", {});
+    }
+    return value.map((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} must be an object`, {});
+        }
+        const entry = item;
+        if (["reason", "by_lane", "at", "story"].some((key) => typeof entry[key] !== "string" || !entry[key].trim())) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} is incomplete`, {});
+        }
+        if (!Number.isFinite(Date.parse(entry.at))) {
+            throw new LanesError("project_focus_overrides_invalid", `Project focus override ${index} has an invalid timestamp`, {});
+        }
+        return entry;
+    });
+}
+export function readProjectStoryFocusData(hqRoot, projectId, companySlug) {
+    const ledger = resolveProjectStoryLedger(hqRoot, projectId, companySlug);
+    const parsed = readLedger(ledger);
+    const metadata = parsed.metadata;
+    return {
+        path: ledger.path,
+        metadata: metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+            ? metadata
+            : {},
+        userStories: parsed.userStories,
+        focusOverrides: projectFocusOverrides(parsed.focus_overrides),
+    };
+}
+export function appendProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const existing = projectFocusOverrides(current.focus_overrides);
+        return { ...current, focus_overrides: [...existing, override].slice(-100) };
+    });
+}
+export function removeProjectFocusOverride(hqRoot, projectId, companySlug, override) {
+    updateLedgerAtomically(resolveProjectStoryLedger(hqRoot, projectId, companySlug), (current) => {
+        const remaining = projectFocusOverrides(current.focus_overrides).filter((entry) => entry.reason !== override.reason || entry.by_lane !== override.by_lane ||
+            entry.at !== override.at || entry.story !== override.story);
+        return { ...current, focus_overrides: remaining };
+    });
+}
 export function laneStoryLedgerEnabled(companyUid) {
     return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false, companyUid);
 }

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

@@ -525,6 +525,13 @@ export interface LaneRecord {
     story_id: string;
     /** Explicit reason a lane was created without a project story. */
     no_story_reason?: string;
+    /** Human-authored focus guard overrides used to launch this lane onto a story. */
+    focus_overrides?: Array<{
+        reason: string;
+        by_lane: string;
+        at: string;
+        story: string;
+    }>;
     /** Last failed story-ledger synchronization, cleared after a successful retry. */
     ledger_sync_error?: string;
     /** Pending question ids owned by this lane. */
@@ -758,8 +765,9 @@ export interface LaneRecord {
     /** Last successful lane_progress mesh delivery, preserved across watcher restarts. */
     last_progress_event_at?: string;
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
-export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "company", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
+export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
 export declare const LANE_WRITERS: readonly ["creator", "command", "watcher", "reconcile", "spawn", "story-ledger"];
 export type LaneWriter = (typeof LANE_WRITERS)[number];
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */

package/dist/lib/lanes/types.js

@@ -215,9 +215,10 @@ export function parseSeniorKind(value) {
         return value;
     throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
 }
-/** The v1 fields that must exist on every durable lane record (spec §3). */
+/** The v1 fields that must exist on every durable lane record (spec §3).
+ * `company` is normalized from absence for pre-attribution legacy records. */
 export const REQUIRED_LANE_RECORD_FIELDS = [
-    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "schema_version", "lane_id", "project_id", "story_id", "depth",
     "senior", "senior_history", "state", "priority", "provider", "host",
     "version", "created_at", "updated_at", "attribution_history",
 ];
@@ -225,7 +226,7 @@ export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spaw
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */
 export const LANE_FIELD_WRITERS = {
     schema_version: ["creator"], lane_id: ["creator"], written_by_version: [], owner_written_by_version: [], company: ["creator", "command"], company_history: ["command"],
-    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"],
+    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], focus_overrides: ["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"],
     released_hire_grant: ["command"],

package/dist/utils/hook-trust.d.ts

@@ -53,6 +53,13 @@ export interface RuntimeHookTrustResult {
 export declare function createCodexAppServerClient(cwd: string, executable?: string, args?: string[]): Promise<CodexRpcClient>;
 /** Trust only hooks declared by this HQ root's project `.codex/` layer. */
 export declare function trustCodexProjectHooks(hqRoot: string, deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult>;
+/**
+ * Trust the user-scope hooks `hq install --global --runtime codex` registered
+ * in ~/.codex/hooks.json, named by their Codex keys (`<file>:<event>:<group>:<hook>`).
+ * Codex skips untrusted hooks, so without this HQ stays inert in every session
+ * outside the HQ folder. Other hooks in the same file are never trusted here.
+ */
+export declare function trustCodexUserHooks(cwd: string, keys: readonly string[], deps?: HookTrustDependencies): Promise<RuntimeHookTrustResult>;
 /**
  * Mark this HQ root as a trusted Claude Code workspace.
  *