@yagni-app/code 0.3.4 → 1.0.0

package/dist/extension/errorSink.js

@@ -0,0 +1,180 @@
+/**
+ * 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.
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { codeStateHome } from "./stateHome.js";
+import { scrubSecrets } from "./pipeline/scrubSecrets.js";
+const MAX_LOG_BYTES = 256 * 1024;
+const KEEP_ROTATIONS = 2;
+const RING_MAX_BYTES = 256 * 1024;
+/** Test seam: point the log at a tmpdir (mirrors _setDiagnosticsHomeForTest). */
+let homeOverride = null;
+export function _setErrorSinkHomeForTest(dir) {
+    homeOverride = dir;
+}
+function logDir() {
+    return join(codeStateHome(homeOverride), "logs");
+}
+function dayStamp(now = new Date()) {
+    return now.toISOString().slice(0, 10); // YYYY-MM-DD
+}
+export function errorSinkPath(now = new Date()) {
+    return join(logDir(), `errors-${dayStamp(now)}.jsonl`);
+}
+/** In-memory ring buffer, byte-budgeted (trailing bytes kept when over cap). */
+class RingBuffer {
+    maxBytes;
+    chunks = [];
+    bytes = 0;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    push(line) {
+        const b = Buffer.byteLength(line, "utf8");
+        if (b >= this.maxBytes) {
+            this.chunks = [line];
+            this.bytes = b;
+            return;
+        }
+        while (this.bytes + b > this.maxBytes && this.chunks.length > 0) {
+            const dropped = this.chunks.shift();
+            this.bytes -= Buffer.byteLength(dropped, "utf8");
+        }
+        this.chunks.push(line);
+        this.bytes += b;
+    }
+    snapshot() {
+        return this.chunks.join("");
+    }
+    clear() {
+        this.chunks = [];
+        this.bytes = 0;
+    }
+}
+const ring = new RingBuffer(RING_MAX_BYTES);
+export function _clearErrorSinkRingForTest() {
+    ring.clear();
+}
+export function errorSinkInMemory() {
+    return ring.snapshot();
+}
+function rotateIfNeeded(path) {
+    try {
+        if (!statSync(path).isFile() || 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 */
+    }
+}
+function isDebug(env = process.env) {
+    const v = env.YAGNI_DEBUG;
+    return v === "1" || v === "true";
+}
+function sessionIdFor(ev) {
+    return ev.sessionId ?? process.env.YAGNI_SESSION_ID ?? "";
+}
+function serialize(ev) {
+    const line = {
+        ts: new Date().toISOString(),
+        source: ev.source,
+        level: ev.level,
+        event: ev.event,
+        sessionId: sessionIdFor(ev),
+        ...(ev.fields ?? {}),
+    };
+    return JSON.stringify(line) + "\n";
+}
+/**
+ * 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 function logEvent(ev) {
+    try {
+        if (process.env.NODE_TEST_CONTEXT && homeOverride === null)
+            return;
+        const line = serialize(ev);
+        ring.push(line);
+        const path = errorSinkPath();
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path);
+        appendFileSync(path, line, "utf8");
+    }
+    catch {
+        /* logging must never throw into the editor */
+    }
+}
+/**
+ * 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 function readSessionTrail(sessionId, maxBytes = 64 * 1024) {
+    try {
+        const data = readFileSync(errorSinkPath(), "utf8");
+        // Defense-in-depth: scrub each kept line so /diagnostics and /feedback
+        // never surface a secret or local path, even if a future caller slipped a
+        // content-bearing value onto an always-on line.
+        const lines = data
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .filter((l) => {
+            try {
+                const obj = JSON.parse(l);
+                return obj.sessionId === sessionId && obj.level !== "debug";
+            }
+            catch {
+                return false;
+            }
+        })
+            .map((l) => scrubSecrets(l))
+            .join("\n");
+        return lines.length > maxBytes ? lines.slice(lines.length - maxBytes) : lines;
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=errorSink.js.map

package/dist/extension/feedbackCommand.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The `/feedback` (alias `/bug`) command + the `/diagnostics` companion
+ * (YAG-580).
+ *
+ * `/feedback` captures the session transcript (pi's own append-only JSONL, read
+ * via `ctx.sessionManager` — never reconstructed from YAGNI_SESSION_ID, which is
+ * the proxy-attribution id), the session-scoped error trail (from the unified
+ * sink), any child `/go` run transcripts, a sanitized `yagni doctor` report, and
+ * git metadata — sanitizes the whole bundle with the shared scrub contract, and
+ * POSTs it to the YAGNI backend (opt-in, gated, named-human).
+ *
+ * `/diagnostics` is the read-only companion: it prints the last N sink lines for
+ * THIS session so the user can see what failed before deciding to attach it.
+ *
+ * Both treat the transcript as best-effort enrichment: pi's flush-to-file timing
+ * at command-invoke is not guaranteed, so a report never claims the reporting
+ * turn is captured unless it verifiably is.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface FeedbackDeps {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** Sanitized `yagni doctor` output (string), or undefined to omit. */
+    getDoctorReport?: () => Promise<string | undefined>;
+    /** Git facts for the report; undefined fields are omitted. */
+    getGitState?: (cwd: string) => Promise<{
+        branch?: string;
+        commit?: string;
+        remote?: string;
+        dirty?: boolean;
+    }>;
+    /** Child `/go` run transcripts keyed by run id, for the current run tree. */
+    getChildTranscripts?: (cwd: string, sessionFile: string | undefined) => Promise<Record<string, string>>;
+}
+export declare function registerFeedbackCommands(pi: ExtensionAPI, deps: FeedbackDeps): void;
+//# sourceMappingURL=feedbackCommand.d.ts.map

package/dist/extension/feedbackCommand.js

@@ -0,0 +1,151 @@
+/**
+ * The `/feedback` (alias `/bug`) command + the `/diagnostics` companion
+ * (YAG-580).
+ *
+ * `/feedback` captures the session transcript (pi's own append-only JSONL, read
+ * via `ctx.sessionManager` — never reconstructed from YAGNI_SESSION_ID, which is
+ * the proxy-attribution id), the session-scoped error trail (from the unified
+ * sink), any child `/go` run transcripts, a sanitized `yagni doctor` report, and
+ * git metadata — sanitizes the whole bundle with the shared scrub contract, and
+ * POSTs it to the YAGNI backend (opt-in, gated, named-human).
+ *
+ * `/diagnostics` is the read-only companion: it prints the last N sink lines for
+ * THIS session so the user can see what failed before deciding to attach it.
+ *
+ * Both treat the transcript as best-effort enrichment: pi's flush-to-file timing
+ * at command-invoke is not guaranteed, so a report never claims the reporting
+ * turn is captured unless it verifiably is.
+ */
+import { readFileSync } from "node:fs";
+import { scrubSecrets } from "./pipeline/scrubSecrets.js";
+import { readSessionTrail } from "./errorSink.js";
+const MAX_DESCRIPTION = 512;
+const MAX_TRANSCRIPT_READ_BYTES = 512 * 1024;
+const notify = (ctx, message, type) => {
+    if (ctx.hasUI)
+        ctx.ui.notify(message, type);
+};
+function redact(text) {
+    return scrubSecrets(text);
+}
+/**
+ * Read the durable transcript, clamped by byte size. Returns empty on any
+ * failure or when too large (mirrors Claude's MAX_TRANSCRIPT_READ_BYTES guard).
+ */
+function readTranscript(sessionFile) {
+    if (!sessionFile)
+        return "";
+    try {
+        const data = readFileSync(sessionFile, "utf8");
+        if (Buffer.byteLength(data, "utf8") > MAX_TRANSCRIPT_READ_BYTES)
+            return "";
+        return data;
+    }
+    catch {
+        return "";
+    }
+}
+async function handleFeedback(args, ctx, deps) {
+    const sessionId = ctx.sessionManager.getSessionId?.() ?? deps.env?.YAGNI_SESSION_ID ?? "";
+    const sessionFile = ctx.sessionManager.getSessionFile?.();
+    const cwd = ctx.cwd;
+    const description = args.trim()
+        ? args.trim()
+        : await ctx.ui.input("Describe the issue", "What went wrong, in one or two lines?");
+    if (!description || description.trim().length === 0) {
+        notify(ctx, "Feedback cancelled.", "info");
+        return;
+    }
+    if (!ctx.isIdle()) {
+        notify(ctx, "YAGNI Code is busy; wait for the current turn to finish before /feedback.", "warning");
+        return;
+    }
+    const transcript = readTranscript(sessionFile);
+    const trail = readSessionTrail(sessionId);
+    const doctorReport = deps.getDoctorReport
+        ? await deps.getDoctorReport().catch(() => undefined)
+        : undefined;
+    const git = deps.getGitState
+        ? await deps.getGitState(cwd).catch(() => ({}))
+        : {};
+    const childTranscripts = deps.getChildTranscripts
+        ? await deps.getChildTranscripts(cwd, sessionFile).catch(() => ({}))
+        : {};
+    // Consent: enumerate exactly what is about to leave the machine.
+    const lines = [
+        "Your feedback description",
+        `This session's transcript${transcript ? "" : " (could not be read — possibly one turn stale)"}`,
+        `${Object.keys(childTranscripts).length} child run transcript(s)`,
+        "Recent error trail for this session",
+        ...(doctorReport ? ["Sanitized yagni doctor report"] : []),
+        ...(git.branch ? ["Git metadata (branch/commit/remote/dirty)"] : []),
+    ];
+    const ok = await ctx.ui.confirm("Submit feedback?", lines.join("\n     - ") + "\n\nSend this report?");
+    if (!ok) {
+        notify(ctx, "Feedback cancelled.", "info");
+        return;
+    }
+    const payload = {
+        client: "cli",
+        clientVersion: deps.env?.YAGNI_CODE_VERSION?.trim() || "unknown",
+        platform: `${process.platform} ${process.arch}`,
+        description: redact(description).slice(0, MAX_DESCRIPTION),
+        sessionId,
+        ...(transcript ? { transcriptJsonl: redact(transcript) } : {}),
+        ...(trail ? { errorTrailJsonl: redact(trail) } : {}),
+        ...(Object.keys(childTranscripts).length > 0
+            ? { childTranscripts: Object.fromEntries(Object.entries(childTranscripts).map(([k, v]) => [k, redact(v)])) }
+            : {}),
+        ...(doctorReport ? { doctorReport: redact(doctorReport) } : {}),
+        ...(git.branch ? { gitBranch: git.branch } : {}),
+        ...(git.commit ? { gitCommit: git.commit } : {}),
+        ...(git.remote ? { gitRemote: git.remote } : {}),
+        ...(git.dirty !== undefined ? { gitDirty: git.dirty } : {}),
+    };
+    try {
+        const fetchImpl = deps.fetchImpl ?? fetch;
+        const res = await fetchImpl(`${deps.baseUrl.replace(/\/$/, "")}/api/yagni-code/feedback`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${deps.getToken() ?? ""}`,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (res.ok) {
+            notify(ctx, "Feedback submitted. Thank you!", "info");
+        }
+        else {
+            notify(ctx, "Could not submit feedback. Please try again.", "error");
+        }
+    }
+    catch {
+        notify(ctx, "Could not submit feedback (network error). Please try again.", "error");
+    }
+}
+export function registerFeedbackCommands(pi, deps) {
+    pi.registerCommand("feedback", {
+        description: "File a bug report with your session transcript + error trail attached.",
+        handler: (args, ctx) => handleFeedback(args, ctx, deps),
+    });
+    pi.registerCommand("bug", {
+        description: "Alias for /feedback.",
+        handler: (args, ctx) => handleFeedback(args, ctx, deps),
+    });
+    pi.registerCommand("diagnostics", {
+        description: "Show recent error-trail lines for this session.",
+        handler: async (_args, ctx) => {
+            const sessionId = ctx.sessionManager.getSessionId?.() ?? deps.env?.YAGNI_SESSION_ID ?? "";
+            const trail = readSessionTrail(sessionId, 16 * 1024);
+            if (!trail) {
+                notify(ctx, "No recent diagnostics for this session.", "info");
+                return;
+            }
+            const lines = trail.split("\n").filter(Boolean);
+            const tail = lines.slice(-20);
+            notify(ctx, `Recent diagnostics (${lines.length} events):\n${tail.join("\n")}`, "info");
+        },
+    });
+}
+//# sourceMappingURL=feedbackCommand.js.map

package/dist/extension/hooks.js

@@ -17,11 +17,12 @@
  * Fail-soft: a broken hook degrades to "no hook," never to "broken session."
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, appendFileSync, existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import { codeStateHome } from "./stateHome.js";
 import { isDebug } from "./diagnostics.js";
+import { logEvent } from "./errorSink.js";
 const SUPPORTED_EVENTS = [
     "SessionStart",
     "UserPromptSubmit",
@@ -286,16 +287,15 @@ export function parseCompactCancel(stdout) {
 function logHookEvent(env, payload) {
     if (!isDebug(env))
         return;
-    try {
-        if (process.env.NODE_TEST_CONTEXT)
-            return;
-        const logPath = join(codeStateHome(null, env), "logs", "hooks.log");
-        mkdirSync(dirname(logPath), { recursive: true });
-        appendFileSync(logPath, JSON.stringify({ ts: new Date().toISOString(), ...payload }) + "\n", "utf8");
-    }
-    catch {
-        // logging must never break the session
-    }
+    const event = typeof payload.event === "string" ? payload.event : "hook_event";
+    const { event: _ignored, ...fields } = payload;
+    logEvent({
+        source: "hooks",
+        level: "debug",
+        event,
+        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+        fields,
+    });
 }
 /** Filter hook groups by workspace trust: project-level groups are skipped when untrusted. */
 function filterByTrust(groups, isTrusted) {

package/dist/extension/index.d.ts

@@ -120,6 +120,7 @@ export default function (pi: ExtensionAPI): Promise<void>;
 export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+export { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
 export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs, } from "./permission/guardian.js";
 export type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./permission/guardian.js";

package/dist/extension/index.js

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
 import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./permission/approvedPrefixes.js";
 import { redactCommand } from "./redact.js";
 import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs } from "./permission/guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+import { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
+import { makeWebFetchTool } from "./webFetchTool.js";
 import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 import { makeReviewBusinessMatchTool } from "./reviewTool.js";
 import { registerCmuxBridge } from "./cmux/index.js";
@@ -18,6 +18,8 @@ import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, Y
 import { claudeRulesSection } from "./claudeRules.js";
 import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
+import { logEvent } from "./errorSink.js";
+import { registerFeedbackCommands } from "./feedbackCommand.js";
 import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
 import { codeStateHome } from "./stateHome.js";
 import { logTurnLifecycle } from "./turnLog.js";
@@ -45,6 +47,7 @@ import { buildYagniProvider } from "./provider.js";
 import { registerChipEditor } from "./chipEditor.js";
 import { defaultMineBeatGit, fileMineBeatMarkers, maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, } from "./mineBeat.js";
 import { makeFlywheelState } from "./flywheel.js";
+import { registerSilentTurnReminder } from "./silentTurnReminder.js";
 function isEvalMode(env = process.env) {
     return env.YAGNI_CODE_EVAL_MODE === "1";
 }
@@ -158,6 +161,9 @@ export async function registerYagni(pi, deps = {}) {
     // (flywheel-attributed records send dedupe: true). Run 7.
     const flywheelState = makeFlywheelState();
     pi.registerTool(makeAskYagniTool({ ...toolOpts, flywheel: flywheelState, getRepo: () => sessionRepo }));
+    // WebFetch (YAG-578): read an arbitrary URL as clean markdown + a
+    // standard-tier extraction, replacing the bash + curl + python dance.
+    pi.registerTool(makeWebFetchTool(toolOpts));
     // Ticket write-back (spec 2026-08-09): explicit user-intent writes to the
     // workspace tracker, attributed to the developer via per-user credentials.
     if (!evalMode) {
@@ -176,6 +182,9 @@ export async function registerYagni(pi, deps = {}) {
     // /advise runs the SAME tool, sharing the state handle, so a manual consult
     // draws on the same cap rather than opening a side channel around it.
     registerAdviseCommand(pi, askAdvisorTool);
+    // Structured human questions: the model poses a closed 2-4-option question
+    // and gets a clean machine-readable answer via ctx.ui.custom.
+    pi.registerTool(makeAskUserQuestionTool());
     // The differentiated business-grounded tools (loop bricks): review a change
     // for business fit, rank the next work by business priority, and record the
     // engineering rationale back onto the work-item.
@@ -191,6 +200,11 @@ export async function registerYagni(pi, deps = {}) {
     // above-editor widget, and /todos. Branch-replayed, so forks and resumes
     // show the list as it stood at that point.
     registerTodos(pi);
+    // YAG-574: the silent-turn reminder, driver-only. A child/subagent/advisor
+    // process has no direct user to answer, so it is never nudged (same gating
+    // as the delegation identity in branding.ts); eval mode is untouched so its
+    // measured behavior is not perturbed.
+    registerSilentTurnReminder(pi, { isDriver: isDriverCaller(env), evalMode, env: deps.env });
     // Image paste with [Image #N] chips: replaces the editor on
     // session_start (TUI mode) so pasting a screenshot drops a chip instead of a
     // temp path, and registers the input transform that turns chips into image
@@ -238,6 +252,19 @@ export async function registerYagni(pi, deps = {}) {
     // M6 eval (report-only): /go-compare runs a ticket grounded vs blind and reports
     // the business-fit delta. Never wired to routing.
     registerGoCompareCommand(pi);
+    // YAG-580: /feedback (alias /bug) + /diagnostics. The capture/upload is the
+    // whole point, so it is gated to non-eval mode like every external side
+    // effect; the command's deps (doctor report, git state, child transcripts)
+    // are injected so the handler stays unit-testable without spawning git or
+    // reading the real session dir.
+    if (!evalMode) {
+        registerFeedbackCommands(pi, {
+            baseUrl,
+            getToken: getTokenFn,
+            fetchImpl: deps.fetchImpl,
+            env: deps.env,
+        });
+    }
     // W4 judgment loop: the decisions surface (/decide + /decisions) and the
     // bless-with-remember capture are the same product-intent write as the record
     // tools, so both are gated together (skipped in eval mode).
@@ -282,18 +309,19 @@ export async function registerYagni(pi, deps = {}) {
         ...(guardianMaxAttemptsAdvertised !== undefined ? { maxAttempts: guardianMaxAttemptsAdvertised } : {}),
     });
     guardianLimits.timeoutMs = guardianTimeoutMs;
-    // YAG-510: guardian.log stays the sanitized local debug sink (hash-only,
-    // never the command). The remote guardian-events stream below is the
-    // separate, opt-in, per-workspace analytics sink; the two are independent.
+    // YAG-510: Guardian events go to the unified sink under source:"guardian"
+    // (hash-only, never the command). The remote guardian-events stream below is
+    // the separate, opt-in, per-workspace analytics sink; the two are independent.
     const guardianLogSink = (payload) => {
-        try {
-            if (process.env.NODE_TEST_CONTEXT)
-                return;
-            const logPath = join(codeStateHome(null), "logs", "guardian.log");
-            mkdirSync(dirname(logPath), { recursive: true });
-            appendFileSync(logPath, JSON.stringify({ ts: new Date().toISOString(), ...payload }) + "\n", "utf8");
-        }
-        catch { /* logging must never break the session */ }
+        const event = typeof payload.event === "string" ? payload.event : "guardian_event";
+        const { event: _ignored, ...fields } = payload;
+        logEvent({
+            source: "guardian",
+            level: event === "guardian_event_post_failed" ? "error" : "info",
+            event,
+            sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            fields,
+        });
     };
     // YAG-510: persisted "don't ask again" grants, per-repo keyed. Loaded once
     // at startup (grants added by other concurrent sessions appear next launch —
@@ -325,7 +353,8 @@ export async function registerYagni(pi, deps = {}) {
         // "off" → nothing (not even sent); "hash" → sha256 + family prefix +
         // metadata, no command content; "raw" → adds client-REDACTED command and
         // rationale. Fire-and-forget: one attempt, short timeout, failures logged
-        // fail-soft to guardian.log — a storage outage never touches the session.
+        // fail-soft to the unified sink (source:"guardian") — a storage outage
+        // never touches the session.
         onGuardianEvent: guardianStorageTier === "off" || evalMode
             ? undefined
             : (ev) => {
@@ -363,10 +392,10 @@ export async function registerYagni(pi, deps = {}) {
                             guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
                         }
                     }
-                    catch (err) {
+                    catch {
                         guardianLogSink({
                             event: "guardian_event_post_failed",
-                            error: err instanceof Error ? err.message : "unknown",
+                            kind: "network",
                         });
                     }
                 })();
@@ -448,15 +477,13 @@ export async function registerYagni(pi, deps = {}) {
         onDivergence: (driverServerUsd, localUsd) => {
             if (!isDebug(env))
                 return;
-            try {
-                const path = join(codeStateHome(null, env), "logs", "cost-divergence.log");
-                mkdirSync(dirname(path), { recursive: true });
-                const line = { ts: new Date().toISOString(), driverServerUsd, localUsd };
-                appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
-            }
-            catch {
-                /* a diagnostic must never break /cost */
-            }
+            logEvent({
+                source: "cost",
+                level: "debug",
+                event: "cost_divergence",
+                sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                fields: { driverServerUsd, localUsd },
+            });
         },
         // Carry-over (/cost re-review): surfaces sessionRuns.ts's dropped-run-id
         // count as costHud's "Excludes N earlier /go runs." note.
@@ -685,21 +712,16 @@ export async function registerYagni(pi, deps = {}) {
                 // session token is expired and refresh failed — the most critical
                 // failure signal is no longer silently dropped.
                 void authReporter(new Error(`auth_401 on model path; refresh=${rotated ? "succeeded" : "failed"}`), "auth-failure").catch(() => { });
-                // YAG-500 Fix F: local diagnostics log under YAGNI_DEBUG.
-                if (isDebug(env)) {
-                    try {
-                        const logPath = join(codeStateHome(null, env), "logs", "auth-events.log");
-                        mkdirSync(dirname(logPath), { recursive: true });
-                        appendFileSync(logPath, JSON.stringify({
-                            ts: new Date().toISOString(),
-                            status: 401,
-                            refresh: rotated ? "succeeded" : "failed",
-                        }) + "\n", "utf8");
-                    }
-                    catch {
-                        // A diagnostic must never break the session.
-                    }
-                }
+                // YAG-500 Fix F: auth-401 signal is content-free (status + refresh
+                // boolean), so it is always-on and upload-safe by the default-on
+                // invariant. No message content, no tokens, no headers.
+                logEvent({
+                    source: "auth",
+                    level: "info",
+                    event: "auth_401",
+                    sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                    fields: { status: 401, refresh: rotated ? "succeeded" : "failed" },
+                });
                 return { message: { ...msg, errorMessage: explanation } };
             }
             // YAG-460: the backend proxy answers an oversized conversation with an
@@ -753,6 +775,16 @@ export async function registerYagni(pi, deps = {}) {
     // and a "Pi can explain its own features…" line) with a YAGNI Code masthead,
     // set the terminal title, and add a footer brand mark. TUI only.
     pi.on("session_start", async (event, ctx) => {
+        // Surface Pi's native find/grep/ls on the driver. These are Pi's
+        // equivalents of Claude Code's Glob/Grep/LS; the /go stages and subagents
+        // already pass them explicitly, but the driver defaults to read/bash/edit/write
+        // and otherwise reaches for `bash` find/grep/ls.
+        try {
+            pi.setActiveTools([...pi.getActiveTools(), "grep", "find", "ls"]);
+        }
+        catch {
+            // Tool enrichment must never break session start.
+        }
         ctx.ui?.setTitle(BRAND_NAME);
         if (ctx.mode === "tui") {
             ctx.ui?.setStatus?.("brand", BRAND_NAME);
@@ -883,6 +915,30 @@ export async function registerYagni(pi, deps = {}) {
             footerInvalidateHandle.invalidateGit();
         }
     });
+    // Seed the unified error trail from tool-exec failures. A tool's SUCCESS
+    // is content (it lives in the transcript); its FAILURE is an error and belongs
+    // in the sink. We log only the tool name + error class — never args, partial
+    // results, or result bodies (those are content and stay out of the upload-safe
+    // tier). This is the tool-failure half of the error trail the ticket asks for.
+    pi.on("tool_execution_end", (event) => {
+        if (!event.isError)
+            return;
+        // `event.result` is any; its `.error`/message can echo a path or secret
+        // (a tool's own failure text). Keep the always-on trail content-free: use
+        // ONLY the Error subclass name, never the message or a String() of the
+        // result's error payload.
+        const errorClass = event.result instanceof Error
+            ? event.result.name || "Error"
+            : "tool_error";
+        logEvent({
+            source: "tool",
+            level: "error",
+            event: "tool_failed",
+            sessionId: sessionIdForLog(),
+            flush: "sync",
+            fields: { toolName: event.toolName, errorClass },
+        });
+    });
 }
 export default async function (pi) {
     await registerYagni(pi);
@@ -896,6 +952,7 @@ export default async function (pi) {
 export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+export { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
 export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs, } from "./permission/guardian.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";