@yagni-app/code-staging 1.0.0-staging.1174.1 → 1.0.0-staging.1177.1

package/dist/cli.js

@@ -27,6 +27,7 @@ import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { tokenCommand } from "./token.js";
 import { buildLaunch } from "./launch.js";
+import { parseOutputFormat, parseJsonEvents, buildResultObject, readGuardianEvents, } from "./outputFormat.js";
 import { runDoctor } from "./doctor.js";
 import { installProcessCrashHandlers } from "./crashReport.js";
 import { currentCliVersion, maybeNudgeAndRefresh, upgradeCommand } from "./upgrade.js";
@@ -159,6 +160,10 @@ export function seedHideThinkingBlock(piAgentDir) {
     return seedSetting(piAgentDir, "hideThinkingBlock", true);
 }
 async function runDefault(passthroughArgs) {
+    // Parse --output-format out of argv before passing to pi (pi doesn't know
+    // about it). The format determines how we handle pi's stdout: text = inherit,
+    // stream-json = inherit with --mode json, json = pipe + post-process.
+    const { format: outputFormat, remainingArgs } = parseOutputFormat(passthroughArgs);
     // Cache-backed update nudge (never a network wait), then a background cache
     // refresh that completes while the session runs. Both fail soft.
     await maybeNudgeAndRefresh({ current: cliVersion() });
@@ -237,7 +242,7 @@ async function runDefault(passthroughArgs) {
     // re-login in another terminal is picked up here with no stale cached token.
     let plan;
     try {
-        plan = buildLaunch(creds, passthroughArgs, {
+        plan = buildLaunch(creds, remainingArgs, {
             extensionPath: resolveExtensionPath(),
             agentDir: piAgentDir,
             piPackageDir: shadowPiDir,
@@ -260,18 +265,57 @@ async function runDefault(passthroughArgs) {
         process.stderr.write(`${warning}\n`);
     }
     const { env, argv } = plan;
+    // For json/stream-json output, inject --mode json so pi emits NDJSON events.
+    // Don't override if the user already chose --mode (mirrors userChoseProvider/
+    // userChoseModel in buildLaunch). Appended at the end — pi's flag parser
+    // handles --mode anywhere in argv.
+    const userChoseMode = remainingArgs.some((a) => a === "--mode" || a.startsWith("--mode="));
+    const childArgv = outputFormat === "text" || userChoseMode
+        ? argv
+        : [...argv, "--mode", "json"];
+    // text + stream-json: inherit stdout (passthrough). json: pipe stdout so we
+    // can post-process the NDJSON into a single result object.
+    const stdio = outputFormat === "json"
+        ? ["inherit", "pipe", "inherit"]
+        : "inherit";
     const piCli = resolvePiCliPath();
+    const startMs = Date.now();
     return await new Promise((resolve) => {
-        const child = spawn(process.execPath, [piCli, ...argv], {
-            stdio: "inherit",
+        const child = spawn(process.execPath, [piCli, ...childArgv], {
+            stdio: stdio,
             env,
         });
+        // Collect pi's stdout when piping for --output-format json.
+        let stdoutChunks = "";
+        if (outputFormat === "json" && child.stdout) {
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                stdoutChunks += chunk;
+            });
+        }
         // Forward termination signals to pi instead of dying around it (see
         // signalForward.ts for the policy: first signal graceful, second tree-kill).
         installSignalForwarding(child);
         // 128+n for a signal death (bash parity), so a cancelled/killed run never
         // reads as success to scripts or CI.
-        child.on("exit", (code, signal) => resolve(exitCodeFor(code, signal)));
+        child.on("exit", (code, signal) => {
+            const exitCode = exitCodeFor(code, signal);
+            if (outputFormat === "json") {
+                const durationMs = Date.now() - startMs;
+                const events = parseJsonEvents(stdoutChunks);
+                const yagniSessionId = env.YAGNI_SESSION_ID ?? "";
+                const guardianEvents = readGuardianEvents(yagniSessionId);
+                const verbose = remainingArgs.includes("--verbose");
+                const result = buildResultObject({
+                    events,
+                    guardianEvents,
+                    durationMs,
+                    verbose,
+                });
+                process.stdout.write(`${JSON.stringify(result)}\n`);
+            }
+            resolve(exitCode);
+        });
         child.on("error", (err) => {
             process.stderr.write(`Failed to start YAGNI Code: ${err.message}\n`);
             resolve(1);
@@ -286,6 +330,8 @@ export const HELP_TEXT = [
     "  yagni -c                 Continue the most recent session.",
     "  yagni -r                 Browse and resume a previous session.",
     '  yagni -p "prompt"        Print one response and exit (reads piped stdin too).',
+    '  yagni -p "prompt"        Use --output-format json for a machine-readable',
+    '    --output-format json   result object with tools, cost, guardian reviews.',
     "  yagni login              Authorize the active environment (device-code flow).",
     "  yagni logout             Revoke and clear the active environment's token.",
     "  yagni doctor             Check that everything is ready (green/red checklist).",
@@ -307,6 +353,9 @@ export const HELP_TEXT = [
     "  --model <tier>           Model tier (fixed to advanced).",
     "  --thinking <level>       off | minimal | low | medium | high | xhigh | max",
     "  --session <id>           Open a specific session; --fork <id> branches one.",
+    "  --output-format <fmt>    Output format: text (default), json, stream-json.",
+    "                           json emits a single result object; stream-json",
+    "                           emits NDJSON events (same as --mode json).",
     "  --mode json              Emit machine-readable events (for scripts and CI).",
     "",
     "In a session:",

package/dist/extension/askAdvisorTool.js

@@ -32,6 +32,7 @@ import { SPINNER_FRAMES } from "./pipeline/activityFeed.js";
 import { withResilience } from "./pipeline/resilience.js";
 import { runStage as defaultRunStage } from "./pipeline/runner.js";
 import { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
+import { logEvent } from "./errorSink.js";
 import { applyChildEvent, finalizeTask, formatWorkingMessage, newTaskProgress, progressSummaryText, receiptLine, renderSubagentResult, runningLines, } from "./subagentRender.js";
 /**
  * Read-only recon plus grounding. Mirrors the `plan` stage's allowlist for the
@@ -288,6 +289,7 @@ export function registerAdviseCommand(pi, tool) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
+                logEvent({ source: "advisor", level: "error", event: "advise_failed", fields: { kind: "consult" } });
                 notify(`/advise failed: ${message}`, "error");
                 await pi.sendUserMessage(`/advise failed: ${message}`);
             }

package/dist/extension/cmux/state.js

@@ -1,6 +1,4 @@
-import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { codeStateHome } from "../stateHome.js";
+import { logEvent } from "../errorSink.js";
 export function firstString(...values) {
     for (const value of values) {
         if (typeof value === "string" && value.trim().length > 0)
@@ -132,20 +130,15 @@ export function settleTurn(sessionStates, sessionId) {
     return completion;
 }
 export function warn(ctx, message, details = {}, notifyUser = false) {
-    const payload = { source: "yagni-cmux-bridge", level: "warning", message, ...details };
     // The TUI is in raw mode: writing to stdout/stderr corrupts the terminal (the
-    // JSON was landing at the prompt cursor). Route warnings/errors to a rotating
-    // local log instead — never to the terminal.
-    try {
-        if (!process.env.NODE_TEST_CONTEXT) {
-            const path = join(codeStateHome(null), "logs", "cmux-bridge.log");
-            mkdirSync(dirname(path), { recursive: true });
-            appendFileSync(path, JSON.stringify({ ts: new Date().toISOString(), ...payload }) + "\n", "utf8");
-        }
-    }
-    catch {
-        /* logging must never throw into the editor */
-    }
+    // JSON was landing at the prompt cursor). Route warnings/errors to the unified
+    // local sink instead — never to the terminal.
+    logEvent({
+        source: "cmux",
+        level: "warn",
+        event: "cmux_bridge",
+        fields: { message, ...details },
+    });
     if (notifyUser) {
         try {
             ctx?.notifyWarning?.();

package/dist/extension/crashReport.js

@@ -27,6 +27,7 @@
 import { spawn } from "node:child_process";
 import { scrubSecrets } from "./pipeline/scrubSecrets.js";
 import { isDesktopSurface } from "./surface.js";
+import { logEvent } from "./errorSink.js";
 const defaultSpawn = (command, args, options) => spawn(command, args, options);
 export const CRASH_REPORT_DISABLE_ENV = "YAGNI_DISABLE_CRASH_REPORTS";
 export const CRASH_REPORT_TIMEOUT_MS = 1_500;
@@ -267,6 +268,17 @@ export function reportFatalCrash(error, opts, context) {
 export function installUncaughtExceptionMonitor(opts, proc = process) {
     proc.on("uncaughtExceptionMonitor", (err) => {
         reportFatalCrash(err, opts, "uncaught-exception");
+        // Also seed the local error trail (best-effort): the crash report is a
+        // sanitized POST, but the ON-DISK trail is what /feedback binds for a
+        // report someone files next session.
+        logEvent({
+            source: "tool",
+            level: "error",
+            event: "uncaught_exception",
+            sessionId: process.env.YAGNI_SESSION_ID ?? undefined,
+            flush: "sync",
+            fields: { errorClass: err instanceof Error ? err.name || "Error" : "Error" },
+        });
     });
 }
 //# sourceMappingURL=crashReport.js.map

package/dist/extension/decisionCapture.js

@@ -17,6 +17,7 @@
  * never affects the tool call that triggered it.
  */
 import { bankDecision } from "./decisions.js";
+import { logEvent } from "./errorSink.js";
 /** At most one capture prompt per this window (spec: 10 minutes). */
 export const CAPTURE_DEBOUNCE_MS = 10 * 60 * 1000;
 /** Build a session-scoped decision capture (holds the debounce timestamp). */
@@ -54,10 +55,12 @@ export function makeDecisionCapture(deps) {
                     ctx.ui.notify("Saved the decision locally; it will sync automatically.", "info");
                 }
                 else {
+                    logEvent({ source: "decision-capture", level: "error", event: "capture_failed", fields: { kind: outcome.kind } });
                     ctx.ui.notify(outcome.message, "error");
                 }
             }
             catch {
+                logEvent({ source: "decision-capture", level: "error", event: "capture_failed", fields: { kind: "threw" } });
                 /* fail-soft: a capture failure never affects the tool call */
             }
         },

package/dist/extension/decisions.js

@@ -20,6 +20,7 @@
 import { randomUUID } from "node:crypto";
 import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
 import { sendOrSpool } from "./spool.js";
+import { logEvent } from "./errorSink.js";
 /**
  * Bank a `cli_correction` decision durably. Every logical write carries a
  * generated idempotencyKey; the backend dedups on it, so a spool replay or a
@@ -151,6 +152,7 @@ export function registerDecisionCommands(pi, opts) {
                 notify(notice.message, notice.type);
             }
             catch (err) {
+                logEvent({ source: "decisions", level: "error", event: "decide_failed", fields: { op: "decide" } });
                 notify(`Could not record the decision: ${err instanceof Error ? err.message : String(err)}`, "error");
             }
         },
@@ -183,6 +185,7 @@ export function registerDecisionCommands(pi, opts) {
                     notify(`Superseded decision ${shortId(id)}.`, "info");
                 }
                 catch (err) {
+                    logEvent({ source: "decisions", level: "error", event: "supersede_failed", fields: { op: "supersede" } });
                     notify(`Could not supersede decision: ${err instanceof Error ? err.message : String(err)}`, "error");
                 }
                 return;
@@ -192,6 +195,7 @@ export function registerDecisionCommands(pi, opts) {
                 await pi.sendUserMessage(formatDecisionsList(items));
             }
             catch (err) {
+                logEvent({ source: "decisions", level: "error", event: "list_failed", fields: { op: "list" } });
                 notify(`Could not list decisions: ${err instanceof Error ? err.message : String(err)}`, "error");
             }
         },

package/dist/extension/diagnostics.d.ts

@@ -12,10 +12,10 @@
  * A support flow can tail this file and POST it with the user's consent;
  * nothing is uploaded automatically.
  */
+import { readSessionTrail } from "./errorSink.js";
 export declare function _setDiagnosticsHomeForTest(dir: string | null): void;
+/** Active unified-sink path (one rotating per-day JSONL for all sources). */
 export declare function diagnosticsLogPath(): string;
-/** Dedicated log for the ask_user_question interactive tool's state machine. */
-export declare function askQuestionLogPath(): string;
 /** Layer A: verbose mode. `YAGNI_DEBUG=1` (or "true") turns on extra detail. */
 export declare function isDebug(env?: NodeJS.ProcessEnv): boolean;
 export interface ImagePasteEvent {
@@ -56,7 +56,8 @@ export interface AskQuestionEvent {
     checked?: boolean;
 }
 /**
- * Append one sanitized ask-user-question event to `ask-question.log`.
+ * Append one sanitized ask-user-question event to the unified sink
+ * (source:"ask-question").
  * Fail-soft and hermetically gated under `node --test` exactly like
  * `logImagePaste`. Never logs user-typed text, question text, or option labels
  * — only indices, lengths, key bytes (escaped), and resolution status.
@@ -66,4 +67,6 @@ export declare function logAskQuestion(ev: AskQuestionEvent): void;
 export declare function readRecentDiagnostics(maxBytes?: number): string;
 /** List existing diagnostic log files (active + rotations), for a report. */
 export declare function listDiagnosticFiles(): string[];
+/** Re-export the session-scoped trail reader for the /feedback flow. */
+export { readSessionTrail };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/extension/diagnostics.js

@@ -12,26 +12,19 @@
  * A support flow can tail this file and POST it with the user's consent;
  * nothing is uploaded automatically.
  */
-import { appendFileSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
-import { codeStateHome } from "./stateHome.js";
+import { _setErrorSinkHomeForTest, logEvent, errorSinkPath, readSessionTrail, } from "./errorSink.js";
 /** Test seam (mirrors `_setYagniCodeHomeForTest`): point the log at a tmpdir. */
 let homeOverride = null;
 export function _setDiagnosticsHomeForTest(dir) {
     homeOverride = dir;
+    _setErrorSinkHomeForTest(dir);
 }
-function yagniCodeHome() {
-    return codeStateHome(homeOverride);
-}
+/** Active unified-sink path (one rotating per-day JSONL for all sources). */
 export function diagnosticsLogPath() {
-    return join(yagniCodeHome(), "logs", "image-paste.log");
-}
-/** Dedicated log for the ask_user_question interactive tool's state machine. */
-export function askQuestionLogPath() {
-    return join(yagniCodeHome(), "logs", "ask-question.log");
+    return errorSinkPath();
 }
-const MAX_LOG_BYTES = 256 * 1024; // rotate the active file past this
-const KEEP_ROTATIONS = 2; // keep image-paste.log.1 and .2 alongside the active file
 /** Layer A: verbose mode. `YAGNI_DEBUG=1` (or "true") turns on extra detail. */
 export function isDebug(env = process.env) {
     const v = env.YAGNI_DEBUG;
@@ -42,88 +35,55 @@ export function isDebug(env = process.env) {
  * prompt. `detail` is included only when YAGNI_DEBUG is on.
  */
 export function logImagePaste(ev) {
-    try {
-        // Hermetic under `node --test`: never touch the real home dir from a test
-        // unless the test explicitly stubbed it. Writing to the runner's $HOME made
-        // the suite's exit depend on the CI filesystem (a read-only or slow $HOME
-        // could stall the write), which is the leading suspect for the CI hang.
-        if (process.env.NODE_TEST_CONTEXT && homeOverride === null)
-            return;
-        const line = {
-            ts: new Date().toISOString(),
-            event: ev.event,
-            ...(ev.outcome !== undefined ? { outcome: ev.outcome } : {}),
-            ...(ev.mimeType !== undefined ? { mimeType: ev.mimeType } : {}),
-            ...(ev.bytes !== undefined ? { bytes: ev.bytes } : {}),
-            ...(ev.imageCount !== undefined ? { imageCount: ev.imageCount } : {}),
-            ...(ev.file !== undefined ? { file: basename(ev.file) } : {}),
-            ...(ev.detail !== undefined && isDebug() ? { detail: ev.detail } : {}),
-        };
-        const path = diagnosticsLogPath();
-        mkdirSync(dirname(path), { recursive: true });
-        rotateIfNeeded(path);
-        appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
-    }
-    catch {
-        /* logging must never throw into the editor */
-    }
-}
-/** Shift image-paste.log -> .1 -> .2 once the active file passes the size cap. */
-function rotateIfNeeded(path) {
-    try {
-        if (statSync(path).size < MAX_LOG_BYTES)
-            return;
-        for (let i = KEEP_ROTATIONS; i >= 1; i--) {
-            const from = i === 1 ? path : `${path}.${i - 1}`;
-            const to = `${path}.${i}`;
-            try {
-                renameSync(from, to);
-            }
-            catch {
-                /* absent source — fine */
-            }
-        }
-    }
-    catch {
-        /* rotation is best-effort */
-    }
+    // The unified sink: content-free fields are always-on, the debug-only
+    // `detail` rides level:debug (never bound by /feedback).
+    const fields = {
+        ...(ev.outcome !== undefined ? { outcome: ev.outcome } : {}),
+        ...(ev.mimeType !== undefined ? { mimeType: ev.mimeType } : {}),
+        ...(ev.bytes !== undefined ? { bytes: ev.bytes } : {}),
+        ...(ev.imageCount !== undefined ? { imageCount: ev.imageCount } : {}),
+        ...(ev.file !== undefined ? { file: basename(ev.file) } : {}),
+        ...(ev.detail !== undefined && isDebug() ? { detail: ev.detail } : {}),
+    };
+    logEvent({
+        source: "image-paste",
+        level: ev.detail !== undefined && isDebug() ? "debug" : "info",
+        event: ev.event,
+        fields,
+    });
 }
 /**
- * Append one sanitized ask-user-question event to `ask-question.log`.
+ * Append one sanitized ask-user-question event to the unified sink
+ * (source:"ask-question").
  * Fail-soft and hermetically gated under `node --test` exactly like
  * `logImagePaste`. Never logs user-typed text, question text, or option labels
  * — only indices, lengths, key bytes (escaped), and resolution status.
  */
 export function logAskQuestion(ev) {
-    try {
-        if (process.env.NODE_TEST_CONTEXT && homeOverride === null)
-            return;
-        const line = {
-            ts: new Date().toISOString(),
-            event: ev.event,
-            ...(ev.selectedIndex !== undefined ? { selectedIndex: ev.selectedIndex } : {}),
-            ...(ev.otherIndex !== undefined ? { otherIndex: ev.otherIndex } : {}),
-            ...(ev.otherLen !== undefined ? { otherLen: ev.otherLen } : {}),
-            ...(ev.status !== undefined ? { status: ev.status } : {}),
-            ...(ev.multi !== undefined ? { multi: ev.multi } : {}),
-            ...(ev.qIndex !== undefined ? { qIndex: ev.qIndex } : {}),
-            ...(ev.checked !== undefined ? { checked: ev.checked } : {}),
-            ...(ev.key !== undefined ? { key: ev.key } : {}),
-            ...(ev.detail !== undefined && isDebug() ? { detail: ev.detail } : {}),
-        };
-        const path = askQuestionLogPath();
-        mkdirSync(dirname(path), { recursive: true });
-        rotateIfNeeded(path);
-        appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
-    }
-    catch {
-        /* logging must never throw into the tool */
-    }
+    // Raw key bytes (`key`) and `detail` are content-ish: gate them behind DEBUG.
+    const debug = isDebug();
+    const fields = {
+        ...(ev.selectedIndex !== undefined ? { selectedIndex: ev.selectedIndex } : {}),
+        ...(ev.otherIndex !== undefined ? { otherIndex: ev.otherIndex } : {}),
+        ...(ev.otherLen !== undefined ? { otherLen: ev.otherLen } : {}),
+        ...(ev.status !== undefined ? { status: ev.status } : {}),
+        ...(ev.multi !== undefined ? { multi: ev.multi } : {}),
+        ...(ev.qIndex !== undefined ? { qIndex: ev.qIndex } : {}),
+        ...(ev.checked !== undefined ? { checked: ev.checked } : {}),
+        ...(ev.key !== undefined && debug ? { key: ev.key } : {}),
+        ...(ev.detail !== undefined && debug ? { detail: ev.detail } : {}),
+    };
+    logEvent({
+        source: "ask-question",
+        level: debug ? "debug" : "info",
+        event: ev.event,
+        fields,
+    });
 }
 /** Read the most recent log content (for a user-triggered report). */
 export function readRecentDiagnostics(maxBytes = 64 * 1024) {
     try {
-        const data = readFileSync(diagnosticsLogPath(), "utf8");
+        const data = readFileSync(errorSinkPath(), "utf8");
         return data.length > maxBytes ? data.slice(data.length - maxBytes) : data;
     }
     catch {
@@ -133,9 +93,9 @@ export function readRecentDiagnostics(maxBytes = 64 * 1024) {
 /** List existing diagnostic log files (active + rotations), for a report. */
 export function listDiagnosticFiles() {
     try {
-        const dir = dirname(diagnosticsLogPath());
+        const dir = dirname(errorSinkPath());
         return readdirSync(dir)
-            .filter((f) => f.startsWith("image-paste.log"))
+            .filter((f) => f.startsWith("errors-"))
             .sort()
             .map((f) => join(dir, f));
     }
@@ -143,4 +103,6 @@ export function listDiagnosticFiles() {
         return [];
     }
 }
+/** Re-export the session-scoped trail reader for the /feedback flow. */
+export { readSessionTrail };
 //# sourceMappingURL=diagnostics.js.map

package/dist/extension/errorSink.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The unified local error/log sink for YAGNI Code (YAG-580).
+ *
+ * Replaces the previous ~9 hand-rolled JSONL writers (image-paste.log,
+ * ask-question.log, turn-lifecycle.log, guardian.log, cost-divergence.log,
+ * auth-events.log, cmux-bridge.log, hooks.log, *.stream.log) with ONE sink.
+ *
+ * Two storage layers, purpose-named so their roles stay clear:
+ *
+ *  1. The DURABLE TRAIL — one rotating per-day JSONL under
+ *     `~/.yagni-code/logs/errors-<date>.jsonl` (size-capped + 2 rotations).
+ *     This is the crash-survivable WAL: `turn_start` without a matching
+ *     `turn_end` still leaves a record even if the process is killed. Critical
+ *     events append SYNCHRONOUSLY for exactly that reason.
+ *
+ *  2. The IN-MEMORY CAPTURE — a byte-budgeted ring buffer (not line-counted).
+ *     This is the `/feedback` binding convenience, NOT durability (an in-memory
+ *     ring does not survive a crash). Mirrors Codex's CodexFeedback ring and
+ *     Claude's inMemoryErrorLog.
+ *
+ * Every line carries a REQUIRED `sessionId` and a `source`/`level`/`event`
+ * triple so a shared file stays filterable: `jq 'select(.source=="guardian")'`
+ * reproduces today's per-file tail exactly, and /feedback reads the trail
+ * filtered by sessionId (never the raw file) so one session's report never
+ * leaks another session's errors.
+ *
+ * Default-on vs DEBUG invariant (the thing that makes "log everything by
+ * default" safe): default-on == scrub-safe == upload-safe. Any field carrying
+ * raw content (tool arguments, partial/result bodies, provider payloads, raw
+ * key bytes) must be gated behind YAGNI_DEBUG, and the /feedback reader refuses
+ * to bind any `level: debug` line. DEBUG == may-contain-content == never-uploads.
+ */
+export type SinkLevel = "error" | "warn" | "info" | "debug";
+export interface SinkEvent {
+    /** Former filename / subsystem: tool, turn, guardian, image-paste, ask-question, cost, auth, cmux, hooks. */
+    source: string;
+    level: SinkLevel;
+    /** Stable machine name (e.g. "turn_start", "bash.exit_1", "denied"). */
+    event: string;
+    /** Additional structured fields. NEVER raw content on a non-debug line. */
+    fields?: Record<string, unknown>;
+    /** Session id so the trail is filterable and scoped per feedback. Defaults to YAGNI_SESSION_ID. */
+    sessionId?: string;
+    /** "sync" flushes immediately (critical events); "buffered" is fine for high-volume debug. */
+    flush?: "sync" | "buffered";
+}
+export declare function _setErrorSinkHomeForTest(dir: string | null): void;
+export declare function errorSinkPath(now?: Date): string;
+export declare function _clearErrorSinkRingForTest(): void;
+export declare function errorSinkInMemory(): string;
+/**
+ * Append one event to both the ring and the durable trail. Fail-soft: a logging
+ * failure must never break the session. `flush: "sync"` (default for
+ * error-level events and lifecycle turns) bypasses any future buffering so a
+ * turn that starts but never ends still leaves a durable `turn_start`.
+ */
+export declare function logEvent(ev: SinkEvent): void;
+/**
+ * Read recent trail lines for ONE session, filtered by `sessionId`, up to
+ * `maxBytes`. Never returns `level: debug` lines — the default-on tier is the
+ * upload-safe tier, and DEBUG may contain content that must not leave the machine.
+ */
+export declare function readSessionTrail(sessionId: string, maxBytes?: number): string;
+//# sourceMappingURL=errorSink.d.ts.map