dsh-decision-layer 0.4.0 → 0.5.0

package/service/config-store.mjs

@@ -55,7 +55,7 @@ function validRules(value) {
 
 function validCheck(value) {
   if (!safeObject(value)) return undefined;
-  if (Object.keys(value).some(key => !['mode', 'rubric', 'lowScoreThreshold'].includes(key))) throw new Error('Invalid self-check settings');
+  if (Object.keys(value).some(key => !['mode', 'rubric', 'lowScoreThreshold', 'trendMinConfidence', 'trendRun', 'trendSevereRun'].includes(key))) throw new Error('Invalid self-check settings');
   const check = {};
   if (value.mode !== undefined) {
     if (value.mode !== 'observe' && value.mode !== 'steer') throw new Error('Invalid self-check settings');
@@ -71,6 +71,27 @@ function validCheck(value) {
     if (!Number.isSafeInteger(value.lowScoreThreshold) || value.lowScoreThreshold < 0 || value.lowScoreThreshold > 9) throw new Error('Invalid self-check settings');
     check.lowScoreThreshold = value.lowScoreThreshold;
   }
+  // Quality-trend alarm thresholds (all unvalidated heuristics, tuned on real logs):
+  // a high-confidence low score requires confidence ≥ trendMinConfidence; a run of
+  // trendRun such scores raises "warn", trendSevereRun raises "severe".
+  if (value.trendMinConfidence !== undefined) {
+    if (typeof value.trendMinConfidence !== 'number' || !Number.isFinite(value.trendMinConfidence) || value.trendMinConfidence < 0 || value.trendMinConfidence > 1) throw new Error('Invalid self-check settings');
+    check.trendMinConfidence = value.trendMinConfidence;
+  }
+  if (value.trendRun !== undefined) {
+    if (!Number.isSafeInteger(value.trendRun) || value.trendRun < 2 || value.trendRun > 10) throw new Error('Invalid self-check settings');
+    check.trendRun = value.trendRun;
+  }
+  if (value.trendSevereRun !== undefined) {
+    if (!Number.isSafeInteger(value.trendSevereRun) || value.trendSevereRun < 2 || value.trendSevereRun > 20) throw new Error('Invalid self-check settings');
+    check.trendSevereRun = value.trendSevereRun;
+  }
+  // The severe threshold must sit strictly above the warn threshold; check against
+  // the effective warn value (explicit or default 3) so the pair is always ordered.
+  if (check.trendSevereRun !== undefined) {
+    const warn = check.trendRun ?? 3;
+    if (check.trendSevereRun <= warn) throw new Error('Invalid self-check settings');
+  }
   return check;
 }
 
@@ -106,9 +127,27 @@ function validNarrow(value) {
   return narrow;
 }
 
-// Per-feature enable flags for the three decision points. Every flag defaults to
+// Per-feature enable flags for the decision points. Every flag defaults to
 // enabled; only an explicit `false` disables its decision point.
-export const FEATURE_KEYS = Object.freeze(['gate', 'check', 'narrow']);
+export const FEATURE_KEYS = Object.freeze(['gate', 'check', 'narrow', 'complete']);
+
+// Task-completion checking settings: observe-only by default; steer opts into a
+// single supplemental prompt on low completion. minConditions is the minimum
+// number of explicit conditions a turn must have for the check to run at all.
+function validComplete(value) {
+  if (!safeObject(value)) return undefined;
+  if (Object.keys(value).some(key => !['mode', 'minConditions'].includes(key))) throw new Error('Invalid task-completion settings');
+  const complete = {};
+  if (value.mode !== undefined) {
+    if (value.mode !== 'observe' && value.mode !== 'steer') throw new Error('Invalid task-completion settings');
+    complete.mode = value.mode;
+  }
+  if (value.minConditions !== undefined) {
+    if (!Number.isSafeInteger(value.minConditions) || value.minConditions < 2 || value.minConditions > 20) throw new Error('Invalid task-completion settings');
+    complete.minConditions = value.minConditions;
+  }
+  return complete;
+}
 
 function validFeatures(value) {
   if (!safeObject(value)) return undefined;
@@ -138,6 +177,7 @@ function view(stored) {
   if (stored.dangerRules !== undefined) result.dangerRules = validRules(stored.dangerRules);
   if (stored.checkSettings !== undefined) result.checkSettings = validCheck(stored.checkSettings);
   if (stored.narrowSettings !== undefined) result.narrowSettings = validNarrow(stored.narrowSettings);
+  if (stored.completeSettings !== undefined) result.completeSettings = validComplete(stored.completeSettings);
   if (stored.features !== undefined) result.features = validFeatures(stored.features);
   return result;
 }
@@ -158,12 +198,13 @@ export async function resolveConfig({ path = configPath(), env = process.env } =
   if (stored.dangerRules !== undefined) resolved.dangerRules = validRules(stored.dangerRules);
   if (stored.checkSettings !== undefined) resolved.checkSettings = validCheck(stored.checkSettings);
   if (stored.narrowSettings !== undefined) resolved.narrowSettings = validNarrow(stored.narrowSettings);
+  if (stored.completeSettings !== undefined) resolved.completeSettings = validComplete(stored.completeSettings);
   if (stored.features !== undefined) resolved.features = validFeatures(stored.features);
   return resolved;
 }
 
 export async function saveConfig(input, path = configPath()) {
-  if (!safeObject(input) || Object.keys(input).some(key => !['url', 'apiKey', 'model', 'confirmHttpUrl', 'dangerRules', 'checkSettings', 'narrowSettings', 'features'].includes(key))) {
+  if (!safeObject(input) || Object.keys(input).some(key => !['url', 'apiKey', 'model', 'confirmHttpUrl', 'dangerRules', 'checkSettings', 'narrowSettings', 'completeSettings', 'features'].includes(key))) {
     throw new Error('Invalid configuration fields');
   }
   for (const key of ['url', 'apiKey', 'model', 'confirmHttpUrl']) {
@@ -179,6 +220,7 @@ export async function saveConfig(input, path = configPath()) {
   const dangerRules = input.dangerRules === undefined ? previous.dangerRules : validRules(input.dangerRules);
   const checkSettings = input.checkSettings === undefined ? previous.checkSettings : validCheck(input.checkSettings);
   const narrowSettings = input.narrowSettings === undefined ? previous.narrowSettings : validNarrow(input.narrowSettings);
+  const completeSettings = input.completeSettings === undefined ? previous.completeSettings : validComplete(input.completeSettings);
   const features = input.features === undefined ? previous.features : validFeatures(input.features);
   const confirmed = url.startsWith('http://') && input.confirmHttpUrl !== undefined &&
     checkedUrl(safeText(input.confirmHttpUrl)) === url;
@@ -189,6 +231,7 @@ export async function saveConfig(input, path = configPath()) {
   if (dangerRules !== undefined) next.dangerRules = dangerRules;
   if (checkSettings !== undefined) next.checkSettings = checkSettings;
   if (narrowSettings !== undefined) next.narrowSettings = narrowSettings;
+  if (completeSettings !== undefined) next.completeSettings = completeSettings;
   if (features !== undefined) next.features = features;
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${randomUUID()}.tmp`;

package/service/danger-gate.mjs

@@ -92,10 +92,19 @@ export function createDangerGate({ evaluate, sessions, rules = DEFAULT_DANGEROUS
     try { sessions.log(id, { kind: 'gate', outcome, tool: exec?.name, ...detail }); }
     catch { /* logging is best effort */ }
   };
-  const fallback = (exec, reason = 'unavailable', detail = {}) => {
-    record(exec, 'error', { action: 'ask', reason, ...detail });
+  // Two-tier model: the gate intervenes ONLY on a high-confidence `deny`
+  // (returned as kind:'deny', enforced monotonically through tools.guard,
+  // independent of the host approval policy). Every other outcome — a low-
+  // confidence verdict, a high-confidence allow/ask, an invalid response, or a
+  // backend failure — is NOT an intervention: the call proceeds on its original
+  // path (next()). The gate no longer emits `ask`, so it never routes through
+  // host approval and can no longer be mis-rendered as "the user rejected".
+  // `passThrough` records the non-intervention for observability and returns
+  // undefined so preExecute falls through to next().
+  const passThrough = (exec, outcome, detail = {}) => {
+    record(exec, outcome, { action: 'pass', ...detail });
     if (exec && typeof exec === 'object') evaluatedCalls.add(exec);
-    return { kind: 'ask', reason: 'Dangerous call requires host approval' };
+    return undefined;
   };
   return {
     classify: exec => classifyDangerous(exec, typeof rules === 'function' ? DEFAULT_DANGEROUS_RULES : rules),
@@ -112,18 +121,27 @@ export function createDangerGate({ evaluate, sessions, rules = DEFAULT_DANGEROUS
       evaluatedCalls.delete(exec);
     },
     async evaluate(exec) {
-      if (exec && typeof exec === 'object') evaluatedCalls.add(exec);
       let result;
       try {
         result = await evaluate(suggestionQuestion(exec), { signal: exec.signal });
-      } catch (error) { return fallback(exec, typeof error?.reason === 'string' ? error.reason : 'unreachable'); }
+      } catch (error) {
+        // Backend failure: no verdict, so do not intervene (pass through).
+        return passThrough(exec, 'error', { reason: typeof error?.reason === 'string' ? error.reason : 'unreachable' });
+      }
       const answer = result?.answers?.verdict;
       const choice = answer?.choice;
-      if (!['allow', 'ask', 'deny'].includes(choice)) return fallback(exec, 'invalid-response');
-      if (typeof answer.confidence !== 'number' || answer.confidence < minConfidence) return fallback(exec, 'low-confidence', typeof answer.confidence === 'number' && Number.isFinite(answer.confidence) ? { confidence: answer.confidence } : {});
-      if (choice === 'deny') { record(exec, 'deny', { suggestion: 'deny', action: 'deny' }); if (exec && typeof exec === 'object') deniedCalls.add(exec); return { kind: 'deny', reason: 'Dangerous call rejected by decision policy', modelSuggestion: choice }; }
-      record(exec, choice, { suggestion: choice, action: 'ask' });
-      return { kind: 'ask', reason: 'Dangerous call requires host approval', modelSuggestion: choice };
+      if (!['allow', 'ask', 'deny'].includes(choice)) return passThrough(exec, 'error', { reason: 'invalid-response' });
+      const confident = typeof answer.confidence === 'number' && Number.isFinite(answer.confidence) && answer.confidence >= minConfidence;
+      // Only a high-confidence deny blocks the call.
+      if (choice === 'deny' && confident) {
+        record(exec, 'deny', { suggestion: 'deny', action: 'deny' });
+        if (exec && typeof exec === 'object') deniedCalls.add(exec);
+        return { kind: 'deny', reason: 'Dangerous call rejected by decision policy', modelSuggestion: choice };
+      }
+      // Uncertain (low confidence) or a non-deny verdict → do not intervene.
+      const detail = { suggestion: choice };
+      if (!confident) { detail.reason = 'low-confidence'; if (typeof answer.confidence === 'number' && Number.isFinite(answer.confidence)) detail.confidence = answer.confidence; }
+      return passThrough(exec, 'allow', detail);
     },
     async preExecute(exec, next) {
       const classification = classifyDangerous(exec, await resolveRules());
@@ -131,13 +149,12 @@ export function createDangerGate({ evaluate, sessions, rules = DEFAULT_DANGEROUS
       const id = exec?.agent?.session?.id;
       if (sessions && typeof id === 'string') {
         try {
-          const snapshot = sessions.snapshot(id);
-          // A deliberate user toggle bypasses the gate; involuntary capacity overflow must not fail-open.
-          if (snapshot.enabled === false && !snapshot.capacityExceeded) return next();
-          if (snapshot.capacityExceeded) return fallback(exec, 'capacity');
-        } catch { return fallback(exec, 'unreachable'); }
+          // A deliberate user toggle bypasses the gate entirely (no record).
+          if (sessions.snapshot(id).enabled === false) return next();
+        } catch { passThrough(exec, 'error', { reason: 'unreachable' }); return next(); }
       }
-      return this.evaluate(exec);
+      const decision = await this.evaluate(exec);
+      return decision ?? next();
     },
   };
 }

package/service/dsh.mjs

@@ -7,8 +7,10 @@ import { createSessionState } from './session-state.mjs';
 import { createDangerGate, normalizeDangerRules } from './danger-gate.mjs';
 import { createSelfCheck } from './self-check.mjs';
 import { createNarrowing } from './narrowing.mjs';
+import { createTaskCompletion } from './task-completion.mjs';
 import { createLoopGuard } from './loop-guard.mjs';
 import { createLogStore } from './log-store.mjs';
+import { analyzeSessionLogs } from './log-analyze.mjs';
 
 export const name = 'dsh-decision-layer';
 export const inject = ['tools', 'skills'];
@@ -40,6 +42,47 @@ function stepTaskText(messages) {
   } catch { return ''; }
 }
 
+// The user's request text for this turn, used by task-completion to extract the
+// explicit conditions. Best-effort: an unreachable shape yields '', which skips
+// the check. Takes the trailing run of user messages (the prompt entering the turn).
+function turnUserText(agent) {
+  try {
+    const messages = agent?.session?.deriveMessages?.();
+    if (!Array.isArray(messages)) return '';
+    const texts = [];
+    let collecting = false;
+    // Walk backwards: skip the turn's trailing assistant/tool messages, collect the
+    // contiguous user run that started this turn, then stop at the prior assistant.
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i];
+      if (message?.role === 'user' && Array.isArray(message.content)) {
+        collecting = true;
+        texts.unshift(message.content.filter(block => block?.type === 'text' && typeof block.text === 'string').map(block => block.text).join('\n'));
+      } else if (collecting) break;
+    }
+    return texts.join('\n').slice(0, 8 * 1024);
+  } catch { return ''; }
+}
+
+// Tool evidence for the turn's task-completion check: the tool calls and their
+// ok/error outcome from the derived history. Names only (no arguments), bounded.
+// An unreachable shape yields [], which skips the check.
+function turnToolEvidence(agent) {
+  try {
+    const messages = agent?.session?.deriveMessages?.();
+    if (!Array.isArray(messages)) return [];
+    const evidence = [];
+    for (const message of messages) {
+      if (message?.role !== 'tool' || !Array.isArray(message.content)) continue;
+      const tool = typeof message.name === 'string' ? message.name : (typeof message.toolName === 'string' ? message.toolName : '');
+      if (!tool) continue;
+      evidence.push({ tool: tool.slice(0, 128), outcome: message.isError === true ? 'error' : 'ok' });
+      if (evidence.length >= 40) break;
+    }
+    return evidence;
+  } catch { return []; }
+}
+
 // Enumerate the tool names/descriptions visible to this agent scope, best-effort.
 function agentTools(ctx, agent) {
   try {
@@ -106,6 +149,29 @@ export async function apply(ctx, options = {}) {
     if (typeof ctx.effect === 'function') ctx.effect(installCheck);
     else installCheck();
 
+    const taskCompletion = createTaskCompletion({
+      evaluate: (input, request) => backend.evaluate(input, request),
+      sessions,
+      settings: async () => (await resolveConfig({ path })).completeSettings,
+      steer: (agent, text) => agent.steer(createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: 'user' },
+      })),
+    });
+    // Independent turn-stopping listener, separate from the self-check: it checks
+    // whether the user's explicit conditions have supporting tool evidence.
+    const installCompletion = () => ctx.on('agent/turn-stopping', async payload => {
+      if (!(await featureOn('complete'))) return;
+      return taskCompletion.review({
+        agent: payload.agent, turn: payload.turn, signal: payload.signal,
+        output: lastAssistantText(payload.agent),
+        userText: turnUserText(payload.agent),
+        evidence: turnToolEvidence(payload.agent),
+      });
+    });
+    if (typeof ctx.effect === 'function') ctx.effect(installCompletion);
+    else installCompletion();
+
     const narrowing = createNarrowing({
       evaluate: (input, request) => backend.evaluate(input, request),
       sessions,
@@ -169,7 +235,12 @@ export async function apply(ctx, options = {}) {
 
   ctx.inject(['webServer'], web => {
     logStore = createLogStore({ port: web.webServer.port });
-    const unregister = createManagerRoutes({ path, sessions, backend, bindHost: web.webServer.host }).map(route => web.webServer.register(route));
+    const port = web.webServer.port;
+    const analyze = async sessionId => analyzeSessionLogs(sessionId, {
+      port,
+      trendConfig: (await resolveConfig({ path })).checkSettings,
+    });
+    const unregister = createManagerRoutes({ path, sessions, backend, logStore, analyze, bindHost: web.webServer.host }).map(route => web.webServer.register(route));
     return () => { unregister.forEach(dispose => dispose()); const store = logStore; logStore = undefined; void store?.dispose(); };
   });
 }

package/service/log-analyze.mjs

@@ -0,0 +1,155 @@
+import { createReadableStream } from './log-read.mjs';
+
+// Offline analysis over the persisted decision JSONL logs. Pure aggregation:
+// given a stream of records (decision events + annotation events) for one
+// session, fold annotations onto decisions by id (latest wins) and build a
+// process-metrics profile plus a quality-trend threshold backtest.
+//
+// Reading is separated (log-read.mjs) so this module stays pure and testable
+// without touching the filesystem.
+
+const DECISION_KINDS = new Set(['gate', 'check', 'narrow', 'complete']);
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Reduce one session's records into decisions (with the latest annotation
+// attached) and per-kind aggregates. `records` is any iterable of parsed rows.
+export function foldSession(records) {
+  const decisions = new Map();          // id → decision record
+  const annotations = new Map();        // target id → latest annotation
+  for (const record of records) {
+    if (!isObject(record)) continue;
+    if (record.kind === 'annotation') {
+      const target = typeof record.target === 'string' ? record.target : undefined;
+      if (!target) continue;
+      const prev = annotations.get(target);
+      if (!prev || (Number.isFinite(record.at) && record.at >= (prev.at ?? 0))) {
+        annotations.set(target, { rating: record.rating, at: Number.isFinite(record.at) ? record.at : 0 });
+      }
+      continue;
+    }
+    if (DECISION_KINDS.has(record.kind) && typeof record.id === 'string') {
+      decisions.set(record.id, record);
+    }
+  }
+  return { decisions, annotations };
+}
+
+// A confidence bucket label for the [0,1] range, coarse enough to be useful.
+function confidenceBucket(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+  if (value < 0.4) return 'lt40';
+  if (value < 0.6) return 'lt60';
+  if (value < 0.8) return 'lt80';
+  return 'gte80';
+}
+
+function emptyProfile() {
+  return {
+    gate: { attempts: 0, allow: 0, ask: 0, deny: 0, error: 0 },
+    check: { attempts: 0, ok: 0, low: 0, error: 0, scoreSum: 0, scoreCount: 0, confidence: { lt40: 0, lt60: 0, lt80: 0, gte80: 0 } },
+    narrow: { attempts: 0, applied: 0, error: 0, droppedSum: 0, tooManyCandidates: 0 },
+    complete: { attempts: 0, satisfied: 0, unsatisfied: 0, insufficient: 0, error: 0, steered: 0 },
+  };
+}
+
+// Build the process-metrics profile from the folded decisions. Clean denominators:
+// each `attempts` counts real evaluations of that kind; averages (e.g. mean
+// dropped) are reported as-is, never mislabeled as percentages.
+export function buildProfile(decisions) {
+  const profile = emptyProfile();
+  for (const record of decisions.values()) {
+    const kind = record.kind;
+    const bucket = profile[kind];
+    if (!bucket) continue;
+    bucket.attempts++;
+    if (kind === 'gate') {
+      if (record.outcome === 'error') bucket.error++;
+      else if (['allow', 'ask', 'deny'].includes(record.outcome)) bucket[record.outcome]++;
+    } else if (kind === 'check') {
+      if (record.outcome === 'error') bucket.error++;
+      else if (record.outcome === 'low') bucket.low++;
+      else bucket.ok++;
+      if (typeof record.score === 'number' && Number.isFinite(record.score)) { bucket.scoreSum += record.score; bucket.scoreCount++; }
+      const cb = confidenceBucket(record.confidence);
+      if (cb) bucket.confidence[cb]++;
+    } else if (kind === 'narrow') {
+      if (record.outcome === 'error') bucket.error++;
+      else if (record.outcome === 'applied') bucket.applied++;
+      if (Number.isSafeInteger(record.dropped) && record.dropped > 0) bucket.droppedSum += record.dropped;
+      if (record.reason === 'too-many-candidates') bucket.tooManyCandidates++;
+    } else if (kind === 'complete') {
+      if (record.outcome === 'error') bucket.error++;
+      if (Number.isSafeInteger(record.satisfied)) bucket.satisfied += record.satisfied;
+      if (Number.isSafeInteger(record.unsatisfied)) bucket.unsatisfied += record.unsatisfied;
+      if (Number.isSafeInteger(record.insufficient)) bucket.insufficient += record.insufficient;
+      if (record.steered === true) bucket.steered++;
+    }
+  }
+  return profile;
+}
+
+// Replay the quality-trend thresholds over this session's check records in time
+// order: how many times would the alarm have fired at warn / severe? Uses the
+// same run semantics as quality-trend.mjs (good resets, high-confidence low
+// grows, low-confidence low and non-low are skipped for the run — but a good
+// score still resets). This is a calibration aid, not a live signal.
+export function backtestTrend(checkRecords, { trendMinConfidence = 0.6, trendRun = 3, trendSevereRun = 5, lowScoreThreshold = 1 } = {}) {
+  const ordered = [...checkRecords].filter(r => isObject(r) && r.kind === 'check').sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+  let run = 0, warnHits = 0, severeHits = 0, maxRun = 0;
+  for (const record of ordered) {
+    if (record.outcome === 'error') continue; // unevaluated: skip
+    const isLow = record.outcome === 'low' || (typeof record.score === 'number' && record.score <= lowScoreThreshold);
+    if (!isLow) { run = 0; continue; }
+    const confident = typeof record.confidence === 'number' && Number.isFinite(record.confidence) && record.confidence >= trendMinConfidence;
+    if (!confident) continue; // low-confidence low: skip, run unchanged
+    run++;
+    maxRun = Math.max(maxRun, run);
+    if (run === trendSevereRun) severeHits++;
+    else if (run === trendRun) warnHits++;
+  }
+  return { warnHits, severeHits, maxRun };
+}
+
+// Attach annotation summary: how many decisions carry a good/bad/unsure rating.
+// Also returns a per-decision ratings map (id → rating) so a UI can show the
+// persisted annotation state on each decision, whichever surface renders it.
+export function annotationSummary(decisions, annotations) {
+  const summary = { rated: 0, good: 0, bad: 0, unsure: 0 };
+  const ratings = Object.create(null);
+  for (const [id] of decisions) {
+    const annotation = annotations.get(id);
+    if (!annotation || typeof annotation.rating !== 'string') continue;
+    summary.rated++;
+    if (annotation.rating === 'good') summary.good++;
+    else if (annotation.rating === 'bad') summary.bad++;
+    else if (annotation.rating === 'unsure') summary.unsure++;
+    ratings[id] = annotation.rating;
+  }
+  return { summary, ratings };
+}
+
+// One-call analysis over an iterable of records for a single session.
+export function analyzeSession(records, trendConfig) {
+  const { decisions, annotations } = foldSession(records);
+  const annotation = annotationSummary(decisions, annotations);
+  return {
+    totalDecisions: decisions.size,
+    profile: buildProfile(decisions),
+    trendBacktest: backtestTrend([...decisions.values()], trendConfig),
+    annotations: annotation.summary,
+    ratings: annotation.ratings,
+  };
+}
+
+// Read the persisted logs for one session id and analyze them. Streams files so
+// a large corpus is never fully buffered; only rows whose sessionId matches are
+// kept. `readStream` is injected for tests; production reads the logs dir.
+export async function analyzeSessionLogs(sessionId, { dir, port, trendConfig, readStream = createReadableStream } = {}) {
+  if (typeof sessionId !== 'string' || !sessionId.trim()) throw new Error('Invalid session id');
+  const records = [];
+  for await (const record of readStream({ dir, port })) {
+    if (!isObject(record)) continue;
+    if (record.sessionId === sessionId) records.push(record);
+  }
+  return analyzeSession(records, trendConfig);
+}

package/service/log-read.mjs

@@ -0,0 +1,27 @@
+import { createReadStream } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+import { logsDir } from './log-store.mjs';
+
+// Stream the persisted decision JSONL logs line by line, yielding one parsed
+// record per line. Files are read sequentially so a large corpus is never fully
+// buffered. A malformed line is skipped, not fatal. Only this port's files are
+// read when `port` is given (matching the log-store naming); otherwise all
+// `decisions-*.jsonl` files are read.
+export async function* createReadableStream({ dir = logsDir(), port } = {}) {
+  const prefix = Number.isInteger(port) && port > 0 ? `decisions-${port}-` : 'decisions-';
+  let names;
+  try { names = await readdir(dir); } catch { return; }
+  const files = names.filter(name => name.startsWith(prefix) && name.endsWith('.jsonl')).sort();
+  for (const name of files) {
+    const stream = createReadStream(join(dir, name), { encoding: 'utf8' });
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of lines) {
+        if (!line.trim()) continue;
+        try { yield JSON.parse(line); } catch { /* skip malformed line */ }
+      }
+    } finally { lines.close(); stream.close(); }
+  }
+}

package/service/log-store.mjs

@@ -61,6 +61,18 @@ export function createLogStore({ port, dir = logsDir(), flushIntervalMs = 5000,
       if (buffer.length >= maxBuffer) { void flush(); return; }
       if (!timer) timer = setTimeout(() => { timer = undefined; void flush(); }, flushIntervalMs);
     },
+    // An annotation is an explicit user action, not telemetry: write it
+    // immediately (not batched) and surface failure to the caller instead of
+    // dropping it. It lands in the same JSONL directory as a `kind:"annotation"`
+    // event and is pruned with the decision logs on the next flush.
+    async appendAnnotation(entry) {
+      if (entry === null || typeof entry !== 'object') throw new Error('Invalid annotation');
+      const at = Number.isFinite(entry.at) ? entry.at : now().getTime();
+      const record = { ...entry, at };
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      await appendFile(fileFor(new Date(at)), `${JSON.stringify(record)}\n`, { mode: 0o600 });
+      return record;
+    },
     flush,
     dispose() {
       if (timer) { clearTimeout(timer); timer = undefined; }

package/service/loop-guard.mjs

@@ -28,12 +28,11 @@ export function createLoopGuard({ threshold = 3, maxSessions = 1024, sessions }
     check(exec) {
       const id = exec?.agent?.session?.id;
       if (typeof id !== 'string') return undefined;
-      // The master switch pauses automatic intervention (mirrors the danger gate);
-      // capacity overflow still guards, since that is involuntary, not a user choice.
+      // The master switch pauses automatic intervention (mirrors the danger gate):
+      // a deliberate user toggle skips the loop guard too.
       if (sessions) {
         try {
-          const snapshot = sessions.snapshot(id);
-          if (snapshot.enabled === false && !snapshot.capacityExceeded) return undefined;
+          if (sessions.snapshot(id).enabled === false) return undefined;
         } catch { /* fall through and guard */ }
       }
       const run = runFor(id);

package/service/manager-api.mjs

@@ -37,7 +37,7 @@ async function readBody(req) {
   return value;
 }
 
-export function createManagerRoutes({ path, sessions, backend, env = process.env, bindHost = '127.0.0.1' }) {
+export function createManagerRoutes({ path, sessions, backend, logStore, analyze, env = process.env, bindHost = '127.0.0.1' }) {
   const route = (suffix, methods) => ({ kind: 'exact', path: `${API_PREFIX}/${suffix}`, handler: async (req, res) => {
     if (bindHost !== '127.0.0.1' || !authorizedBrowser(req)) return respond(res, 403, { ok: false, error: 'Local same-origin browser request required' });
     if (!Object.hasOwn(methods, req.method)) return respond(res, 405, { ok: false, error: 'Method not allowed' });
@@ -75,6 +75,31 @@ export function createManagerRoutes({ path, sessions, backend, env = process.env
     }),
     route('metrics', { GET: req => sessions.snapshot(sessionId(req)) }),
     route('log', { GET: req => ({ entries: sessions.snapshot(sessionId(req)).log ?? [] }) }),
+    // Read-only analysis over the persisted decision logs for one session. Returns
+    // only aggregates and annotation counts — never raw log rows — so gate command
+    // / path fragments are not echoed back to the browser.
+    route('logs', {
+      GET: async req => {
+        if (typeof analyze !== 'function') { const error = new Error('analysis unavailable'); error.code = 'BAD_REQUEST'; throw error; }
+        return analyze(sessionId(req));
+      },
+    }),
+    // Append one annotation event for a decision. Explicit user intent: validated
+    // and written immediately; a write failure surfaces as an error, not silence.
+    route('annotate', {
+      POST: async req => {
+        if (!logStore || typeof logStore.appendAnnotation !== 'function') { const error = new Error('annotation unavailable'); error.code = 'BAD_REQUEST'; throw error; }
+        const body = await readBody(req);
+        const target = typeof body.target === 'string' ? body.target.trim() : '';
+        const rating = body.rating;
+        const session = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+        if (!target || target.length > 128 || !['good', 'bad', 'unsure'].includes(rating) || !session || session.length > 512) {
+          const error = new Error('Invalid annotation'); error.code = 'BAD_REQUEST'; throw error;
+        }
+        await logStore.appendAnnotation({ kind: 'annotation', target, rating, sessionId: session });
+        return { ok: true, target, rating };
+      },
+    }),
     route('session', {
       GET: req => sessions.snapshot(sessionId(req)),
       PUT: async req => {

package/service/quality-trend.mjs

@@ -0,0 +1,29 @@
+// Pure helpers for the output-quality trend alarm. A run counts consecutive
+// high-confidence low self-check scores; the run length maps to a severity that
+// the trigger icon renders (normal → warn → severe). All thresholds are
+// unvalidated heuristics, tuned later on real decision logs.
+
+export const DEFAULT_TREND_MIN_CONFIDENCE = 0.6;
+export const DEFAULT_TREND_RUN = 3;
+export const DEFAULT_TREND_SEVERE_RUN = 5;
+
+// Advance the run over ONE evaluated self-check:
+//   - a good score (not low) resets the run to 0;
+//   - a high-confidence low score increments it;
+//   - a low-confidence low score is skipped (neither resets nor increments);
+//   - an unevaluated/absent verdict must not call this at all.
+// `sample` is { lowScore: boolean, confident: boolean }.
+export function advanceRun(run, sample) {
+  const current = Number.isSafeInteger(run) && run >= 0 ? run : 0;
+  if (!sample || sample.lowScore !== true) return 0;
+  if (sample.confident === true) return current + 1;
+  return current;
+}
+
+// Map a run length to a severity, given the warn/severe thresholds.
+export function severityOf(run, { trendRun = DEFAULT_TREND_RUN, trendSevereRun = DEFAULT_TREND_SEVERE_RUN } = {}) {
+  const value = Number.isSafeInteger(run) && run >= 0 ? run : 0;
+  if (value >= trendSevereRun) return 'severe';
+  if (value >= trendRun) return 'warn';
+  return 'normal';
+}

package/service/self-check.mjs

@@ -40,12 +40,16 @@ export function createSelfCheck({ evaluate, sessions, steer, settings, minConfid
     try { raw = (typeof settings === 'function' ? await settings() : settings) ?? {}; } catch { raw = {}; }
     const mode = raw?.mode === 'steer' ? 'steer' : 'observe';
     const lowScoreThreshold = Number.isSafeInteger(raw?.lowScoreThreshold) && raw.lowScoreThreshold >= 0 ? raw.lowScoreThreshold : 1;
-    return { mode, rubric: boundedRubric(raw?.rubric), lowScoreThreshold };
+    // Quality-trend thresholds (unvalidated heuristics; see quality-trend.mjs).
+    const trendMinConfidence = typeof raw?.trendMinConfidence === 'number' && Number.isFinite(raw.trendMinConfidence) && raw.trendMinConfidence >= 0 && raw.trendMinConfidence <= 1 ? raw.trendMinConfidence : 0.6;
+    const trendRun = Number.isSafeInteger(raw?.trendRun) && raw.trendRun >= 2 ? raw.trendRun : 3;
+    const trendSevereRun = Number.isSafeInteger(raw?.trendSevereRun) && raw.trendSevereRun > trendRun ? raw.trendSevereRun : Math.max(trendRun + 1, 5);
+    return { mode, rubric: boundedRubric(raw?.rubric), lowScoreThreshold, trendMinConfidence, trendRun, trendSevereRun };
   };
-  const record = (turn, outcome, detail = {}) => {
+  const record = (turn, outcome, detail = {}, trend) => {
     const id = turn?.agent?.session?.id;
     if (!sessions || typeof id !== 'string' || typeof sessions.recordCheck !== 'function') return;
-    try { sessions.recordCheck(id, outcome); } catch { /* telemetry is best effort */ }
+    try { sessions.recordCheck(id, outcome, trend); } catch { /* telemetry is best effort */ }
     if (typeof sessions.log !== 'function') return;
     try { sessions.log(id, { kind: 'check', outcome, ...detail }); }
     catch { /* logging is best effort */ }
@@ -59,7 +63,7 @@ export function createSelfCheck({ evaluate, sessions, steer, settings, minConfid
         try { if (sessions.snapshot(id).enabled === false) return { evaluated: false, lowScore: false, steered: false }; }
         catch { return { evaluated: false, lowScore: false, steered: false }; }
       }
-      const { mode, rubric, lowScoreThreshold } = await resolveSettings();
+      const { mode, rubric, lowScoreThreshold, trendMinConfidence, trendRun, trendSevereRun } = await resolveSettings();
       let answer;
       try {
         const result = await evaluate(scoreQuestion(output, rubric), { signal: turn.signal });
@@ -75,7 +79,10 @@ export function createSelfCheck({ evaluate, sessions, steer, settings, minConfid
       const confidence = typeof answer.confidence === 'number' && Number.isFinite(answer.confidence) ? answer.confidence : undefined;
       const detail = confidence === undefined ? {} : { confidence };
       const lowScore = answer.score <= lowScoreThreshold;
-      record(turn, lowScore ? 'low' : 'ok', { score: answer.score, ...detail });
+      // The trend run advances over every evaluated score; a high-confidence low
+      // score is the only thing that grows it. Thresholds flow to session-state.
+      const trend = { confident: lowScore && confidence !== undefined && confidence >= trendMinConfidence, trendRun, trendSevereRun };
+      record(turn, lowScore ? 'low' : 'ok', { score: answer.score, ...detail }, trend);
       if (!lowScore) return { evaluated: true, lowScore: false, steered: false, score: answer.score };
       const confident = confidence !== undefined && confidence >= minConfidence;
       if (mode === 'steer' && confident && typeof steer === 'function' && turn?.agent) {