@indigoai-us/hq-cli 5.313.0 → 5.314.0

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

@@ -1,355 +0,0 @@
-/**
- * Detached lane-worker spawn (spec §5, §5.1, §5.4, §5.5).
- *
- * The worker must leave the caller's process tree (`detached: true` / setsid)
- * with stdio pointed at files in the run directory. Account selection is the
- * provider home environment variable only. Provider credential files are
- * probed for existence and never read. Identity in the child is `HQ_LANE_ID`;
- * mutable fields are re-read from the lane record (spec §5.4).
- */
-import { PROVIDER_HOME_ENV } from "./accounts.js";
-import { type RunCompactionFn } from "./compaction.js";
-import { type ResolvedEffort } from "./effort.js";
-import { type KnownModelsDeps } from "./models.js";
-import { type LaunchTrigger } from "./delivery.js";
-import { type MachineIdentity } from "./machine-identity.js";
-import { type AdmissionHost } from "./admission.js";
-import { type StatFs } from "./disk-guard.js";
-import { type LaneCompanyRef, type LaneProvider, type LaneRecord, type AccountHistoryEntry } from "./types.js";
-export declare const LANES_RUNS_REL: string;
-/** Written by reconcile before a resume spawn; the worker prompt names this path. */
-export declare const ANSWERED_QUESTIONS_FILE = "answered-questions.json";
-export declare const SPAWN_TERMINAL_REASONS: readonly ["account_not_logged_in", "unknown_account", "account_disabled", "no_enabled_account", "spawn_failed", "not_detached", "watcher_not_armed", "model_unsupported"];
-export type SpawnTerminalReason = (typeof SPAWN_TERMINAL_REASONS)[number];
-declare const PROVIDER_COMMAND: Record<LaneProvider, string>;
-export declare function providerCommandOnPath(command: string, pathEnv: string | undefined): boolean;
-/** Per-provider model flag. A missing entry means --model is refused. */
-export declare const PROVIDER_MODEL_FLAG: Record<LaneProvider, string>;
-export declare const CLAUDE_AUTO_COMPACT_ENV = "CLAUDE_CODE_AUTO_COMPACT_WINDOW";
-/** Codex CLI overrides required for its ChatGPT fast service tier. */
-export declare const CODEX_FAST_MODE_FLAGS: readonly ["-c", "service_tier=\"fast\"", "--enable", "fast_mode"];
-export declare function parseCliModel(raw: string | undefined): string | undefined;
-export declare function resolveLaneModel(input: {
-    cliModel?: string;
-    profileModel?: string;
-    accountModel?: string;
-    providerModel?: string;
-}): string | undefined;
-type AutomaticAccountChangeReason = Exclude<AccountHistoryEntry["reason"], "operator_move">;
-/** Change account only after a provider/runtime account failure, then re-admit. */
-export declare function retryLaneOnAlternateAccount(hqRoot: string, lane: LaneRecord, reason: Extract<AutomaticAccountChangeReason, "usage_limit" | "account_unavailable">, writer?: "watcher" | "reconcile", deps?: SpawnLaneDeps): Promise<LaneRecord>;
-export declare function appendModelFlag(provider: LaneProvider, args: string[], model: string | undefined): string[];
-/** Add Codex fast-mode flags before the prompt/positional separator. */
-export declare function appendFastModeFlags(provider: LaneProvider, args: string[], enabled: boolean | undefined): string[];
-export interface ProviderProfileLaunch {
-    systemPrompt: string;
-    settingsPath?: string;
-    ignoredFields?: readonly string[];
-}
-export type DetachedStdio = ["ignore", number, number];
-export interface DetachedSpawnOptions {
-    detached: true;
-    windowsHide: true;
-    stdio: DetachedStdio;
-    env: NodeJS.ProcessEnv;
-    cwd: string;
-}
-export type SpawnProcessFn = (command: string, args: string[], options: DetachedSpawnOptions) => {
-    pid?: number;
-    unref(): void;
-};
-export interface DetachProof {
-    detached: boolean;
-    pid: number;
-    pgid?: number;
-    sid?: number;
-    method?: string;
-    reason?: string;
-}
-export type ProveDetachedFn = (pid: number) => DetachProof;
-export type KillProcessFn = (pid: number, signal?: NodeJS.Signals) => void;
-export interface SpawnLaneDeps {
-    env?: NodeJS.ProcessEnv;
-    /** Absolute CLI entry captured when the watcher is armed; tests may inject it. */
-    hqCliEntry?: string;
-    hostname?: string;
-    /** The caller's host scope for admission checks; reconcile supplies its resolved host. */
-    admissionHost?: AdmissionHost;
-    /** Resolved per-company by the async command/reconcile boundary. */
-    lowDiskGuardEnabled?: boolean;
-    /** Injected statfs boundary; production uses node:fs.statfsSync. */
-    statfs?: StatFs;
-    /** Provider model catalog dependencies, shared with create in tests. */
-    modelDeps?: KnownModelsDeps;
-    /** Create validated this exact account/model candidate before its admission lock. */
-    currentModelValidated?: boolean;
-    existsSync?: (p: string) => boolean;
-    spawnProcess?: SpawnProcessFn;
-    proveDetached?: ProveDetachedFn;
-    killProcess?: KillProcessFn;
-    now?: () => Date;
-    /** Shared with create. Injected in tests; default is resolveMachineIdentity. */
-    resolveMachineIdentity?: () => MachineIdentity;
-    /** Runs the synchronous `/compact` call. Injected in tests. */
-    runCompaction?: RunCompactionFn;
-    /** Finds a session transcript under an account home. Injected in tests. */
-    locateTranscript?: (home: string, sessionId: string) => string | null;
-}
-export interface ProviderLaunch {
-    command: string;
-    args: string[];
-}
-interface ProcStat {
-    pid: number;
-    ppid: number;
-    pgrp: number;
-    session: number;
-    starttime?: number;
-}
-export interface PidRecord {
-    pid: number;
-    starttime?: number;
-}
-export declare const PID_LIVENESS_DECISIONS: readonly ["esrch", "starttime_mismatch", "eperm", "starttime_match", "no_recorded_starttime", "starttime_unreadable", "missing_pid_file"];
-export type PidLivenessDecision = (typeof PID_LIVENESS_DECISIONS)[number];
-export interface PidLivenessProbe {
-    pid: number | null;
-    recorded_starttime: number | null;
-    live_starttime: number | null;
-    starttime_error: string | null;
-    alive: boolean;
-    decided_by: PidLivenessDecision;
-}
-export declare function missingPidProbe(): PidLivenessProbe;
-export declare function defaultPidIsAlive(pid: number): boolean;
-export declare const STOP_TERM_WAIT_MS = 500;
-export declare const STOP_KILL_WAIT_MS = 200;
-export declare function parseSpawnTerminalReason(value: string): SpawnTerminalReason;
-export declare function laneRunDir(hqRoot: string, laneId: string): string;
-export declare function watcherMainPath(): string;
-export declare function parseProcStat(text: string): ProcStat;
-export declare function readProcStarttimeDetailed(pid: number): {
-    starttime: number | null;
-    error: string | null;
-};
-export declare function readProcStarttime(pid: number): number | null;
-export declare function formatPidRecord(rec: PidRecord): string;
-export declare function parsePidRecord(text: string): PidRecord | null;
-export declare function readPidRecord(filePath: string): PidRecord | null;
-export declare function writePidRecord(filePath: string, rec: PidRecord): void;
-export declare function probePidRecord(rec: PidRecord, isAlive?: (pid: number) => boolean, readStarttime?: (pid: number) => number | null): PidLivenessProbe;
-export declare function isPidRecordAlive(rec: PidRecord, isAlive?: (pid: number) => boolean, readStarttime?: (pid: number) => number | null): boolean;
-export declare function signalProcessGroup(pid: number, signal: NodeJS.Signals, killProcess: KillProcessFn): void;
-export interface StopLaneDeps {
-    killProcess?: KillProcessFn;
-    isAlive?: (pid: number) => boolean;
-    sleepMs?: (ms: number) => void;
-    readStarttime?: (pid: number) => number | null;
-}
-export interface StopLaneResult {
-    worker: PidRecord | null;
-    watcher: PidRecord | null;
-    signals: Array<{
-        pid: number;
-        signal: NodeJS.Signals;
-        group: boolean;
-    }>;
-}
-export declare function stopLaneProcesses(hqRoot: string, laneId: string, deps?: StopLaneDeps): StopLaneResult;
-export interface ProveDetachedDeps {
-    /** Test seam: throw ENOENT to exercise the no-/proc fallback. */
-    readProcStatText?: (pid: number) => string;
-}
-export declare function defaultProveDetached(pid: number, deps?: ProveDetachedDeps): DetachProof;
-export declare function nextEnvelopePath(runDir: string): string;
-export declare function envelopeInstruction(envelopePath: string): string;
-/**
- * Prompt for a resumed session. The conversation already holds the brief, so
- * the new turn carries only what changed plus the envelope contract for this
- * run's slot. The operator message is framed exactly as the drop-box drain
- * frames it.
- */
-export interface AnsweredQuestionLine {
-    question_id: string;
-    choice: string;
-    /** The operator's free-text notes from `questions answer --notes`, when any. */
-    notes?: string;
-}
-/**
- * Standing authorization carried by every brief and every resume turn. A
- * lane that ends each turn asking "continue or stop" has asked the operator
- * to re-grant what the brief already granted; the paragraph names that as
- * out of bounds and says what a `decision: ask` envelope is for.
- */
-export declare const STANDING_AUTHORIZATION: string;
-/**
- * Foreground-only rule carried next to the standing authorization. Two lanes
- * ended `interrupted` after backgrounding a slow test suite and ending the
- * turn while it was still running; nothing in the brief said not to.
- */
-export declare const FOREGROUND_ONLY_RULE: string;
-/**
- * The answers as written by the reconcile pass (`answered-questions.json`),
- * reduced to id + choice. A malformed file reads as no inline answers; the
- * path is still named so the worker can read it.
- */
-export declare function readAnsweredQuestionLines(answersPath: string): AnsweredQuestionLine[];
-export declare function resumePrompt(input: {
-    envelopePath: string;
-    operatorMessage?: string;
-    monitorEvent?: string;
-    answersPath?: string;
-    /** Inline copy of the answers so the turn carries them, not only a path. */
-    answers?: AnsweredQuestionLine[];
-    /** `hq lanes resume`: the state the operator resumed the lane from. */
-    resumedFrom?: string;
-    /** Automatic continuation initiated by the lane watcher. */
-    resumeSource?: "watcher";
-    /** Exact validator errors recorded after the prior envelope repair failed. */
-    envelopeRepairErrors?: {
-        first_error: string;
-        second_error?: string;
-    };
-}): string;
-/** Spec §4: the one repair turn. Schema, parser error, raw text, JSON only. */
-export declare function envelopeRepairPrompt(input: {
-    envelopePath: string;
-    error: string;
-    rawText: string;
-    missing?: boolean;
-}): string;
-export interface ProviderResumeInput {
-    session_id: string;
-    prompt: string;
-}
-export declare function buildProviderCommand(provider: LaneProvider, input: {
-    hqRoot: string;
-    briefPath: string;
-    envelopePath: string;
-    lastMessagePath: string;
-    extraPrompt?: string;
-    model?: string;
-    /** Validated against the provider's own value set by appendEffortFlag. */
-    effort?: string;
-    /** Enable Codex's fast service tier for this resolved model. */
-    fastMode?: boolean;
-    /** Per-spawn worker profile instructions and materialized settings. */
-    profile?: ProviderProfileLaunch;
-    /** Worker profile path, forwarded to Codex hook subprocesses when supported. */
-    workerPolicyDir?: string;
-    /** Continue a recorded session. Only providers in PROVIDER_SESSION_RESUME accept this. */
-    resume?: ProviderResumeInput;
-    /**
-     * Replace the brief prompt with a single-turn prompt on a fresh session
-     * (spec §4 envelope repair for a provider that cannot resume). Mutually
-     * exclusive with `resume`.
-     */
-    freshTurnPrompt?: string;
-}): ProviderLaunch;
-export declare function workerEnv(base: NodeJS.ProcessEnv, resolved: {
-    envVar: string;
-    home: string;
-}, laneId: string, hqRoot: string, autoCompactTokens?: number, meshCompany?: LaneCompanyRef, workerPolicyDir?: string, registryWorker?: LaneRecord["registry_worker"]): NodeJS.ProcessEnv;
-export declare const WORKER_POLICY_HOOK_CAPABILITY = "# hq-capability: worker-policy-dir v1";
-/** Grok does not run HQ hooks; Claude and Codex use the installed capability marker. */
-export declare function workerPolicyDeliveryMode(hqRoot: string, provider: LaneProvider): "hook" | "prompt";
-export declare function markSpawnFailure(hqRoot: string, laneId: string, reasonRaw: string, details: Record<string, unknown>): LaneRecord;
-/**
- * Spec §5.2 executing-side check. Compares this machine's identity to
- * `origin_host` (never to `host.id`). Unresolvable identity is a cancel.
- * Must run before the worker is spawned.
- */
-export declare function refuseOutpostSelfTarget(hqRoot: string, lane: LaneRecord, deps: SpawnLaneDeps): void;
-/** Arm (or re-arm) the detached per-lane watcher. */
-export declare function armLaneWatcher(hqRoot: string, laneId: string, deps?: SpawnLaneDeps): number;
-export interface SpawnManifestFile {
-    envelope_path?: string;
-    turn_id?: string;
-    resume?: {
-        session_id: string;
-    } | null;
-    provider_home_at_spawn?: string;
-    /** Byte length of logs/worker.out before this run started; its result is after this. */
-    worker_out_offset?: number;
-    fast_mode?: boolean;
-    worker_profile?: string;
-    worker_profile_hash?: string;
-    worker_profile_ignored?: string[];
-    worker_profile_settings?: string;
-    worker_policy_delivery?: "hook" | "prompt";
-    worker_policy_dir?: string;
-    worker_policy_env?: {
-        HQ_POLICY_WORKER_DIR: string;
-    };
-}
-/** Read the per-run manifest. Missing file or field reads as absent. */
-export declare function readSpawnManifest(runDir: string): SpawnManifestFile;
-export interface SpawnLaunchOptions {
-    /**
-     * Why this spawn is happening. Omitted: inferred from the record's state
-     * (queued → admit, awaiting_input → answered_questions). An operator message
-     * must be passed explicitly; it is the only trigger that resumes from a
-     * finished lane.
-     */
-    trigger?: LaunchTrigger;
-    /**
-     * False skips the resume-time compaction check for this launch only
-     * (`hq lanes message --no-compact`). Default true.
-     */
-    compact?: boolean;
-    /** Effort resolved by an explicit resume/message request, or pinned from its record. */
-    effort?: ResolvedEffort;
-}
-/**
- * Bind the account, spawn the worker and its watcher outside the caller's
- * tree, then CAS the record to `running`. A spawn that cannot be proven
- * started and detached is a named terminal reason, never a bare `failed`.
- *
- * Fresh-vs-resume is decided by `planLaneLaunch` (delivery.ts), never here.
- */
-export declare function spawnLaneWorker(hqRoot: string, lane: LaneRecord, deps?: SpawnLaneDeps, launch?: SpawnLaunchOptions): LaneRecord;
-export interface EnvelopeRepairSpawnInput {
-    /** Recorded session to resume. Required for a resumable provider; ignored otherwise. */
-    session_id?: string | null;
-    envelopePath: string;
-    error: string;
-    rawText: string;
-    /** True when this run never wrote its expected envelope file. */
-    missing?: boolean;
-    /** Repair-only warning hook for profile metadata ignored during recovery. */
-    onProfileWarning?: (fields: readonly string[]) => void;
-}
-/**
- * Handle the private request sent by an older, long-running watcher to the
- * currently installed `hq` executable. The persisted repair attempt is the
- * authorization for this one-shot spawn; the request cannot select an
- * arbitrary lane or write outside that lane's envelope directory.
- */
-export declare function spawnEnvelopeRepairRequest(hqRoot: string, rawRequest: unknown, deps?: SpawnLaneDeps): {
-    pid: number;
-    profile_warnings: string[][];
-};
-/** How the spec §4 repair turn reaches the provider (recorded as `envelope_repair.mode`). */
-export type EnvelopeRepairMode = "resume" | "fresh_turn";
-/**
- * `resume`: claude and codex continue the recorded session with the repair
- * prompt. `fresh_turn`: grok gets a new single-turn invocation on the same
- * account, whose prompt carries the schema, the parser error and the raw
- * failed output. Grok can resume a session (operator messages and
- * `hq lanes resume` use it), but its repair turn stays a fresh turn: that
- * path was built and proven that way, and a repair by resume has not been.
- */
-export declare function envelopeRepairMode(provider: LaneProvider): EnvelopeRepairMode;
-/**
- * Spec §4 repair turn. The lane is still `running` (the watcher has not
- * written a terminal state), so this does not claim or transition the
- * record. It resumes the recorded provider session with the repair prompt
- * (`resume` mode), or for a provider with no session resume runs the repair
- * prompt as a fresh single turn on the same account (`fresh_turn` mode). It
- * replaces `worker.pid` and rewrites `spawn.json` so the watcher's next tick
- * follows the new process. The account is the one already bound on the record.
- * Fast-mode evidence is updated after the replacement is proven detached.
- */
-export declare function spawnEnvelopeRepair(hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput, deps?: SpawnLaneDeps): number;
-export { PROVIDER_HOME_ENV, PROVIDER_COMMAND };
-//# sourceMappingURL=spawn.d.ts.map