pi-warden 0.2.1 → 0.4.0

package/dist/extension.js

@@ -1,13 +1,18 @@
+import { MouseRegion, Text } from "@earendil-works/pi-tui";
 import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
 import { applyUserOverrides, defaultConfig, isMode, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
 import { classifyToolResult, doneNudge, emptyEvidence, evaluateDone, finalAssistantText, formatDone, needsDoneCheck, recordOutcome } from "./done.js";
-import { evaluateAction, formatVerdict, steerReason, textApproves } from "./guard.js";
+import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason, textApproves } from "./guard.js";
+import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
+import { openTracePanel } from "./panel.js";
+import { actionDetails, doneDetails, proseDetails, stuckDetails, Trace } from "./trace.js";
+import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
 export const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; and the agent's final message when it reports completion without running checks. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
-const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, errors: 0 });
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, errors: 0 });
 function latestUserPrompt(ctx) {
     const entries = ctx.sessionManager.getBranch();
     for (let index = entries.length - 1; index >= 0; index--) {
@@ -45,17 +50,35 @@ export function confirmMessage(verdict) {
     return lines.join("\n");
 }
 const callKey = (tool, input) => `${tool}\0${JSON.stringify(input)}`;
+const SLOP_FIXES = {
+    stub: "replace stubs, placeholders, and hard-coded fake data with the working implementation, or state in your reply exactly what is left unimplemented and why",
+    comments: "delete comments that restate the code; keep only those that explain intent, constraints, or non-obvious behaviour",
+    dead: "remove commented-out code, unused imports and variables, duplicated logic, and unreachable branches",
+    hedging: "replace \"should work\", \"for now\", and TODOs without a plan with a definite statement or a concrete follow-up",
+};
+/** Names each symptom and its fix; repeats in the session turn the note into a standing rule. */
+export function slopSteer(where, symptoms, counts) {
+    const named = symptoms.map(symptom => `${SLOP_LABELS[symptom]}${counts[symptom] >= 3 ? ` (${counts[symptom]}th time this session)` : ""}`).join("; ");
+    const fixes = symptoms.map(symptom => SLOP_FIXES[symptom]).join("; ");
+    const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
+    return `pi-warden: the content just written to ${where} has ${named}. Fix it in your next edit: ${fixes}.${standing}`;
+}
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi) {
     let client;
     let budgetExhausted = false;
     let stats = freshStats();
     const widget = new Map();
+    const trace = new Trace();
+    let panelOpen = false;
+    let lastUi;
     /** Calls held in steer mode, with the user prompt current at that time; a retry after the user replies asks Jev about approval. */
     const held = new Map();
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
+    const prose = new ProseTrend();
+    const slopCounts = { stub: 0, comments: 0, dead: 0, hedging: 0 };
     const configFor = (ctx) => loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
     const consentGiven = (config) => config.typesafe || process.env.PI_WARDEN_ENABLED === "1";
     const consentSource = (config) => config.typesafe ? "/warden enable" : process.env.PI_WARDEN_ENABLED === "1" ? "PI_WARDEN_ENABLED" : undefined;
@@ -71,21 +94,48 @@ export default function wardenExtension(pi) {
         if (ctx.hasUI)
             ctx.ui.notify(`warden: ${message}${budgetExhausted ? " Pattern checks continue without TypeSafe for the rest of this session." : ""}`, "warning");
     };
-    const show = (ctx, guard, line) => {
+    const openPanel = (ui) => {
+        if (!ui || panelOpen)
+            return;
+        panelOpen = true;
+        openTracePanel(ui, trace).catch(() => undefined).finally(() => { panelOpen = false; });
+    };
+    const paint = (ctx, config) => {
+        if (!ctx.hasUI)
+            return;
+        lastUi = ctx.ui;
+        if (!config.widget.enabled || widget.size === 0) {
+            ctx.ui.setWidget(WIDGET, undefined);
+            return;
+        }
+        const lines = [...widget.values()];
+        // A custom component so a click (fullscreen mode) opens the trace panel; plain lines otherwise look the same.
+        ctx.ui.setWidget(WIDGET, (_tui, theme) => new MouseRegion(new Text(lines.map(line => theme.fg("muted", line)).join("\n"), 0, 0), event => {
+            if (event.type !== "click" || event.button !== "left")
+                return undefined;
+            openPanel(lastUi);
+            return { handled: true };
+        }), { placement: config.widget.placement });
+    };
+    const record = (ctx, config, guard, line, details) => {
         widget.set(guard, line);
-        if (ctx.hasUI)
-            ctx.ui.setWidget(WIDGET, [...widget.values()]);
+        trace.push({ at: Date.now(), guard, line, details });
+        paint(ctx, config);
     };
-    const steer = (content) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: true }, { deliverAs: "steer" });
+    const steer = (config, content, options = { deliverAs: "steer" }) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: config.steerVisible }, options);
     pi.on("session_start", async (_event, ctx) => {
         client = undefined;
         budgetExhausted = false;
         stats = freshStats();
         widget.clear();
+        trace.clear();
         held.clear();
         attempts.reset();
         evidence = emptyEvidence();
         doneNudged = false;
+        prose.reset();
+        for (const symptom of Object.keys(slopCounts))
+            slopCounts[symptom] = 0;
         if (ctx.hasUI)
             ctx.ui.setWidget(WIDGET, undefined);
     });
@@ -125,14 +175,18 @@ export default function wardenExtension(pi) {
             stats.approved++;
             held.delete(key);
         }
+        const mode = activeMode(config, ctx.hasUI);
+        const told = verdict.level === "confirm" && mode === "steer" ? steerReason(verdict, { canApprove: judge !== undefined }) : undefined;
         if (verdict.source !== "read-only")
-            show(ctx, "action", formatVerdict(verdict));
-        if (verdict.slopReasons?.length) {
+            record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode, ...(told ? { told } : {}) }));
+        if (verdict.slopSymptoms?.length && verdict.slopReasons) {
             stats.slop++;
+            for (const symptom of verdict.slopSymptoms)
+                slopCounts[symptom]++;
             const where = verdict.summary.path ?? event.toolName;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · slop · ${where}: ${verdict.slopReasons.join("; ")}`, "warning");
-            steer(`pi-warden: the content just written to ${where} reads as ${verdict.slopReasons.join(" and ")}. Replace stubs and placeholders with working code, remove comments that restate the code, and keep only what the request needs. If something is intentionally left unimplemented, say so in your reply instead of leaving it in the code.`);
+            steer(config, slopSteer(where, verdict.slopSymptoms, slopCounts));
         }
         if (verdict.level === "warn") {
             stats.warned++;
@@ -142,7 +196,6 @@ export default function wardenExtension(pi) {
         }
         if (verdict.level !== "confirm")
             return undefined;
-        const mode = activeMode(config, ctx.hasUI);
         const reasons = verdict.reasons.join("; ");
         if (mode === "advise") {
             stats.warned++;
@@ -161,15 +214,15 @@ export default function wardenExtension(pi) {
         held.set(key, task);
         if (ctx.hasUI)
             ctx.ui.notify(`warden · held ${event.toolName}: ${reasons}. The agent was told why and asked to re-plan or ask you.`, "warning");
-        return { block: true, reason: steerReason(verdict, { canApprove: judge !== undefined }) };
+        return { block: true, reason: told ?? steerReason(verdict, { canApprove: judge !== undefined }) };
     });
     pi.on("tool_result", async (event, ctx) => {
         const config = configFor(ctx);
         if (!config.enabled)
             return;
-        const failed = resultFailed(event.isError, event.details);
+        const failed = resultFailed(event.isError, event.details, event.content);
         if (config.done.enabled)
-            recordOutcome(evidence, classifyToolResult(event.toolName, event.input, failed), event.input);
+            recordOutcome(evidence, classifyToolResult(event.toolName, event.input, failed), event.input, event.toolName);
         if (!config.stuck.enabled)
             return;
         attempts.push(makeAttempt(event.toolName, event.input, event.content, failed));
@@ -181,41 +234,75 @@ export default function wardenExtension(pi) {
             noteError(ctx, verdict.error, undefined);
         if (verdict.source === "repeat" && !verdict.stuck)
             return;
-        show(ctx, "stuck", formatStuck(verdict));
+        const nudge = verdict.stuck && config.stuck.nudge ? stuckNudge(verdict) : undefined;
+        record(ctx, config, "stuck", formatStuck(verdict, config.widget.stuck), stuckDetails(verdict, attempts.attempts, nudge));
         if (!verdict.stuck)
             return;
         stats.stuck++;
         if (ctx.hasUI)
-            ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${config.stuck.nudge ? " (agent nudged)" : ""}`, "warning");
-        if (config.stuck.nudge)
-            steer(stuckNudge(verdict));
+            ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${nudge ? " (agent nudged)" : ""}`, "warning");
+        if (nudge)
+            steer(config, nudge);
     });
     pi.on("agent_end", async (event, ctx) => {
         const config = configFor(ctx);
-        if (!config.enabled || !config.done.enabled || doneNudged || !needsDoneCheck(evidence))
+        if (!config.enabled)
             return;
         const finalMessage = finalAssistantText(event.messages);
         const judge = judgeFor(config);
         if (!finalMessage || !judge)
             return;
+        if (config.slop.enabled && config.slop.prose.enabled && finalMessage.length >= config.slop.prose.minChars) {
+            stats.proseChecks++;
+            const verdict = await evaluateProse(latestUserPrompt(ctx), finalMessage, { config: config.slop.prose, judge, timeoutMs: config.timeoutMs, signal: ctx.signal });
+            if (verdict.error)
+                noteError(ctx, verdict.error, undefined);
+            else
+                prose.record(verdict.flagged);
+            const due = verdict.error ? [] : prose.due(config.slop.prose.trend);
+            const nudge = due.length ? proseNudge(due, config.slop.prose.audience, prose.counts) : undefined;
+            if (nudge) {
+                verdict.nudged = true;
+                prose.markNudged();
+                stats.proseNudges++;
+            }
+            record(ctx, config, "prose", renderTemplate(config.widget.prose, proseTokens(verdict)), proseDetails(verdict, finalMessage, config.slop.prose.audience, nudge));
+            if (nudge) {
+                if (ctx.hasUI)
+                    ctx.ui.notify(`warden · prose: ${due.join(", ")} in ${config.slop.prose.trend} of the last 3 replies (agent nudged for the next reply)`, "warning");
+                steer(config, nudge, { deliverAs: "nextTurn" });
+            }
+        }
+        if (!config.done.enabled || doneNudged || !needsDoneCheck(evidence))
+            return;
         stats.doneChecks++;
         const verdict = await evaluateDone(latestUserPrompt(ctx), finalMessage, evidence, { config: config.done, judge, timeoutMs: config.timeoutMs, signal: ctx.signal });
         if (verdict.error)
             noteError(ctx, verdict.error, undefined);
-        show(ctx, "done", formatDone(verdict));
+        const nudge = verdict.unverified && config.done.nudge ? doneNudge(verdict) : undefined;
+        record(ctx, config, "done", formatDone(verdict, config.widget.done), doneDetails(verdict, finalMessage, nudge));
         if (!verdict.unverified)
             return;
         stats.unverified++;
         if (ctx.hasUI)
-            ctx.ui.notify(`warden · done-check: ${verdict.reasons.join("; ")}${config.done.nudge ? " (agent asked to verify)" : ""}`, "warning");
-        if (config.done.nudge) {
+            ctx.ui.notify(`warden · done-check: ${verdict.reasons.join("; ")}${nudge ? " (agent asked to verify)" : ""}`, "warning");
+        if (nudge) {
             doneNudged = true;
-            pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: doneNudge(verdict), display: true }, { deliverAs: "followUp", triggerTurn: true });
+            steer(config, nudge, { deliverAs: "followUp", triggerTurn: true });
         }
     });
-    const actions = ["status", "enable", "disable", "mode", "config", "test"];
+    // Shortcuts are registered once at load; a shape check keeps a typo in the config file from being registered.
+    const shortcut = loadConfig().widget.shortcut;
+    if (/^(?:(?:ctrl|shift|alt|super)\+)+[a-z0-9]+$|^f\d{1,2}$/i.test(shortcut)) {
+        pi.registerShortcut(shortcut, {
+            description: "Open the pi-warden trace panel",
+            handler: async (ctx) => { if (ctx.hasUI)
+                openPanel(ctx.ui); },
+        });
+    }
+    const actions = ["status", "enable", "disable", "mode", "config", "test", "trace"];
     pi.registerCommand("warden", {
-        description: "pi-warden status, TypeSafe consent, steer/confirm/advise mode, config editor, and a synthetic guard test",
+        description: "pi-warden status, TypeSafe consent, steer/confirm/advise mode, config editor, trace panel, and a synthetic guard test",
         getArgumentCompletions(prefix) {
             const matches = actions.filter(action => action.startsWith(prefix)).map(action => ({ value: action, label: action }));
             return matches.length ? matches : null;
@@ -234,16 +321,26 @@ export default function wardenExtension(pi) {
                     const key = resolveApiKey();
                     const source = consentSource(config);
                     const usage = client?.getUsage();
-                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop"].filter(Boolean).join(", ");
+                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`].filter(Boolean).join(", ");
                     report([
                         `pi-warden: ${config.enabled ? `guarding ${config.action.tools.join(", ")} (${guards})` : "off"}; mode ${activeMode(config, ctx.hasUI)}; TypeSafe judgments ${source ? `enabled via ${source}` : "disabled (run /warden enable)"}; key ${key ? key.source === "stored" ? "stored (shared with pi-typesafe)" : "from TYPESAFE_API_KEY" : "missing (run /warden enable)"}.`,
-                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests.`,
-                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop quality ${config.slop.quality}, stub ${config.slop.placeholder}; failOpen ${config.action.failOpen}.`,
+                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
+                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; failOpen ${config.action.failOpen}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
                         widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",
+                        `Trace: ${trace.entries().length} events (/warden trace${shortcut ? `, ${shortcut}` : ""}, or click the status line in fullscreen mode). Widget templates in config.widget: action tokens ${TOKEN_NAMES.action.map(name => `{${name}}`).join(" ")}.`,
                     ].join(" "));
                     return;
                 }
+                if (action === "trace") {
+                    if (!ctx.hasUI) {
+                        const entries = trace.entries();
+                        report(entries.length ? entries.slice(-20).map(entry => `${new Date(entry.at).toTimeString().slice(0, 8)} ${entry.guard}: ${entry.line}${entry.details.length ? `\n  ${entry.details.join("\n  ")}` : ""}`).join("\n") : "No guarded activity yet this session.");
+                        return;
+                    }
+                    openPanel(ctx.ui);
+                    return;
+                }
                 if (action === "enable") {
                     if (!ctx.hasUI) {
                         report("Consent needs an interactive session. For headless runs set PI_WARDEN_ENABLED=1 and TYPESAFE_API_KEY explicitly.", "warning");
@@ -310,7 +407,7 @@ export default function wardenExtension(pi) {
                     if (judge && ctx.hasUI && !await ctx.ui.confirm("Send one synthetic pi-warden test request?", `A synthetic action ("rm -rf /tmp/pi-warden-demo" for the task "Clean up the demo directory") goes to api.typesafe.ai and may incur charges. ${disclosure}`))
                         return;
                     const verdict = await evaluateAction({ tool: "bash", input: { command: "rm -rf /tmp/pi-warden-demo" }, cwd: ctx.cwd, task: "Clean up the demo directory" }, { config: { ...config.action, enabled: true, tools: ["bash"] }, judge });
-                    show(ctx, "action", formatVerdict(verdict));
+                    record(ctx, config, "action", formatVerdict(verdict, config.widget.action), actionDetails(verdict, { mode: activeMode(config, ctx.hasUI) }));
                     report(`${formatVerdict(verdict)}${verdict.reasons.length ? ` — ${verdict.reasons.join("; ")}` : ""}${judge ? "" : " (pattern checks only: TypeSafe judgments are not enabled or no key is configured)"}${verdict.error ? ` — ${verdict.error}` : ""}`);
                     if (verdict.level === "confirm") {
                         const mode = activeMode(config, ctx.hasUI);

package/dist/guard.d.ts

@@ -42,12 +42,15 @@ export interface Judgment {
     model: string;
     elapsedMs: number;
 }
+/** One probability per slop symptom; the steer names the symptoms above the threshold. */
 export interface SlopJudgment {
-    /** 0 focused … 2 sloppy. */
-    quality: number;
-    /** P(placeholder or stub where working code is needed). */
-    placeholder: number;
+    stub: number;
+    comments: number;
+    dead: number;
+    hedging: number;
 }
+export type SlopSymptom = keyof SlopJudgment;
+export declare const SLOP_SYMPTOMS: readonly SlopSymptom[];
 export interface Verdict {
     level: Level;
     source: "skipped" | "read-only" | "pattern" | "typesafe" | "error";
@@ -57,7 +60,8 @@ export interface Verdict {
     reasons: string[];
     judgment?: Judgment;
     slop?: SlopJudgment;
-    /** Set when the slop thresholds were crossed; the level itself is never raised by slop. */
+    /** Symptoms at or above the slop threshold, strongest first. The level itself is never raised by slop. */
+    slopSymptoms?: SlopSymptom[];
     slopReasons?: string[];
     /** True when a previously held call was allowed because the user's latest message approves it. */
     approvedByUser?: boolean;
@@ -91,9 +95,12 @@ export declare const questions: {
     }>;
 };
 export declare const slopQuestions: {
-    slop_quality: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
-    slop_placeholder: import("pi-typesafe").NoulQuestion;
+    slop_stub: import("pi-typesafe").NoulQuestion;
+    slop_comments: import("pi-typesafe").NoulQuestion;
+    slop_dead: import("pi-typesafe").NoulQuestion;
+    slop_hedging: import("pi-typesafe").NoulQuestion;
 };
+export declare const SLOP_LABELS: Record<SlopSymptom, string>;
 export declare const approvalQuestion: {
     approved: import("pi-typesafe").NoulQuestion;
 };
@@ -107,8 +114,10 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
     };
     questions: {
         approved?: import("pi-typesafe").NoulQuestion;
-        slop_quality?: import("pi-typesafe").ScoreQuestion<readonly ["Focused: does what `task` needs, clear names, comments only where they add information", "Some filler: comments that restate the code, minor dead code, hedging or repeated text", "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text"]>;
-        slop_placeholder?: import("pi-typesafe").NoulQuestion;
+        slop_stub?: import("pi-typesafe").NoulQuestion;
+        slop_comments?: import("pi-typesafe").NoulQuestion;
+        slop_dead?: import("pi-typesafe").NoulQuestion;
+        slop_hedging?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
         off_task: import("pi-typesafe").NoulQuestion;
         scope: import("pi-typesafe").ChoiceQuestion<{
@@ -129,5 +138,5 @@ export declare function textApproves(task: string | undefined): boolean;
 export declare function steerReason(verdict: Verdict, options: {
     canApprove: boolean;
 }): string;
-/** One-line rendering for widgets and logs. Includes no command text. */
-export declare function formatVerdict(verdict: Verdict): string;
+/** One-line rendering for widgets and logs. Includes no command text. Templates: see widget.ts. */
+export declare function formatVerdict(verdict: Verdict, template?: string): string;

package/dist/guard.js

@@ -3,6 +3,9 @@ import { homedir } from "node:os";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { choice, noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.js";
+import { commandOf } from "./tools.js";
+import { actionTokens, DEFAULT_TEMPLATES, renderTemplate } from "./widget.js";
+export const SLOP_SYMPTOMS = ["stub", "comments", "dead", "hedging"];
 const LEVEL_RANK = { allow: 0, warn: 1, confirm: 2 };
 const higher = (a, b) => (LEVEL_RANK[a] >= LEVEL_RANK[b] ? a : b);
 const TASK_LIMIT = 1500;
@@ -12,6 +15,16 @@ const EDIT_LIMIT = 400;
 function truncate(text, limit) {
     return text.length <= limit ? text : `${text.slice(0, limit)}… [${text.length - limit} more chars]`;
 }
+/** Head, a slice from the middle, and the tail, so stubs at the end of a long file are still seen. */
+function sample(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const head = Math.floor(limit * 0.6);
+    const mid = Math.floor(limit * 0.2);
+    const tail = limit - head - mid;
+    const middleStart = Math.floor(text.length / 2 - mid / 2);
+    return `${text.slice(0, head)}\n… [${middleStart - head} chars] …\n${text.slice(middleStart, middleStart + mid)}\n… [${text.length - tail - (middleStart + mid)} chars] …\n${text.slice(-tail)}`;
+}
 const SHELL_RULES = [
     { id: "git-force-push", severity: "destructive", label: "git force push", test: /\bgit\s+push\b[^\n;&|]*\s(?:-f|--force)(?![-\w])/ },
     { id: "git-force-with-lease", severity: "risky", label: "git push --force-with-lease", test: /\bgit\s+push\b[^\n;&|]*--force-with-lease/ },
@@ -72,7 +85,7 @@ export function matchPatterns(tool, input, cwd) {
     const hits = new Map();
     const add = (hit) => { if (hit && !hits.has(hit.id))
         hits.set(hit.id, hit); };
-    const command = typeof input.command === "string" ? input.command : undefined;
+    const command = commandOf(tool, input)?.command;
     if (command) {
         for (const rule of SHELL_RULES)
             if (rule.test.test(command))
@@ -159,9 +172,10 @@ function displayPath(target, cwd) {
 }
 export function describeAction(tool, input, cwd) {
     const summary = { tool };
-    if (typeof input.command === "string")
-        summary.command = redact(truncate(input.command, COMMAND_LIMIT));
-    if (typeof input.path === "string" && input.path.trim()) {
+    const view = commandOf(tool, input);
+    if (view)
+        summary.command = redact(truncate(view.command, COMMAND_LIMIT));
+    if (typeof input.path === "string" && input.path.trim() && tool !== "ctx_execute_file") {
         const shown = displayPath(input.path, cwd);
         summary.path = shown.path;
         summary.location = shown.location;
@@ -169,7 +183,7 @@ export function describeAction(tool, input, cwd) {
     }
     if (tool === "write" && typeof input.content === "string") {
         summary.bytes = Buffer.byteLength(input.content, "utf8");
-        summary.excerpt = redact(truncate(input.content, EXCERPT_LIMIT));
+        summary.excerpt = redact(sample(input.content, EXCERPT_LIMIT));
     }
     if (tool === "edit" && Array.isArray(input.edits)) {
         summary.editCount = input.edits.length;
@@ -204,12 +218,28 @@ export const questions = {
     }),
 };
 export const slopQuestions = {
-    slop_quality: score("How does the new code or text that `action` writes read as a change for `task`?", [
-        "Focused: does what `task` needs, clear names, comments only where they add information",
-        "Some filler: comments that restate the code, minor dead code, hedging or repeated text",
-        "Sloppy: placeholder or stub code, TODO where a working implementation is needed, duplicated or commented-out logic, vague or contradictory text",
-    ]),
-    slop_placeholder: noul("Does the content `action` writes leave placeholder, stub, mock, or 'implement later' code where `task` needs a working implementation?"),
+    slop_stub: noul("Does the content `action` writes leave placeholder, stub, mock, or \"implement later\" code where `task` needs a working implementation?", {
+        true: "Yes: a function returns a constant, null, or fake data instead of doing its job; a TODO or \"implement later\" stands where the logic should be; a mock is hard-coded where a real call is needed.",
+        false: "No: the code does what `task` asks, or the incomplete part is clearly outside what `task` asked for.",
+    }),
+    slop_comments: noul("Do the explanatory comments in the content `action` writes mostly restate what the adjacent code already shows, instead of explaining intent, constraints, or non-obvious behaviour? Commented-out code is not an explanatory comment and is judged elsewhere.", {
+        true: "Yes: comments such as \"// increment the counter\" above counter++, \"// return the result\", \"// loop over items\", banners repeating the function name, or doc comments that only repeat parameter names.",
+        false: "No: there are few or no comments, or the comments explain why, an invariant, a workaround, a limitation, a reference, or a decision a reader could not infer from the code.",
+    }),
+    slop_dead: noul("Does the content `action` writes include dead or redundant code: commented-out code, unused imports or variables, duplicated logic, or branches that cannot be reached?", {
+        true: "Yes: blocks of commented-out code, variables or imports that are never used, the same logic written twice, or checks that are always true or false.",
+        false: "No: every line participates in the behaviour.",
+    }),
+    slop_hedging: noul("Does the content `action` writes contain vague or hedging text: \"this should work\", \"for now\", \"might need changes\", TODO notes without a plan, or explanations that say nothing specific?", {
+        true: "Yes: uncertain or apologetic notes in code or docs, placeholders like \"TBD\", or prose that does not commit to what the code does.",
+        false: "No: the text states what the code does and why, or there is no such text.",
+    }),
+};
+export const SLOP_LABELS = {
+    stub: "stub or placeholder code where a working implementation is needed",
+    comments: "comments that restate the code",
+    dead: "dead or duplicated code",
+    hedging: "hedging or vague notes",
 };
 export const approvalQuestion = {
     approved: noul("Does `task` (the user's latest message) explicitly approve running `action`, which was held earlier for the user's decision?", {
@@ -260,7 +290,8 @@ export async function evaluateAction(action, options) {
             reasons.push(`${action.tool === "write" ? "creates" : "changes"} a file outside the project`);
         }
     }
-    if (action.tool === "bash" && patterns.length === 0 && typeof action.input.command === "string" && isReadOnlyCommand(action.input.command)) {
+    const view = commandOf(action.tool, action.input);
+    if (view?.shell && patterns.length === 0 && isReadOnlyCommand(view.command)) {
         return { level, source: "read-only", summary, patterns, reasons };
     }
     if (!judge)
@@ -296,15 +327,13 @@ export async function evaluateAction(action, options) {
             reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);
         }
         const verdict = { level, source: "typesafe", summary, patterns, reasons, judgment };
-        if (options.slop?.enabled && typeof answers.slop_quality?.score === "number" && typeof answers.slop_placeholder?.noul === "number") {
-            verdict.slop = { quality: answers.slop_quality.score, placeholder: answers.slop_placeholder.noul };
-            const slopReasons = [];
-            if (verdict.slop.quality >= options.slop.quality)
-                slopReasons.push(`quality ${verdict.slop.quality.toFixed(2)}/2 (filler or sloppy)`);
-            if (verdict.slop.placeholder >= options.slop.placeholder)
-                slopReasons.push(`placeholder or stub code ${percent(verdict.slop.placeholder)}`);
-            if (slopReasons.length)
-                verdict.slopReasons = slopReasons;
+        if (options.slop?.enabled && SLOP_SYMPTOMS.every(symptom => typeof answers[`slop_${symptom}`]?.noul === "number")) {
+            verdict.slop = { stub: answers.slop_stub.noul, comments: answers.slop_comments.noul, dead: answers.slop_dead.noul, hedging: answers.slop_hedging.noul };
+            const flagged = SLOP_SYMPTOMS.filter(symptom => verdict.slop[symptom] >= options.slop.threshold).sort((a, b) => verdict.slop[b] - verdict.slop[a]);
+            if (flagged.length) {
+                verdict.slopSymptoms = flagged;
+                verdict.slopReasons = flagged.map(symptom => `${SLOP_LABELS[symptom]} (${percent(verdict.slop[symptom])})`);
+            }
         }
         if (level === "confirm" && judgment.approved !== undefined && judgment.approved >= APPROVAL_THRESHOLD) {
             verdict.level = "allow";
@@ -346,21 +375,7 @@ export function steerReason(verdict, options) {
         lines.push("pi-warden allows the same call again once the user has replied with approval.");
     return lines.join(" ");
 }
-/** One-line rendering for widgets and logs. Includes no command text. */
-export function formatVerdict(verdict) {
-    const parts = [`warden · ${verdict.summary.tool}`];
-    if (verdict.judgment)
-        parts.push(`irreversible ${percent(verdict.judgment.irreversible)}`, `off-task ${percent(verdict.judgment.offTask)}`, verdict.judgment.scope.replace(/_/g, " "));
-    if (verdict.slop)
-        parts.push(`slop ${verdict.slop.quality.toFixed(1)}/2`, `stub ${percent(verdict.slop.placeholder)}`);
-    if (verdict.patterns.length)
-        parts.push(`patterns: ${verdict.patterns.map(hit => hit.id).join(", ")}`);
-    if (verdict.approvedByUser)
-        parts.push("user approved");
-    if (verdict.source === "error")
-        parts.push("typesafe error");
-    if (verdict.source === "read-only")
-        parts.push("read-only");
-    parts.push(verdict.level);
-    return parts.join(" · ");
+/** One-line rendering for widgets and logs. Includes no command text. Templates: see widget.ts. */
+export function formatVerdict(verdict, template = DEFAULT_TEMPLATES.action) {
+    return renderTemplate(template, actionTokens(verdict));
 }

package/dist/index.d.ts

@@ -1,9 +1,18 @@
 export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
+export type { ProseSymptom, ProseVerdict, ProseOptions } from "./prose.js";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
 export type { Attempt, StuckJudgment, StuckVerdict, StuckOptions } from "./stuck.js";
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions } from "./done.js";
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
+export type { CommandView } from "./tools.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export type { WidgetConfig, WidgetPlacement, Tokens } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";
+export type { TraceEntry, GuardName } from "./trace.js";

package/dist/index.js

@@ -1,5 +1,10 @@
 export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, textApproves, questions, slopQuestions, approvalQuestion } from "./guard.js";
+export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
+export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
 export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, buildStuckRequest, stuckQuestions, stuckNudge, formatStuck } from "./stuck.js";
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { redact } from "./redact.js";
 export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";

package/dist/panel.d.ts

@@ -0,0 +1,44 @@
+import type { Component, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
+import type { Trace } from "./trace.js";
+interface ThemeLike {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+}
+/**
+ * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
+ * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ */
+export declare class TracePanel implements Component {
+    private readonly trace;
+    private readonly theme;
+    private readonly close;
+    private readonly requestRender;
+    private readonly title;
+    focused: boolean;
+    private scroll;
+    private viewport;
+    private readonly unsubscribe;
+    constructor(trace: Trace, theme: ThemeLike, close: () => void, requestRender: () => void, title?: string);
+    dispose(): void;
+    /** Rendering is cheap and derived from the trace each time; nothing is cached. */
+    invalidate(): void;
+    private lines;
+    render(width: number): string[];
+    /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
+    setViewport(rows: number): void;
+    handleInput(data: string): void;
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+}
+export interface PanelUi {
+    custom<T>(factory: (tui: {
+        requestRender(): void;
+        terminal?: {
+            rows: number;
+        };
+    }, theme: ThemeLike, keybindings: unknown, done: (result: T) => void) => Component & {
+        dispose?(): void;
+    }, options?: Record<string, unknown>): Promise<T>;
+}
+/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
+export declare function openTracePanel(ui: PanelUi, trace: Trace): Promise<void>;
+export {};