@indigoai-us/hq-cli 5.274.0 → 5.275.0

package/dist/lib/daemon/supervisor.js

@@ -13,7 +13,11 @@
  * - restart/trigger/stop requests from the CLI are polled and applied; a
  *   request for a unit that is not planned yet re-reads the plan first;
  * - stop() sends SIGTERM to every child, escalates to SIGKILL after
- *   STOP_ESCALATION_MS, and resolves once every child has exited.
+ *   STOP_ESCALATION_MS, and resolves once every child has exited;
+ * - release() instead leaves every child running and reports the long-running
+ *   ones, so the next daemon can adopt them (`adopt`). Adopted units whose
+ *   command is unchanged keep running; changed ones are replaced one at a
+ *   time, draining first when the unit has a drain signal.
  *
  * Processes, time, and state output are injected; `run.ts` wires the real ones.
  */
@@ -21,11 +25,24 @@ export const BACKOFF_BASE_MS = 1_000;
 export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
+/** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
+export const HANDOFF_STAGGER_MS = 15_000;
+/** How long a draining unit may take to finish its work before it gets SIGTERM. */
+export const HANDOFF_DRAIN_MAX_MS = 15 * 60_000;
 export function backoffMs(attempt) {
     return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
 }
-function planKey(plan) {
-    return JSON.stringify([plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env]);
+/**
+ * What a unit's process was started from; a unit whose key changes is
+ * restarted. The CLI version counts only for `hq` commands, so a CLI update
+ * leaves hq-cloud runners, other programs, and units marked
+ * `keepAcrossCliUpdates` running.
+ */
+export function planKey(plan, cliVersion) {
+    const fields = [plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env];
+    if (cliVersion !== undefined && plan.command?.type === "hq" && !plan.keepAcrossCliUpdates)
+        fields.push(cliVersion);
+    return JSON.stringify(fields);
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -42,6 +59,10 @@ export function createSupervisor(deps) {
     let started = false;
     let reconcileTimer;
     let requestTimer;
+    /** Adopted units whose command changed, replaced one at a time. */
+    const handoffQueue = [];
+    let handoffActive = false;
+    let handoffTimer;
     /** Every child process not yet known to have exited, including ones the slots have let go of. */
     const live = new Set();
     let drained = null;
@@ -75,8 +96,20 @@ export function createSupervisor(deps) {
         delete slot.state.pid;
         delete slot.state.nextRunAt;
     };
-    /** Stop the slot's child (if any), then run `then` once it has exited. */
-    const terminate = (slot, then) => {
+    const signalChild = (slot, child, signal) => {
+        try {
+            child.kill(signal);
+        }
+        catch (err) {
+            deps.log("error", `could not send ${signal} to ${slot.plan.id}: ${errorMessage(err)}`);
+        }
+    };
+    /**
+     * Stop the slot's child (if any), then run `then` once it has exited. With
+     * `drain`, a unit that has a drain signal gets it first and SIGTERM only
+     * after HANDOFF_DRAIN_MAX_MS; SIGKILL follows SIGTERM after STOP_ESCALATION_MS.
+     */
+    const terminate = (slot, then, drain = false) => {
         clearTimer(slot);
         const child = slot.child;
         if (!child) {
@@ -85,24 +118,32 @@ export function createSupervisor(deps) {
         }
         slot.expectingExit = true;
         slot.afterExit = then;
-        slot.killTimer = setT(() => {
-            slot.killTimer = undefined;
-            if (slot.child === child) {
+        if (slot.killTimer !== undefined)
+            clearT(slot.killTimer);
+        const escalateToKill = () => {
+            slot.killTimer = setT(() => {
+                slot.killTimer = undefined;
+                if (slot.child !== child)
+                    return;
                 deps.log("warn", `${slot.plan.id} ignored SIGTERM; sending SIGKILL`);
-                try {
-                    child.kill("SIGKILL");
-                }
-                catch (err) {
-                    deps.log("error", `could not SIGKILL ${slot.plan.id}: ${errorMessage(err)}`);
-                }
-            }
-        }, STOP_ESCALATION_MS);
-        try {
-            child.kill("SIGTERM");
-        }
-        catch (err) {
-            deps.log("error", `could not stop ${slot.plan.id}: ${errorMessage(err)}`);
+                signalChild(slot, child, "SIGKILL");
+            }, STOP_ESCALATION_MS);
+        };
+        const drainSignal = drain ? slot.plan.drainSignal : undefined;
+        if (drainSignal) {
+            slot.killTimer = setT(() => {
+                slot.killTimer = undefined;
+                if (slot.child !== child)
+                    return;
+                deps.log("warn", `${slot.plan.id} did not finish draining; sending SIGTERM`);
+                escalateToKill();
+                signalChild(slot, child, "SIGTERM");
+            }, HANDOFF_DRAIN_MAX_MS);
+            signalChild(slot, child, drainSignal);
+            return;
         }
+        escalateToKill();
+        signalChild(slot, child, "SIGTERM");
     };
     const scheduleRestart = (slot) => {
         if (stopped)
@@ -198,6 +239,7 @@ export function createSupervisor(deps) {
             return;
         }
         slot.child = child;
+        slot.childKey = slot.key;
         slot.childStartedAt = now();
         slot.state.status = "running";
         slot.state.startedAt = slot.childStartedAt;
@@ -263,6 +305,7 @@ export function createSupervisor(deps) {
             return;
         }
         slot.child = child;
+        slot.childKey = slot.key;
         slot.childStartedAt = now();
         slot.state.status = "running";
         delete slot.state.reason;
@@ -290,7 +333,7 @@ export function createSupervisor(deps) {
     };
     const newSlot = (plan) => ({
         plan,
-        key: planKey(plan),
+        key: planKey(plan, deps.cliVersion),
         attempts: 0,
         expectingExit: false,
         busy: false,
@@ -334,7 +377,9 @@ export function createSupervisor(deps) {
                 continue;
             }
             next.set(plan.id, existing);
-            const key = planKey(plan);
+            const adopted = existing.adopted === true;
+            existing.adopted = false;
+            const key = planKey(plan, deps.cliVersion);
             const wasBlocked = existing.plan.blocked !== undefined;
             const changed = key !== existing.key;
             existing.plan = plan;
@@ -358,6 +403,10 @@ export function createSupervisor(deps) {
                 else
                     activate(existing);
             }
+            else if (changed && adopted && existing.child) {
+                deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
+                handoffQueue.push(existing);
+            }
             else if (changed) {
                 deps.log("info", `restarting ${plan.id}: its command changed`);
                 existing.attempts = 0;
@@ -367,6 +416,93 @@ export function createSupervisor(deps) {
         }
         slots = next;
         emit();
+        pumpHandoff();
+    };
+    /** Replace the next queued adopted unit once the previous replacement has settled. */
+    const pumpHandoff = () => {
+        if (stopped || handoffActive)
+            return;
+        let slot;
+        while ((slot = handoffQueue.shift())) {
+            // Skip units that left the plan, were paused, or already restarted on their own.
+            if (slots.get(slot.plan.id) === slot && !slot.plan.blocked && slot.child && slot.childKey !== slot.key)
+                break;
+        }
+        if (!slot)
+            return;
+        const target = slot;
+        handoffActive = true;
+        deps.log("info", `replacing ${target.plan.id}${target.plan.drainSignal ? " once it finishes its current work" : ""}`);
+        target.attempts = 0;
+        target.state.restarts = 0;
+        terminate(target, () => activate(target), true);
+        const settle = (delay) => {
+            handoffTimer = setT(() => {
+                handoffTimer = undefined;
+                if (stopped)
+                    return;
+                const gone = slots.get(target.plan.id) !== target || target.plan.blocked !== undefined;
+                if (!gone && target.expectingExit)
+                    return settle(HANDOFF_STAGGER_MS);
+                if (!gone && target.child) {
+                    const ranFor = now() - (target.childStartedAt ?? now());
+                    if (ranFor < HANDOFF_STAGGER_MS)
+                        return settle(HANDOFF_STAGGER_MS - ranFor);
+                }
+                else if (!gone && target.state.status === "backoff") {
+                    return settle(HANDOFF_STAGGER_MS);
+                }
+                handoffActive = false;
+                pumpHandoff();
+            }, delay);
+        };
+        settle(HANDOFF_STAGGER_MS);
+    };
+    /** Stop a process the plan has no place for. */
+    const stopStray = (id, child) => {
+        const slot = newSlot({ id, service: id, description: id, kind: "long-running", restart: "always", command: null, env: {} });
+        slot.child = child;
+        watch(slot, child);
+        terminate(slot);
+    };
+    /** Take over the previous daemon's services before the first plan read starts anything. */
+    const adoptPrevious = () => {
+        const adopt = deps.adopt ?? [];
+        if (adopt.length === 0)
+            return;
+        let plans = [];
+        try {
+            const result = deps.plan();
+            if (!Array.isArray(result))
+                throw new Error("plan did not return a list of units");
+            plans = result;
+        }
+        catch (err) {
+            deps.log("error", `could not plan units; stopping the services left by the previous daemon: ${errorMessage(err)}`);
+        }
+        const byId = new Map(plans.map((p) => [p.id, p]));
+        for (const unit of adopt) {
+            const plan = byId.get(unit.id);
+            if (!plan || plan.kind !== "long-running" || slots.has(unit.id)) {
+                deps.log("info", `stopping ${unit.id} left by the previous daemon: no longer planned as a service`);
+                stopStray(unit.id, unit.child);
+                continue;
+            }
+            // Recorded as runnable, so the first plan read pauses it when it is now blocked.
+            const slot = newSlot({ ...plan, blocked: undefined });
+            slot.key = unit.key;
+            slot.adopted = true;
+            slot.child = unit.child;
+            slot.childKey = unit.key;
+            slot.childStartedAt = now();
+            slot.state.status = "running";
+            slot.state.startedAt = slot.childStartedAt;
+            if (unit.child.pid !== undefined)
+                slot.state.pid = unit.child.pid;
+            watch(slot, unit.child);
+            slots.set(unit.id, slot);
+            deps.log("info", `adopted ${unit.id} (pid ${unit.child.pid ?? "?"}) from the previous daemon`);
+        }
     };
     const handleRequest = (req) => {
         if (req.action === "restart-daemon") {
@@ -461,6 +597,7 @@ export function createSupervisor(deps) {
             if (started)
                 return;
             started = true;
+            adoptPrevious();
             reconcile();
             reconcileTimer = setT(reconcileLoop, reconcileMs);
             requestTimer = setT(pollRequests, requestPollMs);
@@ -473,6 +610,8 @@ export function createSupervisor(deps) {
                 clearT(reconcileTimer);
             if (requestTimer !== undefined)
                 clearT(requestTimer);
+            if (handoffTimer !== undefined)
+                clearT(handoffTimer);
             for (const slot of slots.values()) {
                 clearTimer(slot);
                 slot.child = undefined;
@@ -519,6 +658,34 @@ export function createSupervisor(deps) {
         },
         reconcile,
         state: snapshot,
+        release() {
+            const released = [];
+            for (const slot of slots.values()) {
+                const pid = slot.child?.pid;
+                if (slot.plan.kind === "long-running" && pid !== undefined && slot.childKey !== undefined) {
+                    released.push({ id: slot.plan.id, pid, key: slot.childKey });
+                }
+            }
+            stopped = true;
+            if (reconcileTimer !== undefined)
+                clearT(reconcileTimer);
+            if (requestTimer !== undefined)
+                clearT(requestTimer);
+            if (handoffTimer !== undefined)
+                clearT(handoffTimer);
+            for (const slot of slots.values()) {
+                clearTimer(slot);
+                if (slot.killTimer !== undefined)
+                    clearT(slot.killTimer);
+                slot.killTimer = undefined;
+                slot.child = undefined;
+                slot.state.status = "stopped";
+                delete slot.state.pid;
+                delete slot.state.nextRunAt;
+            }
+            emit();
+            return released;
+        },
     };
 }
 //# sourceMappingURL=supervisor.js.map

package/dist/lib/lanes/hire-grant-dispatch.d.ts

@@ -16,9 +16,10 @@ export interface OutpostHireGrantContext {
     expected_senior: SeniorRef;
     hierarchy: HireGrantLaneSnapshot[];
     superseded_message_caller_id?: string;
+    superseded_message_session_id?: string;
 }
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
-export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string): string;
+export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string, supersededMessageSessionId?: string): string;
 /** Decode and validate an owner grant context, binding it to the target lane. */
 export declare function parseOutpostHireGrantContext(encoded: string, targetLaneId: string): OutpostHireGrantContext;
 export declare function sameHireGrantSenior(a: SeniorRef, b: SeniorRef): boolean;

package/dist/lib/lanes/hire-grant-dispatch.js

@@ -30,11 +30,18 @@ function snapshot(lane) {
     };
 }
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
-export function createOutpostHireGrantContext(target, lanes, supersededMessageCallerId) {
+export function createOutpostHireGrantContext(target, lanes, supersededMessageCallerId, supersededMessageSessionId) {
     const current = lanes.find((lane) => lane.lane_id === target.lane_id);
     if (!current || !sameSenior(current.senior, target.senior)) {
         throw new LanesError("hire_grant_hierarchy_unavailable", `Cannot build an authoritative hire-grant hierarchy for lane ${target.lane_id}`, { lane_id: target.lane_id });
     }
+    if (supersededMessageCallerId !== undefined && supersededMessageSessionId !== undefined) {
+        throw contextError("Outpost grant context cannot contain both lane and session message callers");
+    }
+    if (supersededMessageSessionId !== undefined &&
+        (current.senior.kind !== "session" || current.senior.id !== supersededMessageSessionId)) {
+        throw new LanesError("hire_grant_message_caller_invalid", `Cannot include an unverified session message caller in lane ${target.lane_id}'s Outpost context`, { lane_id: target.lane_id });
+    }
     const relevant = new Map();
     relevant.set(current.lane_id, current);
     if (current.senior.kind === "lane") {
@@ -65,6 +72,18 @@ export function createOutpostHireGrantContext(target, lanes, supersededMessageCa
             }
         }
     }
+    if (current.senior.kind === "session") {
+        const companyUid = current.company?.uid;
+        const projectId = current.project_id;
+        if (companyUid) {
+            for (const candidate of lanes) {
+                if (candidate.company?.uid === companyUid && ((current.worker_profile !== undefined && candidate.worker_profile === current.worker_profile) ||
+                    (projectId !== undefined && candidate.project_id === projectId && (candidate.hire_grant ?? 0) > 0))) {
+                    relevant.set(candidate.lane_id, candidate);
+                }
+            }
+        }
+    }
     const hierarchy = [...relevant.values()]
         .map(snapshot)
         .sort((a, b) => a.lane_id.localeCompare(b.lane_id));
@@ -79,6 +98,9 @@ export function createOutpostHireGrantContext(target, lanes, supersededMessageCa
         ...(supersededMessageCallerId === undefined
             ? {}
             : { superseded_message_caller_id: supersededMessageCallerId }),
+        ...(supersededMessageSessionId === undefined
+            ? {}
+            : { superseded_message_session_id: supersededMessageSessionId }),
     };
     const encoded = Buffer.from(JSON.stringify(context), "utf8").toString("base64url");
     if (Buffer.byteLength(encoded, "utf8") > MAX_CONTEXT_BYTES) {
@@ -183,7 +205,7 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
         throw contextError("Outpost grant context must be an object");
     }
     const record = raw;
-    if (Object.keys(record).some((key) => !["schema_version", "enforcement_enabled", "expected_senior", "hierarchy", "superseded_message_caller_id"].includes(key))) {
+    if (Object.keys(record).some((key) => !["schema_version", "enforcement_enabled", "expected_senior", "hierarchy", "superseded_message_caller_id", "superseded_message_session_id"].includes(key))) {
         throw contextError("Outpost grant context contains unknown fields");
     }
     if (record.schema_version !== HIRE_GRANT_CONTEXT_SCHEMA ||
@@ -194,10 +216,18 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
     }
     const expectedSenior = parseSenior(record.expected_senior);
     const messageCallerId = record.superseded_message_caller_id;
+    const messageSessionId = record.superseded_message_session_id;
     if (messageCallerId !== undefined &&
         (typeof messageCallerId !== "string" || !messageCallerId.trim() || messageCallerId.trim() !== messageCallerId)) {
         throw contextError("Outpost grant context contains an invalid superseded-message caller");
     }
+    if (messageSessionId !== undefined &&
+        (typeof messageSessionId !== "string" || !messageSessionId.trim() || messageSessionId.trim() !== messageSessionId)) {
+        throw contextError("Outpost grant context contains an invalid superseded-message session");
+    }
+    if (messageCallerId !== undefined && messageSessionId !== undefined) {
+        throw contextError("Outpost grant context cannot contain both lane and session message callers");
+    }
     const hierarchy = record.hierarchy.map(parseLaneSnapshot);
     if (!expectedSenior || hierarchy.some((lane) => lane === null)) {
         throw contextError("Outpost grant context contains an invalid senior or lane snapshot");
@@ -211,6 +241,10 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
     if (!target || !sameSenior(target.senior, expectedSenior)) {
         throw contextError("Outpost grant context does not match the target's expected senior");
     }
+    if (messageSessionId !== undefined &&
+        (expectedSenior.kind !== "session" || expectedSenior.id !== messageSessionId)) {
+        throw contextError("Outpost grant context session caller does not match the target's session senior");
+    }
     if (expectedSenior.kind === "lane" &&
         (!expectedSenior.id || !byId.has(expectedSenior.id))) {
         throw contextError("Outpost grant context is missing the target's senior lane");
@@ -232,6 +266,7 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
         expected_senior: expectedSenior,
         hierarchy: snapshots,
         ...(messageCallerId === undefined ? {} : { superseded_message_caller_id: messageCallerId }),
+        ...(messageSessionId === undefined ? {} : { superseded_message_session_id: messageSessionId }),
     };
 }
 export function sameHireGrantSenior(a, b) {

package/dist/lib/lanes/host-capacity.js

@@ -10,7 +10,13 @@ function admissionHost(host) {
 /** Snapshot the same per-host running-slot predicate used by lane admission. */
 export function buildHostCapacitySnapshot(input) {
     const at = input.now.getTime();
-    const onHost = input.lanes.filter((lane) => laneRunsOnHost(lane, admissionHost(input.host)));
+    const localHostname = input.hostname?.trim();
+    const onHost = input.lanes.filter((lane) => laneRunsOnHost(lane, admissionHost(input.host)) ||
+        (input.host.kind === "outpost" &&
+            localHostname !== undefined &&
+            localHostname !== "" &&
+            lane.host.kind === "local" &&
+            lane.host.id === localHostname));
     const providers = {};
     for (const provider of ["claude", "codex", "grok"]) {
         const providerConfig = input.config.providers[provider];

package/dist/lib/lanes/keep-alive.js

@@ -234,8 +234,8 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
         // Any descendant is part of this lead's work tree, not a replacement lead.
         if (laneAncestorsFrom(candidate.senior, lanesById, sessionOwners).has(lane.lane_id))
             return false;
-        const sameLaneSenior = lane.senior.kind === "lane" &&
-            candidate.senior.kind === "lane" &&
+        const sameLaneSenior = (lane.senior.kind === "lane" || lane.senior.kind === "session") &&
+            candidate.senior.kind === lane.senior.kind &&
             candidate.senior.id === lane.senior.id;
         const sameProfile = lane.worker_profile !== undefined &&
             candidate.worker_profile === lane.worker_profile &&

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

@@ -67,6 +67,8 @@ export declare function parseClaudeHelpModels(text: string): {
     aliases: string[];
     prefixes: string[];
 };
+/** Prefix of every Claude model full name, e.g. `claude-sonnet-5-5`. */
+export declare const CLAUDE_FULL_NAME_PREFIX = "claude-";
 export declare function claudeKnownModels(probe?: ProbeCommand, env?: NodeJS.ProcessEnv): KnownModels | null;
 export declare function knownModels(provider: LaneProvider, home: string, deps?: KnownModelsDeps): KnownModels | null;
 export declare function modelIsKnown(known: KnownModels, model: string): boolean;

package/dist/lib/lanes/models.js

@@ -154,6 +154,8 @@ export function parseClaudeHelpModels(text) {
     }
     return { aliases, prefixes: [...prefixes] };
 }
+/** Prefix of every Claude model full name, e.g. `claude-sonnet-5-5`. */
+export const CLAUDE_FULL_NAME_PREFIX = "claude-";
 export function claudeKnownModels(probe = defaultProbe, env = process.env) {
     const source = "claude --help";
     const result = probe("claude", ["--help"], env);
@@ -166,7 +168,10 @@ export function claudeKnownModels(probe = defaultProbe, env = process.env) {
         process.stderr.write(`hq lanes: \`${source}\` named no --model aliases (exit ${result.status ?? "spawn error"}); --model is not validated for claude\n`);
         return null;
     }
-    return { provider: "claude", ids: parsed.aliases, prefixes: parsed.prefixes, source };
+    // Every Claude model's full name starts with `claude-`. Accept it even when
+    // this help text carries no full-name example, as some releases' help does.
+    const prefixes = [...new Set([CLAUDE_FULL_NAME_PREFIX, ...parsed.prefixes])];
+    return { provider: "claude", ids: parsed.aliases, prefixes, source };
 }
 export function knownModels(provider, home, deps = {}) {
     switch (provider) {

package/package.json

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