@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -1,110 +0,0 @@
-/**
- * Automatic compaction of a resumed Claude lane.
- *
- * Owner directives 2026-09-22: "if it's been an hour since last msg, always
- * run compact" and "there should be a way to run compact automatically using
- * code written in hqcli".
- *
- * Every `--resume` replays the whole conversation. When a resume is due
- * (`now - last_message_at >= compact_after_ms`), hq-cli first runs
- * `claude -p --resume <sid> "/compact"` in the lane's account, then starts
- * the resume as usual. The decision is made at resume time only; there is no
- * timer.
- *
- * Measured 2026-09-22 on account d, claude-opus-5, effort low: a session
- * with 71,853 cache-read tokens on a control turn was compacted in print
- * mode. The `/compact` call's own JSON result reports `num_turns: 0` and
- * zero usage, so it cannot be used as evidence. The session transcript
- * gained a `compact_boundary` record (`trigger: manual`,
- * `preTokens: 71899`), the session id was unchanged, and the next turn read
- * 10,383 cache tokens plus 9,136 cache-creation tokens and still recalled a
- * value from before the compaction. The transcript boundary is therefore
- * the success signal this module checks.
- *
- * Nothing here logs the prompt, the summary or a response body. The
- * transcript is read only for `compact_boundary` system records, and only
- * their `compactMetadata.preTokens` is kept.
- */
-import type { LaneCompactionRecord, LaneProvider, LaneRecord, LaneRunUsage } from "./types.js";
-export declare const COMPACTION_MECHANISM: "claude_print_compact";
-/** The whole prompt of the compaction turn. */
-export declare const COMPACTION_PROMPT = "/compact";
-/** Upper bound on the synchronous `/compact` call. */
-export declare const COMPACTION_TIMEOUT_MS: number;
-export interface CompactionDecision {
-    due: boolean;
-    reference_at: string;
-    elapsed_ms: number;
-    threshold_ms: number;
-}
-/**
- * Whether a resume of this lane must compact first. The reference is the
- * last accepted operator message, else the lane's creation (the brief is the
- * first message). Only Claude lanes resume a session, so only they compact.
- */
-export declare function compactionDue(lane: Pick<LaneRecord, "provider" | "last_message_at" | "created_at">, nowMs: number, thresholdMs: number): CompactionDecision;
-export interface CompactBoundaryProbe {
-    count: number;
-    last_pre_tokens: number | null;
-}
-export interface ProviderCompactionDelta {
-    count: number;
-    next_offset: number;
-    replaced: boolean;
-}
-/** Read newly appended, newline-complete marker records after a saved byte offset. */
-export declare function probeProviderCompactionsSince(transcriptPath: string, provider: LaneProvider, startOffset: number): ProviderCompactionDelta;
-export declare function providerTranscriptSize(transcriptPath: string): number;
-/**
- * Read only provider compaction markers from a lane transcript. Claude writes
- * `system/compact_boundary`; Codex rollout files write a top-level
- * `compacted` record. Tool and prompt contents are never returned or logged.
- */
-export declare function probeProviderCompactions(transcriptPath: string | null, provider: LaneProvider): number;
-/** Locate `<home>/projects/<cwd-slug>/<sid>.jsonl` without deriving the slug. */
-export declare function findSessionTranscript(home: string, sessionId: string): string | null;
-/** Count compact boundaries in a transcript. Other lines are never parsed. */
-export declare function probeCompactBoundaries(transcriptPath: string | null): CompactBoundaryProbe;
-export interface CompactionCommandResult {
-    status: number | null;
-    error?: string;
-}
-export type RunCompactionFn = (input: {
-    command: string;
-    args: string[];
-    env: NodeJS.ProcessEnv;
-    cwd: string;
-    stderrPath: string;
-    timeoutMs: number;
-}) => CompactionCommandResult;
-/** Synchronous `/compact`. stdout is discarded; stderr goes to the run dir. */
-export declare const defaultRunCompaction: RunCompactionFn;
-export interface CompactLaneSessionInput {
-    command: string;
-    /** Full argv of `claude -p --resume <sid> "/compact" …`, built by buildProviderCommand. */
-    args: string[];
-    sessionId: string;
-    accountHome: string;
-    env: NodeJS.ProcessEnv;
-    cwd: string;
-    logsDir: string;
-    decision: CompactionDecision;
-    before: LaneRunUsage | null;
-    now: () => Date;
-    run?: RunCompactionFn;
-    locateTranscript?: (home: string, sessionId: string) => string | null;
-}
-/**
- * Run `/compact` on the recorded session and report what happened. A failed
- * or ineffective compaction is recorded, not thrown: the resume that needed
- * it still has a message to deliver.
- */
-export declare function compactLaneSession(input: CompactLaneSessionInput): LaneCompactionRecord;
-/**
- * Counters of the first run after the last compaction. Known once that run
- * has exited and no later run has started: the watcher writes
- * `last_run_usage` at exit, and `last_resume.at` still equals the
- * compaction's `resume_at`.
- */
-export declare function compactionAfterUsage(lane: LaneRecord): LaneRunUsage | null;
-//# sourceMappingURL=compaction.d.ts.map

package/dist/lib/lanes/compaction.js

@@ -1,293 +0,0 @@
-/**
- * Automatic compaction of a resumed Claude lane.
- *
- * Owner directives 2026-09-22: "if it's been an hour since last msg, always
- * run compact" and "there should be a way to run compact automatically using
- * code written in hqcli".
- *
- * Every `--resume` replays the whole conversation. When a resume is due
- * (`now - last_message_at >= compact_after_ms`), hq-cli first runs
- * `claude -p --resume <sid> "/compact"` in the lane's account, then starts
- * the resume as usual. The decision is made at resume time only; there is no
- * timer.
- *
- * Measured 2026-09-22 on account d, claude-opus-5, effort low: a session
- * with 71,853 cache-read tokens on a control turn was compacted in print
- * mode. The `/compact` call's own JSON result reports `num_turns: 0` and
- * zero usage, so it cannot be used as evidence. The session transcript
- * gained a `compact_boundary` record (`trigger: manual`,
- * `preTokens: 71899`), the session id was unchanged, and the next turn read
- * 10,383 cache tokens plus 9,136 cache-creation tokens and still recalled a
- * value from before the compaction. The transcript boundary is therefore
- * the success signal this module checks.
- *
- * Nothing here logs the prompt, the summary or a response body. The
- * transcript is read only for `compact_boundary` system records, and only
- * their `compactMetadata.preTokens` is kept.
- */
-import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-export const COMPACTION_MECHANISM = "claude_print_compact";
-/** The whole prompt of the compaction turn. */
-export const COMPACTION_PROMPT = "/compact";
-/** Upper bound on the synchronous `/compact` call. */
-export const COMPACTION_TIMEOUT_MS = 10 * 60 * 1000;
-/**
- * Whether a resume of this lane must compact first. The reference is the
- * last accepted operator message, else the lane's creation (the brief is the
- * first message). Only Claude lanes resume a session, so only they compact.
- */
-export function compactionDue(lane, nowMs, thresholdMs) {
-    const reference_at = lane.last_message_at ?? lane.created_at;
-    const refMs = Date.parse(reference_at);
-    const elapsed_ms = Number.isFinite(refMs) ? nowMs - refMs : 0;
-    return {
-        due: lane.provider === "claude" && Number.isFinite(refMs) && elapsed_ms >= thresholdMs,
-        reference_at,
-        elapsed_ms,
-        threshold_ms: thresholdMs,
-    };
-}
-function isProviderMarkerLine(line, lineNumber, transcriptPath, provider) {
-    const needle = provider === "claude" ? "compact_boundary" : "compacted";
-    if (!line.includes(needle))
-        return false;
-    let record;
-    try {
-        const parsed = JSON.parse(line);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return false;
-        record = parsed;
-    }
-    catch (err) {
-        process.stderr.write(`hq lanes: skipped unparseable provider transcript marker line ${lineNumber} in ${transcriptPath}: ${err instanceof Error ? err.message : String(err)}\n`);
-        return false;
-    }
-    return ((provider === "claude" && record.type === "system" && record.subtype === "compact_boundary") ||
-        (provider === "codex" && record.type === "compacted"));
-}
-/** Read newly appended, newline-complete marker records after a saved byte offset. */
-export function probeProviderCompactionsSince(transcriptPath, provider, startOffset) {
-    if (provider === "grok")
-        return { count: 0, next_offset: startOffset, replaced: false };
-    const fd = fs.openSync(transcriptPath, "r");
-    try {
-        const size = fs.fstatSync(fd).size;
-        if (startOffset > size)
-            return { count: 0, next_offset: size, replaced: true };
-        if (startOffset === size)
-            return { count: 0, next_offset: size, replaced: false };
-        const chunkSize = 1024 * 1024;
-        const lineParts = [];
-        let count = 0;
-        let position = startOffset;
-        let nextOffset = startOffset;
-        let lineNumber = 0;
-        while (position < size) {
-            const chunk = Buffer.allocUnsafe(Math.min(chunkSize, size - position));
-            const read = fs.readSync(fd, chunk, 0, chunk.length, position);
-            if (read === 0)
-                break;
-            position += read;
-            let lineStart = 0;
-            for (let index = 0; index < read; index += 1) {
-                if (chunk[index] !== 0x0a)
-                    continue;
-                lineParts.push(chunk.subarray(lineStart, index));
-                const line = Buffer.concat(lineParts).toString("utf8");
-                lineParts.length = 0;
-                lineNumber += 1;
-                if (isProviderMarkerLine(line, lineNumber, transcriptPath, provider))
-                    count += 1;
-                lineStart = index + 1;
-                nextOffset = position - (read - lineStart);
-            }
-            if (lineStart < read)
-                lineParts.push(chunk.subarray(lineStart, read));
-        }
-        return {
-            count,
-            next_offset: nextOffset,
-            replaced: false,
-        };
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-export function providerTranscriptSize(transcriptPath) {
-    try {
-        return fs.statSync(transcriptPath).size;
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return 0;
-        throw err;
-    }
-}
-/**
- * Read only provider compaction markers from a lane transcript. Claude writes
- * `system/compact_boundary`; Codex rollout files write a top-level
- * `compacted` record. Tool and prompt contents are never returned or logged.
- */
-export function probeProviderCompactions(transcriptPath, provider) {
-    if (transcriptPath === null)
-        return 0;
-    if (provider === "grok")
-        return 0;
-    try {
-        return probeProviderCompactionsSince(transcriptPath, provider, 0).count;
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return 0;
-        throw err;
-    }
-}
-/** Locate `<home>/projects/<cwd-slug>/<sid>.jsonl` without deriving the slug. */
-export function findSessionTranscript(home, sessionId) {
-    const projects = path.join(home, "projects");
-    let dirs;
-    try {
-        dirs = fs.readdirSync(projects);
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT")
-            return null;
-        throw err;
-    }
-    for (const dir of dirs) {
-        const candidate = path.join(projects, dir, `${sessionId}.jsonl`);
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
-/** Count compact boundaries in a transcript. Other lines are never parsed. */
-export function probeCompactBoundaries(transcriptPath) {
-    if (transcriptPath === null)
-        return { count: 0, last_pre_tokens: null };
-    let text;
-    try {
-        text = fs.readFileSync(transcriptPath, "utf8");
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT")
-            return { count: 0, last_pre_tokens: null };
-        throw err;
-    }
-    let count = 0;
-    let last = null;
-    for (const line of text.split("\n")) {
-        if (!line.includes('"compact_boundary"'))
-            continue;
-        let rec;
-        try {
-            rec = JSON.parse(line);
-        }
-        catch (err) {
-            process.stderr.write(`hq lanes: skipped an unparseable line in ${transcriptPath}: ${err instanceof Error ? err.message : String(err)}\n`);
-            continue;
-        }
-        if (rec.type !== "system" || rec.subtype !== "compact_boundary")
-            continue;
-        count += 1;
-        const meta = rec.compactMetadata;
-        const pre = meta?.preTokens;
-        last = typeof pre === "number" && Number.isFinite(pre) ? pre : null;
-    }
-    return { count, last_pre_tokens: last };
-}
-/** Synchronous `/compact`. stdout is discarded; stderr goes to the run dir. */
-export const defaultRunCompaction = (input) => {
-    fs.mkdirSync(path.dirname(input.stderrPath), { recursive: true });
-    const errFd = fs.openSync(input.stderrPath, "a");
-    try {
-        const result = spawnSync(input.command, input.args, {
-            cwd: input.cwd,
-            env: input.env,
-            stdio: ["ignore", "ignore", errFd],
-            timeout: input.timeoutMs,
-        });
-        if (result.error) {
-            return { status: result.status, error: result.error.message };
-        }
-        return { status: result.status };
-    }
-    finally {
-        fs.closeSync(errFd);
-    }
-};
-/**
- * Run `/compact` on the recorded session and report what happened. A failed
- * or ineffective compaction is recorded, not thrown: the resume that needed
- * it still has a message to deliver.
- */
-export function compactLaneSession(input) {
-    const run = input.run ?? defaultRunCompaction;
-    const locate = input.locateTranscript ?? findSessionTranscript;
-    const started = input.now();
-    const beforeProbe = probeCompactBoundaries(locate(input.accountHome, input.sessionId));
-    const result = run({
-        command: input.command,
-        args: input.args,
-        env: input.env,
-        cwd: input.cwd,
-        stderrPath: path.join(input.logsDir, "compact.err"),
-        timeoutMs: COMPACTION_TIMEOUT_MS,
-    });
-    const afterProbe = probeCompactBoundaries(locate(input.accountHome, input.sessionId));
-    const duration_ms = input.now().getTime() - started.getTime();
-    let outcome;
-    let reason;
-    if (afterProbe.count > beforeProbe.count) {
-        outcome = "compacted";
-    }
-    else if (result.status !== 0 || result.error !== undefined) {
-        outcome = "failed";
-        reason = result.error ?? `exit status ${String(result.status)}`;
-    }
-    else {
-        outcome = "no_effect";
-        reason = "the session transcript gained no compact_boundary record";
-    }
-    if (outcome !== "compacted") {
-        process.stderr.write(`hq lanes: compaction of session ${input.sessionId} ${outcome}: ${reason ?? ""}\n`);
-    }
-    return {
-        at: started.toISOString(),
-        mechanism: COMPACTION_MECHANISM,
-        session_id: input.sessionId,
-        outcome,
-        ...(reason !== undefined ? { reason } : {}),
-        duration_ms,
-        elapsed_ms: input.decision.elapsed_ms,
-        reference_at: input.decision.reference_at,
-        pre_tokens: outcome === "compacted" ? afterProbe.last_pre_tokens : null,
-        before: input.before,
-        after: null,
-    };
-}
-/**
- * Counters of the first run after the last compaction. Known once that run
- * has exited and no later run has started: the watcher writes
- * `last_run_usage` at exit, and `last_resume.at` still equals the
- * compaction's `resume_at`.
- */
-export function compactionAfterUsage(lane) {
-    const c = lane.last_compaction;
-    if (c === undefined)
-        return null;
-    if (c.after !== null)
-        return c.after;
-    if (c.resume_at === undefined || lane.state === "running" || lane.state === "queued") {
-        return null;
-    }
-    if (lane.last_resume?.at !== c.resume_at)
-        return null;
-    return lane.last_run_usage ?? null;
-}
-//# sourceMappingURL=compaction.js.map

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

@@ -1,91 +0,0 @@
-/**
- * Load and validate personal/lanes/config.json (spec §5.5).
- *
- * A missing file is the documented defaults, not an error. A `providers` key
- * outside {claude, codex, grok} is rejected with the accepted list. Account
- * homes are canonicalised with realpath; two account ids for one provider
- * that resolve to the same home are refused (identity-keyed-cap rule).
- */
-import * as fs from "node:fs";
-import { type AccountConfig, type LaneProvider, type LanesConfig, type RunawaySearchGuardConfig, type LivenessWindows, type ProviderConfig, type TrackerChecksConfig } from "./types.js";
-export declare const LANES_CONFIG_REL: string;
-export declare const DEFAULT_MAX_QUEUED = 3;
-export declare const DEFAULT_CPU_BUSY_PAUSE = 0.85;
-export declare const DEFAULT_CPU_BUSY_RESUME = 0.7;
-export declare const DEFAULT_MIN_AVAILABLE_MEM_MB = 1024;
-/**
- * Owner directive 2026-09-22: "if it's been an hour since last msg, always
- * run compact". Override per provider with `compact_after_ms`.
- */
-export declare const DEFAULT_COMPACT_AFTER_MS: number;
-/**
- * Claude Code's auto-compaction window, in tokens. Override with
- * `providers.claude.auto_compact_tokens`.
- */
-export declare const DEFAULT_AUTO_COMPACT_TOKENS = 200000;
-/**
- * Watcher `lane_progress` throttle: at most one thread event per five minutes
- * per lane, and only when the tick saw new activity. Override per provider
- * with `progress_event_min_interval_ms`.
- */
-export declare const DEFAULT_PROGRESS_EVENT_MIN_INTERVAL_MS: number;
-/** Account hold after a 429 that names no reset time (`quota_default_hold_ms`). */
-export declare const DEFAULT_QUOTA_HOLD_MS: number;
-/** Spec §9: last event within 10 minutes → live. */
-export declare const DEFAULT_LIVE_WITHIN_MS: number;
-/** Spec §9: turn_start with no turn_end after 2 hours → lost. */
-export declare const DEFAULT_TURN_START_LOST_MS: number;
-/** Spec §9: no event for 12 hours (and no session_end) → lost. */
-export declare const DEFAULT_SILENT_LOST_MS: number;
-/** Unanswered session questions move to the next audience after 10 minutes. */
-export declare const DEFAULT_SESSION_QUESTION_TIMEOUT_SECS: number;
-/** Open manager blockers are re-verified every four hours by default. */
-export declare const DEFAULT_BLOCKER_FRESHNESS_HOURS = 4;
-/** Manager key results must be re-measured within six hours by default. */
-export declare const DEFAULT_KR_FRESHNESS_HOURS = 6;
-export declare const DEFAULT_TRACKER_CHECKS: TrackerChecksConfig;
-export declare const DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG: RunawaySearchGuardConfig;
-export declare const DEFAULT_LIVENESS_WINDOWS: LivenessWindows;
-export declare const DEFAULT_PROVIDER_MAX_RUNNING: Record<LaneProvider, number>;
-export declare const DEFAULT_ACCOUNT_HOMES: Record<LaneProvider, string>;
-export interface ConfigLoadDeps {
-    homedir: () => string;
-    realpathSync: (p: string) => string;
-    existsSync: (p: string) => boolean;
-    readFileSync: (p: string, encoding: "utf8") => string;
-}
-export declare function expandHome(home: string, homedir: string): string;
-/**
- * Canonical principal for an account home: realpath when the path exists,
- * otherwise resolve existing ancestors and rejoin the missing tail so two
- * not-yet-created spellings of the same directory still collide.
- */
-export declare function canonicalizeHome(home: string, deps?: Pick<ConfigLoadDeps, "homedir" | "realpathSync" | "existsSync">): string;
-export declare function assertUniqueAccountHomes(provider: LaneProvider, accounts: Record<string, AccountConfig>): void;
-export declare function documentedDefaultConfig(deps?: ConfigLoadDeps): LanesConfig;
-export declare function parseLanesConfig(raw: unknown, deps?: ConfigLoadDeps): LanesConfig;
-export declare function lanesConfigPath(hqRoot: string): string;
-/**
- * Load operator config. Missing file → documented defaults. Unreadable or
- * invalid JSON is an error (never a silent default).
- */
-export declare function loadLanesConfig(hqRoot: string, deps?: ConfigLoadDeps): LanesConfig;
-export interface ConfigWriteDeps {
-    mkdirSync: typeof fs.mkdirSync;
-    writeFileSync: typeof fs.writeFileSync;
-    renameSync: typeof fs.renameSync;
-    unlinkSync: typeof fs.unlinkSync;
-}
-/** Persist operator config. Homes are stored as already-canonicalised paths. */
-export declare function writeLanesConfig(hqRoot: string, config: LanesConfig, deps?: ConfigWriteDeps): void;
-/** Resume-time compaction threshold for a provider, defaulting to one hour. */
-export declare function providerCompactAfterMs(provider: ProviderConfig): number;
-/** Claude Code auto-compaction threshold, defaulting to 200,000 tokens. */
-export declare function providerAutoCompactTokens(provider: ProviderConfig): number;
-/** Minimum gap between two `lane_progress` events, defaulting to five minutes. */
-export declare function providerProgressEventMinIntervalMs(provider: ProviderConfig): number;
-/** Hold for a reset-less 429 on this provider's accounts. */
-export declare function providerQuotaDefaultHoldMs(provider: ProviderConfig): number;
-/** Account running cap, defaulting to the provider ceiling when unset. */
-export declare function accountMaxRunning(provider: ProviderConfig, accountId: string): number;
-//# sourceMappingURL=config.d.ts.map