@indigoai-us/hq-cli 5.345.43 → 5.345.45

package/dist/commands/lanes-shared.d.ts

@@ -3,6 +3,7 @@ import type { OutpostIdentity } from "../lib/lanes/admission-host.js";
 import type { OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
 import type { CpuBusySource } from "../lib/lanes/throttle.js";
 import type { ProbeCommand } from "../lib/lanes/models.js";
+import type { FocusGuardReason } from "../lib/lanes/focus-guard.js";
 import type { KillProcessFn, ProveDetachedFn, SpawnProcessFn } from "../lib/lanes/spawn.js";
 import type { WatcherLoopDeps } from "../lib/lanes/watcher.js";
 import type { RunCompactionFn } from "../lib/lanes/compaction.js";
@@ -38,6 +39,7 @@ export interface LaneMessageOptions {
     textFile?: string;
     project?: string;
     story?: string;
+    focusOverride?: string;
     compact?: boolean;
     account?: string;
     model?: string;
@@ -68,6 +70,7 @@ export interface LaneResumeOptions {
     failedResumeContext?: string;
     project?: string;
     story?: string;
+    focusOverride?: string;
     compact?: boolean;
     account?: string;
     model?: string;
@@ -181,6 +184,16 @@ export interface LaneMessageHandlerDeps {
     casUpdateLane(hqRoot: string, laneId: string, updater: (current: LaneRecord) => LaneRecord): LaneRecord;
     dispatchOutpostLaneCommand(ctx: Ctx, lane: LaneRecord, action: "message" | "resume", options: LaneMessageOptions | LaneResumeOptions, behavior?: OutpostLaneDispatchBehavior): Promise<LaneMessageResponse | undefined>;
     dispatchPrimaryLaneMessage(ctx: Ctx, laneId: string, options: LaneMessageOptions): Promise<LaneMessageResponse | undefined>;
+    focusGuardAssessment(ctx: Ctx, input: {
+        projectId: string;
+        storyIds: readonly string[];
+        company: LaneCompanyRef | null;
+        checkTeamBlockers: boolean;
+        overrideReason?: string;
+    }): Promise<{
+        enabled: boolean;
+        reasons: FocusGuardReason[];
+    }>;
     drainHookStatusFor(ctx: Ctx, lane: LaneRecord): {
         registered: boolean;
         kind: string;
@@ -217,6 +230,16 @@ export interface LaneMessageHandlerDeps {
     withResumeHireAdmission<T>(ctx: Ctx, lane: LaneRecord, fn: () => T, grantContext?: OutpostHireGrantContext): Promise<T>;
 }
 export interface LaneResumeHandlerDeps extends Pick<LaneMessageHandlerDeps, "onLaneWorkerStarted" | "archiveResumeMessage" | "assertLaneRunsHereForAdmission" | "assertLaneRunsHereForOperatorMutation" | "assessLaneAdmission" | "casUpdateLane" | "laneIsHostedHere" | "laneWithRecoveredProviderSession" | "mintMessageId" | "prepareAccountMove" | "persistClaudeAccountSelection" | "printJson" | "recordResumeSetup" | "resolveCommandLane" | "hasPendingQuestionForLane" | "pendingQuestionsForLane" | "cancelFallbackQuestionsForLane" | "resolveResumeProfile" | "reuseProfileRefreshEnabled" | "selectAutomaticClaudeResumeAccount" | "validateResumeProfileModel" | "withResumeHireAdmission"> {
+    focusGuardAssessment(ctx: Ctx, input: {
+        projectId: string;
+        storyIds: readonly string[];
+        company: LaneCompanyRef | null;
+        checkTeamBlockers: boolean;
+        overrideReason?: string;
+    }): Promise<{
+        enabled: boolean;
+        reasons: FocusGuardReason[];
+    }>;
     dispatchOutpostLaneCommand(ctx: Ctx, lane: LaneRecord, action: "resume", options: LaneResumeOptions, behavior?: OutpostLaneDispatchBehavior): Promise<void>;
     authorizeFailedResume(ctx: Ctx, lane: LaneRecord, encodedContext?: string): string;
     authorizeResumeProfileRepin(ctx: Ctx, lane: LaneRecord, profile: ResolvedResumeProfile | undefined, encodedContext: string | undefined): ResumeProfileRepinAuthorization | undefined;
@@ -285,6 +308,8 @@ export interface Ctx {
     readLeadAutopilotFlag: (flag: string, options: {
         company: LaneCompanyRef;
     }) => Promise<boolean>;
+    /** Test seam for the default-off project focus guard flag. */
+    focusGuardEnabled?: (company?: LaneCompanyRef) => Promise<boolean>;
     storyLedgerEnabled: () => boolean;
     isSsmOwnerDispatch: () => boolean;
     withGrantHireLocks: typeof withLaneHireLocks;

package/dist/commands/lanes.d.ts

@@ -11,6 +11,7 @@ import { type LanesMesh, type OutpostRouteIdentity, type SpawnLoginResult } from
 export type { LanesMesh, SpawnLoginResult } from "./lanes-shared.js";
 export { CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG, LANE_OUTPOST_LOAD_BALANCING_FLAG } from "./lanes-shared.js";
 export { resolveAnswerChoice } from "./lanes-questions.js";
+import { type FocusGuardPullRequest } from "../lib/lanes/focus-guard.js";
 import type { OutpostIdentity } from "../lib/lanes/admission-host.js";
 export { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity } from "../lib/lanes/admission-host.js";
 export type { OutpostIdentity } from "../lib/lanes/admission-host.js";
@@ -23,6 +24,7 @@ import type { WatcherLoopDeps } from "../lib/lanes/watcher.js";
 import { type KnownModelsDeps, type ProbeCommand } from "../lib/lanes/models.js";
 import { spawnLaneWorker, type KillProcessFn, type ProveDetachedFn, type SpawnProcessFn } from "../lib/lanes/spawn.js";
 export { spawnLaneWorker };
+export declare function openPullRequestsForProject(hqRoot: string, metadata: Record<string, unknown>): FocusGuardPullRequest[];
 export { questionBodyAbsPath };
 export { MAX_LANE_DEPTH };
 export declare const LANES_RUNS_REL: string;
@@ -98,6 +100,8 @@ export interface LanesCommandDeps {
     lanePlacementEnabled?: (company: LaneCompanyRef | undefined) => Promise<boolean>;
     /** Test seam for the default-off story ledger flag. */
     storyLedgerEnabled?: () => boolean;
+    /** Test seam for the default-off focus guard flag. */
+    focusGuardEnabled?: (company?: LaneCompanyRef) => Promise<boolean>;
     /** Test seam for the SSM-only Outpost owner grant path. */
     isSsmOwnerDispatch?: () => boolean;
     /** Test seam for changing a lane between pre-lock and locked grant reads. */

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_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,
@@ -5939,17 +6135,23 @@ async function applyHireGrant(ctx, laneId, hireGrant, authorization, grantContex
                 assigned_child_grants: allocated,
             });
         }
-        return retryUpdateLane(hqRoot, laneId, "command", (record) => ({
-            ...record,
-            hire_grant: hireGrant,
-        }));
+        return retryUpdateLane(hqRoot, laneId, "command", (record) => isTerminalLaneState(record.state)
+            ? { ...record, hire_grant: 0, released_hire_grant: hireGrant }
+            : { ...record, hire_grant: hireGrant });
     });
     return updated;
 }
 async function printGrantResult(ctx, hqRoot, updated, hierarchy) {
     const finishedChildrenDoNotCount = await hireGrantFinishedChildrenDoNotCount(ctx, updated);
     const fields = laneHireFields(updated, hierarchy ?? loadAllLanes(hqRoot), undefined, finishedChildrenDoNotCount);
-    printJson({ ok: true, action: "grant", lane_id: updated.lane_id, lane: updated, ...fields });
+    printJson({
+        ok: true,
+        action: "grant",
+        lane_id: updated.lane_id,
+        lane: updated,
+        ...fields,
+        hire_grant: updated.released_hire_grant ?? fields.hire_grant,
+    });
 }
 /**
  * `hq lanes set`: change the model or effort a lane uses from its next
@@ -5958,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) {
@@ -7573,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,
@@ -8879,6 +9088,7 @@ export function registerLanesCommand(parent, deps = {}) {
         casUpdateLane,
         dispatchOutpostLaneCommand,
         dispatchPrimaryLaneMessage,
+        focusGuardAssessment,
         drainHookStatusFor,
         laneIsHostedHere,
         laneWithRecoveredProviderSession,
@@ -8910,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);
@@ -8985,6 +9196,10 @@ export function registerLanesCommand(parent, deps = {}) {
         hqRoot: ctx.hqRoot,
         resolveCompany: ctx.resolveCompany,
         now: ctx.now,
+        focusDashboardEnabled: (company) => readLanesRegistryFlagFailOff(LANE_FOCUS_DASHBOARD_FLAG, {
+            company,
+            env: ctx.env,
+        }, readLanesRegistryFlag),
         readQuestionBody: (root, question) => {
             const body = questionHandlers.requireQuestionBody(root, question);
             assertQuestionBodySecretSafe(body);
@@ -9021,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")
@@ -9083,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")
@@ -9295,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")
@@ -9351,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/index.js

@@ -12,6 +12,7 @@ import { CLI_COMMAND_HELP_CATALOG_FLAG } from "./lib/cli-flag-keys.js";
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
 import { installFastPathStreamErrorHandlers } from "./utils/fast-stream-errors.js";
+import { fileURLToPath } from "node:url";
 // Install BEFORE any dispatch so a floated rejection on ANY path (the command
 // graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
 // onUnhandledRejection integration defaults to 'warn' — it captures but does
@@ -20,6 +21,44 @@ import { installFastPathStreamErrorHandlers } from "./utils/fast-stream-errors.j
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
 installFastPathStreamErrorHandlers();
+async function runMainWithInstallTreeRecovery() {
+    let runCli;
+    const { registerCommandsWithRecovery } = await import("./startup-registration.js");
+    try {
+        const result = await registerCommandsWithRecovery({
+            register: async () => {
+                runCli = (await import("./main.js")).runCli;
+            },
+            argv: process.argv,
+            env: process.env,
+            entryPath: fileURLToPath(import.meta.url),
+            stderr: process.stderr,
+        });
+        if (result.reexecStatus !== undefined) {
+            process.exitCode = result.reexecStatus;
+            return;
+        }
+        if (!runCli)
+            throw new Error("HQ CLI startup did not load its command runner");
+        await runCli();
+    }
+    catch (error) {
+        // main.js may be the module that is missing, so the global rejection
+        // reporter cannot import its usual handler to print the recovery remedy.
+        const installTree = await import("./utils/install-tree-torn.js");
+        if (installTree.isInstallTreeTornError(error)) {
+            process.stderr.write(`${installTree.installTreeTornStderrLine(error)}\n`);
+            const sentry = await import("./sentry.js");
+            sentry.initSentry();
+            sentry.Sentry.captureException(error, installTree.installTreeTornCaptureContext(error));
+            sentry.finishSentrySession();
+            await sentry.Sentry.flush(2_000);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}
 function dispatchCliEntry() {
     const versionRequest = isVersionRequest(process.argv);
     const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
@@ -51,8 +90,7 @@ function dispatchCliEntry() {
                 await runCommandHelp(process.argv);
                 return;
             }
-            const { runCli } = await import("./main.js");
-            await runCli();
+            await runMainWithInstallTreeRecovery();
         });
     }
     else if (parsedFastCore?.entry.kind === "native" &&
@@ -73,8 +111,7 @@ function dispatchCliEntry() {
                 await runFastCore(process.argv, parsedFastCore);
             }
             else {
-                const { runCli } = await import("./main.js");
-                await runCli();
+                await runMainWithInstallTreeRecovery();
             }
         });
     }
@@ -88,8 +125,7 @@ function dispatchCliEntry() {
                     return runSecretsEnvFastPath(request);
                 },
                 runCurrent: async () => {
-                    const { runCli } = await import("./main.js");
-                    await runCli();
+                    await runMainWithInstallTreeRecovery();
                 },
             });
         });
@@ -111,7 +147,7 @@ function dispatchCliEntry() {
         // successful command into exit 13 when that teardown promise remains pending.
         // A floated rejection here no longer exits 0 silently: the boundary installed
         // above turns it into a non-zero exit (HQ-CLI-W).
-        void import("./main.js").then(({ runCli }) => runCli());
+        void runMainWithInstallTreeRecovery();
     }
 }
 function isNpmPackageEntry(entryUrl) {

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

@@ -147,8 +147,11 @@ const SAFE_SLOW_PHASES = new Set([
     "child_wait",
     "probe",
     "parse",
+    "no_phase_recorded",
 ]);
-const DEBUG_CONTEXT_PHASES = new Set(SAFE_SLOW_PHASES);
+// This sentinel describes an absent active-phase record, not a phase a hook
+// measures in phase_timings.
+const DEBUG_CONTEXT_PHASES = new Set([...SAFE_SLOW_PHASES].filter((phase) => phase !== "no_phase_recorded"));
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -278,6 +281,10 @@ function safeSlowPhase(value) {
 }
 function resolvedSlowPhase(metadata) {
     const reported = safeSlowPhase(metadata.slow_phase);
+    // The hook explicitly recorded that no phase was active. Do not replace that
+    // finding with a different phase inferred from aggregate timing data.
+    if (reported === "no_phase_recorded")
+        return reported;
     if (reported !== "unknown" && reported !== "other")
         return reported;
     // Which measured master-hook phase consumed the most time when the caller's

package/dist/lib/db/control-plane.d.ts

@@ -130,4 +130,9 @@ export declare class ControlPlaneDbClient {
         appId: string;
     }): Promise<RemoteDestroyAppResponse>;
 }
+export type ControlPlaneHttpError = Error & {
+    status?: number;
+    code?: string;
+    reason?: string;
+};
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/lib/db/control-plane.js

@@ -48,6 +48,8 @@ export class ControlPlaneDbClient {
             err.status = res.status;
             if (typeof payload?.code === "string")
                 err.code = payload.code;
+            if (typeof payload?.reason === "string")
+                err.reason = payload.reason;
             throw err;
         }
         return JSON.parse(text);
@@ -145,12 +147,15 @@ export class ControlPlaneDbClient {
 function httpError(label, status, text) {
     let msg = `${label} failed (${status})`;
     let code;
+    let reason;
     try {
         const j = JSON.parse(text);
         if (typeof j.error === "string")
             msg = j.error;
         if (typeof j.code === "string")
             code = j.code;
+        if (typeof j.reason === "string")
+            reason = j.reason;
     }
     catch {
         /* keep */
@@ -159,6 +164,8 @@ function httpError(label, status, text) {
     err.status = status;
     if (code)
         err.code = code;
+    if (reason)
+        err.reason = reason;
     return err;
 }
 //# sourceMappingURL=control-plane.js.map