@indigoai-us/hq-cli 5.345.44 → 5.345.45

package/dist/commands/lanes.js

@@ -37,7 +37,9 @@ import { laneDepthCap } from "../lib/lanes/depth-cap.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { runResidentCommandWithPackageLease } from "../utils/resident-package-preload.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "../lib/lanes/registry-flag.js";
-import { LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, } from "../lib/lanes/flag-keys.js";
+import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
+import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
+import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, } from "../lib/lanes/flag-keys.js";
 import { configuredCodexRolloutHomes, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
 import { runLeadAutopilotPass } from "../lib/lanes/autopilot.js";
@@ -86,6 +88,133 @@ import { defaultProbe, validateProfileLaneModel, validateLaneModel, } from "../l
 import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
 import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export { spawnLaneWorker };
+export function openPullRequestsForProject(hqRoot, metadata) {
+    const configured = metadata.repos;
+    if (!Array.isArray(configured)) {
+        throw new Error("project does not name repositories");
+    }
+    if (configured.length === 0)
+        return [];
+    const all = [];
+    const reposRoot = fs.realpathSync(path.resolve(hqRoot, "repos")) + path.sep;
+    for (const repo of configured) {
+        if (repo === null || typeof repo !== "object" || typeof repo.path !== "string") {
+            throw new Error("project repository entry is invalid");
+        }
+        const repoPath = repo.path;
+        if (!/^repos\/(private|public)\/[a-zA-Z0-9._/-]+$/.test(repoPath)) {
+            throw new Error("project repository path is outside repos");
+        }
+        if (repoPath.split("/").some((segment) => segment === "." || segment === "..")) {
+            throw new Error("project repository path is outside repos");
+        }
+        const repoDir = path.resolve(hqRoot, repoPath);
+        const canonicalRepoDir = fs.realpathSync(repoDir);
+        if (!canonicalRepoDir.startsWith(reposRoot))
+            throw new Error("project repository path is outside repos");
+        const remoteResult = spawnSync("git", ["-C", repoDir, "remote", "get-url", "origin"], {
+            encoding: "utf8",
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        if (remoteResult.status !== 0)
+            throw new Error("project repository remote could not be read");
+        const remote = remoteResult.stdout.trim();
+        const match = remote.match(/^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i);
+        if (!match)
+            throw new Error("project repository is not a GitHub repository");
+        const endpoint = `repos/${match[1]}/${match[2]}/pulls?state=open&per_page=100`;
+        const result = spawnSync("gh", ["api", "--paginate", "--slurp", endpoint], {
+            encoding: "utf8",
+            timeout: 20_000,
+            windowsHide: true,
+        });
+        if (result.status !== 0)
+            throw new Error("GitHub pull request lookup failed");
+        const pages = JSON.parse(result.stdout || "[]");
+        if (!Array.isArray(pages))
+            throw new Error("GitHub pull request response was invalid");
+        for (const page of pages) {
+            if (!Array.isArray(page))
+                throw new Error("GitHub pull request page was invalid");
+            for (const item of page) {
+                if (item === null || typeof item !== "object")
+                    throw new Error("GitHub pull request entry was invalid");
+                const pr = item;
+                if (!Number.isInteger(pr.number) || typeof pr.created_at !== "string" || !Number.isFinite(Date.parse(pr.created_at))) {
+                    throw new Error("GitHub pull request entry was invalid");
+                }
+                all.push({ number: pr.number, created_at: pr.created_at, repository: `${match[1]}/${match[2]}` });
+            }
+        }
+    }
+    return all;
+}
+async function focusGuardAssessment(ctx, input) {
+    if (input.overrideReason !== undefined) {
+        const normalizedReason = input.overrideReason.trim();
+        if (!normalizedReason) {
+            throw new LanesError("focus_override_reason_required", "--focus-override requires a non-empty reason", {
+                story_ids: input.storyIds,
+            });
+        }
+        assertNoSecretText("focus override reason", normalizedReason);
+    }
+    let enabled = false;
+    try {
+        enabled = ctx.focusGuardEnabled
+            ? await ctx.focusGuardEnabled(input.company ?? undefined)
+            : await readLanesRegistryFlagFailOff(LANE_FOCUS_GUARD_FLAG, {
+                company: input.company,
+                env: ctx.env,
+            });
+    }
+    catch (error) {
+        process.stderr.write(`${JSON.stringify({
+            event: "lanes.focus_guard.flag_read_failed",
+            error: error instanceof Error ? error.name : "UnknownError",
+            fallback: false,
+        })}\n`);
+    }
+    if (!enabled)
+        return { enabled: false, reasons: [] };
+    const project = readProjectStoryFocusData(ctx.hqRoot(), input.projectId, input.company?.slug);
+    let pullRequests;
+    let pullRequestLookupFailed = false;
+    if (input.checkTeamBlockers) {
+        try {
+            pullRequests = openPullRequestsForProject(ctx.hqRoot(), project.metadata);
+        }
+        catch (error) {
+            pullRequestLookupFailed = true;
+            process.stderr.write(`${JSON.stringify({
+                event: "lanes.focus_guard.pr_lookup_failed",
+                project_id: input.projectId,
+                error: error instanceof Error ? error.name : "UnknownError",
+            })}\n`);
+        }
+    }
+    const tenantLanes = loadAllLanes(ctx.hqRoot()).filter((lane) => lane.company?.slug === input.company?.slug && (lane.project_id === input.projectId ||
+        lane.stories?.some((story) => story.project_id === input.projectId) === true));
+    const reasons = assertFocusGuardAllows(enabled, {
+        storyIds: input.storyIds,
+        stories: project.userStories.map((story) => ({
+            id: typeof story.id === "string" ? story.id : "",
+            focus_id: story.focus_id,
+            kpi: story.kpi,
+            state: story.state,
+            status: story.status,
+            lane: story.lane,
+            lanes: story.lanes,
+        })),
+        lanes: tenantLanes,
+        ...(pullRequests === undefined ? {} : { pullRequests }),
+        pullRequestLookupFailed,
+        now: ctx.now(),
+        checkTeamBlockers: input.checkTeamBlockers,
+    }, input.overrideReason);
+    return { enabled: true, reasons };
+}
 export { questionBodyAbsPath };
 export { MAX_LANE_DEPTH };
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
@@ -329,6 +458,7 @@ function resolveDeps(deps = {}) {
         fetchText: deps.fetchText ?? defaultFetchText,
         lanePlacementEnabled: deps.lanePlacementEnabled ?? defaultLanePlacementEnabled,
         storyLedgerEnabled: deps.storyLedgerEnabled ?? laneStoryLedgerEnabled,
+        focusGuardEnabled: deps.focusGuardEnabled,
         isSsmOwnerDispatch: deps.isSsmOwnerDispatch ?? (() => isSsmRunCommandProcess()),
         withGrantHireLocks: deps.withGrantHireLocks ?? withLaneHireLocks,
         mergeReviewEnabled: deps.mergeReviewEnabled,
@@ -3033,6 +3163,12 @@ async function runCreate(ctx, opts) {
     if (opts.story !== undefined && opts.noStory !== undefined) {
         throw new LanesError("story_selection_conflict", "Pass either --story or --no-story, not both", {});
     }
+    if (opts.focusOverride !== undefined) {
+        if (!opts.focusOverride.trim()) {
+            throw new LanesError("focus_override_reason_required", "--focus-override requires a non-empty reason", {});
+        }
+        assertNoSecretText("focus override reason", opts.focusOverride.trim());
+    }
     if (opts.noStory !== undefined && !noStoryReason) {
         throw new LanesError("missing_no_story_reason", "--no-story requires a non-empty reason", {});
     }
@@ -3046,6 +3182,9 @@ async function runCreate(ctx, opts) {
         throw new LanesError("missing_story", "--additional-story values must be non-empty", {});
     }
     const storyIds = story ? [story, ...additionalStories] : [];
+    if (opts.focusOverride !== undefined && storyIds.length === 0) {
+        throw new LanesError("focus_override_story_required", "--focus-override requires --story", {});
+    }
     if (new Set(storyIds).size !== storyIds.length) {
         throw new LanesError("duplicate_story", "A lane cannot carry the same project/story more than once", {
             project_id: project,
@@ -3113,6 +3252,15 @@ async function runCreate(ctx, opts) {
     if (storyIds.length > 0 && ctx.storyLedgerEnabled()) {
         validateProjectStories(hqRoot, project, storyIds, company?.slug);
     }
+    const focusAssessment = storyIds.length > 0
+        ? await focusGuardAssessment(ctx, {
+            projectId: project,
+            storyIds,
+            company,
+            checkTeamBlockers: true,
+            overrideReason: opts.focusOverride,
+        })
+        : { enabled: false, reasons: [] };
     let meshCompany = company;
     if (meshCompanyFlag) {
         const resolvedMeshCompany = await ctx.resolveCompany(meshCompanyFlag);
@@ -3767,6 +3915,53 @@ async function runCreate(ctx, opts) {
     }
     let lane = persisted.lane;
     const { admission, validation } = persisted;
+    if (focusAssessment.enabled && opts.focusOverride !== undefined) {
+        const focusOverride = makeFocusOverride({
+            reason: opts.focusOverride,
+            laneId: lane.lane_id,
+            at: ctx.now().toISOString(),
+            storyId: story ?? "",
+        });
+        try {
+            appendProjectFocusOverride(hqRoot, project, company?.slug, focusOverride);
+            lane = casUpdateLane(hqRoot, lane.lane_id, (current) => ({
+                ...appendLaneFocusOverride(current, focusOverride),
+            }));
+        }
+        catch (error) {
+            try {
+                removeProjectFocusOverride(hqRoot, project, company?.slug, focusOverride);
+            }
+            catch (cleanupError) {
+                process.stderr.write(`${JSON.stringify({
+                    event: "lanes.focus_guard.override_rollback_failed",
+                    lane_id: lane.lane_id,
+                    error: cleanupError instanceof Error ? cleanupError.name : "UnknownError",
+                })}\n`);
+            }
+            try {
+                casUpdateLane(hqRoot, lane.lane_id, (current) => ({
+                    ...current,
+                    state: "failed",
+                    queued_reason: undefined,
+                    queued_details: undefined,
+                    admission_reserved_at: undefined,
+                    terminal_reason: "focus_override_persist_failed",
+                }));
+            }
+            catch (markError) {
+                process.stderr.write(`${JSON.stringify({
+                    event: "lanes.focus_guard.lane_fail_mark_failed",
+                    lane_id: lane.lane_id,
+                    error: markError instanceof Error ? markError.name : "UnknownError",
+                })}\n`);
+            }
+            throw new LanesError("focus_override_persist_failed", "Could not persist the focus override; lane launch was refused", {
+                lane_id: lane.lane_id,
+                error: error instanceof Error ? error.name : "UnknownError",
+            });
+        }
+    }
     if (meshCompany) {
         try {
             lane = await ensureLaneThreadRecord(ctx, lane);
@@ -4521,6 +4716,7 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options, behavior =
                 text: options.text,
                 project: options.project,
                 story: options.story,
+                focusOverride: options.focusOverride,
                 account: options.account,
                 model: options.model,
                 effort: options.effort,
@@ -5964,8 +6160,15 @@ async function printGrantResult(ctx, hqRoot, updated, hierarchy) {
  * next `set` or an explicit resume `--effort`/`--worker`.
  */
 async function runSet(ctx, laneId, opts) {
+    if (opts.company !== undefined) {
+        if (opts.model !== undefined || opts.effort !== undefined || opts.reason !== undefined) {
+            throw new LanesError("lane_set_company_exclusive", "--company cannot be combined with --model, --effort, or --reason", { lane_id: laneId });
+        }
+        await runRepairCompany(ctx, laneId, { company: opts.company });
+        return;
+    }
     if (opts.model === undefined && opts.effort === undefined) {
-        throw new LanesError("lane_set_empty", "hq lanes set needs --model or --effort", { lane_id: laneId });
+        throw new LanesError("lane_set_empty", "hq lanes set needs --company, --model, or --effort", { lane_id: laneId });
     }
     const reason = opts.reason?.trim();
     if (opts.reason !== undefined && !reason) {
@@ -7579,7 +7782,7 @@ async function repairCompanyOnOwner(ctx, laneId, opts, emitResult = true) {
         if (current.company !== null) {
             if (sameLaneCompany(current.company, company))
                 return current;
-            throw new LanesError("lane_company_already_set", `Lane ${laneId} already belongs to ${current.company.slug}; company repair only fills missing attribution`, { lane_id: laneId, company: current.company.slug, requested_company: company.slug });
+            throw new LanesError("lane_company_already_set", `Cannot set lane ${laneId} to ${company.slug}: it already belongs to ${current.company.slug}`, { lane_id: laneId, company: current.company.slug, requested_company: company.slug });
         }
         return {
             ...current,
@@ -8885,6 +9088,7 @@ export function registerLanesCommand(parent, deps = {}) {
         casUpdateLane,
         dispatchOutpostLaneCommand,
         dispatchPrimaryLaneMessage,
+        focusGuardAssessment,
         drainHookStatusFor,
         laneIsHostedHere,
         laneWithRecoveredProviderSession,
@@ -8916,6 +9120,7 @@ export function registerLanesCommand(parent, deps = {}) {
         automaticBalanceMoveHistoryReason,
         authorizeFailedResume,
         authorizeResumeProfileRepin,
+        focusGuardAssessment,
         casUpdateLane,
         dispatchOutpostLaneCommand: async (commandCtx, lane, action, options, behavior) => {
             await dispatchOutpostLaneCommand(commandCtx, lane, action, options, behavior);
@@ -9031,6 +9236,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--mesh-company <slug|uid>", "Explicit Work Mesh company for a personal lane; membership is verified")
         .requiredOption("--project <slug>", "HQ project slug")
         .option("--story <id>", "Story id from the project's prd.json")
+        .option("--focus-override <reason>", "Human-approved reason to override the lane focus guard")
         .addOption(noStoryOption)
         .option("--additional-story <id>", "Additional story carried by this lane; repeatable and discouraged when active", collectRepeatable)
         .requiredOption("--brief-file <path>", "Path to the lane brief")
@@ -9093,8 +9299,9 @@ export function registerLanesCommand(parent, deps = {}) {
     }));
     lanes
         .command("set")
-        .description("Change the model or effort a lane uses from its next resume")
+        .description("Change lane settings or bind its missing company attribution")
         .argument("<lane-id>", "Lane id")
+        .option("--company <slug>", "Bind missing company attribution to this lane")
         .option("--model <model>", "Model for the lane's next and later turns")
         .option("--effort <level>", "Effort for the lane's next and later turns")
         .option("--reason <text>", "Why the settings changed; recorded in settings_history")
@@ -9305,6 +9512,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--text-file <path>", "Read message text from a file")
         .option("--project <slug>", "Re-point project attribution; a changed story is named in the resumed prompt")
         .option("--story <id>", "Re-point story attribution; a changed story is named in the resumed prompt")
+        .option("--focus-override <reason>", "Human-approved reason to override the lane focus guard")
         .option("--account <id>", "Move the lane's session to this account of its provider before the message resumes it")
         .option("--model <id>", "Model for the moved lane (with --account only)")
         .option("--effort <level>", "Reasoning effort for the resumed provider turn")
@@ -9361,6 +9569,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--reason <text>", "Required explanation for resuming from failed")
         .option("--project <slug>", "Re-point project attribution; a changed story is named in the resumed prompt")
         .option("--story <id>", "Re-point story attribution; a changed story is named in the resumed prompt")
+        .option("--focus-override <reason>", "Human-approved reason to override the lane focus guard")
         .option("--account <id>", "Move the lane's session to this account of its provider before resuming")
         .option("--model <id>", "Model for the moved lane (with --account only)")
         .option("--effort <level>", "Reasoning effort for the resumed provider turn")

package/dist/commands/meetings.js

@@ -520,7 +520,10 @@ export function registerMeetingsCommand(program) {
             }
             const token = await ensureCognitoToken();
             const companyId = await getCompanyUid(token, companySlug);
-            const recorderPersonUid = await resolveCallerPersonUid(token);
+            // The import endpoint records a person as the recorder (prs_* only).
+            const recorderPersonUid = await resolveCallerPersonUid(token, undefined, {
+                command: "hq meetings import",
+            });
             const res = await vaultApiFetch({
                 token,
                 method: "POST",

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/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);
     }