@indigoai-us/hq-cli 5.282.0 → 5.284.0

package/dist/commands/lanes.js

@@ -31,13 +31,14 @@ 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 { getOrFetchOutpostSnapshot, OUTPOST_SNAPSHOT_CACHE_TTL_MS, outpostLaneListSnapshotKey, OutpostSnapshotInvocationMemo, } from "../lib/lanes/outpost-snapshot-cache.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";
 export { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity } from "../lib/lanes/admission-host.js";
-import { buildOutpostCapacityCommand, buildOutpostIdentityBackfillCommand, buildOutpostLaneCommand, buildOutpostQuestionListCommand, buildOutpostPickupCommand, createOutpostsClient, dispatchErrorMessage, dispatchOutpostPickup, buildOutpostLaneListCommand, outpostRejectedEffortOption, parseOutpostPickupPayload, PICKUP_WAIT_MS, stageOutpostPayload, } from "../lib/lanes/outpost-dispatch.js";
-import { outpostHireSummaryCacheKey, readOutpostHireSummaryCache, writeOutpostHireSummaryCache, } from "../lib/lanes/outpost-hire-cache.js";
+import { buildOutpostCapacityCommand, buildOutpostIdentityBackfillCommand, buildOutpostLaneCommand, buildOutpostQuestionListCommand, buildOutpostPickupCommand, createOutpostsClient, dispatchErrorMessage, dispatchOutpostPickup, buildOutpostLaneListCommand, REMOTE_LANE_READ_ENV, outpostRejectedEffortOption, parseOutpostPickupPayload, PICKUP_WAIT_MS, stageOutpostPayload, } from "../lib/lanes/outpost-dispatch.js";
+import { outpostHireSummaryCacheKey, LANE_OUTPOST_SNAPSHOT_CACHE_FLAG, OUTPOST_HIRE_SUMMARY_CACHE_TTL_MS, readOutpostHireSummaryCache, readOutpostHireSummaryCacheIncludingStale, writeOutpostHireSummaryCache, } from "../lib/lanes/outpost-hire-cache.js";
 import { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "../lib/lanes/host-capacity.js";
 import { BALANCE_MOVABLE_STATES, selectClaudeAccount, } from "../lib/lanes/claude-balance.js";
 import { parseUserYaml } from "../utils/user-yaml-error.js";
@@ -51,7 +52,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, readWorkerRunResult, resumeCommandRefusal, 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, readAllLanes, 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";
@@ -79,6 +80,7 @@ export const LANE_REMOTE_MIRROR_SYNC_FLAG = "lanes.remote-done-mirror";
 const REMOTE_MIRROR_REFRESH_BATCH_SIZE = 100;
 /** The lane → mesh seam. Defined in lib/lanes/mesh-events.ts; the watcher shares it. */
 export { emitLaneDecisionEvents };
+export { LANE_OUTPOST_SNAPSHOT_CACHE_FLAG };
 function withoutProviderHome(value) {
     if (Array.isArray(value))
         return value.map(withoutProviderHome);
@@ -294,6 +296,8 @@ function resolveDeps(deps = {}) {
         })),
         fetchText: deps.fetchText ?? defaultFetchText,
         lanePlacementEnabled: deps.lanePlacementEnabled ?? defaultLanePlacementEnabled,
+        outpostSnapshotCacheEnabled: deps.outpostSnapshotCacheEnabled ?? (() => readLanesRegistryFlag(LANE_OUTPOST_SNAPSHOT_CACHE_FLAG, { env })),
+        startOutpostLaneSnapshotRefresh: deps.startOutpostLaneSnapshotRefresh ?? ((root) => startOutpostLaneSnapshotRefresh(root, env)),
         storyLedgerEnabled: deps.storyLedgerEnabled ?? laneStoryLedgerEnabled,
         isSsmOwnerDispatch: deps.isSsmOwnerDispatch ?? (() => isSsmRunCommandProcess()),
         withGrantHireLocks: deps.withGrantHireLocks ?? withLaneHireLocks,
@@ -460,7 +464,7 @@ function readQuestionBody(hqRoot, question) {
     return stored.body;
 }
 function loadAllLanes(hqRoot) {
-    return listLaneIds(hqRoot).map((id) => readLane(hqRoot, id));
+    return readAllLanes(hqRoot);
 }
 function laneHireFields(lane, lanes, aliveChildrenByParent) {
     const aliveChildCount = aliveChildrenByParent
@@ -697,7 +701,7 @@ function laneListQueryFlags(query) {
     return [
         ...(query.laneIds?.length ? ["--lane"] : []),
         ...(query.active ? ["--active"] : []),
-        ...(query.hierarchy !== undefined ? ["--hierarchy"] : []),
+        ...(query.hierarchy?.length ? ["--hierarchy"] : []),
         ...(query.snapshot ? ["--snapshot"] : []),
     ];
 }
@@ -726,7 +730,7 @@ async function dispatchOutpostLaneList(ctx, outpostId, query, timeoutSeconds, wa
         waitMs,
     });
 }
-async function fetchOutpostListHireSummaries(ctx, outpostId, lanes) {
+async function fetchOutpostListHireSummaries(ctx, outpostId, lanes, localLanes) {
     const fallback = (error) => new Map(lanes.map((lane) => [lane.lane_id, {
             error: new LanesError(error.error, error.message, {
                 ...error.details,
@@ -734,65 +738,91 @@ async function fetchOutpostListHireSummaries(ctx, outpostId, lanes) {
                 lane_id: lane.lane_id,
             }),
         }]));
-    let dispatched;
+    const summaryReadError = (err) => {
+        if (isLanesError(err)) {
+            if (err.error === "outpost_lane_list_invalid") {
+                return new LanesError("outpost_lane_hire_summary_invalid", err.message, err.details);
+            }
+            if (err.error === "outpost_lane_list_unavailable") {
+                return new LanesError("outpost_lane_hire_summary_unavailable", err.message, err.details);
+            }
+            return err;
+        }
+        return new LanesError("outpost_lane_hire_summary_unavailable", `Could not read hire summaries from Outpost ${outpostId}: ${dispatchErrorMessage(err)}`, { outpost_id: outpostId });
+    };
+    const dispatchOptions = {
+        timeoutSeconds: OUTPOST_HIRE_SUMMARY_TIMEOUT_SECONDS,
+        waitMs: OUTPOST_HIRE_SUMMARY_WAIT_MS,
+    };
+    let ownerLanes;
     try {
-        dispatched = await dispatchOutpostLaneList(ctx, outpostId, { laneIds: lanes.map((lane) => lane.lane_id) }, OUTPOST_HIRE_SUMMARY_TIMEOUT_SECONDS, OUTPOST_HIRE_SUMMARY_WAIT_MS);
+        ownerLanes = await readOutpostLaneRecords(ctx, outpostId, {
+            hierarchy: lanes.map((lane) => lane.lane_id),
+            snapshot: true,
+        }, dispatchOptions);
     }
     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 }));
-    }
-    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 }));
-    }
-    const remote = parseRemoteJson(dispatched.stdout, "Outpost lane hire summary list");
-    if (!remote || remote.ok !== true || remote.action !== "list" || !Array.isArray(remote.lanes)) {
-        return fallback(new LanesError("outpost_lane_hire_summary_invalid", `Outpost ${outpostId} returned an invalid lane list for hire summaries`, { outpost_id: outpostId, command_id: dispatched.commandId }));
+        return fallback(summaryReadError(err));
+    }
+    const requestedOwnerIds = new Set(lanes.map((lane) => lane.lane_id));
+    const returnedOwnerIds = new Set(ownerLanes
+        .filter((lane) => requestedOwnerIds.has(lane.lane_id))
+        .map((lane) => lane.lane_id));
+    const missingOwnerLanes = lanes.filter((lane) => !returnedOwnerIds.has(lane.lane_id));
+    const retryErrors = new Map();
+    if (returnedOwnerIds.size > 0 && missingOwnerLanes.length > 0) {
+        const retries = await mapWithConcurrency(missingOwnerLanes, OUTPOST_HIRE_SUMMARY_CONCURRENCY, async (lane) => {
+            try {
+                const rows = await readOutpostLaneRecords(ctx, outpostId, {
+                    hierarchy: [lane.lane_id],
+                    snapshot: true,
+                }, dispatchOptions);
+                return { laneId: lane.lane_id, rows };
+            }
+            catch (err) {
+                return { laneId: lane.lane_id, error: summaryReadError(err) };
+            }
+        });
+        for (const retry of retries) {
+            if (retry.error)
+                retryErrors.set(retry.laneId, retry.error);
+            else if (retry.rows)
+                ownerLanes.push(...retry.rows);
+        }
     }
+    const hierarchy = mergeOwnerLaneHierarchy(localLanes, ownerLanes);
     const outcomes = new Map();
     for (const lane of lanes) {
-        const matchingRows = remote.lanes.filter((row) => row !== null && typeof row === "object" && !Array.isArray(row) &&
-            row.lane_id === lane.lane_id);
-        if (matchingRows.length === 0) {
-            outcomes.set(lane.lane_id, { error: new LanesError("outpost_lane_hire_summary_missing", `Outpost ${outpostId} did not return lane ${lane.lane_id} in its lane list`, { outpost_id: outpostId, lane_id: lane.lane_id, command_id: dispatched.commandId }) });
+        const matchingLanes = ownerLanes.filter((ownerLane) => ownerLane.lane_id === lane.lane_id);
+        if (matchingLanes.length === 0) {
+            const error = retryErrors.get(lane.lane_id) ?? new LanesError("outpost_lane_hire_summary_missing", `Outpost ${outpostId} did not return lane ${lane.lane_id} in its lane list`, { outpost_id: outpostId, lane_id: lane.lane_id });
+            outcomes.set(lane.lane_id, { error });
             continue;
         }
-        if (matchingRows.length !== 1) {
-            outcomes.set(lane.lane_id, { error: new LanesError("outpost_lane_hire_summary_invalid", `Outpost ${outpostId} returned duplicate lane rows for ${lane.lane_id}`, { outpost_id: outpostId, lane_id: lane.lane_id, command_id: dispatched.commandId }) });
+        if (matchingLanes.length !== 1) {
+            outcomes.set(lane.lane_id, { error: new LanesError("outpost_lane_hire_summary_invalid", `Outpost ${outpostId} returned duplicate lane rows for ${lane.lane_id}`, { outpost_id: outpostId, lane_id: lane.lane_id }) });
             continue;
         }
-        const row = matchingRows[0];
-        try {
-            outcomes.set(lane.lane_id, { fields: validateOwnerLaneHireSummary({
-                    outpostId,
-                    laneId: lane.lane_id,
-                    rawLane: row,
-                    hireGrant: row.hire_grant,
-                    hireAliveChildren: row.hire_alive_children,
-                    hire: row.hire,
-                    hireSummary: row.hire_summary,
-                    commandId: dispatched.commandId,
-                }) });
-        }
-        catch (err) {
-            outcomes.set(lane.lane_id, { error: isLanesError(err)
-                    ? err
-                    : new LanesError("outpost_lane_hire_summary_invalid", `Outpost ${outpostId} returned an invalid hire summary for lane ${lane.lane_id}`, { outpost_id: outpostId, lane_id: lane.lane_id, command_id: dispatched.commandId }) });
+        const ownerLane = matchingLanes[0];
+        if (ownerLane.host.kind !== "outpost" || ownerLane.host.id !== outpostId) {
+            outcomes.set(lane.lane_id, { error: new LanesError("outpost_lane_hire_summary_invalid", `Outpost ${outpostId} returned a lane owned by a different host`, { outpost_id: outpostId, lane_id: lane.lane_id }) });
+            continue;
         }
+        outcomes.set(lane.lane_id, { fields: laneHireFields(ownerLane, hierarchy) });
     }
     return outcomes;
 }
-async function batchOwnerLaneHireFields(ctx, lanes) {
+async function batchOwnerLaneHireFields(ctx, lanes, localLanes, options = {}) {
     const outcomes = new Map();
     const groups = new Map();
     const nowMs = ctx.now().getTime();
-    const cached = readOutpostHireSummaryCache(ctx.hqRoot(), nowMs);
+    const cached = readOutpostHireSummaryCacheIncludingStale(ctx.hqRoot(), nowMs);
     for (const lane of lanes) {
         if (lane.host.kind !== "outpost")
             continue;
         const cachedSummary = cached.get(outpostHireSummaryCacheKey(lane.host.id, lane.lane_id));
-        if (cachedSummary) {
+        if (cachedSummary && !options.forceRefresh &&
+            nowMs - Date.parse(cachedSummary.cached_at) <= OUTPOST_HIRE_SUMMARY_CACHE_TTL_MS) {
             outcomes.set(lane.lane_id, {
                 fields: {
                     hire_grant: cachedSummary.hire_grant,
@@ -807,7 +837,7 @@ async function batchOwnerLaneHireFields(ctx, lanes) {
         group.push(lane);
         groups.set(lane.host.id, group);
     }
-    const fetchedGroups = await mapWithConcurrency([...groups.entries()], OUTPOST_HIRE_SUMMARY_CONCURRENCY, ([outpostId, group]) => fetchOutpostListHireSummaries(ctx, outpostId, group));
+    const fetchedGroups = await mapWithConcurrency([...groups.entries()], OUTPOST_HIRE_SUMMARY_CONCURRENCY, ([outpostId, group]) => fetchOutpostListHireSummaries(ctx, outpostId, group, localLanes));
     const cacheUpdates = [];
     for (const groupOutcomes of fetchedGroups) {
         for (const [laneId, outcome] of groupOutcomes) {
@@ -947,6 +977,9 @@ function laneHostFromCtx(ctx, expectedId) {
     return { kind: "local", id: hostname };
 }
 async function readOutpostCapacity(ctx, outpostId) {
+    return readOutpostSnapshotWithCache(ctx, JSON.stringify(["capacity", outpostId]), (value) => isOutpostCapacitySnapshot(value, outpostId), () => readOutpostCapacityUncached(ctx, outpostId));
+}
+async function readOutpostCapacityUncached(ctx, outpostId) {
     let result;
     try {
         result = await ctx.dispatchOutpostExec({
@@ -980,7 +1013,68 @@ async function readOutpostCapacity(ctx, outpostId) {
     }
     return snapshot;
 }
-async function loadHostCapacitySnapshots(ctx, hqRoot, config = loadLanesConfig(hqRoot)) {
+async function readOutpostSnapshotWithCache(ctx, key, isValue, fetch) {
+    let enabled = false;
+    try {
+        enabled = await ctx.outpostSnapshotCacheEnabled();
+    }
+    catch (err) {
+        process.stderr.write(`lanes snapshot cache flag read failed; using uncached Outpost read: ${dispatchErrorMessage(err)}\n`);
+    }
+    if (!enabled)
+        return fetch();
+    return getOrFetchOutpostSnapshot({ hqRoot: ctx.hqRoot(), key, isValue, fetch });
+}
+function startOutpostLaneSnapshotRefresh(root, env) {
+    let entry;
+    try {
+        const currentEntry = process.argv[1];
+        if (!currentEntry)
+            throw new Error("process.argv[1] is empty");
+        entry = fs.realpathSync(currentEntry);
+    }
+    catch (err) {
+        process.stderr.write(`lanes snapshot refresh could not resolve the running CLI entry: ${dispatchErrorMessage(err)}\n`);
+        return;
+    }
+    try {
+        const child = spawn(process.execPath, [...process.execArgv, entry, "lanes", "list"], {
+            cwd: root,
+            detached: true,
+            stdio: ["ignore", "ignore", "inherit"],
+            env: { ...env, HQ_ROOT: root, HQ_NO_UPDATE_CHECK: "1", HQ_INTERNAL_LANES_REFRESH_REMOTE_SNAPSHOT: "1" },
+        });
+        child.once("error", (err) => {
+            process.stderr.write(`lanes snapshot refresh could not start: ${dispatchErrorMessage(err)}\n`);
+        });
+        child.unref();
+    }
+    catch (err) {
+        process.stderr.write(`lanes snapshot refresh could not start: ${dispatchErrorMessage(err)}\n`);
+    }
+}
+function isLaneRecordArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    try {
+        for (const lane of value)
+            parseLaneRecord(lane);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isOutpostCapacitySnapshot(value, outpostId) {
+    try {
+        const snapshot = parseHostCapacitySnapshot(value);
+        return snapshot.host.kind === "outpost" && snapshot.host.id === outpostId;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadHostCapacitySnapshots(ctx, hqRoot, config = loadLanesConfig(hqRoot), localLanes = loadAllLanes(hqRoot)) {
     const localHost = laneHostFromCtx(ctx);
     let outpostIds;
     try {
@@ -1007,7 +1101,7 @@ async function loadHostCapacitySnapshots(ctx, hqRoot, config = loadLanesConfig(h
         .sort();
     const local = buildHostCapacitySnapshot({
         host: localHost,
-        lanes: loadAllLanes(hqRoot),
+        lanes: localLanes,
         config,
         existsSync: ctx.existsSync,
         hostname: ctx.hostname(),
@@ -1053,25 +1147,30 @@ function normalizedLaneListQuery(query) {
     const laneIds = query.laneIds === undefined
         ? undefined
         : [...new Set(query.laneIds)].sort((a, b) => a.localeCompare(b));
+    const hierarchy = query.hierarchy === undefined
+        ? undefined
+        : [...new Set(query.hierarchy)].sort((a, b) => a.localeCompare(b));
     return {
         ...(laneIds === undefined ? {} : { laneIds }),
         ...(query.active ? { active: true } : {}),
-        ...(query.hierarchy === undefined ? {} : { hierarchy: query.hierarchy }),
+        ...(hierarchy === undefined ? {} : { hierarchy }),
         ...(query.snapshot ? { snapshot: true } : {}),
         ...(query.strictSnapshot ? { strictSnapshot: true } : {}),
     };
 }
-async function readOutpostLaneRecordsUncached(ctx, outpostId, query) {
+async function readOutpostLaneRecordsUncached(ctx, outpostId, query, dispatchOptions = {}) {
     const targetedLookup = query.hierarchy !== undefined || query.laneIds !== undefined;
     const waitMs = targetedLookup ? outpostSingleLaneWaitMs(ctx.env) : CAPACITY_PROBE_TIMEOUT_MS;
+    const dispatchWaitMs = dispatchOptions.waitMs ?? waitMs;
+    const dispatchTimeoutSeconds = dispatchOptions.timeoutSeconds ?? Math.ceil(dispatchWaitMs / 1000);
     let result;
     try {
-        result = await dispatchOutpostLaneList(ctx, outpostId, query, Math.ceil(waitMs / 1000), waitMs);
+        result = await dispatchOutpostLaneList(ctx, outpostId, query, dispatchTimeoutSeconds, dispatchWaitMs);
     }
     catch (err) {
         const message = dispatchErrorMessage(err);
         if (/timed out waiting for outpost pickup/i.test(message)) {
-            throw new LanesError("outpost_lane_list_unavailable", outpostPickupTimeoutMessage(outpostId, waitMs, "reading the requested lane"), { outpost_id: outpostId, wait_ms: waitMs, wait_env: OUTPOST_SINGLE_LANE_WAIT_ENV });
+            throw new LanesError("outpost_lane_list_unavailable", outpostPickupTimeoutMessage(outpostId, dispatchWaitMs, "reading the requested lane"), { outpost_id: outpostId, wait_ms: dispatchWaitMs, wait_env: OUTPOST_SINGLE_LANE_WAIT_ENV });
         }
         if (isLanesError(err))
             throw err;
@@ -1130,24 +1229,14 @@ async function readOutpostLaneRecordsUncached(ctx, outpostId, query) {
     }
     return lanes;
 }
-async function readOutpostLaneRecords(ctx, outpostId, requestedQuery = {}) {
+async function readOutpostLaneRecords(ctx, outpostId, requestedQuery = {}, dispatchOptions = {}) {
     const query = normalizedLaneListQuery(requestedQuery);
-    const queryKey = JSON.stringify(query);
-    let byOutpost = outpostLaneListMemo.get(ctx);
-    if (!byOutpost) {
-        byOutpost = new Map();
-        outpostLaneListMemo.set(ctx, byOutpost);
+    let invocationMemo = outpostLaneListMemo.get(ctx);
+    if (!invocationMemo) {
+        invocationMemo = new OutpostSnapshotInvocationMemo();
+        outpostLaneListMemo.set(ctx, invocationMemo);
     }
-    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;
+    return invocationMemo.getOrCreate(outpostId, query, () => readOutpostSnapshotWithCache(ctx, outpostLaneListSnapshotKey(outpostId, query), isLaneRecordArray, () => readOutpostLaneRecordsUncached(ctx, outpostId, query, dispatchOptions)));
 }
 /** Refresh only primary-created, non-terminal Outpost mirrors in one bounded owner query per Outpost. */
 async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
@@ -1307,6 +1396,16 @@ async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
         if (!(err instanceof LanesError) || err.error !== "lane_not_found")
             throw err;
     }
+    const requestedUlid = laneUlidPart(laneId);
+    if (requestedUlid) {
+        const localMatches = listLaneIds(ctx.hqRoot()).filter((storedId) => laneUlidPart(storedId) === requestedUlid);
+        if (localMatches.length > 1) {
+            throw new LanesError("lane_ulid_ambiguous", `More than one local lane record has ULID ${requestedUlid}`, { lane_id: laneId, matches: localMatches });
+        }
+        const localMatch = localMatches[0];
+        if (localMatch)
+            return { lane: readLane(ctx.hqRoot(), localMatch), remoteOnly: false };
+    }
     const separator = laneId.lastIndexOf("_");
     const hostSuffix = separator < 0 ? "" : laneId.slice(separator + 1);
     if (!hostSuffix || sanitizeHostComponent(hostSuffix) !== hostSuffix) {
@@ -1373,7 +1472,7 @@ async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
         let ownerLanes;
         try {
             ownerLanes = await readOutpostLaneRecords(ctx, outpostId, {
-                hierarchy: laneId,
+                hierarchy: [laneId],
                 snapshot: true,
             });
         }
@@ -1407,6 +1506,13 @@ async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
         ownerHost: match.lane.host,
     };
 }
+function laneUlidPart(laneId) {
+    const separator = laneId.indexOf("_");
+    if (separator !== 26)
+        return undefined;
+    const ulid = laneId.slice(0, separator);
+    return /^[0-9A-HJKMNP-TV-Z]{26}$/i.test(ulid) ? ulid.toUpperCase() : undefined;
+}
 function commandLaneNotFound(laneId, outpostHint, details = {}) {
     const hint = outpostHint
         ? "; pass --outpost <id> to confirm a registered Outpost"
@@ -3802,7 +3908,7 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options, behavior =
     let grantHierarchy;
     if (action === "grant") {
         const hierarchy = mergeOwnerLaneRecords(loadAllLanes(ctx.hqRoot()), await readOutpostLaneRecords(ctx, outpostId, {
-            hierarchy: lane.lane_id,
+            hierarchy: [lane.lane_id],
             snapshot: true,
         }));
         grantHierarchy = hierarchy;
@@ -3811,7 +3917,7 @@ async function dispatchOutpostLaneCommand(ctx, lane, action, options, behavior =
     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, {
-            hierarchy: lane.lane_id,
+            hierarchy: [lane.lane_id],
             snapshot: true,
         }));
         grantContext = createOutpostHireGrantContext(lane, hierarchy, action === "message" ? options.supersededMessageCallerId : undefined, action === "message" ? options.supersededMessageSessionId : undefined);
@@ -4359,7 +4465,7 @@ async function runPickup(ctx, opts) {
         lane: started,
     });
 }
-async function runList(ctx, opts) {
+async function runList(ctx, opts, fastRouteFlags) {
     if (opts.json && opts.human) {
         throw new LanesError("conflicting_output_format", "Use either --json or --human for hq lanes list", { json: true, human: true });
     }
@@ -4369,8 +4475,11 @@ async function runList(ctx, opts) {
         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.hierarchy !== undefined &&
+        (!Array.isArray(opts.hierarchy) || opts.hierarchy.length === 0 ||
+            opts.hierarchy.some((laneId) => typeof laneId !== "string" || !laneId.trim() || laneId.trim() !== laneId) ||
+            new Set(opts.hierarchy).size !== opts.hierarchy.length)) {
+        throw new LanesError("lane_list_hierarchy_invalid", "--hierarchy must be repeated with distinct, non-empty lane ids 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", {});
@@ -4395,7 +4504,7 @@ async function runList(ctx, opts) {
         : loadAllLanes(hqRoot);
     const hierarchyIds = opts.hierarchy === undefined
         ? undefined
-        : new Set(selectOutpostHireGrantHierarchy(opts.hierarchy, laneSource).map((lane) => lane.lane_id));
+        : new Set(opts.hierarchy.flatMap((laneId) => selectOutpostHireGrantHierarchy(laneId, laneSource).map((lane) => lane.lane_id)));
     let selectedLanes = laneSource
         .filter((lane) => {
         if (requestedLaneIds.length > 0 && !requestedIds.has(lane.lane_id))
@@ -4434,9 +4543,12 @@ async function runList(ctx, opts) {
         });
         return;
     }
-    const remoteRefresh = await refreshRemoteLaneMirrors(ctx, hqRoot, laneSource, new Set(selectedLanes
-        .filter((lane) => !isTerminalLaneState(lane.state))
-        .map((lane) => lane.lane_id)));
+    const remoteRead = ctx.env[REMOTE_LANE_READ_ENV] === "1";
+    const remoteRefresh = remoteRead
+        ? { updated: new Map(), unverifiedRemote: new Map() }
+        : await refreshRemoteLaneMirrors(ctx, hqRoot, laneSource, new Set(selectedLanes
+            .filter((lane) => !isTerminalLaneState(lane.state))
+            .map((lane) => lane.lane_id)));
     for (const [laneId, updated] of remoteRefresh.updated) {
         const index = laneSource.findIndex((lane) => lane.lane_id === laneId);
         if (index >= 0)
@@ -4454,7 +4566,8 @@ async function runList(ctx, opts) {
     }
     const ownerEligibleLaneIds = new Set();
     for (const lane of selectedLanes) {
-        if (lane.host.kind !== "outpost" ||
+        if (remoteRead ||
+            lane.host.kind !== "outpost" ||
             isTerminalLaneState(lane.state) ||
             laneRunsHere(lane, host)) {
             continue;
@@ -4462,7 +4575,33 @@ async function runList(ctx, opts) {
         ownerEligibleLaneIds.add(lane.lane_id);
     }
     const ownerLanes = selectedLanes.filter((lane) => ownerEligibleLaneIds.has(lane.lane_id));
+    const refreshRemote = ctx.env.HQ_INTERNAL_LANES_REFRESH_REMOTE_SNAPSHOT === "1";
+    let snapshotCacheEnabled = fastRouteFlags?.snapshotCacheEnabled ?? false;
+    if (fastRouteFlags === undefined &&
+        (refreshRemote || (!opts.fresh && ownerLanes.length > 0))) {
+        try {
+            snapshotCacheEnabled = await ctx.outpostSnapshotCacheEnabled();
+        }
+        catch (err) {
+            process.stderr.write(`lanes snapshot cache flag read failed; using wait-for-remote list: ${dispatchErrorMessage(err)}\n`);
+        }
+    }
+    if (refreshRemote) {
+        if (snapshotCacheEnabled && ownerLanes.length > 0) {
+            const outcomes = await batchOwnerLaneHireFields(ctx, ownerLanes, allLanes, { forceRefresh: true });
+            const failures = [...outcomes.entries()].filter(([, outcome]) => "error" in outcome);
+            if (failures.length > 0) {
+                const firstOutcome = failures[0][1];
+                const firstError = "error" in firstOutcome ? firstOutcome.error : undefined;
+                process.stderr.write(`lanes snapshot refresh failed for ${failures.length} lane(s): ${firstError?.error ?? "outpost_lane_hire_summary_missing"}: ${firstError?.message ?? "owner summary outcome was missing"}\n`);
+                throw firstError ?? new LanesError("outpost_lane_hire_summary_missing", "Background Outpost lane summary refresh returned a missing outcome", { lane_ids: failures.map(([laneId]) => laneId) });
+            }
+        }
+        return;
+    }
     const hireByLane = new Map();
+    const remoteSnapshotMetadata = new Map();
+    let remoteLanesLoading = false;
     for (const lane of selectedLanes) {
         if (!ownerEligibleLaneIds.has(lane.lane_id)) {
             hireByLane.set(lane.lane_id, {
@@ -4472,8 +4611,48 @@ async function runList(ctx, opts) {
             continue;
         }
     }
-    if (ownerLanes.length > 0) {
-        const ownerSummaries = await batchOwnerLaneHireFields(ctx, ownerLanes);
+    if (snapshotCacheEnabled && !opts.fresh && ownerLanes.length > 0) {
+        const nowMs = ctx.now().getTime();
+        const cached = readOutpostHireSummaryCacheIncludingStale(hqRoot, nowMs);
+        let refreshNeeded = false;
+        for (const lane of ownerLanes) {
+            if (lane.host.kind !== "outpost")
+                continue;
+            const summary = cached.get(outpostHireSummaryCacheKey(lane.host.id, lane.lane_id));
+            if (!summary) {
+                hireByLane.set(lane.lane_id, {
+                    ...laneHireFields(lane, allLanes, aliveChildrenByParent),
+                    hire_source: "local",
+                });
+                remoteSnapshotMetadata.set(lane.lane_id, { ageSeconds: null, stale: true, loading: true });
+                refreshNeeded = true;
+                remoteLanesLoading = true;
+                continue;
+            }
+            const ageMs = Math.max(0, nowMs - Date.parse(summary.cached_at));
+            const stale = ageMs >= OUTPOST_SNAPSHOT_CACHE_TTL_MS;
+            hireByLane.set(lane.lane_id, {
+                hire_grant: summary.hire_grant,
+                hire_alive_children: summary.hire_alive_children,
+                hire: summary.hire,
+                hire_summary: summary.hire_summary,
+                hire_source: "owner",
+            });
+            remoteSnapshotMetadata.set(lane.lane_id, {
+                ageSeconds: Math.floor(ageMs / 1_000),
+                stale,
+                loading: stale,
+            });
+            if (stale) {
+                refreshNeeded = true;
+                remoteLanesLoading = true;
+            }
+        }
+        if (refreshNeeded)
+            ctx.startOutpostLaneSnapshotRefresh(hqRoot);
+    }
+    else if (ownerLanes.length > 0) {
+        const ownerSummaries = await batchOwnerLaneHireFields(ctx, ownerLanes, allLanes);
         for (const lane of ownerLanes) {
             const outcome = ownerSummaries.get(lane.lane_id);
             if (outcome && "fields" in outcome) {
@@ -4506,6 +4685,15 @@ async function runList(ctx, opts) {
             ...(remoteQueued
                 ? { state: "remote", remote_state: lane.state, queued_reason: undefined, queued_details: undefined }
                 : {}),
+            ...(remoteSnapshotMetadata.has(lane.lane_id)
+                ? {
+                    remote_snapshot_age_s: remoteSnapshotMetadata.get(lane.lane_id).ageSeconds,
+                    remote_snapshot_stale: remoteSnapshotMetadata.get(lane.lane_id).stale,
+                    ...(remoteSnapshotMetadata.get(lane.lane_id).loading
+                        ? { remote_snapshot_loading: true }
+                        : {}),
+                }
+                : {}),
             overdue: Boolean(lane.overdue) || isOverdue(hqRoot, lane.lane_id, now),
             stalled: Boolean(lane.stalled),
             // Listing is observational. Reconcile owns durable liveness transitions.
@@ -4529,8 +4717,10 @@ async function runList(ctx, opts) {
         };
     });
     const placementCompany = company ?? processLanePlacementCompany(ctx);
-    const host_capacity = await readLanePlacementEnabled(ctx, placementCompany)
-        ? (await loadHostCapacitySnapshots(ctx, hqRoot)).entries
+    const placementEnabled = !remoteRead && (fastRouteFlags?.lanePlacementEnabled ??
+        await readLanePlacementEnabled(ctx, placementCompany));
+    const host_capacity = placementEnabled
+        ? (await loadHostCapacitySnapshots(ctx, hqRoot, undefined, allLanes)).entries
         : undefined;
     const result = {
         ok: true,
@@ -4539,24 +4729,44 @@ async function runList(ctx, opts) {
         ...(remoteRefresh.unverifiedRemote.size > 0
             ? { unverified_remote_lanes: [...remoteRefresh.unverifiedRemote.keys()] }
             : {}),
+        ...(remoteLanesLoading ? { remote_lanes_loading: true } : {}),
         ...(host_capacity !== undefined ? { host_capacity } : {}),
     };
     if (opts.human)
-        console.log(formatLaneListHuman(lanes));
+        console.log(formatLaneListHuman(lanes, remoteLanesLoading));
     else
         printJson(result);
 }
-function formatLaneListHuman(lanes) {
-    if (lanes.length === 0)
-        return "No lanes.";
-    return lanes.map((lane) => {
+/** Keeps the placement-enabled cache-first path on the full lane command graph. */
+export async function runFastCachedLanesListFromEntrypoint() {
+    try {
+        await runList(resolveDeps(), { json: true }, {
+            snapshotCacheEnabled: true,
+            lanePlacementEnabled: true,
+        });
+    }
+    catch (err) {
+        failJson(err);
+    }
+}
+function formatLaneListHuman(lanes, remoteLanesLoading = false) {
+    const rows = lanes.map((lane) => {
         const ids = lane.story_ids;
         const storyLabel = ids.length > 0
             ? "stories: " + ids.join(", ")
             : "no story: " + (lane.no_story_reason ?? "reason not recorded");
+        const snapshotNote = lane.remote_snapshot_stale && lane.remote_snapshot_age_s !== null &&
+            lane.remote_snapshot_age_s !== undefined
+            ? `  remote snapshot stale (${lane.remote_snapshot_age_s}s)`
+            : "";
         return lane.lane_id + "  " + lane.state + "  " + lane.provider + "  " + lane.project_id +
-            "  " + storyLabel;
-    }).join("\n");
+            "  " + storyLabel + snapshotNote;
+    });
+    if (rows.length === 0)
+        rows.push("No lanes.");
+    if (remoteLanesLoading)
+        rows.push("Remote lanes loading.");
+    return rows.join("\n");
 }
 async function runStatus(ctx, opts) {
     if (!ctx.storyLedgerEnabled()) {
@@ -5238,7 +5448,7 @@ async function runGrant(ctx, laneId, opts) {
         await dispatchOutpostLaneCommand(ctx, initial, "grant", { hire: String(hireGrant) });
         return;
     }
-    const updated = await applyHireGrant(ctx, laneId, hireGrant, "senior");
+    const updated = await applyHireGrant(ctx, initial.lane_id, hireGrant, "senior");
     printGrantResult(hqRoot, updated);
 }
 async function runApprove(ctx, laneId, opts) {
@@ -7765,8 +7975,10 @@ export function registerLanesCommand(parent, deps = {}) {
         .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("--hierarchy <lane-id>").hideHelp()
+        .argParser((value, previous = []) => [...previous, value]))
         .addOption(new Option("--snapshot").hideHelp())
+        .option("--fresh", "Wait for fresh remote owner summaries")
         .option("--json", "Emit JSON on stdout (default)")
         .option("--human", "Emit human-readable output")
         .action(wrap(async (opts) => {