@indigoai-us/hq-cli 5.345.44 → 5.345.46

package/CHANGELOG.md

@@ -2,7 +2,24 @@
 
 ## [Unreleased]
 
+## [5.345.46] — 2026-10-08
+- Global Claude hooks installed by `hq install --global` now point `HQ_ROOT` and `CLAUDE_PROJECT_DIR` at the HQ root. Sessions outside the HQ folder now load HQ policies, and hook state stays inside HQ instead of creating a `workspace/` folder in the project. To update an existing install, re-run `hq install --global --runtime claude`.
+- `hq install --global --runtime codex` now trusts the HQ hooks it registers in `~/.codex/hooks.json`. Codex skips untrusted hooks, so before this HQ hooks never ran in Codex sessions outside the HQ folder. Only HQ entries are trusted; other hooks in the file are left alone. If Codex cannot be reached, the install still completes and tells you to approve the hooks with `/hooks`.
+- The local HQ MCP server (`hq mcp serve`) now uses your existing HQ sign-in when you have not run `hq mcp login`, so HQ tools work in Claude and Codex outside the HQ folder without a second browser login. This needs the matching hq-pro change that lets the hosted connector accept the HQ sign-in.
+- The HQ background service no longer switches HQ Anywhere off when one re-read of your HQ Anywhere setting times out. It keeps the last value it read for up to 30 minutes; turning the setting off still applies on the next successful read.
+- Sync restart checks now count settled restarts across the full one-hour window and leave out only the unsettled tail.
+- `hq lanes stop` and `hq lanes reparent` now resolve lanes on registered Outposts and dispatch mutations to the owning host, including lanes without a primary mirror.
+
+## [5.345.45] — 2026-10-07
+- A failed automatic CLI update now pauses automatic updates for 24 hours, including for newer releases, instead of retrying on every command. `hq rescue` still updates on request. Processes started by an update can no longer start another install, and update package-manager processes run with Corepack settings that cannot change your default pnpm version.
+
+- Hosted agents can run `hq access`, `hq secrets --personal`, and the `hq db destroy` role check under their own `agt_*` identity instead of failing with "No person entity found". Person-only commands (`hq meetings import`, `hq bot create`) now tell an agent identity that the command is not available to agents.
+- Add a default-off focus guard to lane creation and story-switch resume, with logged, auditable overrides.
+- `hq lanes set <lane> --company <slug>` binds missing company attribution, including on legacy and terminal lane records.
+- Use the per-user local application cache when Windows denies the configured flag snapshot cache.
+
 ## [5.345.44] — 2026-10-07
+- Long-running CLI processes now refresh their package-use lease so desktop updates only reclaim holders whose liveness heartbeat has expired.
 - Quota-exhausted lanes can fail over within their provider, hold with per-account eligibility reasons when none is available, and retry when the earliest quota reset arrives. The default-off `lanes.quota-account-failover` gate controls the new recovery path.
 
 - When a company's plan does not include remote databases, `hq db provision`, `usage`, `sql`, `dump` and `destroy` now show which plan includes them, the $10 per database app price and the upgrade link.

package/dist/command-catalog.generated.d.ts

@@ -11469,6 +11469,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--story <id>";
             readonly description: "Story id from the project's prd.json";
             readonly hidden: false;
+        }, {
+            readonly flags: "--focus-override <reason>";
+            readonly description: "Human-approved reason to override the lane focus guard";
+            readonly hidden: false;
         }, {
             readonly flags: "--no-story <reason>";
             readonly description: "Create a lane without a story and record why";
@@ -11683,7 +11687,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "set";
-        readonly description: "Change the model or effort a lane uses from its next resume";
+        readonly description: "Change lane settings or bind its missing company attribution";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -11697,6 +11701,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Lane id";
         }];
         readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Bind missing company attribution to this lane";
+            readonly hidden: false;
+        }, {
             readonly flags: "--model <model>";
             readonly description: "Model for the lane's next and later turns";
             readonly hidden: false;
@@ -12374,6 +12382,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--story <id>";
             readonly description: "Re-point story attribution; a changed story is named in the resumed prompt";
             readonly hidden: false;
+        }, {
+            readonly flags: "--focus-override <reason>";
+            readonly description: "Human-approved reason to override the lane focus guard";
+            readonly hidden: false;
         }, {
             readonly flags: "--account <id>";
             readonly description: "Move the lane's session to this account of its provider before the message resumes it";
@@ -12497,6 +12509,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--story <id>";
             readonly description: "Re-point story attribution; a changed story is named in the resumed prompt";
             readonly hidden: false;
+        }, {
+            readonly flags: "--focus-override <reason>";
+            readonly description: "Human-approved reason to override the lane focus guard";
+            readonly hidden: false;
         }, {
             readonly flags: "--account <id>";
             readonly description: "Move the lane's session to this account of its provider before resuming";

package/dist/command-catalog.generated.js

@@ -13932,6 +13932,11 @@ export const COMMAND_CATALOG = [
                         "description": "Story id from the project's prd.json",
                         "hidden": false
                     },
+                    {
+                        "flags": "--focus-override <reason>",
+                        "description": "Human-approved reason to override the lane focus guard",
+                        "hidden": false
+                    },
                     {
                         "flags": "--no-story <reason>",
                         "description": "Create a lane without a story and record why",
@@ -14198,7 +14203,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "set",
-                "description": "Change the model or effort a lane uses from its next resume",
+                "description": "Change lane settings or bind its missing company attribution",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -14214,6 +14219,11 @@ export const COMMAND_CATALOG = [
                     }
                 ],
                 "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Bind missing company attribution to this lane",
+                        "hidden": false
+                    },
                     {
                         "flags": "--model <model>",
                         "description": "Model for the lane's next and later turns",
@@ -15045,6 +15055,11 @@ export const COMMAND_CATALOG = [
                         "description": "Re-point story attribution; a changed story is named in the resumed prompt",
                         "hidden": false
                     },
+                    {
+                        "flags": "--focus-override <reason>",
+                        "description": "Human-approved reason to override the lane focus guard",
+                        "hidden": false
+                    },
                     {
                         "flags": "--account <id>",
                         "description": "Move the lane's session to this account of its provider before the message resumes it",
@@ -15197,6 +15212,11 @@ export const COMMAND_CATALOG = [
                         "description": "Re-point story attribution; a changed story is named in the resumed prompt",
                         "hidden": false
                     },
+                    {
+                        "flags": "--focus-override <reason>",
+                        "description": "Human-approved reason to override the lane focus guard",
+                        "hidden": false
+                    },
                     {
                         "flags": "--account <id>",
                         "description": "Move the lane's session to this account of its provider before resuming",

package/dist/commands/access.js

@@ -19,7 +19,7 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { ListObjectsV2Command, } from "@aws-sdk/client-s3";
 import { DEFAULT_HQ_ROOT } from "../utils/cognito-session.js";
-import { getCompanyUid, vaultApiFetch, resolveCallerPersonUid } from "../utils/vault-api.js";
+import { getCompanyUid, vaultApiFetch, resolveCallerUid } from "../utils/vault-api.js";
 import { parseCompanySlugFromPath, resolveBrowseSession, makeCompanyPresignFactory, runGet, } from "./files-browse.js";
 import { listJournals, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { listActiveMembers } from "./members.js";
@@ -705,9 +705,11 @@ export async function runAccessForPath(path, opts) {
         }));
     };
     const members = await listMembers();
-    const callerUid = await resolveCallerPersonUid(token);
-    const me = members.find((m) => m.personUid === callerUid);
-    let requesterEmail = me?.personEmail;
+    const caller = await resolveCallerUid(token);
+    const me = members.find((m) => m.personUid === caller.uid);
+    // An agent has no mailbox and no person entity. `hq files share --with`
+    // accepts its agt_* uid, so the access request names the agent by uid.
+    let requesterEmail = caller.kind === "agent" ? caller.uid : me?.personEmail;
     const requesterName = me?.personName;
     if (!requesterEmail) {
         const claims = peekIdToken(token);

package/dist/commands/bot.js

@@ -504,7 +504,7 @@ export async function runBotCreate(nameArg, opts) {
         throw Object.assign(new Error(`The name ${RESERVED_SETUP_BOT_NAME} is reserved for HQ's setup bot; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
     }
     const token = await ownerToken();
-    const owner = await resolveCallerPersonUid(token);
+    const owner = await resolveCallerPersonUid(token, undefined, { command: "hq bot create" });
     if (!owner)
         throw Object.assign(new Error("Your HQ login has no person entity yet; open the HQ desktop app once, then retry."), { expected: true });
     const api = new BotApi({ token: async () => token });

package/dist/commands/db-destroy.js

@@ -12,16 +12,17 @@ async function defaultCheckRole(deps, companyUid) {
     if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1")
         return "unknown";
     try {
-        const [{ listActiveMembers }, { resolveCallerPersonUid }] = await Promise.all([
+        const [{ listActiveMembers }, { resolveCallerUid }] = await Promise.all([
             import("./members.js"),
             import("../utils/vault-api.js"),
         ]);
         const token = await deps.getAccessToken();
-        const [personUid, members] = await Promise.all([
-            resolveCallerPersonUid(token),
+        // An agent's membership row carries its agt_* uid in the personUid slot.
+        const [caller, members] = await Promise.all([
+            resolveCallerUid(token),
             listActiveMembers(token, companyUid),
         ]);
-        const me = members.find((m) => m.personUid === personUid);
+        const me = members.find((m) => m.personUid === caller.uid);
         if (!me)
             return "unknown";
         return me.role === "owner" || me.role === "admin" ? "allowed" : "denied";

package/dist/commands/install-global.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
+import { type RuntimeHookTrustResult } from '../utils/hook-trust.js';
 import { type HookTarget } from '../lib/install/claude-targets.js';
 export interface GlobalInstallOptions {
     /** HQ checkout to install from (absolute). */
@@ -78,6 +79,8 @@ export interface GlobalCommandOpts {
     /** Root-discovery seams used by command tests and wrappers. */
     home?: string;
     cwd?: string;
+    /** Test seam for trusting the Codex hooks a global install registers. */
+    trustCodexHooks?: (cwd: string, keys: readonly string[]) => Promise<RuntimeHookTrustResult>;
 }
 export declare function resolveInstallRoot(explicit: string | undefined, options?: {
     env?: NodeJS.ProcessEnv;

package/dist/commands/install-global.js

@@ -23,10 +23,11 @@ import { grokConnectorInstructions } from '../lib/install/grok-targets.js';
 import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/registry/registry.js';
 import { readCompaniesManifestMap } from '../lib/work-context/repo-remote.js';
 import { resolveDefaultHqRoot } from '../utils/hq-root-resolver.js';
+import { trustCodexUserHooks } from '../utils/hook-trust.js';
 import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
 import { readDaemonConfig } from '../lib/daemon/config.js';
 import { daemonPaths } from '../lib/daemon/paths.js';
-import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
+import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexHookTrustKeys, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
 import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
 /** True when an hq daemon unit (launchd plist or systemd unit) exists. */
 export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
@@ -1074,8 +1075,9 @@ export async function runInstallGlobal(opts) {
         }
     }
     const install = runtime === 'codex' ? installGlobalCodex : installGlobalClaude;
+    const hqRoot = resolveInstallRoot(opts.hqRoot, { env, cwd: opts.cwd, home: opts.home });
     install({
-        hqRoot: resolveInstallRoot(opts.hqRoot, { env, cwd: opts.cwd, home: opts.home }),
+        hqRoot,
         home: opts.home,
         dryRun: opts.dryRun,
         via: opts.via,
@@ -1084,6 +1086,26 @@ export async function runInstallGlobal(opts) {
         env,
         log: opts.log,
     });
+    if (runtime === 'codex' && !opts.dryRun)
+        await trustInstalledCodexHooks(hqRoot, opts);
+}
+/**
+ * Codex skips untrusted hooks, so the hooks.json entries written above do
+ * nothing until they are trusted. Trust exactly those entries; on failure keep
+ * the install and tell the user how to finish.
+ */
+async function trustInstalledCodexHooks(hqRoot, opts) {
+    const log = opts.log ?? ((l) => console.log(l));
+    const home = resolveEnv({ home: opts.home }).home;
+    const hooksJson = codexTargets(home).hooksJson;
+    const keys = codexHookTrustKeys(JSON.parse(fs.readFileSync(hooksJson, 'utf-8')), hooksJson, hqRoot);
+    const result = await (opts.trustCodexHooks ?? trustCodexUserHooks)(home, keys);
+    if (result.status === 'trusted')
+        log(`  hooks: trusted ${result.trusted} HQ hook(s) in Codex`);
+    else if (result.status === 'failed') {
+        log(`  hooks: Codex hooks are not trusted yet (${result.reason ?? 'unknown error'}), so Codex will skip them.`);
+        log('  To finish, open Codex and approve the HQ hooks with /hooks, or re-run `hq install --global --runtime codex`.');
+    }
 }
 export function registerUninstallCommand(program) {
     program

package/dist/commands/lanes-message.js

@@ -14,6 +14,8 @@ import { laneRunDir, probePidRecord, readPidRecord, readProcStarttime, spawnLane
 import { findRetiredLaneEntry, keepAliveExclusion, keepAliveSupersededBy, LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds } from "../lib/lanes/keep-alive.js";
 import { isTerminalLaneState } from "../lib/lanes/types.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { appendLaneFocusOverride, focusGuardRefusal, makeFocusOverride } from "../lib/lanes/focus-guard.js";
+import { appendProjectFocusOverride, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
 import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
 import { accountMoveSummary, accountRequestKeepsCurrentLane, assertCurrentResumeAccountAvailable, callerMatchesSessionSenior, recordedResumeEffort, resetKeepAliveProgress, resolveResumeEffort } from "./lanes-shared.js";
 export function parseMonitorLaneMessagePayload(input) {
@@ -381,6 +383,28 @@ export function createLaneMessageHandlers(deps) {
         if (opts.story !== undefined && !opts.story.trim()) {
             throw new LanesError("missing_story", "--story must be non-empty", {});
         }
+        if ((opts.project !== undefined || opts.story !== undefined) && ctx.storyLedgerEnabled()) {
+            validateProjectStories(hqRoot, projectId, [storyId], lane.company?.slug);
+        }
+        if (opts.focusOverride !== undefined && !storyId) {
+            throw new LanesError("focus_override_story_required", "--focus-override requires --story", { lane_id: laneId });
+        }
+        const attributionChanged = projectId !== lane.project_id || storyId !== lane.story_id;
+        const focusAssessment = opts.project !== undefined || opts.story !== undefined || opts.focusOverride !== undefined
+            ? await deps.focusGuardAssessment(ctx, {
+                projectId,
+                storyIds: storyId ? [storyId] : [],
+                company: lane.company,
+                checkTeamBlockers: attributionChanged,
+                overrideReason: opts.focusOverride,
+            })
+            : { enabled: false, reasons: [] };
+        if (focusAssessment.enabled && focusAssessment.reasons.length > 0 && opts.focusOverride === undefined) {
+            throw focusGuardRefusal(focusAssessment.reasons);
+        }
+        const focusOverride = focusAssessment.enabled && opts.focusOverride !== undefined
+            ? makeFocusOverride({ reason: opts.focusOverride, laneId, at: ctx.now().toISOString(), storyId: storyId })
+            : undefined;
         const refreshProfileSettings = lane.state === "done" &&
             (projectId !== lane.project_id || storyId !== lane.story_id) &&
             await deps.reuseProfileRefreshEnabled(ctx, lane);
@@ -567,12 +591,6 @@ export function createLaneMessageHandlers(deps) {
             });
             const messageId = mintMessageId();
             const at = ctx.now().toISOString();
-            if (opts.story !== undefined && !opts.story.trim()) {
-                throw new LanesError("missing_story", "--story must be non-empty", {});
-            }
-            if ((opts.project !== undefined || opts.story !== undefined) && ctx.storyLedgerEnabled()) {
-                validateProjectStories(hqRoot, projectId, [storyId], lane.company?.slug);
-            }
             const notice = storySwitchNotice(lane.project_id, lane.story_id, projectId, storyId);
             const promptedText = notice === undefined ? text : `${notice}\n\n${text}`;
             const framedMonitorEvent = opts.monitorEvent === undefined
@@ -602,51 +620,66 @@ export function createLaneMessageHandlers(deps) {
                     sequence: opts.monitorEvent.sequence,
                 }),
             };
-            if (projectId !== lane.project_id || storyId !== lane.story_id) {
-                lane = casUpdateLane(hqRoot, laneId, (current) => {
-                    const already = current.attribution_history.some((entry) => entry.message_id === messageId);
-                    if (already)
-                        return current;
-                    const existingStory = laneStory(current, projectId, storyId);
-                    storySwitchRollback = {
-                        message_id: messageId,
-                        project_id: current.project_id,
-                        story_id: current.story_id,
-                        no_story_reason: current.no_story_reason,
-                        ...(!existingStory ? {
-                            added_story: { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
-                        } : {}),
-                        story_switch_unacknowledged: current.story_switch_unacknowledged,
-                    };
-                    return {
-                        ...current,
-                        project_id: projectId,
-                        story_id: storyId,
-                        no_story_reason: storyId ? undefined : current.no_story_reason,
-                        stories: laneStory(current, projectId, storyId)
-                            ? laneStories(current)
-                            : [
-                                ...laneStories(current),
-                                { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
-                            ],
-                        attribution_history: appendCappedHistory(current.attribution_history, {
-                            project_id: projectId,
-                            story_id: storyId,
-                            message_id: messageId,
-                            at,
-                        }),
-                        story_switch_pending: {
-                            previous_project_id: current.project_id,
-                            previous_story_id: current.story_id,
-                            project_id: projectId,
-                            story_id: storyId,
-                            message_id: messageId,
-                            at,
-                            previous_artifact_keys: artifactIdentityKeys(current.last_envelope?.artifacts),
-                        },
-                        story_switch_unacknowledged: undefined,
-                    };
-                });
+            if (attributionChanged || focusOverride !== undefined) {
+                if (focusOverride !== undefined) {
+                    appendProjectFocusOverride(hqRoot, projectId, lane.company?.slug, focusOverride);
+                }
+                try {
+                    lane = casUpdateLane(hqRoot, laneId, (current) => {
+                        let next = current;
+                        if (attributionChanged) {
+                            const already = current.attribution_history.some((entry) => entry.message_id === messageId);
+                            if (!already) {
+                                const existingStory = laneStory(current, projectId, storyId);
+                                storySwitchRollback = {
+                                    message_id: messageId,
+                                    project_id: current.project_id,
+                                    story_id: current.story_id,
+                                    no_story_reason: current.no_story_reason,
+                                    ...(!existingStory ? {
+                                        added_story: { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
+                                    } : {}),
+                                    story_switch_unacknowledged: current.story_switch_unacknowledged,
+                                };
+                                next = {
+                                    ...current,
+                                    project_id: projectId,
+                                    story_id: storyId,
+                                    no_story_reason: storyId ? undefined : current.no_story_reason,
+                                    stories: laneStory(current, projectId, storyId)
+                                        ? laneStories(current)
+                                        : [
+                                            ...laneStories(current),
+                                            { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
+                                        ],
+                                    attribution_history: appendCappedHistory(current.attribution_history, {
+                                        project_id: projectId,
+                                        story_id: storyId,
+                                        message_id: messageId,
+                                        at,
+                                    }),
+                                    story_switch_pending: {
+                                        previous_project_id: current.project_id,
+                                        previous_story_id: current.story_id,
+                                        project_id: projectId,
+                                        story_id: storyId,
+                                        message_id: messageId,
+                                        at,
+                                        previous_artifact_keys: artifactIdentityKeys(current.last_envelope?.artifacts),
+                                    },
+                                    story_switch_unacknowledged: undefined,
+                                };
+                            }
+                        }
+                        return focusOverride === undefined ? next : appendLaneFocusOverride(next, focusOverride);
+                    });
+                }
+                catch (error) {
+                    if (focusOverride !== undefined) {
+                        removeProjectFocusOverride(hqRoot, projectId, lane.company?.slug, focusOverride);
+                    }
+                    throw error;
+                }
             }
             let resumed = null;
             let move = null;

package/dist/commands/lanes-resume.js

@@ -7,6 +7,8 @@ import { assertNoSecretText } from "../lib/lanes/text-scan.js";
 import { laneStories, laneStory, storyWarning } from "../lib/lanes/stories.js";
 import { artifactIdentityKeys, rollbackStorySwitchAttribution, storySwitchNotice } from "../lib/lanes/story-switch.js";
 import { markSpawnFailure, spawnLaneWorker } from "../lib/lanes/spawn.js";
+import { appendProjectFocusOverride, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
+import { appendLaneFocusOverride, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { accountMoveSummary, accountRequestKeepsCurrentLane, assertCurrentResumeAccountAvailable, hasKeepAliveProgress, recordedResumeEffort, resetKeepAliveProgress, resolveResumeEffort } from "./lanes-shared.js";
 export function createLaneResumeHandlers(deps) {
     const { archiveResumeMessage, assertLaneRunsHereForAdmission, assertLaneRunsHereForOperatorMutation, assessLaneAdmission, automaticBalanceMoveHistoryReason, authorizeFailedResume, authorizeResumeProfileRepin, casUpdateLane, dispatchOutpostLaneCommand, laneIsHostedHere, laneWithRecoveredProviderSession, mintMessageId, persistClaudeAccountSelection, prepareAccountMove, printJson, recordResumeSetup, resolveResumeProfile, selectAutomaticClaudeResumeAccount, validateResumeProfileModel, withResumeHireAdmission } = deps;
@@ -200,10 +202,22 @@ export function createLaneResumeHandlers(deps) {
         if (opts.story !== undefined && !opts.story.trim()) {
             throw new LanesError("missing_story", "--story must be non-empty", {});
         }
+        if (opts.focusOverride !== undefined && !storyId) {
+            throw new LanesError("focus_override_story_required", "--focus-override requires a target story", { lane_id: laneId });
+        }
         if ((opts.project !== undefined || opts.story !== undefined) && ctx.storyLedgerEnabled()) {
             validateProjectStories(hqRoot, projectId, [storyId], lane.company?.slug);
         }
         const attributionChanged = projectId !== lane.project_id || storyId !== lane.story_id;
+        const focusAssessment = opts.story !== undefined || opts.project !== undefined || opts.focusOverride !== undefined
+            ? await deps.focusGuardAssessment(ctx, {
+                projectId,
+                storyIds: storyId ? [storyId] : [],
+                company: lane.company,
+                checkTeamBlockers: attributionChanged,
+                overrideReason: opts.focusOverride,
+            })
+            : { enabled: false, reasons: [] };
         const refreshProfileSettings = lane.state === "done" && attributionChanged &&
             await deps.reuseProfileRefreshEnabled(ctx, lane);
         const refreshWorker = opts.worker ?? (refreshProfileSettings ? lane.worker_profile : undefined);
@@ -370,6 +384,36 @@ export function createLaneResumeHandlers(deps) {
             });
         }
         try {
+            if (focusAssessment.enabled && opts.focusOverride !== undefined) {
+                const focusOverride = makeFocusOverride({
+                    reason: opts.focusOverride,
+                    laneId: lane.lane_id,
+                    at,
+                    storyId,
+                });
+                try {
+                    appendProjectFocusOverride(hqRoot, projectId, lane.company?.slug, focusOverride);
+                    lane = casUpdateLane(hqRoot, laneId, (current) => ({
+                        ...appendLaneFocusOverride(current, focusOverride),
+                    }));
+                }
+                catch (error) {
+                    try {
+                        removeProjectFocusOverride(hqRoot, projectId, lane.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`);
+                    }
+                    throw new LanesError("focus_override_persist_failed", "Could not persist the focus override; lane resume was refused", {
+                        lane_id: lane.lane_id,
+                        error: error instanceof Error ? error.name : "UnknownError",
+                    });
+                }
+            }
             let move = null;
             if (opts.account !== undefined && !keepCurrentAccount) {
                 move = await prepareAccountMove(ctx, lane, {

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. */