@indigoai-us/hq-cli 5.275.0 → 5.277.0

package/dist/commands/lanes.js

@@ -17,8 +17,8 @@ import { createLaneMoveHandlers } from "./lanes-move.js";
 import { createLaneQuestionsHandlers } from "./lanes-questions.js";
 import { createLaneResumeHandlers } from "./lanes-resume.js";
 import { createLaneWatchHandlers } from "./lanes-watch.js";
-import { callerMatchesSessionSenior, assertPlacementEnabled, defaultLanePlacementEnabled, parsePlacementPolicy, processLanePlacementCompany, readLanePlacementEnabled, } from "./lanes-shared.js";
-export { LANE_OUTPOST_LOAD_BALANCING_FLAG } from "./lanes-shared.js";
+import { callerMatchesSessionSenior, assertPlacementEnabled, defaultLanePlacementEnabled, parsePlacementPolicy, processLanePlacementCompany, readClaudeAccountBalanceSignalsEnabled, readLanePlacementEnabled, } 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 { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneKpisCommand } from "./lanes-kpis.js";
@@ -27,10 +27,11 @@ import { registerLaneReportCommands } from "./lanes-report.js";
 import { registerLaneRepoMergeHoldCommand } from "./lanes-hold.js";
 import { registerLaneReviewCommand } from "./lanes-review.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
-import { createOutpostHireGrantContext, parseOutpostHireGrantContext, sameHireGrantSenior, } from "../lib/lanes/hire-grant-dispatch.js";
+import { createOutpostHireGrantContext, parseOutpostHireGrantContext, selectOutpostHireGrantHierarchy, sameHireGrantSenior, } from "../lib/lanes/hire-grant-dispatch.js";
 import { createOutpostProfileRepinContext, parseOutpostProfileRepinContext, } from "../lib/lanes/outpost-profile-repin.js";
 import { createOutpostRegistryWorkerApprovalContext, parseOutpostRegistryWorkerApprovalContext, } from "../lib/lanes/outpost-registry-worker-approval.js";
 import { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity, resolveAdmissionHost, } from "../lib/lanes/admission-host.js";
@@ -50,7 +51,7 @@ import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, lan
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { listLaneReviews } from "../lib/lanes/reviews.js";
 import { effectiveAccountHome } from "../lib/lanes/account-home.js";
-import { AccountResolutionError, compareLaneQueueOrder, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
+import { AccountResolutionError, compareLaneQueueOrder, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, readWorkerRunResult, resumeCommandRefusal, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
 import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
 import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
@@ -450,14 +451,16 @@ function readQuestionBody(hqRoot, question) {
 function loadAllLanes(hqRoot) {
     return listLaneIds(hqRoot).map((id) => readLane(hqRoot, id));
 }
-function laneHireFields(lane, lanes) {
-    const aliveChildren = aliveDirectChildren(lanes, lane.lane_id);
+function laneHireFields(lane, lanes, aliveChildrenByParent) {
+    const aliveChildCount = aliveChildrenByParent
+        ? aliveChildrenByParent.get(lane.lane_id) ?? 0
+        : aliveDirectChildren(lanes, lane.lane_id).length;
     const hireGrant = lane.hire_grant ?? 0;
-    const hireSummary = `hire ${aliveChildren.length}/${hireGrant}`;
+    const hireSummary = `hire ${aliveChildCount}/${hireGrant}`;
     return {
         hire_grant: hireGrant,
-        hire_alive_children: aliveChildren.length,
-        hire: `${aliveChildren.length}/${hireGrant}`,
+        hire_alive_children: aliveChildCount,
+        hire: `${aliveChildCount}/${hireGrant}`,
         hire_summary: hireSummary,
     };
 }
@@ -675,6 +678,39 @@ function validateOwnerLaneHireSummary(input) {
         hire_summary: `hire ${alive}/${grant}`,
     };
 }
+function laneListQueryFlags(query) {
+    return [
+        ...(query.laneIds?.length ? ["--lane"] : []),
+        ...(query.active ? ["--active"] : []),
+        ...(query.hierarchy !== undefined ? ["--hierarchy"] : []),
+        ...(query.snapshot ? ["--snapshot"] : []),
+    ];
+}
+function rejectedLaneListFlag(result, query) {
+    if (result.done === true && result.status === "Success" && result.exitCode === 0)
+        return undefined;
+    const output = `${result.stderr}\n${result.stdout}`;
+    const match = /unknown\s+(?:option|argument)\s+["']?(--[a-z-]+)/i.exec(output);
+    const rejected = match?.[1];
+    return rejected && laneListQueryFlags(query).includes(rejected) ? rejected : undefined;
+}
+async function dispatchOutpostLaneList(ctx, outpostId, query, timeoutSeconds, waitMs) {
+    const hqBinary = outpostCliOverride(ctx, outpostId);
+    const filtered = await ctx.dispatchOutpostExec({
+        outpostId,
+        command: buildOutpostLaneListCommand({ hqBinary, ...query }),
+        timeoutSeconds,
+        waitMs,
+    });
+    if (!rejectedLaneListFlag(filtered, query))
+        return filtered;
+    return ctx.dispatchOutpostExec({
+        outpostId,
+        command: buildOutpostLaneListCommand({ hqBinary }),
+        timeoutSeconds,
+        waitMs,
+    });
+}
 async function fetchOutpostListHireSummaries(ctx, outpostId, lanes) {
     const fallback = (error) => new Map(lanes.map((lane) => [lane.lane_id, {
             error: new LanesError(error.error, error.message, {
@@ -683,28 +719,15 @@ async function fetchOutpostListHireSummaries(ctx, outpostId, lanes) {
                 lane_id: lane.lane_id,
             }),
         }]));
-    let hqBinary;
+    let dispatched;
     try {
-        hqBinary = outpostCliOverride(ctx, outpostId);
+        dispatched = await dispatchOutpostLaneList(ctx, outpostId, { laneIds: lanes.map((lane) => lane.lane_id) }, OUTPOST_HIRE_SUMMARY_TIMEOUT_SECONDS, OUTPOST_HIRE_SUMMARY_WAIT_MS);
     }
     catch (err) {
         if (isLanesError(err))
             return fallback(err);
         return fallback(new LanesError("outpost_lane_hire_summary_unavailable", `Could not read hire summaries from Outpost ${outpostId}: ${dispatchErrorMessage(err)}`, { outpost_id: outpostId }));
     }
-    let dispatched;
-    try {
-        // No filters: the owner list must return every lane requested by this host group.
-        dispatched = await ctx.dispatchOutpostExec({
-            outpostId,
-            command: buildOutpostLaneListCommand({ hqBinary }),
-            timeoutSeconds: OUTPOST_HIRE_SUMMARY_TIMEOUT_SECONDS,
-            waitMs: OUTPOST_HIRE_SUMMARY_WAIT_MS,
-        });
-    }
-    catch (err) {
-        return fallback(new LanesError("outpost_lane_hire_summary_unavailable", `Could not read hire summaries from Outpost ${outpostId}: ${dispatchErrorMessage(err)}`, { outpost_id: outpostId }));
-    }
     if (dispatched.done !== true || dispatched.status !== "Success" || dispatched.exitCode !== 0) {
         return fallback(new LanesError("outpost_lane_hire_summary_unavailable", `Outpost ${outpostId} did not confirm its lane list for hire summaries`, { outpost_id: outpostId, command_id: dispatched.commandId }));
     }
@@ -989,18 +1012,26 @@ async function loadHostCapacitySnapshots(ctx, hqRoot, config = loadLanesConfig(h
         skippedHosts: unavailable.map(({ outpost_id, error }) => ({ outpost_id, error })),
     };
 }
-async function readOutpostLaneRecords(ctx, outpostId) {
-    const hqBinary = outpostCliOverride(ctx, outpostId);
+const outpostLaneListMemo = new WeakMap();
+function normalizedLaneListQuery(query) {
+    const laneIds = query.laneIds === undefined
+        ? undefined
+        : [...new Set(query.laneIds)].sort((a, b) => a.localeCompare(b));
+    return {
+        ...(laneIds === undefined ? {} : { laneIds }),
+        ...(query.active ? { active: true } : {}),
+        ...(query.hierarchy === undefined ? {} : { hierarchy: query.hierarchy }),
+        ...(query.snapshot ? { snapshot: true } : {}),
+    };
+}
+async function readOutpostLaneRecordsUncached(ctx, outpostId, query) {
     let result;
     try {
-        result = await ctx.dispatchOutpostExec({
-            outpostId,
-            command: buildOutpostLaneListCommand({ hqBinary }),
-            timeoutSeconds: CAPACITY_PROBE_TIMEOUT_MS / 1000,
-            waitMs: CAPACITY_PROBE_TIMEOUT_MS,
-        });
+        result = await dispatchOutpostLaneList(ctx, outpostId, query, CAPACITY_PROBE_TIMEOUT_MS / 1000, CAPACITY_PROBE_TIMEOUT_MS);
     }
     catch (err) {
+        if (isLanesError(err))
+            throw err;
         throw new LanesError("outpost_lane_list_unavailable", `Could not read lanes from Outpost ${outpostId}: ${dispatchErrorMessage(err)}`, { outpost_id: outpostId });
     }
     if (result.done !== true || result.status !== "Success" || result.exitCode !== 0) {
@@ -1056,6 +1087,25 @@ async function readOutpostLaneRecords(ctx, outpostId) {
     }
     return lanes;
 }
+async function readOutpostLaneRecords(ctx, outpostId, requestedQuery = {}) {
+    const query = normalizedLaneListQuery(requestedQuery);
+    const queryKey = JSON.stringify(query);
+    let byOutpost = outpostLaneListMemo.get(ctx);
+    if (!byOutpost) {
+        byOutpost = new Map();
+        outpostLaneListMemo.set(ctx, byOutpost);
+    }
+    const existing = byOutpost.get(outpostId);
+    if (existing) {
+        if (existing.queryKey !== queryKey) {
+            throw new LanesError("outpost_lane_list_query_conflict", `Outpost ${outpostId} was already read with a different lane-list query in this invocation`, { outpost_id: outpostId });
+        }
+        return existing.promise;
+    }
+    const promise = readOutpostLaneRecordsUncached(ctx, outpostId, query);
+    byOutpost.set(outpostId, { queryKey, promise });
+    return promise;
+}
 async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
     try {
         return { lane: readLane(ctx.hqRoot(), laneId), remoteOnly: false };
@@ -1098,7 +1148,10 @@ async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
     for (const outpostId of lookupOutpostIds) {
         let ownerLanes;
         try {
-            ownerLanes = await readOutpostLaneRecords(ctx, outpostId);
+            ownerLanes = await readOutpostLaneRecords(ctx, outpostId, {
+                hierarchy: laneId,
+                snapshot: true,
+            });
         }
         catch (err) {
             if (requestedOutpostId !== undefined)
@@ -1214,7 +1267,9 @@ async function loadClaudeBalanceHostSnapshots(ctx, hqRoot, config) {
         let lanes = [];
         let laneListAvailable = false;
         try {
-            lanes = await readOutpostLaneRecords(ctx, id);
+            // Balance can move done and interrupted lanes, so the snapshot must keep
+            // terminal rows; `--active` would drop them.
+            lanes = await readOutpostLaneRecords(ctx, id, { snapshot: true });
             laneListAvailable = true;
         }
         catch (err) {
@@ -2722,6 +2777,8 @@ async function runCreate(ctx, opts) {
             hosts: balanceHostLoad.snapshots,
             targetHost,
             config,
+            recentUsageEnabled: await readClaudeAccountBalanceSignalsEnabled(ctx, company ?? undefined),
+            now: ctx.now(),
             ...(allowedAccounts !== undefined ? { allowedAccounts } : {}),
             ...(explicitBalanceAccount !== undefined ? { explicitAccount: explicitBalanceAccount } : {}),
             unavailableHosts: balanceHostLoad.unavailableHosts,
@@ -2767,6 +2824,8 @@ async function runCreate(ctx, opts) {
                     hosts,
                     targetHost: balanceTargetHost,
                     config,
+                    recentUsageEnabled: await readClaudeAccountBalanceSignalsEnabled(ctx, company ?? undefined),
+                    now: ctx.now(),
                     ...(allowedAccounts !== undefined ? { allowedAccounts } : {}),
                     unavailableHosts: balanceHostLoad.unavailableHosts,
                 });
@@ -3503,13 +3562,19 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options, behavior =
     let grantContext;
     let grantHierarchy;
     if (action === "grant") {
-        const hierarchy = mergeOwnerLaneRecords(loadAllLanes(ctx.hqRoot()), await readOutpostLaneRecords(ctx, outpostId));
+        const hierarchy = mergeOwnerLaneRecords(loadAllLanes(ctx.hqRoot()), await readOutpostLaneRecords(ctx, outpostId, {
+            hierarchy: lane.lane_id,
+            snapshot: true,
+        }));
         grantHierarchy = hierarchy;
         grantContext = createOutpostHireGrantContext(lane, hierarchy);
     }
     else if ((action === "resume" && lane.senior.kind === "lane") ||
         (action === "message" && (lane.senior.kind === "lane" || lane.senior.kind === "session"))) {
-        const hierarchy = mergeOwnerLaneRecords(loadAllLanes(ctx.hqRoot()), await readOutpostLaneRecords(ctx, outpostId));
+        const hierarchy = mergeOwnerLaneRecords(loadAllLanes(ctx.hqRoot()), await readOutpostLaneRecords(ctx, outpostId, {
+            hierarchy: lane.lane_id,
+            snapshot: true,
+        }));
         grantContext = createOutpostHireGrantContext(lane, hierarchy, action === "message" ? options.supersededMessageCallerId : undefined, action === "message" ? options.supersededMessageSessionId : undefined);
     }
     let dispatched;
@@ -4049,6 +4114,21 @@ async function runList(ctx, opts) {
     if (opts.json && opts.human) {
         throw new LanesError("conflicting_output_format", "Use either --json or --human for hq lanes list", { json: true, human: true });
     }
+    const requestedLaneIds = opts.lane ?? [];
+    if (!Array.isArray(requestedLaneIds) ||
+        requestedLaneIds.some((laneId) => typeof laneId !== "string" || !laneId.trim() || laneId.trim() !== laneId) ||
+        new Set(requestedLaneIds).size !== requestedLaneIds.length) {
+        throw new LanesError("lane_list_filter_invalid", "--lane must be repeated with distinct, non-empty lane ids", { lane_ids: requestedLaneIds });
+    }
+    if (opts.hierarchy !== undefined && (!opts.hierarchy.trim() || opts.hierarchy.trim() !== opts.hierarchy)) {
+        throw new LanesError("lane_list_hierarchy_invalid", "--hierarchy requires one non-empty lane id without surrounding whitespace", {});
+    }
+    if (opts.snapshot && (opts.human || opts.company || opts.project || opts.story || opts.state || opts.senior)) {
+        throw new LanesError("lane_list_snapshot_invalid", "--snapshot only supports owner lane filters and JSON output", {});
+    }
+    if (opts.hierarchy !== undefined && !opts.snapshot) {
+        throw new LanesError("lane_list_hierarchy_invalid", "--hierarchy requires --snapshot", {});
+    }
     const hqRoot = ctx.hqRoot();
     const state = opts.state ? parseLaneState(opts.state) : undefined;
     const senior = opts.senior ? parseSeniorRef(opts.senior) : undefined;
@@ -4056,11 +4136,25 @@ async function runList(ctx, opts) {
     if (opts.company) {
         company = await ctx.resolveCompany(opts.company);
     }
-    const now = ctx.now();
-    const host = reconcileHostFromCtx(ctx);
-    const allLanes = loadAllLanes(hqRoot);
-    const selectedLanes = allLanes
+    const requestedIds = new Set(requestedLaneIds);
+    const canReadOnlyRequestedIds = opts.snapshot && requestedLaneIds.length > 0 &&
+        !opts.active && opts.hierarchy === undefined;
+    const laneSource = canReadOnlyRequestedIds
+        ? listLaneIds(hqRoot)
+            .filter((laneId) => requestedIds.has(laneId))
+            .map((laneId) => readLane(hqRoot, laneId))
+        : loadAllLanes(hqRoot);
+    const hierarchyIds = opts.hierarchy === undefined
+        ? undefined
+        : new Set(selectOutpostHireGrantHierarchy(opts.hierarchy, laneSource).map((lane) => lane.lane_id));
+    const selectedLanes = laneSource
         .filter((lane) => {
+        if (requestedLaneIds.length > 0 && !requestedIds.has(lane.lane_id))
+            return false;
+        if (opts.active && isTerminalLaneState(lane.state))
+            return false;
+        if (hierarchyIds && !hierarchyIds.has(lane.lane_id))
+            return false;
         if (state && lane.state !== state)
             return false;
         const carriesFilter = laneStories(lane).some((story) => (!opts.project || story.project_id === opts.project) &&
@@ -4078,6 +4172,19 @@ async function runList(ctx, opts) {
         return true;
     })
         .sort(compareLaneQueueOrder);
+    if (opts.snapshot) {
+        printJson({ ok: true, action: "list", lanes: selectedLanes });
+        return;
+    }
+    const now = ctx.now();
+    const host = reconcileHostFromCtx(ctx);
+    const allLanes = laneSource;
+    const aliveChildrenByParent = new Map();
+    for (const child of allLanes) {
+        if (child.senior.kind !== "lane" || !child.senior.id || isTerminalLaneState(child.state))
+            continue;
+        aliveChildrenByParent.set(child.senior.id, (aliveChildrenByParent.get(child.senior.id) ?? 0) + 1);
+    }
     const ownerEligibleLaneIds = new Set();
     for (const lane of selectedLanes) {
         if (lane.host.kind !== "outpost" ||
@@ -4092,7 +4199,7 @@ async function runList(ctx, opts) {
     for (const lane of selectedLanes) {
         if (!ownerEligibleLaneIds.has(lane.lane_id)) {
             hireByLane.set(lane.lane_id, {
-                ...laneHireFields(lane, allLanes),
+                ...laneHireFields(lane, allLanes, aliveChildrenByParent),
                 hire_source: "local",
             });
             continue;
@@ -4110,12 +4217,14 @@ async function runList(ctx, opts) {
                 ? outcome.error
                 : new LanesError("outpost_lane_hire_summary_missing", `No owner hire summary was returned for lane ${lane.lane_id}`, { lane_id: lane.lane_id, outpost_id: lane.host.id });
             hireByLane.set(lane.lane_id, {
-                ...laneHireFields(lane, allLanes),
+                ...laneHireFields(lane, allLanes, aliveChildrenByParent),
                 hire_source: "local",
                 hire_warning: `${error.error}: ${error.message}`,
             });
         }
     }
+    const livenessBySession = new Map();
+    let livenessDeps;
     const lanes = selectedLanes.map((lane) => {
         const remoteQueued = lane.state === "queued" &&
             lane.host.kind === "outpost" &&
@@ -4134,12 +4243,19 @@ async function runList(ctx, opts) {
             // Listing is observational. Reconcile owns durable liveness transitions.
             senior_lost: lane.state === "running" && lane.senior.kind === "session" && lane.senior.id
                 ? (() => {
-                    const state = sessionLiveness(hqRoot, lane.senior.id, {
+                    const sessionId = lane.senior.id;
+                    const cached = livenessBySession.get(sessionId);
+                    if (cached !== undefined)
+                        return cached;
+                    livenessDeps ??= livenessDepsFromCtx(ctx);
+                    const state = sessionLiveness(hqRoot, sessionId, {
                         nowMs: now.getTime(),
-                        deps: livenessDepsFromCtx(ctx),
+                        deps: livenessDeps,
                         presenceConnected: ctx.presenceConnected,
                     });
-                    return state === null || state === "ended" || state === "lost";
+                    const lost = state === null || state === "ended" || state === "lost";
+                    livenessBySession.set(sessionId, lost);
+                    return lost;
                 })()
                 : false,
         };
@@ -4413,6 +4529,7 @@ async function runShow(ctx, laneId) {
         model: lane.model ?? null,
         effort: lane.effort ?? null,
         effort_source: lane.effort_source ?? null,
+        settings_history: lane.settings_history ?? [],
         terminal_reason: lane.terminal_reason ?? null,
         terminal_details: lane.terminal_details ?? null,
         keep_alive_state: {
@@ -4644,6 +4761,107 @@ function printGrantResult(hqRoot, updated, hierarchy) {
     const fields = laneHireFields(updated, hierarchy ?? loadAllLanes(hqRoot));
     printJson({ ok: true, action: "grant", lane_id: updated.lane_id, lane: updated, ...fields });
 }
+/**
+ * `hq lanes set`: change the model or effort a lane uses from its next
+ * resume. The running turn keeps its values. Both are stored as explicit
+ * (`cli`) choices, so keep-alive and `hq lanes resume` keep them until the
+ * next `set` or an explicit resume `--effort`/`--worker`.
+ */
+async function runSet(ctx, laneId, opts) {
+    if (opts.model === undefined && opts.effort === undefined) {
+        throw new LanesError("lane_set_empty", "hq lanes set needs --model or --effort", { lane_id: laneId });
+    }
+    const reason = opts.reason?.trim();
+    if (opts.reason !== undefined && !reason) {
+        throw new LanesError("lane_set_reason_invalid", "Set reason must not be empty", { lane_id: laneId });
+    }
+    if (reason !== undefined)
+        assertNoSecretText("set reason", reason);
+    const hqRoot = ctx.hqRoot();
+    const lane = readLane(hqRoot, laneId);
+    const callerLaneId = ctx.env.HQ_LANE_ID?.trim() || undefined;
+    const authorization = callerLaneId === laneId
+        ? { authorized: true }
+        : callerSeniorAuthorization(ctx, lane.senior);
+    if (!authorization.authorized) {
+        throw new LanesError("lane_set_unauthorized", appendCallerSeniorReason(`Only lane ${laneId} or its senior ${seniorKey(lane.senior)} may change its model or effort`, authorization), { lane_id: laneId, senior: lane.senior, reason: authorization.reason });
+    }
+    if (lane.host.kind === "outpost" && !laneRunsHereForOperatorMutation(ctx, lane)) {
+        throw new LanesError("set_remote_unsupported", `Lane ${laneId} runs on Outpost ${lane.host.id}; run hq lanes set on that Outpost`, { lane_id: laneId, outpost_id: lane.host.id });
+    }
+    assertLaneRunsHereForOperatorMutation(ctx, lane, "set");
+    if (lane.state === "killed" || lane.state === "cancelled") {
+        throw new LanesError("lane_not_resumable", `Lane ${laneId} is ${lane.state} and will not run again`, { lane_id: laneId, state: lane.state });
+    }
+    const model = opts.model?.trim();
+    if (opts.model !== undefined && !model) {
+        throw new LanesError("empty_model", "--model is empty or whitespace-only", { value: opts.model });
+    }
+    if (model !== undefined) {
+        const config = loadLanesConfig(hqRoot);
+        const account = lane.account === undefined
+            ? undefined
+            : config.providers[lane.provider].accounts[lane.account];
+        if (account === undefined) {
+            throw new AccountResolutionError("unknown_account", `Lane ${laneId} records account ${JSON.stringify(lane.account)} which is not configured for ${lane.provider}`, { provider: lane.provider, account: lane.account ?? "", enabled: [] });
+        }
+        validateLaneModel(lane.provider, model, effectiveAccountHome(account, ctx.hostname()).home, {
+            readFileSync: ctx.readFileSync,
+            probe: ctx.probeProvider,
+            env: ctx.env,
+        });
+    }
+    const effort = parseCliEffort(lane.provider, opts.effort);
+    const at = ctx.now().toISOString();
+    const actor = callerLaneId !== undefined
+        ? `lane:${callerLaneId}`
+        : `session:${sessionIdFromEnv(ctx.env) ?? "unknown"}`;
+    const updated = casUpdateLane(hqRoot, laneId, (current) => {
+        if (current.version !== lane.version) {
+            throw new LanesError("lane_set_conflict", `Lane ${laneId} changed while the settings were checked; run hq lanes set again`, { lane_id: laneId, prepared_version: lane.version, version: current.version });
+        }
+        const entry = { at, actor, ...(reason !== undefined ? { reason } : {}) };
+        const next = { ...current };
+        const pending = { ...(current.pending_settings ?? {}) };
+        // A running turn keeps the model and effort it launched with, because the
+        // watcher classifies that turn's exit (including model quota) by them.
+        const deferred = current.state === "running";
+        if (model !== undefined) {
+            entry.model = { from: pending.model ?? current.model ?? null, to: model };
+            if (deferred) {
+                pending.model = model;
+            }
+            else {
+                next.model = model;
+                next.model_source = "cli";
+                delete pending.model;
+            }
+        }
+        if (effort !== undefined) {
+            entry.effort = { from: pending.effort ?? current.effort ?? null, to: effort };
+            if (deferred) {
+                pending.effort = effort;
+            }
+            else {
+                next.effort = effort;
+                next.effort_source = "cli";
+                delete pending.effort;
+            }
+        }
+        next.pending_settings = Object.keys(pending).length > 0 ? pending : undefined;
+        next.settings_history = appendCappedHistory(current.settings_history ?? [], entry);
+        return next;
+    });
+    printJson({
+        ok: true,
+        action: "set",
+        lane: updated,
+        model: updated.pending_settings?.model ?? updated.model ?? null,
+        effort: updated.pending_settings?.effort ?? updated.effort ?? null,
+        pending: updated.pending_settings !== undefined,
+        applies: "next_resume",
+    });
+}
 async function runKeepAlive(ctx, laneId, opts) {
     if (opts.standing && !opts.on) {
         throw new LanesError("keep_alive_standing_requires_on", "Pass --standing together with --on", { lane_id: laneId });
@@ -5159,7 +5377,8 @@ function recordResumeSetup(ctx, lane, input) {
         input.effort === undefined &&
         input.keepAlive === undefined &&
         input.cliModel === undefined &&
-        input.meshCompany === undefined)
+        input.meshCompany === undefined &&
+        lane.keep_alive_blocked_reason !== "terminal_state")
         return lane;
     return casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => {
         if (current.version !== lane.version) {
@@ -5169,6 +5388,10 @@ function recordResumeSetup(ctx, lane, input) {
             assertResumeProfileRepinStillAuthorized(ctx, current, input.profileRepin);
         }
         const next = { ...current };
+        // An operator resume takes the lane out of the terminal state reconcile
+        // recorded, so keep-alive may continue it again after this turn.
+        if (next.keep_alive_blocked_reason === "terminal_state")
+            next.keep_alive_blocked_reason = undefined;
         applyResumeProfileAndEffort(current, next, { ...input, at: ctx.now().toISOString() });
         if (input.cliModel !== undefined) {
             next.model = input.cliModel.trim();
@@ -5449,6 +5672,8 @@ async function selectAutomaticClaudeResumeAccount(ctx, lane, workerProfile, opti
         hosts: balanceHosts.snapshots,
         targetHost: lane.host,
         config,
+        recentUsageEnabled: await readClaudeAccountBalanceSignalsEnabled(ctx, lane.company ?? undefined),
+        now: ctx.now(),
         ...(!repairUnavailableAccount && allowedAccounts !== undefined ? { allowedAccounts } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(recordedModelAccount !== undefined ? { recordedModelAccount } : {}),
@@ -6343,6 +6568,8 @@ async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false) {
             ok: true,
             action: "stop",
             lane: updated,
+            terminal: true,
+            resumable: false,
             cancelled_questions: cancelledQuestions,
             outpost_id: outpostId,
             outpost_command_id: commandId,
@@ -6364,6 +6591,9 @@ async function runStop(ctx, laneId, reason, quiet = false) {
         assertNoSecretText("stop reason", operatorReason);
     const hqRoot = ctx.hqRoot();
     const lane = readLane(hqRoot, laneId);
+    if (!quiet && lane.state !== "queued" && !isTerminalLaneState(lane.state)) {
+        process.stderr.write(stopTerminalWarning(laneId));
+    }
     if (lane.host.kind === "outpost" && !laneRunsHereForOperatorMutation(ctx, lane)) {
         await dispatchOutpostLaneStop(ctx, lane, operatorReason, quiet);
         return;
@@ -6408,9 +6638,108 @@ async function runStop(ctx, laneId, reason, quiet = false) {
             ok: true,
             action: "stop",
             lane: updated,
+            terminal: true,
+            resumable: false,
             cancelled_questions: cancelled.map((q) => q.question_id),
         });
 }
+/** Stderr notice that `stop` ends a lane for good, naming the resumable path. */
+export function stopTerminalWarning(laneId) {
+    return `hq lanes: warning: stop kills lane ${laneId} and it cannot be resumed. ` +
+        `To pause it and keep it resumable, use hq lanes interrupt ${laneId}.\n`;
+}
+/**
+ * Stop a running lane's worker and leave it `interrupted`, keeping the provider
+ * session so `hq lanes resume` continues it. Keep-alive resumes only
+ * `exited_with_partial_output` interruptions, so it leaves this lane alone.
+ */
+async function runInterrupt(ctx, laneId, reason) {
+    const operatorReason = reason?.trim();
+    if (reason !== undefined && !operatorReason) {
+        throw new LanesError("lane_interrupt_reason_invalid", "Interrupt reason must not be empty", {});
+    }
+    if (operatorReason !== undefined)
+        assertNoSecretText("interrupt reason", operatorReason);
+    const hqRoot = ctx.hqRoot();
+    const lane = readLane(hqRoot, laneId);
+    if (lane.host.kind === "outpost" && !laneRunsHereForOperatorMutation(ctx, lane)) {
+        throw new LanesError("interrupt_remote_unsupported", `Lane ${laneId} runs on Outpost ${lane.host.id}; run hq lanes interrupt on that Outpost`, { lane_id: laneId, outpost_id: lane.host.id });
+    }
+    assertLaneRunsHereForOperatorMutation(ctx, lane, "interrupt");
+    const assertInterruptible = (current) => {
+        if (current.state !== "running") {
+            throw new LanesError("lane_not_running", current.state === "queued"
+                ? `Lane ${laneId} is queued and has no running turn; use hq lanes stop to cancel it`
+                : `Lane ${laneId} is ${current.state}; only a running lane can be interrupted`, { lane_id: laneId, state: current.state });
+        }
+    };
+    assertInterruptible(lane);
+    // Hold the provider's admission lock across the state change, the process
+    // stop and the session write, so a resume cannot spawn a second worker on
+    // the same session while the old one is still exiting.
+    const updated = await withLaneAdmissionLock(hqRoot, lane.provider, async () => {
+        const at = ctx.now().toISOString();
+        const interrupted = casUpdateLane(hqRoot, laneId, (current) => {
+            assertLaneRunsHereForOperatorMutation(ctx, current, "interrupt");
+            assertInterruptible(current);
+            return {
+                ...current,
+                state: "interrupted",
+                queued_reason: undefined,
+                interrupted_at: at,
+                terminal_reason: "operator_interrupt",
+                ...(operatorReason === undefined ? {} : {
+                    stop_history: [
+                        ...(current.stop_history ?? []),
+                        { at, reason: operatorReason },
+                    ],
+                }),
+            };
+        });
+        stopLaneProcesses(hqRoot, laneId, {
+            killProcess: ctx.killProcess,
+            isAlive: ctx.isAlive,
+            sleepMs: ctx.stopSleepMs,
+        });
+        return persistInterruptedSession(hqRoot, interrupted);
+    }, ctx.sleep);
+    await emitLaneTerminalStateSoft(ctx, updated);
+    const resumable = resumeCommandRefusal(laneWithRecoveredProviderSession(hqRoot, updated)) === null;
+    if (!resumable)
+        process.stderr.write(interruptNotResumableWarning(laneId));
+    printJson({
+        ok: true,
+        action: "interrupt",
+        lane: updated,
+        terminal: false,
+        resumable,
+    });
+}
+/**
+ * The watcher skips lanes that are already terminal, so it never records the
+ * session id of a turn the operator interrupted. Read it from this run's
+ * worker output here; a lane with no session id cannot be resumed.
+ */
+function persistInterruptedSession(hqRoot, lane) {
+    const runDir = laneRunDir(hqRoot, lane.lane_id);
+    let sessionId = null;
+    try {
+        sessionId = readWorkerRunResult(runDir, lane.provider, readSpawnManifest(runDir).worker_out_offset ?? 0)?.session_id ?? null;
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: could not read the session id of interrupted lane ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    if (sessionId === null || sessionId === lane.provider_session_id)
+        return lane;
+    return casUpdateLane(hqRoot, lane.lane_id, (current) => current.state !== "interrupted"
+        ? current
+        : { ...current, provider_session_id: sessionId, provider_session_id_absent: undefined });
+}
+/** Stderr notice when an interrupted lane has no session to resume from. */
+export function interruptNotResumableWarning(laneId) {
+    return `hq lanes: warning: lane ${laneId} was interrupted before its provider reported a session id, ` +
+        `so hq lanes resume cannot continue it. Start a new lane for the remaining work.\n`;
+}
 async function runAsk(ctx, opts) {
     const hqRoot = ctx.hqRoot();
     const laneId = ctx.env.HQ_LANE_ID?.trim();
@@ -6739,6 +7068,7 @@ export function registerLanesCommand(parent, deps = {}) {
         parseRemoteJson,
         prepareAccountMove,
         printJson,
+        readClaudeAccountBalanceSignalsEnabled,
         reconcileHostFromCtx,
         resolveCallerPath,
     });
@@ -6911,7 +7241,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--placement <mode>", "local | auto | outpost:<id>")
         .option("--default-placement <mode>", "Default placement for lanes launched by this lane: local | auto | outpost:<id>")
         .action(wrap(async (opts) => {
-        await runCreate(ctx, opts);
+        await withCliFeatureUsed("lane_create", () => runCreate(ctx, opts));
     }));
     lanes
         .command("approve-target", { hidden: true })
@@ -6947,6 +7277,17 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (laneId, opts) => {
         await runKeepAlive(ctx, laneId, opts);
     }));
+    lanes
+        .command("set")
+        .description("Change the model or effort a lane uses from its next resume")
+        .argument("<lane-id>", "Lane id")
+        .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")
+        .option("--json", "Emit JSON on stdout (default)")
+        .action(wrap(async (laneId, opts) => {
+        await runSet(ctx, laneId, opts);
+    }));
     lanes
         .command("grant")
         .description("Set a lane's alive child-lane grant as its senior")
@@ -6972,6 +7313,10 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--story <id>", "Filter by story")
         .option("--state <state>", `Filter by state (${LANE_STATES.join("|")})`)
         .option("--senior <ref>", "Filter by senior ref")
+        .option("--lane <id>", "Filter by lane id (repeatable)", (value, previous = []) => [...previous, value], [])
+        .option("--active", "Include only lanes that are not terminal")
+        .addOption(new Option("--hierarchy <lane-id>").hideHelp())
+        .addOption(new Option("--snapshot").hideHelp())
         .option("--json", "Emit JSON on stdout (default)")
         .option("--human", "Emit human-readable output")
         .action(wrap(async (opts) => {
@@ -7215,7 +7560,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--mesh-company <slug>", "Attach Work Mesh attribution after verifying company membership")
         .option("--no-compact", "Skip the resume-time compaction check for this resume")
         .action(wrap(async (laneId, opts) => {
-        await resumeHandlers.runResume(ctx, laneId, opts);
+        await withCliFeatureUsed("lane_resume", () => resumeHandlers.runResume(ctx, laneId, opts));
     }));
     lanes
         .command("reparent")
@@ -7236,12 +7581,20 @@ export function registerLanesCommand(parent, deps = {}) {
     }));
     lanes
         .command("stop")
-        .description("Cancel a queued lane or kill a running one")
+        .description("Cancel a queued lane or kill a running one (terminal; use interrupt to keep it resumable)")
         .argument("<lane-id>", "Lane id")
         .option("--reason <text>", "Record the reason in the lane's terminal history")
         .action(wrap(async (laneId, options) => {
         await runStop(ctx, laneId, options.reason);
     }));
+    lanes
+        .command("interrupt")
+        .description("Stop a running lane's turn and keep it resumable with hq lanes resume")
+        .argument("<lane-id>", "Lane id")
+        .option("--reason <text>", "Record the reason in the lane's stop history")
+        .action(wrap(async (laneId, options) => {
+        await runInterrupt(ctx, laneId, options.reason);
+    }));
     lanes
         .command("approve")
         .description("Record senior approval for a registry worker checkpoint")