peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/job-snapshot/snapshot.js

@@ -0,0 +1,75 @@
+import os from 'node:os';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Collects a coarse-grained snapshot of host + project resources.
+ * Numeric ranges are clamped to zod's domain — out-of-range values are clamped, not thrown,
+ * so callers can decide what to do.
+ */
+export function collectResourceSnapshot(jobDir) {
+    const cpus = os.cpus();
+    const loadAvg = (os.loadavg()[0] ?? 0) / (cpus.length || 1);
+    const cpuPercent = Math.max(0, Math.min(100, loadAvg * 100));
+    const totalMemMb = os.totalmem() / 1024 / 1024;
+    const freeMemMb = os.freemem() / 1024 / 1024;
+    const usedMemMb = Math.max(0, totalMemMb - freeMemMb);
+    const memMb = Math.round(usedMemMb);
+    const diskMb = dirSizeMb(jobDir);
+    // contextRatio is best-effort: pull from the same env-var the v2.13.0 auto-compact uses.
+    const envVal = process.env.CLAUDE_CONTEXT_USAGE_PERCENT;
+    const contextRatio = envVal ? Math.max(0, Math.min(1, Number(envVal) / 100)) : 0;
+    return {
+        capturedAt: new Date().toISOString(),
+        cpuPercent,
+        memMb,
+        diskMb,
+        contextRatio,
+    };
+}
+// Non-enumerable internal attachment for test-time access via
+// `collectResourceSnapshot.dirSizeMb`. NOT a public export — keeps
+// the prod module surface clean per PRD while still allowing
+// targeted AC-1/AC-2/AC-3 unit tests to drive `dirSizeMb` directly.
+Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
+    value: dirSizeMb,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Best-effort, non-recursive size of one directory level, in rounded megabytes.
+ *
+ * - Missing directory → 0.
+ * - Per-entry stat failures (race with deletion, EBUSY on Windows) → silently skipped.
+ * - When `opts.maxEntries` > 0 and the directory has more entries than the cap,
+ *   the returned value is a partial sum (a lower bound), and no further `stat`
+ *   calls are issued past the cap. Callers must treat the value as a lower bound.
+ * - `opts.maxEntries` defaults to 0 (unbounded, legacy behaviour).
+ *
+ * NOTE: when maxEntries > 0 and the directory contains more entries than the
+ * cap, this is a partial sum. Callers must treat the value as a lower bound.
+ */
+function dirSizeMb(dir, opts) {
+    const cap = opts?.maxEntries ?? 0;
+    let total = 0;
+    let index = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (cap > 0 && index >= cap)
+                break;
+            try {
+                total += statSync(join(dir, name)).size;
+            }
+            catch (e) {
+                // best-effort: missing entries (race with deletion) are silently skipped
+                void e;
+            }
+            index++;
+        }
+    }
+    catch (e) {
+        // best-effort: missing dir is treated as 0 bytes
+        void e;
+    }
+    return Math.round(total / 1024 / 1024);
+}

package/dist/services/job-snapshot/types.d.ts

@@ -0,0 +1,7 @@
+export interface ResourceSnapshot {
+    capturedAt: string;
+    cpuPercent: number;
+    memMb: number;
+    diskMb: number;
+    contextRatio: number;
+}

package/dist/services/job-snapshot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/karpathy-cost/karpathy-cost-check-service.d.ts

@@ -0,0 +1,67 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+/** Threshold above which a `'block'` is downgraded to `'warn'`. */
+export declare const KARPATHY_COST_DOWNGRADE_THRESHOLD = 10;
+/** Threshold above which a sediment line is appended for human review. */
+export declare const KARPATHY_COST_REPORT_THRESHOLD = 50;
+export interface EvaluationCost {
+    readonly wallMs: number;
+    readonly subAgentsDispatched: number;
+    readonly tokensEstimated: number;
+    readonly sliceCodeSize: number;
+}
+export type GateAction = 'pass' | 'warn' | 'block';
+export interface KarpathyReviewEnvelope {
+    readonly passed?: boolean;
+    readonly violations?: ReadonlyArray<unknown>;
+    readonly gateAction?: GateAction;
+    readonly evaluationCost?: EvaluationCost;
+    readonly costRatio?: number;
+}
+export type KarpathyCostCheckDecision = {
+    readonly kind: 'no-cost-data';
+    readonly gateAction: GateAction | null;
+    readonly reason: 'envelope-missing-evaluationCost' | 'file-missing' | 'file-unreadable' | 'envelope-not-json';
+} | {
+    readonly kind: '24h-mode-active';
+    readonly gateAction: GateAction | null;
+    readonly reason: 'peaks session 24h-mode state = 24H_ACTIVE; cost-check is the OVERRIDE, not the constrained side';
+} | {
+    readonly kind: 'downgraded';
+    readonly originalGateAction: 'block';
+    readonly newGateAction: 'warn';
+    readonly costRatio: number;
+    readonly evaluationCost: EvaluationCost;
+} | {
+    readonly kind: 'reported';
+    readonly gateAction: GateAction;
+    readonly costRatio: number;
+    readonly evaluationCost: EvaluationCost;
+} | {
+    readonly kind: 'unchanged';
+    readonly gateAction: GateAction;
+    readonly costRatio: number;
+    readonly evaluationCost: EvaluationCost;
+};
+export interface KarpathyCostCheckInput {
+    /** The karpathy-review.md file content (verbatim). */
+    readonly reviewFileContent: string;
+    /** Callable that returns true if 24h-mode is active. */
+    readonly is24hModeActive: () => boolean;
+}
+export interface KarpathyCostCheckOutput {
+    readonly decision: KarpathyCostCheckDecision;
+    /** Plain-text reason line for the CLI to print under the envelope. */
+    readonly reasonLine: string;
+}
+/**
+ * Pure: decide whether to downgrade a karpathy-reviewer gateAction.
+ * No fs / no env reads — the input is pre-loaded by the CLI.
+ */
+export declare function decideKarpathyCostCheck(input: KarpathyCostCheckInput): KarpathyCostCheckOutput;
+/** Convenience: load the review file from disk and run the decision. */
+export declare function runKarpathyCostCheck(opts: {
+    readonly reviewFilePath: string;
+    readonly is24hModeActive: () => boolean;
+}): KarpathyCostCheckOutput;
+/** Envelope-shape return for the CLI. */
+export declare function buildCostCheckEnvelope(out: KarpathyCostCheckOutput): ResultEnvelope<KarpathyCostCheckDecision>;

package/dist/services/karpathy-cost/karpathy-cost-check-service.js

@@ -0,0 +1,108 @@
+// src/services/karpathy-cost/karpathy-cost-check-service.ts
+//
+// Slice 2026-07-30-karpathy-cost-self-review (slice 2/4). The
+// karpathy-reviewer's JSON envelope is extended with `evaluationCost`
+// + `costRatio` (see agents/karpathy-reviewer.md §4). This service
+// is the orchestrator-side consumer of those fields.
+//
+// The check is intentionally small and pure-with-respect-to-its-inputs:
+//   - It reads the slice's `rd/karpathy-review.md` (a JSON envelope
+//     written by karpathy-reviewer sub-agent)
+//   - It reads the 24h-mode state via a passed-in callable (NOT
+//     a direct fs read, to keep this unit-testable in isolation)
+//   - It decides whether to auto-downgrade a `'block'` gateAction
+//     to `'warn'` based on costRatio
+//   - It returns a structured result the CLI can render with
+//     printResult()
+//
+// Backward compatibility: when evaluationCost is absent the check
+// returns `'skipped-no-cost-data'` and gateAction is left untouched
+// (the existing hard gate stays in effect — missing cost data must
+// not silently downgrade a 'block').
+import { readFileSync } from 'node:fs';
+import { ok } from 'peaks-loop-shared/result';
+/** Threshold above which a `'block'` is downgraded to `'warn'`. */
+export const KARPATHY_COST_DOWNGRADE_THRESHOLD = 10;
+/** Threshold above which a sediment line is appended for human review. */
+export const KARPATHY_COST_REPORT_THRESHOLD = 50;
+/**
+ * Pure: decide whether to downgrade a karpathy-reviewer gateAction.
+ * No fs / no env reads — the input is pre-loaded by the CLI.
+ */
+export function decideKarpathyCostCheck(input) {
+    if (input.is24hModeActive()) {
+        return {
+            decision: {
+                kind: '24h-mode-active',
+                gateAction: null,
+                reason: 'peaks session 24h-mode state = 24H_ACTIVE; cost-check is the OVERRIDE, not the constrained side',
+            },
+            reasonLine: 'karpathy-cost-check: skipped (24h-mode active)',
+        };
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(input.reviewFileContent);
+    }
+    catch {
+        return {
+            decision: { kind: 'no-cost-data', gateAction: null, reason: 'envelope-not-json' },
+            reasonLine: 'karpathy-cost-check: skipped (envelope not JSON)',
+        };
+    }
+    if (!envelope.evaluationCost || typeof envelope.costRatio !== 'number') {
+        return {
+            decision: {
+                kind: 'no-cost-data',
+                gateAction: envelope.gateAction ?? null,
+                reason: 'envelope-missing-evaluationCost',
+            },
+            reasonLine: 'karpathy-cost-check: skipped (envelope missing evaluationCost/costRatio)',
+        };
+    }
+    const costRatio = envelope.costRatio;
+    const evaluationCost = envelope.evaluationCost;
+    if (envelope.gateAction === 'block' && costRatio > KARPATHY_COST_DOWNGRADE_THRESHOLD) {
+        return {
+            decision: {
+                kind: 'downgraded',
+                originalGateAction: 'block',
+                newGateAction: 'warn',
+                costRatio,
+                evaluationCost,
+            },
+            reasonLine: `karpathy-cost-check: downgraded block → warn (costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_DOWNGRADE_THRESHOLD})`,
+        };
+    }
+    if (costRatio > KARPATHY_COST_REPORT_THRESHOLD) {
+        return {
+            decision: { kind: 'reported', gateAction: envelope.gateAction ?? 'pass', costRatio, evaluationCost },
+            reasonLine: `karpathy-cost-check: costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_REPORT_THRESHOLD} (sediment appended)`,
+        };
+    }
+    return {
+        decision: { kind: 'unchanged', gateAction: envelope.gateAction ?? 'pass', costRatio, evaluationCost },
+        reasonLine: `karpathy-cost-check: unchanged (costRatio=${costRatio.toFixed(2)})`,
+    };
+}
+/** Convenience: load the review file from disk and run the decision. */
+export function runKarpathyCostCheck(opts) {
+    let content;
+    try {
+        content = readFileSync(opts.reviewFilePath, 'utf8');
+    }
+    catch {
+        return {
+            decision: { kind: 'no-cost-data', gateAction: null, reason: 'file-missing' },
+            reasonLine: `karpathy-cost-check: skipped (file missing: ${opts.reviewFilePath})`,
+        };
+    }
+    return decideKarpathyCostCheck({
+        reviewFileContent: content,
+        is24hModeActive: opts.is24hModeActive,
+    });
+}
+/** Envelope-shape return for the CLI. */
+export function buildCostCheckEnvelope(out) {
+    return ok('karpathy-cost-check', out.decision);
+}

package/dist/services/legacy/legacy-detector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v2.15.0 follow-up — G8: legacy code detector.
+ *
+ * 12 Gaps memory: when peaks-loop is applied to a 存量老项目 (legacy
+ * codebase), it is helpful to surface a quick inventory of "what
+ * smells old" so the LLM / operator knows where to focus.
+ *
+ * Heuristics (intentionally light, since the user is Senior FE and
+ * the AI is the integrator):
+ *   - TODO / FIXME / HACK comments
+ *   - console.log calls (debug leftover)
+ *   - any-type TypeScript annotations (`as any`, `: any`)
+ *   - large files (> 500 lines)
+ *   - ts-ignore / @ts-expect-error (suppressed type errors)
+ *
+ * Pure function. No I/O. The CLI is `peaks legacy detect`.
+ */
+export type LegacyKind = 'todo' | 'console-log' | 'any-type' | 'large-file' | 'ts-ignore' | 'fixme' | 'hack';
+export interface LegacyFinding {
+    readonly kind: LegacyKind;
+    readonly file: string;
+    /** Line number, or null when the finding is file-level (e.g. large-file). */
+    readonly line: number | null;
+    /** A short excerpt of the offending line. */
+    readonly excerpt: string;
+}
+export interface LegacyReport {
+    readonly projectRoot: string;
+    readonly scannedFiles: number;
+    readonly findings: readonly LegacyFinding[];
+    readonly summary: Record<LegacyKind, number>;
+    readonly smells: 'low' | 'medium' | 'high';
+}
+export declare function detectLegacy(projectRoot: string, dir?: string): LegacyReport;

package/dist/services/legacy/legacy-detector.js

@@ -0,0 +1,111 @@
+/**
+ * v2.15.0 follow-up — G8: legacy code detector.
+ *
+ * 12 Gaps memory: when peaks-loop is applied to a 存量老项目 (legacy
+ * codebase), it is helpful to surface a quick inventory of "what
+ * smells old" so the LLM / operator knows where to focus.
+ *
+ * Heuristics (intentionally light, since the user is Senior FE and
+ * the AI is the integrator):
+ *   - TODO / FIXME / HACK comments
+ *   - console.log calls (debug leftover)
+ *   - any-type TypeScript annotations (`as any`, `: any`)
+ *   - large files (> 500 lines)
+ *   - ts-ignore / @ts-expect-error (suppressed type errors)
+ *
+ * Pure function. No I/O. The CLI is `peaks legacy detect`.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const PATTERNS = [
+    { kind: 'todo', regex: /(?:\/\/|\/\*|<!--)\s*(?:TODO|FIXME|HACK|XXX)\b/i },
+    { kind: 'console-log', regex: /\bconsole\.(log|debug|info)\s*\(/ },
+    { kind: 'any-type', regex: /\b(?:as\s+any|:\s*any\b|<any>)/ },
+    { kind: 'ts-ignore', regex: /@ts-(?:ignore|expect-error|nocheck)/ }
+];
+const LARGE_FILE_LINES = 500;
+function scanFile(file) {
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split('\n');
+    const findings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const { kind, regex } of PATTERNS) {
+            if (regex.test(line)) {
+                findings.push({ kind, file, line: i + 1, excerpt: line.trim().slice(0, 120) });
+                break; // one finding per line (avoid double-counting)
+            }
+        }
+    }
+    if (lines.length > LARGE_FILE_LINES) {
+        findings.push({ kind: 'large-file', file, line: null, excerpt: `${lines.length} lines (> ${LARGE_FILE_LINES})` });
+    }
+    return findings;
+}
+function walkFiles(root, maxDepth = 8) {
+    const out = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist' || e.name === 'node_modules' || e.name.startsWith('.'))
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDirectory())
+                walk(full, depth + 1);
+            else if (e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.js') || e.name.endsWith('.tsx') || e.name.endsWith('.jsx'))) {
+                out.push(full);
+            }
+        }
+    }
+    walk(root, 0);
+    return out;
+}
+export function detectLegacy(projectRoot, dir = 'src') {
+    const root = resolve(projectRoot, dir);
+    if (!existsSync(root)) {
+        const empty = { todo: 0, 'console-log': 0, 'any-type': 0, 'large-file': 0, 'ts-ignore': 0, fixme: 0, hack: 0 };
+        return { projectRoot, scannedFiles: 0, findings: [], summary: empty, smells: 'low' };
+    }
+    const files = walkFiles(root);
+    const findings = [];
+    for (const f of files) {
+        findings.push(...scanFile(f));
+    }
+    // Re-key console-log to match the union
+    const mapped = findings.map((f) => f.kind === 'console-log' ? { ...f, kind: 'console-log' } : f);
+    const summary = {
+        todo: 0, 'console-log': 0, 'any-type': 0, 'large-file': 0, 'ts-ignore': 0, fixme: 0, hack: 0
+    };
+    for (const f of mapped) {
+        // The todo pattern catches both TODO and FIXME/HACK; reflect into fixme/hack as well when applicable
+        if (f.kind === 'todo') {
+            const lc = f.excerpt.toLowerCase();
+            if (lc.includes('fixme'))
+                summary.fixme++;
+            else if (lc.includes('hack'))
+                summary.hack++;
+            else
+                summary.todo++;
+        }
+        else {
+            summary[f.kind]++;
+        }
+    }
+    const total = Object.values(summary).reduce((s, n) => s + n, 0);
+    const smells = total > 50 ? 'high' : total > 10 ? 'medium' : 'low';
+    return { projectRoot, scannedFiles: files.length, findings: mapped, summary, smells };
+}

package/dist/services/log/log-commands-service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Service layer for `peaks log tail` and `peaks log ls` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Pure helpers that the
+ * commander layer in `src/cli/commands/log-commands.ts` wraps.
+ * Separated from `logger.ts` so the surface is small + testable
+ * without spinning up a Commander program.
+ *
+ * Both helpers default to the on-disk log dir (`resolveLogDir()`)
+ * but accept an `dirOverride` so tests can pin the home to a
+ * tempdir without monkey-patching `os.homedir()`.
+ */
+import { type LogEntry } from './logger.js';
+/**
+ * Return all `peaks-loop-*.log` files in the log dir, sorted by
+ * date descending (newest first). Returns `[]` when the dir is
+ * missing or unreadable. Non-matching entries (e.g. a stray
+ * README) are filtered out.
+ */
+export declare function listLogFiles(opts?: {
+    dirOverride?: string;
+}): string[];
+export type TailLogOptions = {
+    /** Number of trailing lines to return. Defaults to 50. */
+    lines?: number;
+    /** Override the clock for deterministic tests. */
+    now?: () => Date;
+    /** Override the log dir (used by tests). */
+    dirOverride?: string;
+    /** Override the date (PRD AC2: PEAKS_LOG_DATE_OVERRIDE). */
+    dateOverride?: string;
+    /**
+     * Slice 2026-06-23-audit-4th #B2: filter by batchId. When set,
+     * only entries whose `batchId` field matches are returned (and
+     * the trailing-window accounting respects the post-filter total
+     * so a busy day does not push old matching entries out of view).
+     */
+    batchId?: string;
+};
+export type TailLogResult = {
+    /** Absolute path to the file that was tailed, or null when no file exists. */
+    file: string | null;
+    /** The trailing entries (already trimmed to `lines`). */
+    entries: LogEntry[];
+    /** The total number of entries in the file (for header messaging). */
+    total: number;
+    /** When `batchId` filter is applied, the number of matches in the file. */
+    batchMatches?: number;
+};
+/**
+ * Read today's log file and return the last `lines` entries. When
+ * no file exists for the given date, returns `{ file: null, entries: [], total: 0 }`.
+ */
+export declare function tailLog(opts?: TailLogOptions): TailLogResult;

package/dist/services/log/log-commands-service.js

@@ -0,0 +1,83 @@
+/**
+ * Service layer for `peaks log tail` and `peaks log ls` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Pure helpers that the
+ * commander layer in `src/cli/commands/log-commands.ts` wraps.
+ * Separated from `logger.ts` so the surface is small + testable
+ * without spinning up a Commander program.
+ *
+ * Both helpers default to the on-disk log dir (`resolveLogDir()`)
+ * but accept an `dirOverride` so tests can pin the home to a
+ * tempdir without monkey-patching `os.homedir()`.
+ */
+import { readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildLogFileName, readLogEntries, resolveLogDir } from './logger.js';
+const LOG_FILE_NAME_PATTERN = /^peaks-loop-\d{4}-\d{2}-\d{2}\.log$/;
+/**
+ * Return all `peaks-loop-*.log` files in the log dir, sorted by
+ * date descending (newest first). Returns `[]` when the dir is
+ * missing or unreadable. Non-matching entries (e.g. a stray
+ * README) are filtered out.
+ */
+export function listLogFiles(opts = {}) {
+    const logDir = opts.dirOverride ?? resolveLogDir();
+    if (!existsSync(logDir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(logDir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => LOG_FILE_NAME_PATTERN.test(name))
+        .filter((name) => {
+        try {
+            return statSync(join(logDir, name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort()
+        .reverse();
+}
+/**
+ * Read today's log file and return the last `lines` entries. When
+ * no file exists for the given date, returns `{ file: null, entries: [], total: 0 }`.
+ */
+export function tailLog(opts = {}) {
+    const lines = opts.lines ?? 50;
+    const logDir = opts.dirOverride ?? resolveLogDir();
+    const now = opts.now ? opts.now() : new Date();
+    const dateForFile = opts.dateOverride !== undefined
+        ? new Date(`${opts.dateOverride}T00:00:00.000Z`)
+        : now;
+    const fileName = buildLogFileName(dateForFile);
+    const fullPath = join(logDir, fileName);
+    const allEntries = readLogEntries({
+        now: () => now,
+        ...(opts.dirOverride !== undefined ? { dirOverride: opts.dirOverride } : {}),
+        ...(opts.dateOverride !== undefined ? { dateOverride: opts.dateOverride } : {})
+    });
+    const total = allEntries.length;
+    if (total === 0) {
+        return { file: null, entries: [], total: 0 };
+    }
+    // Slice 2026-06-23-audit-4th #B2: batchId filter — apply AFTER the
+    // read but BEFORE the trailing window, so a single batch's
+    // interleaved log lines surface as a coherent sequence instead of
+    // being pushed out by sibling-batch lines.
+    const filtered = opts.batchId !== undefined
+        ? allEntries.filter((e) => e.batchId === opts.batchId)
+        : allEntries;
+    if (filtered.length === 0) {
+        return { file: fullPath, entries: [], total, batchMatches: 0 };
+    }
+    const trailing = filtered.slice(Math.max(0, filtered.length - lines));
+    return opts.batchId !== undefined
+        ? { file: fullPath, entries: trailing, total, batchMatches: filtered.length }
+        : { file: fullPath, entries: trailing, total };
+}

package/dist/services/log/logger.d.ts

@@ -0,0 +1,103 @@
+/**
+ * JSONL file logger for peaks-loop.
+ *
+ * Slice 2026-06-16-cli-logging (G1, G2, G5, G6, G7).
+ *
+ * Default-on file logging: every peaks-loop invocation writes a
+ * structured log entry to `<homedir>/.peaks/logs/peaks-loop-YYYY-MM-DD.log`
+ * (UTC date stamp). One JSON object per line.
+ *
+ * Hard contracts enforced here:
+ *  - stdout is NEVER touched by the logger (G7). Use the returned
+ *    `LogLine` string and pipe it to the file only.
+ *  - The log dir is created lazily on first write (G1).
+ *  - File mode is 0o600 on POSIX (R3). Windows uses ACLs and the
+ *    0o600 bit is a no-op there; the call is best-effort.
+ *  - All write paths go through `redact` so a leaked secret can
+ *    never reach disk (G6).
+ *  - The log level can be overridden via `PEAKS_LOG_LEVEL` (G3) and
+ *    `PEAKS_LOG_DATE_OVERRIDE` (AC2) for deterministic tests.
+ *
+ * No third-party deps (R1): `fs.appendFileSync` + `JSON.stringify`
+ * is enough; pino/winston are NOT pulled in.
+ */
+import { dirname } from 'node:path';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogEntry = {
+    ts: string;
+    level: LogLevel;
+    command: string;
+    msg: string;
+    sessionId?: string;
+    version?: string;
+    batchId?: string;
+    data?: Record<string, unknown>;
+};
+/**
+ * Returns the canonical log directory. On Windows, `homedir()` is
+ * `%USERPROFILE%`; on macOS / Linux, `$HOME`. The path is the
+ * user-global `~/.peaks/logs/` — never inside a project tree (NG6).
+ */
+export declare function resolveLogDir(): string;
+/**
+ * Returns the UTC date-stamped file name. `date` is injectable so
+ * tests can pin the date without monkey-patching `Date`.
+ */
+export declare function buildLogFileName(date: Date): string;
+export type WriteLogOptions = {
+    /** Override the clock for deterministic tests. Defaults to `new Date()`. */
+    now?: () => Date;
+    /**
+     * Override the log dir for tests. Defaults to `resolveLogDir()`.
+     * Allows the test harness to redirect to a temp dir without
+     * monkey-patching `os.homedir()`.
+     */
+    dirOverride?: string;
+    /**
+     * Override the date used for the file name + entry `ts`. The PRD
+     * AC2 contract is `PEAKS_LOG_DATE_OVERRIDE=YYYY-MM-DD`; the
+     * program-level flag plumbing in `program.ts` reads it and passes
+     * it down. The `now` option still drives the `ts` field, so the
+     * caller MUST pass a matching `Date` for the AC2 invariant.
+     */
+    dateOverride?: string;
+};
+/**
+ * Write a single JSONL log entry. Returns the absolute file path
+ * the entry was written to, or `null` when the entry was filtered
+ * out by the current log level.
+ *
+ * Failures inside the logger (mkdir, appendFile, chmod) are caught
+ * and swallowed: a logger that takes down the CLI is worse than a
+ * logger that drops a line. The swallow is intentional per the PRD
+ * non-goals (NG1: no remote ship; the user only ever sees a file
+ * they read directly).
+ */
+export declare function writeLogEntry(entry: LogEntry, opts?: WriteLogOptions): string | null;
+export type ReadLogOptions = {
+    now?: () => Date;
+    dirOverride?: string;
+    dateOverride?: string;
+};
+/**
+ * Read the current day's log file and return all parseable JSON
+ * entries. Malformed lines are skipped (the on-disk file is JSONL,
+ * but a crash mid-write can leave a partial line; we don't want
+ * that to break `peaks log tail`).
+ */
+export declare function readLogEntries(opts?: ReadLogOptions): LogEntry[];
+/**
+ * Print a log line to stderr IF the current process is in verbose
+ * mode (`--verbose` / `-v` / `PEAKS_LOG_LEVEL=debug`). This is the
+ * G3 opt-in channel: by default, stderr stays clean so the CLI's
+ * `--json` envelope is not contaminated.
+ *
+ * Returns `true` when the line was written; `false` otherwise. The
+ * caller can use the boolean to detect silent-failure patterns (a
+ * `peaks log tail` that prints nothing when the user expected a
+ * verbose stream).
+ */
+export declare function maybeWriteStderr(entry: LogEntry, opts: {
+    verbose: boolean;
+}): boolean;
+export { dirname };