@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/reconcile-install.d.ts

@@ -0,0 +1,69 @@
+/**
+ * systemd user timer install for the lanes reconcile pass.
+ *
+ * Policy: hq-infra-watchdogs-systemd-not-session. The pass is a oneshot
+ * invoked by a timer, never a session-bound background job. Install writes
+ * unit files under a systemd user dir and is idempotent and reversible.
+ * Enabling the timer is optional — the CLI pass works without it.
+ */
+export declare const RECONCILE_TIMER_INTERVAL = "1min";
+export interface ProviderPathEnv {
+    /** PATH for the systemd unit: resolved provider dirs, systemd defaults, then the shell PATH. */
+    path: string;
+    /** Providers whose binary resolved on the installing shell's PATH. */
+    resolved: string[];
+    /** Providers whose binary did not resolve. Reported, never fatal on their own. */
+    unresolved: string[];
+}
+/**
+ * Resolve provider commands with the installing shell's PATH. The resulting
+ * directories are carried into the systemd unit, whose default PATH is too
+ * narrow for per-user provider installations.
+ *
+ * A default config enables one account per provider, so `providers` usually
+ * names every provider even on a box with one installed. A provider that does
+ * not resolve is reported in `unresolved`; the install only refuses when none
+ * of the requested providers resolves, because then the timer has nothing to
+ * run.
+ */
+export declare function providerPathEnv(providers: readonly string[], pathEnv?: string | undefined): ProviderPathEnv;
+export interface RunCommandResult {
+    status: number;
+    stdout?: string;
+    stderr?: string;
+}
+export type RunCommand = (command: string, args: string[]) => RunCommandResult;
+export interface ReconcileInstallOpts {
+    systemdRoot: string;
+    hqRoot: string;
+    nodeBinary?: string;
+    hqBinary?: string;
+    pathEnv?: string;
+    home?: string;
+    enable?: boolean;
+    runCommand?: RunCommand;
+}
+export interface ReconcileInstallResult {
+    ok: true;
+    action: "reconcile.install" | "reconcile.uninstall";
+    systemd_root: string;
+    unit: string;
+    timer: string;
+    written?: boolean;
+    enabled?: boolean;
+    removed?: boolean;
+}
+export declare function renderReconcileService(opts: {
+    nodeBinary: string;
+    hqBinary: string;
+    hqRoot: string;
+    home?: string;
+    pathEnv?: string;
+}): string;
+export declare function renderReconcileTimer(): string;
+export declare function defaultSystemdUserDir(home?: string): string;
+export declare function installReconcileTimer(opts: ReconcileInstallOpts): ReconcileInstallResult;
+export declare function uninstallReconcileTimer(opts: Pick<ReconcileInstallOpts, "systemdRoot" | "runCommand"> & {
+    disable?: boolean;
+}): ReconcileInstallResult;
+//# sourceMappingURL=reconcile-install.d.ts.map

package/dist/lib/lanes/reconcile-install.js

@@ -0,0 +1,221 @@
+/**
+ * systemd user timer install for the lanes reconcile pass.
+ *
+ * Policy: hq-infra-watchdogs-systemd-not-session. The pass is a oneshot
+ * invoked by a timer, never a session-bound background job. Install writes
+ * unit files under a systemd user dir and is idempotent and reversible.
+ * Enabling the timer is optional — the CLI pass works without it.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { RECONCILE_TIMER_NAME, RECONCILE_UNIT_NAME } from "./reconcile.js";
+import { resolveHqBinary, resolveNodeBinary, } from "../mesh/live/daemon/install.js";
+import { SYSTEMD_PATH_ENV } from "../service-manager/systemd.js";
+export const RECONCILE_TIMER_INTERVAL = "1min";
+/**
+ * Resolve provider commands with the installing shell's PATH. The resulting
+ * directories are carried into the systemd unit, whose default PATH is too
+ * narrow for per-user provider installations.
+ *
+ * A default config enables one account per provider, so `providers` usually
+ * names every provider even on a box with one installed. A provider that does
+ * not resolve is reported in `unresolved`; the install only refuses when none
+ * of the requested providers resolves, because then the timer has nothing to
+ * run.
+ */
+export function providerPathEnv(providers, pathEnv = process.env.PATH) {
+    const searched = pathEnv ?? "";
+    const directories = searched.split(path.delimiter).filter(Boolean);
+    const resolvedDirs = [];
+    const resolved = [];
+    const unresolved = [];
+    for (const provider of providers) {
+        const found = directories.find((directory) => {
+            try {
+                fs.accessSync(path.join(directory, provider), fs.constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!found) {
+            unresolved.push(provider);
+            continue;
+        }
+        resolved.push(provider);
+        // Keep the real binary's directory, not only a wrapper directory that
+        // happened to be on the installing shell's PATH. Systemd must be able to
+        // invoke the resolved provider after it starts with its own environment.
+        resolvedDirs.push(path.dirname(fs.realpathSync(path.join(found, provider))));
+    }
+    if (providers.length > 0 && resolved.length === 0) {
+        throw new LanesError("provider_binary_unresolved", `Cannot resolve any provider binary (${providers.join(", ")}) from PATH`, { providers: [...providers], searched_path: searched });
+    }
+    return {
+        path: [...new Set([...resolvedDirs, ...SYSTEMD_PATH_ENV.split(":"), ...directories])]
+            .filter(Boolean)
+            .join(":"),
+        resolved,
+        unresolved,
+    };
+}
+function shellQuote(v) {
+    return /^[A-Za-z0-9_./:-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`;
+}
+export function renderReconcileService(opts) {
+    const exec = [opts.nodeBinary, opts.hqBinary, "lanes", "reconcile"]
+        .map(shellQuote)
+        .join(" ");
+    const home = opts.home ?? os.homedir();
+    const pathEnv = opts.pathEnv ?? SYSTEMD_PATH_ENV;
+    return `[Unit]
+Description=HQ lanes reconcile pass
+Documentation=file://personal/projects/hq-cli-lanes/SPEC.md
+
+[Service]
+Type=oneshot
+ExecStart=${exec}
+WorkingDirectory=${shellQuote(opts.hqRoot)}
+Nice=10
+Environment=HOME=${shellQuote(home)}
+Environment=PATH=${shellQuote(pathEnv)}
+Environment=HQ_ROOT=${shellQuote(opts.hqRoot)}
+Environment=HQ_NO_UPDATE_CHECK=1
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function renderReconcileTimer() {
+    return `[Unit]
+Description=Periodic HQ lanes reconcile pass
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=${RECONCILE_TIMER_INTERVAL}
+AccuracySec=10s
+Persistent=true
+Unit=${RECONCILE_UNIT_NAME}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function defaultSystemdUserDir(home = os.homedir()) {
+    return path.join(home, ".config", "systemd", "user");
+}
+function writeIfChanged(filePath, contents) {
+    try {
+        const existing = fs.readFileSync(filePath, "utf8");
+        if (existing === contents)
+            return false;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(tmp, contents, { encoding: "utf8", mode: 0o644 });
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const unlinkCode = unlinkErr.code;
+            if (unlinkCode !== "ENOENT") {
+                process.stderr.write(`hq lanes reconcile install: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+    return true;
+}
+function unlinkIfExists(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function runSystemctl(args, runCommand) {
+    const result = runCommand("systemctl", args);
+    if (result.status !== 0) {
+        throw new LanesError("systemd_failed", `systemctl ${args.join(" ")} failed: ${(result.stderr ?? "").trim() || `exit ${result.status}`}`, { args, status: result.status, stderr: result.stderr });
+    }
+}
+export function installReconcileTimer(opts) {
+    const nodeBinary = opts.nodeBinary ?? resolveNodeBinary();
+    const hqBinary = opts.hqBinary ?? resolveHqBinary();
+    const unitPath = path.join(opts.systemdRoot, RECONCILE_UNIT_NAME);
+    const timerPath = path.join(opts.systemdRoot, RECONCILE_TIMER_NAME);
+    const unitChanged = writeIfChanged(unitPath, renderReconcileService({
+        nodeBinary,
+        hqBinary,
+        hqRoot: opts.hqRoot,
+        home: opts.home,
+        pathEnv: opts.pathEnv,
+    }));
+    const timerChanged = writeIfChanged(timerPath, renderReconcileTimer());
+    let enabled = false;
+    if (opts.enable) {
+        if (!opts.runCommand) {
+            throw new LanesError("systemd_enable_requires_runner", "--enable needs a systemctl runner; pass runCommand or omit --enable to write unit files only", {});
+        }
+        runSystemctl(["--user", "daemon-reload"], opts.runCommand);
+        runSystemctl(["--user", "enable", "--now", RECONCILE_TIMER_NAME], opts.runCommand);
+        enabled = true;
+    }
+    return {
+        ok: true,
+        action: "reconcile.install",
+        systemd_root: opts.systemdRoot,
+        unit: unitPath,
+        timer: timerPath,
+        written: unitChanged || timerChanged,
+        enabled,
+    };
+}
+export function uninstallReconcileTimer(opts) {
+    if (opts.disable) {
+        if (!opts.runCommand) {
+            throw new LanesError("systemd_enable_requires_runner", "--disable needs a systemctl runner", {});
+        }
+        const disable = opts.runCommand("systemctl", [
+            "--user",
+            "disable",
+            "--now",
+            RECONCILE_TIMER_NAME,
+        ]);
+        if (disable.status !== 0) {
+            process.stderr.write(`hq lanes reconcile uninstall: systemctl disable exited ${disable.status}: ${(disable.stderr ?? "").trim()}\n`);
+        }
+        opts.runCommand("systemctl", ["--user", "daemon-reload"]);
+    }
+    const unitPath = path.join(opts.systemdRoot, RECONCILE_UNIT_NAME);
+    const timerPath = path.join(opts.systemdRoot, RECONCILE_TIMER_NAME);
+    const removedUnit = unlinkIfExists(unitPath);
+    const removedTimer = unlinkIfExists(timerPath);
+    return {
+        ok: true,
+        action: "reconcile.uninstall",
+        systemd_root: opts.systemdRoot,
+        unit: unitPath,
+        timer: timerPath,
+        removed: removedUnit || removedTimer,
+    };
+}
+//# sourceMappingURL=reconcile-install.js.map

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

@@ -0,0 +1,102 @@
+/**
+ * Periodic reconcile pass (spec §5.7, §6.8, §9).
+ *
+ * Owned by the machine, not by any lane. Reads never mutate; every write is a
+ * compare-and-set. The per-lane watcher owns progress/terminal/silence of a
+ * live process — this pass owns the transitions no single lane can own.
+ */
+import { type LivenessDeps } from "./liveness.js";
+import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
+import { type ThrottleDeps } from "./throttle.js";
+import type { LaneRecord, LivenessState, QuestionRecord, SeniorRef } from "./types.js";
+import { type LaneMesh } from "./mesh-events.js";
+/** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
+export declare const QUESTION_AGE_MS: number;
+/** Spec §6.6 + §9: v1 permits exactly one aged advance. */
+export declare const MAX_AGED_ADVANCES = 1;
+/** Aligns with watcher silence: a host that has not reported for this long is dead. */
+export declare const DEAD_HOST_MS: number;
+export declare const RECONCILE_LOCK_STALE_MS = 30000;
+export declare const RECONCILE_LOCK_TIMEOUT_MS = 5000;
+export declare const RECONCILE_UNIT_NAME = "hq-lanes-reconcile.service";
+export declare const RECONCILE_TIMER_NAME = "hq-lanes-reconcile.timer";
+export interface ReconcileSkip {
+    kind: "lane" | "question" | "store" | "throttle" | "liveness";
+    id?: string;
+    why: string;
+}
+export interface ReconcileChange {
+    id: string;
+    from?: string;
+    to?: string;
+    reason?: string;
+    /** The attempted provider PATH when admission found no executable. */
+    searched_path?: string;
+}
+export interface ReconcileSummary {
+    ok: boolean;
+    action: "reconcile";
+    dry_run: boolean;
+    admitted: ReconcileChange[];
+    overdue: ReconcileChange[];
+    aged: ReconcileChange[];
+    advanced: ReconcileChange[];
+    resumed: ReconcileChange[];
+    dead_host: ReconcileChange[];
+    heartbeats: string[];
+    skipped: ReconcileSkip[];
+    errors: Array<{
+        message: string;
+        code?: string;
+    }>;
+    heartbeat_at: string | null;
+}
+export interface ReconcileHost {
+    hostname: string;
+    outpostId: string | null;
+}
+export interface ReconcileDeps {
+    now: () => Date;
+    host: ReconcileHost;
+    dryRun: boolean;
+    spawn?: (hqRoot: string, lane: LaneRecord) => LaneRecord;
+    spawnRepair?: (hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput) => number;
+    spawnLaneDeps?: SpawnLaneDeps;
+    throttleDeps?: ThrottleDeps;
+    livenessDeps?: LivenessDeps;
+    isAlive?: (pid: number) => boolean;
+    readSessionSenior?: (sessionId: string) => SeniorRef;
+    presenceConnected?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Detached mesh seam for dead-watcher recovery. */
+    mesh?: LaneMesh | null;
+    /** Bound on one terminal mesh emit during dead-host recovery. Default 10 s. */
+    meshEmitTimeoutMs?: number;
+    /**
+     * Awaited after lane/question records and liveness are loaded, before any
+     * CAS write. Test seam so two in-process passes can share a snapshot.
+     */
+    afterLoad?: () => Promise<void>;
+}
+export declare function reconcileHeartbeatPath(hqRoot: string): string;
+export declare function timeoutPath(hqRoot: string, laneId: string): string;
+export declare function laneRunsHere(lane: LaneRecord, host: ReconcileHost): boolean;
+export declare function agedAdvanceCount(question: QuestionRecord): number;
+export declare function currentHopStartedAtMs(question: QuestionRecord): number;
+export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number): boolean;
+export declare function shouldAdvanceAudienceEnded(audience: SeniorRef, liveness: LivenessState | null): boolean;
+export declare function readTimeoutDeadline(hqRoot: string, laneId: string): {
+    deadline_at: string;
+    timeout_secs?: number;
+} | null;
+export declare function isDeadlinePassed(deadlineAt: string, nowMs: number): boolean;
+export declare function resolveQuestionAudience(question: QuestionRecord, readLaneSenior: (laneId: string) => SeniorRef, readSessionSenior: (sessionId: string) => SeniorRef): SeniorRef;
+/** Unlocked pass body. `runReconcilePass` takes the process lock around this. */
+export declare function runPassBody(hqRoot: string, deps: ReconcileDeps): Promise<ReconcileSummary>;
+/**
+ * One idempotent reconcile pass. Throws only when the store directory itself
+ * cannot be listed; per-record failures are logged onto the summary and set
+ * `ok: false` rather than being swallowed.
+ */
+export declare function runReconcilePass(hqRoot: string, deps: ReconcileDeps): Promise<ReconcileSummary>;
+//# sourceMappingURL=reconcile.d.ts.map