@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,110 @@
+/**
+ * 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

@@ -0,0 +1,293 @@
+/**
+ * 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

@@ -0,0 +1,94 @@
+/**
+ * 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_LOW_DISK_MIN_FREE_BYTES: number;
+export declare const DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS = 24;
+export declare const DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS = 7;
+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