@yagni-app/code-staging 0.3.0-staging.1079.1 → 0.3.0-staging.1081.1

package/dist/extension/guardian.d.ts

@@ -13,15 +13,23 @@
  *
  * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
  * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
- * the user. On allow, the command runs. On deny, the agent sees the rationale
- * and is told to find a safer alternative or ask the user. On timeout/error,
- * auto mode fails closed (block); review mode falls back to the user prompt.
+ * the user. On allow, the command runs. On ask (YAG-510), the user arbitrates:
+ * the gate shows the Guardian's question-rationale and the user approves or
+ * declines. On deny, the agent sees the rationale and is told to find a safer
+ * alternative or ask the user. On timeout/error, auto mode falls back to an
+ * ask when a UI exists, else fails closed; review mode falls back to the
+ * ordinary user confirm.
  *
- * Circuit breaker: 3 consecutive denials in one turn → turn interrupted.
+ * Circuit breaker: 3 consecutive denials within one user prompt → escalation
+ * (ask the user once) or, headless, interruption. Denial streaks reset on
+ * `before_agent_start`, which fires once per USER PROMPT (not per LLM turn).
+ * An `ask` outcome leaves the streak untouched — neither a denial nor an
+ * exoneration — so an ask-preferring model cannot disarm the breaker by
+ * alternating deny/ask.
  */
 import { runStage as defaultRunStage } from "./pipeline/runner.js";
 import type { PipelineStage } from "./pipeline/types.js";
-export type GuardianOutcome = "allow" | "deny";
+export type GuardianOutcome = "allow" | "ask" | "deny";
 export type GuardianRiskLevel = "low" | "medium" | "high" | "critical";
 export interface GuardianVerdict {
     outcome: GuardianOutcome;
@@ -64,7 +72,7 @@ export interface CircuitBreakerResult {
 export declare function checkCircuitBreaker(state: GuardianState, limits: GuardianLimits): CircuitBreakerResult;
 export declare function parseVerdict(raw: string): GuardianVerdict | null;
 export declare function formatGuardianSubtotal(state: GuardianState, limits: GuardianLimits): string;
-export type GuardianError = "timeout" | "malformed" | "network" | "empty";
+export type GuardianError = "timeout" | "malformed" | "network" | "empty" | "aborted";
 export interface ReviewResult {
     verdict: GuardianVerdict | null;
     error?: GuardianError;
@@ -76,6 +84,14 @@ export interface ReviewCommandDeps {
     signal?: AbortSignal;
     /** Override the model tier (default: efficient). */
     modelTier?: string;
+    /** Consult timeout in ms (default: DEFAULT_GUARDIAN_LIMITS.timeoutMs). */
+    timeoutMs?: number;
+    /**
+     * The exec policy's justification for routing this command to the Guardian
+     * ("pushes to remote — confirm intent"). Included in the consult prompt so
+     * an `ask` rationale can add information beyond the static rule text.
+     */
+    execJustification?: string;
 }
 /**
  * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId

package/dist/extension/guardian.js

@@ -13,11 +13,19 @@
  *
  * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
  * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
- * the user. On allow, the command runs. On deny, the agent sees the rationale
- * and is told to find a safer alternative or ask the user. On timeout/error,
- * auto mode fails closed (block); review mode falls back to the user prompt.
+ * the user. On allow, the command runs. On ask (YAG-510), the user arbitrates:
+ * the gate shows the Guardian's question-rationale and the user approves or
+ * declines. On deny, the agent sees the rationale and is told to find a safer
+ * alternative or ask the user. On timeout/error, auto mode falls back to an
+ * ask when a UI exists, else fails closed; review mode falls back to the
+ * ordinary user confirm.
  *
- * Circuit breaker: 3 consecutive denials in one turn → turn interrupted.
+ * Circuit breaker: 3 consecutive denials within one user prompt → escalation
+ * (ask the user once) or, headless, interruption. Denial streaks reset on
+ * `before_agent_start`, which fires once per USER PROMPT (not per LLM turn).
+ * An `ask` outcome leaves the streak untouched — neither a denial nor an
+ * exoneration — so an ask-preferring model cannot disarm the breaker by
+ * alternating deny/ask.
  */
 import { runStage as defaultRunStage } from "./pipeline/runner.js";
 export const DEFAULT_GUARDIAN_LIMITS = {
@@ -49,9 +57,12 @@ export function makeGuardianState() {
             if (outcome === "deny") {
                 state.consecutiveDenials += 1;
             }
-            else {
+            else if (outcome === "allow") {
                 state.consecutiveDenials = 0;
             }
+            // "ask" leaves the denial streak UNCHANGED: it is neither a denial nor
+            // an exoneration. If it reset the streak, deny/ask/deny/ask would never
+            // trip the breaker (round-2 review blocker).
             return { ...state };
         },
         resetTurn() {
@@ -77,7 +88,7 @@ export function parseVerdict(raw) {
         const jsonStr = jsonMatch ? jsonMatch[0] : raw;
         const parsed = JSON.parse(jsonStr);
         const outcome = parsed?.outcome;
-        if (outcome !== "allow" && outcome !== "deny")
+        if (outcome !== "allow" && outcome !== "ask" && outcome !== "deny")
             return null;
         const riskLevel = parsed.riskLevel;
         const validLevels = ["low", "medium", "high", "critical"];
@@ -124,8 +135,9 @@ export function guardianStage(modelTier = GUARDIAN_MODEL_TIER) {
 export async function reviewCommand(command, deps) {
     const runStage = deps.runStage ?? defaultRunStage;
     const stage = guardianStage(deps.modelTier);
-    // Build the abort signal with the Guardian timeout.
-    const timeoutMs = DEFAULT_GUARDIAN_LIMITS.timeoutMs;
+    // Build the abort signal with the Guardian timeout (injectable — the gate
+    // threads guardianLimits.timeoutMs through).
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_GUARDIAN_LIMITS.timeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     timer.unref?.();
@@ -137,13 +149,23 @@ export async function reviewCommand(command, deps) {
             deps.signal.addEventListener("abort", () => controller.abort(), { once: true });
     }
     try {
-        const result = await runStage(stage, { ticket: `Review this shell command for safety. Output only the JSON verdict.\n\nCommand:\n${command}` }, {
+        const justificationLine = deps.execJustification
+            ? `\n\nWhy this command was routed to you (static policy): ${deps.execJustification}`
+            : "";
+        const result = await runStage(stage, { ticket: `Review this shell command for safety. Output only the JSON verdict.${justificationLine}\n\nCommand:\n${command}` }, {
             cwd: deps.cwd,
             signal: controller.signal,
             callerLabel: "guardian",
         });
         const cost = result.usage?.cost ?? 0;
         const output = result.finalOutput.trim();
+        // An aborted child often RESOLVES with empty/partial output instead of
+        // throwing (observed live: ESC → 433ms "empty"). Any result produced
+        // while the caller's signal is aborted is an abort, not an outage — the
+        // gate must not warn or fall back to an ask on it.
+        if (deps.signal?.aborted) {
+            return { verdict: null, error: "aborted", cost };
+        }
         if (!output) {
             return { verdict: null, error: "empty", cost };
         }
@@ -154,8 +176,13 @@ export async function reviewCommand(command, deps) {
         return { verdict, cost };
     }
     catch (err) {
-        // Distinguish timeout from network/process errors.
-        if (controller.signal.aborted && !deps.signal?.aborted) {
+        // Distinguish the caller aborting (user hit ESC — must NOT be treated as
+        // an outage, or the fallback ask would pop a dialog on an aborted turn),
+        // our own timeout, and real network/process errors.
+        if (deps.signal?.aborted) {
+            return { verdict: null, error: "aborted", cost: 0 };
+        }
+        if (controller.signal.aborted) {
             return { verdict: null, error: "timeout", cost: 0 };
         }
         return { verdict: null, error: "network", cost: 0 };

package/dist/extension/index.js

@@ -1,7 +1,10 @@
+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 "./approvedPrefixes.js";
+import { redactCommand } from "./redact.js";
 import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand } from "./guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
@@ -127,7 +130,7 @@ export async function registerYagni(pi, deps = {}) {
     // after_provider_response event does NOT fire on a 401 (the OpenAI SDK throws
     // before onResponse is reached), so message_end is the only seam.
     let lastAuthRecovery = null;
-    const { models: fullCatalog, guardianEnabled: workspaceGuardianEnabled } = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    const { models: fullCatalog, guardianEnabled: workspaceGuardianEnabled, guardianStorage: guardianStorageTier, } = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
     // Lock the interactive session to the `advanced` tier only. The backend
     // catalog returns all tiers, but only `advanced` is registered with the
     // `yagni` provider, so /model and Ctrl+P show a single entry. Child
@@ -245,6 +248,23 @@ export async function registerYagni(pi, deps = {}) {
         !workspaceGuardianEnabled;
     const guardianTier = env.YAGNI_GUARDIAN_TIER ?? GUARDIAN_MODEL_TIER;
     const guardianLimits = resolveGuardianLimits(env);
+    // 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.
+    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 */ }
+    };
+    // YAG-510: persisted "don't ask again" grants, per-repo keyed. Loaded once
+    // at startup (grants added by other concurrent sessions appear next launch).
+    const sessionGrants = evalMode ? [] : loadGrants();
+    const GUARDIAN_EVENT_TIMEOUT_MS = 5_000;
     registerPermissionGate(pi, {
         modeHolder,
         guardianState,
@@ -252,16 +272,63 @@ export async function registerYagni(pi, deps = {}) {
         guardianTier,
         guardianDisabled,
         guardianReview: (command, deps) => reviewCommand(command, { ...deps, modelTier: guardianTier }),
-        onGuardianReview: (ev) => {
-            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(), ...ev }) + "\n", "utf8");
-            }
-            catch { /* logging must never break the session */ }
+        onGuardianReview: (ev) => guardianLogSink(ev),
+        grants: sessionGrants,
+        resolveRepoKey,
+        persistGrant: (grant) => {
+            if (!evalMode)
+                appendGrant(grant);
         },
+        // Opt-in storage stream (YAG-510). Tier decides what leaves the machine:
+        // "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.
+        onGuardianEvent: guardianStorageTier === "off" || evalMode
+            ? undefined
+            : (ev) => {
+                void (async () => {
+                    try {
+                        const body = {
+                            sessionId: env.YAGNI_SESSION_ID ?? null,
+                            commandHash: createHash("sha256").update(ev.command).digest("hex"),
+                            commandPrefix: storagePrefix(ev.command),
+                            outcome: ev.outcome,
+                            mode: ev.mode,
+                            ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+                            ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
+                            ...(ev.tier ? { tier: ev.tier } : {}),
+                            ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
+                        };
+                        if (guardianStorageTier === "raw") {
+                            body.command = redactCommand(ev.command);
+                            if (ev.rationale)
+                                body.rationale = redactCommand(ev.rationale);
+                        }
+                        const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
+                            method: "POST",
+                            headers: {
+                                "content-type": "application/json",
+                                authorization: `Bearer ${getTokenFn() ?? ""}`,
+                                ...attributionHeaders(deps.env),
+                            },
+                            body: JSON.stringify(body),
+                        }, {
+                            fetchImpl: authedFetch,
+                            policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
+                        });
+                        if (!res.ok) {
+                            guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
+                        }
+                    }
+                    catch (err) {
+                        guardianLogSink({
+                            event: "guardian_event_post_failed",
+                            error: err instanceof Error ? err.message : "unknown",
+                        });
+                    }
+                })();
+            },
         ...(mcpMutatingTools.length > 0
             ? {
                 policy: {

package/dist/extension/permission.d.ts

@@ -27,8 +27,10 @@
  * the context so the model doesn't keep believing it is restricted.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
 import { type BlessStore } from "./bless.js";
 import { type ExecPolicy } from "./execPolicy.js";
+import { type GuardianError, type GuardianRiskLevel } from "./guardian.js";
 export type PermissionMode = "auto" | "plan" | "review";
 /**
  * A shared, mutable holder for the current permission mode. Both
@@ -76,6 +78,12 @@ export interface GateDecision {
      * command string is available.
      */
     classify?: "allow" | "prompt" | "forbidden";
+    /**
+     * The exec policy's justification for a "prompt" classification — why the
+     * command was routed to the Guardian. Threaded into the consult prompt and
+     * the storage event (it is the layer-tuning signal, YAG-510).
+     */
+    classifyJustification?: string;
 }
 /**
  * Pure permission decision for one tool call under a mode + policy. Auto allows
@@ -83,6 +91,35 @@ export interface GateDecision {
  * unless a recorded decision blesses them.
  */
 export declare function decideGate(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): GateDecision;
+/**
+ * Terminal outcome of one prompt-band decision (YAG-510). One storage event
+ * is emitted per terminal outcome; `consulted` says whether a Guardian LLM
+ * call actually happened (grants/cache hits skip it).
+ */
+export type GuardianGateOutcome = "prefix_allow" | "cached_allow" | "allow" | "deny" | "ask_approved" | "ask_approved_remembered" | "ask_denied" | "ask_headless_blocked" | "breaker_ask_approved" | "breaker_blocked" | GuardianError;
+/**
+ * Rich per-decision event for opt-in storage (YAG-510). Carries the RAW
+ * command — the wiring layer (index.ts) hashes/redacts per the workspace's
+ * storage tier before anything leaves the machine. Distinct from the
+ * sanitized GuardianDiagnosticEvent (local debug log), which never carries
+ * the command.
+ */
+export interface GuardianGateEvent {
+    command: string;
+    outcome: GuardianGateOutcome;
+    /** Why the exec policy routed this command to the Guardian. */
+    execJustification?: string;
+    riskLevel?: GuardianRiskLevel;
+    rationale?: string;
+    mode: PermissionMode;
+    tier?: string;
+    durationMs?: number;
+    /** Whether a Guardian LLM consult actually ran for this decision. */
+    consulted: boolean;
+    /** Present when the terminal outcome followed a Guardian error (e.g. an
+     * error-fallback ask that the user then approved). */
+    guardianError?: GuardianError;
+}
 /** What was blessed with "don't ask again", handed to the capture hook. */
 export interface BlessRememberInfo {
     tool: string;
@@ -123,6 +160,24 @@ export interface RegisterPermissionDeps {
     onGuardianReview?: (event: import("./guardian.js").GuardianDiagnosticEvent) => void;
     /** Disable the Guardian entirely (env var YAGNI_DISABLE_GUARDIAN). */
     guardianDisabled?: boolean;
+    /**
+     * Persisted "don't ask again" grants for this session's repo (YAG-510).
+     * Consulted ONLY after the exec policy classified a command as "prompt" —
+     * a grant can never override the forbidden band. Suppressed in review mode.
+     */
+    grants?: readonly ApprovedPrefixGrant[];
+    /** Resolve the grant scope key for a cwd (git remote origin URL fallback
+     * realpath). Lazily invoked on the first prompt-band bash call. */
+    resolveRepoKey?: (cwd: string) => string;
+    /** Persist a new grant (fire-and-forget; the in-memory list is updated
+     * either way). index.ts wires approvedPrefixes.appendGrant. */
+    persistGrant?: (grant: ApprovedPrefixGrant) => void;
+    /**
+     * Called (fire-and-forget) at every terminal prompt-band outcome with the
+     * rich storage event (raw command — the wiring layer redacts/hashes).
+     * Fail-soft; never blocks.
+     */
+    onGuardianEvent?: (event: GuardianGateEvent) => void;
 }
 /** The customType tag on injected mode-context messages (filterable later). */
 export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";