@davidorex/pi-behavior-monitors 0.14.4 → 0.26.0

package/dist/index.js

@@ -12,20 +12,51 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { readBlock } from "@davidorex/pi-project/block-api";
-import { validateFromFile } from "@davidorex/pi-project/schema-validator";
+import { appendToBlock, appendToTypedFile, readBlock, upsertItemInBlock, writeTypedFile, } from "@davidorex/pi-context/block-api";
+import { validateFromFile } from "@davidorex/pi-context/schema-validator";
+import { dateRotatedPath, executeAgent } from "@davidorex/pi-jit-agents";
 import { createAgentLoader } from "@davidorex/pi-workflows/agent-spec";
 import { compileAgentSpec } from "@davidorex/pi-workflows/step-shared";
-import { complete, StringEnum } from "@mariozechner/pi-ai";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
-import { Box, Text } from "@mariozechner/pi-tui";
-import { Type } from "@sinclair/typebox";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
 import nunjucks from "nunjucks";
 const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
-const EXAMPLES_DIR = path.join(EXTENSION_DIR, "..", "examples");
-const AGENTS_DIR = path.join(EXTENSION_DIR, "..", "agents");
-/** Tool definition for forcing structured verdict output from the classify LLM call. */
-const VERDICT_TOOL = {
+/**
+ * Package root is one level up from `dist/` at runtime (compiled `dist/index.js`),
+ * or equal to `EXTENSION_DIR` when running from source (e.g. vitest). Detecting
+ * which case we're in by inspecting the basename keeps the bundled-content paths
+ * (`examples/`, `agents/`) reachable from both contexts without separate test
+ * fixtures.
+ */
+const PACKAGE_ROOT = path.basename(EXTENSION_DIR) === "dist" ? path.dirname(EXTENSION_DIR) : EXTENSION_DIR;
+const EXAMPLES_DIR = path.join(PACKAGE_ROOT, "examples");
+const AGENTS_DIR = path.join(PACKAGE_ROOT, "agents");
+const SCHEMAS_DIR = path.join(PACKAGE_ROOT, "schemas");
+/**
+ * Framework-contract schemas for monitor side-car state files. The
+ * `*.patterns.json` and `*.instructions.json` files written by `learnPattern`
+ * and `saveInstructions` route through `appendToTypedFile` /
+ * `writeTypedFile` from `@davidorex/pi-context/block-api`, threading these
+ * schema paths so AJV validation, atomic write, and proper-lockfile gating
+ * apply uniformly with `.project/<block>.json` writes (FGAP-019 closure;
+ * issue-065's three remaining bypass categories — no AJV, no
+ * proper-lockfile, no centralized choke point — closed for monitor
+ * framework state).
+ */
+const PATTERN_LIST_SCHEMA_PATH = path.join(SCHEMAS_DIR, "monitor-pattern-list.schema.json");
+const INSTRUCTIONS_LIST_SCHEMA_PATH = path.join(SCHEMAS_DIR, "monitor-instruction-list.schema.json");
+/**
+ * Tool definition for forcing structured verdict output from the classify LLM call.
+ *
+ * Retained as a documentation reference; the live phantom-tool used at dispatch
+ * time is now built by `buildPhantomTool(outputSchema)` inside pi-jit-agents'
+ * `executeAgent`, fed by the agent spec's `outputSchema` (canonical:
+ * `verdict.schema.json`). The shape below mirrors that schema. Underscore
+ * prefix suppresses the unused-symbol lint while preserving the on-file
+ * trace of the contract that the phantom-tool path now enforces.
+ */
+const _VERDICT_TOOL = {
     name: "classify_verdict",
     description: "Output the monitor classification verdict",
     parameters: Type.Object({
@@ -84,41 +115,71 @@ export const VALID_EVENTS = new Set(["message_end", "turn_end", "agent_end", "co
 function isValidEvent(event) {
     return VALID_EVENTS.has(event);
 }
-// =============================================================================
-// Discovery
-// =============================================================================
-export function discoverMonitors() {
-    const dirs = [];
-    // project-local
+/**
+ * Walk up from `process.cwd()` looking for a `.pi/monitors/` directory, stopping
+ * at the first `.git` boundary so we never escape into the user's home config.
+ * Returns the resolved path or `null` when no project-tier monitors directory
+ * exists. Single source for the project-tier walk used by both `discoverMonitors`
+ * and `createMonitorAgentTemplateEnv` (the previous `resolveProjectMonitorsDir`
+ * also returned a synthesized cwd-rooted fallback path even when no directory
+ * existed, which conflated "exists" with "would be created on seed"; that
+ * conflation is no longer needed and is removed here).
+ */
+function findProjectMonitorsDir() {
     let cwd = process.cwd();
     while (true) {
         const candidate = path.join(cwd, ".pi", "monitors");
-        if (isDir(candidate)) {
-            dirs.push(candidate);
-            break;
-        }
-        // Stop at project root (.git boundary) — don't traverse into user home config
+        if (isDir(candidate))
+            return candidate;
         if (isDir(path.join(cwd, ".git")))
-            break;
+            return null;
         const parent = path.dirname(cwd);
         if (parent === cwd)
-            break;
+            return null;
         cwd = parent;
     }
-    // global
+}
+/**
+ * Discover monitors across three tiers; first match by `name` wins.
+ *
+ * Precedence (highest first):
+ *   1. project   `.pi/monitors/`            (walk-up to .git boundary)
+ *   2. global    `~/.pi/agent/monitors/`    (via `getAgentDir()`)
+ *   3. bundled   `<package>/examples/`      (built-in defaults shipped with this extension)
+ *
+ * Any monitor file in a lower tier whose `name` matches an already-seen
+ * higher-tier monitor is recorded in `overrides` (not loaded). This replaces
+ * the prior `seedExamples()` copy-on-first-run pattern: bundled fixes (e.g.
+ * commit affe992 routing fragility/hedge classifiers through `agent_end`) now
+ * propagate to users automatically because tier 3 is read live, not copied.
+ */
+export function discoverMonitors() {
+    const dirs = [];
+    const projectDir = findProjectMonitorsDir();
+    if (projectDir)
+        dirs.push(projectDir);
     const globalDir = path.join(getAgentDir(), "monitors");
     if (isDir(globalDir))
         dirs.push(globalDir);
+    if (isDir(EXAMPLES_DIR))
+        dirs.push(EXAMPLES_DIR);
     const seen = new Map();
+    const overrides = [];
     for (const dir of dirs) {
         for (const file of listMonitorFiles(dir)) {
             const monitor = parseMonitorJson(path.join(dir, file), dir);
-            if (monitor && !seen.has(monitor.name)) {
+            if (!monitor)
+                continue;
+            const winner = seen.get(monitor.name);
+            if (!winner) {
                 seen.set(monitor.name, monitor);
             }
+            else {
+                overrides.push({ name: monitor.name, winnerDir: winner.dir, losingDir: dir });
+            }
         }
     }
-    return Array.from(seen.values());
+    return { monitors: Array.from(seen.values()), overrides };
 }
 function isDir(p) {
     try {
@@ -209,73 +270,6 @@ function parseMonitorJson(filePath, dir) {
     };
 }
 // =============================================================================
-// Example seeding
-// =============================================================================
-export function resolveProjectMonitorsDir() {
-    let cwd = process.cwd();
-    while (true) {
-        const piDir = path.join(cwd, ".pi");
-        if (isDir(piDir))
-            return path.join(piDir, "monitors");
-        // Stop at project root (.git boundary) — don't traverse into user home config
-        if (isDir(path.join(cwd, ".git")))
-            break;
-        const parent = path.dirname(cwd);
-        if (parent === cwd)
-            break;
-        cwd = parent;
-    }
-    return path.join(process.cwd(), ".pi", "monitors");
-}
-function seedExamples() {
-    if (discoverMonitors().length > 0)
-        return 0;
-    if (!isDir(EXAMPLES_DIR))
-        return 0;
-    const targetDir = resolveProjectMonitorsDir();
-    fs.mkdirSync(targetDir, { recursive: true });
-    if (listMonitorFiles(targetDir).length > 0)
-        return 0;
-    const entries = fs.readdirSync(EXAMPLES_DIR, { withFileTypes: true });
-    const files = entries.filter((e) => e.isFile() && e.name.endsWith(".json"));
-    let copied = 0;
-    for (const file of files) {
-        const dest = path.join(targetDir, file.name);
-        if (!fs.existsSync(dest)) {
-            fs.copyFileSync(path.join(EXAMPLES_DIR, file.name), dest);
-            copied++;
-        }
-    }
-    // Also copy template subdirectories (e.g., commit-hygiene/classify.md)
-    // These contain Nunjucks .md prompt templates referenced by promptTemplate
-    // fields in the monitor JSON specs.
-    const dirs = entries.filter((e) => e.isDirectory());
-    for (const dir of dirs) {
-        const srcDir = path.join(EXAMPLES_DIR, dir.name);
-        const destDir = path.join(targetDir, dir.name);
-        if (!fs.existsSync(destDir)) {
-            copyDirRecursive(srcDir, destDir);
-        }
-    }
-    return copied;
-}
-// =============================================================================
-// Skill syncing
-// =============================================================================
-function copyDirRecursive(src, dest) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-            copyDirRecursive(srcPath, destPath);
-        }
-        else if (entry.isFile()) {
-            fs.copyFileSync(srcPath, destPath);
-        }
-    }
-}
-// =============================================================================
 // Context collection
 // =============================================================================
 const TRUNCATE = 2000;
@@ -319,14 +313,59 @@ function collectUserText(branch) {
     }
     return "";
 }
-function collectAssistantText(branch) {
+/**
+ * Collect the assistant's response text for the current turn.
+ *
+ * Walks the branch backward from the tail and aggregates text from every
+ * assistant `MessageEntry` until it reaches the most recent user message
+ * (turn boundary), at which point the walk stops. Collected segments are
+ * reversed back to chronological order and joined with `\n\n`. Empty
+ * segments (from tool-call-only assistant messages with no text content)
+ * are dropped before joining.
+ *
+ * Encoded design decisions:
+ *
+ * - F-014 root-cause fix: previously the function returned from the FIRST
+ *   assistant message it hit walking backward; when that latest assistant
+ *   message was tool-call-only, the result was empty even though earlier
+ *   assistant messages in the same turn carried the user-visible text.
+ *   The walk now aggregates across all assistant messages in the turn so
+ *   tool-call-only tail messages no longer mask prior text.
+ *
+ * - F-018 multi-message-turn semantics: "the assistant's response" is
+ *   defined as all assistant text emitted from the most recent user
+ *   message up to the present, joined with double-newline separator.
+ *   Non-message entries (model_change, label, custom_message,
+ *   branch_summary, etc.) are skipped — they are not part of the
+ *   assistant's response.
+ *
+ * - `extractText` (text-only filter) is intentionally not modified here:
+ *   tool-call blocks have no user-visible text, and thinking blocks are
+ *   model-internal reasoning that should not leak into classifier prompts.
+ *
+ * Edge cases:
+ *   - Empty branch: returns "".
+ *   - No user message in branch (e.g., system-init turn): walks to start
+ *     and returns all collected assistant text.
+ *   - All assistant messages tool-call-only: returns "" (true empty
+ *     response, distinct from the F-014 false-positive case).
+ */
+export function collectAssistantText(branch) {
+    const segments = [];
     for (let i = branch.length - 1; i >= 0; i--) {
         const entry = branch[i];
-        if (isMessageEntry(entry) && entry.message.role === "assistant") {
-            return extractText(entry.message.content);
+        if (!isMessageEntry(entry))
+            continue;
+        if (entry.message.role === "user")
+            break;
+        if (entry.message.role === "assistant") {
+            segments.push(extractText(entry.message.content));
         }
     }
-    return "";
+    return segments
+        .reverse()
+        .filter((s) => s.length > 0)
+        .join("\n\n");
 }
 function collectToolResults(branch, limit = 5) {
     const results = [];
@@ -699,20 +738,20 @@ function loadInstructions(monitor) {
         return [];
     }
 }
-function saveInstructions(monitor, instructions) {
-    const tmpPath = `${monitor.resolvedInstructionsPath}.${process.pid}.tmp`;
+// Exported (over the package barrel) so the side-car-routing test suite in
+// `index.test.ts` can drive it directly without reaching through the
+// `/monitors rules ...` command surface; behavior is otherwise identical to
+// when this was a module-private helper.
+export function saveInstructions(monitor, instructions) {
+    // Routes through `writeTypedFile` so AJV validates the array against
+    // `monitor-instruction-list.schema.json`, the write goes through
+    // proper-lockfile, and the same atomic tmp+rename + cleanup-on-failure
+    // applies as for `.project/<block>.json` writes — FGAP-019 closure.
     try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(instructions, null, 2)}\n`);
-        fs.renameSync(tmpPath, monitor.resolvedInstructionsPath);
+        writeTypedFile(monitor.resolvedInstructionsPath, INSTRUCTIONS_LIST_SCHEMA_PATH, instructions, undefined, `monitor '${monitor.name}' instructions`);
         return null;
     }
     catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* cleanup */
-        }
         return err instanceof Error ? err.message : String(err);
     }
 }
@@ -937,13 +976,13 @@ export function mapVerdictToClassifyResult(parsed) {
  * Monitor paths take precedence.
  */
 function createMonitorAgentTemplateEnv(cwd) {
-    const projectMonitorsDir = resolveProjectMonitorsDir();
+    const projectMonitorsDir = findProjectMonitorsDir();
     const userMonitorsDir = path.join(os.homedir(), ".pi", "agent", "monitors");
     const projectTemplatesDir = path.join(cwd, ".pi", "templates");
     const userTemplatesDir = path.join(os.homedir(), ".pi", "agent", "templates");
     const searchPaths = [];
     // Monitor paths first — monitor templates take precedence
-    if (isDir(projectMonitorsDir))
+    if (projectMonitorsDir)
         searchPaths.push(projectMonitorsDir);
     if (isDir(userMonitorsDir))
         searchPaths.push(userMonitorsDir);
@@ -964,6 +1003,86 @@ function createMonitorAgentTemplateEnv(cwd) {
 let cachedAgentLoader = null;
 /** Module-level cached template environment for classify agent specs, populated at session_start. */
 let cachedMonitorAgentEnv = null;
+/**
+ * Module-level reference to the ExtensionAPI for CLI flag lookup at classify time.
+ * Set by the default export (activate function) so classifyViaAgent can read
+ * --trace, --no-trace, --trace-dir, and --trace-filter via pi.getFlag().
+ *
+ * Held as an opaque `getFlag` callable rather than the full ExtensionAPI to keep
+ * the surface narrow and to allow future-replacement by direct argv parsing
+ * without a wider refactor.
+ */
+let getCliFlag = null;
+/**
+ * Resolve effective trace settings for a monitor classify call.
+ *
+ * Trace-path resolution precedence (highest to lowest):
+ *   1. `--no-trace` CLI flag → null (explicit disable)
+ *   2. `--trace-dir <dir>` CLI flag → dateRotatedPath(<dir>) — single shared dir,
+ *      no per-monitor subdir (caller chose the path explicitly)
+ *   3. `PI_AGENT_TRACE_DIR` env var → dateRotatedPath(<env>/<monitor.name>) —
+ *      env var is the global base; per-monitor subdir appends
+ *   4. `--trace` CLI flag → default per-monitor path (explicit enable)
+ *   5. Default ON when no flags / env unset → default per-monitor path
+ *
+ * Default per-monitor path:
+ *   .workflows/monitors/<monitor.name>/<YYYY-MM-DD>.jsonl
+ *
+ * Redaction-config path resolution (highest to lowest):
+ *   1. `--trace-filter <file>` CLI flag
+ *   2. `PI_AGENT_TRACE_FILTER` env var
+ *   3. .workflows/monitors/<monitor.name>/trace-config.json (if exists)
+ *   4. null (builtin patterns only)
+ *
+ * Per DEC-0005 the trace stream is push-write inside executeAgent and is
+ * intentionally divergent from pi-mono's pull/replay session model — this
+ * resolver feeds DispatchContext fields the runtime consumes; trace-write
+ * failures are non-fatal and never abort classify.
+ */
+function resolveTraceSettings(monitorName) {
+    const flagNoTrace = getCliFlag?.("no-trace") === true;
+    const flagTrace = getCliFlag?.("trace") === true;
+    const flagTraceDirRaw = getCliFlag?.("trace-dir");
+    const flagTraceDir = typeof flagTraceDirRaw === "string" && flagTraceDirRaw.length > 0 ? flagTraceDirRaw : null;
+    const flagTraceFilterRaw = getCliFlag?.("trace-filter");
+    const flagTraceFilter = typeof flagTraceFilterRaw === "string" && flagTraceFilterRaw.length > 0 ? flagTraceFilterRaw : null;
+    const envTraceDir = process.env.PI_AGENT_TRACE_DIR;
+    const envTraceFilter = process.env.PI_AGENT_TRACE_FILTER;
+    const defaultTraceBaseDir = path.join(process.cwd(), ".workflows", "monitors", monitorName);
+    const defaultTracePath = dateRotatedPath(defaultTraceBaseDir);
+    let tracePath;
+    if (flagNoTrace) {
+        tracePath = null;
+    }
+    else if (flagTraceDir) {
+        tracePath = dateRotatedPath(flagTraceDir);
+    }
+    else if (envTraceDir && envTraceDir.length > 0) {
+        tracePath = dateRotatedPath(path.join(envTraceDir, monitorName));
+    }
+    else if (flagTrace) {
+        tracePath = defaultTracePath;
+    }
+    else {
+        // Default: trace ON to per-monitor path. Disable explicitly via --no-trace.
+        tracePath = defaultTracePath;
+    }
+    const monitorTraceConfigPath = path.join(process.cwd(), ".workflows", "monitors", monitorName, "trace-config.json");
+    let redactionConfigPath;
+    if (flagTraceFilter) {
+        redactionConfigPath = flagTraceFilter;
+    }
+    else if (envTraceFilter && envTraceFilter.length > 0) {
+        redactionConfigPath = envTraceFilter;
+    }
+    else if (fs.existsSync(monitorTraceConfigPath)) {
+        redactionConfigPath = monitorTraceConfigPath;
+    }
+    else {
+        redactionConfigPath = null;
+    }
+    return { tracePath, redactionConfigPath };
+}
 /**
  * Classify via agent spec — the sole classify path.
  * Loads the agent YAML, builds context from collectors, compiles via
@@ -1012,71 +1131,127 @@ async function classifyViaAgent(ctx, monitor, branch, extraContext, signal) {
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
     if (!auth.ok)
         throw new Error(auth.error);
+    // --- Trace-capture wiring (issue-023 T6) -------------------------------
+    // Resolve effective tracePath / redactionConfigPath / monitorName for this
+    // classify call. See resolveTraceSettings() for precedence rules. The
+    // dispatch surface is pi-jit-agents' executeAgent (DEC-0005 push-write
+    // trace pipeline); failures inside the trace path are non-fatal and never
+    // abort the classify call.
+    const { tracePath, redactionConfigPath } = resolveTraceSettings(monitor.name);
+    // Resolve absolute outputSchema path. The pi-workflows compileAgentSpec
+    // preserves the relative path that the agent YAML declared; executeAgent
+    // requires an absolute filesystem path for validateFromFile / phantom-tool
+    // construction. AGENTS_DIR is the canonical fallback resolution base.
+    let resolvedOutputSchema;
+    if (compiled.outputSchema) {
+        resolvedOutputSchema = path.isAbsolute(compiled.outputSchema)
+            ? compiled.outputSchema
+            : path.resolve(AGENTS_DIR, compiled.outputSchema);
+    }
+    // Build a synthetic CompiledAgent from the pi-workflows compileAgentSpec
+    // output. The two AgentSpec shapes are not identical — pi-jit-agents only
+    // reads `name` off `spec` for trace stamping; we stub `loadedFrom` so the
+    // type-check passes. `contextValues` carries the resolved collector output
+    // keyed by collector name so executeAgent can emit one context_collection
+    // entry per resolved key.
+    const synthCompiled = {
+        spec: {
+            name: agentSpec.name,
+            loadedFrom: "<monitor-classify>",
+        },
+        systemPrompt: compiled.systemPrompt,
+        taskPrompt: prompt,
+        model: modelSpec,
+        outputSchema: resolvedOutputSchema,
+        contextValues: { ...collected, ...(extraContext ?? {}) },
+    };
+    const dispatch = {
+        model: model,
+        // JitAgentAuth requires non-optional apiKey/headers; the
+        // ResolvedRequestAuth ok-branch leaves both optional. Default empty
+        // values match the legacy behavior where pi-ai's `complete` accepted
+        // undefined values transparently.
+        auth: { apiKey: auth.apiKey ?? "", headers: auth.headers ?? {} },
+        maxTokens: 1024,
+        signal,
+        tracePath,
+        redactionConfigPath,
+        monitorName: monitor.name,
+    };
     // Thinking is disabled for classify calls — Anthropic API rejects
     // thinking + forced toolChoice. The phantom tool enforces output shape;
     // thinking support requires Structured Outputs (output_config.format)
-    // which pi-ai does not yet expose.
-    const response = await complete(model, {
-        messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
-        tools: [VERDICT_TOOL],
-    }, {
-        apiKey: auth.apiKey,
-        headers: auth.headers,
-        maxTokens: 1024,
-        signal,
-        toolChoice: { type: "tool", name: "classify_verdict" },
-    });
-    const toolCall = response.content.find((c) => c.type === "toolCall");
-    if (!toolCall) {
-        const contentTypes = response.content.map((c) => c.type).join(", ");
-        const errMsg = response.errorMessage ? ` error: ${response.errorMessage}` : "";
+    // which pi-ai does not yet expose. executeAgent enforces the same
+    // constraint internally.
+    let result;
+    try {
+        result = await executeAgent(synthCompiled, dispatch);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
         return {
             verdict: "error",
-            error: `No tool call in response (stopReason: ${response.stopReason}, content: [${contentTypes}]${errMsg})`,
+            error: errMsg,
         };
     }
-    const parsed = toolCall.arguments;
-    // Validate against verdict schema if the agent spec declares one
-    if (compiled.outputSchema) {
-        const schemaPath = path.isAbsolute(compiled.outputSchema)
-            ? compiled.outputSchema
-            : path.resolve(AGENTS_DIR, compiled.outputSchema);
-        validateFromFile(schemaPath, parsed, `verdict for monitor '${monitor.name}'`);
+    // executeAgent returns the validated tool-call arguments as `output` when
+    // outputSchema is set (verdict schema). Otherwise `output` is the extracted
+    // text — fall back to parseVerdict for unstructured responses to preserve
+    // the legacy free-text classify path used by some agent specs.
+    if (resolvedOutputSchema && result.output && typeof result.output === "object") {
+        const parsed = result.output;
+        // Re-validate at the call site for parity with the prior implementation
+        // (executeAgent already validated; the duplicate call is a no-op on the
+        // happy path and preserves the existing error-surfacing label).
+        validateFromFile(resolvedOutputSchema, parsed, `verdict for monitor '${monitor.name}'`);
+        return mapVerdictToClassifyResult(parsed);
+    }
+    if (!resolvedOutputSchema && typeof result.output === "string") {
+        return parseVerdict(result.output);
     }
-    return mapVerdictToClassifyResult(parsed);
+    return {
+        verdict: "error",
+        error: `Unexpected executeAgent output shape (type=${typeof result.output})`,
+    };
 }
 // =============================================================================
 // Pattern learning (JSON)
 // =============================================================================
-function learnPattern(monitor, description, severity = "warning") {
-    const patterns = loadPatterns(monitor);
+// Exported (over the package barrel) so the side-car-routing test suite can
+// drive it directly without reaching through the dispatch path; behavior is
+// otherwise identical to when this was a module-private helper.
+export function learnPattern(monitor, description, severity = "warning") {
     const id = description
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .slice(0, 60);
     // dedup by ID — two different descriptions can slugify to the same ID,
     // so check ID rather than raw description to avoid collisions
-    if (patterns.some((p) => p.id === id))
+    const existing = loadPatterns(monitor);
+    if (existing.some((p) => p.id === id))
         return;
-    patterns.push({
+    const newPattern = {
         id,
         description,
         severity,
         source: "learned",
         learned_at: new Date().toISOString(),
-    });
-    const tmpPath = `${monitor.resolvedPatternsPath}.${process.pid}.tmp`;
+    };
+    // Routes through `appendToTypedFile` (arrayPath = null = top-level array
+    // shape) so AJV validates the appended item + the whole array against
+    // `monitor-pattern-list.schema.json`, the read-modify-write critical
+    // section is wrapped in proper-lockfile, and the same atomic tmp+rename
+    // applies as for `.project/<block>.json` writes — FGAP-019 closure.
+    // `appendToTypedFile` requires the file to already exist, so bootstrap
+    // an empty list here when the patterns file is absent (matching the
+    // prior "loadPatterns returns [] on read failure" behavior).
     try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(patterns, null, 2)}\n`);
-        fs.renameSync(tmpPath, monitor.resolvedPatternsPath);
+        if (!fs.existsSync(monitor.resolvedPatternsPath)) {
+            writeTypedFile(monitor.resolvedPatternsPath, PATTERN_LIST_SCHEMA_PATH, [], undefined, `monitor '${monitor.name}' patterns`);
+        }
+        appendToTypedFile(monitor.resolvedPatternsPath, PATTERN_LIST_SCHEMA_PATH, null, newPattern, undefined, `monitor '${monitor.name}' pattern`);
     }
     catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* cleanup */
-        }
         console.error(`[${monitor.name}] Failed to write pattern: ${err instanceof Error ? err.message : err}`);
     }
 }
@@ -1086,12 +1261,43 @@ function learnPattern(monitor, description, severity = "warning") {
 export function generateFindingId(monitorName, _description) {
     return `${monitorName}-${Date.now().toString(36)}`;
 }
-function executeWriteAction(monitor, action, result) {
+/**
+ * Apply a monitor's write-action by routing through `@davidorex/pi-context/block-api`.
+ *
+ * Closes issue-065: the prior body wrote findings via `fs.writeFileSync`
+ * after manual JSON read+merge+write, bypassing AJV schema validation,
+ * proper-lockfile contention guards, DispatchContext author stamping, and
+ * any centralized "monitor wrote here" choke point. This refactor routes
+ * every monitor write through `appendToBlock` / `upsertItemInBlock` with
+ * a `DispatchContext.writer` of `{ kind: "monitor", monitor_name }` so:
+ *
+ *   1. AJV validates the entry against `.project/schemas/<block>.schema.json`
+ *      before write — drift surfaces immediately, not on later reader load.
+ *   2. proper-lockfile guards concurrent monitor + LLM writes against the
+ *      same block file.
+ *   3. created_by / created_at / modified_by / modified_at fields, when
+ *      declared on the destination schema, are stamped with the monitor's
+ *      writer string ("monitor/<name>") so monitor-authored entries are
+ *      distinguishable from human / agent / workflow entries downstream.
+ *   4. All monitor writes funnel through one execute boundary — the future
+ *      "detect monitor bypass" check has a single call site to inspect.
+ *
+ * Failure model: AJV ValidationError or any block-api error is logged via
+ * console.error with the monitor name and propagated NO FURTHER. This
+ * mirrors the previous fs-write failure handling — a monitor that cannot
+ * persist a finding does not crash the host turn; the operator sees the
+ * stderr line and can investigate. Re-raising would change the host
+ * extension's failure model and is out of scope for this refactor.
+ *
+ * Exported for unit-test access (Phase F of issue-065 closure plan).
+ */
+export function executeWriteAction(monitor, action, result) {
     if (!action.write)
         return;
     const writeCfg = action.write;
-    const filePath = path.isAbsolute(writeCfg.path) ? writeCfg.path : path.resolve(process.cwd(), writeCfg.path);
-    // Build the entry from template, substituting placeholders
+    // Build the entry from template, substituting placeholders.
+    // Template substitution semantics preserved verbatim from the prior body —
+    // the change is the persistence path, not the entry shape.
     const findingId = generateFindingId(monitor.name, result.description ?? "unknown");
     const entry = {};
     for (const [key, tmpl] of Object.entries(writeCfg.template)) {
@@ -1102,45 +1308,25 @@ function executeWriteAction(monitor, action, result) {
             .replace(/\{monitor_name\}/g, monitor.name)
             .replace(/\{timestamp\}/g, new Date().toISOString());
     }
-    // Read existing file or create structure
-    let data = {};
+    // DispatchContext writer identifying the monitor — block-api stamps
+    // created_by / modified_by with `writerToString({ kind: "monitor", monitor_name })`
+    // → "monitor/<name>" when the destination schema declares those fields.
+    const ctx = {
+        writer: { kind: "monitor", monitor_name: monitor.name },
+    };
     try {
-        data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    }
-    catch {
-        // file doesn't exist or is invalid — create fresh
-    }
-    const arrayField = writeCfg.array_field;
-    if (!Array.isArray(data[arrayField])) {
-        data[arrayField] = [];
-    }
-    const arr = data[arrayField];
-    if (writeCfg.merge === "upsert") {
-        const idx = arr.findIndex((item) => item.id === entry.id);
-        if (idx !== -1) {
-            arr[idx] = entry;
+        if (writeCfg.merge === "upsert") {
+            upsertItemInBlock(process.cwd(), writeCfg.block, writeCfg.array_field, entry, "id", ctx);
         }
         else {
-            arr.push(entry);
+            appendToBlock(process.cwd(), writeCfg.block, writeCfg.array_field, entry, ctx);
         }
     }
-    else {
-        arr.push(entry);
-    }
-    const tmpPath = `${filePath}.${process.pid}.tmp`;
-    try {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`);
-        fs.renameSync(tmpPath, filePath);
-    }
     catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* cleanup */
-        }
-        console.error(`[${monitor.name}] Failed to write to ${filePath}: ${err instanceof Error ? err.message : err}`);
+        // Mirror the previous failure model: log + continue. Includes AJV
+        // ValidationError (schema mismatch), missing block file, missing
+        // arrayKey, lock-contention timeout — all surface here as Error.
+        console.error(`[${monitor.name}] block-api write failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 // =============================================================================
@@ -1357,8 +1543,32 @@ async function escalate(monitor, _pi, ctx) {
 // Extension entry point
 // =============================================================================
 export default function (pi) {
-    const seeded = seedExamples();
-    const monitors = discoverMonitors();
+    // Cache pi for classify-time CLI flag lookup. classifyViaAgent reads
+    // --trace / --no-trace / --trace-dir / --trace-filter via getCliFlag()
+    // to resolve the trace destination passed through DispatchContext.
+    getCliFlag = (name) => pi.getFlag(name);
+    // CLI flag registration for the agent-trace pipeline (issue-023 T6).
+    // pi-coding-agent's convention is `--no-<name>` for boolean disable, plain
+    // `--<name>` for boolean enable, and `--<name> <value>` for value flags.
+    pi.registerFlag("trace", {
+        type: "boolean",
+        default: false,
+        description: "Enable agent-trace JSONL emission for monitor classify calls (default location: .workflows/monitors/<name>/<YYYY-MM-DD>.jsonl).",
+    });
+    pi.registerFlag("no-trace", {
+        type: "boolean",
+        default: false,
+        description: "Disable agent-trace JSONL emission for monitor classify calls.",
+    });
+    pi.registerFlag("trace-dir", {
+        type: "string",
+        description: "Override the base directory for agent-trace JSONL files. Date-rotated filename appended.",
+    });
+    pi.registerFlag("trace-filter", {
+        type: "string",
+        description: "Path to a trace-config.json with custom redaction patterns layered atop the builtin set.",
+    });
+    const { monitors, overrides } = discoverMonitors();
     loadedMonitors = monitors;
     if (monitors.length === 0)
         return;
@@ -1391,9 +1601,14 @@ export default function (pi) {
         try {
             statusCtx = ctx;
             invokeCtx = ctx;
-            if (seeded > 0 && ctx.hasUI) {
-                const dir = resolveProjectMonitorsDir();
-                ctx.ui.notify(`Seeded ${seeded} example monitor files into ${dir}\nEdit or delete them to customize.`, "info");
+            // Surface drift between project/user overrides and bundled defaults.
+            // One notification per shadowed lower-tier monitor; users decide
+            // whether to delete the override (and pick up bundled updates) or
+            // keep it (preserving local customisations).
+            if (ctx.hasUI && overrides.length > 0) {
+                for (const o of overrides) {
+                    ctx.ui.notify(`[monitors] override active for '${o.name}' — using ${o.winnerDir}/${o.name}.monitor.json; bundled version at ${o.losingDir} may be newer (delete the override to receive updates)`, "warning");
+                }
             }
             // Reset per-monitor state for the new session. This covers both
             // fresh sessions and what was previously handled by session_switch