@indigoai-us/hq-cli 5.175.0 → 5.177.0

package/dist/lib/lanes/hire-grants.d.ts

@@ -0,0 +1,25 @@
+import { type LaneRecord } from "./types.js";
+export declare const LANE_HIRE_GRANTS_FLAG = "lanes.hire-grants";
+export declare function aliveDirectChildren(lanes: readonly LaneRecord[], parentLaneId: string): LaneRecord[];
+export declare function assignedChildHireGrants(children: readonly LaneRecord[], exceptLaneId?: string): number;
+export interface HireGrantAdmissionSnapshot {
+    parent: LaneRecord;
+    children: LaneRecord[];
+    parentGrant: number;
+    availableChildGrant: number;
+}
+/** Keep the occupancy snapshot and the resulting lane write in one parent-lock scope. */
+export declare function withHireGrantAdmission<T>(hqRoot: string, parentLaneId: string, fn: (snapshot: HireGrantAdmissionSnapshot) => T): T;
+export interface HireGrantBackfillRow {
+    lane_id: string;
+    existing_grant: number | null;
+    alive_children: number;
+    profile_max_concurrent: number | null;
+    allocated_child_grants: number;
+    proposed_grant: number;
+    grant_shortfall: number;
+    action: "set" | "unchanged";
+}
+/** Select alive manager lanes and calculate the non-destructive one-time backfill. */
+export declare function planHireGrantBackfill(lanes: readonly LaneRecord[], profileMaxConcurrent: ReadonlyMap<string, number>): HireGrantBackfillRow[];
+//# sourceMappingURL=hire-grants.d.ts.map

package/dist/lib/lanes/hire-grants.js

@@ -0,0 +1,85 @@
+import { isTerminalLaneState } from "./types.js";
+import { listLaneIds, readLane, withLaneHireLocks } from "./store.js";
+import { LanesError } from "./errors.js";
+export const LANE_HIRE_GRANTS_FLAG = "lanes.hire-grants";
+export function aliveDirectChildren(lanes, parentLaneId) {
+    return lanes.filter((lane) => lane.senior.kind === "lane" &&
+        lane.senior.id === parentLaneId &&
+        !isTerminalLaneState(lane.state));
+}
+export function assignedChildHireGrants(children, exceptLaneId) {
+    return children.reduce((sum, child) => child.lane_id === exceptLaneId ? sum : sum + (child.hire_grant ?? 0), 0);
+}
+/** Keep the occupancy snapshot and the resulting lane write in one parent-lock scope. */
+export function withHireGrantAdmission(hqRoot, parentLaneId, fn) {
+    return withLaneHireLocks(hqRoot, [parentLaneId], () => {
+        const parent = readLane(hqRoot, parentLaneId);
+        const allLanes = listLaneIds(hqRoot).map((id) => readLane(hqRoot, id));
+        const children = aliveDirectChildren(allLanes, parentLaneId);
+        const parentGrant = parent.hire_grant ?? 0;
+        const availableChildGrant = Math.max(0, parentGrant - assignedChildHireGrants(children));
+        return fn({ parent, children, parentGrant, availableChildGrant });
+    });
+}
+/** Select alive manager lanes and calculate the non-destructive one-time backfill. */
+export function planHireGrantBackfill(lanes, profileMaxConcurrent) {
+    const candidates = lanes.filter((lane) => {
+        if (isTerminalLaneState(lane.state))
+            return false;
+        return aliveDirectChildren(lanes, lane.lane_id).length > 0 ||
+            lane.worker_profile === "hq-lanes-manager";
+    });
+    const candidateIds = new Set(candidates.map((lane) => lane.lane_id));
+    const proposed = new Map();
+    const active = new Set();
+    const proposalFor = (lane) => {
+        const cached = proposed.get(lane.lane_id);
+        if (cached !== undefined)
+            return cached;
+        if (active.has(lane.lane_id)) {
+            throw new LanesError("hire_grant_backfill_cycle", `Cannot plan hire grants for cyclic lane hierarchy at ${lane.lane_id}`, { lane_id: lane.lane_id });
+        }
+        active.add(lane.lane_id);
+        const children = aliveDirectChildren(lanes, lane.lane_id);
+        const allocated = children.reduce((sum, child) => {
+            if (child.hire_grant !== undefined)
+                return sum + child.hire_grant;
+            return sum + (candidateIds.has(child.lane_id) ? proposalFor(child) : 0);
+        }, 0);
+        const profileMax = lane.worker_profile
+            ? profileMaxConcurrent.get(lane.worker_profile) ?? 0
+            : 0;
+        const value = lane.hire_grant ?? Math.max(children.length, profileMax, allocated);
+        active.delete(lane.lane_id);
+        proposed.set(lane.lane_id, value);
+        return value;
+    };
+    for (const lane of candidates)
+        proposalFor(lane);
+    return candidates
+        .map((lane) => {
+        const children = aliveDirectChildren(lanes, lane.lane_id);
+        const profileMax = lane.worker_profile
+            ? profileMaxConcurrent.get(lane.worker_profile) ?? null
+            : null;
+        const existing = lane.hire_grant ?? null;
+        const allocatedChildGrants = children.reduce((sum, child) => {
+            if (child.hire_grant !== undefined)
+                return sum + child.hire_grant;
+            return sum + (candidateIds.has(child.lane_id) ? proposalFor(child) : 0);
+        }, 0);
+        const proposedGrant = proposalFor(lane);
+        return {
+            lane_id: lane.lane_id,
+            existing_grant: existing,
+            alive_children: children.length,
+            profile_max_concurrent: profileMax,
+            allocated_child_grants: allocatedChildGrants,
+            proposed_grant: proposedGrant,
+            grant_shortfall: Math.max(0, allocatedChildGrants - proposedGrant),
+            action: existing === null ? "set" : "unchanged",
+        };
+    })
+        .sort((a, b) => a.lane_id.localeCompare(b.lane_id));
+}
+//# sourceMappingURL=hire-grants.js.map

package/dist/lib/lanes/index.d.ts

@@ -3,6 +3,8 @@
  */
 export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
 export { MAX_LANE_DEPTH } from "./constants.js";
+export { assignedChildHireGrants, aliveDirectChildren, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, withHireGrantAdmission } from "./hire-grants.js";
+export type { HireGrantBackfillRow } from "./hire-grants.js";
 export { compareLaneQueueOrder, hasActiveAdmissionReservation, hasActivePendingResume, hasEarlierEligibleQueuedLane, laneOccupiesRunningSlot, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, withLaneAdmissionLock, } from "./admission.js";
 export type { AdmissionCapReason, AdmissionHost } from "./admission.js";
 export { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "./host-capacity.js";
@@ -16,7 +18,7 @@ export { resolveLanesHqRoot } from "./hq-root.js";
 export type { LanesHqRootOpts } from "./hq-root.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
 export type { OutpostDispatchResult, OutpostPickupPayload, } from "./outpost-dispatch.js";
-export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, } from "./store.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
 export type { StoreDeps } from "./store.js";
 export { DEFAULT_LANE_WATCH_INTERVAL_MS, MAX_LANE_WATCH_INTERVAL_MS, MAX_WATCHED_LANES, MAX_WATCH_OUTPUT_LINES, runLaneWatch, } from "./watch.js";
 export type { LaneWatchDeps, LaneWatchResult } from "./watch.js";

package/dist/lib/lanes/index.js

@@ -3,6 +3,7 @@
  */
 export { AccountResolutionError, LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesConfigError, LanesError, WorkerResolutionError, isLaneVersionConflict, isLanesError, } from "./errors.js";
 export { MAX_LANE_DEPTH } from "./constants.js";
+export { assignedChildHireGrants, aliveDirectChildren, LANE_HIRE_GRANTS_FLAG, planHireGrantBackfill, withHireGrantAdmission } from "./hire-grants.js";
 export { compareLaneQueueOrder, hasActiveAdmissionReservation, hasActivePendingResume, hasEarlierEligibleQueuedLane, laneOccupiesRunningSlot, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, withLaneAdmissionLock, } from "./admission.js";
 export { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "./host-capacity.js";
 export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STORY_STATUSES, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";
@@ -10,7 +11,7 @@ export { ACTIVE_LANE_STORY_STATUSES, activeLaneStories, laneStories, laneStory,
 export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFTER_MS, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, providerCompactAfterMs, providerAutoCompactTokens, providerQuotaDefaultHoldMs, DEFAULT_QUOTA_HOLD_MS, writeLanesConfig, } from "./config.js";
 export { resolveLanesHqRoot } from "./hq-root.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
-export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, } from "./store.js";
+export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
 export { DEFAULT_LANE_WATCH_INTERVAL_MS, MAX_LANE_WATCH_INTERVAL_MS, MAX_WATCHED_LANES, MAX_WATCH_OUTPUT_LINES, runLaneWatch, } from "./watch.js";
 export { MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_TASK_OUTPUT_MAX_BYTES, MONITOR_TRANSCRIPT_MAX_BYTES, MONITOR_UNCOVERED_EXIT_CODE, coveredLaneIds, isMonitorTaskLive, monitorReminderText, parseCanonicalWatchCommand, parseMonitorTranscript, readLiveMonitorEvidence, } from "./monitor.js";
 export { IMDS_HOST, IMDS_INSTANCE_ID_URL, IMDS_TIMEOUT_MS, IMDS_TOKEN_URL, defaultReadImdsInstanceId, resolveMachineIdentity, } from "./machine-identity.js";

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -27,13 +27,15 @@ export interface OutpostDispatchResult {
     stderr: string;
 }
 export interface OutpostLaneCommand {
-    action: "message" | "resume" | "stop" | "show";
+    action: "message" | "resume" | "stop" | "show" | "grant";
     laneId: string;
+    hqBinary?: string;
     text?: string;
     project?: string;
     story?: string;
     account?: string;
     model?: string;
+    hire?: string;
     compact?: boolean;
 }
 export interface OutpostExecPort {

package/dist/lib/lanes/outpost-dispatch.js

@@ -73,13 +73,19 @@ export function buildOutpostIdentityBackfillCommand(expectedId) {
 }
 /** Build the same `hq outposts exec` remote command used by lane pickup. */
 export function buildOutpostLaneCommand(input) {
-    const args = ["hq", "lanes", input.action, input.laneId];
+    const args = [
+        input.hqBinary?.trim() || "hq",
+        "lanes",
+        input.action,
+        input.laneId,
+    ];
     for (const [flag, value] of [
         ["--text", input.text],
         ["--project", input.project],
         ["--story", input.story],
         ["--account", input.account],
         ["--model", input.model],
+        ["--hire", input.hire],
     ]) {
         if (value !== undefined)
             args.push(flag, value);

package/dist/lib/lanes/store.d.ts

@@ -53,13 +53,17 @@ export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDep
 export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
 export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
 export declare function createLane(hqRoot: string, init: Omit<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at"> & Partial<Pick<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at">>, deps?: StoreDeps): LaneRecord;
+/** Hierarchy lock: separate from record writes so callers can CAS-write while holding it. */
+export declare function withLaneHireLocks<T>(hqRoot: string, laneIds: readonly string[], fn: () => T, deps?: StoreDeps): T;
 export declare function updateLane(hqRoot: string, laneId: string, expectedVersion: number, writer: LaneWriter, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps): LaneRecord;
 /**
  * Replace the primary copy with a terminal snapshot returned by the Outpost
  * that owns the lane. The owner is authoritative on equal versions; a newer
  * primary version is a conflict and must not be overwritten.
  */
-export declare function syncLaneRecordFromOwner(hqRoot: string, laneId: string, outpostId: string, rawOwnerLane: unknown, deps?: StoreDeps): LaneRecord;
+export declare function syncLaneRecordFromOwner(hqRoot: string, laneId: string, outpostId: string, rawOwnerLane: unknown, deps?: StoreDeps, options?: {
+    allowNonTerminal?: boolean;
+}): LaneRecord;
 /** Compare-and-set with conflict retry. Callers that race a concurrent writer re-read. */
 export declare function retryUpdateLane(hqRoot: string, laneId: string, writer: LaneWriter, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps, attempts?: number): LaneRecord;
 /** Compare-and-set with conflict retry for question records (spec §6.2). */

package/dist/lib/lanes/store.js

@@ -388,6 +388,14 @@ export function parseLaneRecord(raw, filePath) {
     requireInt(raw.version, "version");
     requireInt(raw.depth, "depth");
     requireInt(raw.priority, "priority");
+    if (raw.hire_grant !== undefined &&
+        (typeof raw.hire_grant !== "number" || !Number.isSafeInteger(raw.hire_grant) || raw.hire_grant < 0)) {
+        throw new LaneSchemaError("Expected non-negative safe integer for hire_grant", {
+            path: filePath,
+            field: "hire_grant",
+            value: raw.hire_grant,
+        });
+    }
     requireString(raw.project_id, "project_id");
     requireString(raw.story_id, "story_id");
     requireTimestamp(raw.created_at, "created_at", filePath);
@@ -760,6 +768,7 @@ export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
     const filePath = laneRecordPath(hqRoot, lane_id);
     const record = {
         ...init,
+        hire_grant: init.hire_grant ?? 0,
         schema_version: init.schema_version ?? LANE_SCHEMA_VERSION,
         lane_id,
         version: 1,
@@ -780,6 +789,18 @@ export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
         return record;
     });
 }
+/** Hierarchy lock: separate from record writes so callers can CAS-write while holding it. */
+export function withLaneHireLocks(hqRoot, laneIds, fn, deps = defaultStoreDeps()) {
+    const uniqueIds = [...new Set(laneIds)].sort();
+    const acquire = (index) => {
+        const laneId = uniqueIds[index];
+        if (laneId === undefined)
+            return fn();
+        const lockPath = path.join(lanesStoreRoot(hqRoot), "hire-locks", `${laneId}.json`);
+        return withRecordLock(lockPath, deps, () => acquire(index + 1));
+    };
+    return acquire(0);
+}
 /** Value equality over JSON-shaped record fields; the clone breaks reference identity. */
 function fieldUnchanged(before, after) {
     if (Object.is(before, after))
@@ -815,7 +836,7 @@ export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, dep
  * that owns the lane. The owner is authoritative on equal versions; a newer
  * primary version is a conflict and must not be overwritten.
  */
-export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane, deps = defaultStoreDeps()) {
+export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane, deps = defaultStoreDeps(), options = {}) {
     let ownerLane;
     try {
         ownerLane = parseLaneRecord(rawOwnerLane);
@@ -830,13 +851,14 @@ export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane,
     if (ownerLane.lane_id !== laneId ||
         ownerLane.host.kind !== "outpost" ||
         ownerLane.host.id !== outpostId ||
-        !isTerminalLaneState(ownerLane.state)) {
-        throw new LanesError("outpost_lane_sync_invalid", `Outpost ${outpostId} did not return its terminal record for lane ${laneId}`, {
+        (!options.allowNonTerminal && !isTerminalLaneState(ownerLane.state))) {
+        throw new LanesError("outpost_lane_sync_invalid", `Outpost ${outpostId} did not return an owned lane snapshot for lane ${laneId}`, {
             lane_id: laneId,
             outpost_id: outpostId,
             owner_lane_id: ownerLane.lane_id,
             owner_host: ownerLane.host,
             owner_state: ownerLane.state,
+            require_terminal: !options.allowNonTerminal,
         });
     }
     const filePath = laneRecordPath(hqRoot, laneId);

package/dist/lib/lanes/types.d.ts

@@ -299,6 +299,8 @@ export interface LaneRecord {
     worker_pack?: string;
     /** Personal worker profile id applied to every spawn. */
     worker_profile?: string;
+    /** Maximum number of direct child lanes this lane may keep alive; old records default to 0. */
+    hire_grant?: number;
     /** Content hash of the profile last applied to this lane. */
     worker_profile_hash?: string;
     /** Profile fields intentionally unsupported by the selected provider. */

package/dist/lib/lanes/types.js

@@ -219,6 +219,7 @@ export const LANE_FIELD_WRITERS = {
     schema_version: ["creator"], lane_id: ["creator"], company: ["creator"],
     project_id: ["command"], story_id: ["command"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
     depth: ["command"], senior: ["command"], senior_history: ["command"],
+    hire_grant: ["creator", "command"],
     state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.175.0",
+  "version": "5.177.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {